@markjaquith/agency 2.17.0 → 2.18.0

package/src/commands/workbase.test.ts

@@ -31,7 +31,7 @@ describe("workbase command", () => {
 				}),
 			),
 		)
-		const path = JSON.parse(added[0]!).path
+		const registration = JSON.parse(added[0]!)
 
 		const listed = await captureLogs(() =>
 			runTestEffect(
@@ -44,7 +44,68 @@ describe("workbase command", () => {
 			),
 		)
 
-		expect(JSON.parse(listed[0]!)).toEqual([path])
+		expect(JSON.parse(listed[0]!)).toEqual({
+			workbases: [registration],
+		})
+	})
+
+	test("sets, clears, and removes the default workbase", async () => {
+		const added = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "add",
+					args: [root],
+					name: "primary",
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		const registration = JSON.parse(added[0]!)
+
+		await runTestEffect(
+			workbase({
+				subcommand: "default",
+				args: ["primary"],
+				configDirectory,
+				silent: true,
+			}),
+		)
+		const listed = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "list",
+					args: [],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		expect(JSON.parse(listed[0]!).defaultId).toBe(registration.id)
+		await runTestEffect(
+			workbase({
+				subcommand: "default",
+				args: [],
+				clear: true,
+				configDirectory,
+				silent: true,
+			}),
+		)
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
+		).toEqual({ version: 2, workbases: [registration] })
+
+		await runTestEffect(
+			workbase({
+				subcommand: "remove",
+				args: [registration.id],
+				configDirectory,
+				silent: true,
+			}),
+		)
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
+		).toEqual({ version: 2, workbases: [] })
 	})
 
 	test("requires an add path", async () => {

package/src/commands/workbase.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect"
+import { resolve } from "node:path"
 import type { BaseCommandOptions } from "../utils/command"
 import { WorkbaseService } from "../services/WorkbaseService"
 import { createLoggers } from "../utils/effect"
@@ -7,6 +8,8 @@ interface WorkbaseOptions extends BaseCommandOptions {
 	readonly subcommand?: string
 	readonly args: readonly string[]
 	readonly configDirectory?: string
+	readonly name?: string
+	readonly clear?: boolean
 }
 
 export const workbase = (options: WorkbaseOptions) =>
@@ -22,26 +25,85 @@ export const workbase = (options: WorkbaseOptions) =>
 						new Error("Usage: agency workbase add <path>"),
 					)
 				}
-				const root = yield* service.register(path, options.configDirectory)
+				const registration = yield* service.register(
+					resolve(options.cwd ?? process.cwd(), path),
+					options.configDirectory,
+					options.name,
+				)
 				log(
 					options.json
-						? JSON.stringify({ path: root }, null, 2)
-						: `Added workbase ${root}`,
+						? JSON.stringify(registration, null, 2)
+						: `Added workbase ${registration.name ?? registration.id} (${registration.path})`,
 				)
 				return
 			}
 			case "list": {
-				const workbases = yield* service.listRegistered(options.configDirectory)
+				const registrations = yield* service.listRegistrations(
+					options.configDirectory,
+				)
 				if (options.json) {
-					log(JSON.stringify(workbases, null, 2))
+					log(JSON.stringify(registrations, null, 2))
 				} else {
-					for (const path of workbases) log(path)
+					for (const entry of registrations.workbases) {
+						const marker = entry.id === registrations.defaultId ? "*" : " "
+						log(`${marker} ${entry.name ?? entry.id}\t${entry.path}`)
+					}
 				}
 				return
 			}
