@markjaquith/agency 1.11.0 → 2.0.0

package/src/services/TaskService.ts

@@ -0,0 +1,192 @@
+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 { EpicService, type EpicRecord } from "./EpicService"
+import {
+	EntityId,
+	TaskFrontmatter,
+	type RepositoryReference,
+	type TaskFrontmatter as TaskData,
+} from "../workbase/schemas"
+import {
+	formatMarkdownDocument,
+	parseFrontmatter,
+} from "../workbase/frontmatter"
+
+class TaskError extends Data.TaggedError("TaskError")<{
+	readonly message: string
+}> {}
+
+interface TaskRecord {
+	readonly id: string
+	readonly path: string
+	readonly content: string
+	readonly data: TaskData
+}
+
+export interface CreateTaskInput {
+	readonly id: string
+	readonly ticketUrl: string
+	readonly description?: string
+	readonly epic?: string
+	readonly multiPhase?: boolean
+	readonly repo?: string
+	readonly repos?: readonly RepositoryReference[]
+	readonly branch?: string
+	readonly base?: string
+}
+
+const decodeTask = (input: unknown) => {
+	const result = Schema.decodeUnknownEither(TaskFrontmatter, {
+		errors: "all",
+		onExcessProperty: "error",
+	})(input)
+	return Either.isLeft(result)
+		? Effect.fail(
+				new TaskError({ message: TreeFormatter.formatErrorSync(result.left) }),
+			)
+		: Effect.succeed(result.right)
+}
+
+const decodeId = (id: string) => {
+	const result = Schema.decodeUnknownEither(EntityId)(id)
+	return Either.isLeft(result)
+		? Effect.fail(new TaskError({ message: `Invalid task ID '${id}'` }))
+		: Effect.succeed(result.right)
+}
+
+export class TaskService extends Effect.Service<TaskService>()("TaskService", {
+	sync: () => ({
+		create: (input: CreateTaskInput, startPath: string = process.cwd()) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const workbase = yield* WorkbaseService
+				const epics = yield* EpicService
+				const root = yield* workbase.discover(startPath)
+				const id = yield* decodeId(input.id)
+				const directory = join(root, "tasks", id)
+				const path = join(directory, "TASK.md")
+
+				if (yield* fs.exists(directory)) {
+					return yield* new TaskError({
+						message: `Task '${id}' already exists`,
+					})
+				}
+
+				let data: TaskData
+				if (input.multiPhase) {
+					data = yield* decodeTask({
+						ticketUrl: input.ticketUrl,
+						...(input.description !== undefined
+							? { description: input.description }
+							: {}),
+						...(input.epic ? { epic: input.epic } : {}),
+						phases: [],
+					})
+				} else {
+					if (!input.repo || !input.branch || !input.base) {
+						return yield* new TaskError({
+							message: "Single-phase tasks require repo, branch, and base",
+						})
+					}
+					data = yield* decodeTask({
+						ticketUrl: input.ticketUrl,
+						...(input.description !== undefined
+							? { description: input.description }
+							: {}),
+						...(input.epic ? { epic: input.epic } : {}),
+						repo: input.repo,
+						...(input.repos?.length ? { repos: input.repos } : {}),
+						branch: input.branch,
+						base: input.base,
+						pr: null,
+					})
+				}
+
+				const referencedRepos =
+					"repo" in data
+						? [
+								data.repo,
+								...(data.repos ?? []).map((reference) => reference.repo),
+							]
+						: []
+				for (const alias of referencedRepos) {
+					if (!(yield* fs.exists(join(root, "repos", alias)))) {
+						return yield* new TaskError({
+							message: `Unknown repository alias '${alias}'`,
+						})
+					}
+				}
+
+				let parentEpic: EpicRecord | undefined
+				if (input.epic) {
+					parentEpic = yield* epics.show(input.epic, root)
+				}
+
+				const title = id
+					.split("-")
+					.map((part) => part[0]?.toUpperCase() + part.slice(1))
+					.join(" ")
+				const content = formatMarkdownDocument(
+					data,
+					`# ${title}\n\nDescribe the task outcome.`,
+				)
+				yield* fs.createDirectory(directory)
+				yield* fs.writeFile(path, content)
+
+				if (input.epic && parentEpic) {
+					const parsed = yield* parseFrontmatter(
+						parentEpic.content,
+						parentEpic.path,
+					)
+					const epicData = {
+						...parentEpic.data,
+						tasks: [...parentEpic.data.tasks, { id }],
+					}
+					const updated = formatMarkdownDocument(epicData, parsed.body)
+					yield* fs.writeFile(parentEpic.path, updated)
+				}
+
+				return { id, path, content, data } satisfies TaskRecord
+			}),
+
+		list: (startPath: string = process.cwd()) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const workbase = yield* WorkbaseService
+				const root = yield* workbase.discover(startPath)
+				const directory = join(root, "tasks")
+				if (!(yield* fs.isDirectory(directory))) return [] as TaskRecord[]
+				const entries = (yield* fs.readDirectory(directory))
+					.filter((entry) => entry.isDirectory)
+					.sort((a, b) => a.name.localeCompare(b.name))
+				const records: TaskRecord[] = []
+				for (const entry of entries) {
+					const path = join(directory, entry.name, "TASK.md")
+					if (!(yield* fs.exists(path))) continue
+					const content = yield* fs.readFile(path)
+					const parsed = yield* parseFrontmatter(content, path)
+					const data = yield* decodeTask(parsed.data)
+					records.push({ id: entry.name, path, content, data })
+				}
+				return records
+			}),
+
+		show: (id: string, startPath: string = process.cwd()) =>
+			Effect.gen(function* () {
+				const service = yield* TaskService
+				const validId = yield* decodeId(id)
+				const record = (yield* service.list(startPath)).find(
+					(task) => task.id === validId,
+				)
+				if (!record) {
+					return yield* new TaskError({
+						message: `Task '${validId}' does not exist`,
+					})
+				}
+				return record
+			}),
+	}),
+}) {}

