@markjaquith/agency 2.15.0 → 2.17.0

package/src/services/ReadinessService.ts

@@ -0,0 +1,230 @@
+import { Data, Effect } from "effect"
+import type { AgencyGraph, GraphBlocker, GraphNode } from "../graph-schema"
+import type { WorkStatus } from "../workbase/schemas"
+import { GraphService } from "./GraphService"
+
+type ExecutionNode = Extract<GraphNode, { readonly kind: "execution-unit" }>
+
+interface NextItem {
+	readonly rank: number
+	readonly key: string
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly description?: string
+	readonly parent: {
+		readonly taskId?: string
+		readonly epicId?: string
+	}
+	readonly status: WorkStatus
+	readonly repositories: readonly string[]
+	readonly priority: {
+		readonly dependentCount: number
+	}
+	readonly ready: boolean
+	readonly terminal: boolean
+	readonly blockedBy: readonly string[]
+	readonly blockers: readonly GraphBlocker[]
+}
+
+interface NextResult {
+	readonly ready: readonly NextItem[]
+	readonly excluded: readonly NextItem[]
+	readonly selected?: NextItem
+}
+
+class ExecutionGuardError extends Data.TaggedError("ExecutionGuardError")<{
+	readonly message: string
+	readonly action: "work" | "pr"
+	readonly target: string
+	readonly status: WorkStatus
+	readonly blockedBy: readonly string[]
+	readonly blockers: readonly GraphBlocker[]
+}> {}
+
+const executionNodeId = (taskId: string, phaseId?: string) =>
+	phaseId
+		? `execution-unit:phase/${taskId}/${phaseId}`
+		: `execution-unit:task/${taskId}`
+
+const itemFor = (
+	node: ExecutionNode,
+	graph: AgencyGraph,
+	rank: number,
+): NextItem => {
+	const task = graph.nodes.find(
+		(candidate) =>
+			candidate.kind === "task" && candidate.key === node.data.taskId,
+	)
+	const epicId =
+		task?.kind === "task" && typeof task.data.epic === "string"
+			? task.data.epic
+			: undefined
+	const dependentIds = new Set(node.dependents)
+	if (node.data.phaseId) {
+		const siblings = graph.nodes.filter(
+			(candidate): candidate is ExecutionNode =>
+				candidate.kind === "execution-unit" &&
+				candidate.data.taskId === node.data.taskId &&
+				candidate.id !== node.id,
+		)
+		if (siblings.every((sibling) => sibling.status === "done")) {
+			for (const dependent of task?.dependents ?? [])
+				dependentIds.add(dependent)
+		}
+	}
+	return {
+		rank,
+		key: node.key,
+		taskId: node.data.taskId,
+		...(node.data.phaseId ? { phaseId: node.data.phaseId } : {}),
+		...(node.data.description ? { description: node.data.description } : {}),
+		parent: {
+			...(node.data.phaseId ? { taskId: node.data.taskId } : {}),
+			...(epicId ? { epicId } : {}),
+		},
+		status: node.status,
+		repositories: node.repositories,
+		priority: { dependentCount: dependentIds.size },
+		ready: node.readiness.ready,
+		terminal: node.readiness.terminal,
+		blockedBy: node.readiness.blockedBy,
+		blockers: node.readiness.blockers,
+	}
+}
+
+const rankedItems = (graph: AgencyGraph) =>
+	graph.nodes
+		.filter((node): node is ExecutionNode => node.kind === "execution-unit")
+		.map((node) => itemFor(node, graph, 0))
+		.sort(
+			(left, right) =>
+				right.priority.dependentCount - left.priority.dependentCount ||
+				left.key.localeCompare(right.key),
+		)
+		.map((item, index) => ({ ...item, rank: index + 1 }))
+
+const guardMessage = (
+	action: "work" | "pr",
+	item: Pick<NextItem, "key" | "status" | "blockers">,
+) => {
+	const reasons = item.blockers.map((blocker) => blocker.reason)
+	return `Cannot ${action === "work" ? "work on" : "create a pull request for"} '${item.key}': ${reasons.length > 0 ? reasons.join("; ") : `status is ${item.status}`}. Use --force to override.`
+}
+
+export class ReadinessService extends Effect.Service<ReadinessService>()(
+	"ReadinessService",
+	{
+		sync: () => ({
+			getReadyWorkTargetIds: (cwd: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const graphs = yield* GraphService
+					const graph = yield* graphs.get({ cwd })
+					return new Set(
+						graph.nodes
+							.filter((node) => node.readiness?.ready)
+							.map((node) => node.id),
+					)
+				}),
+
+			getNext: (cwd: string = process.cwd(), select = false) =>
+				Effect.gen(function* () {
+					const graphs = yield* GraphService
+					const graph = yield* graphs.get({ cwd })
+					const items = rankedItems(graph)
+					const ready = items
+						.filter((item) => item.ready)
+						.map((item, index) => ({ ...item, rank: index + 1 }))
+					const excluded = items
+						.filter((item) => !item.ready)
+						.map((item, index) => ({ ...item, rank: index + 1 }))
+					return {
+						ready,
+						excluded,
+						...(select && ready[0] ? { selected: ready[0] } : {}),
+					} satisfies NextResult
+				}),
+
+			guardWorkTarget: (
+				target: string,
+				cwd: string = process.cwd(),
+				override = false,
+			) =>
+				Effect.gen(function* () {
+					if (override) return
+					const graphs = yield* GraphService
+					const graph = yield* graphs.get({ cwd })
+					const node = graph.nodes.find((candidate) => candidate.id === target)
+					if (!node || !node.readiness) {
+						return yield* new ExecutionGuardError({
+							message: `Work target '${target}' was not found in the work graph.`,
+							action: "work",
+							target,
+							status: "open",
+							blockedBy: [],
+							blockers: [],
+						})
+					}
+					if (!node.readiness.ready) {
+						const item = {
+							key: node.key,
+							status: node.status!,
+							blockers: node.readiness.blockers,
+						}
+						return yield* new ExecutionGuardError({
+							message: guardMessage("work", item),
+							action: "work",
+							target,
+							status: node.status!,
+							blockedBy: node.readiness.blockedBy,
+							blockers: node.readiness.blockers,
+						})
+					}
+				}),
+
+			guard: (
+				action: "work" | "pr",
+				taskId: string,
+				phaseId?: string,
+				cwd: string = process.cwd(),
+				override = false,
+			) =>
+				Effect.gen(function* () {
+					if (override) return
+					const graphs = yield* GraphService
+					const graph = yield* graphs.get({ cwd })
+					const items = rankedItems(graph)
+					const key = phaseId ? `phase/${taskId}/${phaseId}` : `task/${taskId}`
+					const item = items.find((candidate) => candidate.key === key)
+					if (!item) {
+						return yield* new ExecutionGuardError({
+							message: `Execution unit '${key}' was not found in the work graph.`,
+							action,
+							target: executionNodeId(taskId, phaseId),
+							status: "open",
+							blockedBy: [],
+							blockers: [],
+						})
+					}
+					const actionable =
+						action === "work"
+							? item.ready
+							: !item.terminal &&
+								!item.blockers.some(
+									(blocker) =>
+										blocker.kind === "dependency" ||
+										blocker.kind === "validation",
+								)
+					if (!actionable) {
+						return yield* new ExecutionGuardError({
+							message: guardMessage(action, item),
+							action,
+							target: executionNodeId(taskId, phaseId),
+							status: item.status,
+							blockedBy: item.blockedBy,
+							blockers: item.blockers,
+						})
+					}
+				}),
+		}),
+	},
+) {}

