@gjsify/cli 0.27.1 → 0.29.0

package/lib/commands/debug.d.ts

@@ -1,6 +1,7 @@
 import type { Command } from '../types/index.js';
 interface DebugCliOptions {
     busName?: string;
+    address?: string;
     profile?: string;
     globals?: string;
     out?: string;

package/lib/commands/debug.js

@@ -43,26 +43,32 @@ function deriveBrowserAppId(name) {
 function hasDep(pkg, name) {
     return Boolean(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
 }
-function generateEntry(profile, busNameBase, name, version) {
+function generateEntry(profile, busNameBase, name, version, address) {
+    const base = JSON.stringify(busNameBase);
+    // Only emit the option when an address was actually given: an `address:
+    // undefined` in the generated entry would read like a decision, when the
+    // bridge's own precedence (env var → published address file → session bus)
+    // is what should apply.
+    const options = address ? `, { address: ${JSON.stringify(address)} }` : '';
     if (profile === 'storybook') {
         return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
 import { runDevtoolsMcp, storybookProfile } from '@gjsify/devtools-mcp';
 
-await runDevtoolsMcp(storybookProfile(${JSON.stringify(busNameBase)}));
+await runDevtoolsMcp(storybookProfile(${base}${options}));
 `;
     }
     if (profile === 'browser') {
         return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
 import { runDevtoolsMcp, browserProfile } from '@gjsify/devtools-mcp';
 
-await runDevtoolsMcp(browserProfile(${JSON.stringify(busNameBase)}));
+await runDevtoolsMcp(browserProfile(${base}${options}));
 `;
     }
     if (profile === 'cdp') {
         return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
 import { runDevtoolsMcp, cdpProfile } from '@gjsify/devtools-mcp';
 
-await runDevtoolsMcp(cdpProfile(${JSON.stringify(busNameBase)}));
+await runDevtoolsMcp(cdpProfile(${base}${options}));
 `;
     }
     return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
@@ -71,7 +77,7 @@ import { runDevtoolsMcp } from '@gjsify/devtools-mcp';
 await runDevtoolsMcp({
     name: ${JSON.stringify(name)},
     version: ${JSON.stringify(version)},
-    busNameBase: ${JSON.stringify(busNameBase)},
+    busNameBase: ${base},${address ? `\n    address: ${JSON.stringify(address)},` : ''}
 });
 `;
 }
@@ -82,6 +88,12 @@ export const debugCommand = {
         .option('bus-name', {
         description: 'App DBus base name (default: gjsify.devtools.busNameBase, or the storybook app-id)',
         type: 'string',
+    })
+        .option('address', {
+        description: 'Peer D-Bus address of the app (unix:path=… / nonce-tcp:…) instead of the session bus — for ' +
+            'macOS/Windows, which have no session bus. Default: GJSIFY_DEVTOOLS_ADDRESS, then the address ' +
+            'file the app publishes, then the session bus',
+        type: 'string',
     })
         .option('profile', {
         description: 'Tool profile: generic | storybook | browser | cdp (default: auto — storybook if @gjsify/storybook is a dep, browser if @gjsify/devtools-browser is, cdp if @gjsify/devtools-cdp is, else generic)',
@@ -133,9 +145,10 @@ export const debugCommand = {
         mkdirSync(cacheDir, { recursive: true });
         const entryPath = join(cacheDir, 'entry.ts');
         const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, 'bridge.gjs.mjs');
-        writeFileSync(entryPath, generateEntry(profile, busNameBase, name, version));
+        const address = args.address ?? config.address;
+        writeFileSync(entryPath, generateEntry(profile, busNameBase, name, version, address));
         // stderr only — stdout is the MCP JSON-RPC channel.
-        console.error(`[gjsify debug] profile=${profile} bus=${busNameBase}`);
+        console.error(`[gjsify debug] profile=${profile} bus=${busNameBase}${address ? ` address=${address}` : ''}`);
         // In-process build (runtime-agnostic), then launch with stdio inherited
         // so the bridge's JSON-RPC stdin/stdout are the client's pipes.
         const { runCli } = await import('../cli-app.js');

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/utils/bin-shim.d.ts

@@ -119,6 +119,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).

package/lib/utils/bin-shim.js

@@ -303,6 +303,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).

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

@@ -52,3 +52,37 @@ 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[];

package/lib/utils/check-system-deps.js

@@ -11,7 +11,7 @@
 // is in the project's dependency tree. A user with only @gjsify/fs in their
 // project never sees a warning about libmanette.
 import { execFileSync } from 'node:child_process';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
@@ -546,3 +546,123 @@ export function buildInstallCommand(pm, missing) {
     }
     return lines.length > 0 ? lines.join('\n  ') : null;
 }
+/**
+ * Only libraries whose GIR carries a real `<package version>`, verified against
+ * the published packages rather than assumed. A binding whose value turns out
+ * degenerate is skipped at runtime by `isDegenerate`, so a wrong entry here
+ * cannot produce a false alarm — it can only produce silence.
+ */
+const TYPE_PACKAGE_BINDINGS = [
+    { pkgConfig: 'gtk4', typePackage: '@girs/gtk-4.0', namespaceVersion: '4.0' },
+    { pkgConfig: 'libadwaita-1', typePackage: '@girs/adw-1', namespaceVersion: '1' },
+    { pkgConfig: 'libsoup-3.0', typePackage: '@girs/soup-3.0', namespaceVersion: '3.0' },
+    { pkgConfig: 'glib-2.0', typePackage: '@girs/glib-2.0', namespaceVersion: '2.0' },
+    { pkgConfig: 'gobject-2.0', typePackage: '@girs/gobject-2.0', namespaceVersion: '2.0' },
+    { pkgConfig: 'gio-2.0', typePackage: '@girs/gio-2.0', namespaceVersion: '2.0' },
+    { pkgConfig: 'gstreamer-1.0', typePackage: '@girs/gst-1.0', namespaceVersion: '1.0' },
+    { pkgConfig: 'webkitgtk-6.0', typePackage: '@girs/webkit-6.0', namespaceVersion: '6.0' },
+    { pkgConfig: 'manette-0.2', typePackage: '@girs/manette-0.2', namespaceVersion: '0.2' },
+    { pkgConfig: 'pango', typePackage: '@girs/pango-1.0', namespaceVersion: '1.0' },
+    { pkgConfig: 'harfbuzz', typePackage: '@girs/harfbuzz-0.0', namespaceVersion: '0.0' },
+];
+/**
+ * Read `libraryVersion` from an installed `@girs/*` package.
+ *
+ * Resolves the package's MAIN entry and walks up to its root `package.json`
+ * rather than resolving the `package.json` subpath: `@girs/*` exports maps do not
+ * expose `./package.json` (verified on all 32 installed packages), so
+ * `require.resolve('@girs/gtk-4.0/package.json')` throws
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED`. The same trap silently disabled the
+ * `@nativescript/vite` major-version gate until it was found by measurement.
+ */
+function readGirsLibraryVersion(cwd, typePackage) {
+    for (const from of [pathToFileURL(join(cwd, '_girs_.js')).href, import.meta.url]) {
+        let dir;
+        try {
+            dir = dirname(createRequire(from).resolve(typePackage));
+        }
+        catch {
+            continue;
+        }
+        // Walk up to the package root — the entry may sit in a subdirectory.
+        for (let i = 0; i < 5; i++) {
+            const manifest = join(dir, 'package.json');
+            if (existsSync(manifest)) {
+                try {
+                    const parsed = JSON.parse(readFileSync(manifest, 'utf-8'));
+                    if (parsed.name === typePackage)
+                        return parsed.libraryVersion ?? null;
+                }
+                catch {
+                    return null; // present but unreadable — nothing to compare against
+                }
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+/** `[major, minor]`, or null when the string is not a comparable version. */
+function majorMinor(version) {
+    const match = /^(\d+)\.(\d+)/.exec(version.trim());
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2])];
+}
+/**
+ * True when `libraryVersion` is ts-for-gir's namespace-version fallback rather
+ * than a real upstream release — `@girs/gdk-4.0`'s `4.0.0` against namespace `4.0`.
+ *
+ * Compares against every `.0`-padded spelling of the namespace version, not just
+ * the three-component one: `4.0` and `4.0.0` are the same claim, and matching only
+ * the padded form let the bare spelling through as a bogus 18-minor "behind"
+ * finding. Deliberately NOT a major.minor comparison — `@girs/adw-1` has namespace
+ * `1` and a real `libraryVersion` of `1.10.0`, which any major-only rule discards.
+ */
+function isDegenerate(declared, namespaceVersion) {
+    const trimmed = declared.trim();
+    const parts = namespaceVersion.split('.');
+    for (let n = parts.length; n <= 3; n++) {
+        if (trimmed === [...parts, ...Array(n - parts.length).fill('0')].join('.'))
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 function checkTypeSkew(cwd, readers = {}) {
+    const readDeclared = readers.readDeclared ?? readGirsLibraryVersion;
+    const readInstalled = readers.readInstalled ?? ((pkgConfig) => tryExecFile('pkg-config', ['--modversion', pkgConfig]));
+    const findings = [];
+    for (const binding of TYPE_PACKAGE_BINDINGS) {
+        const declared = readDeclared(cwd, binding.typePackage);
+        if (declared === null)
+            continue; // types not installed, or no declaration
+        if (isDegenerate(declared, binding.namespaceVersion))
+            continue;
+        const installed = readInstalled(binding.pkgConfig);
+        if (installed === null)
+            continue; // library absent — the presence check owns that
+        const want = majorMinor(declared);
+        const have = majorMinor(installed.split('\n')[0] ?? installed);
+        if (!want || !have)
+            continue;
+        if (want[0] === have[0] && want[1] === have[1])
+            continue;
+        findings.push({
+            typePackage: binding.typePackage,
+            pkgConfig: binding.pkgConfig,
+            declared,
+            installed: installed.split('\n')[0] ?? installed,
+            relation: want[0] > have[0] || (want[0] === have[0] && want[1] > have[1]) ? 'ahead' : 'behind',
+        });
+    }
+    return findings;
+}

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

@@ -1,3 +1,4 @@
+import { type SystemGiOptions } from './system-gi.js';
 export interface NativePackage {
     /** npm package name, e.g. "@gjsify/webgl" */
     name: string;
@@ -42,8 +43,15 @@ export interface NativeEnv {
     GI_TYPELIB_PATH: string;
     /** ELF loader (Linux and other ELF platforms). */
     LD_LIBRARY_PATH?: string;
-    /** Mach-O loader (macOS). `dyld` ignores `LD_LIBRARY_PATH` entirely. */
+    /** Mach-O loader (macOS), OVERRIDING resolution by leaf. `dyld` ignores `LD_LIBRARY_PATH` entirely. */
     DYLD_LIBRARY_PATH?: string;
+    /**
+     * Mach-O loader (macOS), consulted only AFTER the normal search fails. This
+     * is where the HOST's GI libdirs go — never `DYLD_LIBRARY_PATH`, which would
+     * shadow correctly-resolved libraries process-wide. See
+     * {@link buildNativeEnv}.
+     */
+    DYLD_FALLBACK_LIBRARY_PATH?: string;
     [key: string]: string | undefined;
 }
 /**
@@ -287,8 +295,44 @@ export declare function libraryPathVar(platform: string): {
  * (a stock Windows env block uses `Path`) — Windows env names are
  * case-insensitive, but a plain JS object is not, and `{...process.env,
  * PATH: …}` would hand a child process two competing entries.
+ *
+ * ── DARWIN ALSO GETS THE *HOST'S* GI LIBDIRS ─────────────────────────────────
+ *
+ * Everything above is about the prebuilds gjsify itself ships. On macOS there is
+ * a second, independent gap that has nothing to do with gjsify: a typelib names
+ * its library by BARE LEAF (`libgtk-4.1.dylib`), and dyld carries neither
+ * `/usr/local/lib` nor `/opt/homebrew/lib` in its default fallback path.
+ * Homebrew's `gjs` has an rpath into GLIB's keg only, so it resolves no other
+ * keg's leaves — measured: bare `gjs -c "imports.gi.Gtk; Gtk.init()"`, no gjsify
+ * in the process, dies on that dlopen (full trace in `utils/system-gi.ts`). This
+ * is the ONE place `gjsify run`, `showcase`, `storybook`, `tsc` and `info` all
+ * pass through, so it is where the child's launch env is repaired.
+ *
+ * Two properties are load-bearing:
+ *
+ *   1. **`DYLD_FALLBACK_LIBRARY_PATH`, never `DYLD_LIBRARY_PATH`.** The override
+ *      variable wins by LEAF for every dylib in the process, including ones the
+ *      host already resolved correctly — pointing it at a whole system libdir is
+ *      how you replace a linked-against library with a same-named different one.
+ *      The fallback is consulted only after the normal search fails, which is
+ *      exactly the "nothing else found it" case. Consequence, and it is the
+ *      intended precedence: gjsify's own prebuilds keep priority through the
+ *      override variable, the system stack fills in behind it.
+ *   2. **Our dirs go FIRST, an inherited fallback is kept BEHIND them, and
+ *      `/usr/lib` is appended when there is none.** Setting the variable
+ *      REPLACES dyld's own default fallback list, so writing only our dirs would
+ *      silently remove `/usr/lib` from the search — a host that exported the
+ *      variable itself already carries whatever tail it wants. Same composition
+ *      as node-gi's re-exec.
+ *
+ * Emitted even when `packages` is empty: the gap is in the host's loader, not in
+ * a gjsify prebuild, so a plain `gjsify run script.gjs.js` that touches GTK needs
+ * it just as much. Empty off darwin — `ld.so`'s configured cache already resolves
+ * these leaves on Linux, and Windows re-reads `PATH` per `LoadLibrary`.
  */
 export declare function buildNativeEnv(packages: NativePackage[], opts?: {
     platform?: string;
     env?: Record<string, string | undefined>;
+    /** Injectable for tests — the darwin branch is asserted from Linux. */
+    systemGiDirs?: (opts: SystemGiOptions) => string[];
 }): NativeEnv;