@gjsify/cli 0.52.0 → 0.53.0

package/lib/actions/build.d.ts

@@ -1,6 +1,7 @@
 import type { ConfigData } from '../types/index.js';
 import type { App } from '@gjsify/rolldown-plugin-gjsify';
 import type { RolldownOutput } from 'rolldown';
+import { type RunBundleOptions } from '../bundler-pick.js';
 export declare class BuildAction {
     readonly configData: ConfigData;
     constructor(configData?: ConfigData);
@@ -186,11 +187,31 @@ export declare class BuildAction {
          */
         resolveFromToolchain?: boolean;
     }): Promise<string>;
+    /**
+     * The uncached half of {@link bundleFileForGjsCached}: bundle `inputPath` to
+     * `outfile` as one self-contained `--app gjs` module. `gjsify exec` calls it
+     * directly because it keys its artifacts by CONTENT (package version, lockfile,
+     * CLI version — `utils/exec-bin.ts`) rather than by mtime.
+     */
+    static bundleFileForGjs(inputPath: string, outfile: string, opts: {
+        verbose?: boolean;
+        define?: Record<string, string>;
+        preserveDefaultExport?: boolean;
+        globals?: string;
+        excludeGlobals?: string[];
+        /** The running CLI's file, or null — see `resolveFromToolchain` above; the CALLER decides. */
+        toolchainAnchor?: string | null;
+        /** `silent` drops warnings, never errors — errors reject the build either way. */
+        logLevel?: 'silent';
+    }): Promise<void>;
+    /** The running CLI's own file — the toolchain anchor `gjsify exec` hands {@link bundleFileForGjs}. */
+    static runningCliFile(): string | null;
     /** Application mode */
     buildApp(app?: App, opts?: {
         watch?: boolean;
         preserveDefaultExport?: boolean;
         toolchainAnchor?: string;
+        onWatchFiles?: RunBundleOptions['onWatchFiles'];
     }): Promise<RolldownOutput[]>;
     /**
      * Drive `rolldown.watch(...)`: rebuild on source change, apply the
@@ -203,5 +224,6 @@ export declare class BuildAction {
         library?: boolean;
         app?: App;
         watch?: boolean;
+        onWatchFiles?: RunBundleOptions['onWatchFiles'];
     }): Promise<RolldownOutput[]>;
 }

package/lib/actions/build.js

@@ -555,6 +555,16 @@ export class BuildAction {
         }
         if (opts.verbose)
             console.debug(`[gjsify] bundling ${inputPath} for GJS → ${outfile}`);
+        await BuildAction.bundleFileForGjs(inputPath, outfile, { ...opts, toolchainAnchor: anchorFile });
+        return outfile;
+    }
+    /**
+     * The uncached half of {@link bundleFileForGjsCached}: bundle `inputPath` to
+     * `outfile` as one self-contained `--app gjs` module. `gjsify exec` calls it
+     * directly because it keys its artifacts by CONTENT (package version, lockfile,
+     * CLI version — `utils/exec-bin.ts`) rather than by mtime.
+     */
+    static async bundleFileForGjs(inputPath, outfile, opts) {
         await mkdir(dirname(outfile), { recursive: true });
         await new BuildAction({
             verbose: opts.verbose,
@@ -564,15 +574,18 @@ export class BuildAction {
                 input: inputPath,
                 output: { file: outfile },
                 ...(opts.define ? { transform: { define: opts.define } } : {}),
+                ...(opts.logLevel ? { logLevel: opts.logLevel } : {}),
             },
         }).buildApp('gjs', {
             preserveDefaultExport: opts.preserveDefaultExport ?? true,
-            // See `opts.resolveFromToolchain`: the CALLER decides whether this input is
-            // toolchain, because this helper alone cannot tell a config file from a
-            // consumer's `node ./src/main.mjs`.
-            ...(anchorFile === null ? {} : { toolchainAnchor: anchorFile }),
+            // The CALLER decides whether this input is toolchain, because this helper
+            // alone cannot tell a config file from a consumer's `node ./src/main.mjs`.
+            ...(opts.toolchainAnchor ? { toolchainAnchor: opts.toolchainAnchor } : {}),
         });
-        return outfile;
+    }
+    /** The running CLI's own file — the toolchain anchor `gjsify exec` hands {@link bundleFileForGjs}. */
+    static runningCliFile() {
+        return runningCliFile();
     }
     /** Application mode */
     async buildApp(app = 'gjs', opts = {}) {
@@ -712,7 +725,13 @@ export class BuildAction {
             // unresolvable import would hard-crash the analysis pass.
             // Mirrors the explicit-globals path (resolveGlobalsInject)
             // and resolveUserPlugins above, which already anchor on cwd.
-            { extraGlobalsList: extras, excludeGlobals, cwd: process.cwd() }, bundleToChunks);
+            {
+                extraGlobalsList: extras,
+                excludeGlobals,
+                cwd: process.cwd(),
+                // The same fallback the resolver gets, or the gate drops what it would rescue.
+                ...(opts.toolchainAnchor !== undefined ? { toolchainDir: dirname(opts.toolchainAnchor) } : {}),
+            }, bundleToChunks);
             pluginOpts.autoGlobalsInject = injectPath;
         }
         else if (app === 'node' && autoMode) {
@@ -803,7 +822,7 @@ export class BuildAction {
             await this.runWatchLoop(finalOpts, app, outfile, outdir, verbose);
             return [];
         }
-        const writeResult = await runBundle(finalOpts);
+        const writeResult = await runBundle(finalOpts, { onWatchFiles: opts.onWatchFiles });
         // GJS truncates module source at a raw U+0000 (it is handed to SpiderMonkey as a
         // NUL-terminated C string), so escape any the minifier emitted before anything else
         // touches the file. See utils/gjs-source-escape.ts.
@@ -920,14 +939,23 @@ export class BuildAction {
         }
         await closed;
     }
