task-while 0.0.1

package/src/runtime/github-pr-snapshot.ts

@@ -0,0 +1,139 @@
+import {
+  parseReviewThreadCommentsPage,
+  parseSnapshotPage,
+} from './github-pr-snapshot-decode'
+import {
+  buildReviewThreadCommentsArgs,
+  buildSnapshotArgs,
+} from './github-pr-snapshot-queries'
+
+import type {
+  PullRequestDiscussionComment,
+  PullRequestReaction,
+  PullRequestReviewSummary,
+  PullRequestReviewThread,
+  PullRequestSnapshot,
+} from '../core/runtime'
+
+export type RunGh = (args: string[]) => Promise<string>
+
+export interface GetPullRequestSnapshotViaGraphQLInput {
+  owner: string
+  pullRequestNumber: number
+  repo: string
+  runGh: RunGh
+}
+
+export async function getPullRequestSnapshotViaGraphQL(
+  input: GetPullRequestSnapshotViaGraphQLInput,
+): Promise<PullRequestSnapshot> {
+  const changedFiles: string[] = []
+  const discussionComments: PullRequestDiscussionComment[] = []
+  const reactions: PullRequestReaction[] = []
+  const reviewSummaries: PullRequestReviewSummary[] = []
+  const reviewThreads: PullRequestReviewThread[] = []
+  const cursors = {
+    comments: null as null | string,
+    files: null as null | string,
+    reactions: null as null | string,
+    reviews: null as null | string,
+    reviewThreads: null as null | string,
+  }
+  const includes = {
+    comments: true,
+    files: true,
+    reactions: true,
+    reviews: true,
+    reviewThreads: true,
+  }
+
+  while (
+    includes.comments ||
+    includes.files ||
+    includes.reactions ||
+    includes.reviews ||
+    includes.reviewThreads
+  ) {
+    const page = parseSnapshotPage(
+      await input.runGh(
+        buildSnapshotArgs({
+          commentsAfter: cursors.comments,
+          filesAfter: cursors.files,
+          includeComments: includes.comments,
+          includeFiles: includes.files,
+          includeReactions: includes.reactions,
+          includeReviews: includes.reviews,
+          includeReviewThreads: includes.reviewThreads,
+          number: input.pullRequestNumber,
+          owner: input.owner,
+          reactionsAfter: cursors.reactions,
+          repo: input.repo,
+          reviewsAfter: cursors.reviews,
+          reviewThreadsAfter: cursors.reviewThreads,
+        }),
+      ),
+      {
+        comments: includes.comments,
+        files: includes.files,
+        reactions: includes.reactions,
+        reviews: includes.reviews,
+        reviewThreads: includes.reviewThreads,
+      },
+    )
+
+    if (page.comments) {
+      discussionComments.push(...page.comments.nodes)
+      cursors.comments = page.comments.pageInfo.endCursor
+      includes.comments = page.comments.pageInfo.hasNextPage
+    }
+    if (page.files) {
+      changedFiles.push(...page.files.nodes)
+      cursors.files = page.files.pageInfo.endCursor
+      includes.files = page.files.pageInfo.hasNextPage
+    }
+    if (page.reactions) {
+      reactions.push(...page.reactions.nodes)
+      cursors.reactions = page.reactions.pageInfo.endCursor
+      includes.reactions = page.reactions.pageInfo.hasNextPage
+    }
+    if (page.reviews) {
+      reviewSummaries.push(...page.reviews.nodes)
+      cursors.reviews = page.reviews.pageInfo.endCursor
+      includes.reviews = page.reviews.pageInfo.hasNextPage
+    }
+    if (page.reviewThreads) {
+      for (const thread of page.reviewThreads.nodes) {
+        const comments = [...thread.comments]
+        let pageInfo = thread.commentsPageInfo
+        while (pageInfo.hasNextPage) {
+          const nextPage = parseReviewThreadCommentsPage(
+            await input.runGh(
+              buildReviewThreadCommentsArgs({
+                after: pageInfo.endCursor,
+                threadId: thread.id,
+              }),
+            ),
+          )
+          comments.push(...nextPage.nodes)
+          pageInfo = nextPage.pageInfo
+        }
+        reviewThreads.push({
+          id: thread.id,
+          comments,
+          isOutdated: thread.isOutdated,
+          isResolved: thread.isResolved,
+        })
+      }
+      cursors.reviewThreads = page.reviewThreads.pageInfo.endCursor
+      includes.reviewThreads = page.reviewThreads.pageInfo.hasNextPage
+    }
+  }
+
+  return {
+    changedFiles: changedFiles.filter(Boolean),
+    discussionComments,
+    reactions,
+    reviewSummaries,
+    reviewThreads,
+  }
+}

