@markjaquith/agency 2.28.1 → 2.30.0

package/src/cli-parser.ts

@@ -127,13 +127,19 @@ const commands = {
 		},
 	},
 	workbase: {
-		usage: "agency workbase <add|list|show|name|remove|prune|default>",
+		usage: "agency workbase <init|add|list|show|name|remove|prune|default>",
 		options: {
 			...outputOptions,
 			name: { type: "string" },
 			clear: { type: "boolean" },
 		},
 		subcommands: {
+			init: {
+				usage: "agency workbase init [path] [--json]",
+				minArgs: 0,
+				maxArgs: 1,
+				options: ["json"],
+			},
 			add: {
 				usage: "agency workbase add <path> [--json]",
 				minArgs: 1,
@@ -199,9 +205,20 @@ const commands = {
 	},
 	repo: {
 		usage:
-			"agency repo <add|link|list|show|fetch|remove|unlink|rename|remote|verify>",
-		options: outputOptions,
+			"agency repo <setup|add|link|list|show|fetch|remove|unlink|rename|remote|verify>",
+		options: {
+			...outputOptions,
+			"dry-run": { type: "boolean" },
+			apply: { type: "boolean" },
+		},
 		subcommands: {
+			setup: {
+				usage: "agency repo setup [--dry-run | --apply] [--json]",
+				minArgs: 0,
+				maxArgs: 0,
+				options: ["dry-run", "apply", "json"],
+				conflicts: [["dry-run", "apply"]],
+			},
 			add: {
 				usage: "agency repo add <alias> <remote> [--json]",
 				minArgs: 2,

package/src/cli.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, test } from "bun:test"
+import { afterAll, afterEach, describe, expect, test } from "bun:test"
 import { access, mkdir, realpath } from "node:fs/promises"
 import { join } from "node:path"
 import errorFixture from "../fixtures/protocol/error.json"
@@ -7,6 +7,9 @@ import { cleanupTempDir, createTempDir } from "./test-utils"
 
 const projectRoot = join(import.meta.dir, "..")
 const cliPath = join(projectRoot, "cli.ts")
+const isolatedConfigHome = await createTempDir()
+
+afterAll(() => cleanupTempDir(isolatedConfigHome))
 
 interface CliResult {
 	exitCode: number
@@ -21,7 +24,11 @@ async function runCli(
 ): Promise<CliResult> {
 	const subprocess = Bun.spawn([process.execPath, cliPath, ...args], {
 		cwd,
-		env: env ? { ...process.env, ...env } : undefined,
+		env: {
+			...process.env,
+			XDG_CONFIG_HOME: isolatedConfigHome,
+			...env,
+		},
 		stdout: "pipe",
 		stderr: "pipe",
 	})
@@ -34,13 +41,55 @@ async function runCli(
 }
 
 function parseJson(result: CliResult) {
-	expect(result.exitCode).toBe(0)
+	expect(result.exitCode, JSON.stringify(result)).toBe(0)
 	expect(result.stderr).toBe("")
 	const envelope = JSON.parse(result.stdout)
 	expect(envelope).toMatchObject({ version: 1, ok: true })
 	return envelope.result
 }
 
+async function runGit(args: string[]) {
+	const subprocess = Bun.spawn(["git", ...args], {
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	const [exitCode, stdout, stderr] = await Promise.all([
+		subprocess.exited,
+		new Response(subprocess.stdout).text(),
+		new Response(subprocess.stderr).text(),
+	])
+	if (exitCode !== 0) throw new Error(stderr)
+	return stdout
+}
+
+async function startGitDaemon(basePath: string) {
+	const port = 20000 + Math.floor(Math.random() * 20000)
+	const process = Bun.spawn(
+		[
+			"git",
+			"daemon",
+			"--reuseaddr",
+			"--export-all",
+			`--base-path=${basePath}`,
+			"--listen=127.0.0.1",
+			`--port=${port}`,
+			basePath,
+		],
+		{ stdout: "pipe", stderr: "pipe" },
+	)
+	const remote = `git://127.0.0.1:${port}/source.git`
+	for (let attempt = 0; attempt < 40; attempt++) {
+		const probe = Bun.spawn(["git", "ls-remote", remote], {
+			stdout: "ignore",
+			stderr: "ignore",
+		})
+		if ((await probe.exited) === 0) return { process, remote }
+		await Bun.sleep(25)
+	}
+	process.kill()
+	throw new Error("Git daemon did not start")
+}
+
 describe("CLI", () => {
 	const tempDirs: string[] = []
 
@@ -550,6 +599,22 @@ describe("CLI", () => {
 			kind: "task",
 			taskId: "explicit",
 		})
+		const nextByCwd = parseJson(
+			await runCli(
+				["next", "--cwd", root, "--select", "--json"],
+				projectRoot,
+				env,
+			),
+		)
+		expect(nextByCwd.selected.key).toBe("task/explicit")
+		const nextByRegistration = parseJson(
+			await runCli(
+				["next", "--workbase", "primary", "--select", "--json"],
+				projectRoot,
+				env,
+			),
+		)
+		expect(nextByRegistration.selected.key).toBe("task/explicit")
 
 		parseJson(
 			await runCli(["workbase", "default", "primary", "--json"], parent, env),
@@ -662,11 +727,23 @@ status: open
 			["config", "user.name", "Test"],
 			["add", "README.md"],
 			["-c", "commit.gpgsign=false", "commit", "-m", "initial"],
+			["remote", "add", "origin", source],
 		]) {
 			expect(Bun.spawnSync(["git", "-C", source, ...args]).exitCode).toBe(0)
 		}
 
 		parseJson(await runCli(["init", root, "--json"], parent))
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency-tests/source.git",
+					},
+				},
+			}),
+		)
 		parseJson(await runCli(["repo", "link", "agency", source, "--json"], root))
 		parseJson(
 			await runCli(
@@ -789,6 +866,14 @@ status: open
 			stderr: "pipe",
 		})
 		expect(await git.exited).toBe(0)
+		await runGit([
+			"-C",
+			source,
+			"remote",
+			"add",
+			"origin",
+			"https://example.com/agency-tests/source.git",
+		])
 
 		expect(parseJson(await runCli(["init", root, "--json"]))).toEqual({
 			root,
@@ -981,4 +1066,121 @@ status: open
 			valid: true,
 		})
 	}, 30_000)
+
+	test("restores portable repositories in a fresh workbase clone", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const sourceWorktree = join(parent, "source-worktree")
+		const source = join(parent, "source.git")
+		const root = join(parent, "workbase")
+		const restored = join(parent, "restored")
+
+		await runGit(["init", "--initial-branch=main", sourceWorktree])
+		await Bun.write(join(sourceWorktree, "README.md"), "portable\n")
+		await runGit([
+			"-C",
+			sourceWorktree,
+			"config",
+			"user.email",
+			"test@example.com",
+		])
+		await runGit(["-C", sourceWorktree, "config", "user.name", "Test"])
+		await runGit(["-C", sourceWorktree, "add", "README.md"])
+		await runGit([
+			"-C",
+			sourceWorktree,
+			"-c",
+			"commit.gpgsign=false",
+			"commit",
+			"-m",
+			"initial",
+		])
+		await runGit(["clone", "--bare", sourceWorktree, source])
+		const daemon = await startGitDaemon(parent)
+
+		try {
+			parseJson(await runCli(["init", root, "--json"], parent))
+			parseJson(
+				await runCli(["repo", "add", "agency", daemon.remote, "--json"], root),
+			)
+			parseJson(
+				await runCli(
+					[
+						"task",
+						"create",
+						"portable",
+						"--repo",
+						"agency",
+						"--branch",
+						"feat/portable",
+						"--base",
+						"main",
+						"--json",
+					],
+					root,
+				),
+			)
+
+			await runGit(["init", "--initial-branch=main", root])
+			await runGit(["-C", root, "config", "user.email", "test@example.com"])
+			await runGit(["-C", root, "config", "user.name", "Test"])
+			await runGit(["-C", root, "add", "."])
+			await runGit([
+				"-C",
+				root,
+				"-c",
+				"commit.gpgsign=false",
+				"commit",
+				"-m",
+				"portable workbase",
+			])
+			const tracked = await runGit(["-C", root, "ls-files"])
+			expect(tracked).toContain("agency.json")
+			expect(tracked).not.toContain("repos/agency")
+
+			await runGit(["clone", root, restored])
+			const planned = parseJson(
+				await runCli(["repo", "setup", "--dry-run", "--json"], restored),
+			)
+			expect(planned.actions).toEqual([
+				expect.objectContaining({
+					alias: "agency",
+					kind: "materialize",
+					status: "planned",
+				}),
+			])
+			expect(await Bun.file(join(restored, "repos/agency/HEAD")).exists()).toBe(
+				false,
+			)
+
+			const applied = parseJson(
+				await runCli(["repo", "setup", "--apply", "--json"], restored),
+			)
+			expect(applied.actions[0]).toMatchObject({
+				alias: "agency",
+				status: "applied",
+			})
+			expect(await Bun.file(join(restored, "repos/agency/HEAD")).exists()).toBe(
+				true,
+			)
+
+			const prepared = parseJson(
+				await runCli(["work", "prepare", "portable", "--json"], restored),
+			)
+			expect(prepared.checkouts).toEqual([
+				expect.objectContaining({
+					repo: "agency",
+					action: "created",
+				}),
+			])
+			expect(
+				await Bun.file(
+					join(restored, "tasks/portable/code/agency/README.md"),
+				).text(),
+			).toBe("portable\n")
+		} finally {
+			daemon.process.kill()
+			await daemon.process.exited
+		}
+	}, 30_000)
 })

