@north-light/crouter 0.3.318 → 0.3.320

package/dist/core/__tests__/helpers/broker-clients.js

@@ -1,174 +0,0 @@
-// helpers/broker-clients.ts — the shared attach-client kit for the broker
-// lifecycle/attach-gate suite (plan T8/T11). Extracted VERBATIM from the original
-// single-file broker-lifecycle.test.ts when it was split into per-area files so
-// node:test's file-level parallelism applies (each file holds its own isolated
-// harness); the helpers are unchanged in behavior.
-//
-// The kit wraps the PRODUCTION attach client (pure node:net + the broker codec,
-// no TUI) as the in-test controller/observer so the G1–G9 gate exercises the REAL
-// client too (§0 one-writer: a viewer holds ONLY a socket), plus a raw node:net
-// peer for the cases where the client lifecycle is awkward (G7 oversized line,
-// G8 stalled viewer).
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { createConnection } from 'node:net';
-import { BrokerClient } from '../../broker-client/index.js';
-import { CLIENT_READ_CAPS, FrameDecoder, encodeFrame, } from '../../runtime/broker-protocol.js';
-export const delay = (ms) => new Promise((r) => setTimeout(r, ms));
-export const tok = (s) => `${s}-${Math.random().toString(36).slice(2, 8)}`;
-export const frameHas = (f, token) => JSON.stringify(f).includes(token);
-// Reads the canonical event log (job/log.jsonl) — the sole write path for
-// broker.runtime.diagnostic events (e.g. viewer-drop reasons) since the
-// logging hard cut. job/broker.log is raw stdout/stderr residue only and no
-// longer carries these reasons; do not fall back to it.
-export function brokerLogText(h, id) {
-    try {
-        return readFileSync(join(h.home, 'nodes', id, 'job', 'log.jsonl'), 'utf8');
-    }
-    catch {
-        return '';
-    }
-}
-/** Build the attach kit against a lazily-resolved harness (the harness is
- *  created in the file's before() hook, after the kit is constructed). */
-export function createAttachKit(getH) {
-    const liveClients = [];
-    // Connect a BrokerClient to a node's running broker, hello, await welcome.
-    // awaitBoot returns once the boot proof is written — which is BEFORE the broker's
-    // server.listen() binds view.sock — so a fresh attach can momentarily race the
-    // bind; retry the connect on BrokerUnavailable until it is listening.
-    async function attach(id, role, clientId, opts = {}) {
-        const h = getH();
-        await h.waitFor(() => existsSync(h.brokerSock(id)), { label: `view.sock for ${id}`, timeoutMs: 20_000 });
-        const frames = [];
-        let client;
-        for (let attempt = 0;; attempt++) {
-            client = new BrokerClient(id);
-            client.on('frame', (f) => frames.push(f));
-            try {
-                await new Promise((resolve, reject) => {
-                    client.once('connect', resolve);
-                    client.once('error', reject);
-                    client.connect();
-                });
-                break;
-            }
-            catch (err) {
-                client.close();
-                if (attempt >= 30)
-                    throw err;
-                await delay(100);
-            }
-        }
-        client.on('error', () => { }); // post-connect error sink (never throw uncaught)
-        // Register cleanup the instant the socket is connected — BEFORE the hello/welcome
-        // round-trip — so a welcome timeout cannot leak a connected socket past the test.
-        liveClients.push({ close: () => client.close() });
-        const waitFrame = (pred, label, timeoutMs = 15_000) => h.waitFor(() => frames.find(pred) ?? null, { label, timeoutMs });
-        client.send({
-            type: 'hello',
-            role,
-            client_id: clientId,
-            ...(opts.snapshotTail === undefined ? {} : { snapshot_tail: opts.snapshotTail }),
-            ...(opts.attends === undefined ? {} : { attends: opts.attends }),
-        });
-        let welcome;
-        try {
-            welcome = (await waitFrame((f) => f.type === 'welcome', `welcome for ${clientId}`));
-        }
-        catch (err) {
-            client.close();
-            throw err;
-        }
-        return { client, frames, welcome, send: (f) => client.send(f), waitFrame, close: () => client.close() };
-    }
-    // Attach (as `role`) and retry until the welcome satisfies `pred` — used where the
-    // observable lands a beat after a prior action, such as snapshot accrual or
-    // persisted presence after a socket closes. Deterministic: it polls an observable.
-    async function attachUntil(id, role, clientId, pred, label) {
-        for (let attempt = 0;; attempt++) {
-            const a = await attach(id, role, `${clientId}-${attempt}`);
-            if (pred(a))
-                return a;
-            a.close();
-            if (attempt >= 40)
-                throw new Error(`attachUntil timed out: ${label}`);
-            await delay(150);
-        }
-    }
-    // A raw node:net peer. read:true decodes incoming frames; read:false leaves the
-    // socket PAUSED (no 'data' listener, never resumed) so it never drains — the
-    // stalled viewer (G8) whose backlog the broker must shed at the HWM.
-    async function connectRaw(id, opts) {
-        const h = getH();
-        await h.waitFor(() => existsSync(h.brokerSock(id)), { label: `view.sock for ${id}`, timeoutMs: 20_000 });
-        const frames = [];
-        const decoder = new FrameDecoder(CLIENT_READ_CAPS);
-        let isClosed = false;
-        const socket = await new Promise((resolve, reject) => {
-            const s = createConnection(h.brokerSock(id));
-            s.once('connect', () => resolve(s));
-            s.once('error', reject);
-        });
-        socket.on('close', () => {
-            isClosed = true;
-        });
-        socket.on('error', () => {
-            /* close follows */
-        });
-        if (opts.read) {
-            socket.on('data', (chunk) => {
-                try {
-                    for (const f of decoder.push(chunk))
-                        frames.push(f);
-                }
-                catch {
-                    /* a client-side overflow is irrelevant here */
-                }
-            });
-        }
-        const rc = {
-            socket,
-            frames,
-            closed: () => isClosed,
-            send: (f) => {
-                try {
-                    socket.write(encodeFrame(f));
-                }
-                catch {
-                    /* dead */
-                }
-            },
-            writeRaw: (d) => {
-                try {
-                    socket.write(d);
-                }
-                catch {
-                    /* dead */
-                }
-            },
-            waitClosed: (label, timeoutMs = 15_000) => h.waitFor(() => (isClosed ? true : null), { label, timeoutMs }).then(() => undefined),
-            close: () => {
-                try {
-                    socket.destroy();
-                }
-                catch {
-                    /* ignore */
-                }
-            },
-        };
-        liveClients.push(rc);
-        return rc;
-    }
-    function closeAll() {
-        for (const c of liveClients.splice(0)) {
-            try {
-                c.close();
-            }
-            catch {
-                /* already gone */
-            }
-        }
-    }
-    return { attach, attachUntil, connectRaw, closeAll };
-}

