open-plan-annotator 1.0.17 → 1.0.20

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -23,11 +23,9 @@ Everything runs locally. Nothing leaves your machine.
 ## Install
 
 > [!NOTE]
-> The first run might take up to 30s to pop open the UI. If your agentic coding
-> tool installed it via pnpm, they block post-install scripts by default so
-> Claude / OpenCode will trigger the download of the correct binary for your
-> platform upon first use, i.e. when first transitioning out of plan mode.
-> All subsequent runs will be instant.
+> `open-plan-annotator` now ships as one package-managed install. The npm package
+> contains the plugin glue and resolves a platform runtime package locally. There
+> is no first-run binary download and no in-app self-update path.
 
 ### Claude Code
 
@@ -38,7 +36,7 @@ From within Claude Code, add the marketplace and install the plugin:
 /plugin install open-plan-annotator@ndom91-open-plan-annotator
 ```
 
-This 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.
 
 ### OpenCode
 
@@ -57,6 +55,8 @@ 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
 
+To update, refresh the plugin through OpenCode and restart the app so it reloads the latest package-managed runtime.
+
 #### 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/`:
@@ -74,7 +74,7 @@ Set `enabled` to `false` to disable auto-handoff. Project config overrides globa
 
 ### Manual Install
 
-If you want to run the binary standalone or build from source:
+If you want to run the CLI standalone or install the package globally:
 
 ```sh
 npm install -g open-plan-annotator
@@ -95,6 +95,18 @@ Then load it directly in Claude Code:
 claude --plugin-dir ./open-plan-annotator
 ```
 
+## Updates
+
+- OpenCode: update the installed npm plugin through OpenCode, then restart OpenCode.
+- Claude Code: update the marketplace/plugin install, then restart Claude Code.
+- Standalone/global install: update the npm package (`npm`, `pnpm`, or `bun`), then rerun `open-plan-annotator`.
+
+The built-in `doctor` command reports the resolved runtime package and runtime path:
+
+```sh
+open-plan-annotator doctor
+```
+
 ## Keyboard Shortcuts
 
 | Action | Shortcut | Description |

package/bin/open-plan-annotator.mjs

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 
-import { execFileSync, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildCliHelpText, buildUnknownCommandPrefix } from "../shared/cliHelp.mjs";
 import { resolveCliMode } from "../shared/cliMode.mjs";
+import { resolveRuntimeBinary } from "../shared/runtimeResolver.mjs";
+import { buildUpdateInstructions } from "../shared/updateHints.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const binaryPath = path.join(__dirname, "open-plan-annotator-binary");
-const installScript = path.join(__dirname, "..", "install.mjs");
 const VERSION = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version;
 
 const arg = process.argv[2];
@@ -25,6 +25,11 @@ if (cliMode === "help") {
   process.exit(0);
 }
 