package/src/commands/pr.test.ts

@@ -7,20 +7,39 @@ import { pr } from "./pr"
 describe("pr command", () => {
 	test("outputs the created pull request URL as JSON", async () => {
 		const url = "https://github.com/markjaquith/agency/pull/123"
+		let received: unknown[] = []
 		const logs = await captureLogs(() =>
 			Effect.runPromise(
 				pr({
 					subcommand: "create",
 					taskId: "example",
+					phaseId: "implementation",
+					draft: true,
+					force: true,
+					cwd: "/workbase",
 					json: true,
 				}).pipe(
 					Effect.provideService(PullRequestService, {
-						create: () => Effect.succeed(url),
+						create: (...args: unknown[]) => {
+							received = args
+							return Effect.succeed(url)
+						},
 					} as never),
 				) as Effect.Effect<void, unknown, never>,
 			),
 		)
 
 		expect(JSON.parse(logs[0]!)).toEqual({ url })
+		expect(received).toEqual([
+			"example",
+			"implementation",
+			true,
+			"/workbase",
+			expect.objectContaining({
+				force: true,
+				draft: true,
+				json: true,
+			}),
+		])
 	})
 })

package/src/commands/repo.test.ts

@@ -23,7 +23,7 @@ describe("repo command", () => {
 	test("requires a subcommand", async () => {
 		await expect(
 			runTestEffect(repo({ args: [], silent: true })),
-		).rejects.toThrow("Available subcommands: add, link, list")
+		).rejects.toThrow("Available subcommands: setup, add, link, list")
 	})
 
 	test("requires add arguments", async () => {
@@ -47,7 +47,9 @@ describe("repo command", () => {
 				path: join(root, "repos/agency"),
 				kind: "repository",
 				remote: null,
+				declaredRemote: null,
 				target: null,
+				states: ["materialized", "invalid"],
 			},
 		])
 	})