package/src/runtime/github.ts

@@ -0,0 +1,232 @@
+import { execa } from 'execa'
+
+import {
+  getPullRequestSnapshotViaGraphQL,
+  type RunGh,
+} from './github-pr-snapshot'
+
+import type {
+  CreatePullRequestInput,
+  FindMergedPullRequestByHeadBranchInput,
+  FindOpenPullRequestByHeadBranchInput,
+  GetPullRequestSnapshotInput,
+  GitHubPort,
+  MergedPullRequestRef,
+  PullRequestRef,
+  PullRequestSnapshot,
+  SquashMergePullRequestInput,
+} from '../core/runtime'
+
+async function defaultRunGh(args: string[], cwd: string) {
+  const env = process.env.GITHUB_BOT_TOKEN
+    ? {
+        ...process.env,
+        GH_TOKEN: process.env.GITHUB_BOT_TOKEN,
+      }
+    : process.env
+  const result = await execa('gh', args, { cwd, env })
+  return result.stdout.trim()
+}
+
+function asArray<T>(value: unknown): T[] {
+  return Array.isArray(value) ? (value as T[]) : []
+}
+
+function asNumber(value: unknown) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+function asString(value: unknown) {
+  return typeof value === 'string' ? value : ''
+}
+
+interface LoginLike {
+  login?: unknown
+}
+
+interface MergeCommitLike {
+  oid?: unknown
+}
+
+interface RepoViewPayload {
+  nameWithOwner?: unknown
+}
+
+function asOwnerLogin(value: unknown) {
+  if (typeof value === 'string') {
+    return value
+  }
+  if (value && typeof value === 'object' && 'login' in value) {
+    return asString((value as LoginLike).login)
+  }
+  return ''
+}
+
+export class GitHubRuntime implements GitHubPort {
+  private readonly runGh: RunGh
+
+  public constructor(
+    workspaceRoot: string,
+    runGh?: RunGh,
+    private readonly repoName?: string,
+  ) {
+    this.runGh = runGh ?? ((args) => defaultRunGh(args, workspaceRoot))
+  }
+
+  private async resolveRepo() {
+    if (this.repoName) {
+      return this.repoName
+    }
+    const payload = JSON.parse(
+      await this.runGh(['repo', 'view', '--json', 'nameWithOwner']),
+    ) as RepoViewPayload
+    return asString(payload.nameWithOwner)
+  }
+
+  private async resolveRepoOwner() {
+    const repo = await this.resolveRepo()
+    const [owner] = repo.split('/')
+    if (!owner) {
+      throw new Error(`Invalid GitHub repository name: ${repo}`)
+    }
+    return owner
+  }
+
+  public async createPullRequest(
+    input: CreatePullRequestInput,
+  ): Promise<PullRequestRef> {
+    await this.runGh([
+      'pr',
+      'create',
+      '--base',
+      input.baseBranch,
+      '--head',
+      input.headBranch,
+      '--title',
+      input.title,
+      '--body',
+      input.body,
+    ])
+    const created = await this.findOpenPullRequestByHeadBranch({
+      headBranch: input.headBranch,
+    })
+    if (!created) {
+      throw new Error(
+        `Could not resolve pull request after creating branch ${input.headBranch}`,
+      )
+    }
+    return created
+  }
+
+  public async findMergedPullRequestByHeadBranch(
+    input: FindMergedPullRequestByHeadBranchInput,
+  ): Promise<MergedPullRequestRef | null> {
+    const owner = await this.resolveRepoOwner()
+    const payload = JSON.parse(
+      await this.runGh([
+        'pr',
+        'list',
+        '--head',
+        input.headBranch,
+        '--state',
+        'merged',
+        '--json',
+        'number,title,url,mergeCommit,headRefName,headRepositoryOwner',
+      ]),
+    )
+    const pullRequests = asArray<Record<string, unknown>>(payload)
+    const match =
+      pullRequests.find(
+        (candidate) =>
+          asString(candidate.headRefName) === input.headBranch &&
+          asOwnerLogin(candidate.headRepositoryOwner) === owner,
+      ) ?? null
+    if (!match) {
+      return null
+    }
+    const mergeCommit = match.mergeCommit
+    const mergeCommitSha =
+      mergeCommit && typeof mergeCommit === 'object' && 'oid' in mergeCommit
+        ? asString((mergeCommit as MergeCommitLike).oid)
+        : ''
+    if (!mergeCommitSha) {
+      throw new Error(
+        `Merged pull request for branch ${input.headBranch} is missing mergeCommit`,
+      )
+    }
+    return {
+      mergeCommitSha,
+      number: asNumber(match.number),
+      title: asString(match.title),
+      url: asString(match.url),
+    }
+  }
+
+  public async findOpenPullRequestByHeadBranch(
+    input: FindOpenPullRequestByHeadBranchInput,
+  ): Promise<null | PullRequestRef> {
+    const owner = await this.resolveRepoOwner()
+    const payload = JSON.parse(
+      await this.runGh([
+        'pr',
+        'list',
+        '--head',
+        input.headBranch,
+        '--state',
+        'open',
+        '--json',
+        'number,title,url,headRefName,headRepositoryOwner',
+      ]),
+    )
+    const pullRequests = asArray<Record<string, unknown>>(payload)
+    const match =
+      pullRequests.find(
+        (candidate) =>
+          asString(candidate.headRefName) === input.headBranch &&
+          asOwnerLogin(candidate.headRepositoryOwner) === owner,
+      ) ?? null
+    if (!match) {
+      return null
+    }
+    return {
+      number: asNumber(match.number),
+      title: asString(match.title),
+      url: asString(match.url),
+    }
+  }
+
+  public async getPullRequestSnapshot(
+    input: GetPullRequestSnapshotInput,
+  ): Promise<PullRequestSnapshot> {
+    const repo = await this.resolveRepo()
+    const [owner, repoName] = repo.split('/')
+    if (!owner || !repoName) {
+      throw new Error(`Invalid GitHub repository name: ${repo}`)
+    }
+    return getPullRequestSnapshotViaGraphQL({
+      owner,
+      pullRequestNumber: input.pullRequestNumber,
+      repo: repoName,
+      runGh: this.runGh,
+    })
+  }
+
+  public async squashMergePullRequest(input: SquashMergePullRequestInput) {
+    const repo = await this.resolveRepo()
+    const commitSha = asString(
+      JSON.parse(
+        await this.runGh([
+          'api',
+          `repos/${repo}/pulls/${input.pullRequestNumber}/merge`,
+          '--method',
+          'PUT',
+          '-f',
+          'merge_method=squash',
+          '-f',
+          `commit_title=${input.subject}`,
+        ]),
+      ).sha,
+    )
+    return { commitSha }
+  }
+}

