@gjsify/cli 0.51.1 → 0.53.0

package/lib/commands/affected-script-refs.js

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: MIT
+// Who READS a root `scripts/*` file — the edge the `affected` closure walk has no way to see.
+//
+// WHY THIS EXISTS. `scripts/` belongs to no workspace, so every change there used to land in
+// `unmatched` and buy a FULL `main.yml` run. Measured over the 60 PRs before #1774: 33 went
+// full for that reason alone, and most of them touched only a website or gallery gate that
+// `audit-runtimes.yml` runs and `main.yml` never opens. The full run was never wrong — it was
+// the classifier saying "I cannot tell" about a question the tree answers: a script matters to
+// `main.yml` exactly when something `main.yml` builds or runs names it.
+//
+// So a changed root script is REPLACED by the files that name it, and those go through the
+// ordinary IGNORE → GLOBAL → workspace mapping. A spec that imports it seeds its workspace; a
+// workspace build script that runs it seeds that workspace; a sibling workflow that runs it is
+// IGNOREd like the workflow itself; `.github/actions`, `tests/e2e/**` or anything else the
+// classifier does not model still forces the full run. A script that names another script
+// hands the question on (`affected-classify.ts` walks that recursively).
+//
+// THE MATCH IS DELIBERATELY LOOSE, because it may only fail towards running MORE. It is the
+// script's file name (stem plus a JS/TS extension, `.d.mts` included), not an import
+// statement: `join(root, 'scripts', 'x.mjs')` and `node scripts/x.mjs` are both reads, and a
+// parser for "is this an import" would miss the first. The price is that an error message
+// naming a script counts as a reader too — measured, that turns some script changes back
+// into full runs, which is the direction this is allowed to be wrong in. Comment lines are
+// dropped first; without that, the prose cross-references in this repository chain every
+// script to every other one and the whole mechanism collapses back into "run everything".
+//
+// TWO READERS ARE NARROWED, and each narrowing is a claim about `main.yml`'s shape:
+//   · `main.yml` itself counts only from a job that (transitively) `needs: changes`. A job
+//     that does not — `tree-checks` today — runs on every PR whatever this classifier says,
+//     so a script it runs cannot be skipped by anything decided here.
+//   · the root `package.json` counts only when the script is named outside `scripts`, or by
+//     a lifecycle/build/test entry, or by an entry another root script or a gated `main.yml`
+//     job runs. The `check:*` conveniences that only a person or a sibling workflow invokes
+//     are not `main.yml` inputs.
+//
+// NOT SEEN, stated so nobody reads this as more: a reader that builds the file name at run
+// time, and a tool that walks `scripts/` as a directory. The second shape exists
+// (`generate-status.mjs`, `check-comment-budget.mjs`) but only in jobs outside `main.yml`'s
+// gated set. Push-to-main and the nightly still run the FULL suite.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { join, posix } from 'node:path';
+const MAIN_WORKFLOW = '.github/workflows/main.yml';
+const ROOT_MANIFEST = 'package.json';
+/** Larger files are data (lockfile, generated corpora), never a script's reader. */
+const MAX_TEXT_BYTES = 2 * 1024 * 1024;
+/**
+ * A root package.json entry whose run is part of installing, building or testing the tree.
+ * Not `check:*`: those are single-gate conveniences (`node scripts/check-….mjs`), and the
+ * one `main.yml` does run (`check:examples`) is caught by name in the workflow instead.
+ */
+const LIFECYCLE_SCRIPT = /^(pre|post)?(install|prepare|build|test)(:|$)/;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Comment lines out: `#` for YAML, shell, git and Docker files, `//` + block-comment lines
+ * for everything else. `#` is not stripped from JS, where a line may open with a private
+ * field.
+ */
+function stripCommentLines(path, text) {
+    const hashComments = /\.(ya?ml|sh|bash|py|toml)$|(^|\/)\.git[a-z]*$|Dockerfile$/.test(path);
+    const comment = hashComments ? /^\s*#/ : /^\s*(\/\/|\/\*|\*)/;
+    return text
+        .split('\n')
+        .filter((line) => !comment.test(line))
+        .join('\n');
+}
+/**
+ * The file-name pattern for a script: `adwaita-elements.mjs` is also read as
+ * `adwaita-elements.d.mts` (a TS import of the `.mjs` resolves to its declaration) and a
+ * `.d.mts` change is read through its `.mjs`. The leading boundary excludes `-` so
+ * `value-types.mjs` does not match `generate-value-types.mjs`.
+ */
+export function scriptNamePattern(scriptPath) {
+    // A git path, always `/`-separated whatever the host: POSIX basename, not the host's.
+    const base = posix.basename(scriptPath);
+    const js = /^(.*?)(\.d)?\.[mc]?[jt]sx?$/.exec(base);
+    const tail = js ? `${escapeRe(js[1])}(\\.d)?\\.[mc]?[jt]sx?\\b` : `${escapeRe(base)}\\b`;
+    return new RegExp(`(^|[^\\w.-])${tail}`);
+}
+/**
+ * Jobs of `main.yml` that depend, directly or through `needs:`, on the `changes` job — the
+ * ones the classifier can switch off. Comment lines are already gone: `setup`'s comments
+ * NAME `needs.changes.outputs.*`, and counting that made `tree-checks` look gated.
+ */
+function gatedJobs(lines) {
+    const needs = new Map();
+    const mentionsChanges = new Set();
+    for (const { job, text } of lines) {
+        if (!job)
+            continue;
+        if (!needs.has(job))
+            needs.set(job, []);
+        const n = /^ {4}needs:\s*\[(.*)\]/.exec(text) ?? /^ {4}needs:\s*([A-Za-z0-9_-]+)\s*$/.exec(text);
+        if (n)
+            needs.set(job, n[1]
+                .split(',')
+                .map((d) => d.trim())
+                .filter(Boolean));
+        // A block-list `needs:` is a spelling this parse does not read, so the job counts
+        // as gated: misreading one here could only ever skip less.
+        if (/needs\.changes\b/.test(text) || /^ {4}needs:\s*$/.test(text))
+            mentionsChanges.add(job);
+    }
+    const gated = new Set(['changes', ...mentionsChanges]);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const [j, deps] of needs) {
+            if (!gated.has(j) && deps.some((d) => gated.has(d))) {
+                gated.add(j);
+                grew = true;
+            }
+        }
+    }
+    // `changes` itself runs the classifier; it is not switched off by it.
+    gated.delete('changes');
+    return gated;
+}
+function workflowLines(text) {
+    const lines = text.split('\n');
+    const out = [];
+    let job;
+    let inJobs = false;
+    for (const line of lines) {
+        if (/^jobs:\s*$/.test(line))
+            inJobs = true;
+        else if (/^\S/.test(line))
+            inJobs = false;
+        const key = inJobs ? /^ {2}([A-Za-z0-9_-]+):\s*$/.exec(line) : null;
+        if (key)
+            job = key[1];
+        if (/^\s*#/.test(line))
+            continue;
+        out.push({ job: inJobs ? job : undefined, text: line });
+    }
+    return out;
+}
+/**
+ * Build the reader lookup over `texts` (repo-relative path → raw content). Pure: the command
+ * feeds it `git ls-files`, the spec feeds it a fixture map.
+ */
+export function buildScriptReferrers(texts) {
+    const stripped = new Map();
+    for (const [path, text] of texts) {
+        if (path === MAIN_WORKFLOW || path === ROOT_MANIFEST)
+            continue;
+        stripped.set(path, stripCommentLines(path, text));
+    }
+    const workflowText = texts.get(MAIN_WORKFLOW);
+    const workflow = workflowText === undefined ? [] : workflowLines(workflowText);
+    const gated = gatedJobs(workflow);
+    // Top-level workflow keys (`env:`) reach every job, so they count as gated too.
+    const gatedWorkflowNames = (re) => workflow.some((l) => re.test(l.text) && (l.job === undefined || gated.has(l.job)));
+    let manifest;
+    const manifestText = texts.get(ROOT_MANIFEST);
+    if (manifestText !== undefined)
+        manifest = JSON.parse(manifestText);
+    const manifestReads = (re) => {
+        if (!manifest)
+            return false;
+        for (const [k, v] of Object.entries(manifest)) {
+            if (k !== 'scripts' && re.test(JSON.stringify(v)))
+                return true;
+        }
+        const scripts = manifest.scripts ?? {};
+        for (const [key, value] of Object.entries(scripts)) {
+            if (!re.test(value))
+                continue;
+            if (LIFECYCLE_SCRIPT.test(key))
+                return true;
+            const byName = new RegExp(`(^|[\\s"'])${escapeRe(key)}($|[\\s"'&;|])`);
+            if (Object.entries(scripts).some(([other, v]) => other !== key && byName.test(v)))
+                return true;
+            if (gatedWorkflowNames(byName))
+                return true;
+        }
+        return false;
+    };
+    return (scriptPath) => {
+        const re = scriptNamePattern(scriptPath);
+        const readers = [];
+        for (const [path, text] of stripped) {
+            if (path !== scriptPath && re.test(text))
+                readers.push(path);
+        }
+        if (gatedWorkflowNames(re))
+            readers.push(MAIN_WORKFLOW);
+        if (manifestReads(re))
+            readers.push(ROOT_MANIFEST);
+        return readers.sort();
+    };
+}
+/**
+ * Every tracked text file under `rootDir`, for {@link buildScriptReferrers}. Throws when git
+ * cannot list the tree — the caller then classifies without the lookup, which is the old,
+ * conservative behaviour (a root script lands in `unmatched`).
+ */
+export function readTrackedTexts(rootDir) {
+    const r = spawnSync('git', ['ls-files', '-z'], { cwd: rootDir, encoding: 'utf8' });
+    if (r.status !== 0)
+        throw new Error(`git ls-files failed (${r.status}): ${String(r.stderr).trim()}`);
+    const texts = new Map();
+    for (const path of r.stdout.split('\0')) {
+        if (!path || path.startsWith('refs/'))
+            continue;
+        const abs = join(rootDir, path);
+        // A gitlink (submodule) is listed but is a directory; a deleted-but-staged path is
+        // listed and absent. Neither can name a script.
+        const st = statSync(abs, { throwIfNoEntry: false });
+        if (!st?.isFile() || st.size > MAX_TEXT_BYTES)
+            continue;
+        const text = readFileSync(abs, 'utf8');
+        if (text.includes('\0'))
+            continue;
+        texts.set(path, text);
+    }
+    return texts;
+}

package/lib/commands/affected.js

@@ -58,6 +58,7 @@ import { appendFileSync } from 'node:fs';
 import { readStdinLines } from '../utils/stdin.js';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { classifyAndExpand } from './affected-classify.js';
+import { buildScriptReferrers, readTrackedTexts } from './affected-script-refs.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 export const affectedCommand = {
     command: 'affected',
@@ -92,15 +93,36 @@ export const affectedCommand = {
         const changedFiles = args['changed-from-stdin']
             ? readStdinLines()
             : runGitDiff(rootDir, args.base ?? 'origin/main', args.head ?? 'HEAD');
-        const result = classifyAndExpand(workspaces, changedFiles);
+        const result = classifyAndExpand(workspaces, changedFiles, scriptReadersFor(rootDir, changedFiles));
         emit(args.format, result);
     },
 };
