@codemcp/ade-harnesses 0.0.2 → 0.1.0

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

@@ -2,9 +2,57 @@ 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 { LogicalConfig } from "@codemcp/ade-core";
+import type {
+  AutonomyProfile,
+  LogicalConfig,
+  PermissionPolicy
+} from "@codemcp/ade-core";
 import { rooCodeWriter } from "./roo-code.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("rooCodeWriter", () => {
   let dir: string;
 
@@ -19,6 +67,7 @@ describe("rooCodeWriter", () => {
   it("has correct metadata", () => {
     expect(rooCodeWriter.id).toBe("roo-code");
     expect(rooCodeWriter.label).toBe("Roo Code");
+    expect(rooCodeWriter.description).toContain(".roomodes");
   });
 
   it("writes .roo/mcp.json with MCP servers", async () => {
@@ -66,4 +115,83 @@ describe("rooCodeWriter", () => {
     const content = await readFile(join(dir, ".roorules"), "utf-8");
     expect(content).toContain("Follow TDD.");
   });
+
+  it("maps autonomy to Roo mode groups conservatively while forwarding MCP approvals separately", async () => {
+    const rigidRoot = join(dir, "rigid");
+    const defaultsRoot = join(dir, "defaults");
+    const maxRoot = join(dir, "max");
+
+    const baseConfig = {
+      mcp_servers: [
+        {
+          ref: "workflows",
+          command: "npx",
+          args: ["-y", "@codemcp/workflows"],
+          env: {},
+          allowedTools: ["whats_next"]
+        }
+      ],
+      instructions: [],
+      cli_actions: [],
+      knowledge_sources: [],
+      skills: [],
+      git_hooks: [],
+      setup_notes: []
+    } satisfies LogicalConfig;
+
+    await rooCodeWriter.install(
+      {
+        ...baseConfig,
+        permission_policy: autonomyPolicy("rigid")
+      },
+      rigidRoot
+    );
+    await rooCodeWriter.install(
+      {
+        ...baseConfig,
+        permission_policy: autonomyPolicy("sensible-defaults")
+      },
+      defaultsRoot
+    );
+    await rooCodeWriter.install(
+      {
+        ...baseConfig,
+        permission_policy: autonomyPolicy("max-autonomy")
+      },
+      maxRoot
+    );
+
+    const rigidModes = JSON.parse(
+      await readFile(join(rigidRoot, ".roomodes"), "utf-8")
+    );
+    const defaultsModes = JSON.parse(
+      await readFile(join(defaultsRoot, ".roomodes"), "utf-8")
+    );
+    const maxModes = JSON.parse(
+      await readFile(join(maxRoot, ".roomodes"), "utf-8")
+    );
+    const rigidMcp = JSON.parse(
+      await readFile(join(rigidRoot, ".roo", "mcp.json"), "utf-8")
+    );
+
+    expect(rigidModes.customModes.ade.groups).toEqual(["mcp"]);
+    expect(defaultsModes.customModes.ade.groups).toEqual([
+      "read",
+      "edit",
+      "mcp"
+    ]);
+    expect(maxModes.customModes.ade.groups).toEqual([
+      "read",
+      "edit",
+      "command",
+      "mcp"
+    ]);
+
+    expect(defaultsModes.customModes.ade.groups).not.toContain("command");
+    expect(rigidModes.customModes.ade.groups).not.toContain("web");
+    expect(defaultsModes.customModes.ade.groups).not.toContain("web");
+    expect(maxModes.customModes.ade.groups).not.toContain("web");
+
+    expect(rigidMcp.mcpServers.workflows.alwaysAllow).toEqual(["whats_next"]);
+  });
 });

package/src/writers/roo-code.ts

@@ -2,23 +2,70 @@ import { join } from "node:path";
 import type { LogicalConfig } from "@codemcp/ade-core";
 import type { HarnessWriter } from "../types.js";
 import {
+  readJsonOrEmpty,
   writeMcpServers,
   alwaysAllowEntry,
   writeRulesFile,
-  writeGitHooks
+  writeGitHooks,
+  writeJson
 } from "../util.js";
+import { allowsCapability, hasPermissionPolicy } from "../permission-policy.js";
 
 export const rooCodeWriter: HarnessWriter = {
   id: "roo-code",
   label: "Roo Code",
-  description: "AI coding agent — .roo/mcp.json + .roorules",
+  description: "AI coding agent — .roo/mcp.json + .roomodes + .roorules",
   async install(config: LogicalConfig, projectRoot: string) {
     await writeMcpServers(config.mcp_servers, {
       path: join(projectRoot, ".roo", "mcp.json"),
       transform: alwaysAllowEntry
     });
 
+    await writeRooModes(config, projectRoot);
     await writeRulesFile(config.instructions, join(projectRoot, ".roorules"));
     await writeGitHooks(config.git_hooks, projectRoot);
   }
 };
+
+async function writeRooModes(
+  config: LogicalConfig,
+  projectRoot: string
+): Promise<void> {
+  if (!hasPermissionPolicy(config)) {
+    return;
+  }
+
+  const roomodesPath = join(projectRoot, ".roomodes");
+  const existing = await readJsonOrEmpty(roomodesPath);
+  const existingCustomModes = asRecord(existing.customModes);
+
+  await writeJson(roomodesPath, {
+    ...existing,
+    customModes: {
+      ...existingCustomModes,
+      ade: {
+        slug: "ade",
+        name: "ADE",
+        roleDefinition:
+          "ADE — Agentic Development Environment mode generated by ADE.",
+        groups: getRooModeGroups(config),
+        source: "project"
+      }
+    }
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function getRooModeGroups(config: LogicalConfig): string[] {
+  return [
+    ...(allowsCapability(config, "read") ? ["read"] : []),
+    ...(allowsCapability(config, "edit_write") ? ["edit"] : []),
+    ...(allowsCapability(config, "bash_unsafe") ? ["command"] : []),
+    ...(config.mcp_servers.length > 0 ? ["mcp"] : [])
+  ];
+}

package/src/writers/universal.spec.ts

@@ -0,0 +1,134 @@
+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 { universalWriter } from "./universal.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("universalWriter", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "ade-harness-universal-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("has correct metadata", () => {
+    expect(universalWriter.id).toBe("universal");
+    expect(universalWriter.label).toBe("Universal (AGENTS.md + .mcp.json)");
+    expect(universalWriter.description).toContain("AGENTS.md");
+  });
+
+  it("writes AGENTS.md instructions when provided", async () => {
+    const config: LogicalConfig = {
+      mcp_servers: [],
+      instructions: ["Follow the workflow.", "Keep changes focused."],
+      cli_actions: [],
+      knowledge_sources: [],
+      skills: [],
+      git_hooks: [],
+      setup_notes: []
+    };
+
+    await universalWriter.install(config, dir);
+
+    const content = await readFile(join(dir, "AGENTS.md"), "utf-8");
+    expect(content).toContain("# AGENTS");
+    expect(content).toContain("Follow the workflow.");
+    expect(content).toContain("Keep changes focused.");
+  });
+
+  it("documents autonomy as guidance only because Universal has no enforceable permission schema", async () => {
+    const config: LogicalConfig = {
+      mcp_servers: [
+        {
+          ref: "workflows",
+          command: "npx",
+          args: ["-y", "@codemcp/workflows"],
+          env: {},
+          allowedTools: ["whats_next"]
+        }
+      ],
+      instructions: [],
+      cli_actions: [],
+      knowledge_sources: [],
+      skills: [],
+      git_hooks: [],
+      setup_notes: [],
+      permission_policy: autonomyPolicy("sensible-defaults")
+    };
+
+    await universalWriter.install(config, dir);
+
+    const agents = await readFile(join(dir, "AGENTS.md"), "utf-8");
+    expect(agents).toContain("## Autonomy");
+    expect(agents).toContain("documentation-only guidance");
+    expect(agents).toContain("no enforceable harness-level permission schema");
+    expect(agents).toContain("Profile: `sensible-defaults`");
+    expect(agents).toContain("- `read`: allow");
+    expect(agents).toContain("- `bash_unsafe`: ask");
+    expect(agents).toContain("- `web`: ask");
+    expect(agents).toContain(
+      "MCP permissions are not re-modeled by autonomy here"
+    );
+
+    const mcpRaw = await readFile(join(dir, ".mcp.json"), "utf-8");
+    const mcp = JSON.parse(mcpRaw);
+    expect(mcp.mcpServers.workflows).toEqual({
+      command: "npx",
+      args: ["-y", "@codemcp/workflows"]
+    });
+    expect(mcp.mcpServers.workflows).not.toHaveProperty("allowedTools");
+  });
+});

package/src/writers/universal.ts

@@ -1,20 +1,73 @@
 import { join } from "node:path";
 import { writeFile } from "node:fs/promises";
-import type { LogicalConfig } from "@codemcp/ade-core";
+import type {
+  AutonomyCapability,
+  LogicalConfig,
+  PermissionDecision
+} from "@codemcp/ade-core";
 import type { HarnessWriter } from "../types.js";
 import { writeMcpServers, writeGitHooks } from "../util.js";
 
+const CAPABILITY_ORDER: AutonomyCapability[] = [
+  "read",
+  "edit_write",
+  "search_list",
+  "bash_safe",
+  "bash_unsafe",
+  "web",
+  "task_agent"
+];
+
+function formatCapabilityGuidance(
+  capability: AutonomyCapability,
+  decision: PermissionDecision
+): string {
+  return `- \`${capability}\`: ${decision}`;
+}
+
+function renderAutonomyGuidance(config: LogicalConfig): string | undefined {
+  const policy = config.permission_policy;
+  if (!policy) {
+    return undefined;
+  }
+
+  const capabilityLines = CAPABILITY_ORDER.map((capability) =>
+    formatCapabilityGuidance(capability, policy.capabilities[capability])
+  );
+
+  return [
+    "## Autonomy",
+    "",
+    "Universal harness limitation: `AGENTS.md` + `.mcp.json` provide documentation and server registration only; there is no enforceable harness-level permission schema here.",
+    "",
+    "Treat this autonomy profile as documentation-only guidance for built-in/basic operations.",
+    "",
+    `Profile: \`${policy.profile}\``,
+    "",
+    "Built-in/basic capability guidance:",
+    ...capabilityLines,
+    "",
+    "MCP permissions are not re-modeled by autonomy here; any MCP approvals must come from provisioning-aware consuming harnesses rather than the Universal writer."
+  ].join("\n");
+}
+
 export const universalWriter: HarnessWriter = {
   id: "universal",
   label: "Universal (AGENTS.md + .mcp.json)",
   description:
-    "Cross-tool standard — AGENTS.md + .mcp.json (works with any agent)",
+    "Cross-tool standard — AGENTS.md + .mcp.json (portable instructions and MCP registration, not enforceable permissions)",
   async install(config: LogicalConfig, projectRoot: string) {
-    if (config.instructions.length > 0) {
+    const autonomyGuidance = renderAutonomyGuidance(config);
+    const instructionSections = [...config.instructions];
+    if (autonomyGuidance) {
+      instructionSections.push(autonomyGuidance);
+    }
+
+    if (instructionSections.length > 0) {
       const lines = [
         "# AGENTS",
         "",
-        ...config.instructions.flatMap((i) => [i, ""])
+        ...instructionSections.flatMap((instruction) => [instruction, ""])
       ];
       await writeFile(
         join(projectRoot, "AGENTS.md"),

package/src/writers/windsurf.spec.ts

@@ -21,14 +21,15 @@ describe("windsurfWriter", () => {
     expect(windsurfWriter.label).toBe("Windsurf");
   });
 
-  it("writes .windsurf/mcp.json with MCP servers", async () => {
+  it("writes .windsurf/mcp.json with forwarded MCP approvals", async () => {
     const config: LogicalConfig = {
       mcp_servers: [
         {
           ref: "workflows",
           command: "npx",
           args: ["-y", "@codemcp/workflows"],
-          env: { API_KEY: "test" }
+          env: { API_KEY: "test" },
+          allowedTools: ["whats_next", "proceed_to_phase"]
         }
       ],
       instructions: [],
@@ -47,10 +48,71 @@ describe("windsurfWriter", () => {
       command: "npx",
       args: ["-y", "@codemcp/workflows"],
       env: { API_KEY: "test" },
-      alwaysAllow: ["*"]
+      alwaysAllow: ["whats_next", "proceed_to_phase"]
     });
   });
 
+  it("records autonomy as advisory guidance because Windsurf has no verified committed built-in permission schema", async () => {
+    const rigidRoot = join(dir, "rigid");
+    const sensibleRoot = join(dir, "sensible");
+    const maxRoot = join(dir, "max");
+
+    const rigidConfig: LogicalConfig = {
+      mcp_servers: [],
+      instructions: [],
+      cli_actions: [],
+      knowledge_sources: [],
+      skills: [],
+      git_hooks: [],
+      setup_notes: [],
+      permission_policy: autonomyPolicy("rigid")
+    };
+
+    const sensibleConfig: LogicalConfig = {
+      ...rigidConfig,
+      permission_policy: autonomyPolicy("sensible-defaults")
+    };
+
+    const maxConfig: LogicalConfig = {
+      ...rigidConfig,
+      permission_policy: autonomyPolicy("max-autonomy")
+    };
+
+    await windsurfWriter.install(rigidConfig, rigidRoot);
+    await windsurfWriter.install(sensibleConfig, sensibleRoot);
+    await windsurfWriter.install(maxConfig, maxRoot);
+
+    const rigidRules = await readFile(
+      join(rigidRoot, ".windsurfrules"),
+      "utf-8"
+    );
+    const sensibleRules = await readFile(
+      join(sensibleRoot, ".windsurfrules"),
+      "utf-8"
+    );
+    const maxRules = await readFile(join(maxRoot, ".windsurfrules"), "utf-8");
+
+    expect(rigidRules).toContain("Windsurf limitation:");
+    expect(rigidRules).toContain("advisory only");
+    expect(rigidRules).toContain(
+      "Ask before: read files, edit and write files, search and list files, safe local shell commands, unsafe local shell commands, web and network access, task or agent delegation."
+    );
+
+    expect(sensibleRules).toContain("Windsurf limitation:");
+    expect(sensibleRules).toContain(
+      "May proceed without extra approval: read files, edit and write files, search and list files, safe local shell commands, task or agent delegation."
+    );
+    expect(sensibleRules).toContain(
+      "Ask before: unsafe local shell commands, web and network access."
+    );
+
+    expect(maxRules).toContain("Windsurf limitation:");
+    expect(maxRules).toContain(
+      "May proceed without extra approval: read files, edit and write files, search and list files, safe local shell commands, unsafe local shell commands, task or agent delegation."
+    );
+    expect(maxRules).toContain("Ask before: web and network access.");
+  });
+
   it("writes .windsurfrules with instructions", async () => {
     const config: LogicalConfig = {
       mcp_servers: [],
@@ -68,3 +130,49 @@ describe("windsurfWriter", () => {
     expect(content).toContain("Follow TDD.");
   });
 });
+
+function autonomyPolicy(
+  profile: "rigid" | "sensible-defaults" | "max-autonomy"
+): LogicalConfig["permission_policy"] {
+  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"
+        }
+      };
+  }
+}

package/src/writers/windsurf.ts

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import type { LogicalConfig } from "@codemcp/ade-core";
+import type { AutonomyCapability, LogicalConfig } from "@codemcp/ade-core";
 import type { HarnessWriter } from "../types.js";
 import {
   writeMcpServers,
@@ -7,6 +7,7 @@ import {
   writeRulesFile,
   writeGitHooks
 } from "../util.js";
+import { hasPermissionPolicy } from "../permission-policy.js";
 
 export const windsurfWriter: HarnessWriter = {
   id: "windsurf",
@@ -19,9 +20,70 @@ export const windsurfWriter: HarnessWriter = {
     });
 
     await writeRulesFile(
-      config.instructions,
+      getWindsurfRules(config),
       join(projectRoot, ".windsurfrules")
     );
     await writeGitHooks(config.git_hooks, projectRoot);
   }
 };
+
+function getWindsurfRules(config: LogicalConfig): string[] {
+  if (!hasPermissionPolicy(config)) {
+    return config.instructions;
+  }
+
+  const { capabilities } = config.permission_policy!;
+  const allow = listCapabilities(capabilities, "allow");
+  const ask = listCapabilities(capabilities, "ask");
+  const deny = listCapabilities(capabilities, "deny");
+
+  const autonomyGuidance = [
+    "Windsurf limitation: ADE could not verify a stable committed project-local permission schema for Windsurf built-in tools, so this autonomy policy is advisory only and should be applied conservatively.",
+    formatGuidance(allow, ask, deny)
+  ];
+
+  return [...autonomyGuidance, ...config.instructions];
+}
+
+function listCapabilities(
+  capabilities: NonNullable<LogicalConfig["permission_policy"]>["capabilities"],
+  decision: "ask" | "allow" | "deny"
+): string[] {
+  return (Object.entries(capabilities) as Array<[AutonomyCapability, string]>)
+    .filter(([, value]) => value === decision)
+    .map(([capability]) => CAPABILITY_LABELS[capability]);
+}
+
+function formatGuidance(
+  allow: string[],
+  ask: string[],
+  deny: string[]
+): string {
+  const lines = ["Autonomy guidance for Windsurf built-in capabilities:"];
+
+  if (allow.length > 0) {
+    lines.push(`- May proceed without extra approval: ${allow.join(", ")}.`);
+  }
+
+  if (ask.length > 0) {
+    lines.push(`- Ask before: ${ask.join(", ")}.`);
+  }
+
+  if (deny.length > 0) {
+    lines.push(
+      `- Do not use unless the user explicitly overrides: ${deny.join(", ")}.`
+    );
+  }
+
+  return lines.join("\n");
+}
+
+const CAPABILITY_LABELS: Record<AutonomyCapability, string> = {
+  read: "read files",
+  edit_write: "edit and write files",
+  search_list: "search and list files",
+  bash_safe: "safe local shell commands",
+  bash_unsafe: "unsafe local shell commands",
+  web: "web and network access",
+  task_agent: "task or agent delegation"
+};