pi-chassis 0.0.0-stage → 0.7.1

package/dist/chassis/bash-output.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Bash tool output for the one-line tool rows: separate what pi appended to the text (exit status,
+ * truncation notice) from what the command printed, clean the printed lines for the screen, and
+ * fold them. Pure functions with no pi imports, so tests run standalone.
+ *
+ * pi adds its notices at the END of the text, after a blank line:
+ *
+ *     <output>
+ *
+ *     [Showing lines 1001-3000 of 3000. Full output: /tmp/pi-bash-x.log]      (only when truncated)
+ *
+ *     Command exited with code 3                                              (only on failure)
+ *
+ * Only that trailing position is read, so output that merely contains those words is never
+ * mistaken for a notice.
+ */
+export type BashStatus = "ok" | "failed" | "aborted" | "timeout" | "no-exit";
+/** How long a command runs before its live output appears under the row. */
+export declare const LIVE_DELAY_MS = 500;
+/** Lines of live output shown under a running row. */
+export declare const LIVE_TAIL_LINES = 5;
+/** Lines of a finished command's output left under its row until the row is expanded. */
+export declare const PEEK_LINES = 3;
+export interface BashOutput {
+    /** What the command printed, cleaned for display, without pi's notices. */
+    lines: string[];
+    status: BashStatus;
+    /** The exit code, when pi reported one. */
+    exitCode?: number;
+    timeoutSecs?: number;
+    /** pi cut the output; `lines` holds only the part it kept (the end). */
+    truncated: boolean;
+    /** Lines the command printed, counting those pi cut. Equals `lines.length` when not truncated. */
+    totalLines: number;
+    fullOutputPath?: string;
+}
+export interface BashOutputHints {
+    /** Whether pi reports this result as an error. */
+    isError: boolean;
+    /** `result.details.truncation` */
+    truncation?: {
+        truncated?: boolean;
+        totalLines?: number;
+    };
+    /** `result.details.fullOutputPath` */
+    fullOutputPath?: string;
+}
+/**
+ * One output line as plain text: every escape sequence removed (colour, cursor movement, titles,
+ * hyperlinks), a progress line that was redrawn with carriage returns reduced to its last state,
+ * tabs widened, other control characters dropped.
+ */
+export declare function cleanLine(line: string): string;
+/** A line longer than this is cut, like OpenCode's character cap: no terminal shows more. */
+export declare const MAX_LINE_CHARS = 1000;
+/** Split pi's bash result text into the command's output and the status pi attached. */
+export declare function parseBashOutput(raw: string, hints: BashOutputHints): BashOutput;
+/** The first or last `keep` lines, and how many of the given lines were left out. */
+export declare function foldLines(lines: string[], keep: number, from: "head" | "tail"): {
+    shown: string[];
+    hidden: number;
+};
+/** "2.1s" for a run of a second or more, else undefined (a 0.0s tag is noise). */
+export declare function formatWallTime(seconds: unknown): string | undefined;
+/**
+ * The live output of a command that is still running, from the partial result pi sends while it
+ * runs (the text so far, cut to its last lines by pi). Returns the last `keep` lines, cleaned for
+ * the screen, and how many earlier lines are not shown. There is no status to read yet, so nothing
+ * is removed from the end: a line that looks like a notice is just a line.
+ */
+export declare function liveTail(raw: string, keep?: number): {
+    lines: string[];
+    earlier: number;
+};
+/**
+ * Whether a running row should show its live output yet: it has waited `LIVE_DELAY_MS` since it
+ * first appeared, and there is something to show.
+ */
+export declare function liveVisible(firstSeenAt: number | undefined, now: number, hasOutput: boolean): boolean;
+/** Milliseconds until a row that is not yet visible should look again, or undefined if it never will. */
+export declare function liveWaitMs(firstSeenAt: number | undefined, now: number): number | undefined;
+/**
+ * What stays visible under a finished row: the last `keep` lines (an error is usually at the end),
+ * and how many lines are not shown, counting those pi cut from a very long output.
+ */
+export declare function bashPeek(out: BashOutput, keep?: number): {
+    lines: string[];
+    hidden: number;
+};

