@ag-eco/agentplate-cli 0.13.0

package/src/beads/client.test.ts

@@ -0,0 +1,217 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { realpathSync } from "node:fs";
+import { AgentError } from "../errors.ts";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import { type BeadsClient, createBeadsClient } from "./client.ts";
+
+/**
+ * Check if the bd CLI is available on this machine (synchronous).
+ * Uses Bun.spawnSync so the result is available at test registration time
+ * for use with test.skipIf().
+ */
+function isBdAvailable(): boolean {
+	try {
+		const result = Bun.spawnSync(["bd", "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		return result.exitCode === 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Initialize beads in a git repo directory.
+ */
+async function initBeads(cwd: string): Promise<void> {
+	const proc = Bun.spawn(["bd", "init"], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		const stderr = await new Response(proc.stderr).text();
+		throw new Error(`bd init failed: ${stderr}`);
+	}
+}
+
+const bdAvailable = isBdAvailable();
+
+/**
+ * Optimized test suite: uses a single shared repo (beforeAll) instead of
+ * creating a fresh repo per test. All 16 original tests share one repo
+ * since they create issues with unique IDs and use toContain/not.toContain
+ * assertions. This reduces setup from ~96 subprocess spawns to ~6.
+ */
+describe("createBeadsClient (integration)", () => {
+	let tempDir: string;
+	let client: BeadsClient;
+
+	// Pre-created issue IDs for tests that need existing issues
+	let openIssueId: string;
+	let claimedIssueId: string;
+	let closedIssueId: string;
+
+	beforeAll(async () => {
+		if (!bdAvailable) return;
+		// realpathSync resolves macOS /var -> /private/var symlink so paths match
+		tempDir = realpathSync(await createTempGitRepo());
+		await initBeads(tempDir);
+		client = createBeadsClient(tempDir);
+
+		// Pre-create issues used by read-only tests (list, ready, show)
+		openIssueId = await client.create("Pre-created open issue");
+		claimedIssueId = await client.create("Pre-created claimed issue");
+		await client.claim(claimedIssueId);
+		closedIssueId = await client.create("Pre-created closed issue");
+		await client.close(closedIssueId);
+	});
+
+	afterAll(async () => {
+		if (!bdAvailable) return;
+		await cleanupTempDir(tempDir);
+	});
+
+	describe("create", () => {
+		test.skipIf(!bdAvailable)("returns an issue ID", async () => {
+			const id = await client.create("Integration test issue");
+
+			expect(typeof id).toBe("string");
+			expect(id.length).toBeGreaterThan(0);
+		});
+
+		test.skipIf(!bdAvailable)("returns ID with type and priority options", async () => {
+			const id = await client.create("Typed issue", {
+				type: "bug",
+				priority: 1,
+			});
+
+			expect(typeof id).toBe("string");
+			expect(id.length).toBeGreaterThan(0);
+		});
+
+		test.skipIf(!bdAvailable)("returns ID with description option", async () => {
+			const id = await client.create("Described issue", {
+				description: "A detailed description",
+			});
+
+			expect(typeof id).toBe("string");
+			expect(id.length).toBeGreaterThan(0);
+		});
+	});
+
+	describe("show", () => {
+		test.skipIf(!bdAvailable)("returns issue details for a valid ID", async () => {
+			const id = await client.create("Show test issue", {
+				type: "task",
+				priority: 2,
+			});
+
+			const issue = await client.show(id);
+
+			expect(issue.id).toBe(id);
+			expect(issue.title).toBe("Show test issue");
+			expect(issue.status).toBe("open");
+			expect(issue.priority).toBe(2);
+			expect(issue.type).toBe("task");
+		});
+	});
+
+	describe("claim", () => {
+		test.skipIf(!bdAvailable)("changes issue status to in_progress and returns void", async () => {
+			const id = await client.create("Claim test issue");
+
+			const result = await client.claim(id);
+			expect(result).toBeUndefined();
+
+			const issue = await client.show(id);
+			expect(issue.status).toBe("in_progress");
+		});
+	});
+
+	describe("close", () => {
+		test.skipIf(!bdAvailable)("closes issues with and without reason", async () => {
+			const id1 = await client.create("Close test issue");
+			const id2 = await client.create("Close reason test");
+
+			await client.close(id1);
+			await client.close(id2, "Completed all acceptance criteria");
+
+			const issue1 = await client.show(id1);
+			expect(issue1.status).toBe("closed");
+
+			const issue2 = await client.show(id2);
+			expect(issue2.status).toBe("closed");
+		});
+	});
+
+	describe("list", () => {
+		test.skipIf(!bdAvailable)("returns all issues", async () => {
+			const issues = await client.list();
+
+			// Pre-created issues should be present (plus any from other tests)
+			expect(issues.length).toBeGreaterThanOrEqual(3);
+			const titles = issues.map((i) => i.title);
+			expect(titles).toContain("Pre-created open issue");
+			expect(titles).toContain("Pre-created claimed issue");
+		});
+
+		test.skipIf(!bdAvailable)("filters by status", async () => {
+			const openIssues = await client.list({ status: "open" });
+			const openIds = openIssues.map((i) => i.id);
+			expect(openIds).toContain(openIssueId);
+			expect(openIds).not.toContain(claimedIssueId);
+			expect(openIds).not.toContain(closedIssueId);
+
+			const inProgressIssues = await client.list({ status: "in_progress" });
+			const inProgressIds = inProgressIssues.map((i) => i.id);
+			expect(inProgressIds).toContain(claimedIssueId);
+			expect(inProgressIds).not.toContain(openIssueId);
+		});
+
+		test.skipIf(!bdAvailable)("respects limit option", async () => {
+			const limited = await client.list({ limit: 1 });
+			expect(limited).toHaveLength(1);
+		});
+	});
+
+	describe("ready", () => {
+		test.skipIf(!bdAvailable)(
+			"returns open unblocked issues but not claimed or closed",
+			async () => {
+				const readyIssues = await client.ready();
+				const readyIds = readyIssues.map((i) => i.id);
+
+				// Open issue should appear in ready
+				expect(readyIds).toContain(openIssueId);
+				// Claimed issue should not appear in ready
+				expect(readyIds).not.toContain(claimedIssueId);
+				// Closed issue should not appear in ready
+				expect(readyIds).not.toContain(closedIssueId);
+			},
+		);
+	});
+
+	describe("error handling", () => {
+		test.skipIf(!bdAvailable)("show throws AgentError for nonexistent ID", async () => {
+			await expect(client.show("nonexistent-id")).rejects.toThrow(AgentError);
+		});
+
+		test.skipIf(!bdAvailable)(
+			"throws AgentError when bd is run without beads initialized",
+			async () => {
+				// Create a git repo without bd init — independent from shared repo
+				const bareDir = realpathSync(await createTempGitRepo());
+				const bareClient = createBeadsClient(bareDir);
+
+				try {
+					await expect(bareClient.list()).rejects.toThrow(AgentError);
+				} finally {
+					await cleanupTempDir(bareDir);
+				}
+			},
+		);
+	});
+});

package/src/beads/client.ts

@@ -0,0 +1,230 @@
+/**
+ * Beads (bd) CLI client.
+ *
+ * Wraps the `bd` command-line tool for issue tracking operations.
+ * All commands use `--json` for parseable output where supported.
+ * Uses Bun.spawn — zero runtime dependencies.
+ */
+
+import { AgentError } from "../errors.ts";
+
+/**
+ * A beads issue as returned by the bd CLI.
+ * Defined locally since it comes from an external CLI tool.
+ */
+export interface BeadIssue {
+	id: string;
+	title: string;
+	status: string;
+	priority: number;
+	type: string;
+	assignee?: string;
+	description?: string;
+	blocks?: string[];
+	blockedBy?: string[];
+}
+
+export interface BeadsClient {
+	/** List issues that are ready for work (open, unblocked). */
+	ready(options?: { mol?: string }): Promise<BeadIssue[]>;
+
+	/** Show details for a specific issue. */
+	show(id: string): Promise<BeadIssue>;
+
+	/** Create a new issue. Returns the new issue ID. */
+	create(
+		title: string,
+		options?: { type?: string; priority?: number; description?: string },
+	): Promise<string>;
+
+	/** Claim an issue (mark as in_progress). */
+	claim(id: string): Promise<void>;
+
+	/** Close an issue with an optional reason. */
+	close(id: string, reason?: string): Promise<void>;
+
+	/** List issues with optional filters. */
+	list(options?: { status?: string; limit?: number }): Promise<BeadIssue[]>;
+}
+
+/**
+ * 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 };
+}
+
+/**
+ * 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)}`,
+		);
+	}
+}
+
+/**
+ * Raw issue shape from the bd CLI.
+ * bd uses `issue_type` instead of `type`.
+ */
+interface RawBeadIssue {
+	id: string;
+	title: string;
+	status: string;
+	priority: number;
+	issue_type?: string;
+	type?: string;
+	assignee?: string;
+	description?: string;
+	blocks?: string[];
+	blockedBy?: string[];
+}
+
+/**
+ * Normalize a raw bd issue into a BeadIssue.
+ * Maps `issue_type` -> `type` to match the BeadIssue interface.
+ */
+function normalizeIssue(raw: RawBeadIssue): BeadIssue {
+	return {
+		id: raw.id,
+		title: raw.title,
+		status: raw.status,
+		priority: raw.priority,
+		type: raw.issue_type ?? raw.type ?? "unknown",
+		assignee: raw.assignee,
+		description: raw.description,
+		blocks: raw.blocks,
+		blockedBy: raw.blockedBy,
+	};
+}
+
+/**
+ * Create a BeadsClient bound to the given working directory.
+ *
+ * @param cwd - Working directory where bd commands should run
+ * @returns A BeadsClient instance wrapping the bd CLI
+ */
+export function createBeadsClient(cwd: string): BeadsClient {
+	async function runBd(
+		args: 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 };
+	}
+
+	return {
+		async ready(options) {
+			const args = ["ready", "--json"];
+			if (options?.mol) {
+				args.push("--mol", options.mol);
+			}
+			const { stdout } = await runBd(args, "ready");
+			const raw = parseJsonOutput<RawBeadIssue[]>(stdout, "ready");
+			return raw.map(normalizeIssue);
+		},
+
+		async show(id) {
+			const { stdout } = await runBd(["show", id, "--json"], `show ${id}`);
+			// bd show --json returns an array with a single element
+			const raw = parseJsonOutput<RawBeadIssue[]>(stdout, `show ${id}`);
+			const first = raw[0];
+			if (!first) {
+				throw new AgentError(`bd show ${id} returned empty array`);
+			}
+			return normalizeIssue(first);
+		},
+
+		async create(title, options) {
+			const args = ["create", title, "--json"];
+			if (options?.type) {
+				args.push("--type", options.type);
+			}
+			if (options?.priority !== undefined) {
+				args.push("--priority", String(options.priority));
+			}
+			if (options?.description) {
+				args.push("--description", options.description);
+			}
+			const { stdout } = await runBd(args, "create");
+			const result = parseJsonOutput<{ id: string }>(stdout, "create");
+			return result.id;
+		},
+
+		async claim(id) {
+			await runBd(["update", id, "--status", "in_progress"], `claim ${id}`);
+		},
+
+		async close(id, reason) {
+			const args = ["close", id];
+			if (reason) {
+				args.push("--reason", reason);
+			}
+			await runBd(args, `close ${id}`);
+		},
+
+		async list(options) {
+			const args = ["list", "--json"];
+			if (options?.status) {
+				args.push("--status", options.status);
+			}
+			if (options?.limit !== undefined) {
+				args.push("--limit", String(options.limit));
+			}
+			try {
+				const { stdout } = await runBd(args, "list");
+				const trimmed = stdout.trim();
+				if (trimmed === "") return [];
+				const parsed: unknown = JSON.parse(trimmed);
+				if (Array.isArray(parsed)) {
+					// Flat format: RawBeadIssue[]
+					return (parsed as RawBeadIssue[]).map(normalizeIssue);
+				}
+				if (typeof parsed === "object" && parsed !== null) {
+					// Tree format: { mol: RawBeadIssue[] } — flatten all groups
+					const tree = parsed as Record<string, unknown>;
+					const issues: BeadIssue[] = [];
+					for (const group of Object.values(tree)) {
+						if (Array.isArray(group)) {
+							for (const item of group) {
+								issues.push(normalizeIssue(item as RawBeadIssue));
+							}
+						}
+					}
+					if (issues.length > 0) return issues;
+				}
+			} catch {
+				// fall through to ready fallback
+			}
+			// Fallback: bd ready --json always returns a flat array
+			const { stdout: readyStdout } = await runBd(["ready", "--json"], "ready (list fallback)");
+			const readyTrimmed = readyStdout.trim();
+			if (readyTrimmed === "") return [];
+			const readyRaw = parseJsonOutput<RawBeadIssue[]>(readyTrimmed, "ready (list fallback)");
+			return readyRaw.map(normalizeIssue);
+		},
+	};
+}