@markjaquith/agency 2.28.1 → 2.30.0

package/src/graph-schema.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test"
+import { Schema } from "@effect/schema"
 import jsonSchema from "../schemas/agency-graph-v1.schema.json"
-import { graphJsonlRecords, type AgencyGraph } from "./graph-schema"
+import { AgencyGraph, graphJsonlRecords } from "./graph-schema"
 
 describe("graph contract", () => {
 	test("publishes the v1 JSON Schema", () => {
@@ -29,6 +30,38 @@ describe("graph contract", () => {
 	})
 
 	test("streams records that reconstruct graph semantics", () => {
+		const nodes = [
+			{
+				id: "repository:agency",
+				key: "agency",
+				kind: "repository" as const,
+				dependents: ["repository:effect"],
+				repositories: ["agency"],
+				status: null,
+				readiness: null,
+				aggregate: null,
+				data: { alias: "agency" },
+			},
+			{
+				id: "repository:effect",
+				key: "effect",
+				kind: "repository" as const,
+				dependents: [],
+				repositories: ["effect"],
+				status: null,
+				readiness: null,
+				aggregate: null,
+				data: { alias: "effect" },
+			},
+		]
+		const edges = [
+			{
+				id: "references:repository:agency:repository:effect",
+				kind: "references" as const,
+				from: "repository:agency",
+				to: "repository:effect",
+			},
+		]
 		const graph = {
 			version: 1,
 			workbase: { version: 2 },
@@ -40,8 +73,8 @@ describe("graph contract", () => {
 				kinds: [],
 			},
 			includes: [],
-			nodes: [],
-			edges: [],
+			nodes,
+			edges,
 			summary: {
 				status: "open",
 				total: 0,
@@ -54,6 +87,11 @@ describe("graph contract", () => {
 			},
 			validation: { valid: true, issues: [] },
 		} satisfies AgencyGraph
+		expect(
+			Schema.decodeUnknownSync(AgencyGraph, { onExcessProperty: "error" })(
+				graph,
+			),
+		).toEqual(graph)
 		const records = [...graphJsonlRecords(graph)]
 		const { nodes: _nodes, edges: _edges, ...metadata } = graph
 		expect(records).toEqual([
@@ -62,7 +100,17 @@ describe("graph contract", () => {
 				type: "meta",
 				graph: metadata,
 			},
-			{ version: 1, type: "end", nodeCount: 0, edgeCount: 0 },
+			...nodes.map((node) => ({
+				version: 1 as const,
+				type: "node" as const,
+				node,
+			})),
+			...edges.map((edge) => ({
+				version: 1 as const,
+				type: "edge" as const,
+				edge,
+			})),
+			{ version: 1, type: "end", nodeCount: 2, edgeCount: 1 },
 		])
 	})
 })

package/src/protocol.test.ts

@@ -53,6 +53,34 @@ describe("machine protocol", () => {
 		).rejects.toThrow("more than one result")
 	})
 
+	test("restores collection state after a command throws", async () => {
+		const originalLog = console.log
+		await expect(
+			collectCommandResult(async () => {
+				emitCommandResult("partial")
+				throw new Error("command failed")
+			}),
+		).rejects.toThrow("command failed")
+		expect(console.log).toBe(originalLog)
+
+		await expect(
+			collectCommandResult(async () => {
+				emitCommandResult("recovered")
+			}),
+		).resolves.toBe("recovered")
+	})
+
+	test("rejects nested result collectors without disrupting the outer one", async () => {
+		const result = await collectCommandResult(async () => {
+			await expect(collectCommandResult(async () => {})).rejects.toThrow(
+				"already active",
+			)
+			emitCommandResult("outer")
+		})
+
+		expect(result).toBe("outer")
+	})
+
 	test("normalizes unknown failures into stable error details", () => {
 		expect(errorEnvelope(new Error("boom"))).toEqual({
 			version: 1,
@@ -67,14 +95,15 @@ describe("machine protocol", () => {
 	})
 
 	test("preserves relevant fields from classified errors", () => {
-		expect(
-			errorEnvelope({
-				_tag: "ValidationFailedError",
-				message: "invalid workbase",
-				root: "/work/agency",
-				issues: [{ path: "TASK.md", message: "invalid status" }],
-			}),
-		).toMatchObject({
+		const validation = errorEnvelope({
+			_tag: "ValidationFailedError",
+			message: "invalid workbase",
+			cause: new Error("private cause"),
+			optional: undefined,
+			root: "/work/agency",
+			issues: [{ path: "TASK.md", message: "invalid status" }],
+		})
+		expect(validation).toMatchObject({
 			error: {
 				code: "VALIDATION_FAILED",
 				fields: {
@@ -83,6 +112,10 @@ describe("machine protocol", () => {
 				},
 			},
 		})
+		expect(Object.keys(validation.error.fields).sort()).toEqual([
+			"issues",
+			"root",
+		])
 		expect(
 			errorEnvelope({
 				_tag: "ClaimConflictError",

package/src/readiness.test.ts

@@ -1,10 +1,21 @@
 import { describe, expect, test } from "bun:test"
 import {
+	WORK_STATUS_TRANSITIONS,
 	aggregateProgress,
 	canTransitionStatus,
 	isDependencySatisfied,
+	isTerminalStatus,
 	readinessState,
 } from "./readiness"
+import type { WorkStatus } from "./workbase/schemas"
+
+const statuses: readonly WorkStatus[] = [
+	"open",
+	"working",
+	"delegated",
+	"done",
+	"dropped",
+]
 
 describe("readiness model", () => {
 	test("only done satisfies dependencies and terminal states remain distinct", () => {
@@ -24,24 +35,71 @@ describe("readiness model", () => {
 		})
 	})
 
-	test("rolls child statuses into deterministic aggregate progress", () => {
-		expect(aggregateProgress(["done", "dropped"])).toEqual({
-			status: "dropped",
-			total: 2,
-			open: 0,
-			working: 0,
-			delegated: 0,
-			done: 1,
-			dropped: 1,
-			terminal: 2,
-		})
+	test("classifies every status and dependency state", () => {
+		expect(statuses.map(isTerminalStatus)).toEqual([
+			false,
+			false,
+			false,
+			true,
+			true,
+		])
+		expect([...statuses, undefined].map(isDependencySatisfied)).toEqual([
+			false,
+			false,
+			false,
+			true,
+			false,
+			false,
+		])
 	})
 
-	test("requires terminal work to reopen before changing its outcome", () => {
-		expect(canTransitionStatus("open", "done")).toBe(true)
-		expect(canTransitionStatus("working", "delegated")).toBe(true)
-		expect(canTransitionStatus("done", "dropped")).toBe(false)
-		expect(canTransitionStatus("dropped", "done")).toBe(false)
-		expect(canTransitionStatus("done", "open")).toBe(true)
+	test("covers the complete status transition matrix", () => {
+		for (const from of statuses) {
+			for (const to of statuses) {
+				expect(canTransitionStatus(from, to), `${from} -> ${to}`).toBe(
+					WORK_STATUS_TRANSITIONS[from].includes(to as never),
+				)
+			}
+		}
+	})
+
+	test("rolls every status-precedence branch into aggregate progress", () => {
+		const cases: readonly [readonly WorkStatus[], WorkStatus][] = [
+			[[], "open"],
+			[["done", "done"], "done"],
+			[["done", "dropped"], "dropped"],
+			[["open", "working", "delegated"], "working"],
+			[["open", "delegated"], "delegated"],
+			[["open", "done"], "open"],
+		]
+
+		for (const [input, status] of cases) {
+			const result = aggregateProgress(input)
+			expect(result.status, input.join(",") || "empty").toBe(status)
+			expect(result.total).toBe(input.length)
+			expect(result.terminal).toBe(
+				input.filter((value) => value === "done" || value === "dropped").length,
+			)
+			for (const value of statuses) {
+				expect(result[value]).toBe(
+					input.filter((candidate) => candidate === value).length,
+				)
+			}
+		}
+	})
+
+	test("deduplicates and sorts blockers while honoring explicit readiness", () => {
+		expect(
+			readinessState(
+				"open",
+				[{ id: "task:z" }, { id: "task:a" }, { id: "task:z" }],
+				true,
+			),
+		).toEqual({
+			ready: true,
+			blocked: false,
+			blockedBy: ["task:a", "task:z"],
+			terminal: false,
+		})
 	})
 })

package/src/services/DoctorService.ts

@@ -295,31 +295,40 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 						})
 					}
 					for (const repository of repositoryList) {
-						const verified = yield* fs.runCommand(
-							["git", "-C", repository.path, "rev-parse", "--git-dir"],
-							{ captureOutput: true },
-						)
-						const repositoryValid = verified.exitCode === 0
+						const missing = repository.states.includes("missing")
+						const repositoryValid =
+							!missing && !repository.states.includes("invalid")
 						add({
 							id: `repository.${repository.alias}.valid`,
 							category: "repository",
 							level: "error",
 							status: repositoryValid ? "pass" : "fail",
-							message: repositoryValid
-								? `Repository '${repository.alias}' is a valid Git repository`
-								: `Repository '${repository.alias}' is not a valid Git repository`,
-							remediation: `Run 'agency repo verify ${repository.alias}', then repair or relink the repository.`,
+							message: missing
+								? `Repository '${repository.alias}' is declared but not materialized`
+								: repositoryValid
+									? `Repository '${repository.alias}' is a valid Git repository`
+									: `Repository '${repository.alias}' is not a valid Git repository`,
+							remediation: missing
+								? "Run 'agency repo setup --apply'."
+								: `Run 'agency repo verify ${repository.alias}', then repair or relink the repository.`,
 						})
 						add({
 							id: `repository.${repository.alias}.remote`,
 							category: "repository",
 							level: "warning",
-							status: repository.remote ? "pass" : "fail",
-							message: repository.remote
-								? `Repository '${repository.alias}' origin is ${repository.remote}`
-								: `Repository '${repository.alias}' has no origin remote`,
+							status:
+								repository.declaredRemote &&
+								!repository.states.includes("remote-drifted")
+									? "pass"
+									: "fail",
+							message: repository.states.includes("remote-drifted")
+								? `Repository '${repository.alias}' origin differs from ${repository.declaredRemote}`
+								: repository.declaredRemote
+									? `Repository '${repository.alias}' portable origin is ${repository.declaredRemote}`
+									: `Repository '${repository.alias}' has no portable origin declaration`,
 							remediation: `Run 'agency repo remote ${repository.alias} <url>' to configure origin.`,
 						})
+						if (!repositoryValid) continue
 
 						for (const ref of [...(refs.get(repository.alias) ?? [])].sort()) {
 							const local = yield* fs.runCommand(

package/src/services/EpicService.ts

@@ -81,7 +81,7 @@ export class EpicService extends Effect.Service<EpicService>()("EpicService", {
 				}
 
 				for (const { repo: alias } of data.repos) {
-					if (!(yield* fs.exists(join(root, "repos", alias)))) {
+					if (!(yield* workbase.hasRepositoryAlias(alias, root))) {
 						return yield* new EpicError({
 							message: `Unknown repository alias '${alias}'`,
 						})

package/src/services/GraphMutationService.ts

@@ -309,7 +309,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						"epic metadata",
 					)
 					for (const reference of data.repos) {
-						if (!(yield* fs.exists(join(root, "repos", reference.repo)))) {
+						if (!(yield* workbase.hasRepositoryAlias(reference.repo, root))) {
 							return yield* new GraphMutationError({
 								message: `Unknown repository alias '${reference.repo}'`,
 							})
@@ -420,7 +420,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							})
 						}
 						for (const alias of aliases) {
-							if (!(yield* fs.exists(join(root, "repos", alias)))) {
+							if (!(yield* workbase.hasRepositoryAlias(alias, root))) {
 								return yield* new GraphMutationError({
 									message: `Unknown repository alias '${alias}'`,
 								})
@@ -538,7 +538,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						})
 					}
 					for (const alias of aliases) {
-						if (!(yield* fs.exists(join(root, "repos", alias)))) {
+						if (!(yield* workbase.hasRepositoryAlias(alias, root))) {
 							return yield* new GraphMutationError({
 								message: `Unknown repository alias '${alias}'`,
 							})

package/src/services/GraphService.ts

@@ -197,13 +197,20 @@ export class GraphService extends Effect.Service<GraphService>()(
 						}
 					}
 
-					const repositoryRecords: RepositoryRecord[] = []
+					const repositoryRecords = new Map<string, RepositoryRecord>()
 					const reposPath = join(root, "repos")
+					for (const alias of Object.keys(config.repositories ?? {}).sort()) {
+						repositoryRecords.set(alias, {
+							alias,
+							path: join(reposPath, alias),
+							target: null,
+						})
+					}
 					if (yield* fs.isDirectory(reposPath)) {
 						for (const entry of (yield* fs.readDirectory(reposPath))
-							.filter((item) => item.isDirectory || item.isSymlink)
+							.filter((item) => !item.name.startsWith(".agency-"))
 							.sort((a, b) => a.name.localeCompare(b.name))) {
-							repositoryRecords.push({
+							repositoryRecords.set(entry.name, {
 								alias: entry.name,
 								path: join(reposPath, entry.name),
 								target: entry.isSymlink
@@ -760,7 +767,9 @@ export class GraphService extends Effect.Service<GraphService>()(
 							...(yield* executionDetails(phase.path, phase.data)),
 						})
 					}
-					for (const repository of repositoryRecords) {
+					for (const repository of [...repositoryRecords.values()].sort(
+						(a, b) => a.alias.localeCompare(b.alias),
+					)) {
 						nodes.push({
 							id: repositoryNodeId(repository.alias),
 							kind: "repository",

package/src/services/PhaseService.ts

@@ -174,7 +174,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						})
 					}
 					for (const alias of aliases) {
-						if (!(yield* fs.exists(join(root, "repos", alias)))) {
+						if (!(yield* workbase.hasRepositoryAlias(alias, root))) {
 							return yield* new PhaseError({
 								message: `Unknown repository alias '${alias}'`,
 							})

package/src/services/ReadinessService.test.ts

@@ -187,6 +187,53 @@ describe("ReadinessService", () => {
 		})
 	})
 
+	test("returns ready target IDs and guards structural work targets", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+
+		const readyIds = await service((readiness) =>
+			readiness.getReadyWorkTargetIds(root),
+		)
+		expect([...readyIds].sort()).toEqual([
+			"epic:delivery",
+			"execution-unit:phase/ship/implement",
+			"phase:ship/implement",
+			"task:ship",
+		])
+		await service((readiness) =>
+			readiness.guardWorkTarget("phase:ship/implement", root),
+		)
+
+		const blocked = await service((readiness) =>
+			Effect.either(readiness.guardWorkTarget("phase:ship/verify", root)),
+		)
+		expect(blocked).toMatchObject({
+			_tag: "Left",
+			left: {
+				_tag: "ExecutionGuardError",
+				action: "work",
+				target: "phase:ship/verify",
+				status: "open",
+				blockedBy: ["phase:ship/implement"],
+			},
+		})
+
+		const missing = await service((readiness) =>
+			Effect.either(readiness.guardWorkTarget("task:missing", root)),
+		)
+		expect(missing).toMatchObject({
+			_tag: "Left",
+			left: {
+				_tag: "ExecutionGuardError",
+				target: "task:missing",
+				blockers: [],
+			},
+		})
+		await service((readiness) =>
+			readiness.guardWorkTarget("task:missing", root, true),
+		)
+	})
+
 	test("uses the same readiness for work and PR guards", async () => {
 		const root = await createWorkbase()
 		roots.push(root)