@gjsify/cli 0.10.0 → 0.12.0

package/lib/cli-app.js

@@ -19,7 +19,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
-import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, } from './commands/index.js';
+import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -114,6 +114,8 @@ export async function runCli(argv) {
         .command(tsc.command, tsc.description, tsc.builder, tsc.handler)
         .command(affected.command, affected.description, affected.builder, affected.handler)
         .command(storybook.command, storybook.description, storybook.builder, storybook.handler)
+        .command(debug.command, debug.description, debug.builder, debug.handler)
+        .command(browse.command, browse.description, browse.builder, browse.handler)
         .demandCommand(1)
         .epilogue(`Running on ${runtimeLabel()}`)
         .help()

package/lib/commands/browse.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from '../types/index.js';
+interface BrowseCliOptions {
+    url?: string;
+    appId?: string;
+    title?: string;
+    globals?: string;
+    out?: string;
+    devtools: boolean;
+    inspectorPort?: number;
+    screenshot?: string;
+    buildOnly: boolean;
+}
+/** Derive a DBus app id from the package name (mirrored by `gjsify debug`). */
+export declare function deriveBrowserAppId(name?: string): string;
+export declare const browseCommand: Command<unknown, BrowseCliOptions>;
+export {};

package/lib/commands/browse.js

@@ -0,0 +1,117 @@
+// `gjsify browse [url]` — launch the Adwaita web browser from
+// @gjsify/devtools-browser, optionally at a URL. Generates a tiny entry that
+// calls runBrowserDevtools(), builds it (`--app gjs --globals auto,dom`), and
+// launches it. Dispatch is IN-PROCESS (runCli + runGjsBundle), like
+// `gjsify storybook`. `--devtools` sets GJSIFY_DEVTOOLS=1 so @gjsify/devtools
+// wires the org.gjsify.Devtools control plane (driveable via `gjsify debug`).
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+function readPackage(cwd) {
+    try {
+        return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Derive a DBus app id from the package name (mirrored by `gjsify debug`). */
+export function deriveBrowserAppId(name) {
+    if (!name)
+        return 'org.gjsify.Browser';
+    const slug = name
+        .replace(/^@/, '')
+        .replace(/[^a-zA-Z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+    return `org.gjsify.browser.${slug}`;
+}
+function generateEntry(applicationId, url, title, inspectorPort, screenshot) {
+    const titleLine = title ? `\n    title: ${JSON.stringify(title)},` : '';
+    const urlLine = url ? `\n    homeUrl: ${JSON.stringify(url)},` : '';
+    const inspectorLine = inspectorPort !== undefined ? `\n    inspectorPort: ${inspectorPort},` : '';
+    const screenshotLine = screenshot ? `\n    screenshot: ${JSON.stringify(screenshot)},` : '';
+    return `// Auto-generated by \`gjsify browse\` — do not edit by hand.
+import { runBrowserDevtools } from '@gjsify/devtools-browser';
+
+await runBrowserDevtools({
+    applicationId: ${JSON.stringify(applicationId)},${titleLine}${urlLine}${inspectorLine}${screenshotLine}
+});
+`;
+}
+export const browseCommand = {
+    command: 'browse [url]',
+    description: 'Launch the Adwaita web browser, optionally pointed at a URL.',
+    builder: (yargs) => yargs
+        .positional('url', { description: 'Initial URL to load (default: page:welcome)', type: 'string' })
+        .option('app-id', {
+        description: 'GApplication id (default: gjsify.browse.applicationId or derived from the package name)',
+        type: 'string',
+    })
+        .option('title', { description: 'Window title', type: 'string' })
+        .option('globals', {
+        description: 'Value for `gjsify build --globals` (default: auto,dom — WebKit/iframe need DOM globals)',
+        type: 'string',
+    })
+        .option('out', {
+        description: 'Output bundle path (default: node_modules/.cache/gjsify-browse)',
+        type: 'string',
+    })
+        .option('devtools', {
+        description: 'Enable the MCP devtools control plane (sets GJSIFY_DEVTOOLS=1)',
+        type: 'boolean',
+        default: false,
+    })
+        .option('inspector-port', {
+        description: "Enable WebKit's remote inspector protocol on this port + the Cdp* methods (implies --devtools)",
+        type: 'number',
+    })
+        .option('screenshot', {
+        description: 'One-shot: load the URL, capture a WebKit screenshot to this path, and exit (CI / quick captures).',
+        type: 'string',
+    })
+        .option('build-only', {
+        description: 'Build the bundle but do not launch it',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const pkg = readPackage(cwd);
+        const config = pkg.gjsify?.browse ?? {};
+        const applicationId = args.appId ?? config.applicationId ?? deriveBrowserAppId(pkg.name);
+        const title = args.title ?? config.title;
+        const globals = args.globals ?? config.globals ?? 'auto,dom';
+        const url = args.url;
+        const inspectorPort = args.inspectorPort ?? config.inspectorPort;
+        // CDP-over-MCP needs the control plane, so --inspector-port implies --devtools.
+        const devtools = args.devtools || inspectorPort !== undefined;
+        const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify-browse');
+        mkdirSync(cacheDir, { recursive: true });
+        const entryPath = join(cacheDir, 'entry.ts');
+        const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, 'browse.gjs.mjs');
+        const screenshotPath = args.screenshot ? resolve(cwd, args.screenshot) : undefined;
+        writeFileSync(entryPath, generateEntry(applicationId, url, title, inspectorPort, screenshotPath));
+        console.log(`[gjsify browse] app=${applicationId}${url ? ` url=${url}` : ''}${devtools ? ' devtools=1' : ''}${inspectorPort !== undefined ? ` inspector-port=${inspectorPort}` : ''}`);
+        const { runCli } = await import('../cli-app.js');
+        await runCli(['build', entryPath, '--app', 'gjs', '--globals', globals, '--outfile', outPath]);
+        if (args.buildOnly) {
+            console.log(`[gjsify browse] built ${outPath}`);
+            return;
+        }
+        // runGjsBundle spreads process.env into the child, so set the devtools
+        // gate here (RunGjsBundleOptions has no env field).
+        if (devtools)
+            process.env.GJSIFY_DEVTOOLS = '1';
+        // Set the inspector env in the LAUNCHER so the spawned gjs has it from
+        // process start. WebKit reads WEBKIT_INSPECTOR_HTTP_SERVER once, at
+        // WebKitInitialize (triggered as the first WebView type initializes —
+        // before the app's own constructor runs), so setting it only inside the
+        // app is too late to bind the server. This is the authoritative place;
+        // the BrowserApplication constructor keeps a best-effort fallback for
+        // direct runBrowserDevtools() callers.
+        if (inspectorPort !== undefined) {
+            process.env.WEBKIT_INSPECTOR_HTTP_SERVER = `127.0.0.1:${inspectorPort}`;
+        }
+        const { runGjsBundle } = await import('../utils/run-gjs.js');
+        await runGjsBundle(outPath, [], { exitOnSuccess: true });
+    },
+};

package/lib/commands/build.js

@@ -99,7 +99,12 @@ export const buildCommand = {
             description: "Comma-separated list of global identifiers, 'auto' (default) to detect automatically from the bundled output, or 'none' to disable. The 'auto' token may be combined with explicit identifiers/groups (e.g. 'auto,dom') for cases where the detector cannot statically see a global because it's accessed via indirection. Each identifier is mapped to the corresponding `@gjsify/<pkg>/register` module and injected into the bundle. See the CLI Reference docs for the full list of known identifiers. Only applies to GJS app builds.",
             type: 'string',
             normalize: true,
-            default: 'auto',
+            // No yargs `default: 'auto'` — a yargs default is
+            // indistinguishable from a user-set value and would always
+            // clobber `package.json#gjsify.globals` / `.gjsifyrc.*` in
+            // config.ts (same footgun as `entryPoints`/`bundler.input`).
+            // The 'auto' fallback is applied post-merge in `Config.forBuild`
+            // so precedence is: CLI flag > config file > 'auto'.
         })
             .option('shebang', {
             description: 'Prepend a target-appropriate shebang to the output and mark it executable (chmod 755): `#!/usr/bin/env -S gjs -m` for --app gjs, `#!/usr/bin/env node` for --app node. Applies to GJS and Node app builds with a single --outfile. Default: false (use --shebang to enable, or set `shebang: true` in `.gjsifyrc.js`).',

package/lib/commands/debug.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from '../types/index.js';
+interface DebugCliOptions {
+    busName?: string;
+    profile?: string;
+    globals?: string;
+    out?: string;
+    buildOnly: boolean;
+}
+export declare const debugCommand: Command<unknown, DebugCliOptions>;
+export {};

package/lib/commands/debug.js

@@ -0,0 +1,148 @@
+// `gjsify debug` — launch an MCP↔devtools bridge for a running, devtools-enabled
+// gjsify app (its `org.gjsify.Devtools` DBus control plane). An MCP client (e.g.
+// Claude Code) uses this as its server command; the bridge speaks JSON-RPC on
+// stdio and translates tool calls to the app's DBus interface.
+//
+// Dispatch is IN-PROCESS (runCli + runGjsBundle), like `gjsify storybook`. The
+// generated entry resolves `@gjsify/devtools-mcp` from the CONSUMER's
+// node_modules (so it stays out of the CLI's own deps). The bridge is built
+// `--app gjs --shebang` and launched with stdio inherited, so its JSON-RPC
+// stdout reaches the client untouched.
+//
+// CRITICAL: this command logs ONLY to stderr — stdout is the MCP channel.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+function readPackage(cwd) {
+    try {
+        return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Mirror of `commands/storybook.ts` deriveAppId — the storybook app's DBus id. */
+function deriveStorybookAppId(name) {
+    if (!name)
+        return 'org.gjsify.Storybook';
+    const slug = name
+        .replace(/^@/, '')
+        .replace(/[^a-zA-Z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+    return `org.gjsify.storybook.${slug}`;
+}
+/** Mirror of `commands/browse.ts` deriveBrowserAppId — the browser app's DBus id. */
+function deriveBrowserAppId(name) {
+    if (!name)
+        return 'org.gjsify.Browser';
+    const slug = name
+        .replace(/^@/, '')
+        .replace(/[^a-zA-Z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+    return `org.gjsify.browser.${slug}`;
+}
+function hasDep(pkg, name) {
+    return Boolean(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
+}
+function generateEntry(profile, busNameBase, name, version) {
+    if (profile === 'storybook') {
+        return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
+import { runDevtoolsMcp, storybookProfile } from '@gjsify/devtools-mcp';
+
+await runDevtoolsMcp(storybookProfile(${JSON.stringify(busNameBase)}));
+`;
+    }
+    if (profile === 'browser') {
+        return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
+import { runDevtoolsMcp, browserProfile } from '@gjsify/devtools-mcp';
+
+await runDevtoolsMcp(browserProfile(${JSON.stringify(busNameBase)}));
+`;
+    }
+    if (profile === 'cdp') {
+        return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
+import { runDevtoolsMcp, cdpProfile } from '@gjsify/devtools-mcp';
+
+await runDevtoolsMcp(cdpProfile(${JSON.stringify(busNameBase)}));
+`;
+    }
+    return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
+import { runDevtoolsMcp } from '@gjsify/devtools-mcp';
+
+await runDevtoolsMcp({
+    name: ${JSON.stringify(name)},
+    version: ${JSON.stringify(version)},
+    busNameBase: ${JSON.stringify(busNameBase)},
+});
+`;
+}
+export const debugCommand = {
+    command: 'debug',
+    description: 'Launch an MCP bridge for a devtools-enabled gjsify app (org.gjsify.Devtools).',
+    builder: (yargs) => yargs
+        .option('bus-name', {
+        description: 'App DBus base name (default: gjsify.devtools.busNameBase, or the storybook app-id)',
+        type: 'string',
+    })
+        .option('profile', {
+        description: 'Tool profile: generic | storybook | browser | cdp (default: auto — storybook if @gjsify/storybook is a dep, browser if @gjsify/devtools-browser is, cdp if @gjsify/devtools-cdp is, else generic)',
+        type: 'string',
+    })
+        .option('globals', {
+        description: 'Value for `gjsify build --globals` (default: auto)',
+        type: 'string',
+    })
+        .option('out', {
+        description: 'Output bundle path (default: node_modules/.cache/gjsify-debug)',
+        type: 'string',
+    })
+        .option('build-only', {
+        description: 'Build the bridge bundle but do not launch it (for a .mcp.json command pointing at the bundle)',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const pkg = readPackage(cwd);
+        const config = pkg.gjsify?.devtools ?? {};
+        const profile = args.profile ??
+            config.profile ??
+            (hasDep(pkg, '@gjsify/storybook')
+                ? 'storybook'
+                : hasDep(pkg, '@gjsify/devtools-browser')
+                    ? 'browser'
+                    : hasDep(pkg, '@gjsify/devtools-cdp')
+                        ? 'cdp'
+                        : 'generic');
+        const busNameBase = args.busName ??
+            config.busNameBase ??
+            (profile === 'storybook'
+                ? (pkg.gjsify?.storybook?.applicationId ?? deriveStorybookAppId(pkg.name))
+                : profile === 'browser' || profile === 'cdp'
+                    ? (pkg.gjsify?.browse?.applicationId ?? deriveBrowserAppId(pkg.name))
+                    : undefined);
+        if (!busNameBase) {
+            console.error('gjsify debug: no bus name — set package.json#gjsify.devtools.busNameBase or pass --bus-name <org.example.App>');
+            process.exit(1);
+        }
+        const globals = args.globals ?? config.globals ?? 'auto';
+        const name = pkg.name ? `${pkg.name}-devtools` : 'gjsify-devtools';
+        const version = '0.8.0';
+        const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify-debug');
+        mkdirSync(cacheDir, { recursive: true });
+        const entryPath = join(cacheDir, 'entry.ts');
+        const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, 'bridge.gjs.mjs');
+        writeFileSync(entryPath, generateEntry(profile, busNameBase, name, version));
+        // stderr only — stdout is the MCP JSON-RPC channel.
+        console.error(`[gjsify debug] profile=${profile} bus=${busNameBase}`);
+        // In-process build (runtime-agnostic), then launch with stdio inherited
+        // so the bridge's JSON-RPC stdin/stdout are the client's pipes.
+        const { runCli } = await import('../cli-app.js');
+        await runCli(['build', entryPath, '--app', 'gjs', '--shebang', '--globals', globals, '--outfile', outPath]);
+        if (args.buildOnly) {
+            console.error(`[gjsify debug] built ${outPath}`);
+            return;
+        }
+        const { runGjsBundle } = await import('../utils/run-gjs.js');
+        await runGjsBundle(outPath, [], { exitOnSuccess: true });
+    },
+};

package/lib/commands/index.d.ts

@@ -31,3 +31,5 @@ export * from './barrels.js';
 export * from './tsc.js';
 export * from './affected.js';
 export * from './storybook.js';
+export * from './debug.js';
+export * from './browse.js';

package/lib/commands/index.js

@@ -31,3 +31,5 @@ export * from './barrels.js';
 export * from './tsc.js';
 export * from './affected.js';
 export * from './storybook.js';
+export * from './debug.js';
+export * from './browse.js';

package/lib/commands/install.js

@@ -25,7 +25,7 @@ import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
 import { detectNativePackages } from '../utils/detect-native-packages.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
-import { binDirOnPath, defaultGlobalLayout, linkGlobalBins, specToPackageName } from '../utils/install-global.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
 // (212+ sub-packages × 600+ external deps in the gjsify monorepo itself)
@@ -920,12 +920,27 @@ async function installGlobalAndLink(specs, opts) {
     mkdirSync(layout.prefix, { recursive: true });
     console.log(`gjsify install --global  → ${layout.prefix}`);
     console.log(`                  bins → ${layout.binDir}`);
-    await installPackages({
+    const result = await installPackages({
         prefix: layout.prefix,
         specs,
         verbose: opts.verbose,
     });
     const packageNames = specs.map(specToPackageName);
+    // A global GJS install of `@gjsify/cli` must also lay down the GJS-native
+    // bundler engine (`@gjsify/rolldown-native`) + the sibling format/CSS
+    // bridges. They are declared OPTIONAL peers of `@gjsify/cli` (so plain
+    // `npm install @gjsify/cli` on Node doesn't force a linux prebuild), and
+    // the native backend doesn't resolve peerDependencies at all — so without
+    // this they'd never be installed, and `gjsify build` would hard-fail under
+    // GJS ("no usable bundler engine"). Installed best-effort at the cli's
+    // resolved version so they move in lockstep with the bundle; a platform
+    // with no published prebuild degrades to a warning. Must run BEFORE
+    // linkGlobalBins so the launcher's detectNativePackages() bakes the
+    // engine's prebuild dirs into the wrapper's GI_TYPELIB_PATH/LD_LIBRARY_PATH.
+    if (packageNames.includes('@gjsify/cli')) {
+        const cliVersion = result.installed.find((r) => r.name === '@gjsify/cli')?.version ?? 'latest';
+        await installGjsEnginePackages(layout.prefix, cliVersion, { verbose: opts.verbose });
+    }
     const created = linkGlobalBins(packageNames, layout);
     if (created.length === 0) {
         console.warn('\nNo bins declared (neither `gjsify.bin` nor `bin` in package.json) — nothing was symlinked.');

package/lib/commands/self-update.js

@@ -16,7 +16,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fetchPackument } from '@gjsify/npm-registry';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
-import { defaultGlobalLayout, linkGlobalBins } from '../utils/install-global.js';
+import { defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, } from '../utils/install-global.js';
 const PACKAGE_NAME = '@gjsify/cli';
 export const selfUpdateCommand = {
     command: 'self-update',
@@ -76,12 +76,31 @@ export const selfUpdateCommand = {
             return;
         }
         console.log(`Latest matching --tag ${args.tag}: v${target}`);
-        if (currentVersion === target && !args.force) {
+        // A version match is NOT sufficient to declare "up to date": a global
+        // GJS install can be on the right `@gjsify/cli` version yet be MISSING
+        // the GJS bundler engine (`@gjsify/rolldown-native`) — it's an optional
+        // peer the native backend never resolves, so an install.mjs bootstrap
+        // before this fix laid down the cli but not the engine, and `gjsify
+        // build` hard-fails ("no usable bundler engine"). When the version
+        // matches but the engine is absent, REPAIR it (install the engine +
+        // re-link) instead of printing "Already up to date". `--skip-deps`
+        // still honours its contract (don't touch on-disk deps) and `--check`
+        // only reports, so neither triggers the repair.
+        const engineMissing = installedAtPrefix && !hasBundlerEngineInstalled(layout.prefix);
+        const needsEngineRepair = engineMissing && !args.skipDeps && !args.check;
+        if (currentVersion === target && !args.force && !needsEngineRepair) {
             console.log(`Already up to date (v${target}).`);
+            if (engineMissing && args.skipDeps) {
+                console.log(`Note: the GJS bundler engine @gjsify/rolldown-native is not installed — ` +
+                    `re-run without --skip-deps to repair it (\`gjsify build\` needs it under GJS).`);
+            }
             if (!args.check)
                 console.log(`Run with --force to reinstall anyway.`);
             return;
         }
+        if (needsEngineRepair && currentVersion === target && !args.force) {
+            console.log(`@gjsify/cli is at v${target} but the GJS bundler engine @gjsify/rolldown-native is missing — repairing.`);
+        }
         if (args.check) {
             console.log(currentVersion ? `Update available: v${currentVersion} → v${target}` : `Install required: → v${target}`);
             process.exit(1);
@@ -125,6 +144,14 @@ export const selfUpdateCommand = {
             process.exit(1);
             return;
         }
+        // Lay down (or repair) the GJS-native engine bridges in lockstep with
+        // the bundle — same set + best-effort handling as the global installer.
+        // Gated on `pullDeps` so `--skip-deps` keeps its bundle-only contract.
+        // Must run BEFORE linkGlobalBins so the launcher's detectNativePackages()
+        // bakes the engine's prebuild dirs into the wrapper env preamble.
+        if (pullDeps) {
+            await installGjsEnginePackages(layout.prefix, target, { verbose: false });
+        }
         const linked = linkGlobalBins([PACKAGE_NAME], layout);
         if (linked.length === 0) {
             console.warn('self-update: install completed but no bins were linked — package.json may be missing a `bin` field.');

package/lib/commands/tsc.js

@@ -129,12 +129,23 @@ export const tscCommand = {
         // `gjs` is not on PATH (ENOENT), transparently fall back to upstream
         // `typescript` under Node when available.
         if (bundlePath) {
+            // A failed spawn (notably ENOENT when `gjs` is absent) emits BOTH
+            // 'error' AND 'close'. The 'error' handler owns the outcome (Node
+            // fallback or a clear exit), so the 'close' handler must NOT also
+            // exit — otherwise it races and exits with the spawn errno (e.g.
+            // ENOENT → -2), which surfaced as a misleading 254 and pre-empted the
+            // fallback (gjsify tsc died instead of degrading to upstream tsc on a
+            // gjs-less host such as a CI runner).
+            let gjsSpawnFailed = false;
             const child = spawn('gjs', ['-m', bundlePath, ...tscArgs], { env, stdio: 'inherit' });
             await new Promise((resolvePromise) => {
                 child.on('close', (code) => {
+                    if (gjsSpawnFailed)
+                        return;
                     process.exit(code ?? 1);
                 });
                 child.on('error', (err) => {
+                    gjsSpawnFailed = true;
                     if (err.code === 'ENOENT' && nodeTscPath) {
                         // No gjs on PATH — run upstream typescript under Node.
                         runNodeTsc();

package/lib/config.js

@@ -137,6 +137,12 @@ export class Config {
             configData.consoleShim = cliArgs.consoleShim;
         if (cliArgs.globals !== undefined)
             configData.globals = cliArgs.globals;
+        // Fallback applied post-merge (not as a yargs `default:`) so a
+        // `globals` declared in package.json#gjsify / `.gjsifyrc.*` survives —
+        // a yargs default is indistinguishable from a user value and would
+        // overwrite the config one. Precedence: CLI flag > config file > 'auto'
+        // (mirrors the `bundler.input` fallback below).
+        configData.globals ??= 'auto';
         if (cliArgs.shebang !== undefined)
             configData.shebang = cliArgs.shebang;
         if (cliArgs.excludeGlobals) {

package/lib/index.js

@@ -6,4 +6,23 @@
 // This file is just the executable wrapper around `runCli`.
 import { hideBin } from 'yargs/helpers';
 import { runCli } from './cli-app.js';
-await runCli(hideBin(process.argv));
+try {
+    await runCli(hideBin(process.argv));
+}
+catch (err) {
+    // A command handler (or yargs) rejected. Print the message cleanly and exit
+    // 1 on BOTH runtimes. Without this, the rejection escapes the entry's
+    // top-level await as an UNHANDLED rejection: Node prints it, but GJS surfaces
+    // a scary `Gjs-CRITICAL **: Module … threw an exception` that buries the
+    // real, already-actionable message (e.g. "gjsify build: no usable bundler
+    // engine under GJS — build the facade first or run under Node"). See #597.
+    console.error(err instanceof Error ? err.message : String(err));
+    if (process.env.GJSIFY_DEBUG && err instanceof Error && err.stack)
+        console.error(err.stack);
+    // `process.exitCode` is the gentle Node idiom (streams flush). GJS has no
+    // atexit hook and would exit 0 at natural shutdown, so force a non-zero exit
+    // via `imports.system.exit` there (no-op on Node, where `imports` is unset).
+    process.exitCode = 1;
+    const gjs = globalThis.imports;
+    gjs?.system?.exit?.(1);
+}

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

@@ -631,8 +631,14 @@ async function downloadAndExtractAll(nodes, prefix, npmrc, log, signal, progress
     const concurrency = Math.max(1, Math.min(DEFAULT_CONCURRENCY, queue.length));
     progress?.beginPhase('download', queue.length);
     let completed = 0;
-    const tickProgress = (node) => {
+    // Count how many nodes were already correctly materialised on disk and
+    // skipped (the npm "unchanged" set). Surfaced in the summary log so a warm
+    // install makes it obvious why the phase finished in seconds.
+    let skipped = 0;
+    const tickProgress = (node, wasSkipped) => {
         completed++;
+        if (wasSkipped)
+            skipped++;
         progress?.update({
             phase: 'download',
             current: completed,
@@ -648,30 +654,91 @@ async function downloadAndExtractAll(nodes, prefix, npmrc, log, signal, progress
     const splitAt = depth1End < 0 ? queue.length : depth1End;
     // Serial root pass.
     while (cursor < splitAt) {
+        if (signal?.aborted)
+            throw abortError(signal);
         const node = queue[cursor++];
         if (!node)
             break;
-        await extractOne(node, prefix, npmrc, log, signal);
-        tickProgress(node);
+        const wasSkipped = await extractOne(node, prefix, npmrc, log, signal);
+        tickProgress(node, wasSkipped);
     }
     // Concurrent nested pass.
     for (let i = 0; i < concurrency; i++) {
         workers.push((async () => {
             while (true) {
+                // Honour an aborted overall-install budget inside the pool.
+                // Without this, a fired --timeout (or Ctrl-C) only aborts
+                // the NETWORK fetches; a tree that is mostly cache-hits /
+                // already-extracted keeps churning the extract loop to
+                // completion, so the install never actually stops when
+                // asked to (a contributor to the observed "it never
+                // completed; I killed it" hang).
+                if (signal?.aborted)
+                    throw abortError(signal);
                 const idx = cursor++;
                 if (idx >= queue.length)
                     return;
                 const node = queue[idx];
                 if (!node)
                     return;
-                await extractOne(node, prefix, npmrc, log, signal);
-                tickProgress(node);
+                const wasSkipped = await extractOne(node, prefix, npmrc, log, signal);
+                tickProgress(node, wasSkipped);
             }
         })());
     }
     await Promise.all(workers);
     progress?.endPhase('download');
+    if (skipped > 0) {
+        log('install: %d/%d package(s) already up to date — extracted %d', skipped, queue.length, queue.length - skipped);
+    }
 }
+/**
+ * Is `name@version` already correctly materialised at `dest`? Reads
+ * `<dest>/package.json` and returns true iff its `name` AND `version` match the
+ * resolved node exactly. This is the npm/yarn/pnpm "unchanged node" check — an
+ * already-present, correct copy is skipped instead of being `rm`-ed and
+ * re-extracted.
+ *
+ * Conservative by design: a missing / unreadable / unparseable package.json, or
+ * ANY name/version mismatch, returns false so the caller falls through to the
+ * full rm + extract. The only thing this fast-paths is the exact-match case,
+ * which is the overwhelming majority of nodes on a warm re-install (the whole
+ * resolved tree minus the genuinely-new subtree). Skipping the re-extract is
+ * what turns a warm `gjsify install` on a 2000+-package workspace from a
+ * many-minute re-extract of every tarball (each gunzip routed through GJS's
+ * Gio.ZlibDecompressor on the single GLib main loop) into a near-instant no-op.
+ */
+function isAlreadyExtracted(dest, node) {
+    const manifestPath = path.join(dest, 'package.json');
+    let raw;
+    try {
+        raw = fs.readFileSync(manifestPath, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // Match version exactly. Match name too when present — a stale dir from
+        // a previous resolve could hold a different package at the same path
+        // (e.g. a nested placement that moved), in which case the version alone
+        // could coincidentally collide. A missing `name` (rare, malformed) is
+        // tolerated as long as the version matches.
+        if (parsed.version !== node.version)
+            return false;
+        if (typeof parsed.name === 'string' && parsed.name !== node.name)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Download + extract one node, or skip it when an identical copy is already on
+ * disk. Returns `true` when the node was skipped (already up to date), `false`
+ * when it was (re-)extracted.
+ */
 async function extractOne(node, prefix, npmrc, log, signal) {
     const dest = path.join(prefix, node.installPath);
     // Defense-in-depth against the workspace-source-wipe data-loss bug:
@@ -683,6 +750,15 @@ async function extractOne(node, prefix, npmrc, log, signal) {
     // source dir — the realpath check additionally rejects a `dest` that
     // resolves THROUGH a symlink into a directory outside node_modules.
     assertNodeModulesDest(dest, node);
+    // Idempotent fast-path: the package is already extracted at the resolved
+    // version. Skip the cache read + rm + re-extract entirely — this is the
+    // npm/yarn/pnpm default (only added/changed nodes are written), and it is
+    // the dominant cost on a warm re-install. Force a full re-extract with
+    // GJSIFY_INSTALL_FORCE_EXTRACT=1 (debug / corrupted-tree recovery).
+    if (process.env.GJSIFY_INSTALL_FORCE_EXTRACT !== '1' && isAlreadyExtracted(dest, node)) {
+        log('up-to-date: %s@%s (already extracted at %s)', node.name, node.version, node.installPath);
+        return true;
+    }
     // Hit the content-addressable cache before touching the network.
     // Tarballs are immutable per SRI integrity, so a hash hit means the
     // cached bytes are byte-identical to whatever the registry would
@@ -717,6 +793,21 @@ async function extractOne(node, prefix, npmrc, log, signal) {
     fs.rmSync(dest, { recursive: true, force: true });
     fs.mkdirSync(dest, { recursive: true });
     await extractTarball(bytes, dest);
+    return false;
+}
+/**
+ * Canonical AbortError carrying the signal's `reason` when it is an Error
+ * (e.g. the overall-install timeout sentinel), so `isAbortedFromOverallTimeout`
+ * in the install command recognises it and prints the actionable timeout
+ * message instead of a raw stack.
+ */
+function abortError(signal) {
+    const reason = signal && 'reason' in signal ? signal.reason : undefined;
+    if (reason instanceof Error)
+        return reason;
+    const err = new Error('Aborted');
+    err.name = 'AbortError';
+    return err;
 }
 /**
  * Guard: a tarball may only be extracted into a `node_modules/` directory.