@gjsify/cli 0.41.0 → 0.43.0

package/lib/utils/dev-plan.d.ts

@@ -0,0 +1,52 @@
+export interface DevPlanRequest {
+    /** The project's `package.json#scripts`. */
+    scripts: Readonly<Record<string, string>>;
+    /** Name of the build script to reuse, e.g. `build:gjs`. */
+    scriptName: string;
+    /** `gjsify build --app <app>` target the chosen runtime consumes. */
+    app: 'gjs' | 'node';
+    /** The bundle the package declares for `app` (`gjsify.main` / `gjsify.example.node`). */
+    declaredBundle?: string;
+    /** `gjsify dev [entry]` — overrides the entry point the script names. */
+    entry?: string;
+    /** `--globals` override. */
+    globals?: string;
+    /** `--outfile` override. */
+    outfile?: string;
+    /** `--watch-dir` override. */
+    watchDir?: string;
+}
+export interface DevPlan {
+    /** argv fed to `runCli` on every rebuild (starts with `build`). */
+    buildArgv: string[];
+    /**
+     * Bundle launched after a successful build, or undefined when nothing names
+     * one. See {@link noBundleError}.
+     */
+    bundle?: string;
+    /** Directory watched recursively. */
+    watchDir: string;
+}
+/** The value of `--name value` / `--name=value` in `argv`, if present. */
+export declare function readFlag(argv: readonly string[], name: string): string | undefined;
+/** `argv` with `--name value` set — replacing any existing occurrence, else appended. */
+export declare function withFlag(argv: readonly string[], name: string, value: string): string[];
+/**
+ * The entry point a `gjsify build` argv names positionally. Only the token
+ * DIRECTLY after `build` counts: further positionals are indistinguishable from
+ * the value of a preceding flag without knowing every flag's arity, and a wrong
+ * guess here would silently build the wrong file.
+ */
+export declare function buildEntryPoint(argv: readonly string[]): string | undefined;
+/**
+ * Resolve the build argv, the bundle to launch and the directory to watch.
+ * Throws with both fixes named when the project declares neither.
+ */
+export declare function planDev(req: DevPlanRequest): DevPlan;
+/**
+ * Message for a launch that has no bundle to launch. Separate from `planDev`
+ * because only the LAUNCHING caller needs one: a build writing an `--outdir`
+ * legitimately has no single output file, and refusing inside the planner would
+ * fail `--build-only` for a reason that does not apply to it.
+ */
+export declare function noBundleError(scriptName: string, app: 'gjs' | 'node'): Error;

package/lib/utils/dev-plan.js

