@gjsify/rolldown-plugin-gjsify 0.52.0 → 0.53.0

package/lib/shims/addon-resolve.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve the addon's `.node` for the RUNNING host from the build-time table.
+ *
+ * `targets` maps platform keys (`linux-x64`, `linux-x64-musl`, …) to
+ * `<package>/<subpath>` specs. The host keys are tried most-specific first
+ * (exact, then libc-agnostic, then `*`). The package root is resolved at run
+ * time through the bundle-URL anchor, which is what makes the bundle relocatable
+ * (ADR 0084).
+ *
+ * Throws when no entry matches the running host, when the table is empty, and
+ * when the addon package is not installed next to the bundle. The last one is
+ * a LIMIT, not an oversight: identity-based resolution needs the package to be
+ * somewhere on disk, so a bundle shipped with no `node_modules` around it cannot
+ * load a third-party addon. It throws rather than returning
+ * `<bundle dir>/addons/…` because that directory is a declared layout nothing
+ * fills yet, and a path that cannot exist reaches `loadAddon` as a bare ENOENT
+ * that names neither the package nor the remedy. Both facts are in the message.
+ */
+export declare function __gjsifyAddonResolve(targets: Record<string, string>): string;

package/lib/shims/addon-resolve.js

@@ -0,0 +1,193 @@
+// Runtime resolver for a GJS bundle's Node-API addon, ADR 0084.
+//
+// The build enumerates every `.node` an addon package ships, keyed by
+// platform (`linux-x64`, `linux-x64-musl`, `darwin-arm64`, …), and bakes the
+// table into the bundle. At RUN time the bundle picks the entry for the host
+// it finds itself on and resolves the addon's package root through the same
+// `__gjsifyBundleUrl` banner + `createRequire` anchor the module-resolve shim
+// uses. The addon is never copied and never leaves its package, so a `.node`
+// that `dlopen`s a sibling `.so` or reads a data file beside itself keeps
+// working.
+//
+// Three correctness constraints shape the implementation:
+//
+//  1. *Location anchor.* The resolver anchors at the BUNDLE's URL, not its
+//     own. When a consumer bundles this shim it lives under
+//     `node_modules/@gjsify/rolldown-plugin-gjsify/...`, so the path rewriter
+//     would rewrite this file's own `import.meta.url` too. We therefore take
+//     no `import.meta.url` here and read the anchor from `globalThis.
+//     __gjsifyBundleUrl`, captured by a one-line banner at byte 0 of the
+//     bundle — the single point where `import.meta.url` is unambiguously the
+//     bundle's URL.
+//
+//  2. *exports-map safety.* `createRequire(...).resolve("<pkg>/<deep/path>")`
+//     is rejected by strict `"exports"` maps under Node's native
+//     `createRequire` (the `--app node` target), and `@gjsify/module` is
+//     exports-aware too. So we never resolve the deep path directly: we
+//     resolve the PACKAGE ROOT and join the subpath literally, which no
+//     `exports` map can block.
+//
+//  3. *libc is a variable, not a probe.* It is read from `process.env.LIBC`,
+//     never sniffed off the filesystem. On a musl host with an unset `LIBC`
+//     the lookup falls through to the libc-agnostic entry, which is what
+//     node-gyp-build's own untagged prebuilds assume; a package shipping a
+//     glibc-only and a musl prebuild under one tuple is served the glibc one,
+//     which `LIBC=musl` fixes. (The one `package.json` read in this file is on
+//     the `exports`-blocked root fallback, not on the libc decision.)
+//
+// The `addons/` layout the resolver names when the package is not installed is
+// the declared destination a packaging step would fill. `gjsify ship` does not
+// fill it yet — see ADR 0084 § Consequences for the measurement.
+//
+// @ts-ignore — `node:{module,url,path,fs}` are resolved by the consumer's
+// `gjsify build` run (aliased to `@gjsify/{module,url,path,fs}`), not by tsc here.
+import { createRequire } from 'node:module';
+// @ts-ignore — see above.
+import { fileURLToPath } from 'node:url';
+// @ts-ignore — see above.
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+// @ts-ignore — see above. Read on the `exports`-blocked fallback only; see
+// `declaresPackage`. The no-filesystem rule above is about libc, not this.
+import { readFileSync } from 'node:fs';
+import { hostAddonKeys, selectAddonTarget } from '../utils/addon-platform.js';
+/** The bundle's own URL (set by the byte-0 banner). Throws only if the banner didn't run. */
+function bundleAnchorUrl() {
+    const anchor = globalThis.__gjsifyBundleUrl;
+    if (!anchor) {
+        throw new Error('gjsify: __gjsifyBundleUrl is not set — the bundle-URL banner did not run. ' +
+            'The addon-resolve shim is only valid in single-file app builds (gjsify build --app gjs).');
+    }
+    return anchor;
+}
+/**
+ * Split a bundled-file spec into its package name and the path within the
+ * package. Handles scoped names:
+ *   "typedoc/dist/lib/app.js"   → { pkg: "typedoc",        subpath: "dist/lib/app.js" }
+ *   "@scope/name/sub/file.js"   → { pkg: "@scope/name",    subpath: "sub/file.js" }
+ *   "typedoc"                   → { pkg: "typedoc",        subpath: "" }
+ */
+function splitPackageSpec(spec) {
+    const parts = spec.split('/');
+    const segments = spec.startsWith('@') ? 2 : 1;
+    return {
+        pkg: parts.slice(0, segments).join('/'),
+        subpath: parts.slice(segments).join('/'),
+    };
+}
+/**
+ * Find the on-disk root directory of `pkg`, exports-map-agnostic.
+ *
+ * `package.json` is resolvable for nearly every package and points straight at
+ * the root. When a strict `exports` map blocks it, fall back to the package's
+ * main entry (always an export) and derive the root from the
+ * `node_modules/<pkg>` boundary in its path.
+ *
+ * A WORKSPACE-LINKED package resolves to its real path, which carries no
+ * `node_modules/<pkg>/` segment, and answering `dirname(main)` there named the
+ * directory the entry sits in — `packages/typedoc/dist` — so the subpath was
+ * joined onto `dist/` and the addon was reported missing at a path that never
+ * existed. The boundary is therefore only a shortcut; the fallback walks up to
+ * the nearest ancestor whose own `package.json` declares `pkg`, which is the
+ * root by definition. Returns null when `pkg` is not installed.
+ */
+function resolvePackageRoot(pkg) {
+    try {
+        const require = createRequire(bundleAnchorUrl());
+        return dirname(require.resolve(`${pkg}/package.json`));
+    }
+    catch {
+        /* strict `exports`: fall through to the entry point */
+    }
+    let main;
+    try {
+        main = createRequire(bundleAnchorUrl()).resolve(pkg);
+    }
+    catch {
+        return null;
+    }
+    const marker = `/node_modules/${pkg}/`;
+    const idx = main.lastIndexOf(marker);
+    if (idx >= 0)
+        return main.slice(0, idx + marker.length - 1);
+    for (let dir = dirname(main), i = 0; i < 64; i++) {
+        if (declaresPackage(dir, pkg))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Does the `package.json` in `dir` declare `name: pkg`? The root test, read not inferred. */
+function declaresPackage(dir, pkg) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        return manifest.name === pkg;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the addon's `.node` for the RUNNING host from the build-time table.
+ *
+ * `targets` maps platform keys (`linux-x64`, `linux-x64-musl`, …) to
+ * `<package>/<subpath>` specs. The host keys are tried most-specific first
+ * (exact, then libc-agnostic, then `*`). The package root is resolved at run
+ * time through the bundle-URL anchor, which is what makes the bundle relocatable
+ * (ADR 0084).
+ *
+ * Throws when no entry matches the running host, when the table is empty, and
+ * when the addon package is not installed next to the bundle. The last one is
+ * a LIMIT, not an oversight: identity-based resolution needs the package to be
+ * somewhere on disk, so a bundle shipped with no `node_modules` around it cannot
+ * load a third-party addon. It throws rather than returning
+ * `<bundle dir>/addons/…` because that directory is a declared layout nothing
+ * fills yet, and a path that cannot exist reaches `loadAddon` as a bare ENOENT
+ * that names neither the package nor the remedy. Both facts are in the message.
+ */
+export function __gjsifyAddonResolve(targets) {
+    const keys = hostAddonKeys(process.platform, process.arch, process.env.LIBC);
+    const spec = selectAddonTarget(targets, keys);
+    if (spec === null) {
+        const known = Object.keys(targets).join(', ') || '(empty)';
+        throw new Error(`gjsify-napi-addon: no .node for host '${process.platform}-${process.arch}' ` +
+            `(libc: ${process.env.LIBC ?? 'unset'}). Addon table knows: ${known}. ` +
+            `Install the platform package or build the addon for this host.`);
+    }
+    // A `.node` outside every `node_modules` has no package IDENTITY to resolve
+    // by, and `packageSpecFor` recorded the path itself. Splitting it as a
+    // specifier made the first segment the package name and the rest the subpath,
+    // so a direct import of a locally built addon resolved a package named ``
+    // and threw naming neither the file nor the remedy. There is nothing to
+    // resolve — the build's path is the only answer — so it is returned, and the
+    // build warns once that this entry does not travel with the bundle.
+    if (isAbsolute(spec))
+        return spec;
+    const { pkg, subpath } = splitPackageSpec(spec);
+    const root = resolvePackageRoot(pkg);
+    if (root !== null) {
+        if (subpath === '')
+            return root;
+        // The subpath is the build's own `relative()` today, so this cannot
+        // reject a table this plugin wrote. It is here because this is the
+        // function that decides which file gets dlopen'd: a table naming `..`
+        // would otherwise walk out of the package it claims to belong to.
+        const target = resolve(root, subpath);
+        if (target !== root && !target.startsWith(root + sep)) {
+            throw new Error(`gjsify-napi-addon: the addon table names '${subpath}', which leaves the package ` +
+                `root '${root}'. A package cannot provide a file outside itself.`);
+        }
+        return target;
+    }
+    // The package is not installed where this bundle can see it. `<bundle
+    // dir>/addons/<package>/` is the declared layout a packaging step would
+    // fill — `gjsify ship` does not yet — so name it and the two remedies.
+    const staged = join(dirname(fileURLToPath(bundleAnchorUrl())), 'addons', pkg, subpath);
+    throw new Error(`gjsify-napi-addon: cannot find the addon package '${pkg}' from this bundle. ` +
+        `A GJS bundle finds its addon by package identity, so '${pkg}' must be installed in a ` +
+        `node_modules reachable from the bundle's own location, or staged at ` +
+        `'${staged}' (a layout no gjsify step fills yet). Run the bundle next to its ` +
+        "project's node_modules, or rebuild where the package is installed.");
+}

package/lib/utils/addon-platform.d.ts

@@ -0,0 +1,23 @@
+/** The one spelling: `linux-x64`, `linux-x64-musl`, `darwin-arm64`, `win32-x64`. */
+export declare function addonPlatformKey(platform: string, arch: string, libc?: string): string;
+/**
+ * A napi-rs triple as an {@link addonPlatformKey}. The ABI token napi-rs appends is
+ * either implied by the platform (`gnu` on linux, `msvc` on win32, the arm eabi
+ * flavours) or a real axis (`musl`) — only the latter survives into the key.
+ */
+export declare function normalizeNapiRsTriple(triple: string): string;
+/**
+ * The keys to try for a host, most specific first.
+ *
+ * A musl host also accepts the UNTAGGED key, because that is what node-gyp-build's own
+ * untagged prebuilds mean — "no libc claim" — and a musl-only tree would otherwise find
+ * nothing. A glibc host does NOT accept the musl key: loading a musl binary against
+ * glibc is the failure this selection exists to avoid, and a missing entry with a clear
+ * message beats a `dlopen` crash.
+ *
+ * `*` is last and is not host-specific: it is the entry a DIRECTLY imported `.node`
+ * writes, where the source named one file and there is no selection to make.
+ */
+export declare function hostAddonKeys(platform: string, arch: string, libc?: string): string[];
+/** The first key of `keys` present in `targets`, or null. */
+export declare function selectAddonTarget(targets: Record<string, string>, keys: string[]): string | null;

package/lib/utils/addon-platform.js

@@ -0,0 +1,50 @@
+// The platform VOCABULARY shared by the two halves of ADR 0084: the build enumerates
+// every `.node` an addon package ships, keyed by platform; the bundle picks one at run
+// time from the host it finds itself on. Both halves must spell a platform the same way
+// or the lookup silently misses, so the spelling lives here — a pure module with no
+// `node:` imports, because the runtime half (`shims/addon-resolve.ts`) is bundled into
+// user output and must not drag the filesystem in.
+//
+// The key is node-gyp-build's tuple (`<platform>-<arch>`) plus a `-musl` suffix, NOT
+// napi-rs' triple: napi-rs spells the same platform `linux-x64-gnu` / `win32-x64-msvc`
+// while prebuildify spells it `linux-x64`, and one bundle can carry addons of both
+// conventions. {@link normalizeNapiRsTriple} folds the second spelling into the first.
+/** The one spelling: `linux-x64`, `linux-x64-musl`, `darwin-arm64`, `win32-x64`. */
+export function addonPlatformKey(platform, arch, libc) {
+    return libc === 'musl' ? `${platform}-${arch}-musl` : `${platform}-${arch}`;
+}
+/**
+ * A napi-rs triple as an {@link addonPlatformKey}. The ABI token napi-rs appends is
+ * either implied by the platform (`gnu` on linux, `msvc` on win32, the arm eabi
+ * flavours) or a real axis (`musl`) — only the latter survives into the key.
+ */
+export function normalizeNapiRsTriple(triple) {
+    if (triple.endsWith('-musl'))
+        return triple;
+    return triple.replace(/-(?:gnu|msvc|eabi|eabihf|gnueabihf|androideabi)$/, '');
+}
+/**
+ * The keys to try for a host, most specific first.
+ *
+ * A musl host also accepts the UNTAGGED key, because that is what node-gyp-build's own
+ * untagged prebuilds mean — "no libc claim" — and a musl-only tree would otherwise find
+ * nothing. A glibc host does NOT accept the musl key: loading a musl binary against
+ * glibc is the failure this selection exists to avoid, and a missing entry with a clear
+ * message beats a `dlopen` crash.
+ *
+ * `*` is last and is not host-specific: it is the entry a DIRECTLY imported `.node`
+ * writes, where the source named one file and there is no selection to make.
+ */
+export function hostAddonKeys(platform, arch, libc) {
+    const base = addonPlatformKey(platform, arch);
+    return libc === 'musl' ? [`${base}-musl`, base, '*'] : [base, '*'];
+}
+/** The first key of `keys` present in `targets`, or null. */
+export function selectAddonTarget(targets, keys) {
+    for (const key of keys) {
+        const hit = targets[key];
+        if (typeof hit === 'string' && hit.length > 0)
+            return hit;
+    }
+    return null;
+}

package/lib/utils/auto-globals.d.ts

@@ -55,6 +55,12 @@ export interface DetectAutoGlobalsOptions {
      * `process.cwd()`.
      */
     cwd?: string;
+    /**
+     * A second root for that gate: the running CLI's directory when the build was given
+     * a `toolchainAnchor`, whose resolver takes a `@gjsify/*` the project lacks from
+     * beside the CLI. Only consulted together with `cwd`.
+     */
+    toolchainDir?: string;
 }
 /**
  * Build options for the analyser: the same input options the caller would use for the

package/lib/utils/auto-globals.js

@@ -81,7 +81,7 @@ function isSubset(a, b) {
             return false;
     return true;
 }
-async function applyExcludeGlobals(detected, currentInject, extraRegisterPaths, excludeGlobals, cwd) {
+async function applyExcludeGlobals(detected, currentInject, extraRegisterPaths, excludeGlobals, cwd, searchDirs = cwd) {
     if (excludeGlobals?.length) {
         for (const id of excludeGlobals)
             detected.delete(id);
@@ -91,12 +91,12 @@ async function applyExcludeGlobals(detected, currentInject, extraRegisterPaths,
     const finalPaths = detectedToRegisterPaths(detected);
     for (const p of extraRegisterPaths)
         finalPaths.add(p);
-    emitGiBackedDiagnostic(finalPaths, detected, cwd);
+    emitGiBackedDiagnostic(finalPaths, detected, searchDirs);
     // No exclude: `currentInject` already reflects `finalPaths`, so reuse it —
     // re-running filterResolvableRegisterPaths would repeat its skip warnings.
     if (!excludeGlobals?.length)
         return { detected, injectPath: currentInject };
-    const filtered = cwd ? filterResolvableRegisterPaths(finalPaths, cwd) : finalPaths;
+    const filtered = searchDirs ? filterResolvableRegisterPaths(finalPaths, searchDirs) : finalPaths;
     const injectPath = filtered.size > 0 ? ((await writeRegisterInjectFile(filtered, cwd)) ?? undefined) : undefined;
     return { detected, injectPath };
 }
@@ -169,14 +169,14 @@ let giNoteEmitted = false;
  * register, via `isRegisterPathResolvable` rather than
  * `filterResolvableRegisterPaths` to avoid duplicating that one's skip warnings.
  */
-function emitGiBackedDiagnostic(registerPaths, detected, cwd) {
+function emitGiBackedDiagnostic(registerPaths, detected, searchDirs) {
     if (giNoteEmitted)
         return;
     const candidates = new Set();
     for (const path of registerPaths) {
         if (!giNamespacesForRegister(path))
             continue;
-        if (cwd && !isRegisterPathResolvable(path, cwd))
+        if (searchDirs && !isRegisterPathResolvable(path, searchDirs))
             continue;
         candidates.add(path);
     }
@@ -265,10 +265,13 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         : new Set();
     const excludeSet = new Set(options.excludeGlobals ?? []);
     const cwd = options.cwd;
+    const searchDirs = cwd && options.toolchainDir ? [cwd, options.toolchainDir] : cwd;
     let detected = new Set();
     let currentInject = undefined;
     if (extraRegisterPaths.size > 0) {
-        const resolvableExtra = cwd ? filterResolvableRegisterPaths(extraRegisterPaths, cwd) : extraRegisterPaths;
+        const resolvableExtra = searchDirs
+            ? filterResolvableRegisterPaths(extraRegisterPaths, searchDirs)
+            : extraRegisterPaths;
         currentInject = (await writeRegisterInjectFile(resolvableExtra, cwd)) ?? undefined;
     }
     // Caller plugins (e.g. the PnP relay) survive every pass; the gjsify plugin is
@@ -381,7 +384,7 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
                 const extras = extraRegisterPaths.size > 0 ? ` (+ ${extraRegisterPaths.size} extra register module(s))` : '';
                 console.debug(`[gjsify] --globals auto: converged after ${iteration - 1} iteration(s), ${detected.size} global(s)${sorted.length ? ': ' + sorted.join(', ') : ''}${extras}`);
             }
-            return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals, cwd);
+            return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals, cwd, searchDirs);
         }
         // Seed the next pass with the precomputed closure. Unioning with the
         // previously-injected set keeps growth monotonic — an over-approximated superset
