task-while 0.0.1

package/src/workflow/config.ts

@@ -0,0 +1,127 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { parse } from 'yaml'
+import { z } from 'zod'
+
+import {
+  claudeProviderOptionsSchema,
+  codexProviderOptionsSchema,
+  type WorkflowRoleProviderOptions,
+} from '../agents/provider-options'
+
+const workflowModeSchema = z.enum(['direct', 'pull-request'])
+
+const defaultWorkflowRole: WorkflowRoleProviderOptions = {
+  provider: 'codex',
+}
+
+const workflowRoleProviderSchema = z.discriminatedUnion('provider', [
+  z
+    .object({
+      provider: z.literal('claude'),
+    })
+    .extend(claudeProviderOptionsSchema.shape)
+    .strict(),
+  z
+    .object({
+      provider: z.literal('codex'),
+    })
+    .extend(codexProviderOptionsSchema.shape)
+    .strict(),
+])
+
+const workflowRoleSchema = z.preprocess((value) => {
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const role = value as Record<string, unknown>
+    if (!('provider' in role)) {
+      return {
+        ...role,
+        provider: 'codex',
+      }
+    }
+  }
+  return value
+}, workflowRoleProviderSchema)
+
+const workflowRolesSchema = z
+  .object({
+    implementer: workflowRoleSchema.default(defaultWorkflowRole),
+    reviewer: workflowRoleSchema.default(defaultWorkflowRole),
+  })
+  .strict()
+
+const taskConfigSchema = z
+  .object({
+    maxIterations: z.number().int().min(1).max(20).default(5),
+    source: z.string().trim().min(1).default('spec-kit'),
+  })
+  .strict()
+
+const workflowConfigSchema = z
+  .object({
+    task: taskConfigSchema.default({}),
+    workflow: z
+      .object({
+        mode: workflowModeSchema.default('direct'),
+        roles: workflowRolesSchema.default({}),
+      })
+      .strict()
+      .default({}),
+  })
+  .strict()
+  .default({})
+
+export type WorkflowMode = 'direct' | 'pull-request'
+
+export type WorkflowProvider = WorkflowRoleProviderOptions['provider']
+export type WorkflowRoleConfig = WorkflowRoleProviderOptions
+
+export interface WorkflowRolesConfig {
+  implementer: WorkflowRoleConfig
+  reviewer: WorkflowRoleConfig
+}
+
+export interface WorkflowSettingsConfig {
+  mode: WorkflowMode
+  roles: WorkflowRolesConfig
+}
+
+export interface TaskSettingsConfig {
+  maxIterations: number
+  source: string
+}
+
+export interface WorkflowConfig {
+  task: TaskSettingsConfig
+  workflow: WorkflowSettingsConfig
+}
+
+export async function loadWorkflowConfig(
+  workspaceRoot: string,
+): Promise<WorkflowConfig> {
+  const configPath = path.join(workspaceRoot, 'while.yaml')
+  let rawConfig: unknown = {}
+
+  try {
+    const configSource = await readFile(configPath, 'utf8')
+    rawConfig = parse(configSource) ?? {}
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw error
+    }
+  }
+
+  const parsedConfig = workflowConfigSchema.parse(rawConfig)
+
+  return {
+    task: {
+      maxIterations: parsedConfig.task.maxIterations,
+      source: parsedConfig.task.source,
+    },
+    workflow: {
+      mode: parsedConfig.workflow.mode,
+      roles: parsedConfig.workflow.roles,
+    },
+  }
+}

package/src/workflow/direct-preset.ts

@@ -0,0 +1,44 @@
+import { finalizeTaskCheckbox } from './finalize-task-checkbox'
+
+import type { ReviewerProvider } from '../agents/types'
+import type { DirectWorkflowPreset } from './preset'
+
+export interface CreateDirectWorkflowPresetInput {
+  reviewer: ReviewerProvider
+}
+
+export function createDirectWorkflowPreset(
+  input: CreateDirectWorkflowPresetInput,
+): DirectWorkflowPreset {
+  return {
+    mode: 'direct',
+    async integrate(context) {
+      const { commitSha } = await finalizeTaskCheckbox({
+        commitMessage: context.commitMessage,
+        runtime: context.runtime,
+        taskHandle: context.taskHandle,
+      })
+      return {
+        kind: 'completed',
+        result: {
+          commitSha,
+          summary: 'integrated',
+        },
+      }
+    },
+    async review(context) {
+      const review = await input.reviewer.review({
+        actualChangedFiles: context.actualChangedFiles,
+        attempt: context.attempt,
+        generation: context.generation,
+        implement: context.implement,
+        lastFindings: context.lastFindings,
+        prompt: context.prompt,
+        taskHandle: context.taskHandle,
+      })
+      return review.verdict === 'pass'
+        ? { kind: 'approved', review }
+        : { kind: 'rejected', review }
+    },
+  }
+}

