@zerwiz/ymir 0.1.34 → 0.1.35

package/apps/sessrumnir/src/main/cmd-escape.test.ts

@@ -0,0 +1,424 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import {
+  buildNpmPrefixCommand,
+  escapeCmdArg,
+  escapeCmdSpawn,
+  quoteCmdProgram,
+} from './cmd-escape'
+
+// --- escapeCmdArg: args that need no rewriting stay byte-identical ---
+
+test('escapeCmdArg leaves plain flags unchanged', () => {
+  assert.equal(escapeCmdArg('-p'), '-p')
+  assert.equal(escapeCmdArg('--output-format'), '--output-format')
+  assert.equal(escapeCmdArg('stream-json'), 'stream-json')
+  assert.equal(escapeCmdArg('prefix'), 'prefix')
+  assert.equal(escapeCmdArg('-g'), '-g')
+})
+
+test('escapeCmdArg leaves a bare windows path without spaces unchanged', () => {
+  assert.equal(
+    escapeCmdArg(String.raw`C:\Users\tester\file.txt`),
+    String.raw`C:\Users\tester\file.txt`,
+  )
+})
+
+// --- escapeCmdArg: quoting layer (Microsoft argv backslash rules + "" quotes) ---
+
+test('escapeCmdArg quotes an arg containing spaces', () => {
+  assert.equal(escapeCmdArg('hello world'), '"hello world"')
+})
+
+test('escapeCmdArg quotes an arg containing a tab', () => {
+  assert.equal(escapeCmdArg('a\tb'), '"a\tb"')
+})
+
+test('escapeCmdArg doubles embedded double quotes', () => {
+  assert.equal(escapeCmdArg('say "hi"'), '"say ""hi"""')
+})
+
+test('escapeCmdArg escapes a quote even without surrounding spaces', () => {
+  assert.equal(escapeCmdArg('a"b'), '"a""b"')
+})
+
+test('escapeCmdArg doubles backslashes that precede an embedded quote', () => {
+  assert.equal(escapeCmdArg(String.raw`a\"b`), String.raw`"a\\""b"`)
+})
+
+test('escapeCmdArg doubles trailing backslashes before the closing quote', () => {
+  assert.equal(escapeCmdArg('C:\\my dir\\'), String.raw`"C:\my dir\\"`)
+  assert.equal(escapeCmdArg(String.raw`a b\\`), String.raw`"a b\\\\"`)
+})
+
+test('escapeCmdArg leaves interior backslashes alone', () => {
+  assert.equal(escapeCmdArg(String.raw`C:\my dir\file.txt`), String.raw`"C:\my dir\file.txt"`)
+})
+
+test('escapeCmdArg quotes the empty string', () => {
+  assert.equal(escapeCmdArg(''), '""')
+})
+
+// --- escapeCmdArg: cmd.exe metacharacters are enclosed in real quotes ---
+
+test('escapeCmdArg encloses ampersand command chaining in quotes', () => {
+  assert.equal(escapeCmdArg('a&b'), '"a&b"')
+  assert.equal(escapeCmdArg('a&&calc'), '"a&&calc"')
+})
+
+test('escapeCmdArg encloses pipes in quotes', () => {
+  assert.equal(escapeCmdArg('a|b'), '"a|b"')
+})
+
+test('escapeCmdArg encloses carets in quotes', () => {
+  assert.equal(escapeCmdArg('a^b'), '"a^b"')
+})
+
+test('escapeCmdArg encloses redirects in quotes', () => {
+  assert.equal(escapeCmdArg('a<in>out'), '"a<in>out"')
+})
+
+test('escapeCmdArg encloses parentheses in quotes', () => {
+  assert.equal(escapeCmdArg('(paren)'), '"(paren)"')
+})
+
+// --- escapeCmdArg: % and ! expand even inside quotes, so they are interrupted ---
+
+test('escapeCmdArg interrupts %VAR% outside the quotes with a caret', () => {
+  assert.equal(escapeCmdArg('%PATH%'), '""^%"PATH"^%""')
+  assert.equal(escapeCmdArg('100%'), '"100"^%""')
+})
+
+test('escapeCmdArg interrupts delayed-expansion bangs outside the quotes', () => {
+  assert.equal(escapeCmdArg('!delayed!'), '""^!"delayed"^!""')
+})
+
+test('escapeCmdArg doubles backslashes that precede a percent interrupt', () => {
+  // The interrupt opens with a quote, so a preceding backslash run must be
+  // doubled exactly as it would be before any other emitted quote.
+  assert.equal(escapeCmdArg(String.raw`dir\%PATH%`), String.raw`"dir\\"^%"PATH"^%""`)
+})
+
+test('escapeCmdArg handles a realistic council prompt full of metacharacters', () => {
+  const prompt = 'Fix build & deploy | grep "error" > out.txt (100% done)'
+  assert.equal(
+    escapeCmdArg(prompt),
+    '"Fix build & deploy | grep ""error"" > out.txt (100"^%" done)"',
+  )
+})
+
+// --- escapeCmdArg: characters no escaping can make safe ---
+
+test('escapeCmdArg rejects newlines, carriage returns, and NUL', () => {
+  assert.throws(() => escapeCmdArg('a\nb'), /cannot be passed through cmd\.exe/)
+  assert.throws(() => escapeCmdArg('a\rb'), /cannot be passed through cmd\.exe/)
+  assert.throws(() => escapeCmdArg('a\0b'), /cannot be passed through cmd\.exe/)
+})
+
+// --- quoteCmdProgram ---
+
+test('quoteCmdProgram leaves a bare shim name unchanged', () => {
+  assert.equal(quoteCmdProgram('npm.cmd'), 'npm.cmd')
+})
+
+test('quoteCmdProgram leaves a plain absolute path unchanged', () => {
+  assert.equal(
+    quoteCmdProgram(String.raw`C:\Users\tester\AppData\Roaming\npm\claude.cmd`),
+    String.raw`C:\Users\tester\AppData\Roaming\npm\claude.cmd`,
+  )
+})
+
+test('quoteCmdProgram quotes a path containing spaces', () => {
+  assert.equal(
+    quoteCmdProgram(String.raw`C:\Program Files\nodejs\claude.cmd`),
+    String.raw`"C:\Program Files\nodejs\claude.cmd"`,
+  )
+})
+
+test('quoteCmdProgram quotes a path containing an ampersand', () => {
+  assert.equal(
+    quoteCmdProgram(String.raw`C:\Users\Tom & Jerry\npm\pi.cmd`),
+    String.raw`"C:\Users\Tom & Jerry\npm\pi.cmd"`,
+  )
+})
+
+test('quoteCmdProgram quotes a path containing a caret', () => {
+  assert.equal(quoteCmdProgram(String.raw`C:\odd^dir\pi.cmd`), String.raw`"C:\odd^dir\pi.cmd"`)
+})
+
+test('quoteCmdProgram interrupts percent signs outside the quotes for a shim target', () => {
+  assert.equal(
+    quoteCmdProgram(String.raw`C:\Users\100%cool\pi.cmd`),
+    String.raw`"C:\Users\100"^%"cool\pi.cmd"`,
+  )
+  assert.equal(quoteCmdProgram(String.raw`C:\a%b%c\pi.cmd`), String.raw`"C:\a"^%"b"^%"c\pi.cmd"`)
+})
+
+test('quoteCmdProgram interrupts exclamation marks outside the quotes for a shim target', () => {
+  assert.equal(
+    quoteCmdProgram(String.raw`C:\Users\wow!\pi.cmd`),
+    String.raw`"C:\Users\wow"^!"\pi.cmd"`,
+  )
+  assert.equal(quoteCmdProgram(String.raw`C:\a!b!c\pi.bat`), String.raw`"C:\a"^!"b"^!"c\pi.bat"`)
+})
+
+test('quoteCmdProgram uses plain quotes for a native executable target', () => {
+  // cmd hands the token to the child verbatim; an interruption would end the
+  // CRT's argv[0] at the first quote and spill the remainder into argv[1].
+  assert.equal(
+    quoteCmdProgram(String.raw`C:\Users\100%cool\pi.exe`),
+    String.raw`"C:\Users\100%cool\pi.exe"`,
+  )
+  assert.equal(quoteCmdProgram(String.raw`C:\Users\wow!\pi.EXE`), String.raw`"C:\Users\wow!\pi.EXE"`)
+  assert.equal(quoteCmdProgram(String.raw`C:\odd dir\pi.com`), String.raw`"C:\odd dir\pi.com"`)
+})
+
+test('quoteCmdProgram rejects embedded quotes and control characters', () => {
+  assert.throws(() => quoteCmdProgram('bad"name.cmd'), /cannot be quoted as a cmd\.exe program/)
+  assert.throws(() => quoteCmdProgram('bad\nname.cmd'), /cannot be passed through cmd\.exe/)
+})
+
+// --- quoteCmdProgram: end-to-end round trip through the parsers it must survive ---
+
+const CARET = '^'
+const QUOTE_CHAR = '"'
+const BACKSLASH_CHAR = '\\'
+/** Extensions cmd.exe launches through CreateProcess, leaving the CRT to re-parse argv[0]. */
+const NATIVE_TARGET = /\.(exe|com)$/i
+/** Fake host environment for the expansion phase; `b` proves the interruption works. */
+const HOST_ENV: Record<string, string> = { b: 'EXPANDED', PATH: 'C:\\Windows' }
+
+/** What the child process ends up seeing for the program token. */
+interface ChildCommand {
+  program: string
+  extraArgs: string[]
+}
+
+/**
+ * cmd.exe phase 1: substitute %name% pairs, quotes included. `cmd /c` keeps an
+ * undefined reference literal instead of collapsing it, so a name our escaping
+ * interrupted with a caret survives untouched.
+ */
+function expandPercentRefs(line: string, env: Record<string, string>): string {
+  let out = ''
+  for (let index = 0; index < line.length; index++) {
+    if (line[index] !== '%') {
+      out += line[index]
+      continue
+    }
+    const close = line.indexOf('%', index + 1)
+    const value = close === -1 ? undefined : env[line.slice(index + 1, close)]
+    if (value === undefined) {
+      out += line[index]
+      continue
+    }
+    out += value
+    index = close
+  }
+  return out
+}
+
+/** cmd.exe phase 2: a caret outside quotes escapes the next character and vanishes. */
+function consumeCarets(line: string): string {
+  let out = ''
+  let inQuotes = false
+  for (let index = 0; index < line.length; index++) {
+    const char = line[index]
+    if (!inQuotes && char === CARET && index + 1 < line.length) {
+      out += line[index + 1]
+      index++
+      continue
+    }
+    if (char === QUOTE_CHAR) inQuotes = !inQuotes
+    out += char
+  }
+  return out
+}
+
+/** Split on whitespace that is not inside a quoted span, then drop the real quotes. */
+function splitUnquotedFields(line: string): string[] {
+  const fields: string[] = []
+  let current = ''
+  let started = false
+  let inQuotes = false
+  for (const char of line) {
+    if (char === QUOTE_CHAR) {
+      inQuotes = !inQuotes
+      started = true
+      continue
+    }
+    if (!inQuotes && /\s/.test(char)) {
+      if (started) fields.push(current)
+      current = ''
+      started = false
+      continue
+    }
+    current += char
+    started = true
+  }
+  if (started) fields.push(current)
+  return fields
+}
+
+/**
+ * The CRT / CommandLineToArgvW split, including the argv[0] special case: a
+ * leading quote makes argv[0] run to the NEXT quote with no escape processing,
+ * which is exactly what a program-token interruption breaks.
+ */
+function crtArgv(line: string): string[] {
+  const argv: string[] = []
+  let index = 0
+  if (line[0] === QUOTE_CHAR) {
+    const close = line.indexOf(QUOTE_CHAR, 1)
+    argv.push(line.slice(1, close === -1 ? line.length : close))
+    index = close === -1 ? line.length : close + 1
+  } else {
+    while (index < line.length && !/\s/.test(line[index])) index++
+    argv.push(line.slice(0, index))
+  }
+
+  let current = ''
+  let started = false
+  let inQuotes = false
+  let backslashes = 0
+  for (; index < line.length; index++) {
+    const char = line[index]
+    if (char === BACKSLASH_CHAR) {
+      backslashes++
+      continue
+    }
+    if (char === QUOTE_CHAR) {
+      current += BACKSLASH_CHAR.repeat(Math.floor(backslashes / 2))
+      const escaped = backslashes % 2 === 1
+      backslashes = 0
+      started = true
+      if (escaped) {
+        current += QUOTE_CHAR
+      } else if (inQuotes && line[index + 1] === QUOTE_CHAR) {
+        current += QUOTE_CHAR
+        index++
+      } else {
+        inQuotes = !inQuotes
+      }
+      continue
+    }
+    current += BACKSLASH_CHAR.repeat(backslashes)
+    backslashes = 0
+    if (!inQuotes && /\s/.test(char)) {
+      if (started) argv.push(current)
+      current = ''
+      started = false
+      continue
+    }
+    current += char
+    started = true
+  }
+  current += BACKSLASH_CHAR.repeat(backslashes)
+  if (started || current !== '') argv.push(current)
+  return argv
+}
+
+/**
+ * Push a program path through the whole Windows chain: our escaping, cmd.exe's
+ * two phases, and then whichever token parse the target type implies — cmd
+ * consuming the token for a shim, the CRT re-parsing it for a native binary.
+ */
+function throughCmd(program: string, env: Record<string, string> = HOST_ENV): ChildCommand {
+  const line = consumeCarets(expandPercentRefs(quoteCmdProgram(program), env))
+  const argv = NATIVE_TARGET.test(program) ? crtArgv(line) : splitUnquotedFields(line)
+  return { program: argv[0], extraArgs: argv.slice(1) }
+}
+
+const ROUND_TRIP_PATHS = [
+  String.raw`C:\Users\tester\npm\pi`,
+  String.raw`C:\Program Files\nodejs\pi`,
+  String.raw`C:\Users\100%cool\pi`,
+  String.raw`C:\Users\wow!\pi`,
+  String.raw`C:\Users\Tom & Jerry\100%!\pi`,
+  String.raw`C:\odd^dir (x86)\a b\pi`,
+]
+
+test('quoteCmdProgram round-trips shim paths through cmd.exe untouched', () => {
+  for (const base of ROUND_TRIP_PATHS) {
+    const path = `${base}.cmd`
+    assert.deepEqual(throughCmd(path), { program: path, extraArgs: [] }, path)
+  }
+})
+
+test('quoteCmdProgram round-trips native executable paths through cmd.exe untouched', () => {
+  for (const base of ROUND_TRIP_PATHS) {
+    const path = `${base}.exe`
+    assert.deepEqual(throughCmd(path), { program: path, extraArgs: [] }, path)
+  }
+})
+
+test('quoteCmdProgram keeps a defined %VAR% literal in a shim path', () => {
+  const path = String.raw`C:\a%b%c\pi.cmd`
+  assert.deepEqual(throughCmd(path), { program: path, extraArgs: [] })
+})
+
+test('quoteCmdProgram cannot stop %VAR% expansion in a native executable path', () => {
+  // Documented residual: the CRT argv[0] rule forbids the caret interruption
+  // for native targets, so a defined variable reference in the path still
+  // expands. Pinned so the trade-off cannot be lost silently.
+  assert.deepEqual(throughCmd(String.raw`C:\a%b%c\pi.exe`), {
+    program: String.raw`C:\aEXPANDEDc\pi.exe`,
+    extraArgs: [],
+  })
+})
+
+// --- escapeCmdSpawn ---
+
+test('escapeCmdSpawn passes program and args through untouched off the cmd path', () => {
+  assert.deepEqual(escapeCmdSpawn(false, '/usr/bin/claude', ['-p', 'a b', 'x&y']), {
+    file: '/usr/bin/claude',
+    args: ['-p', 'a b', 'x&y'],
+  })
+})
+
+test('escapeCmdSpawn keeps the npm prefix probe byte-identical on the cmd path', () => {
+  assert.deepEqual(escapeCmdSpawn(true, 'npm.cmd', ['prefix', '-g']), {
+    file: 'npm.cmd',
+    args: ['prefix', '-g'],
+  })
+})
+
+test('escapeCmdSpawn quotes the program and escapes each arg on the cmd path', () => {
+  assert.deepEqual(
+    escapeCmdSpawn(true, String.raw`C:\Program Files\nodejs\claude.cmd`, ['-p', 'a b', 'x&y']),
+    {
+      file: String.raw`"C:\Program Files\nodejs\claude.cmd"`,
+      args: ['-p', '"a b"', '"x&y"'],
+    },
+  )
+})
+
+test('escapeCmdSpawn does not mutate the input args array', () => {
+  const args = ['a b']
+  escapeCmdSpawn(true, 'npm.cmd', args)
+  assert.deepEqual(args, ['a b'])
+})
+
+// --- buildNpmPrefixCommand: the shared `npm prefix -g` probe ---
+
+test('buildNpmPrefixCommand targets the npm shim through cmd.exe on Windows', () => {
+  assert.deepEqual(buildNpmPrefixCommand(true), {
+    file: 'npm.cmd',
+    args: ['prefix', '-g'],
+  })
+})
+
+test('buildNpmPrefixCommand targets plain npm off Windows', () => {
+  assert.deepEqual(buildNpmPrefixCommand(false), {
+    file: 'npm',
+    args: ['prefix', '-g'],
+  })
+})
+
+test('buildNpmPrefixCommand returns a fresh args array each call', () => {
+  // Callers hand these straight to spawn; a shared array could be mutated by one
+  // caller and observed by the next.
+  const first = buildNpmPrefixCommand(true)
+  first.args.push('--extra')
+  assert.deepEqual(buildNpmPrefixCommand(true).args, ['prefix', '-g'])
+})

