@ag-eco/agentplate-cli 0.13.0

package/src/tracker/beads.test.ts

@@ -0,0 +1,454 @@
+/**
+ * Beads tracker adapter tests.
+ *
+ * Uses Bun.spawn mocks — legitimate exception to "never mock what you can use for real".
+ * The `bd` CLI may not be installed in all environments and would modify real tracker
+ * state (creating/closing actual beads) if invoked directly in tests.
+ */
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { AgentError } from "../errors.ts";
+import { createBeadsTracker } from "./beads.ts";
+
+/**
+ * Helper to create a mock Bun.spawn return value.
+ *
+ * The actual code reads stdout/stderr via `new Response(proc.stdout).text()`
+ * and `new Response(proc.stderr).text()`, so we need ReadableStreams.
+ */
+function mockSpawnResult(
+	stdout: string,
+	stderr: string,
+	exitCode: number,
+): {
+	stdout: ReadableStream<Uint8Array>;
+	stderr: ReadableStream<Uint8Array>;
+	exited: Promise<number>;
+	pid: number;
+} {
+	return {
+		stdout: new Response(stdout).body as ReadableStream<Uint8Array>,
+		stderr: new Response(stderr).body as ReadableStream<Uint8Array>,
+		exited: Promise.resolve(exitCode),
+		pid: 12345,
+	};
+}
+
+const TEST_CWD = "/test/repo";
+
+describe("createBeadsTracker — ready()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns normalized TrackerIssue[] with issue_type → type mapping", async () => {
+		const raw = [
+			{
+				id: "bd-1",
+				title: "Fix login",
+				status: "open",
+				priority: 1,
+				issue_type: "bug",
+			},
+			{
+				id: "bd-2",
+				title: "Add auth",
+				status: "open",
+				priority: 2,
+				issue_type: "feature",
+				assignee: "bob",
+			},
+		];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues).toHaveLength(2);
+		expect(issues[0]).toMatchObject({ id: "bd-1", title: "Fix login", type: "bug" });
+		expect(issues[1]).toMatchObject({ id: "bd-2", type: "feature", assignee: "bob" });
+	});
+
+	test("verifies CLI args: [bd, ready, --json]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.ready();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "ready", "--json"]);
+	});
+
+	test("throws AgentError on non-zero exit code", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "bd: command not found", 1));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await expect(tracker.ready()).rejects.toThrow(AgentError);
+	});
+});
+
+describe("createBeadsTracker — show()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns normalized TrackerIssue from bd array response", async () => {
+		// bd show --json returns an array with a single element
+		const raw = [
+			{
+				id: "bd-42",
+				title: "Critical bug",
+				status: "open",
+				priority: 1,
+				issue_type: "bug",
+				description: "Crashes on startup",
+				blocks: ["bd-50"],
+			},
+		];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issue = await tracker.show("bd-42");
+
+		expect(issue).toMatchObject({
+			id: "bd-42",
+			title: "Critical bug",
+			type: "bug",
+			description: "Crashes on startup",
+			blocks: ["bd-50"],
+		});
+	});
+
+	test("throws AgentError when bd returns empty array", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await expect(tracker.show("bd-99")).rejects.toThrow(AgentError);
+	});
+
+	test("verifies CLI args: [bd, show, <id>, --json]", async () => {
+		const raw = [{ id: "bd-1", title: "t", status: "open", priority: 1, issue_type: "task" }];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.show("bd-1");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "show", "bd-1", "--json"]);
+	});
+});
+
+describe("createBeadsTracker — create()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns new issue ID from { id: '...' } response", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify({ id: "bd-101" }), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const id = await tracker.create("New feature");
+
+		expect(id).toBe("bd-101");
+	});
+
+	test("verifies CLI args: [bd, create, <title>, --json]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify({ id: "bd-1" }), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.create("My Issue");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd[0]).toBe("bd");
+		expect(cmd[1]).toBe("create");
+		expect(cmd[2]).toBe("My Issue");
+		expect(cmd).toContain("--json");
+	});
+
+	test("passes optional --type, --priority, --description args", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify({ id: "bd-200" }), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.create("My task", {
+			type: "feature",
+			priority: 2,
+			description: "A detailed description",
+		});
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toContain("--type");
+		expect(cmd).toContain("feature");
+		expect(cmd).toContain("--priority");
+		expect(cmd).toContain("2");
+		expect(cmd).toContain("--description");
+		expect(cmd).toContain("A detailed description");
+	});
+});
+
+describe("createBeadsTracker — claim()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("calls [bd, update, <id>, --status, in_progress]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.claim("bd-7");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "update", "bd-7", "--status", "in_progress"]);
+	});
+});
+
+describe("createBeadsTracker — close()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("calls [bd, close, <id>] without reason", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.close("bd-10");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "close", "bd-10"]);
+	});
+
+	test("calls [bd, close, <id>, --reason, ...] with reason", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.close("bd-10", "Completed implementation");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "close", "bd-10", "--reason", "Completed implementation"]);
+	});
+});
+
+describe("createBeadsTracker — list()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns normalized issues from bd array response", async () => {
+		const raw = [
+			{ id: "bd-1", title: "Task A", status: "open", priority: 1, issue_type: "task" },
+			{
+				id: "bd-2",
+				title: "Bug B",
+				status: "in_progress",
+				priority: 2,
+				issue_type: "bug",
+			},
+		];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.list();
+
+		expect(issues).toHaveLength(2);
+		expect(issues[0]).toMatchObject({ id: "bd-1", type: "task" });
+		expect(issues[1]).toMatchObject({ id: "bd-2", type: "bug", status: "in_progress" });
+	});
+
+	test("verifies CLI args: [bd, list, --json]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.list();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd[0]).toBe("bd");
+		expect(cmd[1]).toBe("list");
+		expect(cmd).toContain("--json");
+	});
+
+	test("passes --status and --limit options", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.list({ status: "open", limit: 5 });
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toContain("--status");
+		expect(cmd).toContain("open");
+		expect(cmd).toContain("--limit");
+		expect(cmd).toContain("5");
+	});
+});
+
+describe("createBeadsTracker — sync()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("calls [bd, sync] directly (not via beads client)", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.sync();
+
+		// sync() calls Bun.spawn directly in beads.ts, not via the beads client
+		expect(spawnSpy).toHaveBeenCalledTimes(1);
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "sync"]);
+	});
+
+	test("throws AgentError on failure", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "bd sync failed", 1));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await expect(tracker.sync()).rejects.toThrow(AgentError);
+	});
+});
+
+describe("createBeadsTracker — issue_type normalization", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("maps issue_type to type field", async () => {
+		const raw = [{ id: "bd-1", title: "t", status: "open", priority: 1, issue_type: "bug" }];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues[0]?.type).toBe("bug");
+	});
+
+	test("falls back to type when issue_type absent", async () => {
+		const raw = [{ id: "bd-1", title: "t", status: "open", priority: 1, type: "feature" }];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues[0]?.type).toBe("feature");
+	});
+
+	test("defaults to 'unknown' when neither issue_type nor type present", async () => {
+		const raw = [{ id: "bd-1", title: "t", status: "open", priority: 1 }];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues[0]?.type).toBe("unknown");
+	});
+
+	test("prefers issue_type over type when both present", async () => {
+		const raw = [
+			{
+				id: "bd-1",
+				title: "t",
+				status: "open",
+				priority: 1,
+				issue_type: "bug",
+				type: "feature",
+			},
+		];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues[0]?.type).toBe("bug");
+	});
+});
+
+describe("createBeadsTracker — cwd propagation", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("propagates cwd to Bun.spawn for ready()", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const customCwd = "/my/project/root";
+		const tracker = createBeadsTracker(customCwd);
+		await tracker.ready();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const opts = callArgs[1] as { cwd: string };
+		expect(opts.cwd).toBe(customCwd);
+	});
+
+	test("propagates cwd to Bun.spawn for sync()", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const customCwd = "/my/project/root";
+		const tracker = createBeadsTracker(customCwd);
+		await tracker.sync();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const opts = callArgs[1] as { cwd: string };
+		expect(opts.cwd).toBe(customCwd);
+	});
+});

