@kal-elsam/kairo-runtime 0.16.0 → 0.18.0

package/src/global/cockpit/rows.js

@@ -0,0 +1,148 @@
+// Pure, dependency-free logic for the `kairo start` interactive cockpit.
+// Kept separate from the pi-tui rendering so it can be unit tested without a terminal.
+
+/**
+ * @typedef {object} CockpitRow
+ * @property {string} taskId
+ * @property {string|null} taskText - the real task description, never the noisy taskId slug
+ * @property {string} planState - one of the PLAN_STATES values (draft/awaiting_approval/approved/rejected/failed)
+ * @property {string} approval - "approved" | "rejected" | "not_decided"
+ * @property {string} execState - "not_started" | "reserved" | "running" | "done" | "failed" | ...
+ * @property {boolean} execActive
+ * @property {string|null} execMessage
+ * @property {string|null} planProvider - who planned it (e.g. "codex"); real, never inferred
+ * @property {string|null} planModel - explicit model if one was requested; null means provider default
+ * @property {string|null} execProvider - who is/was executing it (e.g. "claude")
+ */
+
+/**
+ * Maps a conversation-service snapshot's timeline into display rows.
+ * @param {Array<object>} timeline - conversation snapshot().timeline entries
+ * @returns {CockpitRow[]}
+ */
+export function buildTaskRows(timeline) {
+  if (!Array.isArray(timeline)) return [];
+  return timeline.map((plan) => ({
+    taskId: plan.taskId,
+    taskText: plan.taskText ?? null,
+    planState: plan.state,
+    approval: plan.approval ?? "not_decided",
+    execState: plan.execution?.state ?? "not_started",
+    execActive: plan.execution?.active === true,
+    execMessage: plan.execution?.message ?? null,
+    planProvider: plan.provider ?? null,
+    planModel: plan.model ?? null,
+    execProvider: plan.execution?.provider ?? null
+  }));
+}
+
+/**
+ * Derives an honest lifecycle phase from real plan/execution state — never
+ * a phase Kairo can't actually distinguish today (e.g. no "REVIEWING" step
+ * exists in the data model, so it's not offered).
+ * @param {CockpitRow|null} row
+ * @returns {"IDLE"|"WAITING APPROVAL"|"REJECTED"|"READY"|"IMPLEMENTING"|"COMPLETE"|"ERROR"|"PLANNING"}
+ */
+export function derivePhase(row) {
+  if (!row) return "IDLE";
+  if (row.execActive) return "IMPLEMENTING";
+  if (row.execState === "done") return "COMPLETE";
+  if (row.execState === "failed" || row.planState === "failed") return "ERROR";
+  if (row.planState === "rejected") return "REJECTED";
+  if (row.planState === "approved") return "READY";
+  if (row.planState === "awaiting_approval") return "WAITING APPROVAL";
+  return "PLANNING";
+}
+
+/**
+ * Clamps a selection index into the valid range for the given rows array.
+ * @param {number} index
+ * @param {number} length
+ * @returns {number}
+ */
+export function clampSelection(index, length) {
+  if (length <= 0) return 0;
+  if (index < 0) return 0;
+  if (index > length - 1) return length - 1;
+  return index;
+}
+
+/**
+ * Formats a single row as one display line.
+ * @param {CockpitRow} row
+ * @param {{selected?: boolean}} [options]
+ * @returns {string}
+ */
+export function formatRowText(row, { selected = false } = {}) {
+  const marker = selected ? ">" : " ";
+  const planState = String(row.planState ?? "").padEnd(18);
+  const execState = String(row.execState ?? "").padEnd(12);
+  return `${marker} ${planState} ${execState} ${row.taskId}`;
+}
+
+/**
+ * Returns the header line matching formatRowText's column layout.
+ * @returns {string}
+ */
+export function headerLine() {
+  return `  ${"PLAN".padEnd(18)} ${"EXECUTION".padEnd(12)} TASK`;
+}
+
+/**
+ * Maps a row's plan/execution state to a card tone (see ./card.js CARD_TONE)
+ * so its rendered line's left rail reflects its state at a glance.
+ * @param {CockpitRow} row
+ * @returns {"info"|"success"|"warning"|"error"}
+ */
+export function rowTone(row) {
+  if (row.execState === "failed" || row.planState === "rejected") return "error";
+  if (row.execActive || row.execState === "running" || row.planState === "awaiting_approval") return "warning";
+  if (row.planState === "approved" || row.execState === "done") return "success";
+  return "info";
+}
+
+/**
+ * Returns whether a given action key is currently available for a row (or
+ * with no row selected). `mode` (the cockpit's WorkMode, when given) gates
+ * which actions the current mode allows advancing through — ASK is
+ * strictly read-only (blocks approve/reject/execute outright, matching
+ * "ASK: estrictamente read-only"); PLAN can review a plan (approve/reject)
+ * but never execute it ("PLAN: genera y persiste un plan, sin ejecutar");
+ * AGENT allows every gated action ("AGENT: permite avanzar bajo permisos y
+ * gates"). `cancel` is deliberately NEVER mode-gated — stopping a run that
+ * is already active is a safety action, not a way to advance the
+ * pipeline, and must stay available no matter which mode the cockpit is
+ * in when the need to cancel comes up. Omitting `mode` keeps the original,
+ * mode-unaware behavior (every real caller passes it; a few existing
+ * direct unit tests don't and must see no change).
+ * @param {"approve"|"reject"|"execute"|"cancel"} action
+ * @param {CockpitRow|null} row
+ * @param {"ask"|"plan"|"agent"|null} [mode]
+ * @returns {boolean}
+ */
+export function isActionAvailable(action, row, mode = null) {
+  if (!row) return false;
+  if (action === "cancel") return row.execActive === true;
+  if (mode === "ask") return false;
+  if (action === "approve" || action === "reject") return row.planState === "awaiting_approval";
+  if (action === "execute") {
+    if (mode === "plan") return false;
+    return row.planState === "approved" && row.execState === "not_started";
+  }
+  return false;
+}
+
+/**
+ * Builds the key-hint bar text for the current selection.
+ * @param {CockpitRow|null} row
+ * @param {"ask"|"plan"|"agent"|null} [mode]
+ * @returns {string}
+ */
+export function keyHintsLine(row, mode = null) {
+  const hints = ["up/down select", "enter view plan", "r refresh", "q quit"];
+  if (isActionAvailable("approve", row, mode)) hints.push("a approve");
+  if (isActionAvailable("reject", row, mode)) hints.push("j reject");
+  if (isActionAvailable("execute", row, mode)) hints.push("x execute");
+  if (isActionAvailable("cancel", row, mode)) hints.push("c cancel");
+  return hints.join("  |  ");
+}

