@codemcp/ade-harnesses 0.0.2

package/dist/writers/universal.js

@@ -0,0 +1,22 @@
+import { join } from "node:path";
+import { writeFile } from "node:fs/promises";
+import { writeMcpServers, writeGitHooks } from "../util.js";
+export const universalWriter = {
+    id: "universal",
+    label: "Universal (AGENTS.md + .mcp.json)",
+    description: "Cross-tool standard — AGENTS.md + .mcp.json (works with any agent)",
+    async install(config, projectRoot) {
+        if (config.instructions.length > 0) {
+            const lines = [
+                "# AGENTS",
+                "",
+                ...config.instructions.flatMap((i) => [i, ""])
+            ];
+            await writeFile(join(projectRoot, "AGENTS.md"), lines.join("\n"), "utf-8");
+        }
+        await writeMcpServers(config.mcp_servers, {
+            path: join(projectRoot, ".mcp.json")
+        });
+        await writeGitHooks(config.git_hooks, projectRoot);
+    }
+};

package/dist/writers/windsurf.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessWriter } from "../types.js";
+export declare const windsurfWriter: HarnessWriter;

package/dist/writers/windsurf.js

@@ -0,0 +1,15 @@
+import { join } from "node:path";
+import { writeMcpServers, alwaysAllowEntry, writeRulesFile, writeGitHooks } from "../util.js";
+export const windsurfWriter = {
+    id: "windsurf",
+    label: "Windsurf",
+    description: "Codeium's AI IDE — .windsurf/mcp.json + .windsurfrules",
+    async install(config, projectRoot) {
+        await writeMcpServers(config.mcp_servers, {
+            path: join(projectRoot, ".windsurf", "mcp.json"),
+            transform: alwaysAllowEntry
+        });
+        await writeRulesFile(config.instructions, join(projectRoot, ".windsurfrules"));
+        await writeGitHooks(config.git_hooks, projectRoot);
+    }
+};

package/eslint.config.mjs

@@ -0,0 +1,40 @@
+import js from "@eslint/js";
+import { parser, configs } from "typescript-eslint";
+import prettier from "eslint-config-prettier";
+
+export default [
+  js.configs.recommended,
+  ...configs.recommended,
+  prettier,
+  {
+    // Config for TypeScript files
+    files: ["**/*.{ts,tsx}"],
+    languageOptions: {
+      parser,
+      parserOptions: {
+        project: ["./tsconfig.json", "./tsconfig.vitest.json"]
+      }
+    }
+  },
+  {
+    // Config for JavaScript files - no TypeScript parsing
+    files: ["**/*.{js,jsx}"],
+    ...js.configs.recommended
+  },
+  {
+    // Relaxed rules for test files
+    files: ["**/*.test.ts", "**/*.spec.ts"],
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": "off"
+    }
+  },
+  {
+    ignores: [
+      "**/node_modules/**",
+      "**/dist/**",
+      ".pnpm-store/**",
+      "pnpm-lock.yaml"
+    ]
+  }
+];

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@codemcp/ade-harnesses",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@codemcp/skills": "^2.3.0",
+    "@codemcp/ade-core": "0.0.2"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.21.0",
+    "@typescript-eslint/parser": "^8.21.0",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "prettier": "^3.4.2",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.7.3"
+  },
+  "version": "0.0.2",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean:build": "rimraf ./dist",
+    "dev": "nodemon",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "typecheck": "tsc"
+  }
+}

