@markjaquith/agency 2.16.0 → 2.18.0

package/src/services/PullRequestService.ts

@@ -5,6 +5,7 @@ import { WorktreeService } from "./WorktreeService"
 import type { BaseCommandOptions } from "../utils/command"
 import { TaskService } from "./TaskService"
 import { PhaseService } from "./PhaseService"
+import { ReadinessService } from "./ReadinessService"
 import {
 	formatMarkdownDocument,
 	parseFrontmatter,
@@ -16,6 +17,10 @@ class PullRequestError extends Data.TaggedError("PullRequestError")<{
 
 const PR_URL = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+\/?$/
 
+interface PullRequestOptions extends BaseCommandOptions {
+	readonly force?: boolean
+}
+
 export class PullRequestService extends Effect.Service<PullRequestService>()(
 	"PullRequestService",
 	{
@@ -60,7 +65,7 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 				phaseId?: string,
 				draft = false,
 				startPath: string = process.cwd(),
-				options: BaseCommandOptions = {},
+				options: PullRequestOptions = {},
 			) =>
 				Effect.gen(function* () {
 					const service = yield* PullRequestService
@@ -68,6 +73,14 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 					const tasks = yield* TaskService
 					const phases = yield* PhaseService
 					const worktrees = yield* WorktreeService
+					const readiness = yield* ReadinessService
+					yield* readiness.guard(
+						"pr",
+						taskId,
+						phaseId,
+						startPath,
+						options.force,
+					)
 					const workspace = yield* worktrees.materialize(
 						taskId,
 						phaseId,

package/src/services/ReadinessService.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { ReadinessService } from "./ReadinessService"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+const execution = (status: string, branch: string) => `---
+repo: agency
+branch: ${branch}
+base: main
+pr: null
+status: ${status}
+---
+
+# Execution
+`
+
+const createWorkbase = async () => {
+	const root = await createTempDir()
+	await write(root, "agency.json", '{"version":2}\n')
+	await mkdir(join(root, "repos/agency"), { recursive: true })
+	await write(
+		root,
+		"epics/delivery/EPIC.md",
+		`---
+ticketUrl: https://example.com/delivery
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: prepare
+  - id: ship
+    dependsOn: [prepare]
+  - id: deploy
+    dependsOn: [ship]
+---
+
+# Delivery
+`,
+	)
+	await write(
+		root,
+		"tasks/prepare/TASK.md",
+		`---
+ticketUrl: null
+epic: delivery
+repo: agency
+branch: feat/prepare
+base: main
+pr: null
+status: done
+---
+
+# Prepare
+`,
+	)
+	await write(
+		root,
+		"tasks/ship/TASK.md",
+		`---
+ticketUrl: null
+description: Ship the feature.
+epic: delivery
+phases:
+  - id: implement
+  - id: verify
+    dependsOn: [implement]
+---
+
+# Ship
+`,
+	)
+	await write(
+		root,
+		"tasks/ship/phases/implement/PHASE.md",
+		execution("open", "feat/implement"),
+	)
+	await write(
+		root,
+		"tasks/ship/phases/verify/PHASE.md",
+		execution("open", "feat/verify"),
+	)
+	await write(
+		root,
+		"tasks/abandoned/TASK.md",
+		`---
+ticketUrl: null
+repo: agency
+branch: feat/abandoned
+base: main
+pr: null
+status: dropped
+---
+
+# Abandoned
+`,
+	)
+	await write(
+		root,
+		"tasks/deploy/TASK.md",
+		`---
+ticketUrl: null
+epic: delivery
+repo: agency
+branch: feat/deploy
+base: main
+pr: null
+status: open
+---
+
+# Deploy
+`,
+	)
+	return root
+}
+
+const service = <A>(
+	run: (readiness: ReadinessService) => Effect.Effect<A, unknown, any>,
+) => runTestEffect(ReadinessService.pipe(Effect.flatMap(run)))
+
+describe("ReadinessService", () => {
+	const roots: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(roots.splice(0).map(cleanupTempDir))
+	})
+
+	test("ranks ready work and explains every excluded execution unit", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+
+		const result = await service((readiness) => readiness.getNext(root, true))
+
+		expect(result.ready.map((item) => item.key)).toEqual([
+			"phase/ship/implement",
+		])
+		expect(result.selected).toMatchObject({
+			key: "phase/ship/implement",
+			parent: { epicId: "delivery", taskId: "ship" },
+			priority: { dependentCount: 1 },
+		})
+		expect(result.excluded.map((item) => item.key)).toEqual([
+			"task/prepare",
+			"phase/ship/verify",
+			"task/abandoned",
+			"task/deploy",
+		])
+		expect(
+			result.excluded.find((item) => item.key === "phase/ship/verify"),
+		).toMatchObject({
+			ready: false,
+			terminal: false,
+			blockedBy: ["phase:ship/implement"],
+			blockers: [
+				{
+					kind: "dependency",
+					status: "open",
+					reason: "Phase dependency is open",
+				},
+			],
+		})
+		expect(
+			result.excluded.find((item) => item.key === "task/abandoned"),
+		).toMatchObject({ status: "dropped", terminal: true })
+	})
+
+	test("includes cross-task unlocks in final-phase priority", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+		await Bun.write(
+			join(root, "tasks/ship/phases/implement/PHASE.md"),
+			execution("done", "feat/implement"),
+		)
+
+		const result = await service((readiness) => readiness.getNext(root, true))
+
+		expect(result.selected).toMatchObject({
+			key: "phase/ship/verify",
+			priority: { dependentCount: 1 },
+		})
+	})
+
+	test("uses the same readiness for work and PR guards", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+
+		await service((readiness) =>
+			readiness.guard("work", "ship", "implement", root),
+		)
+		await expect(
+			service((readiness) => readiness.guard("work", "ship", "verify", root)),
+		).rejects.toThrow("Phase dependency is open")
+		await expect(
+			service((readiness) => readiness.guard("pr", "ship", "verify", root)),
+		).rejects.toThrow("Phase dependency is open")
+		await service((readiness) =>
+			readiness.guard("work", "ship", "verify", root, true),
+		)
+	})
+
+	test("allows active PR targets but rejects terminal outcomes", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+		const path = join(root, "tasks/ship/phases/implement/PHASE.md")
+		await Bun.write(path, execution("working", "feat/implement"))
+
+		await service((readiness) =>
+			readiness.guard("pr", "ship", "implement", root),
+		)
+
+		await Bun.write(path, execution("done", "feat/implement"))
+		await expect(
+			service((readiness) => readiness.guard("pr", "ship", "implement", root)),
+		).rejects.toThrow("Phase status is done")
+	})
+})

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/WorkbaseService.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdir, realpath } from "node:fs/promises"
+import { mkdir, realpath, rm, symlink } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { WorkbaseService } from "./WorkbaseService"
@@ -66,11 +66,154 @@ describe("WorkbaseService", () => {
 			),
 		)
 
