tickmarkr 1.64.0 → 1.66.0

package/dist/tui/app.d.ts

@@ -0,0 +1,40 @@
+import { type OutputStream } from "../tui/engine.js";
+import type { InputStream } from "../tui/input.js";
+export type View = {
+    id: string;
+    label: string;
+    render(props: {
+        cols: number;
+        rows: number;
+    }): string[];
+};
+export type StudioOptions = {
+    input: InputStream;
+    output: OutputStream;
+};
+export declare class StudioApp {
+    private engine;
+    private views;
+    private active;
+    private showingHelp;
+    private notice;
+    private _lines;
+    private resolveExit;
+    readonly exited: Promise<void>;
+    constructor(opts: StudioOptions);
+    /** Current line model last rendered or prepared. */
+    get lines(): string[];
+    /** Labels of every registered view, in order. */
+    get viewLabels(): string[];
+    /** Enter the alternate screen and start routing input. */
+    start(): void;
+    /** Restore the terminal and release the input stream. */
+    stop(): void;
+    private bindKeys;
+    private setView;
+    private showNotice;
+    private paint;
+    private buildFrame;
+    private renderTabBar;
+    private renderHelp;
+}

package/dist/tui/app.js

@@ -0,0 +1,130 @@
+import { TerminalEngine } from "../tui/engine.js";
+import { createFleetView } from "./views/fleet-view.js";
+import { createPreviewView } from "./views/preview-view.js";
+import { createProfileView } from "./views/profile-view.js";
+import { createRoutingView } from "./views/routing-view.js";
+const MUTATION_KEYS = ["r", "s", "m", "return"];
+const READONLY_NOTICE = "read-only in v1.66 — write path ships in v1.67";
+export class StudioApp {
+    engine;
+    views;
+    active = 0;
+    showingHelp = false;
+    notice = null;
+    _lines = [];
+    resolveExit = null;
+    exited;
+    constructor(opts) {
+        this.engine = new TerminalEngine({
+            input: opts.input,
+            output: opts.output,
+            onResize: () => this.paint(),
+        });
+        this.views = [createFleetView(), createRoutingView(), createPreviewView(), createProfileView()];
+        this.exited = new Promise((resolve) => {
+            this.resolveExit = resolve;
+        });
+    }
+    /** Current line model last rendered or prepared. */
+    get lines() {
+        return this._lines;
+    }
+    /** Labels of every registered view, in order. */
+    get viewLabels() {
+        return this.views.map((v) => v.label);
+    }
+    /** Enter the alternate screen and start routing input. */
+    start() {
+        this.bindKeys();
+        this.paint();
+        this.engine.start(this._lines);
+    }
+    /** Restore the terminal and release the input stream. */
+    stop() {
+        this.engine.stop();
+        if (this.resolveExit) {
+            this.resolveExit();
+            this.resolveExit = null;
+        }
+    }
+    bindKeys() {
+        // view switching
+        // Tab is decoded as the raw "\t" sequence by the micro-engine.
+        this.engine.key("\t", () => this.setView((this.active + 1) % this.views.length));
+        for (let i = 1; i <= this.views.length; i++) {
+            const idx = i - 1;
+            this.engine.key(String(i), () => this.setView(idx));
+        }
+        // help overlay
+        this.engine.key("?", () => {
+            this.showingHelp = true;
+            this.paint();
+        });
+        // dismissal / quit
+        this.engine.key("escape", () => {
+            if (this.showingHelp) {
+                this.showingHelp = false;
+                this.paint();
+            }
+            else {
+                this.stop();
+            }
+        });
+        this.engine.key("q", () => this.stop());
+        // mutation keys — read-only until the v1.67 write path
+        for (const key of MUTATION_KEYS) {
+            this.engine.key(key, () => this.showNotice());
+        }
+    }
+    setView(idx) {
+        this.active = idx;
+        this.showingHelp = false;
+        this.notice = null;
+        this.paint();
+    }
+    showNotice() {
+        this.notice = READONLY_NOTICE;
+        this.paint();
+    }
+    paint() {
+        this._lines = this.buildFrame();
+        this.engine.render(this._lines);
+    }
+    buildFrame() {
+        const { cols, rows } = this.engine.size;
+        const lines = [];
+        lines.push(this.renderTabBar());
+        if (this.showingHelp) {
+            lines.push(...this.renderHelp());
+        }
+        else {
+            const view = this.views[this.active];
+            lines.push(...view.render({ cols, rows: Math.max(rows - 2, 1) }));
+        }
+        if (this.notice) {
+            lines.push(this.notice);
+        }
+        return lines;
+    }
+    renderTabBar() {
+        const parts = ["tickmarkr ui ──"];
+        for (let i = 0; i < this.views.length; i++) {
+            const view = this.views[i];
+            const marker = i === this.active ? `*${view.label}` : view.label;
+            parts.push(`[${i + 1}]${marker}`);
+        }
+        return parts.join(" ");
+    }
+    renderHelp() {
+        return [
+            "Key bindings",
+            "1-4      switch view",
+            "tab      cycle views",
+            "?        show this help",
+            "esc / q  quit",
+            "r        re-probe (read-only)",
+            "s        save (read-only)",
+            "m        mode (read-only)",
+        ];
+    }
+}

