Skip to content

fix(tools): use cross-spawn for Windows commands - #698

Merged
a-oren merged 4 commits into
guacsec:mainfrom
a-oren:fix/tc-7561-cross-spawn
Nov 18, 2026
Merged

a-oren merged 4 commits into
guacsec:mainfrom
a-oren:fix/tc-7561-cross-spawn

Conversation

@a-oren

@a-oren a-oren commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Fix pre-existing Windows command invocation in the shared invokeCommand() helper, used by Python, Maven, Gradle, and other providers.
  • Use cross-spawn 7.0.6, pinned as a runtime dependency, for native executables, PATH/PATHEXT resolution, Windows batch wrappers, and npm .bin shims. Remove the blanket shell: true and path pre-quoting; do not add a handwritten resolver or cmd.exe escaping implementation.
  • Preserve synchronous UTF-8 stdout, existing environment/options handling, the 10 MiB output limit, and thrown failures with spawn error codes/status/stdout/stderr.
  • Keep the existing Linux unit-test workflow unchanged; do not add duplicate Windows unit-test jobs. The separate shared integration workflow already has Linux/Windows/macOS runners.
  • Replace the 13 intercepted boundary cases in the earlier implementation with seven real-process contract tests: five platform-neutral tests and two Windows-only wrapper/shim tests. Assertions inspect process results, not generated caret-escaping strings.

This is independent of PR #696's Python venv-placement change (b6d2f58), which is not included here. It supersedes the handwritten implementation in 0724cb7; neither that implementation nor the premise that configurable TEMP content introduced a new exposure is retained. Maven and Gradle build-tool paths, wrappers, and arguments use the same corrected command boundary.

Verification

  • npm run tests -- test/tools.test.js: 23 passing, 2 pending on Linux; the pending tests require Windows.
  • npm run lint: 0 errors, 15 unchanged baseline warnings.
  • npm run compile: passed.
  • npm ls cross-spawn: runtime and deduplicated transitive copies are 7.0.6.
  • Full-suite comparison against exact main (ce9658d): 1,042 passing / 1 pending / 21 failing before; 1,047 passing / 3 pending / the same 21 failing after. All failing test names and extracted primary/cause errors match; no additional failures were observed. This is not a clean full-suite pass.
  • Supplemental real-process Linux comparisons against the original helper match for UTF-8/Buffer stdout, stdin/file-URL cwd, nonzero exit, missing executable, timeout, signal termination, and the 10 MiB buffer limit.

Native Windows behavior for this fix remains unverified. The two Windows-only wrapper/shim tests are retained for manual execution and skipped on Linux, not counted as passing. The shared integration workflow tests the built CLI with its own scenarios; it does not run these Mocha tests.

The existing shared integration workflow has a Linux/Windows/macOS matrix, including Python, Maven, and Gradle. Recent integration runs were skipped; the caller runs them automatically only after a successful Test workflow, or manually. The latest pre-removal Test workflow for this PR failed; Linux Node 22 reported three discoverMavenModules failures, whose names also occur in the local baseline. An older cross-platform run built ca3a598, not this fix, and is not evidence for this PR.

Current shared scenarios do not explicitly enable Python venv creation, configure special-character temporary paths, or include Maven/Gradle wrapper fixtures. Targeted integration regression coverage remains follow-up work; existing Windows matrix coverage alone does not validate these cases.

The removed Windows unit jobs failed at checkout of unrelated existing OCI fixture filenames containing : before invocation tests ran. The proposed sparse-checkout workaround was never committed or pushed.

The implementation has had local self-review only; independent review is still required.

Implements TC-7561.

Summary by Sourcery

Fix cross-platform command execution by using cross-spawn and add contract coverage for process behavior and Windows command wrappers.

Bug Fixes:

  • Fix synchronous command invocation across platforms, including Windows executables, batch wrappers, and npm shims, while preserving command arguments and failure details.

Enhancements:

  • Replace shell-based command execution and manual path quoting with cross-spawn handling.

Build:

  • Add cross-spawn 7.0.6 as a runtime dependency.

Tests:

  • Add real-process contract tests covering literal arguments, large output, nonzero exits, unavailable tools, timeouts, and Windows wrapper and shim execution.

@sourcery-ai

sourcery-ai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

API

Update the exported helper’s documented options type to match the synchronous spawn API.

  • src/tools.js L235

Implementation

Replace shell-based invocation and manual Windows quoting with cross-spawn, while preserving output limits and enriching spawn failures without retaining a circular error reference.

  • src/tools.js L258-267 (+4 small edits)

Configuration

Add cross-spawn as a runtime dependency for the shared command helper.

  • package.json L53

