@gjsify/cli 0.52.0 → 0.54.0

package/lib/commands/blueprint/types.js

@@ -0,0 +1,124 @@
+// `gjsify blueprint types [paths..]` — write the `.d.blp.ts` sidecars ADR 0088 § 4 defines.
+//
+// WHY THE CLI HAS THIS AT ALL, when `@gjsify/vite-plugin-blueprint` already writes a sidecar
+// during `load`: a type-check is not a build. `gjsify check` runs `tsc` and nothing else, so a
+// fresh clone — or a `.blp` whose consumer is being WRITTEN, before any bundle exists — has no
+// sidecar unless something outside the bundler can produce one. This is that something, and it
+// is why the command is usable before `gjsify check` rather than only after a build.
+//
+// `--check` IS FOR CONSUMERS OF THE PUBLISHED CLI. In this repository the sidecar gate is
+// `scripts/check-blueprint-sidecars.mjs`, which CI runs with plain `node` beside the other three
+// Blueprint gates — it has to be, because the CI bootstrap is the PREVIOUS RELEASE's bundle
+// (ADR 0002) and cannot run a command this tree just added. A third-party project has no
+// `scripts/` of ours, so without this flag it could generate sidecars and never hold them.
+// The two share the derivation; what is duplicated is the byte comparison.
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, isAbsolute, join, resolve } from 'node:path';
+import { emitTypedSidecar, parseBlueprint, sidecarPathFor } from '@gjsify/blueprint';
+/** What a walk never descends into: build output, and other projects' sources. */
+const SKIP = new Set(['node_modules', 'dist', 'lib', '.git']);
+/**
+ * Every `.blp` under one path, or the path itself when it names one.
+ *
+ * `statSync` rather than `withFileTypes`, the same choice `utils/build-cache.ts` makes and for
+ * the same reason: this command also runs from the GJS bundle, where `@gjsify/fs` is the readdir
+ * implementation.
+ */
+function blueprintsUnder(path, found) {
+    let entry;
+    try {
+        entry = statSync(path);
+    }
+    catch {
+        return found;
+    }
+    if (!entry.isDirectory()) {
+        if (path.endsWith('.blp'))
+            found.push(path);
+        return found;
+    }
+    for (const name of readdirSync(path).sort()) {
+        if (SKIP.has(name) || name.startsWith('.'))
+            continue;
+        blueprintsUnder(join(path, name), found);
+    }
+    return found;
+}
+export const blueprintTypesCommand = {
+    command: 'types [paths..]',
+    description: 'Generate the `<name>.d.blp.ts` type sidecar for each .blp (ADR 0088), so `import { build }` / ' +
+        '`import { GTypeName }` type-check before anything is built. Defaults to the current directory.',
+    builder: (yargs) => yargs
+        .positional('paths', {
+        description: 'Files or directories to scan for .blp (default: the current directory)',
+        type: 'string',
+        array: true,
+        normalize: true,
+        default: [],
+    })
+        .option('check', {
+        description: 'Write nothing; exit non-zero when a sidecar is missing or stale',
+        type: 'boolean',
+        default: false,
+    })
+        .option('verbose', {
+        description: 'Print every file considered, not only the ones that changed',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (args) => {
+        const given = args.paths ?? [];
+        const roots = (given.length > 0 ? given : ['.']).map((path) => isAbsolute(path) ? path : resolve(process.cwd(), path));
+        const blueprints = [];
+        for (const root of roots)
+            blueprintsUnder(root, blueprints);
+        const outdated = [];
+        let written = 0;
+        for (const file of blueprints) {
+            const sidecar = sidecarPathFor(file);
+            // A parse or derive refusal is NOT caught. It names its file and its line (ADR 0053
+            // clause 3), which is the whole contract, and swallowing it here would report "0
+            // sidecars written" for a `.blp` that cannot compile.
+            // `basename` from `node:path`, which is the host's own answer under the GJS bundle as
+            // well as under node: `@gjsify/node-path` picks its win32 or posix flavour at module
+            // init, and the path here is the user's, on their machine. `@gjsify/blueprint` cannot
+            // take the name itself — see `typed-exports.mjs` § `emitTypedSidecar`.
+            const ast = parseBlueprint(readFileSync(file, 'utf8'), file);
+            const expected = emitTypedSidecar(ast, basename(file));
+            let current;
+            try {
+                current = readFileSync(sidecar, 'utf8');
+            }
+            catch {
+                current = undefined;
+            }
+            if (current === expected) {
+                if (args.verbose)
+                    console.log(`[gjsify blueprint types] current: ${sidecar}`);
+                continue;
+            }
+            if (args.check) {
+                outdated.push(sidecar);
+                continue;
+            }
+            // Only on a difference: an identical rewrite still moves the mtime, which a watcher
+            // reads as a change — the same rule `vite-plugin-blueprint`'s own writer follows.
+            writeFileSync(sidecar, expected, 'utf8');
+            written += 1;
+            console.log(`[gjsify blueprint types] wrote ${sidecar}`);
+        }
+        if (args.check) {
+            if (outdated.length === 0) {
+                console.log(`[gjsify blueprint types] ${blueprints.length} .blp checked, every sidecar current.`);
+                return;
+            }
+            for (const sidecar of outdated)
+                console.error(`[gjsify blueprint types] missing or stale: ${sidecar}`);
+            console.error('[gjsify blueprint types] run without --check to regenerate.');
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`[gjsify blueprint types] ${blueprints.length} .blp scanned, ${written} sidecar(s) written, ` +
+            `${blueprints.length - written} already current.`);
+    },
+};

package/lib/commands/devtools.d.ts

@@ -0,0 +1,21 @@
+import type { Command } from '../types/index.js';
+interface DevtoolsCliOptions {
+    /** Positional 1: the control-plane operation, e.g. `shot`. */
+    operation: string;
+    /** Positional 2+: its arguments — the output path for `shot`, the selector for `find`. */
+    operands?: string[];
+    busName?: string;
+    address?: string;
+    instance?: string;
+    globals?: string;
+    out?: string;
+    timeout: number;
+}
+/**
+ * `gjsify devtools` builds and runs a tiny client over the `org.gjsify.Devtools` control
+ * plane. Subcommands mirror the control-plane methods — `shot`, `find`, `activate`, `key`,
+ * `tree`, `property`, `resize`, `status`, `actions`, `toplevels`, `css`, `gsettings`,
+ * `instances` — so anything a rig does by hand over `gdbus` has a scriptable spelling.
+ */
+export declare const devtoolsCommand: Command<unknown, DevtoolsCliOptions>;
+export {};

package/lib/commands/devtools.js

@@ -0,0 +1,146 @@
+// `gjsify devtools` — drive a running, devtools-enabled gjsify app from a SCRIPT.
+//
+// The peer of `gjsify debug`, not a replacement for it. `debug` speaks MCP over stdio, which
+// is the right shape for an AI agent and the wrong one for a shell script, a Makefile, or a CI
+// step: there is no way to pipe `Screenshot` into a file, because MCP's answer is base64 inside
+// a JSON-RPC frame. So every consumer that wanted a screenshot on disk wrote its own GJS
+// caller to unpack the `ay` variant — and every one of them had to re-decide the same two
+// things this command decides once:
+//
+//   · EMPTY BYTES ARE A FAILURE. `Screenshot` answers `ay[0]` when there is no active window
+//     or the window was never realised (the deliberate `CaptureBlocker` contract). Writing
+//     that produces a 0-byte file named `.png` and a success message.
+//   · THE SIZE COMES FROM THE PNG. `ResizeWindow` answers with the size it was ASKED for, so a
+//     window that ignored the resize still reports success — measured in a consumer: 1280
+//     requested, 1100 in the file, four checks green.
+//
+// Both live in `@gjsify/devtools` (`captureShot`), so a consumer driving the control plane from
+// its own code gets them by importing one function rather than by copying a script.
+//
+// Dispatch is IN-PROCESS like `debug`/`storybook`: the generated entry imports
+// `@gjsify/devtools` + `@gjsify/devtools-mcp` from the CONSUMER's node_modules (so the CLI keeps
+// no dependency on either), is built `--app gjs`, and the RESULT is printed on stdout.
+//
+// WHY A GENERATED BUNDLE AND NOT `gdbus`: the peer transport (macOS/Windows, which have no
+// session bus) is `Gio.DBusServer` + an address file, and `gdbus` cannot speak it. A command
+// that reached the app only over the session bus would be the Linux-only half of a capability
+// the package deliberately made OS-agnostic.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+function readPackage(cwd) {
+    try {
+        return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The generated entry. It takes its options as ARGV rather than baking them in, so one cached
+ * bundle serves every invocation — the command-line flags of a rig change far more often than
+ * the code does, and a rebuild per flag would make `--timeout` cost a full bundle build.
+ *
+ * `system.exit(await …)` is load-bearing rather than decorative: 0 done / 1 the app said no /
+ * 2 the request itself was wrong is the whole contract a shell rig reads out of `$?`, and an
+ * awaited value cannot become a process exit status under GJS. `system.programArgs` are the
+ * user arguments — under `gjs -m bundle.js …` the `-m` and the path are `programInvocationName`,
+ * not args, so nothing has to be sliced off.
+ */
+function generateEntry() {
+    return `// Auto-generated by \`gjsify devtools\` — do not edit by hand.
+import system from 'system';
+
+import { runDevtoolsCli } from '@gjsify/devtools-mcp';
+
+system.exit(await runDevtoolsCli(system.programArgs));
+`;
+}
+/**
+ * `gjsify devtools` builds and runs a tiny client over the `org.gjsify.Devtools` control
+ * plane. Subcommands mirror the control-plane methods — `shot`, `find`, `activate`, `key`,
+ * `tree`, `property`, `resize`, `status`, `actions`, `toplevels`, `css`, `gsettings`,
+ * `instances` — so anything a rig does by hand over `gdbus` has a scriptable spelling.
+ */
+export const devtoolsCommand = {
+    command: 'devtools',
+    description: 'Drive a running devtools-enabled app from a script: capture a screenshot to a file, find a widget, ' +
+        'activate it, send a key. Peer of `gjsify debug`, which speaks MCP for an AI agent.',
+    builder: (yargs) => yargs
+        .positional('operation', {
+        description: 'Control-plane operation: shot | find | activate | key | tree | property | …',
+        type: 'string',
+        demandOption: true,
+    })
+        .positional('operands', {
+        description: 'Subcommand arguments — e.g. the output path for `shot`, the selector for `find`.',
+        type: 'string',
+        array: true,
+    })
+        .option('bus-name', {
+        description: "App DBus base name — the app's Gtk application id (default: gjsify.devtools.busNameBase, " +
+            'then the storybook app-id). Unlike `gjsify debug` there is no derived fallback: the bus name ' +
+            'IS the application id, and guessing it produces a name nothing answers to',
+        type: 'string',
+    })
+        .option('address', {
+        description: 'Peer D-Bus address of the app (unix:path=… / nonce-tcp:…) instead of the session bus — for ' +
+            'macOS/Windows, which have no session bus. Default: GJSIFY_DEVTOOLS_ADDRESS, then the address ' +
+            'file the app publishes, then the session bus',
+        type: 'string',
+    })
+        .option('instance', {
+        description: 'App instance label for a multi-instance app (default: GJSIFY_DEVTOOLS_INSTANCE)',
+        type: 'string',
+    })
+        .option('globals', {
+        description: 'Value for `gjsify build --globals` (default: auto)',
+        type: 'string',
+    })
+        .option('out', {
+        description: 'Output bundle path (default: node_modules/.cache/gjsify-devtools)',
+        type: 'string',
+    })
+        .option('timeout', {
+        description: 'Seconds to keep polling GetStatus for the control plane to answer (default: 30). 0 = do not wait',
+        type: 'number',
+        default: 30,
+    }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const pkg = readPackage(cwd);
+        const config = pkg.gjsify?.devtools ?? {};
+        const busNameBase = args.busName ??
+            config.busNameBase ??
+            pkg.gjsify?.storybook?.applicationId ??
+            pkg.gjsify?.browse?.applicationId;
+        // Asked for BEFORE a bundle is built: without a bus name the build succeeds and the
+        // client then exits 2 having done nothing, which reads like a broken app.
+        if (!busNameBase) {
+            console.error("gjsify devtools: no bus name — the bus name IS the app's Gtk application id, so it cannot be " +
+                'derived from the package name. Pass --bus-name <org.example.App> (the app prints it when it ' +
+                'exports the control plane) or set package.json#gjsify.devtools.busNameBase.');
+            return process.exit(1);
+        }
+        const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify-devtools');
+        mkdirSync(cacheDir, { recursive: true });
+        const entryPath = join(cacheDir, 'entry.ts');
+        const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, 'cli.gjs.mjs');
+        const globals = args.globals ?? 'auto';
+        writeFileSync(entryPath, generateEntry());
+        // stderr for progress — stdout is the RESULT the caller captures.
+        console.error(`[gjsify devtools] bus=${busNameBase}${args.address ? ` address=${args.address}` : ''}${args.instance ? ` instance=${args.instance}` : ''}`);
+        const { runCli } = await import('../cli-app.js');
+        await runCli(['build', entryPath, '--app', 'gjs', '--globals', globals, '--outfile', outPath]);
+        // The RESOLVED values are forwarded, never the raw argv: the child parses its own flags
+        // and knows nothing about package.json, so forwarding only what was typed would drop the
+        // configured bus name on the floor.
+        const forwarded = [args.operation, ...(args.operands ?? []), '--bus-name', busNameBase];
+        if (args.address)
+            forwarded.push('--address', args.address);
+        if (args.instance)
+            forwarded.push('--instance', args.instance);
+        forwarded.push('--timeout', String(args.timeout));
+        const { runGjsBundle } = await import('../utils/run-gjs.js');
+        await runGjsBundle(outPath, forwarded, { completion: 'exit', exitOnSuccess: true });
+    },
+};

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] : [] });
+    },
+};