@aliou/pi-dev-kit 0.6.4 → 0.7.0

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

@@ -1,6 +1,6 @@
 # Commands
 
-Commands are user-invoked actions triggered with `/command-name` in the input editor.
+Commands are user-invoked actions triggered with `/command-name`. Register them with `pi.registerCommand(name, options)`.
 
 ## Registration
 
@@ -8,17 +8,49 @@ Commands are user-invoked actions triggered with `/command-name` in the input ed
 pi.registerCommand("my-command", {
   description: "What this command does",
   handler: async (args, ctx) => {
-    // args: string (everything after the command name)
-    // ctx: ExtensionContext
+    // args is the raw text after the command name.
+    // ctx is ExtensionCommandContext.
+  },
+});
+```
+
+If several extensions register the same command, Pi keeps all of them and assigns invocation suffixes such as `/review:1` and `/review:2`.
+
+## Argument Completion
+
+Use `getArgumentCompletions` for command-specific autocomplete.
+
+```typescript
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+
+pi.registerCommand("deploy", {
+  description: "Deploy to an environment",
+  getArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+    const items = ["dev", "staging", "prod"].map((env) => ({ value: env, label: env }));
+    const filtered = items.filter((item) => item.value.startsWith(prefix));
+    return filtered.length > 0 ? filtered : null;
+  },
+  handler: async (args, ctx) => {
+    ctx.ui.notify(`Deploying ${args}`, "info");
   },
 });
 ```
 
 ## Command Context
 
-The `ctx` parameter provides the same `ExtensionContext` as hooks, with access to `ctx.ui`, `ctx.hasUI`, `ctx.cwd`, etc.
+Command handlers receive `ExtensionCommandContext`, which includes normal `ExtensionContext` fields plus session-control methods.
+
+Common fields and methods:
 
-Commands are interactive by nature (the user typed them), so `ctx.hasUI` is usually `true`. However, commands can also be invoked programmatically (for example via RPC), so the three-tier pattern still applies.
+- `ctx.ui`, `ctx.hasUI`, `ctx.cwd`, `ctx.model`, `ctx.modelRegistry`, `ctx.sessionManager`, `ctx.signal`.
+- `ctx.waitForIdle()`.
+- `ctx.newSession({ setup, withSession })`.
+- `ctx.fork(entryId, { position, withSession })`.
+- `ctx.switchSession(path, { withSession })`.
+- `ctx.navigateTree(targetId, options)`.
+- `ctx.reload()`.
+
+Session replacement invalidates captured old session-bound objects. Put post-switch work in `withSession` and use only that callback context.
 
 ## Simple Command
 
@@ -32,9 +64,24 @@ pi.registerCommand("balance", {
 });
 ```
 
-## Command with Rich Display
+Fire-and-forget UI calls such as `notify`, `setStatus`, and `setEditorText` are safe without `ctx.hasUI` guards.
+
+## Parsing Arguments
+
+`args` is a raw string. Parse it yourself.
+
+```typescript
+handler: async (args, ctx) => {
+  const [subcommand, ...rest] = args.trim().split(/\s+/);
+  const value = rest.join(" ");
+}
+```
+
+For complex inputs, prefer a small parser over ad hoc indexing.
 
-When a command needs a rich TUI display, use the three-tier pattern from `references/modes.md`:
+## Rich TUI Display
+
+Use the three-tier pattern when a command uses `ctx.ui.custom()`.
 
 ```typescript
 pi.registerCommand("quotas", {
@@ -42,19 +89,18 @@ pi.registerCommand("quotas", {
   handler: async (_args, ctx) => {
     const quotas = await fetchQuotas();
 
-    // Print mode
+    // Print/JSON mode: no UI.
     if (!ctx.hasUI) {
       console.log(formatQuotasPlain(quotas));
       return;
     }
 
-    // Interactive mode: full TUI component.
-    // Use explicit sentinel value for close/cancel, not undefined.
-    const result = await ctx.ui.custom<"closed">((tui, theme, _kb, done) => {
+    // Interactive mode: rich component. Use explicit sentinel, not undefined.
+    const result = await ctx.ui.custom<"closed">((_tui, theme, _keybindings, done) => {
       return new QuotasDisplay(theme, quotas, () => done("closed"));
     });
 
-    // RPC mode: custom() returns undefined by design.
+    // RPC fallback: custom() returns undefined by design.
     if (result === undefined) {
       ctx.ui.notify(formatQuotasPlain(quotas), "info");
     }
@@ -62,39 +108,73 @@ pi.registerCommand("quotas", {
 });
 ```
 
