@gjsify/cli 0.21.0 → 0.23.0

package/lib/utils/install-global.js

@@ -23,7 +23,8 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { detectNativePackages } from './detect-native-packages.js';
+import { detectNativePackages, libraryPathVar } from './detect-native-packages.js';
+import { buildLauncherShims, parseShebang } from './bin-shim.js';
 /**
  * Compute the canonical global install layout for the current user. Honours
  * `XDG_DATA_HOME` (per the XDG Base Directory Spec) plus
@@ -174,7 +175,9 @@ export function linkGlobalBins(packageNames, layout) {
                 /* best effort */
             }
             const linkPath = path.join(layout.binDir, binName);
-            fs.rmSync(linkPath, { force: true });
+            for (const stale of [linkPath, `${linkPath}.cmd`, `${linkPath}.ps1`]) {
+                fs.rmSync(stale, { force: true, maxRetries: 10, retryDelay: 100 });
+            }
             // Inline `${target}` directly — this file is rewritten on every
             // install, paths are user-owned, and POSIX `sh` quoting via
             // single-quotes plus `'\''` for embedded quotes is well-defined.
@@ -196,6 +199,36 @@ export function linkGlobalBins(packageNames, layout) {
                 : `#!/bin/sh\nexec ${shQuote(targetAbs)} "$@"\n`;
             fs.writeFileSync(linkPath, launcher);
             fs.chmodSync(linkPath, 0o755);
+            // Windows runs neither an extension-less file nor a `#!` line, so
+            // the `sh` launcher above is only reachable from git-bash/MSYS/WSL.
+            // Write the `.cmd`/`.ps1` companions cmd.exe and pwsh need — the
+            // same three-file layout npm's cmd-shim produces.
+            if (process.platform === 'win32') {
+                const joined = nativePrebuildDirs.join(';');
+                // No dedicated DLL-search variable on Windows: LoadLibrary
+                // searches PATH, and GLib's search-path separator is `;` there
+                // too — so both variables take the same `;`-joined value.
+                const prependEnv = isGjsBundle && nativePrebuildDirs.length > 0 ? { GI_TYPELIB_PATH: joined, PATH: joined } : {};
+                // A non-bundle bin is exec'd directly by the sh launcher, which
+                // relies on its `#!` line; batch/pwsh have no shebang support,
+                // so read the interpreter out of it the way cmd-shim does
+                // (defaulting to `node`, what every npm bin declares).
+                const shebang = isGjsBundle ? null : readShebangOf(targetAbs);
+                const shims = isGjsBundle
+                    ? buildLauncherShims({
+                        interpreter: 'gjs',
+                        interpreterArgs: ['-m'],
+                        target: targetAbs,
+                        prependEnv,
+                    })
+                    : buildLauncherShims({
+                        interpreter: shebang?.prog || 'node',
+                        interpreterArgs: shebang?.args.trim() ? shebang.args.trim().split(/\s+/) : [],
+                        target: targetAbs,
+                    });
+                fs.writeFileSync(`${linkPath}.cmd`, shims.cmd);
+                fs.writeFileSync(`${linkPath}.ps1`, shims.ps1);
+            }
             created.push({ name: binName, target: targetAbs, link: linkPath });
         }
     }
@@ -206,20 +239,37 @@ function shQuote(s) {
 }
 /**
  * Build the POSIX-sh `export` lines that prepend the given prebuild
- * directories to GI_TYPELIB_PATH and LD_LIBRARY_PATH. Any pre-existing value
- * inherited from the user's environment is preserved as a suffix so
- * user-installed typelibs/libraries still resolve.
+ * directories to GI_TYPELIB_PATH and the host's shared-library search path.
+ * Any pre-existing value inherited from the user's environment is preserved as
+ * a suffix so user-installed typelibs/libraries still resolve.
+ *
+ * The library variable is host-dependent — `LD_LIBRARY_PATH` on Linux,
+ * `DYLD_LIBRARY_PATH` on macOS (dyld never reads the ELF one), so a launcher
+ * written on a Mac used to export a variable nothing consults, leaving every
+ * `darwin-arm64` prebuild unloadable. `platform` is a parameter so both
+ * branches are unit-testable from either host.
  *
  * Returns the empty string when no prebuilds were found — avoids emitting an
  * inert assignment in the launcher.
  */
-function buildLauncherEnvPreamble(prebuildsDirs) {
+export function buildLauncherEnvPreamble(prebuildsDirs, platform = process.platform) {
     if (prebuildsDirs.length === 0)
         return '';
+    const { name: libVar } = libraryPathVar(platform);
     const joined = shQuote(prebuildsDirs.join(':'));
     return (`GI_TYPELIB_PATH=${joined}\${GI_TYPELIB_PATH:+":$GI_TYPELIB_PATH"}\n` +
-        `LD_LIBRARY_PATH=${joined}\${LD_LIBRARY_PATH:+":$LD_LIBRARY_PATH"}\n` +
-        `export GI_TYPELIB_PATH LD_LIBRARY_PATH\n`);
+        `${libVar}=${joined}\${${libVar}:+":$${libVar}"}\n` +
+        `export GI_TYPELIB_PATH ${libVar}\n`);
+}
+/** Parse a bin file's `#!` line; `null` when unreadable or not a shebang. */
+function readShebangOf(file) {
+    try {
+        const head = fs.readFileSync(file, 'utf-8');
+        return parseShebang(head.trimStart().split(/\r*\n/, 1)[0] ?? '');
+    }
+    catch {
+        return null;
+    }
 }
 function pickBinMap(pkgName, pkgJson) {
     const gjsifyEntry = pkgJson.gjsify;

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;