@gjsify/cli 0.22.0 → 0.24.1

package/lib/utils/spawn.d.ts

@@ -0,0 +1,82 @@
+import type { ChildProcess } from 'node:child_process';
+/**
+ * What the calling command does once this spawn settles.
+ *
+ * - `'exit'` — the command terminates the process itself (`process.exit(…)`,
+ *   `forceExit(…)`, …). The armed GJS main loop is quit by that exit, so the
+ *   streaming async `spawn` is safe on both hosts.
+ * - `'return'` — the command returns normally and lets the CLI unwind. Under
+ *   GJS that MUST NOT leave a main loop armed, so the child is run on the
+ *   blocking `spawnSync` path instead.
+ *
+ * See the module header for the full rationale.
+ */
+export type SpawnCompletionContract = 'exit' | 'return';
+export interface SpawnToCompletionOptions {
+    /** The caller's teardown contract. Required — see {@link SpawnCompletionContract}. */
+    completion: SpawnCompletionContract;
+    /** Working directory for the child. Defaults to the parent's. */
+    cwd?: string;
+    /**
+     * Environment for the child. Omit to inherit the parent's environment
+     * verbatim (what `spawn` does with no `env`).
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Seed `FORCE_COLOR=1` (on top of `env` ?? `process.env`) unless the user
+     * explicitly set `FORCE_COLOR` or `NO_COLOR`, so tools that key on
+     * `process.stdout.isTTY` (chalk, picocolors, …) still emit ANSI when their
+     * stdout is a pipe. Mirrors yarn / npm. Default `false`.
+     */
+    color?: boolean;
+    /**
+     * `'inherit'` (default) forwards the parent's stdio. `'pipe'` gives the
+     * caller `child.stdout` / `child.stderr` via {@link onSpawn} — only
+     * meaningful together with `completion: 'exit'` (see {@link onSpawn}).
+     */
+    stdio?: 'inherit' | 'pipe';
+    /**
+     * Invoked synchronously with the live `ChildProcess` right after a
+     * successful async spawn — the seam for kill-tracking registries and for
+     * wiring piped output forwarders.
+     *
+     * ONLY fires on the streaming path: the blocking `spawnSync` path has no
+     * `ChildProcess` handle at all. A site that needs the handle must
+     * therefore declare `completion: 'exit'`.
+     */
+    onSpawn?: (child: ChildProcess) => void;
+    /**
+     * Map an `ENOENT` spawn failure (command not on PATH) to a domain error
+     * carrying an install hint. Other spawn errors are rejected as-is.
+     */
+    notFound?: (err: NodeJS.ErrnoException) => Error;
+    /**
+     * Capture ceiling for the blocking path. Defaults to 64 MiB — a
+     * full-workspace lint with many findings runs well past Node's 1 MB
+     * default, and an overflow would silently truncate diagnostics.
+     */
+    maxBuffer?: number;
+}
+export interface SpawnCompletion {
+    /** The child's exit code, or `null` when it was terminated by a signal. */
+    code: number | null;
+    /** The terminating signal, or `null` on a normal exit. */
+    signal: NodeJS.Signals | null;
+}
+/**
+ * Run `cmd args…` to completion and resolve with its exit code and signal.
+ *
+ * Resolves for ANY child exit — a non-zero code is data, not an error, so each
+ * call site keeps its own failure message. Rejects only when the child could
+ * not be started at all (mapped through {@link SpawnToCompletionOptions.notFound}
+ * for ENOENT).
+ *
+ * Picks the streaming async path or the blocking captured path per the GJS
+ * teardown contract documented at the top of this file.
+ */
+export declare function spawnToCompletion(cmd: string, args: readonly string[], opts: SpawnToCompletionOptions): Promise<SpawnCompletion>;
+/**
+ * Format the "child failed" suffix the way the call sites report it: an exit
+ * code when the child exited, the signal name when it was killed.
+ */
+export declare function describeExit(result: SpawnCompletion): string;

package/lib/utils/spawn.js

