@bastani/atomic 0.7.17 → 0.8.0

package/dist/builtin/workflows/src/tui/keybindings-adapter.ts

@@ -0,0 +1,154 @@
+/**
+ * Structural adapter for Pi's injected `KeybindingsManager` plus the
+ * string-buffer helpers that the workflow form's editing actions need.
+ *
+ * Workflow input surfaces (the inline form editor and the fallback overlay
+ * picker) receive Pi's keybindings manager as the third argument of their
+ * factory. They use it to translate raw terminal byte sequences into named
+ * Pi actions (`tui.editor.deleteWordBackward`, etc.) so user-configured
+ * keybindings — Ctrl/Cmd+Backspace, Ctrl+W, Ctrl+U, Ctrl+K, Alt+Arrow,
+ * Home/End, etc. — work consistently with the rest of the agent's TUI.
+ *
+ * We intentionally avoid a direct `KeybindingsManager` import from
+ * `@earendil-works/pi-tui` here:
+ *   - The manager is a runtime singleton owned by the host; constructing
+ *     a second one in the extension graph would duplicate state and
+ *     fight the host for action resolution.
+ *   - The structural `{ matches(data, action): boolean }` shape is all
+ *     this code needs and keeps the per-call surface tiny.
+ *
+ * Rendering primitives are different — `Box`, `Text`, `Spacer`,
+ * `Markdown`, etc. from `@earendil-works/pi-tui` are stateless and SHOULD be
+ * imported directly in extension code (per pi.dev/docs/latest/tui).
+ *
+ * cross-ref:
+ *   - node_modules/@earendil-works/pi-tui/src/keybindings.ts → KeybindingsManager
+ *   - node_modules/@earendil-works/pi-tui/src/components/editor.ts routes through
+ *     the same action ids (`tui.editor.cursorWordLeft`, etc.).
+ */
+
+/**
+ * Minimal shape this codebase needs from Pi's `KeybindingsManager`.
+ *
+ * `matches(data, action)` returns true when raw terminal bytes in `data`
+ * map to the named action under the user's resolved keybindings. Real
+ * pi-tui `KeybindingsManager.matches` is fully covariant with this type.
+ */
+export interface KeybindingsLike {
+  matches(data: string, action: string): boolean;
+}
+
+/** Runtime guard for hosts that wire the keybindings manager. */
+export function isKeybindingsLike(kb: unknown): kb is KeybindingsLike {
+  return (
+    typeof kb === "object" &&
+    kb !== null &&
+    typeof (kb as { matches?: unknown }).matches === "function"
+  );
+}
+
+/**
+ * Ask Pi whether `data` maps to the named action. Returns `false` when
+ * no keybindings manager is wired or the action does not match — there
+ * is intentionally no parallel raw-byte fallback table. Hosts are
+ * expected to provide a `KeybindingsManager` and tests pass a real or
+ * structural fake one.
+ */
+export function matchesAction(
+  kb: KeybindingsLike | undefined,
+  data: string,
+  action: string,
+): boolean {
+  if (!kb) return false;
+  return kb.matches(data, action);
+}
+
+// ── Word boundary helpers ────────────────────────────────────────────────
+//
+// Emacs/bash-readline semantics: a "word" is a maximal run of non-
+// whitespace characters. Word-left/word-right skip the leading
+// whitespace gap, then skip the word run. This intentionally diverges
+// from pi-tui's Unicode-aware grapheme segmenter (which requires the
+// pi-natives addon) — workflow inputs are short prompts where simple
+// whitespace-based word boundaries match user intuition and keep the
+// helper free of native-module deps so tests run on any host.
+
+function isWordBoundary(ch: string): boolean {
+  return /\s/.test(ch);
+}
+
+/**
+ * Return the offset to the left of `caret` that lands on the previous
+ * word boundary. Mirrors readline's `backward-word`: skip whitespace
+ * (and newlines) leftward, then skip non-whitespace leftward. Clamps to
+ * the start of the string.
+ */
+export function wordLeft(text: string, caret: number): number {
+  let i = Math.max(0, Math.min(caret, text.length));
+  // Skip trailing whitespace (including newlines).
+  while (i > 0 && isWordBoundary(text[i - 1]!)) i -= 1;
+  // Skip word body.
+  while (i > 0 && !isWordBoundary(text[i - 1]!)) i -= 1;
+  return i;
+}
+
+/**
+ * Return the offset to the right of `caret` that lands on the next
+ * word boundary. Mirrors readline's `forward-word`: skip whitespace
+ * rightward, then skip non-whitespace rightward. Clamps to the end of
+ * the string.
+ */
+export function wordRight(text: string, caret: number): number {
+  const len = text.length;
+  let i = Math.max(0, Math.min(caret, len));
+  while (i < len && isWordBoundary(text[i]!)) i += 1;
+  while (i < len && !isWordBoundary(text[i]!)) i += 1;
+  return i;
+}
+
+// ── Logical-line helpers ─────────────────────────────────────────────────
+//
+// The form caret is a single integer offset into `rawText[fieldName]`;
+// logical lines are split by `\n`. Line-start / line-end resolve to the
+// boundaries of the line containing the caret. Line-start is the offset
+// of the character AFTER the previous `\n` (or 0). Line-end is the
+// offset of the next `\n` (or `text.length`).
+
+export function lineStart(text: string, caret: number): number {
+  const c = Math.max(0, Math.min(caret, text.length));
+  return text.lastIndexOf("\n", c - 1) + 1;
+}
+
+export function lineEnd(text: string, caret: number): number {
+  const c = Math.max(0, Math.min(caret, text.length));
+  const nl = text.indexOf("\n", c);
+  return nl === -1 ? text.length : nl;
+}
+
+/**
+ * Splice `[start, end)` out of `text` and return the new value plus the
+ * caret position after the deletion. Both bounds are clamped to the
+ * valid range; an empty or inverted range is a no-op (returns original
+ * text and `caret`).
+ */
+export interface DeleteRangeResult {
+  text: string;
+  caret: number;
+}
+
+export function deleteRange(text: string, start: number, end: number, caret: number): DeleteRangeResult {
+  const len = text.length;
+  const s = Math.max(0, Math.min(start, len));
+  const e = Math.max(s, Math.min(end, len));
+  if (s === e) return { text, caret };
+  const next = text.slice(0, s) + text.slice(e);
+  // The caret tracks the user's logical position. Cases:
+  //   - caret < s              → unaffected, stays in place
+  //   - s <= caret <= e        → collapses to s
+  //   - caret > e              → shifts left by the deleted run's length
+  let nextCaret: number;
+  if (caret <= s) nextCaret = caret;
+  else if (caret <= e) nextCaret = s;
+  else nextCaret = caret - (e - s);
+  return { text: next, caret: nextCaret };
+}

