pi-editor-footer 0.1.0

package/docs/specs/05-footer.md

@@ -0,0 +1,30 @@
+# Spec 05 — Footer Wireframe & Segments
+
+Ticket: #10 · Type: grilling · Branch: `feat/footer`
+
+## Question
+
+What is the footer's wireframe: which segments, how they respond to width, and where cost lives?
+
+## Decision
+
+- Segments (priority low→high, high survives): `cwd` (if not in header), `gitBranch`, `gitStatus`, `runtime`, `context`, `tokens`, `cost`, `extensionStatuses`. `sessionName` optional.
+- Each segment: `{text, compactText?, truncate?, priority}` consumed by `fitSegmentsByPriority`.
+- Placement: `setWidget("theme-footer", ..., {placement:"belowEditor"})`, always on.
+- Responsive: `fitSegmentsByPriority(maxWidth)` — compact forms first, then drop lowest priority.
+- Cost duplication: cost shown in **bottom-border telemetry** (rate) and optionally footer (total) — footer shows `fmtTokens` + extension status; border shows telemetry cost rate. Footer may omit cost if telemetry enabled (decide in impl).
+- Refresh: git + runtime polled on `session_start` and interval; footer re-renders on `requestRender`.
+- Theme: live `Theme`, glyphs via `icons.mode`.
+
+## Reference
+
+- `tmp/pi-open-tui/extensions/open-tui/footer.ts` (300+ lines)
+- `tmp/pi-open-tui/extensions/open-tui/utils.ts` (`fitSegmentsByPriority`, `truncatePath`, `fmtTokens`, `formatDuration`)
+- `tmp/pi-open-tui/extensions/open-tui/state.ts`
+
+## Acceptance
+
+- [ ] `src/footer.ts` with segment priorities and `fitSegmentsByPriority` integration
+- [ ] Reads `config.footerSegments`, respects theme + icon mode
+- [ ] Narrow width sheds gracefully (snapshot test)
+- [ ] `npm run typecheck` + `npm test` pass

package/docs/specs/06-git.md