-    async start(buildType = { app: 'gjs' }) {
+    async start(buildType = {
+        app: 'gjs',
+    }) {
         if (buildType.library) {
+            // `onWatchFiles` has no consumer here and is deliberately NOT
+            // forwarded: a `--library` build emits a published package, and
+            // nothing asks whether it is stale (`gjsify test` is the only
+            // freshness check, and it never builds a library).
             if (buildType.watch) {
                 throw new Error('gjsify build: --watch is not supported with --library (library mode would emit watcher rebuilds for every produced format; use --app gjs|node|browser instead).');
             }
             return await this.buildLibrary();
         }
-        return await this.buildApp(buildType.app, { watch: buildType.watch });
+        return await this.buildApp(buildType.app, {
+            watch: buildType.watch,
+            onWatchFiles: buildType.onWatchFiles,
+        });
     }
 }
 async function runOneLibraryBuild(args) {

package/lib/bundler-pick.d.ts

@@ -8,6 +8,20 @@ export interface NativePluginContext {
         id: string;
         external: boolean;
     } | null>;
+    /**
+     * rolldown's `this.addWatchFile`, collected by the native facade into
+     * `BundleResult.watchedFiles` — the native half of what npm rolldown reports
+     * as `RolldownBuild.watchFiles`.
+     *
+     * OPTIONAL here on purpose. The engine is resolved through several anchors
+     * and a global-prefix copy can answer first (measured 2026-09-29 on a dev
+     * host whose project-local engine was the current one), so a plugin cannot
+     * assume the method exists: it is this bridge's documented stance that an
+     * unimplemented context method FAILS at hook-call time, and a build must
+     * not fail over bookkeeping. `gjsify-css-as-string` therefore
+     * feature-detects and warns once.
+     */
+    addWatchFile(id: string): void;
     warn(message: string): void;
     error(message: string): never;
 }
