task-while 0.0.1

package/src/task-sources/openspec/session.ts

@@ -0,0 +1,235 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { readOpenSpecApplyInstructions } from './cli-json'
+import { readContextFileMap } from './context-files'
+
+import type {
+  OpenTaskSourceInput,
+  TaskPrompt,
+  TaskSourceSession,
+} from '../types'
+import type { OpenSpecTask } from './parse-tasks-md'
+
+function createImplementPrompt(
+  task: OpenSpecTask,
+  input: {
+    apply: Awaited<ReturnType<typeof readOpenSpecApplyInstructions>>
+    context: Map<string, string>
+    featureId: string
+  },
+): TaskPrompt {
+  return {
+    instructions: [
+      'Implement only the current task from the OpenSpec change.',
+      'Use the OpenSpec apply instruction as the execution contract.',
+      input.apply.instruction,
+      'Do not mark tasks.md complete; while will apply completion after review/integrate.',
+      'Do not move to the next task.',
+      'Return structured output only.',
+    ],
+    sections: [
+      { content: input.featureId, title: 'Change' },
+      { content: input.apply.schemaName, title: 'Schema' },
+      { content: input.apply.state, title: 'Apply State' },
+      {
+        content: `${input.apply.progress.complete}/${input.apply.progress.total} complete`,
+        title: 'Apply Progress',
+      },
+      { content: task.rawLine, title: 'Current Task' },
+      { content: task.sectionTitle, title: 'Task Group' },
+      { content: input.context.get('proposal') ?? '', title: 'Proposal' },
+      { content: input.context.get('design') ?? '', title: 'Design' },
+      { content: input.context.get('specs') ?? '', title: 'Specs' },
+      { content: input.context.get('tasks') ?? '', title: 'Tasks' },
+    ],
+  }
+}
+
+function createReviewPrompt(
+  task: OpenSpecTask,
+  input: {
+    apply: Awaited<ReturnType<typeof readOpenSpecApplyInstructions>>
+    context: Map<string, string>
+    featureId: string
+  },
+): TaskPrompt {
+  return {
+    instructions: [
+      'Review only the current task from the OpenSpec change.',
+      'Use the OpenSpec apply instruction as the execution contract.',
+      input.apply.instruction,
+      'Judge the implementation against the current task, OpenSpec context, and actual changed files.',
+      'Only return verdict "pass" when the current task is satisfied by the implementation.',
+      'Do not expand the review to unrelated repository changes.',
+    ],
+    sections: [
+      { content: input.featureId, title: 'Change' },
+      { content: input.apply.schemaName, title: 'Schema' },
+      { content: input.apply.state, title: 'Apply State' },
+      {
+        content: `${input.apply.progress.complete}/${input.apply.progress.total} complete`,
+        title: 'Apply Progress',
+      },
+      { content: task.rawLine, title: 'Current Task' },
+      { content: task.sectionTitle, title: 'Task Group' },
+      { content: input.context.get('proposal') ?? '', title: 'Proposal' },
+      { content: input.context.get('design') ?? '', title: 'Design' },
+      { content: input.context.get('specs') ?? '', title: 'Specs' },
+      { content: input.context.get('tasks') ?? '', title: 'Tasks' },
+    ],
+  }
+}
+
+function splitTasksMd(tasksMd: string) {
+  return {
+    lineEnding: tasksMd.includes('\r\n') ? '\r\n' : '\n',
+    lines: tasksMd.split(/\r?\n/),
+  }
+}
+
+function getTaskLineIndex(lines: string[], task: OpenSpecTask) {
+  let currentOrdinal = 0
+  for (const [index, line] of lines.entries()) {
+    if (!line.match(/^[-*]\s+\[[ x]\]\s+/i)) {
+      continue
+    }
+    currentOrdinal += 1
+    if (currentOrdinal === task.ordinal) {
+      return index
+    }
+  }
+  throw new Error(`Task line not found for handle: ${task.handle}`)
+}
+
+function isTaskChecked(tasksMd: string, task: OpenSpecTask) {
+  const { lines } = splitTasksMd(tasksMd)
+  const line = lines[getTaskLineIndex(lines, task)]
+  if (!line) {
+    return false
+  }
+  return /^[-*]\s+\[x\]\s+/i.test(line)
+}
+
+async function updateTaskCheckbox(
+  tasksPath: string,
+  task: OpenSpecTask,
+  checked: boolean,
+) {
+  const content = await readFile(tasksPath, 'utf8')
+  const { lineEnding, lines } = splitTasksMd(content)
+  const targetIndex = getTaskLineIndex(lines, task)
+  const targetLine = lines[targetIndex]
+  if (!targetLine) {
+    throw new Error(`Task line not found for handle: ${task.handle}`)
+  }
+  const pattern = /^([-*]\s+)\[[ x]\](\s+(?:\S.*)?)$/i
+  const match = targetLine.match(pattern)
+  if (!match) {
+    throw new Error(`Invalid task line: ${targetLine}`)
+  }
+  const replacementCheckbox = checked ? '[X]' : '[ ]'
+  lines[targetIndex] = `${match[1]}${replacementCheckbox}${match[2]}`
+  await writeFile(tasksPath, lines.join(lineEnding))
+}
+
+export interface CreateOpenSpecSessionInput extends OpenTaskSourceInput {
+  tasks: OpenSpecTask[]
+}
+
+export function createOpenSpecSession(
+  input: CreateOpenSpecSessionInput,
+): TaskSourceSession {
+  const tasksPath = path.join(input.featureDir, 'tasks.md')
+  const tasksByHandle = new Map(input.tasks.map((task) => [task.handle, task]))
+
+  const getTask = (taskHandle: string) => {
+    const task = tasksByHandle.get(taskHandle)
+    if (!task) {
+      throw new Error(`Unknown task selector: ${taskHandle}`)
+    }
+    return task
+  }
+
+  const loadApplyContext = async () => {
+    const apply = await readOpenSpecApplyInstructions({
+      changeName: input.featureId,
+      workspaceRoot: input.workspaceRoot,
+    })
+    const context = await readContextFileMap(
+      input.featureDir,
+      apply.contextFiles,
+    )
+    return {
+      apply,
+      context,
+    }
+  }
+
+  return {
+    async applyTaskCompletion(taskHandle: string) {
+      const task = getTask(taskHandle)
+      if (await this.isTaskCompleted(taskHandle)) {
+        return
+      }
+      await updateTaskCheckbox(tasksPath, task, true)
+    },
+    buildCommitSubject(taskHandle: string) {
+      const task = getTask(taskHandle)
+      return `Task ${input.featureId}/${task.handle}: ${task.title}`
+    },
+    async buildImplementPrompt(args) {
+      const task = getTask(args.taskHandle)
+      const applyContext = await loadApplyContext()
+      return createImplementPrompt(task, {
+        ...applyContext,
+        featureId: input.featureId,
+      })
+    },
+    async buildReviewPrompt(args) {
+      const task = getTask(args.taskHandle)
+      const applyContext = await loadApplyContext()
+      void args
+      return createReviewPrompt(task, {
+        ...applyContext,
+        featureId: input.featureId,
+      })
+    },
+    async getCompletionCriteria(taskHandle: string) {
+      return [getTask(taskHandle).title]
+    },
+    getTaskDependencies(taskHandle: string) {
+      void taskHandle
+      return []
+    },
+    async isTaskCompleted(taskHandle: string) {
+      const task = getTask(taskHandle)
+      const tasksMd = await readFile(tasksPath, 'utf8')
+      return isTaskChecked(tasksMd, task)
+    },
+    listTasks() {
+      return input.tasks.map((task) => task.handle)
+    },
+    resolveTaskSelector(selector: string) {
+      if (tasksByHandle.has(selector)) {
+        return selector
+      }
+      if (!selector.match(/^\d+$/)) {
+        throw new Error(`Unknown task selector: ${selector}`)
+      }
+      const ordinal = Number(selector)
+      const task = input.tasks.find((item) => item.ordinal === ordinal)
+      if (!task) {
+        throw new Error(`Unknown task selector: ${selector}`)
+      }
+      return task.handle
+    },
+    async revertTaskCompletion(taskHandle: string) {
+      const task = getTask(taskHandle)
+      if (!(await this.isTaskCompleted(taskHandle))) {
+        return
+      }
+      await updateTaskCheckbox(tasksPath, task, false)
+    },
+  }
+}

