@markjaquith/agency 0.5.0

package/src/test-utils.ts

@@ -0,0 +1,362 @@
+import { mkdtemp, rm, cp } from "fs/promises"
+import { tmpdir } from "os"
+import { join } from "path"
+
+// Cache a template git repository to speed up test setup
+let templateGitRepo: string | null = null
+let templateGitRepoPromise: Promise<string> | null = null
+
+async function getTemplateGitRepo(): Promise<string> {
+	// Return cached result if available
+	if (templateGitRepo) {
+		return templateGitRepo
+	}
+
+	// Use a promise to prevent concurrent initialization (race condition fix)
+	if (templateGitRepoPromise) {
+		return templateGitRepoPromise
+	}
+
+	// Create and cache the initialization promise
+	templateGitRepoPromise = (async () => {
+		// Create a template git repo once and reuse it
+		const tempDir = await mkdtemp(join(tmpdir(), "agency-template-"))
+
+		const proc = Bun.spawn(["git", "init", "-b", "main"], {
+			cwd: tempDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		})
+		await proc.exited
+
+		if (proc.exitCode !== 0) {
+			throw new Error("Failed to initialize template git repository")
+		}
+
+		// Write config directly
+		const configFile = Bun.file(join(tempDir, ".git", "config"))
+		const existingConfig = await configFile.text()
+		const newConfig =
+			existingConfig +
+			"\n[user]\n\temail = test@example.com\n\tname = Test User\n[core]\n\thooksPath = /dev/null\n"
+		await Bun.write(join(tempDir, ".git", "config"), newConfig)
+
+		// Create initial commit
+		await Bun.write(join(tempDir, ".gitkeep"), "")
+		await Bun.spawn(["git", "add", ".gitkeep"], {
+			cwd: tempDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		}).exited
+		await Bun.spawn(["git", "commit", "-m", "Initial commit"], {
+			cwd: tempDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		}).exited
+
+		templateGitRepo = tempDir
+		return tempDir
+	})()
+
+	return templateGitRepoPromise
+}
+
+/**
+ * Create a temporary directory for testing
+ */
+export async function createTempDir(): Promise<string> {
+	return await mkdtemp(join(tmpdir(), "agency-test-"))
+}
+
+/**
+ * Clean up a temporary directory
+ */
+export async function cleanupTempDir(path: string): Promise<void> {
+	try {
+		await rm(path, { recursive: true, force: true })
+	} catch (error) {
+		// Ignore errors during cleanup
+	}
+}
+
+/**
+ * Initialize a git repository in a directory
+ * Uses a cached template repository for much faster setup
+ */
+export async function initGitRepo(path: string): Promise<void> {
+	const template = await getTemplateGitRepo()
+
+	// Copy the template .git directory
+	await cp(join(template, ".git"), join(path, ".git"), {
+		recursive: true,
+	})
+
+	// Copy the .gitkeep file
+	await cp(join(template, ".gitkeep"), join(path, ".gitkeep"))
+}
+
+/**
+ * Create a subdirectory in a path
+ */
+export async function createSubdir(
+	basePath: string,
+	name: string,
+): Promise<string> {
+	const subdirPath = join(basePath, name)
+	await Bun.write(join(subdirPath, ".gitkeep"), "")
+	return subdirPath
+}
+
+/**
+ * Check if a file exists
+ */
+export async function fileExists(path: string): Promise<boolean> {
+	const file = Bun.file(path)
+	return await file.exists()
+}
+
+/**
+ * Read file content
+ */
+export async function readFile(path: string): Promise<string> {
+	const file = Bun.file(path)
+	return await file.text()
+}
+
+/**
+ * Execute a git command and return its output
+ */
+export async function getGitOutput(
+	cwd: string,
+	args: string[],
+): Promise<string> {
+	const proc = Bun.spawn(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	await proc.exited
+	return await new Response(proc.stdout).text()
+}
+
+/**
+ * Get the current branch name in a git repository
+ */
+export async function getCurrentBranch(cwd: string): Promise<string> {
+	const output = await getGitOutput(cwd, ["branch", "--show-current"])
+	return output.trim()
+}
+
+/**
+ * Run a git command directly - fire and forget version (fastest)
+ */
+async function gitRun(cwd: string, args: string[]): Promise<void> {
+	const proc = Bun.spawn(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	await proc.exited
+}
+
+/**
+ * Create a test commit in a git repository
+ */
+export async function createCommit(
+	cwd: string,
+	message: string,
+): Promise<void> {
+	// Create a test file and commit it
+	await Bun.write(join(cwd, "test.txt"), message)
+	await gitRun(cwd, ["add", "test.txt"])
+	await gitRun(cwd, ["commit", "--no-verify", "-m", message])
+}
+
+/**
+ * Checkout a branch in a git repository
+ */
+export async function checkoutBranch(
+	cwd: string,
+	branchName: string,
+): Promise<void> {
+	await gitRun(cwd, ["checkout", branchName])
+}
+
+/**
+ * Create a new branch and switch to it
+ */
+export async function createBranch(
+	cwd: string,
+	branchName: string,
+): Promise<void> {
+	await gitRun(cwd, ["checkout", "-b", branchName])
+}
+
+/**
+ * Stage files and commit in a single operation
+ */
+export async function addAndCommit(
+	cwd: string,
+	files: string | string[],
+	message: string,
+): Promise<void> {
+	const fileList = Array.isArray(files) ? files : files.split(" ")
+	await gitRun(cwd, ["add", ...fileList])
+	await gitRun(cwd, ["commit", "--no-verify", "-m", message])
+}
+
+/**
+ * Setup a remote and fetch in a single operation
+ */
+export async function setupRemote(
+	cwd: string,
+	remoteName: string,
+	remoteUrl: string,
+): Promise<void> {
+	await gitRun(cwd, ["remote", "add", remoteName, remoteUrl])
+	await gitRun(cwd, ["fetch", remoteName])
+}
+
+/**
+ * Delete a branch
+ */
+export async function deleteBranch(
+	cwd: string,
+	branchName: string,
+	force: boolean = false,
+): Promise<void> {
+	const flag = force ? "-D" : "-d"
+	await gitRun(cwd, ["branch", flag, branchName])
+}
+
+/**
+ * Rename current branch
+ */
+export async function renameBranch(
+	cwd: string,
+	newName: string,
+): Promise<void> {
+	await gitRun(cwd, ["branch", "-m", newName])
+}
+
+/**
+ * Check if a branch exists in a git repository
+ */
+export async function branchExists(
+	cwd: string,
+	branch: string,
+): Promise<boolean> {
+	const proc = Bun.spawn(["git", "rev-parse", "--verify", branch], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	await proc.exited
+	return proc.exitCode === 0
+}
+
+/**
+ * Initialize a repository with agency by setting a template in git config
+ */
+export async function initAgency(
+	cwd: string,
+	templateName: string,
+): Promise<void> {
+	await Bun.spawn(
+		["git", "config", "--local", "agency.template", templateName],
+		{
+			cwd,
+			stdout: "pipe",
+			stderr: "pipe",
+		},
+	).exited
+}
+
+/**
+ * Get a git config value for testing
+ */
+export async function getGitConfig(
+	key: string,
+	gitRoot: string,
+): Promise<string | null> {
+	try {
+		const proc = Bun.spawn(["git", "config", "--local", "--get", key], {
+			cwd: gitRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+		})
+		await proc.exited // Must await before reading stdout to prevent hangs in concurrent tests
+		const output = await new Response(proc.stdout).text()
+		return output.trim() || null
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Run a git command
+ */
+export async function runGitCommand(
+	cwd: string,
+	args: string[],
+): Promise<void> {
+	const proc = Bun.spawn(args, {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	await proc.exited
+	if (proc.exitCode !== 0) {
+		const stderr = await new Response(proc.stderr).text()
+		throw new Error(`Git command failed: ${args.join(" ")}\n${stderr}`)
+	}
+}
+
+/**
+ * Create a file with content
+ */
+export async function createFile(
+	cwd: string,
+	filename: string,
+	content: string,
+): Promise<void> {
+	await Bun.write(join(cwd, filename), content)
+}
+
+/**
+ * Run an Effect in tests with all services provided
+ */
+import { Effect, Layer } from "effect"
+import { GitService } from "./services/GitService"
+import { ConfigService } from "./services/ConfigService"
+import { FileSystemService } from "./services/FileSystemService"
+import { PromptService } from "./services/PromptService"
+import { TemplateService } from "./services/TemplateService"
+import { OpencodeService } from "./services/OpencodeService"
+import { ClaudeService } from "./services/ClaudeService"
+
+// Create test layer with all services
+const TestLayer = Layer.mergeAll(
+	GitService.Default,
+	ConfigService.Default,
+	FileSystemService.Default,
+	PromptService.Default,
+	TemplateService.Default,
+	OpencodeService.Default,
+	ClaudeService.Default,
+)
+
+export async function runTestEffect<A, E>(
+	effect: Effect.Effect<A, E, any>,
+): Promise<A> {
+	const providedEffect = Effect.provide(effect, TestLayer) as Effect.Effect<
+		A,
+		E,
+		never
+	>
+	const program = Effect.catchAllDefect(providedEffect, (defect) =>
+		Effect.fail(defect instanceof Error ? defect : new Error(String(defect))),
+	) as Effect.Effect<A, E | Error, never>
+
+	return await Effect.runPromise(program)
+}

package/src/types/native-exec.d.ts

@@ -0,0 +1,8 @@
+declare module "@triggi/native-exec" {
+	function exec(
+		command: string,
+		env?: NodeJS.ProcessEnv,
+		...args: string[]
+	): void
+	export default exec
+}

package/src/types.ts

@@ -0,0 +1,216 @@
+import { join } from "node:path"
+import { Effect } from "effect"
+import { Schema } from "@effect/schema"
+import { ManagedFile, AgencyMetadata } from "./schemas"
+import {
+	AgencyMetadataService,
+	AgencyMetadataServiceLive,
+} from "./services/AgencyMetadataService"
+import { FileSystemService } from "./services/FileSystemService"
+import { GitService } from "./services/GitService"
+
+export interface Command {
+	name: string
+	description: string
+	run: (args: string[], options: Record<string, any>) => Promise<void>
+	help?: string
+}
+
+/**
+ * Load template content from the templates directory.
+ * Falls back to inline defaults if files cannot be read (e.g., in bundled packages).
+ */
+async function loadTemplateContent(fileName: string): Promise<string> {
+	try {
+		// Try to load from the templates directory relative to this file's location
+		const templatePath = join(import.meta.dir, "..", "templates", fileName)
+		const file = Bun.file(templatePath)
+		if (await file.exists()) {
+			return await file.text()
+		}
+	} catch (error) {
+		// Fall through to defaults if file loading fails
+	}
+
+	// Return inline defaults as fallback
+	const defaults: Record<string, string> = {
+		"AGENCY.md": `# 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.
+
+See \`TASK.md\` for the current task description and progress.
+`,
+		"AGENTS.md": `# Agency
+
+Agency is a CLI tool for managing \`AGENTS.md\`, \`TASK.md\`, and \`opencode.json\` files in git repositories. It helps coordinate work across multiple branches and templates.
+
+## Key Commands
+
+- \`agency task\` - Initialize template files on a feature branch
+- \`agency edit\` - Open TASK.md in system editor
+- \`agency template save\` - Save current file versions back to a template
+- \`agency template use\` - Switch to a different template
+- \`agency emit\` - Create an emit branch with managed files reverted to their merge-base state
+- \`agency switch\` - Toggle between feature and emit branches
+- \`agency template source\` - Get the path to a template's source directory
+- \`agency set-base\` - Update the saved base branch for emit creation
+
+## Features
+
+- **Template-based workflow** - Reusable templates stored in \`~/.config/agency/templates/\`
+- **Git integration** - Saves template configuration in \`.git/config\`
+- **Emit branch management** - Automatically creates clean emit branches without local modifications
+- **Multi-file support** - Manages AGENTS.md, TASK.md, and opencode.json
+`,
+		"TASK.md": `{task}
+
+## Tasks
+
+- [ ] Populate this list
+`,
+		"opencode.json": JSON.stringify(
+			{
+				$schema: "https://opencode.ai/config.json",
+				instructions: ["AGENCY.md", "TASK.md"],
+			},
+			null,
+			2,
+		),
+	}
+
+	return defaults[fileName] || ""
+}
+
+/**
+ * Initialize managed files with their default content.
+ * This is a synchronous function that returns a promise for the initialized files.
+ */
+export async function initializeManagedFiles(): Promise<ManagedFile[]> {
+	const files: ManagedFile[] = []
+
+	for (const fileName of [
+		"AGENCY.md",
+		"AGENTS.md",
+		"opencode.json",
+		"TASK.md",
+	]) {
+		const content = await loadTemplateContent(fileName)
+		files.push({
+			name: fileName,
+			defaultContent: content,
+		})
+	}
+
+	return files
+}
+
+// This will be initialized by commands that need it
+// For backward compatibility, export a variable that can be set
+let MANAGED_FILES: ManagedFile[] = []
+
+// Validation is now handled by Effect schemas in schemas.ts
+
+/**
+ * Read agency.json metadata from a repository.
+ * @deprecated Use AgencyMetadataService.readFromDisk instead
+ */
+export async function readAgencyMetadata(
+	gitRoot: string,
+): Promise<AgencyMetadata | null> {
+	const program = Effect.gen(function* () {
+		const metadataService = yield* AgencyMetadataService
+		return yield* metadataService.readFromDisk(gitRoot)
+	}).pipe(
+		Effect.provide(AgencyMetadataServiceLive),
+		Effect.provide(FileSystemService.Default),
+		Effect.provide(GitService.Default),
+	)
+
+	return Effect.runPromise(program)
+}
+
+/**
+ * Write agency.json metadata to a repository.
+ * @deprecated Use AgencyMetadataService.write instead
+ */
+export async function writeAgencyMetadata(
+	gitRoot: string,
+	metadata: AgencyMetadata,
+): Promise<void> {
+	const program = Effect.gen(function* () {
+		const metadataService = yield* AgencyMetadataService
+		return yield* metadataService.write(gitRoot, metadata)
+	}).pipe(
+		Effect.provide(AgencyMetadataServiceLive),
+		Effect.provide(FileSystemService.Default),
+		Effect.provide(GitService.Default),
+	)
+
+	return Effect.runPromise(program)
+}
+
+/**
+ * Get list of files to filter during PR/merge operations.
+ * Always includes TASK.md, AGENCY.md, and agency.json, plus any backpack files from metadata.
+ * @deprecated Use AgencyMetadataService.getFilesToFilter instead
+ */
+export async function getFilesToFilter(gitRoot: string): Promise<string[]> {
+	const program = Effect.gen(function* () {
+		const metadataService = yield* AgencyMetadataService
+		return yield* metadataService.getFilesToFilter(gitRoot)
+	}).pipe(
+		Effect.provide(AgencyMetadataServiceLive),
+		Effect.provide(FileSystemService.Default),
+		Effect.provide(GitService.Default),
+	)
+
+	return Effect.runPromise(program)
+}
+
+/**
+ * Get the configured base branch from agency.json metadata.
+ * @deprecated Use AgencyMetadataService.getBaseBranch instead
+ */
+export async function getBaseBranchFromMetadata(
+	gitRoot: string,
+): Promise<string | null> {
+	const program = Effect.gen(function* () {
+		const metadataService = yield* AgencyMetadataService
+		return yield* metadataService.getBaseBranch(gitRoot)
+	}).pipe(
+		Effect.provide(AgencyMetadataServiceLive),
+		Effect.provide(FileSystemService.Default),
+		Effect.provide(GitService.Default),
+	)
+
+	return Effect.runPromise(program)
+}
+
+/**
+ * Set the base branch in agency.json metadata.
+ * @deprecated Use AgencyMetadataService.setBaseBranch instead
+ */
+export async function setBaseBranchInMetadata(
+	gitRoot: string,
+	baseBranch: string,
+): Promise<void> {
+	const program = Effect.gen(function* () {
+		const metadataService = yield* AgencyMetadataService
+		return yield* metadataService.setBaseBranch(gitRoot, baseBranch)
+	}).pipe(
+		Effect.provide(AgencyMetadataServiceLive),
+		Effect.provide(FileSystemService.Default),
+		Effect.provide(GitService.Default),
+	)
+
+	return Effect.runPromise(program)
+}