@zenodinh/pi-render 0.0.0-stage → 0.1.0

package/src/core/settings.ts

@@ -0,0 +1,119 @@
+// ported from pi-pretty-tui/src/core/state.ts — survives because: its tmp+rename write and its
+// fill-defaults read are exactly the mechanics that keep one document uncorrupted and cheap to read.
+
+/**
+ * The one persisted settings document (SA §3), at `~/.pi/agent/pi-render/settings.json`.
+ *
+ * Why cached: the predecessor re-read its document inside the render path (P render.ts:62), so every
+ * row paid a disk read. Here only the first load reads; save() refreshes the cache.
+ *
+ * Why tmp+rename: a reader opening the final path mid-write must see the old document or the new one
+ * complete — never a torn file.
+ *
+ * shape: closure returning an object literal — trigger #4, this module's one runtime unit is
+ * createSettingsStore(): a cached document plus two methods, so no class, subclassing, or instanceof.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Logger, ModuleSettings, SettingsDoc, SettingsStore } from "./types.ts";
+
+const DOC_VERSION = 1;
+
+/** Stands in when no logger is injected, so every factory call needs no logger guard. */
+const NOOP_LOGGER: Logger = {
+	logLine: () => {},
+	logOnce: () => {},
+	drain: () => [],
+};
+
+/** shape: none — one env lookup; PI_CODING_AGENT_DIR mirrors how the host resolves its agent dir. */
+function defaultSettingsPath(): string {
+	const agentDir = process.env.PI_CODING_AGENT_DIR || join(process.env.HOME ?? "", ".pi/agent");
+	return join(agentDir, "pi-render", "settings.json");
+}
+
+/** shape: none — one type predicate over untrusted JSON. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** shape: none — one code check on an unknown catch value. */
+function isEnoent(error: unknown): boolean {
+	return isRecord(error) && error.code === "ENOENT";
+}
+
+/** shape: none — one field shape per key; a bad entry reads as the module's defaults. */
+function normalizeModule(entry: unknown): ModuleSettings {
+	if (!isRecord(entry)) return { enabled: true };
+	const enabled = typeof entry.enabled === "boolean" ? entry.enabled : true;
+	return isRecord(entry.settings) ? { enabled, settings: entry.settings } : { enabled };
+}
+
+/** shape: none — one field shape per key; a schema library does not earn a dependency for two keys. */
+function normalize(raw: Record<string, unknown>): SettingsDoc {
+	const version = typeof raw.version === "number" ? raw.version : DOC_VERSION;
+	const source = isRecord(raw.modules) ? raw.modules : {};
+	// Object.fromEntries writes own data properties, so a "__proto__" key cannot set the prototype.
+	const modules = Object.fromEntries(
+		Object.entries(source).map(([key, entry]): [string, ModuleSettings] => [key, normalizeModule(entry)]),
+	);
+	return { version, modules };
+}
+
+/**
+ * Cached load plus atomic save. `path` and `logger` are injectable so tests never touch the real
+ * agent directory and can read the malformed-doc line back.
+ */
+export function createSettingsStore(opts?: { path?: string; logger?: Logger }): SettingsStore {
+	const path = opts?.path ?? defaultSettingsPath();
+	const logger = opts?.logger ?? NOOP_LOGGER;
+	let cache: SettingsDoc | undefined;
+
+	const defaults = (): SettingsDoc => ({ version: DOC_VERSION, modules: {} });
+
+	const malformed = (why: string): SettingsDoc => {
+		logger.logOnce(`settings:${path}`, "settings", `${why} at ${path} — using defaults`);
+		return defaults();
+	};
+
+	const readFromDisk = (): SettingsDoc => {
+		let text: string;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch (error) {
+			// A missing file is the normal first run, not a fault worth a line.
+			return isEnoent(error) ? defaults() : malformed("settings unreadable");
+		}
+		let raw: unknown;
+		try {
+			raw = JSON.parse(text);
+		} catch {
+			return malformed("settings malformed");
+		}
+		if (!isRecord(raw)) return malformed("settings malformed");
+		if (raw.modules !== undefined && !isRecord(raw.modules)) return malformed("settings malformed");
+		return normalize(raw);
+	};
+
+	return {
+		load(): SettingsDoc {
+			const current = cache ?? readFromDisk();
+			cache = current;
+			return current;
+		},
+
+		save(doc: SettingsDoc): void {
+			try {
+				mkdirSync(dirname(path), { recursive: true });
+				const temporary = `${path}.tmp`;
+				writeFileSync(temporary, `${JSON.stringify(doc, null, 2)}\n`);
+				renameSync(temporary, path);
+			} catch {
+				// A write failure degrades to in-memory: the panel keeps working, the disk stays old.
+				logger.logOnce(`settings:save:${path}`, "settings", `settings write failed at ${path} — kept in memory`);
+			}
+			cache = doc;
+		},
+	};
+}

