@markjaquith/agency 1.11.0 → 2.0.0

package/src/commands/work.ts

@@ -1,193 +1,74 @@
-import { join } from "node:path"
 import { Effect } from "effect"
 import type { BaseCommandOptions } from "../utils/command"
+import { WorktreeService } from "../services/WorktreeService"
 import { FileSystemService } from "../services/FileSystemService"
-import { createLoggers, ensureGitRepo } from "../utils/effect"
-import { spawnProcess } from "../utils/process"
+import { createLoggers } from "../utils/effect"
 import { execvp } from "../utils/exec"
 
 interface WorkOptions extends BaseCommandOptions {
-	/**
-	 * Force use of OpenCode CLI
-	 */
-	opencode?: boolean
-	/**
-	 * Force use of Claude Code CLI
-	 */
-	claude?: boolean
-	/**
-	 * Additional arguments to pass to the CLI tool
-	 */
-	extraArgs?: string[]
-	/**
-	 * Internal option to disable exec for testing.
-	 * When true, uses spawn instead of exec so tests can complete.
-	 */
-	_noExec?: boolean
+	readonly taskId?: string
+	readonly phaseId?: string
+	readonly opencode?: boolean
+	readonly claude?: boolean
 }
 
-export const work = (options: WorkOptions = {}) =>
-	Effect.gen(function* () {
-		const { verboseLog } = createLoggers(options)
-
-		const fs = yield* FileSystemService
+type LaunchAgent = (cli: string, args: readonly string[], cwd: string) => void
 
-		const gitRoot = yield* ensureGitRepo()
+const launchAgent: LaunchAgent = (cli, args, cwd) => {
+	process.chdir(cwd)
+	execvp(cli, [...args])
+}
 
-		// Check if TASK.md exists
-		const taskPath = join(gitRoot, "TASK.md")
-		const taskExists = yield* fs.exists(taskPath)
-		if (!taskExists) {
-			return yield* Effect.fail(
-				new Error("TASK.md not found. Run 'agency task' first to create it."),
-			)
+export const work = (
+	options: WorkOptions = {},
+	launch: LaunchAgent = launchAgent,
+) =>
+	Effect.gen(function* () {
+		if (!options.taskId) {
+			return yield* Effect.fail(new Error("Task ID is required"))
 		}
-
-		verboseLog(`Found TASK.md at: ${taskPath}`)
-
-		// Change to git root before executing
-		process.chdir(gitRoot)
-
-		// Check for conflicting flags
 		if (options.opencode && options.claude) {
 			return yield* Effect.fail(
-				new Error(
-					"Cannot use both --opencode and --claude flags together. Choose one.",
-				),
+				new Error("Cannot use both --opencode and --claude"),
 			)
 		}
 
-		// Check which CLI tool is available
-		const hasOpencode = yield* Effect.tryPromise({
-			try: async () => {
-				const result = Bun.spawnSync(["which", "opencode"], {
-					stdout: "ignore",
-					stderr: "ignore",
-				})
-				return result.exitCode === 0
-			},
-			catch: () => false,
-		})
-
-		const hasClaude = yield* Effect.tryPromise({
-			try: async () => {
-				const result = Bun.spawnSync(["which", "claude"], {
-					stdout: "ignore",
-					stderr: "ignore",
-				})
-				return result.exitCode === 0
-			},
-			catch: () => false,
+		const worktrees = yield* WorktreeService
+		const fs = yield* FileSystemService
+		const { verboseLog } = createLoggers(options)
+		const workspace = yield* worktrees.materialize(
+			options.taskId,
+			options.phaseId,
+			options.cwd ?? process.cwd(),
+		)
+		const prompt = workspace.phasePath
+			? `Start the task. Read ${workspace.taskPath} and ${workspace.phasePath}.`
+			: `Start the task. Read ${workspace.taskPath}.`
+
+		const requested = options.claude ? "claude" : "opencode"
+		let cli = requested
+		let available = yield* fs.runCommand(["which", cli], {
+			captureOutput: true,
 		})
-
-		// Determine which CLI to use based on flags or auto-detection
-		let useOpencode: boolean
-		if (options.opencode) {
-			if (!hasOpencode) {
-				return yield* Effect.fail(
-					new Error(
-						"opencode CLI tool not found. Please install OpenCode or remove the --opencode flag.",
-					),
-				)
-			}
-			useOpencode = true
-			verboseLog("Using opencode (explicitly requested)")
-		} else if (options.claude) {
-			if (!hasClaude) {
-				return yield* Effect.fail(
-					new Error(
-						"claude CLI tool not found. Please install Claude Code or remove the --claude flag.",
-					),
-				)
-			}
-			useOpencode = false
-			verboseLog("Using claude (explicitly requested)")
-		} else {
-			// Auto-detect
-			if (!hasOpencode && !hasClaude) {
-				return yield* Effect.fail(
-					new Error(
-						"Neither opencode nor claude CLI tool found. Please install OpenCode or Claude Code.",
-					),
-				)
-			}
-			useOpencode = hasOpencode
-			verboseLog(`Using ${useOpencode ? "opencode" : "claude"} (auto-detected)`)
+		if (available.exitCode !== 0 && !options.opencode && !options.claude) {
+			cli = "claude"
+			available = yield* fs.runCommand(["which", cli], { captureOutput: true })
 		}
-
-		const cliName = useOpencode ? "opencode" : "claude"
-		const baseArgs = useOpencode
-			? [cliName, "--prompt", "Start the task"]
-			: [cliName, "Start the task"]
-
-		// Append extra args if provided
-		const cliArgs =
-			options.extraArgs && options.extraArgs.length > 0
-				? [...baseArgs, ...options.extraArgs]
-				: baseArgs
-
-		if (options.extraArgs && options.extraArgs.length > 0) {
-			verboseLog(
-				`Running ${cliName} with extra args: ${options.extraArgs.join(" ")}`,
-			)
-		} else {
-			verboseLog(`Running ${cliName} with task prompt...`)
+		if (available.exitCode !== 0) {
+			return yield* Effect.fail(new Error(`${cli} CLI tool not found`))
 		}
 
-		// For testing, we need to use spawn instead of exec since exec never returns
-		if (options._noExec) {
-			const result = yield* spawnProcess(cliArgs, {
-				cwd: gitRoot,
-				stdout: "inherit",
-				stderr: "inherit",
-			}).pipe(
-				Effect.catchAll((error) =>
-					Effect.fail(
-						new Error(`${cliName} exited with code ${error.exitCode}`),
-					),
-				),
-			)
-
-			if (result.exitCode !== 0) {
-				return yield* Effect.fail(
-					new Error(`${cliName} exited with code ${result.exitCode}`),
-				)
-			}
-		} else {
-			// Use execvp to replace the current process with the CLI tool
-			// This will never return - the process is completely replaced
-			execvp(cliName, cliArgs)
-		}
+		verboseLog(`Launching ${cli} in ${workspace.writablePath}`)
+		const args = cli === "opencode" ? ["--prompt", prompt] : [prompt]
+		launch(cli, [cli, ...args], workspace.writablePath)
 	})
 
 export const help = `
-Usage: agency work [options] [-- extra-args...]
-
-Start working on the task described in TASK.md using OpenCode or Claude Code.
+Usage: agency work <task-id> [phase-id]
 
-This command replaces the current process with OpenCode (if available) or
-Claude Code (if OpenCode is not available), launching it with a prompt to
-get started on the task described in your TASK.md file.
+Materialize repository worktrees and launch an agent in the writable checkout.
 
 Options:
-  --opencode            Force use of OpenCode CLI
-  --claude              Force use of Claude Code CLI
-
-Pass-through Arguments:
-  Use -- to pass additional arguments to the underlying CLI tool.
-  Everything after -- will be forwarded to opencode or claude.
-
-Examples:
-  agency work                                  # Auto-detect (prefers opencode)
-  agency work --opencode                       # Explicitly use OpenCode
-  agency work --claude                         # Explicitly use Claude Code
-  agency work -- --model claude-sonnet-4-20250514  # Pass custom args to CLI
-
-Notes:
-  - Requires TASK.md to exist (run 'agency task' first)
-  - Requires either opencode or claude to be installed and available in PATH
-  - By default, prefers opencode if both are available
-  - Use --opencode or --claude to override auto-detection
-  - Arguments after -- are passed directly to the underlying tool
-  - Replaces the current process (agency exits and the tool takes over)
+  --opencode           Require OpenCode
+  --claude             Require Claude Code
 `

package/src/services/EpicService.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { Effect } from "effect"
+import { EpicService } from "./EpicService"
+
+describe("EpicService", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+	})
+
+	afterEach(async () => {
+		await cleanupTempDir(root)
+	})
+
+	test("creates, lists, and shows epics", async () => {
+		const created = await runTestEffect(
+			EpicService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						"workspace-orchestration",
+						"https://example.com/tickets/epic",
+						[{ repo: "agency", ref: "main" }],
+						root,
+					),
+				),
+			),
+		)
+
+		expect(created.content).toContain("ticketUrl:")
+		expect(created.content).toContain("tasks: []")
+
+		const records = await runTestEffect(
+			EpicService.pipe(Effect.flatMap((service) => service.list(root))),
+		)
+		expect(records.map((record) => record.id)).toEqual([
+			"workspace-orchestration",
+		])
+
+		const shown = await runTestEffect(
+			EpicService.pipe(
+				Effect.flatMap((service) =>
+					service.show("workspace-orchestration", root),
+				),
+			),
+		)
+		expect(shown.path).toBe(join(root, "epics/workspace-orchestration/EPIC.md"))
+	})
+
+	test("rejects unknown repository aliases", async () => {
+		await expect(
+			runTestEffect(
+				EpicService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							"example",
+							"https://example.com/tickets/epic",
+							[{ repo: "missing", ref: "main" }],
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("Unknown repository alias 'missing'")
+	})
+})

package/src/services/EpicService.ts

@@ -0,0 +1,135 @@
+import { Schema, TreeFormatter } from "@effect/schema"
+import { Data, Effect, Either } from "effect"
+import { join } from "node:path"
+import { FileSystemService } from "./FileSystemService"
+import { WorkbaseService } from "./WorkbaseService"
+import {
+	EpicFrontmatter,
+	EntityId,
+	type RepositoryReference,
+} from "../workbase/schemas"
+import {
+	formatMarkdownDocument,
+	parseFrontmatter,
+} from "../workbase/frontmatter"
+
+class EpicError extends Data.TaggedError("EpicError")<{
+	readonly message: string
+}> {}
+
+export interface EpicRecord {
+	readonly id: string
+	readonly path: string
+	readonly content: string
+	readonly data: Schema.Schema.Type<typeof EpicFrontmatter>
+}
+
+const decodeEpic = (input: unknown) => {
+	const result = Schema.decodeUnknownEither(EpicFrontmatter, {
+		errors: "all",
+		onExcessProperty: "error",
+	})(input)
+	return Either.isLeft(result)
+		? Effect.fail(
+				new EpicError({ message: TreeFormatter.formatErrorSync(result.left) }),
+			)
+		: Effect.succeed(result.right)
+}
+
+const decodeId = (id: string) => {
+	const result = Schema.decodeUnknownEither(EntityId)(id)
+	return Either.isLeft(result)
+		? Effect.fail(new EpicError({ message: `Invalid epic ID '${id}'` }))
+		: Effect.succeed(result.right)
+}
+
+export class EpicService extends Effect.Service<EpicService>()("EpicService", {
+	sync: () => ({
+		create: (
+			id: string,
+			ticketUrl: string,
+			repos: readonly RepositoryReference[],
+			startPath: string = process.cwd(),
+			description?: string,
+		) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const workbase = yield* WorkbaseService
+				const root = yield* workbase.discover(startPath)
+				const validId = yield* decodeId(id)
+				const data = yield* decodeEpic({
+					ticketUrl,
+					...(description !== undefined ? { description } : {}),
+					repos,
+					tasks: [],
+				})
+				const directory = join(root, "epics", validId)
+				const path = join(directory, "EPIC.md")
+
+				if (yield* fs.exists(directory)) {
+					return yield* new EpicError({
+						message: `Epic '${validId}' already exists`,
+					})
+				}
+
+				for (const { repo: alias } of data.repos) {
+					if (!(yield* fs.exists(join(root, "repos", alias)))) {
+						return yield* new EpicError({
+							message: `Unknown repository alias '${alias}'`,
+						})
+					}
+				}
+
+				yield* fs.createDirectory(directory)
+				const title = validId
+					.split("-")
+					.map((part) => part[0]?.toUpperCase() + part.slice(1))
+					.join(" ")
+				const content = formatMarkdownDocument(
+					data,
+					`# ${title}\n\nDescribe the epic outcome.`,
+				)
+				yield* fs.writeFile(path, content)
+				return { id: validId, path, content, data } satisfies EpicRecord
+			}),
+
+		list: (startPath: string = process.cwd()) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const workbase = yield* WorkbaseService
+				const root = yield* workbase.discover(startPath)
+				const directory = join(root, "epics")
+				if (!(yield* fs.isDirectory(directory))) {
+					return [] as EpicRecord[]
+				}
+
+				const entries = (yield* fs.readDirectory(directory))
+					.filter((entry) => entry.isDirectory)
+					.sort((a, b) => a.name.localeCompare(b.name))
+				const records: EpicRecord[] = []
+				for (const entry of entries) {
+					const path = join(directory, entry.name, "EPIC.md")
+					if (!(yield* fs.exists(path))) continue
+					const content = yield* fs.readFile(path)
+					const parsed = yield* parseFrontmatter(content, path)
+					const data = yield* decodeEpic(parsed.data)
+					records.push({ id: entry.name, path, content, data })
+				}
+				return records
+			}),
+
+		show: (id: string, startPath: string = process.cwd()) =>
+			Effect.gen(function* () {
+				const service = yield* EpicService
+				const validId = yield* decodeId(id)
+				const records = yield* service.list(startPath)
+				const record = records.find((epic) => epic.id === validId)
+				if (!record) {
+					return yield* new EpicError({
+						message: `Epic '${validId}' does not exist`,
+					})
+				}
+				return record
+			}),
+	}),
+}) {}