package/src/services/SyncService.test.ts

@@ -0,0 +1,364 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { chmod, mkdir, rm } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { ClaimService } from "./ClaimService"
+import { PullRequestService } from "./PullRequestService"
+import { SyncService } from "./SyncService"
+import { TaskService } from "./TaskService"
+import { WorktreeService } from "./WorktreeService"
+
+const git = async (args: string[], cwd?: string) => {
+	const process = Bun.spawn(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	await process.exited
+	if (process.exitCode !== 0) {
+		throw new Error(await new Response(process.stderr).text())
+	}
+}
+
+describe("SyncService", () => {
+	let root: string
+	let originalPath: string | undefined
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		const source = join(root, "source")
+		await mkdir(source, { recursive: true })
+		await git(["init", "--initial-branch=main"], source)
+		await git(["config", "user.email", "test@example.com"], source)
+		await git(["config", "user.name", "Test"], source)
+		await Bun.write(join(source, "README.md"), "example\n")
+		await git(["add", "README.md"], source)
+		await git(["-c", "commit.gpgsign=false", "commit", "-m", "initial"], source)
+		await mkdir(join(root, "repos"), { recursive: true })
+		await git(["clone", "--bare", source, join(root, "repos/agency")])
+		await git(["clone", "--bare", source, join(root, "repos/reference")])
+
+		const bin = join(root, "bin")
+		await mkdir(bin)
+		const gh = join(bin, "gh")
+		await Bun.write(
+			gh,
+			`#!/bin/sh
+if [ "$2" = "view" ]; then
+cat <<'JSON'
+{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"}}
+JSON
+exit 0
+fi
+cat <<'JSON'
+[{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"}}]
+JSON
+`,
+		)
+		await chmod(gh, 0o755)
+		originalPath = process.env.PATH
+		process.env.PATH = `${bin}:${originalPath}`
+	})
+
+	afterEach(async () => {
+		if (originalPath === undefined) delete process.env.PATH
+		else process.env.PATH = originalPath
+		await cleanupTempDir(root)
+	})
+
+	test("observes drift without mutation and applies only safe transitions", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "example",
+							ticketUrl: null,
+							repo: "agency",
+							repos: [{ repo: "reference", ref: "main" }],
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("example", undefined, root),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:example/agency.git"],
+			join(root, "repos/agency"),
+		)
+		const inspected = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.inspect("example", undefined, root),
+				),
+			),
+		)
+		await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.claim(
+						{
+							taskId: "example",
+							claimant: "orchestrator",
+							runner: "agent",
+							sessionId: "session-1",
+							revision: inspected.revision,
+							expiresAt: "2099-01-01T00:00:00.000Z",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await Bun.write(
+			join(workspace.codePath, "reference", "LOCAL.md"),
+			"dirty\n",
+		)
+
+		const taskPath = join(root, "tasks/example/TASK.md")
+		const before = await Bun.file(taskPath).text()
+		const observed = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, now: new Date("2100-01-02") }),
+				),
+			),
+		)
+
+		expect(observed.mode).toBe("dry-run")
+		expect(observed.warnings).toContainEqual(
+			expect.objectContaining({
+				kind: "dirty-reference",
+				target: "task:example",
+			}),
+		)
+		expect(observed.changes.map((change) => change.kind)).toEqual([
+			"release-stale-claim",
+			"record-pr",
+			"mark-done",
+		])
+		expect(await Bun.file(taskPath).text()).toBe(before)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({
+						cwd: root,
+						apply: true,
+						now: new Date("2100-01-02"),
+					}),
+				),
+			),
+		)
+		expect(applied.changes.map((change) => change.kind)).toEqual([
+			"release-stale-claim",
+			"record-pr",
+			"mark-done",
+		])
+		expect(applied.changes.every((change) => change.status === "applied")).toBe(
+			true,
+		)
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("example", root)),
+			),
+		)
+		expect(task.data).toMatchObject({
+			status: "done",
+			pr: "https://github.com/example/agency/pull/42",
+			claim: { state: "released", sessionId: "session-1" },
+		})
+	})
+
+	test("materializes missing workspaces but leaves branch conflicts unresolved", async () => {
+		for (const [id, branch] of [
+			["missing", "feat/missing"],
+			["conflict", "feat/conflict"],
+		] as const) {
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{ id, ticketUrl: null, repo: "agency", branch, base: "main" },
+							root,
+						),
+					),
+				),
+			)
+		}
+		const repository = join(root, "repos/agency")
+		await git(["branch", "feat/conflict", "main"], repository)
+		await git(
+			["worktree", "add", join(root, "external-conflict"), "feat/conflict"],
+			repository,
+		)
+
+		const observed = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) => service.reconcile({ cwd: root })),
+			),
+		)
+		expect(observed.changes).toContainEqual(
+			expect.objectContaining({
+				kind: "materialize-workspace",
+				target: "task:missing",
+				status: "planned",
+			}),
+		)
+		expect(observed.unresolved).toContainEqual(
+			expect.objectContaining({
+				kind: "branch-conflict",
+				target: "task:conflict",
+			}),
+		)
+		expect(
+			await Bun.file(
+				join(root, "tasks/missing/code/agency/README.md"),
+			).exists(),
+		).toBe(false)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(applied.changes).toContainEqual(
+			expect.objectContaining({
+				kind: "materialize-workspace",
+				target: "task:missing",
+				status: "applied",
+			}),
+		)
+		expect(
+			applied.executions.find((item) => item.target === "task:missing")
+				?.checkouts[0],
+		).toMatchObject({ exists: true, registered: true, dirty: false })
+		expect(
+			await Bun.file(join(root, "tasks/missing/code/agency/README.md")).text(),
+		).toBe("example\n")
+		expect(
+			await Bun.file(
+				join(root, "tasks/conflict/code/agency/README.md"),
+			).exists(),
+		).toBe(false)
+	})
+
+	test("leaves a missing checkout registration unresolved", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "stale",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/stale",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("stale", undefined, root),
+				),
+			),
+		)
+		await rm(workspace.writablePath, { recursive: true, force: true })
+
+		const observed = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) => service.reconcile({ cwd: root })),
+			),
+		)
+		expect(observed.changes).toEqual([])
+		expect(observed.unresolved).toContainEqual(
+			expect.objectContaining({
+				kind: "stale-registration",
+				target: "task:stale",
+			}),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(applied.changes).toEqual([])
+		expect(
+			await Bun.file(join(workspace.writablePath, "README.md")).exists(),
+		).toBe(false)
+	})
+
+	test("does not trust a recorded PR from another repository", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "example",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.setUrl(
+						"example",
+						undefined,
+						"https://github.com/other/repository/pull/42",
+						root,
+					),
+				),
+			),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(applied.unresolved).toContainEqual(
+			expect.objectContaining({
+				kind: "pr-repository-conflict",
+				target: "task:example",
+			}),
+		)
+		expect(applied.changes.some((change) => change.kind === "mark-done")).toBe(
+			false,
+		)
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("example", root)),
+			),
+		)
+		expect(task.data).toMatchObject({ status: "open" })
+	})
+})