@every-env/compound-plugin 0.1.0

package/src/targets/codex.ts

@@ -0,0 +1,91 @@
+import path from "path"
+import { copyDir, ensureDir, writeText } from "../utils/files"
+import type { CodexBundle } from "../types/codex"
+import type { ClaudeMcpServer } from "../types/claude"
+
+export async function writeCodexBundle(outputRoot: string, bundle: CodexBundle): Promise<void> {
+  const codexRoot = resolveCodexRoot(outputRoot)
+  await ensureDir(codexRoot)
+
+  if (bundle.prompts.length > 0) {
+    const promptsDir = path.join(codexRoot, "prompts")
+    for (const prompt of bundle.prompts) {
+      await writeText(path.join(promptsDir, `${prompt.name}.md`), prompt.content + "\n")
+    }
+  }
+
+  if (bundle.skillDirs.length > 0) {
+    const skillsRoot = path.join(codexRoot, "skills")
+    for (const skill of bundle.skillDirs) {
+      await copyDir(skill.sourceDir, path.join(skillsRoot, skill.name))
+    }
+  }
+
+  if (bundle.generatedSkills.length > 0) {
+    const skillsRoot = path.join(codexRoot, "skills")
+    for (const skill of bundle.generatedSkills) {
+      await writeText(path.join(skillsRoot, skill.name, "SKILL.md"), skill.content + "\n")
+    }
+  }
+
+  const config = renderCodexConfig(bundle.mcpServers)
+  if (config) {
+    await writeText(path.join(codexRoot, "config.toml"), config)
+  }
+}
+
+function resolveCodexRoot(outputRoot: string): string {
+  return path.basename(outputRoot) === ".codex" ? outputRoot : path.join(outputRoot, ".codex")
+}
+
+export function renderCodexConfig(mcpServers?: Record<string, ClaudeMcpServer>): string | null {
+  if (!mcpServers || Object.keys(mcpServers).length === 0) return null
+
+  const lines: string[] = ["# Generated by compound-plugin", ""]
+
+  for (const [name, server] of Object.entries(mcpServers)) {
+    const key = formatTomlKey(name)
+    lines.push(`[mcp_servers.${key}]`)
+
+    if (server.command) {
+      lines.push(`command = ${formatTomlString(server.command)}`)
+      if (server.args && server.args.length > 0) {
+        const args = server.args.map((arg) => formatTomlString(arg)).join(", ")
+        lines.push(`args = [${args}]`)
+      }
+
+      if (server.env && Object.keys(server.env).length > 0) {
+        lines.push("")
+        lines.push(`[mcp_servers.${key}.env]`)
+        for (const [envKey, value] of Object.entries(server.env)) {
+          lines.push(`${formatTomlKey(envKey)} = ${formatTomlString(value)}`)
+        }
+      }
+    } else if (server.url) {
+      lines.push(`url = ${formatTomlString(server.url)}`)
+      if (server.headers && Object.keys(server.headers).length > 0) {
+        lines.push(`http_headers = ${formatTomlInlineTable(server.headers)}`)
+      }
+    }
+
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}
+
+function formatTomlString(value: string): string {
+  return JSON.stringify(value)
+}
+
+function formatTomlKey(value: string): string {
+  if (/^[A-Za-z0-9_-]+$/.test(value)) return value
+  return JSON.stringify(value)
+}
+
+function formatTomlInlineTable(entries: Record<string, string>): string {
+  const parts = Object.entries(entries).map(
+    ([key, value]) => `${formatTomlKey(key)} = ${formatTomlString(value)}`,
+  )
+  return `{ ${parts.join(", ")} }`
+}

package/src/targets/index.ts

@@ -0,0 +1,29 @@
+import type { ClaudePlugin } from "../types/claude"
+import type { OpenCodeBundle } from "../types/opencode"
+import type { CodexBundle } from "../types/codex"
+import { convertClaudeToOpenCode, type ClaudeToOpenCodeOptions } from "../converters/claude-to-opencode"
+import { convertClaudeToCodex } from "../converters/claude-to-codex"
+import { writeOpenCodeBundle } from "./opencode"
+import { writeCodexBundle } from "./codex"
+
+export type TargetHandler<TBundle = unknown> = {
+  name: string
+  implemented: boolean
+  convert: (plugin: ClaudePlugin, options: ClaudeToOpenCodeOptions) => TBundle | null
+  write: (outputRoot: string, bundle: TBundle) => Promise<void>
+}
+
+export const targets: Record<string, TargetHandler> = {
+  opencode: {
+    name: "opencode",
+    implemented: true,
+    convert: convertClaudeToOpenCode,
+    write: writeOpenCodeBundle,
+  },
+  codex: {
+    name: "codex",
+    implemented: true,
+    convert: convertClaudeToCodex as TargetHandler<CodexBundle>["convert"],
+    write: writeCodexBundle as TargetHandler<CodexBundle>["write"],
+  },
+}

package/src/targets/opencode.ts

@@ -0,0 +1,48 @@
+import path from "path"
+import { copyDir, ensureDir, writeJson, writeText } from "../utils/files"
+import type { OpenCodeBundle } from "../types/opencode"
+
+export async function writeOpenCodeBundle(outputRoot: string, bundle: OpenCodeBundle): Promise<void> {
+  const paths = resolveOpenCodePaths(outputRoot)
+  await ensureDir(paths.root)
+  await writeJson(paths.configPath, bundle.config)
+
+  const agentsDir = paths.agentsDir
+  for (const agent of bundle.agents) {
+    await writeText(path.join(agentsDir, `${agent.name}.md`), agent.content + "\n")
+  }
+
+  if (bundle.plugins.length > 0) {
+    const pluginsDir = paths.pluginsDir
+    for (const plugin of bundle.plugins) {
+      await writeText(path.join(pluginsDir, plugin.name), plugin.content + "\n")
+    }
+  }
+
+  if (bundle.skillDirs.length > 0) {
+    const skillsRoot = paths.skillsDir
+    for (const skill of bundle.skillDirs) {
+      await copyDir(skill.sourceDir, path.join(skillsRoot, skill.name))
+    }
+  }
+}
+
+function resolveOpenCodePaths(outputRoot: string) {
+  if (path.basename(outputRoot) === ".opencode") {
+    return {
+      root: outputRoot,
+      configPath: path.join(outputRoot, "opencode.json"),
+      agentsDir: path.join(outputRoot, "agents"),
+      pluginsDir: path.join(outputRoot, "plugins"),
+      skillsDir: path.join(outputRoot, "skills"),
+    }
+  }
+
+  return {
+    root: outputRoot,
+    configPath: path.join(outputRoot, "opencode.json"),
+    agentsDir: path.join(outputRoot, ".opencode", "agents"),
+    pluginsDir: path.join(outputRoot, ".opencode", "plugins"),
+    skillsDir: path.join(outputRoot, ".opencode", "skills"),
+  }
+}

package/src/types/claude.ts

@@ -0,0 +1,88 @@
+export type ClaudeMcpServer = {
+  type?: string
+  command?: string
+  args?: string[]
+  url?: string
+  env?: Record<string, string>
+  headers?: Record<string, string>
+}
+
+export type ClaudeManifest = {
+  name: string
+  version: string
+  description?: string
+  author?: {
+    name?: string
+    email?: string
+    url?: string
+  }
+  keywords?: string[]
+  agents?: string | string[]
+  commands?: string | string[]
+  skills?: string | string[]
+  hooks?: string | string[] | ClaudeHooks
+  mcpServers?: Record<string, ClaudeMcpServer> | string | string[]
+}
+
+export type ClaudeAgent = {
+  name: string
+  description?: string
+  capabilities?: string[]
+  model?: string
+  body: string
+  sourcePath: string
+}
+
+export type ClaudeCommand = {
+  name: string
+  description?: string
+  argumentHint?: string
+  model?: string
+  allowedTools?: string[]
+  body: string
+  sourcePath: string
+}
+
+export type ClaudeSkill = {
+  name: string
+  description?: string
+  sourceDir: string
+  skillPath: string
+}
+
+export type ClaudePlugin = {
+  root: string
+  manifest: ClaudeManifest
+  agents: ClaudeAgent[]
+  commands: ClaudeCommand[]
+  skills: ClaudeSkill[]
+  hooks?: ClaudeHooks
+  mcpServers?: Record<string, ClaudeMcpServer>
+}
+
+export type ClaudeHookCommand = {
+  type: "command"
+  command: string
+  timeout?: number
+}
+
+export type ClaudeHookPrompt = {
+  type: "prompt"
+  prompt: string
+}
+
+export type ClaudeHookAgent = {
+  type: "agent"
+  agent: string
+}
+
+export type ClaudeHookEntry = ClaudeHookCommand | ClaudeHookPrompt | ClaudeHookAgent
+
+export type ClaudeHookMatcher = {
+  matcher: string
+  hooks: ClaudeHookEntry[]
+}
+
+export type ClaudeHooks = {
+  hooks: Record<string, ClaudeHookMatcher[]>
+}

package/src/types/codex.ts

@@ -0,0 +1,23 @@
+import type { ClaudeMcpServer } from "./claude"
+
+export type CodexPrompt = {
+  name: string
+  content: string
+}
+
+export type CodexSkillDir = {
+  name: string
+  sourceDir: string
+}
+
+export type CodexGeneratedSkill = {
+  name: string
+  content: string
+}
+
+export type CodexBundle = {
+  prompts: CodexPrompt[]
+  skillDirs: CodexSkillDir[]
+  generatedSkills: CodexGeneratedSkill[]
+  mcpServers?: Record<string, ClaudeMcpServer>
+}

package/src/types/opencode.ts

@@ -0,0 +1,54 @@
+export type OpenCodePermission = "allow" | "ask" | "deny"
+
+export type OpenCodeConfig = {
+  $schema?: string
+  model?: string
+  default_agent?: string
+  tools?: Record<string, boolean>
+  permission?: Record<string, OpenCodePermission | Record<string, OpenCodePermission>>
+  agent?: Record<string, OpenCodeAgentConfig>
+  command?: Record<string, OpenCodeCommandConfig>
+  mcp?: Record<string, OpenCodeMcpServer>
+}
+
+export type OpenCodeAgentConfig = {
+  description?: string
+  mode?: "primary" | "subagent"
+  model?: string
+  temperature?: number
+  tools?: Record<string, boolean>
+  permission?: Record<string, OpenCodePermission>
+}
+
+export type OpenCodeCommandConfig = {
+  description?: string
+  model?: string
+  agent?: string
+  template: string
+}
+
+export type OpenCodeMcpServer = {
+  type: "local" | "remote"
+  command?: string[]
+  url?: string
+  environment?: Record<string, string>
+  headers?: Record<string, string>
+  enabled?: boolean
+}
+
+export type OpenCodeAgentFile = {
+  name: string
+  content: string
+}
+
+export type OpenCodePluginFile = {
+  name: string
+  content: string
+}
+
+export type OpenCodeBundle = {
+  config: OpenCodeConfig
+  agents: OpenCodeAgentFile[]
+  plugins: OpenCodePluginFile[]
+  skillDirs: { sourceDir: string; name: string }[]
+}

package/src/utils/codex-agents.ts

@@ -0,0 +1,64 @@
+import path from "path"
+import { ensureDir, pathExists, readText, writeText } from "./files"
+
+export const CODEX_AGENTS_BLOCK_START = "<!-- BEGIN COMPOUND CODEX TOOL MAP -->"
+export const CODEX_AGENTS_BLOCK_END = "<!-- END COMPOUND CODEX TOOL MAP -->"
+
+const CODEX_AGENTS_BLOCK_BODY = `## Compound Codex Tool Mapping (Claude Compatibility)
+
+This section maps Claude Code plugin tool references to Codex behavior.
+Only this block is managed automatically.
+
+Tool mapping:
+- Read: use shell reads (cat/sed) or rg
+- Write: create files via shell redirection or apply_patch
+- Edit/MultiEdit: use apply_patch
+- Bash: use shell_command
+- Grep: use rg (fallback: grep)
+- Glob: use rg --files or find
+- LS: use ls via shell_command
+- WebFetch/WebSearch: use curl or Context7 for library docs
+- AskUserQuestion/Question: ask the user in chat
+- Task/Subagent/Parallel: run sequentially in main thread; use multi_tool_use.parallel for tool calls
+- TodoWrite/TodoRead: use file-based todos in todos/ with file-todos skill
+- Skill: open the referenced SKILL.md and follow it
+- ExitPlanMode: ignore
+`
+
+export async function ensureCodexAgentsFile(codexHome: string): Promise<void> {
+  await ensureDir(codexHome)
+  const filePath = path.join(codexHome, "AGENTS.md")
+  const block = buildCodexAgentsBlock()
+
+  if (!(await pathExists(filePath))) {
+    await writeText(filePath, block + "\n")
+    return
+  }
+
+  const existing = await readText(filePath)
+  const updated = upsertBlock(existing, block)
+  if (updated !== existing) {
+    await writeText(filePath, updated)
+  }
+}
+
+function buildCodexAgentsBlock(): string {
+  return [CODEX_AGENTS_BLOCK_START, CODEX_AGENTS_BLOCK_BODY.trim(), CODEX_AGENTS_BLOCK_END].join("\n")
+}
+
+function upsertBlock(existing: string, block: string): string {
+  const startIndex = existing.indexOf(CODEX_AGENTS_BLOCK_START)
+  const endIndex = existing.indexOf(CODEX_AGENTS_BLOCK_END)
+
+  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+    const before = existing.slice(0, startIndex).trimEnd()
+    const after = existing.slice(endIndex + CODEX_AGENTS_BLOCK_END.length).trimStart()
+    return [before, block, after].filter(Boolean).join("\n\n") + "\n"
+  }
+
+  if (existing.trim().length === 0) {
+    return block + "\n"
+  }
+
+  return existing.trimEnd() + "\n\n" + block + "\n"
+}