package/dist/tui/engine.d.ts

@@ -0,0 +1,52 @@
+import { type Key, type KeyHandler, type InputStream } from "./input.js";
+export type { Key, KeyHandler };
+/** Writable stream with the small surface the engine needs. */
+export interface OutputStream {
+    isTTY?: boolean;
+    columns?: number;
+    rows?: number;
+    write: (chunk: string) => unknown;
+    on?(event: "resize", listener: () => void): this;
+    off?(event: "resize", listener: () => void): this;
+}
+export interface EngineOptions {
+    input: InputStream;
+    output: OutputStream;
+    onResize?: (cols: number, rows: number) => void;
+    onError?: (error: unknown) => void;
+}
+/**
+ * Dependency-free terminal engine: alternate-screen line-diff renderer, named-key routing,
+ * resize tracking, and terminal restoration on every exit path including thrown handlers.
+ */
+export declare class TerminalEngine {
+    private opts;
+    private frame;
+    private input;
+    private lastLines;
+    private _cols;
+    private _rows;
+    private running;
+    private userHandlers;
+    constructor(opts: EngineOptions);
+    /** Enter the alternate screen, begin listening for keys and resize events. */
+    start(lines: string[]): void;
+    /** Restore the terminal and stop listening. Safe to call multiple times. */
+    stop(): void;
+    /** Update the line model; only changed lines are repainted. */
+    render(lines: string[]): void;
+    /** Register a handler for a named key. */
+    key(name: string, handler: KeyHandler): void;
+    /** Unregister a handler. */
+    unkey(name: string, handler: KeyHandler): void;
+    /** Trigger a full repaint at the new size. */
+    resize(cols: number, rows: number): void;
+    /** Current terminal size as last seen or reported by a resize event. */
+    get size(): {
+        cols: number;
+        rows: number;
+    };
+    private onResize;
+    private attachResize;
+    private detachResize;
+}

package/dist/tui/engine.js