package/src/workflow/finalize-task-checkbox.ts

@@ -0,0 +1,24 @@
+import type { OrchestratorRuntime } from '../core/runtime'
+
+export interface FinalizeTaskCheckboxInput {
+  commitMessage: string
+  runtime: OrchestratorRuntime
+  taskHandle: string
+}
+
+export async function finalizeTaskCheckbox(input: FinalizeTaskCheckboxInput) {
+  try {
+    await input.runtime.taskSource.applyTaskCompletion(input.taskHandle)
+    return await input.runtime.git.commitTask({
+      message: input.commitMessage,
+    })
+  } catch (error) {
+    let reason = `Task commit failed: ${error instanceof Error ? error.message : String(error)}`
+    try {
+      await input.runtime.taskSource.revertTaskCompletion(input.taskHandle)
+    } catch (rollbackError) {
+      reason = `${reason}; task completion rollback failed: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`
+    }
+    throw new Error(reason)
+  }
+}

package/src/workflow/preset.ts

@@ -0,0 +1,86 @@
+import type { WorkflowRoleProviders } from '../agents/types'
+import type { OrchestratorRuntime } from '../core/runtime'
+import type { TaskPrompt } from '../task-sources/types'
+import type { ImplementOutput, ReviewFinding, ReviewOutput } from '../types'
+
+export type WorkflowMode = 'direct' | 'pull-request'
+
+export interface DirectReviewPhaseContext {
+  actualChangedFiles: string[]
+  attempt: number
+  commitMessage: string
+  generation: number
+  implement: ImplementOutput
+  lastFindings: ReviewFinding[]
+  prompt: TaskPrompt
+  taskHandle: string
+}
+
+export interface PullRequestReviewPhaseContext {
+  attempt: number
+  commitMessage: string
+  completionCriteria: string[]
+  generation?: number
+  implement?: ImplementOutput
+  lastFindings?: never[]
+  runtime: OrchestratorRuntime
+  taskHandle: string
+}
+
+export interface ApprovedReviewPhaseResult {
+  kind: 'approved'
+  review: ReviewOutput
+}
+
+export interface RejectedReviewPhaseResult {
+  kind: 'rejected'
+  review: ReviewOutput
+}
+
+export type ReviewPhaseResult =
+  | ApprovedReviewPhaseResult
+  | RejectedReviewPhaseResult
+
+export interface IntegratePhaseContext {
+  commitMessage: string
+  runtime: OrchestratorRuntime
+  taskHandle: string
+}
+
+export interface IntegratePhaseResult {
+  kind: 'completed'
+  result: IntegrateResult
+}
+
+export interface IntegrateResult {
+  commitSha: string
+  summary: string
+}
+
+export interface DirectWorkflowPreset {
+  integrate: (context: IntegratePhaseContext) => Promise<IntegratePhaseResult>
+  readonly mode: 'direct'
+  review: (context: DirectReviewPhaseContext) => Promise<ReviewPhaseResult>
+}
+
+export interface PullRequestWorkflowPreset {
+  integrate: (context: IntegratePhaseContext) => Promise<IntegratePhaseResult>
+  readonly mode: 'pull-request'
+  review: (context: PullRequestReviewPhaseContext) => Promise<ReviewPhaseResult>
+}
+
+export type WorkflowPreset = DirectWorkflowPreset | PullRequestWorkflowPreset
+
+export function isPullRequestWorkflowPreset(
+  preset: WorkflowPreset,
+): preset is PullRequestWorkflowPreset {
+  return preset.mode === 'pull-request'
+}
+
+export interface WorkflowRuntime {
+  preset: WorkflowPreset
+  roles: WorkflowRoleProviders
+}
+
+export { createDirectWorkflowPreset } from './direct-preset'
+export { createPullRequestWorkflowPreset } from './pull-request-preset'

package/src/workflow/pull-request-preset.ts