package/src/utils/files.ts

@@ -0,0 +1,64 @@
+import { promises as fs } from "fs"
+import path from "path"
+
+export async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await fs.mkdir(dirPath, { recursive: true })
+}
+
+export async function readText(filePath: string): Promise<string> {
+  return fs.readFile(filePath, "utf8")
+}
+
+export async function readJson<T>(filePath: string): Promise<T> {
+  const raw = await readText(filePath)
+  return JSON.parse(raw) as T
+}
+
+export async function writeText(filePath: string, content: string): Promise<void> {
+  await ensureDir(path.dirname(filePath))
+  await fs.writeFile(filePath, content, "utf8")
+}
+
+export async function writeJson(filePath: string, data: unknown): Promise<void> {
+  const content = JSON.stringify(data, null, 2)
+  await writeText(filePath, content + "\n")
+}
+
+export async function walkFiles(root: string): Promise<string[]> {
+  const entries = await fs.readdir(root, { withFileTypes: true })
+  const results: string[] = []
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name)
+    if (entry.isDirectory()) {
+      const nested = await walkFiles(fullPath)
+      results.push(...nested)
+    } else if (entry.isFile()) {
+      results.push(fullPath)
+    }
+  }
+  return results
+}
+
+export async function copyDir(sourceDir: string, targetDir: string): Promise<void> {
+  await ensureDir(targetDir)
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true })
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name)
+    const targetPath = path.join(targetDir, entry.name)
+    if (entry.isDirectory()) {
+      await copyDir(sourcePath, targetPath)
+    } else if (entry.isFile()) {
+      await ensureDir(path.dirname(targetPath))
+      await fs.copyFile(sourcePath, targetPath)
+    }
+  }
+}

