@gjsify/cli 0.41.0 → 0.43.0

package/lib/actions/build.d.ts

@@ -72,6 +72,12 @@ export declare class BuildAction {
      * natively, `@gjsify/rolldown-native` via `synthRolldownOutput`), and it
      * cannot be fooled by a `node:` specifier quoted inside a string, which a
      * text scan cannot tell from a statement.
+     *
+     * The same list also answers the GENERAL form of the question — any bare
+     * specifier GJS cannot resolve, `node:` or not — which is why the target's
+     * externals predicate and the emitted fileNames are handed over: they are
+     * what separates a declared external and a sibling chunk from a dependency
+     * that simply is not there.
      */
     private assertGjsOutputLoadable;
     /**
@@ -166,11 +172,25 @@ export declare class BuildAction {
          */
         globals?: string;
         excludeGlobals?: string[];
+        /**
+         * Allow a `@gjsify/*` this project cannot resolve to come from the copy
+         * installed beside the RUNNING CLI.
+         *
+         * OPT-IN PER CALLER, never inferred here, because this helper does NOT
+         * only bundle toolchain — the `node` shim `gjsify run` puts on the PATH
+         * routes any project's `node <file>` through `utils/node-script.ts` and
+         * into this same function, a consumer's `"start": "node ./src/main.mjs"`
+         * included. Each caller states what it is bundling and why that earns the
+         * fallback; `gjsify build` sets nothing, so a user's missing dependency
+         * stays fatal there.
+         */
+        resolveFromToolchain?: boolean;
     }): Promise<string>;
     /** Application mode */
     buildApp(app?: App, opts?: {
         watch?: boolean;
         preserveDefaultExport?: boolean;
+        toolchainAnchor?: string;
     }): Promise<RolldownOutput[]>;
     /**
      * Drive `rolldown.watch(...)`: rebuild on source change, apply the

package/lib/actions/build.js

@@ -1,16 +1,18 @@
 import { runBundle, runWatch, bundleToChunks } from '../bundler-pick.js';
-import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG } from '@gjsify/rolldown-plugin-gjsify';
+import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG, createGjsExternalsPredicate, globToEntryPoints, } from '@gjsify/rolldown-plugin-gjsify';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { resolveUserPlugins } from '../utils/resolve-plugin-by-name.js';
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, detectNodeGiGlobals, } from '@gjsify/rolldown-plugin-gjsify/globals';
 import { pnpPlugin } from '@gjsify/rolldown-plugin-pnp';
 import { basename, dirname, extname, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize-bundler-options.js';
 import { inputSourceDirs, isOutdirInsideSource, libraryOutputLeakError } from '../utils/library-output.js';
 import { detectHtmlEntry, parseHtmlEntry, emitBrowserHtml, htmlOutPathFor } from '../utils/html-entry.js';
-import { assertGjsBundleLoadable } from '../utils/gjs-bundle-guard.js';
+import { assertGjsBundleLoadable, assertGjsBundleParses } from '../utils/gjs-bundle-guard.js';
+import { collectEntryPaths, describeJsxConfig, findJsxEntryPoint, jsxConfigMissingError } from '../utils/jsx-config.js';
+import { giSystemProbes } from '../utils/gi-runtime-paths.js';
 import { escapeRawNulForGjs } from '../utils/gjs-source-escape.js';
 import { assertNodeBundleGlobalsShimmed } from '../utils/node-bundle-guard.js';
 const DEFAULT_GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
@@ -78,17 +80,41 @@ async function newestLockfileMtime(cwd) {
     }
     return newest;
 }
+/**
+ * Absolute path of the CLI module that is running, or `null` when it did not come
+ * from a `file:` URL.
+ *
+ * The conversion happens ONCE, here, inside a catch. A CLI loaded from a non-`file:`
+ * origin — the bundled/Flatpak shape `commands/tsc.ts` names as the reason its second
+ * anchor exists — would otherwise make `fileURLToPath` throw on the path that loads
+ * every config file and every plugin, not merely lose the fallback.
+ */
+function runningCliFile() {
+    try {
+        return fileURLToPath(import.meta.url);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Fresh when the cached GJS bundle is newer than BOTH the source file AND the
  * project's lockfile (the dep-change signal). Missing bundle/source → not fresh
  * (rebuild). Shared by the plugin + config GJS-bundle caches.
+ *
+ * `anchorFile` is the running CLI, and only set when this bundle was allowed the
+ * toolchain fallback. Such a bundle can carry code from the CLI's OWN install,
+ * which neither the entry mtime nor the project lockfile tracks — so after a
+ * `gjsify self-update` a cached config/plugin bundle holding the previous CLI's
+ * `@gjsify/*` would otherwise stay "fresh" forever.
  */
-async function isBundleFresh(outfile, sourcePath, cwd) {
+async function isBundleFresh(outfile, sourcePath, cwd, anchorFile) {
     try {
         const outStat = await stat(outfile);
         const srcStat = await stat(sourcePath);
         const depMtime = await newestLockfileMtime(cwd);
-        return outStat.mtimeMs >= Math.max(srcStat.mtimeMs, depMtime);
+        const anchorMtime = anchorFile === undefined ? 0 : (await stat(anchorFile)).mtimeMs;
+        return outStat.mtimeMs >= Math.max(srcStat.mtimeMs, depMtime, anchorMtime);
     }
     catch {
         return false;
@@ -124,6 +150,21 @@ export class BuildAction {
         const multipleBuilds = moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
         const pnp = await buildPnpPlugin();
         const pnpPlugins = pnp ? [pnp] : [];
+        // The same chain `buildApp` assembles, and it was missing here entirely:
+        // a library build resolved NO user plugin and NO user text loader, then
+        // emitted the default transform at exit 0. Configuring
+        // `gjsify.bundler.plugins` and watching it do nothing is the repo's most
+        // expensive failure shape, and `@gjsify/gtk-host` itself builds with
+        // `--library` — which is where it was found.
+        const userTextLoader = textLoaderPlugin({ loaders: this.configData.loaders });
+        const userPlugins = userTextLoader ? [userTextLoader] : [];
+        if (userBundler.plugins?.length) {
+            // Under GJS a plugin module cannot always be imported directly — the
+            // native ESM loader does not follow `package.json#exports` — so the
+            // same bundle-then-import escape the app path uses is passed in here.
+            const resolved = await resolveUserPlugins(userBundler.plugins, process.cwd(), isGjs() ? { loadModule: (pth, name) => this.loadPluginViaGjsBundle(pth, name, verbose) } : {});
+            userPlugins.push(...resolved);
+        }
         const results = [];
         if (multipleBuilds) {
             // Both outdirs are derived from module/main — always guard them
@@ -143,6 +184,7 @@ export class BuildAction {
                 output: { dir: moduleOutdir },
                 userAliases: aliases,
                 pnpPlugins,
+                userPlugins,
             }));
             const mainFormat = mainOutdir.includes('/cjs') || mainOutExt === '.cjs' ? 'cjs' : 'esm';
             results.push(await runOneLibraryBuild({
@@ -157,6 +199,7 @@ export class BuildAction {
                 output: { dir: mainOutdir },
                 userAliases: aliases,
                 pnpPlugins,
+                userPlugins,
             }));
         }
         else {
@@ -182,6 +225,7 @@ export class BuildAction {
                 output: { dir: outdir },
                 userAliases: aliases,
                 pnpPlugins,
+                userPlugins,
             }));
         }
         return results;
@@ -350,10 +394,22 @@ export class BuildAction {
      * natively, `@gjsify/rolldown-native` via `synthRolldownOutput`), and it
      * cannot be fooled by a `node:` specifier quoted inside a string, which a
      * text scan cannot tell from a statement.
+     *
+     * The same list also answers the GENERAL form of the question — any bare
+     * specifier GJS cannot resolve, `node:` or not — which is why the target's
+     * externals predicate and the emitted fileNames are handed over: they are
+     * what separates a declared external and a sibling chunk from a dependency
+     * that simply is not there.
      */
-    assertGjsOutputLoadable(result, outfile, outdir) {
+    assertGjsOutputLoadable(result, outfile, outdir, userExternal) {
         const chunks = (result.output ?? []).filter((item) => item.type === 'chunk');
-        assertGjsBundleLoadable(chunks, outfile ?? outdir ?? 'the GJS bundle');
+        assertGjsBundleLoadable(chunks, outfile ?? outdir ?? 'the GJS bundle', {
+            // The target's OWN predicate, not a second list: `externalsPlugin` enforces
+            // this exact one, so a specifier the build let through as external cannot be
+            // reported as unresolvable here.
+            isExternal: createGjsExternalsPredicate(userExternal ?? []),
+            emitted: (result.output ?? []).map((item) => item.fileName),
+        });
     }
     /**
      * Post-bundle gate for `--app node`: throw when the emitted bundle still
@@ -433,6 +489,9 @@ export class BuildAction {
                 label: pluginName,
                 verbose,
                 noCacheEnv: 'GJSIFY_NO_PLUGIN_CACHE',
+                // A bundler plugin runs inside the CLI process — toolchain by
+                // construction, not by where its file happens to sit.
+                resolveFromToolchain: true,
             });
         }
         catch (err) {
@@ -471,9 +530,13 @@ export class BuildAction {
         // policies is two artifacts, and the freshness check below (entry mtime + lockfile)
         // cannot see the `package.json` edit that changed one. Callers without a policy keep
         // their existing cache filenames.
-        const cacheKey = opts.globals === undefined && opts.excludeGlobals === undefined
+        // The anchor belongs in the key for the same reason: with it the artifact may
+        // contain code from a DIFFERENT install than without it, and two CLIs on one
+        // machine resolve to two different paths.
+        const anchorFile = opts.resolveFromToolchain === true ? runningCliFile() : null;
+        const cacheKey = opts.globals === undefined && opts.excludeGlobals === undefined && anchorFile === null
             ? inputPath
-            : `${inputPath} ${JSON.stringify([opts.globals ?? null, opts.excludeGlobals ?? null])}`;
+            : `${inputPath} ${JSON.stringify([opts.globals ?? null, opts.excludeGlobals ?? null, anchorFile])}`;
         // THE HASH GOES IN THE DIRECTORY, THE FILE KEEPS THE SOURCE'S NAME. As
         // `<name>-<hash>.mjs` it broke every script guarding its body with the standard
         // is-entry test: `audit-runtimes.mjs` asks whether `process.argv[1]` ENDS WITH its
@@ -482,7 +545,7 @@ export class BuildAction {
         // does — and a name is cheaper to keep right than an argv to rewrite.
         const outfile = join(cacheDir, `${safeName}-${shortHash(cacheKey)}`, `${basename(inputPath).replace(/\.[cm]?[jt]sx?$/i, '')}.mjs`);
         const cacheDisabled = opts.cache === false || (opts.noCacheEnv ? isTruthyEnv(process.env[opts.noCacheEnv]) : false);
-        if (!cacheDisabled && (await isBundleFresh(outfile, inputPath, cwd))) {
+        if (!cacheDisabled && (await isBundleFresh(outfile, inputPath, cwd, anchorFile ?? undefined))) {
             if (opts.verbose)
                 console.debug(`[gjsify] reusing cached GJS bundle ${outfile}`);
             return outfile;
@@ -499,13 +562,34 @@ export class BuildAction {
                 output: { file: outfile },
                 ...(opts.define ? { transform: { define: opts.define } } : {}),
             },
-        }).buildApp('gjs', { preserveDefaultExport: opts.preserveDefaultExport ?? true });
+        }).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 }),
+        });
         return outfile;
     }
     /** Application mode */
     async buildApp(app = 'gjs', opts = {}) {
         const { verbose, typescript, exclude, library: pkg, aliases, excludeGlobals } = this.configData;
         const userBundler = normalizeBundlerOptions(this.configData);
+        // Refuse a JSX entry with no JSX policy BEFORE bundling anything — see
+        // `utils/jsx-config.ts` for what the unset default emits and why it can never be
+        // right for this target. The glob expansion is paid only on the failing branch:
+        // when JSX is configured there is nothing to name.
+        const jsxPolicy = describeJsxConfig({
+            transformJsx: userBundler.transform?.jsx,
+            tsconfigJsx: typescript?.compilerOptions?.jsx,
+            tsconfigJsxImportSource: typescript?.compilerOptions?.jsxImportSource,
+        });
+        if (app === 'gjs' && !jsxPolicy.configured) {
+            const entries = collectEntryPaths(await globToEntryPoints(userBundler.input, exclude));
+            const jsxEntry = findJsxEntryPoint(entries);
+            if (jsxEntry !== undefined)
+                throw jsxConfigMissingError(jsxEntry);
+        }
         // --- `--app browser` HTML entry (Vite-style) ---
         // When the entry is an `index.html`, bundle the module its
         // `<script type="module" src>` references (rewrite `input` to that
@@ -558,6 +642,7 @@ export class BuildAction {
             consoleShim,
             ...(aliases ? { aliases } : {}),
             ...(opts.preserveDefaultExport ? { preserveDefaultExport: true } : {}),
+            ...(opts.toolchainAnchor !== undefined ? { toolchainAnchor: opts.toolchainAnchor } : {}),
         };
         const { autoMode, extras } = this.parseGlobalsValue(globals);
         const pnp = await buildPnpPlugin();
@@ -682,6 +767,13 @@ export class BuildAction {
         else if (extras) {
             pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
         }
+        // Fills the byte-1 GI prologue — built across #1152/#1160/#1026 and called by
+        // nothing, so every `--app gjs` bundle ever built shipped the empty string
+        // `giRuntimePathsStub` returns for an empty input. Only the FINAL build: the
+        // two analysis passes above bundle in memory to be PARSED for free globals,
+        // never written and never run, so a prologue there is work whose result is
+        // discarded.
+        const giProbes = app === 'gjs' ? giSystemProbes() : undefined;
         // Final build: orchestrator → rolldown → write
         const cfg = await gjsifyPlugin({
             input: userBundler.input,
@@ -690,6 +782,7 @@ export class BuildAction {
             userBanner,
             userAliases: aliases,
             shebang: this.configData.shebang,
+            giSystemProbes: giProbes,
         }, pluginOpts);
         const merged = mergeBundlerOptions(cfg.options, userBundler);
         const finalOpts = {
@@ -699,7 +792,7 @@ export class BuildAction {
             // and appended into `userPlugins` above. Re-emitting the raw
             // entries (which may include `BundlerPluginByName` shapes
             // Rolldown doesn't understand) would crash the build.
-            plugins: [...pnpPlugins, ...userPlugins, ...cfg.plugins],
+            plugins: [...pnpPlugins, ...cfg.prePlugins, ...userPlugins, ...cfg.plugins],
         };
         if (opts.watch) {
             await this.runWatchLoop(finalOpts, app, outfile, outdir, verbose);
@@ -715,9 +808,15 @@ export class BuildAction {
         if ((app === 'gjs' || app === 'node') && this.configData.shebang) {
             await this.applyShebang(app, outfile, verbose);
         }
-        // Refuse to hand back a `--app gjs` bundle stock GJS cannot even load.
+        // Refuse to hand back a `--app gjs` bundle stock GJS cannot even load: one that
+        // imports what the runtime cannot resolve, or — when the transform was told to
+        // keep JSX — one that is not parseable JavaScript at all.
         if (app === 'gjs') {
-            this.assertGjsOutputLoadable(writeResult, outfile, outdir);
+            this.assertGjsOutputLoadable(writeResult, outfile, outdir, userExternal);
+            if (jsxPolicy.preserves) {
+                const chunks = (writeResult.output ?? []).filter((item) => item.type === 'chunk');
+                assertGjsBundleParses(chunks, outfile ?? outdir ?? 'the GJS bundle');
+            }
         }
         // Refuse to hand back a `--app node` bundle that reaches for GJS ambient
         // globals nothing seeds. Only meaningful when the shim was NOT injected:
@@ -835,7 +934,11 @@ async function runOneLibraryBuild(args) {
     const merged = mergeBundlerOptions(cfg.options, args.userBundler);
     const finalOpts = {
         ...merged,
-        plugins: [...args.pnpPlugins, ...cfg.plugins],
+        // Same order as the app path: PnP resolves, then the user transforms,
+        // then gjsify's own chain. `merged.plugins` is deliberately NOT spread —
+        // the user's entries arrive RESOLVED, in `userPlugins`, exactly as
+        // `buildApp` passes them.
+        plugins: [...args.pnpPlugins, ...cfg.prePlugins, ...args.userPlugins, ...cfg.plugins],
     };
     return await runBundle(finalOpts);
 }

package/lib/bundler-pick.js

@@ -2,8 +2,16 @@
 // npm `rolldown(opts).write(opts.output)`; GJS gets `@gjsify/rolldown-native` (the
 // Vala/Rust prebuild) via `bundleWithPlugins()`, with `runNativeBundle` replicating
 // npm rolldown's `.write()` including nested chunk/asset subdirectories. The native
-// engine is the GJS DEFAULT with no env var, because npm `rolldown` is a Rust N-API
-// addon that cannot load under GJS at all.
+// engine is the GJS DEFAULT with no env var, because npm `rolldown` does not run
+// under GJS. Where it fails matters: NOT in the N-API addon, but in the JS entry
+// above it. `rolldown/dist/shared/binding-*.mjs` evaluates
+// `createRequire(import.meta.url)` at module scope and its platform detection then
+// calls `__require('node:fs')` / `__require('node:child_process')`; GJS refuses a
+// 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`
+// § "Can `@gjsify/napi` retire the hand-written `-native` bridges?".
 //
 // `GJSIFY_BUNDLER=native|npm` overrides that: `native` throws when the prebuild is
 // not loadable for the running architecture instead of silently switching engines;

package/lib/cli-app.js

@@ -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, 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, debugCommand as debug, browseCommand as browse, } from './commands/index.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, 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 { APP_NAME } from './constants.js';
 import { isBun, isDeno, isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -129,6 +129,7 @@ export async function runCli(argv) {
         .command(tsc.command, tsc.description, tsc.builder, tsc.handler)
         .command(affected.command, affected.description, affected.builder, affected.handler)
         .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(browse.command, browse.description, browse.builder, browse.handler)
         .demandCommand(1)

package/lib/commands/browse.js

@@ -112,6 +112,6 @@ export const browseCommand = {
             process.env.WEBKIT_INSPECTOR_HTTP_SERVER = `127.0.0.1:${inspectorPort}`;
         }
         const { runGjsBundle } = await import('../utils/run-gjs.js');
-        await runGjsBundle(outPath, [], { exitOnSuccess: true });
+        await runGjsBundle(outPath, [], { completion: 'exit', exitOnSuccess: true });
     },
 };

package/lib/commands/debug.js

@@ -158,6 +158,6 @@ export const debugCommand = {
             return;
         }
         const { runGjsBundle } = await import('../utils/run-gjs.js');
-        await runGjsBundle(outPath, [], { exitOnSuccess: true });
+        await runGjsBundle(outPath, [], { completion: 'exit', exitOnSuccess: true });
     },
 };

package/lib/commands/dev.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from '../types/index.js';
+interface DevCliOptions {
+    entry?: string;
+    runtime?: string;
+    script?: string;
+    globals?: string;
+    outfile?: string;
+    watchDir?: string;
+    debounce: number;
+    buildOnly: boolean;
+}
+export declare const devCommand: Command<unknown, DevCliOptions>;
+export {};

package/lib/commands/dev.js

@@ -0,0 +1,132 @@
+// `gjsify dev` — the inner development loop: watch, rebuild, relaunch.
+//
+// It exists because `gjsify build --watch` cannot serve it on the host that
+// needs it most. That flag drives rolldown's watcher API, which only the npm
+// engine exposes (`bundler-pick.ts` refuses under `@gjsify/rolldown-native`), so
+// on a Node-free GJS host the loop was manual: edit, Ctrl-C, rebuild, relaunch.
+// `gjsify storybook --watch` had already shown the way around it — watch with
+// `fs.watch` and rebuild by re-entering the ordinary build command, which needs
+// no watcher API and is runtime-agnostic. That loop is now shared
+// (`utils/watch-loop.ts`) and this command is its second caller.
+//
+// WHAT to build is not re-declared here: it is read out of the project's own
+// `build:gjs` / `build:node` script (`utils/dev-plan.ts`), so the dev loop and
+// `gjsify run build` cannot drift into building different bundles.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { noBundleError, planDev } from '../utils/dev-plan.js';
+import { buildAppForRuntime, EXAMPLE_RUNTIMES } from '../utils/runtimes.js';
+import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+function readPackage(cwd) {
+    try {
+        return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        // A missing or malformed package.json is not this command's error to
+        // report: `planDev` refuses right after, naming the flags that make
+        // `gjsify dev` work in a directory with no manifest at all.
+        return {};
+    }
+}
+export const devCommand = {
+    command: 'dev [entry]',
+    description: 'Watch this project, rebuild on change and relaunch the app.',
+    builder: (yargs) => yargs
+        .positional('entry', {
+        description: 'Entry point to build (default: the one the build script names, e.g. src/index.ts from `build:gjs`).',
+        type: 'string',
+    })
+        .option('runtime', {
+        description: 'Runtime to build for and launch on: gjs | node | bun | deno (default: the host runtime). ' +
+            'node/bun/deno build the same `--app node` bundle.',
+        type: 'string',
+        choices: EXAMPLE_RUNTIMES,
+        // No yargs `default` — the host default is applied in the
+        // handler, so `hostRuntime()` is evaluated where it can be seen.
+        defaultDescription: 'host runtime (gjs on gjs, else node/bun/deno)',
+    })
+        .option('script', {
+        description: 'package.json script the build flags are read from (default: build:gjs, or build:node for node/bun/deno).',
+        type: 'string',
+    })
+        .option('globals', { description: 'Override the build script `--globals` value.', type: 'string' })
+        .option('outfile', { description: 'Override the build script `--outfile` path.', type: 'string' })
+        .option('watch-dir', {
+        description: 'Directory watched recursively (default: the directory of the entry point).',
+        type: 'string',
+    })
+        .option('debounce', {
+        description: 'Quiet window in ms after a change before rebuilding.',
+        type: 'number',
+        default: 200,
+    })
+        .option('build-only', {
+        description: 'Rebuild on every change but never launch the app.',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const pkg = readPackage(cwd);
+        // The cast, not a guard: yargs' `choices` above already rejects anything
+        // outside the four, and `hostRuntime()` returns exactly that union — a
+        // second check here would be validating our own vocabulary.
+        const runtime = (args.runtime ?? hostRuntime());
+        const app = buildAppForRuntime(runtime);
+        const scriptName = args.script ?? (app === 'gjs' ? 'build:gjs' : 'build:node');
+        let plan;
+        try {
+            plan = planDev({
+                scripts: pkg.scripts ?? {},
+                scriptName,
+                app,
+                declaredBundle: app === 'gjs' ? pkg.gjsify?.main : pkg.gjsify?.example?.node,
+                entry: args.entry,
+                globals: args.globals,
+                outfile: args.outfile,
+                watchDir: args.watchDir,
+            });
+        }
+        catch (err) {
+            console.error(err.message);
+            // `return process.exit()`: under GJS a bare `process.exit()` only
+            // SCHEDULES the exit and returns, so execution would fall through
+            // into the watch loop and the deferred exit would never carry its
+            // code. Same trap as `showcase.ts` / `storybook.ts`.
+            return process.exit(1);
+        }
+        const bundlePath = plan.bundle === undefined ? undefined : resolve(cwd, plan.bundle);
+        if (bundlePath === undefined && !args.buildOnly) {
+            console.error(noBundleError(scriptName, app).message);
+            return process.exit(1);
+        }
+        const watchDir = resolve(cwd, plan.watchDir);
+        if (!existsSync(watchDir)) {
+            // `fs.watch` on a missing directory throws a bare ENOENT with the
+            // path buried in a stack — say which directory was DERIVED and how
+            // to override it instead.
+            console.error(`gjsify dev: nothing to watch — ${relative(cwd, watchDir) || watchDir} does not exist.\n` +
+                `  Point the loop at your sources:   gjsify dev --watch-dir <dir>`);
+            return process.exit(1);
+        }
+        const target = bundlePath === undefined ? `\`${scriptName}\` output` : relative(cwd, bundlePath);
+        console.log(`Watching ${relative(cwd, watchDir) || '.'} → ${target} (runtime: ${runtime})`);
+        // In-process build — runtime-agnostic (Node uses npm rolldown, GJS the
+        // @gjsify/rolldown-native facade), no re-spawn of the CLI binary.
+        const { runCli } = await import('../cli-app.js');
+        const { runWatchLoop, spawnBundleSupervised } = await import('../utils/watch-loop.js');
+        await runWatchLoop({
+            dir: watchDir,
+            dirLabel: relative(cwd, watchDir) || '.',
+            label: 'dev',
+            build: () => runCli(plan.buildArgv),
+            spawnChild: args.buildOnly || bundlePath === undefined
+                ? null
+                : () => spawnBundleSupervised(runtime, bundlePath, cwd, 'this project'),
+            // Passed even under `--build-only`: what makes the loop feed itself
+            // is the WRITE, not the launch.
+            output: bundlePath,
+            debounceMs: args.debounce,
+        });
+    },
+};

package/lib/commands/dlx.js

@@ -100,7 +100,7 @@ export const dlxCommand = {
         }
         // Terminal call — exit on success, or the GJS main loop parks this
         // process forever (see RunGjsBundleOptions.exitOnSuccess).
-        await runGjsBundle(entry.bundlePath, extraArgs, { exitOnSuccess: true });
+        await runGjsBundle(entry.bundlePath, extraArgs, { completion: 'exit', exitOnSuccess: true });
     },
 };
 /**

package/lib/commands/index.d.ts

@@ -36,5 +36,6 @@ export * from './barrels.js';
 export * from './tsc.js';
 export * from './affected.js';
 export * from './storybook.js';
+export * from './dev.js';
 export * from './debug.js';
 export * from './browse.js';

package/lib/commands/index.js

@@ -36,5 +36,6 @@ export * from './barrels.js';
 export * from './tsc.js';
 export * from './affected.js';
 export * from './storybook.js';
+export * from './dev.js';
 export * from './debug.js';
 export * from './browse.js';