@markjaquith/agency 2.17.0 → 2.19.0

package/src/work-view.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, 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 { getWorkViews } from "./work-view"
+
+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)
+}
+
+describe("work views", () => {
+	let root: string
+
+	beforeEach(async () => {
+		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: zeta
+  - id: alpha
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/zeta/TASK.md",
+			`---
+ticketUrl: null
+epic: delivery
+phases:
+  - id: verify
+    dependsOn: [implement]
+  - id: implement
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/zeta/phases/verify/PHASE.md",
+			`---
+repo: agency
+branch: feat/verify
+base: main
+pr: null
+status: open
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/zeta/phases/implement/PHASE.md",
+			`---
+repo: agency
+branch: feat/implement
+base: main
+pr: https://github.com/example/agency/pull/1
+status: dropped
+---
+`,
+		)
+		await mkdir(join(root, "tasks/zeta/phases/implement/code/agency"), {
+			recursive: true,
+		})
+		await write(
+			root,
+			"tasks/alpha/TASK.md",
+			`---
+ticketUrl: null
+epic: delivery
+repo: agency
+branch: feat/alpha
+base: main
+pr: null
+status: open
+---
+`,
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	const views = (options: Record<string, unknown> = {}) =>
+		runTestEffect(Effect.suspend(() => getWorkViews({ cwd: root, ...options })))
+
+	test("uses declared graph order and exposes operational state", async () => {
+		const result = await views()
+
+		expect(result.taskRows.map((row) => row.id)).toEqual(["zeta", "alpha"])
+		expect(result.phaseRows.map((row) => row.id)).toEqual([
+			"verify",
+			"implement",
+		])
+		expect(result.executionRows.map((row) => row.key)).toEqual([
+			"zeta/verify",
+			"zeta/implement",
+			"alpha",
+		])
+		expect(result.phaseRows[0]).toMatchObject({
+			parent: "zeta",
+			status: "open",
+			readiness: "blocked",
+			repositories: "agency",
+			branch: "feat/verify",
+			pr: "absent",
+			worktree: "absent",
+		})
+		expect(result.phaseRows[1]).toMatchObject({
+			readiness: "terminal",
+			pr: "present",
+			worktree: "materialized",
+		})
+		expect(result.taskRows[0]).toMatchObject({
+			parent: "delivery",
+			branch: "multiple",
+			pr: "1/2 present",
+			worktree: "1/2 materialized",
+		})
+	})
+
+	test("composes lifecycle, repository, readiness, and PR filters", async () => {
+		expect(
+			(await views({ statuses: ["dropped"] })).executionRows.map(
+				(row) => row.key,
+			),
+		).toEqual(["zeta/implement"])
+		expect(
+			(await views({ repositories: ["agency"], blocked: true })).phaseRows.map(
+				(row) => row.id,
+			),
+		).toEqual(["verify"])
+		expect(
+			(await views({ ready: true, pr: false })).executionRows.map(
+				(row) => row.key,
+			),
+		).toEqual(["alpha"])
+		expect((await views({ pr: true })).phaseRows.map((row) => row.id)).toEqual([
+			"implement",
+		])
+	})
+})

package/src/work-view.ts

@@ -0,0 +1,253 @@
+import { Effect } from "effect"
+import type { GraphNode } from "./graph-schema"
+import { GraphService } from "./services/GraphService"
+import type { WorkStatus } from "./workbase/schemas"
+
+type WorkNode = Extract<
+	GraphNode,
+	{ readonly kind: "epic" | "task" | "phase" | "execution-unit" }
+>
+type EntityNode = Exclude<WorkNode, { readonly kind: "execution-unit" }>
+type ExecutionNode = Extract<WorkNode, { readonly kind: "execution-unit" }>
+
+export interface WorkViewOptions {
+	readonly cwd?: string
+	readonly statuses?: readonly string[]
+	readonly repositories?: readonly string[]
+	readonly ready?: boolean
+	readonly blocked?: boolean
+	readonly pr?: boolean
+}
+
+export interface WorkViewRow {
+	readonly kind: "epic" | "task" | "phase"
+	readonly id: string
+	readonly key: string
+	readonly parent: string
+	readonly status: WorkStatus
+	readonly readiness: "ready" | "blocked" | "waiting" | "terminal"
+	readonly repositories: string
+	readonly branch: string
+	readonly pr: string
+	readonly worktree: string
+	readonly hasPr: boolean
+}
+
+const allowedStatuses = new Set<WorkStatus>([
+	"open",
+	"working",
+	"delegated",
+	"done",
+	"dropped",
+])
+
+const validatedStatuses = (values: readonly string[] | undefined) =>
+	(values ?? []).map((value) => {
+		if (!allowedStatuses.has(value as WorkStatus)) {
+			throw new Error(
+				`Invalid --status value '${value}'. Expected one of: ${[...allowedStatuses].join(", ")}`,
+			)
+		}
+		return value as WorkStatus
+	})
+
+const readinessLabel = (node: EntityNode): WorkViewRow["readiness"] =>
+	node.readiness.ready
+		? "ready"
+		: node.readiness.terminal
+			? "terminal"
+			: node.readiness.blocked
+				? "blocked"
+				: "waiting"
+
+const aggregateLabel = (
+	executions: readonly ExecutionNode[],
+	predicate: (node: ExecutionNode) => boolean,
+	singular: readonly [present: string, absent: string],
+) => {
+	if (executions.length === 0) return "-"
+	const count = executions.filter(predicate).length
+	if (executions.length === 1) return count === 1 ? singular[0] : singular[1]
+	return `${count}/${executions.length} ${singular[0]}`
+}
+
+const rowFor = (
+	node: EntityNode,
+	executions: readonly ExecutionNode[],
+): WorkViewRow => {
+	const branches = [
+		...new Set(executions.map((execution) => execution.data.branch)),
+	]
+	const parent =
+		node.kind === "task"
+			? (node.data.epic ?? "-")
+			: node.kind === "phase"
+				? node.key.slice(0, node.key.indexOf("/"))
+				: "-"
+	const id =
+		node.kind === "phase" ? node.key.slice(node.key.indexOf("/") + 1) : node.key
+
+	return {
+		kind: node.kind,
+		id,
+		key: node.key,
+		parent,
+		status: node.status,
+		readiness: readinessLabel(node),
+		repositories: node.repositories.join(",") || "-",
+		branch:
+			branches.length === 0
+				? "-"
+				: branches.length === 1
+					? branches[0]!
+					: "multiple",
+		pr: aggregateLabel(executions, (execution) => Boolean(execution.data.pr), [
+			"present",
+			"absent",
+		]),
+		worktree: aggregateLabel(
+			executions,
+			(execution) => execution.workspace?.materialized === true,
+			["materialized", "absent"],
+		),
+		hasPr: executions.some((execution) => Boolean(execution.data.pr)),
+	}
+}
+
+const orderedTasks = (
+	epics: readonly Extract<EntityNode, { readonly kind: "epic" }>[],
+	tasks: ReadonlyMap<string, Extract<EntityNode, { readonly kind: "task" }>>,
+) => {
+	const ordered: Extract<EntityNode, { readonly kind: "task" }>[] = []
+	const seen = new Set<string>()
+	for (const epic of epics) {
+		for (const item of epic.data.tasks) {
+			const task = tasks.get(item.id)
+			if (task && !seen.has(task.key)) {
+				ordered.push(task)
+				seen.add(task.key)
+			}
+		}
+	}
+	for (const task of [...tasks.values()].sort((a, b) =>
+		a.key.localeCompare(b.key),
+	)) {
+		if (!seen.has(task.key)) ordered.push(task)
+	}
+	return ordered
+}
+
+const orderedPhases = (
+	task: Extract<EntityNode, { readonly kind: "task" }>,
+	phases: ReadonlyMap<string, Extract<EntityNode, { readonly kind: "phase" }>>,
+) => {
+	const ordered: Extract<EntityNode, { readonly kind: "phase" }>[] = []
+	const seen = new Set<string>()
+	if ("phases" in task.data) {
+		for (const item of task.data.phases) {
+			const phase = phases.get(`${task.key}/${item.id}`)
+			if (phase) {
+				ordered.push(phase)
+				seen.add(phase.key)
+			}
+		}
+	}
+	for (const phase of [...phases.values()]
+		.filter((value) => value.key.startsWith(`${task.key}/`))
+		.sort((a, b) => a.key.localeCompare(b.key))) {
+		if (!seen.has(phase.key)) ordered.push(phase)
+	}
+	return ordered
+}
+
+export const getWorkViews = (options: WorkViewOptions = {}) =>
+	Effect.gen(function* () {
+		const graphService = yield* GraphService
+		const statuses = yield* Effect.sync(() =>
+			validatedStatuses(options.statuses),
+		)
+		const graph = yield* graphService.get({
+			cwd: options.cwd,
+			include: ["workspace"],
+		})
+		const workNodes = graph.nodes.filter(
+			(node): node is WorkNode => node.kind !== "repository",
+		)
+		const epics = workNodes
+			.filter(
+				(node): node is Extract<EntityNode, { readonly kind: "epic" }> =>
+					node.kind === "epic",
+			)
+			.sort((a, b) => a.key.localeCompare(b.key))
+		const tasks = new Map(
+			workNodes
+				.filter(
+					(node): node is Extract<EntityNode, { readonly kind: "task" }> =>
+						node.kind === "task",
+				)
+				.map((node) => [node.key, node]),
+		)
+		const phases = new Map(
+			workNodes
+				.filter(
+					(node): node is Extract<EntityNode, { readonly kind: "phase" }> =>
+						node.kind === "phase",
+				)
+				.map((node) => [node.key, node]),
+		)
+		const executions = workNodes.filter(
+			(node): node is ExecutionNode => node.kind === "execution-unit",
+		)
+		const taskOrder = orderedTasks(epics, tasks)
+		const phaseOrder = taskOrder.flatMap((task) => orderedPhases(task, phases))
+		const executionsFor = (node: EntityNode) => {
+			if (node.kind === "phase") {
+				const separator = node.key.indexOf("/")
+				const taskId = node.key.slice(0, separator)
+				const phaseId = node.key.slice(separator + 1)
+				return executions.filter(
+					(execution) =>
+						execution.data.taskId === taskId &&
+						execution.data.phaseId === phaseId,
+				)
+			}
+			if (node.kind === "task") {
+				return executions.filter(
+					(execution) => execution.data.taskId === node.key,
+				)
+			}
+			const taskIds = new Set(node.data.tasks.map((item) => item.id))
+			return executions.filter((execution) =>
+				taskIds.has(execution.data.taskId),
+			)
+		}
+		const makeRows = (nodes: readonly EntityNode[]) =>
+			nodes.map((node) => rowFor(node, executionsFor(node)))
+		const filterRows = (rows: readonly WorkViewRow[]) =>
+			rows
+				.filter((row) => statuses.length === 0 || statuses.includes(row.status))
+				.filter(
+					(row) =>
+						!options.repositories?.length ||
+						row.repositories
+							.split(",")
+							.some((repo) => options.repositories!.includes(repo)),
+				)
+				.filter((row) => options.ready !== true || row.readiness === "ready")
+				.filter(
+					(row) => options.blocked !== true || row.readiness === "blocked",
+				)
+				.filter((row) => options.pr === undefined || row.hasPr === options.pr)
+
+		const epicRows = filterRows(makeRows(epics))
+		const taskRows = filterRows(makeRows(taskOrder))
+		const phaseRows = filterRows(makeRows(phaseOrder))
+		const executionEntities: EntityNode[] = []
+		for (const task of taskOrder) {
+			const taskPhases = orderedPhases(task, phases)
+			executionEntities.push(...(taskPhases.length > 0 ? taskPhases : [task]))
+		}
+		const executionRows = filterRows(makeRows(executionEntities))
+
+		return { epicRows, taskRows, phaseRows, executionRows }
+	})

package/src/workbase/schemas.test.ts

@@ -185,23 +185,34 @@ describe("workbase registry", () => {
 	test("accepts registered paths", () => {
 		expect(
 			Schema.decodeUnknownSync(WorkbaseRegistry)({
-				version: 1,
-				workbases: ["/work/one", "/work/two"],
+				version: 2,
+				workbases: [
+					{ id: "wb-one", name: "one", path: "/work/one" },
+					{ id: "wb-two", path: "/work/two" },
+				],
+				defaultId: "wb-one",
 			}),
-		).toEqual({ version: 1, workbases: ["/work/one", "/work/two"] })
+		).toEqual({
+			version: 2,
+			workbases: [
+				{ id: "wb-one", name: "one", path: "/work/one" },
+				{ id: "wb-two", path: "/work/two" },
+			],
+			defaultId: "wb-one",
+		})
 	})
 
 	test("rejects invalid versions and empty paths", () => {
 		expect(() =>
 			Schema.decodeUnknownSync(WorkbaseRegistry)({
-				version: 2,
+				version: 3,
 				workbases: [],
 			}),
 		).toThrow()
 		expect(() =>
 			Schema.decodeUnknownSync(WorkbaseRegistry)({
-				version: 1,
-				workbases: [""],
+				version: 2,
+				workbases: [{ id: "wb-one", path: "" }],
 			}),
 		).toThrow()
 	})

package/src/workbase/schemas.ts

@@ -54,11 +54,23 @@ export const WorkbaseConfig = Schema.Struct({
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 })
 
-export const WorkbaseRegistry = Schema.Struct({
+export const LegacyWorkbaseRegistry = Schema.Struct({
 	version: Schema.Literal(1),
 	workbases: Schema.Array(NonEmptyString),
 })
 
+export const WorkbaseRegistration = Schema.Struct({
+	id: EntityId,
+	name: Schema.optional(EntityId),
+	path: NonEmptyString,
+})
+
+export const WorkbaseRegistry = Schema.Struct({
+	version: Schema.Literal(2),
+	workbases: Schema.Array(WorkbaseRegistration),
+	defaultId: Schema.optional(EntityId),
+})
+
 export const Dependency = Schema.Struct({
 	id: EntityId,
 	dependsOn: Schema.optional(Schema.Array(EntityId)),
@@ -107,6 +119,9 @@ export const PhaseFrontmatter = Schema.Struct({
 
 export type WorkbaseConfig = Schema.Schema.Type<typeof WorkbaseConfig>
 export type WorkbaseRegistry = Schema.Schema.Type<typeof WorkbaseRegistry>
+export type WorkbaseRegistration = Schema.Schema.Type<
+	typeof WorkbaseRegistration
+>
 export type Dependency = Schema.Schema.Type<typeof Dependency>
 export type RepositoryReference = Schema.Schema.Type<typeof RepositoryReference>
 export type WorkStatus = Schema.Schema.Type<typeof WorkStatus>

package/src/workbase/workbase-choice.ts

@@ -30,6 +30,8 @@ export const resolveWorkbase = (
 		return yield* workbase.discover(startPath).pipe(
 			Effect.catchTag("WorkbaseNotFoundError", () =>
 				Effect.gen(function* () {
+					const defaultWorkbase = yield* workbase.getDefault()
+					if (defaultWorkbase) return defaultWorkbase.path
 					const registered = yield* workbase.listRegistered()
 					if (registered.length === 0) {
 						return yield* Effect.fail(