@kurrent/kcap 0.7.1 → 0.7.2

package/README.md

@@ -24,7 +24,7 @@ kcap status                 Show server, auth, and daemon status
 kcap daemon start [-d]      Start the daemon
 kcap daemon stop            Stop the daemon
 kcap review <pr>            Launch Claude Code with PR review context
-kcap update                 Check for updates
+kcap update                 Upgrade the CLI and refresh agent plugins
 kcap --version              Show version
 kcap --help                 Show all commands
 ```

package/bin/kcap.js

@@ -2,7 +2,7 @@
 
 // Resolves and exec's the native kcap binary for the current platform.
 
-const { execFileSync } = require("child_process");
+const { execFileSync, spawnSync } = require("child_process");
 const path = require("path");
 const fs = require("fs");
 
@@ -63,6 +63,21 @@ try {
   try { fs.chmodSync(binaryPath, 0o755); } catch {}
 }
 
+// `kcap update` for npm-global installs is driven HERE, in the Node launcher,
+// not by the native binary. The OS locks an executable image for the whole
+// process lifetime but a script only during load — so by driving the upgrade
+// from this script (with the native binary not running) npm can overwrite the
+// binary even on Windows, with no temp-file/rename/detached-helper dance.
+// `--check` (JSON probe) and `--help` fall through to the native binary.
+{
+  const updArgs   = process.argv.slice(3);
+  const checkOnly = updArgs.includes("--check");
+  const wantsHelp = updArgs.some((a) => a === "--help" || a === "-h");
+  if (process.argv[2] === "update" && !checkOnly && !wantsHelp) {
+    runUpdate(binaryPath); // never returns
+  }
+}
+
 // Exec the native binary, replacing this process
 try {
   execFileSync(binaryPath, process.argv.slice(2), {
@@ -76,3 +91,87 @@ try {
   }
   process.exit(1);
 }
+
+// Performs `kcap update`: upgrade the global npm package, then refresh
+// user-scope skills/hooks. Always exits the process; never returns.
+function runUpdate(binaryPath) {
+  // On Windows, `npm` is a .cmd shim; Node refuses to spawn .cmd/.bat directly
+  // (2024 command-injection fix), so route npm through a shell there. Our npm
+  // args are static, so shell use is safe.
+  const npmOpts = process.platform === "win32" ? { shell: true } : {};
+
+  // Resolve npm's global root so we can (a) confirm this is a global install we
+  // own and (b) check we can write to it before starting.
+  let globalRoot = null;
+  try {
+    globalRoot = execFileSync("npm", ["root", "-g"], { encoding: "utf8", ...npmOpts }).trim();
+  } catch {}
+
+  let isGlobalNpm = false;
+  try {
+    if (globalRoot) {
+      const root = fs.realpathSync(globalRoot) + path.sep;
+      isGlobalNpm = fs.realpathSync(__filename).startsWith(root);
+    }
+  } catch {}
+
+  if (!isGlobalNpm) {
+    console.error("kcap was not installed via a global npm install, so it can't");
+    console.error("self-update. Update it the way you installed it, e.g.:");
+    console.error("  npm install -g @kurrent/kcap@latest   (npm)");
+    console.error("  brew upgrade kcap                      (Homebrew)");
+    process.exit(1);
+  }
+
+  // Ask the native binary whether a newer version exists. This short-lived
+  // child fully EXITS before we run npm, so the binary file is unlocked when
+  // npm overwrites it (matters on Windows). `--no-update-check` keeps the
+  // background nudge from racing onto stderr.
+  try {
+    const out  = execFileSync(binaryPath, ["update", "--check", "--no-update-check"], { encoding: "utf8" });
+    // The probe prints one JSON line; take the last {...} line in case anything
+    // else (e.g. a git-remote warning) landed on stdout first.
+    const line = out.split(/\r?\n/).reverse().find((l) => l.trim().startsWith("{"));
+    const info = JSON.parse(line);
+    // Only short-circuit when the probe is CONFIDENT we're up to date: `newer`
+    // explicitly false AND a known current version. `newer: null` (version
+    // unknown / check failed) falls through to the upgrade rather than stranding
+    // the user on a stale CLI.
+    if (info && info.newer === false && info.current) {
+      console.log(`Already up to date: ${info.current}`);
+      process.exit(0);
+    }
+    if (info && info.newer) {
+      console.log(`Updating kcap: ${info.current} → ${info.latest}`);
+    }
+  } catch {
+    // Couldn't determine — fall through and let npm decide (it's idempotent).
+  }
+
+  // Fail clearly instead of half-installing under a root-owned prefix.
+  try {
+    fs.accessSync(globalRoot, fs.constants.W_OK);
+  } catch {
+    console.error(`Cannot write to the global npm directory (${globalRoot}).`);
+    console.error("Re-run with the permissions you installed kcap with, or reinstall");
+    console.error("to a user-owned prefix to avoid needing elevated rights on updates.");
+    process.exit(1);
+  }
+
+  const res = spawnSync("npm", ["install", "-g", "@kurrent/kcap@latest"], {
+    stdio: "inherit",
+    windowsHide: true,
+    ...npmOpts,
+  });
+  if (res.status !== 0) {
+    console.error("npm install failed; kcap was not updated.");
+    process.exit(res.status == null ? 1 : res.status);
+  }
+
+  // npm has now overwritten kcap.js, refresh.js, and the binary. require()
+  // reads the NEW refresh.js, which spawns the NEW launcher -> NEW binary.
+  console.log("Refreshing hooks and skills…");
+  require("./refresh").runRefreshes(fs.realpathSync(__filename));
+  console.log("kcap updated.");
+  process.exit(0);
+}

package/bin/postinstall.js

@@ -2,58 +2,30 @@
 
 // Runs after `npm install -g @kurrent/kcap` (including upgrades).
 //
-// Refreshes user-scope kcap agent installations so users pick up
-// new or updated skills, Codex hook commands, Cursor hook commands, and
-// Claude plugin registration without manually re-running `kcap setup`.
+// Refreshes user-scope kcap agent installations so users pick up new or updated
+// skills, hook commands, and Claude plugin registration without manually
+// re-running `kcap setup`. The actual refresh logic lives in refresh.js, shared
+// with the `kcap update` path.
 //
 // Contract:
-// - Only runs on global installs. Skipping non-global installs avoids
-//   touching ~/.agents/, ~/.codex/, ~/.cursor/, or ~/.claude/ during unrelated
+// - Only runs on global installs. Skipping non-global installs avoids touching
+//   ~/.agents/, ~/.codex/, ~/.cursor/, or ~/.claude/ during unrelated
 //   local/transitive installs on already-opted-in machines.
-// - Each refresh uses `--if-installed`, which no-ops unless the user
-//   has previously opted in (marker file present OR pre-marker install
-//   detected via existing kcap entries in the target file).
-// - Each refresh runs independently. A failure, timeout, or unexpected
-//   exit code from one does not prevent the others. The script always
-//   exits 0 — a failed refresh must never break `npm install`.
+// - Always exits 0 — a failed refresh must never break `npm install`.
+//
+// Note: modern package managers gate install scripts behind an "allowed
+// scripts" allowlist, so this hook may not run on upgrade. `kcap update` runs
+// the same refresh and is not subject to that gate (the user invokes it
+// explicitly).
 
-const { spawnSync } = require("child_process");
 const path = require("path");
 
 const isGlobal =
   process.env.npm_config_global === "true" ||
   process.env.npm_config_location === "global";
 
-if (!isGlobal) {
-  process.exit(0);
-}
-
-const launcher = path.join(__dirname, "kcap.js");
-
-// One entry per agent. Order is independent — each refresh is gated by
-// its own marker.
-const refreshes = [
-  ["plugin", "install", "--skills",  "--if-installed"],
-  ["plugin", "install", "--codex",   "--if-installed"],
-  ["plugin", "install", "--cursor",  "--if-installed"],
-  ["plugin", "install", "--copilot", "--if-installed"],
-  ["plugin", "install",              "--if-installed"], // Claude
-];
-
-for (const argv of refreshes) {
-  try {
-    spawnSync(process.execPath, [launcher, ...argv], {
-      stdio: "ignore",
-      env: process.env,
-      // Hard ceiling so a stalled child can never hang `npm install`.
-      // Each refresh is bounded independently.
-      timeout: 60_000,
-      killSignal: "SIGKILL",
-      windowsHide: true,
-    });
-  } catch {
-    // Never fail npm install.
-  }
+if (isGlobal) {
+  require("./refresh").runRefreshes(path.join(__dirname, "kcap.js"));
 }
 
 process.exit(0);

package/bin/refresh.js

@@ -0,0 +1,44 @@
+// Refreshes user-scope kcap agent installations so users pick up new or updated
+// skills, Codex/Cursor/Copilot hook commands, and Claude plugin registration.
+//
+// Shared by:
+// - postinstall.js — runs after `npm install -g @kurrent/kcap` (incl. upgrades),
+//   when the package manager allows install scripts to run.
+// - kcap.js `update` — runs after a user-initiated `kcap update`, which works
+//   even when the package manager blocks postinstall scripts.
+
+const { spawnSync } = require("child_process");
+
+// One entry per agent. Order is independent — each refresh is gated by its own
+// marker via `--if-installed`, which no-ops unless the user has previously
+// opted in (marker file present OR pre-marker install detected).
+const REFRESHES = [
+  ["plugin", "install", "--skills",  "--if-installed"],
+  ["plugin", "install", "--codex",   "--if-installed"],
+  ["plugin", "install", "--cursor",  "--if-installed"],
+  ["plugin", "install", "--copilot", "--if-installed"],
+  ["plugin", "install",              "--if-installed"], // Claude
+];
+
+// Runs each refresh via the given launcher (an absolute path to kcap.js).
+// Each refresh runs independently: a failure, timeout, or unexpected exit code
+// from one never prevents the others and never throws to the caller — a failed
+// refresh must never break `npm install` or report `kcap update` as failed.
+function runRefreshes(launcherPath) {
+  for (const argv of REFRESHES) {
+    try {
+      spawnSync(process.execPath, [launcherPath, ...argv], {
+        stdio: "ignore",
+        env: process.env,
+        // Hard ceiling so a stalled child can never hang the caller.
+        timeout: 60_000,
+        killSignal: "SIGKILL",
+        windowsHide: true,
+      });
+    } catch {
+      // Never fail the caller.
+    }
+  }
+}
+
+module.exports = { runRefreshes };

package/kcap/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -14,12 +14,12 @@
     "postinstall": "node bin/postinstall.js"
   },
   "optionalDependencies": {
-    "@kurrent/kcap-darwin-arm64": "0.7.1",
-    "@kurrent/kcap-linux-x64": "0.7.1",
-    "@kurrent/kcap-linux-arm64": "0.7.1",
-    "@kurrent/kcap-linux-musl-x64": "0.7.1",
-    "@kurrent/kcap-linux-musl-arm64": "0.7.1",
-    "@kurrent/kcap-win-x64": "0.7.1"
+    "@kurrent/kcap-darwin-arm64": "0.7.2",
+    "@kurrent/kcap-linux-x64": "0.7.2",
+    "@kurrent/kcap-linux-arm64": "0.7.2",
+    "@kurrent/kcap-linux-musl-x64": "0.7.2",
+    "@kurrent/kcap-linux-musl-arm64": "0.7.2",
+    "@kurrent/kcap-win-x64": "0.7.2"
   },
   "files": [
     "bin/",