@gjsify/cli 0.51.1 → 0.53.0

package/lib/commands/webext/subcommands.js

@@ -0,0 +1,204 @@
+// `gjsify webext build|zip|dev` — browser extensions as a project shape
+// (ADR 0077). The command owns the folder around the bundles: one per target,
+// with a manifest composed for that target, pages, icons, public files and
+// locales. The bundles themselves are ordinary `gjsify build --app browser`
+// runs, re-entered in-process like `gjsify dev` does.
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { buildWebext } from '../../utils/webext/build.js';
+import { resolveWebextConfig, selectTargets } from '../../utils/webext/config.js';
+import { defaultDevProfile, resolveWebExt, WEB_EXT_MISSING, webExtRunArgs, } from '../../utils/webext/launch.js';
+function loadConfig(cwd) {
+    const manifest = join(cwd, 'package.json');
+    if (!existsSync(manifest))
+        throw new Error(`gjsify webext: no package.json in ${cwd}.`);
+    return resolveWebextConfig(JSON.parse(readFileSync(manifest, 'utf8')), cwd);
+}
+/** `--define K=V` entries on top of the config's map, the way `gjsify build` spells them. */
+function effectiveDefines(config, flags) {
+    const out = { ...config.define };
+    for (const flag of flags) {
+        const at = flag.indexOf('=');
+        if (at <= 0)
+            throw new Error(`gjsify webext: --define "${flag}" is not KEY=VALUE.`);
+        out[flag.slice(0, at)] = flag.slice(at + 1);
+    }
+    return out;
+}
+/** One bundle, through the ordinary build command in this process. */
+async function bundleInProcess(request) {
+    const { runCli } = await import('../../cli-app.js');
+    const argv = ['build', request.entry, '--app', 'browser', '--format', request.format, '--outfile', request.outfile];
+    for (const [key, value] of Object.entries(request.define))
+        argv.push('--define', `${key}=${value}`);
+    if (!request.minify)
+        argv.push('--no-minify');
+    await runCli(argv);
+}
+const targetOption = {
+    description: 'Build only these targets (default: every target in gjsify.webext.targets).',
+    type: 'string',
+    array: true,
+};
+const outDirOption = {
+    description: 'Output directory (default: gjsify.webext.outDir, else .output).',
+    type: 'string',
+};
+const defineOption = {
+    description: 'Compile-time constant for every bundle, KEY=VALUE (repeatable); wins over gjsify.webext.define.',
+    type: 'string',
+    array: true,
+    default: [],
+};
+async function runBuild(args, zip) {
+    const cwd = process.cwd();
+    const config = loadConfig(cwd);
+    const mode = args.mode === 'development' ? 'development' : 'production';
+    await buildWebext({
+        config,
+        targets: selectTargets(config, args.target),
+        outDir: args.outDir ? resolve(cwd, args.outDir) : config.outDir,
+        mode,
+        define: effectiveDefines(config, args.define),
+        inPlace: false,
+        zip,
+        bundle: bundleInProcess,
+    });
+}
+export const webextBuildCommand = {
+    command: 'build',
+    description: 'Build one extension folder per target: bundles, pages, icons, locales and the manifest.',
+    builder: (yargs) => yargs
+        .option('target', targetOption)
+        .option('out-dir', outDirOption)
+        .option('define', defineOption)
+        .option('mode', {
+        description: 'Passed to the manifest as ctx.mode; development also skips minification.',
+        type: 'string',
+        choices: ['production', 'development'],
+        default: 'production',
+    }),
+    handler: (args) => runBuild(args, false),
+};
+export const webextZipCommand = {
+    command: 'zip',
+    description: 'Production build, then one store-ready <name>-<version>-<target>.zip per target.',
+    builder: (yargs) => yargs.option('target', targetOption).option('out-dir', outDirOption).option('define', defineOption),
+    handler: (args) => runBuild(args, true),
+};
+/** The dev target when none is asked for: the first Firefox target, since web-ext's Firefox driver needs no extra binary. */
+function devTarget(config, requested) {
+    if (requested && requested.length > 1)
+        throw new Error('gjsify webext dev: pass one --target.');
+    const [chosen] = selectTargets(config, requested);
+    if (requested && requested.length === 1)
+        return chosen;
+    return config.targets.find((t) => t.browser === 'firefox') ?? chosen;
+}
+/**
+ * What the loop watches: every top-level directory except `node_modules`,
+ * dot-directories and the output, recursively; the project root itself only
+ * for its own entries (`manifest.ts`, `package.json`); and `watch` extras.
+ */
+function devWatchTargets(config, outDir) {
+    const skip = (name) => name === 'node_modules' || name.startsWith('.');
+    const out = [{ path: config.root, recursive: false }];
+    for (const entry of readdirSync(config.root, { withFileTypes: true })) {
+        const full = join(config.root, entry.name);
+        if (!entry.isDirectory() || skip(entry.name) || full === outDir || outDir.startsWith(full + sep))
+            continue;
+        out.push({ path: full, recursive: true });
+    }
+    for (const extra of config.watch)
+        out.push({ path: extra, recursive: true });
+    return out;
+}
+export const webextDevCommand = {
+    command: 'dev',
+    description: 'Build one target in development mode, launch it in a browser via web-ext, and rebuild in place on change.',
+    builder: (yargs) => yargs
+        .option('target', {
+        ...targetOption,
+        description: 'The target to run (default: the first Firefox target).',
+    })
+        .option('out-dir', { description: 'Output directory (default: <outDir>-dev).', type: 'string' })
+        .option('define', defineOption)
+        .option('launch', {
+        description: 'Start a browser with the extension (--no-launch only rebuilds).',
+        type: 'boolean',
+        default: true,
+    })
+        .option('browser-binary', { description: 'Browser executable web-ext should start.', type: 'string' })
+        .option('profile', {
+        description: 'Browser profile directory (default: $XDG_CACHE_HOME/gjsify/webext/<name>/<target>).',
+        type: 'string',
+    })
+        .option('headless', { description: 'Start the browser without a window.', type: 'boolean', default: false })
+        .option('debounce', { description: 'Quiet window in ms before a rebuild.', type: 'number', default: 200 }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const config = loadConfig(cwd);
+        const target = devTarget(config, args.target);
+        const outDir = args.outDir ? resolve(cwd, args.outDir) : `${config.outDir}-dev`;
+        const define = effectiveDefines(config, args.define);
+        const sourceDir = join(outDir, target.id);
+        let webExt = null;
+        if (args.launch) {
+            webExt = resolveWebExt(cwd);
+            if (webExt === null)
+                throw new Error(WEB_EXT_MISSING);
+        }
+        let browser = null;
+        const stopBrowser = () => {
+            browser?.kill();
+        };
+        // Registered BEFORE the loop's own handlers, which end in process.exit.
+        process.on('SIGINT', stopBrowser);
+        process.on('SIGTERM', stopBrowser);
+        const launch = async () => {
+            if (webExt === null || browser !== null)
+                return;
+            const profile = args.profile ? resolve(cwd, args.profile) : defaultDevProfile(config.name, target);
+            // web-ext creates the profile directory but not its parent (ENOENT on a fresh machine).
+            mkdirSync(dirname(profile), { recursive: true });
+            const argv = webExtRunArgs({
+                sourceDir,
+                target,
+                profile,
+                browserBinary: args.browserBinary,
+                headless: args.headless,
+            });
+            console.log(`[webext] launching ${target.id} with profile ${profile}`);
+            const { spawnSupervised } = await import('../../utils/watch-loop.js');
+            browser = await spawnSupervised(webExt.cmd, argv, webExt.env);
+            browser.on('exit', (code) => {
+                console.log(`[webext] browser closed (${code ?? 0}) — stopping`);
+                process.exit(0);
+            });
+        };
+        const { runWatchLoop } = await import('../../utils/watch-loop.js');
+        await runWatchLoop({
+            dir: cwd,
+            dirLabel: '.',
+            label: 'webext',
+            watch: devWatchTargets(config, outDir),
+            ignore: (changed) => changed === outDir || changed.startsWith(outDir + sep),
+            build: async () => {
+                await buildWebext({
+                    config,
+                    targets: [target],
+                    outDir,
+                    mode: 'development',
+                    define,
+                    inPlace: true,
+                    zip: false,
+                    bundle: bundleInProcess,
+                });
+                // After the first SUCCESSFUL build: web-ext on a folder with no manifest.json exits at once.
+                await launch();
+            },
+            spawnChild: null,
+            debounceMs: args.debounce,
+        });
+    },
+};

