Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

refactor: share Windows CLI resolution and batch escaping (#10704)

Adam Eivy888cb03a00c1
diff --git a/server/lib/aiToolkit/internal/windowsSafeSpawn.js b/server/lib/aiToolkit/internal/windowsSafeSpawn.js
index ce32a5d32f..43ffd8a328 100644
--- a/server/lib/aiToolkit/internal/windowsSafeSpawn.js
+++ b/server/lib/aiToolkit/internal/windowsSafeSpawn.js
@@ -1,15 +1,14 @@
/**
- * Windows-safe spawn helpers shared by every CLI probe that resolves a bare
- * command name into an executable path before handing it to `spawn`/`execFile`.
+ * Windows command resolution and batch argument escaping shared by host CLI
+ * launches, the toolkit runner, and provider catalog probes.
*
- * Lives here (its own leaf) rather than inline in `providerCatalogService.js`
- * because `internal/codexAppServer.js` needs the same resolution and this
- * directory stays self-contained — no imports out, so a second copy of these
- * rules is the alternative to importing this file.
+ * This toolkit leaf stays self-contained so host callers can depend inward
+ * without requiring toolkit code to import PortOS modules.
*/
import { existsSync } from 'fs';
import { join, isAbsolute, delimiter } from 'path';
+// Prefer native executables to batch shims; ignore npm's POSIX extensionless stubs.
const WIN_EXECUTABLE_EXTS = ['.exe', '.cmd', '.bat', '.com'];
/**
@@ -44,7 +43,10 @@ function escapeCmdMetacharsIfUnquoted(value) {
/**
* A `.cmd`/`.bat` target must run through `cmd.exe /c`, or `spawn` under
* `shell: false` cannot execute it at all. Every other command/argv pair
- * passes through unchanged.
+ * passes through unchanged. No shell:true workaround is needed: spawning
+ * cmd.exe directly lets Node quote whitespace/quotes in each argument.
+ * Caret escaping protects metacharacters only in values Node leaves unquoted;
+ * escaping already-quoted values would introduce literal carets.
*/
export function prepareWindowsSafeSpawn(command, args, isWin32 = process.platform === 'win32') {
if (isWin32 && WIN_BATCH_EXT_RE.test(command)) {
diff --git a/server/lib/aiToolkit/runner.js b/server/lib/aiToolkit/runner.js
index 8f0e59bb36..83eab213cb 100644
--- a/server/lib/aiToolkit/runner.js
+++ b/server/lib/aiToolkit/runner.js
@@ -2,7 +2,7 @@ import { mkdir, readFile, readdir, rm } from 'fs/promises';
import { atomicWrite } from './internal/atomicWrite.js';
import { evaluateSecretEndpoint } from './endpointGuard.js';
import { existsSync } from 'fs';
-import { join, extname, basename, isAbsolute, delimiter } from 'path';
+import { join, extname, basename, isAbsolute } from 'path';
import { spawn, ChildProcess } from 'child_process';
import { randomUUID } from 'crypto';
import { analyzeError, ERROR_CATEGORIES } from './errorDetection.js';
@@ -19,20 +19,11 @@ import { DEFAULT_API_RUN_TIMEOUT_MS, apiRunAbsoluteTimeoutMs } from './internal/
import { streamTransportDispatcher } from './internal/streamTransport.js';
import { createRunLifecycle } from './internal/runLifecycle.js';
import { createRunFinalizer } from './internal/runFinalizer.js';
+import { resolveWindowsExecutable, prepareWindowsSafeSpawn } from './internal/windowsSafeSpawn.js';
-// npm-installed CLI providers (claude, codex, opencode, …) are .cmd/.bat
-// shims on Windows; Node's spawn() can't execute those without going through
-// cmd.exe. Mirrors `server/lib/bufferedSpawn.js`'s IS_WIN32/killProcessTree/
-// resolveWindowsExecutable pattern — duplicated rather than imported, since
-// this directory must stay self-contained (see ./AGENTS.md).
+// Windows process-tree teardown stays local; command preparation uses the shared leaf.
const IS_WIN32 = process.platform === 'win32';
-// Extensions Windows can launch directly, checked in cmd.exe's own resolution
-// preference. Deliberately excludes an extension-less match — npm ships a
-// POSIX shell-script stub alongside a package's `.cmd`/`.bat`/`.ps1` Windows
-// wrappers (for Git Bash/WSL), and that stub is not natively launchable here.
-const WIN_EXECUTABLE_EXTS = ['.exe', '.cmd', '.bat', '.com'];
-
const DEFAULT_OUTPUT_RESERVE_TOKENS = 8000;
const CHARS_PER_TOKEN = 4;
@@ -44,73 +35,6 @@ function deriveRequestCapabilities({ prompt, screenshots, requestCapabilities })
};
}
-/**
- * Resolve a bare command name to its full path WITH extension on Windows, so
- * the caller knows exactly which file (and which kind — `.exe` vs
- * `.cmd`/`.bat`) it's about to launch. Filesystem-only (no subprocess). See
- * server/lib/bufferedSpawn.js's `resolveWindowsExecutable` docstring for the
- * full root-cause explanation (including why `searchEnv` matters — a
- * provider-configured PATH override), mirrored here for self-containment.
- * Pair with `prepareWindowsSafeSpawn` below to get a launchable
- * `{ command, args }`.
- */
-function resolveWindowsExecutable(command, isWin32 = IS_WIN32, searchEnv = process.env) {
- if (!isWin32 || !command || isAbsolute(command) || /[\\/]/.test(command)) return null;
- const pathDirs = (searchEnv.PATH || searchEnv.Path || '').split(delimiter).filter(Boolean);
- for (const dir of pathDirs) {
- for (const ext of WIN_EXECUTABLE_EXTS) {
- const candidate = join(dir, `${command}${ext}`);
- if (existsSync(candidate)) return candidate;
- }
- }
- return null;
-}
-
-const WIN_BATCH_EXT_RE = /\.(cmd|bat)$/i;
-
-/**
- * Return the `{ command, args }` pair that's actually safe to hand to
- * `spawn()` under `shell:false` — THE ACTUAL FIX FOR #1865. `.bat`/`.cmd`
- * files cannot be launched directly under `shell:false` even with the
- * explicit extension (Node's CVE-2024-27980 patch makes `spawn()` refuse
- * them outright, full stop — it does NOT safely auto-wrap them). Node's
- * documented safe alternative is to spawn `cmd.exe /c <path> <args>`
- * directly: `cmd.exe` is a normal `.exe`, so Node's existing, already-tested
- * non-shell argv→command-line escaping governs the result, with none of
- * `shell:true`'s DEP0190 unescaped-join hazard. Mirrors
- * server/lib/bufferedSpawn.js's `prepareWindowsSafeSpawn` for self-containment.
- */
-function prepareWindowsSafeSpawn(command, args, isWin32 = IS_WIN32) {
- if (isWin32 && WIN_BATCH_EXT_RE.test(command)) {
- return {
- command: 'cmd.exe',
- args: ['/c', escapeCmdMetacharsIfUnquoted(command), ...args.map(escapeCmdMetacharsIfUnquoted)],
- };
- }
- return { command, args };
-}
-
-// cmd.exe metacharacters that act as command separators / redirection /
-// grouping on its raw command line.
-const CMD_METACHAR_RE = /[&|<>^()]/g;
-// Node's argv→command-line quoting wraps an argument in literal double
-// quotes only when it contains whitespace or a `"`; characters inside that
-// quoted span are not re-interpreted by cmd.exe.
-const NEEDS_NODE_QUOTING_RE = /[\s"]/;
-
-/**
- * Caret-escape cmd.exe metacharacters, but ONLY when Node's own quoting
- * would otherwise leave the argument unquoted on cmd.exe's raw command line
- * (an argument WITH whitespace is already double-quoted by Node, and
- * caret-escaping it too would inject literal `^` into the value the target
- * program receives). Mirrors server/lib/bufferedSpawn.js for self-containment.
- */
-function escapeCmdMetacharsIfUnquoted(value) {
- const str = String(value);
- if (NEEDS_NODE_QUOTING_RE.test(str)) return str;
- return str.replace(CMD_METACHAR_RE, '^$&');
-}
-
// On Windows, taskkill (used below) runs in a separate detached process that
// never touches the original ChildProcess object — `.killed` is set
// synchronously here (mirroring what Node's own `child.kill()` does on the
@@ -490,7 +414,7 @@ export function createRunnerService(config = {}) {
// shell metacharacters, and so the full prompt isn't visible in
// process listings as a single command-line argument. On Windows,
// resolve+wrap a .cmd/.bat target instead of enabling a shell — see
- // prepareWindowsSafeSpawn above for why shell:true is unsafe here.
+ // internal/windowsSafeSpawn.js for why shell:true is unsafe here.
const args = [...(provider.args || [])];
console.log(`🚀 Executing CLI: ${provider.command} ${args.join(' ')} (${prompt.length} chars via stdin)`);
diff --git a/server/lib/aiToolkit/runner.test.js b/server/lib/aiToolkit/runner.test.js
index 74ae9f71b1..b37087203f 100644
--- a/server/lib/aiToolkit/runner.test.js
+++ b/server/lib/aiToolkit/runner.test.js
@@ -4,6 +4,7 @@ import { join, basename } from 'path';
import { tmpdir } from 'os';
import EventEmitter from 'events';
import { ChildProcess } from 'child_process';
+import { pinPlatform } from '../testHelper.js';
const IS_WIN32 = process.platform === 'win32';
@@ -1975,15 +1976,8 @@ describe('AI Toolkit runner — built-in executeCliRun spawn (#1865)', () => {
}
it('never enables shell:true — resolveWindowsExecutable (not a shell) is the Windows fix', async () => {
- // resolveWindowsExecutable is module-private here, and its IS_WIN32 default
- // is bound once at module load like the rest of the codebase's win32-gated
- // logic (see bufferedSpawn.test.js) — it can't be faked by mutating
- // process.platform mid-test. The resolution ALGORITHM itself is exhaustively
- // covered by server/lib/bufferedSpawn.test.js's injectable-isWin32 tests
- // (this file's copy is a byte-for-byte mirror); this test only pins the
- // wiring — that the built-in spawn never falls back to shell:true (the
- // DEP0190-unsafe approach this directory rejected — see resolveWindowsExecutable
- // docstring above) regardless of platform.
+ // The shared leaf's input matrix lives in bufferedSpawn.test.js; this
+ // caller contract pins shell-free spawning regardless of platform.
const dataDir = await mkdtemp(join(tmpdir(), 'ai-toolkit-runner-spawn-'));
const runner = createRunnerService({ dataDir });
const child = makeChild();
@@ -2014,6 +2008,40 @@ describe('AI Toolkit runner — built-in executeCliRun spawn (#1865)', () => {
await rm(dataDir, { recursive: true, force: true });
});
+ it('resolves a Windows shim from the child PATH and escapes only unquoted values', async () => {
+ const dataDir = await mkdtemp(join(tmpdir(), 'ai-toolkit-runner-windows-'));
+ const shimDir = join(dataDir, 'tools&cli');
+ await mkdir(shimDir);
+ const shim = join(shimDir, 'example.cmd');
+ await writeFile(shim, '');
+ const restorePlatform = pinPlatform('win32');
+ let completed;
+ try {
+ const runner = createRunnerService({ dataDir });
+ const child = makeChild();
+ spawn.mockReturnValue(child);
+ let resolveComplete;
+ completed = new Promise(resolve => { resolveComplete = resolve; });
+ await runner.executeCliRun({
+ runId: 'windows-shim',
+ provider: { id: 'example', command: 'example', args: ['plain&value', 'quoted & value'], envVars: { PATH: shimDir } },
+ prompt: 'test prompt',
+ onComplete: resolveComplete,
+ });
+ const [command, args, options] = spawn.mock.calls.at(-1);
+ child.stdout.emit('data', Buffer.from('output'));
+ child.emit('close', 0);
+ await completed;
+ expect(command).toBe('cmd.exe');
+ expect(args).toEqual(['/c', shim.replace('&', '^&'), 'plain^&value', 'quoted & value']);
+ expect(options.shell).toBeFalsy();
+ expect(options.env.PATH).toBe(shimDir);
+ } finally {
+ restorePlatform();
+ await rm(dataDir, { recursive: true, force: true });
+ }
+ });
+
it('settles a failed spawn once, clears the run, and swallows stdin EPIPE (#8031)', async () => {
const dataDir = await mkdtemp(join(tmpdir(), 'ai-toolkit-runner-spawn-err-'));
const runId = 'spawn-enoent';
diff --git a/server/lib/bufferedSpawn.js b/server/lib/bufferedSpawn.js
index 2d57a093e5..f8600b4e70 100644
--- a/server/lib/bufferedSpawn.js
+++ b/server/lib/bufferedSpawn.js
@@ -1,6 +1,8 @@
import { spawn, ChildProcess } from './childProcess.js';
-import { existsSync } from 'fs';
-import { delimiter, isAbsolute, join } from 'path';
+import { resolveWindowsExecutable, prepareWindowsSafeSpawn } from './aiToolkit/internal/windowsSafeSpawn.js';
+
+// Keep the host's public API while sharing the toolkit's self-contained leaf.
+export { resolveWindowsExecutable, prepareWindowsSafeSpawn };
import { withSpawnCwdEnv } from './spawnCwd.js';
/**
@@ -35,99 +37,6 @@ export const WIN_CMD_SHIMS = new Set(['npm', 'npx']);
*/
export const needsShell = (cmd) => IS_WIN32 && WIN_CMD_SHIMS.has(cmd);
-// Extensions Windows can launch directly, checked in cmd.exe's own resolution
-// preference (a real .exe wins over a batch shim when both exist). Deliberately
-// excludes an extension-less match — npm ships a POSIX shell-script stub
-// alongside a package's `.cmd`/`.bat`/`.ps1` Windows wrappers (for Git
-// Bash/WSL), and that stub is not natively launchable on Windows.
-const WIN_EXECUTABLE_EXTS = ['.exe', '.cmd', '.bat', '.com'];
-
-/**
- * Resolve a bare command name (e.g. "opencode") to its full path WITH
- * extension on Windows, so the caller knows exactly which file (and which
- * kind — `.exe` vs `.cmd`/`.bat`) it's about to launch.
- *
- * A bare command with no extension never resolves on Windows even though
- * typing it at a real cmd.exe prompt works fine: libuv's internal PATHEXT
- * search finds e.g. "opencode.cmd", but `spawn()`'s default `shell: false`
- * doesn't apply that search at all (it targets the literal string given).
- *
- * Deliberately filesystem-only (no `where`/`which` subprocess) so resolution
- * is synchronous and side-effect-free. Pair with `prepareWindowsSafeSpawn`
- * below to get a `{ command, args }` pair that's actually launchable.
- *
- * Searches `searchEnv.PATH`/`.Path`, NOT necessarily `process.env` — pass the
- * actual env object the child will run under (e.g. after merging a
- * provider's `envVars`) so a per-provider `PATH` override is honored. The
- * default is `process.env` for callers that don't customize the child env.
- *
- * @param {string} command - bare command name, or an existing path (returned unchanged)
- * @param {boolean} [isWin32] - injectable for tests; defaults to the real platform
- * @param {NodeJS.ProcessEnv} [searchEnv] - env to read PATH from; defaults to `process.env`
- * @returns {string|null} the resolved absolute path, or null when not found
- * (off win32, command is already a path, or no match exists on PATH)
- */
-export function resolveWindowsExecutable(command, isWin32 = IS_WIN32, searchEnv = process.env) {
- if (!isWin32 || !command || isAbsolute(command) || /[\\/]/.test(command)) return null;
- const pathDirs = (searchEnv.PATH || searchEnv.Path || '').split(delimiter).filter(Boolean);
- for (const dir of pathDirs) {
- for (const ext of WIN_EXECUTABLE_EXTS) {
- const candidate = join(dir, `${command}${ext}`);
- if (existsSync(candidate)) return candidate;
- }
- }
- return null;
-}
-
-const WIN_BATCH_EXT_RE = /\.(cmd|bat)$/i;
-
-/**
- * Return the `{ command, args }` pair that's actually safe to hand to
- * `spawn()`/`execFile()` under the default `shell: false`, given a (possibly
- * `resolveWindowsExecutable`-resolved) command.
- *
- * THE ACTUAL FIX FOR #1865. An earlier version of this fix assumed Node's
- * CVE-2024-27980 patch safely auto-escapes a `.bat`/`.cmd` target under
- * `shell: false` once it carries the explicit extension — that's wrong. The
- * shipped patch instead makes `spawn()`/`spawnSync()` **refuse** (an
- * `'error'`/EINVAL-class failure) any `.bat`/`.cmd` target under
- * `shell: false`, full stop; per Node's own docs, `.bat`/`.cmd` files
- * "are not executable on their own... and cannot be launched" that way.
- * Node's documented safe alternative is to spawn `cmd.exe /c <path> <args>`
- * directly: `cmd.exe` is a normal `.exe`, so Node's existing, already-tested
- * non-shell argv→command-line escaping governs the result — correctly
- * preserving spaces/quotes in each arg — with none of `shell: true`'s
- * DEP0190 unescaped-join hazard (a literal `shell: true` + args array does
- * NOT escape arguments, it just space-joins them).
- *
- * A resolved native `.exe`/`.com` target needs no wrapping at all — it's
- * directly launchable, so it's returned unchanged.
- *
- * The resolved path AND each arg are passed through
- * `escapeCmdMetacharsIfUnquoted` (see its docstring) — Node's own
- * argv→command-line quoting only wraps a value in literal double quotes when
- * it contains whitespace/a quote; a value with none of those reaches
- * cmd.exe's raw command line UNQUOTED, so a bare metacharacter like `&` in
- * it would still be interpreted by cmd.exe as a command separator despite
- * `shell:false` — this covers both a metacharacter in an arg AND one in the
- * resolved install path itself (e.g. a custom npm prefix directory named
- * `C:\Tools&CLIs\npm`).
- *
- * @param {string} command - bare name, or a resolveWindowsExecutable result
- * @param {string[]} args
- * @param {boolean} [isWin32] - injectable for tests; defaults to the real platform
- * @returns {{ command: string, args: string[] }}
- */
-export function prepareWindowsSafeSpawn(command, args, isWin32 = IS_WIN32) {
- if (isWin32 && WIN_BATCH_EXT_RE.test(command)) {
- return {
- command: 'cmd.exe',
- args: ['/c', escapeCmdMetacharsIfUnquoted(command), ...args.map(escapeCmdMetacharsIfUnquoted)],
- };
- }
- return { command, args };
-}
-
/**
* Compose `resolveWindowsExecutable` + `prepareWindowsSafeSpawn` into the single
* `{ command, args }` pair a caller should hand to `spawn()` under the default
@@ -162,32 +71,6 @@ export function prepareCliSpawn(command, args, searchEnv = process.env, isWin32
return prepareWindowsSafeSpawn(resolved, args, isWin32);
}
-// cmd.exe metacharacters that act as command separators / redirection /
-// grouping on its raw command line.
-const CMD_METACHAR_RE = /[&|<>^()]/g;
-// Node's argv→command-line quoting (CommandLineToArgvW rules, used because
-// cmd.exe is a normal executable target from Node's point of view) wraps an
-// argument in literal double quotes only when it contains whitespace or a
-// `"` — characters inside that quoted span are not re-interpreted by cmd.exe.
-const NEEDS_NODE_QUOTING_RE = /[\s"]/;
-
-/**
- * Caret-escape cmd.exe metacharacters in an argument, but ONLY when Node's
- * own quoting (see NEEDS_NODE_QUOTING_RE above) would otherwise leave it
- * unquoted on cmd.exe's raw command line. An argument containing whitespace
- * is deliberately left untouched here — it's already wrapped in literal
- * double quotes by Node, and caret-escaping it too would inject literal `^`
- * characters into the value the target program receives, corrupting it.
- * This is the narrower, conservative fix for the specific gap: an argument
- * with NO whitespace but a metacharacter (e.g. `foo&calc`) reaches cmd.exe
- * unquoted and unprotected without this.
- */
-function escapeCmdMetacharsIfUnquoted(value) {
- const str = String(value);
- if (NEEDS_NODE_QUOTING_RE.test(str)) return str;
- return str.replace(CMD_METACHAR_RE, '^$&');
-}
-
// Cap buffered stdout/stderr so a runaway child can't exhaust memory; we only
// ever surface a tail of the output anyway.
export const MAX_OUTPUT_BYTES = 64 * 1024;