+/**
+ * The root-script reader lookup, built only when the diff has a root script in it — reading
+ * the tree costs a second or two and most diffs do not need it. `undefined` when git cannot
+ * list the tree (a fixture without a repository): the classifier then treats a root script
+ * as it always did, as `unmatched`, which forces the full run.
+ */
+function scriptReadersFor(rootDir, changedFiles) {
+    if (!changedFiles.some((f) => /^scripts\/[^/]+$/.test(f.replace(/\\/g, '/'))))
+        return undefined;
+    try {
+        return buildScriptReferrers(readTrackedTexts(rootDir));
+    }
+    catch (err) {
+        process.stderr.write(`gjsify affected: cannot index the tree for script readers (${String(err)}); root scripts stay unmatched\n`);
+        return undefined;
+    }
+}
 function runGitDiff(cwd, base, head) {
     // `base...head` lists changed paths on `head` relative to the MERGE-BASE, which
     // matches what a GitHub PR diff shows and survives stacked PRs without picking up
     // commits from base.
-    const r = spawnSync('git', ['diff', '--name-only', `${base}...${head}`], {
+    // `--no-renames`: with rename detection on (git's default since 2.9), a pure move lists
+    // only the DESTINATION. Moving `packages/node/os/src/x.ts` to `docs/x.ts` then reads as
+    // a docs-only change and skips every suite that would have seen `@gjsify/os` break.
+    // Without detection a move is a delete plus an add, and the deleted side seeds as usual.
+    const r = spawnSync('git', ['diff', '--no-renames', '--name-only', `${base}...${head}`], {
         cwd,
         encoding: 'utf8',
     });

package/lib/commands/env.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from '../types/index.js';
+interface EnvOptions {
+    entries: string[];
+}
+export interface EnvInvocation {
+    assignments: Array<[name: string, value: string]>;
+    command: string;
+    args: string[];
+}
+/**
+ * Split env(1)-style argv: leading `NAME=VALUE` words, then the command and its
+ * arguments. A later `X=y` is an ARGUMENT, as in env(1). `null` when no command
+ * follows the assignments.
+ */
+export declare function splitEnvArgv(argv: readonly string[]): EnvInvocation | null;
+/**
+ * Rejoin the argv yargs split at the first `--`. One AFTER the command belongs to
+ * the command, as in env(1) (`gjsify env A=1 node x.mjs -- --flag` hands node the
+ * `--`); only one BEFORE it separates (`gjsify env A=1 -- node …`).
+ */
+export declare function joinEnvArgv(entries: readonly string[], tail: readonly string[]): string[];
+/**
+ * The child's environment: `base` with `assignments` applied.
+ *
+ * On win32 names are case-insensitive, and a spread of `process.env` keeps the
+ * stored spelling (`Path`). Assigning `PATH` beside it would hand the child two
+ * variables for one name, so any differently-cased key is dropped first.
+ */
+export declare function applyAssignments(base: NodeJS.ProcessEnv, assignments: ReadonlyArray<readonly [string, string]>, platform?: string): NodeJS.ProcessEnv;
+export declare const envCommand: Command<unknown, EnvOptions>;
+export {};

package/lib/commands/env.js

@@ -0,0 +1,114 @@
+// `gjsify env NAME=VALUE… <command> [args…]` — env(1) for package scripts.
+//
+// npm runs package scripts through `cmd.exe` on Windows, and cmd has no form of
+// the POSIX `NAME=value command` prefix: `LC_ALL=C node --test` fails there with
+// "'LC_ALL' is not recognized as an internal or external command" (measured on
+// the win11-gjsify VM for `@gjsify/node-gi`'s `npm test`). The prefix cannot be
+// rewritten into a cmd spelling either, because `set NAME=value && …` leaks into
+// every later clause and keeps the trailing space in the value.
+//
+// Same answer as `gjsify clear`/`gjsify copy` gave `rm -rf`/`cp -r`: one portable
+// command, so the fix is prepending `gjsify env` rather than a platform branch per
+// script. `portable-scripts` rejects the bare prefix so it stays fixed.
+//
+// The child is spawned through `spawnToCompletion`, so a bare `.cmd` shim (`npm`,
+// `tsc`) resolves on Windows the same way it does for every other CLI spawn.
+import { doubleDashArgs } from '../utils/double-dash-args.js';
+import { describeExit, spawnToCompletion } from '../utils/spawn.js';
+/** POSIX `name=value` assignment word: a portable identifier, then `=`. */
+const ASSIGNMENT_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/s;
+/**
+ * Split env(1)-style argv: leading `NAME=VALUE` words, then the command and its
+ * arguments. A later `X=y` is an ARGUMENT, as in env(1). `null` when no command
+ * follows the assignments.
+ */
+export function splitEnvArgv(argv) {
+    const assignments = [];
+    let i = 0;
+    for (; i < argv.length; i++) {
+        const m = ASSIGNMENT_RE.exec(argv[i]);
+        if (!m)
+            break;
+        assignments.push([m[1], m[2]]);
+    }
+    if (i >= argv.length)
+        return null;
+    return { assignments, command: argv[i], args: argv.slice(i + 1) };
+}
+/**
+ * Rejoin the argv yargs split at the first `--`. One AFTER the command belongs to
+ * the command, as in env(1) (`gjsify env A=1 node x.mjs -- --flag` hands node the
+ * `--`); only one BEFORE it separates (`gjsify env A=1 -- node …`).
+ */
+export function joinEnvArgv(entries, tail) {
+    if (tail.length === 0)
+        return [...entries];
+    return splitEnvArgv(entries) ? [...entries, '--', ...tail] : [...entries, ...tail];
+}
+/**
+ * The child's environment: `base` with `assignments` applied.
+ *
+ * On win32 names are case-insensitive, and a spread of `process.env` keeps the
+ * stored spelling (`Path`). Assigning `PATH` beside it would hand the child two
+ * variables for one name, so any differently-cased key is dropped first.
+ */
+export function applyAssignments(base, assignments, platform = process.platform) {
+    const env = { ...base };
+    for (const [name, value] of assignments) {
+        if (platform === 'win32') {
+            for (const key of Object.keys(env)) {
+                if (key !== name && key.toLowerCase() === name.toLowerCase())
+                    delete env[key];
+            }
+        }
+        env[name] = value;
+    }
+    return env;
+}
+export const envCommand = {
+    command: 'env <entries..>',
+    description: 'Run a command with extra environment variables: `gjsify env NAME=VALUE… <command> [args…]`. Portable replacement for the POSIX `NAME=value command` prefix, which cmd.exe cannot run.',
+    builder: (yargs) => yargs
+        .positional('entries', {
+        description: '`NAME=VALUE` assignments, then the command and its arguments.',
+        type: 'string',
+        array: true,
+    })
+        // The command owns its whole flag namespace, as with `gjsify run`:
+        // `gjsify env LC_ALL=C node --test --help` must reach node.
+        .version(false)
+        .help(false)
+        .parserConfiguration({
+        'populate--': true,
+        'parse-positional-numbers': false,
+        'unknown-options-as-args': true,
+    }),
+    handler: async (args) => {
+        const invocation = splitEnvArgv(joinEnvArgv(args.entries ?? [], doubleDashArgs(args)));
+        if (!invocation) {
+            console.error('gjsify env: no command given. Usage: gjsify env NAME=VALUE… <command> [args…]');
+            return process.exit(1);
+        }
+        const { assignments, command, args: childArgs } = invocation;
+        let result;
+        try {
+            result = await spawnToCompletion(command, childArgs, {
+                completion: 'exit',
+                env: applyAssignments(process.env, assignments),
+            });
+        }
+        catch (err) {
+            const e = err;
+            console.error(e.code === 'ENOENT'
+                ? `gjsify env: \`${command}\` not found on PATH`
+                : `gjsify env: ${command}: ${e.message}`);
+            return process.exit(127);
+        }
+        if (result.code !== 0) {
+            if (result.code === null)
+                console.error(`gjsify env: ${command} ended by ${describeExit(result)}`);
+            return process.exit(result.code ?? 1);
+        }
+        return process.exit(0);
+    },
+};

package/lib/commands/exec.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from '../types/index.js';
+import { type ResolvedBin } from '../utils/exec-bin.js';
+interface ExecOptions {
+    entries?: string[];
+}
+export declare class ExecRebuildError extends Error {
+    constructor(bin: ResolvedBin, entry: string, cause: unknown, verbose: boolean);
+}
+export declare const execCommand: Command<unknown, ExecOptions>;
+export {};

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/flatpak/diff.js

@@ -125,10 +125,16 @@ async function loadFlathubSource(args, sourceIndex) {
     const sources = modules[0]?.sources ?? [];
     if (sources.length === 0)
         return null;
-    const idx = sourceIndex ?? sources.findIndex((s) => s?.type === 'git');
+    const idx = sourceIndex ?? sources.findIndex((s) => isSourceObject(s) && s.type === 'git');
     if (idx < 0 || idx >= sources.length)
         return null;
-    return sources[idx] ?? null;
+    // A `--source-index` aimed at a file reference has no tag to compare, which
+    // the caller already reports as a manifest without one.
+    const entry = sources[idx];
+    return isSourceObject(entry) ? entry : null;
+}
+function isSourceObject(entry) {
+    return typeof entry === 'object' && entry !== null;
 }
 async function fetchFlathubManifest(flathubRepo, appId, verbose) {
     for (const branch of ['master', 'main']) {

package/lib/commands/flatpak/init.js

@@ -153,7 +153,10 @@ export const flatpakInitCommand = {
         //   `flatpak.extraModules` — prepended to the meson default.
         //                            Right shape for meson-built GTK apps
         //                            that want a few extra sibling modules
-        //                            (e.g. blueprint-compiler).
+        //                            (e.g. a GI library the runtime lacks). NOT
+        //                            blueprint-compiler: ADR 0053 clause 5 parses
+        //                            `.blp` in the bundler, so a manifest that
+        //                            builds it builds a tool nothing runs.
         const modules = [];
         if (flatpak.modules?.length) {
             modules.push(...flatpak.modules);