@stateforge-labs/herdr 0.0.0-stage → 0.3.0

package/dist/core/test-kit/constants.js

@@ -0,0 +1,43 @@
+// Role: every string and number of the fake herdr-core: its file names, recorded-frame names, fault kinds and codes, messages and demo terminals.
+// Informs HERDR-ADR-0020 (the fake core) and HERDR-ADR-0021 (strings centralized). Shipped only in ./core/test-kit.
+export const FakeName = { DirPrefix: 'herdr-core-fake-', Socket: 'default.sock' };
+// The JSON-RPC fault kinds and codes the fake answers with.
+export const FakeFaultKind = { MethodNotFound: 'method_not_found', NotFound: 'not_found' };
+export const FakeRpcCode = { MethodNotFound: -32601, NotFound: -32000 };
+// The names of the recorded frames in frames.ts.
+export const FrameName = {
+    Hello: 'hello',
+    Subscribed: 'subscribed',
+    Created: 'event:created',
+    eventOf: (type) => `event:${type}`,
+};
+// Fields of a terminal and of the fake's replies that the core client does not read itself.
+export const FakeField = {
+    Address: 'address',
+    HiddenFinished: 'hidden_finished',
+    Channel: 'channel',
+};
+export const FakeText = {
+    NoFrame: (name) => `no scripted frame ${name}`,
+    NoMethod: (method) => `no method ${method}`,
+    NoTerminal: (address) => `no terminal "${String(address)}"`,
+    Screen: (terminal) => `screen of ${String(terminal)}`,
+};
+export const FakeScreen = { How: 'screen' };
+// Replies split in two halves: the first SPLIT_AT characters, then the rest after SPLIT_DELAY ms.
+export const SPLIT_AT = 7;
+export const SPLIT_DELAY = 15;
+// The two demo terminals every fake starts with.
+export const DemoTerminal = {
+    First: 't1',
+    Second: 't2',
+    Working: 'working',
+    Idle: 'idle',
+    Live: 'live',
+    App: 'claude-code',
+    Argv: ['claude'],
+    Cwd: '~/work/probe',
+    Name: 'claude',
+    Pid: 4242,
+    Labels: { 'herdr.tab': 'tb1', 'herdr.space': 'sp1', where: 'S / 1' },
+};

package/dist/core/test-kit/fake-core.d.ts

@@ -0,0 +1,61 @@
+import type { SocketPath } from '../wire.js';
+type Fields = Record<string, unknown>;
+export type Handler = (params: Fields) => unknown;
+export declare class FakeFault {
+    readonly code: number;
+    readonly kind: string;
+    readonly message: string;
+    constructor(code: number, kind: string, message: string);
+}
+export interface Seen {
+    readonly method: string;
+    readonly params: Fields;
+    readonly connection: number;
+}
+export declare function frame(name: string): Fields;
+export declare const agentTerminal: (address: string, state: string, labels?: Fields) => Fields;
+export declare const shellTerminal: (address: string) => Fields;
+export declare class FakeHcCore {
+    connections: number;
+    silent: boolean;
+    splitReplies: boolean;
+    seq: number;
+    terminals: Fields[];
+    readonly seen: Seen[];
+    private readonly handlers;
+    private readonly delays;
+    private readonly sockets;
+    private readonly subscribers;
+    private readonly timers;
+    private server;
+    private helloResult;
+    private readonly dir;
+    readonly path: SocketPath;
+    private constructor();
+    static start(): Promise<FakeHcCore>;
+    static unlistened(): FakeHcCore;
+    get open(): number;
+    get subscribed(): number;
+    on(method: string, handler: Handler): void;
+    delay(method: string, ms: number): void;
+    hello(patch: Fields): void;
+    up(): Promise<void>;
+    down(): Promise<void>;
+    dropAll(): void;
+    event(type: string, terminal: string | null, data?: Fields): number;
+    heartbeat(): void;
+    missed(terminals: Fields[]): void;
+    raw(text: string): void;
+    stop(): Promise<void>;
+    private send;
+    private accept;
+    private handle;
+    private reply;
+    private outcome;
+    private resultOf;
+    private readonly served;
+    private getOf;
+}
+export declare function nextWithin<T>(iterator: AsyncIterator<T>, ms: number): Promise<T | null>;
+export declare const later: (ms: number) => Promise<void>;
+export {};

package/dist/core/test-kit/fake-core.js

