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>
This commit is contained in:
Ryan Burnham
205
src/converters/claude-to-windsurf.ts
Normal file
205
src/converters/claude-to-windsurf.ts
Normal file
@@ -0,0 +1,205 @@
|
||||
import { formatFrontmatter } from "../utils/frontmatter"
|
||||
import { findServersWithPotentialSecrets } from "../utils/secrets"
|
||||
import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
|
||||
import type { WindsurfBundle, WindsurfGeneratedSkill, WindsurfMcpConfig, WindsurfMcpServerEntry, WindsurfWorkflow } from "../types/windsurf"
|
||||
import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
|
||||
|
||||
export type ClaudeToWindsurfOptions = ClaudeToOpenCodeOptions
|
||||
|
||||
const WINDSURF_WORKFLOW_CHAR_LIMIT = 12_000
|
||||
|
||||
export function convertClaudeToWindsurf(
|
||||
plugin: ClaudePlugin,
|
||||
_options: ClaudeToWindsurfOptions,
|
||||
): WindsurfBundle {
|
||||
const knownAgentNames = plugin.agents.map((a) => normalizeName(a.name))
|
||||
|
||||
// Pass-through skills (collected first so agent skill names can deduplicate against them)
|
||||
const skillDirs = plugin.skills.map((skill) => ({
|
||||
name: skill.name,
|
||||
sourceDir: skill.sourceDir,
|
||||
}))
|
||||
|
||||
// Convert agents to skills (seed usedNames with pass-through skill names)
|
||||
const usedSkillNames = new Set<string>(skillDirs.map((s) => s.name))
|
||||
const agentSkills = plugin.agents.map((agent) =>
|
||||
convertAgentToSkill(agent, knownAgentNames, usedSkillNames),
|
||||
)
|
||||
|
||||
// Convert commands to workflows
|
||||
const usedCommandNames = new Set<string>()
|
||||
const commandWorkflows = plugin.commands.map((command) =>
|
||||
convertCommandToWorkflow(command, knownAgentNames, usedCommandNames),
|
||||
)
|
||||
|
||||
// Build MCP config
|
||||
const mcpConfig = buildMcpConfig(plugin.mcpServers)
|
||||
|
||||
// Warn about hooks
|
||||
if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
|
||||
console.warn(
|
||||
"Warning: Windsurf has no hooks equivalent. Hooks were skipped during conversion.",
|
||||
)
|
||||
}
|
||||
|
||||
return { agentSkills, commandWorkflows, skillDirs, mcpConfig }
|
||||
}
|
||||
|
||||
function convertAgentToSkill(
|
||||
agent: ClaudeAgent,
|
||||
knownAgentNames: string[],
|
||||
usedNames: Set<string>,
|
||||
): WindsurfGeneratedSkill {
|
||||
const name = uniqueName(normalizeName(agent.name), usedNames)
|
||||
const description = sanitizeDescription(
|
||||
agent.description ?? `Converted from Claude agent ${agent.name}`,
|
||||
)
|
||||
|
||||
let body = transformContentForWindsurf(agent.body.trim(), knownAgentNames)
|
||||
if (agent.capabilities && agent.capabilities.length > 0) {
|
||||
const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
|
||||
body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
|
||||
}
|
||||
if (body.length === 0) {
|
||||
body = `Instructions converted from the ${agent.name} agent.`
|
||||
}
|
||||
|
||||
const content = formatFrontmatter({ name, description }, `# ${name}\n\n${body}`) + "\n"
|
||||
return { name, content }
|
||||
}
|
||||
|
||||
function convertCommandToWorkflow(
|
||||
command: ClaudeCommand,
|
||||
knownAgentNames: string[],
|
||||
usedNames: Set<string>,
|
||||
): WindsurfWorkflow {
|
||||
const name = uniqueName(normalizeName(command.name), usedNames)
|
||||
const description = sanitizeDescription(
|
||||
command.description ?? `Converted from Claude command ${command.name}`,
|
||||
)
|
||||
|
||||
let body = transformContentForWindsurf(command.body.trim(), knownAgentNames)
|
||||
if (command.argumentHint) {
|
||||
body = `> Arguments: ${command.argumentHint}\n\n${body}`
|
||||
}
|
||||
if (body.length === 0) {
|
||||
body = `Instructions converted from the ${command.name} command.`
|
||||
}
|
||||
|
||||
const frontmatter: Record<string, unknown> = { description }
|
||||
const fullContent = formatFrontmatter(frontmatter, `# ${name}\n\n${body}`)
|
||||
if (fullContent.length > WINDSURF_WORKFLOW_CHAR_LIMIT) {
|
||||
console.warn(
|
||||
`Warning: Workflow "${name}" is ${fullContent.length} characters (limit: ${WINDSURF_WORKFLOW_CHAR_LIMIT}). It may be truncated by Windsurf.`,
|
||||
)
|
||||
}
|
||||
|
||||
return { name, description, body }
|
||||
}
|
||||
|
||||
/**
|
||||
* Transform Claude Code content to Windsurf-compatible content.
|
||||
*
|
||||
* 1. Path rewriting: .claude/ -> .windsurf/, ~/.claude/ -> ~/.codeium/windsurf/
|
||||
* 2. Slash command refs: /workflows:plan -> /workflows-plan (Windsurf invokes workflows as /{name})
|
||||
* 3. @agent-name refs: kept as @agent-name (already Windsurf skill invocation syntax)
|
||||
* 4. Task agent calls: Task agent-name(args) -> Use the @agent-name skill: args
|
||||
*/
|
||||
export function transformContentForWindsurf(body: string, knownAgentNames: string[] = []): string {
|
||||
let result = body
|
||||
|
||||
// 1. Rewrite paths
|
||||
result = result.replace(/(?<=^|\s|["'`])~\/\.claude\//gm, "~/.codeium/windsurf/")
|
||||
result = result.replace(/(?<=^|\s|["'`])\.claude\//gm, ".windsurf/")
|
||||
|
||||
// 2. Slash command refs: /workflows:plan -> /workflows-plan (Windsurf invokes as /{name})
|
||||
result = result.replace(/(?<=^|\s)`?\/([a-zA-Z][a-zA-Z0-9_:-]*)`?/gm, (_match, cmdName: string) => {
|
||||
const workflowName = normalizeName(cmdName)
|
||||
return `/${workflowName}`
|
||||
})
|
||||
|
||||
// 3. @agent-name references: no transformation needed.
|
||||
// In Windsurf, @skill-name is the native invocation syntax for skills.
|
||||
// Since agents are now mapped to skills, @agent-name already works correctly.
|
||||
|
||||
// 4. Transform Task agent calls to skill references
|
||||
const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
|
||||
result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
|
||||
return `${prefix}Use the @${normalizeName(agentName)} skill: ${args.trim()}`
|
||||
})
|
||||
|
||||
return result
|
||||
}
|
||||
|
||||
function buildMcpConfig(servers?: Record<string, ClaudeMcpServer>): WindsurfMcpConfig | null {
|
||||
if (!servers || Object.keys(servers).length === 0) return null
|
||||
|
||||
const result: Record<string, WindsurfMcpServerEntry> = {}
|
||||
for (const [name, server] of Object.entries(servers)) {
|
||||
if (server.command) {
|
||||
// stdio transport
|
||||
const entry: WindsurfMcpServerEntry = { command: server.command }
|
||||
if (server.args?.length) entry.args = server.args
|
||||
if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
|
||||
result[name] = entry
|
||||
} else if (server.url) {
|
||||
// HTTP/SSE transport
|
||||
const entry: WindsurfMcpServerEntry = { serverUrl: server.url }
|
||||
if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
|
||||
if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
|
||||
result[name] = entry
|
||||
} else {
|
||||
console.warn(`Warning: MCP server "${name}" has no command or URL. Skipping.`)
|
||||
continue
|
||||
}
|
||||
}
|
||||
|
||||
if (Object.keys(result).length === 0) return null
|
||||
|
||||
// Warn about secrets (don't redact — they're needed for the config to work)
|
||||
const flagged = findServersWithPotentialSecrets(result)
|
||||
if (flagged.length > 0) {
|
||||
console.warn(
|
||||
`Warning: MCP servers contain env vars that may include secrets: ${flagged.join(", ")}.\n` +
|
||||
" These will be written to mcp_config.json. Review before sharing the config file.",
|
||||
)
|
||||
}
|
||||
|
||||
return { mcpServers: result }
|
||||
}
|
||||
|
||||
export function normalizeName(value: string): string {
|
||||
const trimmed = value.trim()
|
||||
if (!trimmed) return "item"
|
||||
let normalized = trimmed
|
||||
.toLowerCase()
|
||||
.replace(/[\\/]+/g, "-")
|
||||
.replace(/[:\s]+/g, "-")
|
||||
.replace(/[^a-z0-9_-]+/g, "-")
|
||||
.replace(/-+/g, "-")
|
||||
.replace(/^-+|-+$/g, "")
|
||||
|
||||
if (normalized.length === 0 || !/^[a-z]/.test(normalized)) {
|
||||
return "item"
|
||||
}
|
||||
|
||||
return normalized
|
||||
}
|
||||
|
||||
function sanitizeDescription(value: string): string {
|
||||
return value.replace(/\s+/g, " ").trim()
|
||||
}
|
||||
|
||||
function uniqueName(base: string, used: Set<string>): string {
|
||||
if (!used.has(base)) {
|
||||
used.add(base)
|
||||
return base
|
||||
}
|
||||
let index = 2
|
||||
while (used.has(`${base}-${index}`)) {
|
||||
index += 1
|
||||
}
|
||||
const name = `${base}-${index}`
|
||||
used.add(name)
|
||||
return name
|
||||
}
|
||||
Reference in New Issue
Block a user