package/src/tracker/beads.ts

@@ -0,0 +1,56 @@
+/**
+ * Beads tracker adapter.
+ *
+ * Wraps src/beads/client.ts to implement the unified TrackerClient interface.
+ */
+
+import { createBeadsClient } from "../beads/client.ts";
+import { AgentError } from "../errors.ts";
+import type { TrackerClient, TrackerIssue } from "./types.ts";
+
+/**
+ * Create a TrackerClient backed by the beads (bd) CLI.
+ *
+ * @param cwd - Working directory for bd commands
+ */
+export function createBeadsTracker(cwd: string): TrackerClient {
+	const client = createBeadsClient(cwd);
+
+	return {
+		async ready() {
+			const issues = await client.ready();
+			return issues as TrackerIssue[];
+		},
+
+		async show(id) {
+			const issue = await client.show(id);
+			return issue as TrackerIssue;
+		},
+
+		async create(title, options) {
+			return client.create(title, options);
+		},
+
+		async claim(id) {
+			return client.claim(id);
+		},
+
+		async close(id, reason) {
+			return client.close(id, reason);
+		},
+
+		async list(options) {
+			const issues = await client.list(options);
+			return issues as TrackerIssue[];
+		},
+
+		async sync() {
+			const proc = Bun.spawn(["bd", "sync"], { cwd, stdout: "pipe", stderr: "pipe" });
+			const exitCode = await proc.exited;
+			if (exitCode !== 0) {
+				const stderr = await new Response(proc.stderr).text();
+				throw new AgentError(`bd sync failed (exit ${exitCode}): ${stderr.trim()}`);
+			}
+		},
+	};
+}