-Do not use `done(undefined)` in normal interactive close paths if you rely on `result === undefined` to detect RPC fallback.
+Do not call `done(undefined)` for normal interactive close paths if `result === undefined` detects RPC fallback.
 
-## Extracting Components
+## Commands That Trigger Agent Work
 
-Keep command handlers thin. Extract the TUI component into a separate file:
+Use `pi.sendUserMessage()` when a command should queue a user message.
 
-```
-src/
-  commands/
-    quotas.ts              # Handler + formatQuotasPlain
-  components/
-    quotas-display.ts      # QuotasDisplay component class
+```typescript
+pi.registerCommand("review-last", {
+  description: "Ask Pi to review the last change",
+  handler: async (_args, _ctx) => {
+    pi.sendUserMessage("Review the last code change for correctness.");
+  },
+});
 ```
 
-The component file should export the component class. The command file imports it and wires up the handler.
+When calling during streaming, specify delivery mode:
+
+```typescript
+pi.sendUserMessage("Focus on tests next.", { deliverAs: "steer" });
+pi.sendUserMessage("Then summarize.", { deliverAs: "followUp" });
+```
 
-## Arguments
+## Reload Command
 
-The `args` parameter is the raw string after the command name. Parse it yourself:
+Treat reload as terminal.
 
 ```typescript
-handler: async (args, ctx) => {
-  const parts = args.trim().split(/\s+/);
-  const subcommand = parts[0];
-  // ...
-},
+pi.registerCommand("reload-runtime", {
+  description: "Reload extensions, skills, prompts, and themes",
+  handler: async (_args, ctx) => {
+    await ctx.reload();
+    return;
+  },
+});
 ```
 
+Do not perform post-reload work in the same handler; it is still running in the old call frame.
+
 ## Command vs Tool
 
 | Aspect | Command | Tool |
 |---|---|---|
-| Invoked by | User (typing `/name`) | LLM (during a turn) |
-| Purpose | User-facing actions, settings, displays | LLM capabilities |
-| UI access | Full (user is present) | Limited (LLM is driving) |
-| Return value | void | `AgentToolResult` (output for LLM) |
+| Invoked by | User or RPC `prompt` with `/name` | LLM during a turn |
+| Purpose | User-facing action, setup, settings, display | Model capability |
+| UI | User is usually present; still handle RPC/print | Must avoid surprising user prompts unless designed |
+| Return | `Promise<void>` | `AgentToolResult` for the LLM |
+| Session methods | Yes, command-only methods available | No session replacement methods |
+
+If the LLM should use a capability autonomously, make it a tool. If the user intentionally invokes it, make it a command. Some features expose both: a command for setup/reload and a tool that queues that command as a follow-up.
+
+## Component Extraction
+
+Keep handlers thin. Extract rich components near the command that uses them.
+
+```
+src/commands/quotas.ts
+src/commands/components/quotas-display.ts
+```
+
+Shared components can live in `src/components/`, but do not list component files in `pi.extensions`.
+
+## Checklist
+
+- [ ] Command has a clear description.
+- [ ] Argument parsing handles empty input.
+- [ ] `getArgumentCompletions` is used when arguments have known choices.
+- [ ] Rich UI uses explicit sentinels and RPC/print fallback.
+- [ ] Session replacement uses `withSession` for post-switch work.
+- [ ] Reload command returns immediately after `ctx.reload()`.
+- [ ] Long-running or cancellable work uses available abort signals.

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

@@ -1,166 +1,331 @@
 # Components
 
-TUI components render custom UI in the terminal. They are used in `ctx.ui.custom()`, `renderResult`, and other display contexts.
+TUI components render custom UI in Pi. Use them in `ctx.ui.custom()`, tool renderers, message renderers, widgets, custom footers, and custom editors.
 
 ## Component Interface
 
 ```typescript
