@every-env/compound-plugin 0.9.0 → 0.12.0

package/src/targets/windsurf.ts

@@ -0,0 +1,104 @@
+import path from "path"
+import { backupFile, copyDir, ensureDir, pathExists, readJson, writeJsonSecure, writeText } from "../utils/files"
+import { formatFrontmatter } from "../utils/frontmatter"
+import type { WindsurfBundle } from "../types/windsurf"
+import type { TargetScope } from "./index"
+
+/**
+ * Write a WindsurfBundle directly into outputRoot.
+ *
+ * Unlike other target writers, this writer expects outputRoot to be the final
+ * resolved directory — the CLI handles scope-based nesting (global vs workspace).
+ */
+export async function writeWindsurfBundle(outputRoot: string, bundle: WindsurfBundle, scope?: TargetScope): Promise<void> {
+  await ensureDir(outputRoot)
+
+  // Write agent skills (before pass-through copies so pass-through takes precedence on collision)
+  if (bundle.agentSkills.length > 0) {
+    const skillsDir = path.join(outputRoot, "skills")
+    await ensureDir(skillsDir)
+    for (const skill of bundle.agentSkills) {
+      validatePathSafe(skill.name, "agent skill")
+      const destDir = path.join(skillsDir, skill.name)
+
+      const resolvedDest = path.resolve(destDir)
+      if (!resolvedDest.startsWith(path.resolve(skillsDir))) {
+        console.warn(`Warning: Agent skill name "${skill.name}" escapes skills/. Skipping.`)
+        continue
+      }
+
+      await ensureDir(destDir)
+      await writeText(path.join(destDir, "SKILL.md"), skill.content)
+    }
+  }
+
+  // Write command workflows (flat in global_workflows/ for global scope, workflows/ for workspace)
+  if (bundle.commandWorkflows.length > 0) {
+    const workflowsDirName = scope === "global" ? "global_workflows" : "workflows"
+    const workflowsDir = path.join(outputRoot, workflowsDirName)
+    await ensureDir(workflowsDir)
+    for (const workflow of bundle.commandWorkflows) {
+      validatePathSafe(workflow.name, "command workflow")
+      const content = formatWorkflowContent(workflow.name, workflow.description, workflow.body)
+      await writeText(path.join(workflowsDir, `${workflow.name}.md`), content)
+    }
+  }
+
+  // Copy pass-through skill directories (after generated skills so copies overwrite on collision)
+  if (bundle.skillDirs.length > 0) {
+    const skillsDir = path.join(outputRoot, "skills")
+    await ensureDir(skillsDir)
+    for (const skill of bundle.skillDirs) {
+      validatePathSafe(skill.name, "skill directory")
+      const destDir = path.join(skillsDir, skill.name)
+
+      const resolvedDest = path.resolve(destDir)
+      if (!resolvedDest.startsWith(path.resolve(skillsDir))) {
+        console.warn(`Warning: Skill name "${skill.name}" escapes skills/. Skipping.`)
+        continue
+      }
+
+      await copyDir(skill.sourceDir, destDir)
+    }
+  }
+
+  // Merge MCP config
+  if (bundle.mcpConfig) {
+    const mcpPath = path.join(outputRoot, "mcp_config.json")
+    const backupPath = await backupFile(mcpPath)
+    if (backupPath) {
+      console.log(`Backed up existing mcp_config.json to ${backupPath}`)
+    }
+
+    let existingConfig: Record<string, unknown> = {}
+    if (await pathExists(mcpPath)) {
+      try {
+        const parsed = await readJson<unknown>(mcpPath)
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          existingConfig = parsed as Record<string, unknown>
+        }
+      } catch {
+        console.warn("Warning: existing mcp_config.json could not be parsed and will be replaced.")
+      }
+    }
+
+    const existingServers =
+      existingConfig.mcpServers &&
+      typeof existingConfig.mcpServers === "object" &&
+      !Array.isArray(existingConfig.mcpServers)
+        ? (existingConfig.mcpServers as Record<string, unknown>)
+        : {}
+    const merged = { ...existingConfig, mcpServers: { ...existingServers, ...bundle.mcpConfig.mcpServers } }
+    await writeJsonSecure(mcpPath, merged)
+  }
+}
+
+function validatePathSafe(name: string, label: string): void {
+  if (name.includes("..") || name.includes("/") || name.includes("\\")) {
+    throw new Error(`${label} name contains unsafe path characters: ${name}`)
+  }
+}
+
+function formatWorkflowContent(name: string, description: string, body: string): string {
+  return formatFrontmatter({ description }, `# ${name}\n\n${body}`) + "\n"
+}

package/src/types/openclaw.ts

@@ -0,0 +1,52 @@
+export type OpenClawPluginManifest = {
+  id: string
+  name: string
+  kind: "tool"
+  configSchema?: {
+    type: "object"
+    additionalProperties: boolean
+    properties: Record<string, OpenClawConfigProperty>
+    required?: string[]
+  }
+  uiHints?: Record<string, OpenClawUiHint>
+  skills?: string[]
+}
+
+export type OpenClawConfigProperty = {
+  type: string
+  description?: string
+  default?: unknown
+}
+
+export type OpenClawUiHint = {
+  label: string
+  sensitive?: boolean
+  placeholder?: string
+}
+
+export type OpenClawSkillFile = {
+  name: string
+  content: string
+  /** Subdirectory path inside skills/ (e.g. "agent-native-reviewer") */
+  dir: string
+}
+
+export type OpenClawCommandRegistration = {
+  name: string
+  description: string
+  acceptsArgs: boolean
+  /** The prompt body that becomes the command handler response */
+  body: string
+}
+
+export type OpenClawBundle = {
+  manifest: OpenClawPluginManifest
+  packageJson: Record<string, unknown>
+  entryPoint: string
+  skills: OpenClawSkillFile[]
+  /** Skill directories to copy verbatim (original Claude skills with references/) */
+  skillDirCopies: { sourceDir: string; name: string }[]
+  commands: OpenClawCommandRegistration[]
+  /** openclaw.json fragment for MCP servers */
+  openclawConfig?: Record<string, unknown>
+}

package/src/types/opencode.ts

@@ -7,7 +7,6 @@ export type OpenCodeConfig = {
   tools?: Record<string, boolean>
   permission?: Record<string, OpenCodePermission | Record<string, OpenCodePermission>>
   agent?: Record<string, OpenCodeAgentConfig>
-  command?: Record<string, OpenCodeCommandConfig>
   mcp?: Record<string, OpenCodeMcpServer>
 }
 
@@ -20,13 +19,6 @@ export type OpenCodeAgentConfig = {
   permission?: Record<string, OpenCodePermission>
 }
 
