tickmarkr 1.79.0 → 1.81.0

package/dist/tui/cockpit/keys.js

@@ -0,0 +1,265 @@
+import { GLYPHS } from "../../brand.js";
+export function initialRunInteractionState() {
+    return {
+        selection: -1,
+        panel: 0,
+        opened: null,
+        follow: false,
+        filterPrompt: false,
+        filterQuery: "",
+        help: false,
+        quit: false,
+    };
+}
+/**
+ * The panels Tab cycles focus through, in cycle order; index 0 is the focus
+ * the surface opens with, so the initial frame is the one the anchors pin.
+ */
+export const RUN_PANEL_FOCUS_ORDER = ["RUN", "VIEWS", "KEYS"];
+/** A toggle's on/off report: the brand's reserved glyphs, never brackets. */
+export function toggleReport(label, on) {
+    return `${label} ${on ? GLYPHS.toggleActive : GLYPHS.toggleInactive}`;
+}
+/**
+ * Every key the run surface advertises, in keybar order. Each entry carries
+ * its handler, so advertisement and behaviour cannot drift apart.
+ */
+export const RUN_KEY_BINDINGS = [
+    {
+        key: "↑↓",
+        label: "Move",
+        matches: ({ key }) => key.upArrow === true || key.downArrow === true,
+        apply: (state, { key }) => ({
+            ...state,
+            selection: Math.max(-1, state.selection + (key.upArrow === true ? -1 : 1)),
+        }),
+    },
+    {
+        key: "⏎",
+        label: "Open",
+        matches: ({ key }) => key.return === true,
+        apply: (state) => state.selection >= 0 ? { ...state, opened: state.selection } : state,
+    },
+    {
+        key: "←",
+        label: "Back",
+        matches: ({ key }) => key.leftArrow === true,
+        apply: (state) => ({ ...state, opened: null }),
+    },
+    {
+        key: "Tab",
+        label: "Panel",
+        matches: ({ key }) => key.tab === true,
+        apply: (state) => ({
+            ...state,
+            panel: (state.panel + 1) % RUN_PANEL_FOCUS_ORDER.length,
+        }),
+    },
+    {
+        key: "?",
+        label: "Help",
+        matches: ({ input }) => input === "?",
+        apply: (state) => ({ ...state, help: !state.help }),
+    },
+    {
+        key: "q",
+        label: "Quit",
+        matches: ({ input }) => input === "q",
+        apply: (state) => ({ ...state, quit: true }),
+    },
+    {
+        key: "f",
+        label: "Follow",
+        matches: ({ input }) => input === "f",
+        apply: (state) => ({ ...state, follow: !state.follow }),
+        report: (state) => toggleReport("Follow", state.follow),
+    },
+    {
+        key: "/",
+        label: "Filter",
+        matches: ({ input }) => input === "/",
+        apply: (state) => ({ ...state, filterPrompt: true, filterQuery: "" }),
+    },
+];
+/** The panels the setup surface cycles through, in their painted order. */
+export const SETUP_PANEL_FOCUS_ORDER = ["SETUP", "HARNESSES", "KEYS"];
+export function initialSetupInteractionState() {
+    return {
+        selection: -1,
+        panel: 1,
+        step: 2,
+        selected: [],
+        all: false,
+        probeRevision: 0,
+        savePrompt: false,
+        saved: false,
+        help: false,
+        quit: false,
+    };
+}
+function setupStep(state, delta) {
+    return { ...state, step: Math.min(6, Math.max(1, state.step + delta)) };
+}
+/**
+ * Every setup advertisement and handler, in the exact order the surface has
+ * always drawn. The global six are registered here with setup semantics; the
+ * six setup-only bindings follow them on the same surface registry.
+ */
+export const SETUP_KEY_BINDINGS = [
+    {
+        key: "↑↓",
+        label: "Move",
+        matches: ({ key }) => key.upArrow === true || key.downArrow === true,
+        apply: (state, { key }) => ({
+            ...state,
+            selection: key.upArrow === true
+                ? Math.max(0, state.selection - 1)
+                : state.selection + 1,
+        }),
+    },
+    {
+        key: "⏎",
+        label: "Next",
+        matches: ({ key }) => key.return === true,
+        apply: (state) => setupStep(state, 1),
+    },
+    {
+        key: "←",
+        label: "Back",
+        matches: ({ key }) => key.leftArrow === true,
+        apply: (state) => setupStep(state, -1),
+    },
+    {
+        key: "Tab",
+        label: "Panel",
+        matches: ({ key }) => key.tab === true,
+        apply: (state) => ({
+            ...state,
+            panel: (state.panel + 1) % SETUP_PANEL_FOCUS_ORDER.length,
+        }),
+    },
+    {
+        key: "?",
+        label: "Help",
+        matches: ({ input }) => input === "?",
+        apply: (state) => ({ ...state, help: !state.help }),
+    },
+    {
+        key: "q",
+        label: "Quit",
+        matches: ({ input }) => input === "q",
+        apply: (state) => ({ ...state, quit: true }),
+    },
+    {
+        key: "␣",
+        label: "Toggle",
+        matches: ({ input }) => input === " ",
+        apply: (state) => {
+            const selection = Math.max(0, state.selection);
+            const selected = state.selected.includes(selection)
+                ? state.selected.filter((index) => index !== selection)
+                : [...state.selected, selection];
+            return { ...state, selection, selected, all: false };
+        },
+        report: (state) => toggleReport("Selection", state.all || state.selected.length > 0),
+    },
+    {
+        key: "a",
+        label: "All",
+        matches: ({ input }) => input === "a",
+        apply: (state) => ({ ...state, all: true, selected: [] }),
+    },
+    {
+        key: "r",
+        label: "Re-probe",
+        matches: ({ input }) => input === "r",
+        apply: (state) => ({ ...state, probeRevision: state.probeRevision + 1 }),
+    },
+    {
+        key: "s",
+        label: "Save",
+        matches: ({ input }) => input === "s",
+        apply: (state) => ({ ...state, savePrompt: true }),
+        report: (state) => toggleReport("Saved", state.saved),
+    },
+    {
+        key: "n",
+        label: "Next",
+        matches: ({ input }) => input === "n",
+        apply: (state) => setupStep(state, 1),
+    },
+    {
+        key: "p",
+        label: "Prev",
+        matches: ({ input }) => input === "p",
+        apply: (state) => setupStep(state, -1),
+    },
+];
+/** One surface-aware registry serves both cockpit renderers and dispatchers. */
+export const SURFACE_KEY_BINDINGS = {
+    run: RUN_KEY_BINDINGS,
+    setup: SETUP_KEY_BINDINGS,
+};
+/** Save confirmation owns input until it is accepted or dismissed. */
+export function applySetupPromptInput(event, state) {
+    if (!state.savePrompt)
+        return undefined;
+    if (event.input === "y" || event.key.return === true) {
+        return { ...state, savePrompt: false, saved: true };
+    }
+    if (event.input === "n" || event.key.escape === true) {
+        return { ...state, savePrompt: false };
+    }
+    return state;
+}
+/**
+ * The transitions of the open / prompt. The prompt is not an advertised key,
+ * so it has no binding — but its transitions live here beside the registry
+ * because they rewrite the same interaction state: characters grow the query,
+ * backspace shrinks it, ⏎ applies it (the journal stays narrowed), escape
+ * cancels it. Anything else the prompt swallows unchanged.
+ */
+export function applyFilterInput(event, state) {
+    if (!state.filterPrompt)
+        return undefined;
+    const { input, key } = event;
+    if (key.return === true)
+        return { ...state, filterPrompt: false };
+    if (key.escape === true) {
+        return { ...state, filterPrompt: false, filterQuery: "" };
+    }
+    if (key.backspace === true || key.delete === true) {
+        return { ...state, filterQuery: [...state.filterQuery].slice(0, -1).join("") };
+    }
+    if (input.length === 1 && key.ctrl !== true) {
+        return { ...state, filterQuery: state.filterQuery + input };
+    }
+    return state;
+}
+/**
+ * The keybar's entries, derived from a binding registry. This is the only way
+ * a keybar list is produced: remove a handler and its entry disappears.
+ */
+export function keybarEntries(bindings) {
+    return bindings.map(({ key, label }) => ({ key, label }));
+}
+/** The binding a key event activates, or undefined when no handler owns it. */
+export function resolveRunKeyBinding(bindings, event) {
+    return bindings.find((binding) => binding.matches(event));
+}
+/**
+ * Send a key event to the registry: the matching binding's handler produces
+ * the next interaction state. An event no handler owns changes nothing.
+ */
+export function dispatchRunKey(event, state, bindings = RUN_KEY_BINDINGS) {
+    const binding = resolveRunKeyBinding(bindings, event);
+    return binding?.apply(state, event);
+}
+/** The setup binding a key event activates, or undefined when none owns it. */
+export function resolveSetupKeyBinding(bindings, event) {
+    return bindings.find((binding) => binding.matches(event));
+}
+/** Send a key event through the setup half of the shared surface registry. */
+export function dispatchSetupKey(event, state, bindings = SETUP_KEY_BINDINGS) {
+    return resolveSetupKeyBinding(bindings, event)?.apply(state, event);
+}