package/lib/types/config-data.d.ts

@@ -743,7 +743,7 @@ export interface ShipFlatpakOptions {
  * here (ADR 0024 § 8; the window is `utils/ship/flatpak-config.ts`). They are
  * NOT marked `@deprecated`: for the subcommands in this group they are still
  * the only spelling, and those commands have not moved under `ship` yet
- * (`status/open-todos.md`). Nothing else in this block is deprecated at all —
+ * (`status/open-todos/README.md`). Nothing else in this block is deprecated at all —
  * the {@link AppMetadata} half is a designed alias, not a legacy one.
  */
 export interface ConfigDataFlatpak extends AppMetadata {
@@ -771,7 +771,7 @@ export interface ConfigDataFlatpak extends AppMetadata {
     command?: string;
     /** Finish-args (capabilities). Default depends on `runtime` + `--cli-only`. */
     finishArgs?: string[];
-    /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. `blueprint-compiler` build). */
+    /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. a GI library the runtime lacks). */
     extraModules?: unknown[];
     /**
      * Full replacement for the manifest's `modules` array: used verbatim, with

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

@@ -138,7 +138,7 @@ export declare function buildLauncherShims(opts: {
  * in shell would be a knowingly partial THIRD copy of a two-copy rule, in the
  * one language nothing here type-checks. The REMAINING gap — a host GI stack
  * under a prefix dyld never defaulted to, `/opt/homebrew/lib` on Apple silicon —
- * stays in `status/open-todos.md`, to be closed by teaching such a launcher to
+ * stays in `status/open-todos/README.md`, to be closed by teaching such a launcher to
  * defer to the CLI rather than to re-derive.
  *
  * @param scanRoot Directory whose `node_modules` is globbed at launch time.
@@ -178,7 +178,7 @@ export declare function buildNativeEnvPreamble(scanRoot: string, bakedDirs?: rea
  *
  * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
  * either, so an ARM Mac has that gap with or without gjsify —
- * `status/open-todos.md`.
+ * `status/open-todos/README.md`.
  */
 export declare function dyldFallbackPreamble(platform: string): string;
 /** POSIX `sh` single-quoting for a launcher's target path. */
@@ -263,6 +263,12 @@ export declare function buildShLauncher(targetAbs: string, opts: {
     envPreamble?: string;
     isGjsBundle: boolean;
     nodeFallbackAbs?: string;
+    /**
+     * The gjs to exec — `GJS_CONSOLE` for the CLI's self-shim. NAMED rather
+     * than pathed by default, so a missing interpreter fails the same way on
+     * every OS.
+     */
+    gjs?: string;
 }): string;
 /** True when a bin target is a GJS-runnable bundle rather than a Node script. */
 export declare function isGjsBundlePath(target: string): boolean;

package/lib/utils/bin-shim.js

@@ -349,7 +349,7 @@ function shQuote(s) {
  * in shell would be a knowingly partial THIRD copy of a two-copy rule, in the
  * one language nothing here type-checks. The REMAINING gap — a host GI stack
  * under a prefix dyld never defaulted to, `/opt/homebrew/lib` on Apple silicon —
- * stays in `status/open-todos.md`, to be closed by teaching such a launcher to
+ * stays in `status/open-todos/README.md`, to be closed by teaching such a launcher to
  * defer to the CLI rather than to re-derive.
  *
  * @param scanRoot Directory whose `node_modules` is globbed at launch time.
@@ -449,7 +449,7 @@ export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
  *
  * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
  * either, so an ARM Mac has that gap with or without gjsify —
- * `status/open-todos.md`.
+ * `status/open-todos/README.md`.
  */
 export function dyldFallbackPreamble(platform) {
     if (platform !== 'darwin')
@@ -556,15 +556,16 @@ export function pickBinMap(pkgName, pkgJson) {
  */
 export function buildShLauncher(targetAbs, opts) {
     const preamble = opts.isGjsBundle ? (opts.envPreamble ?? '') : '';
+    const gjs = opts.gjs === undefined || opts.gjs === 'gjs' ? 'gjs' : shQuote(opts.gjs);
     if (opts.isGjsBundle && opts.nodeFallbackAbs !== undefined) {
         // The preamble only ever configures the GI search path, so it stays
         // inside the gjs branch — exporting it around a Node exec would be
         // inert at best and misleading to anyone reading the shim.
-        return (`#!/bin/sh\nif command -v gjs >/dev/null 2>&1; then\n${preamble}` +
-            `exec gjs -m ${shQuote(targetAbs)} "$@"\nfi\n` +
+        return (`#!/bin/sh\nif command -v ${gjs} >/dev/null 2>&1; then\n${preamble}` +
+            `exec ${gjs} -m ${shQuote(targetAbs)} "$@"\nfi\n` +
             `exec node ${shQuote(opts.nodeFallbackAbs)} "$@"\n`);
     }
-    const exec = opts.isGjsBundle ? `exec gjs -m ${shQuote(targetAbs)} "$@"` : `exec ${shQuote(targetAbs)} "$@"`;
+    const exec = opts.isGjsBundle ? `exec ${gjs} -m ${shQuote(targetAbs)} "$@"` : `exec ${shQuote(targetAbs)} "$@"`;
     return `#!/bin/sh\n${preamble}${exec}\n`;
 }
 /** True when a bin target is a GJS-runnable bundle rather than a Node script. */

package/lib/utils/bundle-inputs.d.ts

@@ -0,0 +1,84 @@
+import type { RolldownPluginOption } from 'rolldown';
+/**
+ * Bumped when the shape changes; a manifest of any other version is ignored.
+ *
+ * v2 adds `watchList`. A v1 manifest says nothing about whether the engine that
+ * wrote it could report a watch list at all, and the safe reading of "unknown"
+ * is "do not trust it": see {@link readBundleInputs}.
+ */
+export declare const BUNDLE_INPUTS_VERSION = 2;
+/** What a manifest says, once parsed. */
+export interface BundleInputs {
+    inputs: string[];
+    /** `false` = this bundle's build could not see plugin-read inputs at all. */
+    watchList: boolean;
+}
+/** The manifest that belongs to `outfile`. */
+export declare function bundleInputsPath(outfile: string): string;
+export interface BundleInputsRecorder {
+    /** Pass to the bundler as a plugin; it observes, it never transforms. */
+    plugin: RolldownPluginOption;
+    /**
+     * The build's own watch list — what the engine reports, which is its module
+     * set PLUS everything a plugin declared with `this.addWatchFile`. That is
+     * the only account of a file the bundler never turned into a module: the
+     * CSS plugin follows a stylesheet's `@import` chain with its own `readFile`,
+     * and no graph mentions the imported file.
+     */
+    addWatchFiles(watch: {
+        files: readonly string[];
+        reportedByEngine: boolean;
+    }): void;
+    /** The recorded inputs so far: sorted, deduplicated, existing files only. */
+    inputs(): string[];
+    /**
+     * Persist the manifest beside `outfile`, so the NEXT freshness check can
+     * judge against the same set. Never throws: a manifest that cannot be
+     * written must not fail a test run — it degrades the check to the package
+     * walk, and says so.
+     */
+    write(): void;
+}
+/**
+ * A plugin that records every module the build transforms, plus the writer for
+ * the manifest.
+ *
+ * `transform` rather than a graph API (`getModuleIds`/`getModuleInfo`) because
+ * it is the one hook both engines run and the native bridge translates
+ * (`bundler-pick.ts` picks it verbatim). Every module that reaches the
+ * transform stage was LOADED from disk, so the observed set is what the build
+ * read — the modules it then tree-shook away are still inputs of the next
+ * build, which is the direction that errs safely.
+ *
+ * The observation is KEPT alongside {@link BundleInputsRecorder.addWatchFiles}
+ * rather than replaced by it, and neither engine is the reason: the native
+ * engine has no watch list to hand over (`BundleResult` carries warnings and
+ * output only, and its JS context had no `addWatchFile` at all until
+ * `rolldown-native` grew one), so on GJS the observed set is the only account
+ * of the modules; on npm the watch list is a superset of it. Union: the cost of
+ * a redundant path is a `stat`, the cost of a missing one is a stale green.
+ */
+export declare function createBundleInputsRecorder(outfile: string): BundleInputsRecorder;
+/**
+ * The inputs recorded for `outfile` by the build that wrote it, or `null` when
+ * there is none to trust — never written, unreadable, or written by another
+ * version of this shape. `null` is the fallback the caller must handle, not an
+ * error: a bundle built by an older CLI, or copied in from elsewhere, has no
+ * manifest and is judged by the package walk alone.
+ */
+export declare function readBundleInputs(outfile: string): BundleInputs | null;
+/**
+ * Newest mtime (ms) among recorded inputs, or 0 for an empty set.
+ *
+ * A recorded input that has since VANISHED counts as CHANGED, exactly as the
+ * package walk counts one that vanished mid-walk: an input we cannot read is
+ * not evidence that the artifact is current. A workspace-package source deleted
+ * while the bundle still imports it is precisely that case, and skipping it
+ * would rerun a bundle built from a file that no longer exists.
+ *
+ * Safe only because the toolchain's own scratch is never RECORDED
+ * ({@link isToolchainScratch}): the globals-inject stub and the cached plugin
+ * bundles are written and deleted between builds, and treating their absence as
+ * a change would rebuild on every run, forever.
+ */
+export declare function newestBundleInputMtimeMs(inputs: readonly string[]): number;

package/lib/utils/bundle-inputs.js

@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: MIT
+// The SECOND half of "what are this bundle's build inputs" — what the BUNDLER
+// read, recorded at build time beside the bundle it produced.
+//
+// `package-inputs.ts` answers the other half by walking the package, and that
+// walk cannot see outside the package. A consumer's test bundle routinely reads
+// outside it: a workspace package reached through `node_modules/<name>` — a
+// SYMLINK into a sibling directory — is a file the build read and the walk
+// never enumerates. An edit there left `gjsify test` judging a fresh bundle and
+// rerunning it: a stale GREEN, the worst kind of wrong, and the only remedy a
+// consumer had was `rm -rf dist`.
+//
+// The set is recorded from the bundler's own module graph rather than guessed
+// from a directory list: a bare specifier's resolution is known to the bundler
+// and to nobody else, and a list of "likely dirs" is wrong for every layout
+// nobody anticipated — the same failure `package-inputs.ts` documents twice.
+//
+// TWO halves, because the bundler is not the only reader: a `transform`
+// observer sees every MODULE, and the engine's watch list carries what a plugin
+// read and declared itself (a stylesheet's `@import` chain is read by
+// `gjsify-css-as-string`, not by the bundler, so no graph names it). Neither
+// engine reports both, so the recorder takes the union. Deciding freshness
+// stays cheap: the manifest is written once per build and read as `stat` calls.
+//
+// `package-inputs.ts` is not replaced by this. Its walk answers "what MAY this
+// package's build read", which covers a file the current build does not import
+// yet; this answers "what DID this build read", which reaches outside the
+// package. The union is the honest input set, and both halves must exist.
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+/**
+ * Bumped when the shape changes; a manifest of any other version is ignored.
+ *
+ * v2 adds `watchList`. A v1 manifest says nothing about whether the engine that
+ * wrote it could report a watch list at all, and the safe reading of "unknown"
+ * is "do not trust it": see {@link readBundleInputs}.
+ */
+export const BUNDLE_INPUTS_VERSION = 2;
+/** The manifest that belongs to `outfile`. */
+export function bundleInputsPath(outfile) {
+    return `${outfile}.inputs.json`;
+}
+/**
+ * A module id as a path, or `null` when it names no file we can stat.
+ *
+ * A query or a hash is PART OF THE ID, not of the path: `@scope/pkg/x.css?raw`
+ * and `main-window.blp?shared-tree` (the blueprint plugin's shared-tree exit)
+ * both stat as ENOENT, and dropping the id silently would drop the file with
+ * it. `\0` is the bundler's virtual-module marker — no file, ever.
+ */
+function idToPath(id) {
+    if (id === '' || id.startsWith('\0'))
+        return null;
+    const cut = id.search(/[?#]/);
+    if (cut === -1)
+        return id;
+    const stripped = id.slice(0, cut);
+    // The fallback is not a nicety: `#` is LEGAL in a Linux filename, and
+    // `a#b.blp` is that file's whole name. Stripping turned it into `a`, which
+    // does not exist, and the input was dropped. So the unstripped id gets its
+    // turn — and when neither is a file, `inputs()` drops it as before.
+    return isFile(stripped) ? stripped : id;
+}
+function isFile(abs) {
+    try {
+        return statSync(abs).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Files the TOOLCHAIN writes and deletes between builds, which therefore must
+ * never enter the input set.
+ *
+ * Not a filter on staleness but on membership: a vanished recorded input forces
+ * a rebuild (see {@link newestBundleInputMtimeMs}), so recording the
+ * globals-inject stub — `node_modules/.cache/gjsify/auto-globals-<hash>.mjs`,
+ * rewritten per build and DELETED when its config changes — would rebuild every
+ * run, forever. The same directory holds the cached GJS plugin bundles, which
+ * carry their own freshness rule (`bundleFileForGjsCached`).
+ *
+ * **Not a `tmpdir()` test**, which is the obvious wrong answer and the one this
+ * started as: the stub is written into the project's own cache directory
+ * (`utils/scan-globals.ts`), never to a temp dir, while a PROJECT under
+ * `/tmp` is a project — a CI job, a container, this suite's own fixtures. A
+ * freshness check that goes blind in those trees is the defect being fixed,
+ * reached from the other side.
+ */
+function isToolchainScratch(abs) {
+    return abs.includes(`${sep}node_modules${sep}.cache${sep}`);
+}
+/**
+ * The resolution files of the package a recorded input belongs to: the nearest
+ * `package.json` above it, and the `tsconfig.json` beside it when there is one.
+ *
+ * Neither is ever a module. A workspace package reached through a symlink
+ * contributes its files, but a `package.json#exports` edit — which moves what
+ * every bare specifier in the app resolves to — or a `tsconfig.json` that turns
+ * on a `paths` mapping changes the output with no file of its own in the graph.
+ * Per package, deduplicated, so the walk is a handful of stats however many
+ * modules that package contributed.
+ */
+function resolutionFilesFor(abs) {
+    const found = [];
+    for (let dir = dirname(abs);; dir = dirname(dir)) {
+        const manifest = join(dir, 'package.json');
+        if (existsSync(manifest)) {
+            found.push(manifest);
+            const tsconfig = join(dir, 'tsconfig.json');
+            if (existsSync(tsconfig))
+                found.push(tsconfig);
+            return found;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return found;
+    }
+}
+/**
+ * A plugin that records every module the build transforms, plus the writer for
+ * the manifest.
+ *
+ * `transform` rather than a graph API (`getModuleIds`/`getModuleInfo`) because
+ * it is the one hook both engines run and the native bridge translates
+ * (`bundler-pick.ts` picks it verbatim). Every module that reaches the
+ * transform stage was LOADED from disk, so the observed set is what the build
+ * read — the modules it then tree-shook away are still inputs of the next
+ * build, which is the direction that errs safely.
+ *
+ * The observation is KEPT alongside {@link BundleInputsRecorder.addWatchFiles}
+ * rather than replaced by it, and neither engine is the reason: the native
+ * engine has no watch list to hand over (`BundleResult` carries warnings and
+ * output only, and its JS context had no `addWatchFile` at all until
+ * `rolldown-native` grew one), so on GJS the observed set is the only account
+ * of the modules; on npm the watch list is a superset of it. Union: the cost of
+ * a redundant path is a `stat`, the cost of a missing one is a stale green.
+ */
+export function createBundleInputsRecorder(outfile) {
+    const seen = new Set();
+    // Sticky, and pessimistic: ONE pass without a watch list is enough to know
+    // the build cannot see a plugin-read input, and the artifact must not be
+    // judged fresh on the strength of the passes that could.
+    let watchList = true;
+    const record = (raw) => {
+        const abs = idToPath(raw);
+        if (abs !== null)
+            seen.add(abs);
+    };
+    const plugin = {
+        name: 'gjsify:bundle-inputs',
+        transform(_code, id) {
+            record(id);
+            return undefined;
+        },
+    };
+    const inputs = () => {
+        const out = [];
+        const packages = new Set();
+        for (const abs of seen) {
+            let isFile;
+            try {
+                isFile = statSync(abs).isFile();
+            }
+            catch {
+                continue;
+            }
+            if (!isFile || isToolchainScratch(abs))
+                continue;
+            out.push(abs);
+            // `resolutionFilesFor` walks to the package root; one call per
+            // DIRECTORY keeps a 1000-module bundle from walking 1000 times.
+            const dir = dirname(abs);
+            if (packages.has(dir))
+                continue;
+            packages.add(dir);
+            for (const meta of resolutionFilesFor(abs))
+                out.push(meta);
+        }
+        return [...new Set(out)].sort();
+    };
+    return {
+        plugin,
+        addWatchFiles(watch) {
+            if (!watch.reportedByEngine)
+                watchList = false;
+            for (const id of watch.files)
+                record(id);
+        },
+        inputs,
+        write() {
+            const path = bundleInputsPath(outfile);
+            const manifest = { version: BUNDLE_INPUTS_VERSION, inputs: inputs(), watchList };
+            const tmp = `${path}.tmp`;
+            try {
+                mkdirSync(dirname(path), { recursive: true });
+                // Rename, not write: a manifest is read by the NEXT process, and
+                // a half-written one is a parse error there — which reads as "no
+                // manifest" and silently degrades the check to the package walk.
+                writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+                renameSync(tmp, path);
+            }
+            catch (err) {
+                try {
+                    rmSync(tmp, { force: true });
+                }
+                catch {
+                    // Nothing left to clean up — the write never got that far.
+                }
+                console.warn(`[gjsify test] could not record the build inputs beside ${path} (${err.message}) — ` +
+                    'the next run judges freshness by the package walk alone, which cannot see outside this package.');
+            }
+        },
+    };
+}
+/**
+ * The inputs recorded for `outfile` by the build that wrote it, or `null` when
+ * there is none to trust — never written, unreadable, or written by another
+ * version of this shape. `null` is the fallback the caller must handle, not an
+ * error: a bundle built by an older CLI, or copied in from elsewhere, has no
+ * manifest and is judged by the package walk alone.
+ */
+export function readBundleInputs(outfile) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(bundleInputsPath(outfile), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (parsed?.version !== BUNDLE_INPUTS_VERSION || !Array.isArray(parsed.inputs))
+        return null;
+    return {
+        inputs: parsed.inputs.filter((abs) => typeof abs === 'string'),
+        // v2 only, so a missing flag cannot be v2 — but the pessimistic reading
+        // is kept anyway: a manifest that does not vouch for its engine's watch
+        // list is not one to judge freshness on.
+        watchList: parsed.watchList === true,
+    };
+}
+/**
+ * Newest mtime (ms) among recorded inputs, or 0 for an empty set.
+ *
+ * A recorded input that has since VANISHED counts as CHANGED, exactly as the
+ * package walk counts one that vanished mid-walk: an input we cannot read is
+ * not evidence that the artifact is current. A workspace-package source deleted
+ * while the bundle still imports it is precisely that case, and skipping it
+ * would rerun a bundle built from a file that no longer exists.
+ *
+ * Safe only because the toolchain's own scratch is never RECORDED
+ * ({@link isToolchainScratch}): the globals-inject stub and the cached plugin
+ * bundles are written and deleted between builds, and treating their absence as
+ * a change would rebuild on every run, forever.
+ */
+export function newestBundleInputMtimeMs(inputs) {
+    let newest = 0;
+    for (const abs of inputs) {
+        try {
+            const { mtimeMs } = statSync(abs);
+            if (mtimeMs > newest)
+                newest = mtimeMs;
+        }
+        catch {
+            return Number.POSITIVE_INFINITY;
+        }
+    }
+    return newest;
+}