pi-extension-utils 0.3.1 → 0.3.3

package/dist/src/widgets/host.js

@@ -0,0 +1,143 @@
+import { basePayload, EVENTS, PROTOCOL_VERSION, } from "./protocol.js";
+const HOST_CLIENT_ID = "pi-extension-utils-host";
+const HOST_WIDGET_PREFIX = "pi-extension-utils";
+const PLACEMENTS = ["aboveEditor", "belowEditor"];
+export function registerWidgetHost(pi) {
+    const widgets = new Map();
+    const fullscreenStack = [];
+    let seq = 0;
+    let currentCtx;
+    for (const placement of PLACEMENTS)
+        widgets.set(placement, []);
+    function setHostWidget(placement) {
+        if (!currentCtx)
+            return;
+        const records = sortedWidgets(placement);
+        const hidden = fullscreenStack.length > 0;
+        if (records.length === 0 && !hidden) {
+            currentCtx.ui.setWidget(hostKey(placement), undefined, { placement });
+            return;
+        }
+        currentCtx.ui.setWidget(hostKey(placement), (tui, theme) => createHostComponent(tui, theme, records, hidden), { placement });
+    }
+    function rerenderAll() {
+        for (const placement of PLACEMENTS)
+            setHostWidget(placement);
+    }
+    pi.events.on(EVENTS.hello, (data) => {
+        const payload = readPayload(data, "hello");
+        if (!payload)
+            return;
+        pi.events.emit(EVENTS.ready, basePayload(HOST_CLIENT_ID));
+    });
+    pi.events.on(EVENTS.registerWidget, (data) => {
+        const payload = readPayload(data, "register-widget");
+        if (!payload || !isPlacement(payload.placement) || typeof payload.key !== "string" || typeof payload.order !== "number" || typeof payload.factory !== "function") {
+            warnDrop("register-widget", data);
+            return;
+        }
+        const records = widgets.get(payload.placement);
+        const existing = records.find((record) => record.clientId === payload.clientId && record.key === payload.key);
+        if (existing) {
+            existing.order = payload.order;
+            existing.factory = payload.factory;
+        }
+        else {
+            records.push({ clientId: payload.clientId, key: payload.key, order: payload.order, factory: payload.factory, seq: seq++ });
+        }
+        setHostWidget(payload.placement);
+    });
+    pi.events.on(EVENTS.unregisterWidget, (data) => {
+        const payload = readPayload(data, "unregister-widget");
+        if (!payload)
+            return;
+        if (payload.all) {
+            removeClient(payload.clientId);
+            rerenderAll();
+            return;
+        }
+        if (!isPlacement(payload.placement) || typeof payload.key !== "string") {
+            warnDrop("unregister-widget", data);
+            return;
+        }
+        const records = widgets.get(payload.placement);
+        widgets.set(payload.placement, records.filter((record) => record.clientId !== payload.clientId || record.key !== payload.key));
+        setHostWidget(payload.placement);
+    });
+    pi.events.on(EVENTS.fullscreenAcquire, (data) => {
+        const payload = readPayload(data, "fullscreen-acquire");
+        if (!payload || typeof payload.token !== "string") {
+            warnDrop("fullscreen-acquire", data);
+            return;
+        }
+        if (!fullscreenStack.some((lease) => lease.token === payload.token)) {
+            fullscreenStack.push({ clientId: payload.clientId, token: payload.token });
+            rerenderAll();
+        }
+    });
+    pi.events.on(EVENTS.fullscreenRelease, (data) => {
+        const payload = readPayload(data, "fullscreen-release");
+        if (!payload || typeof payload.token !== "string") {
+            warnDrop("fullscreen-release", data);
+            return;
+        }
+        const before = fullscreenStack.length;
+        for (let index = fullscreenStack.length - 1; index >= 0; index--) {
+            if (fullscreenStack[index].token === payload.token)
+                fullscreenStack.splice(index, 1);
+        }
+        if (fullscreenStack.length !== before)
+            rerenderAll();
+    });
+    pi.on("session_start", (_event, ctx) => {
+        currentCtx = ctx;
+        rerenderAll();
+        pi.events.emit(EVENTS.ready, basePayload(HOST_CLIENT_ID));
+    });
+    pi.events.emit(EVENTS.ready, basePayload(HOST_CLIENT_ID));
+    function removeClient(clientId) {
+        for (const placement of PLACEMENTS) {
+            widgets.set(placement, widgets.get(placement).filter((record) => record.clientId !== clientId));
+        }
+        for (let index = fullscreenStack.length - 1; index >= 0; index--) {
+            if (fullscreenStack[index].clientId === clientId)
+                fullscreenStack.splice(index, 1);
+        }
+    }
+    function sortedWidgets(placement) {
+        return [...widgets.get(placement)].sort((a, b) => a.order - b.order || a.seq - b.seq);
+    }
+}
+function createHostComponent(tui, theme, records, hidden) {
+    const components = hidden ? [] : records.map((record) => record.factory(tui, theme));
+    return {
+        render(width) {
+            return components.flatMap((component) => component.render(width));
+        },
+        invalidate() {
+            for (const component of components)
+                component.invalidate();
+        },
+    };
+}
+function hostKey(placement) {
+    return `${HOST_WIDGET_PREFIX}-${placement}`;
+}
+function readPayload(data, eventName) {
+    if (!data || typeof data !== "object") {
+        warnDrop(eventName, data);
+        return undefined;
+    }
+    const payload = data;
+    if (typeof payload.protocolVersion !== "number" || payload.protocolVersion > PROTOCOL_VERSION || typeof payload.clientId !== "string") {
+        warnDrop(eventName, data);
+        return undefined;
+    }
+    return payload;
+}
+function isPlacement(value) {
+    return value === "aboveEditor" || value === "belowEditor";
+}
+function warnDrop(eventName, data) {
+    console.warn(`pi-extension-utils: dropping invalid ${eventName} payload`, data);
+}

