@cat-factory/cli 0.8.6 → 0.9.0

package/dist/supervise.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Decision core for `cat-factory supervise` — the self-healing local-dev supervisor.
+ *
+ * WHY THIS EXISTS. Every local deployment runs its server under `node --watch`, and
+ * `node --watch` PARKS on crash: it restarts the entry only on a FILE CHANGE, never on a process
+ * exit. A sleeping laptop is the common trigger — on resume the Postgres/Docker connection is
+ * gone, the server dies in `migrate`, and the watcher settles at "Waiting for file changes before
+ * restarting". The result is the worst kind of failure: the wrapper PID is still alive and the
+ * ready banner has already scrolled past, so the stack LOOKS running while nothing is bound to
+ * the port, and the SPA reports only a generic "can't reach backend". It never self-heals, and it
+ * stays that way until someone notices and restarts by hand.
+ *
+ * This module is the JUDGEMENT half of the fix, kept pure — no sockets, no processes, no ambient
+ * clock — so every transition is unit-testable from a table of observations (`supervise.test.ts`).
+ * `supervise-runtime.ts` owns the effects and feeds observations in. That split is the same one
+ * `scripts/silent-catch.mjs` documents for itself: a guard whose judgement nothing tests is a
+ * guard that is trusted without evidence.
+ */
+/** Tuning for the supervisor loop. Resolve partial input with {@link resolveSuperviseConfig}. */
+export interface SuperviseConfig {
+    /** How often the health probe runs. */
+    pollMs: number;
+    /**
+     * Grace window after a (re)start during which a failed probe does NOT count against the child.
+     * A cold boot builds the workspace dependency and runs migrations first, so the port legitimately
+     * stays unbound for a while.
+     */
+    bootGraceMs: number;
+    /** Grace window after a detected resume, so a still-waking Docker/Postgres isn't blamed. */
+    resumeGraceMs: number;
+    /**
+     * A tick arriving this much later than `pollMs` means time jumped — the host slept (or stalled
+     * hard). Timers do not fire while suspended, so lateness is the signal.
+     *
+     * The measurement is deliberately taken tick-START to tick-START (see {@link step}): sampling it
+     * after the probe would fold the probe's own duration into the drift, and a probe that times out
+     * on a filtered port takes seconds — enough to read as a suspend on a short `--poll` and so to
+     * bypass `failureThreshold` entirely.
+     */
+    clockJumpMs: number;
+    /** Consecutive failed probes required before a repair (outside any grace window). */
+    failureThreshold: number;
+    /**
+     * How many restarts in a row may fail to produce a SERVING stack before the supervisor reports
+     * and gives up. A command that is simply broken (a syntax error, a missing binary, a port already
+     * owned by something else) can never be fixed by restarting it, and looping forever on it is the
+     * exact pathology this supervisor exists to end — the motivating incident was a container that
+     * restarted 518 times, exiting 0 each time, while `docker ps` showed healthy motion.
+     */
+    maxFailedStarts: number;
+}
+/** Defaults chosen for a laptop-dev loop: notice within ~30s, never fight a cold boot. */
+export declare const SUPERVISE_DEFAULTS: {
+    readonly pollMs: 10000;
+    readonly bootGraceMs: 60000;
+    readonly resumeGraceMs: 25000;
+    readonly failureThreshold: 3;
+    readonly maxFailedStarts: 5;
+};
+/**
+ * Fill in defaults and derive `clockJumpMs` from the poll interval. A tick 3 intervals late is
+ * well outside normal scheduler jitter but still catches a short suspend.
+ */
+export declare function resolveSuperviseConfig(partial?: Partial<SuperviseConfig>): SuperviseConfig;
+/** Loop state carried between ticks. Treated as immutable: {@link step} returns the next one. */
+export interface SuperviseState {
+    /** Consecutive failed probes so far, reset by any success or repair. */
+    failures: number;
+    /** No failed probe counts against the child until this timestamp (boot/resume grace). */
+    quietUntil: number;
+    /** When the previous tick ran — the basis for clock-jump (sleep) detection. */
+    lastTickAt: number;
+}
+/** What the runtime should do about this tick. Every branch of {@link step} names one. */
+export type SuperviseAction = 
+/** Serving, and it was serving before too — nothing to say. */
+{
+    kind: 'serving';
+}
+/** Serving again after one or more failed probes, without needing a repair. */
+ | {
+    kind: 'recovered';
+    afterFailures: number;
+}
+/** Not serving, but inside a boot/resume grace window — wait it out. */
+ | {
+    kind: 'grace';
+    msLeft: number;
+}
+/** Not serving; failure counted but still below the threshold. */
+ | {
+    kind: 'counting';
+    failures: number;
+    threshold: number;
+}
+/** Run the recovery ladder: re-check dependencies, then restart the child. */
+ | {
+    kind: 'repair';
+    reason: string;
+}
+/** The host resumed from sleep and the stack is still serving. */
+ | {
+    kind: 'resumed';
+    driftMs: number;
+};
+/** State for a freshly started child: clean counters and a full boot grace window. */
+export declare function initialState(now: number, config: SuperviseConfig): SuperviseState;
+/**
+ * State to adopt right after (re)spawning a child mid-run — a fresh boot grace, counters clear.
+ *
+ * `lastTickAt` is re-based on `now` (the moment the new child started), NOT carried over from the
+ * previous tick, because a repair is not instantaneous: it runs the whole dependency ladder first,
+ * and those budgets are 90s (compose readiness) and 120s (apiserver readiness) against a default
+ * `clockJumpMs` of 30s. Carrying the old timestamp forward makes the very next tick measure the
+ * repair's own duration as drift, read a slow-but-successful recovery as a host suspend, and — since
+ * resume detection deliberately outranks the boot-grace window — immediately kill the child it just
+ * started. Re-basing means the clock-jump signal only ever measures time we were genuinely idle.
+ */
+export declare function stateAfterStart(now: number, config: SuperviseConfig): SuperviseState;
+/**
+ * One tick of the supervisor: current state + what we just observed -> next state + the action to
+ * take. Pure; the caller supplies `now` and the probe result.
+ *
+ * `now` must be sampled at the START of the tick, before the probe runs — see `clockJumpMs`.
+ *
+ * Order matters:
+ *  1. The clock-jump check runs FIRST and outranks the grace windows, because a resume is precisely
+ *     when the stack is most likely already dead — deferring it to the normal threshold path would
+ *     idle for another `failureThreshold * pollMs` before repairing something we can already tell
+ *     is broken.
+ *  2. A confirmed-serving stack short-circuits everything below it.
+ *  3. A child that has EXITED then repairs immediately, ahead of the grace window and the failure
+ *     counter, because neither can tell us anything a dead process handle hasn't already: counting
+ *     three more probes against a process that does not exist just adds `failureThreshold * pollMs`
+ *     of downtime. This is checked only once the stack is known not to be serving, so a wrapper that
+ *     exits while its grandchild keeps serving (a shell that `exec`s away, say) is left alone
+ *     rather than having a healthy server restarted out from under it.
+ */
+export declare function step(state: SuperviseState, observation: {
+    now: number;
+    serving: boolean;
+    childExited?: boolean;
+}, config: SuperviseConfig): {
+    state: SuperviseState;
+    action: SuperviseAction;
+};
+//# sourceMappingURL=supervise.d.ts.map