package/src/index.spec.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { allHarnessWriters, getHarnessWriter, getHarnessIds } from "./index.js";
+
+describe("harness registry", () => {
+  it("exports all harness writers", () => {
+    expect(allHarnessWriters).toHaveLength(9);
+    const ids = allHarnessWriters.map((w) => w.id);
+    expect(ids).toContain("universal");
+    expect(ids).toContain("claude-code");
+    expect(ids).toContain("cursor");
+    expect(ids).toContain("copilot");
+    expect(ids).toContain("windsurf");
+    expect(ids).toContain("cline");
+    expect(ids).toContain("roo-code");
+    expect(ids).toContain("kiro");
+    expect(ids).toContain("opencode");
+  });
+
+  it("looks up harness by id", () => {
+    expect(getHarnessWriter("cursor")?.label).toBe("Cursor");
+    expect(getHarnessWriter("nonexistent")).toBeUndefined();
+  });
+
+  it("returns all harness ids", () => {
+    const ids = getHarnessIds();
+    expect(ids).toEqual([
+      "universal",
+      "claude-code",
+      "cursor",
+      "copilot",
+      "windsurf",
+      "cline",
+      "roo-code",
+      "kiro",
+      "opencode"
+    ]);
+  });
+
+  it("all writers have label and description", () => {
+    for (const w of allHarnessWriters) {
+      expect(w.label).toBeTruthy();
+      expect(w.description).toBeTruthy();
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,46 @@
+export type { HarnessWriter } from "./types.js";
+export { installSkills } from "./skills-installer.js";
+
+export { universalWriter } from "./writers/universal.js";
+export { claudeCodeWriter } from "./writers/claude-code.js";
+export { cursorWriter } from "./writers/cursor.js";
+export { copilotWriter } from "./writers/copilot.js";
+export { windsurfWriter } from "./writers/windsurf.js";
+export { clineWriter } from "./writers/cline.js";
+export { rooCodeWriter } from "./writers/roo-code.js";
+export { kiroWriter } from "./writers/kiro.js";
+export { opencodeWriter } from "./writers/opencode.js";
+
+import type { HarnessWriter } from "./types.js";
+import { universalWriter } from "./writers/universal.js";
+import { claudeCodeWriter } from "./writers/claude-code.js";
+import { cursorWriter } from "./writers/cursor.js";
+import { copilotWriter } from "./writers/copilot.js";
+import { windsurfWriter } from "./writers/windsurf.js";
+import { clineWriter } from "./writers/cline.js";
+import { rooCodeWriter } from "./writers/roo-code.js";
+import { kiroWriter } from "./writers/kiro.js";
+import { opencodeWriter } from "./writers/opencode.js";
+
+/** All built-in harness writers, ordered for wizard display. */
+export const allHarnessWriters: HarnessWriter[] = [
+  universalWriter,
+  claudeCodeWriter,
+  cursorWriter,
+  copilotWriter,
+  windsurfWriter,
+  clineWriter,
+  rooCodeWriter,
+  kiroWriter,
+  opencodeWriter
+];
+
+/** Look up a harness writer by id. */
+export function getHarnessWriter(id: string): HarnessWriter | undefined {
+  return allHarnessWriters.find((w) => w.id === id);
+}
+
+/** All valid harness IDs. */
+export function getHarnessIds(): string[] {
+  return allHarnessWriters.map((w) => w.id);
+}

package/src/skills-installer.ts

@@ -0,0 +1,54 @@
+import { join } from "node:path";
+import type { SkillDefinition, InlineSkill } from "@codemcp/ade-core";
+import { runAdd } from "@codemcp/skills/api";
+
+function isInlineSkill(skill: SkillDefinition): skill is InlineSkill {
+  return "body" in skill;
+}
+
+/**
+ * Install skills using the @codemcp/skills programmatic API.
+ *
+ * Inline skills are expected to already exist as SKILL.md files under
+ * `<projectRoot>/.ade/skills/<name>/` (written by the agent writer).
+ * This function calls `runAdd` with the local path for inline skills
+ * and the remote source for external skills.
+ *
+ * Note: `runAdd` uses `process.cwd()` to determine the install destination.
+ * This function changes cwd to `projectRoot` before calling `runAdd`.
+ */
+export async function installSkills(
+  skills: SkillDefinition[],
+  projectRoot: string
+): Promise<void> {
+  if (skills.length === 0) return;
+
+  const originalCwd = process.cwd();
+  process.chdir(projectRoot);
+
+  try {
+    for (const skill of skills) {
+      const source = isInlineSkill(skill)
+        ? join(projectRoot, ".ade", "skills", skill.name)
+        : skill.source;
+
+      try {
+        await runAdd([source], { yes: true, all: true });
+      } catch (err) {
+        // runAdd may throw on network errors for external skills.
+        // Log and continue — inline skills should always succeed.
+        console.warn(
+          `Warning: failed to install skill "${skill.name}" from ${source}:`,
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
+  } finally {
+    // Restore cwd only if the original directory still exists
+    try {
+      process.chdir(originalCwd);
+    } catch {
+      // Original cwd may have been removed (e.g. in tests)
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,12 @@
+import type { AgentWriterDef } from "@codemcp/ade-core";
+
+/**
+ * A harness writer extends AgentWriterDef with metadata for display in the
+ * setup wizard and CLI help.
+ */
+export interface HarnessWriter extends AgentWriterDef {
+  /** Human-readable label for the wizard (e.g. "Claude Code") */
+  label: string;
+  /** Short description shown as hint in the wizard */
+  description: string;
+}

package/src/util.ts

@@ -0,0 +1,208 @@
+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<void> {
+  for (const skill of config.skills) {
+    if (!("body" in skill)) continue;
+
+    const skillDir = join(projectRoot, ".ade", "skills", skill.name);
+    await mkdir(skillDir, { recursive: true });
+
+    const frontmatter = [
+      "---",
+      `name: ${skill.name}`,
+      `description: ${skill.description}`,
+      "---"
+    ].join("\n");
+
+    await writeFile(
+      join(skillDir, "SKILL.md"),
+      `${frontmatter}\n\n${skill.body}\n`,
+      "utf-8"
+    );
+  }
+}

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

@@ -0,0 +1,162 @@
+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 { claudeCodeWriter } from "./claude-code.js";
+
+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("writes .claude/settings.json with MCP tool permissions", 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).toContain("MCP(workflows:*)");
+  });
+
+  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", 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 claudeCodeWriter.install(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");
+  });
+});