task-while 0.0.1

package/src/core/runtime.ts

@@ -0,0 +1,175 @@
+import type { TaskSourceSession } from '../task-sources/types'
+import type {
+  FinalReport,
+  ImplementArtifact,
+  IntegrateArtifact,
+  ReviewArtifact,
+  TaskGraph,
+  WorkflowEvent,
+  WorkflowState,
+} from '../types'
+
+export interface AttemptArtifactKey {
+  attempt: number
+  generation: number
+  taskHandle: string
+}
+
+export interface WorkflowStore {
+  appendEvent: (event: WorkflowEvent) => Promise<void>
+  loadGraph: () => Promise<null | TaskGraph>
+  loadImplementArtifact: (
+    key: AttemptArtifactKey,
+  ) => Promise<ImplementArtifact | null>
+  loadReviewArtifact: (
+    key: AttemptArtifactKey,
+  ) => Promise<null | ReviewArtifact>
+  loadState: () => Promise<null | WorkflowState>
+  readReport: () => Promise<FinalReport | null>
+  reset: () => Promise<void>
+  saveGraph: (graph: TaskGraph) => Promise<void>
+  saveImplementArtifact: (artifact: ImplementArtifact) => Promise<void>
+  saveIntegrateArtifact: (artifact: IntegrateArtifact) => Promise<void>
+  saveReport: (report: FinalReport) => Promise<void>
+  saveReviewArtifact: (artifact: ReviewArtifact) => Promise<void>
+  saveState: (state: WorkflowState) => Promise<void>
+}
+
+export interface GitCheckoutBranchOptions {
+  create?: boolean
+  startPoint?: string
+}
+
+export interface GitCommitTaskInput {
+  message: string
+}
+
+export interface GitCommitTaskResult {
+  commitSha: string
+}
+
+export interface GitPushBranchOptions {
+  setUpstream?: boolean
+}
+
+export interface GitPort {
+  checkoutBranch: (
+    name: string,
+    options?: GitCheckoutBranchOptions,
+  ) => Promise<void>
+  checkoutRemoteBranch: (name: string) => Promise<void>
+  commitTask: (input: GitCommitTaskInput) => Promise<GitCommitTaskResult>
+  deleteLocalBranch: (name: string) => Promise<void>
+  getChangedFilesSinceHead: () => Promise<string[]>
+  getCurrentBranch: () => Promise<string>
+  getHeadSha: () => Promise<string>
+  getHeadSubject: () => Promise<string>
+  getHeadTimestamp: () => Promise<string>
+  pullFastForward: (branch: string) => Promise<void>
+  pushBranch: (name: string, options?: GitPushBranchOptions) => Promise<void>
+  requireCleanWorktree: () => Promise<void>
+}
+
+export interface PullRequestRef {
+  number: number
+  title: string
+  url: string
+}
+
+export interface MergedPullRequestRef extends PullRequestRef {
+  mergeCommitSha: string
+}
+
+export interface PullRequestReaction {
+  content: string
+  createdAt: string
+  userLogin: string
+}
+
+export interface PullRequestReviewSummary {
+  body: string
+  id: number
+  state: string
+  submittedAt: null | string
+  url: string
+  userLogin: string
+}
+
+export interface PullRequestDiscussionComment {
+  body: string
+  createdAt: string
+  id: number
+  url: string
+  userLogin: string
+}
+
+export interface PullRequestReviewThreadComment {
+  body: string
+  createdAt: string
+  line: null | number
+  path: string
+  url: string
+  userLogin: string
+}
+
+export interface PullRequestReviewThread {
+  comments: PullRequestReviewThreadComment[]
+  id: string
+  isOutdated: boolean
+  isResolved: boolean
+}
+
+export interface PullRequestSnapshot {
+  changedFiles: string[]
+  discussionComments: PullRequestDiscussionComment[]
+  reactions: PullRequestReaction[]
+  reviewSummaries: PullRequestReviewSummary[]
+  reviewThreads: PullRequestReviewThread[]
+}
+
+export interface GitHubPort {
+  createPullRequest: (input: CreatePullRequestInput) => Promise<PullRequestRef>
+  findMergedPullRequestByHeadBranch: (
+    input: FindMergedPullRequestByHeadBranchInput,
+  ) => Promise<MergedPullRequestRef | null>
+  findOpenPullRequestByHeadBranch: (
+    input: FindOpenPullRequestByHeadBranchInput,
+  ) => Promise<null | PullRequestRef>
+  getPullRequestSnapshot: (
+    input: GetPullRequestSnapshotInput,
+  ) => Promise<PullRequestSnapshot>
+  squashMergePullRequest: (
+    input: SquashMergePullRequestInput,
+  ) => Promise<GitCommitTaskResult>
+}
+
+export interface CreatePullRequestInput {
+  baseBranch: string
+  body: string
+  headBranch: string
+  title: string
+}
+
+export interface FindMergedPullRequestByHeadBranchInput {
+  headBranch: string
+}
+
+export interface FindOpenPullRequestByHeadBranchInput {
+  headBranch: string
+}
+
+export interface GetPullRequestSnapshotInput {
+  pullRequestNumber: number
+}
+
+export interface SquashMergePullRequestInput {
+  pullRequestNumber: number
+  subject: string
+}
+
+export interface OrchestratorRuntime {
+  git: GitPort
+  github: GitHubPort
+  store: WorkflowStore
+  taskSource: TaskSourceSession
+}

