@gjsify/cli 0.51.1 → 0.53.0

package/lib/utils/install-tarball-cache.d.ts

@@ -1,9 +1,31 @@
 /**
- * Read a cached tarball by SRI integrity — raw bytes on a HIT, `null` otherwise. A
- * read failure (e.g. a partial write from an interrupted run) is a MISS, and the
- * file is left untouched so a follow-up writer's atomic rename is not tripped.
+ * Read a cached tarball by SRI integrity — raw bytes on a VERIFIED hit, `null`
+ * otherwise. A read failure (e.g. a partial write from an interrupted run) is a MISS,
+ * and the file is left untouched so a follow-up writer's atomic rename is not tripped.
+ *
+ * The bytes are re-hashed against the integrity that named them, through the SAME
+ * {@link verifyIntegrity} the download path uses — so both paths agree by
+ * construction instead of by comment.
+ *
+ * This used to trust the path: "content-addressed, so a hash hit is byte-identical to
+ * what the registry would return". That is a claim ABOUT the bytes, and nothing read
+ * them to check it. It held while the store was a local directory this machine had
+ * written itself. It stops holding the moment the store is a restorable CI artifact —
+ * a GitHub Actions cache entry that is truncated, corrupted, or written by a workflow
+ * on another branch would have been consumed as authentic, because the only thing
+ * asserting its contents was its filename. `gjsify-setup` now restores exactly such an
+ * artifact, so the check is no longer optional. Yarn re-hashes on every install for
+ * this reason (refs/yarn-berry Cache.ts, "we check the file hashes during each install
+ * anyway"); measured here, it costs ~0.5 s over this repo's ~420 MB closure, against
+ * an extract phase of minutes.
+ *
+ * A mismatch DELETES the entry rather than merely skipping it. That is not the prune
+ * this repo refuses elsewhere — the name asserts the content and the content
+ * disproves the name, so the file is garbage by its own definition. It has to go:
+ * {@link putCachedTarball} is idempotent on existence, so a corrupt blob left in place
+ * would never be replaced and every future install would re-download it forever.
  */
-export declare function getCachedTarball(integrity: string | undefined): Uint8Array | null;
+export declare function getCachedTarball(integrity: string | undefined): Promise<Uint8Array | null>;
 /**
  * Persist a tarball to the cache, via a `<path>.tmp.<pid>` sibling and an atomic
  * rename so concurrent installs never observe a half-written entry. No-op when
@@ -17,9 +39,15 @@ export declare function cacheRootForLogging(): string;
 export declare function isCacheHit(integrity: string | undefined): boolean;
 /**
  * Read a tarball from npm's cacache content store by SRI integrity — raw `.tgz`
- * bytes on a HIT, `null` on a MISS, disabled interop or read failure. Like
- * {@link getCachedTarball} it trusts the content-addressed path rather than
- * re-hashing: cacache verified the bytes on write, and the extractor surfaces a
- * genuinely corrupt tarball loudly.
+ * bytes on a VERIFIED hit, `null` on a MISS, disabled interop or read failure.
+ *
+ * Re-hashed like {@link getCachedTarball}, and with more reason: these bytes come
+ * from ANOTHER tool's store, on a path this code does not control and cannot assume
+ * was written by a cacache that verified anything. The old note argued cacache
+ * verified on write and a corrupt tarball would fail loudly in the extractor — but
+ * "the next stage will probably notice" is not verification, and the caller
+ * write-throughs a foreign hit into OUR store, which would launder an unchecked blob
+ * into a first-class entry. A mismatch is left alone here rather than deleted: this
+ * store belongs to npm, and removing another tool's files is not this code's call.
  */
-export declare function getForeignCachedTarball(integrity: string | undefined): Uint8Array | null;
+export declare function getForeignCachedTarball(integrity: string | undefined): Promise<Uint8Array | null>;

package/lib/utils/install-tarball-cache.js

@@ -25,9 +25,10 @@
 // on too. Tarballs without an integrity hash (older registries) fall through to a
 // no-op cache and download every time.
 import { Buffer } from 'node:buffer';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { verifyIntegrity } from '@gjsify/npm-registry';
 import { atomicWrite, gjsifyCacheRoot, readCacheFile } from './install-cache-fs.js';
 const CACHE_LAYOUT_VERSION = 'v1';
 /** Root of the tarball cache: `$XDG_CACHE_HOME/gjsify/tarballs/v1`. */
