pi-workflow-engine 0.5.0 → 0.7.0

package/.pi/extensions/pi-workflow-engine/src/engine.ts

@@ -5,12 +5,35 @@ import { runAgent, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
 import { createPerfRecorder, type PerfSnapshot } from "./perf.ts";
 import { defaultConcurrency, resolveWorkflowRunOptions } from "./options.ts";
-import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowRunOptions } from "./types.ts";
+import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
 import { WorkflowInspector } from "./ui/workflow-inspector.ts";
 
 /** Default global cap on concurrent agents per run. */
 const DEFAULT_CONCURRENCY = defaultConcurrency();
 
+/** The workflow-facing slice of the progress tracker (satisfied by `ProgressTracker`). */
+export interface WorkflowProgress {
+  phase(title: string): void;
+  log(message: string): void;
+  event(event: WorkflowProgressEvent): void;
+}
+
+/** Per-context knobs threaded through `runWorkflowWithContext` (and re-derived for each sub-workflow). */
+export interface WorkflowContextOptions {
+  /** Controller whose `.signal` equals `rc.signal`; aborts in-flight `parallel` siblings on failure. */
+  abortController: AbortController;
+  /** Eager-submission cap for `parallel`. */
+  submissionLimit: number;
+  /** Resolve a sub-workflow reference for `api.workflow()`. Omit to disable composition. */
+  resolveWorkflow?: (ref: WorkflowRef) => Promise<WorkflowModule>;
+  /** Nesting depth. Sub-workflows run at depth >= 1, where `api.workflow()` rejects. */
+  depth?: number;
+  /** Prefix applied to phase titles so sub-workflow phases nest as "<name> ▸ <title>". */
+  progressPrefix?: string;
+  /** Namespace applied to child structured progress keys/lanes/logs. */
+  progressNamespace?: string;
+}
+
 /**
  * Run a workflow module: build the per-run primitives (binding agent/parallel/pipeline
  * to a shared semaphore + progress tracker), invoke the workflow, return its result.
@@ -23,6 +46,8 @@ export async function runWorkflow(
 ): Promise<unknown> {
   const resolvedOptions = resolveWorkflowRunOptions(options);
   const progress = new ProgressTracker(ctx, mod.meta.name);
+  const progressSource = { snapshot: () => progress.snapshot() };
+  resolvedOptions.onProgressSource?.(progressSource);
   if (resolvedOptions.inspect && ctx.hasUI) {
     void ctx.ui
       .custom<void>(
@@ -46,36 +71,141 @@ export async function runWorkflow(
     perf,
   };
 
-  const agent = ((prompt: string, opts?: AgentOptions) => runAgent(rc, prompt, opts)) as WorkflowApi["agent"];
+  try {
+    // perf.total_ms wraps the whole tree: sub-workflows run inside this span via api.workflow().
+    return await perf.time("workflow.total_ms", () =>
+      runWorkflowWithContext(rc, progress, mod, args, {
+        abortController: runAbortController,
+        submissionLimit: resolvedOptions.parallelSubmissionLimit ?? resolvedOptions.concurrency * 2,
+        resolveWorkflow: resolvedOptions.resolveWorkflow,
+        depth: 0,
+        progressPrefix: "",
+      }),
+    );
+  } finally {
+    try {
+      const snapshot = perf.snapshot();
+      if (resolvedOptions.perf) {
+        resolvedOptions.onPerfSnapshot?.(snapshot);
+        progress.log(formatPerfSummary(snapshot));
+      }
+      progress.done();
+      resolvedOptions.onProgressSnapshot?.(progress.snapshot());
+    } finally {
+      resolvedOptions.onProgressSource?.(undefined);
+      unlinkContextAbortSignal();
+      unlinkOptionAbortSignal();
+    }
+  }
+}
+
+/**
+ * Build the `WorkflowApi` from an existing run context and invoke the module. Reused for both
+ * the top-level run and every `api.workflow()` sub-step, so children share the parent's semaphore,
+ * abort signal, and perf sink. No setup/teardown of its own — that belongs to `runWorkflow`.
+ */
+export async function runWorkflowWithContext(
+  rc: RunContext,
+  progress: WorkflowProgress,
+  mod: WorkflowModule,
+  args: string,
+  opts: WorkflowContextOptions,
+): Promise<unknown> {
+  const depth = opts.depth ?? 0;
+  const scope = createWorkflowScope(progress, opts.progressPrefix ?? "", opts.progressNamespace);
+
+  const agent = ((prompt: string, agentOpts?: AgentOptions) => runAgent(rc, prompt, scope.agentOptions(agentOpts))) as WorkflowApi["agent"];
+
+  const workflow: WorkflowApi["workflow"] =
+    depth >= 1
+      ? async () => {
+          throw new Error("workflow() can only nest one level deep");
+        }
+      : async (ref, childArgs) => {
+          if (!opts.resolveWorkflow) throw new Error("sub-workflows are not enabled in this context");
+          const childMod = await opts.resolveWorkflow(ref);
+          // A child controller isolates the child's failures from the parent (so the parent can
+          // try/catch a failed sub-workflow), while still cancelling the child when the run aborts.
+          const childController = new AbortController();
+          const unlink = linkAbortSignal(rc.signal, childController);
+          try {
+            return await runWorkflowWithContext({ ...rc, signal: childController.signal }, progress, childMod, childArgs ?? "", {
+              abortController: childController,
+              submissionLimit: opts.submissionLimit,
+              resolveWorkflow: opts.resolveWorkflow,
+              depth: depth + 1,
+              progressPrefix: `${childMod.meta.name} ▸ `,
+              progressNamespace: childMod.meta.name,
+            });
+          } finally {
+            unlink();
+            scope.restorePhase();
+          }
+        };
 
   const api: WorkflowApi = {
     agent,
+    workflow,
     parallel: (thunks) =>
       parallel(thunks, {
-        signal: runAbortController.signal,
-        abortController: runAbortController,
-        limit: resolvedOptions.parallelSubmissionLimit ?? resolvedOptions.concurrency * 2,
+        signal: rc.signal,
+        abortController: opts.abortController,
+        limit: opts.submissionLimit,
       }),
     pipeline,
-    phase: (title) => progress.phase(title),
-    log: (message) => progress.log(message),
-    progress: (event) => progress.event(event),
+    phase: scope.phase,
+    log: scope.log,
+    progress: scope.event,
     args,
-    cwd: ctx.cwd,
-    signal: runAbortController.signal,
+    cwd: rc.cwd,
+    signal: rc.signal,
   };
 
-  try {
-    return await perf.time("workflow.total_ms", () => mod.default(api));
-  } finally {
-    const snapshot = perf.snapshot();
-    if (resolvedOptions.perf) {
-      resolvedOptions.onPerfSnapshot?.(snapshot);
-      progress.log(formatPerfSummary(snapshot));
-    }
-    unlinkContextAbortSignal();
-    unlinkOptionAbortSignal();
-    progress.done();
+  return await mod.default(api);
+}
+
+interface WorkflowScope {
+  agentOptions(opts: AgentOptions | undefined): AgentOptions;
+  phase(title: string): void;
+  log(message: string): void;
+  event(event: WorkflowProgressEvent): void;
+  restorePhase(): void;
+}
+
+function createWorkflowScope(progress: WorkflowProgress, prefix: string, namespace: string | undefined): WorkflowScope {
+  let currentPhase = `${prefix}Workflow`;
+  const display = (title: string) => `${prefix}${title}`;
+  return {
+    agentOptions(opts) {
+      const phase = opts?.phase ? display(opts.phase) : currentPhase;
+      return opts ? { ...opts, phase } : { phase };
+    },
+    phase(title) {
+      currentPhase = display(title);
+      progress.phase(currentPhase);
+    },
+    log(message) {
+      progress.log(namespace ? `${namespace}: ${message}` : message);
+    },
+    event(event) {
+      progress.event(namespace ? namespaceProgressEvent(namespace, event) : event);
+    },
+    restorePhase() {
+      progress.phase(currentPhase);
+    },
+  };
+}
+
+function namespaceProgressEvent(namespace: string, event: WorkflowProgressEvent): WorkflowProgressEvent {
+  switch (event.type) {
+    case "counter":
+      return { ...event, key: `${namespace}.${event.key}` };
+    case "counter_delta":
+      return { ...event, key: `${namespace}.${event.key}` };
+    case "lane_item":
+      return { ...event, lane: `${namespace} ▸ ${event.lane}` };
+    case "summary":
+      return { ...event, key: `${namespace}.${event.key}` };
   }
 }
 

package/.pi/extensions/pi-workflow-engine/src/review/github-pr-comments.ts

@@ -0,0 +1,190 @@
+import { isCommentableIssue, type ReviewContext, type ReviewIssue } from "./review-issues.ts";
+
+export interface ExecResultLike {
+  readonly stdout: string;
+  readonly stderr?: string;
+  readonly code: number;
+  readonly killed?: boolean;
+}
+
+export type ExecLike = (
+  command: string,
+  args: string[],
+  options?: { readonly cwd?: string; readonly timeout?: number; readonly signal?: AbortSignal },
+) => Promise<ExecResultLike>;
+
+export interface GitHubPrContext {
+  readonly owner: string;
+  readonly repo: string;
+  readonly number: number;
+  readonly headSha: string;
+  readonly url?: string;
+}
+
+export type ResolveGitHubPrContextResult = { readonly ok: true; readonly context: GitHubPrContext } | { readonly ok: false; readonly reason: string };
+
+export type InlineCommentStatus =
+  | { readonly issueId: string; readonly status: "posted"; readonly url?: string }
+  | { readonly issueId: string; readonly status: "skipped"; readonly reason: string }
+  | { readonly issueId: string; readonly status: "failed"; readonly reason: string };
+
+const PR_VIEW_JSON_FIELDS = "number,headRefOid,url";
+
+export async function resolveGitHubPrContext(
+  exec: ExecLike,
+  cwd: string,
+  reviewContext: ReviewContext | undefined,
+): Promise<ResolveGitHubPrContextResult> {
+  const parsedNumber = parsePrNumber(reviewContext?.diffCommand);
+  const prArgs = parsedNumber
+    ? ["pr", "view", String(parsedNumber), "--json", PR_VIEW_JSON_FIELDS]
+    : ["pr", "view", "--json", PR_VIEW_JSON_FIELDS];
+  const prView = await runJson(exec, cwd, prArgs);
+  if (!prView.ok) return { ok: false, reason: prView.reason };
+
+  const number = numberField(prView.value, "number") ?? parsedNumber;
+  const headSha = stringField(prView.value, "headRefOid");
+  if (number === undefined) return { ok: false, reason: "No GitHub PR number found." };
+  if (!headSha) return { ok: false, reason: "GitHub PR head SHA is missing." };
+
+  const url = stringField(prView.value, "url");
+  const baseFromUrl = parsePullRequestUrl(url);
+  let owner = baseFromUrl?.owner;
+  let repo = baseFromUrl?.repo;
+  if (!owner || !repo) {
+    const repoView = await runJson(exec, cwd, ["repo", "view", "--json", "nameWithOwner"]);
+    if (!repoView.ok) return { ok: false, reason: repoView.reason };
+    const nameWithOwner = stringField(repoView.value, "nameWithOwner");
+    const parsed = parseNameWithOwner(nameWithOwner);
+    owner = owner ?? parsed?.owner;
+    repo = repo ?? parsed?.repo;
+  }
+  if (!owner || !repo) return { ok: false, reason: "GitHub repository owner/name is missing." };
+
+  return { ok: true, context: { owner, repo, number, headSha, url } };
+}
+
+export function buildInlineCommentBody(issue: ReviewIssue): string {
+  const finding = issue.finding;
+  const evidence = finding.evidence.length > 0 ? finding.evidence.map((entry) => `- ${entry}`).join("\n") : "- (none cited)";
+  return `**${issue.id}: ${finding.summary}**
+
+Severity: ${finding.severity} · Confidence: ${finding.confidence} · Category: ${finding.category}
+
+Impact: ${finding.impact}
+
+Evidence:
+${evidence}
+
+Recommendation: ${finding.recommendation}`;
+}
+
+export async function postInlineComment(
+  exec: ExecLike,
+  cwd: string,
+  prContext: GitHubPrContext,
+  issue: ReviewIssue,
+): Promise<InlineCommentStatus> {
+  if (!isCommentableIssue(issue)) return { issueId: issue.id, status: "skipped", reason: "Finding has no commentable file/line." };
+
+  const result = await runCommand(exec, cwd, [
+    "api",
+    `repos/${prContext.owner}/${prContext.repo}/pulls/${prContext.number}/comments`,
+    "-f",
+    `body=${buildInlineCommentBody(issue)}`,
+    "-f",
+    `commit_id=${prContext.headSha}`,
+    "-f",
+    `path=${issue.file}`,
+    "-F",
+    `line=${issue.line}`,
+    "-f",
+    "side=RIGHT",
+  ]);
+  if (!result.ok) return { issueId: issue.id, status: "failed", reason: result.reason };
+  return { issueId: issue.id, status: "posted", url: parsePostedCommentUrl(result.stdout) };
+}
+
+export async function postInlineComments(
+  exec: ExecLike,
+  cwd: string,
+  prContext: GitHubPrContext,
+  issues: readonly ReviewIssue[],
+): Promise<InlineCommentStatus[]> {
+  const statuses: InlineCommentStatus[] = [];
+  for (const issue of issues) {
+    statuses.push(await postInlineComment(exec, cwd, prContext, issue));
+  }
+  return statuses;
+}
+
+function parsePrNumber(diffCommand: string | undefined): number | undefined {
+  if (!diffCommand) return undefined;
+  const match = /(?:^|\s)gh\s+pr\s+diff\s+(\d+)(?:\s|$)/.exec(diffCommand);
+  if (!match) return undefined;
+  const parsed = Number(match[1]);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+async function runJson(exec: ExecLike, cwd: string, args: string[]): Promise<{ readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly reason: string }> {
+  const result = await runCommand(exec, cwd, args);
+  if (!result.ok) return result;
+  try {
+    return { ok: true, value: JSON.parse(result.stdout) };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? `Invalid gh JSON: ${error.message}` : "Invalid gh JSON." };
+  }
+}
+
+async function runCommand(exec: ExecLike, cwd: string, args: string[]): Promise<{ readonly ok: true; readonly stdout: string } | { readonly ok: false; readonly reason: string }> {
+  try {
+    const result = await exec("gh", args, { cwd, timeout: 30_000 });
+    if (result.code !== 0) return { ok: false, reason: result.stderr?.trim() || `gh exited with code ${result.code}` };
+    return { ok: true, stdout: result.stdout };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : "gh command failed." };
+  }
+}
+
+function numberField(value: unknown, key: string): number | undefined {
+  if (!isRecord(value)) return undefined;
+  const field = value[key];
+  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+}
+
+function stringField(value: unknown, key: string): string | undefined {
+  if (!isRecord(value)) return undefined;
+  const field = value[key];
+  return typeof field === "string" && field.trim().length > 0 ? field : undefined;
+}
+
+function parseNameWithOwner(value: string | undefined): { readonly owner: string; readonly repo: string } | undefined {
+  if (!value) return undefined;
+  const [owner, repo, extra] = value.split("/");
+  if (!owner || !repo || extra !== undefined) return undefined;
+  return { owner, repo };
+}
+
+function parsePullRequestUrl(value: string | undefined): { readonly owner: string; readonly repo: string } | undefined {
+  if (!value) return undefined;
+  try {
+    const parsed = new URL(value);
+    const [owner, repo, type, number, extra] = parsed.pathname.split("/").filter(Boolean);
+    if (!owner || !repo || type !== "pull" || !number || extra !== undefined) return undefined;
+    return { owner, repo };
+  } catch {
+    return undefined;
+  }
+}
+
+function parsePostedCommentUrl(stdout: string): string | undefined {
+  try {
+    return stringField(JSON.parse(stdout), "html_url");
+  } catch {
+    return undefined;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/.pi/extensions/pi-workflow-engine/src/review/review-actions.ts

@@ -0,0 +1,114 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { postInlineComments, resolveGitHubPrContext, type ExecLike, type InlineCommentStatus } from "./github-pr-comments.ts";
+import { buildCommentHandoffPrompt, buildFixHandoffPrompt } from "./review-handoff.ts";
+import { isCommentableIssue, type ReviewContext, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
+
+export type ReviewActionPi = Pick<ExtensionAPI, "sendUserMessage" | "exec">;
+export interface ReviewActionContext {
+  readonly cwd: string;
+  readonly ui: {
+    confirm(title: string, message: string): Promise<boolean>;
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+  };
+}
+
+export async function handleReviewViewerAction(
+  pi: ReviewActionPi,
+  ctx: ReviewActionContext,
+  action: ReviewIssueSelection | undefined,
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+): Promise<void> {
+  if (!action || action.action === "close") return;
+  const selected = selectedIssues(issues, action.issueIds);
+  if (action.action === "fix") {
+    handleFixAction(pi, ctx, selected, context);
+    return;
+  }
+  await handleCommentAction(pi, ctx, selected, context);
+}
+
+function handleFixAction(pi: ReviewActionPi, ctx: ReviewActionContext, selected: readonly ReviewIssue[], context: ReviewContext | undefined): void {
+  if (selected.length === 0) {
+    ctx.ui.notify("No selected findings to fix", "warning");
+    return;
+  }
+  pi.sendUserMessage(buildFixHandoffPrompt(selected, context), { deliverAs: "followUp" });
+  ctx.ui.notify(`Queued fix request for ${selected.length} selected finding(s)`, "info");
+}
+
+async function handleCommentAction(
+  pi: ReviewActionPi,
+  ctx: ReviewActionContext,
+  selected: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+): Promise<void> {
+  const commentable = selected.filter(isCommentableIssue);
+  if (commentable.length === 0) {
+    ctx.ui.notify("No selected findings have file and line information for inline PR comments", "warning");
+    return;
+  }
+
+  const confirmed = await ctx.ui.confirm(
+    "Post inline PR comments?",
+    `Post ${commentable.length} selected finding(s) to the upstream PR using GitHub CLI if available?`,
+  );
+  if (!confirmed) {
+    queueCommentFallback(pi, ctx, commentable, context, "User chose parent-agent fallback instead of direct gh posting.");
+    return;
+  }
+
+  const exec = toExecLike(pi);
+  const resolved = await resolveGitHubPrContext(exec, ctx.cwd, context);
+  if (!resolved.ok) {
+    queueCommentFallback(pi, ctx, commentable, context, resolved.reason);
+    return;
+  }
+
+  const statuses = await postInlineComments(exec, ctx.cwd, resolved.context, commentable);
+  const summary = summarizeStatuses(statuses);
+  ctx.ui.notify(`PR comments: ${summary.posted} posted, ${summary.skipped} skipped, ${summary.failed} failed`, summary.failed > 0 ? "warning" : "info");
+  if (summary.failed > 0) {
+    const failedIds = new Set(statuses.filter((status) => status.status === "failed").map((status) => status.issueId));
+    queueCommentFallback(
+      pi,
+      ctx,
+      commentable.filter((issue) => failedIds.has(issue.id)),
+      context,
+      "Direct gh posting failed for one or more selected findings.",
+    );
+  }
+}
+
+function queueCommentFallback(
+  pi: ReviewActionPi,
+  ctx: ReviewActionContext,
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+  reason: string,
+): void {
+  if (issues.length === 0) return;
+  pi.sendUserMessage(buildCommentHandoffPrompt(issues, context, reason), { deliverAs: "followUp" });
+  ctx.ui.notify(`Queued PR comment request for ${issues.length} selected finding(s)`, "info");
+}
+
+function toExecLike(pi: ReviewActionPi): ExecLike {
+  return async (command, args, options) => await pi.exec(command, args, options);
+}
+
+function selectedIssues(issues: readonly ReviewIssue[], issueIds: readonly string[]): ReviewIssue[] {
+  const selected = new Set(issueIds);
+  return issues.filter((issue) => selected.has(issue.id));
+}
+
+function summarizeStatuses(statuses: readonly InlineCommentStatus[]): { readonly posted: number; readonly skipped: number; readonly failed: number } {
+  let posted = 0;
+  let skipped = 0;
+  let failed = 0;
+  for (const status of statuses) {
+    if (status.status === "posted") posted++;
+    else if (status.status === "skipped") skipped++;
+    else failed++;
+  }
+  return { posted, skipped, failed };
+}

package/.pi/extensions/pi-workflow-engine/src/review/review-format.ts

@@ -0,0 +1,132 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { truncateDisplay, type WorkflowThemeColor } from "../ui/workflow-format.ts";
+import { formatIssueLocation, type ReviewIssue } from "./review-issues.ts";
+
+export interface RenderIssuesTableOptions {
+  readonly maxRows?: number;
+}
+
+const DEFAULT_MAX_ROWS = 12;
+const ID_WIDTH = 4;
+const SEVERITY_WIDTH = 6;
+const CONFIDENCE_WIDTH = 6;
+const CATEGORY_WIDTH = 8;
+const LOCATION_WIDTH = 30;
+const SUMMARY_WIDTH = 58;
+
+export function renderIssuesTable(issues: readonly ReviewIssue[], theme: Theme, options: RenderIssuesTableOptions = {}): string {
+  const maxRows = options.maxRows ?? DEFAULT_MAX_ROWS;
+  const visible = maxRows >= 0 ? issues.slice(0, maxRows) : issues;
+  const lines = [
+    renderRow(["ID", "Sev", "Conf", "Cat", "Location", "Summary"], theme.fg("dim", "│"), theme, true),
+    theme.fg("dim", renderSeparator()),
+  ];
+
+  for (const issue of visible) {
+    lines.push(
+      renderRow(
+        [
+          issue.id,
+          issue.finding.severity,
+          issue.finding.confidence,
+          issue.finding.category,
+          formatIssueLocation(issue),
+          issue.finding.summary,
+        ],
+        theme.fg("dim", "│"),
+        theme,
+        false,
+        issue,
+      ),
+    );
+  }
+
+  if (issues.length > visible.length) {
+    lines.push(theme.fg("dim", `… ${issues.length - visible.length} more finding(s)`));
+  }
+
+  return lines.join("\n");
+}
+
+export function renderIssueDetails(issue: ReviewIssue, theme: Theme): string {
+  return renderIssueDetailLines(issue, theme, 120).join("\n");
+}
+
+export function renderIssueDetailLines(issue: ReviewIssue, theme: Theme, width: number): string[] {
+  const finding = issue.finding;
+  const metadata = `${finding.category} · severity ${finding.severity} · confidence ${finding.confidence}`;
+  const lines = [`${theme.fg("accent", issue.id)} ${theme.fg("text", finding.summary)}`];
+  lines.push(...fieldLines("Metadata", metadata, width, theme));
+  lines.push(...fieldLines("Location", formatIssueLocation(issue), width, theme, "accent"));
+  lines.push(...fieldLines("Impact", finding.impact, width, theme));
+  lines.push(...fieldLines("Evidence", finding.evidence.join("; ") || "(none cited)", width, theme));
+  lines.push(...fieldLines("Recommendation", finding.recommendation, width, theme));
+  return lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(10, width)));
+}
+
+function fieldLines(label: string, value: string, width: number, theme: Theme, valueColor: WorkflowThemeColor = "muted"): string[] {
+  const prefix = `  ${theme.fg("dim", `${label}:`)}`;
+  const separator = " ";
+  const valueText = theme.fg(valueColor, value);
+  const available = Math.max(10, width - visibleWidth(`${label}:  `) - 2);
+  const wrapped = wrapTextWithAnsi(valueText, available);
+  if (wrapped.length === 0) return [`${prefix}${separator}`];
+  const continuation = " ".repeat(visibleWidth(`${label}:  `) + 2);
+  return wrapped.map((line, index) => (index === 0 ? `${prefix}${separator}${line}` : `${continuation}${line}`));
+}
+
+function renderRow(
+  cells: readonly [string, string, string, string, string, string],
+  separator: string,
+  theme: Theme,
+  header: boolean,
+  issue?: ReviewIssue,
+): string {
+  const rendered = [
+    cell(cells[0], ID_WIDTH),
+    colorCell(cell(cells[1], SEVERITY_WIDTH), header ? "dim" : severityColor(issue?.finding.severity ?? "low"), theme),
+    colorCell(cell(cells[2], CONFIDENCE_WIDTH), header ? "dim" : confidenceColor(issue?.finding.confidence ?? "low"), theme),
+    cell(cells[3], CATEGORY_WIDTH),
+    cell(cells[4], LOCATION_WIDTH),
+    cell(cells[5], SUMMARY_WIDTH),
+  ];
+  if (header) {
+    return rendered.map((entry) => theme.fg("dim", entry)).join(` ${separator} `);
+  }
+  return rendered.join(` ${separator} `);
+}
+
+function cell(value: string, width: number): string {
+  return truncateDisplay(value, width).padEnd(width, " ");
+}
+
+function colorCell(value: string, color: WorkflowThemeColor, theme: Theme): string {
+  return theme.fg(color, value);
+}
+
+function renderSeparator(): string {
+  return [ID_WIDTH, SEVERITY_WIDTH, CONFIDENCE_WIDTH, CATEGORY_WIDTH, LOCATION_WIDTH, SUMMARY_WIDTH].map((width) => "─".repeat(width)).join("─┼─");
+}
+
+function severityColor(severity: ReviewIssue["finding"]["severity"]): WorkflowThemeColor {
+  switch (severity) {
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}
+
+function confidenceColor(confidence: ReviewIssue["finding"]["confidence"]): WorkflowThemeColor {
+  switch (confidence) {
+    case "high":
+      return "success";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}