@gjsify/rolldown-plugin-gjsify 0.40.0 → 0.42.0

package/lib/app/gjs.d.ts

@@ -1,5 +1,6 @@
 import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
 import type { PluginOptions } from '../types/plugin-options.js';
+import type { GiSystemProbe } from '../plugins/gi-runtime-paths.js';
 /** Resolved Rolldown configuration template + plugins for `--app gjs`. */
 export interface GjsBuildConfig {
     options: RolldownOptions;
@@ -26,6 +27,13 @@ export interface GjsFactoryInput {
      *   `"…"`   → custom line, supports `${env:NAME[:-default]}` placeholders
      */
     shebang?: boolean | string;
+    /**
+     * System GI library dirs the byte-1 prologue tries at RUNTIME — see `GiSystemProbe`.
+     * The only half a build can honestly fill: the build machine is not the host that
+     * runs the bundle, so what travels is a candidate plus the markers that decide it
+     * there. See `GjsifyPluginInput.giSystemProbes` for why the relative half is absent.
+     */
+    giSystemProbes?: readonly GiSystemProbe[];
     /** Plugin options forwarded to sub-plugins (deepkit, css, …). */
     pluginOptions: PluginOptions;
 }

package/lib/app/gjs.js

@@ -191,7 +191,11 @@ export const setupForGjs = async (input) => {
         // into the subset GTK4 understands.
         cssAsStringPlugin({ targets: { firefox: 60 << 16 } }),
         nodeModulesPathRewritePlugin({ bundleDir, runtimeResolve: format === 'esm' }),
-        processStubPlugin({ userBanner: input.userBanner, captureBundleUrl: format === 'esm' }),
+        processStubPlugin({
+            userBanner: input.userBanner,
+            captureBundleUrl: format === 'esm',
+            giSystemProbes: input.giSystemProbes,
+        }),
         // resolveShebangLine returns null when disabled, else the resolved line
         // with `${env:…}` expanded.
         (() => {
@@ -205,7 +209,14 @@ export const setupForGjs = async (input) => {
         // Unsupported URI scheme for importing: node`) — the same failure
         // `utils/gjs-bundle-guard.ts` catches at emit time, caught here at its
         // source with the importer and cause named.
-        unresolvedWorkspaceImportPlugin({ target: 'gjs', aliases: aliasEntries, isExternal: external }),
+        unresolvedWorkspaceImportPlugin({
+            target: 'gjs',
+            aliases: aliasEntries,
+            isExternal: external,
+            ...(input.pluginOptions.toolchainAnchor !== undefined
+                ? { toolchainAnchor: input.pluginOptions.toolchainAnchor }
+                : {}),
+        }),
     ];
     return { options, plugins };
 };

package/lib/app/nativescript.js

@@ -21,13 +21,11 @@
 // slot routing would only change 4 of its 122 entries and all four are
 // regressions — `fs`/`fs/promises` (+ their `node:` forms) deliberately point
 // at `@gjsify/native-fs-bridge`, which declares `nativescript: "native"` in the
-// "this package IS the native implementation" sense and therefore routes to a
-// `globals.mjs` it does not ship → `@gjsify/empty`. The slot vocabulary's
-// `native` means "the RUNTIME provides this, use its value", so the bridge
-// packages are mis-declared; that is tracked in status/open-todos.md and must be settled
-// before this table is composed. A direct `import … from
-// '@gjsify/native-fs-bridge'` already hits the derived map (plain key hit) and
-// is emptied TODAY — same root cause, listed in the same TODO.
+// "this package IS the native implementation" sense and therefore promises a
+// `globals.mjs` it does not ship. The slot vocabulary's `native` means "the
+// RUNTIME provides this, use its value", so the bridge packages are
+// mis-declared; that is tracked in status/open-todos.md and must be settled
+// before this table is composed.
 //
 // Derived `@gjsify/<X>` entries are merged into the map below, so an import by
 // PACKAGE NAME still routes per its declared slot in a single hop.
@@ -41,9 +39,14 @@ import { globToEntryPoints } from '../utils/entry-points.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
 import { platformResolvePlugin, detectNativescriptPlatform, nativescriptPlatformDefines, } from '../plugins/platform-resolve.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
+// Never bundled: an app works only with the ONE core instance the runtime boots, and what
+// this target emits is an ENTRY the NS bundler resolves it for. An optional peer absent from
+// the workspace install, it was not resolvable either — every UI-widget bridge failed to build.
+const NATIVESCRIPT_CORE = /^@nativescript\/core(?:\/|$)/;
 export const setupForNativescript = async (input) => {
     const userExternal = input.userExternal ?? [];
-    const external = [...userExternal];
+    const external = [...userExternal, NATIVESCRIPT_CORE];
+    const isExternal = (id) => external.some((entry) => (typeof entry === 'string' ? entry === id : entry.test(id)));
     const exclude = input.pluginOptions.exclude ?? [];
     const entryPoints = await globToEntryPoints(input.input, exclude);
     // Target platform — discovered from the env NS' CLI sets when it spawns a
@@ -141,7 +144,7 @@ export const setupForNativescript = async (input) => {
         unresolvedWorkspaceImportPlugin({
             target: 'nativescript',
             aliases: aliasEntries,
-            isExternal: (id) => external.includes(id),
+            isExternal,
         }),
     ];
     return { options, plugins };

package/lib/index.d.ts

@@ -2,10 +2,11 @@ export * from './types/index.js';
 export * from './utils/index.js';
 export * from './app/index.js';
 export * from './library/index.js';
-export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteContents, shouldRewrite, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
+export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteContents, shouldRewrite, shouldInline, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
 export type { NodeModulesPathRewriteOptions, RewriteResult } from './plugins/rewrite-node-modules-paths.js';
 export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
 export { giRuntimePathsStub } from './plugins/gi-runtime-paths.js';
+export type { GiSystemProbe } from './plugins/gi-runtime-paths.js';
 export type { ProcessStubPluginOptions } from './plugins/process-stub.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';
 export { textLoaderPlugin } from './plugins/text-loader.js';

package/lib/index.js

@@ -3,7 +3,7 @@ export * from './types/index.js';
 export * from './utils/index.js';
 export * from './app/index.js';
 export * from './library/index.js';
-export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteContents, shouldRewrite, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
+export { REWRITE_FILTER, extractPackageSpec, getBundleDirFromOutput, rewriteContents, shouldRewrite, shouldInline, nodeModulesPathRewritePlugin, } from './plugins/rewrite-node-modules-paths.js';
 export { processStubPlugin, GJS_PROCESS_STUB, composeBanner } from './plugins/process-stub.js';
 export { giRuntimePathsStub } from './plugins/gi-runtime-paths.js';
 export { cssAsStringPlugin } from './plugins/css-as-string.js';

package/lib/plugin.d.ts

@@ -1,5 +1,6 @@
 import type { RolldownOptions, RolldownPluginOption } from 'rolldown';
 import type { PluginOptions } from './types/plugin-options.js';
+import type { GiSystemProbe } from './plugins/gi-runtime-paths.js';
 export interface GjsifyConfig {
     options: RolldownOptions;
     plugins: RolldownPluginOption[];
@@ -20,6 +21,15 @@ export interface GjsifyPluginInput {
      *   `"…"`   → custom line, supports `${env:NAME[:-default]}` placeholders
      */
     shebang?: boolean | string;
+    /**
+     * `--app gjs` only: system GI library dirs the byte-1 prologue probes on the RUNNING
+     * host. The bundle-relative half of that prologue is deliberately NOT plumbed here —
+     * `processStubPlugin`'s `giRuntimePaths` still takes it, but nothing in this repo can
+     * fill it with a path that is true on the machine a shipped bundle runs on
+     * (`packages/infra/cli/src/utils/gi-runtime-paths.ts` records what was measured), and
+     * an option no caller fills is the defect this wiring was added to remove.
+     */
+    giSystemProbes?: readonly GiSystemProbe[];
 }
 /**
  * Build the Rolldown configuration template + plugin array for the given

package/lib/plugin.js

@@ -42,6 +42,7 @@ export const gjsifyPlugin = async (input, pluginOptions = {}) => {
                 userBanner: input.userBanner,
                 userAliases: input.userAliases,
                 shebang: input.shebang,
+                giSystemProbes: input.giSystemProbes,
                 pluginOptions,
             });
         case 'node':

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

@@ -1,10 +1,32 @@
 /**
- * The byte-1 prologue that prepends `dirs` to the default repository's typelib
- * search path and library path. Empty list → `''`: a no-op prologue in every
- * bundle is a guard that can never fire, and a banner that is not there cannot
- * drift.
+ * An absolute candidate library dir, the path that proves it IS one, and the path
+ * that proves the running host is the PLATFORM the candidate belongs to.
+ *
+ * Both gates, because they answer different questions and only one of them travels
+ * well. `/usr/local/lib` holding a `girepository-1.0/` says "a GI stack is installed
+ * here"; it does NOT say "this host's loader needs help finding it" — on Linux
+ * `ld.so`'s system-wide cache already resolves those leaves, and a `meson setup
+ * --prefix=/usr/local` or jhbuild tree is a normal shape there. Prepending it anyway
+ * puts a second GI stack ahead of the distro's for every bundle on that host, which
+ * is the two-registries failure ADR 0023 § 4 / #910 describe. The bundle cannot ask
+ * `process.platform` (it is platform-neutral JavaScript built on a machine that is
+ * not the host), so the platform scope travels as a marker path too.
+ */
+export type GiSystemProbe = readonly [libDir: string, marker: string, hostMarker: string];
+/**
+ * The byte-1 prologue that prepends directories to the default repository's typelib
+ * search path and library path. Nothing to prepend → `''`: a no-op prologue in every
+ * bundle is a guard that can never fire, and a banner that is not there cannot drift.
+ *
+ * Prepending REVERSES a list, so both loops count down and the emitted order is the
+ * order given. `systemProbes` are applied first and therefore end up BEHIND `dirs`:
+ * ADR 0023's bundle-before-system precedence, which #910 paid for.
  *
  * @param dirs directories RELATIVE to the program's own directory, `/`-separated —
  *   an absolute path baked at build time is the BUILD machine's
+ * @param systemProbes absolute directories prepended only where BOTH of a probe's
+ *   marker paths exist on the RUNNING host; the markers are passed in so the
+ *   `girepository-1.0` layout rule and the platform scope around it keep their single
+ *   definition in the caller
  */
-export declare function giRuntimePathsStub(dirs: readonly string[]): string;
+export declare function giRuntimePathsStub(dirs: readonly string[], systemProbes?: readonly GiSystemProbe[]): string;

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

@@ -1,37 +1,84 @@
-// Tell GI where a bundle's own typelibs and their backing libraries are — from
-// INSIDE the process, so a `--app gjs` bundle needs no launcher and no environment.
-// Why it exists, what it does NOT cover (a dylib reached through another dylib's
-// link closure never passes through GI, so only `@rpath`/`$ORIGIN` reaches it) and
-// the macOS measurements behind it: `status/open-todos.md` § "A globally installed
-// GJS launcher still cannot load a system GTK on macOS", ADR 0023 § 4.
+// SPDX-License-Identifier: MIT
+// The GI runtime search-path prologue for `--app gjs` bundles: the only repair shape
+// that survives macOS (a typelib names its library by bare leaf, and the link closure
+// never passes through GI, so only `@rpath`/`$ORIGIN` reaches it). Measurements:
+// `status/open-todos.md` § "A globally installed GJS launcher still cannot load a
+// system GTK on macOS", ADR 0023 § 4.
+//
+// WHAT IT REACHES, MEASURED (gjs 1.88.1, linux; pinned by the `gi-runtime-prologue`
+// e2e): a banner is the entry chunk's BODY and ESM evaluates imports first, so a
+// STATIC `import … from 'gi://Ns'` has already loaded its typelib before this runs.
+// What is left is what loads LATER — `await import('gi://Soup')` and the other
+// optional namespaces. Reaching the static ones changes how a bundle acquires GI
+// namespaces at all; that is an ADR, filed in the same entry.
+//
+// TWO KINDS OF DIRECTORY, split by WHOSE FACT each is. `dirs` describe the SHIPPED
+// TREE, so they are baked, relative to the program. `systemProbes` describe the host
+// that will RUN it, which the build machine cannot know — so the candidate travels
+// and is dropped on the host when it names nothing.
 /**
- * The byte-1 prologue that prepends `dirs` to the default repository's typelib
- * search path and library path. Empty list → `''`: a no-op prologue in every
- * bundle is a guard that can never fire, and a banner that is not there cannot
- * drift.
+ * The byte-1 prologue that prepends directories to the default repository's typelib
+ * search path and library path. Nothing to prepend → `''`: a no-op prologue in every
+ * bundle is a guard that can never fire, and a banner that is not there cannot drift.
+ *
+ * Prepending REVERSES a list, so both loops count down and the emitted order is the
+ * order given. `systemProbes` are applied first and therefore end up BEHIND `dirs`:
+ * ADR 0023's bundle-before-system precedence, which #910 paid for.
  *
  * @param dirs directories RELATIVE to the program's own directory, `/`-separated —
  *   an absolute path baked at build time is the BUILD machine's
+ * @param systemProbes absolute directories prepended only where BOTH of a probe's
+ *   marker paths exist on the RUNNING host; the markers are passed in so the
+ *   `girepository-1.0` layout rule and the platform scope around it keep their single
+ *   definition in the caller
  */
-export function giRuntimePathsStub(dirs) {
-    if (dirs.length === 0)
+export function giRuntimePathsStub(dirs, systemProbes = []) {
+    if (dirs.length === 0 && systemProbes.length === 0)
         return '';
     const list = dirs.map((d) => JSON.stringify(d)).join(',');
+    const probes = systemProbes.map((probe) => `[${probe.map((v) => JSON.stringify(v)).join(',')}]`).join(',');
     // Four rules, each pinned with its incident by `gi-runtime-paths-banner.spec.ts`:
-    // every ambient global through `globalThis.` (a bare `imports` at byte 1 binds to
-    // a bundled module's own top-level `const imports`, still in its TDZ); guarded
-    // probes, not try/catch (no call here has a throw path, so a catch would hide a
-    // real absence); one line (the banner precedes source-map-aware machinery); both
-    // prepends (search path alone finds the typelib, then fails the dlopen).
-    return (`(function(){var i=globalThis.imports;if(!i||!i.gi||!i.system)return;` +
-        `var R=i.gi.GIRepository;if(!R||!R.Repository||!R.Repository.dup_default)return;` +
+    // every ambient global through `globalThis.` (a bare `imports` at byte 1 binds to a
+    // bundled module's own top-level `const imports`, still in its TDZ); capability
+    // guards rather than try/catch for every CALL, since none has a throw path in the
+    // GIR; one line (the banner precedes source-map-aware machinery); both prepends
+    // (search path alone finds the typelib, then fails the dlopen).
+    //
+    // The ONE try wraps a namespace LOAD, the only operation here that does throw:
+    // distributions ship the GIRepository typelib separately from the girepository
+    // library GJS links against (Debian's `gir1.2-girepository-3.0` vs
+    // `libgirepository-2.0-0`), so a host with only the second raises "Typelib file
+    // for namespace 'GIRepository' (any version) not found" — measured, and why
+    // `activateNativePrebuilds()` wraps the same access. At byte 1 that throw takes
+    // down a program that ran fine while this prologue was the empty string. Not
+    // logged, for that function's reason: every outcome leaves the caller where it
+    // was before the prologue existed, so no host is made worse.
+    const head = `(function(){var i=globalThis.imports;if(!i||!i.gi)return;` +
+        `var R;try{R=i.gi.GIRepository}catch(e){return}` +
+        `if(!R||!R.Repository||!R.Repository.dup_default)return;` +
         `var r=R.Repository.dup_default();if(!r||!r.prepend_search_path||!r.prepend_library_path)return;` +
-        `var p=i.system.programPath||i.system.programInvocationName||'';` +
-        // Both separators: the program path is the HOST's, and on win32 a `/`-only
-        // cut matches nothing (same rule as `lastPathSeparatorIndex`, #1143).
-        `var m=/^(.*)[\\/\\\\][^\\/\\\\]*$/.exec(p);if(!m)return;` +
-        // Absolute stays absolute: joining a system libdir under the program dir names nothing.
-        `var b=m[1];for(var d of [${list}]){var f=/^([A-Za-z]:[\\/\\\\]|[\\/\\\\])/.test(d)?d:b+'/'+d;` +
-        `r.prepend_search_path(f);r.prepend_library_path(f)}` +
-        `})();`);
+        `var a=function(f){r.prepend_search_path(f);r.prepend_library_path(f)};`;
+    // GLib gets its own try for the same reason, separate so a host that cannot
+    // introspect it still gets the relative half.
+    //
+    // The HOST marker is tested first and short-circuits: on a host the candidate does
+    // not belong to, the whole table costs one `stat` per entry and changes nothing.
+    const probeHalf = probes.length === 0
+        ? ''
+        : `var G;try{G=i.gi.GLib}catch(e){}` +
+            `if(G&&G.file_test&&G.FileTest){var S=[${probes}];` +
+            `for(var j=S.length;j--;)` +
+            `if(G.file_test(S[j][2],G.FileTest.EXISTS)&&G.file_test(S[j][1],G.FileTest.IS_DIR))a(S[j][0])}`;
+    // Guards rather than returns, so a program path with no separator (`gjs -c`) still
+    // leaves the system half applied.
+    const relativeHalf = list.length === 0
+        ? ''
+        : `var p=(i.system&&(i.system.programPath||i.system.programInvocationName))||'';` +
+            // Both separators: the program path is the HOST's, and on win32 a `/`-only
+            // cut matches nothing (same rule as `lastPathSeparatorIndex`, #1143).
+            `var m=/^(.*)[\\/\\\\][^\\/\\\\]*$/.exec(p);if(m){var b=m[1];var D=[${list}];` +
+            `for(var k=D.length;k--;){var d=D[k];` +
+            // Absolute stays absolute: joining a system libdir under the program dir names nothing.
+            `var q=/^([A-Za-z]:[\\/\\\\]|[\\/\\\\])/.test(d)?d:b+'/'+d;a(q)}}`;
+    return `${head}${probeHalf}${relativeHalf}})();`;
 }

package/lib/plugins/process-stub.d.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from 'rolldown';
+import { type GiSystemProbe } from './gi-runtime-paths.js';
 export declare const GJS_PROCESS_STUB: string;
 /**
  * Compose the GJS process stub with the user-supplied banner so the result is
@@ -23,6 +24,12 @@ export interface ProcessStubPluginOptions {
      * Empty or unset emits nothing.
      */
     giRuntimePaths?: readonly string[];
+    /**
+     * Absolute system GI library directories, each paired with the path that proves the
+     * host really has one. Prepended BEHIND {@link giRuntimePaths} and only where the
+     * marker exists at RUNTIME. Empty or unset emits nothing.
+     */
+    giSystemProbes?: readonly GiSystemProbe[];
 }
 /** Inject the byte-1 banner as a chunk banner, after any user `output.banner`. */
 export declare function processStubPlugin(options?: ProcessStubPluginOptions): Plugin;

package/lib/plugins/process-stub.js

@@ -85,7 +85,7 @@ export function processStubPlugin(options = {}) {
     const stub = (options.captureBundleUrl ? BUNDLE_URL_BANNER : '') +
         GJS_WELLKNOWN_SYMBOLS_STUB +
         GJS_PROCESS_STUB +
-        giRuntimePathsStub(options.giRuntimePaths ?? []);
+        giRuntimePathsStub(options.giRuntimePaths ?? [], options.giSystemProbes ?? []);
     const banner = composeBanner(stub, options.userBanner ?? '');
     return {
         name: 'gjsify-process-stub',

package/lib/plugins/rewrite-node-modules-paths.d.ts

@@ -2,6 +2,36 @@ import type { Plugin } from 'rolldown';
 export declare const REWRITE_FILTER: RegExp;
 /** True when the rewriter wants to look at this path — node_modules + supported ext. */
 export declare function shouldRewrite(path: string): boolean;
+/**
+ * True when the static-read INLINER wants to look at this path — any supported
+ * source, first-party included.
+ *
+ * Deliberately wider than {@link shouldRewrite}, because the two answer different
+ * questions. The inliner asks *is this read resolvable at build time*, which is a
+ * property of the expression and can be true in any file. The rewriter asks *does
+ * this file's `import.meta.url` still mean anything once bundled*, which is only
+ * worth asking of a file whose original location was `node_modules` — the whole
+ * subject of this plugin.
+ *
+ * They were ONE gate until 2026-08-22, and the cost was silent. Each of
+ * `@gjsify/cli`'s own six `readFileSync(new URL(<literal>, import.meta.url))`
+ * template loaders shipped into `dist/cli.gjs.mjs` as a LIVE read pointing at a
+ * `templates/` directory that exists neither in the repo (the sources are in
+ * `src/templates/`; the build copies them to `lib/templates/`) nor in the
+ * published tarball (`files` ships `lib`, not a root `templates`). Measured on a
+ * fresh build: `gjs -m dist/cli.gjs.mjs ship --stage` died with
+ * `ENOENT … packages/infra/cli/templates/app/desktop.tmpl` while the identical
+ * command through `lib/index.js` staged the desktop entry. Two of those six files
+ * carry a comment asserting the inliner handles them, so reading the code
+ * confirmed the belief rather than the behaviour.
+ *
+ * Consequence for a CONSUMER's build, stated because it is a behaviour change: a
+ * statically resolvable read in their own source is baked into their bundle too.
+ * That is the promise the inliner exists to make — a bundle that survives leaving
+ * its build site — and a read meant to stay dynamic keeps working by not being
+ * statically resolvable, since anything the evaluator cannot fold is left alone.
+ */
+export declare function shouldInline(path: string): boolean;
 /** The directory the bundle's outfile lives in, from `output.file` or `output.dir`. */
 export declare function getBundleDirFromOutput(opts: {
     file?: string;
@@ -48,5 +78,10 @@ export interface NodeModulesPathRewriteOptions {
 /**
  * Build a Rolldown plugin that runs the path rewriter as a `transform(code, id)`
  * hook with `order: 'post'`.
+ *
+ * Two scopes in one transform, not two plugins: a second transform would parse
+ * every module a second time, and the inliner's own fast path (skip unless the
+ * source mentions `readFileSync`/`readdirSync`/`existsSync`) already makes the
+ * wider scope nearly free. See {@link shouldInline} for why the scopes differ.
  */
 export declare function nodeModulesPathRewritePlugin(options: NodeModulesPathRewriteOptions): Plugin;

package/lib/plugins/rewrite-node-modules-paths.js

@@ -18,6 +18,12 @@
 //
 // Hosted as a `transform(code, id)` hook with `order: 'post'`: after the
 // deepkit/blueprint/css pre-transforms, still during module loading, before chunking.
+//
+// TWO SCOPES, one transform. The four cases above are node_modules-only, because
+// they are about a file whose recorded location stopped being true. The static-read
+// INLINER that runs alongside them is not: it folds build-time-resolvable reads in
+// ANY source, first-party included, and it was trapped inside the node_modules gate
+// until 2026-08-22 — see `shouldInline` for the incident that measured the cost.
 import { createRequire } from 'node:module';
 import { dirname, join, relative, resolve } from 'node:path';
 import { inlineStaticReads } from '../utils/inline-static-reads.js';
@@ -39,6 +45,40 @@ export function shouldRewrite(path) {
         return false;
     return true;
 }
+/**
+ * True when the static-read INLINER wants to look at this path — any supported
+ * source, first-party included.
+ *
+ * Deliberately wider than {@link shouldRewrite}, because the two answer different
+ * questions. The inliner asks *is this read resolvable at build time*, which is a
+ * property of the expression and can be true in any file. The rewriter asks *does
+ * this file's `import.meta.url` still mean anything once bundled*, which is only
+ * worth asking of a file whose original location was `node_modules` — the whole
+ * subject of this plugin.
+ *
+ * They were ONE gate until 2026-08-22, and the cost was silent. Each of
+ * `@gjsify/cli`'s own six `readFileSync(new URL(<literal>, import.meta.url))`
+ * template loaders shipped into `dist/cli.gjs.mjs` as a LIVE read pointing at a
+ * `templates/` directory that exists neither in the repo (the sources are in
+ * `src/templates/`; the build copies them to `lib/templates/`) nor in the
+ * published tarball (`files` ships `lib`, not a root `templates`). Measured on a
+ * fresh build: `gjs -m dist/cli.gjs.mjs ship --stage` died with
+ * `ENOENT … packages/infra/cli/templates/app/desktop.tmpl` while the identical
+ * command through `lib/index.js` staged the desktop entry. Two of those six files
+ * carry a comment asserting the inliner handles them, so reading the code
+ * confirmed the belief rather than the behaviour.
+ *
+ * Consequence for a CONSUMER's build, stated because it is a behaviour change: a
+ * statically resolvable read in their own source is baked into their bundle too.
+ * That is the promise the inliner exists to make — a bundle that survives leaving
+ * its build site — and a read meant to stay dynamic keeps working by not being
+ * statically resolvable, since anything the evaluator cannot fold is left alone.
+ */
+export function shouldInline(path) {
+    if (!REWRITE_FILTER.test(path))
+        return false;
+    return !GJSIFY_SHIM_RE.test(path);
+}
 /** The directory the bundle's outfile lives in, from `output.file` or `output.dir`. */
 export function getBundleDirFromOutput(opts) {
     const outFile = opts.file ?? join(opts.dir ?? '.', 'bundle.mjs');
@@ -265,6 +305,11 @@ export function rewriteContents(args, srcInput, bundleDir, runtimeResolve) {
 /**
  * Build a Rolldown plugin that runs the path rewriter as a `transform(code, id)`
  * hook with `order: 'post'`.
+ *
+ * Two scopes in one transform, not two plugins: a second transform would parse
+ * every module a second time, and the inliner's own fast path (skip unless the
+ * source mentions `readFileSync`/`readdirSync`/`existsSync`) already makes the
+ * wider scope nearly free. See {@link shouldInline} for why the scopes differ.
  */
 export function nodeModulesPathRewritePlugin(options) {
     const runtimeResolve = options.runtimeResolve ?? false;
@@ -274,12 +319,19 @@ export function nodeModulesPathRewritePlugin(options) {
             order: 'post',
             filter: { id: REWRITE_FILTER },
             handler(code, id) {
-                if (!id.includes('node_modules'))
-                    return null;
-                const result = rewriteContents({ path: id }, code, options.bundleDir, runtimeResolve);
-                if (!result)
+                if (id.includes('node_modules')) {
+                    const result = rewriteContents({ path: id }, code, options.bundleDir, runtimeResolve);
+                    if (!result)
+                        return null;
+                    return { code: result.code, map: null };
+                }
+                // First-party source: inline statically resolvable reads, and
+                // nothing else. `import.meta.url` here is not rewritten — that
+                // is the node_modules question this plugin was written for.
+                if (!shouldInline(id))
                     return null;
-                return { code: result.code, map: null };
+                const inlined = inlineStaticReads(code, id);
+                return inlined.inlined > 0 ? { code: inlined.contents, map: null } : null;
             },
         },
     };

package/lib/plugins/unresolved-workspace-import.d.ts

@@ -16,6 +16,43 @@ export interface WorkspaceImportGuardOptions {
      * (plus exact-name membership) so the two cannot drift.
      */
     isExternal?: (id: string) => boolean;
+    /**
+     * Last-resort anchor for a `@gjsify/*` the PROJECT cannot resolve — set only
+     * when the thing being bundled is TOOLCHAIN rather than user code, and unset
+     * for every ordinary `gjsify build`.
+     *
+     * A repo build script (`node scripts/x.mjs`, re-entered as `gjsify run
+     * --node-script` on a Node-less host) does not need the WORKSPACE's copy of
+     * `@gjsify/fs` — it needs a working one. Anchored at the script, resolution
+     * finds the workspace symlink, whose `lib/esm` a cold clone has not built
+     * yet; anchored additionally at the running CLI, it finds the copy installed
+     * beside it, which is built by construction.
+     *
+     * Measured on postmarketOS/aarch64 (gjs 1.88.1, no node): without this the
+     * ADR 0002 bootstrap fails at its third step, because `--globals auto` pulls
+     * the whole `@gjsify/<pkg>/register` closure into a one-line script (the
+     * count and the incident are in this package's AGENTS.md § toolchainAnchor).
+     * The alternative is building most of the polyfill tree before the first
+     * script runs, on every host including the ones that never bundle one.
+     *
+     * The value is a FILE PATH inside the running CLI's own install, used as the
+     * IMPORTER of the fallback resolve — not a second resolver. That matters:
+     * `--app gjs` deliberately omits both `import` and `require` from
+     * `conditionNames` (`app/gjs.ts`), and a `createRequire().resolve()` here
+     * would resolve under `require` and hand a `cjs-compat.cjs` shim to a GJS
+     * bundle for the ~3 `@gjsify/*` packages that declare a `require` branch.
+     * Going back through `this.resolve` uses the target's own condition set by
+     * construction, so the rescue can only pick the entry the build would have
+     * picked. The precedent is `commands/tsc.ts`, which resolves
+     * `@gjsify/tsc/bundle` from the project first and the running CLI second for
+     * exactly this reason; `tests/e2e/node-free-bootstrap` states that invariant.
+     *
+     * PROJECT FIRST, ALWAYS: consulted only after normal resolution returns
+     * null, so a workspace that HAS the package keeps using it and nothing about
+     * a warm tree changes. A project resolve that ERRORED is not a null and is
+     * never rescued — see the handler.
+     */
+    toolchainAnchor?: string;
 }
 /**
  * Is `id` a bare `@gjsify/*` package specifier (root or subpath)? Excludes disk
@@ -62,11 +99,16 @@ export interface UnresolvedWorkspaceImportDetails {
      */
     aliasedFrom?: readonly string[];
     importer: string;
+    /**
+     * Set when `this.resolve` THREW instead of answering — the message then names
+     * it rather than listing three causes that cannot apply.
+     */
+    resolverFailure?: string;
 }
 /** A `@gjsify/*` edge the build promised to substitute could not be resolved. */
 export declare class UnresolvedWorkspaceImportError extends Error {
     readonly details: UnresolvedWorkspaceImportDetails;
-    constructor(details: UnresolvedWorkspaceImportDetails);
+    constructor(details: UnresolvedWorkspaceImportDetails, cause?: unknown);
 }
 /**
  * The actionable message: names the specifier, the importer and the likely cause —
@@ -82,6 +124,10 @@ export declare function buildReverseAliasIndex(aliases: Record<string, string> |
  * imports-empty/externals at normal) gets first refusal — only ids NOTHING claimed
  * reach this hook. It then re-runs the resolution Rolldown would have run next
  * (`this.resolve(…, { skipSelf })`) and returns that, so a healthy build resolves
- * each specifier exactly once and behaves identically. Only a genuine `null` throws.
+ * each specifier exactly once and behaves identically.
+ *
+ * A genuine `null` throws — unless `toolchainAnchor` is set and the CLI's own install
+ * has it. A THROW is not a `null`: it is rethrown with this plugin's context and the
+ * original as `cause`, never rescued and never reported as a missing dependency.
  */
 export declare function unresolvedWorkspaceImportPlugin(options: WorkspaceImportGuardOptions): Plugin;

package/lib/plugins/unresolved-workspace-import.js

@@ -72,8 +72,8 @@ export function classifyImport(input) {
 /** A `@gjsify/*` edge the build promised to substitute could not be resolved. */
 export class UnresolvedWorkspaceImportError extends Error {
     details;
-    constructor(details) {
-        super(formatUnresolvedWorkspaceImport(details));
+    constructor(details, cause) {
+        super(formatUnresolvedWorkspaceImport(details), cause === undefined ? undefined : { cause });
         this.name = 'UnresolvedWorkspaceImportError';
         this.details = details;
     }
@@ -83,7 +83,7 @@ export class UnresolvedWorkspaceImportError extends Error {
  * the three things `UNRESOLVED_IMPORT` and the post-hoc `node:` guard cannot.
  */
 export function formatUnresolvedWorkspaceImport(details) {
-    const { target, source, candidate, aliasTarget, aliasedFrom, importer } = details;
+    const { target, source, candidate, aliasTarget, aliasedFrom, importer, resolverFailure } = details;
     // The specifiers `candidate` stood in for: `source` when IT carried the table
     // entry, else the reverse lookup — but only when its fan-in is SMALL. A shared
     // sink inverts to a wall of text (`@gjsify/empty` is the browser target for 49
@@ -114,11 +114,18 @@ export function formatUnresolvedWorkspaceImport(details) {
             `\`--app ${target}\` runtime cannot resolve.`
         : `Leaving it unresolved would silently externalise the ORIGINAL ${substitutedFor.length === 1 ? 'specifier' : 'specifiers'} ${quoted} into the ` +
             `bundle, defeating the substitution the \`--app ${target}\` target exists to perform.`) + symptom;
+    // A resolver that FAILED is not a resolver that found nothing, and the three
+    // likely causes below are all wrong for it: an EACCES on `node_modules`, a
+    // corrupt `package.json`, or a deliberate throw from another `resolveId` hook
+    // (`napi-node-addon`'s `resolveAddonPath`) would otherwise be reported as the
+    // user's missing dependency, with the real error gone from the process.
+    const failure = resolverFailure === undefined ? [] : ['', `The project resolver failed with: ${resolverFailure}`];
     return [
         headline,
         `  imported by: ${importer}`,
         '',
         consequence,
+        ...failure,
         '',
         'Likely causes:',
         '  - `node_modules` is missing or incomplete — run `gjsify install` (`--immutable` in CI).',
@@ -143,6 +150,10 @@ export function buildReverseAliasIndex(aliases) {
         list.sort();
     return index;
 }
+/** One line for the message; the untouched error rides along as `cause`. */
+function describeResolverFailure(err) {
+    return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+}
 /**
  * Refuse a build whose `@gjsify/*` substitution could not be resolved.
  *
@@ -150,10 +161,14 @@ export function buildReverseAliasIndex(aliases) {
  * imports-empty/externals at normal) gets first refusal — only ids NOTHING claimed
  * reach this hook. It then re-runs the resolution Rolldown would have run next
  * (`this.resolve(…, { skipSelf })`) and returns that, so a healthy build resolves
- * each specifier exactly once and behaves identically. Only a genuine `null` throws.
+ * each specifier exactly once and behaves identically.
+ *
+ * A genuine `null` throws — unless `toolchainAnchor` is set and the CLI's own install
+ * has it. A THROW is not a `null`: it is rethrown with this plugin's context and the
+ * original as `cause`, never rescued and never reported as a missing dependency.
  */
 export function unresolvedWorkspaceImportPlugin(options) {
-    const { target, aliases, isExternal } = options;
+    const { target, aliases, isExternal, toolchainAnchor } = options;
     // Re-entrancy belt: `skipSelf: true` should keep our own `this.resolve` out of
     // this hook, but a hang is a far worse failure than a missed check. Keyed by
     // `candidate\0importer` — the same package legitimately resolves from many.
@@ -185,6 +200,12 @@ export function unresolvedWorkspaceImportPlugin(options) {
                 const importer = typeof rawImporter === 'string' ? rawImporter : undefined;
                 if (extraOptions?.isEntry)
                     return null;
+                // The toolchain fallback below re-enters this hook with the anchor as
+                // the importer. Declining there keeps the probe from rescuing itself:
+                // the anchor cannot answer for the anchor, and the recursion has no
+                // bound of its own.
+                if (toolchainAnchor !== undefined && importer === toolchainAnchor)
+                    return null;
                 const verdict = classifyImport({ source, importer, aliases, isExternal });
                 if (verdict.verdict === 'ignore')
                     return null;
@@ -198,13 +219,29 @@ export function unresolvedWorkspaceImportPlugin(options) {
                 if (inFlight.has(key))
                     return null;
                 inFlight.add(key);
-                let resolved;
+                let resolved = null;
+                // KEPT DELIBERATELY, and NOT as a miss. `this.resolve` re-runs the whole
+                // `pre`-order chain, so it can fail two very different ways. "Nothing is
+                // there" is `null` on both engines — npm `rolldown` always answered that,
+                // and `@gjsify/rolldown-native` now does too (`isResolveMiss`, which is
+                // where the engine mismatch that hid this plugin's diagnostic under GJS
+                // is fixed). What reaches this catch is the OTHER kind: a hook in that
+                // chain throwing on purpose (`napi-node-addon`'s `resolveAddonPath`), an
+                // EACCES, a corrupt `package.json`, a bridge fault. Letting it escape
+                // surfaces it as a bare "plugin `gjsify-alias` threw an error" naming
+                // neither specifier nor importer; swallowing it would report a real fault
+                // as the user's missing dependency. So it is caught, kept, and thrown
+                // BELOW with this plugin's context around it and the original as `cause`.
+                let resolverFailure;
                 try {
                     resolved = await this.resolve(verdict.candidate, importer, {
                         skipSelf: true,
                         kind: extraOptions?.kind,
                     });
                 }
+                catch (err) {
+                    resolverFailure = err;
+                }
                 finally {
                     inFlight.delete(key);
                 }
@@ -212,6 +249,30 @@ export function unresolvedWorkspaceImportPlugin(options) {
                     resolvedCache.set(key, resolved);
                     return resolved;
                 }
+                // Toolchain fallback — see `toolchainAnchor`. Only after a real `null`:
+                // a resolver that ERRORED has not established that the project lacks the
+                // package, and rescuing there would turn "project first, always" into
+                // "project first unless the project errors".
+                if (resolverFailure === undefined && toolchainAnchor !== undefined) {
+                    const fromToolchain = await this.resolve(verdict.candidate, toolchainAnchor, {
+                        skipSelf: true,
+                        kind: extraOptions?.kind,
+                    });
+                    if (fromToolchain) {
+                        // The one visible trace that this artifact is MIXED — some of its
+                        // `@gjsify/*` from the project, this one from the CLI's own
+                        // install, possibly a different major. Without it a rescued build
+                        // and a healthy one have byte-identical logs, and a wrong answer
+                        // that leaves no trace is the expensive kind. Deduplicated by
+                        // `resolvedCache`: one line per (candidate, importer dir, kind).
+                        this.warn(`gjsify: \`${verdict.candidate}\` did not resolve from the project ` +
+                            `(imported by ${importer ?? '<entry>'}) — using the copy installed beside the ` +
+                            `running CLI (${toolchainAnchor}). Build the workspace package to use the ` +
+                            `project's own copy.`);
+                        resolvedCache.set(key, fromToolchain);
+                        return fromToolchain;
+                    }
+                }
                 throw new UnresolvedWorkspaceImportError({
                     target,
                     source,
@@ -219,7 +280,10 @@ export function unresolvedWorkspaceImportPlugin(options) {
                     aliasTarget: verdict.aliasTarget,
                     aliasedFrom: reverseAliases.get(verdict.candidate)?.filter((s) => s !== source),
                     importer: importer ?? '<entry>',
-                });
+                    ...(resolverFailure === undefined
+                        ? {}
+                        : { resolverFailure: describeResolverFailure(resolverFailure) }),
+                }, resolverFailure);
             },
         },
     };

package/lib/types/plugin-options.d.ts

@@ -67,4 +67,16 @@ export interface PluginOptions {
      * the wrapper. Defaults to `false`.
      */
     preserveDefaultExport?: boolean;
+    /**
+     * Where to look for a `@gjsify/*` the PROJECT cannot resolve, when the input is
+     * TOOLCHAIN rather than user code: a file path inside the running CLI's own
+     * install, used as the importer of a second resolve.
+     *
+     * OPT-IN PER CALL SITE, never inferred from the code path. `gjsify build` never
+     * sets it, and neither does a `node <file>` in an ordinary project's package
+     * script — a user's application must still fail loudly on a missing dependency
+     * rather than silently pick up whatever version the CLI ships. Rationale and the
+     * measured incident: `WorkspaceImportGuardOptions.toolchainAnchor`.
+     */
+    toolchainAnchor?: string;
 }

package/lib/utils/inline-static-reads.d.ts

@@ -1,10 +1,3 @@
-/**
- * Run the inliner on a source string. Returns the rewritten source (or the
- * original string when no inlining applied) and the count of edits applied.
- *
- * Safe to call on any JS source. Files that don't reference `readFileSync` /
- * `readdirSync` / `existsSync` skip the AST parse entirely (cheap fast path).
- */
 export declare function inlineStaticReads(src: string, sourceFilePath: string): {
     contents: string;
     inlined: number;

package/lib/utils/inline-static-reads.js

@@ -41,7 +41,7 @@
 // Anything not statically resolvable is left untouched — the legacy
 // `import.meta.url` rewriter still applies as a fallback.
 import * as acorn from 'acorn';
-import * as walk from 'acorn-walk';
+import { tsPlugin } from 'acorn-typescript';
 import { dirname, join, resolve, basename, relative, extname, posix, win32 } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
@@ -52,35 +52,98 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
  * Safe to call on any JS source. Files that don't reference `readFileSync` /
  * `readdirSync` / `existsSync` skip the AST parse entirely (cheap fast path).
  */
+const TS_EXT_RE = /\.[cm]?tsx?$/i;
+/**
+ * The TypeScript-capable parser, built once.
+ *
+ * `acorn-typescript` and not the bundler's own parser, and the reason is the
+ * runtime rather than a preference: under GJS the engine is
+ * `@gjsify/rolldown-native`, and npm `rolldown` is "a Rust napi crate that cannot
+ * run under GJS" (`bundler-pick.ts`), loaded only behind a dynamic import on Node.
+ * A top-level `import { parseAst } from 'rolldown/parseAst'` therefore links a
+ * Node-only N-API package into a module that has to load under GJS — measured:
+ * the CLI's own bundle then died at startup with `createRequire: Cannot require
+ * builtin module "fs" synchronously in GJS`. `acorn-typescript` is pure JS, emits
+ * the same ESTree shapes the evaluator below already speaks, and needs
+ * `locations: true` (it refuses to parse without them).
+ */
+const TS_PARSER = acorn.Parser.extend(tsPlugin());
+/**
+ * Parse a source with the parser its extension calls for.
+ *
+ * The TypeScript half is why first-party sources were invisible to this inliner
+ * for as long as it was scoped to `node_modules`: an installed package ships JS,
+ * so plain acorn could always parse it, and nothing ever asked what happens to a
+ * `.ts`. The answer was that `acorn.parse` threw and the `catch` returned
+ * "nothing to inline" — a result indistinguishable from a file that genuinely has
+ * no static reads. Measured on `packages/infra/cli/src/utils/app-metadata.ts`:
+ * `inlined: 0`, while the identical expression in a `.js` file returned
+ * `inlined: 1`.
+ */
+function parseSource(src, sourceFilePath) {
+    const shared = {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        allowAwaitOutsideFunction: true,
+        allowReturnOutsideFunction: true,
+        allowImportExportEverywhere: true,
+    };
+    if (!TS_EXT_RE.test(sourceFilePath))
+        return acorn.parse(src, shared);
+    return TS_PARSER.parse(src, { ...shared, locations: true });
+}
+/**
+ * Visit every `CallExpression` in the tree.
+ *
+ * A generic descent rather than `acorn-walk`, and that is not a preference:
+ * `walk.simple` looks its visitor up in a table keyed by node type and throws
+ * `No walker function defined for node type TSInterfaceDeclaration` on the first
+ * interface in a first-party source. A walker with no node table cannot fall
+ * behind the parser — which matters precisely because the parser is now allowed
+ * to emit node types this file has never heard of.
+ */
+function forEachCallExpression(root, visit) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node === null || typeof node !== 'object')
+            continue;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                stack.push(child);
+            continue;
+        }
+        if (node.type === 'CallExpression')
+            visit(node);
+        for (const value of Object.values(node)) {
+            if (value !== null && typeof value === 'object')
+                stack.push(value);
+        }
+    }
+}
 export function inlineStaticReads(src, sourceFilePath) {
     if (!src.includes('readFileSync') && !src.includes('readdirSync') && !src.includes('existsSync')) {
         return { contents: src, inlined: 0 };
     }
     let ast;
     try {
-        ast = acorn.parse(src, {
-            ecmaVersion: 'latest',
-            sourceType: 'module',
-            allowAwaitOutsideFunction: true,
-            allowReturnOutsideFunction: true,
-            allowImportExportEverywhere: true,
-        });
+        ast = parseSource(src, sourceFilePath);
     }
     catch {
-        // Source isn't valid JS (CJS source with shebangs, mixed module
-        // syntax, ...). Skip; the rest of the rewriter still runs.
+        // Not parseable as the language its extension claims (a CJS source with
+        // a shebang, mixed module syntax, ...). Skip; the rest of the rewriter
+        // still runs. This catch used to swallow every TypeScript file in the
+        // tree as well — see `parseSource`.
         return { contents: src, inlined: 0 };
     }
     const ctx = {
         sourceUrl: pathToFileURL(sourceFilePath).href,
     };
     const edits = [];
-    walk.simple(ast, {
-        CallExpression(node) {
-            const edit = tryInlineCall(node, ctx, src);
-            if (edit)
-                edits.push(edit);
-        },
+    forEachCallExpression(ast, (node) => {
+        const edit = tryInlineCall(node, ctx, src);
+        if (edit)
+            edits.push(edit);
     });
     if (edits.length === 0)
         return { contents: src, inlined: 0 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-plugin-gjsify",
-    "version": "0.40.0",
+    "version": "0.42.0",
     "description": "Rolldown / Rollup / Vite plugin orchestrator for GJS, Node, and Browser targets",
     "type": "module",
     "main": "lib/index.js",
@@ -55,20 +55,21 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/console": "^0.40.0",
-        "@gjsify/resolve-npm": "^0.40.0",
-        "@gjsify/rolldown-plugin-deepkit": "^0.40.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.40.0",
-        "@gjsify/vite-plugin-blueprint": "^0.40.0",
+        "@gjsify/console": "^0.42.0",
+        "@gjsify/resolve-npm": "^0.42.0",
+        "@gjsify/rolldown-plugin-deepkit": "^0.42.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.42.0",
+        "@gjsify/vite-plugin-blueprint": "^0.42.0",
         "@rollup/pluginutils": "^5.4.0",
         "acorn": "^8.17.0",
+        "acorn-typescript": "^1.4.13",
         "acorn-walk": "^8.3.5",
         "fast-glob": "^3.3.3",
         "lightningcss": "^1.32.0",
         "sass": "^1.101.0"
     },
     "peerDependencies": {
-        "@gjsify/lightningcss-native": "^0.40.0",
+        "@gjsify/lightningcss-native": "^0.42.0",
         "rolldown": "^1.1.4"
     },
     "peerDependenciesMeta": {