@ilya-lesikov/pi-pi 0.1.0

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

@@ -0,0 +1,401 @@
+/**
+ * Annotate Server
+ *
+ * Provides a server for annotating arbitrary markdown files.
+ * Follows the same patterns as the review server but serves
+ * markdown content via /api/plan so the plan editor UI can
+ * render it without modifications.
+ *
+ * Environment variables:
+ *   PLANNOTATOR_REMOTE - Set to "1"/"true" for remote, "0"/"false" for local
+ *   PLANNOTATOR_PORT   - Fixed port to use (default: random locally, 19432 for remote)
+ */
+
+import { isRemoteSession, getServerHostname, getServerPort } from "./remote";
+import { getRepoInfo } from "./repo";
+import type { Origin } from "@plannotator/shared/agents";
+import { handleImage, handleUpload, handleServerReady, handleDraftSave, handleDraftLoad, handleDraftDelete, handleFavicon } from "./shared-handlers";
+import { handleDoc, handleDocExists, handleFileBrowserFiles, handleObsidianVaults, handleObsidianFiles, handleObsidianDoc } from "./reference-handlers";
+import { warmFileListCache } from "@plannotator/shared/resolve-file";
+import { contentHash, deleteDraft } from "./draft";
+import { createExternalAnnotationHandler } from "./external-annotations";
+import { saveConfig, detectGitUser, getServerConfig } from "./config";
+import { dirname, resolve as resolvePath } from "path";
+import { isWSL } from "./browser";
+import { AI_QUERY_ENDPOINT, createAIRuntime } from "./ai-runtime";
+import type { AIEndpoints } from "@plannotator/ai";
+
+// Re-export utilities
+export { isRemoteSession, getServerPort } from "./remote";
+export { openBrowser } from "./browser";
+export { handleServerReady as handleAnnotateServerReady } from "./shared-handlers";
+
+// --- Types ---
+
+export interface AnnotateServerOptions {
+  /** Markdown content of the file to annotate */
+  markdown: string;
+  /** Original file path (for display purposes) */
+  filePath: string;
+  /** HTML content to serve for the UI */
+  htmlContent: string;
+  /** Origin identifier for UI customization */
+  origin?: Origin;
+  /** UI mode: "annotate" for files, "annotate-last" for last agent message, "annotate-folder" for folders */
+  mode?: "annotate" | "annotate-last" | "annotate-folder";
+  /** Folder path when annotating a directory (used as projectRoot for file browser) */
+  folderPath?: string;
+  /**
+   * Recent assistant messages for `annotate-last` mode (newest-first). When
+   * provided with more than one entry, the editor renders a picker so users
+   * can choose which message to annotate; index 0 is the default selection
+   * and matches the legacy "last message" behavior.
+   */
+  recentMessages?: { messageId: string; text: string; timestamp?: string }[];
+  /** Whether URL sharing is enabled (default: true) */
+  sharingEnabled?: boolean;
+  /** Custom base URL for share links */
+  shareBaseUrl?: string;
+  /** Base URL of the paste service API for short URL sharing */
+  pasteApiUrl?: string;
+  /** Source attribution: original URL or filename (e.g. "https://..." or "index.html") */
+  sourceInfo?: string;
+  /** True when `markdown` was produced by Turndown/Jina (HTML or URL) —
+   *  feedback line numbers won't match the original source. */
+  sourceConverted?: boolean;
+  /** Enable review-gate UX: adds an Approve button alongside Close/Send Annotations */
+  gate?: boolean;
+  /** Raw HTML content for direct iframe rendering (--render-html mode) */
+  rawHtml?: string;
+  /** Render HTML as-is in an iframe instead of converting to markdown */
+  renderHtml?: boolean;
+  /** Session-level force-markdown preference (`--markdown`). Exposed in /api/plan so the
+   *  frontend appends `&convert=1` when navigating folder/linked HTML files. */
+  convertHtml?: boolean;
+  /** Called when server starts with the URL, remote status, and port */
+  onReady?: (url: string, isRemote: boolean, port: number) => void;
+}
+
+export interface AnnotateServerResult {
+  /** The port the server is running on */
+  port: number;
+  /** The full URL to access the server */
+  url: string;
+  /** Whether running in remote mode */
+  isRemote: boolean;
+  /** Wait for user feedback submission */
+  waitForDecision: () => Promise<{
+    feedback: string;
+    annotations: unknown[];
+    exit?: boolean;
+    approved?: boolean;
+    selectedMessageId?: string;
+    feedbackScope?: "message" | "messages";
+  }>;
+  /** Stop the server */
+  stop: () => void;
+}
+
+// --- Server Implementation ---
+
+const MAX_RETRIES = 5;
+const RETRY_DELAY_MS = 500;
+
+/**
+ * Start the Annotate server
+ *
+ * Handles:
+ * - Remote detection and port configuration
+ * - API routes (/api/plan with mode:"annotate", /api/feedback)
+ * - Port conflict retries
+ */
+export async function startAnnotateServer(
+  options: AnnotateServerOptions
+): Promise<AnnotateServerResult> {
+  // Side-channel pre-warm so /api/doc/exists POSTs land on warm cache.
+  void warmFileListCache(process.cwd(), "code");
+
+  const {
+    markdown,
+    filePath,
+    htmlContent,
+    origin,
+    mode = "annotate",
+    folderPath,
+    recentMessages,
+    sourceInfo,
+    sourceConverted,
+    sharingEnabled = true,
+    shareBaseUrl,
+    pasteApiUrl,
+    gate = false,
+    rawHtml,
+    renderHtml = false,
+    convertHtml = false,
+    onReady,
+  } = options;
+
+  const isRemote = isRemoteSession();
+  const configuredPort = getServerPort();
+  const wslFlag = await isWSL();
+  const gitUser = detectGitUser();
+  const draftSource =
+    mode === "annotate-folder" && folderPath
+      ? `folder:${resolvePath(folderPath)}`
+      : renderHtml && rawHtml ? rawHtml : markdown;
+  const draftKey = contentHash(draftSource);
+  const externalAnnotations = createExternalAnnotationHandler("plan");
+  const aiRuntime = await createAIRuntime();
+
+  // Detect repo info (cached for this session)
+  const repoInfo = await getRepoInfo();
+
+  // Decision promise
+  let resolveDecision: (result: {
+    feedback: string;
+    annotations: unknown[];
+    exit?: boolean;
+    approved?: boolean;
+    selectedMessageId?: string;
+    feedbackScope?: "message" | "messages";
+  }) => void;
+  const decisionPromise = new Promise<{
+    feedback: string;
+    annotations: unknown[];
+    exit?: boolean;
+    approved?: boolean;
+    selectedMessageId?: string;
+    feedbackScope?: "message" | "messages";
+  }>((resolve) => {
+    resolveDecision = resolve;
+  });
+
+  // Start server with retry logic
+  let server: ReturnType<typeof Bun.serve> | null = null;
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      server = Bun.serve({
+        hostname: getServerHostname(),
+        port: configuredPort,
+
+        async fetch(req, server) {
+          const url = new URL(req.url);
+
+          // API: Get plan content (reuse /api/plan so the plan editor UI works)
+          if (url.pathname === "/api/plan" && req.method === "GET") {
+            return Response.json({
+              plan: markdown,
+              origin,
+              mode,
+              filePath,
+              sourceInfo,
+              sourceConverted: sourceConverted ?? false,
+              gate,
+              renderAs: renderHtml && rawHtml ? 'html' as const : 'markdown' as const,
+              ...(renderHtml && rawHtml ? { rawHtml } : {}),
+              convertHtml,
+              sharingEnabled,
+              shareBaseUrl,
+              pasteApiUrl,
+              repoInfo,
+              projectRoot: folderPath || process.cwd(),
+              isWSL: wslFlag,
+              serverConfig: getServerConfig(gitUser),
+              ...(recentMessages ? { recentMessages } : {}),
+            });
+          }
+
+          // API: Update user config (write-back to ~/.plannotator/config.json)
+          if (url.pathname === "/api/config" && req.method === "POST") {
+            try {
+              const body = (await req.json()) as { displayName?: string; diffOptions?: Record<string, unknown>; conventionalComments?: boolean; conventionalLabels?: unknown[] | null };
+              const toSave: Record<string, unknown> = {};
+              if (body.displayName !== undefined) toSave.displayName = body.displayName;
+              if (body.diffOptions !== undefined) toSave.diffOptions = body.diffOptions;
+              if (body.conventionalComments !== undefined) toSave.conventionalComments = body.conventionalComments;
+              if (body.conventionalLabels !== undefined) toSave.conventionalLabels = body.conventionalLabels;
+              if (Object.keys(toSave).length > 0) saveConfig(toSave as Parameters<typeof saveConfig>[0]);
+              return Response.json({ ok: true });
+            } catch {
+              return Response.json({ error: "Invalid request" }, { status: 400 });
+            }
+          }
+
+          // API: Serve images (local paths or temp uploads)
+          if (url.pathname === "/api/image") {
+            return handleImage(req);
+          }
+
+          // API: Serve a linked markdown document
+          // Inject source file's directory as base for relative path resolution.
+          // Skip base injection for URL annotations — there's no local directory to resolve against.
+          if (url.pathname === "/api/doc" && req.method === "GET") {
+            if (!url.searchParams.has("base") && !/^https?:\/\//i.test(filePath)) {
+              const docUrl = new URL(req.url);
+              docUrl.searchParams.set("base", dirname(filePath));
+              return handleDoc(new Request(docUrl.toString()));
+            }
+            return handleDoc(req);
+          }
+
+          // API: Batch existence check for code-file paths the renderer detected
+          if (url.pathname === "/api/doc/exists" && req.method === "POST") {
+            return handleDocExists(req);
+          }
+
+          // API: Detect Obsidian vaults
+          if (url.pathname === "/api/obsidian/vaults") {
+            return handleObsidianVaults();
+          }
+
+          // API: List Obsidian vault files as a tree
+          if (url.pathname === "/api/reference/obsidian/files" && req.method === "GET") {
+            return handleObsidianFiles(req);
+          }
+
+          // API: Read an Obsidian vault document
+          if (url.pathname === "/api/reference/obsidian/doc" && req.method === "GET") {
+            return handleObsidianDoc(req);
+          }
+
+          // API: List markdown files in a directory as a tree
+          if (url.pathname === "/api/reference/files" && req.method === "GET") {
+            return handleFileBrowserFiles(req);
+          }
+
+          // API: Upload image -> save to temp -> return path
+          if (url.pathname === "/api/upload" && req.method === "POST") {
+            return handleUpload(req);
+          }
+
+          // API: Annotation draft persistence
+          if (url.pathname === "/api/draft") {
+            if (req.method === "POST") return handleDraftSave(req, draftKey);
+            if (req.method === "DELETE") return handleDraftDelete(draftKey);
+            return handleDraftLoad(draftKey);
+          }
+
+          // API: External annotations (SSE-based, for any external tool)
+          const externalResponse = await externalAnnotations.handle(req, url, {
+            disableIdleTimeout: () => server.timeout(req, 0),
+          });
+          if (externalResponse) return externalResponse;
+
+          if (url.pathname.startsWith("/api/ai/")) {
+            const handler = aiRuntime.endpoints[url.pathname as keyof AIEndpoints];
+            if (handler) {
+              if (url.pathname === AI_QUERY_ENDPOINT) {
+                server.timeout(req, 0);
+              }
+              return handler(req);
+            }
+            return Response.json({ error: "Not found" }, { status: 404 });
+          }
+
+          // API: Exit annotation session without feedback
+          if (url.pathname === "/api/exit" && req.method === "POST") {
+            deleteDraft(draftKey);
+            resolveDecision({ feedback: "", annotations: [], exit: true });
+            return Response.json({ ok: true });
+          }
+
+          // API: Approve the annotation session (review-gate UX)
+          if (url.pathname === "/api/approve" && req.method === "POST") {
+            deleteDraft(draftKey);
+            resolveDecision({ feedback: "", annotations: [], approved: true });
+            return Response.json({ ok: true });
+          }
+
+          // API: Submit annotation feedback
+          if (url.pathname === "/api/feedback" && req.method === "POST") {
+            try {
+              const body = (await req.json()) as {
+                feedback: string;
+                annotations: unknown[];
+                selectedMessageId?: string;
+                feedbackScope?: "message" | "messages";
+              };
+
+              deleteDraft(draftKey);
+              resolveDecision({
+                feedback: body.feedback || "",
+                annotations: body.annotations || [],
+                selectedMessageId: body.selectedMessageId,
+                feedbackScope: body.feedbackScope,
+              });
+
+              return Response.json({ ok: true });
+            } catch (err) {
+              const message =
+                err instanceof Error
+                  ? err.message
+                  : "Failed to process feedback";
+              return Response.json({ error: message }, { status: 500 });
+            }
+          }
+
+          // Favicon
+          if (url.pathname === "/favicon.svg") return handleFavicon();
+
+          // Serve embedded HTML for all other routes (SPA)
+          return new Response(htmlContent, {
+            headers: { "Content-Type": "text/html" },
+          });
+        },
+
+        error(err) {
+          console.error("[plannotator] Server error:", err);
+          return new Response(
+            `Internal Server Error: ${err instanceof Error ? err.message : String(err)}`,
+            { status: 500, headers: { "Content-Type": "text/plain" } },
+          );
+        },
+      });
+
+      break; // Success, exit retry loop
+    } catch (err: unknown) {
+      const isAddressInUse =
+        err instanceof Error && err.message.includes("EADDRINUSE");
+
+      if (isAddressInUse && attempt < MAX_RETRIES) {
+        await Bun.sleep(RETRY_DELAY_MS);
+        continue;
+      }
+
+      if (isAddressInUse) {
+        const hint = isRemote
+          ? " (set PLANNOTATOR_PORT to use different port)"
+          : "";
+        throw new Error(
+          `Port ${configuredPort} in use after ${MAX_RETRIES} retries${hint}`
+        );
+      }
+
+      throw err;
+    }
+  }
+
+  if (!server) {
+    throw new Error("Failed to start server");
+  }
+
+  const port = server.port!;
+  const serverUrl = `http://localhost:${port}`;
+
+  // Notify caller that server is ready
+  if (onReady) {
+    onReady(serverUrl, isRemote, port);
+  }
+
+  return {
+    port,
+    url: serverUrl,
+    isRemote,
+    waitForDecision: () => decisionPromise,
+    stop: () => {
+      aiRuntime.dispose();
+      server.stop();
+    },
+  };
+}

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