@@ -0,0 +1,36 @@
+# Spec 06 — Git State Engine
+
+Ticket: #13 · Type: task (AFK) · Branch: `feat/git` (or part of `feat/footer`) · Blocked by #10
+
+## Question
+
+Which rich git states does the footer's git segment surface, and how are they computed?
+
+## Decision
+
+Rebuild `tmp/pi-open-tui/extensions/open-tui/git.ts` bespoke. Expose:
+
+```ts
+interface GitStatus {
+  branch: string | null;
+  commit: { oid: string; tag: string | null; detached: boolean } | null;
+  ahead: number; behind: number;
+  staged: number; modified: number; untracked: number;
+  conflicted: number; stashed: number;
+}
+function readGitStatus(cwd: string): Promise<GitStatus>
+function emptyGitStatus(): GitStatus
+```
+
+- Detection via `git` CLI (`git rev-parse`, `git status --porcelain`, `git rev-list --left-right`, stash list). No `isomorphic-git` dep.
+- Handles detached HEAD (show short oid + tag), ahead/behind, staged/modified/untracked, stashed.
+- Cached + debounced (don't spawn git on every render; refresh on interval + on demand from footer).
+- Theme glyphs for each status via `icons.ts` (`resolveGlyphs`).
+
+Blocked by footer wireframe (git segment shape). AFK.
+
+## Acceptance
+
+- [ ] `src/git.ts` with `readGitStatus` + tests (mock git)
+- [ ] Footer consumes it via `FooterState.git`
+- [ ] `npm run typecheck` + `npm test` pass

package/docs/specs/07-runtime.md

@@ -0,0 +1,28 @@
+# Spec 07 — Runtime Detection
+
+Ticket: #14 · Type: task (AFK) · Branch: `feat/runtime` (or part of `feat/footer`) · Blocked by #10
+
+## Question
+
+What is the runtime-signature catalog the footer's runtime segment recognises?
+
+## Decision
+
+Rebuild `tmp/pi-open-tui/extensions/open-tui/runtime.ts` bespoke.
+
+```ts
+interface RuntimeInfo { name: string; version?: string; icon: string }
+function readRuntimeInfo(cwd: string): Promise<RuntimeInfo | null>
+```
+
+- Catalog: at least 10 common runtimes (node, python, rust, go, ruby, java, deno, bun, etc.) detected via lockfiles/config presence (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `Gemfile`, etc.) — subset of 50+ is acceptable for v1, expand later.
+- Priority order: explicit lockfile > version file (`.nvmrc`, `.python-version`) > generic.
+- Glyph via `icons.ts` / `runtimeSymbol` helper, respects `icons.mode`.
+
+Blocked by footer wireframe. AFK.
+
+## Acceptance
+
+- [ ] `src/runtime.ts` + unit tests (fixture dirs)
+- [ ] Footer consumes via `FooterState.runtime`
+- [ ] `npm run typecheck` + `npm test` pass

package/docs/specs/theme-overview.md

@@ -0,0 +1,116 @@
+# Spec: pi-skill-desc → Full pi TUI Theme
+
+**Status:** draft  
+**Branch:** `dev/theme-refactor`  
+**Reference:** `tmp/pi-open-tui` (mirror, rebuild bespoke — never vendored)  
+**Map:** #5
+
+## 1. Destination
+
+Turn `pi-skill-desc` (detail window above input, TrackingEditor, model-info border glow) into a **full TUI theme** — rebuilt bespoke on `TrackingEditor`'s architecture. Reaching the end: a renamed theme whose
+
+- header (cwd + slash hints, no model/thinking),
+- responsive footer (git, 50+ runtime, context, tokens, cost, extension status),
+- editor cursor styles (block/bar/underline),
+- live telemetry right-aligned on the input's **bottom** border (all six toggleable)
+
+all render against **pi's live theme**, while
+
+- skill-description detail window (cap 5 lines, scrollable)
+- model-info border glow on the **top** border
+- single editor slot ownership
+
+are preserved, and `workspaceDisplay: "path" | "name"` is honoured.
+
+All visuals must respect pi's live `Theme` (read via `ctx.ui.theme` / `getFgAnsi`, `getThinkingBorderColor`, `fg`, etc.). No hardcoded colors.
+
+## 2. Standing Decisions (R1/R2)
+
+| Decision | Choice |
+| --- | --- |
+| Theme scope | **Full theme** (header+footer+project awareness) |
+| Build method | **Rebuild bespoke**, `tmp/pi-open-tui` as reference only |
+| Header model display | **Omit model/thinking** — border owns it |
+| Footer richness | **Wholesale** — git + 50+ runtime + all segments |
+| Border layout | **Model glow top, telemetry right bottom** |
+| Settings surface | **Lightweight English dialog** (`/theme` or `/open-tui` equivalent) |
+| Workspace toggle | `workspaceDisplay: "path" | "name"` config flag |
+| Identity | **Rename** package + display name to read as theme |
+| Execution | **Carry into map** — each ticket delivers working subsystem |
+
+## 3. Non-Goals / Out of Scope
+
+- Full bilingual (EN/ZH) settings — English only.
+- Vendoring `pi-open-tui` code.
+- Replacing pi's native header/footer vs augmenting (theme adds its own).
+
+## 4. Architecture
+
+### 4.1 Editor Slot
+
+`TrackingEditor extends Editor` owns `setEditorComponent`. It replicates `CustomEditor` inline (handleInput, actionHandlers, duck-typing). All editor features fold into it:
+
+- highlight observation (`autocompleteList` + `applyAutocompleteSuggestions` patch)
+- model-info glow (`applyModelInfo` on top border)
+- telemetry segment on bottom border (right-aligned)
+- cursor styles (bar `\x1b[6 q`, underline `\x1b[4 q`, hardware cursor)
+
+See `docs/reference/pi-tui-internals.md`, ADRs 0001/0002.
+
+### 4.2 Widgets
+
+- **Detail window** — `setWidget("pi-skill-desc", ..., {placement:"aboveEditor"})` — preserved.
+- **Header** — `setWidget("theme-header", ..., {placement:"aboveEditor"})` or TUI header slot if available; always on.
+- **Footer** — `setWidget("theme-footer", ..., {placement:"belowEditor"})`; responsive, priority-based shedding.
+
+Header and detail window both use `aboveEditor` — they must not overlap. Header is always visible; detail window appears only with popup. Header sits above detail window (or detail window pushes header).
+
+### 4.3 Config
+
+Single JSON file `~/.pi/agent/pi-skill-desc.json` or `~/.pi/agent/theme.json` (decided in config ticket). Shape:
+
+```ts
+interface ThemeConfig {
+  enabled: boolean
+  workspaceDisplay: "path" | "name"
+  cursorStyle: "block" | "bar" | "underline"
+  icons: { mode: "auto" | "nerd" | "ascii" }
+  telemetry: { enabled: boolean; tps: boolean; ttft: boolean; duration: boolean; tokens: boolean; stalls: boolean; cost: boolean }
+  footerSegments: { cwd: boolean; sessionName: boolean; gitBranch: boolean; gitStatus: boolean; gitCommit: boolean; runtime: boolean; context: boolean; tokens: boolean; cost: boolean; extensionStatuses: boolean }
+  // + fullscreen wheel etc. deferred to fog
+}
+```
+
+Defaults match `tmp/pi-open-tui`'s DEFAULT_CONFIG where applicable. Live reload on settings dialog save, re-render requested.
+
+### 4.4 Theme Respect
+
+Every new surface reads live theme:
+
+- `theme.fg("accent" | "dim" | "border" | "text" | ...)`
+- `theme.getThinkingBorderColor(level)` for glow
+- Icons via glyphs resolved by `icons.mode`
+
+No hardcoded ANSI except cursor sequences (not themed).
+
+## 5. Subsystems & Tickets
+
+| # | Ticket | Spec File |
+| --- | --- | --- |
+| 6 | Theme identity & rename | `02-identity.md` |
+| 7 | Config schema & persistence | `01-config.md` |
+| 8 | Editor border: model-label + telemetry layout | `03-border.md` |
+| 9 | Header: cwd + hints (no model) | `04-header.md` |
+| 10 | Footer wireframe & segments | `05-footer.md` |
+| 11 | Cursor styles in TrackingEditor | `02-editor-cursor.md` |
+| 12 | Telemetry engine | `03-telemetry.md` |
+| 13 | Git state engine | `06-git.md` |
+| 14 | Runtime detection | `07-runtime.md` |
+
+Each spec file defines acceptance criteria sized to one PR.
+
+## 6. Verification
+
+- `npm run typecheck` passes
+- `npm test` passes (new pure modules unit-tested via `node:test` + `tsx`)
+- Manual live pi session: theme loads via `pi -e ./src/index.ts`, header/footer render, detail window tracks, border shows model top + telemetry bottom right, cursor style toggles, workspaceDisplay toggles.

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "pi-editor-footer",
+  "type": "module",
+  "description": "Pi TUI theme — project-aware footer, model border, and skill detail window (TrackingEditor, live theme)",
+  "scripts": {
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-tui": "0.84.2",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "version": "0.1.0"
+}

package/src/config.ts

@@ -0,0 +1,184 @@
+/** Typed config for pi-skill-desc theme (admission boundary: validate once). */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type WorkspaceDisplay = "path" | "name";
+export type CursorStyle = "block" | "bar" | "underline";
+export type IconMode = "auto" | "nerd" | "ascii";
+
+export interface TelemetryConfig {
+  enabled: boolean;
+  tps: boolean;
+  ttft: boolean;
+  duration: boolean;
+  tokens: boolean;
+  stalls: boolean;
+  cost: boolean;
+}
+
+export interface FooterSegments {
+  cwd: boolean;
+  sessionName: boolean;
+  gitBranch: boolean;
+  gitStatus: boolean;
+  gitCommit: boolean;
+  runtime: boolean;
+  context: boolean;
+  tokens: boolean;
+  cost: boolean;
+  extensionStatuses: boolean;
+}
+
+export interface ThemeConfig {
+  enabled: boolean;
+  workspaceDisplay: WorkspaceDisplay;
+  cursorStyle: CursorStyle;
+  icons: {
+    mode: IconMode;
+  };
+  telemetry: TelemetryConfig;
+  footerSegments: FooterSegments;
+}
+
+export const DEFAULT_CONFIG: ThemeConfig = {
+  enabled: true,
+  workspaceDisplay: "path",
+  cursorStyle: "block",
+  icons: {
+    mode: "auto",
+  },
+  footerSegments: {
+    cwd: true,
+    sessionName: false,
+    gitBranch: true,
+    gitStatus: true,
+    gitCommit: false,
+    runtime: true,
+    context: true,
+    tokens: true,
+    cost: true,
+    extensionStatuses: true,
+  },
+  telemetry: {
+    enabled: true,
+    tps: true,
+    ttft: true,
+    duration: true,
+    tokens: true,
+    stalls: true,
+    cost: true,
+  },
+};
+
+export function getConfigPath(): string {
+  const home = homedir();
+  return join(home, ".pi", "agent", "pi-skill-desc.json");
+}
+
+function deepMerge<T>(base: T, override: unknown): T {
+  if (typeof base !== "object" || base === null || Array.isArray(base)) {
+    return (override as T) ?? base;
+  }
+  if (
+    typeof override !== "object" ||
+    override === null ||
+    Array.isArray(override)
+  ) {
+    return base;
+  }
+  const result = { ...(base as Record<string, unknown>) };
+  const rec = override as Record<string, unknown>;
+  for (const key of Object.keys(rec)) {
+    const bv = (base as Record<string, unknown>)[key];
+    const ov = rec[key];
+    if (
+      typeof bv === "object" &&
+      bv !== null &&
+      !Array.isArray(bv) &&
+      typeof ov === "object" &&
+      ov !== null &&
+      !Array.isArray(ov)
+    ) {
+      result[key] = deepMerge(bv, ov);
+    } else if (ov !== undefined) {
+      result[key] = ov;
+    }
+  }
+  return result as T;
+}
+
+function validate(config: ThemeConfig): ThemeConfig {
+  // workspaceDisplay
+  if (
+    config.workspaceDisplay !== "path" &&
+    config.workspaceDisplay !== "name"
+  ) {
+    config.workspaceDisplay = DEFAULT_CONFIG.workspaceDisplay;
+  }
+  // cursorStyle
+  if (
+    config.cursorStyle !== "block" &&
+    config.cursorStyle !== "bar" &&
+    config.cursorStyle !== "underline"
+  ) {
+    config.cursorStyle = DEFAULT_CONFIG.cursorStyle;
+  }
+  // icons.mode
+  if (
+    config.icons.mode !== "auto" &&
+    config.icons.mode !== "nerd" &&
+    config.icons.mode !== "ascii"
+  ) {
+    config.icons.mode = DEFAULT_CONFIG.icons.mode;
+  }
+  return config;
+}
+
+export function ensureConfigExists(): void {
+  const path = getConfigPath();
+  if (existsSync(path)) return;
+  try {
+    const dir = join(path, "..");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n", "utf8");
+  } catch {
+    // best-effort
+  }
+}
+
+export function loadConfig(): ThemeConfig {
+  const path = getConfigPath();
+  if (!existsSync(path)) {
+    ensureConfigExists();
+    return structuredClone(DEFAULT_CONFIG);
+  }
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    const merged = deepMerge(structuredClone(DEFAULT_CONFIG), parsed);
+    return validate(merged);
+  } catch (err) {
+    console.warn(
+      `[pi-skill-desc] config parse error (${path}): ${err instanceof Error ? err.message : String(err)} — using defaults`,
+    );
+    return structuredClone(DEFAULT_CONFIG);
+  }
+}
+
+export function saveConfig(
+  patch: Partial<ThemeConfig> & Record<string, unknown>,
+): ThemeConfig {
+  const current = loadConfig();
+  const merged = validate(deepMerge(current, patch) as ThemeConfig);
+  const path = getConfigPath();
+  try {
+    const dir = join(path, "..");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  } catch {
+    // best-effort
+  }
+  return merged;
+}

