@bugabinga/pi-ext-diff-review 0.1.0

package/PLAN.md

@@ -0,0 +1,770 @@
+# diff-review plan
+
+Interactive browser review workflow for Pi using Pierre.
+
+## Goal
+
+Add `/diff-review`: collect a git diff, open a tokenized localhost browser UI powered by `@pierre/diffs` + `@pierre/trees`, let user annotate exact changed lines, then persist structured findings and send a user message back to Pi so the agent proposes a fix plan before editing.
+
+## Verdict-driven constraints
+
+These are blockers, not polish:
+
+- browser bundle lifecycle must be enforced before command starts
+- Pierre APIs must match installed published typings, not repo assumptions
+- browser opener must be explicit + safe with manual fallback
+- command must never wait forever: timeout, heartbeat, abort, cancel command, shared cleanup
+- static server must serve complete production output dir, not only `app.js`
+- browser smoke test must validate production bundle in real browser before v1 is considered done
+
+## Workspace conventions from `AGENTS.md`
+
+- New extension path is `agent/extensions/diff-review/`.
+- Required first files:
+  1. `agent/extensions/diff-review/package.json`
+  2. `agent/extensions/diff-review/index.ts`
+  3. run `bun install` after structural/package changes
+- `package.json` must follow workspace template: `@bugabinga/pi-ext-diff-review`, `private`, `type: "module"`, `main: "index.ts"`.
+- Add only deps actually imported by this extension.
+- Pi packages (`@earendil-works/*`) go in `peerDependencies`.
+- Do not import from any `@bugabinga/pi-ext-*` extension; copy local patterns instead.
+- TS source imports local files with `.js` specifiers, matching existing extensions.
+- Use existing extension patterns:
+  - constants in `constants.ts` (`EXTENSION_ID`, command names, status ids)
+  - types in `types.ts`
+  - session helpers in `session-state.ts`, following `q/session-state.ts`
+  - `index.ts` stays orchestration-only where possible
+
+## Verified research
+
+### Pi extension APIs
+
+- Extension entrypoint: `agent/extensions/diff-review/index.ts` exporting `default function (pi: ExtensionAPI)`.
+- Slash command via `pi.registerCommand("diff-review", { handler })`.
+- Command handler should:
+  - require `ctx.hasUI`
+  - `await ctx.waitForIdle()` before starting
+  - block until browser submit/cancel/timeout/abort
+  - call `pi.sendUserMessage([{ type: "text", text: markdown }])` after submit
+- Persist branch-local state via custom session entries:
+  - use `pi.appendEntry(customType, data)` when entry id is not needed
+  - use local helper with `ExtensionContext["sessionManager"]` cast when entry id is needed, matching `q/session-state.ts`
+- Restore state on `session_start` by scanning `ctx.sessionManager.getBranch()` and selecting entries where:
+  - `entry.type === "custom"`
+  - `entry.customType === "diff-review"`
+- Clean up active localhost server on `session_shutdown`.
+- No verified generic Pi URL-open API found. Implement platform opener fallback in extension.
+
+### Verified `@pierre/diffs@1.1.22` typings
+
+Installed package inspected from npm tarball under `~/.pi/research/extracts/pierre-npm/diffs`.
+
+Relevant exact API:
+
+```ts
+import {
+  FileDiff,
+  parsePatchFiles,
+  type DiffLineAnnotation,
+  type FileDiffMetadata,
+  type ParsedPatch,
+  type SelectedLineRange,
+} from "@pierre/diffs";
+
+const patches: ParsedPatch[] = parsePatchFiles(diffText, "diff-review", true);
+
+const instance = new FileDiff<{ findingId: string }>({
+  theme: { dark: "pierre-dark", light: "pierre-light" },
+  diffStyle: "split",
+  overflow: "scroll",
+  enableLineSelection: true,
+  enableGutterUtility: true,
+  lineHoverHighlight: "both",
+  onLineSelected(range: SelectedLineRange | null) {},
+  onGutterUtilityClick(range: SelectedLineRange) {},
+  renderAnnotation(annotation: DiffLineAnnotation<{ findingId: string }>) {
+    return document.createElement("div");
+  },
+});
+
+const ok: boolean = instance.render({
+  fileDiff,
+  containerWrapper,
+  lineAnnotations,
+});
+
+instance.setLineAnnotations(lineAnnotations);
+instance.setSelectedLines({ start, end, side: "additions", endSide: "additions" });
+instance.rerender();
+instance.cleanUp();
+```
+
+`FileDiff.render(...)` accepts:
+
+```ts
+{
+  fileDiff?: FileDiffMetadata;
+  oldFile?: FileContents;
+  newFile?: FileContents;
+  forceRender?: boolean;
+  preventEmit?: boolean;
+  fileContainer?: HTMLElement;
+  containerWrapper?: HTMLElement;
+  lineAnnotations?: DiffLineAnnotation<T>[];
+  renderRange?: RenderRange;
+}
+```
+
+`SelectedLineRange` is:
+
+```ts
+{
+  start: number;
+  side?: "deletions" | "additions";
+  end: number;
+  endSide?: "deletions" | "additions";
+}
+```
+
+`DiffLineAnnotation<T>` is:
+
+```ts
+{
+  side: "deletions" | "additions";
+  lineNumber: number;
+  metadata: T;
+}
+```
+
+Important asset note:
+
+- `@pierre/diffs` ships `dist/style.js`; component code imports CSS through wrapper utilities/web component registration.
+- Worker assets exist under `dist/worker/*`, but v1 will not instantiate `WorkerPoolManager`; no worker route needed unless later enabled.
+
+### Verified `@pierre/trees@1.0.0-beta.4` typings
+
+Installed package inspected from npm tarball under `~/.pi/research/extracts/pierre-npm/trees`.
+
+Relevant exact API:
+
+```ts
+import { FileTree, type GitStatusEntry } from "@pierre/trees";
+
+const tree = new FileTree({
+  paths,
+  search: true,
+  initialExpansion: "open",
+  initialSelectedPaths: [],
+  gitStatus,
+  onSelectionChange(selectedPaths: readonly string[]) {},
+});
+
+tree.render({ fileTreeContainer });
+// or tree.render({ containerWrapper });
+
+tree.getSelectedPaths();
+tree.getFocusedPath();
+tree.focusPath(path);
+tree.scrollToPath(path);
+tree.setGitStatus(gitStatus);
+tree.cleanUp();
+```
+
+`FileTree` render props are exactly:
+
+```ts
+{
+  containerWrapper?: HTMLElement;
+  fileTreeContainer?: HTMLElement;
+}
+```
+
+## Scope
+
+### Command
+
+```text
+/diff-review [--base origin/main] [--staged] [--files a.ts,b.ts]
+/diff-review-cancel
+```
+
+Behavior:
+
+- interactive-only
+- waits for browser submit/cancel/timeout
+- on submit:
+  1. append `diff-review` custom entry
+  2. shared cleanup
+  3. send markdown review to Pi as user message
+- on browser/user cancel: shared cleanup, no session entry, no user message
+- `/diff-review-cancel`: abort active review server and unblock command
+- starting a second `/diff-review` while one is active: notify error with active URL
+
+Flag semantics:
+
+- default: unstaged working tree diff (`git diff`), untracked files ignored in v1
+- `--staged`: staged diff (`git diff --cached`)
+- `--base <ref>`: branch/base comparison (`git diff <ref>...HEAD`)
+- `--staged` and `--base` are mutually exclusive
+- `--files a.ts,b.ts`: path filter, relative paths only, no absolute paths, no `..`
+
+### Git commands
+
+Run with `execFile`/`pi.exec` args, never shell interpolation.
+
+```ts
+// repo check/root
+git rev-parse --show-toplevel
+
+// default
+git diff --no-ext-diff --find-renames --unified=3 -- [files...]
+
+// staged
+git diff --cached --no-ext-diff --find-renames --unified=3 -- [files...]
+
+// base
+git diff --no-ext-diff --find-renames --unified=3 <base>...HEAD -- [files...]
+```
+
+Empty diff → notify `No diff to review` and return.
+
+Binary-only/unparseable files:
+
+- keep raw diff in payload
+- mark file as skipped if no hunks can be rendered
+- do not allow line findings for skipped files
+
+## Browser bundle lifecycle
+
+### Chosen policy
+
+Commit generated production browser assets and also guard against stale/missing builds at runtime.
+
+Implementation layout:
+
+```text
+agent/extensions/diff-review/
+├── package.json
+├── index.ts                 # register commands/events; orchestration only
+├── constants.ts             # EXTENSION_ID, command/status ids, defaults
+├── types.ts                 # shared node/browser serializable types
+├── args.ts                  # slash-arg parser
+├── git.ts                   # git diff collection + DiffIndex
+├── server.ts                # localhost server + token auth + lifecycle
+├── session-state.ts         # append/restore helpers, q-style
+├── format.ts                # markdown formatting
+├── open-browser.ts          # safe opener fallback
+├── scripts/
+│   ├── build-browser.ts
+│   └── smoke-browser.ts
+├── browser/
+│   ├── index.html
+│   ├── index.ts
+│   └── style.css
+└── static/
+    ├── index.html
+    ├── app.js
+    ├── app.css?          # if Bun emits/copies one
+    ├── assets/...        # any emitted assets
+    └── manifest.json     # generated by build script
+```
+
+Pattern rules:
+
+- Node files import Pi types from `@earendil-works/pi-coding-agent`.
+- Browser files import Pierre deps only; keep Pi SDK out of browser bundle.
+- Local imports use `.js` specifiers, e.g. `import { EXTENSION_ID } from "./constants.js"`.
+- No imports from sibling extensions.
+
+`static/` is generated but committed for normal Pi runtime. Server serves all of `static/`, not individual hard-coded assets.
+
+### Build script requirements
+
+Use a small `scripts/build-browser.ts`, not only raw `bun build`, because it must:
+
+1. copy `browser/index.html` → `static/index.html`
+2. bundle `browser/index.ts` → `static/app.js`
+3. copy/emit any CSS/assets Bun produces
+4. write `static/manifest.json` containing:
+   - source file mtimes + sha256 for `browser/**`
+   - package versions for `@pierre/diffs` and `@pierre/trees`
+   - build timestamp
+   - Bun version
+
+Runtime `ensureBrowserBundle()`:
+
+- if `static/index.html`, `static/app.js`, or manifest missing:
+  - try auto-build if `bun` is available and extension dir is writable
+  - otherwise fail fast with exact command: `cd agent/extensions/diff-review && bun install && bun run build`
+- if manifest source hashes/mtimes do not match:
+  - try auto-build in dev workspace
+  - otherwise fail fast with same command
+- if auto-build fails: show stderr + command, do not start server
+
+### Package scaffold
+
+Start from `AGENTS.md` template, then add only imported deps:
+
+```json
+{
+  "name": "@bugabinga/pi-ext-diff-review",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "build": "bun ./scripts/build-browser.ts",
+    "smoke:browser": "bun ./scripts/smoke-browser.ts"
+  },
+  "dependencies": {
+    "@pierre/diffs": "^1.1.22",
+    "@pierre/trees": "^1.0.0-beta.4"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}
+```
+
+Notes:
+
+- `@pierre/diffs` and `@pierre/trees` are `dependencies` because `browser/index.ts` imports them.
+- Do not add `@earendil-works/pi-tui` unless Node-side rendering/widget code imports it.
+- Do not add Playwright unless `scripts/smoke-browser.ts` imports it; if used, add as `devDependencies` only.
+- After creating/changing this package file or build layout, run `bun install` from workspace/extension as required by `AGENTS.md`.
+
+Run after scaffold/deps/asset changes:
+
+```bash
+cd agent/extensions/diff-review
+bun install
+bun run build
+bun run smoke:browser
+```
+
+## Browser launch strategy
+
+No Pi URL-open API is verified, so use safe platform fallback.
+
+`openBrowser(url)`:
+
+- Termux: `termux-open-url <url>` if available
+- macOS: `open <url>`
+- Windows: `cmd.exe /c start "" <url>`
+- Linux/BSD: `xdg-open <url>`
+- WSL fallback if needed: `wslview <url>`
+
+Rules:
+
+- use `spawn`/`execFile`, no shell except Windows `cmd.exe /c start`
+- opener failure is non-fatal
+- always show manual URL via `ctx.ui.notify` and status/widget
+- optionally copy URL if a clipboard command exists (`wl-copy`, `xclip`, `pbcopy`, `clip.exe`, `termux-clipboard-set`), but do not depend on clipboard
+
+UI status while active:
+
+```text
+diff-review: open http://127.0.0.1:<port>/?token=...
+```
+
+## Abort / timeout / heartbeat
+
+All command exits go through one `finish(result)` path guarded by an idempotent state flag.
+
+Active review state:
+
+```ts
+type ActiveReview = {
+  id: string;
+  url: string;
+  server: Server;
+  controller: AbortController;
+  heartbeatTimer: NodeJS.Timeout;
+  timeoutTimer: NodeJS.Timeout;
+  lastHeartbeatAt: number;
+  resolve(result: BrowserResult): void;
+};
+```
+
+Timeouts:
+
+- hard session timeout default: 30 min
+- heartbeat interval from browser: 5s
+- heartbeat considered lost after 30s
+- heartbeat loss only warns first; hard timeout or explicit cancel ends command
+- `/diff-review-cancel` ends immediately
+- `session_shutdown` aborts active review immediately
+
+Browser routes:
+
+```text
+POST /api/heartbeat          updates lastHeartbeatAt
+POST /api/cancel             explicit browser cancel
+```
+
+If browser tab closes, heartbeat warning tells user to reopen URL or run `/diff-review-cancel`; hard timeout prevents indefinite hang.
+
+## Local server protocol
+
+Bind only to localhost:
+
+```text
+127.0.0.1:0
+```
+
+Token:
+
+- `crypto.randomBytes(32).toString("base64url")`
+- browser URL: `http://127.0.0.1:<port>/?token=<token>`
+- all `/api/*` requests require `Authorization: Bearer <token>`
+- static files require either token query on `/` or a same-origin session cookie set by `/`; API still uses bearer token
+
+Routes:
+
+```text
+GET  /                         static/index.html; requires token query
+GET  /static/*                 files from static build dir
+GET  /api/review               JSON review payload
+POST /api/heartbeat            heartbeat
+POST /api/finding/validate     validate selection + preview anchor
+POST /api/submit               submit notes/findings
+POST /api/cancel               cancel command
+```
+
+`GET /api/review` response:
+
+```ts
+type ReviewPayload = {
+  round: number;
+  source: ReviewSource;
+  diffText: string;
+  files: Array<{
+    path: string;
+    prevPath?: string;
+    status: "added" | "modified" | "deleted" | "renamed" | "binary";
+    additions: number;
+    deletions: number;
+  }>;
+  carriedFindings: Finding[];
+};
+```
+
+Command awaits one of:
+
+```ts
+type BrowserResult =
+  | { type: "submit"; notes?: string; findings: FindingDraft[] }
+  | { type: "cancel"; reason: "browser" | "command" | "shutdown" | "timeout" };
+```
+
+Cleanup:
+
+- close server
+- abort controller
+- clear timers
+- clear status/widget
+- clean active review global
+
+## Browser UI
+
+Layout:
+
+- left sidebar: `@pierre/trees` changed-file tree
+- main panel: one `@pierre/diffs` `FileDiff` per changed file
+- right drawer: active selection + annotation form
+- footer/header: submit/cancel, round number, source summary
+
+Review drawer fields:
+
+- category: `bug | style | perf | question`
+- severity: `high | medium | low`
+- comment: required
+- notes: optional per-finding note or global notes textarea
+
+Selection rules:
+
+- use `onLineSelected(range)` and `onGutterUtilityClick(range)`
+- accept only `range.side`/`range.endSide` in `additions | deletions`
+- if mixed sides, reject for v1 with UI hint
+- `startLine = Math.min(range.start, range.end)`
+- `endLine = Math.max(range.start, range.end)`
+- render saved findings as `DiffLineAnnotation<{ findingId, severity, category, comment }>`
+
+Browser lifecycle:
+
+- heartbeat starts after successful `/api/review`
+- `beforeunload` tries best-effort `navigator.sendBeacon("/api/cancel")` only if no submit happened; command does not rely on this
+- explicit Cancel button posts `/api/cancel`
+- Submit disables form, posts `/api/submit`, then shows `Submitted — return to Pi`
+
+Implementation sketch with verified APIs:
+
+```ts
+import { FileDiff, parsePatchFiles, type SelectedLineRange } from "@pierre/diffs";
+import { FileTree } from "@pierre/trees";
+
+const review = await apiGetReview();
+const patches = parsePatchFiles(review.diffText, `diff-review-${review.round}`, true);
+
+const tree = new FileTree({
+  paths: review.files.map((f) => f.path),
+  search: true,
+  initialExpansion: "open",
+  gitStatus: toGitStatus(review.files),
+  onSelectionChange(paths) {
+    const path = paths[0];
+    if (path) scrollToDiff(path);
+  },
+});
+tree.render({ fileTreeContainer: document.getElementById("tree")! });
+
+for (const patch of patches) {
+  for (const fileDiff of patch.files) {
+    const instance = new FileDiff({
+      theme: { dark: "pierre-dark", light: "pierre-light" },
+      diffStyle: "split",
+      overflow: "scroll",
+      enableLineSelection: true,
+      enableGutterUtility: true,
+      lineHoverHighlight: "both",
+      onLineSelected: (range: SelectedLineRange | null) => openDrawer(fileDiff.name, range),
+      onGutterUtilityClick: (range: SelectedLineRange) => openDrawer(fileDiff.name, range),
+      renderAnnotation: renderFindingAnnotation,
+    });
+    instance.render({ fileDiff, containerWrapper: diffRoot, lineAnnotations: [] });
+  }
+}
+```
+
+## Agent result
+
+After submit, send this as a user message:
+
+```md
+# Diff Review Round N
+
+## Findings
+- [high][bug] src/foo.ts:43 additions — comment
+
+## Notes
+...
+
+Use this review to propose and discuss a fix plan first. Do not edit files yet.
+```
+
+No findings:
+
+```md
+# Diff Review Round N
+
+No findings recorded.
+
+Use this review result to decide whether any follow-up is needed. Do not edit files yet.
+```
+
+## Data model
+
+```ts
+type ReviewCategory = "bug" | "style" | "perf" | "question";
+type ReviewSeverity = "high" | "medium" | "low";
+type ReviewSide = "additions" | "deletions";
+type FindingStatus = "open" | "resolved" | "closed_auto";
+
+type Finding = {
+  id: string;
+  round: number;
+  file: string;
+  prevFile?: string;
+  side: ReviewSide;
+  startLine: number;
+  endLine: number;
+  category: ReviewCategory;
+  severity: ReviewSeverity;
+  comment: string;
+  notes?: string;
+  status: FindingStatus;
+  statusReason?: "file_removed" | "anchor_missing" | "manual";
+  anchor: {
+    before: string;
+    selected: string;
+    after: string;
+  };
+};
+
+type ReviewSource = {
+  kind: "working-tree" | "staged" | "base";
+  base?: string;
+  files?: string[];
+};
+
+type ReviewRoundEntry = {
+  version: 1;
+  kind: "round";
+  round: number;
+  source: ReviewSource;
+  findings: Finding[];
+  notes?: string;
+  diffSummary: {
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+    skippedFiles: string[];
+  };
+  createdAt: string;
+};
+```
+
+Custom session entry:
+
+```ts
+pi.appendEntry("diff-review", reviewRoundEntry);
+```
+
+Restore state:
+
+```ts
+function restore(branch: SessionEntry[]): ReviewState {
+  const rounds: ReviewRoundEntry[] = [];
+  for (const entry of branch) {
+    if (entry.type !== "custom" || entry.customType !== "diff-review") continue;
+    const data = entry.data as ReviewRoundEntry;
+    if (data?.version === 1 && data.kind === "round") rounds.push(data);
+  }
+  return {
+    round: Math.max(0, ...rounds.map((r) => r.round)),
+    findings: rounds.flatMap((r) => r.findings),
+  };
+}
+```
+
+## Diff index / anchors
+
+Server builds a `DiffIndex` from unified patch before opening browser:
+
+```ts
+type DiffLineMap = Map<number, string>;
+
+type IndexedFileDiff = {
+  file: string;
+  prevFile?: string;
+  status: "added" | "modified" | "deleted" | "renamed" | "binary";
+  additions: DiffLineMap; // new-file line number → text
+  deletions: DiffLineMap; // old-file line number → text
+};
+```
+
+Anchor generation on submit:
+
+- browser sends selection + form data only
+- server looks up selected lines in `DiffIndex`
+- `selected`: selected line texts joined with `\n`
+- `before`: up to 3 available same-side lines before `startLine`
+- `after`: up to 3 available same-side lines after `endLine`
+
+If lookup fails, reject submit with `400` so browser can show stale-selection error.
+
+## Security
+
+- bind `127.0.0.1` only
+- random token, required for API writes
+- no filesystem writes from browser
+- sanitize/validate file filters before passing to git
+- never invoke shell with interpolated args
+- render user comments/paths via `textContent`
+- cap diff size for v1, e.g. 5 MiB patch text; notify if too large
+- clear token/session state on submit/cancel/timeout
+
+## Production browser smoke test
+
+Add `scripts/smoke-browser.ts` before v1 completion.
+
+Test must:
+
+1. run `bun run build`
+2. start extension static server with sample diff fixture
+3. open real browser using Playwright or available Chromium
+4. load tokenized URL
+5. assert no 404s for `static/*`
+6. assert no console errors
+7. assert Pierre tree renders file path
+8. assert Pierre diff renders changed line
+9. create one finding via DOM event/click path if possible, otherwise call UI fn behind test hook
+10. submit and assert server receives finding
+
+If Playwright browser unavailable, smoke script exits with clear skip only in dev; CI/v1 release requires pass.
+
+## Implementation phases
+
+### 0. Preflight proof
+
+- scaffold package
+- install deps
+- inspect local `node_modules/@pierre/*/dist/*.d.ts` after `bun install`
+- build minimal browser bundle
+- run smoke server/page manually or via `smoke:browser`
+- verify no missing assets/console errors
+
+Acceptance:
+
+- `bun run build` creates `static/index.html`, `static/app.js`, `manifest.json`
+- `bun run smoke:browser` passes or gives actionable missing-browser skip
+
+### 1. Minimal command + local server
+
+- parse args
+- `ensureBrowserBundle()`
+- collect git diff + file summary + `DiffIndex`
+- start tokenized localhost server serving full `static/` dir
+- open browser or show manual URL
+- wait for submit/cancel/timeout
+- append `diff-review` entry
+- send markdown user message
+- `/diff-review-cancel`
+
+Acceptance:
+
+- `/diff-review` opens browser for unstaged diff
+- missing/stale browser bundle auto-builds or fails with exact command
+- opener failure still provides usable URL
+- Submit returns to Pi and triggers agent turn with review markdown
+- Cancel/timeout/session shutdown unblocks command and closes server
+
+### 2. Pierre UI
+
+- `@pierre/trees` changed-file sidebar with verified `FileTree` API
+- `@pierre/diffs` split diff list with verified `FileDiff` API
+- line/range selection
+- annotation drawer
+- finding chips via `lineAnnotations`
+- tree status badges via `gitStatus`
+
+### 3. Pi persistence
+
+- append `diff-review` entries
+- reconstruct current-branch state on `session_start`
+- widget/status: `N open review findings`
+
+### 4. Reconciliation
+
+On next review round:
+
+- file missing → `closed_auto`, `statusReason: "file_removed"`
+- selected anchor missing → `closed_auto`, `statusReason: "anchor_missing"`
+- selected anchor found elsewhere → update line range
+- user can manually resolve carried findings
+
+### 5. Polish
+
+- dark/light sync with Pi theme if possible
+- markdown export fallback only if later requested
+- optional prompt injection of open findings before next agent turn
+- optional worker pool for large diffs, only after serving/copying worker assets is verified
+
+## Non-goals for v1
+
+- applying fixes directly from browser
+- replacing normal `edit` rendering
+- full Pi session tree browser
+- untracked-file review
+- non-interactive mode
+- Pierre worker pool / WASM highlighter routing