@@ -68,15 +69,50 @@ function pathFor(integrity) {
     return join(cacheRoot(), sri.algorithm, shard, `${sri.hex}.tgz`);
 }
 /**
- * Read a cached tarball by SRI integrity — raw bytes on a HIT, `null` otherwise. A
- * read failure (e.g. a partial write from an interrupted run) is a MISS, and the
- * file is left untouched so a follow-up writer's atomic rename is not tripped.
+ * Read a cached tarball by SRI integrity — raw bytes on a VERIFIED hit, `null`
+ * otherwise. A read failure (e.g. a partial write from an interrupted run) is a MISS,
+ * and the file is left untouched so a follow-up writer's atomic rename is not tripped.
+ *
+ * The bytes are re-hashed against the integrity that named them, through the SAME
+ * {@link verifyIntegrity} the download path uses — so both paths agree by
+ * construction instead of by comment.
+ *
+ * This used to trust the path: "content-addressed, so a hash hit is byte-identical to
+ * what the registry would return". That is a claim ABOUT the bytes, and nothing read
+ * them to check it. It held while the store was a local directory this machine had
+ * written itself. It stops holding the moment the store is a restorable CI artifact —
+ * a GitHub Actions cache entry that is truncated, corrupted, or written by a workflow
+ * on another branch would have been consumed as authentic, because the only thing
+ * asserting its contents was its filename. `gjsify-setup` now restores exactly such an
+ * artifact, so the check is no longer optional. Yarn re-hashes on every install for
+ * this reason (refs/yarn-berry Cache.ts, "we check the file hashes during each install
+ * anyway"); measured here, it costs ~0.5 s over this repo's ~420 MB closure, against
+ * an extract phase of minutes.
+ *
+ * A mismatch DELETES the entry rather than merely skipping it. That is not the prune
+ * this repo refuses elsewhere — the name asserts the content and the content
+ * disproves the name, so the file is garbage by its own definition. It has to go:
+ * {@link putCachedTarball} is idempotent on existence, so a corrupt blob left in place
+ * would never be replaced and every future install would re-download it forever.
  */
-export function getCachedTarball(integrity) {
+export async function getCachedTarball(integrity) {
     const path = pathFor(integrity);
-    if (!path)
+    if (!path || !integrity)
+        return null;
+    const bytes = readCacheFile(path);
+    if (!bytes)
         return null;
-    return readCacheFile(path);
+    if (await verifyIntegrity(bytes, integrity))
+        return bytes;
+    // Best-effort: a read-only cache volume must not break the install, and the
+    // caller falls through to a verifying download either way.
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        /* keep going — the download path replaces the value we return as a MISS */
+    }
+    return null;
 }
 /**
  * Persist a tarball to the cache, via a `<path>.tmp.<pid>` sibling and an atomic
@@ -158,14 +194,23 @@ function npmCachePathFor(integrity) {
 }
 /**
  * Read a tarball from npm's cacache content store by SRI integrity — raw `.tgz`
- * bytes on a HIT, `null` on a MISS, disabled interop or read failure. Like
- * {@link getCachedTarball} it trusts the content-addressed path rather than
- * re-hashing: cacache verified the bytes on write, and the extractor surfaces a
- * genuinely corrupt tarball loudly.
+ * bytes on a VERIFIED hit, `null` on a MISS, disabled interop or read failure.
+ *
+ * Re-hashed like {@link getCachedTarball}, and with more reason: these bytes come
+ * from ANOTHER tool's store, on a path this code does not control and cannot assume
+ * was written by a cacache that verified anything. The old note argued cacache
+ * verified on write and a corrupt tarball would fail loudly in the extractor — but
+ * "the next stage will probably notice" is not verification, and the caller
+ * write-throughs a foreign hit into OUR store, which would launder an unchecked blob
+ * into a first-class entry. A mismatch is left alone here rather than deleted: this
+ * store belongs to npm, and removing another tool's files is not this code's call.
  */
-export function getForeignCachedTarball(integrity) {
+export async function getForeignCachedTarball(integrity) {
     const path = npmCachePathFor(integrity);
-    if (!path)
+    if (!path || !integrity)
+        return null;
+    const bytes = readCacheFile(path);
+    if (!bytes)
         return null;
-    return readCacheFile(path);
+    return (await verifyIntegrity(bytes, integrity)) ? bytes : null;
 }

package/lib/utils/native-skip-scan.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function externalParserFor(fileName: string, svelteEnabled?: boolean): string | null;
+export interface NativeSkipScanOptions {
+    /** The `--config` handed to oxfmt. Absent → discovery, as in oxfmt. */
+    configPath?: string;
+}
+export interface NativeSkipScanResult {
+    /** Files napi oxfmt would format that the native build skips. */
+    skipped: string[];
+    /** Files the walk hands to oxfmt's classifier. */
+    total: number;
+}
+/** Walk `paths` the way oxfmt does and report what the native build skips. */
+export declare function scanForNativeSkips(paths: string[], cwd?: string, options?: NativeSkipScanOptions): NativeSkipScanResult;
+/** JSON with comments and trailing commas; string contents are never touched. */
+export declare function parseJsonc(text: string): unknown;

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/normalize-bundler-options.js

@@ -130,6 +130,17 @@ export function mergeBundlerOptions(base, overrides) {
         if (base.transform?.define || overrides.transform?.define) {
             out.transform.define = { ...base.transform?.define, ...overrides.transform?.define };
         }
+        // `inject` is a map like `define` and merges the same way. Replacing it wholesale
+        // meant a user who injected ONE identifier silently lost the orchestrator's
+        // `console` → `@gjsify/rolldown-plugin-gjsify/shims/console-gjs` rewrite, which
+        // `--app gjs` cannot express any other way: GJS defines `globalThis.console`
+        // non-writable and non-configurable, so assigning to it from a register module
+        // no-ops. It also has to stay in lockstep with `mergeTransformOptions` in the
+        // plugin's auto-globals analyser — when the two merge the same options
+        // differently, the detector measures a bundle that is not the one that ships.
+        if (base.transform?.inject || overrides.transform?.inject) {
+            out.transform.inject = { ...base.transform?.inject, ...overrides.transform?.inject };
+        }
     }
     if (base.resolve || overrides.resolve) {
         out.resolve = { ...base.resolve, ...overrides.resolve };

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