@serfab/cadre-host 0.7.1

package/dist/orchestrator/log-rotator.js

@@ -0,0 +1,56 @@
+import { existsSync, renameSync, unlinkSync, } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * On-disk log rotation helper.
+ *
+ * Children spawned by the orchestrator inherit a direct file descriptor to
+ * their `node.log` (see `host-process-orchestrator.ts`), so rotation can no
+ * longer be driven by an in-process byte counter — renaming the path under a
+ * running child would leave it writing to the renamed inode. Instead the
+ * orchestrator calls `rotateOnDisk(...)` at spawn time, before the child is
+ * launched and its fd is opened. This is the only safe point to rotate
+ * without coordinating with the running process.
+ *
+ * Within a workdir there is at most one live child, so spawn-time rotation
+ * is sufficient for v1: a child that exceeds `logMaxBytes` mid-run will
+ * keep appending to the active file until it (or its successor) is restarted.
+ */
+/**
+ * Perform a rotation cascade against on-disk paths: drop the oldest, then
+ * shift `.N-1 → .N`, …, `.1 → .2`, and finally `filePath → .1`.
+ *
+ * Caller is responsible for deciding when to rotate (e.g. when
+ * `statSync(filePath).size >= logMaxBytes`). No fd is held by this helper.
+ */
+export function rotateOnDisk(filePath, maxFiles) {
+    if (maxFiles < 1)
+        return;
+    const oldest = `${filePath}.${maxFiles}`;
+    if (existsSync(oldest)) {
+        try {
+            unlinkSync(oldest);
+        }
+        catch { /* ignore */ }
+    }
+    for (let i = maxFiles - 1; i >= 1; i--) {
+        const from = `${filePath}.${i}`;
+        const to = `${filePath}.${i + 1}`;
+        if (existsSync(from)) {
+            try {
+                renameSync(from, to);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    if (existsSync(filePath)) {
+        try {
+            renameSync(filePath, `${filePath}.1`);
+        }
+        catch { /* ignore */ }
+    }
+}
+/** Build the standard log file path for a workdir. */
+export function defaultLogPath(workdir) {
+    return join(workdir, 'node.log');
+}
+//# sourceMappingURL=log-rotator.js.map

package/dist/orchestrator/log-rotator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-rotator.js","sourceRoot":"","sources":["../../src/orchestrator/log-rotator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,UAAU,EACV,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,QAAgB;IAC7D,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO;IAEzB,MAAM,MAAM,GAAG,GAAG,QAAQ,IAAI,QAAQ,EAAE,CAAC;IACzC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC;YAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IACpD,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,GAAG,QAAQ,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,EAAE,GAAG,GAAG,QAAQ,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC;gBAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,IAAI,CAAC;YAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,QAAQ,IAAI,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACnC,CAAC"}

package/dist/orchestrator/pid-liveness.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Cross-platform PID liveness check using only stdlib.
+ *
+ * `process.kill(pid, 0)` sends signal 0, which performs error checking
+ * without actually delivering a signal:
+ *   - returns successfully when the process exists and we have permission
+ *   - throws EPERM when the process exists but is owned by another user
+ *     (common on Windows where signals don't translate cleanly)
+ *   - throws ESRCH when the process does not exist
+ */
+export declare function isPidAlive(pid: number): boolean;

package/dist/orchestrator/pid-liveness.js

@@ -0,0 +1,26 @@
+/**
+ * Cross-platform PID liveness check using only stdlib.
+ *
+ * `process.kill(pid, 0)` sends signal 0, which performs error checking
+ * without actually delivering a signal:
+ *   - returns successfully when the process exists and we have permission
+ *   - throws EPERM when the process exists but is owned by another user
+ *     (common on Windows where signals don't translate cleanly)
+ *   - throws ESRCH when the process does not exist
+ */
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        // EPERM means the process exists but we lack permission to signal it.
+        // That's still "alive" from a liveness perspective.
+        return code === 'EPERM';
+    }
+}
+//# sourceMappingURL=pid-liveness.js.map

package/dist/orchestrator/pid-liveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid-liveness.js","sourceRoot":"","sources":["../../src/orchestrator/pid-liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,sEAAsE;QACtE,oDAAoD;QACpD,OAAO,IAAI,KAAK,OAAO,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/orchestrator/port-allocator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Range-based port tracker. Allocations are in-memory; on orchestrator
+ * restart the caller rehydrates the used-set from persisted state via
+ * `markUsed(port)` before serving new allocations.
+ */
+export declare class PortAllocator {
+    private readonly start;
+    private readonly end;
+    private readonly usedPorts;
+    constructor(start: number, end: number);
+    allocate(): number;
+    release(port: number): void;
+    /** Used during restart rehydration to reserve ports already in use. */
+    markUsed(port: number): void;
+    has(port: number): boolean;
+}

package/dist/orchestrator/port-allocator.js

@@ -0,0 +1,38 @@
+/**
+ * Range-based port tracker. Allocations are in-memory; on orchestrator
+ * restart the caller rehydrates the used-set from persisted state via
+ * `markUsed(port)` before serving new allocations.
+ */
+export class PortAllocator {
+    constructor(start, end) {
+        this.start = start;
+        this.end = end;
+        this.usedPorts = new Set();
+        if (!Number.isInteger(start) || !Number.isInteger(end) || start <= 0 || end < start) {
+            throw new Error(`Invalid port range: ${start}..${end}`);
+        }
+    }
+    allocate() {
+        for (let port = this.start; port <= this.end; port++) {
+            if (!this.usedPorts.has(port)) {
+                this.usedPorts.add(port);
+                return port;
+            }
+        }
+        throw new Error(`No available ports in range ${this.start}..${this.end}`);
+    }
+    release(port) {
+        this.usedPorts.delete(port);
+    }
+    /** Used during restart rehydration to reserve ports already in use. */
+    markUsed(port) {
+        if (port < this.start || port > this.end) {
+            return;
+        }
+        this.usedPorts.add(port);
+    }
+    has(port) {
+        return this.usedPorts.has(port);
+    }
+}
+//# sourceMappingURL=port-allocator.js.map

package/dist/orchestrator/port-allocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-allocator.js","sourceRoot":"","sources":["../../src/orchestrator/port-allocator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,aAAa;IAGxB,YACmB,KAAa,EACb,GAAW;QADX,UAAK,GAAL,KAAK,CAAQ;QACb,QAAG,GAAH,GAAG,CAAQ;QAJb,cAAS,GAAG,IAAI,GAAG,EAAU,CAAC;QAM7C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;YACpF,MAAM,IAAI,KAAK,CAAC,uBAAuB,KAAK,KAAK,GAAG,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,QAAQ;QACN,KAAK,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;YACrD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACzB,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,uEAAuE;IACvE,QAAQ,CAAC,IAAY;QACnB,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzC,OAAO;QACT,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/orchestrator/state-store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Persisted record for a single managed child. The orchestrator mirrors its
+ * in-memory map to disk so that cadre-host can re-attach to surviving
+ * children after a restart.
+ */
+export interface PersistedHandle {
+    containerId: string;
+    dockerId: string;
+    pid: number;
+    startupToken: string;
+    workdir: string;
+    ports: {
+        health: number;
+        metrics: number;
+        p2p: number;
+    };
+    spawnedAt: string;
+    partyId: string;
+    profile: 'storage' | 'transaction';
+}
+export interface PersistedState {
+    version: 1;
+    handles: PersistedHandle[];
+}
+/** JSON state file at `<rootDir>/state.json`, written atomically. */
+export declare class StateStore {
+    private readonly path;
+    constructor(rootDir: string);
+    load(): PersistedState;
+    save(state: PersistedState): void;
+    filePath(): string;
+}

package/dist/orchestrator/state-store.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync, renameSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import debug from 'debug';
+const log = debug('cadre:host:state-store');
+const STATE_VERSION = 1;
+/** JSON state file at `<rootDir>/state.json`, written atomically. */
+export class StateStore {
+    constructor(rootDir) {
+        mkdirSync(rootDir, { recursive: true });
+        this.path = join(rootDir, 'state.json');
+    }
+    load() {
+        if (!existsSync(this.path)) {
+            return { version: STATE_VERSION, handles: [] };
+        }
+        try {
+            const raw = readFileSync(this.path, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.handles)) {
+                log('state file at %s has unexpected shape; treating as empty', this.path);
+                return { version: STATE_VERSION, handles: [] };
+            }
+            return { version: STATE_VERSION, handles: parsed.handles };
+        }
+        catch (err) {
+            // A corrupt state file is operationally significant — surviving children
+            // may now be leaked to the OS without an in-memory handle. Make the
+            // failure visible rather than silently returning empty.
+            log('failed to load state file at %s: %o', this.path, err);
+            return { version: STATE_VERSION, handles: [] };
+        }
+    }
+    save(state) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        const payload = JSON.stringify({ version: STATE_VERSION, handles: state.handles }, null, 2);
+        const tmp = `${this.path}.tmp`;
+        writeFileSync(tmp, payload, { encoding: 'utf8' });
+        renameSync(tmp, this.path);
+    }
+    filePath() {
+        return this.path;
+    }
+}
+//# sourceMappingURL=state-store.js.map

