@gjsify/cli 0.28.0 → 0.30.0

package/lib/commands/format.js

@@ -11,6 +11,15 @@
 // toolchain handled is intentionally DROPPED in the oxc migration — no other
 // formatter is wired up for those file types.
 //
+// A BARE `gjsify format` WRITES. `--check` is the read-only CI mode and
+// `--no-write` the read-only local one; there is no flagless report mode.
+// This is what every other formatter in the ecosystem does with its bare
+// invocation (oxfmt itself, `cargo fmt`, `gofmt -w`-less `go fmt`), it is what
+// the sibling `gjsify fix` already did, and the previous report-only default
+// silently did nothing in a loop: `gjsify format` was run repeatedly against
+// two unformatted files while `--check` kept flagging them, because the
+// command that looks like the fix was the diagnosis.
+//
 // `--init` writes recommended `.oxlintrc.json` + `.oxfmtrc.json` templates
 // tuned for GJS/GNOME projects (4-space, single-quote, printWidth 120,
 // trailing-comma all, semicolons always, arrow parens always).
@@ -28,9 +37,9 @@ export const formatCommand = {
             array: true,
         })
             .option('write', {
-            description: 'Modify files in place (default: report drift without writing).',
+            description: 'Modify files in place (default: true). Pass --no-write to report drift instead.',
             type: 'boolean',
-            default: false,
+            default: true,
         })
             .option('check', {
             description: 'Report formatting drift without modifying files; exit non-zero if any file is unformatted. Useful for CI.',
@@ -69,13 +78,13 @@ export const formatCommand = {
         if (args.check) {
             oxfmtArgs.push('--check');
         }
-        else if (args.write) {
-            oxfmtArgs.push('--write');
+        else if (args.write === false) {
+            // `--no-write` — report drift without modifying files. oxfmt's own
+            // bare default is `--write` too, so this branch must be explicit.
+            oxfmtArgs.push('--list-different');
         }
         else {
-            // No flag: report drift without modifying files. oxfmt's bare
-            // default is `--write`, so be explicit with `--list-different`.
-            oxfmtArgs.push('--list-different');
+            oxfmtArgs.push('--write');
         }
         const configPath = args.configPath ?? findOxfmtConfig(cwd) ?? undefined;
         if (configPath)
@@ -107,5 +116,5 @@ function handleInit({ cwd, force }) {
     };
     writeOne('.oxlintrc.json', loadOxlintTemplate());
     writeOne('.oxfmtrc.json', loadOxfmtTemplate());
-    console.log('[gjsify format] Run `gjsify format --write .` to apply the formatter to the project.');
+    console.log('[gjsify format] Run `gjsify format` to apply the formatter to the project.');
 }

package/lib/commands/install.d.ts

@@ -1,4 +1,5 @@
 import type { Command } from '../types/index.js';
+import { type PackageJson } from '../utils/pkg-json-edit.js';
 interface InstallOptions {
     packages?: string[];
     global?: boolean;
@@ -18,6 +19,32 @@ interface InstallOptions {
     force?: boolean;
 }
 export declare const installCommand: Command<unknown, InstallOptions>;
+/**
+ * Which dependency NAMES are optional across the given manifests.
+ *
+ * The specs handed to the install backend are flat `"<name>@<range>"` strings —
+ * `projectSpecsFromPackageJson` merges the three dependency blocks — so the kind
+ * has to travel beside them. It matters for exactly one decision: an
+ * incompatible `os`/`cpu`/`libc` skips an OPTIONAL dependency and fails a
+ * REQUIRED one (see `NativeInstallOptions.optionalSpecs`).
+ *
+ * REQUIRED WINS ACROSS MANIFESTS, OPTIONAL WINS WITHIN ONE — and the two halves
+ * are different rules for different reasons, so neither is a special case of the
+ * other:
+ *   - Across manifests: in a workspace the same package can be a plain dependency
+ *     of one member and an optionalDependency of another. Those are two real
+ *     edges; if one of them is not allowed to be missing, the install is not
+ *     allowed to silently miss it. Subtracting rather than "last block seen" also
+ *     makes the answer independent of manifest iteration order.
+ *   - Within one manifest: a name in BOTH blocks is OPTIONAL, because npm says so
+ *     ("entries in optionalDependencies will override entries of the same name in
+ *     dependencies") — there is only ONE edge and the optional block names its
+ *     kind. Treating it as required is the root-edge twin of the transitive defect
+ *     `requiredDepEntries` fixes: `optionalDependencies: { fsevents }` alongside a
+ *     `dependencies: { fsevents }` line would fail every Linux install with
+ *     EBADPLATFORM over a package npm never installs there.
+ */
+export declare function optionalDependencyNames(manifests: readonly PackageJson[]): Set<string>;
 export declare function buildBinShim(wsLocation: string, nodeTarget?: string, gjsTarget?: string, nativePrebuildDirs?: string[], platform?: string, scanRoot?: string): string;
 /**
  * `.cmd` / `.ps1` companions for {@link buildBinShim}.

package/lib/commands/install.js

@@ -446,21 +446,38 @@ function isWorkspaceRoot(cwd) {
  * incompatible `os`/`cpu`/`libc` skips an OPTIONAL dependency and fails a
  * REQUIRED one (see `NativeInstallOptions.optionalSpecs`).
  *
- * REQUIRED WINS. In a workspace, the same package can be a plain dependency of
- * one member and an optionalDependency of another; if anything is not allowed to
- * be missing, the whole install is not allowed to silently miss it. Subtracting
- * rather than "last block seen" also makes the answer independent of manifest
- * iteration order.
+ * REQUIRED WINS ACROSS MANIFESTS, OPTIONAL WINS WITHIN ONE — and the two halves
+ * are different rules for different reasons, so neither is a special case of the
+ * other:
+ *   - Across manifests: in a workspace the same package can be a plain dependency
+ *     of one member and an optionalDependency of another. Those are two real
+ *     edges; if one of them is not allowed to be missing, the install is not
+ *     allowed to silently miss it. Subtracting rather than "last block seen" also
+ *     makes the answer independent of manifest iteration order.
+ *   - Within one manifest: a name in BOTH blocks is OPTIONAL, because npm says so
+ *     ("entries in optionalDependencies will override entries of the same name in
+ *     dependencies") — there is only ONE edge and the optional block names its
+ *     kind. Treating it as required is the root-edge twin of the transitive defect
+ *     `requiredDepEntries` fixes: `optionalDependencies: { fsevents }` alongside a
+ *     `dependencies: { fsevents }` line would fail every Linux install with
+ *     EBADPLATFORM over a package npm never installs there.
  */
-function optionalDependencyNames(manifests) {
+export function optionalDependencyNames(manifests) {
     const optional = new Set();
     const required = new Set();
     for (const manifest of manifests) {
-        for (const name of Object.keys(manifest.optionalDependencies ?? {}))
+        const optionalHere = new Set(Object.keys(manifest.optionalDependencies ?? {}));
+        for (const name of optionalHere)
             optional.add(name);
         for (const kind of ['dependencies', 'devDependencies']) {
-            for (const name of Object.keys(manifest[kind] ?? {}))
+            for (const name of Object.keys(manifest[kind] ?? {})) {
+                // Overridden by THIS manifest's own optional block — not a
+                // required edge, so it must not veto another manifest's optional
+                // declaration either.
+                if (optionalHere.has(name))
+                    continue;
                 required.add(name);
+            }
         }
     }
     for (const name of required)

package/lib/commands/system-check.js

@@ -1,4 +1,4 @@
-import { runAllChecks, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
+import { runAllChecks, detectPackageManager, buildInstallCommand, checkTypeSkew } from '../utils/check-system-deps.js';
 export const systemCheckCommand = {
     command: 'system-check',
     description: 'Check that required system dependencies (GJS, GTK4, libsoup3, …) are installed. Optional dependencies are detected only when their @gjsify/* package is in your project. (Previously called `gjsify check`; the bare name now runs TypeScript checks across the workspace — see `gjsify check --help`.)',
@@ -12,11 +12,12 @@ export const systemCheckCommand = {
     handler: async (args) => {
         const results = runAllChecks(process.cwd());
         const pm = detectPackageManager();
+        const typeSkew = checkTypeSkew(process.cwd());
         const missingRequired = results.filter((r) => !r.found && r.severity === 'required');
         const missingOptional = results.filter((r) => !r.found && r.severity === 'optional');
         const allMissing = [...missingRequired, ...missingOptional];
         if (args.json) {
-            console.log(JSON.stringify({ packageManager: pm, deps: results }, null, 2));
+            console.log(JSON.stringify({ packageManager: pm, deps: results, typeSkew }, null, 2));
             // Only required deps influence the exit code.
             return process.exit(missingRequired.length > 0 ? 1 : 0);
         }
@@ -41,6 +42,25 @@ export const systemCheckCommand = {
                 console.log(`  ${icon}  ${dep.name}${ver}${requiredBy}`);
             }
         }
+        // Printed BEFORE the all-found early return: a version skew is invisible to
+        // the presence checks by construction (both sides are installed and both
+        // report a version), so "All dependencies found." is exactly the message it
+        // would otherwise hide behind.
+        if (typeSkew.length > 0) {
+            console.log('\nType/runtime version skew:');
+            for (const skew of typeSkew) {
+                const arrow = skew.relation === 'ahead' ? '⚠' : 'ℹ';
+                console.log(`  ${arrow}  ${skew.typePackage} describes ${skew.declared}, ` +
+                    `installed ${skew.pkgConfig} is ${skew.installed}`);
+            }
+            if (typeSkew.some((skew) => skew.relation === 'ahead')) {
+                console.log('\n  ⚠ types are AHEAD of the installed library: code using newer API\n' +
+                    '    type-checks and then fails at runtime with an undefined property.\n' +
+                    '    Either install the matching library version, or pin the older\n' +
+                    '    @girs/* release. GIRepository cannot detect this — it matches the\n' +
+                    '    API version (e.g. 4.0) only, so any 4.x typelib satisfies gi://Gtk.');
+            }
+        }
         console.log(`\nPackage manager: ${pm}`);
         if (allMissing.length === 0) {
             console.log('\nAll dependencies found.');

package/lib/config.js

@@ -223,7 +223,7 @@ export class Config {
         const pkg = (await this.readPackageJSON(configFilePath));
         const tsConfig = (await this.readTSConfig(configFilePath));
         tsConfig.reflection ||= cliArgs.reflection;
-        // TODO replace with `cliArgs.logLevel`
+        // TODO(open-todos: 10 small API gaps): replace with `cliArgs.logLevel`
         configData.verbose = cliArgs.verbose || false;
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined)

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

@@ -61,6 +61,17 @@ export declare function buildLauncherShims(opts: {
      * path the prebuilds have to be reachable through.
      */
     prependEnv?: Readonly<Record<string, string>>;
+    /**
+     * Second interpreter + script to run when the primary interpreter is not on
+     * `PATH`. The batch/PowerShell counterpart of {@link buildShLauncher}'s
+     * `nodeFallbackAbs` — a Windows host with no `gjs` is the majority case, and
+     * the `.cmd`/`.ps1` members are the ones cmd.exe and pwsh actually reach.
+     */
+    fallback?: {
+        interpreter: string;
+        interpreterArgs?: readonly string[];
+        target: string;
+    };
 }): {
     cmd: string;
     ps1: string;
@@ -119,6 +130,32 @@ export declare function buildLauncherShims(opts: {
  * script chain: the self-relative `@loader_path` rpath that
  * `check-prebuild-loader-path.mjs` enforces is what actually has to carry it.
  *
+ * NOT EXTENDED WITH THE HOST'S GI LIBDIRS — a decision, not an oversight.
+ * `buildNativeEnv()` now puts `systemGiLibraryDirs()` on the gjs CHILD's
+ * `DYLD_FALLBACK_LIBRARY_PATH`, which repairs every command that goes through this
+ * CLI. A launcher that `exec`s a GJS bundle DIRECTLY — `gjsify install -g` on a
+ * package whose `gjsify.bin` is a GTK app — has no CLI in the loop and still
+ * carries the gap.
+ *
+ * The MECHANISM would work, and that was measured on the macOS 15.7.8 VM rather
+ * than assumed. It is a finer point than the caveat above: what SIP strips is an
+ * INHERITED `DYLD_*` at the `/bin/sh` exec, so a value this preamble exports
+ * ITSELF survives the following `exec gjs` (an unprotected Homebrew binary) and
+ * `Gtk.init()` then succeeds. What is missing is a shape worth having:
+ *
+ *   - BAKING `systemGiLibraryDirs()` in at write time reintroduces precisely the
+ *     snapshot this function exists to remove — a launcher is routinely written
+ *     BEFORE `brew install gtk4`, and would bake nothing while saying nothing.
+ *   - RE-DERIVING it in shell means a THIRD copy of a rule that already has two,
+ *     pinned in agreement by `system-gi.spec.ts` — and shell can express only one
+ *     of its three sources (the probed prefixes; `pkg-config` would be a spawn on
+ *     every launch), so that copy would be knowingly partial, in the one language
+ *     nothing here type-checks.
+ *
+ * So the gap is recorded in `status/open-todos.md` with the measurement attached
+ * instead of being closed by a mechanism that drifts. Closing it properly means
+ * teaching such a launcher to defer to the CLI, not to re-derive.
+ *
  * @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).
@@ -156,6 +193,26 @@ export declare function normalizeBinMap(pkgName: string, bin: string | Record<st
  *
  * `isGjsBin` lets the caller keep plain-Node packages on the plain symlink path
  * — this must not change how `lodash`'s bin is linked.
+ *
+ * WHY THE npm MAP COMES BACK TOO
+ *
+ * The reasoning above is sound and INCOMPLETE: it was written from the Node-less
+ * GJS host and is blind to the mirror case. `@gjsify/cli` declares BOTH fields,
+ * so a host with no `gjs` — macOS and Windows, the two active port targets —
+ * got `exec gjs -m <bundle>`, which is exit 127, while a working Node entry sat
+ * beside it in the same package. `cli-cross-platform.yml` recorded that on both
+ * OSes for three consecutive releases (v0.27.1, v0.28.0, v0.29.0); it is
+ * advisory, so it stayed red. The install even KNEW: its own post-install check
+ * printed `Missing required system dependencies: ✗ GJS` and then wrote a
+ * gjs-only launcher anyway.
+ *
+ * So `nodeFallback` carries the npm map alongside, and the LAUNCHER decides per
+ * invocation. Deliberately not an install-time host probe: an install-time
+ * decision is a SNAPSHOT, and this repo has already paid for that exact mistake
+ * once — `buildNativeEnvPreamble` used to bake the install-time prebuild scan,
+ * so a package installed later was invisible and v0.24.1 shipped a launcher with
+ * no preamble at all. A host probe here fails the same way in reverse: install
+ * without gjs, install gjs afterwards, shim still points at Node forever.
  */
 export declare function pickBinMap(pkgName: string, pkgJson: {
     bin?: string | Record<string, string>;
@@ -165,6 +222,7 @@ export declare function pickBinMap(pkgName: string, pkgJson: {
 }): {
     map: Map<string, string>;
     isGjsBin: boolean;
+    nodeFallback: Map<string, string> | null;
 } | null;
 /**
  * The POSIX `sh` launcher gjsify writes for a bin it owns.
@@ -179,10 +237,17 @@ export declare function pickBinMap(pkgName: string, pkgJson: {
  * because not every published bundle carries a `#!/usr/bin/env -S gjs -m` line,
  * and direct-exec'ing a shebang-less `.mjs` falls through to `/bin/sh`, which
  * then parses JavaScript as shell.
+ *
+ * `nodeFallbackAbs` makes the runtime choice per INVOCATION rather than per
+ * install — see {@link pickBinMap} for why a host probe at install time is the
+ * wrong shape. `gjs` stays first: that is today's behaviour on a host carrying
+ * both, and which runtime wins is a separate decision from making the shim
+ * runnable at all.
  */
 export declare function buildShLauncher(targetAbs: string, opts: {
     envPreamble?: string;
     isGjsBundle: boolean;
+    nodeFallbackAbs?: string;
 }): string;
 /** True when a bin target is a GJS-runnable bundle rather than a Node script. */
 export declare function isGjsBundlePath(target: string): boolean;

package/lib/utils/bin-shim.js

@@ -223,26 +223,63 @@ export function buildCmdShim(relTargetPosix, shebang) {
  * fails the same way on every OS.
  */
 export function buildLauncherShims(opts) {
-    const { interpreter, interpreterArgs = [], target, prependEnv = {} } = opts;
+    const { interpreter, interpreterArgs = [], target, prependEnv = {}, fallback } = opts;
     const winTarget = target.split('/').join('\\');
     const argv = interpreterArgs.length > 0 ? `${interpreterArgs.join(' ')} ` : '';
     const entries = Object.entries(prependEnv);
+    const fbTarget = fallback === undefined ? '' : fallback.target.split('/').join('\\');
+    const fbArgv = fallback?.interpreterArgs !== undefined && fallback.interpreterArgs.length > 0
+        ? `${fallback.interpreterArgs.join(' ')} `
+        : '';
     let cmd = CMD_HEAD;
     for (const [key, value] of entries)
         cmd += `@SET "${key}=${value};%${key}%"\r\n`;
-    cmd += `${interpreter} ${argv}"${winTarget}" %*\r\n`;
+    if (fallback === undefined) {
+        cmd += `${interpreter} ${argv}"${winTarget}" %*\r\n`;
+    }
+    else {
+        // `where` is the batch equivalent of `command -v`; it writes to stdout,
+        // so both streams are silenced. ERRORLEVEL is read via IF/ELSE rather
+        // than `&&`/`||` chaining, which would swallow the child's own exit code.
+        cmd +=
+            `@where ${interpreter} >NUL 2>NUL\r\n` +
+                `@IF %ERRORLEVEL% EQU 0 (\r\n` +
+                `  ${interpreter} ${argv}"${winTarget}" %*\r\n` +
+                `) ELSE (\r\n` +
+                `  ${fallback.interpreter} ${fbArgv}"${fbTarget}" %*\r\n` +
+                `)\r\n`;
+    }
     let ps1 = '#!/usr/bin/env pwsh\n';
     for (const [key, value] of entries)
         ps1 += `$env:${key} = "${value};" + $env:${key}\n`;
     const ps1Args = interpreterArgs.map((a) => `"${a}" `).join('');
-    ps1 +=
-        '# Support pipeline input\n' +
-            'if ($MyInvocation.ExpectingInput) {\n' +
-            `  $input | & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
-            '} else {\n' +
-            `  & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
-            '}\n' +
-            'exit $LASTEXITCODE\n';
+    if (fallback === undefined) {
+        ps1 +=
+            '# Support pipeline input\n' +
+                'if ($MyInvocation.ExpectingInput) {\n' +
+                `  $input | & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
+                '} else {\n' +
+                `  & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
+                '}\n';
+    }
+    else {
+        // Bind the three parts once, then call once — the alternative (a full
+        // if/else around two near-identical invocation blocks, each of which
+        // already branches on pipeline input) is four copies of the same call.
+        const psList = (a) => a.length === 0 ? '@()' : `@(${a.map((x) => `"${x}"`).join(', ')})`;
+        ps1 +=
+            `$exe = "${interpreter}"; $exeArgs = ${psList(interpreterArgs)}; $script = "${winTarget}"\n` +
+                `if (-not (Get-Command "${interpreter}" -ErrorAction SilentlyContinue)) {\n` +
+                `  $exe = "${fallback.interpreter}"; $exeArgs = ${psList(fallback.interpreterArgs ?? [])}; $script = "${fbTarget}"\n` +
+                '}\n' +
+                '# Support pipeline input\n' +
+                'if ($MyInvocation.ExpectingInput) {\n' +
+                '  $input | & $exe @exeArgs $script $args\n' +
+                '} else {\n' +
+                '  & $exe @exeArgs $script $args\n' +
+                '}\n';
+    }
+    ps1 += 'exit $LASTEXITCODE\n';
     return { cmd, ps1 };
 }
 /** POSIX `sh` single-quoting — the one place the escape lives. */
@@ -303,6 +340,32 @@ function shQuote(s) {
  * script chain: the self-relative `@loader_path` rpath that
  * `check-prebuild-loader-path.mjs` enforces is what actually has to carry it.
  *
+ * NOT EXTENDED WITH THE HOST'S GI LIBDIRS — a decision, not an oversight.
+ * `buildNativeEnv()` now puts `systemGiLibraryDirs()` on the gjs CHILD's
+ * `DYLD_FALLBACK_LIBRARY_PATH`, which repairs every command that goes through this
+ * CLI. A launcher that `exec`s a GJS bundle DIRECTLY — `gjsify install -g` on a
+ * package whose `gjsify.bin` is a GTK app — has no CLI in the loop and still
+ * carries the gap.
+ *
+ * The MECHANISM would work, and that was measured on the macOS 15.7.8 VM rather
+ * than assumed. It is a finer point than the caveat above: what SIP strips is an
+ * INHERITED `DYLD_*` at the `/bin/sh` exec, so a value this preamble exports
+ * ITSELF survives the following `exec gjs` (an unprotected Homebrew binary) and
+ * `Gtk.init()` then succeeds. What is missing is a shape worth having:
+ *
+ *   - BAKING `systemGiLibraryDirs()` in at write time reintroduces precisely the
+ *     snapshot this function exists to remove — a launcher is routinely written
+ *     BEFORE `brew install gtk4`, and would bake nothing while saying nothing.
+ *   - RE-DERIVING it in shell means a THIRD copy of a rule that already has two,
+ *     pinned in agreement by `system-gi.spec.ts` — and shell can express only one
+ *     of its three sources (the probed prefixes; `pkg-config` would be a spawn on
+ *     every launch), so that copy would be knowingly partial, in the one language
+ *     nothing here type-checks.
+ *
+ * So the gap is recorded in `status/open-todos.md` with the measurement attached
+ * instead of being closed by a mechanism that drifts. Closing it properly means
+ * teaching such a launcher to defer to the CLI, not to re-derive.
+ *
  * @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).
@@ -411,14 +474,39 @@ export function normalizeBinMap(pkgName, bin) {
  *
  * `isGjsBin` lets the caller keep plain-Node packages on the plain symlink path
  * — this must not change how `lodash`'s bin is linked.
+ *
+ * WHY THE npm MAP COMES BACK TOO
+ *
+ * The reasoning above is sound and INCOMPLETE: it was written from the Node-less
+ * GJS host and is blind to the mirror case. `@gjsify/cli` declares BOTH fields,
+ * so a host with no `gjs` — macOS and Windows, the two active port targets —
+ * got `exec gjs -m <bundle>`, which is exit 127, while a working Node entry sat
+ * beside it in the same package. `cli-cross-platform.yml` recorded that on both
+ * OSes for three consecutive releases (v0.27.1, v0.28.0, v0.29.0); it is
+ * advisory, so it stayed red. The install even KNEW: its own post-install check
+ * printed `Missing required system dependencies: ✗ GJS` and then wrote a
+ * gjs-only launcher anyway.
+ *
+ * So `nodeFallback` carries the npm map alongside, and the LAUNCHER decides per
+ * invocation. Deliberately not an install-time host probe: an install-time
+ * decision is a SNAPSHOT, and this repo has already paid for that exact mistake
+ * once — `buildNativeEnvPreamble` used to bake the install-time prebuild scan,
+ * so a package installed later was invisible and v0.24.1 shipped a launcher with
+ * no preamble at all. A host probe here fails the same way in reverse: install
+ * without gjs, install gjs afterwards, shim still points at Node forever.
  */
 export function pickBinMap(pkgName, pkgJson) {
     const gjsifyBin = pkgJson.gjsify?.bin;
-    if (gjsifyBin !== undefined)
-        return { map: normalizeBinMap(pkgName, gjsifyBin), isGjsBin: true };
     const npmBin = pkgJson.bin;
+    if (gjsifyBin !== undefined) {
+        return {
+            map: normalizeBinMap(pkgName, gjsifyBin),
+            isGjsBin: true,
+            nodeFallback: npmBin === undefined ? null : normalizeBinMap(pkgName, npmBin),
+        };
+    }
     if (npmBin !== undefined)
-        return { map: normalizeBinMap(pkgName, npmBin), isGjsBin: false };
+        return { map: normalizeBinMap(pkgName, npmBin), isGjsBin: false, nodeFallback: null };
     return null;
 }
 /**
@@ -434,9 +522,23 @@ export function pickBinMap(pkgName, pkgJson) {
  * because not every published bundle carries a `#!/usr/bin/env -S gjs -m` line,
  * and direct-exec'ing a shebang-less `.mjs` falls through to `/bin/sh`, which
  * then parses JavaScript as shell.
+ *
+ * `nodeFallbackAbs` makes the runtime choice per INVOCATION rather than per
+ * install — see {@link pickBinMap} for why a host probe at install time is the
+ * wrong shape. `gjs` stays first: that is today's behaviour on a host carrying
+ * both, and which runtime wins is a separate decision from making the shim
+ * runnable at all.
  */
 export function buildShLauncher(targetAbs, opts) {
     const preamble = opts.isGjsBundle ? (opts.envPreamble ?? '') : '';
+    if (opts.isGjsBundle && opts.nodeFallbackAbs !== undefined) {
+        // The preamble only ever configures the GI search path, so it stays
+        // inside the gjs branch — exporting it around a Node exec would be
+        // inert at best and misleading to anyone reading the shim.
+        return (`#!/bin/sh\nif command -v gjs >/dev/null 2>&1; then\n${preamble}` +
+            `exec gjs -m ${shQuote(targetAbs)} "$@"\nfi\n` +
+            `exec node ${shQuote(opts.nodeFallbackAbs)} "$@"\n`);
+    }
     const exec = opts.isGjsBundle ? `exec gjs -m ${shQuote(targetAbs)} "$@"` : `exec ${shQuote(targetAbs)} "$@"`;
     return `#!/bin/sh\n${preamble}${exec}\n`;
 }

package/lib/utils/check-system-deps.d.ts

@@ -28,6 +28,27 @@ export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew
  * MacPorts or Nix host, and it is why this must never fall back to "probably brew".
  */
 export declare function detectPackageManager(): PackageManager;
+interface OptionalDep {
+    /** DepCheck id */
+    id: string;
+    /** Display name */
+    name: string;
+    /** pkg-config library name */
+    pkgName: string;
+}
+/** Optional system deps keyed by their DepCheck id. Exported for the spec's declaration invariant. */
+export declare const OPTIONAL_DEPS: Record<string, OptionalDep>;
+/**
+ * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
+ * Generated by walking each package's `gi://` imports (excluding the always-
+ * available trio GLib/GObject/Gio).
+ *
+ * Used to compute the set of optional deps to check for a given project.
+ *
+ * Exported for the spec's declaration invariant: every id named here must exist in
+ * OPTIONAL_DEPS, or the dep is silently never checked.
+ */
+export declare const PACKAGE_DEPS: Record<string, string[]>;
 /**
  * Run all dependency checks. Used by `gjsify check` to show full system status.
  *
@@ -52,3 +73,38 @@ export declare function checkGwebgl(cwd: string): DepCheck;
  * Returns null when package manager is unknown or no installable deps are missing.
  */
 export declare function buildInstallCommand(pm: PackageManager, missing: DepCheck[]): string | null;
+export interface TypeSkew {
+    typePackage: string;
+    pkgConfig: string;
+    /** `libraryVersion` declared by the installed `@girs/*` package. */
+    declared: string;
+    /** `pkg-config --modversion` of the library the host actually has. */
+    installed: string;
+    /**
+     * `ahead` = the types describe a NEWER library than is installed. This is the
+     * direction that compiles and then throws, so it is the one worth reporting.
+     * `behind` = API the host has is invisible to the compiler; limiting, not wrong.
+     */
+    relation: 'ahead' | 'behind';
+}
+/**
+ * Readers the comparison depends on, injectable so every branch is unit-testable
+ * from ANY host. Same reasoning as `resolvePrebuildDirName`, which is a pure
+ * function of injected values precisely so its darwin/win32 branches are tested
+ * from Linux: a check whose only test is "run it on the maintainer's machine and
+ * look" is a check whose skew cases are never exercised.
+ */
+export interface TypeSkewReaders {
+    /** `libraryVersion` of an installed `@girs/*` package, or null when absent. */
+    readDeclared?: (cwd: string, typePackage: string) => string | null;
+    /** `pkg-config --modversion` of a library, or null when absent. */
+    readInstalled?: (pkgConfig: string) => string | null;
+}
+/**
+ * Compare each installed `@girs/*` package's declared upstream version against the
+ * library the host actually has. Only reports a `major.minor` difference: a micro
+ * difference does not change the API set, and reporting it would train people to
+ * ignore the output.
+ */
+export declare function checkTypeSkew(cwd: string, readers?: TypeSkewReaders): TypeSkew[];
+export {};