@acpus/tui 0.1.0

package/dist/controls.js

@@ -0,0 +1,68 @@
+/**
+ * Control actions — map keypresses to supervisor control calls, guarding
+ * client-side by state so we only attempt actions that can succeed.
+ */
+/** Whether a node-addressed action is applicable to a node in the given state. */
+export function canApply(action, state) {
+    switch (action) {
+        case "retry":
+            return state === "failed";
+        case "approve":
+        case "reject":
+            return state === "awaiting";
+        default:
+            return false;
+    }
+}
+/** Whether a Run-level action is applicable to a Run in the given status. */
+export function canApplyRun(action, status) {
+    switch (action) {
+        case "pause":
+            return status === "running";
+        case "cancel":
+            return status === "running" || status === "paused";
+        case "resume":
+            return status === "paused";
+        case "retry":
+            return status === "failed";
+        // approve/reject are node-level only; there is no Run-level decision.
+        case "approve":
+        case "reject":
+            return false;
+        default:
+            return false;
+    }
+}
+/** Apply a node-addressed action. */
+export async function applyControl(client, action, runId, nodeKey) {
+    switch (action) {
+        case "retry":
+            return client.retryNode(runId, nodeKey);
+        case "approve":
+            return client.signalApproval(runId, nodeKey, true);
+        case "reject":
+            return client.signalApproval(runId, nodeKey, false);
+        case "pause":
+        case "resume":
+        case "cancel":
+            throw new Error(`'${action}' is not a Node-level action`);
+    }
+}
+/** Apply a Run-level control action. */
+export async function applyRunControl(client, action, runId) {
+    switch (action) {
+        case "pause":
+            return client.pauseRun(runId);
+        case "resume":
+            return client.resumeRun(runId);
+        case "cancel":
+            return client.cancelRun(runId);
+        case "retry":
+            return client.retryRun(runId);
+        case "approve":
+        case "reject":
+            // Guarded out by canApplyRun; approve/reject are node-level only.
+            throw new Error(`'${action}' is not a Run-level action`);
+    }
+}
+//# sourceMappingURL=controls.js.map

package/dist/controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controls.js","sourceRoot":"","sources":["../src/controls.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,kFAAkF;AAClF,MAAM,UAAU,QAAQ,CAAC,MAAqB,EAAE,KAA4B;IAC1E,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO;YACV,OAAO,KAAK,KAAK,QAAQ,CAAC;QAC5B,KAAK,SAAS,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,KAAK,KAAK,UAAU,CAAC;QAC9B;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,MAAqB,EAAE,MAA6B;IAC9E,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO;YACV,OAAO,MAAM,KAAK,SAAS,CAAC;QAC9B,KAAK,QAAQ;YACX,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,QAAQ,CAAC;QACrD,KAAK,QAAQ;YACX,OAAO,MAAM,KAAK,QAAQ,CAAC;QAC7B,KAAK,OAAO;YACV,OAAO,MAAM,KAAK,QAAQ,CAAC;QAC7B,sEAAsE;QACtE,KAAK,SAAS,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,KAAK,CAAC;QACf;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED,qCAAqC;AACrC,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAA2B,EAC3B,MAAqB,EACrB,KAAa,EACb,OAAe;IAEf,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO;YACV,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC1C,KAAK,SAAS;YACZ,OAAO,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACrD,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QACtD,KAAK,OAAO,CAAC;QACb,KAAK,QAAQ,CAAC;QACd,KAAK,QAAQ;YACX,MAAM,IAAI,KAAK,CAAC,IAAI,MAAM,8BAA8B,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED,wCAAwC;AACxC,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAA2B,EAC3B,MAAqB,EACrB,KAAa;IAEb,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO;YACV,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAChC,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACjC,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACjC,KAAK,OAAO;YACV,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAChC,KAAK,SAAS,CAAC;QACf,KAAK,QAAQ;YACX,kEAAkE;YAClE,MAAM,IAAI,KAAK,CAAC,IAAI,MAAM,6BAA6B,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export interface RunTuiOptions {
+    /** Run to visualize. If omitted, a picker is shown. */
+    runId?: string;
+    /** Supervisor endpoint URL (required). */
+    endpoint: string;
+}
+/** Launch the TUI. Resolves when the user exits. */
+export declare function runTui(options: RunTuiOptions): Promise<void>;
+/** Clear the TUI frame after exit without touching non-interactive output. */
+export declare function clearTerminalViewport(stdout?: NodeJS.WriteStream): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAMA,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAUD,oDAAoD;AACpD,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CASlE;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,MAAM,CAAC,WAA4B,GAAG,OAAO,CAI1F"}