package/dist/tui/cockpit/layout.d.ts

@@ -0,0 +1,76 @@
+export declare const COCKPIT_ROW_FLOOR = 14;
+export declare const COCKPIT_COLUMN_FLOOR = 40;
+export declare const FULL_JOURNAL_ROWS = 3;
+/**
+ * Ordered from highest priority (last surrendered) to lowest (first
+ * surrendered). A minimum row preserves an element in the compact frame; its
+ * preferred rows restore the full presentation before the next step receives
+ * any rows. The stats minimum is its one-line summary, not the full tiles.
+ */
+declare const ORDERED_POLICY: readonly [{
+    readonly element: "keybar";
+    readonly minimumRows: 1;
+    readonly preferredRows: 1;
+}, {
+    readonly element: "statusStrip";
+    readonly minimumRows: 1;
+    readonly preferredRows: 1;
+}, {
+    readonly element: "primaryHeader";
+    readonly minimumRows: 1;
+    readonly preferredRows: 1;
+}, {
+    readonly element: "progressBar";
+    readonly minimumRows: 1;
+    readonly preferredRows: 1;
+}, {
+    readonly element: "journal";
+    readonly minimumRows: 1;
+    readonly preferredRows: 3;
+}, {
+    readonly element: "progressCaption";
+    readonly minimumRows: 0;
+    readonly preferredRows: 1;
+}, {
+    readonly element: "statTiles";
+    readonly minimumRows: 1;
+    readonly preferredRows: 2;
+}, {
+    readonly element: "secondaryHeader";
+    readonly minimumRows: 0;
+    readonly preferredRows: 1;
+}];
+type PolicyElement = (typeof ORDERED_POLICY)[number]["element"];
+type RowAllocation = Record<PolicyElement, number>;
+export declare const LAYOUT_PRIORITY: readonly PolicyElement[];
+export declare const FULL_LAYOUT_ROWS: number;
+export type CockpitArrangement = "stacked" | "folded-keys" | "three-column";
+export interface FrameCockpitLayout {
+    renderer: "frame";
+    arrangement: CockpitArrangement;
+    elements: {
+        version: true;
+        keybar: true;
+        statusStrip: true;
+        primaryHeader: true;
+        progressBar: boolean;
+        progressCaption: boolean;
+        secondaryHeader: boolean;
+    };
+    stats: {
+        mode: "tiles" | "summary";
+        rows: number;
+        figures: readonly ["tasks", "gates", "pass"];
+    };
+    journalRows: number;
+    rowAllocation: {
+        chrome: number;
+    } & RowAllocation;
+}
+export interface PlainCockpitLayout {
+    renderer: "plain";
+    arrangement: "plain";
+}
+export type CockpitLayout = FrameCockpitLayout | PlainCockpitLayout;
+export declare function resolveCockpitLayout(columns: number, rows: number): CockpitLayout;
+export {};