package/src/task-sources/openspec/source.ts

@@ -0,0 +1,59 @@
+import path from 'node:path'
+
+import * as fsExtra from 'fs-extra'
+
+import { readOpenSpecStatus } from './cli-json'
+import { readContextFileMap } from './context-files'
+import { parseTasksMd } from './parse-tasks-md'
+import { createOpenSpecSession } from './session'
+
+import type { OpenTaskSourceInput, TaskSource } from '../types'
+
+async function assertRequiredChangeFiles(featureDir: string) {
+  for (const fileName of ['proposal.md', 'design.md', 'tasks.md']) {
+    const filePath = path.join(featureDir, fileName)
+    const exists = await fsExtra.pathExists(filePath)
+    if (!exists) {
+      throw new Error(`Missing required change file: ${filePath}`)
+    }
+  }
+
+  const context = await readContextFileMap(featureDir, {
+    specs: 'specs/**/*.md',
+  })
+  if (!(context.get('specs') ?? '').trim()) {
+    throw new Error(`Missing required change specs under: ${featureDir}/specs`)
+  }
+}
+
+async function assertOpenSpecReady(input: OpenTaskSourceInput) {
+  const status = await readOpenSpecStatus({
+    changeName: input.featureId,
+    workspaceRoot: input.workspaceRoot,
+  })
+
+  const allApplyRequirementsReady = status.applyRequires.every((artifactId) => {
+    const artifact = status.artifacts.find((item) => item.id === artifactId)
+    return artifact?.status === 'done'
+  })
+
+  if (allApplyRequirementsReady) {
+    return
+  }
+  throw new Error(
+    `OpenSpec change is not ready for apply instructions: ${input.featureId}`,
+  )
+}
+
+export const openspecTaskSource: TaskSource = {
+  name: 'openspec',
+  async open(input: OpenTaskSourceInput) {
+    await assertRequiredChangeFiles(input.featureDir)
+    await assertOpenSpecReady(input)
+    const tasks = await parseTasksMd(path.join(input.featureDir, 'tasks.md'))
+    return createOpenSpecSession({
+      ...input,
+      tasks,
+    })
+  },
+}

package/src/task-sources/registry.ts

@@ -0,0 +1,22 @@
+import { openspecTaskSource } from './openspec/source'
+import { specKitTaskSource } from './spec-kit/source'
+
+import type { TaskSource } from './types'
+
+export function getTaskSource(name: string): TaskSource {
+  if (name === 'spec-kit') {
+    return specKitTaskSource
+  }
+  if (name === 'openspec') {
+    return openspecTaskSource
+  }
+
+  throw new Error(`Unknown task source: ${name}`)
+}
+
+export async function openTaskSource(
+  name: string,
+  input: Parameters<TaskSource['open']>[0],
+) {
+  return getTaskSource(name).open(input)
+}

package/src/task-sources/spec-kit/parse-tasks-md.ts

@@ -0,0 +1,48 @@
+import { readFile } from 'node:fs/promises'
+
+export interface SpecKitTask {
+  id: string
+  phase: string
+  rawLine: string
+  title: string
+}
+
+function createTask(line: string, phase: string): SpecKitTask {
+  const match = line.match(
+    /^- \[[ xX]\] (T\d{3,})(?: \[P\])?(?: \[[A-Z]{2,}\d+\])? (.+)$/,
+  )
+  if (!match) {
+    throw new Error(`Invalid task line: ${line}`)
+  }
+  return {
+    id: match[1]!,
+    phase,
+    rawLine: line,
+    title: match[2]!,
+  }
+}
+
+export async function parseTasksMd(tasksPath: string): Promise<SpecKitTask[]> {
+  const content = await readFile(tasksPath, 'utf8')
+  const lines = content.split(/\r?\n/)
+  const tasks: SpecKitTask[] = []
+  let currentPhase = 'unknown'
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd()
+    if (line.startsWith('## ')) {
+      currentPhase = line.replace(/^##\s+/, '').trim()
+      continue
+    }
+
+    if (line.startsWith('- [') && line.includes(' T')) {
+      tasks.push(createTask(line, currentPhase))
+    }
+  }
+
+  if (tasks.length === 0) {
+    throw new Error('No tasks found in tasks.md')
+  }
+
+  return tasks
+}

