@gjsify/cli 0.40.0 → 0.42.0

package/lib/commands/tsc.js

@@ -17,7 +17,6 @@
 // if the dep was removed or the consumer is running a forked CLI.
 //
 // Reference: packages/infra/cli/src/commands/run.ts (env-setup precedent).
-import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -27,6 +26,7 @@ import { existsSync } from 'node:fs';
 import { forceExit } from '../utils/force-exit.js';
 import { nodeBinary } from '../utils/run-node.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { spawnToCompletion } from '../utils/spawn.js';
 export const tscCommand = {
     command: 'tsc [tscArgs..]',
     description: 'Run TypeScript compiler (tsc) under GJS via the @gjsify/tsc bundle. All arguments are passed through to tsc. Equivalent to `gjsify-tsc <args>` from the @gjsify/tsc bin.',
@@ -139,7 +139,7 @@ export const tscCommand = {
         // fallback below is the NORMAL path there, not an edge case.
         // `run-node.ts` owns the one correct answer; every other spawn site in
         // this CLI already routes through it.
-        const runNodeTsc = () => {
+        const runNodeTsc = async () => {
             const nodeBin = nodeBinary();
             // PRE-FLIGHT, deliberately NOT the spawn's `'error'` event.
             //
@@ -161,64 +161,115 @@ export const tscCommand = {
                 console.error('  …or install Node.js so the upstream `typescript` fallback can be spawned.');
                 return forceExit(1);
             }
-            const child = spawn(nodeBin, [nodeTscPath, ...tscArgs], { env, stdio: 'inherit' });
-            child.on('close', (code) => forceExit(code ?? 1));
-            child.on('error', (err) => {
-                if (err.code === 'ENOENT') {
+            // `forceExit` runs from the child's own `'close'` DISPATCH, never from a
+            // promise continuation — which is why this awaits a promise that only
+            // ever REJECTS instead of `await`ing the completion.
+            //
+            // Under GJS `forceExit` ends the process by THROWING SpiderMonkey's
+            // uncatchable exit exception. Thrown inside an `await` continuation that
+            // exception is captured by the async machinery as a rejection rather than
+            // unwinding the stack, so nothing exits — and the GLib main loop the spawn
+            // armed then keeps the process alive with nothing left to quit it.
+            // Measured: `gjsify tsc --version` printed `Version 6.0.3` and hung
+            // forever, which in CI is a 30-minute step timeout.
+            try {
+                await new Promise((_never, reject) => {
+                    void spawnToCompletion(nodeBin, [nodeTscPath, ...tscArgs], {
+                        completion: 'exit',
+                        env,
+                        onSpawn: (child) => {
+                            // A FAILED spawn emits both `'error'` and `'close'`, and
+                            // that `'close'` carries the SPAWN ERRNO rather than an
+                            // exit status — win32 ENOENT is -4058, which reached the
+                            // shell as 4294963238 and took every Windows build down
+                            // with it. Exiting on it would also pre-empt the Node
+                            // fallback. This is the race the old `gjsSpawnFailed`
+                            // flag existed to break; deleting the flag deleted the
+                            // property, so it is back, with its measurement.
+                            let spawnFailed = false;
+                            child.on('error', () => {
+                                spawnFailed = true;
+                            });
+                            child.on('close', (code) => {
+                                if (!spawnFailed)
+                                    forceExit(code ?? 1);
+                            });
+                        },
+                    }).catch(reject);
+                });
+            }
+            catch (err) {
+                const e = err;
+                if (e.code === 'ENOENT') {
                     console.error('gjsify tsc: the @gjsify/tsc GJS bundle is unavailable and `node` is not on PATH, ' +
                         'so upstream `typescript` cannot run either.');
                     console.error('  Build the bundle with: gjsify workspace @gjsify/tsc build');
                 }
                 else {
-                    console.error(`gjsify tsc (node typescript): ${err.message}`);
+                    console.error(`gjsify tsc (node typescript): ${e.message}`);
                 }
-                forceExit(1);
-            });
+                return forceExit(1);
+            }
         };
         // Prefer GJS — the Node-free @gjsify/tsc bundle — when it resolves. If
         // `gjs` is not on PATH (ENOENT), transparently fall back to upstream
         // `typescript` under Node when available.
         if (bundlePath) {
-            // A failed spawn (notably ENOENT when `gjs` is absent) emits BOTH
-            // 'error' AND 'close'. The 'error' handler owns the outcome (Node
-            // fallback or a clear exit), so the 'close' handler must NOT also
-            // exit — otherwise it races and exits with the spawn errno (e.g.
-            // ENOENT → -2), which surfaced as a misleading 254 and pre-empted the
-            // fallback (gjsify tsc died instead of degrading to upstream tsc on a
-            // gjs-less host such as a CI runner).
-            let gjsSpawnFailed = false;
-            const child = spawn('gjs', ['-m', bundlePath, ...tscArgs], { env, stdio: 'inherit' });
-            await new Promise((resolvePromise) => {
-                child.on('close', (code) => {
-                    if (gjsSpawnFailed)
-                        return;
-                    forceExit(code ?? 1);
-                });
-                child.on('error', (err) => {
-                    gjsSpawnFailed = true;
-                    if (err.code === 'ENOENT' && nodeTscPath) {
-                        // No gjs on PATH — run upstream typescript under Node.
-                        runNodeTsc();
-                    }
-                    else if (err.code === 'ENOENT') {
-                        console.error('gjsify tsc: `gjs` not found on PATH and no npm `typescript` fallback.');
-                        console.error('  Install GJS (e.g. `dnf install gjs`), or add `typescript` to the project.');
-                        forceExit(1);
-                    }
-                    else {
-                        console.error(`gjsify tsc: ${err.message}`);
-                        forceExit(1);
-                    }
+            // A raw failed spawn (notably ENOENT when `gjs` is absent) emits BOTH
+            // 'error' AND 'close', and the two raced: the 'close' handler exited
+            // with the spawn errno (ENOENT → -2, surfacing as a misleading 254)
+            // and pre-empted the Node fallback, so `gjsify tsc` died instead of
+            // degrading to upstream tsc on a gjs-less host such as a CI runner. A
+            // promise cannot both reject and resolve, so routing through
+            // `spawnToCompletion` makes that race structurally impossible rather
+            // than guarded by a flag.
+            // Same shape, and the same reason, as `runNodeTsc` above: exit from the
+            // child's `'close'` dispatch, await a promise that only rejects.
+            try {
+                await new Promise((_never, reject) => {
+                    void spawnToCompletion('gjs', ['-m', bundlePath, ...tscArgs], {
+                        completion: 'exit',
+                        env,
+                        onSpawn: (child) => {
+                            // A FAILED spawn emits both `'error'` and `'close'`, and
+                            // that `'close'` carries the SPAWN ERRNO rather than an
+                            // exit status — win32 ENOENT is -4058, which reached the
+                            // shell as 4294963238 and took every Windows build down
+                            // with it. Exiting on it would also pre-empt the Node
+                            // fallback. This is the race the old `gjsSpawnFailed`
+                            // flag existed to break; deleting the flag deleted the
+                            // property, so it is back, with its measurement.
+                            let spawnFailed = false;
+                            child.on('error', () => {
+                                spawnFailed = true;
+                            });
+                            child.on('close', (code) => {
+                                if (!spawnFailed)
+                                    forceExit(code ?? 1);
+                            });
+                        },
+                    }).catch(reject);
                 });
-                // Never resolves naturally — process.exit() above terminates the
-                // program once the child closes. The promise just keeps the
-                // handler alive while the child runs.
-                void resolvePromise;
-            });
+            }
+            catch (err) {
+                const e = err;
+                if (e.code === 'ENOENT' && nodeTscPath) {
+                    // No gjs on PATH — run upstream typescript under Node.
+                    return await runNodeTsc();
+                }
+                if (e.code === 'ENOENT') {
+                    console.error('gjsify tsc: `gjs` not found on PATH and no npm `typescript` fallback.');
+                    console.error('  Install GJS (e.g. `dnf install gjs`), or add `typescript` to the project.');
+                }
+                else {
+                    console.error(`gjsify tsc: ${e.message}`);
+                }
+                return forceExit(1);
+            }
         }
         else {
             // No GJS bundle resolvable — go straight to the Node fallback.
-            runNodeTsc();
+            await runNodeTsc();
         }
     },
 };

package/lib/config.js

@@ -38,6 +38,10 @@ async function loadConfigViaGjsBundle(filepath, verbose) {
             // import.meta.url)), 'package.json'))`) relative to ITS OWN location.
             // Bake the original config's URL so those reads hit the real dir.
             define: { 'import.meta.url': JSON.stringify(pathToFileURL(filepath).href) },
+            // A config file is evaluated INSIDE the CLI process — toolchain by
+            // construction, so a `@gjsify/*` the project cannot resolve may come
+            // from the CLI's own install.
+            resolveFromToolchain: true,
         });
     }
     catch (bundleErr) {

package/lib/templates/install.mjs.tmpl

@@ -188,9 +188,14 @@ function checkGjsVersion() {
     if (major < 1 || (major === 1 && minor < 86)) {
         error(`gjs ${major}.${minor} is too old — gjsify requires gjs 1.86 or newer.`);
         error('Install hints:');
-        error('  Fedora 43+:  sudo dnf install gjs');
-        error('  Debian 13+:  sudo apt install gjs');
-        error('  Arch:        sudo pacman -S gjs');
+        error('  Fedora 43+:      sudo dnf install gjs');
+        error('  Arch:            sudo pacman -S gjs');
+        // NOT "Debian 13+". Measured 2026-08-16 against tracker.debian.org: trixie
+        // (13, stable) ships 1.82.3, forky (testing) 1.88.1, sid 1.89.2 — 1.84 and
+        // 1.86 were skipped entirely. Sending a trixie user to `apt install gjs`
+        // hands them the very version this branch just rejected, from the branch
+        // that rejected it. Same fact, same wording as `utils/ship/depends.ts`.
+        error('  Debian forky/sid: sudo apt install gjs   (trixie ships 1.82.3 — too old)');
         exit(1);
     }
 }

package/lib/types/config-data.d.ts

@@ -433,6 +433,33 @@ export interface ConfigDataShip extends AppMetadata {
         deb: string;
         rpm: string;
     }>;
+    /**
+     * Directories whose `*.typelib` and `lib*.so*` the package CARRIES ITSELF, e.g.
+     * `["../node_modules/@gjsify/webgl-linux-x64/prebuilds/linux-x64"]`.
+     *
+     * gjsify's own GI libraries — `Gwebgl`, the GTK runtime bundles, the napi host — arrive as npm
+     * prebuilds, not as distro packages, so an app that imports one has no `gir1.2-…` to depend on.
+     * Staging them here puts them in `lib/<binary>/gi/` and makes the launcher point
+     * `GI_TYPELIB_PATH` and `LD_LIBRARY_PATH` at that directory.
+     *
+     * The namespaces this covers are read back off the STAGED FILES, not from a separate list:
+     * a declaration that a namespace is bundled, without the file being there, is exactly the lie
+     * the dependency check exists to prevent.
+     */
+    bundledTypelibs?: string[];
+    /**
+     * Directory holding COMPILED gettext catalogues in the layout `bindtextdomain` reads —
+     * `<lang>/LC_MESSAGES/<domain>.mo` — e.g. `"dist/locale"`, which is what
+     * `@gjsify/vite-plugin-gettext`'s `gettextPlugin` writes by default.
+     *
+     * Staged into `share/locale/` with that structure preserved, and the launcher then exports
+     * `GJSIFY_LOCALE_DIR` so the app can call `bindtextdomain(domain, dir)` without knowing which
+     * prefix it was installed under.
+     *
+     * `.po` sources are NOT accepted: `bindtextdomain` reads `.mo` only, and staging a `.po`
+     * produces a package that installs its translations and shows none of them.
+     */
+    localeDir?: string;
     /** Extra payload entries: prefix-relative destination → project-relative source. */
     extraFiles?: Record<string, string>;
     /** Arguments the launcher appends before the user's own. */

package/lib/utils/app-metadata.js

@@ -13,15 +13,36 @@
 // attributes, provides) has too many optional nested sections for a
 // template+placeholder approach to stay legible. The `.desktop` entry stays
 // template-based — it is flat `key=value`.
-import { readFileSync } from 'node:fs';
 /**
- * Lazy template loader. `static-read-inliner` matches this exact shape
- * (`readFileSync(new URL(<literal>, import.meta.url), 'utf-8')`) and inlines
- * the template into the GJS bundle at build time — a `join(__dirname, …)`
- * spelling silently loses that and ENOENTs under GJS.
+ * The `.desktop` skeleton, as source rather than as a file to find at runtime.
+ *
+ * It used to live in `src/templates/app/desktop.tmpl` and be read through
+ * `readFileSync(new URL(…, import.meta.url))`, with a comment stating that
+ * `static-read-inliner` inlines it into the GJS bundle. It does not: the
+ * inliner's `shouldRewrite` requires the file to sit under `node_modules`, and
+ * the CLI bundles its OWN source. So the read survived into
+ * `dist/cli.gjs.mjs`, resolved `../templates/…` against `dist/`, and
+ * `gjsify ship` died with ENOENT on every project — while the Node `lib/`
+ * entry, where the relative path happens to be right, worked. A comment
+ * asserting the opposite is why it went unnoticed.
+ *
+ * A ten-line skeleton is not worth a file the bundle has to locate. As a
+ * template literal there is nothing to resolve, nothing to package, and the
+ * two entry points cannot disagree.
  */
+const DESKTOP_TEMPLATE = `[Desktop Entry]
+Name={{NAME}}
+Comment={{SUMMARY}}
+Exec={{COMMAND}}
+Icon={{APP_ID}}
+Terminal=false
+Type=Application
+Categories={{CATEGORIES_LINE}}
+{{KEYWORDS_LINE}}{{MIMETYPES_LINE}}StartupNotify=true
+StartupWMClass={{APP_ID}}
+`;
 function loadDesktopTemplate() {
-    return readFileSync(new URL('../templates/app/desktop.tmpl', import.meta.url), 'utf-8');
+    return DESKTOP_TEMPLATE;
 }
 /**
  * Validate that the metadata has the minimum set of fields AppStream needs.

package/lib/utils/check-system-deps.d.ts

@@ -126,8 +126,8 @@ export declare const PACKAGE_DEPS: Record<string, string[]>;
  */
 export declare function runAllChecks(cwd: string): DepCheck[];
 /**
- * Minimal checks needed to run any GJS example (Node + GJS binaries only).
- * Used by `gjsify showcase` for examples that have no native deps.
+ * Minimal checks needed to run any GJS example (the GJS binary; Node is reported but
+ * not required). Used by `gjsify showcase` for examples that have no native deps.
  */
 export declare function runMinimalChecks(): DepCheck[];
 /**

package/lib/utils/check-system-deps.js

@@ -18,6 +18,8 @@ import { readFileSync, existsSync, readdirSync } from 'node:fs';
 // The zero-dependency subpath, deliberately: importing the plugin root would
 // pull vite/execa/minify-xml into a system CHECK.
 import { resolveBlueprintCompiler } from '@gjsify/vite-plugin-blueprint/resolve';
+import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { findSystemTypelib } from './gi-typelib.js';
 /** Run a binary and return its stdout trimmed, or null if it fails. */
 function tryExecFile(binary, args) {
     try {
@@ -78,6 +80,35 @@ function checkPkgConfig(id, name, libName, severity, requiredBy) {
         return { id, name, found: false, severity, requiredBy };
     return { id, name, found: true, version: version.split('\n')[0], severity, requiredBy };
 }
+/**
+ * Check a GI library the way a RUNNING app needs it: by its typelib.
+ *
+ * `checkPkgConfig` answers a different question — "is the DEVELOPMENT package
+ * installed" — and for a library an app merely loads, that question has the
+ * wrong answer on every distribution that splits `-dev` out. Measured on
+ * postmarketOS v26.06 / aarch64 (OnePlus 6T, gjs 1.88.1): libadwaita 1.9.2
+ * installed, `Adw-1.typelib` present, Adwaita apps running, and `system-check`
+ * printing `✗ libadwaita` under **Required** and exiting 1 because
+ * `libadwaita-dev` was absent. The install hint then named a package the user
+ * had no reason to install.
+ *
+ * So PRESENCE comes from {@link findSystemTypelib} — the same file
+ * `gi_repository_require()` resolves — and the VERSION still comes from
+ * pkg-config, which is a perfectly good version oracle when it happens to be
+ * there. A bare `✓ libadwaita` with no version is the honest reading of "the
+ * library is here and the `.pc` file is not"; `✗` was not.
+ *
+ * pkg-config remains the sole oracle for anything whose subject genuinely IS the
+ * development package (`gobject-introspection-1.0` gates `g-ir-scanner`, a build
+ * tool with no typelib of its own).
+ */
+function checkGiLibrary(id, name, namespace, apiVersion, pkgConfigName, severity, requiredBy) {
+    const found = findSystemTypelib(namespace, apiVersion) !== null;
+    if (!found)
+        return { id, name, found: false, severity, requiredBy };
+    const version = tryExecFile('pkg-config', ['--modversion', pkgConfigName]);
+    return { id, name, found: true, version: version?.split('\n')[0], severity, requiredBy };
+}
 /**
  * Check for an npm package. Tries the user's project first (cwd), then falls
  * back to the CLI's own node_modules. This way a locally installed version
@@ -378,13 +409,41 @@ export function runAllChecks(cwd) {
     ];
 }
 /**
- * Minimal checks needed to run any GJS example (Node + GJS binaries only).
- * Used by `gjsify showcase` for examples that have no native deps.
+ * Is a Node.js runtime available — asked of the host rather than asserted.
+ *
+ * This row used to be the literal `{found: true, version: process.version}`, which is
+ * a lie on three of the four hosts: `@gjsify/process` stubs `process.version` to
+ * `"v20.0.0"` for npm compatibility (Bun and Deno fake `process.versions.node` for the
+ * same reason), so `gjsify system-check` under GJS reported `✓ Node.js (v20.0.0)` on a
+ * machine with no Node on it — under the NODE-FREE toolchain, whose entire premise is
+ * that there is none. `cli-app.ts`'s `runtimeLabel()` already had to know better; one
+ * question gets one answer, so this asks the same module.
+ *
+ * Under Node the running process IS the answer and its version cannot be faked from
+ * inside; elsewhere it is a PATH question whose answer may legitimately be "no".
+ *
+ * `isNode()` rather than `hostRuntime() === 'node'`: the latter RETURNS `'node'` as its
+ * fallback for an unrecognised host, which would put an exotic runtime's possibly-stubbed
+ * `process.version` on the trusted branch. `isNode()` demands positive evidence.
+ *
+ * `optional`, never `required`: `gjsify showcase` and `gjsify install` both treat a
+ * missing `required` row as fatal, and a GJS showcase needs no Node. The old row could
+ * not have failed either gate — it was constant — so nothing that used to pass now
+ * fails; what changes is only that the printed line is true.
+ */
+function checkNodeRuntime() {
+    if (isNode()) {
+        return { id: 'nodejs', name: 'Node.js', found: true, version: process.version, severity: 'optional' };
+    }
+    return checkBinary('nodejs', 'Node.js', 'node', ['--version'], 'optional');
+}
+/**
+ * Minimal checks needed to run any GJS example (the GJS binary; Node is reported but
+ * not required). Used by `gjsify showcase` for examples that have no native deps.
  */
 export function runMinimalChecks() {
     const results = [];
-    // Node.js — always present
-    results.push({ id: 'nodejs', name: 'Node.js', found: true, version: process.version, severity: 'required' });
+    results.push(checkNodeRuntime());
     // GJS
     results.push(checkBinary('gjs', 'GJS', 'gjs', ['--version'], 'required', (out) => out.replace(/^GJS\s+/i, '').split('\n')[0] ?? out));
     // The one win32 system dependency that is real and was undiagnosed (#997).
@@ -433,14 +492,21 @@ export function checkGwebgl(cwd) {
  */
 function runRequiredChecks(_cwd) {
     const results = [];
-    // Build toolchain
-    results.push(checkBinary('blueprint-compiler', 'Blueprint Compiler', 'blueprint-compiler', ['--version'], 'required'));
+    // Build toolchain. NO blueprint-compiler here: it is checked by
+    // `checkBlueprintCompiler()` among the build toolchain below, through the
+    // SAME resolver the build uses. A second `checkBinary` probe lived here and
+    // was wrong twice over — it reported a PATH miss on win32, where the
+    // compiler is normally an MSYS2 script deliberately off PATH (the exact case
+    // that function's comment exists to explain), and it made `system-check`
+    // exit 1 on any host without it, `.blp` files in the project or not. It also
+    // printed a second entry under a second display name and put
+    // `blueprint-compiler` into the install hint twice.
     results.push(checkBinary('pkg-config', 'pkg-config', 'pkg-config', ['--version'], 'required'));
     results.push(checkBinary('meson', 'Meson', 'meson', ['--version'], 'required'));
-    // Foundational libraries
-    results.push(checkPkgConfig('gtk4', 'GTK4', 'gtk4', 'required'));
-    results.push(checkPkgConfig('libadwaita', 'libadwaita', 'libadwaita-1', 'required'));
-    results.push(checkPkgConfig('libsoup3', 'libsoup3', 'libsoup-3.0', 'required'));
+    // Foundational libraries — by TYPELIB, the runtime question. See checkGiLibrary.
+    results.push(checkGiLibrary('gtk4', 'GTK4', 'Gtk', '4.0', 'gtk4', 'required'));
+    results.push(checkGiLibrary('libadwaita', 'libadwaita', 'Adw', '1', 'libadwaita-1', 'required'));
+    results.push(checkGiLibrary('libsoup3', 'libsoup3', 'Soup', '3.0', 'libsoup-3.0', 'required'));
     results.push(checkPkgConfig('gobject-introspection', 'GObject Introspection', 'gobject-introspection-1.0', 'required'));
     return results;
 }
@@ -528,6 +594,7 @@ function runOptionalChecks(needed, cwd) {
 // Entries with multiple space-separated packages are intentional (one dep needs multiple system pkgs).
 const PM_PACKAGES = {
     apt: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
@@ -553,6 +620,7 @@ const PM_PACKAGES = {
         epoxy: 'libepoxy-dev',
     },
     dnf: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf-pkg-config',
@@ -578,6 +646,7 @@ const PM_PACKAGES = {
         epoxy: 'libepoxy-devel',
     },
     pacman: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
@@ -603,6 +672,7 @@ const PM_PACKAGES = {
         epoxy: 'libepoxy',
     },
     zypper: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkg-config',
@@ -628,6 +698,7 @@ const PM_PACKAGES = {
         epoxy: 'libepoxy-devel',
     },
     apk: {
+        nodejs: 'nodejs',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
@@ -675,6 +746,7 @@ const PM_PACKAGES = {
     // Recorded here so the next reader does not "fix" the gap by guessing a name;
     // both are genuine platform gaps, not table omissions.
     brew: {
+        nodejs: 'node',
         gjs: 'gjs',
         'blueprint-compiler': 'blueprint-compiler',
         'pkg-config': 'pkgconf',
@@ -750,15 +822,22 @@ export function buildInstallCommand(pm, missing) {
                 'mingw-w64-ucrt-x86_64-libadwaita   # inside MSYS2; found automatically afterwards');
             continue;
         }
-        if (dep.id === 'nodejs')
-            continue; // can't be missing if we're running
+        // No `continue` for `nodejs`. It USED to be unmissable — the row was the
+        // literal `found: true` — and since it became a real probe it can report
+        // absent under GJS, so skipping it here printed "Missing optional: Node.js"
+        // above an install command that did not install it.
         const pkg = pkgMap[dep.id];
         if (pkg)
             pkgs.push(pkg);
     }
     const lines = [];
     if (pkgs.length > 0) {
-        lines.push(`${PM_INSTALL_PREFIX[pm]} ${pkgs.join(' ')}`);
+        // Deduplicated because the command is COPY-PASTED: two checks mapping to
+        // one system package (or one check reported under two ids) produced
+        // `apk add blueprint-compiler libadwaita-dev … blueprint-compiler`,
+        // which is how the duplicate blueprint check first became visible.
+        // Dropping the second occurrence cannot change what gets installed.
+        lines.push(`${PM_INSTALL_PREFIX[pm]} ${[...new Set(pkgs)].join(' ')}`);
     }
     if (npmDeps.length > 0) {
         lines.push(`npm install ${npmDeps.join(' ')}`);

package/lib/utils/daemon-command.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Declare that this command keeps running after its handler resolves, so a
+ * caller must not treat that resolution as completion.
+ */
+export declare function markDaemonCommand(): void;
+/** Whether a command dispatched in this process declared itself a daemon. */
+export declare function isDaemonCommand(): boolean;

package/lib/utils/daemon-command.js

@@ -0,0 +1,30 @@
+// Whether the command currently running SETTLES.
+//
+// Almost every gjsify command finishes: its handler resolves and the caller acts
+// on the result. A watch loop does not — `runWatchLoop` resolves as soon as the
+// watcher is armed and the process then lives on the watcher (Node) or the held
+// main loop (GJS) until Ctrl+C. To anything that merely awaits the handler the
+// two are the same event, and one caller has to tell them apart: `gjsify run`'s
+// in-process fast path dispatches a `gjsify <sub>` script through the same yargs
+// surface and then `process.exit()`s on the result. For `gjsify run dev` that
+// exit fired the instant the first build+launch was done, killing the loop the
+// script had just asked for — and that IS the documented entry point (`gjsify
+// create` prints `gjsify run dev`, and every template's `dev` script is a bare
+// `gjsify dev`). Invisible on Node, where the same script takes the spawn path.
+//
+// A module-level flag rather than a return value because the answer has to cross
+// `runCli`, whose contract is `Promise<void>` for every command; threading a
+// "did not settle" result through yargs would change the shape of all of them to
+// carry a fact about one.
+let daemon = false;
+/**
+ * Declare that this command keeps running after its handler resolves, so a
+ * caller must not treat that resolution as completion.
+ */
+export function markDaemonCommand() {
+    daemon = true;
+}
+/** Whether a command dispatched in this process declared itself a daemon. */
+export function isDaemonCommand() {
+    return daemon;
+}

package/lib/utils/dev-plan.d.ts

@@ -0,0 +1,52 @@
+export interface DevPlanRequest {
+    /** The project's `package.json#scripts`. */
+    scripts: Readonly<Record<string, string>>;
+    /** Name of the build script to reuse, e.g. `build:gjs`. */
+    scriptName: string;
+    /** `gjsify build --app <app>` target the chosen runtime consumes. */
+    app: 'gjs' | 'node';
+    /** The bundle the package declares for `app` (`gjsify.main` / `gjsify.example.node`). */
+    declaredBundle?: string;
+    /** `gjsify dev [entry]` — overrides the entry point the script names. */
+    entry?: string;
+    /** `--globals` override. */
+    globals?: string;
+    /** `--outfile` override. */
+    outfile?: string;
+    /** `--watch-dir` override. */
+    watchDir?: string;
+}
+export interface DevPlan {
+    /** argv fed to `runCli` on every rebuild (starts with `build`). */
+    buildArgv: string[];
+    /**
+     * Bundle launched after a successful build, or undefined when nothing names
+     * one. See {@link noBundleError}.
+     */
+    bundle?: string;
+    /** Directory watched recursively. */
+    watchDir: string;
+}
+/** The value of `--name value` / `--name=value` in `argv`, if present. */
+export declare function readFlag(argv: readonly string[], name: string): string | undefined;
+/** `argv` with `--name value` set — replacing any existing occurrence, else appended. */
+export declare function withFlag(argv: readonly string[], name: string, value: string): string[];
+/**
+ * The entry point a `gjsify build` argv names positionally. Only the token
+ * DIRECTLY after `build` counts: further positionals are indistinguishable from
+ * the value of a preceding flag without knowing every flag's arity, and a wrong
+ * guess here would silently build the wrong file.
+ */
+export declare function buildEntryPoint(argv: readonly string[]): string | undefined;
+/**
+ * Resolve the build argv, the bundle to launch and the directory to watch.
+ * Throws with both fixes named when the project declares neither.
+ */
+export declare function planDev(req: DevPlanRequest): DevPlan;
+/**
+ * Message for a launch that has no bundle to launch. Separate from `planDev`
+ * because only the LAUNCHING caller needs one: a build writing an `--outdir`
+ * legitimately has no single output file, and refusing inside the planner would
+ * fail `--build-only` for a reason that does not apply to it.
+ */
+export declare function noBundleError(scriptName: string, app: 'gjs' | 'node'): Error;