tickmarkr 1.80.0 → 1.83.0

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

@@ -1,7 +1,9 @@
 import { type ReactElement } from "react";
+import { Journal } from "../../run/journal.js";
 import { type TickmarkrConfig } from "../../config/config.js";
 import { type ComponentState, type JournalRow } from "./components.js";
 import type { DemoCaptures } from "./demo.js";
+import { type RunKeyEvent, type SetupInteractionState, type SetupKeyBinding } from "./keys.js";
 export type SetupCockpitData = {
     readonly binaryVersion: string;
     readonly harnesses: readonly {
@@ -34,8 +36,154 @@ export declare function deriveSetupCockpitData(captures: DemoCaptures, binaryVer
  * describes the fleet.
  */
 export declare const SETUP_DETAIL_ORDER: readonly ["detected", "consultsAndReviewers", "overlayDiff", "fleetAndGates"];
-export declare function SetupCockpitFrame({ data, columns, rows, }: {
+export declare function SetupCockpitFrame({ data, columns, rows, interaction, bindings, }: {
     data: SetupCockpitData;
     columns: number;
     rows?: number;
+    interaction?: SetupInteractionState;
+    bindings?: readonly SetupKeyBinding[];
 }): ReactElement;
+/**
+ * One parked task awaiting a human decision, derived from the journal alone.
+ * The graph is never consulted: a recompile can never make a parked task read
+ * as anything but parked on this surface.
+ */
+export type ParkedDecision = {
+    readonly taskId: string;
+    /** The daemon-recorded park kind (task-human data.kind), never inferred prose. */
+    readonly kind: string;
+    readonly reason: string | undefined;
+    /** UTC HH:MM:SS sliced from the newest task-human event's ISO ts, or "unknown". */
+    readonly parkedAt: string;
+    /** Count of recorded task-dispatch events — never max(attempt)+1. */
+    readonly attempts: number;
+    /**
+     * The newest failed gate-result before the newest task-human, derived with
+     * the same rule the production approve command applies. It decides what the
+     * confirm inset may promise: uphold exists only when this is "review", and a
+     * gate-fail approve records this gate as satisfied.
+     */
+    readonly failedGate: string | undefined;
+    /**
+     * A park that is permanent by design: an id the spec retains only so the
+     * engagement can resume, gated so it never dispatches. Nothing releases it,
+     * so it is drawn read-only and neither verb is offered on it.
+     */
+    readonly tombstone: boolean;
+};
+/** The parks a verb can release — the rows the surface draws live verbs on. */
+export declare function actionableDecisions(decisions: readonly ParkedDecision[]): readonly ParkedDecision[];
+/**
+ * The decisions section's rows: one per task the journal's own status replay
+ * leaves parked on a human, in the order the journal first named them. The
+ * replay is the production one (`Journal.replayStatuses`) so this surface and
+ * `tickmarkr status` can never disagree about what is parked.
+ */
+export declare function deriveParkedDecisions(journal: Journal): readonly ParkedDecision[];
+/** The two decisions a parked task offers — the production command's two verbs. */
+export type SetupDecisionVerb = "approve" | "uphold";
+/** A decision the operator has named but not yet confirmed. */
+export type SetupDecisionCommand = {
+    readonly verb: SetupDecisionVerb;
+    readonly taskId: string;
+};
+/** What the journal file gained this session — one entry per confirmed write. */
+export type SetupDecisionWrite = {
+    readonly taskId: string;
+    readonly verb: SetupDecisionVerb;
+    /** The release marker read back from the recorded task-approved event. */
+    readonly release: string | undefined;
+    readonly by: string;
+};
+/**
+ * The observable state of the decisions surface. Every field is drawn, so a
+ * state the surface cannot show is not expressible: the confirm inset is
+ * `confirming`, the verbatim command output is `notice`, and the pending
+ * writes region is `writes`.
+ */
+export type SetupDecisionsSession = {
+    readonly selection: number;
+    readonly confirming: SetupDecisionCommand | null;
+    readonly writes: readonly SetupDecisionWrite[];
+    readonly notice: string | null;
+};
+export declare function initialSetupDecisionsSession(): SetupDecisionsSession;
+export type SetupDecisionsKeyResult = {
+    readonly session: SetupDecisionsSession;
+    /** Present only when the confirm key landed — the one moment a write may happen. */
+    readonly command?: SetupDecisionCommand;
+    readonly quit?: boolean;
+};
+/**
+ * Uphold exists only where the production command honours it: the newest
+ * failed gate before the park is the review gate. Everywhere else the key is
+ * inert and the keybar does not advertise it — the surface never promises a
+ * decision the command must refuse.
+ */
+export declare function upholdAvailable(decision: ParkedDecision): boolean;
+/**
+ * The decisions surface's whole key grammar: ↑↓ move, a approve, u uphold,
+ * y confirm, n/Esc cancel, q quit. The reducer never writes — it can only
+ * *name* a command, and only on the confirm key, so a write the operator did
+ * not predict cannot happen. a/u are inert when nothing actionable is parked,
+ * and u is inert on a park the command would refuse, matching the keybar, which
+ * then does not advertise them. Tombstone parks sit outside the grammar: the
+ * pointer never reaches one, so no key can name a decision on it.
+ */
+export declare function applySetupDecisionsKey(session: SetupDecisionsSession, event: RunKeyEvent, parked: readonly ParkedDecision[]): SetupDecisionsKeyResult;
+export type SetupDecisionOutcome = {
+    readonly ok: true;
+    readonly command: SetupDecisionCommand;
+    /** The exact string the production command returned. */
+    readonly message: string;
+    readonly write: SetupDecisionWrite;
+} | {
+    readonly ok: false;
+    readonly command: SetupDecisionCommand;
+    /** The exact string the production command threw. */
+    readonly refusal: string;
+};
+/**
+ * THE write. It calls the production `approve` command — validation, fail-closed
+ * refusals and the journal append are inherited, never re-implemented — and then
+ * reads the file back so the session records the release the journal actually
+ * gained. A refusal is the command's own message, verbatim, and appends nothing.
+ */
+export declare function executeSetupDecision(command: SetupDecisionCommand, { cwd, runId, by }: {
+    cwd: string;
+    runId: string;
+    by: string;
+}): Promise<SetupDecisionOutcome>;
+/** Fold an executed command's outcome into the session the surface draws. */
+export declare function recordSetupDecisionOutcome(session: SetupDecisionsSession, outcome: SetupDecisionOutcome): SetupDecisionsSession;
+/**
+ * The confirm inset's lines: the task, the actor, the effect and the file,
+ * stated before the single key that can write.
+ */
+export declare function setupDecisionConfirmLines(command: SetupDecisionCommand, decision: ParkedDecision | undefined, actor: string, journalFile: string): readonly string[];
+/**
+ * The decisions surface. Every row it draws — decisions, the confirm inset,
+ * the pending writes region — is measured and clipped through the width
+ * module alone (`fitCells`), so a task name carrying a ZWJ grapheme can
+ * neither overflow its row nor be cut mid-cluster. The one unclipped element
+ * is `notice`: the production command's own words, verbatim.
+ */
+export declare function SetupDecisionsSurface({ decisions, session, columns, actor, journalFile, }: {
+    decisions: readonly ParkedDecision[];
+    session: SetupDecisionsSession;
+    columns: number;
+    actor: string;
+    journalFile: string;
+}): ReactElement;
+/**
+ * The setup decisions surface on a live engagement. This is the only cockpit
+ * surface that writes, and it writes exactly one way: a confirmed approve or
+ * uphold through the production command path.
+ */
+export declare function runSetupDecisionsCockpit({ input, output, cwd, runId, actor, }: {
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+    cwd: string;
+    runId: string;
+    actor?: string;
+}): Promise<void>;