@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/subagents/cli.test.mjs

@@ -1,389 +0,0 @@
-/**
- * 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);
-});