package/src/core/types/code-theme.ts

@@ -0,0 +1,24 @@
+/**
+ * code-theme.ts — the highlighting contract core/code-theme (T-10) implements.
+ *
+ * Boundary: the highlighter is injected — the shiki adapter in production, a counting double in
+ * tests — so no renderer imports shiki and no test needs the wasm engine.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+/** The injectable highlighter: code plus a language id in, one escape-wrapped line per array entry out. */
+export type HighlightEngine = (
+	/** Source text to highlight; may be multi-line. Required. */
+	code: string,
+	/** Language id, e.g. "ts" or "bash". Required. */
+	lang: string,
+) => string[];
+
+/** Cached highlighting: an oversize input and an engine failure both yield plain, uncoloured lines. */
+export interface CodeTheme {
+	/** Highlights one block, waiting for the engine. Required; never rejects — failures degrade. */
+	highlight(code: string, lang: string): Promise<string[]>;
+	/** Highlights one block from cache or synchronous engine. Required; the render-path entry. */
+	highlightSync(code: string, lang: string): string;
+}

package/src/core/types/host.ts

@@ -0,0 +1,160 @@
+/**
+ * host.ts — the host shapes pi-render reads, composes against, and registers through.
+ *
+ * Boundary: these are STRUCTURAL declarations of shapes the pi host also declares. No host
+ * package is imported here, so a plain object literal satisfies them and a unit test needs no pi
+ * runtime; the composition root (index.ts) passes the real host in as a parameter.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ *
+ * Ported from pi-pretty-tui/src/types.ts — survives because: host-verified structural shapes keep
+ * every renderer decoupled from a host import, so unit tests need no pi runtime. The predecessor's
+ * `*Like` suffix meant "structural declaration of the host shape"; that meaning lives in these docs.
+ */
+
+/** The host theme slice paint reads. Structural host shape: any object with these two members qualifies. */
+export interface HostTheme {
+	/** Maps a theme token and text to escape-wrapped text, e.g. fg("accent", "ok"). Required. */
+	fg(key: string, text: string): string;
+	/** Wraps text in the theme's bold escape sequence. Required. */
+	bold(text: string): string;
+}
+
+/** Live markdown-theme closures the content painter wraps. Structural host shape — no host import. */
+export interface MarkdownTheme {
+	/** Horizontal-rule escape wrapper. Optional: a host without this token degrades to plain text. */
+	hr?(text: string): string;
+	/** Blockquote body wrapper. Optional. */
+	quote?(text: string): string;
+	/** Blockquote left-border wrapper. Optional. */
+	quoteBorder?(text: string): string;
+	/** Inline-code wrapper. Optional. */
+	code?(text: string): string;
+	/** Fenced-code-block border wrapper. Optional. */
+	codeBlockBorder?(text: string): string;
+}
+
+/** The pi-tui component slice renderers return and receive. Structural host shape — no host import. */
+export interface UiComponent {
+	/** Draws the current frame as lines; `width` is the terminal width in columns. Required. */
+	render(width: number): string[];
+	/** Marks the cached frame stale so the next render() redraws. Required. */
+	invalidate(): void;
+	/** Replaces the component's text. Optional: base components the runtime delegates to do not have it. */
+	setText?(v: string): void;
+}
+
+/** The text-component slice the runtime reads back. Structural host shape — no host import. */
+export interface TextComponent {
+	/** Replaces the displayed text. Required. */
+	setText(v: string): void;
+	/** Reads the displayed text back. Optional: the host's own component may not expose it. */
+	getText?(): string;
+}
+
+/** What renderCall / renderResult receive. Structural host shape — no host import; a plain object is accepted. */
+export interface RenderContext {
+	/** ONE state bag per row, shared across that row's invocations; the parse-once memo lives here. Required. */
+	state: Record<string, unknown>;
+	/** Tool arguments as the host passes them; unreadable until argsComplete is true. Optional. */
+	args?: Record<string, unknown>;
+	/** Stable id of the tool call this row draws, used as the logOnce key. Optional. */
+	toolCallId?: string;
+	/** Asks the host to redraw this row, e.g. after an async decorate() resolved. Optional. */
+	invalidate?: () => void;
+	/** The component returned on the previous invocation of the same row. Optional. */
+	lastComponent?: UiComponent;
+	/** Working directory the tool ran in, when the host reports one. Optional. */
+	cwd?: string;
+	/** True once the host has delivered the full argument set — the gate for argument-dependent output. Optional. */
+	argsComplete?: boolean;
+	/** True while the row is drawn expanded (ctrl+o or click). Optional. */
+	expanded?: boolean;
+	/** True when the tool call failed; the row collapses to an error summary. Optional. */
+	isError?: boolean;
+	/** True while the result is still streaming; the row must stay cheap. Optional. */
+	isPartial?: boolean;
+}
+
+/** One result content block; only text blocks are rendered. Structural host shape. */
+export interface ToolResultContent {
+	/** Block kind as the host labels it, e.g. "text" or "image". Required. */
+	type: string;
+	/** The block's text; absent for non-text blocks. Optional. */
+	text?: string;
+}
+
+/** The result slice renderers read. Structural host shape — the shape is narrowed, never assumed. */
+export interface ToolResult {
+	/** Result blocks in host order. Optional: a result may carry details only. */
+	content?: ToolResultContent[];
+	/** Host-supplied structured payload; opaque here and never rendered directly. Optional. */
+	details?: unknown;
+	/** True when the tool call failed. Optional. */
+	isError?: boolean;
+}
+
+/** Renderer options exactly as the host passes them — one bag per render call, no defaults invented. */
+export interface RenderResultOptions {
+	/** True while the row is drawn expanded. Required. */
+	expanded: boolean;
+	/** True while the result is still streaming. Required. */
+	isPartial: boolean;
+}
+
+/** The renderer triple the resolver returns or delegates to; renderShell stays host-owned. */
+export interface ToolRenderers {
+	/** Asks the host for its own shell frame instead of drawing one. Optional: exactly "default" or "self". */
+	renderShell?: "default" | "self";
+	/** Draws the call line. Optional: omitting it delegates this row to the next resolver. */
+	renderCall?(args: Record<string, unknown>, theme: HostTheme, ctx: RenderContext): UiComponent;
+	/** Draws the result. Optional: omitting it delegates this row to the next resolver. */
+	renderResult?(result: ToolResult, options: RenderResultOptions, theme: HostTheme, ctx: RenderContext): UiComponent;
+}
+
+/** The host resolver chain signature. Structural host shape — the host calls it, pi-render returns it. */
+export type ToolRendererResolver = (
+	/** Name of the tool being rendered, exactly as the host spells it, e.g. "bash". Required. */
+	toolName: string,
+	/** Returns what the remaining chain would draw, or undefined when the chain is exhausted. Required. */
+	next: () => ToolRenderers | undefined,
+) => ToolRenderers | undefined;
+
+/** The host markdown-transform context slice surfaces read. Structural host shape — no host import. */
+export interface TransformContext {
+	/** Which transcript stream the text belongs to. Required: "user" | "assistant" | "assistant-thinking". */
+	messageType: "user" | "assistant" | "assistant-thinking";
+	/** True while the message is still streaming in; a streaming message is not rewritten. Required. */
+	isStreaming: boolean;
+	/** Columns available to the message, in the host's character-cell units. Required; > 0. */
+	availableWidth: number;
+}
+
+/** The command-handler context slice /canvas reads. Structural host shape — no host import. */
+export interface CommandContext {
+	/** Host output mode. Required: "tui" | "rpc" | "json" | "print". */
+	mode: "tui" | "rpc" | "json" | "print";
+	/** Host notification seam for user-facing feedback. Required. */
+	ui: {
+		/** Shows one message to the user, e.g. notify("Canvas closed"). Required. */
+		notify(message: string): void;
+	};
+}
+
+/**
+ * The host surface the extension registers through. Structural host shape: the host arrives as the
+ * composition root's parameter, never as a module import, so this file stays pi-free.
+ */
+export interface ExtensionApi {
+	/** Adds one resolver to the tool-render chain. Required; called exactly once, in index.ts. */
+	registerToolRenderer(resolver: ToolRendererResolver): void;
+	/** Adds one markdown rewrite stage. Required; called exactly once, in index.ts. */
+	registerMarkdownTransformer(transformer: (markdown: string, ctx: TransformContext) => string): void;
+	/** Registers one slash command, e.g. name "canvas". Required; one call per command. */
+	registerCommand(
+		name: string,
+		options: { description?: string; handler: (args: string, ctx: CommandContext) => Promise<void> },
+	): void;
+	/** Collapses every tool row to one line at boot. Required; the render-only default is false. */
+	setToolsExpanded(expanded: boolean): void;
+}

