@katyella/legio 0.1.0

package/src/commands/spec.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Tests for the `legio spec` command.
+ *
+ * Uses real filesystem (temp dirs) for all tests. No mocks.
+ * Philosophy: "never mock what you can use for real" (mx-252b16).
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import { specCommand, writeSpec } from "./spec.ts";
+
+let tempDir: string;
+let legioDir: string;
+let originalCwd: string;
+let stdoutOutput: string;
+let _stderrOutput: string;
+let originalStdoutWrite: typeof process.stdout.write;
+let originalStderrWrite: typeof process.stderr.write;
+let originalIsTTY: boolean | undefined;
+
+beforeEach(async () => {
+	// Force stdin.isTTY so readStdin() returns immediately instead of blocking
+	originalIsTTY = process.stdin.isTTY;
+	process.stdin.isTTY = true;
+	tempDir = await createTempGitRepo();
+	legioDir = join(tempDir, ".legio");
+	await mkdir(legioDir, { recursive: true });
+
+	// Write minimal config.yaml so resolveProjectRoot works
+	await writeFile(
+		join(legioDir, "config.yaml"),
+		`project:\n  name: test-project\n  root: ${tempDir}\n  canonicalBranch: main\n`,
+	);
+
+	originalCwd = process.cwd();
+	process.chdir(tempDir);
+
+	// Capture stdout/stderr
+	stdoutOutput = "";
+	_stderrOutput = "";
+	originalStdoutWrite = process.stdout.write;
+	originalStderrWrite = process.stderr.write;
+	process.stdout.write = ((chunk: string) => {
+		stdoutOutput += chunk;
+		return true;
+	}) as typeof process.stdout.write;
+	process.stderr.write = ((chunk: string) => {
+		_stderrOutput += chunk;
+		return true;
+	}) as typeof process.stderr.write;
+});
+
+afterEach(async () => {
+	process.stdin.isTTY = originalIsTTY as true;
+	process.chdir(originalCwd);
+	process.stdout.write = originalStdoutWrite;
+	process.stderr.write = originalStderrWrite;
+	await cleanupTempDir(tempDir);
+});
+
+// === help ===
+
+describe("help", () => {
+	test("--help shows usage", async () => {
+		await specCommand(["--help"]);
+		expect(stdoutOutput).toContain("legio spec");
+		expect(stdoutOutput).toContain("write");
+		expect(stdoutOutput).toContain("--body");
+		expect(stdoutOutput).toContain("--agent");
+	});
+
+	test("-h shows usage", async () => {
+		await specCommand(["-h"]);
+		expect(stdoutOutput).toContain("legio spec");
+	});
+
+	test("no args shows help", async () => {
+		await specCommand([]);
+		expect(stdoutOutput).toContain("legio spec");
+	});
+});
+
+// === validation ===
+
+describe("validation", () => {
+	test("unknown subcommand throws ValidationError", async () => {
+		await expect(specCommand(["unknown"])).rejects.toThrow("Unknown spec subcommand");
+	});
+
+	test("write without bead-id throws ValidationError", async () => {
+		await expect(specCommand(["write"])).rejects.toThrow("Bead ID is required");
+	});
+
+	test("write without body throws ValidationError", async () => {
+		await expect(specCommand(["write", "task-abc", "--agent", "scout-1"])).rejects.toThrow(
+			"Spec body is required",
+		);
+	});
+
+	test("write with empty body throws ValidationError", async () => {
+		await expect(specCommand(["write", "task-abc", "--body", "  "])).rejects.toThrow(
+			"Spec body is required",
+		);
+	});
+});
+
+// === writeSpec (core function) ===
+
+describe("writeSpec", () => {
+	test("writes spec file to .legio/specs/<bead-id>.md", async () => {
+		const specPath = await writeSpec(tempDir, "task-abc", "# My Spec\n\nDetails here.");
+
+		expect(specPath).toBe(join(tempDir, ".legio", "specs", "task-abc.md"));
+
+		const content = await readFile(specPath, "utf-8");
+		expect(content).toBe("# My Spec\n\nDetails here.\n");
+	});
+
+	test("creates specs directory if it does not exist", async () => {
+		// Verify specs dir does not exist yet (no .gitkeep check needed)
+		await writeSpec(tempDir, "task-xyz", "content");
+
+		const specsDir = join(legioDir, "specs");
+		const content = await readFile(join(specsDir, "task-xyz.md"), "utf-8");
+		expect(content).toBe("content\n");
+	});
+
+	test("adds attribution header when agent is provided", async () => {
+		const specPath = await writeSpec(tempDir, "task-123", "# Spec body", "scout-1");
+
+		const content = await readFile(specPath, "utf-8");
+		expect(content).toContain("<!-- written-by: scout-1 -->");
+		expect(content).toContain("# Spec body");
+	});
+
+	test("does not add attribution header when agent is omitted", async () => {
+		const specPath = await writeSpec(tempDir, "task-456", "# Spec body");
+
+		const content = await readFile(specPath, "utf-8");
+		expect(content).not.toContain("written-by");
+		expect(content).toBe("# Spec body\n");
+	});
+
+	test("ensures trailing newline", async () => {
+		const specPath = await writeSpec(tempDir, "task-nl", "no newline at end");
+
+		const content = await readFile(specPath, "utf-8");
+		expect(content.endsWith("\n")).toBe(true);
+	});
+
+	test("does not double trailing newline", async () => {
+		const specPath = await writeSpec(tempDir, "task-nl2", "already has newline\n");
+
+		const content = await readFile(specPath, "utf-8");
+		expect(content).toBe("already has newline\n");
+		expect(content.endsWith("\n\n")).toBe(false);
+	});
+
+	test("overwrites existing spec file", async () => {
+		await writeSpec(tempDir, "task-ow", "version 1");
+		await writeSpec(tempDir, "task-ow", "version 2");
+
+		const specPath = join(legioDir, "specs", "task-ow.md");
+		const content = await readFile(specPath, "utf-8");
+		expect(content).toBe("version 2\n");
+	});
+});
+
+// === specCommand (CLI integration) ===
+
+describe("specCommand write", () => {
+	test("writes spec and prints path", async () => {
+		await specCommand(["write", "task-cmd", "--body", "# CLI Spec"]);
+
+		// Path may differ due to macOS /var -> /private/var symlink resolution
+		expect(stdoutOutput.trim()).toContain(".legio/specs/task-cmd.md");
+
+		const specPath = stdoutOutput.trim();
+		const content = await readFile(specPath, "utf-8");
+		expect(content).toBe("# CLI Spec\n");
+	});
+
+	test("writes spec with agent attribution", async () => {
+		await specCommand(["write", "task-attr", "--body", "# Attributed", "--agent", "scout-2"]);
+
+		expect(stdoutOutput.trim()).toContain(".legio/specs/task-attr.md");
+
+		const specPath = stdoutOutput.trim();
+		const content = await readFile(specPath, "utf-8");
+		expect(content).toContain("<!-- written-by: scout-2 -->");
+		expect(content).toContain("# Attributed");
+	});
+
+	test("flags can appear in any order", async () => {
+		await specCommand(["write", "--agent", "scout-3", "--body", "# Content", "task-order"]);
+
+		expect(stdoutOutput.trim()).toContain(".legio/specs/task-order.md");
+
+		const specPath = stdoutOutput.trim();
+		const content = await readFile(specPath, "utf-8");
+		expect(content).toContain("<!-- written-by: scout-3 -->");
+		expect(content).toContain("# Content");
+	});
+});

