cue-ai 0.3.0

package/src/lib/mcp-materializer.test.ts

@@ -0,0 +1,358 @@
+/**
+ * Tests for the MCP materializer (Agent A9).
+ *
+ * Run with `bun test bin/cli/lib/mcp-materializer.test.ts`.
+ *
+ * Fixtures live entirely under `tmpdir()` so the suite does not depend on
+ * `mcps/configs/*.sanitized.json` evolving — the real registry can change
+ * shape without breaking these tests.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { ResolvedProfile } from "../../profiles/_types";
+import {
+  McpNotFound,
+  UnresolvedEnvPlaceholder,
+  materializeMcp,
+} from "./mcp-materializer";
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+let configsRoot: string;
+
+const CLAUDE_FIXTURE = {
+  server_key: "mcpServers",
+  servers: {
+    drawio: {
+      command: "npx",
+      args: ["-y", "@drawio/mcp"],
+      env: {},
+      type: "stdio",
+    },
+    gbrain: {
+      command: "~/.local/bin/gbrain-mcp-wrapper.sh",
+    },
+    recodee: {
+      command: "~/Documents/recodee/.venv/bin/recodee-mcp",
+      env: {
+        RECODEE_BASE_URL: "${RECODEE_BASE_URL}",
+      },
+    },
+    "higgsfield-http": {
+      type: "http",
+      url: "${HIGGSFIELD_URL}",
+    },
+  },
+  source: "claude",
+  source_path: "~/.claude/settings.json",
+};
+
+const CODEX_FIXTURE = {
+  server_key: "mcp_servers",
+  servers: {
+    colony: {
+      command: "~/.nvm/versions/node/v22.22.0/bin/colony",
+      args: ["mcp"],
+      enabled: true,
+      startup_timeout_sec: 60,
+      env: {
+        COLONY_HOME: "${COLONY_HOME}",
+      },
+    },
+    recodee: {
+      command: "~/Documents/recodee/.venv/bin/recodee-mcp",
+      env: {
+        RECODEE_BASE_URL: "${RECODEE_BASE_URL}",
+      },
+    },
+  },
+  source: "codex",
+  source_path: "~/.codex/config.toml",
+};
+
+async function writeFixtures(root: string): Promise<void> {
+  await writeFile(
+    join(root, "claude.sanitized.json"),
+    JSON.stringify(CLAUDE_FIXTURE, null, 2),
+    "utf8",
+  );
+  await writeFile(
+    join(root, "codex.sanitized.json"),
+    JSON.stringify(CODEX_FIXTURE, null, 2),
+    "utf8",
+  );
+}
+
+function makeProfile(
+  overrides: Partial<ResolvedProfile & { mcps: (string | { id: string })[] }> = {},
+): ResolvedProfile {
+  const { mcps: rawMcps, ...rest } = overrides;
+  // Normalize string mcps to { id } objects for the new ResolvedProfile shape.
+  const mcps = rawMcps
+    ? rawMcps.map((ref) => (typeof ref === "string" ? { id: ref } : ref))
+    : [];
+  return {
+    name: "test",
+    description: "fixture",
+    agents: ["claude-code", "codex"],
+    skills: { local: [], npx: [] },
+    mcps,
+    plugins: [],
+    env: {},
+    inheritanceChain: ["test"],
+    ...rest,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+
+beforeEach(async () => {
+  configsRoot = await mkdtemp(join(tmpdir(), "soul-mcp-mat-"));
+  await mkdir(configsRoot, { recursive: true });
+  await writeFixtures(configsRoot);
+});
+
+afterEach(async () => {
+  await rm(configsRoot, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("materializeMcp — filtering", () => {
+  test("returns only servers listed in profile.mcps for each agent", async () => {
+    const profile = makeProfile({
+      mcps: ["drawio", "colony"],
+      env: { COLONY_HOME: "/tmp/colony" },
+    });
+
+    const out = await materializeMcp(profile, { configsRoot, processEnv: {} });
+
+    // claude registry has drawio (and no colony), codex registry has colony
+    // (and no drawio). Each side filters to what it knows.
+    expect(out.claude).toEqual({
+      mcpServers: {
+        drawio: {
+          command: "npx",
+          args: ["-y", "@drawio/mcp"],
+          env: {},
+          type: "stdio",
+        },
+      },
+    });
+    expect(out.codex).toEqual({
+      mcp_servers: {
+        colony: {
+          command: "~/.nvm/versions/node/v22.22.0/bin/colony",
+          args: ["mcp"],
+          enabled: true,
+          startup_timeout_sec: 60,
+          env: { COLONY_HOME: "/tmp/colony" },
+        },
+      },
+    });
+  });
+
+  test("emits empty server blocks when profile.mcps is empty", async () => {
+    const profile = makeProfile({ mcps: [] });
+    const out = await materializeMcp(profile, { configsRoot, processEnv: {} });
+    expect(out.claude).toEqual({ mcpServers: {} });
+    expect(out.codex).toEqual({ mcp_servers: {} });
+  });
+
+  test("emits a server on BOTH sides when it appears in both registries", async () => {
+    const profile = makeProfile({
+      mcps: ["recodee"],
+      env: { RECODEE_BASE_URL: "https://recodee.example" },
+    });
+    const out = await materializeMcp(profile, { configsRoot, processEnv: {} });
+    expect((out.claude as { mcpServers: Record<string, unknown> }).mcpServers)
+      .toHaveProperty("recodee");
+    expect((out.codex as { mcp_servers: Record<string, unknown> }).mcp_servers)
+      .toHaveProperty("recodee");
+  });
+});
+
+describe("materializeMcp — McpNotFound", () => {
+  test("throws when profile references an id missing from BOTH registries", async () => {
+    const profile = makeProfile({ mcps: ["does-not-exist"] });
+    try {
+      await materializeMcp(profile, { configsRoot, processEnv: {} });
+      throw new Error("expected materializeMcp to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(McpNotFound);
+      expect((err as McpNotFound).id).toBe("does-not-exist");
+      // Surface the known ids so the user can correct their profile.
+      expect((err as McpNotFound).known).toContain("drawio");
+      expect((err as McpNotFound).known).toContain("colony");
+    }
+  });
+
+  test("does NOT throw when an id is only in one registry — that's normal", async () => {
+    const profile = makeProfile({ mcps: ["drawio"] });
+    const out = await materializeMcp(profile, { configsRoot, processEnv: {} });
+    expect((out.claude as { mcpServers: Record<string, unknown> }).mcpServers)
+      .toHaveProperty("drawio");
+    expect((out.codex as { mcp_servers: Record<string, unknown> }).mcp_servers)
+      .toEqual({});
+  });
+});
+
+describe("materializeMcp — env substitution", () => {
+  test("substitutes from profile.env first", async () => {
+    const profile = makeProfile({
+      mcps: ["recodee"],
+      env: { RECODEE_BASE_URL: "https://from-profile" },
+    });
+    const out = await materializeMcp(profile, {
+      configsRoot,
+      processEnv: { RECODEE_BASE_URL: "https://from-process" },
+    });
+    const claudeRecodee = (out.claude as {
+      mcpServers: { recodee: { env: { RECODEE_BASE_URL: string } } };
+    }).mcpServers.recodee;
+    expect(claudeRecodee.env.RECODEE_BASE_URL).toBe("https://from-profile");
+  });
+
+  test("falls back to process.env when profile.env is silent", async () => {
+    const profile = makeProfile({ mcps: ["recodee"] });
+    const out = await materializeMcp(profile, {
+      configsRoot,
+      processEnv: { RECODEE_BASE_URL: "https://from-process" },
+    });
+    const claudeRecodee = (out.claude as {
+      mcpServers: { recodee: { env: { RECODEE_BASE_URL: string } } };
+    }).mcpServers.recodee;
+    expect(claudeRecodee.env.RECODEE_BASE_URL).toBe("https://from-process");
+  });
+
+  test("substitutes inside string values at any depth (url, args, env)", async () => {
+    const profile = makeProfile({
+      mcps: ["higgsfield-http", "colony"],
+      env: {
+        HIGGSFIELD_URL: "https://hf.example/mcp",
+        COLONY_HOME: "/tmp/colony",
+      },
+    });
+    const out = await materializeMcp(profile, { configsRoot, processEnv: {} });
+    expect(
+      (out.claude as {
+        mcpServers: { "higgsfield-http": { url: string } };
+      }).mcpServers["higgsfield-http"].url,
+    ).toBe("https://hf.example/mcp");
+    expect(
+      (out.codex as {
+        mcp_servers: { colony: { env: { COLONY_HOME: string } } };
+      }).mcp_servers.colony.env.COLONY_HOME,
+    ).toBe("/tmp/colony");
+  });
+
+  test("throws UnresolvedEnvPlaceholder when no source defines the var", async () => {
+    const profile = makeProfile({ mcps: ["recodee"] });
+    try {
+      await materializeMcp(profile, { configsRoot, processEnv: {} });
+      throw new Error("expected materializeMcp to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(UnresolvedEnvPlaceholder);
+      expect((err as UnresolvedEnvPlaceholder).varName).toBe(
+        "RECODEE_BASE_URL",
+      );
+      expect((err as UnresolvedEnvPlaceholder).serverId).toBe("recodee");
+      expect((err as UnresolvedEnvPlaceholder).source).toBe("claude");
+    }
+  });
+
+  test("UnresolvedEnvPlaceholder fires for codex-only servers too", async () => {
+    const profile = makeProfile({ mcps: ["colony"] });
+    try {
+      await materializeMcp(profile, { configsRoot, processEnv: {} });
+      throw new Error("expected materializeMcp to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(UnresolvedEnvPlaceholder);
+      expect((err as UnresolvedEnvPlaceholder).varName).toBe("COLONY_HOME");
+      expect((err as UnresolvedEnvPlaceholder).source).toBe("codex");
+    }
+  });
+
+  test("never leaves a literal ${...} in the emitted config", async () => {
+    const profile = makeProfile({
+      mcps: ["recodee"],
+      env: { RECODEE_BASE_URL: "https://ok" },
+    });
+    const out = await materializeMcp(profile, { configsRoot, processEnv: {} });
+    const serialized = JSON.stringify(out);
+    expect(serialized).not.toMatch(/\$\{[A-Za-z_]/);
+  });
+});
+
+describe("materializeMcp — round-trip / determinism", () => {
+  test("two consecutive runs produce identical JSON output", async () => {
+    const profile = makeProfile({
+      mcps: ["drawio", "colony", "recodee"],
+      env: {
+        RECODEE_BASE_URL: "https://r.example",
+        COLONY_HOME: "/tmp/colony",
+      },
+    });
+    const a = await materializeMcp(profile, { configsRoot, processEnv: {} });
+    const b = await materializeMcp(profile, { configsRoot, processEnv: {} });
+    expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+  });
+
+  test("server order in output follows profile.mcps order", async () => {
+    const profile = makeProfile({
+      mcps: ["recodee", "drawio"],
+      env: { RECODEE_BASE_URL: "https://r.example" },
+    });
+    const out = await materializeMcp(profile, { configsRoot, processEnv: {} });
+    expect(
+      Object.keys(
+        (out.claude as { mcpServers: Record<string, unknown> }).mcpServers,
+      ),
+    ).toEqual(["recodee", "drawio"]);
+  });
+
+  test("duplicate ids in profile.mcps collapse to a single entry", async () => {
+    const profile = makeProfile({ mcps: ["drawio", "drawio"] });
+    const out = await materializeMcp(profile, { configsRoot, processEnv: {} });
+    expect(
+      Object.keys(
+        (out.claude as { mcpServers: Record<string, unknown> }).mcpServers,
+      ),
+    ).toEqual(["drawio"]);
+  });
+});
+
+describe("materializeMcp — configs root discovery", () => {
+  test("honors the SOUL_MCPS_ROOT env var when no explicit option is given", async () => {
+    const profile = makeProfile({ mcps: ["drawio"] });
+    const out = await materializeMcp(profile, {
+      // Don't pass configsRoot — force the env-var path.
+      processEnv: { SOUL_MCPS_ROOT: configsRoot },
+    });
+    expect(
+      (out.claude as { mcpServers: Record<string, unknown> }).mcpServers,
+    ).toHaveProperty("drawio");
+  });
+
+  test("explicit configsRoot wins over SOUL_MCPS_ROOT", async () => {
+    const profile = makeProfile({ mcps: ["drawio"] });
+    // SOUL_MCPS_ROOT points somewhere bogus; configsRoot is the real one.
+    const out = await materializeMcp(profile, {
+      configsRoot,
+      processEnv: { SOUL_MCPS_ROOT: "/nonexistent/path" },
+    });
+    expect(
+      (out.claude as { mcpServers: Record<string, unknown> }).mcpServers,
+    ).toHaveProperty("drawio");
+  });
+});

package/src/lib/mcp-materializer.ts

@@ -0,0 +1,317 @@
+/**
+ * MCP materializer (Agent A9).
+ *
+ * Given a `ResolvedProfile`, emit the per-agent MCP config blocks that the
+ * profile would drop into `~/.claude.json` and `~/.codex/config.toml`-style
+ * files. A14 writes the result to disk; this module is read-only by contract.
+ *
+ * Inputs
+ *   - The sanitized master registry at `mcps/configs/{claude,codex}.sanitized.json`.
+ *     Each file has the shape `{ server_key: string, servers: Record<id, value>, ... }`.
+ *     The `server_key` is the idiomatic top-level key for that agent
+ *     (e.g. `mcpServers` for Claude, `mcp_servers` for Codex).
+ *   - `profile.mcps`  — the list of server ids to include.
+ *   - `profile.env`   — declared environment overrides for placeholder substitution.
+ *
+ * Output
+ *   `{ claude: { <server_key>: {<id>: {...}} },
+ *      codex:  { <server_key>: {<id>: {...}} } }`
+ *
+ * Substitution rules
+ *   Any string value within a server config that contains `${VAR_NAME}` is
+ *   substituted. Lookup order is:
+ *     1. `profile.env[VAR_NAME]`
+ *     2. `process.env[VAR_NAME]`
+ *   If neither defines the var, throw `UnresolvedEnvPlaceholder`. We never
+ *   silently leave a `${...}` literal in the emitted config.
+ *
+ * Error semantics
+ *   - `McpNotFound`               — profile references an id missing from *both* registries.
+ *   - `UnresolvedEnvPlaceholder`  — a `${VAR}` placeholder couldn't be resolved.
+ */
+
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ProfileError, type ResolvedProfile } from "../../profiles/_types";
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class McpNotFound extends ProfileError {
+  constructor(
+    public id: string,
+    public known: string[],
+  ) {
+    super(
+      "MCP_NOT_FOUND",
+      `MCP server "${id}" not found in sanitized registry. ` +
+        `Known: ${known.length > 0 ? known.join(", ") : "<empty>"}`,
+    );
+  }
+}
+
+export class UnresolvedEnvPlaceholder extends ProfileError {
+  constructor(
+    public varName: string,
+    public serverId: string,
+    public source: "claude" | "codex",
+  ) {
+    super(
+      "UNRESOLVED_ENV_PLACEHOLDER",
+      `Unresolved env placeholder "\${${varName}}" in ${source} server ` +
+        `"${serverId}". Declare it in profile.env or export it in the shell.`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Constants & options
+// ---------------------------------------------------------------------------
+
+/** Resolve repo root by walking up from this file: src/lib -> repo root. */
+const REPO_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+const DEFAULT_CONFIGS_ROOT = join(REPO_ROOT, "resources", "mcps", "configs");
+
+export interface MaterializeOptions {
+  /**
+   * Root directory holding `claude.sanitized.json` and `codex.sanitized.json`.
+   * Defaults to env var `SOUL_MCPS_ROOT`, then to `<repo>/mcps/configs`.
+   */
+  configsRoot?: string;
+  /**
+   * Override the `process.env` lookup table (for tests). When omitted the real
+   * `process.env` is consulted.
+   */
+  processEnv?: Record<string, string | undefined>;
+}
+
+export interface MaterializedMcp {
+  claude: Record<string, unknown>;
+  codex: Record<string, unknown>;
+}
+
+/** Shape of each sanitized config file on disk. */
+interface SanitizedConfig {
+  server_key: string;
+  servers: Record<string, unknown>;
+  source?: string;
+  source_path?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Sanitized config loader
+// ---------------------------------------------------------------------------
+
+function resolveConfigsRoot(opts?: MaterializeOptions): string {
+  if (opts?.configsRoot) return opts.configsRoot;
+  const fromEnv = (opts?.processEnv ?? process.env).SOUL_MCPS_ROOT;
+  if (fromEnv && fromEnv.length > 0) return fromEnv;
+  return DEFAULT_CONFIGS_ROOT;
+}
+
+async function readSanitized(
+  root: string,
+  agent: "claude" | "codex",
+): Promise<SanitizedConfig> {
+  const path = join(root, `${agent}.sanitized.json`);
+  const text = await readFile(path, "utf8");
+  const parsed = JSON.parse(text) as unknown;
+  if (
+    parsed === null ||
+    typeof parsed !== "object" ||
+    Array.isArray(parsed)
+  ) {
+    throw new ProfileError(
+      "INVALID_SANITIZED_CONFIG",
+      `${agent}.sanitized.json must be a JSON object`,
+    );
+  }
+  const obj = parsed as Record<string, unknown>;
+  const serverKey = obj.server_key;
+  const servers = obj.servers;
+  if (typeof serverKey !== "string" || serverKey.length === 0) {
+    throw new ProfileError(
+      "INVALID_SANITIZED_CONFIG",
+      `${agent}.sanitized.json missing string "server_key"`,
+    );
+  }
+  if (
+    servers === null ||
+    typeof servers !== "object" ||
+    Array.isArray(servers)
+  ) {
+    throw new ProfileError(
+      "INVALID_SANITIZED_CONFIG",
+      `${agent}.sanitized.json "servers" must be an object`,
+    );
+  }
+  return {
+    server_key: serverKey,
+    servers: servers as Record<string, unknown>,
+    source: typeof obj.source === "string" ? obj.source : undefined,
+    source_path:
+      typeof obj.source_path === "string" ? obj.source_path : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Env-placeholder substitution
+// ---------------------------------------------------------------------------
+
+/**
+ * Matches `${VAR_NAME}` where VAR_NAME is `[A-Za-z_][A-Za-z0-9_]*`. We are
+ * intentionally strict: a placeholder that doesn't fit shell-style identifier
+ * rules is treated as literal text (no substitution attempted, no error).
+ */
+const PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+function substituteString(
+  value: string,
+  serverId: string,
+  source: "claude" | "codex",
+  profileEnv: Record<string, string>,
+  processEnv: Record<string, string | undefined>,
+): string {
+  // Replace each placeholder; collect first unresolved name so we throw with
+  // useful context rather than silently leaving `${X}` in output.
+  let unresolved: string | null = null;
+  const out = value.replace(PLACEHOLDER_RE, (_match, name: string) => {
+    if (Object.prototype.hasOwnProperty.call(profileEnv, name)) {
+      return profileEnv[name]!;
+    }
+    const fromProc = processEnv[name];
+    if (fromProc !== undefined) {
+      return fromProc;
+    }
+    if (unresolved === null) unresolved = name;
+    return _match;
+  });
+  if (unresolved !== null) {
+    throw new UnresolvedEnvPlaceholder(unresolved, serverId, source);
+  }
+  return out;
+}
+
+/**
+ * Walk an arbitrary JSON-shaped value, returning a structurally identical copy
+ * with every string passed through {@link substituteString}. Order of object
+ * keys is preserved (matters for deterministic round-tripping).
+ */
+function substituteDeep(
+  value: unknown,
+  serverId: string,
+  source: "claude" | "codex",
+  profileEnv: Record<string, string>,
+  processEnv: Record<string, string | undefined>,
+): unknown {
+  if (typeof value === "string") {
+    return substituteString(value, serverId, source, profileEnv, processEnv);
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) =>
+      substituteDeep(v, serverId, source, profileEnv, processEnv),
+    );
+  }
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = substituteDeep(v, serverId, source, profileEnv, processEnv);
+    }
+    return out;
+  }
+  // numbers, booleans, null — pass through untouched.
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// Per-agent filter
+// ---------------------------------------------------------------------------
+
+function filterAgentConfig(
+  sanitized: SanitizedConfig,
+  source: "claude" | "codex",
+  wanted: string[],
+  profileEnv: Record<string, string>,
+  processEnv: Record<string, string | undefined>,
+): Record<string, unknown> {
+  const filtered: Record<string, unknown> = {};
+  // Preserve the order in which profile.mcps lists the ids; this makes the
+  // output deterministic and easy to diff. Duplicate ids in the input list
+  // are collapsed by virtue of object-key uniqueness.
+  for (const id of wanted) {
+    if (!Object.prototype.hasOwnProperty.call(sanitized.servers, id)) {
+      // Caller (materializeMcp) already verified existence across BOTH
+      // registries, so a miss here is an expected branch — that means this
+      // id only exists in the other agent's registry. Skip silently.
+      continue;
+    }
+    const raw = sanitized.servers[id];
+    filtered[id] = substituteDeep(raw, id, source, profileEnv, processEnv);
+  }
+  return { [sanitized.server_key]: filtered };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the per-agent MCP config blocks for a resolved profile.
+ *
+ * @throws McpNotFound              if `profile.mcps` references an id missing from BOTH sanitized registries.
+ * @throws UnresolvedEnvPlaceholder if a `${VAR}` placeholder can't be resolved from profile.env or process.env.
+ * @throws ProfileError             on malformed sanitized config files.
+ */
+export async function materializeMcp(
+  profile: ResolvedProfile,
+  opts?: MaterializeOptions,
+): Promise<MaterializedMcp> {
+  const root = resolveConfigsRoot(opts);
+  const [claudeCfg, codexCfg] = await Promise.all([
+    readSanitized(root, "claude"),
+    readSanitized(root, "codex"),
+  ]);
+
+  // An MCP id is "known" if it exists in at least one registry. A truly
+  // unknown id is a configuration error and aborts the materialization.
+  const knownUnion = new Set<string>([
+    ...Object.keys(claudeCfg.servers),
+    ...Object.keys(codexCfg.servers),
+  ]);
+
+  // Extract string ids from the resolved MCPs ({ id, agents? } objects).
+  const mcpIds = profile.mcps.map((ref) => ref.id);
+
+  for (const id of mcpIds) {
+    if (!knownUnion.has(id)) {
+      throw new McpNotFound(id, [...knownUnion].sort());
+    }
+  }
+
+  const procEnv = opts?.processEnv ?? process.env;
+
+  return {
+    claude: filterAgentConfig(
+      claudeCfg,
+      "claude",
+      mcpIds,
+      profile.env,
+      procEnv,
+    ),
+    codex: filterAgentConfig(
+      codexCfg,
+      "codex",
+      mcpIds,
+      profile.env,
+      procEnv,
+    ),
+  };
+}