compound-engineering-pi 0.2.3

package/src/converters/claude-to-pi.ts

@@ -0,0 +1,205 @@
+import { formatFrontmatter } from "../utils/frontmatter"
+import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
+import type {
+  PiBundle,
+  PiGeneratedSkill,
+  PiMcporterConfig,
+  PiMcporterServer,
+} from "../types/pi"
+import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
+import { PI_COMPAT_EXTENSION_SOURCE } from "../templates/pi/compat-extension"
+
+export type ClaudeToPiOptions = ClaudeToOpenCodeOptions
+
+const PI_DESCRIPTION_MAX_LENGTH = 1024
+
+export function convertClaudeToPi(
+  plugin: ClaudePlugin,
+  _options: ClaudeToPiOptions,
+): PiBundle {
+  const promptNames = new Set<string>()
+  const usedSkillNames = new Set<string>(plugin.skills.map((skill) => normalizeName(skill.name)))
+
+  const prompts = plugin.commands
+    .filter((command) => !command.disableModelInvocation)
+    .map((command) => convertPrompt(command, promptNames))
+
+  const generatedSkills = plugin.agents.map((agent) => convertAgent(agent, usedSkillNames))
+
+  const extensions = [
+    {
+      name: "compound-engineering-compat.ts",
+      content: PI_COMPAT_EXTENSION_SOURCE,
+    },
+  ]
+
+  return {
+    prompts,
+    skillDirs: plugin.skills.map((skill) => ({
+      name: skill.name,
+      sourceDir: skill.sourceDir,
+    })),
+    generatedSkills,
+    extensions,
+    mcporterConfig: plugin.mcpServers ? convertMcpToMcporter(plugin.mcpServers) : undefined,
+  }
+}
+
+function convertPrompt(command: ClaudeCommand, usedNames: Set<string>) {
+  const name = uniqueName(normalizeName(command.name), usedNames)
+  const frontmatter: Record<string, unknown> = {
+    description: command.description,
+    "argument-hint": command.argumentHint,
+  }
+
+  let body = transformContentForPi(command.body)
+  body = appendCompatibilityNoteIfNeeded(body)
+
+  return {
+    name,
+    content: formatFrontmatter(frontmatter, body.trim()),
+  }
+}
+
+function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): PiGeneratedSkill {
+  const name = uniqueName(normalizeName(agent.name), usedNames)
+  const description = sanitizeDescription(
+    agent.description ?? `Converted from Claude agent ${agent.name}`,
+  )
+
+  const frontmatter: Record<string, unknown> = {
+    name,
+    description,
+  }
+
+  const sections: string[] = []
+  if (agent.capabilities && agent.capabilities.length > 0) {
+    sections.push(`## Capabilities\n${agent.capabilities.map((capability) => `- ${capability}`).join("\n")}`)
+  }
+
+  const body = [
+    ...sections,
+    agent.body.trim().length > 0
+      ? agent.body.trim()
+      : `Instructions converted from the ${agent.name} agent.`,
+  ].join("\n\n")
+
+  return {
+    name,
+    content: formatFrontmatter(frontmatter, body),
+  }
+}
+
+function transformContentForPi(body: string): string {
+  let result = body
+
+  // Task repo-research-analyst(feature_description)
+  // -> Run subagent with agent="repo-research-analyst" and task="feature_description"
+  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
+  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
+    const skillName = normalizeName(agentName)
+    const trimmedArgs = args.trim().replace(/\s+/g, " ")
+    return `${prefix}Run subagent with agent=\"${skillName}\" and task=\"${trimmedArgs}\".`
+  })
+
+  // Claude-specific tool references
+  result = result.replace(/\bAskUserQuestion\b/g, "ask_user_question")
+  result = result.replace(/\bTodoWrite\b/g, "file-based todos (todos/ + /skill:file-todos)")
+  result = result.replace(/\bTodoRead\b/g, "file-based todos (todos/ + /skill:file-todos)")
+
+  // /command-name or /workflows:command-name -> /workflows-command-name
+  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
+  result = result.replace(slashCommandPattern, (match, commandName: string) => {
+    if (commandName.includes("/")) return match
+    if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) {
+      return match
+    }
+
+    if (commandName.startsWith("skill:")) {
+      const skillName = commandName.slice("skill:".length)
+      return `/skill:${normalizeName(skillName)}`
+    }
+
+    const withoutPrefix = commandName.startsWith("prompts:")
+      ? commandName.slice("prompts:".length)
+      : commandName
+
+    return `/${normalizeName(withoutPrefix)}`
+  })
+
+  return result
+}
+
+function appendCompatibilityNoteIfNeeded(body: string): string {
+  if (!/\bmcp\b/i.test(body)) return body
+
+  const note = [
+    "",
+    "## Pi + MCPorter note",
+    "For MCP access in Pi, use MCPorter via the generated tools:",
+    "- `mcporter_list` to inspect available MCP tools",
+    "- `mcporter_call` to invoke a tool",
+    "",
+  ].join("\n")
+
+  return body + note
+}
+
+function convertMcpToMcporter(servers: Record<string, ClaudeMcpServer>): PiMcporterConfig {
+  const mcpServers: Record<string, PiMcporterServer> = {}
+
+  for (const [name, server] of Object.entries(servers)) {
+    if (server.command) {
+      mcpServers[name] = {
+        command: server.command,
+        args: server.args,
+        env: server.env,
+        headers: server.headers,
+      }
+      continue
+    }
+
+    if (server.url) {
+      mcpServers[name] = {
+        baseUrl: server.url,
+        headers: server.headers,
+      }
+    }
+  }
+
+  return { mcpServers }
+}
+
+function normalizeName(value: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) return "item"
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[\\/]+/g, "-")
+    .replace(/[:\s]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+  return normalized || "item"
+}
+
+function sanitizeDescription(value: string, maxLength = PI_DESCRIPTION_MAX_LENGTH): string {
+  const normalized = value.replace(/\s+/g, " ").trim()
+  if (normalized.length <= maxLength) return normalized
+  const ellipsis = "..."
+  return normalized.slice(0, Math.max(0, maxLength - ellipsis.length)).trimEnd() + ellipsis
+}
+
+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
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env bun
+import { defineCommand, runMain } from "citty"
+import convert from "./commands/convert"
+import install from "./commands/install"
+import listCommand from "./commands/list"
+import sync from "./commands/sync"
+
+const main = defineCommand({
+  meta: {
+    name: "compound-plugin",
+    version: "0.1.0",
+    description: "Convert Claude Code plugins into other agent formats",
+  },
+  subCommands: {
+    convert: () => convert,
+    install: () => install,
+    list: () => listCommand,
+    sync: () => sync,
+  },
+})
+
+runMain(main)