@@ -0,0 +1,117 @@
+// What `gjsify dev` builds, launches and watches — resolved from the project's
+// OWN declarations rather than from a second set of flags.
+//
+// Re-declaring `--globals auto,dom,PointerEvent,…` here, beside the `build:gjs`
+// script that already says it, would be exactly the drifting second copy this
+// repo keeps paying for: the day the build script gains a flag, the dev loop
+// builds a different bundle than `gjsify run build` does, and the difference
+// surfaces as a runtime error in the app rather than as a diff. So the plan is
+// DERIVED from the script, with the CLI flags as overrides on top.
+//
+// Pure by design — no filesystem, no process — so precedence is unit-tested
+// instead of inferred from a running watch loop.
+import { dirname } from 'node:path';
+import { gjsifyCommandArgv } from './simple-command.js';
+/** The value of `--name value` / `--name=value` in `argv`, if present. */
+export function readFlag(argv, name) {
+    const long = `--${name}`;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === long)
+            return argv[i + 1];
+        if (token.startsWith(`${long}=`))
+            return token.slice(long.length + 1);
+    }
+    return undefined;
+}
+/** `argv` with `--name value` set — replacing any existing occurrence, else appended. */
+export function withFlag(argv, name, value) {
+    const long = `--${name}`;
+    const out = [...argv];
+    for (let i = 0; i < out.length; i++) {
+        const token = out[i];
+        if (token === long) {
+            out[i + 1] = value;
+            return out;
+        }
+        if (token.startsWith(`${long}=`)) {
+            out[i] = `${long}=${value}`;
+            return out;
+        }
+    }
+    out.push(long, value);
+    return out;
+}
+/**
+ * The entry point a `gjsify build` argv names positionally. Only the token
+ * DIRECTLY after `build` counts: further positionals are indistinguishable from
+ * the value of a preceding flag without knowing every flag's arity, and a wrong
+ * guess here would silently build the wrong file.
+ */
+export function buildEntryPoint(argv) {
+    const candidate = argv[1];
+    if (candidate === undefined || candidate.startsWith('-'))
+        return undefined;
+    return candidate;
+}
+/** Message shown when neither a usable build script nor an explicit entry exists. */
+function noEntryError(scriptName, hasScript) {
+    const why = hasScript
+        ? `\`${scriptName}\` is not a plain \`gjsify build <entry> …\` command, so its entry point cannot be read`
+        : `this package declares no \`${scriptName}\` script`;
+    return new Error(`gjsify dev: nothing to build — ${why}.\n` +
+        `  Name the entry point directly:   gjsify dev src/index.ts\n` +
+        `  or point at another script:      gjsify dev --script <name>`);
+}
+/**
+ * Resolve the build argv, the bundle to launch and the directory to watch.
+ * Throws with both fixes named when the project declares neither.
+ */
+export function planDev(req) {
+    const literal = req.scripts[req.scriptName];
+    const scriptArgv = typeof literal === 'string' ? gjsifyCommandArgv(literal) : null;
+    const derived = scriptArgv && scriptArgv[0] === 'build' ? scriptArgv : null;
+    const entry = req.entry ?? (derived ? buildEntryPoint(derived) : undefined);
+    if (entry === undefined)
+        throw noEntryError(req.scriptName, typeof literal === 'string');
+    // Start from the script's own argv so every flag it declares survives, then
+    // put the overrides on top. `--app` is SET rather than inherited: `--script`
+    // and `--runtime` can name different targets, and the runtime that will
+    // launch the bundle is the one that must decide what is built.
+    let argv;
+    if (derived) {
+        argv = [...derived];
+        // Replace the entry the script names, or splice one in when it names
+        // none (the script may take its entry from `gjsify.bundler.input`).
+        if (buildEntryPoint(derived) !== undefined)
+            argv[1] = entry;
+        else
+            argv.splice(1, 0, entry);
+    }
+    else {
+        argv = ['build', entry];
+    }
+    argv = withFlag(argv, 'app', req.app);
+    if (req.globals !== undefined)
+        argv = withFlag(argv, 'globals', req.globals);
+    if (req.outfile !== undefined)
+        argv = withFlag(argv, 'outfile', req.outfile);
+    return {
+        buildArgv: argv,
+        bundle: readFlag(argv, 'outfile') ?? req.declaredBundle,
+        watchDir: req.watchDir ?? dirname(entry),
+    };
+}
+/**
+ * Message for a launch that has no bundle to launch. Separate from `planDev`
+ * because only the LAUNCHING caller needs one: a build writing an `--outdir`
+ * legitimately has no single output file, and refusing inside the planner would
+ * fail `--build-only` for a reason that does not apply to it.
+ */
+export function noBundleError(scriptName, app) {
+    const declaration = app === 'gjs' ? '`gjsify.main`' : '`gjsify.example.node`';
+    return new Error(`gjsify dev: nothing to launch — neither \`${scriptName}\` nor --outfile names an output file, ` +
+        `and this package declares no ${declaration}.\n` +
+        `  Pass one:   gjsify dev --outfile dist/index.${app}.mjs\n` +
+        `  or rebuild without launching:   gjsify dev --build-only`);
+}

package/lib/utils/gi-runtime-paths.d.ts

