@jaybeeuu/agent-cortex 1.38.1 → 1.40.0

package/test/copilot-installer.test.mjs

@@ -5,7 +5,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { mkdtemp, mkdir, writeFile, rm, readFile, readdir, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { join, dirname } from "node:path";
@@ -15,6 +15,16 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..");
 const CLI_PATH = join(ROOT, "bin", "agent-cortex.mjs");
 
+/** True when a path exists (stat succeeds). */
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function runCli(args) {
   return new Promise((resolve) => {
     execFile(process.execPath, [CLI_PATH, ...args], (error, stdout, stderr) => {
@@ -43,28 +53,28 @@ function tokenMap() {
   };
 }
 
-function makeFixture() {
-  const root = mkdtempSync(join(tmpdir(), "copilot-installer-"));
+async function makeFixture() {
+  const root = await mkdtemp(join(tmpdir(), "copilot-installer-"));
   return {
     root,
     output: join(root, "generated"),
-    cleanup: () => rmSync(root, { recursive: true, force: true }),
+    cleanup: async () => rm(root, { recursive: true, force: true }),
   };
 }
 
-function writeFixture(fx, relPath, content) {
+async function writeFixture(fx, relPath, content) {
   const p = join(fx.root, relPath);
-  mkdirSync(dirname(p), { recursive: true });
-  writeFileSync(p, content);
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, content);
 }
 
 /** Seed a minimal but realistic package tree (agents + token-map). */
-function seedCopilotPackage(fx, opts = {}) {
+async function seedCopilotPackage(fx, opts = {}) {
   const { agents = {} } = opts;
-  writeFixture(fx, "token-map.json", JSON.stringify(tokenMap()));
+  await writeFixture(fx, "token-map.json", JSON.stringify(tokenMap()));
   for (const [name, def] of Object.entries(agents)) {
-    writeFixture(fx, `agents/${name}/agent.md`, def.body ?? `# ${name}\nBody of ${name}.`);
-    writeFixture(
+    await writeFixture(fx, `agents/${name}/agent.md`, def.body ?? `# ${name}\nBody of ${name}.`);
+    await writeFixture(
       fx,
       `agents/${name}/copilot/frontmatter.json`,
       JSON.stringify(
@@ -77,34 +87,34 @@ function seedCopilotPackage(fx, opts = {}) {
       ),
     );
     for (const [section, content] of Object.entries(def.sections ?? {})) {
-      writeFixture(fx, `agents/${name}/copilot/${section}.md`, content);
+      await writeFixture(fx, `agents/${name}/copilot/${section}.md`, content);
     }
   }
 }
 
 /** Deterministic snapshot of a directory: relative paths + byte content. */
-function snapshot(dir) {
+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);
       if (e.isDirectory()) {
         entries.push([e.name, "dir"]);
-        walk(full);
-      } else entries.push([e.name, "file", readFileSync(full, "utf-8")]);
+        await walk(full);
+      } else entries.push([e.name, "file", await readFile(full, "utf-8")]);
     }
   };
-  walk(dir);
+  await walk(dir);
   return entries;
 }
 
 // ─── Agent composition ───────────────────────────────────────────────────────
 
 describe("installCopilot — agent composition", () => {
-  it("writes one flat <name>.agent.md per composable agent dir with copilot frontmatter and no leftover tokens", () => {
-    const fx = makeFixture();
+  it("writes one flat <name>.agent.md per composable agent dir with copilot frontmatter and no leftover tokens", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, {
+      await seedCopilotPackage(fx, {
         agents: {
           alpha: {
             body: "# alpha\nUse {{TOOL:view}} to read.\n{{SECTION:polling}}\nRead {{PATH:agents_dir}}.",
@@ -119,11 +129,11 @@ describe("installCopilot — agent composition", () => {
         },
       });
 
-      const result = installCopilot({ root: fx.root, output: fx.output });
+      const result = await installCopilot({ root: fx.root, output: fx.output });
 
       const file = join(fx.output, "alpha.agent.md");
-      assert.ok(existsSync(file), "flat agent file written");
-      const content = readFileSync(file, "utf-8");
+      assert.ok(await pathExists(file), "flat agent file written");
+      const content = await readFile(file, "utf-8");
       assert.ok(content.startsWith("---\n"), "yaml frontmatter");
       assert.ok(content.includes("# GENERATED from agents/alpha/ by scripts/build-copilot-agents.mjs — DO NOT EDIT."));
       // Committed flat-file field order: description, name, tools (YAML array), argument-hint.
@@ -138,64 +148,64 @@ describe("installCopilot — agent composition", () => {
       assert.deepEqual(result.agents, ["alpha"]);
       assert.equal(result.output, fx.output);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("skips non-composable entries in agents/ and never clobbers composable sources", () => {
-    const fx = makeFixture();
+  it("skips non-composable entries in agents/ and never clobbers composable sources", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
-      writeFixture(fx, "agents/README.md", "# agents dir docs\n");
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await writeFixture(fx, "agents/README.md", "# agents dir docs\n");
 
-      const result = installCopilot({ root: fx.root, output: fx.output });
+      const result = await installCopilot({ root: fx.root, output: fx.output });
 
-      assert.deepEqual(readdirSync(fx.output).sort(), ["alpha.agent.md"], "no README, no subdirectories written");
+      assert.deepEqual((await readdir(fx.output)).sort(), ["alpha.agent.md"], "no README, no subdirectories written");
       assert.deepEqual(result.agents, ["alpha"]);
       // The composable source dir next to the generated file stays untouched.
-      assert.ok(existsSync(join(fx.root, "agents", "alpha", "agent.md")), "composable source preserved");
-      assert.ok(existsSync(join(fx.root, "agents", "alpha", "copilot", "frontmatter.json")), "harness dir preserved");
+      assert.ok(await pathExists(join(fx.root, "agents", "alpha", "agent.md")), "composable source preserved");
+      assert.ok(await pathExists(join(fx.root, "agents", "alpha", "copilot", "frontmatter.json")), "harness dir preserved");
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("throws when a composable dir lacks copilot/frontmatter.json", () => {
-    const fx = makeFixture();
+  it("throws when a composable dir lacks copilot/frontmatter.json", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
-      rmSync(join(fx.root, "agents", "alpha", "copilot"), { recursive: true, force: true });
-      assert.throws(
-        () => installCopilot({ root: fx.root, output: fx.output }),
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await rm(join(fx.root, "agents", "alpha", "copilot"), { recursive: true, force: true });
+      await assert.rejects(
+        installCopilot({ root: fx.root, output: fx.output }),
         /without copilot\/frontmatter\.json/,
       );
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("defaults to the plugin-scanned agents/ dir of the package root (plugin.json \"agents\": \"agents/\")", () => {
-    const fx = makeFixture();
+  it("defaults to the plugin-scanned agents/ dir of the package root (plugin.json \"agents\": \"agents/\")", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
 
-      const result = installCopilot({ root: fx.root });
+      const result = await installCopilot({ root: fx.root });
 
       assert.equal(result.output, join(fx.root, "agents"), "default output is the dir plugin.json scans");
-      assert.ok(existsSync(join(fx.root, "agents", "alpha.agent.md")), "flat file lands next to the composable dir");
-      assert.ok(existsSync(join(fx.root, "agents", "alpha", "agent.md")), "composable source untouched");
+      assert.ok(await pathExists(join(fx.root, "agents", "alpha.agent.md")), "flat file lands next to the composable dir");
+      assert.ok(await pathExists(join(fx.root, "agents", "alpha", "agent.md")), "composable source untouched");
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("throws on an unknown tool token", () => {
-    const fx = makeFixture();
+  it("throws on an unknown tool token", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha\nUse {{TOOL:nope}} now." } } });
-      assert.throws(() => installCopilot({ root: fx.root, output: fx.output }), /unknown tool token {{TOOL:nope}}/);
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha\nUse {{TOOL:nope}} now." } } });
+      await assert.rejects(installCopilot({ root: fx.root, output: fx.output }), /unknown tool token {{TOOL:nope}}/);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 });
@@ -203,37 +213,37 @@ describe("installCopilot — agent composition", () => {
 // ─── Output / dry-run ────────────────────────────────────────────────────────
 
 describe("installCopilot — output & dry-run", () => {
-  it("dry-run reports the plan without writing anything", () => {
-    const fx = makeFixture();
+  it("dry-run reports the plan without writing anything", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
 
-      const result = installCopilot({ root: fx.root, output: fx.output, dryRun: true });
+      const result = await installCopilot({ root: fx.root, output: fx.output, dryRun: true });
 
       assert.equal(result.dryRun, true);
-      assert.equal(existsSync(fx.output), false, "no output dir created in dry-run");
+      assert.equal(await pathExists(fx.output), false, "no output dir created in dry-run");
       assert.deepEqual(result.agents, ["alpha"], "planned files still reported");
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("is deterministic across repeated installs into the same output", () => {
-    const fx = makeFixture();
+  it("is deterministic across repeated installs into the same output", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, {
+      await seedCopilotPackage(fx, {
         agents: {
           alpha: { body: "# alpha\n{{SECTION:polling}}", sections: { polling: "Poll with {{TOOL:task}}." } },
           beta: { body: "# beta" },
         },
       });
 
-      installCopilot({ root: fx.root, output: fx.output });
-      const first = snapshot(fx.output);
-      installCopilot({ root: fx.root, output: fx.output });
-      assert.deepEqual(snapshot(fx.output), first);
+      await installCopilot({ root: fx.root, output: fx.output });
+      const first = await snapshot(fx.output);
+      await installCopilot({ root: fx.root, output: fx.output });
+      assert.deepEqual(await snapshot(fx.output), first);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 });
@@ -241,19 +251,19 @@ describe("installCopilot — output & dry-run", () => {
 // ─── Integration against the real repo ───────────────────────────────────────
 
 describe("installCopilot — real repo integration", () => {
-  it("regenerates byte-identical copies of the committed agents/*.agent.md files", () => {
-    const fx = makeFixture();
+  it("regenerates byte-identical copies of the committed agents/*.agent.md files", async () => {
+    const fx = await makeFixture();
     try {
-      const result = installCopilot({ root: ROOT, output: fx.output });
+      const result = await installCopilot({ root: ROOT, output: fx.output });
 
       assert.deepEqual(result.agents.sort(), ["plan", "ralph", "ralph-plan", "strategy"]);
       for (const name of result.agents) {
-        const generated = readFileSync(join(fx.output, `${name}.agent.md`), "utf-8");
-        const committed = readFileSync(join(ROOT, "agents", `${name}.agent.md`), "utf-8");
+        const generated = await readFile(join(fx.output, `${name}.agent.md`), "utf-8");
+        const committed = await readFile(join(ROOT, "agents", `${name}.agent.md`), "utf-8");
         assert.equal(generated, committed, `${name}.agent.md must match the committed flat file (CI drift check)`);
       }
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 });
@@ -262,37 +272,37 @@ describe("installCopilot — real repo integration", () => {
 
 describe("CLI integration", () => {
   it("exits 0 for install copilot --output <tmp> and writes the flat files", async () => {
-    const fx = makeFixture();
+    const fx = await makeFixture();
     try {
       const { exitCode, stdout } = await runCli(["install", "copilot", "--output", fx.output]);
       assert.equal(exitCode, 0);
       assert.ok(stdout.includes("copilot"), "prints the harness name");
       assert.ok(stdout.includes("Generated"), "prints the generation summary");
-      assert.ok(existsSync(join(fx.output, "ralph.agent.md")), "agent files written");
-      assert.ok(existsSync(join(fx.output, "plan.agent.md")));
+      assert.ok(await pathExists(join(fx.output, "ralph.agent.md")), "agent files written");
+      assert.ok(await pathExists(join(fx.output, "plan.agent.md")));
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
   it("exits 0 for install copilot --dry-run and writes nothing", async () => {
-    const fx = makeFixture();
+    const fx = await makeFixture();
     try {
       const { exitCode, stdout } = await runCli(["install", "copilot", "--output", fx.output, "--dry-run"]);
       assert.equal(exitCode, 0);
       assert.ok(/dry-run/i.test(stdout));
-      assert.equal(existsSync(fx.output), false, "no files written in dry-run");
+      assert.equal(await pathExists(fx.output), false, "no files written in dry-run");
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
   it("exits 0 for install copilot (default output) without touching committed files", async () => {
-    const before = readFileSync(join(ROOT, "agents", "ralph.agent.md"), "utf-8");
+    const before = await readFile(join(ROOT, "agents", "ralph.agent.md"), "utf-8");
     const { exitCode } = await runCli(["install", "copilot"]);
     assert.equal(exitCode, 0);
     // Default output regenerates the shared agents/ dir in place — output must
     // stay byte-identical to what is committed.
-    assert.equal(readFileSync(join(ROOT, "agents", "ralph.agent.md"), "utf-8"), before);
+    assert.equal(await readFile(join(ROOT, "agents", "ralph.agent.md"), "utf-8"), before);
   });
 });

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"));
+}