@gjsify/cli 0.52.0 → 0.54.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

@@ -1,5 +1,6 @@
 import type { RolldownOutput, InputOptions, RolldownWatcher } from 'rolldown';
 import type { BundlerOptions } from './types/index.js';
+import { type ResolveNpmPackageOptions } from './utils/resolve-npm-package.js';
 export interface NativePluginContext {
     resolve(specifier: string, importer?: string, opts?: {
         skipSelf?: boolean;
@@ -8,6 +9,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 +87,67 @@ 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>;
+/**
+ * The file `@gjsify/utils/native-library` resolves to, or THROWS when no anchor
+ * reaches it.
+ *
+ * `resolveNpmPackage` first, the same resolver — and the same `?? createRequire`
+ * tail — the ENGINE loader below uses, for the same reason: ONE
+ * `createRequire(import.meta.url)` anchor walks exactly one node_modules chain,
+ * the one rooted at the BUNDLE. v0.53.0's release `publish-napi` job runs the
+ * published bundle from `~/.cache/gjsify/bootstrap/`, which is in no workspace's
+ * chain, so the bundle-only anchor found nothing — and since #1901 moved
+ * `probeNativeLibrary()` onto `tryLoadNative()`'s SUCCESS path, that is not a
+ * degraded diagnostic but NO ENGINE: every `gjsify build` under GJS died with
+ * "no usable bundler engine", reported by a diagnostic that resolves the same
+ * specifier and so could not name the cause. MEASURED on the release job's own
+ * shape: with `@gjsify/utils` FULLY BUILT, anchoring only at the bundle still
+ * fails with `Cannot find module "@gjsify/utils/native-library" - not found in
+ * any node_modules directory`; anchoring at cwd resolves it. `main.yml` never
+ * saw this because it exports `XDG_CACHE_HOME=$PWD/.gjsify-cache` and therefore
+ * caches the bundle INSIDE the workspace, where the bundle-only anchor happens
+ * to work.
+ *
+ * Two independent defects, so both are fixed where they live: this anchor, and
+ * the `lib/esm` emit it then needs on a cold tree (`@gjsify/utils build:esm`
+ * before the first bundler clause, rule 5 of
+ * `scripts/check-build-infra-order.mjs`).
+ *
+ * SCOPE, since it decides what this unblocks: the release job runs `build:infra`
+ * with the PUBLISHED bundle, which is fixed code this change cannot reach — so on
+ * its own it does NOT unblock v0.53.0. What does is the `XDG_CACHE_HOME` line in
+ * release.yml's `publish-napi` job, which puts that bundle inside the workspace
+ * where ANY anchor finds this tree. This fix is what stops the next release from
+ * depending on that line.
+ */
+export declare function resolveNativeLibraryModule(opts?: ResolveNpmPackageOptions): string;
 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,112 @@ 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;
+/**
+ * The file `@gjsify/utils/native-library` resolves to, or THROWS when no anchor
+ * reaches it.
+ *
+ * `resolveNpmPackage` first, the same resolver — and the same `?? createRequire`
+ * tail — the ENGINE loader below uses, for the same reason: ONE
+ * `createRequire(import.meta.url)` anchor walks exactly one node_modules chain,
+ * the one rooted at the BUNDLE. v0.53.0's release `publish-napi` job runs the
+ * published bundle from `~/.cache/gjsify/bootstrap/`, which is in no workspace's
+ * chain, so the bundle-only anchor found nothing — and since #1901 moved
+ * `probeNativeLibrary()` onto `tryLoadNative()`'s SUCCESS path, that is not a
+ * degraded diagnostic but NO ENGINE: every `gjsify build` under GJS died with
+ * "no usable bundler engine", reported by a diagnostic that resolves the same
+ * specifier and so could not name the cause. MEASURED on the release job's own
+ * shape: with `@gjsify/utils` FULLY BUILT, anchoring only at the bundle still
+ * fails with `Cannot find module "@gjsify/utils/native-library" - not found in
+ * any node_modules directory`; anchoring at cwd resolves it. `main.yml` never
+ * saw this because it exports `XDG_CACHE_HOME=$PWD/.gjsify-cache` and therefore
+ * caches the bundle INSIDE the workspace, where the bundle-only anchor happens
+ * to work.
+ *
+ * Two independent defects, so both are fixed where they live: this anchor, and
+ * the `lib/esm` emit it then needs on a cold tree (`@gjsify/utils build:esm`
+ * before the first bundler clause, rule 5 of
+ * `scripts/check-build-infra-order.mjs`).
+ *
+ * SCOPE, since it decides what this unblocks: the release job runs `build:infra`
+ * with the PUBLISHED bundle, which is fixed code this change cannot reach — so on
+ * its own it does NOT unblock v0.53.0. What does is the `XDG_CACHE_HOME` line in
+ * release.yml's `publish-napi` job, which puts that bundle inside the workspace
+ * where ANY anchor finds this tree. This fix is what stops the next release from
+ * depending on that line.
+ */
+export function resolveNativeLibraryModule(opts = {}) {
+    const specifier = '@gjsify/utils/native-library';
+    return resolveNpmPackage(specifier, opts) ?? createRequire(opts.bundleUrl ?? import.meta.url).resolve(specifier);
+}
+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.
+        //
+        // Off disk, so the resolution's ANCHORS matter — see
+        // `resolveNativeLibraryModule()` — and on a cold tree the WORKSPACE copy
+        // it finds is itself a build output, which is what
+        // `@gjsify/utils build:esm` orders (rule 5 of
+        // `scripts/check-build-infra-order.mjs`). Two independent preconditions,
+        // and v0.53.0's release `publish-napi` job needed both: a bundle-only
+        // anchor resolved nothing when the bundle was the published
+        // `cli.gjs.mjs` — one loose file in `<cache>/gjsify/bootstrap/`, no
+        // `node_modules` above it. So a throw here is "not measured" (see
+        // `tryLoadNative`), never "no engine".
+        const href = pathToFileURL(resolveNativeLibraryModule({ bundleUrl: import.meta.url })).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 +387,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 +481,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 +505,44 @@ 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 — and only a library the probe
+            // MEASURED as broken vetoes the engine. A probe that could not be
+            // LOADED does not: the engine's own load already answered twice
+            // over (the module imported, `hasNativeRolldown()` resolved its
+            // typelib), and under GJS there is no second engine to fall back to
+            // — the npm `rolldown` crate is a napi binary — so `null` here
+            // turned "nothing was measured" into "there is no bundler".
+            //
+            // What reaches that verdict is not exotic. `utilsCore()` resolves
+            // `@gjsify/utils/native-library` from THIS bundle's own directory,
+            // while every other resolution in this function goes through
+            // `resolveNpmPackage()` with its cwd/workspace anchors; the bundle
+            // that runs a cold `build:infra` is the PUBLISHED `cli.gjs.mjs`,
+            // which `install.mjs --fetch-only` caches as one loose file in
+            // `<cache>/gjsify/bootstrap/` with no `node_modules` beside it. On
+            // the release runner the probe therefore resolved nothing and
+            // `@gjsify/napi` did not publish (v0.53.0), and building utils'
+            // `lib/esm` first changed nothing — measured, which is why the
+            // asymmetry is fixed here and no clause was reordered.
+            let surface = null;
+            try {
+                surface = await utilsCore();
+            }
+            catch (err) {
+                _utilsCoreError = err;
+            }
+            if (surface !== null) {
+                _nativeLibraryFailure = surface.probeNativeLibrary('GjsifyRolldown');
+                if (_nativeLibraryFailure)
+                    return null;
+            }
             return mod;
         }
         catch {
@@ -407,7 +551,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 +584,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, devtoolsCommand as devtools, browseCommand as browse, webextCommand as webext, blueprintCommand as blueprint, } 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)
@@ -133,7 +135,10 @@ export async function runCli(argv) {
         .command(storybook.command, storybook.description, storybook.builder, storybook.handler)
         .command(dev.command, dev.description, dev.builder, dev.handler)
         .command(debug.command, debug.description, debug.builder, debug.handler)
+        .command(devtools.command, devtools.description, devtools.builder, devtools.handler)
         .command(browse.command, browse.description, browse.builder, browse.handler)
+        .command(webext.command, webext.description, webext.builder, webext.handler)
+        .command(blueprint.command, blueprint.description, blueprint.builder, blueprint.handler)
         .demandCommand(1)
         .epilogue(`Running on ${runtimeLabel()}`)
         .help()

package/lib/commands/blueprint/index.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from '../../types/index.js';
+import { blueprintTypesCommand } from './types.js';
+export { blueprintTypesCommand };
+export declare const blueprintCommand: Command;

package/lib/commands/blueprint/index.js

@@ -0,0 +1,15 @@
+// `gjsify blueprint` — yargs subcommand-group dispatcher, the same shape as `flatpak/`.
+//
+// A directory rather than one file because `check-website-cli-reference.mjs` reads every
+// `command:` in a top-level file as a top-level command; a group's subcommands live beside
+// its `index.ts` and are documented as `#### gjsify blueprint <sub>`.
+import { blueprintTypesCommand } from './types.js';
+export { blueprintTypesCommand };
+export const blueprintCommand = {
+    command: 'blueprint <subcommand>',
+    description: 'Blueprint (.blp) tooling: generate the TypeScript type sidecars a .blp exports (ADR 0088).',
+    builder: (yargs) => yargs
+        .command(blueprintTypesCommand.command, blueprintTypesCommand.description, blueprintTypesCommand.builder, blueprintTypesCommand.handler)
+        .demandCommand(1)
+        .strict(),
+};

package/lib/commands/blueprint/types.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from '../../types/index.js';
+interface BlueprintTypesOptions {
+    paths?: string[];
+    check?: boolean;
+    verbose?: boolean;
+}
+export declare const blueprintTypesCommand: Command<unknown, BlueprintTypesOptions>;
+export {};