package/src/detail-render.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure, TUI-free rendering of the Detail window (ADR-0001).
+ *
+ * Given a highlighted completion candidate and window state, produces the
+ * lines to render in the 5-line detail window above the input box.
+ * No pi imports — this is the single testable seam of the extension.
+ */
+
+export interface DetailItem {
+	label: string;
+	kind: string;
+	description: string;
+}
+
+/**
+ * Rendered lines for the detail window: `[header, ...contentLines]`.
+ *
+ * - Returns `[]` when `item` is null or its description is empty/whitespace.
+ * - Header is `<label> · <kind>`, suffixed with a ` offset/total` scroll
+ *   marker (e.g. ` 3/8`) when the description overflows the window.
+ * - The description is wrapped to `width` characters per line (simple
+ *   character-based wrap; embedded newlines become paragraph breaks).
+ * - Shrink-to-fit: exactly `min(maxLines, 1 + contentLines)` lines are
+ *   returned (1 header + up to `maxLines - 1` content lines).
+ * - `scrollOffset` is clamped into `[0, max(0, contentLines - (maxLines - 1))]`.
+ */
+export function renderDetail(
+	item: DetailItem | null,
+	width: number,
+	maxLines: number,
+	scrollOffset: number,
+): string[] {
+	if (!item || item.description.trim() === "") {
+		return [];
+	}
+
+	const wrapWidth = Math.max(1, Math.floor(width));
+	const safeMax = Math.max(1, Math.floor(maxLines));
+
+	const contentLines = wrapDescription(item.description, wrapWidth);
+	const capacity = Math.max(0, safeMax - 1);
+	const maxOffset =
+		capacity === 0 ? 0 : Math.max(0, contentLines.length - capacity);
+	const offset = clamp(Math.floor(scrollOffset) || 0, 0, maxOffset);
+
+	const visibleLines = contentLines.slice(offset, offset + capacity);
+
+	// "More content" marker: `...` replaces the last visible content line when
+	// there is content remaining BELOW the window (not yet scrolled to the
+	// bottom). The header's ` offset/total` marker still carries the totals.
+	const hasMoreBelow = offset + visibleLines.length < contentLines.length;
+	if (hasMoreBelow && visibleLines.length > 0) {
+		visibleLines[visibleLines.length - 1] = "...";
+	}
+	const overflows = contentLines.length > capacity;
+	const namePart = `${item.label} · ${item.kind}`;
+	let header: string;
+	if (overflows) {
+		// Reserve room for the scroll marker so it always survives truncation.
+		const marker = ` ${offset + 1}/${contentLines.length}`;
+		const nameWidth = Math.max(0, wrapWidth - marker.length);
+		header = truncateToWidth(namePart, nameWidth) + marker;
+	} else {
+		header = truncateToWidth(namePart, wrapWidth);
+	}
+
+	return [header, ...visibleLines];
+}
+
+/**
+ * Next scroll offset after moving by `delta` (-1 = back/up, +1 = forward/down).
+ *
+ * - Returns 0 when there is nothing to scroll (description fits the window).
+ * - Otherwise returns `offset + delta`, clamped to
+ *   `[0, contentLines - (maxLines - 1)]`.
+ */
+export function scroll(
+	offset: number,
+	delta: -1 | 1,
+	contentLines: number,
+	maxLines: number,
+): number {
+	const capacity = Math.max(0, maxLines - 1);
+	if (capacity === 0) {
+		return 0;
+	}
+	const maxOffset = Math.max(0, contentLines - capacity);
+	if (maxOffset === 0) {
+		return 0;
+	}
+	return clamp(Math.floor(offset) + delta, 0, maxOffset);
+}
+
+function wrapDescription(description: string, width: number): string[] {
+	const lines: string[] = [];
+	for (const rawLine of description.split("\n")) {
+		const trimmed = rawLine.replace(/\s+$/g, "");
+		if (trimmed === "") {
+			// Preserve explicit paragraph breaks (empty lines in the description).
+			lines.push("");
+			continue;
+		}
+		for (let i = 0; i < trimmed.length; i += width) {
+			const segment = trimmed.slice(i, i + width).replace(/\s+$/g, "");
+			if (segment !== "") {
+				lines.push(segment);
+			}
+		}
+	}
+	return lines;
+}
+
+function truncateToWidth(text: string, width: number): string {
+	return text.length <= width ? text : text.slice(0, width);
+}
+
+function clamp(value: number, min: number, max: number): number {
+	return Math.max(min, Math.min(max, value));
+}