@markjaquith/agency 1.11.0 → 2.0.0

package/src/utils/command.ts

@@ -4,14 +4,10 @@
 export interface BaseCommandOptions {
 	readonly silent?: boolean
 	readonly verbose?: boolean
+	readonly json?: boolean
 	/**
 	 * Working directory to use instead of process.cwd().
 	 * Primarily used for testing to enable concurrent test execution.
 	 */
 	readonly cwd?: string
-	/**
-	 * Agency config directory to use instead of AGENCY_CONFIG_DIR env var.
-	 * Primarily used for testing to enable concurrent test execution.
-	 */
-	readonly configDir?: string
 }

package/src/utils/effect.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test"
+import { captureLogs } from "../test-utils"
+import { createLoggers } from "./effect"
+
+describe("createLoggers", () => {
+	test("keeps JSON output machine-readable when verbose is enabled", async () => {
+		const logs = await captureLogs(async () => {
+			const { log, verboseLog } = createLoggers({ json: true, verbose: true })
+			verboseLog("debug")
+			log('{"ok":true}')
+		})
+
+		expect(logs).toEqual(['{"ok":true}'])
+	})
+
+	test("lets silent suppress JSON output", async () => {
+		const logs = await captureLogs(async () => {
+			const { log } = createLoggers({ json: true, silent: true })
+			log('{"ok":true}')
+		})
+
+		expect(logs).toEqual([])
+	})
+})

package/src/utils/effect.ts

@@ -1,281 +1,11 @@
-import { Effect } from "effect"
-import { GitService } from "../services/GitService"
-import { getBaseBranchFromMetadata } from "../types"
-import highlight from "./colors"
-
-/**
- * Ensure a branch exists, failing with an error if it doesn't
- */
-export function ensureBranchExists(
-	gitRoot: string,
-	branch: string,
-	errorMessage?: string,
-) {
-	return Effect.gen(function* () {
-		const git = yield* GitService
-		const exists = yield* git.branchExists(gitRoot, branch)
-		if (!exists) {
-			return yield* Effect.fail(
-				new Error(
-					errorMessage ?? `Branch ${highlight.branch(branch)} does not exist`,
-				),
-			)
-		}
-	})
-}
-
-/**
- * Create logging functions based on options
- */
 export function createLoggers(options: {
 	readonly silent?: boolean
 	readonly verbose?: boolean
+	readonly json?: boolean
 }) {
-	const { silent = false, verbose = false } = options
+	const { silent = false, verbose = false, json = false } = options
 	return {
 		log: silent ? () => {} : console.log,
-		verboseLog: verbose && !silent ? console.log : () => {},
+		verboseLog: verbose && !silent && !json ? console.log : () => {},
 	}
 }
