handoff-mcp-server 0.25.1 → 0.27.0

package/README.md

@@ -61,6 +61,32 @@ to pick up the change mid-session (a Claude Code restart also applies it).
 > is the *marketplace* name (the `name` field in `.claude-plugin/marketplace.json`).
 > Install commands always use `<plugin>@<marketplace>`.
 
+#### Platform support
+
+The npm package ships **prebuilt binaries** — no Rust toolchain, no compiler,
+and no install scripts are needed. npm downloads only the binary matching your
+platform.
+
+| Platform | x64 | arm64 |
+|---|---|---|
+| Linux (glibc 2.35+) | ✅ | ✅ |
+| macOS | ✅ | ✅ |
+| Windows | ✅ | ✅ |
+
+WSL works as a plain Linux install. For anything else — musl/Alpine, FreeBSD,
+32-bit, or glibc older than 2.35 — install with `cargo install handoff-mcp`
+instead, which builds from source.
+
+If you already have a binary you built yourself, point the npm wrapper at it
+with `HANDOFF_MCP_BINARY_PATH=/path/to/handoff-mcp`.
+
+> **Note**: installing with `--omit=optional` skips the prebuilt binary and
+> leaves the CLI unable to start. Reinstall without that flag.
+>
+> **Alpine / musl**: the Linux binaries are glibc-linked. npm may install one
+> anyway, and it fails to exec with a confusing "not found" error even though
+> the file is present. Use `cargo install handoff-mcp` on musl systems.
+
 **Optional: task loop (automated TDD + research workflows)**
 
 ```bash
@@ -263,10 +289,11 @@ cargo install handoff-mcp
 npm install -g handoff-mcp-server
 ```
 
