@markjaquith/agency 2.24.0 → 2.26.0

package/README.md

@@ -379,14 +379,24 @@ conditions remain visible in `warnings` or `unresolved` with a suggested action.
 agency init [path] [--json]
 agency workbase add <path> [--name <name>] [--json]
 agency workbase list [--json]
+agency workbase show <id|name|path> [--json]
+agency workbase name <id|name|path> <name> [--json]
+agency workbase name <id|name|path> --clear [--json]
 agency workbase remove <id|name|path> [--json]
 agency workbase prune [--json]
-agency workbase default [<id|name> | --clear] [--json]
+agency workbase default [<id|name|path> | --clear] [--json]
 agency integration status [--json]
 agency integration sync [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
 agency repo list [--json]
+agency repo show <alias> [--json]
+agency repo fetch <alias> [--json]
+agency repo remove <alias> [--json]
+agency repo unlink <alias> [--json]
+agency repo rename <alias> <new-alias> [--json]
+agency repo remote <alias> [remote] [--json]
+agency repo verify <alias> [--json]
 ```
 
 Registered workbases are stored in
@@ -395,7 +405,9 @@ Each registration has a stable ID and may have a unique name. A default workbase
 is used when the current directory is outside every workbase. `prune` removes
 registrations whose workbase configuration no longer exists.
 `repo add` creates a bare clone. `repo link` creates a symlink to an existing Git
-repository. Alias names are then used by all documents and commands.
+repository. Alias names are then used by all documents and commands. Remove,
+unlink, and rename refuse aliases referenced by active work or backed by linked
+worktrees, and report each blocker.
 
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,

package/cli.ts

@@ -683,6 +683,7 @@ try {
 	}
 	if (error instanceof Error) {
 		let message = error.message
+		let details: any = error
 
 		// Handle Effect FiberFailure errors that wrap tagged errors
 		// When the message is generic "An error has occurred", try to extract the actual error
@@ -695,6 +696,7 @@ try {
 				const cause = (error as any)[causeSymbol]
 				if (cause && cause._tag === "Fail" && cause.failure) {
 					const failure = cause.failure
+					details = failure
 					// Try common error message patterns
 					message =
 						failure.message ||
@@ -705,6 +707,14 @@ try {
 				}
 			}
 		}
+		for (const [field, label] of [
+			["completed", "Completed"],
+			["rolledBack", "Rolled back"],
+			["manualRecovery", "Manual recovery"],
+		] as const) {
+			if (Array.isArray(details[field]) && details[field].length > 0)
+				message += `\n${label}: ${details[field].join("; ")}`
+		}
 
 		console.error(`ⓘ ${message}`)
 	} else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.24.0",
+  "version": "2.26.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/skills/agency/SKILL.md

@@ -65,7 +65,9 @@ Register and name known workbases so commands can select one from anywhere:
 ```bash
 agency workbase add <path> [--name <name>]
 agency workbase list
-agency workbase default [<id|name> | --clear]
+agency workbase show <id|name|path>
+agency workbase name <id|name|path> <name> | --clear
+agency workbase default [<id|name|path> | --clear]
 agency workbase remove <id|name|path>
 agency workbase prune
 ```
@@ -85,6 +87,13 @@ Link an existing local Git repository:
 
 ```bash
 agency repo link <alias> <path>
+agency repo show <alias>
+agency repo fetch <alias>
+agency repo remove <alias>
+agency repo unlink <alias>
+agency repo rename <alias> <new-alias>
+agency repo remote <alias> [remote]
+agency repo verify <alias>
 ```
 
 Use aliases, never absolute paths or Git URLs, in epic/task/phase frontmatter.

package/src/cli-parser.test.ts

@@ -121,6 +121,23 @@ describe("strict CLI parsing", () => {
 		expect(parseCli(["status", "--no-pr"]).values["no-pr"]).toBe(true)
 	})
 
+	test("parses addressable resource maintenance commands", () => {
+		for (const args of [
+			["repo", "show", "agency", "--json"],
+			["repo", "fetch", "agency"],
+			["repo", "remove", "agency"],
+			["repo", "unlink", "agency"],
+			["repo", "rename", "agency", "renamed"],
+			["repo", "remote", "agency", "https://example.com/repo.git"],
+			["repo", "verify", "agency"],
+			["workbase", "show", "primary", "--json"],
+			["workbase", "name", "primary", "renamed"],
+			["workbase", "name", "primary", "--clear"],
+		]) {
+			expect(() => parseCli(args)).not.toThrow()
+		}
+	})
+
 	test("validates view filter values and conflicts", () => {
 		expect(() => parseCli(["epic", "list", "--status", "invalid"])).toThrow(
 			"Invalid '--status' value",
@@ -292,6 +309,15 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
+	test("accepts archive dry-run", () => {
+		expect(parseCli(["archive", "task", "example", "--dry-run"])).toMatchObject(
+			{
+				commandName: "archive",
+				values: { "dry-run": true },
+			},
+		)
+	})
+
 	test("validates revision-guarded claim operations", () => {
 		const revision = "0".repeat(64)
 		expect(

package/src/cli-parser.ts

@@ -127,7 +127,7 @@ const commands = {
 		},
 	},
 	workbase: {
-		usage: "agency workbase <add|list|remove|prune|default>",
+		usage: "agency workbase <add|list|show|name|remove|prune|default>",
 		options: {
 			...outputOptions,
 			name: { type: "string" },
@@ -146,6 +146,18 @@ const commands = {
 				maxArgs: 0,
 				options: ["json"],
 			},
+			show: {
+				usage: "agency workbase show <selector> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			name: {
+				usage: "agency workbase name <selector> <name> | --clear [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["json", "clear"],
+			},
 			remove: {
 				usage: "agency workbase remove <selector> [--json]",
 				minArgs: 1,
@@ -186,7 +198,8 @@ const commands = {
 		},
 	},
 	repo: {
-		usage: "agency repo <add|link|list>",
+		usage:
+			"agency repo <add|link|list|show|fetch|remove|unlink|rename|remote|verify>",
 		options: outputOptions,
 		subcommands: {
 			add: {
@@ -207,6 +220,48 @@ const commands = {
 				maxArgs: 0,
 				options: ["json"],
 			},
+			show: {
+				usage: "agency repo show <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			fetch: {
+				usage: "agency repo fetch <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			remove: {
+				usage: "agency repo remove <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			unlink: {
+				usage: "agency repo unlink <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			rename: {
+				usage: "agency repo rename <alias> <new-alias> [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: ["json"],
+			},
+			remote: {
+				usage: "agency repo remote <alias> [remote] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["json"],
+			},
+			verify: {
+				usage: "agency repo verify <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
 		},
 	},
 	epic: {

package/src/commands/archive.test.ts

@@ -63,6 +63,28 @@ describe("archive command", () => {
 		})
 	})
 
+	test("preflights an archive without moving the task", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				archive({
+					type: "task",
+					args: ["example"],
+					cwd: root,
+					dryRun: true,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!).dryRun).toBe(true)
+		expect(await Bun.file(join(root, "tasks/example/TASK.md")).exists()).toBe(
+			true,
+		)
+		expect(await Bun.file(join(root, "archive/tasks/example")).exists()).toBe(
+			false,
+		)
+	})
+
 	test("requires a supported work item type", async () => {
 		await expect(
 			runTestEffect(archive({ args: [], cwd: root, silent: true })),

package/src/commands/archive.ts

@@ -112,7 +112,9 @@ export const archive = (options: ArchiveOptions) =>
 		log(
 			options.json
 				? JSON.stringify(result, null, 2)
-				: `${result.dryRun ? "Would archive" : "Archived"} ${result.kind} '${result.id}' to ${result.path}`,
+				: result.dryRun
+					? `Would archive ${result.kind} '${result.id}' to ${result.path}`
+					: `Archived ${result.kind} '${result.id}' to ${result.path}`,
 		)
 	})
 

package/src/commands/repo.test.ts

@@ -52,6 +52,21 @@ describe("repo command", () => {
 		])
 	})
 
+	test("shows a repository by alias as JSON", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				repo({
+					subcommand: "show",
+					args: ["agency"],
+					cwd: root,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!).alias).toBe("agency")
+	})
+
 	test("outputs a linked repository as JSON", async () => {
 		const target = join(root, "source")
 		await mkdir(target)
@@ -77,4 +92,33 @@ describe("repo command", () => {
 			path: join(root, "repos/linked"),
 		})
 	})
+
+	test("unlinks a linked repository by alias", async () => {
+		const target = join(root, "unlink-source")
+		await mkdir(target)
+		const git = Bun.spawn(["git", "init", target], {
+			stdout: "ignore",
+			stderr: "ignore",
+		})
+		expect(await git.exited).toBe(0)
+		await runTestEffect(
+			repo({
+				subcommand: "link",
+				args: ["linked", target],
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+		await runTestEffect(
+			repo({
+				subcommand: "unlink",
+				args: ["linked"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+		expect(await Bun.file(join(target, ".git/HEAD")).exists()).toBe(true)
+	})
 })

package/src/commands/repo.ts

@@ -9,6 +9,9 @@ interface RepoOptions extends BaseCommandOptions {
 	readonly json?: boolean
 }
 
+const requireArg = (args: readonly string[], index: number, usage: string) =>
+	args[index] ? Effect.succeed(args[index]) : Effect.fail(new Error(usage))
+
 export const repo = (options: RepoOptions) =>
 	Effect.gen(function* () {
 		const repositories = yield* RepositoryService
@@ -61,10 +64,106 @@ export const repo = (options: RepoOptions) =>
 				return
 			}
 
+			case "show": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo show <alias>",
+				)
+				const item = yield* repositories.show(alias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `${item.alias}\t${item.kind}\t${item.target ?? item.remote ?? item.path}`,
+				)
+				return
+			}
+
+			case "fetch": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo fetch <alias>",
+				)
+				const item = yield* repositories.fetch(alias, cwd)
+				log(options.json ? JSON.stringify(item, null, 2) : `Fetched '${alias}'`)
+				return
+			}
+
+			case "remove":
+			case "unlink": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					`Usage: agency repo ${options.subcommand} <alias>`,
+				)
+				const item = yield* repositories[options.subcommand](alias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `${options.subcommand === "unlink" ? "Unlinked" : "Removed"} '${alias}'`,
+				)
+				return
+			}
+
+			case "rename": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo rename <alias> <new-alias>",
+				)
+				const newAlias = yield* requireArg(
+					options.args,
+					1,
+					"Usage: agency repo rename <alias> <new-alias>",
+				)
+				const item = yield* repositories.rename(alias, newAlias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `Renamed '${alias}' to '${newAlias}'`,
+				)
+				return
+			}
+
+			case "remote": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo remote <alias> [remote]",
+				)
+				const item = yield* repositories.remote(alias, options.args[1], cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: (item.remote ?? "No origin remote configured"),
+				)
+				return
+			}
+
+			case "verify": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo verify <alias>",
+				)
+				const report = yield* repositories.verify(alias, cwd)
+				if (options.json) log(JSON.stringify(report, null, 2))
+				if (!report.valid) {
+					return yield* Effect.fail(
+						new Error(
+							`Repository '${alias}' verification failed:\n${report.issues.map((issue) => `- ${issue}`).join("\n")}`,
+						),
+					)
+				}
+				if (!options.json) log(`Verified repository '${alias}'`)
+				return
+			}
+
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available subcommands: add, link, list",
+						"Subcommand is required. Available subcommands: add, link, list, show, fetch, remove, unlink, rename, remote, verify",
 					),
 				)
 		}
@@ -77,6 +176,13 @@ Subcommands:
   add <alias> <remote>  Create a bare clone
   link <alias> <path>   Link an existing Git repository
   list                  List repository aliases
+  show <alias>          Show a repository alias
+  fetch <alias>         Fetch and prune a repository
+  remove <alias>        Remove an unused repository alias
+  unlink <alias>        Remove an unused linked alias
+  rename <old> <new>    Rename an unused repository alias
+  remote <alias> [url]  Show or update the origin remote
+  verify <alias>        Verify repository operation
 
 Options:
   --json                Output repository aliases as JSON

package/src/commands/workbase.test.ts

@@ -108,6 +108,53 @@ describe("workbase command", () => {
 		).toEqual({ version: 2, workbases: [] })
 	})
 
+	test("names, shows, and clears a workbase name", async () => {
+		const added = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "add",
+					args: [root],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		const registration = JSON.parse(added[0]!)
+		await runTestEffect(
+			workbase({
+				subcommand: "name",
+				args: [registration.id, "primary"],
+				configDirectory,
+				silent: true,
+			}),
+		)
+
+		const shown = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "show",
+					args: ["primary"],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		expect(JSON.parse(shown[0]!).name).toBe("primary")
+
+		await runTestEffect(
+			workbase({
+				subcommand: "name",
+				args: [registration.id],
+				clear: true,
+				configDirectory,
+				silent: true,
+			}),
+		)
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
+		).toEqual({ version: 2, workbases: [registration] })
+	})
+
 	test("requires an add path", async () => {
 		await expect(
 			runTestEffect(

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/services/ArchiveService.test.ts

@@ -850,4 +850,63 @@ describe("ArchiveService", () => {
 			),
 		).rejects.toThrow("is archived; restore it")
 	})
+
+	test("preflights every phase worktree before removing any of them", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "multi-dirty",
+							ticketUrl: "https://example.com/task",
+							multiPhase: true,
+						},
+						root,
+					),
+				),
+			),
+		)
+		for (const id of ["clean", "dirty"]) {
+			await runTestEffect(
+				PhaseService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{
+								taskId: "multi-dirty",
+								id,
+								repo: "agency",
+								branch: `task/${id}`,
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			)
+			await runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("multi-dirty", id, root),
+					),
+				),
+			)
+		}
+		await Bun.write(
+			join(root, "tasks/multi-dirty/phases/dirty/code/agency/dirty.txt"),
+			"keep me\n",
+		)
+
+		await expect(
+			runTestEffect(
+				ArchiveService.pipe(
+					Effect.flatMap((service) => service.archiveTask("multi-dirty", root)),
+				),
+			),
+		).rejects.toThrow("uncommitted changes")
+		expect(
+			await Bun.file(
+				join(root, "tasks/multi-dirty/phases/clean/code/agency/README.md"),
+			).exists(),
+		).toBe(true)
+	})
 })