package/src/tracker/factory.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTrackerClient, resolveBackend, trackerCliName } from "./factory.ts";
+
+describe("createTrackerClient", () => {
+	test("creates beads tracker for beads backend", () => {
+		const client = createTrackerClient("beads", "/tmp");
+		expect(client).toBeDefined();
+		expect(client.ready).toBeTypeOf("function");
+		expect(client.show).toBeTypeOf("function");
+		expect(client.create).toBeTypeOf("function");
+		expect(client.claim).toBeTypeOf("function");
+		expect(client.close).toBeTypeOf("function");
+		expect(client.list).toBeTypeOf("function");
+		expect(client.sync).toBeTypeOf("function");
+	});
+
+	test("creates sprout tracker for sprout backend", () => {
+		const client = createTrackerClient("sprout", "/tmp");
+		expect(client).toBeDefined();
+		expect(client.ready).toBeTypeOf("function");
+		expect(client.show).toBeTypeOf("function");
+		expect(client.create).toBeTypeOf("function");
+		expect(client.claim).toBeTypeOf("function");
+		expect(client.close).toBeTypeOf("function");
+		expect(client.list).toBeTypeOf("function");
+		expect(client.sync).toBeTypeOf("function");
+	});
+
+	test("throws for invalid backend", () => {
+		// @ts-expect-error - intentionally testing runtime guard
+		expect(() => createTrackerClient("invalid", "/tmp")).toThrow();
+	});
+});
+
+describe("resolveBackend", () => {
+	test("returns beads for beads backend", async () => {
+		expect(await resolveBackend("beads", "/tmp")).toBe("beads");
+	});
+	test("returns sprout for sprout backend", async () => {
+		expect(await resolveBackend("sprout", "/tmp")).toBe("sprout");
+	});
+	test("returns sprout for auto when no tracker dirs exist", async () => {
+		const tempDir = await mkdtemp(join(tmpdir(), "tracker-test-"));
+		try {
+			expect(await resolveBackend("auto", tempDir)).toBe("sprout");
+		} finally {
+			await rm(tempDir, { recursive: true });
+		}
+	});
+	test("returns sprout for auto when .sprout/ exists", async () => {
+		const tempDir = await mkdtemp(join(tmpdir(), "tracker-test-"));
+		try {
+			await mkdir(join(tempDir, ".sprout"));
+			expect(await resolveBackend("auto", tempDir)).toBe("sprout");
+		} finally {
+			await rm(tempDir, { recursive: true });
+		}
+	});
+	test("returns beads for auto when .beads/ exists", async () => {
+		const tempDir = await mkdtemp(join(tmpdir(), "tracker-test-"));
+		try {
+			await mkdir(join(tempDir, ".beads"));
+			expect(await resolveBackend("auto", tempDir)).toBe("beads");
+		} finally {
+			await rm(tempDir, { recursive: true });
+		}
+	});
+	test("returns beads for auto when both .sprout/ and .beads/ exist", async () => {
+		const tempDir = await mkdtemp(join(tmpdir(), "tracker-test-"));
+		try {
+			await mkdir(join(tempDir, ".beads"));
+			await mkdir(join(tempDir, ".sprout"));
+			expect(await resolveBackend("auto", tempDir)).toBe("beads");
+		} finally {
+			await rm(tempDir, { recursive: true });
+		}
+	});
+});
+
+describe("trackerCliName", () => {
+	test("returns bd for beads", () => {
+		expect(trackerCliName("beads")).toBe("bd");
+	});
+	test("returns sr for sprout", () => {
+		expect(trackerCliName("sprout")).toBe("sr");
+	});
+});