package/src/core/types/log.ts

@@ -0,0 +1,28 @@
+/**
+ * log.ts — the diagnostics contract core/log (T-06) implements.
+ *
+ * Boundary: renderers call these from a render path, so the contract forbids throwing and forbids
+ * writing to stdout/stderr — pi owns both for the TUI.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+/** One captured diagnostic entry: the memory record a test or the /render panel reads back. */
+export interface LogEntry {
+	/** Emitting module scope, e.g. "tool.bash". Required. */
+	scope: string;
+	/** One-line diagnostic text, never multi-line. Required. */
+	message: string;
+	/** Capture time in epoch milliseconds (Date.now()). Required. */
+	time: number;
+}
+
+/** Keyed in-memory diagnostics. Structural core shape: any object with these three methods qualifies. */
+export interface Logger {
+	/** Appends one entry. Required; repeats freely, so keep it off per-frame paths. */
+	logLine(scope: string, message: string): void;
+	/** Appends at most one entry per key, e.g. key "tool:call-42". Required — the per-frame default. */
+	logOnce(key: string, scope: string, message: string): void;
+	/** Returns every captured entry and empties the buffer. Required; tests and the panel consume this. */
+	drain(): LogEntry[];
+}

package/src/core/types/paint.ts

@@ -0,0 +1,54 @@
+/**
+ * paint.ts — the painting contract: the two role sets every renderer draws through.
+ *
+ * Boundary: region 1 is the tool row, region 2 is markdown content. Renderers call role methods
+ * and never emit an escape sequence themselves (AGENTS: escapes originate in core/paint.ts).
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+import type { HostTheme } from "./host.ts";
+
+/** Region 1 — the tool-row roles. Text in, theme-derived escape-wrapped text out. */
+export interface RowPaint {
+	/** The tool name or call title, e.g. title("bash"). Required. */
+	title(text: string): string;
+	/** Tool output / result text. Required. */
+	output(text: string): string;
+	/** De-emphasized metadata such as durations and counts. Required. */
+	muted(text: string): string;
+	/** Accent for the active or highlighted element. Required. */
+	accent(text: string): string;
+	/** Error text on a failed call. Required. */
+	error(text: string): string;
+	/** Warning text for a degraded or partial result. Required. */
+	warning(text: string): string;
+	/** The row's left gutter marker. Required. */
+	gutter(text: string): string;
+	/** A matched substring highlighted inside a result line. Required. */
+	match(text: string): string;
+	/** Diff line added (+), from the host toolDiffAdded token. Required. */
+	diffAdded(text: string): string;
+	/** Diff line removed (−), from the host toolDiffRemoved token. Required. */
+	diffRemoved(text: string): string;
+	/** Diff context line, from the host toolDiffContext token. Required. */
+	diffContext(text: string): string;
+}
+
+/** Region 1 factory: the theme arrives per render call and is read live, so a theme switch repaints. */
+export type RowPaintFactory = (
+	/** The host theme as delivered on this render call. Required. */
+	theme: HostTheme,
+) => RowPaint;
+
+/** Region 2 — the markdown-content roles. */
+export interface ContentPaint {
+	/** Horizontal rule; falls back hr → quoteBorder → plain rather than throw. Required. */
+	rule(text: string): string;
+	/** Blockquote body. Required. */
+	quote(text: string): string;
+	/** Inline code. Required. */
+	code(text: string): string;
+	/** Fenced-code-block border. Required. */
+	codeBlockBorder(text: string): string;
+}

