opencastle 0.1.0

package/src/cli/adapters/vscode.ts

@@ -0,0 +1,168 @@
+import { resolve } from 'node:path'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { copyDir, getOrchestratorRoot, removeDirIfExists } from '../copy.js'
+import { scaffoldMcpConfig } from '../mcp.js'
+import { getExcludedSkills, getExcludedAgents, getCustomizationsTransform } from '../stack-config.js'
+import type { CopyResults, ManagedPaths, StackConfig } from '../types.js'
+
+/**
+ * VS Code / GitHub Copilot adapter.
+ *
+ * This is the **native format** — the orchestrator source files map 1:1.
+ *
+ *   copilot-instructions.md    → .github/copilot-instructions.md
+ *   agents/                    → .github/agents/
+ *   instructions/              → .github/instructions/
+ *   skills/                    → .github/skills/
+ *   agent-workflows/           → .github/agent-workflows/
+ *   prompts/                   → .github/prompts/
+ *   customizations/            → .github/customizations/  (scaffolded once)
+ */
+
+export const IDE_ID = 'vscode'
+export const IDE_LABEL = 'VS Code (GitHub Copilot)'
+
+/** Directories whose contents are framework-managed (overwritten on update). */
+const FRAMEWORK_DIRS = [
+  'agents',
+  'instructions',
+  'skills',
+  'agent-workflows',
+  'prompts',
+]
+
+/** Directories scaffolded once and never overwritten. */
+const CUSTOMIZABLE_DIRS = ['customizations']
+
+export async function install(
+  pkgRoot: string,
+  projectRoot: string,
+  stack?: StackConfig
+): Promise<CopyResults> {
+  const srcRoot = getOrchestratorRoot(pkgRoot)
+  const destRoot = resolve(projectRoot, '.github')
+
+  await mkdir(destRoot, { recursive: true })
+
+  const results: CopyResults = { copied: [], skipped: [], created: [] }
+
+  const excludedSkills = stack ? getExcludedSkills(stack) : new Set<string>()
+  const excludedAgents = stack ? getExcludedAgents(stack) : new Set<string>()
+
+  // copilot-instructions.md
+  const copilotSrc = resolve(srcRoot, 'copilot-instructions.md')
+  const copilotDest = resolve(destRoot, 'copilot-instructions.md')
+  if (!existsSync(copilotDest)) {
+    await writeFile(copilotDest, await readFile(copilotSrc, 'utf8'))
+    results.created.push(copilotDest)
+  } else {
+    results.skipped.push(copilotDest)
+  }
+
+  // Framework directories
+  for (const dir of FRAMEWORK_DIRS) {
+    const srcDir = resolve(srcRoot, dir)
+    if (!existsSync(srcDir)) continue
+    const destDir = resolve(destRoot, dir)
+
+    // Build filter based on directory type
+    let filter: ((_name: string, _srcPath: string) => boolean) | undefined
+    if (dir === 'skills') {
+      filter = (name) => !excludedSkills.has(name)
+    } else if (dir === 'agents') {
+      filter = (name) => !excludedAgents.has(name)
+    }
+
+    const sub = await copyDir(srcDir, destDir, { filter })
+    results.copied.push(...sub.copied)
+    results.skipped.push(...sub.skipped)
+    results.created.push(...sub.created)
+  }
+
+  // Customization templates (scaffold once)
+  const custTransform = stack ? getCustomizationsTransform(stack) : undefined
+  for (const dir of CUSTOMIZABLE_DIRS) {
+    const srcDir = resolve(srcRoot, dir)
+    if (!existsSync(srcDir)) continue
+    const destDir = resolve(destRoot, dir)
+    const sub = await copyDir(srcDir, destDir, { transform: custTransform })
+    results.copied.push(...sub.copied)
+    results.skipped.push(...sub.skipped)
+    results.created.push(...sub.created)
+  }
+
+  // MCP server config → .vscode/mcp.json (scaffold once)
+  const mcpResult = await scaffoldMcpConfig(
+    pkgRoot,
+    projectRoot,
+    '.vscode/mcp.json',
+    stack
+  )
+  results[mcpResult.action].push(mcpResult.path)
+
+  return results
+}
+
+export async function update(
+  pkgRoot: string,
+  projectRoot: string,
+  stack?: StackConfig
+): Promise<CopyResults> {
+  const srcRoot = getOrchestratorRoot(pkgRoot)
+  const destRoot = resolve(projectRoot, '.github')
+
+  const results: CopyResults = { copied: [], skipped: [], created: [] }
+
+  const excludedSkills = stack ? getExcludedSkills(stack) : new Set<string>()
+  const excludedAgents = stack ? getExcludedAgents(stack) : new Set<string>()
+
+  // Overwrite copilot-instructions.md
+  const copilotDest = resolve(destRoot, 'copilot-instructions.md')
+  await writeFile(
+    copilotDest,
+    await readFile(resolve(srcRoot, 'copilot-instructions.md'), 'utf8')
+  )
+  results.copied.push(copilotDest)
+
+  // Remove existing framework directories to clear stale files
+  for (const dir of FRAMEWORK_DIRS) {
+    await removeDirIfExists(resolve(destRoot, dir))
+  }
+
+  // Re-copy framework directories
+  for (const dir of FRAMEWORK_DIRS) {
+    const srcDir = resolve(srcRoot, dir)
+    if (!existsSync(srcDir)) continue
+    const destDir = resolve(destRoot, dir)
+
+    let filter: ((_name: string, _srcPath: string) => boolean) | undefined
+    if (dir === 'skills') {
+      filter = (name) => !excludedSkills.has(name)
+    } else if (dir === 'agents') {
+      filter = (name) => !excludedAgents.has(name)
+    }
+
+    const sub = await copyDir(srcDir, destDir, { overwrite: true, filter })
+    // All re-installed framework files count as "updated" (copied), not "created"
+    results.copied.push(...sub.copied, ...sub.created)
+    results.skipped.push(...sub.skipped)
+  }
+
+  // Customizations are NEVER overwritten during update.
+
+  return results
+}
+
+export function getManagedPaths(): ManagedPaths {
+  return {
+    framework: [
+      '.github/copilot-instructions.md',
+      ...FRAMEWORK_DIRS.map((d) => `.github/${d}/`),
+    ],
+    customizable: [
+      ...CUSTOMIZABLE_DIRS.map((d) => `.github/${d}/`),
+      '.vscode/mcp.json',
+    ],
+  }
+}

