@gjsify/cli 0.40.0 → 0.42.0

package/lib/actions/build.d.ts

@@ -166,11 +166,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

@@ -5,12 +5,13 @@ 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 { 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 +79,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;
@@ -433,6 +458,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 +499,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 +514,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,7 +531,13 @@ 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 */
@@ -558,6 +596,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 +721,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 +736,7 @@ export class BuildAction {
             userBanner,
             userAliases: aliases,
             shebang: this.configData.shebang,
+            giSystemProbes: giProbes,
         }, pluginOpts);
         const merged = mergeBundlerOptions(cfg.options, userBundler);
         const 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, 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';
@@ -120,6 +120,7 @@ export async function runCli(argv) {
         .command(selfUpdate.command, selfUpdate.description, selfUpdate.builder, selfUpdate.handler)
         .command(generateInstaller.command, generateInstaller.description, generateInstaller.builder, generateInstaller.handler)
         .command(uninstall.command, uninstall.description, uninstall.builder, uninstall.handler)
+        .command(prune.command, prune.description, prune.builder, prune.handler)
         .command(upgrade.command, upgrade.description, upgrade.builder, upgrade.handler)
         .command(format.command, format.description, format.builder, format.handler)
         .command(lint.command, lint.description, lint.builder, lint.handler)
@@ -128,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/create.d.ts

@@ -1,7 +1,10 @@
+import type { PackageManager } from '@gjsify/create-app';
 import type { Command } from '../types/index.js';
 interface CreateOptions {
     'project-name': string;
     template?: string;
+    runtime?: string;
+    'package-manager'?: PackageManager;
     force: boolean;
     install: boolean;
 }

package/lib/commands/create.js

@@ -1,11 +1,15 @@
-import { createProject, discoverTemplates } from '@gjsify/create-app';
-import { promptTemplate } from '@gjsify/create-app/prompt';
+import { createProject, discoverTemplates, PACKAGE_MANAGERS, supportedRuntimes } from '@gjsify/create-app';
+import { isCancelled, promptSetup, promptTemplate } from '@gjsify/create-app/prompt';
 export const createCommand = {
     command: 'create [project-name]',
     description: 'Scaffold a new Gjsify project in a new directory.',
     builder: (yargs) => {
         const templates = discoverTemplates();
         const templateChoices = templates.map((t) => t.name);
+        // DERIVED from the shipped templates, never a hand-written list:
+        // accepting `--runtime deno` is a claim that some template runs there,
+        // and only the templates can make it.
+        const runtimeChoices = [...new Set(templates.flatMap((t) => supportedRuntimes(t)))];
         return yargs
             .positional('project-name', {
             describe: 'Name of the project directory to create',
@@ -17,6 +21,12 @@ export const createCommand = {
             describe: 'Template to scaffold from',
             type: 'string',
             choices: templateChoices.length > 0 ? templateChoices : undefined,
+        })
+            .option('runtime', {
+            alias: 'r',
+            describe: 'Runtime to set the project up for. Decides which package managers are offered and which start script the next steps name.',
+            type: 'string',
+            choices: runtimeChoices.length > 0 ? runtimeChoices : undefined,
         })
             .option('force', {
             alias: 'f',
@@ -25,30 +35,63 @@ export const createCommand = {
             default: false,
         })
             .option('install', {
-            describe: 'Run npm install after scaffolding',
+            describe: 'Install dependencies after scaffolding',
             type: 'boolean',
             default: false,
+        })
+            .option('package-manager', {
+            alias: 'p',
+            describe: 'Package manager to install with, and to name in the printed next steps. Must be one the chosen runtime can install for. `gjsify` is the only one that works on a host with no Node.js.',
+            type: 'string',
+            choices: PACKAGE_MANAGERS,
         });
     },
     handler: async (args) => {
+        const interactive = Boolean(process.stdin.isTTY);
+        const templates = discoverTemplates();
         let template = args.template;
         if (!template) {
-            const templates = discoverTemplates();
-            if (!process.stdin.isTTY) {
+            if (!interactive) {
                 const list = templates.map((t) => t.name).join(', ');
                 console.error(`Error: --template is required in non-interactive mode. Available templates: ${list || '(none)'}`);
                 // `return` — the deferred GJS exit otherwise fell through into
                 // the interactive template prompt on a non-TTY.
                 return process.exit(1);
             }
-            const picked = await promptTemplate(templates);
+            // Ctrl+C is an abort, not a crash.
+            const picked = await promptTemplate(templates).catch((error) => {
+                if (!isCancelled(error))
+                    throw error;
+                console.error('Cancelled.');
+                return undefined;
+            });
+            if (picked === undefined)
+                return process.exit(1);
             template = picked.name;
         }
+        // The SAME decision layer `npm create @gjsify/app` runs, not a second
+        // one. Wired late: this command used to pass neither runtime nor package
+        // manager, so `createProject` fell back to the host runtime and the first
+        // manager for it — meaning `gjsify create --install` on a Node host ran
+        // `npm install` without ever saying so, the one default that reaches the
+        // user's disk and the one the standalone bin refuses to guess.
+        const info = templates.find((t) => t.name === template);
+        const setup = await promptSetup({
+            offered: info ? supportedRuntimes(info) : [],
+            runtime: args.runtime,
+            packageManager: args['package-manager'],
+            install: args.install,
+            interactive,
+        });
+        if (setup === undefined)
+            return process.exit(1);
         await createProject({
             projectName: args['project-name'],
             template,
+            runtime: setup.runtime,
             force: args.force,
             install: args.install,
+            packageManager: setup.packageManager,
         });
     },
 };

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

@@ -26,6 +26,7 @@ export * from './trust.js';
 export * from './onboard.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
+export * from './prune.js';
 export * from './uninstall.js';
 export * from './format.js';
 export * from './lint.js';
@@ -35,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

@@ -26,6 +26,7 @@ export * from './trust.js';
 export * from './onboard.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
+export * from './prune.js';
 export * from './uninstall.js';
 export * from './format.js';
 export * from './lint.js';
@@ -35,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/install.d.ts

@@ -7,6 +7,7 @@ interface InstallOptions {
     'save-peer'?: boolean;
     'save-optional'?: boolean;
     immutable?: boolean;
+    prune?: boolean;
     'refresh-lockfile'?: boolean;
     verbose: boolean;
     quiet?: boolean;

package/lib/commands/install.js

@@ -32,6 +32,8 @@ import { nodeBinary } from '../utils/run-node.js';
 import { spawnToCompletion } from '../utils/spawn.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { binDirOnPath, BUNDLER_ENGINE_PACKAGE, defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
+import { resolveHostPlatform } from '../utils/platform-check.js';
+import { pruneAfterInstall } from '../utils/prune-prefix.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 /**
  * Link type for the workspace↔workspace directory links.
@@ -125,6 +127,11 @@ export const installCommand = {
         description: 'Install a REQUIRED dependency even when its os/cpu/libc excludes the target, instead of failing with EBADPLATFORM (npm config key `force`). Incompatible OPTIONAL dependencies stay skipped — npm ignores --force for those too, and a binary that cannot load is not worth downloading.',
         type: 'boolean',
         default: false,
+    })
+        .option('prune', {
+        description: 'After installing, remove packages an earlier install left behind that this host cannot use (foreign os/cpu/libc). Use --no-prune to disable. Skipped automatically under --immutable, and whenever --os/--cpu/--libc is given: an install must never delete against a target the user typed.',
+        type: 'boolean',
+        default: true,
     }),
     handler: async (args) => {
         // Must run before anything resolves — `--os/--cpu/--libc/--force` are npm
@@ -161,7 +168,7 @@ export const installCommand = {
                     console.warn(`gjsify install --global ignores --${flag}: global installs do not modify a project package.json.`);
                 }
             }
-            await installGlobalAndLink(args.packages, { verbose: args.verbose });
+            await installGlobalAndLink(args.packages, { verbose: args.verbose, prune: args.prune });
             return;
         }
         // Before the heavy install, so the skew is visible even if a later phase
@@ -170,6 +177,7 @@ export const installCommand = {
         const backend = args.backend ?? process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
         if (backend === 'npm') {
             await projectInstallViaNpm(args);
+            pruneProjectPrefix(args);
             await runPostInstallChecks(args);
             return;
         }
@@ -217,6 +225,7 @@ export const installCommand = {
         hardExitTimerId?.unref?.();
         try {
             await projectInstallNative(args, overallController?.signal);
+            pruneProjectPrefix(args);
             await runPostInstallChecks(args);
         }
         catch (err) {
@@ -1198,6 +1207,14 @@ async function installGlobalAndLink(specs, opts) {
             const cliVersion = result.installed.find((r) => r.name === '@gjsify/cli')?.version ?? 'latest';
             await installGjsEnginePackages(layout.prefix, cliVersion, { verbose: opts.verbose });
         }
+        // Before the LINK on purpose: `linkGlobalBins`' launchers bake the resolved
+        // prebuild directories into GI_TYPELIB_PATH/LD_LIBRARY_PATH, and must not name
+        // a directory this pass is about to delete.
+        if (opts.prune !== false) {
+            pruneAfterInstall(layout.prefix, resolveHostPlatform({ env: {} }), {
+                hint: 'gjsify prune -g --dry-run',
+            });
+        }
         const created = linkGlobalBins(packageNames, layout);
         reportLinkedBins(created, layout.binDir);
     }
@@ -1205,6 +1222,20 @@ async function installGlobalAndLink(specs, opts) {
         lock.release();
     }
 }
+/**
+ * The automatic pass for a PROJECT prefix.
+ *
+ * Hooked at the command level rather than inside `installPackages`, so `dlx`'s
+ * throwaway cache prefix — created, used once and dropped — pays nothing for it.
+ */
+function pruneProjectPrefix(args) {
+    if (args.prune === false)
+        return;
+    pruneAfterInstall(process.cwd(), resolveHostPlatform({ env: {} }), {
+        immutable: args.immutable === true,
+        hint: 'gjsify prune --dry-run',
+    });
+}
 function reportLinkedBins(created, binDir) {
     if (created.length === 0) {
         console.warn('\nNo bins declared (neither `gjsify.bin` nor `bin` in package.json) — nothing was symlinked.');

package/lib/commands/prune.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from '../types/index.js';
+interface PruneOptions {
+    global: boolean;
+    dryRun: boolean;
+    verbose: boolean;
+    os?: string;
+    cpu?: string;
+    libc?: string;
+}
+export declare const pruneCommand: Command<unknown, PruneOptions>;
+export {};