@gjsify/cli 0.11.0 → 0.12.0

package/lib/commands/browse.d.ts

@@ -6,6 +6,8 @@ interface BrowseCliOptions {
     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`). */

package/lib/commands/browse.js

@@ -24,14 +24,16 @@ export function deriveBrowserAppId(name) {
         .replace(/^\.+|\.+$/g, '');
     return `org.gjsify.browser.${slug}`;
 }
-function generateEntry(applicationId, url, title) {
+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}
+    applicationId: ${JSON.stringify(applicationId)},${titleLine}${urlLine}${inspectorLine}${screenshotLine}
 });
 `;
 }
@@ -57,6 +59,14 @@ export const browseCommand = {
         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',
@@ -71,12 +81,16 @@ export const browseCommand = {
         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');
-        writeFileSync(entryPath, generateEntry(applicationId, url, title));
-        console.log(`[gjsify browse] app=${applicationId}${url ? ` url=${url}` : ''}${args.devtools ? ' devtools=1' : ''}`);
+        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) {
@@ -85,8 +99,18 @@ export const browseCommand = {
         }
         // runGjsBundle spreads process.env into the child, so set the devtools
         // gate here (RunGjsBundleOptions has no env field).
-        if (args.devtools)
+        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/debug.js

@@ -56,6 +56,13 @@ await runDevtoolsMcp(storybookProfile(${JSON.stringify(busNameBase)}));
 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.
@@ -77,7 +84,7 @@ export const debugCommand = {
         type: 'string',
     })
         .option('profile', {
-        description: 'Tool profile: generic | storybook | browser (default: auto — storybook if @gjsify/storybook is a dep, browser if @gjsify/devtools-browser is, else generic)',
+        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', {
@@ -103,12 +110,14 @@ export const debugCommand = {
                 ? 'storybook'
                 : hasDep(pkg, '@gjsify/devtools-browser')
                     ? 'browser'
-                    : 'generic');
+                    : 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 === 'browser' || profile === 'cdp'
                     ? (pkg.gjsify?.browse?.applicationId ?? deriveBrowserAppId(pkg.name))
                     : undefined);
         if (!busNameBase) {

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/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.

package/lib/utils/install-global.d.ts

@@ -10,6 +10,47 @@ export interface GlobalLayout {
  * `GJSIFY_GLOBAL_PREFIX` and `GJSIFY_GLOBAL_BIN_DIR` escape hatches for tests.
  */
 export declare function defaultGlobalLayout(): GlobalLayout;
+/**
+ * The GJS-native tooling bridges the global CLI needs to run a build under GJS.
+ *
+ * These are declared OPTIONAL peer dependencies of `@gjsify/cli` (so a plain
+ * `npm install @gjsify/cli` on Node — where the npm `rolldown` / `lightningcss`
+ * / `oxfmt` crates work — does not force a linux prebuild fetch). But a *global
+ * GJS install* exists precisely to run the GJS CLI, where there is NO npm
+ * fallback: `@gjsify/rolldown-native` is the only bundler engine (`gjsify build`
+ * hard-fails without it), `@gjsify/lightningcss-native` backs CSS lowering, and
+ * `@gjsify/oxfmt-native` backs `gjsify format`/`fix`. So the global installer
+ * lays them down explicitly, on top of the cli's resolved runtime deps.
+ *
+ * `@gjsify/rolldown-native` is the load-bearing one (build is dead without it);
+ * the other two degrade gracefully at runtime (CSS / format fall back), so all
+ * three are installed best-effort: a platform with no published prebuild for
+ * the engine just gets a warning + continue, mirroring how the optional-peer
+ * story already degrades on Node.
+ */
+export declare const GJS_ENGINE_PACKAGES: readonly ["@gjsify/rolldown-native", "@gjsify/lightningcss-native", "@gjsify/oxfmt-native"];
+/** True when `<prefix>/node_modules/@gjsify/rolldown-native` is laid down. */
+export declare function hasBundlerEngineInstalled(prefix: string): boolean;
+/**
+ * Best-effort install of the GJS-native engine packages into a global prefix.
+ *
+ * Each engine is installed in its own `installPackages` call so one engine that
+ * has no published prebuild for the current platform (the resolver throws "No
+ * version of … satisfies …", or the registry 404s) does NOT abort the others —
+ * it warns and continues. The bundler engine (`@gjsify/rolldown-native`) is the
+ * one a build truly needs; the failure surfaces a clear, actionable message.
+ *
+ * `version` is the dist-tag / version the top-level `@gjsify/cli` resolved to,
+ * so the engines move in lockstep with the bundle. It may be a concrete version
+ * (`0.11.0`) or a dist-tag (`latest`, `next`); both are valid spec suffixes.
+ *
+ * @param installFn Injected to keep this unit-testable without a real registry —
+ *   defaults to the production `installPackages` backend.
+ */
+export declare function installGjsEnginePackages(prefix: string, version: string, opts?: {
+    verbose?: boolean;
+    installFn?: (spec: string) => Promise<void>;
+}): Promise<void>;
 export interface LinkedBin {
     /** The bin-name (key from `bin` / `gjsify.bin`). */
     name: string;

package/lib/utils/install-global.js

@@ -39,6 +39,80 @@ export function defaultGlobalLayout() {
         binDir: binOverride ?? path.join(home, '.local', 'bin'),
     };
 }
+/**
+ * The GJS-native tooling bridges the global CLI needs to run a build under GJS.
+ *
+ * These are declared OPTIONAL peer dependencies of `@gjsify/cli` (so a plain
+ * `npm install @gjsify/cli` on Node — where the npm `rolldown` / `lightningcss`
+ * / `oxfmt` crates work — does not force a linux prebuild fetch). But a *global
+ * GJS install* exists precisely to run the GJS CLI, where there is NO npm
+ * fallback: `@gjsify/rolldown-native` is the only bundler engine (`gjsify build`
+ * hard-fails without it), `@gjsify/lightningcss-native` backs CSS lowering, and
+ * `@gjsify/oxfmt-native` backs `gjsify format`/`fix`. So the global installer
+ * lays them down explicitly, on top of the cli's resolved runtime deps.
+ *
+ * `@gjsify/rolldown-native` is the load-bearing one (build is dead without it);
+ * the other two degrade gracefully at runtime (CSS / format fall back), so all
+ * three are installed best-effort: a platform with no published prebuild for
+ * the engine just gets a warning + continue, mirroring how the optional-peer
+ * story already degrades on Node.
+ */
+export const GJS_ENGINE_PACKAGES = [
+    '@gjsify/rolldown-native',
+    '@gjsify/lightningcss-native',
+    '@gjsify/oxfmt-native',
+];
+/** True when `<prefix>/node_modules/@gjsify/rolldown-native` is laid down. */
+export function hasBundlerEngineInstalled(prefix) {
+    return fs.existsSync(path.join(prefix, 'node_modules', '@gjsify/rolldown-native', 'package.json'));
+}
+/**
+ * Best-effort install of the GJS-native engine packages into a global prefix.
+ *
+ * Each engine is installed in its own `installPackages` call so one engine that
+ * has no published prebuild for the current platform (the resolver throws "No
+ * version of … satisfies …", or the registry 404s) does NOT abort the others —
+ * it warns and continues. The bundler engine (`@gjsify/rolldown-native`) is the
+ * one a build truly needs; the failure surfaces a clear, actionable message.
+ *
+ * `version` is the dist-tag / version the top-level `@gjsify/cli` resolved to,
+ * so the engines move in lockstep with the bundle. It may be a concrete version
+ * (`0.11.0`) or a dist-tag (`latest`, `next`); both are valid spec suffixes.
+ *
+ * @param installFn Injected to keep this unit-testable without a real registry —
+ *   defaults to the production `installPackages` backend.
+ */
+export async function installGjsEnginePackages(prefix, version, opts = {}) {
+    const verbose = opts.verbose ?? false;
+    const installOne = opts.installFn ??
+        (async (spec) => {
+            // Lazy import to avoid a static cycle (install-backend → … → here)
+            // and to keep this module importable from the lighter unit tests.
+            const { installPackages } = await import('./install-backend.js');
+            await installPackages({ prefix, specs: [spec], verbose });
+        });
+    for (const name of GJS_ENGINE_PACKAGES) {
+        const spec = version ? `${name}@${version}` : name;
+        try {
+            await installOne(spec);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // `@gjsify/rolldown-native` is the bundler engine — its absence
+            // means `gjsify build` (and storybook / anything that builds) will
+            // hard-fail under GJS. Make that one loud; the other two degrade
+            // gracefully so a plain note suffices.
+            if (name === '@gjsify/rolldown-native') {
+                console.warn(`\nWarning: could not install the GJS bundler engine ${name}@${version} — ${msg}\n` +
+                    `  \`gjsify build\` (and storybook / flatpak) will fail under GJS until it is present.\n` +
+                    `  This usually means no prebuild is published for this platform (${process.platform}/${process.arch}).`);
+            }
+            else if (verbose) {
+                console.warn(`gjsify install: optional GJS engine ${name}@${version} not installed — ${msg}`);
+            }
+        }
+    }
+}
 /**
  * Install each top-level package's bin entries into `binDir` as small POSIX
  * `sh` launchers that exec the real bin. Reads each package's installed

package/lib/utils/install-progress.js

@@ -73,14 +73,38 @@ function makeTtyReporter(stream) {
         },
     };
 }
-// ──── Plain reporter — one line per phase begin + end (non-TTY) ────────────
+// ──── Plain reporter — phase begin/end + periodic heartbeat (non-TTY) ──────
+//
+// On a non-TTY (piped to a log file, CI, or captured output) the bar can't
+// `\r`-overwrite, so per-package lines are suppressed to avoid flooding the
+// log. But emitting NOTHING between `beginPhase` and `endPhase` makes a long
+// download/extract phase look frozen — the exact "no further output for 25+
+// minutes" symptom of a slow install. So we emit a low-frequency heartbeat:
+// at most one line per HEARTBEAT_MS, AND only after at least a few packages of
+// real progress, so a fast warm install (most nodes skipped) stays quiet while
+// a genuinely long phase reports `… N/M (X%)` every few seconds. This mirrors
+// what npm (`--loglevel http`) and pnpm log on non-TTY: progress you can watch
+// without it being one line per file.
+const HEARTBEAT_MS = 5_000;
 function makePlainReporter(stream) {
+    let lastHeartbeat = 0;
+    let lastReported = 0;
     return {
         beginPhase(phase, total) {
+            lastHeartbeat = Date.now();
+            lastReported = 0;
             stream.write(`gjsify install: ${PHASE_LABEL[phase]} ${total} package(s)\n`);
         },
-        update() {
-            // Per-package output would flood logs; skip on non-TTY.
+        update(ev) {
+            const now = Date.now();
+            if (now - lastHeartbeat < HEARTBEAT_MS)
+                return;
+            if (ev.current <= lastReported)
+                return;
+            lastHeartbeat = now;
+            lastReported = ev.current;
+            const pct = ev.total > 0 ? Math.round((ev.current / ev.total) * 100) : 0;
+            stream.write(`gjsify install: ${PHASE_LABEL[ev.phase]} ${ev.current}/${ev.total} (${pct}%)\n`);
         },
         endPhase(phase) {
             stream.write(`gjsify install: ${PHASE_LABEL[phase]} done\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.11.0",
+    "version": "0.12.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -120,19 +120,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.11.0",
-        "@gjsify/create-app": "^0.11.0",
-        "@gjsify/node-globals": "^0.11.0",
-        "@gjsify/node-polyfills": "^0.11.0",
-        "@gjsify/npm-registry": "^0.11.0",
-        "@gjsify/resolve-npm": "^0.11.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.11.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.11.0",
-        "@gjsify/semver": "^0.11.0",
-        "@gjsify/tar": "^0.11.0",
-        "@gjsify/tsc": "^0.11.0",
-        "@gjsify/web-polyfills": "^0.11.0",
-        "@gjsify/workspace": "^0.11.0",
+        "@gjsify/buffer": "^0.12.0",
+        "@gjsify/create-app": "^0.12.0",
+        "@gjsify/node-globals": "^0.12.0",
+        "@gjsify/node-polyfills": "^0.12.0",
+        "@gjsify/npm-registry": "^0.12.0",
+        "@gjsify/resolve-npm": "^0.12.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.12.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.12.0",
+        "@gjsify/semver": "^0.12.0",
+        "@gjsify/tar": "^0.12.0",
+        "@gjsify/tsc": "^0.12.0",
+        "@gjsify/web-polyfills": "^0.12.0",
+        "@gjsify/workspace": "^0.12.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -140,13 +140,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.11.0",
+        "@gjsify/unit": "^0.12.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.11.0",
-        "@gjsify/rolldown-native": "^0.11.0"
+        "@gjsify/oxfmt-native": "^0.12.0",
+        "@gjsify/rolldown-native": "^0.12.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {