@ilya-lesikov/pi-pi 0.1.0

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

@@ -0,0 +1,378 @@
+/**
+ * Plan Storage Utility
+ *
+ * Saves plans and annotations to ~/.plannotator/plans/
+ * Cross-platform: works on Windows, macOS, and Linux.
+ *
+ * Runtime-agnostic: uses only node:fs, node:path, node:os.
+ */
+
+import { join, resolve, sep } from "path";
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, statSync, existsSync } from "fs";
+import { sanitizeTag } from "./project";
+import { resolveUserPath } from "./resolve-file";
+import { getPlannotatorDataDir } from "./data-dir";
+
+const DATA_DIR = getPlannotatorDataDir();
+
+/**
+ * Get the plan storage directory, creating it if needed.
+ * Cross-platform: uses os.homedir() for Windows/macOS/Linux compatibility.
+ * @param customPath Optional custom path. Supports ~ for home directory.
+ */
+export function getPlanDir(customPath?: string | null): string {
+  let planDir: string;
+
+  if (customPath?.trim()) {
+    planDir = resolveUserPath(customPath);
+  } else {
+    planDir = join(DATA_DIR, "plans");
+  }
+
+  mkdirSync(planDir, { recursive: true });
+  return planDir;
+}
+
+/**
+ * Extract the first heading from markdown content.
+ */
+function extractFirstHeading(markdown: string): string | null {
+  const match = markdown.match(/^#\s+(.+)$/m);
+  if (!match) return null;
+  return match[1].trim();
+}
+
+/**
+ * Generate a slug from plan content.
+ * Format: {sanitized-heading}-YYYY-MM-DD
+ */
+export function generateSlug(plan: string): string {
+  const date = new Date().toISOString().split("T")[0]; // YYYY-MM-DD
+
+  const heading = extractFirstHeading(plan);
+  const slug = heading ? sanitizeTag(heading) : null;
+
+  return slug ? `${slug}-${date}` : `plan-${date}`;
+}
+
+/**
+ * Save the plan markdown to disk.
+ * Returns the full path to the saved file.
+ */
+export function savePlan(slug: string, content: string, customPath?: string | null): string {
+  const planDir = getPlanDir(customPath);
+  const filePath = join(planDir, `${slug}.md`);
+  writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
+/**
+ * Save annotations to disk.
+ * Returns the full path to the saved file.
+ */
+export function saveAnnotations(slug: string, annotationsContent: string, customPath?: string | null): string {
+  const planDir = getPlanDir(customPath);
+  const filePath = join(planDir, `${slug}.annotations.md`);
+  writeFileSync(filePath, annotationsContent, "utf-8");
+  return filePath;
+}
+
+/**
+ * Save the final snapshot on approve/deny.
+ * Combines plan and annotations into a single file with status suffix.
+ * Returns the full path to the saved file.
+ */
+export function saveFinalSnapshot(
+  slug: string,
+  status: "approved" | "denied",
+  plan: string,
+  annotations: string,
+  customPath?: string | null
+): string {
+  const planDir = getPlanDir(customPath);
+  const filePath = join(planDir, `${slug}-${status}.md`);
+
+  // Combine plan with annotations appended
+  let content = plan;
+  if (annotations && annotations !== "No changes detected.") {
+    content += "\n\n---\n\n" + annotations;
+  }
+
+  writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
+// --- Plan Archive ---
+
+export interface ArchivedPlan {
+  filename: string;
+  title: string;
+  date: string;
+  timestamp: string;  // ISO string from file mtime
+  status: "approved" | "denied" | "unknown";
+  size: number;
+}
+
+/**
+ * Parse an archive filename into metadata.
+ * Handles both old (DATE-heading-status.md) and new (heading-DATE-status.md) formats.
+ */
+export function parseArchiveFilename(filename: string): ArchivedPlan | null {
+  // Skip non-decision files
+  if (filename.endsWith(".annotations.md") || filename.endsWith(".diff.md")) return null;
+
+  const base = filename.replace(/\.md$/, "");
+
+  // Extract status suffix
+  let status: ArchivedPlan["status"] = "unknown";
+  let slug = base;
+  if (base.endsWith("-approved")) {
+    status = "approved";
+    slug = base.slice(0, -"-approved".length);
+  } else if (base.endsWith("-denied")) {
+    status = "denied";
+    slug = base.slice(0, -"-denied".length);
+  } else {
+    // Skip plain files (no decision status)
+    return null;
+  }
+
+  // Extract date (YYYY-MM-DD) — could be anywhere in the slug
+  const dateMatch = slug.match(/(\d{4}-\d{2}-\d{2})/);
+  const date = dateMatch ? dateMatch[1] : "";
+
+  // Title: remove date, convert hyphens to spaces, trim
+  const title = slug
+    .replace(/\d{4}-\d{2}-\d{2}/, "")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-+/g, " ")
+    .trim() || "Untitled Plan";
+
+  return { filename, title, date, timestamp: "", status, size: 0 };
+}
+
+/**
+ * List all archived plans (approved/denied decision snapshots).
+ * Returns plans sorted by date descending.
+ */
+export function listArchivedPlans(customPath?: string | null): ArchivedPlan[] {
+  const planDir = getPlanDir(customPath);
+  try {
+    const entries = readdirSync(planDir);
+    const plans: ArchivedPlan[] = [];
+    for (const entry of entries) {
+      if (!entry.endsWith(".md")) continue;
+      const parsed = parseArchiveFilename(entry);
+      if (!parsed) continue;
+      try {
+        const stat = statSync(join(planDir, entry));
+        parsed.size = stat.size;
+        parsed.timestamp = stat.mtime.toISOString();
+      } catch { /* keep defaults */ }
+      plans.push(parsed);
+    }
+    return plans.sort((a, b) => b.date.localeCompare(a.date) || b.timestamp.localeCompare(a.timestamp));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read an archived plan file by filename.
+ * Returns null if the file doesn't exist or on read error.
+ */
+export function readArchivedPlan(filename: string, customPath?: string | null): string | null {
+  const planDir = getPlanDir(customPath);
+  const filePath = resolve(planDir, filename);
+  // Guard against path traversal (resolve + trailing separator, matching reference-handlers.ts)
+  if (!filePath.startsWith(planDir + sep)) return null;
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+// --- Version History ---
+
+/**
+ * Get the history directory for a project/slug combination, creating it if needed.
+ * History is always stored in ~/.plannotator/history/{project}/{slug}/.
+ * Not affected by the customPath setting (that only affects decision saves).
+ */
+export function getHistoryDir(project: string, slug: string): string {
+  const historyDir = join(DATA_DIR, "history", project, slug);
+  mkdirSync(historyDir, { recursive: true });
+  return historyDir;
+}
+
+/**
+ * Determine the next version number by scanning existing files.
+ * Returns 1 if no versions exist, otherwise max + 1.
+ */
+function getNextVersionNumber(historyDir: string): number {
+  try {
+    const entries = readdirSync(historyDir);
+    let max = 0;
+    for (const entry of entries) {
+      const match = entry.match(/^(\d+)\.md$/);
+      if (match) {
+        const num = parseInt(match[1], 10);
+        if (num > max) max = num;
+      }
+    }
+    return max + 1;
+  } catch {
+    return 1;
+  }
+}
+
+/**
+ * Save a plan version to the history directory.
+ * Deduplication: if the latest version has identical content, skip saving.
+ * Returns the version number, file path, and whether a new file was created.
+ */
+export function saveToHistory(
+  project: string,
+  slug: string,
+  plan: string
+): { version: number; path: string; isNew: boolean } {
+  const historyDir = getHistoryDir(project, slug);
+  const nextVersion = getNextVersionNumber(historyDir);
+
+  // Deduplicate: check if latest version has identical content
+  if (nextVersion > 1) {
+    const latestPath = join(historyDir, `${String(nextVersion - 1).padStart(3, "0")}.md`);
+    try {
+      const existing = readFileSync(latestPath, "utf-8");
+      if (existing === plan) {
+        return { version: nextVersion - 1, path: latestPath, isNew: false };
+      }
+    } catch {
+      // File read failed, proceed with saving
+    }
+  }
+
+  const fileName = `${String(nextVersion).padStart(3, "0")}.md`;
+  const filePath = join(historyDir, fileName);
+  writeFileSync(filePath, plan, "utf-8");
+  return { version: nextVersion, path: filePath, isNew: true };
+}
+
+/**
+ * Read a specific version's content from history.
+ * Returns null if the version doesn't exist or on read error.
+ */
+export function getPlanVersion(
+  project: string,
+  slug: string,
+  version: number
+): string | null {
+  const historyDir = join(DATA_DIR, "history", project, slug);
+  const fileName = `${String(version).padStart(3, "0")}.md`;
+  const filePath = join(historyDir, fileName);
+
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the file path for a specific version in history.
+ * Returns null if the version file doesn't exist.
+ */
+export function getPlanVersionPath(
+  project: string,
+  slug: string,
+  version: number
+): string | null {
+  const historyDir = join(DATA_DIR, "history", project, slug);
+  const fileName = `${String(version).padStart(3, "0")}.md`;
+  const filePath = join(historyDir, fileName);
+  return existsSync(filePath) ? filePath : null;
+}
+
+/**
+ * Get the number of versions stored for a project/slug.
+ * Returns 0 if the directory doesn't exist.
+ */
+export function getVersionCount(project: string, slug: string): number {
+  const historyDir = join(DATA_DIR, "history", project, slug);
+  try {
+    const entries = readdirSync(historyDir);
+    return entries.filter((e) => /^\d+\.md$/.test(e)).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * List all versions for a project/slug with metadata.
+ * Returns versions sorted ascending by version number.
+ */
+export function listVersions(
+  project: string,
+  slug: string
+): Array<{ version: number; timestamp: string }> {
+  const historyDir = join(DATA_DIR, "history", project, slug);
+  try {
+    const entries = readdirSync(historyDir);
+    const versions: Array<{ version: number; timestamp: string }> = [];
+    for (const entry of entries) {
+      const match = entry.match(/^(\d+)\.md$/);
+      if (match) {
+        const version = parseInt(match[1], 10);
+        const filePath = join(historyDir, entry);
+        try {
+          const stat = statSync(filePath);
+          versions.push({ version, timestamp: stat.mtime.toISOString() });
+        } catch {
+          versions.push({ version, timestamp: "" });
+        }
+      }
+    }
+    return versions.sort((a, b) => a.version - b.version);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * List all plan slugs stored for a project.
+ * Returns slugs sorted by most recently modified first.
+ */
+export function listProjectPlans(
+  project: string
+): Array<{ slug: string; versions: number; lastModified: string }> {
+  const projectDir = join(DATA_DIR, "history", project);
+  try {
+    const entries = readdirSync(projectDir, { withFileTypes: true });
+    const plans: Array<{ slug: string; versions: number; lastModified: string }> = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const slugDir = join(projectDir, entry.name);
+      const files = readdirSync(slugDir).filter((f) => /^\d+\.md$/.test(f));
+      if (files.length === 0) continue;
+
+      // Find most recent file modification time
+      let latest = 0;
+      for (const file of files) {
+        try {
+          const mtime = statSync(join(slugDir, file)).mtime.getTime();
+          if (mtime > latest) latest = mtime;
+        } catch { /* skip */ }
+      }
+
+      plans.push({
+        slug: entry.name,
+        versions: files.length,
+        lastModified: latest ? new Date(latest).toISOString() : "",
+      });
+    }
+    return plans.sort((a, b) => b.lastModified.localeCompare(a.lastModified));
+  } catch {
+    return [];
+  }
+}

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

@@ -0,0 +1,61 @@
+export interface TourDiffAnchor {
+  /** Relative file path within the repo. */
+  file: string;
+  /** Start line in the new file (post-change). */
+  line: number;
+  /** End line in the new file. */
+  end_line: number;
+  /** Raw unified diff hunk for this anchor. */
+  hunk: string;
+  /** One-line chip label, e.g. "Add retry logic". */
+  label: string;
+}
+
+export interface TourKeyTakeaway {
+  /** One sentence — the takeaway. */
+  text: string;
+  /** Severity for visual styling. */
+  severity: "info" | "important" | "warning";
+}
+
+export interface TourStop {
+  /** Short chapter title, friendly tone. */
+  title: string;
+  /** ONE sentence — the headline for this stop. Scannable without expanding. */
+  gist: string;
+  /** 2-3 sentences of additional context. Only shown when expanded. */
+  detail: string;
+  /** Connective phrase to the next stop, e.g. "Building on that..." (empty for last stop). */
+  transition: string;
+  /** Diff anchors — the code locations this stop references. */
+  anchors: TourDiffAnchor[];
+}
+
+export interface TourQAItem {
+  /** Product-level verification question. */
+  question: string;
+  /** Indices into stops[] that this question relates to. */
+  stop_indices: number[];
+}
+
+export interface CodeTourOutput {
+  /** One-line title for the entire tour. */
+  title: string;
+  /** 1-2 sentence friendly greeting + summary. Conversational, not formal. */
+  greeting: string;
+  /** 1-3 sentences: why this changeset exists — the motivation/problem being solved. */
+  intent: string;
+  /** What things looked like before this changeset — one sentence. */
+  before: string;
+  /** What things look like after — one sentence. */
+  after: string;
+  /** 3-5 key takeaways — the most critical info, scannable at a glance. */
+  key_takeaways: TourKeyTakeaway[];
+  /** Ordered tour stops — the detailed walk-through. */
+  stops: TourStop[];
+  /** Product-level QA checklist. */
+  qa_checklist: TourQAItem[];
+}
+
+/** UI-side tour shape: server output extended with persisted checklist state. */
+export type CodeTourData = CodeTourOutput & { checklist: boolean[] };

package/3p/pi-plannotator/packages/shared/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "types": ["node"]
+  },
+  "exclude": ["**/*.test.ts"]
+}

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

@@ -0,0 +1,29 @@
+// Editor annotations from VS Code extension (ephemeral, in-memory only)
+export interface EditorAnnotation {
+  id: string;
+  filePath: string;     // workspace-relative (e.g., "src/auth.ts")
+  selectedText: string;
+  lineStart: number;    // 1-based
+  lineEnd: number;      // 1-based
+  comment?: string;
+  createdAt: number;
+}
+
+// Git review types shared between server and client
+export type {
+  DiffOption,
+  WorktreeInfo,
+  GitContext,
+  JjEvoLogEntry,
+  RecentCommit,
+  AvailableBranches,
+  CompareTargetConfig,
+  CompareTargetPickerCopy,
+  RepositoryContext,
+} from "./review-core";
+
+export type {
+  WorkspaceDiffType,
+  WorkspaceRepoState,
+  WorkspaceReviewState,
+} from "./review-workspace";

package/3p/pi-plannotator/packages/shared/url-to-markdown.test.ts

@@ -0,0 +1,177 @@
+import { test, expect, mock, beforeEach, afterEach } from "bun:test";
+import { urlToMarkdown } from "./url-to-markdown";
+
+// Track fetch calls to verify headers and URL selection
+let fetchCalls: { url: string; headers: Record<string, string> }[] = [];
+const originalFetch = globalThis.fetch;
+
+beforeEach(() => {
+  fetchCalls = [];
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+/**
+ * Create a mock fetch that responds based on the Accept header.
+ * When Accept includes text/markdown, returns markdown with the right content-type.
+ * Otherwise returns HTML.
+ */
+function mockFetchWithMarkdownSupport(markdown: string) {
+  return mock((url: string | URL | Request, init?: RequestInit) => {
+    const headers = init?.headers as Record<string, string> | undefined;
+    fetchCalls.push({ url: String(url), headers: headers ?? {} });
+
+    const accept = headers?.Accept || headers?.accept || "";
+    if (accept.includes("text/markdown")) {
+      return Promise.resolve(
+        new Response(markdown, {
+          status: 200,
+          headers: {
+            "content-type": "text/markdown; charset=utf-8",
+            "x-markdown-tokens": "42",
+          },
+        }),
+      );
+    }
+    return Promise.resolve(
+      new Response("<html><body><p>Hello</p></body></html>", {
+        status: 200,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      }),
+    );
+  });
+}
+
+/** Mock fetch that only returns HTML (no markdown support). */
+function mockFetchHtmlOnly(html = "<html><body><p>Fallback</p></body></html>") {
+  return mock((url: string | URL | Request, init?: RequestInit) => {
+    const headers = init?.headers as Record<string, string> | undefined;
+    fetchCalls.push({ url: String(url), headers: headers ?? {} });
+    return Promise.resolve(
+      new Response(html, {
+        status: 200,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      }),
+    );
+  });
+}
+
+test("content negotiation: uses markdown when server supports it", async () => {
+  const md = "# Hello\n\nThis is markdown from the server.";
+  globalThis.fetch = mockFetchWithMarkdownSupport(md) as typeof fetch;
+
+  const result = await urlToMarkdown("https://example.com/page", { useJina: true });
+
+  expect(result.source).toBe("content-negotiation");
+  expect(result.markdown).toBe(md);
+  // Should only make one fetch (the content negotiation request)
+  expect(fetchCalls).toHaveLength(1);
+  expect(fetchCalls[0].headers.Accept).toContain("text/markdown");
+});
+
+test("content negotiation: falls through to Jina when server returns HTML", async () => {
+  // First call (content negotiation) returns HTML, second (Jina) returns markdown
+  let callCount = 0;
+  globalThis.fetch = mock((url: string | URL | Request, init?: RequestInit) => {
+    const headers = init?.headers as Record<string, string> | undefined;
+    fetchCalls.push({ url: String(url), headers: headers ?? {} });
+    callCount++;
+
+    if (callCount === 1) {
+      // Content negotiation attempt — server doesn't support it
+      return Promise.resolve(
+        new Response("<html><body>Hi</body></html>", {
+          status: 200,
+          headers: { "content-type": "text/html; charset=utf-8" },
+        }),
+      );
+    }
+    // Jina Reader call
+    return Promise.resolve(
+      new Response("# From Jina", {
+        status: 200,
+        headers: { "content-type": "text/plain" },
+      }),
+    );
+  }) as typeof fetch;
+
+  const result = await urlToMarkdown("https://example.com/page", { useJina: true });
+
+  expect(result.source).toBe("jina");
+  expect(result.markdown).toBe("# From Jina");
+  // Content negotiation fetch + Jina fetch
+  expect(fetchCalls.length).toBeGreaterThanOrEqual(2);
+  expect(fetchCalls[1].url).toContain("r.jina.ai");
+});
+
+test("content negotiation: skipped for local URLs", async () => {
+  let callCount = 0;
+  globalThis.fetch = mock((_url: string | URL | Request, init?: RequestInit) => {
+    const headers = init?.headers as Record<string, string> | undefined;
+    fetchCalls.push({ url: String(_url), headers: headers ?? {} });
+    callCount++;
+    return Promise.resolve(
+      new Response("<html><body>Local</body></html>", {
+        status: 200,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      }),
+    );
+  }) as typeof fetch;
+
+  const result = await urlToMarkdown("http://localhost:3000/readme", { useJina: false });
+
+  expect(result.source).toBe("fetch+turndown");
+  // No content negotiation request should have been made
+  // (first call should be the Turndown fetch, not a markdown request)
+  for (const call of fetchCalls) {
+    if (call.headers.Accept) {
+      expect(call.headers.Accept).not.toContain("text/markdown");
+    }
+  }
+});
+
+test("content negotiation: handles server error gracefully", async () => {
+  let callCount = 0;
+  globalThis.fetch = mock((_url: string | URL | Request, init?: RequestInit) => {
+    const headers = init?.headers as Record<string, string> | undefined;
+    fetchCalls.push({ url: String(_url), headers: headers ?? {} });
+    callCount++;
+
+    if (callCount === 1) {
+      // Content negotiation — server error
+      return Promise.resolve(new Response(null, { status: 500 }));
+    }
+    // Jina fallback
+    return Promise.resolve(
+      new Response("# Jina fallback", {
+        status: 200,
+        headers: { "content-type": "text/plain" },
+      }),
+    );
+  }) as typeof fetch;
+
+  const result = await urlToMarkdown("https://example.com/page", { useJina: true });
+
+  // Should fall through to Jina
+  expect(result.source).toBe("jina");
+});
+
+test("raw .md URL: still takes priority over content negotiation", async () => {
+  globalThis.fetch = mock((_url: string | URL | Request, init?: RequestInit) => {
+    const headers = init?.headers as Record<string, string> | undefined;
+    fetchCalls.push({ url: String(_url), headers: headers ?? {} });
+    return Promise.resolve(
+      new Response("# Raw markdown file", {
+        status: 200,
+        headers: { "content-type": "text/plain; charset=utf-8" },
+      }),
+    );
+  }) as typeof fetch;
+
+  const result = await urlToMarkdown("https://example.com/README.md", { useJina: true });
+
+  expect(result.source).toBe("fetch-raw");
+  expect(result.markdown).toBe("# Raw markdown file");
+});