-export type OpenCodeCommandConfig = {
-  description?: string
-  model?: string
-  agent?: string
-  template: string
-}
-
 export type OpenCodeMcpServer = {
   type: "local" | "remote"
   command?: string[]
@@ -46,9 +38,16 @@ export type OpenCodePluginFile = {
   content: string
 }
 
+export type OpenCodeCommandFile = {
+  name: string
+  content: string
+}
+
 export type OpenCodeBundle = {
   config: OpenCodeConfig
   agents: OpenCodeAgentFile[]
+  // Commands are written as individual .md files, not in opencode.json. See ADR-001.
+  commandFiles: OpenCodeCommandFile[]
   plugins: OpenCodePluginFile[]
   skillDirs: { sourceDir: string; name: string }[]
 }

package/src/types/qwen.ts

@@ -0,0 +1,48 @@
+export type QwenExtensionConfig = {
+  name: string
+  version: string
+  mcpServers?: Record<string, QwenMcpServer>
+  contextFileName?: string
+  commands?: string
+  skills?: string
+  agents?: string
+  settings?: QwenSetting[]
+}
+
+export type QwenMcpServer = {
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+}
+
+export type QwenSetting = {
+  name: string
+  description: string
+  envVar: string
+  sensitive?: boolean
+}
+
+export type QwenAgentFile = {
+  name: string
+  content: string
+  format: "yaml" | "markdown"
+}
+
+export type QwenSkillDir = {
+  sourceDir: string
+  name: string
+}
+
+export type QwenCommandFile = {
+  name: string
+  content: string
+}
+
+export type QwenBundle = {
+  config: QwenExtensionConfig
+  agents: QwenAgentFile[]
+  commandFiles: QwenCommandFile[]
+  skillDirs: QwenSkillDir[]
+  contextFile?: string
+}

package/src/types/windsurf.ts

@@ -0,0 +1,34 @@
+export type WindsurfWorkflow = {
+  name: string
+  description: string
+  body: string
+}
+
+export type WindsurfGeneratedSkill = {
+  name: string
+  content: string
+}
+
+export type WindsurfSkillDir = {
+  name: string
+  sourceDir: string
+}
+
+export type WindsurfMcpServerEntry = {
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  serverUrl?: string
+  headers?: Record<string, string>
+}
+
+export type WindsurfMcpConfig = {
+  mcpServers: Record<string, WindsurfMcpServerEntry>
+}
+
+export type WindsurfBundle = {
+  agentSkills: WindsurfGeneratedSkill[]
+  commandWorkflows: WindsurfWorkflow[]
+  skillDirs: WindsurfSkillDir[]
+  mcpConfig: WindsurfMcpConfig | null
+}

package/src/utils/detect-tools.ts

@@ -0,0 +1,46 @@
+import os from "os"
+import path from "path"
+import { pathExists } from "./files"
+
+export type DetectedTool = {
+  name: string
+  detected: boolean
+  reason: string
+}
+
+export async function detectInstalledTools(
+  home: string = os.homedir(),
+  cwd: string = process.cwd(),
+): Promise<DetectedTool[]> {
+  const checks: Array<{ name: string; paths: string[] }> = [
+    { name: "opencode", paths: [path.join(home, ".config", "opencode"), path.join(cwd, ".opencode")] },
+    { name: "codex", paths: [path.join(home, ".codex")] },
+    { name: "droid", paths: [path.join(home, ".factory")] },
+    { name: "cursor", paths: [path.join(cwd, ".cursor"), path.join(home, ".cursor")] },
+    { name: "pi", paths: [path.join(home, ".pi")] },
+    { name: "gemini", paths: [path.join(cwd, ".gemini"), path.join(home, ".gemini")] },
+  ]
+
+  const results: DetectedTool[] = []
+  for (const check of checks) {
+    let detected = false
+    let reason = "not found"
+    for (const p of check.paths) {
+      if (await pathExists(p)) {
+        detected = true
+        reason = `found ${p}`
+        break
+      }
+    }
+    results.push({ name: check.name, detected, reason })
+  }
+  return results
+}
+
+export async function getDetectedTargetNames(
+  home: string = os.homedir(),
+  cwd: string = process.cwd(),
+): Promise<string[]> {
+  const tools = await detectInstalledTools(home, cwd)
+  return tools.filter((t) => t.detected).map((t) => t.name)
+}

package/src/utils/files.ts

@@ -46,6 +46,13 @@ export async function writeJson(filePath: string, data: unknown): Promise<void>
   await writeText(filePath, content + "\n")
 }
 
+/** Write JSON with restrictive permissions (0o600) for files containing secrets */
+export async function writeJsonSecure(filePath: string, data: unknown): Promise<void> {
+  const content = JSON.stringify(data, null, 2)
+  await ensureDir(path.dirname(filePath))
+  await fs.writeFile(filePath, content + "\n", { encoding: "utf8", mode: 0o600 })
+}
+
 export async function walkFiles(root: string): Promise<string[]> {
   const entries = await fs.readdir(root, { withFileTypes: true })
   const results: string[] = []

package/src/utils/resolve-output.ts

@@ -0,0 +1,50 @@
+import os from "os"
+import path from "path"
+import type { TargetScope } from "../targets"
+
+export function resolveTargetOutputRoot(options: {
+  targetName: string
+  outputRoot: string
+  codexHome: string
+  piHome: string
+  openclawHome?: string
+  qwenHome?: string
+  pluginName?: string
+  hasExplicitOutput: boolean
+  scope?: TargetScope
+}): string {
+  const { targetName, outputRoot, codexHome, piHome, openclawHome, qwenHome, pluginName, hasExplicitOutput, scope } = options
+  if (targetName === "codex") return codexHome
+  if (targetName === "pi") return piHome
+  if (targetName === "droid") return path.join(os.homedir(), ".factory")
+  if (targetName === "cursor") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".cursor")
+  }
+  if (targetName === "gemini") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".gemini")
+  }
+  if (targetName === "copilot") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".github")
+  }
+  if (targetName === "kiro") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".kiro")
+  }
+  if (targetName === "windsurf") {
+    if (hasExplicitOutput) return outputRoot
+    if (scope === "global") return path.join(os.homedir(), ".codeium", "windsurf")
+    return path.join(process.cwd(), ".windsurf")
+  }
+  if (targetName === "openclaw") {
+    const home = openclawHome ?? path.join(os.homedir(), ".openclaw", "extensions")
+    return path.join(home, pluginName ?? "plugin")
+  }
+  if (targetName === "qwen") {
+    const home = qwenHome ?? path.join(os.homedir(), ".qwen", "extensions")
+    return path.join(home, pluginName ?? "plugin")
+  }
+  return outputRoot
+}