package/dist/builtin/workflows/src/tui/layout.ts

@@ -0,0 +1,153 @@
+/**
+ * DAG layout engine: flat stage list → 2D grid.
+ * cross-ref: spec §5.4.1, v0.x packages/atomic-sdk/src/components/layout.ts
+ */
+import type { StageSnapshot } from "../shared/store-types.js";
+
+export const NODE_W = 24;
+export const NODE_H = 5;
+
+export interface LayoutNode {
+  stage: StageSnapshot;
+  col: number;
+  row: number;
+  x: number;
+  y: number;
+}
+
+export interface LayoutOpts {
+  colGap?: number;
+  rowGap?: number;
+  /**
+   * `horizontal` (default): depth flows left → right. `col → x`, `row → y`.
+   * `vertical`: depth flows top → bottom. `col → y`, `row → x`.
+   *
+   * `col` and `row` retain their semantic identity (depth × sibling-index)
+   * in both orientations — only the projection to pixel space swaps. This
+   * keeps unit tests addressing `col/row` orientation-agnostic.
+   */
+  orientation?: "horizontal" | "vertical";
+}
+
+/**
+ * Assign each stage a (col, row) via BFS from roots.
+ * Parallel stages share the same column; sequential stages increment column.
+ */
+export function computeLayout(
+  stages: readonly StageSnapshot[],
+  opts: LayoutOpts = {},
+): LayoutNode[] {
+  const colGap = opts.colGap ?? 4;
+  const rowGap = opts.rowGap ?? 2;
+
+  if (stages.length === 0) return [];
+
+  const idSet = new Set(stages.map((s) => s.id));
+
+  // Map from id → stage
+  const byId = new Map<string, StageSnapshot>();
+  for (const s of stages) byId.set(s.id, s);
+
+  // Assign columns via BFS (longest path from root)
+  const colMap = new Map<string, number>();
+
+  // Topological BFS: process nodes whose all parents have been assigned
+  const inDegree = new Map<string, number>();
+  const children = new Map<string, string[]>();
+
+  for (const s of stages) {
+    const validParents = s.parentIds.filter((pid) => idSet.has(pid));
+    inDegree.set(s.id, validParents.length);
+    for (const pid of validParents) {
+      if (!children.has(pid)) children.set(pid, []);
+      children.get(pid)!.push(s.id);
+    }
+  }
+
+  // Roots: nodes with no valid parents
+  const queue: string[] = [];
+  for (const s of stages) {
+    if (inDegree.get(s.id) === 0) {
+      queue.push(s.id);
+      colMap.set(s.id, 0);
+    }
+  }
+
+  // BFS assigning col = max(parent cols) + 1
+  const visited = new Set<string>();
+  let qi = 0;
+  while (qi < queue.length) {
+    const id = queue[qi++]!;
+    if (visited.has(id)) continue;
+    visited.add(id);
+
+    const stage = byId.get(id)!;
+    const validParents = stage.parentIds.filter((pid) => idSet.has(pid));
+    let myCol = 0;
+    for (const pid of validParents) {
+      myCol = Math.max(myCol, (colMap.get(pid) ?? 0) + 1);
+    }
+    colMap.set(id, myCol);
+
+    const kids = children.get(id) ?? [];
+    for (const kid of kids) {
+      const deg = (inDegree.get(kid) ?? 1) - 1;
+      inDegree.set(kid, deg);
+      if (deg === 0) queue.push(kid);
+    }
+  }
+
+  // Handle any nodes not visited (cycles or disconnected) - assign next col
+  for (const s of stages) {
+    if (!colMap.has(s.id)) colMap.set(s.id, 0);
+  }
+
+  // Group by column, assign rows
+  const colGroups = new Map<number, string[]>();
+  for (const [id, col] of colMap) {
+    if (!colGroups.has(col)) colGroups.set(col, []);
+    colGroups.get(col)!.push(id);
+  }
+
+  const orientation = opts.orientation ?? "horizontal";
+
+  // Vertical orientation centres each depth's sibling band around the
+  // widest depth so single-child rows sit beneath the centre of the parent
+  // fan-out instead of left-aligning. The shift is computed as the
+  // difference between the widest band's centre and this band's centre,
+  // in pixel cells — not in whole-column steps, otherwise a 1-of-even
+  // row lands under one sibling rather than between two.
+  const bandWidth = (count: number): number =>
+    count > 0 ? count * NODE_W + (count - 1) * colGap : 0;
+  const widestBand = (() => {
+    let max = 0;
+    for (const ids of colGroups.values()) {
+      if (ids.length > max) max = ids.length;
+    }
+    return max;
+  })();
+  const widestCentre = bandWidth(widestBand) / 2;
+  const centreShift = new Map<number, number>();
+  for (const [depth, ids] of colGroups) {
+    const centre = bandWidth(ids.length) / 2;
+    centreShift.set(depth, Math.round(widestCentre - centre));
+  }
+
+  const nodes: LayoutNode[] = [];
+  for (const s of stages) {
+    const col = colMap.get(s.id) ?? 0;
+    const group = colGroups.get(col) ?? [];
+    const row = group.indexOf(s.id);
+    const x =
+      orientation === "vertical"
+        ? row * (NODE_W + colGap) + (centreShift.get(col) ?? 0)
+        : col * (NODE_W + colGap);
+    const y =
+      orientation === "vertical"
+        ? col * (NODE_H + rowGap)
+        : row * (NODE_H + rowGap);
+    nodes.push({ stage: s, col, row, x, y });
+  }
+
+  return nodes;
+}