package/src/runtime/path-layout.ts

@@ -0,0 +1,13 @@
+import path from 'node:path'
+
+export function createRuntimePaths(featureDir: string) {
+  const runtimeDir = path.join(featureDir, '.while')
+  return {
+    events: path.join(runtimeDir, 'events.jsonl'),
+    graph: path.join(runtimeDir, 'graph.json'),
+    report: path.join(runtimeDir, 'report.json'),
+    runtimeDir,
+    state: path.join(runtimeDir, 'state.json'),
+    tasksDir: path.join(runtimeDir, 'tasks'),
+  }
+}

package/src/runtime/workspace-resolver.ts

@@ -0,0 +1,125 @@
+import path from 'node:path'
+
+import { execa } from 'execa'
+import * as fsExtra from 'fs-extra'
+
+import type { WorkspaceContext } from '../types'
+
+export interface ResolveWorkspaceContextInput {
+  cwd: string
+  feature?: string | undefined
+  taskSource?: string | undefined
+}
+
+function resolveFeatureRoot(workspaceRoot: string, taskSource: string) {
+  if (taskSource === 'openspec') {
+    return path.join(workspaceRoot, 'openspec', 'changes')
+  }
+  return path.join(workspaceRoot, 'specs')
+}
+
+async function resolveWorkspaceRoot(cwd: string, taskSource: string) {
+  const workspaceRoot = path.resolve(cwd)
+  const featureRoot = resolveFeatureRoot(workspaceRoot, taskSource)
+  const featureRootExists = await fsExtra.pathExists(featureRoot)
+  if (!featureRootExists) {
+    if (taskSource === 'openspec') {
+      throw new Error(
+        'Current working directory must contain an openspec/changes/ directory. Run task-while from the workspace root.',
+      )
+    }
+    throw new Error(
+      'Current working directory must contain a specs/ directory. Run task-while from the workspace root.',
+    )
+  }
+  return workspaceRoot
+}
+
+async function readFeatureDirs(workspaceRoot: string, taskSource: string) {
+  const featureRoot = resolveFeatureRoot(workspaceRoot, taskSource)
+  const entries = await fsExtra.readdir(featureRoot, {
+    withFileTypes: true,
+  })
+  return entries
+    .filter((entry) => {
+      if (!entry.isDirectory()) {
+        return false
+      }
+      if (taskSource === 'openspec' && entry.name === 'archive') {
+        return false
+      }
+      return true
+    })
+    .map((entry) => entry.name)
+}
+
+async function detectGitBranch(workspaceRoot: string) {
+  try {
+    const { stdout } = await execa(
+      'git',
+      ['rev-parse', '--abbrev-ref', 'HEAD'],
+      {
+        cwd: workspaceRoot,
+      },
+    )
+    return stdout.trim()
+  } catch {
+    return null
+  }
+}
+
+function matchFeatureByPrefix(featureDirs: string[], branch: string) {
+  const prefixMatch = branch.match(/^(\d{3}|\d{8}-\d{6})-/)
+  const prefix = prefixMatch?.[1]
+  if (!prefix) {
+    return null
+  }
+  return featureDirs.find((feature) => feature.startsWith(`${prefix}-`)) ?? null
+}
+
+export async function resolveWorkspaceContext(
+  input: ResolveWorkspaceContextInput,
+): Promise<WorkspaceContext> {
+  const taskSource = input.taskSource ?? 'spec-kit'
+  const workspaceRoot = await resolveWorkspaceRoot(input.cwd, taskSource)
+
+  const featureDirs = await readFeatureDirs(workspaceRoot, taskSource)
+  let featureId = input.feature ?? null
+
+  if (!featureId && taskSource === 'spec-kit') {
+    const branch = await detectGitBranch(workspaceRoot)
+    if (branch) {
+      featureId = matchFeatureByPrefix(featureDirs, branch)
+    }
+  }
+
+  if (!featureId) {
+    if (featureDirs.length === 1) {
+      featureId = featureDirs[0] ?? null
+    } else {
+      throw new Error('Unable to determine feature. Pass --feature explicitly.')
+    }
+  }
+
+  if (!featureId) {
+    throw new Error('Unable to determine feature. Pass --feature explicitly.')
+  }
+
+  const featureDir = path.join(
+    resolveFeatureRoot(workspaceRoot, taskSource),
+    featureId,
+  )
+  const featureExists = await fsExtra.pathExists(featureDir)
+  if (!featureExists) {
+    if (taskSource === 'openspec') {
+      throw new Error(`OpenSpec change directory does not exist: ${featureId}`)
+    }
+    throw new Error(`Feature directory does not exist: ${featureId}`)
+  }
+  return {
+    featureDir,
+    featureId,
+    runtimeDir: path.join(featureDir, '.while'),
+    workspaceRoot,
+  }
+}

