@markjaquith/agency 2.24.0 → 2.25.0

package/src/services/LifecycleTransaction.ts

@@ -0,0 +1,302 @@
+import { Data, Effect } from "effect"
+import { lstat, mkdir, open, rename, rm } from "node:fs/promises"
+import { dirname, join, relative } from "node:path"
+import {
+	documentRevision,
+	RevisionConflictError,
+} from "../workbase/document-revision"
+
+class LifecycleTransactionError extends Data.TaggedError(
+	"LifecycleTransactionError",
+)<{
+	readonly message: string
+	readonly completed: readonly string[]
+	readonly rolledBack: readonly string[]
+	readonly manualRecovery: readonly string[]
+	readonly cause?: unknown
+}> {}
+
+export interface TransactionStep {
+	readonly label: string
+	readonly preflight?: () => Promise<void>
+	readonly apply: () => Promise<void>
+	readonly rollback?: () => Promise<void>
+	readonly finalize?: () => Promise<void>
+	readonly manualRecovery?: string
+}
+
+interface DocumentWrite {
+	readonly path: string
+	readonly content: string
+	readonly create?: boolean
+}
+
+interface TransactionPlan {
+	readonly root: string
+	readonly preconditions?: readonly {
+		readonly path: string
+		readonly revision: string
+	}[]
+	readonly steps: readonly TransactionStep[]
+}
+
+const exists = async (path: string) => {
+	try {
+		await lstat(path)
+		return true
+	} catch (error) {
+		if (
+			typeof error === "object" &&
+			error !== null &&
+			"code" in error &&
+			error.code === "ENOENT"
+		)
+			return false
+		throw error
+	}
+}
+
+export const documentWriteStep = (
+	root: string,
+	writes: readonly DocumentWrite[],
+): TransactionStep => {
+	const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+	const stagingDirectory = join(root, `.agency-transaction-${token}`)
+	const staged = writes.map((write, index) => ({
+		...write,
+		stage: join(stagingDirectory, `${index}.stage`),
+		backup: join(stagingDirectory, `${index}.backup`),
+	}))
+	const installed: typeof staged = []
+	const backedUp: typeof staged = []
+	const createdDirectories: string[] = []
+	const label = `install documents: ${writes
+		.map((write) => relative(root, write.path))
+		.join(", ")}`
+
+	const rollback = async () => {
+		for (const write of [...installed].reverse()) {
+			await rm(write.path, { force: true })
+		}
+		for (const write of [...backedUp].reverse()) {
+			if (await exists(write.backup)) await rename(write.backup, write.path)
+		}
+		for (const directory of [...createdDirectories].reverse()) {
+			await rm(directory, { recursive: true, force: true })
+		}
+		installed.length = 0
+		backedUp.length = 0
+		createdDirectories.length = 0
+	}
+
+	return {
+		label,
+		preflight: async () => {
+			for (const write of staged) {
+				const targetExists = await exists(write.path)
+				if (write.create === true && targetExists)
+					throw new Error(
+						`Document already exists: ${relative(root, write.path)}`,
+					)
+				if (write.create !== true && !targetExists)
+					throw new Error(
+						`Document does not exist: ${relative(root, write.path)}`,
+					)
+			}
+		},
+		apply: async () => {
+			await mkdir(stagingDirectory)
+			for (const write of staged) await Bun.write(write.stage, write.content)
+			try {
+				for (const write of staged) {
+					const parent = dirname(write.path)
+					if (!(await exists(parent))) {
+						await mkdir(parent, { recursive: true })
+						createdDirectories.push(parent)
+					}
+					if (!write.create) {
+						await rename(write.path, write.backup)
+						backedUp.push(write)
+					}
+					try {
+						await rename(write.stage, write.path)
+					} catch (cause) {
+						if (!write.create && (await exists(write.backup)))
+							await rename(write.backup, write.path)
+						throw cause
+					}
+					installed.push(write)
+				}
+			} catch (cause) {
+				try {
+					await rollback()
+					await rm(stagingDirectory, { recursive: true, force: true })
+				} catch (rollbackCause) {
+					throw new LifecycleTransactionError({
+						message: `Document installation failed and requires manual recovery: ${cause instanceof Error ? cause.message : String(cause)}`,
+						completed: [label],
+						rolledBack: [],
+						manualRecovery: [
+							`Inspect ${relative(root, stagingDirectory)} for staged documents and backups`,
+						],
+						cause: new AggregateError([cause, rollbackCause]),
+					})
+				}
+				throw cause
+			}
+		},
+		rollback,
+		finalize: async () => {
+			await rm(stagingDirectory, { recursive: true, force: true })
+		},
+		manualRecovery: `Inspect ${relative(root, stagingDirectory)} for staged documents and backups`,
+	}
+}
+
+export const directoryMoveStep = (
+	root: string,
+	from: string,
+	to: string,
+): TransactionStep => {
+	let createdParent = false
+	return {
+		label: `move ${relative(root, from)} to ${relative(root, to)}`,
+		preflight: async () => {
+			if (!(await exists(from)))
+				throw new Error(`Move source does not exist: ${relative(root, from)}`)
+			if (await exists(to))
+				throw new Error(
+					`Move destination already exists: ${relative(root, to)}`,
+				)
+		},
+		apply: async () => {
+			const parent = dirname(to)
+			if (!(await exists(parent))) {
+				await mkdir(parent, { recursive: true })
+				createdParent = true
+			}
+			await rename(from, to)
+		},
+		rollback: async () => {
+			await rename(to, from)
+			if (createdParent) await rm(dirname(to), { recursive: true, force: true })
+		},
+		manualRecovery: `Move ${relative(root, to)} back to ${relative(root, from)}`,
+	}
+}
+
+export const runLifecycleTransaction = ({
+	root,
+	preconditions = [],
+	steps,
+}: TransactionPlan) =>
+	Effect.tryPromise({
+		try: async () => {
+			const lockPath = join(root, ".agency-graph-mutation.lock")
+			let lock: Awaited<ReturnType<typeof open>>
+			try {
+				lock = await open(lockPath, "wx")
+			} catch (cause) {
+				throw new LifecycleTransactionError({
+					message:
+						"Another graph mutation is in progress; wait for it to finish and retry",
+					completed: [],
+					rolledBack: [],
+					manualRecovery: [],
+					cause,
+				})
+			}
+
+			const completed: TransactionStep[] = []
+			const rolledBack: string[] = []
+			try {
+				for (const precondition of preconditions) {
+					const content = await Bun.file(precondition.path).text()
+					const currentRevision = documentRevision(content)
+					if (currentRevision !== precondition.revision) {
+						throw new RevisionConflictError({
+							path: relative(root, precondition.path),
+							expectedRevision: precondition.revision,
+							currentRevision,
+							message: `Revision conflict for ${relative(root, precondition.path)}`,
+						})
+					}
+				}
+				for (const step of steps) await step.preflight?.()
+				for (const step of steps) {
+					await step.apply()
+					completed.push(step)
+				}
+				const cleanup = await Promise.allSettled(
+					completed.map((step) => step.finalize?.() ?? Promise.resolve()),
+				)
+				const cleanupFailures = cleanup.filter(
+					(result) => result.status === "rejected",
+				)
+				if (cleanupFailures.length > 0) {
+					throw new LifecycleTransactionError({
+						message:
+							"Lifecycle mutation completed, but transaction artifacts require manual cleanup",
+						completed: completed.map((step) => step.label),
+						rolledBack: [],
+						manualRecovery: completed.flatMap((step) =>
+							step.finalize && step.manualRecovery ? [step.manualRecovery] : [],
+						),
+						cause: new AggregateError(
+							cleanupFailures.map((result) =>
+								result.status === "rejected" ? result.reason : undefined,
+							),
+						),
+					})
+				}
+			} catch (cause) {
+				if (cause instanceof LifecycleTransactionError) throw cause
+				const rollbackErrors: unknown[] = []
+				for (const step of [...completed].reverse()) {
+					if (!step.rollback) continue
+					try {
+						await step.rollback()
+						rolledBack.push(step.label)
+						await step.finalize?.()
+					} catch (error) {
+						rollbackErrors.push(error)
+					}
+				}
+				const manualRecovery = completed
+					.filter(
+						(step) =>
+							!rolledBack.includes(step.label) &&
+							step.manualRecovery !== undefined,
+					)
+					.map((step) => step.manualRecovery!)
+				throw new LifecycleTransactionError({
+					message:
+						completed.length === 0
+							? `Lifecycle mutation failed before changes were applied: ${cause instanceof Error ? cause.message : String(cause)}`
+							: rollbackErrors.length
+								? `Lifecycle mutation failed and rollback requires manual recovery: ${cause instanceof Error ? cause.message : String(cause)}`
+								: `Lifecycle mutation failed; completed changes were rolled back: ${cause instanceof Error ? cause.message : String(cause)}`,
+					completed: completed.map((step) => step.label),
+					rolledBack,
+					manualRecovery,
+					cause: rollbackErrors.length
+						? new AggregateError([cause, ...rollbackErrors])
+						: cause,
+				})
+			} finally {
+				await lock.close().catch(() => undefined)
+				await rm(lockPath, { force: true }).catch(() => undefined)
+			}
+		},
+		catch: (cause) =>
+			cause instanceof LifecycleTransactionError ||
+			cause instanceof RevisionConflictError
+				? cause
+				: new LifecycleTransactionError({
+						message: "Lifecycle mutation failed before changes were applied",
+						completed: [],
+						rolledBack: [],
+						manualRecovery: [],
+						cause,
+					}),
+	})