package/dist/builtin/workflows/src/tui/node-card.ts

@@ -0,0 +1,274 @@
+/**
+ * DAG node card — rounded, status-coloured, with an accent focus tab.
+ *
+ * Visual contract (DESIGN.md §5):
+ *  - Rounded border `╭╮╰╯` only. No square or ASCII art.
+ *  - Border colour carries status. `running` pulses via sine lerp
+ *    against the dim border (focus locks the pulse). `completed` /
+ *    `failed` stay status-coloured regardless of focus. `pending`
+ *    sits on `borderDim` and lifts to `borderActive` when focused.
+ *  - When focused, the centred title segment becomes a compact accent
+ *    "tab": `▸ name` painted with `theme.accent` bg + `theme.surface`
+ *    fg + bold. The tab is the only focus signal — the surrounding
+ *    border is reserved for status. No `[focused]` text, no glow,
+ *    no resize.
+ *  - Single centred duration line in the body, coloured by status.
+ *
+ * Reuses the existing `paint(...)` color-utils helper (a thin wrapper
+ * over `hexBg` + `hexToAnsi` + `BOLD` + `RESET`) so the tab matches
+ * the same ANSI shape Pi's renderer uses for every other styled run.
+ *
+ * cross-ref:
+ *   - github.com/flora131/atomic packages/atomic-sdk/src/components/node-card.tsx
+ *   - DESIGN.md §5 "Node Cards (orchestrator graph)"
+ *   - src/tui/graph-theme.ts `deriveGraphThemeFromPiTheme` — the
+ *     accent/surface tokens used below are sourced from Pi's live
+ *     `Theme` when the overlay mounts.
+ */
+
+import type { StageSnapshot, StageStatus } from "../shared/store-types.js";
+import type { GraphTheme } from "./graph-theme.js";
+import { fmtDuration } from "./status-helpers.js";
+import { lerpColor, hexToAnsi, hexBg, paint, RESET, BOLD } from "./color-utils.js";
+import { NODE_W, NODE_H } from "./layout.js";
+
+export interface NodeCardOpts {
+  width?: number;
+  height?: number;
+  focused?: boolean;
+  /** 0–1; ignored when status is terminal (complete/failed). */
+  pulsePhase?: number;
+  theme: GraphTheme;
+  /** Run stages, used to resolve blockedByStageId into a short upstream name. */
+  stages?: readonly StageSnapshot[];
+}
+
+/** Glyph that prefixes the focused-tab title; matches the compact
+ * cursor `❯` vocabulary used elsewhere but rotated to fit inline
+ * inside the top border (`▸` reads as a small wedge in the slot). */
+const FOCUS_TAB_GLYPH = "▸";
+
+/** Sine-eased pulse `t ∈ [0, 1]`. Phase 0 ≈ quiet, 0.5 ≈ peak. */
+function pulseT(phase: number): number {
+  return (Math.sin(phase * Math.PI * 2 - Math.PI / 2) + 1) / 2;
+}
+
+function pickBorder(
+  status: StageStatus,
+  focused: boolean,
+  phase: number,
+  theme: GraphTheme,
+): string {
+  switch (status) {
+    case "running":
+      // Focus locks the pulse at peak. Status colour wins either way.
+      if (focused) return theme.warning;
+      return lerpColor(theme.borderDim, theme.warning, pulseT(phase));
+    case "awaiting_input":
+      if (focused) return theme.info;
+      return lerpColor(theme.borderDim, theme.info, pulseT(phase));
+    case "completed":
+      return theme.success;
+    case "failed":
+      return theme.error;
+    case "blocked":
+      return theme.dim;
+    case "pending":
+    default:
+      // Pending has no semantic colour; the focused-tab carries the
+      // cursor signal, so we only lift the border one step.
+      return focused ? theme.borderActive : theme.borderDim;
+  }
+}
+
+function durationColor(status: StageStatus, theme: GraphTheme): string {
+  switch (status) {
+    case "running":
+      return theme.warning;
+    case "awaiting_input":
+      return theme.info;
+    case "completed":
+      return theme.success;
+    case "failed":
+      return theme.error;
+    default:
+      return theme.dim;
+  }
+}
+
+function blockedBadgeText(
+  stage: StageSnapshot,
+  stages: readonly StageSnapshot[] | undefined,
+  width: number,
+): string {
+  const base = "↑ blocked";
+  const blockedBy = stage.blockedByStageId;
+  if (!blockedBy) return base;
+
+  const upstream = stages?.find((s) => s.id === blockedBy)?.name ?? blockedBy;
+  const withUpstream = `${base} by ${upstream}`;
+  if (withUpstream.length <= width) return withUpstream;
+  return base;
+}
+
+function durationText(stage: StageSnapshot): string {
+  if (stage.durationMs != null) return fmtDuration(stage.durationMs);
+  if (stage.startedAt != null) return fmtDuration(Date.now() - stage.startedAt);
+  return "—";
+}
+
+function truncate(s: string, maxLen: number): string {
+  if (maxLen <= 0) return "";
+  if (s.length <= maxLen) return s;
+  return s.slice(0, Math.max(1, maxLen - 1)) + "…";
+}
+
+/**
+ * Centre a visible string inside `width` cells, wrapping it with `fg`
+ * (and optional bold) ANSI escapes. The visible width is computed before
+ * the colour escapes are added so padding stays correct. `bg` is
+ * re-emitted around the coloured run so trailing pad cells stay on the
+ * card stratum instead of dropping to the terminal default.
+ */
+function centreColored(
+  content: string,
+  width: number,
+  fg: string,
+  bg: string,
+  opts: { bold?: boolean } = {},
+): string {
+  const safe = truncate(content, width);
+  const pad = width - safe.length;
+  const left = Math.max(0, Math.floor(pad / 2));
+  const right = Math.max(0, pad - left);
+  const bold = opts.bold ? BOLD : "";
+  return (
+    `${bg}${" ".repeat(left)}` +
+    `${hexToAnsi(fg)}${bold}${safe}${RESET}` +
+    `${bg}${" ".repeat(right)}`
+  );
+}
+
+/**
+ * Build the title slot — the run of cells between the rounded corners
+ * on the top border. Returns a pre-styled fragment plus its visible
+ * width so the caller can pad the surrounding dashes correctly.
+ *
+ * When `focused`, the slot reads as a small accent-coloured tab:
+ *   `╭── ▸ stage ──╮`
+ * Otherwise it falls back to the historical bold-title shape:
+ *   `╭── stage ──╮`
+ *
+ * The visible-width contract is preserved (length of the title slot
+ * is included in the dash math) so the card geometry never shifts
+ * between the two states — focus only changes the styling of the
+ * existing slot, not its size.
+ */
+function buildTitleSlot(
+  name: string,
+  innerWidth: number,
+  focused: boolean,
+  theme: GraphTheme,
+  cardBg: string,
+): { slot: string; visibleWidth: number } {
+  const overhead = focused ? FOCUS_TAB_GLYPH.length + 1 /* space */ : 0;
+  const maxName = Math.max(2, innerWidth - 4 - overhead);
+  const safeName = truncate(name, maxName);
+  if (focused) {
+    // ` ▸ name ` — flanking spaces sit on the accent tab so the
+    // pill reads as a single coloured run. Use `paint` to combine
+    // bg + fg + bold + RESET in one ANSI sequence (re-priming the
+    // card stratum afterwards so the dashes outside the slot stay
+    // on the body bg).
+    const tabText = ` ${FOCUS_TAB_GLYPH} ${safeName} `;
+    const styled = `${paint(tabText, theme.surface, {
+      bg: theme.accent,
+      bold: true,
+    })}${cardBg}`;
+    return { slot: styled, visibleWidth: tabText.length };
+  }
+  const titleRaw = ` ${safeName} `;
+  const styled = `${BOLD}${titleRaw}${RESET}${cardBg}`;
+  return { slot: styled, visibleWidth: titleRaw.length };
+}
+
+/**
+ * Render a stage as a multi-line card string.
+ * Returns array of exactly `height` lines, each `width` cells wide.
+ */
+export function renderNodeCard(stage: StageSnapshot, opts: NodeCardOpts): string[] {
+  const width = opts.width ?? NODE_W;
+  const height = opts.height ?? NODE_H;
+  const focused = opts.focused ?? false;
+  const phase = opts.pulsePhase ?? 0;
+  const theme = opts.theme;
+
+  const borderHex = pickBorder(stage.status, focused, phase, theme);
+  const bc = hexToAnsi(borderHex);
+  // Card stratum bg — painted explicitly on every cell so internal
+  // RESETs never let the terminal default leak through as a shadow
+  // strip on the right/bottom of the card. Per DESIGN.md the card
+  // background is `base` (same as the canvas), so this paints flush
+  // with the body bg and only the border outline reads visually.
+  const bg = hexBg(theme.bg);
+  const innerWidth = Math.max(2, width - 2);
+
+  // Title sits inside the top border: ╭── name ──╮ or, when focused,
+  // ╭── ▸ name ──╮ with an accent-coloured pill on the name slot.
+  const { slot: titleSlot, visibleWidth: titleVisibleWidth } = buildTitleSlot(
+    stage.name,
+    innerWidth,
+    focused,
+    theme,
+    bg,
+  );
+  const titleStart = Math.max(1, Math.floor((innerWidth - titleVisibleWidth) / 2));
+  const titleEnd = titleStart + titleVisibleWidth;
+  const topMiddle =
+    `${bc}${"─".repeat(titleStart)}` +
+    `${titleSlot}${bc}` +
+    `${"─".repeat(Math.max(0, innerWidth - titleEnd))}`;
+  const top = `${bg}${bc}╭${topMiddle}╮${RESET}`;
+  const bottom = `${bg}${bc}╰${"─".repeat(innerWidth)}╯${RESET}`;
+
+  // Interior — single centred duration line. Each `│` border is
+  // followed by a `bg`-primed centred run so the inner cells stay on
+  // the card stratum.
+  const bodyText =
+    stage.status === "blocked"
+      ? blockedBadgeText(stage, opts.stages, innerWidth)
+      : durationText(stage);
+  const bodyHex = durationColor(stage.status, theme);
+  const durLine =
+    `${bg}${bc}│${RESET}` +
+    centreColored(bodyText, innerWidth, bodyHex, bg, {
+      bold: stage.status === "blocked",
+    }) +
+    `${bg}${bc}│${RESET}`;
+
+  const interior: string[] =
+    stage.status === "awaiting_input"
+      ? [
+          durLine,
+          `${bg}${bc}│${RESET}` +
+            centreColored("waiting for response", innerWidth, theme.info, bg) +
+            `${bg}${bc}│${RESET}`,
+          `${bg}${bc}│${RESET}` +
+            centreColored("↵ enter to respond", innerWidth, theme.dim, bg) +
+            `${bg}${bc}│${RESET}`,
+        ]
+      : [durLine];
+
+  // Pad / clip to exactly `height` lines.
+  const contentRows = Math.max(0, height - 2);
+  while (interior.length < contentRows) {
+    interior.push(
+      `${bg}${bc}│${RESET}${bg}${" ".repeat(innerWidth)}${bg}${bc}│${RESET}`,
+    );
+  }
+  if (interior.length > contentRows) {
+    interior.length = contentRows;
+  }
+
+  return [top, ...interior, bottom];
+}