@gjsify/cli 0.52.0 → 0.53.0

package/lib/utils/native-skip-scan.js

@@ -0,0 +1,343 @@
+// Scan for files the Node oxfmt would format but the native one (GJS) skips.
+//
+// `@gjsify/oxfmt-native` is oxfmt built WITHOUT its `napi` feature. That build
+// formats JS/TS, JSON, TOML, GraphQL and CSS/SCSS/Less itself, but the formats
+// oxfmt hands to its Prettier host (Markdown, HTML, Vue, YAML, …) are not even
+// classified: oxfmt's walker drops them without a word. `gjsify format --check`
+// under GJS would then exit 0 on a tree that the Node CLI finds unformatted.
+//
+// The answer is only honest when it is asked about the SAME file set oxfmt
+// walks. The first version of this scan walked everything, `node_modules/`
+// included, read no ignore file and flagged CSS the native build formats; on
+// this repository `format --check` exited 1 on dependency READMEs without ever
+// starting oxfmt. So the walk mirrors oxfmt's (refs/oxc
+// `apps/oxfmt/src/cli/{walk,resolve}.rs`, `crates/oxc_config/src/walk.rs`):
+//
+//   - VCS directories and `node_modules` are never entered;
+//   - `.prettierignore` in cwd and `!`-prefixed CLI paths block everywhere;
+//   - `.gitignore` (nested, plus parents up to the repository root) and
+//     `.git/info/exclude` apply to walked entries — only inside a repository
+//     when every walk root is in one, everywhere when not;
+//   - the config's `ignorePatterns` apply to every file, relative to the
+//     config's directory; with no explicit config a nested `.oxfmtrc.json(c)`
+//     scopes its subtree, like oxfmt's nested-config discovery;
+//   - a file named directly is not held to `.gitignore`, as in oxfmt;
+//   - symlinks are not followed.
+//
+// Only a file that survives all of that AND that napi oxfmt would route to its
+// external formatter is reported.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { compileGitignore, globToRegexSource, readGitignoreFile } from './gitignore.js';
+const parsers = (parser, keys) => Object.fromEntries(keys.map((k) => [k, parser]));
+// oxfmt `core/support.rs`: the `#[cfg(feature = "napi")]` sets behind
+// `get_external_parser_name`. Matched case-sensitively, as oxfmt does.
+const EXTERNAL_BY_EXTENSION = {
+    ...parsers('yaml', ['yml', 'mir', 'reek', 'rviz', 'sublime-syntax', 'syntax', 'yaml', 'yaml-tmlanguage']),
+    ...parsers('markdown', [
+        'md',
+        'livemd',
+        'markdown',
+        'mdown',
+        'mdwn',
+        'mkd',
+        'mkdn',
+        'mkdown',
+        'ronn',
+        'scd',
+        'workbook',
+    ]),
+    ...parsers('html', ['html', 'hta', 'htm', 'inc', 'xht', 'xhtml']),
+    ...parsers('glimmer', ['handlebars', 'hbs']),
+    mdx: 'mdx',
+    vue: 'vue',
+    svelte: 'svelte',
+    mjml: 'mjml',
+};
+const EXTERNAL_BY_FILENAME = {
+    ...parsers('yaml', ['.clang-format', '.clang-tidy', '.clangd', '.gemrc', 'CITATION.cff', 'glide.lock']),
+    ...parsers('yaml', ['pixi.lock', '.prettierrc', '.stylelintrc', '.lintstagedrc']),
+    ...parsers('markdown', ['contents.lr', 'README']),
+};
+// Machine-written files oxfmt refuses before classifying — `pnpm-lock.yaml`
+// would otherwise look like YAML the native build skipped.
+const EXCLUDE_FILENAMES = new Set([
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'MODULE.bazel.lock',
+    'bun.lock',
+    'deno.lock',
+    'composer.lock',
+    'Package.resolved',
+    'Pipfile.lock',
+    'flake.lock',
+    'mcmod.info',
+    'Cargo.lock',
+    'Gopkg.lock',
+    'pdm.lock',
+    'poetry.lock',
+    'uv.lock',
+]);
+const VCS_DIRS = new Set(['.git', '.jj', '.sl', '.svn', '.hg']);
+const CONFIG_NAMES = ['.oxfmtrc.json', '.oxfmtrc.jsonc'];
+/**
+ * The Prettier parser napi oxfmt would format `fileName` with, or `null` when
+ * the native build formats it itself or no oxfmt formats it. `svelte` counts
+ * only when the config enables it, as in oxfmt.
+ */
+export function externalParserFor(fileName, svelteEnabled = false) {
+    if (EXCLUDE_FILENAMES.has(fileName))
+        return null;
+    const ext = extname(fileName).slice(1);
+    const parser = EXTERNAL_BY_FILENAME[fileName] ?? (ext ? EXTERNAL_BY_EXTENSION[ext] : undefined) ?? null;
+    if (parser === 'svelte' && !svelteEnabled)
+        return null;
+    return parser;
+}
+/** Walk `paths` the way oxfmt does and report what the native build skips. */
+export function scanForNativeSkips(paths, cwd = process.cwd(), options = {}) {
+    const skipped = [];
+    let total = 0;
+    const excludes = paths.filter((p) => p.startsWith('!')).map((p) => p.slice(1));
+    const globals = [];
+    const prettierignore = readGitignoreFile(join(cwd, '.prettierignore'));
+    if (prettierignore)
+        globals.push(prettierignore);
+    if (excludes.length)
+        globals.push(compileGitignore(excludes, cwd));
+    const globallyIgnored = (p, isDir, anyParent) => globals.some((g) => (anyParent ? g.matchedPathOrAnyParents(p, isDir) : g.matched(p, isDir)) === 'ignore');
+    const explicitConfig = options.configPath ? resolve(cwd, options.configPath) : null;
+    const rootScope = loadScope(explicitConfig ?? discoverConfig(cwd));
+    const nested = explicitConfig === null;
+    const scopeFor = (dir) => (nested ? nearestScope(dir, rootScope) : rootScope);
+    // oxfmt matches CLI globs with fast_glob::glob_match, which expands `{a,b}`
+    // brace groups (nested too); globToRegexSource — the gitignore translator —
+    // escapes the braces instead, so a brace glob would match nothing. Expand
+    // them into alternatives first. Gitignore patterns never carry braces, so
+    // this stays a CLI-glob-only translation.
+    const expandBraces = (glob) => {
+        const m = /\{([^{}]*)\}/.exec(glob);
+        if (!m)
+            return [glob];
+        return m[1]
+            .split(',')
+            .flatMap((alt) => expandBraces(glob.slice(0, m.index) + alt + glob.slice(m.index + m[0].length)));
+    };
+    // An argument that names nothing on disk but carries glob characters is a
+    // pattern: oxfmt then walks cwd and keeps the files it matches.
+    const globs = [];
+    const targets = new Set();
+    for (const p of paths) {
+        if (p.startsWith('!'))
+            continue;
+        const abs = resolve(cwd, p);
+        if (/[*?[{]/.test(p) && !existsSync(abs)) {
+            for (const alt of expandBraces(p)) {
+                globs.push(new RegExp(`^${globToRegexSource(alt.includes('/') ? alt : `**/${alt}`)}$`));
+            }
+        }
+        else {
+            targets.add(abs);
+        }
+    }
+    if (globs.length || targets.size === 0)
+        targets.add(resolve(cwd));
+    const record = (file, scope) => {
+        if (scope?.ignore?.matchedPathOrAnyParents(file, false) === 'ignore')
+            return;
+        total++;
+        if (externalParserFor(basename(file), scope?.svelte))
+            skipped.push(file);
+    };
+    const walkRoots = [];
+    for (const target of targets) {
+        let st;
+        try {
+            st = statSync(target);
+        }
+        catch {
+            continue;
+        }
+        if (globallyIgnored(target, st.isDirectory(), true))
+            continue;
+        if (st.isDirectory())
+            walkRoots.push(target);
+        else if (st.isFile())
+            record(target, scopeFor(dirname(target)));
+    }
+    const matchesGlob = (file) => {
+        if (!globs.length || targets.has(file))
+            return true;
+        const rel = relative(cwd, file).split(sep).join('/');
+        return globs.some((g) => g.test(rel));
+    };
+    const seen = new Set();
+    const walk = (dir, inherited, scope) => {
+        if (seen.has(dir))
+            return;
+        seen.add(dir);
+        const own = readGitignoreFile(join(dir, '.gitignore'));
+        const stack = own ? [own, ...inherited] : inherited;
+        if (nested && dir !== scope?.dir)
+            scope = scopeAt(dir) ?? scope;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            const isDir = entry.isDirectory();
+            if (!isDir && !entry.isFile())
+                continue;
+            if (isDir && (VCS_DIRS.has(entry.name) || entry.name === 'node_modules'))
+                continue;
+            if (globallyIgnored(full, isDir, false) || gitIgnored(stack, full, isDir))
+                continue;
+            if (isDir)
+                walk(full, stack, scope);
+            else if (matchesGlob(full))
+                record(full, scope);
+        }
+    };
+    const requireGit = walkRoots.every((r) => repoRootOf(r) !== null);
+    for (const root of walkRoots) {
+        walk(root, parentGitignores(root, requireGit ? repoRootOf(root) : null, requireGit), scopeFor(root));
+    }
+    return { skipped, total };
+}
+/** Nearest-first: the first matcher that decides wins, as in the `ignore` crate. */
+function gitIgnored(stack, path, isDir) {
+    for (const m of stack) {
+        const hit = m.matched(path, isDir);
+        if (hit !== null)
+            return hit === 'ignore';
+    }
+    return false;
+}
+/**
+ * The `.gitignore` files ABOVE a walk root (the walk reads the root's own),
+ * nearest first, then `.git/info/exclude`, which ranks below them. Inside a
+ * repository the lookup stops at its root, outside one it runs to `/`.
+ */
+function parentGitignores(root, repo, requireGit) {
+    if (requireGit && repo === null)
+        return [];
+    const out = [];
+    for (let dir = root; dir !== repo;) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+        const m = readGitignoreFile(join(dir, '.gitignore'));
+        if (m)
+            out.push(m);
+    }
+    const exclude = repo ? readGitignoreFile(join(repo, '.git', 'info', 'exclude'), repo) : null;
+    if (exclude)
+        out.push(exclude);
+    return out;
+}
+function repoRootOf(start) {
+    for (let dir = start;; dir = dirname(dir)) {
+        if (existsSync(join(dir, '.git')) || existsSync(join(dir, '.jj')))
+            return dir;
+        if (dirname(dir) === dir)
+            return null;
+    }
+}
+function configIn(dir) {
+    for (const name of CONFIG_NAMES) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+function discoverConfig(cwd) {
+    for (let dir = resolve(cwd);; dir = dirname(dir)) {
+        const found = configIn(dir);
+        if (found)
+            return found;
+        if (dirname(dir) === dir)
+            return null;
+    }
+}
+function scopeAt(dir) {
+    const cfg = configIn(dir);
+    return cfg ? loadScope(cfg) : null;
+}
+/** The scope of the nearest config at or above `dir`. */
+function nearestScope(dir, fallback) {
+    for (;; dir = dirname(dir)) {
+        if (fallback && dir === fallback.dir)
+            return fallback;
+        const scope = scopeAt(dir);
+        if (scope)
+            return scope;
+        if (dirname(dir) === dir)
+            return fallback;
+    }
+}
+/**
+ * A config's `ignorePatterns`, and whether it enables Svelte. A config that
+ * does not parse contributes no patterns — more files reported, never fewer;
+ * oxfmt rejects that config anyway.
+ */
+function loadScope(configPath) {
+    if (!configPath)
+        return null;
+    const dir = dirname(configPath);
+    let raw = {};
+    try {
+        raw = parseJsonc(readFileSync(configPath, 'utf-8'));
+    }
+    catch {
+        raw = {};
+    }
+    const patterns = Array.isArray(raw.ignorePatterns)
+        ? raw.ignorePatterns.filter((p) => typeof p === 'string')
+        : [];
+    return {
+        dir,
+        ignore: patterns.length ? compileGitignore(patterns, dir) : null,
+        svelte: raw.svelte !== undefined && raw.svelte !== null && raw.svelte !== false,
+    };
+}
+/** JSON with comments and trailing commas; string contents are never touched. */
+export function parseJsonc(text) {
+    const pass = (src, drop) => {
+        let out = '';
+        for (let i = 0; i < src.length;) {
+            if (src[i] === '"') {
+                let j = i + 1;
+                while (j < src.length && src[j] !== '"')
+                    j += src[j] === '\\' ? 2 : 1;
+                out += src.slice(i, j + 1);
+                i = j + 1;
+                continue;
+            }
+            const skip = drop(src, i);
+            if (skip > 0)
+                i += skip;
+            else
+                out += src[i++];
+        }
+        return out;
+    };
+    const uncommented = pass(text, (src, i) => {
+        if (src.startsWith('//', i)) {
+            const nl = src.indexOf('\n', i);
+            return (nl === -1 ? src.length : nl) - i;
+        }
+        if (src.startsWith('/*', i)) {
+            const end = src.indexOf('*/', i + 2);
+            return (end === -1 ? src.length : end + 2) - i;
+        }
+        return 0;
+    });
+    return JSON.parse(pass(uncommented, (src, i) => (src[i] === ',' && /^\s*[}\]]/.test(src.slice(i + 1)) ? 1 : 0)));
+}