@@ -75,6 +77,19 @@ describe("repo command", () => {
 			stderr: "ignore",
 		})
 		expect(await git.exited).toBe(0)
+		const remote = Bun.spawn(
+			[
+				"git",
+				"-C",
+				target,
+				"remote",
+				"add",
+				"origin",
+				"https://example.com/linked.git",
+			],
+			{ stdout: "ignore", stderr: "ignore" },
+		)
+		expect(await remote.exited).toBe(0)
 
 		const logs = await captureLogs(() =>
 			runTestEffect(
@@ -101,6 +116,19 @@ describe("repo command", () => {
 			stderr: "ignore",
 		})
 		expect(await git.exited).toBe(0)
+		const remote = Bun.spawn(
+			[
+				"git",
+				"-C",
+				target,
+				"remote",
+				"add",
+				"origin",
+				"https://example.com/unlink.git",
+			],
+			{ stdout: "ignore", stderr: "ignore" },
+		)
+		expect(await remote.exited).toBe(0)
 		await runTestEffect(
 			repo({
 				subcommand: "link",
@@ -120,5 +148,42 @@ describe("repo command", () => {
 		)
 
 		expect(await Bun.file(join(target, ".git/HEAD")).exists()).toBe(true)
+		expect(await Bun.file(join(root, "repos/linked")).exists()).toBe(false)
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				repo({ subcommand: "list", args: [], cwd: root, json: true }),
+			),
+		)
+		expect(
+			JSON.parse(logs[0]!).map(({ alias }: { alias: string }) => alias),
+		).toEqual(["agency", "linked"])
+	})
+
+	test("reports setup plans as JSON without mutating", async () => {
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					missing: { remote: "https://example.com/missing.git" },
+				},
+			}),
+		)
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				repo({ subcommand: "setup", args: [], cwd: root, json: true }),
+			),
+		)
+		const result = JSON.parse(logs[0]!)
+		expect(result.mode).toBe("dry-run")
+		expect(result.actions).toEqual([
+			{
+				kind: "materialize",
+				alias: "missing",
+				remote: "https://example.com/missing.git",
+				status: "planned",
+			},
+		])
+		expect(await Bun.file(join(root, "repos/missing")).exists()).toBe(false)
 	})
 })

