opencastle 0.14.0 → 0.16.0

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { parseYaml, parseTimeout, validateSpec, applyDefaults, isConvoySpec } from './schema.js'
+import { parseYaml, parseTimeout, validateSpec, applyDefaults, isConvoySpec, parseTaskSpecText } from './schema.js'
 
 // ── parseYaml ──────────────────────────────────────────────────
 
@@ -351,246 +351,6 @@ describe('applyDefaults', () => {
   })
 })
 
-// ── loop mode — validateSpec ───────────────────────────────────
-
-describe('validateSpec — loop mode', () => {
-  const validLoopSpec = {
-    name: 'build-auth',
-    mode: 'loop',
-    adapter: 'copilot',
-    loop: {
-      prompt: 'PROMPT_build.md',
-      plan_file: 'IMPLEMENTATION_PLAN.md',
-      max_iterations: 20,
-      timeout: '10m',
-      model: 'gpt-5.1',
-      backpressure: ['npm test', 'npx tsc --noEmit'],
-    },
-  }
-
-  it('accepts a valid minimal loop spec (only prompt required)', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT_build.md' },
-    })
-    expect(result.valid).toBe(true)
-    expect(result.errors).toHaveLength(0)
-  })
-
-  it('accepts a full loop spec', () => {
-    const result = validateSpec(validLoopSpec)
-    expect(result.valid).toBe(true)
-    expect(result.errors).toHaveLength(0)
-  })
-
-  it('does not require tasks array in loop mode', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT_build.md' },
-    })
-    expect(result.valid).toBe(true)
-  })
-
-  it('fails when loop object is missing', () => {
-    const result = validateSpec({ name: 'build-auth', mode: 'loop' })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('`loop` is required'))
-  })
-
-  it('fails when loop.prompt is missing', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { max_iterations: 10 },
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('loop.prompt'))
-  })
-
-  it('fails when loop.prompt is not a string', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 123 },
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('loop.prompt'))
-  })
-
-  it('fails when loop.max_iterations is 0', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md', max_iterations: 0 },
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('loop.max_iterations'))
-  })
-
-  it('fails when loop.max_iterations is a float', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md', max_iterations: 1.5 },
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('loop.max_iterations'))
-  })
-
-  it('fails when loop.timeout has invalid format', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md', timeout: 'bad' },
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('loop.timeout'))
-  })
-
-  it('accepts valid loop.timeout formats', () => {
-    for (const t of ['5s', '10m', '2h']) {
-      const result = validateSpec({
-        name: 'build-auth',
-        mode: 'loop',
-        loop: { prompt: 'PROMPT.md', timeout: t },
-      })
-      expect(result.valid).toBe(true)
-    }
-  })
-
-  it('fails when loop.backpressure is not an array', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md', backpressure: 'npm test' },
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('loop.backpressure'))
-  })
-
-  it('fails when loop.backpressure contains non-strings', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md', backpressure: ['npm test', 42] },
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('loop.backpressure'))
-  })
-
-  it('fails when loop.plan_file is not a string', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md', plan_file: true },
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('loop.plan_file'))
-  })
-
-  it('fails when loop.model is not a string', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md', model: 99 },
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('loop.model'))
-  })
-
-  it('rejects unknown mode value', () => {
-    const result = validateSpec({
-      name: 'build-auth',
-      mode: 'parallel',
-      tasks: [{ id: 'a', prompt: 'x' }],
-    })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('mode'))
-  })
-
-  it('mode: tasks still requires tasks array', () => {
-    const result = validateSpec({ name: 'build-auth', mode: 'tasks' })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('tasks'))
-  })
-
-  it('spec without mode field defaults to tasks behavior (requires tasks)', () => {
-    const result = validateSpec({ name: 'build-auth' })
-    expect(result.valid).toBe(false)
-    expect(result.errors).toContainEqual(expect.stringContaining('tasks'))
-  })
-})
-
-// ── loop mode — applyDefaults ──────────────────────────────────
-
-describe('applyDefaults — loop mode', () => {
-  it('applies default max_iterations', () => {
-    const spec = applyDefaults({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md' },
-    })
-    expect(spec.loop?.max_iterations).toBe(20)
-  })
-
-  it('applies default plan_file', () => {
-    const spec = applyDefaults({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md' },
-    })
-    expect(spec.loop?.plan_file).toBe('IMPLEMENTATION_PLAN.md')
-  })
-
-  it('applies default timeout', () => {
-    const spec = applyDefaults({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md' },
-    })
-    expect(spec.loop?.timeout).toBe('10m')
-  })
-
-  it('preserves user-specified loop values', () => {
-    const spec = applyDefaults({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: {
-        prompt: 'PROMPT.md',
-        max_iterations: 5,
-        plan_file: 'MY_PLAN.md',
-        timeout: '30m',
-        model: 'gpt-5.1',
-        backpressure: ['npm test'],
-      },
-    })
-    expect(spec.loop?.max_iterations).toBe(5)
-    expect(spec.loop?.plan_file).toBe('MY_PLAN.md')
-    expect(spec.loop?.timeout).toBe('30m')
-    expect(spec.loop?.model).toBe('gpt-5.1')
-    expect(spec.loop?.backpressure).toEqual(['npm test'])
-  })
-
-  it('sets mode to tasks when not specified', () => {
-    const spec = applyDefaults({
-      name: 'test',
-      tasks: [{ id: 'a', prompt: 'x' }],
-    })
-    expect(spec.mode).toBe('tasks')
-  })
-
-  it('preserves mode: loop', () => {
-    const spec = applyDefaults({
-      name: 'build-auth',
-      mode: 'loop',
-      loop: { prompt: 'PROMPT.md' },
-    })
-    expect(spec.mode).toBe('loop')
-  })
-})
-
 // ── validateSpec — version field ───────────────────────────────
 
 describe('validateSpec — version field', () => {
@@ -1051,3 +811,63 @@ describe('backward compatibility — legacy specs', () => {
     expect(spec.tasks![0].model).toBeUndefined()
   })
 })