package/src/utils/secrets.ts

@@ -0,0 +1,24 @@
+export const SENSITIVE_PATTERN = /key|token|secret|password|credential|api_key/i
+
+/** Check if any MCP servers have env vars that might contain secrets */
+export function hasPotentialSecrets(
+  servers: Record<string, { env?: Record<string, string> }>,
+): boolean {
+  for (const server of Object.values(servers)) {
+    if (server.env) {
+      for (const key of Object.keys(server.env)) {
+        if (SENSITIVE_PATTERN.test(key)) return true
+      }
+    }
+  }
+  return false
+}
+
+/** Return names of MCP servers whose env vars may contain secrets */
+export function findServersWithPotentialSecrets(
+  servers: Record<string, { env?: Record<string, string> }>,
+): string[] {
+  return Object.entries(servers)
+    .filter(([, s]) => s.env && Object.keys(s.env).some((k) => SENSITIVE_PATTERN.test(k)))
+    .map(([name]) => name)
+}

package/tests/cli.test.ts

@@ -426,4 +426,82 @@ describe("CLI", () => {
     expect(await exists(path.join(piRoot, "prompts", "workflows-review.md"))).toBe(true)
     expect(await exists(path.join(piRoot, "extensions", "compound-engineering-compat.ts"))).toBe(true)
   })
+
+  test("install --to opencode uses permissions:none by default", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "cli-perms-none-"))
+    const fixtureRoot = path.join(import.meta.dir, "fixtures", "sample-plugin")
+
+    const proc = Bun.spawn([
+      "bun",
+      "run",
+      "src/index.ts",
+      "install",
+      fixtureRoot,
+      "--to",
+      "opencode",
+      "--output",
+      tempRoot,
+    ], {
+      cwd: path.join(import.meta.dir, ".."),
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+
+    const exitCode = await proc.exited
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+
+    if (exitCode !== 0) {
+      throw new Error(`CLI failed (exit ${exitCode}).\nstdout: ${stdout}\nstderr: ${stderr}`)
+    }
+
+    expect(stdout).toContain("Installed compound-engineering")
+
+    const opencodeJsonPath = path.join(tempRoot, "opencode.json")
+    const content = await fs.readFile(opencodeJsonPath, "utf-8")
+    const json = JSON.parse(content)
+
+    expect(json).not.toHaveProperty("permission")
+    expect(json).not.toHaveProperty("tools")
+  })
+
+  test("install --to opencode --permissions broad writes permission block", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "cli-perms-broad-"))
+    const fixtureRoot = path.join(import.meta.dir, "fixtures", "sample-plugin")
+
+    const proc = Bun.spawn([
+      "bun",
+      "run",
+      "src/index.ts",
+      "install",
+      fixtureRoot,
+      "--to",
+      "opencode",
+      "--permissions",
+      "broad",
+      "--output",
+      tempRoot,
+    ], {
+      cwd: path.join(import.meta.dir, ".."),
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+
+    const exitCode = await proc.exited
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+
+    if (exitCode !== 0) {
+      throw new Error(`CLI failed (exit ${exitCode}).\nstdout: ${stdout}\nstderr: ${stderr}`)
+    }
+
+    expect(stdout).toContain("Installed compound-engineering")
+
+    const opencodeJsonPath = path.join(tempRoot, "opencode.json")
+    const content = await fs.readFile(opencodeJsonPath, "utf-8")
+    const json = JSON.parse(content)
+
+    expect(json).toHaveProperty("permission")
+    expect(json.permission).not.toBeNull()
+  })
 })

package/tests/converter.test.ts