@@ -0,0 +1,312 @@
+import { finalizeTaskCheckbox } from './finalize-task-checkbox'
+
+import type {
+  PullRequestReviewResult,
+  RemoteReviewerProvider,
+} from '../agents/types'
+import type { OrchestratorRuntime, PullRequestRef } from '../core/runtime'
+import type {
+  IntegratePhaseResult,
+  PullRequestReviewPhaseContext,
+  PullRequestWorkflowPreset,
+  ReviewPhaseResult,
+} from './preset'
+
+const DEFAULT_BASE_BRANCH = 'main'
+const DEFAULT_REVIEW_POLL_INTERVAL_MS = 60_000
+
+function toTaskBranchName(commitMessage: string) {
+  const slug = commitMessage
+    .replace(/^Task\s+/i, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return `task/${slug}`
+}
+
+function createCheckpointCommitMessage(commitMessage: string, attempt: number) {
+  return `checkpoint: ${commitMessage} (attempt ${attempt})`
+}
+
+function createPullRequestBody(context: PullRequestReviewPhaseContext) {
+  return [
+    `Task: ${context.commitMessage}`,
+    `Attempt: ${context.attempt}`,
+    '',
+    'Managed by task-while.',
+  ].join('\n')
+}
+
+interface EnsureTaskBranchInput {
+  branchName: string
+  restoreFromRemote: boolean
+  runtime: OrchestratorRuntime
+}
+
+async function ensureTaskBranch(input: EnsureTaskBranchInput) {
+  const currentBranch = await input.runtime.git.getCurrentBranch()
+  if (currentBranch === input.branchName) {
+    return
+  }
+  try {
+    await input.runtime.git.checkoutBranch(input.branchName)
+  } catch {
+    if (input.restoreFromRemote) {
+      await input.runtime.git.checkoutRemoteBranch(input.branchName)
+      return
+    }
+    await input.runtime.git.checkoutBranch(input.branchName, {
+      create: true,
+      startPoint: DEFAULT_BASE_BRANCH,
+    })
+  }
+}
+
+interface EnsurePullRequestInput {
+  branchName: string
+  branchNeedsPush: boolean
+  context: PullRequestReviewPhaseContext
+  existingPullRequest: null | PullRequestRef
+}
+
+async function ensurePullRequest(
+  input: EnsurePullRequestInput,
+): Promise<PullRequestRef> {
+  let pullRequest = input.existingPullRequest
+
+  if (input.branchNeedsPush || !pullRequest) {
+    await input.context.runtime.git.pushBranch(input.branchName)
+  }
+
+  if (pullRequest) {
+    return pullRequest
+  }
+
+  pullRequest = await input.context.runtime.github.createPullRequest({
+    baseBranch: DEFAULT_BASE_BRANCH,
+    body: createPullRequestBody(input.context),
+    headBranch: input.branchName,
+    title: input.context.commitMessage,
+  })
+  return pullRequest
+}
+
+interface WaitForRemoteReviewInput {
+  checkpointStartedAt: string
+  context: PullRequestReviewPhaseContext
+  pullRequest: PullRequestRef
+  reviewer: RemoteReviewerProvider
+  sleep: SleepFunction
+}
+
+type SleepFunction = (ms: number) => Promise<void>
+
+async function waitForRemoteReview(
+  input: WaitForRemoteReviewInput,
+): Promise<ReviewPhaseResult> {
+  const evaluateReview = async () => {
+    const snapshot = await input.context.runtime.github.getPullRequestSnapshot({
+      pullRequestNumber: input.pullRequest.number,
+    })
+    return input.reviewer.evaluatePullRequestReview({
+      checkpointStartedAt: input.checkpointStartedAt,
+      completionCriteria: input.context.completionCriteria,
+      pullRequest: snapshot,
+      taskHandle: input.context.taskHandle,
+    })
+  }
+
+  let result: PullRequestReviewResult = await evaluateReview()
+  while (result.kind === 'pending') {
+    await input.sleep(DEFAULT_REVIEW_POLL_INTERVAL_MS)
+    result = await evaluateReview()
+  }
+  return result
+}
+
+function toLocalCleanupWarning(error: unknown) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+interface CleanupAfterMergeInput {
+  branchName: string
+  runtime: OrchestratorRuntime
+}
+
+async function cleanupAfterMerge(input: CleanupAfterMergeInput) {
+  const warnings: string[] = []
+  let onBaseBranch = false
+
+  try {
+    await input.runtime.git.checkoutBranch(DEFAULT_BASE_BRANCH)
+    onBaseBranch = true
+  } catch (error) {
+    warnings.push(
+      `checkout ${DEFAULT_BASE_BRANCH} failed: ${toLocalCleanupWarning(error)}`,
+    )
+  }
+
+  if (!onBaseBranch) {
+    return warnings
+  }
+
+  try {
+    await input.runtime.git.pullFastForward(DEFAULT_BASE_BRANCH)
+  } catch (error) {
+    warnings.push(
+      `pull ${DEFAULT_BASE_BRANCH} failed: ${toLocalCleanupWarning(error)}`,
+    )
+  }
+
+  try {
+    await input.runtime.git.deleteLocalBranch(input.branchName)
+  } catch (error) {
+    warnings.push(`delete local branch failed: ${toLocalCleanupWarning(error)}`)
+  }
+
+  return warnings
+}
+
+interface SummarizeIntegrateResultInput {
+  status: 'already integrated' | 'integrated'
+  warnings: string[]
+}
+
+function summarizeIntegrateResult(input: SummarizeIntegrateResultInput) {
+  return input.warnings.length === 0
+    ? input.status
+    : `${input.status}; local cleanup warning: ${input.warnings.join('; ')}`
+}
+
+export interface CreatePullRequestWorkflowPresetInput {
+  reviewer: RemoteReviewerProvider
+  sleep?: SleepFunction
+}
+
+export function createPullRequestWorkflowPreset(
+  input: CreatePullRequestWorkflowPresetInput,
+): PullRequestWorkflowPreset {
+  const sleep =
+    input.sleep ??
+    (async (ms: number) => {
+      await new Promise((resolve) => {
+        setTimeout(resolve, ms)
+      })
+    })
+
+  return {
+    mode: 'pull-request',
+    async integrate(context): Promise<IntegratePhaseResult> {
+      const branchName = toTaskBranchName(context.commitMessage)
+      const openPullRequest =
+        await context.runtime.github.findOpenPullRequestByHeadBranch({
+          headBranch: branchName,
+        })
+      if (openPullRequest) {
+        await ensureTaskBranch({
+          branchName,
+          restoreFromRemote: true,
+          runtime: context.runtime,
+        })
+        const taskChecked = await context.runtime.taskSource.isTaskCompleted(
+          context.taskHandle,
+        )
+        if (!taskChecked) {
+          await finalizeTaskCheckbox({
+            commitMessage: context.commitMessage,
+            runtime: context.runtime,
+            taskHandle: context.taskHandle,
+          })
+        }
+        await context.runtime.git.pushBranch(branchName)
+        const mergeResult = await context.runtime.github.squashMergePullRequest(
+          {
+            pullRequestNumber: openPullRequest.number,
+            subject: context.commitMessage,
+          },
+        )
+        const warnings = await cleanupAfterMerge({
+          branchName,
+          runtime: context.runtime,
+        })
+
+        return {
+          kind: 'completed',
+          result: {
+            commitSha: mergeResult.commitSha,
+            summary: summarizeIntegrateResult({
+              status: 'integrated',
+              warnings,
+            }),
+          },
+        }
+      }
+
+      const mergedPullRequest =
+        await context.runtime.github.findMergedPullRequestByHeadBranch({
+          headBranch: branchName,
+        })
+      if (!mergedPullRequest) {
+        throw new Error(
+          `Missing open or merged pull request for branch ${branchName}`,
+        )
+      }
+      const warnings = await cleanupAfterMerge({
+        branchName,
+        runtime: context.runtime,
+      })
+
+      return {
+        kind: 'completed',
+        result: {
+          commitSha: mergedPullRequest.mergeCommitSha,
+          summary: summarizeIntegrateResult({
+            status: 'already integrated',
+            warnings,
+          }),
+        },
+      }
+    },
+    async review(context): Promise<ReviewPhaseResult> {
+      const branchName = toTaskBranchName(context.commitMessage)
+      const checkpointMessage = createCheckpointCommitMessage(
+        context.commitMessage,
+        context.attempt,
+      )
+      const existingPullRequest =
+        await context.runtime.github.findOpenPullRequestByHeadBranch({
+          headBranch: branchName,
+        })
+      await ensureTaskBranch({
+        branchName,
+        restoreFromRemote: existingPullRequest !== null,
+        runtime: context.runtime,
+      })
+
+      const headSubject = await context.runtime.git.getHeadSubject()
+      if (headSubject !== checkpointMessage) {
+        await context.runtime.git.commitTask({
+          message: checkpointMessage,
+        })
+      }
+
+      const checkpointStartedAt = await context.runtime.git.getHeadTimestamp()
+      const pullRequest = await ensurePullRequest({
+        branchName,
+        branchNeedsPush: true,
+        context,
+        existingPullRequest,
+      })
+
+      return waitForRemoteReview({
+        checkpointStartedAt,
+        context,
+        pullRequest,
+        reviewer: input.reviewer,
+        sleep,
+      })
+    },
+  }
+}
+
+export { DEFAULT_REVIEW_POLL_INTERVAL_MS, toTaskBranchName }