@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/extensions/shared/wizard-ui.ts

@@ -0,0 +1,551 @@
+/**
+ * General-purpose multi-page wizard UI.
+ *
+ * Supports declarative page definitions with select and text fields.
+ * Pages can conditionally route to different next pages based on answers.
+ *
+ * Navigation:
+ *   ←           go back one page (on page 1: triggers exit confirmation)
+ *   → / Enter   advance to next page (or submit on last page)
+ *   Escape      triggers exit confirmation overlay
+ *
+ * Exit confirmation (shown on Escape or ← from page 1):
+ *   1. Go back  — dismiss and return to current page
+ *   2. Exit     — cancel the wizard, returns null to caller
+ *
+ * Returns:
+ *   Record<pageId, Record<fieldId, string | string[]>>  on completion
+ *   null                                                 on exit/cancel
+ *
+ * Example:
+ *
+ *   const result = await showWizard(ctx, {
+ *     title: "New Project",
+ *     pages: [
+ *       {
+ *         id: "mode",
+ *         fields: [
+ *           {
+ *             type: "select",
+ *             id: "start_type",
+ *             question: "How do you want to start?",
+ *             options: [
+ *               { label: "Describe it", description: "Type what you want to build." },
+ *               { label: "Provide a file", description: "Point to an existing doc." },
+ *             ],
+ *           },
+ *         ],
+ *         next: (answers) =>
+ *           answers["mode"]?.["start_type"] === "Provide a file" ? "file_path" : null,
+ *       },
+ *       {
+ *         id: "file_path",
+ *         fields: [
+ *           { type: "text", id: "path", label: "File path", placeholder: "/path/to/doc.md" },
+ *         ],
+ *         next: () => null,
+ *       },
+ *     ],
+ *   });
+ *
+ *   if (!result) return; // user exited
+ *   const startType = result["mode"]["start_type"]; // "Describe it" | "Provide a file"
+ *   const filePath  = result["file_path"]?.["path"];
+ */
+
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { type Theme } from "@mariozechner/pi-coding-agent";
+import {
+	Editor,
+	Key,
+	matchesKey,
+	truncateToWidth,
+	type TUI,
+} from "@mariozechner/pi-tui";
+import { makeUI } from "./ui.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+export interface WizardOption {
+	label: string;
+	description: string;
+}
+
+export interface SelectField {
+	type: "select";
+	id: string;
+	question: string;
+	options: WizardOption[];
+	/** Allow multiple selections. Default: false. */
+	allowMultiple?: boolean;
+}
+
+export interface TextField {
+	type: "text";
+	id: string;
+	label: string;
+	placeholder?: string;
+}
+
+export type WizardField = SelectField | TextField;
+
+/** Answers collected so far: pageId → fieldId → value */
+export type WizardAnswers = Record<string, Record<string, string | string[]>>;
+
+export interface WizardPage {
+	id: string;
+	/** Optional subtitle shown below the wizard title for this page. */
+	subtitle?: string;
+	fields: WizardField[];
+	/**
+	 * Return the id of the next page, or null to end the wizard.
+	 * Called with all answers collected so far when the user advances.
+	 * If omitted, the wizard ends after this page.
+	 */
+	next?: (answers: WizardAnswers) => string | null;
+}
+
+export interface WizardOptions {
+	/** Title shown at the top of every page. */
+	title: string;
+	/** Ordered page definitions. Pages are navigated in order unless next() routes elsewhere. */
+	pages: WizardPage[];
+}
+
+// ─── Internal state ───────────────────────────────────────────────────────────
+
+interface SelectState {
+	cursorIndex: number;
+	/** Single-select: committed option index, null if not yet chosen */
+	committedIndex: number | null;
+	/** Multi-select: which indices are checked */
+	checkedIndices: Set<number>;
+}
+
+interface PageState {
+	selectStates: Map<string, SelectState>;
+	textValues: Map<string, string>;
+	/** Which field is focused (for text fields) */
+	focusedFieldId: string | null;
+}
+
+// ─── Main export ──────────────────────────────────────────────────────────────
+
+/**
+ * Show a multi-page wizard and return collected answers, or null if the user exits.
+ */
+export async function showWizard(
+	ctx: ExtensionCommandContext,
+	opts: WizardOptions,
+): Promise<WizardAnswers | null> {
+	const pageMap = new Map<string, WizardPage>(opts.pages.map((p) => [p.id, p]));
+
+	return ctx.ui.custom<WizardAnswers | null>((tui: TUI, theme: Theme, _kb, done) => {
+		// ── State ──────────────────────────────────────────────────────────────
+
+		/** Stack of page ids visited — drives back navigation */
+		const pageStack: string[] = [opts.pages[0].id];
+		const pageStates = new Map<string, PageState>();
+		/** Collected answers across all pages */
+		const answers: WizardAnswers = {};
+		/** Whether the exit-confirmation overlay is showing */
+		let showingExitConfirm = false;
+		/** Cursor in the exit-confirm overlay: 0 = go back, 1 = exit */
+		let exitCursor = 0;
+
+		let cachedLines: string[] | undefined;
+
+		// Editors keyed by fieldId — one per text field
+		// editorTheme is derived from the design system at first render
+		const editors = new Map<string, Editor>();
+		let resolvedEditorTheme: import("@mariozechner/pi-tui").EditorTheme | null = null;
+
+		function getEditor(fieldId: string): Editor {
+			if (!resolvedEditorTheme) resolvedEditorTheme = makeUI(theme, 80).editorTheme;
+			if (!editors.has(fieldId)) editors.set(fieldId, new Editor(tui, resolvedEditorTheme));
+			return editors.get(fieldId)!;
+		}
+
+		// ── Page state helpers ─────────────────────────────────────────────────
+
+		function getPageState(pageId: string): PageState {
+			if (!pageStates.has(pageId)) {
+				pageStates.set(pageId, {
+					selectStates: new Map(),
+					textValues: new Map(),
+					focusedFieldId: null,
+				});
+			}
+			return pageStates.get(pageId)!;
+		}
+
+		function getSelectState(pageId: string, fieldId: string, _optCount: number): SelectState {
+			const ps = getPageState(pageId);
+			if (!ps.selectStates.has(fieldId)) {
+				ps.selectStates.set(fieldId, {
+					cursorIndex: 0,
+					committedIndex: null, // nothing pre-committed — user must explicitly confirm
+					checkedIndices: new Set(),
+				});
+			}
+			return ps.selectStates.get(fieldId)!;
+		}
+
+		// ── Current page ───────────────────────────────────────────────────────
+
+		function currentPageId(): string {
+			return pageStack[pageStack.length - 1];
+		}
+
+		function currentPage(): WizardPage {
+			return pageMap.get(currentPageId())!;
+		}
+
+		function currentPageState(): PageState {
+			return getPageState(currentPageId());
+		}
+
+		// ── Validation ─────────────────────────────────────────────────────────
+
+		function isPageComplete(page: WizardPage, ps: PageState): boolean {
+			for (const field of page.fields) {
+				if (field.type === "select") {
+					const ss = ps.selectStates.get(field.id);
+					if (!ss) return false;
+					if (field.allowMultiple) {
+						if (ss.checkedIndices.size === 0) return false;
+					} else {
+						if (ss.committedIndex === null) return false;
+					}
+				} else {
+					const val = ps.textValues.get(field.id) ?? "";
+					if (!val.trim()) return false;
+				}
+			}
+			return true;
+		}
+
+		// ── Collect answers for a page ─────────────────────────────────────────
+
+		function collectPageAnswers(page: WizardPage, ps: PageState): Record<string, string | string[]> {
+			const result: Record<string, string | string[]> = {};
+			for (const field of page.fields) {
+				if (field.type === "select") {
+					const ss = ps.selectStates.get(field.id);
+					if (!ss) continue;
+					if (field.allowMultiple) {
+						result[field.id] = Array.from(ss.checkedIndices)
+							.sort((a, b) => a - b)
+							.map((i) => field.options[i].label);
+					} else {
+						if (ss.committedIndex !== null && ss.committedIndex < field.options.length) {
+							result[field.id] = field.options[ss.committedIndex].label;
+						}
+					}
+				} else {
+					result[field.id] = ps.textValues.get(field.id) ?? "";
+				}
+			}
+			return result;
+		}
+
+		// ── Auto-focus helper ──────────────────────────────────────────────────
+
+		/** If a page's first field is a text field, focus it immediately on arrival. */
+		function autoFocusPageIfText(pageId: string) {
+			const page = pageMap.get(pageId);
+			if (!page) return;
+			const firstField = page.fields[0];
+			if (firstField?.type === "text") {
+				const ps = getPageState(pageId);
+				ps.focusedFieldId = firstField.id;
+				const editor = getEditor(firstField.id);
+				editor.setText(ps.textValues.get(firstField.id) ?? "");
+			}
+		}
+
+		// Auto-focus the first page if it starts with a text field
+		autoFocusPageIfText(opts.pages[0].id);
+
+		// ── Navigation ─────────────────────────────────────────────────────────
+
+		function advance() {
+			const page = currentPage();
+			const ps = currentPageState();
+			if (!isPageComplete(page, ps)) {
+				refresh();
+				return;
+			}
+
+			// Save text field values from editors
+			for (const field of page.fields) {
+				if (field.type === "text") {
+					ps.textValues.set(field.id, getEditor(field.id).getText().trim());
+				}
+			}
+
+			// Collect answers for this page
+			answers[page.id] = collectPageAnswers(page, ps);
+
+			// Route to next page
+			const nextId = page.next ? page.next(answers) : null;
+			if (!nextId) {
+				// End of wizard
+				done(answers);
+				return;
+			}
+
+			const nextPage = pageMap.get(nextId);
+			if (!nextPage) {
+				done(answers);
+				return;
+			}
+
+			pageStack.push(nextId);
+			autoFocusPageIfText(nextId);
+			refresh();
+		}
+
+		function goBack() {
+			if (pageStack.length <= 1) {
+				// Already at first page — Esc here means exit
+				showingExitConfirm = true;
+				exitCursor = 0;
+				refresh();
+				return;
+			}
+			pageStack.pop();
+			autoFocusPageIfText(currentPageId());
+			refresh();
+		}
+
+		function refresh() {
+			cachedLines = undefined;
+			tui.requestRender();
+		}
+
+		// ── Input handler ──────────────────────────────────────────────────────
+
+		function handleInput(data: string) {
+			// ── Exit confirm overlay ─────────────────────────────────────────
+			if (showingExitConfirm) {
+				if (matchesKey(data, Key.up)) { exitCursor = 0; refresh(); return; }
+				if (matchesKey(data, Key.down)) { exitCursor = 1; refresh(); return; }
+				if (data === "1") { showingExitConfirm = false; refresh(); return; }
+				if (data === "2") { done(null); return; }
+				if (matchesKey(data, Key.enter) || matchesKey(data, Key.space)) {
+					if (exitCursor === 0) { showingExitConfirm = false; refresh(); }
+					else { done(null); }
+					return;
+				}
+				// Esc on the confirm screen = go back (dismiss confirm)
+				if (matchesKey(data, Key.escape)) { showingExitConfirm = false; refresh(); return; }
+				return;
+			}
+
+			// ── Text field focus ─────────────────────────────────────────────
+			const ps = currentPageState();
+			if (ps.focusedFieldId) {
+				const editor = getEditor(ps.focusedFieldId);
+				if (matchesKey(data, Key.escape)) {
+					// First Esc: unfocus the text field
+					ps.textValues.set(ps.focusedFieldId, editor.getText().trim());
+					ps.focusedFieldId = null;
+					refresh();
+					return;
+				}
+				if (matchesKey(data, Key.enter)) {
+					ps.textValues.set(ps.focusedFieldId, editor.getText().trim());
+					ps.focusedFieldId = null;
+					advance();
+					return;
+				}
+				editor.handleInput(data);
+				refresh();
+				return;
+			}
+
+			// ── Esc with no text field focused: go back (or exit if on page 1) ──
+			if (matchesKey(data, Key.escape)) { goBack(); return; }
+
+			// ── Enter / → to advance ─────────────────────────────────────────
+			if (matchesKey(data, Key.enter) || matchesKey(data, Key.right)) {
+				// For single-select fields, commit cursor before advancing
+				const page = currentPage();
+				for (const field of page.fields) {
+					if (field.type === "select" && !field.allowMultiple) {
+						const ss = getSelectState(currentPageId(), field.id, field.options.length);
+						if (ss.committedIndex === null) ss.committedIndex = ss.cursorIndex;
+					}
+				}
+				advance();
+				return;
+			}
+
+			// ── Select field interactions ────────────────────────────────────
+			const page = currentPage();
+			for (const field of page.fields) {
+				if (field.type !== "select") continue;
+				const ss = getSelectState(currentPageId(), field.id, field.options.length);
+				const totalOpts = field.options.length;
+
+				if (matchesKey(data, Key.up)) {
+					ss.cursorIndex = (ss.cursorIndex - 1 + totalOpts) % totalOpts;
+					refresh(); return;
+				}
+				if (matchesKey(data, Key.down)) {
+					ss.cursorIndex = (ss.cursorIndex + 1) % totalOpts;
+					refresh(); return;
+				}
+
+				if (field.allowMultiple) {
+					if (matchesKey(data, Key.space)) {
+						if (ss.checkedIndices.has(ss.cursorIndex)) ss.checkedIndices.delete(ss.cursorIndex);
+						else ss.checkedIndices.add(ss.cursorIndex);
+						refresh(); return;
+					}
+				} else {
+					// Numeric shortcut: press the number to select and immediately advance
+					if (data.length === 1 && data >= "1" && data <= "9") {
+						const idx = parseInt(data, 10) - 1;
+						if (idx < totalOpts) {
+							ss.cursorIndex = idx;
+							ss.committedIndex = idx;
+							advance();
+							return;
+						}
+					}
+					// Enter/Space commit cursor and advance (Enter handled above, Space here)
+					if (matchesKey(data, Key.space)) {
+						ss.committedIndex = ss.cursorIndex;
+						advance();
+						return;
+					}
+				}
+				// Only handle the first select field for nav
+				break;
+			}
+		}
+
+		// ── Render ─────────────────────────────────────────────────────────────
+
+		function renderExitConfirm(width: number): string[] {
+			const ui = makeUI(theme, width);
+			const lines: string[] = [];
+			const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
+
+			push(
+				ui.bar(), ui.blank(),
+				ui.header("  Exit wizard?"),
+				ui.blank(),
+				ui.subtitle("  Your progress will be lost."),
+				ui.blank(),
+			);
+
+			if (exitCursor === 0) push(ui.actionSelected(1, "Go back", "Return to where you were."));
+			else push(ui.actionUnselected(1, "Go back", "Return to where you were."));
+			push(ui.blank());
+			if (exitCursor === 1) push(ui.actionSelected(2, "Exit", "Cancel and discard all answers."));
+			else push(ui.actionUnselected(2, "Exit", "Cancel and discard all answers."));
+			push(
+				ui.blank(),
+				ui.hints(["↑/↓ to choose", "1/2 to quick-select", "enter to confirm"]),
+				ui.bar(),
+			);
+			return lines;
+		}
+
+		function renderSelectField(ui: ReturnType<typeof makeUI>, field: SelectField, lines: string[]) {
+			const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
+			const ss = getSelectState(currentPageId(), field.id, field.options.length);
+			const multi = !!field.allowMultiple;
+
+			push(ui.question(`  ${field.question}`));
+			if (multi) push(ui.meta("  (select all that apply — space to toggle, enter to confirm)"));
+			push(ui.blank());
+
+			for (let i = 0; i < field.options.length; i++) {
+				const opt = field.options[i];
+				const isCursor = i === ss.cursorIndex;
+				const isCommitted = i === ss.committedIndex;
+
+				if (multi) {
+					const isChecked = ss.checkedIndices.has(i);
+					if (isCursor) push(ui.checkboxSelected(opt.label, opt.description, isChecked));
+					else push(ui.checkboxUnselected(opt.label, opt.description, isChecked));
+				} else {
+					if (isCursor) push(ui.optionSelected(i + 1, opt.label, opt.description, isCommitted));
+					else push(ui.optionUnselected(i + 1, opt.label, opt.description, { isCommitted }));
+				}
+			}
+		}
+
+		function renderTextField(ui: ReturnType<typeof makeUI>, field: TextField, ps: PageState, lines: string[], width: number) {
+			const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
+			const isFocused = ps.focusedFieldId === field.id;
+			const value = isFocused ? getEditor(field.id).getText() : (ps.textValues.get(field.id) ?? "");
+
+			push(ui.question(`  ${field.label}`), ui.blank());
+
+			if (isFocused) {
+				for (const line of getEditor(field.id).render(width - 2)) lines.push(truncateToWidth(` ${line}`, width));
+			} else if (value) {
+				push(ui.answer(`  ${value}`));
+			} else if (field.placeholder) {
+				push(ui.meta(`  ${field.placeholder}`));
+			}
+		}
+
+		function render(width: number): string[] {
+			if (cachedLines) return cachedLines;
+			if (showingExitConfirm) { cachedLines = renderExitConfirm(width); return cachedLines; }
+
+			const ui = makeUI(theme, width);
+			const lines: string[] = [];
+			const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
+
+			push(ui.bar(), ui.header(`  ${opts.title}`));
+
+			// ── Page indicator ────────────────────────────────────────────────
+			if (opts.pages.length > 1) {
+				push(ui.pageDots(opts.pages.length, pageStack.length - 1));
+			}
+
+			// ── Page content ──────────────────────────────────────────────────
+			const page = currentPage();
+			const ps = currentPageState();
+
+			if (page.subtitle) { push(ui.blank(), ui.subtitle(`  ${page.subtitle}`)); }
+			push(ui.blank());
+
+			for (const field of page.fields) {
+				if (field.type === "select") renderSelectField(ui, field, lines);
+				else renderTextField(ui, field, ps, lines, width);
+				push(ui.blank());
+			}
+
+			// ── Footer hints ──────────────────────────────────────────────────
+			const isFirst = pageStack.length === 1;
+			const ps2 = currentPageState();
+			const hints: string[] = [];
+			if (ps2.focusedFieldId) {
+				hints.push("enter to continue");
+				hints.push("esc to unfocus");
+			} else {
+				hints.push("↑/↓ to move");
+				hints.push("enter to select");
+				hints.push(!isFirst ? "esc to go back" : "esc to exit");
+			}
+			push(ui.hints(hints), ui.bar());
+
+			cachedLines = lines;
+			return lines;
+		}
+
+		return {
+			render,
+			invalidate: () => { cachedLines = undefined; },
+			handleInput,
+		};
+	});
+}