package/dist/orchestrator/state-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.js","sourceRoot":"","sources":["../../src/orchestrator/state-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,GAAG,GAAG,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAwB5C,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,qEAAqE;AACrE,MAAM,OAAO,UAAU;IAGrB,YAAY,OAAe;QACzB,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI;QACF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACjD,CAAC;QACD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;YACjD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC5E,GAAG,CAAC,0DAA0D,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC3E,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;YACjD,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QAC7D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,yEAAyE;YACzE,oEAAoE;YACpE,wDAAwD;YACxD,GAAG,CAAC,qCAAqC,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC3D,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACjD,CAAC;IACH,CAAC;IAED,IAAI,CAAC,KAAqB;QACxB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC5F,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,MAAM,CAAC;QAC/B,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAClD,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/orchestrator/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Public + internal types for the HostProcessOrchestrator.
+ */
+import type { ChildProcess } from 'node:child_process';
+/** User-facing configuration for `HostProcessOrchestrator`. */
+export interface HostProcessConfig {
+    /** Root directory under which per-container workdirs live. */
+    rootDir: string;
+    /** Port allocation range (default 10000..20000). */
+    portRange?: {
+        start: number;
+        end: number;
+    };
+    /** Default resource limits (memory only in v1). */
+    defaultResources?: {
+        memoryLimit?: string;
+    };
+    /** SIGTERM → SIGKILL grace period (default 10000 ms). */
+    stopTimeoutMs?: number;
+    /** Log rotation: bytes per file (default 10 MB). */
+    logMaxBytes?: number;
+    /** Log rotation: max rotated files (default 5). */
+    logMaxFiles?: number;
+    /**
+     * Test-only hook: override the child entrypoint. When set, the orchestrator
+     * spawns `node <entrypoint> ...` instead of resolving `@serfab/cadre-cli`.
+     */
+    spawn?: {
+        entrypoint?: string;
+    };
+}
+/** In-memory record per managed child. */
+export interface Handle {
+    containerId: string;
+    dockerId: string;
+    pid: number;
+    startupToken: string;
+    workdir: string;
+    ports: {
+        health: number;
+        metrics: number;
+        p2p: number;
+    };
+    spawnedAt: string;
+    partyId: string;
+    profile: 'storage' | 'transaction';
+    /** Live ChildProcess reference; absent after re-attach via init(). */
+    child?: ChildProcess;
+    /** Marked false when init() finds the PID dead or token mismatched. */
+    alive: boolean;
+}
+/** Public view of a managed node — surfaced to `/api/nodes` callers. */
+export interface ManagedNodeInfo {
+    /** Friendly container id passed at create time. */
+    id: string;
+    /** Opaque dockerId (`pid:token`) — pass to stop/getStats/getLogs. */
+    dockerId: string;
+    partyId: string;
+    profile: 'storage' | 'transaction';
+    /** Runtime state derived from `Handle.alive`. */
+    status: 'running' | 'stopped';
+    spawnedAt: string;
+    workdir: string;
+    ports: {
+        health: number;
+        metrics: number;
+        p2p: number;
+    };
+}
+/**
+ * Listener invoked when a managed node's lifecycle state changes
+ * (create, child exit, manual stop). Subscribe via
+ * `HostProcessOrchestrator.onStateChange`.
+ */
+export type NodeStateListener = (info: ManagedNodeInfo) => void;
+/**
+ * Encode an opaque handle that callers treat the same way they treat a
+ * Docker container hash. The shape is `<pid>:<token>`; tokens are hex
+ * generated from `crypto.randomBytes` so they never contain `:`.
+ */
+export declare function encodeDockerId(pid: number, token: string): string;
+export declare function decodeDockerId(id: string): {
+    pid: number;
+    token: string;
+};

