@markjaquith/agency 1.11.0 → 2.0.0

package/src/services/PhaseService.ts

@@ -0,0 +1,323 @@
+import { Schema, TreeFormatter } from "@effect/schema"
+import { Data, Effect, Either } from "effect"
+import { join } from "node:path"
+import { FileSystemService } from "./FileSystemService"
+import { WorkbaseService } from "./WorkbaseService"
+import { TaskService } from "./TaskService"
+import {
+	EntityId,
+	PhaseFrontmatter,
+	type PhaseFrontmatter as PhaseData,
+	type RepositoryReference,
+} from "../workbase/schemas"
+import {
+	formatMarkdownDocument,
+	parseFrontmatter,
+} from "../workbase/frontmatter"
+
+class PhaseError extends Data.TaggedError("PhaseError")<{
+	readonly message: string
+}> {}
+
+interface PhaseRecord {
+	readonly taskId: string
+	readonly id: string
+	readonly path: string
+	readonly content: string
+	readonly data: PhaseData
+}
+
+export interface CreatePhaseInput {
+	readonly taskId: string
+	readonly id: string
+	readonly description?: string
+	readonly repo: string
+	readonly repos?: readonly RepositoryReference[]
+	readonly branch: string
+	readonly base: string
+	readonly dependsOn?: readonly string[]
+	readonly firstPhase?: string
+}
+
+const decodeId = (id: string, label: string) => {
+	const result = Schema.decodeUnknownEither(EntityId)(id)
+	return Either.isLeft(result)
+		? Effect.fail(new PhaseError({ message: `Invalid ${label} ID '${id}'` }))
+		: Effect.succeed(result.right)
+}
+
+const decodePhase = (input: unknown) => {
+	const result = Schema.decodeUnknownEither(PhaseFrontmatter, {
+		errors: "all",
+		onExcessProperty: "error",
+	})(input)
+	return Either.isLeft(result)
+		? Effect.fail(
+				new PhaseError({ message: TreeFormatter.formatErrorSync(result.left) }),
+			)
+		: Effect.succeed(result.right)
+}
+
+export class PhaseService extends Effect.Service<PhaseService>()(
+	"PhaseService",
+	{
+		sync: () => ({
+			create: (input: CreatePhaseInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const tasks = yield* TaskService
+					const root = yield* workbase.discover(startPath)
+					const taskId = yield* decodeId(input.taskId, "task")
+					const id = yield* decodeId(input.id, "phase")
+					const task = yield* tasks.show(taskId, root)
+					const isMultiPhase = "phases" in task.data
+					let firstPhaseId: string | undefined
+					if (!isMultiPhase) {
+						if (!input.firstPhase) {
+							return yield* new PhaseError({
+								message:
+									"Converting a single-phase task requires --first-phase <id>",
+							})
+						}
+						firstPhaseId = yield* decodeId(input.firstPhase, "first phase")
+						if (firstPhaseId === id) {
+							return yield* new PhaseError({
+								message: "The existing and new phase IDs must be different",
+							})
+						}
+					} else if (input.firstPhase) {
+						return yield* new PhaseError({
+							message:
+								"--first-phase is only valid when converting a single-phase task",
+						})
+					}
+
+					if (
+						isMultiPhase &&
+						task.data.phases.some((phase) => phase.id === id)
+					) {
+						return yield* new PhaseError({
+							message: `Phase '${id}' already exists on task '${taskId}'`,
+						})
+					}
+					const knownPhases = new Set(
+						isMultiPhase
+							? task.data.phases.map((phase) => phase.id)
+							: [firstPhaseId!],
+					)
+					for (const dependency of input.dependsOn ?? []) {
+						if (!knownPhases.has(dependency)) {
+							return yield* new PhaseError({
+								message: `Unknown phase dependency '${dependency}'`,
+							})
+						}
+					}
+
+					const data = yield* decodePhase({
+						...(input.description !== undefined
+							? { description: input.description }
+							: {}),
+						repo: input.repo,
+						...(input.repos?.length ? { repos: input.repos } : {}),
+						branch: input.branch,
+						base: input.base,
+						pr: null,
+					})
+					const existingExecution = isMultiPhase ? undefined : task.data
+					const aliases = new Set([
+						data.repo,
+						...(data.repos ?? []).map((reference) => reference.repo),
+						...(existingExecution
+							? [
+									existingExecution.repo,
+									...(existingExecution.repos ?? []).map(
+										(reference) => reference.repo,
+									),
+								]
+							: []),
+					])
+					for (const alias of aliases) {
+						if (!(yield* fs.exists(join(root, "repos", alias)))) {
+							return yield* new PhaseError({
+								message: `Unknown repository alias '${alias}'`,
+							})
+						}
+					}
+
+					const directory = join(root, "tasks", taskId, "phases", id)
+					const path = join(directory, "PHASE.md")
+					if (yield* fs.exists(directory)) {
+						return yield* new PhaseError({
+							message: `Phase directory already exists: ${id}`,
+						})
+					}
+
+					const parsedTask = yield* parseFrontmatter(task.content, task.path)
+					const title = id
+						.split("-")
+						.map((part) => part[0]?.toUpperCase() + part.slice(1))
+						.join(" ")
+					const content = formatMarkdownDocument(
+						data,
+						`# ${title}\n\nDescribe the phase outcome.`,
+					)
+
+					if (!isMultiPhase) {
+						const firstDirectory = join(
+							root,
+							"tasks",
+							taskId,
+							"phases",
+							firstPhaseId!,
+						)
+						if (yield* fs.exists(firstDirectory)) {
+							return yield* new PhaseError({
+								message: `Phase directory already exists: ${firstPhaseId}`,
+							})
+						}
+						const firstData = yield* decodePhase({
+							repo: task.data.repo,
+							...(task.data.repos?.length ? { repos: task.data.repos } : {}),
+							branch: task.data.branch,
+							base: task.data.base,
+							pr: task.data.pr,
+						})
+						const firstTitle = firstPhaseId!
+							.split("-")
+							.map((part) => part[0]?.toUpperCase() + part.slice(1))
+							.join(" ")
+
+						yield* fs.createDirectory(firstDirectory)
+						yield* fs.createDirectory(directory)
+						yield* fs.writeFile(
+							join(firstDirectory, "PHASE.md"),
+							formatMarkdownDocument(
+								firstData,
+								`# ${firstTitle}\n\nDescribe the phase outcome.`,
+							),
+						)
+						yield* fs.writeFile(path, content)
+
+						const oldCodePath = join(root, "tasks", taskId, "code")
+						if (yield* fs.isDirectory(oldCodePath)) {
+							const firstCodePath = join(firstDirectory, "code")
+							yield* fs.moveDirectory(oldCodePath, firstCodePath)
+							for (const alias of [
+								firstData.repo,
+								...(firstData.repos ?? []).map((reference) => reference.repo),
+							]) {
+								const checkoutPath = join(firstCodePath, alias)
+								if (!(yield* fs.isDirectory(checkoutPath))) continue
+								const repair = yield* fs.runCommand(
+									[
+										"git",
+										"-C",
+										join(root, "repos", alias),
+										"worktree",
+										"repair",
+										checkoutPath,
+									],
+									{ captureOutput: true },
+								)
+								if (repair.exitCode !== 0) {
+									return yield* new PhaseError({
+										message: `Failed to repair moved worktree for '${alias}': ${repair.stderr}`,
+									})
+								}
+							}
+						}
+
+						const convertedTaskData = {
+							ticketUrl: task.data.ticketUrl,
+							...(task.data.description
+								? { description: task.data.description }
+								: {}),
+							...(task.data.epic ? { epic: task.data.epic } : {}),
+							phases: [
+								{ id: firstPhaseId! },
+								{
+									id,
+									...(input.dependsOn?.length
+										? { dependsOn: input.dependsOn }
+										: {}),
+								},
+							],
+						}
+						yield* fs.writeFile(
+							task.path,
+							formatMarkdownDocument(convertedTaskData, parsedTask.body),
+						)
+						return { taskId, id, path, content, data } satisfies PhaseRecord
+					}
+
+					yield* fs.createDirectory(directory)
+					yield* fs.writeFile(path, content)
+					const updatedTaskData = {
+						...task.data,
+						phases: [
+							...task.data.phases,
+							{
+								id,
+								...(input.dependsOn?.length
+									? { dependsOn: input.dependsOn }
+									: {}),
+							},
+						],
+					}
+					yield* fs.writeFile(
+						task.path,
+						formatMarkdownDocument(updatedTaskData, parsedTask.body),
+					)
+
+					return { taskId, id, path, content, data } satisfies PhaseRecord
+				}),
+
+			list: (taskId: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const tasks = yield* TaskService
+					const root = yield* workbase.discover(startPath)
+					const validTaskId = yield* decodeId(taskId, "task")
+					yield* tasks.show(validTaskId, root)
+					const directory = join(root, "tasks", validTaskId, "phases")
+					if (!(yield* fs.isDirectory(directory))) return [] as PhaseRecord[]
+					const entries = (yield* fs.readDirectory(directory))
+						.filter((entry) => entry.isDirectory)
+						.sort((a, b) => a.name.localeCompare(b.name))
+					const records: PhaseRecord[] = []
+					for (const entry of entries) {
+						const path = join(directory, entry.name, "PHASE.md")
+						if (!(yield* fs.exists(path))) continue
+						const content = yield* fs.readFile(path)
+						const parsed = yield* parseFrontmatter(content, path)
+						const data = yield* decodePhase(parsed.data)
+						records.push({
+							taskId: validTaskId,
+							id: entry.name,
+							path,
+							content,
+							data,
+						})
+					}
+					return records
+				}),
+
+			show: (taskId: string, id: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const service = yield* PhaseService
+					const validId = yield* decodeId(id, "phase")
+					const record = (yield* service.list(taskId, startPath)).find(
+						(phase) => phase.id === validId,
+					)
+					if (!record) {
+						return yield* new PhaseError({
+							message: `Phase '${validId}' does not exist on task '${taskId}'`,
+						})
+					}
+					return record
+				}),
+		}),
+	},
+) {}

