task-while 0.0.1

package/src/schema/model.ts

@@ -0,0 +1,233 @@
+import { z } from 'zod'
+
+import {
+  acceptanceStatusValues,
+  dateTimeSchema,
+  finalStatusValues,
+  findingSeverityValues,
+  implementStatusValues,
+  nonEmptyStringSchema,
+  overallRiskValues,
+  reviewVerdictValues,
+  runningStageValues,
+  taskHandleSchema,
+  taskStatusValues,
+  uniqueStringArray,
+  workflowEventTypeValues,
+} from './shared'
+
+export const reviewFindingSchema = z
+  .object({
+    file: nonEmptyStringSchema.optional(),
+    fixHint: nonEmptyStringSchema,
+    issue: nonEmptyStringSchema,
+    severity: z.enum(findingSeverityValues),
+  })
+  .strict()
+
+export const acceptanceCheckSchema = z
+  .object({
+    criterion: nonEmptyStringSchema,
+    note: nonEmptyStringSchema,
+    status: z.enum(acceptanceStatusValues),
+  })
+  .strict()
+
+export const taskTopologyEntrySchema = z
+  .object({
+    commitSubject: nonEmptyStringSchema,
+    dependsOn: uniqueStringArray('dependency task handle'),
+    handle: taskHandleSchema,
+  })
+  .strict()
+
+export const taskGraphSchema = z
+  .object({
+    featureId: nonEmptyStringSchema,
+    maxIterations: z.number().int().min(1).max(20),
+    tasks: z
+      .array(taskTopologyEntrySchema)
+      .min(1)
+      .superRefine((tasks, ctx) => {
+        const seen = new Set<string>()
+        for (const [index, task] of tasks.entries()) {
+          if (seen.has(task.handle)) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: `Duplicate task handle: ${task.handle}`,
+              path: [index, 'handle'],
+            })
+            continue
+          }
+          seen.add(task.handle)
+        }
+      }),
+  })
+  .strict()
+
+export const implementOutputSchemaInternal = z
+  .object({
+    assumptions: uniqueStringArray('assumption'),
+    needsHumanAttention: z.boolean(),
+    notes: uniqueStringArray('note'),
+    status: z.enum(implementStatusValues),
+    summary: nonEmptyStringSchema,
+    taskHandle: taskHandleSchema,
+    unresolvedItems: uniqueStringArray('unresolved item'),
+  })
+  .strict()
+
+export const reviewOutputSchemaInternal = z
+  .object({
+    acceptanceChecks: z.array(acceptanceCheckSchema).min(1),
+    findings: z.array(reviewFindingSchema),
+    overallRisk: z.enum(overallRiskValues),
+    summary: nonEmptyStringSchema,
+    taskHandle: taskHandleSchema,
+    verdict: z.enum(reviewVerdictValues),
+  })
+  .strict()
+
+const taskStateBaseSchema = z
+  .object({
+    attempt: z.number().int().min(0),
+    generation: z.number().int().min(1),
+    invalidatedBy: taskHandleSchema.nullable(),
+    lastFindings: z.array(reviewFindingSchema),
+    lastReviewVerdict: z.enum(reviewVerdictValues).optional(),
+  })
+  .strict()
+
+export const pendingTaskStateSchema = taskStateBaseSchema
+  .extend({
+    status: z.literal('pending'),
+  })
+  .strict()
+
+export const runningTaskStateSchema = taskStateBaseSchema
+  .extend({
+    stage: z.enum(runningStageValues),
+    status: z.literal('running'),
+  })
+  .strict()
+
+export const reworkTaskStateSchema = taskStateBaseSchema
+  .extend({
+    status: z.literal('rework'),
+  })
+  .strict()
+
+export const doneTaskStateSchema = taskStateBaseSchema
+  .extend({
+    commitSha: nonEmptyStringSchema,
+    status: z.literal('done'),
+  })
+  .strict()
+
+export const blockedTaskStateSchema = taskStateBaseSchema
+  .extend({
+    reason: nonEmptyStringSchema,
+    status: z.literal('blocked'),
+  })
+  .strict()
+
+export const replanTaskStateSchema = taskStateBaseSchema
+  .extend({
+    reason: nonEmptyStringSchema,
+    status: z.literal('replan'),
+  })
+  .strict()
+
+export const taskStateSchema = z.discriminatedUnion('status', [
+  pendingTaskStateSchema,
+  runningTaskStateSchema,
+  reworkTaskStateSchema,
+  doneTaskStateSchema,
+  blockedTaskStateSchema,
+  replanTaskStateSchema,
+])
+
+export const workflowStateSchema = z
+  .object({
+    currentTaskHandle: taskHandleSchema.nullable(),
+    featureId: nonEmptyStringSchema,
+    tasks: z.record(taskStateSchema),
+  })
+  .strict()
+
+export const implementArtifactSchema = z
+  .object({
+    attempt: z.number().int().min(1),
+    commitSha: nonEmptyStringSchema.optional(),
+    createdAt: dateTimeSchema,
+    generation: z.number().int().min(1),
+    result: implementOutputSchemaInternal,
+    taskHandle: taskHandleSchema,
+  })
+  .strict()
+
+export const reviewArtifactSchema = z
+  .object({
+    attempt: z.number().int().min(1),
+    commitSha: nonEmptyStringSchema.optional(),
+    createdAt: dateTimeSchema,
+    generation: z.number().int().min(1),
+    result: reviewOutputSchemaInternal,
+    taskHandle: taskHandleSchema,
+  })
+  .strict()
+
+export const integrateArtifactSchema = z
+  .object({
+    attempt: z.number().int().min(1),
+    createdAt: dateTimeSchema,
+    generation: z.number().int().min(1),
+    taskHandle: taskHandleSchema,
+    result: z
+      .object({
+        commitSha: nonEmptyStringSchema,
+        summary: nonEmptyStringSchema,
+      })
+      .strict(),
+  })
+  .strict()
+
+export const workflowEventSchema = z
+  .object({
+    attempt: z.number().int().min(0),
+    detail: z.string().optional(),
+    generation: z.number().int().min(1),
+    taskHandle: taskHandleSchema,
+    timestamp: dateTimeSchema,
+    type: z.enum(workflowEventTypeValues),
+  })
+  .strict()
+
+export const finalReportTaskSchema = z
+  .object({
+    attempt: z.number().int().min(0),
+    commitSha: nonEmptyStringSchema.optional(),
+    generation: z.number().int().min(1),
+    lastReviewVerdict: z.enum(reviewVerdictValues).optional(),
+    reason: nonEmptyStringSchema.optional(),
+    status: z.enum(taskStatusValues),
+    taskHandle: taskHandleSchema,
+  })
+  .strict()
+
+export const finalReportSchema = z
+  .object({
+    featureId: nonEmptyStringSchema,
+    generatedAt: dateTimeSchema,
+    tasks: z.array(finalReportTaskSchema),
+    summary: z
+      .object({
+        blockedTasks: z.number().int().min(0),
+        completedTasks: z.number().int().min(0),
+        finalStatus: z.enum(finalStatusValues),
+        replanTasks: z.number().int().min(0),
+        totalTasks: z.number().int().min(0),
+      })
+      .strict(),
+  })
+  .strict()