@@ -0,0 +1,27 @@
+import type { GiSystemProbe } from '@gjsify/rolldown-plugin-gjsify';
+/**
+ * The system libdir candidates a `--app gjs` bundle carries — every platform the
+ * table names, not the building host's.
+ *
+ * A build-time platform gate would be exactly the snapshot the note above exists to
+ * avoid: `--app gjs` emits platform-neutral JavaScript, so the bundle a Linux runner
+ * produces is the bundle a Mac runs. What travels instead is the RUNTIME gate, and it
+ * is two markers, not one, because the `girepository-1.0` marker alone answers the
+ * wrong question. It says "a GI stack is installed under this prefix" — true on a
+ * Linux box built with `meson setup --prefix=/usr/local` or jhbuild, a normal shape
+ * for this project's own audience — while the rule this mirrors is about LOADERS:
+ * `systemGiLibraryDirs()` is empty off darwin because `ld.so`'s system-wide cache
+ * already resolves these leaves. Without the host marker every such Linux host would
+ * get `/usr/local/lib` prepended ahead of the distro's typelibs AND libraries, which
+ * is the two-stacks precedence ADR 0023 § 4 / #910 paid for — measured against a
+ * stand-in host in `gi-runtime-paths-banner.spec.ts`.
+ *
+ * A platform in the table with no {@link HOST_MARKERS} entry THROWS rather than
+ * shipping an ungated candidate: an unknown-host default of "prepend" is the bug
+ * above, on every platform at once.
+ *
+ * SORTED and deduplicated: the result is emitted into a bundle two machines must be
+ * able to build byte-for-byte identically, and `Object.entries()` order is the
+ * table's, which is a source-edit away from changing.
+ */
+export declare function giSystemProbes(): GiSystemProbe[];

package/lib/utils/gi-runtime-paths.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MIT
+// WHAT a `--app gjs` bundle's byte-1 GI prologue is told. The prologue itself is
+// `rolldown-plugin-gjsify`'s `giRuntimePathsStub`; this is the only production caller
+// that fills it, and until it did, every bundle carried the empty string that stub
+// returns for nothing-to-say.
+//
+// WHY A BUNDLE NEEDS IT. On macOS a typelib names its library by bare leaf
+// (`libgtk-4.1.dylib`), and SIP strips an inherited `DYLD_*` at the `/bin/sh` exec a
+// launcher goes through, so the only repair that survives is one the process makes to
+// girepository's own search paths from the inside. Measurements, and what this reaches
+// (loads AFTER module evaluation starts, not a static `gi://` import):
+// `status/open-todos.md` § "A globally installed GJS launcher still cannot load a
+// system GTK on macOS".
+//
+// A SHIPPED BUNDLE RUNS ON A MACHINE THE BUILD NEVER SAW, which rules out both
+// tempting sources. `systemGiLibraryDirs()` MEASURES the build host and answers `[]`
+// on the Linux runner that builds most releases — so what travels is the CANDIDATE
+// table it probes, with the probe moved into the bundle. `detectNativePackages()`
+// answers with the build tree's `node_modules/@gjsify/<pkg>-<target>/prebuilds/
+// <target>`: the build host's target twice over (ADR 0017), at the build tree's depth,
+// so it names nothing on an installed macOS host — and baking it would make
+// `dist/affected.gjs.mjs`, a `--app gjs` bundle `scripts/verify-committed-bundles.mjs`
+// compares byte for byte, encode which platform siblings the committing machine had.
+// `activateNativePrebuilds()` already covers those from inside the running process.
+//
+// DELIBERATELY NOT INCLUDED: a `@gjsify/gtk-runtime-<target>` bundle's `gtk/lib`. That
+// is node-gi's mechanism, for a host process that brings no GTK of its own; a `--app
+// gjs` bundle runs under a `gjs` already linked against a system GLib, so a second GTK
+// stack in that process is the two-registries failure #910 paid for (ADR 0023 § 4).
+import { PROBED_GI_LIBDIRS, TYPELIB_SUBDIR } from './system-gi.js';
+/**
+ * A path that proves the RUNNING host is the platform whose candidates it keys, for
+ * every platform `PROBED_GI_LIBDIRS` names.
+ *
+ * The bundle cannot read `process.platform` — it is platform-neutral JavaScript, built
+ * on a machine that is not the host — so the darwin scope `systemGiLibraryDirs()`
+ * enforces with `PROBED_GI_LIBDIRS[platform]` has to travel as a marker path.
+ * Same probe, same spelling as `@gjsify/child_process`'s `detectPlatform()` and
+ * `@gjsify/v8`'s `detectHeapPlatform()`: macOS has no procfs, and this plist is
+ * present on every install.
+ */
+const HOST_MARKERS = {
+    darwin: '/System/Library/CoreServices/SystemVersion.plist',
+};
+/**
+ * The system libdir candidates a `--app gjs` bundle carries — every platform the
+ * table names, not the building host's.
+ *
+ * A build-time platform gate would be exactly the snapshot the note above exists to
+ * avoid: `--app gjs` emits platform-neutral JavaScript, so the bundle a Linux runner
+ * produces is the bundle a Mac runs. What travels instead is the RUNTIME gate, and it
+ * is two markers, not one, because the `girepository-1.0` marker alone answers the
+ * wrong question. It says "a GI stack is installed under this prefix" — true on a
+ * Linux box built with `meson setup --prefix=/usr/local` or jhbuild, a normal shape
+ * for this project's own audience — while the rule this mirrors is about LOADERS:
+ * `systemGiLibraryDirs()` is empty off darwin because `ld.so`'s system-wide cache
+ * already resolves these leaves. Without the host marker every such Linux host would
+ * get `/usr/local/lib` prepended ahead of the distro's typelibs AND libraries, which
+ * is the two-stacks precedence ADR 0023 § 4 / #910 paid for — measured against a
+ * stand-in host in `gi-runtime-paths-banner.spec.ts`.
+ *
+ * A platform in the table with no {@link HOST_MARKERS} entry THROWS rather than
+ * shipping an ungated candidate: an unknown-host default of "prepend" is the bug
+ * above, on every platform at once.
+ *
+ * SORTED and deduplicated: the result is emitted into a bundle two machines must be
+ * able to build byte-for-byte identically, and `Object.entries()` order is the
+ * table's, which is a source-edit away from changing.
+ */
+export function giSystemProbes() {
+    const probes = new Map();
+    for (const [platform, dirs] of Object.entries(PROBED_GI_LIBDIRS)) {
+        const hostMarker = HOST_MARKERS[platform];
+        if (!hostMarker) {
+            throw new Error(`[gjsify] PROBED_GI_LIBDIRS names '${platform}' but HOST_MARKERS does not: ` +
+                'a bundle cannot ask process.platform, so an ungated candidate would be ' +
+                'prepended on every host that happens to have the directory.');
+        }
+        for (const dir of dirs) {
+            probes.set(`${dir}\u0000${hostMarker}`, [dir, `${dir}/${TYPELIB_SUBDIR}`, hostMarker]);
+        }
+    }
+    return [...probes.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, probe]) => probe);
+}

