gsd-pi 2.33.1 → 2.34.0-dev.0150ae9

package/dist/resources/extensions/shared/wizard-ui.js

@@ -0,0 +1,478 @@
+/**
+ * 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 { Editor, Key, matchesKey, truncateToWidth, } from "@gsd/pi-tui";
+import { makeUI } from "./ui.js";
+// ─── Main export ──────────────────────────────────────────────────────────────
+/**
+ * Show a multi-page wizard and return collected answers, or null if the user exits.
+ */
+export async function showWizard(ctx, opts) {
+    const pageMap = new Map(opts.pages.map((p) => [p.id, p]));
+    return ctx.ui.custom((tui, theme, _kb, done) => {
+        // ── State ──────────────────────────────────────────────────────────────
+        /** Stack of page ids visited — drives back navigation */
+        const pageStack = [opts.pages[0].id];
+        const pageStates = new Map();
+        /** Collected answers across all pages */
+        const answers = {};
+        /** 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;
+        // Editors keyed by fieldId — one per text field
+        // editorTheme is derived from the design system at first render
+        const editors = new Map();
+        let resolvedEditorTheme = null;
+        function getEditor(fieldId) {
+            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) {
+            if (!pageStates.has(pageId)) {
+                pageStates.set(pageId, {
+                    selectStates: new Map(),
+                    textValues: new Map(),
+                    focusedFieldId: null,
+                });
+            }
+            return pageStates.get(pageId);
+        }
+        function getSelectState(pageId, fieldId, _optCount) {
+            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() {
+            return pageStack[pageStack.length - 1];
+        }
+        function currentPage() {
+            return pageMap.get(currentPageId());
+        }
+        function currentPageState() {
+            return getPageState(currentPageId());
+        }
+        // ── Validation ─────────────────────────────────────────────────────────
+        function isPageComplete(page, ps) {
+            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, ps) {
+            const result = {};
+            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) {
+            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) {
+            // ── 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) {
+            const ui = makeUI(theme, width);
+            const lines = [];
+            const push = (...rows) => { 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, field, lines) {
+            const push = (...rows) => { 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, field, ps, lines, width) {
+            const push = (...rows) => { 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) {
+            if (cachedLines)
+                return cachedLines;
+            if (showingExitConfirm) {
+                cachedLines = renderExitConfirm(width);
+                return cachedLines;
+            }
+            const ui = makeUI(theme, width);
+            const lines = [];
+            const push = (...rows) => { 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 = [];
+            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/dist/resources/extensions/slash-commands/audit.js

@@ -0,0 +1,72 @@
+export default function auditCommand(pi) {
+    pi.registerCommand("audit", {
+        description: "Audit the current codebase against a specific goal and write a structured report to .gsd/audits/",
+        async handler(args, ctx) {
+            // ── 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 (.gsd/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 = `.gsd/audits/${timestamp}-${slug}.md`;
+            // ── Step 3: Ensure the output directory exists ───────────────────────
+            await pi.exec("mkdir", ["-p", ".gsd/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 /gsd-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);
+        },
+    });
+}

package/dist/resources/extensions/slash-commands/clear.js

@@ -0,0 +1,8 @@
+export default function clearCommand(pi) {
+    pi.registerCommand("clear", {
+        description: "Alias for /new — start a new session",
+        async handler(_args, ctx) {
+            await ctx.newSession();
+        },
+    });
+}