@gjsify/cli 0.41.0 → 0.43.0

package/lib/commands/storybook.js

@@ -16,7 +16,6 @@
 // identically under Node and GJS. @gjsify/storybook is resolved from the
 // CONSUMER's node_modules by the generated entry, so it stays out of the CLI's
 // own dependencies.
-import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
@@ -165,18 +164,18 @@ export const storybookCommand = {
         const launch = async () => {
             if (runtime === 'gjs') {
                 const { runGjsBundle } = await import('../utils/run-gjs.js');
-                await runGjsBundle(outPath, [], { exitOnSuccess: true });
+                await runGjsBundle(outPath, [], { completion: 'exit', exitOnSuccess: true });
             }
             else if (runtime === 'node') {
                 const { runNodeBundle } = await import('../utils/run-node.js');
-                await runNodeBundle(outPath, [], { exitOnSuccess: true });
+                await runNodeBundle(outPath, [], { completion: 'exit', exitOnSuccess: true });
             }
             else {
                 // bun / deno — run the SAME `--app node` bundle via the shared
                 // runner (Node-API is their common ABI). node-gi is required
                 // because the storybook uses gi:// (checked in runRuntimeBundle).
                 const { runRuntimeBundle } = await import('../utils/run-node.js');
-                await runRuntimeBundle(runtime, outPath, [], { exitOnSuccess: true });
+                await runRuntimeBundle(runtime, outPath, [], { completion: 'exit', exitOnSuccess: true });
             }
         };
         if (!args.watch) {
@@ -186,77 +185,21 @@ export const storybookCommand = {
             await launch();
             return;
         }
-        // Watch mode: rebuild + relaunch on any change under the stories dir.
-        // The storybook bundle only needs system Gtk/Adw typelibs at runtime
-        // (no @gjsify native bridges), so a plain `gjs -m` / `node` child is
-        // enough and stays killable for relaunch.
-        const { watch } = await import('node:fs');
-        const spawnChild = async () => {
-            if (runtime === 'gjs') {
-                return spawn('gjs', ['-m', outPath], { stdio: 'inherit' });
-            }
-            // node / bun / deno — run the `--app node` bundle with the native
-            // typelib env wired like `gjsify run`. All three need @gjsify/node-gi
-            // (the storybook uses gi://), kept external by the bundler.
-            const { computeNativeEnvForBundle } = await import('../utils/run-gjs.js');
-            const { resolveNodeGiForBundle, nodeBinary } = await import('../utils/run-node.js');
-            const { RUNTIMES } = await import('../utils/runtimes.js');
-            // Same resolution base as `runRuntimeBundle`: the bundle's own dir
-            // first (that is where the runtime resolves the external specifier
-            // from), cwd as the fallback.
-            if (!resolveNodeGiForBundle(outPath, cwd)) {
-                throw new Error(`Cannot run the storybook on ${runtime}: \`@gjsify/node-gi\` is not installed. ` +
-                    `Add @gjsify/node-gi as a dependency to run the storybook on ${runtime}.`);
-            }
-            const { env: nativeEnv } = computeNativeEnvForBundle(outPath, cwd);
-            const env = { ...process.env, ...nativeEnv };
-            // `node` uses the resolved node binary (under a GJS-hosted CLI
-            // `process.execPath` is gjs); bun/deno launch via the shared spec
-            // (deno's `--node-modules-dir=manual`, etc.).
-            if (runtime === 'node') {
-                return spawn(nodeBinary(), [outPath], { stdio: 'inherit', env });
-            }
-            const [cmd, launchArgs] = RUNTIMES[runtime].launch(outPath);
-            return spawn(cmd, launchArgs, { stdio: 'inherit', env });
-        };
-        let child = null;
-        let rebuilding = false;
-        let pending = false;
-        const rebuild = async () => {
-            if (rebuilding) {
-                pending = true;
-                return;
-            }
-            rebuilding = true;
-            try {
+        // Watch mode: rebuild + relaunch on any change under the stories dir,
+        // through the loop shared with `gjsify dev` (`utils/watch-loop.ts`).
+        const { runWatchLoop, spawnBundleSupervised } = await import('../utils/watch-loop.js');
+        await runWatchLoop({
+            dir: storiesDir,
+            dirLabel: relative(cwd, storiesDir) || '.',
+            label: 'storybook',
+            // Stories are DISCOVERED, so the generated entry is re-derived on
+            // every pass — a new `*.story.ts` must show up without a restart.
+            prepare: () => {
                 writeEntry();
-                if (child) {
-                    child.kill();
-                    child = null;
-                }
-                await buildBundle();
-                if (!args.buildOnly) {
-                    child = await spawnChild();
-                }
-            }
-            catch (err) {
-                console.error(`[storybook] rebuild failed: ${err.message}`);
-            }
-            finally {
-                rebuilding = false;
-                if (pending) {
-                    pending = false;
-                    void rebuild();
-                }
-            }
-        };
-        await rebuild();
-        let debounce = null;
-        watch(storiesDir, { recursive: true }, () => {
-            if (debounce)
-                clearTimeout(debounce);
-            debounce = setTimeout(() => void rebuild(), 200);
+            },
+            build: buildBundle,
+            spawnChild: args.buildOnly ? null : () => spawnBundleSupervised(runtime, outPath, cwd, 'the storybook'),
+            output: outPath,
         });
-        console.log(`[storybook] watching ${relative(cwd, storiesDir) || '.'} — press Ctrl+C to stop`);
     },
 };

package/lib/commands/test.js

@@ -7,9 +7,9 @@
 // exit codes.
 import { existsSync, statSync, readdirSync } from 'node:fs';
 import { join, dirname, resolve, relative } from 'node:path';
-import { spawn } from 'node:child_process';
 import { isRuntimeAvailable, RUNTIMES } from '../utils/runtimes.js';
 import { nodeBinary } from '../utils/run-node.js';
+import { describeExit, spawnToCompletion } from '../utils/spawn.js';
 import { Config } from '../config.js';
 import { BuildAction } from '../actions/build.js';
 import { runGjsBundle } from '../utils/run-gjs.js';
@@ -190,23 +190,19 @@ async function buildTestBundle(entry, outfile, runtime, verbose) {
 /** Run a single test bundle and reject on non-zero exit. */
 async function runTestBundle(outfile, runtime) {
     if (runtime === 'gjs') {
-        await runGjsBundle(outfile);
+        // `completion: 'exit'` (this handler ends in `process.exit`) WITHOUT
+        // `exitOnSuccess`: the two answer different questions, and exiting here
+        // would truncate the multi-runtime loop after the first bundle.
+        await runGjsBundle(outfile, [], { completion: 'exit' });
         return;
     }
-    await new Promise((resolvePromise, reject) => {
-        // `nodeBinary()`, never a bare `'node'`: under GJS `process.execPath` is
-        // the `gjs` interpreter, which cannot run a `--app node` bundle, and on a
-        // host without Node a bare literal dies `spawn node ENOENT` — which is
-        // how a fully passing GJS suite was reported as a failed run.
-        const child = spawn(nodeBinary(), [outfile], { stdio: 'inherit' });
-        child.on('error', reject);
-        child.on('exit', (code) => {
-            if (code === 0)
-                resolvePromise();
-            else
-                reject(new Error(`node exited with code ${code}`));
-        });
-    });
+    // `nodeBinary()`, never a bare `'node'`: under GJS `process.execPath` is
+    // the `gjs` interpreter, which cannot run a `--app node` bundle, and on a
+    // host without Node a bare literal dies `spawn node ENOENT` — which is
+    // how a fully passing GJS suite was reported as a failed run.
+    const result = await spawnToCompletion(nodeBinary(), [outfile], { completion: 'exit' });
+    if (result.code !== 0)
+        throw new Error(`node exited with ${describeExit(result)}`);
 }
 /** True when `outfile` exists and is newer than every `.ts`/`.mts` file under the entry's directory tree. */
 function isFresh(outfile, entry) {

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/types/config-data.d.ts

@@ -328,6 +328,38 @@ export interface AppMetadata {
      * https://www.freedesktop.org/software/appstream/docs/sect-Metadata-DesktopApps.html#tag-dapp-kudos
      */
     kudos?: string[];
+    /**
+     * File types this package DEFINES for the whole system — a shared-mime-info
+     * document staged into `share/mime/packages/`.
+     *
+     * Distinct from `provides.mimetypes`, which only says the app HANDLES a type.
+     * For a standard type (`text/plain`, `application/pdf`) handling is all you
+     * need: the distribution already defines it. For a type of your own
+     * (`application/x-bauplan`) handling it is not enough and the failure is
+     * silent — nothing on the system knows the type exists, so a `.bauplan` file
+     * is never recognised as one, `MimeType=` in the desktop entry matches
+     * nothing, and double-clicking the file does nothing at all. No error, no
+     * log line: the association simply never fires.
+     *
+     * Every type declared here is added to the handled set automatically, because
+     * defining a file type in your own package and then not opening it is not a
+     * thing anyone means to do.
+     */
+    mimeTypes?: Array<{
+        /** `<media>/<subtype>`, e.g. `application/x-bauplan`. */
+        type: string;
+        /**
+         * What a file manager shows instead of the raw type string. Required:
+         * a type with no comment is listed to the user as `application/x-bauplan`.
+         */
+        comment: string;
+        /** Filename patterns, e.g. `["*.bauplan"]`. */
+        globs?: string[];
+        /** A registered type to inherit from, e.g. `application/zip` for a zip container. */
+        subClassOf?: string;
+        /** Fallback icon name when no type-specific icon is installed. */
+        genericIcon?: string;
+    }>;
     /**
      * What this app provides to the system. `<binary>` is auto-included with the
      * value of `command` when omitted — AppStream needs it to register the binary
@@ -433,6 +465,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.js

@@ -19,6 +19,7 @@ import { readFileSync, existsSync, readdirSync } from 'node:fs';
 // 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 {
@@ -79,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
@@ -462,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;
 }
@@ -795,7 +832,12 @@ export function buildInstallCommand(pm, missing) {
     }
     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;
+}