package/lib/utils/node-script.js

@@ -6,7 +6,7 @@
 // has no `node:` URI scheme and no node_modules walker, so `gjs -m <script>.mjs` dies on the
 // first import. That gap is why a Node-less host could install gjsify, resolve every native
 // prebuild, and then fail `build:infra` at `node scripts/process-template.mjs` (see
-// `status/open-todos.md`).
+// `status/open-todos/README.md`).
 //
 // Rejected alternative: commit a `dist/*.gjs.mjs` per script — one more artifact each under
 // the committed-bundle freshness gate, scaling with the number of scripts. This is ONE

package/lib/utils/oxc-resolve.js

@@ -45,7 +45,7 @@
 // `gjsify/register-class-order` rule wired via `.oxlintrc.json` jsPlugins)
 // lives in the Node launcher, so a native oxlint bridge could only run the
 // Rust rule subset. Lint stays Node-spawned until that trade-off is decided
-// (tracked in status/open-todos.md).
+// (tracked in status/open-todos/README.md).
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
@@ -233,6 +233,8 @@ function findConfigFile(cwd, names) {
     return null;
 }
 let _nativeOxfmtProbe = null;
+/** Why the bridge's library would not open, when `tryLoadNativeOxfmt()` measured it. */
+let _nativeOxfmtLoadError = null;
 /**
  * Try to load `@gjsify/oxfmt-native` (GJS only). Same multi-anchor
  * resolution as `bundler-pick.ts`'s `tryLoadNative()` — GJS's native ESM
@@ -257,6 +259,34 @@ async function tryLoadNativeOxfmt() {
             const mod = (await import(/* @vite-ignore */ target));
             if (!mod.hasNativeOxfmt())
                 return null;