package/src/resources/extensions/slash-commands/audit.ts

@@ -0,0 +1,92 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+
+export default function auditCommand(pi: ExtensionAPI) {
+  pi.registerCommand("audit", {
+    description:
+      "Audit the current codebase against a specific goal and write a structured report to .kata/audits/",
+    async handler(args: string, ctx: ExtensionCommandContext) {
+      // ── Step 1: Get the audit goal ────────────────────────────────────────
+
+      let goal = (typeof args === "string" ? args : "").trim();
+
+      if (!goal) {
+        const input = await ctx.ui.input(
+          "What is the audit goal?",
+          "e.g. understand performance bottlenecks before planning a roadmap",
+        );
+        if (!input?.trim()) {
+          ctx.ui.notify("audit: No goal provided — cancelled.", "error");
+          return;
+        }
+        goal = input.trim();
+      }
+
+      // ── Step 2: Build output path (.kata/audits/<timestamp>-<slug>.md) ────
+
+      const now = new Date();
+      const timestamp = now
+        .toISOString()
+        .replace(/T/, "-")
+        .replace(/:/g, "")
+        .replace(/\..+/, "");
+
+      const slug = goal
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+
+      const outputPath = `.kata/audits/${timestamp}-${slug}.md`;
+
+      // ── Step 3: Ensure the output directory exists ───────────────────────
+
+      await pi.exec("mkdir", ["-p", ".kata/audits"]);
+
+      // ── Step 4: Send the audit prompt to the agent ───────────────────────
+
+      const prompt = `You are conducting a codebase audit. This is a **read-only recce** — you will explore the codebase deeply and produce a structured report. You must NOT edit any code or create any files other than the audit report itself.
+
+## Audit Goal
+${goal}
+
+## Your Task
+
+1. **Discover the codebase** — explore the project structure, key files, configuration, dependencies, and architecture. Use \`find\`, \`ls\`, \`cat\`, \`grep\`, and \`read\` freely. Read as deeply as needed to form a thorough opinion relative to the goal.
+
+2. **Analyse against the goal** — evaluate the codebase specifically through the lens of the audit goal. What already exists? What works well? What's missing, weak, or risky?
+
+3. **Write the audit report** to \`${outputPath}\` using exactly this markdown template:
+
+\`\`\`markdown
+# Audit: ${goal}
+
+**Date:** ${now.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" })}
+**Goal:** ${goal}
+**Codebase:** [detected project name / root path]
+
+---
+
+## Strengths
+<!-- What already exists that supports this goal? What's solid? -->
+
+## Gaps
+<!-- What's missing, incomplete, or problematic relative to this goal? Be specific: file paths, patterns, missing abstractions. -->
+
+## Next Steps
+<!-- Concrete, prioritised actions. These should be directly usable as input to /kata-roadmap. -->
+
+---
+
+*Generated by /audit — read-only recce, no code was modified.*
+\`\`\`
+
+After writing the file, confirm with: "✅ Audit complete — report saved to \`${outputPath}\`"`;
+
+      ctx.ui.notify(`Starting audit: "${goal}"`, "info");
+      pi.sendUserMessage(prompt);
+    },
+  });
+}