@markjaquith/agency 2.24.0 → 2.26.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/RepositoryService.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { mkdir } from "node:fs/promises"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { RepositoryService } from "./RepositoryService"
 
@@ -16,6 +16,12 @@ const runGit = async (args: string[]) => {
 	}
 }
 
+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("RepositoryService", () => {
 	let root: string
 
@@ -103,4 +109,126 @@ describe("RepositoryService", () => {
 			),
 		).rejects.toThrow("already exists")
 	})
+
+	test("shows, fetches, updates, and verifies a repository", async () => {
+		const source = join(root, "source")
+		const replacement = join(root, "replacement.git")
+		await runGit(["init", "--initial-branch=main", source])
+		await Bun.write(join(source, "README.md"), "# Source\n")
+		await runGit(["-C", source, "add", "README.md"])
+		await runGit([
+			"-C",
+			source,
+			"-c",
+			"user.name=Agency Tests",
+			"-c",
+			"user.email=agency@example.com",
+			"commit",
+			"-m",
+			"Initial commit",
+		])
+		await runGit(["init", "--bare", "--initial-branch=main", replacement])
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.add("agency", source, root)),
+			),
+		)
+
+		const result = await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						const shown = yield* service.show("agency", root)
+						yield* service.fetch("agency", root)
+						const updated = yield* service.remote("agency", replacement, root)
+						const verified = yield* service.verify("agency", root)
+						return { shown, updated, verified }
+					}),
+				),
+			),
+		)
+
+		expect(result.shown.remote).toBe(source)
+		expect(result.updated.remote).toBe(replacement)
+		expect(result.verified.valid).toBe(true)
+		expect(result.verified.issues).toEqual([])
+	})
+
+	test("renames and removes an unused repository", async () => {
+		const source = join(root, "source.git")
+		await runGit(["init", "--bare", "--initial-branch=main", source])
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.add("old", source, root)),
+			),
+		)
+
+		const removed = await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						const renamed = yield* service.rename("old", "new", root)
+						expect(renamed.alias).toBe("new")
+						return yield* service.remove("new", root)
+					}),
+				),
+			),
+		)
+
+		expect(removed.alias).toBe("new")
+		expect(await Bun.file(join(root, "repos/new/HEAD")).exists()).toBe(false)
+	})
+
+	test("unlinks a symlink without deleting its target", async () => {
+		const target = join(root, "linked-repository")
+		await mkdir(target, { recursive: true })
+		await runGit(["init", "--initial-branch=main", target])
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.link("linked", target, root)),
+			),
+		)
+
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.unlink("linked", root)),
+			),
+		)
+
+		expect(await Bun.file(join(target, ".git/HEAD")).exists()).toBe(true)
+		expect(await Bun.file(join(root, "repos/linked/.git/HEAD")).exists()).toBe(
+			false,
+		)
+	})
+
+	test("reports active references and refuses unsafe removal", async () => {
+		const source = join(root, "source.git")
+		await runGit(["init", "--bare", "--initial-branch=main", source])
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.add("agency", source, root)),
+			),
+		)
+		await write(
+			root,
+			"tasks/active/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: task/active
+base: main
+pr: null
+---
+`,
+		)
+
+		await expect(
+			runTestEffect(
+				RepositoryService.pipe(
+					Effect.flatMap((service) => service.remove("agency", root)),
+				),
+			),
+		).rejects.toThrow("active reference execution-unit:task/active")
+		expect(await Bun.file(join(root, "repos/agency/HEAD")).exists()).toBe(true)
+	})
 })