package/dist/tui/cockpit/layout.js

@@ -0,0 +1,84 @@
+export const COCKPIT_ROW_FLOOR = 14;
+export const COCKPIT_COLUMN_FLOOR = 40;
+export const FULL_JOURNAL_ROWS = 3;
+const FRAME_CHROME_ROWS = 8;
+/**
+ * Ordered from highest priority (last surrendered) to lowest (first
+ * surrendered). A minimum row preserves an element in the compact frame; its
+ * preferred rows restore the full presentation before the next step receives
+ * any rows. The stats minimum is its one-line summary, not the full tiles.
+ */
+const ORDERED_POLICY = [
+    { element: "keybar", minimumRows: 1, preferredRows: 1 },
+    { element: "statusStrip", minimumRows: 1, preferredRows: 1 },
+    { element: "primaryHeader", minimumRows: 1, preferredRows: 1 },
+    { element: "progressBar", minimumRows: 1, preferredRows: 1 },
+    { element: "journal", minimumRows: 1, preferredRows: FULL_JOURNAL_ROWS },
+    { element: "progressCaption", minimumRows: 0, preferredRows: 1 },
+    { element: "statTiles", minimumRows: 1, preferredRows: 2 },
+    { element: "secondaryHeader", minimumRows: 0, preferredRows: 1 },
+];
+export const LAYOUT_PRIORITY = ORDERED_POLICY.map(({ element }) => element);
+export const FULL_LAYOUT_ROWS = FRAME_CHROME_ROWS +
+    ORDERED_POLICY.reduce((rows, step) => rows + step.preferredRows, 0);
+function arrangementFor(columns) {
+    if (columns >= 120)
+        return "three-column";
+    if (columns >= 90)
+        return "folded-keys";
+    return "stacked";
+}
+function allocateRows(rows) {
+    const allocation = Object.fromEntries(ORDERED_POLICY.map(({ element }) => [element, 0]));
+    let available = rows - FRAME_CHROME_ROWS;
+    // Preserve each element's compact form. At the contracted floor these
+    // minima consume the budget exactly.
+    for (const step of ORDERED_POLICY) {
+        const granted = Math.min(step.minimumRows, available);
+        allocation[step.element] = granted;
+        available -= granted;
+    }
+    // Restore full forms in priority order, never funding a lower-priority
+    // element while a higher-priority element remains compact.
+    for (const step of ORDERED_POLICY) {
+        const wanted = step.preferredRows - allocation[step.element];
+        const granted = Math.min(wanted, available);
+        allocation[step.element] += granted;
+        available -= granted;
+    }
+    // Once every element is full, journal history is the sole useful sink.
+    allocation.journal += available;
+    return allocation;
+}
+export function resolveCockpitLayout(columns, rows) {
+    if (!Number.isFinite(columns) ||
+        !Number.isFinite(rows) ||
+        columns < COCKPIT_COLUMN_FLOOR ||
+        rows < COCKPIT_ROW_FLOOR) {
+        return { renderer: "plain", arrangement: "plain" };
+    }
+    const allocation = allocateRows(Math.floor(rows));
+    return {
+        renderer: "frame",
+        arrangement: arrangementFor(Math.floor(columns)),
+        elements: {
+            version: true,
+            keybar: true,
+            statusStrip: true,
+            primaryHeader: true,
+            progressBar: allocation.progressBar > 0,
+            progressCaption: allocation.progressCaption > 0,
+            secondaryHeader: allocation.secondaryHeader > 0,
+        },
+        stats: {
+            mode: allocation.statTiles > 1 ? "tiles" : "summary",
+            rows: allocation.statTiles,
+            figures: ["tasks", "gates", "pass"],
+        },
+        journalRows: allocation.journal,
+        rowAllocation: {
+            chrome: FRAME_CHROME_ROWS,
+            ...allocation,
+        },
+    };
+}

