opencastle 0.10.7 → 0.12.0

package/src/cli/lesson.ts

@@ -0,0 +1,312 @@
+import { readFile, writeFile, stat } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import type { CliContext } from './types.js'
+
+const CATEGORIES = [
+  'task-management',
+  'jira',
+  'mcp-tools',
+  'codebase-tool',
+  'terminal',
+  'framework',
+  'cms',
+  'database',
+  'git',
+  'deployment',
+  'browser-testing',
+  'general',
+] as const
+
+type Category = (typeof CATEGORIES)[number]
+
+const SEVERITIES = ['high', 'medium', 'low'] as const
+type Severity = (typeof SEVERITIES)[number]
+
+const HELP = `
+  opencastle lesson [options]
+
+  Append a structured lesson to .github/customizations/LESSONS-LEARNED.md
+
+  Required flags:
+    --title <text>           Short descriptive title
+    --category <cat>         One of: ${CATEGORIES.join(', ')}
+    --severity <level>       One of: high, medium, low
+    --problem <text>         What went wrong
+
+  Optional flags:
+    --wrong <text>           The wrong approach that was tried
+    --correct <text>         The correct approach that works
+    --why <text>             Root cause explanation
+    --customizations-dir <p> Override the customizations directory path
+    --help, -h               Show this help
+
+  Examples:
+    opencastle lesson \\
+      --title "Never call foo without bar" \\
+      --category general \\
+      --severity high \\
+      --problem "foo throws on Node 18 without bar"
+
+    opencastle lesson \\
+      --title "Always quote shell variables" \\
+      --category terminal \\
+      --severity medium \\
+      --problem "Unquoted variables break on paths with spaces" \\
+      --wrong 'rm -rf \$DIR/old' \\
+      --correct 'rm -rf "\$DIR/old"' \\
+      --why "Word splitting expands spaces into separate arguments"
+`
+
+function isCategory(s: string): s is Category {
+  return (CATEGORIES as ReadonlyArray<string>).includes(s)
+}
+
+function isSeverity(s: string): s is Severity {
+  return (SEVERITIES as ReadonlyArray<string>).includes(s)
+}
+
+async function resolveCustomizationsDir(override: string | null): Promise<string> {
+  if (override) return override
+  let dir = process.cwd()
+  for (;;) {
+    try {
+      const s = await stat(join(dir, '.github'))
+      if (s.isDirectory()) return join(dir, '.github', 'customizations')
+    } catch {
+      // .github not found here, walk up
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return join(process.cwd(), '.github', 'customizations')
+}
+
+function nextLessonId(content: string): string {
+  const matches = [...content.matchAll(/^### LES-(\d+)/gm)]
+  if (matches.length === 0) return 'LES-001'
+  const last = Math.max(...matches.map((m) => parseInt(m[1], 10)))
+  return `LES-${String(last + 1).padStart(3, '0')}`
+}
+
+function escapeMarkdown(s: string): string {
+  return s.replace(/\|/g, '\\|').replace(/[\n\r]/g, ' ')
+}
+
+function formatLesson(opts: {
+  id: string
+  title: string
+  category: Category
+  severity: Severity
+  date: string
+  problem: string
+  wrong?: string
+  correct?: string
+  why?: string
+}): string {
+  const title = opts.title.replace(/[\n\r]/g, ' ')
+  const lines: string[] = [
+    `### ${opts.id}: ${title}`,
+    '',
+    '| Field | Value |',
+    '|-------|-------|',
+    `| **Category** | \`${opts.category}\` |`,
+    `| **Added** | ${opts.date} |`,
+    `| **Severity** | \`${opts.severity}\` |`,
+    '',
+    `**Problem:** ${escapeMarkdown(opts.problem)}`,
+  ]
+  if (opts.wrong !== undefined) lines.push('', `**Wrong approach:** ${escapeMarkdown(opts.wrong)}`)
+  if (opts.correct !== undefined) lines.push('', `**Correct approach:** ${escapeMarkdown(opts.correct)}`)
+  if (opts.why !== undefined) lines.push('', `**Why:** ${escapeMarkdown(opts.why)}`)
+  return lines.join('\n')
+}
+
+function insertLesson(content: string, block: string): string {
+  const marker = '\n## Index by Category'
+  const idx = content.indexOf(marker)
+  if (idx === -1) {
+    return content.trimEnd() + '\n\n' + block + '\n'
+  }
+  // Insert block right before the \n## Index sequence
+  return content.slice(0, idx) + '\n' + block + '\n' + content.slice(idx)
+}
+
+function updateIndex(content: string, category: string, lessonId: string): string {
+  const lines = content.split('\n')
+  let found = false
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\| `([^`]+)` \| (.+) \|$/)
+    if (m && m[1] === category) {
+      const current = m[2].trim()
+      const updated = current === '\u2014' ? lessonId : `${current}, ${lessonId}`
+      lines[i] = `| \`${category}\` | ${updated} |`
+      found = true
+      break
+    }
+  }
+
+  if (!found) {
+    // Row doesn't exist — append after the last table row in the Index section
+    const indexHeading = lines.findIndex((l) => l.trim() === '## Index by Category')
+    if (indexHeading !== -1) {
+      let lastTableRow = -1
+      for (let i = indexHeading; i < lines.length; i++) {
+        if (lines[i].startsWith('|')) lastTableRow = i
+        else if (lastTableRow > indexHeading && lines[i].trim() !== '') break
+      }
+      if (lastTableRow !== -1) {
+        lines.splice(lastTableRow + 1, 0, `| \`${category}\` | ${lessonId} |`)
+      }
+    }
+  }
+
+  return lines.join('\n')
+}
+
+export interface LessonInput {
+  title: string
+  category: string
+  severity: string
+  problem: string
+  wrong?: string
+  correct?: string
+  why?: string
+}
+
+/**
+ * Append a structured lesson to LESSONS-LEARNED.md programmatically.
+ * Returns the generated lesson ID (e.g., "LES-005").
+ */
+export async function appendLesson(
+  input: LessonInput,
+  customizationsDir?: string | null,
+): Promise<string> {
+  if (!isCategory(input.category)) {
+    throw new Error(`Invalid category "${input.category}". Must be one of: ${CATEGORIES.join(', ')}`)
+  }
+  if (!isSeverity(input.severity)) {
+    throw new Error(`Invalid severity "${input.severity}". Must be one of: ${SEVERITIES.join(', ')}`)
+  }
+  const category = input.category
+  const severity = input.severity
+
+  const resolvedDir = await resolveCustomizationsDir(customizationsDir ?? null)
+  const lessonsFile = join(resolvedDir, 'LESSONS-LEARNED.md')
+
+  let content: string
+  try {
+    content = await readFile(lessonsFile, 'utf8')
+  } catch {
+    throw new Error(`LESSONS-LEARNED.md not found at: ${lessonsFile}`)
+  }
+
+  const id = nextLessonId(content)
+  const date = new Date().toISOString().slice(0, 10)
+
+  const block = formatLesson({
+    id,
+    title: input.title,
+    category,
+    severity,
+    date,
+    problem: input.problem,
+    wrong: input.wrong,
+    correct: input.correct,
+    why: input.why,
+  })
+
+  let updated = insertLesson(content, block)
+  updated = updateIndex(updated, category, id)
+
+  await writeFile(lessonsFile, updated, 'utf8')
+  return id
+}
+
+export default async function lesson({ args }: CliContext): Promise<void> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(HELP)
+    return
+  }
+
+  let title: string | null = null
+  let category: string | null = null
+  let severity: string | null = null
+  let problem: string | null = null
+  let wrong: string | undefined
+  let correct: string | undefined
+  let why: string | undefined
+  let customizationsDir: string | null = null
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    switch (a) {
+      case '--title':
+        if (i + 1 >= args.length) { console.error('  \u2717 --title requires a value'); process.exit(1) }
+        title = args[++i]
+        break
+      case '--category':
+        if (i + 1 >= args.length) { console.error('  \u2717 --category requires a value'); process.exit(1) }
+        category = args[++i]
+        break
+      case '--severity':
+        if (i + 1 >= args.length) { console.error('  \u2717 --severity requires a value'); process.exit(1) }
+        severity = args[++i]
+        break
+      case '--problem':
+        if (i + 1 >= args.length) { console.error('  \u2717 --problem requires a value'); process.exit(1) }
+        problem = args[++i]
+        break
+      case '--wrong':
+        if (i + 1 >= args.length) { console.error('  \u2717 --wrong requires a value'); process.exit(1) }
+        wrong = args[++i]
+        break
+      case '--correct':
+        if (i + 1 >= args.length) { console.error('  \u2717 --correct requires a value'); process.exit(1) }
+        correct = args[++i]
+        break
+      case '--why':
+        if (i + 1 >= args.length) { console.error('  \u2717 --why requires a value'); process.exit(1) }
+        why = args[++i]
+        break
+      case '--customizations-dir':
+        if (i + 1 >= args.length) { console.error('  \u2717 --customizations-dir requires a path'); process.exit(1) }
+        customizationsDir = args[++i]
+        break
+    }
+  }
+
+  const missing: string[] = []
+  if (!title) missing.push('--title')
+  if (!category) missing.push('--category')
+  if (!severity) missing.push('--severity')
+  if (!problem) missing.push('--problem')
+
+  if (missing.length > 0) {
+    console.error(`  \u2717 Missing required flags: ${missing.join(', ')}`)
+    console.error('  Run "opencastle lesson --help" for usage.')
+    process.exit(1)
+  }
+
+  if (!isCategory(category!)) {
+    console.error(`  \u2717 Invalid --category "${category}". Must be one of: ${CATEGORIES.join(', ')}`)
+    process.exit(1)
+  }
+
+  if (!isSeverity(severity!)) {
+    console.error(`  \u2717 Invalid --severity "${severity}". Must be one of: ${SEVERITIES.join(', ')}`)
+    process.exit(1)
+  }
+
+  try {
+    const id = await appendLesson(
+      { title: title!, category: category!, severity: severity!, problem: problem!, wrong, correct, why },
+      customizationsDir,
+    )
+    console.log(`${id}: ${title}`)
+  } catch (err: unknown) {
+    console.error(`  \u2717 ${(err as Error).message}`)
+    process.exit(1)
+  }
+}

