@yaag/extension 0.1.0

package/src/fake-extension-ui.ts

@@ -0,0 +1,183 @@
+/**
+ * A fully typed `ExtensionUIContext` for the tui-mode test context.
+ *
+ * `custom`, `notify`, `editor`, `setWidget`, and a scripted `select` work;
+ * every other capability throws, so a dependency a view is not supposed to
+ * have fails loudly. The
+ * class implements the interface, so pi's UI surface is checked at compile
+ * time and no `as` cast is needed at the seam.
+ */
+import type {
+  ExtensionUIContext,
+  KeybindingsManager,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { fakeTheme } from "./fake-theme.ts";
+import { FakeTerminal, FakeTui } from "./fake-tui.ts";
+import { loadPiKeybindings } from "./pi-keybindings.ts";
+
+/** The live component `custom` opened, as a test drives it. */
+export interface OpenedComponent {
+  render(width: number): string[];
+  input(data: string): void;
+  /** How many redraws the component requested so far. */
+  readonly renders: number;
+}
+
+/** A notification the view sent to the Host Session. */
+export interface Notice {
+  readonly message: string;
+  readonly level: "info" | "warning" | "error";
+}
+
+/** An editor the view opened, with the body it pre-filled. */
+export interface OpenedEditor {
+  readonly title: string;
+  readonly body: string;
+}
+
+/**
+ * The fake terminal size a test gives the view. Both fields are optional and
+ * default to a 20x100 terminal; no value here can make construction fail.
+ */
+export interface FakeExtensionUiOptions {
+  /** Terminal rows the fake TUI reports; the view sizes overlays from it. */
+  readonly rows?: number;
+  /** Terminal columns the fake TUI reports. */
+  readonly columns?: number;
+}
+
+/** Runs the factory `ctx.ui.custom()` receives against fake pi services. */
+export class FakeExtensionUi implements ExtensionUIContext {
+  readonly notices: Notice[] = [];
+  readonly edits: OpenedEditor[] = [];
+  /** The latest frame per widget key; `undefined` means the key was cleared. */
+  readonly widgets = new Map<string, string[] | undefined>();
+  /** Answers `select` in order; an empty queue answers `undefined`, i.e. esc. */
+  readonly selections: string[] = [];
+  /** The component `custom` opened, once a Run opened one. */
+  opened: OpenedComponent | undefined;
+  readonly theme: Theme = fakeTheme();
+
+  readonly #tui: FakeTui;
+
+  constructor(options: FakeExtensionUiOptions = {}) {
+    this.#tui = new FakeTui(new FakeTerminal(options.rows ?? 20, options.columns ?? 100));
+  }
+
+  custom<T>(
+    factory: (
+      tui: TUI,
+      theme: Theme,
+      keybindings: KeybindingsManager,
+      done: (result: T) => void,
+    ) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>,
+  ): Promise<T> {
+    let resolve: (value: T) => void = () => {};
+    const promise = new Promise<T>((settle) => {
+      resolve = settle;
+    });
+    // Synchronous on purpose: a test drives the component right after the call,
+    // with no scheduling of its own.
+    const component = factory(this.#tui, this.theme, loadPiKeybindings(), resolve);
+    if (component instanceof Promise) {
+      throw new TypeError("FakeExtensionUi.custom: the factory must return a component directly");
+    }
+    const tui = this.#tui;
+    this.opened = {
+      render: (width) => component.render(width),
+      input: (data) => component.handleInput?.(data),
+      get renders() {
+        return tui.renders;
+      },
+    };
+    return promise;
+  }
+
+  notify(message: string, type?: "info" | "warning" | "error"): void {
+    this.notices.push({ message, level: type ?? "info" });
+  }
+
+  async editor(title: string, prefill?: string): Promise<string | undefined> {
+    this.edits.push({ title, body: prefill ?? "" });
+    return prefill;
+  }
+
+  async select(): Promise<string | undefined> {
+    return this.selections.shift();
+  }
+  async confirm(): Promise<boolean> {
+    return unavailable("ui.confirm");
+  }
+  async input(): Promise<string | undefined> {
+    return unavailable("ui.input");
+  }
+  onTerminalInput(): () => void {
+    return unavailable("ui.onTerminalInput");
+  }
+  setStatus(): void {
+    unavailable("ui.setStatus");
+  }
+  setWorkingMessage(): void {
+    unavailable("ui.setWorkingMessage");
+  }
+  setWorkingVisible(): void {
+    unavailable("ui.setWorkingVisible");
+  }
+  setWorkingIndicator(): void {
+    unavailable("ui.setWorkingIndicator");
+  }
+  setHiddenThinkingLabel(): void {
+    unavailable("ui.setHiddenThinkingLabel");
+  }
+  setWidget(key: string, content?: string[] | unknown): void {
+    this.widgets.set(key, Array.isArray(content) ? content.map(String) : undefined);
+  }
+  setFooter(): void {
+    unavailable("ui.setFooter");
+  }
+  setHeader(): void {
+    unavailable("ui.setHeader");
+  }
+  setTitle(): void {
+    unavailable("ui.setTitle");
+  }
+  pasteToEditor(): void {
+    unavailable("ui.pasteToEditor");
+  }
+  setEditorText(): void {
+    unavailable("ui.setEditorText");
+  }
+  getEditorText(): string {
+    return unavailable("ui.getEditorText");
+  }
+  addAutocompleteProvider(): void {
+    unavailable("ui.addAutocompleteProvider");
+  }
+  setEditorComponent(): void {
+    unavailable("ui.setEditorComponent");
+  }
+  getEditorComponent(): undefined {
+    return unavailable("ui.getEditorComponent");
+  }
+  getAllThemes(): { name: string; path: string | undefined }[] {
+    return unavailable("ui.getAllThemes");
+  }
+  getTheme(): Theme | undefined {
+    return unavailable("ui.getTheme");
+  }
+  setTheme(): { success: boolean; error?: string } {
+    return unavailable("ui.setTheme");
+  }
+  getToolsExpanded(): boolean {
+    return unavailable("ui.getToolsExpanded");
+  }
+  setToolsExpanded(): void {
+    unavailable("ui.setToolsExpanded");
+  }
+}
+
+function unavailable(capability: string): never {
+  throw new Error(`unexpected test context dependency: ${capability}`);
+}

package/src/fake-theme.ts

@@ -0,0 +1,72 @@
+/**
+ * A `Theme` instance for tests, built from an explicit colour table.
+ *
+ * `ctx.ui.custom()` hands a real `Theme` to its factory, so the tui-mode test
+ * context needs one. The table is written out in full: TypeScript checks it
+ * against `ThemeColor`/`ThemeBg`, which keeps the double honest without a cast.
+ */
+import { Theme } from "@earendil-works/pi-coding-agent";
+
+/** Default 256-colour indexes; every colour renders as plain text. */
+const FOREGROUND = {
+  accent: 7,
+  border: 7,
+  borderAccent: 7,
+  borderMuted: 7,
+  success: 7,
+  error: 7,
+  warning: 7,
+  muted: 7,
+  dim: 7,
+  text: 7,
+  thinkingText: 7,
+  userMessageText: 7,
+  customMessageText: 7,
+  customMessageLabel: 7,
+  toolTitle: 7,
+  toolOutput: 7,
+  mdHeading: 7,
+  mdLink: 7,
+  mdLinkUrl: 7,
+  mdCode: 7,
+  mdCodeBlock: 7,
+  mdCodeBlockBorder: 7,
+  mdQuote: 7,
+  mdQuoteBorder: 7,
+  mdHr: 7,
+  mdListBullet: 7,
+  toolDiffAdded: 7,
+  toolDiffRemoved: 7,
+  toolDiffContext: 7,
+  syntaxComment: 7,
+  syntaxKeyword: 7,
+  syntaxFunction: 7,
+  syntaxVariable: 7,
+  syntaxString: 7,
+  syntaxNumber: 7,
+  syntaxType: 7,
+  syntaxOperator: 7,
+  syntaxPunctuation: 7,
+  thinkingOff: 7,
+  thinkingMinimal: 7,
+  thinkingLow: 7,
+  thinkingMedium: 7,
+  thinkingHigh: 7,
+  thinkingXhigh: 7,
+  thinkingMax: 7,
+  bashMode: 7,
+} as const satisfies Record<string, number>;
+
+const BACKGROUND = {
+  selectedBg: 0,
+  userMessageBg: 0,
+  customMessageBg: 0,
+  toolPendingBg: 0,
+  toolSuccessBg: 0,
+  toolErrorBg: 0,
+} as const satisfies Record<string, number>;
+
+/** Builds the test theme. Colours are inert, so frames stay comparable. */
+export function fakeTheme(): Theme {
+  return new Theme(FOREGROUND, BACKGROUND, "256color", { name: "test" });
+}

package/src/fake-tui.ts

@@ -0,0 +1,165 @@
+/**
+ * Fully typed `TUI` and `Terminal` doubles for the tui-mode test context.
+ *
+ * The foreground Run view uses three capabilities only: `terminal.rows`,
+ * `terminal.columns`, and `requestRender()`. Every other member of `Terminal`
+ * and `TUI` — fields and getters included — throws on access, so a component
+ * that starts to depend on the terminal fails loudly in the test instead of
+ * behaving differently in production. `renders` is the fake's own counter, not
+ * part of pi's surface.
+ */
+import type {
+  Component,
+  OverlayHandle,
+  RgbColor,
+  Terminal,
+  TerminalColorScheme,
+  TUI,
+  TuiInputListener,
+  TuiMode,
+} from "@earendil-works/pi-tui";
+
+/** A terminal of a fixed size that refuses every write. */
+export class FakeTerminal implements Terminal {
+  constructor(
+    readonly rows: number,
+    readonly columns: number,
+  ) {}
+
+  get kittyProtocolActive(): boolean {
+    return unavailable("terminal.kittyProtocolActive");
+  }
+
+  start(): void {
+    unavailable("terminal.start");
+  }
+  stop(): void {
+    unavailable("terminal.stop");
+  }
+  async drainInput(): Promise<void> {
+    unavailable("terminal.drainInput");
+  }
+  write(): void {
+    unavailable("terminal.write");
+  }
+  moveBy(): void {
+    unavailable("terminal.moveBy");
+  }
+  hideCursor(): void {
+    unavailable("terminal.hideCursor");
+  }
+  showCursor(): void {
+    unavailable("terminal.showCursor");
+  }
+  clearLine(): void {
+    unavailable("terminal.clearLine");
+  }
+  clearFromCursor(): void {
+    unavailable("terminal.clearFromCursor");
+  }
+  clearScreen(): void {
+    unavailable("terminal.clearScreen");
+  }
+  setTitle(): void {
+    unavailable("terminal.setTitle");
+  }
+  setProgress(): void {
+    unavailable("terminal.setProgress");
+  }
+}
+
+/** A TUI that counts redraw requests instead of drawing. */
+export class FakeTui implements TUI {
+  /** How many times a component asked for a redraw. */
+  renders = 0;
+
+  constructor(readonly terminal: Terminal) {}
+
+  get mode(): TuiMode {
+    return unavailable("tui.mode");
+  }
+
+  get children(): Component[] {
+    return unavailable("tui.children");
+  }
+
+  get fullRedraws(): number {
+    return unavailable("tui.fullRedraws");
+  }
+
+  requestRender(): void {
+    this.renders += 1;
+  }
+
+  render(): string[] {
+    return unavailable("tui.render");
+  }
+  invalidate(): void {
+    unavailable("tui.invalidate");
+  }
+
+  addChild(): void {
+    unavailable("tui.addChild");
+  }
+  removeChild(): void {
+    unavailable("tui.removeChild");
+  }
+  clear(): void {
+    unavailable("tui.clear");
+  }
+  getShowHardwareCursor(): boolean {
+    return unavailable("tui.getShowHardwareCursor");
+  }
+  setShowHardwareCursor(): void {
+    unavailable("tui.setShowHardwareCursor");
+  }
+  getClearOnShrink(): boolean {
+    return unavailable("tui.getClearOnShrink");
+  }
+  setClearOnShrink(): void {
+    unavailable("tui.setClearOnShrink");
+  }
+  setFocus(): void {
+    unavailable("tui.setFocus");
+  }
+  showOverlay(): OverlayHandle {
+    return unavailable("tui.showOverlay");
+  }
+  hideOverlay(): void {
+    unavailable("tui.hideOverlay");
+  }
+  hasOverlay(): boolean {
+    return unavailable("tui.hasOverlay");
+  }
+  start(): void {
+    unavailable("tui.start");
+  }
+  stop(): void {
+    unavailable("tui.stop");
+  }
+  renderNow(): void {
+    unavailable("tui.renderNow");
+  }
+  addInputListener(_listener: TuiInputListener): () => void {
+    return unavailable("tui.addInputListener");
+  }
+  removeInputListener(): void {
+    unavailable("tui.removeInputListener");
+  }
+  onTerminalColorSchemeChange(): () => void {
+    return unavailable("tui.onTerminalColorSchemeChange");
+  }
+  setTerminalColorSchemeNotifications(): void {
+    unavailable("tui.setTerminalColorSchemeNotifications");
+  }
+  async queryTerminalBackgroundColor(): Promise<RgbColor | undefined> {
+    return unavailable("tui.queryTerminalBackgroundColor");
+  }
+  async queryTerminalColorScheme(): Promise<TerminalColorScheme | undefined> {
+    return unavailable("tui.queryTerminalColorScheme");
+  }
+}
+
+function unavailable(capability: string): never {
+  throw new Error(`unexpected test tui dependency: ${capability}`);
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createBackgroundWidget } from "./background-widget.ts";
+import { createDescribeTool } from "./describe-tool.ts";
+import { findProgramDirectories } from "./program-directories.ts";
+import { resolveBun } from "./resolve-bun.ts";
+import { resolveCliEntry } from "./resolve-cli.ts";
+import { createRunCompleteRenderer } from "./run-complete-renderer.ts";
+import { RunRegistry } from "./run-registry.ts";
+import { createRunTool } from "./run-tool.ts";
+import { RunTreeStore } from "./run-trees.ts";
+import { createSetupWorkspaceExecutor } from "./setup-workspace.ts";
+import { createSetupWorkspaceCommand } from "./setup-workspace-command.ts";
+import { createSetupWorkspaceTool } from "./setup-workspace-tool.ts";
+import { statusReport } from "./status.ts";
+import { createStatusTool } from "./status-tool.ts";
+import { createStopTool } from "./stop-tool.ts";
+import { createSystemPromptAppender } from "./system-prompt-append.ts";
+import { createYaagCommand } from "./yaag-command.ts";
+
+/**
+ * The yaag pi extension. Loaded by pi through jiti, in Node — nothing here may
+ * touch a Bun-only API (ADR-0005). It resolves the bridge to the Bun CLI once,
+ * at load, and reports what it found. Run execution, program discovery, and
+ * workspace setup bridge from pi's Node process to the Bun CLI.
+ *
+ * The run, describe, and workspace-setup tools are registered even when Bun is
+ * missing: a tool that explains how to install Bun is more use to a model than one absent.
+ */
+export default async function (pi: ExtensionAPI): Promise<void> {
+  const bun = await resolveBun();
+  const cli = resolveCliEntry();
+  const report = statusReport(bun, cli);
+
+  // One registry per session retains every foreground and background Run.
+  const registry = new RunRegistry();
+  // The renderer projections and the one combined inline widget both live for
+  // the session, beside the registry, so a background Run keeps a tree.
+  const store = new RunTreeStore();
+  const widget = createBackgroundWidget({ registry, store });
+  pi.registerTool(
+    createRunTool({ bun, cli, registry, store, widget, sendMessage: pi.sendMessage.bind(pi) }),
+  );
+  pi.registerTool(createStatusTool(registry));
+  pi.registerMessageRenderer("yaag-run-complete", createRunCompleteRenderer());
+  pi.registerTool(createDescribeTool({ bun, cli }));
+  const workspaceSetup = createSetupWorkspaceExecutor({ bun, cli });
+  pi.registerTool(createSetupWorkspaceTool({ executor: workspaceSetup }));
+  pi.registerTool(createStopTool(registry));
+
+  // Host discovery: when this repo holds a Program Directory, tell the session
+  // where programs live and how to author one. The handler's result REPLACES
+  // the turn's system prompt, so it re-emits the incoming prompt first.
+  const appendYaagPrompt = createSystemPromptAppender(() => findProgramDirectories(process.cwd()));
+  pi.on("before_agent_start", (event) => appendYaagPrompt(event));
+
+  pi.on("session_start", (_event, ctx) => {
+    if (bun === null) ctx.ui.notify(report, "error");
+    if (ctx.hasUI) widget.bind(ctx.ui);
+  });
+
+  // Commands and tools have separate namespaces: this CLI-resolution command
+  // deliberately keeps its established hyphenated name beside `yaag_status`.
+  pi.registerCommand("yaag-status", {
+    description: "Show how yaag resolved Bun and the yaag CLI",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(report, bun === null ? "error" : "info");
+    },
+  });
+  pi.registerCommand("yaag-setup-workspace", createSetupWorkspaceCommand(workspaceSetup));
+
+  // Human-only, read-only interactive Run tree over any Run of this session.
+  pi.registerCommand("yaag", createYaagCommand({ registry, store }));
+}

package/src/pi-keybindings.ts

@@ -0,0 +1,45 @@
+/**
+ * Loads pi's own `KeybindingsManager` for tests.
+ *
+ * `ctx.ui.custom()` hands the factory a pi `KeybindingsManager`. Pi exports
+ * that class as a type only, and its private field makes it impossible to
+ * implement, so a fake UI must give the factory the real class. This module
+ * loads it from the installed package and narrows the import with a runtime
+ * check, so a pi release that moves or renames the class fails here with a
+ * clear message instead of at the first keystroke.
+ *
+ * The load is synchronous, so `ctx.ui.custom()` can stay synchronous in tests.
+ */
+import { createRequire } from "node:module";
+import { getPackageDir, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
+
+const require = createRequire(import.meta.url);
+
+/** Builds a manager over pi's default bindings. Throws when pi's shape changed. */
+export function loadPiKeybindings(): KeybindingsManager {
+  const source = `${getPackageDir()}/dist/core/keybindings.js`;
+  const module: unknown = require(source);
+  if (typeof module !== "object" || module === null || !("KeybindingsManager" in module)) {
+    throw new Error(`pi keybindings: ${source} exports no KeybindingsManager`);
+  }
+  const exported = module.KeybindingsManager;
+  if (typeof exported !== "function") {
+    throw new Error(`pi keybindings: ${source} exports a non-constructor KeybindingsManager`);
+  }
+  const manager: unknown = Reflect.construct(exported, []);
+  if (!isKeybindingsManager(manager)) {
+    throw new Error("pi keybindings: the constructed manager has an unexpected shape");
+  }
+  return manager;
+}
+
+/** Every member the loaded object must have to be pi's manager. */
+const MEMBERS = ["matches", "getKeys", "setUserBindings", "reload", "getEffectiveConfig"] as const;
+
+function isKeybindingsManager(value: unknown): value is KeybindingsManager {
+  if (typeof value !== "object" || value === null) return false;
+  return MEMBERS.every((name) => {
+    const member: unknown = Reflect.get(value, name);
+    return typeof member === "function";
+  });
+}

package/src/program-directories.ts

@@ -0,0 +1,29 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+const MAX_DEPTH = 4;
+const SKIPPED = new Set(["node_modules"]);
+
+/**
+ * Finds Program Directories: directories containing a `.yaag` subdirectory.
+ * Bounded breadth-first walk — depth <= 4, skips node_modules and dot-dirs —
+ * so the per-turn cost of host discovery stays negligible.
+ */
+export async function findProgramDirectories(root: string): Promise<readonly string[]> {
+  const found: string[] = [];
+  let frontier: readonly string[] = [root];
+  for (let depth = 0; depth <= MAX_DEPTH && frontier.length > 0; depth += 1) {
+    const next: string[] = [];
+    for (const dir of frontier) {
+      const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name === ".yaag") found.push(dir);
+        else if (!entry.name.startsWith(".") && !SKIPPED.has(entry.name))
+          next.push(join(dir, entry.name));
+      }
+    }
+    frontier = next;
+  }
+  return found.sort();
+}

