@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-plannotator/packages/server/sessions.ts

@@ -0,0 +1,111 @@
+/**
+ * Session Registry
+ *
+ * Tracks active Plannotator server sessions in ~/.plannotator/sessions/
+ * so users can discover and reopen closed browser tabs.
+ */
+
+import { join } from "path";
+import {
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+  unlinkSync,
+  existsSync,
+} from "fs";
+import { getPlannotatorDataDir } from "@plannotator/shared/data-dir";
+
+export interface SessionInfo {
+  pid: number;
+  port: number;
+  url: string;
+  mode: "plan" | "review" | "annotate" | "archive" | "goal-setup";
+  project: string;
+  startedAt: string;
+  label: string;
+}
+
+function getSessionsDir(): string {
+  const dir = join(getPlannotatorDataDir(), "sessions");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function sessionPath(pid: number): string {
+  return join(getSessionsDir(), `${pid}.json`);
+}
+
+/**
+ * Check if a process is still alive.
+ */
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Register the current server session.
+ */
+export function registerSession(info: SessionInfo): void {
+  writeFileSync(sessionPath(info.pid), JSON.stringify(info, null, 2), "utf-8");
+}
+
+/**
+ * Unregister the current process's session. No-op if not found.
+ */
+export function unregisterSession(pid: number = process.pid): void {
+  const filePath = sessionPath(pid);
+  try {
+    if (existsSync(filePath)) unlinkSync(filePath);
+  } catch {
+    // Ignore delete failures
+  }
+}
+
+/**
+ * List all active sessions. Automatically removes stale entries.
+ */
+export function listSessions(): SessionInfo[] {
+  const dir = getSessionsDir();
+  const active: SessionInfo[] = [];
+
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+
+    const filePath = join(dir, entry);
+    try {
+      const data: SessionInfo = JSON.parse(readFileSync(filePath, "utf-8"));
+
+      if (isAlive(data.pid)) {
+        active.push(data);
+      } else {
+        // Stale session — clean up
+        try {
+          unlinkSync(filePath);
+        } catch {}
+      }
+    } catch {
+      // Corrupt file — remove it
+      try {
+        unlinkSync(filePath);
+      } catch {}
+    }
+  }
+
+  // Sort by most recent first
+  return active.sort(
+    (a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime()
+  );
+}

package/3p/pi-plannotator/packages/server/share-url.ts

@@ -0,0 +1,53 @@
+/**
+ * Server-side share URL generation for remote sessions
+ *
+ * Generates a share.plannotator.ai URL from plan content so remote users
+ * can open the review in their local browser without port forwarding.
+ */
+
+import { compress } from "@plannotator/shared/compress";
+
+const DEFAULT_SHARE_BASE = "https://share.plannotator.ai";
+
+/**
+ * Generate a share URL from plan markdown content.
+ *
+ * Returns the full hash-based URL. For remote sessions, this lets the
+ * user open the plan in their local browser without any backend needed.
+ */
+export async function generateRemoteShareUrl(
+  plan: string,
+  shareBaseUrl?: string
+): Promise<string> {
+  const base = shareBaseUrl || DEFAULT_SHARE_BASE;
+  const hash = await compress({ p: plan, a: [] });
+  return `${base}/#${hash}`;
+}
+
+/**
+ * Format byte size as human-readable string
+ */
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const kb = bytes / 1024;
+  return kb < 100 ? `${kb.toFixed(1)} KB` : `${Math.round(kb)} KB`;
+}
+
+/**
+ * Generate a remote share URL and write it to stderr for the user.
+ * Silently does nothing on failure.
+ */
+export async function writeRemoteShareLink(
+  content: string,
+  shareBaseUrl: string | undefined,
+  verb: string,
+  noun: string
+): Promise<void> {
+  const shareUrl = await generateRemoteShareUrl(content, shareBaseUrl);
+  const size = formatSize(new TextEncoder().encode(shareUrl).length);
+  process.stderr.write(
+    `\n  Open this link on your local machine to ${verb}:\n` +
+    `  ${shareUrl}\n\n` +
+    `  (${size} — ${noun}, annotations added in browser)\n\n`
+  );
+}