-
-/**
- * Ensure we're in a git repository and return the git root
- * @param providedCwd - Optional working directory to use instead of process.cwd()
- */
-export function ensureGitRepo(providedCwd?: string) {
-	return Effect.gen(function* () {
-		const git = yield* GitService
-		const cwd = providedCwd ?? process.cwd()
-
-		const isGitRepo = yield* git.isInsideGitRepo(cwd)
-		if (!isGitRepo) {
-			return yield* Effect.fail(
-				new Error(
-					"Not in a git repository. Please run this command inside a git repo.",
-				),
-			)
-		}
-
-		return yield* git.getGitRoot(cwd)
-	})
-}
-
-/**
- * Get the configured template name for the current repository
- */
-export function getTemplateName(gitRoot: string) {
-	return Effect.flatMap(GitService, (git) =>
-		git.getGitConfig("agency.template", gitRoot),
-	)
-}
-
-/**
- * Resolve base branch with fallback chain:
- * 1. Explicitly provided base branch
- * 2. Branch-specific base branch from agency.json
- * 3. Repository-level default base branch from git config
- * 4. Auto-detected from origin/HEAD or common branches
- */
-export function resolveBaseBranch(
-	gitRoot: string,
-	providedBaseBranch?: string,
-) {
-	return Effect.gen(function* () {
-		const git = yield* GitService
-
-		// If explicitly provided, use it
-		if (providedBaseBranch) {
-			yield* ensureBranchExists(gitRoot, providedBaseBranch)
-			return providedBaseBranch
-		}
-
-		// Check if we have a branch-specific base branch in agency.json
-		const savedBaseBranch = yield* Effect.tryPromise({
-			try: () => getBaseBranchFromMetadata(gitRoot),
-			catch: (error) =>
-				new Error(`Failed to get base branch from metadata: ${error}`),
-		})
-		if (savedBaseBranch) {
-			const exists = yield* git.branchExists(gitRoot, savedBaseBranch)
-			if (exists) {
-				return savedBaseBranch
-			}
-		}
-
-		// Check for repository-level default base branch in git config
-		const defaultBaseBranch = yield* git.getDefaultBaseBranchConfig(gitRoot)
-		if (defaultBaseBranch) {
-			const exists = yield* git.branchExists(gitRoot, defaultBaseBranch)
-			if (exists) {
-				return defaultBaseBranch
-			}
-		}
-
-		// Try to auto-detect the default remote branch
-		const defaultRemote = yield* git.getDefaultRemoteBranch(gitRoot)
-		if (defaultRemote) {
-			const exists = yield* git.branchExists(gitRoot, defaultRemote)
-			if (exists) {
-				return defaultRemote
-			}
-		}
-
-		// Try common base branches in order, using resolved remote
-		const remote = yield* git
-			.resolveRemote(gitRoot)
-			.pipe(Effect.catchAll(() => Effect.succeed(null)))
-
-		const commonBases: string[] = []
-		if (remote) {
-			commonBases.push(`${remote}/main`, `${remote}/master`)
-		}
-		commonBases.push("main", "master")
-
-		for (const base of commonBases) {
-			const exists = yield* git.branchExists(gitRoot, base)
-			if (exists) {
-				return base
-			}
-		}
-
-		// Could not auto-detect, require explicit specification
-		return yield* Effect.fail(
-			new Error(
-				"Could not auto-detect base branch. Please specify one explicitly with the --base-branch option or configure one with: agency base set <branch>",
-			),
-		)
-	})
-}
-
-/**
- * Get base branch from agency.json metadata as an Effect
- */
-export function getBaseBranchFromMetadataEffect(gitRoot: string) {
-	return Effect.tryPromise({
-		try: () => getBaseBranchFromMetadata(gitRoot),
-		catch: (error) =>
-			new Error(`Failed to get base branch from metadata: ${error}`),
-	})
-}
-
-/**
- * Get base branch from agency.json on a specific branch without checking it out.
- * Uses git show to read the file contents directly.
- */
-export function getBaseBranchFromBranch(gitRoot: string, branch: string) {
-	return Effect.gen(function* () {
-		const git = yield* GitService
-
-		// Use git show to read agency.json from the branch
-		const content = yield* git.getFileAtRef(gitRoot, branch, "agency.json")
-
-		if (!content) {
-			return null
-		}
-
-		// Parse the content
-		const data = yield* Effect.try({
-			try: () => JSON.parse(content),
-			catch: () => null,
-		}).pipe(Effect.catchAll(() => Effect.succeed(null)))
-
-		if (!data || typeof data !== "object") {
-			return null
-		}
-
-		return (data as { baseBranch?: string }).baseBranch || null
-	}).pipe(Effect.catchAll(() => Effect.succeed(null)))
-}
-
-/**
- * Get the configured remote name with fallback to auto-detection
- */
-export function getRemoteName(gitRoot: string) {
-	return Effect.gen(function* () {
-		const git = yield* GitService
-
-		// Use the new centralized resolveRemote method
-		// This already handles config checking and auto-detection with smart precedence
-		const remote = yield* git.resolveRemote(gitRoot)
-
-		return remote
-	})
-}
-
-/**
- * Execute an operation that may change branches, with automatic cleanup on interrupt.
- * This ensures that if Ctrl-C is pressed during an operation that changes branches,
- * the user is returned to their original branch.
- *
- * @param gitRoot - The git repository root
- * @param operation - The Effect operation to run
- * @returns The result of the operation
- */
-export function withBranchProtection<A, E, R>(
-	gitRoot: string,
-	operation: Effect.Effect<A, E, R>,
-) {
-	return Effect.gen(function* () {
-		const git = yield* GitService
-
-		// Store the original branch before any operations
-		const originalBranch = yield* git.getCurrentBranch(gitRoot)
-
-		// Set up SIGINT handler to restore branch on interrupt
-		let interrupted = false
-		const originalSigintHandler = process.listeners("SIGINT")
-
-		const cleanup = async () => {
-			if (interrupted) return
-			interrupted = true
-
-			// Restore original SIGINT handlers
-			process.removeAllListeners("SIGINT")
-			for (const handler of originalSigintHandler) {
-				process.on("SIGINT", handler as NodeJS.SignalsListener)
-			}
-
-			// Try to restore the original branch
-			try {
-				const currentBranch = await Effect.runPromise(
-					git
-						.getCurrentBranch(gitRoot)
-						.pipe(Effect.provide(GitService.Default)),
-				)
-
-				if (currentBranch !== originalBranch) {
-					await Effect.runPromise(
-						git
-							.checkoutBranch(gitRoot, originalBranch)
-							.pipe(Effect.provide(GitService.Default)),
-					)
-					console.error(`\nInterrupted. Restored to branch: ${originalBranch}`)
-				}
-			} catch {
-				console.error(
-					`\nInterrupted. Could not restore branch. You may need to run: git checkout ${originalBranch}`,
-				)
-			}
-
-			// Exit the process
-			process.exit(130) // Standard exit code for SIGINT
-		}
-
-		// Install our SIGINT handler
-		process.removeAllListeners("SIGINT")
-		process.on("SIGINT", cleanup)
-
-		// Run the operation
-		const result = yield* Effect.onExit(operation, () =>
-			Effect.sync(() => {
-				// Restore original SIGINT handlers when operation completes
-				process.removeAllListeners("SIGINT")
-				for (const handler of originalSigintHandler) {
-					process.on("SIGINT", handler as NodeJS.SignalsListener)
-				}
-			}),
-		)
-
-		return result
-	})
-}