@@ -0,0 +1,92 @@
+import { Frame } from "./frame.js";
+import { InputRouter } from "./input.js";
+/**
+ * Dependency-free terminal engine: alternate-screen line-diff renderer, named-key routing,
+ * resize tracking, and terminal restoration on every exit path including thrown handlers.
+ */
+export class TerminalEngine {
+    opts;
+    frame;
+    input;
+    lastLines = [];
+    _cols;
+    _rows;
+    running = false;
+    userHandlers = new Map();
+    constructor(opts) {
+        this.opts = opts;
+        this.frame = new Frame(opts.output);
+        this.input = new InputRouter(opts.input);
+        this._cols = opts.output.columns ?? 80;
+        this._rows = opts.output.rows ?? 24;
+    }
+    /** Enter the alternate screen, begin listening for keys and resize events. */
+    start(lines) {
+        if (this.running)
+            return;
+        this.running = true;
+        this.lastLines = lines.slice();
+        this.frame.enter(this.lastLines);
+        this.input.start();
+        this.attachResize();
+    }
+    /** Restore the terminal and stop listening. Safe to call multiple times. */
+    stop() {
+        if (!this.running)
+            return;
+        this.detachResize();
+        this.input.stop();
+        this.frame.exit();
+        this.running = false;
+    }
+    /** Update the line model; only changed lines are repainted. */
+    render(lines) {
+        this.lastLines = lines.slice();
+        this.frame.render(this.lastLines);
+    }
+    /** Register a handler for a named key. */
+    key(name, handler) {
+        const wrapped = async (k) => {
+            try {
+                await handler(k);
+            }
+            catch (e) {
+                this.stop();
+                this.opts.onError?.(e);
+            }
+        };
+        this.userHandlers.set(handler, wrapped);
+        this.input.on(name, wrapped);
+    }
+    /** Unregister a handler. */
+    unkey(name, handler) {
+        const wrapped = this.userHandlers.get(handler);
+        if (wrapped) {
+            this.input.off(name, wrapped);
+            this.userHandlers.delete(handler);
+        }
+    }
+    /** Trigger a full repaint at the new size. */
+    resize(cols, rows) {
+        this._cols = cols;
+        this._rows = rows;
+        this.frame.resize(this.lastLines);
+        this.opts.onResize?.(cols, rows);
+    }
+    /** Current terminal size as last seen or reported by a resize event. */
+    get size() {
+        return { cols: this._cols, rows: this._rows };
+    }
+    onResize = () => {
+        this._cols = this.opts.output.columns ?? this._cols;
+        this._rows = this.opts.output.rows ?? this._rows;
+        this.frame.resize(this.lastLines);
+        this.opts.onResize?.(this._cols, this._rows);
+    };
+    attachResize() {
+        this.opts.output.on?.("resize", this.onResize);
+    }
+    detachResize() {
+        this.opts.output.off?.("resize", this.onResize);
+    }
+}

package/dist/tui/frame.d.ts

@@ -0,0 +1,22 @@
+/** A write target — anything with a write(chunk: string) method. */
+export interface OutputSink {
+    write: (chunk: string) => unknown;
+}
+/** Frame state + diff rendering. */
+export declare class Frame {
+    private out;
+    private prev;
+    private active;
+    constructor(out: OutputSink);
+    /** Enter the alternate screen, hide the cursor, and paint the initial frame. */
+    enter(lines: string[]): void;
+    /**
+     * Paint only the lines that differ from the previous model. Lines are addressed with
+     * absolute cursor positioning; unchanged rows produce no output.
+     */
+    render(lines: string[]): void;
+    /** Invalidate the cached frame so the next render writes every line. */
+    resize(lines: string[]): void;
+    /** Restore the terminal: show cursor and return to the normal screen buffer. */
+    exit(): void;
+}

package/dist/tui/frame.js

@@ -0,0 +1,56 @@
+// Line-diff renderer for the alternate screen. Maintains the previous line model and
+// repaints only rows that changed since the last render, keeping terminal traffic small.
+/** Frame state + diff rendering. */
+export class Frame {
+    out;
+    prev = [];
+    active = false;
+    constructor(out) {
+        this.out = out;
+    }
+    /** Enter the alternate screen, hide the cursor, and paint the initial frame. */
+    enter(lines) {
+        this.active = true;
+        this.prev = [];
+        this.out.write("\x1b[?1049h"); // alternate screen buffer
+        this.out.write("\x1b[?25l"); // hide cursor
+        this.render(lines);
+    }
+    /**
+     * Paint only the lines that differ from the previous model. Lines are addressed with
+     * absolute cursor positioning; unchanged rows produce no output.
+     */
+    render(lines) {
+        if (!this.active)
+            return;
+        const curr = lines.slice();
+        const max = Math.max(this.prev.length, curr.length);
+        for (let i = 0; i < max; i++) {
+            if (this.prev[i] !== curr[i]) {
+                this.out.write(`\x1b[${i + 1};1H`); // row i+1, column 1
+                this.out.write(curr[i] ?? "");
+                this.out.write("\x1b[K"); // clear to end of line
+            }
+        }
+        if (curr.length < this.prev.length) {
+            // The frame shrank — clear everything below the new last line.
+            this.out.write(`\x1b[${curr.length + 1};1H`);
+            this.out.write("\x1b[J");
+        }
+        this.prev = curr;
+    }
+    /** Invalidate the cached frame so the next render writes every line. */
+    resize(lines) {
+        this.prev = [];
+        this.render(lines);
+    }
+    /** Restore the terminal: show cursor and return to the normal screen buffer. */
+    exit() {
+        if (!this.active)
+            return;
+        this.out.write("\x1b[?25h"); // show cursor
+        this.out.write("\x1b[?1049l"); // normal screen buffer
+        this.active = false;
+        this.prev = [];
+    }
+}

