@katyella/legio 0.1.0

package/src/commands/stop.ts

@@ -0,0 +1,119 @@
+/**
+ * CLI command: legio stop
+ *
+ * Stops active agent sessions deepest-first (leaf agents before parents).
+ * Kills each agent's tmux session and marks the session as completed in
+ * the session store.
+ *
+ * If --agent <name> is provided, stops only that specific agent.
+ * Otherwise stops all active sessions (state: booting, working, stalled).
+ *
+ * Uses DI (StopDeps._tmux) for tmux operations, matching coordinator.ts pattern.
+ */
+
+import { join } from "node:path";
+import { loadConfig } from "../config.ts";
+import { AgentError } from "../errors.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import { isSessionAlive, killSession } from "../worktree/tmux.ts";
+
+function hasFlag(args: string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+function getFlagValue(args: string[], flag: string): string | undefined {
+	const idx = args.indexOf(flag);
+	if (idx === -1) return undefined;
+	return args[idx + 1];
+}
+
+/** Dependency injection interface for testing. */
+export interface StopDeps {
+	_tmux?: {
+		isSessionAlive: (name: string) => Promise<boolean>;
+		killSession: (name: string) => Promise<void>;
+	};
+	_projectRoot?: string;
+}
+
+const STOP_HELP = `legio stop — Stop active agent sessions
+
+Usage: legio stop [options]
+
+Options:
+  --agent <name>  Stop only the named agent (default: stop all active agents)
+  --json          JSON output
+  --help, -h      Show this help
+
+Agents are stopped deepest-first (leaf agents before their parents).
+Running legio stop when no agents are active is a safe no-op.`;
+
+/**
+ * Entry point for \`legio stop [options]\`.
+ *
+ * @param args - CLI arguments after "stop"
+ * @param deps - Optional dependency injection for testing
+ */
+export async function stopCommand(args: string[], deps: StopDeps = {}): Promise<void> {
+	if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+		process.stdout.write(`${STOP_HELP}\n`);
+		return;
+	}
+
+	const json = hasFlag(args, "--json");
+	const agentFilter = getFlagValue(args, "--agent");
+	const tmux = deps._tmux ?? { isSessionAlive, killSession };
+	const projectRoot = deps._projectRoot ?? process.cwd();
+
+	const config = await loadConfig(projectRoot);
+	const legioDir = join(config.project.root, ".legio");
+	const { store } = openSessionStore(legioDir);
+
+	try {
+		const sessions = agentFilter
+			? (() => {
+					const session = store.getByName(agentFilter);
+					if (!session) {
+						throw new AgentError(`No session found for agent '${agentFilter}'`, {
+							agentName: agentFilter,
+						});
+					}
+					return [session];
+				})()
+			: store.getActive();
+
+		if (sessions.length === 0) {
+			if (json) {
+				process.stdout.write(`${JSON.stringify({ stopped: [], nothingToStop: true })}\n`);
+			} else {
+				process.stdout.write("Nothing to stop\n");
+			}
+			return;
+		}
+
+		// Sort deepest-first: leaf agents die before their parents
+		const sorted = [...sessions].sort((a, b) => b.depth - a.depth);
+
+		const stopped: string[] = [];
+
+		for (const session of sorted) {
+			const alive = await tmux.isSessionAlive(session.tmuxSession);
+			if (alive) {
+				await tmux.killSession(session.tmuxSession);
+			}
+			store.updateState(session.agentName, "completed");
+			stopped.push(session.agentName);
+			if (!json) {
+				process.stdout.write(`Stopped: ${session.agentName} (${session.tmuxSession})\n`);
+			}
+		}
+
+		if (json) {
+			process.stdout.write(`${JSON.stringify({ stopped, nothingToStop: false })}\n`);
+		} else {
+			process.stdout.write(`Stopped ${stopped.length} agent${stopped.length === 1 ? "" : "s"}\n`);
+		}
+	} finally {
+		store.close();
+	}
+}