package/src/parsers/claude-home.ts

@@ -0,0 +1,65 @@
+import path from "path"
+import os from "os"
+import fs from "fs/promises"
+import type { ClaudeSkill, ClaudeMcpServer } from "../types/claude"
+
+export interface ClaudeHomeConfig {
+  skills: ClaudeSkill[]
+  mcpServers: Record<string, ClaudeMcpServer>
+}
+
+export async function loadClaudeHome(claudeHome?: string): Promise<ClaudeHomeConfig> {
+  const home = claudeHome ?? path.join(os.homedir(), ".claude")
+
+  const [skills, mcpServers] = await Promise.all([
+    loadPersonalSkills(path.join(home, "skills")),
+    loadSettingsMcp(path.join(home, "settings.json")),
+  ])
+
+  return { skills, mcpServers }
+}
+
+async function loadPersonalSkills(skillsDir: string): Promise<ClaudeSkill[]> {
+  try {
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true })
+    const skills: ClaudeSkill[] = []
+
+    for (const entry of entries) {
+      // Check if directory or symlink (symlinks are common for skills)
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+
+      const entryPath = path.join(skillsDir, entry.name)
+      const skillPath = path.join(entryPath, "SKILL.md")
+
+      try {
+        await fs.access(skillPath)
+        // Resolve symlink to get the actual source directory
+        const sourceDir = entry.isSymbolicLink()
+          ? await fs.realpath(entryPath)
+          : entryPath
+        skills.push({
+          name: entry.name,
+          sourceDir,
+          skillPath,
+        })
+      } catch {
+        // No SKILL.md, skip
+      }
+    }
+    return skills
+  } catch {
+    return [] // Directory doesn't exist
+  }
+}
+
+async function loadSettingsMcp(
+  settingsPath: string,
+): Promise<Record<string, ClaudeMcpServer>> {
+  try {
+    const content = await fs.readFile(settingsPath, "utf-8")
+    const settings = JSON.parse(content) as { mcpServers?: Record<string, ClaudeMcpServer> }
+    return settings.mcpServers ?? {}
+  } catch {
+    return {} // File doesn't exist or invalid JSON
+  }
+}