package/src/services/PhaseService.ts

@@ -1,5 +1,6 @@
 import { Schema, TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either } from "effect"
+import { lstat, mkdir, readdir, realpath, rename, rm } from "node:fs/promises"
 import { join } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { WorkbaseService } from "./WorkbaseService"
@@ -18,6 +19,12 @@ import {
 import { canTransitionStatus } from "../readiness"
 import { documentRevision } from "../workbase/document-revision"
 import { archivedPhaseDirectory } from "../workbase/archive"
+import {
+	documentWriteStep,
+	runLifecycleTransaction,
+	type TransactionStep,
+} from "./LifecycleTransaction"
+import { withWorktreeLocks } from "./WorktreeLock"
 
 class PhaseError extends Data.TaggedError("PhaseError")<{
 	readonly message: string
@@ -156,6 +163,16 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 								]
 							: []),
 					])
+					const newAliases = [
+						data.repo,
+						...(data.repos ?? []).map((reference) => reference.repo),
+					]
+					if (new Set(newAliases).size !== newAliases.length) {
+						return yield* new PhaseError({
+							message:
+								"Repository references must be unique and cannot include the writable repository",
+						})
+					}
 					for (const alias of aliases) {
 						if (!(yield* fs.exists(join(root, "repos", alias)))) {
 							return yield* new PhaseError({
@@ -209,46 +226,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							.map((part) => part[0]?.toUpperCase() + part.slice(1))
 							.join(" ")
 
-						yield* fs.createDirectory(firstDirectory)
-						yield* fs.createDirectory(directory)
-						yield* fs.writeFile(
-							join(firstDirectory, "PHASE.md"),
-							formatMarkdownDocument(
-								firstData,
-								`# ${firstTitle}\n\nDescribe the phase outcome.`,
-							),
-						)
-						yield* fs.writeFile(path, content)
-
 						const oldCodePath = join(root, "tasks", taskId, "code")
-						if (yield* fs.isDirectory(oldCodePath)) {
-							const firstCodePath = join(firstDirectory, "code")
-							yield* fs.moveDirectory(oldCodePath, firstCodePath)
-							for (const alias of [
-								firstData.repo,
-								...(firstData.repos ?? []).map((reference) => reference.repo),
-							]) {
-								const checkoutPath = join(firstCodePath, alias)
-								if (!(yield* fs.isDirectory(checkoutPath))) continue
-								const repair = yield* fs.runCommand(
-									[
-										"git",
-										"-C",
-										join(root, "repos", alias),
-										"worktree",
-										"repair",
-										checkoutPath,
-									],
-									{ captureOutput: true },
-								)
-								if (repair.exitCode !== 0) {
-									return yield* new PhaseError({
-										message: `Failed to repair moved worktree for '${alias}': ${repair.stderr}`,
-									})
-								}
-							}
-						}
-
 						const convertedTaskData = {
 							ticketUrl: task.data.ticketUrl,
 							...(task.data.description
@@ -265,9 +243,129 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 								},
 							],
 						}
-						yield* fs.writeFile(
-							task.path,
-							formatMarkdownDocument(convertedTaskData, parsedTask.body),
+						const firstPhasePath = join(firstDirectory, "PHASE.md")
+						const firstContent = formatMarkdownDocument(
+							firstData,
+							`# ${firstTitle}\n\nDescribe the phase outcome.`,
+						)
+						const steps: TransactionStep[] = []
+						if (yield* fs.isDirectory(oldCodePath)) {
+							const firstCodePath = join(firstDirectory, "code")
+							const checkoutAliases = [
+								firstData.repo,
+								...(firstData.repos ?? []).map((reference) => reference.repo),
+							]
+							const repair = async (basePath: string) => {
+								for (const alias of checkoutAliases) {
+									const checkoutPath = join(basePath, alias)
+									try {
+										await lstat(checkoutPath)
+									} catch {
+										continue
+									}
+									const result = Bun.spawnSync([
+										"git",
+										"-C",
+										join(root, "repos", alias),
+										"worktree",
+										"repair",
+										checkoutPath,
+									])
+									if (result.exitCode !== 0) {
+										throw new Error(
+											`Failed to repair moved worktree for '${alias}': ${new TextDecoder().decode(result.stderr)}`,
+										)
+									}
+								}
+							}
+							steps.push({
+								label: `move and repair code for ${taskId}/${firstPhaseId}`,
+								preflight: async () => {
+									for (const entry of await readdir(oldCodePath)) {
+										if (!checkoutAliases.includes(entry))
+											throw new Error(
+												`Cannot convert task '${taskId}'; code contains unmanaged entry '${entry}'`,
+											)
+									}
+									for (const alias of checkoutAliases) {
+										const checkoutPath = join(oldCodePath, alias)
+										try {
+											await lstat(checkoutPath)
+										} catch {
+											continue
+										}
+										const listed = Bun.spawnSync([
+											"git",
+											"-C",
+											join(root, "repos", alias),
+											"worktree",
+											"list",
+											"--porcelain",
+										])
+										if (listed.exitCode !== 0)
+											throw new Error(
+												`Failed to inspect worktrees for '${alias}'`,
+											)
+										const expected = await realpath(checkoutPath)
+										let registered = false
+										for (const line of new TextDecoder()
+											.decode(listed.stdout)
+											.split("\n")) {
+											if (!line.startsWith("worktree ")) continue
+											try {
+												if ((await realpath(line.slice(9))) === expected) {
+													registered = true
+													break
+												}
+											} catch {}
+										}
+										if (!registered)
+											throw new Error(
+												`Cannot convert task '${taskId}'; checkout '${alias}' is not registered as a Git worktree`,
+											)
+									}
+								},
+								apply: async () => {
+									await mkdir(firstDirectory, { recursive: true })
+									await rename(oldCodePath, firstCodePath)
+									try {
+										await repair(firstCodePath)
+									} catch (cause) {
+										await rename(firstCodePath, oldCodePath)
+										await repair(oldCodePath)
+										await rm(firstDirectory, { recursive: true, force: true })
+										throw cause
+									}
+								},
+								rollback: async () => {
+									await rename(firstCodePath, oldCodePath)
+									await repair(oldCodePath)
+									await rm(firstDirectory, { recursive: true, force: true })
+								},
+								manualRecovery: `Move ${firstCodePath} back to ${oldCodePath} and run git worktree repair`,
+							})
+						}
+						steps.push(
+							documentWriteStep(root, [
+								{ path: firstPhasePath, content: firstContent, create: true },
+								{ path, content, create: true },
+								{
+									path: task.path,
+									content: formatMarkdownDocument(
+										convertedTaskData,
+										parsedTask.body,
+									),
+								},
+							]),
+						)
+						yield* withWorktreeLocks(
+							root,
+							[{ taskId }],
+							runLifecycleTransaction({
+								root,
+								preconditions: [{ path: task.path, revision: task.revision }],
+								steps,
+							}),
 						)
 						return {
 							taskId,
@@ -279,8 +377,6 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						} satisfies PhaseRecord
 					}
 
-					yield* fs.createDirectory(directory)
-					yield* fs.writeFile(path, content)
 					const updatedTaskData = {
 						...task.data,
 						phases: [
@@ -293,10 +389,22 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							},
 						],
 					}
-					yield* fs.writeFile(
-						task.path,
-						formatMarkdownDocument(updatedTaskData, parsedTask.body),
-					)
+					yield* runLifecycleTransaction({
+						root,
+						preconditions: [{ path: task.path, revision: task.revision }],
+						steps: [
+							documentWriteStep(root, [
+								{ path, content, create: true },
+								{
+									path: task.path,
+									content: formatMarkdownDocument(
+										updatedTaskData,
+										parsedTask.body,
+									),
+								},
+							]),
+						],
+					})
 
 					return {
 						taskId,

package/src/services/TaskPhaseService.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdir } from "node:fs/promises"
+import { mkdir, rm } from "node:fs/promises"
 import { join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { EpicService } from "./EpicService"
@@ -60,6 +60,52 @@ describe("task and phase services", () => {
 		expect(epic.data.tasks).toEqual([{ id: "task-one" }])
 	})
 
+	test("does not create a task when its parent update cannot start", async () => {
+		await runTestEffect(
+			EpicService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						"locked",
+						"https://example.com/epic",
+						[{ repo: "agency", ref: "main" }],
+						root,
+					),
+				),
+			),
+		)
+		const lock = join(root, ".agency-graph-mutation.lock")
+		await Bun.write(lock, "held")
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{
+								id: "not-created",
+								ticketUrl: null,
+								epic: "locked",
+								repo: "agency",
+								branch: "task/not-created",
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("Another graph mutation is in progress")
+		await rm(lock)
+		expect(
+			await Bun.file(join(root, "tasks/not-created/TASK.md")).exists(),
+		).toBe(false)
+		const epic = await runTestEffect(
+			EpicService.pipe(
+				Effect.flatMap((service) => service.show("locked", root)),
+			),
+		)
+		expect(epic.data.tasks).toEqual([])
+	})
+
 	test("creates and sequences phases on a multi-phase task", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/TaskService.ts

@@ -18,6 +18,10 @@ import {
 import { canTransitionStatus } from "../readiness"
 import { documentRevision } from "../workbase/document-revision"
 import { archivedTaskDirectory } from "../workbase/archive"
+import {
+	documentWriteStep,
+	runLifecycleTransaction,
+} from "./LifecycleTransaction"
 
 class TaskError extends Data.TaggedError("TaskError")<{
 	readonly message: string
@@ -129,6 +133,12 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 								...(data.repos ?? []).map((reference) => reference.repo),
 							]
 						: []
+				if (new Set(referencedRepos).size !== referencedRepos.length) {
+					return yield* new TaskError({
+						message:
+							"Repository references must be unique and cannot include the writable repository",
+					})
+				}
 				for (const alias of referencedRepos) {
 					if (!(yield* fs.exists(join(root, "repos", alias)))) {
 						return yield* new TaskError({
@@ -140,6 +150,11 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				let parentEpic: EpicRecord | undefined
 				if (input.epic) {
 					parentEpic = yield* epics.show(input.epic, root)
+					if (parentEpic.data.tasks.some((task) => task.id === id)) {
+						return yield* new TaskError({
+							message: `Epic '${input.epic}' already lists task '${id}'`,
+						})
+					}
 				}
 
 				const title = id
@@ -150,9 +165,11 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					data,
 					`# ${title}\n\nDescribe the task outcome.`,
 				)
-				yield* fs.createDirectory(directory)
-				yield* fs.writeFile(path, content)
-
+				const writes: {
+					path: string
+					content: string
+					create?: boolean
+				}[] = [{ path, content, create: true }]
 				if (input.epic && parentEpic) {
 					const parsed = yield* parseFrontmatter(
 						parentEpic.content,
@@ -163,8 +180,15 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 						tasks: [...parentEpic.data.tasks, { id }],
 					}
 					const updated = formatMarkdownDocument(epicData, parsed.body)
-					yield* fs.writeFile(parentEpic.path, updated)
+					writes.push({ path: parentEpic.path, content: updated })
 				}
+				yield* runLifecycleTransaction({
+					root,
+					preconditions: parentEpic
+						? [{ path: parentEpic.path, revision: parentEpic.revision }]
+						: [],
+					steps: [documentWriteStep(root, writes)],
+				})
 
 				return {
 					id,