@aliou/pi-dev-kit 0.4.9 → 0.6.0

package/src/skills/pi-extension/references/components.md

@@ -0,0 +1,166 @@
+# Components
+
+TUI components render custom UI in the terminal. They are used in `ctx.ui.custom()`, `renderResult`, and other display contexts.
+
+## Component Interface
+
+```typescript
+import type { Component, Theme } from "@mariozechner/pi-tui";
+
+class MyComponent implements Component {
+  render(maxWidth: number, maxHeight: number): string {
+    return "Hello from my component";
+  }
+
+  // Optional: handle keyboard input
+  handleInput?(key: string): void;
+}
+```
+
+`render` is called whenever the TUI needs to repaint. Return a string (can include ANSI codes via theme helpers). `maxWidth` and `maxHeight` are the available terminal dimensions.
+
+## Available Components from pi-tui
+
+Before creating custom components, check if an existing one fits your need:
+
+| Component | Description |
+|---|---|
+| `Text` | Styled text with wrapping |
+| `Box` | Container with borders and padding |
+| `Container` | Vertical/horizontal layout |
+| `Spacer` | Empty space |
+| `Input` | Text input field |
+| `Editor` | Multi-line text editor |
+| `SelectList` | Scrollable selection list |
+| `SettingsList` | Key-value settings display |
+| `Loader` | Loading spinner |
+| `CancellableLoader` | Loader with cancel support |
+| `Markdown` | Markdown rendering |
+| `Image` | Image rendering (kitty/sixel protocol) |
+| `TruncatedText` | Text with line limit and expand/collapse |
+
+Import from `@mariozechner/pi-tui`:
+
+```typescript
+import { Text, Box, Container, SelectList } from "@mariozechner/pi-tui";
+```
+
+## Utility Components from pi-coding-agent
+
+These are higher-level components for common extension patterns:
+
+| Component | Description |
+|---|---|
+| `DynamicBorder` | Border that adjusts to content width |
+| `BorderedLoader` | Loader inside a bordered box with optional cancel |
+| `ToolExecutionComponent` | Standard tool execution display |
+
+Import from `@mariozechner/pi-coding-agent`:
+
+```typescript
+import { DynamicBorder, BorderedLoader } from "@mariozechner/pi-coding-agent";
+```
+
+## Using ctx.ui.custom()
+
+`custom()` displays a full-screen component and returns when the component calls `done()`.
+
+```typescript
+const result = await ctx.ui.custom<string>((tui, theme, kb, done) => {
+  return new MyPickerComponent(theme, items, (selected) => done(selected));
+});
+```
+
+Parameters passed to the factory:
+- `tui`: The TUI instance (rarely needed directly).
+- `theme`: Current theme for styling.
+- `kb`: Keybinding configuration.
+- `done(value)`: Call to close the component and return the value.
+
+The generic type (`<string>` above) is the type of value passed to `done()`.
+
+Mode behavior:
+- Interactive: returns the value passed to `done(value)`.
+- RPC: returns `undefined` (by design; no local TUI).
+- Print: returns `undefined`.
+
+Important: `undefined` is ambiguous. In Interactive mode you can also produce it yourself by calling `done(undefined)`. If you need to detect RPC fallback, use explicit non-undefined sentinels for interactive close paths (`null`, `"closed"`, `false`, etc.).
+
+See `references/modes.md` for the three-tier pattern.
+
+## Theme Styling
+
+All render functions receive a `theme` object for consistent styling:
+
+```typescript
+// Foreground colors
+theme.fg("toolTitle", text)    // Tool names
+theme.fg("accent", text)       // Highlights
+theme.fg("success", text)      // Green
+theme.fg("error", text)        // Red
+theme.fg("warning", text)      // Yellow
+theme.fg("muted", text)        // Secondary text
+theme.fg("dim", text)          // Tertiary text
+
+// Text styles
+theme.bold(text)
+theme.italic(text)
+theme.strikethrough(text)
+```
+
+## `renderResult` is not a Component
+
+`renderResult` is a plain render function. It returns a string (or `undefined`) and is not an interactive `Component` class.
+
+```typescript
+renderResult(result, { expanded, isPartial }, theme) {
+  if (isPartial) return theme.fg("muted", "Loading...");
+
+  const items = result.details?.items ?? [];
+  const visible = expanded ? items : items.slice(0, 5);
+  return [
+    theme.fg("success", `Found ${items.length} results`),
+    ...visible.map((item: string) => `  ${theme.fg("accent", item)}`),
+  ].join("\n");
+},
+```
+
+For full `renderCall`/`renderResult` formatting rules, follow `references/tools.md` (Tool UI Rendering Guidelines + consistency contract).
+
+## Keyboard Handling in custom()
+
+Interactive components handle keyboard input through `handleInput`:
+
+```typescript
+class MyComponent implements Component {
+  private done: (value: string | null) => void;
+
+  constructor(done: (value: string | null) => void) {
+    this.done = done;
+  }
+
+  handleInput(key: string) {
+    if (key === "escape" || key === "q") {
+      this.done(null); // Cancel (explicit sentinel)
+    }
+    if (key === "return") {
+      this.done("selected"); // Confirm
+    }
+  }
+
+  render(maxWidth: number, maxHeight: number): string {
+    return "Press Enter to confirm, Esc to cancel";
+  }
+}
+```
+
+## Code Highlighting
+
+For displaying code in renderers:
+
+```typescript
+import { highlightCode, getLanguageFromPath } from "@mariozechner/pi-coding-agent";
+
+const lang = getLanguageFromPath("/path/to/file.ts"); // "typescript"
+const highlighted = highlightCode(code, lang, theme);
+```