package/src/cli/log.ts

@@ -0,0 +1,133 @@
+import { mkdir, appendFile, stat } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import type { CliContext } from './types.js'
+
+const HELP = `
+  opencastle log [options]
+
+  Append a structured event to the observability log (events.ndjson).
+
+  Options:
+    --type <type>          Event type (required): session|delegation|review|panel|dispute
+    --<field> <value>      Any field from the event schema (see documentation)
+    --logs-dir <path>      Override the logs directory path
+    --help, -h             Show this help
+
+  Array fields (comma-separated): file_partition, lessons_added, discoveries, reviewing_agents
+  Boolean fields: escalated, weighted
+  Numeric fields: auto-detected from value
+
+  Examples:
+    opencastle log --type session --agent Developer --model claude-sonnet-4-6 --task "Fix bug" --outcome success
+    opencastle log --type delegation --session_id feat/prj-1 --agent Developer --tier fast --mechanism sub-agent --outcome success
+    opencastle log --type panel --panel_key auth-review --verdict pass --pass_count 3 --block_count 0
+`
+
+const VALID_TYPES = ['session', 'delegation', 'review', 'panel', 'dispute']
+
+const ARRAY_FIELDS = new Set([
+  'file_partition',
+  'lessons_added',
+  'discoveries',
+  'reviewing_agents',
+])
+
+const BOOLEAN_FIELDS = new Set(['escalated', 'weighted'])
+
+function coerceValue(key: string, raw: string): unknown {
+  if (ARRAY_FIELDS.has(key)) return raw.split(',').map((s) => s.trim()).filter(Boolean)
+  if (BOOLEAN_FIELDS.has(key)) return raw === 'true'
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw)
+  return raw
+}
+
+/** Resolve the path to the logs directory (walks up to find .github/). */
+export async function resolveLogsDir(override?: string | null): Promise<string> {
+  if (override) return override
+  let dir = process.cwd()
+  for (;;) {
+    try {
+      const s = await stat(join(dir, '.github'))
+      if (s.isDirectory()) return join(dir, '.github', 'customizations', 'logs')
+    } catch {
+      // .github not in this directory, walk up
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return join(process.cwd(), '.github', 'customizations', 'logs')
+}
+
+/** Append a structured event record to events.ndjson. */
+export async function appendEvent(
+  record: Record<string, unknown>,
+  logsDir?: string | null,
+): Promise<void> {
+  const resolvedDir = await resolveLogsDir(logsDir ?? null)
+  const eventsFile = join(resolvedDir, 'events.ndjson')
+  await mkdir(resolvedDir, { recursive: true })
+  const line = JSON.stringify(record)
+  await appendFile(eventsFile, line + '\n', 'utf8')
+}
+
+export default async function log({ args }: CliContext): Promise<void> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(HELP)
+    return
+  }
+
+  let type: string | null = null
+  let logsDir: string | null = null
+  const fields: Record<string, unknown> = {}
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    switch (arg) {
+      case '--type':
+        if (i + 1 >= args.length) { console.error('  \u2717 --type requires a value'); process.exit(1) }
+        type = args[++i]
+        break
+      case '--logs-dir':
+        if (i + 1 >= args.length) { console.error('  \u2717 --logs-dir requires a path'); process.exit(1) }
+        logsDir = args[++i]
+        break
+      default:
+        if (arg.startsWith('--')) {
+          const key = arg.slice(2)
+          const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+          if (DANGEROUS_KEYS.has(key)) break
+          const next = args[i + 1]
+          if (next === undefined || next.startsWith('--')) {
+            fields[key] = true
+          } else {
+            fields[key] = coerceValue(key, args[++i])
+          }
+        }
+    }
+  }
+
+  if (!type) {
+    console.error('  \u2717 --type is required. Use one of: session, delegation, review, panel, dispute')
+    console.error('  Run "opencastle log --help" for usage.')
+    process.exit(1)
+  }
+
+  if (!VALID_TYPES.includes(type)) {
+    console.error(`  \u2717 Invalid --type "${type}". Must be one of: ${VALID_TYPES.join(', ')}`)
+    process.exit(1)
+  }
+
+  const timestamp = (fields['timestamp'] as string | undefined) ?? new Date().toISOString()
+  delete fields['timestamp']
+  const record = { type, timestamp, ...fields }
+
+  try {
+    await appendEvent(record, logsDir)
+    console.log(JSON.stringify(record))
+  } catch (err: unknown) {
+    console.error(`  ✗ Failed to write log: ${(err as Error).message}`)
+    process.exit(1)
+  }
+}
+

