@markjaquith/agency 0.5.0

package/src/utils/colors.ts

@@ -0,0 +1,178 @@
+/**
+ * Color highlighting utilities for CLI output
+ *
+ * This module provides centralized color management for highlighting
+ * meaningful values in CLI feedback. All highlight types use the same
+ * base color initially, but are separated into buckets to allow for
+ * future customization.
+ *
+ * Colors can be disabled via:
+ * - NO_COLOR environment variable (standard)
+ * - Setting colorsEnabled to false
+ */
+
+// ANSI color codes
+const RESET = "\x1b[0m"
+const CYAN_BRIGHT = "\x1b[96m"
+const GREEN = "\x1b[32m"
+const YELLOW = "\x1b[33m"
+
+/**
+ * Central color configuration
+ * All buckets use the same color initially (bright cyan)
+ * but can be easily changed independently in the future
+ */
+const COLORS = {
+	branch: CYAN_BRIGHT,
+	template: CYAN_BRIGHT,
+	file: CYAN_BRIGHT,
+	setting: CYAN_BRIGHT,
+	value: CYAN_BRIGHT,
+	commit: CYAN_BRIGHT,
+	pattern: CYAN_BRIGHT,
+	remote: YELLOW,
+} as const
+
+/**
+ * Global flag to enable/disable colors
+ * Defaults to enabled unless NO_COLOR environment variable is set
+ */
+let colorsEnabled = !process.env.NO_COLOR
+
+/**
+ * Enable or disable color output
+ * @param enabled - Whether to enable colors
+ */
+export function setColorsEnabled(enabled: boolean): void {
+	colorsEnabled = enabled
+}
+
+/**
+ * Check if colors are currently enabled
+ */
+function areColorsEnabled(): boolean {
+	return colorsEnabled
+}
+
+/**
+ * Internal helper to apply color formatting
+ * Returns plain text if colors are disabled
+ */
+function colorize(text: string, color: string): string {
+	if (!colorsEnabled) {
+		return text
+	}
+	return `${color}${text}${RESET}`
+}
+
+/**
+ * Highlight a branch name
+ * @example highlight.branch("main") -> "\x1b[96mmain\x1b[0m"
+ */
+function branch(name: string): string {
+	return colorize(name, COLORS.branch)
+}
+
+/**
+ * Highlight a template name
+ * @example highlight.template("my-template") -> "\x1b[96mmy-template\x1b[0m"
+ */
+function template(name: string): string {
+	return colorize(name, COLORS.template)
+}
+
+/**
+ * Highlight a file name or path
+ * @example highlight.file("AGENTS.md") -> "\x1b[96mAGENTS.md\x1b[0m"
+ */
+function file(name: string): string {
+	return colorize(name, COLORS.file)
+}
+
+/**
+ * Highlight a setting name
+ * @example highlight.setting("agency.template") -> "\x1b[96magency.template\x1b[0m"
+ */
+function setting(name: string): string {
+	return colorize(name, COLORS.setting)
+}
+
+/**
+ * Highlight a numeric value or count
+ * @example highlight.value("3") -> "\x1b[96m3\x1b[0m"
+ */
+function value(val: string | number): string {
+	return colorize(String(val), COLORS.value)
+}
+
+/**
+ * Highlight a commit hash
+ * @example highlight.commit("abc123") -> "\x1b[96mabc123\x1b[0m"
+ */
+function commit(hash: string): string {
+	return colorize(hash, COLORS.commit)
+}
+
+/**
+ * Highlight a pattern or placeholder
+ * @example highlight.pattern("{task}") -> "\x1b[96m{task}\x1b[0m"
+ */
+function pattern(text: string): string {
+	return colorize(text, COLORS.pattern)
+}
+
+/**
+ * Highlight a git remote name
+ * @example highlight.remote("origin") -> "\x1b[33morigin\x1b[0m"
+ */
+function remote(name: string): string {
+	return colorize(name, COLORS.remote)
+}
+
+/**
+ * Prepends a green checkmark to a message for success output
+ * Uses the same checkmark symbol and color as ora for consistency
+ * @param message - The message to prepend the checkmark to
+ * @example log(done(`Merged ${highlight.branch("main")}`))
+ * @example log(done("Operation completed"))
+ */
+export function done(message: string): string {
+	const checkmark = colorsEnabled ? `\x1b[32m✔\x1b[0m` : "✔"
+	return `${checkmark} ${message}`
+}
+
+/**
+ * Prepends an info icon to a message for informational output
+ * @param message - The message to prepend the info icon to
+ * @example log(info("Skipping task description"))
+ * @example log(info(`File already exists`))
+ */
+export function info(message: string): string {
+	return `ⓘ ${message}`
+}
+
+/**
+ * Returns "s" if count is not 1, empty string otherwise
+ * Useful for pluralizing words in messages
+ * @param count - The count to check
+ * @example `Committed ${count} file${plural(count)}`  -> "Committed 1 file" or "Committed 3 files"
+ */
+export function plural(count: number): string {
+	return count === 1 ? "" : "s"
+}
+
+/**
+ * Default export as namespace for convenient usage
+ * @example import highlight from "./colors"
+ * @example console.log(`Switched to ${highlight.branch("main")}`)
+ */
+export default {
+	branch,
+	template,
+	file,
+	setting,
+	value,
+	commit,
+	pattern,
+	remote,
+}