package/src/task-sources/spec-kit/session.ts

@@ -0,0 +1,174 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import * as fsExtra from 'fs-extra'
+
+import type {
+  OpenTaskSourceInput,
+  TaskPrompt,
+  TaskSourceSession,
+} from '../types'
+import type { SpecKitTask } from './parse-tasks-md'
+
+async function readRequiredTextFile(filePath: string) {
+  const exists = await fsExtra.pathExists(filePath)
+  if (!exists) {
+    throw new Error(`Missing required feature file: ${filePath}`)
+  }
+  return readFile(filePath, 'utf8')
+}
+
+function isTaskChecked(tasksMd: string, taskId: string) {
+  const pattern = new RegExp(String.raw`^- \[[Xx]\] ${taskId}(?=\b)`, 'm')
+  return pattern.test(tasksMd)
+}
+
+async function updateTaskCheckbox(
+  tasksPath: string,
+  taskHandle: string,
+  checked: boolean,
+) {
+  const content = await readFile(tasksPath, 'utf8')
+  const pattern = new RegExp(String.raw`^- \[[ Xx]\] ${taskHandle}(?=\b)`, 'm')
+  const replacement = checked ? `- [X] ${taskHandle}` : `- [ ] ${taskHandle}`
+  await writeFile(tasksPath, content.replace(pattern, replacement))
+}
+
+function createImplementPrompt(
+  task: SpecKitTask,
+  input: {
+    plan: string
+    spec: string
+    tasks: string
+  },
+): TaskPrompt {
+  return {
+    instructions: [
+      'Implement only the current task.',
+      'Use the provided source documents as the source of truth.',
+      'Modify only the files that are reasonably required for the current task.',
+      'Do not modify tasks.md.',
+      'Do not move to the next task.',
+      'Do not declare the task finalized.',
+      'Return structured output only.',
+    ],
+    sections: [
+      { content: task.rawLine, title: 'Task' },
+      { content: task.phase, title: 'Phase' },
+      { content: input.spec, title: 'Spec' },
+      { content: input.plan, title: 'Plan' },
+      { content: input.tasks, title: 'Tasks' },
+    ],
+  }
+}
+
+function createReviewPrompt(
+  task: SpecKitTask,
+  input: {
+    plan: string
+    spec: string
+    tasks: string
+  },
+): TaskPrompt {
+  return {
+    instructions: [
+      'Review only the current task.',
+      'Use the provided source documents to judge whether the task matches the intended implementation.',
+      'Evaluate the task description, source documents, actual changed files, and overall risk.',
+      'Only return verdict "pass" when the current task is satisfied by the implementation.',
+      'acceptanceChecks must stay consistent with the current task description.',
+      'Do not expand the review to unrelated files or repository-wide history.',
+    ],
+    sections: [
+      { content: task.rawLine, title: 'Task' },
+      { content: task.phase, title: 'Phase' },
+      { content: input.spec, title: 'Spec' },
+      { content: input.plan, title: 'Plan' },
+      { content: input.tasks, title: 'Tasks' },
+    ],
+  }
+}
+
+export interface CreateSpecKitSessionInput extends OpenTaskSourceInput {
+  tasks: SpecKitTask[]
+}
+
+export function createSpecKitSession(
+  input: CreateSpecKitSessionInput,
+): TaskSourceSession {
+  const tasksPath = path.join(input.featureDir, 'tasks.md')
+  const planPath = path.join(input.featureDir, 'plan.md')
+  const specPath = path.join(input.featureDir, 'spec.md')
+  const tasksById = new Map(input.tasks.map((task) => [task.id, task]))
+
+  const getTask = (taskHandle: string) => {
+    const task = tasksById.get(taskHandle)
+    if (!task) {
+      throw new Error(`Unknown task selector: ${taskHandle}`)
+    }
+    return task
+  }
+
+  const loadSharedDocs = async () => {
+    const [plan, spec, tasks] = await Promise.all([
+      readRequiredTextFile(planPath),
+      readRequiredTextFile(specPath),
+      readRequiredTextFile(tasksPath),
+    ])
+    return {
+      plan,
+      spec,
+      tasks,
+    }
+  }
+
+  return {
+    async applyTaskCompletion(taskHandle: string) {
+      if (await this.isTaskCompleted(taskHandle)) {
+        return
+      }
+      await updateTaskCheckbox(tasksPath, taskHandle, true)
+    },
+    buildCommitSubject(taskHandle: string) {
+      const task = getTask(taskHandle)
+      return `Task ${task.id}: ${task.title}`
+    },
+    async buildImplementPrompt(args) {
+      const task = getTask(args.taskHandle)
+      const docs = await loadSharedDocs()
+      return createImplementPrompt(task, docs)
+    },
+    async buildReviewPrompt(args) {
+      const task = getTask(args.taskHandle)
+      const docs = await loadSharedDocs()
+      void args
+      return createReviewPrompt(task, docs)
+    },
+    async getCompletionCriteria(taskHandle: string) {
+      return [getTask(taskHandle).title]
+    },
+    getTaskDependencies(taskHandle: string) {
+      void taskHandle
+      return []
+    },
+    async isTaskCompleted(taskHandle: string) {
+      const tasksMd = await readRequiredTextFile(tasksPath)
+      return isTaskChecked(tasksMd, taskHandle)
+    },
+    listTasks() {
+      return input.tasks.map((task) => task.id)
+    },
+    resolveTaskSelector(selector: string) {
+      if (!tasksById.has(selector)) {
+        throw new Error(`Unknown task selector: ${selector}`)
+      }
+      return selector
+    },
+    async revertTaskCompletion(taskHandle: string) {
+      if (!(await this.isTaskCompleted(taskHandle))) {
+        return
+      }
+      await updateTaskCheckbox(tasksPath, taskHandle, false)
+    },
+  }
+}