package/src/schema/index.ts

@@ -0,0 +1,127 @@
+import { zodToJsonSchema } from 'zod-to-json-schema'
+
+import {
+  finalReportSchema,
+  implementArtifactSchema,
+  implementOutputSchemaInternal,
+  integrateArtifactSchema,
+  reviewArtifactSchema,
+  reviewOutputSchemaInternal,
+  taskGraphSchema,
+  workflowEventSchema,
+  workflowStateSchema,
+  type acceptanceCheckSchema,
+  type blockedTaskStateSchema,
+  type doneTaskStateSchema,
+  type finalReportTaskSchema,
+  type pendingTaskStateSchema,
+  type replanTaskStateSchema,
+  type reviewFindingSchema,
+  type reworkTaskStateSchema,
+  type runningTaskStateSchema,
+  type taskStateSchema,
+  type taskTopologyEntrySchema,
+} from './model'
+import { parseWithSchema } from './shared'
+
+import type { z } from 'zod'
+
+export * from './model'
+export * from './shared'
+
+function ensureReviewSemantics(result: ReviewOutput) {
+  if (result.verdict === 'pass' && result.findings.length !== 0) {
+    throw new Error('Review verdict pass requires empty findings')
+  }
+  if (
+    result.verdict === 'pass' &&
+    result.acceptanceChecks.some((check) => check.status !== 'pass')
+  ) {
+    throw new Error(
+      'Review verdict pass requires all acceptance checks to pass',
+    )
+  }
+}
+
+function toOpenAiOutputSchema(
+  schema:
+    | typeof implementOutputSchemaInternal
+    | typeof reviewOutputSchemaInternal,
+) {
+  return zodToJsonSchema(schema, {
+    $refStrategy: 'none',
+    target: 'openAi',
+  }) as Record<string, unknown>
+}
+
+export const implementOutputSchema = toOpenAiOutputSchema(
+  implementOutputSchemaInternal,
+)
+export const reviewOutputSchema = toOpenAiOutputSchema(
+  reviewOutputSchemaInternal,
+)
+
+export function validateImplementOutput(value: unknown) {
+  return parseWithSchema(implementOutputSchemaInternal, value)
+}
+
+export function validateReviewOutput(value: unknown) {
+  const result = parseWithSchema(reviewOutputSchemaInternal, value)
+  ensureReviewSemantics(result)
+  return result
+}
+
+export function validateTaskGraph(value: unknown) {
+  return parseWithSchema(taskGraphSchema, value)
+}
+
+export function validateWorkflowState(value: unknown) {
+  return parseWithSchema(workflowStateSchema, value)
+}
+
+export function validateImplementArtifact(value: unknown) {
+  return parseWithSchema(implementArtifactSchema, value)
+}
+
+export function validateIntegrateArtifact(value: unknown) {
+  return parseWithSchema(integrateArtifactSchema, value)
+}
+
+export function validateReviewArtifact(value: unknown) {
+  return parseWithSchema(reviewArtifactSchema, value)
+}
+
+export function validateWorkflowEvent(value: unknown) {
+  return parseWithSchema(workflowEventSchema, value)
+}
+
+export function validateFinalReport(value: unknown) {
+  return parseWithSchema(finalReportSchema, value)
+}
+
+export type AcceptanceCheck = z.infer<typeof acceptanceCheckSchema>
+export type BlockedTaskState = z.infer<typeof blockedTaskStateSchema>
+export type DoneTaskState = z.infer<typeof doneTaskStateSchema>
+export type FinalReport = z.infer<typeof finalReportSchema>
+export type FinalReportTask = z.infer<typeof finalReportTaskSchema>
+export type IntegrateArtifact = z.infer<typeof integrateArtifactSchema>
+export type ImplementArtifact = z.infer<typeof implementArtifactSchema>
+export type ImplementOutput = z.infer<typeof implementOutputSchemaInternal>
+export type PendingTaskState = z.infer<typeof pendingTaskStateSchema>
+export type ReviewArtifact = z.infer<typeof reviewArtifactSchema>
+export type ReviewFinding = z.infer<typeof reviewFindingSchema>
+export type ReviewOutput = z.infer<typeof reviewOutputSchemaInternal>
+export type ReviewVerdict = z.infer<
+  typeof reviewOutputSchemaInternal
+>['verdict']
+export type ReplanTaskState = z.infer<typeof replanTaskStateSchema>
+export type ReworkTaskState = z.infer<typeof reworkTaskStateSchema>
+export type RunningStage = z.infer<typeof runningTaskStateSchema>['stage']
+export type RunningTaskState = z.infer<typeof runningTaskStateSchema>
+export type TaskTopologyEntry = z.infer<typeof taskTopologyEntrySchema>
+export type TaskGraph = z.infer<typeof taskGraphSchema>
+export type TaskState = z.infer<typeof taskStateSchema>
+export type TaskStatus = z.infer<typeof taskStateSchema>['status']
+export type WorkflowEvent = z.infer<typeof workflowEventSchema>
+export type WorkflowEventType = z.infer<typeof workflowEventSchema>['type']
+export type WorkflowState = z.infer<typeof workflowStateSchema>