package/src/cli/run/executor.test.ts

@@ -11,6 +11,7 @@ function makeTask(overrides: Partial<Task> & { id: string; prompt: string }): Ta
     depends_on: [],
     files: [],
     description: overrides.id,
+    max_retries: 1,
     ...overrides,
   }
 }

package/src/cli/run/executor.ts

@@ -72,12 +72,12 @@ export function createExecutor(
   adapter: AgentAdapter,
   reporter: Reporter
 ): Executor {
-  const phases = buildPhases(spec.tasks)
+  const phases = buildPhases(spec.tasks!)
   const statuses = new Map<string, TaskStatus>()
   const results = new Map<string, TaskResult | null>()
   const startTimes = new Map<string, number>()
 
-  for (const t of spec.tasks) {
+  for (const t of spec.tasks!) {
     statuses.set(t.id, 'pending')
     results.set(t.id, null)
   }
@@ -154,7 +154,7 @@ export function createExecutor(
   function skipTask(taskId: string, reason: string): void {
     if (statuses.get(taskId) !== 'pending') return
     statuses.set(taskId, 'skipped')
-    const task = spec.tasks.find((t) => t.id === taskId)!
+    const task = spec.tasks!.find((t) => t.id === taskId)!
     results.set(taskId, {
       id: taskId,
       status: 'skipped',
@@ -165,7 +165,7 @@ export function createExecutor(
     reporter.onTaskSkipped(task, reason)
 
     // Recursively skip dependents
-    for (const t of spec.tasks) {
+    for (const t of spec.tasks!) {
       if ((t.depends_on || []).includes(taskId)) {
         skipTask(t.id, `dependency "${taskId}" was skipped/failed`)
       }
@@ -201,14 +201,14 @@ export function createExecutor(
             if (spec.on_failure === 'stop') {
               halted = true
               // Skip all remaining tasks
-              for (const t of spec.tasks) {
+              for (const t of spec.tasks!) {
                 if (statuses.get(t.id) === 'pending') {
                   skipTask(t.id, 'execution halted due to on_failure: stop')
                 }
               }
             } else {
               // on_failure: continue — skip dependents of this failed task
-              for (const t of spec.tasks) {
+              for (const t of spec.tasks!) {
                 if ((t.depends_on || []).includes(r.id)) {
                   skipTask(t.id, `dependency "${r.id}" failed`)
                 }
@@ -220,7 +220,7 @@ export function createExecutor(
     }
 
     const completedAt = new Date()
-    const allResults: TaskResult[] = spec.tasks.map(
+    const allResults: TaskResult[] = spec.tasks!.map(
       (t) =>
         results.get(t.id) || {
           id: t.id,
@@ -232,7 +232,7 @@ export function createExecutor(
     )
 
     const summary: RunSummary = {
-      total: spec.tasks.length,
+      total: spec.tasks!.length,
       done: 0,
       failed: 0,
       skipped: 0,