@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-plannotator/packages/shared/diff-paths.ts

@@ -0,0 +1,137 @@
+export interface DiffPathPair {
+  oldPath?: string;
+  newPath?: string;
+}
+
+export function unquoteGitPath(value: string): string {
+  if (!value.startsWith('"') || !value.endsWith('"')) return value;
+  try {
+    return JSON.parse(value) as string;
+  } catch {
+    return value.slice(1, -1)
+      .replace(/\\"/g, '"')
+      .replace(/\\\\/g, "\\")
+      .replace(/\\t/g, "\t")
+      .replace(/\\n/g, "\n");
+  }
+}
+
+export function quoteGitPath(value: string): string {
+  if (!/[\s"\\]/.test(value)) return value;
+  return JSON.stringify(value);
+}
+
+function stripUnquotedPathMetadata(token: string): string {
+  if (token.startsWith('"')) return token;
+  const tabIndex = token.indexOf("\t");
+  return tabIndex === -1 ? token : token.slice(0, tabIndex);
+}
+
+export function parsePatchPathToken(token: string, side: "a" | "b"): string | null {
+  const pathToken = stripUnquotedPathMetadata(token);
+  if (pathToken === "/dev/null") return "/dev/null";
+  const unquoted = unquoteGitPath(pathToken);
+  const prefix = `${side}/`;
+  return unquoted.startsWith(prefix) ? unquoted.slice(prefix.length) : null;
+}
+
+function scanHeaderToken(input: string): { token: string; rest: string } | null {
+  const trimmed = input.trimStart();
+  if (!trimmed) return null;
+
+  if (trimmed.startsWith('"')) {
+    let escaped = false;
+    for (let i = 1; i < trimmed.length; i += 1) {
+      const char = trimmed[i];
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (char === '"') {
+        return { token: trimmed.slice(0, i + 1), rest: trimmed.slice(i + 1) };
+      }
+    }
+    return null;
+  }
+
+  const space = trimmed.indexOf(" ");
+  if (space === -1) return { token: trimmed, rest: "" };
+  return { token: trimmed.slice(0, space), rest: trimmed.slice(space + 1) };
+}
+
+export function parseDiffGitHeader(header: string): DiffPathPair {
+  const prefix = "diff --git ";
+  if (!header.startsWith(prefix)) return {};
+
+  const rest = header.slice(prefix.length);
+  if (rest.trimStart().startsWith('"')) {
+    const first = scanHeaderToken(rest);
+    const second = first ? scanHeaderToken(first.rest) : null;
+    if (first && second) {
+      const oldPath = parsePatchPathToken(first.token, "a");
+      const newPath = parsePatchPathToken(second.token, "b");
+      return {
+        oldPath: oldPath && oldPath !== "/dev/null" ? oldPath : undefined,
+        newPath: newPath && newPath !== "/dev/null" ? newPath : undefined,
+      };
+    }
+  }
+
+  const match = header.match(/^diff --git a\/(.+) b\/(.+)$/);
+  if (!match) return {};
+  return { oldPath: match[1], newPath: match[2] };
+}
+
+export function formatPatchPathToken(side: "a" | "b", filePath: string): string {
+  if (filePath === "/dev/null") return filePath;
+  return quoteGitPath(`${side}/${filePath}`);
+}
+
+export function parseDiffMetadataPathToken(token: string): string {
+  if (token === "/dev/null") return token;
+  return unquoteGitPath(token);
+}
+
+export function formatDiffMetadataPathToken(filePath: string): string {
+  if (filePath === "/dev/null") return filePath;
+  return quoteGitPath(filePath);
+}
+
+export function parseDiffFilePathLines(lines: string[]): DiffPathPair {
+  let oldPath: string | undefined;
+  let newPath: string | undefined;
+
+  for (const line of lines) {
+    if (line.startsWith("@@ ") || line === "GIT binary patch") break;
+    if (line.startsWith("--- ")) {
+      const parsed = parsePatchPathToken(line.slice(4), "a");
+      if (parsed && parsed !== "/dev/null") oldPath = parsed;
+    } else if (line.startsWith("+++ ")) {
+      const parsed = parsePatchPathToken(line.slice(4), "b");
+      if (parsed && parsed !== "/dev/null") newPath = parsed;
+    }
+  }
+
+  return { oldPath, newPath };
+}
+
+export function parseDiffMetadataPathLines(lines: string[]): DiffPathPair {
+  let oldPath: string | undefined;
+  let newPath: string | undefined;
+
+  for (const line of lines) {
+    if (line.startsWith("rename from ") || line.startsWith("copy from ")) {
+      const parsed = parseDiffMetadataPathToken(line.slice(line.indexOf(" from ") + " from ".length));
+      if (parsed !== "/dev/null") oldPath = parsed;
+    } else if (line.startsWith("rename to ") || line.startsWith("copy to ")) {
+      const parsed = parseDiffMetadataPathToken(line.slice(line.indexOf(" to ") + " to ".length));
+      if (parsed !== "/dev/null") newPath = parsed;
+    }
+  }
+
+  return { oldPath, newPath };
+}

package/3p/pi-plannotator/packages/shared/draft.ts

@@ -0,0 +1,64 @@
+/**
+ * Draft Storage
+ *
+ * Persists annotation drafts to ~/.plannotator/drafts/ so they survive
+ * server crashes. Each draft is keyed by a content hash of the plan/diff
+ * it was created against.
+ *
+ * Runtime-agnostic: uses only node:fs, node:path, node:os, node:crypto.
+ */
+
+import { join } from "path";
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync, existsSync } from "fs";
+import { createHash } from "crypto";
+import { getPlannotatorDataDir } from "./data-dir";
+
+/**
+ * Get the drafts directory, creating it if needed.
+ */
+export function getDraftDir(): string {
+  const dir = join(getPlannotatorDataDir(), "drafts");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Generate a stable key from content using truncated SHA-256.
+ * Same content always produces the same key across server restarts.
+ */
+export function contentHash(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+/**
+ * Save a draft to disk.
+ */
+export function saveDraft(key: string, data: object): void {
+  const dir = getDraftDir();
+  writeFileSync(join(dir, `${key}.json`), JSON.stringify(data), "utf-8");
+}
+
+/**
+ * Load a draft from disk. Returns null if not found.
+ */
+export function loadDraft(key: string): object | null {
+  const filePath = join(getDraftDir(), `${key}.json`);
+  try {
+    if (!existsSync(filePath)) return null;
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Delete a draft from disk. No-op if not found.
+ */
+export function deleteDraft(key: string): void {
+  const filePath = join(getDraftDir(), `${key}.json`);
+  try {
+    if (existsSync(filePath)) unlinkSync(filePath);
+  } catch {
+    // Ignore delete failures
+  }
+}

package/3p/pi-plannotator/packages/shared/external-annotation.ts

@@ -0,0 +1,397 @@
+/**
+ * External Annotations — shared types, store logic, and SSE helpers.
+ *
+ * Runtime-agnostic: no node:fs, no node:http, no Bun APIs.
+ * Both the Bun server handler and Pi server handler import this module
+ * and wrap it with their respective HTTP transport layers.
+ *
+ * The store is generic — plan servers store Annotation objects,
+ * review servers store CodeAnnotation objects. The mode-specific
+ * input transformers handle validation and field assignment.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Constraint for any annotation type the store can hold. */
+export type StorableAnnotation = { id: string; source?: string };
+
+export type ExternalAnnotationEvent<T = unknown> =
+  | { type: "snapshot"; annotations: T[] }
+  | { type: "add"; annotations: T[] }
+  | { type: "remove"; ids: string[] }
+  | { type: "clear"; source?: string }
+  | { type: "update"; id: string; annotation: T };
+
+// ---------------------------------------------------------------------------
+// SSE helpers
+// ---------------------------------------------------------------------------
+
+/** Heartbeat comment to keep SSE connections alive (sent every 30s). */
+export const HEARTBEAT_COMMENT = ":\n\n";
+
+/** Interval in ms between heartbeat comments. */
+export const HEARTBEAT_INTERVAL_MS = 30_000;
+
+/** Encode an event as an SSE `data:` line. */
+export function serializeSSEEvent<T>(event: ExternalAnnotationEvent<T>): string {
+  return `data: ${JSON.stringify(event)}\n\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Input validation — shared helpers
+// ---------------------------------------------------------------------------
+
+export interface ParseError {
+  error: string;
+}
+
+/**
+ * Unwrap a POST body into an array of raw input objects.
+ *
+ * Accepts either:
+ *   - A single annotation object: `{ source: "...", ... }`
+ *   - A batch wrapper: `{ annotations: [{ source: "...", ... }, ...] }`
+ */
+function unwrapBody(body: unknown): Record<string, unknown>[] | ParseError {
+  if (!body || typeof body !== "object") {
+    return { error: "Request body must be a JSON object" };
+  }
+
+  const obj = body as Record<string, unknown>;
+
+  // Batch format: { annotations: [...] }
+  if (Array.isArray(obj.annotations)) {
+    if (obj.annotations.length === 0) {
+      return { error: "annotations array must not be empty" };
+    }
+    const items: Record<string, unknown>[] = [];
+    for (let i = 0; i < obj.annotations.length; i++) {
+      const item = obj.annotations[i];
+      if (!item || typeof item !== "object") {
+        return { error: `annotations[${i}] must be an object` };
+      }
+      items.push(item as Record<string, unknown>);
+    }
+    return items;
+  }
+
+  // Single format: { source: "...", ... }
+  if (typeof obj.source === "string") {
+    return [obj as Record<string, unknown>];
+  }
+
+  return { error: 'Missing required "source" field or "annotations" array' };
+}
+
+function requireString(obj: Record<string, unknown>, field: string, index: number): string | ParseError {
+  const val = obj[field];
+  if (typeof val !== "string" || val.length === 0) {
+    return { error: `annotations[${index}] missing required "${field}" field` };
+  }
+  return val;
+}
+
+// ---------------------------------------------------------------------------
+// Plan mode transformer — produces Annotation objects
+// ---------------------------------------------------------------------------
+
+/** The Annotation type shape for plan mode (mirrors packages/ui/types.ts). */
+interface PlanAnnotation {
+  id: string;
+  blockId: string;
+  startOffset: number;
+  endOffset: number;
+  type: string; // AnnotationType value
+  text?: string;
+  originalText: string;
+  createdA: number;
+  author?: string;
+  source?: string;
+}
+
+const VALID_PLAN_TYPES = ["DELETION", "COMMENT", "GLOBAL_COMMENT"];
+
+export function transformPlanInput(
+  body: unknown,
+): { annotations: PlanAnnotation[] } | ParseError {
+  const items = unwrapBody(body);
+  if ("error" in items) return items;
+
+  const annotations: PlanAnnotation[] = [];
+  for (let i = 0; i < items.length; i++) {
+    const obj = items[i];
+
+    const source = requireString(obj, "source", i);
+    if (typeof source !== "string") return source;
+
+    // Must have text content
+    if (typeof obj.text !== "string" || obj.text.length === 0) {
+      return { error: `annotations[${i}] missing required "text" field` };
+    }
+
+    // Validate type if provided, default to GLOBAL_COMMENT
+    const type = typeof obj.type === "string" ? obj.type : "GLOBAL_COMMENT";
+    if (!VALID_PLAN_TYPES.includes(type)) {
+      return {
+        error: `annotations[${i}] invalid type "${type}". Must be one of: ${VALID_PLAN_TYPES.join(", ")}`,
+      };
+    }
+
+    // DELETION requires originalText (the text to remove)
+    if (type === "DELETION" && (typeof obj.originalText !== "string" || obj.originalText.length === 0)) {
+      return { error: `annotations[${i}] DELETION type requires non-empty "originalText" field` };
+    }
+
+    // COMMENT requires originalText so the renderer can pin it to a phrase.
+    // External agents that want sidebar-only feedback should use GLOBAL_COMMENT
+    // instead — without a phrase to anchor to, a COMMENT renders as an empty
+    // quote bubble in the sidebar and exports as `Feedback on: ""`.
+    if (type === "COMMENT" && (typeof obj.originalText !== "string" || obj.originalText.length === 0)) {
+      return {
+        error: `annotations[${i}] COMMENT requires non-empty "originalText" field. Use GLOBAL_COMMENT for sidebar-only feedback.`,
+      };
+    }
+
+    annotations.push({
+      id: crypto.randomUUID(),
+      blockId: "external",
+      startOffset: 0,
+      endOffset: 0,
+      type,
+      text: String(obj.text),
+      originalText: typeof obj.originalText === "string" ? obj.originalText : "",
+      createdA: Date.now(),
+      author: typeof obj.author === "string" ? obj.author : undefined,
+      source,
+    });
+  }
+
+  return { annotations };
+}
+
+// ---------------------------------------------------------------------------
+// Review mode transformer — produces CodeAnnotation objects
+// ---------------------------------------------------------------------------
+
+/** The CodeAnnotation type shape for review mode (mirrors packages/ui/types.ts). */
+interface ReviewAnnotation {
+  id: string;
+  type: string; // CodeAnnotationType value
+  scope?: string;
+  filePath: string;
+  lineStart: number;
+  lineEnd: number;
+  side: string;
+  text?: string;
+  suggestedCode?: string;
+  originalCode?: string;
+  createdAt: number;
+  author?: string;
+  source?: string;
+  // Agent review metadata (optional — only set by Claude review findings)
+  severity?: string; // "important" | "nit" | "pre_existing"
+  reasoning?: string; // Validation chain explaining how the issue was confirmed
+}
+
+const VALID_REVIEW_TYPES = ["comment", "suggestion", "concern"];
+const VALID_SIDES = ["old", "new"];
+const VALID_SCOPES = ["line", "file"];
+
+export function transformReviewInput(
+  body: unknown,
+): { annotations: ReviewAnnotation[] } | ParseError {
+  const items = unwrapBody(body);
+  if ("error" in items) return items;
+
+  const annotations: ReviewAnnotation[] = [];
+  for (let i = 0; i < items.length; i++) {
+    const obj = items[i];
+
+    const source = requireString(obj, "source", i);
+    if (typeof source !== "string") return source;
+
+    const filePath = requireString(obj, "filePath", i);
+    if (typeof filePath !== "string") return filePath;
+
+    if (typeof obj.lineStart !== "number") {
+      return { error: `annotations[${i}] missing required "lineStart" field` };
+    }
+    if (typeof obj.lineEnd !== "number") {
+      return { error: `annotations[${i}] missing required "lineEnd" field` };
+    }
+
+    // side: optional, defaults to "new"
+    const side = typeof obj.side === "string" ? obj.side : "new";
+    if (!VALID_SIDES.includes(side)) {
+      return {
+        error: `annotations[${i}] invalid side "${side}". Must be one of: ${VALID_SIDES.join(", ")}`,
+      };
+    }
+
+    // type: optional, defaults to "comment"
+    const type = typeof obj.type === "string" ? obj.type : "comment";
+    if (!VALID_REVIEW_TYPES.includes(type)) {
+      return {
+        error: `annotations[${i}] invalid type "${type}". Must be one of: ${VALID_REVIEW_TYPES.join(", ")}`,
+      };
+    }
+
+    // scope: optional, defaults to "line"
+    const scope = typeof obj.scope === "string" ? obj.scope : "line";
+    if (!VALID_SCOPES.includes(scope)) {
+      return {
+        error: `annotations[${i}] invalid scope "${scope}". Must be one of: ${VALID_SCOPES.join(", ")}`,
+      };
+    }
+
+    // Must have at least text or suggestedCode
+    if (typeof obj.text !== "string" && typeof obj.suggestedCode !== "string") {
+      return {
+        error: `annotations[${i}] must have at least one of: text, suggestedCode`,
+      };
+    }
+
+    annotations.push({
+      id: crypto.randomUUID(),
+      type,
+      scope,
+      filePath,
+      lineStart: obj.lineStart,
+      lineEnd: obj.lineEnd,
+      side,
+      text: typeof obj.text === "string" ? obj.text : undefined,
+      suggestedCode: typeof obj.suggestedCode === "string" ? obj.suggestedCode : undefined,
+      originalCode: typeof obj.originalCode === "string" ? obj.originalCode : undefined,
+      createdAt: Date.now(),
+      author: typeof obj.author === "string" ? obj.author : undefined,
+      source,
+      // Agent review metadata (optional — only set by Claude review findings)
+      ...(typeof obj.severity === "string" && { severity: obj.severity }),
+      ...(typeof obj.reasoning === "string" && { reasoning: obj.reasoning }),
+    });
+  }
+
+  return { annotations };
+}
+
+// ---------------------------------------------------------------------------
+// Annotation Store (generic)
+// ---------------------------------------------------------------------------
+
+type MutationListener<T> = (event: ExternalAnnotationEvent<T>) => void;
+
+export interface AnnotationStore<T extends StorableAnnotation> {
+  /** Add fully-formed annotations. Returns the added annotations. */
+  add(items: T[]): T[];
+  /** Remove an annotation by ID. Returns true if found. */
+  remove(id: string): boolean;
+  /** Remove all annotations from a specific source. Returns count removed. */
+  clearBySource(source: string): number;
+  /** Update an annotation by ID. Returns the updated annotation, or null if not found. */
+  update(id: string, fields: Partial<T>): T | null;
+  /** Remove all annotations. Returns count removed. */
+  clearAll(): number;
+  /** Get all annotations (snapshot). */
+  getAll(): T[];
+  /** Monotonic version counter — incremented on every mutation. */
+  readonly version: number;
+  /** Register a listener for mutation events. Returns unsubscribe function. */
+  onMutation(listener: MutationListener<T>): () => void;
+}
+
+/**
+ * Create an in-memory annotation store.
+ *
+ * The store is runtime-agnostic — it holds data and emits events.
+ * HTTP transport (SSE broadcasting, request parsing) is handled by
+ * the server-specific adapter (Bun or Pi).
+ */
+export function createAnnotationStore<T extends StorableAnnotation>(): AnnotationStore<T> {
+  const annotations: T[] = [];
+  const listeners = new Set<MutationListener<T>>();
+  let version = 0;
+
+  function emit(event: ExternalAnnotationEvent<T>): void {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Don't let a failing listener break the store
+      }
+    }
+  }
+
+  return {
+    add(items) {
+      if (items.length > 0) {
+        for (const item of items) {
+          annotations.push(item);
+        }
+        version++;
+        emit({ type: "add", annotations: items });
+      }
+      return items;
+    },
+
+    remove(id) {
+      const idx = annotations.findIndex((a) => a.id === id);
+      if (idx === -1) return false;
+      annotations.splice(idx, 1);
+      version++;
+      emit({ type: "remove", ids: [id] });
+      return true;
+    },
+
+    update(id, fields) {
+      const idx = annotations.findIndex((a) => a.id === id);
+      if (idx === -1) return null;
+      const merged = { ...annotations[idx], ...fields, id } as T;
+      annotations[idx] = merged;
+      version++;
+      emit({ type: "update", id, annotation: merged });
+      return merged;
+    },
+
+    clearBySource(source) {
+      const before = annotations.length;
+      for (let i = annotations.length - 1; i >= 0; i--) {
+        if (annotations[i].source === source) {
+          annotations.splice(i, 1);
+        }
+      }
+      const removed = before - annotations.length;
+      if (removed > 0) {
+        version++;
+        emit({ type: "clear", source });
+      }
+      return removed;
+    },
+
+    clearAll() {
+      const count = annotations.length;
+      if (count > 0) {
+        annotations.length = 0;
+        version++;
+        emit({ type: "clear" });
+      }
+      return count;
+    },
+
+    getAll() {
+      return [...annotations];
+    },
+
+    get version() {
+      return version;
+    },
+
+    onMutation(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}

package/3p/pi-plannotator/packages/shared/extract-code-paths.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect } from "bun:test";
+import { extractCandidateCodePaths } from "./extract-code-paths";
+
+describe("extractCandidateCodePaths", () => {
+	test("extracts backtick code-file paths", () => {
+		const md = "Open `packages/editor/App.tsx` to see the code.";
+		expect(extractCandidateCodePaths(md)).toEqual(["packages/editor/App.tsx"]);
+	});
+
+	test("extracts bare-prose paths", () => {
+		const md = "see editor/App.tsx and review-editor/App.tsx";
+		const out = extractCandidateCodePaths(md);
+		expect(out).toContain("editor/App.tsx");
+		expect(out).toContain("review-editor/App.tsx");
+	});
+
+	test("dedupes repeated references", () => {
+		const md = "`src/foo.ts` and src/foo.ts again";
+		expect(extractCandidateCodePaths(md)).toEqual(["src/foo.ts"]);
+	});
+
+	test("strips line anchors", () => {
+		const md = "see `src/foo.ts#L42`";
+		expect(extractCandidateCodePaths(md)).toEqual(["src/foo.ts"]);
+	});
+
+	test("rejects shell brace expansion", () => {
+		const md = "files in packages/ui/{a,b}.ts";
+		expect(extractCandidateCodePaths(md)).toEqual([]);
+	});
+
+	test("ignores fenced code blocks", () => {
+		const md = "```ts\nimport foo from 'src/foo.ts';\n```";
+		expect(extractCandidateCodePaths(md)).toEqual([]);
+	});
+
+	test("ignores HTML comments", () => {
+		const md = "<!-- src/foo.ts is a placeholder -->";
+		expect(extractCandidateCodePaths(md)).toEqual([]);
+	});
+
+	test("URLs do not produce path-shaped substrings", () => {
+		const md = "see https://github.com/foo/bar.ts in the docs";
+		expect(extractCandidateCodePaths(md)).toEqual([]);
+	});
+
+	test("URL on same line as a real path keeps the path", () => {
+		const md = "https://github.com/example.com docs and editor/App.tsx";
+		const out = extractCandidateCodePaths(md);
+		expect(out).toContain("editor/App.tsx");
+	});
+
+	test("URLs containing parens or brackets do not leak path-shaped substrings", () => {
+		// Wikipedia-style URL ends in `).ts` — earlier extractor erroneously
+		// stopped its URL match at `(`, leaving `bar).ts` as a path candidate.
+		const md = "see https://en.wikipedia.org/wiki/Foo_(bar).ts in the docs";
+		expect(extractCandidateCodePaths(md)).toEqual([]);
+	});
+});