@@ -405,8 +408,8 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         // Drop register paths whose polyfill package is not installed: an unresolvable
         // import is a HARD Rolldown error, strictly worse than skipping with a warning.
         // The caller adds the dep or acknowledges the gap via --exclude-globals.
-        if (cwd)
-            registerPaths = filterResolvableRegisterPaths(registerPaths, cwd);
+        if (searchDirs)
+            registerPaths = filterResolvableRegisterPaths(registerPaths, searchDirs);
         if (registerPaths.size === 0) {
             return { detected, injectPath: undefined };
         }
@@ -419,7 +422,7 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
     if (verbose) {
         console.debug(`[gjsify] --globals auto: hit max iterations (${MAX_ITERATIONS}), using last detected set`);
     }
-    return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals, cwd);
+    return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals, cwd, searchDirs);
 }
 /**
  * `--app node` genuine-GJS-source detection (the reverse of `--globals auto`).

package/lib/utils/declare-build-input.d.ts

@@ -0,0 +1,13 @@
+/** One file the output depends on. */
+export type DeclareBuildInput = (abs: string) => void;
+/** A plugin context that MAY carry `addWatchFile` — an older engine does not. */
+export interface WatchFileCapableContext {
+    addWatchFile?: (id: string) => void;
+}
+/**
+ * `this.addWatchFile(abs)`, or one line saying it was missing.
+ *
+ * The context is passed in rather than bound, so each caller keeps its own `this`
+ * and this stays usable from any hook shape.
+ */
+export declare function declareBuildInput(ctx: WatchFileCapableContext, abs: string): void;