package/dist/chassis/bash-output.js

@@ -0,0 +1,157 @@
+/**
+ * Bash tool output for the one-line tool rows: separate what pi appended to the text (exit status,
+ * truncation notice) from what the command printed, clean the printed lines for the screen, and
+ * fold them. Pure functions with no pi imports, so tests run standalone.
+ *
+ * pi adds its notices at the END of the text, after a blank line:
+ *
+ *     <output>
+ *
+ *     [Showing lines 1001-3000 of 3000. Full output: /tmp/pi-bash-x.log]      (only when truncated)
+ *
+ *     Command exited with code 3                                              (only on failure)
+ *
+ * Only that trailing position is read, so output that merely contains those words is never
+ * mistaken for a notice.
+ */
+/** How long a command runs before its live output appears under the row. */
+export const LIVE_DELAY_MS = 500;
+/** Lines of live output shown under a running row. */
+export const LIVE_TAIL_LINES = 5;
+/** Lines of a finished command's output left under its row until the row is expanded. */
+export const PEEK_LINES = 3;
+const EXIT = /^Command exited with code (-?\d+)$/;
+const TIMEOUT = /^Command timed out after (\d+(?:\.\d+)?) seconds?$/;
+const SHOWING = /^\[Showing .*Full output: (.+)\]$/;
+const CSI = /\x1b\[[0-9;:?<=>]*[ -/]*[@-~]/g;
+const OSC = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g;
+const OTHER_ESC = /\x1b[\s\S]?/g;
+const CONTROL = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+/**
+ * One output line as plain text: every escape sequence removed (colour, cursor movement, titles,
+ * hyperlinks), a progress line that was redrawn with carriage returns reduced to its last state,
+ * tabs widened, other control characters dropped.
+ */
+export function cleanLine(line) {
+    const plain = line.replace(CSI, "").replace(OSC, "").replace(OTHER_ESC, "");
+    const last = plain.split("\r").reverse().find((p) => p.trim() !== "") ?? "";
+    const clean = last.replace(/\t/g, "  ").replace(CONTROL, "").replace(/\s+$/, "");
+    return capLine(clean);
+}
+/** A line longer than this is cut, like OpenCode's character cap: no terminal shows more. */
+export const MAX_LINE_CHARS = 1000;
+function capLine(line) {
+    if (line.length <= MAX_LINE_CHARS)
+        return line;
+    // Cut by code points, so an emoji is never split in half.
+    return `${[...line].slice(0, MAX_LINE_CHARS - 1).join("")}…`;
+}
+/** Split pi's bash result text into the command's output and the status pi attached. */
+export function parseBashOutput(raw, hints) {
+    const all = raw.replace(/\r\n/g, "\n").split("\n");
+    const dropBlankTail = () => {
+        while (all.length && all[all.length - 1].trim() === "")
+            all.pop();
+    };
+    dropBlankTail();
+    let status = "ok";
+    let exitCode;
+    let timeoutSecs;
+    if (hints.isError) {
+        status = "failed";
+        const last = all[all.length - 1] ?? "";
+        let m;
+        if ((m = last.match(EXIT))) {
+            exitCode = Number(m[1]);
+            all.pop();
+        }
+        else if (last === "Command aborted") {
+            status = "aborted";
+            all.pop();
+        }
+        else if ((m = last.match(TIMEOUT))) {
+            status = "timeout";
+            timeoutSecs = Number(m[1]);
+            all.pop();
+        }
+        else if (last === "Command terminated without an exit code") {
+            status = "no-exit";
+            all.pop();
+        }
+        else if (/operation was aborted/i.test(raw)) {
+            status = "aborted";
+        }
+        dropBlankTail();
+    }
+    let truncated = false;
+    let fullOutputPath = hints.fullOutputPath;
+    if (hints.truncation?.truncated) {
+        truncated = true;
+        const m = (all[all.length - 1] ?? "").match(SHOWING);
+        if (m) {
+            fullOutputPath = m[1];
+            all.pop();
+            dropBlankTail();
+        }
+    }
+    // pi's placeholder for a command that printed nothing.
+    if (all.length === 1 && all[0] === "(no output)")
+        all.length = 0;
+    const lines = all.map(cleanLine);
+    const reported = hints.truncation?.totalLines;
+    const totalLines = truncated && typeof reported === "number" && reported >= lines.length ? reported : lines.length;
+    return { lines, status, exitCode, timeoutSecs, truncated, totalLines, fullOutputPath };
+}
+/** The first or last `keep` lines, and how many of the given lines were left out. */
+export function foldLines(lines, keep, from) {
+    if (lines.length <= keep)
+        return { shown: lines, hidden: 0 };
+    return { shown: from === "head" ? lines.slice(0, keep) : lines.slice(lines.length - keep), hidden: lines.length - keep };
+}
+/** "2.1s" for a run of a second or more, else undefined (a 0.0s tag is noise). */
+export function formatWallTime(seconds) {
+    if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 1)
+        return undefined;
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    const m = Math.floor(seconds / 60);
+    return `${m}m${String(Math.round(seconds % 60)).padStart(2, "0")}s`;
+}
+/**
+ * The live output of a command that is still running, from the partial result pi sends while it
+ * runs (the text so far, cut to its last lines by pi). Returns the last `keep` lines, cleaned for
+ * the screen, and how many earlier lines are not shown. There is no status to read yet, so nothing
+ * is removed from the end: a line that looks like a notice is just a line.
+ */
+export function liveTail(raw, keep = LIVE_TAIL_LINES) {
+    const all = raw.replace(/\r\n/g, "\n").split("\n");
+    while (all.length && all[all.length - 1].trim() === "")
+        all.pop();
+    const lines = all.map(cleanLine);
+    // A last line that cleans to nothing (a bare redraw escape) would show as an empty row.
+    while (lines.length && lines[lines.length - 1] === "")
+        lines.pop();
+    const { shown, hidden } = foldLines(lines, keep, "tail");
+    return { lines: shown, earlier: hidden };
+}
+/**
+ * Whether a running row should show its live output yet: it has waited `LIVE_DELAY_MS` since it
+ * first appeared, and there is something to show.
+ */
+export function liveVisible(firstSeenAt, now, hasOutput) {
+    return hasOutput && firstSeenAt !== undefined && now - firstSeenAt >= LIVE_DELAY_MS;
+}
+/** Milliseconds until a row that is not yet visible should look again, or undefined if it never will. */
+export function liveWaitMs(firstSeenAt, now) {
+    if (firstSeenAt === undefined)
+        return undefined;
+    return Math.max(0, LIVE_DELAY_MS - (now - firstSeenAt)) + 10;
+}
+/**
+ * What stays visible under a finished row: the last `keep` lines (an error is usually at the end),
+ * and how many lines are not shown, counting those pi cut from a very long output.
+ */
+export function bashPeek(out, keep = PEEK_LINES) {
+    const { shown } = foldLines(out.lines, keep, "tail");
+    return { lines: shown, hidden: Math.max(0, out.totalLines - shown.length) };
+}

