@bitmagic/cli 0.1.22 → 0.1.25

package/dist/editor/watch.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Deciding *when* the browser should reload.
+ *
+ * The hard part is not noticing a change — `fs.watch` does that — it is not reloading at the wrong
+ * moment. Three wrong moments, each of which this file exists to avoid:
+ *
+ *  1. **Mid-burst.** An agent editing five files produces five reloads unless the writes are let
+ *     go quiet first. Hence the debounce.
+ *  2. **Mid-compile.** A `.ts` edit changes `src/` long before `tsc --watch` finishes emitting
+ *     `dist/`, and every module the project loads resolves into `dist/`. Reloading on the source
+ *     write shows the creator the *old* build and reads as "my change did nothing". Hence the
+ *     compile gate: reloads are held while a compile is open and released when it lands clean.
+ *  3. **After a failed compile.** `dist/` still holds the last good emit, so a reload would show
+ *     working code for broken source — the most confusing outcome of the three. The pending reload
+ *     is dropped and the shell is told the build failed instead.
+ *
+ * `ReloadCoordinator` holds all of that and touches no I/O, so it is testable with fake timers and
+ * no filesystem. `watchProject` and `pipeTscWatch` are the thin I/O shells that feed it.
+ */
+import { type ChildProcess } from 'child_process';
+import type { BuildStatus } from './reload-bus.js';
+/**
+ * How long the writes must stay quiet before a reload fires.
+ *
+ * Long enough that `tsc --watch` (which has its own ~250 ms debounce before it reports
+ * `File change detected`) has almost always opened its compile by the time this elapses, so the
+ * gate below actually gets to hold the reload. Too short and a `.ts` edit produces two reloads —
+ * one stale, one correct — instead of one.
+ */
+export declare const RELOAD_QUIET_MS = 700;
+/**
+ * How long after one of our own writes to ignore file events.
+ *
+ * `/api/scene/save` and the HQ generation both write `world.json`, and a reload fired at the
+ * creator's own gizmo drag would throw away the drag that caused it. `fs.watch` delivers
+ * asynchronously but promptly, so this only has to outlast the delivery, not the write.
+ */
+export declare const OWN_WRITE_GRACE_MS = 400;
+export interface ReloadCoordinatorOptions {
+    onReload: (reason: string) => void;
+    onBuild: (status: BuildStatus, message?: string) => void;
+    quietMs?: number;
+}
+export declare class ReloadCoordinator {
+    private readonly options;
+    private timer;
+    private pendingReason;
+    private compiling;
+    private suppressUntil;
+    private stopped;
+    constructor(options: ReloadCoordinatorOptions);
+    /** A file under a watched directory changed. Arms — or re-arms — the quiet window. */
+    noteFileChange(reason: string): void;
+    /**
+     * Reload as soon as it is safe to — now, or the moment the compile in flight lands clean.
+     *
+     * The wait is the whole point for `bitmagic reload`: an agent's stop hook fires immediately after
+     * its last edit, which is precisely when `tsc` is still compiling it. Returns whether the reload
+     * was queued behind a compile rather than sent, so the command can say which happened.
+     */
+    requestNow(reason: string): {
+        queued: boolean;
+    };
+    /** The sidecar wrote `world.json` itself; the resulting file events are not news. */
+    noteOwnWrite(): void;
+    noteCompileStart(): void;
+    noteCompileEnd(errorCount: number): void;
+    stop(): void;
+    /** Send the pending reload, unless a compile is still open — then it waits for `noteCompileEnd`. */
+    private release;
+}
+export interface ProjectWatcher {
+    close(): void;
+}
+/**
+ * Watch the two directories that decide what the browser shows: `src/` (what the agent and the
+ * creator edit — including `work/world.json`) and `dist/` (what the page actually loads).
+ *
+ * `dist/` is watched as well as `src/` even though the compile gate already covers the normal
+ * `tsc --watch` path, because it is what a build run outside this process — a manual `tsc`, an
+ * editor's own compiler — lands in, and that should reach the browser too.
+ *
+ * A directory that cannot be watched is skipped with a note rather than failing the command: a
+ * missing `dist/` means "not built yet", and losing auto-reload is a smaller loss than losing
+ * `bitmagic dev`.
+ */
+export declare function watchProject(root: string, coordinator: ReloadCoordinator, log: (message: string) => void): ProjectWatcher;
+/**
+ * Feed one line of `tsc --watch` output to the coordinator. Exported for its test — the markers are
+ * tsc's own wording, and a version that changes them would otherwise break auto-reload silently.
+ */
+export declare function noteTscLine(line: string, coordinator: ReloadCoordinator): void;
+/**
+ * Spawn `tsc --watch` with its output piped through us instead of inherited.
+ *
+ * Piping is what makes the compile gate possible — the only signal that a build finished, and
+ * whether it finished clean, is tsc's own `Found N errors` line. Every line is re-echoed verbatim,
+ * so the creator sees exactly what an inherited stdio would have shown, and `--pretty` is forced
+ * back on when our own stdout is a terminal (tsc drops colour the moment it is piped).
+ */
+export declare function pipeTscWatch(tsc: string, cwd: string, coordinator: ReloadCoordinator): ChildProcess;