package/src/commands/supervisor.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, test } from "vitest";
+import { buildSupervisorBeacon, supervisorCommand } from "./supervisor.ts";
+
+/**
+ * Tests for supervisor command functions.
+ *
+ * Session persistence is now handled by SessionStore (SQLite).
+ * Those tests live in src/sessions/store.test.ts and src/sessions/compat.test.ts.
+ * Here we test beacon generation.
+ */
+
+describe("buildSupervisorBeacon", () => {
+	test("contains agent name and beadId from opts", () => {
+		const beacon = buildSupervisorBeacon({
+			name: "supervisor-1",
+			beadId: "task-abc123",
+			depth: 1,
+			parent: "coordinator",
+		});
+
+		expect(beacon).toContain("supervisor-1");
+		expect(beacon).toContain("task-abc123");
+	});
+
+	test("contains [LEGIO] prefix", () => {
+		const beacon = buildSupervisorBeacon({
+			name: "supervisor-1",
+			beadId: "task-1",
+			depth: 1,
+			parent: "coordinator",
+		});
+
+		expect(beacon).toContain("[LEGIO]");
+	});
+
+	test("contains (supervisor) designation", () => {
+		const beacon = buildSupervisorBeacon({
+			name: "supervisor-1",
+			beadId: "task-1",
+			depth: 1,
+			parent: "coordinator",
+		});
+
+		expect(beacon).toContain("(supervisor)");
+	});
+
+	test("contains depth and parent info from opts", () => {
+		const beacon = buildSupervisorBeacon({
+			name: "supervisor-1",
+			beadId: "task-1",
+			depth: 2,
+			parent: "lead-cli",
+		});
+
+		expect(beacon).toContain("Depth: 2");
+		expect(beacon).toContain("Parent: lead-cli");
+	});
+
+	test("contains startup instructions", () => {
+		const beacon = buildSupervisorBeacon({
+			name: "supervisor-1",
+			beadId: "task-1",
+			depth: 1,
+			parent: "coordinator",
+		});
+
+		// Should include mulch prime
+		expect(beacon).toContain("mulch prime");
+
+		// Should include mail check with agent name
+		expect(beacon).toContain("legio mail check --agent supervisor-1");
+
+		// Should include bd show with beadId
+		expect(beacon).toContain("bd show task-1");
+	});
+
+	test("contains ISO timestamp", () => {
+		const before = new Date();
+		const beacon = buildSupervisorBeacon({
+			name: "supervisor-1",
+			beadId: "task-1",
+			depth: 1,
+			parent: "coordinator",
+		});
+		const after = new Date();
+
+		// Extract timestamp from beacon (format: [LEGIO] {name} (supervisor) {timestamp} task:{beadId})
+		const timestampMatch = beacon.match(/\(supervisor\)\s+(\S+)\s+task:/);
+		expect(timestampMatch).toBeTruthy();
+
+		if (timestampMatch?.[1]) {
+			const timestamp = new Date(timestampMatch[1]);
+			expect(timestamp.getTime()).toBeGreaterThanOrEqual(before.getTime());
+			expect(timestamp.getTime()).toBeLessThanOrEqual(after.getTime());
+
+			// Verify ISO format (should parse correctly)
+			expect(timestamp.toISOString()).toBeTruthy();
+		}
+	});
+});
+
+describe("supervisorCommand", () => {
+	test("--help prints help containing required keywords", async () => {
+		const originalWrite = process.stdout.write;
+		let output = "";
+		process.stdout.write = ((chunk: string) => {
+			output += chunk;
+			return true;
+		}) as typeof process.stdout.write;
+
+		try {
+			await supervisorCommand(["--help"]);
+			expect(output).toContain("legio supervisor");
+			expect(output).toContain("start");
+			expect(output).toContain("stop");
+			expect(output).toContain("status");
+			expect(output).toContain("--task");
+			expect(output).toContain("--name");
+		} finally {
+			process.stdout.write = originalWrite;
+		}
+	});
+
+	test("-h prints help", async () => {
+		const originalWrite = process.stdout.write;
+		let output = "";
+		process.stdout.write = ((chunk: string) => {
+			output += chunk;
+			return true;
+		}) as typeof process.stdout.write;
+
+		try {
+			await supervisorCommand(["-h"]);
+			expect(output).toContain("legio supervisor");
+		} finally {
+			process.stdout.write = originalWrite;
+		}
+	});
+
+	test("empty args [] shows help", async () => {
+		const originalWrite = process.stdout.write;
+		let output = "";
+		process.stdout.write = ((chunk: string) => {
+			output += chunk;
+			return true;
+		}) as typeof process.stdout.write;
+
+		try {
+			await supervisorCommand([]);
+			expect(output).toContain("legio supervisor");
+		} finally {
+			process.stdout.write = originalWrite;
+		}
+	});
+
+	test("unknown subcommand throws ValidationError with bad value in message", async () => {
+		await expect(supervisorCommand(["invalid-subcommand"])).rejects.toThrow(/invalid-subcommand/);
+	});
+
+	test("start without --task throws ValidationError", async () => {
+		await expect(supervisorCommand(["start", "--name", "supervisor-1"])).rejects.toThrow(/--task/);
+	});
+
+	test("start without --name throws ValidationError", async () => {
+		await expect(supervisorCommand(["start", "--task", "task-1"])).rejects.toThrow(/--name/);
+	});
+
+	test("stop without --name throws ValidationError", async () => {
+		await expect(supervisorCommand(["stop"])).rejects.toThrow(/--name/);
+	});
+
+	test("start throws ValidationError with uid field when running as root", async () => {
+		const original = process.getuid;
+		process.getuid = () => 0;
+		try {
+			await expect(
+				supervisorCommand(["start", "--task", "legio-test", "--name", "sup-1"]),
+			).rejects.toMatchObject({
+				name: "ValidationError",
+				field: "uid",
+			});
+		} finally {
+			process.getuid = original;
+		}
+	});
+});