package/src/global/cockpit/theme.js

@@ -0,0 +1,118 @@
+// Minimal ANSI true-color theme for the `kairo start` cockpit, ported from
+// gentle-pi's Gentle.json palette (docs/gentle-pi reference, MIT) so the
+// cockpit reads like a real TUI instead of plain padded text.
+
+// Exported so real contrast (WCAG relative luminance) can be verified
+// directly against the actual values in use, not a guess — see
+// theme.test.js's own regression for the real bug this caught (muted
+// measured ~3.40:1 on black, below the 4.5:1 floor for normal text).
+export const PALETTE = {
+  border: [49, 51, 66],
+  accent: [224, 193, 90],
+  text: [243, 246, 249],
+  // Bumped from [92,97,112] (real measured WCAG contrast on black: ~3.40:1
+  // — below the 4.5:1 minimum for normal text, which is why provider
+  // names, tags, and hint lines read as illegible in a real screenshot).
+  // [118,124,142] measures ~5.04:1, comfortably above the floor while
+  // staying visibly muted relative to `text` — still a secondary-info
+  // color, just a real, readable one.
+  muted: [118, 124, 142],
+  warning: [222, 186, 135],
+  error: [203, 124, 148],
+  success: [183, 204, 133],
+  info: [127, 180, 202],
+  // Bumped from [35,42,64] (real measured contrast against a plain black
+  // terminal background: ~1.48:1 — nearly indistinguishable, which is why
+  // a real screenshot of the analyst/model picker showed the selected row
+  // and the unselected background as "both black"). [50,80,140] measures
+  // ~2.66:1 against black — a real, clearly visible steel-blue bar — while
+  // still keeping `text` on top of it at ~7.27:1, comfortably above the
+  // 4.5:1 floor for normal text.
+  selection: [50, 80, 140]
+};
+
+/**
+ * @param {string} role - a PALETTE key
+ * @param {string} text
+ * @returns {string}
+ */
+function fg(role, text) {
+  const rgb = PALETTE[role] ?? PALETTE.text;
+  return `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${text}\x1b[0m`;
+}
+
+/** @param {string} text */
+function bold(text) {
+  return `\x1b[1m${text}\x1b[0m`;
+}
+
+/**
+ * Background-color highlight (e.g. the selected row in a list), like the
+ * blue selection bar in a real file tree.
+ * @param {string} role
+ * @param {string} text
+ */
+function bg(role, text) {
+  const rgb = PALETTE[role] ?? PALETTE.text;
+  return `\x1b[48;2;${rgb[0]};${rgb[1]};${rgb[2]}m${text}\x1b[0m`;
+}
+
+/**
+ * Bold + foreground + background combined in ONE ANSI escape with a
+ * SINGLE trailing reset — never nest `bold(bg(...))`/`fg(bg(...))`:
+ * each of those helpers ends with its own `\x1b[0m`, and an inner reset
+ * inside an outer one silently cuts the outer styling short partway
+ * through the text. Used for a real, clearly-highlighted selected row —
+ * "fondo/acentuación clara únicamente a la fila seleccionada" — without
+ * that hazard.
+ * @param {string} bgRole
+ * @param {string} fgRole
+ * @param {string} text
+ */
+function bgFg(bgRole, fgRole, text) {
+  const bgRgb = PALETTE[bgRole] ?? PALETTE.text;
+  const fgRgb = PALETTE[fgRole] ?? PALETTE.text;
+  // Strip any ANSI already embedded in `text` first — a real SelectList
+  // row can arrive here already carrying its own fg()-wrapped label
+  // (project-overlay.js explicitly colors model+provider text) and/or a
+  // theme.fg("muted", ...)-wrapped description; a caller can't be trusted
+  // to hand back plain text just because it usually does. Each of those
+  // inner wrappers ends with its own `\x1b[0m`, which — left in place —
+  // cuts the outer background short partway through the row (verified:
+  // the real bug this fixes, caught only by rendering a real SelectList
+  // row, never by testing bgFg against plain text alone). One combined
+  // escape with a single trailing reset is the only composition that's
+  // actually safe here.
+  return `\x1b[1m\x1b[38;2;${fgRgb[0]};${fgRgb[1]};${fgRgb[2]}m\x1b[48;2;${bgRgb[0]};${bgRgb[1]};${bgRgb[2]}m${stripAnsi(text)}\x1b[0m`;
+}
+
+/** Removes any ANSI SGR escape sequences already embedded in `text` — see bgFg's own doc for why this must happen before re-wrapping. */
+function stripAnsi(text) {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+export const theme = { fg, bold, bg, bgFg };
+
+/**
+ * pi-tui's Editor component requires this shape (EditorTheme). We don't use
+ * autocomplete yet, so the selectList sub-theme is only there to satisfy the
+ * type contract.
+ */
+export const editorTheme = {
+  // Bright, not the muted "border" gray used for card rules elsewhere — the
+  // composer is the one place the user is actively typing, so it needs to
+  // read as a distinct, easy-to-find zone rather than blend into the frame.
+  borderColor: (text) => fg("success", text),
+  selectList: {
+    selectedPrefix: (text) => fg("accent", text),
+    // A real background highlight on the selected row only (never the
+    // whole panel — see project-overlay.js's own Box, which applies no
+    // background of its own), bold + bright text for clear legibility
+    // against it.
+    selectedText: (text) => bgFg("selection", "text", text),
+    description: (text) => fg("muted", text),
+    scrollInfo: (text) => fg("muted", text),
+    noMatch: (text) => fg("muted", text)
+  }
+};