package/dist/editor/watch.js

@@ -0,0 +1,228 @@
+/**
+ * Deciding *when* the browser should reload.
+ *
+ * The hard part is not noticing a change — `fs.watch` does that — it is not reloading at the wrong
+ * moment. Three wrong moments, each of which this file exists to avoid:
+ *
+ *  1. **Mid-burst.** An agent editing five files produces five reloads unless the writes are let
+ *     go quiet first. Hence the debounce.
+ *  2. **Mid-compile.** A `.ts` edit changes `src/` long before `tsc --watch` finishes emitting
+ *     `dist/`, and every module the project loads resolves into `dist/`. Reloading on the source
+ *     write shows the creator the *old* build and reads as "my change did nothing". Hence the
+ *     compile gate: reloads are held while a compile is open and released when it lands clean.
+ *  3. **After a failed compile.** `dist/` still holds the last good emit, so a reload would show
+ *     working code for broken source — the most confusing outcome of the three. The pending reload
+ *     is dropped and the shell is told the build failed instead.
+ *
+ * `ReloadCoordinator` holds all of that and touches no I/O, so it is testable with fake timers and
+ * no filesystem. `watchProject` and `pipeTscWatch` are the thin I/O shells that feed it.
+ */
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * How long the writes must stay quiet before a reload fires.
+ *
+ * Long enough that `tsc --watch` (which has its own ~250 ms debounce before it reports
+ * `File change detected`) has almost always opened its compile by the time this elapses, so the
+ * gate below actually gets to hold the reload. Too short and a `.ts` edit produces two reloads —
+ * one stale, one correct — instead of one.
+ */
+export const RELOAD_QUIET_MS = 700;
+/**
+ * How long after one of our own writes to ignore file events.
+ *
+ * `/api/scene/save` and the HQ generation both write `world.json`, and a reload fired at the
+ * creator's own gizmo drag would throw away the drag that caused it. `fs.watch` delivers
+ * asynchronously but promptly, so this only has to outlast the delivery, not the write.
+ */
+export const OWN_WRITE_GRACE_MS = 400;
+export class ReloadCoordinator {
+    options;
+    timer = null;
+    pendingReason = null;
+    compiling = false;
+    suppressUntil = 0;
+    stopped = false;
+    constructor(options) {
+        this.options = { quietMs: RELOAD_QUIET_MS, ...options };
+    }
+    /** A file under a watched directory changed. Arms — or re-arms — the quiet window. */
+    noteFileChange(reason) {
+        if (this.stopped)
+            return;
+        if (Date.now() < this.suppressUntil)
+            return;
+        this.pendingReason = reason;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.release();
+        }, this.options.quietMs);
+    }
+    /**
+     * Reload as soon as it is safe to — now, or the moment the compile in flight lands clean.
+     *
+     * The wait is the whole point for `bitmagic reload`: an agent's stop hook fires immediately after
+     * its last edit, which is precisely when `tsc` is still compiling it. Returns whether the reload
+     * was queued behind a compile rather than sent, so the command can say which happened.
+     */
+    requestNow(reason) {
+        if (this.stopped)
+            return { queued: false };
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.pendingReason = reason;
+        this.release();
+        return { queued: this.pendingReason !== null };
+    }
+    /** The sidecar wrote `world.json` itself; the resulting file events are not news. */
+    noteOwnWrite() {
+        this.suppressUntil = Date.now() + OWN_WRITE_GRACE_MS;
+    }
+    noteCompileStart() {
+        if (this.stopped || this.compiling)
+            return;
+        this.compiling = true;
+        this.options.onBuild('building');
+    }
+    noteCompileEnd(errorCount) {
+        if (this.stopped)
+            return;
+        this.compiling = false;
+        if (errorCount > 0) {
+            // Dropped, not deferred: `dist/` holds the last good emit, so reloading would show working
+            // code for broken source. The shell says so instead, and the next clean compile reloads.
+            this.pendingReason = null;
+            this.options.onBuild('failed', `${errorCount} TypeScript error${errorCount === 1 ? '' : 's'} — the game was not rebuilt.`);
+            return;
+        }
+        this.options.onBuild('ok');
+        this.release();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.pendingReason = null;
+    }
+    /** Send the pending reload, unless a compile is still open — then it waits for `noteCompileEnd`. */
+    release() {
+        if (this.pendingReason === null || this.compiling)
+            return;
+        const reason = this.pendingReason;
+        this.pendingReason = null;
+        this.options.onReload(reason);
+    }
+}
+/** Path segments that never mean "the project changed". */
+const IGNORED_SEGMENTS = new Set(['node_modules', '.bitmagic', '.vite-cache', '.git']);
+/**
+ * Editors write through temporary siblings — vim's `4913`/`~`, JetBrains' `___jb_tmp___`, an
+ * atomic-rename `.tmp`. Reloading on those means reloading on a file that no longer exists.
+ */
+function isIgnoredPath(relative) {
+    const segments = relative.split(path.sep);
+    if (segments.some((segment) => IGNORED_SEGMENTS.has(segment)))
+        return true;
+    const name = segments[segments.length - 1] ?? '';
+    return name.startsWith('.') || name.endsWith('~') || name.includes('___jb_') || name.endsWith('.tmp');
+}
+/**
+ * Watch the two directories that decide what the browser shows: `src/` (what the agent and the
+ * creator edit — including `work/world.json`) and `dist/` (what the page actually loads).
+ *
+ * `dist/` is watched as well as `src/` even though the compile gate already covers the normal
+ * `tsc --watch` path, because it is what a build run outside this process — a manual `tsc`, an
+ * editor's own compiler — lands in, and that should reach the browser too.
+ *
+ * A directory that cannot be watched is skipped with a note rather than failing the command: a
+ * missing `dist/` means "not built yet", and losing auto-reload is a smaller loss than losing
+ * `bitmagic dev`.
+ */
+export function watchProject(root, coordinator, log) {
+    const watchers = [];
+    for (const dir of ['src', 'dist']) {
+        const absolute = path.join(root, dir);
+        if (!fs.existsSync(absolute))
+            continue;
+        try {
+            const watcher = fs.watch(absolute, { recursive: true }, (_event, filename) => {
+                const relative = filename === null ? '' : String(filename);
+                if (relative !== '' && isIgnoredPath(relative))
+                    return;
+                coordinator.noteFileChange(path.posix.join(dir, relative.split(path.sep).join('/')));
+            });
+            watcher.on('error', (error) => {
+                log(`[dev] stopped watching ${dir}/: ${error.message}`);
+            });
+            watchers.push(watcher);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log(`[dev] could not watch ${dir}/ (${message}) — reload on change is off for it.`);
+        }
+    }
+    return {
+        close: () => {
+            for (const watcher of watchers)
+                watcher.close();
+        },
+    };
+}
+/** tsc colourises when it thinks it is on a terminal; the markers below must match either way. */
+// eslint-disable-next-line no-control-regex
+const ANSI = /\u001B\[[0-9;]*m/g;
+const COMPILE_STARTED = /(File change detected|Starting compilation in watch mode)/;
+const COMPILE_FINISHED = /Found (\d+) error/;
+/**
+ * Feed one line of `tsc --watch` output to the coordinator. Exported for its test — the markers are
+ * tsc's own wording, and a version that changes them would otherwise break auto-reload silently.
+ */
+export function noteTscLine(line, coordinator) {
+    const plain = line.replace(ANSI, '');
+    const finished = COMPILE_FINISHED.exec(plain);
+    if (finished) {
+        coordinator.noteCompileEnd(Number(finished[1]));
+        return;
+    }
+    if (COMPILE_STARTED.test(plain))
+        coordinator.noteCompileStart();
+}
+/**
+ * Spawn `tsc --watch` with its output piped through us instead of inherited.
+ *
+ * Piping is what makes the compile gate possible — the only signal that a build finished, and
+ * whether it finished clean, is tsc's own `Found N errors` line. Every line is re-echoed verbatim,
+ * so the creator sees exactly what an inherited stdio would have shown, and `--pretty` is forced
+ * back on when our own stdout is a terminal (tsc drops colour the moment it is piped).
+ */
+export function pipeTscWatch(tsc, cwd, coordinator) {
+    const args = ['--watch', '--preserveWatchOutput'];
+    if (process.stdout.isTTY)
+        args.push('--pretty');
+    const child = spawn(tsc, args, { cwd, stdio: ['inherit', 'pipe', 'pipe'] });
+    const consume = (stream, echo) => {
+        if (!stream)
+            return;
+        let buffered = '';
+        stream.setEncoding('utf-8');
+        stream.on('data', (chunk) => {
+            echo.write(chunk);
+            buffered += chunk;
+            const lines = buffered.split('\n');
+            // The last element is whatever came after the final newline — an incomplete line, held over.
+            buffered = lines.pop() ?? '';
+            for (const line of lines)
+                noteTscLine(line, coordinator);
+        });
+    };
+    consume(child.stdout, process.stdout);
+    consume(child.stderr, process.stderr);
+    return child;
+}
+//# sourceMappingURL=watch.js.map

package/dist/editor/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/editor/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,KAAK,EAAqB,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAI7B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAQtC,MAAM,OAAO,iBAAiB;IACX,OAAO,CAAqC;IACrD,KAAK,GAAyC,IAAI,CAAC;IACnD,aAAa,GAAkB,IAAI,CAAC;IACpC,SAAS,GAAG,KAAK,CAAC;IAClB,aAAa,GAAG,CAAC,CAAC;IAClB,OAAO,GAAG,KAAK,CAAC;IAExB,YAAY,OAAiC;QAC3C,IAAI,CAAC,OAAO,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,EAAE,CAAC;IAC1D,CAAC;IAED,sFAAsF;IACtF,cAAc,CAAC,MAAc;QAC3B,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa;YAAE,OAAO;QAC5C,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;QAC5B,IAAI,IAAI,CAAC,KAAK;YAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC3B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,MAAc;QACvB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAC3C,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;QAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;IACjD,CAAC;IAED,qFAAqF;IACrF,YAAY;QACV,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,kBAAkB,CAAC;IACvD,CAAC;IAED,gBAAgB;QACd,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;IAED,cAAc,CAAC,UAAkB;QAC/B,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACnB,2FAA2F;YAC3F,yFAAyF;YACzF,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,OAAO,CAClB,QAAQ,EACR,GAAG,UAAU,oBAAoB,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,8BAA8B,CAC3F,CAAC;YACF,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,KAAK;YAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;IAC5B,CAAC;IAED,oGAAoG;IAC5F,OAAO;QACb,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC;QAClC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;CACF;AAED,2DAA2D;AAC3D,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;AAEvF;;;GAGG;AACH,SAAS,aAAa,CAAC,QAAgB;IACrC,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3E,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACjD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACxG,CAAC;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,WAA8B,EAC9B,GAA8B;IAE9B,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,SAAS;QACvC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE;gBAC3E,MAAM,QAAQ,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBAC3D,IAAI,QAAQ,KAAK,EAAE,IAAI,aAAa,CAAC,QAAQ,CAAC;oBAAE,OAAO;gBACvD,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACvF,CAAC,CAAC,CAAC;YACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;gBACnC,GAAG,CAAC,0BAA0B,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1D,CAAC,CAAC,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,GAAG,CAAC,yBAAyB,GAAG,MAAM,OAAO,qCAAqC,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IACD,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,KAAK,MAAM,OAAO,IAAI,QAAQ;gBAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAClD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,kGAAkG;AAClG,4CAA4C;AAC5C,MAAM,IAAI,GAAG,mBAAmB,CAAC;AAEjC,MAAM,eAAe,GAAG,2DAA2D,CAAC;AACpF,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,WAA8B;IACtE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,QAAQ,EAAE,CAAC;QACb,WAAW,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,OAAO;IACT,CAAC;IACD,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,WAAW,CAAC,gBAAgB,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAW,EACX,GAAW,EACX,WAA8B;IAE9B,MAAM,IAAI,GAAG,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC;IAClD,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAE5E,MAAM,OAAO,GAAG,CAAC,MAAuB,EAAE,IAAc,EAAQ,EAAE;QAChE,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,QAAQ,GAAG,EAAE,CAAC;QAClB,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClB,QAAQ,IAAI,KAAK,CAAC;YAClB,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACnC,6FAA6F;YAC7F,QAAQ,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;YAC7B,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/local-port.d.ts

@@ -16,6 +16,16 @@
  */
 export declare const CORS_ALLOWED_PORT_MIN = 3000;
 export declare const CORS_ALLOWED_PORT_MAX = 3199;
+/**
+ * A `--port`-style flag parsed and checked against the window above.
+ *
+ * Every port `bitmagic dev` binds goes through here, the game port for the reason documented above
+ * and the shell port because the two are adjacent by default: a creator who moves one will move the
+ * other, and being told the rule once, at the point of the mistake, beats discovering it as a
+ * terrain-less world. (The shell itself fetches nothing from the CDN, so its own check is purely
+ * that kindness.)
+ */
+export declare function parseLocalPort(value: string | undefined, fallback: number, flag: string): number;
 /**
  * A free port the CDN will serve assets to, or `null` when the whole window is taken.
  *

package/dist/local-port.js

@@ -1,4 +1,5 @@
 import * as net from 'net';
+import { CliError } from './errors.js';
 /**
  * The port window the platform's bucket CORS policy allowlists as an origin.
  *
@@ -17,6 +18,28 @@ import * as net from 'net';
  */
 export const CORS_ALLOWED_PORT_MIN = 3000;
 export const CORS_ALLOWED_PORT_MAX = 3199;
+/**
+ * A `--port`-style flag parsed and checked against the window above.
+ *
+ * Every port `bitmagic dev` binds goes through here, the game port for the reason documented above
+ * and the shell port because the two are adjacent by default: a creator who moves one will move the
+ * other, and being told the rule once, at the point of the mistake, beats discovering it as a
+ * terrain-less world. (The shell itself fetches nothing from the CDN, so its own check is purely
+ * that kindness.)
+ */
+export function parseLocalPort(value, fallback, flag) {
+    if (value === undefined)
+        return fallback;
+    const port = Number(value);
+    if (!Number.isInteger(port)) {
+        throw new CliError(`\`${flag}\` must be a whole number, got "${value}".`);
+    }
+    if (port < CORS_ALLOWED_PORT_MIN || port > CORS_ALLOWED_PORT_MAX) {
+        throw new CliError(`\`${flag}\` must be between ${CORS_ALLOWED_PORT_MIN} and ${CORS_ALLOWED_PORT_MAX}. `
+            + 'The asset CDN only allows those origins; outside that window the game loads with no terrain.');
+    }
+    return port;
+}
 function tryListen(port) {
     return new Promise((resolve) => {
         const server = net.createServer();

package/dist/local-port.js.map

@@ -1 +1 @@
-{"version":3,"file":"local-port.js","sourceRoot":"","sources":["../src/local-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAE3B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAE1C,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE;YACpC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACpF,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAC1C,MAAM,IAAI,GAAG,qBAAqB,GAAG,qBAAqB,GAAG,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,qBAAqB,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;IACnC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"local-port.js","sourceRoot":"","sources":["../src/local-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAC3B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAyB,EAAE,QAAgB,EAAE,IAAY;IACtF,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,QAAQ,CAAC,KAAK,IAAI,mCAAmC,KAAK,IAAI,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,IAAI,GAAG,qBAAqB,IAAI,IAAI,GAAG,qBAAqB,EAAE,CAAC;QACjE,MAAM,IAAI,QAAQ,CAChB,KAAK,IAAI,sBAAsB,qBAAqB,QAAQ,qBAAqB,IAAI;cACnF,8FAA8F,CACjG,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE;YACpC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACpF,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAC1C,MAAM,IAAI,GAAG,qBAAqB,GAAG,qBAAqB,GAAG,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,qBAAqB,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;IACnC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/project/dev-handle.d.ts

@@ -0,0 +1,14 @@
+export interface DevHandle {
+    /** The `--editor-port` value: where the tabbed Game/Editor shell is served — the URL to open. */
+    editorPort: number;
+    /** The `--port` value: where vite serves the game itself. */
+    gamePort: number;
+    /** The `bitmagic dev` process, for a human reading the file. Never used as a liveness check. */
+    pid: number;
+}
+export declare function devHandlePath(root: string): string;
+export declare function writeDevHandle(root: string, handle: DevHandle): void;
+/** Best-effort: a handle we cannot remove is a stale file, never a failed shutdown. */
+export declare function removeDevHandle(root: string): void;
+/** The recorded handle, or null when there is no readable one. */
+export declare function readDevHandle(root: string): DevHandle | null;

package/dist/project/dev-handle.js

@@ -0,0 +1,53 @@
+/**
+ * `.bitmagic/dev.json` — how a second process finds the `bitmagic dev` already running here.
+ *
+ * `bitmagic reload` needs the shell's port, and hard-coding 3011 would break the moment a creator
+ * passes `--editor-port`. So `dev` writes what it bound the instant it is listening, and removes the
+ * file on shutdown. `.bitmagic/` is already gitignored (scaffold/project-files.ts renderGitignore),
+ * so this never reaches a commit.
+ *
+ * A stale file is expected, not exceptional: a `dev` killed with SIGKILL leaves one behind. Nothing
+ * here tries to detect that — `reload` simply fails to connect to the recorded port and reports that
+ * no dev server is running, which is the same outcome and the same message as no file at all. The
+ * pid is recorded for a human reading the file, not for liveness checks.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export function devHandlePath(root) {
+    return path.join(root, '.bitmagic', 'dev.json');
+}
+export function writeDevHandle(root, handle) {
+    const file = devHandlePath(root);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(handle, null, 2)}\n`);
+}
+/** Best-effort: a handle we cannot remove is a stale file, never a failed shutdown. */
+export function removeDevHandle(root) {
+    try {
+        fs.rmSync(devHandlePath(root), { force: true });
+    }
+    catch {
+        // See above.
+    }
+}
+/** The recorded handle, or null when there is no readable one. */
+export function readDevHandle(root) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(devHandlePath(root), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const record = parsed;
+    if (typeof record.editorPort !== 'number' || typeof record.gamePort !== 'number')
+        return null;
+    return {
+        editorPort: record.editorPort,
+        gamePort: record.gamePort,
+        pid: typeof record.pid === 'number' ? record.pid : 0,
+    };
+}
+//# sourceMappingURL=dev-handle.js.map

package/dist/project/dev-handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-handle.js","sourceRoot":"","sources":["../../src/project/dev-handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAW7B,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,MAAiB;IAC5D,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACjC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAC;QACH,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,aAAa;IACf,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACxF,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC9F,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,GAAG,EAAE,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;KACrD,CAAC;AACJ,CAAC"}

package/dist/scaffold/claude-settings.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `.claude/settings.json` — the one line that makes the browser reload when the agent stops.
+ *
+ * `bitmagic dev` reloads on its own once writes go quiet, which is right for a human saving a file
+ * and a guess for an agent, because an agent pauses to think and a long enough pause reads as
+ * "finished". Claude Code's `Stop` hook removes the guess: it fires exactly once, when the turn
+ * ends, and running `bitmagic reload` there means the creator sees the finished work rather than a
+ * frame from the middle of it.
+ *
+ * ── Why this file is merged and not rendered ─────────────────────────────────────────────────
+ *
+ * Every other file the CLI ships into `.claude/` is in PLATFORM_GENERATED_FILES, which `upgrade`
+ * overwrites wholesale — correct for a skill that documents the CLI, since a stale copy is worse
+ * than a lost edit. `settings.json` is the opposite: it is where a creator puts their permissions,
+ * their env, their own hooks. Overwriting it would delete work that was never ours, so `upgrade`
+ * adds our hook to whatever is there and touches nothing else, in the same read-modify-write shape
+ * `bitmagic.json` already uses.
+ *
+ * Anything that cannot be merged confidently is left alone entirely. A creator with a hand-written
+ * settings file that we cannot parse keeps their file; they lose auto-reload-on-stop, which the
+ * watcher in `editor/watch.ts` mostly covers anyway.
+ */
+export declare const CLAUDE_SETTINGS_FILE = ".claude/settings.json";
+/** What the hook runs. One definition, so the scaffold and the merge cannot disagree. */
+export declare const RELOAD_HOOK_COMMAND = "bitmagic reload";
+export interface ReloadHookMerge {
+    /** The text to write, or null to leave the file exactly as it is. */
+    contents: string | null;
+    /** Present only when `contents` is null *because* the file could not be merged. */
+    skipped?: string;
+}
+/** The settings a project with no `.claude/settings.json` at all gets. */
+export declare function renderClaudeSettings(): string;
+/**
+ * Add the Stop hook to an existing settings file, preserving everything else in it.
+ *
+ * `existing` is the file's text, or undefined when there is no file. Returns `contents: null` when
+ * there is nothing to do — the hook is already there, or the file is not something we can safely
+ * rewrite.
+ */
+export declare function mergeReloadHook(existing: string | undefined): ReloadHookMerge;

package/dist/scaffold/claude-settings.js

@@ -0,0 +1,98 @@
+/**
+ * `.claude/settings.json` — the one line that makes the browser reload when the agent stops.
+ *
+ * `bitmagic dev` reloads on its own once writes go quiet, which is right for a human saving a file
+ * and a guess for an agent, because an agent pauses to think and a long enough pause reads as
+ * "finished". Claude Code's `Stop` hook removes the guess: it fires exactly once, when the turn
+ * ends, and running `bitmagic reload` there means the creator sees the finished work rather than a
+ * frame from the middle of it.
+ *
+ * ── Why this file is merged and not rendered ─────────────────────────────────────────────────
+ *
+ * Every other file the CLI ships into `.claude/` is in PLATFORM_GENERATED_FILES, which `upgrade`
+ * overwrites wholesale — correct for a skill that documents the CLI, since a stale copy is worse
+ * than a lost edit. `settings.json` is the opposite: it is where a creator puts their permissions,
+ * their env, their own hooks. Overwriting it would delete work that was never ours, so `upgrade`
+ * adds our hook to whatever is there and touches nothing else, in the same read-modify-write shape
+ * `bitmagic.json` already uses.
+ *
+ * Anything that cannot be merged confidently is left alone entirely. A creator with a hand-written
+ * settings file that we cannot parse keeps their file; they lose auto-reload-on-stop, which the
+ * watcher in `editor/watch.ts` mostly covers anyway.
+ */
+export const CLAUDE_SETTINGS_FILE = '.claude/settings.json';
+/** What the hook runs. One definition, so the scaffold and the merge cannot disagree. */
+export const RELOAD_HOOK_COMMAND = 'bitmagic reload';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringify(settings) {
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}
+/** The `Stop` matcher group this CLI owns. */
+function reloadMatcher() {
+    return { hooks: [{ type: 'command', command: RELOAD_HOOK_COMMAND }] };
+}
+/** The settings a project with no `.claude/settings.json` at all gets. */
+export function renderClaudeSettings() {
+    return stringify({ hooks: { Stop: [reloadMatcher()] } });
+}
+/**
+ * Does this `Stop` group already run our command?
+ *
+ * Matched by substring rather than equality on purpose: a creator who wrapped it — `cd app &&
+ * bitmagic reload`, `bitmagic reload --port 3021` — has the hook, and adding a second one would
+ * reload twice per turn.
+ */
+function runsReload(matcher) {
+    if (!isRecord(matcher))
+        return false;
+    const hooks = matcher.hooks;
+    if (!Array.isArray(hooks))
+        return false;
+    return hooks.some((hook) => {
+        if (!isRecord(hook))
+            return false;
+        const command = hook.command;
+        return typeof command === 'string' && command.includes(RELOAD_HOOK_COMMAND);
+    });
+}
+/**
+ * Add the Stop hook to an existing settings file, preserving everything else in it.
+ *
+ * `existing` is the file's text, or undefined when there is no file. Returns `contents: null` when
+ * there is nothing to do — the hook is already there, or the file is not something we can safely
+ * rewrite.
+ */
+export function mergeReloadHook(existing) {
+    if (existing === undefined || existing.trim() === '') {
+        return { contents: renderClaudeSettings() };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(existing);
+    }
+    catch {
+        return { contents: null, skipped: `${CLAUDE_SETTINGS_FILE} is not valid JSON` };
+    }
+    if (!isRecord(parsed)) {
+        return { contents: null, skipped: `${CLAUDE_SETTINGS_FILE} does not contain a settings object` };
+    }
+    const hooks = parsed.hooks === undefined ? {} : parsed.hooks;
+    if (!isRecord(hooks)) {
+        return { contents: null, skipped: `${CLAUDE_SETTINGS_FILE} has a "hooks" value we cannot merge into` };
+    }
+    const stop = hooks.Stop === undefined ? [] : hooks.Stop;
+    if (!Array.isArray(stop)) {
+        return { contents: null, skipped: `${CLAUDE_SETTINGS_FILE} has a "hooks.Stop" value we cannot merge into` };
+    }
+    if (stop.some(runsReload))
+        return { contents: null };
+    return {
+        contents: stringify({
+            ...parsed,
+            hooks: { ...hooks, Stop: [...stop, reloadMatcher()] },
+        }),
+    };
+}
+//# sourceMappingURL=claude-settings.js.map

package/dist/scaffold/claude-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-settings.js","sourceRoot":"","sources":["../../src/scaffold/claude-settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAE5D,yFAAyF;AACzF,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAkBrD,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,SAAS,CAAC,QAAiB;IAClC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED,8CAA8C;AAC9C,SAAS,aAAa;IACpB,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC,EAAE,CAAC;AACxE,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,oBAAoB;IAClC,OAAO,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,SAAS,UAAU,CAAC,OAAgB;IAClC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,MAAM,KAAK,GAAI,OAAuB,CAAC,KAAK,CAAC;IAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAa,EAAE,EAAE;QAClC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAClC,MAAM,OAAO,GAAI,IAAkB,CAAC,OAAO,CAAC;QAC5C,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,QAA4B;IAC1D,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,EAAE,CAAC;IAC9C,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,oBAAoB,oBAAoB,EAAE,CAAC;IAClF,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,oBAAoB,qCAAqC,EAAE,CAAC;IACnG,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;IAC7D,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,oBAAoB,2CAA2C,EAAE,CAAC;IACzG,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;IACxD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,oBAAoB,gDAAgD,EAAE,CAAC;IAC9G,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAErD,OAAO;QACL,QAAQ,EAAE,SAAS,CAAC;YAClB,GAAG,MAAM;YACT,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,aAAa,EAAE,CAAC,EAAE;SACtD,CAAC;KACH,CAAC;AACJ,CAAC"}