/** * @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ĩ */ 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("serverIsLive", () => { const infoPath = path.join(TMP_HOME, ".agent-dashboard.json"); beforeEach(() => fs.rmSync(infoPath, { force: true })); after(() => fs.rmSync(infoPath, { force: true })); it("is false with no discovery file at all", () => { // Regression: server-info's resolveAllDashboardPorts() falls back to // [DEFAULT_PORT] when nothing is live (a reasonable guess for the CLI), // which made the bootstrap wrongly believe a server was already running // and skip starting its own. assert.equal(boot.serverIsLive(), false); }); it("is false when every recorded pid is dead", () => { fs.writeFileSync( infoPath, JSON.stringify({ servers: [{ port: 4820, pid: 999999, startedAt: "x" }] }) ); assert.equal(boot.serverIsLive(), false); }); it("is true when a recorded pid is actually alive", () => { fs.writeFileSync( infoPath, JSON.stringify({ servers: [{ port: 4820, pid: process.pid, startedAt: "x" }] }) ); assert.equal(boot.serverIsLive(), true); assert.deepEqual(boot.liveServers(), [{ port: 4820, pid: process.pid, startedAt: "x" }]); }); }); 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/); }); });