package/src/core/types/registry.ts

@@ -0,0 +1,44 @@
+/**
+ * registry.ts — the module-registry contract core/registry (T-09) implements.
+ *
+ * Boundary: index.ts is the only registration site; renderers read the registry per invocation and
+ * never write it.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+/** One declared setting: the /render panel renders an editor from this spec. */
+export interface SettingSpec {
+	/** Setting name inside the module's slice, e.g. "collapseAt". Required; unique per module. */
+	name: string;
+	/** Editor kind. Required: "enum" | "toggle" | "number". */
+	kind: "enum" | "toggle" | "number";
+	/** Allowed values — required when kind is "enum", ignored otherwise. Optional. */
+	values?: string[];
+	/** Value used when the document omits the key. Required; must read as `unknown` before use. */
+	default: unknown;
+}
+
+/** One pluggable module's registration. Duplicate keys keep the first and log once. */
+export interface ModuleDescriptor {
+	/** Registry key, unique module id, e.g. "row.bash". Required. */
+	key: string;
+	/** Human-readable name shown in the /render panel, e.g. "Bash row". Required. */
+	name: string;
+	/** Initial enabled state before any settings write. Required. */
+	defaultEnabled: boolean;
+	/** Settings this module exposes. Required; use [] when it exposes none. */
+	settings: SettingSpec[];
+}
+
+/** Consumers poll per invocation; a settings write lands on the next read and pushes no redraw. */
+export interface Registry {
+	/** Declares one module. Required; a repeat key keeps the first definition. */
+	defineModule(d: ModuleDescriptor): void;
+	/** Reads a module's enabled flag by key, e.g. "row.bash". Required; an unknown key reads false. */
+	isEnabled(key: string): boolean;
+	/** Reads a module's effective settings (defaults merged with stored values). Required; unknown key = {}. */
+	getSettings(key: string): Record<string, unknown>;
+	/** Merges a patch into a module's stored settings. Required; takes effect on the next read, not now. */
+	setSettings(key: string, patch: object): void;
+}

