opencastle 0.29.0 → 0.30.1

package/src/cli/pipeline.ts

@@ -1,10 +1,56 @@
-import { readFile } from 'node:fs/promises'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { resolve, dirname } from 'node:path'
+import { stringify } from 'yaml'
 import { c, confirm, closePrompts } from './prompt.js'
-import { runPromptStep } from './plan.js'
+import { runPromptStep, readProjectMcpServers } from './plan.js'
 import type { CliContext } from './types.js'
 
+export interface ConvoyGroup {
+  name: string
+  description: string
+  phases: number[]
+  depends_on: string[]
+}
+
+export interface ComplexityAssessment {
+  total_tasks: number
+  total_phases: number
+  domains: string[]
+  estimated_duration_minutes?: number
+  complexity: 'low' | 'medium' | 'high'
+  recommended_strategy: 'single' | 'chain'
+  chain_rationale?: string
+  convoy_groups: ConvoyGroup[]
+}
+
+export function parseComplexityAssessment(prdContent: string): ComplexityAssessment | null {
+  const sectionMatch = prdContent.match(/## Complexity Assessment\s+([\s\S]*?)(?=\n## |\n# |$)/)
+  if (!sectionMatch) return null
+
+  const sectionContent = sectionMatch[1]
+  const jsonMatch = sectionContent.match(/```json\s*([\s\S]*?)```/)
+  if (!jsonMatch) return null
+
+  try {
+    const parsed = JSON.parse(jsonMatch[1].trim()) as ComplexityAssessment
+    // Validate required fields
+    if (
+      typeof parsed.total_tasks !== 'number' ||
+      typeof parsed.total_phases !== 'number' ||
+      !Array.isArray(parsed.domains) ||
+      !parsed.complexity ||
+      !parsed.recommended_strategy ||
+      !Array.isArray(parsed.convoy_groups)
+    ) {
+      return null
+    }
+    return parsed
+  } catch {
+    return null
+  }
+}
+
 const HELP = `
   opencastle pipeline [options]
 
@@ -12,9 +58,10 @@ const HELP = `
 
     Step 1 — Generate PRD        (generate-prd)
     Step 2 — Validate PRD        (validate-prd)
-    Step 3 — Generate convoy spec (generate-convoy, using PRD as BDO)
-    Step 4 — Validate convoy spec (validate-convoy)
-    Step 5 — Fix convoy spec      (fix-convoy, up to 2 retries if invalid)
+    Step 3 — Fix PRD             (fix-prd, up to 2 retries if invalid)
+    Step 4 — Generate convoy spec (generate-convoy, using PRD as BDO)
+    Step 5 — Validate convoy spec (validate-convoy)
+    Step 6 — Fix convoy spec      (fix-convoy, up to 2 retries if invalid)
 
   Options:
     --text, -t <text>        Feature prompt text (required, unless --prd is set)
@@ -137,11 +184,13 @@ export default async function pipeline({ args, pkgRoot }: CliContext): Promise<v
     }
   }
 
-  const totalSteps = opts.skipValidation ? 3 : 5
+  const totalSteps = opts.skipValidation ? 3 : 6
+  const mcpServers = await readProjectMcpServers(process.cwd())
   const sharedOpts = {
     adapterName: opts.adapter ?? undefined,
     verbose: opts.verbose,
     pkgRoot,
+    ...(mcpServers.length ? { mcpServers } : {}),
   }
 
   console.log(c.bold('\n  opencastle pipeline\n'))
