@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

package/test/copilot-installer.test.mjs

@@ -0,0 +1,298 @@
+// Integration tests for `agent-cortex install copilot`: the install-time
+// generator for the Copilot CLI flat agent files (agents/*.agent.md). All tests
+// install into mkdtemp dirs so the real repo agents/ is never touched.
+
+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 { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+import { installCopilot } from "../bin/installers/copilot.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+const CLI_PATH = join(ROOT, "bin", "agent-cortex.mjs");
+
+function runCli(args) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI_PATH, ...args], (error, stdout, stderr) => {
+      resolve({ exitCode: error ? error.code ?? 1 : 0, stdout, stderr });
+    });
+  });
+}
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+function tokenMap() {
+  return {
+    name: "fixture token map",
+    version: 1,
+    harnesses: ["copilot"],
+    tools: {
+      bash: { copilot: "bash" },
+      view: { copilot: "view" },
+      task: { copilot: "task" },
+      ask_user: { copilot: "ask_user" },
+    },
+    paths: {
+      plugin_root: { copilot: "~/.copilot/installed-plugins/_direct/agent-cortex" },
+      agents_dir: { copilot: { base: "plugin_root", relative: "agents" } },
+    },
+  };
+}
+
+function makeFixture() {
+  const root = mkdtempSync(join(tmpdir(), "copilot-installer-"));
+  return {
+    root,
+    output: join(root, "generated"),
+    cleanup: () => rmSync(root, { recursive: true, force: true }),
+  };
+}
+
+function writeFixture(fx, relPath, content) {
+  const p = join(fx.root, relPath);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+}
+
+/** Seed a minimal but realistic package tree (agents + token-map). */
+function seedCopilotPackage(fx, opts = {}) {
+  const { agents = {} } = opts;
+  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(
+      fx,
+      `agents/${name}/copilot/frontmatter.json`,
+      JSON.stringify(
+        def.frontmatter ?? {
+          name: `agent-cortex:${name}`,
+          description: `Description of ${name}`,
+          tools: ["bash", "view"],
+          argumentHint: `Hint for ${name}`,
+        },
+      ),
+    );
+    for (const [section, content] of Object.entries(def.sections ?? {})) {
+      writeFixture(fx, `agents/${name}/copilot/${section}.md`, content);
+    }
+  }
+}
+
+/** Deterministic snapshot of a directory: relative paths + byte content. */
+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 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")]);
+    }
+  };
+  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();
+    try {
+      seedCopilotPackage(fx, {
+        agents: {
+          alpha: {
+            body: "# alpha\nUse {{TOOL:view}} to read.\n{{SECTION:polling}}\nRead {{PATH:agents_dir}}.",
+            sections: { polling: "Spawn with {{TOOL:task}}." },
+            frontmatter: {
+              name: "agent-cortex:alpha",
+              description: "Reads things.",
+              tools: ["bash", "view"],
+              argumentHint: "Read something",
+            },
+          },
+        },
+      });
+
+      const result = 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(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.
+      const order = ["description:", "name: \"agent-cortex:alpha\"", "tools: [", "argument-hint:"].map((s) => content.indexOf(s));
+      assert.ok(order.every((i) => i !== -1), "all frontmatter fields present");
+      assert.deepEqual([...order].sort((a, b) => a - b), order, "frontmatter fields in committed order");
+      assert.match(content, /tools: \["bash", "view"\]/, "copilot tools kept as a YAML array (no translation)");
+      assert.ok(content.includes("Use view to read."), "{{TOOL:view}} substituted");
+      assert.ok(content.includes("Spawn with task."), "{{SECTION:polling}} composed from copilot/polling.md");
+      assert.ok(!/{{/.test(content), "no literal tokens remain");
+      assert.equal(result.agents.length, 1);
+      assert.deepEqual(result.agents, ["alpha"]);
+      assert.equal(result.output, fx.output);
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("skips non-composable entries in agents/ and never clobbers composable sources", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      writeFixture(fx, "agents/README.md", "# agents dir docs\n");
+
+      const result = installCopilot({ root: fx.root, output: fx.output });
+
+      assert.deepEqual(readdirSync(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");
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("throws when a composable dir lacks copilot/frontmatter.json", () => {
+    const fx = 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 }),
+        /without copilot\/frontmatter\.json/,
+      );
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("defaults to the plugin-scanned agents/ dir of the package root (plugin.json \"agents\": \"agents/\")", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+
+      const result = 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");
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("throws on an unknown tool token", () => {
+    const fx = 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}}/);
+    } finally {
+      fx.cleanup();
+    }
+  });
+});
+
+// ─── Output / dry-run ────────────────────────────────────────────────────────
+
+describe("installCopilot — output & dry-run", () => {
+  it("dry-run reports the plan without writing anything", () => {
+    const fx = makeFixture();
+    try {
+      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+
+      const result = 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.deepEqual(result.agents, ["alpha"], "planned files still reported");
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("is deterministic across repeated installs into the same output", () => {
+    const fx = makeFixture();
+    try {
+      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);
+    } finally {
+      fx.cleanup();
+    }
+  });
+});
+
+// ─── 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();
+    try {
+      const result = 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");
+        assert.equal(generated, committed, `${name}.agent.md must match the committed flat file (CI drift check)`);
+      }
+    } finally {
+      fx.cleanup();
+    }
+  });
+});
+
+// ─── CLI wiring ──────────────────────────────────────────────────────────────
+
+describe("CLI integration", () => {
+  it("exits 0 for install copilot --output <tmp> and writes the flat files", async () => {
+    const fx = 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")));
+    } finally {
+      fx.cleanup();
+    }
+  });
+
+  it("exits 0 for install copilot --dry-run and writes nothing", async () => {
+    const fx = 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");
+    } finally {
+      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 { 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);
+  });
+});

