@markjaquith/agency 0.5.0

package/src/utils/pr-branch.ts

@@ -0,0 +1,473 @@
+/**
+ * Utilities for working with source and emit branch names and patterns
+ */
+
+import { Effect, pipe } from "effect"
+import { FileSystemService } from "../services/FileSystemService"
+import { GitService } from "../services/GitService"
+import {
+	AgencyMetadataService,
+	AgencyMetadataServiceLive,
+} from "../services/AgencyMetadataService"
+import { AgencyMetadata } from "../schemas"
+import { Schema } from "@effect/schema"
+
+/**
+ * Generate a source branch name by applying a pattern to a clean branch name.
+ * If pattern contains %branch%, it replaces it with the branch name.
+ * Otherwise, treats the pattern as a prefix.
+ *
+ * @example
+ * makeSourceBranchName("main", "agency/%branch%") // "agency/main"
+ * makeSourceBranchName("feature-foo", "wip/%branch%") // "wip/feature-foo"
+ * makeSourceBranchName("main", "agency/") // "agency/main"
+ */
+export function makeSourceBranchName(
+	cleanBranch: string,
+	pattern: string,
+): string {
+	if (pattern.includes("%branch%")) {
+		return pattern.replace("%branch%", cleanBranch)
+	}
+
+	// If no %branch% placeholder, treat pattern as prefix
+	return pattern + cleanBranch
+}
+
+/**
+ * Extract the clean branch name from a source branch name using a pattern.
+ * Returns null if the source branch name doesn't match the pattern.
+ *
+ * @example
+ * extractCleanBranch("agency/main", "agency/%branch%") // "main"
+ * extractCleanBranch("wip/feature-foo", "wip/%branch%") // "feature-foo"
+ * extractCleanBranch("agency/main", "agency/") // "main"
+ * extractCleanBranch("main", "agency/%branch%") // null
+ */
+export function extractCleanBranch(
+	sourceBranchName: string,
+	pattern: string,
+): string | null {
+	if (pattern.includes("%branch%")) {
+		// Split pattern into prefix and suffix around %branch%
+		const parts = pattern.split("%branch%")
+		if (parts.length !== 2) return null
+
+		const prefix = parts[0]!
+		const suffix = parts[1]!
+
+		// Check if source branch name matches the pattern
+		if (
+			!sourceBranchName.startsWith(prefix) ||
+			!sourceBranchName.endsWith(suffix)
+		) {
+			return null
+		}
+
+		// Extract the clean branch name by removing prefix and suffix
+		const cleanBranch = sourceBranchName.slice(
+			prefix.length,
+			sourceBranchName.length - suffix.length,
+		)
+
+		// Ensure we extracted something (not empty string)
+		return cleanBranch.length > 0 ? cleanBranch : null
+	} else {
+		// Pattern is a prefix - check if branch starts with it
+		if (!sourceBranchName.startsWith(pattern)) {
+			return null
+		}
+
+		const cleanBranch = sourceBranchName.slice(pattern.length)
+		return cleanBranch.length > 0 ? cleanBranch : null
+	}
+}
+
+/**
+ * Generate an emit branch name from a clean branch name and emit pattern.
+ * If pattern is "%branch%", returns the clean branch name unchanged.
+ * Otherwise, applies the pattern the same way as makeSourceBranchName.
+ *
+ * @example
+ * makeEmitBranchName("main", "%branch%") // "main"
+ * makeEmitBranchName("feature-foo", "%branch%--PR") // "feature-foo--PR"
+ * makeEmitBranchName("feature-foo", "PR/%branch%") // "PR/feature-foo"
+ */
+export function makeEmitBranchName(
+	cleanBranch: string,
+	emitPattern: string,
+): string {
+	// Special case: "%branch%" means use clean branch name as-is
+	if (emitPattern === "%branch%") {
+		return cleanBranch
+	}
+
+	if (emitPattern.includes("%branch%")) {
+		return emitPattern.replace("%branch%", cleanBranch)
+	}
+
+	// If no %branch% placeholder, treat pattern as suffix
+	return cleanBranch + emitPattern
+}
+
+/**
+ * Extract the clean branch name from an emit branch name using an emit pattern.
+ * Returns null if the emit branch name doesn't match the pattern.
+ *
+ * @example
+ * extractCleanFromEmit("main", "%branch%") // "main"
+ * extractCleanFromEmit("feature-foo--PR", "%branch%--PR") // "feature-foo"
+ * extractCleanFromEmit("PR/feature-foo", "PR/%branch%") // "feature-foo"
+ * extractCleanFromEmit("main", "%branch%--PR") // null
+ */
+export function extractCleanFromEmit(
+	emitBranchName: string,
+	emitPattern: string,
+): string | null {
+	// Special case: "%branch%" means emit branch is the clean branch name
+	if (emitPattern === "%branch%") {
+		return emitBranchName
+	}
+
+	if (emitPattern.includes("%branch%")) {
+		// Split pattern into prefix and suffix around %branch%
+		const parts = emitPattern.split("%branch%")
+		if (parts.length !== 2) return null
+
+		const prefix = parts[0]!
+		const suffix = parts[1]!
+
+		// Check if emit branch name matches the pattern
+		if (
+			!emitBranchName.startsWith(prefix) ||
+			!emitBranchName.endsWith(suffix)
+		) {
+			return null
+		}
+
+		// Extract the clean branch name by removing prefix and suffix
+		const cleanBranch = emitBranchName.slice(
+			prefix.length,
+			emitBranchName.length - suffix.length,
+		)
+
+		// Ensure we extracted something (not empty string)
+		return cleanBranch.length > 0 ? cleanBranch : null
+	} else {
+		// Pattern is a suffix - check if branch ends with it
+		if (!emitBranchName.endsWith(emitPattern)) {
+			return null
+		}
+
+		const cleanBranch = emitBranchName.slice(0, -emitPattern.length)
+		return cleanBranch.length > 0 ? cleanBranch : null
+	}
+}
+
+/**
+ * Result of resolving a branch pair (source and emit branches).
+ */
+export interface BranchPair {
+	/** The source branch name (with source pattern applied) */
+	sourceBranch: string
+	/** The emit branch name (clean or with emit pattern) */
+	emitBranch: string
+	/** Whether the current branch is the emit branch */
+	isOnEmitBranch: boolean
+}
+
+/**
+ * Resolve the source and emit branch names from a current branch and patterns.
+ * This determines whether we're on an emit branch or source branch and provides
+ * both branch names.
+ *
+ * @example
+ * resolveBranchPair("agency/main", "agency/%branch%", "%branch%")
+ * // { sourceBranch: "agency/main", emitBranch: "main", isOnEmitBranch: false }
+ *
+ * resolveBranchPair("main", "agency/%branch%", "%branch%")
+ * // { sourceBranch: "agency/main", emitBranch: "main", isOnEmitBranch: true }
+ */
+function resolveBranchPair(
+	currentBranch: string,
+	sourcePattern: string,
+	emitPattern: string,
+): BranchPair {
+	// First, try to extract clean branch from source pattern
+	const cleanFromSource = extractCleanBranch(currentBranch, sourcePattern)
+
+	if (cleanFromSource) {
+		// Current branch is a source branch (matches source pattern)
+		return {
+			sourceBranch: currentBranch,
+			emitBranch: makeEmitBranchName(cleanFromSource, emitPattern),
+			isOnEmitBranch: false,
+		}
+	}
+
+	// If emit pattern is not just "%branch%" (which would match anything),
+	// check if current branch matches the emit pattern
+	if (emitPattern !== "%branch%") {
+		const cleanFromEmit = extractCleanFromEmit(currentBranch, emitPattern)
+
+		if (cleanFromEmit) {
+			// Current branch is an emit branch (matches emit pattern)
+			return {
+				sourceBranch: makeSourceBranchName(cleanFromEmit, sourcePattern),
+				emitBranch: currentBranch,
+				isOnEmitBranch: true,
+			}
+		}
+	}
+
+	// If neither pattern matches (or emit pattern is "%branch%"), this is a
+	// "legacy" branch that doesn't follow the new naming convention.
+	// Treat it as a source branch where the branch name itself is the clean name.
+	return {
+		sourceBranch: currentBranch,
+		emitBranch: makeEmitBranchName(currentBranch, emitPattern),
+		isOnEmitBranch: false,
+	}
+}
+
+/**
+ * Effect-based utilities for resolving branch pairs using agency.json
+ */
+
+/**
+ * Try to read agency.json from the git root on a specific branch.
+ * Returns the metadata if found, null otherwise.
+ */
+const readAgencyJsonFromBranch = (
+	gitRoot: string,
+	branch: string,
+): Effect.Effect<
+	AgencyMetadata | null,
+	never,
+	GitService | FileSystemService
+> =>
+	Effect.gen(function* () {
+		const metadataService = yield* AgencyMetadataService
+		return yield* metadataService.readFromBranch(gitRoot, branch)
+	}).pipe(Effect.provide(AgencyMetadataServiceLive))
+
+/**
+ * Get the agency.json metadata from the current branch (if it exists).
+ */
+const getCurrentBranchAgencyJson = (
+	gitRoot: string,
+): Effect.Effect<
+	AgencyMetadata | null,
+	never,
+	FileSystemService | GitService
+> =>
+	Effect.gen(function* () {
+		const metadataService = yield* AgencyMetadataService
+		return yield* metadataService.readFromDisk(gitRoot)
+	}).pipe(Effect.provide(AgencyMetadataServiceLive))
+
+/**
+ * Find the source branch by searching all branches for an agency.json
+ * with a matching emitBranch value.
+ */
+const findSourceBranchByEmitBranch = (
+	gitRoot: string,
+	currentBranch: string,
+): Effect.Effect<string | null, never, GitService | FileSystemService> =>
+	Effect.gen(function* () {
+		const git = yield* GitService
+
+		// Get all local branches
+		const branchesResult = yield* pipe(
+			git.runGitCommand(
+				["git", "branch", "--format=%(refname:short)"],
+				gitRoot,
+				{
+					captureOutput: true,
+				},
+			),
+			Effect.catchAll(() => Effect.succeed({ exitCode: 1, stdout: "" })),
+		)
+
+		if (branchesResult.exitCode !== 0 || !branchesResult.stdout) {
+			return null
+		}
+
+		const branches = branchesResult.stdout
+			.split("\n")
+			.map((b) => b.trim())
+			.filter((b) => b.length > 0 && b !== currentBranch)
+
+		// Search each branch for agency.json with matching emitBranch
+		for (const branch of branches) {
+			const metadata = yield* readAgencyJsonFromBranch(gitRoot, branch)
+
+			if (metadata?.emitBranch === currentBranch) {
+				return branch
+			}
+		}
+
+		return null
+	})
+
+/**
+ * Strategy 1: Try to resolve branch pair from current branch's agency.json.
+ * If current branch has agency.json with emitBranch that differs from current branch,
+ * we're on a source branch. If emitBranch equals current branch, we're on the emit branch.
+ */
+const tryResolveFromCurrentAgencyJson = (
+	gitRoot: string,
+	currentBranch: string,
+): Effect.Effect<BranchPair | null, never, GitService | FileSystemService> =>
+	Effect.gen(function* () {
+		const currentMetadata = yield* getCurrentBranchAgencyJson(gitRoot)
+
+		if (currentMetadata?.emitBranch) {
+			// If emitBranch equals current branch, we're actually ON the emit branch,
+			// not the source branch. This can happen when skipFilter is used in tests
+			// and the agency.json is copied to the emit branch with emitBranch intact.
+			if (currentMetadata.emitBranch === currentBranch) {
+				// Return null to let Strategy 2 find the actual source branch
+				return null
+			}
+			return {
+				sourceBranch: currentBranch,
+				emitBranch: currentMetadata.emitBranch,
+				isOnEmitBranch: false,
+			}
+		}
+
+		return null
+	})
+
+/**
+ * Strategy 2: Search other branches for agency.json with matching emitBranch.
+ * If found, we're on an emit branch.
+ */
+const tryResolveFromOtherBranchAgencyJson = (
+	gitRoot: string,
+	currentBranch: string,
+): Effect.Effect<BranchPair | null, never, GitService | FileSystemService> =>
+	Effect.gen(function* () {
+		const sourceBranch = yield* findSourceBranchByEmitBranch(
+			gitRoot,
+			currentBranch,
+		)
+
+		if (sourceBranch) {
+			return {
+				sourceBranch,
+				emitBranch: currentBranch,
+				isOnEmitBranch: true,
+			}
+		}
+
+		return null
+	})
+
+/**
+ * Strategy 3: For clean emit patterns ("%branch%"), check if a patterned source branch exists.
+ * If so, we're on an emit branch.
+ */
+const tryResolveFromPatternedSourceBranch = (
+	gitRoot: string,
+	currentBranch: string,
+	sourcePattern: string,
+	emitPattern: string,
+): Effect.Effect<BranchPair | null, never, GitService | FileSystemService> =>
+	Effect.gen(function* () {
+		// Only applies when emit pattern is "%branch%" (clean emit branches)
+		if (emitPattern !== "%branch%") {
+			return null
+		}
+
+		const git = yield* GitService
+		const possibleSourceBranch = makeSourceBranchName(
+			currentBranch,
+			sourcePattern,
+		)
+
+		const sourceExists = yield* pipe(
+			git.branchExists(gitRoot, possibleSourceBranch),
+			Effect.catchAll(() => Effect.succeed(false)),
+		)
+
+		if (sourceExists) {
+			return {
+				sourceBranch: possibleSourceBranch,
+				emitBranch: currentBranch,
+				isOnEmitBranch: true,
+			}
+		}
+
+		return null
+	})
+
+/**
+ * Resolve branch pair using agency.json as the first source of truth,
+ * falling back to pattern-based resolution.
+ *
+ * Resolution strategies (in priority order):
+ * 1. Current branch has agency.json with emitBranch -> we're on source branch
+ * 2. Another branch has agency.json pointing to current branch -> we're on emit branch
+ * 3. Clean emit pattern and patterned source branch exists -> we're on emit branch
+ * 4. Fall back to pattern-based resolution
+ */
+export const resolveBranchPairWithAgencyJson = (
+	gitRoot: string,
+	currentBranch: string,
+	sourcePattern: string,
+	emitPattern: string,
+): Effect.Effect<BranchPair, never, GitService | FileSystemService> =>
+	Effect.gen(function* () {
+		// Strategy 1: Check current branch's agency.json
+		const fromCurrentAgencyJson = yield* tryResolveFromCurrentAgencyJson(
+			gitRoot,
+			currentBranch,
+		)
+		if (fromCurrentAgencyJson) {
+			return fromCurrentAgencyJson
+		}
+
+		// Strategy 2: Search other branches for matching agency.json
+		const fromOtherBranchAgencyJson =
+			yield* tryResolveFromOtherBranchAgencyJson(gitRoot, currentBranch)
+		if (fromOtherBranchAgencyJson) {
+			return fromOtherBranchAgencyJson
+		}
+
+		// Strategy 3: Check for patterned source branch (clean emit patterns only)
+		const fromPatternedSource = yield* tryResolveFromPatternedSourceBranch(
+			gitRoot,
+			currentBranch,
+			sourcePattern,
+			emitPattern,
+		)
+		if (fromPatternedSource) {
+			return fromPatternedSource
+		}
+
+		// Strategy 4: Fall back to pattern-based resolution
+		return resolveBranchPair(currentBranch, sourcePattern, emitPattern)
+	})
+
+// Legacy function names for backward compatibility
+// These will be updated as we migrate the codebase
+
+/**
+ * @deprecated Use makeEmitBranchName instead. This function now creates emit branches,
+ * not PR branches with suffixes.
+ */
+export function makePrBranchName(branchName: string, pattern: string): string {
+	return makeEmitBranchName(branchName, pattern)
+}
+
+/**
+ * @deprecated Use extractCleanFromEmit instead. Extracts clean branch from emit branch.
+ */
+export function extractSourceBranch(
+	emitBranchName: string,
+	pattern: string,
+): string | null {
+	return extractCleanFromEmit(emitBranchName, pattern)
+}

