@gjsify/cli 0.4.42 → 0.4.44

package/lib/bundler-pick.js

@@ -1,14 +1,19 @@
-// Phase D-2.B.5b — runtime bundler pick.
+// Runtime bundler pick (Phase D-2.B.5b → D-3.1 runtime-aware default).
 //
-// Default behavior: call npm `rolldown(opts).write(opts.output)` exactly
-// as before. Setting `GJSIFY_BUNDLER=native` opts into the
-// `@gjsify/rolldown-native` Vala/Rust prebuild via `bundleWithPlugins()`.
+// The engine is chosen by `shouldUseNative()` per host runtime:
+//   - Node: npm `rolldown(opts).write(opts.output)`.
+//   - GJS:  `@gjsify/rolldown-native` (the Vala/Rust prebuild) via
+//           `bundleWithPlugins()`. npm `rolldown` is a Rust N-API addon
+//           that CANNOT load under GJS, so the native engine is the GJS
+//           DEFAULT — no env var needed (this is the Node-free build
+//           chain's bundler). This writes the BundleOutput to disk
+//           (`runNativeBundle`), replicating npm rolldown's `.write()`
+//           incl. nested chunk/asset subdirectories.
 //
-// The native path is only attempted under GJS — under Node it falls
-// back to npm rolldown silently. Under GJS, if the prebuild isn't
-// loadable for the running architecture, we throw so the caller
-// notices the configuration mismatch instead of silently using a
-// different code path.
+// `GJSIFY_BUNDLER=native|npm` is an explicit override: `native` forces
+// the native engine and throws if its prebuild isn't loadable for the
+// running architecture (instead of silently switching engines); `npm`
+// forces the npm crate (Node only).
 //
 // Plugin shape conversion: rolldown plugins may declare hooks either
 // as bare functions (`load(id)`) or as `{filter, handler}` objects.
@@ -264,10 +269,23 @@ async function runNativeBundle(finalOpts) {
     if (outDir)
         await fs.mkdir(outDir, { recursive: true });
     for (const item of result.output) {
+        // A single `--outfile` build collapses to that exact path; otherwise
+        // each chunk/asset lands at `outDir/<fileName>`. Nested fileNames
+        // (e.g. `_virtual/_rolldown/runtime.js` from a `--library` /
+        // code-split build) live in subdirectories npm rolldown's `.write()`
+        // creates implicitly — replicate that here, or `writeFile` throws
+        // ENOENT on the missing parent (regression: `--library` under the
+        // native GJS engine). Also write text assets for `.write()` parity.
+        const target = outputCfg.file && item.type === 'chunk' && result.output.length === 1
+            ? outputCfg.file
+            : path.join(outDir, item.fileName);
+        await fs.mkdir(path.dirname(target), { recursive: true });
         if (item.type === 'chunk') {
-            const target = outputCfg.file && result.output.length === 1 ? outputCfg.file : path.join(outDir, item.fileName);
             await fs.writeFile(target, item.code, 'utf8');
         }
+        else if (item.sourceText !== undefined) {
+            await fs.writeFile(target, item.sourceText, 'utf8');
+        }
     }
     // Synthesize the RolldownOutput shape downstream code touches.
     return synthRolldownOutput(result);

package/lib/commands/affected.js

@@ -10,15 +10,19 @@
 // Classifier table (first-match wins) handles the cases that aren't a
 // straightforward "file lives in workspace X":
 //
-//   1. GLOBAL_TRIGGERS  — change touches infra the classifier itself
-//      depends on (`@gjsify/workspace`, `@gjsify/cli`, the bundler
-//      plugins, the lockfile, root tsconfig / package.json, this very
-//      workflow file). Emits `global=true` → CI must run the full
-//      suite. We can't trust the closure when the algorithm that
-//      computes it just changed.
+//   1. IGNORE  — pure-docs / *.md / website / refs/ submodule / unrelated
+//      workflow files / LICENSE / .gitignore. Discarded FIRST, before every
+//      other rule: an ignored file is never build-relevant, not even inside
+//      a GLOBAL_TRIGGERS directory (e.g. `packages/infra/cli/README.md` must
+//      not force a full run just because `packages/infra/cli/` is a global
+//      trigger). Ignore wins over global.
 //
-//   2. IGNORE  — pure-docs / website / refs/ submodule / unrelated
-//      workflow files. Discard; do not contribute to seeds.
+//   2. GLOBAL_TRIGGERS  — a non-ignored change touching infra the classifier
+//      itself depends on (`@gjsify/workspace`, `@gjsify/cli`, the bundler
+//      plugins, the lockfile, root tsconfig / package.json, this very
+//      workflow file). Emits `global=true` → CI must run the full suite. We
+//      can't trust the closure when the algorithm that computes it just
+//      changed.
 //
 //   3. TEST_ONLY  — every changed file under ONE workspace is a spec
 //      file, e2e fixture, or integration test. Seed = that workspace
@@ -133,22 +137,11 @@ function classifyAndExpand(workspaces, rootDir, changedFiles) {
             skipAll: true,
         };
     }
