@ag-eco/agentplate-cli 0.13.0

package/src/commands/run.ts

@@ -0,0 +1,353 @@
+/**
+ * CLI command: agentplate run [subcommand] [--json]
+ *
+ * Manage runs (coordinator session groupings).
+ * A "run" groups all agents spawned from one coordinator session.
+ *
+ * Subcommands:
+ *   (default)     Show current run status
+ *   list          List recent runs
+ *   complete      Mark current run as completed
+ *   show <id>     Show run details with agents
+ */
+
+import { join } from "node:path";
+import { Command, CommanderError } from "commander";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonError, jsonOutput } from "../json.ts";
+import { accent, printError, printHint, printSuccess } from "../logging/color.ts";
+import { formatDuration } from "../logging/format.ts";
+import { renderHeader, separator } from "../logging/theme.ts";
+import { createRunStore, createSessionStore } from "../sessions/store.ts";
+import type { AgentSession, Run } from "../types.ts";
+
+/**
+ * Get the path to the current-run.txt file.
+ */
+function currentRunPath(agentplateDir: string): string {
+	return join(agentplateDir, "current-run.txt");
+}
+
+/**
+ * Read the current run ID from current-run.txt, or null if no active run.
+ */
+async function readCurrentRunId(agentplateDir: string): Promise<string | null> {
+	const path = currentRunPath(agentplateDir);
+	const file = Bun.file(path);
+	if (!(await file.exists())) {
+		return null;
+	}
+	const text = await file.text();
+	const trimmed = text.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Compute duration string for a run.
+ */
+function runDuration(run: Run): string {
+	const start = new Date(run.startedAt).getTime();
+	const end = run.completedAt ? new Date(run.completedAt).getTime() : Date.now();
+	return formatDuration(end - start);
+}
+
+/**
+ * Format an agent's duration from startedAt to now (or completion).
+ */
+function formatAgentDuration(agent: AgentSession): string {
+	const start = new Date(agent.startedAt).getTime();
+	const end =
+		agent.state === "completed" || agent.state === "zombie"
+			? new Date(agent.lastActivity).getTime()
+			: Date.now();
+	return formatDuration(end - start);
+}
+
+/**
+ * Show current run status (default subcommand).
+ */
+async function showCurrentRun(agentplateDir: string, json: boolean): Promise<void> {
+	const runId = await readCurrentRunId(agentplateDir);
+	if (!runId) {
+		if (json) {
+			jsonOutput("run", { run: null, message: "No active run" });
+		} else {
+			printHint("No active run");
+		}
+		return;
+	}
+
+	const dbPath = join(agentplateDir, "sessions.db");
+	const runStore = createRunStore(dbPath);
+	try {
+		const run = runStore.getRun(runId);
+		if (!run) {
+			if (json) {
+				jsonOutput("run", { run: null, message: `Run ${runId} not found in store` });
+			} else {
+				process.stdout.write(`Run ${accent(runId)} not found in store\n`);
+			}
+			return;
+		}
+
+		if (json) {
+			jsonOutput("run", { run, duration: runDuration(run) });
+			return;
+		}
+
+		process.stdout.write(`${renderHeader("Current Run")}\n`);
+		process.stdout.write(`  ID:       ${accent(run.id)}\n`);
+		process.stdout.write(`  Status:   ${run.status}\n`);
+		process.stdout.write(`  Started:  ${run.startedAt}\n`);
+		process.stdout.write(`  Agents:   ${run.agentCount}\n`);
+		process.stdout.write(`  Duration: ${runDuration(run)}\n`);
+	} finally {
+		runStore.close();
+	}
+}
+
+/**
+ * List recent runs.
+ */
+async function listRuns(agentplateDir: string, limit: number, json: boolean): Promise<void> {
+	const dbPath = join(agentplateDir, "sessions.db");
+	const dbFile = Bun.file(dbPath);
+	if (!(await dbFile.exists())) {
+		if (json) {
+			jsonOutput("run list", { runs: [] });
+		} else {
+			printHint("No runs recorded yet");
+		}
+		return;
+	}
+
+	const runStore = createRunStore(dbPath);
+	try {
+		const runs = runStore.listRuns({ limit });
+
+		if (json) {
+			const runsWithDuration = runs.map((r) => ({ ...r, duration: runDuration(r) }));
+			jsonOutput("run list", { runs: runsWithDuration });
+			return;
+		}
+
+		if (runs.length === 0) {
+			printHint("No runs recorded yet");
+			return;
+		}
+
+		process.stdout.write(`${renderHeader("Recent Runs")}\n`);
+		process.stdout.write(
+			`${"ID".padEnd(36)} ${"Status".padEnd(10)} ${"Agents".padEnd(7)} Duration\n`,
+		);
+		process.stdout.write(`${separator()}\n`);
+
+		for (const run of runs) {
+			const id = accent(run.id.length > 35 ? `${run.id.slice(0, 32)}...` : run.id.padEnd(36));
+			const status = run.status.padEnd(10);
+			const agents = String(run.agentCount).padEnd(7);
+			const duration = runDuration(run);
+			process.stdout.write(`${id} ${status} ${agents} ${duration}\n`);
+		}
+	} finally {
+		runStore.close();
+	}
+}
+
+/**
+ * Mark the current run as completed.
+ */
+async function completeCurrentRun(agentplateDir: string, json: boolean): Promise<void> {
+	const runId = await readCurrentRunId(agentplateDir);
+	if (!runId) {
+		if (json) {
+			jsonError("run complete", "No active run to complete");
+		} else {
+			printError("No active run to complete");
+		}
+		process.exitCode = 1;
+		return;
+	}
+
+	const dbPath = join(agentplateDir, "sessions.db");
+	const runStore = createRunStore(dbPath);
+	try {
+		runStore.completeRun(runId, "completed");
+	} finally {
+		runStore.close();
+	}
+
+	// Delete current-run.txt
+	const { unlink } = await import("node:fs/promises");
+	try {
+		await unlink(currentRunPath(agentplateDir));
+	} catch {
+		// File may already be gone, that's fine
+	}
+
+	if (json) {
+		jsonOutput("run complete", { runId, status: "completed" });
+	} else {
+		printSuccess("Run completed", runId);
+	}
+}
+
+/**
+ * Show detailed information for a specific run.
+ */
+async function showRun(agentplateDir: string, runId: string, json: boolean): Promise<void> {
+	const dbPath = join(agentplateDir, "sessions.db");
+	const dbFile = Bun.file(dbPath);
+	if (!(await dbFile.exists())) {
+		if (json) {
+			jsonError("run show", `Run ${runId} not found`);
+		} else {
+			printError("Run not found", runId);
+		}
+		process.exitCode = 1;
+		return;
+	}
+
+	const runStore = createRunStore(dbPath);
+	const sessionStore = createSessionStore(dbPath);
+	try {
+		const run = runStore.getRun(runId);
+		if (!run) {
+			if (json) {
+				jsonError("run show", `Run ${runId} not found`);
+			} else {
+				printError("Run not found", runId);
+			}
+			process.exitCode = 1;
+			return;
+		}
+
+		const agents = sessionStore.getByRun(runId);
+
+		if (json) {
+			jsonOutput("run show", { run, duration: runDuration(run), agents });
+			return;
+		}
+
+		process.stdout.write(`${renderHeader("Run Details")}\n`);
+		process.stdout.write(`  ID:       ${accent(run.id)}\n`);
+		process.stdout.write(`  Status:   ${run.status}\n`);
+		process.stdout.write(`  Started:  ${run.startedAt}\n`);
+		if (run.completedAt) {
+			process.stdout.write(`  Ended:    ${run.completedAt}\n`);
+		}
+		process.stdout.write(`  Agents:   ${run.agentCount}\n`);
+		process.stdout.write(`  Duration: ${runDuration(run)}\n`);
+
+		if (agents.length > 0) {
+			process.stdout.write(`\nAgents (${agents.length}):\n`);
+			process.stdout.write(`${separator()}\n`);
+			for (const agent of agents) {
+				const agentDuration = formatAgentDuration(agent);
+				process.stdout.write(
+					`  ${accent(agent.agentName)} [${agent.capability}] ${agent.state} | ${agentDuration}\n`,
+				);
+			}
+		} else {
+			process.stdout.write("\nNo agents recorded for this run.\n");
+		}
+	} finally {
+		runStore.close();
+		sessionStore.close();
+	}
+}
+
+interface RunDefaultOpts {
+	json?: boolean;
+}
+
+interface RunListOpts {
+	last?: string;
+	json?: boolean;
+}
+
+interface RunShowOpts {
+	json?: boolean;
+}
+
+interface RunCompleteOpts {
+	json?: boolean;
+}
+
+export function createRunCommand(): Command {
+	const cmd = new Command("run").description("Manage runs (coordinator session groupings)");
+
+	// Default action (bare `agentplate run`)
+	cmd.option("--json", "Output as JSON").action(async (opts: RunDefaultOpts) => {
+		const cwd = process.cwd();
+		const config = await loadConfig(cwd);
+		const agentplateDir = join(config.project.root, ".agentplate");
+		await showCurrentRun(agentplateDir, opts.json ?? false);
+	});
+
+	// `agentplate run list`
+	cmd
+		.command("list")
+		.description("List recent runs")
+		.option("--last <n>", "Number of recent runs to show (default: 10)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: RunListOpts) => {
+			const lastStr = opts.last;
+			const limit = lastStr ? Number.parseInt(lastStr, 10) : 10;
+			if (Number.isNaN(limit) || limit < 1) {
+				throw new ValidationError("--last must be a positive integer", {
+					field: "last",
+					value: lastStr,
+				});
+			}
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			const agentplateDir = join(config.project.root, ".agentplate");
+			await listRuns(agentplateDir, limit, opts.json ?? false);
+		});
+
+	// `agentplate run show <id>`
+	cmd
+		.command("show")
+		.description("Show run details (agents, duration)")
+		.argument("<id>", "Run ID")
+		.option("--json", "Output as JSON")
+		.action(async (id: string, opts: RunShowOpts) => {
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			const agentplateDir = join(config.project.root, ".agentplate");
+			await showRun(agentplateDir, id, opts.json ?? false);
+		});
+
+	// `agentplate run complete`
+	cmd
+		.command("complete")
+		.description("Mark current run as completed")
+		.option("--json", "Output as JSON")
+		.action(async (opts: RunCompleteOpts) => {
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			const agentplateDir = join(config.project.root, ".agentplate");
+			await completeCurrentRun(agentplateDir, opts.json ?? false);
+		});
+
+	return cmd;
+}
+
+export async function runCommand(args: string[]): Promise<void> {
+	const program = new Command("ap").exitOverride().configureOutput({
+		writeOut: (str) => process.stdout.write(str),
+		writeErr: (str) => process.stderr.write(str),
+	});
+	program.addCommand(createRunCommand());
+	try {
+		await program.parseAsync(["node", "ap", "run", ...args]);
+	} catch (err: unknown) {
+		if (err instanceof CommanderError) {
+			if (err.code === "commander.helpDisplayed" || err.code === "commander.version") return;
+			throw new ValidationError(err.message, { field: "args" });
+		}
+		throw err;
+	}
+}

