@osolmaz/pi-workflows 0.1.0

package/src/extension/widget.ts

@@ -0,0 +1,183 @@
+import { ansi, stripAnsi } from "../render/ansi.js";
+import { renderGraphLines } from "../render/graph-render.js";
+import { sanitizeText } from "../workflows/text.js";
+import type {
+  WorkflowDefinitionSnapshot,
+  WorkflowRunState,
+  WorkflowRunStatus,
+} from "../workflows/types.js";
+
+const STATUS_GLYPHS: Record<WorkflowRunStatus, string> = {
+  running: "◐",
+  waiting: "⏸",
+  completed: "✓",
+  failed: "✗",
+  timed_out: "✗",
+  cancelled: "✗",
+};
+
+/**
+ * pi renders at most this many widget lines (InteractiveMode.MAX_WIDGET_LINES)
+ * and appends its own "(widget truncated)" marker beyond it. Stay inside the
+ * budget and choose which graph rows to show instead of losing the bottom.
+ */
+const PI_MAX_WIDGET_LINES = 10;
+
+export function nodeGlyph(state: WorkflowRunState, nodeId: string): string {
+  if (state.currentNode === nodeId) {
+    return "◐";
+  }
+  const result = state.results[nodeId];
+  if (!result) {
+    return "·";
+  }
+  if (state.waitingOn === nodeId) {
+    return "⏸";
+  }
+  return result.outcome === "ok" ? "✓" : "✗";
+}
+
+/** Node ids in a stable display order: definition order from the snapshot. */
+export function displayNodeIds(snapshot: WorkflowDefinitionSnapshot): string[] {
+  return Object.keys(snapshot.nodes);
+}
+
+export type WidgetView = {
+  lines: string[];
+  /** The clamped first visible graph row; feed back in to scroll relatively. */
+  scroll: number;
+  /** Largest useful scroll value; 0 when the whole graph fits. */
+  maxScroll: number;
+};
+
+/**
+ * Live-progress view for the in-pi widget: a header plus the same boxed
+ * graph the standalone viewer draws. When the graph is taller than pi's
+ * widget budget, a window is shown with ↑/↓ overflow markers — centered on
+ * the active node by default, or at `scroll` when the user scrolled
+ * manually. Pure so it can be tested without a TUI.
+ */
+export function buildWidgetView(
+  state: WorkflowRunState,
+  snapshot: WorkflowDefinitionSnapshot,
+  now: Date = new Date(),
+  scroll: number | null = null,
+  held = false,
+): WidgetView {
+  // `held` covers pauses the state cannot see yet: an escape-interrupted
+  // step or a pause requested while the current node is still finishing.
+  const paused = held || state.paused === true;
+  const glyph = paused ? "⏸" : STATUS_GLYPHS[state.status];
+  const statusText = paused ? "paused" : state.status;
+  // Titles, status details, and errors can carry model- or shell-controlled
+  // text; never let escape sequences or newlines reach the terminal.
+  const title = state.runTitle ? ` — ${sanitizeText(state.runTitle)}` : "";
+  const header = `${glyph} workflow ${sanitizeText(state.workflowName)}${title} [${statusText}]`;
+
+  const footer: string[] = [];
+  if (state.error) {
+    footer.push(`  error: ${truncate(sanitizeText(state.error), 120)}`);
+  }
+  if (state.status === "waiting" && state.waitingOn) {
+    footer.push(`  waiting on checkpoint: ${state.waitingOn}`);
+  }
+
+  const budget = PI_MAX_WIDGET_LINES - 1 - footer.length;
+  const graph = renderGraphLines({ state, snapshot }, state.steps.length - 1, now, {
+    nodeStyle: "box",
+  });
+  if (graph.length === 0) {
+    return {
+      lines: [header, `  ${compactNodeStrip(state, snapshot)}`, ...footer],
+      scroll: 0,
+      maxScroll: 0,
+    };
+  }
+  const windowed = windowLines(graph, budget, scroll ?? focusLine(graph, state), scroll !== null);
+  return {
+    lines: [header, ...windowed.lines.map((line) => `  ${line}`), ...footer],
+    scroll: windowed.scroll,
+    maxScroll: windowed.maxScroll,
+  };
+}
+
+/** Back-compatible line view following the active node. */
+export function buildWidgetLines(
+  state: WorkflowRunState,
+  snapshot: WorkflowDefinitionSnapshot,
+  now: Date = new Date(),
+): string[] {
+  return buildWidgetView(state, snapshot, now).lines;
+}
+
+/** The graph row the window should center on: the active or waiting node. */
+function focusLine(graph: string[], state: WorkflowRunState): number {
+  const active = graph.findIndex((line) => stripAnsi(line).includes("◐"));
+  if (active !== -1) {
+    return active;
+  }
+  if (state.waitingOn) {
+    const waiting = graph.findIndex((line) => stripAnsi(line).includes(state.waitingOn as string));
+    if (waiting !== -1) {
+      return waiting;
+    }
+  }
+  return graph.length - 1;
+}
+
+/**
+ * Slice `lines` to at most `budget` rows, marking hidden rows at either end.
+ * Markers count against the budget. `anchor` is a row to center on (follow
+ * mode) or the requested first visible row (manual scroll).
+ */
+function windowLines(
+  lines: string[],
+  budget: number,
+  anchor: number,
+  anchorIsStart: boolean,
+): { lines: string[]; scroll: number; maxScroll: number } {
+  if (lines.length <= budget) {
+    return { lines, scroll: 0, maxScroll: 0 };
+  }
+  // First pass decides which markers exist; the second re-fits within the
+  // remaining space. A marker flag can only turn on (never off) in the
+  // second pass, so the result stays within budget.
+  let inner = budget;
+  for (let pass = 0; pass < 2; pass += 1) {
+    const start = clampStart(anchor, inner, lines.length, anchorIsStart);
+    inner = budget - (start > 0 ? 1 : 0) - (start + inner < lines.length ? 1 : 0);
+  }
+  const start = clampStart(anchor, inner, lines.length, anchorIsStart);
+  const end = start + inner;
+  const out: string[] = [];
+  if (start > 0) {
+    out.push(ansi.dim(`↑ ${start} more`));
+  }
+  out.push(...lines.slice(start, end));
+  if (end < lines.length) {
+    out.push(ansi.dim(`↓ ${lines.length - end} more · shift+↑/↓ scroll`));
+  }
+  return { lines: out, scroll: start, maxScroll: Math.max(0, lines.length - inner) };
+}
+
+function clampStart(anchor: number, inner: number, total: number, anchorIsStart: boolean): number {
+  const start = anchorIsStart ? anchor : anchor - Math.floor(inner / 2);
+  return Math.max(0, Math.min(start, total - inner));
+}
+
+function compactNodeStrip(state: WorkflowRunState, snapshot: WorkflowDefinitionSnapshot): string {
+  return displayNodeIds(snapshot)
+    .map((nodeId) => {
+      const marker = nodeGlyph(state, nodeId);
+      const detail =
+        state.currentNode === nodeId && state.statusDetail
+          ? ` (${sanitizeText(state.statusDetail)})`
+          : "";
+      return `${marker} ${nodeId}${detail}`;
+    })
+    .join("  ");
+}
+
+function truncate(text: string, maxLength: number): string {
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
+}