Tests

Import the helper and add real-process contract tests for command arguments, output, failures, timeouts, and Windows wrappers and npm shims.

  • test/tools.test.js L1-4, L9, L199-293

Lock files and vendored code

Update the lockfile to record the runtime dependency.

  • package-lock.json L13-3616 (7 small edits)

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 2 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path=".github/workflows/test.yml" line_range="43" />
<code_context>
+      # The full provider suite currently needs Linux-only tools (including skopeo).
+      # Exercise real native, batch, and npm-shim execution here, without mocking Windows.
+      - name: Test command invocation on Windows
+        run: npm run tests -- test/tools.test.js --grep "^invokeCommand"
+
   test:
</code_context>
<issue_to_address>
**Windows validation job fails**

When the Windows workflow runs the focused test command, mocha matches the full test title, which starts with the outer suite title rather than `invokeCommand`; the anchored grep selects zero tests, and `fail-zero: true` makes the job fail instead of validating Windows command execution.

Use a grep pattern that matches the full nested test titles, such as `invokeCommand` without the start anchor.
</issue_to_address>

### Comment 2
<location path="src/tools.js" line_range="261" />
<code_context>
+	const result = spawn.sync(bin, args, {stdio: 'pipe', encoding: 'utf-8', ...opts})
+	// Unlike execFileSync, spawn.sync returns failures instead of throwing them.
+	if (result.error) {
+		throw Object.assign(result.error, result)
+	}
+	if (result.status !== 0) {
</code_context>
<issue_to_address>
**Spawn errors become circular**

When `spawn.sync` returns a non-null `result.error`, such as for a missing executable or timeout, `Object.assign(result.error, result)` copies `result.error` back onto that same object as its `error` property, so the thrown error contains a self-reference and `JSON.stringify` on it throws instead of reporting the command failure.

Copy the result fields onto the thrown error without copying its `error` property.
</issue_to_address>

Sourcery assessment

Approval pending. 2 findings to address first.

Blocking findings: .github/workflows/test.yml:43, src/tools.js:261


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread .github/workflows/test.yml Resolved
Comment thread src/tools.js Resolved
@a-oren
a-oren requested a review from Strum355 November 18, 2026 13:31
Comment thread package.json Resolved
@a-oren
a-oren requested a review from Strum355 November 18, 2026 15:16

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sourcery assessment

Approved.

Replace blanket shell execution and pre-quoting with cross-spawn 7.0.6
for the shared Python, Maven, and Gradle invocation helper. Preserve
synchronous stdout, thrown failures, environment handling, and the
10 MiB output buffer.

Add real-process contract tests and focused Windows Node 22/24 CI.
Keep the Python venv-placement change independent in PR guacsec#696.

Implements TC-7561

Assisted-by: OpenCode (GPT-6.1 Sol)
Signed-off-by: Adva Oren <aoren@redhat.com>
Keep unit CI on Linux; the shared integration workflow already has
Windows and macOS runners. Retain Windows-only contract tests for manual
runs; they remain skipped on Linux, not counted as passing.

The initial Windows jobs failed during checkout of existing OCI fixture
filenames containing colons, before any invocation tests ran. Do not
include the proposed sparse-checkout workaround. Fix-specific native
Windows results remain unverified.

Implements TC-7561

Assisted-by: OpenCode (GPT-6.1 Sol)
Signed-off-by: Adva Oren <aoren@redhat.com>
Exclude the nested error reference when enriching spawn failures so
JSON serialization preserves diagnostic fields without a cycle.
Cover missing executables and timeouts with real-process assertions.

Implements TC-7561

Signed-off-by: Adva Oren <aoren@redhat.com>
Use ^7.0.6 for consumers while retaining the locked 7.0.6 version
for reproducible repository installs. No resolved dependency changes.

Implements TC-7561

Signed-off-by: Adva Oren <aoren@redhat.com>
@a-oren
a-oren force-pushed the fix/tc-7561-cross-spawn branch from e5b18c4 to 597c991 Compare November 18, 2026 16:14
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.64%. Comparing base (626fc21) to head (597c991).

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #698      +/-   ##
==========================================
+ Coverage   91.60%   91.64%   +0.03%     
==========================================
  Files          44       44              
  Lines       11641    11644       +3     
  Branches     2349     2352       +3     
==========================================
+ Hits        10664    10671       +7     
+ Misses        977      973       -4     
Flag Coverage Δ
unit-tests 91.64% <100.00%> (+0.03%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
src/tools.js 93.59% <100.00%> (+1.28%) ⬆️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@a-oren
a-oren merged commit e7aac23 into guacsec:main Nov 18, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants