@markjaquith/agency 2.23.0 → 2.25.0

package/src/services/EpicService.ts

@@ -13,6 +13,7 @@ import {
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { documentRevision } from "../workbase/document-revision"
+import { archivedEpicDirectory } from "../workbase/archive"
 
 class EpicError extends Data.TaggedError("EpicError")<{
 	readonly message: string
@@ -73,6 +74,11 @@ export class EpicService extends Effect.Service<EpicService>()("EpicService", {
 						message: `Epic '${validId}' already exists`,
 					})
 				}
+				if (yield* fs.exists(archivedEpicDirectory(root, validId))) {
+					return yield* new EpicError({
+						message: `Epic '${validId}' is archived; restore it before reusing this ID`,
+					})
+				}
 
 				for (const { repo: alias } of data.repos) {
 					if (!(yield* fs.exists(join(root, "repos", alias)))) {

package/src/services/LifecycleTransaction.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir } from "../test-utils"
+import {
+	documentWriteStep,
+	runLifecycleTransaction,
+} from "./LifecycleTransaction"
+
+describe("lifecycle transactions", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("completes every preflight before applying the first step", async () => {
+		const marker = join(root, "marker")
+		await expect(
+			Effect.runPromise(
+				runLifecycleTransaction({
+					root,
+					steps: [
+						{
+							label: "write marker",
+							apply: () => Bun.write(marker, "applied").then(() => undefined),
+						},
+						{
+							label: "reject plan",
+							preflight: async () => {
+								throw new Error("preflight rejected")
+							},
+							apply: async () => undefined,
+						},
+					],
+				}),
+			),
+		).rejects.toThrow("failed before changes were applied")
+		expect(await Bun.file(marker).exists()).toBe(false)
+	})
+
+	test("installs document writes together and rolls them back together", async () => {
+		const existing = join(root, "existing.md")
+		const created = join(root, "nested", "created.md")
+		await Bun.write(existing, "before")
+
+		let failure: any
+		const result = await Effect.runPromise(
+			runLifecycleTransaction({
+				root,
+				steps: [
+					documentWriteStep(root, [
+						{ path: existing, content: "after" },
+						{ path: created, content: "created", create: true },
+					]),
+					{
+						label: "fail after documents",
+						apply: async () => {
+							throw new Error("injected failure")
+						},
+					},
+				],
+			}).pipe(Effect.either),
+		)
+		if (result._tag === "Left") failure = result.left
+
+		expect(failure.completed).toEqual([
+			"install documents: existing.md, nested/created.md",
+		])
+		expect(failure.rolledBack).toEqual(failure.completed)
+		expect(failure.manualRecovery).toEqual([])
+		expect(await Bun.file(existing).text()).toBe("before")
+		expect(await Bun.file(created).exists()).toBe(false)
+	})
+
+	test("reports completed and manually recoverable work when rollback fails", async () => {
+		let failure: any
+		const result = await Effect.runPromise(
+			runLifecycleTransaction({
+				root,
+				steps: [
+					{
+						label: "external mutation",
+						apply: async () => undefined,
+						rollback: async () => {
+							throw new Error("rollback failed")
+						},
+						manualRecovery: "undo external mutation",
+					},
+					{
+						label: "injected failure",
+						apply: async () => {
+							throw new Error("apply failed")
+						},
+					},
+				],
+			}).pipe(Effect.either),
+		)
+		if (result._tag === "Left") failure = result.left
+
+		expect(failure.completed).toEqual(["external mutation"])
+		expect(failure.rolledBack).toEqual([])
+		expect(failure.manualRecovery).toEqual(["undo external mutation"])
+	})
+})

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"
@@ -17,6 +18,13 @@ import {
 } from "../workbase/frontmatter"
 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
@@ -114,6 +122,11 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							message: `Phase '${id}' already exists on task '${taskId}'`,
 						})
 					}
+					if (yield* fs.exists(archivedPhaseDirectory(root, taskId, id))) {
+						return yield* new PhaseError({
+							message: `Phase '${id}' on task '${taskId}' is archived; restore it before reusing this ID`,
+						})
+					}
 					const knownPhases = new Set(
 						isMultiPhase
 							? task.data.phases.map((phase) => phase.id)
@@ -150,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({
@@ -203,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
@@ -259,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,
@@ -273,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: [
@@ -287,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,