@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/subagents/cli.test.mjs

@@ -0,0 +1,389 @@
+/**
+ * cli.test.mjs — `maestro subagents <sub>` (§2.4). Every subcommand returns
+ * `{ok, code, lines}` and only prints when asked, which is what makes the whole
+ * verb surface testable without importing bin/maestro.mjs.
+ * Run: node --test lib/subagents/cli.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { loadRoster, loadState, run, skeleton, usage } from "./cli.mjs";
+import { buildManifest, readManifest, writeManifest } from "./manifest.mjs";
+import { listOutbox, readLock, writeCache } from "./lock.mjs";
+import { agentFilePath } from "./resolve.mjs";
+import { checkAgentFile, parseAgentMd, stringifyAgentMd } from "./schema.mjs";
+
+const ENV = { COHORT_BASE: "https://hq.example.com", COHORT_API_KEY: "sk-test", COHORT_ORG_ID: "org_1" };
+const OFFLINE_ENV = {};
+
+function md(slug, body = `# ${slug}\n\nsdk body\n`, over = {}) {
+  return stringifyAgentMd({ name: slug, description: `${slug} does things`, model: "sonnet", tools: ["Read"], ...over }, body);
+}
+function put(root, slug, text) {
+  mkdirSync(join(root, "agents", slug), { recursive: true });
+  writeFileSync(join(root, "agents", slug, "agent.md"), text);
+  return text;
+}
+function sdkWith(slugs) {
+  const root = mkdtempSync(join(tmpdir(), "subagent-cli-sdk-"));
+  for (const s of slugs) put(root, s, md(s));
+  writeManifest(root, buildManifest({ maestroRoot: root, sdkVersion: "9.9.9" }).manifest);
+  return root;
+}
+function agentRepo(agentConfig = { firstName: "Isla", function: "executive-operator", altitude: "c-suite" }) {
+  const root = mkdtempSync(join(tmpdir(), "subagent-cli-agent-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  mkdirSync(join(root, "workflows"), { recursive: true });
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify(agentConfig));
+  return root;
+}
+function fakeFetch(reply) {
+  const calls = [];
+  const fn = async (url, init) => {
+    calls.push({ url: String(url), body: init && init.body ? JSON.parse(init.body) : null });
+    const r = typeof reply === "function" ? reply(String(url), calls.length) : reply;
+    if (r instanceof Error) throw r;
+    return { ok: r.ok !== false, status: r.status || 200, json: async () => r.body };
+  };
+  fn.calls = calls;
+  return fn;
+}
+const okFrame = (result) => ({ ok: true, status: 200, body: { ok: true, result } });
+const opts = (agentRoot, maestroRoot, extra = {}) => ({ agentRoot, maestroRoot, print: false, env: OFFLINE_ENV, ...extra });
+/** The RPC methods a run actually invoked, in order. Every command loads state
+ *  first, so `subagent.resolve` legitimately leads most write sequences. */
+const methods = (f) => f.calls.map((c) => c.url.split("/v1/")[1]);
+const callTo = (f, method) => f.calls.find((c) => c.url.endsWith(`/v1/${method}`));
+const surface = (ids) => async () => ({ standardAgents: ids.map((id) => ({ id, role: id })), roleAgents: [] });
+
+// ---------------------------------------------------------------------------
+// dispatch
+// ---------------------------------------------------------------------------
+
+test("no subcommand / help prints usage; an unknown one exits 2", async () => {
+  const sdk = sdkWith([]);
+  const agent = agentRepo();
+  for (const argv of [[], ["help"]]) {
+    const r = await run(argv, opts(agent, sdk));
+    assert.equal(r.ok, true);
+    assert.equal(r.lines.join("\n"), usage());
+  }
+  const bad = await run(["frobnicate"], opts(agent, sdk));
+  assert.deepEqual([bad.ok, bad.code], [false, 2]);
+});
+
+test("every documented subcommand appears in the usage text", async () => {
+  for (const cmd of ["list", "status", "show", "diff", "add", "fork", "publish", "pull", "drop", "export", "--no-network"]) {
+    assert.match(usage(), new RegExp(cmd.replace(/[-]/g, "\\-")));
+  }
+});
+
+// ---------------------------------------------------------------------------
+// local-first reads
+// ---------------------------------------------------------------------------
+
+test("list: resolved roster with the winning layer per slug, no network needed", async () => {
+  const sdk = sdkWith(["alpha", "beta"]);
+  const agent = agentRepo();
+  const r = await run(["list"], opts(agent, sdk));
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.data.entries.map((e) => [e.slug, e.layer]), [["alpha", "sdk"], ["beta", "sdk"]]);
+  assert.match(r.lines.join("\n"), /alpha\s+sdk/);
+});
+
+test("list --json emits the slim provenance shape", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const r = await run(["list", "--json"], opts(agentRepo(), sdk));
+  const parsed = JSON.parse(r.lines[0]);
+  assert.deepEqual(Object.keys(parsed[0]).sort(), ["contentHash", "layer", "localEdits", "slug", "source", "version"]);
+});
+
+test("status: the three-way diff, with the roster injected", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  writeFileSync(join(agent, "workflows", "w.yaml"), "steps:\n  - agent: alpha\n  - agent: ghost-writer\n");
+  const r = await run(["status", "--json"], opts(agent, sdk, { resolveSurfaceImpl: surface(["alpha", "beta"]) }));
+  assert.equal(r.ok, false, "not complete: beta is missing and ghost-writer dangles");
+  assert.deepEqual(r.data.missing.map((m) => m.slug), ["beta"]);
+  assert.deepEqual(r.data.unrostered.map((u) => u.ref), ["ghost-writer"]);
+  assert.deepEqual(r.data.idle.map((i) => i.slug), ["beta"]);
+});
+
+test("status: a clean repo reports complete", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  writeFileSync(join(agent, "workflows", "w.yaml"), "steps:\n  - agent: alpha\n");
+  const r = await run(["status"], opts(agent, sdk, { resolveSurfaceImpl: surface(["alpha"]) }));
+  assert.equal(r.ok, true);
+  assert.match(r.lines.join("\n"), /roster complete/);
+});
+
+test("show: prints the resolved body and its provenance", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const r = await run(["show", "alpha"], opts(agentRepo(), sdk));
+  const text = r.lines.join("\n");
+  assert.match(text, /layer:\s+sdk/);
+  assert.match(text, /source:\s+sdk:\/\/9\.9\.9\/alpha/);
+  assert.match(text, /sdk body/);
+});
+
+test("show / diff / fork: a slug that resolves nowhere fails cleanly", async () => {
+  const sdk = sdkWith([]);
+  const agent = agentRepo();
+  for (const argv of [["show", "nope"], ["diff", "nope"], ["fork", "nope"]]) {
+    const r = await run(argv, opts(agent, sdk));
+    assert.deepEqual([r.ok, r.code], [false, 1]);
+    assert.match(r.lines.join(" "), /no sub-agent resolves/);
+  }
+});
+
+test("show / diff / publish / add / drop: a missing slug argument prints usage", async () => {
+  const sdk = sdkWith([]);
+  const agent = agentRepo();
+  for (const argv of [["show"], ["diff"], ["publish"], ["add"], ["fork"], ["drop"], ["export"]]) {
+    const r = await run(argv, opts(agent, sdk));
+    assert.equal(r.ok, false);
+    assert.match(r.lines.join(" "), /usage: maestro subagents/);
+  }
+});
+
+test("diff: reports identical after a pull, and shows the delta after an edit", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  await run(["pull"], opts(agent, sdk));
+  assert.match((await run(["diff", "alpha"], opts(agent, sdk))).lines.join("\n"), /identical to the sdk layer/);
+
+  writeFileSync(agentFilePath(agent, "alpha"), readFileSync(agentFilePath(agent, "alpha"), "utf8") + "\nHAND EDIT\n");
+  const after = await run(["diff", "alpha"], opts(agent, sdk));
+  assert.match(after.lines.join("\n"), /differs from the local layer/);
+  assert.match(after.lines.join("\n"), /HAND EDIT/);
+});
+
+// ---------------------------------------------------------------------------
+// pull
+// ---------------------------------------------------------------------------
+
+test("pull: materialises winners, records the lock, and is idempotent", async () => {
+  const sdk = sdkWith(["alpha", "beta"]);
+  const agent = agentRepo();
+  const first = await run(["pull"], opts(agent, sdk));
+  assert.equal(first.data.written, 2);
+  assert.equal(existsSync(agentFilePath(agent, "alpha")), true);
+
+  const lock = readLock(agent);
+  assert.equal(lock.agents.alpha.layer, "sdk");
+  assert.ok(lock.agents.alpha.fileHash);
+
+  const second = await run(["pull"], opts(agent, sdk));
+  assert.equal(second.data.written, 0, "nothing churns on a second pull");
+});
+
+test("pull: leaves a local edit alone; --force is the ONLY thing that overwrites it", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  const mine = put(agent, "alpha", md("alpha", "# alpha\n\nMINE\n"));
+
+  const gentle = await run(["pull"], opts(agent, sdk));
+  assert.equal(gentle.data.written, 0);
+  assert.equal(readFileSync(agentFilePath(agent, "alpha"), "utf8"), mine);
+
+  const forced = await run(["pull", "--force"], opts(agent, sdk));
+  assert.equal(forced.data.written, 1);
+  assert.match(readFileSync(agentFilePath(agent, "alpha"), "utf8"), /sdk body/);
+});
+
+test("pull: an unreachable hq degrades to SDK + cache and still succeeds", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  const r = await run(["pull"], opts(agent, sdk, { env: ENV, fetchImpl: fakeFetch(new Error("ECONNREFUSED")) }));
+  assert.equal(r.ok, true, "a dead registry degrades the roster, it never blocks the agent");
+  assert.equal(r.data.written, 1);
+  assert.deepEqual(readLock(agent).degraded, ["workspace"]);
+  assert.match(r.lines.join("\n"), /degraded: workspace/);
+});
+
+test("pull: the workspace layer wins when hq answers, and the body is cached for next time", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  const f = fakeFetch(okFrame({
+    rosterVersion: 12,
+    entries: [{ slug: "alpha", definitionId: "d1", version: 3, contentHash: "h", frontmatter: { name: "alpha", description: "d", model: "sonnet", tools: ["Read"] }, body: "# alpha\n\nWORKSPACE BODY\n" }],
+  }));
+  const r = await run(["pull"], opts(agent, sdk, { env: ENV, fetchImpl: f }));
+  assert.equal(r.data.written, 1);
+  assert.match(readFileSync(agentFilePath(agent, "alpha"), "utf8"), /WORKSPACE BODY/);
+  assert.equal(readLock(agent).rosterVersion, 12);
+  assert.equal(readLock(agent).agents.alpha.definitionId, "d1");
+});
+
+test("--no-network never calls hq, even when the agent IS enrolled", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const f = fakeFetch(okFrame({ rosterVersion: 1, entries: [] }));
+  await run(["pull", "--no-network"], opts(agentRepo(), sdk, { env: ENV, fetchImpl: f }));
+  assert.deepEqual(f.calls, []);
+});
+
+test("offline layer 1: a workspace pin in the lock resolves from the cache with no network", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  writeCache(agent, "alpha", 3, stringifyAgentMd({ name: "alpha", description: "d", model: "sonnet", tools: ["Read"] }, "# alpha\n\nCACHED\n"));
+  writeFileSync(join(agent, ".maestro-seed.json"), "");
+  const { mergeLock } = await import("./lock.mjs");
+  mergeLock(agent, { agents: { alpha: { layer: "workspace", definitionId: "d1", version: 3, contentHash: "h" } } });
+
+  const st = await loadState({ agentRoot: agent, maestroRoot: sdk, network: false, env: OFFLINE_ENV });
+  assert.equal(st.resolved.bySlug.get("alpha").layer, "workspace");
+  assert.match(st.resolved.bySlug.get("alpha").body, /CACHED/, "the cache is a de-facto fourth layer");
+});
+
+// ---------------------------------------------------------------------------
+// writes
+// ---------------------------------------------------------------------------
+
+test("add: scaffolds a VALID skeleton and calls create + pin", async () => {
+  const sdk = sdkWith([]);
+  const agent = agentRepo();
+  const f = fakeFetch(okFrame({ definitionId: "d1", version: 1 }));
+  const r = await run(["add", "new-helper"], opts(agent, sdk, { env: ENV, fetchImpl: f }));
+  assert.equal(r.ok, true);
+
+  const text = readFileSync(agentFilePath(agent, "new-helper"), "utf8");
+  assert.equal(checkAgentFile(text, "new-helper").ok, true, "the scaffold must validate on the first pass");
+  assert.deepEqual(methods(f), ["subagent.resolve", "subagent.create", "subagent.pin"], "state is loaded first, then the two writes");
+  assert.equal(callTo(f, "subagent.create").body.slug, "new-helper");
+});
+
+test("add: refuses to clobber an existing file without --force", async () => {
+  const sdk = sdkWith([]);
+  const agent = agentRepo();
+  const mine = put(agent, "taken", md("taken", "# taken\n\nMINE\n"));
+  const r = await run(["add", "taken"], opts(agent, sdk));
+  assert.equal(r.ok, false);
+  assert.match(r.lines.join(" "), /already exists/);
+  assert.equal(readFileSync(agentFilePath(agent, "taken"), "utf8"), mine);
+});
+
+test("add: offline, the write queues to the outbox instead of being lost", async () => {
+  const sdk = sdkWith([]);
+  const agent = agentRepo();
+  const r = await run(["add", "new-helper"], opts(agent, sdk, { env: ENV, fetchImpl: fakeFetch(new Error("offline")) }));
+  assert.equal(r.ok, true, "the local scaffold still succeeded");
+  assert.deepEqual(listOutbox(agent).map((e) => e.op), ["subagent.create"]);
+  assert.match(r.lines.join("\n"), /queued offline/);
+});
+
+test("skeleton: full model id, a tools array, and tokens declared from the body", () => {
+  // The two fields that used to drift between shipped and generated agents.
+  const fm = parseAgentMd(skeleton("helper", { fullName: "Isla Roselli" })).frontmatter;
+  assert.equal(fm.model, "claude-sonnet-4-6");
+  assert.deepEqual(fm.tools, ["Read", "Write", "Edit", "Glob", "Grep"]);
+  assert.deepEqual(fm.tokens, ["agent.firstName"]);
+  assert.equal(checkAgentFile(skeleton("helper"), "helper").ok, true);
+});
+
+test("fork: copies the resolved body and RENAMES it, so the copy still validates", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  const f = fakeFetch(okFrame({ definitionId: "d2", version: 1 }));
+  const r = await run(["fork", "alpha", "--as", "alpha-mine"], opts(agent, sdk, { env: ENV, fetchImpl: f }));
+  assert.equal(r.ok, true);
+  const sent = callTo(f, "subagent.fork").body;
+  assert.equal(sent.slug, "alpha-mine");
+  assert.equal(sent.baseSlug, "alpha");
+  assert.equal(sent.baseLayer, "sdk");
+  assert.equal(sent.frontmatter.name, "alpha-mine", "name must equal the NEW dirname or it fails at materialisation");
+  assert.deepEqual(methods(f), ["subagent.resolve", "subagent.fork", "subagent.pin"]);
+});
+
+test("publish: refuses an invalid local file BEFORE hq sees it", async () => {
+  const sdk = sdkWith([]);
+  const agent = agentRepo();
+  put(agent, "broken", md("broken", "# broken\n\nb\n", { name: "wrong-name" }));
+  const f = fakeFetch(okFrame({ version: 2 }));
+  const r = await run(["publish", "broken"], opts(agent, sdk, { env: ENV, fetchImpl: f }));
+  assert.equal(r.ok, false);
+  assert.match(r.lines.join(" "), /must equal the directory name/);
+  assert.deepEqual(f.calls, [], "the operator gets the full error list, not one server-side message");
+});
+
+test("publish: sends the on-disk body with provenance stripped", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  await run(["pull"], opts(agent, sdk));
+  const f = fakeFetch(okFrame({ version: 2 }));
+  const r = await run(["publish", "alpha"], opts(agent, sdk, { env: ENV, fetchImpl: f }));
+  assert.equal(r.ok, true);
+  const sent = callTo(f, "subagent.publishVersion").body;
+  assert.equal("layer" in sent.frontmatter, false, "shipping provenance upstream would make the next fetch claim to come from itself");
+  assert.equal("contentHash" in sent.frontmatter, false);
+  assert.match(sent.body, /sdk body/);
+});
+
+test("publish: a file that does not exist fails without a request", async () => {
+  const f = fakeFetch(okFrame({}));
+  const r = await run(["publish", "nope"], opts(agentRepo(), sdkWith([]), { env: ENV, fetchImpl: f }));
+  assert.equal(r.ok, false);
+  assert.match(r.lines.join(" "), /does not exist/);
+  assert.deepEqual(f.calls, []);
+});
+
+test("drop: unpins, optionally yanks, records the drop and NEVER deletes the file", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  await run(["pull"], opts(agent, sdk));
+  const f = fakeFetch(okFrame({}));
+  const r = await run(["drop", "alpha", "--yank"], opts(agent, sdk, { env: ENV, fetchImpl: f }));
+  assert.equal(r.ok, true);
+  assert.deepEqual(methods(f), ["subagent.resolve", "subagent.unpin", "subagent.yank"]);
+  assert.equal(existsSync(agentFilePath(agent, "alpha")), true, "removal is a status flip, never a delete");
+  assert.equal(readLock(agent).acceptedDrops[0].ref, "alpha");
+});
+
+// ---------------------------------------------------------------------------
+// export — the ENTIRE "push upstream" story in v1
+// ---------------------------------------------------------------------------
+
+test("export --to-sdk: writes the body + manifest entry and prints the PR line", async () => {
+  const sdk = sdkWith(["alpha"]);
+  const agent = agentRepo();
+  const dest = mkdtempSync(join(tmpdir(), "sdk-checkout-"));
+  mkdirSync(join(dest, "agents"), { recursive: true });
+
+  const r = await run(["export", "alpha", "--to-sdk", dest], opts(agent, sdk));
+  assert.equal(r.ok, true);
+  const written = readFileSync(join(dest, "agents", "alpha", "agent.md"), "utf8");
+  assert.equal(parseAgentMd(written).frontmatter.layer, undefined, "what lands in the SDK is the DEFINITION, not one org's copy of it");
+  assert.ok(readManifest(dest).agents.alpha, "the destination manifest is regenerated");
+  assert.match(r.lines.join("\n"), /gh pr create/, "no new auth, no PAT, no hq surface — promotion is a human PR");
+});
+
+test("export: requires --to-sdk", async () => {
+  const r = await run(["export", "alpha"], opts(agentRepo(), sdkWith(["alpha"])));
+  assert.equal(r.ok, false);
+  assert.match(r.lines.join(" "), /--to-sdk/);
+});
+
+// ---------------------------------------------------------------------------
+// roster loading
+// ---------------------------------------------------------------------------
+
+test("loadRoster: uses the injected surface; fail-open to [] when it throws", async () => {
+  assert.deepEqual((await loadRoster({}, { resolveSurfaceImpl: surface(["alpha"]) })).map((a) => a.id), ["alpha"]);
+  assert.deepEqual(await loadRoster({}, { resolveSurfaceImpl: async () => { throw new Error("boom"); } }), []);
+});
+
+test("loadRoster: no function/altitude → no authoritative roster, and that is fine", async () => {
+  assert.deepEqual(await loadRoster({}), []);
+  assert.deepEqual(await loadRoster({ function: "executive-operator" }), []);
+});
+
+test("loadRoster: the REAL capability pack resolves a non-empty roster", async () => {
+  const roster = await loadRoster({ function: "executive-operator", altitude: "c-suite" });
+  assert.ok(roster.length >= 1, "the shipped capability packs must still produce a roster");
+  assert.equal(roster.every((a) => typeof a.id === "string" && a.id), true);
+});