package/apps/sessrumnir/src/main/cmd-escape.ts

@@ -0,0 +1,186 @@
+/**
+ * Escaping for Windows spawns that must run with shell:true.
+ *
+ * Since Node's CVE-2024-27980 fix, `.cmd`/`.bat` shims can only be launched
+ * through cmd.exe (shell:true) — and with shell:true Node performs NO quoting:
+ * it joins program and args with spaces into `cmd.exe /d /s /c "..."`. Every
+ * argument therefore traverses up to three parsers, and must survive each:
+ *
+ *   1. cmd.exe's command line: phase 1 expands %var% (even inside quotes),
+ *      phase 2 honors quotes and treats & | < > ^ ( ) as operators outside
+ *      them. `cmd /c` uses command-line semantics: an UNDEFINED %name%
+ *      reference is left literal (in batch files it would collapse to
+ *      nothing), and carets are consumed outside quotes.
+ *   2. The `.cmd` shim's own `%*` line: npm shims re-insert the args into a
+ *      batch line (`"%_prog%" "%dp0%\...\cli.js" %*`) that goes through cmd's
+ *      phase 2 AGAIN. `%*` substitution is single-pass and non-recursive, so
+ *      percents inside argument text are not re-expanded there — but any
+ *      metacharacter not enclosed in REAL quotes at this point injects (the
+ *      BatBadBut pattern, CVE-2024-24576).
+ *   3. The final program's argv split (CommandLineToArgvW / CRT rules):
+ *      backslashes are literal except runs preceding a quote (2n backslashes
+ *      collapse to n), and inside a quoted span a PAIRED `""` yields one
+ *      literal quote.
+ *
+ * Parser 2 is why the classic caret-everything approach (argv-quote with \",
+ *  then ^-prefix every metacharacter) is NOT used for arguments: the outer
+ * cmd.exe consumes the carets, so by the time the shim's `%*` line re-parses
+ * the text, a quote escaped as \" has broken cmd's quote pairing and any
+ * following & | < > executes inside the shim. The encoding that survives all
+ * three parsers is:
+ *
+ *   - wrap the argument in real double quotes (kept by every cmd pass, so
+ *     metacharacters stay quoted through the shim), escaping embedded quotes
+ *     as paired `""` — which preserves cmd's quote parity AND parses back to
+ *     one literal quote under rule 3;
+ *   - double every backslash run that precedes an emitted quote, per the
+ *     Microsoft argv rules of parser 3;
+ *   - `%` and `!` expand inside quotes, so each is moved OUTSIDE the quotes
+ *     and caret-interrupted: `"^%"` / `"^!"`. The caret lands inside every
+ *     candidate variable name, no such name is defined, command-line
+ *     semantics keep the undefined reference literal, and phase 2 then strips
+ *     the caret — restoring the original character. No whitespace is ever
+ *     exposed outside quotes, so the argument cannot split.
+ *
+ * Known residual limits, unfixable at this layer: an environment variable
+ * whose name itself contains a caret would still expand, and delayed expansion
+ * can mangle `^`/`!` combinations inside a shim we do not control. Delayed
+ * expansion is OFF for `cmd /c` by default, so this affects only two host
+ * configurations: a machine whose Command Processor\DelayedExpansion registry
+ * value (HKCU or HKLM) is enabled, and a shim that runs `setlocal
+ * EnableDelayedExpansion` itself. \r, \n and NUL truncate the command line and
+ * have no escape at all, so they are rejected outright.
+ *
+ * The program token gets its own, different treatment (quoteCmdProgram):
+ * cmd.exe locates the command with genuine quote state, so its quotes must be
+ * real (a caret-escaped quote would end the token at the first space), and
+ * cmd — not the CRT — consumes them, so argv backslash doubling does not
+ * apply. What follows depends on who parses the token last:
+ *
+ *   - `.cmd`/`.bat` shims, and every other target (a bare name cmd resolves
+ *     through PATHEXT ends up at one): cmd alone consumes the token, so `%`
+ *     and `!` are caret-interrupted exactly as in arguments and nothing
+ *     re-reads the text. This is also the safe default for an unknown target,
+ *     since an interruption can only be observed by a CRT argv[0] parse.
+ *   - `.exe`/`.com` targets: cmd hands the command line to CreateProcess and
+ *     the child's CRT re-parses argv[0], where a LEADING quote runs to the
+ *     next quote with no escape processing. An interruption would therefore
+ *     end argv[0] early and spill the remainder into a spurious argv[1], so
+ *     the path is wrapped in plain real quotes instead. Residual risk, of the
+ *     same kind as the delayed-expansion caveat above: a defined `%VAR%`
+ *     reference inside such a path still expands in cmd's phase 1. Windows
+ *     paths containing `%` are pathological, and no encoding can prevent it
+ *     while keeping argv[0] intact.
+ */
+
+const BACKSLASH = '\\'
+const QUOTE = '"'
+/** Paired-quote escape: keeps cmd quote parity, parses back to one quote. */
+const DOUBLED_QUOTE = '""'
+/** Close the quotes, neutralize the character with a caret, reopen. */
+const PERCENT_INTERRUPT = '"^%"'
+const BANG_INTERRUPT = '"^!"'
+/** Characters cmd.exe treats as line terminators; nothing can escape them. */
+const CMD_UNPASSABLE_CHARS = ['\0', '\r', '\n']
+/** Anything here forces the full quoting algorithm; a miss stays byte-identical. */
+const ARG_NEEDS_QUOTING = /[\s"%!^&|<>()]/
+/** Same set minus the quote, which is rejected for program paths instead. */
+const PROGRAM_NEEDS_QUOTING = /[\s%!^&|<>()]/
+/** Targets cmd.exe starts directly, leaving the child's CRT to re-parse argv[0]. */
+const NATIVE_PROGRAM_PATTERN = /\.(exe|com)$/i
+
+function assertCmdPassable(value: string, role: string): void {
+  for (const char of CMD_UNPASSABLE_CHARS) {
+    if (value.includes(char)) {
+      throw new Error(
+        `${role} contains characters that cannot be passed through cmd.exe: ${JSON.stringify(value)}`,
+      )
+    }
+  }
+}
+
+/**
+ * Escape one argv element for a Windows shell:true spawn. Safe plain args
+ * (flags, bare paths) are returned unchanged.
+ */
+export function escapeCmdArg(arg: string): string {
+  assertCmdPassable(arg, 'argument')
+  if (arg !== '' && !ARG_NEEDS_QUOTING.test(arg)) return arg
+
+  let out = QUOTE
+  let backslashes = 0
+  for (const char of arg) {
+    if (char === BACKSLASH) {
+      backslashes += 1
+      continue
+    }
+    if (char === QUOTE || char === '%' || char === '!') {
+      // Each of these emits a quote next, so the run preceding it doubles.
+      out += BACKSLASH.repeat(backslashes * 2)
+      out += char === QUOTE ? DOUBLED_QUOTE : char === '%' ? PERCENT_INTERRUPT : BANG_INTERRUPT
+    } else {
+      out += BACKSLASH.repeat(backslashes) + char
+    }
+    backslashes = 0
+  }
+  return out + BACKSLASH.repeat(backslashes * 2) + QUOTE
+}
+
+/**
+ * Quote the program token of a Windows shell:true spawn. Plain names and
+ * paths are returned unchanged; quotes cannot appear in Windows paths and are
+ * rejected rather than escaped, because no escape exists in command position.
+ * The encoding follows the target type (see the file header): `%`/`!` are
+ * caret-interrupted for shims, whose token only cmd itself reads, and left
+ * inside plain quotes for native binaries, whose CRT re-parses argv[0].
+ */
+export function quoteCmdProgram(program: string): string {
+  assertCmdPassable(program, 'program')
+  if (program.includes(QUOTE)) {
+    throw new Error(
+      `program contains a quote and cannot be quoted as a cmd.exe program: ${JSON.stringify(program)}`,
+    )
+  }
+  if (program !== '' && !PROGRAM_NEEDS_QUOTING.test(program)) return program
+  if (NATIVE_PROGRAM_PATTERN.test(program)) return QUOTE + program + QUOTE
+  return (
+    QUOTE + program.replaceAll('%', PERCENT_INTERRUPT).replaceAll('!', BANG_INTERRUPT) + QUOTE
+  )
+}
+
+/**
+ * Prepare a program + argv pair for spawn(). With `viaCmd` false (POSIX,
+ * shell:false) both pass through untouched, keeping non-Windows spawns
+ * byte-for-byte identical; with it true both are escaped to survive the
+ * cmd.exe traversal that shell:true implies.
+ */
+export function escapeCmdSpawn(
+  viaCmd: boolean,
+  file: string,
+  args: readonly string[],
+): { file: string; args: string[] } {
+  if (!viaCmd) return { file, args: [...args] }
+  return { file: quoteCmdProgram(file), args: args.map(escapeCmdArg) }
+}
+
+const NPM_WINDOWS_SHIM = 'npm.cmd'
+const NPM_POSIX_BINARY = 'npm'
+const NPM_PREFIX_ARGS = ['prefix', '-g'] as const
+
+/**
+ * The `npm prefix -g` probe used to locate globally installed CLIs. Both
+ * callers spawn it with shell:true on Windows to reach npm's `.cmd` shim.
+ *
+ * Every token is a constant that needs no rewriting, so the escaped and raw
+ * forms are byte-identical and no behavioural test can distinguish a caller
+ * that uses this helper from one that inlines the strings. Centralising it is
+ * what keeps the guarantee: a caller that later needs a variable argument
+ * inherits the escaping instead of reinventing an unescaped spawn.
+ */
+export function buildNpmPrefixCommand(isWindows: boolean): { file: string; args: string[] } {
+  return escapeCmdSpawn(
+    isWindows,
+    isWindows ? NPM_WINDOWS_SHIM : NPM_POSIX_BINARY,
+    NPM_PREFIX_ARGS,
+  )
+}