@@ -0,0 +1,139 @@
+// One `spawn` → `Promise<{ code, signal }>` wrapper for the whole CLI.
+//
+// Six near-identical wrappers used to live in `commands/{foreach,check,
+// workspace,install}.ts`, `flatpak/build.ts` and `utils/oxc-resolve.ts`. They
+// diverged on the completion event (`close` vs `exit`), whether an ENOENT
+// spawn failure got a human hint, whether `FORCE_COLOR` was seeded — and, the
+// dangerous one, on how they handled the GJS teardown contract below.
+//
+// ## The GJS teardown contract — why this helper has a host branch
+//
+// `@gjsify/child_process`'s ASYNC `spawn()` calls `ensureMainLoop()`
+// (`@gjsify/utils`) so the `Gio.Subprocess` `wait_async` exit callback has a
+// running GLib main context to be dispatched on. `ensureMainLoop()` arms a
+// GJS **main-loop hook** (`GLib.MainLoop.runAsync()` → `setMainLoopHook`), and
+// GJS's `eval_module` runs that hook AFTER the entry module's top-level await
+// settles — entering a blocking `g_main_loop_run()` that nothing ever quits.
+// GJS has no atexit hook, so the only thing that tears it back down is
+// `process.exit()` (whose `exitProcess` idle-schedules `quitMainLoop()` +
+// `imports.system.exit()`).
+//
+// Consequence, measured on gjs 1.88 against the committed `dist/cli.gjs.mjs`:
+// a command that async-spawns a child and then RETURNS NORMALLY parks at 0%
+// CPU **after** the child has already exited and been reaped. The symptom —
+// a live parent with no children, blocked in `poll`, `SNl` — is *identical*
+// to a lost exit callback, which is how it was previously misdiagnosed as
+// "the async `spawn`'s exit/close event is not delivered under the bundle".
+// It IS delivered: instrumenting the exit handler shows it firing with the
+// right code; the parent then parks in the armed loop on its way out.
+//
+// So the branch is NOT "GJS ⇒ spawnSync". It is exactly this:
+//
+//   | host | caller ends with       | path                                |
+//   |------|------------------------|-------------------------------------|
+//   | Node | anything               | async `spawn` (streaming)           |
+//   | GJS  | `process.exit(…)`      | async `spawn` (streaming)           |
+//   | GJS  | a normal `return`      | blocking `spawnSync` (captured)     |
+//
+// which is why `gjsify foreach` / `workspace` / `check` and `runGjsBundle` run
+// hundreds of async-spawned children under GJS without ever hanging: every one
+// of them ends its handler with `process.exit(…)`. `gjsify lint` did not, and
+// that is the hang the `spawnSync` branch in `oxc-resolve.ts` was papering
+// over.
+//
+// Callers therefore declare their teardown contract via the REQUIRED
+// {@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.
+import { spawn, spawnSync } from 'node:child_process';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+/** Default capture ceiling on the blocking path — 64 MiB. */
+const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;
+/**
+ * Build the child's environment: `undefined` (inherit) unless the caller
+ * passed one or asked for colour seeding.
+ */
+function resolveEnv(opts) {
+    if (!opts.color)
+        return opts.env;
+    const base = opts.env ?? process.env;
+    const seed = process.env.FORCE_COLOR !== undefined || process.env.NO_COLOR !== undefined ? {} : { FORCE_COLOR: '1' };
+    return { ...base, ...seed };
+}
+/** 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)
+        return opts.notFound(err);
+    return err;
+}
+/**
+ * Whether this call has to run on the blocking path.
+ *
+ * Only true under GJS for a caller that returns normally — see the module
+ * header's table. On Node the async path is always correct (and keeps the
+ * event loop free), and under GJS a caller that exits the process quits the
+ * armed main loop itself.
+ */
+function mustBlock(opts) {
+    return isGjs() && opts.completion === 'return';
+}
+/**
+ * Run `cmd args…` to completion and resolve with its exit code and signal.
+ *
+ * Resolves for ANY child exit — a non-zero code is data, not an error, so each
+ * call site keeps its own failure message. Rejects only when the child could
+ * not be started at all (mapped through {@link SpawnToCompletionOptions.notFound}
+ * for ENOENT).
+ *
+ * Picks the streaming async path or the blocking captured path per the GJS
+ * teardown contract documented at the top of this file.
+ */
+export function spawnToCompletion(cmd, args, opts) {
+    const env = resolveEnv(opts);
+    if (mustBlock(opts)) {
+        // `'inherit'` is NOT forwarded through `@gjsify/child_process`'s GJS
+        // spawnSync path (it drives a private main context via
+        // `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], {
+            stdio: ['inherit', 'pipe', 'pipe'],
+            cwd: opts.cwd,
+            env,
+            maxBuffer: opts.maxBuffer ?? DEFAULT_MAX_BUFFER,
+        });
+        if (r.error)
+            return Promise.reject(mapSpawnError(r.error, opts));
+        if (r.stdout && r.stdout.length > 0)
+            process.stdout.write(r.stdout);
+        if (r.stderr && r.stderr.length > 0)
+            process.stderr.write(r.stderr);
+        return Promise.resolve({ code: r.status, signal: r.signal ?? null });
+    }
+    return new Promise((resolvePromise, reject) => {
+        const spawnOpts = {
+            cwd: opts.cwd,
+            stdio: opts.stdio === 'pipe' ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+        };
+        if (env)
+            spawnOpts.env = env;
+        const child = spawn(cmd, [...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
+        // back to back, so this is a strict superset of the old `exit` sites.
+        child.on('close', (code, signal) => {
+            resolvePromise({ code, signal });
+        });
+        child.on('error', (err) => {
+            reject(mapSpawnError(err, opts));
+        });
+    });
+}
+/**
+ * Format the "child failed" suffix the way the call sites report it: an exit
+ * code when the child exited, the signal name when it was killed.
+ */
+export function describeExit(result) {
+    return result.signal !== null ? `signal ${result.signal}` : `code ${result.code}`;
+}

package/lib/utils/stdin.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read the whole of stdin as UTF-8. Works on Node and under the GJS bundle.
+ *
+ * Branches on WHICH RUNTIME CAN WORK, not on which capability is present. The
+ * distinction matters because the two branches are not interchangeable:
+ * `readFileSync(0)` is correct on Node/Bun/Deno and can NEVER work under GJS —
+ * `@gjsify/fs` has no numeric-fd path, so the `0` is coerced to a relative
+ * PATH and the call opens `./0`. A GJS run that reaches that line is already
+ * lost, so using it as GJS's fallback only converts a clear failure into
+ * `ENOENT … read '0'`, which is what a capability probe returning a false
+ * negative did.
+ *
+ * So: the presence of `imports.gi` decides. On GJS both GJS readers are tried
+ * and a failure THROWS with what was attempted; the Node reader is never
+ * reached. Off GJS there is no gi namespace and `readFileSync(0)` is the only
+ * and correct answer.
+ */
+export declare function readStdinText(): string;
+/**
+ * Read stdin and split it into trimmed, non-empty lines. Accepts LF and CRLF
+ * so a `git diff --name-only` piped from any host works unchanged.
+ */
+export declare function readStdinLines(): string[];
+/** Pure line-splitter behind {@link readStdinLines} — unit-testable without a pipe. */
+export declare function splitStdinLines(text: string): string[];

package/lib/utils/stdin.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: MIT
+// Read ALL of stdin, on Node AND inside the committed GJS bundles.
+//
+// `readFileSync(0, 'utf-8')` is the Node idiom for "slurp stdin", and it is
+// what `gjsify affected --changed-from-stdin` used. It does NOT survive the
+// GJS bundle: `@gjsify/fs` has no numeric-file-descriptor path, so the `0` is
+// coerced to a PATH and the call opens the relative file `./0` — every GJS
+// caller died with
+//
+//     Error: ENOENT: … read '0'   (readStdinLines → readFileSync)
+//
+// which silently disabled the ONE fixture-driven entry point AGENTS.md
+// documents for testing the CI classifier (`--changed-from-stdin`).
+//
+// Under GJS we therefore read fd 0 through `GioUnix.InputStream`. Two
+// deliberate choices:
+//
+//   - `globalThis.imports.gi.GioUnix` rather than a `gi://GioUnix` import.
+//     `packages/infra/cli/lib/**` is ALSO the Node entry point of
+//     `@gjsify/cli` (`bin: lib/index.js`); a static `gi://` import anywhere
+//     reachable from it breaks `gjsify` on Node, and a dynamic one would need
+//     an `@girs/giounix-2.0` type dependency the CLI does not otherwise have.
+//     The legacy `imports.gi` form is the sanctioned GJS-bootstrap escape
+//     hatch (AGENTS.md "Reading globals", exception 4) and adds NO new typelib
+//     to the classifier bundle — `gi://GioUnix?version=2.0` is already in its
+//     import graph via `@gjsify/fs`.
+//   - a synchronous read. The callers are CLI argument-parsing paths that run
+//     before any main loop exists, and the async `process.stdin` route carries
+//     the documented resume/pause races (see `utils/prompt.ts`).
+import { readFileSync } from 'node:fs';
+const CHUNK = 64 * 1024;
+/** Read fd 0 to EOF under GJS via GioUnix (no `@gjsify/fs` fd support needed). */
+function readStdinTextGioUnix() {
+    const gi = giNamespace();
+    const GioUnix = gi?.GioUnix;
+    if (typeof GioUnix?.InputStream !== 'function') {
+        throw new Error('GioUnix.InputStream is unavailable');
+    }
+    const stream = new GioUnix.InputStream({ fd: 0, close_fd: false });
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const bytes = stream.read_bytes(CHUNK, null);
+        if (bytes.get_size() === 0)
+            break;
+        const arr = bytes.toArray();
+        chunks.push(arr);
+        total += arr.length;
+    }
+    if (total === 0)
+        return '';
+    const buf = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        buf.set(c, offset);
+        offset += c.length;
+    }
+    return new TextDecoder().decode(buf);
+}
+/**
+ * Read stdin under GJS through Gio ALONE, without GioUnix.
+ *
+ * `/dev/stdin` is fd 0 by another name, and `Gio` is present in every bundle
+ * that can reach this code at all. This exists because the GioUnix route has
+ * been observed to be unavailable on a host where it should have worked, and a
+ * second independent mechanism is cheaper than another round of guessing.
+ */
+function readStdinTextGioFile() {
+    const gi = giNamespace();
+    const Gio = gi?.Gio;
+    if (!Gio?.File)
+        throw new Error('Gio.File is unavailable');
+    const [ok, contents] = Gio.File.new_for_path('/dev/stdin').load_contents(null);
+    if (!ok)
+        throw new Error('Gio.File.load_contents("/dev/stdin") returned false');
+    return new TextDecoder().decode(contents);
+}
+/** The GJS `imports.gi` namespace, or `undefined` when not running on GJS. */
+function giNamespace() {
+    try {
+        return globalThis.imports?.gi;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the whole of stdin as UTF-8. Works on Node and under the GJS bundle.
+ *
+ * Branches on WHICH RUNTIME CAN WORK, not on which capability is present. The
+ * distinction matters because the two branches are not interchangeable:
+ * `readFileSync(0)` is correct on Node/Bun/Deno and can NEVER work under GJS —
+ * `@gjsify/fs` has no numeric-fd path, so the `0` is coerced to a relative
+ * PATH and the call opens `./0`. A GJS run that reaches that line is already
+ * lost, so using it as GJS's fallback only converts a clear failure into
+ * `ENOENT … read '0'`, which is what a capability probe returning a false
+ * negative did.
+ *
+ * So: the presence of `imports.gi` decides. On GJS both GJS readers are tried
+ * and a failure THROWS with what was attempted; the Node reader is never
+ * reached. Off GJS there is no gi namespace and `readFileSync(0)` is the only
+ * and correct answer.
+ */
+export function readStdinText() {
+    if (!giNamespace())
+        return readFileSync(0, 'utf-8');
+    const attempts = [];
+    for (const read of [readStdinTextGioUnix, readStdinTextGioFile]) {
+        try {
+            return read();
+        }
+        catch (err) {
+            attempts.push(`${read.name}: ${err.message}`);
+        }
+    }
+    throw new Error(`gjsify: cannot read stdin under GJS. Tried ${attempts.join('; ')}. ` +
+        'Pass the input as an argument instead (e.g. --base <ref> rather than --changed-from-stdin).');
+}
+/**
+ * Read stdin and split it into trimmed, non-empty lines. Accepts LF and CRLF
+ * so a `git diff --name-only` piped from any host works unchanged.
+ */
+export function readStdinLines() {
+    return splitStdinLines(readStdinText());
+}
+/** Pure line-splitter behind {@link readStdinLines} — unit-testable without a pipe. */
+export function splitStdinLines(text) {
+    return text
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.22.0",
+    "version": "0.24.1",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -96,7 +96,12 @@
                 }
             ]
         },