+
+// ── parseTaskSpecText ──────────────────────────────────────────
+
+describe('parseTaskSpecText', () => {
+  it('parses a valid YAML string and returns a TaskSpec', () => {
+    const yaml = `
+name: test-run
+tasks:
+  - id: task-1
+    prompt: Do something
+`
+    const spec = parseTaskSpecText(yaml)
+    expect(spec.name).toBe('test-run')
+    expect(spec.tasks).toHaveLength(1)
+    expect(spec.tasks![0].id).toBe('task-1')
+  })
+
+  it('throws on empty string', () => {
+    expect(() => parseTaskSpecText('')).toThrow('empty')
+  })
+
+  it('throws on whitespace-only string', () => {
+    expect(() => parseTaskSpecText('   \n  ')).toThrow('empty')
+  })
+
+  it('throws on invalid YAML', () => {
+    expect(() => parseTaskSpecText(': invalid: yaml: {')).toThrow(/YAML parse error/)
+  })
+
+  it('throws on invalid spec (missing tasks)', () => {
+    expect(() => parseTaskSpecText('name: test')).toThrow(/Invalid task spec/)
+  })
+
+  it('applies defaults when parsing', () => {
+    const yaml = `
+name: test-run
+tasks:
+  - id: task-1
+    prompt: Do something
+`
+    const spec = parseTaskSpecText(yaml)
+    expect(spec.concurrency).toBe(1)
+    expect(spec.on_failure).toBe('continue')
+    expect(spec.tasks![0].agent).toBe('developer')
+    expect(spec.tasks![0].timeout).toBe('30m')
+  })
+
+  it('parses a convoy spec (version: 1)', () => {
+    const yaml = `
+name: convoy-run
+version: 1
+tasks:
+  - id: task-1
+    prompt: Do something
+`
+    const spec = parseTaskSpecText(yaml)
+    expect(spec.version).toBe(1)
+    expect(isConvoySpec(spec)).toBe(true)
+  })
+})