-import type { Component, Theme } from "@mariozechner/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
 
 class MyComponent implements Component {
-  render(maxWidth: number, maxHeight: number): string {
-    return "Hello from my component";
+  render(width: number): string[] {
+    return ["Hello from my component"];
   }
 
-  // Optional: handle keyboard input
-  handleInput?(key: string): void;
+  handleInput?(data: string): void;
+
+  invalidate(): void {
+    // Clear cached render state.
+  }
 }
 ```
 
-`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.
+Rules:
+
+- `render(width)` returns one string per line.
+- Each rendered line must fit within `width`.
+- Use `truncateToWidth()` or `wrapTextWithAnsi()` for long lines.
+- Implement `invalidate()` and clear cached themed output.
+- Use `matchesKey()` for key handling.
 
-## Available Components from pi-tui
+If a component displays a text cursor or embeds `Input`/`Editor`, implement `Focusable` and propagate `focused` to the child input so IME candidate windows appear in the right place.
 
-Before creating custom components, check if an existing one fits your need:
+## Built-in Components
 
-| Component | Description |
+Import common components from `@earendil-works/pi-tui`:
+
+```typescript
+import {
+  Box,
+  Container,
+  Image,
+  Input,
+  Markdown,
+  SelectList,
+  SettingsList,
+  Spacer,
+  Text,
+} from "@earendil-works/pi-tui";
+```
+
+Use existing components before creating your own:
+
+| Component | Use for |
 |---|---|
-| `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`:
+| `Text` | Wrapped multi-line text. |
+| `Box` | Padded/background container. |
+| `Container` | Vertical grouping of child components. |
+| `Spacer` | Empty vertical space. |
+| `Input` | Single-line text input. |
+| `Editor` | Multi-line editor. |
+| `SelectList` | Searchable/scrollable pickers. |
+| `SettingsList` | Toggle and settings rows. |
+| `Markdown` | Markdown with syntax highlighting. |
+| `Image` | Inline images in supported terminals. |
+
+Higher-level Pi components come from `@earendil-works/pi-coding-agent`:
 
 ```typescript
-import { Text, Box, Container, SelectList } from "@mariozechner/pi-tui";
+import {
+  BorderedLoader,
+  CustomEditor,
+  DynamicBorder,
+  getMarkdownTheme,
+  getSettingsListTheme,
+} from "@earendil-works/pi-coding-agent";
 ```
 
-## Utility Components from pi-coding-agent
+## `ctx.ui.custom()`
 
-These are higher-level components for common extension patterns:
+`custom()` temporarily replaces the editor with your component until `done(value)` is called.
 
-| Component | Description |
-|---|---|
-| `DynamicBorder` | Border that adjusts to content width |
-| `BorderedLoader` | Loader inside a bordered box with optional cancel |
-| `ToolExecutionComponent` | Standard tool execution display |
+```typescript
+const result = await ctx.ui.custom<string | null>((tui, theme, keybindings, done) => {
+  const list = new SelectList(items, Math.min(items.length, 10), {
+    selectedPrefix: (text) => theme.fg("accent", text),
+    selectedText: (text) => theme.fg("accent", text),
+    description: (text) => theme.fg("muted", text),
+  });
+
+  list.onSelect = (item) => done(item.value);
+  list.onCancel = () => done(null);
+
+  return {
+    render: (width) => list.render(width),
+    invalidate: () => list.invalidate(),
+    handleInput: (data) => {
+      list.handleInput?.(data);
+      tui.requestRender();
+    },
+  };
+});
+```
+
+Callback args:
 
-Import from `@mariozechner/pi-coding-agent`:
+- `tui`: request renders and inspect terminal state.
+- `theme`: current theme. Do not import a global theme.
+- `keybindings`: current app keybindings.
+- `done(value)`: close and resolve.
+
+Use explicit non-`undefined` sentinels for close/cancel paths (`null`, `false`, `"closed"`). In RPC and print modes, `custom()` returns `undefined`, so `done(undefined)` makes fallback detection ambiguous.
+
+## Overlay Mode
+
+Use overlays for modal or side-panel UI without clearing existing content.
 
 ```typescript
-import { DynamicBorder, BorderedLoader } from "@mariozechner/pi-coding-agent";
+const result = await ctx.ui.custom<string | null>(
+  (_tui, _theme, _keybindings, done) => new MyOverlay({ onClose: done }),
+  {
+    overlay: true,
+    overlayOptions: {
+      anchor: "right-center",
+      width: "50%",
+      maxHeight: "80%",
+      margin: 2,
+      visible: (termWidth) => termWidth >= 80,
+    },
+  },
+);
 ```
 
-## Using ctx.ui.custom()
+Overlay components are disposed when closed. Create a fresh instance each time you show one.
+
+## Keyboard Handling
 
-`custom()` displays a full-screen component and returns when the component calls `done()`.
+Use `matchesKey()` and `Key` from `pi-tui`.
 
 ```typescript
-const result = await ctx.ui.custom<string>((tui, theme, kb, done) => {
-  return new MyPickerComponent(theme, items, (selected) => done(selected));
-});
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+
+handleInput(data: string): void {
+  if (matchesKey(data, Key.up)) this.moveUp();
+  if (matchesKey(data, Key.down)) this.moveDown();
+  if (matchesKey(data, Key.enter)) this.confirm();
+  if (matchesKey(data, Key.escape)) this.cancel();
+}
 ```
 
-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.
+Common IDs include `Key.enter`, `Key.escape`, `Key.tab`, `Key.up`, `Key.down`, `Key.left`, `Key.right`, `Key.ctrl("c")`, and `Key.ctrlShift("p")`.
+
+## Line Width and ANSI
+
+Rendered lines must not exceed the provided width.
+
+```typescript
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+render(width: number): string[] {
+  return wrapTextWithAnsi(this.theme.fg("accent", this.text), width);
+}
+```
 
-The generic type (`<string>` above) is the type of value passed to `done()`.
+Use:
 
-Mode behavior:
-- Interactive: returns the value passed to `done(value)`.
-- RPC: returns `undefined` (by design; no local TUI).
-- Print: returns `undefined`.
+- `visibleWidth(str)` to measure display width without ANSI codes.
+- `truncateToWidth(str, width, ellipsis?)` for single-line truncation.
+- `wrapTextWithAnsi(str, width)` for wrapping styled text.
 
-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.).
+## Theming
 