package/src/commands/spec.ts

@@ -0,0 +1,171 @@
+/**
+ * CLI command: legio spec write <bead-id> --body <content>
+ *
+ * Writes a task specification to `.legio/specs/<bead-id>.md`.
+ * Scouts use this to persist spec documents as files instead of
+ * sending entire specs via mail messages.
+ *
+ * Supports reading body content from --body flag or stdin.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ValidationError } from "../errors.ts";
+
+/** Boolean flags that do NOT consume the next arg. */
+const BOOLEAN_FLAGS = new Set(["--help", "-h"]);
+
+/**
+ * Parse a named flag value from args.
+ */
+function getFlag(args: string[], flag: string): string | undefined {
+	const idx = args.indexOf(flag);
+	if (idx === -1 || idx + 1 >= args.length) {
+		return undefined;
+	}
+	return args[idx + 1];
+}
+
+/**
+ * Extract positional arguments, skipping flag-value pairs.
+ */
+function getPositionalArgs(args: string[]): string[] {
+	const positional: string[] = [];
+	let i = 0;
+	while (i < args.length) {
+		const arg = args[i];
+		if (arg?.startsWith("-")) {
+			if (BOOLEAN_FLAGS.has(arg)) {
+				i += 1;
+			} else {
+				i += 2;
+			}
+		} else {
+			if (arg !== undefined) {
+				positional.push(arg);
+			}
+			i += 1;
+		}
+	}
+	return positional;
+}
+
+/**
+ * Read all of stdin as a string. Returns empty string if stdin is a TTY
+ * (no piped input).
+ */
+async function readStdin(): Promise<string> {
+	if (process.stdin.isTTY) {
+		return "";
+	}
+	const chunks: Buffer[] = [];
+	for await (const chunk of process.stdin) {
+		chunks.push(Buffer.from(chunk as Buffer));
+	}
+	return Buffer.concat(chunks).toString("utf-8");
+}
+
+const SPEC_HELP = `legio spec -- Manage task specifications
+
+Usage: legio spec <subcommand> [args...]
+
+Subcommands:
+  write <bead-id>          Write a spec file to .legio/specs/<bead-id>.md
+
+Options for 'write':
+  --body <content>         Spec content (or pipe via stdin)
+  --agent <name>           Agent writing the spec (for attribution)
+  --help, -h               Show this help
+
+Examples:
+  legio spec write task-abc --body "# Spec\\nDetails here..."
+  echo "# Spec" | legio spec write task-abc
+  legio spec write task-abc --body "..." --agent scout-1`;
+
+/**
+ * Write a spec file to .legio/specs/<bead-id>.md.
+ *
+ * Exported for direct use in tests.
+ */
+export async function writeSpec(
+	projectRoot: string,
+	beadId: string,
+	body: string,
+	agent?: string,
+): Promise<string> {
+	const specsDir = join(projectRoot, ".legio", "specs");
+	await mkdir(specsDir, { recursive: true });
+
+	// Build the spec content with optional attribution header
+	let content = "";
+	if (agent) {
+		content += `<!-- written-by: ${agent} -->\n`;
+	}
+	content += body;
+
+	// Ensure trailing newline
+	if (!content.endsWith("\n")) {
+		content += "\n";
+	}
+
+	const specPath = join(specsDir, `${beadId}.md`);
+	await writeFile(specPath, content);
+
+	return specPath;
+}
+
+/**
+ * Entry point for `legio spec <subcommand>`.
+ */
+export async function specCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+		process.stdout.write(`${SPEC_HELP}\n`);
+		return;
+	}
+
+	const subcommand = args[0];
+	const subArgs = args.slice(1);
+
+	switch (subcommand) {
+		case "write": {
+			const positional = getPositionalArgs(subArgs);
+			const beadId = positional[0];
+			if (!beadId || beadId.trim().length === 0) {
+				throw new ValidationError(
+					"Bead ID is required: legio spec write <bead-id> --body <content>",
+					{ field: "beadId" },
+				);
+			}
+
+			const agent = getFlag(subArgs, "--agent");
+			let body = getFlag(subArgs, "--body");
+
+			// If no --body flag, try reading from stdin
+			if (body === undefined) {
+				const stdinContent = await readStdin();
+				if (stdinContent.trim().length > 0) {
+					body = stdinContent;
+				}
+			}
+
+			if (body === undefined || body.trim().length === 0) {
+				throw new ValidationError("Spec body is required: use --body <content> or pipe via stdin", {
+					field: "body",
+				});
+			}
+
+			const { resolveProjectRoot } = await import("../config.ts");
+			const projectRoot = await resolveProjectRoot(process.cwd());
+
+			const specPath = await writeSpec(projectRoot, beadId, body, agent);
+			process.stdout.write(`${specPath}\n`);
+			break;
+		}
+
+		default:
+			throw new ValidationError(
+				`Unknown spec subcommand: ${subcommand}. Run 'legio spec --help' for usage.`,
+				{ field: "subcommand", value: subcommand },
+			);
+	}
+}