package/dist/orchestrator/types.js

@@ -0,0 +1,31 @@
+/**
+ * Public + internal types for the HostProcessOrchestrator.
+ */
+const TOKEN_SEPARATOR = ':';
+/**
+ * Encode an opaque handle that callers treat the same way they treat a
+ * Docker container hash. The shape is `<pid>:<token>`; tokens are hex
+ * generated from `crypto.randomBytes` so they never contain `:`.
+ */
+export function encodeDockerId(pid, token) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        throw new Error(`Invalid pid for docker id: ${pid}`);
+    }
+    if (token.length === 0 || token.includes(TOKEN_SEPARATOR)) {
+        throw new Error(`Invalid token for docker id: ${JSON.stringify(token)}`);
+    }
+    return `${pid}${TOKEN_SEPARATOR}${token}`;
+}
+export function decodeDockerId(id) {
+    const idx = id.indexOf(TOKEN_SEPARATOR);
+    if (idx <= 0) {
+        throw new Error(`Malformed dockerId: ${id}`);
+    }
+    const pid = Number.parseInt(id.slice(0, idx), 10);
+    const token = id.slice(idx + 1);
+    if (!Number.isInteger(pid) || pid <= 0 || token.length === 0) {
+        throw new Error(`Malformed dockerId: ${id}`);
+    }
+    return { pid, token };
+}
+//# sourceMappingURL=types.js.map

