@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/extensions/shared/next-action-ui.ts

@@ -0,0 +1,235 @@
+/**
+ * Shared next-action prompt for Kata extensions.
+ *
+ * Renders a consistent "step complete" UI at the end of every Kata stage:
+ *
+ *   ─────────────────────────────────────────
+ *   ✓  Phase 1 research complete
+ *
+ *      [caller summary lines]
+ *
+ *      [optional extra content block]
+ *
+ *   Files written:
+ *      .kata/phases/01-foo/01-RESEARCH.md
+ *
+ *   › 1. Plan phase 1           ← recommended, pre-selected
+ *        Create PLAN.md files for execution
+ *
+ *     2. Not yet
+ *        Run /kata-plan-phase 1 when ready.
+ *   ─────────────────────────────────────────
+ *
+ * Usage:
+ *
+ *   const choice = await showNextAction(ctx, {
+ *     title: "Phase 1 research complete",
+ *     summary: ["6 libraries evaluated", "Stack: Phaser 3 + TypeScript"],
+ *     files: ["/abs/path/to/01-RESEARCH.md"],
+ *     extra: ["Wave 1: 01-01, 01-02  (parallel)", "Wave 2: 01-03"],
+ *     actions: [
+ *       { id: "plan",  label: "Plan phase 1",   description: "Create PLAN.md files for execution", recommended: true },
+ *       { id: "later", label: "Discuss first",  description: "Capture constraints before planning" },
+ *     ],
+ *     notYetMessage: "Run /kata-plan-phase 1 when ready.",
+ *   });
+ *
+ *   // choice is one of the action ids, or "not_yet"
+ *   if (choice === "plan") { ... }
+ *
+ * "Not yet" is always appended automatically as the last option.
+ * Pressing Escape also resolves as "not_yet".
+ */
+
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { type Theme } from "@mariozechner/pi-coding-agent";
+import { Key, matchesKey, type TUI } from "@mariozechner/pi-tui";
+import { makeUI } from "./ui.js";
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export interface NextAction {
+  /** Unique id returned when this action is chosen. */
+  id: string;
+  /** Short label shown in the list (e.g. "Plan phase 1"). */
+  label: string;
+  /** One-line description shown below the label. */
+  description: string;
+  /** Pre-selects this item and renders it with a (recommended) marker. At most one. */
+  recommended?: boolean;
+}
+
+export interface NextActionOptions {
+  /** Bold heading after the ✓ — e.g. "Phase 1 research complete". */
+  title: string;
+  /**
+   * Stage-specific narrative lines rendered below the title.
+   * Keep these short and informative.
+   */
+  summary?: string[];
+  /**
+   * Absolute paths to files that were written this step.
+   * Displayed as relative paths from cwd when possible.
+   */
+  files?: string[];
+  /**
+   * Optional extra content rendered between the file list and the actions.
+   * Each string is one display line — already formatted by the caller.
+   */
+  extra?: string[];
+  /** The action choices. "Not yet" is always appended automatically. */
+  actions: NextAction[];
+  /**
+   * Message shown in the "Not yet" description line.
+   * e.g. "Run /kata-plan-phase 1 when ready."
+   */
+  notYetMessage?: string;
+  /**
+   * Current working directory — used to make file paths relative.
+   * Defaults to process.cwd().
+   */
+  cwd?: string;
+}
+
+/**
+ * Show the next-action prompt and return the chosen action id, or "not_yet".
+ */
+export async function showNextAction(
+  ctx: ExtensionCommandContext,
+  opts: NextActionOptions,
+): Promise<string> {
+  const cwd = opts.cwd ?? process.cwd();
+  const notYetMessage = opts.notYetMessage ?? "Continue when ready.";
+
+  const allActions: NextAction[] = [
+    ...opts.actions,
+    { id: "not_yet", label: "Not yet", description: notYetMessage },
+  ];
+
+  const recommendedIdx = allActions.findIndex((a) => a.recommended);
+  const defaultIdx = recommendedIdx >= 0 ? recommendedIdx : 0;
+
+  const relativeFiles = (opts.files ?? []).map((f) => {
+    try {
+      const rel = f.startsWith(cwd)
+        ? f.slice(cwd.length).replace(/^\//, "")
+        : f;
+      return rel || f;
+    } catch {
+      return f;
+    }
+  });
+
+  return ctx.ui.custom<string>((_tui: TUI, theme: Theme, _kb, done) => {
+    let cursorIdx = defaultIdx;
+    let cachedLines: string[] | undefined;
+
+    function refresh() {
+      cachedLines = undefined;
+      _tui.requestRender();
+    }
+
+    function handleInput(data: string) {
+      if (matchesKey(data, Key.up)) {
+        cursorIdx = Math.max(0, cursorIdx - 1);
+        refresh();
+        return;
+      }
+      if (matchesKey(data, Key.down)) {
+        cursorIdx = Math.min(allActions.length - 1, cursorIdx + 1);
+        refresh();
+        return;
+      }
+      const num = parseInt(data, 10);
+      if (!isNaN(num) && num >= 1 && num <= allActions.length) {
+        done(allActions[num - 1].id);
+        return;
+      }
+      if (matchesKey(data, Key.enter) || matchesKey(data, Key.space)) {
+        done(allActions[cursorIdx].id);
+        return;
+      }
+      if (matchesKey(data, Key.escape)) {
+        done("not_yet");
+        return;
+      }
+    }
+
+    function render(width: number): string[] {
+      if (cachedLines) return cachedLines;
+      const ui = makeUI(theme, width);
+      const lines: string[] = [];
+      const push = (...rows: string[][]) => {
+        for (const r of rows) lines.push(...r);
+      };
+
+      // ── Header — uses success colour to signal completion ────────────
+      // Note: next-action intentionally uses "success" for its bar/title
+      // to distinguish it from regular accent-coloured screens.
+      push(ui.bar());
+      push(ui.blank());
+      push(ui.header(`  ✓  ${opts.title}`));
+
+      // ── Summary ──────────────────────────────────────────────────────
+      if (opts.summary && opts.summary.length > 0) {
+        push(ui.blank());
+        for (const line of opts.summary) push(ui.subtitle(`     ${line}`));
+      }
+
+      // ── Files written ─────────────────────────────────────────────────
+      if (relativeFiles.length > 0) {
+        push(ui.blank());
+        push(ui.meta("  Files written:"));
+        for (const f of relativeFiles) push(ui.meta(`     ${f}`));
+      }
+
+      // ── Extra content ─────────────────────────────────────────────────
+      if (opts.extra && opts.extra.length > 0) {
+        push(ui.blank());
+        for (const line of opts.extra) push(ui.subtitle(`  ${line}`));
+      }
+
+      // ── Actions ───────────────────────────────────────────────────────
+      push(ui.blank());
+      for (let i = 0; i < allActions.length; i++) {
+        const action = allActions[i];
+        const isSelected = i === cursorIdx;
+        const isNotYet = action.id === "not_yet";
+        const tag = action.recommended ? "(recommended)" : undefined;
+
+        if (isSelected) {
+          push(ui.actionSelected(i + 1, action.label, action.description, tag));
+        } else if (isNotYet) {
+          push(ui.actionDim(i + 1, action.label, action.description));
+        } else {
+          push(
+            ui.actionUnselected(i + 1, action.label, action.description, tag),
+          );
+        }
+        push(ui.blank());
+      }
+
+      // ── Footer ────────────────────────────────────────────────────────
+      const numHint = allActions.map((_, i) => `${i + 1}`).join("/");
+      push(
+        ui.hints([
+          `↑/↓ to choose`,
+          `${numHint} to quick-select`,
+          `enter to confirm`,
+        ]),
+      );
+      push(ui.bar());
+
+      cachedLines = lines;
+      return lines;
+    }
+
+    return {
+      render,
+      invalidate: () => {
+        cachedLines = undefined;
+      },
+      handleInput,
+    };
+  });
+}

package/src/resources/extensions/shared/progress-widget.ts

@@ -0,0 +1,282 @@
+/**
+ * Shared persistent progress/status panel widget.
+ *
+ * Renders an ordered list of progress items with status glyphs, optional
+ * badge, subtitle, metadata, and footer hints. Supports pulse animation
+ * for active items during agent execution.
+ *
+ * Usage:
+ *
+ *   import { createProgressPanel } from "./shared/progress-widget.js";
+ *
+ *   const panel = createProgressPanel(ctx.ui, {
+ *     widgetKey: "workflow",
+ *     statusKey: "workflow",
+ *     statusPrefix: "wf",
+ *   });
+ *
+ *   panel.update(model);       // render/re-render with new model
+ *   panel.startPulse();        // animate active items
+ *   panel.stopPulse();         // stop animation
+ *   panel.dispose();           // remove widget and status
+ */
+
+import type { ExtensionUIContext, Theme } from "@mariozechner/pi-coding-agent";
+import type { TUI } from "@mariozechner/pi-tui";
+import { makeUI, type ProgressStatus } from "./ui.js";
+
+// ─── Exported types ───────────────────────────────────────────────────────────
+
+export type ProgressItemStatus = ProgressStatus;
+
+export interface ProgressItem {
+	/** Display label */
+	label: string;
+	/** Drives glyph and color */
+	status: ProgressItemStatus;
+	/** Optional text after label — e.g. artifact type, task ID */
+	detail?: string;
+	/** Optional secondary line below item — e.g. "waiting for /workflow-continue" */
+	annotation?: string;
+}
+
+export interface ProgressPanelModel {
+	/** Panel title */
+	title: string;
+	/** Optional badge next to title — e.g. "RUNNING", "PAUSED" */
+	badge?: string;
+	/** Badge color control — maps to ProgressItemStatus color */
+	badgeStatus?: ProgressItemStatus;
+	/** Optional subtitle lines below title */
+	subtitle?: string[];
+	/** Ordered progress items */
+	items: ProgressItem[];
+	/** Optional metadata lines below items */
+	meta?: string[];
+	/** Optional footer hint strings */
+	hints?: string[];
+}
+
+export interface ProgressPanelOptions {
+	/**
+	 * Widget key used with ctx.ui.setWidget(...).
+	 * Must be unique per extension.
+	 */
+	widgetKey: string;
+	/**
+	 * Status key used with ctx.ui.setStatus(...).
+	 * Must be unique per extension.
+	 */
+	statusKey: string;
+	/**
+	 * Short prefix for footer status text.
+	 * Example: "wf" produces "wf:2/3 RUNNING"
+	 */
+	statusPrefix: string;
+}
+
+export interface ProgressPanel {
+	/** Update the widget with a new model. Triggers re-render. */
+	update(model: ProgressPanelModel): void;
+	/** Start pulsing items with status "active". */
+	startPulse(): void;
+	/** Stop pulsing. Active items render at full brightness. */
+	stopPulse(): void;
+	/** Remove the widget and status from the UI. */
+	dispose(): void;
+}
+
+// ─── Internal constants ───────────────────────────────────────────────────────
+
+const PULSE_INTERVAL_MS = 500;
+
+// ─── Implementation ───────────────────────────────────────────────────────────
+
+/**
+ * Create and register a persistent progress widget.
+ *
+ * @param ui       The `ctx.ui` object from ExtensionContext or ExtensionCommandContext
+ * @param options  Widget key, status key, and status prefix
+ * @returns        ProgressPanel controller
+ */
+export function createProgressPanel(
+	ui: ExtensionUIContext,
+	options: ProgressPanelOptions,
+): ProgressPanel {
+	const { widgetKey, statusKey, statusPrefix } = options;
+
+	// ── Internal state ────────────────────────────────────────────────────────
+
+	let currentModel: ProgressPanelModel | null = null;
+	let stateVersion = 0;
+	let cachedLines: string[] | undefined;
+	let cachedWidth: number | undefined;
+	let cachedVersion = -1;
+	let pulseBright = true;
+	let pulseTimer: ReturnType<typeof setInterval> | null = null;
+	let widgetRef: { invalidate: () => void; requestRender: () => void } | null = null;
+
+	// ── Footer status ─────────────────────────────────────────────────────────
+
+	function updateFooterStatus(): void {
+		if (!currentModel) return;
+		const { items, badge } = currentModel;
+		const total = items.length;
+		let current = 0;
+
+		// Find first active item index (1-based)
+		const activeIdx = items.findIndex((it) => it.status === "active");
+		if (activeIdx >= 0) {
+			current = activeIdx + 1;
+		} else {
+			// Count done items + 1
+			current = items.filter((it) => it.status === "done").length + 1;
+		}
+		if (current > total) current = total;
+
+		const badgePart = badge ? ` ${badge}` : "";
+		const statusText = ui.theme.fg("accent", `${statusPrefix}:${current}/${total}${badgePart}`);
+		ui.setStatus(statusKey, statusText);
+	}
+
+	// ── Render function ───────────────────────────────────────────────────────
+
+	function renderPanel(width: number, theme: Theme): string[] {
+		// Version-based cache check
+		if (cachedLines && cachedWidth === width && cachedVersion === stateVersion) {
+			return cachedLines;
+		}
+
+		if (!currentModel) return [];
+
+		const uiHelper = makeUI(theme, width);
+		const lines: string[] = [];
+		const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
+		const model = currentModel;
+
+		// 1. Top bar
+		push(uiHelper.bar());
+
+		// 2. Title area — title with optional inline badge
+		if (model.badge && model.badgeStatus) {
+			const titleText = uiHelper.header(model.title)[0];
+			const badgeGlyph = uiHelper.statusGlyph(model.badgeStatus);
+			const badgeLabel = uiHelper.statusBadge(model.badge, model.badgeStatus)[0];
+			lines.push(`${titleText}  ${badgeGlyph} ${badgeLabel.trimStart()}`);
+		} else {
+			push(uiHelper.header(model.title));
+		}
+
+		// 3. Subtitle
+		if (model.subtitle?.length) {
+			for (const line of model.subtitle) {
+				push(uiHelper.meta(line));
+			}
+		}
+
+		// 4. Blank line
+		push(uiHelper.blank());
+
+		// 5. Items
+		for (const item of model.items) {
+			// Pulse: when pulseBright is false and item is active, render as pending (dimmed)
+			const renderStatus: ProgressStatus = (!pulseBright && item.status === "active")
+				? "pending"
+				: item.status;
+
+			push(uiHelper.progressItem(item.label, renderStatus, {
+				detail: item.detail,
+				emphasized: item.status === "active",
+			}));
+
+			if (item.annotation) {
+				push(uiHelper.progressAnnotation(item.annotation));
+			}
+		}
+
+		// 6. Blank line (if meta or hints follow)
+		if (model.meta?.length || model.hints?.length) {
+			push(uiHelper.blank());
+		}
+
+		// 7. Meta
+		if (model.meta?.length) {
+			for (const line of model.meta) {
+				push(uiHelper.meta(line));
+			}
+		}
+
+		// 8. Hints
+		if (model.hints?.length) {
+			push(uiHelper.hints(model.hints));
+		}
+
+		// 9. Bottom bar
+		push(uiHelper.bar());
+
+		cachedLines = lines;
+		cachedWidth = width;
+		cachedVersion = stateVersion;
+		return lines;
+	}
+
+	// ── Register widget ───────────────────────────────────────────────────────
+
+	ui.setWidget(widgetKey, (tui: TUI, theme: Theme) => {
+		widgetRef = {
+			invalidate: () => { cachedLines = undefined; },
+			requestRender: () => tui.requestRender(),
+		};
+
+		return {
+			render(width: number): string[] {
+				return renderPanel(width, theme);
+			},
+			invalidate() {
+				cachedLines = undefined;
+			},
+		};
+	});
+
+	// ── Controller ────────────────────────────────────────────────────────────
+
+	return {
+		update(model: ProgressPanelModel): void {
+			currentModel = model;
+			stateVersion++;
+			cachedLines = undefined;
+			updateFooterStatus();
+			if (widgetRef) widgetRef.requestRender();
+		},
+
+		startPulse(): void {
+			if (pulseTimer) return; // already pulsing
+			pulseTimer = setInterval(() => {
+				pulseBright = !pulseBright;
+				cachedLines = undefined;
+				if (widgetRef) widgetRef.requestRender();
+			}, PULSE_INTERVAL_MS);
+		},
+
+		stopPulse(): void {
+			if (pulseTimer) {
+				clearInterval(pulseTimer);
+				pulseTimer = null;
+			}
+			pulseBright = true;
+			cachedLines = undefined;
+			if (widgetRef) widgetRef.requestRender();
+		},
+
+		dispose(): void {
+			if (pulseTimer) {
+				clearInterval(pulseTimer);
+				pulseTimer = null;
+			}
+			ui.setWidget(widgetKey, undefined);
+			ui.setStatus(statusKey, undefined);
+			currentModel = null;
+			widgetRef = null;
+		},
+	};
+}

package/src/resources/extensions/shared/thinking-widget.ts

@@ -0,0 +1,107 @@
+/**
+ * Shared thinking/spinner widget.
+ *
+ * Shows an animated spinner with a label and an optional live-preview of
+ * streamed text (e.g. LLM output) while a background operation is running.
+ *
+ * Usage:
+ *
+ *   import { showThinkingWidget } from "./shared/thinking-widget.js";
+ *
+ *   const widget = showThinkingWidget("Generating questions…", ctx);
+ *
+ *   // Optionally stream partial text into the preview line:
+ *   widget.setText(partialLlmOutput);
+ *
+ *   // Always dispose when done — removes the widget from the UI:
+ *   widget.dispose();
+ *
+ * Each call gets a unique widget key derived from a monotonic counter, so
+ * multiple widgets can safely coexist without key collisions.
+ */
+
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { type Theme } from "@mariozechner/pi-coding-agent";
+import { truncateToWidth, type TUI } from "@mariozechner/pi-tui";
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export interface ThinkingWidget {
+	/**
+	 * Update the streamed-text preview line.
+	 * Pass the full accumulated text — the widget trims and previews the tail.
+	 */
+	setText(text: string): void;
+	/** Remove the widget from the UI. Always call this when the operation completes. */
+	dispose(): void;
+}
+
+// ─── Internal constants ───────────────────────────────────────────────────────
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+const SPINNER_INTERVAL_MS = 80;
+const PREVIEW_MAX_CHARS = 120;
+
+let widgetCounter = 0;
+
+// ─── Implementation ───────────────────────────────────────────────────────────
+
+/**
+ * Show an animated thinking spinner as a TUI widget.
+ *
+ * @param label  Short description of what is happening, e.g. "Writing PROJECT.md…"
+ * @param ctx    Extension command context
+ * @returns      Handle with setText() and dispose()
+ */
+export function showThinkingWidget(label: string, ctx: ExtensionCommandContext): ThinkingWidget {
+	const widgetKey = `thinking-widget-${++widgetCounter}`;
+
+	let streamedText = "";
+	let widgetRef: { invalidate: () => void; requestRender: () => void } | null = null;
+
+	ctx.ui.setWidget(widgetKey, (tui: TUI, theme: Theme) => {
+		let frame = 0;
+		let cachedLines: string[] | undefined;
+
+		const interval = setInterval(() => {
+			frame = (frame + 1) % SPINNER_FRAMES.length;
+			cachedLines = undefined;
+			tui.requestRender();
+		}, SPINNER_INTERVAL_MS);
+
+		widgetRef = {
+			invalidate: () => { cachedLines = undefined; },
+			requestRender: () => tui.requestRender(),
+		};
+
+		return {
+			render(width: number): string[] {
+				if (cachedLines) return cachedLines;
+				const spinner = theme.fg("accent", SPINNER_FRAMES[frame]);
+				const lines: string[] = [];
+				lines.push(truncateToWidth(`  ${spinner} ${theme.fg("muted", label)}`, width));
+				if (streamedText) {
+					const preview = streamedText.replace(/\s+/g, " ").trim().slice(-PREVIEW_MAX_CHARS);
+					lines.push(truncateToWidth(`  ${theme.fg("dim", preview)}`, width));
+				}
+				cachedLines = lines;
+				return lines;
+			},
+			invalidate() { cachedLines = undefined; },
+			dispose() { clearInterval(interval); },
+		};
+	});
+
+	return {
+		setText(text: string) {
+			streamedText = text;
+			if (widgetRef) {
+				widgetRef.invalidate();
+				widgetRef.requestRender();
+			}
+		},
+		dispose() {
+			ctx.ui.setWidget(widgetKey, undefined);
+		},
+	};
+}