package/test/installer.test.mjs

@@ -0,0 +1,179 @@
+// 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.
+
+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 { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join, relative } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+const CLI_PATH = join(ROOT, "bin", "agent-cortex.mjs");
+
+function runCli(args) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI_PATH, ...args], (error, stdout, stderr) => {
+      resolve({ exitCode: error ? error.code ?? 1 : 0, stdout, stderr });
+    });
+  });
+}
+
+function makeTmp() {
+  return mkdtempSync(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) {
+  const entries = [];
+  const walk = (p) => {
+    for (const e of readdirSync(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)]);
+      else if (e.isDirectory()) {
+        entries.push([rel, "dir"]);
+        walk(full);
+      } else entries.push([rel, "file", readFileSync(full, "utf-8")]);
+    }
+  };
+  walk(dir);
+  return entries;
+}
+
+describe("install claude", () => {
+  it("composes agents from the composable sources (claude names, no tokens)", async () => {
+    const out = makeTmp();
+    const { exitCode } = await runCli(["install", "claude", "--output", out]);
+    assert.equal(exitCode, 0);
+
+    const plan = readFileSync(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.
+    assert.match(plan, /bin\/installers\/claude\.mjs/);
+    assert.doesNotMatch(plan, /build-claude-agents/);
+    assert.match(plan, /\nname: plan\n/);
+    assert.doesNotMatch(plan, /\{\{(TOOL|PATH|SECTION):/);
+
+    const ralphPlan = readFileSync(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();
+    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);
+  });
+
+  it("symlinks flattened skills and excludes ralph-coupled skills", async () => {
+    const out = makeTmp();
+    await runCli(["install", "claude", "--output", out]);
+    const skills = join(out, "skills");
+    const names = readdirSync(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")));
+  });
+
+  it("generates plugin.json tracking the package version and referencing hooks.json", async () => {
+    const out = 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"));
+    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();
+    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"));
+    assert.deepStrictEqual(installed, source);
+    assert.ok(source.hooks.SessionStart);
+  });
+
+  it("matches the Notification hook only on documented notification types", async () => {
+    // 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();
+    await runCli(["install", "claude", "--output", out]);
+    const installed = JSON.parse(readFileSync(join(out, "hooks.json"), "utf-8"));
+    const matcher = installed.hooks.Notification.flatMap((g) => g.hooks).length
+      ? installed.hooks.Notification[0].matcher
+      : "";
+    const documented = new Set([
+      "permission_prompt",
+      "idle_prompt",
+      "auth_success",
+      "elicitation_dialog",
+      "elicitation_url_dialog",
+      "elicitation_complete",
+      "elicitation_response",
+      "agent_needs_input",
+      "agent_completed",
+      "quota_auto_resume_fired",
+      "quota_auto_resume_stale",
+      "quota_auto_resume_disabled",
+    ]);
+    const types = matcher ? matcher.split("|") : [];
+    assert.ok(types.length > 0, "Notification hook should list at least one matcher type");
+    for (const t of types) {
+      assert.ok(documented.has(t), `Notification matcher references unknown type "${t}"`);
+    }
+  });
+
+  it("bundles hook support scripts into claude/hooks/ and references them via the plugin root", async () => {
+    const out = 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");
+    assert.equal(bundled, canonical);
+
+    const installed = JSON.parse(readFileSync(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");
+    assert.match(notify[0].command, /^node "\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\/scripts\/notify\.mjs"$/);
+  });
+
+  it("is deterministic across repeated installs into the same output", async () => {
+    const out = makeTmp();
+    await runCli(["install", "claude", "--output", out]);
+    const first = snapshot(out);
+    await runCli(["install", "claude", "--output", out]);
+    assert.deepStrictEqual(snapshot(out), first);
+  });
+
+  it("--dry-run reports the plan without writing anything", async () => {
+    const out = 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);
+  });
+
+  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");
+    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);
+  });
+});

package/test/notify-hook.test.mjs

@@ -0,0 +1,63 @@
+// Tests for the Claude Code Notification hook script (hooks/claude/scripts/notify.mjs).
+// The script reads the Notification hook JSON payload from stdin and prints a
+// `{ "terminalSequence": "..." }` JSON response that Claude Code emits for us
+// (hooks run without a controlling terminal, so OSC sequences must go through
+// terminalSequence — see the Claude Code hooks reference).
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const SCRIPT = join(ROOT, "hooks", "claude", "scripts", "notify.mjs");
+
+/** Run the hook script with the given payload on stdin and a controlled env. */
+function runNotify(payload, env = {}) {
+  return new Promise((resolve) => {
+    const child = execFile(
+      process.execPath,
+      [SCRIPT],
+      { env, timeout: 10_000 },
+      (error, stdout, stderr) => {
+        resolve({ exitCode: error ? error.code ?? 1 : 0, stdout, stderr });
+      },
+    );
+    child.stdin.end(JSON.stringify(payload));
+  });
+}
+
+describe("notify.mjs (Claude Notification hook)", () => {
+  it("emits an OSC 777 desktop notification on a bare-terminal agent_completed payload", async () => {
+    const { exitCode, stdout } = await runNotify(
+      { notification_type: "agent_completed", title: "task done", message: "all tests pass" },
+      { PATH: process.env.PATH },
+    );
+    assert.equal(exitCode, 0);
+    const out = JSON.parse(stdout);
+    assert.ok(out.terminalSequence.startsWith("\u001b]777;notify;"));
+    assert.match(out.terminalSequence, /task done/);
+    assert.match(out.terminalSequence, /all tests pass/);
+  });
+
+  it("switches to OSC 99 when running inside Kitty", async () => {
+    const { exitCode, stdout } = await runNotify(
+      { notification_type: "agent_needs_input", title: "input needed", message: "build broke" },
+      { PATH: process.env.PATH, KITTY_WINDOW_ID: "0" },
+    );
+    assert.equal(exitCode, 0);
+    const out = JSON.parse(stdout);
+    assert.ok(out.terminalSequence.startsWith("\u001b]99;"));
+    assert.match(out.terminalSequence, /build broke/);
+  });
+
+  it("stays silent (no output, exit 0) when the payload has no message", async () => {
+    const { exitCode, stdout } = await runNotify(
+      { notification_type: "permission_prompt" },
+      { PATH: process.env.PATH },
+    );
+    assert.equal(exitCode, 0);
+    assert.equal(stdout, "");
+  });
+});