@peaske7/readit 0.2.1 → 0.3.0-rc.1

package/docs/plans/2026-03-13-client-mode-design.md

@@ -1,86 +0,0 @@
-# Client Mode: `readit open`
-
-## Problem
-
-readit starts a long-running server per invocation. When used as a Claude Code PostToolUse hook, every Write/Edit on a `.md` file would spawn a new server instance. We need a way to send files to an already-running server.
-
-## Design
-
-### Overview
-
-Add a `readit open <files...>` CLI command that hot-adds files to a running readit server via HTTP, or starts a new server if none exists. Uses a PID file for server discovery and the existing SSE infrastructure for browser notifications.
-
-### 1. PID File (`~/.readit/server.json`)
-
-**On server start** (in `startServer`):
-```json
-{ "port": 4567, "pid": 12345 }
-```
-
-**On shutdown** (SIGINT handler): delete the file.
-
-**Client discovery:**
-1. Read `~/.readit/server.json`
-2. Verify PID is alive (`process.kill(pid, 0)`)
-3. Confirm via `GET /api/health`
-4. Any failure → treat as no server running
-
-### 2. Server Endpoint: `POST /api/files`
-
-Request body: `{ "path": "/absolute/path/to/file.md" }`
-
-Behavior:
-- **File already loaded** → re-read from disk, update `fileMap` content, broadcast SSE `{ type: "update", path }`
-- **New file** → validate type, read content, add to `fileMap` + `fileOrder`, set up file watcher, broadcast SSE `{ type: "file-added", path, fileName, fileType }`
-
-Response: `200 { path, fileName, type }`
-
-### 3. Frontend: Handle `file-added` SSE Event
-
-The Zustand store's SSE listener handles a new event type:
-- `file-added` → add document to store, render new tab (lazy content fetch via existing pattern)
-
-### 4. CLI Command: `readit open`
-
-```
-readit open <files...>          # Add files to running server or start new one
-```
-
-Logic:
-1. Resolve and validate file paths (must exist, must be supported type)
-2. Discover running server via PID file + health check
-3. If server found → `POST /api/files` for each file
-4. If no server → start server in foreground with the given files (same as default command)
-
-### 5. Hook Configuration
-
-```json
-{
-  "PostToolUse": [
-    {
-      "matcher": "Write|Edit",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "bash -c 'FILE=$(cat | jq -r \".tool_input.file_path\"); if [[ \"$FILE\" == *.md ]]; then bunx readit open \"$FILE\"; fi; exit 0'"
-        }
-      ]
-    }
-  ]
-}
-```
-
-## Files to Modify
-
-- `src/server/index.ts` — PID file write/cleanup, `POST /api/files` endpoint, file watcher setup for hot-added files
-- `src/cli/index.ts` — new `open` subcommand with server discovery logic
-- Frontend store — handle `file-added` SSE event type
-
-## Verification
-
-1. Start `readit test.md`
-2. Run `readit open other.md` in another terminal
-3. Confirm new tab appears in browser with `other.md`
-4. Edit `other.md` on disk → confirm live reload works
-5. Kill server, run `readit open test.md` → confirm new server starts
-6. Run `readit open test.md` again (already loaded) → confirm content refreshes without duplicate tab

package/docs/plans/2026-03-13-client-mode-plan.md