package/3p/pi-plannotator/packages/server/shared-handlers.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { handleServerReady, writeServerReadyMetadata } from "./shared-handlers";
+
+describe("writeServerReadyMetadata", () => {
+  test("writes host-plugin ready metadata", () => {
+    const dir = mkdtempSync(join(tmpdir(), "plannotator-ready-"));
+    const readyFile = join(dir, "nested", "ready.jsonl");
+
+    try {
+      writeServerReadyMetadata(readyFile, {
+        url: "http://localhost:12345",
+        isRemote: false,
+        port: 12345,
+      });
+      const [line] = readFileSync(readyFile, "utf8").trim().split(/\r?\n/);
+      expect(JSON.parse(line)).toEqual({
+        url: "http://localhost:12345",
+        isRemote: false,
+        port: 12345,
+      });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("handleServerReady", () => {
+  test("does not open a browser when host-plugin mode handles it", async () => {
+    let opened = false;
+
+    await handleServerReady("http://localhost:12345", false, 12345, {
+      skipBrowserOpen: true,
+      openBrowser: async () => {
+        opened = true;
+      },
+    });
+
+    expect(opened).toBe(false);
+  });
+});

package/3p/pi-plannotator/packages/server/shared-handlers.ts

@@ -0,0 +1,177 @@
+/**
+ * Shared route handlers used by plan, review, and annotate servers.
+ *
+ * Eliminates duplication of /api/image, /api/upload, /api/draft, and the
+ * server-ready handler across all three server files. Also shares /api/agents
+ * for plan + review.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { openBrowser as openBrowserImpl } from "./browser";
+import { validateImagePath, validateUploadExtension, UPLOAD_DIR } from "./image";
+import { saveDraft, loadDraft, deleteDraft } from "./draft";
+import { FAVICON_SVG } from "@plannotator/shared/favicon";
+
+/** Serve images from local paths or temp uploads. Used by all 3 servers. */
+export async function handleImage(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  const imagePath = url.searchParams.get("path");
+  if (!imagePath) {
+    return new Response("Missing path parameter", { status: 400 });
+  }
+  const validation = validateImagePath(imagePath);
+  if (!validation.valid) {
+    return new Response(validation.error!, { status: 403 });
+  }
+  try {
+    const file = Bun.file(validation.resolved);
+    if (await file.exists()) {
+      return new Response(file);
+    }
+    // If not found and a base directory is provided, try resolving relative to it
+    const base = url.searchParams.get("base");
+    if (base && !imagePath.startsWith("/")) {
+      const { resolve: resolvePath } = await import("path");
+      const fromBase = resolvePath(base, imagePath);
+      const baseValidation = validateImagePath(fromBase);
+      if (baseValidation.valid) {
+        const baseFile = Bun.file(baseValidation.resolved);
+        if (await baseFile.exists()) {
+          return new Response(baseFile);
+        }
+      }
+    }
+    return new Response("File not found", { status: 404 });
+  } catch {
+    return new Response("Failed to read file", { status: 500 });
+  }
+}
+
+/** Upload image to temp dir, return path. Used by all 3 servers. */
+export async function handleUpload(req: Request): Promise<Response> {
+  try {
+    const formData = await req.formData();
+    const file = formData.get("file") as File;
+    if (!file) {
+      return new Response("No file provided", { status: 400 });
+    }
+
+    const extResult = validateUploadExtension(file.name);
+    if (!extResult.valid) {
+      return Response.json({ error: extResult.error }, { status: 400 });
+    }
+    mkdirSync(UPLOAD_DIR, { recursive: true });
+    const tempPath = `${UPLOAD_DIR}/${crypto.randomUUID()}.${extResult.ext}`;
+
+    await Bun.write(tempPath, file);
+    return Response.json({ path: tempPath, originalName: file.name });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Upload failed";
+    return Response.json({ error: message }, { status: 500 });
+  }
+}
+
+/** OpenCode agent client interface (subset of OpenCode SDK) */
+export interface OpencodeClient {
+  app: {
+    agents: (options?: object) => Promise<{
+      data?: Array<{ name: string; description?: string; mode: string; hidden?: boolean }>;
+    }>;
+  };
+}
+
+/** List available agents. Used by plan + review servers (OpenCode only). */
+export async function handleAgents(opencodeClient?: OpencodeClient): Promise<Response> {
+  if (!opencodeClient) {
+    return Response.json({ agents: [] });
+  }
+
+  try {
+    const result = await opencodeClient.app.agents({});
+    const agents = (result.data ?? [])
+      .filter((a) => a.mode === "primary" && !a.hidden)
+      .map((a) => ({ id: a.name, name: a.name, description: a.description }));
+
+    return Response.json({ agents });
+  } catch {
+    return Response.json({ agents: [], error: "Failed to fetch agents" });
+  }
+}
+
+/** Save annotation draft. Used by all 3 servers. */
+export async function handleDraftSave(req: Request, contentKey: string): Promise<Response> {
+  try {
+    const body = await req.json();
+    saveDraft(contentKey, body);
+    return Response.json({ ok: true });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Failed to save draft";
+    console.error(`[draft] save failed: ${message}`);
+    return Response.json({ error: message }, { status: 500 });
+  }
+}
+
+/** Load annotation draft. Used by all 3 servers. */
+export function handleDraftLoad(contentKey: string): Response {
+  const draft = loadDraft(contentKey);
+  if (!draft) {
+    return Response.json({ found: false }, { status: 404 });
+  }
+  return Response.json(draft);
+}
+
+/** Delete annotation draft. Used by all 3 servers. */
+export function handleDraftDelete(contentKey: string): Response {
+  deleteDraft(contentKey);
+  return Response.json({ ok: true });
+}
+
+
+
+/** Serve the app favicon. Used by all 3 servers. */
+export function handleFavicon(): Response {
+  return new Response(FAVICON_SVG, {
+    headers: { "Content-Type": "image/svg+xml", "Cache-Control": "public, max-age=86400" },
+  });
+}
+
+interface ServerReadyOptions {
+  readyFile?: string;
+  skipBrowserOpen?: boolean;
+  openBrowser?: typeof openBrowserImpl;
+}
+
+export interface ServerReadyMetadata {
+  url: string;
+  isRemote: boolean;
+  port: number;
+}
+
+export function writeServerReadyMetadata(readyFile: string, metadata: ServerReadyMetadata): void {
+  mkdirSync(dirname(readyFile), { recursive: true });
+  appendFileSync(readyFile, `${JSON.stringify(metadata)}\n`, "utf8");
+}
+
+/** Attempt to open the browser for the session URL. */
+export async function handleServerReady(
+  url: string,
+  isRemote: boolean,
+  port: number,
+  options: ServerReadyOptions = {},
+): Promise<void> {
+  const readyFile = options.readyFile ?? process.env.PLANNOTATOR_READY_FILE;
+  if (readyFile) {
+    try {
+      writeServerReadyMetadata(readyFile, { url, isRemote, port });
+    } catch (error) {
+      if (options.readyFile) throw error;
+      // Best effort: host plugins use this side channel to open the browser.
+    }
+  }
+
+  const skipBrowserOpen = options.skipBrowserOpen ?? process.env.PLANNOTATOR_SKIP_BROWSER_OPEN === "1";
+  if (skipBrowserOpen) return;
+
+  await (options.openBrowser ?? openBrowserImpl)(url, { isRemote, useGlimpse: true });
+}

package/3p/pi-plannotator/packages/server/storage.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Plan Storage Tests
+ *
+ * Run: bun test packages/server/storage.test.ts
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, readFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generateSlug, getPlanDir, savePlan, saveToHistory, getPlanVersion, getVersionCount, listVersions } from "./storage";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "plannotator-storage-test-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("generateSlug", () => {
+  test("uses first heading and date", () => {
+    const slug = generateSlug("# My Plan\n\nSome content");
+    const date = new Date().toISOString().split("T")[0];
+    expect(slug).toMatch(/^my-plan-\d{4}-\d{2}-\d{2}$/);
+    expect(slug).toEndWith(date);
+  });
+
+  test("falls back to 'plan' when no heading", () => {
+    const slug = generateSlug("No heading here");
+    expect(slug).toMatch(/^plan-\d{4}-\d{2}-\d{2}$/);
+  });
+
+  test("same heading on same day produces same slug", () => {
+    const a = generateSlug("# Deploy Strategy\nVersion A");
+    const b = generateSlug("# Deploy Strategy\nVersion B");
+    expect(a).toBe(b);
+  });
+
+  test("different headings produce different slugs", () => {
+    const a = generateSlug("# Plan A");
+    const b = generateSlug("# Plan B");
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("getPlanDir", () => {
+  test("creates directory at custom path", () => {
+    const dir = makeTempDir();
+    const customPath = join(dir, "custom", "plans");
+    const result = getPlanDir(customPath);
+    expect(result).toBe(customPath);
+    // Directory should exist
+    expect(readdirSync(customPath)).toBeDefined();
+  });
+
+  test("expands tilde in custom path", () => {
+    const result = getPlanDir("~/.plannotator/test-plans");
+    expect(result).not.toContain("~");
+    expect(result).toMatch(/\.plannotator\/test-plans$/);
+  });
+
+  test("uses default when no custom path", () => {
+    const result = getPlanDir();
+    expect(result).toMatch(/plans$/);
+    expect(result).toBe(getPlanDir(null));
+  });
+
+  test("uses default for null", () => {
+    const result = getPlanDir(null);
+    expect(result).toMatch(/plans$/);
+  });
+
+  test("uses default for whitespace-only custom path", () => {
+    const result = getPlanDir("   ");
+    expect(result).toMatch(/plans$/);
+    expect(result).not.toBe(process.cwd());
+  });
+});
+
+describe("savePlan", () => {
+  test("writes markdown file to disk", () => {
+    const dir = makeTempDir();
+    const path = savePlan("test-slug", "# Content", dir);
+    expect(path).toBe(join(dir, "test-slug.md"));
+    expect(readFileSync(path, "utf-8")).toBe("# Content");
+  });
+});
+
+describe("saveToHistory", () => {
+  test("creates first version as 001.md", () => {
+    const slug = `first-version-${Date.now()}`;
+    const result = saveToHistory("test-project", slug, "# V1");
+    expect(result.version).toBe(1);
+    expect(result.path).toEndWith("001.md");
+    expect(result.isNew).toBe(true);
+    expect(readFileSync(result.path, "utf-8")).toBe("# V1");
+  });
+
+  test("increments version number", () => {
+    const slug = `inc-test-${Date.now()}`;
+    const v1 = saveToHistory("test-project", slug, "# V1");
+    const v2 = saveToHistory("test-project", slug, "# V2");
+    expect(v1.version).toBe(1);
+    expect(v2.version).toBe(2);
+    expect(v2.path).toEndWith("002.md");
+  });
+
+  test("deduplicates identical content", () => {
+    const slug = `dedup-test-${Date.now()}`;
+    const v1 = saveToHistory("test-project", slug, "# Same");
+    const v2 = saveToHistory("test-project", slug, "# Same");
+    expect(v1.version).toBe(1);
+    expect(v2.version).toBe(1);
+    expect(v2.isNew).toBe(false);
+  });
+
+  test("saves when content differs", () => {
+    const slug = `diff-test-${Date.now()}`;
+    const v1 = saveToHistory("test-project", slug, "# V1");
+    const v2 = saveToHistory("test-project", slug, "# V2");
+    expect(v2.isNew).toBe(true);
+    expect(v2.version).toBe(2);
+  });
+});
+
+describe("getPlanVersion", () => {
+  test("reads saved version content", () => {
+    const slug = `read-test-${Date.now()}`;
+    saveToHistory("test-project", slug, "# Read Me");
+    const content = getPlanVersion("test-project", slug, 1);
+    expect(content).toBe("# Read Me");
+  });
+
+  test("returns null for nonexistent version", () => {
+    const content = getPlanVersion("test-project", "nonexistent", 99);
+    expect(content).toBeNull();
+  });
+});
+
+describe("getVersionCount", () => {
+  test("returns 0 for nonexistent project", () => {
+    expect(getVersionCount("nope", "nope")).toBe(0);
+  });
+
+  test("counts versions correctly", () => {
+    const slug = `count-test-${Date.now()}`;
+    saveToHistory("test-project", slug, "# V1");
+    saveToHistory("test-project", slug, "# V2");
+    saveToHistory("test-project", slug, "# V3");
+    expect(getVersionCount("test-project", slug)).toBe(3);
+  });
+});
+
+describe("listVersions", () => {
+  test("returns empty for nonexistent project", () => {
+    expect(listVersions("nope", "nope")).toEqual([]);
+  });
+
+  test("lists versions in ascending order", () => {
+    const slug = `list-test-${Date.now()}`;
+    saveToHistory("test-project", slug, "# V1");
+    saveToHistory("test-project", slug, "# V2");
+    const versions = listVersions("test-project", slug);
+    expect(versions).toHaveLength(2);
+    expect(versions[0].version).toBe(1);
+    expect(versions[1].version).toBe(2);
+    expect(versions[0].timestamp).toBeTruthy();
+  });
+});

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

@@ -0,0 +1,17 @@
+export {
+  getPlanDir,
+  generateSlug,
+  savePlan,
+  saveAnnotations,
+  saveFinalSnapshot,
+  getHistoryDir,
+  saveToHistory,
+  getPlanVersion,
+  getPlanVersionPath,
+  getVersionCount,
+  listVersions,
+  parseArchiveFilename,
+  listArchivedPlans,
+  readArchivedPlan,
+  type ArchivedPlan,
+} from "@plannotator/shared/storage";