package/src/schema/shared.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod'
+
+export const nonEmptyStringSchema = z.string().min(1)
+export const taskHandleSchema = nonEmptyStringSchema
+export const dateTimeSchema = z.string().datetime({ offset: true })
+
+export const taskStatusValues = [
+  'pending',
+  'running',
+  'rework',
+  'done',
+  'blocked',
+  'replan',
+] as const
+export const runningStageValues = ['implement', 'review', 'integrate'] as const
+export const reviewVerdictValues = [
+  'blocked',
+  'pass',
+  'replan',
+  'rework',
+] as const
+export const implementStatusValues = [
+  'blocked',
+  'implemented',
+  'partial',
+] as const
+export const findingSeverityValues = ['high', 'low', 'medium'] as const
+export const acceptanceStatusValues = ['fail', 'pass', 'unclear'] as const
+export const overallRiskValues = ['high', 'low', 'medium'] as const
+export const workflowEventTypeValues = [
+  'attempt_started',
+  'implement_succeeded',
+  'implement_failed',
+  'review_started',
+  'review_completed',
+  'review_failed',
+  'integrate_started',
+  'integrate_completed',
+  'integrate_failed',
+] as const
+export const finalStatusValues = [
+  'blocked',
+  'completed',
+  'in_progress',
+  'replan_required',
+] as const
+
+function uniqueStrings(items: string[], label: string, ctx: z.RefinementCtx) {
+  const seen = new Set<string>()
+  for (const [index, item] of items.entries()) {
+    if (seen.has(item)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Duplicate ${label}: ${item}`,
+        path: [index],
+      })
+      continue
+    }
+    seen.add(item)
+  }
+}
+
+export function uniqueStringArray(
+  label: string,
+  options?: { minItems?: number },
+) {
+  const base = z.array(nonEmptyStringSchema)
+  const withMin = options?.minItems ? base.min(options.minItems) : base
+  return withMin.superRefine((items, ctx) => {
+    uniqueStrings(items, label, ctx)
+  })
+}
+
+export function formatPath(path: (number | string)[]) {
+  if (path.length === 0) {
+    return '/'
+  }
+  return `/${path.join('/')}`
+}
+
+export function formatIssues(error: z.ZodError) {
+  return error.issues
+    .map((issue) => `${formatPath(issue.path)} ${issue.message}`.trim())
+    .join('; ')
+}
+
+export function parseWithSchema<T>(schema: z.ZodType<T>, value: unknown): T {
+  const result = schema.safeParse(value)
+  if (!result.success) {
+    throw new Error(formatIssues(result.error))
+  }
+  return result.data
+}

package/src/task-sources/openspec/cli-json.ts

@@ -0,0 +1,79 @@
+import { execa } from 'execa'
+
+export interface OpenSpecCliTask {
+  description: string
+  id: string
+}
+
+export interface OpenSpecApplyInstructions {
+  changeName: string
+  contextFiles: Record<string, string>
+  instruction: string
+  progress: {
+    complete: number
+    total: number
+  }
+  schemaName: string
+  state: string
+  tasks: OpenSpecCliTask[]
+}
+
+export interface OpenSpecStatus {
+  applyRequires: string[]
+  artifacts: {
+    id: string
+    outputPath: string
+    status: string
+  }[]
+  changeName: string
+  isComplete: boolean
+  schemaName: string
+}
+
+export async function parseCliJson<T>(stdout: string): Promise<T> {
+  const start = stdout.indexOf('{')
+  if (start === -1) {
+    throw new Error('OpenSpec CLI did not return JSON payload')
+  }
+  return JSON.parse(stdout.slice(start)) as T
+}
+
+export async function readOpenSpecApplyInstructions(input: {
+  changeName: string
+  workspaceRoot: string
+}): Promise<OpenSpecApplyInstructions> {
+  try {
+    const { stdout } = await execa(
+      'openspec',
+      ['instructions', 'apply', '--change', input.changeName, '--json'],
+      {
+        cwd: input.workspaceRoot,
+      },
+    )
+    return await parseCliJson<OpenSpecApplyInstructions>(stdout)
+  } catch (error) {
+    throw new Error(
+      `Failed to read OpenSpec apply instructions for ${input.changeName}: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}
+
+export async function readOpenSpecStatus(input: {
+  changeName: string
+  workspaceRoot: string
+}): Promise<OpenSpecStatus> {
+  try {
+    const { stdout } = await execa(
+      'openspec',
+      ['status', '--change', input.changeName, '--json'],
+      {
+        cwd: input.workspaceRoot,
+      },
+    )
+    return await parseCliJson<OpenSpecStatus>(stdout)
+  } catch (error) {
+    throw new Error(
+      `Failed to read OpenSpec status for ${input.changeName}: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}

package/src/task-sources/openspec/context-files.ts

@@ -0,0 +1,121 @@
+import { readdir, readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+function normalizeGlobPath(value: string) {
+  return value.replaceAll(path.sep, '/')
+}
+
+function escapeRegex(value: string) {
+  return value.replace(/[.+^${}()|[\]\\]/g, String.raw`\$&`)
+}
+
+function globToRegExp(pattern: string) {
+  const normalized = normalizeGlobPath(pattern)
+  let source = ''
+  for (let index = 0; index < normalized.length; index += 1) {
+    const char = normalized[index] ?? ''
+    const next = normalized[index + 1]
+    const nextNext = normalized[index + 2]
+    if (char === '*' && next === '*' && nextNext === '/') {
+      source += '(?:[^/]+/)*'
+      index += 2
+      continue
+    }
+    if (char === '*' && next === '*') {
+      source += '.*'
+      index += 1
+      continue
+    }
+    if (char === '*') {
+      source += '[^/]*'
+      continue
+    }
+    source += escapeRegex(char)
+  }
+  return new RegExp(`^${source}$`)
+}
+
+async function listFilesRecursively(root: string): Promise<string[]> {
+  const entries = await readdir(root, { withFileTypes: true })
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = path.join(root, entry.name)
+      if (entry.isDirectory()) {
+        return listFilesRecursively(entryPath)
+      }
+      return [entryPath]
+    }),
+  )
+  return files.flat()
+}
+
+async function expandPattern(
+  baseDir: string,
+  pattern: string,
+): Promise<string[]> {
+  const isAbsolutePattern = path.isAbsolute(pattern)
+  const matchRoot = isAbsolutePattern ? path.parse(pattern).root : baseDir
+
+  if (!pattern.includes('*')) {
+    return [isAbsolutePattern ? pattern : path.join(baseDir, pattern)]
+  }
+
+  const normalizedPattern = normalizeGlobPath(
+    isAbsolutePattern ? path.relative(matchRoot, pattern) : pattern,
+  )
+  const firstGlobIndex = normalizedPattern.search(/\*/)
+  const slashIndex =
+    firstGlobIndex === -1
+      ? normalizedPattern.length
+      : normalizedPattern.lastIndexOf('/', firstGlobIndex)
+  const searchPrefix =
+    slashIndex <= 0 ? '.' : normalizedPattern.slice(0, slashIndex)
+  const searchRoot = path.join(matchRoot, searchPrefix)
+  const regex = globToRegExp(normalizedPattern)
+
+  try {
+    const files = await listFilesRecursively(searchRoot)
+    return files
+      .filter((filePath) =>
+        regex.test(normalizeGlobPath(path.relative(matchRoot, filePath))),
+      )
+      .sort((left, right) =>
+        normalizeGlobPath(path.relative(matchRoot, left)).localeCompare(
+          normalizeGlobPath(path.relative(matchRoot, right)),
+        ),
+      )
+  } catch {
+    return []
+  }
+}
+
+async function readPattern(baseDir: string, pattern: string) {
+  const filePaths = await expandPattern(baseDir, pattern)
+  const contents = await Promise.all(
+    filePaths.map((filePath) => readFile(filePath, 'utf8')),
+  )
+  return contents.join('\n\n')
+}
+
+export async function readContextFileMap(
+  baseDir: string,
+  contextFiles: Record<string, string>,
+): Promise<Map<string, string>> {
+  const orderedKeys = ['proposal', 'design', 'specs', 'tasks']
+  const remainingKeys = Object.keys(contextFiles).filter(
+    (key) => !orderedKeys.includes(key),
+  )
+  const finalKeys = [
+    ...orderedKeys.filter((key) => key in contextFiles),
+    ...remainingKeys,
+  ]
+
+  const entries = await Promise.all(
+    finalKeys.map(
+      async (key) =>
+        [key, await readPattern(baseDir, contextFiles[key]!)] as const,
+    ),
+  )
+
+  return new Map(entries)
+}

package/src/task-sources/openspec/parse-tasks-md.ts

@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises'
+
+export interface OpenSpecTask {
+  checked: boolean
+  handle: string
+  ordinal: number
+  rawLine: string
+  sectionTitle: string
+  title: string
+}
+
+function createTask(
+  line: string,
+  ordinal: number,
+  sectionTitle: string,
+): OpenSpecTask {
+  const checkboxMatch = line.match(/^[-*]\s+\[([ x])\]\s+(\S.*)$/i)
+  if (!checkboxMatch) {
+    throw new Error(`Invalid task line: ${line}`)
+  }
+  const body = checkboxMatch[2]!
+  const numberedMatch = body.match(/^(\d+(?:\.\d+)*)\s+(\S.*)$/)
+
+  return {
+    checked: checkboxMatch[1]!.toLowerCase() === 'x',
+    handle: numberedMatch?.[1] ?? `task-${ordinal}`,
+    ordinal,
+    rawLine: line,
+    sectionTitle,
+    title: numberedMatch?.[2] ?? body,
+  }
+}
+
+export async function parseTasksMd(tasksPath: string): Promise<OpenSpecTask[]> {
+  const content = await readFile(tasksPath, 'utf8')
+  const lines = content.split(/\r?\n/)
+  const tasks: OpenSpecTask[] = []
+  let currentSectionTitle = 'unknown'
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd()
+    if (line.startsWith('## ')) {
+      currentSectionTitle = line.replace(/^##\s+/, '').trim()
+      continue
+    }
+    if (!line.match(/^[-*]\s+\[[ x]\]\s+/i)) {
+      continue
+    }
+    tasks.push(createTask(line, tasks.length + 1, currentSectionTitle))
+  }
+
+  if (tasks.length === 0) {
+    throw new Error('No tasks found in tasks.md')
+  }
+
+  return tasks
+}