@jaybeeuu/agent-cortex 1.39.0 → 1.41.0

package/test/installer.test.mjs

@@ -1,57 +1,101 @@
 // Integration tests for `agent-cortex install claude`: the install-time
-// generator for the Claude Code plugin subtree. All tests install into
-// mkdtemp dirs so the real repo claude/ and ~/.claude are never touched.
+// generator that materialises the Claude Code plugin. The default target is a
+// home-scoped directory (~/.agent-cortex/claude, overridable via HOME for
+// tests); all tests install into mkdtemp dirs — the real ~/.agent-cortex and
+// the repo's canonical sources (agents/, skills/, claude-extras/, hooks/claude/) are never touched.
 
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
-import { mkdtempSync, readFileSync, readdirSync, existsSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
+import {
+  mkdtemp,
+  mkdir,
+  writeFile,
+  chmod,
+  rm,
+  readFile,
+  readdir,
+  stat,
+  lstat,
+  readlink,
+  symlink,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname, join, relative } from "node:path";
+import { installClaude } from "../bin/installers/claude.mjs";
+import { makeFakeClaude, registrationActions } from "./helpers/fake-claude.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..");
 const CLI_PATH = join(ROOT, "bin", "agent-cortex.mjs");
 
-function runCli(args) {
+/** True when a path exists (stat succeeds). */
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run the CLI; optionally pass a custom env (e.g. a fake HOME). */
+function runCli(args, env = {}) {
   return new Promise((resolve) => {
-    execFile(process.execPath, [CLI_PATH, ...args], (error, stdout, stderr) => {
-      resolve({ exitCode: error ? error.code ?? 1 : 0, stdout, stderr });
-    });
+    execFile(
+      process.execPath,
+      [CLI_PATH, ...args],
+      { env: { ...process.env, ...env } },
+      (error, stdout, stderr) => {
+        resolve({ exitCode: error ? error.code ?? 1 : 0, stdout, stderr });
+      },
+    );
   });
 }
 
-function makeTmp() {
-  return mkdtempSync(join(tmpdir(), "agent-cortex-installer-"));
+async function makeTmp() {
+  return await mkdtemp(join(tmpdir(), "agent-cortex-installer-"));
 }
 
-/** Deterministic snapshot of a generated tree: relative paths, kind, and for
- * files/symlinks their byte content / link target. */
-function snapshot(dir) {
+
+/** Deterministic snapshot of a generated tree: kind, and for files/symlinks
+ * their byte content / link target. */
+async function snapshot(dir) {
   const entries = [];
-  const walk = (p) => {
-    for (const e of readdirSync(p, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+  const walk = async (p) => {
+    for (const e of (await readdir(p, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
       const full = join(p, e.name);
       const rel = relative(dir, full);
-      if (e.isSymbolicLink()) entries.push([rel, "link", readlinkSync(full)]);
+      if (e.isSymbolicLink()) entries.push([rel, "link", await readlink(full)]);
       else if (e.isDirectory()) {
         entries.push([rel, "dir"]);
-        walk(full);
-      } else entries.push([rel, "file", readFileSync(full, "utf-8")]);
+        await walk(full);
+      } else entries.push([rel, "file", await readFile(full, "utf-8")]);
     }
   };
-  walk(dir);
+  await walk(dir);
   return entries;
 }
 
+async function listFiles(dir) {
+  if (!(await pathExists(dir))) return [];
+  const out = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await listFiles(p)).map((f) => join(entry.name, f)));
+    else out.push(entry.name);
+  }
+  return out;
+}
+
 describe("install claude", () => {
   it("composes agents from the composable sources (claude names, no tokens)", async () => {
-    const out = makeTmp();
+    const out = await makeTmp();
     const { exitCode } = await runCli(["install", "claude", "--output", out]);
     assert.equal(exitCode, 0);
 
-    const plan = readFileSync(join(out, "agents", "plan.md"), "utf-8");
+    const plan = await readFile(join(out, "agents", "plan.md"), "utf-8");
     assert.match(plan, /^---\n# GENERATED from agents\/plan\//);
     // provenance names the shared installer (no build-time script), so the
     // committed subtree can only come from the install-time generator.
@@ -60,46 +104,127 @@ describe("install claude", () => {
     assert.match(plan, /\nname: plan\n/);
     assert.doesNotMatch(plan, /\{\{(TOOL|PATH|SECTION):/);
 
-    const ralphPlan = readFileSync(join(out, "agents", "ralph-plan.md"), "utf-8");
+    const ralphPlan = await readFile(join(out, "agents", "ralph-plan.md"), "utf-8");
     assert.match(ralphPlan, /^---\n# GENERATED from agents\/ralph-plan\//);
     assert.match(ralphPlan, /\nname: ralph-plan\n/);
   });
 
   it("copies native agents verbatim (ralph stays native, no composed counterpart)", async () => {
-    const out = makeTmp();
+    const out = await makeTmp();
     await runCli(["install", "claude", "--output", out]);
-    const native = readFileSync(join(ROOT, "agents-native", "ralph.md"), "utf-8");
-    assert.equal(readFileSync(join(out, "agents", "ralph.md"), "utf-8"), native);
+    const native = await readFile(join(ROOT, "agents-native", "ralph.md"), "utf-8");
+    assert.equal(await readFile(join(out, "agents", "ralph.md"), "utf-8"), native);
   });
 
-  it("symlinks flattened skills and excludes ralph-coupled skills", async () => {
-    const out = makeTmp();
-    await runCli(["install", "claude", "--output", out]);
+  it("copies skill dirs flat with substituted tokens, no symlinks, excluding ralph-coupled skills", async () => {
+    const out = await makeTmp();
+    const { exitCode } = await runCli(["install", "claude", "--output", out]);
+    assert.equal(exitCode, 0);
+
     const skills = join(out, "skills");
-    const names = readdirSync(skills);
+    const names = await readdir(skills);
     assert.ok(names.includes("tdd"));
     assert.ok(names.includes("plan"));
     assert.ok(!names.includes("ralph"));
     assert.ok(!names.includes("run-pipeline-stage"));
-    assert.ok(lstatSync(join(skills, "tdd")).isSymbolicLink());
-    assert.equal(realpathSync(join(skills, "tdd")), realpathSync(join(ROOT, "skills", "engineering", "tdd")));
+
+    // skills are real directories (copies), not symlinks
+    assert.ok((await stat(join(skills, "tdd"))).isDirectory());
+    assert.ok(await pathExists(join(skills, "tdd", "SKILL.md")));
+    assert.ok(!(await lstat(join(skills, "plan"))).isSymbolicLink());
+
+    // no symlinks anywhere in the materialised tree
+    for (const e of await snapshot(out)) {
+      assert.notEqual(e[1], "link", `unexpected symlink in tree: ${e[0]}`);
+    }
+
+    // tokens substituted against the claude column
+    const techDir = await readFile(join(skills, "technical-direction", "SKILL.md"), "utf-8");
+    assert.ok(techDir.includes("using Grep, Read, and Glob"), "rg/view/glob mapped to Grep/Read/Glob");
+    assert.ok(techDir.includes("via WebFetch"), "web_fetch mapped to WebFetch");
+    assert.doesNotMatch(techDir, /\{\{TOOL:/);
+
+    // null-mapped tool dropped from prose (claude has no read_agent step)
+    const design = await readFile(join(skills, "design-an-interface", "SKILL.md"), "utf-8");
+    assert.ok(design.includes("with Task,"), "task mapped to Task");
+    assert.doesNotMatch(design, /\{\{TOOL:|read_agent/);
+  });
+
+  it("leaves no literal tokens in any installed skill markdown", async () => {
+    const out = await makeTmp();
+    await runCli(["install", "claude", "--output", out]);
+    const files = (await listFiles(join(out, "skills"))).filter((f) => f.endsWith(".md"));
+    assert.ok(files.length > 0);
+    for (const f of files) {
+      const content = await readFile(join(out, "skills", f), "utf-8");
+      assert.doesNotMatch(content, /\{\{TOOL:|\{\{PATH:/, `no literal tokens in skill ${f}`);
+    }
+  });
+
+  it("copies hand-authored plugin extras (.mcp.json, scripts/) from the canonical claude-extras/ dir", async () => {
+    const out = await makeTmp();
+    await runCli(["install", "claude", "--output", out]);
+
+    const mcp = await readFile(join(ROOT, "claude-extras", ".mcp.json"), "utf-8");
+    assert.equal(await readFile(join(out, ".mcp.json"), "utf-8"), mcp);
+
+    const statusline = await readFile(join(ROOT, "claude-extras", "scripts", "statusline-command.sh"), "utf-8");
+    assert.equal(await readFile(join(out, "scripts", "statusline-command.sh"), "utf-8"), statusline);
+  });
+
+  it("copies hand-authored extras from claude-extras/ with executable bits preserved", async () => {
+    // claude-extras/ is the canonical store for .mcp.json and scripts/ (the
+    // committed claude/ subtree is retired); the installer ships them into the
+    // output, keeping the executable bit, and never writes into the store.
+    const root = await makeTmp();
+    const out = join(root, "out");
+    const extras = join(root, "claude-extras");
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ name: "agent-cortex", version: "1.2.3", license: "MIT" }),
+    );
+    await writeFile(
+      join(root, "token-map.json"),
+      JSON.stringify({ tools: {}, paths: { plugin_root: { claude: "PLUGIN_ROOT" } } }),
+    );
+    await mkdir(join(root, "agents"));
+    await mkdir(join(root, "skills"));
+    await mkdir(join(extras, "scripts"), { recursive: true });
+    await writeFile(join(extras, ".mcp.json"), JSON.stringify({ mcpServers: {} }, null, 2) + "\n");
+    await writeFile(join(extras, "scripts", "statusline-command.sh"), "#!/bin/sh\necho status\n");
+    await chmod(join(extras, "scripts", "statusline-command.sh"), 0o755);
+
+    const result = await installClaude({ root, output: out });
+
+    assert.deepEqual(result.handAuthored, [".mcp.json", "scripts/statusline-command.sh"]);
+    assert.equal(
+      await readFile(join(out, ".mcp.json"), "utf-8"),
+      JSON.stringify({ mcpServers: {} }, null, 2) + "\n",
+    );
+    assert.equal(
+      (await stat(join(out, "scripts", "statusline-command.sh"))).mode & 0o111,
+      0o111,
+      "executable bit survives the copy",
+    );
+    // the source store is never written to
+    assert.deepStrictEqual((await readdir(extras)).sort(), [".mcp.json", "scripts"]);
   });
 
   it("generates plugin.json tracking the package version and referencing hooks.json", async () => {
-    const out = makeTmp();
+    const out = await makeTmp();
     await runCli(["install", "claude", "--output", out]);
-    const pkgVersion = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8")).version;
-    const plugin = JSON.parse(readFileSync(join(out, ".claude-plugin", "plugin.json"), "utf-8"));
+    const pkgVersion = JSON.parse(await readFile(join(ROOT, "package.json"), "utf-8")).version;
+    const plugin = JSON.parse(await readFile(join(out, ".claude-plugin", "plugin.json"), "utf-8"));
     assert.equal(plugin.name, "agent-cortex");
     assert.equal(plugin.version, pkgVersion);
     assert.equal(plugin.hooks, "./hooks.json");
   });
 
   it("generates hooks.json from the canonical hooks/claude/ source", async () => {
-    const out = makeTmp();
+    const out = await makeTmp();
     await runCli(["install", "claude", "--output", out]);
-    const source = JSON.parse(readFileSync(join(ROOT, "hooks", "claude", "hooks.json"), "utf-8"));
-    const installed = JSON.parse(readFileSync(join(out, "hooks.json"), "utf-8"));
+    const source = JSON.parse(await readFile(join(ROOT, "hooks", "claude", "hooks.json"), "utf-8"));
+    const installed = JSON.parse(await readFile(join(out, "hooks.json"), "utf-8"));
     assert.deepStrictEqual(installed, source);
     assert.ok(source.hooks.SessionStart);
   });
@@ -108,9 +233,9 @@ describe("install claude", () => {
     // The Notification matcher is an exact-string list over `notification_type` —
     // there are no success/error types, so that matcher would never fire. Guard
     // against it recurring (see docs/claude-hooks.md for the documented type list).
-    const out = makeTmp();
+    const out = await makeTmp();
     await runCli(["install", "claude", "--output", out]);
-    const installed = JSON.parse(readFileSync(join(out, "hooks.json"), "utf-8"));
+    const installed = JSON.parse(await readFile(join(out, "hooks.json"), "utf-8"));
     const matcher = installed.hooks.Notification.flatMap((g) => g.hooks).length
       ? installed.hooks.Notification[0].matcher
       : "";
@@ -135,15 +260,15 @@ describe("install claude", () => {
     }
   });
 
-  it("bundles hook support scripts into claude/hooks/ and references them via the plugin root", async () => {
-    const out = makeTmp();
+  it("bundles hook support scripts into hooks/ and references them via the plugin root", async () => {
+    const out = await makeTmp();
     await runCli(["install", "claude", "--output", out]);
 
-    const canonical = readFileSync(join(ROOT, "hooks", "claude", "scripts", "notify.mjs"), "utf-8");
-    const bundled = readFileSync(join(out, "hooks", "scripts", "notify.mjs"), "utf-8");
+    const canonical = await readFile(join(ROOT, "hooks", "claude", "scripts", "notify.mjs"), "utf-8");
+    const bundled = await readFile(join(out, "hooks", "scripts", "notify.mjs"), "utf-8");
     assert.equal(bundled, canonical);
 
-    const installed = JSON.parse(readFileSync(join(out, "hooks.json"), "utf-8"));
+    const installed = JSON.parse(await readFile(join(out, "hooks.json"), "utf-8"));
     const notify = installed.hooks.Notification.flatMap((g) => g.hooks)
       .filter((h) => h.command?.includes("notify.mjs"));
     assert.ok(notify.length === 1, "hooks.json should reference the notification script");
@@ -151,29 +276,389 @@ describe("install claude", () => {
   });
 
   it("is deterministic across repeated installs into the same output", async () => {
-    const out = makeTmp();
+    const out = await makeTmp();
     await runCli(["install", "claude", "--output", out]);
-    const first = snapshot(out);
+    const first = await snapshot(out);
     await runCli(["install", "claude", "--output", out]);
-    assert.deepStrictEqual(snapshot(out), first);
+    assert.deepStrictEqual(await snapshot(out), first);
   });
 
-  it("--dry-run reports the plan without writing anything", async () => {
-    const out = makeTmp();
+  it("--dry-run reports the plan (copied skills, output target) without writing anything", async () => {
+    const out = await makeTmp();
     const { exitCode, stdout } = await runCli(["install", "claude", "--output", out, "--dry-run"]);
     assert.equal(exitCode, 0);
     assert.ok(/would/i.test(stdout));
-    assert.equal(existsSync(join(out, "agents")), false);
-    assert.equal(existsSync(join(out, "skills")), false);
-    assert.equal(existsSync(join(out, ".claude-plugin")), false);
+    assert.ok(/copied/i.test(stdout), "dry-run should describe skills as copied, not symlinked");
+    assert.ok(stdout.includes(out), "dry-run should name the output target");
+    assert.equal(await pathExists(join(out, "agents")), false);
+    assert.equal(await pathExists(join(out, "skills")), false);
+    assert.equal(await pathExists(join(out, ".claude-plugin")), false);
   });
 
-  it("leaves the committed claude/ subtree untouched when --output is given", async () => {
-    const out = makeTmp();
-    const beforeSkills = readdirSync(join(ROOT, "claude", "skills")).sort();
-    const beforePlugin = readFileSync(join(ROOT, "claude", ".claude-plugin", "plugin.json"), "utf-8");
+  it("leaves the canonical sources untouched (no generated claude/ output)", async () => {
+    const out = await makeTmp();
+    const beforeExtras = (await readdir(join(ROOT, "claude-extras"))).sort();
+    const beforeExtrasScripts = (await readdir(join(ROOT, "claude-extras", "scripts"))).sort();
     await runCli(["install", "claude", "--output", out]);
-    assert.deepStrictEqual(readdirSync(join(ROOT, "claude", "skills")).sort(), beforeSkills);
-    assert.equal(readFileSync(join(ROOT, "claude", ".claude-plugin", "plugin.json"), "utf-8"), beforePlugin);
+    // the committed claude/ store carries only the settings template — the
+    // generated plugin subtree (agents/, skills/, .claude-plugin/, hooks.json)
+    // is never committed, and installs never write into the canonical sources
+    assert.deepStrictEqual((await readdir(join(ROOT, "claude"))).sort(), ["settings.json"]);
+    assert.deepStrictEqual((await readdir(join(ROOT, "claude-extras"))).sort(), beforeExtras);
+    assert.deepStrictEqual((await readdir(join(ROOT, "claude-extras", "scripts"))).sort(), beforeExtrasScripts);
+  });
+
+  it("plain install materialises into ~/.agent-cortex/claude with a marketplace manifest and drives the claude plugin CLI", async () => {
+    const fakeHome = await makeTmp();
+    const fakeBin = await makeTmp();
+    const fake = await makeFakeClaude(fakeBin);
+    const env = { HOME: fakeHome, PATH: `${fakeBin}:${process.env.PATH}` };
+
+    const { exitCode, stdout } = await runCli(["install", "claude"], env);
+    assert.equal(exitCode, 0);
+
+    const pluginDir = join(fakeHome, ".agent-cortex", "claude");
+    // plugin materialised into the home install root
+    assert.ok(await pathExists(join(pluginDir, "skills", "tdd", "SKILL.md")), "skill copied into home plugin");
+    assert.ok((await stat(join(pluginDir, "skills", "tdd"))).isDirectory(), "home skills are copies, not symlinks");
+    // hand-authored extras shipped into the home plugin
+    assert.equal(
+      await readFile(join(pluginDir, ".mcp.json"), "utf-8"),
+      await readFile(join(ROOT, "claude-extras", ".mcp.json"), "utf-8"),
+    );
+
+    // marketplace manifest at the home root exposes ./claude
+    const marketPath = join(fakeHome, ".agent-cortex", ".claude-plugin", "marketplace.json");
+    const market = JSON.parse(await readFile(marketPath, "utf-8"));
+    assert.equal(market.name, "jaybeeuu");
+    assert.deepStrictEqual(market.plugins, [
+      {
+        name: "agent-cortex",
+        source: "./claude",
+        description: "Personal Claude Code plugin with custom agents and skills",
+      },
+    ]);
+
+    // registration drove the claude plugin CLI against the home install root:
+    // fresh state → marketplace add + plugin install (state queries and the
+    // availability probe are not registration actions).
+    const calls = (await readFile(fake.log, "utf-8")).trim().split("\n");
+    assert.deepEqual(registrationActions(calls), [
+      `plugin marketplace add ${join(fakeHome, ".agent-cortex")}`,
+      "plugin install agent-cortex@jaybeeuu -y",
+    ]);
+    assert.ok(stdout.includes("Registering plugin"), "CLI reports registration");
+
+    // the default install also materialises ~/.claude/settings.json from the
+    // committed template, owning only the two declared keys
+    const settings = JSON.parse(await readFile(join(fakeHome, ".claude", "settings.json"), "utf-8"));
+    assert.deepEqual(Object.keys(settings).sort(), ["enabledPlugins", "extraKnownMarketplaces"]);
+  });
+
+  it("re-running a plain install is the update path: no marketplace re-add, no double-install", async () => {
+    const fakeHome = await makeTmp();
+    const fakeBin = await makeTmp();
+    const fake = await makeFakeClaude(fakeBin);
+    const env = { HOME: fakeHome, PATH: `${fakeBin}:${process.env.PATH}` };
+    const allCalls = async () => (await readFile(fake.log, "utf-8")).trim().split("\n").filter(Boolean);
+
+    const first = await runCli(["install", "claude"], env);
+    assert.equal(first.exitCode, 0);
+    assert.deepEqual(registrationActions(await allCalls()), [
+      `plugin marketplace add ${join(fakeHome, ".agent-cortex")}`,
+      "plugin install agent-cortex@jaybeeuu -y",
+    ]);
+    const run1End = (await allCalls()).length;
+
+    // Second run: marketplace registered, plugin at the materialised version →
+    // marketplace update only — the documented no-op update path.
+    const second = await runCli(["install", "claude"], env);
+    assert.equal(second.exitCode, 0);
+    assert.deepEqual(registrationActions((await allCalls()).slice(run1End)), [
+      "plugin marketplace update jaybeeuu",
+    ]);
+
+    // Across both runs the marketplace was added exactly once and the plugin
+    // installed exactly once (idempotent — no re-add, no double-install).
+    const all = registrationActions(await allCalls());
+    assert.equal(all.filter((c) => c.startsWith("plugin marketplace add")).length, 1);
+    assert.equal(all.filter((c) => c === "plugin install agent-cortex@jaybeeuu -y").length, 1);
+  });
+
+  it("warns with manual commands when the claude CLI is missing; --require-register fails the run", async () => {
+    const fakeHome = await makeTmp();
+    const env = { HOME: fakeHome, PATH: "/nonexistent" };
+
+    // Default: warn-only — the plugin is materialised, exit 0, manual
+    // registration commands printed for the user to run.
+    const warned = await runCli(["install", "claude"], env);
+    assert.equal(warned.exitCode, 0, "missing claude CLI is warn-only by default");
+    assert.match(warned.stderr, /NOT registered/);
+    assert.match(warned.stderr, /claude plugin marketplace add /);
+    assert.match(warned.stderr, /claude plugin install agent-cortex@jaybeeuu -y/);
+    // The plugin itself is still materialised into the fake home.
+    assert.ok(await pathExists(join(fakeHome, ".agent-cortex", "claude", "skills", "tdd", "SKILL.md")));
+
+    // --require-register escalates the same failure to a non-zero exit.
+    const required = await runCli(["install", "claude", "--require-register"], env);
+    assert.equal(required.exitCode, 1);
+    assert.match(required.stderr, /require-register/);
+  });
+
+  it("plain --dry-run prints the home target and copied-skill plan without writing", async () => {
+    const fakeHome = await makeTmp();
+    const fakeBin = await makeTmp();
+    await makeFakeClaude(fakeBin);
+    const env = { HOME: fakeHome, PATH: `${fakeBin}:${process.env.PATH}` };
+
+    const { exitCode, stdout } = await runCli(["install", "claude", "--dry-run"], env);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes(join(fakeHome, ".agent-cortex", "claude")), "dry-run names the home target");
+    assert.ok(stdout.includes(join(fakeHome, ".claude", "settings.json")), "dry-run names the settings target");
+    assert.ok(/copied/i.test(stdout), "dry-run describes copied skills");
+    assert.equal(await pathExists(join(fakeHome, ".agent-cortex")), false, "nothing written in dry-run");
+    assert.equal(await pathExists(join(fakeHome, ".claude")), false, "no settings written in dry-run");
+  });
+
+  it("--output stays generate-only and never touches ~/.claude/settings.json", async () => {
+    const fakeHome = await makeTmp();
+    const out = await makeTmp();
+    try {
+      const { exitCode } = await runCli(["install", "claude", "--output", out], { HOME: fakeHome });
+      assert.equal(exitCode, 0);
+      assert.ok(await pathExists(join(out, ".claude-plugin", "plugin.json")), "plugin subtree still generated");
+      assert.equal(await pathExists(join(fakeHome, ".claude")), false, "no user settings written by --output");
+    } finally {
+      await rm(fakeHome, { recursive: true, force: true });
+      await rm(out, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects token-map.json versions newer than the implemented contract", async () => {
+    const fixture = await makeTmp();
+    try {
+      await mkdir(join(fixture, "agents"), { recursive: true });
+      await writeFile(
+        join(fixture, "token-map.json"),
+        JSON.stringify({ name: "fixture", version: 99, tools: {}, paths: {} }),
+      );
+      await assert.rejects(
+        installClaude({ root: fixture, output: join(fixture, "out") }),
+        /version 99/,
+      );
+      assert.equal(await pathExists(join(fixture, "out")), false, "nothing written when the contract is rejected");
+    } finally {
+      await rm(fixture, { recursive: true, force: true });
+    }
+  });
+});
+
+// ─── installClaude — ~/.claude/settings.json ─────────────────────────────────
+
+/** A claude/settings.json template carrying the two CLI-owned keys. */
+function settingsTemplate(overrides = {}) {
+  return { enabledPlugins: {}, extraKnownMarketplaces: {}, ...overrides };
+}
+
+/** A realistic personal ~/.claude/settings.json (keys the installer must never own). */
+function personalSettings(overrides = {}) {
+  return {
+    permissions: { allow: ["Bash(pnpm test:*)"] },
+    hooks: { SessionStart: [{ hooks: [{ type: "command", command: "echo personal" }] }] },
+    env: { PERSONAL_FLAG: "1" },
+    statusLine: { type: "command", command: "~/.claude/statusline.sh" },
+    ...overrides,
+  };
+}
+
+/** Minimal package root with a claude/settings.json template, enough for
+ * installClaude to materialise the plugin subtree into a throwaway output. */
+async function makeSettingsFixture({ template = settingsTemplate(), settings } = {}) {
+  const root = await makeTmp();
+  await writeFile(
+    join(root, "package.json"),
+    JSON.stringify({ name: "agent-cortex", version: "1.2.3", license: "MIT" }),
+  );
+  await writeFile(
+    join(root, "token-map.json"),
+    JSON.stringify({ tools: {}, paths: { plugin_root: { claude: "PLUGIN_ROOT" } } }),
+  );
+  await mkdir(join(root, "agents"));
+  await mkdir(join(root, "skills"));
+  if (template !== null) {
+    await mkdir(join(root, "claude"), { recursive: true });
+    await writeFile(join(root, "claude", "settings.json"), JSON.stringify(template, null, 2) + "\n");
+  }
+  const output = join(root, "out");
+  const settingsPath = join(root, "claude-home", "settings.json");
+  if (settings !== undefined) {
+    await mkdir(dirname(settingsPath), { recursive: true });
+    await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  }
+  return { root, output, settingsPath, cleanup: () => rm(root, { recursive: true, force: true }) };
+}
+
+describe("install claude — settings.json", () => {
+  it("materialises a real settings.json carrying the CLI-owned keys from the committed template", async () => {
+    const fx = await makeSettingsFixture({
+      template: settingsTemplate({
+        enabledPlugins: { "context7@claude-plugins-official": true },
+        extraKnownMarketplaces: {
+          "claude-plugins-official": { source: { source: "github", repo: "anthropics/claude-plugins" } },
+        },
+      }),
+    });
+    try {
+      const result = await installClaude({ root: fx.root, output: fx.output, settingsPath: fx.settingsPath });
+
+      assert.equal(result.settings.path, fx.settingsPath);
+      assert.equal(result.settings.action, "written");
+      assert.equal((await lstat(fx.settingsPath)).isSymbolicLink(), false, "settings.json is a real file");
+      const settings = JSON.parse(await readFile(fx.settingsPath, "utf-8"));
+      assert.deepEqual(settings.enabledPlugins, { "context7@claude-plugins-official": true });
+      assert.deepEqual(settings.extraKnownMarketplaces, {
+        "claude-plugins-official": { source: { source: "github", repo: "anthropics/claude-plugins" } },
+      });
+      assert.deepEqual(
+        Object.keys(settings).sort(),
+        ["enabledPlugins", "extraKnownMarketplaces"],
+        "only the two CLI-owned keys are written",
+      );
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("preserves personal and unknown keys on re-install (merge-keep-personal)", async () => {
+    const fx = await makeSettingsFixture({
+      template: settingsTemplate({
+        theme: { name: "dark", accent: "blue" },
+        enabledPlugins: { "team@official": true },
+      }),
+      settings: personalSettings({
+        theme: { name: "light" },
+        personalOnly: { nested: true },
+      }),
+    });
+    try {
+      await installClaude({ root: fx.root, output: fx.output, settingsPath: fx.settingsPath });
+      const settings = JSON.parse(await readFile(fx.settingsPath, "utf-8"));
+
+      assert.deepEqual(settings.permissions, { allow: ["Bash(pnpm test:*)"] });
+      assert.deepEqual(settings.hooks, { SessionStart: [{ hooks: [{ type: "command", command: "echo personal" }] }] });
+      assert.deepEqual(settings.env, { PERSONAL_FLAG: "1" });
+      assert.deepEqual(settings.statusLine, { type: "command", command: "~/.claude/statusline.sh" });
+      assert.deepEqual(settings.personalOnly, { nested: true }, "unknown key preserved");
+      assert.equal(settings.theme.name, "light", "personal value wins over the template default");
+      assert.equal(settings.theme.accent, "blue", "template default fills the unset nested key");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("owns only enabledPlugins + extraKnownMarketplaces — personal entries under them are replaced by the template", async () => {
+    const fx = await makeSettingsFixture({
+      template: settingsTemplate({
+        enabledPlugins: { "team@official": true },
+        extraKnownMarketplaces: {
+          official: { source: { source: "github", repo: "anthropics/plugins" } },
+        },
+      }),
+      settings: personalSettings({
+        enabledPlugins: { "personal@mine": true },
+        extraKnownMarketplaces: { mine: { source: { source: "github", repo: "me/mine" } } },
+      }),
+    });
+    try {
+      await installClaude({ root: fx.root, output: fx.output, settingsPath: fx.settingsPath });
+      const settings = JSON.parse(await readFile(fx.settingsPath, "utf-8"));
+
+      assert.deepEqual(settings.enabledPlugins, { "team@official": true }, "template owns enabledPlugins");
+      assert.deepEqual(
+        settings.extraKnownMarketplaces,
+        { official: { source: { source: "github", repo: "anthropics/plugins" } } },
+        "template owns extraKnownMarketplaces",
+      );
+      assert.ok(!("personal@mine" in settings.enabledPlugins));
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("dry-run plans the settings write without touching the filesystem", async () => {
+    const fx = await makeSettingsFixture({
+      template: settingsTemplate({ enabledPlugins: { "team@official": true } }),
+    });
+    try {
+      const result = await installClaude({
+        root: fx.root,
+        output: fx.output,
+        settingsPath: fx.settingsPath,
+        dryRun: true,
+      });
+
+      assert.equal(result.settings.action, "would-write");
+      assert.equal(await pathExists(fx.settingsPath), false, "nothing written in dry-run");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("re-running is idempotent — the second install leaves settings.json unchanged", async () => {
+    const fx = await makeSettingsFixture({
+      template: settingsTemplate({ enabledPlugins: { "team@official": true } }),
+    });
+    try {
+      await installClaude({ root: fx.root, output: fx.output, settingsPath: fx.settingsPath });
+      const first = await readFile(fx.settingsPath, "utf-8");
+
+      const second = await installClaude({ root: fx.root, output: fx.output, settingsPath: fx.settingsPath });
+      assert.equal(second.settings.action, "unchanged");
+      assert.equal(await readFile(fx.settingsPath, "utf-8"), first);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("replaces a legacy symlinked settings.json with a real file, never writing through the template", async () => {
+    const fx = await makeSettingsFixture({
+      template: settingsTemplate({ enabledPlugins: { "team@official": true } }),
+    });
+    try {
+      const templatePath = join(fx.root, "claude", "settings.json");
+      const templateBefore = await readFile(templatePath, "utf-8");
+      await mkdir(dirname(fx.settingsPath), { recursive: true });
+      await symlink(templatePath, fx.settingsPath);
+
+      const result = await installClaude({ root: fx.root, output: fx.output, settingsPath: fx.settingsPath });
+
+      assert.equal(result.settings.action, "removed-symlink");
+      assert.equal(result.settings.removedSymlink, true);
+      assert.equal((await lstat(fx.settingsPath)).isSymbolicLink(), false, "symlink replaced by a real file");
+      const settings = JSON.parse(await readFile(fx.settingsPath, "utf-8"));
+      assert.deepEqual(settings.enabledPlugins, { "team@official": true });
+      assert.equal(await readFile(templatePath, "utf-8"), templateBefore, "template never written through");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("warns and skips when the package ships no claude/settings.json template", async () => {
+    const fx = await makeSettingsFixture({ template: null });
+    try {
+      const warnings = [];
+      const result = await installClaude({
+        root: fx.root,
+        output: fx.output,
+        settingsPath: fx.settingsPath,
+        warn: (m) => warnings.push(m),
+      });
+
+      assert.equal(result.settings, null);
+      assert.ok(warnings.some((w) => w.includes("claude/settings.json")), "missing template is warned about");
+      assert.equal(await pathExists(fx.settingsPath), false, "nothing written without a template");
+    } finally {
+      await fx.cleanup();
+    }
   });
 });