@gjsify/cli 0.22.0 → 0.23.0

package/lib/utils/oxc-resolve.js

@@ -48,12 +48,12 @@
 // (tracked in STATUS.md Open TODOs).
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { findWorkspaceRoot } from './workspace-root.js';
 import { resolveNpmPackage } from './resolve-npm-package.js';
 import { nodeBinary } from './run-node.js';
+import { spawnToCompletion } from './spawn.js';
 import { isGjs, gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
 /**
  * Map Node.js `process.platform` + `arch` (+ musl on Linux) to the
@@ -298,6 +298,14 @@ export async function runOxc(tool, args, opts = {}) {
  * launcher as its first positional (yargs prints top-level help) and the parent
  * hangs waiting on a child that never does the intended work. `nodeBinary()`
  * resolves to PATH `node` under GJS, so the launcher runs on Node as required.
+ *
+ * `completion: 'return'`: `lint` / `format` / `fix` hand the tool's exit code
+ * to `setOxcExitCode`, which deliberately does NOT terminate the process on a
+ * clean run — so under GJS this must take `spawnToCompletion`'s blocking path
+ * (see `utils/spawn.ts`; the async one would leave the main loop `spawn()`
+ * arms parked at 0% CPU on the way out). That path also captures and re-emits
+ * the tool's stdout/stderr with a raised `maxBuffer`, which is exactly what a
+ * full-workspace lint needs.
  */
 function spawnOxcLauncher(tool, args, opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
@@ -306,61 +314,16 @@ function spawnOxcLauncher(tool, args, opts = {}) {
     if (opts.verbose) {
         console.log(`[gjsify oxc] ${node} ${launcher} ${args.join(' ')}`);
     }
-    // Under the GJS bundle the ASYNC spawn's exit/close event is never delivered
-    // back to JS: the child runs, streams its output, and exits (reaped, no
-    // zombie), but the `Gio.Subprocess` `wait_async` callback that emits
-    // `exit`/`close` does not fire, so the parent's await hangs at 0% CPU
-    // forever (the process sits in `SNl`). `spawnSync` uses the synchronous
-    // `communicate()` path instead — no async callback to lose — so it
-    // completes reliably. It blocks, which is exactly right for a CLI leaf
-    // command that just runs the tool to completion. On Node the async spawn is
-    // fine (and keeps the event loop free), so it is kept there.
-    if (isGjs()) {
-        // Capture stdout/stderr (`'inherit'` is not forwarded through the GJS
-        // spawnSync path — the tool's diagnostics would be silently lost), then
-        // re-emit them so oxlint/oxfmt's own output still reaches the user.
-        // maxBuffer generous: a full-workspace lint with many findings can emit
-        // well past the 1 MB Node default; overflow would truncate diagnostics.
-        const r = spawnSync(node, [launcher, ...args], {
-            stdio: ['inherit', 'pipe', 'pipe'],
-            cwd,
-            maxBuffer: 64 * 1024 * 1024,
-        });
-        if (r.error) {
-            const code = r.error.code;
-            if (code === 'ENOENT')
-                return Promise.reject(new OxcNotFoundError(tool, cwd));
-            return Promise.reject(r.error);
-        }
-        if (r.stdout && r.stdout.length)
-            process.stdout.write(r.stdout);
-        if (r.stderr && r.stderr.length)
-            process.stderr.write(r.stderr);
-        if (r.signal) {
-            console.error(`[gjsify oxc] ${tool} terminated by signal ${r.signal}`);
-            return Promise.resolve(1);
+    return spawnToCompletion(node, [launcher, ...args], {
+        completion: 'return',
+        cwd,
+        notFound: () => new OxcNotFoundError(tool, cwd),
+    }).then(({ code, signal }) => {
+        if (signal !== null) {
+            console.error(`[gjsify oxc] ${tool} terminated by signal ${signal}`);
+            return 1;
         }
-        return Promise.resolve(r.status ?? 0);
-    }
-    return new Promise((res, rej) => {
-        const spawnOpts = { stdio: 'inherit', cwd };
-        const child = spawn(node, [launcher, ...args], spawnOpts);
-        child.on('error', (err) => {
-            if (err.code === 'ENOENT') {
-                rej(new OxcNotFoundError(tool, cwd));
-            }
-            else {
-                rej(err);
-            }
-        });
-        child.on('exit', (code, signal) => {
-            if (signal) {
-                console.error(`[gjsify oxc] ${tool} terminated by signal ${signal}`);
-                res(1);
-                return;
-            }
-            res(code ?? 0);
-        });
+        return code ?? 0;
     });
 }
 /** Convenience wrappers. */

package/lib/utils/publish-headers.d.ts

@@ -24,9 +24,8 @@ export interface PublishHeaderOptions {
      */
     authorization?: string;
     /**
-     * npm user-agent. Defaults to an npm-CLI-shaped string. The registry does
-     * not validate the exact value, but a real UA is what npm sends; the dead
-     * `gjsify-install/0.3.7` placeholder is not used here.
+     * npm user-agent. Defaults to an npm-CLI-shaped string carrying this CLI's
+     * real version — never a hard-coded placeholder (see {@link cliVersion}).
      */
     userAgent?: string;
 }

package/lib/utils/publish-headers.js

@@ -27,8 +27,12 @@
 //     literal `@`. (gjsify's URL encoding already matches this — it was never
 //     the bug.)
 //
-// This module is pure (no I/O, no `gi://`) so it is unit-testable on both Node
-// and GJS without dragging in the runtime fetch/Soup stack.
+// This module pulls in no `gi://` and no runtime fetch/Soup stack, so it is
+// unit-testable on both Node and GJS. Its one filesystem touch is the
+// manifest walk backing the user-agent version — see `cliVersion()`.
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { buildHeaders } from '@gjsify/npm-registry';
 /**
  * Percent-encode a package name for the publish PUT path, matching
@@ -85,6 +89,63 @@ export function buildPublishHeaders(url, opts) {
         headers['authorization'] = opts.authorization;
     return headers;
 }
+/**
+ * This CLI's own `package.json#version`, memoised. Two layers, because
+ * `@gjsify/cli` is a DUAL-ENTRY package and neither layer covers both entries:
+ *
+ * 1. **`__PACKAGE_VERSION__`** — the compile-time define
+ *    (`package.json#gjsify.defineFromPackageJson`), the mechanism
+ *    `@gjsify/npm-registry` uses for the same stale-UA bug. Zero I/O, but the
+ *    bundler only ever writes `dist/cli.gjs.mjs`: the npm-wired Node bin under
+ *    `lib/` is emitted by plain `tsc`, which knows nothing about defines. A
+ *    define alone would therefore have left the Node entry — the one `npm
+ *    install @gjsify/cli` actually runs — on a permanent placeholder.
+ *
+ * 2. **an upward manifest walk** for the nearest `package.json` naming
+ *    `@gjsify/cli`, covering `lib/`. Deliberately NOT a fixed
+ *    `new URL('../../package.json', import.meta.url)` read: that resolves
+ *    correctly from `lib/utils/` but points one directory too high from
+ *    `dist/`, and the build-time `inlineStaticReads` pass that would have
+ *    frozen it is scoped to `node_modules` paths, so first-party source never
+ *    gets it. The walk is depth-independent and so works from `src/`, `lib/`,
+ *    `dist/`, and from an installed `node_modules/@gjsify/cli/**` alike.
+ *
+ * `GJSIFY_CLI_PACKAGE_JSON` overrides both, matching `self-update.ts`.
+ */
+let cachedCliVersion;
+function cliVersion() {
+    if (cachedCliVersion !== undefined)
+        return cachedCliVersion;
+    cachedCliVersion =
+        (typeof __PACKAGE_VERSION__ === 'string' ? __PACKAGE_VERSION__ : '') || walkForCliVersion() || 'unknown';
+    return cachedCliVersion;
+}
+/** Nearest ancestor `package.json` whose `name` is `@gjsify/cli`; '' when none. */
+function walkForCliVersion() {
+    const override = globalThis.process?.env?.['GJSIFY_CLI_PACKAGE_JSON'];
+    let dir;
+    try {
+        dir = override ? dirname(override) : dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return '';
+    }
+    for (let i = 0; i < 12; i++) {
+        try {
+            const pkg = JSON.parse(readFileSync(`${dir}/package.json`, 'utf8'));
+            if (pkg.name === '@gjsify/cli' && typeof pkg.version === 'string')
+                return pkg.version;
+        }
+        catch {
+            /* no manifest here (or unreadable) — keep climbing */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return '';
+}
 /**
  * npm-CLI-shaped user-agent. Format mirrors npm-registry-fetch's
  * `default-opts.js` (`npm@<v>/node@<v>+<arch> (<platform>)`); we substitute the
@@ -95,5 +156,5 @@ function defaultUserAgent() {
     const proc = globalThis.process;
     const arch = proc?.arch ?? 'x64';
     const platform = proc?.platform ?? 'linux';
-    return `gjsify-publish/0.5.0 (${platform} ${arch})`;
+    return `gjsify-publish/${cliVersion()} (${platform} ${arch})`;
 }

package/lib/utils/publishable-packages.d.ts

@@ -0,0 +1,22 @@
+import type { Workspace } from '@gjsify/workspace';
+/**
+ * Package-group directories holding publishable packages that are NOT root
+ * workspaces. Add one here the moment a new non-workspace publishable group
+ * appears — this list is the only thing standing between such a package and a
+ * silently broken first release.
+ */
+export declare const NON_WORKSPACE_PUBLISHABLE_DIRS: readonly [readonly ["packages", "node-gi"], readonly ["packages", "napi"]];
+/**
+ * Publishable packages in {@link NON_WORKSPACE_PUBLISHABLE_DIRS}, shaped as
+ * `Workspace` entries so callers can treat them like any other package.
+ *
+ * Best-effort by design: a missing directory or an unreadable/malformed
+ * manifest is skipped rather than thrown, because this runs inside sweeps whose
+ * value is covering everything they can reach.
+ */
+export declare function discoverNonWorkspacePublishables(cwd: string): Workspace[];
+/**
+ * Merge workspace-discovered packages with the non-workspace publishables,
+ * deduped by name. A real workspace always wins over a scanned directory.
+ */
+export declare function mergePublishables(workspaces: Workspace[], cwd: string): Workspace[];

package/lib/utils/publishable-packages.js

@@ -0,0 +1,93 @@
+// Publishable-package discovery shared by `gjsify trust` and `gjsify onboard`.
+//
+// `discoverWorkspaces` only sees ROOT WORKSPACES. Some publishable packages
+// deliberately are not: each is an independent native engine with its own CI
+// workflow, kept out of the workspace graph so a full `gjsify foreach` never
+// tries to build it. They still publish through `release.yml`, so every sweep
+// that reasons about "what do we publish" has to include them — otherwise the
+// sweep silently under-reports and the package's first release fails the OIDC
+// exchange with `404 — package not found`.
+//
+// That is not hypothetical: `gjsify onboard` reported 127 packages "already
+// done" on 2026-07-26 while `@gjsify/napi` was neither in the list nor
+// published at all, because only `packages/node-gi/*` was carved out.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Package-group directories holding publishable packages that are NOT root
+ * workspaces. Add one here the moment a new non-workspace publishable group
+ * appears — this list is the only thing standing between such a package and a
+ * silently broken first release.
+ */
+export const NON_WORKSPACE_PUBLISHABLE_DIRS = [
+    ['packages', 'node-gi'], // @gjsify/node-gi + the @gjsify/gtk-runtime-* bundles
+    ['packages', 'napi'], // @gjsify/napi (the N-API host in GJS, own napi.yml)
+];
+/**
+ * Publishable packages in {@link NON_WORKSPACE_PUBLISHABLE_DIRS}, shaped as
+ * `Workspace` entries so callers can treat them like any other package.
+ *
+ * Best-effort by design: a missing directory or an unreadable/malformed
+ * manifest is skipped rather than thrown, because this runs inside sweeps whose
+ * value is covering everything they can reach.
+ */
+export function discoverNonWorkspacePublishables(cwd) {
+    // Walk up to the repo root. Anchored on the FIRST configured group rather
+    // than on `packages/` itself, which also exists inside individual packages.
+    let root = cwd;
+    const anchor = NON_WORKSPACE_PUBLISHABLE_DIRS[0];
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(root, ...anchor)))
+            break;
+        const parent = dirname(root);
+        if (parent === root)
+            return [];
+        root = parent;
+    }
+    const out = [];
+    for (const group of NON_WORKSPACE_PUBLISHABLE_DIRS) {
+        const base = join(root, ...group);
+        if (!existsSync(base))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(base, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const location = join(base, entry.name);
+            const pkgPath = join(location, 'package.json');
+            if (!existsSync(pkgPath))
+                continue;
+            try {
+                const manifest = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                if (!manifest || typeof manifest.name !== 'string' || manifest.name.length === 0)
+                    continue;
+                out.push({
+                    location,
+                    relativeLocation: join(...group, entry.name),
+                    name: manifest.name,
+                    version: typeof manifest.version === 'string' ? manifest.version : '0.0.0',
+                    manifest,
+                    private: manifest.private === true,
+                });
+            }
+            catch {
+                /* unreadable / malformed — skip */
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Merge workspace-discovered packages with the non-workspace publishables,
+ * deduped by name. A real workspace always wins over a scanned directory.
+ */
+export function mergePublishables(workspaces, cwd) {
+    const seen = new Set(workspaces.map((ws) => ws.name));
+    return [...workspaces, ...discoverNonWorkspacePublishables(cwd).filter((ws) => !seen.has(ws.name))];
+}

package/lib/utils/run-gjs.d.ts

@@ -1,14 +1,13 @@
+import { type NativeEnv } from './detect-native-packages.js';
 /**
- * Pure env computation for a given bundle. Returns the LD_LIBRARY_PATH /
- * GI_TYPELIB_PATH values that {@link runGjsBundle} would inject into the
+ * Pure env computation for a given bundle. Returns the typelib +
+ * shared-library search paths that {@link runGjsBundle} would inject into the
  * spawned `gjs` process, plus the formatted env-prefix string used for the
- * `$ …` echo.
+ * `$ …` echo. Which library variable is set is host-dependent
+ * (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see `buildNativeEnv`.
  */
 export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: string): {
-    env: {
-        LD_LIBRARY_PATH: string;
-        GI_TYPELIB_PATH: string;
-    };
+    env: NativeEnv;
     envPrefix: string;
 };
 /**

package/lib/utils/run-gjs.js

@@ -20,10 +20,11 @@ import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { detectNativePackages, buildNativeEnv } from './detect-native-packages.js';
 /**
- * Pure env computation for a given bundle. Returns the LD_LIBRARY_PATH /
- * GI_TYPELIB_PATH values that {@link runGjsBundle} would inject into the
+ * Pure env computation for a given bundle. Returns the typelib +
+ * shared-library search paths that {@link runGjsBundle} would inject into the
  * spawned `gjs` process, plus the formatted env-prefix string used for the
- * `$ …` echo.
+ * `$ …` echo. Which library variable is set is host-dependent
+ * (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see `buildNativeEnv`.
  */
 export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd()) {
     const resolvedBundle = resolve(bundlePath);

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[];