@jaybeeuu/agent-cortex 1.39.0 → 1.40.0

package/test/helpers/fake-claude.mjs

@@ -0,0 +1,152 @@
+// Shared test helper: a stateful fake `claude` binary for the `claude plugin`
+// CLI. The real CLI is a genuine external system (and its home config must
+// never be touched by tests), so tests drive this fake instead. It records
+// every invocation to `calls.log` (argv, space-joined, one line each) and
+// simulates just enough real behaviour for idempotency assertions:
+//
+//   plugin --help                    → exit 0 (availability probe)
+//   plugin marketplace list --json   → registered marketplaces as JSON
+//   plugin marketplace add <root>    → registers <root> (name read from its
+//                                      .claude-plugin/marketplace.json)
+//   plugin marketplace update <m>    → exit 0
+//   plugin list --json               → installed plugins as JSON
+//   plugin install <id> -y           → records id at the version published by
+//                                      the marketplace source's plugin.json
+//   plugin update <name> -y          → re-reads the version from the source
+//
+// State lives in `state.json` next to the binary, so a test can re-run the CLI
+// against the same fake and observe the update path. `failWhen` makes any
+// invocation whose argv contains the substring exit 1 (probe/command failures).
+//
+// Written async throughout (the fake is a child process and the helper's own
+// I/O is test code) — the repo's check-no-sync lint scans test/ for *Sync.
+
+import { chmod, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const FAKE_CLAUDE_SCRIPT = [
+  "#!/usr/bin/env node",
+  "// Stateful fake for the `claude plugin` CLI (test/helpers/fake-claude.mjs).",
+  "const fs = require('node:fs/promises');",
+  "const path = require('node:path');",
+  "",
+  "const dir = __dirname;",
+  "const stateFile = path.join(dir, 'state.json');",
+  "const logFile = path.join(dir, 'calls.log');",
+  "const failWhenFile = path.join(dir, 'failWhen.txt');",
+  "",
+  "(async () => {",
+  "  const argv = process.argv.slice(2);",
+  "  const joined = argv.join(' ');",
+  "  await fs.appendFile(logFile, joined + '\\n');",
+  "",
+  "  const failWhen = await fs.readFile(failWhenFile, 'utf8').catch(() => null);",
+  "  if (failWhen && joined.includes(failWhen)) process.exit(1);",
+  "",
+  "  if (argv[0] !== 'plugin') process.exit(0);",
+  "",
+  "  const readState = async () => {",
+  "    try {",
+  "      return JSON.parse(await fs.readFile(stateFile, 'utf8'));",
+  "    } catch {",
+  "      return { markets: [], installed: [] };",
+  "    }",
+  "  };",
+  "  const writeState = (state) => fs.writeFile(stateFile, JSON.stringify(state));",
+  "",
+  "  // Real claude resolves the plugin version from the marketplace source's",
+  "  // plugin.json; the fake mirrors that by reading <source>/claude/.claude-plugin/plugin.json.",
+  "  const pluginJsonVersion = async (marketPath) => {",
+  "    try {",
+  "      return JSON.parse(await fs.readFile(path.join(marketPath, 'claude', '.claude-plugin', 'plugin.json'), 'utf8')).version;",
+  "    } catch {",
+  "      return undefined;",
+  "    }",
+  "  };",
+  "  const marketplaceName = async (source) => {",
+  "    try {",
+  "      return JSON.parse(await fs.readFile(path.join(source, '.claude-plugin', 'marketplace.json'), 'utf8')).name;",
+  "    } catch {",
+  "      return undefined;",
+  "    }",
+  "  };",
+  "",
+  "  const state = await readState();",
+  "  const [sub, ...rest] = argv.slice(1);",
+  "",
+  "  if (sub === '--help') process.exit(0);",
+  "",
+  "  if (sub === 'marketplace') {",
+  "    const [op, ...opArgs] = rest;",
+  "    if (op === 'list') {",
+  "      console.log(JSON.stringify(state.markets));",
+  "      process.exit(0);",
+  "    }",
+  "    if (op === 'add') {",
+  "      const source = path.resolve(opArgs[0]);",
+  "      const name = (await marketplaceName(source)) ?? 'market-' + state.markets.length;",
+  "      if (!state.markets.some((m) => m.name === name)) state.markets.push({ name, path: source });",
+  "      await writeState(state);",
+  "      process.exit(0);",
+  "    }",
+  "    if (op === 'update') process.exit(0);",
+  "    process.exit(0);",
+  "  }",
+  "",
+  "  if (sub === 'list') {",
+  "    console.log(JSON.stringify(state.installed));",
+  "    process.exit(0);",
+  "  }",
+  "",
+  "  if (sub === 'install') {",
+  "    const id = rest[0];",
+  "    if (!state.installed.some((i) => i.id === id)) {",
+  "      const [name, market] = id.split('@');",
+  "      const m = state.markets.find((x) => x.name === market);",
+  "      state.installed.push({ id, version: m ? (await pluginJsonVersion(m.path)) ?? '0.0.0' : '0.0.0' });",
+  "      await writeState(state);",
+  "    }",
+  "    process.exit(0);",
+  "  }",
+  "",
+  "  if (sub === 'update') {",
+  "    const name = rest[0];",
+  "    const entry = state.installed.find((i) => i.id.startsWith(name + '@'));",
+  "    if (entry) {",
+  "      const m = state.markets.find((x) => x.name === entry.id.split('@')[1]);",
+  "      const v = m ? await pluginJsonVersion(m.path) : undefined;",
+  "      if (v) entry.version = v;",
+  "      await writeState(state);",
+  "    }",
+  "    process.exit(0);",
+  "  }",
+  "",
+  "  process.exit(0);",
+  "})().catch((err) => {",
+  "  console.error(err);",
+  "  process.exit(1);",
+  "});",
+].join("\n");
+
+/** Create a stateful fake `claude` binary in `dir`.
+ * @param {string} dir  Directory to hold bin, calls.log, state.json
+ * @param {{ failWhen?: string|null }} [options]  Invocations whose argv contains
+ *                                                failWhen exit 1
+ * @returns {Promise<{ bin: string, log: string, state: string }>} */
+export async function makeFakeClaude(dir, { failWhen = null } = {}) {
+  const bin = join(dir, "claude");
+  const log = join(dir, "calls.log");
+  const state = join(dir, "state.json");
+  await writeFile(bin, FAKE_CLAUDE_SCRIPT + "\n");
+  await chmod(bin, 0o755);
+  await writeFile(state, JSON.stringify({ markets: [], installed: [] }));
+  if (failWhen) await writeFile(join(dir, "failWhen.txt"), failWhen);
+  return { bin, log, state };
+}
+
+/** Registration actions from a fake call log: probes and state queries dropped.
+ * @param {string[]} lines  Raw call-log lines
+ * @returns {string[]}      Action lines (marketplace add/update, install, update) */
+export function registrationActions(lines) {
+  return lines.filter((c) => !c.startsWith("plugin --help") && !c.includes("--json"));
+}

package/test/installer.test.mjs

@@ -1,57 +1,100 @@
 // 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,
+} 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 +103,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 +232,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 +259,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 +275,157 @@ 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 committed 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);
+    // no committed claude/ output remains, and installs never write into the
+    // canonical sources the plugin materialises from
+    assert.equal(await pathExists(join(ROOT, "claude")), false);
+    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");
+  });
+
+  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(/copied/i.test(stdout), "dry-run describes copied skills");
+    assert.equal(await pathExists(join(fakeHome, ".agent-cortex")), false, "nothing written in dry-run");
+  });
+
+  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 });
+    }
   });
 });