@katyella/legio 0.1.0

package/src/worktree/manager.test.ts

@@ -0,0 +1,444 @@
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { WorktreeError } from "../errors.ts";
+import { cleanupTempDir, cloneFixtureRepo, commitFile, getDefaultBranch } from "../test-helpers.ts";
+import { createWorktree, isBranchMerged, listWorktrees, removeWorktree } from "./manager.ts";
+
+/**
+ * Run a git command in a directory and return stdout. Throws on non-zero exit.
+ */
+async function git(cwd: string, args: string[]): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const proc = spawn("git", args, {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		const stdoutChunks: Buffer[] = [];
+		const stderrChunks: Buffer[] = [];
+		proc.stdout.on("data", (data: Buffer) => stdoutChunks.push(data));
+		proc.stderr.on("data", (data: Buffer) => stderrChunks.push(data));
+		proc.on("error", reject);
+		proc.on("close", (code) => {
+			const stdout = Buffer.concat(stdoutChunks).toString();
+			const stderr = Buffer.concat(stderrChunks).toString();
+			if (code !== 0) {
+				reject(new Error(`git ${args.join(" ")} failed (exit ${code}): ${stderr.trim()}`));
+			} else {
+				resolve(stdout);
+			}
+		});
+	});
+}
+
+describe("createWorktree", () => {
+	let repoDir: string;
+	let worktreesDir: string;
+	let defaultBranch: string;
+
+	beforeEach(async () => {
+		// realpathSync resolves macOS /var -> /private/var symlink so paths match git output
+		repoDir = realpathSync(await cloneFixtureRepo());
+		defaultBranch = await getDefaultBranch(repoDir);
+		worktreesDir = join(repoDir, ".legio", "worktrees");
+		await mkdir(worktreesDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(repoDir);
+	});
+
+	test("returns correct path and branch name", async () => {
+		const result = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc123",
+		});
+
+		expect(result.path).toBe(join(worktreesDir, "auth-login"));
+		expect(result.branch).toBe("legio/auth-login/bead-abc123");
+	});
+
+	test("creates worktree directory on disk", async () => {
+		const result = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc123",
+		});
+
+		expect(existsSync(result.path)).toBe(true);
+		// The worktree should contain a .git file (not a directory, since it's a linked worktree)
+		expect(existsSync(join(result.path, ".git"))).toBe(true);
+	});
+
+	test("creates the branch in the repo", async () => {
+		await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc123",
+		});
+
+		const branchList = await git(repoDir, ["branch", "--list"]);
+		expect(branchList).toContain("legio/auth-login/bead-abc123");
+	});
+
+	test("throws WorktreeError when creating same worktree twice", async () => {
+		await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc123",
+		});
+
+		await expect(
+			createWorktree({
+				repoRoot: repoDir,
+				baseDir: worktreesDir,
+				agentName: "auth-login",
+				baseBranch: defaultBranch,
+				beadId: "bead-abc123",
+			}),
+		).rejects.toThrow(WorktreeError);
+	});
+
+	test("WorktreeError includes worktree path and branch name", async () => {
+		// Create once to occupy the branch name
+		await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc123",
+		});
+
+		try {
+			await createWorktree({
+				repoRoot: repoDir,
+				baseDir: worktreesDir,
+				agentName: "auth-login",
+				baseBranch: defaultBranch,
+				beadId: "bead-abc123",
+			});
+			// Should not reach here
+			expect(true).toBe(false);
+		} catch (err: unknown) {
+			expect(err).toBeInstanceOf(WorktreeError);
+			const wtErr = err as WorktreeError;
+			expect(wtErr.worktreePath).toBe(join(worktreesDir, "auth-login"));
+			expect(wtErr.branchName).toBe("legio/auth-login/bead-abc123");
+		}
+	});
+});
+
+describe("listWorktrees", () => {
+	let repoDir: string;
+	let worktreesDir: string;
+	let defaultBranch: string;
+
+	beforeEach(async () => {
+		repoDir = realpathSync(await cloneFixtureRepo());
+		defaultBranch = await getDefaultBranch(repoDir);
+		worktreesDir = join(repoDir, ".legio", "worktrees");
+		await mkdir(worktreesDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(repoDir);
+	});
+
+	test("lists main worktree when no additional worktrees exist", async () => {
+		const entries = await listWorktrees(repoDir);
+
+		expect(entries.length).toBeGreaterThanOrEqual(1);
+		// The first entry should be the main repo
+		const mainEntry = entries[0];
+		expect(mainEntry?.path).toBe(repoDir);
+		expect(mainEntry?.branch).toMatch(/^(main|master)$/);
+		expect(mainEntry?.head).toMatch(/^[a-f0-9]{40}$/);
+	});
+
+	test("lists multiple worktrees after creation", async () => {
+		await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc",
+		});
+
+		await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "data-sync",
+			baseBranch: defaultBranch,
+			beadId: "bead-xyz",
+		});
+
+		const entries = await listWorktrees(repoDir);
+
+		// Main worktree + 2 created = 3
+		expect(entries).toHaveLength(3);
+
+		const paths = entries.map((e) => e.path);
+		expect(paths).toContain(repoDir);
+		expect(paths).toContain(join(worktreesDir, "auth-login"));
+		expect(paths).toContain(join(worktreesDir, "data-sync"));
+
+		const branches = entries.map((e) => e.branch);
+		expect(branches).toContain("legio/auth-login/bead-abc");
+		expect(branches).toContain("legio/data-sync/bead-xyz");
+	});
+
+	test("strips refs/heads/ prefix from branch names", async () => {
+		await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "feature-worker",
+			baseBranch: defaultBranch,
+			beadId: "bead-123",
+		});
+
+		const entries = await listWorktrees(repoDir);
+		const worktreeEntry = entries.find((e) => e.path === join(worktreesDir, "feature-worker"));
+
+		expect(worktreeEntry?.branch).toBe("legio/feature-worker/bead-123");
+		// Ensure no refs/heads/ prefix leaked through
+		expect(worktreeEntry?.branch).not.toContain("refs/heads/");
+	});
+
+	test("each entry has a valid HEAD commit hash", async () => {
+		await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc",
+		});
+
+		const entries = await listWorktrees(repoDir);
+
+		for (const entry of entries) {
+			expect(entry.head).toMatch(/^[a-f0-9]{40}$/);
+		}
+	});
+
+	test("throws WorktreeError for non-git directory", async () => {
+		// Use a separate temp dir outside the git repo so git won't find a parent .git
+		const tmpDir = realpathSync(await mkdtemp(join(tmpdir(), "legio-notgit-")));
+		try {
+			await expect(listWorktrees(tmpDir)).rejects.toThrow(WorktreeError);
+		} finally {
+			await cleanupTempDir(tmpDir);
+		}
+	});
+});
+
+describe("removeWorktree", () => {
+	let repoDir: string;
+	let worktreesDir: string;
+	let defaultBranch: string;
+
+	beforeEach(async () => {
+		repoDir = realpathSync(await cloneFixtureRepo());
+		defaultBranch = await getDefaultBranch(repoDir);
+		worktreesDir = join(repoDir, ".legio", "worktrees");
+		await mkdir(worktreesDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(repoDir);
+	});
+
+	test("removes worktree directory from disk", async () => {
+		const { path: wtPath } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc",
+		});
+
+		expect(existsSync(wtPath)).toBe(true);
+
+		await removeWorktree(repoDir, wtPath);
+
+		expect(existsSync(wtPath)).toBe(false);
+	});
+
+	test("deletes the associated branch after removal", async () => {
+		const { path: wtPath } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc",
+		});
+
+		await removeWorktree(repoDir, wtPath);
+
+		const branchList = await git(repoDir, ["branch", "--list"]);
+		expect(branchList).not.toContain("legio/auth-login/bead-abc");
+	});
+
+	test("worktree no longer appears in listWorktrees after removal", async () => {
+		const { path: wtPath } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc",
+		});
+
+		await removeWorktree(repoDir, wtPath);
+
+		const entries = await listWorktrees(repoDir);
+		const paths = entries.map((e) => e.path);
+		expect(paths).not.toContain(wtPath);
+	});
+
+	test("force flag removes worktree with uncommitted changes", async () => {
+		const { path: wtPath } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc",
+		});
+
+		// Create an untracked file in the worktree
+		await writeFile(join(wtPath, "untracked.txt"), "some content", "utf-8");
+
+		// Without force, git worktree remove may fail on dirty worktrees.
+		// With force, it should succeed.
+		await removeWorktree(repoDir, wtPath, { force: true, forceBranch: true });
+
+		expect(existsSync(wtPath)).toBe(false);
+	});
+
+	test("forceBranch deletes unmerged branch", async () => {
+		const { path: wtPath } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc",
+		});
+
+		// Add a commit in the worktree so the branch diverges (making it "unmerged")
+		await commitFile(wtPath, "new-file.ts", "export const x = 1;", "add new file");
+
+		// forceBranch uses -D instead of -d, so even unmerged branches get deleted
+		await removeWorktree(repoDir, wtPath, { force: true, forceBranch: true });
+
+		const branchList = await git(repoDir, ["branch", "--list"]);
+		expect(branchList).not.toContain("legio/auth-login/bead-abc");
+	});
+
+	test("throws WorktreeError when branch is unmerged and forceBranch is false", async () => {
+		const { path: wtPath } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			beadId: "bead-abc",
+		});
+
+		// Add a commit to make the branch unmerged
+		await commitFile(wtPath, "new-file.ts", "export const x = 1;", "add new file");
+
+		// Without forceBranch, removeWorktree should throw WorktreeError because
+		// the branch has unmerged commits (git branch -d refuses to delete it).
+		await expect(removeWorktree(repoDir, wtPath, { force: true })).rejects.toThrow(WorktreeError);
+
+		// Worktree directory is removed before the throw (worktree remove runs first)
+		expect(existsSync(wtPath)).toBe(false);
+
+		// Branch still exists because -d failed and we threw instead of silently ignoring
+		const branchList = await git(repoDir, ["branch", "--list"]);
+		expect(branchList).toContain("legio/auth-login/bead-abc");
+	});
+});
+
+describe("isBranchMerged", () => {
+	let repoDir: string;
+	let worktreesDir: string;
+	let defaultBranch: string;
+
+	beforeEach(async () => {
+		repoDir = realpathSync(await cloneFixtureRepo());
+		defaultBranch = await getDefaultBranch(repoDir);
+		worktreesDir = join(repoDir, ".legio", "worktrees");
+		await mkdir(worktreesDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(repoDir);
+	});
+
+	test("returns true for a branch with no extra commits (same tip as target)", async () => {
+		const { branch } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "agent-a",
+			baseBranch: defaultBranch,
+			beadId: "bead-001",
+		});
+
+		// Branch was created from defaultBranch with no extra commits — its tip IS HEAD
+		const merged = await isBranchMerged(repoDir, branch, "HEAD");
+		expect(merged).toBe(true);
+	});
+
+	test("returns false for a branch with unmerged commits", async () => {
+		const { path: wtPath, branch } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "agent-b",
+			baseBranch: defaultBranch,
+			beadId: "bead-002",
+		});
+
+		// Commit diverges the branch from HEAD
+		await commitFile(wtPath, "feature.ts", "export const y = 2;", "add feature");
+
+		const merged = await isBranchMerged(repoDir, branch, "HEAD");
+		expect(merged).toBe(false);
+	});
+
+	test("returns true after branch is merged into HEAD", async () => {
+		const { path: wtPath, branch } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "agent-c",
+			baseBranch: defaultBranch,
+			beadId: "bead-003",
+		});
+
+		// Commit diverges the branch
+		await commitFile(wtPath, "feature.ts", "export const z = 3;", "add feature");
+
+		// Not merged yet
+		expect(await isBranchMerged(repoDir, branch, "HEAD")).toBe(false);
+
+		// Remove the worktree (but NOT the branch) so it is no longer checked out.
+		// Use git directly to detach just the worktree without deleting the branch ref.
+		await git(repoDir, ["worktree", "remove", "--force", wtPath]);
+
+		// Merge the branch into the main repo's HEAD
+		await git(repoDir, ["merge", branch, "--no-ff", "-m", `Merge ${branch}`]);
+
+		// Now the branch tip is an ancestor of HEAD
+		expect(await isBranchMerged(repoDir, branch, "HEAD")).toBe(true);
+	});
+});