package/src/cli/run/schema.ts

@@ -39,8 +39,6 @@ interface RawSpec {
   on_failure?: unknown
   adapter?: unknown
   tasks?: unknown
-  mode?: unknown
-  loop?: unknown
   version?: unknown
   defaults?: unknown
   gates?: unknown
@@ -146,132 +144,87 @@ export function validateSpec(spec: unknown): ValidationResult {
     errors.push('`branch` must be a string')
   }
 
-  // mode
-  const mode = s.mode !== undefined ? s.mode : 'tasks'
-  if (mode !== 'tasks' && mode !== 'loop') {
-    errors.push('`mode` must be one of: tasks, loop')
+  // Tasks are always required
+  if (!s.tasks || !Array.isArray(s.tasks) || s.tasks.length === 0) {
+    errors.push('`tasks` is required and must be a non-empty array')
+    return { valid: false, errors }
   }
 
-  if (mode === 'loop') {
-    // Loop validation — tasks array is NOT required
-    const loop = s.loop as Record<string, unknown> | undefined
-    if (!loop || typeof loop !== 'object') {
-      errors.push('`loop` is required when mode is "loop"')
-    } else {
-      if (!loop.prompt || typeof loop.prompt !== 'string') {
-        errors.push('`loop.prompt` is required and must be a string')
-      }
-      if (loop.max_iterations !== undefined) {
-        const mi = Number(loop.max_iterations)
-        if (!Number.isInteger(mi) || mi < 1) {
-          errors.push('`loop.max_iterations` must be an integer >= 1')
-        }
-      }
-      if (loop.timeout !== undefined) {
-        if (isNaN(parseTimeout(loop.timeout as string))) {
-          errors.push(
-            '`loop.timeout` must be in format: <number><s|m|h> (e.g. "10m")'
-          )
-        }
-      }
-      if (loop.backpressure !== undefined) {
-        if (
-          !Array.isArray(loop.backpressure) ||
-          !(loop.backpressure as unknown[]).every((b) => typeof b === 'string')
-        ) {
-          errors.push('`loop.backpressure` must be an array of strings')
-        }
-      }
-      if (loop.plan_file !== undefined && typeof loop.plan_file !== 'string') {
-        errors.push('`loop.plan_file` must be a string')
-      }
-      if (loop.model !== undefined && typeof loop.model !== 'string') {
-        errors.push('`loop.model` must be a string')
-      }
-    }
-  } else {
-    // Tasks mode — tasks array is required
-    if (!s.tasks || !Array.isArray(s.tasks) || s.tasks.length === 0) {
-      errors.push('`tasks` is required and must be a non-empty array')
-      return { valid: false, errors }
-    }
-
-    const taskIds = new Set<string>()
-    const tasks = s.tasks as RawTask[]
+  const taskIds = new Set<string>()
+  const tasks = s.tasks as RawTask[]
 
-    for (let i = 0; i < tasks.length; i++) {
+  for (let i = 0; i < tasks.length; i++) {
       const task = tasks[i]
       const prefix = `tasks[${i}]`
 
       if (!task || typeof task !== 'object') {
         errors.push(`${prefix}: must be an object`)
-        continue
-      }
+      continue
+    }
 
-      // id
-      if (!task.id || typeof task.id !== 'string') {
-        errors.push(`${prefix}: \`id\` is required and must be a string`)
-      } else if (taskIds.has(task.id)) {
-        errors.push(`${prefix}: duplicate task id "${task.id}"`)
-      } else {
-        taskIds.add(task.id)
-      }
+    // id
+    if (!task.id || typeof task.id !== 'string') {
+      errors.push(`${prefix}: \`id\` is required and must be a string`)
+    } else if (taskIds.has(task.id)) {
+      errors.push(`${prefix}: duplicate task id "${task.id}"`)
+    } else {
+      taskIds.add(task.id)
+    }
 
-      // prompt
-      if (!task.prompt || typeof task.prompt !== 'string') {
-        errors.push(`${prefix}: \`prompt\` is required and must be a string`)
-      }
+    // prompt
+    if (!task.prompt || typeof task.prompt !== 'string') {
+      errors.push(`${prefix}: \`prompt\` is required and must be a string`)
+    }
 
-      // timeout
-      if (task.timeout !== undefined) {
-        if (isNaN(parseTimeout(task.timeout as string))) {
-          errors.push(
-            `${prefix}: \`timeout\` must be in format: <number><s|m|h> (e.g. "10m")`
-          )
-        }
+    // timeout
+    if (task.timeout !== undefined) {
+      if (isNaN(parseTimeout(task.timeout as string))) {
+        errors.push(
+          `${prefix}: \`timeout\` must be in format: <number><s|m|h> (e.g. "10m")`
+        )
       }
+    }
 
-      // depends_on
-      if (task.depends_on !== undefined) {
-        if (!Array.isArray(task.depends_on)) {
-          errors.push(`${prefix}: \`depends_on\` must be an array`)
-        } else {
-          for (const dep of task.depends_on as string[]) {
-            if (!taskIds.has(dep) && !tasks.some((t) => t && t.id === dep)) {
-              errors.push(
-                `${prefix}: \`depends_on\` references unknown task "${dep}"`
-              )
-            }
+    // depends_on
+    if (task.depends_on !== undefined) {
+      if (!Array.isArray(task.depends_on)) {
+        errors.push(`${prefix}: \`depends_on\` must be an array`)
+      } else {
+        for (const dep of task.depends_on as string[]) {
+          if (!taskIds.has(dep) && !tasks.some((t) => t && t.id === dep)) {
+            errors.push(
+              `${prefix}: \`depends_on\` references unknown task "${dep}"`
+            )
           }
         }
       }
+    }
 
-      // files
-      if (task.files !== undefined && !Array.isArray(task.files)) {
-        errors.push(`${prefix}: \`files\` must be an array`)
-      }
+    // files
+    if (task.files !== undefined && !Array.isArray(task.files)) {
+      errors.push(`${prefix}: \`files\` must be an array`)
+    }
 
-      // model
-      if (task.model !== undefined && typeof task.model !== 'string') {
-        errors.push(`${prefix}: \`model\` must be a string`)
-      }
+    // model
+    if (task.model !== undefined && typeof task.model !== 'string') {
+      errors.push(`${prefix}: \`model\` must be a string`)
+    }
 
-      // max_retries
-      if (task.max_retries !== undefined) {
-        const mr = Number(task.max_retries)
-        if (!Number.isInteger(mr) || mr < 0) {
-          errors.push(
-            `${prefix}: \`max_retries\` must be a non-negative integer`
-          )
-        }
+    // max_retries
+    if (task.max_retries !== undefined) {
+      const mr = Number(task.max_retries)
+      if (!Number.isInteger(mr) || mr < 0) {
+        errors.push(
+          `${prefix}: \`max_retries\` must be a non-negative integer`
+        )
       }
     }
+  }
 
-    // DAG cycle detection
-    if (errors.length === 0) {
-      const cycleErr = detectCycles(tasks as Array<{ id: string; depends_on?: string[] }>)
-      if (cycleErr) errors.push(cycleErr)
-    }
+  // DAG cycle detection
+  if (errors.length === 0) {
+    const cycleErr = detectCycles(tasks as Array<{ id: string; depends_on?: string[] }>)
+    if (cycleErr) errors.push(cycleErr)
   }
 
   return { valid: errors.length === 0, errors }
@@ -330,39 +283,30 @@ export function applyDefaults(spec: Record<string, unknown>): TaskSpec {
   s.on_failure = (s.on_failure as string) || 'continue'
   // Leave adapter empty so run.ts can auto-detect the best available CLI
   s.adapter = (s.adapter as string) || ''
-  s.mode = (s.mode as string) || 'tasks'
-
-  if (s.mode === 'loop') {
-    const loop = ((s.loop ?? {}) as Record<string, unknown>)
-    loop.max_iterations = loop.max_iterations !== undefined ? Number(loop.max_iterations) : 20
-    loop.plan_file = (loop.plan_file as string) || 'IMPLEMENTATION_PLAN.md'
-    loop.timeout = (loop.timeout as string) || '10m'
-    s.loop = loop
-  } else {
-    const tasks = s.tasks as Array<Record<string, unknown>>
-    const d =
-      s.version === 1 && s.defaults
-        ? (s.defaults as Record<string, unknown>)
-        : {}
-    for (const task of tasks) {
-      task.agent =
-        (task.agent as string) || (d.agent as string | undefined) || 'developer'
-      task.timeout =
-        (task.timeout as string) ||
-        (d.timeout as string | undefined) ||
-        '30m'
-      task.depends_on = (task.depends_on as string[]) || []
-      task.files = (task.files as string[]) || []
-      task.description = (task.description as string) || (task.id as string)
-      // model: task-level overrides defaults (no hardcoded fallback)
-      if (task.model === undefined && d.model !== undefined) {
-        task.model = d.model
-      }
-      // max_retries: task-level overrides defaults, fallback to 1
-      if (task.max_retries === undefined) {
-        task.max_retries =
-          d.max_retries !== undefined ? Number(d.max_retries) : 1
-      }
+
+  const tasks = s.tasks as Array<Record<string, unknown>>
+  const d =
+    s.version === 1 && s.defaults
+      ? (s.defaults as Record<string, unknown>)
+      : {}
+  for (const task of tasks) {
+    task.agent =
+      (task.agent as string) || (d.agent as string | undefined) || 'developer'
+    task.timeout =
+      (task.timeout as string) ||
+      (d.timeout as string | undefined) ||
+      '30m'
+    task.depends_on = (task.depends_on as string[]) || []
+    task.files = (task.files as string[]) || []
+    task.description = (task.description as string) || (task.id as string)
+    // model: task-level overrides defaults (no hardcoded fallback)
+    if (task.model === undefined && d.model !== undefined) {
+      task.model = d.model
+    }
+    // max_retries: task-level overrides defaults, fallback to 1
+    if (task.max_retries === undefined) {
+      task.max_retries =
+        d.max_retries !== undefined ? Number(d.max_retries) : 1
     }
   }
 
@@ -378,21 +322,10 @@ export function isConvoySpec(spec: unknown): boolean {
 }
 
 /**
- * Read, parse, validate, and return a typed task spec from a YAML file.
- * @throws If file cannot be read, parsed, or spec is invalid
+ * Parse, validate, and return a typed task spec from a YAML string.
+ * @throws If the text is empty, cannot be parsed, or spec is invalid
  */
-export async function parseTaskSpec(filePath: string): Promise<TaskSpec> {
-  let text: string
-  try {
-    text = await readFile(filePath, 'utf8')
-  } catch (err: unknown) {
-    const e = err as Error & { code?: string }
-    if (e.code === 'ENOENT') {
-      throw new Error(`Task spec file not found: ${filePath}`)
-    }
-    throw new Error(`Cannot read task spec file: ${e.message}`)
-  }
-
+export function parseTaskSpecText(text: string): TaskSpec {
   if (!text.trim()) {
     throw new Error('Task spec file is empty')
   }
@@ -411,3 +344,22 @@ export async function parseTaskSpec(filePath: string): Promise<TaskSpec> {
 
   return applyDefaults(spec)
 }
+
+/**
+ * Read, parse, validate, and return a typed task spec from a YAML file.
+ * @throws If file cannot be read, parsed, or spec is invalid
+ */
+export async function parseTaskSpec(filePath: string): Promise<TaskSpec> {
+  let text: string
+  try {
+    text = await readFile(filePath, 'utf8')
+  } catch (err: unknown) {
+    const e = err as Error & { code?: string }
+    if (e.code === 'ENOENT') {
+      throw new Error(`Task spec file not found: ${filePath}`)
+    }
+    throw new Error(`Cannot read task spec file: ${e.message}`)
+  }
+
+  return parseTaskSpecText(text)
+}