+if (cliMode === "doctor") {
+  printDoctor();
+  process.exit(0);
+}
+
 if (cliMode === "unknown") {
   console.error(buildUnknownCommandPrefix(arg));
   console.error("Run `open-plan-annotator --help` for usage.");
@@ -44,46 +49,8 @@ if (cliMode === "hook") {
   stdinBuffer = Buffer.alloc(0);
 }
 
-let justInstalled = false;
-if (!fs.existsSync(binaryPath)) {
-  // Auto-download the binary (handles pnpm blocking postinstall)
-  console.error("open-plan-annotator: binary not found, downloading...");
-  try {
-    execFileSync(process.execPath, [installScript], {
-      stdio: ["ignore", 2, "inherit"],
-    });
-  } catch (e) {
-    console.error(
-      "\nopen-plan-annotator: failed to download binary.\n" +
-      "Try running manually: node " + installScript + "\n"
-    );
-    process.exit(1);
-  }
-
-  if (!fs.existsSync(binaryPath)) {
-    console.error(
-      "open-plan-annotator: binary still not found after install.\n" +
-      "Try running manually: node " + installScript + "\n"
-    );
-    process.exit(1);
-  }
-  justInstalled = true;
-}
-
-// Handle `open-plan-annotator update|upgrade` subcommand
 if (cliMode === "update") {
-  if (justInstalled) {
-    console.log("Binary installed (v" + VERSION + ")");
-    process.exit(0);
-  }
-  try {
-    execFileSync(binaryPath, ["update"], {
-      stdio: "inherit",
-      env: { ...process.env, OPEN_PLAN_PKG_MANAGER: detectPackageManager() },
-    });
-  } catch (e) {
-    process.exit(e.status || 1);
-  }
+  console.log(buildUpdateInstructions({ host: process.env.OPEN_PLAN_HOST, packageManager: detectPackageManager() }));
   process.exit(0);
 }
 
@@ -96,13 +63,22 @@ function detectPackageManager() {
   return "npm";
 }
 
-// Spawn the binary with detached so it can outlive this wrapper.
-// We pipe stdout to detect the JSON hook output, then forward it and exit
-// immediately — the binary keeps its server alive in the background.
-const child = spawn(binaryPath, process.argv.slice(2), {
+let runtime;
+try {
+  runtime = resolveRuntimeBinary({ parentUrl: import.meta.url });
+} catch (error) {
+  console.error(`open-plan-annotator: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
+
+const child = spawn(runtime.binaryPath, process.argv.slice(2), {
   stdio: ["pipe", "pipe", "inherit"],
   detached: true,
-  env: { ...process.env, OPEN_PLAN_PKG_MANAGER: detectPackageManager() },
+  env: {
+    ...process.env,
+    OPEN_PLAN_HOST: process.env.OPEN_PLAN_HOST || "claude-code",
+    OPEN_PLAN_PKG_MANAGER: detectPackageManager(),
+  },
 });
 
 child.stdin.write(stdinBuffer);
@@ -149,3 +125,26 @@ child.on("error", (err) => {
   console.error("open-plan-annotator: failed to spawn binary:", err.message);
   process.exit(1);
 });
+
+function printDoctor() {
+  const platformKey = `${process.platform}-${process.arch}`;
+
+  try {
+    const runtime = resolveRuntimeBinary({ parentUrl: import.meta.url });
+    console.log([
+      `open-plan-annotator v${VERSION}`,
+      `platform: ${platformKey}`,
+      `runtime package: ${runtime.packageName}`,
+      `runtime path: ${runtime.binaryPath}`,
+      `update: ${buildUpdateInstructions({ host: process.env.OPEN_PLAN_HOST, packageManager: detectPackageManager() })}`,
+    ].join("\n"));
+  } catch (error) {
+    console.log([
+      `open-plan-annotator v${VERSION}`,
+      `platform: ${platformKey}`,
+      `runtime: missing`,
+      `error: ${error instanceof Error ? error.message : String(error)}`,
+      `update: ${buildUpdateInstructions({ host: process.env.OPEN_PLAN_HOST, packageManager: detectPackageManager() })}`,
+    ].join("\n"));
+  }
+}

package/opencode/bridge.js

@@ -1,15 +1,11 @@
-import { execFileSync, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveRuntimeBinary } from "../shared/runtimeResolver.mjs";
 
 const PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
-const LOCAL_BINARY_PATH = join(PKG_ROOT, "bin", "open-plan-annotator-binary");
-const INSTALL_SCRIPT = join(PKG_ROOT, "install.mjs");
-
-/** Resolved path to the binary (may differ from LOCAL_BINARY_PATH if found on PATH). */
-let BINARY_PATH = LOCAL_BINARY_PATH;
 
 /**
  * @typedef {{
@@ -102,27 +98,6 @@ function validateHookOutput(value) {
   throw new Error("unsupported decision payload");
 }
 
-/**
- * Check if `open-plan-annotator` is available on PATH.
- * The CLI wrapper handles binary discovery/download and stdin/stdout
- * forwarding, so we can spawn it directly as a fallback when the local
- * binary isn't available (e.g. OpenCode loads the plugin from its own
- * node_modules but the binary only exists in a global pnpm install).
- * @returns {string | undefined}
- */
-function findWrapperOnPath() {
-  const cmd = process.platform === "win32" ? "where" : "which";
-  try {
-    const result = execFileSync(cmd, ["open-plan-annotator"], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim().split("\n")[0];
-    return result || undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 function detectPackageManager() {
   const ua = process.env.npm_config_user_agent || "";
   if (ua.startsWith("pnpm")) return "pnpm";
@@ -131,55 +106,11 @@ function detectPackageManager() {
   return "npm";
 }
 
-/** Ensure the compiled binary exists, downloading if necessary. */
-function ensureBinary() {
-  if (existsSync(LOCAL_BINARY_PATH)) {
-    BINARY_PATH = LOCAL_BINARY_PATH;
-    return;
-  }
-
-  // Try to find node on PATH for running the install script
-  try {
-    execFileSync(process.execPath, [INSTALL_SCRIPT], {
-      cwd: PKG_ROOT,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-  } catch {
-    // Retry with "node" explicitly in case process.execPath is bun
-    try {
-      execFileSync("node", [INSTALL_SCRIPT], {
-        cwd: PKG_ROOT,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-    } catch {
-      // ignore — we'll check below
-    }
-  }
-
-  if (existsSync(LOCAL_BINARY_PATH)) {
-    BINARY_PATH = LOCAL_BINARY_PATH;
-    return;
-  }
-
-  // Fallback: use the CLI wrapper from PATH (e.g. global pnpm install).
-  // The wrapper handles binary discovery/download and stdio forwarding.
-  const wrapperPath = findWrapperOnPath();
-  if (wrapperPath) {
-    BINARY_PATH = wrapperPath;
-    return;
-  }
-
-  throw new Error(
-    `open-plan-annotator: binary not found at ${LOCAL_BINARY_PATH}. ` +
-      `Try running: node ${INSTALL_SCRIPT}`,
-  );
-}
-
 /**
  * @param {{ plan: string, sessionId?: string, cwd?: string }} options
  */
 export async function runPlanReview(options) {
-  ensureBinary();
+  const runtime = resolveRuntimeBinary({ parentUrl: import.meta.url });
 
   const payload = buildHookPayload(options);
 
@@ -197,11 +128,12 @@ export async function runPlanReview(options) {
 
     // Spawn detached so the binary can outlive this call — it keeps its
     // HTTP server alive for ~10s after emitting the JSON hook response.
-    const child = spawn(BINARY_PATH, [], {
+    const child = spawn(runtime.binaryPath, [], {
       cwd,
       stdio: ["pipe", "pipe", "pipe"],
       env: {
         ...process.env,
+        OPEN_PLAN_HOST: "opencode",
         OPEN_PLAN_PKG_MANAGER: process.env.OPEN_PLAN_PKG_MANAGER || detectPackageManager(),
       },
       detached: true,

package/opencode/index.js

@@ -162,7 +162,7 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
     tool: {
       submit_plan: tool({
         description:
-          "Submit a markdown plan for interactive user review. Returns a structured result with plan_status, next_state, feedback, and guidance fields.",
+          "Submit a markdown plan for interactive user review. Returns plain-text execution or revision instructions for the agent.",
 
         args: {
           plan: tool.schema.string().describe("The complete implementation plan in markdown format"),
@@ -178,17 +178,8 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
 
           const feedback = result.approved ? "" : (result.feedback ?? "Plan changes requested.");
 
-          const basePayload = {
-            plan_status: result.approved ? "approved" : "rejected",
-            next_state: result.approved ? "EXECUTION" : "PLAN_DRAFT",
-            feedback,
-          };
-
           if (result.approved) {
-            const lines = [
-              "Plan approved by the user.",
-              "Do NOT call `submit_plan` again. The planning phase is finished.",
-            ];
+            const lines = ["Plan review status: plan_status=approved.", "State transition: next_state=EXECUTION."];
 
             if (args.summary) {
               lines.push(`Summary: ${args.summary}`);
@@ -203,25 +194,23 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
               }
             }
 
-            lines.push("Begin implementing the approved plan now — write code and make changes.");
-            return {
-              ...basePayload,
-              guidance: lines.join("\n\n"),
-            };
+            lines.push("Replan intent: explicit_replan=false unless the user explicitly asks to revise the plan.");
+            lines.push("Execute the approved plan directly now — write code, create files, and make changes.");
+            lines.push("Do not call `submit_plan` again unless the user explicitly requests re-planning.");
+
+            return lines.join("\n\n");
           }
 
-          return {
-            ...basePayload,
-            guidance: [
-              "Plan needs revision.",
-              "",
-              "## User feedback",
-              "",
-              feedback,
-              "",
-              "Revise the plan using this feedback, then submit the revised draft once via `submit_plan`.",
-            ].join("\n"),
-          };
+          return [
+            "Plan review status: plan_status=rejected.",
+            "State transition: next_state=PLAN_DRAFT.",
+            "",
+            "## User feedback",
+            "",
+            feedback,
+            "",
+            "Revise the plan using this feedback, then submit the revised draft once via `submit_plan`.",
+          ].join("\n");
         },
       }),
     },

package/opencode/index.test.ts

@@ -19,8 +19,8 @@ function createPluginContext() {
   };
 }
 
-describe("submit_plan return schema contract", () => {
-  test("approved decision maps to approved execution payload", async () => {
+describe("submit_plan tool output", () => {
+  test("returns plain text execution instructions after approval", async () => {
     mock.module("./bridge.js", () => ({
       runPlanReview: async () => ({ approved: true }),
     }));
@@ -30,17 +30,15 @@ describe("submit_plan return schema contract", () => {
 
     const result = await plugin.tool.submit_plan.execute({ plan: "# Plan" }, { sessionID: "session-1" });
 
-    expect(result.plan_status).toBe("approved");
-    expect(result.next_state).toBe("EXECUTION");
-    expect(result.feedback).toBe("");
-    expect(result.guidance).toContain("Plan approved by the user.");
+    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("rejected decision maps to plan redraft payload with bridge feedback", async () => {
-    const bridgeFeedback = "Need to add rollback steps.";
-
+  test("returns plain text revision instructions after rejection", async () => {
     mock.module("./bridge.js", () => ({
-      runPlanReview: async () => ({ approved: false, feedback: bridgeFeedback }),
+      runPlanReview: async () => ({ approved: false, feedback: "Need rollback steps." }),
     }));
 
     const { OpenPlanAnnotatorPlugin } = await import(`./index.js?rejected-${Date.now()}`);
@@ -48,29 +46,9 @@ describe("submit_plan return schema contract", () => {
 
     const result = await plugin.tool.submit_plan.execute({ plan: "# Plan" }, { sessionID: "session-2" });
 
-    expect(result.plan_status).toBe("rejected");
-    expect(result.next_state).toBe("PLAN_DRAFT");
-    expect(result.feedback).toBe(bridgeFeedback);
-    expect(result.guidance).toContain("## User feedback");
-  });
-
-  test("all top-level submit_plan fields are strings for display safety", async () => {
-    mock.module("./bridge.js", () => ({
-      runPlanReview: async () => ({ approved: true }),
-    }));
-
-    const { OpenPlanAnnotatorPlugin } = await import(`./index.js?display-safe-${Date.now()}`);
-    const plugin = await OpenPlanAnnotatorPlugin(createPluginContext());
-
-    const result = await plugin.tool.submit_plan.execute(
-      { plan: "# Plan", summary: "Short summary" },
-      { sessionID: "session-3" },
-    );
-
-    for (const value of Object.values(result)) {
-      expect(typeof value).toBe("string");
-    }
-
-    expect(result).not.toHaveProperty("approved");
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.0.17",
+  "version": "1.0.20",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -17,13 +17,15 @@
     "annotation",
     "code-review"
   ],
+  "workspaces": [
+    "packages/*"
+  ],
   "main": "opencode/index.js",
   "bin": {
     "open-plan-annotator": "bin/open-plan-annotator.mjs"
   },
   "files": [
     "bin/open-plan-annotator.mjs",
-    "install.mjs",
     "shared/",
     ".claude-plugin/",
     "opencode/",
@@ -32,14 +34,12 @@
     "README.md"
   ],
   "scripts": {
-    "postinstall": "node install.mjs",
     "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",
-    "tarball": "node scripts/tarball.mjs",
-    "release": "bun run build && node scripts/tarball.mjs",
+    "release": "bun run build",
     "pack:check": "node scripts/check-package-files.mjs",
     "dev:ui": "cd ui && bun run vite --port 5173",
     "dev:server": "NODE_ENV=development bun run server/index.ts",
@@ -59,5 +59,11 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.2.14"
+  },
+  "optionalDependencies": {
+    "@open-plan-annotator/runtime-darwin-arm64": "1.0.20",
+    "@open-plan-annotator/runtime-darwin-x64": "1.0.20",
+    "@open-plan-annotator/runtime-linux-arm64": "1.0.20",
+    "@open-plan-annotator/runtime-linux-x64": "1.0.20"
   }
 }

package/shared/cliHelp.mjs

@@ -3,7 +3,8 @@ const REPOSITORY_URL = "https://github.com/ndom91/open-plan-annotator";
 const HELP_USAGE_LINES = [
   "open-plan-annotator              Show this help",
   "open-plan-annotator < event.json Run as a Claude Code hook (debug)",
-  "open-plan-annotator update       Update the binary to the latest version",
+  "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",

package/shared/cliHelp.test.ts

@@ -8,7 +8,8 @@ describe("buildCliHelpText", () => {
 Usage:
   open-plan-annotator              Show this help
   open-plan-annotator < event.json Run as a Claude Code hook (debug)
-  open-plan-annotator update       Update the binary to the latest version
+  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

package/shared/cliMode.mjs

@@ -1,5 +1,5 @@
 /**
- * @typedef {"hook" | "update" | "help" | "version" | "unknown"} CliMode
+ * @typedef {"hook" | "update" | "doctor" | "help" | "version" | "unknown"} CliMode
  */
 
 /**
@@ -17,6 +17,7 @@ export function resolveCliMode(arg, options = {}) {
   }
 
   if (arg === "update" || arg === "upgrade") return "update";
+  if (arg === "doctor") return "doctor";
   if (arg === "--help" || arg === "-h") return "help";
   if (arg === "--version" || arg === "-v") return "version";
   return "unknown";

package/shared/cliMode.test.ts

@@ -18,6 +18,10 @@ describe("resolveCliMode", () => {
     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");

package/shared/runtimeResolver.mjs

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+export const RUNTIME_PACKAGE_MAP = {
+  "darwin-arm64": "@open-plan-annotator/runtime-darwin-arm64",
+  "darwin-x64": "@open-plan-annotator/runtime-darwin-x64",
+  "linux-arm64": "@open-plan-annotator/runtime-linux-arm64",
+  "linux-x64": "@open-plan-annotator/runtime-linux-x64",
+};
+
+export function getRuntimePlatformKey(platform = process.platform, arch = process.arch) {
+  return `${platform}-${arch}`;
+}
+
+export function getRuntimePackageName(platform = process.platform, arch = process.arch) {
+  return RUNTIME_PACKAGE_MAP[getRuntimePlatformKey(platform, arch)];
+}
+
+export function resolveRuntimeBinary(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  const packageName = getRuntimePackageName(platform, arch);
+
+  if (!packageName) {
+    throw new Error(`Unsupported platform ${getRuntimePlatformKey(platform, arch)}`);
+  }
+
+  const requireFrom = createRequire(options.parentUrl ?? import.meta.url);
+  const workspaceRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+  let packageJsonPath;
+  try {
+    packageJsonPath = requireFrom.resolve(`${packageName}/package.json`);
+  } catch {
+    const workspaceBinaryPath = path.join(workspaceRoot, "packages", packageName.split("/").at(-1) ?? "", "bin", "open-plan-annotator");
+    if (fs.existsSync(workspaceBinaryPath)) {
+      return {
+        packageName,
+        packageRoot: path.dirname(path.dirname(workspaceBinaryPath)),
+        binaryPath: workspaceBinaryPath,
+      };
+    }
+
+    throw new Error(
+      `Missing runtime package ${packageName}. Reinstall open-plan-annotator for ${getRuntimePlatformKey(platform, arch)}.`,
+    );
+  }
+
+  const packageRoot = path.dirname(packageJsonPath);
+  const binaryPath = path.join(packageRoot, "bin", "open-plan-annotator");
+
+  if (!fs.existsSync(binaryPath)) {
+    throw new Error(`Runtime package ${packageName} is installed but ${binaryPath} is missing. Rebuild or reinstall it.`);
+  }
+
+  return {
+    packageName,
+    packageRoot,
+    binaryPath,
+  };
+}

package/shared/runtimeResolver.test.ts

@@ -0,0 +1,36 @@
+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));
+  });
+});

package/shared/updateHints.mjs

@@ -0,0 +1,14 @@
+export function buildUpdateInstructions(options = {}) {
+  const host = options.host ?? process.env.OPEN_PLAN_HOST;
+  const packageManager = options.packageManager ?? "npm";
+
+  if (host === "opencode") {
+    return "Refresh the OpenCode plugin install, then restart OpenCode.";
+  }
+
+  if (host === "claude-code") {
+    return "Refresh the Claude Code plugin or marketplace install, then restart Claude Code.";
+  }
+
+  return `Update open-plan-annotator via ${packageManager}, then rerun it.`;
+}

package/install.mjs

@@ -1,218 +0,0 @@
-#!/usr/bin/env node
-
-import crypto from "node:crypto";
-import fs from "node:fs";
-import https from "node:https";
-import path from "node:path";
-import {
-  PLATFORM_ASSET_BASENAME_MAP,
-  REPO,
-  getPlatformAssetArchiveName,
-  getPlatformKey,
-  parseChecksumManifest,
-  selectChecksumAsset,
-} from "./shared/releaseAssets.mjs";
-import { fileURLToPath } from "node:url";
-import zlib from "node:zlib";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const VERSION = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
-
-function getReleaseApiUrl() {
-  return `https://api.github.com/repos/${REPO}/releases/tags/v${VERSION}`;
-}
-
-function fetch(url, redirects) {
-  if (redirects === undefined) redirects = 5;
-  return new Promise((resolve, reject) => {
-    https
-      .get(url, { headers: { "User-Agent": "open-plan-annotator-install" } }, (res) => {
-        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-          if (redirects <= 0) return reject(new Error("Too many redirects"));
-          return fetch(res.headers.location, redirects - 1).then(resolve, reject);
-        }
-        if (res.statusCode < 200 || res.statusCode >= 300) {
-          return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
-        }
-        const chunks = [];
-        res.on("data", (c) => chunks.push(c));
-        res.on("end", () => resolve(Buffer.concat(chunks)));
-      })
-      .on("error", reject);
-  });
-}
-
-async function fetchJson(url) {
-  const buffer = await fetch(url);
-  return JSON.parse(buffer.toString("utf8"));
-}
-
-function sha256Hex(buffer) {
-  return crypto.createHash("sha256").update(buffer).digest("hex");
-}
-
-async function resolveReleaseAssetAndChecksum(options) {
-  const opts = options || {};
-  const fetchJsonImpl = opts.fetchJson || fetchJson;
-  const fetchBuffer = opts.fetch || fetch;
-  const releaseApiUrl = opts.releaseApiUrl || getReleaseApiUrl();
-  const version = opts.version || VERSION;
-
-  const release = await fetchJsonImpl(releaseApiUrl);
-  const releaseAssets = Array.isArray(release.assets) ? release.assets : [];
-  const key = opts.platformKey || getPlatformKey();
-  const assetName = getPlatformAssetArchiveName(key);
-  if (!assetName) {
-    throw new Error(`Unsupported platform ${key}`);
-  }
-
-  const asset = releaseAssets.find((entry) => entry.name === assetName);
-  if (!asset) {
-    throw new Error(`Release v${version} is missing asset ${assetName}`);
-  }
-
-  const checksumAsset = selectChecksumAsset(releaseAssets);
-  if (!checksumAsset) {
-    throw new Error(`Release v${version} does not contain a checksum manifest asset`);
-  }
-
-  const checksumManifest = (await fetchBuffer(checksumAsset.browser_download_url)).toString("utf8");
-  const checksums = parseChecksumManifest(checksumManifest);
-  const expectedSha256 = checksums.get(assetName);
-  if (!expectedSha256) {
-    throw new Error(`Checksum manifest does not contain ${assetName}`);
-  }
-
-  return {
-    assetName,
-    assetUrl: asset.browser_download_url,
-    expectedSha256,
-  };
-}
-
-function errorMessage(err) {
-  return err && err.message ? err.message : String(err);
-}
-
-async function downloadVerifiedArchive(options) {
-  const opts = options || {};
-  const resolveRelease = opts.resolveReleaseAssetAndChecksum || resolveReleaseAssetAndChecksum;
-  const fetchBuffer = opts.fetch || fetch;
-  const checksumRequirement =
-    "open-plan-annotator requires release checksum/sha256sum availability and will not install without verification.";
-
-  let releaseInfo;
-
-  try {
-    releaseInfo = await resolveRelease();
-  } catch (err) {
-    throw new Error(`Unable to verify release checksums: ${errorMessage(err)} ${checksumRequirement}`);
-  }
-
-  const { assetName, assetUrl, expectedSha256 } = releaseInfo;
-  const archiveBuffer = await fetchBuffer(assetUrl);
-  const actualSha256 = sha256Hex(archiveBuffer);
-
-  if (actualSha256 !== expectedSha256) {
-    throw new Error(
-      `Checksum verification failed for ${assetName} (expected ${expectedSha256}, got ${actualSha256}). ${checksumRequirement}`,
-    );
-  }
-
-  return archiveBuffer;
-}
-
-function extractBinaryFromTarGz(buffer) {
-  const tarBuffer = zlib.gunzipSync(buffer);
-  let offset = 0;
-
-  while (offset < tarBuffer.length) {
-    const header = tarBuffer.subarray(offset, offset + 512);
-    offset += 512;
-
-    const name = header.toString("utf-8", 0, 100).replace(/\0.*/g, "");
-    const sizeStr = header.toString("utf-8", 124, 136).replace(/\0.*/g, "").trim();
-    const size = parseInt(sizeStr, 8);
-
-    if (!name || isNaN(size)) break;
-
-    if (name === "open-plan-annotator" || name.endsWith("/open-plan-annotator")) {
-      return tarBuffer.subarray(offset, offset + size);
-    }
-
-    offset += Math.ceil(size / 512) * 512;
-  }
-
-  throw new Error("Binary 'open-plan-annotator' not found in archive");
-}
-
-async function main() {
-  const destDir = path.join(__dirname, "bin");
-  const destPath = path.join(destDir, "open-plan-annotator-binary");
-  const tempPath = `${destPath}.tmp-${process.pid}-${Date.now()}`;
-
-  // Skip if binary already exists
-  if (fs.existsSync(destPath)) {
-    return;
-  }
-
-  console.error(`Downloading open-plan-annotator for ${getPlatformKey()}...`);
-  const archiveBuffer = await downloadVerifiedArchive();
-
-  try {
-    const binaryBuffer = extractBinaryFromTarGz(archiveBuffer);
-
-    if (!fs.existsSync(destDir)) {
-      fs.mkdirSync(destDir, { recursive: true });
-    }
-
-    fs.writeFileSync(tempPath, binaryBuffer, { mode: 0o755 });
-    fs.renameSync(tempPath, destPath);
-    fs.chmodSync(destPath, 0o755);
-    console.error(`Installed open-plan-annotator to ${destPath}`);
-  } catch (err) {
-    try {
-      fs.unlinkSync(tempPath);
-    } catch {
-      // Temp file may not exist
-    }
-    throw err;
-  }
-}
-
-function shouldSkipInstall() {
-  return Boolean(process.env.OPEN_PLAN_ANNOTATOR_SKIP_INSTALL || process.env.npm_config_dev);
-}
-
-function runCli() {
-  if (shouldSkipInstall()) {
-    process.exit(0);
-  }
-
-  main().catch((err) => {
-    console.error("Failed to install open-plan-annotator binary:", err.message);
-    console.error("You can try manually running: node", path.join(__dirname, "install.mjs"));
-    process.exit(1);
-  });
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  runCli();
-}
-
-export {
-  VERSION,
-  PLATFORM_ASSET_BASENAME_MAP as PLATFORM_MAP,
-  getPlatformKey,
-  getReleaseApiUrl,
-  fetch,
-  fetchJson,
-  sha256Hex,
-  parseChecksumManifest,
-  selectChecksumAsset,
-  resolveReleaseAssetAndChecksum,
-  extractBinaryFromTarGz,
-  downloadVerifiedArchive,
-  shouldSkipInstall,
-  main,
-};

package/shared/releaseAssets.d.ts

@@ -1,12 +0,0 @@
-export interface ReleaseAsset {
-  name: string;
-  browser_download_url: string;
-}
-
-export declare const REPO: string;
-export declare const PLATFORM_ASSET_BASENAME_MAP: Record<string, string>;
-
-export declare function getPlatformKey(platform?: string, arch?: string): string;
-export declare function getPlatformAssetArchiveName(platformKey?: string): string | null;
-export declare function parseChecksumManifest(manifestText: string): Map<string, string>;
-export declare function selectChecksumAsset(assets: ReleaseAsset[]): ReleaseAsset | null;

package/shared/releaseAssets.mjs

@@ -1,65 +0,0 @@
-const REPO = "ndom91/open-plan-annotator";
-
-const PLATFORM_ASSET_BASENAME_MAP = {
-  "darwin-arm64": "open-plan-annotator-darwin-arm64",
-  "darwin-x64": "open-plan-annotator-darwin-x64",
-  "linux-x64": "open-plan-annotator-linux-x64",
-  "linux-arm64": "open-plan-annotator-linux-arm64",
-};
-
-function getPlatformKey(platform = process.platform, arch = process.arch) {
-  return `${platform}-${arch}`;
-}
-
-function getPlatformAssetArchiveName(platformKey = getPlatformKey()) {
-  const assetBaseName = PLATFORM_ASSET_BASENAME_MAP[platformKey];
-  if (!assetBaseName) {
-    return null;
-  }
-  return `${assetBaseName}.tar.gz`;
-}
-
-function parseChecksumManifest(manifestText) {
-  const checksums = new Map();
-
-  for (const rawLine of manifestText.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) continue;
-
-    const bsdStyle = line.match(/^SHA256\s*\(([^)]+)\)\s*=\s*([a-fA-F0-9]{64})$/);
-    if (bsdStyle) {
-      checksums.set(bsdStyle[1].trim(), bsdStyle[2].toLowerCase());
-      continue;
-    }
-
-    const gnuStyle = line.match(/^([a-fA-F0-9]{64})\s+[* ]?(.+)$/);
-    if (gnuStyle) {
-      checksums.set(gnuStyle[2].trim(), gnuStyle[1].toLowerCase());
-    }
-  }
-
-  return checksums;
-}
-
-function selectChecksumAsset(assets) {
-  const checksumAssets = assets
-    .filter((asset) => {
-      const lower = asset.name.toLowerCase();
-      return (
-        (lower.includes("sha256") || lower.includes("checksum")) &&
-        (lower.endsWith(".txt") || lower.endsWith(".sha256") || lower.endsWith(".sha256sum") || lower.endsWith(".sha256sums"))
-      );
-    })
-    .sort((a, b) => a.name.localeCompare(b.name));
-
-  return checksumAssets[0] ?? null;
-}
-
-export {
-  REPO,
-  PLATFORM_ASSET_BASENAME_MAP,
-  getPlatformKey,
-  getPlatformAssetArchiveName,
-  parseChecksumManifest,
-  selectChecksumAsset,
-};