package/src/utils/process.test.ts

@@ -23,19 +23,4 @@ describe("spawnProcess", () => {
 		expect(result.stderr).toContain("err:0:")
 		expect(result.stderr).toContain("err:1999:")
 	})
-
-	test("reports progress while process is still running", async () => {
-		const progress: number[] = []
-		const script = "await new Promise((resolve) => setTimeout(resolve, 80))"
-
-		const result = await Effect.runPromise(
-			spawnProcess([process.execPath, "-e", script], {
-				onProgress: ({ elapsedMs }) => progress.push(elapsedMs),
-				progressIntervalMs: 10,
-			}),
-		)
-
-		expect(result.exitCode).toBe(0)
-		expect(progress.length).toBeGreaterThan(0)
-	})
 })

package/src/utils/process.ts

@@ -18,11 +18,6 @@ interface SpawnOptions {
 	readonly stdout?: "pipe" | "inherit"
 	readonly stderr?: "pipe" | "inherit"
 	readonly env?: Record<string, string>
-	readonly onProgress?: (progress: {
-		readonly elapsedMs: number
-		readonly pid?: number
-	}) => void
-	readonly progressIntervalMs?: number
 }
 
 /**
@@ -59,18 +54,6 @@ export const spawnProcess = (
 				stderr: options?.stderr ?? "pipe",
 				env: options?.env ? { ...process.env, ...options.env } : process.env,
 			})
-			const startedAt = Date.now()
-			const progressInterval = options?.onProgress
-				? setInterval(
-						() =>
-							options.onProgress?.({
-								elapsedMs: Date.now() - startedAt,
-								pid: proc.pid,
-							}),
-						options.progressIntervalMs ?? 10_000,
-					)
-				: null
-
 			// Start draining stdout/stderr immediately so verbose subprocesses
 			// cannot block on filled pipe buffers before they exit.
 			const stdoutPromise =
@@ -86,11 +69,7 @@ export const spawnProcess = (
 				proc.exited,
 				stdoutPromise,
 				stderrPromise,
-			]).finally(() => {
-				if (progressInterval) {
-					clearInterval(progressInterval)
-				}
-			})
+			])
 
 			return {
 				stdout: stdout.trim(),
@@ -106,41 +85,3 @@ export const spawnProcess = (
 				stderr: error instanceof Error ? error.message : String(error),
 			}),
 	})
-
-/**
- * Helper to check exit code and return stdout on success
- */
-export const checkExitCodeAndReturnStdout =
-	<E>(errorMapper: (result: ProcessResult) => E) =>
-	(result: ProcessResult): Effect.Effect<string, E> =>
-		result.exitCode === 0
-			? Effect.succeed(result.stdout)
-			: Effect.fail(errorMapper(result))
-
-/**
- * Helper to check exit code and return void on success
- */
-export const checkExitCodeAndReturnVoid =
-	<E>(errorMapper: (result: ProcessResult) => E) =>
-	(result: ProcessResult): Effect.Effect<void, E> =>
-		result.exitCode === 0 ? Effect.void : Effect.fail(errorMapper(result))
-
-/**
- * Helper to create an error mapper function for a specific error type
- * This is useful for wrapping spawnProcess with domain-specific error types
- */
-export const createErrorMapper =
-	<E extends { command: string; exitCode: number; stderr: string }>(
-		ErrorConstructor: new (args: {
-			command: string
-			exitCode: number
-			stderr: string
-		}) => E,
-	) =>
-	(args: readonly string[]) =>
-	(result: ProcessResult): E =>
-		new ErrorConstructor({
-			command: args.join(" "),
-			exitCode: result.exitCode,
-			stderr: result.stderr,
-		})