+			case "remove": {
+				const entry = yield* service.removeRegistered(
+					options.args[0]!,
+					options.configDirectory,
+					options.cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(entry, null, 2)
+						: `Removed workbase ${entry.name ?? entry.id}`,
+				)
+				return
+			}
+			case "prune": {
+				const removed = yield* service.pruneRegistered(options.configDirectory)
+				log(
+					options.json
+						? JSON.stringify(removed, null, 2)
+						: `Pruned ${removed.length} stale workbase${removed.length === 1 ? "" : "s"}`,
+				)
+				return
+			}
+			case "default": {
+				const selector = options.clear ? null : options.args[0]
+				if (selector === undefined) {
+					const entry = yield* service.getDefault(options.configDirectory)
+					log(
+						options.json
+							? JSON.stringify(entry ?? null, null, 2)
+							: entry
+								? `${entry.name ?? entry.id}\t${entry.path}`
+								: "No default workbase",
+					)
+					return
+				}
+				const entry = yield* service.setDefault(
+					selector,
+					options.configDirectory,
+				)
+				log(
+					options.json
+						? JSON.stringify(entry, null, 2)
+						: entry
+							? `Default workbase is ${entry.name ?? entry.id}`
+							: "Cleared default workbase",
+				)
+				return
+			}
 			default:
 				return yield* Effect.fail(
-					new Error("Subcommand is required. Available: add, list"),
+					new Error(
+						"Subcommand is required. Available: add, list, remove, prune, default",
+					),
 				)
 		}
 	})
@@ -50,9 +112,14 @@ export const help = `
 Usage: agency workbase <subcommand>
 
 Subcommands:
-  add <path>  Register an Agency workbase
-  list        List registered workbases
+  add <path>        Register an Agency workbase
+  list              List registered workbases
+  remove <selector> Remove a registered workbase
+  prune             Remove registrations whose paths no longer exist
+  default [selector] Show or set the default workbase
 
 Options:
-  --json      Output results as JSON
+  --name <name> Name a registered workbase
+  --clear       Clear the default workbase
+  --json        Output results as JSON
 `

package/src/services/WorkbaseService.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdir, realpath } from "node:fs/promises"
+import { mkdir, realpath, rm, symlink } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { WorkbaseService } from "./WorkbaseService"
@@ -66,11 +66,154 @@ describe("WorkbaseService", () => {
 			),
 		)
 
-		expect(first).toBe(await realpath(workbaseRoot))
-		expect(registered).toEqual([first])
+		expect(first.path).toBe(await realpath(workbaseRoot))
+		expect(registered).toEqual([first.path])
 		expect(
 			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
-		).toEqual({ version: 1, workbases: [first] })
+		).toEqual({ version: 2, workbases: [first] })
+	})
+
+	test("resolves names and stable IDs and manages the default", 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, "primary"),
+				),
+			),
+		)
+		const result = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						yield* service.setDefault("primary", configDirectory)
+						return {
+							byName: yield* service.resolveRegistered(
+								"primary",
+								configDirectory,
+							),
+							byId: yield* service.resolveRegistered(
+								registered.id,
+								configDirectory,
+							),
+							defaultWorkbase: yield* service.getDefault(configDirectory),
+						}
+					}),
+				),
+			),
+		)
+
+		expect(result.byName).toBe(registered.path)
+		expect(result.byId).toBe(registered.path)
+		expect(result.defaultWorkbase).toEqual(registered)
+	})
+
+	test("rejects names that collide with stable IDs", async () => {
+		const firstRoot = join(root, "first")
+		const secondRoot = join(root, "second")
+		const configDirectory = join(root, "config")
+		await write(firstRoot, "agency.json", '{"version":2}\n')
+		await write(secondRoot, "agency.json", '{"version":2}\n')
+		const first = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.register(firstRoot, configDirectory),
+				),
+			),
+		)
+
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) =>
+						service.register(secondRoot, configDirectory, first.id),
+					),
+				),
+			),
+		).rejects.toThrow("already registered")
+	})
+
+	test("rejects invalid workbase names before writing the registry", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const configDirectory = join(root, "config")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+
+		for (const name of ["bad/name", ""]) {
+			await expect(
+				runTestEffect(
+					WorkbaseService.pipe(
+						Effect.flatMap((service) =>
+							service.register(workbaseRoot, configDirectory, name),
+						),
+					),
+				),
+			).rejects.toThrow("Invalid workbase name")
+		}
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).exists(),
+		).toBe(false)
+	})
+
+	test("removes a registration by an equivalent symlink path", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const linkedRoot = join(root, "linked")
+		const configDirectory = join(root, "config")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+		await symlink(workbaseRoot, linkedRoot)
+		await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.register(workbaseRoot, configDirectory),
+				),
+			),
+		)
+
+		const removed = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.removeRegistered(linkedRoot, configDirectory),
+				),
+			),
+		)
+		expect(removed.path).toBe(await realpath(workbaseRoot))
+	})
+
+	test("migrates legacy registrations and prunes stale paths", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const staleRoot = join(root, "stale")
+		const configDirectory = join(root, "config")
+		const registryPath = join(configDirectory, "agency/workbases.json")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+		await write(staleRoot, "agency.json", '{"version":2}\n')
+		await write(
+			configDirectory,
+			"agency/workbases.json",
+			JSON.stringify({ version: 1, workbases: [workbaseRoot, staleRoot] }),
+		)
+		await rm(staleRoot, { recursive: true })
+
+		const result = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						const before = yield* service.listRegistrations(configDirectory)
+						const removed = yield* service.pruneRegistered(configDirectory)
+						return { before, removed }
+					}),
+				),
+			),
+		)
+
+		expect(result.before.workbases).toHaveLength(2)
+		expect(result.before.workbases[0]?.id).toStartWith("wb-")
+		expect(result.removed.map((entry) => entry.path)).toEqual([staleRoot])
+		expect(await Bun.file(registryPath).json()).toEqual({
+			version: 2,
+			workbases: [result.before.workbases[0]],
+		})
 	})
 
 	test("rejects an invalid worktree command template", async () => {

package/src/services/WorkbaseService.ts

@@ -6,7 +6,9 @@ import { dirname, join, relative, resolve } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { parseFrontmatter } from "../workbase/frontmatter"
 import {
+	EntityId,
 	EpicFrontmatter,
+	LegacyWorkbaseRegistry,
 	PhaseFrontmatter,
 	TaskFrontmatter,
 	WorkbaseConfig,
@@ -15,6 +17,8 @@ import {
 	type EpicFrontmatter as EpicData,
 	type PhaseFrontmatter as PhaseData,
 	type TaskFrontmatter as TaskData,
+	type WorkbaseRegistry as WorkbaseRegistryData,
+	type WorkbaseRegistration,
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
 
@@ -81,12 +85,17 @@ const registryPath = (configDirectory?: string) =>
 		"workbases.json",
 	)
 
+const registrationId = (path: string) =>
+	`wb-${new Bun.CryptoHasher("sha256").update(path).digest("hex").slice(0, 12)}`
+
+const emptyRegistry: WorkbaseRegistryData = { version: 2, workbases: [] }
+
 const readRegistry = (configDirectory?: string) =>
 	Effect.gen(function* () {
 		const fs = yield* FileSystemService
 		const path = registryPath(configDirectory)
 		if (!(yield* fs.exists(path))) {
-			return { path, registry: { version: 1, workbases: [] } as const }
+			return { path, registry: emptyRegistry }
 		}
 
 		const content = yield* fs.readFile(path)
@@ -102,13 +111,37 @@ const readRegistry = (configDirectory?: string) =>
 		}
 
 		const decoded = decode(WorkbaseRegistry, input)
-		if (!decoded.success) {
+		if (decoded.success) return { path, registry: decoded.value }
+
+		const legacy = decode(LegacyWorkbaseRegistry, input)
+		if (!legacy.success) {
 			return yield* new WorkbaseRegistryError({
 				path,
 				message: `Invalid workbase registry in ${path}:\n${decoded.error}`,
 			})
 		}
-		return { path, registry: decoded.value }
+		const registry: WorkbaseRegistryData = {
+			version: 2 as const,
+			workbases: legacy.value.workbases.map((workbasePath) => ({
+				id: registrationId(workbasePath),
+				path: workbasePath,
+			})),
+		}
+		return { path, registry }
+	})
+
+const writeRegistry = (
+	path: string,
+	registry: {
+		readonly version: 2
+		readonly workbases: readonly WorkbaseRegistration[]
+		readonly defaultId?: string
+	},
+) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		yield* fs.createDirectory(dirname(path))
+		yield* fs.writeJSON(path, registry)
 	})
 
 const findCycles = (nodes: readonly Dependency[]): readonly string[] => {
@@ -285,26 +318,195 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					return { root, config: decoded.value }
 				}),
 
