open-plan-annotator 1.1.0 → 1.1.2

package/.claude-plugin/marketplace.json

@@ -5,19 +5,14 @@
   },
   "metadata": {
     "description": "Interactive plan annotation plugin for Claude Code",
-    "version": "1.1.0"
+    "version": "1.1.2"
   },
   "plugins": [
     {
       "name": "open-plan-annotator",
-      "source": {
-        "npm": {
-          "package": "open-plan-annotator",
-          "version": "1.1.0"
-        }
-      },
+      "source": "./",
       "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
-      "version": "1.1.0",
+      "version": "1.1.2",
       "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.1.0",
+  "version": "1.1.2",
   "author": {
     "name": "ndom91"
   },

package/README.md

@@ -1,14 +1,13 @@
-# open-plan-annotator
+![](.github/assets/header.jpg)
 
-[![npm version](https://img.shields.io/npm/v/open-plan-annotator?style=flat-square)](https://www.npmjs.com/package/open-plan-annotator)
-[![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)]()
+[![npm version](https://img.shields.io/npm/v/open-plan-annotator?style=for-the-badge&labelColor=black&color=black)](https://www.npmjs.com/package/open-plan-annotator)
+[![License: MIT](https://img.shields.io/badge/license-MIT-orange.svg?style=for-the-badge&labelColor=black&color=black)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-pink?style=for-the-badge&labelColor=black&color=black)]()
 
 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
 
@@ -20,6 +19,8 @@ Select text to <code>strikethrough</code>, <code>replace</code>, <code>insert</c
 
 Everything runs locally. Nothing leaves your machine.
 
+![](.github/assets/screenshot.png)
+
 ## Install
 
 > [!NOTE]
@@ -36,7 +37,7 @@ From within Claude Code, add the marketplace and install the plugin:
 /plugin install open-plan-annotator@ndom91-open-plan-annotator
 ```
 
-This installs the npm-backed plugin and registers the `ExitPlanMode` hook that launches the annotation UI.
+This installs the npm-backed plugin and registers the `ExitPlanMode` hook that launches the annotation UI. In Claude Code, third-party marketplaces have auto-update disabled by default, so also enable auto-update for the `ndom91-open-plan-annotator` marketplace in the Marketplace UI.
 
 ### OpenCode
 
@@ -44,7 +45,7 @@ Add `open-plan-annotator` to the `plugin` array in your OpenCode config (`openco
 
 ```json
 {
-  "plugin": ["open-plan-annotator"]
+  "plugin": ["open-plan-annotator@latest"]
 }
 ```
 
@@ -57,6 +58,9 @@ OpenCode will install the package and load it automatically. The plugin:
 
 To update, refresh the plugin through OpenCode and restart the app so it reloads the latest package-managed runtime.
 
+> [!NOTE]
+> The update mechanism changed significantly in `1.0.20+`: OpenCode now loads the npm package plus a platform runtime package instead of using the old in-place binary updater. If OpenCode appears to be stuck on an older plugin build, clear the cached `open-plan-annotator` entries under `~/.cache/opencode/node_modules/` and restart OpenCode.
+
 #### 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/`:
@@ -77,6 +81,7 @@ Set `enabled` to `false` to disable auto-handoff. Project config overrides globa
 If you want to run the CLI standalone or install the package globally:
 
 ```sh
+pnpm add -g open-plan-annotator
 npm install -g open-plan-annotator
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -26,9 +26,15 @@
   },
   "files": [
     "bin/open-plan-annotator.mjs",
-    "shared/",
+    "shared/cliHelp.mjs",
+    "shared/cliMode.mjs",
+    "shared/packageManager.mjs",
+    "shared/runtimeResolver.mjs",
+    "shared/updateHints.mjs",
     ".claude-plugin/",
-    "opencode/",
+    "opencode/bridge.js",
+    "opencode/config.js",
+    "opencode/index.js",
     "hooks/",
     "CLAUDE.md",
     "README.md"
@@ -37,10 +43,10 @@
     "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.mjs",
-    "build": "bun run build:ui && node scripts/build-platforms.mjs",
+    "build:platforms": "bun scripts/build-platforms.mjs",
+    "build": "bun run build:ui && bun run build:platforms",
     "release": "bun run build",
-    "pack:check": "node scripts/check-package-files.mjs",
+    "pack:check": "bun scripts/check-package-files.mjs",
     "dev:ui": "cd ui && bun run vite --port 5173",
     "dev:server": "NODE_ENV=development bun run server/index.ts",
     "dev": "NODE_ENV=development bun run server/index.ts & cd ui && bun run vite --port 5173",
@@ -48,11 +54,11 @@
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
     "do-release": "./scripts/release.sh",
-    "prepack": "node scripts/claude-pack-docs.mjs prepack",
-    "postpack": "node scripts/claude-pack-docs.mjs postpack"
+    "prepack": "bun scripts/claude-pack-docs.mjs prepack",
+    "postpack": "bun scripts/claude-pack-docs.mjs postpack"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
+    "@biomejs/biome": "^2.4.6",
     "@types/node": "^25.3.0",
     "@types/bun": "^1.3.9",
     "@typescript/native-preview": "^7.0.0-dev.20260224.1"
@@ -61,9 +67,10 @@
     "@opencode-ai/plugin": "^1.2.14"
   },
   "optionalDependencies": {
-    "@open-plan-annotator/runtime-darwin-arm64": "1.1.0",
-    "@open-plan-annotator/runtime-darwin-x64": "1.1.0",
-    "@open-plan-annotator/runtime-linux-arm64": "1.1.0",
-    "@open-plan-annotator/runtime-linux-x64": "1.1.0"
-  }
+    "@open-plan-annotator/runtime-darwin-arm64": "1.1.2",
+    "@open-plan-annotator/runtime-darwin-x64": "1.1.2",
+    "@open-plan-annotator/runtime-linux-arm64": "1.1.2",
+    "@open-plan-annotator/runtime-linux-x64": "1.1.2"
+  },
+  "packageManager": "bun@1.3.9"
 }

package/opencode/config.test.ts

@@ -1,110 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { resolveImplementationHandoff } from "./config.js";
-
-function withEnv(key: string, value: string | undefined, fn: () => Promise<void>) {
-  const original = process.env[key];
-  if (value === undefined) {
-    delete process.env[key];
-  } else {
-    process.env[key] = value;
-  }
-
-  return fn().finally(() => {
-    if (original === undefined) {
-      delete process.env[key];
-    } else {
-      process.env[key] = original;
-    }
-  });
-}
-
-describe("resolveImplementationHandoff", () => {
-  test("returns defaults when no config files exist", async () => {
-    const tempRoot = mkdtempSync(join(tmpdir(), "open-plan-annotator-config-"));
-
-    try {
-      await withEnv("XDG_CONFIG_HOME", join(tempRoot, "xdg"), async () => {
-        const result = await resolveImplementationHandoff(join(tempRoot, "project"));
-        expect(result.enabled).toBe(true);
-        expect(result.agent).toBe("build");
-      });
-    } finally {
-      rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-
-  test("uses global config when project config is missing", async () => {
-    const tempRoot = mkdtempSync(join(tmpdir(), "open-plan-annotator-config-"));
-    const xdgHome = join(tempRoot, "xdg");
-    const globalConfigDir = join(xdgHome, "opencode");
-    mkdirSync(globalConfigDir, { recursive: true });
-    writeFileSync(
-      join(globalConfigDir, "open-plan-annotator.json"),
-      JSON.stringify({ implementationHandoff: { enabled: false, agent: "explore" } }),
-      "utf8",
-    );
-
-    try {
-      await withEnv("XDG_CONFIG_HOME", xdgHome, async () => {
-        const result = await resolveImplementationHandoff(join(tempRoot, "project"));
-        expect(result.enabled).toBe(false);
-        expect(result.agent).toBe("explore");
-      });
-    } finally {
-      rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-
-  test("project config overrides global config", async () => {
-    const tempRoot = mkdtempSync(join(tmpdir(), "open-plan-annotator-config-"));
-    const xdgHome = join(tempRoot, "xdg");
-    const globalConfigDir = join(xdgHome, "opencode");
-    const projectDir = join(tempRoot, "project");
-    const projectConfigDir = join(projectDir, ".opencode");
-
-    mkdirSync(globalConfigDir, { recursive: true });
-    mkdirSync(projectConfigDir, { recursive: true });
-
-    writeFileSync(
-      join(globalConfigDir, "open-plan-annotator.json"),
-      JSON.stringify({ implementationHandoff: { enabled: true, agent: "explore" } }),
-      "utf8",
-    );
-    writeFileSync(
-      join(projectConfigDir, "open-plan-annotator.json"),
-      JSON.stringify({ implementationHandoff: { enabled: false, agent: "build" } }),
-      "utf8",
-    );
-
-    try {
-      await withEnv("XDG_CONFIG_HOME", xdgHome, async () => {
-        const result = await resolveImplementationHandoff(projectDir);
-        expect(result.enabled).toBe(false);
-        expect(result.agent).toBe("build");
-      });
-    } finally {
-      rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-
-  test("ignores malformed config and falls back", async () => {
-    const tempRoot = mkdtempSync(join(tmpdir(), "open-plan-annotator-config-"));
-    const xdgHome = join(tempRoot, "xdg");
-    const globalConfigDir = join(xdgHome, "opencode");
-    mkdirSync(globalConfigDir, { recursive: true });
-    writeFileSync(join(globalConfigDir, "open-plan-annotator.json"), "not-json", "utf8");
-
-    try {
-      await withEnv("XDG_CONFIG_HOME", xdgHome, async () => {
-        const result = await resolveImplementationHandoff(join(tempRoot, "project"));
-        expect(result.enabled).toBe(true);
-        expect(result.agent).toBe("build");
-      });
-    } finally {
-      rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-});

package/opencode/index.test.ts

@@ -1,54 +0,0 @@
-import { afterEach, describe, expect, mock, test } from "bun:test";
-
-afterEach(() => {
-  mock.restore();
-});
-
-function createPluginContext() {
-  return {
-    directory: process.cwd(),
-    client: {
-      session: {
-        messages: async () => ({ data: [] }),
-        prompt: async () => ({ data: null }),
-      },
-      app: {
-        agents: async () => ({ data: [] }),
-      },
-    },
-  };
-}
-
-describe("submit_plan tool output", () => {
-  test("returns plain text execution instructions after approval", async () => {
-    mock.module("./bridge.js", () => ({
-      runPlanReview: async () => ({ approved: true }),
-    }));
-
-    const { OpenPlanAnnotatorPlugin } = await import(`./index.js?approved-${Date.now()}`);
-    const plugin = await OpenPlanAnnotatorPlugin(createPluginContext());
-
-    const result = await plugin.tool.submit_plan.execute({ plan: "# Plan" }, { sessionID: "session-1" });
-
-    expect(typeof result).toBe("string");
-    expect(result).toContain("plan_status=approved");
-    expect(result).toContain("next_state=EXECUTION");
-    expect(result).toContain("Do not call `submit_plan` again");
-  });
-
-  test("returns plain text revision instructions after rejection", async () => {
-    mock.module("./bridge.js", () => ({
-      runPlanReview: async () => ({ approved: false, feedback: "Need rollback steps." }),
-    }));
-
-    const { OpenPlanAnnotatorPlugin } = await import(`./index.js?rejected-${Date.now()}`);
-    const plugin = await OpenPlanAnnotatorPlugin(createPluginContext());
-
-    const result = await plugin.tool.submit_plan.execute({ plan: "# Plan" }, { sessionID: "session-2" });
-
-    expect(typeof result).toBe("string");
-    expect(result).toContain("plan_status=rejected");
-    expect(result).toContain("next_state=PLAN_DRAFT");
-    expect(result).toContain("Need rollback steps.");
-  });
-});

package/shared/cliHelp.test.ts

@@ -1,29 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { buildCliHelpText, buildUnknownCommandPrefix } from "./cliHelp.mjs";
-
-describe("buildCliHelpText", () => {
-  test("builds canonical help text for all entrypoints", () => {
-    expect(buildCliHelpText("1.2.3")).toBe(`open-plan-annotator v1.2.3
-
-Usage:
-  open-plan-annotator              Show this help
-  open-plan-annotator < event.json Run as a Claude Code hook (debug)
-  open-plan-annotator doctor       Show resolved runtime details
-  open-plan-annotator update       Show package-managed update guidance
-  open-plan-annotator upgrade      Alias for update
-  open-plan-annotator --version    Print version
-  open-plan-annotator --help       Show this help
-
-https://github.com/ndom91/open-plan-annotator`);
-  });
-});
-
-describe("buildUnknownCommandPrefix", () => {
-  test("formats unknown command prefix consistently", () => {
-    expect(buildUnknownCommandPrefix("wat")).toBe("open-plan-annotator: unknown command `wat`");
-  });
-
-  test("handles missing command safely", () => {
-    expect(buildUnknownCommandPrefix(undefined)).toBe("open-plan-annotator: unknown command ``");
-  });
-});

package/shared/cliMode.test.ts

@@ -1,35 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { resolveCliMode } from "./cliMode.mjs";
-
-describe("resolveCliMode", () => {
-  test("returns help for no-arg interactive invocation", () => {
-    expect(resolveCliMode(undefined, { stdinIsTTY: true })).toBe("help");
-  });
-
-  test("returns hook for no-arg piped invocation", () => {
-    expect(resolveCliMode(undefined, { stdinIsTTY: false })).toBe("hook");
-  });
-
-  test("defaults no-arg invocation to hook mode", () => {
-    expect(resolveCliMode(undefined)).toBe("hook");
-  });
-
-  test("treats upgrade as update alias", () => {
-    expect(resolveCliMode("upgrade")).toBe("update");
-  });
-
-  test("recognizes doctor subcommand", () => {
-    expect(resolveCliMode("doctor")).toBe("doctor");
-  });
-
-  test("recognizes help and version flags", () => {
-    expect(resolveCliMode("--help")).toBe("help");
-    expect(resolveCliMode("-h")).toBe("help");
-    expect(resolveCliMode("--version")).toBe("version");
-    expect(resolveCliMode("-v")).toBe("version");
-  });
-
-  test("marks unknown commands explicitly", () => {
-    expect(resolveCliMode("noop")).toBe("unknown");
-  });
-});

package/shared/packageManager.test.ts

@@ -1,33 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { detectPackageManager } from "./packageManager.mjs";
-
-describe("detectPackageManager", () => {
-  test("prefers explicit OPEN_PLAN_PKG_MANAGER", () => {
-    expect(detectPackageManager({ env: { OPEN_PLAN_PKG_MANAGER: "pnpm" } })).toBe("pnpm");
-  });
-
-  test("detects package manager from npm user agent", () => {
-    expect(detectPackageManager({ env: { npm_config_user_agent: "pnpm/10.0.0 node/v22.0.0" } })).toBe("pnpm");
-  });
-
-  test("detects package manager from npm execpath", () => {
-    expect(detectPackageManager({ env: { npm_execpath: "/usr/local/lib/node_modules/pnpm/bin/pnpm.cjs" } })).toBe(
-      "pnpm",
-    );
-  });
-
-  test("detects package manager from install path hints", () => {
-    expect(
-      detectPackageManager({
-        env: {},
-        installPath: "/Users/test/Library/pnpm/global/5/node_modules/open-plan-annotator/bin/open-plan-annotator.mjs",
-      }),
-    ).toBe("pnpm");
-  });
-
-  test("falls back to npm", () => {
-    expect(detectPackageManager({ env: {}, installPath: "/tmp/open-plan-annotator/bin/open-plan-annotator.mjs" })).toBe(
-      "npm",
-    );
-  });
-});

package/shared/runtimeResolver.test.ts

@@ -1,36 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { getRuntimePackageName, resolveRuntimeBinary } from "./runtimeResolver.mjs";
-
-describe("runtimeResolver", () => {
-  test("maps supported platforms to runtime packages", () => {
-    expect(getRuntimePackageName("darwin", "arm64")).toBe("@open-plan-annotator/runtime-darwin-arm64");
-    expect(getRuntimePackageName("linux", "x64")).toBe("@open-plan-annotator/runtime-linux-x64");
-  });
-
-  test("throws for unsupported platforms", () => {
-    expect(() => resolveRuntimeBinary({ platform: "win32", arch: "x64" })).toThrow("Unsupported platform win32-x64");
-  });
-
-  test("resolves binary from installed runtime package", () => {
-    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "opa-runtime-"));
-    const packageRoot = path.join(tempRoot, "node_modules", "@open-plan-annotator", "runtime-linux-x64");
-    const binaryPath = path.join(packageRoot, "bin", "open-plan-annotator");
-
-    fs.mkdirSync(path.dirname(binaryPath), { recursive: true });
-    fs.writeFileSync(path.join(packageRoot, "package.json"), '{"name":"@open-plan-annotator/runtime-linux-x64"}');
-    fs.writeFileSync(binaryPath, "binary");
-
-    const resolved = resolveRuntimeBinary({
-      platform: "linux",
-      arch: "x64",
-      parentUrl: pathToFileURL(path.join(tempRoot, "index.mjs")).href,
-    });
-
-    expect(resolved.packageName).toBe("@open-plan-annotator/runtime-linux-x64");
-    expect(fs.realpathSync(resolved.binaryPath)).toBe(fs.realpathSync(binaryPath));
-  });
-});