package/dist/supervise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervise.d.ts","sourceRoot":"","sources":["../src/supervise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,iGAAiG;AACjG,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,4FAA4F;IAC5F,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,qFAAqF;IACrF,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB;aAC7B,MAAM,EAAE,KAAM;aACd,WAAW,EAAE,KAAM;aACnB,aAAa,EAAE,KAAM;aACrB,gBAAgB,EAAE,CAAC;aACnB,eAAe,EAAE,CAAC;CACV,CAAA;AAEV;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,eAAe,CAU9F;AAED,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,0FAA0F;AAC1F,MAAM,MAAM,eAAe;AACzB,+DAA+D;AAC7D;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB,+EAA+E;GAC7E;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE;AAC9C,wEAAwE;GACtE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACnC,kEAAkE;GAChE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AAC3D,8EAA8E;GAC5E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACpC,kEAAkE;GAChE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAExC,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,cAAc,CAEjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,cAAc,CAEpF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAClB,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,EACrE,MAAM,EAAE,eAAe,GACtB;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAwDpD"}

package/dist/supervise.js

@@ -0,0 +1,130 @@
+/**
+ * Decision core for `cat-factory supervise` — the self-healing local-dev supervisor.
+ *
+ * WHY THIS EXISTS. Every local deployment runs its server under `node --watch`, and
+ * `node --watch` PARKS on crash: it restarts the entry only on a FILE CHANGE, never on a process
+ * exit. A sleeping laptop is the common trigger — on resume the Postgres/Docker connection is
+ * gone, the server dies in `migrate`, and the watcher settles at "Waiting for file changes before
+ * restarting". The result is the worst kind of failure: the wrapper PID is still alive and the
+ * ready banner has already scrolled past, so the stack LOOKS running while nothing is bound to
+ * the port, and the SPA reports only a generic "can't reach backend". It never self-heals, and it
+ * stays that way until someone notices and restarts by hand.
+ *
+ * This module is the JUDGEMENT half of the fix, kept pure — no sockets, no processes, no ambient
+ * clock — so every transition is unit-testable from a table of observations (`supervise.test.ts`).
+ * `supervise-runtime.ts` owns the effects and feeds observations in. That split is the same one
+ * `scripts/silent-catch.mjs` documents for itself: a guard whose judgement nothing tests is a
+ * guard that is trusted without evidence.
+ */
+/** Defaults chosen for a laptop-dev loop: notice within ~30s, never fight a cold boot. */
+export const SUPERVISE_DEFAULTS = {
+    pollMs: 10_000,
+    bootGraceMs: 60_000,
+    resumeGraceMs: 25_000,
+    failureThreshold: 3,
+    maxFailedStarts: 5,
+};
+/**
+ * Fill in defaults and derive `clockJumpMs` from the poll interval. A tick 3 intervals late is
+ * well outside normal scheduler jitter but still catches a short suspend.
+ */
+export function resolveSuperviseConfig(partial = {}) {
+    const pollMs = partial.pollMs ?? SUPERVISE_DEFAULTS.pollMs;
+    return {
+        pollMs,
+        bootGraceMs: partial.bootGraceMs ?? SUPERVISE_DEFAULTS.bootGraceMs,
+        resumeGraceMs: partial.resumeGraceMs ?? SUPERVISE_DEFAULTS.resumeGraceMs,
+        clockJumpMs: partial.clockJumpMs ?? pollMs * 3,
+        failureThreshold: partial.failureThreshold ?? SUPERVISE_DEFAULTS.failureThreshold,
+        maxFailedStarts: partial.maxFailedStarts ?? SUPERVISE_DEFAULTS.maxFailedStarts,
+    };
+}
+/** State for a freshly started child: clean counters and a full boot grace window. */
+export function initialState(now, config) {
+    return { failures: 0, quietUntil: now + config.bootGraceMs, lastTickAt: now };
+}
+/**
+ * State to adopt right after (re)spawning a child mid-run — a fresh boot grace, counters clear.
+ *
+ * `lastTickAt` is re-based on `now` (the moment the new child started), NOT carried over from the
+ * previous tick, because a repair is not instantaneous: it runs the whole dependency ladder first,
+ * and those budgets are 90s (compose readiness) and 120s (apiserver readiness) against a default
+ * `clockJumpMs` of 30s. Carrying the old timestamp forward makes the very next tick measure the
+ * repair's own duration as drift, read a slow-but-successful recovery as a host suspend, and — since
+ * resume detection deliberately outranks the boot-grace window — immediately kill the child it just
+ * started. Re-basing means the clock-jump signal only ever measures time we were genuinely idle.
+ */
+export function stateAfterStart(now, config) {
+    return { failures: 0, quietUntil: now + config.bootGraceMs, lastTickAt: now };
+}
+/**
+ * One tick of the supervisor: current state + what we just observed -> next state + the action to
+ * take. Pure; the caller supplies `now` and the probe result.
+ *
+ * `now` must be sampled at the START of the tick, before the probe runs — see `clockJumpMs`.
+ *
+ * Order matters:
+ *  1. The clock-jump check runs FIRST and outranks the grace windows, because a resume is precisely
+ *     when the stack is most likely already dead — deferring it to the normal threshold path would
+ *     idle for another `failureThreshold * pollMs` before repairing something we can already tell
+ *     is broken.
+ *  2. A confirmed-serving stack short-circuits everything below it.
+ *  3. A child that has EXITED then repairs immediately, ahead of the grace window and the failure
+ *     counter, because neither can tell us anything a dead process handle hasn't already: counting
+ *     three more probes against a process that does not exist just adds `failureThreshold * pollMs`
+ *     of downtime. This is checked only once the stack is known not to be serving, so a wrapper that
+ *     exits while its grandchild keeps serving (a shell that `exec`s away, say) is left alone
+ *     rather than having a healthy server restarted out from under it.
+ */
+export function step(state, observation, config) {
+    const { now, serving } = observation;
+    const driftMs = now - state.lastTickAt - config.pollMs;
+    if (driftMs > config.clockJumpMs) {
+        // Timers stalled, so wall-clock time passed without us running: the host suspended. Extend the
+        // quiet window either way — a resume needs a moment for Docker's VM and the DB to come back.
+        const quietUntil = Math.max(state.quietUntil, now + config.resumeGraceMs);
+        if (serving) {
+            return {
+                state: { failures: 0, quietUntil, lastTickAt: now },
+                action: { kind: 'resumed', driftMs },
+            };
+        }
+        return {
+            state: { failures: 0, quietUntil, lastTickAt: now },
+            action: {
+                kind: 'repair',
+                reason: `not serving after a ${Math.round(driftMs / 1000)}s stall (host slept?)`,
+            },
+        };
+    }
+    if (serving) {
+        const action = state.failures > 0
+            ? { kind: 'recovered', afterFailures: state.failures }
+            : { kind: 'serving' };
+        return { state: { failures: 0, quietUntil: state.quietUntil, lastTickAt: now }, action };
+    }
+    if (observation.childExited === true) {
+        return {
+            state: { failures: 0, quietUntil: state.quietUntil, lastTickAt: now },
+            action: { kind: 'repair', reason: 'the supervised command exited' },
+        };
+    }
+    if (now < state.quietUntil) {
+        return {
+            state: { ...state, lastTickAt: now },
+            action: { kind: 'grace', msLeft: state.quietUntil - now },
+        };
+    }
+    const failures = state.failures + 1;
+    if (failures >= config.failureThreshold) {
+        return {
+            state: { failures: 0, quietUntil: state.quietUntil, lastTickAt: now },
+            action: { kind: 'repair', reason: `${failures} consecutive failed health probes` },
+        };
+    }
+    return {
+        state: { failures, quietUntil: state.quietUntil, lastTickAt: now },
+        action: { kind: 'counting', failures, threshold: config.failureThreshold },
+    };
+}
+//# sourceMappingURL=supervise.js.map