package/src/workbase/frontmatter.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { parseFrontmatter } from "./frontmatter"
+
+describe("parseFrontmatter", () => {
+	test("parses YAML 1.2 frontmatter and body", async () => {
+		const parsed = await Effect.runPromise(
+			parseFrontmatter(
+				"---\nrepo: agency\npr: null\n---\n\n# Task\n",
+				"TASK.md",
+			),
+		)
+
+		expect(parsed.data).toEqual({ repo: "agency", pr: null })
+		expect(parsed.body).toBe("\n# Task\n")
+	})
+
+	test("rejects duplicate keys", async () => {
+		await expect(
+			Effect.runPromise(
+				parseFrontmatter("---\nrepo: agency\nrepo: effect\n---\n", "TASK.md"),
+			),
+		).rejects.toThrow("Map keys must be unique")
+	})
+
+	test("rejects anchors and aliases", async () => {
+		await expect(
+			Effect.runPromise(
+				parseFrontmatter(
+					"---\nrepo: &repo agency\nrepos:\n  - *repo\n---\n",
+					"TASK.md",
+				),
+			),
+		).rejects.toThrow("not supported")
+	})
+
+	test("rejects custom tags", async () => {
+		await expect(
+			Effect.runPromise(
+				parseFrontmatter("---\nrepo: !custom agency\n---\n", "TASK.md"),
+			),
+		).rejects.toThrow()
+	})
+
+	test("requires frontmatter at the start of the document", async () => {
+		await expect(
+			Effect.runPromise(parseFrontmatter("# Task\n", "TASK.md")),
+		).rejects.toThrow("must begin with YAML frontmatter")
+	})
+})

package/src/workbase/frontmatter.ts

