opencastle 0.8.0 → 0.8.1

package/src/cli/adapters/opencode.ts

@@ -1,10 +1,4 @@
-import { resolve, basename } from 'node:path'
-import { mkdir, writeFile, readdir, readFile, unlink, rm } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { copyDir, getOrchestratorRoot, getPluginsRoot, getPluginSkillEntries } from '../copy.js'
-import { scaffoldMcpConfig } from '../mcp.js'
-import { getExcludedSkills, getExcludedAgents, getCustomizationsTransform, getIncludedPluginIds } from '../stack-config.js'
-import type { CopyResults, ManagedPaths, RepoInfo, StackConfig } from '../types.js'
+import { createSingleFileAdapter } from './single-file-base.js'
 
 /**
  * OpenCode adapter.
@@ -21,300 +15,17 @@ import type { CopyResults, ManagedPaths, RepoInfo, StackConfig } from '../types.
  */
 
 export const IDE_ID = 'opencode'
-export const IDE_LABEL = 'OpenCode'
 
-// ─── Helpers ──────────────────────────────────────────────────────
+const { install, update, getManagedPaths } = createSingleFileAdapter({
+  rootFile: 'AGENTS.md',
+  dotDir: '.opencode',
+  mcpConfigPath: 'opencode.json',
+  mcpFormat: 'opencode',
+  promptsDir: 'prompts',
+  workflowsDir: 'workflows',
+  workflowPrefix: '',
+  frameworkDirs: ['agents', 'skills', 'prompts', 'workflows'],
+})
 
-function stripFrontmatter(content: string): string {
-  const m = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/)
-  return m ? m[2].trim() : content.trim()
-}
+export { install, update, getManagedPaths }
 