-			register: (startPath: string, configDirectory?: string) =>
+			register: (startPath: string, configDirectory?: string, name?: string) =>
 				Effect.gen(function* () {
 					const service = yield* WorkbaseService
 					const fs = yield* FileSystemService
 					const discovered = yield* service.discover(startPath)
 					const root = yield* fs.realPath(discovered)
 					const { path, registry } = yield* readRegistry(configDirectory)
-					if (registry.workbases.includes(root)) return root
+					if (name !== undefined) {
+						const decodedName = decode(EntityId, name)
+						if (!decodedName.success) {
+							return yield* new WorkbaseRegistryError({
+								path,
+								message: `Invalid workbase name '${name}': names must contain only letters, numbers, dots, underscores, and hyphens`,
+							})
+						}
+					}
+					const named = name
+						? registry.workbases.find(
+								(entry) =>
+									(entry.name === name && entry.path !== root) ||
+									entry.id === name,
+							)
+						: undefined
+					if (named) {
+						return yield* new WorkbaseRegistryError({
+							path,
+							message: `Workbase name '${name}' is already registered for ${named.path}`,
+						})
+					}
+					const existing = registry.workbases.find(
+						(entry) => entry.path === root,
+					)
+					const registration = {
+						id: existing?.id ?? registrationId(root),
+						...(name
+							? { name }
+							: existing?.name
+								? { name: existing.name }
+								: {}),
+						path: root,
+					}
+					const idNameCollision = registry.workbases.find(
+						(entry) => entry.name === registration.id && entry.path !== root,
+					)
+					if (idNameCollision) {
+						return yield* new WorkbaseRegistryError({
+							path,
+							message: `Workbase ID '${registration.id}' conflicts with the registered name for ${idNameCollision.path}`,
+						})
+					}
+					const workbases = existing
+						? registry.workbases.map((entry) =>
+								entry.id === existing.id ? registration : entry,
+							)
+						: [...registry.workbases, registration]
+					yield* writeRegistry(path, { ...registry, workbases })
+					return registration
+				}),
+
+			listRegistered: (configDirectory?: string) =>
+				readRegistry(configDirectory).pipe(
+					Effect.map(({ registry }) =>
+						registry.workbases.map((entry) => entry.path),
+					),
+				),
+
+			listRegistrations: (configDirectory?: string) =>
+				readRegistry(configDirectory).pipe(
+					Effect.map(({ registry }) => ({
+						workbases: registry.workbases,
+						defaultId: registry.defaultId,
+					})),
+				),
+
+			resolveRegistered: (
+				selector: string,
+				configDirectory?: string,
+				basePath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const service = yield* WorkbaseService
+					const fs = yield* FileSystemService
+					const { path, registry } = yield* readRegistry(configDirectory)
+					const candidatePath = resolve(basePath, selector)
+					const direct =
+						registry.workbases.find((entry) => entry.id === selector) ??
+						registry.workbases.find((entry) => entry.name === selector) ??
+						registry.workbases.find((entry) => entry.path === candidatePath)
+					if (direct) return direct.path
+					if (yield* fs.exists(candidatePath))
+						return yield* service.discover(candidatePath)
+					return yield* new WorkbaseRegistryError({
+						path,
+						message: `Unknown workbase selector '${selector}'`,
+					})
+				}),
+
+			removeRegistered: (
+				selector: string,
+				configDirectory?: string,
+				basePath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const { path, registry } = yield* readRegistry(configDirectory)
+					const candidatePath = resolve(basePath, selector)
+					const canonicalCandidate = (yield* fs.exists(candidatePath))
+						? yield* fs.realPath(candidatePath)
+						: candidatePath
+					const entry =
+						registry.workbases.find((item) => item.id === selector) ??
+						registry.workbases.find((item) => item.name === selector) ??
+						registry.workbases.find((item) => item.path === canonicalCandidate)
+					if (!entry) {
+						return yield* new WorkbaseRegistryError({
+							path,
+							message: `Unknown workbase selector '${selector}'`,
+						})
+					}
+					const workbases = registry.workbases.filter(
+						(item) => item.id !== entry.id,
+					)
+					const next = {
+						version: 2 as const,
+						workbases,
+						...(registry.defaultId && registry.defaultId !== entry.id
+							? { defaultId: registry.defaultId }
+							: {}),
+					}
+					yield* writeRegistry(path, next)
+					return entry
+				}),
 