package/src/resolve-bun.ts

@@ -0,0 +1,35 @@
+import { access, constants } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+
+/** Where to look for a `bun` executable. Injectable so the search is testable. */
+export interface BunSearch {
+  /** A `PATH`-shaped list of directories. */
+  readonly path: string;
+  /** The user's home directory, holding the conventional `.bun/bin` install. */
+  readonly home: string;
+}
+
+/**
+ * Finds a `bun` executable: `PATH` first, then the conventional user install
+ * location (`~/.bun/bin`). Returns null when there is none — the caller decides
+ * how to surface that (ADR-0015).
+ */
+export async function resolveBun(search?: BunSearch): Promise<string | null> {
+  const { path, home } = search ?? { path: process.env.PATH ?? "", home: homedir() };
+  const dirs = [...path.split(delimiter).filter(Boolean), join(home, ".bun", "bin")];
+  for (const dir of dirs) {
+    const candidate = join(dir, "bun");
+    if (await isExecutable(candidate)) return candidate;
+  }
+  return null;
+}
+
+async function isExecutable(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/resolve-cli.ts

@@ -0,0 +1,9 @@
+import { createRequire } from "node:module";
+
+/**
+ * Resolves the `yaag` CLI entry point through node resolution, so it works both
+ * in-monorepo (workspace symlink) and from a published tarball (ADR-0015).
+ */
+export function resolveCliEntry(): string {
+  return createRequire(import.meta.url).resolve("yaag/src/cli.ts");
+}

package/src/run-complete-renderer.ts

@@ -0,0 +1,20 @@
+import type { MessageRenderer } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { parseRunDetails } from "./run-details.ts";
+import { RunTreeComponent } from "./run-tree-component.ts";
+
+/** Renders the completion Run tree when the durable message carries valid details. */
+export function createRunCompleteRenderer(): MessageRenderer<unknown> {
+  return (message, { outputPad }, theme) => {
+    const details = parseRunDetails(message.details);
+    if (details === undefined)
+      return new Text(theme.fg("customMessageText", messageText(message.content)), outputPad, 0);
+    const box = new Box(outputPad, 0, (text) => theme.bg("customMessageBg", text));
+    box.addChild(new RunTreeComponent(details));
+    return box;
+  };
+}
+
+function messageText(value: string | readonly unknown[]): string {
+  return typeof value === "string" ? value : value.map((part) => JSON.stringify(part)).join("\n");
+}