open-plan-annotator 1.7.0 → 1.8.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Interactive plan annotation plugin for Claude Code",
-    "version": "1.7.0"
+    "version": "1.8.0"
   },
   "plugins": [
     {
       "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.7.0",
+      "version": "1.8.0",
       "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.7.0",
+  "version": "1.8.0",
   "author": {
     "name": "ndom91"
   },

package/hooks/hooks.json

@@ -1,12 +1,24 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/install-runtime.mjs\"",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
     "PermissionRequest": [
       {
         "matcher": "ExitPlanMode",
         "hooks": [
           {
             "type": "command",
-            "command": "open-plan-annotator-binary",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/open-plan-annotator.mjs\"",
             "timeout": 345600
           }
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -27,7 +27,7 @@
   },
   "files": [
     "bin/open-plan-annotator.mjs",
-    "bin/open-plan-annotator-binary",
+    "scripts/install-runtime.mjs",
     "shared/cliHelp.mjs",
     "shared/cliMode.mjs",
     "shared/packageManager.mjs",
@@ -84,10 +84,10 @@
     }
   },
   "optionalDependencies": {
-    "@open-plan-annotator/runtime-darwin-arm64": "1.7.0",
-    "@open-plan-annotator/runtime-darwin-x64": "1.7.0",
-    "@open-plan-annotator/runtime-linux-arm64": "1.7.0",
-    "@open-plan-annotator/runtime-linux-x64": "1.7.0"
+    "@open-plan-annotator/runtime-darwin-arm64": "1.8.0",
+    "@open-plan-annotator/runtime-darwin-x64": "1.8.0",
+    "@open-plan-annotator/runtime-linux-arm64": "1.8.0",
+    "@open-plan-annotator/runtime-linux-x64": "1.8.0"
   },
   "overrides": {
     "uuid": "^14.0.0"

package/scripts/install-runtime.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// Installs the per-platform Bun-compiled runtime binary for open-plan-annotator
+// from the npm registry. Intended to run as a Claude Code SessionStart hook.
+//
+// Behavior:
+//   1. Determines plugin version from the sibling package.json.
+//   2. Picks the runtime package matching the host platform/arch.
+//   3. If the target binary already exists at the resolver's fallback path
+//      (`packages/runtime-<platform>-<arch>/bin/open-plan-annotator`), exits 0.
+//   4. Otherwise fetches the package manifest from the npm registry,
+//      downloads the tarball, verifies its integrity against `dist.integrity`,
+//      extracts it via system `tar`, and atomically moves the binary into place.
+//
+// Logs go to stderr only — stdout is reserved for hook protocol output.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { get as httpsGet } from "node:https";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SUPPORTED_PLATFORMS = new Set([
+  "darwin-arm64",
+  "darwin-x64",
+  "linux-arm64",
+  "linux-x64",
+]);
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = resolve(here, "..");
+
+const pkg = JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf8"));
+const version = pkg.version;
+
+const platformKey = `${process.platform}-${process.arch}`;
+if (!SUPPORTED_PLATFORMS.has(platformKey)) {
+  process.stderr.write(
+    `open-plan-annotator: unsupported platform ${platformKey}. Supported: ${[...SUPPORTED_PLATFORMS].join(", ")}\n`,
+  );
+  process.exit(1);
+}
+
+const runtimePackage = `@open-plan-annotator/runtime-${platformKey}`;
+const targetDir = join(pluginRoot, "packages", `runtime-${platformKey}`, "bin");
+const targetBinary = join(targetDir, "open-plan-annotator");
+
+if (existsSync(targetBinary)) {
+  // Fast path: nothing to do.
+  process.exit(0);
+}
+
+process.stderr.write(
+  `open-plan-annotator: installing runtime ${runtimePackage}@${version} for ${platformKey}…\n`,
+);
+
+const start = Date.now();
+
+try {
+  const manifest = await fetchJson(
+    `https://registry.npmjs.org/${encodeURIComponent(runtimePackage)}/${encodeURIComponent(version)}`,
+  );
+
+  const tarballUrl = manifest?.dist?.tarball;
+  const integrity = manifest?.dist?.integrity;
+  if (typeof tarballUrl !== "string" || typeof integrity !== "string") {
+    throw new Error(
+      `npm manifest for ${runtimePackage}@${version} missing dist.tarball or dist.integrity`,
+    );
+  }
+
+  const tarballBuf = await fetchBuffer(tarballUrl);
+  verifyIntegrity(tarballBuf, integrity, runtimePackage, version);
+
+  const tmp = mkdtempSync(join(tmpdir(), "opa-runtime-"));
+  try {
+    const tarPath = join(tmp, "runtime.tgz");
+    writeFileSync(tarPath, tarballBuf);
+    execFileSync("tar", ["-xzf", tarPath, "-C", tmp], { stdio: "ignore" });
+
+    // npm tarballs always extract to a `package/` directory.
+    const extractedBinary = join(tmp, "package", "bin", "open-plan-annotator");
+    if (!existsSync(extractedBinary)) {
+      throw new Error(
+        `expected ${extractedBinary} after extracting ${runtimePackage}@${version}, not found`,
+      );
+    }
+
+    mkdirSync(targetDir, { recursive: true });
+    // renameSync may fail across filesystems; tmpdir is usually on the same
+    // device as the plugin cache, but if not, fall back to copy+unlink.
+    try {
+      renameSync(extractedBinary, targetBinary);
+    } catch (err) {
+      if (err?.code === "EXDEV") {
+        const buf = readFileSync(extractedBinary);
+        writeFileSync(targetBinary, buf);
+      } else {
+        throw err;
+      }
+    }
+    chmodSync(targetBinary, 0o755);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+
+  const elapsedMs = Date.now() - start;
+  process.stderr.write(
+    `open-plan-annotator: installed ${targetBinary} (${elapsedMs}ms)\n`,
+  );
+  process.exit(0);
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(
+    `open-plan-annotator: failed to install runtime ${runtimePackage}@${version}: ${message}\n`,
+  );
+  process.stderr.write(
+    `open-plan-annotator: rerun a Claude Code session to retry; ExitPlanMode will not work until install succeeds.\n`,
+  );
+  process.exit(1);
+}
+
+/**
+ * Fetch a URL with redirect handling and return the response buffer.
+ *
+ * @param {string} url
+ * @param {number} [maxRedirects]
+ * @returns {Promise<Buffer>}
+ */
+function fetchBuffer(url, maxRedirects = 5) {
+  return new Promise((resolveFetch, rejectFetch) => {
+    httpsGet(
+      url,
+      {
+        headers: {
+          "user-agent": `open-plan-annotator-installer/${version}`,
+          accept: "*/*",
+        },
+      },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        if ((status === 301 || status === 302 || status === 307 || status === 308) && res.headers.location) {
+          if (maxRedirects <= 0) {
+            rejectFetch(new Error(`too many redirects for ${url}`));
+            res.resume();
+            return;
+          }
+          const next = new URL(res.headers.location, url).toString();
+          res.resume();
+          fetchBuffer(next, maxRedirects - 1).then(resolveFetch, rejectFetch);
+          return;
+        }
+        if (status !== 200) {
+          rejectFetch(new Error(`GET ${url} -> HTTP ${status}`));
+          res.resume();
+          return;
+        }
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => resolveFetch(Buffer.concat(chunks)));
+        res.on("error", rejectFetch);
+      },
+    ).on("error", rejectFetch);
+  });
+}
+
+/**
+ * @param {string} url
+ * @returns {Promise<unknown>}
+ */
+async function fetchJson(url) {
+  const buf = await fetchBuffer(url);
+  return JSON.parse(buf.toString("utf8"));
+}
+
+/**
+ * Verify a buffer against an npm Subresource Integrity string (e.g. "sha512-…").
+ *
+ * @param {Buffer} buf
+ * @param {string} integrity
+ * @param {string} pkgName
+ * @param {string} pkgVersion
+ */
+function verifyIntegrity(buf, integrity, pkgName, pkgVersion) {
+  const match = integrity.match(/^(sha\d+)-([A-Za-z0-9+/=]+)$/);
+  if (!match) {
+    throw new Error(
+      `unrecognized integrity format "${integrity}" for ${pkgName}@${pkgVersion}`,
+    );
+  }
+  const [, algo, expectedB64] = match;
+  const actualB64 = createHash(algo).update(buf).digest("base64");
+  if (actualB64 !== expectedB64) {
+    throw new Error(
+      `integrity mismatch for ${pkgName}@${pkgVersion}\n  expected ${algo}: ${expectedB64}\n  actual   ${algo}: ${actualB64}`,
+    );
+  }
+}

package/shared/runtimeResolver.mjs

@@ -1,6 +1,7 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
-import path from "node:path";
 import { createRequire } from "node:module";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const RUNTIME_PACKAGE_MAP = {
@@ -19,12 +20,45 @@ export function getRuntimePackageName(platform = process.platform, arch = proces
 }
 
 export function resolveRuntimeBinary(options = {}) {
+  const attempt = () => tryResolveRuntimeBinary(options);
+
+  const first = attempt();
+  if (first.ok) return first.value;
+
+  // Skip installer for hard-failure conditions (unsupported platform): no
+  // amount of installing will produce a binary, and we'd waste a network
+  // round trip downloading the host's binary unnecessarily.
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  if (!getRuntimePackageName(platform, arch)) {
+    throw first.error;
+  }
+
+  // Last-resort recovery: invoke the SessionStart installer synchronously and
+  // retry resolution once. Useful for hosts that fetch this package without
+  // running `npm install` (and therefore skip the optionalDependencies that
+  // would otherwise pull the matching runtime binary). The Claude Code plugin
+  // install path is the canonical example, but it triggers the same script
+  // earlier via its SessionStart hook; this branch covers everyone else.
+  if (runInstaller(options)) {
+    const second = attempt();
+    if (second.ok) return second.value;
+    throw second.error;
+  }
+
+  throw first.error;
+}
+
+function tryResolveRuntimeBinary(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)}`);
+    return {
+      ok: false,
+      error: new Error(`Unsupported platform ${getRuntimePlatformKey(platform, arch)}`),
+    };
   }
 
   const requireFrom = createRequire(options.parentUrl ?? import.meta.url);
@@ -37,27 +71,66 @@ export function resolveRuntimeBinary(options = {}) {
     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,
+        ok: true,
+        value: {
+          packageName,
+          packageRoot: path.dirname(path.dirname(workspaceBinaryPath)),
+          binaryPath: workspaceBinaryPath,
+        },
       };
     }
 
-    throw new Error(
-      `Missing runtime package ${packageName}. Reinstall open-plan-annotator for ${getRuntimePlatformKey(platform, arch)}.`,
-    );
+    return {
+      ok: false,
+      error: 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 {
+      ok: false,
+      error: new Error(`Runtime package ${packageName} is installed but ${binaryPath} is missing. Rebuild or reinstall it.`),
+    };
   }
 
   return {
-    packageName,
-    packageRoot,
-    binaryPath,
+    ok: true,
+    value: {
+      packageName,
+      packageRoot,
+      binaryPath,
+    },
   };
 }
+
+/**
+ * Run `scripts/install-runtime.mjs` synchronously to lay down the per-platform
+ * runtime binary. Returns true if the installer ran successfully, false if it
+ * was unavailable or failed. Diagnostics go to stderr; this function never
+ * throws so a failure here falls through to the original missing-runtime
+ * error from the caller.
+ */
+function runInstaller(_options = {}) {
+  // Opt-out for callers that want to keep the old behavior (e.g. tests that
+  // assert the error path) or environments where re-entry would be harmful.
+  if (process.env.OPEN_PLAN_ANNOTATOR_SKIP_INSTALL === "1") return false;
+
+  const workspaceRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const installerPath = path.join(workspaceRoot, "scripts", "install-runtime.mjs");
+  if (!fs.existsSync(installerPath)) return false;
+
+  try {
+    execFileSync(process.execPath, [installerPath], {
+      stdio: ["ignore", "ignore", "inherit"],
+      timeout: 60_000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}