package/dist/orchestrator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/orchestrator/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgEH,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,KAAa;IACvD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,GAAG,GAAG,eAAe,GAAG,KAAK,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AACxB,CAAC"}

package/dist/server/error-handler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Fastify error handler — translates known typed errors to stable HTTP status
+ * codes and uniform `{ ok: false, error: { code, message } }` payloads.
+ *
+ * Codes (cross-referenced with `auth/types.ts`, `nat/types.ts`, `update/types.ts`):
+ *   - TrustCircleError
+ *       invalid_label, invalid_token             → 400
+ *       not_found, already_redeemed              → 404
+ *       expired                                  → 410
+ *       storage_error                            → 500
+ *   - NatError
+ *       invalid_config, ddns_provider_unknown,
+ *       ddns_credentials_missing                 → 400
+ *       secrets_unavailable, storage_error,
+ *       mapping_failed, router_unreachable,
+ *       ip_detection_failed, ddns_update_failed  → 500
+ *   - UpdateErrorException
+ *       manifest_invalid, no_update_available,
+ *       min_previous_version                     → 400
+ *       apply_in_progress                        → 409
+ *       signature_invalid, unsupported_state_version,
+ *       apply_failed, rollback_failed, storage_error → 500
+ *   - everything else                            → 500 (code "internal")
+ */
+import type { FastifyInstance } from 'fastify';
+export declare function registerErrorHandler(app: FastifyInstance): void;