+            // The typelib resolved; its library opens at the first class access.
+            // Open it now, beside that typelib — the wrapper cannot, for the reason
+            // `bundler-pick.ts`'s `tryLoadNative()` gives — so a library that will
+            // not load names itself instead of failing inside `runOxfmt()`.
+            // Resolved and imported, not statically imported — the reasoning is
+            // at the top of this file. By the time a formatter asks for the
+            // native backend, utils' `lib/esm` is built. `./native-library`
+            // rather than `./core`: `core` re-exports `main-loop`, whose
+            // module-level singleton would then exist twice in a process that
+            // already carries it inlined in the GJS bundle.
+            //
+            // Its own `try` because the outer one cannot tell this apart from
+            // "there is no native backend", and `_nativeOxfmtLoadError` is the
+            // one place the npm fallback reports why it took over.
+            let openNativeLibrary;
+            try {
+                const utilsResolved = resolveNpmPackage('@gjsify/utils/native-library', { bundleUrl: import.meta.url }) ??
+                    createRequire(import.meta.url).resolve('@gjsify/utils/native-library');
+                const utilsHref = pathToFileURL(utilsResolved).href;
+                ({ openNativeLibrary } = (await import(/* @vite-ignore */ utilsHref)));
+            }
+            catch (err) {
+                _nativeOxfmtLoadError = err instanceof Error ? err : new Error(String(err));
+                return null;
+            }
+            _nativeOxfmtLoadError = openNativeLibrary('GjsifyOxfmt');
+            if (_nativeOxfmtLoadError)
+                return null;
             return mod;
         }
         catch {
@@ -281,13 +311,22 @@ export async function shouldUseNativeOxfmt() {
     if (choice === 'native') {
         const native = await tryLoadNativeOxfmt();
         if (!native) {
-            throw new Error('GJSIFY_OXFMT=native but @gjsify/oxfmt-native is not loadable (no prebuild for this architecture, or not running under GJS).');
+            throw new Error('GJSIFY_OXFMT=native but @gjsify/oxfmt-native is not loadable (no prebuild for this architecture, or not running under GJS).' +
+                (_nativeOxfmtLoadError ? `\n${_nativeOxfmtLoadError.message}` : ''));
         }
         return true;
     }
     if (!isGjs())
         return false;
-    return (await tryLoadNativeOxfmt()) !== null;
+    const native = (await tryLoadNativeOxfmt()) !== null;
+    // Falling back to the npm launcher is not an error, so the default path is
+    // quiet — but a MEASURED reason why the native bridge would not load is the
+    // only place the user hears it, and it is the whole point of measuring.
+    // `GJSIFY_OXFMT=native` above throws with this text; the default earns the
+    // same answer for free.
+    if (!native && _nativeOxfmtLoadError)
+        console.debug(_nativeOxfmtLoadError.message);
+    return native;
 }
 /**
  * Run an oxc tool (oxlint / oxfmt).

package/lib/utils/process-table.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Is `pid` a live process on this machine?
+ *
+ * `/proc/<pid>` where procfs exists (one stat, no subprocess, identical under
+ * Node and GJS); elsewhere Node's signal-0 probe — `ESRCH` dead, `EPERM`
+ * alive-but-foreign. Any OTHER outcome counts as ALIVE: callers use this to
+ * decide whether something may be taken away from its owner, and "cannot tell"
+ * must never read as "gone".
+ */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Parse `ps -A -o pid=,ppid=` output (two integer columns, blank headers) into
+ * ppid → children. Exported for the unit test; the format is POSIX, so procps
+ * on Linux and the BSD `ps` on macOS print the same shape.
+ */
+export declare function parsePsPidPpid(output: string): Map<number, number[]>;
+/**
+ * Every transitive descendant of `pid`, breadth-first (reverse the list for
+ * deepest-first signalling). A snapshot — processes spawned after it are not in
+ * it, which is why `foreach` re-walks before escalating to SIGKILL.
+ */
+export declare function collectDescendants(pid: number): number[];

package/lib/utils/process-table.js

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: MIT
+// What the CLI asks the OS about OTHER processes — is this pid alive, who are
+// its descendants — answered in ONE place, for Node and GJS hosts alike.
+//
+// Both questions used to be answered only by reading `/proc`, in two files
+// (`install-lock.ts`, `commands/foreach.ts`). procfs is a LINUX filesystem, and
+// on macOS neither reader failed — each returned a plausible, wrong answer:
+//
+//   - `foreach`'s fail-fast tree kill found NO descendants, so it signalled only
+//     the direct `npm run` child and left its shell → gjs/node build grandchildren
+//     running (the orphaned-bundler-at-100%-CPU shape the tree kill exists for).
+//   - `install-lock`'s liveness probe fell back to `process.kill(pid, 0)`, whose
+//     GJS implementation returned `true` for every pid, so a crashed install's
+//     lock was never stolen as dead-owner — only after the 35-min budget.
+//
+// So every reader here is chosen by what the host HAS (procfs readable?), never
+// by platform name — a Linux container can lack procfs too. Only the no-procfs
+// fallback's COMMAND depends on the platform, because Windows has no `ps`.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+/**
+ * Is `pid` a live process on this machine?
+ *
+ * `/proc/<pid>` where procfs exists (one stat, no subprocess, identical under
+ * Node and GJS); elsewhere Node's signal-0 probe — `ESRCH` dead, `EPERM`
+ * alive-but-foreign. Any OTHER outcome counts as ALIVE: callers use this to
+ * decide whether something may be taken away from its owner, and "cannot tell"
+ * must never read as "gone".
+ */
+export function isPidAlive(pid) {
+    // `existsSync` never throws by contract: Node returns false on any error, and
+    // the GJS shim is a typeof guard + Gio `query_exists`.
+    if (existsSync('/proc/self'))
+        return existsSync(`/proc/${pid}`);
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+/**
+ * Parse `ps -A -o pid=,ppid=` output (two integer columns, blank headers) into
+ * ppid → children. Exported for the unit test; the format is POSIX, so procps
+ * on Linux and the BSD `ps` on macOS print the same shape.
+ */
+export function parsePsPidPpid(output) {
+    const map = new Map();
+    for (const line of output.split('\n')) {
+        const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        if (pid <= 0 || ppid <= 0 || pid === ppid)
+            continue;
+        const siblings = map.get(ppid);
+        if (siblings)
+            siblings.push(pid);
+        else
+            map.set(ppid, [pid]);
+    }
+    return map;
+}
+// Direct children of `pid` from /proc/<pid>/task/*/children (Linux,
+// CONFIG_PROC_CHILDREN — standard on every mainstream kernel). `null` when the
+// files are unreadable, which sends the caller to the full-table fallback.
+function readProcChildren(pid) {
+    let taskIds;
+    try {
+        taskIds = readdirSync(`/proc/${pid}/task`);
+    }
+    catch {
+        // Process already gone (common) or no procfs.
+        return null;
+    }
+    const kids = [];
+    let readAny = false;
+    for (const tid of taskIds) {
+        try {
+            const data = readFileSync(`/proc/${pid}/task/${tid}/children`, 'utf-8');
+            readAny = true;
+            for (const tok of data.trim().split(/\s+/)) {
+                const n = Number(tok);
+                if (Number.isInteger(n) && n > 0)
+                    kids.push(n);
+            }
+        }
+        catch {
+            // Thread vanished mid-walk, or kernel lacks CONFIG_PROC_CHILDREN.
+        }
+    }
+    return readAny ? kids : null;
+}
+// ppid → children from one /proc/*/stat scan. Empty when there is no procfs.
+function procPpidMap() {
+    const map = new Map();
+    let entries = [];
+    try {
+        entries = readdirSync('/proc');
+    }
+    catch {
+        return map;
+    }
+    for (const entry of entries) {
+        const pid = Number(entry);
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf-8');
+            // comm (field 2) may contain spaces/parens — parse after last ')'.
+            const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+            const ppid = Number(rest[1]);
+            if (!Number.isInteger(ppid) || ppid <= 0)
+                continue;
+            const siblings = map.get(ppid);
+            if (siblings)
+                siblings.push(pid);
+            else
+                map.set(ppid, [pid]);
+        }
+        catch {
+            // Process exited between readdir and read — fine.
+        }
+    }
+    return map;
+}
+// ppid → children from the OS's process list where there is no procfs:
+// `ps(1)` on macOS/BSD, CIM's Win32_Process on Windows (no `ps` there — Git's
+// MSYS `ps` rejects `-o` and sees only MSYS processes). Both print "pid ppid"
+// lines, so one parser serves. Empty when neither can be run, which degrades to
+// "signal the direct child only".
+function osPpidMap() {
+    const [cmd, args] = process.platform === 'win32'
+        ? [
+            'powershell.exe',
+            [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId)" }',
+            ],
+        ]
+        : ['ps', ['-A', '-o', 'pid=,ppid=']];
+    try {
+        const res = spawnSync(cmd, args, { encoding: 'utf-8' });
+        if (res.status !== 0 || typeof res.stdout !== 'string')
+            return new Map();
+        return parsePsPidPpid(res.stdout);
+    }
+    catch {
+        return new Map();
+    }
+}
+/**
+ * Every transitive descendant of `pid`, breadth-first (reverse the list for
+ * deepest-first signalling). A snapshot — processes spawned after it are not in
+ * it, which is why `foreach` re-walks before escalating to SIGKILL.
+ */
+export function collectDescendants(pid) {
+    const result = [];
+    const seen = new Set([pid]);
+    const queue = [pid];
+    let table = null;
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        let kids = table ? null : readProcChildren(cur);
+        if (kids === null) {
+            // Per-task children files unreadable: one full table for this and
+            // every later level. procfs first, the OS process list where there is none.
+            if (!table) {
+                table = procPpidMap();
+                if (table.size === 0)
+                    table = osPpidMap();
+            }
+            kids = table.get(cur) ?? [];
+        }
+        for (const kid of kids) {
+            if (seen.has(kid))
+                continue;
+            seen.add(kid);
+            result.push(kid);
+            queue.push(kid);
+        }
+    }
+    return result;
+}