package/dist/supervise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervise.js","sourceRoot":"","sources":["../src/supervise.ts"],"names":[],"mappings":"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"}

package/dist/superviseCommand.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `cat-factory supervise` — wire the real effects into the supervision loop.
+ *
+ * Thin on purpose: the judgement lives in `supervise.ts`, the effects in `supervise-runtime.ts`.
+ * This resolves flags into a config, builds the process/socket/shell-backed seams, prints what it
+ * is about to watch, and hands over to `runSupervisor`.
+ */
+import { type CliOptions } from './args.js';
+/**
+ * Re-quote a token that contains whitespace. The child is launched as one shell string (see
+ * `createChildLauncher`), so a path with a space in it would otherwise split into two arguments —
+ * `C:\Program Files\nodejs\node.exe` being the case that matters on Windows.
+ *
+ * Deliberately NOT `JSON.stringify`: that escapes backslashes (`C:\\Program Files\\…`), which no
+ * shell unescapes, so the quoted path becomes a path that does not exist. Only the surrounding
+ * quotes and any embedded quote need handling.
+ *
+ * The escape for an embedded quote is platform-specific, because `shell: true` means a genuinely
+ * different shell on each side: `cmd.exe` does not honour a backslash escape at all (it would pass
+ * the backslash through and treat the quote as closing the argument), and doubles the quote instead.
+ * `platform` is injectable so both dialects are testable from either host.
+ */
+export declare function quoteToken(token: string, platform?: string): string;
+export declare function supervise(options: CliOptions): Promise<void>;
+//# sourceMappingURL=superviseCommand.d.ts.map

