claude-plan-viewer 1.1.1 → 1.4.0

package/index.ts

@@ -1,23 +1,148 @@
 #!/usr/bin/env bun
-import { readdir, stat } from "node:fs/promises";
+import { readdir, stat, watch } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import index from "./index.html";
-import prismBundlePath from "./prism.bundle.js" with { type: "file" };
-
-const PLANS_DIR = join(homedir(), ".claude", "plans");
-const PROJECTS_DIR = join(homedir(), ".claude", "projects");
-
-// Parse --port from command line arguments (undefined = auto-assign)
-function getRequestedPort(): number | undefined {
-  const args = process.argv;
-  const portIndex = args.indexOf("--port");
-  const portArg = args[portIndex + 1];
-  if (portIndex !== -1 && portArg) {
-    const port = parseInt(portArg, 10);
-    if (!isNaN(port)) return port;
+import index from "./src/index.html";
+import apiDocs from "./src/api-docs.html";
+import pkg from "./package.json";
+import openapi from "./openapi.json";
+
+// Resolved at startup based on --claude-dir flag or CLAUDE_DIR env var
+let PLANS_DIR: string;
+let PROJECTS_DIR: string;
+
+function resolveClaudeDir(cliArg?: string): string {
+  return cliArg || process.env.CLAUDE_DIR || join(homedir(), ".claude");
+}
+
+function initializeDirectories(claudeDir: string): void {
+  PLANS_DIR = join(claudeDir, "plans");
+  PROJECTS_DIR = join(claudeDir, "projects");
+}
+
+interface CliArgs {
+  port?: number;
+  json?: boolean;
+  output?: string;
+  fromFile?: string;
+  claudeDir?: string;
+  version?: boolean;
+  help?: boolean;
+}
+
+function parseCliArgs(): CliArgs {
+  const args: CliArgs = {};
+  const argv = process.argv.slice(2);
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const nextArg = argv[i + 1];
+
+    if (arg === "--port" || arg === "-p") {
+      if (nextArg && !nextArg.startsWith("-")) {
+        args.port = parseInt(nextArg, 10);
+        i++;
+      }
+    } else if (arg === "--json" || arg === "-j") {
+      args.json = true;
+    } else if (arg === "--output" || arg === "-o") {
+      if (nextArg && !nextArg.startsWith("-")) {
+        args.output = nextArg;
+        i++;
+      }
+    } else if (arg === "--from-file" || arg === "-f") {
+      if (nextArg && !nextArg.startsWith("-")) {
+        args.fromFile = nextArg;
+        i++;
+      }
+    } else if (arg === "--claude-dir" || arg === "-c") {
+      if (nextArg && !nextArg.startsWith("-")) {
+        args.claudeDir = nextArg;
+        i++;
+      }
+    } else if (arg === "--version" || arg === "-v") {
+      args.version = true;
+    } else if (arg === "--help" || arg === "-h") {
+      args.help = true;
+    }
+  }
+
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`
+claude-plan-viewer - Browse and search Claude Code plans
+
+Usage: claude-plan-viewer [options]
+
+Options:
+  -p, --port <number>       Port to start server on (default: 3000)
+  -c, --claude-dir <path>   Path to .claude directory (default: ~/.claude)
+                            Can also be set via CLAUDE_DIR environment variable
+  -j, --json                Export all plans as JSON and exit
+  -o, --output <file>       Output file for JSON export (stdout if omitted)
+  -f, --from-file <file>    Load plans from JSON file instead of ~/.claude/plans
+  -v, --version             Show version number
+  -h, --help                Show this help message
+
+Examples:
+  claude-plan-viewer                        Start viewer on default port
+  claude-plan-viewer -p 8080                Start on port 8080
+  claude-plan-viewer -c /path/to/.claude    Use custom .claude directory
+  claude-plan-viewer -j -o plans.json       Export plans to file
+  claude-plan-viewer -f plans.json          Load plans from exported file
+`);
+}
+
+async function exportPlansAsJson(outputPath?: string): Promise<void> {
+  const plans = await loadPlans();
+
+  const plansWithContent = plans.map((plan) => ({
+    ...plan,
+    content: contentCache.get(plan.filename) || "",
+  }));
+
+  const jsonOutput = JSON.stringify(plansWithContent, null, 2);
+
+  if (outputPath) {
+    await Bun.write(outputPath, jsonOutput);
+    console.log(`Exported ${plans.length} plans to ${outputPath}`);
+  } else {
+    console.log(jsonOutput);
+  }
+}
+
+async function loadPlansFromFile(filepath: string): Promise<PlanMetadata[]> {
+  const file = Bun.file(filepath);
+  const exists = await file.exists();
+
+  if (!exists) {
+    console.error(`File not found: ${filepath}`);
+    process.exit(1);
+  }
+
+  const data = await file.json();
+  const plans: PlanMetadata[] = [];
+
+  for (const plan of data) {
+    contentCache.set(plan.filename, plan.content || "");
+    plans.push({
+      filename: plan.filename,
+      filepath: plan.filepath,
+      title: plan.title,
+      size: plan.size,
+      modified: plan.modified,
+      created: plan.created,
+      lineCount: plan.lineCount,
+      wordCount: plan.wordCount,
+      project: plan.project,
+      sessionId: plan.sessionId,
+    });
   }
-  return undefined;
+
+  cachedPlans = plans;
+  return plans;
 }
 
 // Find an available port starting from the requested port