package/src/task-sources/spec-kit/source.ts

@@ -0,0 +1,30 @@
+import path from 'node:path'
+
+import * as fsExtra from 'fs-extra'
+
+import { parseTasksMd } from './parse-tasks-md'
+import { createSpecKitSession } from './session'
+
+import type { OpenTaskSourceInput, TaskSource } from '../types'
+
+async function assertRequiredFeatureFiles(featureDir: string) {
+  for (const fileName of ['spec.md', 'plan.md', 'tasks.md']) {
+    const filePath = path.join(featureDir, fileName)
+    const fileExists = await fsExtra.pathExists(filePath)
+    if (!fileExists) {
+      throw new Error(`Missing required feature file: ${filePath}`)
+    }
+  }
+}
+
+export const specKitTaskSource: TaskSource = {
+  name: 'spec-kit',
+  async open(input: OpenTaskSourceInput) {
+    await assertRequiredFeatureFiles(input.featureDir)
+    const tasks = await parseTasksMd(path.join(input.featureDir, 'tasks.md'))
+    return createSpecKitSession({
+      ...input,
+      tasks,
+    })
+  },
+}

package/src/task-sources/types.ts

@@ -0,0 +1,47 @@
+import type { ImplementOutput, ReviewFinding } from '../types'
+
+export type TaskSourceName = string
+
+export interface TaskPrompt {
+  instructions: string[]
+  sections: {
+    content: string
+    title: string
+  }[]
+}
+
+export interface TaskSourceSession {
+  applyTaskCompletion: (taskHandle: string) => Promise<void>
+  buildCommitSubject: (taskHandle: string) => string
+  buildImplementPrompt: (input: {
+    attempt: number
+    generation: number
+    lastFindings: ReviewFinding[]
+    taskHandle: string
+  }) => Promise<TaskPrompt>
+  buildReviewPrompt: (input: {
+    actualChangedFiles: string[]
+    attempt: number
+    generation: number
+    implement: ImplementOutput
+    lastFindings: ReviewFinding[]
+    taskHandle: string
+  }) => Promise<TaskPrompt>
+  getCompletionCriteria: (taskHandle: string) => Promise<string[]>
+  getTaskDependencies: (taskHandle: string) => string[]
+  isTaskCompleted: (taskHandle: string) => Promise<boolean>
+  listTasks: () => string[]
+  resolveTaskSelector: (selector: string) => string
+  revertTaskCompletion: (taskHandle: string) => Promise<void>
+}
+
+export interface OpenTaskSourceInput {
+  featureDir: string
+  featureId: string
+  workspaceRoot: string
+}
+
+export interface TaskSource {
+  readonly name: TaskSourceName
+  open: (input: OpenTaskSourceInput) => Promise<TaskSourceSession>
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+export type {
+  AcceptanceCheck,
+  FinalReport,
+  FinalReportTask,
+  ImplementArtifact,
+  ImplementOutput,
+  IntegrateArtifact,
+  PendingTaskState,
+  ReviewArtifact,
+  ReviewFinding,
+  ReviewOutput,
+  ReviewVerdict,
+  RunningStage,
+  RunningTaskState,
+  TaskGraph,
+  TaskState,
+  TaskStatus,
+  TaskTopologyEntry,
+  WorkflowEvent,
+  WorkflowEventType,
+  WorkflowState,
+} from './schema/index'
+
+export interface WorkspaceContext {
+  featureDir: string
+  featureId: string
+  runtimeDir: string
+  workspaceRoot: string
+}

package/src/utils/fs.ts

@@ -0,0 +1,31 @@
+import path from 'node:path'
+
+import * as fsExtra from 'fs-extra'
+
+export function isWithinRelativePath(targetPath: string, basePath: string) {
+  return targetPath === basePath || targetPath.startsWith(`${basePath}/`)
+}
+
+export function parsePorcelainPath(line: string) {
+  const rawPath = line.slice(3).trim()
+  const renamedSegments = rawPath.split(' -> ')
+  return renamedSegments.at(-1) ?? rawPath
+}
+
+export function filterPorcelainStatus(
+  lines: string[],
+  ignoredBasePath: string,
+) {
+  return lines.filter((line) => {
+    const filePath = parsePorcelainPath(line)
+    return !isWithinRelativePath(filePath, ignoredBasePath)
+  })
+}
+
+export async function writeJsonAtomic(filePath: string, value: unknown) {
+  const dir = path.dirname(filePath)
+  await fsExtra.ensureDir(dir)
+  const tempFile = `${filePath}.tmp`
+  await fsExtra.writeFile(tempFile, JSON.stringify(value, null, 2))
+  await fsExtra.rename(tempFile, filePath)
+}