@peaske7/readit 0.2.1 → 0.3.0-rc.1

package/docs/superpowers/specs/2026-03-27-go-server-rewrite-design.md

@@ -1,284 +0,0 @@
-# Go Server Rewrite Design Spec
-
-## Summary
-
-Rewrite readit's server and CLI from Bun/TypeScript to Go. The Svelte 5 frontend stays unchanged. Go handles all heavy computation (markdown rendering, syntax highlighting, comment storage, file watching, SSE) while Svelte handles client-side interactivity (highlights, margin notes, comment CRUD UI).
-
-## Motivation
-
-The current Bun server's cold-start path is dominated by Shiki WASM initialization (80-200ms) and the JSDOM mermaid worker (2-5s). A compiled Go binary with native libraries eliminates both bottlenecks:
-
-- Process startup: 30-50ms (Bun) → <1ms (Go binary)
-- Syntax highlighting init: 80-200ms (Shiki WASM) → 0ms (chroma, compiled in)
-- Markdown render (3000 lines): 5-20ms (markdown-it) → <1ms (goldmark)
-- Single binary distribution, no node_modules runtime dependency
-
-Target: 50-100x improvement on server-side TTFB.
-
-## Architecture
-
-```
-readit/
-├── go/
-│   ├── cmd/readit/main.go              # CLI entry point
-│   ├── internal/server/
-│   │   ├── server.go                   # Mux setup, static serving, dev proxy
-│   │   ├── documents.go                # Document routes + file state
-│   │   ├── comments.go                 # Comment CRUD routes
-│   │   ├── settings.go                 # Settings routes
-│   │   ├── sse.go                      # SSE broker, heartbeat, shutdown timer
-│   │   ├── markdown.go                 # goldmark + chroma rendering
-│   │   ├── headings.go                 # AST-based heading extraction
-│   │   ├── storage.go                  # .comments.md parse/serialize
-│   │   ├── anchor.go                   # Anchor resolution + fuzzy matching
-│   │   ├── watcher.go                  # fsnotify file watching + debounce
-│   │   ├── template.go                 # HTML page template
-│   │   ├── types.go                    # Shared types
-│   │   └── embed.go                    # go:embed dist/ assets
-│   ├── go.mod
-│   └── go.sum
-├── src/                                # Svelte frontend (unchanged)
-├── dist/                               # Vite build output (Go embeds this)
-├── Makefile
-├── vite.config.ts
-└── package.json
-```
-
-Single Go package (`internal/server`) with flat files. `cmd/readit/main.go` calls `server.Start(opts)`. No nested packages, no interface indirection.
-
-## Decisions
-
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| Language | Go | goldmark+chroma ecosystem, fast dev velocity, single binary |
-| Repo structure | Monorepo (`go/` + `src/`) | Shared build pipeline, colocated frontend |
-| Asset serving | `go:embed` + `--assets-dir` override | Single binary for production, filesystem for dev |
-| Mermaid | Client-only with `<link rel="modulepreload">` | Eliminates JSDOM complexity, door open for server-side later |
-| Dev workflow | `make dev` — Go manages Vite child process | Single command, Go proxies to Vite for HMR |
-| Comment format | Keep `.comments.md` unchanged | Backward compatible, simple to parse in Go |
-| File support | Markdown only | Tight scope for v1 |
-| HTTP router | `net/http.ServeMux` (Go 1.22+) | Method+pattern routing, no framework dependency |
-| CLI parsing | `flag` package | Simple subcommands, no cobra overhead |
-
-## Server Core
-
-The `Server` struct holds all shared state:
-
-```go
-type Server struct {
-    mux        *http.ServeMux
-    files      map[string]*FileState
-    fileOrder  []string
-    sse        *SSEBroker
-    watcher    *Watcher
-    renderer   *Renderer
-    settings   Settings
-    workingDir string
-    clean      bool
-    assetsFS   fs.FS
-    template   *template.Template
-    mu         sync.RWMutex
-}
-```
-
-Routes registered as methods on `Server` — no handler interfaces, no middleware chain. Dev mode proxies non-API requests to Vite at `localhost:24678`.
-
-## API Contract
-
-The Go server implements the exact same API the Svelte frontend consumes. No changes to request/response shapes.
-
-### Document Routes (`documents.go`)
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| GET | `/api/documents` | List open files |
-| POST | `/api/documents` | Add file to session |
-| GET | `/api/document?path=` | Get rendered HTML + headings |
-
-### Comment Routes (`comments.go`)
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| GET | `/api/comments?path=` | List comments (with anchor resolution) |
-| POST | `/api/comments?path=` | Create comment |
-| PUT | `/api/comments/{id}?path=` | Update comment text |
-| DELETE | `/api/comments/{id}?path=` | Delete comment |
-| DELETE | `/api/comments?path=` | Delete all comments |
-| PUT | `/api/comments/{id}/reanchor?path=` | Reanchor comment |
-| GET | `/api/comments/raw?path=` | Raw .comments.md content |
-
-### Settings Routes (`settings.go`)
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| GET | `/api/settings` | Read settings |
-| PUT | `/api/settings` | Update font family |
-
-### SSE Endpoints (`sse.go`)
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| GET | `/api/document/stream` | Document change events |
-| GET | `/api/heartbeat` | Keep-alive, manages auto-shutdown |
-
-### Other
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| GET | `/api/health` | Health check (`{"status":"ok"}`) |
-| GET | `/` | SSR page with inline data |
-| GET | `/assets/*` | Static assets (embedded or filesystem) |
-
-### Inline Data Shape
-
-The root page embeds JSON in `<script type="application/json" id="__readit">`:
-
-```json
-{
-  "files": [{"path": "...", "fileName": "..."}],
-  "activeFile": "...",
-  "clean": false,
-  "workingDirectory": "...",
-  "documents": {
-    "/path/to/file.md": {
-      "html": "...",
-      "headings": [{"id": "...", "text": "...", "level": 1}],
-      "comments": [...]
-    }
-  },
-  "settings": {"version": 1, "fontFamily": "serif"}
-}
-```
-
-## Markdown Pipeline (`markdown.go` + `headings.go`)
-
-goldmark with extensions, configured once at startup:
-
-- **GFM**: tables, strikethrough, autolinks, task lists
-- **Chroma highlighting**: `onedark` style, CSS classes (not inline styles)
-- **Auto heading IDs**: generated from heading text
-- **Unsafe HTML**: raw HTML passthrough (matches current behavior)
-
-Heading extraction walks the goldmark AST directly instead of regex.
-
-Mermaid fenced code blocks pass through as `<pre><code class="language-mermaid">`. The Svelte frontend's `DocumentViewer.svelte` hydrates these client-side via lazy `import("mermaid")`. A `<link rel="modulepreload">` hint in the template accelerates the mermaid chunk download.
-
-## Comment Storage (`storage.go` + `anchor.go`)
-
-Parses and serializes the existing `.comments.md` format unchanged:
-
-- Storage path: `~/.readit/comments/<mirrored-path>.comments.md`
-- Format: YAML frontmatter (`source`, `hash`, `version`) + comment blocks separated by `---`
-- Atomic writes: temp file + `os.Rename`
-- Hash: SHA-256 of source content, truncated to 16 hex chars
-
-Anchor resolution algorithm (direct port):
-
-1. Exact match near `lineHint` position
-2. Exact match anywhere in source
-3. Normalized match (collapse whitespace)
-4. Mark as `unresolved`
-
-Two-key cache: comment file mtime + source content hash. Skip re-parsing when neither changed.
-
-## SSE & File Watching (`sse.go` + `watcher.go`)
-
-SSE broker manages two client sets:
-
-- **Document stream clients**: receive `document-updated` and `document-added` events
-- **Heartbeat clients**: keep-alive pings, manage auto-shutdown timer (1.5s grace after last client disconnects, production only)
-
-File watcher uses `fsnotify` with 100ms debounce per file. On change: invalidate render cache → invalidate comment cache → broadcast SSE event.
-
-## CLI (`cmd/readit/main.go`)
-
-Subcommands:
-
-- `readit <file.md> [flags]` — start server + open browser
-- `readit list` — list files with comments (stdout)
-- `readit show <file.md>` — print comments for file (stdout)
-- `readit open <file.md>` — attach to running server or start new one
-
-Flags:
-
-- `--port` (default: random available)
-- `--host` (default: `127.0.0.1`)
-- `--no-open` (skip browser launch)
-- `--clean` (clear existing comments)
-- `--assets-dir` (override embedded assets)
-- `--dev` (spawn Vite child process, proxy to it)
-
-Server discovery: `~/.readit/server.json` with PID liveness check + HTTP health check. File lock (`server.lock`) prevents race conditions.
-
-## Build & Dev Workflow
-
-```makefile
-dev:           # Go spawns Vite child process, single command
-build:         # bun vite build → go build (embeds dist/)
-test:          # go test ./...
-test-client:   # bun run test
-test-e2e:      # playwright
-```
-
-Dev mode: `make dev` → Go runs with `--dev`, spawns `bunx vite` on port 24678, proxies non-API requests. Ctrl+C kills both.
-
-Production build: `make build` → Vite builds frontend into `dist/`, then `go build` embeds `dist/` into the binary.
-
-## Types (`types.go`)
-
-```go
-type Comment struct {
-    ID               string `json:"id"`
-    SelectedText     string `json:"selectedText"`
-    Comment          string `json:"comment"`
-    StartOffset      int    `json:"startOffset"`
-    EndOffset        int    `json:"endOffset"`
-    CreatedAt        string `json:"createdAt"`
-    LineHint         string `json:"lineHint,omitempty"`
-    AnchorConfidence string `json:"anchorConfidence,omitempty"`
-    AnchorPrefix     string `json:"anchorPrefix,omitempty"`
-}
-
-type Heading struct {
-    ID    string `json:"id"`
-    Text  string `json:"text"`
-    Level int    `json:"level"`
-}
-
-type FileState struct {
-    FilePath    string
-    FileName    string
-    Content     []byte
-    RenderedHTML string
-    Headings    []Heading
-    mu          sync.Mutex
-}
-
-type Settings struct {
-    Version    int    `json:"version"`
-    FontFamily string `json:"fontFamily"`
-}
-```
-
-JSON tags match the current API responses exactly.
-
-## Go Dependencies
-
-| Package | Purpose |
-|---------|---------|
-| `github.com/yuin/goldmark` | Markdown → HTML |
-| `github.com/yuin/goldmark-highlighting/v2` | Chroma integration for goldmark |
-| `github.com/alecthomas/chroma/v2` | Syntax highlighting (native Go) |
-| `github.com/fsnotify/fsnotify` | Cross-platform file watching |
-| `github.com/pkg/browser` | Cross-platform browser launch |
-
-Five dependencies total. No HTTP framework, no CLI framework.
-
-## Migration Path
-
-1. Build Go server implementing the full API contract
-2. Verify Svelte frontend works unchanged against Go server
-3. Run existing E2E perf tests, compare against React/Svelte baselines
-4. Remove `src/server.ts`, `src/cli.ts`, `src/lib/markdown-renderer.ts`, `src/lib/mermaid-worker.ts`, `src/lib/mermaid-renderer.ts`, `src/lib/comment-storage.ts`, `src/lib/anchor.ts`, related server-side code
-5. Update `package.json` scripts to use Makefile
-6. Remove server-side JS dependencies (`shiki`, `markdown-it`, `jsdom`, `mermaid`, `commander`)