-    // Global triggers short-circuit immediately.
-    for (const f of files) {
-        for (const re of GLOBAL_TRIGGERS) {
-            if (re.test(f)) {
-                return {
-                    global: true,
-                    reason: `global-trigger ${re.source} matched ${f}`,
-                    workspaces: workspaces.map((w) => w.name),
-                    runE2E: true,
-                    runIntegration: true,
-                    skipAll: false,
-                };
-            }
-        }
-    }
-    // Drop ignored files; collect the remainder.
+    // Drop ignored files FIRST — before the global-trigger check. An ignored
+    // file (docs, *.md, LICENSE, .gitignore, …) is never build-relevant, not
+    // even inside a GLOBAL_TRIGGERS directory: `packages/infra/cli/README.md`
+    // must NOT force a full run just because `packages/infra/cli/` is a global
+    // trigger. Ignore wins over global.
     const remaining = [];
     for (const f of files) {
         if (IGNORE.some((re) => re.test(f)))
@@ -165,6 +158,21 @@ function classifyAndExpand(workspaces, rootDir, changedFiles) {
             skipAll: true,
         };
     }
+    // Global triggers short-circuit — checked on the non-ignored remainder.
+    for (const f of remaining) {
+        for (const re of GLOBAL_TRIGGERS) {
+            if (re.test(f)) {
+                return {
+                    global: true,
+                    reason: `global-trigger ${re.source} matched ${f}`,
+                    workspaces: workspaces.map((w) => w.name),
+                    runE2E: true,
+                    runIntegration: true,
+                    skipAll: false,
+                };
+            }
+        }
+    }
     // Map files → workspaces. Files outside any workspace stay in `unmatched`.
     const { matched, unmatched } = workspacesForChangedFiles(workspaces, rootDir, remaining);
     // Unmatched-but-not-ignored files are suspicious enough to fall back to

package/lib/commands/flatpak/index.d.ts

@@ -2,10 +2,11 @@ import type { Command } from '../../types/index.js';
 import { flatpakInitCommand } from './init.js';
 import { flatpakBuildCommand } from './build.js';
 import { flatpakDepsCommand } from './deps.js';
+import { flatpakSourcesCommand } from './sources.js';
 import { flatpakCiCommand } from './ci.js';
 import { flatpakCheckCommand } from './check.js';
 import { flatpakSyncFlathubCommand } from './sync-flathub.js';
 import { flatpakDiffCommand } from './diff.js';
 import { flatpakReleaseCommand } from './release.js';
 export declare const flatpakCommand: Command;
-export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, flatpakCheckCommand, flatpakSyncFlathubCommand, flatpakDiffCommand, flatpakReleaseCommand, };
+export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakSourcesCommand, flatpakCiCommand, flatpakCheckCommand, flatpakSyncFlathubCommand, flatpakDiffCommand, flatpakReleaseCommand, };

package/lib/commands/flatpak/index.js

@@ -6,6 +6,7 @@
 import { flatpakInitCommand } from './init.js';
 import { flatpakBuildCommand } from './build.js';
 import { flatpakDepsCommand } from './deps.js';
+import { flatpakSourcesCommand } from './sources.js';
 import { flatpakCiCommand } from './ci.js';
 import { flatpakCheckCommand } from './check.js';
 import { flatpakSyncFlathubCommand } from './sync-flathub.js';
