@katyella/legio 0.1.0

package/src/beads/molecules.ts

@@ -0,0 +1,209 @@
+/**
+ * Beads molecule management helpers.
+ *
+ * Wraps `bd mol` commands via node:child_process for multi-step workflow prototypes.
+ * Molecules are templates with ordered steps. "Pouring" a prototype creates
+ * actual issues with dependencies pre-wired.
+ *
+ * Zero runtime npm dependencies — only node:child_process built-in.
+ */
+
+import { spawn } from "node:child_process";
+import { AgentError } from "../errors.ts";
+
+// === Types ===
+
+export interface MoleculeStep {
+	title: string;
+	type?: string;
+}
+
+export interface MoleculePrototype {
+	id: string;
+	name: string;
+	stepCount: number;
+}
+
+export interface ConvoyStatus {
+	total: number;
+	completed: number;
+	inProgress: number;
+	blocked: number;
+}
+
+// === Internal helpers ===
+
+/**
+ * Run a shell command and capture its output.
+ */
+async function runCommand(
+	cmd: string[],
+	cwd: string,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	const [command, ...args] = cmd;
+	if (!command) throw new Error("Empty command");
+	return new Promise((resolve, reject) => {
+		const proc = spawn(command, args, {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		const chunks: { stdout: Buffer[]; stderr: Buffer[] } = { stdout: [], stderr: [] };
+		proc.stdout.on("data", (data: Buffer) => chunks.stdout.push(data));
+		proc.stderr.on("data", (data: Buffer) => chunks.stderr.push(data));
+		proc.on("error", reject);
+		proc.on("close", (code) => {
+			resolve({
+				stdout: Buffer.concat(chunks.stdout).toString(),
+				stderr: Buffer.concat(chunks.stderr).toString(),
+				exitCode: code ?? 1,
+			});
+		});
+	});
+}
+
+/**
+ * Run a `bd` subcommand and throw on failure.
+ */
+async function runBd(
+	args: string[],
+	cwd: string,
+	context: string,
+): Promise<{ stdout: string; stderr: string }> {
+	const { stdout, stderr, exitCode } = await runCommand(["bd", ...args], cwd);
+	if (exitCode !== 0) {
+		throw new AgentError(`bd ${context} failed (exit ${exitCode}): ${stderr.trim()}`);
+	}
+	return { stdout, stderr };
+}
+
+/**
+ * Parse JSON output from a bd command.
+ * Handles the case where output may be empty or malformed.
+ */
+function parseJsonOutput<T>(stdout: string, context: string): T {
+	const trimmed = stdout.trim();
+	if (trimmed === "") {
+		throw new AgentError(`Empty output from bd ${context}`);
+	}
+	try {
+		return JSON.parse(trimmed) as T;
+	} catch {
+		throw new AgentError(
+			`Failed to parse JSON output from bd ${context}: ${trimmed.slice(0, 200)}`,
+		);
+	}
+}
+
+// === Public API ===
+
+/**
+ * Create a molecule prototype with ordered steps.
+ *
+ * First creates the prototype via `bd mol create`, then adds each step
+ * in order via `bd mol step add`. Returns the prototype ID.
+ *
+ * @param cwd - Working directory where bd commands should run
+ * @param options - Prototype name and ordered steps
+ * @returns The molecule prototype ID
+ */
+export async function createMoleculePrototype(
+	cwd: string,
+	options: { name: string; steps: MoleculeStep[] },
+): Promise<string> {
+	const { stdout } = await runBd(
+		["mol", "create", "--name", options.name, "--json"],
+		cwd,
+		"mol create",
+	);
+	const result = parseJsonOutput<{ id: string }>(stdout, "mol create");
+	const molId = result.id;
+
+	for (const step of options.steps) {
+		const stepArgs = [
+			"mol",
+			"step",
+			"add",
+			molId,
+			"--title",
+			step.title,
+			"--type",
+			step.type ?? "task",
+			"--json",
+		];
+		await runBd(stepArgs, cwd, `mol step add (${step.title})`);
+	}
+
+	return molId;
+}
+
+/**
+ * Pour (instantiate) a molecule prototype into actual issues.
+ *
+ * Creates issues from the prototype with dependencies pre-wired.
+ * Optionally applies a prefix to all created issue titles.
+ *
+ * @param cwd - Working directory where bd commands should run
+ * @param options - Prototype ID and optional title prefix
+ * @returns Array of created issue IDs
+ */
+export async function pourMolecule(
+	cwd: string,
+	options: { prototypeId: string; prefix?: string },
+): Promise<string[]> {
+	const args = ["mol", "pour", options.prototypeId, "--json"];
+	if (options.prefix !== undefined) {
+		args.push("--prefix", options.prefix);
+	}
+	const { stdout } = await runBd(args, cwd, "mol pour");
+	const result = parseJsonOutput<{ ids: string[] }>(stdout, "mol pour");
+	return result.ids;
+}
+
+/**
+ * List all molecule prototypes.
+ *
+ * @param cwd - Working directory where bd commands should run
+ * @returns Array of prototype summaries
+ */
+export async function listPrototypes(cwd: string): Promise<MoleculePrototype[]> {
+	const { stdout } = await runBd(["mol", "list", "--json"], cwd, "mol list");
+	const result = parseJsonOutput<Array<{ id: string; name: string; stepCount: number }>>(
+		stdout,
+		"mol list",
+	);
+	return result.map((entry) => ({
+		id: entry.id,
+		name: entry.name,
+		stepCount: entry.stepCount,
+	}));
+}
+
+/**
+ * Get the convoy status for a molecule prototype instance.
+ *
+ * Returns counts of total, completed, in-progress, and blocked issues
+ * that were poured from this prototype.
+ *
+ * @param cwd - Working directory where bd commands should run
+ * @param prototypeId - The prototype ID to check status for
+ * @returns Status counts for the convoy
+ */
+export async function getConvoyStatus(cwd: string, prototypeId: string): Promise<ConvoyStatus> {
+	const { stdout } = await runBd(
+		["mol", "status", prototypeId, "--json"],
+		cwd,
+		`mol status ${prototypeId}`,
+	);
+	const result = parseJsonOutput<{
+		total: number;
+		completed: number;
+		inProgress: number;
+		blocked: number;
+	}>(stdout, `mol status ${prototypeId}`);
+	return {
+		total: result.total,
+		completed: result.completed,
+		inProgress: result.inProgress,
+		blocked: result.blocked,
+	};
+}

package/src/commands/agents.test.ts

@@ -0,0 +1,325 @@
+/**
+ * Tests for the agents command.
+ */
+
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createSessionStore } from "../sessions/store.ts";
+import type { AgentSession } from "../types.ts";
+import { agentsCommand, discoverAgents, extractFileScope } from "./agents.ts";
+
+describe("extractFileScope", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "legio-test-"));
+	});
+
+	it("should return empty array when overlay doesn't exist", async () => {
+		const scope = await extractFileScope(tempDir);
+		expect(scope).toEqual([]);
+	});
+
+	it("should return empty array when 'No file scope restrictions'", async () => {
+		const overlayPath = join(tempDir, ".claude", "CLAUDE.md");
+		const content = `# Agent Overlay
+
+## File Scope (exclusive ownership)
+
+No file scope restrictions. You may modify any file in the worktree.
+
+## Expertise
+
+Some expertise here.
+`;
+		await mkdir(join(tempDir, ".claude"), { recursive: true });
+		await writeFile(overlayPath, content);
+		const scope = await extractFileScope(tempDir);
+		expect(scope).toEqual([]);
+	});
+
+	it("should extract file paths from valid overlay", async () => {
+		const overlayPath = join(tempDir, ".claude", "CLAUDE.md");
+		const content = `# Agent Overlay
+
+## File Scope (exclusive ownership)
+
+These files are yours to modify:
+
+- \`src/commands/agents.ts\`
+- \`src/commands/agents.test.ts\`
+- \`src/index.ts\`
+
+## Expertise
+
+Some expertise here.
+`;
+		await mkdir(join(tempDir, ".claude"), { recursive: true });
+		await writeFile(overlayPath, content);
+		const scope = await extractFileScope(tempDir);
+		expect(scope).toEqual([
+			"src/commands/agents.ts",
+			"src/commands/agents.test.ts",
+			"src/index.ts",
+		]);
+	});
+
+	afterEach(async () => {
+		await rm(tempDir, { recursive: true, force: true });
+	});
+});
+
+describe("discoverAgents", () => {
+	let tempDir: string;
+	let dbPath: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "legio-test-"));
+		const legioDir = join(tempDir, ".legio");
+		await mkdir(legioDir, { recursive: true });
+		await writeFile(join(legioDir, ".gitkeep"), "");
+		dbPath = join(legioDir, "sessions.db");
+	});
+
+	it("should return empty when no sessions", async () => {
+		const store = createSessionStore(dbPath);
+		store.close();
+
+		const agents = await discoverAgents(tempDir);
+		expect(agents).toEqual([]);
+	});
+
+	it("should return active agents", async () => {
+		const store = createSessionStore(dbPath);
+
+		const session: AgentSession = {
+			id: "session-1",
+			agentName: "builder-test",
+			capability: "builder",
+			worktreePath: join(tempDir, ".legio", "worktrees", "builder-test"),
+			branchName: "legio/builder-test/task-123",
+			beadId: "task-123",
+			tmuxSession: "legio-test-builder",
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:01:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+		};
+
+		store.upsert(session);
+		store.close();
+
+		const agents = await discoverAgents(tempDir);
+		expect(agents).toHaveLength(1);
+		expect(agents[0]?.agentName).toBe("builder-test");
+		expect(agents[0]?.capability).toBe("builder");
+		expect(agents[0]?.state).toBe("working");
+	});
+
+	it("should filter by capability", async () => {
+		const store = createSessionStore(dbPath);
+
+		const builder: AgentSession = {
+			id: "session-1",
+			agentName: "builder-test",
+			capability: "builder",
+			worktreePath: join(tempDir, ".legio", "worktrees", "builder-test"),
+			branchName: "legio/builder-test/task-123",
+			beadId: "task-123",
+			tmuxSession: "legio-test-builder",
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:01:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+		};
+
+		const scout: AgentSession = {
+			id: "session-2",
+			agentName: "scout-test",
+			capability: "scout",
+			worktreePath: join(tempDir, ".legio", "worktrees", "scout-test"),
+			branchName: "legio/scout-test/task-456",
+			beadId: "task-456",
+			tmuxSession: "legio-test-scout",
+			state: "working",
+			pid: 12346,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:01:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+		};
+
+		store.upsert(builder);
+		store.upsert(scout);
+		store.close();
+
+		const agents = await discoverAgents(tempDir, { capability: "builder" });
+		expect(agents).toHaveLength(1);
+		expect(agents[0]?.agentName).toBe("builder-test");
+		expect(agents[0]?.capability).toBe("builder");
+	});
+
+	it("should includeAll returns completed agents too", async () => {
+		const store = createSessionStore(dbPath);
+
+		const working: AgentSession = {
+			id: "session-1",
+			agentName: "builder-working",
+			capability: "builder",
+			worktreePath: join(tempDir, ".legio", "worktrees", "builder-working"),
+			branchName: "legio/builder-working/task-123",
+			beadId: "task-123",
+			tmuxSession: "legio-test-working",
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:01:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+		};
+
+		const completed: AgentSession = {
+			id: "session-2",
+			agentName: "builder-completed",
+			capability: "builder",
+			worktreePath: join(tempDir, ".legio", "worktrees", "builder-completed"),
+			branchName: "legio/builder-completed/task-456",
+			beadId: "task-456",
+			tmuxSession: "legio-test-completed",
+			state: "completed",
+			pid: null,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:02:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+		};
+
+		store.upsert(working);
+		store.upsert(completed);
+		store.close();
+
+		// Without includeAll, only active agents
+		const activeAgents = await discoverAgents(tempDir);
+		expect(activeAgents).toHaveLength(1);
+		expect(activeAgents[0]?.agentName).toBe("builder-working");
+
+		// With includeAll, both working and completed
+		const allAgents = await discoverAgents(tempDir, { includeAll: true });
+		expect(allAgents).toHaveLength(2);
+		const names = allAgents.map((a) => a.agentName);
+		expect(names).toContain("builder-working");
+		expect(names).toContain("builder-completed");
+	});
+
+	afterEach(async () => {
+		await rm(tempDir, { recursive: true, force: true });
+	});
+});
+
+describe("agentsCommand", () => {
+	let tempDir: string;
+	let originalCwd: string;
+	let originalStdoutWrite: typeof process.stdout.write;
+	let stdoutBuffer: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "legio-test-"));
+		const legioDir = join(tempDir, ".legio");
+		await mkdir(legioDir, { recursive: true });
+
+		// Create config.yaml
+		const configContent = `project:
+  name: test-project
+  root: ${tempDir}
+  canonicalBranch: main
+agents:
+  manifestPath: .legio/agent-manifest.json
+  baseDir: agents
+  maxConcurrent: 5
+  staggerDelayMs: 100
+  maxDepth: 2
+worktrees:
+  baseDir: .legio/worktrees
+beads:
+  enabled: true
+mulch:
+  enabled: true
+  domains: []
+  primeFormat: markdown
+merge:
+  aiResolveEnabled: false
+  reimagineEnabled: false
+watchdog:
+  tier0Enabled: false
+  tier0IntervalMs: 30000
+  tier1Enabled: false
+  tier2Enabled: false
+  zombieThresholdMs: 600000
+  nudgeIntervalMs: 60000
+logging:
+  verbose: false
+  redactSecrets: true
+`;
+		await writeFile(join(legioDir, "config.yaml"), configContent);
+
+		// Create sessions.db
+		const dbPath = join(legioDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+		store.close();
+
+		// Mock stdout.write
+		stdoutBuffer = "";
+		originalStdoutWrite = process.stdout.write;
+		process.stdout.write = vi.fn((chunk: unknown) => {
+			stdoutBuffer += String(chunk);
+			return true;
+		});
+
+		// Change to temp dir
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+	});
+
+	it("should show help with --help flag", async () => {
+		await agentsCommand(["--help"]);
+		expect(stdoutBuffer).toContain("legio agents");
+		expect(stdoutBuffer).toContain("discover");
+	});
+
+	it("should show help with no subcommand", async () => {
+		await agentsCommand([]);
+		expect(stdoutBuffer).toContain("legio agents");
+		expect(stdoutBuffer).toContain("discover");
+	});
+
+	it("should error on unknown subcommand", async () => {
+		await expect(agentsCommand(["unknown"])).rejects.toThrow("Unknown subcommand");
+	});
+
+	afterEach(async () => {
+		process.stdout.write = originalStdoutWrite;
+		process.chdir(originalCwd);
+		await rm(tempDir, { recursive: true, force: true });
+	});
+});