@@ -8,7 +8,7 @@ import type { ClaudePlugin } from "../src/types/claude"
 const fixtureRoot = path.join(import.meta.dir, "fixtures", "sample-plugin")
 
 describe("convertClaudeToOpenCode", () => {
-  test("maps commands, permissions, and agents", async () => {
+  test("from-command mode: map allowedTools to global permission block", async () => {
     const plugin = await loadClaudePlugin(fixtureRoot)
     const bundle = convertClaudeToOpenCode(plugin, {
       agentMode: "subagent",
@@ -16,8 +16,9 @@ describe("convertClaudeToOpenCode", () => {
       permissions: "from-commands",
     })
 
-    expect(bundle.config.command?.["workflows:review"]).toBeDefined()
-    expect(bundle.config.command?.["plan_review"]).toBeDefined()
+    expect(bundle.config.command).toBeUndefined()
+    expect(bundle.commandFiles.find((f) => f.name === "workflows:review")).toBeDefined()
+    expect(bundle.commandFiles.find((f) => f.name === "plan_review")).toBeDefined()
 
     const permission = bundle.config.permission as Record<string, string | Record<string, string>>
     expect(Object.keys(permission).sort()).toEqual([
@@ -71,8 +72,10 @@ describe("convertClaudeToOpenCode", () => {
     expect(parsed.data.model).toBe("anthropic/claude-sonnet-4-20250514")
     expect(parsed.data.temperature).toBe(0.1)
 
-    const modelCommand = bundle.config.command?.["workflows:work"]
-    expect(modelCommand?.model).toBe("openai/gpt-4o")
+    const modelCommand = bundle.commandFiles.find((f) => f.name === "workflows:work")
+    expect(modelCommand).toBeDefined()
+    const commandParsed = parseFrontmatter(modelCommand!.content)
+    expect(commandParsed.data.model).toBe("openai/gpt-4o")
   })
 
   test("resolves bare Claude model aliases to full IDs", () => {
@@ -199,7 +202,7 @@ describe("convertClaudeToOpenCode", () => {
     expect(parsed.data.mode).toBe("primary")
   })
 
-  test("excludes commands with disable-model-invocation from command map", async () => {
+  test("excludes commands with disable-model-invocation from commandFiles", async () => {
     const plugin = await loadClaudePlugin(fixtureRoot)
     const bundle = convertClaudeToOpenCode(plugin, {
       agentMode: "subagent",
@@ -208,10 +211,10 @@ describe("convertClaudeToOpenCode", () => {
     })
 
     // deploy-docs has disable-model-invocation: true, should be excluded
-    expect(bundle.config.command?.["deploy-docs"]).toBeUndefined()
+    expect(bundle.commandFiles.find((f) => f.name === "deploy-docs")).toBeUndefined()
 
     // Normal commands should still be present
-    expect(bundle.config.command?.["workflows:review"]).toBeDefined()
+    expect(bundle.commandFiles.find((f) => f.name === "workflows:review")).toBeDefined()
   })
 
   test("rewrites .claude/ paths to .opencode/ in command bodies", () => {
@@ -240,10 +243,11 @@ Run \`/compound-engineering-setup\` to create a settings file.`,
       permissions: "none",
     })
 
-    const template = bundle.config.command?.["review"]?.template ?? ""
+    const commandFile = bundle.commandFiles.find((f) => f.name === "review")
+    expect(commandFile).toBeDefined()
 
     // Tool-agnostic path in project root — no rewriting needed
-    expect(template).toContain("compound-engineering.local.md")
+    expect(commandFile!.content).toContain("compound-engineering.local.md")
   })
 
   test("rewrites .claude/ paths in agent bodies", () => {
@@ -273,4 +277,33 @@ Run \`/compound-engineering-setup\` to create a settings file.`,
     // Tool-agnostic path in project root — no rewriting needed
     expect(agentFile!.content).toContain("compound-engineering.local.md")
   })
+
+  test("command .md files include description in frontmatter", () => {
+    const plugin: ClaudePlugin = {
+      root: "/tmp/plugin",
+      manifest: { name: "fixture", version: "1.0.0" },
+      agents: [],
+      commands: [
+        {
+          name: "test-cmd",
+          description: "Test description",
+          body: "Do the thing",
+          sourcePath: "/tmp/plugin/commands/test-cmd.md",
+        },
+      ],
+      skills: [],
+    }
+
+    const bundle = convertClaudeToOpenCode(plugin, {
+      agentMode: "subagent",
+      inferTemperature: false,
+      permissions: "none",
+    })
+
+    const commandFile = bundle.commandFiles.find((f) => f.name === "test-cmd")
+    expect(commandFile).toBeDefined()
+    const parsed = parseFrontmatter(commandFile!.content)
+    expect(parsed.data.description).toBe("Test description")
+    expect(parsed.body).toContain("Do the thing")
+  })
 })