package/src/core/task-topology.ts

@@ -0,0 +1,85 @@
+import type { TaskSourceSession } from '../task-sources/types'
+
+export interface TaskTopologyEntry {
+  commitSubject: string
+  dependsOn: string[]
+  handle: string
+}
+
+export interface TaskTopology {
+  featureId: string
+  maxIterations: number
+  tasks: TaskTopologyEntry[]
+}
+
+function ensureUniqueHandles(handles: string[]) {
+  const seen = new Set<string>()
+  for (const handle of handles) {
+    if (seen.has(handle)) {
+      throw new Error(`Duplicate task handle: ${handle}`)
+    }
+    seen.add(handle)
+  }
+}
+
+function ensureDependenciesExist(tasks: TaskTopologyEntry[]) {
+  const handles = new Set(tasks.map((task) => task.handle))
+  for (const task of tasks) {
+    for (const dependency of task.dependsOn) {
+      if (!handles.has(dependency)) {
+        throw new Error(
+          `Unknown dependency: ${dependency} for task ${task.handle}`,
+        )
+      }
+    }
+  }
+}
+
+function ensureAcyclic(tasks: TaskTopologyEntry[]) {
+  const graph = new Map(tasks.map((task) => [task.handle, task.dependsOn]))
+  const visiting = new Set<string>()
+  const visited = new Set<string>()
+
+  const visit = (handle: string) => {
+    if (visiting.has(handle)) {
+      throw new Error(`Dependency cycle detected at ${handle}`)
+    }
+    if (visited.has(handle)) {
+      return
+    }
+    visiting.add(handle)
+    for (const dependency of graph.get(handle) ?? []) {
+      visit(dependency)
+    }
+    visiting.delete(handle)
+    visited.add(handle)
+  }
+
+  for (const task of tasks) {
+    visit(task.handle)
+  }
+}
+
+export function buildTaskTopology(
+  session: TaskSourceSession,
+  featureId: string,
+  maxIterations: number,
+): TaskTopology {
+  const handles = session.listTasks()
+  ensureUniqueHandles(handles)
+
+  const tasks = handles.map((handle) => ({
+    commitSubject: session.buildCommitSubject(handle),
+    dependsOn: session.getTaskDependencies(handle),
+    handle,
+  }))
+
+  ensureDependenciesExist(tasks)
+  ensureAcyclic(tasks)
+
+  return {
+    featureId,
+    maxIterations,
+    tasks,
+  }
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+import { inspect } from 'node:util'
+
+import arg from 'arg'
+
+import { runBatchCommand } from './commands/batch'
+import { runCommand } from './commands/run'
+import { resolveWorkspaceContext } from './runtime/workspace-resolver'
+import { loadWorkflowConfig } from './workflow/config'
+
+interface PositionalArgs {
+  _: string[]
+}
+
+interface RunOptions {
+  feature?: string
+  untilTaskId?: string
+  verbose: boolean
+}
+
+interface BatchOptions {
+  configPath: string
+  verbose: boolean
+}
+
+function assertNoPositionalArgs(values: PositionalArgs) {
+  if (values._.length !== 0) {
+    throw new Error(`Unexpected positional arguments: ${values._.join(' ')}`)
+  }
+}
+
+function parseRunOptions(args: string[]) {
+  const values = arg(
+    {
+      '--feature': String,
+      '--until-task': String,
+      '--verbose': Boolean,
+    },
+    { argv: args },
+  )
+  assertNoPositionalArgs(values)
+  const options: RunOptions = {
+    verbose: values['--verbose'] ?? false,
+  }
+  if (values['--until-task']) {
+    options.untilTaskId = values['--until-task']
+  }
+  if (values['--feature']) {
+    options.feature = values['--feature']
+  }
+  return options
+}
+
+function parseBatchOptions(args: string[]) {
+  const values = arg(
+    {
+      '--config': String,
+      '--verbose': Boolean,
+    },
+    { argv: args },
+  )
+  assertNoPositionalArgs(values)
+  const configPath = values['--config']
+  if (!configPath) {
+    throw new Error('Missing required --config')
+  }
+  return {
+    configPath,
+    verbose: values['--verbose'] ?? false,
+  } satisfies BatchOptions
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  const [command = 'run', ...args] = argv
+  switch (command) {
+    case 'batch': {
+      const options = parseBatchOptions(args)
+      const result = await runBatchCommand({
+        configPath: options.configPath,
+        cwd: process.cwd(),
+        verbose: options.verbose,
+      })
+      process.stdout.write(
+        `${inspect(result, { colors: false, depth: null })}\n`,
+      )
+      return
+    }
+    case 'run': {
+      const options = parseRunOptions(args)
+      const config = await loadWorkflowConfig(process.cwd())
+      const context = await resolveWorkspaceContext({
+        cwd: process.cwd(),
+        ...(options.feature ? { feature: options.feature } : {}),
+        taskSource: config.task.source,
+      })
+      const result = await runCommand(context, {
+        config,
+        ...(options.untilTaskId ? { untilTaskId: options.untilTaskId } : {}),
+        verbose: options.verbose,
+      })
+      process.stdout.write(
+        `${inspect(result, { colors: false, depth: null })}\n`,
+      )
+      return
+    }
+    default:
+      throw new Error(`Unknown command: ${command}`)
+  }
+}
+
+export async function main() {
+  return runCli()
+}
+
+export function handleFatalError(error: unknown) {
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  )
+  process.exitCode = 1
+}
+
+void main().catch(handleFatalError)

