@ag-eco/agentplate-cli 0.13.0

package/src/commands/worktree.ts

@@ -0,0 +1,451 @@
+/**
+ * CLI command: ap worktree list | clean [--completed] [--all]
+ *
+ * List shows worktrees with agent status.
+ * Clean removes worktree dirs, branch refs (if merged), and tmux sessions.
+ * Logs are never auto-deleted.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { printHint, printSuccess, printWarning } from "../logging/color.ts";
+import { createMailStore } from "../mail/store.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import type { AgentSession } from "../types.ts";
+import {
+	isBranchMerged,
+	listWorktrees,
+	preserveSproutChanges,
+	removeWorktree,
+} from "../worktree/manager.ts";
+import { isSessionAlive, killSession } from "../worktree/tmux.ts";
+
+/**
+ * Check for live child sessions nested inside a worktree's own .agentplate/sessions.db.
+ *
+ * Returns the live children (agentName + pid). Empty array if no nested DB or no live children.
+ */
+export async function checkLiveChildren(
+	worktreePath: string,
+): Promise<{ agentName: string; pid: number }[]> {
+	const nestedDb = join(worktreePath, ".agentplate", "sessions.db");
+	if (!existsSync(nestedDb)) {
+		return [];
+	}
+
+	const store = createSessionStore(nestedDb);
+	let sessions: AgentSession[];
+	try {
+		sessions = store.getAll();
+	} finally {
+		store.close();
+	}
+
+	const deadStates = new Set(["completed", "zombie"]);
+	const liveChildren: { agentName: string; pid: number }[] = [];
+
+	for (const session of sessions) {
+		if (deadStates.has(session.state)) continue;
+		if (session.pid === null) continue;
+
+		// process.kill(pid, 0) throws if the process is dead (ESRCH)
+		let alive = false;
+		try {
+			process.kill(session.pid, 0);
+			alive = true;
+		} catch {
+			// ESRCH — process is dead
+		}
+
+		if (alive) {
+			liveChildren.push({ agentName: session.agentName, pid: session.pid });
+		}
+	}
+
+	return liveChildren;
+}
+
+/**
+ * Handle `ap worktree list`.
+ */
+async function handleList(root: string, json: boolean): Promise<void> {
+	const worktrees = await listWorktrees(root);
+	const agentplateDir = join(root, ".agentplate");
+	const { store } = openSessionStore(agentplateDir);
+	let sessions: AgentSession[];
+	try {
+		sessions = store.getAll();
+	} finally {
+		store.close();
+	}
+
+	const agentplateWts = worktrees.filter((wt) => wt.branch.startsWith("agentplate/"));
+
+	if (json) {
+		const entries = agentplateWts.map((wt) => {
+			const session = sessions.find((s) => s.worktreePath === wt.path);
+			return {
+				path: wt.path,
+				branch: wt.branch,
+				head: wt.head,
+				agentName: session?.agentName ?? null,
+				state: session?.state ?? null,
+				taskId: session?.taskId ?? null,
+			};
+		});
+		jsonOutput("worktree list", { worktrees: entries });
+		return;
+	}
+
+	if (agentplateWts.length === 0) {
+		printHint("No agent worktrees found");
+		return;
+	}
+
+	process.stdout.write(`Agent worktrees: ${agentplateWts.length}\n\n`);
+	for (const wt of agentplateWts) {
+		const session = sessions.find((s) => s.worktreePath === wt.path);
+		const state = session?.state ?? "unknown";
+		const agent = session?.agentName ?? "?";
+		const bead = session?.taskId ?? "?";
+		process.stdout.write(`  ${wt.branch}\n`);
+		process.stdout.write(`    Agent: ${agent} | State: ${state} | Task: ${bead}\n`);
+		process.stdout.write(`    Path: ${wt.path}\n\n`);
+	}
+}
+
+/**
+ * Handle `ap worktree clean [--completed] [--all] [--force]`.
+ */
+async function handleClean(
+	opts: { all: boolean; force: boolean; completedOnly: boolean },
+	root: string,
+	json: boolean,
+	canonicalBranch: string,
+): Promise<void> {
+	const { force, completedOnly } = opts;
+
+	const worktrees = await listWorktrees(root);
+	const agentplateDir = join(root, ".agentplate");
+	const { store } = openSessionStore(agentplateDir);
+
+	let sessions: AgentSession[];
+	try {
+		sessions = store.getAll();
+	} catch {
+		store.close();
+		return;
+	}
+
+	const agentplateWts = worktrees.filter((wt) => wt.branch.startsWith("agentplate/"));
+	const cleaned: string[] = [];
+	const failed: string[] = [];
+	const skipped: string[] = [];
+	const sproutPreserved: string[] = [];
+	const blockedByChildren: string[] = [];
+
+	try {
+		for (const wt of agentplateWts) {
+			const session = sessions.find((s) => s.worktreePath === wt.path);
+
+			// If --completed (default), only clean worktrees whose agent is done/zombie
+			if (completedOnly && session && session.state !== "completed" && session.state !== "zombie") {
+				continue;
+			}
+
+			// Lead branches are never merged via the normal pipeline — skip merge check for leads.
+			const isLead = session?.capability === "lead";
+
+			// Check if the branch has been merged into the canonical branch (unless --force or lead)
+			if (!force && !isLead && wt.branch.length > 0) {
+				let merged = false;
+				try {
+					merged = await isBranchMerged(root, wt.branch, canonicalBranch);
+				} catch {
+					// If we can't determine merge status, treat as unmerged (safe default)
+					merged = false;
+				}
+
+				if (!merged) {
+					skipped.push(wt.branch);
+					continue;
+				}
+			}
+
+			// Live-children guard: refuse to remove a worktree that has active nested agents.
+			// Nested sessions live in {wt.path}/.agentplate/sessions.db (lead worktrees).
+			const liveChildren = await checkLiveChildren(wt.path);
+			if (liveChildren.length > 0) {
+				if (!force) {
+					blockedByChildren.push(wt.branch);
+					continue;
+				}
+				// --force: SIGTERM each live child, wait briefly, then proceed.
+				if (!json) {
+					printWarning(
+						`Force-terminating ${liveChildren.length} live child${liveChildren.length === 1 ? "" : "ren"} in ${wt.branch}`,
+					);
+					for (const child of liveChildren) {
+						process.stdout.write(`  ${child.agentName} (pid ${child.pid})\n`);
+					}
+				}
+				for (const child of liveChildren) {
+					try {
+						process.kill(child.pid, "SIGTERM");
+					} catch {
+						// Best effort
+					}
+				}
+				await Bun.sleep(500);
+			}
+
+			// If --all, clean everything
+			// Kill tmux session if still alive
+			if (session?.tmuxSession) {
+				const alive = await isSessionAlive(session.tmuxSession);
+				if (alive) {
+					try {
+						await killSession(session.tmuxSession);
+					} catch {
+						// Best effort
+					}
+				}
+			}
+
+			// Warn about force-deleting unmerged branch (non-lead only)
+			if (force && !isLead && wt.branch.length > 0) {
+				let merged = false;
+				try {
+					merged = await isBranchMerged(root, wt.branch, canonicalBranch);
+				} catch {
+					merged = false;
+				}
+				if (!merged && !json) {
+					printWarning("Force-deleting unmerged branch", wt.branch);
+				}
+			}
+
+			// Preserve .sprout/ changes from lead worktrees before removal.
+			// Lead branches are never merged, so .sprout/ files would otherwise be lost.
+			if (isLead && wt.branch.length > 0) {
+				const result = await preserveSproutChanges(
+					root,
+					wt.branch,
+					canonicalBranch,
+					session?.agentName ?? "unknown-lead",
+				);
+				if (result.preserved) {
+					sproutPreserved.push(wt.branch);
+					if (!json) {
+						printSuccess("Preserved .sprout/ changes", session?.agentName ?? "unknown-lead");
+					}
+				} else if (result.error) {
+					printWarning(`Failed to preserve .sprout/ from ${wt.branch}`, result.error);
+				}
+			}
+
+			// Remove worktree and its branch.
+			// Always force worktree removal since deployed .claude/ files create untracked
+			// files that cause non-forced removal to fail.
+			// Always force-delete the branch since we're cleaning up finished/zombie agents
+			// whose branches are typically unmerged.
+			try {
+				await removeWorktree(root, wt.path, { force: true, forceBranch: true });
+				cleaned.push(wt.branch);
+
+				if (!json) {
+					printSuccess("Removed", wt.branch);
+				}
+			} catch (err) {
+				failed.push(wt.branch);
+				if (!json) {
+					const msg = err instanceof Error ? err.message : String(err);
+					printWarning(`Failed to remove ${wt.branch}`, msg);
+				}
+			}
+		}
+
+		// Purge mail for cleaned agents
+		let mailPurged = 0;
+		if (cleaned.length > 0) {
+			const mailDbPath = join(root, ".agentplate", "mail.db");
+			const mailDbFile = Bun.file(mailDbPath);
+			if (await mailDbFile.exists()) {
+				const mailStore = createMailStore(mailDbPath);
+				try {
+					for (const branch of cleaned) {
+						const session = sessions.find((s) => s.branchName === branch);
+						if (session) {
+							mailPurged += mailStore.purge({ agent: session.agentName });
+						}
+					}
+				} finally {
+					mailStore.close();
+				}
+			}
+		}
+
+		// Mark cleaned sessions as zombie in the SessionStore
+		for (const branch of cleaned) {
+			const session = sessions.find((s) => s.branchName === branch);
+			if (session) {
+				store.updateState(session.agentName, "zombie");
+			}
+		}
+
+		// Prune zombie entries whose worktree paths no longer exist on disk.
+		// This prevents the session store from growing unbounded with stale entries.
+		const remainingWorktrees = await listWorktrees(root);
+		const worktreePaths = new Set(remainingWorktrees.map((wt) => wt.path));
+		let pruneCount = 0;
+
+		// Re-read sessions after state updates to get current zombie list
+		const currentSessions = store.getAll();
+		for (const session of currentSessions) {
+			if (session.state === "zombie" && !worktreePaths.has(session.worktreePath)) {
+				store.remove(session.agentName);
+				pruneCount++;
+			}
+		}
+
+		if (json) {
+			jsonOutput("worktree clean", {
+				cleaned,
+				failed,
+				skipped,
+				blockedByChildren,
+				pruned: pruneCount,
+				mailPurged,
+				sproutPreserved,
+			});
+		} else if (
+			cleaned.length === 0 &&
+			pruneCount === 0 &&
+			failed.length === 0 &&
+			skipped.length === 0 &&
+			blockedByChildren.length === 0 &&
+			sproutPreserved.length === 0
+		) {
+			printHint("No worktrees to clean");
+		} else {
+			if (cleaned.length > 0) {
+				printSuccess(`Cleaned ${cleaned.length} worktree${cleaned.length === 1 ? "" : "s"}`);
+			}
+			if (failed.length > 0) {
+				printWarning(`Failed to clean ${failed.length} worktree${failed.length === 1 ? "" : "s"}`);
+			}
+			if (mailPurged > 0) {
+				printSuccess(
+					`Purged ${mailPurged} mail message${mailPurged === 1 ? "" : "s"} from cleaned agents`,
+				);
+			}
+			if (pruneCount > 0) {
+				printSuccess(
+					`Pruned ${pruneCount} zombie session${pruneCount === 1 ? "" : "s"} from store`,
+				);
+			}
+			if (sproutPreserved.length > 0) {
+				printSuccess(
+					`Preserved .sprout/ from ${sproutPreserved.length} lead${sproutPreserved.length === 1 ? "" : "s"}`,
+				);
+			}
+			if (skipped.length > 0) {
+				printWarning(
+					`Skipped ${skipped.length} worktree${skipped.length === 1 ? "" : "s"} with unmerged branches`,
+				);
+				for (const branch of skipped) {
+					process.stdout.write(`  ${branch}\n`);
+				}
+				printHint("Use --force to delete unmerged branches");
+			}
+			if (blockedByChildren.length > 0) {
+				printWarning(
+					`Skipped ${blockedByChildren.length} worktree${blockedByChildren.length === 1 ? "" : "s"} with live child agents`,
+				);
+				for (const branch of blockedByChildren) {
+					process.stdout.write(`  ${branch}\n`);
+				}
+				printHint("Use --force to cascade-terminate live children");
+			}
+		}
+	} finally {
+		store.close();
+	}
+}
+
+export function createWorktreeCommand(): Command {
+	const cmd = new Command("worktree").description("Manage agent worktrees");
+
+	cmd
+		.command("list")
+		.description("List worktrees with agent status")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			await handleList(config.project.root, opts.json ?? false);
+		});
+
+	cmd
+		.command("clean")
+		.description("Remove completed worktrees")
+		.option("--completed", "Only finished agents (default)")
+		.option("--all", "Force remove all worktrees")
+		.option("--force", "Delete even if branches are unmerged")
+		.option("--json", "Output as JSON")
+		.action(
+			async (opts: { completed?: boolean; all?: boolean; force?: boolean; json?: boolean }) => {
+				const cwd = process.cwd();
+				const config = await loadConfig(cwd);
+				const all = opts.all ?? false;
+				await handleClean(
+					{
+						all,
+						force: opts.force ?? false,
+						completedOnly: opts.completed ?? !all,
+					},
+					config.project.root,
+					opts.json ?? false,
+					config.project.canonicalBranch,
+				);
+			},
+		);
+
+	return cmd;
+}
+
+/**
+ * Entry point for `ap worktree <subcommand> [flags]`.
+ *
+ * Subcommands: list, clean.
+ */
+export async function worktreeCommand(args: string[]): Promise<void> {
+	const cmd = createWorktreeCommand();
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
+		return;
+	}
+
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+			if (code === "commander.unknownCommand") {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "subcommand" });
+			}
+		}
+		throw err;
+	}
+}