package/src/parsers/claude.ts

@@ -0,0 +1,252 @@
+import path from "path"
+import { parseFrontmatter } from "../utils/frontmatter"
+import { readJson, readText, pathExists, walkFiles } from "../utils/files"
+import type {
+  ClaudeAgent,
+  ClaudeCommand,
+  ClaudeHooks,
+  ClaudeManifest,
+  ClaudeMcpServer,
+  ClaudePlugin,
+  ClaudeSkill,
+} from "../types/claude"
+
+const PLUGIN_MANIFEST = path.join(".claude-plugin", "plugin.json")
+
+export async function loadClaudePlugin(inputPath: string): Promise<ClaudePlugin> {
+  const root = await resolveClaudeRoot(inputPath)
+  const manifestPath = path.join(root, PLUGIN_MANIFEST)
+  const manifest = await readJson<ClaudeManifest>(manifestPath)
+
+  const agents = await loadAgents(resolveComponentDirs(root, "agents", manifest.agents))
+  const commands = await loadCommands(resolveComponentDirs(root, "commands", manifest.commands))
+  const skills = await loadSkills(resolveComponentDirs(root, "skills", manifest.skills))
+  const hooks = await loadHooks(root, manifest.hooks)
+
+  const mcpServers = await loadMcpServers(root, manifest)
+
+  return {
+    root,
+    manifest,
+    agents,
+    commands,
+    skills,
+    hooks,
+    mcpServers,
+  }
+}
+
+async function resolveClaudeRoot(inputPath: string): Promise<string> {
+  const absolute = path.resolve(inputPath)
+  const manifestAtPath = path.join(absolute, PLUGIN_MANIFEST)
+  if (await pathExists(manifestAtPath)) {
+    return absolute
+  }
+
+  if (absolute.endsWith(PLUGIN_MANIFEST)) {
+    return path.dirname(path.dirname(absolute))
+  }
+
+  if (absolute.endsWith("plugin.json")) {
+    return path.dirname(path.dirname(absolute))
+  }
+
+  throw new Error(`Could not find ${PLUGIN_MANIFEST} under ${inputPath}`)
+}
+
+async function loadAgents(agentsDirs: string[]): Promise<ClaudeAgent[]> {
+  const files = await collectMarkdownFiles(agentsDirs)
+
+  const agents: ClaudeAgent[] = []
+  for (const file of files) {
+    const raw = await readText(file)
+    const { data, body } = parseFrontmatter(raw)
+    const name = (data.name as string) ?? path.basename(file, ".md")
+    agents.push({
+      name,
+      description: data.description as string | undefined,
+      capabilities: data.capabilities as string[] | undefined,
+      model: data.model as string | undefined,
+      body: body.trim(),
+      sourcePath: file,
+    })
+  }
+  return agents
+}
+
+async function loadCommands(commandsDirs: string[]): Promise<ClaudeCommand[]> {
+  const files = await collectMarkdownFiles(commandsDirs)
+
+  const commands: ClaudeCommand[] = []
+  for (const file of files) {
+    const raw = await readText(file)
+    const { data, body } = parseFrontmatter(raw)
+    const name = (data.name as string) ?? path.basename(file, ".md")
+    const allowedTools = parseAllowedTools(data["allowed-tools"])
+    const disableModelInvocation = data["disable-model-invocation"] === true ? true : undefined
+    commands.push({
+      name,
+      description: data.description as string | undefined,
+      argumentHint: data["argument-hint"] as string | undefined,
+      model: data.model as string | undefined,
+      allowedTools,
+      disableModelInvocation,
+      body: body.trim(),
+      sourcePath: file,
+    })
+  }
+  return commands
+}
+
+async function loadSkills(skillsDirs: string[]): Promise<ClaudeSkill[]> {
+  const entries = await collectFiles(skillsDirs)
+  const skillFiles = entries.filter((file) => path.basename(file) === "SKILL.md")
+  const skills: ClaudeSkill[] = []
+  for (const file of skillFiles) {
+    const raw = await readText(file)
+    const { data } = parseFrontmatter(raw)
+    const name = (data.name as string) ?? path.basename(path.dirname(file))
+    const disableModelInvocation = data["disable-model-invocation"] === true ? true : undefined
+    skills.push({
+      name,
+      description: data.description as string | undefined,
+      disableModelInvocation,
+      sourceDir: path.dirname(file),
+      skillPath: file,
+    })
+  }
+  return skills
+}
+
+async function loadHooks(root: string, hooksField?: ClaudeManifest["hooks"]): Promise<ClaudeHooks | undefined> {
+  const hookConfigs: ClaudeHooks[] = []
+
+  const defaultPath = path.join(root, "hooks", "hooks.json")
+  if (await pathExists(defaultPath)) {
+    hookConfigs.push(await readJson<ClaudeHooks>(defaultPath))
+  }
+
+  if (hooksField) {
+    if (typeof hooksField === "string" || Array.isArray(hooksField)) {
+      const hookPaths = toPathList(hooksField)
+      for (const hookPath of hookPaths) {
+        const resolved = resolveWithinRoot(root, hookPath, "hooks path")
+        if (await pathExists(resolved)) {
+          hookConfigs.push(await readJson<ClaudeHooks>(resolved))
+        }
+      }
+    } else {
+      hookConfigs.push(hooksField)
+    }
+  }
+
+  if (hookConfigs.length === 0) return undefined
+  return mergeHooks(hookConfigs)
+}
+
+async function loadMcpServers(
+  root: string,
+  manifest: ClaudeManifest,
+): Promise<Record<string, ClaudeMcpServer> | undefined> {
+  const field = manifest.mcpServers
+  if (field) {
+    if (typeof field === "string" || Array.isArray(field)) {
+      return mergeMcpConfigs(await loadMcpPaths(root, field))
+    }
+    return field as Record<string, ClaudeMcpServer>
+  }
+
+  const mcpPath = path.join(root, ".mcp.json")
+  if (await pathExists(mcpPath)) {
+    return readJson<Record<string, ClaudeMcpServer>>(mcpPath)
+  }
+
+  return undefined
+}
+
+function parseAllowedTools(value: unknown): string[] | undefined {
+  if (!value) return undefined
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item))
+  }
+  if (typeof value === "string") {
+    return value
+      .split(/,/)
+      .map((item) => item.trim())
+      .filter(Boolean)
+  }
+  return undefined
+}
+
+function resolveComponentDirs(
+  root: string,
+  defaultDir: string,
+  custom?: string | string[],
+): string[] {
+  const dirs = [path.join(root, defaultDir)]
+  for (const entry of toPathList(custom)) {
+    dirs.push(resolveWithinRoot(root, entry, `${defaultDir} path`))
+  }
+  return dirs
+}
+
+function toPathList(value?: string | string[]): string[] {
+  if (!value) return []
+  if (Array.isArray(value)) return value
+  return [value]
+}
+
+async function collectMarkdownFiles(dirs: string[]): Promise<string[]> {
+  const entries = await collectFiles(dirs)
+  return entries.filter((file) => file.endsWith(".md"))
+}
+
+async function collectFiles(dirs: string[]): Promise<string[]> {
+  const files: string[] = []
+  for (const dir of dirs) {
+    if (!(await pathExists(dir))) continue
+    const entries = await walkFiles(dir)
+    files.push(...entries)
+  }
+  return files
+}
+
+function mergeHooks(hooksList: ClaudeHooks[]): ClaudeHooks {
+  const merged: ClaudeHooks = { hooks: {} }
+  for (const hooks of hooksList) {
+    for (const [event, matchers] of Object.entries(hooks.hooks)) {
+      if (!merged.hooks[event]) {
+        merged.hooks[event] = []
+      }
+      merged.hooks[event].push(...matchers)
+    }
+  }
+  return merged
+}
+
+async function loadMcpPaths(
+  root: string,
+  value: string | string[],
+): Promise<Record<string, ClaudeMcpServer>[]> {
+  const configs: Record<string, ClaudeMcpServer>[] = []
+  for (const entry of toPathList(value)) {
+    const resolved = resolveWithinRoot(root, entry, "mcpServers path")
+    if (await pathExists(resolved)) {
+      configs.push(await readJson<Record<string, ClaudeMcpServer>>(resolved))
+    }
+  }
+  return configs
+}
+
+function mergeMcpConfigs(configs: Record<string, ClaudeMcpServer>[]): Record<string, ClaudeMcpServer> {
+  return configs.reduce((acc, config) => ({ ...acc, ...config }), {})
+}
+
+function resolveWithinRoot(root: string, entry: string, label: string): string {
+  const resolvedRoot = path.resolve(root)
+  const resolvedPath = path.resolve(root, entry)
+  if (resolvedPath === resolvedRoot || resolvedPath.startsWith(resolvedRoot + path.sep)) {
+    return resolvedPath
+  }
+  throw new Error(`Invalid ${label}: ${entry}. Paths must stay within the plugin root.`)
+}

