@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/extensions/slash-commands/create-extension.ts

@@ -0,0 +1,375 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  showInterviewRound,
+  type Question,
+  type RoundResult,
+} from "../shared/interview-ui.js";
+
+export default function createExtension(pi: ExtensionAPI) {
+  pi.registerCommand("create-extension", {
+    description:
+      "Scaffold a new pi extension with interview-driven context gathering",
+    async handler(args, ctx) {
+      const inlineName = (typeof args === "string" ? args : "").trim();
+
+      // ── Interview — always runs first ─────────────────────────────────────
+
+      const questions: Question[] = [
+        ...(!inlineName
+          ? [
+              {
+                id: "purpose",
+                header: "Purpose",
+                question: "What should this extension do?",
+                options: [
+                  {
+                    label: "Add a custom tool",
+                    description:
+                      "Register a new tool the LLM can call (like kata_plan, plan_clarify).",
+                  },
+                  {
+                    label: "Add a slash command",
+                    description:
+                      "A /command the user types — runs logic, optionally triggers an agent turn.",
+                  },
+                  {
+                    label: "React to agent events",
+                    description:
+                      "Hook into turn_end, agent_end, tool_call, etc. to observe or intercept.",
+                  },
+                  {
+                    label: "Custom TUI component",
+                    description:
+                      "Render a widget, overlay, dialog, or custom editor in the terminal UI.",
+                  },
+                ],
+              } satisfies Question,
+            ]
+          : []),
+        {
+          id: "ui",
+          header: "UI",
+          question: "Does this extension need any custom UI?",
+          options: [
+            {
+              label: "No UI",
+              description:
+                "Pure logic — no dialogs, widgets, or custom rendering needed.",
+            },
+            {
+              label: "Dialogs only",
+              description:
+                "Uses built-in ctx.ui.select / ctx.ui.input / ctx.ui.confirm dialogs.",
+            },
+            {
+              label: "Status / widget",
+              description:
+                "Shows a persistent status indicator or footer widget.",
+            },
+            {
+              label: "Full custom component",
+              description:
+                "Uses ctx.ui.custom() to render a fully bespoke TUI component.",
+            },
+          ],
+        },
+        {
+          id: "events",
+          header: "Events",
+          question: "Does it need to hook into the agent lifecycle?",
+          options: [
+            {
+              label: "No — standalone",
+              description:
+                "Runs only when explicitly invoked — no event listeners needed.",
+            },
+            {
+              label: "Yes — tool_call",
+              description:
+                "Intercepts or observes tool calls before or after they run.",
+            },
+            {
+              label: "Yes — turn / session",
+              description:
+                "Reacts to turn_end, agent_end, session_start, or similar lifecycle events.",
+            },
+            {
+              label: "Yes — context / prompt",
+              description:
+                "Modifies the system prompt or filters messages via context / before_agent_start.",
+            },
+          ],
+        },
+        {
+          id: "persistence",
+          header: "State",
+          question:
+            "Does this extension need to persist state across sessions?",
+          options: [
+            {
+              label: "No state needed",
+              description: "Stateless — each invocation is independent.",
+            },
+            {
+              label: "In-memory only",
+              description:
+                "Keeps state while the session is running but doesn't survive restarts.",
+            },
+            {
+              label: "Persisted to session",
+              description:
+                "Uses pi.appendEntry() to write state into the session JSONL for resume.",
+            },
+          ],
+        },
+        {
+          id: "complexity",
+          header: "Complexity",
+          question: "How complex is the implementation?",
+          options: [
+            {
+              label: "Simple — one concern",
+              description:
+                "A single tool or command, minimal branching, easy to follow.",
+            },
+            {
+              label: "Moderate — a few parts",
+              description:
+                "A command plus an event hook, or a tool with custom rendering.",
+            },
+            {
+              label: "Complex — full extension",
+              description:
+                "Multiple tools, commands, events, UI, and state working together.",
+            },
+          ],
+        },
+      ];
+
+      const result: RoundResult = await showInterviewRound(
+        questions,
+        {
+          progress: "New pi extension · Context",
+          reviewHeadline: "Review your choices",
+          exitHeadline: "Cancel extension creation?",
+          exitLabel: "cancel",
+        },
+        ctx,
+      );
+
+      // User hit Esc — bail silently
+      if (!result.answers || Object.keys(result.answers).length === 0) {
+        ctx.ui.notify("Cancelled.", "info");
+        return;
+      }
+
+      // ── Resolve name / description ────────────────────────────────────────
+
+      let extensionDescription = inlineName;
+      if (!extensionDescription) {
+        const purpose = result.answers["purpose"];
+        if (purpose) {
+          extensionDescription = purpose.notes?.trim()
+            ? purpose.notes.trim()
+            : Array.isArray(purpose.selected)
+              ? purpose.selected[0]
+              : purpose.selected;
+        }
+      }
+
+      if (!extensionDescription) {
+        ctx.ui.notify(
+          "No description captured — add details in the notes field next time.",
+          "warning",
+        );
+        return;
+      }
+
+      // ── Build and send the enriched prompt ────────────────────────────────
+
+      sendPrompt(extensionDescription, result, pi);
+    },
+  });
+}
+
+// ─── Prompt builder ───────────────────────────────────────────────────────────
+
+function formatAnswers(result: RoundResult): string {
+  const lines: string[] = [];
+
+  const purpose = result.answers["purpose"];
+  if (purpose?.notes) {
+    lines.push(`- **Extension goal (user's words)**: ${purpose.notes}`);
+  }
+
+  const ui = result.answers["ui"];
+  if (ui) {
+    const selected = Array.isArray(ui.selected) ? ui.selected[0] : ui.selected;
+    lines.push(
+      `- **UI needs**: ${selected}${ui.notes ? ` — ${ui.notes}` : ""}`,
+    );
+  }
+
+  const events = result.answers["events"];
+  if (events) {
+    const selected = Array.isArray(events.selected)
+      ? events.selected[0]
+      : events.selected;
+    lines.push(
+      `- **Event hooks**: ${selected}${events.notes ? ` — ${events.notes}` : ""}`,
+    );
+  }
+
+  const persistence = result.answers["persistence"];
+  if (persistence) {
+    const selected = Array.isArray(persistence.selected)
+      ? persistence.selected[0]
+      : persistence.selected;
+    lines.push(
+      `- **State persistence**: ${selected}${persistence.notes ? ` — ${persistence.notes}` : ""}`,
+    );
+  }
+
+  const complexity = result.answers["complexity"];
+  if (complexity) {
+    const selected = Array.isArray(complexity.selected)
+      ? complexity.selected[0]
+      : complexity.selected;
+    lines.push(
+      `- **Complexity**: ${selected}${complexity.notes ? ` — ${complexity.notes}` : ""}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function sendPrompt(
+  description: string,
+  result: RoundResult,
+  pi: ExtensionAPI,
+): void {
+  const contextSection = `\n## Context gathered from user\n${formatAnswers(result)}\n`;
+
+  // Determine which doc sections to highlight based on answers
+  const uiAnswer = result.answers["ui"];
+  const uiSelected = uiAnswer
+    ? Array.isArray(uiAnswer.selected)
+      ? uiAnswer.selected[0]
+      : uiAnswer.selected
+    : "";
+
+  const eventsAnswer = result.answers["events"];
+  const eventsSelected = eventsAnswer
+    ? Array.isArray(eventsAnswer.selected)
+      ? eventsAnswer.selected[0]
+      : eventsAnswer.selected
+    : "";
+
+  const persistenceAnswer = result.answers["persistence"];
+  const persistenceSelected = persistenceAnswer
+    ? Array.isArray(persistenceAnswer.selected)
+      ? persistenceAnswer.selected[0]
+      : persistenceAnswer.selected
+    : "";
+
+  const docHints: string[] = [
+    "- `~/.kata-cli/agent/docs/extending-pi/01-what-are-extensions.md` — capabilities overview",
+    "- `~/.kata-cli/agent/docs/extending-pi/03-getting-started.md` — minimal extension, hot reload",
+    "- `~/.kata-cli/agent/docs/extending-pi/08-extensioncontext-what-you-can-access.md` — ExtensionContext API",
+    "- `~/.kata-cli/agent/docs/extending-pi/09-extensionapi-what-you-can-do.md` — ExtensionAPI: registration, messaging",
+    "- `~/.kata-cli/agent/docs/extending-pi/22-key-rules-gotchas.md` — must-read rules before shipping",
+  ];
+
+  if (uiSelected.includes("custom component")) {
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/extending-pi/12-custom-ui-visual-components.md` — dialogs, widgets, overlays",
+    );
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — ctx.ui.custom() API",
+    );
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList",
+    );
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey",
+    );
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules",
+    );
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md` — step-by-step guide",
+    );
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md` — pitfalls",
+    );
+  } else if (uiSelected.includes("Dialogs")) {
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/04-built-in-dialog-methods.md` — select, confirm, input, editor",
+    );
+  } else if (uiSelected.includes("Status")) {
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/05-persistent-ui-elements.md` — status, widgets, footer, header",
+    );
+  }
+
+  if (uiSelected.includes("tool") || result.answers["purpose"]) {
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult",
+    );
+  }
+
+  if (eventsSelected && !eventsSelected.includes("standalone")) {
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/extending-pi/07-events-the-nervous-system.md` — all events reference",
+    );
+  }
+
+  if (eventsSelected.includes("context / prompt")) {
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/extending-pi/15-system-prompt-modification.md` — system prompt hooks",
+    );
+  }
+
+  if (persistenceSelected.includes("session")) {
+    docHints.push(
+      "- `~/.kata-cli/agent/docs/extending-pi/13-state-management-persistence.md` — pi.appendEntry, session state",
+    );
+  }
+
+  const prompt = `Create a new pi extension based on this description:
+
+"${description}"
+${contextSection}
+## Reference documentation
+
+Before writing any code, read the relevant docs below. They contain the exact APIs, rules, and patterns for building pi extensions — do not guess or rely on general TypeScript knowledge alone.
+
+${docHints.join("\n")}
+
+## Output
+
+Write the complete implementation as a single self-contained extension file:
+
+\`~/.kata-cli/agent/extensions/<kebab-case-name>.ts\`
+
+Then register it in the main extensions index:
+
+\`~/.kata-cli/agent/extensions/index.ts\` — import and call the new extension's default export alongside existing ones
+
+## Rules you must follow exactly
+
+- Extension entry point: \`export default function <camelCaseName>(pi: ExtensionAPI): void { ... }\`
+- Import type: \`import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";\`
+- \`pi\` is the registration surface — call \`pi.registerCommand\`, \`pi.registerTool\`, \`pi.on\`, \`pi.registerShortcut\` inside the default export
+- \`ctx\` (ExtensionCommandContext or ExtensionContext) is passed to handlers and event callbacks — never stored, never assumed available globally
+- To send a message to the agent: \`pi.sendUserMessage("...")\` or \`pi.sendMessage({ content, display }, { triggerTurn })\`
+- To show UI: \`ctx.ui.notify\`, \`ctx.ui.select\`, \`ctx.ui.input\`, \`ctx.ui.confirm\`, \`ctx.ui.custom\`
+- To run shell commands: \`await pi.exec("cmd", ["arg1"])\` — returns \`{ stdout, stderr, exitCode }\`
+- Events use \`pi.on("event_name", async (event, ctx) => { ... })\`
+- No direct file I/O without \`node:fs\` — import it explicitly if needed
+- Read the gotchas file before finalising: \`22-key-rules-gotchas.md\`
+
+After writing the files, run \`/reload\` to load the new extension.`;
+
+  pi.sendUserMessage(prompt);
+}

