@zhuxixi/pi-agent-board 0.5.0 → 0.5.2

package/docs/superpowers/plans/2026-08-30-circular-navigation.md

@@ -0,0 +1,308 @@
+# Circular List Navigation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make dashboard list arrow-key navigation wrap around (last ⇄ first) instead of clamping at boundaries.
+
+**Architecture:** Change index clamping to modulo wrap in `moveSelection()` and `peekStep()` in `src/ui/dashboard.ts`. Scroll-follow needs no change (`windowBody()` keeps the selected row visible regardless of direction). Behavior is covered by a new child-process test following the `ui-smoke` pattern.
+
+**Tech Stack:** Node 24 (`--experimental-transform-types`), node:test, TypeScript (parameter properties, no typecheck on test-support).
+
+**Spec:** `docs/superpowers/specs/2026-08-30-circular-navigation-design.md`
+
+## Global Constraints
+
+- Work only in the worktree: `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation` (all paths below are relative to it).
+- `npm test` = `node --test test/*.test.mjs`; `npm run typecheck` = `tsc --noEmit`. Both must stay green.
+- `src/ui/dashboard.ts` uses TS parameter properties → it can only be imported from a child process spawned with `--experimental-transform-types` (the `test-support/ui-smoke.ts` pattern). Never import it directly from `test/*.test.mjs`.
+- `tsconfig.json` excludes `test/` and `test-support/` — no type casts needed in the probe script.
+- Do NOT touch the launch dialog pickers (`dashboard.ts` L539-547) — out of scope for this issue.
+- Commit per task with conventional commits; `git add <file>` per file, never `git add -A`.
+- `cur < 0` fallback semantics: out-of-list `selectedId` uses base index 0 — ↓ yields index 1 (second row, same as before); ↑ wraps to the last row (**changed** from the old clamp's first row — intentional, wrap-consistent, and effectively unreachable since `refresh()` keeps `selectedId` ∈ `orderedIds`).
+
+---
+
+### Task 1: `moveSelection()` 取模回绕 + 行为测试
+
+**Files:**
+- Modify: `src/ui/dashboard.ts:250-258` (`moveSelection`)
+- Create: `test-support/navigation-wrap.ts` (probe script, prints JSON)
+- Create: `test/dashboard-navigation.test.mjs` (node:test wrapper)
+
+**Interfaces:**
+- Consumes: existing `createService` (`src/runtime/service.mjs`), `createView` (`src/core/store.mjs`), `DashboardComponent` (`src/ui/dashboard.ts`), public method `handleInput(data: string)`.
+- Produces: `test-support/navigation-wrap.ts` prints one JSON line `{ ids: string[], seq: (string|null)[] }`; Task 2 extends the same probe with a peek-mode segment (do not rewrite the file structure).
+
+- [ ] **Step 1: Worktree dependency setup**
+
+Worktree has no `node_modules`. Symlink from the main checkout (instant; postinstall patches already applied there):
+
+```bash
+WT=/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+ln -s /home/elling/git-repo/github/pi-agent-board/node_modules "$WT/node_modules"
+ls "$WT/node_modules/@mariozechner"  # sanity: pi-tui present
+```
+
+(Fallback if the symlink misbehaves: `cd "$WT" && npm ci`.)
+
+- [ ] **Step 2: Write the failing test probe**
+
+Create `test-support/navigation-wrap.ts`:
+
+```ts
+// Nav wrap probe: construct a dashboard with 3 views, drive arrow keys through
+// the public handleInput(), and report the selection sequence as JSON.
+// Run via `node --experimental-transform-types` (dashboard.ts uses TS
+// parameter properties). Not typechecked (tsconfig excludes test-support).
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createService } from "../src/runtime/service.mjs";
+import { createView } from "../src/core/store.mjs";
+import { DashboardComponent } from "../src/ui/dashboard.ts";
+
+const root = mkdtempSync(join(tmpdir(), "agentview-nav-wrap-"));
+createView(root, { id: "v1", name: "one", cwd: root });
+createView(root, { id: "v2", name: "two", cwd: root });
+createView(root, { id: "v3", name: "three", cwd: root });
+
+const service = createService({
+	root,
+	runnerScript: "/no/runner.mjs",
+	piCommand: "pi",
+	piArgsPrefix: [],
+	defaultCwd: root,
+	launch: () => ({ pid: null, configPath: "/no/config.json" }),
+	launchHost: () => ({ pid: null, configPath: "/no/host-config.json" }),
+	launchTitle: () => ({ pid: null, configPath: "/no/title-config.json" }),
+});
+
+const writes = [];
+const tui = {
+	terminal: { rows: 24, cols: 80, columns: 80, write: (d) => writes.push(d) },
+	requestRender: () => {},
+};
+const theme = { fg: (_c, t) => t, bold: (t) => t };
+
+const dash = new DashboardComponent(tui, theme, {}, () => {}, {
+	service,
+	root,
+	defaultCwd: root,
+	availableModels: [],
+	currentModel: null,
+	currentThinkingLevel: "off",
+});
+
+// TS-private is runtime-accessible; read white-box state for assertions.
+const ids = dash.orderedIds;
+const seq = [];
+seq.push(dash.selectedId); // initial selection = ids[0]
+dash.handleInput("\x1b[B"); // ↓ -> ids[1]
+seq.push(dash.selectedId);
+dash.handleInput("\x1b[B"); // ↓ -> ids[2]
+seq.push(dash.selectedId);
+dash.handleInput("\x1b[B"); // ↓ at last -> WRAP to ids[0]
+seq.push(dash.selectedId);
+dash.handleInput("\x1b[A"); // ↑ at first -> WRAP to ids[2]
+seq.push(dash.selectedId);
+
+dash.dispose();
+console.log(JSON.stringify({ ids, seq }));
+```
+
+- [ ] **Step 3: Write the failing test wrapper**
+
+Create `test/dashboard-navigation.test.mjs`:
+
+```js
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import test from "node:test";
+
+const ROOT_DIR = fileURLToPath(new URL("../", import.meta.url));
+const PROBE = join(ROOT_DIR, "test-support", "navigation-wrap.ts");
+
+test("list arrow-key navigation wraps around at both ends (issue #52)", () => {
+	// dashboard.ts uses TS parameter properties, which strip-only mode rejects;
+	// --experimental-transform-types handles them (Node 22.7+ / 24).
+	const out = execFileSync(process.execPath, ["--experimental-transform-types", PROBE], {
+		encoding: "utf8",
+		timeout: 30_000,
+	});
+	const { ids, seq } = JSON.parse(out);
+	assert.equal(ids.length, 3, "probe must see 3 rows");
+	assert.deepEqual(
+		seq,
+		[ids[0], ids[1], ids[2], ids[0], ids[2]],
+		"down past the last row wraps to first; up past the first wraps to last",
+	);
+});
+```
+
+- [ ] **Step 4: Run test to verify it fails**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+node --test test/dashboard-navigation.test.mjs
+```
+
+Expected: FAIL — `seq[3]` is `ids[2]` (clamped at last) instead of `ids[0]`, and `seq[4]` is `ids[0]` instead of `ids[2]`.
+
+If the probe itself crashes (e.g. key sequence mismatch), debug the probe first — `matchesKey(data, Key.up/down)` must match `\x1b[A` / `\x1b[B]`; verify against `@mariozechner/pi-tui` `Key` defaults if not.
+
+- [ ] **Step 5: Implement modulo wrap in `moveSelection()`**
+
+In `src/ui/dashboard.ts`, replace:
+
+```ts
+	private moveSelection(delta: number): void {
+		if (this.orderedIds.length === 0) return;
+		const cur = this.selectedId ? this.orderedIds.indexOf(this.selectedId) : 0;
+		const next = Math.max(0, Math.min(this.orderedIds.length - 1, (cur < 0 ? 0 : cur) + delta));
+```
+
+with:
+
+```ts
+	private moveSelection(delta: number): void {
+		if (this.orderedIds.length === 0) return;
+		const cur = this.selectedId ? this.orderedIds.indexOf(this.selectedId) : 0;
+		const len = this.orderedIds.length;
+		// Wrap around both ends: down past last -> first, up past first -> last.
+		const next = (((cur < 0 ? 0 : cur) + delta) % len + len) % len;
+```
+
+Everything below that line (`const nextId = ...` through the end of the method) stays unchanged — the `nextId === this.selectedId` early return keeps single-row lists a no-op.
+
+- [ ] **Step 6: Run test to verify it passes**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+node --test test/dashboard-navigation.test.mjs
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Full test suite + typecheck**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+npm test && npm run typecheck
+```
+
+Expected: all green.
+
+- [ ] **Step 8: Commit**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+git add src/ui/dashboard.ts test-support/navigation-wrap.ts test/dashboard-navigation.test.mjs
+git commit -m "fix: wrap list arrow-key navigation at both ends (issue #52)"
+```
+
+---
+
+### Task 2: `peekStep()` 取模回绕 + peek 段测试
+
+**Files:**
+- Modify: `src/ui/dashboard.ts:1094-1101` (`peekStep`)
+- Modify: `test-support/navigation-wrap.ts` (append peek segment)
+- Modify: `test/dashboard-navigation.test.mjs` (assert extended sequence)
+
+**Interfaces:**
+- Consumes: Task 1's probe file and test wrapper; `peekId` / `mode` are TS-private fields on `DashboardComponent`, runtime-accessible from the probe (same white-box pattern as `selectedId`).
+- Produces: probe JSON gains nothing new — `seq` grows by one entry (peek-mode wrap result); test asserts the 6-element sequence.
+
+- [ ] **Step 1: Extend the probe with a peek-mode segment (failing)**
+
+In `test-support/navigation-wrap.ts`, insert immediately BEFORE `dash.dispose();`:
+
+```ts
+// Peek mode: stepping down from the last row wraps to the first.
+dash.peekId = ids[2];
+dash.selectedId = ids[2];
+dash.mode = "peek";
+dash.handleInput("\x1b[B"); // ↓ at last in peek -> WRAP to ids[0]
+seq.push(dash.selectedId);
+```
+
+And in `test/dashboard-navigation.test.mjs`, replace the final assertion with:
+
+```js
+	assert.deepEqual(
+		seq,
+		[ids[0], ids[1], ids[2], ids[0], ids[2], ids[0]],
+		"list and peek navigation wrap around at both ends",
+	);
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+node --test test/dashboard-navigation.test.mjs
+```
+
+Expected: FAIL — `seq[5]` is `ids[2]` (peek clamped at last) instead of `ids[0]`.
+
+- [ ] **Step 3: Implement modulo wrap in `peekStep()`**
+
+In `src/ui/dashboard.ts`, replace:
+
+```ts
+	private peekStep(delta: number): void {
+		if (!this.peekId) return;
+		const idx = this.orderedIds.indexOf(this.peekId);
+		if (idx < 0) return;
+		const next = Math.max(0, Math.min(this.orderedIds.length - 1, idx + delta));
+```
+
+with:
+
+```ts
+	private peekStep(delta: number): void {
+		if (!this.peekId) return;
+		const idx = this.orderedIds.indexOf(this.peekId);
+		if (idx < 0) return;
+		const len = this.orderedIds.length;
+		// Wrap around both ends, same as moveSelection().
+		const next = ((idx + delta) % len + len) % len;
+```
+
+The two lines below (`this.peekId = ...; this.selectedId = ...`) stay unchanged. `len` is guaranteed `>= 1` here because `idx >= 0` implies the id was found in `orderedIds`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+node --test test/dashboard-navigation.test.mjs
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Full test suite + typecheck**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+npm test && npm run typecheck
+```
+
+Expected: all green.
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+git add src/ui/dashboard.ts test-support/navigation-wrap.ts test/dashboard-navigation.test.mjs
+git commit -m "fix: wrap peek-mode stepping at both ends (issue #52)"
+```
+
+---
+
+## Self-Review 记录
+
+- **Spec coverage**：spec 改动点 #1 → Task 1；改动点 #2 → Task 2；滚动跟随"不改"已在 Global Constraints 外无对应任务（无需任务）；launch picker 非目标 → Global Constraints 显式禁止。测试要求 → 两任务各带 TDD 循环。✅ 无缺口。
+- **Placeholder scan**：无 TBD/TODO；每个代码步骤含完整可运行代码。✅
+- **Type consistency**：`orderedIds` / `selectedId` / `peekId` / `mode` / `handleInput(data: string)` / `dispose()` 名称与 `src/ui/dashboard.ts` 实际成员一致；probe 的 JSON 形状 `{ ids, seq }` 在两个任务间一致（Task 2 只扩 seq 长度）。✅

package/docs/superpowers/plans/2026-08-30-pty-attach-quality-debt.md

@@ -0,0 +1,311 @@
+# pty-attach.ts Legacy Quality Debt Cleanup — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Clear the 10 legacy quality issues in `src/ui/pty-attach.ts` flagged by issue #8 — document 9 intentional empty catches, add a SAFETY comment to 1 as-cast, drop 1 unused parameter. Zero behavior change.
+
+**Architecture:** Single-file comment/signature cleanup. Empty catches are expanded to the repo's documented-catch house style (see `dashboard.ts` precedent); the as-cast gets an invariant comment; `project()` loses its unused `width` parameter. Existing test suite is the regression net — no new tests (no behavior change to test).
+
+**Tech Stack:** TypeScript (strict), `node --test`, tab indentation.
+
+**Spec:** `docs/superpowers/specs/2026-08-30-pty-attach-quality-debt-design.md`
+
+## Global Constraints
+
+- Touch ONLY `src/ui/pty-attach.ts` (plus this plan file's checkboxes).
+- Zero behavior change: no logic added/removed except the parameter deletion and its call-site argument.
+- Indentation is TABS. Comment style: expand `} catch {}` to multi-line with the comment INSIDE the braces, exactly like `dashboard.ts` (`} catch {` / `\t/* best effort: ... */` / `}`).
+- Locate sites by method name, not line number (lines drift).
+- `git add` per file only; NEVER `git add -A` (main checkout has untracked files that must not be swept — the worktree is clean, but keep the habit).
+- Run all commands from the worktree root: `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-8-pty-attach-quality-debt`
+
+---
+
+### Task 1: Document the 9 empty catches + the as-cast invariant
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (9 catch sites + 1 as-cast site, by method)
+
+**Interfaces:** none changed (comments only).
+
+There are exactly 9 single-line `} catch {}` sites in the file. Each becomes a 3-line documented catch. The edits, by method (old → new). Match surrounding context exactly; indentation is tabs.
+
+1. `enableMouseScroll()` — inside `try { this.tui.terminal.write(XTSHIFTESCAPE_SELECT); this.tui.terminal.write(MOUSE_ENABLE); }`:
+
+```ts
+// OLD
+		} catch {}
+	}
+
+	private mouseScrollEnabled(): boolean {
+// NEW
+		} catch {
+			/* best-effort: some terminals reject these sequences; mouse reporting is optional */
+		}
+	}
+
+	private mouseScrollEnabled(): boolean {
+```
+
+2. `disableMouseScroll()`:
+
+```ts
+// OLD
+	private disableMouseScroll(): void {
+		try {
+			this.tui.terminal.write(MOUSE_DISABLE);
+		} catch {}
+	}
+// NEW
+	private disableMouseScroll(): void {
+		try {
+			this.tui.terminal.write(MOUSE_DISABLE);
+		} catch {
+			/* best-effort: terminal may already be gone at teardown */
+		}
+	}
+```
+
+3. `copySelectionToClipboard()` — the OSC52 write:
+
+```ts
+// OLD
+		if (seq) {
+			try {
+				this.tui.terminal.write(seq);
+			} catch {}
+		}
+// NEW
+		if (seq) {
+			try {
+				this.tui.terminal.write(seq);
+			} catch {
+				/* best-effort: OSC52 clipboard support is optional */
+			}
+		}
+```
+
+4. `pastePrimarySelection()` — inner timer kill:
+
+```ts
+// OLD
+			const timer = setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {}
+			}, 800);
+// NEW
+			const timer = setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					/* the child may have already exited before the timeout fired */
+				}
+			}, 800);
+```
+
+5. `pastePrimarySelection()` — outer catch, at end of method (the `} catch {}` right before the method's closing `}`):
+
+```ts
+// OLD
+			child.on("close", () => {
+				clearTimeout(timer);
+				if (!this.closed && out) this.send({ type: "input", data: out });
+			});
+		} catch {}
+	}
+// NEW
+			child.on("close", () => {
+				clearTimeout(timer);
+				if (!this.closed && out) this.send({ type: "input", data: out });
+			});
+		} catch {
+			/* silent no-op when xclip is absent — documented contract of this helper */
+		}
+	}
+```
+
+6. `writePrimarySelection()`:
+
+```ts
+// OLD
+			child.stdin?.on("error", () => {});
+			child.on("error", () => {});
+			child.stdin?.end(text);
+		} catch {}
+	}
+// NEW
+			child.stdin?.on("error", () => {});
+			child.on("error", () => {});
+			child.stdin?.end(text);
+		} catch {
+			/* silent no-op when xclip is absent */
+		}
+	}
+```
+
+7. `forwardTerminalProtocols()` — the per-sequence write loop:
+
+```ts
+// OLD
+		for (const seq of toWrite) {
+			try {
+				this.tui.terminal.write(seq);
+			} catch {}
+		}
+// NEW
+		for (const seq of toWrite) {
+			try {
+				this.tui.terminal.write(seq);
+			} catch {
+				/* best-effort: forwarded sequences are enhancements, never critical */
+			}
+		}
+```
+
+8. `replayScreenLog()` — outer catch at end of method:
+
+```ts
+// OLD
+			} finally {
+				closeSync(fd);
+			}
+		} catch {}
+	}
+// NEW
+			} finally {
+				closeSync(fd);
+			}
+		} catch {
+			/* best-effort: a missing or racing screen.log must not block attach */
+		}
+	}
+```
+
+9. `close()` — socket destroy:
+
+```ts
+// OLD
+		try {
+			this.socket?.destroy();
+		} catch {}
+		this.socket = null;
+// NEW
+		try {
+			this.socket?.destroy();
+		} catch {
+			/* best-effort teardown: socket may already be destroyed */
+		}
+		this.socket = null;
+```
+
+10. `currentSize()` — SAFETY comment above the as-cast:
+
+```ts
+// OLD
+	private currentSize(): { cols: number; rows: number } {
+		const term = this.tui.terminal as unknown as { cols?: number; columns?: number; rows?: number } | undefined;
+// NEW
+	private currentSize(): { cols: number; rows: number } {
+		// SAFETY: duck-typed read — Pi TUI's Terminal type does not consistently expose
+		// cols/columns/rows across versions (see resizeIfNeeded below). Runtime
+		// fallbacks (120/24) keep this safe when the fields are absent.
+		const term = this.tui.terminal as unknown as { cols?: number; columns?: number; rows?: number } | undefined;
+```
+
+- [ ] **Step 1: Apply all 10 edits** (by method, exact old→new above)
+
+- [ ] **Step 2: Assert no bare `catch {}` remains**
+
+Run: `grep -c "catch {}" src/ui/pty-attach.ts`
+Expected: `0`
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: clean exit
+
+- [ ] **Step 4: Tests**
+
+Run: `npm test`
+Expected: all pass (no behavior change)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ui/pty-attach.ts
+git commit -m "chore: document intentional empty catches and as-cast invariant in pty-attach (issue #8)"
+```
+
+---
+
+### Task 2: Drop the unused `width` parameter from `project()`
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (signature + single call site)
+
+**Interfaces:**
+- Changes: `private project(height: number, width: number)` → `private project(height: number)` (private; one caller)
+
+The parameter `width` is never read in the method body. `width` at the call site remains used by `resizeIfNeeded(width)` / `renderLoading(...)` / `clip(...)` — only the `project()` argument goes away.
+
+```ts
+// OLD (signature)
+	private project(height: number, width: number): { lines: string[]; cursor: { row: number; col: number } | null } {
+// NEW (signature)
+	private project(height: number): { lines: string[]; cursor: { row: number; col: number } | null } {
+```
+
+```ts
+// OLD (call site, in render(width: number))
+			const projected = this.project(bodyHeight, width);
+// NEW (call site)
+			const projected = this.project(bodyHeight);
+```
+
+- [ ] **Step 1: Apply both edits**
+
+- [ ] **Step 2: Assert single-arg signature and call**
+
+Run: `grep -n "project(" src/ui/pty-attach.ts`
+Expected: exactly 2 hits — `render(...)`'s `this.project(bodyHeight);` and `private project(height: number): ...`
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: clean exit (a missed call site would fail here)
+
+- [ ] **Step 4: Tests**
+
+Run: `npm test`
+Expected: all pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ui/pty-attach.ts
+git commit -m "chore: drop unused width param from PtyAttachComponent.project (issue #8)"
+```
+
+---
+
+### Task 3: Final verification sweep
+
+**Files:** none modified.
+
+- [ ] **Step 1: Full verify pipeline (same as CI)**
+
+Run: `npm run verify`
+Expected: typecheck + tests + coverage thresholds (lines 85 / funcs 80 / branches 70) + pack dry-run all pass.
+
+- [ ] **Step 2: Zero-behavior diff audit**
+
+Run: `git diff main...HEAD -- src/ui/pty-attach.ts | grep -E "^[+-]" | grep -vE "^(\+\+\+|---)" | grep -vE "^\+\s*(/\*|//|\*/?)" | grep -vE "^-.*catch \{\}" | grep -vE "^\+\s*} catch \{" | grep -vE "^\+\s*}"`
+Expected: exactly 4 lines — the `project` signature and call site (`-`/`+` pairs). Everything else in the raw diff must be comment additions or `catch {}` expansions; any other code line appearing here means behavior changed — investigate before proceeding.
+
+- [ ] **Step 3: Confirm working tree clean**
+
+Run: `git status --short`
+Expected: empty (nothing uncommitted, nothing swept in)
+
+No commit in this task (verification only).