@gjsify/cli 0.26.1 → 0.27.1

package/lib/utils/spawn.js

@@ -45,8 +45,34 @@
 // {@link SpawnToCompletionOptions.completion} field. It is required on
 // purpose: a new call site must state which side of the table it is on rather
 // than silently inherit a default that may be wrong for it.
+//
+// ## When a raw `node:child_process` spawn is still fine — and when it is not
+//
+// This helper is also where the Windows command rewrite lives (`forWin32`
+// below), so the rule is about WHAT is being spawned, not about house style:
+//
+//   • spawning a real executable — `git`, `gh`, `node`, `gjs`, `flatpak`, or
+//     `process.execPath` — may use `node:child_process` directly. Windows
+//     resolves those via `.exe` on its own.
+//   • spawning with `shell: true` is fine too: Node routes it through
+//     `%COMSPEC%`, which finds `.cmd` shims.
+//   • spawning a PACKAGE MANAGER or any other `node_modules/.bin` entry by
+//     BARE NAME — `npm`, `yarn`, `npx`, `tsc`, `oxlint`, or a `pm` variable
+//     from `detectPackageManager()` — MUST come through here. On Windows those
+//     are `.cmd` shims: `spawn('npm')` is ENOENT and `spawn('npm.cmd')` is
+//     EINVAL, so a raw spawn cannot work at all.
+//
+// The third case is not hypothetical. Three sites kept a raw spawn after the
+// consolidation above and each one broke on win32 in its own way:
+// `commands/check.ts` (single-package mode) read only `r.status` and so exited
+// 1 with no diagnostic whatsoever; `utils/install-backend.ts` reported "npm not
+// found on PATH" on a host where npm was on PATH; `commands/onboard.ts` broke
+// the pre-publish build. All three were invisible to Linux and macOS CI.
 import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { resolveWin32Command } from './win32-command.js';
 /** Default capture ceiling on the blocking path — 64 MiB. */
 const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;
 /**
@@ -60,6 +86,23 @@ function resolveEnv(opts) {
     const seed = process.env.FORCE_COLOR !== undefined || process.env.NO_COLOR !== undefined ? {} : { FORCE_COLOR: '1' };
     return { ...base, ...seed };
 }
+/**
+ * Rewrite a bare command for Windows, where `spawn('npm', …)` is ENOENT and
+ * `spawn('npm.cmd', …)` is EINVAL — see `utils/win32-command.ts`. A no-op on
+ * every other platform, and on win32 for anything already carrying a path or an
+ * extension. Applied to BOTH paths below so the blocking GJS branch and the
+ * streaming one agree; `env` is the child's, because its `PATH` (with
+ * `node_modules/.bin` prepended) is what has to be searched.
+ */
+function forWin32(cmd, args, env) {
+    const rewritten = resolveWin32Command(cmd, args, {
+        platform: process.platform,
+        env: env ?? process.env,
+        exists: existsSync,
+        join,
+    });
+    return rewritten ?? { cmd, args: [...args] };
+}
 /** Turn a spawn-time failure into the caller's domain error when it is ENOENT. */
 function mapSpawnError(err, opts) {
     if (err.code === 'ENOENT' && opts.notFound)
@@ -96,11 +139,13 @@ export function spawnToCompletion(cmd, args, opts) {
         // `communicateWithTimeout`), so the child's diagnostics would be
         // silently dropped. Capture them and re-emit after the child exits.
         // stdin stays inherited so an interactive child still reads the tty.
-        const r = spawnSync(cmd, [...args], {
+        const win = forWin32(cmd, args, env);
+        const r = spawnSync(win.cmd, win.args, {
             stdio: ['inherit', 'pipe', 'pipe'],
             cwd: opts.cwd,
             env,
             maxBuffer: opts.maxBuffer ?? DEFAULT_MAX_BUFFER,
+            windowsVerbatimArguments: win.windowsVerbatimArguments,
         });
         if (r.error)
             return Promise.reject(mapSpawnError(r.error, opts));
@@ -111,13 +156,16 @@ export function spawnToCompletion(cmd, args, opts) {
         return Promise.resolve({ code: r.status, signal: r.signal ?? null });
     }
     return new Promise((resolvePromise, reject) => {
+        const win = forWin32(cmd, args, env);
         const spawnOpts = {
             cwd: opts.cwd,
             stdio: opts.stdio === 'pipe' ? ['ignore', 'pipe', 'pipe'] : 'inherit',
         };
         if (env)
             spawnOpts.env = env;
-        const child = spawn(cmd, [...args], spawnOpts);
+        if (win.windowsVerbatimArguments)
+            spawnOpts.windowsVerbatimArguments = true;
+        const child = spawn(win.cmd, win.args, spawnOpts);
         opts.onSpawn?.(child);
         // `close` (not `exit`) so piped stdio is fully drained before the
         // caller's flushers run. With `stdio: 'inherit'` the two are emitted

package/lib/utils/win32-command.d.ts

@@ -0,0 +1,54 @@
+/** A command rewritten for Windows: what to spawn, with which argv. */
+export interface Win32Invocation {
+    /** Executable to spawn — an absolute path, or the command interpreter. */
+    cmd: string;
+    /** Arguments for {@link cmd}. Pre-escaped when {@link windowsVerbatimArguments} is set. */
+    args: string[];
+    /** Tells Node the argv is already escaped and must be passed through untouched. */
+    windowsVerbatimArguments?: boolean;
+}
+/** Everything {@link resolveWin32Command} needs from the outside world. */
+export interface Win32ResolveContext {
+    /** `process.platform`. Injected so the branch is testable off Windows. */
+    platform: string;
+    /** The environment the CHILD will get — its `PATH` is what must be searched. */
+    env: NodeJS.ProcessEnv;
+    /** Filesystem probe. Injected so tests need no real files. */
+    exists: (path: string) => boolean;
+    /** Path joiner. Injected so a Linux host can exercise Windows-shaped paths. */
+    join: (dir: string, file: string) => string;
+}
+/**
+ * Read `name` from `env` case-insensitively.
+ *
+ * Windows environment variables are case-insensitive and `process.env` mirrors
+ * that, but a plain object handed in as `env` (which is what every spawn call
+ * site builds) does not — a child env carrying `Path` rather than `PATH` would
+ * otherwise silently resolve nothing.
+ */
+export declare function lookupEnv(env: NodeJS.ProcessEnv, name: string): string | undefined;
+/** Escape a command path for cmd.exe. Port of cross-spawn's `escape.command`. */
+export declare function escapeCmdCommand(arg: string): string;
+/**
+ * Escape one argument for cmd.exe. Port of cross-spawn's `escape.argument`,
+ * whose algorithm is https://qntm.org/cmd with the backtracking removed.
+ */
+export declare function escapeCmdArgument(arg: string, doubleEscapeMetaChars?: boolean): string;
+/**
+ * Build the `cmd.exe /d /s /c "…"` invocation for a resolved, non-directly-
+ * executable target. Pure — the unit tests drive this from any host.
+ *
+ * @param commandFile Resolved absolute path of the target (e.g. the `.cmd` shim).
+ * @param args The caller's arguments, unescaped.
+ * @param comspec The interpreter, normally `%COMSPEC%`.
+ */
+export declare function buildCmdExeInvocation(commandFile: string, args: readonly string[], comspec?: string): Win32Invocation;
+/**
+ * Rewrite a bare command name into something Windows can actually spawn.
+ *
+ * Returns `undefined` when nothing needs rewriting — not win32, not a bare
+ * name, or not found on `PATH`. The last case is deliberate: letting `spawn`
+ * fail with `ENOENT` preserves the contract callers key their install hints on
+ * (see the module header).
+ */
+export declare function resolveWin32Command(cmd: string, args: readonly string[], ctx: Win32ResolveContext): Win32Invocation | undefined;

package/lib/utils/win32-command.js

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: MIT
+// Adapted from `cross-spawn` (node_modules/cross-spawn/lib/parse.js and
+// lib/util/escape.js, v7.0.6). Copyright (c) 2018 Made With MOXY Lda. MIT.
+// Modifications: rewritten as pure TypeScript with `platform`, `env` and the
+// filesystem probe INJECTED, so the Windows branch is unit-testable from a
+// Linux host (the same shape `utils/bin-shim.ts` uses), and narrowed to the one
+// case the CLI needs — resolving a bare command name before `spawn`.
+//
+// WHY THIS EXISTS
+//
+// `spawn('npm', …)` cannot work on Windows, and the failure is not a PATH
+// problem. `CreateProcess` appends only `.exe` when it searches PATH for a bare
+// name, and every npm-installed bin on Windows is a `.cmd` shim. Measured on
+// win32 x64 / Node 24.18.1:
+//
+//     spawn('npm',     ['--version'])  →  ENOENT   (.cmd is never tried)
+//     spawn('node',    ['--version'])  →  ok       (.exe is appended)
+//     spawn('npm.cmd', ['--version'])  →  EINVAL   (Node refuses a batch file)
+//
+// The EINVAL is Node's CVE-2024-27980 mitigation: a `.cmd`/`.bat` target has to
+// go through a command interpreter. So resolving the shim path is NOT enough —
+// it must be invoked as `cmd.exe /d /s /c "…"` with every argument escaped for
+// cmd's parser, which is what {@link buildCmdExeInvocation} does.
+//
+// That gap took out the whole orchestration layer, not one command: `gjsify
+// workspace`/`foreach`/`check` spawn `<pm> run <script>` per package and the
+// package manager is `npm` on every non-GJS host, so on Windows each one died
+// with `spawn npm ENOENT` before running a single script.
+//
+// WHY RESOLUTION HAPPENS HERE AND NOT IN cmd.exe
+//
+// Handing the bare name to `cmd.exe /c` would also find the `.cmd` — and would
+// destroy the ENOENT contract every caller depends on. A missing command would
+// come back as a generic exit 1 with an unparsable message instead of an
+// `ENOENT` error, and `SpawnToCompletionOptions.notFound` (the install hints)
+// plus `commands/tsc.ts`'s transparent fall back to upstream tsc when `gjs` is
+// absent both key on exactly that code. Resolving first keeps "not found" a
+// spawn-time error and routes only what really is a batch file through cmd.exe.
+/** Default when `PATHEXT` is unset — the extensions `CreateProcess` users expect. */
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+/** Only `.com`/`.exe` can be executed without an interpreter. Verbatim from cross-spawn. */
+const DIRECTLY_EXECUTABLE_RE = /\.(?:com|exe)$/i;
+/** A cmd-shim under `node_modules/.bin/` re-enters cmd.exe, so meta chars need escaping twice. */
+const CMD_SHIM_RE = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i;
+// See http://www.robvanderwoude.com/escapechars.php — verbatim from cross-spawn.
+const META_CHARS_RE = /([()\][%!^"`<>&|;, *?])/g;
+/**
+ * Read `name` from `env` case-insensitively.
+ *
+ * Windows environment variables are case-insensitive and `process.env` mirrors
+ * that, but a plain object handed in as `env` (which is what every spawn call
+ * site builds) does not — a child env carrying `Path` rather than `PATH` would
+ * otherwise silently resolve nothing.
+ */
+export function lookupEnv(env, name) {
+    const wanted = name.toLowerCase();
+    for (const key of Object.keys(env)) {
+        // A key present but explicitly `undefined` means NOT SET — `spawn`
+        // drops it from the child env. Returning it here would shadow a later
+        // spelling (`{ PATH: undefined, Path: 'C:\\bin' }`) and resolve nothing.
+        if (key.toLowerCase() === wanted && env[key] !== undefined)
+            return env[key];
+    }
+    return undefined;
+}
+/** Escape a command path for cmd.exe. Port of cross-spawn's `escape.command`. */
+export function escapeCmdCommand(arg) {
+    return arg.replace(META_CHARS_RE, '^$1');
+}
+/**
+ * Escape one argument for cmd.exe. Port of cross-spawn's `escape.argument`,
+ * whose algorithm is https://qntm.org/cmd with the backtracking removed.
+ */
+export function escapeCmdArgument(arg, doubleEscapeMetaChars = false) {
+    let out = `${arg}`;
+    // A run of backslashes before a double quote: double the run, escape the quote.
+    out = out.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+    // A run of backslashes at the end (about to precede the closing quote): double it.
+    out = out.replace(/(?=(\\+?)?)\1$/, '$1$1');
+    out = `"${out}"`;
+    out = out.replace(META_CHARS_RE, '^$1');
+    if (doubleEscapeMetaChars)
+        out = out.replace(META_CHARS_RE, '^$1');
+    return out;
+}
+/**
+ * Build the `cmd.exe /d /s /c "…"` invocation for a resolved, non-directly-
+ * executable target. Pure — the unit tests drive this from any host.
+ *
+ * @param commandFile Resolved absolute path of the target (e.g. the `.cmd` shim).
+ * @param args The caller's arguments, unescaped.
+ * @param comspec The interpreter, normally `%COMSPEC%`.
+ */
+export function buildCmdExeInvocation(commandFile, args, comspec = 'cmd.exe') {
+    // A cmd-shim under `node_modules/.bin/` is itself a batch file that re-invokes
+    // cmd.exe, so its meta chars are interpreted twice and must be escaped twice.
+    const doubleEscape = CMD_SHIM_RE.test(commandFile);
+    const line = [escapeCmdCommand(commandFile), ...args.map((a) => escapeCmdArgument(a, doubleEscape))].join(' ');
+    return { cmd: comspec, args: ['/d', '/s', '/c', `"${line}"`], windowsVerbatimArguments: true };
+}
+/** True when `cmd` is a bare name — no directory part and no extension. */
+function isBareName(cmd) {
+    return !cmd.includes('/') && !cmd.includes('\\') && !/\.[^.]+$/.test(cmd);
+}
+/**
+ * Find `cmd` on the child's `PATH`, trying each `PATHEXT` extension per
+ * directory — the order `CreateProcess` itself uses.
+ */
+function lookupOnPath(cmd, ctx) {
+    const dirs = (lookupEnv(ctx.env, 'PATH') ?? '').split(';').filter(Boolean);
+    const exts = (lookupEnv(ctx.env, 'PATHEXT') ?? DEFAULT_PATHEXT).split(';').filter(Boolean);
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const candidate = ctx.join(dir, cmd + ext);
+            if (ctx.exists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Rewrite a bare command name into something Windows can actually spawn.
+ *
+ * Returns `undefined` when nothing needs rewriting — not win32, not a bare
+ * name, or not found on `PATH`. The last case is deliberate: letting `spawn`
+ * fail with `ENOENT` preserves the contract callers key their install hints on
+ * (see the module header).
+ */
+export function resolveWin32Command(cmd, args, ctx) {
+    if (ctx.platform !== 'win32' || !isBareName(cmd))
+        return undefined;
+    const resolved = lookupOnPath(cmd, ctx);
+    if (!resolved)
+        return undefined;
+    // `.exe`/`.com` run without an interpreter; spawning the resolved absolute
+    // path skips a second PATH search and cannot be shadowed in between.
+    if (DIRECTLY_EXECUTABLE_RE.test(resolved))
+        return { cmd: resolved, args: [...args] };
+    return buildCmdExeInvocation(resolved, args, lookupEnv(ctx.env, 'COMSPEC') ?? 'cmd.exe');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.26.1",
+    "version": "0.27.1",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -109,13 +109,12 @@
         "showcases.json"
     ],
     "scripts": {
-        "clear": "rm -rf lib dist tsconfig.tsbuildinfo || exit 0",
+        "clear": "gjsify clear lib dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
         "start": "node lib/index.js",
-        "build": "tsc && mkdir -p lib/templates/flatpak && cp -L src/templates/install.mjs.tmpl lib/templates/install.mjs.tmpl && cp src/templates/flatpak/*.tmpl lib/templates/flatpak/ && cp src/templates/oxlintrc.json.tmpl lib/templates/oxlintrc.json.tmpl && cp src/templates/oxfmtrc.tmpl lib/templates/oxfmtrc.tmpl && gjsify run chmod",
+        "build": "gjsify tsc && node scripts/build-assets.mjs",
         "build:gjs-bundle": "node lib/index.js build src/index.ts --app gjs --outfile dist/cli.gjs.mjs --shebang",
         "build:affected-bundle": "node lib/index.js build src/affected-entry.ts --app gjs --outfile dist/affected.gjs.mjs",
-        "chmod": "chmod +x ./lib/index.js",
         "build:test:node": "node lib/index.js build src/test.mts --app node --outfile dist/test.node.mjs",
         "test:node": "node dist/test.node.mjs",
         "test:bun": "bun dist/test.node.mjs",
@@ -130,19 +129,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.26.1",
-        "@gjsify/create-app": "^0.26.1",
-        "@gjsify/node-globals": "^0.26.1",
-        "@gjsify/node-polyfills": "^0.26.1",
-        "@gjsify/npm-registry": "^0.26.1",
-        "@gjsify/resolve-npm": "^0.26.1",
-        "@gjsify/rolldown-plugin-gjsify": "^0.26.1",
-        "@gjsify/rolldown-plugin-pnp": "^0.26.1",
-        "@gjsify/semver": "^0.26.1",
-        "@gjsify/tar": "^0.26.1",
-        "@gjsify/tsc": "^0.26.1",
-        "@gjsify/web-polyfills": "^0.26.1",
-        "@gjsify/workspace": "^0.26.1",
+        "@gjsify/buffer": "^0.27.1",
+        "@gjsify/create-app": "^0.27.1",
+        "@gjsify/node-globals": "^0.27.1",
+        "@gjsify/node-polyfills": "^0.27.1",
+        "@gjsify/npm-registry": "^0.27.1",
+        "@gjsify/resolve-npm": "^0.27.1",
+        "@gjsify/rolldown-plugin-gjsify": "^0.27.1",
+        "@gjsify/rolldown-plugin-pnp": "^0.27.1",
+        "@gjsify/semver": "^0.27.1",
+        "@gjsify/tar": "^0.27.1",
+        "@gjsify/tsc": "^0.27.1",
+        "@gjsify/web-polyfills": "^0.27.1",
+        "@gjsify/workspace": "^0.27.1",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -150,13 +149,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.26.1",
+        "@gjsify/unit": "^0.27.1",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.26.1",
-        "@gjsify/rolldown-native": "^0.26.1"
+        "@gjsify/oxfmt-native": "^0.27.1",
+        "@gjsify/rolldown-native": "^0.27.1"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {