open-plan-annotator 1.0.3 → 1.0.5

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "open-plan-annotator",
       "source": "./",
       "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
-      "version": "1.0.3",
+      "version": "1.0.5",
       "author": {
         "name": "ndom91"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "open-plan-annotator",
   "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "author": {
     "name": "ndom91"
   },

package/README.md

@@ -4,43 +4,27 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-pink?style=flat-square)]()
 
-A fully local agentic coding plugin that intercepts plan mode and opens an annotation UI in your browser. Mark up the plan, send structured feedback to the agent, and receive a revised version — iterate as many times as you need until you're ready to accept.
-
-Select text to <code>strikethrough</code>, <code>replace</code>, <code>insert</code>, or <code>comment</code> — then approve the plan or request changes.
+A fully local agentic coding plugin that intercepts plan mode and opens an annotation UI in your browser. Mark up the plan, send structured feedback to the agent, and receive a revised version — iterate as many times as you need until you're ready to approve.
 
+Select text to <code>strikethrough</code>, <code>replace</code>, <code>insert</code>, or <code>comment</code> — then approve the plan or request changes
 
 ![](.github/assets/screenshot.png)
 
+## How It Works
 
-## How it works
-
-1. Host submits a plan to `open-plan-annotator`
-2. An ephemeral HTTP server starts and opens a React UI in your browser
-3. You review and annotate the plan
-4. **Approve** or **Request Changes**
-5. The tool returns structured JSON output back to the host
+1. Your coding agent (Claude Code or OpenCode) finishes writing a plan
+2. The plugin launches an ephemeral HTTP server and opens a React UI in your browser
+3. You review the plan and annotate it — strikethrough, replace, insert, or comment on any section
+4. **Approve** to let the agent proceed, or **Request Changes** to send your annotations back as structured feedback
+5. The agent revises the plan and the cycle repeats until you're satisfied
 
-The server shuts down after you decide. Everything runs locally, nothing leaves your machine.
+Everything runs locally. Nothing leaves your machine.
 
 ## Install
 
-> [!NOTE]
-> The first run might take a few seconds if you use pnpm as it blocks postinstall scripts.
-> Claude / OpenCode will trigger the download upon first use then.
-
-**1. Install the binary**
-
-```sh
-npm install -g open-plan-annotator
-```
-
-This JS shim downloads the correct binary for your platform (macOS, Linux).
-
 ### Claude Code
 
-Add the marketplace and install the plugin:
-
-From within Claude Code:
+From within Claude Code, add the marketplace and install the plugin:
 
 ```
 /plugin marketplace add ndom91/open-plan-annotator
@@ -66,7 +50,7 @@ OpenCode will install the package and load it automatically. The plugin:
 - Returns structured feedback to the agent on approval or rejection
 - Optionally hands off to an implementation agent after approval
 
-#### Implementation handoff
+#### Implementation Handoff
 
 By default, after a plan is approved the plugin sends "Proceed with implementation." to a `build` agent. To customize or disable this, create `open-plan-annotator.json` in your project's `.opencode/` directory or globally in `~/.config/opencode/`:
 
@@ -81,7 +65,19 @@ By default, after a plan is approved the plugin sends "Proceed with implementati
 
 Set `enabled` to `false` to disable auto-handoff. Project config overrides global config.
 
-### From source (Claude Code)
+### Manual Install
+
+If you want to run the binary standalone or build from source:
+
+```sh
+npm install -g open-plan-annotator
+```
+
+> [!NOTE]
+> The first run might take a few seconds if you use pnpm, as it blocks postinstall scripts.
+> Claude / OpenCode will trigger the download upon first use then.
+
+#### From Source
 
 ```sh
 git clone https://github.com/ndom91/open-plan-annotator.git
@@ -96,16 +92,16 @@ Then load it directly in Claude Code:
 claude --plugin-dir ./open-plan-annotator
 ```
 
-## Annotations
+## Keyboard Shortcuts
 
-| Type | Shortcut | Description |
-|------|----------|-------------|
+| Action | Shortcut | Description |
+|--------|----------|-------------|
 | Delete | `d` | Strikethrough selected text |
-| Replace | `r` | Replace selected text with new text |
-| Insert | `i` | Insert text after selection |
+| Replace | `r` | Replace selected text with new content |
+| Insert | `i` | Insert text after the selection |
 | Comment | `c` | Attach a comment to selected text |
-
-Global shortcuts: `Cmd+Enter` to approve, `Cmd+Shift+Enter` to request changes.
+| Approve | `Cmd+Enter` | Approve the plan and proceed |
+| Request Changes | `Cmd+Shift+Enter` | Send annotations back to the agent |
 
 ## Development
 

package/bin/open-plan-annotator.cjs

@@ -7,10 +7,11 @@ const fs = require("fs");
 const binaryPath = path.join(__dirname, "open-plan-annotator-binary");
 const installScript = path.join(__dirname, "..", "install.cjs");
 
-// Buffer stdin immediately so it's not lost if we need to download first
+// Buffer stdin immediately so it's not lost if we need to download first.
+// Skip when stdin is a TTY (manual invocation) to avoid blocking forever.
 let stdinBuffer;
 try {
-  stdinBuffer = fs.readFileSync(0);
+  stdinBuffer = process.stdin.isTTY ? Buffer.alloc(0) : fs.readFileSync(0);
 } catch {
   stdinBuffer = Buffer.alloc(0);
 }
@@ -39,6 +40,19 @@ if (!fs.existsSync(binaryPath)) {
   }
 }
 
+// Handle `open-plan-annotator update` subcommand
+if (process.argv[2] === "update") {
+  try {
+    execFileSync(binaryPath, ["update"], {
+      stdio: "inherit",
+      env: { ...process.env, OPEN_PLAN_PKG_MANAGER: detectPackageManager() },
+    });
+  } catch (e) {
+    process.exit(e.status || 1);
+  }
+  process.exit(0);
+}
+
 // Detect package manager so the binary can suggest the right update command
 function detectPackageManager() {
   const ua = process.env.npm_config_user_agent || "";

package/install.cjs

@@ -176,9 +176,12 @@ async function main() {
   const fallbackUrl = getDownloadUrl();
   console.error(`Downloading open-plan-annotator for ${getPlatformKey()}...`);
 
+  let archiveBuffer;
+
+  // Try checksum-verified download via GitHub API first, fall back to direct URL
   try {
     const { assetName, assetUrl, expectedSha256 } = await resolveReleaseAssetAndChecksum();
-    const archiveBuffer = await fetch(assetUrl);
+    archiveBuffer = await fetch(assetUrl);
     const actualSha256 = sha256Hex(archiveBuffer);
 
     if (actualSha256 !== expectedSha256) {
@@ -186,7 +189,21 @@ async function main() {
         `Checksum verification failed for ${assetName} (expected ${expectedSha256}, got ${actualSha256})`,
       );
     }
+  } catch (verifiedErr) {
+    const message = verifiedErr && verifiedErr.message ? verifiedErr.message : String(verifiedErr);
+    console.error(`open-plan-annotator: checksum-verified install failed: ${message}`);
+    console.error(`Falling back to direct download (without checksum verification)...`);
 
+    try {
+      archiveBuffer = await fetch(fallbackUrl);
+    } catch (fallbackErr) {
+      const fbMsg = fallbackErr && fallbackErr.message ? fallbackErr.message : String(fallbackErr);
+      console.error(`open-plan-annotator: fallback download also failed: ${fbMsg}`);
+      throw verifiedErr;
+    }
+  }
+
+  try {
     const binaryBuffer = extractBinaryFromTarGz(archiveBuffer);
 
     if (!fs.existsSync(destDir)) {
@@ -203,10 +220,6 @@ async function main() {
     } catch {
       // Temp file may not exist
     }
-
-    const message = err && err.message ? err.message : String(err);
-    console.error(`open-plan-annotator: install failed: ${message}`);
-    console.error(`Fallback URL for diagnostics: ${fallbackUrl}`);
     throw err;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -33,6 +33,7 @@
   "scripts": {
     "postinstall": "node install.cjs",
     "test": "bun test",
+    "typecheck": "tsgo --noEmit --project ui/tsconfig.json && tsgo --noEmit --project server/tsconfig.json",
     "build:ui": "cd ui && bun run vite build",
     "build:platforms": "node scripts/build-platforms.cjs",
     "build": "bun run build:ui && node scripts/build-platforms.cjs",
@@ -50,7 +51,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",
-    "@types/bun": "^1.3.9"
+    "@types/bun": "^1.3.9",
+    "@typescript/native-preview": "^7.0.0-dev.20260224.1"
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.2.14",