package/src/commands/serve/agent-actions.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Tests for the fleet-control action wrappers (sling / stop / merge).
+ *
+ * Uses a real file-backed SessionStore and dependency-injected fakes for the
+ * heavy command cores (slingCommand / stopCommand / mergeCommand /
+ * predictConflicts) so no agents are spawned and git is never touched.
+ *
+ * mock.module() is intentionally avoided per loam record mx-56558b.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ValidationError } from "../../errors.ts";
+import type { SessionStore } from "../../sessions/store.ts";
+import { createSessionStore } from "../../sessions/store.ts";
+import type { AgentplateConfig, AgentSession, ConflictPrediction } from "../../types.ts";
+import {
+	type AgentActionDeps,
+	mergePreview,
+	mergeRun,
+	slingAgent,
+	stopAgent,
+} from "./agent-actions.ts";
+
+interface Ctx {
+	tempDir: string;
+	sessionStore: SessionStore;
+	deps: AgentActionDeps;
+}
+
+function makeSession(name: string, overrides: Partial<AgentSession> = {}): AgentSession {
+	const now = new Date().toISOString();
+	return {
+		id: `session-${name}`,
+		agentName: name,
+		capability: "builder",
+		worktreePath: "/tmp/wt",
+		branchName: `agentplate/${name}/t1`,
+		taskId: "t1",
+		tmuxSession: "",
+		state: "working",
+		pid: 12345,
+		parentAgent: null,
+		depth: 0,
+		runId: "run-1",
+		startedAt: now,
+		lastActivity: now,
+		escalationLevel: 0,
+		stalledSince: null,
+		transcriptPath: null,
+		...overrides,
+	};
+}
+
+function makeCtx(): Ctx {
+	const tempDir = mkdtempSync(join(tmpdir(), "ap-agent-actions-"));
+	const sessionStore = createSessionStore(join(tempDir, "sessions.db"));
+	return {
+		tempDir,
+		sessionStore,
+		deps: { projectRoot: tempDir, _sessionStore: sessionStore },
+	};
+}
+
+describe("agent-actions", () => {
+	let ctx: Ctx;
+
+	beforeEach(() => {
+		ctx = makeCtx();
+	});
+
+	afterEach(() => {
+		ctx.sessionStore.close();
+		rmSync(ctx.tempDir, { recursive: true, force: true });
+	});
+
+	// ─── slingAgent ─────────────────────────────────────────────────────────
+
+	test("slingAgent forces headless + json and reads back the created session", async () => {
+		let calledTaskId: string | null = null;
+		let calledOpts: Record<string, unknown> | null = null;
+		const deps: AgentActionDeps = {
+			...ctx.deps,
+			_slingCommand: async (taskId, opts) => {
+				calledTaskId = taskId;
+				calledOpts = opts as Record<string, unknown>;
+				// Simulate the spawn writing a session row.
+				ctx.sessionStore.upsert(makeSession("builder-t1", { state: "booting" }));
+			},
+		};
+
+		const result = await slingAgent(deps, { taskId: "t1", capability: "builder" });
+
+		expect(calledTaskId as string | null).toBe("t1");
+		expect(calledOpts).toMatchObject({ json: true, headless: true, capability: "builder" });
+		expect(result).toEqual({ agentName: "builder-t1", state: "booting", spawned: true });
+	});
+
+	test("slingAgent honors an explicit name", async () => {
+		const deps: AgentActionDeps = {
+			...ctx.deps,
+			_slingCommand: async () => {
+				ctx.sessionStore.upsert(makeSession("custom", { capability: "scout" }));
+			},
+		};
+		const result = await slingAgent(deps, { taskId: "t1", capability: "scout", name: "custom" });
+		expect(result.agentName).toBe("custom");
+		expect(result.spawned).toBe(true);
+	});
+
+	test("slingAgent rejects a missing taskId", async () => {
+		await expect(slingAgent(ctx.deps, { taskId: "  " })).rejects.toBeInstanceOf(ValidationError);
+	});
+
+	// ─── stopAgent ──────────────────────────────────────────────────────────
+
+	test("stopAgent invokes stopCommand with json + cleanWorktree", async () => {
+		let calledName: string | null = null;
+		let calledOpts: Record<string, unknown> | null = null;
+		const deps: AgentActionDeps = {
+			...ctx.deps,
+			_stopCommand: async (name, opts) => {
+				calledName = name;
+				calledOpts = opts as Record<string, unknown>;
+			},
+		};
+		const result = await stopAgent(deps, "builder-t1", { cleanWorktree: true });
+		expect(calledName as string | null).toBe("builder-t1");
+		expect(calledOpts).toMatchObject({ json: true, cleanWorktree: true });
+		expect(result).toEqual({ stopped: true, agentName: "builder-t1" });
+	});
+
+	test("stopAgent rejects an empty name", async () => {
+		await expect(stopAgent(ctx.deps, "   ")).rejects.toBeInstanceOf(ValidationError);
+	});
+
+	// ─── mergePreview ─────────────────────────────────────────────────────────
+
+	test("mergePreview uses the explicit target and returns the prediction", async () => {
+		const prediction: ConflictPrediction = {
+			predictedTier: "clean-merge",
+			conflictFiles: [],
+			wouldRequireAgent: false,
+			reason: "no conflicts",
+		};
+		let predictTarget: string | null = null;
+		const deps: AgentActionDeps = {
+			...ctx.deps,
+			_predictConflicts: async (entry, canonicalBranch) => {
+				predictTarget = canonicalBranch;
+				expect(entry.branchName).toBe("agentplate/builder-t1/t1");
+				return prediction;
+			},
+		};
+		const result = await mergePreview(deps, {
+			branch: "agentplate/builder-t1/t1",
+			into: "develop",
+		});
+		expect(predictTarget as string | null).toBe("develop");
+		expect(result).toMatchObject({
+			predictedTier: "clean-merge",
+			branch: "agentplate/builder-t1/t1",
+			target: "develop",
+		});
+	});
+
+	test("mergePreview falls back to config canonicalBranch when no target given", async () => {
+		const deps: AgentActionDeps = {
+			...ctx.deps,
+			_loadConfig: async () =>
+				({ project: { root: ctx.tempDir, canonicalBranch: "main" } }) as AgentplateConfig,
+			_predictConflicts: async (_entry, canonicalBranch) => {
+				expect(canonicalBranch).toBe("main");
+				return {
+					predictedTier: "clean-merge",
+					conflictFiles: [],
+					wouldRequireAgent: false,
+					reason: "ok",
+				};
+			},
+		};
+		const result = await mergePreview(deps, { branch: "agentplate/x/y" });
+		expect(result.target).toBe("main");
+	});
+
+	test("mergePreview rejects a missing branch", async () => {
+		await expect(mergePreview(ctx.deps, { branch: "" })).rejects.toBeInstanceOf(ValidationError);
+	});
+
+	// ─── mergeRun ───────────────────────────────────────────────────────────
+
+	test("mergeRun forwards branch to mergeCommand", async () => {
+		let calledOpts: Record<string, unknown> | null = null;
+		const deps: AgentActionDeps = {
+			...ctx.deps,
+			_mergeCommand: async (opts) => {
+				calledOpts = opts as Record<string, unknown>;
+			},
+		};
+		const result = await mergeRun(deps, { branch: "agentplate/x/y" });
+		expect(calledOpts).toMatchObject({ json: true, branch: "agentplate/x/y" });
+		expect(result).toEqual({ triggered: true });
+	});
+
+	test("mergeRun rejects when neither branch nor all is provided", async () => {
+		await expect(mergeRun(ctx.deps, {})).rejects.toBeInstanceOf(ValidationError);
+	});
+});