package/dist/superviseCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"superviseCommand.d.ts","sourceRoot":"","sources":["../src/superviseCommand.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAY,KAAK,UAAU,EAAoC,MAAM,WAAW,CAAA;AAcvF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAyB,GAAG,MAAM,CAMrF;AAkBD,wBAAsB,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAsGlE"}

package/dist/superviseCommand.js

@@ -0,0 +1,136 @@
+/**
+ * `cat-factory supervise` — wire the real effects into the supervision loop.
+ *
+ * Thin on purpose: the judgement lives in `supervise.ts`, the effects in `supervise-runtime.ts`.
+ * This resolves flags into a config, builds the process/socket/shell-backed seams, prints what it
+ * is about to watch, and hands over to `runSupervisor`.
+ */
+import { resolve } from 'node:path';
+import { ArgError, OPTION_DEFAULTS } from './args.js';
+import { createNodeShell } from './host-shell.js';
+import { createK3sClusterDependency } from './supervise-k3s.js';
+import { createChildLauncher, createComposeDependency, createHealthProbe, createPortReaper, OperatorActionRequiredError, runSupervisor, } from './supervise-runtime.js';
+import { resolveSuperviseConfig } from './supervise.js';
+/**
+ * Re-quote a token that contains whitespace. The child is launched as one shell string (see
+ * `createChildLauncher`), so a path with a space in it would otherwise split into two arguments —
+ * `C:\Program Files\nodejs\node.exe` being the case that matters on Windows.
+ *
+ * Deliberately NOT `JSON.stringify`: that escapes backslashes (`C:\\Program Files\\…`), which no
+ * shell unescapes, so the quoted path becomes a path that does not exist. Only the surrounding
+ * quotes and any embedded quote need handling.
+ *
+ * The escape for an embedded quote is platform-specific, because `shell: true` means a genuinely
+ * different shell on each side: `cmd.exe` does not honour a backslash escape at all (it would pass
+ * the backslash through and treat the quote as closing the argument), and doubles the quote instead.
+ * `platform` is injectable so both dialects are testable from either host.
+ */
+export function quoteToken(token, platform = process.platform) {
+    if (token === '')
+        return '""';
+    if (!/[\s"]/.test(token))
+        return token;
+    const escaped = platform === 'win32' ? token.replace(/"/g, '""') : token.replace(/"/g, String.raw `\"`);
+    return `"${escaped}"`;
+}
+/**
+ * Narrow the shared `--runtime` picklist to what a supervisor can actually start, REFUSING the
+ * third member rather than quietly treating it as k3d. `k3s` proper is a host service (systemd), not
+ * a set of containers this command owns, so it has no `cluster start` to call. Degrading silently
+ * would leave `k3d cluster list` never listing the cluster, so the dependency would report "not
+ * ready — will retry next cycle" on every cycle forever, with nothing naming the real reason.
+ */
+function supervisedRuntime(runtime) {
+    if (runtime === undefined)
+        return 'k3d';
+    if (runtime === 'k3d' || runtime === 'kind')
+        return runtime;
+    throw new ArgError(`--runtime ${runtime} cannot be supervised: a k3s host service has no cluster for this command ` +
+        'to start. Use --runtime k3d or --runtime kind, or drop --k3s-cluster.');
+}
+export async function supervise(options) {
+    const argv = options.superviseCommand ?? [];
+    if (argv.length === 0) {
+        throw new ArgError('supervise needs a command to run, after `--`\n' +
+            '  e.g. cat-factory supervise --port 8787 -- pnpm dev');
+    }
+    // Not `argv.map(quoteToken)`: `map` would pass the index as the platform argument.
+    const command = argv.map((token) => quoteToken(token)).join(' ');
+    const cwd = options.dir ? resolve(options.dir) : process.cwd();
+    const port = options.port ?? OPTION_DEFAULTS.port;
+    const healthPath = options.healthPath ?? OPTION_DEFAULTS.healthPath;
+    const config = resolveSuperviseConfig({
+        pollMs: options.pollSeconds !== undefined ? options.pollSeconds * 1_000 : undefined,
+        bootGraceMs: options.bootGraceSeconds !== undefined ? options.bootGraceSeconds * 1_000 : undefined,
+        failureThreshold: options.failures,
+    });
+    const shell = createNodeShell();
+    // Only wire the dependencies that were named — the supervisor is useful with none at all. Order
+    // matters: the database comes first because the server dies in `migrate` without it, while a dead
+    // cluster only breaks environment provisioning.
+    const dependencies = [];
+    if (options.composeService) {
+        dependencies.push(createComposeDependency(shell, {
+            dir: options.composeDir ? resolve(options.composeDir) : cwd,
+            service: options.composeService,
+        }));
+    }
+    if (options.k3sCluster) {
+        dependencies.push(createK3sClusterDependency(shell, {
+            cluster: options.k3sCluster,
+            runtime: supervisedRuntime(options.k3sRuntime),
+        }));
+    }
+    const launcher = createChildLauncher({ command, cwd });
+    const probe = createHealthProbe({ port, healthPath });
+    const log = (message) => {
+        process.stdout.write(`[supervise] ${message}\n`);
+    };
+    const reaper = createPortReaper(shell, port, { log });
+    log(`watching :${port}${healthPath} every ${config.pollMs / 1_000}s — ` +
+        `repairs after ${config.failureThreshold} failed probes or a detected resume`);
+    for (const dependency of dependencies)
+        log(`dependency: ${dependency.label}`);
+    log(`command: ${command}`);
+    // Bring the dependencies up BEFORE the first start, so a cold `pnpm dev:safe` on a machine whose
+    // engine was restarted doesn't spend its first boot crashing against a stopped database.
+    for (const dependency of dependencies) {
+        try {
+            const ready = await dependency.ensure();
+            log(ready
+                ? `✔ ${dependency.label} is ready`
+                : `✖ ${dependency.label} is not ready — starting anyway`);
+        }
+        catch (err) {
+            if (!(err instanceof OperatorActionRequiredError))
+                throw err;
+            log(`✖ ${dependency.label} NEEDS YOU: ${err.message}`);
+        }
+    }
+    // Shutdown is delegated to the loop, which owns the child handle: aborting makes it break out of
+    // its sleep, kill the child TREE, and reap the port. Reaping from here instead would kill the
+    // inner listener while leaving the package-manager wrapper and its parked `node --watch` alive.
+    const stopper = new AbortController();
+    const stop = () => {
+        if (stopper.signal.aborted)
+            return;
+        log('shutting down');
+        stopper.abort();
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    const outcome = await runSupervisor({
+        config,
+        probe,
+        launcher,
+        dependencies,
+        reaper,
+        log,
+        stopSignal: stopper.signal,
+    });
+    // A supervisor that stopped because the command is broken must not report success — a wrapper
+    // exiting 0 on a dead stack is the failure shape this whole command exists to make impossible.
+    if (outcome.gaveUp !== undefined)
+        process.exitCode = 1;
+}
+//# sourceMappingURL=superviseCommand.js.map

package/dist/superviseCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"superviseCommand.js","sourceRoot":"","sources":["../src/superviseCommand.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/cli",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "description": "Bootstrap CLI for the Agent Architecture Board: scaffold a local-mode deployment (Node/local backend + frontend SPA) on your own machine — generates the crypto secrets, populates and gitignores the .env files, and mints a GitHub/GitLab personal access token by opening the browser at the right pre-scoped URL.",
   "keywords": [
     "bootstrap",
@@ -41,8 +41,8 @@
     "typescript": "7.0.2",
     "valibot": "^1.4.2",
     "vitest": "^4.1.10",
-    "@cat-factory/contracts": "0.168.0",
-    "@cat-factory/kernel": "0.163.0"
+    "@cat-factory/contracts": "0.197.0",
+    "@cat-factory/kernel": "0.194.0"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json",
@@ -50,6 +50,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest",
     "test:run": "vitest run",
-    "test:integration": "vitest run --config vitest.integration.config.ts"
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:supervise": "vitest run --config vitest.supervise.config.ts"
   }
 }