@codemcp/ade-harnesses 0.2.0 → 0.2.3

package/src/util.ts

@@ -1,221 +0,0 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import type { GitHook, LogicalConfig, McpServerEntry } from "@codemcp/ade-core";
-
-// ---------------------------------------------------------------------------
-// JSON helpers
-// ---------------------------------------------------------------------------
-
-/** Read a JSON file, returning `{}` if missing or unparseable. */
-export async function readJsonOrEmpty(
-  path: string
-): Promise<Record<string, unknown>> {
-  try {
-    return JSON.parse(await readFile(path, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-
-/** Write a JSON object with trailing newline. Creates parent dirs. */
-export async function writeJson(path: string, data: unknown): Promise<void> {
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
-}
-
-// ---------------------------------------------------------------------------
-// Server entry transform — each harness overrides only what differs
-// ---------------------------------------------------------------------------
-
-/** Minimal MCP entry: command + args + optional env. */
-function baseEntry(server: McpServerEntry) {
-  return {
-    command: server.command,
-    args: server.args,
-    ...(Object.keys(server.env).length > 0 ? { env: server.env } : {})
-  };
-}
-
-export type ServerTransform = (
-  server: McpServerEntry
-) => Record<string, unknown>;
-
-/** Standard mcpServers entry (cursor, universal, claude-code). */
-export const standardEntry: ServerTransform = baseEntry;
-
-/** Adds `type: "stdio"` (copilot). */
-export const stdioEntry: ServerTransform = (s) => ({
-  type: "stdio",
-  ...baseEntry(s)
-});
-
-/** Adds `alwaysAllow` (cline, roo-code, windsurf). */
-export const alwaysAllowEntry: ServerTransform = (s) => ({
-  ...baseEntry(s),
-  alwaysAllow: s.allowedTools ?? ["*"]
-});
-
-// ---------------------------------------------------------------------------
-// MCP JSON writer — covers 7 of 9 harnesses
-// ---------------------------------------------------------------------------
-
-interface WriteMcpServersOpts {
-  /** Full path to the JSON file. */
-  path: string;
-  /** Key in the JSON that holds the server map. Default: `"mcpServers"`. */
-  key?: string;
-  /** Transform each McpServerEntry into the harness-specific shape. */
-  transform?: ServerTransform;
-  /** Extra top-level fields to merge (e.g. `$schema`). */
-  defaults?: Record<string, unknown>;
-}
-
-/**
- * Merge MCP server entries into an existing JSON config file.
- * Creates the file (and parent dirs) if missing.
- */
-export async function writeMcpServers(
-  servers: McpServerEntry[],
-  opts: WriteMcpServersOpts
-): Promise<void> {
-  if (servers.length === 0) return;
-
-  const key = opts.key ?? "mcpServers";
-  const transform = opts.transform ?? standardEntry;
-
-  const existing = await readJsonOrEmpty(opts.path);
-  const map = (existing[key] as Record<string, unknown>) ?? {};
-
-  for (const server of servers) {
-    map[server.ref] = transform(server);
-  }
-
-  const result = { ...(opts.defaults ?? {}), ...existing, [key]: map };
-  await writeJson(opts.path, result);
-}
-
-// ---------------------------------------------------------------------------
-// Instructions → flat rules file (windsurf, cline, roo-code)
-// ---------------------------------------------------------------------------
-
-/**
- * Write instructions as a plain text rules file.
- * Skips if no instructions.
- */
-export async function writeRulesFile(
-  instructions: string[],
-  path: string
-): Promise<void> {
-  if (instructions.length === 0) return;
-  const lines = instructions.flatMap((i) => [i, ""]);
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, lines.join("\n"), "utf-8");
-}
-
-// ---------------------------------------------------------------------------
-// Instructions → agent markdown with YAML frontmatter
-// ---------------------------------------------------------------------------
-
-interface AgentMdOpts {
-  /** Full path to the .md file. */
-  path: string;
-  /** Extra YAML frontmatter lines (after name/description, before `---`). */
-  extraFrontmatter?: string[];
-  /** Fallback body when instructions are empty. */
-  fallbackBody?: string;
-}
-
-/**
- * Write an agent markdown file with YAML frontmatter.
- * Shared by claude-code, copilot, and opencode.
- */
-export async function writeAgentMd(
-  config: LogicalConfig,
-  opts: AgentMdOpts
-): Promise<void> {
-  if (config.instructions.length === 0 && config.mcp_servers.length === 0)
-    return;
-
-  const fm: string[] = [
-    "---",
-    "name: ade",
-    "description: ADE — Agentic Development Environment agent with project conventions and tools"
-  ];
-
-  if (opts.extraFrontmatter) {
-    fm.push(...opts.extraFrontmatter);
-  }
-
-  fm.push("---");
-
-  const body =
-    config.instructions.length > 0
-      ? config.instructions.join("\n\n")
-      : (opts.fallbackBody ?? "");
-
-  const content = fm.join("\n") + "\n\n" + body + "\n";
-  await mkdir(dirname(opts.path), { recursive: true });
-  await writeFile(opts.path, content, "utf-8");
-}
-
-// ---------------------------------------------------------------------------
-// Inline skill SKILL.md writer (used by claude-code)
-// ---------------------------------------------------------------------------
-
-// ---------------------------------------------------------------------------
-// Git hook installer
-// ---------------------------------------------------------------------------
-
-/**
- * Write git hook scripts to `.git/hooks/<phase>`.
- * Files are created with executable permissions (0o755).
- * No-op when the hooks array is empty.
- */
-export async function writeGitHooks(
-  hooks: GitHook[] | undefined,
-  projectRoot: string
-): Promise<void> {
-  if (!hooks) return;
-  for (const hook of hooks) {
-    const hookPath = join(projectRoot, ".git", "hooks", hook.phase);
-    await writeFile(hookPath, hook.script, { mode: 0o755 });
-  }
-}
-
-export async function writeInlineSkills(
-  config: LogicalConfig,
-  projectRoot: string
-): Promise<string[]> {
-  const modified: string[] = [];
-
-  for (const skill of config.skills) {
-    if (!("body" in skill)) continue;
-
-    const skillDir = join(projectRoot, ".ade", "skills", skill.name);
-    const skillPath = join(skillDir, "SKILL.md");
-
-    const frontmatter = [
-      "---",
-      `name: ${skill.name}`,
-      `description: ${skill.description}`,
-      "---"
-    ].join("\n");
-
-    const expected = `${frontmatter}\n\n${skill.body}\n`;
-
-    try {
-      const existing = await readFile(skillPath, "utf-8");
-      if (existing !== expected) {
-        modified.push(skill.name);
-        continue;
-      }
-    } catch {
-      // File doesn't exist yet — fall through to write
-    }
-
-    await mkdir(skillDir, { recursive: true });
-    await writeFile(skillPath, expected, "utf-8");
-  }
-
-  return modified;
-}

package/src/writers/claude-code.spec.ts

@@ -1,320 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdtemp, rm, readFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type {
-  AutonomyProfile,
-  LogicalConfig,
-  PermissionPolicy
-} from "@codemcp/ade-core";
-import { claudeCodeWriter } from "./claude-code.js";
-import { writeInlineSkills } from "../util.js";
-
-function autonomyPolicy(profile: AutonomyProfile): PermissionPolicy {
-  switch (profile) {
-    case "rigid":
-      return {
-        profile,
-        capabilities: {
-          read: "ask",
-          edit_write: "ask",
-          search_list: "ask",
-          bash_safe: "ask",
-          bash_unsafe: "ask",
-          web: "ask",
-          task_agent: "ask"
-        }
-      };
-    case "sensible-defaults":
-      return {
-        profile,
-        capabilities: {
-          read: "allow",
-          edit_write: "allow",
-          search_list: "allow",
-          bash_safe: "allow",
-          bash_unsafe: "ask",
-          web: "ask",
-          task_agent: "allow"
-        }
-      };
-    case "max-autonomy":
-      return {
-        profile,
-        capabilities: {
-          read: "allow",
-          edit_write: "allow",
-          search_list: "allow",
-          bash_safe: "allow",
-          bash_unsafe: "allow",
-          web: "ask",
-          task_agent: "allow"
-        }
-      };
-  }
-}
-
-describe("claudeCodeWriter", () => {
-  let dir: string;
-
-  beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), "ade-harness-cc-"));
-  });
-
-  afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
-  });
-
-  it("has correct metadata", () => {
-    expect(claudeCodeWriter.id).toBe("claude-code");
-    expect(claudeCodeWriter.label).toBe("Claude Code");
-    expect(claudeCodeWriter.description).toBeTruthy();
-  });
-
-  it("writes .claude/agents/ade.md custom agent", async () => {
-    const config: LogicalConfig = {
-      mcp_servers: [
-        {
-          ref: "workflows",
-          command: "npx",
-          args: ["-y", "@codemcp/workflows"],
-          env: {}
-        }
-      ],
-      instructions: ["Use workflow files.", "Follow conventions."],
-      cli_actions: [],
-      knowledge_sources: [],
-      skills: [],
-      git_hooks: [],
-      setup_notes: []
-    };
-
-    await claudeCodeWriter.install(config, dir);
-
-    const content = await readFile(
-      join(dir, ".claude", "agents", "ade.md"),
-      "utf-8"
-    );
-    expect(content).toContain("name: ade");
-    expect(content).toContain("description:");
-    expect(content).toContain("Use workflow files.");
-    expect(content).toContain("Follow conventions.");
-  });
-
-  it("writes .mcp.json with MCP servers", async () => {
-    const config: LogicalConfig = {
-      mcp_servers: [
-        {
-          ref: "@codemcp/workflows",
-          command: "npx",
-          args: ["-y", "@codemcp/workflows"],
-          env: {}
-        }
-      ],
-      instructions: [],
-      cli_actions: [],
-      knowledge_sources: [],
-      skills: [],
-      git_hooks: [],
-      setup_notes: []
-    };
-
-    await claudeCodeWriter.install(config, dir);
-
-    const raw = await readFile(join(dir, ".mcp.json"), "utf-8");
-    const parsed = JSON.parse(raw);
-    expect(parsed.mcpServers["@codemcp/workflows"]).toEqual({
-      command: "npx",
-      args: ["-y", "@codemcp/workflows"]
-    });
-  });
-
-  it("forwards explicit MCP tool permissions using Claude rule names", async () => {
-    const config: LogicalConfig = {
-      mcp_servers: [
-        {
-          ref: "workflows",
-          command: "npx",
-          args: ["-y", "@codemcp/workflows"],
-          env: {},
-          allowedTools: ["use_skill", "whats_next"]
-        }
-      ],
-      instructions: [],
-      cli_actions: [],
-      knowledge_sources: [],
-      skills: [],
-      git_hooks: [],
-      setup_notes: []
-    };
-
-    await claudeCodeWriter.install(config, dir);
-
-    const raw = await readFile(join(dir, ".claude", "settings.json"), "utf-8");
-    const settings = JSON.parse(raw);
-    expect(settings.permissions.allow).toEqual(
-      expect.arrayContaining([
-        "mcp__workflows__use_skill",
-        "mcp__workflows__whats_next"
-      ])
-    );
-  });
-
-  it("does not invent wildcard MCP permission rules", async () => {
-    const config: LogicalConfig = {
-      mcp_servers: [
-        {
-          ref: "workflows",
-          command: "npx",
-          args: ["-y", "@codemcp/workflows"],
-          env: {}
-        }
-      ],
-      instructions: [],
-      cli_actions: [],
-      knowledge_sources: [],
-      skills: [],
-      git_hooks: [],
-      setup_notes: []
-    };
-
-    await claudeCodeWriter.install(config, dir);
-
-    const raw = await readFile(join(dir, ".claude", "settings.json"), "utf-8");
-    const settings = JSON.parse(raw);
-    expect(settings.permissions.allow ?? []).toEqual([]);
-  });
-
-  it("keeps web on ask for rigid autonomy without broad built-in allows", async () => {
-    const config: LogicalConfig = {
-      mcp_servers: [],
-      instructions: [],
-      cli_actions: [],
-      knowledge_sources: [],
-      skills: [],
-      git_hooks: [],
-      setup_notes: [],
-      permission_policy: autonomyPolicy("rigid")
-    };
-
-    await claudeCodeWriter.install(config, dir);
-
-    const raw = await readFile(join(dir, ".claude", "settings.json"), "utf-8");
-    const settings = JSON.parse(raw);
-    expect(settings.permissions.allow ?? []).toEqual([]);
-    expect(settings.permissions.ask).toEqual(
-      expect.arrayContaining(["WebFetch", "WebSearch"])
-    );
-  });
-
-  it("maps sensible-defaults to Claude built-in permission rules", async () => {
-    const config: LogicalConfig = {
-      mcp_servers: [],
-      instructions: [],
-      cli_actions: [],
-      knowledge_sources: [],
-      skills: [],
-      git_hooks: [],
-      setup_notes: [],
-      permission_policy: autonomyPolicy("sensible-defaults")
-    };
-
-    await claudeCodeWriter.install(config, dir);
-
-    const raw = await readFile(join(dir, ".claude", "settings.json"), "utf-8");
-    const settings = JSON.parse(raw);
-    expect(settings.permissions.allow).toEqual(
-      expect.arrayContaining(["Read", "Edit", "Glob", "Grep", "TodoWrite"])
-    );
-    expect(settings.permissions.allow).not.toContain("Bash");
-    expect(settings.permissions.ask).toEqual(
-      expect.arrayContaining(["WebFetch", "WebSearch"])
-    );
-  });
-
-  it("maps max-autonomy to broad Claude built-in permission rules while preserving web ask", async () => {
-    const config: LogicalConfig = {
-      mcp_servers: [],
-      instructions: [],
-      cli_actions: [],
-      knowledge_sources: [],
-      skills: [],
-      git_hooks: [],
-      setup_notes: [],
-      permission_policy: autonomyPolicy("max-autonomy")
-    };
-
-    await claudeCodeWriter.install(config, dir);
-
-    const raw = await readFile(join(dir, ".claude", "settings.json"), "utf-8");
-    const settings = JSON.parse(raw);
-    expect(settings.permissions.allow).toEqual(
-      expect.arrayContaining([
-        "Read",
-        "Edit",
-        "Bash",
-        "Glob",
-        "Grep",
-        "TodoWrite"
-      ])
-    );
-    expect(settings.permissions.ask).toEqual(
-      expect.arrayContaining(["WebFetch", "WebSearch"])
-    );
-  });
-
-  it("includes agentskills server from mcp_servers", async () => {
-    const config: LogicalConfig = {
-      mcp_servers: [
-        {
-          ref: "agentskills",
-          command: "npx",
-          args: ["-y", "@codemcp/skills-server"],
-          env: {}
-        }
-      ],
-      instructions: [],
-      cli_actions: [],
-      knowledge_sources: [],
-      skills: [{ name: "my-skill", description: "A skill", body: "Do stuff." }],
-      git_hooks: [],
-      setup_notes: []
-    };
-
-    await claudeCodeWriter.install(config, dir);
-
-    const raw = await readFile(join(dir, ".mcp.json"), "utf-8");
-    const parsed = JSON.parse(raw);
-    expect(parsed.mcpServers["agentskills"]).toEqual({
-      command: "npx",
-      args: ["-y", "@codemcp/skills-server"]
-    });
-  });
-
-  it("writes inline SKILL.md files via writeInlineSkills", async () => {
-    const config: LogicalConfig = {
-      mcp_servers: [],
-      instructions: [],
-      cli_actions: [],
-      knowledge_sources: [],
-      skills: [
-        {
-          name: "tanstack-architecture",
-          description: "TanStack architecture conventions",
-          body: "# Architecture\n\nUse file-based routing."
-        }
-      ],
-      git_hooks: [],
-      setup_notes: []
-    };
-
-    await writeInlineSkills(config, dir);
-
-    const skillMd = await readFile(
-      join(dir, ".ade", "skills", "tanstack-architecture", "SKILL.md"),
-      "utf-8"
-    );
-    expect(skillMd).toContain("name: tanstack-architecture");
-    expect(skillMd).toContain("# Architecture");
-  });
-});