package/src/prompts/implementer.ts

@@ -0,0 +1,18 @@
+import type { ImplementAgentInput } from '../agents/types'
+
+export async function buildImplementerPrompt(input: ImplementAgentInput) {
+  return [
+    'Return JSON only.',
+    ...input.prompt.instructions,
+    `Task Handle: ${input.taskHandle}`,
+    ...[
+      ...input.prompt.sections,
+      { content: String(input.attempt), title: 'Attempt' },
+      { content: String(input.generation), title: 'Generation' },
+      {
+        content: JSON.stringify(input.lastFindings),
+        title: 'Previous Findings',
+      },
+    ].map((section) => `${section.title}:\n${section.content}`),
+  ].join('\n\n')
+}

package/src/prompts/reviewer.ts

@@ -0,0 +1,26 @@
+import type { ReviewAgentInput } from '../agents/types'
+
+export async function buildReviewerPrompt(input: ReviewAgentInput) {
+  return [
+    'Return JSON only.',
+    ...input.prompt.instructions,
+    `Task Handle: ${input.taskHandle}`,
+    ...[
+      ...input.prompt.sections,
+      { content: String(input.attempt), title: 'Attempt' },
+      { content: String(input.generation), title: 'Generation' },
+      {
+        content: JSON.stringify(input.lastFindings),
+        title: 'Previous Findings',
+      },
+      {
+        content: JSON.stringify(input.actualChangedFiles),
+        title: 'Actual Changed Files',
+      },
+      {
+        content: JSON.stringify(input.implement),
+        title: 'Implement Result',
+      },
+    ].map((section) => `${section.title}:\n${section.content}`),
+  ].join('\n\n')
+}

package/src/runtime/fs-runtime.ts