@@ -1,605 +0,0 @@
-# Client Mode (`readit open`) Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Add a `readit open` CLI command that hot-adds files to a running readit server, or starts a new one if none exists.
-
-**Architecture:** PID file (`~/.readit/server.json`) for server discovery. New `POST /api/files` endpoint on the existing Bun.serve() for hot-adding files. Existing SSE infrastructure broadcasts `file-added` events to the frontend. Extract `getFileType` to shared lib to avoid duplication.
-
-**Tech Stack:** Bun, Commander.js, existing SSE, Zustand store
-
----
-
-### Task 1: Extract `getFileType` to shared lib
-
-`getFileType` is currently defined in `src/cli/index.ts` and will be needed in both CLI and server code.
-
-**Files:**
-- Modify: `src/lib/utils.ts`
-- Modify: `src/cli/index.ts`
-
-**Step 1: Add `getFileType` to `src/lib/utils.ts`**
-
-```ts
-import type { DocumentType } from "../types";
-
-export function getFileType(filePath: string): DocumentType | null {
-  if (filePath.endsWith(".md") || filePath.endsWith(".markdown")) {
-    return "markdown";
-  }
-  if (filePath.endsWith(".html") || filePath.endsWith(".htm")) {
-    return "html";
-  }
-  return null;
-}
-```
-
-**Step 2: Update `src/cli/index.ts` to import from shared lib**
-
-Replace the local `getFileType` function with:
-```ts
-import { getFileType } from "../lib/utils.js";
-```
-
-Remove the local `getFileType` function definition (lines 22-30).
-
-**Step 3: Verify build passes**
-
-Run: `bun run typecheck`
-Expected: No errors
-
-**Step 4: Commit**
-
-```bash
-git add src/lib/utils.ts src/cli/index.ts
-git commit -m "refactor: extract getFileType to shared lib"
-```
-
----
-
-### Task 2: Add PID file write/cleanup to server
-
-**Files:**
-- Modify: `src/server/index.ts` — write `~/.readit/server.json` on start, delete on shutdown
-- Modify: `src/cli/index.ts` — clean up PID file in SIGINT handler
-
-**Step 1: Add PID file helpers to `src/server/index.ts`**
-
-Add near the top of the file, after the existing helpers:
-
-```ts
-const SERVER_INFO_PATH = path.join(os.homedir(), ".readit", "server.json");
-
-async function writeServerInfo(port: number): Promise<void> {
-  await fs.mkdir(path.dirname(SERVER_INFO_PATH), { recursive: true });
-  await fs.writeFile(
-    SERVER_INFO_PATH,
-    JSON.stringify({ port, pid: process.pid }),
-    "utf-8",
-  );
-}
-
-async function removeServerInfo(): Promise<void> {
-  try {
-    await fs.unlink(SERVER_INFO_PATH);
-  } catch (err) {
-    if (!isErrnoException(err) || err.code !== "ENOENT") {
-      console.error("Failed to remove server info:", err);
-    }
-  }
-}
-```
-
-**Step 2: Call `writeServerInfo` at end of `startServer`**
-
-In the `startServer` function, after the server is successfully created, before the `return`:
-
-```ts
-await writeServerInfo(actualPort);
-```
-
-**Step 3: Export `removeServerInfo` and `SERVER_INFO_PATH`**
-
-Export both so the CLI can use them in its SIGINT handler:
-
-```ts
-export { SERVER_INFO_PATH, removeServerInfo };
-```
-
-**Step 4: Update SIGINT handler in `src/cli/index.ts`**
-
-```ts
-import { removeServerInfo } from "../server/index.js";
-
-// In the SIGINT handler:
-process.on("SIGINT", async () => {
-  console.log("\n\nShutting down...");
-  server.stop();
-  await removeServerInfo();
-  process.exit(0);
-});
-```
-
-**Step 5: Verify build passes**
-
-Run: `bun run typecheck`
-Expected: No errors
-
-**Step 6: Commit**
-
-```bash
-git add src/server/index.ts src/cli/index.ts
-git commit -m "feat: write/cleanup PID file on server start/stop"
-```
-
----
-
-### Task 3: Add `POST /api/files` endpoint to server
-
-This endpoint hot-adds or refreshes files in a running server.
-
-**Files:**
-- Modify: `src/server/index.ts`
-
-**Step 1: Extract watcher setup into a reusable function**
-
-The file watcher logic (lines 686-719) needs to be callable for hot-added files too. Extract it within `createServer`:
-
-```ts
-function watchFile(filePath: string): FSWatcher | null {
-  try {
-    const watcher = watch(filePath, async (eventType) => {
-      if (eventType !== "change") return;
-
-      const state = fileMap.get(filePath);
-      if (!state) return;
-
-      if (state.debounceTimer) clearTimeout(state.debounceTimer);
-      state.debounceTimer = setTimeout(async () => {
-        try {
-          const newContent = await fs.readFile(filePath, "utf-8");
-          if (newContent !== state.content) {
-            state.content = newContent;
-            console.log(`File changed: ${basename(filePath)}`);
-
-            const message = `data: ${JSON.stringify({ type: "update", path: filePath })}\n\n`;
-            for (const controller of sseClients) {
-              try {
-                controller.enqueue(message);
-              } catch {
-                sseClients.delete(controller);
-              }
-            }
-          }
-        } catch (err) {
-          console.error(`Failed to read updated file ${filePath}:`, err);
-        }
-      }, 100);
-    });
-    return watcher;
-  } catch (err) {
-    console.warn(`File watching not available for ${filePath}:`, err);
-    return null;
-  }
-}
-```
-
-Replace the inline watcher loop with:
-```ts
-for (const filePath of fileOrder) {
-  const watcher = watchFile(filePath);
-  if (watcher) watchers.push(watcher);
-}
-```
-
-**Step 2: Add `POST /api/files` route**
-
-Add inside the `fetch` handler in `createServer`, after the `/api/documents` route:
-
-```ts
-if (pathname === "/api/files" && method === "POST") {
-  try {
-    const { path: requestedPath } = await req.json();
-
-    if (!requestedPath || typeof requestedPath !== "string") {
-      return errorResponse("Missing 'path' field", 400);
-    }
-
-    const filePath = path.resolve(requestedPath);
-    const fileType = getFileType(filePath);
-
-    if (!fileType) {
-      return errorResponse(
-        `Unsupported file type: ${filePath} (expected .md, .markdown, .html, or .htm)`,
-        400,
-      );
-    }
-
-    let content: string;
-    try {
-      content = await fs.readFile(filePath, "utf-8");
-    } catch (err) {
-      if (isErrnoException(err) && err.code === "ENOENT") {
-        return errorResponse(`File not found: ${filePath}`, 404);
-      }
-      throw err;
-    }
-
-    const existingState = fileMap.get(filePath);
-
-    if (existingState) {
-      // File already loaded — refresh content
-      existingState.content = content;
-      const message = `data: ${JSON.stringify({ type: "update", path: filePath })}\n\n`;
-      for (const controller of sseClients) {
-        try {
-          controller.enqueue(message);
-        } catch {
-          sseClients.delete(controller);
-        }
-      }
-    } else {
-      // New file — add to server
-      fileMap.set(filePath, {
-        content,
-        type: fileType,
-        debounceTimer: null,
-      });
-      fileOrder.push(filePath);
-
-      // Set up file watcher for the new file
-      const watcher = watchFile(filePath);
-      if (watcher) watchers.push(watcher);
-
-      const message = `data: ${JSON.stringify({
-        type: "file-added",
-        path: filePath,
-        fileName: basename(filePath),
-        fileType,
-      })}\n\n`;
-      for (const controller of sseClients) {
-        try {
-          controller.enqueue(message);
-        } catch {
-          sseClients.delete(controller);
-        }
-      }
-    }
-
-    return json({
-      path: filePath,
-      fileName: basename(filePath),
-      type: fileType,
-    });
-  } catch (err) {
-    console.error("Failed to add file:", err);
-    return errorResponse("Failed to add file", 500);
-  }
-}
-```
-
-**Step 3: Add the `getFileType` import**
-
-```ts
-import { getFileType } from "../lib/utils.js";
-```
-
-**Step 4: Verify build passes**
-
-Run: `bun run typecheck`
-Expected: No errors
-
-**Step 5: Commit**
-
-```bash
-git add src/server/index.ts
-git commit -m "feat: add POST /api/files endpoint for hot-adding files"
-```
-
----
-
-### Task 4: Handle `file-added` SSE event in frontend
-
-**Files:**
-- Modify: `src/hooks/useDocument.ts`
-
-**Step 1: Add `file-added` handling to SSE listener**
-
-In the `eventSource.onmessage` handler (around line 90), add a branch for `file-added`:
-
-```ts
-eventSource.onmessage = async (e) => {
-  try {
-    const data = JSON.parse(e.data);
-
-    if (data.type === "file-added" && data.path) {
-      appStore.getState().openDocument({
-        content: "", // Lazy-loaded when tab activated
-        type: data.fileType,
-        filePath: data.path,
-        fileName: data.fileName,
-        clean: false,
-      });
-      return;
-    }
-
-    if (data.type === "update" && data.path) {
-      // ... existing update logic unchanged
-    }
-  } catch {
-    // Ignore non-JSON messages ("connected", "ping")
-  }
-};
-```
-
-**Step 2: Verify build passes**
-
-Run: `bun run typecheck`
-Expected: No errors
-
-**Step 3: Commit**
-
-```bash
-git add src/hooks/useDocument.ts
-git commit -m "feat: handle file-added SSE event for hot-added documents"
-```
-
----
-
-### Task 5: Add `readit open` CLI command
-
-**Files:**
-- Modify: `src/cli/index.ts`
-
-**Step 1: Add server discovery function**
-
-Add after the imports:
-
-```ts
-import { readFileSync as readFileSyncNode } from "node:fs";
-
-interface ServerInfo {
-  port: number;
-  pid: number;
-}
-
-async function discoverServer(): Promise<ServerInfo | null> {
-  const serverInfoPath = join(os.homedir(), ".readit", "server.json");
-
-  try {
-    const content = readFileSyncNode(serverInfoPath, "utf-8");
-    const info: ServerInfo = JSON.parse(content);
-
-    // Verify the process is alive
-    try {
-      process.kill(info.pid, 0);
-    } catch {
-      return null;
-    }
-
-    // Verify health endpoint responds
-    try {
-      const res = await fetch(`http://127.0.0.1:${info.port}/api/health`);
-      if (!res.ok) return null;
-    } catch {
-      return null;
-    }
-
-    return info;
-  } catch {
-    return null;
-  }
-}
-```
-
-**Step 2: Add `open` subcommand**
-
-Add before `program.parse()`:
-
-```ts
-program
-  .command("open")
-  .argument("<files...>", "Markdown or HTML files to add to running server")
-  .description("Add files to a running readit server, or start a new one")
-  .option("-p, --port <number>", "Port for new server (if starting)", "4567")
-  .option("--host <address>", "Host for new server (if starting)", "127.0.0.1")
-  .action(
-    async (
-      fileArgs: string[],
-      options: { port: string; host: string },
-    ) => {
-      // Resolve and validate files
-      const resolvedFiles: { path: string; type: DocumentType }[] = [];
-      for (const arg of fileArgs) {
-        const filePath = resolve(process.cwd(), arg);
-
-        if (!existsSync(filePath)) {
-          console.error(`error: not found: ${filePath}`);
-          process.exit(1);
-        }
-
-        const type = getFileType(filePath);
-        if (!type) {
-          console.error(
-            `error: unsupported file type: ${arg} (expected .md, .markdown, .html, or .htm)`,
-          );
-          process.exit(1);
-        }
-
-        resolvedFiles.push({ path: filePath, type });
-      }
-
-      // Try to find running server
-      const server = await discoverServer();
-
-      if (server) {
-        // Send files to running server
-        for (const file of resolvedFiles) {
-          try {
-            const res = await fetch(
-              `http://127.0.0.1:${server.port}/api/files`,
-              {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ path: file.path }),
-              },
-            );
-
-            if (!res.ok) {
-              const data = await res.json();
-              console.error(
-                `error: failed to add ${file.path}: ${data.error}`,
-              );
-              process.exit(1);
-            }
-
-            const data = await res.json();
-            console.log(`Added: ${data.fileName} (${data.type})`);
-          } catch (err) {
-            console.error(
-              `error: failed to connect to server:`,
-              err instanceof Error ? err.message : err,
-            );
-            process.exit(1);
-          }
-        }
-
-        console.log(
-          `\nServer: http://127.0.0.1:${server.port}`,
-        );
-        return;
-      }
-
-      // No running server — start one
-      console.log("No running server found, starting new one...\n");
-
-      const files = resolvedFiles.map((f) => ({
-        content: readFileSync(f.path, "utf-8"),
-        type: f.type,
-        filePath: f.path,
-      }));
-
-      const preferredPort = Number.parseInt(options.port, 10);
-      try {
-        const { url, server: newServer } = await startServer({
-          files,
-          port: preferredPort,
-          host: options.host,
-        });
-
-        const fileList = files.map((f) => `  ${f.filePath} (${f.type})`);
-        console.log(`
-readit - Document Review Tool
-
-  ${files.length === 1 ? "File:" : "Files:"}
-${fileList.join("\n")}
-  URL:  ${url}
-
-  Server running. Close browser tab to stop.
-  Press Ctrl+C to force stop.
-`);
-
-        open(url);
-
-        process.on("SIGINT", async () => {
-          console.log("\n\nShutting down...");
-          newServer.stop();
-          await removeServerInfo();
-          process.exit(0);
-        });
-      } catch (error) {
-        console.error(
-          "error: failed to start server:",
-          error instanceof Error ? error.message : error,
-        );
-        process.exit(1);
-      }
-    },
-  );
-```
-
-**Step 3: Add missing imports**
-
-Make sure these imports are at the top of the file:
-
-```ts
-import { getFileType } from "../lib/utils.js";
-import { removeServerInfo } from "../server/index.js";
-import type { DocumentType } from "../types/index.js";
-```
-
-**Step 4: Verify build passes**
-
-Run: `bun run typecheck`
-Expected: No errors
-
-**Step 5: Commit**
-
-```bash
-git add src/cli/index.ts
-git commit -m "feat: add readit open command for client mode"
-```
-
----
-
-### Task 6: Update the hook configuration
-
-**Files:**
-- Modify: `/Users/jay/.claude/settings.json`
-
-**Step 1: Update the PostToolUse hook**
-
-Change the command from `open -a Arto` to `bunx readit open`:
-
-```json
-"PostToolUse": [
-  {
-    "matcher": "Write|Edit",
-    "hooks": [
-      {
-        "type": "command",
-        "command": "bash -c 'FILE=$(cat | jq -r \".tool_input.file_path\"); if [[ \"$FILE\" == *.md ]]; then bunx readit open \"$FILE\"; fi; exit 0'"
-      }
-    ]
-  }
-]
-```
-
-**Step 2: Verify the hook fires correctly**
-
-Write or edit any `.md` file and confirm the hook runs without error.
-
----
-
-### Task 7: End-to-end verification
-
-**Step 1: Build the project**
-
-Run: `bun run build`
-Expected: Successful build
-
-**Step 2: Start server with a test file**
-
-Run: `bunx readit test.md`
-Expected: Server starts, browser opens
-
-**Step 3: Open another file via client mode**
-
-In another terminal:
-Run: `bunx readit open README.md`
-Expected: "Added: README.md (markdown)" printed, new tab appears in browser
-
-**Step 4: Verify live reload for hot-added file**
-
-Edit `README.md` on disk, confirm the browser updates automatically.
-
-**Step 5: Verify reload for already-loaded file**
-
-Run: `bunx readit open test.md`
-Expected: Content refreshes, no duplicate tab
-
-**Step 6: Verify auto-start when no server running**
-
-Stop the server (Ctrl+C), then:
-Run: `bunx readit open test.md`
-Expected: New server starts with `test.md`