package/src/services/FileSystemService.ts

@@ -1,10 +1,13 @@
 import { Effect, Data, pipe } from "effect"
 import {
 	mkdir,
-	copyFile as fsCopyFile,
-	unlink,
 	lstat,
 	readlink,
+	readdir,
+	realpath,
+	rename,
+	stat,
+	symlink,
 } from "node:fs/promises"
 import { spawnProcess } from "../utils/process"
 
@@ -26,8 +29,20 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 			exists: (path: string) =>
 				Effect.tryPromise({
 					try: async () => {
-						const file = Bun.file(path)
-						return await file.exists()
+						try {
+							await lstat(path)
+							return true
+						} catch (error) {
+							if (
+								typeof error === "object" &&
+								error !== null &&
+								"code" in error &&
+								error.code === "ENOENT"
+							) {
+								return false
+							}
+							throw error
+						}
 					},
 					catch: () =>
 						new FileSystemError({
@@ -38,16 +53,19 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 			isDirectory: (path: string) =>
 				Effect.tryPromise({
 					try: async () => {
-						const file = Bun.file(path)
-						const exists = await file.exists()
-						if (!exists) {
-							return false
+						try {
+							return (await stat(path)).isDirectory()
+						} catch (error) {
+							if (
+								typeof error === "object" &&
+								error !== null &&
+								"code" in error &&
+								error.code === "ENOENT"
+							) {
+								return false
+							}
+							throw error
 						}
-						// Use stat to check if it's a directory
-						const stat = await import("node:fs/promises").then((fs) =>
-							fs.stat(path),
-						)
-						return stat.isDirectory()
 					},
 					catch: () =>
 						new FileSystemError({
@@ -55,6 +73,16 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 						}),
 				}),
 
+			realPath: (path: string) =>
+				Effect.tryPromise({
+					try: () => realpath(path),
+					catch: (error) =>
+						new FileSystemError({
+							message: `Failed to resolve path: ${path}`,
+							cause: error,
+						}),
+				}),
+
 			readFile: (path: string) =>
 				Effect.tryPromise({
 					try: async () => {
@@ -78,19 +106,6 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 						}),
 				}),
 
-			readJSON: <T = unknown>(path: string) =>
-				Effect.tryPromise({
-					try: async (): Promise<T> => {
-						const file = Bun.file(path)
-						const exists = await file.exists()
-						if (!exists) {
-							throw new Error(`File not found: ${path}`)
-						}
-						return await file.json()
-					},
-					catch: () => new FileNotFoundError({ path }),
-				}),
-
 			writeJSON: <T = unknown>(path: string, data: T) =>
 				Effect.tryPromise({
 					try: () => Bun.write(path, JSON.stringify(data, null, 2) + "\n"),
@@ -111,22 +126,29 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 						}),
 				}),
 
-			deleteFile: (path: string) =>
+			moveDirectory: (from: string, to: string) =>
 				Effect.tryPromise({
-					try: () => unlink(path),
+					try: () => rename(from, to),
 					catch: (error) =>
 						new FileSystemError({
-							message: `Failed to delete file: ${path}`,
+							message: `Failed to move directory from ${from} to ${to}`,
 							cause: error,
 						}),
 				}),
 
-			copyFile: (from: string, to: string) =>
+			readDirectory: (path: string) =>
 				Effect.tryPromise({
-					try: () => fsCopyFile(from, to),
+					try: async () => {
+						const entries = await readdir(path, { withFileTypes: true })
+						return entries.map((entry) => ({
+							name: entry.name,
+							isDirectory: entry.isDirectory(),
+							isSymlink: entry.isSymbolicLink(),
+						}))
+					},
 					catch: (error) =>
 						new FileSystemError({
-							message: `Failed to copy file from ${from} to ${to}`,
+							message: `Failed to read directory: ${path}`,
 							cause: error,
 						}),
 				}),
@@ -158,15 +180,16 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 				options?: {
 					readonly cwd?: string
 					readonly captureOutput?: boolean
-					readonly interactive?: boolean
+					readonly env?: Record<string, string>
 				},
 			) =>
 				pipe(
 					spawnProcess(args, {
 						cwd: options?.cwd,
-						stdin: options?.interactive ? "inherit" : "pipe",
+						stdin: "pipe",
 						stdout: options?.captureOutput ? "pipe" : "inherit",
-						stderr: options?.interactive ? "inherit" : "pipe",
+						stderr: "pipe",
+						env: options?.env,
 					}),
 					Effect.mapError(
 						(processError) =>
@@ -177,70 +200,16 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 					),
 				),
 
-			/**
-			 * Recursively collect all files in a directory.
-			 * Returns paths relative to the directory (or relativeTo if specified).
-			 */
-			collectFiles: (
-				dirPath: string,
-				options?: {
-					readonly relativeTo?: string
-					readonly exclude?: readonly string[]
-					readonly sort?: boolean
-				},
-			) =>
+			createSymlink: (target: string, path: string) =>
 				Effect.tryPromise({
-					try: async () => {
-						const { relativeTo, exclude = [], sort = false } = options ?? {}
-						const basePath = relativeTo ?? dirPath
-
-						// Build find command with exclusions
-						const findArgs = ["find", dirPath, "-type", "f"]
-						for (const pattern of exclude) {
-							findArgs.push("!", "-name", pattern)
-						}
-
-						const result = Bun.spawnSync(findArgs, {
-							stdout: "pipe",
-							stderr: "ignore",
-						})
-
-						const output = new TextDecoder().decode(result.stdout)
-						if (!output) {
-							return []
-						}
-
-						const files = output
-							.trim()
-							.split("\n")
-							.filter((f: string) => f.length > 0)
-							.map((file) => file.replace(basePath + "/", ""))
-							.filter((f) => f.length > 0)
-
-						return sort ? files.sort() : files
-					},
+					try: () => symlink(target, path, "dir"),
 					catch: (error) =>
 						new FileSystemError({
-							message: `Failed to collect files from ${dirPath}`,
+							message: `Failed to create symlink ${path} -> ${target}`,
 							cause: error,
 						}),
 				}),
 
-			/**
-			 * Check if a path is a symbolic link.
-			 * Returns false if the file doesn't exist or if it's not a symlink.
-			 */
-			isSymlink: (path: string) =>
-				Effect.tryPromise({
-					try: async () => {
-						const stats = await lstat(path)
-						return stats.isSymbolicLink()
-					},
-					catch: () =>
-						// If we can't lstat, it's not a symlink (or doesn't exist)
-						false,
-				}).pipe(Effect.catchAll(() => Effect.succeed(false))),
-
 			/**
 			 * Read the target of a symbolic link.
 			 * Returns null if the file is not a symlink or doesn't exist.