package/src/worktree/manager.ts

@@ -0,0 +1,224 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { WorktreeError } from "../errors.ts";
+
+/**
+ * Run a shell command and capture its output.
+ */
+async function runCommand(
+	cmd: string[],
+	cwd?: string,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	const [command, ...args] = cmd;
+	if (!command) throw new Error("Empty command");
+	return new Promise((resolve, reject) => {
+		const proc = spawn(command, args, {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		const chunks: { stdout: Buffer[]; stderr: Buffer[] } = { stdout: [], stderr: [] };
+		proc.stdout.on("data", (data: Buffer) => chunks.stdout.push(data));
+		proc.stderr.on("data", (data: Buffer) => chunks.stderr.push(data));
+		proc.on("error", reject);
+		proc.on("close", (code) => {
+			resolve({
+				stdout: Buffer.concat(chunks.stdout).toString(),
+				stderr: Buffer.concat(chunks.stderr).toString(),
+				exitCode: code ?? 1,
+			});
+		});
+	});
+}
+
+/**
+ * Run a git command and return stdout. Throws WorktreeError on non-zero exit.
+ */
+async function runGit(
+	repoRoot: string,
+	args: string[],
+	context?: { worktreePath?: string; branchName?: string },
+): Promise<string> {
+	const { stdout, stderr, exitCode } = await runCommand(["git", ...args], repoRoot);
+
+	if (exitCode !== 0) {
+		throw new WorktreeError(
+			`git ${args.join(" ")} failed (exit ${exitCode}): ${stderr.trim() || stdout.trim()}`,
+			{
+				worktreePath: context?.worktreePath,
+				branchName: context?.branchName,
+			},
+		);
+	}
+
+	return stdout;
+}
+
+/**
+ * Create a new git worktree for an agent.
+ *
+ * Creates a worktree at `{baseDir}/{agentName}` with a new branch
+ * named `legio/{agentName}/{beadId}` based on `baseBranch`.
+ *
+ * @returns The absolute worktree path and branch name.
+ */
+export async function createWorktree(options: {
+	repoRoot: string;
+	baseDir: string;
+	agentName: string;
+	baseBranch: string;
+	beadId: string;
+}): Promise<{ path: string; branch: string }> {
+	const { repoRoot, baseDir, agentName, baseBranch, beadId } = options;
+
+	const worktreePath = join(baseDir, agentName);
+	const branchName = `legio/${agentName}/${beadId}`;
+
+	await runGit(repoRoot, ["worktree", "add", "-b", branchName, worktreePath, baseBranch], {
+		worktreePath,
+		branchName,
+	});
+
+	return { path: worktreePath, branch: branchName };
+}
+
+/**
+ * Parsed representation of a single worktree entry from `git worktree list --porcelain`.
+ */
+interface WorktreeEntry {
+	path: string;
+	branch: string;
+	head: string;
+}
+
+/**
+ * Parse the output of `git worktree list --porcelain` into structured entries.
+ *
+ * Porcelain format example:
+ * ```
+ * worktree /path/to/main
+ * HEAD abc123
+ * branch refs/heads/main
+ *
+ * worktree /path/to/wt
+ * HEAD def456
+ * branch refs/heads/legio/agent/bead
+ * ```
+ */
+function parseWorktreeOutput(output: string): WorktreeEntry[] {
+	const entries: WorktreeEntry[] = [];
+	const blocks = output.trim().split("\n\n");
+
+	for (const block of blocks) {
+		if (block.trim() === "") continue;
+
+		let path = "";
+		let head = "";
+		let branch = "";
+
+		const lines = block.trim().split("\n");
+		for (const line of lines) {
+			if (line.startsWith("worktree ")) {
+				path = line.slice("worktree ".length);
+			} else if (line.startsWith("HEAD ")) {
+				head = line.slice("HEAD ".length);
+			} else if (line.startsWith("branch ")) {
+				// Strip refs/heads/ prefix to get the short branch name
+				const ref = line.slice("branch ".length);
+				branch = ref.replace(/^refs\/heads\//, "");
+			}
+		}
+
+		if (path.length > 0) {
+			entries.push({ path, head, branch });
+		}
+	}
+
+	return entries;
+}
+
+/**
+ * List all git worktrees in the repository.
+ *
+ * @returns Array of worktree entries with path, branch name, and HEAD commit.
+ */
+export async function listWorktrees(
+	repoRoot: string,
+): Promise<Array<{ path: string; branch: string; head: string }>> {
+	const stdout = await runGit(repoRoot, ["worktree", "list", "--porcelain"]);
+	return parseWorktreeOutput(stdout);
+}
+
+/**
+ * Check whether a branch has been merged into a target ref.
+ *
+ * Uses `git merge-base --is-ancestor <branch> <target>`, which exits 0
+ * when branch is an ancestor of target (i.e., merged) and 1 when it is not.
+ * Any other exit code (e.g., unknown object) is treated as not merged.
+ *
+ * @param repoRoot - Absolute path to the git repository root.
+ * @param branch - Branch to check.
+ * @param target - Ref to check against (e.g. "HEAD", "main").
+ */
+export async function isBranchMerged(
+	repoRoot: string,
+	branch: string,
+	target: string,
+): Promise<boolean> {
+	const { exitCode } = await runCommand(
+		["git", "merge-base", "--is-ancestor", branch, target],
+		repoRoot,
+	);
+	// exit 0 = is ancestor (merged), exit 1 = not ancestor, other = error → treat as not merged
+	return exitCode === 0;
+}
+
+/**
+ * Remove a git worktree and delete its associated branch.
+ *
+ * Runs `git worktree remove {path}` to remove the worktree, then
+ * deletes the branch. With `forceBranch: true`, uses `git branch -D`
+ * to force-delete even unmerged branches and swallows deletion errors
+ * (best-effort). Without `forceBranch`, uses `git branch -d` which only
+ * deletes merged branches — if deletion fails (branch is unmerged), throws
+ * `WorktreeError` to signal that unmerged work remains.
+ */
+export async function removeWorktree(
+	repoRoot: string,
+	path: string,
+	options?: { force?: boolean; forceBranch?: boolean },
+): Promise<void> {
+	// First, figure out which branch this worktree is on so we can clean it up
+	const worktrees = await listWorktrees(repoRoot);
+	const entry = worktrees.find((wt) => wt.path === path);
+	const branchName = entry?.branch ?? "";
+
+	// Remove the worktree (--force handles untracked files and uncommitted changes)
+	const removeArgs = ["worktree", "remove", path];
+	if (options?.force) {
+		removeArgs.push("--force");
+	}
+	await runGit(repoRoot, removeArgs, {
+		worktreePath: path,
+		branchName,
+	});
+
+	// Delete the associated branch after worktree removal.
+	// Use -D (force) when forceBranch is set, since the branch may not have
+	// been merged yet. Use -d (safe) otherwise, which only deletes merged branches.
+	if (branchName.length > 0) {
+		const deleteFlag = options?.forceBranch ? "-D" : "-d";
+		try {
+			await runGit(repoRoot, ["branch", deleteFlag, branchName], { branchName });
+		} catch {
+			if (!options?.forceBranch) {
+				// Branch deletion failed without forceBranch — the branch has unmerged commits.
+				// Throw so callers know unmerged work remains on the branch.
+				throw new WorktreeError(
+					`Branch "${branchName}" has unmerged commits; pass forceBranch: true to force-delete.`,
+					{ worktreePath: path, branchName },
+				);
+			}
+			// forceBranch: branch deletion is best-effort, swallow the error.
+		}
+	}
+}