package/src/commands/repo.ts

@@ -7,6 +7,8 @@ interface RepoOptions extends BaseCommandOptions {
 	readonly subcommand?: string
 	readonly args: readonly string[]
 	readonly json?: boolean
+	readonly apply?: boolean
+	readonly dryRun?: boolean
 }
 
 const requireArg = (args: readonly string[], index: number, usage: string) =>
@@ -19,6 +21,27 @@ export const repo = (options: RepoOptions) =>
 		const cwd = options.cwd ?? process.cwd()
 
 		switch (options.subcommand) {
+			case "setup": {
+				const result = yield* repositories.setup({
+					cwd,
+					apply: options.apply === true,
+				})
+				if (options.json) {
+					log(JSON.stringify(result, null, 2))
+					return
+				}
+				if (result.actions.length === 0) log("Repository setup is current")
+				for (const action of result.actions) {
+					log(
+						`${action.status === "applied" ? "Applied" : "Planned"} ${action.kind} '${action.alias}' from ${action.remote}`,
+					)
+				}
+				for (const issue of result.unresolved) {
+					log(`Unresolved '${issue.alias}': ${issue.message}. ${issue.action}`)
+				}
+				return
+			}
+
 			case "add": {
 				const [alias, remote] = options.args
 				if (!alias || !remote) {
@@ -58,8 +81,9 @@ export const repo = (options: RepoOptions) =>
 					return
 				}
 				for (const item of items) {
-					const detail = item.target ?? item.remote ?? item.path
-					log(`${item.alias}\t${item.kind}\t${detail}`)
+					const detail =
+						item.target ?? item.remote ?? item.declaredRemote ?? item.path
+					log(`${item.alias}\t${item.states.join(",")}\t${detail}`)
 				}
 				return
 			}
@@ -74,7 +98,7 @@ export const repo = (options: RepoOptions) =>
 				log(
 					options.json
 						? JSON.stringify(item, null, 2)
-						: `${item.alias}\t${item.kind}\t${item.target ?? item.remote ?? item.path}`,
+						: `${item.alias}\t${item.states.join(",")}\t${item.target ?? item.remote ?? item.declaredRemote ?? item.path}`,
 				)
 				return
 			}
@@ -136,7 +160,7 @@ export const repo = (options: RepoOptions) =>
 				log(
 					options.json
 						? JSON.stringify(item, null, 2)
-						: (item.remote ?? "No origin remote configured"),
+						: (item.declaredRemote ?? "No portable remote declared"),
 				)
 				return
 			}