-        "tier": 1
+        "tier": 1,
+        "defineFromPackageJson": {
+            "__PACKAGE_VERSION__": {
+                "field": "version"
+            }
+        }
     },
     "files": [
         "lib",
@@ -125,19 +130,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.22.0",
-        "@gjsify/create-app": "^0.22.0",
-        "@gjsify/node-globals": "^0.22.0",
-        "@gjsify/node-polyfills": "^0.22.0",
-        "@gjsify/npm-registry": "^0.22.0",
-        "@gjsify/resolve-npm": "^0.22.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.22.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.22.0",
-        "@gjsify/semver": "^0.22.0",
-        "@gjsify/tar": "^0.22.0",
-        "@gjsify/tsc": "^0.22.0",
-        "@gjsify/web-polyfills": "^0.22.0",
-        "@gjsify/workspace": "^0.22.0",
+        "@gjsify/buffer": "^0.24.1",
+        "@gjsify/create-app": "^0.24.1",
+        "@gjsify/node-globals": "^0.24.1",
+        "@gjsify/node-polyfills": "^0.24.1",
+        "@gjsify/npm-registry": "^0.24.1",
+        "@gjsify/resolve-npm": "^0.24.1",
+        "@gjsify/rolldown-plugin-gjsify": "^0.24.1",
+        "@gjsify/rolldown-plugin-pnp": "^0.24.1",
+        "@gjsify/semver": "^0.24.1",
+        "@gjsify/tar": "^0.24.1",
+        "@gjsify/tsc": "^0.24.1",
+        "@gjsify/web-polyfills": "^0.24.1",
+        "@gjsify/workspace": "^0.24.1",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -145,13 +150,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.22.0",
+        "@gjsify/unit": "^0.24.1",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.22.0",
-        "@gjsify/rolldown-native": "^0.22.0"
+        "@gjsify/oxfmt-native": "^0.24.1",
+        "@gjsify/rolldown-native": "^0.24.1"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {