@ag-eco/agentplate-cli 0.13.0

package/src/beads/molecules.test.ts

@@ -0,0 +1,338 @@
+/**
+ * Unit tests for beads molecules module.
+ *
+ * WHY MOCKING IS USED HERE:
+ * The molecules.ts module expects a bd mol API that doesn't exist yet in beads.
+ * Expected API: bd mol create --name, bd mol step add, bd mol list, bd mol status
+ * Actual API: bd formula, bd cook, bd mol pour, bd mol wisp
+ *
+ * These tests mock Bun.spawn to verify the module's logic is correct.
+ * When the bd API is implemented to match the module's expectations,
+ * these can be converted to integration tests using the real bd CLI.
+ *
+ * See loam record mx-56558b for why mocking is normally avoided.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { AgentError } from "../errors.ts";
+import {
+	createMoleculePrototype,
+	getConvoyStatus,
+	listPrototypes,
+	pourMolecule,
+} from "./molecules.ts";
+
+/**
+ * Mock Bun.spawn to simulate bd mol CLI responses.
+ * Returns a mock process with configurable stdout/stderr/exitCode.
+ */
+function mockSpawn(
+	stdout: string,
+	stderr = "",
+	exitCode = 0,
+): {
+	stdout: ReadableStream<Uint8Array>;
+	stderr: ReadableStream<Uint8Array>;
+	exited: Promise<number>;
+} {
+	const stdoutBody = new Response(stdout).body;
+	const stderrBody = new Response(stderr).body;
+	if (!stdoutBody || !stderrBody) {
+		throw new Error("Response body is null");
+	}
+	return {
+		stdout: stdoutBody,
+		stderr: stderrBody,
+		exited: Promise.resolve(exitCode),
+	};
+}
+
+let originalSpawn: typeof Bun.spawn;
+
+beforeEach(() => {
+	// Save original spawn
+	originalSpawn = Bun.spawn;
+});
+
+describe("molecules", () => {
+	beforeEach(() => {
+		// Restore original spawn before each test
+		Bun.spawn = originalSpawn;
+	});
+
+	afterEach(() => {
+		// Ensure cleanup after each test to prevent mock leaks
+		Bun.spawn = originalSpawn;
+	});
+
+	describe("createMoleculePrototype", () => {
+		test("creates a prototype with ordered steps", async () => {
+			let callCount = 0;
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock((cmd: string[], _opts?: unknown) => {
+				callCount++;
+				// First call: bd mol create
+				if (callCount === 1) {
+					expect(cmd).toEqual(["bd", "mol", "create", "--name", "Test Workflow", "--json"]);
+					return mockSpawn(JSON.stringify({ id: "mol-123" }));
+				}
+				// Subsequent calls: bd mol step add
+				expect(cmd[0]).toBe("bd");
+				expect(cmd[1]).toBe("mol");
+				expect(cmd[2]).toBe("step");
+				expect(cmd[3]).toBe("add");
+				expect(cmd[4]).toBe("mol-123");
+				return mockSpawn(JSON.stringify({ success: true }));
+			});
+
+			const molId = await createMoleculePrototype("/test/dir", {
+				name: "Test Workflow",
+				steps: [
+					{ title: "Step 1: Setup", type: "task" },
+					{ title: "Step 2: Implementation", type: "task" },
+					{ title: "Step 3: Testing", type: "task" },
+				],
+			});
+
+			expect(molId).toBe("mol-123");
+			expect(callCount).toBe(4); // 1 create + 3 step adds
+		});
+
+		test("creates a prototype with default type (task)", async () => {
+			let callCount = 0;
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock((cmd: string[], _opts?: unknown) => {
+				callCount++;
+				if (callCount === 1) {
+					return mockSpawn(JSON.stringify({ id: "mol-456" }));
+				}
+				// Check that default type is "task"
+				expect(cmd).toContain("--type");
+				const typeIndex = cmd.indexOf("--type");
+				expect(cmd[typeIndex + 1]).toBe("task");
+				return mockSpawn(JSON.stringify({ success: true }));
+			});
+
+			const molId = await createMoleculePrototype("/test/dir", {
+				name: "Default Type Workflow",
+				steps: [{ title: "Step without explicit type" }],
+			});
+
+			expect(molId).toBe("mol-456");
+			expect(callCount).toBe(2); // 1 create + 1 step add
+		});
+
+		test("creates a prototype with empty steps array", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn(JSON.stringify({ id: "mol-empty" }));
+			});
+
+			const molId = await createMoleculePrototype("/test/dir", {
+				name: "Empty Workflow",
+				steps: [],
+			});
+
+			expect(molId).toBe("mol-empty");
+		});
+
+		test("throws AgentError on create failure", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn("", "bd mol create failed: invalid name", 1);
+			});
+
+			await expect(
+				createMoleculePrototype("/test/dir", {
+					name: "Bad",
+					steps: [],
+				}),
+			).rejects.toThrow(AgentError);
+		});
+
+		test("throws AgentError on step add failure", async () => {
+			let callCount = 0;
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				callCount++;
+				if (callCount === 1) {
+					return mockSpawn(JSON.stringify({ id: "mol-789" }));
+				}
+				// Step add fails
+				return mockSpawn("", "step add failed", 1);
+			});
+
+			await expect(
+				createMoleculePrototype("/test/dir", {
+					name: "Test",
+					steps: [{ title: "Step 1" }],
+				}),
+			).rejects.toThrow(AgentError);
+		});
+	});
+
+	describe("listPrototypes", () => {
+		test("returns all created prototypes", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn(
+					JSON.stringify([
+						{ id: "mol-1", name: "List Test 1", stepCount: 1 },
+						{ id: "mol-2", name: "List Test 2", stepCount: 2 },
+					]),
+				);
+			});
+
+			const prototypes = await listPrototypes("/test/dir");
+
+			expect(prototypes).toHaveLength(2);
+			expect(prototypes[0]).toEqual({ id: "mol-1", name: "List Test 1", stepCount: 1 });
+			expect(prototypes[1]).toEqual({ id: "mol-2", name: "List Test 2", stepCount: 2 });
+		});
+
+		test("returns empty array when no prototypes exist", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn(JSON.stringify([]));
+			});
+
+			const prototypes = await listPrototypes("/test/dir");
+
+			expect(Array.isArray(prototypes)).toBe(true);
+			expect(prototypes).toHaveLength(0);
+		});
+
+		test("throws AgentError on failure", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn("", "bd mol list failed", 1);
+			});
+
+			await expect(listPrototypes("/test/dir")).rejects.toThrow(AgentError);
+		});
+
+		test("throws AgentError on empty output", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn("");
+			});
+
+			await expect(listPrototypes("/test/dir")).rejects.toThrow(AgentError);
+		});
+	});
+
+	describe("pourMolecule", () => {
+		test("pours a prototype into actual issues", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock((cmd: string[]) => {
+				expect(cmd).toEqual(["bd", "mol", "pour", "mol-123", "--json"]);
+				return mockSpawn(JSON.stringify({ ids: ["issue-1", "issue-2", "issue-3"] }));
+			});
+
+			const issueIds = await pourMolecule("/test/dir", {
+				prototypeId: "mol-123",
+			});
+
+			expect(Array.isArray(issueIds)).toBe(true);
+			expect(issueIds).toHaveLength(3);
+			expect(issueIds).toEqual(["issue-1", "issue-2", "issue-3"]);
+		});
+
+		test("applies prefix when provided", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock((cmd: string[]) => {
+				expect(cmd).toEqual(["bd", "mol", "pour", "mol-456", "--json", "--prefix", "v2.0"]);
+				return mockSpawn(JSON.stringify({ ids: ["issue-4", "issue-5"] }));
+			});
+
+			const issueIds = await pourMolecule("/test/dir", {
+				prototypeId: "mol-456",
+				prefix: "v2.0",
+			});
+
+			expect(issueIds).toEqual(["issue-4", "issue-5"]);
+		});
+
+		test("handles empty prototype (0 steps)", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn(JSON.stringify({ ids: [] }));
+			});
+
+			const issueIds = await pourMolecule("/test/dir", {
+				prototypeId: "mol-empty",
+			});
+
+			expect(Array.isArray(issueIds)).toBe(true);
+			expect(issueIds).toHaveLength(0);
+		});
+
+		test("throws AgentError for nonexistent prototype", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn("", "prototype not found", 1);
+			});
+
+			await expect(
+				pourMolecule("/test/dir", {
+					prototypeId: "nonexistent-mol-id",
+				}),
+			).rejects.toThrow(AgentError);
+		});
+	});
+
+	describe("getConvoyStatus", () => {
+		test("returns status for poured prototype", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock((cmd: string[]) => {
+				expect(cmd).toEqual(["bd", "mol", "status", "mol-123", "--json"]);
+				return mockSpawn(
+					JSON.stringify({
+						total: 3,
+						completed: 1,
+						inProgress: 1,
+						blocked: 0,
+					}),
+				);
+			});
+
+			const status = await getConvoyStatus("/test/dir", "mol-123");
+
+			expect(status).toBeDefined();
+			expect(status.total).toBe(3);
+			expect(status.completed).toBe(1);
+			expect(status.inProgress).toBe(1);
+			expect(status.blocked).toBe(0);
+		});
+
+		test("handles empty poured prototype", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn(
+					JSON.stringify({
+						total: 0,
+						completed: 0,
+						inProgress: 0,
+						blocked: 0,
+					}),
+				);
+			});
+
+			const status = await getConvoyStatus("/test/dir", "mol-empty");
+
+			expect(status.total).toBe(0);
+			expect(status.completed).toBe(0);
+			expect(status.inProgress).toBe(0);
+			expect(status.blocked).toBe(0);
+		});
+
+		test("throws AgentError for nonexistent prototype", async () => {
+			// @ts-expect-error - Mocking Bun.spawn for testing
+			Bun.spawn = mock(() => {
+				return mockSpawn("", "prototype not found", 1);
+			});
+
+			await expect(getConvoyStatus("/test/dir", "nonexistent-mol-id")).rejects.toThrow(AgentError);
+		});
+	});
+});

package/src/beads/molecules.ts

@@ -0,0 +1,198 @@
+/**
+ * Beads molecule management helpers.
+ *
+ * Wraps `bd mol` commands via Bun.spawn for multi-step workflow prototypes.
+ * Molecules are templates with ordered steps. "Pouring" a prototype creates
+ * actual issues with dependencies pre-wired.
+ *
+ * Zero runtime dependencies — only Bun built-in APIs.
+ */
+
+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 proc = Bun.spawn(cmd, {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const stdout = await new Response(proc.stdout).text();
+	const stderr = await new Response(proc.stderr).text();
+	const exitCode = await proc.exited;
+	return { stdout, stderr, exitCode };
+}
+
+/**
+ * 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,
+	};
+}