@@ -13,12 +14,13 @@ import { flatpakDiffCommand } from './diff.js';
 import { flatpakReleaseCommand } from './release.js';
 export const flatpakCommand = {
     command: 'flatpak <subcommand>',
-    description: 'Flatpak toolchain: init/build/deps/ci/check/sync-flathub/diff/release subcommands for shipping GJS apps and CLIs as Flatpaks.',
+    description: 'Flatpak toolchain: init/build/deps/sources/ci/check/sync-flathub/diff/release subcommands for shipping GJS apps and CLIs as Flatpaks.',
     builder: (yargs) => {
         return yargs
             .command(flatpakInitCommand.command, flatpakInitCommand.description, flatpakInitCommand.builder, flatpakInitCommand.handler)
             .command(flatpakBuildCommand.command, flatpakBuildCommand.description, flatpakBuildCommand.builder, flatpakBuildCommand.handler)
             .command(flatpakDepsCommand.command, flatpakDepsCommand.description, flatpakDepsCommand.builder, flatpakDepsCommand.handler)
+            .command(flatpakSourcesCommand.command, flatpakSourcesCommand.description, flatpakSourcesCommand.builder, flatpakSourcesCommand.handler)
             .command(flatpakCiCommand.command, flatpakCiCommand.description, flatpakCiCommand.builder, flatpakCiCommand.handler)
             .command(flatpakCheckCommand.command, flatpakCheckCommand.description, flatpakCheckCommand.builder, flatpakCheckCommand.handler)
             .command(flatpakSyncFlathubCommand.command, flatpakSyncFlathubCommand.description, flatpakSyncFlathubCommand.builder, flatpakSyncFlathubCommand.handler)
@@ -28,4 +30,4 @@ export const flatpakCommand = {
             .strict();
     },
 };
-export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, flatpakCheckCommand, flatpakSyncFlathubCommand, flatpakDiffCommand, flatpakReleaseCommand, };
+export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakSourcesCommand, flatpakCiCommand, flatpakCheckCommand, flatpakSyncFlathubCommand, flatpakDiffCommand, flatpakReleaseCommand, };

package/lib/commands/flatpak/sources.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from '../../types/index.js';
+type LockfileType = 'gjsify' | 'npm' | 'yarn' | 'pnpm';
+interface FlatpakSourcesOptions {
+    lockfile?: string;
+    type?: LockfileType;
+    out?: string;
+    cacheRoot?: string;
+    printModule?: boolean;
+}
+export declare const flatpakSourcesCommand: Command<unknown, FlatpakSourcesOptions>;
+export {};

package/lib/commands/flatpak/sources.js