package/dist/tui/cockpit/live.d.ts

@@ -0,0 +1,31 @@
+import type { RunCockpitData, RunCockpitSource } from "./derive.js";
+/**
+ * THE engagement selection rule — stated once, here, so it can change in one
+ * place without touching the renderer or the command: an explicit engagement
+ * reference from the command line wins; the bare command opens the most
+ * recently started engagement that has a readable journal.
+ */
+export declare function selectEngagementRunId(cwd: string, explicit?: string): string | null;
+/**
+ * The journal bytes of a real engagement — never a committed capture. A read
+ * failure throws: the caller refuses rather than drawing from nothing.
+ */
+export declare function loadEngagementSource(cwd: string, runId: string): RunCockpitSource;
+export declare function formatEventAge(ageMs: number): string;
+/**
+ * Live derivation over a real engagement's journal bytes. The header's
+ * elapsed field additionally states how long ago the engagement's last event
+ * arrived, so an engagement that has stopped moving reads as stale rather
+ * than as current. Throws on unreadable bytes (empty capture, no run-start) —
+ * the caller refuses instead of rendering a plausible surface from nothing.
+ */
+export declare function deriveLiveRunCockpitData(source: RunCockpitSource, binaryVersion: string, now?: () => number): RunCockpitData;
+export declare function runLiveCockpit({ input, output, cwd, runId, binaryVersion, refreshMs, now, }: {
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+    cwd: string;
+    runId: string;
+    binaryVersion: string;
+    refreshMs?: number;
+    now?: () => number;
+}): Promise<void>;