package/lib/utils/prune-prefix.js

@@ -25,7 +25,7 @@
 // Reachability ("nothing installed points at this any more") would catch that one
 // and more, but it needs a record of what the prefix was ASSEMBLED FROM, which no
 // prefix carries yet. Uncertain means keep — see ADR 0025 and
-// `status/open-todos.md`.
+// `status/open-todos/README.md`.
 import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { checkPlatform, declaresPlatform, describePlatformTarget, readPlatformOverrides, } from './platform-check.js';

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

@@ -6,7 +6,7 @@ import { type SpawnCompletionContract } from './spawn.js';
  * variable is set is host-dependent (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see
  * `buildNativeEnv`.
  */
-export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: string, inherited?: Record<string, string | undefined>): {
+export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: string, inherited?: Record<string, string | undefined>, extraRoots?: readonly string[]): {
     env: NativeEnv;
     envPrefix: string;
 };
@@ -41,5 +41,19 @@ export interface RunGjsBundleOptions {
      * (`utils/node-script.ts`).
      */
     quiet?: boolean;
+    /**
+     * Do not add `gjs exited with code N` to a failing child's own output. For a
+     * transparent runner (`gjsify exec`) a non-zero exit is often an ANSWER — `semver
+     * -r '>2' 1.0.0` exits 1 to say "no match" — and the child's code is re-raised
+     * either way.
+     */
+    quietExit?: boolean;
+    /**
+     * More directories to look for native `@gjsify/*` prebuilds in, after the cwd and the
+     * bundle's own tree. `gjsify exec` passes the running CLI's: a rebuilt bin takes its
+     * polyfills from beside the CLI, so their typelibs live there too — web-ext's rebuild
+     * died at load with `Typelib file for namespace 'GjsifyHttpSoupBridge' … not found`.
+     */
+    nativeRoots?: readonly string[];
 }
 export declare function runGjsBundle(bundlePath: string, extraArgs: string[] | undefined, options: RunGjsBundleOptions): Promise<void>;