package/src/writers/claude-code.ts

@@ -1,107 +0,0 @@
-import { join } from "node:path";
-import type { LogicalConfig } from "@codemcp/ade-core";
-import type { HarnessWriter } from "../types.js";
-import {
-  readJsonOrEmpty,
-  writeJson,
-  writeMcpServers,
-  writeAgentMd,
-  writeGitHooks
-} from "../util.js";
-import { allowsCapability, keepsWebOnAsk } from "../permission-policy.js";
-
-export const claudeCodeWriter: HarnessWriter = {
-  id: "claude-code",
-  label: "Claude Code",
-  description:
-    "Anthropic's CLI agent — .claude/agents/ade.md + .mcp.json + .claude/settings.json",
-  async install(config: LogicalConfig, projectRoot: string) {
-    await writeAgentMd(config, {
-      path: join(projectRoot, ".claude", "agents", "ade.md"),
-      fallbackBody: "ADE — Agentic Development Environment agent."
-    });
-
-    await writeMcpServers(config.mcp_servers, {
-      path: join(projectRoot, ".mcp.json")
-    });
-
-    await writeClaudeSettings(config, projectRoot);
-    await writeGitHooks(config.git_hooks, projectRoot);
-  }
-};
-
-async function writeClaudeSettings(
-  config: LogicalConfig,
-  projectRoot: string
-): Promise<void> {
-  const settingsPath = join(projectRoot, ".claude", "settings.json");
-  const existing = await readJsonOrEmpty(settingsPath);
-  const existingPerms = (existing.permissions as Record<string, unknown>) ?? {};
-  const existingAllow = asStringArray(existingPerms.allow);
-  const existingAsk = asStringArray(existingPerms.ask);
-
-  const autonomyRules = getClaudeAutonomyRules(config);
-  const mcpRules = getClaudeMcpAllowRules(config);
-  const allowRules = [
-    ...new Set([...existingAllow, ...autonomyRules.allow, ...mcpRules])
-  ];
-  const askRules = [...new Set([...existingAsk, ...autonomyRules.ask])];
-
-  if (
-    allowRules.length === 0 &&
-    askRules.length === 0 &&
-    config.mcp_servers.length === 0
-  ) {
-    return;
-  }
-
-  await writeJson(settingsPath, {
-    ...existing,
-    permissions: {
-      ...existingPerms,
-      ...(allowRules.length > 0 ? { allow: allowRules } : {}),
-      ...(askRules.length > 0 ? { ask: askRules } : {})
-    }
-  });
-}
-
-function asStringArray(value: unknown): string[] {
-  return Array.isArray(value)
-    ? value.filter((entry): entry is string => typeof entry === "string")
-    : [];
-}
-
-function getClaudeMcpAllowRules(config: LogicalConfig): string[] {
-  const allowRules: string[] = [];
-
-  for (const server of config.mcp_servers) {
-    const allowedTools = server.allowedTools;
-    if (!allowedTools || allowedTools.includes("*")) {
-      continue;
-    }
-
-    for (const tool of allowedTools) {
-      allowRules.push(`mcp__${server.ref}__${tool}`);
-    }
-  }
-
-  return allowRules;
-}
-
-function getClaudeAutonomyRules(config: LogicalConfig): {
-  allow: string[];
-  ask: string[];
-} {
-  const ask = keepsWebOnAsk(config) ? ["WebFetch", "WebSearch"] : [];
-
-  return {
-    allow: [
-      ...(allowsCapability(config, "read") ? ["Read"] : []),
-      ...(allowsCapability(config, "edit_write") ? ["Edit"] : []),
-      ...(allowsCapability(config, "search_list") ? ["Glob", "Grep"] : []),
-      ...(allowsCapability(config, "bash_unsafe") ? ["Bash"] : []),
-      ...(allowsCapability(config, "task_agent") ? ["TodoWrite"] : [])
-    ],
-    ask
-  };
-}