package/dist/tui/cockpit/live.js

@@ -0,0 +1,135 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { render, useApp, useInput } from "ink";
+import { createElement, useEffect, useState } from "react";
+import { stateDirName } from "../../graph/graph.js";
+import { Journal, parseRunId } from "../../run/journal.js";
+import { deriveRunCockpitData, RunCockpitFrame } from "./run-cockpit.js";
+import { applyFilterInput, dispatchRunKey, initialRunInteractionState, SURFACE_KEY_BINDINGS, } from "./keys.js";
+// ponytail: fixed 2s re-derive cadence, matching `status --watch`; promote to a
+// config knob only if an operator asks.
+const REFRESH_MS = 2_000;
+/**
+ * THE engagement selection rule — stated once, here, so it can change in one
+ * place without touching the renderer or the command: an explicit engagement
+ * reference from the command line wins; the bare command opens the most
+ * recently started engagement that has a readable journal.
+ */
+export function selectEngagementRunId(cwd, explicit) {
+    if (explicit !== undefined)
+        return parseRunId(explicit);
+    return Journal.latestRunId(cwd, { withJournal: true });
+}
+/**
+ * The journal bytes of a real engagement — never a committed capture. A read
+ * failure throws: the caller refuses rather than drawing from nothing.
+ */
+export function loadEngagementSource(cwd, runId) {
+    const id = parseRunId(runId);
+    const path = join(cwd, stateDirName(cwd), "runs", id, "journal.jsonl");
+    const raw = readFileSync(path, "utf8");
+    return { fileName: `${id}.journal.jsonl`, raw };
+}
+// The same s/m/h age vocabulary `status` speaks (status.ts fmtAge).
+export function formatEventAge(ageMs) {
+    const safe = Math.max(0, ageMs);
+    if (safe < 90_000)
+        return `${Math.floor(safe / 1_000)}s`;
+    if (safe < 5_400_000)
+        return `${Math.floor(safe / 60_000)}m`;
+    return `${Math.floor(safe / 3_600_000)}h`;
+}
+function lastEventMs(raw) {
+    const lines = raw.split("\n");
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index].trim();
+        if (!line)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const ms = typeof parsed.ts === "string" ? Date.parse(parsed.ts) : NaN;
+            if (Number.isFinite(ms))
+                return ms;
+        }
+        catch {
+            // a torn trailing line does not hide the event written before it
+        }
+    }
+    return undefined;
+}
+/**
+ * Live derivation over a real engagement's journal bytes. The header's
+ * elapsed field additionally states how long ago the engagement's last event
+ * arrived, so an engagement that has stopped moving reads as stale rather
+ * than as current. Throws on unreadable bytes (empty capture, no run-start) —
+ * the caller refuses instead of rendering a plausible surface from nothing.
+ */
+export function deriveLiveRunCockpitData(source, binaryVersion, now = Date.now) {
+    const data = deriveRunCockpitData(source, binaryVersion);
+    const lastMs = lastEventMs(source.raw);
+    const staleness = lastMs === undefined
+        ? "last event unknown"
+        : `last event ${formatEventAge(now() - lastMs)} ago`;
+    return { ...data, elapsed: `${data.elapsed} · ${staleness}` };
+}
+function LiveApp({ cwd, runId, binaryVersion, columns, rows, refreshMs, now, }) {
+    const { exit } = useApp();
+    const [data, setData] = useState(() => deriveLiveRunCockpitData(loadEngagementSource(cwd, runId), binaryVersion, now));
+    const [interaction, setInteraction] = useState(initialRunInteractionState);
+    useEffect(() => {
+        const timer = setInterval(() => {
+            try {
+                setData(deriveLiveRunCockpitData(loadEngagementSource(cwd, runId), binaryVersion, now));
+            }
+            catch {
+                // a torn read mid-append keeps the last good frame rather than blanking the surface
+            }
+        }, refreshMs);
+        return () => clearInterval(timer);
+    }, [cwd, runId, binaryVersion, refreshMs, now]);
+    useInput((input, key) => {
+        if (key.ctrl && input === "c") {
+            exit();
+            return;
+        }
+        // While the / prompt is open it owns the keyboard: characters grow the
+        // query and no advertised binding fires.
+        if (interaction.filterPrompt) {
+            const prompted = applyFilterInput({ input, key }, interaction);
+            if (prompted !== undefined)
+                setInteraction(prompted);
+            return;
+        }
+        const next = dispatchRunKey({ input, key }, interaction, SURFACE_KEY_BINDINGS.run);
+        if (next === undefined)
+            return;
+        setInteraction(next);
+        if (next.quit)
+            exit();
+    });
+    return createElement(RunCockpitFrame, { data, columns, rows, interaction });
+}
+export async function runLiveCockpit({ input, output, cwd, runId, binaryVersion, refreshMs = REFRESH_MS, now = Date.now, }) {
+    const columns = output.columns ?? 80;
+    const rows = output.rows ?? 24;
+    const app = render(createElement(LiveApp, {
+        cwd,
+        runId,
+        binaryVersion,
+        columns,
+        rows,
+        refreshMs,
+        now,
+    }), {
+        stdin: input,
+        stdout: output,
+        exitOnCtrlC: false,
+        patchConsole: false,
+    });
+    try {
+        await app.waitUntilExit();
+    }
+    finally {
+        app.unmount();
+    }
+}