package/src/resources/extensions/slash-commands/create-slash-command.ts

@@ -0,0 +1,280 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  showInterviewRound,
+  type Question,
+  type RoundResult,
+} from "../shared/interview-ui.js";
+
+export default function createSlashCommand(pi: ExtensionAPI) {
+  pi.registerCommand("create-slash-command", {
+    description:
+      "Generate a new slash command extension from a plain-English description",
+    async handler(args, ctx) {
+      const inlineDescription = (typeof args === "string" ? args : "").trim();
+
+      // ── Interview — always run, no free-text step first ───────────────────
+      //
+      // If the user already typed a description as args, we skip the "what
+      // should it do?" question and go straight to the behaviour questions.
+      // Otherwise it's the first question in the round.
+
+      const questions: Question[] = [
+        ...(!inlineDescription
+          ? [
+              {
+                id: "purpose",
+                header: "Purpose",
+                question: "What should this slash command do?",
+                options: [
+                  {
+                    label: "Automate git workflow",
+                    description:
+                      "Commit, branch, diff, stash — anything git-related.",
+                  },
+                  {
+                    label: "Send a crafted prompt",
+                    description:
+                      "Build a rich context prompt and hand it to the LLM.",
+                  },
+                  {
+                    label: "Run a shell task",
+                    description:
+                      "Execute CLI tools (npm, docker, etc.) and show the output.",
+                  },
+                  {
+                    label: "Something else",
+                    description: "Describe it in the notes field below.",
+                  },
+                ],
+              } satisfies Question,
+            ]
+          : []),
+        {
+          id: "trigger",
+          header: "Trigger",
+          question: "How does this command kick off its work?",
+          options: [
+            {
+              label: "Sends to agent",
+              description:
+                "Builds a prompt and hands off to the LLM to do the heavy lifting.",
+            },
+            {
+              label: "Runs shell commands",
+              description:
+                "Executes CLI commands directly (git, npm, etc.) without an LLM turn.",
+            },
+            {
+              label: "Shows a UI prompt",
+              description:
+                "Pops up a select/input dialog to gather more info, then acts.",
+            },
+            {
+              label: "Mixed — UI then agent",
+              description:
+                "Collects some info via a dialog, then sends a crafted prompt to the LLM.",
+            },
+          ],
+        },
+        {
+          id: "output",
+          header: "Output",
+          question: "How should the command communicate results to the user?",
+          options: [
+            {
+              label: "Agent response",
+              description:
+                "The LLM writes the response — the command just triggers the turn.",
+            },
+            {
+              label: "Notification",
+              description:
+                "A brief inline notification (success/error/info) — no agent turn.",
+            },
+            {
+              label: "Command output",
+              description:
+                "Shows raw shell output or a formatted summary in the chat.",
+            },
+          ],
+        },
+        {
+          id: "args",
+          header: "Arguments",
+          question: "Does the command take arguments when invoked?",
+          options: [
+            {
+              label: "No args needed",
+              description:
+                "Called as just /command-name — gathers everything it needs at runtime.",
+            },
+            {
+              label: "Optional freeform arg",
+              description:
+                "User can type /command-name <something>, but it works without it too.",
+            },
+            {
+              label: "Required arg",
+              description:
+                "Needs a specific value typed after the name; shows usage if missing.",
+            },
+          ],
+        },
+        {
+          id: "complexity",
+          header: "Complexity",
+          question: "How complex does the implementation need to be?",
+          options: [
+            {
+              label: "Simple — one action",
+              description:
+                "Does one thing in a handful of lines. Easy to follow.",
+            },
+            {
+              label: "Moderate — a few steps",
+              description:
+                "Some branching, maybe a shell call or two, a conditional prompt.",
+            },
+            {
+              label: "Complex — multi-step",
+              description:
+                "Multiple async steps, error handling, state, or UI interactions.",
+            },
+          ],
+        },
+      ];
+
+      const result: RoundResult = await showInterviewRound(
+        questions,
+        {
+          progress: "New slash command · Context",
+          reviewHeadline: "Review your choices",
+          exitHeadline: "Cancel command creation?",
+          exitLabel: "cancel",
+        },
+        ctx,
+      );
+
+      // User hit Esc with nothing answered — bail silently
+      if (!result.answers || Object.keys(result.answers).length === 0) {
+        ctx.ui.notify("Cancelled.", "info");
+        return;
+      }
+
+      // ── Resolve description ───────────────────────────────────────────────
+
+      let description = inlineDescription;
+      if (!description) {
+        const purpose = result.answers["purpose"];
+        if (purpose) {
+          const selected = Array.isArray(purpose.selected)
+            ? purpose.selected[0]
+            : purpose.selected;
+          description = purpose.notes
+            ? purpose.notes // prefer their own words from the notes field
+            : selected;
+        }
+      }
+
+      if (!description) {
+        ctx.ui.notify(
+          "No description captured — add details in the notes field next time.",
+          "warning",
+        );
+        return;
+      }
+
+      // ── Build and send the enriched prompt ────────────────────────────────
+
+      sendPrompt(description, result, pi);
+    },
+  });
+}
+
+// ─── Prompt builder ───────────────────────────────────────────────────────────
+
+function formatAnswers(result: RoundResult): string {
+  const lines: string[] = [];
+
+  const purpose = result.answers["purpose"];
+  if (purpose?.notes) {
+    lines.push(`- **Command goal (user's words)**: ${purpose.notes}`);
+  }
+
+  const trigger = result.answers["trigger"];
+  if (trigger) {
+    const selected = Array.isArray(trigger.selected)
+      ? trigger.selected[0]
+      : trigger.selected;
+    lines.push(
+      `- **Trigger pattern**: ${selected}${trigger.notes ? ` — ${trigger.notes}` : ""}`,
+    );
+  }
+
+  const output = result.answers["output"];
+  if (output) {
+    const selected = Array.isArray(output.selected)
+      ? output.selected[0]
+      : output.selected;
+    lines.push(
+      `- **Output style**: ${selected}${output.notes ? ` — ${output.notes}` : ""}`,
+    );
+  }
+
+  const argsAnswer = result.answers["args"];
+  if (argsAnswer) {
+    const selected = Array.isArray(argsAnswer.selected)
+      ? argsAnswer.selected[0]
+      : argsAnswer.selected;
+    lines.push(
+      `- **Arguments**: ${selected}${argsAnswer.notes ? ` — ${argsAnswer.notes}` : ""}`,
+    );
+  }
+
+  const complexity = result.answers["complexity"];
+  if (complexity) {
+    const selected = Array.isArray(complexity.selected)
+      ? complexity.selected[0]
+      : complexity.selected;
+    lines.push(
+      `- **Complexity**: ${selected}${complexity.notes ? ` — ${complexity.notes}` : ""}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function sendPrompt(
+  description: string,
+  result: RoundResult,
+  pi: ExtensionAPI,
+): void {
+  const contextSection = `\n## Context gathered from user\n${formatAnswers(result)}\n`;
+
+  const prompt = `Create a new pi slash command extension based on this description:
+
+"${description}"
+${contextSection}
+Write the complete file contents for two files:
+
+1. \`~/.kata-cli/agent/extensions/slash-commands/<name>.ts\` — the command implementation
+2. Update \`~/.kata-cli/agent/extensions/slash-commands/index.ts\` — import and register the new command alongside existing ones
+
+Rules you must follow exactly:
+- Command registration: \`pi.registerCommand("name", { description, handler })\`
+- Handler signature: \`async handler(args: string, ctx: ExtensionCommandContext)\`
+- \`args\` is the raw string typed after the command name (may be empty)
+- To send a message to the agent: \`pi.sendUserMessage("...")\` — this triggers an agent turn
+- To show a quick notification without triggering a turn: \`ctx.ui.notify("...", "info" | "success" | "error")\`
+- To run a shell command: \`await pi.exec("cmd", ["arg1", "arg2"])\` — returns \`{ stdout, stderr, exitCode }\`
+- To show a select dialog: \`await ctx.ui.select("prompt", ["Option A", "Option B"])\` — returns the chosen string
+- To show a text input dialog: \`await ctx.ui.input("prompt", "placeholder")\` — returns the string or null
+- \`pi\` is captured in closure from the outer \`export default function(pi: ExtensionAPI)\` — use it freely inside the handler
+- No \`ctx.session\`, no \`ctx.sendMessage\`, no \`args[]\` array — these do not exist
+- Import type: \`import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";\`
+- Export default: \`export default function <camelCaseName>(pi: ExtensionAPI) { ... }\`
+
+After writing the files, run \`/reload\` to load the new command.`;
+
+  pi.sendUserMessage(prompt);
+}

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

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import createSlashCommand from "./create-slash-command.js";
+import createExtension from "./create-extension.js";
+import auditCommand from "./audit.js";
+import kataRun from "./kata-run.js";
+
+export default function slashCommands(pi: ExtensionAPI) {
+  createSlashCommand(pi);
+  createExtension(pi);
+  auditCommand(pi);
+  kataRun(pi);
+}