@gjsify/cli 0.41.0 → 0.43.0

package/lib/utils/ship/types.d.ts

@@ -1,9 +1,12 @@
-/** One file in the payload, addressed relative to the install prefix. */
-export interface StagedFile {
+/** One planned path and the mode the PLAN gives it. */
+export interface StagedMode {
     /** Prefix-relative path, e.g. `bin/learn6502`, `share/applications/x.desktop`. */
     path: string;
     /** POSIX mode bits. */
     mode: number;
+}
+/** One file in the payload, addressed relative to the install prefix. */
+export interface StagedFile extends StagedMode {
     /** Where the bytes come from. */
     source: {
         kind: 'text';
@@ -13,6 +16,18 @@ export interface StagedFile {
         path: string;
     };
 }
+/**
+ * What {@link readStage} checks a staged tree against.
+ *
+ * `bytes` is present only when the plan came from a stage manifest, i.e. when
+ * the tree travelled between hosts and there is something to compare against.
+ * The single-host run plans and writes in one process, so there is no transfer
+ * to check and no second opinion to check it with.
+ */
+export interface StagePlanEntry extends StagedMode {
+    /** Size the manifest recorded for this path, when one was recorded. */
+    bytes?: number;
+}
 /** A packed artifact on disk. */
 export interface ShipArtifact {
     format: FormatId;
@@ -49,17 +64,61 @@ export interface FormatDescriptor {
      * arm64 machine it runs on perfectly. One `.so` in the payload flips it.
      */
     archName: (arch: string, archIndependent: boolean) => string;
-    /** Artifact filename, given the resolved settings and the resolved arch label. */
-    fileName: (settings: ShipSettings, archLabel: string) => string;
+    /** Artifact filename, given the pack-time settings and the resolved arch label. */
+    fileName: (settings: PackSettings, archLabel: string) => string;
 }
-/** The resolved, fully defaulted configuration for one `gjsify ship` run. */
-export interface ShipSettings {
-    /** Absolute path to the project being shipped. */
-    projectDir: string;
-    /** Reverse-DNS application id — desktop entry, metainfo and icon basename. */
-    appId: string;
-    /** Human-readable display name. */
-    name: string;
+/** One shared-mime-info type definition (`gjsify.ship.mimeTypes`). */
+export interface ShipMimeType {
+    type: string;
+    comment: string;
+    globs?: string[];
+    subClassOf?: string;
+    genericIcon?: string;
+}
+/**
+ * The half of the configuration that survives the host boundary.
+ *
+ * `gjsify ship --from-stage` runs on a machine that has the staged tree and
+ * NOTHING else: no project directory, no `package.json`, no built bundle. So
+ * the two phases exchange exactly this object, serialised into the stage's
+ * `.gjsify-ship-stage.json`, and that is why the split is a TYPE rather than a
+ * convention — the packers take a `PackSettings`, so a `settings.bundlePath`
+ * read added to `deb.ts` or `rpm.ts` is a compile error until the field is
+ * moved here, and moving it here is what puts it in the manifest.
+ *
+ * Every field below has a MEASURED reader in the pack path
+ * (`deb.ts`, `rpm.ts`, `depends.ts`, `formats.ts#fileName`). Nothing is here
+ * "because ship needs it": a settings dump is what ADR 0024 § A2 rejects, and
+ * a dumped field that happens to be an absolute path is a path the packing host
+ * cannot open.
+ *
+ * NOT here, deliberately, and each with the reason it is not:
+ *  - `projectDir`, `outDir` — nothing in the pack path reads either; the
+ *    finishing host has its own output root.
+ *  - `bundlePath`, `bundleDir` — build-tree paths. Their three readers are all
+ *    phase 1: the build stamp (carried as the manifest's `mtime`), the
+ *    launcher's exec target (already rendered into the staged `bin/<name>`),
+ *    and the GI-namespace scan (carried as the manifest's `namespaces`).
+ *  - `iconFiles`, `schemaFiles`, `typelibFiles` — the pack path reads them only
+ *    to ask what the PAYLOAD contains, which the payload answers itself; see
+ *    `readPayloadFacts`.
+ *  - `licenseFile`, `extraFiles` — phase 1 reads their bytes into the plan.
+ *  - `localeFiles` — same, and the reason is worth stating because the field
+ *    arrived (#1263) AFTER this split was written and carries a build-host
+ *    `abs` path: `planStage` reads each catalogue into the staged tree at
+ *    `share/locale/<rel>`, and no packer reads the field. So translations
+ *    cross in the payload, where they belong, and the `abs` path does not
+ *    cross at all. This list being explicit is what caught that.
+ *  - `appId`, `name`, `kind`, `execArgs` — read by the planner and the metadata
+ *    renderers, all of which have run by the time a stage exists.
+ *  - `arch` — carried by the manifest's `target`, which is also the value a
+ *    mismatched stage is refused on, so it lives in exactly one place.
+ *  - `mimeTypes` — phase 1 renders the shared-mime-info document into the
+ *    staged tree, and the one pack-time reader asks whether that FILE is in the
+ *    payload (`readPayloadFacts#hasMimeTypes`), which is the same question one
+ *    host later. Carrying the declarations would put the answer in two places.
+ */
+export interface PackSettings {
     /** Package name: the `bin/` entry, the deb `Package:`, the rpm `Name:`. */
     binaryName: string;
     /** Upstream version, normalised for package managers. */
@@ -74,15 +133,11 @@ export interface ShipSettings {
     description: string[];
     /** SPDX identifier of the project licence. */
     license: string;
-    /** Absolute path to the licence file, when one was found. */
-    licenseFile?: string;
     homepage?: string;
     /** deb `Section:`. */
     section: string;
     /** rpm `Group:`. */
     group: string;
-    /** `'app'` stages a desktop entry and an icon; `'cli'` stages neither. */
-    kind: 'app' | 'cli';
     /** Extra runtime dependencies per format, appended to the derived set. */
     extraDepends: {
         deb: string[];
@@ -93,6 +148,21 @@ export interface ShipSettings {
         deb: string;
         rpm: string;
     }>;
+    /** Minimum GJS the emitted dependency asks for. */
+    minGjsVersion: string;
+}
+/** The resolved, fully defaulted configuration for one `gjsify ship` run. */
+export interface ShipSettings extends PackSettings {
+    /** Absolute path to the project being shipped. */
+    projectDir: string;
+    /** Reverse-DNS application id — desktop entry, metainfo and icon basename. */
+    appId: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Absolute path to the licence file, when one was found. */
+    licenseFile?: string;
+    /** `'app'` stages a desktop entry and an icon; `'cli'` stages neither. */
+    kind: 'app' | 'cli';
     /** Absolute path to the built bundle that `bin/<binaryName>` executes. */
     bundlePath: string;
     /** Absolute path of the directory staged wholesale into `lib/<binaryName>/`. */
@@ -101,6 +171,30 @@ export interface ShipSettings {
     iconFiles: string[];
     /** Absolute paths of `*.gschema.xml` files to install. */
     schemaFiles: string[];
+    /**
+     * File types this package defines system-wide (shared-mime-info). Empty for a package that only
+     * HANDLES existing types — that needs no document of its own.
+     */
+    mimeTypes: ShipMimeType[];
+    /**
+     * Typelibs + shared libraries the package carries itself (`gjsify.ship.bundledTypelibs`).
+     *
+     * gjsify's own GI libraries arrive as npm prebuilds, not distro packages, so an app using one
+     * has nothing to depend on and must ship the files — with the launcher pointing GI at them.
+     */
+    typelibFiles: string[];
+    /**
+     * Compiled gettext catalogues (`gjsify.ship.localeDir`), each keeping its
+     * `<lang>/LC_MESSAGES/<domain>.mo` path so `share/locale/` comes out in the layout
+     * `bindtextdomain` reads.
+     *
+     * `rel` rather than a bare list of absolute paths, because the LAYOUT is the whole point here:
+     * a `.mo` staged by basename alone lands where no catalogue lookup will ever look at it.
+     */
+    localeFiles: {
+        rel: string;
+        abs: string;
+    }[];
     /** `<dest relative to prefix>` → absolute source path. */
     extraFiles: Record<string, string>;
     /** Arguments appended to the launcher's `exec` line. */
@@ -109,6 +203,4 @@ export interface ShipSettings {
     outDir: string;
     /** Target architecture in `process.arch` spelling. */
     arch: string;
-    /** Minimum GJS the emitted dependency asks for. */
-    minGjsVersion: string;
 }

package/lib/utils/ship/types.js

@@ -7,4 +7,9 @@
 // (`refs/gtkx`, MPL-2.0, reimplemented not copied) expresses the same
 // distinction as `if (target === 'deb')` inside its stager, and pays for it:
 // adding a fifth target there means editing six files.
+//
+// ADR 0024 § A2 splits the command in two — `--stage` assembles anywhere,
+// `--from-stage` packs on the host that owns the format — and that split shows
+// up here as the {@link PackSettings} / {@link ShipSettings} pair. Read the
+// comment on {@link PackSettings} before adding a field to either.
 export {};

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

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function tokenizeSimpleCommand(cmd: string): string[] | null;
+/**
+ * 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 declare function gjsifyCommandArgv(literal: string): string[] | null;

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>;