open-plan-annotator 1.0.12 → 1.0.14

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Interactive plan annotation plugin for Claude Code",
-    "version": "1.0.12"
+    "version": "1.0.14"
   },
   "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.0.12",
+      "version": "1.0.14",
       "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.12",
+  "version": "1.0.14",
   "author": {
     "name": "ndom91"
   },

package/bin/open-plan-annotator.mjs

@@ -4,6 +4,8 @@ import { execFileSync, 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";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const binaryPath = path.join(__dirname, "open-plan-annotator-binary");
@@ -11,31 +13,34 @@ 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];
+const cliMode = resolveCliMode(arg, { stdinIsTTY: process.stdin.isTTY === true });
 
-if (arg === "--version" || arg === "-v") {
+if (cliMode === "version") {
   console.log(VERSION);
   process.exit(0);
 }
 
-if (arg === "--help" || arg === "-h") {
-  console.log(`open-plan-annotator v${VERSION}
-
-Usage:
-  open-plan-annotator              Run as a Claude Code hook (reads stdin)
-  open-plan-annotator update       Update the binary to the latest version
-  open-plan-annotator --version    Print version
-  open-plan-annotator --help       Show this help
-
-https://github.com/ndom91/open-plan-annotator`);
+if (cliMode === "help") {
+  console.log(buildCliHelpText(VERSION));
   process.exit(0);
 }
 
+if (cliMode === "unknown") {
+  console.error(buildUnknownCommandPrefix(arg));
+  console.error("Run `open-plan-annotator --help` for usage.");
+  process.exit(1);
+}
+
 // 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 = process.stdin.isTTY ? Buffer.alloc(0) : fs.readFileSync(0);
-} catch {
+if (cliMode === "hook") {
+  try {
+    stdinBuffer = process.stdin.isTTY ? Buffer.alloc(0) : fs.readFileSync(0);
+  } catch {
+    stdinBuffer = Buffer.alloc(0);
+  }
+} else {
   stdinBuffer = Buffer.alloc(0);
 }
 
@@ -65,8 +70,8 @@ if (!fs.existsSync(binaryPath)) {
   justInstalled = true;
 }
 
-// Handle `open-plan-annotator update` subcommand
-if (process.argv[2] === "update") {
+// Handle `open-plan-annotator update|upgrade` subcommand
+if (cliMode === "update") {
   if (justInstalled) {
     console.log("Binary installed (v" + VERSION + ")");
     process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",

package/shared/cliHelp.mjs

@@ -0,0 +1,27 @@
+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 upgrade      Alias for update",
+  "open-plan-annotator --version    Print version",
+  "open-plan-annotator --help       Show this help",
+];
+
+/**
+ * @param {string} version
+ * @returns {string}
+ */
+export function buildCliHelpText(version) {
+  const usage = HELP_USAGE_LINES.map((line) => `  ${line}`).join("\n");
+  return `open-plan-annotator v${version}\n\nUsage:\n${usage}\n\n${REPOSITORY_URL}`;
+}
+
+/**
+ * @param {string | undefined} command
+ * @returns {string}
+ */
+export function buildUnknownCommandPrefix(command) {
+  return `open-plan-annotator: unknown command \`${command ?? ""}\``;
+}

package/shared/cliHelp.test.ts

@@ -0,0 +1,28 @@
+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 update       Update the binary to the latest version
+  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.mjs

@@ -0,0 +1,23 @@
+/**
+ * @typedef {"hook" | "update" | "help" | "version" | "unknown"} CliMode
+ */
+
+/**
+ * @typedef {{ stdinIsTTY?: boolean }} CliModeOptions
+ */
+
+/**
+ * @param {string | undefined} arg
+ * @param {CliModeOptions} [options]
+ * @returns {CliMode}
+ */
+export function resolveCliMode(arg, options = {}) {
+  if (!arg) {
+    return options.stdinIsTTY ? "help" : "hook";
+  }
+
+  if (arg === "update" || arg === "upgrade") return "update";
+  if (arg === "--help" || arg === "-h") return "help";
+  if (arg === "--version" || arg === "-v") return "version";
+  return "unknown";
+}

package/shared/cliMode.test.ts

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