package/src/commands/status.test.ts

@@ -0,0 +1,276 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import type { AgentSession } from "../types.ts";
+import { printStatus, type StatusData, statusCommand, type VerboseAgentDetail } from "./status.ts";
+
+/**
+ * Tests for the --verbose flag in legio status.
+ *
+ * printStatus is tested by capturing process.stdout.write output.
+ * We spy on stdout.write because printStatus uses it directly.
+ */
+
+function makeAgent(overrides: Partial<AgentSession> = {}): AgentSession {
+	return {
+		id: "sess-001",
+		agentName: "test-builder",
+		capability: "builder",
+		worktreePath: "/tmp/worktrees/test-builder",
+		branchName: "legio/test-builder/task-1",
+		beadId: "task-1",
+		tmuxSession: "legio-test-builder",
+		state: "working",
+		pid: 12345,
+		parentAgent: null,
+		depth: 0,
+		runId: null,
+		startedAt: new Date(Date.now() - 60_000).toISOString(),
+		lastActivity: new Date().toISOString(),
+		escalationLevel: 0,
+		stalledSince: null,
+		...overrides,
+	};
+}
+
+function makeStatusData(overrides: Partial<StatusData> = {}): StatusData {
+	return {
+		agents: [makeAgent()],
+		worktrees: [],
+		tmuxSessions: [{ name: "legio-test-builder", pid: 12345 }],
+		unreadMailCount: 0,
+		mergeQueueCount: 0,
+		recentMetricsCount: 0,
+		...overrides,
+	};
+}
+
+describe("printStatus", () => {
+	let chunks: string[];
+	let originalWrite: typeof process.stdout.write;
+
+	beforeEach(() => {
+		chunks = [];
+		originalWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+	});
+
+	afterEach(() => {
+		process.stdout.write = originalWrite;
+	});
+
+	function output(): string {
+		return chunks.join("");
+	}
+
+	test("non-verbose: does not show worktree path or logs dir", () => {
+		const data = makeStatusData();
+		printStatus(data);
+		const out = output();
+
+		expect(out).toContain("test-builder");
+		expect(out).toContain("[builder]");
+		expect(out).not.toContain("Worktree:");
+		expect(out).not.toContain("Logs:");
+		expect(out).not.toContain("Mail sent:");
+	});
+
+	test("verbose: shows worktree path, logs dir, and mail timestamps", () => {
+		const detail: VerboseAgentDetail = {
+			worktreePath: "/tmp/worktrees/test-builder",
+			logsDir: "/tmp/.legio/logs/test-builder",
+			lastMailSent: "2025-01-15T10:00:00.000Z",
+			lastMailReceived: "2025-01-15T10:05:00.000Z",
+			capability: "builder",
+		};
+
+		const data = makeStatusData({
+			verboseDetails: { "test-builder": detail },
+		});
+		printStatus(data);
+		const out = output();
+
+		expect(out).toContain("Worktree: /tmp/worktrees/test-builder");
+		expect(out).toContain("Logs:     /tmp/.legio/logs/test-builder");
+		expect(out).toContain("Mail sent: 2025-01-15T10:00:00.000Z");
+		expect(out).toContain("received: 2025-01-15T10:05:00.000Z");
+	});
+
+	test("verbose: shows 'none' for null mail timestamps", () => {
+		const detail: VerboseAgentDetail = {
+			worktreePath: "/tmp/worktrees/test-builder",
+			logsDir: "/tmp/.legio/logs/test-builder",
+			lastMailSent: null,
+			lastMailReceived: null,
+			capability: "builder",
+		};
+
+		const data = makeStatusData({
+			verboseDetails: { "test-builder": detail },
+		});
+		printStatus(data);
+		const out = output();
+
+		expect(out).toContain("Mail sent: none");
+		expect(out).toContain("received: none");
+	});
+
+	test("verbose: zombie agents do not get verbose detail", () => {
+		const agent = makeAgent({ state: "zombie", agentName: "zombie-agent" });
+		const detail: VerboseAgentDetail = {
+			worktreePath: "/tmp/worktrees/zombie-agent",
+			logsDir: "/tmp/.legio/logs/zombie-agent",
+			lastMailSent: null,
+			lastMailReceived: null,
+			capability: "builder",
+		};
+
+		const data = makeStatusData({
+			agents: [agent],
+			verboseDetails: { "zombie-agent": detail },
+		});
+		printStatus(data);
+		const out = output();
+
+		// Zombie agents are filtered from the active list
+		expect(out).toContain("0 active");
+		expect(out).not.toContain("Worktree:");
+	});
+
+	test("verbose with multiple agents: each gets its own detail", () => {
+		const agent1 = makeAgent({ agentName: "builder-1", tmuxSession: "legio-builder-1" });
+		const agent2 = makeAgent({
+			agentName: "scout-1",
+			capability: "scout",
+			tmuxSession: "legio-scout-1",
+		});
+
+		const data = makeStatusData({
+			agents: [agent1, agent2],
+			tmuxSessions: [
+				{ name: "legio-builder-1", pid: 100 },
+				{ name: "legio-scout-1", pid: 200 },
+			],
+			verboseDetails: {
+				"builder-1": {
+					worktreePath: "/tmp/wt/builder-1",
+					logsDir: "/tmp/logs/builder-1",
+					lastMailSent: "2025-01-15T10:00:00.000Z",
+					lastMailReceived: null,
+					capability: "builder",
+				},
+				"scout-1": {
+					worktreePath: "/tmp/wt/scout-1",
+					logsDir: "/tmp/logs/scout-1",
+					lastMailSent: null,
+					lastMailReceived: "2025-01-15T11:00:00.000Z",
+					capability: "scout",
+				},
+			},
+		});
+		printStatus(data);
+		const out = output();
+
+		expect(out).toContain("Worktree: /tmp/wt/builder-1");
+		expect(out).toContain("Worktree: /tmp/wt/scout-1");
+		expect(out).toContain("Logs:     /tmp/logs/builder-1");
+		expect(out).toContain("Logs:     /tmp/logs/scout-1");
+	});
+});
+
+describe("--verbose --json", () => {
+	test("verboseDetails is included in StatusData when present", () => {
+		const detail: VerboseAgentDetail = {
+			worktreePath: "/tmp/wt/agent",
+			logsDir: "/tmp/logs/agent",
+			lastMailSent: "2025-01-15T10:00:00.000Z",
+			lastMailReceived: null,
+			capability: "builder",
+		};
+
+		const data: StatusData = {
+			agents: [],
+			worktrees: [],
+			tmuxSessions: [],
+			unreadMailCount: 0,
+			mergeQueueCount: 0,
+			recentMetricsCount: 0,
+			verboseDetails: { agent: detail },
+		};
+
+		const json = JSON.parse(JSON.stringify(data)) as StatusData;
+		expect(json.verboseDetails).toBeDefined();
+		expect(json.verboseDetails?.agent?.worktreePath).toBe("/tmp/wt/agent");
+		expect(json.verboseDetails?.agent?.lastMailSent).toBe("2025-01-15T10:00:00.000Z");
+		expect(json.verboseDetails?.agent?.lastMailReceived).toBeNull();
+	});
+
+	test("verboseDetails is omitted from JSON when undefined", () => {
+		const data: StatusData = {
+			agents: [],
+			worktrees: [],
+			tmuxSessions: [],
+			unreadMailCount: 0,
+			mergeQueueCount: 0,
+			recentMetricsCount: 0,
+		};
+
+		const json = JSON.stringify(data);
+		expect(json).not.toContain("verboseDetails");
+	});
+});
+
+describe("--watch deprecation", () => {
+	test("help text marks --watch as deprecated", async () => {
+		const chunks: string[] = [];
+		const originalWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		try {
+			await statusCommand(["--help"]);
+		} finally {
+			process.stdout.write = originalWrite;
+		}
+
+		const out = chunks.join("");
+		expect(out).toContain("deprecated");
+		expect(out).toContain("legio dashboard");
+	});
+
+	test("--watch writes deprecation notice to stderr", async () => {
+		const stderrChunks: string[] = [];
+		const originalStderr = process.stderr.write;
+		process.stderr.write = ((chunk: string) => {
+			stderrChunks.push(chunk);
+			return true;
+		}) as typeof process.stderr.write;
+
+		// statusCommand with --watch will fail at loadConfig (no .legio/)
+		// but the deprecation notice is written before that. We just verify
+		// the notice was emitted.
+		const tmpDir = await mkdtemp(join(tmpdir(), "status-deprecation-"));
+		const originalCwd = process.cwd();
+		process.chdir(tmpDir);
+
+		try {
+			await statusCommand(["--watch"]);
+		} catch {
+			// Expected: loadConfig fails without .legio/
+		} finally {
+			process.stderr.write = originalStderr;
+			process.chdir(originalCwd);
+			await rm(tmpDir, { recursive: true, force: true });
+		}
+
+		const err = stderrChunks.join("");
+		expect(err).toContain("--watch is deprecated");
+		expect(err).toContain("legio dashboard");
+	});
+});