@@ -196,20 +245,254 @@ export default async function pipeline({ args, pkgRoot }: CliContext): Promise<v
     }
 
     if (!result.isValid) {
-      console.log(c.red(`  ✗ PRD validation failed.\n`))
-      console.log(result.errors ?? result.rawOutput)
+      let prdValidationErrors = result.errors ?? result.rawOutput
+      console.log(c.yellow(`  ⚠ PRD has validation issues — attempting auto-fix…\n`))
+      console.log(c.dim(prdValidationErrors))
+      console.log()
+
+      // ── Step 3: Fix PRD (up to 2 retries) ──────────────────────────────────
+      const MAX_PRD_FIX_RETRIES = 2
+      let fixedPrdContent = prdContent
+      let prdFixed = false
+
+      for (let attempt = 1; attempt <= MAX_PRD_FIX_RETRIES; attempt++) {
+        const label = `Fix PRD attempt ${attempt}/${MAX_PRD_FIX_RETRIES}…`
+        console.log(stepLabel(3, totalSteps, label))
+
+        try {
+          await runPromptStep({
+            ...sharedOpts,
+            template: 'fix-prd',
+            goalText: fixedPrdContent,
+            contextText: prdValidationErrors,
+            outputPath: prdPath, // overwrite in place
+          })
+        } catch (err) {
+          console.error(`\n  ✗ Step 3 (attempt ${attempt}) failed: ${err instanceof Error ? err.message : String(err)}`)
+          process.exit(1)
+        }
+
+        console.log(c.dim(`  Re-validating after fix…`))
+
+        fixedPrdContent = await readFile(prdPath, 'utf8')
+
+        let revalidation
+        try {
+          revalidation = await runPromptStep({
+            ...sharedOpts,
+            template: 'validate-prd',
+            goalText: fixedPrdContent,
+          })
+        } catch (err) {
+          console.error(`\n  ✗ Re-validation failed: ${err instanceof Error ? err.message : String(err)}`)
+          process.exit(1)
+        }
+
+        if (revalidation.isValid) {
+          console.log(c.green(`  ✓ PRD fixed and validated\n`))
+          prdFixed = true
+          break
+        }
+
+        prdValidationErrors = revalidation.errors ?? revalidation.rawOutput
+
+        if (attempt < MAX_PRD_FIX_RETRIES) {
+          console.log(c.yellow(`  ⚠ Still has issues after fix attempt ${attempt} — retrying…\n`))
+          console.log(c.dim(prdValidationErrors))
+          console.log()
+        }
+      }
+
+      if (!prdFixed) {
+        console.log(c.red(`\n  ✗ Could not auto-fix the PRD after ${MAX_PRD_FIX_RETRIES} attempts.\n`))
+        console.log(`  Remaining issues:\n`)
+        console.log(prdValidationErrors)
+        console.log(
+          c.dim(`\n  The PRD has been saved to ${relPath(prdPath)} with the best available fixes.\n`) +
+            c.dim(`  Review the remaining issues above and edit the file manually, then re-run with:\n`) +
+            `    opencastle pipeline --prd ${relPath(prdPath)}${opts.adapter ? ` --adapter ${opts.adapter}` : ''}\n`
+        )
+        process.exit(1)
+      }
+    } else {
+      console.log(c.green(`  ✓ PRD is valid\n`))
+    }
+  }
+
+  // ── Complexity-aware strategy decision ────────────────────────────────────
+  const prdContentForComplexity = await readFile(prdPath, 'utf8')
+  const complexity = parseComplexityAssessment(prdContentForComplexity)
+
+  if (complexity) {
+    if (complexity.recommended_strategy === 'chain' && complexity.convoy_groups.length > 1) {
       console.log(
-        c.dim(`\n  Fix the PRD at ${relPath(prdPath)} and re-run with:\n`) +
-          `    opencastle pipeline --prd ${relPath(prdPath)}${opts.adapter ? ` --adapter ${opts.adapter}` : ''}\n`
+        c.cyan(`  ℹ`) +
+          ` Complexity: ${complexity.complexity} | Strategy: chain | ${complexity.convoy_groups.length} convoy groups\n`
+      )
+      console.log(`  Chain plan:`)
+      for (let i = 0; i < complexity.convoy_groups.length; i++) {
+        const g = complexity.convoy_groups[i]
+        const depStr =
+          g.depends_on.length > 0 ? ` → depends on: ${g.depends_on.join(', ')}` : ''
+        console.log(
+          `    ${i + 1}. ${g.name.padEnd(20)} (phases: ${g.phases.join(', ')})${depStr}`
+        )
+      }
+      console.log()
+
+      const convoyDir = resolve(process.cwd(), '.opencastle', 'convoys')
+      await mkdir(convoyDir, { recursive: true })
+
+      const genBaseStep = opts.skipValidation ? 2 : 4
+      const groupSpecPaths: string[] = []
+      const totalGroupSteps =
+        (opts.skipValidation ? 2 : 3) + complexity.convoy_groups.length * (opts.skipValidation ? 1 : 2)
+
+      for (let i = 0; i < complexity.convoy_groups.length; i++) {
+        const group = complexity.convoy_groups[i]
+        const groupStep = genBaseStep + i * (opts.skipValidation ? 1 : 2)
+
+        console.log(
+          stepLabel(
+            groupStep,
+            totalGroupSteps,
+            `Generating convoy spec for group: ${group.name}…`
+          )
+        )
+
+        const chainContext = JSON.stringify({
+          mode: 'chain_subset',
+          group_name: group.name,
+          group_description: group.description,
+          group_phases: group.phases,
+          depends_on_groups: group.depends_on,
+          total_groups: complexity.convoy_groups.length,
+          group_index: i + 1,
+        })
+
+        const groupSpecPath = resolve(convoyDir, `${group.name}.convoy.yml`)
+
+        let groupResult
+        try {
+          groupResult = await runPromptStep({
+            ...sharedOpts,
+            template: 'generate-convoy',
+            filePath: prdPath,
+            contextText: chainContext,
+            outputPath: groupSpecPath,
+          })
+        } catch (err) {
+          console.error(
+            `\n  ✗ Step ${groupStep} failed: ${err instanceof Error ? err.message : String(err)}`
+          )
+          process.exit(1)
+        }
+
+        const resolvedGroupSpecPath = groupResult.outputPath ?? groupSpecPath
+        groupSpecPaths.push(resolvedGroupSpecPath)
+
+        console.log(c.green(`  ✓ Group spec written to ${relPath(resolvedGroupSpecPath)}\n`))
+
+        if (!opts.skipValidation) {
+          const valStep = groupStep + 1
+          console.log(stepLabel(valStep, totalGroupSteps, `Validating spec: ${group.name}…`))
+
+          const groupSpecContent = await readFile(resolvedGroupSpecPath, 'utf8')
+          let groupValidation
+          try {
+            groupValidation = await runPromptStep({
+              ...sharedOpts,
+              template: 'validate-convoy',
+              goalText: groupSpecContent,
+            })
+          } catch (err) {
+            console.error(
+              `\n  ✗ Validation failed for group ${group.name}: ${err instanceof Error ? err.message : String(err)}`
+            )
+            process.exit(1)
+          }
+
+          if (!groupValidation.isValid) {
+            console.log(c.yellow(`  ⚠ Spec has issues — attempting one auto-fix…\n`))
+            console.log(c.dim(groupValidation.errors ?? groupValidation.rawOutput))
+            console.log()
+
+            try {
+              await runPromptStep({
+                ...sharedOpts,
+                template: 'fix-convoy',
+                goalText: groupSpecContent,
+                contextText: groupValidation.errors ?? groupValidation.rawOutput,
+                outputPath: resolvedGroupSpecPath,
+              })
+            } catch (err) {
+              console.error(
+                `\n  ✗ Fix failed for group ${group.name}: ${err instanceof Error ? err.message : String(err)}`
+              )
+              process.exit(1)
+            }
+
+            console.log(c.dim(`  Applied fix for ${group.name}\n`))
+          } else {
+            console.log(c.green(`  ✓ Spec valid\n`))
+          }
+        }
+      }
+
+      // Build master pipeline spec (version 2)
+      const featureNameMatch = prdContentForComplexity.match(/^# (.+?)\s*(?:—|-)?\s*PRD/m)
+      const featureName = featureNameMatch
+        ? featureNameMatch[1].trim().toLowerCase().replace(/[^a-z0-9]+/g, '-')
+        : 'feature'
+
+      const branchMatch = prdContentForComplexity.match(/`feat\/([^`]+)`/)
+      const branch = branchMatch ? `feat/${branchMatch[1]}` : `feat/${featureName}`
+
+      const masterSpec = {
+        name: featureNameMatch ? featureNameMatch[1].trim() : 'Feature Pipeline',
+        version: 2,
+        branch,
+        on_failure: 'stop',
+        depends_on_convoy: groupSpecPaths.map(p => relPath(p)),
+      }
+
+      const masterSpecPath = resolve(convoyDir, `${featureName}-pipeline.convoy.yml`)
+      await writeFile(masterSpecPath, stringify(masterSpec), 'utf8')
+
+      console.log(c.green(`  ✓ Generated convoy chain:\n`))
+      for (const p of groupSpecPaths) {
+        console.log(`    ${relPath(p)}`)
+      }
+      console.log(`    ${relPath(masterSpecPath)} ${c.dim('(master)')}`)
+      console.log()
+      console.log(
+        `  ${c.dim('Preview:')} npx opencastle run -f ${relPath(masterSpecPath)} --dry-run\n` +
+          `  ${c.dim('Execute:')} npx opencastle run -f ${relPath(masterSpecPath)}\n`
       )
-      process.exit(1)
-    }
 
-    console.log(c.green(`  ✓ PRD is valid\n`))
+      try {
+        const shouldRun = await confirm('Run the convoy chain now?', true)
+        if (shouldRun) {
+          closePrompts()
+          const runModule = await import('./run.js')
+          const runArgs = ['-f', masterSpecPath]
+          if (opts.adapter) runArgs.push('-a', opts.adapter)
+          if (opts.verbose) runArgs.push('--verbose')
+          await runModule.default({ args: runArgs, pkgRoot })
+        }
+      } finally {
+        closePrompts()
+      }
+      return
+    } else {
+      console.log(
+        c.cyan(`  ℹ`) + ` Complexity: ${complexity.complexity} | Strategy: single\n`
+      )
+    }
   }
 
-  // ── Step 3: Generate convoy spec ──────────────────────────────────────────
-  const genStep = opts.skipValidation ? 2 : 3
+  // ── Step 4: Generate convoy spec ──────────────────────────────────────────
+  const genStep = opts.skipValidation ? 2 : 4
   console.log(stepLabel(genStep, totalSteps, 'Generating convoy spec…'))
 
   let specPath: string
@@ -233,8 +516,8 @@ export default async function pipeline({ args, pkgRoot }: CliContext): Promise<v
     return
   }
 
-  // ── Step 4: Validate convoy spec ──────────────────────────────────────────
-  console.log(stepLabel(4, totalSteps, 'Validating convoy spec…'))
+  // ── Step 5: Validate convoy spec ──────────────────────────────────────────
+  console.log(stepLabel(5, totalSteps, 'Validating convoy spec…'))
 
   const specContent = await readFile(specPath, 'utf8')
   let validationErrors: string
@@ -248,7 +531,7 @@ export default async function pipeline({ args, pkgRoot }: CliContext): Promise<v
         goalText: specContent,
       })
     } catch (err) {
-      console.error(`\n  ✗ Step 4 failed: ${err instanceof Error ? err.message : String(err)}`)
+      console.error(`\n  ✗ Step 5 failed: ${err instanceof Error ? err.message : String(err)}`)
       process.exit(1)
     }
 
@@ -264,13 +547,13 @@ export default async function pipeline({ args, pkgRoot }: CliContext): Promise<v
     console.log()
   }
 
-  // ── Step 5: Fix convoy spec (up to 2 retries) ─────────────────────────────
+  // ── Step 6: Fix convoy spec (up to 2 retries) ─────────────────────────────
   const MAX_FIX_RETRIES = 2
   let fixedSpecContent = specContent
 
   for (let attempt = 1; attempt <= MAX_FIX_RETRIES; attempt++) {
     const label = `Fix attempt ${attempt}/${MAX_FIX_RETRIES}…`
-    console.log(stepLabel(5, totalSteps, label))
+    console.log(stepLabel(6, totalSteps, label))
 
     let fixResult
     try {
@@ -282,7 +565,7 @@ export default async function pipeline({ args, pkgRoot }: CliContext): Promise<v
         outputPath: specPath, // overwrite in place
       })
     } catch (err) {
-      console.error(`\n  ✗ Step 5 (attempt ${attempt}) failed: ${err instanceof Error ? err.message : String(err)}`)
+      console.error(`\n  ✗ Step 6 (attempt ${attempt}) failed: ${err instanceof Error ? err.message : String(err)}`)
       process.exit(1)
     }
 

package/src/cli/plan.ts

@@ -6,6 +6,7 @@ import { getAdapter, detectAdapter } from './run/adapters/index.js'
 import { parseTaskSpecText } from './run/schema.js'
 import { c } from './prompt.js'
 import type { CliContext, Task } from './types.js'
+import type { MCPServerConfig } from './convoy/types.js'
 
 const HELP = `
   opencastle plan [options]
@@ -66,6 +67,8 @@ export interface PromptStepOptions {
   dryRun?: boolean
   /** Absolute path to the opencastle package root (for locating prompt templates) */
   pkgRoot: string
+  /** MCP servers to make available to the AI adapter during execution. */
+  mcpServers?: MCPServerConfig[]
 }
 
 export interface PromptStepResult {
@@ -221,6 +224,34 @@ function parseValidationResult(output: string): { isValid: boolean; errors: stri
   return { isValid: false, errors: errorsMatch ? errorsMatch[1].trim() : trimmed }
 }
 
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+
+const TEMPLATE_MESSAGES: Record<string, string> = {
+  'generate-prd': 'Generating PRD…',
+  'generate-convoy': 'Generating convoy spec…',
+  'validate-prd': 'Validating PRD…',
+  'validate-convoy': 'Validating convoy spec…',
+  'fix-prd': 'Fixing PRD…',
+  'fix-convoy': 'Fixing convoy spec…',
+}
+
+/** Show an in-place spinner with elapsed time during a long-running adapter call. Returns a stop function. */
+function startProgress(templateName: string): () => void {
+  const message = TEMPLATE_MESSAGES[templateName] ?? `Running ${templateName}…`
+  const startTime = Date.now()
+  let frame = 0
+  const interval = setInterval(() => {
+    const elapsed = Math.floor((Date.now() - startTime) / 1000)
+    const spinner = SPINNER_FRAMES[frame % SPINNER_FRAMES.length]!
+    process.stdout.write(c.dim(`\r  ${spinner} ${message} (${elapsed}s)`))
+    frame++
+  }, 250)
+  return () => {
+    clearInterval(interval)
+    process.stdout.write('\r' + ' '.repeat(60) + '\r')
+  }
+}
+
 // ── Exported programmatic API ───────────────────────────────────────────────
 
 /**
@@ -303,7 +334,16 @@ export async function runPromptStep(opts: PromptStepOptions): Promise<PromptStep
     max_retries: 1,
   }
 
-  const execResult = await adapter.execute(task, { verbose: opts.verbose ?? false })
+  const stop = opts.verbose ? null : startProgress(templateName)
+  let execResult
+  try {
+    execResult = await adapter.execute(task, {
+      verbose: opts.verbose ?? false,
+      ...(opts.mcpServers?.length ? { mcpServers: opts.mcpServers } : {}),
+    })
+  } finally {
+    stop?.()
+  }
   const rawOutput = execResult.output
 
   if (outputType === 'validation') {
@@ -355,6 +395,48 @@ export async function runPromptStep(opts: PromptStepOptions): Promise<PromptStep
   return { outputPath, rawOutput, outputType, isValid: schemaValid }
 }
 
+/**
+ * Read MCP server configurations from the project's MCP config file.
+ * Checks in priority order: .vscode/mcp.json, .cursor/mcp.json, .claude/mcp.json, mcp.json
+ */
+export async function readProjectMcpServers(projectRoot: string): Promise<MCPServerConfig[]> {
+  const candidates = [
+    join(projectRoot, '.vscode', 'mcp.json'),
+    join(projectRoot, '.cursor', 'mcp.json'),
+    join(projectRoot, '.claude', 'mcp.json'),
+    join(projectRoot, 'mcp.json'),
+  ]
+
+  for (const filePath of candidates) {
+    if (!existsSync(filePath)) continue
+    try {
+      const raw = await readFile(filePath, 'utf8')
+      const parsed = JSON.parse(raw) as Record<string, unknown>
+
+      // VS Code format: { servers: { name: { type, command, args } } }
+      // Cursor/Claude format: { mcpServers: { name: { command, args } } }
+      const serversMap =
+        (parsed['servers'] as Record<string, unknown> | undefined) ??
+        (parsed['mcpServers'] as Record<string, unknown> | undefined)
+
+      if (!serversMap || typeof serversMap !== 'object') continue
+
+      return Object.entries(serversMap).map(([name, cfg]) => {
+        const c = cfg as Record<string, unknown>
+        const server: MCPServerConfig = { name, type: (c['type'] as string) ?? 'stdio' }
+        if (typeof c['command'] === 'string') server.command = c['command']
+        if (Array.isArray(c['args'])) server.args = c['args'] as string[]
+        if (typeof c['url'] === 'string') server.url = c['url']
+        return server
+      })
+    } catch {
+      return []
+    }
+  }
+
+  return []
+}
+
 // ── CLI argument parsing ────────────────────────────────────────────────────
 
 function parseArgs(args: string[]): PlanOptions {