@gjsify/cli 0.23.0 → 0.24.2

package/lib/commands/showcase.js

@@ -7,8 +7,7 @@ import { ensurePkgDir } from './dlx.js';
 import { parseSpec } from '../utils/parse-spec.js';
 import { resolveNodeEntry } from '../utils/resolve-gjs-entry.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
-import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
-import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, } from '../utils/runtimes.js';
+import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, defaultExampleRuntime, } from '../utils/runtimes.js';
 function readCliVersion() {
     try {
         const pkgUrl = new URL('../../package.json', import.meta.url);
@@ -19,6 +18,27 @@ function readCliVersion() {
         return undefined;
     }
 }
+/**
+ * `[gjsify <version>] ` for the banner — the CLI naming ITSELF.
+ *
+ * `showcase` pins the showcase package to the CLI's own version, so a stale CLI
+ * silently runs a stale showcase, and the only version in the output was the
+ * showcase's. That is not a hypothetical: every runner that caches an unpinned
+ * bin reuses whatever it resolved once (`npx @gjsify/cli` → a 0.4.x `_npx`
+ * entry; `deno run npm:@gjsify/cli` → whatever sits in `DENO_DIR`), so the same
+ * command produced 0.24.1 under bunx, 0.4.25 under npx and 0.23.0 under deno on
+ * ONE machine on ONE day — and the two old ones failed in ways that read as
+ * gjsify bugs. gjsify cannot flush somebody else's cache, but it can stop the
+ * output from hiding which gjsify is talking.
+ */
+function runningAs(cliVersion) {
+    return cliVersion ? `[gjsify ${cliVersion}] ` : '';
+}
+/** Pinned invocations for the three runners that cache an unpinned bin. */
+const PIN_HINT = 'A package runner reuses a CACHED copy of an unpinned bin. Force the current one:\n' +
+    '    npx @gjsify/cli@latest showcase <name>\n' +
+    '    bunx @gjsify/cli@latest showcase <name>\n' +
+    '    deno run -A --reload npm:@gjsify/cli@latest showcase <name>';
 export const showcaseCommand = {
     command: 'showcase [name]',
     description: 'List or run curated gjsify showcase applications.',
@@ -38,18 +58,23 @@ export const showcaseCommand = {
         default: false,
     })
         .option('runtime', {
-        // Runtime selector, mirroring `gjsify storybook --runtime`. The
-        // default FOLLOWS the host runtime the CLI executes in (gjs under
-        // gjs, node under node/bun/deno). gjs runs the showcase's GJS
-        // bundle via `gjsify dlx`; node/bun/deno run its `--app node`
-        // bundle on that runtime. Validated against the showcase's
-        // declared `gjsify.example.runtimes` — a GTK-only showcase
-        // requested under node fails with a clear message, not a crash.
+        // Runtime selector, mirroring `gjsify storybook --runtime`. gjs
+        // runs the showcase's GJS bundle via `gjsify dlx`; node/bun/deno
+        // run its `--app node` bundle on that runtime. Validated against
+        // the showcase's declared `gjsify.example.runtimes` — a GTK-only
+        // showcase requested under node fails with a clear message, not
+        // a crash.
+        //
+        // NO eager yargs `default:` — it is resolved in the handler via
+        // `defaultExampleRuntime()` (gjs when gjs is installed, else the
+        // host runtime). Two reasons: yargs evaluates a `default:` while
+        // BUILDING the command, before we know a showcase was even
+        // named, and resolving it probes PATH — work that must not
+        // happen for `gjsify showcase` in list mode.
         type: 'string',
         choices: EXAMPLE_RUNTIMES,
-        default: hostRuntime(),
-        defaultDescription: 'host runtime (gjs on gjs, else node/bun/deno)',
-        description: 'Runtime to run the showcase on: gjs | node | bun | deno (default: the host runtime). node/bun/deno run its `--app node` bundle.',
+        defaultDescription: 'gjs when gjs is installed, else the host runtime',
+        description: 'Runtime to run the showcase on: gjs | node | bun | deno (default: gjs when installed, else the host runtime). node/bun/deno run its `--app node` bundle.',
     }),
     handler: async (args) => {
         // List mode: no name given, or --list flag
@@ -116,7 +141,7 @@ export const showcaseCommand = {
             // `return` — bare `process.exit` falls through under GJS (see above).
             return process.exit(1);
         }
-        const runtime = (args.runtime ?? hostRuntime());
+        const runtime = (args.runtime ?? defaultExampleRuntime());
         if (!isExampleRuntime(runtime)) {
             console.error(`Unknown --runtime "${runtime}" (expected: ${EXAMPLE_RUNTIMES.join(', ')}).`);
             // `return` — bare `process.exit` falls through under GJS (see above).
@@ -142,7 +167,7 @@ export const showcaseCommand = {
         // newer CLI assumes (the `@gjsify/http-soup-bridge` regression
         // reported against `@gjsify/cli@0.3.17`).
         const dlxSpec = cliVersion ? `${showcase.packageName}@${cliVersion}` : showcase.packageName;
-        console.log(`Running showcase: ${showcase.name} (via gjsify dlx ${dlxSpec})\n`);
+        console.log(`Running showcase: ${showcase.name} ${runningAs(cliVersion)}(via gjsify dlx ${dlxSpec})\n`);
         // Dispatch `dlx` IN-PROCESS (not `spawn(process.execPath, [cliBin, …])`):
         // under the committed GJS bundle `process.execPath` is `gjs` and
         // `../index.js` is the Node entry, so the spawn ran `gjs cli.gjs.mjs
@@ -165,7 +190,7 @@ export const showcaseCommand = {
  * in-tree build), falling back to `gjsify dlx`'s install-into-cache for a
  * published showcase. Returns the directory containing the package.json.
  */
-async function resolveShowcaseDir(showcase, cliVersion) {
+async function resolveShowcaseDir(showcase, cliVersion, extraSpecs = []) {
     // Local-first: a workspace showcase resolves via its own package name.
     try {
         const req = createRequire(import.meta.url);
@@ -181,6 +206,7 @@ async function resolveShowcaseDir(showcase, cliVersion) {
         verbose: false,
         cacheMaxAge: 60 * 24 * 7,
         frozen: false,
+        extraSpecs,
     });
     return pkgDir;
 }
@@ -193,7 +219,16 @@ async function resolveShowcaseDir(showcase, cliVersion) {
 async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
     let pkgDir;
     try {
-        pkgDir = await resolveShowcaseDir(showcase, cliVersion);
+        // `@gjsify/node-gi` is the `gi://` bridge the `--app node` bundle
+        // resolves at RUNTIME. Showcases carry it as a devDependency (it is a
+        // build input for them), so a dlx tree — the package plus its own
+        // `dependencies` — does not contain it and the launch died with "add
+        // @gjsify/node-gi as a dependency": advice the user cannot act on,
+        // since the tree is the CLI's cache. The launcher knows the runtime, so
+        // it supplies the bridge. Pinned to the CLI's version like the showcase
+        // itself, so the bridge and the bundle move together.
+        const nodeGiSpec = cliVersion ? `@gjsify/node-gi@${cliVersion}` : '@gjsify/node-gi';
+        pkgDir = await resolveShowcaseDir(showcase, cliVersion, [nodeGiSpec]);
     }
     catch (err) {
         console.error(`Could not resolve showcase "${showcase.name}": ${err.message}`);
@@ -218,10 +253,19 @@ async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
         entry = resolveNodeEntry(pkgDir);
     }
     catch (err) {
-        console.error(`Cannot run showcase "${showcase.name}" on ${runtime}: ${err.message}`);
+        // The showcase promised this runtime and did not ship the bundle. Two
+        // causes, and the user can only act on one of them, so name both: the
+        // package version is genuinely broken (fixed by a newer one), or THIS
+        // CLI is a cached old copy that pinned a genuinely broken old showcase.
+        const version = typeof pkg.name === 'string' ? `${pkg.name}@${cliVersion ?? '?'}` : showcase.packageName;
+        console.error(`Cannot run showcase "${showcase.name}" on ${runtime}: ${err.message}\n\n` +
+            `  ${version} declares --runtime ${runtime} but ships no \`--app node\` bundle, so that\n` +
+            `  version of the showcase cannot run there. You are running gjsify ${cliVersion ?? '(unknown)'},\n` +
+            `  and \`showcase\` pins the showcase to the CLI's own version.\n\n  ${PIN_HINT}\n\n` +
+            `  Or run it on GJS, which every showcase ships: gjsify showcase ${showcase.name} --runtime gjs`);
         return process.exit(1);
     }
-    console.log(`Running showcase: ${showcase.name} on ${runtime} (${entry})\n`);
+    console.log(`Running showcase: ${showcase.name} ${runningAs(cliVersion)}on ${runtime} (${entry})\n`);
     // Terminal call — exit on success.
     await runRuntimeBundle(runtime, entry, [], { exitOnSuccess: true });
 }

package/lib/commands/storybook.js

@@ -181,9 +181,12 @@ export const storybookCommand = {
             // typelib env wired like `gjsify run`. All three need @gjsify/node-gi
             // (the storybook uses gi://), kept external by the bundler.
             const { computeNativeEnvForBundle } = await import('../utils/run-gjs.js');
-            const { resolveNodeGi, nodeBinary } = await import('../utils/run-node.js');
+            const { resolveNodeGiForBundle, nodeBinary } = await import('../utils/run-node.js');
             const { RUNTIMES } = await import('../utils/runtimes.js');
-            if (!resolveNodeGi(cwd)) {
+            // Same resolution base as `runRuntimeBundle`: the bundle's own dir
+            // first (that is where the runtime resolves the external specifier
+            // from), cwd as the fallback.
+            if (!resolveNodeGiForBundle(outPath, cwd)) {
                 throw new Error(`Cannot run the storybook on ${runtime}: \`@gjsify/node-gi\` is not installed. ` +
                     `Add @gjsify/node-gi as a dependency to run the storybook on ${runtime}.`);
             }

package/lib/utils/bin-shim.d.ts

@@ -64,3 +64,52 @@ export declare function buildLauncherShims(opts: {
     cmd: string;
     ps1: string;
 };
+/**
+ * The `sh` preamble a GJS launcher needs so `imports.gi.X` resolves against the
+ * `@gjsify/*` native prebuilds installed next to it.
+ *
+ * WHY IT SCANS AT RUN TIME INSTEAD OF BAKING A LIST
+ *
+ * The typelib/library lookup happens inside the GJS runtime, before a single
+ * line of the CLI bundle runs, so the env MUST be set by the launcher — the CLI
+ * cannot repair it from the inside. The launcher used to bake the directories
+ * `detectNativePackages()` found at INSTALL time, which makes the env a SNAPSHOT
+ * of one moment:
+ *
+ *   - a native package installed into the same prefix LATER (`gjsify install -g
+ *     @gjsify/<x>-native`, a project `gjsify install` that adds one) is invisible
+ *     until something happens to rewrite the launcher;
+ *   - and if the scan comes back empty for any reason, the launcher is written
+ *     with NO preamble at all and nothing says so. The failure then surfaces
+ *     much later and somewhere else entirely — `gjsify build` dying with "no
+ *     usable bundler engine under GJS" in an unrelated project, which reads as a
+ *     broken install rather than a stale launcher. That is what shipped in
+ *     v0.24.1: a `~/.local/bin/gjsify` with a bare `exec gjs -m …` line while
+ *     `@gjsify/rolldown-native` sat correctly installed in the prefix.
+ *
+ * Deriving the env from disk on every launch removes both: the launcher states
+ * WHERE to look rather than WHAT was there, so it cannot go stale, and an empty
+ * result is a fact about the current prefix instead of a silently frozen one.
+ * The cost is a handful of shell globs per launch (they are builtins, and a
+ * pattern that matches nothing stays literal and is rejected by `[ -d ]`).
+ *
+ * `bakedDirs` covers what a run-time scan of `scanRoot` structurally cannot see:
+ * `detectNativePackages()` walks UP the directory chain, so in a hoisted layout
+ * a prebuild may live in an ancestor's `node_modules`. Those are still embedded
+ * verbatim; only the primary root is dynamic. Duplicates are harmless (both
+ * variables are search paths).
+ *
+ * Windows is deliberately excluded: there the `sh` file is only reachable from
+ * git-bash/MSYS, the real launchers are the `.cmd`/`.ps1` companions built by
+ * {@link buildLauncherShims} from the same baked list, and `PATH` doubles as the
+ * DLL search path with `;` separators. It keeps the snapshot behaviour.
+ *
+ * @param scanRoot Directory whose `node_modules` is globbed at launch time.
+ * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
+ *   are embedded (entries inside it are dropped — the scan finds them).
+ * @returns the preamble, or `''` when there is nothing to export.
+ */
+export declare function buildNativeEnvPreamble(scanRoot: string, bakedDirs?: readonly string[], target?: {
+    platform?: string;
+    arch?: string;
+}): string;

package/lib/utils/bin-shim.js

@@ -24,6 +24,7 @@
 // All three re-derive the interpreter from the target's shebang, so a bin
 // declaring `#!/usr/bin/env node` and one declaring `#!/usr/bin/env -S gjs -m`
 // both work without the caller knowing which it is.
+import { libraryPathVar, prebuildDirCandidates } from './detect-native-packages.js';
 // Matches `#!<prog> <args>` and `#!/usr/bin/env [-S] [K=V ...] <prog> <args>`.
 // Verbatim from cmd-shim's `shebangExpr`.
 const SHEBANG_RE = /^#!\s*(?:\/usr\/bin\/env\s+(?:-S\s+)?((?:[^ \t=]+=[^ \t=]+\s+)*))?([^ \t]+)(.*)$/;
@@ -244,3 +245,107 @@ export function buildLauncherShims(opts) {
             'exit $LASTEXITCODE\n';
     return { cmd, ps1 };
 }
+/** POSIX `sh` single-quoting — the one place the escape lives. */
+function shQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The `sh` preamble a GJS launcher needs so `imports.gi.X` resolves against the
+ * `@gjsify/*` native prebuilds installed next to it.
+ *
+ * WHY IT SCANS AT RUN TIME INSTEAD OF BAKING A LIST
+ *
+ * The typelib/library lookup happens inside the GJS runtime, before a single
+ * line of the CLI bundle runs, so the env MUST be set by the launcher — the CLI
+ * cannot repair it from the inside. The launcher used to bake the directories
+ * `detectNativePackages()` found at INSTALL time, which makes the env a SNAPSHOT
+ * of one moment:
+ *
+ *   - a native package installed into the same prefix LATER (`gjsify install -g
+ *     @gjsify/<x>-native`, a project `gjsify install` that adds one) is invisible
+ *     until something happens to rewrite the launcher;
+ *   - and if the scan comes back empty for any reason, the launcher is written
+ *     with NO preamble at all and nothing says so. The failure then surfaces
+ *     much later and somewhere else entirely — `gjsify build` dying with "no
+ *     usable bundler engine under GJS" in an unrelated project, which reads as a
+ *     broken install rather than a stale launcher. That is what shipped in
+ *     v0.24.1: a `~/.local/bin/gjsify` with a bare `exec gjs -m …` line while
+ *     `@gjsify/rolldown-native` sat correctly installed in the prefix.
+ *
+ * Deriving the env from disk on every launch removes both: the launcher states
+ * WHERE to look rather than WHAT was there, so it cannot go stale, and an empty
+ * result is a fact about the current prefix instead of a silently frozen one.
+ * The cost is a handful of shell globs per launch (they are builtins, and a
+ * pattern that matches nothing stays literal and is rejected by `[ -d ]`).
+ *
+ * `bakedDirs` covers what a run-time scan of `scanRoot` structurally cannot see:
+ * `detectNativePackages()` walks UP the directory chain, so in a hoisted layout
+ * a prebuild may live in an ancestor's `node_modules`. Those are still embedded
+ * verbatim; only the primary root is dynamic. Duplicates are harmless (both
+ * variables are search paths).
+ *
+ * Windows is deliberately excluded: there the `sh` file is only reachable from
+ * git-bash/MSYS, the real launchers are the `.cmd`/`.ps1` companions built by
+ * {@link buildLauncherShims} from the same baked list, and `PATH` doubles as the
+ * DLL search path with `;` separators. It keeps the snapshot behaviour.
+ *
+ * @param scanRoot Directory whose `node_modules` is globbed at launch time.
+ * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
+ *   are embedded (entries inside it are dropped — the scan finds them).
+ * @returns the preamble, or `''` when there is nothing to export.
+ */
+export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
+    const platform = target.platform ?? process.platform;
+    const arch = target.arch ?? process.arch;
+    const { name: libVar, separator } = libraryPathVar(platform);
+    if (platform === 'win32') {
+        if (bakedDirs.length === 0)
+            return '';
+        const joined = shQuote(bakedDirs.join(separator));
+        return (`GI_TYPELIB_PATH=${joined}\${GI_TYPELIB_PATH:+"${separator}$GI_TYPELIB_PATH"}\n` +
+            `${libVar}=${joined}\${${libVar}:+"${separator}$${libVar}"}\n` +
+            `export GI_TYPELIB_PATH ${libVar}\n`);
+    }
+    // Only the ancestors' hits need embedding — anything under `scanRoot` is
+    // what the loop below finds, and re-embedding it would reintroduce the
+    // snapshot for exactly the packages the scan exists to keep current.
+    const nmRoot = `${scanRoot.replace(/\/+$/, '')}/node_modules/`;
+    const external = bakedDirs.filter((d) => !d.startsWith(nmRoot));
+    // The same `<os>-<arch>` spellings `resolvePrebuildDirName()` probes, in the
+    // same order: the canonical `${platform}-${arch}` plus the legacy uname one
+    // a tarball published before the rename still ships. Passing no declared
+    // platforms is correct here — the shell cannot read a package.json, and a
+    // package declaring ONLY a non-canonical spelling of this host has not
+    // existed since the audit made that state impossible.
+    const candidates = prebuildDirCandidates(platform, arch);
+    const patterns = [];
+    for (const candidate of candidates) {
+        // Scoped (`@gjsify/x`) and unscoped packages, matching `scanNodeModules`.
+        patterns.push(`${shQuote(scanRoot)}/node_modules/@*/*/prebuilds/${candidate}`);
+        patterns.push(`${shQuote(scanRoot)}/node_modules/*/prebuilds/${candidate}`);
+    }
+    const seed = external.length > 0 ? shQuote(external.join(separator)) : `''`;
+    // A directory match is not enough: `prebuilds/<os>-<arch>/` is ALSO the
+    // prebuildify convention, so a plain glob sweeps in `bare-fs`, `bare-os`
+    // and friends — packages with no typelib at all, which `detectNativePackages`
+    // never returned because it keyed on `gjsify.prebuilds`. Onto
+    // GI_TYPELIB_PATH that is merely noise; onto the LOADER path it is a
+    // directory of foreign shared objects ahead of the system ones. The
+    // `.typelib` probe restores the old precision from the filesystem alone —
+    // and it is exactly what the artifact invariant already guarantees every
+    // gjsify GI bridge ships (a library AND the typelib without which
+    // GI_TYPELIB_PATH resolves nothing).
+    return (`gjsify_np=${seed}\n` +
+        `for gjsify_d in ${patterns.join(' ')}; do\n` +
+        `  [ -d "$gjsify_d" ] || continue\n` +
+        `  for gjsify_t in "$gjsify_d"/*.typelib; do\n` +
+        `    if [ -f "$gjsify_t" ]; then gjsify_np="\${gjsify_np:+$gjsify_np${separator}}$gjsify_d"; break; fi\n` +
+        `  done\n` +
+        `done\n` +
+        `if [ -n "$gjsify_np" ]; then\n` +
+        `  GI_TYPELIB_PATH="$gjsify_np\${GI_TYPELIB_PATH:+${separator}$GI_TYPELIB_PATH}"\n` +
+        `  ${libVar}="$gjsify_np\${${libVar}:+${separator}$${libVar}}"\n` +
+        `  export GI_TYPELIB_PATH ${libVar}\n` +
+        `fi\n` +
+        `unset gjsify_np gjsify_d gjsify_t\n`);
+}

package/lib/utils/detect-native-packages.d.ts

@@ -1,7 +1,7 @@
 export interface NativePackage {
     /** npm package name, e.g. "@gjsify/webgl" */
     name: string;
-    /** Absolute path to the arch-specific prebuilds dir, e.g. "/…/@gjsify/webgl/prebuilds/linux-x86_64" */
+    /** Absolute path to the arch-specific prebuilds dir, e.g. "/…/@gjsify/webgl/prebuilds/linux-x64" */
     prebuildsDir: string;
 }
 /** The host target a resolution is performed for. Defaults to the running process. */
@@ -31,34 +31,39 @@ export interface NativeEnv {
     [key: string]: string | undefined;
 }
 /**
- * Canonical `<os>-<arch>` form so `linux-x64` and `linux-x86_64` — or
- * `darwin-arm64` and `darwin-aarch64` — compare equal. Only the *arch* half is
- * normalised; the OS half is always a `process.platform` token
- * (`linux`/`darwin`/`win32`), which has no competing spelling.
+ * Canonical `<os>-<arch>` form — the node spelling — so `linux-x86_64` and
+ * `linux-x64` compare equal. Only the *arch* half is normalised; the OS half
+ * is always a `process.platform` token (`linux`/`darwin`/`win32`), which has
+ * no competing spelling.
  */
 export declare function canonicalPlatformToken(token: string): string;
 /**
  * The prebuild directory names to probe for a host, most-specific first.
  *
- * There are two live spellings in this repo and neither can be declared the
- * winner:
+ * The canonical name is `${process.platform}-${process.arch}` — `linux-x64`,
+ * `linux-arm64`, `darwin-arm64`, `win32-x64`. Every package in the release
+ * train declares it (`gjsify.platforms`), `scripts/stage-prebuild.mjs` is the
+ * only thing that creates it, and `scripts/audit-runtimes.mjs --check` rejects
+ * any other spelling, so the three can no longer drift.
  *
- *   * the Vala/meson bridges stage `prebuilds/linux-x86_64/` — uname-style,
- *     because the meson jobs name the directory after `uname -m`;
- *   * `@gjsify/node-gi` (and `@gjsify/napi`'s prebuild staging) use
- *     `prebuilds/${process.platform}-${process.arch}/` — node-style
- *     (`linux-x64`, `darwin-arm64`, `win32-x64`).
+ * Two probes remain BEHIND that canonical name, and both are backward
+ * compatibility with tarballs already on npm — not a second convention:
  *
- * So we probe both, and — when the package declares `gjsify.platforms` — we
- * probe the package's OWN spelling first. That is strictly better than
- * guessing: a package that declares `darwin-arm64` tells us the exact
- * directory name it stages, whatever convention it picked.
+ *   1. **The package's own declared spelling.** A tarball published before the
+ *      rename declares (and ships) `linux-x86_64`; probing its declaration
+ *      first loads it without the CLI having to guess. This is also what makes
+ *      the rename work in the OTHER direction — an older CLI resolving a newer
+ *      package — because `canonicalPlatformToken` folds both spellings onto
+ *      one form at both ends.
+ *   2. **The legacy uname spelling.** Only reachable for a package that ships
+ *      a prebuild dir and declares NO `gjsify.platforms` at all — i.e. a
+ *      tarball predating the OS-axis audit, or a third-party package using
+ *      `gjsify.prebuilds` without the declaration. Inside this repo the audit
+ *      makes that state impossible.
  *
- * Ordering of the generic fallbacks is per-OS rather than fixed, so the first
- * probe is the spelling that platform's toolchain actually produces:
- * uname-style on Linux (`linux-x86_64`), node-style on macOS/Windows
- * (`darwin-arm64`, `win32-x64` — on Apple silicon `uname -m` also reports
- * `arm64`, so there node-style *is* the native spelling).
+ * Both are pure array entries matched against an already-read directory
+ * listing — no extra I/O — so tolerance on the READ side costs nothing, while
+ * the single spelling is enforced everywhere a name is WRITTEN.
  *
  * @param platform `process.platform` value.
  * @param arch `process.arch` value.

package/lib/utils/detect-native-packages.js

@@ -22,33 +22,42 @@ import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readPackageJson } from './pkg-json.js';
 /**
- * Map a Node `process.arch` value to the uname-style spelling used by the
- * Vala/meson bridges, which stage into `prebuilds/linux-x86_64/` (the output
- * of `uname -m` on the build host).
+ * Map a Node `process.arch` value to the uname-style spelling the Vala/meson
+ * bridges used to stage into (`prebuilds/linux-x86_64/`, the output of
+ * `uname -m` on the build host).
+ *
+ * LEGACY. Every `@gjsify/*` package now declares and stages the node spelling
+ * (`linux-x64`); this table exists only so the CLI can still load a prebuild
+ * out of a tarball published before the rename. See
+ * {@link prebuildDirCandidates}.
  */
-const NODE_ARCH_TO_UNAME = {
+const NODE_ARCH_TO_LEGACY_UNAME = {
     x64: 'x86_64',
     arm64: 'aarch64',
     arm: 'armv7',
     ia32: 'i686',
 };
 /**
- * Arch spellings that name the same target. Mirrors `ARCH_ALIASES` in
- * `scripts/audit-runtimes.mjs` — that script canonicalises
- * `package.json#gjsify.platforms` the same way for the platform-support
- * matrix, and the two MUST agree or a package could pass the audit while the
- * CLI fails to find its artifact.
+ * Arch spellings that name the same target, folded onto the NODE spelling.
+ * Mirrors `ARCH_ALIASES` in `scripts/audit-runtimes.mjs` — that script
+ * canonicalises `package.json#gjsify.platforms` the same way for the
+ * platform-support matrix, and the two MUST agree or a package could pass the
+ * audit while the CLI fails to find its artifact.
+ *
+ * The direction matters: `${process.platform}-${process.arch}` is what a
+ * running process can compute about itself, so folding *onto* it means the
+ * host identity never has to be translated in the hot path.
  */
 const ARCH_ALIASES = {
-    x64: 'x86_64',
-    amd64: 'x86_64',
-    arm64: 'aarch64',
+    x86_64: 'x64',
+    amd64: 'x64',
+    aarch64: 'arm64',
 };
 /**
- * Canonical `<os>-<arch>` form so `linux-x64` and `linux-x86_64` — or
- * `darwin-arm64` and `darwin-aarch64` — compare equal. Only the *arch* half is
- * normalised; the OS half is always a `process.platform` token
- * (`linux`/`darwin`/`win32`), which has no competing spelling.
+ * Canonical `<os>-<arch>` form — the node spelling — so `linux-x86_64` and
+ * `linux-x64` compare equal. Only the *arch* half is normalised; the OS half
+ * is always a `process.platform` token (`linux`/`darwin`/`win32`), which has
+ * no competing spelling.
  */
 export function canonicalPlatformToken(token) {
     const dash = token.indexOf('-');
@@ -61,36 +70,38 @@ export function canonicalPlatformToken(token) {
 /**
  * The prebuild directory names to probe for a host, most-specific first.
  *
- * There are two live spellings in this repo and neither can be declared the
- * winner:
+ * The canonical name is `${process.platform}-${process.arch}` — `linux-x64`,
+ * `linux-arm64`, `darwin-arm64`, `win32-x64`. Every package in the release
+ * train declares it (`gjsify.platforms`), `scripts/stage-prebuild.mjs` is the
+ * only thing that creates it, and `scripts/audit-runtimes.mjs --check` rejects
+ * any other spelling, so the three can no longer drift.
  *
- *   * the Vala/meson bridges stage `prebuilds/linux-x86_64/` — uname-style,
- *     because the meson jobs name the directory after `uname -m`;
- *   * `@gjsify/node-gi` (and `@gjsify/napi`'s prebuild staging) use
- *     `prebuilds/${process.platform}-${process.arch}/` — node-style
- *     (`linux-x64`, `darwin-arm64`, `win32-x64`).
+ * Two probes remain BEHIND that canonical name, and both are backward
+ * compatibility with tarballs already on npm — not a second convention:
  *
- * So we probe both, and — when the package declares `gjsify.platforms` — we
- * probe the package's OWN spelling first. That is strictly better than
- * guessing: a package that declares `darwin-arm64` tells us the exact
- * directory name it stages, whatever convention it picked.
+ *   1. **The package's own declared spelling.** A tarball published before the
+ *      rename declares (and ships) `linux-x86_64`; probing its declaration
+ *      first loads it without the CLI having to guess. This is also what makes
+ *      the rename work in the OTHER direction — an older CLI resolving a newer
+ *      package — because `canonicalPlatformToken` folds both spellings onto
+ *      one form at both ends.
+ *   2. **The legacy uname spelling.** Only reachable for a package that ships
+ *      a prebuild dir and declares NO `gjsify.platforms` at all — i.e. a
+ *      tarball predating the OS-axis audit, or a third-party package using
+ *      `gjsify.prebuilds` without the declaration. Inside this repo the audit
+ *      makes that state impossible.
  *
- * Ordering of the generic fallbacks is per-OS rather than fixed, so the first
- * probe is the spelling that platform's toolchain actually produces:
- * uname-style on Linux (`linux-x86_64`), node-style on macOS/Windows
- * (`darwin-arm64`, `win32-x64` — on Apple silicon `uname -m` also reports
- * `arm64`, so there node-style *is* the native spelling).
+ * Both are pure array entries matched against an already-read directory
+ * listing — no extra I/O — so tolerance on the READ side costs nothing, while
+ * the single spelling is enforced everywhere a name is WRITTEN.
  *
  * @param platform `process.platform` value.
  * @param arch `process.arch` value.
  * @param declaredPlatforms `package.json#gjsify.platforms`, when present.
  */
 export function prebuildDirCandidates(platform, arch, declaredPlatforms) {
-    const unameArch = NODE_ARCH_TO_UNAME[arch] ?? arch;
-    const preferred = platform === 'linux' ? unameArch : arch;
-    const alternate = platform === 'linux' ? arch : unameArch;
-    const generic = [`${platform}-${preferred}`, `${platform}-${alternate}`];
-    const hostCanonical = canonicalPlatformToken(generic[0]);
+    const canonical = `${platform}-${arch}`;
+    const legacyArch = NODE_ARCH_TO_LEGACY_UNAME[arch] ?? arch;
     const out = [];
     const push = (name) => {
         if (!out.includes(name))
@@ -100,12 +111,13 @@ export function prebuildDirCandidates(platform, arch, declaredPlatforms) {
     for (const declared of declaredPlatforms ?? []) {
         if (typeof declared !== 'string')
             continue;
-        if (canonicalPlatformToken(declared) === hostCanonical)
+        if (canonicalPlatformToken(declared) === canonical)
             push(declared);
     }
-    // 2. The two generic spellings.
-    for (const name of generic)
-        push(name);
+    // 2. The canonical node spelling — what everything in the train stages.
+    push(canonical);
+    // 3. The legacy uname spelling, for undeclared pre-rename tarballs.
+    push(`${platform}-${legacyArch}`);
     return out;
 }
 /**

package/lib/utils/gjs-bundle-guard.d.ts

@@ -0,0 +1,32 @@
+/** The one bundler-output field this guard needs, from either engine. */
+export interface GuardedChunk {
+    /** Emitted chunk name, for the error message. */
+    fileName?: string;
+    /** External specifiers the chunk STATICALLY imports (rollup/rolldown contract). */
+    imports?: readonly string[];
+}
+/**
+ * Bare `node:` specifiers a `--app gjs` bundle may keep as static imports.
+ *
+ * Deliberately EMPTY. Every Node builtin has an `@gjsify/*` polyfill that
+ * `--app gjs` aliases to, so there is no specifier that both survives into the
+ * module graph and loads under GJS. Reading the graph instead of the text is
+ * what keeps this list empty — the entries an earlier text-scanning version
+ * needed (`node:module`, `node:process`) were quoted lookalikes, never imports.
+ *
+ * Add an entry ONLY with a comment naming why GJS can resolve it. Each one is a
+ * specifier this guard can no longer catch for real.
+ */
+export declare const GJS_ALLOWED_NODE_IMPORTS: readonly string[];
+/**
+ * The distinct bare `node:` specifiers `chunks` statically import, minus the
+ * allowlist. Sorted, so the error message and any test are stable.
+ */
+export declare function findDisallowedNodeImports(chunks: readonly GuardedChunk[], allowed?: readonly string[]): string[];
+/**
+ * Throw when a built `--app gjs` bundle statically imports Node builtins.
+ *
+ * @param chunks   the emitted chunks, as reported by the bundler
+ * @param outfile  path of the bundle, for the error message
+ */
+export declare function assertGjsBundleLoadable(chunks: readonly GuardedChunk[], outfile: string): void;