package/dist/chassis/brand.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Brand: the few things that make the TUI look like a particular product: the mark shown next to
+ * the version, the startup art and tagline, and the accent colours of the chrome.
+ *
+ * chassis ships a neutral default. A separate package layers its own identity on top by calling
+ * `registerBrand()` from client.ts:
+ *
+ *     import { registerBrand } from "pi-chassis/client";
+ *     export default function () {
+ *       registerBrand({ name: "Acme", glyph: "A", colors: { primary: "#E4572E" } });
+ *     }
+ *
+ * The brand is stored on globalThis (the same reason the widget registry is: pi loads every
+ * extension in its own module scope) and read while rendering, so load order does not matter and
+ * a later registration simply wins. Fields left out keep the defaults.
+ *
+ * This file has no imports, so client.ts can re-export it without loading anything else.
+ */
+/** `#RRGGBB` (or any colour string pi-tui's parseColor accepts). */
+export type ColorValue = string;
+export interface BrandColors {
+    /** Build-mode rail and badge, focus marks, the mark next to the version. */
+    primary: ColorValue;
+    /** Darker companion of `primary`. */
+    primaryDark: ColorValue;
+    /** Plan-mode rail and badge, and the provider glyph in the sidebar. */
+    plan: ColorValue;
+    /** Quiet brand neutral used for taglines. */
+    neutral: ColorValue;
+}
+export interface BrandSurfaces {
+    /** Sidebar, user messages, tool blocks. Keep in step with the theme's panel colour. */
+    panel: ColorValue;
+    /** The prompt box. Keep in step with the theme's raised panel colour. */
+    element: ColorValue;
+}
+/**
+ * `surfaces` are for dark themes, and `lightSurfaces` for light ones (a theme says which it is with
+ * its `appearance`). Text that chassis draws in a brand colour is darkened on a light surface until
+ * it can be read; rails, bars and the mode pill keep the brand colour exactly.
+ */
+export interface BrandSpec {
+    /** Shown as "<glyph> <name> pi <version>". Leave out for "<glyph> pi <version>". */
+    name?: string;
+    /** A single-cell mark. Pick one your users' fonts have, or ship a font that does. */
+    glyph?: string;
+    /** Line under the startup art. */
+    tagline?: string;
+    /** Startup header art, one string per row, painted in `primary`. Default: the pi logo. */
+    art?: string[];
+    colors?: Partial<BrandColors>;
+    /** For dark themes. */
+    surfaces?: Partial<BrandSurfaces>;
+    /** For light themes. Default: a light neutral pair. */
+    lightSurfaces?: Partial<BrandSurfaces>;
+    /**
+     * The icon set to use when the user has not chosen one: "nerd" for a brand whose users have a
+     * Nerd Font (or that ships one), "plain" for icons that need no special font. Default: "plain".
+     */
+    icons?: "nerd" | "plain";
+}
+export declare const DEFAULT_BRAND: {
+    readonly glyph: "●";
+    readonly colors: {
+        readonly primary: "#4F8EB3";
+        readonly primaryDark: "#3B6B87";
+        readonly plan: "#EAB65D";
+        readonly neutral: "#C9CCC9";
+    };
+    readonly surfaces: {
+        readonly panel: "#121212";
+        readonly element: "#1C1C1C";
+    };
+    readonly lightSurfaces: {
+        readonly panel: "#F0F0F0";
+        readonly element: "#E6E6E6";
+    };
+};
+export interface ResolvedBrand {
+    name?: string;
+    glyph: string;
+    tagline?: string;
+    art?: string[];
+    colors: BrandColors;
+    surfaces: BrandSurfaces;
+    lightSurfaces: BrandSurfaces;
+    icons?: "nerd" | "plain";
+    /** Changes whenever the brand does; part of render cache keys. */
+    version: number;
+}
+/** The brand in effect, with defaults filled in. Cheap: cached per change. */
+export declare function getBrand(): ResolvedBrand;
+/**
+ * Merge a brand onto the current one. Nested `colors`, `surfaces` and `lightSurfaces` merge key by key. Returns a
+ * function that restores the previous brand (used by tests and by packages that unload).
+ */
+export declare function setBrand(spec: BrandSpec): () => void;
+/** Forget any registered brand and go back to the defaults. */
+export declare function resetBrand(): void;