package/src/render/ansi.ts

@@ -0,0 +1,47 @@
+import { sanitizeText, stripAnsi } from "../workflows/text.js";
+
+export { sanitizeText, stripAnsi };
+
+/**
+ * Colors are on for interactive terminals only, so piped output stays clean.
+ * `NO_COLOR`/`PI_WORKFLOWS_NO_COLOR` force them off; `FORCE_COLOR` forces
+ * them on. Evaluated per call so env changes (tests) take effect.
+ */
+function colorEnabled(): boolean {
+  if (process.env.NO_COLOR !== undefined || process.env.PI_WORKFLOWS_NO_COLOR !== undefined) {
+    return false;
+  }
+  if (process.env.FORCE_COLOR !== undefined) {
+    return true;
+  }
+  return process.stdout.isTTY === true;
+}
+
+function wrap(code: string, text: string): string {
+  return colorEnabled() ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+
+export const ansi = {
+  bold: (text: string) => wrap("1", text),
+  dim: (text: string) => wrap("2", text),
+  red: (text: string) => wrap("31", text),
+  green: (text: string) => wrap("32", text),
+  yellow: (text: string) => wrap("33", text),
+  blue: (text: string) => wrap("34", text),
+  magenta: (text: string) => wrap("35", text),
+  cyan: (text: string) => wrap("36", text),
+};
+
+/** Visible length of a string, ignoring ANSI escape sequences. */
+export function visibleLength(text: string): number {
+  return stripAnsi(text).length;
+}
+
+/** Truncate to a visible width, keeping ANSI sequences intact by stripping them first when needed. */
+export function fitWidth(text: string, width: number): string {
+  if (visibleLength(text) <= width) {
+    return text;
+  }
+  const plain = stripAnsi(text);
+  return width <= 1 ? plain.slice(0, width) : `${plain.slice(0, width - 1)}…`;
+}

package/src/render/canvas.ts

@@ -0,0 +1,196 @@
+/**
+ * A sparse character grid for drawing the workflow graph. Box-drawing
+ * characters merge by connectivity (│ crossing ─ becomes ┼) so overlapping
+ * edge polylines join instead of overwriting each other.
+ */
+
+export type CanvasStyle = "plain" | "dim" | "taken" | "active" | "back" | "ok" | "fail" | "warn";
+
+type CanvasChar = { char: string; style: CanvasStyle };
+
+export const UP = 1;
+export const DOWN = 2;
+export const LEFT = 4;
+export const RIGHT = 8;
+
+/** Which sides each box-drawing character connects to (exported for tests). */
+export const CHAR_TO_MASK: Record<string, number> = {
+  "─": LEFT | RIGHT,
+  "│": UP | DOWN,
+  "┌": DOWN | RIGHT,
+  "┐": DOWN | LEFT,
+  "└": UP | RIGHT,
+  "┘": UP | LEFT,
+  "├": UP | DOWN | RIGHT,
+  "┤": UP | DOWN | LEFT,
+  "┬": DOWN | LEFT | RIGHT,
+  "┴": UP | LEFT | RIGHT,
+  "┼": UP | DOWN | LEFT | RIGHT,
+};
+
+const MASK_TO_CHAR = new Map<number, string>(
+  Object.entries(CHAR_TO_MASK).map(([char, mask]) => [mask, char]),
+);
+
+/** Styles later in this list win when merged lines overlap. */
+const STYLE_PRIORITY: CanvasStyle[] = [
+  "plain",
+  "dim",
+  "back",
+  "warn",
+  "ok",
+  "fail",
+  "taken",
+  "active",
+];
+
+function mergeStyles(a: CanvasStyle, b: CanvasStyle): CanvasStyle {
+  return STYLE_PRIORITY.indexOf(a) >= STYLE_PRIORITY.indexOf(b) ? a : b;
+}
+
+export class CharCanvas {
+  private readonly cells = new Map<number, Map<number, CanvasChar>>();
+  private maxX = 0;
+  private maxY = 0;
+
+  private row(y: number): Map<number, CanvasChar> {
+    let row = this.cells.get(y);
+    if (!row) {
+      row = new Map();
+      this.cells.set(y, row);
+    }
+    this.maxY = Math.max(this.maxY, y);
+    return row;
+  }
+
+  /** Place a single character, merging box-drawing connectivity. */
+  put(x: number, y: number, char: string, style: CanvasStyle = "plain"): void {
+    if (x < 0 || y < 0) {
+      return;
+    }
+    const row = this.row(y);
+    this.maxX = Math.max(this.maxX, x);
+    const existing = row.get(x);
+    // Spaces never occupy cells; textOverRun handles deliberate padding.
+    if (char === " ") {
+      return;
+    }
+    if (existing) {
+      const existingMask = CHAR_TO_MASK[existing.char];
+      const incomingMask = CHAR_TO_MASK[char];
+      if (existingMask !== undefined && incomingMask !== undefined) {
+        row.set(x, {
+          char: MASK_TO_CHAR.get(existingMask | incomingMask) ?? char,
+          style: mergeStyles(existing.style, style),
+        });
+        return;
+      }
+      // Non-line characters (labels, glyphs, arrows) win over lines; between
+      // two non-line characters the newest wins.
+      if (existingMask === undefined && incomingMask !== undefined) {
+        return;
+      }
+    }
+    row.set(x, { char, style });
+  }
+
+  /** Write a text run left to right (labels, node lines). */
+  text(x: number, y: number, value: string, style: CanvasStyle = "plain"): void {
+    for (const [index, char] of [...value].entries()) {
+      this.put(x + index, y, char, style);
+    }
+  }
+
+  /**
+   * Write text only when every target cell is empty. Returns whether the
+   * text was written. Used for optional decorations (edge labels) that must
+   * never corrupt lines or nodes already on the canvas.
+   */
+  textIfEmpty(x: number, y: number, value: string, style: CanvasStyle = "plain"): boolean {
+    if (x < 0 || y < 0) {
+      return false;
+    }
+    const row = this.cells.get(y);
+    const width = [...value].length;
+    for (let index = 0; index < width; index += 1) {
+      if (row?.has(x + index)) {
+        return false;
+      }
+    }
+    this.text(x, y, value, style);
+    return true;
+  }
+
+  /**
+   * Write text over a plain horizontal run, replacing `─` cells only.
+   * Refuses (returns false) unless every target cell and both flanking
+   * cells are exactly `─`, so a label can never overwrite or sit against
+   * corners, crossings, or other labels. Spaces in `value` become real
+   * blanks, visually breaking the run around the label on purpose.
+   */
+  textOverRun(x: number, y: number, value: string, style: CanvasStyle = "plain"): boolean {
+    if (x < 1 || y < 0) {
+      return false;
+    }
+    const chars = [...value];
+    const row = this.cells.get(y);
+    for (let index = -1; index <= chars.length; index += 1) {
+      if (row?.get(x + index)?.char !== "─") {
+        return false;
+      }
+    }
+    for (const [index, char] of chars.entries()) {
+      this.row(y).set(x + index, { char, style });
+    }
+    this.maxX = Math.max(this.maxX, x + chars.length - 1);
+    return true;
+  }
+
+  hline(y: number, x1: number, x2: number, style: CanvasStyle = "plain"): void {
+    const [start, end] = x1 <= x2 ? [x1, x2] : [x2, x1];
+    for (let x = start; x <= end; x += 1) {
+      this.put(x, y, "─", style);
+    }
+  }
+
+  vline(x: number, y1: number, y2: number, style: CanvasStyle = "plain"): void {
+    const [start, end] = y1 <= y2 ? [y1, y2] : [y2, y1];
+    for (let y = start; y <= end; y += 1) {
+      this.put(x, y, "│", style);
+    }
+  }
+
+  /** Render to lines; `paint` applies terminal styling per character run. */
+  render(paint: (text: string, style: CanvasStyle) => string): string[] {
+    const lines: string[] = [];
+    for (let y = 0; y <= this.maxY; y += 1) {
+      const row = this.cells.get(y);
+      if (!row || row.size === 0) {
+        lines.push("");
+        continue;
+      }
+      let line = "";
+      let runText = "";
+      let runStyle: CanvasStyle = "plain";
+      const flush = () => {
+        if (runText.length > 0) {
+          line += paint(runText, runStyle);
+          runText = "";
+        }
+      };
+      for (let x = 0; x <= this.maxX; x += 1) {
+        const cell = row.get(x);
+        const char = cell?.char ?? " ";
+        const style = cell?.style ?? "plain";
+        if (style !== runStyle) {
+          flush();
+          runStyle = style;
+        }
+        runText += char;
+      }
+      flush();
+      lines.push(line.replace(/\s+$/, ""));
+    }
+    return lines;
+  }
+}

package/src/render/format.ts

@@ -0,0 +1,19 @@
+import type { WorkflowRunState } from "../workflows/types.js";
+
+export function formatDuration(durationMs: number): string {
+  if (durationMs < 1_000) {
+    return `${Math.max(durationMs, 0)}ms`;
+  }
+  const seconds = durationMs / 1_000;
+  if (seconds < 60) {
+    return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  const rest = Math.round(seconds % 60);
+  return `${minutes}m${rest.toString().padStart(2, "0")}s`;
+}
+
+export function runElapsedMs(state: WorkflowRunState, now: Date = new Date()): number {
+  const end = state.finishedAt ? Date.parse(state.finishedAt) : now.getTime();
+  return Math.max(0, end - Date.parse(state.startedAt));
+}