-See `references/modes.md` for the three-tier pattern.
+Use the `theme` passed into render/custom callbacks.
 
-## Theme Styling
+```typescript
+theme.fg("accent", text);
+theme.fg("muted", text);
+theme.fg("success", text);
+theme.fg("error", text);
+theme.bg("toolPendingBg", text);
+theme.bold(text);
+```
 
-All render functions receive a `theme` object for consistent styling:
+For markdown in a tool or message renderer:
 
 ```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)
+const markdown = new Markdown(content, 0, 0, getMarkdownTheme());
 ```
 
-## `renderResult` is not a Component
+If a component caches strings that already include theme escape codes, rebuild those strings in `invalidate()` so theme changes apply correctly.
 
-`renderResult` is a plain render function. It returns a string (or `undefined`) and is not an interactive `Component` class.
+## Common Patterns
+
+### Selection dialog
+
+Use `SelectList` with `DynamicBorder`.
 
 ```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");
-},
+const result = await ctx.ui.custom<string | null>((tui, theme, _keybindings, done) => {
+  const container = new Container();
+  container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+  container.addChild(new Text(theme.fg("accent", theme.bold("Pick an option")), 1, 0));
+
+  const list = new SelectList(items, Math.min(items.length, 10), {
+    selectedPrefix: (t) => theme.fg("accent", t),
+    selectedText: (t) => theme.fg("accent", t),
+    description: (t) => theme.fg("muted", t),
+    scrollInfo: (t) => theme.fg("dim", t),
+    noMatch: (t) => theme.fg("warning", t),
+  });
+  list.onSelect = (item) => done(item.value);
+  list.onCancel = () => done(null);
+
+  container.addChild(list);
+  container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+  return {
+    render: (width) => container.render(width),
+    invalidate: () => container.invalidate(),
+    handleInput: (data) => {
+      list.handleInput?.(data);
+      tui.requestRender();
+    },
+  };
+});
 ```
 
-For full `renderCall`/`renderResult` formatting rules, follow `references/tools.md` (Tool UI Rendering Guidelines + consistency contract).
+### Async operation with cancel
 
-## Keyboard Handling in custom()
+Use `BorderedLoader`.
 