package/src/services/PullRequestService.test.ts

@@ -0,0 +1,386 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { chmod, mkdir, realpath, rm } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { PhaseService } from "./PhaseService"
+import { TaskService } from "./TaskService"
+import { PullRequestService } from "./PullRequestService"
+import { WorktreeService } from "./WorktreeService"
+
+interface CommandResult {
+	readonly stdout: string
+	readonly stderr: string
+	readonly exitCode: number
+}
+
+const runCommand = async (
+	args: readonly string[],
+	cwd?: string,
+): Promise<CommandResult> => {
+	const process = Bun.spawn([...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(process.stdout).text(),
+		new Response(process.stderr).text(),
+		process.exited,
+	])
+	return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode }
+}
+
+const requireCommand = async (args: readonly string[], cwd?: string) => {
+	const result = await runCommand(args, cwd)
+	if (result.exitCode !== 0) {
+		throw new Error(`${args.join(" ")} failed: ${result.stderr}`)
+	}
+	return result
+}
+
+describe("PullRequestService", () => {
+	let root: string
+	let remotePath: string
+	let ghCallPath: string
+	let originalPath: string | undefined
+
+	const createTask = (id = "example", branch = `task/${id}`) =>
+		runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id,
+							ticketUrl: "https://example.com/task",
+							repo: "agency",
+							branch,
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+	const createPullRequest = (
+		taskId = "example",
+		phaseId?: string,
+		draft = false,
+	) =>
+		runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.create(taskId, phaseId, draft, root),
+				),
+			),
+		)
+
+	const materialize = (taskId = "example", phaseId?: string) =>
+		runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) => service.materialize(taskId, phaseId, root)),
+			),
+		)
+
+	const writeFakeGh = async ({
+		stdout = "",
+		stderr = "",
+		exitCode = 0,
+	}: {
+		stdout?: string
+		stderr?: string
+		exitCode?: number
+	}) => {
+		const path = join(root, "bin", "gh")
+		await Bun.write(
+			path,
+			`#!/usr/bin/env bun
+await Bun.write(${JSON.stringify(ghCallPath)}, JSON.stringify({ args: Bun.argv.slice(2), cwd: process.cwd() }))
+process.stdout.write(${JSON.stringify(stdout)})
+process.stderr.write(${JSON.stringify(stderr)})
+process.exit(${exitCode})
+`,
+		)
+		await chmod(path, 0o755)
+	}
+
+	const readGhCall = async () =>
+		(await Bun.file(ghCallPath).json()) as {
+			args: string[]
+			cwd: string
+		}
+
+	const expectRemoteBranch = async (branch: string, exists = true) => {
+		const result = await runCommand([
+			"git",
+			"--git-dir",
+			remotePath,
+			"show-ref",
+			"--verify",
+			`refs/heads/${branch}`,
+		])
+		expect(result.exitCode === 0).toBe(exists)
+	}
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		remotePath = join(root, "remote.git")
+		ghCallPath = join(root, "gh-call.json")
+		originalPath = process.env.PATH
+		await mkdir(join(root, "bin"), { recursive: true })
+		process.env.PATH = `${join(root, "bin")}:${originalPath ?? ""}`
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos"), { recursive: true })
+		await requireCommand([
+			"git",
+			"init",
+			"--bare",
+			"--initial-branch=main",
+			remotePath,
+		])
+		const seedPath = join(root, "seed")
+		await requireCommand(["git", "init", "--initial-branch=main", seedPath])
+		await requireCommand(
+			["git", "config", "user.name", "Agency Test"],
+			seedPath,
+		)
+		await requireCommand(
+			["git", "config", "user.email", "agency@example.com"],
+			seedPath,
+		)
+		await Bun.write(join(seedPath, "README.md"), "# Test repository\n")
+		await requireCommand(["git", "add", "README.md"], seedPath)
+		await requireCommand(["git", "commit", "-m", "Initial commit"], seedPath)
+		await requireCommand(
+			["git", "remote", "add", "origin", remotePath],
+			seedPath,
+		)
+		await requireCommand(["git", "push", "-u", "origin", "main"], seedPath)
+		await requireCommand([
+			"git",
+			"clone",
+			"--bare",
+			remotePath,
+			join(root, "repos", "agency"),
+		])
+	})
+
+	afterEach(async () => {
+		process.env.PATH = originalPath
+		await cleanupTempDir(root)
+	})
+
+	test("updates the execution document with a PR URL", async () => {
+		await createTask()
+		const url = "https://github.com/markjaquith/agency/pull/123"
+		await runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.setUrl("example", undefined, url, root),
+				),
+			),
+		)
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("example", root)),
+			),
+		)
+		expect("pr" in task.data && task.data.pr).toBe(url)
+	})
+
+	test("rejects non-GitHub PR URLs", async () => {
+		await createTask()
+		await expect(
+			runTestEffect(
+				PullRequestService.pipe(
+					Effect.flatMap((service) =>
+						service.setUrl(
+							"example",
+							undefined,
+							"https://example.com/pr/1",
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("Invalid GitHub pull request URL")
+	})
+
+	test("creates a clean single-phase PR and preserves the task body", async () => {
+		await createTask()
+		const taskPath = join(root, "tasks", "example", "TASK.md")
+		const body = "# Example\n\nKeep this exact body after creating the PR."
+		const original = await Bun.file(taskPath).text()
+		await Bun.write(
+			taskPath,
+			original.replace("# Example\n\nDescribe the task outcome.", body),
+		)
+		const url = "https://github.com/example/agency/pull/42"
+		await writeFakeGh({ stdout: `${url}\n` })
+
+		expect(await createPullRequest()).toBe(url)
+		await expectRemoteBranch("task/example")
+		const ghCall = await readGhCall()
+		expect(ghCall).toEqual({
+			args: ["pr", "create", "--fill", "--base", "main"],
+			cwd: await realpath(join(root, "tasks", "example", "code", "agency")),
+		})
+		const updated = await Bun.file(taskPath).text()
+		expect(updated).toContain("pr: https://github.com/example/agency/pull/42")
+		expect(updated.endsWith(`${body}\n`)).toBe(true)
+	})
+
+	test("passes --draft to gh", async () => {
+		await createTask()
+		await writeFakeGh({
+			stdout: "https://github.com/example/agency/pull/43\n",
+		})
+
+		await createPullRequest("example", undefined, true)
+
+		expect((await readGhCall()).args).toEqual([
+			"pr",
+			"create",
+			"--fill",
+			"--base",
+			"main",
+			"--draft",
+		])
+	})
+
+	test("updates only PHASE.md for a phase PR", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "multi",
+							ticketUrl: "https://example.com/task",
+							multiPhase: true,
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							taskId: "multi",
+							id: "implementation",
+							repo: "agency",
+							branch: "task/multi-implementation",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const taskPath = join(root, "tasks", "multi", "TASK.md")
+		const phasePath = join(
+			root,
+			"tasks",
+			"multi",
+			"phases",
+			"implementation",
+			"PHASE.md",
+		)
+		const originalTask = await Bun.file(taskPath).text()
+		const url = "https://github.com/example/agency/pull/44"
+		await writeFakeGh({ stdout: url })
+
+		await createPullRequest("multi", "implementation")
+
+		expect(await Bun.file(taskPath).text()).toBe(originalTask)
+		expect(await Bun.file(phasePath).text()).toContain(`pr: ${url}`)
+		await expectRemoteBranch("task/multi-implementation")
+	})
+
+	test("blocks a dirty checkout before push or gh", async () => {
+		await createTask()
+		const workspace = await materialize()
+		await Bun.write(join(workspace.writablePath, "dirty.txt"), "dirty\n")
+		await writeFakeGh({ stdout: "https://github.com/example/agency/pull/45" })
+
+		await expect(createPullRequest()).rejects.toThrow(
+			"Cannot create a PR with a dirty worktree",
+		)
+
+		await expectRemoteBranch("task/example", false)
+		expect(await Bun.file(ghCallPath).exists()).toBe(false)
+	})
+
+	test("reports push failure and does not invoke gh", async () => {
+		await createTask()
+		await materialize()
+		const hookPath = join(remotePath, "hooks", "pre-receive")
+		await Bun.write(hookPath, "#!/bin/sh\necho push rejected >&2\nexit 1\n")
+		await chmod(hookPath, 0o755)
+		await writeFakeGh({ stdout: "https://github.com/example/agency/pull/46" })
+
+		await expect(createPullRequest()).rejects.toThrow("Failed to push branch")
+
+		await expectRemoteBranch("task/example", false)
+		expect(await Bun.file(ghCallPath).exists()).toBe(false)
+	})
+
+	test("reports gh failure without persisting a URL", async () => {
+		await createTask()
+		await writeFakeGh({ stderr: "authentication failed\n", exitCode: 1 })
+
+		await expect(createPullRequest()).rejects.toThrow(
+			"Failed to create pull request: authentication failed",
+		)
+
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("example", root)),
+			),
+		)
+		expect("pr" in task.data && task.data.pr).toBeNull()
+	})
+
+	test("rejects successful gh output without a PR URL", async () => {
+		await createTask()
+		await writeFakeGh({ stdout: "Pull request created successfully\n" })
+
+		await expect(createPullRequest()).rejects.toThrow(
+			"GitHub CLI did not return a pull request URL",
+		)
+	})
+
+	test("extracts a PR URL from noisy gh output", async () => {
+		await createTask()
+		const url = "https://github.com/example/agency/pull/47"
+		await writeFakeGh({
+			stdout: `Creating pull request...\n${url}\nView it in your browser.\n`,
+		})
+
+		expect(await createPullRequest()).toBe(url)
+
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("example", root)),
+			),
+		)
+		expect("pr" in task.data && task.data.pr).toBe(url)
+	})
+
+	test("reports git status failure before push or gh", async () => {
+		await createTask()
+		const workspace = await materialize()
+		await rm(join(workspace.writablePath, ".git"))
+		await writeFakeGh({ stdout: "https://github.com/example/agency/pull/48" })
+
+		await expect(createPullRequest()).rejects.toThrow(
+			"Failed to inspect worktree status",
+		)
+
+		await expectRemoteBranch("task/example", false)
+		expect(await Bun.file(ghCallPath).exists()).toBe(false)
+	})
+})