@gjsify/cli 0.22.0 → 0.24.1

package/lib/utils/install-global.js

@@ -23,7 +23,8 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { detectNativePackages } from './detect-native-packages.js';
+import { detectNativePackages, libraryPathVar } from './detect-native-packages.js';
+import { buildLauncherShims, parseShebang } from './bin-shim.js';
 /**
  * Compute the canonical global install layout for the current user. Honours
  * `XDG_DATA_HOME` (per the XDG Base Directory Spec) plus
@@ -174,7 +175,9 @@ export function linkGlobalBins(packageNames, layout) {
                 /* best effort */
             }
             const linkPath = path.join(layout.binDir, binName);
-            fs.rmSync(linkPath, { force: true });
+            for (const stale of [linkPath, `${linkPath}.cmd`, `${linkPath}.ps1`]) {
+                fs.rmSync(stale, { force: true, maxRetries: 10, retryDelay: 100 });
+            }
             // Inline `${target}` directly — this file is rewritten on every
             // install, paths are user-owned, and POSIX `sh` quoting via
             // single-quotes plus `'\''` for embedded quotes is well-defined.
@@ -196,6 +199,36 @@ export function linkGlobalBins(packageNames, layout) {
                 : `#!/bin/sh\nexec ${shQuote(targetAbs)} "$@"\n`;
             fs.writeFileSync(linkPath, launcher);
             fs.chmodSync(linkPath, 0o755);
+            // Windows runs neither an extension-less file nor a `#!` line, so
+            // the `sh` launcher above is only reachable from git-bash/MSYS/WSL.
+            // Write the `.cmd`/`.ps1` companions cmd.exe and pwsh need — the
+            // same three-file layout npm's cmd-shim produces.
+            if (process.platform === 'win32') {
+                const joined = nativePrebuildDirs.join(';');
+                // No dedicated DLL-search variable on Windows: LoadLibrary
+                // searches PATH, and GLib's search-path separator is `;` there
+                // too — so both variables take the same `;`-joined value.
+                const prependEnv = isGjsBundle && nativePrebuildDirs.length > 0 ? { GI_TYPELIB_PATH: joined, PATH: joined } : {};
+                // A non-bundle bin is exec'd directly by the sh launcher, which
+                // relies on its `#!` line; batch/pwsh have no shebang support,
+                // so read the interpreter out of it the way cmd-shim does
+                // (defaulting to `node`, what every npm bin declares).
+                const shebang = isGjsBundle ? null : readShebangOf(targetAbs);
+                const shims = isGjsBundle
+                    ? buildLauncherShims({
+                        interpreter: 'gjs',
+                        interpreterArgs: ['-m'],
+                        target: targetAbs,
+                        prependEnv,
+                    })
+                    : buildLauncherShims({
+                        interpreter: shebang?.prog || 'node',
+                        interpreterArgs: shebang?.args.trim() ? shebang.args.trim().split(/\s+/) : [],
+                        target: targetAbs,
+                    });
+                fs.writeFileSync(`${linkPath}.cmd`, shims.cmd);
+                fs.writeFileSync(`${linkPath}.ps1`, shims.ps1);
+            }
             created.push({ name: binName, target: targetAbs, link: linkPath });
         }
     }
@@ -206,20 +239,37 @@ function shQuote(s) {
 }
 /**
  * Build the POSIX-sh `export` lines that prepend the given prebuild
- * directories to GI_TYPELIB_PATH and LD_LIBRARY_PATH. Any pre-existing value
- * inherited from the user's environment is preserved as a suffix so
- * user-installed typelibs/libraries still resolve.
+ * directories to GI_TYPELIB_PATH and the host's shared-library search path.
+ * Any pre-existing value inherited from the user's environment is preserved as
+ * a suffix so user-installed typelibs/libraries still resolve.
+ *
+ * The library variable is host-dependent — `LD_LIBRARY_PATH` on Linux,
+ * `DYLD_LIBRARY_PATH` on macOS (dyld never reads the ELF one), so a launcher
+ * written on a Mac used to export a variable nothing consults, leaving every
+ * `darwin-arm64` prebuild unloadable. `platform` is a parameter so both
+ * branches are unit-testable from either host.
  *
  * Returns the empty string when no prebuilds were found — avoids emitting an
  * inert assignment in the launcher.
  */
