@gjsify/cli 0.41.0 → 0.42.0

package/lib/utils/simple-command.js

@@ -0,0 +1,77 @@
+// Quote-aware tokenizer for a package.json script that is a SIMPLE command line.
+//
+// Lifted out of `commands/run.ts` when `gjsify dev` became the second caller:
+// both need to know whether a declared script is a plain `gjsify <subcommand> …`
+// they may take apart, or something only a shell can execute. The predicate is
+// deliberately conservative in ONE direction — a `null` costs the caller its
+// fast path, a wrong token list would run a different command than the script
+// says.
+/**
+ * Tokenize `cmd`, or return `null` if the string contains anything the shell
+ * would treat specially — operators (`&& | ; < > &`), substitutions (`$(...)` /
+ * backticks / `$VAR`), unquoted globs/expansions (`* ? { } [ ] ~`), comments
+ * (`#`), or an unterminated quote — in which case the caller MUST use the real
+ * shell instead. Quotes are honoured so a quoted glob (`'src/**'`) survives as a
+ * single literal token, exactly as the shell would hand it to `gjsify` (which
+ * does its own glob expansion).
+ */
+export function tokenizeSimpleCommand(cmd) {
+    const tokens = [];
+    let cur = '';
+    let has = false;
+    let quote = null;
+    for (let i = 0; i < cmd.length; i++) {
+        const c = cmd[i];
+        if (quote === "'") {
+            if (c === "'")
+                quote = null;
+            else
+                cur += c;
+            continue;
+        }
+        if (quote === '"') {
+            if (c === '"')
+                quote = null;
+            else if (c === '\\' && (cmd[i + 1] === '"' || cmd[i + 1] === '\\'))
+                cur += cmd[++i];
+            else if (c === '$' || c === '`')
+                return null; // substitution inside "…"
+            else
+                cur += c;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            quote = c;
+            has = true;
+            continue;
+        }
+        if (c === ' ' || c === '\t') {
+            if (has) {
+                tokens.push(cur);
+                cur = '';
+                has = false;
+            }
+            continue;
+        }
+        if ('|&;<>`$()\\\n\r*?{}[]~#!'.includes(c))
+            return null;
+        cur += c;
+        has = true;
+    }
+    if (quote)
+        return null; // unterminated quote
+    if (has)
+        tokens.push(cur);
+    return tokens;
+}
+/**
+ * The argv of a script that is a single `gjsify <subcommand> …` command — i.e.
+ * the tokens after `gjsify` — or `null` when it is anything else. `null` is the
+ * signal to hand the literal to a shell.
+ */
+export function gjsifyCommandArgv(literal) {
+    const tokens = tokenizeSimpleCommand(literal);
+    if (!tokens || tokens.length < 2 || tokens[0] !== 'gjsify')
+        return null;
+    return tokens.slice(1);
+}

package/lib/utils/spawn.d.ts

@@ -6,10 +6,16 @@ import type { ChildProcess } from 'node:child_process';
  *   main loop, so the streaming async `spawn` is safe on both hosts.
  * - `'return'` — the command returns and lets the CLI unwind. Under GJS that must
  *   not leave a main loop armed, so the child runs on the blocking `spawnSync` path.
+ * - `'daemon'` — the command settles nothing: it stays alive supervising the child,
+ *   on a main loop it holds ITSELF under GJS (`holdMainLoop()`; see the module header
+ *   for why this spawn cannot arm one for it). The caller takes the handle through
+ *   {@link SpawnToCompletionOptions.onSpawn} and does NOT await the returned promise,
+ *   so "once this spawn settles" has no answer for it. Distinct from `'exit'` because
+ *   a supervisor has no exit to be safe by; it routes to the same streaming path.
  *
  * See the module header for the full rationale.
  */