package/lib/utils/gi-typelib.d.ts

@@ -0,0 +1,49 @@
+/** Injectable host facts — every platform branch is testable from any host. */
+export interface GiTypelibOptions {
+    /** `process.platform` value; defaults to the running process. */
+    platform?: string;
+    /** Environment to read `GI_TYPELIB_PATH` / `PATH` from; defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Directory-existence predicate; defaults to a `statSync` probe. */
+    existsDir?: (dir: string) => boolean;
+    /** File-existence predicate; defaults to `existsSync`. */
+    existsFile?: (file: string) => boolean;
+    /** Immediate subdirectory names of `dir`, or `[]`; defaults to a `readdirSync` probe. */
+    listDirs?: (dir: string) => string[];
+    /** `pkg-config`'s `.pc` search directories; defaults to {@link pkgConfigSearchDirs}. */
+    searchDirs?: (env: Record<string, string | undefined>) => string[];
+}
+/**
+ * Directories girepository looks for typelibs in, most specific first,
+ * deduplicated, each verified on disk.
+ *
+ * Sources, in precedence order:
+ *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live.
+ *      Believed on existence alone; an explicit statement is not second-guessed.
+ *   2. `pkg-config`'s `.pc` search path → `<libdir>/girepository-1.0`. The
+ *      general mechanism: it finds a jhbuild or otherwise bespoke prefix that no
+ *      list here could name. Present only when pkg-config is, which on a
+ *      runtime-only host it is not — hence 3.
+ *   3. Platform defaults, each believed only on the marker directory existing.
+ *
+ * Source 3 is where the platforms differ, and each branch is a statement about
+ * that platform's install layout:
+ *   * **linux** — {@link LINUX_LIBDIRS} plus the discovered multiarch triplets.
+ *   * **darwin** — {@link systemGiLibraryDirs}, which already probes Homebrew,
+ *     MacPorts and pkg-config prefixes for exactly this marker. Reused rather
+ *     than re-derived: the two must not be able to disagree about where the GI
+ *     stack is.
+ *   * **win32** — a GTK distribution ships `<prefix>/bin` on `PATH` and its
+ *     typelibs in the sibling `<prefix>/lib/girepository-1.0`, so PATH is the
+ *     prefix oracle. (Untested against a real Windows GTK; it costs a `stat` per
+ *     `bin` entry and cannot make any host worse than the empty list it replaces.)
+ */
+export declare function systemGiTypelibDirs({ platform, env, existsDir, listDirs, searchDirs, }?: GiTypelibOptions): string[];
+/**
+ * The installed `<namespace>-<version>.typelib`, or `null`.
+ *
+ * `version` is GI's API version as it appears in a `gi://` specifier (`4.0` for
+ * `gi://Gtk?version=4.0`, `1` for Adwaita) — the same string the filename
+ * carries, so the caller states it exactly once.
+ */
+export declare function findSystemTypelib(namespace: string, version: string, { existsFile, ...options }?: GiTypelibOptions): string | null;

