@markjaquith/agency 2.5.0 → 2.7.0

package/src/commands/work.test.ts

@@ -9,6 +9,7 @@ import { WorktreeService } from "../services/WorktreeService"
 import { captureLogs } from "../test-utils"
 import { work } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
+import type { PickWorkbase } from "../workbase/workbase-choice"
 import type { Progress } from "../utils/progress"
 
 type ExecutionWorkspace = Effect.Effect.Success<
@@ -43,6 +44,8 @@ interface HarnessOptions {
 	readonly epicRecords?: readonly any[]
 	readonly taskRecords?: readonly any[]
 	readonly phaseRecords?: readonly any[]
+	readonly outsideWorkbase?: boolean
+	readonly registeredWorkbases?: readonly string[]
 }
 
 const createHarness = (options: HarnessOptions = {}) => {
@@ -73,7 +76,14 @@ const createHarness = (options: HarnessOptions = {}) => {
 		},
 	}
 	const workbase = {
-		discover: () => Effect.succeed("/workbase"),
+		discover: (path: string) =>
+			options.outsideWorkbase && path === "/outside"
+				? Effect.fail({
+						_tag: "WorkbaseNotFoundError" as const,
+						message: "No Agency workbase found from /outside",
+					})
+				: Effect.succeed("/workbase"),
+		listRegistered: () => Effect.succeed(options.registeredWorkbases ?? []),
 	}
 	const epics = {
 		show: (id: string) =>
@@ -114,6 +124,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		},
 	}
 	const fs = {
+		isDirectory: () => Effect.succeed(true),
 		runCommand: (args: readonly string[]) => {
 			const cli = args[1] as "opencode" | "claude"
 			events.push(`probe:${cli}`)
@@ -130,6 +141,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		launches.push({ cli, args, cwd })
 	}
 	const defaultPick: PickWorkTarget = () => Effect.succeed(null)
+	const defaultPickWorkbase: PickWorkbase = () => Effect.succeed(null)
 	const progress: Progress = {
 		start: (message) => progressUpdates.push(`start:${message}`),
 		succeed: (message) => progressUpdates.push(`succeed:${message}`),
@@ -138,9 +150,10 @@ const createHarness = (options: HarnessOptions = {}) => {
 	const run = (
 		commandOptions: Parameters<typeof work>[0],
 		pick: PickWorkTarget = defaultPick,
+		pickBase: PickWorkbase = defaultPickWorkbase,
 	) =>
 		Effect.runPromise(
-			work(commandOptions, launch, pick, progress).pipe(
+			work(commandOptions, launch, pick, progress, pickBase).pipe(
 				Effect.provideService(WorktreeService, worktrees as never),
 				Effect.provideService(FileSystemService, fs as never),
 				Effect.provideService(WorkbaseService, workbase as never),
@@ -165,7 +178,11 @@ describe("work command", () => {
 	test("launches an epic agent from an epic directory", async () => {
 		const harness = createHarness()
 
-		await harness.run({ cwd: "/workbase/epics/delivery", opencode: true })
+		await harness.run({
+			cwd: "/workbase/epics/delivery",
+			directory: ".",
+			opencode: true,
+		})
 
 		expect(harness.events).toEqual(["probe:opencode", "launch:opencode"])
 		expect(harness.launches[0]).toEqual({
@@ -178,7 +195,11 @@ describe("work command", () => {
 	test("launches a multi-phase task agent without materializing", async () => {
 		const harness = createHarness({ multiPhaseTasks: ["delivery"] })
 
-		await harness.run({ cwd: "/workbase/tasks/delivery", opencode: true })
+		await harness.run({
+			cwd: "/workbase/tasks/delivery",
+			directory: ".",
+			opencode: true,
+		})
 
 		expect(harness.events).toEqual(["probe:opencode", "launch:opencode"])
 		expect(harness.launches[0]).toEqual({
@@ -193,6 +214,7 @@ describe("work command", () => {
 
 		await harness.run({
 			cwd: "/workbase/tasks/example/phases/implementation/code/agency/src",
+			directory: ".",
 			opencode: true,
 		})
 
@@ -212,6 +234,7 @@ describe("work command", () => {
 
 		await harness.run({
 			cwd: "/workbase/tasks/example/code/agency/src",
+			directory: ".",
 			opencode: true,
 		})
 
@@ -219,7 +242,7 @@ describe("work command", () => {
 		expect(harness.launches[0]?.cwd).toBe("/workbase/tasks/example")
 	})
 
-	test("selects a target with fzf outside an entity directory", async () => {
+	test("selects a target with fzf when no directory is provided", async () => {
 		const phase = {
 			taskId: "delivery",
 			id: "build",
@@ -242,7 +265,7 @@ describe("work command", () => {
 				choices.find((choice) => choice.label.includes("build"))!.target,
 			)
 
-		await harness.run({ cwd: "/workbase", opencode: true }, pick)
+		await harness.run({ cwd: "/workbase/tasks/example", opencode: true }, pick)
 
 		expect(harness.events).toEqual([
 			"probe:fzf",
@@ -255,6 +278,41 @@ describe("work command", () => {
 		)
 	})
 
+	test("selects a registered workbase when local discovery fails", async () => {
+		const harness = createHarness({
+			outsideWorkbase: true,
+			registeredWorkbases: ["/first", "/workbase"],
+		})
+		const selections: string[][] = []
+		const pickBase: PickWorkbase = (workbases) => {
+			selections.push([...workbases])
+			return Effect.succeed("/workbase")
+		}
+
+		await harness.run(
+			{ cwd: "/outside", taskId: "example", opencode: true },
+			undefined,
+			pickBase,
+		)
+
+		expect(selections).toEqual([["/first", "/workbase"]])
+		expect(harness.events).toEqual([
+			"probe:fzf",
+			"materialize",
+			"probe:opencode",
+			"launch:opencode",
+		])
+	})
+
+	test("explains how to register a workbase when none are known", async () => {
+		const harness = createHarness({ outsideWorkbase: true })
+
+		await expect(harness.run({ cwd: "/outside" })).rejects.toThrow(
+			"agency workbase add <path>",
+		)
+		expect(harness.events).toEqual([])
+	})
+
 	test("prints the target tree when fzf is unavailable", async () => {
 		const harness = createHarness({
 			available: { fzf: false },
@@ -401,7 +459,7 @@ describe("work command", () => {
 			verboseHarness.run({ taskId: "example", verbose: true }),
 		)
 		expect(verboseLogs).toEqual([
-			"Launching opencode in /workbase/tasks/example",
+			"Launching command: opencode --continue (cwd: /workbase/tasks/example)",
 		])
 		expect(verboseHarness.materializeOptions[0]?.verbose).toBe(true)
 

package/src/commands/work.ts

@@ -16,8 +16,14 @@ import {
 	type PickWorkTarget,
 	type WorkTarget,
 } from "../workbase/work-target"
+import {
+	pickWorkbase,
+	resolveWorkbase,
+	type PickWorkbase,
+} from "../workbase/workbase-choice"
 
 interface WorkOptions extends BaseCommandOptions {
+	readonly directory?: string
 	readonly taskId?: string
 	readonly phaseId?: string
 	readonly epicId?: string
@@ -27,6 +33,15 @@ interface WorkOptions extends BaseCommandOptions {
 
 type LaunchAgent = (cli: string, args: readonly string[], cwd: string) => void
 
+const formatCommand = (args: readonly string[]) =>
+	args
+		.map((argument) =>
+			/^[A-Za-z0-9_./:=+@%-]+$/.test(argument)
+				? argument
+				: `'${argument.replaceAll("'", `'\\''`)}'`,
+		)
+		.join(" ")
+
 const launchAgent: LaunchAgent = (cli, args, cwd) => {
 	process.chdir(cwd)
 	execvp(cli, [...args])
@@ -37,6 +52,7 @@ export const work = (
 	launch: LaunchAgent = launchAgent,
 	pick: PickWorkTarget = pickWorkTarget,
 	progress: Progress = createProgress(options),
+	pickBase: PickWorkbase = pickWorkbase,
 ) =>
 	Effect.gen(function* () {
 		if (options.opencode && options.claude) {
@@ -44,9 +60,12 @@ export const work = (
 				new Error("Cannot use both --opencode and --claude"),
 			)
 		}
-		if (options.epicId && (options.taskId || options.phaseId)) {
+		if (
+			options.epicId &&
+			(options.directory || options.taskId || options.phaseId)
+		) {
 			return yield* Effect.fail(
-				new Error("Cannot combine --epic with a task or phase ID"),
+				new Error("Cannot combine --epic with a directory, task, or phase ID"),
 			)
 		}
 
@@ -58,7 +77,14 @@ export const work = (
 		const phases = yield* PhaseService
 		const { log, verboseLog } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
-		const root = yield* workbase.discover(cwd)
+		const startPath = options.directory ? resolve(cwd, options.directory) : cwd
+		if (options.directory && !(yield* fs.isDirectory(startPath))) {
+			return yield* Effect.fail(
+				new Error(`Work directory does not exist: ${startPath}`),
+			)
+		}
+		const root = yield* resolveWorkbase(startPath, log, pickBase)
+		if (!root) return
 
 		let target: WorkTarget | null = null
 		if (options.epicId) {
@@ -82,8 +108,8 @@ export const work = (
 					multiPhase: "phases" in task.data,
 				}
 			}
-		} else {
-			const path = relative(root, resolve(cwd))
+		} else if (options.directory) {
+			const path = relative(root, startPath)
 			const parts =
 				!path || isAbsolute(path) || path.startsWith(`..${sep}`)
 					? []
@@ -138,7 +164,7 @@ export const work = (
 				for (const choice of choices) log(choice.label)
 				return yield* Effect.fail(
 					new Error(
-						"fzf is required to select a work target; install fzf or provide a target explicitly",
+						"fzf is required to select a work target; install fzf or provide a directory explicitly",
 					),
 				)
 			}
@@ -192,16 +218,19 @@ export const work = (
 			yield* tasks.setStatus(target.taskId, "working", root)
 		}
 
-		verboseLog(`Launching ${cli} in ${launchPath}`)
 		const args = cli === "opencode" ? ["--continue"] : [prompt]
+		verboseLog(
+			`Launching command: ${formatCommand([cli, ...args])} (cwd: ${launchPath})`,
+		)
 		launch(cli, [cli, ...args], launchPath)
 	})
 
 export const help = `
-Usage: agency work [<task-id> [phase-id] | --epic <epic-id>]
+Usage: agency work [<directory> | --epic <epic-id>]
 
-Launch an agent for the current epic, task, or phase. Outside an entity
-directory, select one with fzf.
+Launch an agent for an epic, task, or phase. With no directory, select one
+with fzf. Use '.' for the current directory. Outside a workbase, select a
+registered workbase first.
 
 Options:
   --epic <id>         Work on an epic

package/src/commands/workbase.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { workbase } from "./workbase"
+
+describe("workbase command", () => {
+	let root: string
+	let configDirectory: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		configDirectory = join(root, "config")
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("adds and lists workbases as JSON", async () => {
+		const added = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "add",
+					args: [root],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		const path = JSON.parse(added[0]!).path
+
+		const listed = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "list",
+					args: [],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(listed[0]!)).toEqual([path])
+	})
+
+	test("requires an add path", async () => {
+		await expect(
+			runTestEffect(
+				workbase({
+					subcommand: "add",
+					args: [],
+					configDirectory,
+					silent: true,
+				}),
+			),
+		).rejects.toThrow("Usage: agency workbase add <path>")
+	})
+})

package/src/commands/workbase.ts

@@ -0,0 +1,58 @@
+import { Effect } from "effect"
+import type { BaseCommandOptions } from "../utils/command"
+import { WorkbaseService } from "../services/WorkbaseService"
+import { createLoggers } from "../utils/effect"
+
+interface WorkbaseOptions extends BaseCommandOptions {
+	readonly subcommand?: string
+	readonly args: readonly string[]
+	readonly configDirectory?: string
+}
+
+export const workbase = (options: WorkbaseOptions) =>
+	Effect.gen(function* () {
+		const service = yield* WorkbaseService
+		const { log } = createLoggers(options)
+
+		switch (options.subcommand) {
+			case "add": {
+				const path = options.args[0]
+				if (!path) {
+					return yield* Effect.fail(
+						new Error("Usage: agency workbase add <path>"),
+					)
+				}
+				const root = yield* service.register(path, options.configDirectory)
+				log(
+					options.json
+						? JSON.stringify({ path: root }, null, 2)
+						: `Added workbase ${root}`,
+				)
+				return
+			}
+			case "list": {
+				const workbases = yield* service.listRegistered(options.configDirectory)
+				if (options.json) {
+					log(JSON.stringify(workbases, null, 2))
+				} else {
+					for (const path of workbases) log(path)
+				}
+				return
+			}
+			default:
+				return yield* Effect.fail(
+					new Error("Subcommand is required. Available: add, list"),
+				)
+		}
+	})
+
+export const help = `
+Usage: agency workbase <subcommand>
+
+Subcommands:
+  add <path>  Register an Agency workbase
+  list        List registered workbases
+
+Options:
+  --json      Output results as JSON
+`

package/src/services/TaskPhaseService.test.ts

@@ -237,12 +237,12 @@ describe("task and phase services", () => {
 		const task = await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
-					service.setStatus("single-status", "done", root),
+					service.setStatus("single-status", "delegated", root),
 				),
 			),
 		)
-		expect(task.data.status).toBe("done")
-		expect(task.content).toContain("status: done")
+		expect(task.data.status).toBe("delegated")
+		expect(task.content).toContain("status: delegated")
 		expect(task.content).toContain("Describe the task outcome.")
 
 		await runTestEffect(

package/src/services/WorkbaseService.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { createHash } from "node:crypto"
-import { mkdir } from "node:fs/promises"
+import { mkdir, realpath } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { managedWorkbaseAgents } from "../workbase/agents-file"
@@ -52,10 +52,42 @@ describe("WorkbaseService", () => {
 			managedWorkbaseAgents,
 		)
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			managedWorkbaseOpencode,
+			managedWorkbaseOpencode(root),
 		)
 	})
 
+	test("registers canonical workbase paths without duplicates", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const nested = join(workbaseRoot, "nested")
+		const configDirectory = join(root, "config")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+		await mkdir(nested, { recursive: true })
+
+		const first = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) => service.register(nested, configDirectory)),
+			),
+		)
+		await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.register(workbaseRoot, configDirectory),
+				),
+			),
+		)
+		const registered = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) => service.listRegistered(configDirectory)),
+			),
+		)
+
+		expect(first).toBe(await realpath(workbaseRoot))
+		expect(registered).toEqual([first])
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
+		).toEqual({ version: 1, workbases: [first] })
+	})
+
 	test("preserves an unmanaged workbase OpenCode config", async () => {
 		await write(root, "agency.json", '{"version":2}\n')
 		await write(root, ".opencode/opencode.jsonc", '{"model":"test/model"}\n')
@@ -95,7 +127,7 @@ describe("WorkbaseService", () => {
 		)
 
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			managedWorkbaseOpencode,
+			managedWorkbaseOpencode(root),
 		)
 	})
 

package/src/services/WorkbaseService.ts

@@ -1,6 +1,7 @@
 import { Schema } from "@effect/schema"
 import { TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either } from "effect"
+import { homedir } from "node:os"
 import { dirname, join, relative, resolve } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { parseFrontmatter } from "../workbase/frontmatter"
@@ -9,6 +10,7 @@ import {
 	PhaseFrontmatter,
 	TaskFrontmatter,
 	WorkbaseConfig,
+	WorkbaseRegistry,
 	type Dependency,
 	type EpicFrontmatter as EpicData,
 	type PhaseFrontmatter as PhaseData,
@@ -34,6 +36,12 @@ class WorkbaseConfigError extends Data.TaggedError("WorkbaseConfigError")<{
 	readonly cause?: unknown
 }> {}
 
+class WorkbaseRegistryError extends Data.TaggedError("WorkbaseRegistryError")<{
+	readonly message: string
+	readonly path: string
+	readonly cause?: unknown
+}> {}
+
 interface ValidationIssue {
 	readonly path: string
 	readonly message: string
@@ -72,6 +80,45 @@ const decode = <S extends Schema.Schema.AnyNoContext>(
 		: { success: true, value: result.right }
 }
 
+const registryPath = (configDirectory?: string) =>
+	join(
+		configDirectory ||
+			process.env.XDG_CONFIG_HOME ||
+			join(homedir(), ".config"),
+		"agency",
+		"workbases.json",
+	)
+
+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 }
+		}
+
+		const content = yield* fs.readFile(path)
+		let input: unknown
+		try {
+			input = JSON.parse(content)
+		} catch (cause) {
+			return yield* new WorkbaseRegistryError({
+				path,
+				message: `Invalid JSON in workbase registry ${path}`,
+				cause,
+			})
+		}
+
+		const decoded = decode(WorkbaseRegistry, input)
+		if (!decoded.success) {
+			return yield* new WorkbaseRegistryError({
+				path,
+				message: `Invalid workbase registry in ${path}:\n${decoded.error}`,
+			})
+		}
+		return { path, registry: decoded.value }
+	})
+
 const ensureWorkbaseAgents = (root: string) =>
 	Effect.gen(function* () {
 		const fs = yield* FileSystemService
@@ -95,19 +142,17 @@ const ensureWorkbaseOpencode = (root: string) =>
 		const fs = yield* FileSystemService
 		const directory = join(root, ".opencode")
 		const path = join(directory, "opencode.jsonc")
+		const managed = managedWorkbaseOpencode(root)
 		if (!(yield* fs.exists(path))) {
 			if (yield* fs.exists(join(directory, "opencode.json"))) return
 			yield* fs.createDirectory(directory)
-			yield* fs.writeFile(path, managedWorkbaseOpencode)
+			yield* fs.writeFile(path, managed)
 			return
 		}
 
 		const content = yield* fs.readFile(path)
-		if (
-			content !== managedWorkbaseOpencode &&
-			canUpdateManagedWorkbaseOpencode(content)
-		) {
-			yield* fs.writeFile(path, managedWorkbaseOpencode)
+		if (content !== managed && canUpdateManagedWorkbaseOpencode(content)) {
+			yield* fs.writeFile(path, managed)
 		}
 	})
 
@@ -293,6 +338,28 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					return { root, config: decoded.value }
 				}),
 
+			register: (startPath: string, configDirectory?: 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
+
+					yield* fs.createDirectory(dirname(path))
+					yield* fs.writeJSON(path, {
+						version: 1,
+						workbases: [...registry.workbases, root],
+					})
+					return root
+				}),
+
+			listRegistered: (configDirectory?: string) =>
+				readRegistry(configDirectory).pipe(
+					Effect.map(({ registry }) => registry.workbases),
+				),
+
 			validate: (startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const service = yield* WorkbaseService

package/src/services/WorktreeService.test.ts

@@ -85,6 +85,51 @@ describe("WorktreeService", () => {
 		expect(new TextDecoder().decode(branch.stdout).trim()).toBe("task/example")
 	})
 
+	test("does not fetch origins for existing worktrees", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "existing",
+							ticketUrl: "https://example.com/task",
+							repo: "agency",
+							repos: [{ repo: "effect", ref: "main" }],
+							branch: "task/existing",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("existing", undefined, root),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", join(root, "missing")],
+			join(root, "repos/agency"),
+		)
+		await git(
+			["remote", "set-url", "origin", join(root, "missing")],
+			join(root, "repos/effect"),
+		)
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("existing", undefined, root),
+					),
+				),
+			),
+		).resolves.toMatchObject({ repo: "agency" })
+	})
+
 	test("uses a configured worktree creation command", async () => {
 		await Bun.write(
 			join(root, "agency.json"),