@@ -0,0 +1,87 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { isNoOpBrowserSentinel, shouldTryRemoteBrowserFallback } from "./browser";
+
+const savedEnv: Record<string, string | undefined> = {};
+const envKeys = ["PLANNOTATOR_BROWSER", "BROWSER"];
+
+function clearEnv() {
+  for (const key of envKeys) {
+    savedEnv[key] = process.env[key];
+    delete process.env[key];
+  }
+}
+
+afterEach(() => {
+  for (const key of envKeys) {
+    if (savedEnv[key] !== undefined) {
+      process.env[key] = savedEnv[key];
+    } else {
+      delete process.env[key];
+    }
+  }
+});
+
+describe("shouldTryRemoteBrowserFallback", () => {
+  test("false for local sessions", () => {
+    clearEnv();
+    expect(shouldTryRemoteBrowserFallback(false)).toBe(false);
+  });
+
+  test("true for remote sessions without browser handlers", () => {
+    clearEnv();
+    expect(shouldTryRemoteBrowserFallback(true)).toBe(true);
+  });
+
+  test("false for remote sessions with BROWSER configured", () => {
+    clearEnv();
+    process.env.BROWSER = "/usr/bin/browser";
+    expect(shouldTryRemoteBrowserFallback(true)).toBe(false);
+  });
+
+  test("false for remote sessions with PLANNOTATOR_BROWSER configured", () => {
+    clearEnv();
+    process.env.PLANNOTATOR_BROWSER = "/usr/bin/browser";
+    expect(shouldTryRemoteBrowserFallback(true)).toBe(false);
+  });
+
+  test("true for remote sessions when BROWSER is a no-op sentinel", () => {
+    clearEnv();
+    process.env.BROWSER = "true";
+    expect(shouldTryRemoteBrowserFallback(true)).toBe(true);
+  });
+
+  test("true for remote sessions when PLANNOTATOR_BROWSER is a no-op sentinel", () => {
+    clearEnv();
+    process.env.PLANNOTATOR_BROWSER = "none";
+    expect(shouldTryRemoteBrowserFallback(true)).toBe(true);
+  });
+});
+
+describe("isNoOpBrowserSentinel", () => {
+  test("returns false for undefined and empty values", () => {
+    expect(isNoOpBrowserSentinel(undefined)).toBe(false);
+    expect(isNoOpBrowserSentinel("")).toBe(false);
+  });
+
+  test("recognizes no-op values case- and whitespace-insensitively", () => {
+    for (const value of [
+      "true",
+      "false",
+      "none",
+      ":",
+      "0",
+      "1",
+      "TRUE",
+      "  none  ",
+    ]) {
+      expect(isNoOpBrowserSentinel(value)).toBe(true);
+    }
+  });
+
+  test("does not flag real browser handlers or explicit command paths", () => {
+    expect(isNoOpBrowserSentinel("/usr/bin/firefox")).toBe(false);
+    expect(isNoOpBrowserSentinel("Google Chrome")).toBe(false);
+    expect(isNoOpBrowserSentinel("open")).toBe(false);
+    expect(isNoOpBrowserSentinel("/usr/bin/true")).toBe(false);
+  });
+});