package/src/skills/pi-extension/references/documentation.md

@@ -0,0 +1,54 @@
+# Documentation
+
+Every published extension should have a README that explains what it does, how to set it up, and what it provides.
+
+## README Template
+
+```markdown
+# pi-my-extension
+
+Brief description of the extension.
+
+## Setup
+
+\`\`\`bash
+pi install @scope/pi-my-extension
+\`\`\`
+
+### Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `MY_API_KEY` | Yes | API key from [provider](https://...) |
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `my_tool` | What it does |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/my-command` | What it does |
+
+## Providers
+
+| Provider | Models |
+|---|---|
+| `my-provider` | model-a, model-b |
+```
+
+## What to Document
+
+- **Installation**: `pi install` command.
+- **Environment variables**: Every required and optional env var, with links to where to get them.
+- **Tools**: Name and description of each registered tool. Include example usage if non-obvious.
+- **Commands**: Name and description of each registered command.
+- **Providers**: Provider name and available models (if the extension registers a provider).
+- **Limitations**: Known limitations, unsupported modes, or missing features.
+
+## Changelog
+
+If using changesets, the CHANGELOG.md is generated automatically. Each changeset entry should describe what changed from the user's perspective, not implementation details.

package/src/skills/pi-extension/references/hooks.md

@@ -0,0 +1,244 @@
+# Hooks (Events)
+
+Hooks let extensions react to lifecycle events. They are registered with `pi.on(eventName, handler)`.
+
+## Event Reference
+
+### Session Events
+
+| Event | When | Can Cancel | Payload |
+|---|---|---|---|
+| `session_start` | New session created | No | `{}` |
+| `session_switch` | Switched to different session | No | `{ reason: "new" \| "switch" \| "fork" }` |
+| `session_before_switch` | Before switching sessions | Yes (`{ cancel: true }`) | `{ reason: "new" \| "switch" \| "fork" }` |
+| `session_before_fork` | Before forking a session | Yes (`{ cancel: true }`) | `{}` |
+| `session_fork` | After session was forked | No | `{}` |
+| `session_shutdown` | Pi is shutting down | No | `{}` |
+| `session_before_compact` | Before compaction | Yes (return custom summary string) | `{ summary: string }` |
+
+### Agent Events
+
+| Event | When | Payload |
+|---|---|---|
+| `before_agent_start` | Before agent turn starts | `{}` |
+| `agent_start` | Agent turn started | `{}` |
+| `turn_start` | Turn begins processing | `{}` |
+| `turn_end` | Turn finishes processing | `{}` |
+| `model_select` | User changed the model | `{ model: string }` |
+
+### Tool Events
+
+| Event | When | Can Block | Payload |
+|---|---|---|---|
+| `tool_call` | Before a tool executes | Yes (`{ block: true, reason }`) | `{ toolName, toolCallId, input }` |
+
+### Input Events
+
+| Event | When | Can Transform | Payload |
+|---|---|---|---|
+| `input` | User submitted a message | Yes (return transformed text) | `{ text: string }` |
+
+### Bash Events
+
+| Event | When | Can Modify | Payload |
+|---|---|---|---|
+| `user_bash` | Before bash command runs | Yes (return modified command/cwd/env) | `{ command, cwd }` |
+
+## Handler Signature
+
+```typescript
+pi.on("event_name", async (event, ctx) => {
+  // event: event-specific payload
+  // ctx: ExtensionContext (hasUI, ui methods, cwd, model, etc.)
+});
+```
+
+The handler receives the event payload and an `ExtensionContext`. The context provides access to UI methods, the current working directory, model info, and more.
+
+## Blocking and Cancelling
+
+Some events let you prevent the default behavior by returning an object.
+
+### Blocking Tool Calls
+
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  if (event.toolName === "bash" && event.input.command.includes("rm -rf /")) {
+    // Check ctx.hasUI before prompting -- see references/modes.md
+    if (!ctx.hasUI) {
+      return { block: true, reason: "Blocked: dangerous command (no UI to confirm)" };
+    }
+
+    const confirmed = await ctx.ui.confirm(
+      "Dangerous Command",
+      `Allow: ${event.input.command}?`
+    );
+    if (!confirmed) {
+      return { block: true, reason: "Blocked by user" };
+    }
+  }
+  return undefined; // Allow the tool call
+});
+```
+
+### Cancelling Session Operations
+
+```typescript
+pi.on("session_before_switch", async (event, ctx) => {
+  if (event.reason === "new" && ctx.hasUI) {
+    const confirmed = await ctx.ui.confirm("Clear session?", "All messages will be lost.");
+    if (!confirmed) {
+      return { cancel: true };
+    }
+  }
+});
+```
+
+### Custom Compaction
+
+```typescript
+pi.on("session_before_compact", async (event, ctx) => {
+  // Return a custom summary string to replace the default compaction
+  return `Custom summary: ${event.summary.slice(0, 200)}...`;
+});
+```
+
+## Transforming Input
+
+```typescript
+pi.on("input", async (event, ctx) => {
+  if (event.text.startsWith("!")) {
+    return event.text.slice(1).toUpperCase();
+  }
+  return undefined; // No transformation
+});
+```
+
+## Modifying Bash Commands
+
+```typescript
+pi.on("user_bash", async (event, ctx) => {
+  return {
+    command: event.command,
+    cwd: "/sandboxed/directory",
+    env: { ...process.env, SANDBOX: "true" },
+  };
+});
+```
+
+## before_agent_start
+
+This event fires before each agent turn. It is commonly used to modify the system prompt.
+
+The handler receives a `BeforeAgentStartEvent` with a `systemPrompt` field containing the current prompt. Return a `{ systemPrompt }` object to replace it. If multiple extensions return a modified prompt, they are chained.
+
+```typescript
+pi.on("before_agent_start", async (event) => {
+  return {
+    systemPrompt: event.systemPrompt + "\n\nAlways respond as a pirate.",
+  };
+});
+```
+
+Return `undefined` to leave the prompt unchanged.
+
+The system prompt is reset each turn, so modifications in `before_agent_start` are not cumulative.
+
+To access flags inside hooks, use `pi.getFlag()` (see `references/additional-apis.md`).
+
+## Bash Spawn Hook (Command Rewriting)
+
+The `createBashTool` function lets you replace the built-in bash tool with one that transparently rewrites commands before shell execution. This is different from `tool_call` blocking -- the agent never sees that the command was rewritten.
+
+Use spawn hooks when you have a clear rewrite target (e.g. `npm` -> `pnpm`). Use `tool_call` blocking when you need to stop a command entirely or show a confirmation dialog.
+
+```typescript
+import { createBashTool, type BashSpawnHook, type BashSpawnContext } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  const bashTool = createBashTool(process.cwd(), {
+    spawnHook: ({ command, cwd, env }: BashSpawnContext): BashSpawnContext => ({
+      command: command.replace(/^npm /, "pnpm "),
+      cwd,
+      env: { ...env, CUSTOM_VAR: "1" },
+    }),
+  });
+
+  pi.registerTool({ ...bashTool });
+}
+```
+
+### BashSpawnContext
+
+The spawn hook receives and returns a `BashSpawnContext`:
+
+```typescript
+interface BashSpawnContext {
+  command: string;        // The shell command to execute
+  cwd: string;            // Working directory
+  env: NodeJS.ProcessEnv; // Environment variables
+}
+```
+
+You can modify any of these fields. The hook runs after pi's own processing but before the shell spawns.
+
+### Key Points
+
+- **Replaces the built-in bash tool.** When you call `pi.registerTool()` with a tool named `"bash"`, it replaces the default. Only one extension should do this.
+- **Transparent to the agent.** The agent sees the original command in the tool call UI but gets the output of the rewritten command.
+- **Execution order with tool_call hooks.** `tool_call` event hooks (blockers) run first. If a blocker returns `{ block: true }`, the spawn hook never fires. This means you can combine blocking hooks for commands that should be stopped entirely with spawn hooks for commands that should be rewritten.
+- **Prefer AST-based rewrites over regex.** A false positive rewrite corrupts a command silently. Use `@aliou/sh` or similar shell parsers to identify command names in the AST, then do surgical string replacement at the identified positions. If the parse fails, return the command unchanged.
+- **Compose multiple rewriters.** Chain rewriter functions that each transform the context:
+
+```typescript
+const rewriters: ((ctx: BashSpawnContext) => BashSpawnContext)[] = [
+  createPackageManagerRewriter(config),
+  createGitRebaseRewriter(),
+];
+
+const spawnHook = (ctx: BashSpawnContext) => {
+  let result = ctx;
+  for (const rewrite of rewriters) {
+    result = rewrite(result);
+  }
+  return result;
+};
+
+const bashTool = createBashTool(process.cwd(), { spawnHook });
+pi.registerTool({ ...bashTool });
+```
+
+### When to Use What
+
+| Pattern | Use When | Agent Sees |
+|---|---|---|
+| `tool_call` hook + `{ block: true }` | Command must be stopped entirely | Block reason (retries with correct command) |
+| `tool_call` hook + `ctx.ui.confirm()` | User confirmation needed | Block reason if denied |
+| Spawn hook (command rewrite) | Clear 1:1 rewrite target exists | Output of rewritten command (transparent) |
+| Spawn hook (env injection) | Need to set env vars for specific commands | Output with injected env (transparent) |
+
+## Multiple Handlers
+
+Multiple extensions can register handlers for the same event. They execute in registration order. For blocking events (`tool_call`, `session_before_switch`, etc.), the first handler to return a blocking/cancelling result wins.
+
+## Mode Awareness in Hooks
+
+Always consider what happens in Print mode when your hook uses dialog methods. See `references/modes.md` for the full behavior matrix.
+
+Common pattern for `tool_call` handlers:
+
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  if (shouldBlock(event)) {
+    if (!ctx.hasUI) {
+      return { block: true, reason: "No UI to confirm" };
+    }
+    // Safe to use dialogs here
+    const choice = await ctx.ui.select("Allow?", ["Yes", "No"]);
+    if (choice !== "Yes") {
+      return { block: true, reason: "Blocked by user" };
+    }
+  }
+  return undefined;
+});
+```

package/src/skills/pi-extension/references/messages.md

@@ -0,0 +1,169 @@
+# Messages
+
+Pi provides several ways to display information to the user. Choose based on the UX goal.
+
+## When to Use What
+
+| Method | Persistence | Interactivity | Use When |
+|---|---|---|---|
+| `ctx.ui.notify()` | Transient (fades) | None | Quick feedback: "Saved", "API key missing" |
+| `ctx.ui.custom()` | Until dismissed | Full keyboard | Rich interactive display: pickers, dashboards |
+| `pi.sendMessage()` | In session history | Via renderer | Persistent results that should survive compaction |
+| `pi.appendEntry()` | In session history | Via renderer | State tracking entries (see `references/state.md`) |
+
+## sendMessage
+
+Sends a message into the session conversation. It appears as an assistant message and is persisted in session history.
+
+```typescript
+pi.sendMessage({
+  customType: "balance-result",     // Identifier for the message renderer
+  content: "Balance: $42.50",       // Plain text content (LLM sees this)
+  display: true,                    // Show in TUI
+  details: { balance: 42.50 },     // Rich data for custom rendering
+});
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `customType` | `string` | Identifies the message type. Paired with `registerMessageRenderer`. |
+| `content` | `string` | Plain text content. This is what the LLM sees if the message is in context. |
+| `display` | `boolean` | Whether to show the message in the TUI. |
+| `details` | `object` | Arbitrary data passed to the message renderer. |
+
+## registerMessageRenderer
+
+Registers a custom renderer for messages with a specific `customType`:
+
+```typescript
+pi.registerMessageRenderer("balance-result", (message, theme) => {
+  const { balance } = message.details;
+  return [
+    theme.bold("Account Balance"),
+    "",
+    theme.fg("success", `  $${balance.toFixed(2)}`),
+  ].join("\n");
+});
+```
+
+The renderer receives the full message object and the theme. It returns a string for display in the TUI.
+
+If no renderer is registered for a `customType`, the message's `content` field is displayed as plain text.
+
+## Custom Message Design Guide (breadcrumbs-style)
+
+`breadcrumbs` is a good reference for custom entries/messages (`../pi-extensions/extensions/breadcrumbs/lib/session-link.ts`, plus `commands/handoff.ts` and `commands/spawn.ts`).
+
+### 1) Prefer paired entries for links/handovers
+
+For cross-session workflows, use two custom message types:
+- **Marker** in source session: short line (`Handed off to X` / `Continues in X`).
+- **Source** in new session: header + optional expanded context.
+
+This gives both directions of navigation and keeps history readable.
+
+### 2) Collapsed vs expanded behavior
+
+Keep collapsed view minimal and scannable:
+- one semantic line
+- optional hint (`Press Ctrl+O to expand`) only when extra content exists
+
+Use expanded view for rich content:
+- markdown body
+- multi-line context
+- file lists / instructions
+
+### 3) Renderer resilience
+
+Message renderers should degrade safely:
+- missing `details` => fallback to plain `content`
+- markdown render failure => fallback to plain text
+- unknown fields => ignore, don't throw
+
+### 4) Keep details small and durable
+
+`details` should contain stable identifiers and routing data, not large blobs:
+- session IDs
+- link type (`handoff`, `continue`)
+- short metadata (goal/title)
+
+Put large human-readable content in `content` (for expansion/LLM visibility), not deep nested `details`.
+
+### 5) Use visual hierarchy consistently
+
+For message UIs:
+- muted label + accent target/value (`Continues in <session-name>`)
+- subtle container background for custom message blocks
+- avoid decorative noise; optimize for fast scan in session history
+
+## Pattern: Command with sendMessage Fallback
+
+This combines with the three-tier pattern from `references/modes.md`. Use `sendMessage` as the RPC fallback for commands that use `custom()`:
+
+```typescript
+// Register the renderer once at load time
+pi.registerMessageRenderer("my-results", (message, theme) => {
+  const { items } = message.details;
+  return [
+    theme.bold(`Results (${items.length})`),
+    ...items.map((item: string) => `  ${theme.fg("accent", item)}`),
+  ].join("\n");
+});
+
+pi.registerCommand("results", {
+  description: "Show results",
+  handler: async (_args, ctx) => {
+    const items = await fetchItems();
+
+    if (!ctx.hasUI) {
+      console.log(items.join("\n"));
+      return;
+    }
+
+    const result = await ctx.ui.custom<"closed">((tui, theme, _kb, done) => {
+      return new ResultsDisplay(theme, items, () => done("closed"));
+    });
+
+    // RPC fallback only: custom() returns undefined in RPC/Print.
+    if (result === undefined) {
+      pi.sendMessage({
+        customType: "my-results",
+        content: items.join("\n"),
+        display: true,
+        details: { items },
+      });
+    }
+  },
+});
+```
+
+## notify
+
+For transient feedback that does not need to persist:
+
+```typescript
+ctx.ui.notify("Operation complete", "info");
+ctx.ui.notify("Something went wrong", "error");
+ctx.ui.notify("Proceed with caution", "warning");
+```
+
+The second argument is the notification type: `"info"`, `"error"`, or `"warning"`. It affects the color/icon.
+
+`notify` is fire-and-forget. It works in Interactive and RPC modes, and is a no-op in Print mode.
+
+## Writing custom entries in a new session
+
+When using `ctx.newSession({ setup })`, write custom entries directly through the setup `SessionManager`:
+
+```typescript
+await ctx.newSession({
+  setup: async (sm) => {
+    sm.appendCustomMessageEntry("my-source-type", "Context text", true, {
+      parentSessionId: "...",
+      linkType: "handoff",
+    });
+  },
+});
+```
+
+Use this pattern for handoff/spawn-like workflows where the new session must start with structured context.