@gjsify/cli 0.16.3 → 0.16.5

package/lib/commands/install.js

@@ -28,7 +28,8 @@
 // into different prefixes stay parallel; the shared XDG tarball/packument
 // caches need no lock because their writes are atomic tmp+rename.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { spawn, spawnSync } from 'node:child_process';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
@@ -36,6 +37,7 @@ import { detectNativePackages } from '../utils/detect-native-packages.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 import { atomicWriteStrict } from '../utils/install-cache-fs.js';
 import { acquireInstallLock } from '../utils/install-lock.js';
+import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { binDirOnPath, defaultGlobalLayout, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 // Default 30min wall-clock budget for the full install. Big workspaces
@@ -132,6 +134,13 @@ export const installCommand = {
             await installGlobalAndLink(args.packages, { verbose: args.verbose });
             return;
         }
+        // Surface a CLI/workspace version skew BEFORE the heavy install, so
+        // it's visible even if a later phase is slow. A gjsify CLI that is out
+        // of step with the @gjsify/cli the workspace pins is the root cause of
+        // both the mysterious install stall (a mismatched CLI resolves a
+        // differently-shaped lock → full fresh resolve → a wedge-prone extract)
+        // and silent-wrong-builds (the stale CLI builds with stale semantics).
+        warnOnCliVersionSkew(process.cwd());
         // Backend selection (in precedence order):
         //   1. --backend flag (explicit user choice)
         //   2. GJSIFY_INSTALL_BACKEND env (back-compat shape from pre-flag era)
@@ -142,16 +151,47 @@ export const installCommand = {
             await runPostInstallChecks();
             return;
         }
-        // Overall wall-clock budget for the install (default 5 min). On
-        // timeout we abort every in-flight registry fetch via this controller
-        // so the process exits cleanly with an actionable message instead of
-        // a silent hang. Per-request timeouts inside @gjsify/npm-registry
+        // Overall wall-clock budget for the install (default 30 min — big
+        // workspaces on slow networks legitimately take a while). On timeout
+        // we abort every in-flight registry fetch via this controller so a
+        // signal-aware await rejects and the process exits cleanly with an
+        // actionable message. Per-request timeouts inside @gjsify/npm-registry
         // (default 30s, retried) still apply within this budget.
+        //
+        // The abort only rescues awaits that OBSERVE the signal. Some awaits on
+        // the fresh-resolve path do not — most notably tarball extraction (a
+        // Gio-backed decompress whose stream close-event can be dropped under
+        // GJS) and the workspace symlink fs-pool — so an aborted controller
+        // alone cannot guarantee the process ever stops. `hardExitTimerId`
+        // below is the backstop: a grace period after the abort, if the install
+        // STILL hasn't returned, force a non-zero exit. This converts any
+        // residual never-settling await into a clean failure instead of a
+        // silent 0%-CPU hang (the observed "it never completed; I killed it"
+        // pathology). `extractOne` additionally caps each extract with its own
+        // stall timeout so the common case fails fast, long before this.
         const overallTimeoutMs = args.timeout > 0 ? args.timeout : 0;
         const overallController = overallTimeoutMs > 0 ? new AbortController() : null;
         const overallTimerId = overallController !== null
             ? setTimeout(() => overallController.abort(new Error('install-overall-timeout')), overallTimeoutMs)
             : null;
+        // Grace after the abort before we pull the plug. Long enough for a
+        // signal-aware reject to propagate through the catch (the clean path),
+        // short enough that a genuinely-wedged await doesn't hang for minutes.
+        const HARD_EXIT_GRACE_MS = 10_000;
+        const hardExitTimerId = overallTimeoutMs > 0
+            ? setTimeout(() => {
+                const secs = Math.round(overallTimeoutMs / 100) / 10;
+                console.error(`gjsify install: still stuck ${Math.round(HARD_EXIT_GRACE_MS / 1000)}s after the ${secs}s ` +
+                    `budget elapsed and the in-flight aborts — forcing exit. A dependency's extract or ` +
+                    `link step wedged (typically a dropped Gio stream event under GJS). Re-run; if it ` +
+                    `persists, raise --timeout or file an issue.`);
+                forceExit(1);
+            }, overallTimeoutMs + HARD_EXIT_GRACE_MS)
+            : null;
+        // Don't let the backstop timer keep an otherwise-finished process alive
+        // (Node keeps the loop up while a timer is armed). `unref` lets the
+        // process end the instant the install returns; `finally` clears it too.
+        hardExitTimerId?.unref?.();
         try {
             await projectInstallNative(args, overallController?.signal);
             await runPostInstallChecks();
@@ -159,7 +199,7 @@ export const installCommand = {
         catch (err) {
             if (overallController !== null && overallController.signal.aborted && isAbortedFromOverallTimeout(err)) {
                 const secs = Math.round(overallTimeoutMs / 100) / 10;
-                console.error(`gjsify install: timed out after ${secs}s — likely a registry slowdown.\n` +
+                console.error(`gjsify install: timed out after ${secs}s — likely a registry slowdown or a wedged extract.\n` +
                     `Re-run, or override with --timeout <ms> (set --timeout 0 to disable the overall budget).`);
                 process.exit(1);
             }
@@ -168,6 +208,8 @@ export const installCommand = {
         finally {
             if (overallTimerId !== null)
                 clearTimeout(overallTimerId);
+            if (hardExitTimerId !== null)
+                clearTimeout(hardExitTimerId);
         }
     },
 };
@@ -194,6 +236,94 @@ function isAbortedFromOverallTimeout(err) {
         return true;
     return false;
 }
+/**
+ * Force a non-zero process exit that is honored on BOTH runtimes.
+ *
+ * Node exits at natural shutdown once `process.exitCode` is set, but GJS has
+ * no atexit hook, so `imports.system.exit` is called directly there —
+ * SpiderMonkey raises its uncatchable exit exception from any context,
+ * including the `setTimeout` continuation the backstop timer runs in. Mirrors
+ * the entry wrapper (`index.ts`) and `setOxcExitCode` (`oxc-resolve.ts`).
+ */
+function forceExit(code) {
+    process.exitCode = code;
+    const gjs = globalThis.imports;
+    if (gjs?.system?.exit) {
+        gjs.system.exit(code);
+        return;
+    }
+    process.exit(code);
+}
+const CLI_PACKAGE_NAME = '@gjsify/cli';
+/** Read a `version` from a package.json IFF its `name` is `@gjsify/cli`. */
+function readCliVersionFrom(pkgJsonPath) {
+    try {
+        if (!existsSync(pkgJsonPath))
+            return null;
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+        if (pkg.name === CLI_PACKAGE_NAME && typeof pkg.version === 'string')
+            return pkg.version;
+    }
+    catch {
+        /* unreadable / malformed — treat as unknown */
+    }
+    return null;
+}
+/**
+ * Version of the @gjsify/cli that is ACTUALLY running (this bundle / lib entry).
+ * Walks up from `import.meta.url` to the nearest `@gjsify/cli` package.json —
+ * same discovery as `self-update`'s `readCurrentVersion`.
+ */
+function readRunningCliVersion() {
+    try {
+        let dir = dirname(resolve(fileURLToPath(import.meta.url)));
+        for (let i = 0; i < 8 && dir !== dirname(dir); i++) {
+            const v = readCliVersionFrom(join(dir, 'package.json'));
+            if (v)
+                return v;
+            dir = dirname(dir);
+        }
+    }
+    catch {
+        /* not a recognizable layout (e.g. tests) */
+    }
+    return null;
+}
+/**
+ * Version of the @gjsify/cli the workspace at `cwd` pins/ships. Prefers the
+ * resolved install (`node_modules/@gjsify/cli`, a hoisted symlink in the
+ * gjsify monorepo or a real install in a consumer), falling back to the
+ * in-repo source so the check also fires on a fresh, not-yet-installed
+ * checkout of the gjsify monorepo itself.
+ */
+function readWorkspaceCliVersion(cwd) {
+    return (readCliVersionFrom(join(cwd, 'node_modules', CLI_PACKAGE_NAME, 'package.json')) ??
+        readCliVersionFrom(join(cwd, 'packages', 'infra', 'cli', 'package.json')));
+}
+/**
+ * Warn (never block) when the running gjsify CLI is a different version than
+ * the @gjsify/cli the workspace pins. Running a mismatched CLI is the root of
+ * two hard-to-diagnose failures documented on real sessions: install stalls (a
+ * mismatched CLI discards the lock → full fresh resolve → a wedge-prone
+ * extract) and silent-wrong-builds (stale CLI, stale bundle semantics). A
+ * single actionable line pointing at `gjsify self-update` beats both silently.
+ * Suppress with GJSIFY_NO_VERSION_SKEW_WARNING=1.
+ */
+function warnOnCliVersionSkew(cwd) {
+    if (process.env.GJSIFY_NO_VERSION_SKEW_WARNING === '1')
+        return;
+    const running = readRunningCliVersion();
+    const pinned = readWorkspaceCliVersion(cwd);
+    if (!running || !pinned || running === pinned)
+        return;
+    console.warn(`gjsify install: version skew — you are running @gjsify/cli v${running}, but this workspace pins ` +
+        `v${pinned}.\n` +
+        `  A mismatched CLI can stall the install (lock discarded → full re-resolve) or silently produce a ` +
+        `wrong build.\n` +
+        `  Align them: run \`gjsify self-update\` (global CLI) or use the workspace-local \`node_modules/.bin/` +
+        `gjsify\`.\n` +
+        `  Suppress this with GJSIFY_NO_VERSION_SKEW_WARNING=1.`);
+}
 function isWorkspaceRoot(cwd) {
     const pkgPath = join(cwd, 'package.json');
     const pkg = readPackageJson(pkgPath);
@@ -241,14 +371,23 @@ async function projectInstallNative(args, signal) {
             `• If instead you want Yarn to manage dependencies, set \`nodeLinker: node-modules\` ` +
             `in .yarnrc.yml and run \`yarn install\` (not \`gjsify install\`).`);
     }
-    // Workspace install (no args, root pkg.json has `workspaces`).
-    // Project-local `gjsify install <pkg>` inside a workspace child still
-    // goes through the single-package code path below (this branch only
-    // fires for the root no-args case, which is the `yarn install`
-    // equivalent).
-    if ((!args.packages || args.packages.length === 0) && isWorkspaceRoot(cwd)) {
-        await workspaceInstall(cwd, args, signal);
-        return;
+    // Workspace install (no args). Runs from the root, OR from any workspace
+    // child — npm/yarn/pnpm resolve the monorepo root when you `install`
+    // inside a member, so `findWorkspaceRoot` walks up from cwd (sanity-checked
+    // that cwd is actually one of that root's workspaces) and installs the whole
+    // workspace there. Without this, a child install treats the child as the
+    // root and tries to resolve its `workspace:`/sibling deps from the registry.
+    // Project-local `gjsify install <pkg>` inside a child still adds the dep to
+    // that child via the single-package path below (this branch is no-args only).
+    if (!args.packages || args.packages.length === 0) {
+        const wsRoot = isWorkspaceRoot(cwd) ? cwd : findWorkspaceRoot(cwd);
+        if (wsRoot) {
+            if (wsRoot !== cwd) {
+                console.log(`gjsify install: resolved workspace root ${wsRoot} (from ${cwd}); installing the workspace.`);
+            }
+            await workspaceInstall(wsRoot, args, signal);
+            return;
+        }
     }
     let specs;
     const pkg = readPackageJson(pkgPath);

package/lib/commands/pack.d.ts

@@ -61,4 +61,17 @@ export interface PackWorkspaceOptions {
  * `wsDir` to an absolute path.
  */
 export declare function packWorkspace(wsDir: string, opts?: PackWorkspaceOptions): Promise<PackResult>;
+/**
+ * Collect every `types`/`typings` path a consumer's TypeScript would resolve for
+ * this package: the top-level `types`/`typings` fields plus every value under a
+ * `"types"` / `"typings"` CONDITION key anywhere in the `exports` tree. Values
+ * are returned normalized (leading `./` stripped). Wildcard subpath patterns
+ * (`./types/*`) are skipped — they can't be checked against concrete files.
+ *
+ * A subpath KEY named `./types` (as in `@gjsify/vite-plugin-blueprint`) is a
+ * subpath, not a condition — it's walked, and the `types` condition INSIDE it is
+ * what gets collected. Per Node's `exports` semantics a bare `types` key (no `.`
+ * prefix) is a condition, so treating it as one here is correct.
+ */
+export declare function collectTypeDeclarationRefs(pkg: Record<string, unknown>): string[];
 export {};

package/lib/commands/pack.js

@@ -124,6 +124,14 @@ export async function packWorkspace(wsDir, opts = {}) {
     // rewritten contents. We use the post-script `pkgAfterScripts` here so
     // that any `files` array modified by a prepack script is honored.
     const filesToPack = collectFiles(wsDir, pkgAfterScripts);
+    // Guard against the #655 class of bug: a `types`/`typings` declaration that
+    // physically exists in the workspace but is excluded from the tarball by the
+    // `files` allowlist. A mass-added `files: ["lib"]` (Phase D.7d, #179) silently
+    // stripped `@gjsify/vite-plugin-blueprint`'s `types/blueprint.d.ts` and
+    // `@gjsify/adwaita-fonts`' `index.d.ts` — the runtime entry still shipped, so
+    // the break was invisible until a TypeScript consumer hit TS2307 / implicit
+    // any. Enforce it at the exact point of packing so it can never recur.
+    assertTypeDeclarationsShipped(wsDir, pkgAfterScripts, filesToPack);
     const entries = [{ name: 'package/', directory: true, mode: 0o755 }];
     const fileMetas = [];
     let unpackedSize = 0;
@@ -218,6 +226,75 @@ function collectFiles(wsDir, pkg) {
     }
     return [...out].sort();
 }
+/**
+ * Collect every `types`/`typings` path a consumer's TypeScript would resolve for
+ * this package: the top-level `types`/`typings` fields plus every value under a
+ * `"types"` / `"typings"` CONDITION key anywhere in the `exports` tree. Values
+ * are returned normalized (leading `./` stripped). Wildcard subpath patterns
+ * (`./types/*`) are skipped — they can't be checked against concrete files.
+ *
+ * A subpath KEY named `./types` (as in `@gjsify/vite-plugin-blueprint`) is a
+ * subpath, not a condition — it's walked, and the `types` condition INSIDE it is
+ * what gets collected. Per Node's `exports` semantics a bare `types` key (no `.`
+ * prefix) is a condition, so treating it as one here is correct.
+ */
+export function collectTypeDeclarationRefs(pkg) {
+    const out = new Set();
+    const add = (v) => {
+        if (typeof v !== 'string')
+            return;
+        const normalized = v.replace(/^\.\//, '');
+        if (normalized.includes('*'))
+            return;
+        out.add(normalized);
+    };
+    for (const field of ['types', 'typings'])
+        add(pkg[field]);
+    const walk = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const e of node)
+                walk(e);
+            return;
+        }
+        for (const [k, v] of Object.entries(node)) {
+            if (k === 'types' || k === 'typings')
+                add(v);
+            else
+                walk(v);
+        }
+    };
+    walk(pkg.exports);
+    return [...out];
+}
+/**
+ * Fail the pack if any `types`/`typings` declaration that physically exists in
+ * the workspace is excluded from the tarball. There is NO legitimate reason to
+ * reference a type file you don't ship — a consumer installing the package gets
+ * silently broken type resolution while the runtime entry keeps working.
+ *
+ * Deliberately only fires for a file that is PRESENT on disk yet absent from the
+ * packed set — the exact, unambiguous #655 mismatch. A `types` path that isn't
+ * built yet (absent on disk) is left to `tsc`/the build to catch, so an unbuilt
+ * dev tree doesn't produce a false positive.
+ */
+function assertTypeDeclarationsShipped(wsDir, pkg, packed) {
+    const packedSet = new Set(packed);
+    const missing = collectTypeDeclarationRefs(pkg).filter((ref) => {
+        const full = join(wsDir, ref);
+        const onDisk = existsSync(full) && statSync(full).isFile();
+        return onDisk && !packedSet.has(ref);
+    });
+    if (missing.length === 0)
+        return;
+    const name = typeof pkg.name === 'string' ? pkg.name : '(unnamed)';
+    const filesField = Array.isArray(pkg.files) ? JSON.stringify(pkg.files) : '(none)';
+    throw new Error(`gjsify pack: ${name} references TypeScript declaration file(s) via "exports"/"types" ` +
+        `that exist on disk but are excluded from the tarball by the "files" allowlist (${filesField}):\n` +
+        missing.map((m) => `  - ${m}`).join('\n') +
+        `\nAdd the missing path(s) to package.json "files" so type resolution isn't silently broken for consumers.`);
+}
 const NEVER_INCLUDED_BASENAMES = new Set([
     '.git',
     '.svn',

package/lib/commands/run.d.ts

@@ -2,6 +2,7 @@ import type { Command } from '../types/index.js';
 interface RunOptions {
     target: string;
     args: string[];
+    workspace?: string;
 }
 export declare const runCommand: Command<unknown, RunOptions>;
 export {};

package/lib/commands/run.js

@@ -14,11 +14,12 @@
 // as a bundle file. Everything else is a script name. Users who want
 // to disambiguate can pass `./<file>` explicitly.
 import { statSync } from 'node:fs';
-import { delimiter, join, resolve } from 'node:path';
+import { basename, delimiter, join, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { readPackageJson } from '../utils/pkg-json-edit.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { discoverWorkspaces } from '@gjsify/workspace';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 export const runCommand = {
     command: 'run <target> [args..]',
@@ -34,6 +35,16 @@ export const runCommand = {
         type: 'string',
         array: true,
         default: [],
+    })
+        .option('workspace', {
+        // npm/yarn-style `-w <name>`: run <target> as a SCRIPT in the
+        // named workspace instead of the current directory. The name
+        // matches the package.json `name`, the workspace-relative path
+        // (e.g. `cli`), or the directory basename — so both
+        // `-w eco-retrofit-cli` and `-w cli` resolve, matching npm.
+        alias: 'w',
+        type: 'string',
+        description: 'Run <target> as a script in the named workspace (by name or path), like `npm run <script> -w <name>`.',
     })
         .parserConfiguration({
         // Preserve `--` as args['--'] so callers can write
@@ -61,6 +72,12 @@ export const runCommand = {
         const positionalArgs = args.args ?? [];
         const doubleDashArgs = (args['--'] ?? []).filter((v) => typeof v === 'string');
         const extraArgs = [...positionalArgs, ...doubleDashArgs];
+        // `-w <name>` (npm/yarn parity): run <target> as a script in the named
+        // workspace's directory rather than the current one. Never file mode.
+        if (typeof args.workspace === 'string' && args.workspace.length > 0) {
+            await runScriptInWorkspace(args.workspace, target, extraArgs);
+            return;
+        }
         // Script lookup wins over file detection. Without this, a bare
         // `gjsify run build` would resolve to a file when a `./build`
         // directory exists in cwd (e.g. meson's build dir from a Vala
@@ -97,6 +114,31 @@ function looksLikeFile(target) {
         return false;
     }
 }
+/**
+ * Resolve a workspace by npm/yarn `--workspace` semantics — matching the
+ * package.json `name`, the workspace-relative path (`packages/infra/cli` or
+ * `cli`), or the directory basename — then run `script` in that workspace's
+ * directory. Mirrors `npm run <script> --workspace <name>`.
+ */
+async function runScriptInWorkspace(name, script, extraArgs) {
+    const root = findWorkspaceRoot(process.cwd()) ?? process.cwd();
+    let workspaces;
+    try {
+        workspaces = discoverWorkspaces(root);
+    }
+    catch (err) {
+        console.error(`gjsify run: could not read workspaces at ${root}: ${err.message}`);
+        return process.exit(1);
+    }
+    const ws = workspaces.find((w) => w.name === name || w.relativeLocation === name || basename(w.location) === name);
+    if (!ws) {
+        const available = workspaces.map((w) => w.relativeLocation).join(', ') || '<none>';
+        console.error(`gjsify run: no workspace "${name}" under ${root} (available: ${available})`);
+        // `return process.exit` — a bare exit falls through under GJS (see runScript).
+        return process.exit(1);
+    }
+    await runScript(script, extraArgs, ws.location);
+}
 /**
  * Run a script declared in the current workspace's `package.json#scripts`.
  * Mirrors `yarn run <script>` semantics:
@@ -107,20 +149,29 @@ function looksLikeFile(target) {
  *   - executed through `shell: true` so `&&` / `|` / env-var refs work
  *     exactly as in package.json scripts (matches npm/yarn)
  */
-async function runScript(script, extraArgs) {
-    const cwd = process.cwd();
+async function runScript(script, extraArgs, cwd = process.cwd()) {
     const pkgPath = join(cwd, 'package.json');
     const pkg = readPackageJson(pkgPath);
     if (!pkg) {
         console.error(`gjsify run: no package.json in ${cwd}`);
-        process.exit(1);
+        // `return process.exit` — under GJS `process.exit` cannot terminate
+        // synchronously (a parked GLib.MainLoop owns the thread): it SCHEDULES
+        // the exit and returns, so a bare call falls through. Here that reached
+        // `tokenizeSimpleCommand(literal)` with `literal === undefined` →
+        // `cannot access property "length"` → the throw raced the scheduled
+        // exit into a second `system.exit` → `m_should_exit assertion failed`
+        // → core dump. The `return` halts the handler so exactly one exit is
+        // scheduled (same discipline as commands/workspace.ts). No-op on Node.
+        return process.exit(1);
     }
     const scripts = pkg.scripts ?? {};
     const literal = scripts[script];
     if (typeof literal !== 'string') {
         const available = Object.keys(scripts).join(', ') || '<none>';
         console.error(`gjsify run: no script "${script}" in ${pkgPath} (available: ${available})`);
-        process.exit(1);
+        // See the `no package.json` branch above — a bare `process.exit` under
+        // GJS falls through to `tokenizeSimpleCommand(undefined)` and core-dumps.
+        return process.exit(1);
     }
     const monorepoRoot = findWorkspaceRoot(cwd);
     const binDirs = [join(cwd, 'node_modules', '.bin')];

package/lib/utils/install-backend-native.js

@@ -920,9 +920,79 @@ async function extractOne(node, prefix, npmrc, log, signal) {
     }
     fs.rmSync(dest, { recursive: true, force: true });
     fs.mkdirSync(dest, { recursive: true });
-    await extractTarball(bytes, dest);
+    await extractWithStallGuard(bytes, dest, node, signal);
     return false;
 }
+/**
+ * Cap over `extractTarball`, which takes no AbortSignal and no timeout of its
+ * own. A single tarball extract completes in well under a second even for
+ * large packages; anything past `EXTRACT_STALL_MS` means the decompress/write
+ * wedged — the classic dropped Gio stream close-event under GJS, a
+ * never-settling await that nothing downstream can break. Unlike a network
+ * fetch (30s per-request budget in @gjsify/npm-registry), extraction has no
+ * self-healing path, so one stuck package used to hang the whole install at
+ * 0% CPU indefinitely. We race the extract against (a) a stall timer and (b)
+ * the overall-install abort signal, so a wedge surfaces as an actionable
+ * error and the install fails fast instead of hanging.
+ *
+ * Rejecting the race does not tear down the underlying (leaked) extract
+ * promise — the process exit that follows reclaims its resources. Override /
+ * disable the cap via `GJSIFY_EXTRACT_STALL_MS` (0 disables the timer; the
+ * signal race still applies).
+ */
+const EXTRACT_STALL_MS = (() => {
+    const raw = process.env.GJSIFY_EXTRACT_STALL_MS;
+    if (raw === undefined)
+        return 120_000;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : 120_000;
+})();
+async function extractWithStallGuard(bytes, dest, node, signal) {
+    // Fast path: nothing to guard against (timer disabled + no signal).
+    if (EXTRACT_STALL_MS === 0 && !signal) {
+        await extractTarball(bytes, dest);
+        return;
+    }
+    let stallTimer;
+    let onAbort;
+    try {
+        await new Promise((resolve, reject) => {
+            // Test seam (matches GJSIFY_INSTALL_FORCE_EXTRACT precedent): simulate
+            // an extract that never settles, so a suite can prove the stall timer
+            // + abort-signal race actually break the wedge. Never call
+            // extractTarball — leave the inner promise pending forever.
+            if (process.env.GJSIFY_TEST_HANG_EXTRACT !== '1') {
+                // extractTarball keeps running if we lose the race; its settlement
+                // (resolve or reject) is a no-op on the already-settled promise.
+                extractTarball(bytes, dest).then(() => resolve(), reject);
+            }
+            if (EXTRACT_STALL_MS > 0) {
+                stallTimer = setTimeout(() => {
+                    reject(new Error(`gjsify install: extract of ${node.name}@${node.version} stalled for ` +
+                        `${Math.round(EXTRACT_STALL_MS / 1000)}s (${node.installPath}) — the tarball ` +
+                        `decompress/write never completed. This is usually a dropped Gio stream event ` +
+                        `under GJS; re-run the install. Override the cap with GJSIFY_EXTRACT_STALL_MS=<ms> ` +
+                        `(0 disables it).`));
+                }, EXTRACT_STALL_MS);
+                stallTimer.unref?.();
+            }
+            if (signal) {
+                if (signal.aborted) {
+                    reject(abortError(signal));
+                    return;
+                }
+                onAbort = () => reject(abortError(signal));
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+        });
+    }
+    finally {
+        if (stallTimer)
+            clearTimeout(stallTimer);
+        if (signal && onAbort)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
 /**
  * Canonical AbortError carrying the signal's `reason` when it is an Error
  * (e.g. the overall-install timeout sentinel), so `isAbortedFromOverallTimeout`

package/lib/utils/oxc-resolve.d.ts

@@ -41,9 +41,12 @@ export declare function shouldUseNativeOxfmt(): Promise<boolean>;
  * the full oxfmt CLI in-process (Node-free); otherwise the npm Node ESM
  * launcher is spawned. `GJSIFY_OXFMT=native|npm` overrides the pick.
  *
- * oxlint: always spawned via its Node ESM launcher with the current Node
- * executable (`process.execPath`) so the JS plugin host is available —
- * required for the `jsPlugins`-wired `gjsify/register-class-order` rule.
+ * oxlint: always spawned via its Node ESM launcher on a real Node host
+ * (`nodeBinary()`: `process.execPath` under Node, PATH `node` under the GJS
+ * bundle where `process.execPath` is the bundle itself) so the JS plugin host
+ * is available — required for the `jsPlugins`-wired `gjsify/register-class-order`
+ * rule. Under GJS a `node` on PATH is required (oxlint has no native bridge
+ * yet); its absence surfaces as a clear OxcNotFoundError, never a hang.
  *
  * Inherits stdio so the tool's own output (diagnostics, reformatted files,
  * summary lines) reaches the user.

package/lib/utils/oxc-resolve.js

@@ -48,11 +48,12 @@
 // (tracked in STATUS.md Open TODOs).
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { spawn } from 'node:child_process';
+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 { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 /**
  * Map Node.js `process.platform` + `arch` (+ musl on Linux) to the
@@ -260,9 +261,12 @@ export async function shouldUseNativeOxfmt() {
  * the full oxfmt CLI in-process (Node-free); otherwise the npm Node ESM
  * launcher is spawned. `GJSIFY_OXFMT=native|npm` overrides the pick.
  *
- * oxlint: always spawned via its Node ESM launcher with the current Node
- * executable (`process.execPath`) so the JS plugin host is available —
- * required for the `jsPlugins`-wired `gjsify/register-class-order` rule.
+ * oxlint: always spawned via its Node ESM launcher on a real Node host
+ * (`nodeBinary()`: `process.execPath` under Node, PATH `node` under the GJS
+ * bundle where `process.execPath` is the bundle itself) so the JS plugin host
+ * is available — required for the `jsPlugins`-wired `gjsify/register-class-order`
+ * rule. Under GJS a `node` on PATH is required (oxlint has no native bridge
+ * yet); its absence surfaces as a clear OxcNotFoundError, never a hang.
  *
  * Inherits stdio so the tool's own output (diagnostics, reformatted files,
  * summary lines) reaches the user.
@@ -287,16 +291,57 @@ export async function runOxc(tool, args, opts = {}) {
     return spawnOxcLauncher(tool, args, opts);
 }
 /**
- * Spawn an oxc tool via its Node ESM launcher (`node_modules/<tool>/bin/…`)
- * with the current Node executable.
+ * Spawn an oxc tool via its Node ESM launcher (`node_modules/<tool>/bin/…`) on
+ * a real Node host. CRITICAL: use `nodeBinary()`, not `process.execPath`
+ * directly — under the committed GJS bundle `process.execPath` is the CLI
+ * bundle path (`gjs`/the `.mjs`), so spawning it re-executes the CLI with the
+ * 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.
  */
 function spawnOxcLauncher(tool, args, opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const launcher = findOxcLauncher(tool, cwd);
-    const node = process.execPath || 'node';
+    const node = nodeBinary();
     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 Promise.resolve(r.status ?? 0);
+    }
     return new Promise((res, rej) => {
         const spawnOpts = { stdio: 'inherit', cwd };
         const child = spawn(node, [launcher, ...args], spawnOpts);