-Interactive components handle keyboard input through `handleInput`:
+```typescript
+const result = await ctx.ui.custom<string | null>((_tui, theme, _keybindings, done) => {
+  const loader = new BorderedLoader(_tui, theme, "Fetching data...");
+  loader.onAbort = () => done(null);
+
+  fetchData(loader.signal)
+    .then((data) => done(data))
+    .catch(() => done(null));
+
+  return loader;
+});
+```
+
+### Settings list
+
+Use `SettingsList` and `getSettingsListTheme()` for toggles. For full extension settings, prefer `registerSettingsCommand` from `@aliou/pi-utils-settings`.
+
+### Widgets and status
 
 ```typescript
-class MyComponent implements Component {
-  private done: (value: string | null) => void;
+ctx.ui.setStatus("my-extension", ctx.ui.theme.fg("accent", "active"));
+ctx.ui.setStatus("my-extension", undefined);
 
-  constructor(done: (value: string | null) => void) {
-    this.done = done;
-  }
+ctx.ui.setWidget("my-extension", ["Line 1", "Line 2"]);
+ctx.ui.setWidget("my-extension", ["Below editor"], { placement: "belowEditor" });
+ctx.ui.setWidget("my-extension", undefined);
+```
 
-  handleInput(key: string) {
-    if (key === "escape" || key === "q") {
-      this.done(null); // Cancel (explicit sentinel)
-    }
-    if (key === "return") {
-      this.done("selected"); // Confirm
+String-array widgets also work in RPC mode. Component widgets are TUI-only.
+
+### Custom footer
+
+```typescript
+ctx.ui.setFooter((tui, theme, footerData) => ({
+  invalidate() {},
+  render(width: number): string[] {
+    const branch = footerData.getGitBranch() ?? "no git";
+    return [theme.fg("dim", `${ctx.model?.id ?? "no model"} (${branch})`)];
+  },
+  dispose: footerData.onBranchChange(() => tui.requestRender()),
+}));
+
+ctx.ui.setFooter(undefined);
+```
+
+### Custom editor
+
+Extend `CustomEditor`, not the base editor, so app keybindings still work.
+
+```typescript
+class VimEditor extends CustomEditor {
+  private mode: "normal" | "insert" = "insert";
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape) && this.mode === "insert") {
+      this.mode = "normal";
+      return;
     }
+    super.handleInput(data);
   }
+}
+
+pi.on("session_start", (_event, ctx) => {
+  ctx.ui.setEditorComponent((tui, theme, keybindings) => new VimEditor(tui, theme, keybindings));
+});
+```
 
-  render(maxWidth: number, maxHeight: number): string {
-    return "Press Enter to confirm, Esc to cancel";
+Capture `ctx.ui.getEditorComponent()` before replacing the editor if you need to compose with another extension, then explicitly delegate to the previous component in your wrapper.
+
+## Rendering Tools and Messages
+
+`renderCall`, `renderResult`, and message renderers return `Component | undefined`, not raw strings.
+
+```typescript
+renderResult(result, options, theme) {
+  if (options.isPartial) {
+    return new Text(theme.fg("muted", "My Tool: loading..."), 0, 0);
   }
+  return new Text(theme.fg("success", "Done"), 0, 0);
 }
 ```
 
-## Code Highlighting
+Return `undefined` only when fallback rendering is better than custom output.
 
-For displaying code in renderers:
+## Mode Awareness
 
-```typescript
-import { highlightCode, getLanguageFromPath } from "@mariozechner/pi-coding-agent";
+- Interactive mode supports all TUI APIs.
+- RPC mode supports dialogs and fire-and-forget string events, but `custom()` returns `undefined`.
+- JSON/print modes have no UI.
 
-const lang = getLanguageFromPath("/path/to/file.ts"); // "typescript"
-const highlighted = highlightCode(code, lang, theme);
-```
+Read `references/modes.md` before using `ctx.ui.custom()` in commands or hooks.
+
+## Checklist
+
+- [ ] Existing components checked before custom component work.
+- [ ] `render(width)` returns `string[]` and respects width.
+- [ ] `invalidate()` clears cached themed output.
+- [ ] Key handling uses `matchesKey()`.
+- [ ] `ctx.ui.custom()` uses explicit sentinels and has RPC/print fallback.
+- [ ] TUI-only methods are not treated as working in RPC.
+- [ ] Tool/message renderers return components.