@gjsify/cli 0.52.0 → 0.53.0

package/lib/commands/exec.js

@@ -0,0 +1,208 @@
+// `gjsify exec [--runtime <r>] [--rebuild] <bin> [args…]` — run an installed npm bin
+// on the runtime gjsify itself is running on (ADR 0076).
+//
+//   node / bun / deno host → the bin's npm entry, unchanged, on that runtime.
+//   gjs host               → the package's own `gjsify.bin` bundle if it ships one,
+//                            else the npm entry REBUILT `--app gjs` (Node APIs mapped
+//                            to `@gjsify/*`, `.node` addons routed through
+//                            `@gjsify/napi`), cached by content, run with `gjs -m`.
+//
+// A failed rebuild is an error that carries the bundler's diagnostics. There is no
+// silent fallback to `node` under GJS: the host may have none, and a tool that
+// "worked" on a runtime the user did not ask for hides exactly the gap this command
+// exists to expose. `--runtime node` is the explicit, documented escape hatch.
+import { existsSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
+import { ExecBinNotFoundError, ExecPlanError, entryWithinPackage, execArtifactPath, execCacheKey, execCacheRoot, findProjectLockfile, hashFile, planExec, resolveExecBin, splitExecArgv, } from '../utils/exec-bin.js';
+import { cliPackageDir, cliVersion } from '../utils/publish-headers.js';
+import { runGjsBundle } from '../utils/run-gjs.js';
+import { runRuntimeBundle } from '../utils/run-node.js';
+export class ExecRebuildError extends Error {
+    constructor(bin, entry, cause, verbose) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`gjsify exec: rebuilding "${bin.binName}" (${bin.pkgName}@${bin.pkgVersion}) for GJS failed.\n` +
+            `  entry: ${entry}\n` +
+            'Nothing was run — gjsify exec never falls back to another runtime on its own. To run it on Node ' +
+            `explicitly: \`gjsify exec --runtime node ${bin.binName}\`.\n` +
+            // The warnings were silenced for the rebuild; an error can point back at one
+            // (UNRESOLVED_IMPORT behind a load-check failure), so say how to get them.
+            (verbose ? '' : `Re-run with \`gjsify exec --verbose ${bin.binName}\` for the bundler's warnings.\n`) +
+            `Bundler diagnostics:\n${detail}`, { cause });
+        this.name = 'ExecRebuildError';
+    }
+}
+/** The nearest `node_modules` walking up from `start`, or null. */
+function nearestNodeModules(start) {
+    let dir = resolve(start);
+    for (;;) {
+        const candidate = join(dir, 'node_modules');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Rebuild `entry` as a `--app gjs` bundle and return its path, reusing a cached one
+ * whose content key still matches (see `execCacheKey`).
+ *
+ * Written to a private temp directory and RENAMED into place, so two concurrent
+ * `gjsify exec` runs never read a half-written bundle: the loser of the rename race
+ * uses the winner's artifact, which has the same key and therefore the same inputs.
+ */
+async function rebuildForGjs(bin, entry, opts) {
+    const nodeModules = bin.nodeModules ?? nearestNodeModules(process.cwd()) ?? join(bin.pkgDir, 'node_modules');
+    const lockfile = findProjectLockfile(dirname(nodeModules));
+    const key = execCacheKey({
+        pkgName: bin.pkgName,
+        pkgVersion: bin.pkgVersion,
+        entry: entryWithinPackage(bin, entry),
+        cliVersion: cliVersion(),
+        lockfileHash: lockfile ? hashFile(lockfile) : null,
+    });
+    const outfile = execArtifactPath(execCacheRoot(nodeModules), bin, entry, bin.installed ? key : 'local');
+    const reusable = bin.installed && !opts.rebuild;
+    if (reusable && existsSync(outfile)) {
+        if (opts.verbose)
+            console.error(`gjsify exec: reusing ${outfile}`);
+        return outfile;
+    }
+    console.error(`gjsify exec: rebuilding ${bin.pkgName}@${bin.pkgVersion} "${bin.binName}" for GJS…`);
+    const finalDir = dirname(outfile);
+    const tmpDir = `${finalDir}.tmp-${process.pid.toString(16)}-${Date.now().toString(16)}`;
+    const tmpOut = join(tmpDir, basename(outfile));
+    try {
+        const { BuildAction } = await import('../actions/build.js');
+        await BuildAction.bundleFileForGjs(entry, tmpOut, {
+            verbose: opts.verbose,
+            // A bin is executed, never imported.
+            preserveDefaultExport: false,
+            // An installed dependency's `import.meta.url` is rewritten per module by
+            // the node_modules path rewriter; the project's OWN bin is not under
+            // node_modules, so its entry keeps its source URL the way `--node-script`
+            // does it.
+            ...(bin.installed ? {} : { define: { 'import.meta.url': JSON.stringify(pathToFileURL(entry).href) } }),
+            // The CLI is bundling on the user's behalf: the project installed wxt,
+            // not `@gjsify/fs`, so the polyfills come from beside the running CLI.
+            toolchainAnchor: BuildAction.runningCliFile(),
+            // Every polyfill of a rebuilt bin comes from the toolchain, so the per-import
+            // "did not resolve from the project" notice is the rule here, not a symptom —
+            // dozens of lines ahead of `--version`. Warnings only: a failing build still
+            // rejects with its diagnostics, and `--verbose` shows them all.
+            ...(opts.verbose ? {} : { logLevel: 'silent' }),
+        });
+    }
+    catch (err) {
+        rmSync(tmpDir, { recursive: true, force: true });
+        throw new ExecRebuildError(bin, entry, err, opts.verbose);
+    }
+    if (reusable && existsSync(outfile)) {
+        // A concurrent run with the same key finished first; its artifact is ours.
+        rmSync(tmpDir, { recursive: true, force: true });
+        return outfile;
+    }
+    // Whatever sits under this name now is stale: a forced rebuild, or a directory
+    // left by an older layout without the file this one expects.
+    rmSync(finalDir, { recursive: true, force: true });
+    try {
+        renameSync(tmpDir, finalDir);
+    }
+    catch (err) {
+        // Lost the race to a concurrent run with the same key — its bundle is ours.
+        rmSync(tmpDir, { recursive: true, force: true });
+        if (!existsSync(outfile))
+            throw err;
+    }
+    pruneStaleArtifacts(dirname(finalDir), bin, basename(finalDir));
+    return outfile;
+}
+/**
+ * Drop earlier artifacts of the SAME package version: a rebuild under a new CLI or a
+ * moved lockfile leaves the old key behind, and nothing else would ever read it.
+ * Best-effort — housekeeping must not fail the run it follows.
+ */
+function pruneStaleArtifacts(cacheRoot, bin, keep) {
+    const prefix = `${bin.pkgName}@${bin.pkgVersion}`.replace(/[^a-zA-Z0-9._@-]/g, '_');
+    let names;
+    try {
+        names = readdirSync(cacheRoot);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name === keep || !name.startsWith(`${prefix}-`) || name.includes('.tmp-'))
+            continue;
+        rmSync(join(cacheRoot, name), { recursive: true, force: true });
+    }
+}
+export const execCommand = {
+    command: 'exec <entries..>',
+    description: 'Run an installed npm bin on the runtime gjsify runs on: `gjsify exec [--runtime gjs|node|bun|deno] [--rebuild] [--verbose] <bin> [args…]`. ' +
+        'On Node/Bun/Deno the bin runs unchanged; on GJS it is rebuilt `--app gjs` once, cached under node_modules/.cache/gjsify/exec/, and run with gjs. ' +
+        "Options go BEFORE the bin; everything after it is the bin's own.",
+    builder: (yargs) => yargs
+        .positional('entries', {
+        description: 'gjsify exec options, then the bin name and its arguments.',
+        type: 'string',
+        array: true,
+    })
+        // The bin owns its whole flag namespace, as with `gjsify env`/`run`:
+        // `gjsify exec prettier --version` must reach prettier.
+        .version(false)
+        .help(false)
+        .parserConfiguration({
+        'populate--': true,
+        'parse-positional-numbers': false,
+        'unknown-options-as-args': true,
+    }),
+    handler: async (args) => {
+        let invocation;
+        let bin;
+        let plan;
+        try {
+            invocation = splitExecArgv(args.entries ?? [], doubleDashArgs(args));
+            bin = resolveExecBin(invocation.bin, process.cwd());
+            plan = planExec(bin, invocation.runtime ?? hostRuntime());
+        }
+        catch (err) {
+            if (err instanceof ExecBinNotFoundError) {
+                console.error(err.message);
+                // The shell's "command not found", which is what this is.
+                return process.exit(127);
+            }
+            if (err instanceof ExecPlanError) {
+                console.error(err.message);
+                return process.exit(1);
+            }
+            throw err;
+        }
+        const launch = {
+            completion: 'exit',
+            exitOnSuccess: true,
+            quiet: !invocation.verbose,
+            quietExit: true,
+        };
+        if (plan.kind === 'direct') {
+            await runRuntimeBundle(plan.runtime, plan.file, invocation.args, launch);
+            return;
+        }
+        if (plan.kind === 'gjs-bundle') {
+            await runGjsBundle(plan.file, invocation.args, launch);
+            return;
+        }
+        const bundle = await rebuildForGjs(bin, plan.entry, {
+            rebuild: invocation.rebuild,
+            verbose: invocation.verbose,
+        });
+        // The rebuild took its polyfills from beside the CLI, so their native prebuilds
+        // (typelibs, shared libraries) are found there too.
+        const cliDir = cliPackageDir();
+        await runGjsBundle(bundle, invocation.args, { ...launch, nativeRoots: cliDir ? [cliDir] : [] });
+    },
+};

package/lib/commands/foreach.js

@@ -9,7 +9,7 @@
 // matching yarn's interactive flow. Exit code is non-zero if any child
 // process failed; first failure's stderr is forwarded.
 import { spawnToCompletion } from '../utils/spawn.js';
-import { readFileSync, readdirSync } from 'node:fs';
+import { collectDescendants } from '../utils/process-table.js';
 import { cpus } from 'node:os';
 import { affectedClosure, buildDependencyGraph, discoverWorkspaces, filterWorkspaces, topologicalSort, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
@@ -34,101 +34,6 @@ const KILL_GRACE_MS = 5_000;
 // killed child whose grandchildren inherit (and keep open) the stdio pipe
 // never emits 'close', so we must not wait on it unboundedly.
 const DRAIN_DEADLINE_MS = 15_000;
-// Read the direct child PIDs of `pid` from /proc/<pid>/task/*/children
-// (Linux, CONFIG_PROC_CHILDREN — standard on every mainstream kernel). When
-// the per-task children files are unavailable, fall back to one full
-// /proc/*/stat scan building a ppid→children map. Both paths use only
-// `node:fs` reads, so they behave identically under Node and GJS
-// (@gjsify/fs) — unlike a process-group kill, which GJS cannot issue
-// (`@gjsify/process.kill` shells out `kill <sig> <pid>` where a negative
-// PID parses as an option, and Gio.Subprocess has no group-signal API).
-function readDirectChildren(pid) {
-    let taskIds;
-    try {
-        taskIds = readdirSync(`/proc/${pid}/task`);
-    }
-    catch {
-        // Process already gone (common) or /proc unavailable.
-        return null;
-    }
-    const kids = [];
-    let readAny = false;
-    for (const tid of taskIds) {
-        try {
-            const data = readFileSync(`/proc/${pid}/task/${tid}/children`, 'utf-8');
-            readAny = true;
-            for (const tok of data.trim().split(/\s+/)) {
-                const n = Number(tok);
-                if (Number.isInteger(n) && n > 0)
-                    kids.push(n);
-            }
-        }
-        catch {
-            // Thread vanished mid-walk, or kernel lacks CONFIG_PROC_CHILDREN.
-        }
-    }
-    return readAny ? kids : null;
-}
-// Fallback: scan every /proc/<pid>/stat once and build ppid → children.
-// O(#processes) small reads — fine for the rare kill path.
-function buildPpidMap() {
-    const map = new Map();
-    let entries = [];
-    try {
-        entries = readdirSync('/proc');
-    }
-    catch {
-        return map;
-    }
-    for (const entry of entries) {
-        const pid = Number(entry);
-        if (!Number.isInteger(pid) || pid <= 0)
-            continue;
-        try {
-            const stat = readFileSync(`/proc/${pid}/stat`, 'utf-8');
-            // comm (field 2) may contain spaces/parens — parse after last ')'.
-            const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
-            const ppid = Number(rest[1]);
-            if (!Number.isInteger(ppid) || ppid <= 0)
-                continue;
-            const siblings = map.get(ppid);
-            if (siblings)
-                siblings.push(pid);
-            else
-                map.set(ppid, [pid]);
-        }
-        catch {
-            // Process exited between readdir and read — fine.
-        }
-    }
-    return map;
-}
-// Snapshot every transitive descendant of `pid`, breadth-first (so
-// reversing the list yields deepest-first order for signalling).
-function collectDescendants(pid) {
-    const result = [];
-    const seen = new Set([pid]);
-    const queue = [pid];
-    let ppidMap = null;
-    while (queue.length > 0) {
-        const cur = queue.shift();
-        let kids = readDirectChildren(cur);
-        if (kids === null) {
-            // children files unreadable — use (and lazily build) the
-            // full-scan fallback for this and subsequent levels.
-            ppidMap ??= buildPpidMap();
-            kids = ppidMap.get(cur) ?? [];
-        }
-        for (const kid of kids) {
-            if (seen.has(kid))
-                continue;
-            seen.add(kid);
-            result.push(kid);
-            queue.push(kid);
-        }
-    }
-    return result;
-}
 // Signal an already-collected descendant set deepest-first, then the direct
 // child itself. Snapshot-then-signal (not signal-while-walking) so killing
 // the parent can't orphan grandchildren before we enumerated them. The
@@ -157,7 +62,10 @@ function killActiveChildren() {
     // The direct child is `npm run <script>` — killing only it leaves the
     // npm-spawned shell → gjs/node build grandchildren alive (observed: an
     // orphaned gjs bundler at 100% CPU for 19+ min after a fail-fast kill).
-    // So terminate the whole process TREE of each child via a /proc walk.
+    // So terminate the whole process TREE of each child — walked by
+    // `utils/process-table.ts` (procfs on Linux, the OS process list elsewhere).
+    // A process-group kill would be simpler and GJS cannot issue one:
+    // Gio.Subprocess has no group-signal API.
     const termSnapshots = new Map();
     for (const child of activeChildren) {
         const descendants = child.pid ? collectDescendants(child.pid) : [];

package/lib/commands/format.js

@@ -7,9 +7,10 @@
 // optionalDependency, keeping the Node-free runtime promise for the bundled
 // CLI intact (the formatter runs in dev/CI, not in shipped GJS apps).
 //
-// oxfmt formats JS/TS (+TOML) only. CSS/JSON formatting that the old Biome
-// toolchain handled is intentionally DROPPED in the oxc migration — no other
-// formatter is wired up for those file types.
+// oxfmt formats JS/TS, JSON, TOML, CSS and GraphQL in both builds; the
+// languages it hands to its Prettier host (Markdown, HTML, Vue, YAML, …) are
+// napi-only — the native GJS build drops them, which the skip scan below
+// reports.
 //
 // A BARE `gjsify format` WRITES. `--check` is the read-only CI mode and
 // `--no-write` the read-only local one; there is no flagless report mode.
@@ -24,11 +25,12 @@
 // tuned for GJS/GNOME projects (4-space, single-quote, printWidth 120,
 // trailing-comma all, semicolons always, arrow parens always).
 import { existsSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { OxcNotFoundError, findOxfmtConfig, loadOxfmtTemplate, loadOxlintTemplate, printOxcNotFound, runOxfmt, setOxcExitCode, } from '../utils/oxc-resolve.js';
+import { relative, resolve } from 'node:path';
+import { OxcNotFoundError, findOxfmtConfig, loadOxfmtTemplate, loadOxlintTemplate, printOxcNotFound, runOxfmt, setOxcExitCode, shouldUseNativeOxfmt, } from '../utils/oxc-resolve.js';
+import { scanForNativeSkips } from '../utils/native-skip-scan.js';
 export const formatCommand = {
     command: 'format [paths..]',
-    description: 'Format JS/TS source files via oxfmt (CSS/JSON formatting is not supported).',
+    description: 'Format source files via oxfmt (Markdown/YAML/HTML/Vue need the napi build).',
     builder: (yargs) => {
         return yargs
             .positional('paths', {
@@ -90,6 +92,24 @@ export const formatCommand = {
         if (configPath)
             oxfmtArgs.push('--config', resolve(configPath));
         oxfmtArgs.push(...paths);
+        // Under GJS the native oxfmt formats everything but the files napi oxfmt
+        // hands to its Prettier host (Markdown, HTML, Vue, YAML, …), and it drops
+        // those without a word. `--check` FAILS on them, so a green check that
+        // checked nothing is impossible — asked about exactly the files oxfmt
+        // itself would walk with this config, never `node_modules` or ignored ones.
+        if (args.check && (await shouldUseNativeOxfmt())) {
+            const scan = scanForNativeSkips(paths, cwd, { configPath });
+            if (scan.skipped.length > 0) {
+                const list = scan.skipped.map((f) => `  ${relative(cwd, f) || f}`).join('\n');
+                console.error(`[gjsify format] ERROR: ${scan.skipped.length} file(s) skipped — ` +
+                    `the native oxfmt (GJS) has no Prettier host for them (Markdown/HTML/Vue/YAML/…):\n` +
+                    `${list}\n` +
+                    `  The format check is INCOMPLETE. Run \`gjsify format --check\` under Node to check these ` +
+                    `files, or add them to \`ignorePatterns\`.`);
+                setOxcExitCode(1);
+                return;
+            }
+        }
         try {
             const code = await runOxfmt(oxfmtArgs, { cwd, verbose: args.verbose });
             setOxcExitCode(code);

package/lib/commands/index.d.ts

@@ -1,6 +1,8 @@
 export * from './build.js';
 export * from './clear.js';
 export * from './copy.js';
+export * from './env.js';
+export * from './exec.js';
 export * from './test.js';
 export * from './run.js';
 export * from './info.js';
@@ -40,3 +42,4 @@ export * from './storybook.js';
 export * from './dev.js';
 export * from './debug.js';
 export * from './browse.js';
+export { webextCommand } from './webext/index.js';

package/lib/commands/index.js

@@ -1,6 +1,8 @@
 export * from './build.js';
 export * from './clear.js';
 export * from './copy.js';
+export * from './env.js';
+export * from './exec.js';
 export * from './test.js';
 export * from './run.js';
 export * from './info.js';
@@ -40,3 +42,4 @@ export * from './storybook.js';
 export * from './dev.js';
 export * from './debug.js';
 export * from './browse.js';
+export { webextCommand } from './webext/index.js';

package/lib/commands/install.d.ts

@@ -83,8 +83,8 @@ export interface EnsureProjectGjsEngineDeps {
  *
  * The engine is an OPTIONAL PEER of `@gjsify/cli` on purpose — a plain
  * `npm install @gjsify/cli` on Node must not fetch prebuilds — but nobody resolves
- * it for a project: npm 7+ skips optional peers and the native backend does not
- * resolve `peerDependencies` at all. Under GJS there is no npm `rolldown`
+ * it for a project: npm 7+ skips optional peers and so does the native backend
+ * (it installs REQUIRED peers only). Under GJS there is no npm `rolldown`
  * fallback, so `gjsify build` had nothing to load.
  *
  * Four conditions, and (b) is the one worth reading:

package/lib/commands/install.js

@@ -10,7 +10,7 @@
 // `node_modules/` and symlinks `workspace:` refs to their source. Members with
 // conflicting ranges of the same external still share ONE hoisted copy; the
 // resolver warns naming both ranges, both requesters and the winner (per-member
-// dedup is the open Phase D.8 item in status/open-todos.md).
+// dedup is the open Phase D.8 item in status/open-todos/README.md).
 //
 // Concurrency (ADR 0001): every prefix mutation runs under a per-prefix
 // cross-process lock (utils/install-lock.ts), so installs into different
@@ -641,7 +641,7 @@ function syncLockfileRequested(cwd, specs) {
  *
  * Hoisting is deliberately minimal — members with conflicting ranges of the same
  * dep share one hoisted copy and the resolver warns. Per-member dedup and nested
- * `node_modules/` are the open Phase D.8 item in status/open-todos.md.
+ * `node_modules/` are the open Phase D.8 item in status/open-todos/README.md.
  */
 async function workspaceInstall(cwd, args, signal) {
     // Held for the WHOLE flow: bin shims, workspace symlinks and the external
@@ -1272,7 +1272,7 @@ async function installGlobalAndLink(specs, opts) {
         // A global install of `@gjsify/cli` must also lay down the GJS bundler engine
         // + the sibling format/CSS bridges. They are OPTIONAL PEERS of the CLI (so a
         // plain `npm install @gjsify/cli` on Node does not force a prebuild) and the
-        // native backend does not resolve peerDependencies at all, so without this
+        // native backend, like npm ≥ 7, installs required peers only, so without this
         // they never arrive and `gjsify build` hard-fails under GJS with "no usable
         // bundler engine". Pinned to the CLI's resolved version so they move in
         // lockstep with the bundle; a platform with no published prebuild warns.
@@ -1333,8 +1333,8 @@ function reportLinkedBins(created, binDir) {
  *
  * The engine is an OPTIONAL PEER of `@gjsify/cli` on purpose — a plain
  * `npm install @gjsify/cli` on Node must not fetch prebuilds — but nobody resolves
- * it for a project: npm 7+ skips optional peers and the native backend does not
- * resolve `peerDependencies` at all. Under GJS there is no npm `rolldown`
+ * it for a project: npm 7+ skips optional peers and so does the native backend
+ * (it installs REQUIRED peers only). Under GJS there is no npm `rolldown`
  * fallback, so `gjsify build` had nothing to load.
  *
  * Four conditions, and (b) is the one worth reading:

package/lib/commands/self-update.js

@@ -27,6 +27,7 @@ import { fetchPackument } from '@gjsify/npm-registry';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 import { classifyInstall } from '../utils/install-provenance.js';
 import { defaultGlobalLayout, globalLayoutIsDefault, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, resolveBinOnPath, } from '../utils/install-global.js';
+import { pathWithoutSelfShim } from '../utils/gjsify-shim.js';
 import { resolveHostPlatform } from '../utils/platform-check.js';
 import { pruneAfterInstall } from '../utils/prune-prefix.js';
 const PACKAGE_NAME = '@gjsify/cli';
@@ -210,7 +211,7 @@ export const selfUpdateCommand = {
             const verdict = verifyPathResolution({
                 binName: BIN_NAME,
                 binDir: layout.binDir,
-                resolvedBin: resolveBinOnPath(BIN_NAME),
+                resolvedBin: resolveBinOnPath(BIN_NAME, { pathValue: pathWithoutSelfShim() }),
                 runningVersion: currentVersion,
                 targetVersion: target,
             });

package/lib/commands/test.d.ts

@@ -10,16 +10,25 @@ interface TestOptions {
 }
 export declare const testCommand: Command<unknown, TestOptions>;
 /**
- * True when `outfile` is at least as new as every build input of the package
- * at `cwd`.
+ * True when `outfile` is at least as new as every input of the build that
+ * wrote it.
  *
- * The set is {@link packageBuildInputs}, the same one the build cache hashes.
- * It used to be `dirname(entry)` — `tests/` for any package whose suite lives
- * there, so `src/**` was never walked: a change to the code UNDER TEST left
- * the bundle "fresh" and `gjsify test` reran the previous build and reported
- * on it. That went both ways inside one dependency bump — a green run
- * measuring a version that was no longer installed, then a red one after the
- * source had already been repaired (#1651).
+ * The set is the union of two answers, because neither covers the question
+ * alone: {@link packageBuildInputs} — what may this PACKAGE's build read, the
+ * same walk the build cache hashes — and the manifest the build itself wrote
+ * beside `outfile` ({@link readBundleInputs}), what this build DID read. The
+ * second is what reaches a workspace package through a `node_modules` symlink
+ * into a sibling directory: the package walk is blind to it by construction,
+ * so an edit there left the bundle "fresh" and the run reported on code that
+ * was no longer on disk — a stale green, worse than a slow build. The first is
+ * what the walk alone never managed: it was `dirname(entry)`, `tests/` for any
+ * package whose suite lives there, so `src/**` was never seen and `gjsify test`
+ * reran the previous build and reported on it, in both directions inside one
+ * dependency bump (#1651).
+ *
+ * A missing manifest is NOT an answer: it is the pre-recorder shape, and the
+ * package walk then decides alone — never weaker than before, and the next
+ * build writes one.
  *
  * `outdir` is subtracted as this command's own output; `entry` is added
  * because `--entry ../shared/test.mts` may point outside the package.

package/lib/commands/test.js

@@ -7,6 +7,7 @@
 // exit codes.
 import { existsSync, statSync } from 'node:fs';
 import { join, resolve, relative, sep } from 'node:path';
+import { newestBundleInputMtimeMs, readBundleInputs, createBundleInputsRecorder } from '../utils/bundle-inputs.js';
 import { newestDepSignalMtimeMs, newestInputMtimeMs, packageBuildInputs } from '../utils/package-inputs.js';
 import { isRuntimeAvailable, RUNTIMES } from '../utils/runtimes.js';
 import { nodeBinary } from '../utils/run-node.js';
@@ -180,13 +181,39 @@ async function buildTestBundle(entry, outfile, runtime, verbose) {
     // bundler.output.file from the surrounding project don't redirect the
     // bundle elsewhere.
     configData.library = { ...configData.library };
+    // Record what this build READ, so the next `isFresh` can judge against the
+    // bundle's real dependencies rather than this package's tree. A recorder
+    // rides the same plugin chain a user's `bundler.plugins` entry does, and
+    // the auto-globals pre-build pass therefore feeds it too — a superset of
+    // the final graph, which errs towards a rebuild and never towards a stale
+    // green. Appended last so it observes whatever the earlier hooks loaded.
+    const recorder = createBundleInputsRecorder(outfile);
     configData.bundler = {
         ...configData.bundler,
         input: [entry],
         output: { ...configData.bundler?.output, file: outfile },
+        plugins: [...(configData.bundler?.plugins ?? []), recorder.plugin],
     };
     const action = new BuildAction(configData);
-    await action.start({ app: runtime, library: false });
+    // `onWatchFiles` is the half the transform observer cannot reach: a file a
+    // plugin read itself and declared (a stylesheet's `@import` chain). The
+    // recorder takes the union — npm reports its module set too, the native
+    // engine reports nothing but the declarations, and each engine alone would
+    // leave a class of input unrecorded.
+    await action.start({
+        app: runtime,
+        library: false,
+        onWatchFiles: (watch) => recorder.addWatchFiles(watch),
+    });
+    // Written AFTER the build resolves, and that ordering is the whole of what
+    // a failure leaves behind: a build that fails BEFORE writing an artifact
+    // (parse, resolve, a plugin hook) throws out of `start()` and never reaches
+    // this line, so the previous manifest still describes the previous bundle.
+    // A failure in a POST-WRITE gate is the other case and is not ours to
+    // paper over: `actions/build.ts` has already replaced the bundle, the
+    // manifest is rewritten beside it, and both then describe the same build —
+    // the next run re-runs the failing bundle rather than the one before it.
+    recorder.write();
 }
 /** Run a single test bundle and reject on non-zero exit. */
 async function runTestBundle(outfile, runtime) {
@@ -206,16 +233,25 @@ async function runTestBundle(outfile, runtime) {
         throw new Error(`node exited with ${describeExit(result)}`);
 }
 /**
- * True when `outfile` is at least as new as every build input of the package
- * at `cwd`.
+ * True when `outfile` is at least as new as every input of the build that
+ * wrote it.
+ *
+ * The set is the union of two answers, because neither covers the question
+ * alone: {@link packageBuildInputs} — what may this PACKAGE's build read, the
+ * same walk the build cache hashes — and the manifest the build itself wrote
+ * beside `outfile` ({@link readBundleInputs}), what this build DID read. The
+ * second is what reaches a workspace package through a `node_modules` symlink
+ * into a sibling directory: the package walk is blind to it by construction,
+ * so an edit there left the bundle "fresh" and the run reported on code that
+ * was no longer on disk — a stale green, worse than a slow build. The first is
+ * what the walk alone never managed: it was `dirname(entry)`, `tests/` for any
+ * package whose suite lives there, so `src/**` was never seen and `gjsify test`
+ * reran the previous build and reported on it, in both directions inside one
+ * dependency bump (#1651).
  *
- * The set is {@link packageBuildInputs}, the same one the build cache hashes.
- * It used to be `dirname(entry)` — `tests/` for any package whose suite lives
- * there, so `src/**` was never walked: a change to the code UNDER TEST left
- * the bundle "fresh" and `gjsify test` reran the previous build and reported
- * on it. That went both ways inside one dependency bump — a green run
- * measuring a version that was no longer installed, then a red one after the
- * source had already been repaired (#1651).
+ * A missing manifest is NOT an answer: it is the pre-recorder shape, and the
+ * package walk then decides alone — never weaker than before, and the next
+ * build writes one.
  *
  * `outdir` is subtracted as this command's own output; `entry` is added
  * because `--entry ../shared/test.mts` may point outside the package.
@@ -229,7 +265,16 @@ export function isFresh(outfile, entry, cwd, outdir) {
         const outdirRel = relative(cwd, outdir).split(sep).join('/');
         if (outdirRel !== '' && !outdirRel.startsWith('../'))
             extraOutputs.push(outdirRel);
-        const newest = Math.max(newestInputMtimeMs(packageBuildInputs(cwd, { extraOutputs })), statSync(entry).mtimeMs, 
+        const bundleInputs = readBundleInputs(outfile);
+        // A build whose engine could report NO watch list never entered a file
+        // only a PLUGIN read — a stylesheet's `@import` chain, an inlined
+        // `readFileSync` — into the set below, and no mtime comparison can
+        // recover it. Judging such a bundle fresh IS the stale green, so the
+        // answer is no: rebuild, on every run, and say why. `bundler-pick.ts`
+        // prints the skew once; the manifest carries it across processes.
+        if (bundleInputs !== null && !bundleInputs.watchList)
+            return false;
+        const newest = Math.max(newestInputMtimeMs(packageBuildInputs(cwd, { extraOutputs })), bundleInputs === null ? 0 : newestBundleInputMtimeMs(bundleInputs.inputs), statSync(entry).mtimeMs, 
         // A dependency bump changes no file in the package — and that is
         // the shape #1651 was found in. `node_modules` is far too large
         // to stat per run, so the lockfile stands in for it.

package/lib/commands/tsc.js

@@ -128,10 +128,10 @@ export const tscCommand = {
         // Run upstream `typescript` under Node — the Node fallback.
         //
         // `nodeBinary()`, NEVER a bare `process.execPath`: under the GJS bundle
-        // `process.execPath` is the GJS interpreter (`/proc/self/exe` →
-        // `gjs-console`), so `spawn(process.execPath, [tsc.js])` hands
-        // TypeScript's CommonJS CLI to GJS, which dies on the first `module`
-        // reference — or, where execPath resolves to a gjsify launcher instead,
+        // `process.execPath` is the GJS interpreter (`hostExecPath()`:
+        // `/proc/self/exe` on Linux, the PATH lookup of `gjs` on macOS), so
+        // `spawn(process.execPath, [tsc.js])` hands TypeScript's CommonJS CLI to
+        // GJS, which dies on the first `module` reference — or, where execPath resolves to a gjsify launcher instead,
         // re-executes the CLI with the tsc entry as an unknown argument. Both
         // were reached from a COLD tree: `@gjsify/tsc`'s `dist/tsc.gjs.mjs` is a
         // build output, and `build:infra` builds `@gjsify/create-app` (its first