package/src/utils/command.ts

@@ -0,0 +1,17 @@
+/**
+ * Base options that all commands accept
+ */
+export interface BaseCommandOptions {
+	readonly silent?: boolean
+	readonly verbose?: 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.ts

@@ -0,0 +1,281 @@
+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
+}) {
+	const { silent = false, verbose = false } = options
+	return {
+		log: silent ? () => {} : console.log,
+		verboseLog: verbose && !silent ? 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/exec.ts

@@ -0,0 +1,48 @@
+import { dlopen, FFIType, ptr } from "bun:ffi"
+
+/**
+ * Native exec implementation using Bun FFI to call POSIX execvp.
+ * This completely replaces the current process with the specified command.
+ *
+ * IMPORTANT: This function will never return if successful. The process
+ * image is completely replaced with the new program.
+ *
+ * @param file - The program to execute (will be searched in PATH)
+ * @param args - Array of arguments (first should be the program name)
+ * @throws Error if exec fails (e.g., command not found)
+ */
+export function execvp(file: string, args: string[]): never {
+	// Open libc to access execvp (platform-specific library paths)
+	const libcPath =
+		process.platform === "darwin" ? "/usr/lib/libSystem.B.dylib" : "libc.so.6"
+	const libc = dlopen(libcPath, {
+		execvp: {
+			args: [FFIType.cstring, FFIType.ptr],
+			returns: FFIType.int,
+		},
+	})
+
+	// execvp expects argv as a null-terminated array of char* pointers
+	// We need to convert our string array to C strings and create a pointer array
+	const cstrings = args.map((arg) => Buffer.from(arg + "\0"))
+	const ptrs = new BigUint64Array(args.length + 1)
+
+	// Fill the pointer array with addresses of our C strings
+	for (let i = 0; i < args.length; i++) {
+		const buf = cstrings[i]
+		if (buf) {
+			ptrs[i] = BigInt(ptr(buf))
+		}
+	}
+	// Null-terminate the pointer array
+	ptrs[args.length] = 0n
+
+	// Call execvp - this will replace the current process if successful
+	const fileBuffer = Buffer.from(file + "\0")
+	const result = libc.symbols.execvp(ptr(fileBuffer), ptr(ptrs))
+
+	// If we reach here, exec failed
+	throw new Error(
+		`execvp failed with code ${result}: Unable to execute '${file}'`,
+	)
+}

package/src/utils/paths.ts

@@ -0,0 +1,51 @@
+/**
+ * Utilities for resolving agency configuration paths.
+ */
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/**
+ * Get the agency configuration directory.
+ * Defaults to ~/.config/agency, can be overridden via AGENCY_CONFIG_DIR env var.
+ * @param override - Optional override for the config directory (used in testing)
+ */
+export function getAgencyConfigDir(override?: string): string {
+	return (
+		override ||
+		process.env.AGENCY_CONFIG_DIR ||
+		join(homedir(), ".config", "agency")
+	)
+}
+
+/**
+ * Get the path to the agency config file (agency.json).
+ * Can be overridden via AGENCY_CONFIG_PATH env var.
+ * @param configDir - Optional config directory override
+ */
+export function getAgencyConfigPath(configDir?: string): string {
+	return (
+		process.env.AGENCY_CONFIG_PATH ||
+		join(getAgencyConfigDir(configDir), "agency.json")
+	)
+}
+
+/**
+ * Get the templates directory path.
+ * @param configDir - Optional config directory override
+ */
+export function getTemplatesDir(configDir?: string): string {
+	return join(getAgencyConfigDir(configDir), "templates")
+}
+
+/**
+ * Get the path to a specific template directory.
+ * @param templateName - Name of the template
+ * @param configDir - Optional config directory override
+ */
+export function getTemplateDir(
+	templateName: string,
+	configDir?: string,
+): string {
+	return join(getTemplatesDir(configDir), templateName)
+}