package/lib/utils/gi-typelib.js

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MIT
+// Is a GObject-Introspection namespace INSTALLED on this host — the question
+// `gi_repository_require()` answers, asked without loading anything.
+//
+// WHY THIS EXISTS. `gjsify system-check` used to answer it with `pkg-config
+// --modversion libadwaita-1`, which is a question about the DEVELOPMENT package.
+// Measured on postmarketOS v26.06 / aarch64 (OnePlus 6T, gjs 1.88.1, no node):
+// libadwaita 1.9.2 installed, `Adw-1.typelib` present, every Adwaita app on the
+// device running — and `system-check` printing `✗ libadwaita` under **Required**
+// and exiting 1, because `libadwaita-dev` (which ships the `.pc` file and
+// nothing a running app loads) was not installed. A check that fails on a host
+// where the thing it checks demonstrably works is worse than no check: it sends
+// people to install packages they do not need, and it teaches them to ignore the
+// output — the same failure mode `checkTypeSkew`'s comment in
+// `check-system-deps.ts` describes from the other direction.
+//
+// THE ORACLE is the typelib FILE on girepository's search path:
+//   * it is what GI itself resolves, so it cannot disagree with what an app does;
+//   * it is identical under GJS and Node, so the CLI's two entry points give the
+//     same answer (`pkg-config` at least had that property; `imports.gi` would
+//     not);
+//   * it needs no `dlopen`, and a presence probe must not have the side effect of
+//     loading GTK into the process asking the question.
+//
+// It answers PRESENCE only. The version still comes from `pkg-config` where that
+// is installed — see `checkGiLibrary` in `check-system-deps.ts`, which reports a
+// version when it can and a bare `✓` when it cannot. Presence without a version
+// is the honest answer on a runtime-only host; `✗` was not.
+//
+// PURE FUNCTION of injected host facts (platform / env / fs / pkg-config), like
+// `systemGiLibraryDirs()` and `resolvePrebuildDirName()` beside it, so the
+// darwin and win32 branches are unit-tested from Linux.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+import { pkgConfigSearchDirs, splitSearchPath, systemGiLibraryDirs, TYPELIB_SUBDIR } from './system-gi.js';
+/**
+ * Library prefixes a Linux GI stack is installed under, before multiarch.
+ * `/usr/lib64` is Fedora/openSUSE, `/usr/lib` everything else, `/usr/local/lib`
+ * a source install. Each is accepted only when it actually holds the marker
+ * directory, so naming one that does not exist costs a `stat` and nothing else.
+ */
+const LINUX_LIBDIRS = ['/usr/lib', '/usr/lib64', '/usr/local/lib'];
+/**
+ * Where a Debian/Ubuntu multiarch layout hides the typelibs
+ * (`/usr/lib/x86_64-linux-gnu/girepository-1.0`). The triplet is DISCOVERED by
+ * listing the parent rather than derived from `process.arch`: the mapping from
+ * Node's arch names to Debian triplets is a table that would need a row per
+ * port, and one `readdir` of `/usr/lib` answers it for every architecture
+ * including the ones nobody has written down.
+ */
+const MULTIARCH_PARENTS = ['/usr/lib'];
+function isDirectory(dir) {
+    try {
+        return statSync(dir).isDirectory();
+    }
+    catch {
+        // ENOENT on an uninstalled prefix, EACCES on a path this process may not
+        // read: not a usable typelib directory either way.
+        return false;
+    }
+}
+function subdirectories(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Directories girepository looks for typelibs in, most specific first,
+ * deduplicated, each verified on disk.
+ *
+ * Sources, in precedence order:
+ *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live.
+ *      Believed on existence alone; an explicit statement is not second-guessed.
+ *   2. `pkg-config`'s `.pc` search path → `<libdir>/girepository-1.0`. The
+ *      general mechanism: it finds a jhbuild or otherwise bespoke prefix that no
+ *      list here could name. Present only when pkg-config is, which on a
+ *      runtime-only host it is not — hence 3.
+ *   3. Platform defaults, each believed only on the marker directory existing.
+ *
+ * Source 3 is where the platforms differ, and each branch is a statement about
+ * that platform's install layout:
+ *   * **linux** — {@link LINUX_LIBDIRS} plus the discovered multiarch triplets.
+ *   * **darwin** — {@link systemGiLibraryDirs}, which already probes Homebrew,
+ *     MacPorts and pkg-config prefixes for exactly this marker. Reused rather
+ *     than re-derived: the two must not be able to disagree about where the GI
+ *     stack is.
+ *   * **win32** — a GTK distribution ships `<prefix>/bin` on `PATH` and its
+ *     typelibs in the sibling `<prefix>/lib/girepository-1.0`, so PATH is the
+ *     prefix oracle. (Untested against a real Windows GTK; it costs a `stat` per
+ *     `bin` entry and cannot make any host worse than the empty list it replaces.)
+ */
+export function systemGiTypelibDirs({ platform = process.platform, env = process.env, existsDir = isDirectory, listDirs = subdirectories, searchDirs = pkgConfigSearchDirs, } = {}) {
+    // POSIX semantics unless the TARGET is win32 — `platform` is a parameter, so
+    // this answers a question about a foreign filesystem from any host. The same
+    // trap `system-gi.ts` documents: a host-following `join` turns
+    // `/usr/lib/girepository-1.0` into a backslash path on Windows and matches
+    // nothing the caller holds.
+    const { join, dirname, basename } = platform === 'win32' ? win32 : posix;
+    const separator = platform === 'win32' ? ';' : ':';
+    const out = [];
+    const add = (dir) => {
+        if (dir && !out.includes(dir))
+            out.push(dir);
+    };
+    // 1. Explicit.
+    for (const dir of splitSearchPath(env['GI_TYPELIB_PATH'], separator)) {
+        if (existsDir(dir))
+            add(dir);
+    }
+    // 2 + 3. Candidate libdirs, believed only on the marker.
+    const libDirs = [];
+    for (const pcDir of searchDirs(env)) {
+        if (basename(pcDir) === 'pkgconfig')
+            libDirs.push(dirname(pcDir));
+    }
+    if (platform === 'linux') {
+        libDirs.push(...LINUX_LIBDIRS);
+        for (const parent of MULTIARCH_PARENTS) {
+            for (const entry of listDirs(parent))
+                libDirs.push(join(parent, entry));
+        }
+    }
+    else if (platform === 'darwin') {
+        libDirs.push(...systemGiLibraryDirs({ platform, env, existsDir, searchDirs }));
+    }
+    else if (platform === 'win32') {
+        for (const pathEntry of splitSearchPath(env['PATH'], separator)) {
+            if (basename(pathEntry).toLowerCase() === 'bin')
+                libDirs.push(join(dirname(pathEntry), 'lib'));
+        }
+    }
+    for (const libDir of libDirs) {
+        const typelibDir = join(libDir, TYPELIB_SUBDIR);
+        if (existsDir(typelibDir))
+            add(typelibDir);
+    }
+    return out;
+}
+/**
+ * The installed `<namespace>-<version>.typelib`, or `null`.
+ *
+ * `version` is GI's API version as it appears in a `gi://` specifier (`4.0` for
+ * `gi://Gtk?version=4.0`, `1` for Adwaita) — the same string the filename
+ * carries, so the caller states it exactly once.
+ */
+export function findSystemTypelib(namespace, version, { existsFile = existsSync, ...options } = {}) {
+    const { join } = options.platform === 'win32' ? win32 : posix;
+    const leaf = `${namespace}-${version}.typelib`;
+    for (const dir of systemGiTypelibDirs(options)) {
+        const candidate = join(dir, leaf);
+        if (existsFile(candidate))
+            return candidate;
+    }
+    return null;
+}

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

@@ -1,9 +1,11 @@
-/** The one bundler-output field this guard needs, from either engine. */
+/** The bundler-output fields this guard needs, from either engine. */
 export interface GuardedChunk {
     /** Emitted chunk name, for the error message. */
     fileName?: string;
     /** External specifiers the chunk STATICALLY imports (rollup/rolldown contract). */
     imports?: readonly string[];
+    /** Emitted source, for the syntax check. Present on a written chunk on both engines. */
+    code?: string;
 }
 /**
  * Bare `node:` specifiers a `--app gjs` bundle may keep as static imports.
@@ -20,5 +22,57 @@ export declare const GJS_ALLOWED_NODE_IMPORTS: readonly string[];
  * allowlist. Sorted, so the error message and any test are stable.
  */
 export declare function findDisallowedNodeImports(chunks: readonly GuardedChunk[], allowed?: readonly string[]): string[];
-/** Throw when a built `--app gjs` bundle statically imports Node builtins. */
-export declare function assertGjsBundleLoadable(chunks: readonly GuardedChunk[], outfile: string): void;
+/**
+ * Is `id` a BARE package specifier — the only shape GJS's ESM loader cannot resolve on
+ * its own?
+ *
+ * Relative and absolute paths name a file; anything carrying a URL scheme names a
+ * loader GJS either has (`gi:`, `file:`, `resource:`) or will report itself. `node:` is
+ * classified BEFORE this, because it has its own message and its own symptom.
+ * A win32 drive path (`C:\…`) matches the scheme test, which is the intended answer.
+ */
+export declare function isBareSpecifier(id: string): boolean;
+/** What the caller must tell the guard about this build's own promises. */
+export interface GjsImportPolicy {
+    /**
+     * The target's own externals predicate — pass
+     * `createGjsExternalsPredicate(userExternal)`, the same one `externalsPlugin`
+     * enforces, so the guard and the build cannot disagree about what was declared.
+     * Omitted, nothing counts as declared.
+     */
+    isExternal?: (id: string) => boolean;
+    /**
+     * Every fileName the build emitted. `chunk.imports` lists sibling CHUNKS by fileName
+     * with no `./` prefix, which is indistinguishable from a bare package specifier — so
+     * the set is excluded by name rather than guessed at by shape.
+     */
+    emitted?: readonly string[];
+}
+/**
+ * The distinct bare specifiers `chunks` statically import that nothing in this build
+ * promised to provide. Sorted, so the error message and any test are stable.
+ */
+export declare function findUnresolvableBareImports(chunks: readonly GuardedChunk[], policy?: GjsImportPolicy): string[];
+/**
+ * Throw when a built `--app gjs` bundle statically imports something GJS cannot
+ * resolve — a bare `node:` builtin, or any other bare specifier this build did not
+ * declare external.
+ *
+ * The two are reported separately because they have different symptoms and different
+ * fixes: a `node:` specifier aborts with "Unsupported URI scheme", any other bare one
+ * with "Module not found", and the first means an alias target failed while the second
+ * means the dependency is simply not there.
+ */
+export declare function assertGjsBundleLoadable(chunks: readonly GuardedChunk[], outfile: string, policy?: GjsImportPolicy): void;
+/**
+ * Throw when a written `--app gjs` chunk is not parseable JavaScript because raw JSX
+ * survived into it. See `@gjsify/rolldown-plugin-gjsify`'s `utils/jsx-survival.ts` for
+ * why the oracle is a parse and not a pattern, and for the measurement.
+ *
+ * Called ONLY when the effective JSX setting PRESERVES JSX, which is the only way it can
+ * reach an artifact: oxc compiles it otherwise. That is not a cost dodge but the precise
+ * condition — though the cost is real, and measured: parsing the repo's largest bundle
+ * (`dist/cli.gjs.mjs`, 6.8 MB) takes ~850 ms, which is not worth paying on every GJS
+ * build to re-answer a question the transform already settled.
+ */
+export declare function assertGjsBundleParses(chunks: readonly GuardedChunk[], label: string): void;