@@ -0,0 +1,209 @@
+import { appendFile, readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import * as fsExtra from 'fs-extra'
+
+import {
+  validateFinalReport,
+  validateImplementArtifact,
+  validateIntegrateArtifact,
+  validateReviewArtifact,
+  validateTaskGraph,
+  validateWorkflowEvent,
+  validateWorkflowState,
+} from '../schema/index'
+import { writeJsonAtomic } from '../utils/fs'
+import { GitRuntime } from './git'
+import { GitHubRuntime } from './github'
+import { createRuntimePaths } from './path-layout'
+
+import type { AttemptArtifactKey, OrchestratorRuntime } from '../core/runtime'
+import type { TaskSourceSession } from '../task-sources/types'
+
+function createArtifactDir(
+  featureDir: string,
+  taskId: string,
+  generation: number,
+  attempt: number,
+) {
+  const runtimePaths = createRuntimePaths(featureDir)
+  return path.join(
+    runtimePaths.tasksDir,
+    taskId,
+    `g${generation}`,
+    `a${attempt}`,
+  )
+}
+
+async function readTextFileIfExists(filePath: string) {
+  const exists = await fsExtra.pathExists(filePath)
+  if (!exists) {
+    return null
+  }
+  return readFile(filePath, 'utf8')
+}
+
+async function readValidatedJsonFileIfExists<T>(
+  filePath: string,
+  validate: (value: unknown) => T,
+): Promise<null | T> {
+  const raw = await readTextFileIfExists(filePath)
+  if (raw === null) {
+    return null
+  }
+  return validate(JSON.parse(raw))
+}
+
+export interface CreateOrchestratorRuntimeInput {
+  featureDir: string
+  taskSource?: TaskSourceSession
+  workspaceRoot: string
+}
+
+export function createOrchestratorRuntime(
+  input: CreateOrchestratorRuntimeInput,
+): OrchestratorRuntime {
+  const runtimePaths = createRuntimePaths(input.featureDir)
+
+  return {
+    git: new GitRuntime(input.workspaceRoot, runtimePaths.runtimeDir),
+    github: new GitHubRuntime(input.workspaceRoot),
+    store: {
+      async appendEvent(event) {
+        const value = validateWorkflowEvent(event)
+        await fsExtra.ensureDir(path.dirname(runtimePaths.events))
+        await appendFile(runtimePaths.events, `${JSON.stringify(value)}\n`)
+      },
+      async loadGraph() {
+        return readValidatedJsonFileIfExists(
+          runtimePaths.graph,
+          validateTaskGraph,
+        )
+      },
+      async loadImplementArtifact(key: AttemptArtifactKey) {
+        const filePath = path.join(
+          createArtifactDir(
+            input.featureDir,
+            key.taskHandle,
+            key.generation,
+            key.attempt,
+          ),
+          'implement.json',
+        )
+        return readValidatedJsonFileIfExists(
+          filePath,
+          validateImplementArtifact,
+        )
+      },
+      async loadReviewArtifact(key: AttemptArtifactKey) {
+        const filePath = path.join(
+          createArtifactDir(
+            input.featureDir,
+            key.taskHandle,
+            key.generation,
+            key.attempt,
+          ),
+          'review.json',
+        )
+        return readValidatedJsonFileIfExists(filePath, validateReviewArtifact)
+      },
+      async loadState() {
+        return readValidatedJsonFileIfExists(
+          runtimePaths.state,
+          validateWorkflowState,
+        )
+      },
+      async readReport() {
+        return readValidatedJsonFileIfExists(
+          runtimePaths.report,
+          validateFinalReport,
+        )
+      },
+      async reset() {
+        await fsExtra.remove(runtimePaths.runtimeDir)
+      },
+      async saveGraph(graph) {
+        await writeJsonAtomic(runtimePaths.graph, validateTaskGraph(graph))
+      },
+      async saveImplementArtifact(artifact) {
+        const value = validateImplementArtifact(artifact)
+        const targetPath = path.join(
+          createArtifactDir(
+            input.featureDir,
+            artifact.taskHandle,
+            artifact.generation,
+            artifact.attempt,
+          ),
+          'implement.json',
+        )
+        await writeJsonAtomic(targetPath, value)
+      },
+      async saveIntegrateArtifact(artifact) {
+        const value = validateIntegrateArtifact(artifact)
+        const targetPath = path.join(
+          createArtifactDir(
+            input.featureDir,
+            artifact.taskHandle,
+            artifact.generation,
+            artifact.attempt,
+          ),
+          'integrate.json',
+        )
+        await writeJsonAtomic(targetPath, value)
+      },
+      async saveReport(report) {
+        await writeJsonAtomic(runtimePaths.report, validateFinalReport(report))
+      },
+      async saveReviewArtifact(artifact) {
+        const value = validateReviewArtifact(artifact)
+        const targetPath = path.join(
+          createArtifactDir(
+            input.featureDir,
+            artifact.taskHandle,
+            artifact.generation,
+            artifact.attempt,
+          ),
+          'review.json',
+        )
+        await writeJsonAtomic(targetPath, value)
+      },
+      async saveState(state) {
+        await writeJsonAtomic(runtimePaths.state, validateWorkflowState(state))
+      },
+    },
+    taskSource:
+      input.taskSource ??
+      ({
+        async applyTaskCompletion() {
+          throw new Error('task source is not configured')
+        },
+        buildCommitSubject() {
+          throw new Error('task source is not configured')
+        },
+        async buildImplementPrompt() {
+          throw new Error('task source is not configured')
+        },
+        async buildReviewPrompt() {
+          throw new Error('task source is not configured')
+        },
+        async getCompletionCriteria() {
+          throw new Error('task source is not configured')
+        },
+        getTaskDependencies() {
+          throw new Error('task source is not configured')
+        },
+        async isTaskCompleted() {
+          throw new Error('task source is not configured')
+        },
+        listTasks() {
+          throw new Error('task source is not configured')
+        },
+        resolveTaskSelector() {
+          throw new Error('task source is not configured')
+        },
+        async revertTaskCompletion() {
+          throw new Error('task source is not configured')
+        },
+      } satisfies TaskSourceSession),
+  }
+}