package/e2e/comments.spec.ts

@@ -1,81 +0,0 @@
-import { existsSync, rmSync } from "node:fs";
-import * as os from "node:os";
-import { join, resolve } from "node:path";
-import { expect, test } from "@playwright/test";
-import { spawnCli } from "./utils/cli";
-import { addComment, selectTextInArticle } from "./utils/selection";
-
-const FIXTURES_DIR = resolve(import.meta.dirname, "fixtures");
-
-/**
- * Get the expected comment file path for a source file.
- */
-function getCommentPath(sourcePath: string): string {
-  const absolute = resolve(sourcePath);
-  const normalized = absolute.replace(/^\//, "").replace(/^[A-Z]:[\\/]/, "");
-  const ext = normalized.lastIndexOf(".");
-  const withoutExt = ext > 0 ? normalized.slice(0, ext) : normalized;
-  return join(os.homedir(), ".readit", "comments", `${withoutExt}.comments.md`);
-}
-
-/**
- * Clean up comment file for a source file.
- */
-function cleanupCommentFile(sourcePath: string): void {
-  const commentPath = getCommentPath(sourcePath);
-  if (existsSync(commentPath)) {
-    rmSync(commentPath);
-  }
-}
-
-test.describe("Comment Creation", () => {
-  const sampleMdPath = resolve(FIXTURES_DIR, "sample.md");
-
-  test.beforeEach(() => {
-    cleanupCommentFile(sampleMdPath);
-  });
-
-  test.afterEach(() => {
-    cleanupCommentFile(sampleMdPath);
-  });
-
-  test("adds comment to selected text in markdown document", async ({
-    page,
-  }) => {
-    const { url, cleanup } = await spawnCli(sampleMdPath, { port: 4572 });
-
-    try {
-      await page.goto(url);
-
-      // Wait for document to load
-      const article = page.locator("article#document-content");
-      await expect(article).toBeVisible();
-
-      // Select text in the article
-      const textToSelect = "testing text selection";
-      await selectTextInArticle(page, textToSelect);
-
-      // Add a comment
-      const commentText = "This is my test comment";
-      await addComment(page, commentText);
-
-      // Verify: highlight exists via CSS Custom Highlight API observability hook
-      await page.waitForFunction(
-        () => {
-          const h = (window as unknown as Record<string, unknown>)
-            .__readitHighlights as { commentIds: string[] } | undefined;
-          return h && h.commentIds.length > 0;
-        },
-        { timeout: 10_000 },
-      );
-
-      // Verify the selected text is still visible in the article
-      await expect(article).toContainText(textToSelect);
-
-      // Verify: margin note shows the comment
-      await expect(page.locator("body")).toContainText(commentText);
-    } finally {
-      await cleanup();
-    }
-  });
-});

package/e2e/document-load.spec.ts

@@ -1,32 +0,0 @@
-import { resolve } from "node:path";
-import { expect, test } from "@playwright/test";
-import { spawnCli } from "./utils/cli";
-
-const FIXTURES_DIR = resolve(import.meta.dirname, "fixtures");
-
-test.describe("Document Loading", () => {
-  test("loads markdown document and displays content", async ({ page }) => {
-    const { url, cleanup } = await spawnCli(
-      resolve(FIXTURES_DIR, "sample.md"),
-      { port: 4570 },
-    );
-
-    try {
-      await page.goto(url);
-
-      // Wait for document to load - use article scope to avoid header h1
-      const article = page.locator("article#document-content");
-      await expect(article.locator("h1")).toContainText("Test Document");
-
-      // Verify paragraph content is rendered
-      await expect(article).toContainText(
-        "This is a paragraph for testing text selection",
-      );
-
-      // Verify second section is visible
-      await expect(article.locator("h2")).toContainText("Second Section");
-    } finally {
-      await cleanup();
-    }
-  });
-});

package/e2e/export.spec.ts

@@ -1,58 +0,0 @@
-import { resolve } from "node:path";
-import { expect, test } from "@playwright/test";
-import { spawnCli } from "./utils/cli";
-import { addComment, selectTextInArticle } from "./utils/selection";
-
-const FIXTURES_DIR = resolve(import.meta.dirname, "fixtures");
-
-test.describe("Comment Export", () => {
-  test("Copy All generates valid prompt format", async ({ page, context }) => {
-    // Grant clipboard permissions
-    await context.grantPermissions(["clipboard-read", "clipboard-write"]);
-
-    const { url, cleanup } = await spawnCli(
-      resolve(FIXTURES_DIR, "sample.md"),
-      { port: 4590 },
-    );
-
-    try {
-      await page.goto(url);
-
-      // Wait for document to load
-      const article = page.locator("article#document-content");
-      await expect(article).toBeVisible();
-
-      // Add a comment
-      const textToSelect = "testing text selection";
-      const commentText = "This is my review comment";
-      await selectTextInArticle(page, textToSelect);
-      await addComment(page, commentText);
-
-      // Verify comment was added
-      await expect(page.locator("body")).toContainText(commentText);
-
-      // Open the actions menu and click "Copy All"
-      const menuButton = page.getByRole("button", { name: /actions menu/i });
-      await menuButton.click();
-
-      const copyButton = page.getByRole("menuitem", { name: /copy all/i });
-      await copyButton.click();
-
-      // Read clipboard content
-      const clipboardContent = await page.evaluate(() =>
-        navigator.clipboard.readText(),
-      );
-
-      // Verify the format contains expected parts
-      expect(clipboardContent).toContain("# Review Comments for sample.md");
-      expect(clipboardContent).toContain(textToSelect);
-      expect(clipboardContent).toContain(commentText);
-
-      // Verify it follows the prompt format (quoted selected text + comment)
-      expect(clipboardContent).toMatch(/"testing text selection"/);
-      expect(clipboardContent).toContain("This is my review comment");
-    } finally {
-      await cleanup();
-    }
-  });
-});

package/e2e/fixtures/sample.md

@@ -1,7 +0,0 @@
-# Test Document
-
-This is a paragraph for testing text selection.
-
-## Second Section
-
-Here is another paragraph with some more text to select and comment on.

package/e2e/perf/add-comment.spec.ts

@@ -1,116 +0,0 @@
-import { expect, test } from "@playwright/test";
-import { getFixturePath, TIERS } from "./fixtures/generate";
-import {
-  measureInteraction,
-  reportInteraction,
-  waitForHighlightCount,
-} from "./utils/metrics";
-import { spawnPerfCli } from "./utils/perf-cli";
-
-// Use the medium tier — most representative of real usage
-const tier = TIERS[0];
-
-test(`add-comment: ${tier.name} (${tier.lines} lines, ${tier.comments} comments)`, async ({
-  page,
-}, testInfo) => {
-  const fixturePath = getFixturePath(tier);
-  const { url, cleanup } = await spawnPerfCli(fixturePath, { port: 4620 });
-
-  try {
-    await page.goto(url);
-    await waitForHighlightCount(page, tier.comments);
-    await page.waitForTimeout(300);
-
-    // Capture actual highlight count as baseline (may differ from tier.comments)
-    const baselineCount = await page.evaluate(() => {
-      const h = (window as unknown as Record<string, unknown>)
-        .__readitHighlights as { commentIds: string[] } | undefined;
-      return h?.commentIds?.length ?? 0;
-    });
-
-    // Find a text that isn't already highlighted — use a line near the end
-    const selectionText = await page.evaluate(() => {
-      const article = document.querySelector("article");
-      if (!article) throw new Error("Article not found");
-
-      // Find paragraph text near the bottom of the document
-      const paragraphs = article.querySelectorAll("p");
-      const target = paragraphs[paragraphs.length - 2];
-      if (!target?.textContent) throw new Error("No paragraph found");
-
-      // Use first 30 chars
-      return target.textContent.slice(0, 30).trim();
-    });
-
-    // Select text via custom event
-    await page.evaluate((text) => {
-      const article = document.querySelector("article");
-      if (!article) throw new Error("Article not found");
-
-      const walker = document.createTreeWalker(article, NodeFilter.SHOW_TEXT);
-      let currentOffset = 0;
-
-      while (walker.nextNode()) {
-        const textNode = walker.currentNode as Text;
-        const content = textNode.textContent || "";
-        const index = content.indexOf(text);
-
-        if (index !== -1) {
-          const startOffset = currentOffset + index;
-          const endOffset = startOffset + text.length;
-          window.dispatchEvent(
-            new CustomEvent("test:select-text", {
-              detail: { text, startOffset, endOffset },
-            }),
-          );
-          return;
-        }
-
-        currentOffset += content.length;
-      }
-
-      throw new Error(`Text "${text}" not found`);
-    }, selectionText);
-
-    // Wait for comment input to appear
-    const textarea = page.locator(
-      'textarea[placeholder="Add your comment..."]',
-    );
-    await textarea.waitFor({ state: "visible", timeout: 10_000 });
-
-    // Fill in the comment
-    await textarea.fill("Performance benchmark comment");
-
-    // Mark start and click Add
-    const duration = await measureInteraction(
-      page,
-      "add-comment",
-      async () => {
-        await page.getByRole("button", { name: "Add" }).click();
-      },
-      async () => {
-        await page.waitForFunction((expected) => {
-          const h = (window as unknown as Record<string, unknown>)
-            .__readitHighlights as { commentIds: string[] } | undefined;
-          return (h?.commentIds?.length ?? 0) > expected;
-        }, baselineCount);
-      },
-    );
-
-    reportInteraction(
-      testInfo,
-      `add-comment: time to new highlight (${tier.name})`,
-      duration,
-    );
-
-    // Verify the highlight actually appeared
-    const finalCount = await page.evaluate(() => {
-      const h = (window as unknown as Record<string, unknown>)
-        .__readitHighlights as { commentIds: string[] } | undefined;
-      return h?.commentIds?.length ?? 0;
-    });
-    expect(finalCount).toBeGreaterThan(tier.comments);
-  } finally {
-    await cleanup();
-  }
-});