-					yield* fs.createDirectory(dirname(path))
-					yield* fs.writeJSON(path, {
-						version: 1,
-						workbases: [...registry.workbases, root],
+			pruneRegistered: (configDirectory?: string) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const { path, registry } = yield* readRegistry(configDirectory)
+					const kept: WorkbaseRegistration[] = []
+					const removed: WorkbaseRegistration[] = []
+					for (const entry of registry.workbases) {
+						if (yield* fs.exists(join(entry.path, "agency.json")))
+							kept.push(entry)
+						else removed.push(entry)
+					}
+					const defaultId = kept.some(
+						(entry) => entry.id === registry.defaultId,
+					)
+						? registry.defaultId
+						: undefined
+					yield* writeRegistry(path, {
+						version: 2,
+						workbases: kept,
+						...(defaultId ? { defaultId } : {}),
 					})
-					return root
+					return removed
 				}),
 
-			listRegistered: (configDirectory?: string) =>
+			setDefault: (selector: string | null, configDirectory?: string) =>
+				Effect.gen(function* () {
+					const { path, registry } = yield* readRegistry(configDirectory)
+					if (selector === null) {
+						yield* writeRegistry(path, {
+							version: 2,
+							workbases: registry.workbases,
+						})
+						return null
+					}
+					const entry = registry.workbases.find(
+						(item) => item.id === selector || item.name === selector,
+					)
+					if (!entry) {
+						return yield* new WorkbaseRegistryError({
+							path,
+							message: `Unknown registered workbase selector '${selector}'`,
+						})
+					}
+					yield* writeRegistry(path, {
+						version: 2,
+						workbases: registry.workbases,
+						defaultId: entry.id,
+					})
+					return entry
+				}),
+
+			getDefault: (configDirectory?: string) =>
 				readRegistry(configDirectory).pipe(
-					Effect.map(({ registry }) => registry.workbases),
+					Effect.map(({ registry }) =>
+						registry.workbases.find((entry) => entry.id === registry.defaultId),
+					),
 				),
 
 			validate: (startPath: string = process.cwd()) =>

package/src/workbase/schemas.test.ts

@@ -185,23 +185,34 @@ describe("workbase registry", () => {
 	test("accepts registered paths", () => {
 		expect(
 			Schema.decodeUnknownSync(WorkbaseRegistry)({
-				version: 1,
-				workbases: ["/work/one", "/work/two"],
+				version: 2,
+				workbases: [
+					{ id: "wb-one", name: "one", path: "/work/one" },
+					{ id: "wb-two", path: "/work/two" },
+				],
+				defaultId: "wb-one",
 			}),
-		).toEqual({ version: 1, workbases: ["/work/one", "/work/two"] })
+		).toEqual({
+			version: 2,
+			workbases: [
+				{ id: "wb-one", name: "one", path: "/work/one" },
+				{ id: "wb-two", path: "/work/two" },
+			],
+			defaultId: "wb-one",
+		})
 	})
 
 	test("rejects invalid versions and empty paths", () => {
 		expect(() =>
 			Schema.decodeUnknownSync(WorkbaseRegistry)({
-				version: 2,
+				version: 3,
 				workbases: [],
 			}),
 		).toThrow()
 		expect(() =>
 			Schema.decodeUnknownSync(WorkbaseRegistry)({
-				version: 1,
-				workbases: [""],
+				version: 2,
+				workbases: [{ id: "wb-one", path: "" }],
 			}),
 		).toThrow()
 	})