package/src/utils/frontmatter.ts

@@ -0,0 +1,65 @@
+import { load } from "js-yaml"
+
+export type FrontmatterResult = {
+  data: Record<string, unknown>
+  body: string
+}
+
+export function parseFrontmatter(raw: string): FrontmatterResult {
+  const lines = raw.split(/\r?\n/)
+  if (lines.length === 0 || lines[0].trim() !== "---") {
+    return { data: {}, body: raw }
+  }
+
+  let endIndex = -1
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === "---") {
+      endIndex = i
+      break
+    }
+  }
+
+  if (endIndex === -1) {
+    return { data: {}, body: raw }
+  }
+
+  const yamlText = lines.slice(1, endIndex).join("\n")
+  const body = lines.slice(endIndex + 1).join("\n")
+  const parsed = load(yamlText)
+  const data = (parsed && typeof parsed === "object") ? (parsed as Record<string, unknown>) : {}
+  return { data, body }
+}
+
+export function formatFrontmatter(data: Record<string, unknown>, body: string): string {
+  const yaml = Object.entries(data)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => formatYamlLine(key, value))
+    .join("\n")
+
+  if (yaml.trim().length === 0) {
+    return body
+  }
+
+  return [`---`, yaml, `---`, "", body].join("\n")
+}
+
+function formatYamlLine(key: string, value: unknown): string {
+  if (Array.isArray(value)) {
+    const items = value.map((item) => `  - ${formatYamlValue(item)}`)
+    return [key + ":", ...items].join("\n")
+  }
+  return `${key}: ${formatYamlValue(value)}`
+}
+
+function formatYamlValue(value: unknown): string {
+  if (value === null || value === undefined) return ""
+  if (typeof value === "number" || typeof value === "boolean") return String(value)
+  const raw = String(value)
+  if (raw.includes("\n")) {
+    return `|\n${raw.split("\n").map((line) => `  ${line}`).join("\n")}`
+  }
+  if (raw.includes(":") || raw.startsWith("[") || raw.startsWith("{")) {
+    return JSON.stringify(raw)
+  }
+  return raw
+}

