tickmarkr 1.80.0 → 1.83.0

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

@@ -72,5 +72,167 @@ export interface PlainCockpitLayout {
     arrangement: "plain";
 }
 export type CockpitLayout = FrameCockpitLayout | PlainCockpitLayout;
+export interface MeasuredSize {
+    columns: number;
+    rows: number;
+}
+/** The five sidebar views, in jump-key order (1–5). */
+export declare const FRAME_VIEWS: readonly ["run", "tasks", "gates", "journal", "fleet"];
+export type FrameView = (typeof FRAME_VIEWS)[number];
+export type FrameTab = "watch" | "setup";
+export interface FrameState {
+    /** Active top-level tab; SETUP turns the journal tail into PENDING WRITES. */
+    tab?: FrameTab;
+    /** A row's full detail is open in the body (sidebar and tail stay). */
+    detail?: boolean;
+    /** Header caption, pre-measured in terminal cells by the caller. */
+    captionCells?: number;
+}
+export declare const FRAME_WIDTH_FLOOR = 40;
+export declare const FRAME_HEIGHT_FLOOR = 14;
+export declare const SIDEBAR_COLUMN_FLOOR = 64;
+export declare const RAIL_COLUMNS = 15;
+export declare const STANDARD_TAIL_HEIGHT = 16;
+export declare const FULL_TAIL_HEIGHT = 24;
+export declare const TAIL_STANDARD_ROWS = 1;
+export declare const TAIL_FULL_ROWS = 3;
+/**
+ * The header's fixed parts beside the caption — brand and version, then the
+ * two tab labels — joined by the contracted gap. Composed from named parts so
+ * a header change moves the caption fit check with it; the suite pins the
+ * composed text so an unreviewed header change fails a test. Measured in
+ * display cells by the cockpit's width authority, never String length.
+ */
+export declare const FRAME_HEADER_PARTS: readonly ["tickmarkr 1.83.0", "[ WATCH ]", "SETUP"];
+export declare const FRAME_HEADER_GAP = "   ";
+export declare const HEADER_FIXED_CELLS: number;
+/** Every (columns, rows) pair the sweep holds the plan to. */
+export declare const FRAME_CONTRACT_DOMAIN: {
+    readonly minColumns: 40;
+    readonly maxColumns: 220;
+    readonly minRows: 14;
+    readonly maxRows: 50;
+};
+/** The fixed order in which the fit check surrenders regions, first to last. */
+export declare const FRAME_SURRENDER_ORDER: readonly ["caption", "tail"];
+export type SurrenderedRegionId = (typeof FRAME_SURRENDER_ORDER)[number];
+export interface FrameFit {
+    columns: number;
+    tailRows: number;
+    captionCells: number;
+}
+/**
+ * The fit predicate for each surrenderable region. The fit check walks
+ * FRAME_SURRENDER_ORDER and applies these predicates, so the constant is the
+ * ordering decision — not a comment about one.
+ */
+export declare const FRAME_SURRENDER_FIT: Readonly<Record<SurrenderedRegionId, (fit: FrameFit) => boolean>>;
+export type FrameRegionId = "header" | "rule" | "strip" | "rail" | "body" | "rule2" | "tail" | "status" | "keybar" | "caption";
+/** The vitals elements in block order, top first; a short rail surrenders from the top, so the meter is the last to go. */
+export declare const SIDEBAR_VITALS_ORDER: readonly ["tasks", "gates", "meter"];
+export type SidebarVitalsElement = (typeof SIDEBAR_VITALS_ORDER)[number];
+/** The rail rows at and above which the menu carries its label row. */
+export declare const SIDEBAR_MENU_LABEL_ROWS = 10;
+/** Rows one vitals element occupies in each mode: label plus sparkline, or one inline row. */
+export declare const SIDEBAR_VITALS_FULL_ELEMENT_ROWS = 2;
+export declare const SIDEBAR_VITALS_COMPACT_ELEMENT_ROWS = 1;
+export interface SidebarPlan {
+    /** Rows the menu block occupies at the rail's top: the five views, plus the label row when it fits. */
+    menuRows: number;
+    /**
+     * Blank rows between the last menu row and the first vitals row. Never zero
+     * while any vitals element draws — a short rail surrenders whole vitals
+     * elements rather than closing the gap.
+     */
+    gapRows: number;
+    /** Two rows per element, or one when the rail cannot pay for the full block. */
+    vitalsMode: "full" | "compact";
+    /** The vitals elements that draw, top to bottom, anchored to the rail's bottom. */
+    vitals: readonly SidebarVitalsElement[];
+}
+/**
+ * Compose the sidebar band for a rail of `railRows` rows — pure. The menu sits
+ * at the top; the vitals block sits at the bottom; the gap between them absorbs
+ * every surplus row and is never traded away: what remains after the menu and
+ * one gap row is the vitals budget, spent on the full two-row block when it
+ * fits whole, else on the one-row elements, surrendered from the top of the
+ * block with the meter surrendered last. An element draws whole or not at all.
+ */
+export declare function planSidebar(railRows: number): SidebarPlan;
+export interface FrameRegion {
+    id: FrameRegionId;
+    row: number;
+    rows: number;
+    column: number;
+    columns: number;
+}
+export interface FrameBandContent {
+    /** Body band: view rows, an open row detail, or the full-height journal tail. */
+    body: "rows" | "detail" | "journal";
+    /** Tail band: the compact journal tail, or PENDING WRITES on the SETUP tab. */
+    tail: "journal" | "pending-writes";
+}
+export interface PlannedFrame {
+    kind: "frame";
+    size: MeasuredSize;
+    view: FrameView;
+    tab: FrameTab;
+    band: "strip" | "sidebar";
+    /** What the view and state draw into each flexible band. */
+    content: FrameBandContent;
+    regions: readonly FrameRegion[];
+    /**
+     * Row bands, top to bottom; their spans tile the height exactly. A band
+     * map: the nested caption sub-region is deliberately excluded.
+     */
+    rowSpans: Readonly<Record<string, number>>;
+    /**
+     * Column bands of the body band; their spans tile the width exactly. A
+     * band map: the nested caption sub-region is deliberately excluded.
+     */
+    columnSpans: Readonly<Record<string, number>>;
+    /** The single surplus-absorbing element on each axis. */
+    flexible: {
+        readonly row: "body";
+        readonly column: "body";
+    };
+    /**
+     * The rail band's composition — menu, gap and vitals — planned when the
+     * band is the sidebar, null on the strip band. The renderer draws it
+     * unmodified.
+     */
+    sidebar: SidebarPlan | null;
+    /** Regions the fit check surrendered, in FRAME_SURRENDER_ORDER. */
+    surrendered: readonly SurrenderedRegionId[];
+}
+export interface PlainFallbackPlan {
+    kind: "plain";
+    size: MeasuredSize;
+}
+export type FramePlan = PlannedFrame | PlainFallbackPlan;
+/**
+ * Plan the frame for a measured size, a view and a state — pure: no
+ * rendering, no I/O, no read of the live terminal. Below either floor the
+ * plan is the plain fallback. Otherwise the frame is row bands that tile the
+ * height exactly — header, rule, the view strip (40–63 columns), the body
+ * band, a second rule, the journal tail surrendered whole by height tier,
+ * status, keybar — and, at ≥64 columns, column bands that tile the width
+ * exactly: the constant 15-column rail beside the body. The body is the sole
+ * flexible element on both axes. The view and state decide what the flexible
+ * bands draw (the Journal view is the full-height tail; SETUP turns the tail
+ * into PENDING WRITES; an open detail owns the body) without moving any
+ * span. The caption is a nested sub-region sharing row 0 with the header
+ * band, so cells on that row are owned by the header band and refinable by
+ * the caption; it is surrendered first when it does not fit beside the fixed
+ * header text, never squeezed to a zero or negative span. On the sidebar band
+ * the plan also owns the rail's composition: the menu at the top, the vitals
+ * anchored to the bottom, and at least one blank row between them whenever
+ * both draw — a too-short rail surrenders whole vitals elements from the top
+ * of the block, the meter last, rather than closing the gap. rowSpans and
+ * columnSpans are band maps: they deliberately exclude the nested caption,
+ * and column bands are reported for the body band only, so each map's spans
+ * sum to the full height and width respectively.
+ */
+export declare function planFrame(size: MeasuredSize, view?: FrameView, state?: FrameState): FramePlan;
 export declare function resolveCockpitLayout(columns: number, rows: number): CockpitLayout;
 export {};

