@gjsify/cli 0.36.0 → 0.37.0

package/lib/utils/spawn.d.ts

@@ -2,12 +2,10 @@ 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.
+ * - `'exit'` — the command terminates the process itself, which quits the armed GJS
+ *   main loop, so the streaming async `spawn` is safe on both hosts.
+ * - `'return'` — the command returns and lets the CLI unwind. Under GJS that must
+ *   not leave a main loop armed, so the child runs on the blocking `spawnSync` path.
  *
  * See the module header for the full rationale.
  */
@@ -17,59 +15,48 @@ export interface SpawnToCompletionOptions {
     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`).
-     */
+    /** Environment for the child. Omit to inherit the parent's verbatim. */
     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`.
+     * Seed `FORCE_COLOR=1` unless `FORCE_COLOR`/`NO_COLOR` is already set, so tools
+     * keying on `process.stdout.isTTY` still emit ANSI into 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}).
+     * `'inherit'` (default) forwards the parent's stdio; `'pipe'` gives the caller
+     * `child.stdout`/`child.stderr` via {@link onSpawn}, so it needs
+     * `completion: 'exit'`.
      *
-     * `'inherit-stderr'` inherits, but routes the child's **stdout to the
-     * parent's stderr**. For a parent whose own stdout is a machine-readable
-     * stream: `gjsify pack --json` emits JSON there, and a lifecycle script's
-     * log lines interleaved into it make the result unparseable for every
-     * caller that pipes it into `JSON.parse`.
+     * `'inherit-stderr'` inherits but routes the child's **stdout to the parent's
+     * stderr**, for a parent whose own stdout is machine-readable: `gjsify pack
+     * --json` emits JSON there, and interleaved lifecycle-script log lines make it
+     * unparseable for anything piping into `JSON.parse`.
      */
     stdio?: 'inherit' | 'pipe' | 'inherit-stderr';
     /**
-     * Run `cmd` through the platform shell, so `&&`, `|` and env-var
-     * references work. `cmd` is then a whole command LINE and `args` must be
-     * empty — that is npm/yarn script semantics.
-     *
-     * Skips the win32 command rewrite by design, per this file's own rule:
-     * Node routes a `shell: true` spawn through `%COMSPEC%`, which finds
-     * `.cmd` shims on its own, so rewriting the string would corrupt it.
+     * Run `cmd` through the platform shell so `&&`, `|` and env-var references work.
+     * `cmd` is then a whole command LINE and `args` must be empty — npm/yarn script
+     * semantics. Skips the win32 rewrite by design: Node routes it through
+     * `%COMSPEC%`, which finds `.cmd` shims itself, so rewriting would corrupt it.
      */
     shell?: boolean;
     /**
-     * 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'`.
+     * Called synchronously with the live `ChildProcess` after a successful async
+     * spawn — the seam for kill-tracking registries and piped output forwarders.
+     * ONLY fires on the streaming path (the blocking path has no handle), so a site
+     * needing the handle must 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.
+     * Map an `ENOENT` spawn failure 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.
+     * Capture ceiling for the blocking path, default 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;
 }
@@ -82,13 +69,10 @@ export interface SpawnCompletion {
 /**
  * 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.
+ * 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 (ENOENT mapped through {@link SpawnToCompletionOptions.notFound}). Picks
+ * the streaming or blocking path per the teardown contract in the module header.
  */
 export declare function spawnToCompletion(cmd: string, args: readonly string[], opts: SpawnToCompletionOptions): Promise<SpawnCompletion>;
 /**

package/lib/utils/spawn.js

@@ -1,33 +1,23 @@
 // 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()` +
+// (`@gjsify/utils`) to give the `Gio.Subprocess` `wait_async` exit callback a
+// running GLib main context. That arms a GJS main-loop hook
+// (`GLib.MainLoop.runAsync()` → `setMainLoopHook`) which `eval_module` runs AFTER
+// the entry module's top-level await settles, entering a blocking
+// `g_main_loop_run()` nothing ever quits. GJS has no atexit hook, so only
+// `process.exit()` tears it down (`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 on gjs 1.88 a command that async-spawns a child and then RETURNS NORMALLY
+// parks at 0% CPU AFTER the child has exited and been reaped. The symptom — live
+// parent, no children, blocked in `poll`, `SNl` — is identical to a lost exit
+// callback and gets misdiagnosed as one; the event IS delivered, and the parent
+// then parks in the armed loop on its way out.
 //
-// So the branch is NOT "GJS ⇒ spawnSync". It is exactly this:
+// The branch is therefore NOT "GJS ⇒ spawnSync":
 //
 //   | host | caller ends with       | path                                |
 //   |------|------------------------|-------------------------------------|
@@ -35,50 +25,37 @@
 //   | 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.
+// which is why `gjsify foreach`/`workspace`/`check` and `runGjsBundle` run hundreds
+// of async-spawned children under GJS without hanging: each ends its handler with
+// `process.exit(…)`. `gjsify lint` did not, and that was the hang. Hence the
+// REQUIRED {@link SpawnToCompletionOptions.completion} field — a new call site must
+// state which side of the table it is on rather than inherit a wrong default.
 //
-// ## When a raw `node:child_process` spawn is still fine — and when it is not
+// ## When a raw `node:child_process` spawn is still fine
 //
-// 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:
+// This helper also carries the Windows command rewrite (`forWin32`), so the rule is
+// about WHAT is spawned:
 //
-//   • 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.
+//   • a real executable (`git`, `gh`, `node`, `gjs`, `flatpak`, `process.execPath`)
+//     may use `node:child_process` directly — Windows resolves those via `.exe`.
+//   • `shell: true` is fine — Node routes it through `%COMSPEC%`, which finds
+//     `.cmd` shims.
+//   • a PACKAGE MANAGER or any `node_modules/.bin` entry by BARE NAME (`npm`,
+//     `yarn`, `npx`, `tsc`, `oxlint`, a `pm` from `detectPackageManager()`) MUST
+//     come through here: on Windows those are `.cmd` shims, where `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.
+// The third case is not hypothetical, and each instance was invisible to Linux and
+// macOS CI: raw spawns left `commands/check.ts` exiting 1 with no diagnostic,
+// `utils/install-backend.ts` reporting "npm not found on PATH" where npm was on
+// PATH, and `commands/onboard.ts` breaking the pre-publish build.
 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;
-/**
- * Build the child's environment: `undefined` (inherit) unless the caller
- * passed one or asked for colour seeding.
- */
+/** `undefined` (inherit) unless the caller passed an env or asked for colour. */
 function resolveEnv(opts) {
     if (!opts.color)
         return opts.env;
@@ -87,12 +64,10 @@ function resolveEnv(opts) {
     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.
+ * Rewrite a bare command for Windows (see `utils/win32-command.ts`). A no-op on
+ * every other platform, and on win32 for anything already carrying a path or
+ * extension. Applied to BOTH paths below so the blocking and streaming branches
+ * agree; `env` is the CHILD's, because its `PATH` is what must be searched.
  */
 function forWin32(cmd, args, env) {
     const rewritten = resolveWin32Command(cmd, args, {
@@ -110,12 +85,8 @@ function mapSpawnError(err, opts) {
     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.
+ * Whether this call has to run on the blocking path — only under GJS for a caller
+ * that returns normally, per the module header's table.
  */
 function mustBlock(opts) {
     return isGjs() && opts.completion === 'return';
@@ -123,13 +94,10 @@ function mustBlock(opts) {
 /**
  * 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.
+ * 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 (ENOENT mapped through {@link SpawnToCompletionOptions.notFound}). Picks
+ * the streaming or blocking path per the teardown contract in the module header.
  */
 export function spawnToCompletion(cmd, args, opts) {
     const env = resolveEnv(opts);
@@ -141,9 +109,9 @@ export function spawnToCompletion(cmd, args, 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.
+        // `communicateWithTimeout`), so the child's diagnostics would be silently
+        // dropped — capture and re-emit them instead. stdin stays inherited so an
+        // interactive child still reads the tty.
         const r = spawnSync(invocation.cmd, invocation.args, {
             stdio: ['inherit', 'pipe', 'pipe'],
             cwd: opts.cwd,
@@ -154,9 +122,9 @@ export function spawnToCompletion(cmd, args, opts) {
         });
         if (r.error)
             return Promise.reject(mapSpawnError(r.error, opts));
-        // The captured stdout goes to the parent's STDERR under
-        // `'inherit-stderr'` — same destination the streaming path routes it to,
-        // so the two agree on where a lifecycle script's chatter lands.
+        // Captured stdout goes to the parent's STDERR under `'inherit-stderr'`, the
+        // destination the streaming path routes it to, so the two agree on where a
+        // lifecycle script's chatter lands.
         const out = opts.stdio === 'inherit-stderr' ? process.stderr : process.stdout;
         if (r.stdout && r.stdout.length > 0)
             out.write(r.stdout);
@@ -184,9 +152,8 @@ export function spawnToCompletion(cmd, args, opts) {
             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
-        // back to back, so this is a strict superset of the old `exit` sites.
+        // `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.
         child.on('close', (code, signal) => {
             resolvePromise({ code, signal });
         });

package/lib/utils/stdin.d.ts

@@ -1,9 +1,9 @@
 /**
- * Read the whole of stdin as UTF-8. Works on Node and under the GJS bundle.
+ * Read the whole of stdin as UTF-8.
  *
  * Synchronous on purpose: 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`).
+ * resume/pause races documented in `utils/prompt.ts`.
  */
 export declare function readStdinText(): string;
 /**

package/lib/utils/stdin.js

@@ -1,37 +1,22 @@
 // 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". It used NOT to
-// survive the GJS bundle: `@gjsify/fs` had no numeric-file-descriptor path, so
-// the `0` was coerced to a PATH and the call opened the relative file `./0` —
-// every GJS caller died with
+// The Node idiom `readFileSync(0, 'utf-8')` means the same thing under GJS
+// because `@gjsify/fs` maps the parent-supplied descriptors 0/1/2 onto the
+// process's own Unix streams (`packages/node/fs/src/std-fd.ts`, reached from
+// `readFileSync` via `sync.ts`).
 //
-//     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`).
-//
-// THE GAP IS CLOSED AT THE CORE, so the workaround is gone: `@gjsify/fs` maps
-// the parent-supplied descriptors 0/1/2 onto the process's own Unix streams
-// (`packages/node/fs/src/std-fd.ts`, reached from `readFileSync` through
-// `sync.ts`), which makes the Node idiom mean the same thing under GJS. This
-// module used to carry two GJS-only readers for that gap — a
-// `GioUnix.InputStream` chunk loop and a `/dev/stdin` `Gio.File` fallback —
-// plus a runtime branch to choose between them. All three were consumer-side
-// repair for a missing core capability.
-//
-// Anything re-adding a GJS branch HERE is re-adding the workaround. If stdin
-// misbehaves under GJS the defect is in `@gjsify/fs` and belongs there, with a
-// test — that is what made the branch removable in the first place
-// (`packages/node/fs/src/fd-ops.spec.ts` + `tests/e2e/fs-std-fd`, which needs a
-// real pipe and so cannot live in a unit spec).
+// Keep this module runtime-agnostic: a GJS branch here would be consumer-side
+// repair for a core capability. If stdin misbehaves under GJS the defect is in
+// `@gjsify/fs` and belongs there, with a test — `fd-ops.spec.ts` for the fd
+// mapping, `tests/e2e/affected-classifier-bundle` for the real pipe.
 import { readFileSync } from 'node:fs';
 /**
- * Read the whole of stdin as UTF-8. Works on Node and under the GJS bundle.
+ * Read the whole of stdin as UTF-8.
  *
  * Synchronous on purpose: 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`).
+ * resume/pause races documented in `utils/prompt.ts`.
  */
 export function readStdinText() {
     return readFileSync(0, 'utf-8');

package/lib/utils/suggest.d.ts

@@ -1,13 +1,12 @@
 /**
- * Levenshtein edit distance between two strings (classic DP, single-row
- * rolling buffer). Case-sensitive; callers lower-case first if they want a
- * case-insensitive match.
+ * Levenshtein edit distance. Case-SENSITIVE — callers lower-case first if they
+ * want otherwise.
  */
 export declare function editDistance(a: string, b: string): number;
 /**
- * The closest candidate to `target` by edit distance, or `undefined` when no
- * candidate is close enough. "Close enough" scales with the target length so
- * a short name doesn't match everything and a long one tolerates a couple of
- * typos: `max(2, floor(len/3))`. Comparison is case-insensitive.
+ * The closest candidate to `target`, or `undefined` when none is close enough.
+ * The threshold `max(2, floor(len/3))` scales with target length so a short name
+ * does not match everything while a long one still tolerates a couple of typos.
+ * Comparison is case-insensitive.
  */
 export declare function suggestClosest(target: string, candidates: readonly string[]): string | undefined;

package/lib/utils/suggest.js

@@ -1,10 +1,8 @@
-// Small "did you mean …?" helper for CLI name typos (unknown workspace,
-// unknown script, …). Pure — no platform imports — so it is unit-testable
-// off any runtime and safe to pull into a GJS-bundled command.
+// "Did you mean …?" for CLI name typos (unknown workspace, unknown script, …).
+// Kept free of platform imports so it is safe to pull into a GJS-bundled command.
 /**
- * Levenshtein edit distance between two strings (classic DP, single-row
- * rolling buffer). Case-sensitive; callers lower-case first if they want a
- * case-insensitive match.
+ * Levenshtein edit distance. Case-SENSITIVE — callers lower-case first if they
+ * want otherwise.
  */
 export function editDistance(a, b) {
     if (a === b)
@@ -28,10 +26,10 @@ export function editDistance(a, b) {
     return prev[b.length];
 }
 /**
- * The closest candidate to `target` by edit distance, or `undefined` when no
- * candidate is close enough. "Close enough" scales with the target length so
- * a short name doesn't match everything and a long one tolerates a couple of
- * typos: `max(2, floor(len/3))`. Comparison is case-insensitive.
+ * The closest candidate to `target`, or `undefined` when none is close enough.
+ * The threshold `max(2, floor(len/3))` scales with target length so a short name
+ * does not match everything while a long one still tolerates a couple of typos.
+ * Comparison is case-insensitive.
  */
 export function suggestClosest(target, candidates) {
     if (candidates.length === 0)

package/lib/utils/system-gi.d.ts

@@ -9,22 +9,17 @@ export interface SystemGiOptions {
     /** `pkg-config`'s `.pc` search directories; defaults to {@link pkgConfigSearchDirs}. */
     searchDirs?: (env: Record<string, string | undefined>) => string[];
 }
-/**
- * Split an OS search-path variable, dropping empty segments.
- */
+/** Split an OS search-path variable, dropping empty segments. */
 export declare function splitSearchPath(value: string | undefined, separator?: string): string[];
 /**
  * `pkg-config`'s OWN configured `.pc` search path plus `$PKG_CONFIG_PATH`. Every
  * entry is a `<libdir>/pkgconfig` (or `<datadir>/pkgconfig`) directory, so its
- * parent is a candidate libdir — which is how a prefix nobody hardcoded is
- * found. Measured on the reported host: `pc_path` =
- * `/usr/local/lib/pkgconfig:/usr/local/share/pkgconfig:/usr/lib/pkgconfig:…`,
- * whose first parent is exactly the `/usr/local/lib` that resolves every leaf.
+ * parent is a candidate libdir — which is how a prefix nobody hardcoded is found.
  *
- * `spawnSync` reports a missing executable as `result.error`, not by throwing —
- * an absent `pkg-config` is expected on a runtime-only GTK install, so it is a
- * checked return value here and not an exception path. (`@gjsify/child_process`
- * matches Node here deliberately; see its `spawnSync` note.)
+ * `spawnSync` reports a missing executable as `result.error`, not by throwing, so
+ * an absent `pkg-config` (expected on a runtime-only GTK install) is a checked
+ * return value and not an exception path. (`@gjsify/child_process` matches Node
+ * here deliberately; see its `spawnSync` note.)
  */
 export declare function pkgConfigSearchDirs(env: Record<string, string | undefined>): string[];
 /**
@@ -42,19 +37,16 @@ export declare function pkgConfigSearchDirs(env: Record<string, string | undefin
  * Sources 2 and 3 are GUESSES at a prefix, so each must show the
  * `girepository-1.0/` marker before it is believed.
  *
- * Empty off darwin, and that is a statement about LOADERS, not about GI. Linux
- * resolves these leaves through `ld.so`'s system-wide configured cache
- * (`/etc/ld.so.conf.d`), which a package install populates — nothing per-process
- * is needed. dyld is the one loader that neither consults a system-wide config
- * NOR re-reads its search path after launch, which is why darwin needs the
- * variable set at launch and nobody else does.
+ * Empty off darwin, and that is a statement about LOADERS, not about GI: Linux
+ * resolves these leaves through `ld.so`'s system-wide cache (`/etc/ld.so.conf.d`),
+ * which a package install populates. dyld is the one loader that neither consults
+ * a system-wide config NOR re-reads its search path after launch.
  *
- * win32 is deliberately absent rather than proven unnecessary: `PATH` is the DLL
- * search path, a Windows GTK distribution puts its `bin` there itself, and
- * Windows re-reads that path at every `LoadLibrary` — so if a system GTK ever
- * turns out not to be on it, the repair is a `PATH` prepend (which
- * {@link buildNativeEnv} already does for the prebuilds), never a second
- * variable. Untested there.
+ * win32 is deliberately absent rather than proven unnecessary, and untested:
+ * `PATH` is the DLL search path, a Windows GTK distribution puts its `bin` there
+ * itself, and Windows re-reads that path at every `LoadLibrary` — so if a system
+ * GTK ever turns out not to be on it, the repair is a `PATH` prepend (which
+ * {@link buildNativeEnv} already does for the prebuilds), never a second variable.
  *
  * @returns absolute directories, or `[]` when this platform's loader needs none
  */
@@ -63,9 +55,8 @@ export declare function systemGiLibraryDirs({ platform, env, existsDir, searchDi
  * Whether `current` (a split `DYLD_FALLBACK_LIBRARY_PATH`) already covers every
  * directory in `wanted` — the "nothing to do" test.
  *
- * Kept in the port even though this CLI's consumer does not branch on it: the
- * mirror's value is that the two files are the SAME file, and a surface that
- * drifts by one export is a mirror nobody can check. `system-gi.spec.ts` pins
- * both.
+ * Kept in the port even though this CLI's consumer does not branch on it: a mirror
+ * that drifts by one export is a mirror nobody can check. `system-gi.spec.ts`
+ * pins both.
  */
 export declare function pathCovers(wanted: readonly string[], current: readonly string[]): boolean;