@@ -72,11 +86,33 @@ export declare function bundleToChunks(input: {
  * and is responsible for invoking `watcher.close()` on shutdown.
  */
 export declare function runWatch(finalOpts: BundlerOptions): Promise<RolldownWatcher>;
+/** What one build reported about the files its output depends on. */
+export interface BuildWatchList {
+    /**
+     * The engine's watch list: npm rolldown's `RolldownBuild.watchFiles` (its
+     * module set plus every `this.addWatchFile`), the native facade's
+     * `watchedFiles` (the declared half — the native engine reports no modules,
+     * hence the two halves rather than either). Read BEFORE `close()`, which is
+     * where the npm getter is still alive.
+     */
+    files: readonly string[];
+    /**
+     * `false` when the engine CANNOT report one at all (a `@gjsify/rolldown-native`
+     * older than `addWatchFile`). A caller that judges a build's inputs on this
+     * list has to refuse to trust it — the file a plugin read itself is then
+     * invisible, and a stale bundle would read as current.
+     */
+    reportedByEngine: boolean;
+}
+/** Where a build's own input list goes. Absent → the caller does not want it. */
+export interface RunBundleOptions {
+    onWatchFiles?: (watch: BuildWatchList) => void;
+}
 /**
  * Run a bundle with the picked engine. Drop-in replacement for the
  * `rolldown(opts).write(opts.output)` flow used directly in build.ts.
  */
-export declare function runBundle(finalOpts: BundlerOptions): Promise<RolldownOutput>;
+export declare function runBundle(finalOpts: BundlerOptions, options?: RunBundleOptions): Promise<RolldownOutput>;
 export declare function shouldUseNative(): Promise<boolean>;
 /**
  * Walk parent directories from `startDir` (and optionally a second anchor

package/lib/bundler-pick.js

@@ -10,7 +10,7 @@
 // synchronous require of a builtin, so the load dies before any `.node` is opened.
 // The distinction is not pedantry — it says an N-API host alone would not be
 // enough; the wrapper has to be bypassed too, which is exactly what
-// `napiNodeAddonPlugin` does for napi-rs packages. See `status/open-todos.md`
+// `napiNodeAddonPlugin` does for napi-rs packages. See `status/open-todos/README.md`
 // § "Can `@gjsify/napi` retire the hand-written `-native` bridges?".
 //
 // `GJSIFY_BUNDLER=native|npm` overrides that: `native` throws when the prebuild is
@@ -30,7 +30,7 @@
 import { promises as fs, existsSync } from 'node:fs';
 import * as path from 'node:path';
 import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { resolveNpmPackage } from './utils/resolve-npm-package.js';
 // Static, not dynamic: `diagnoseNativeEngine()` is synchronous and called inside a
 // `throw` expression. Safe because check-system-deps imports only `node:` builtins,
@@ -80,7 +80,8 @@ async function loadNpmRolldown() {
 function diagnoseNativeEngine() {
     let pkgDir = null;
     try {
-        const bundleDir = path.dirname(new URL(import.meta.url).pathname);
+        // Not `new URL(...).pathname`: on win32 that is `/C:/...`, percent-encoded, no path.
+        const bundleDir = path.dirname(fileURLToPath(import.meta.url));
         pkgDir = findRolldownNativeDir(process.cwd(), bundleDir);
     }
     catch {
@@ -131,23 +132,39 @@ function diagnoseNativeEngine() {
     // reads the same tables `gjsify system-check` does, so the answer cannot drift
     // from the declaration.
     const missing = missingSystemDepsFor('@gjsify/rolldown-native');
-    if (missing.length > 0) {
-        const names = missing.map((d) => d.name).join(', ');
+    const names = missing.map((d) => d.name).join(', ');
+    const cmd = missing.length > 0 ? buildInstallCommand(detectPackageManager(), missing) : null;
+    const installHint = missing.length === 0
+        ? undefined
+        : cmd
+            ? `Install it:\n  ${cmd}`
+            : `Install ${names} with your system package manager (this host's manager was not recognised, so no command is suggested rather than a wrong one).`;
+    // (0) The measurement could not run at all. First, because everything below
+    // reasons from a measurement: with no reading in hand, (2) would assert the
+    // prebuild IS on girepository's search path — a positive claim this PR
+    // exists to make measurable, so its absence is stated rather than papered over.
+    if (_utilsCoreError !== null) {
+        parts.push(`\nNOT MEASURED — the native-library probe could not be loaded, so nothing below is a reading of this host:\n  ${_utilsCoreError instanceof Error ? _utilsCoreError.message : String(_utilsCoreError)}`);
+    }
+    // (1) The loader's own answer, when `tryLoadNative()` measured one: the file
+    // that would not open and the dependency it named. It outranks (2), which only
+    // knows what pkg-config can see — the dependency may be one no table declares.
+    if (_nativeLibraryFailure && _utilsCore) {
+        parts.push(`\nMEASURED CAUSE — ${new _utilsCore.NativeLibraryLoadError(_nativeLibraryFailure, installHint).message}`);
+    }
+    else if (missing.length > 0) {
         parts.push(`\nMEASURED CAUSE — a system library the engine's prebuild loads is MISSING: ${names}.\n` +
             'The prebuild is present but its typelib cannot open its backing library, which GJS reports as ' +
             '`Unsupported type void, deriving from fundamental void` — a message that names nothing. ' +
             'This is a system package, not an npm one.');
-        const cmd = buildInstallCommand(detectPackageManager(), missing);
-        if (cmd)
-            parts.push(`Install it:\n  ${cmd}`);
-        else
-            parts.push(`Install ${names} with your system package manager (this host's manager was not recognised, so no command is suggested rather than a wrong one).`);
+        if (installHint)
+            parts.push(installHint);
     }
     // (2) No prebuild for this architecture — last because it is least actionable.
     // Read off the set `activateNativePrebuilds()` ACTUALLY put on the search paths:
     // a memoized cached-array read that cannot throw, and it names the per-target
     // sibling package really holding the artifact.
-    if (missing.length === 0) {
+    if (missing.length === 0 && !_nativeLibraryFailure) {
         const engine = activateNativePrebuilds().find((p) => p.name.startsWith('@gjsify/rolldown-native'));
         parts.push(engine
             ? `\nEvery declared system library resolves and ${engine.name}'s prebuild (${engine.prebuildsDir}) IS on ` +
@@ -255,24 +272,64 @@ export async function runWatch(finalOpts) {
     const output = finalOpts.output ?? {};
     return mod.watch({ ...finalOpts, output });
 }
+let _warnedNoWatchList = false;
+function warnNoNativeWatchList() {
+    if (_warnedNoWatchList)
+        return;
+    _warnedNoWatchList = true;
+    console.warn('[gjsify] this `@gjsify/rolldown-native` build reports no watch list: it predates ' +
+        '`addWatchFile`, so a file a plugin read itself (a stylesheet\u2019s `@import` chain, an ' +
+        'inlined `readFileSync`) cannot be declared as a build input. `gjsify test` will rebuild ' +
+        'the affected bundles on every run rather than trust a set it cannot see. Upgrade the ' +
+        'engine (it ships in the same release train as the CLI).');
+}
 /**
  * Run a bundle with the picked engine. Drop-in replacement for the
  * `rolldown(opts).write(opts.output)` flow used directly in build.ts.
  */
-export async function runBundle(finalOpts) {
+export async function runBundle(finalOpts, options = {}) {
     if (await shouldUseNative()) {
-        return await runNativeBundle(finalOpts);
+        return await runNativeBundle(finalOpts, options);
     }
     const rolldown = await loadNpmRolldown();
     const build = await rolldown(finalOpts);
     try {
-        return await build.write(finalOpts.output ?? {});
+        const output = await build.write(finalOpts.output ?? {});
+        if (options.onWatchFiles) {
+            options.onWatchFiles({ files: await build.watchFiles, reportedByEngine: true });
+        }
+        return output;
     }
     finally {
         await build.close();
     }
 }
 let _nativeProbe = null;
+/** Why the engine's library would not open, when `tryLoadNative()` measured it. */
+let _nativeLibraryFailure = null;
+let _utilsCore = null;
+/**
+ * Why the probe itself could not run, when that is the reason. Kept apart from
+ * "there is no engine" on purpose: `tryLoadNative()`'s bare `catch` cannot tell
+ * the two apart, and `diagnoseNativeEngine()` then answers a question nobody
+ * asked — it reports which system libraries resolve, and says the prebuild IS on
+ * girepository's search path, which is a positive claim about a measurement that
+ * never happened. This PR exists to make such a claim measurable, so a missing
+ * measurement is reported as one.
+ */
+let _utilsCoreError = null;
+async function utilsCore() {
+    if (_utilsCore === null) {
+        // `./native-library`, not `./core`: `core` re-exports `main-loop`, which
+        // holds a module-level singleton. The GJS bundle inlines utils already,
+        // so loading `core` off disk would give the process a SECOND copy of that
+        // singleton — inert today because only pure probe functions are read
+        // through this edge, and a trap the first time that stops being true.
+        const href = pathToFileURL(createRequire(import.meta.url).resolve('@gjsify/utils/native-library')).href;
+        _utilsCore = (await import(/* @vite-ignore */ href));
+    }
+    return _utilsCore;
+}
 export async function shouldUseNative() {
     const env = globalThis.process?.env ?? {};
     const choice = env.GJSIFY_BUNDLER;
@@ -282,7 +339,8 @@ export async function shouldUseNative() {
     if (choice === 'native') {
         const native = await tryLoadNative();
         if (!native) {
-            throw new Error('GJSIFY_BUNDLER=native but @gjsify/rolldown-native is not loadable (no prebuild for this architecture, or not running under GJS).');
+            throw new Error('GJSIFY_BUNDLER=native but @gjsify/rolldown-native is not loadable (no prebuild for this architecture, or not running under GJS).' +
+                (isGjs() ? `\n${diagnoseNativeEngine()}` : ''));
         }
         return true;
     }
@@ -375,7 +433,7 @@ async function tryLoadNative() {
                 // limitations and `findWorkspaceRoot`'s dependency on
                 // `discoverWorkspaces`, both of which can fail to map a
                 // sub-package dir up to the hoisted workspace root.
-                const bundleDir = path.dirname(new URL(import.meta.url).pathname);
+                const bundleDir = path.dirname(fileURLToPath(import.meta.url));
                 const resolvedFromNpm = resolveNpmPackage(specifier, { bundleUrl: import.meta.url });
                 const resolvedFromFs = resolvedFromNpm
                     ? null
@@ -399,6 +457,25 @@ async function tryLoadNative() {
             const mod = (await import(/* @vite-ignore */ target));
             if (!mod.hasNativeRolldown())
                 return null;
+            // The typelib resolved, which says nothing about its library: that
+            // opens at the first class access, and a missing system library
+            // (Homebrew json-glib on a Mac) would pass here and fail inside
+            // `new BundlerSession()` as the nameless "Unsupported type void" —
+            // past `diagnoseNativeEngine()`, which then never runs.
+            // Separated from the engine's own failure so that "the engine is
+            // absent" and "the measurement could not run" stay distinguishable
+            // at the one place that reports them.
+            let surface;
+            try {
+                surface = await utilsCore();
+            }
+            catch (err) {
+                _utilsCoreError = err;
+                return null;
+            }
+            _nativeLibraryFailure = surface.probeNativeLibrary('GjsifyRolldown');
+            if (_nativeLibraryFailure)
+                return null;
             return mod;
         }
         catch {
@@ -407,7 +484,7 @@ async function tryLoadNative() {
     })();
     return _nativeProbe;
 }
-async function runNativeBundle(finalOpts) {
+async function runNativeBundle(finalOpts, options = {}) {
     const native = await tryLoadNative();
     if (!native) {
         throw new Error('@gjsify/rolldown-native not loadable');
@@ -440,6 +517,20 @@ async function runNativeBundle(finalOpts) {
     }
     const result = await native.bundleWithPlugins(bundlerOpts, nativePlugins);
     reportNativeWarnings(result, finalOpts);
+    if (options.onWatchFiles) {
+        if (result.watchedFiles === undefined) {
+            // NOT a silent drop. A version-skewed engine has no `addWatchFile` on
+            // its plugin context, so nothing a plugin declares can reach the
+            // build's input set — and a caller judging freshness on that set
+            // would call a stale bundle current. Say so here, where the engine is
+            // in hand, and report `reportedByEngine: false` so the caller refuses.
+            warnNoNativeWatchList();
+            options.onWatchFiles({ files: [], reportedByEngine: false });
+        }
+        else {
+            options.onWatchFiles({ files: result.watchedFiles, reportedByEngine: true });
+        }
+    }
     // The native facade returns the BundleOutput shape but doesn't
     // write files — replicate `.write()` here so callers see the same
     // on-disk layout whether they used npm rolldown or native.

package/lib/cli-app.js

@@ -10,7 +10,7 @@
 // build`, and `gjsify run build:types → gjsify tsc → gjs tsc.gjs.mjs`), so on
 // CI's few cores the multiplier oversubscribes and the build thrashes. Letting
 // `gjsify run` dispatch the inner `gjsify <cmd>` in-process collapses two gjs
-// into one. See status/open-todos.md.
+// into one. See status/open-todos/README.md.
 //
 // This module MUST NOT execute anything at load time (no top-level
 // `parseAsync`) — `run.ts` imports it, and a top-level run would re-dispatch
@@ -18,7 +18,7 @@
 import yargs from 'yargs';
 import { classifyCliFailure } from './cli-fail.js';
 import { cliVersion } from './utils/publish-headers.js';
-import { buildCommand as build, clearCommand as clear, copyCommand as copy, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, shipCommand as ship, dlxCommand as dlx, installCommand as install, linkCommand as link, unlinkCommand as unlink, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, pruneCommand as prune, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, devCommand as dev, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
+import { buildCommand as build, clearCommand as clear, copyCommand as copy, envCommand as env, execCommand as exec, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, shipCommand as ship, dlxCommand as dlx, installCommand as install, linkCommand as link, unlinkCommand as unlink, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, pruneCommand as prune, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, devCommand as dev, debugCommand as debug, browseCommand as browse, webextCommand as webext, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isBun, isDeno, isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -98,6 +98,8 @@ export async function runCli(argv) {
         .command(build.command, build.description, build.builder, build.handler)
         .command(clear.command, clear.description, clear.builder, clear.handler)
         .command(copy.command, copy.description, copy.builder, copy.handler)
+        .command(env.command, env.description, env.builder, env.handler)
+        .command(exec.command, exec.description, exec.builder, exec.handler)
         .command(test.command, test.description, test.builder, test.handler)
         .command(run.command, run.description, run.builder, run.handler)
         .command(dlx.command, dlx.description, dlx.builder, dlx.handler)
@@ -134,6 +136,7 @@ export async function runCli(argv) {
         .command(dev.command, dev.description, dev.builder, dev.handler)
         .command(debug.command, debug.description, debug.builder, debug.handler)
         .command(browse.command, browse.description, browse.builder, browse.handler)
+        .command(webext.command, webext.description, webext.builder, webext.handler)
         .demandCommand(1)
         .epilogue(`Running on ${runtimeLabel()}`)
         .help()

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 {};