@xrkseek/harness 0.6.23 → 0.7.0-rc.2

package/node_modules/@xrkseek/claude-code-mods/dist/surfaces.js

@@ -0,0 +1,243 @@
+/**
+ * The band above the prompt as the host draws it for one session: renders
+ * through the mods' `ui.render` hooks, keeps the latest tree with its button
+ * callbacks held host-side, redraws when a `$.state` value a render read
+ * changes or a mod asks, and hands watchers each new generation.
+ * @module
+ */
+import { serializeTree, treeProblem } from "./elements.js";
+import { messageOf } from "./values.js";
+class SessionBand {
+    generation = 0;
+    tree = null;
+    /** `$.state` slots the last render read, as `<plugin>\u0000<key>`. */
+    subscribed = new Set();
+    /** Button callbacks of the current generation, by the `actionId` the serialized tree carries. */
+    actions = new Map();
+    watchers = new Set();
+    /** The render in flight; a refresh during it joins one more pass that starts when it ends. */
+    rendering;
+    pending;
+    /** Set by `forget`: watchers end at their next wake and no further pass renders. */
+    closed = false;
+    /** Wakes every parked watcher, so a closed band ends its streams. */
+    wakers = new Set();
+    /** Set while a render runs: `$.state` reads subscribe. */
+    collecting;
+    snapshot() {
+        return { generation: this.generation, tree: this.tree };
+    }
+}
+/**
+ * Bands by session id.
+ */
+export class SurfaceTable {
+    host;
+    bands = new Map();
+    disposed = false;
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * The latest snapshot of a session's band, drawing it first when nothing was drawn yet.
+     * @param sessionId - the session.
+     * @returns the current generation.
+     */
+    async current(sessionId) {
+        const band = this.bandOf(sessionId);
+        if (band.generation === 0)
+            await this.refresh(sessionId);
+        return band.snapshot();
+    }
+    /**
+     * Watch a session's band: the current snapshot first, then every redraw, until the signal aborts.
+     * @param sessionId - the session.
+     * @param signal - ends the watch.
+     * @returns the snapshots.
+     */
+    async *watch(sessionId, signal) {
+        const band = this.bandOf(sessionId);
+        const queue = [];
+        let wake;
+        const watcher = (snapshot) => {
+            queue.push(snapshot);
+            wake?.();
+        };
+        band.watchers.add(watcher);
+        const onAbort = () => {
+            wake?.();
+        };
+        const waker = () => {
+            wake?.();
+        };
+        band.wakers.add(waker);
+        signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            const first = await this.current(sessionId);
+            let delivered = first.generation;
+            yield first;
+            while (!signal.aborted && !band.closed) {
+                const next = queue.shift();
+                if (next !== undefined) {
+                    // The first drawing may arrive both as the current snapshot and as a watcher notification.
+                    if (next.generation <= delivered)
+                        continue;
+                    delivered = next.generation;
+                    yield next;
+                    continue;
+                }
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+                wake = undefined;
+            }
+        }
+        finally {
+            band.watchers.delete(watcher);
+            band.wakers.delete(waker);
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
+    /**
+     * Redraw a session's band through the mods and notify watchers when the tree changed.
+     * @param sessionId - the session.
+     * @returns settles once the redraw landed.
+     */
+    refresh(sessionId) {
+        const band = this.bandOf(sessionId);
+        if (band.rendering === undefined) {
+            band.rendering = this.renderOnce(sessionId, band).finally(() => {
+                band.rendering = undefined;
+            });
+            return band.rendering;
+        }
+        // One more pass after the one in flight serves every refresh asked for meanwhile.
+        band.pending ??= band.rendering.then(() => {
+            band.pending = undefined;
+            return this.refresh(sessionId);
+        });
+        return band.pending;
+    }
+    /**
+     * Run the callback a button holds and redraw. A press from an earlier
+     * generation is ignored: the button it names may no longer exist.
+     * @param sessionId - the session.
+     * @param generation - the generation the client saw.
+     * @param actionId - the id the serialized Button carried.
+     * @returns the snapshot after the press.
+     */
+    async press(sessionId, generation, actionId) {
+        const band = this.bandOf(sessionId);
+        const action = generation === band.generation ? band.actions.get(actionId) : undefined;
+        if (action === undefined) {
+            this.host.report(`band press ignored: ${actionId} of generation ${generation} is not on the current drawing (${band.generation})`);
+            return band.snapshot();
+        }
+        await this.host.runAction(sessionId, action);
+        await this.refresh(sessionId);
+        return band.snapshot();
+    }
+    /**
+     * Note a `$.state` read: during a render it subscribes the band to the slot.
+     * @param sessionId - the session the state belongs to.
+     * @param slot - the `<plugin>\u0000<key>` slot.
+     */
+    stateRead(sessionId, slot) {
+        this.bands.get(sessionId)?.collecting?.add(slot);
+    }
+    /**
+     * Note a `$.state` write: a subscribed band redraws.
+     * @param sessionId - the session the state belongs to.
+     * @param slot - the `<plugin>\u0000<key>` slot.
+     */
+    stateWritten(sessionId, slot) {
+        const band = this.bands.get(sessionId);
+        if (band === undefined || !band.subscribed.has(slot))
+            return;
+        void this.refresh(sessionId);
+    }
+    /**
+     * Forget a session's band: its watch streams end and no further pass renders it.
+     * @param sessionId - the disposed session.
+     */
+    forget(sessionId) {
+        const band = this.bands.get(sessionId);
+        if (band === undefined)
+            return;
+        this.bands.delete(sessionId);
+        band.closed = true;
+        band.watchers.clear();
+        for (const waker of [...band.wakers])
+            waker();
+    }
+    /** Stop drawing: every band is forgotten and its watch streams end. */
+    dispose() {
+        this.disposed = true;
+        for (const sessionId of [...this.bands.keys()])
+            this.forget(sessionId);
+    }
+    bandOf(sessionId) {
+        let band = this.bands.get(sessionId);
+        if (band === undefined) {
+            band = new SessionBand();
+            this.bands.set(sessionId, band);
+        }
+        return band;
+    }
+    async renderOnce(sessionId, band) {
+        if (this.disposed || band.closed)
+            return;
+        const input = {
+            component: "AbovePrompt",
+            surface: "AbovePrompt",
+            props: {
+                bodyColumns: this.host.columns,
+                hasSurvey: false,
+                isWorking: false,
+                maxRows: this.host.rows,
+            },
+            viewport: { columns: this.host.columns },
+        };
+        band.collecting = new Set();
+        let tree;
+        try {
+            tree = await this.host.render(sessionId, input);
+        }
+        catch (error) {
+            this.host.report(`band render failed: ${messageOf(error)}`);
+            tree = null;
+        }
+        band.subscribed.clear();
+        for (const slot of band.collecting)
+            band.subscribed.add(slot);
+        band.collecting = undefined;
+        const problem = treeProblem(tree);
+        if (problem !== undefined) {
+            this.host.report(`a ui.render hook returned a tree that does not validate: ${problem}`);
+            tree = null;
+        }
+        // Action ids count up per drawing, so an unchanged tree serializes identically and keeps its generation.
+        const actions = new Map();
+        const serialized = serializeTree(tree, (callback) => {
+            const id = `a${actions.size}`;
+            actions.set(id, callback);
+            return id;
+        });
+        const next = serialized.length === 0 ? null : serialized;
+        if (band.generation > 0 && JSON.stringify(next) === JSON.stringify(band.tree)) {
+            // The same drawing with possibly fresh closures: keep the generation, hold the new callbacks.
+            band.actions.clear();
+            for (const [id, action] of actions)
+                band.actions.set(id, action);
+            return;
+        }
+        band.generation += 1;
+        band.tree = next;
+        band.actions.clear();
+        for (const [id, action] of actions)
+            band.actions.set(id, action);
+        for (const watcher of band.watchers)
+            watcher(band.snapshot());
+    }
+}
+//# sourceMappingURL=surfaces.js.map

package/node_modules/@xrkseek/claude-code-mods/dist/surfaces.js.map

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

package/node_modules/@xrkseek/claude-code-mods/dist/testing.d.ts

@@ -0,0 +1,157 @@
+/**
+ * A test kit in the shape of `claude-code/testing`: load mods, register
+ * stubs that answer in the engine's place beneath every mod, raise events
+ * through the mods' hooks, and mount a surface to assert what a mod draws —
+ * no session, agent, or harness service involved. This repository's test
+ * setup wraps it as `claude-code/testing` for the example mods' own tests.
+ * @module
+ */
+import type { LoadedMod, RegisteredHook } from "./chain.js";
+import type { ModPlugin } from "./define-mod.js";
+import type { TreePattern, UiElement, UiNode } from "./elements.js";
+import type { CommandRunInput, CommandRunResult, ModDefinition, ModsApi, PromptSubmitInput, PromptSubmitResult, SessionEndInput, SessionEndResult, SessionStartInput, SessionStartResult, ToolCallInput, ToolCallResult, TurnCompleteInput, TurnCompleteResult, TurnStartInput, TurnStartResult, UiRenderInput } from "./types.js";
+/**
+ * A stub answering one event in the engine's place. For an engine event it
+ * returns that event's result; for a mods API call it returns `{ value }` or
+ * `{ deny }`, and `undefined` from either reads as "not answered".
+ */
+export type StubHook = ($: ModsApi, e: never) => unknown;
+/** Test kit construction options. */
+export interface ModTestKitOptions {
+    /** Mods to load, in chain order: definitions or the plugins `defineMod` made. */
+    readonly mods?: readonly (ModDefinition | ModPlugin)[];
+    /** `register` option values by plugin name, overlaid on each mod's own options. */
+    readonly options?: Readonly<Record<string, ModDefinition["options"]>>;
+    /** A hook's own running-time limit in milliseconds; defaults to 5 seconds, Claude Code's test limit. */
+    readonly budgetMs?: number;
+}
+/** What `$.ui.mount` takes: the surface to draw and the props the host would pass. */
+export interface MountArgs {
+    /** The plugin under test; accepted for source compatibility, every loaded mod's `ui.render` hooks run in chain order. */
+    readonly plugin?: string;
+    /** The drawing surface's name (`terminal`, `desktop`); accepted for source compatibility. */
+    readonly surface?: string;
+    readonly component: UiRenderInput["component"];
+    /** The pane id a `Pane` was opened with; the band has none. */
+    readonly requestId?: string;
+    readonly props?: Readonly<Record<string, unknown>>;
+}
+/** A found element with the actions a test takes on it. */
+export interface MountedElement {
+    readonly element: UiElement;
+    /** The element's type. */
+    readonly type: UiElement["type"];
+    /** The text the element draws, descendants included. */
+    readonly text: string;
+    /** Run a Button's `onPress` and redraw. */
+    press(): Promise<void>;
+}
+/** A mounted surface: every read renders afresh through the mods' `ui.render` hooks. */
+export interface MountedSurface {
+    /** The current tree, as the hooks returned it. */
+    tree(): Promise<UiNode>;
+    /** The drawn text, one line per top-level node. */
+    text(): Promise<string>;
+    /** The first element matching the pattern, or undefined. */
+    find(pattern: TreePattern): Promise<MountedElement | undefined>;
+    /** Every element matching the pattern, in drawing order. */
+    findAll(pattern: TreePattern): Promise<MountedElement[]>;
+    unmount(): Promise<void>;
+}
+/** The engine's own `$`-shaped raisers: each sends its event through the mods and resolves to the result. */
+export interface TestKitRaisers {
+    readonly tool: {
+        call(input: Omit<ToolCallInput, "tool_use_id"> & {
+            tool_use_id?: string;
+        }): Promise<ToolCallResult>;
+    };
+    readonly command: {
+        run(input: Pick<CommandRunInput, "command" | "args">): Promise<CommandRunResult>;
+    };
+    readonly prompt: {
+        submit(input: Pick<PromptSubmitInput, "text"> & Partial<PromptSubmitInput>): Promise<PromptSubmitResult>;
+    };
+    readonly session: {
+        start(input?: Partial<SessionStartInput>): Promise<SessionStartResult>;
+        end(input?: Partial<SessionEndInput>): Promise<SessionEndResult>;
+    };
+    readonly turn: {
+        start(input: Partial<TurnStartInput> & Pick<TurnStartInput, "turnId">): Promise<TurnStartResult>;
+        complete(input?: Partial<TurnCompleteInput>): Promise<TurnCompleteResult>;
+    };
+    readonly ui: {
+        /** Mount one surface: it renders through the mods' `ui.render` hooks on every read. */
+        mount(args: MountArgs): Promise<MountedSurface>;
+    };
+}
+/** The engine events the kit raises, with their inputs, so a typed stub reads `e` without a cast. */
+export interface KitEventInputs {
+    "session.start": SessionStartInput;
+    "session.end": SessionEndInput;
+    "turn.start": TurnStartInput;
+    "turn.complete": TurnCompleteInput;
+    "prompt.submit": PromptSubmitInput;
+    "tool.call": ToolCallInput;
+    "command.run": CommandRunInput;
+    "ui.render": UiRenderInput;
+}
+/** The kit's `on`: registers a stub that answers one event beneath every mod; name a mods API call without the `$.`. */
+export interface KitOn {
+    /** A stub for one engine event, with the event's typed input. */
+    <K extends keyof KitEventInputs>(event: K, stub: ($: ModsApi, e: KitEventInputs[K]) => unknown): void;
+    /** A stub for any event or mods API call. */
+    (event: string, stub: StubHook): void;
+}
+/** A loaded test kit. */
+export interface ModTestKit {
+    /** Register a stub that answers `event` beneath every mod; name a mods API call without the `$.`. */
+    readonly on: KitOn;
+    /** Raise any event through the mods; a stub, a built-in default, or `no implementation for <event>` answers at the bottom. */
+    raise<R>(event: string, input: unknown): Promise<R>;
+    /** Typed raisers for the events this bridge sends from the harness, plus `ui.mount`. */
+    readonly $: TestKitRaisers;
+    /** Diagnostic lines the engine reported: skipped hooks, failed fire-and-forget calls, timer errors. */
+    readonly reports: string[];
+    /** The loaded mods in chain order. */
+    readonly mods: readonly LoadedMod[];
+    /**
+     * Drop every registration and close every mod timer.
+     * @returns settles once running timer callbacks have finished.
+     */
+    dispose(): Promise<void>;
+}
+/** Stubs that answer a whole namespace from memory. */
+export declare const mock: Readonly<{
+    /**
+     * Answer `$.store` from an in-memory map.
+     * @param on - the kit's `on`.
+     * @param initial - entries the store starts with.
+     * @returns the live map, to read what the mod saved.
+     */
+    store(on: ModTestKit["on"], initial?: Readonly<Record<string, unknown>>): Map<string, unknown>;
+    /**
+     * Answer `$.env.get` from fixed variables and record `$.env.set` writes.
+     * @param on - the kit's `on`.
+     * @param variables - the environment the mod sees.
+     * @returns the live record, to read what the mod set.
+     */
+    env(on: ModTestKit["on"], variables?: Readonly<Record<string, string>>): Record<string, string | undefined>;
+    /**
+     * Answer `$.clock.now` from a settable instant and `$.clock.sleep` at once, advancing it.
+     * @param on - the kit's `on`.
+     * @param startAt - the first `now()`, in epoch milliseconds.
+     * @returns the clock, to read or advance `now`.
+     */
+    clock(on: ModTestKit["on"], startAt?: number): {
+        now: number;
+        advance(ms: number): void;
+    };
+}>;
+/**
+ * Load mods for a test and return the kit.
+ * @param options - the mods to load and the hook time limit.
+ * @returns the kit, with every mod's `register` already run.
+ */
+export declare function createModTestKit(options?: ModTestKitOptions): Promise<ModTestKit>;
+export type { RegisteredHook };
+//# sourceMappingURL=testing.d.ts.map

package/node_modules/@xrkseek/claude-code-mods/dist/testing.d.ts.map

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