claude-code-swarm 0.3.24 → 0.3.26

package/src/__tests__/loadout-template-shape.test.mjs

@@ -0,0 +1,102 @@
+/**
+ * Loadout template shape — runtime-shape verification.
+ *
+ * Loads the openteams `loadout-demo` template via `TemplateLoader.load()`
+ * and verifies that `template.roles.<name>.loadout.skills.*` keeps the
+ * snake_case field names declared in the JSON schema. The bridge
+ * (`mergeOpenteamsSkillsIntoCriteria`) reads `max_tokens` — if the loader
+ * normalizes to camelCase server-side, the bridge would produce wrong
+ * output silently.
+ *
+ * This test is the ground-truth check that the schema field names match
+ * the runtime shape consumed by the bridge.
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { describe, it, expect } from "vitest";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LOADOUT_DEMO = path.resolve(
+  __dirname,
+  "../../../openteams/examples/loadout-demo",
+);
+
+function openteamsAvailable() {
+  try {
+    const cwd = path.resolve(__dirname, "../..");
+    require.resolve("openteams", { paths: [cwd] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const SKIP = !fs.existsSync(LOADOUT_DEMO) || !openteamsAvailable();
+
+describe.skipIf(SKIP)("loadout template shape (openteams runtime)", () => {
+  /** @type {import('openteams')} */
+  let ot;
+  /** @type {import('openteams').ResolvedTemplate} */
+  let template;
+
+  it("loads loadout-demo via openteams TemplateLoader", async () => {
+    ot = await import("openteams");
+    expect(ot.TemplateLoader).toBeDefined();
+    template = ot.TemplateLoader.load(LOADOUT_DEMO);
+    expect(template).toBeDefined();
+    expect(template.roles).toBeDefined();
+  });
+
+  it("template.roles is a Map keyed by role name", () => {
+    // Bridge code calls .get() — fail loudly if the runtime shape is plain object.
+    expect(template.roles instanceof Map).toBe(true);
+    expect(template.roles.has("reviewer")).toBe(true);
+    expect(template.roles.has("implementer")).toBe(true);
+  });
+
+  it("reviewer role has a loadout with skills (extends chain resolved)", () => {
+    const role = template.roles.get("reviewer");
+    expect(role?.loadout).toBeDefined();
+    expect(role.loadout.skills).toBeDefined();
+  });
+
+  it("loadout.skills retains snake_case field name max_tokens (NOT maxTokens)", () => {
+    // This is the load-bearing assertion. The bridge in
+    // skilltree-client.mjs reads `loadoutSkills.max_tokens`. If the
+    // loader normalized to camelCase, the bridge would never see the
+    // value and silently produce LoadoutCriteria with no maxTokens.
+    const reviewer = template.roles.get("reviewer");
+    const skills = reviewer.loadout.skills;
+
+    expect(Object.prototype.hasOwnProperty.call(skills, "max_tokens")).toBe(true);
+    expect(Object.prototype.hasOwnProperty.call(skills, "maxTokens")).toBe(false);
+    expect(typeof skills.max_tokens).toBe("number");
+  });
+
+  it("reviewer's max_tokens is inherited from code-reviewer parent (30000)", () => {
+    // Sanity check that `extends:` resolution flowed through; otherwise
+    // the field-name test above could be a false positive on a
+    // self-declared value.
+    const skills = template.roles.get("reviewer").loadout.skills;
+    expect(skills.max_tokens).toBe(30000);
+  });
+
+  it("loadout.skills.profile is camelCase-free string (no normalization)", () => {
+    // Profile is single-word so it can't visibly normalize, but assert
+    // the key is `profile` (not `Profile` or similar) and the value is
+    // a string, just to lock the shape.
+    const skills = template.roles.get("reviewer").loadout.skills;
+    expect(typeof skills.profile).toBe("string");
+    expect(skills.profile.length).toBeGreaterThan(0);
+  });
+
+  it("loadout.skills.include is an array of skill ids", () => {
+    const skills = template.roles.get("reviewer").loadout.skills;
+    expect(Array.isArray(skills.include)).toBe(true);
+    // reviewer extends security-auditor (extends code-reviewer);
+    // include is unioned across the chain.
+    expect(skills.include.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/mcp-health-checker.test.mjs

@@ -0,0 +1,327 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import {
+  checkMcpHealth,
+  collectScopeReferences,
+  discoverActiveSet,
+  formatHealthReport,
+} from "../mcp-health-checker.mjs";
+
+describe("checkMcpHealth", () => {
+  it("classifies declared servers as ok when active", () => {
+    const report = checkMcpHealth({
+      providers: new Map([
+        ["ast-grep", { command: "npx", args: ["ast-grep-mcp"] }],
+      ]),
+      activeSet: new Map([
+        ["ast-grep", { source: "project", spec: { command: "npx" } }],
+      ]),
+    });
+
+    expect(report.ok).toEqual([
+      expect.objectContaining({ name: "ast-grep", source: "project" }),
+    ]);
+    expect(report.missing).toEqual([]);
+  });
+
+  it("classifies declared-but-not-active servers as missing", () => {
+    const report = checkMcpHealth({
+      providers: {
+        "chrome-devtools": { command: "npx", args: ["chrome-devtools-mcp"] },
+      },
+      activeSet: new Map(),
+    });
+
+    expect(report.missing).toEqual([
+      expect.objectContaining({ name: "chrome-devtools" }),
+    ]);
+    expect(report.ok).toEqual([]);
+  });
+
+  it("separates ref providers from concrete providers", () => {
+    const report = checkMcpHealth({
+      providers: {
+        "secrets-scanner": { ref: "@openhive/secrets-scanner" },
+        "ast-grep": { command: "npx" },
+      },
+      activeSet: new Map([
+        ["ast-grep", { source: "user" }],
+      ]),
+    });
+
+    expect(report.refs).toEqual([
+      expect.objectContaining({
+        name: "secrets-scanner",
+        ref: "@openhive/secrets-scanner",
+      }),
+    ]);
+    expect(report.ok).toEqual([
+      expect.objectContaining({ name: "ast-grep", source: "user" }),
+    ]);
+  });
+
+  it("treats disabled providers as a distinct category", () => {
+    const report = checkMcpHealth({
+      providers: {
+        "ast-grep": { command: "npx", disabled: true },
+      },
+      activeSet: new Map(),
+    });
+
+    expect(report.disabled).toEqual([
+      expect.objectContaining({ name: "ast-grep" }),
+    ]);
+    expect(report.missing).toEqual([]);
+  });
+
+  it("surfaces active servers not declared as activeOnly", () => {
+    const report = checkMcpHealth({
+      providers: new Map(),
+      activeSet: new Map([
+        ["opentasks", { source: "plugin" }],
+        ["agent-inbox", { source: "plugin" }],
+      ]),
+    });
+
+    expect(report.activeOnly.map((a) => a.name).sort()).toEqual([
+      "agent-inbox",
+      "opentasks",
+    ]);
+  });
+
+  it("flags scope references to servers not in providers or active", () => {
+    const report = checkMcpHealth({
+      providers: {
+        "ast-grep": { command: "npx" },
+      },
+      activeSet: new Map([["ast-grep", { source: "project" }]]),
+      scopeReferences: [
+        { loadout: "code-reviewer", server: "ast-grep" }, // backed
+        { loadout: "debug-flow", server: "missing-thing" }, // orphan
+      ],
+    });
+
+    expect(report.orphanedReferences).toEqual([
+      { loadout: "debug-flow", server: "missing-thing" },
+    ]);
+  });
+
+  it("accepts both Map and plain-object inputs", () => {
+    const r1 = checkMcpHealth({
+      providers: { x: { command: "y" } },
+      activeSet: { x: { source: "user" } },
+    });
+    const r2 = checkMcpHealth({
+      providers: new Map([["x", { command: "y" }]]),
+      activeSet: new Map([["x", { source: "user" }]]),
+    });
+
+    expect(r1.ok).toHaveLength(1);
+    expect(r2.ok).toHaveLength(1);
+  });
+});
+
+describe("collectScopeReferences", () => {
+  it("extracts scope references from a loadouts map", () => {
+    const loadouts = new Map([
+      [
+        "reviewer",
+        {
+          mcpScope: [
+            { server: "ast-grep" },
+            { server: "chrome-devtools", tools: ["navigate"] },
+          ],
+        },
+      ],
+      ["planner", { mcpScope: [] }],
+      ["implementer", { mcpScope: [{ server: "filesystem" }] }],
+    ]);
+
+    const refs = collectScopeReferences(loadouts);
+    expect(refs).toEqual([
+      { loadout: "reviewer", server: "ast-grep" },
+      { loadout: "reviewer", server: "chrome-devtools" },
+      { loadout: "implementer", server: "filesystem" },
+    ]);
+  });
+
+  it("accepts plain-object loadouts", () => {
+    const refs = collectScopeReferences({
+      x: { mcpScope: [{ server: "a" }] },
+    });
+    expect(refs).toEqual([{ loadout: "x", server: "a" }]);
+  });
+
+  it("returns empty array for empty input", () => {
+    expect(collectScopeReferences()).toEqual([]);
+    expect(collectScopeReferences(new Map())).toEqual([]);
+  });
+});
+
+describe("discoverActiveSet", () => {
+  let tmpProject;
+  let tmpHome;
+  let tmpPlugin;
+
+  beforeEach(() => {
+    tmpProject = fs.mkdtempSync(path.join(os.tmpdir(), "swarm-proj-"));
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "swarm-home-"));
+    tmpPlugin = fs.mkdtempSync(path.join(os.tmpdir(), "swarm-plugin-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpProject, { recursive: true, force: true });
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+    fs.rmSync(tmpPlugin, { recursive: true, force: true });
+  });
+
+  function writeJson(p, obj) {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(obj));
+  }
+
+  it("returns empty map when no sources exist", () => {
+    const result = discoverActiveSet({
+      projectPath: tmpProject,
+      pluginPath: tmpPlugin,
+      userHome: tmpHome,
+    });
+    expect(result.size).toBe(0);
+  });
+
+  it("reads plugin.json mcpServers with source=plugin", () => {
+    writeJson(path.join(tmpPlugin, ".claude-plugin", "plugin.json"), {
+      mcpServers: { opentasks: { command: "node" } },
+    });
+
+    const result = discoverActiveSet({
+      projectPath: tmpProject,
+      pluginPath: tmpPlugin,
+      userHome: tmpHome,
+    });
+
+    expect(result.get("opentasks")).toEqual(
+      expect.objectContaining({ source: "plugin" })
+    );
+  });
+
+  it("reads project .mcp.json with source=project", () => {
+    writeJson(path.join(tmpProject, ".mcp.json"), {
+      mcpServers: { "ast-grep": { command: "npx" } },
+    });
+
+    const result = discoverActiveSet({
+      projectPath: tmpProject,
+      pluginPath: tmpPlugin,
+      userHome: tmpHome,
+    });
+
+    expect(result.get("ast-grep")).toEqual(
+      expect.objectContaining({ source: "project" })
+    );
+  });
+
+  it("reads ~/.claude/mcp.json with source=user", () => {
+    writeJson(path.join(tmpHome, ".claude", "mcp.json"), {
+      mcpServers: { "my-mcp": { command: "node" } },
+    });
+
+    const result = discoverActiveSet({
+      projectPath: tmpProject,
+      pluginPath: tmpPlugin,
+      userHome: tmpHome,
+    });
+
+    expect(result.get("my-mcp")).toEqual(
+      expect.objectContaining({ source: "user" })
+    );
+  });
+
+  it("project overrides user overrides plugin on name conflict", () => {
+    writeJson(path.join(tmpPlugin, ".claude-plugin", "plugin.json"), {
+      mcpServers: { fs: { command: "plugin-fs" } },
+    });
+    writeJson(path.join(tmpHome, ".claude", "mcp.json"), {
+      mcpServers: { fs: { command: "user-fs" } },
+    });
+    writeJson(path.join(tmpProject, ".mcp.json"), {
+      mcpServers: { fs: { command: "project-fs" } },
+    });
+
+    const result = discoverActiveSet({
+      projectPath: tmpProject,
+      pluginPath: tmpPlugin,
+      userHome: tmpHome,
+    });
+
+    expect(result.get("fs")).toEqual(
+      expect.objectContaining({
+        source: "project",
+        spec: { command: "project-fs" },
+      })
+    );
+  });
+
+  it("silently skips malformed JSON", () => {
+    const mcpPath = path.join(tmpProject, ".mcp.json");
+    fs.writeFileSync(mcpPath, "{not valid json]");
+
+    const result = discoverActiveSet({
+      projectPath: tmpProject,
+      pluginPath: tmpPlugin,
+      userHome: tmpHome,
+    });
+
+    expect(result.size).toBe(0);
+  });
+});
+
+describe("formatHealthReport", () => {
+  it("renders a header with the team name", () => {
+    const report = checkMcpHealth({
+      providers: new Map([["x", { command: "y" }]]),
+      activeSet: new Map(),
+    });
+    const out = formatHealthReport(report, { teamName: "demo" });
+    expect(out).toContain('Team "demo" MCP status');
+  });
+
+  it("marks ok entries with a checkmark and source", () => {
+    const report = checkMcpHealth({
+      providers: { "ast-grep": { command: "npx" } },
+      activeSet: new Map([["ast-grep", { source: "project" }]]),
+    });
+    const out = formatHealthReport(report);
+    expect(out).toContain("✓ ast-grep");
+    expect(out).toContain("(project)");
+  });
+
+  it("marks missing with warning and an actionable hint", () => {
+    const report = checkMcpHealth({
+      providers: { "chrome-devtools": { command: "npx" } },
+      activeSet: new Map(),
+    });
+    const out = formatHealthReport(report);
+    expect(out).toContain("⚠ chrome-devtools");
+    expect(out).toContain("/swarm mcp install chrome-devtools");
+  });
+
+  it("surfaces orphaned scope references in a dedicated section", () => {
+    const report = checkMcpHealth({
+      providers: new Map(),
+      activeSet: new Map(),
+      scopeReferences: [{ loadout: "x", server: "missing" }],
+    });
+    const out = formatHealthReport(report);
+    expect(out).toContain("not backed by any provider");
+    expect(out).toContain('loadout "x" uses "missing"');
+  });
+
+  it("falls back to a neutral message when nothing is declared", () => {
+    const report = checkMcpHealth({ providers: new Map(), activeSet: new Map() });
+    const out = formatHealthReport(report);
+    expect(out).toContain("no MCP providers declared");
+  });
+});

package/src/__tests__/scope-check.test.mjs

@@ -0,0 +1,210 @@
+/**
+ * Integration tests for the scope-check hook.
+ * Runs the hook as a subprocess, pipes stdin JSON, checks exit code + stderr.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const HOOK = path.resolve(
+  new URL("..", import.meta.url).pathname,
+  "..",
+  "scripts",
+  "scope-check.mjs"
+);
+
+function runHook({ toolName, scopeFile, roleName } = {}) {
+  const env = { ...process.env };
+  if (scopeFile) env.SCOPE_FILE = scopeFile;
+  if (roleName) env.ROLE_NAME = roleName;
+
+  const stdin = JSON.stringify({
+    tool_name: toolName,
+    tool_input: {},
+  });
+
+  const result = spawnSync("node", [HOOK], {
+    input: stdin,
+    env,
+    encoding: "utf-8",
+    timeout: 5000,
+  });
+  return {
+    exitCode: result.status,
+    stderr: result.stderr,
+    stdout: result.stdout,
+  };
+}
+
+describe("scope-check hook", () => {
+  let tmpDir;
+  let scopeFile;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "swarm-scope-"));
+    scopeFile = path.join(tmpDir, "scope.json");
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeScope(doc) {
+    fs.writeFileSync(scopeFile, JSON.stringify(doc));
+  }
+
+  // ─── Allow cases ───
+
+  it("allows non-MCP tool calls (defensive)", () => {
+    writeScope({ role: "r", scope: [] });
+    const { exitCode } = runHook({
+      toolName: "Read",
+      scopeFile,
+      roleName: "reviewer",
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("allows when no SCOPE_FILE is set", () => {
+    const { exitCode } = runHook({ toolName: "mcp__ast-grep__search" });
+    expect(exitCode).toBe(0);
+  });
+
+  it("allows when scope file is missing (fail-open)", () => {
+    const { exitCode, stderr } = runHook({
+      toolName: "mcp__ast-grep__search",
+      scopeFile: path.join(tmpDir, "does-not-exist.json"),
+    });
+    expect(exitCode).toBe(0);
+    expect(stderr).toContain("could not read scope file");
+  });
+
+  it("allows when the server is not in scope (Claude Code's allowlist gates elsewhere)", () => {
+    writeScope({
+      role: "r",
+      scope: [{ server: "opentasks" }],
+    });
+    const { exitCode } = runHook({
+      toolName: "mcp__chrome-devtools__navigate",
+      scopeFile,
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("allows a tool within an allowlist", () => {
+    writeScope({
+      role: "r",
+      scope: [{ server: "chrome-devtools", tools: ["navigate", "screenshot"] }],
+    });
+    const { exitCode } = runHook({
+      toolName: "mcp__chrome-devtools__navigate",
+      scopeFile,
+      roleName: "reviewer",
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("allows a tool when server is in scope with no restrictions", () => {
+    writeScope({
+      role: "r",
+      scope: [{ server: "ast-grep" }],
+    });
+    const { exitCode } = runHook({
+      toolName: "mcp__ast-grep__search",
+      scopeFile,
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  // ─── Deny cases ───
+
+  it("denies a tool outside the allowlist", () => {
+    writeScope({
+      role: "r",
+      scope: [{ server: "chrome-devtools", tools: ["navigate"] }],
+    });
+    const { exitCode, stderr } = runHook({
+      toolName: "mcp__chrome-devtools__evaluate_script",
+      scopeFile,
+      roleName: "reviewer",
+    });
+    expect(exitCode).toBe(2);
+    expect(stderr).toContain("not in the scope allowlist");
+    expect(stderr).toContain("reviewer");
+  });
+
+  it("denies a tool in an exclude list", () => {
+    writeScope({
+      role: "r",
+      scope: [{ server: "ast-grep", exclude: ["dangerous_replace"] }],
+    });
+    const { exitCode, stderr } = runHook({
+      toolName: "mcp__ast-grep__dangerous_replace",
+      scopeFile,
+      roleName: "reviewer",
+    });
+    expect(exitCode).toBe(2);
+    expect(stderr).toContain("scope exclude");
+  });
+
+  it("exclude is checked before allowlist", () => {
+    writeScope({
+      role: "r",
+      scope: [
+        {
+          server: "ast-grep",
+          tools: ["search", "dangerous_replace"], // mistakenly allows
+          exclude: ["dangerous_replace"], // but also excludes
+        },
+      ],
+    });
+    const { exitCode, stderr } = runHook({
+      toolName: "mcp__ast-grep__dangerous_replace",
+      scopeFile,
+      roleName: "reviewer",
+    });
+    expect(exitCode).toBe(2);
+    expect(stderr).toContain("exclude");
+  });
+
+  // ─── Edge cases ───
+
+  it("handles malformed stdin as allow (fail-open on protocol glitches)", () => {
+    writeScope({ role: "r", scope: [] });
+    const result = spawnSync("node", [HOOK], {
+      input: "{not json]",
+      env: { ...process.env, SCOPE_FILE: scopeFile },
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    expect(result.status).toBe(0);
+  });
+
+  it("handles tool names with multiple underscores correctly", () => {
+    // mcp__server__tool_with_underscores → server=server, tool=tool_with_underscores
+    writeScope({
+      role: "r",
+      scope: [{ server: "my-server", tools: ["tool_with_underscores"] }],
+    });
+    const { exitCode } = runHook({
+      toolName: "mcp__my-server__tool_with_underscores",
+      scopeFile,
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("derives role from scope file when ROLE_NAME env missing", () => {
+    writeScope({
+      role: "fallback-role",
+      scope: [{ server: "x", tools: ["a"] }],
+    });
+    const { stderr } = runHook({
+      toolName: "mcp__x__b",
+      scopeFile,
+      // no roleName
+    });
+    expect(stderr).toContain("fallback-role");
+  });
+});