package/dist/chassis/brand.js

@@ -0,0 +1,79 @@
+/**
+ * Brand: the few things that make the TUI look like a particular product: the mark shown next to
+ * the version, the startup art and tagline, and the accent colours of the chrome.
+ *
+ * chassis ships a neutral default. A separate package layers its own identity on top by calling
+ * `registerBrand()` from client.ts:
+ *
+ *     import { registerBrand } from "pi-chassis/client";
+ *     export default function () {
+ *       registerBrand({ name: "Acme", glyph: "A", colors: { primary: "#E4572E" } });
+ *     }
+ *
+ * The brand is stored on globalThis (the same reason the widget registry is: pi loads every
+ * extension in its own module scope) and read while rendering, so load order does not matter and
+ * a later registration simply wins. Fields left out keep the defaults.
+ *
+ * This file has no imports, so client.ts can re-export it without loading anything else.
+ */
+export const DEFAULT_BRAND = {
+    glyph: "●",
+    colors: {
+        primary: "#4F8EB3",
+        primaryDark: "#3B6B87",
+        plan: "#EAB65D",
+        neutral: "#C9CCC9",
+    },
+    surfaces: {
+        panel: "#121212",
+        element: "#1C1C1C",
+    },
+    lightSurfaces: {
+        panel: "#F0F0F0",
+        element: "#E6E6E6",
+    },
+};
+const KEY = Symbol.for("pi-chassis/brand");
+function slot() {
+    const g = globalThis;
+    g[KEY] ??= { spec: {}, version: 0 };
+    return g[KEY];
+}
+/** The brand in effect, with defaults filled in. Cheap: cached per change. */
+export function getBrand() {
+    const s = slot();
+    if (s.resolved?.version === s.version)
+        return s.resolved;
+    s.resolved = {
+        name: s.spec.name,
+        glyph: s.spec.glyph || DEFAULT_BRAND.glyph,
+        tagline: s.spec.tagline,
+        art: s.spec.art?.length ? s.spec.art : undefined,
+        colors: { ...DEFAULT_BRAND.colors, ...s.spec.colors },
+        surfaces: { ...DEFAULT_BRAND.surfaces, ...s.spec.surfaces },
+        lightSurfaces: { ...DEFAULT_BRAND.lightSurfaces, ...s.spec.lightSurfaces },
+        icons: s.spec.icons,
+        version: s.version,
+    };
+    return s.resolved;
+}
+/**
+ * Merge a brand onto the current one. Nested `colors`, `surfaces` and `lightSurfaces` merge key by key. Returns a
+ * function that restores the previous brand (used by tests and by packages that unload).
+ */
+export function setBrand(spec) {
+    const s = slot();
+    const before = s.spec;
+    s.spec = { ...before, ...spec, colors: { ...before.colors, ...spec.colors }, surfaces: { ...before.surfaces, ...spec.surfaces }, lightSurfaces: { ...before.lightSurfaces, ...spec.lightSurfaces } };
+    s.version++;
+    return () => {
+        s.spec = before;
+        s.version++;
+    };
+}
+/** Forget any registered brand and go back to the defaults. */
+export function resetBrand() {
+    const s = slot();
+    s.spec = {};
+    s.version++;
+}