@@ -0,0 +1,228 @@
+// Role: FakeHcCore, a scripted herdr-core on a temporary unix socket: hello, terminal.list/get/read, events with heartbeats, missed, drops and slow or silent replies.
+// Informs HERDR-ADR-0020 (the herdr-core client); ported from the desktop work in herdr-plugins.
+import { createServer } from 'node:net';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { RECORDED_FRAMES } from './frames.js';
+import { brand, isString } from '../kernel.js';
+import { EMPTY_TEXT, HC_GET_METHOD, HC_HELLO_METHOD, HC_JSONRPC_VERSION, HC_LINE_SEPARATOR, HC_LIST_METHOD, HC_READ_METHOD, HC_SUBSCRIBE_METHOD, HcField, HcNotificationMethod, JsType, SocketEvent, UTF8 } from '../constants.js';
+import { DemoTerminal, FakeFaultKind, FakeField, FakeName, FakeRpcCode, FakeScreen, FakeText, FrameName, SPLIT_AT, SPLIT_DELAY } from './constants.js';
+export class FakeFault {
+    code;
+    kind;
+    message;
+    constructor(code, kind, message) {
+        this.code = code;
+        this.kind = kind;
+        this.message = message;
+    }
+}
+const isFields = (input) => typeof input === JsType.Object && input !== null && !Array.isArray(input);
+const loaded = RECORDED_FRAMES;
+export function frame(name) {
+    const found = isFields(loaded) ? loaded[name] : undefined;
+    if (!isFields(found)) {
+        throw new FakeFault(FakeRpcCode.NotFound, FakeFaultKind.NotFound, FakeText.NoFrame(name));
+    }
+    return found;
+}
+const section = (source, key) => {
+    const found = source[key];
+    return isFields(found) ? found : {};
+};
+const listOf = (source, key) => {
+    const found = source[key];
+    return Array.isArray(found) ? found : [];
+};
+const dataOf = (name) => section(section(frame(name), HcField.Params), HcField.Data);
+export const agentTerminal = (address, state, labels = DemoTerminal.Labels) => ({
+    ...dataOf(FrameName.Created), address, labels, state: DemoTerminal.Live, status: { app: DemoTerminal.App, state }, foreground: { argv: [...DemoTerminal.Argv], cwd: DemoTerminal.Cwd, name: DemoTerminal.Name, pid: DemoTerminal.Pid },
+});
+export const shellTerminal = (address) => {
+    const first = listOf(section(frame(FrameName.Subscribed), HcField.Result), HcField.Terminals)[0];
+    return { ...(isFields(first) ? first : {}), address };
+};
+export class FakeHcCore {
+    connections = 0;
+    silent = false;
+    splitReplies = false;
+    seq = 100;
+    terminals = [];
+    seen = [];
+    handlers = new Map();
+    delays = new Map();
+    sockets = new Set();
+    subscribers = new Set();
+    timers = new Set();
+    server = null;
+    helloResult = section(frame(FrameName.Hello), HcField.Result);
+    dir;
+    path;
+    constructor(dir, path) {
+        this.dir = dir;
+        this.path = path;
+        this.terminals = [agentTerminal(DemoTerminal.First, DemoTerminal.Working), agentTerminal(DemoTerminal.Second, DemoTerminal.Idle)];
+    }
+    static async start() {
+        const dir = mkdtempSync(join(tmpdir(), FakeName.DirPrefix));
+        const core = new FakeHcCore(dir, brand(join(dir, FakeName.Socket)));
+        await core.up();
+        return core;
+    }
+    static unlistened() {
+        const dir = mkdtempSync(join(tmpdir(), FakeName.DirPrefix));
+        return new FakeHcCore(dir, brand(join(dir, FakeName.Socket)));
+    }
+    get open() {
+        return this.sockets.size;
+    }
+    get subscribed() {
+        return this.subscribers.size;
+    }
+    on(method, handler) {
+        this.handlers.set(method, handler);
+    }
+    delay(method, ms) {
+        this.delays.set(method, ms);
+    }
+    hello(patch) {
+        this.helloResult = { ...this.helloResult, ...patch };
+    }
+    async up() {
+        const server = createServer((socket) => { this.accept(socket); });
+        this.server = server;
+        await new Promise((resolve) => { server.listen(this.path, resolve); });
+    }
+    async down() {
+        const server = this.server;
+        this.server = null;
+        this.dropAll();
+        if (server !== null) {
+            await new Promise((resolve) => { server.close(() => { resolve(); }); });
+        }
+    }
+    dropAll() {
+        for (const socket of this.sockets) {
+            socket.destroy();
+        }
+    }
+    event(type, terminal, data) {
+        this.seq += 1;
+        const base = section(frame(FrameName.eventOf(type)), HcField.Params);
+        this.send(HcNotificationMethod.Event, { [HcField.Seq]: this.seq, [HcField.Terminal]: terminal, [HcField.Type]: type, [HcField.Data]: data ?? section(base, HcField.Data) });
+        return this.seq;
+    }
+    heartbeat() {
+        this.send(HcNotificationMethod.Heartbeat, { [HcField.Seq]: this.seq });
+    }
+    missed(terminals) {
+        this.seq += 1;
+        this.send(HcNotificationMethod.Missed, { [HcField.Seq]: this.seq, [HcField.Terminals]: terminals });
+    }
+    raw(text) {
+        for (const socket of this.subscribers) {
+            socket.write(text);
+        }
+    }
+    async stop() {
+        for (const timer of this.timers) {
+            clearTimeout(timer);
+        }
+        await this.down();
+        rmSync(this.dir, { recursive: true, force: true });
+    }
+    send(method, params) {
+        const line = JSON.stringify({ [HcField.JsonRpc]: HC_JSONRPC_VERSION, [HcField.Method]: method, [HcField.Params]: params }) + HC_LINE_SEPARATOR;
+        for (const socket of this.subscribers) {
+            socket.write(line);
+        }
+    }
+    accept(socket) {
+        this.connections += 1;
+        const connection = this.connections;
+        this.sockets.add(socket);
+        let rest = EMPTY_TEXT;
+        socket.on(SocketEvent.Data, (chunk) => {
+            const lines = (rest + chunk.toString(UTF8)).split(HC_LINE_SEPARATOR);
+            rest = lines.pop() ?? EMPTY_TEXT;
+            for (const line of lines) {
+                this.handle(socket, line, connection);
+            }
+        });
+        socket.on(SocketEvent.Error, () => undefined);
+        socket.on(SocketEvent.Close, () => { this.sockets.delete(socket); this.subscribers.delete(socket); });
+    }
+    handle(socket, line, connection) {
+        const request = JSON.parse(line);
+        if (!isFields(request) || !isString(request[HcField.Method])) {
+            return;
+        }
+        const method = String(request[HcField.Method]);
+        const params = section(request, HcField.Params);
+        this.seen.push({ method, params, connection });
+        if (this.silent) {
+            return;
+        }
+        const wait = this.delays.get(method) ?? 0;
+        const timer = setTimeout(() => { this.timers.delete(timer); this.reply(socket, request[HcField.Id], method, params); }, wait);
+        this.timers.add(timer);
+    }
+    reply(socket, id, method, params) {
+        if (socket.destroyed) {
+            return;
+        }
+        const body = this.outcome(socket, method, params);
+        const line = JSON.stringify({ [HcField.Id]: id, [HcField.JsonRpc]: HC_JSONRPC_VERSION, ...body }) + HC_LINE_SEPARATOR;
+        if (!this.splitReplies) {
+            socket.write(line);
+            return;
+        }
+        socket.write(line.slice(0, SPLIT_AT));
+        const timer = setTimeout(() => { this.timers.delete(timer); socket.write(line.slice(SPLIT_AT)); }, SPLIT_DELAY);
+        this.timers.add(timer);
+    }
+    outcome(socket, method, params) {
+        try {
+            return { [HcField.Result]: this.resultOf(socket, method, params) };
+        }
+        catch (cause) {
+            if (cause instanceof FakeFault) {
+                return { [HcField.Error]: { [HcField.Code]: cause.code, [HcField.Message]: cause.message, [HcField.Data]: { [HcField.Kind]: cause.kind } } };
+            }
+            throw cause;
+        }
+    }
+    resultOf(socket, method, params) {
+        const custom = this.handlers.get(method);
+        if (custom !== undefined) {
+            return custom(params);
+        }
+        const serve = this.served.get(method);
+        if (serve === undefined) {
+            throw new FakeFault(FakeRpcCode.MethodNotFound, FakeFaultKind.MethodNotFound, FakeText.NoMethod(method));
+        }
+        return serve(socket, params);
+    }
+    served = new Map([
+        [HC_HELLO_METHOD, () => this.helloResult],
+        [HC_LIST_METHOD, () => ({ [FakeField.HiddenFinished]: 0, [HcField.Terminals]: this.terminals })],
+        [HC_GET_METHOD, (_socket, params) => this.getOf(params[HcField.Terminal])],
+        [HC_READ_METHOD, (_socket, params) => ({ text: FakeText.Screen(params[HcField.Terminal]), complete: true, how: FakeScreen.How, why: null })],
+        [HC_SUBSCRIBE_METHOD, (socket) => { this.subscribers.add(socket); return { [FakeField.Channel]: null, [HcField.Seq]: this.seq, [HcField.Terminals]: this.terminals }; }],
+    ]);
+    getOf(address) {
+        const found = this.terminals.find((terminal) => terminal[FakeField.Address] === address);
+        if (found === undefined) {
+            throw new FakeFault(FakeRpcCode.NotFound, FakeFaultKind.NotFound, FakeText.NoTerminal(address));
+        }
+        return found;
+    }
+}
+export function nextWithin(iterator, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { resolve(null); }, ms);
+        iterator.next().then((step) => { clearTimeout(timer); resolve(step.done === true ? null : step.value); return step; }, reject);
+    });
+}
+export const later = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });

package/dist/core/test-kit/frames.d.ts

@@ -0,0 +1 @@
+export declare const RECORDED_FRAMES: unknown;