feat(windsurf): add Windsurf as converter target with global scope support

Add `--to windsurf` target for the converter CLI with full spec compliance per docs/specs/windsurf.md: - Claude agents → Windsurf skills (skills/{name}/SKILL.md) - Claude commands → Windsurf workflows (workflows/{name}.md, flat) - Pass-through skills copy unchanged - MCP servers → mcp_config.json (merged with existing, 0o600 permissions) - Hooks skipped with warning, CLAUDE.md skipped Global scope support via generic --scope flag (Windsurf as first adopter): - --to windsurf defaults to global (~/.codeium/windsurf/) - --scope workspace for project-level .windsurf/ output - --output overrides scope-derived paths Shared utilities extracted (resolveTargetOutputRoot, hasPotentialSecrets) to eliminate duplication across CLI commands. 68 new tests (converter, writer, scope resolution). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 18:36:34 +08:00
parent 63e76cf67f
commit 6fe51a0602
19 changed files with 3361 additions and 62 deletions
--- a/tests/resolve-output.test.ts
+++ b/tests/resolve-output.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test"
+import os from "os"
+import path from "path"
+import { resolveTargetOutputRoot } from "../src/utils/resolve-output"
+
+const baseOptions = {
+  outputRoot: "/tmp/output",
+  codexHome: path.join(os.homedir(), ".codex"),
+  piHome: path.join(os.homedir(), ".pi", "agent"),
+  hasExplicitOutput: false,
+}
+
+describe("resolveTargetOutputRoot", () => {
+  test("codex returns codexHome", () => {
+    const result = resolveTargetOutputRoot({ ...baseOptions, targetName: "codex" })
+    expect(result).toBe(baseOptions.codexHome)
+  })
+
+  test("pi returns piHome", () => {
+    const result = resolveTargetOutputRoot({ ...baseOptions, targetName: "pi" })
+    expect(result).toBe(baseOptions.piHome)
+  })
+
+  test("droid returns ~/.factory", () => {
+    const result = resolveTargetOutputRoot({ ...baseOptions, targetName: "droid" })
+    expect(result).toBe(path.join(os.homedir(), ".factory"))
+  })
+
+  test("cursor with no explicit output uses cwd", () => {
+    const result = resolveTargetOutputRoot({ ...baseOptions, targetName: "cursor" })
+    expect(result).toBe(path.join(process.cwd(), ".cursor"))
+  })
+
+  test("cursor with explicit output uses outputRoot", () => {
+    const result = resolveTargetOutputRoot({
+      ...baseOptions,
+      targetName: "cursor",
+      hasExplicitOutput: true,
+    })
+    expect(result).toBe(path.join("/tmp/output", ".cursor"))
+  })
+
+  test("windsurf default scope (global) resolves to ~/.codeium/windsurf/", () => {
+    const result = resolveTargetOutputRoot({
+      ...baseOptions,
+      targetName: "windsurf",
+      scope: "global",
+    })
+    expect(result).toBe(path.join(os.homedir(), ".codeium", "windsurf"))
+  })
+
+  test("windsurf workspace scope resolves to cwd/.windsurf/", () => {
+    const result = resolveTargetOutputRoot({
+      ...baseOptions,
+      targetName: "windsurf",
+      scope: "workspace",
+    })
+    expect(result).toBe(path.join(process.cwd(), ".windsurf"))
+  })
+
+  test("windsurf with explicit output overrides global scope", () => {
+    const result = resolveTargetOutputRoot({
+      ...baseOptions,
+      targetName: "windsurf",
+      hasExplicitOutput: true,
+      scope: "global",
+    })
+    expect(result).toBe("/tmp/output")
+  })
+
+  test("windsurf with explicit output overrides workspace scope", () => {
+    const result = resolveTargetOutputRoot({
+      ...baseOptions,
+      targetName: "windsurf",
+      hasExplicitOutput: true,
+      scope: "workspace",
+    })
+    expect(result).toBe("/tmp/output")
+  })
+
+  test("windsurf with no scope and no explicit output uses cwd/.windsurf/", () => {
+    const result = resolveTargetOutputRoot({
+      ...baseOptions,
+      targetName: "windsurf",
+    })
+    expect(result).toBe(path.join(process.cwd(), ".windsurf"))
+  })
+
+  test("opencode returns outputRoot as-is", () => {
+    const result = resolveTargetOutputRoot({ ...baseOptions, targetName: "opencode" })
+    expect(result).toBe("/tmp/output")
+  })
+})
--- a/tests/windsurf-converter.test.ts
+++ b/tests/windsurf-converter.test.ts
@@ -0,0 +1,573 @@
+import { describe, expect, test } from "bun:test"
+import { convertClaudeToWindsurf, transformContentForWindsurf, normalizeName } from "../src/converters/claude-to-windsurf"
+import type { ClaudePlugin } from "../src/types/claude"
+
+const fixturePlugin: ClaudePlugin = {
+  root: "/tmp/plugin",
+  manifest: { name: "fixture", version: "1.0.0" },
+  agents: [
+    {
+      name: "Security Reviewer",
+      description: "Security-focused agent",
+      capabilities: ["Threat modeling", "OWASP"],
+      model: "claude-sonnet-4-20250514",
+      body: "Focus on vulnerabilities.",
+      sourcePath: "/tmp/plugin/agents/security-reviewer.md",
+    },
+  ],
+  commands: [
+    {
+      name: "workflows:plan",
+      description: "Planning command",
+      argumentHint: "[FOCUS]",
+      model: "inherit",
+      allowedTools: ["Read"],
+      body: "Plan the work.",
+      sourcePath: "/tmp/plugin/commands/workflows/plan.md",
+    },
+  ],
+  skills: [
+    {
+      name: "existing-skill",
+      description: "Existing skill",
+      sourceDir: "/tmp/plugin/skills/existing-skill",
+      skillPath: "/tmp/plugin/skills/existing-skill/SKILL.md",
+    },
+  ],
+  hooks: undefined,
+  mcpServers: {
+    local: { command: "echo", args: ["hello"] },
+  },
+}
+
+const defaultOptions = {
+  agentMode: "subagent" as const,
+  inferTemperature: false,
+  permissions: "none" as const,
+}
+
+describe("convertClaudeToWindsurf", () => {
+  test("converts agents to skills with correct name and description in SKILL.md", () => {
+    const bundle = convertClaudeToWindsurf(fixturePlugin, defaultOptions)
+
+    const skill = bundle.agentSkills.find((s) => s.name === "security-reviewer")
+    expect(skill).toBeDefined()
+    expect(skill!.content).toContain("name: security-reviewer")
+    expect(skill!.content).toContain("description: Security-focused agent")
+    expect(skill!.content).toContain("Focus on vulnerabilities.")
+  })
+
+  test("agent capabilities included in skill content", () => {
+    const bundle = convertClaudeToWindsurf(fixturePlugin, defaultOptions)
+    const skill = bundle.agentSkills.find((s) => s.name === "security-reviewer")
+    expect(skill!.content).toContain("## Capabilities")
+    expect(skill!.content).toContain("- Threat modeling")
+    expect(skill!.content).toContain("- OWASP")
+  })
+
+  test("agent with empty description gets default description", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      agents: [
+        {
+          name: "my-agent",
+          body: "Do things.",
+          sourcePath: "/tmp/plugin/agents/my-agent.md",
+        },
+      ],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.agentSkills[0].content).toContain("description: Converted from Claude agent my-agent")
+  })
+
+  test("agent model field silently dropped", () => {
+    const bundle = convertClaudeToWindsurf(fixturePlugin, defaultOptions)
+    const skill = bundle.agentSkills.find((s) => s.name === "security-reviewer")
+    expect(skill!.content).not.toContain("model:")
+  })
+
+  test("agent with empty body gets default body text", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      agents: [
+        {
+          name: "Empty Agent",
+          description: "An empty agent",
+          body: "",
+          sourcePath: "/tmp/plugin/agents/empty.md",
+        },
+      ],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.agentSkills[0].content).toContain("Instructions converted from the Empty Agent agent.")
+  })
+
+  test("converts commands to workflows with description", () => {
+    const bundle = convertClaudeToWindsurf(fixturePlugin, defaultOptions)
+
+    expect(bundle.commandWorkflows).toHaveLength(1)
+    const workflow = bundle.commandWorkflows[0]
+    expect(workflow.name).toBe("workflows-plan")
+    expect(workflow.description).toBe("Planning command")
+    expect(workflow.body).toContain("Plan the work.")
+  })
+
+  test("command argumentHint preserved as note in body", () => {
+    const bundle = convertClaudeToWindsurf(fixturePlugin, defaultOptions)
+    const workflow = bundle.commandWorkflows[0]
+    expect(workflow.body).toContain("> Arguments: [FOCUS]")
+  })
+
+  test("command with no description gets fallback", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      commands: [
+        {
+          name: "my-command",
+          body: "Do things.",
+          sourcePath: "/tmp/plugin/commands/my-command.md",
+        },
+      ],
+      agents: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.commandWorkflows[0].description).toBe("Converted from Claude command my-command")
+  })
+
+  test("command with disableModelInvocation is still included", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      commands: [
+        {
+          name: "disabled-command",
+          description: "Disabled command",
+          disableModelInvocation: true,
+          body: "Disabled body.",
+          sourcePath: "/tmp/plugin/commands/disabled.md",
+        },
+      ],
+      agents: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.commandWorkflows).toHaveLength(1)
+    expect(bundle.commandWorkflows[0].name).toBe("disabled-command")
+  })
+
+  test("command allowedTools silently dropped", () => {
+    const bundle = convertClaudeToWindsurf(fixturePlugin, defaultOptions)
+    const workflow = bundle.commandWorkflows[0]
+    expect(workflow.body).not.toContain("allowedTools")
+  })
+
+  test("skills pass through as directory references", () => {
+    const bundle = convertClaudeToWindsurf(fixturePlugin, defaultOptions)
+
+    expect(bundle.skillDirs).toHaveLength(1)
+    expect(bundle.skillDirs[0].name).toBe("existing-skill")
+    expect(bundle.skillDirs[0].sourceDir).toBe("/tmp/plugin/skills/existing-skill")
+  })
+
+  test("name normalization handles various inputs", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      agents: [
+        { name: "My Cool Agent!!!", description: "Cool", body: "Body.", sourcePath: "/tmp/a.md" },
+        { name: "UPPERCASE-AGENT", description: "Upper", body: "Body.", sourcePath: "/tmp/b.md" },
+        { name: "agent--with--double-hyphens", description: "Hyphens", body: "Body.", sourcePath: "/tmp/c.md" },
+      ],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.agentSkills[0].name).toBe("my-cool-agent")
+    expect(bundle.agentSkills[1].name).toBe("uppercase-agent")
+    expect(bundle.agentSkills[2].name).toBe("agent-with-double-hyphens")
+  })
+
+  test("name deduplication within agent skills", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      agents: [
+        { name: "reviewer", description: "First", body: "Body.", sourcePath: "/tmp/a.md" },
+        { name: "Reviewer", description: "Second", body: "Body.", sourcePath: "/tmp/b.md" },
+      ],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.agentSkills[0].name).toBe("reviewer")
+    expect(bundle.agentSkills[1].name).toBe("reviewer-2")
+  })
+
+  test("agent skill name deduplicates against pass-through skill names", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      agents: [
+        { name: "existing-skill", description: "Agent with same name as skill", body: "Body.", sourcePath: "/tmp/a.md" },
+      ],
+      commands: [],
+      skills: [
+        {
+          name: "existing-skill",
+          description: "Pass-through skill",
+          sourceDir: "/tmp/plugin/skills/existing-skill",
+          skillPath: "/tmp/plugin/skills/existing-skill/SKILL.md",
+        },
+      ],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.agentSkills[0].name).toBe("existing-skill-2")
+  })
+
+  test("agent skill and command with same normalized name are NOT deduplicated (separate sets)", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      agents: [
+        { name: "review", description: "Agent", body: "Body.", sourcePath: "/tmp/a.md" },
+      ],
+      commands: [
+        { name: "review", description: "Command", body: "Body.", sourcePath: "/tmp/b.md" },
+      ],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.agentSkills[0].name).toBe("review")
+    expect(bundle.commandWorkflows[0].name).toBe("review")
+  })
+
+  test("large agent skill does not emit 12K character limit warning (skills have no limit)", () => {
+    const warnings: string[] = []
+    const originalWarn = console.warn
+    console.warn = (msg: string) => warnings.push(msg)
+
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      agents: [
+        {
+          name: "large-agent",
+          description: "Large agent",
+          body: "x".repeat(12_000),
+          sourcePath: "/tmp/a.md",
+        },
+      ],
+      commands: [],
+      skills: [],
+    }
+
+    convertClaudeToWindsurf(plugin, defaultOptions)
+    console.warn = originalWarn
+
+    expect(warnings.some((w) => w.includes("12000") || w.includes("limit"))).toBe(false)
+  })
+
+  test("hooks present emits console.warn", () => {
+    const warnings: string[] = []
+    const originalWarn = console.warn
+    console.warn = (msg: string) => warnings.push(msg)
+
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      hooks: { hooks: { PreToolUse: [{ matcher: "*", hooks: [{ type: "command", command: "echo test" }] }] } },
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    convertClaudeToWindsurf(plugin, defaultOptions)
+    console.warn = originalWarn
+
+    expect(warnings.some((w) => w.includes("Windsurf"))).toBe(true)
+  })
+
+  test("empty plugin produces empty bundle with null mcpConfig", () => {
+    const plugin: ClaudePlugin = {
+      root: "/tmp/empty",
+      manifest: { name: "empty", version: "1.0.0" },
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.agentSkills).toHaveLength(0)
+    expect(bundle.commandWorkflows).toHaveLength(0)
+    expect(bundle.skillDirs).toHaveLength(0)
+    expect(bundle.mcpConfig).toBeNull()
+  })
+
+  // MCP config tests
+
+  test("stdio server produces correct mcpConfig JSON structure", () => {
+    const bundle = convertClaudeToWindsurf(fixturePlugin, defaultOptions)
+    expect(bundle.mcpConfig).not.toBeNull()
+    expect(bundle.mcpConfig!.mcpServers.local).toEqual({
+      command: "echo",
+      args: ["hello"],
+    })
+  })
+
+  test("stdio server with env vars includes actual values (not redacted)", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      mcpServers: {
+        myserver: {
+          command: "serve",
+          env: {
+            API_KEY: "secret123",
+            PORT: "3000",
+          },
+        },
+      },
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.mcpConfig!.mcpServers.myserver.env).toEqual({
+      API_KEY: "secret123",
+      PORT: "3000",
+    })
+  })
+
+  test("HTTP/SSE server produces correct mcpConfig with serverUrl", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      mcpServers: {
+        remote: { url: "https://example.com/mcp", headers: { Authorization: "Bearer abc" } },
+      },
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.mcpConfig!.mcpServers.remote).toEqual({
+      serverUrl: "https://example.com/mcp",
+      headers: { Authorization: "Bearer abc" },
+    })
+  })
+
+  test("mixed stdio and HTTP servers both included", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      mcpServers: {
+        local: { command: "echo", args: ["hello"] },
+        remote: { url: "https://example.com/mcp" },
+      },
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(Object.keys(bundle.mcpConfig!.mcpServers)).toHaveLength(2)
+    expect(bundle.mcpConfig!.mcpServers.local.command).toBe("echo")
+    expect(bundle.mcpConfig!.mcpServers.remote.serverUrl).toBe("https://example.com/mcp")
+  })
+
+  test("hasPotentialSecrets emits console.warn for sensitive env keys", () => {
+    const warnings: string[] = []
+    const originalWarn = console.warn
+    console.warn = (...msgs: unknown[]) => warnings.push(msgs.map(String).join(" "))
+
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      mcpServers: {
+        myserver: {
+          command: "serve",
+          env: { API_KEY: "secret123", PORT: "3000" },
+        },
+      },
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    convertClaudeToWindsurf(plugin, defaultOptions)
+    console.warn = originalWarn
+
+    expect(warnings.some((w) => w.includes("secrets") && w.includes("myserver"))).toBe(true)
+  })
+
+  test("no secrets warning when env vars are safe", () => {
+    const warnings: string[] = []
+    const originalWarn = console.warn
+    console.warn = (...msgs: unknown[]) => warnings.push(msgs.map(String).join(" "))
+
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      mcpServers: {
+        myserver: {
+          command: "serve",
+          env: { PORT: "3000", HOST: "localhost" },
+        },
+      },
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    convertClaudeToWindsurf(plugin, defaultOptions)
+    console.warn = originalWarn
+
+    expect(warnings.some((w) => w.includes("secrets"))).toBe(false)
+  })
+
+  test("no MCP servers produces null mcpConfig", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      mcpServers: undefined,
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.mcpConfig).toBeNull()
+  })
+
+  test("server with no command and no URL is skipped with warning", () => {
+    const warnings: string[] = []
+    const originalWarn = console.warn
+    console.warn = (...msgs: unknown[]) => warnings.push(msgs.map(String).join(" "))
+
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      mcpServers: {
+        broken: {} as { command: string },
+      },
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    console.warn = originalWarn
+
+    expect(bundle.mcpConfig).toBeNull()
+    expect(warnings.some((w) => w.includes("broken") && w.includes("no command or URL"))).toBe(true)
+  })
+
+  test("server command without args omits args field", () => {
+    const plugin: ClaudePlugin = {
+      ...fixturePlugin,
+      mcpServers: {
+        simple: { command: "myserver" },
+      },
+      agents: [],
+      commands: [],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToWindsurf(plugin, defaultOptions)
+    expect(bundle.mcpConfig!.mcpServers.simple).toEqual({ command: "myserver" })
+    expect(bundle.mcpConfig!.mcpServers.simple.args).toBeUndefined()
+  })
+})
+
+describe("transformContentForWindsurf", () => {
+  test("transforms .claude/ paths to .windsurf/", () => {
+    const result = transformContentForWindsurf("Read .claude/settings.json for config.")
+    expect(result).toContain(".windsurf/settings.json")
+    expect(result).not.toContain(".claude/")
+  })
+
+  test("transforms ~/.claude/ paths to ~/.codeium/windsurf/", () => {
+    const result = transformContentForWindsurf("Check ~/.claude/config for settings.")
+    expect(result).toContain("~/.codeium/windsurf/config")
+    expect(result).not.toContain("~/.claude/")
+  })
+
+  test("transforms Task agent(args) to skill reference", () => {
+    const input = `Run these:
+
+- Task repo-research-analyst(feature_description)
+- Task learnings-researcher(feature_description)
+
+Task best-practices-researcher(topic)`
+
+    const result = transformContentForWindsurf(input)
+    expect(result).toContain("Use the @repo-research-analyst skill: feature_description")
+    expect(result).toContain("Use the @learnings-researcher skill: feature_description")
+    expect(result).toContain("Use the @best-practices-researcher skill: topic")
+    expect(result).not.toContain("Task repo-research-analyst")
+  })
+
+  test("keeps @agent references as-is for known agents (Windsurf skill invocation syntax)", () => {
+    const result = transformContentForWindsurf("Ask @security-sentinel for a review.", ["security-sentinel"])
+    expect(result).toContain("@security-sentinel")
+    expect(result).not.toContain("/agents/")
+  })
+
+  test("does not transform @unknown-name when not in known agents", () => {
+    const result = transformContentForWindsurf("Contact @someone-else for help.", ["security-sentinel"])
+    expect(result).toContain("@someone-else")
+  })
+
+  test("transforms slash command refs to /{workflow-name} (per spec)", () => {
+    const result = transformContentForWindsurf("Run /workflows:plan to start planning.")
+    expect(result).toContain("/workflows-plan")
+    expect(result).not.toContain("/commands/")
+  })
+
+  test("does not transform partial .claude paths in middle of word", () => {
+    const result = transformContentForWindsurf("Check some-package/.claude-config/settings")
+    expect(result).toContain("some-package/")
+  })
+
+  test("handles case sensitivity in @agent-name matching", () => {
+    const result = transformContentForWindsurf("Delegate to @My-Agent for help.", ["my-agent"])
+    // @My-Agent won't match my-agent since regex is case-sensitive on the known names
+    expect(result).toContain("@My-Agent")
+  })
+
+  test("handles multiple occurrences of same transform", () => {
+    const result = transformContentForWindsurf(
+      "Use .claude/foo and .claude/bar for config.",
+    )
+    expect(result).toContain(".windsurf/foo")
+    expect(result).toContain(".windsurf/bar")
+    expect(result).not.toContain(".claude/")
+  })
+})
+
+describe("normalizeName", () => {
+  test("lowercases and hyphenates spaces", () => {
+    expect(normalizeName("Security Reviewer")).toBe("security-reviewer")
+  })
+
+  test("replaces colons with hyphens", () => {
+    expect(normalizeName("workflows:plan")).toBe("workflows-plan")
+  })
+
+  test("collapses consecutive hyphens", () => {
+    expect(normalizeName("agent--with--double-hyphens")).toBe("agent-with-double-hyphens")
+  })
+
+  test("strips leading/trailing hyphens", () => {
+    expect(normalizeName("-leading-and-trailing-")).toBe("leading-and-trailing")
+  })
+
+  test("empty string returns item", () => {
+    expect(normalizeName("")).toBe("item")
+  })
+
+  test("non-letter start returns item", () => {
+    expect(normalizeName("123-agent")).toBe("item")
+  })
+})
--- a/tests/windsurf-writer.test.ts
+++ b/tests/windsurf-writer.test.ts
@@ -0,0 +1,359 @@
+import { describe, expect, test } from "bun:test"
+import { promises as fs } from "fs"
+import path from "path"
+import os from "os"
+import { writeWindsurfBundle } from "../src/targets/windsurf"
+import type { WindsurfBundle } from "../src/types/windsurf"
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const emptyBundle: WindsurfBundle = {
+  agentSkills: [],
+  commandWorkflows: [],
+  skillDirs: [],
+  mcpConfig: null,
+}
+
+describe("writeWindsurfBundle", () => {
+  test("creates correct directory structure with all components", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-test-"))
+    const bundle: WindsurfBundle = {
+      agentSkills: [
+        {
+          name: "security-reviewer",
+          content: "---\nname: security-reviewer\ndescription: Security-focused agent\n---\n\n# security-reviewer\n\nReview code for vulnerabilities.\n",
+        },
+      ],
+      commandWorkflows: [
+        {
+          name: "workflows-plan",
+          description: "Planning command",
+          body: "> Arguments: [FOCUS]\n\nPlan the work.",
+        },
+      ],
+      skillDirs: [
+        {
+          name: "skill-one",
+          sourceDir: path.join(import.meta.dir, "fixtures", "sample-plugin", "skills", "skill-one"),
+        },
+      ],
+      mcpConfig: {
+        mcpServers: {
+          local: { command: "echo", args: ["hello"] },
+        },
+      },
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    // No AGENTS.md — removed in v0.11.0
+    expect(await exists(path.join(tempRoot, "AGENTS.md"))).toBe(false)
+
+    // Agent skill written as skills/<name>/SKILL.md
+    const agentSkillPath = path.join(tempRoot, "skills", "security-reviewer", "SKILL.md")
+    expect(await exists(agentSkillPath)).toBe(true)
+    const agentContent = await fs.readFile(agentSkillPath, "utf8")
+    expect(agentContent).toContain("name: security-reviewer")
+    expect(agentContent).toContain("description: Security-focused agent")
+    expect(agentContent).toContain("Review code for vulnerabilities.")
+
+    // No workflows/agents/ or workflows/commands/ subdirectories (flat per spec)
+    expect(await exists(path.join(tempRoot, "workflows", "agents"))).toBe(false)
+    expect(await exists(path.join(tempRoot, "workflows", "commands"))).toBe(false)
+
+    // Command workflow flat in outputRoot/workflows/ (per spec)
+    const cmdWorkflowPath = path.join(tempRoot, "workflows", "workflows-plan.md")
+    expect(await exists(cmdWorkflowPath)).toBe(true)
+    const cmdContent = await fs.readFile(cmdWorkflowPath, "utf8")
+    expect(cmdContent).toContain("description: Planning command")
+    expect(cmdContent).toContain("Plan the work.")
+
+    // Copied skill directly in outputRoot/skills/
+    expect(await exists(path.join(tempRoot, "skills", "skill-one", "SKILL.md"))).toBe(true)
+
+    // MCP config directly in outputRoot/
+    const mcpPath = path.join(tempRoot, "mcp_config.json")
+    expect(await exists(mcpPath)).toBe(true)
+    const mcpContent = JSON.parse(await fs.readFile(mcpPath, "utf8"))
+    expect(mcpContent.mcpServers.local).toEqual({ command: "echo", args: ["hello"] })
+  })
+
+  test("writes directly into outputRoot without nesting", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-direct-"))
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      agentSkills: [
+        {
+          name: "reviewer",
+          content: "---\nname: reviewer\ndescription: A reviewer\n---\n\n# reviewer\n\nReview content.\n",
+        },
+      ],
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    // Skill should be directly in outputRoot/skills/reviewer/SKILL.md
+    expect(await exists(path.join(tempRoot, "skills", "reviewer", "SKILL.md"))).toBe(true)
+    // Should NOT create a .windsurf subdirectory
+    expect(await exists(path.join(tempRoot, ".windsurf"))).toBe(false)
+  })
+
+  test("handles empty bundle gracefully", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-empty-"))
+
+    await writeWindsurfBundle(tempRoot, emptyBundle)
+    expect(await exists(tempRoot)).toBe(true)
+    // No mcp_config.json for null mcpConfig
+    expect(await exists(path.join(tempRoot, "mcp_config.json"))).toBe(false)
+  })
+
+  test("path traversal in agent skill name is rejected", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-traversal-"))
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      agentSkills: [
+        { name: "../escape", content: "Bad content." },
+      ],
+    }
+
+    expect(writeWindsurfBundle(tempRoot, bundle)).rejects.toThrow("unsafe path")
+  })
+
+  test("path traversal in command workflow name is rejected", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-traversal2-"))
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      commandWorkflows: [
+        { name: "../escape", description: "Malicious", body: "Bad content." },
+      ],
+    }
+
+    expect(writeWindsurfBundle(tempRoot, bundle)).rejects.toThrow("unsafe path")
+  })
+
+  test("skill directory containment check prevents escape", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-skill-escape-"))
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      skillDirs: [
+        { name: "../escape", sourceDir: "/tmp/fake-skill" },
+      ],
+    }
+
+    expect(writeWindsurfBundle(tempRoot, bundle)).rejects.toThrow("unsafe path")
+  })
+
+  test("agent skill files have YAML frontmatter with name and description", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-fm-"))
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      agentSkills: [
+        {
+          name: "test-agent",
+          content: "---\nname: test-agent\ndescription: Test agent description\n---\n\n# test-agent\n\nDo test things.\n",
+        },
+      ],
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    const skillPath = path.join(tempRoot, "skills", "test-agent", "SKILL.md")
+    const content = await fs.readFile(skillPath, "utf8")
+    expect(content).toContain("---")
+    expect(content).toContain("name: test-agent")
+    expect(content).toContain("description: Test agent description")
+    expect(content).toContain("# test-agent")
+    expect(content).toContain("Do test things.")
+  })
+
+  // MCP config merge tests
+
+  test("writes mcp_config.json to outputRoot", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-mcp-"))
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      mcpConfig: {
+        mcpServers: {
+          myserver: { command: "serve", args: ["--port", "3000"] },
+        },
+      },
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    const mcpPath = path.join(tempRoot, "mcp_config.json")
+    expect(await exists(mcpPath)).toBe(true)
+    const content = JSON.parse(await fs.readFile(mcpPath, "utf8"))
+    expect(content.mcpServers.myserver.command).toBe("serve")
+    expect(content.mcpServers.myserver.args).toEqual(["--port", "3000"])
+  })
+
+  test("merges with existing mcp_config.json preserving user servers", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-merge-"))
+    const mcpPath = path.join(tempRoot, "mcp_config.json")
+
+    // Write existing config with a user server
+    await fs.writeFile(mcpPath, JSON.stringify({
+      mcpServers: {
+        "user-server": { command: "my-tool", args: ["--flag"] },
+      },
+    }, null, 2))
+
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      mcpConfig: {
+        mcpServers: {
+          "plugin-server": { command: "plugin-tool" },
+        },
+      },
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    const content = JSON.parse(await fs.readFile(mcpPath, "utf8"))
+    // Both servers should be present
+    expect(content.mcpServers["user-server"].command).toBe("my-tool")
+    expect(content.mcpServers["plugin-server"].command).toBe("plugin-tool")
+  })
+
+  test("backs up existing mcp_config.json before overwrite", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-backup-"))
+    const mcpPath = path.join(tempRoot, "mcp_config.json")
+
+    await fs.writeFile(mcpPath, '{"mcpServers":{}}')
+
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      mcpConfig: {
+        mcpServers: { new: { command: "new-tool" } },
+      },
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    // A backup file should exist
+    const files = await fs.readdir(tempRoot)
+    const backupFiles = files.filter((f) => f.startsWith("mcp_config.json.bak."))
+    expect(backupFiles.length).toBeGreaterThanOrEqual(1)
+  })
+
+  test("handles corrupted existing mcp_config.json with warning", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-corrupt-"))
+    const mcpPath = path.join(tempRoot, "mcp_config.json")
+
+    await fs.writeFile(mcpPath, "not valid json{{{")
+
+    const warnings: string[] = []
+    const originalWarn = console.warn
+    console.warn = (...msgs: unknown[]) => warnings.push(msgs.map(String).join(" "))
+
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      mcpConfig: {
+        mcpServers: { new: { command: "new-tool" } },
+      },
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+    console.warn = originalWarn
+
+    expect(warnings.some((w) => w.includes("could not be parsed"))).toBe(true)
+    const content = JSON.parse(await fs.readFile(mcpPath, "utf8"))
+    expect(content.mcpServers.new.command).toBe("new-tool")
+  })
+
+  test("handles existing mcp_config.json with array at root", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-array-"))
+    const mcpPath = path.join(tempRoot, "mcp_config.json")
+
+    await fs.writeFile(mcpPath, "[1,2,3]")
+
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      mcpConfig: {
+        mcpServers: { new: { command: "new-tool" } },
+      },
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    const content = JSON.parse(await fs.readFile(mcpPath, "utf8"))
+    expect(content.mcpServers.new.command).toBe("new-tool")
+    // Array root should be replaced with object
+    expect(Array.isArray(content)).toBe(false)
+  })
+
+  test("preserves non-mcpServers keys in existing file", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-preserve-"))
+    const mcpPath = path.join(tempRoot, "mcp_config.json")
+
+    await fs.writeFile(mcpPath, JSON.stringify({
+      customSetting: true,
+      version: 2,
+      mcpServers: { old: { command: "old-tool" } },
+    }, null, 2))
+
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      mcpConfig: {
+        mcpServers: { new: { command: "new-tool" } },
+      },
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    const content = JSON.parse(await fs.readFile(mcpPath, "utf8"))
+    expect(content.customSetting).toBe(true)
+    expect(content.version).toBe(2)
+    expect(content.mcpServers.new.command).toBe("new-tool")
+    expect(content.mcpServers.old.command).toBe("old-tool")
+  })
+
+  test("server name collision: plugin entry wins", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-collision-"))
+    const mcpPath = path.join(tempRoot, "mcp_config.json")
+
+    await fs.writeFile(mcpPath, JSON.stringify({
+      mcpServers: { shared: { command: "old-version" } },
+    }, null, 2))
+
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      mcpConfig: {
+        mcpServers: { shared: { command: "new-version" } },
+      },
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    const content = JSON.parse(await fs.readFile(mcpPath, "utf8"))
+    expect(content.mcpServers.shared.command).toBe("new-version")
+  })
+
+  test("mcp_config.json written with restrictive permissions", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "windsurf-perms-"))
+    const bundle: WindsurfBundle = {
+      ...emptyBundle,
+      mcpConfig: {
+        mcpServers: { server: { command: "tool" } },
+      },
+    }
+
+    await writeWindsurfBundle(tempRoot, bundle)
+
+    const mcpPath = path.join(tempRoot, "mcp_config.json")
+    const stat = await fs.stat(mcpPath)
+    // On Unix: 0o600 = owner read+write only. On Windows, permissions work differently.
+    if (process.platform !== "win32") {
+      const mode = stat.mode & 0o777
+      expect(mode).toBe(0o600)
+    }
+  })
+})