package/dist/tui/input.d.ts

@@ -0,0 +1,41 @@
+/** Decoded keypress shape. */
+export interface Key {
+    name?: string;
+    sequence?: string;
+    ctrl?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+}
+/** Handler for a named key. May be async. */
+export type KeyHandler = (key: Key) => void | Promise<void>;
+/** Readable stream with the small TTY surface the engine needs. */
+export interface InputStream extends NodeJS.ReadableStream {
+    isTTY?: boolean;
+    setRawMode?: (mode: boolean) => unknown;
+}
+/**
+ * Decode the next key at the start of a byte buffer. Returns the decoded key and
+ * how many bytes were consumed. Undefined when more bytes are needed.
+ */
+export declare function decodeOneKey(buf: Buffer): {
+    key: Key;
+    consumed: number;
+} | undefined;
+/** Routes decoded keypress events to handlers registered by key name. */
+export declare class InputRouter {
+    private input;
+    private handlers;
+    private started;
+    private buffer;
+    constructor(input: InputStream);
+    /** Register a handler for a named key (e.g. "up", "escape", "q"). */
+    on(name: string, handler: KeyHandler): void;
+    /** Remove a previously registered handler. */
+    off(name: string, handler: KeyHandler): void;
+    /** Start decoding keypresses from the input stream. Idempotent. */
+    start(): void;
+    /** Stop decoding and release the stream. Idempotent. */
+    stop(): void;
+    private onData;
+    private dispatch;
+}

package/dist/tui/input.js

@@ -0,0 +1,100 @@
+/**
+ * Decode the next key at the start of a byte buffer. Returns the decoded key and
+ * how many bytes were consumed. Undefined when more bytes are needed.
+ */
+export function decodeOneKey(buf) {
+    if (buf.length === 0)
+        return undefined;
+    const b0 = buf[0];
+    if (b0 === 0x1b) {
+        // CSI arrow sequences: ESC [ A/B/C/D. Keep an incomplete CSI buffered so
+        // arbitrary stream chunking cannot turn an arrow into Escape + plain keys.
+        if (buf[1] === 0x5b) {
+            if (buf.length < 3)
+                return undefined;
+            const name = buf[2] === 0x41 ? "up"
+                : buf[2] === 0x42 ? "down"
+                    : buf[2] === 0x43 ? "right"
+                        : buf[2] === 0x44 ? "left"
+                            : undefined;
+            if (name) {
+                return { key: { name, sequence: buf.subarray(0, 3).toString("binary") }, consumed: 3 };
+            }
+        }
+        // A lone ESC (or ESC followed by something we do not recognise) is Escape.
+        return { key: { name: "escape", sequence: "\x1b" }, consumed: 1 };
+    }
+    if (b0 === 0x0d || b0 === 0x0a) {
+        return { key: { name: "return", sequence: String.fromCharCode(b0) }, consumed: 1 };
+    }
+    if (b0 === 0x03) {
+        return { key: { name: "c", ctrl: true, sequence: "\x03" }, consumed: 1 };
+    }
+    if (b0 >= 0x20 && b0 < 0x7f) {
+        return { key: { name: String.fromCharCode(b0), sequence: String.fromCharCode(b0) }, consumed: 1 };
+    }
+    // Unknown byte: consume it without a name so it does not block the stream.
+    return { key: { sequence: String.fromCharCode(b0) }, consumed: 1 };
+}
+/** Routes decoded keypress events to handlers registered by key name. */
+export class InputRouter {
+    input;
+    handlers = new Map();
+    started = false;
+    buffer = Buffer.alloc(0);
+    constructor(input) {
+        this.input = input;
+    }
+    /** Register a handler for a named key (e.g. "up", "escape", "q"). */
+    on(name, handler) {
+        let set = this.handlers.get(name);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(name, set);
+        }
+        set.add(handler);
+    }
+    /** Remove a previously registered handler. */
+    off(name, handler) {
+        this.handlers.get(name)?.delete(handler);
+    }
+    /** Start decoding keypresses from the input stream. Idempotent. */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.input.setRawMode?.(true);
+        this.input.on("data", this.onData);
+        this.input.resume();
+    }
+    /** Stop decoding and release the stream. Idempotent. */
+    stop() {
+        if (!this.started)
+            return;
+        this.input.off("data", this.onData);
+        this.input.setRawMode?.(false);
+        this.input.pause();
+        this.started = false;
+    }
+    onData = (chunk) => {
+        const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "binary");
+        this.buffer = Buffer.concat([this.buffer, data]);
+        while (this.buffer.length > 0) {
+            const result = decodeOneKey(this.buffer);
+            if (!result)
+                break;
+            this.dispatch(result.key);
+            this.buffer = this.buffer.subarray(result.consumed);
+        }
+    };
+    dispatch(key) {
+        const name = key.name ?? key.sequence;
+        if (!name)
+            return;
+        const set = this.handlers.get(name);
+        if (!set)
+            return;
+        for (const handler of set)
+            void handler(key);
+    }
+}

