Skip to content

fix(core): prepend call operator for quoted commands in PowerShell (#1551) - #1552

Open
Aryan9891 wants to merge 1 commit into
google:mainfrom
Aryan9891:fix/powershell-quoted-command-1551
Open

Aryan9891 wants to merge 1 commit into
google:mainfrom
Aryan9891:fix/powershell-quoted-command-1551

Conversation

@Aryan9891

Copy link
Copy Markdown

Fixes #1551

Summary

In PowerShell, passing a quoted command or executable path (e.g. "C:\Program Files\nodejs\node.exe" --version) at the start of a command statement causes PowerShell to evaluate the first token as a string literal expression rather than invoking it as a command, throwing Unexpected token '--version' in expression or statement.

In PowerShell syntax (PowerShell Language Specification §7.1.1), invoking an executable whose path is quoted or contained in a variable requires the call operator & (e.g. & "C:\Program Files\nodejs\node.exe" --version).

This PR updates ProcessPromise.fullCmd to automatically prepend the PowerShell call operator & when:

  1. The active shell or quote function is PowerShell / pwsh ($.quote === quotePowerShell or shell binary matches /(?:powershell|pwsh)(?:\.exe)?$/i),
  2. $.prefix does not already specify a call operator (!prefix.trim().startsWith('&')), and
  3. The command starts with a single or double quote (/^['"]/.test(c.trimStart())).

Usage Demo

import process from 'node:process'
import { $, usePowerShell } from 'zx'

usePowerShell()

// C:\Program Files\nodejs\node.exe (contains spaces, gets quoted by quotePowerShell)
// Now correctly invokes through PowerShell via '& "C:\Program Files\nodejs\node.exe" --version'
const p = await $`${process.execPath} --version`
console.log(p.stdout) // v26.x.x

Checklist

  • Setup: Latest Node.js LTS tested.
  • Build: Verified src/core.ts and build/core.cjs.
  • Tests: Added regression unit tests to test/smoke/win32.test.js.
  • Docs: Retains existing documented API contracts.
  • Sign: Commits cryptographically signed with Ed25519 key and conventional commits spec.
  • CoC: Follows project coding guidelines and Code of Conduct.
  • Review: Original, tested engineering contribution.

Aryan9891 added a commit to Aryan9891/Aryan9891 that referenced this pull request Nov 13, 2026
…gle/zx#1552

Signed-off-by: Aryan Sachin <aryansachinixd@gmail.com>

@1AbdullahButt 1AbdullahButt 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.

This fixes quoted executable paths, but it also changes commands that start with a quoted value instead of a program, which work today. PowerShell then reports success for them.

The issue: a leading quoted string isn't always a command. The new check in fullCmd (src/core.ts:520-531) adds & whenever the command starts with ' or ". In PowerShell, a quoted string at the start of a statement is a value, and that's a common pattern with interpolation, e.g. $`${text} | Set-Content out.txt` or $`${json} | ConvertFrom-Json`. quotePowerShell quotes any value with a space or backslash, so these start with '...' today. I ran both forms in Windows PowerShell 5.1:

  • 'some text' | Write-Output prints some text
  • & 'some text' | Write-Output gives The term 'some text' is not recognized as the name of a cmdlet...

The exit code is worse. A CommandNotFoundException doesn't set $LastExitCode, so with zx's postfix ; exit $LastExitCode the process still exits 0 (I got exit=0 for the second form). The command fails, but zx reports success.

Suggested fix: syntax alone can't settle this. I tried requiring an argument after the quoted token (/^\s*('(?:[^']|'')*'|"[^"]*")\s+(?![\s|;>)&]|$)/). That leaves 'text' | … and a bare 'text' alone, but still matches 'a b' -replace 'a','b', because a PowerShell operator looks like a flag. Keying on the value works better: add & only when the leading token, unquoted, is an existing file or ends in .exe/.cmd/.bat/.ps1. Or leave it to the caller ($& ${path} -v) and document that. Either way, a test with `$`${'a b'} | Write-Output next to the new path test would pin the pipeline case.

What I checked that is fine:

  • The bug is real for any Windows path. quotePowerShell only leaves [\w/.\-@:=,+%] unquoted, so a backslash alone forces quoting. 'C:\Program Files\PowerShell\x.exe' --version fails with Unexpected token 'version' in my PowerShell, as in #1551.
  • The shell regex matches what which returns. usePwsh() gives a path like ...\pwsh.EXE, and the i flag covers it. usePowerShell()/usePwsh() set $.prefix = '', so the !prefix.trim().startsWith('&') check doesn't get in the way by default.

How I tested: the PowerShell commands ran directly in Windows PowerShell 5.1. The zx side is from reading the branch. I didn't run zx's tests.

Reviewed with help from Claude Code.

…oogle#1551)

In PowerShell, passing a quoted command or executable path at the start
of a statement causes PowerShell to evaluate the first token as a string
literal expression rather than invoking it as a command, throwing
'Unexpected token in expression or statement'.

However, a leading quoted string can also be an interpolated value piped
to another command (e.g. $${text} | Set-Content ...) or used with an
operator (e.g. $${text} -replace 'a','b'). In those value cases,
prepending the call operator '&' would cause CommandNotFoundException.

Update fullCmd to inspect the leading quoted token and only prepend the
call operator '&' when the token represents an executable or script
(ends in .exe/.cmd/.bat/.ps1/.com or exists on disk as a file),
preserving normal pipeline and operator expressions.

Closes google#1551

Signed-off-by: Aryan Sachin <aryansachinixd@gmail.com>
@Aryan9891
Aryan9891 force-pushed the fix/powershell-quoted-command-1551 branch from 81d6728 to 0b3229d Compare November 15, 2026 04:16
@Aryan9891

Copy link
Copy Markdown
Author

@1AbdullahButt Thank you for the detailed and insightful review!

You are completely right: prepending & purely based on leading quote syntax inadvertently changed statements starting with an interpolated string value in pipelines (e.g. $'some text' | Write-Output) or expressions with operators ('a b' -replace 'a','b'), which then triggered a CommandNotFoundException that masked the failure due to $LastExitCode not being set.

Updates in commit 0b3229d

  1. Target Inspection via isPowerShellExecutable:

    • Instead of checking syntax alone, fullCmd now extracts the leading quoted token (unquoting single-quote '' escapes and double quotes) and checks if it actually targets an executable or script.
    • The call operator & is only prepended when the leading token:
      • Ends in an executable/script extension: /\.(?:exe|cmd|bat|ps1|com)$/i, or
      • Resolves to an existing file on disk (checking executable file extensions or POSIX executable mode bits).
    • Any leading quoted value that is not an executable (e.g. 'a b' | Write-Output or 'a b' -replace ...) is preserved without & .
  2. Added Regression Tests in test/smoke/win32.test.js:

    • Pinned the pipeline case: $`${'a b'} | Write-Output` verifies output a b and confirms fullCmd does not start with & .
    • Pinned the operator case: $`${'a b'} -replace 'a','b'` verifies output b b and confirms fullCmd does not start with & .
    • Verified that process.execPath and quoted executable paths continue to execute seamlessly.
  3. Validation:

    • All 5 PowerShell smoke tests pass (✔ 5 pass, 0 fail).
    • npx size-limit passes cleanly with 0 errors.

Thanks again for catching this edge case!

This branch has not been deployed

No deployments
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.

[Bug]: use of an absolute path to an executable which contains spaces leads to errors using powershell

2 participants