package/src/utils/process.ts

@@ -0,0 +1,110 @@
+import { Effect, Data } from "effect"
+
+/**
+ * Result of a process execution
+ */
+interface ProcessResult {
+	readonly stdout: string
+	readonly stderr: string
+	readonly exitCode: number
+}
+
+/**
+ * Options for spawning a process
+ */
+interface SpawnOptions {
+	readonly cwd?: string
+	readonly stdout?: "pipe" | "inherit"
+	readonly stderr?: "pipe" | "inherit"
+	readonly env?: Record<string, string>
+}
+
+/**
+ * Generic error for process execution failures
+ */
+export class ProcessError extends Data.TaggedError("ProcessError")<{
+	command: string
+	exitCode: number
+	stderr: string
+}> {}
+
+/**
+ * Spawn a process with proper error handling and typed results.
+ * This is a low-level utility that returns raw process results.
+ * Use higher-level wrappers for specific error types.
+ */
+export const spawnProcess = (
+	args: readonly string[],
+	options?: SpawnOptions,
+): Effect.Effect<ProcessResult, ProcessError> =>
+	Effect.tryPromise({
+		try: async () => {
+			const proc = Bun.spawn([...args], {
+				cwd: options?.cwd ?? process.cwd(),
+				stdout: options?.stdout ?? "pipe",
+				stderr: options?.stderr ?? "pipe",
+				env: options?.env ? { ...process.env, ...options.env } : process.env,
+			})
+
+			await proc.exited
+
+			const stdout =
+				options?.stdout === "inherit"
+					? ""
+					: await new Response(proc.stdout).text()
+			const stderr =
+				options?.stderr === "inherit"
+					? ""
+					: await new Response(proc.stderr).text()
+
+			return {
+				stdout: stdout.trim(),
+				stderr: stderr.trim(),
+				exitCode: proc.exitCode ?? 0,
+			}
+		},
+		catch: (error) =>
+			new ProcessError({
+				command: args.join(" "),
+				exitCode: -1,
+				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/utils/spinner.ts

@@ -0,0 +1,82 @@
+import ora from "ora"
+import { Effect } from "effect"
+
+/**
+ * Check if we're running in a test environment
+ */
+const isTestEnvironment = (): boolean => {
+	return process.env.NODE_ENV === "test" || process.env.BUN_ENV === "test"
+}
+
+/**
+ * Configuration for a spinner operation
+ */
+interface SpinnerConfig {
+	/** The message to show while the spinner is running */
+	text: string
+	/** The message to show when the operation succeeds */
+	successText?: string
+	/** The message to show when the operation fails */
+	failText?: string
+	/** Whether the spinner is enabled (defaults to true) */
+	enabled?: boolean
+}
+
+/**
+ * Wraps an Effect operation with a spinner that shows progress
+ * and updates with success/failure messages.
+ *
+ * @param effect The Effect operation to run
+ * @param config Configuration for the spinner
+ * @returns The result of the Effect operation
+ *
+ * @example
+ * ```ts
+ * const result = yield* withSpinner(
+ *   someOperation(),
+ *   {
+ *     text: "Processing...",
+ *     successText: "Processing complete",
+ *     failText: "Processing failed"
+ *   }
+ * )
+ * ```
+ */
+export const withSpinner = <A, E, R>(
+	effect: Effect.Effect<A, E, R>,
+	config: SpinnerConfig,
+): Effect.Effect<A, E, R> => {
+	const { text, successText, failText, enabled = true } = config
+
+	// Disable spinner in test environment or when explicitly disabled
+	if (!enabled || isTestEnvironment()) {
+		return effect
+	}
+
+	return Effect.gen(function* () {
+		const spinner = ora({
+			text,
+			spinner: "dots",
+			color: "cyan",
+		}).start()
+
+		try {
+			const result = yield* effect
+
+			if (successText) {
+				spinner.succeed(successText)
+			} else {
+				spinner.stop()
+			}
+
+			return result
+		} catch (error) {
+			if (failText) {
+				spinner.fail(failText)
+			} else {
+				spinner.stop()
+			}
+			throw error
+		}
+	})
+}

package/templates/AGENCY.md

@@ -0,0 +1,20 @@
+# Agent Instructions
+
+## TASK.md
+
+The `TASK.md` file describes the task being performed and should be kept updated as work progresses. This file serves as a living record of:
+
+- What is being built or fixed
+- Current progress and status
+- Remaining work items
+- Any important context or decisions
+
+All work on this repository should begin by reading and understanding `TASK.md`. Whenever any significant progress is made, `TASK.md` should be updated to reflect the current state of work.
+
+**Note:** When you receive the prompt "Start the task", `TASK.md` is already in your context. DO NOT re-read it — instead, proceed directly with the work described in the task.
+
+## Commit Messages
+
+When creating commit messages, do not reference changes to `TASK.md`, `AGENTS.md`, or any files tracked in `agency.json` (such as `opencode.json`). These are project management and configuration files that should not be mentioned in commit messages. Focus commit messages on actual code changes, features, fixes, and refactoring.
+
+**Important:** Even when the only changes in a commit are to tracked files like `TASK.md`, you should still commit those changes. These updates should be co-located with the code changes they describe. Simply omit mentioning the tracked files in the commit message and focus the message on the actual code changes being made.

package/templates/AGENTS.md

@@ -0,0 +1,11 @@
+# Repo Instructions
+
+Follow these instructions when working in this repository.
+
+You should have already read @AGENCY.md to understand how agency is use to work on features.
+
+When you have read this file, move on to reading @TODO.md to understand the specific tasks.
+
+## Rules
+
+{human: fill this in}

package/templates/CLAUDE.md

@@ -0,0 +1,3 @@
+# Claude Code Instructions
+
+This project uses the agency CLI for managing development tasks and templates.

package/templates/TASK.md

@@ -0,0 +1,5 @@
+{task}
+
+## Tasks
+
+- [ ] Populate this list with tasks