Michael Ramos
4627f75426
Adds a general-purpose External Annotations API that allows external programs (linters, AI tools, security scanners) to push annotations into a live Plannotator session via HTTP, with real-time delivery over SSE. ## What's included - **Shared core** (`packages/shared/external-annotation.ts`): types, in-memory store, input validation, SSE serialization - **Server handlers**: Bun + Pi implementations with full CRUD (GET/POST/PATCH/DELETE) + SSE streaming - **Client hook** (`useExternalAnnotations`): EventSource with polling fallback, optimistic updates - **Editor integration**: two-array state model (local + external), content-aware dedup, ID-based routing - **Persistence**: source field preserved through share URLs and crash-recovery drafts - **Docs**: new Integrations category with API overview page, updated API reference ## API surface All three servers (plan, review, annotate) expose: - `GET /api/external-annotations/stream` - SSE stream - `GET /api/external-annotations` - JSON snapshot (polling fallback) - `POST /api/external-annotations` - Add annotations (single or batch) - `PATCH /api/external-annotations?id=` - Update fields - `DELETE /api/external-annotations` - Remove by id, source, or clear all For provenance purposes, this commit was AI assisted.
Tests
This directory contains manual testing scripts for Plannotator.
UI Tests (manual/local/)
These scripts test the UI components and require a browser.
Plan review UI:
./tests/manual/local/test-hook.sh # Claude Code simulation
./tests/manual/local/test-hook-2.sh # OpenCode origin badge test
Code review UI:
./tests/manual/local/test-opencode-review.sh # Code review UI test
./tests/manual/local/test-worktree-review.sh # Worktree support test (creates sandbox with 4 worktrees)
See UI-TESTING.md for detailed UI testing documentation.
Integration & Utility Tests (manual/local/)
These scripts test integrations, releases, and provide utilities.
Binary release testing:
./tests/manual/local/test-binary.sh # Test installed binary from ~/.local/bin/
Tests the installed plannotator binary to verify releases work correctly.
Bulk plan testing (Obsidian integration):
./tests/manual/local/test-bulk-plans.sh # Iterate through ~/.claude/plans/
Opens each .md file from ~/.claude/plans/ in Plannotator. Great for testing Obsidian integration with multiple
plans.
OpenCode integration sandbox:
./tests/manual/local/sandbox-opencode.sh [--disable-sharing] [--keep] [--no-git]
Creates a temporary sandbox with a sample React/TypeScript project, initializes git with uncommitted changes, sets up the local OpenCode plugin, and launches OpenCode for full integration testing.
Options:
--disable-sharing: Createsopencode.jsonwith sharing disabled--keep: Don't clean up sandbox on exit--no-git: Skip git initialization (tests non-git fallback)
Obsidian utility:
./tests/manual/local/fix-vault-links.sh /path/to/vault/plannotator
Adds Obsidian backlinks ([[Plannotator Plans]]) to existing plan files in your vault.
SSH Remote Testing (manual/ssh/)
Tests SSH session detection and port forwarding for remote development scenarios.
cd tests/manual/ssh/
docker-compose up -d
./test-ssh.sh
See manual/ssh/DOCKER_SSH_TEST.md for detailed setup instructions.