-export type SpawnCompletionContract = 'exit' | 'return';
+export type SpawnCompletionContract = 'exit' | 'return' | 'daemon';
 export interface SpawnToCompletionOptions {
     /** The caller's teardown contract. Required — see {@link SpawnCompletionContract}. */
     completion: SpawnCompletionContract;

package/lib/utils/spawn.js

@@ -24,6 +24,16 @@
 //   | Node | anything               | async `spawn` (streaming)           |
 //   | GJS  | `process.exit(…)`      | async `spawn` (streaming)           |
 //   | GJS  | a normal `return`      | blocking `spawnSync` (captured)     |
+//   | GJS  | never — it supervises  | async `spawn` (streaming)           |
+//
+// The fourth row is `completion: 'daemon'`: a command like `gjsify storybook
+// --watch` neither exits nor unwinds, so an armed loop is not a leak there but the
+// thing keeping it alive. It takes the handle through `onSpawn` and never awaits the
+// completion promise. What it must NOT do is expect this spawn to arm that loop —
+// `ensureMainLoop()` declines at `GLib.main_depth() !== 0`, and a supervisor reaches
+// its spawn from a continuation GJS resumed inside the main-context spin it runs
+// while the entry module's top-level await is pending, i.e. at depth 1. A daemon
+// holds the loop itself, through `holdMainLoop()` (`utils/watch-loop.ts` does).
 //
 // which is why `gjsify foreach`/`workspace`/`check` and `runGjsBundle` run hundreds
 // of async-spawned children under GJS without hanging: each ends its handler with
@@ -31,19 +41,36 @@
 // REQUIRED {@link SpawnToCompletionOptions.completion} field — a new call site must
 // state which side of the table it is on rather than inherit a wrong default.
 //
-// ## When a raw `node:child_process` spawn is still fine
+// ## Under `packages/infra/cli/src/`, a raw async `spawn` is never fine
+//
+// The contract above binds only code that USES this helper, and one import bypassed
+// it for years — `utils/run-lifecycle-script.ts` reached for `node:child_process`
+// while its own header asserted the opposite, and `gjsify pack` parked for 5m30s
+// after finishing its work on any package with a `prepack`, the production
+// `gjsify run publish:app` chain included (#1010).
+//
+// So the rule is enforced rather than written down: `scripts/check-spawn-teardown-
+// contract.mjs` fails on a value import of async `spawn` from `node:child_process`
+// anywhere under `packages/infra/cli/src/` outside this file, unless the site
+// carries an entry in `scripts/spawn-teardown-exceptions.mjs`. Deliberately narrow
+// to async `spawn`: `spawnSync` blocks and arms nothing, and `exec`/`execFile` stay
+// out until the `gjsify gsettings` observation (an `execFile` command that compiles
+// a schema and exits in 0.45 s although `_execImpl` also calls `ensureMainLoop`) is
+// explained rather than generalised from.
+//
+// ## What is spawned still matters — the Windows rewrite
 //
-// This helper also carries the Windows command rewrite (`forWin32`), so the rule is
-// about WHAT is spawned:
+// This helper also carries the Windows command rewrite (`forWin32`), which is a
+// second reason to come through it, and the one that applies OUTSIDE the CLI too:
 //
 //   • a real executable (`git`, `gh`, `node`, `gjs`, `flatpak`, `process.execPath`)
-//     may use `node:child_process` directly — Windows resolves those via `.exe`.
+//     resolves on Windows via `.exe`, so a rewrite is not what it needs.
 //   • `shell: true` is fine — Node routes it through `%COMSPEC%`, which finds
 //     `.cmd` shims.
 //   • a PACKAGE MANAGER or any `node_modules/.bin` entry by BARE NAME (`npm`,
-//     `yarn`, `npx`, `tsc`, `oxlint`, a `pm` from `detectPackageManager()`) MUST
-//     come through here: on Windows those are `.cmd` shims, where `spawn('npm')` is
-//     ENOENT and `spawn('npm.cmd')` is EINVAL, so a raw spawn cannot work at all.
+//     `yarn`, `npx`, `tsc`, `oxlint`, a `pm` from `detectPackageManager()`) cannot
+//     work without it: on Windows those are `.cmd` shims, where `spawn('npm')` is
+//     ENOENT and `spawn('npm.cmd')` is EINVAL.
 //
 // The third case is not hypothetical, and each instance was invisible to Linux and
 // macOS CI: raw spawns left `commands/check.ts` exiting 1 with no diagnostic,

package/lib/utils/system-gi.d.ts

@@ -9,6 +9,30 @@ export interface SystemGiOptions {
     /** `pkg-config`'s `.pc` search directories; defaults to {@link pkgConfigSearchDirs}. */
     searchDirs?: (env: Record<string, string | undefined>) => string[];
 }
+/**
+ * Prefixes a macOS GI stack is installed under in practice — probed, never
+ * assumed: each is accepted only when it actually holds a `girepository-1.0/`.
+ *
+ * Load-bearing rather than belt-and-braces: `brew install gtk4` installs RUNTIME
+ * dependencies only, so a user running a published showcase routinely has the
+ * whole GTK stack and no `pkg-config` at all (a BUILD dependency of those
+ * formulae). The pkg-config source below is the general mechanism — it finds a
+ * jhbuild or otherwise bespoke prefix — but it cannot be the only one.
+ *
+ * Exported because a `--app gjs` BUNDLE has to carry the candidates rather than this
+ * function's answer: it runs on a host the build machine never saw, so the probe moves
+ * into the emitted prologue (`gi-runtime-paths.ts`). `@gjsify/utils`' copy of this rule
+ * exports it too; node-gi's does not, and the mirror suite compares OUTPUTS, not surface.
+ */
+export declare const PROBED_GI_LIBDIRS: Record<string, readonly string[]>;
+/**
+ * The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API.
+ *
+ * Exported so `gi-typelib.ts` shares it rather than keeping a third copy of the
+ * one string this whole layout rule turns on. Both mirrors export it, so the
+ * agreement suite still compares two files that differ only in language.
+ */
+export declare const TYPELIB_SUBDIR = "girepository-1.0";
 /** Split an OS search-path variable, dropping empty segments. */
 export declare function splitSearchPath(value: string | undefined, separator?: string): string[];
 /**

package/lib/utils/system-gi.js

@@ -62,12 +62,23 @@ const { basename, dirname, join } = posix;
  * whole GTK stack and no `pkg-config` at all (a BUILD dependency of those
  * formulae). The pkg-config source below is the general mechanism — it finds a
  * jhbuild or otherwise bespoke prefix — but it cannot be the only one.
+ *
+ * Exported because a `--app gjs` BUNDLE has to carry the candidates rather than this
+ * function's answer: it runs on a host the build machine never saw, so the probe moves
+ * into the emitted prologue (`gi-runtime-paths.ts`). `@gjsify/utils`' copy of this rule
+ * exports it too; node-gi's does not, and the mirror suite compares OUTPUTS, not surface.
  */
-const PROBED_GI_LIBDIRS = {
+export const PROBED_GI_LIBDIRS = {
     darwin: ['/opt/homebrew/lib', '/usr/local/lib', '/opt/local/lib'],
 };
-/** The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API. */
-const TYPELIB_SUBDIR = 'girepository-1.0';
+/**
+ * The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API.
+ *
+ * Exported so `gi-typelib.ts` shares it rather than keeping a third copy of the
+ * one string this whole layout rule turns on. Both mirrors export it, so the
+ * agreement suite still compares two files that differ only in language.
+ */
+export const TYPELIB_SUBDIR = 'girepository-1.0';
 /** Memoized `pkg-config` answer: the spawn happens at most once per process. */
 let pkgConfigDirsCache = null;
 /** Split an OS search-path variable, dropping empty segments. */

package/lib/utils/watch-loop.d.ts

@@ -0,0 +1,91 @@
+import type { ChildProcess } from 'node:child_process';
+import { type ExampleRuntime } from './runtimes.js';
+/**
+ * Start a child the caller SUPERVISES rather than waits for.
+ *
+ * `completion: 'daemon'` is the third row of the teardown table: a watch loop
+ * neither exits nor unwinds, so the armed GJS main loop is not a leak here —
+ * it is what keeps the session alive. The handle arrives synchronously through
+ * `onSpawn`; the completion promise is deliberately never awaited (it settles
+ * when the child is killed for the next rebuild), only its REJECTION is routed
+ * out, so a missing interpreter still surfaces as a rebuild failure.
+ */
+export declare function spawnSupervised(cmd: string, cmdArgs: string[], env?: NodeJS.ProcessEnv): Promise<ChildProcess>;
+/**
+ * Launch a built bundle as a supervised child on `runtime`, wired the way
+ * `gjsify run` would launch it for real: `gjs -m` for the `--app gjs` bundle,
+ * the `--app node` bundle on node/bun/deno, and in BOTH cases the native
+ * typelib/library environment for any `@gjsify` native package the bundle
+ * reaches. The env is not optional on the gjs arm either — a watch loop that
+ * skipped it would run an app that `gjsify run` can start and this cannot.
+ *
+ * `subject` names what is being run in the node-gi diagnostic ("the storybook",
+ * "this project").
+ */
+export declare function spawnBundleSupervised(runtime: ExampleRuntime, bundlePath: string, cwd: string, subject: string): Promise<ChildProcess>;
+export interface WatchLoopOptions {
+    /** Directory watched recursively. */
+    dir: string;
+    /** How `dir` is spelled in the loop's own log lines. Defaults to `dir`. */
+    dirLabel?: string;
+    /** Prefix for the loop's log lines: `[<label>] …`. */
+    label: string;
+    /** Regenerate derived inputs before each build (e.g. a generated entry). */
+    prepare?: () => void | Promise<void>;
+    /** Build the bundle. Runtime-agnostic — an in-process re-entry of `build`. */
+    build: () => Promise<void>;
+    /** Launch the freshly built bundle, or `null` to rebuild without launching. */
+    spawnChild: (() => Promise<ChildProcess>) | null;
+    /**
+     * Absolute path the build WRITES, when one is known. Changes to it never
+     * trigger a rebuild — see {@link isSelfWrite} for why the loop otherwise
+     * feeds itself.
+     */
+    output?: string;
+    /** Quiet window after a change before rebuilding. */
+    debounceMs?: number;
+}
+/**
+ * Whether a watcher event is the loop's OWN output rather than a source edit.
+ *
+ * Without this the loop feeds itself whenever the bundle lands inside the
+ * watched tree, which is the DEFAULT arrangement rather than an exotic one: the
+ * watch dir defaults to the entry point's directory, so `gjsify dev index.ts` on
+ * a project building to `dist/` watches the project root and every build it runs
+ * is a change under it. Measured before this filter: one edit to `index.ts`
+ * started a rebuild every ~5 s that never stopped.
+ *
+ * Two shapes, because a build writes more than the file it is named after:
+ *
+ *  - the bundle itself and anything sharing its stem (`out.mjs.map`), which the
+ *    bundler writes beside it in the same pass;
+ *  - the whole output DIRECTORY — but only when it is not the watched directory
+ *    itself. `--outfile dist/out.mjs` under a watch dir of `.` puts chunks and
+ *    assets there too; an `--outfile` written straight into the watched dir has
+ *    no directory to exclude that would not also exclude the sources.
+ *
+ * `filename` is what `fs.watch` reports, relative to `dir` — `null` on the
+ * platforms that cannot name the changed path, where the honest answer is "no
+ * idea", i.e. rebuild.
+ *
+ * BOTH operands are resolved before they are compared. Resolving only the
+ * changed path is right on POSIX for as long as every caller happens to pass an
+ * already-absolute `output`, and silently wrong the moment one does not: on
+ * win32 `resolve()` also rewrites the separators and picks up the drive, so the
+ * two sides stop being the same spelling of the same file and every self-write
+ * reads as a source edit — which is the feedback loop this filter exists to
+ * stop. Caught by the win32 leg; on Linux all five cases passed.
+ */
+export declare function isSelfWrite(dir: string, output: string | undefined, filename: string | null): boolean;
+/**
+ * Run the loop: build + launch once, then rebuild + relaunch on every change
+ * under `dir`. Returns once the watcher is armed; the process is then held open
+ * — by the watcher handle on Node, by the GLib main loop on GJS — so there is
+ * nothing left to await. That the RESOLUTION is not completion is the one thing
+ * a caller has to know, which is why it is also declared through
+ * `markDaemonCommand()` for the callers that cannot see this signature.
+ *
+ * A build failure is reported and the loop KEEPS WATCHING: the next save is the
+ * fix, and a dev loop that dies on a syntax error is a dev loop nobody uses.
+ */
+export declare function runWatchLoop(opts: WatchLoopOptions): Promise<void>;

package/lib/utils/watch-loop.js

@@ -0,0 +1,207 @@
+// The watch → rebuild → relaunch loop, shared by `gjsify storybook --watch` and
+// `gjsify dev`.
+//
+// It lives here rather than in either command because it is the whole Node-free
+// inner development cycle and `gjsify build --watch` cannot be it: rolldown's
+// watcher API is npm-engine-only (`bundler-pick.ts` refuses under
+// `@gjsify/rolldown-native`), so the one path that watches is the one running on
+// the host that does not need it. This loop asks the bundler for no watcher at
+// all — `fs.watch` reports the change and the rebuild is an in-process re-entry
+// of the ordinary build command, which is runtime-agnostic.
+import { watch } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+import { holdMainLoop } from '@gjsify/utils/main-loop';
+import { markDaemonCommand } from './daemon-command.js';
+import { spawnToCompletion } from './spawn.js';
+import { RUNTIMES } from './runtimes.js';
+/**
+ * Start a child the caller SUPERVISES rather than waits for.
+ *
+ * `completion: 'daemon'` is the third row of the teardown table: a watch loop
+ * neither exits nor unwinds, so the armed GJS main loop is not a leak here —
+ * it is what keeps the session alive. The handle arrives synchronously through
+ * `onSpawn`; the completion promise is deliberately never awaited (it settles
+ * when the child is killed for the next rebuild), only its REJECTION is routed
+ * out, so a missing interpreter still surfaces as a rebuild failure.
+ */
+export function spawnSupervised(cmd, cmdArgs, env) {
+    return new Promise((resolveChild, reject) => {
+        void spawnToCompletion(cmd, cmdArgs, { completion: 'daemon', env, onSpawn: resolveChild }).catch(reject);
+    });
+}
+/**
+ * Launch a built bundle as a supervised child on `runtime`, wired the way
+ * `gjsify run` would launch it for real: `gjs -m` for the `--app gjs` bundle,
+ * the `--app node` bundle on node/bun/deno, and in BOTH cases the native
+ * typelib/library environment for any `@gjsify` native package the bundle
+ * reaches. The env is not optional on the gjs arm either — a watch loop that
+ * skipped it would run an app that `gjsify run` can start and this cannot.
+ *
+ * `subject` names what is being run in the node-gi diagnostic ("the storybook",
+ * "this project").
+ */
+export async function spawnBundleSupervised(runtime, bundlePath, cwd, subject) {
+    if (runtime !== 'gjs') {
+        // Only a bundle that actually reaches gi:// needs the reverse bridge;
+        // the bundler keeps `@gjsify/node-gi` external, so its presence in the
+        // output is the question. A plain Node app must run without it.
+        const { bundleRequiresNodeGi, resolveNodeGiForBundle } = await import('./run-node.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 (bundleRequiresNodeGi(bundlePath) && !resolveNodeGiForBundle(bundlePath, cwd)) {
+            throw new Error(`Cannot run ${subject} on ${runtime}: \`@gjsify/node-gi\` is not installed. ` +
+                `Add @gjsify/node-gi as a dependency to run ${subject} on ${runtime}.`);
+        }
+    }
+    const { computeNativeEnvForBundle } = await import('./run-gjs.js');
+    const { env: nativeEnv } = computeNativeEnvForBundle(bundlePath, cwd);
+    const env = { ...process.env, ...nativeEnv };
+    if (runtime === 'gjs') {
+        return spawnSupervised('gjs', ['-m', bundlePath], env);
+    }
+    // `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') {
+        const { nodeBinary } = await import('./run-node.js');
+        return spawnSupervised(nodeBinary(), [bundlePath], env);
+    }
+    const [cmd, launchArgs] = RUNTIMES[runtime].launch(bundlePath);
+    return spawnSupervised(cmd, launchArgs, env);
+}
+/**
+ * Whether a watcher event is the loop's OWN output rather than a source edit.
+ *
+ * Without this the loop feeds itself whenever the bundle lands inside the
+ * watched tree, which is the DEFAULT arrangement rather than an exotic one: the
+ * watch dir defaults to the entry point's directory, so `gjsify dev index.ts` on
+ * a project building to `dist/` watches the project root and every build it runs
+ * is a change under it. Measured before this filter: one edit to `index.ts`
+ * started a rebuild every ~5 s that never stopped.
+ *
+ * Two shapes, because a build writes more than the file it is named after:
+ *
+ *  - the bundle itself and anything sharing its stem (`out.mjs.map`), which the
+ *    bundler writes beside it in the same pass;
+ *  - the whole output DIRECTORY — but only when it is not the watched directory
+ *    itself. `--outfile dist/out.mjs` under a watch dir of `.` puts chunks and
+ *    assets there too; an `--outfile` written straight into the watched dir has
+ *    no directory to exclude that would not also exclude the sources.
+ *
+ * `filename` is what `fs.watch` reports, relative to `dir` — `null` on the
+ * platforms that cannot name the changed path, where the honest answer is "no
+ * idea", i.e. rebuild.
+ *
+ * BOTH operands are resolved before they are compared. Resolving only the
+ * changed path is right on POSIX for as long as every caller happens to pass an
+ * already-absolute `output`, and silently wrong the moment one does not: on
+ * win32 `resolve()` also rewrites the separators and picks up the drive, so the
+ * two sides stop being the same spelling of the same file and every self-write
+ * reads as a source edit — which is the feedback loop this filter exists to
+ * stop. Caught by the win32 leg; on Linux all five cases passed.
+ */
+export function isSelfWrite(dir, output, filename) {
+    if (output === undefined || filename === null)
+        return false;
+    const changed = resolve(dir, filename);
+    const out = resolve(dir, output);
+    if (changed === out || changed.startsWith(`${out}.`))
+        return true;
+    const outDir = dirname(out);
+    if (outDir === resolve(dir))
+        return false;
+    return changed === outDir || changed.startsWith(`${outDir}${sep}`);
+}
+/**
+ * Run the loop: build + launch once, then rebuild + relaunch on every change
+ * under `dir`. Returns once the watcher is armed; the process is then held open
+ * — by the watcher handle on Node, by the GLib main loop on GJS — so there is
+ * nothing left to await. That the RESOLUTION is not completion is the one thing
+ * a caller has to know, which is why it is also declared through
+ * `markDaemonCommand()` for the callers that cannot see this signature.
+ *
+ * A build failure is reported and the loop KEEPS WATCHING: the next save is the
+ * fix, and a dev loop that dies on a syntax error is a dev loop nobody uses.
+ */
+export async function runWatchLoop(opts) {
+    const { dir, label, prepare, build, spawnChild, output, debounceMs = 200 } = opts;
+    // Say so BEFORE the first build: `gjsify run`'s in-process dispatch acts on
+    // this the moment the handler resolves, and a first build that throws still
+    // leaves the loop watching.
+    markDaemonCommand();
+    let child = null;
+    let rebuilding = false;
+    let pending = false;
+    const rebuild = async () => {
+        if (rebuilding) {
+            pending = true;
+            return;
+        }
+        rebuilding = true;
+        try {
+            if (prepare)
+                await prepare();
+            if (child) {
+                child.kill();
+                child = null;
+            }
+            await build();
+            if (spawnChild) {
+                child = await spawnChild();
+            }
+        }
+        catch (err) {
+            console.error(`[${label}] rebuild failed: ${err.message}`);
+        }
+        finally {
+            rebuilding = false;
+            if (pending) {
+                pending = false;
+                void rebuild();
+            }
+        }
+    };
+    await rebuild();
+    let debounce = null;
+    const watcher = watch(dir, { recursive: true }, (_event, filename) => {
+        if (isSelfWrite(dir, output, typeof filename === 'string' ? filename : null))
+            return;
+        if (debounce)
+            clearTimeout(debounce);
+        debounce = setTimeout(() => void rebuild(), debounceMs);
+    });
+    // Under GJS nothing else keeps us here. An `fs.watch` handle is a Gio file
+    // monitor, not a Node handle count, and the supervised spawn's own
+    // `ensureMainLoop()` declines to arm anything: it is reached from a
+    // continuation that GJS resumed from inside the main-context spin it runs
+    // while our entry module's top-level await is pending, where
+    // `GLib.main_depth()` is 1. So the loop used to print "watching …" and exit
+    // 0 on the very host `gjsify dev` exists for, leaving the app orphaned.
+    // `holdMainLoop()` is the opt-in that arms it anyway; `shutdown()` below is
+    // what takes it back down.
+    holdMainLoop();
+    // Ctrl+C is how this command ENDS, so the supervised child has to be taken
+    // down with it: the loop spawns the app in the CLI's own process group, and
+    // a SIGINT delivered to the CLI alone leaves a live GTK window behind with
+    // nothing watching it. Registering a handler also removes Node's default
+    // terminate, so the exit has to be explicit — and under GJS it is required
+    // anyway, since the loop held above is what is keeping us alive. Delivery
+    // there is `@gjsify/process` arming a `GLibUnix.signal_add()` source on the
+    // first listener, which dispatches on that same held loop; before it existed
+    // these two lines registered listeners nothing ever emitted.
+    let stopping = false;
+    const shutdown = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        if (debounce)
+            clearTimeout(debounce);
+        child?.kill();
+        watcher.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    console.log(`[${label}] watching ${opts.dirLabel ?? dir} — press Ctrl+C to stop`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.41.0",
+    "version": "0.42.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,20 +142,21 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.41.0",
-        "@gjsify/create-app": "^0.41.0",
-        "@gjsify/node-globals": "^0.41.0",
-        "@gjsify/node-polyfills": "^0.41.0",
-        "@gjsify/npm-registry": "^0.41.0",
-        "@gjsify/resolve-npm": "^0.41.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.41.0",
-        "@gjsify/vite-plugin-blueprint": "^0.41.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.41.0",
-        "@gjsify/semver": "^0.41.0",
-        "@gjsify/tar": "^0.41.0",
-        "@gjsify/tsc": "^0.41.0",
-        "@gjsify/web-polyfills": "^0.41.0",
-        "@gjsify/workspace": "^0.41.0",
+        "@gjsify/buffer": "^0.42.0",
+        "@gjsify/create-app": "^0.42.0",
+        "@gjsify/node-globals": "^0.42.0",
+        "@gjsify/node-polyfills": "^0.42.0",
+        "@gjsify/npm-registry": "^0.42.0",
+        "@gjsify/resolve-npm": "^0.42.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.42.0",
+        "@gjsify/vite-plugin-blueprint": "^0.42.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.42.0",
+        "@gjsify/semver": "^0.42.0",
+        "@gjsify/tar": "^0.42.0",
+        "@gjsify/tsc": "^0.42.0",
+        "@gjsify/utils": "^0.42.0",
+        "@gjsify/web-polyfills": "^0.42.0",
+        "@gjsify/workspace": "^0.42.0",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -164,13 +165,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.41.0",
+        "@gjsify/unit": "^0.42.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.41.0",
-        "@gjsify/rolldown-native": "^0.41.0"
+        "@gjsify/oxfmt-native": "^0.42.0",
+        "@gjsify/rolldown-native": "^0.42.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {

package/lib/templates/app/desktop.tmpl

@@ -1,10 +0,0 @@
-[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}}