package/dist/core/__tests__/helpers/fleet.d.ts

@@ -1,12 +0,0 @@
-import { DaemonFleet, type DaemonFleetOpts } from '../../../daemon/fleet.js';
-export interface TestFleet {
-    fleet: DaemonFleet;
-    /** Await lane quiescence: every job enqueued so far (including jobs those
-     *  jobs enqueued) has settled. */
-    drain(): Promise<void>;
-}
-/** Construct a DaemonFleet on a private serial lane and bind it as THIS
- *  process's fleet. Call in `before`/`beforeEach`; `bindFleet` throws on a
- *  conflicting rebind, so the previous binding is reset first (same idiom as
- *  resetEventSourceForTests). Pass `now` to inject the throttle clock. */
-export declare function bindTestFleet(opts?: Partial<Pick<DaemonFleetOpts, 'epoch' | 'now' | 'probeOnline'>>): TestFleet;

package/dist/core/__tests__/helpers/fleet.js

@@ -1,50 +0,0 @@
-// helpers/fleet.ts — an in-process fleet binding for direct-tier tests.
-//
-// Post-cutover, every broker launch resolves `boundFleet()` (host.ts) and
-// `superviseTick`'s first line is `boundFleet()` — an unbound process throws by
-// design (D-2: launches happen only inside crtrd, or a test harness that
-// explicitly bound a fleet). Any test that calls reviveNode/spawnChild/
-// superviseTick in-process must bind one of these first.
-//
-// The binding is a REAL DaemonFleet on a private serial lane, mirroring the
-// daemon's own construction (crtrd.ts runDaemon): registration, the fleet.has
-// revive guard, exit-policy jobs, and the respawn throttle all behave exactly
-// as in production — only the lane is local so a test can `drain()` it to a
-// deterministic quiescent point instead of racing timers.
-import { DaemonFleet } from '../../../daemon/fleet.js';
-import { bindFleet, resetFleetForTests } from '../../runtime/fleet.js';
-/** Construct a DaemonFleet on a private serial lane and bind it as THIS
- *  process's fleet. Call in `before`/`beforeEach`; `bindFleet` throws on a
- *  conflicting rebind, so the previous binding is reset first (same idiom as
- *  resetEventSourceForTests). Pass `now` to inject the throttle clock. */
-export function bindTestFleet(opts = {}) {
-    resetFleetForTests();
-    let lane = Promise.resolve();
-    const fleet = new DaemonFleet({
-        epoch: opts.epoch ?? 'test-epoch',
-        enqueue: (job) => {
-            lane = lane.then(() => job()).then(() => { }, (err) => {
-                // Policy jobs contain their own error handling; anything escaping is
-                // a genuine bug — surface it, never wedge the lane.
-                console.error('[test-fleet] lane job failed:', err);
-            });
-        },
-        ...(opts.now !== undefined ? { now: opts.now } : {}),
-        // Respawn policy consults network reachability — an offline box parks a
-        // node rather than spending its respawn budget. Default it online so tests
-        // stay deterministic off the network; pass `probeOnline` to drive the
-        // outage branch.
-        probeOnline: opts.probeOnline ?? (async () => true),
-    });
-    bindFleet(fleet);
-    return {
-        fleet,
-        async drain() {
-            let tail;
-            do {
-                tail = lane;
-                await tail;
-            } while (tail !== lane);
-        },
-    };
-}

