@katyella/legio 0.1.0

package/src/commands/up.ts

@@ -0,0 +1,275 @@
+/**
+ * CLI command: legio up
+ *
+ * Single command to bring up the full legio stack:
+ * 1. Check git repo
+ * 2. Initialize .legio/ if needed (legio init)
+ * 3. Start the server in daemon mode (legio server start --daemon)
+ *    The server auto-starts the coordinator with watchdog.
+ * 4. Start the gateway (legio gateway start --no-attach)
+ * 5. Open the browser (unless --no-open)
+ *
+ * Running legio up when everything is already running is a safe no-op.
+ */
+
+import { spawn } from "node:child_process";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ServerError, ValidationError } from "../errors.ts";
+import { isProcessRunning } from "../watchdog/health.ts";
+
+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];
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Run an external command and collect stdout/stderr + exit code.
+ */
+async function runCommand(
+	cmd: string[],
+	opts?: { cwd?: string },
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	const [command, ...args] = cmd;
+	if (!command) {
+		return { stdout: "", stderr: "Empty command", exitCode: 1 };
+	}
+	return new Promise((resolve) => {
+		const proc = spawn(command, args, {
+			cwd: opts?.cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		const stdoutChunks: Buffer[] = [];
+		const stderrChunks: Buffer[] = [];
+		proc.stdout?.on("data", (chunk: Buffer) => stdoutChunks.push(chunk));
+		proc.stderr?.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+		proc.on("close", (code) => {
+			resolve({
+				stdout: Buffer.concat(stdoutChunks).toString(),
+				stderr: Buffer.concat(stderrChunks).toString(),
+				exitCode: code ?? 1,
+			});
+		});
+	});
+}
+
+/**
+ * Read a PID from a PID file (first line). Returns null if not found or invalid.
+ */
+async function readPidFromFile(path: string): Promise<number | null> {
+	try {
+		const text = await readFile(path, "utf-8");
+		const firstLine = text.trim().split("\n")[0] ?? "";
+		const pid = Number.parseInt(firstLine, 10);
+		if (Number.isNaN(pid) || pid <= 0) return null;
+		return pid;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Open the browser at the given URL. Fire-and-forget.
+ */
+function openBrowser(url: string): void {
+	const cmd = process.platform === "darwin" ? "open" : "xdg-open";
+	const child = spawn(cmd, [url], { detached: true, stdio: "ignore" });
+	child.unref();
+}
+
+/** Dependency injection interface for testing. */
+export interface UpDeps {
+	_runCommand?: (
+		cmd: string[],
+		opts?: { cwd?: string },
+	) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+	_fileExists?: (path: string) => Promise<boolean>;
+	_readPid?: (path: string) => Promise<number | null>;
+	_isProcessRunning?: (pid: number) => boolean;
+	_openBrowser?: (url: string) => void;
+	_projectRoot?: string;
+}
+
+const UP_HELP = `legio up — Start the full legio stack
+
+Usage: legio up [options]
+
+Options:
+  --port <n>     Server port (default: 4173)
+  --host <addr>  Bind address (default: 127.0.0.1)
+  --no-open      Do not auto-open browser
+  --force        Force reinitialize .legio/ even if it exists
+  --json         JSON output
+  --help, -h     Show this help
+
+legio up initializes .legio/ if needed, starts the server in daemon mode,
+starts the gateway, and opens the browser. The server auto-starts the
+coordinator with watchdog. Running legio up when already running is a no-op.`;
+
+/**
+ * Entry point for \`legio up [options]\`.
+ *
+ * @param args - CLI arguments after "up"
+ * @param deps - Optional dependency injection for testing
+ */
+export async function upCommand(args: string[], deps: UpDeps = {}): Promise<void> {
+	if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+		process.stdout.write(`${UP_HELP}\n`);
+		return;
+	}
+
+	const json = hasFlag(args, "--json");
+	const force = hasFlag(args, "--force");
+	const noOpen = hasFlag(args, "--no-open");
+	const portStr = getFlag(args, "--port");
+	const host = getFlag(args, "--host") ?? "127.0.0.1";
+	const port = portStr ? Number.parseInt(portStr, 10) : 4173;
+
+	if (Number.isNaN(port) || port < 1 || port > 65535) {
+		throw new ValidationError("--port must be a valid port number (1-65535)", {
+			field: "port",
+			value: portStr,
+		});
+	}
+
+	const run = deps._runCommand ?? runCommand;
+	const fileExistsFn = deps._fileExists ?? fileExists;
+	const readPidFn = deps._readPid ?? readPidFromFile;
+	const isRunningFn = deps._isProcessRunning ?? isProcessRunning;
+	const openBrowserFn = deps._openBrowser ?? openBrowser;
+	const projectRoot = deps._projectRoot ?? process.cwd();
+
+	// 1. Check git repo
+	const gitCheck = await run(["git", "rev-parse", "--is-inside-work-tree"], { cwd: projectRoot });
+	if (gitCheck.exitCode !== 0) {
+		throw new ValidationError("legio requires a git repository. Run 'git init' first.", {
+			field: "git",
+		});
+	}
+
+	let initRan = false;
+	let serverStarted = false;
+	let serverAlreadyRunning = false;
+	let gatewayStarted = false;
+	let gatewayAlreadyRunning = false;
+
+	// 2. Check if .legio/ is initialized
+	const configPath = join(projectRoot, ".legio", "config.yaml");
+	const initialized = await fileExistsFn(configPath);
+
+	if (!initialized || force) {
+		if (!json) {
+			const msg = initialized
+				? "Reinitializing .legio/ (--force)...\n"
+				: "Initializing .legio/...\n";
+			process.stdout.write(msg);
+		}
+		const initArgs = ["legio", "init"];
+		if (force) initArgs.push("--force");
+		const initResult = await run(initArgs, { cwd: projectRoot });
+		if (initResult.exitCode !== 0) {
+			throw new ValidationError(`Init failed: ${initResult.stderr.trim()}`, {
+				field: "init",
+			});
+		}
+		if (!json && initResult.stdout) process.stdout.write(initResult.stdout);
+		initRan = true;
+	}
+
+	// 3. Check if server is already running
+	const pidFile = join(projectRoot, ".legio", "server.pid");
+	const pidFileExists = await fileExistsFn(pidFile);
+	let serverPid: number | undefined;
+
+	if (pidFileExists) {
+		const pid = await readPidFn(pidFile);
+		if (pid !== null && isRunningFn(pid)) {
+			serverAlreadyRunning = true;
+			serverPid = pid;
+			if (!json) {
+				process.stdout.write(`Server already running (PID ${pid})\n`);
+			}
+		}
+	}
+
+	if (!serverAlreadyRunning) {
+		// Start server in daemon mode
+		if (!json) {
+			process.stdout.write(`Starting server on ${host}:${port}...\n`);
+		}
+		const serverResult = await run(
+			["legio", "server", "start", "--daemon", "--port", String(port), "--host", host],
+			{ cwd: projectRoot },
+		);
+		if (serverResult.exitCode !== 0) {
+			throw new ServerError(`Server start failed: ${serverResult.stderr.trim()}`, { port });
+		}
+		if (!json && serverResult.stdout) process.stdout.write(serverResult.stdout);
+		serverStarted = true;
+	}
+
+	// 4. Check if gateway is already running and start if needed (non-fatal)
+	let gatewayRunning = false;
+	try {
+		const gatewayStatus = await run(["legio", "gateway", "status", "--json"], { cwd: projectRoot });
+		if (gatewayStatus.exitCode === 0) {
+			const statusData = JSON.parse(gatewayStatus.stdout.trim()) as { running?: boolean };
+			if (statusData.running === true) {
+				gatewayAlreadyRunning = true;
+				gatewayRunning = true;
+				if (!json) process.stdout.write("Gateway already running\n");
+			}
+		}
+	} catch {
+		// ignore status check errors, proceed to try starting
+	}
+	if (!gatewayRunning) {
+		const gatewayStart = await run(["legio", "gateway", "start", "--no-attach"], {
+			cwd: projectRoot,
+		});
+		if (gatewayStart.exitCode === 0) {
+			gatewayStarted = true;
+			if (!json && gatewayStart.stdout) process.stdout.write(gatewayStart.stdout);
+		} else {
+			process.stderr.write(`Warning: gateway start failed: ${gatewayStart.stderr.trim()}\n`);
+		}
+	}
+
+	const url = `http://${host}:${port}`;
+
+	// 5. Open browser (unless --no-open)
+	if (!noOpen) {
+		openBrowserFn(url);
+	}
+
+	// 6. Print summary
+	if (json) {
+		process.stdout.write(
+			`${JSON.stringify({
+				url,
+				initRan,
+				serverStarted,
+				serverAlreadyRunning,
+				serverPid,
+				gatewayStarted,
+				gatewayAlreadyRunning,
+			})}\n`,
+		);
+	} else {
+		process.stdout.write(`\nLegio is up at ${url}\n`);
+	}
+}

package/src/commands/watch.test.ts

@@ -0,0 +1,152 @@
+import { access, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { watchCommand } from "./watch.ts";
+
+/**
+ * Tests for `legio watch` command.
+ *
+ * IMPORTANT: We CANNOT test the actual daemon loop (it would hang the test).
+ * Focus on:
+ * - Help output (safe, returns immediately)
+ * - Background mode: already-running detection
+ * - Background mode: stale PID cleanup
+ *
+ * We do NOT test:
+ * - Foreground mode (blocks forever with await new Promise(() => {}))
+ * - Actual health check loop behavior
+ */
+
+describe("watchCommand", () => {
+	let chunks: string[];
+	let stderrChunks: string[];
+	let originalWrite: typeof process.stdout.write;
+	let originalStderrWrite: typeof process.stderr.write;
+	let tempDir: string;
+	let originalCwd: string;
+	let originalExitCode: string | number | null | undefined;
+
+	beforeEach(async () => {
+		// Spy on stdout
+		chunks = [];
+		originalWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		// Spy on stderr
+		stderrChunks = [];
+		originalStderrWrite = process.stderr.write;
+		process.stderr.write = ((chunk: string) => {
+			stderrChunks.push(chunk);
+			return true;
+		}) as typeof process.stderr.write;
+
+		// Save original exitCode
+		originalExitCode = process.exitCode;
+		process.exitCode = 0;
+
+		// Create temp dir with .legio/config.yaml structure
+		tempDir = await mkdtemp(join(tmpdir(), "watch-test-"));
+		const legioDir = join(tempDir, ".legio");
+		await mkdir(legioDir, { recursive: true });
+		await writeFile(
+			join(legioDir, "config.yaml"),
+			`project:\n  name: test\n  root: ${tempDir}\n  canonicalBranch: main\n`,
+		);
+
+		// Change to temp dir so loadConfig() works
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+	});
+
+	afterEach(async () => {
+		process.stdout.write = originalWrite;
+		process.stderr.write = originalStderrWrite;
+		process.exitCode = originalExitCode;
+		process.chdir(originalCwd);
+		await rm(tempDir, { recursive: true, force: true });
+	});
+
+	function output(): string {
+		return chunks.join("");
+	}
+
+	function stderr(): string {
+		return stderrChunks.join("");
+	}
+
+	test("--help flag shows help text with key info", async () => {
+		await watchCommand(["--help"]);
+		const out = output();
+
+		expect(out).toContain("legio watch");
+		expect(out).toContain("--interval");
+		expect(out).toContain("--background");
+		expect(out).toContain("Tier 0");
+	});
+
+	test("-h flag shows help text", async () => {
+		await watchCommand(["-h"]);
+		const out = output();
+
+		expect(out).toContain("legio watch");
+		expect(out).toContain("Tier 0");
+	});
+
+	test("background mode: already running detection", async () => {
+		// Write a PID file with a running process (use our own PID)
+		const pidFilePath = join(tempDir, ".legio", "watchdog.pid");
+		await writeFile(pidFilePath, `${process.pid}\n`);
+
+		// Try to start in background mode — should fail with "already running"
+		await watchCommand(["--background"]);
+
+		const err = stderr();
+		expect(err).toContain("already running");
+		expect(err).toContain(`${process.pid}`);
+		expect(process.exitCode).toBe(1);
+	});
+
+	test("background mode: stale PID cleanup", async () => {
+		// Write a PID file with a non-running process (999999 is very unlikely to exist)
+		const pidFilePath = join(tempDir, ".legio", "watchdog.pid");
+		await writeFile(pidFilePath, "999999\n");
+
+		// Verify the stale PID file exists before the test
+		const fileBeforeExists = await access(pidFilePath).then(
+			() => true,
+			() => false,
+		);
+		expect(fileBeforeExists).toBe(true);
+
+		// Try to start in background mode
+		// This will clean up the stale PID file, then attempt to spawn.
+		// The spawn will fail because there's no real legio binary in test env,
+		// but the important part is that the stale PID file gets removed.
+		try {
+			await watchCommand(["--background"]);
+		} catch {
+			// Expected to fail when trying to spawn — that's OK
+		}
+
+		// The stale PID file should have been removed during the check
+		// (Even if the spawn itself failed, the cleanup happens before spawn)
+		// Actually, looking at the code: if existingPid is not null but not running,
+		// it removes the PID file. Then it tries to spawn. So the file should be gone
+		// OR replaced with a new PID.
+
+		// Let's check: the file should either not exist, OR contain a different PID
+		const fileAfterExists = await access(pidFilePath).then(
+			() => true,
+			() => false,
+		);
+		if (fileAfterExists) {
+			const content = await readFile(pidFilePath, "utf-8");
+			expect(content.trim()).not.toBe("999999");
+		}
+		// If it doesn't exist, that's also valid (spawn failed before writing new PID)
+	});
+});

package/src/commands/watch.ts

@@ -0,0 +1,238 @@
+/**
+ * CLI command: legio watch [--interval <ms>] [--background]
+ *
+ * Starts the Tier 0 mechanical watchdog daemon. Foreground mode shows real-time status.
+ * Background mode spawns a detached process via node:child_process and writes a PID file.
+ * Interval configurable, default 30000ms.
+ */
+
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadConfig } from "../config.ts";
+import { LegioError } from "../errors.ts";
+import type { HealthCheck } from "../types.ts";
+import { startDaemon } from "../watchdog/daemon.ts";
+import { isProcessRunning } from "../watchdog/health.ts";
+
+/**
+ * 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];
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+/**
+ * Format a health check for display.
+ */
+function formatCheck(check: HealthCheck): string {
+	const actionIcon =
+		check.action === "terminate"
+			? "💀"
+			: check.action === "escalate"
+				? "⚠️"
+				: check.action === "investigate"
+					? "🔍"
+					: "✅";
+	const pidLabel = check.pidAlive === null ? "n/a" : check.pidAlive ? "up" : "down";
+	let line = `${actionIcon} ${check.agentName}: ${check.state} (tmux=${check.tmuxAlive ? "up" : "down"}, pid=${pidLabel})`;
+	if (check.reconciliationNote) {
+		line += ` [${check.reconciliationNote}]`;
+	}
+	return line;
+}
+
+// isProcessRunning is imported from ../watchdog/health.ts (ZFC shared utility)
+
+/**
+ * Read the PID from the watchdog PID file.
+ * Returns null if the file doesn't exist or can't be parsed.
+ */
+async function readPidFile(pidFilePath: string): Promise<number | null> {
+	try {
+		const text = await readFile(pidFilePath, "utf-8");
+		const pid = Number.parseInt(text.trim(), 10);
+		if (Number.isNaN(pid) || pid <= 0) {
+			return null;
+		}
+		return pid;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Write a PID to the watchdog PID file.
+ */
+async function writePidFile(pidFilePath: string, pid: number): Promise<void> {
+	await writeFile(pidFilePath, `${pid}\n`);
+}
+
+/**
+ * Remove the watchdog PID file.
+ */
+async function removePidFile(pidFilePath: string): Promise<void> {
+	const { unlink } = await import("node:fs/promises");
+	try {
+		await unlink(pidFilePath);
+	} catch {
+		// File may already be gone — not an error
+	}
+}
+
+/**
+ * Resolve the path to the legio binary for re-launching.
+ * Uses `which legio` first, then falls back to process.argv.
+ */
+async function resolveLegioBin(): Promise<string> {
+	try {
+		const result = await new Promise<{ exitCode: number; stdout: string }>((resolve) => {
+			const proc = spawn("which", ["legio"], { stdio: ["ignore", "pipe", "pipe"] });
+			const stdoutChunks: Buffer[] = [];
+			proc.stdout?.on("data", (chunk: Buffer) => stdoutChunks.push(chunk));
+			proc.on("close", (code: number | null) => {
+				resolve({ exitCode: code ?? 1, stdout: Buffer.concat(stdoutChunks).toString("utf-8") });
+			});
+		});
+		if (result.exitCode === 0) {
+			const binPath = result.stdout.trim();
+			if (binPath.length > 0) {
+				return binPath;
+			}
+		}
+	} catch {
+		// which not available or legio not on PATH
+	}
+
+	// Fallback: use the script that's currently running (process.argv[1])
+	const scriptPath = process.argv[1];
+	if (scriptPath) {
+		return scriptPath;
+	}
+
+	throw new LegioError("Cannot resolve legio binary path for background launch", "WATCH_ERROR");
+}
+
+/**
+ * Entry point for `legio watch [--interval <ms>] [--background]`.
+ */
+const WATCH_HELP = `legio watch — Start Tier 0 mechanical watchdog daemon
+
+Usage: legio watch [--interval <ms>] [--background]
+
+Tier numbering:
+  Tier 0  Mechanical daemon (heartbeat, tmux/pid liveness) — this command
+  Tier 1  Triage agent (ephemeral AI analysis of stalled agents)
+  Tier 2  Monitor agent (continuous patrol — not yet implemented)
+  Tier 3  Supervisor monitors (per-project)
+
+Options:
+  --interval <ms>    Health check interval in milliseconds (default: from config)
+  --background       Daemonize (run in background)
+  --help, -h         Show this help`;
+
+export async function watchCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(`${WATCH_HELP}\n`);
+		return;
+	}
+
+	const intervalStr = getFlag(args, "--interval");
+	const background = hasFlag(args, "--background");
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+
+	const intervalMs = intervalStr
+		? Number.parseInt(intervalStr, 10)
+		: config.watchdog.tier0IntervalMs;
+
+	const zombieThresholdMs = config.watchdog.zombieThresholdMs;
+	const pidFilePath = join(config.project.root, ".legio", "watchdog.pid");
+
+	if (background) {
+		// Check if a watchdog is already running
+		const existingPid = await readPidFile(pidFilePath);
+		if (existingPid !== null && isProcessRunning(existingPid)) {
+			process.stderr.write(
+				`Error: Watchdog already running (PID: ${existingPid}). ` +
+					`Kill it first or remove ${pidFilePath}\n`,
+			);
+			process.exitCode = 1;
+			return;
+		}
+
+		// Clean up stale PID file if process is no longer running
+		if (existingPid !== null) {
+			await removePidFile(pidFilePath);
+		}
+
+		// Build the args for the child process, forwarding --interval but not --background
+		const childArgs: string[] = ["watch"];
+		if (intervalStr) {
+			childArgs.push("--interval", intervalStr);
+		}
+
+		// Resolve the legio binary path
+		const legioBin = await resolveLegioBin();
+
+		// Spawn a detached background process running `legio watch` (without --background)
+		const child = spawn(process.execPath, ["--import", "tsx", legioBin, ...childArgs], {
+			cwd,
+			stdio: "ignore",
+			detached: true,
+		});
+
+		// Unref the child so the parent can exit without waiting for it
+		child.unref();
+
+		const childPid = child.pid ?? 0;
+
+		// Write PID file for later cleanup
+		await writePidFile(pidFilePath, childPid);
+
+		process.stdout.write(
+			`Watchdog started in background (PID: ${childPid}, interval: ${intervalMs}ms)\n`,
+		);
+		process.stdout.write(`PID file: ${pidFilePath}\n`);
+		return;
+	}
+
+	// Foreground mode: show real-time health checks
+	process.stdout.write(`Watchdog running (interval: ${intervalMs}ms)\n`);
+	process.stdout.write("Press Ctrl+C to stop.\n\n");
+
+	// Write PID file so `--background` check and external tools can find us
+	await writePidFile(pidFilePath, process.pid);
+
+	const { stop } = startDaemon({
+		root: config.project.root,
+		intervalMs,
+		zombieThresholdMs,
+		onHealthCheck(check) {
+			const timestamp = new Date().toISOString().slice(11, 19);
+			process.stdout.write(`[${timestamp}] ${formatCheck(check)}\n`);
+		},
+	});
+
+	// Keep running until interrupted
+	process.on("SIGINT", () => {
+		stop();
+		// Clean up PID file on graceful shutdown
+		removePidFile(pidFilePath).finally(() => {
+			process.stdout.write("\nWatchdog stopped.\n");
+			process.exit(0);
+		});
+	});
+
+	// Block forever
+	await new Promise(() => {});
+}