package/src/sync/codex.ts

@@ -0,0 +1,92 @@
+import fs from "fs/promises"
+import path from "path"
+import type { ClaudeHomeConfig } from "../parsers/claude-home"
+import type { ClaudeMcpServer } from "../types/claude"
+import { forceSymlink, isValidSkillName } from "../utils/symlink"
+
+export async function syncToCodex(
+  config: ClaudeHomeConfig,
+  outputRoot: string,
+): Promise<void> {
+  // Ensure output directories exist
+  const skillsDir = path.join(outputRoot, "skills")
+  await fs.mkdir(skillsDir, { recursive: true })
+
+  // Symlink skills (with validation)
+  for (const skill of config.skills) {
+    if (!isValidSkillName(skill.name)) {
+      console.warn(`Skipping skill with invalid name: ${skill.name}`)
+      continue
+    }
+    const target = path.join(skillsDir, skill.name)
+    await forceSymlink(skill.sourceDir, target)
+  }
+
+  // Write MCP servers to config.toml (TOML format)
+  if (Object.keys(config.mcpServers).length > 0) {
+    const configPath = path.join(outputRoot, "config.toml")
+    const mcpToml = convertMcpForCodex(config.mcpServers)
+
+    // Read existing config and merge idempotently
+    let existingContent = ""
+    try {
+      existingContent = await fs.readFile(configPath, "utf-8")
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err
+      }
+    }
+
+    // Remove any existing Claude Code MCP section to make idempotent
+    const marker = "# MCP servers synced from Claude Code"
+    const markerIndex = existingContent.indexOf(marker)
+    if (markerIndex !== -1) {
+      existingContent = existingContent.slice(0, markerIndex).trimEnd()
+    }
+
+    const newContent = existingContent
+      ? existingContent + "\n\n" + marker + "\n" + mcpToml
+      : "# Codex config - synced from Claude Code\n\n" + mcpToml
+
+    await fs.writeFile(configPath, newContent, { mode: 0o600 })
+  }
+}
+
+/** Escape a string for TOML double-quoted strings */
+function escapeTomlString(str: string): string {
+  return str
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t")
+}
+
+function convertMcpForCodex(servers: Record<string, ClaudeMcpServer>): string {
+  const sections: string[] = []
+
+  for (const [name, server] of Object.entries(servers)) {
+    if (!server.command) continue
+
+    const lines: string[] = []
+    lines.push(`[mcp_servers.${name}]`)
+    lines.push(`command = "${escapeTomlString(server.command)}"`)
+
+    if (server.args && server.args.length > 0) {
+      const argsStr = server.args.map((arg) => `"${escapeTomlString(arg)}"`).join(", ")
+      lines.push(`args = [${argsStr}]`)
+    }
+
+    if (server.env && Object.keys(server.env).length > 0) {
+      lines.push("")
+      lines.push(`[mcp_servers.${name}.env]`)
+      for (const [key, value] of Object.entries(server.env)) {
+        lines.push(`${key} = "${escapeTomlString(value)}"`)
+      }
+    }
+
+    sections.push(lines.join("\n"))
+  }
+
+  return sections.join("\n\n") + "\n"
+}