@@ -163,7 +187,7 @@ export const repo = (options: RepoOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available subcommands: add, link, list, show, fetch, remove, unlink, rename, remote, verify",
+						"Subcommand is required. Available subcommands: setup, add, link, list, show, fetch, remove, unlink, rename, remote, verify",
 					),
 				)
 		}
@@ -173,17 +197,20 @@ export const help = `
 Usage: agency repo <subcommand>
 
 Subcommands:
+  setup                 Plan or apply portable repository setup
   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
+  remove <alias>        Remove a declaration and local materialization
+  unlink <alias>        Remove only this machine's linked checkout
   rename <old> <new>    Rename an unused repository alias
-  remote <alias> [url]  Show or update the origin remote
+	remote <alias> [url]  Show or update the portable remote declaration
   verify <alias>        Verify repository operation
 
 Options:
+  --dry-run             Report setup changes without applying them (default)
+  --apply               Apply safe setup changes
   --json                Output repository aliases as JSON
 `

package/src/commands/status.test.ts

@@ -41,7 +41,9 @@ describe("status command", () => {
 				path: join(root, "repos/agency"),
 				kind: "repository",
 				remote: null,
+				declaredRemote: null,
 				target: null,
+				states: ["materialized", "invalid"],
 			},
 		])
 	})
@@ -58,6 +60,25 @@ describe("status command", () => {
 				silent: true,
 			}),
 		)
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["finished"],
+				repo: "agency",
+				branch: "feat/finished",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			task({
+				subcommand: "status",
+				args: ["finished", "done"],
+				cwd: root,
+				silent: true,
+			}),
+		)
 
 		const logs = await captureLogs(() =>
 			runTestEffect(
@@ -71,6 +92,7 @@ describe("status command", () => {
 		expect(logs.at(-1)).toContain(
 			"task  example  -       open    ready      agency        feat/example  absent  absent",
 		)
+		expect(logs.at(-1)).not.toContain("finished")
 	})
 
 	test("reports validation issues without requiring a decodable graph", async () => {

package/src/commands/status.ts

@@ -42,6 +42,7 @@ export const status = (options: StatusOptions = {}) =>
 
 		log(`Workbase: ${report.root}`)
 		log(`Repositories: ${repos.length}`)
+		for (const repo of repos) log(`  ${repo.alias}: ${repo.states.join(", ")}`)
 		log(`Epics: ${report.epicCount}`)
 		log(`Tasks: ${report.taskCount}`)
 		log(`Phases: ${report.phaseCount}`)

package/src/commands/sync.ts

@@ -22,15 +22,17 @@ export const sync = (options: SyncCommandOptions = {}) =>
 export const help = `
 Usage: agency sync [--dry-run | --apply] [--json]
 
-Compare declared execution state with Git worktrees, branches, references, claims,
-and GitHub pull requests. Dry-run is the default.
+Compare portable repository declarations and execution state with local Git
+repositories, worktrees, branches, references, claims, and pull requests.
+Dry-run is the default.
 
 Options:
   --dry-run                 Report planned safe transitions without changing state
   --apply                   Apply safe reconciliation transitions
   --json                    Output one versioned machine result
 
-Apply may materialize unambiguous missing checkouts, release expired claims,
+Apply may materialize declared repositories and unambiguous missing checkouts,
+adopt legacy repositories with portable origins, release expired claims,
 record a uniquely matched PR, and mark merged work done. Dirty, stale, or
 conflicting checkouts are always left unresolved.
 `

package/src/commands/workbase.ts

@@ -151,7 +151,7 @@ export const workbase = (options: WorkbaseOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available: add, list, show, name, remove, prune, default",
+						"Subcommand is required. Available: init, add, list, show, name, remove, prune, default",
 					),
 				)
 		}
@@ -161,6 +161,7 @@ export const help = `
 Usage: agency workbase <subcommand>
 
 Subcommands:
+  init [path]       Initialize an Agency workbase
   add <path>        Register an Agency workbase
   list              List registered workbases
   show <selector>   Show a registered workbase