package/dist/tui/cockpit/layout.js

@@ -1,3 +1,4 @@
+import { cellWidth } from "./width.js";
 export const COCKPIT_ROW_FLOOR = 14;
 export const COCKPIT_COLUMN_FLOOR = 40;
 export const FULL_JOURNAL_ROWS = 3;
@@ -50,6 +51,234 @@ function allocateRows(rows) {
     allocation.journal += available;
     return allocation;
 }
+/** The five sidebar views, in jump-key order (1–5). */
+export const FRAME_VIEWS = ["run", "tasks", "gates", "journal", "fleet"];
+export const FRAME_WIDTH_FLOOR = COCKPIT_COLUMN_FLOOR;
+export const FRAME_HEIGHT_FLOOR = COCKPIT_ROW_FLOOR;
+export const SIDEBAR_COLUMN_FLOOR = 64;
+export const RAIL_COLUMNS = 15;
+export const STANDARD_TAIL_HEIGHT = 16;
+export const FULL_TAIL_HEIGHT = 24;
+export const TAIL_STANDARD_ROWS = 1;
+export const TAIL_FULL_ROWS = FULL_JOURNAL_ROWS;
+/**
+ * The header's fixed parts beside the caption — brand and version, then the
+ * two tab labels — joined by the contracted gap. Composed from named parts so
+ * a header change moves the caption fit check with it; the suite pins the
+ * composed text so an unreviewed header change fails a test. Measured in
+ * display cells by the cockpit's width authority, never String length.
+ */
+export const FRAME_HEADER_PARTS = [
+    "tickmarkr 1.83.0",
+    "[ WATCH ]",
+    "SETUP",
+];
+export const FRAME_HEADER_GAP = "   ";
+export const HEADER_FIXED_CELLS = cellWidth(FRAME_HEADER_PARTS.join(FRAME_HEADER_GAP));
+/** Every (columns, rows) pair the sweep holds the plan to. */
+export const FRAME_CONTRACT_DOMAIN = {
+    minColumns: 40,
+    maxColumns: 220,
+    minRows: 14,
+    maxRows: 50,
+};
+/** The fixed order in which the fit check surrenders regions, first to last. */
+export const FRAME_SURRENDER_ORDER = ["caption", "tail"];
+/**
+ * The fit predicate for each surrenderable region. The fit check walks
+ * FRAME_SURRENDER_ORDER and applies these predicates, so the constant is the
+ * ordering decision — not a comment about one.
+ */
+export const FRAME_SURRENDER_FIT = {
+    caption: ({ captionCells, columns }) => captionCells >= 1 && captionCells <= columns - HEADER_FIXED_CELLS,
+    tail: ({ tailRows }) => tailRows > 0,
+};
+/* ------------------------------------------------------------------ */
+/* The sidebar band's composition: the menu at the rail's top, the     */
+/* vitals anchored to the rail's bottom, and at least one blank row    */
+/* between them whenever both draw. The plan owns this geometry; the   */
+/* band composition draws it unmodified.                               */
+/* ------------------------------------------------------------------ */
+/** The vitals elements in block order, top first; a short rail surrenders from the top, so the meter is the last to go. */
+export const SIDEBAR_VITALS_ORDER = ["tasks", "gates", "meter"];
+/** The rail rows at and above which the menu carries its label row. */
+export const SIDEBAR_MENU_LABEL_ROWS = 10;
+/** Rows one vitals element occupies in each mode: label plus sparkline, or one inline row. */
+export const SIDEBAR_VITALS_FULL_ELEMENT_ROWS = 2;
+export const SIDEBAR_VITALS_COMPACT_ELEMENT_ROWS = 1;
+/**
+ * Compose the sidebar band for a rail of `railRows` rows — pure. The menu sits
+ * at the top; the vitals block sits at the bottom; the gap between them absorbs
+ * every surplus row and is never traded away: what remains after the menu and
+ * one gap row is the vitals budget, spent on the full two-row block when it
+ * fits whole, else on the one-row elements, surrendered from the top of the
+ * block with the meter surrendered last. An element draws whole or not at all.
+ */
+export function planSidebar(railRows) {
+    const menuRows = railRows >= SIDEBAR_MENU_LABEL_ROWS
+        ? 1 + FRAME_VIEWS.length
+        : FRAME_VIEWS.length;
+    const fullRows = SIDEBAR_VITALS_ORDER.length * SIDEBAR_VITALS_FULL_ELEMENT_ROWS;
+    // The gap is funded before the vitals are: the budget is what remains after it.
+    const budget = railRows - menuRows - 1;
+    if (budget >= fullRows) {
+        return {
+            menuRows,
+            gapRows: railRows - menuRows - fullRows,
+            vitalsMode: "full",
+            vitals: SIDEBAR_VITALS_ORDER,
+        };
+    }
+    const kept = Math.max(0, Math.min(SIDEBAR_VITALS_ORDER.length, Math.floor(budget)));
+    return {
+        menuRows,
+        gapRows: kept > 0 ? railRows - menuRows - kept : 0,
+        vitalsMode: "compact",
+        vitals: SIDEBAR_VITALS_ORDER.slice(SIDEBAR_VITALS_ORDER.length - kept),
+    };
+}
+function tailRowsFor(rows) {
+    if (rows >= FULL_TAIL_HEIGHT)
+        return TAIL_FULL_ROWS;
+    if (rows >= STANDARD_TAIL_HEIGHT)
+        return TAIL_STANDARD_ROWS;
+    return 0;
+}
+/**
+ * Plan the frame for a measured size, a view and a state — pure: no
+ * rendering, no I/O, no read of the live terminal. Below either floor the
+ * plan is the plain fallback. Otherwise the frame is row bands that tile the
+ * height exactly — header, rule, the view strip (40–63 columns), the body
+ * band, a second rule, the journal tail surrendered whole by height tier,
+ * status, keybar — and, at ≥64 columns, column bands that tile the width
+ * exactly: the constant 15-column rail beside the body. The body is the sole
+ * flexible element on both axes. The view and state decide what the flexible
+ * bands draw (the Journal view is the full-height tail; SETUP turns the tail
+ * into PENDING WRITES; an open detail owns the body) without moving any
+ * span. The caption is a nested sub-region sharing row 0 with the header
+ * band, so cells on that row are owned by the header band and refinable by
+ * the caption; it is surrendered first when it does not fit beside the fixed
+ * header text, never squeezed to a zero or negative span. On the sidebar band
+ * the plan also owns the rail's composition: the menu at the top, the vitals
+ * anchored to the bottom, and at least one blank row between them whenever
+ * both draw — a too-short rail surrenders whole vitals elements from the top
+ * of the block, the meter last, rather than closing the gap. rowSpans and
+ * columnSpans are band maps: they deliberately exclude the nested caption,
+ * and column bands are reported for the body band only, so each map's spans
+ * sum to the full height and width respectively.
+ */
+export function planFrame(size, view = "tasks", state = {}) {
+    const columns = Math.floor(size.columns);
+    const rows = Math.floor(size.rows);
+    if (!Number.isFinite(columns) ||
+        !Number.isFinite(rows) ||
+        columns < FRAME_WIDTH_FLOOR ||
+        rows < FRAME_HEIGHT_FLOOR) {
+        return { kind: "plain", size: { columns, rows } };
+    }
+    const tab = state.tab ?? "watch";
+    const band = columns >= SIDEBAR_COLUMN_FLOOR ? "sidebar" : "strip";
+    const stripRows = band === "strip" ? 1 : 0;
+    const tailRows = tailRowsFor(rows);
+    // Fixed chrome is five rows: header, rule, a second rule below the body
+    // band, status and keybar.
+    const bodyRows = rows - (5 + stripRows + tailRows);
+    const fit = {
+        columns,
+        tailRows,
+        captionCells: state.captionCells ?? 0,
+    };
+    // The fit check walks the declared order; the constant is what orders the
+    // surrender decisions.
+    const surrendered = FRAME_SURRENDER_ORDER.filter((id) => !FRAME_SURRENDER_FIT[id](fit));
+    const captionFits = FRAME_SURRENDER_FIT.caption(fit);
+    const captionCells = fit.captionCells;
+    const regions = [];
+    let row = 0;
+    regions.push({ id: "header", row, rows: 1, column: 0, columns });
+    row += 1;
+    regions.push({ id: "rule", row, rows: 1, column: 0, columns });
+    row += 1;
+    if (stripRows > 0) {
+        regions.push({ id: "strip", row, rows: stripRows, column: 0, columns });
+        row += stripRows;
+    }
+    const bodyRow = row;
+    row += bodyRows;
+    regions.push({ id: "rule2", row, rows: 1, column: 0, columns });
+    row += 1;
+    if (tailRows > 0) {
+        regions.push({ id: "tail", row, rows: tailRows, column: 0, columns });
+        row += tailRows;
+    }
+    regions.push({ id: "status", row, rows: 1, column: 0, columns });
+    row += 1;
+    regions.push({ id: "keybar", row, rows: 1, column: 0, columns });
+    row += 1;
+    if (band === "sidebar") {
+        regions.push({
+            id: "rail",
+            row: bodyRow,
+            rows: bodyRows,
+            column: 0,
+            columns: RAIL_COLUMNS,
+        });
+        regions.push({
+            id: "body",
+            row: bodyRow,
+            rows: bodyRows,
+            column: RAIL_COLUMNS,
+            columns: columns - RAIL_COLUMNS,
+        });
+    }
+    else {
+        regions.push({
+            id: "body",
+            row: bodyRow,
+            rows: bodyRows,
+            column: 0,
+            columns,
+        });
+    }
+    if (captionFits) {
+        regions.push({
+            id: "caption",
+            row: 0,
+            rows: 1,
+            column: columns - captionCells,
+            columns: captionCells,
+        });
+    }
+    const rowSpans = { header: 1, rule: 1 };
+    if (stripRows > 0)
+        rowSpans.strip = stripRows;
+    rowSpans.body = bodyRows;
+    rowSpans.rule2 = 1;
+    if (tailRows > 0)
+        rowSpans.tail = tailRows;
+    rowSpans.status = 1;
+    rowSpans.keybar = 1;
+    const columnSpans = band === "sidebar"
+        ? { rail: RAIL_COLUMNS, body: columns - RAIL_COLUMNS }
+        : { body: columns };
+    return {
+        kind: "frame",
+        size: { columns, rows },
+        view,
+        tab,
+        band,
+        content: {
+            body: view === "journal" ? "journal" : state.detail ? "detail" : "rows",
+            tail: tab === "setup" ? "pending-writes" : "journal",
+        },
+        regions,
+        rowSpans,
+        columnSpans,
+        flexible: { row: "body", column: "body" },
+        sidebar: band === "sidebar" ? planSidebar(bodyRows) : null,
+        surrendered,
+    };
+}
 export function resolveCockpitLayout(columns, rows) {
     if (!Number.isFinite(columns) ||
         !Number.isFinite(rows) ||

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

@@ -0,0 +1,80 @@
+import type { CockpitGraph, RunCockpitData, RunCockpitSource } from "./derive.js";
+import { type RunInteractionState, type RunKeyEvent } from "./keys.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;
+/**
+ * The compiled graph, when the repository has one. It lends the tasks view its
+ * identities and nothing else, so an engagement with no compiled graph at all
+ * still draws every task the journal mentions rather than refusing to open.
+ *
+ * Absence is the only fallback. A graph that exists and cannot be read, parsed
+ * or validated is a fault, and swallowing it would quietly demote the surface:
+ * every task the graph alone knows about would vanish from the rows, and a
+ * selection standing on one of them would be cleared as if the engagement had
+ * dropped it. So it throws, and the caller keeps its last good frame instead.
+ */
+export declare function loadEngagementGraph(cwd: string): CockpitGraph | undefined;
+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, graph?: CockpitGraph): RunCockpitData;
+/**
+ * Repair the interaction state against the rows a refreshed view now owns.
+ * Selection is held by the row's source identity, so it survives rows landing
+ * above it and is dropped — never slid onto whoever inherited its index —
+ * when the refreshed engagement no longer carries it.
+ */
+export declare function reconcileLiveRunInteraction(interaction: RunInteractionState, data: RunCockpitData): RunInteractionState;
+/**
+ * The rows the live surface hands its keys — the engagement's own identities,
+ * minus the journal's, which are never selectable in either tab. This is the
+ * one place rows enter the dispatcher, so no key can reach a journal row.
+ */
+export declare function liveRunViewRowIds(interaction: RunInteractionState, data: RunCockpitData): readonly string[];
+export type LiveCockpitSurface = {
+    readonly data: RunCockpitData;
+    readonly interaction: RunInteractionState;
+    /** The tab waiting behind the drawn one, holding the state it was left in. */
+    readonly stashed: RunInteractionState;
+};
+/**
+ * The live owner's delivery boundary. A refresh is the real journal read and
+ * state transition used by the timer; snapshot exposes the state subsequent
+ * deliveries will read. Batch keeps applying transitions synchronously while
+ * deferring only the redraw notification, so multiple sources can be ordered
+ * in one turn without substituting a helper state machine for the live one.
+ */
+export type LiveCockpitDelivery = {
+    readonly snapshot: () => LiveCockpitSurface;
+    readonly refresh: () => boolean;
+    readonly key: (event: RunKeyEvent, columns?: number) => boolean;
+    readonly batch: <Result>(deliver: () => Result) => Result;
+};
+export declare function runLiveCockpit({ input, output, cwd, runId, binaryVersion, refreshMs, now, debug, onDelivery, }: {
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+    cwd: string;
+    runId: string;
+    binaryVersion: string;
+    refreshMs?: number;
+    now?: () => number;
+    /** Emit complete frames for diagnostics instead of terminal diffs. */
+    debug?: boolean;
+    /** Observe and control the production delivery boundary. */
+    onDelivery?: (delivery: LiveCockpitDelivery) => void;
+}): Promise<void>;