package/lib/utils/declare-build-input.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+// "This file is an input of the output" — `this.addWatchFile`, one layer down.
+//
+// Two of this package's plugins read a file the BUNDLER never sees: a
+// stylesheet's `@import` chain (`css-as-string`) and a package's own
+// `readFileSync(new URL(..., import.meta.url))` (the static-read inliner, which
+// folds the bytes into the bundle). Neither file is a module, so no graph names
+// it and a `gjsify test` bundle that depends on one reads as fresh after it
+// changes. `this.addWatchFile` is the standard contract for exactly that, and
+// this is the one place it is issued from.
+//
+// FEATURE-DETECTED, and that is measured, not defensive: the engine the GJS CLI
+// loads is resolved through several anchors, and one of them answered with a
+// build whose plugin context had no such method — a direct call then fails the
+// build with `this.addWatchFile is not a function`. A build must not fail over
+// bookkeeping, so a miss degrades to a single line naming the consequence and the
+// fix. The other half is in the CLI: a bundle whose build reported NO watch list
+// can never be called fresh (`utils/bundle-inputs.ts`).
+let _warned = false;
+/**
+ * `this.addWatchFile(abs)`, or one line saying it was missing.
+ *
+ * The context is passed in rather than bound, so each caller keeps its own `this`
+ * and this stays usable from any hook shape.
+ */
+export function declareBuildInput(ctx, abs) {
+    if (typeof ctx.addWatchFile === 'function') {
+        ctx.addWatchFile.call(ctx, abs);
+        return;
+    }
+    if (_warned)
+        return;
+    _warned = true;
+    console.warn('[gjsify] this Rolldown engine has no `addWatchFile`, so a file a plugin read itself is ' +
+        'not declared as a build input — editing one may leave a `gjsify test` bundle looking ' +
+        'fresh. Upgrade `@gjsify/rolldown-native` (the GJS engine) to declare it.');
+}