package/tests/claude-parser.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test"
+import path from "path"
+import { loadClaudePlugin } from "../src/parsers/claude"
+
+const fixtureRoot = path.join(import.meta.dir, "fixtures", "sample-plugin")
+const mcpFixtureRoot = path.join(import.meta.dir, "fixtures", "mcp-file")
+const customPathsRoot = path.join(import.meta.dir, "fixtures", "custom-paths")
+const invalidCommandPathRoot = path.join(import.meta.dir, "fixtures", "invalid-command-path")
+const invalidHooksPathRoot = path.join(import.meta.dir, "fixtures", "invalid-hooks-path")
+const invalidMcpPathRoot = path.join(import.meta.dir, "fixtures", "invalid-mcp-path")
+
+describe("loadClaudePlugin", () => {
+  test("loads manifest, agents, commands, skills, hooks", async () => {
+    const plugin = await loadClaudePlugin(fixtureRoot)
+
+    expect(plugin.manifest.name).toBe("compound-engineering")
+    expect(plugin.agents.length).toBe(2)
+    expect(plugin.commands.length).toBe(6)
+    expect(plugin.skills.length).toBe(1)
+    expect(plugin.hooks).toBeDefined()
+    expect(plugin.mcpServers).toBeDefined()
+
+    const researchAgent = plugin.agents.find((agent) => agent.name === "repo-research-analyst")
+    expect(researchAgent?.capabilities).toEqual(["Capability A", "Capability B"])
+
+    const reviewCommand = plugin.commands.find((command) => command.name === "workflows:review")
+    expect(reviewCommand?.allowedTools).toEqual([
+      "Read",
+      "Write",
+      "Edit",
+      "Bash(ls:*)",
+      "Bash(git:*)",
+      "Grep",
+      "Glob",
+      "List",
+      "Patch",
+      "Task",
+    ])
+
+    const planReview = plugin.commands.find((command) => command.name === "plan_review")
+    expect(planReview?.allowedTools).toEqual(["Read", "Edit"])
+
+    const skillCommand = plugin.commands.find((command) => command.name === "create-agent-skill")
+    expect(skillCommand?.allowedTools).toEqual(["Skill(create-agent-skills)"])
+
+    const modelCommand = plugin.commands.find((command) => command.name === "workflows:work")
+    expect(modelCommand?.allowedTools).toEqual(["WebFetch"])
+
+    const patternCommand = plugin.commands.find((command) => command.name === "report-bug")
+    expect(patternCommand?.allowedTools).toEqual(["Read(.env)", "Bash(git:*)"])
+
+    const planCommand = plugin.commands.find((command) => command.name === "workflows:plan")
+    expect(planCommand?.allowedTools).toEqual(["Question", "TodoWrite", "TodoRead"])
+
+    expect(plugin.mcpServers?.context7?.url).toBe("https://mcp.context7.com/mcp")
+  })
+
+  test("loads MCP servers from .mcp.json when manifest is empty", async () => {
+    const plugin = await loadClaudePlugin(mcpFixtureRoot)
+    expect(plugin.mcpServers?.remote?.url).toBe("https://example.com/stream")
+  })
+
+  test("merges default and custom component paths", async () => {
+    const plugin = await loadClaudePlugin(customPathsRoot)
+    expect(plugin.agents.map((agent) => agent.name).sort()).toEqual(["custom-agent", "default-agent"])
+    expect(plugin.commands.map((command) => command.name).sort()).toEqual(["custom-command", "default-command"])
+    expect(plugin.skills.map((skill) => skill.name).sort()).toEqual(["custom-skill", "default-skill"])
+    expect(plugin.hooks?.hooks.PreToolUse?.[0]?.hooks[0]?.command).toBe("echo default")
+    expect(plugin.hooks?.hooks.PostToolUse?.[0]?.hooks[0]?.command).toBe("echo custom")
+  })
+
+  test("rejects custom component paths that escape the plugin root", async () => {
+    await expect(loadClaudePlugin(invalidCommandPathRoot)).rejects.toThrow(
+      "Invalid commands path: ../outside-commands. Paths must stay within the plugin root.",
+    )
+  })
+
+  test("rejects hook paths that escape the plugin root", async () => {
+    await expect(loadClaudePlugin(invalidHooksPathRoot)).rejects.toThrow(
+      "Invalid hooks path: ../outside-hooks.json. Paths must stay within the plugin root.",
+    )
+  })
+
+  test("rejects MCP paths that escape the plugin root", async () => {
+    await expect(loadClaudePlugin(invalidMcpPathRoot)).rejects.toThrow(
+      "Invalid mcpServers path: ../outside-mcp.json. Paths must stay within the plugin root.",
+    )
+  })
+})