@@ -37,7 +162,9 @@ async function findAvailablePort(startPort: number = 3000): Promise<number> {
       port++;
     }
   }
-  throw new Error(`No available port found in range ${startPort}-${startPort + maxAttempts}`);
+  throw new Error(
+    `No available port found in range ${startPort}-${startPort + maxAttempts}`,
+  );
 }
 
 // Cross-platform open file in default editor
@@ -52,17 +179,21 @@ async function openInEditor(filepath: string): Promise<void> {
   }
 }
 
-interface Plan {
+interface PlanMetadata {
   filename: string;
   filepath: string;
   title: string;
-  content: string;
   size: number;
   modified: string;
   created: string;
   lineCount: number;
   wordCount: number;
   project: string | null;
+  sessionId: string | null;
+}
+
+interface Plan extends PlanMetadata {
+  content: string;
 }
 
 // Extract project name from a full path (cross-platform)
@@ -73,7 +204,9 @@ function extractProjectName(cwd: string): string {
   // Normalize: handle both / and \ separators
   const normalized = cwd.replace(/\\/g, "/");
   // Remove trailing slash
-  const trimmed = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+  const trimmed = normalized.endsWith("/")
+    ? normalized.slice(0, -1)
+    : normalized;
   // Get last segment
   const lastSlash = trimmed.lastIndexOf("/");
   return lastSlash === -1 ? trimmed : trimmed.slice(lastSlash + 1);
@@ -83,70 +216,123 @@ function extractProjectName(cwd: string): string {
 function extractCwdFromJsonl(content: string): string | null {
   if (!content) return null;
   const match = content.match(/"cwd":"([^"]+)"/);
-  if (!match) return null;
+  if (!match || !match[1]) return null;
   // Unescape JSON string (convert \\\\ to \\)
   return match[1].replace(/\\\\/g, "\\");
 }
 
-// Extract unique slugs from JSONL content
+// Extract slug -> sessionId mapping from JSONL content
+// Each line in JSONL may contain both "slug" and "sessionId" fields
+function extractSlugSessionMap(content: string): Map<string, string> {
+  if (!content) return new Map();
+  const slugSessionMap = new Map<string, string>();
+
+  // Process each line to find slug and sessionId pairs
+  const lines = content.split("\n");
+  for (const line of lines) {
+    if (!line.trim()) continue;
+
+    const slugMatch = line.match(/"slug":"([\w-]+)"/);
+    const sessionMatch = line.match(/"sessionId":"([^"]+)"/);
+
+    if (slugMatch && slugMatch[1] && sessionMatch && sessionMatch[1]) {
+      slugSessionMap.set(slugMatch[1], sessionMatch[1]);
+    }
+  }
+
+  return slugSessionMap;
+}
+
+// Extract unique slugs from JSONL content (for backwards compatibility)
 function extractSlugsFromJsonl(content: string): string[] {
   if (!content) return [];
   const slugs = new Set<string>();
   const matches = content.matchAll(/"slug":"([\w-]+)"/g);
   for (const match of matches) {
-    slugs.add(match[1]);
+    if (match[1]) {
+      slugs.add(match[1]);
+    }
   }
   return Array.from(slugs);
 }
 
+interface SlugMetadata {
+  project: string;
+  sessionId: string | null;
+}
+
 interface ProjectMapping {
-  [slug: string]: string; // plan slug -> project name
+  [slug: string]: SlugMetadata;
 }
 
-// Build a mapping of plan slugs to project names by scanning Claude Code's project metadata
+// Build a mapping of plan slugs to project names and session IDs by scanning Claude Code's project metadata
 async function buildProjectMapping(): Promise<ProjectMapping> {
   const mapping: ProjectMapping = {};
 
   try {
     const projectDirs = await readdir(PROJECTS_DIR);
 
-    for (const dir of projectDirs) {
-      const dirPath = join(PROJECTS_DIR, dir);
-      const dirStats = await stat(dirPath);
-      if (!dirStats.isDirectory()) continue;
-
-      // Find JSONL files and extract cwd + slugs
-      const files = await readdir(dirPath);
-      const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
-
-      let projectName: string | null = null;
-      const allSlugs: string[] = [];
-
-      for (const file of jsonlFiles) {
+    // Process all project directories in parallel
+    const results = await Promise.all(
+      projectDirs.map(async (dir) => {
+        const dirPath = join(PROJECTS_DIR, dir);
         try {
-          const content = await Bun.file(join(dirPath, file)).text();
+          const dirStats = await stat(dirPath);
+          if (!dirStats.isDirectory()) return null;
+
+          // Find JSONL files
+          const files = await readdir(dirPath);
+          const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
+          if (jsonlFiles.length === 0) return null;
+
+          // Read all JSONL files in parallel
+          const fileContents = await Promise.all(
+            jsonlFiles.map(async (file) => {
+              try {
+                return await Bun.file(join(dirPath, file)).text();
+              } catch {
+                return null;
+              }
+            })
+          );
+
+          let projectName: string | null = null;
+          const slugSessionMap = new Map<string, string>();
+
+          // Process file contents
+          for (const content of fileContents) {
+            if (!content) continue;
+
+            // Get project name from cwd (only need to find it once)
+            if (!projectName) {
+              const cwd = extractCwdFromJsonl(content);
+              if (cwd) {
+                projectName = extractProjectName(cwd);
+              }
+            }
 
-          // Get project name from cwd (only need to find it once)
-          if (!projectName) {
-            const cwd = extractCwdFromJsonl(content);
-            if (cwd) {
-              projectName = extractProjectName(cwd);
+            // Collect slug -> sessionId mappings
+            const fileSlugSessions = extractSlugSessionMap(content);
+            for (const [slug, sessionId] of fileSlugSessions) {
+              slugSessionMap.set(slug, sessionId);
             }
           }
 
-          // Collect all slugs
-          const slugs = extractSlugsFromJsonl(content);
-          allSlugs.push(...slugs);
+          return { projectName, slugSessionMap };
         } catch {
-          // Skip files that can't be read
-        }
-      }
-
-      // Map all slugs to this project
-      if (projectName) {
-        for (const slug of allSlugs) {
-          mapping[slug] = projectName;
+          return null;
         }
+      })
+    );
+
+    // Merge results into mapping
+    for (const result of results) {
+      if (!result?.projectName) continue;
+      for (const [slug, sessionId] of result.slugSessionMap) {
+        mapping[slug] = {
+          project: result.projectName,
+          sessionId: sessionId,
+        };
       }
     }
   } catch {
@@ -156,9 +342,19 @@ async function buildProjectMapping(): Promise<ProjectMapping> {
   return mapping;
 }
 
-async function loadPlans(): Promise<Plan[]> {
-  // Build project mapping from Claude Code metadata
-  const projectMapping = await buildProjectMapping();
+let cachedPlans: PlanMetadata[] | null = null;
+let cachedProjectMapping: ProjectMapping | null = null;
+const contentCache = new Map<string, string>();
+
+async function loadPlans(): Promise<PlanMetadata[]> {
+  // Build or use cached project mapping
+  let projectMapping: ProjectMapping;
+  if (!cachedProjectMapping) {
+    projectMapping = await buildProjectMapping();
+    cachedProjectMapping = projectMapping;
+  } else {
+    projectMapping = cachedProjectMapping;
+  }
 
   const files = await readdir(PLANS_DIR);
   const mdFiles = files.filter((f) => f.endsWith(".md"));
@@ -167,10 +363,8 @@ async function loadPlans(): Promise<Plan[]> {
     mdFiles.map(async (filename) => {
       const filepath = join(PLANS_DIR, filename);
       const file = Bun.file(filepath);
-      const [content, stats] = await Promise.all([
-        file.text(),
-        stat(filepath),
-      ]);
+
+      const [content, stats] = await Promise.all([file.text(), stat(filepath)]);
 
       const titleMatch = content.match(/^#\s+(.+)$/m);
       const title = titleMatch?.[1]
@@ -179,42 +373,147 @@ async function loadPlans(): Promise<Plan[]> {
 
       // Look up project from metadata using plan slug (filename without .md)
       const slug = filename.replace(".md", "");
+      const lineCount = content.split("\n").length;
+      const wordCount = content.split(/\s+/).filter(Boolean).length;
+
+      const metadata = projectMapping[slug];
+      // Cache content separately for search and lazy loading
+      contentCache.set(filename, content);
 
       return {
         filename,
         filepath,
         title,
-        content,
         size: stats.size,
         modified: stats.mtime.toISOString(),
         created: stats.birthtime.toISOString(),
-        lineCount: content.split("\n").length,
-        wordCount: content.split(/\s+/).filter(Boolean).length,
-        project: projectMapping[slug] || null,
+        lineCount,
+        wordCount,
+        project: metadata?.project || null,
+        sessionId: metadata?.sessionId || null,
       };
-    })
+    }),
   );
 
-  return plans.sort(
-    (a, b) => new Date(b.modified).getTime() - new Date(a.modified).getTime()
-  );
+  cachedPlans = plans;
+  return plans;
+}
+
+// Granular cache invalidation
+function invalidatePlansCache() {
+  cachedPlans = null;
+}
+
+function invalidateProjectMapping() {
+  cachedProjectMapping = null;
+}
+
+function invalidateContentCache(filename?: string) {
+  if (filename) {
+    contentCache.delete(filename);
+  } else {
+    contentCache.clear();
+  }
+}
+
+function invalidateAllCaches() {
+  invalidatePlansCache();
+  invalidateProjectMapping();
+  invalidateContentCache();
+}
+
+// Watch plans directory for changes and invalidate cache
+async function watchPlansDirectory() {
+  try {
+    const watcher = watch(PLANS_DIR);
+    for await (const event of watcher) {
+      if (event.filename?.endsWith(".md")) {
+        // Only invalidate plans metadata and the specific file's content
+        // Project mapping rarely changes, keep it cached
+        invalidatePlansCache();
+        invalidateContentCache(event.filename);
+      }
+    }
+  } catch {
+    // Directory may not exist or watching may not be supported
+  }
 }
 
 // Main server startup
 async function startServer() {
-  const requestedPort = getRequestedPort();
-  const port = await findAvailablePort(requestedPort ?? 3000);
+  const args = parseCliArgs();
+  const port = await findAvailablePort(args.port ?? 3000);
 
   const server = Bun.serve({
     port,
-    static: {
-      "/prism.bundle.js": Bun.file(prismBundlePath),
-    },
     routes: {
       "/": index,
-      "/api/plans": async () => {
-        const plans = await loadPlans();
-        return Response.json(plans);
+      "/api": () => Response.redirect("/api/", 301),
+      "/api/": apiDocs,
+      "/api/openapi.json": () => Response.json(openapi),
+      "/api/projects": async () => {
+        // Lazy load cache on first request
+        if (!cachedPlans) {
+          await loadPlans();
+        }
+
+        const plans = cachedPlans || [];
+        const projects = [
+          ...new Set(plans.map((p) => p.project).filter(Boolean)),
+        ] as string[];
+        projects.sort((a, b) => a.localeCompare(b));
+
+        return Response.json({ projects });
+      },
+      "/api/plans": async (req) => {
+        // Lazy load cache on first request
+        if (!cachedPlans) {
+          await loadPlans();
+        }
+
+        const plans = cachedPlans || [];
+
+        // Strip content from response - will be fetched separately via /api/plans/{id}/content
+        const plansWithoutContent = plans.map((p) => ({
+          filename: p.filename,
+          filepath: p.filepath,
+          title: p.title,
+          size: p.size,
+          modified: p.modified,
+          created: p.created,
+          lineCount: p.lineCount,
+          wordCount: p.wordCount,
+          project: p.project,
+          sessionId: p.sessionId,
+        }));
+
+        return Response.json({
+          plans: plansWithoutContent,
+        });
+      },
+      "/api/plans/:filename/content": async (req) => {
+        // Lazy load cache on first request
+        if (!cachedPlans) {
+          await loadPlans();
+        }
+
+        const filename = req.params.filename as string;
+        const content = contentCache.get(filename);
+
+        if (content === undefined) {
+          return new Response("Plan not found", { status: 404 });
+        }
+
+        return Response.json({ content });
+      },
+      "/api/refresh": {
+        POST: async () => {
+          const before = cachedPlans?.length ?? 0;
+          invalidateAllCaches();
+          await loadPlans();
+          const after = cachedPlans?.length ?? 0;
+          return Response.json({ success: true, before, after });
+        },
       },
       "/api/open": {
         POST: async (req) => {
@@ -231,10 +530,13 @@ async function startServer() {
         },
       },
     },
-    development: process.env.NODE_ENV !== "production" ? {
-      hmr: true,
-      console: true,
-    } : undefined,
+    development:
+      process.env.NODE_ENV !== "production"
+        ? {
+            hmr: true,
+            console: true,
+          }
+        : undefined,
   });
 
   return server;
@@ -253,14 +555,62 @@ const c = {
 
 // Main entry point
 (async () => {
+  const args = parseCliArgs();
+
+  if (args.version) {
+    console.log(`claude-plan-viewer v${pkg.version}`);
+    process.exit(0);
+  }
+
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Initialize directory paths based on --claude-dir flag or CLAUDE_DIR env var
+  const claudeDir = resolveClaudeDir(args.claudeDir);
+  initializeDirectories(claudeDir);
+
+  if (args.json) {
+    await exportPlansAsJson(args.output);
+    process.exit(0);
+  }
+
+  // Pre-load plans from file if --from-file is provided
+  let planCount: number;
+  let sourceDisplay: string;
+
+  if (args.fromFile) {
+    const plans = await loadPlansFromFile(args.fromFile);
+    planCount = plans.length;
+    sourceDisplay = args.fromFile;
+  } else {
+    planCount = (await readdir(PLANS_DIR)).filter((f) =>
+      f.endsWith(".md"),
+    ).length;
+    sourceDisplay = PLANS_DIR;
+    // Only watch for file changes when not using --from-file
+    watchPlansDirectory();
+  }
+
   const server = await startServer();
-  const planCount = (await readdir(PLANS_DIR)).filter(f => f.endsWith('.md')).length;
+
   console.log();
-  console.log(`${c.bold}${c.magenta}  📋 Plans Viewer${c.reset}`);
+  console.log(`${c.bold}${c.magenta}  📋 Claude Plan Viewer${c.reset}`);
   console.log(`${c.dim}  ─────────────────────────────${c.reset}`);
   console.log(`${c.green}  ✓${c.reset} Server running`);
+  if (!args.fromFile) {
+    console.log(`${c.green}  ✓${c.reset} Watching for file changes`);
+  }
   console.log();
-  console.log(`${c.dim}  Local:${c.reset}   ${c.cyan}${c.bold}http://localhost:${server.port}${c.reset}`);
-  console.log(`${c.dim}  Plans:${c.reset}   ${c.yellow}${planCount} plans${c.reset} in ${c.dim}${PLANS_DIR}${c.reset}`);
+  console.log(
+    `${c.dim}  Local:${c.reset}   ${c.cyan}${c.bold}http://localhost:${server.port}${c.reset}`,
+  );
+  console.log(
+    `${c.dim}  API:${c.reset}     ${c.cyan}http://localhost:${server.port}/api/${c.reset}`,
+  );
+  console.log(
+    `${c.dim}  Plans:${c.reset}   ${c.yellow}${planCount} plans${c.reset} in ${c.dim}${sourceDisplay}${c.reset}`,
+  );
   console.log();
 })();