@@ -0,0 +1,77 @@
+import { Data, Effect } from "effect"
+import { parseDocument, stringify, visit } from "yaml"
+
+class FrontmatterParseError extends Data.TaggedError("FrontmatterParseError")<{
+	readonly path: string
+	readonly message: string
+	readonly cause?: unknown
+}> {}
+
+interface ParsedFrontmatter {
+	readonly data: unknown
+	readonly body: string
+}
+
+export const parseFrontmatter = (content: string, path: string) =>
+	Effect.try({
+		try: (): ParsedFrontmatter => {
+			const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)
+			if (!match) {
+				throw new Error("Markdown file must begin with YAML frontmatter")
+			}
+
+			const document = parseDocument(match[1]!, {
+				customTags: [],
+				merge: false,
+				schema: "core",
+				strict: true,
+				uniqueKeys: true,
+				version: "1.2",
+			})
+
+			const parseMessages = [...document.errors, ...document.warnings]
+			if (parseMessages.length > 0) {
+				throw new Error(parseMessages.map((error) => error.message).join("; "))
+			}
+
+			let unsupportedFeature: string | null = null
+			visit(document, {
+				Alias: () => {
+					unsupportedFeature = "YAML aliases are not supported"
+				},
+				Node: (_key, node) => {
+					if (node.anchor) {
+						unsupportedFeature = "YAML anchors are not supported"
+					} else if (node.tag && !node.tag.startsWith("tag:yaml.org,2002:")) {
+						unsupportedFeature = "Custom YAML tags are not supported"
+					}
+				},
+			})
+
+			if (unsupportedFeature) {
+				throw new Error(unsupportedFeature)
+			}
+
+			const data = document.toJS({ maxAliasCount: 0 })
+			if (data === null || typeof data !== "object" || Array.isArray(data)) {
+				throw new Error("YAML frontmatter must be a mapping")
+			}
+
+			return {
+				data,
+				body: content.slice(match[0].length),
+			}
+		},
+		catch: (cause) =>
+			new FrontmatterParseError({
+				path,
+				message:
+					cause instanceof Error
+						? cause.message
+						: "Failed to parse frontmatter",
+				cause,
+			}),
+	})
+
+export const formatMarkdownDocument = (data: object, body: string) =>
+	`---\n${stringify(data, { lineWidth: 0 }).trimEnd()}\n---\n\n${body.trim()}\n`

package/src/workbase/repository-reference.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test"
+import { parseRepositoryReferences } from "./repository-reference"
+
+describe("repository references", () => {
+	test("parses alias and ref CLI values", () => {
+		expect(parseRepositoryReferences(["web:origin/main"])[0]).toEqual({
+			repo: "web",
+			ref: "origin/main",
+		})
+		expect(
+			parseRepositoryReferences(["web:main", "zenpayroll:v1.2.3"]),
+		).toEqual([
+			{ repo: "web", ref: "main" },
+			{ repo: "zenpayroll", ref: "v1.2.3" },
+		])
+	})
+
+	test("rejects references without both parts", () => {
+		for (const value of ["web", ":main", "web:"]) {
+			expect(() => parseRepositoryReferences([value])).toThrow(
+				"expected <alias>:<ref>",
+			)
+		}
+	})
+})

package/src/workbase/repository-reference.ts

@@ -0,0 +1,18 @@
+import type { RepositoryReference } from "./schemas"
+
+const parseRepositoryReference = (value: string): RepositoryReference => {
+	const separator = value.indexOf(":")
+	if (separator <= 0 || separator === value.length - 1) {
+		throw new Error(
+			`Invalid repository reference '${value}'; expected <alias>:<ref>`,
+		)
+	}
+
+	return {
+		repo: value.slice(0, separator),
+		ref: value.slice(separator + 1),
+	}
+}
+
+export const parseRepositoryReferences = (values: readonly string[] = []) =>
+	values.map(parseRepositoryReference)