package/dist/server/error-handler.js

@@ -0,0 +1,95 @@
+/**
+ * Fastify error handler — translates known typed errors to stable HTTP status
+ * codes and uniform `{ ok: false, error: { code, message } }` payloads.
+ *
+ * Codes (cross-referenced with `auth/types.ts`, `nat/types.ts`, `update/types.ts`):
+ *   - TrustCircleError
+ *       invalid_label, invalid_token             → 400
+ *       not_found, already_redeemed              → 404
+ *       expired                                  → 410
+ *       storage_error                            → 500
+ *   - NatError
+ *       invalid_config, ddns_provider_unknown,
+ *       ddns_credentials_missing                 → 400
+ *       secrets_unavailable, storage_error,
+ *       mapping_failed, router_unreachable,
+ *       ip_detection_failed, ddns_update_failed  → 500
+ *   - UpdateErrorException
+ *       manifest_invalid, no_update_available,
+ *       min_previous_version                     → 400
+ *       apply_in_progress                        → 409
+ *       signature_invalid, unsupported_state_version,
+ *       apply_failed, rollback_failed, storage_error → 500
+ *   - everything else                            → 500 (code "internal")
+ */
+import debug from 'debug';
+import { TrustCircleError } from '../auth/types.js';
+import { NatError } from '../nat/types.js';
+import { UpdateErrorException } from '../update/types.js';
+const log = debug('cadre:host:error-handler');
+const TRUST_STATUS = {
+    invalid_label: 400,
+    invalid_token: 400,
+    not_found: 404,
+    already_redeemed: 404,
+    expired: 410,
+    storage_error: 500,
+};
+const NAT_STATUS = {
+    invalid_config: 400,
+    ddns_provider_unknown: 400,
+    ddns_credentials_missing: 400,
+    secrets_unavailable: 500,
+    storage_error: 500,
+    mapping_failed: 500,
+    router_unreachable: 500,
+    ip_detection_failed: 500,
+    ddns_update_failed: 500,
+};
+const UPDATE_STATUS = {
+    manifest_invalid: 400,
+    no_update_available: 400,
+    min_previous_version: 400,
+    apply_in_progress: 409,
+    signature_invalid: 500,
+    unsupported_state_version: 500,
+    apply_failed: 500,
+    rollback_failed: 500,
+    storage_error: 500,
+};
+export function registerErrorHandler(app) {
+    app.setErrorHandler((err, request, reply) => {
+        const { status, code, message } = classify(err);
+        if (status >= 500) {
+            log('5xx %s %s: [%s] %s', request.method, request.url, code, message);
+        }
+        else {
+            log('%d %s %s: [%s] %s', status, request.method, request.url, code, message);
+        }
+        return reply.code(status).send({
+            ok: false,
+            error: { code, message },
+        });
+    });
+}
+function classify(err) {
+    if (err instanceof TrustCircleError) {
+        return { status: TRUST_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+    }
+    if (err instanceof NatError) {
+        return { status: NAT_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+    }
+    if (err instanceof UpdateErrorException) {
+        return { status: UPDATE_STATUS[err.code] ?? 500, code: err.code, message: err.message };
+    }
+    // Fastify body-parsing / validation errors have a statusCode we should honour.
+    if (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600) {
+        return {
+            status: err.statusCode,
+            code: err.code ?? (err.statusCode === 404 ? 'not_found' : 'bad_request'),
+            message: err.message ?? 'request failed',
+        };
+    }
+    return { status: 500, code: 'internal', message: err.message || 'internal error' };
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/server/error-handler.js.map

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

package/dist/server/events/bus.d.ts

@@ -0,0 +1,17 @@
+/**
+ * In-memory event bus for the local UI.
+ *
+ * Tiny synchronous fan-out: publishers (route adapters, orchestrator hook,
+ * update observer) call `publish`; SSE connections subscribe and receive every
+ * event until they unsubscribe. Listener errors are caught so one broken
+ * client cannot break others.
+ */
+import type { LocalUiEvent } from './types.js';
+export type LocalUiEventListener = (event: LocalUiEvent) => void;
+export declare class EventBus {
+    private readonly listeners;
+    publish(event: LocalUiEvent): void;
+    subscribe(listener: LocalUiEventListener): () => void;
+    /** Test helper. */
+    listenerCount(): number;
+}

package/dist/server/events/bus.js

@@ -0,0 +1,36 @@
+/**
+ * In-memory event bus for the local UI.
+ *
+ * Tiny synchronous fan-out: publishers (route adapters, orchestrator hook,
+ * update observer) call `publish`; SSE connections subscribe and receive every
+ * event until they unsubscribe. Listener errors are caught so one broken
+ * client cannot break others.
+ */
+import debug from 'debug';
+const log = debug('cadre:host:event-bus');
+export class EventBus {
+    constructor() {
+        this.listeners = new Set();
+    }
+    publish(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                log('listener threw for event %s: %s', event.type, err.message);
+            }
+        }
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Test helper. */
+    listenerCount() {
+        return this.listeners.size;
+    }
+}
+//# sourceMappingURL=bus.js.map

package/dist/server/events/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../../../src/server/events/bus.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,MAAM,GAAG,GAAG,KAAK,CAAC,sBAAsB,CAAC,CAAC;AAI1C,MAAM,OAAO,QAAQ;IAArB;QACmB,cAAS,GAAG,IAAI,GAAG,EAAwB,CAAC;IAuB/D,CAAC;IArBC,OAAO,CAAC,KAAmB;QACzB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,GAAG,CAAC,iCAAiC,EAAE,KAAK,CAAC,IAAI,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;YAC7E,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,CAAC,QAA8B;QACtC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;IAED,mBAAmB;IACnB,aAAa;QACX,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;CACF"}

package/dist/server/events/sse-route.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Server-Sent Events route — `GET /api/events`.
+ *
+ * Hand-rolled (~40 lines vs. the 30 KB @fastify/sse-v2 dep). The wire format:
+ *
+ *   retry: 5000\n\n          ← reconnect hint
+ *   : heartbeat\n\n          ← comment line, every 15 s
+ *   event: <type>\n          ← event name
+ *   data: <json>\n\n         ← payload
+ *
+ * The handler subscribes to the bus on connect, unsubscribes on client
+ * disconnect, and ticks a heartbeat so corporate proxies don't close the
+ * connection at the idle timeout.
+ */
+import type { FastifyInstance } from 'fastify';
+import type { EventBus } from './bus.js';
+export interface SseRouteOptions {
+    events: EventBus;
+    /** Test override: shorter heartbeat. */
+    heartbeatIntervalMs?: number;
+}
+export declare function registerSseRoute(app: FastifyInstance, opts: SseRouteOptions): void;

package/dist/server/events/sse-route.js

@@ -0,0 +1,65 @@
+/**
+ * Server-Sent Events route — `GET /api/events`.
+ *
+ * Hand-rolled (~40 lines vs. the 30 KB @fastify/sse-v2 dep). The wire format:
+ *
+ *   retry: 5000\n\n          ← reconnect hint
+ *   : heartbeat\n\n          ← comment line, every 15 s
+ *   event: <type>\n          ← event name
+ *   data: <json>\n\n         ← payload
+ *
+ * The handler subscribes to the bus on connect, unsubscribes on client
+ * disconnect, and ticks a heartbeat so corporate proxies don't close the
+ * connection at the idle timeout.
+ */
+import debug from 'debug';
+const log = debug('cadre:host:sse');
+const HEARTBEAT_INTERVAL_MS = 15000;
+const RECONNECT_HINT_MS = 5000;
+export function registerSseRoute(app, opts) {
+    const heartbeatMs = opts.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+    app.get('/api/events', (request, reply) => {
+        // Tell Fastify we're handling the reply ourselves — it won't try to
+        // serialise or send a payload.
+        reply.hijack();
+        reply.raw.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache, no-transform',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        });
+        reply.raw.write(`retry: ${RECONNECT_HINT_MS}\n\n`);
+        reply.raw.write(`: connected\n\n`);
+        const onEvent = (event) => {
+            try {
+                reply.raw.write(`event: ${event.type}\n`);
+                reply.raw.write(`data: ${JSON.stringify(event)}\n\n`);
+            }
+            catch (err) {
+                log('write failed (client likely gone): %s', err.message);
+            }
+        };
+        const unsubscribe = opts.events.subscribe(onEvent);
+        const heartbeat = setInterval(() => {
+            try {
+                reply.raw.write(`: heartbeat\n\n`);
+            }
+            catch (err) {
+                log('heartbeat write failed: %s', err.message);
+            }
+        }, heartbeatMs);
+        // Don't hold the event loop open for the heartbeat alone.
+        if (typeof heartbeat === 'object' && 'unref' in heartbeat) {
+            heartbeat.unref?.();
+        }
+        const cleanup = () => {
+            clearInterval(heartbeat);
+            unsubscribe();
+        };
+        request.raw.on('close', cleanup);
+        request.raw.on('error', cleanup);
+        // The reply object is intentionally not returned — Fastify must not
+        // attempt to serialise an SSE response.
+    });
+}
+//# sourceMappingURL=sse-route.js.map

package/dist/server/events/sse-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-route.js","sourceRoot":"","sources":["../../../src/server/events/sse-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,MAAM,GAAG,GAAG,KAAK,CAAC,gBAAgB,CAAC,CAAC;AAEpC,MAAM,qBAAqB,GAAG,KAAM,CAAC;AACrC,MAAM,iBAAiB,GAAG,IAAK,CAAC;AAQhC,MAAM,UAAU,gBAAgB,CAAC,GAAoB,EAAE,IAAqB;IAC1E,MAAM,WAAW,GAAG,IAAI,CAAC,mBAAmB,IAAI,qBAAqB,CAAC;IAEtE,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,OAAuB,EAAE,KAAmB,EAAE,EAAE;QACtE,oEAAoE;QACpE,+BAA+B;QAC/B,KAAK,CAAC,MAAM,EAAE,CAAC;QACf,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;YACvB,cAAc,EAAE,mBAAmB;YACnC,eAAe,EAAE,wBAAwB;YACzC,UAAU,EAAE,YAAY;YACxB,mBAAmB,EAAE,IAAI;SAC1B,CAAC,CAAC;QACH,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,iBAAiB,MAAM,CAAC,CAAC;QACnD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QAEnC,MAAM,OAAO,GAAG,CAAC,KAAmB,EAAQ,EAAE;YAC5C,IAAI,CAAC;gBACH,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;gBAC1C,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACxD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,GAAG,CAAC,uCAAuC,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;YACvE,CAAC;QACH,CAAC,CAAC;QACF,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAEnD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;YACjC,IAAI,CAAC;gBACH,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,GAAG,CAAC,4BAA4B,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC,EAAE,WAAW,CAAC,CAAC;QAChB,0DAA0D;QAC1D,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,OAAO,IAAI,SAAS,EAAE,CAAC;YACzD,SAAoC,CAAC,KAAK,EAAE,EAAE,CAAC;QAClD,CAAC;QAED,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,aAAa,CAAC,SAAS,CAAC,CAAC;YACzB,WAAW,EAAE,CAAC;QAChB,CAAC,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAEjC,oEAAoE;QACpE,wCAAwC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC"}