-		expect(first).toBe(await realpath(workbaseRoot))
-		expect(registered).toEqual([first])
+		expect(first.path).toBe(await realpath(workbaseRoot))
+		expect(registered).toEqual([first.path])
 		expect(
 			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
-		).toEqual({ version: 1, workbases: [first] })
+		).toEqual({ version: 2, workbases: [first] })
+	})
+
+	test("resolves names and stable IDs and manages the default", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const configDirectory = join(root, "config")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+
+		const registered = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.register(workbaseRoot, configDirectory, "primary"),
+				),
+			),
+		)
+		const result = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						yield* service.setDefault("primary", configDirectory)
+						return {
+							byName: yield* service.resolveRegistered(
+								"primary",
+								configDirectory,
+							),
+							byId: yield* service.resolveRegistered(
+								registered.id,
+								configDirectory,
+							),
+							defaultWorkbase: yield* service.getDefault(configDirectory),
+						}
+					}),
+				),
+			),
+		)
+
+		expect(result.byName).toBe(registered.path)
+		expect(result.byId).toBe(registered.path)
+		expect(result.defaultWorkbase).toEqual(registered)
+	})
+
+	test("rejects names that collide with stable IDs", async () => {
+		const firstRoot = join(root, "first")
+		const secondRoot = join(root, "second")
+		const configDirectory = join(root, "config")
+		await write(firstRoot, "agency.json", '{"version":2}\n')
+		await write(secondRoot, "agency.json", '{"version":2}\n')
+		const first = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.register(firstRoot, configDirectory),
+				),
+			),
+		)
+
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) =>
+						service.register(secondRoot, configDirectory, first.id),
+					),
+				),
+			),
+		).rejects.toThrow("already registered")
+	})
+
+	test("rejects invalid workbase names before writing the registry", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const configDirectory = join(root, "config")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+
+		for (const name of ["bad/name", ""]) {
+			await expect(
+				runTestEffect(
+					WorkbaseService.pipe(
+						Effect.flatMap((service) =>
+							service.register(workbaseRoot, configDirectory, name),
+						),
+					),
+				),
+			).rejects.toThrow("Invalid workbase name")
+		}
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).exists(),
+		).toBe(false)
+	})
+
+	test("removes a registration by an equivalent symlink path", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const linkedRoot = join(root, "linked")
+		const configDirectory = join(root, "config")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+		await symlink(workbaseRoot, linkedRoot)
+		await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.register(workbaseRoot, configDirectory),
+				),
+			),
+		)
+
+		const removed = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.removeRegistered(linkedRoot, configDirectory),
+				),
+			),
+		)
+		expect(removed.path).toBe(await realpath(workbaseRoot))
+	})
+
+	test("migrates legacy registrations and prunes stale paths", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const staleRoot = join(root, "stale")
+		const configDirectory = join(root, "config")
+		const registryPath = join(configDirectory, "agency/workbases.json")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+		await write(staleRoot, "agency.json", '{"version":2}\n')
+		await write(
+			configDirectory,
+			"agency/workbases.json",
+			JSON.stringify({ version: 1, workbases: [workbaseRoot, staleRoot] }),
+		)
+		await rm(staleRoot, { recursive: true })
+
+		const result = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						const before = yield* service.listRegistrations(configDirectory)
+						const removed = yield* service.pruneRegistered(configDirectory)
+						return { before, removed }
+					}),
+				),
+			),
+		)
+
+		expect(result.before.workbases).toHaveLength(2)
+		expect(result.before.workbases[0]?.id).toStartWith("wb-")
+		expect(result.removed.map((entry) => entry.path)).toEqual([staleRoot])
+		expect(await Bun.file(registryPath).json()).toEqual({
+			version: 2,
+			workbases: [result.before.workbases[0]],
+		})
 	})
 
 	test("rejects an invalid worktree command template", async () => {