package/dist/tui/cockpit/run-cockpit.d.ts

@@ -0,0 +1,26 @@
+import { type ReactElement } from "react";
+import type { RunCockpitData } from "./derive.js";
+import { type RunInteractionState } from "./keys.js";
+export { deriveRunCockpitData } from "./derive.js";
+export type { RunCockpitData } from "./derive.js";
+export { PANEL_CHROME_ROWS } from "./components.js";
+/**
+ * How many rows one line of body text occupies once the renderer wraps it into
+ * `columns`. This mirrors the renderer's own word wrap — greedy, and breaking a
+ * word that cannot fit on a line of its own — so a frame can charge a panel the
+ * rows it will really occupy instead of a hand-tuned constant.
+ */
+export declare function wrappedRows(text: string, columns: number): number;
+/** The rows a bordered panel occupies when its body wraps into `columns`. */
+export declare function panelRows(lines: readonly string[], columns: number): number;
+export declare function RunCockpitFrame({ data, columns, rows, interaction, }: {
+    data: RunCockpitData;
+    columns: number;
+    rows?: number;
+    /**
+     * The run surface's interaction state. Omitted — or at its initial value —
+     * the frame is byte-identical to the pinned appearance; every transition a
+     * binding makes is drawn from it.
+     */
+    interaction?: RunInteractionState;
+}): ReactElement;