-function buildLauncherEnvPreamble(prebuildsDirs) {
+export function buildLauncherEnvPreamble(prebuildsDirs, platform = process.platform) {
     if (prebuildsDirs.length === 0)
         return '';
+    const { name: libVar } = libraryPathVar(platform);
     const joined = shQuote(prebuildsDirs.join(':'));
     return (`GI_TYPELIB_PATH=${joined}\${GI_TYPELIB_PATH:+":$GI_TYPELIB_PATH"}\n` +
-        `LD_LIBRARY_PATH=${joined}\${LD_LIBRARY_PATH:+":$LD_LIBRARY_PATH"}\n` +
-        `export GI_TYPELIB_PATH LD_LIBRARY_PATH\n`);
+        `${libVar}=${joined}\${${libVar}:+":$${libVar}"}\n` +
+        `export GI_TYPELIB_PATH ${libVar}\n`);
+}
+/** Parse a bin file's `#!` line; `null` when unreadable or not a shebang. */
+function readShebangOf(file) {
+    try {
+        const head = fs.readFileSync(file, 'utf-8');
+        return parseShebang(head.trimStart().split(/\r*\n/, 1)[0] ?? '');
+    }
+    catch {
+        return null;
+    }
 }
 function pickBinMap(pkgName, pkgJson) {
     const gjsifyEntry = pkgJson.gjsify;

package/lib/utils/oxc-resolve.js

@@ -46,14 +46,14 @@
 // lives in the Node launcher, so a native oxlint bridge could only run the
 // Rust rule subset. Lint stays Node-spawned until that trade-off is decided
 // (tracked in STATUS.md Open TODOs).
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { findWorkspaceRoot } from './workspace-root.js';
 import { resolveNpmPackage } from './resolve-npm-package.js';
 import { nodeBinary } from './run-node.js';
+import { spawnToCompletion } from './spawn.js';
 import { isGjs, gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
 /**
  * Map Node.js `process.platform` + `arch` (+ musl on Linux) to the
@@ -89,7 +89,12 @@ function oxcBindingSuffix() {
         // glibc systems have `/lib/ld-linux-*`, musl has `/lib/ld-musl-*`.
         let libc = 'gnu';
         try {
-            const { readdirSync } = require('node:fs');
+            // `readdirSync` is imported STATICALLY at the top of this file. It
+            // used to be a lazy `require('node:fs')` inside this try — a bare
+            // `require` in an ESM module, so it threw ReferenceError, the catch
+            // below swallowed it, and `libc` silently stayed 'gnu': a musl host
+            // would be told to install the WRONG binding package. Same defect
+            // class as commands/affected.ts, and even quieter.
             const libEntries = readdirSync('/lib');
             if (libEntries.some((e) => e.startsWith('ld-musl-'))) {
                 libc = 'musl';
@@ -298,6 +303,14 @@ export async function runOxc(tool, args, opts = {}) {
  * launcher as its first positional (yargs prints top-level help) and the parent
  * hangs waiting on a child that never does the intended work. `nodeBinary()`
  * resolves to PATH `node` under GJS, so the launcher runs on Node as required.
+ *
+ * `completion: 'return'`: `lint` / `format` / `fix` hand the tool's exit code
+ * to `setOxcExitCode`, which deliberately does NOT terminate the process on a
+ * clean run — so under GJS this must take `spawnToCompletion`'s blocking path
+ * (see `utils/spawn.ts`; the async one would leave the main loop `spawn()`
+ * arms parked at 0% CPU on the way out). That path also captures and re-emits
+ * the tool's stdout/stderr with a raised `maxBuffer`, which is exactly what a
+ * full-workspace lint needs.
  */
 function spawnOxcLauncher(tool, args, opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
@@ -306,61 +319,16 @@ function spawnOxcLauncher(tool, args, opts = {}) {
     if (opts.verbose) {
         console.log(`[gjsify oxc] ${node} ${launcher} ${args.join(' ')}`);
     }
-    // Under the GJS bundle the ASYNC spawn's exit/close event is never delivered
-    // back to JS: the child runs, streams its output, and exits (reaped, no
-    // zombie), but the `Gio.Subprocess` `wait_async` callback that emits
-    // `exit`/`close` does not fire, so the parent's await hangs at 0% CPU
-    // forever (the process sits in `SNl`). `spawnSync` uses the synchronous
-    // `communicate()` path instead — no async callback to lose — so it
-    // completes reliably. It blocks, which is exactly right for a CLI leaf
-    // command that just runs the tool to completion. On Node the async spawn is
-    // fine (and keeps the event loop free), so it is kept there.
-    if (isGjs()) {
-        // Capture stdout/stderr (`'inherit'` is not forwarded through the GJS
-        // spawnSync path — the tool's diagnostics would be silently lost), then
-        // re-emit them so oxlint/oxfmt's own output still reaches the user.
-        // maxBuffer generous: a full-workspace lint with many findings can emit
-        // well past the 1 MB Node default; overflow would truncate diagnostics.
-        const r = spawnSync(node, [launcher, ...args], {
-            stdio: ['inherit', 'pipe', 'pipe'],
-            cwd,
-            maxBuffer: 64 * 1024 * 1024,
-        });
-        if (r.error) {
-            const code = r.error.code;
-            if (code === 'ENOENT')
-                return Promise.reject(new OxcNotFoundError(tool, cwd));
-            return Promise.reject(r.error);
-        }
-        if (r.stdout && r.stdout.length)
-            process.stdout.write(r.stdout);
-        if (r.stderr && r.stderr.length)
-            process.stderr.write(r.stderr);
-        if (r.signal) {
-            console.error(`[gjsify oxc] ${tool} terminated by signal ${r.signal}`);
-            return Promise.resolve(1);
+    return spawnToCompletion(node, [launcher, ...args], {
+        completion: 'return',
+        cwd,
+        notFound: () => new OxcNotFoundError(tool, cwd),
+    }).then(({ code, signal }) => {
+        if (signal !== null) {
+            console.error(`[gjsify oxc] ${tool} terminated by signal ${signal}`);
+            return 1;
         }
-        return Promise.resolve(r.status ?? 0);
-    }
-    return new Promise((res, rej) => {
-        const spawnOpts = { stdio: 'inherit', cwd };
-        const child = spawn(node, [launcher, ...args], spawnOpts);
-        child.on('error', (err) => {
-            if (err.code === 'ENOENT') {
-                rej(new OxcNotFoundError(tool, cwd));
-            }
-            else {
-                rej(err);
-            }
-        });
-        child.on('exit', (code, signal) => {
-            if (signal) {
-                console.error(`[gjsify oxc] ${tool} terminated by signal ${signal}`);
-                res(1);
-                return;
-            }
-            res(code ?? 0);
-        });
+        return code ?? 0;
     });
 }
 /** Convenience wrappers. */

package/lib/utils/publish-headers.d.ts

@@ -24,9 +24,8 @@ export interface PublishHeaderOptions {
      */
     authorization?: string;
     /**
-     * npm user-agent. Defaults to an npm-CLI-shaped string. The registry does
-     * not validate the exact value, but a real UA is what npm sends; the dead
-     * `gjsify-install/0.3.7` placeholder is not used here.
+     * npm user-agent. Defaults to an npm-CLI-shaped string carrying this CLI's
+     * real version — never a hard-coded placeholder (see {@link cliVersion}).
      */
     userAgent?: string;
 }

package/lib/utils/publish-headers.js

@@ -27,8 +27,12 @@
 //     literal `@`. (gjsify's URL encoding already matches this — it was never
 //     the bug.)
 //
-// This module is pure (no I/O, no `gi://`) so it is unit-testable on both Node
-// and GJS without dragging in the runtime fetch/Soup stack.
+// This module pulls in no `gi://` and no runtime fetch/Soup stack, so it is
+// unit-testable on both Node and GJS. Its one filesystem touch is the
+// manifest walk backing the user-agent version — see `cliVersion()`.
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { buildHeaders } from '@gjsify/npm-registry';
 /**
  * Percent-encode a package name for the publish PUT path, matching
@@ -85,6 +89,63 @@ export function buildPublishHeaders(url, opts) {
         headers['authorization'] = opts.authorization;
     return headers;
 }
+/**
+ * This CLI's own `package.json#version`, memoised. Two layers, because
+ * `@gjsify/cli` is a DUAL-ENTRY package and neither layer covers both entries:
+ *
+ * 1. **`__PACKAGE_VERSION__`** — the compile-time define
+ *    (`package.json#gjsify.defineFromPackageJson`), the mechanism
+ *    `@gjsify/npm-registry` uses for the same stale-UA bug. Zero I/O, but the
+ *    bundler only ever writes `dist/cli.gjs.mjs`: the npm-wired Node bin under
+ *    `lib/` is emitted by plain `tsc`, which knows nothing about defines. A
+ *    define alone would therefore have left the Node entry — the one `npm
+ *    install @gjsify/cli` actually runs — on a permanent placeholder.
+ *
+ * 2. **an upward manifest walk** for the nearest `package.json` naming
+ *    `@gjsify/cli`, covering `lib/`. Deliberately NOT a fixed
+ *    `new URL('../../package.json', import.meta.url)` read: that resolves
+ *    correctly from `lib/utils/` but points one directory too high from
+ *    `dist/`, and the build-time `inlineStaticReads` pass that would have
+ *    frozen it is scoped to `node_modules` paths, so first-party source never
+ *    gets it. The walk is depth-independent and so works from `src/`, `lib/`,
+ *    `dist/`, and from an installed `node_modules/@gjsify/cli/**` alike.
+ *
+ * `GJSIFY_CLI_PACKAGE_JSON` overrides both, matching `self-update.ts`.
+ */
+let cachedCliVersion;
+function cliVersion() {
+    if (cachedCliVersion !== undefined)
+        return cachedCliVersion;
+    cachedCliVersion =
+        (typeof __PACKAGE_VERSION__ === 'string' ? __PACKAGE_VERSION__ : '') || walkForCliVersion() || 'unknown';
+    return cachedCliVersion;
+}
+/** Nearest ancestor `package.json` whose `name` is `@gjsify/cli`; '' when none. */
+function walkForCliVersion() {
+    const override = globalThis.process?.env?.['GJSIFY_CLI_PACKAGE_JSON'];
+    let dir;
+    try {
+        dir = override ? dirname(override) : dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return '';
+    }
+    for (let i = 0; i < 12; i++) {
+        try {
+            const pkg = JSON.parse(readFileSync(`${dir}/package.json`, 'utf8'));
+            if (pkg.name === '@gjsify/cli' && typeof pkg.version === 'string')
+                return pkg.version;
+        }
+        catch {
+            /* no manifest here (or unreadable) — keep climbing */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return '';
+}
 /**
  * npm-CLI-shaped user-agent. Format mirrors npm-registry-fetch's
  * `default-opts.js` (`npm@<v>/node@<v>+<arch> (<platform>)`); we substitute the
@@ -95,5 +156,5 @@ function defaultUserAgent() {
     const proc = globalThis.process;
     const arch = proc?.arch ?? 'x64';
     const platform = proc?.platform ?? 'linux';
-    return `gjsify-publish/0.5.0 (${platform} ${arch})`;
+    return `gjsify-publish/${cliVersion()} (${platform} ${arch})`;
 }

package/lib/utils/publishable-packages.d.ts

@@ -0,0 +1,22 @@
+import type { Workspace } from '@gjsify/workspace';
+/**
+ * Package-group directories holding publishable packages that are NOT root
+ * workspaces. Add one here the moment a new non-workspace publishable group
+ * appears — this list is the only thing standing between such a package and a
+ * silently broken first release.
+ */
+export declare const NON_WORKSPACE_PUBLISHABLE_DIRS: readonly [readonly ["packages", "node-gi"], readonly ["packages", "napi"]];
+/**
+ * Publishable packages in {@link NON_WORKSPACE_PUBLISHABLE_DIRS}, shaped as
+ * `Workspace` entries so callers can treat them like any other package.
+ *
+ * Best-effort by design: a missing directory or an unreadable/malformed
+ * manifest is skipped rather than thrown, because this runs inside sweeps whose
+ * value is covering everything they can reach.
+ */
+export declare function discoverNonWorkspacePublishables(cwd: string): Workspace[];
+/**
+ * Merge workspace-discovered packages with the non-workspace publishables,
+ * deduped by name. A real workspace always wins over a scanned directory.
+ */
+export declare function mergePublishables(workspaces: Workspace[], cwd: string): Workspace[];

package/lib/utils/publishable-packages.js

@@ -0,0 +1,93 @@
+// Publishable-package discovery shared by `gjsify trust` and `gjsify onboard`.
+//
+// `discoverWorkspaces` only sees ROOT WORKSPACES. Some publishable packages
+// deliberately are not: each is an independent native engine with its own CI
+// workflow, kept out of the workspace graph so a full `gjsify foreach` never
+// tries to build it. They still publish through `release.yml`, so every sweep
+// that reasons about "what do we publish" has to include them — otherwise the
+// sweep silently under-reports and the package's first release fails the OIDC
+// exchange with `404 — package not found`.
+//
+// That is not hypothetical: `gjsify onboard` reported 127 packages "already
+// done" on 2026-07-26 while `@gjsify/napi` was neither in the list nor
+// published at all, because only `packages/node-gi/*` was carved out.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Package-group directories holding publishable packages that are NOT root
+ * workspaces. Add one here the moment a new non-workspace publishable group
+ * appears — this list is the only thing standing between such a package and a
+ * silently broken first release.
+ */
+export const NON_WORKSPACE_PUBLISHABLE_DIRS = [
+    ['packages', 'node-gi'], // @gjsify/node-gi + the @gjsify/gtk-runtime-* bundles
+    ['packages', 'napi'], // @gjsify/napi (the N-API host in GJS, own napi.yml)
+];
+/**
+ * Publishable packages in {@link NON_WORKSPACE_PUBLISHABLE_DIRS}, shaped as
+ * `Workspace` entries so callers can treat them like any other package.
+ *
+ * Best-effort by design: a missing directory or an unreadable/malformed
+ * manifest is skipped rather than thrown, because this runs inside sweeps whose
+ * value is covering everything they can reach.
+ */
+export function discoverNonWorkspacePublishables(cwd) {
+    // Walk up to the repo root. Anchored on the FIRST configured group rather
+    // than on `packages/` itself, which also exists inside individual packages.
+    let root = cwd;
+    const anchor = NON_WORKSPACE_PUBLISHABLE_DIRS[0];
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(root, ...anchor)))
+            break;
+        const parent = dirname(root);
+        if (parent === root)
+            return [];
+        root = parent;
+    }
+    const out = [];
+    for (const group of NON_WORKSPACE_PUBLISHABLE_DIRS) {
+        const base = join(root, ...group);
+        if (!existsSync(base))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(base, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const location = join(base, entry.name);
+            const pkgPath = join(location, 'package.json');
+            if (!existsSync(pkgPath))
+                continue;
+            try {
+                const manifest = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                if (!manifest || typeof manifest.name !== 'string' || manifest.name.length === 0)
+                    continue;
+                out.push({
+                    location,
+                    relativeLocation: join(...group, entry.name),
+                    name: manifest.name,
+                    version: typeof manifest.version === 'string' ? manifest.version : '0.0.0',
+                    manifest,
+                    private: manifest.private === true,
+                });
+            }
+            catch {
+                /* unreadable / malformed — skip */
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Merge workspace-discovered packages with the non-workspace publishables,
+ * deduped by name. A real workspace always wins over a scanned directory.
+ */
+export function mergePublishables(workspaces, cwd) {
+    const seen = new Set(workspaces.map((ws) => ws.name));
+    return [...workspaces, ...discoverNonWorkspacePublishables(cwd).filter((ws) => !seen.has(ws.name))];
+}

package/lib/utils/run-gjs.d.ts

@@ -1,14 +1,13 @@
+import { type NativeEnv } from './detect-native-packages.js';
 /**
- * Pure env computation for a given bundle. Returns the LD_LIBRARY_PATH /
- * GI_TYPELIB_PATH values that {@link runGjsBundle} would inject into the
+ * Pure env computation for a given bundle. Returns the typelib +
+ * shared-library search paths that {@link runGjsBundle} would inject into the
  * spawned `gjs` process, plus the formatted env-prefix string used for the
- * `$ …` echo.
+ * `$ …` echo. Which library variable is set is host-dependent
+ * (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see `buildNativeEnv`.
  */
 export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: string): {
-    env: {
-        LD_LIBRARY_PATH: string;
-        GI_TYPELIB_PATH: string;
-    };
+    env: NativeEnv;
     envPrefix: string;
 };
 /**

package/lib/utils/run-gjs.js

@@ -20,10 +20,11 @@ import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { detectNativePackages, buildNativeEnv } from './detect-native-packages.js';
 /**
- * Pure env computation for a given bundle. Returns the LD_LIBRARY_PATH /
- * GI_TYPELIB_PATH values that {@link runGjsBundle} would inject into the
+ * Pure env computation for a given bundle. Returns the typelib +
+ * shared-library search paths that {@link runGjsBundle} would inject into the
  * spawned `gjs` process, plus the formatted env-prefix string used for the
- * `$ …` echo.
+ * `$ …` echo. Which library variable is set is host-dependent
+ * (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see `buildNativeEnv`.
  */
 export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd()) {
     const resolvedBundle = resolve(bundlePath);

package/lib/utils/run-node.d.ts

@@ -6,6 +6,22 @@ import { type ExampleRuntime } from './runtimes.js';
  * not available under the GJS-bundled CLI.
  */
 export declare function resolveNodeGi(startDir: string): string | null;
+/**
+ * Resolve `@gjsify/node-gi` for a bundle we are about to launch: from the
+ * BUNDLE's own directory first, then from `cwd`.
+ *
+ * The bundle's directory is the correct base and cwd is the fallback, for the
+ * same reason {@link computeNativeEnvForBundle} walks both: `@gjsify/node-gi` is
+ * kept EXTERNAL, so what has to be satisfiable is the RUNTIME's resolution of a
+ * bare specifier from inside the bundle — which Node performs relative to the
+ * importing file, never relative to cwd. A dlx-cache layout
+ * (`~/.cache/gjsify/dlx/<sha>/node_modules/<pkg>/dist/bundle.mjs`) has node-gi
+ * sitting right beside the bundle and nothing at all under the user's cwd, so a
+ * cwd-only probe rejected a run that would have worked. The cwd probe is kept
+ * because a project-local `node_modules` legitimately satisfies a bundle built
+ * into a `dist/` outside it (a `--outfile /tmp/…` build from a project root).
+ */
+export declare function resolveNodeGiForBundle(bundlePath: string, cwd: string): string | null;
 /** Pick the node executable: the current one when on Node, else PATH `node`. */
 export declare function nodeBinary(): string;
 export interface RunNodeBundleOptions {

package/lib/utils/run-node.js

@@ -5,10 +5,12 @@
 // through `@gjsify/node-gi` (the Axis-5 reverse bridge). Two things have to be
 // true at runtime:
 //
-//   1. `@gjsify/node-gi` must resolve from the project — it is kept EXTERNAL by
-//      the bundler (a native addon), so it has to physically exist in the
-//      consumer's node_modules. We verify this up front and emit a clear hint
-//      instead of letting Node throw `ERR_MODULE_NOT_FOUND` deep in the bundle.
+//   1. `@gjsify/node-gi` must resolve FROM THE BUNDLE — it is kept EXTERNAL by
+//      the bundler (a native addon), so it has to physically exist in a
+//      node_modules the bundle's own directory can reach (that is where Node
+//      will look), with the CWD as a fallback. We verify this up front and emit
+//      a clear hint instead of letting Node throw `ERR_MODULE_NOT_FOUND` deep in
+//      the bundle. See `resolveNodeGiForBundle`.
 //   2. `gi://Gtk` / `gi://Adw` etc. must resolve. System typelibs come from the
 //      default GI search path, but any `@gjsify/*` Vala bridge a story pulls in
 //      ships its typelib in `prebuilds/` — so we reuse the SAME
@@ -21,7 +23,7 @@
 // `gjs`, which cannot run a `--app node` bundle).
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { computeNativeEnvForBundle } from './run-gjs.js';
 import { RUNTIMES } from './runtimes.js';
@@ -43,6 +45,25 @@ export function resolveNodeGi(startDir) {
         dir = parent;
     }
 }
+/**
+ * Resolve `@gjsify/node-gi` for a bundle we are about to launch: from the
+ * BUNDLE's own directory first, then from `cwd`.
+ *
+ * The bundle's directory is the correct base and cwd is the fallback, for the
+ * same reason {@link computeNativeEnvForBundle} walks both: `@gjsify/node-gi` is
+ * kept EXTERNAL, so what has to be satisfiable is the RUNTIME's resolution of a
+ * bare specifier from inside the bundle — which Node performs relative to the
+ * importing file, never relative to cwd. A dlx-cache layout
+ * (`~/.cache/gjsify/dlx/<sha>/node_modules/<pkg>/dist/bundle.mjs`) has node-gi
+ * sitting right beside the bundle and nothing at all under the user's cwd, so a
+ * cwd-only probe rejected a run that would have worked. The cwd probe is kept
+ * because a project-local `node_modules` legitimately satisfies a bundle built
+ * into a `dist/` outside it (a `--outfile /tmp/…` build from a project root).
+ */
+export function resolveNodeGiForBundle(bundlePath, cwd) {
+    const resolvedBundle = resolve(bundlePath);
+    return resolveNodeGi(dirname(resolvedBundle)) ?? resolveNodeGi(cwd);
+}
 /** Pick the node executable: the current one when on Node, else PATH `node`. */
 export function nodeBinary() {
     return isNode() && process.execPath ? process.execPath : 'node';
@@ -55,7 +76,7 @@ export function nodeBinary() {
  */
 export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
     const cwd = process.cwd();
-    if (!resolveNodeGi(cwd)) {
+    if (!resolveNodeGiForBundle(bundlePath, cwd)) {
         throw new Error('Cannot run the storybook on Node: `@gjsify/node-gi` is not installed.\n' +
             'Add @gjsify/node-gi as a dependency to run the storybook on Node, e.g.:\n' +
             '  "devDependencies": { "@gjsify/node-gi": "^0.13.0" }');
@@ -113,7 +134,7 @@ export function bundleRequiresNodeGi(bundlePath) {
 export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], options = {}) {
     const cwd = process.cwd();
     const resolvedBundle = resolve(bundlePath);
-    if (bundleRequiresNodeGi(resolvedBundle) && !resolveNodeGi(cwd)) {
+    if (bundleRequiresNodeGi(resolvedBundle) && !resolveNodeGiForBundle(resolvedBundle, cwd)) {
         throw new Error(`Cannot run this bundle on ${runtime}: it uses gi:// via \`@gjsify/node-gi\`, which is not installed.\n` +
             'Add @gjsify/node-gi as a dependency to run gi:// code off GJS, e.g.:\n' +
             '  "dependencies": { "@gjsify/node-gi": "^0.13.0" }');

package/lib/utils/runtimes.d.ts

@@ -37,6 +37,27 @@ export declare function isRuntimeOnPath(probe: string): boolean;
 export declare function isRuntimeAvailable(runtime: ExampleRuntime): boolean;
 /** Which of gjs/node/bun/deno are runnable on this host. */
 export declare function availableRuntimes(): ExampleRuntime[];
+/**
+ * The default `--runtime` for running a prebuilt EXAMPLE/SHOWCASE: `gjs`
+ * whenever gjs is runnable here, else the host runtime.
+ *
+ * This is deliberately NOT a plain `hostRuntime()`. A showcase's canonical
+ * artifact is its `--app gjs` bundle (`gjsify.main`) — that is what every
+ * showcase ships, what the `gjs` path installs via `gjsify dlx`, and what the
+ * docs call the default. Following the host instead means `npx @gjsify/cli
+ * showcase <name>` (host = node) silently asks for the `--app node` bundle,
+ * which most showcases do not ship and which additionally needs
+ * `@gjsify/node-gi` in the consumer's project — so the FIRST-RUN experience of
+ * the primary documented entry point failed on a missing file.
+ *
+ * Same rule `gjsify run` already applies in its bare-file path, where a
+ * `--app gjs` bundle stays on gjs regardless of host (`isLikelyGjsBundle`);
+ * here the "is it a gjs artifact" question is answered by the command instead
+ * of by sniffing the file. `--runtime` still overrides explicitly, and a host
+ * WITHOUT gjs (a plain Node/bun/deno box) keeps following the host so the
+ * node-capable showcases stay runnable there.
+ */
+export declare function defaultExampleRuntime(): ExampleRuntime;
 interface ExampleGjsifyField {
     example?: {
         runtimes?: unknown;

package/lib/utils/runtimes.js

@@ -64,6 +64,29 @@ export function isRuntimeAvailable(runtime) {
 export function availableRuntimes() {
     return EXAMPLE_RUNTIMES.filter((rt) => isRuntimeAvailable(rt));
 }
+/**
+ * The default `--runtime` for running a prebuilt EXAMPLE/SHOWCASE: `gjs`
+ * whenever gjs is runnable here, else the host runtime.
+ *
+ * This is deliberately NOT a plain `hostRuntime()`. A showcase's canonical
+ * artifact is its `--app gjs` bundle (`gjsify.main`) — that is what every
+ * showcase ships, what the `gjs` path installs via `gjsify dlx`, and what the
+ * docs call the default. Following the host instead means `npx @gjsify/cli
+ * showcase <name>` (host = node) silently asks for the `--app node` bundle,
+ * which most showcases do not ship and which additionally needs
+ * `@gjsify/node-gi` in the consumer's project — so the FIRST-RUN experience of
+ * the primary documented entry point failed on a missing file.
+ *
+ * Same rule `gjsify run` already applies in its bare-file path, where a
+ * `--app gjs` bundle stays on gjs regardless of host (`isLikelyGjsBundle`);
+ * here the "is it a gjs artifact" question is answered by the command instead
+ * of by sniffing the file. `--runtime` still overrides explicitly, and a host
+ * WITHOUT gjs (a plain Node/bun/deno box) keeps following the host so the
+ * node-capable showcases stay runnable there.
+ */
+export function defaultExampleRuntime() {
+    return isRuntimeAvailable('gjs') ? 'gjs' : hostRuntime();
+}
 /**
  * Read a package's declared example runtimes. Returns the (validated) list, or
  * `null` when the package declares none — the "unconstrained / permissive" case.