package/lib/utils/detect-free-globals.d.ts

@@ -1,3 +1,6 @@
+import * as acorn from 'acorn';
+/** Every name bound by a binding pattern. */
+export declare function extractBindingNames(node: acorn.AnyNode): string[];
 /**
  * Free identifiers in bundled output that match the known web/Node globals in
  * `GJS_GLOBALS_MAP` — drives `--app gjs --globals auto`. Rules: `scanFreeGlobals`.

package/lib/utils/detect-free-globals.js

@@ -69,7 +69,7 @@ function wbgJsNameFor(fnName) {
     return match?.[1] ?? null;
 }
 /** Every name bound by a binding pattern. */
-function extractBindingNames(node) {
+export function extractBindingNames(node) {
     if (!node)
         return [];
     switch (node.type) {

package/lib/utils/entry-wrapper.js

@@ -25,7 +25,12 @@ export function wrapInputWithSideEffects(input, sideEffects, opts = {}) {
     const userEntries = new Map(); // virtualId → realPath
     const PREFIX = `${GJSIFY_VIRTUAL_PREFIX}entry:`;
     function wrap(realPath) {
-        const id = PREFIX + realPath;
+        // The wrapper is ESM whatever the entry is, and Rolldown reads a module's
+        // format off its id's EXTENSION: `\0gjsify-entry:…/prettier.cjs` was parsed as
+        // CommonJS and every `import` in the wrapper failed with `PARSE_ERROR: Cannot
+        // use import statement outside a module`. A CJS entry therefore gets `.mjs`
+        // appended; the others keep the id they always had.
+        const id = PREFIX + realPath + (/\.c[jt]sx?$/i.test(realPath) ? '.mjs' : '');
         userEntries.set(id, realPath);
         return id;
     }

package/lib/utils/index.d.ts

@@ -9,3 +9,4 @@ export { inlineStaticReads, isAbsoluteFsPath, isWithin, resourceRootFor } from '
 export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';
 export { locateSurvivingJsx, classifyJsxParseFailure, formatSurvivingJsx } from './jsx-survival.js';
 export type { SurvivingJsx } from './jsx-survival.js';
+export { wrapInputWithSideEffects } from './entry-wrapper.js';

package/lib/utils/index.js

@@ -8,3 +8,4 @@ export { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
 export { inlineStaticReads, isAbsoluteFsPath, isWithin, resourceRootFor } from './inline-static-reads.js';
 export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';
 export { locateSurvivingJsx, classifyJsxParseFailure, formatSurvivingJsx } from './jsx-survival.js';
+export { wrapInputWithSideEffects } from './entry-wrapper.js';

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

@@ -1,4 +1,18 @@
-export declare function inlineStaticReads(src: string, sourceFilePath: string): {
+import * as acorn from 'acorn';
+/**
+ * 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`.
+ */
+export declare function parseSource(src: string, sourceFilePath: string): acorn.Program;
+export declare function inlineStaticReads(src: string, sourceFilePath: string, declare?: (abs: string) => void): {
     contents: string;
     inlined: number;
 };

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

@@ -66,6 +66,7 @@ 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';
+import { hasZipSegment } from './zip-path.js';
 /**
  * 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.
@@ -101,7 +102,7 @@ const TS_PARSER = acorn.Parser.extend(tsPlugin());
  * `inlined: 0`, while the identical expression in a `.js` file returned
  * `inlined: 1`.
  */
-function parseSource(src, sourceFilePath) {
+export function parseSource(src, sourceFilePath) {
     const shared = {
         ecmaVersion: 'latest',
         sourceType: 'module',
@@ -142,7 +143,7 @@ function forEachCallExpression(root, visit) {
         }
     }
 }
-export function inlineStaticReads(src, sourceFilePath) {
+export function inlineStaticReads(src, sourceFilePath, declare) {
     if (!src.includes('readFileSync') && !src.includes('readdirSync') && !src.includes('existsSync')) {
         return { contents: src, inlined: 0 };
     }
@@ -160,6 +161,7 @@ export function inlineStaticReads(src, sourceFilePath) {
     const ctx = {
         sourceUrl: pathToFileURL(sourceFilePath).href,
         resourceRoot: resourceRootFor(sourceFilePath),
+        declare,
     };
     const edits = [];
     forEachCallExpression(ast, (node) => {
@@ -246,6 +248,7 @@ function tryInlineCall(node, ctx, _src) {
         if (path && existsSync(path) && isDirectorySafe(path)) {
             try {
                 const names = readdirSync(path);
+                ctx.declare?.(path);
                 return {
                     start: node.start,
                     end: node.end,
@@ -260,11 +263,11 @@ function tryInlineCall(node, ctx, _src) {
     if (calleeName === 'existsSync') {
         const path = evalPathExpr(node.arguments[0], ctx);
         if (path !== undefined) {
-            return {
-                start: node.start,
-                end: node.end,
-                replacement: existsSync(path) ? 'true' : 'false',
-            };
+            // The ANSWER is in the bundle, so the file's existence is an input
+            // of the output — a file that appears changes the emitted literal.
+            const present = existsSync(path);
+            ctx.declare?.(path);
+            return { start: node.start, end: node.end, replacement: present ? 'true' : 'false' };
         }
     }
     // `createRequire(<URL>)` from `node:module` returns a CJS-style require.
@@ -288,8 +291,11 @@ function tryInlineCall(node, ctx, _src) {
         //  - the path contains a `.zip/` segment (Yarn PnP virtual zip,
         //    where Node's PnP hooks make `existsSync` return true at build
         //    time but the path doesn't exist under GJS at runtime).
-        const isZip = path !== undefined && path.includes('.zip/');
+        const isZip = path !== undefined && hasZipSegment(path);
         if (path !== undefined && (isZip || !existsSync(path))) {
+            // The stub-vs-real choice reads the file's existence too, so the
+            // same declaration applies to the branch that replaces the call.
+            ctx.declare?.(path);
             return {
                 start: node.start,
                 end: node.end,
@@ -330,6 +336,7 @@ function tryInlineReadFile(node, ctx, forceTextEncoding) {
     try {
         if (encoding) {
             const text = readFileSync(path, encoding);
+            ctx.declare?.(path);
             return jsStringLiteral(text);
         }
         else {
@@ -337,6 +344,7 @@ function tryInlineReadFile(node, ctx, forceTextEncoding) {
             // Buffer-vs-Uint8Array semantic difference is mostly irrelevant in
             // bundled GJS code (Buffer is polyfilled on top of Uint8Array).
             const bytes = readFileSync(path);
+            ctx.declare?.(path);
             return `new Uint8Array([${Array.from(bytes).join(',')}])`;
         }
     }

package/lib/utils/scan-globals.d.ts

@@ -34,7 +34,7 @@ export declare function resolveGlobalsList(globalsArg: string): Set<string>;
  * Returns false — never throws — so a missing package causes a graceful
  * skip rather than a build crash.
  */
-export declare function isRegisterPathResolvable(registerPath: string, fromDir: string): boolean;
+export declare function isRegisterPathResolvable(registerPath: string, fromDir: string | readonly string[]): boolean;
 /**
  * Filter `registerPaths` to only those whose base package is resolvable
  * from `fromDir`. Emits a `console.warn` for each skipped path —
@@ -45,7 +45,7 @@ export declare function isRegisterPathResolvable(registerPath: string, fromDir:
  * dep, and that polyfill is not a direct/transitive dep, the warn makes
  * the gap visible so the developer can add the dep explicitly.
  */
-export declare function filterResolvableRegisterPaths(registerPaths: Set<string>, fromDir: string): Set<string>;
+export declare function filterResolvableRegisterPaths(registerPaths: Set<string>, fromDir: string | readonly string[]): Set<string>;
 /** Options for {@link writeRegisterInjectFile}. */
 export interface WriteRegisterInjectOptions {
     /**