@markjaquith/agency 2.25.0 → 2.27.0

package/src/commands/workbase.ts

@@ -51,6 +51,54 @@ export const workbase = (options: WorkbaseOptions) =>
 				}
 				return
 			}
+			case "show": {
+				const selector = options.args[0]
+				if (!selector) {
+					return yield* Effect.fail(
+						new Error("Usage: agency workbase show <selector>"),
+					)
+				}
+				const entry = yield* service.showRegistered(
+					selector,
+					options.configDirectory,
+					options.cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(entry, null, 2)
+						: `${entry.name ?? entry.id}\t${entry.path}`,
+				)
+				return
+			}
+			case "name": {
+				const selector = options.args[0]
+				const name = options.clear ? null : options.args[1]
+				if (
+					!selector ||
+					name === undefined ||
+					(options.clear && options.args[1] !== undefined)
+				) {
+					return yield* Effect.fail(
+						new Error(
+							"Usage: agency workbase name <selector> <name> | --clear",
+						),
+					)
+				}
+				const entry = yield* service.nameRegistered(
+					selector,
+					name,
+					options.configDirectory,
+					options.cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(entry, null, 2)
+						: name === null
+							? `Cleared name for ${entry.id}`
+							: `Named workbase ${name}`,
+				)
+				return
+			}
 			case "remove": {
 				const entry = yield* service.removeRegistered(
 					options.args[0]!,
@@ -89,6 +137,7 @@ export const workbase = (options: WorkbaseOptions) =>
 				const entry = yield* service.setDefault(
 					selector,
 					options.configDirectory,
+					options.cwd,
 				)
 				log(
 					options.json
@@ -102,7 +151,7 @@ export const workbase = (options: WorkbaseOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available: add, list, remove, prune, default",
+						"Subcommand is required. Available: add, list, show, name, remove, prune, default",
 					),
 				)
 		}
@@ -114,6 +163,8 @@ Usage: agency workbase <subcommand>
 Subcommands:
   add <path>        Register an Agency workbase
   list              List registered workbases
+  show <selector>   Show a registered workbase
+  name <selector>   Set or clear a registered workbase name
   remove <selector> Remove a registered workbase
   prune             Remove registrations whose paths no longer exist
   default [selector] Show or set the default workbase

package/src/commands/worktree.ts

@@ -0,0 +1,138 @@
+import { Effect } from "effect"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+import { WorktreeService } from "../services/WorktreeService"
+
+interface WorktreeOptions extends BaseCommandOptions {
+	readonly subcommand?: string
+	readonly args?: readonly string[]
+}
+
+const targetLabel = (owner: {
+	readonly kind: "task" | "phase"
+	readonly taskId: string
+	readonly phaseId?: string
+}) =>
+	owner.kind === "phase"
+		? `phase:${owner.taskId}/${owner.phaseId}`
+		: `task:${owner.taskId}`
+
+export const worktree = (options: WorktreeOptions = {}) =>
+	Effect.gen(function* () {
+		const worktrees = yield* WorktreeService
+		const { log } = createLoggers(options)
+		const root = options.cwd ?? process.cwd()
+		const subcommand = options.subcommand
+		const taskId = options.args?.[0]
+		const phaseId = options.args?.[1]
+
+		if (subcommand === "list") {
+			const inspections = yield* worktrees.list(root)
+			if (options.json) return log(JSON.stringify(inspections, null, 2))
+			for (const inspection of inspections) {
+				for (const checkout of inspection.checkouts) {
+					const state = checkout.conflicts.length
+						? `conflict:${checkout.conflicts.map(({ kind }) => kind).join(",")}`
+						: checkout.exists
+							? checkout.dirty
+								? "dirty"
+								: "ready"
+							: "missing"
+					log(
+						`${targetLabel(inspection.owner)}\t${checkout.kind}\t${checkout.repo}\t${state}\t${checkout.path}`,
+					)
+				}
+			}
+			return
+		}
+
+		if (!taskId) {
+			return yield* Effect.fail(
+				new Error("Worktree command requires a task ID"),
+			)
+		}
+		if (subcommand === "inspect") {
+			const inspection = yield* worktrees.inspect(taskId, phaseId, root)
+			if (options.json) return log(JSON.stringify(inspection, null, 2))
+			for (const checkout of inspection.checkouts) {
+				const owners = checkout.owners
+					.map((owner) => targetLabel(owner))
+					.join(",")
+				log(
+					`${checkout.kind} ${checkout.repo}: path=${checkout.path} registered=${checkout.registeredPath ?? "no"} branch=${checkout.actualBranch ?? "detached"} commit=${checkout.actualCommit ?? "unknown"} owner=${owners || "none"} dirty=${checkout.dirty ?? "unknown"}`,
+				)
+				for (const conflict of checkout.conflicts) {
+					log(`  conflict ${conflict.kind}: ${conflict.message}`)
+				}
+			}
+			return
+		}
+		if (subcommand === "prepare") {
+			const workspace = yield* worktrees.materialize(
+				taskId,
+				phaseId,
+				root,
+				options,
+			)
+			return log(
+				options.json
+					? JSON.stringify(workspace, null, 2)
+					: `${options.dryRun ? "Worktree plan" : "Worktrees ready"}: ${workspace.codePath}`,
+			)
+		}
+		if (subcommand === "remove") {
+			const inspection = yield* worktrees.inspect(taskId, phaseId, root)
+			const paths = yield* worktrees.remove(taskId, phaseId, root, options)
+			const result = {
+				operation: "remove",
+				dryRun: options.dryRun === true,
+				inspection,
+				actions: paths.map((path) => `remove ${path}`),
+			}
+			return log(
+				options.json
+					? JSON.stringify(result, null, 2)
+					: `${options.dryRun ? "Would remove" : "Removed"} ${paths.length} worktree${paths.length === 1 ? "" : "s"}`,
+			)
+		}
+		if (subcommand === "rebuild") {
+			const result = yield* worktrees.rebuild(taskId, phaseId, root, options)
+			return log(
+				options.json
+					? JSON.stringify(result, null, 2)
+					: `${options.dryRun ? "Would rebuild" : "Rebuilt"} ${result.inspection.codePath}`,
+			)
+		}
+		if (subcommand === "repair") {
+			const result = yield* worktrees.repair(taskId, phaseId, root, options)
+			return log(
+				options.json
+					? JSON.stringify(result, null, 2)
+					: `${options.dryRun ? "Would repair" : "Repaired"} ${result.inspection.codePath}`,
+			)
+		}
+
+		return yield* Effect.fail(
+			new Error(`Unknown worktree subcommand '${subcommand ?? ""}'`),
+		)
+	})
+
+export const help = `
+Usage: agency worktree <list|inspect|prepare|remove|rebuild|repair>
+
+Inspect and maintain Agency-managed writable and reference worktrees.
+
+Commands:
+  list                              List every managed checkout
+  inspect <task-id> [phase-id]      Show registration, branch, commit, ownership, and dirtiness
+  prepare <task-id> [phase-id]      Create or reuse declared worktrees
+  remove <task-id> [phase-id]       Remove clean worktrees while preserving branches
+  rebuild <task-id> [phase-id]      Remove and recreate clean, conflict-free worktrees
+  repair <task-id> [phase-id]       Repair safe registration issues or missing worktrees
+
+Options:
+  --task <id>          Select a task without positional IDs
+  --phase <id>         Select a phase with --task
+  --dry-run            Preflight and report changes without applying them
+  --json               Print structured output
+`

package/src/services/FileSystemService.ts

@@ -6,6 +6,7 @@ import {
 	readdir,
 	realpath,
 	rename,
+	rmdir,
 	stat,
 	symlink,
 } from "node:fs/promises"
@@ -175,6 +176,31 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 					),
 				),
 
+			deleteDirectoryIfEmpty: (path: string) =>
+				Effect.tryPromise({
+					try: async () => {
+						try {
+							await rmdir(path)
+							return true
+						} catch (error) {
+							if (
+								typeof error === "object" &&
+								error !== null &&
+								"code" in error &&
+								["ENOENT", "ENOTEMPTY", "EEXIST"].includes(String(error.code))
+							) {
+								return false
+							}
+							throw error
+						}
+					},
+					catch: (error) =>
+						new FileSystemError({
+							message: `Failed to delete empty directory: ${path}`,
+							cause: error,
+						}),
+				}),
+
 			runCommand: (
 				args: readonly string[],
 				options?: {

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)
+	})
 })

package/src/services/RepositoryService.ts

@@ -2,6 +2,7 @@ import { Schema, TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either } from "effect"
 import { join, resolve } from "node:path"
 import { FileSystemService } from "./FileSystemService"
+import { GraphService } from "./GraphService"
 import { WorkbaseService } from "./WorkbaseService"
 import { RepositoryAlias } from "../workbase/schemas"
 
@@ -18,6 +19,11 @@ interface RepositoryInfo {
 	readonly target: string | null
 }
 
+interface RepositoryVerification extends RepositoryInfo {
+	readonly valid: boolean
+	readonly issues: readonly string[]
+}
+
 const validateAlias = (alias: string) => {
 	const result = Schema.decodeUnknownEither(RepositoryAlias)(alias)
 	return Either.isLeft(result)
@@ -29,6 +35,65 @@ const validateAlias = (alias: string) => {
 		: Effect.succeed(result.right)
 }
 
+const find = (alias: string, startPath: string) =>
+	Effect.gen(function* () {
+		const service = yield* RepositoryService
+		const validAlias = yield* validateAlias(alias)
+		const repositories = yield* service.list(startPath)
+		const repository = repositories.find((item) => item.alias === validAlias)
+		if (!repository) {
+			return yield* new RepositoryError({
+				message: `Unknown repository alias '${validAlias}'`,
+			})
+		}
+		return repository
+	})
+
+const removalBlockers = (repository: RepositoryInfo, startPath: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const graph = yield* GraphService
+		const report = yield* graph.get({ cwd: startPath })
+		const repositoryId = `repository:${repository.alias}`
+		const references = report.edges
+			.filter(
+				(edge) =>
+					edge.to === repositoryId &&
+					(edge.kind === "writes" || edge.kind === "references"),
+			)
+			.map((edge) => edge.from)
+			.sort()
+		const worktrees: string[] = []
+		if (repository.kind !== "symlink") {
+			const result = yield* fs.runCommand(
+				["git", "-C", repository.path, "worktree", "list", "--porcelain"],
+				{ captureOutput: true },
+			)
+			if (result.exitCode === 0) {
+				for (const block of result.stdout.trim().split(/\n\n+/)) {
+					if (!block || /(^|\n)bare(\n|$)/.test(block)) continue
+					const path = block.match(/^worktree (.+)$/m)?.[1]
+					if (path) worktrees.push(path)
+				}
+			}
+		}
+		return { references, worktrees }
+	})
+
+const assertRemovable = (repository: RepositoryInfo, startPath: string) =>
+	Effect.gen(function* () {
+		const blockers = yield* removalBlockers(repository, startPath)
+		const details = [
+			...blockers.references.map((item) => `active reference ${item}`),
+			...blockers.worktrees.map((item) => `linked worktree ${item}`),
+		]
+		if (details.length > 0) {
+			return yield* new RepositoryError({
+				message: `Repository alias '${repository.alias}' is in use and cannot be removed or renamed:\n${details.map((item) => `- ${item}`).join("\n")}`,
+			})
+		}
+	})
+
 export class RepositoryService extends Effect.Service<RepositoryService>()(
 	"RepositoryService",
 	{
@@ -154,6 +219,122 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 
 					return repositories
 				}),
+
+			show: (alias: string, startPath: string = process.cwd()) =>
+				find(alias, startPath),
+
+			fetch: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const repository = yield* find(alias, startPath)
+					const result = yield* fs.runCommand(
+						["git", "-C", repository.path, "fetch", "--prune"],
+						{ captureOutput: true },
+					)
+					if (result.exitCode !== 0) {
+						return yield* new RepositoryError({
+							message: `Failed to fetch repository '${alias}': ${result.stderr.trim()}`,
+						})
+					}
+					return repository
+				}),
+
+			remove: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const repository = yield* find(alias, startPath)
+					yield* assertRemovable(repository, startPath)
+					yield* fs.deleteDirectory(repository.path)
+					return repository
+				}),
+
+			unlink: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const service = yield* RepositoryService
+					const repository = yield* find(alias, startPath)
+					if (repository.kind !== "symlink") {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' is not a link; use 'agency repo remove ${alias}'`,
+						})
+					}
+					return yield* service.remove(alias, startPath)
+				}),
+
+			rename: (
+				alias: string,
+				newAlias: string,
+				startPath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const repository = yield* find(alias, startPath)
+					const validNewAlias = yield* validateAlias(newAlias)
+					const root = yield* workbase.discover(startPath)
+					const destination = join(root, "repos", validNewAlias)
+					if (yield* fs.exists(destination)) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${validNewAlias}' already exists`,
+						})
+					}
+					yield* assertRemovable(repository, startPath)
+					yield* fs.moveDirectory(repository.path, destination)
+					return yield* find(validNewAlias, startPath)
+				}),
+
+			remote: (
+				alias: string,
+				remote: string | undefined,
+				startPath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const repository = yield* find(alias, startPath)
+					if (remote === undefined) return repository
+					if (!remote.trim()) {
+						return yield* new RepositoryError({
+							message: "Repository remote is required",
+						})
+					}
+					const hasOrigin = repository.remote !== null
+					const result = yield* fs.runCommand(
+						[
+							"git",
+							"-C",
+							repository.path,
+							"remote",
+							hasOrigin ? "set-url" : "add",
+							"origin",
+							remote,
+						],
+						{ captureOutput: true },
+					)
+					if (result.exitCode !== 0) {
+						return yield* new RepositoryError({
+							message: `Failed to update remote for repository '${alias}': ${result.stderr.trim()}`,
+						})
+					}
+					return yield* find(alias, startPath)
+				}),
+
+			verify: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const repository = yield* find(alias, startPath)
+					const issues: string[] = []
+					const git = yield* fs.runCommand(
+						["git", "-C", repository.path, "rev-parse", "--git-dir"],
+						{ captureOutput: true },
+					)
+					if (git.exitCode !== 0) issues.push("Path is not a Git repository")
+					if (repository.remote === null)
+						issues.push("Origin remote is not configured")
+					return {
+						...repository,
+						valid: issues.length === 0,
+						issues,
+					} satisfies RepositoryVerification
+				}),
 		}),
 	},
 ) {}

package/src/services/WorkbaseService.test.ts

@@ -111,6 +111,52 @@ describe("WorkbaseService", () => {
 		expect(result.defaultWorkbase).toEqual(registered)
 	})
 
+	test("shows, names, clears names, and defaults by path", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const configDirectory = join(root, "config")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+		const registered = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.register(workbaseRoot, configDirectory),
+				),
+			),
+		)
+
+		const result = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						const named = yield* service.nameRegistered(
+							workbaseRoot,
+							"primary",
+							configDirectory,
+						)
+						const shown = yield* service.showRegistered(
+							"primary",
+							configDirectory,
+						)
+						const defaultWorkbase = yield* service.setDefault(
+							workbaseRoot,
+							configDirectory,
+						)
+						const unnamed = yield* service.nameRegistered(
+							registered.id,
+							null,
+							configDirectory,
+						)
+						return { named, shown, defaultWorkbase, unnamed }
+					}),
+				),
+			),
+		)
+
+		expect(result.named.name).toBe("primary")
+		expect(result.shown).toEqual(result.named)
+		expect(result.defaultWorkbase?.id).toBe(registered.id)
+		expect(result.unnamed).toEqual({ id: registered.id, path: registered.path })
+	})
+
 	test("rejects names that collide with stable IDs", async () => {
 		const firstRoot = join(root, "first")
 		const secondRoot = join(root, "second")