package/dist/index.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState } from "react";
+import { render } from "ink";
+import { RunSupervisorClient } from "@acpus/runtime";
+import { App } from "./components/App.js";
+import { RunPicker } from "./components/RunPicker.js";
+function Root({ client, initialRunId }) {
+    const [runId, setRunId] = useState(initialRunId);
+    if (!runId) {
+        return _jsx(RunPicker, { client: client, onSelect: setRunId });
+    }
+    return _jsx(App, { client: client, runId: runId });
+}
+/** Launch the TUI. Resolves when the user exits. */
+export async function runTui(options) {
+    const client = new RunSupervisorClient(options.endpoint);
+    client.clientKind = "visualize";
+    const { waitUntilExit } = render(_jsx(Root, { client: client, initialRunId: options.runId }));
+    try {
+        await waitUntilExit();
+    }
+    finally {
+        clearTerminalViewport();
+    }
+}
+/** Clear the TUI frame after exit without touching non-interactive output. */
+export function clearTerminalViewport(stdout = process.stdout) {
+    if (!stdout.isTTY)
+        return false;
+    stdout.write("\x1b[2J\x1b[H");
+    return true;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":";AAAA,OAAc,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAStD,SAAS,IAAI,CAAC,EAAE,MAAM,EAAE,YAAY,EAA0D;IAC5F,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAqB,YAAY,CAAC,CAAC;IACrE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,KAAC,SAAS,IAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAI,CAAC;IAC3D,CAAC;IACD,OAAO,KAAC,GAAG,IAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAI,CAAC;AAC/C,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAsB;IACjD,MAAM,MAAM,GAAG,IAAI,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,CAAC,UAAU,GAAG,WAAW,CAAC;IAChC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAAC,KAAC,IAAI,IAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,KAAK,GAAI,CAAC,CAAC;IACxF,IAAI,CAAC;QACH,MAAM,aAAa,EAAE,CAAC;IACxB,CAAC;YAAS,CAAC;QACT,qBAAqB,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,SAA6B,OAAO,CAAC,MAAM;IAC/E,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAChC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/model.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Model overlay — pure functions that build a render tree by walking the frozen
+ * IR (static structure) and attaching the live NodeExecutionState instances for
+ * each node.
+ *
+ * The supervisor returns a flat NodeExecutionState[] keyed by node keys like
+ * "workflow/mapped/item:file-a/lane:0/round:2". A single IR node id can map to
+ * many runtime instances (fanout lanes, loop rounds, parallel branches). Rather
+ * than grouping every IR node's instances globally (which mixes lanes from
+ * different fanout items together and makes every descendant appear "(×N)"),
+ * we rebuild a *real* hierarchical tree keyed by the dynamic dimensions encoded
+ * in each node key.
+ *
+ * Each composite introduces a distinct dynamic dimension:
+ *   - fanout → item + lane   (one lane per item)
+ *   - parallel → branch      (children are distinct IR ids → single instance per lane)
+ *   - loop → round
+ *
+ * So fanout/loop "expand" into one group row per lane/round, and every node
+ * underneath a group is scoped to that lane/round → it resolves to a single
+ * instance, no spurious "(×N)". The "(×N)" count therefore lives only on the
+ * fanout/loop container that actually fans.
+ */
+import type { AcpusIr, IrNode, IrNodeKind } from "@acpus/core";
+import type { NodeExecutionState, NodeState } from "@acpus/runtime";
+/** A dynamic dimension type encoded in node keys. */
+export type Dim = "item" | "lane" | "branch" | "round";
+/** A node key split into its static path segments and dynamic dimensions. */
+export interface ParsedKey {
+    path: string[];
+    dims: Map<Dim, string>;
+}
+/**
+ * Parse a node key into static path segments and dynamic dimensions.
+ * Mirrors runtime/src/keys.ts: dimensions are `type:value` segments appended at
+ * the tail in a fixed order. Last-write-wins for repeated dims (documents the
+ * nested same-kind composite limitation).
+ */
+export declare function parseNodeKey(key: string): ParsedKey;
+/** A node in the render tree: an IR node (or a synthetic lane/round group). */
+export interface RenderNode {
+    /** "ir" = a real IR node; "group" = a synthetic fanout-lane/loop-round group. */
+    type: "ir" | "group";
+    /** The IR node. Group rows carry their PARENT composite IR node. */
+    irNode: IrNode;
+    /** Live runtime states scoped to this node's lane/round. Usually 0 or 1. */
+    instances: NodeExecutionState[];
+    /** Child render nodes. */
+    children: RenderNode[];
+    /** For switch branches: the case label and predicate. */
+    branchLabel?: string;
+    branchWhen?: string;
+    /** Composite summary derived from metadata (e.g. "over=files join=quorum"). */
+    summary?: string;
+    /** Depth in the tree (root = 0). */
+    depth: number;
+    /** Set only on a fanout/loop container → drives the "(×N)" label. */
+    fannedCount?: number;
+    /** Set only on a synthetic group row. */
+    groupDim?: Dim;
+    groupValue?: string;
+    groupLabel?: string;
+    /** For lane group rows: the fanout item value (shown in DETAILS). */
+    groupItem?: string;
+}
+/** Build the full render tree for a run. */
+export declare function buildRenderTree(ir: AcpusIr, states: NodeExecutionState[]): RenderNode;
+/** Group runtime states by their original IR node id, each list sorted by key. */
+export declare function indexByNodeId(states: NodeExecutionState[]): Map<string, NodeExecutionState[]>;
+/** Flatten the render tree into a linear, display-ordered list. */
+export declare function flatten(root: RenderNode): RenderNode[];
+/**
+ * A single selectable/displayable row.
+ */
+export interface DisplayRow {
+    /** Stable key for React + selection. */
+    rowKey: string;
+    irNode: IrNode;
+    /** Indentation depth for rendering. */
+    depth: number;
+    /** The runtime instance this row represents, if any. */
+    instance?: NodeExecutionState;
+    /** Representative state for this row (single instance or aggregate). */
+    state?: NodeState;
+    /** Display label (own node id, group label, or branch label). */
+    label: string;
+    /** True if this is a container header row (groups children). */
+    isHeader: boolean;
+    /** node key usable for control actions, if known. */
+    nodeKey?: string;
+    /** Composite summary (over/join/until ...). */
+    summary?: string;
+    branchLabel?: string;
+    branchWhen?: string;
+    /** Set on synthetic fanout-lane/loop-round group rows. */
+    groupDim?: Dim;
+    groupValue?: string;
+    /** For lane group rows: the fanout item value (shown in DETAILS). */
+    groupItem?: string;
+    /**
+     * Tree guide-line prefix split into colorable segments (one per column).
+     * Each segment is 3 chars (e.g. "│  ", "   ", "├─ ", "└─ "). `ownerKind`
+     * marks the container kind that owns the column, so guide-line colors match
+     * the node-kind legend.
+     */
+    treeSegments: TreeSegment[];
+}
+/** One colorable column of a tree guide-line prefix. */
+export interface TreeSegment {
+    text: string;
+    /** The node kind whose child column this segment belongs to. */
+    ownerKind: IrNodeKind;
+}
+/** Build the display-ordered, selectable rows for the whole tree. */
+export declare function buildRows(root: RenderNode): DisplayRow[];
+/**
+ * The representative state for a node: the single instance if there is one,
+ * else the aggregate state across this subtree's instances (failed if any
+ * failed, completed only if all completed, etc.).
+ */
+export declare function aggregateState(node: RenderNode): NodeState | undefined;
+/** Count every distinct runtime instance by state, for the progress/legend panes. */
+export declare function countByState(root: RenderNode): Record<NodeState, number> & {
+    total: number;
+};
+/** Format a duration between two ISO timestamps as HH:MM:SS. */
+export declare function formatDuration(startedAt?: string, completedAt?: string, freezeAt?: string | number): string;
+/** Format a millisecond span as HH:MM:SS. */
+export declare function formatElapsed(ms: number): string;
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

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