package/dist/tui/views/fleet-view.d.ts

@@ -0,0 +1,69 @@
+import type { View } from "../app.js";
+import type { AuthHealth } from "../../adapters/types.js";
+import type { Tier } from "../../config/config.js";
+import type { TelemetryRow } from "../../run/journal.js";
+/** One discovered adapter and its classified models (cfg.tiers via channels()). */
+export type FleetRosterEntry = {
+    adapter: string;
+    models: {
+        model: string;
+        tier: Tier;
+        channel: "sub" | "api";
+    }[];
+};
+/** Provenance notes harvested from overlay `# comment`s (fleet-overlay.ts shapes). */
+export type FleetProvenanceNotes = {
+    denyAdapters?: Record<string, string>;
+    denyModels?: Record<string, string>;
+};
+/** Everything the roster renders — loaded by the caller, never by the render path. */
+export type FleetViewData = {
+    adapters: FleetRosterEntry[];
+    /** Doctor cache contents (doctor.json), keyed by adapter id. */
+    health: Record<string, AuthHealth>;
+    /** Age of the doctor cache in ms; null when no probe data exists. */
+    doctorAgeMs: number | null;
+    denyAdapters: string[];
+    /** routing.deny.models entries in channelKey form ("adapter:model"). */
+    denyModels: string[];
+    notes?: FleetProvenanceNotes;
+    /** Telemetry folded from recent run journals (readAllTelemetry); runId optional. */
+    telemetry: (TelemetryRow & {
+        runId?: string;
+    })[];
+};
+/** Per-channel health digest, folded from journal telemetry rows only. */
+export type ChannelHealth = {
+    key: string;
+    tasks: number;
+    attempts: number;
+    done: number;
+    failed: number;
+    human: number;
+    overruns: number;
+    quotaFailovers: number;
+    /** Sum of OBSERVED gateFails; null when no row carried the field (unobserved, never 0). */
+    gateFails: number | null;
+    medianDurationMs: number | null;
+    lastOutcome: TelemetryRow["outcome"] | null;
+};
+/** Fold journal telemetry rows into a per-channel health digest keyed by channelKey
+ *  ("adapter:model"). The digest derives from journal telemetry (TelemetryRow, the rows the
+ *  daemon appends to each run's telemetry.jsonl) rather than any new state file: this module
+ *  reads nothing and writes nothing — the caller folds rows out of the existing run journals
+ *  (readAllTelemetry) and the fold is a pure function of them, same telemetry in, same digest
+ *  out. */
+export declare function foldChannelHealth(rows: (TelemetryRow & {
+    runId?: string;
+})[]): Map<string, ChannelHealth>;
+/** The studio View plus the roster's own key seam. The T2 shell binds only view-level keys, so
+ *  expand/collapse and selection are driven through key() — the same names the engine decodes. */
+export type FleetView = View & {
+    /** Handle a decoded key name ("up" | "down" | "left" | "right" | "space" | "return"). */
+    key(name: string): void;
+    /** Whether an adapter's model rows are currently shown. */
+    expanded(adapter: string): boolean;
+    /** channelKey of the cursor's channel, or null when the cursor sits on an adapter row. */
+    selectedChannel(): string | null;
+};
+export declare function createFleetView(data?: FleetViewData): FleetView;