package/dist/core/__tests__/helpers/harness.d.ts

@@ -1,124 +0,0 @@
-import { DaemonFleet } from '../../../daemon/fleet.js';
-import { type FleetExitStatus } from '../../runtime/fleet.js';
-import type { NodeMeta, NodeStatus, Mode, Lifecycle, ExitIntent } from '../../canvas/types.js';
-import type { InboxEntry } from '../../feed/inbox.js';
-export declare const TMUX_TIMEOUT_MS = 10000;
-/** True when a usable tmux is on PATH — tests gate on this and SKIP otherwise. */
-export declare function hasTmux(): boolean;
-export interface WaitOpts {
-    timeoutMs?: number;
-    intervalMs?: number;
-    label?: string;
-}
-export declare function readLines(path: string): string[];
-export interface Injected {
-    content: string;
-    deliverAs?: string;
-}
-export interface BootProof {
-    pid: number;
-    nodeId: string;
-    resuming: boolean;
-    prompt: string | null;
-    extPaths: string[];
-    loaded: string[];
-    failedExt: string[];
-    env: Record<string, string | null>;
-    [k: string]: unknown;
-}
-export interface CliResult {
-    code: number;
-    stdout: string;
-    stderr: string;
-    json?: unknown;
-}
-export interface HarnessOpts {
-    sessionPrefix?: string;
-    /** HEADLESS mode: drive ONLY broker-hosted (paneless) nodes. When set the
-     *  harness does NOT gate on tmux, does NOT eagerly create the isolated tmux
-     *  session, and skips the per-pane `set-environment` seeding — nothing in a
-     *  headless run opens a window. CRTR_NODE_SESSION/CRTR_ROOT_SESSION are still
-     *  scrubbed/restored for env hygiene, but do not route placement: a managed
-     *  child opens NO viewer (it boots a detached broker, supervised by pid), and a
-     *  --root opens one viewer in the caller's current session. Headless tests must
-     *  use `spawnHeadlessChild`, never `spawnChild`. See createHeadlessHarness(). */
-    headless?: boolean;
-}
-export interface SpawnOpts {
-    kind?: string;
-    mode?: Mode;
-    lifecycle?: Lifecycle;
-    model?: string;
-    profile?: string | null;
-    id?: string;
-}
-/** Fabricate a broker-hosted node row directly — tmux-free, boot-free, NO
- *  subprocess. Builds a full NodeMeta (identity ∪ runtime) and calls createNode,
- *  which seeds BOTH halves in one statement (seedRow writes status/intent/pi_pid
- *  from the meta; writeMeta persists pi_session_id). The result is a row the
- *  daemon supervises by pid exactly as if a real broker had booted — so a test
- *  can drive superviseTick(now) liveness decisions against arbitrary liveness
- *  state (alive/dead pid, with/without session, any intent) with ZERO real boot.
- *  See foundation-spec §E.2. */
-export interface FabricateOpts {
-    parent?: string | null;
-    kind?: string;
-    mode?: Mode;
-    lifecycle?: Lifecycle;
-    status?: NodeStatus;
-    intent?: ExitIntent;
-    pi_pid?: number | null;
-    pi_session_id?: string | null;
-    pi_session_file?: string | null;
-    id?: string;
-}
-export interface Harness {
-    home: string;
-    /** Isolated HOME inherited by fake broker processes (provider state lives here). */
-    agentHome: string;
-    session: string;
-    spawnRoot(task: string, o?: SpawnOpts): string;
-    fabricateBrokerNode(o?: FabricateOpts): string;
-    cli(nodeId: string | null, args: string[]): CliResult;
-    spawnHeadlessChild(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
-    stop(nodeId: string, reason?: 'stop' | 'length' | 'aborted' | 'error', errorMessage?: string): Promise<void>;
-    tick(now?: number): Promise<void>;
-    fleet: DaemonFleet;
-    deliverExit(nodeId: string, status?: FleetExitStatus): Promise<void>;
-    awaitFleetExit(nodeId: string, timeoutMs?: number): Promise<void>;
-    awaitBoot(nodeId: string, o?: {
-        minCount?: number;
-        timeoutMs?: number;
-    }): Promise<BootProof>;
-    awaitWake(nodeId: string, o?: {
-        sinceCount?: number;
-        timeoutMs?: number;
-        match?: RegExp;
-    }): Promise<string[]>;
-    waitFor<T>(probe: () => T | undefined | null | false, o?: WaitOpts): Promise<T>;
-    node(nodeId: string): NodeMeta | null;
-    status(nodeId: string): NodeStatus | null;
-    inbox(nodeId: string): InboxEntry[];
-    injected(nodeId: string): Injected[];
-    fakeCmd(nodeId: string, cmd: Record<string, unknown>): void;
-    /** Stop only this harness's API server to exercise a broker daemon-read failure. */
-    stopApiServer(): Promise<void>;
-    dialogResults(nodeId: string): {
-        resolved: unknown;
-        ms: number;
-    }[];
-    brokerSock(nodeId: string): string;
-    bootCount(nodeId: string): number;
-    subscribers(nodeId: string): {
-        node_id: string;
-        active: boolean;
-    }[];
-    subscriptions(nodeId: string): {
-        node_id: string;
-        active: boolean;
-    }[];
-    dispose(): Promise<void>;
-}
-/** Thin wrapper: a headless-only harness (broker-hosted, paneless nodes). */
-export declare function createHeadlessHarness(opts?: HarnessOpts): Promise<Harness>;
-export declare function createHarness(opts?: HarnessOpts): Promise<Harness>;