package/src/cli/copy.ts

@@ -0,0 +1,79 @@
+import {
+  readdir,
+  readFile,
+  mkdir,
+  writeFile,
+  copyFile,
+  rm,
+} from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { CopyResults, CopyDirOptions } from './types.js';
+
+/**
+ * Recursively copy a directory tree.
+ */
+export async function copyDir(
+  src: string,
+  dest: string,
+  { overwrite = false, filter, transform }: CopyDirOptions = {}
+): Promise<CopyResults> {
+  const entries = await readdir(src, { withFileTypes: true });
+  await mkdir(dest, { recursive: true });
+
+  const results: CopyResults = { copied: [], skipped: [], created: [] };
+
+  for (const entry of entries) {
+    const srcPath = resolve(src, entry.name);
+    const destPath = resolve(dest, entry.name);
+
+    if (filter && !filter(entry.name, srcPath)) continue;
+
+    if (entry.isDirectory()) {
+      const sub = await copyDir(srcPath, destPath, {
+        overwrite,
+        filter,
+        transform,
+      });
+      results.copied.push(...sub.copied);
+      results.skipped.push(...sub.skipped);
+      results.created.push(...sub.created);
+    } else {
+      const exists = existsSync(destPath);
+      if (exists && !overwrite) {
+        results.skipped.push(destPath);
+        continue;
+      }
+
+      if (transform) {
+        const content = await readFile(srcPath, 'utf8');
+        const transformed = await transform(content, srcPath);
+        if (transformed !== null) {
+          await writeFile(destPath, transformed);
+          results[exists ? 'copied' : 'created'].push(destPath);
+        }
+      } else {
+        await copyFile(srcPath, destPath);
+        results[exists ? 'copied' : 'created'].push(destPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Resolve the orchestrator source directory from the CLI package root.
+ */
+export function getOrchestratorRoot(pkgRoot: string): string {
+  return resolve(pkgRoot, 'src', 'orchestrator');
+}
+
+/**
+ * Remove a directory if it exists. No-op if it doesn't.
+ */
+export async function removeDirIfExists(dirPath: string): Promise<void> {
+  if (existsSync(dirPath)) {
+    await rm(dirPath, { recursive: true });
+  }
+}

package/src/cli/dashboard.ts

@@ -0,0 +1,225 @@
+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 type { CliContext } from './types.js'
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.json': 'application/json',
+  '.ndjson': 'application/x-ndjson',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+}
+
+const DATA_FILES = [
+  'sessions.ndjson',
+  'delegations.ndjson',
+  'panels.ndjson',
+]
+
+interface DashboardArgs {
+  port: number
+  openBrowser: boolean
+  seed: boolean
+}
+
+function parseArgs(args: string[]): DashboardArgs {
+  let port = 4300
+  let openBrowser = true
+  let seed = false
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--port' && args[i + 1]) {
+      port = parseInt(args[i + 1], 10)
+      i++
+    } else if (args[i] === '--no-open') {
+      openBrowser = false
+    } else if (args[i] === '--seed') {
+      seed = true
+    }
+  }
+
+  return { port, openBrowser, seed }
+}
+
+function openUrl(url: string): void {
+  const plat = process.platform
+  const cmd =
+    plat === 'darwin'
+      ? 'open'
+      : plat === 'win32'
+        ? 'start'
+        : 'xdg-open'
+  exec(`${cmd} ${url}`)
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function tryListen(
+  server: Server,
+  port: number,
+  maxAttempts = 10
+): Promise<number> {
+  return new Promise((res, rej) => {
+    let attempt = 0
+
+    function attemptListen(): void {
+      server.listen(port + attempt, '127.0.0.1', () => {
+        res(port + attempt)
+      })
+      server.once('error', (err: Error & { code?: string }) => {
+        if (err.code === 'EADDRINUSE' && attempt < maxAttempts) {
+          attempt++
+          attemptListen()
+        } else {
+          rej(err)
+        }
+      })
+    }
+
+    attemptListen()
+  })
+}
+
+export default async function dashboard({
+  pkgRoot,
+  args,
+}: CliContext): Promise<void> {
+  const { port, openBrowser, seed } = parseArgs(args)
+
+  const distDir = resolve(pkgRoot, 'src', 'dashboard', 'dist')
+  const projectRoot = process.cwd()
+  const logsDir = resolve(projectRoot, '.github', 'customizations', 'logs')
+
+  // Check if dist exists
+  if (!(await fileExists(distDir))) {
+    throw new Error(
+      'Dashboard not built. Run "npm run build:dashboard" in the opencastle package first.'
+    )
+  }
+
+  // Check if any log files exist (for messaging)
+  let hasLogs = false
+  if (!seed) {
+    for (const f of DATA_FILES) {
+      if (await fileExists(join(logsDir, f))) {
+        hasLogs = true
+        break
+      }
+    }
+  }
+
+  const server = createServer(
+    async (req: IncomingMessage, res: ServerResponse) => {
+      try {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host}`)
+        let pathname = decodeURIComponent(url.pathname)
+
+        // Serve index.html for root
+        if (pathname === '/') {
+          pathname = '/index.html'
+        }
+
+        // Handle data file requests — proxy to project logs or dist
+        const dataMatch = pathname.match(/^\/data\/(.+\.ndjson)$/)
+        if (dataMatch && DATA_FILES.includes(dataMatch[1])) {
+          const filename = dataMatch[1]
+          let filePath: string
+
+          if (seed) {
+            filePath = join(distDir, 'data', filename)
+          } else {
+            filePath = join(logsDir, filename)
+          }
+
+          if (await fileExists(filePath)) {
+            const content = await readFile(filePath)
+            res.writeHead(200, { 'Content-Type': 'application/x-ndjson' })
+            res.end(content)
+          } else {
+            // Graceful fallback — empty body
+            res.writeHead(200, { 'Content-Type': 'application/x-ndjson' })
+            res.end('')
+          }
+          return
+        }
+
+        // Serve static files from dist/
+        const filePath = resolve(distDir, pathname.slice(1))
+
+        // Security: prevent path traversal
+        if (!filePath.startsWith(distDir)) {
+          res.writeHead(403)
+          res.end('Forbidden')
+          return
+        }
+
+        if (await fileExists(filePath)) {
+          const ext = extname(filePath)
+          const contentType = MIME_TYPES[ext] ?? 'application/octet-stream'
+          const content = await readFile(filePath)
+          res.writeHead(200, { 'Content-Type': contentType })
+          res.end(content)
+        } else {
+          res.writeHead(404)
+          res.end('Not Found')
+        }
+      } catch {
+        res.writeHead(500)
+        res.end('Internal Server Error')
+      }
+    }
+  )
+
+  const actualPort = await tryListen(server, port)
+  const url = `http://localhost:${actualPort}`
+
+  console.log('')
+  console.log('  \u{1F3F0} OpenCastle Dashboard')
+  console.log('')
+  console.log(`  \u2192 ${url}`)
+
+  if (seed) {
+    console.log(
+      '  \u{1F4C2} Showing demo data (use without --seed to read project logs)'
+    )
+  } else if (hasLogs) {
+    console.log('  \u{1F4C2} Reading logs from .github/customizations/logs/')
+  } else {
+    console.log(
+      '  \u{1F4A1} No agent logs found. Run agents with OpenCastle to generate data, or use --seed for demo data.'
+    )
+  }
+
+  console.log('')
+  console.log('  Press Ctrl+C to stop')
+  console.log('')
+
+  if (openBrowser) {
+    openUrl(url)
+  }
+
+  // Graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\n  Dashboard stopped.\n')
+    server.close()
+    process.exit(0)
+  })
+
+  // Keep the process alive
+  await new Promise<never>(() => {})
+}

package/src/cli/diff.ts

@@ -0,0 +1,44 @@
+import { resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { readManifest } from './manifest.js'
+import type { CliContext } from './types.js'
+
+export default async function diff({ pkgRoot }: CliContext): Promise<void> {
+  const projectRoot = process.cwd()
+
+  const manifest = await readManifest(projectRoot)
+  if (!manifest) {
+    console.error(
+      '  ✗ No OpenCastle installation found. Run "npx opencastle init" first.'
+    )
+    process.exit(1)
+  }
+
+  const pkg = JSON.parse(
+    await readFile(resolve(pkgRoot, 'package.json'), 'utf8')
+  ) as { version: string }
+
+  if (manifest.version === pkg.version) {
+    console.log(
+      `  No changes — installed version matches package version (v${pkg.version}).`
+    )
+    return
+  }
+
+  console.log(
+    `\n  🏰 OpenCastle diff: v${manifest.version} → v${pkg.version}\n`
+  )
+  console.log('  Framework files that would be updated:\n')
+
+  for (const path of manifest.managedPaths?.framework ?? []) {
+    console.log(`    ↻ ${path}`)
+  }
+
+  console.log('\n  Customization files that would be preserved:\n')
+
+  for (const path of manifest.managedPaths?.customizable ?? []) {
+    console.log(`    ✓ ${path}`)
+  }
+
+  console.log(`\n  Run "npx opencastle update" to apply.\n`)
+}

package/src/cli/eject.ts

@@ -0,0 +1,39 @@
+import { resolve } from 'node:path'
+import { unlink } from 'node:fs/promises'
+import { readManifest } from './manifest.js'
+import { confirm, closePrompts } from './prompt.js'
+import type { CliContext } from './types.js'
+
+export default async function eject({
+  pkgRoot: _pkgRoot,
+  args: _args,
+}: CliContext): Promise<void> {
+  const projectRoot = process.cwd()
+
+  const manifest = await readManifest(projectRoot)
+  if (!manifest) {
+    console.error('  ✗ No OpenCastle installation found.')
+    process.exit(1)
+  }
+
+  console.log(`\n  🏰 OpenCastle eject\n`)
+  console.log('  This will:')
+  console.log('    • Remove .opencastle.json (manifest)')
+  console.log('    • Keep ALL generated files as standalone')
+  console.log(
+    '    • You can safely uninstall the opencastle package after this\n'
+  )
+
+  const proceed = await confirm('Continue?')
+  if (!proceed) {
+    console.log('  Aborted.')
+    return
+  }
+
+  await unlink(resolve(projectRoot, '.opencastle.json'))
+
+  console.log('\n  ✓ Ejected. Files are now standalone.')
+  console.log('  You can uninstall: npm uninstall opencastle\n')
+
+  closePrompts()
+}

package/src/cli/init.ts

@@ -0,0 +1,120 @@
+import { resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { select, confirm, closePrompts } from './prompt.js'
+import { readManifest, writeManifest, createManifest } from './manifest.js'
+import type { CliContext, IdeAdapter, CmsChoice, DbChoice, PmChoice, NotifChoice, StackConfig } from './types.js'
+
+const ADAPTERS: Record<string, () => Promise<IdeAdapter>> = {
+  vscode: () => import('./adapters/vscode.js') as Promise<IdeAdapter>,
+  cursor: () => import('./adapters/cursor.js') as Promise<IdeAdapter>,
+  'claude-code': () =>
+    import('./adapters/claude-code.js') as Promise<IdeAdapter>,
+}
+
+export default async function init({ pkgRoot }: CliContext): Promise<void> {
+  const projectRoot = process.cwd()
+
+  // Check for existing installation
+  const existing = await readManifest(projectRoot)
+  if (existing) {
+    const proceed = await confirm(
+      `OpenCastle already installed (v${existing.version}, ${existing.ide}). Re-initialize?`,
+      false
+    )
+    if (!proceed) {
+      console.log('  Aborted.')
+      return
+    }
+  }
+
+  const pkg = JSON.parse(
+    await readFile(resolve(pkgRoot, 'package.json'), 'utf8')
+  ) as { version: string }
+
+  console.log(`\n  🏰 OpenCastle v${pkg.version}`)
+  console.log(
+    '  Multi-agent orchestration framework for AI coding assistants\n'
+  )
+
+  // ── IDE selection ───────────────────────────────────────────────
+  const ide = await select('Which IDE are you using?', [
+    {
+      label: 'VS Code',
+      hint: 'GitHub Copilot — .github/ agents, instructions, skills',
+      value: 'vscode',
+    },
+    {
+      label: 'Cursor',
+      hint: '.cursorrules & .cursor/rules/*.mdc',
+      value: 'cursor',
+    },
+    {
+      label: 'Claude Code',
+      hint: 'CLAUDE.md & .claude/ commands, skills',
+      value: 'claude-code',
+    },
+  ])
+
+  // ── CMS selection ───────────────────────────────────────────────
+  const cms = await select('Which CMS are you using?', [
+    { label: 'Sanity', hint: 'GROQ queries, real-time collaboration', value: 'sanity' },
+    { label: 'Contentful', hint: 'GraphQL / REST API, structured content', value: 'contentful' },
+    { label: 'Strapi', hint: 'Open-source headless CMS', value: 'strapi' },
+    { label: 'None', hint: 'No CMS — skip CMS skills and agents', value: 'none' },
+  ])
+
+  // ── Database selection ──────────────────────────────────────────
+  const db = await select('Which database are you using?', [
+    { label: 'Supabase', hint: 'Postgres + Auth + RLS + Edge Functions', value: 'supabase' },
+    { label: 'Convex', hint: 'Reactive backend with real-time sync', value: 'convex' },
+    { label: 'None', hint: 'No database — skip DB skills and agents', value: 'none' },
+  ])
+
+  // ── Project management selection ────────────────────────────────
+  const pm = await select('Which project management tool are you using?', [
+    { label: 'Linear', hint: 'Issue tracking with MCP integration', value: 'linear' },
+    { label: 'Jira', hint: 'Atlassian issue tracking via Rovo MCP', value: 'jira' },
+    { label: 'None', hint: 'No project management — skip PM skills', value: 'none' },
+  ])
+
+  // ── Notifications selection ────────────────────────────────────
+  const notifications = await select('Which notifications tool are you using?', [
+    { label: 'Slack', hint: 'Agent notifications and bi-directional communication', value: 'slack' },
+    { label: 'Microsoft Teams', hint: 'Agent notifications via Teams channels', value: 'teams' },
+    { label: 'None', hint: 'No notifications — skip messaging skills', value: 'none' },
+  ])
+
+  const stack: StackConfig = { cms: cms as CmsChoice, db: db as DbChoice, pm: pm as PmChoice, notifications: notifications as NotifChoice }
+
+  console.log(`\n  Installing for ${ide}...`)
+  console.log(`  Stack: CMS=${stack.cms}, DB=${stack.db}, PM=${stack.pm}, Notifications=${stack.notifications}\n`)
+
+  // ── Run adapter ─────────────────────────────────────────────────
+  const adapter = await ADAPTERS[ide]()
+  const results = await adapter.install(pkgRoot, projectRoot, stack)
+
+  // ── Write manifest ──────────────────────────────────────────────
+  const manifest = createManifest(pkg.version, ide)
+  manifest.managedPaths = adapter.getManagedPaths()
+  manifest.stack = stack
+  await writeManifest(projectRoot, manifest)
+
+  // ── Summary ─────────────────────────────────────────────────────
+  const created = results.created.length
+  const skipped = results.skipped.length
+
+  console.log(`  ✓ Created ${created} files`)
+  if (skipped > 0) {
+    console.log(`  → Skipped ${skipped} existing files`)
+  }
+
+  console.log(`\n  Next steps:`)
+  console.log(
+    '  1. Run the "Bootstrap Customizations" prompt to configure for your project'
+  )
+  console.log('  2. Customize agent definitions for your tech stack')
+  console.log('  3. Commit the generated files to your repository')
+  console.log()
+
+  closePrompts()
+}