package/dist/src/{protocol.d.ts → widgets/protocol.d.ts}

@@ -1,3 +1,4 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 export declare const PROTOCOL_VERSION = 1;
 export declare const EVENT_PREFIX = "pi-extension-utils";
 export declare const HELLO_EVENT = "pi-extension-utils:hello";
@@ -15,12 +16,7 @@ export declare const EVENTS: {
     readonly fullscreenRelease: "pi-extension-utils:fullscreen-release";
 };
 export type WidgetPlacement = "aboveEditor" | "belowEditor";
-export interface WidgetComponent {
-    render(width: number): string[];
-    invalidate(): void;
-    dispose?(): void;
-}
-export type WidgetFactory = (tui: unknown, theme: unknown) => WidgetComponent;
+export type WidgetFactory = NonNullable<Parameters<ExtensionContext["ui"]["setWidget"]>[1]>;
 export interface ProtocolPayload {
     protocolVersion: number;
     clientId: string;

package/docs/README.md

@@ -0,0 +1,11 @@
+# Docs
+
+| Doc | Covers |
+|---|---|
+| [client.md](client.md) | `connect()`, fullscreen, reminders, logger |
+| [config.md](config.md) | Extension-owned JSON/JSONC config files |
+| [widgets.md](widgets.md) | Ordered above/below editor widgets |
+| [pane-overlay.md](pane-overlay.md) | Master/detail fullscreen overlays |
+| [reminders.md](reminders.md) | Reminder producer API |
+
+Reference artifacts live under [reference/](reference/).

package/docs/client.md

@@ -0,0 +1,91 @@
+# Client APIs
+
+Import from the package root:
+
+```ts
+import { connect, createLogger, paneOverlay } from "pi-extension-utils";
+```
+
+## Connect
+
+```ts
+const client = connect(pi, { ctx, clientId: "my-extension" });
+```
+
+| Option | Notes |
+|---|---|
+| `pi` | Extension API from your extension factory |
+| `ctx` | Current command/session context |
+| `clientId` | Stable ID used on the shared event bus |
+
+Call `client.dispose()` when a long-lived extension instance is shutting down.
+
+## Widgets
+
+```ts
+client.widgets.set("aboveEditor", "status", (tui, theme) => component, { order: 10 });
+client.widgets.remove("aboveEditor", "status");
+```
+
+| Placement | Meaning |
+|---|---|
+| `aboveEditor` | Widget above the editor |
+| `belowEditor` | Widget below the editor |
+
+The host composes widgets by `(order, insertion)`.
+
+## Fullscreen
+
+```ts
+await client.ui.fullscreen((tui, theme, keybindings, done) => new MyComponent(tui, theme, done));
+```
+
+`ui.fullscreen()`:
+
+- acquires a fullscreen lease
+- blanks coordinated widgets
+- calls `ctx.ui.custom()`
+- releases the lease in `finally`
+
+Use `client.fullscreen.acquire()` only when you need manual lease control.
+
+## Pane overlay
+
+```ts
+await client.ui.fullscreen(paneOverlay({ primary, detail }));
+```
+
+See [pane-overlay.md](pane-overlay.md).
+
+## Reminders
+
+```ts
+client.reminders.upsert({ source: "my-extension", id: "state", text: "Remember this." });
+client.reminders.remove("my-extension", "state");
+client.reminders.clearSource("my-extension");
+const snapshot = await client.reminders.list("my-extension");
+```
+
+See [reminders.md](reminders.md).
+
+## Logger
+
+```ts
+const log = createLogger("my-extension", {
+  level: "info",
+  maxFiles: 5,
+});
+
+log.debug("hidden at info level");
+log.info("started");
+log.warn("slow path");
+log.error("failed");
+```
+
+`createLogger(name)` writes to `getAgentDir()/log/<name>.log` by default. `level` is typed as `"debug" | "info" | "warn" | "error" | "silent"`; `maxFiles` controls retained rotations (`.1`, `.2`, ...). If `level`, `maxFiles`, or `maxBytes` are omitted, the value comes from `getAgentDir()/config/utils.jsonc` `logging` defaults. Explicit options always win.
+
+Override when needed:
+
+```ts
+createLogger("my-extension", { dir: "/tmp/my-extension-logs", maxBytes: 256 * 1024 });
+```

package/docs/config.md

@@ -0,0 +1,86 @@
+# Config
+
+`defineConfig()` manages extension-owned config files without touching Pi `settings.json`.
+
+## Basic use
+
+```ts
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { defineConfig } from "pi-extension-utils";
+
+const schema = Type.Object({
+  asyncByDefault: Type.Boolean({
+    default: false,
+    description: "Run jobs asynchronously unless the caller opts out.",
+  }),
+});
+
+type MyConfig = Static<typeof schema>;
+
+const config = defineConfig({
+  name: "my-extension",
+  schema,
+});
+
+const cfg: MyConfig = config.get();
+```
+
+Default path:
+
+```txt
+getAgentDir()/config/<name>.jsonc
+```
+
+Use `dir` when an extension owns a different config directory:
+
+```ts
+const config = defineConfig({
+  name: "subagent",
+  dir: getAgentDir(),
+  schema,
+});
+```
+
+That resolves either:
+
+```txt
+<dir>/subagent.jsonc
+<dir>/subagent.json
+```
+
+## JSON and JSONC
+
+Resolution is automatic:
+
+- if only `.jsonc` exists, JSONC comments and trailing commas are allowed
+- if only `.json` exists, strict JSON is used
+- if neither exists, `.jsonc` is created
+- if both exist, loading throws an ambiguity error
+
+## Defaults and comments
+
+Put defaults and comments on the TypeBox schema:
+
+```ts
+Type.Boolean({
+  default: false,
+  description: "Show hidden reminders in the transcript UI for debugging.",
+})
+```
+
+`get()` creates the file when missing, applies schema defaults, validates, caches, and returns a typed value.
+
+Generated JSONC uses `description` as comments. `update()` patches existing files through `jsonc-parser`, so existing comments and formatting are preserved where possible.
+
+## Reload and update
+
+```ts
+config.reload();
+
+config.update((cfg) => {
+  cfg.asyncByDefault = true;
+});
+```
+
+`get()` returns cached clones. Use `reload()` after external edits, such as on extension reload/session start.

package/docs/pane-overlay.md

@@ -0,0 +1,88 @@
+# Pane Overlay
+
+`paneOverlay()` builds an opinionated fullscreen master/detail UI.
+
+Use it when you want:
+
+- left/right panes
+- built-in focus, resize, cursor, scroll keys
+- derived key legend
+- custom actions that appear in the legend
+
+## Quick Start
+
+```ts
+await client.ui.fullscreen(
+  paneOverlay<void, Run>({
+    primary: {
+      title: "Runs",
+      mode: "cursor",
+      rows: () => runs,
+      selectionKey: (run) => run.id,
+      renderRow: (run) => run.label,
+    },
+    detail: {
+      title: (ctx) => ctx.selectedRow?.label ?? "Details",
+      rows: (ctx) => renderDetails(ctx.selectedRow),
+    },
+    customActions: [
+      {
+        keys: ["enter", "o"],
+        label: "collapse",
+        run: (ctx) => toggleCollapse(ctx.selectedKey),
+      },
+    ],
+  }),
+);
+```
+
+## Standard keys
+
+| Keys | Action |
+|---|---|
+| `esc`, `ctrl+c`, `q` | Close (`q` is configurable) |
+| `tab`, `←`, `→` | Switch focus |
+| `j/k`, arrows | Move cursor or scroll focused pane |
+| `u/d` | Half-page up/down |
+| `g/G`, `home/end` | Top/bottom |
+| `[/]` | Resize split |
+
+`PageUp/PageDown` are intentionally not part of this helper. Use `u/d`.
+
+## Options
+
+| Option | Purpose |
+|---|---|
+| `primary` | Left pane: list or scroll content |
+| `detail` | Right pane: content derived from selected primary row |
+| `split` | Widths, min/max, resize step |
+| `legendPlacement` | `footer` or `primary` |
+| `customActions` | Extra keys with labels and handlers |
+| `closeKeys` | Override close keys, e.g. omit `q` |
+| `collapse` | Optional primary/sidebar collapse key |
+| `perSelectionScroll` | Keep separate detail scroll per selected key |
+| `stickyBottom` | Detail starts/follows at bottom until user scrolls |
+
+## Custom actions
+
+```ts
+customActions: [
+  {
+    keys: "a",
+    label: "all sessions",
+    run: (ctx) => toggleAllSessions(),
+  },
+  {
+    keys: "y",
+    label: "copy id",
+    when: (ctx) => ctx.detailFocus,
+    run: (ctx) => copy(ctx.selectedKey),
+  },
+]
+```
+
+Custom actions run before standard movement keys and are included in the legend by default.
+
+## Examples
+
+- [examples/pane-overlay.ts](../examples/pane-overlay.ts)