package/src/tracker/factory.ts

@@ -0,0 +1,65 @@
+/**
+ * Tracker factory — creates the right backend client based on configuration.
+ */
+
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { TaskTrackerBackend } from "../types.ts";
+import { createBeadsTracker } from "./beads.ts";
+import { createSproutTracker } from "./sprout.ts";
+import type { TrackerBackend, TrackerClient } from "./types.ts";
+
+/**
+ * Create a tracker client for the specified backend.
+ *
+ * @param backend - Which backend to use ("beads" or "sprout")
+ * @param cwd - Working directory for CLI commands
+ */
+export function createTrackerClient(backend: TrackerBackend, cwd: string): TrackerClient {
+	switch (backend) {
+		case "beads":
+			return createBeadsTracker(cwd);
+		case "sprout":
+			return createSproutTracker(cwd);
+		default: {
+			const _exhaustive: never = backend;
+			throw new Error(`Unknown tracker backend: ${_exhaustive}`);
+		}
+	}
+}
+
+/**
+ * Resolve "auto" to a concrete backend by probing the filesystem.
+ * Explicit "beads" or "sprout" values pass through unchanged.
+ */
+export async function resolveBackend(
+	configBackend: TaskTrackerBackend,
+	cwd: string,
+): Promise<TrackerBackend> {
+	if (configBackend === "beads") return "beads";
+	if (configBackend === "sprout") return "sprout";
+	// "auto" detection: check for .beads/ first (never auto-scaffolded by ap init,
+	// so its presence signals explicit user setup), then .sprout/.
+	const dirExists = async (path: string): Promise<boolean> => {
+		try {
+			const s = await stat(path);
+			return s.isDirectory();
+		} catch {
+			return false;
+		}
+	};
+	if (await dirExists(join(cwd, ".beads"))) return "beads";
+	if (await dirExists(join(cwd, ".sprout"))) return "sprout";
+	// Default fallback — sprout is the preferred tracker
+	return "sprout";
+}
+
+/**
+ * Return the CLI tool name for a resolved backend.
+ */
+export function trackerCliName(backend: TrackerBackend): string {
+	return backend === "sprout" ? "sr" : "bd";
+}
+
+// Re-export types for convenience
+export type { TrackerBackend, TrackerClient, TrackerIssue } from "./types.ts";