@@ -0,0 +1,318 @@
+// `gjsify flatpak sources` — turn a lockfile into a flatpak-builder `sources`
+// array so a Flathub build (which forbids network access) can vendor every npm
+// tarball offline.
+//
+// Auto-detects the lockfile format — gjsify's own `gjsify-lock.json`, npm's
+// `package-lock.json`, classic `yarn.lock`, or pnpm's `pnpm-lock.yaml` — so it
+// is a Node-free, dependency-free replacement for the Python
+// `flatpak-node-generator` that `gjsify flatpak deps` wraps (one tool, no pipx).
+//
+// Each locked tarball becomes a flatpak `file` source that downloads straight
+// into gjsify's content-addressed tarball cache layout:
+//
+//   $XDG_CACHE_HOME/gjsify/tarballs/v1/<algo>/<hex[0:2]>/<full-hex>.tgz
+//
+// (the exact path `install-tarball-cache.ts` computes from the SRI integrity).
+// flatpak-builder fetches them in its network-allowed download phase; the build
+// itself then runs `gjsify install --immutable` fully offline, finding every
+// tarball in the pre-populated cache.
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { Buffer } from 'node:buffer';
+/** Checksum algorithms flatpak-builder accepts on a `file` source. */
+const FLATPAK_ALGOS = new Set(['sha256', 'sha512']);
+/** Parse an SRI integrity (`sha512-<base64>`) into `{ algorithm, hex }`. Mirrors
+ *  `install-tarball-cache.ts` so the emitted cache paths match byte-for-byte. */
+function parseSri(integrity) {
+    if (!integrity)
+        return null;
+    const dash = integrity.indexOf('-');
+    if (dash <= 0 || dash === integrity.length - 1)
+        return null;
+    const algorithm = integrity.slice(0, dash);
+    const b64 = integrity.slice(dash + 1).replace(/=+$/, '');
+    let hex;
+    try {
+        hex = Buffer.from(b64, 'base64').toString('hex');
+    }
+    catch {
+        return null;
+    }
+    if (hex.length < 4)
+        return null;
+    return { algorithm, hex };
+}
+/** gjsify-lock.json + package-lock.json share npm's v2/v3 `packages` shape:
+ *  a map keyed by install path, each with `resolved` + `integrity`. Falls back
+ *  to npm's v1 nested `dependencies` tree. */
+function parseNpmLike(json) {
+    const out = [];
+    const root = json;
+    const packages = root.packages;
+    if (packages && typeof packages === 'object') {
+        for (const entry of Object.values(packages)) {
+            if (entry?.resolved && entry.integrity)
+                out.push({ url: entry.resolved, integrity: entry.integrity });
+        }
+        if (out.length > 0)
+            return out;
+    }
+    // npm lockfileVersion 1: nested `dependencies` tree.
+    if (root.dependencies && typeof root.dependencies === 'object')
+        collectV1Deps(root.dependencies, out);
+    return out;
+}
+function collectV1Deps(deps, out) {
+    for (const node of Object.values(deps)) {
+        if (node?.resolved && node.integrity)
+            out.push({ url: node.resolved, integrity: node.integrity });
+        if (node?.dependencies)
+            collectV1Deps(node.dependencies, out);
+    }
+}
+/** Classic (v1) `yarn.lock`: blank-line-separated blocks, each with a
+ *  `resolved "<url>#<sha1>"` and (yarn ≥1.x) an `integrity sha512-…` line.
+ *  Yarn Berry (v2+) is rejected — its `checksum` is a zip-cache hash, not a
+ *  tarball SRI, so the tarball can't be verified from the lockfile. */
+function parseYarnClassic(text) {
+    if (/^__metadata:/m.test(text)) {
+        throw new Error('gjsify flatpak sources: Yarn Berry (v2+) yarn.lock is not supported — its `checksum` is ' +
+            'a cache hash, not a tarball SRI. Run `gjsify install` to produce a gjsify-lock.json, ' +
+            'or use a classic (v1) yarn.lock.');
+    }
+    const out = [];
+    let noIntegrity = 0;
+    for (const block of text.split(/\n\s*\n/)) {
+        const rm = block.match(/^\s+resolved\s+"([^"]+)"/m);
+        if (!rm)
+            continue;
+        const url = rm[1].replace(/#.*$/, ''); // strip the trailing #<sha1> fragment
+        const im = block.match(/^\s+integrity\s+(\S+)/m);
+        if (!im) {
+            noIntegrity++;
+            continue;
+        }
+        out.push({ url, integrity: im[1] });
+    }
+    if (noIntegrity > 0) {
+        console.warn(`[gjsify flatpak sources] ${noIntegrity} yarn.lock entr(y/ies) had no integrity (pre-1.x format) ` +
+            'and were skipped — re-lock with a modern yarn or use `gjsify install`.');
+    }
+    return out;
+}
+/** pnpm-lock.yaml: each `packages:` entry's `resolution.integrity` is the
+ *  tarball SRI; the URL is `resolution.tarball` or reconstructed from the key.
+ *  Handles both v9 (`name@version`) and v5/6 (`/name/version`) key shapes.
+ *
+ *  A small targeted scanner instead of a full YAML parser: pnpm always writes
+ *  the resolution inline (`resolution: {integrity: …}`), so this needs no extra
+ *  dependency and stays bundle-light. It reads ONLY the top-level `packages:`
+ *  block (not `snapshots:`/`importers:`), keys at exactly 2-space indent. */
+function parsePnpm(text) {
+    const out = [];
+    let inPackages = false;
+    let currentKey = null;
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/\r$/, '');
+        if (/^packages:\s*$/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        // A non-indented, non-comment line ends the `packages:` section.
+        if (inPackages && /^[^\s#]/.test(line))
+            inPackages = false;
+        if (!inPackages)
+            continue;
+        // Package key: exactly 2-space indent, quoted or bare, ending in ':'.
+        const keyM = line.match(/^ {2}(?:'([^']+)'|"([^"]+)"|([^\s#][^:]*)):\s*$/);
+        if (keyM) {
+            currentKey = keyM[1] ?? keyM[2] ?? keyM[3] ?? null;
+            continue;
+        }
+        // Inline resolution: `resolution: {integrity: sha…, tarball: …}`.
+        const resM = line.match(/resolution:\s*\{([^}]*)\}/);
+        if (resM && currentKey) {
+            const intM = resM[1].match(/integrity:\s*(sha\d+-[A-Za-z0-9+/=]+)/);
+            if (!intM)
+                continue;
+            const tarM = resM[1].match(/tarball:\s*([^\s,}]+)/);
+            const url = tarM ? tarM[1] : reconstructNpmTarballUrl(currentKey);
+            if (url)
+                out.push({ url, integrity: intM[1] });
+        }
+    }
+    return out;
+}
+/** Reconstruct the canonical npm tarball URL from a pnpm package key. Returns
+ *  null for non-registry refs (aliases, git, …). */
+function reconstructNpmTarballUrl(key) {
+    let name;
+    let version;
+    if (key.startsWith('/')) {
+        // v5/6: /name/version or /@scope/name/version, optional `_peer` suffix.
+        const k = key.slice(1).replace(/_.*$/, '');
+        const idx = k.lastIndexOf('/');
+        if (idx <= 0)
+            return null;
+        name = k.slice(0, idx);
+        version = k.slice(idx + 1);
+    }
+    else {
+        // v9: name@version, optional `(peer@x)` suffixes.
+        const k = key.replace(/\(.*\)$/, '');
+        const at = k.lastIndexOf('@');
+        if (at <= 0)
+            return null;
+        name = k.slice(0, at);
+        version = k.slice(at + 1);
+    }
+    // Only plain registry semver versions — skip aliases / protocols.
+    if (!name || !version || /[@:/]/.test(version))
+        return null;
+    const basename = name.slice(name.lastIndexOf('/') + 1);
+    return `https://registry.npmjs.org/${name}/-/${basename}-${version}.tgz`;
+}
+function detectType(file) {
+    const base = file.toLowerCase();
+    if (base.endsWith('pnpm-lock.yaml'))
+        return 'pnpm';
+    if (base.endsWith('yarn.lock'))
+        return 'yarn';
+    if (base.endsWith('package-lock.json'))
+        return 'npm';
+    return 'gjsify';
+}
+function defaultLockfile(cwd) {
+    for (const f of ['gjsify-lock.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml']) {
+        if (existsSync(join(cwd, f)))
+            return f;
+    }
+    return 'gjsify-lock.json'; // surfaces a clear "not found" later
+}
+function parseLockfile(path, type) {
+    const text = readFileSync(path, 'utf-8');
+    if (type === 'yarn')
+        return parseYarnClassic(text);
+    if (type === 'pnpm')
+        return parsePnpm(text);
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`gjsify flatpak sources: ${path} is not valid JSON: ${err.message}`);
+    }
+    return parseNpmLike(json);
+}
+// --- command ---------------------------------------------------------------
+export const flatpakSourcesCommand = {
+    command: 'sources',
+    description: 'Generate an offline flatpak-builder `sources` array from any lockfile (gjsify-lock.json / package-lock.json / yarn.lock / pnpm-lock.yaml) for a no-network Flathub build.',
+    builder: (yargs) => {
+        return yargs
+            .option('lockfile', {
+            description: 'Path to the lockfile. Default: the first of gjsify-lock.json / package-lock.json / yarn.lock / pnpm-lock.yaml found in cwd.',
+            type: 'string',
+            normalize: true,
+        })
+            .option('type', {
+            description: 'Lockfile format. Default: detected from the filename.',
+            choices: ['gjsify', 'npm', 'yarn', 'pnpm'],
+        })
+            .option('out', {
+            description: 'Output JSON sources file',
+            type: 'string',
+            default: 'gjsify-sources.json',
+            normalize: true,
+        })
+            .option('cache-root', {
+            description: 'Relative dir the tarballs download into; point XDG_CACHE_HOME here in the build. ' +
+                'Tarballs land at <cache-root>/gjsify/tarballs/v1/<algo>/<shard>/<hex>.tgz.',
+            type: 'string',
+            default: 'flatpak-gjsify-cache',
+        })
+            .option('print-module', {
+            description: 'Also print a ready-to-paste flatpak manifest module snippet to stderr',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const lockfile = resolve(cwd, args.lockfile ?? defaultLockfile(cwd));
+        if (!existsSync(lockfile)) {
+            throw new Error(`gjsify flatpak sources: lockfile ${lockfile} not found. ` +
+                'Run `gjsify install` (or npm/yarn/pnpm) first, or pass --lockfile.');
+        }
+        const type = args.type ?? detectType(lockfile);
+        const tarballs = parseLockfile(lockfile, type);
+        const cacheRoot = args.cacheRoot ?? 'flatpak-gjsify-cache';
+        // Dedupe by content hash — the same tarball is locked at many install
+        // paths; flatpak rejects duplicate dest/filename pairs.
+        const byHex = new Map();
+        let skippedSri = 0;
+        let skippedAlgo = 0;
+        for (const { url, integrity } of tarballs) {
+            const sri = parseSri(integrity);
+            if (!sri) {
+                skippedSri++;
+                continue;
+            }
+            if (!FLATPAK_ALGOS.has(sri.algorithm)) {
+                skippedAlgo++;
+                continue;
+            }
+            const key = `${sri.algorithm}:${sri.hex}`;
+            if (byHex.has(key))
+                continue;
+            const source = {
+                type: 'file',
+                url,
+                dest: `${cacheRoot}/gjsify/tarballs/v1/${sri.algorithm}/${sri.hex.slice(0, 2)}`,
+                'dest-filename': `${sri.hex}.tgz`,
+            };
+            // FLATPAK_ALGOS gates this to exactly sha256 / sha512.
+            if (sri.algorithm === 'sha512')
+                source.sha512 = sri.hex;
+            else
+                source.sha256 = sri.hex;
+            byHex.set(key, source);
+        }
+        // Stable order (by url) so the generated file diffs cleanly across runs.
+        const sources = [...byHex.values()].sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
+        const out = resolve(cwd, args.out ?? 'gjsify-sources.json');
+        mkdirSync(dirname(out), { recursive: true });
+        writeFileSync(out, JSON.stringify(sources, null, 2) + '\n');
+        console.log(`[gjsify flatpak sources] wrote ${out} — ${sources.length} tarball source(s) from ${type} lockfile` +
+            ` (${tarballs.length} locked entr${tarballs.length === 1 ? 'y' : 'ies'})` +
+            (skippedSri ? `, ${skippedSri} without a usable integrity skipped` : '') +
+            (skippedAlgo ? `, ${skippedAlgo} non-sha256/512 skipped` : ''));
+        if (args.printModule) {
+            console.error(buildModuleSnippet(args.out ?? 'gjsify-sources.json', cacheRoot));
+        }
+    },
+};
+/** A copy-pasteable flatpak manifest module that consumes the generated
+ *  sources file and runs a fully offline `gjsify install`. */
+function buildModuleSnippet(sourcesFile, cacheRoot) {
+    return [
+        '',
+        '# Add the generated sources to your app module and point XDG_CACHE_HOME',
+        '# at the vendored cache before running gjsify offline. Example module:',
+        '#',
+        '#   {',
+        '#     "name": "my-app",',
+        '#     "buildsystem": "simple",',
+        '#     "build-commands": [',
+        `#       "export XDG_CACHE_HOME=\\"$(pwd)/${cacheRoot}\\"",`,
+        '#       "gjsify install --immutable",',
+        '#       "gjsify build src/main.ts --app gjs --outfile /app/bin/my-app"',
+        '#     ],',
+        '#     "sources": [',
+        '#       { "type": "dir", "path": "." },',
+        `#       "${sourcesFile}"`,
+        '#     ]',
+        '#   }',
+        '',
+    ].join('\n');
+}

package/lib/commands/self-update.d.ts

@@ -3,6 +3,7 @@ interface SelfUpdateOptions {
     check?: boolean;
     force?: boolean;
     tag: string;
+    skipDeps?: boolean;
 }
 export declare const selfUpdateCommand: Command<unknown, SelfUpdateOptions>;
 export {};

package/lib/commands/self-update.js

@@ -36,6 +36,13 @@ export const selfUpdateCommand = {
         description: 'npm dist-tag or pinned version to install (e.g. `latest`, `next`, `0.5.0`).',
         type: 'string',
         default: 'latest',
+    })
+        .option('skip-deps', {
+        description: 'Update only the @gjsify/cli bundle itself; do not pull its runtime dependencies ' +
+            '(rolldown, lightningcss, @gjsify/tsc, the native gi:// bridges, …). Faster, but can ' +
+            'leave the on-disk runtime deps stale relative to the new bundle.',
+        type: 'boolean',
+        default: false,
     }),
     handler: async (args) => {
         const layout = defaultGlobalLayout();
@@ -80,21 +87,33 @@ export const selfUpdateCommand = {
             process.exit(1);
             return;
         }
-        console.log(`Installing ${PACKAGE_NAME}@${target} ...`);
-        // `@gjsify/cli` is a self-contained GJS bundle: every workspace dep
-        // (`@gjsify/node-polyfills`, `@gjsify/v8`, …) is bundled into the
-        // published `dist/cli.gjs.mjs` artifact and must NOT be resolved as
-        // a separate npm package. `skipDeps: true` limits the native install
-        // backend to fetching the top-level tarball only, avoiding spurious
-        // packument requests for workspace-internal packages that are not
-        // published to the public registry (which previously caused a
-        // 406 Not Acceptable → fatal crash on the `@gjsify/v8` packument).
+        // `@gjsify/cli` ships two runtimes from one package: the Node `bin`
+        // (`lib/index.js`, which imports its deps from `node_modules`) and the
+        // self-contained GJS bundle (`dist/cli.gjs.mjs`, which inlines them).
+        // The published `dependencies` therefore must cover everything `lib/**`
+        // resolves at runtime PLUS the pieces only the GJS runtime loads from
+        // disk (the `gi://` native typelib bridges via the launcher's
+        // GI_TYPELIB_PATH, `rolldown`/`lightningcss` native addons, the
+        // separate `@gjsify/tsc` bundle, `@gjsify/create-app`'s disk templates).
+        //
+        // By DEFAULT self-update now resolves that full production `dependencies`
+        // tree (`skipDeps: false`) so the on-disk runtime deps move in lockstep
+        // with the freshly-installed bundle instead of skewing behind it. This is
+        // safe today because every `@gjsify/*` package — including the
+        // `@gjsify/v8` that once 404'd → 406 and forced `skipDeps: true`
+        // unconditionally — is now published to the public registry.
+        //
+        // `--skip-deps` restores the old fast path: fetch only the top-level
+        // `@gjsify/cli` tarball and re-link the bin, leaving runtime deps untouched.
+        const pullDeps = !args.skipDeps;
+        const depNote = pullDeps ? ' + runtime dependencies' : ' (bundle only)';
+        console.log(`Installing ${PACKAGE_NAME}@${target}${depNote} ...`);
         try {
             await installPackages({
                 prefix: layout.prefix,
                 specs: [`${PACKAGE_NAME}@${target}`],
                 verbose: false,
-                skipDeps: true,
+                skipDeps: !pullDeps,
             });
         }
         catch (err) {
@@ -114,6 +133,12 @@ export const selfUpdateCommand = {
             }
         }
         console.log(`\nUpdated ${PACKAGE_NAME} to v${target}.`);
+        if (pullDeps) {
+            console.log('Runtime dependencies were resolved alongside the bundle.');
+        }
+        else {
+            console.log('Bundle-only update (--skip-deps): on-disk runtime dependencies were left unchanged.');
+        }
     },
 };
 /**

package/package.json

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