-Both install the same binary. `cargo install` fetches the crate from
-[crates.io](https://crates.io/crates/handoff-mcp) and compiles it directly;
-`npm install` downloads the source and runs `cargo build --release` via
-postinstall, so either way you need a Rust toolchain.
+Both install the same binary, by different routes. `cargo install` fetches the
+crate from [crates.io](https://crates.io/crates/handoff-mcp) and compiles it,
+so it needs a Rust toolchain and works on any target Rust supports.
+`npm install` downloads a prebuilt binary for your platform and compiles
+nothing — see [Platform support](#platform-support) for the list.
 
 ### Build from source
 

package/bin/handoff-mcp.js

@@ -1,22 +1,65 @@
 #!/usr/bin/env node
 "use strict";
 
-const { execFileSync } = require("child_process");
-const path = require("path");
-const fs = require("fs");
+// Thin wrapper around the prebuilt binary shipped by the per-platform
+// optionalDependencies. Deliberately does no work at install time: npm v12
+// disables install scripts by default, so anything that needs to happen must
+// happen here, at run time.
 
-const binary = path.join(__dirname, "handoff-mcp-bin");
+const { spawn } = require("child_process");
+const { resolveBinary } = require("./resolve-binary.js");
 
-if (!fs.existsSync(binary)) {
-  console.error(
-    "handoff-mcp binary not found. Try reinstalling: npm install -g handoff-mcp-server"
-  );
+const result = resolveBinary();
+
+if (!result.ok) {
+  console.error(result.message);
   process.exit(1);
 }
 
-try {
-  execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
-} catch (e) {
-  if (e.status != null) process.exit(e.status);
-  process.exit(1);
+// Async spawn, not spawnSync. spawnSync blocks the event loop for the entire
+// life of the child, which means no signal handler can ever run: an MCP client
+// that stops the server signals the wrapper, the wrapper dies instantly, and
+// the real server is reparented to init — a leaked process per session, still
+// holding .handoff/ file handles. Async spawn keeps the wrapper alive to
+// forward the signal.
+//
+// stdio "inherit" is required, not incidental: this is an MCP stdio server, so
+// the child must own the real stdin/stdout and the wrapper must not sit in the
+// middle of the JSON-RPC stream.
+const child = spawn(result.binary, process.argv.slice(2), { stdio: "inherit" });
+
+// Forwarded rather than handled: the binary owns shutdown (flushing state to
+// .handoff/), so the wrapper's only job is to relay the request and wait.
+// Registering a handler also stops Node from applying its default terminate
+// behavior, which is what kept the wrapper from dying before the child.
+const FORWARDED = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+for (const sig of FORWARDED) {
+  process.on(sig, () => {
+    if (!child.killed) child.kill(sig);
+  });
 }
+
+child.on("error", (err) => {
+  const hint =
+    result.source === "env"
+      ? `HANDOFF_MCP_BINARY_PATH points at "${result.binary}", which could not be executed.`
+      : `The prebuilt binary at "${result.binary}" could not be executed.` +
+        "\nIf this is a musl-based system (Alpine), the published binaries are" +
+        "\nglibc-linked and will not run; build from source with" +
+        "\n`cargo install handoff-mcp` and set HANDOFF_MCP_BINARY_PATH.";
+  console.error(`handoff-mcp: ${err.message}\n\n${hint}`);
+  process.exit(1);
+});
+
+child.on("close", (code, signal) => {
+  // Re-raising the signal is what makes `kill` behave as though the wrapper
+  // were not there: the parent shell sees the process die from the signal
+  // rather than from a plain exit code. The default handler must be restored
+  // first, or the forwarding handler above would swallow it.
+  if (signal) {
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code == null ? 1 : code);
+});

package/bin/resolve-binary.js

@@ -0,0 +1,122 @@
+"use strict";
+
+// Resolution logic for the prebuilt binary shipped by the per-platform
+// optionalDependencies (handoff-mcp-server-<platform>-<arch>).
+//
+// Kept separate from handoff-mcp.js so the mapping and the error messages can
+// be unit-tested without spawning a real binary.
+
+const PACKAGE_NAME = "handoff-mcp-server";
+
+// Platform/arch pairs we publish a prebuilt binary for. Keys are
+// `${process.platform}-${process.arch}`; see .github/workflows/release.yml for
+// the matching build matrix.
+const SUPPORTED = {
+  "linux-x64": "linux-x64",
+  "linux-arm64": "linux-arm64",
+  "darwin-x64": "darwin-x64",
+  "darwin-arm64": "darwin-arm64",
+  "win32-x64": "win32-x64",
+  "win32-arm64": "win32-arm64",
+};
+
+/** Name of the platform package for a given platform/arch, or null if unsupported. */
+function platformPackage(platform, arch) {
+  const suffix = SUPPORTED[`${platform}-${arch}`];
+  return suffix ? `${PACKAGE_NAME}-${suffix}` : null;
+}
+
+/** Path of the binary *inside* a platform package. Windows needs the .exe suffix. */
+function binaryEntry(platform) {
+  return platform === "win32" ? "handoff-mcp.exe" : "handoff-mcp";
+}
+
+/**
+ * Locate the handoff-mcp binary.
+ *
+ * Order:
+ *   1. HANDOFF_MCP_BINARY_PATH override (esbuild's ESBUILD_BINARY_PATH
+ *      equivalent) — lets users point at a self-built binary on platforms we
+ *      do not publish, and lets tests run without installing anything.
+ *   2. require.resolve() into the platform package. Never path arithmetic:
+ *      npm hoisting and pnpm's symlinked store both move node_modules around,
+ *      and require.resolve is the only thing that follows those layouts.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.platform] defaults to process.platform
+ * @param {string} [opts.arch] defaults to process.arch
+ * @param {object} [opts.env] defaults to process.env
+ * @param {(id: string) => string} [opts.resolve] defaults to require.resolve
+ * @returns {{ ok: true, binary: string, source: "env" | "package" }
+ *          | { ok: false, message: string }}
+ */
+function resolveBinary(opts = {}) {
+  const platform = opts.platform || process.platform;
+  const arch = opts.arch || process.arch;
+  const env = opts.env || process.env;
+  const resolve = opts.resolve || require.resolve;
+
+  const override = env.HANDOFF_MCP_BINARY_PATH;
+  if (override) {
+    // Trusted as-is: an explicit override that does not exist should surface
+    // as a spawn error naming the path the user asked for, not as a fallback
+    // to some other binary they did not ask for.
+    return { ok: true, binary: override, source: "env" };
+  }
+
+  const pkg = platformPackage(platform, arch);
+  if (!pkg) {
+    return {
+      ok: false,
+      message: unsupportedMessage(platform, arch),
+    };
+  }
+
+  try {
+    return {
+      ok: true,
+      binary: resolve(`${pkg}/bin/${binaryEntry(platform)}`),
+      source: "package",
+    };
+  } catch (e) {
+    return { ok: false, message: missingPackageMessage(pkg, e) };
+  }
+}
+
+function unsupportedMessage(platform, arch) {
+  return [
+    `handoff-mcp: no prebuilt binary for ${platform}-${arch}.`,
+    "",
+    `Prebuilt binaries are published for: ${Object.keys(SUPPORTED).join(", ")}.`,
+    "",
+    "To run on this platform, build from source and point the wrapper at it:",
+    "  cargo install handoff-mcp",
+    "  export HANDOFF_MCP_BINARY_PATH=$(command -v handoff-mcp)",
+  ].join("\n");
+}
+
+function missingPackageMessage(pkg, cause) {
+  return [
+    `handoff-mcp: the platform package "${pkg}" is not installed.`,
+    "",
+    "This usually means one of:",
+    "  - installed with --omit=optional / --no-optional (the prebuilt binary",
+    "    ships as an optional dependency; reinstall without that flag)",
+    "  - a lockfile generated on a different platform was installed with",
+    "    `npm ci` (see https://github.com/npm/cli/issues/8320); delete",
+    "    node_modules and package-lock.json, then reinstall",
+    "",
+    `Reinstall with:  npm install -g ${PACKAGE_NAME}`,
+    `Or set HANDOFF_MCP_BINARY_PATH to a binary you built yourself.`,
+    "",
+    `(resolution error: ${cause && cause.message ? cause.message : cause})`,
+  ].join("\n");
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  SUPPORTED,
+  platformPackage,
+  binaryEntry,
+  resolveBinary,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.25.1",
+  "version": "0.27.0",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",
@@ -21,25 +21,30 @@
     "handoff-mcp": "./bin/handoff-mcp.js"
   },
   "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "test:js": "node --test \"plugin-task-loop/workflows/lib/*.test.js\"",
+    "test:js": "node --test \"bin/*.test.js\" \"plugin-task-loop/workflows/lib/*.test.js\"",
     "sync:workflow": "./scripts/sync-workflow-inline.sh",
     "check:workflow": "./scripts/sync-workflow-inline.sh --check"
   },
+  "//optionalDependencies": "Prebuilt binaries, one per platform. Pinned to an exact version (never ^ or ~): a wrapper must never pair with a platform package built from different sources. npm skips the entries whose os/cpu do not match instead of failing, which is what makes this work.",
+  "optionalDependencies": {
+    "handoff-mcp-server-darwin-arm64": "0.27.0",
+    "handoff-mcp-server-darwin-x64": "0.27.0",
+    "handoff-mcp-server-linux-arm64": "0.27.0",
+    "handoff-mcp-server-linux-x64": "0.27.0",
+    "handoff-mcp-server-win32-arm64": "0.27.0",
+    "handoff-mcp-server-win32-x64": "0.27.0"
+  },
   "files": [
     "bin/handoff-mcp.js",
-    "scripts/",
+    "bin/resolve-binary.js",
     "skills/",
-    "src/",
-    "templates/",
-    "Cargo.toml",
-    "Cargo.lock",
     "LICENSE",
     "README.md"
   ],
   "os": [
     "linux",
-    "darwin"
+    "darwin",
+    "win32"
   ],
   "engines": {
     "node": ">=16"

package/skills/handoff/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "Handoff"
+  short_description: "Load and save session context, track tasks, and manage project state across sessions"
+  default_prompt: "Use $handoff to run the session handoff workflow"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "handoff"
+      description: "Handoff MCP server for session management"
+      transport: "stdio"
+      command: "handoff-mcp"

package/skills/handoff-docs/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "Handoff Docs"
+  short_description: "Save, read, search, and traverse structured project documents (specs, designs, ADRs)"
+  default_prompt: "Use $handoff-docs to manage project documents"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "handoff"
+      description: "Handoff MCP server for session management"
+      transport: "stdio"
+      command: "handoff-mcp"

package/skills/handoff-import/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "Handoff Import"
+  short_description: "Import existing documents into structured .handoff/ task and session management"
+  default_prompt: "Use $handoff-import to import a document into handoff"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "handoff"
+      description: "Handoff MCP server for session management"
+      transport: "stdio"
+      command: "handoff-mcp"

package/skills/handoff-load/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "Handoff Load"
+  short_description: "Load the previous session's handoff context and show what to work on next"
+  default_prompt: "Use $handoff-load to load the handoff context for this project"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "handoff"
+      description: "Handoff MCP server for session management"
+      transport: "stdio"
+      command: "handoff-mcp"

package/skills/handoff-memory/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "Handoff Memory"
+  short_description: "Save, query, merge, and clean up durable project knowledge across sessions"
+  default_prompt: "Use $handoff-memory to query project memories for relevant knowledge"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "handoff"
+      description: "Handoff MCP server for session management"
+      transport: "stdio"
+      command: "handoff-mcp"

package/skills/handoff-refer/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "Handoff Refer"
+  short_description: "Send a cross-project referral to another project's handoff store"
+  default_prompt: "Use $handoff-refer to send a referral to another project"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "handoff"
+      description: "Handoff MCP server for session management"
+      transport: "stdio"
+      command: "handoff-mcp"