feat(plugins): make CCAM installable straight from a Claude Code plugin

Adds a root `ccam` plugin (`.claude-plugin/plugin.json`, `"source": "./"`) so `/plugin marketplace add` + `/plugin install ccam@...` is enough on a machine with nothing but Claude Code: no clone, no npm run setup, no manual npm start. - scripts/plugin-bootstrap.js: SessionStart hook. Fast-path exit, Node >=22.5 gate (node:sqlite), mkdir lock with stale reclaim, deps installed into ~/.claude/agent-dashboard/runtime/ (never the plugin cache), legacy checkout-hook cleanup (backed up), ~/.local/bin/ccam launcher, eager UI build so client routes like /run work immediately, detached server spawn. - scripts/plugin-open.js, scripts/plugin-doctor.js: /ccam-open, /ccam-doctor. - server/index.js: DASHBOARD_CLIENT_DIST override (plugin cache is read-only). - mcp/build/ is committed (plugin MCP servers start before any bootstrap could build them) and kept honest by scripts/check-mcp-build.js (content hash, not mtime), enforced by pre-commit when mcp/src changes. - plugins/ccam-dashboard/.mcp.json moved under plugins/ccam/ with a working ${CLAUDE_PLUGIN_ROOT} path (the old relative path never resolved from a marketplace-cached subdir). - Docs: README, INSTALL, SETUP, ARCHITECTURE, CLAUDE.md, docs/PLUGINS.md, docs/MCP.md, docs/CLI.md, docs/HOOKS.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-10 16:05:37 +07:00
parent 5a793e70cc
commit 8a82895c65
59 changed files with 5982 additions and 44 deletions
@@ -0,0 +1,198 @@
+/**
+ * @file Tests scripts/plugin-bootstrap.js — the SessionStart bootstrap that
+ * makes a plugin install self-sufficient. Covers the fast path, the Node
+ * version gate, stale-lock reclaim, legacy hook removal (the duplicate-hook
+ * double-counting bug) and the CLI launcher's refusal to clobber a foreign
+ * `ccam`. Every path is exercised against injected temp directories — nothing
+ * here touches the real $HOME.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+const { describe, it, beforeEach, after } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const TMP_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "ccam-bootstrap-"));
+process.env.CLAUDE_HOME = TMP_HOME;
+delete process.env.DASHBOARD_DATA_DIR;
+
+const boot = require("../../scripts/plugin-bootstrap");
+
+const RT = path.join(TMP_HOME, "agent-dashboard", "runtime");
+
+function resetRuntime() {
+  fs.rmSync(RT, { recursive: true, force: true });
+  fs.mkdirSync(RT, { recursive: true });
+}
+
+after(() => {
+  fs.rmSync(TMP_HOME, { recursive: true, force: true });
+});
+
+describe("runtime location", () => {
+  it("lives under the shared data dir, not the plugin cache", () => {
+    assert.equal(boot.runtimeDir(), RT);
+  });
+});
+
+describe("node version gate", () => {
+  it("refuses anything below 22.5 (node:sqlite is the only driver available)", () => {
+    assert.equal(boot.nodeVersionOk("20.11.0"), false);
+    assert.equal(boot.nodeVersionOk("22.4.1"), false);
+  });
+
+  it("accepts 22.5 and newer", () => {
+    assert.equal(boot.nodeVersionOk("22.5.0"), true);
+    assert.equal(boot.nodeVersionOk("24.0.0"), true);
+  });
+});
+
+describe("fast path", () => {
+  beforeEach(resetRuntime);
+
+  it("is false with no recorded state", () => {
+    assert.equal(boot.fastPathOk(RT), false);
+  });
+
+  it("is false when the recorded plugin version is stale", () => {
+    fs.mkdirSync(path.join(RT, "node_modules"), { recursive: true });
+    boot.writeState({ pluginVersion: "0.0.0-old", depsHash: boot.depsHash() }, RT);
+    assert.equal(boot.fastPathOk(RT), false);
+  });
+
+  it("is false after a plugin update moved the install to a new cache dir", () => {
+    const pkg = require("../../package.json");
+    fs.mkdirSync(path.join(RT, "node_modules"), { recursive: true });
+    boot.writeState(
+      {
+        pluginVersion: pkg.version,
+        depsHash: boot.depsHash(),
+        pluginRoot: "/old/plugin/cache/dir",
+      },
+      RT
+    );
+    assert.equal(boot.fastPathOk(RT), false);
+  });
+
+  it("is false when node_modules is missing even if state matches", () => {
+    const pkg = require("../../package.json");
+    boot.writeState({ pluginVersion: pkg.version, depsHash: boot.depsHash() }, RT);
+    assert.equal(boot.fastPathOk(RT), false);
+  });
+});
+
+describe("bootstrap lock", () => {
+  beforeEach(resetRuntime);
+
+  it("is exclusive while held", () => {
+    assert.equal(boot.acquireLock(RT), true);
+    assert.equal(boot.acquireLock(RT), false, "a live lock must not be reclaimed");
+    boot.releaseLock(RT);
+    assert.equal(fs.existsSync(boot.lockPath(RT)), false);
+  });
+
+  it("reclaims a lock whose owner is dead", () => {
+    fs.mkdirSync(boot.lockPath(RT), { recursive: true });
+    // PID 1 is alive but not ours; use an unused high pid instead.
+    fs.writeFileSync(path.join(boot.lockPath(RT), "pid"), "999999", "utf8");
+    assert.equal(boot.lockIsStale(boot.lockPath(RT)), true);
+    assert.equal(boot.acquireLock(RT), true);
+    boot.releaseLock(RT);
+  });
+
+  it("reclaims a lock older than the stale timeout even if its pid is alive", () => {
+    fs.mkdirSync(boot.lockPath(RT), { recursive: true });
+    fs.writeFileSync(path.join(boot.lockPath(RT), "pid"), String(process.pid), "utf8");
+    const old = Date.now() - boot.LOCK_STALE_MS - 1000;
+    fs.utimesSync(boot.lockPath(RT), old / 1000, old / 1000);
+    assert.equal(boot.lockIsStale(boot.lockPath(RT)), true);
+    assert.equal(boot.acquireLock(RT), true);
+    boot.releaseLock(RT);
+  });
+
+  it("treats a lock directory with no pid file as debris", () => {
+    fs.mkdirSync(boot.lockPath(RT), { recursive: true });
+    assert.equal(boot.lockIsStale(boot.lockPath(RT)), true);
+  });
+});
+
+describe("legacy hook cleanup", () => {
+  const settings = path.join(TMP_HOME, "settings-legacy.json");
+
+  beforeEach(() => {
+    fs.rmSync(settings, { force: true });
+    fs.rmSync(`${settings}.ccam-bak`, { force: true });
+  });
+
+  it("removes checkout-installed hook entries and backs the file up first", () => {
+    fs.writeFileSync(
+      settings,
+      JSON.stringify({
+        hooks: {
+          PreToolUse: [
+            {
+              matcher: "*",
+              hooks: [
+                { type: "command", command: "node /repo/scripts/hook-handler.js PreToolUse" },
+              ],
+            },
+            { matcher: "*", hooks: [{ type: "command", command: "node /other/tool.js" }] },
+          ],
+          SessionStart: [
+            {
+              hooks: [
+                { type: "command", command: "node /repo/scripts/hook-handler.js SessionStart" },
+              ],
+            },
+          ],
+        },
+      })
+    );
+    const removed = boot.stripLegacyHooks(settings);
+    assert.equal(removed, 2);
+
+    const after = JSON.parse(fs.readFileSync(settings, "utf8"));
+    assert.equal(after.hooks.PreToolUse.length, 1, "unrelated hooks must survive");
+    assert.match(JSON.stringify(after.hooks.PreToolUse), /other\/tool\.js/);
+    assert.equal(after.hooks.SessionStart, undefined, "an emptied list is dropped");
+    assert.ok(fs.existsSync(`${settings}.ccam-bak`), "must back up before writing");
+  });
+
+  it("leaves a file with no CCAM hooks untouched and writes no backup", () => {
+    fs.writeFileSync(settings, JSON.stringify({ hooks: { Stop: [{ hooks: [] }] } }));
+    assert.equal(boot.stripLegacyHooks(settings), 0);
+    assert.equal(fs.existsSync(`${settings}.ccam-bak`), false);
+  });
+
+  it("is a no-op when no settings file exists", () => {
+    assert.equal(boot.stripLegacyHooks(path.join(TMP_HOME, "nope.json")), 0);
+  });
+});
+
+describe("ccam CLI launcher", () => {
+  const bin = path.join(TMP_HOME, "bin");
+  const target = path.join(bin, process.platform === "win32" ? "ccam.cmd" : "ccam");
+
+  beforeEach(() => {
+    fs.rmSync(bin, { recursive: true, force: true });
+  });
+
+  it("writes a launcher that points at the plugin's bin/ccam.js", () => {
+    assert.equal(boot.linkCli(bin), "written");
+    assert.match(fs.readFileSync(target, "utf8"), /bin[/\\]ccam\.js/);
+  });
+
+  it("is idempotent", () => {
+    boot.linkCli(bin);
+    assert.equal(boot.linkCli(bin), "exists");
+  });
+
+  it("never clobbers a ccam it did not write (a linked checkout keeps winning)", () => {
+    fs.mkdirSync(bin, { recursive: true });
+    fs.writeFileSync(target, '#!/bin/sh\nexec node /my/checkout/bin/ccam.js "$@"\n');
+    assert.equal(boot.linkCli(bin), "foreign");
+    assert.match(fs.readFileSync(target, "utf8"), /my\/checkout/);
+  });
+});