package/dist/chassis/client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Widget client: the entry point for widgets that live in other extensions or packages.
+ *
+ *     import { registerWidget } from "pi-chassis/client";
+ *
+ *     registerWidget(pi, { id: "git", render: () => ({ text: "main ●2" }) });
+ *
+ * Same spec and handle as api.ts, but it never loads the registry code: it only looks for the
+ * host on globalThis (the Symbol.for keys below), so it works whichever extension loads first
+ * and it works without chassis installed:
+ *
+ * - chassis already loaded: the widget is registered with it straight away.
+ * - chassis loads later: the widget is queued and chassis registers it when it loads.
+ * - chassis is not installed (checked at session_start, when every extension has loaded): the
+ *   widget falls back to ctx.ui.setStatus(id, "<label> <text>"), updated on `refreshMs`. Only
+ *   the one-line view is shown there: no detail lines, colours or caching.
+ *
+ * Import it as "pi-chassis/client" (the package's `exports` map), which resolves to compiled
+ * JavaScript with type declarations (dist/), so a consumer's plain Node tests and tsc need no
+ * TypeScript loader. pi itself loads this package's extensions from the .ts sources. It loads
+ * two value modules, `./brand.ts` and `./provider.ts`, and `../diff/host.ts` for the diff view API,
+ * and the rest of what it imports is types. To vendor it, copy those four files and keep the
+ * `chassis/` and `diff/` folder layout, or import it from the package instead. Any one of the
+ * three missing fails the load. Those modules import only types themselves, so they add no
+ * further files.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ToolRowsOptions, ToolRowSpecs, WidgetHandle, WidgetSpec } from "./api.ts";
+import { type BrandSpec } from "./brand.ts";
+import { type ProviderStatusSpec } from "./provider.ts";
+/** The registry API version this client was written for. */
+export declare const CLIENT_API_VERSION = 1;
+/** The tool row API version this client was written for (`toolRowsVersion` on the registry). */
+export declare const CLIENT_TOOL_ROWS_VERSION = 1;
+/**
+ * Register (or replace) a widget with chassis if present, else show it as a plain status.
+ *
+ * Call it from the extension's default export. If you call it from inside a `session_start`
+ * handler instead (to be sure every extension has loaded), pass that handler's `ctx`: the widget
+ * missed that session's `session_start` event, and `ctx` lets chassis run its first `update` and
+ * start its timer now. A call made there when chassis is not installed shows nothing.
+ */
+export declare function registerWidget(pi: ExtensionAPI, spec: WidgetSpec, ctx?: ExtensionContext): WidgetHandle;
+/**
+ * Draw the rows of tools that belong to your extension the way chassis draws its built-in tool rows:
+ * one line per call, an icon, a title, a short description and a right-aligned outcome, with an
+ * expanded view on ctrl+o. Keyed by tool name. Returns a function that removes the rows again.
+ *
+ *     registerToolRows({
+ *       deploy_status: {
+ *         icon: { nerd: "\u{F0AD}", plain: "#" },
+ *         title: "Deploy",
+ *         describe: (args, _cwd, theme) => theme.fg("muted", String(args.env)),
+ *         summarize: (result) => String(result.details?.state ?? "done"),
+ *       },
+ *     });
+ *
+ * It works whichever package loads first (rows registered before chassis loads are queued and taken
+ * over when it does) and does nothing when chassis is not installed: the tools keep their own rows.
+ * chassis draws the built-in tools (read, write, edit, bash, grep, find, ls) itself and ignores a spec
+ * for those names. See ToolRowSpec in api.ts for what a spec may return.
+ *
+ * Pass `{ id }` if this can run more than once in a process (on every session_start, or after
+ * /reload): registering again with the same id replaces the earlier rows instead of adding more.
+ * Without an id, call the returned function (on session_shutdown, say) before registering again.
+ */
+export declare function registerToolRows(specs: ToolRowSpecs, options?: ToolRowsOptions): () => void;
+/**
+ * Layer a brand (name, glyph, tagline, startup art, colours) on top of chassis. Call it from an
+ * extension's default export; it works whichever package loads first, and chassis repaints. The
+ * returned function restores the previous brand. See brand.ts for the fields.
+ */
+export declare function registerBrand(spec: BrandSpec): () => void;
+/**
+ * Add a provider's own facts (a plan or quota bar, a display name, a glyph colour) to the sidebar's
+ * provider section and the footer. See provider.ts. The returned function removes it.
+ */
+export declare function registerProviderStatus(spec: ProviderStatusSpec): () => void;
+/** Ask chassis to repaint now (no-op when it isn't loaded). For state a widget changes outside `update`. */
+export declare function requestRender(): void;
+export { addDiffAction, openChanges, openDiff } from "../diff/host.ts";
+export type { DiffAction, DiffActionContext, DiffFileInfo, DiffHunkInfo, OpenDiffRequest } from "../diff/types.ts";
+export type { ProviderMeter, ProviderStatusSpec } from "./provider.ts";
+export type { BrandColors, BrandSpec, BrandSurfaces } from "./brand.ts";
+export type { IconLike } from "./icons.ts";
+export type { ToolRowResult, ToolRowsOptions, ToolRowSpec, ToolRowSpecs } from "./api.ts";
+export type { DetailLine, DetailLink, WidgetAction, WidgetHandle, WidgetSpec, WidgetView, WidgetRenderContext, WidgetSlot, WidgetColor, WidgetLevel } from "./api.ts";