@os-eco/overstory-cli 0.6.1

package/src/worktree/manager.test.ts

@@ -0,0 +1,439 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, realpathSync } from "node:fs";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { WorktreeError } from "../errors.ts";
+import {
+	cleanupTempDir,
+	commitFile,
+	createTempGitRepo,
+	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> {
+	const proc = Bun.spawn(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+
+	if (exitCode !== 0) {
+		throw new Error(`git ${args.join(" ")} failed (exit ${exitCode}): ${stderr.trim()}`);
+	}
+
+	return 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 createTempGitRepo());
+		defaultBranch = await getDefaultBranch(repoDir);
+		worktreesDir = join(repoDir, ".overstory", "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("overstory/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("overstory/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("overstory/auth-login/bead-abc123");
+		}
+	});
+});
+
+describe("listWorktrees", () => {
+	let repoDir: string;
+	let worktreesDir: string;
+	let defaultBranch: string;
+
+	beforeEach(async () => {
+		repoDir = realpathSync(await createTempGitRepo());
+		defaultBranch = await getDefaultBranch(repoDir);
+		worktreesDir = join(repoDir, ".overstory", "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("overstory/auth-login/bead-abc");
+		expect(branches).toContain("overstory/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("overstory/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(), "overstory-notgit-")));
+		try {
+			await expect(listWorktrees(tmpDir)).rejects.toThrow(WorktreeError);
+		} finally {
+			await cleanupTempDir(tmpDir);
+		}
+	});
+});
+
+describe("isBranchMerged", () => {
+	let repoDir: string;
+	let worktreesDir: string;
+	let defaultBranch: string;
+
+	beforeEach(async () => {
+		repoDir = realpathSync(await createTempGitRepo());
+		defaultBranch = await getDefaultBranch(repoDir);
+		worktreesDir = join(repoDir, ".overstory", "worktrees");
+		await mkdir(worktreesDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(repoDir);
+	});
+
+	test("returns true for a branch that has been merged via git merge", async () => {
+		const { path: wtPath, branch } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "feature-agent",
+			baseBranch: defaultBranch,
+			beadId: "bead-merged",
+		});
+
+		// Add a commit to the feature branch
+		await commitFile(wtPath, "feature.ts", "export const x = 1;", "add feature");
+
+		// Merge the feature branch into defaultBranch
+		await git(repoDir, ["merge", "--no-ff", branch, "-m", "merge feature"]);
+
+		const merged = await isBranchMerged(repoDir, branch, defaultBranch);
+		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: "feature-agent",
+			baseBranch: defaultBranch,
+			beadId: "bead-unmerged",
+		});
+
+		// Add a commit to the feature branch (not merged)
+		await commitFile(wtPath, "feature.ts", "export const x = 1;", "add feature");
+
+		const merged = await isBranchMerged(repoDir, branch, defaultBranch);
+		expect(merged).toBe(false);
+	});
+
+	test("returns true for an identical branch (same commit, no additional commits)", async () => {
+		// A freshly created worktree branch has the same HEAD as the base branch
+		const { branch } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "feature-agent",
+			baseBranch: defaultBranch,
+			beadId: "bead-same",
+		});
+
+		// The branch was created from defaultBranch with no additional commits,
+		// so its tip is an ancestor of (equal to) defaultBranch
+		const merged = await isBranchMerged(repoDir, branch, defaultBranch);
+		expect(merged).toBe(true);
+	});
+});
+
+describe("removeWorktree", () => {
+	let repoDir: string;
+	let worktreesDir: string;
+	let defaultBranch: string;
+
+	beforeEach(async () => {
+		repoDir = realpathSync(await createTempGitRepo());
+		defaultBranch = await getDefaultBranch(repoDir);
+		worktreesDir = join(repoDir, ".overstory", "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("overstory/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 Bun.write(join(wtPath, "untracked.txt"), "some content");
+
+		// 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("overstory/auth-login/bead-abc");
+	});
+
+	test("without forceBranch, unmerged branch deletion is silently ignored", 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, branch -d will fail because it's not merged, but
+		// removeWorktree should not throw (it catches the error)
+		await removeWorktree(repoDir, wtPath, { force: true });
+
+		// Worktree is gone
+		expect(existsSync(wtPath)).toBe(false);
+
+		// But branch still exists because -d failed silently
+		const branchList = await git(repoDir, ["branch", "--list"]);
+		expect(branchList).toContain("overstory/auth-login/bead-abc");
+	});
+});

package/src/worktree/manager.ts

@@ -0,0 +1,198 @@
+import { join } from "node:path";
+import { WorktreeError } from "../errors.ts";
+
+/**
+ * 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 proc = Bun.spawn(["git", ...args], {
+		cwd: repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+
+	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 `overstory/{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 = `overstory/${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/overstory/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 if a branch has been merged into a target branch.
+ * Uses `git merge-base --is-ancestor` which returns exit 0 if merged, 1 if not.
+ */
+export async function isBranchMerged(
+	repoRoot: string,
+	branch: string,
+	targetBranch: string,
+): Promise<boolean> {
+	const proc = Bun.spawn(["git", "merge-base", "--is-ancestor", branch, targetBranch], {
+		cwd: repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const [stderr, exitCode] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+
+	if (exitCode === 0) return true;
+	if (exitCode === 1) return false;
+
+	throw new WorktreeError(
+		`git merge-base --is-ancestor failed (exit ${exitCode}): ${stderr.trim()}`,
+		{ branchName: branch },
+	);
+}
+
+/**
+ * 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. Otherwise uses `git branch -d`
+ * which only deletes merged branches.
+ */
+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 {
+			// Branch deletion failed — may be unmerged (with -d) or checked out elsewhere.
+			// This is best-effort; the worktree itself is already removed.
+		}
+	}
+}