package/src/services/WorkbaseService.test.ts

@@ -0,0 +1,446 @@
+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 { WorkbaseService } from "./WorkbaseService"
+
+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("WorkbaseService", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+	})
+
+	afterEach(async () => {
+		await cleanupTempDir(root)
+	})
+
+	test("discovers a workbase from a nested directory", async () => {
+		await write(root, "agency.json", '{"version":2}\n')
+		await mkdir(join(root, "nested/repository/src"), { recursive: true })
+
+		const discovered = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.discover(join(root, "nested/repository/src")),
+				),
+			),
+		)
+
+		expect(discovered).toBe(root)
+	})
+
+	test("rejects an invalid worktree command template", async () => {
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				worktreeCreateCommand: ["tool", "{repo}"],
+			}),
+		)
+
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) => service.discover(root)),
+				),
+			),
+		).rejects.toThrow("{worktree}")
+	})
+
+	test("validates a workbase with an epic and multi-phase task", async () => {
+		await write(root, "agency.json", '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await mkdir(join(root, "repos/effect"), { recursive: true })
+		await write(
+			root,
+			"epics/example/EPIC.md",
+			`---
+ticketUrl: https://example.com/epics/example
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: example-task
+---
+
+# Example
+`,
+		)
+		await write(
+			root,
+			"tasks/example-task/TASK.md",
+			`---
+ticketUrl: https://example.com/tasks/example
+epic: example
+phases:
+  - id: implementation
+---
+
+# Example task
+`,
+		)
+		await write(
+			root,
+			"tasks/example-task/phases/implementation/PHASE.md",
+			`---
+repo: agency
+repos:
+  - repo: effect
+    ref: main
+branch: task/example
+base: main
+pr: null
+---
+
+# Implementation
+`,
+		)
+
+		const report = await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.validate(root))),
+		)
+
+		expect(report.valid).toBe(true)
+		expect(report.issues).toEqual([])
+		expect(report.epicCount).toBe(1)
+		expect(report.taskCount).toBe(1)
+		expect(report.phaseCount).toBe(1)
+	})
+
+	test("reports schema, alias, backlink, and dependency errors", async () => {
+		await write(root, "agency.json", '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await write(
+			root,
+			"epics/example/EPIC.md",
+			`---
+ticketUrl: https://example.com/epics/example
+repos:
+  - repo: missing
+    ref: main
+tasks:
+  - id: example-task
+    dependsOn:
+      - absent-task
+---
+
+# Example
+`,
+		)
+		await write(
+			root,
+			"tasks/example-task/TASK.md",
+			`---
+ticketUrl: https://example.com/tasks/example
+repo: agency
+repos:
+  - repo: agency
+    ref: main
+branch: task/example
+base: main
+pr: null
+---
+
+# Example task
+`,
+		)
+		await write(
+			root,
+			"tasks/bad-schema/TASK.md",
+			`---
+ticketUrl: https://example.com/tasks/bad-schema
+repo: agency
+branch: task/bad-schema
+base: main
+pr: not-a-url
+---
+
+# Bad schema
+`,
+		)
+
+		const report = await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.validate(root))),
+		)
+
+		expect(report.valid).toBe(false)
+		expect(report.issues.map((issue) => issue.message).join("\n")).toContain(
+			"Unknown repository alias 'missing'",
+		)
+		expect(report.issues.map((issue) => issue.message).join("\n")).toContain(
+			"Unknown task dependency 'absent-task'",
+		)
+		expect(report.issues.map((issue) => issue.message).join("\n")).toContain(
+			"Task must reference parent epic 'example'",
+		)
+		expect(report.issues.map((issue) => issue.message).join("\n")).toContain(
+			"Repository 'agency' cannot also be a reference",
+		)
+		expect(
+			report.issues.some(
+				(issue) => issue.path.endsWith("bad-schema/TASK.md") && issue.message,
+			),
+		).toBe(true)
+		expect(report.issues.some((issue) => issue.path.endsWith("TASK.md"))).toBe(
+			true,
+		)
+	})
+
+	test("reports duplicate writable branch ownership", async () => {
+		await write(root, "agency.json", '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		for (const id of ["first", "second"]) {
+			await write(
+				root,
+				`tasks/${id}/TASK.md`,
+				`---
+ticketUrl: https://example.com/tasks/${id}
+repo: agency
+branch: task/shared
+base: main
+pr: null
+---
+`,
+			)
+		}
+
+		const report = await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.validate(root))),
+		)
+
+		expect(report.valid).toBe(false)
+		expect(report.issues).toContainEqual({
+			path: "tasks/second/TASK.md",
+			message:
+				"Writable branch 'task/shared' for repository 'agency' is also owned by tasks/first/TASK.md",
+		})
+	})
+
+	test("reports high-risk structural validation failures", async () => {
+		const fixtures: readonly {
+			name: string
+			files: Readonly<Record<string, string>>
+			directories?: readonly string[]
+			expected: readonly string[]
+		}[] = [
+			{
+				name: "missing-documents",
+				files: {},
+				directories: [
+					"epics/missing-epic",
+					"tasks/missing-task",
+					"tasks/missing-task/phases/missing-phase",
+				],
+				expected: [
+					"epics/missing-epic/EPIC.md: Required document is missing",
+					"tasks/missing-task/TASK.md: Required document is missing",
+					"tasks/missing-task/phases/missing-phase/PHASE.md: Required document is missing",
+				],
+			},
+			{
+				name: "duplicates",
+				files: {
+					"epics/duplicate/EPIC.md": `---
+ticketUrl: https://example.com/epics/duplicate
+repos:
+  - repo: agency
+    ref: main
+  - repo: agency
+    ref: release
+tasks:
+  - id: child
+  - id: child
+---
+`,
+					"tasks/child/TASK.md": `---
+ticketUrl: https://example.com/tasks/child
+epic: duplicate
+phases:
+  - id: implementation
+  - id: implementation
+---
+`,
+					"tasks/child/phases/implementation/PHASE.md": `---
+repo: agency
+branch: task/duplicate
+base: main
+pr: null
+---
+`,
+				},
+				expected: [
+					"Repository references must be unique",
+					"Epic task IDs must be unique",
+					"Task phase IDs must be unique",
+				],
+			},
+			{
+				name: "backlinks",
+				files: {
+					"epics/parent/EPIC.md": `---
+ticketUrl: https://example.com/epics/parent
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: missing-backlink
+---
+`,
+					"tasks/missing-backlink/TASK.md": `---
+ticketUrl: https://example.com/tasks/missing-backlink
+repo: agency
+branch: task/missing-backlink
+base: main
+pr: null
+---
+`,
+					"tasks/unlisted/TASK.md": `---
+ticketUrl: https://example.com/tasks/unlisted
+epic: parent
+repo: agency
+branch: task/unlisted
+base: main
+pr: null
+---
+`,
+				},
+				expected: [
+					"Task must reference parent epic 'parent'",
+					"Epic does not list child task 'unlisted'",
+				],
+			},
+			{
+				name: "dependency-cycles",
+				files: {
+					"epics/cycles/EPIC.md": `---
+ticketUrl: https://example.com/epics/cycles
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: first
+    dependsOn: [second]
+  - id: second
+    dependsOn: [first]
+---
+`,
+					"tasks/first/TASK.md": `---
+ticketUrl: https://example.com/tasks/first
+epic: cycles
+phases:
+  - id: contract
+    dependsOn: [delivery]
+  - id: delivery
+    dependsOn: [contract]
+---
+`,
+					"tasks/first/phases/contract/PHASE.md": `---
+repo: agency
+branch: task/contract
+base: main
+pr: null
+---
+`,
+					"tasks/first/phases/delivery/PHASE.md": `---
+repo: agency
+branch: task/delivery
+base: main
+pr: null
+---
+`,
+					"tasks/second/TASK.md": `---
+ticketUrl: https://example.com/tasks/second
+epic: cycles
+repo: agency
+branch: task/second
+base: main
+pr: null
+---
+`,
+				},
+				expected: [
+					"Task dependency cycle includes 'first'",
+					"Phase dependency cycle includes 'contract'",
+				],
+			},
+			{
+				name: "phase-layout",
+				files: {
+					"tasks/multi/TASK.md": `---
+ticketUrl: https://example.com/tasks/multi
+phases:
+  - id: listed
+---
+`,
+					"tasks/multi/phases/listed/PHASE.md": `---
+repo: agency
+branch: task/listed
+base: main
+pr: null
+---
+`,
+					"tasks/multi/phases/unlisted/PHASE.md": `---
+repo: agency
+branch: task/unlisted
+base: main
+pr: null
+---
+`,
+					"tasks/single/TASK.md": `---
+ticketUrl: https://example.com/tasks/single
+repo: agency
+branch: task/single
+base: main
+pr: null
+---
+`,
+					"tasks/single/phases/unexpected/PHASE.md": `---
+repo: agency
+branch: task/unexpected
+base: main
+pr: null
+---
+`,
+				},
+				expected: [
+					"Unlisted phase 'unlisted'",
+					"Single-phase task cannot contain phase directories",
+				],
+			},
+		]
+
+		for (const fixture of fixtures) {
+			const fixtureRoot = join(root, fixture.name)
+			await write(fixtureRoot, "agency.json", '{"version":2}\n')
+			await mkdir(join(fixtureRoot, "repos/agency"), { recursive: true })
+			for (const directory of fixture.directories ?? []) {
+				await mkdir(join(fixtureRoot, directory), { recursive: true })
+			}
+			for (const [path, content] of Object.entries(fixture.files)) {
+				await write(fixtureRoot, path, content)
+			}
+
+			const report = await runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) => service.validate(fixtureRoot)),
+				),
+			)
+			const messages = report.issues
+				.map((issue) => `${issue.path}: ${issue.message}`)
+				.join("\n")
+			expect(report.valid, fixture.name).toBe(false)
+			for (const expected of fixture.expected) {
+				expect(messages, fixture.name).toContain(expected)
+			}
+		}
+	})
+})