-function parseFrontmatterMeta(content: string): Record<string, string> {
-  const m = content.match(/^---\n([\s\S]*?)\n---/)
-  if (!m) return {}
-  const meta: Record<string, string> = {}
-  for (const line of m[1].split('\n')) {
-    const kv = line.match(/^(\w[\w-]*):\s*['"]?(.+?)['"]?\s*$/)
-    if (kv) meta[kv[1]] = kv[2]
-  }
-  return meta
-}
-
-// ─── Install ──────────────────────────────────────────────────────
-
-export async function install(
-  pkgRoot: string,
-  projectRoot: string,
-  stack?: StackConfig,
-  repoInfo?: RepoInfo
-): Promise<CopyResults> {
-  const srcRoot = getOrchestratorRoot(pkgRoot)
-  const results: CopyResults = { copied: [], skipped: [], created: [] }
-
-  const excludedSkills = stack ? getExcludedSkills(stack) : new Set<string>()
-  const excludedAgents = stack ? getExcludedAgents(stack) : new Set<string>()
-
-  // 1. Build AGENTS.md ← instructions/* + agent index + skill index
-  const agentsMd = resolve(projectRoot, 'AGENTS.md')
-  if (!existsSync(agentsMd)) {
-    const sections: string[] = []
-
-    sections.push(
-      '# Project Instructions\n\n' +
-      'All conventions, architecture, and project context are embedded below. ' +
-      'Skills are in `.opencode/skills/` — read them when a task matches. ' +
-      'Agent definitions are in `.opencode/agents/` — read the relevant file when adopting a persona.'
-    )
-
-    // Always-loaded instruction files
-    const instDir = resolve(srcRoot, 'instructions')
-    if (existsSync(instDir)) {
-      for (const file of (await readdir(instDir)).sort()) {
-        if (!file.endsWith('.md')) continue
-        const content = await readFile(resolve(instDir, file), 'utf8')
-        sections.push(
-          `\n---\n\n<!-- Source: instructions/${file} -->\n\n${stripFrontmatter(content)}`
-        )
-      }
-    }
-
-    // Agent reference
-    const agentsDir = resolve(srcRoot, 'agents')
-    if (existsSync(agentsDir)) {
-      const agentLines: string[] = ['\n---\n\n## Agent Definitions\n']
-      agentLines.push(
-        'The following agent personas are available. Adopt the appropriate persona when asked.\n'
-      )
-      for (const file of (await readdir(agentsDir)).sort()) {
-        if (!file.endsWith('.md')) continue
-        if (excludedAgents.has(file)) continue
-        const meta = parseFrontmatterMeta(
-          await readFile(resolve(agentsDir, file), 'utf8')
-        )
-        const name = meta['name'] ?? basename(file, '.agent.md')
-        const desc = meta['description'] ?? ''
-        agentLines.push(`- **${name}**: ${desc}`)
-      }
-      agentLines.push(
-        '\nFull agent definitions are in `.opencode/agents/`. Read the relevant file when adopting a persona.'
-      )
-      sections.push(agentLines.join('\n'))
-    }
-
-    // Skill index
-    const skillsDir = resolve(srcRoot, 'skills')
-    if (existsSync(skillsDir)) {
-      const skillLines: string[] = ['\n---\n\n## Available Skills\n']
-      skillLines.push(
-        'Skills are on-demand knowledge files. Read the file when the task matches.\n'
-      )
-      const subdirs = (
-        await readdir(skillsDir, { withFileTypes: true })
-      ).filter((e) => e.isDirectory())
-      for (const entry of subdirs.sort((a, b) =>
-        a.name.localeCompare(b.name)
-      )) {
-        if (excludedSkills.has(entry.name)) continue
-        const skillFile = resolve(skillsDir, entry.name, 'SKILL.md')
-        if (!existsSync(skillFile)) continue
-        const meta = parseFrontmatterMeta(await readFile(skillFile, 'utf8'))
-        const desc = meta['description'] ?? ''
-        skillLines.push(
-          `- **${entry.name}** (\`.opencode/skills/${entry.name}.md\`): ${desc}`
-        )
-      }
-
-      // Plugin skills
-      const pluginsRoot = getPluginsRoot(pkgRoot)
-      const includedPlugins = stack ? getIncludedPluginIds(stack) : undefined
-      const pluginEntries = await getPluginSkillEntries(pluginsRoot, includedPlugins)
-      for (const { id, skillPath } of pluginEntries.sort((a, b) => a.id.localeCompare(b.id))) {
-        const pluginMeta = parseFrontmatterMeta(await readFile(skillPath, 'utf8'))
-        const pluginDesc = pluginMeta['description'] ?? ''
-        skillLines.push(
-          `- **${id}** (\`.opencode/skills/${id}.md\`): ${pluginDesc}`
-        )
-      }
-
-      sections.push(skillLines.join('\n'))
-    }
-
-    await writeFile(agentsMd, sections.join('\n') + '\n')
-    results.created.push(agentsMd)
-  } else {
-    results.skipped.push(agentsMd)
-  }
-
-  const openDir = resolve(projectRoot, '.opencode')
-
-  // 2. Agent definitions → .opencode/agents/
-  const agentsDir = resolve(srcRoot, 'agents')
-  if (existsSync(agentsDir)) {
-    const destAgents = resolve(openDir, 'agents')
-    await mkdir(destAgents, { recursive: true })
-    for (const file of await readdir(agentsDir)) {
-      if (!file.endsWith('.md')) continue
-      if (excludedAgents.has(file)) continue
-      const destPath = resolve(destAgents, file)
-      if (existsSync(destPath)) {
-        results.skipped.push(destPath)
-        continue
-      }
-      const content = await readFile(resolve(agentsDir, file), 'utf8')
-      await writeFile(destPath, stripFrontmatter(content) + '\n')
-      results.created.push(destPath)
-    }
-  }
-
-  // 3. Skills → .opencode/skills/<name>.md
-  const skillsDir = resolve(srcRoot, 'skills')
-  if (existsSync(skillsDir)) {
-    const destSkills = resolve(openDir, 'skills')
-    await mkdir(destSkills, { recursive: true })
-    const subdirs = (
-      await readdir(skillsDir, { withFileTypes: true })
-    ).filter((e) => e.isDirectory())
-    for (const entry of subdirs) {
-      if (excludedSkills.has(entry.name)) continue
-      const skillFile = resolve(skillsDir, entry.name, 'SKILL.md')
-      if (!existsSync(skillFile)) continue
-      const destPath = resolve(destSkills, `${entry.name}.md`)
-      if (existsSync(destPath)) {
-        results.skipped.push(destPath)
-        continue
-      }
-      const content = await readFile(skillFile, 'utf8')
-      await writeFile(destPath, stripFrontmatter(content) + '\n')
-      results.created.push(destPath)
-    }
-  }
-
-  // 3b. Plugin skills → .opencode/skills/<plugin-id>.md
-  {
-    const pluginsRoot = getPluginsRoot(pkgRoot)
-    const includedPlugins = stack ? getIncludedPluginIds(stack) : undefined
-    const pluginEntries = await getPluginSkillEntries(pluginsRoot, includedPlugins)
-    const destSkills = resolve(openDir, 'skills')
-    await mkdir(destSkills, { recursive: true })
-    for (const { id, skillPath } of pluginEntries) {
-      const destPath = resolve(destSkills, `${id}.md`)
-      if (existsSync(destPath)) {
-        results.skipped.push(destPath)
-        continue
-      }
-      const content = await readFile(skillPath, 'utf8')
-      await writeFile(destPath, stripFrontmatter(content) + '\n')
-      results.created.push(destPath)
-    }
-  }
-
-  // 4. Prompts → .opencode/prompts/<name>.md
-  const promptDir = resolve(srcRoot, 'prompts')
-  if (existsSync(promptDir)) {
-    const destPrompts = resolve(openDir, 'prompts')
-    await mkdir(destPrompts, { recursive: true })
-    for (const file of await readdir(promptDir)) {
-      if (!file.endsWith('.md')) continue
-      const name = basename(file, '.prompt.md') || basename(file, '.md')
-      const destPath = resolve(destPrompts, `${name}.md`)
-      if (existsSync(destPath)) {
-        results.skipped.push(destPath)
-        continue
-      }
-      const content = await readFile(resolve(promptDir, file), 'utf8')
-      await writeFile(destPath, stripFrontmatter(content) + '\n')
-      results.created.push(destPath)
-    }
-  }
-
-  // 5. Agent Workflows → .opencode/workflows/<name>.md
-  const wfDir = resolve(srcRoot, 'agent-workflows')
-  if (existsSync(wfDir)) {
-    const destWf = resolve(openDir, 'workflows')
-    await mkdir(destWf, { recursive: true })
-    for (const file of await readdir(wfDir)) {
-      if (!file.endsWith('.md')) continue
-      if (file === 'README.md') continue
-      const name = basename(file, '.md')
-      const destPath = resolve(destWf, `${name}.md`)
-      if (existsSync(destPath)) {
-        results.skipped.push(destPath)
-        continue
-      }
-      const content = await readFile(resolve(wfDir, file), 'utf8')
-      await writeFile(destPath, stripFrontmatter(content) + '\n')
-      results.created.push(destPath)
-    }
-  }
-
-  // 6. Customizations (scaffold once, pre-populated with stack choices)
-  const custDir = resolve(srcRoot, 'customizations')
-  if (existsSync(custDir)) {
-    const destCust = resolve(openDir, 'customizations')
-    const custTransform = stack ? getCustomizationsTransform(stack) : undefined
-    const sub = await copyDir(custDir, destCust, { transform: custTransform })
-    results.created.push(...sub.created)
-    results.skipped.push(...sub.skipped)
-  }
-
-  // 7. MCP server config → opencode.json (OpenCode format)
-  const mcpResult = await scaffoldMcpConfig(
-    projectRoot,
-    'opencode.json',
-    stack,
-    repoInfo,
-    'opencode'
-  )
-  results[mcpResult.action].push(mcpResult.path)
-
-  return results
-}
-
-// ─── Update ───────────────────────────────────────────────────────
-
-export async function update(
-  pkgRoot: string,
-  projectRoot: string,
-  stack?: StackConfig
-): Promise<CopyResults> {
-  const results: CopyResults = { copied: [], skipped: [], created: [] }
-  const openDir = resolve(projectRoot, '.opencode')
-
-  // 1. Regenerate AGENTS.md (overwrite)
-  const agentsMd = resolve(projectRoot, 'AGENTS.md')
-  if (existsSync(agentsMd)) {
-    await unlink(agentsMd)
-  }
-
-  // 2. Remove existing framework files so install() recreates them
-  const frameworkDirs = ['agents', 'skills', 'prompts', 'workflows']
-  for (const dir of frameworkDirs) {
-    const dirPath = resolve(openDir, dir)
-    if (existsSync(dirPath)) {
-      await rm(dirPath, { recursive: true })
-    }
-  }
-
-  // 3. Re-run full install
-  const installResult = await install(pkgRoot, projectRoot, stack)
-  results.copied.push(...installResult.created)
-  results.skipped.push(...installResult.skipped)
-
-  return results
-}
-
-// ─── Managed paths ────────────────────────────────────────────────
-
-export function getManagedPaths(): ManagedPaths {
-  return {
-    framework: [
-      'AGENTS.md',
-      '.opencode/agents/',
-      '.opencode/skills/',
-      '.opencode/prompts/',
-      '.opencode/workflows/',
-    ],
-    customizable: ['.opencode/customizations/', 'opencode.json'],
-  }
-}

package/src/cli/adapters/single-file-base.ts

@@ -0,0 +1,320 @@
+import { resolve, basename } from 'node:path'
+import { mkdir, writeFile, readdir, readFile, unlink, rm } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { copyDir, getOrchestratorRoot, getPluginsRoot, getPluginSkillEntries } from '../copy.js'
+import { scaffoldMcpConfig } from '../mcp.js'
+import { getExcludedSkills, getExcludedAgents, getCustomizationsTransform, getIncludedPluginIds } from '../stack-config.js'
+import type { CopyResults, IdeAdapter, IdeChoice, ManagedPaths, RepoInfo, StackConfig } from '../types.js'
+import { stripFrontmatter, parseFrontmatterMeta } from './frontmatter.js'
+
+/**
+ * Configuration for adapters that produce a single root instructions file
+ * and a dot-directory structure (e.g. Claude Code → CLAUDE.md + .claude/,
+ * OpenCode → AGENTS.md + .opencode/).
+ */
+export interface SingleFileAdapterConfig {
+  /** Root instructions file name, e.g. 'CLAUDE.md' */
+  rootFile: string
+  /** Dot directory for framework files, e.g. '.claude' */
+  dotDir: string
+  /** Path for MCP config relative to project root, e.g. '.claude/mcp.json' */
+  mcpConfigPath: string
+  /** MCP format identifier passed to scaffoldMcpConfig */
+  mcpFormat: IdeChoice
+  /** Subdirectory name under dotDir for prompt output, e.g. 'commands' or 'prompts' */
+  promptsDir: string
+  /** Subdirectory name under dotDir for workflow output, e.g. 'commands' or 'workflows' */
+  workflowsDir: string
+  /** Prefix prepended to workflow filenames, e.g. 'workflow-' or '' */
+  workflowPrefix: string
+  /** Framework subdirectories (under dotDir) to remove during update */
+  frameworkDirs: string[]
+}
+
+/**
+ * Creates install/update/getManagedPaths functions from a config object.
+ *
+ * Both Claude Code and OpenCode share the same structure:
+ * 1. A single root .md file with embedded instructions, agent index, and skill index
+ * 2. Agent definitions stripped of frontmatter
+ * 3. Skills stripped of frontmatter
+ * 4. Prompts stripped of frontmatter
+ * 5. Workflows stripped of frontmatter
+ * 6. Customizations scaffolded once
+ * 7. MCP config scaffolded once
+ *
+ * The only differences are directory names and file naming conventions.
+ */
+export function createSingleFileAdapter(config: SingleFileAdapterConfig): IdeAdapter {
+  async function install(
+    pkgRoot: string,
+    projectRoot: string,
+    stack?: StackConfig,
+    repoInfo?: RepoInfo
+  ): Promise<CopyResults> {
+    const srcRoot = getOrchestratorRoot(pkgRoot)
+    const results: CopyResults = { copied: [], skipped: [], created: [] }
+
+    const excludedSkills = stack ? getExcludedSkills(stack) : new Set<string>()
+    const excludedAgents = stack ? getExcludedAgents(stack) : new Set<string>()
+
+    // 1. Build root instructions file
+    const rootPath = resolve(projectRoot, config.rootFile)
+    if (!existsSync(rootPath)) {
+      const sections: string[] = []
+
+      sections.push(
+        '# Project Instructions\n\n' +
+        'All conventions, architecture, and project context are embedded below. ' +
+        `Skills are in \`${config.dotDir}/skills/\` — read them when a task matches. ` +
+        `Agent definitions are in \`${config.dotDir}/agents/\` — read the relevant file when adopting a persona.`
+      )
+
+      // Always-loaded instruction files
+      const instDir = resolve(srcRoot, 'instructions')
+      if (existsSync(instDir)) {
+        for (const file of (await readdir(instDir)).sort()) {
+          if (!file.endsWith('.md')) continue
+          const content = await readFile(resolve(instDir, file), 'utf8')
+          sections.push(
+            `\n---\n\n<!-- Source: instructions/${file} -->\n\n${stripFrontmatter(content)}`
+          )
+        }
+      }
+
+      // Agent reference
+      const agentsDir = resolve(srcRoot, 'agents')
+      if (existsSync(agentsDir)) {
+        const agentLines: string[] = ['\n---\n\n## Agent Definitions\n']
+        agentLines.push(
+          'The following agent personas are available. Adopt the appropriate persona when asked.\n'
+        )
+        for (const file of (await readdir(agentsDir)).sort()) {
+          if (!file.endsWith('.md')) continue
+          if (excludedAgents.has(file)) continue
+          const meta = parseFrontmatterMeta(
+            await readFile(resolve(agentsDir, file), 'utf8')
+          )
+          const name = meta['name'] ?? basename(file, '.agent.md')
+          const desc = meta['description'] ?? ''
+          agentLines.push(`- **${name}**: ${desc}`)
+        }
+        agentLines.push(
+          `\nFull agent definitions are in \`${config.dotDir}/agents/\`. Read the relevant file when adopting a persona.`
+        )
+        sections.push(agentLines.join('\n'))
+      }
+
+      // Skill index
+      const skillsDir = resolve(srcRoot, 'skills')
+      if (existsSync(skillsDir)) {
+        const skillLines: string[] = ['\n---\n\n## Available Skills\n']
+        skillLines.push(
+          'Skills are on-demand knowledge files. Read the file when the task matches.\n'
+        )
+        const subdirs = (
+          await readdir(skillsDir, { withFileTypes: true })
+        ).filter((e) => e.isDirectory())
+        for (const entry of subdirs.sort((a, b) =>
+          a.name.localeCompare(b.name)
+        )) {
+          if (excludedSkills.has(entry.name)) continue
+          const skillFile = resolve(skillsDir, entry.name, 'SKILL.md')
+          if (!existsSync(skillFile)) continue
+          const meta = parseFrontmatterMeta(await readFile(skillFile, 'utf8'))
+          const desc = meta['description'] ?? ''
+          skillLines.push(
+            `- **${entry.name}** (\`${config.dotDir}/skills/${entry.name}.md\`): ${desc}`
+          )
+        }
+
+        // Plugin skills
+        const pluginsRoot = getPluginsRoot(pkgRoot)
+        const includedPlugins = stack ? getIncludedPluginIds(stack) : undefined
+        const pluginEntries = await getPluginSkillEntries(pluginsRoot, includedPlugins)
+        for (const { id, skillPath } of pluginEntries.sort((a, b) => a.id.localeCompare(b.id))) {
+          const pluginMeta = parseFrontmatterMeta(await readFile(skillPath, 'utf8'))
+          const pluginDesc = pluginMeta['description'] ?? ''
+          skillLines.push(
+            `- **${id}** (\`${config.dotDir}/skills/${id}.md\`): ${pluginDesc}`
+          )
+        }
+
+        sections.push(skillLines.join('\n'))
+      }
+
+      await writeFile(rootPath, sections.join('\n') + '\n')
+      results.created.push(rootPath)
+    } else {
+      results.skipped.push(rootPath)
+    }
+
+    const dotDirPath = resolve(projectRoot, config.dotDir)
+
+    // 2. Agent definitions → dotDir/agents/
+    const agentsDir = resolve(srcRoot, 'agents')
+    if (existsSync(agentsDir)) {
+      const destAgents = resolve(dotDirPath, 'agents')
+      await mkdir(destAgents, { recursive: true })
+      for (const file of await readdir(agentsDir)) {
+        if (!file.endsWith('.md')) continue
+        if (excludedAgents.has(file)) continue
+        const destPath = resolve(destAgents, file)
+        if (existsSync(destPath)) {
+          results.skipped.push(destPath)
+          continue
+        }
+        const content = await readFile(resolve(agentsDir, file), 'utf8')
+        await writeFile(destPath, stripFrontmatter(content) + '\n')
+        results.created.push(destPath)
+      }
+    }
+
+    // 3. Skills → dotDir/skills/<name>.md
+    const skillsDir = resolve(srcRoot, 'skills')
+    if (existsSync(skillsDir)) {
+      const destSkills = resolve(dotDirPath, 'skills')
+      await mkdir(destSkills, { recursive: true })
+      const subdirs = (
+        await readdir(skillsDir, { withFileTypes: true })
+      ).filter((e) => e.isDirectory())
+      for (const entry of subdirs) {
+        if (excludedSkills.has(entry.name)) continue
+        const skillFile = resolve(skillsDir, entry.name, 'SKILL.md')
+        if (!existsSync(skillFile)) continue
+        const destPath = resolve(destSkills, `${entry.name}.md`)
+        if (existsSync(destPath)) {
+          results.skipped.push(destPath)
+          continue
+        }
+        const content = await readFile(skillFile, 'utf8')
+        await writeFile(destPath, stripFrontmatter(content) + '\n')
+        results.created.push(destPath)
+      }
+    }
+
+    // 3b. Plugin skills → dotDir/skills/<plugin-id>.md
+    {
+      const pluginsRoot = getPluginsRoot(pkgRoot)
+      const includedPlugins = stack ? getIncludedPluginIds(stack) : undefined
+      const pluginEntries = await getPluginSkillEntries(pluginsRoot, includedPlugins)
+      const destSkills = resolve(dotDirPath, 'skills')
+      await mkdir(destSkills, { recursive: true })
+      for (const { id, skillPath } of pluginEntries) {
+        const destPath = resolve(destSkills, `${id}.md`)
+        if (existsSync(destPath)) {
+          results.skipped.push(destPath)
+          continue
+        }
+        const content = await readFile(skillPath, 'utf8')
+        await writeFile(destPath, stripFrontmatter(content) + '\n')
+        results.created.push(destPath)
+      }
+    }
+
+    // 4. Prompts → dotDir/<promptsDir>/<name>.md
+    const promptDir = resolve(srcRoot, 'prompts')
+    if (existsSync(promptDir)) {
+      const destPrompts = resolve(dotDirPath, config.promptsDir)
+      await mkdir(destPrompts, { recursive: true })
+      for (const file of await readdir(promptDir)) {
+        if (!file.endsWith('.md')) continue
+        const name = basename(file, '.prompt.md') || basename(file, '.md')
+        const destPath = resolve(destPrompts, `${name}.md`)
+        if (existsSync(destPath)) {
+          results.skipped.push(destPath)
+          continue
+        }
+        const content = await readFile(resolve(promptDir, file), 'utf8')
+        await writeFile(destPath, stripFrontmatter(content) + '\n')
+        results.created.push(destPath)
+      }
+    }
+
+    // 5. Agent Workflows → dotDir/<workflowsDir>/<prefix><name>.md
+    const wfDir = resolve(srcRoot, 'agent-workflows')
+    if (existsSync(wfDir)) {
+      const destWf = resolve(dotDirPath, config.workflowsDir)
+      await mkdir(destWf, { recursive: true })
+      for (const file of await readdir(wfDir)) {
+        if (!file.endsWith('.md')) continue
+        if (file === 'README.md') continue
+        const name = basename(file, '.md')
+        const destPath = resolve(destWf, `${config.workflowPrefix}${name}.md`)
+        if (existsSync(destPath)) {
+          results.skipped.push(destPath)
+          continue
+        }
+        const content = await readFile(resolve(wfDir, file), 'utf8')
+        await writeFile(destPath, stripFrontmatter(content) + '\n')
+        results.created.push(destPath)
+      }
+    }
+
+    // 6. Customizations (scaffold once)
+    const custDir = resolve(srcRoot, 'customizations')
+    if (existsSync(custDir)) {
+      const destCust = resolve(dotDirPath, 'customizations')
+      const custTransform = stack ? getCustomizationsTransform(stack) : undefined
+      const sub = await copyDir(custDir, destCust, { transform: custTransform })
+      results.created.push(...sub.created)
+      results.skipped.push(...sub.skipped)
+    }
+
+    // 7. MCP server config (scaffold once)
+    const mcpResult = await scaffoldMcpConfig(
+      projectRoot,
+      config.mcpConfigPath,
+      stack,
+      repoInfo,
+      config.mcpFormat
+    )
+    results[mcpResult.action].push(mcpResult.path)
+
+    return results
+  }
+
+  async function update(
+    pkgRoot: string,
+    projectRoot: string,
+    stack?: StackConfig
+  ): Promise<CopyResults> {
+    const results: CopyResults = { copied: [], skipped: [], created: [] }
+    const dotDirPath = resolve(projectRoot, config.dotDir)
+
+    // 1. Remove root instructions file so install() recreates it
+    const rootPath = resolve(projectRoot, config.rootFile)
+    if (existsSync(rootPath)) {
+      await unlink(rootPath)
+    }
+
+    // 2. Remove existing framework directories
+    for (const dir of config.frameworkDirs) {
+      const dirPath = resolve(dotDirPath, dir)
+      if (existsSync(dirPath)) {
+        await rm(dirPath, { recursive: true })
+      }
+    }
+
+    // 3. Re-run full install
+    const installResult = await install(pkgRoot, projectRoot, stack)
+    results.copied.push(...installResult.created)
+    results.skipped.push(...installResult.skipped)
+
+    return results
+  }
+
+  function getManagedPaths(): ManagedPaths {
+    // Deduplicate dirs (e.g. promptsDir === workflowsDir for claude-code's 'commands')
+    const dirs = new Set(['agents', 'skills', ...config.frameworkDirs])
+    return {
+      framework: [
+        config.rootFile,
+        ...Array.from(dirs).map((d) => `${config.dotDir}/${d}/`),
+      ],
+      customizable: [`${config.dotDir}/customizations/`, config.mcpConfigPath],
+    }
+  }
+
+  return { install, update, getManagedPaths }
+}

package/src/cli/dashboard.ts

@@ -2,7 +2,7 @@ import { createServer } from 'node:http'
 import type { IncomingMessage, ServerResponse, Server } from 'node:http'
 import { readFile, access } from 'node:fs/promises'
 import { resolve, join, extname } from 'node:path'
-import { exec } from 'node:child_process'
+import { execFile } from 'node:child_process'
 import type { CliContext } from './types.js'
 
 const MIME_TYPES: Record<string, string> = {
@@ -22,6 +22,7 @@ const DATA_FILES = [
   'sessions.ndjson',
   'delegations.ndjson',
   'panels.ndjson',
+  'reviews.ndjson',
 ]
 
 interface DashboardArgs {
@@ -57,7 +58,7 @@ function openUrl(url: string): void {
       : plat === 'win32'
         ? 'start'
         : 'xdg-open'
-  exec(`${cmd} ${url}`)
+  execFile(cmd, [url])
 }
 
 async function fileExists(filePath: string): Promise<boolean> {