package/src/core/types/settings.ts

@@ -0,0 +1,31 @@
+/**
+ * settings.ts — the persisted-settings contract core/settings (T-07) implements.
+ *
+ * Boundary: only the store touches the disk; a render path reads the cached document it returns.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+/** One module's persisted slice, e.g. { enabled: false, settings: { collapseAt: 3 } }. */
+export interface ModuleSettings {
+	/** Whether the module's row/surface is active. Required; a missing module key reads as enabled. */
+	enabled: boolean;
+	/** The module's own key/value bag, validated by the module that owns it. Optional; default {}. */
+	settings?: Record<string, unknown>;
+}
+
+/** The persisted document: one file for every module. A malformed value is replaced by all defaults. */
+export interface SettingsDoc {
+	/** Document schema revision, currently 1 — bumped by a migration, never by a module. Required. */
+	version: number;
+	/** Module slices keyed by registry key, e.g. "row.bash". Required; absent key = that module's defaults. */
+	modules: Record<string, ModuleSettings>;
+}
+
+/** Cached load plus atomic save. A render path never touches the disk after the first load. */
+export interface SettingsStore {
+	/** Returns the cached document, reading the file only on first call. Required. */
+	load(): SettingsDoc;
+	/** Writes the document atomically (temp file + rename). Required; a failure degrades to in-memory. */
+	save(doc: SettingsDoc): void;
+}

package/src/core/types.ts

@@ -0,0 +1,34 @@
+/**
+ * types.ts — the seam catalog barrel: every cross-lane contract, in one import path.
+ *
+ * Boundary: cross-lane contracts are declared per scope under `src/core/types/` and per lane under
+ * `src/renderers/{tool,content}/types.ts`; this file re-exports them so `core/types.ts` stays the
+ * stable import path every module and ticket names. Add a type to its scope file, never here.
+ * AC-2 scope: "a later ticket finds a missing interface" means a missing cross-lane interface in
+ * one of those files, never any interface a ticket happens to mention.
+ *
+ * shape: none — re-export barrel (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+export type { Surface, SurfaceKey } from "../renderers/content/types.ts";
+export type { CallModel, RowSpec, RowView } from "../renderers/tool/types.ts";
+export type { CodeTheme, HighlightEngine } from "./types/code-theme.ts";
+export type {
+	CommandContext,
+	ExtensionApi,
+	HostTheme,
+	MarkdownTheme,
+	RenderContext,
+	RenderResultOptions,
+	TextComponent,
+	ToolRendererResolver,
+	ToolRenderers,
+	ToolResult,
+	ToolResultContent,
+	TransformContext,
+	UiComponent,
+} from "./types/host.ts";
+export type { LogEntry, Logger } from "./types/log.ts";
+export type { ContentPaint, RowPaint, RowPaintFactory } from "./types/paint.ts";
+export type { ModuleDescriptor, Registry, SettingSpec } from "./types/registry.ts";
+export type { ModuleSettings, SettingsDoc, SettingsStore } from "./types/settings.ts";