@ag-eco/agentplate-cli 0.13.0

package/src/tracker/sprout.test.ts

@@ -0,0 +1,461 @@
+/**
+ * Sprout tracker adapter tests.
+ *
+ * Uses Bun.spawn mocks — legitimate exception to "never mock what you can use for real".
+ * The `sr` CLI may not be installed in all environments and would modify real tracker
+ * state (creating/closing actual issues) if invoked directly in tests.
+ */
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { AgentError } from "../errors.ts";
+import { createSproutTracker } from "./sprout.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("createSproutTracker — ready()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("parses envelope and returns normalized TrackerIssue[]", async () => {
+		const envelope = {
+			success: true,
+			command: "ready",
+			issues: [
+				{ id: "sr-1", title: "Fix bug", status: "open", priority: 1, type: "task" },
+				{
+					id: "sr-2",
+					title: "Add feature",
+					status: "open",
+					priority: 2,
+					type: "feature",
+					assignee: "alice",
+					blocks: ["sr-5"],
+				},
+			],
+		};
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues).toHaveLength(2);
+		expect(issues[0]).toMatchObject({ id: "sr-1", title: "Fix bug", type: "task" });
+		expect(issues[1]).toMatchObject({ id: "sr-2", assignee: "alice", blocks: ["sr-5"] });
+	});
+
+	test("verifies CLI args: [sr, ready, --json]", async () => {
+		spawnSpy.mockImplementation(() =>
+			mockSpawnResult(JSON.stringify({ success: true, command: "ready", issues: [] }), "", 0),
+		);
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await tracker.ready();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["sr", "ready", "--json"]);
+	});
+
+	test("throws AgentError on non-zero exit code", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "sr: command failed", 1));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await expect(tracker.ready()).rejects.toThrow(AgentError);
+	});
+
+	test("throws AgentError on envelope failure", async () => {
+		const envelope = { success: false, command: "ready", error: "no issues available" };
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await expect(tracker.ready()).rejects.toThrow(AgentError);
+	});
+
+	test("throws AgentError on empty output", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await expect(tracker.ready()).rejects.toThrow(AgentError);
+	});
+});
+
+describe("createSproutTracker — show()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns normalized TrackerIssue from envelope", async () => {
+		const envelope = {
+			success: true,
+			command: "show",
+			issue: {
+				id: "sr-42",
+				title: "My issue",
+				status: "open",
+				priority: 3,
+				type: "bug",
+				description: "A detailed bug report",
+				blockedBy: ["sr-10"],
+			},
+		};
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		const issue = await tracker.show("sr-42");
+
+		expect(issue).toMatchObject({
+			id: "sr-42",
+			title: "My issue",
+			type: "bug",
+			description: "A detailed bug report",
+			blockedBy: ["sr-10"],
+		});
+	});
+
+	test("verifies CLI args: [sr, show, <id>, --json]", async () => {
+		const envelope = {
+			success: true,
+			command: "show",
+			issue: { id: "sr-1", title: "t", status: "open", priority: 1, type: "task" },
+		};
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await tracker.show("sr-1");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["sr", "show", "sr-1", "--json"]);
+	});
+
+	test("throws AgentError on non-zero exit code", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "issue not found", 1));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await expect(tracker.show("sr-999")).rejects.toThrow(AgentError);
+	});
+});
+
+describe("createSproutTracker — create()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns issue ID from envelope.id", async () => {
+		const envelope = { success: true, command: "create", id: "sr-100" };
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		const id = await tracker.create("New issue");
+
+		expect(id).toBe("sr-100");
+	});
+
+	test("returns issue ID from envelope.issue.id (alternate format)", async () => {
+		const envelope = { success: true, command: "create", issue: { id: "sr-200" } };
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		const id = await tracker.create("Another issue");
+
+		expect(id).toBe("sr-200");
+	});
+
+	test("passes optional --type, --priority, --description args", async () => {
+		const envelope = { success: true, command: "create", id: "sr-300" };
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(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");
+	});
+
+	test("throws AgentError when no ID returned in envelope", async () => {
+		const envelope = { success: true, command: "create" };
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await expect(tracker.create("No ID")).rejects.toThrow(AgentError);
+	});
+
+	test("throws AgentError on envelope failure", async () => {
+		const envelope = { success: false, command: "create", error: "validation failed" };
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await expect(tracker.create("Bad issue")).rejects.toThrow(AgentError);
+	});
+});
+
+describe("createSproutTracker — claim()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("calls [sr, update, <id>, --status, in_progress]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await tracker.claim("sr-5");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["sr", "update", "sr-5", "--status", "in_progress"]);
+	});
+
+	test("throws AgentError on failure", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "issue already claimed", 1));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await expect(tracker.claim("sr-5")).rejects.toThrow(AgentError);
+	});
+});
+
+describe("createSproutTracker — close()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("calls [sr, close, <id>] without reason", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await tracker.close("sr-10");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["sr", "close", "sr-10"]);
+	});
+
+	test("calls [sr, close, <id>, --reason, ...] with reason", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await tracker.close("sr-10", "Done implementing");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["sr", "close", "sr-10", "--reason", "Done implementing"]);
+	});
+});
+
+describe("createSproutTracker — list()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns normalized issues from envelope", async () => {
+		const envelope = {
+			success: true,
+			command: "list",
+			issues: [
+				{ id: "sr-1", title: "Issue A", status: "open", priority: 1, type: "task" },
+				{ id: "sr-2", title: "Issue B", status: "in_progress", priority: 2, type: "bug" },
+			],
+		};
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		const issues = await tracker.list();
+
+		expect(issues).toHaveLength(2);
+		expect(issues[0]).toMatchObject({ id: "sr-1", status: "open" });
+		expect(issues[1]).toMatchObject({ id: "sr-2", status: "in_progress" });
+	});
+
+	test("verifies CLI args: [sr, list, --json]", async () => {
+		spawnSpy.mockImplementation(() =>
+			mockSpawnResult(JSON.stringify({ success: true, command: "list", issues: [] }), "", 0),
+		);
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await tracker.list();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd[0]).toBe("sr");
+		expect(cmd[1]).toBe("list");
+		expect(cmd).toContain("--json");
+	});
+
+	test("passes --status and --limit options", async () => {
+		const envelope = { success: true, command: "list", issues: [] };
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await tracker.list({ status: "open", limit: 10 });
+
+		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("10");
+	});
+});
+
+describe("createSproutTracker — sync()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("calls [sr, sync]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await tracker.sync();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["sr", "sync"]);
+	});
+
+	test("throws AgentError on failure", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "sync failed: dirty working tree", 1));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await expect(tracker.sync()).rejects.toThrow(AgentError);
+	});
+});
+
+describe("createSproutTracker — edge cases", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("strips non-JSON prefix lines before parsing", async () => {
+		const envelope = {
+			success: true,
+			command: "ready",
+			issues: [{ id: "sr-1", title: "Test", status: "open", priority: 1, type: "task" }],
+		};
+		const output = `Syncing with remote...\nDone.\n${JSON.stringify(envelope)}`;
+		spawnSpy.mockImplementation(() => mockSpawnResult(output, "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues).toHaveLength(1);
+		expect(issues[0]).toMatchObject({ id: "sr-1" });
+	});
+
+	test("throws AgentError on invalid JSON", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("{not: valid json}", "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		await expect(tracker.ready()).rejects.toThrow(AgentError);
+	});
+
+	test("handles envelope with missing error field (defaults to 'unknown error')", async () => {
+		const envelope = { success: false, command: "ready" }; // No error field
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const tracker = createSproutTracker(TEST_CWD);
+		try {
+			await tracker.ready();
+			expect(true).toBe(false); // Should have thrown
+		} catch (err: unknown) {
+			expect(err).toBeInstanceOf(AgentError);
+			const agentErr = err as AgentError;
+			expect(agentErr.message).toContain("unknown error");
+		}
+	});
+
+	test("propagates cwd to Bun.spawn", async () => {
+		const envelope = { success: true, command: "ready", issues: [] };
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(envelope), "", 0));
+
+		const customCwd = "/my/custom/project";
+		const tracker = createSproutTracker(customCwd);
+		await tracker.ready();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const opts = callArgs[1] as { cwd: string };
+		expect(opts.cwd).toBe(customCwd);
+	});
+});

package/src/tracker/sprout.ts

@@ -0,0 +1,182 @@
+/**
+ * Sprout tracker adapter.
+ *
+ * Implements the unified TrackerClient interface by calling the `sr` CLI directly
+ * via Bun.spawn. Sprout uses a { success, command, ...data } JSON envelope.
+ */
+
+import { AgentError } from "../errors.ts";
+import type { TrackerClient, TrackerIssue } from "./types.ts";
+
+/**
+ * Run an sr command and return its output.
+ */
+async function runSd(
+	args: string[],
+	cwd: string,
+	context: string,
+): Promise<{ stdout: string; stderr: string }> {
+	const proc = Bun.spawn(["sr", ...args], { 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;
+	if (exitCode !== 0) {
+		throw new AgentError(`sr ${context} failed (exit ${exitCode}): ${stderr.trim()}`);
+	}
+	return { stdout, stderr };
+}
+
+/**
+ * Parse JSON from sr output, stripping any non-JSON prefix lines.
+ */
+function parseSdJson<T>(stdout: string, context: string): T {
+	const trimmed = stdout.trim();
+	if (trimmed === "") {
+		throw new AgentError(`Empty output from sr ${context}`);
+	}
+	// Sprout may emit non-JSON lines before the JSON object; find the first '{' or '['
+	const jsonStart = trimmed.search(/[{[]/);
+	const jsonStr = jsonStart >= 0 ? trimmed.slice(jsonStart) : trimmed;
+	try {
+		return JSON.parse(jsonStr) as T;
+	} catch {
+		throw new AgentError(
+			`Failed to parse JSON output from sr ${context}: ${trimmed.slice(0, 200)}`,
+		);
+	}
+}
+
+/** Base envelope shape shared by all sr JSON responses. */
+interface SdEnvelopeBase {
+	success: boolean;
+	command: string;
+	error?: string;
+}
+
+/** Sprout JSON envelope for list-style responses. */
+interface SdListEnvelope extends SdEnvelopeBase {
+	issues: SdRawIssue[];
+}
+
+/** Sprout JSON envelope for single-issue responses. */
+interface SdShowEnvelope extends SdEnvelopeBase {
+	issue: SdRawIssue;
+}
+
+/** Sprout JSON envelope for create responses. */
+interface SdCreateEnvelope extends SdEnvelopeBase {
+	id?: string;
+	issue?: { id: string };
+}
+
+/**
+ * Validate that an sr envelope indicates success.
+ * Throws AgentError if the envelope reports failure.
+ */
+function assertEnvelopeSuccess(envelope: SdEnvelopeBase, context: string): void {
+	if (envelope.success === false) {
+		const detail = envelope.error ?? "unknown error";
+		throw new AgentError(`sr ${context} returned failure: ${detail}`);
+	}
+}
+
+/** Raw issue shape from the sr CLI. Sprout uses `type` directly (no issue_type mapping). */
+interface SdRawIssue {
+	id: string;
+	title: string;
+	status: string;
+	priority: number;
+	type: string;
+	assignee?: string;
+	description?: string;
+	blocks?: string[];
+	blockedBy?: string[];
+}
+
+function normalizeIssue(raw: SdRawIssue): TrackerIssue {
+	return {
+		id: raw.id,
+		title: raw.title,
+		status: raw.status,
+		priority: raw.priority,
+		type: raw.type ?? "unknown",
+		assignee: raw.assignee,
+		description: raw.description,
+		blocks: raw.blocks,
+		blockedBy: raw.blockedBy,
+	};
+}
+
+/**
+ * Create a TrackerClient backed by the sprout (sr) CLI.
+ *
+ * @param cwd - Working directory for sr commands
+ */
+export function createSproutTracker(cwd: string): TrackerClient {
+	return {
+		async ready() {
+			const { stdout } = await runSd(["ready", "--json"], cwd, "ready");
+			const envelope = parseSdJson<SdListEnvelope>(stdout, "ready");
+			assertEnvelopeSuccess(envelope, "ready");
+			return envelope.issues.map(normalizeIssue);
+		},
+
+		async show(id) {
+			const { stdout } = await runSd(["show", id, "--json"], cwd, `show ${id}`);
+			const envelope = parseSdJson<SdShowEnvelope>(stdout, `show ${id}`);
+			assertEnvelopeSuccess(envelope, `show ${id}`);
+			return normalizeIssue(envelope.issue);
+		},
+
+		async create(title, options) {
+			const args = ["create", "--title", 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 runSd(args, cwd, "create");
+			const envelope = parseSdJson<SdCreateEnvelope>(stdout, "create");
+			assertEnvelopeSuccess(envelope, "create");
+			const id = envelope.id ?? envelope.issue?.id;
+			if (!id) {
+				throw new AgentError("sr create did not return an issue ID");
+			}
+			return id;
+		},
+
+		async claim(id) {
+			await runSd(["update", id, "--status", "in_progress"], cwd, `claim ${id}`);
+		},
+
+		async close(id, reason) {
+			const args = ["close", id];
+			if (reason) {
+				args.push("--reason", reason);
+			}
+			await runSd(args, cwd, `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));
+			}
+			const { stdout } = await runSd(args, cwd, "list");
+			const envelope = parseSdJson<SdListEnvelope>(stdout, "list");
+			assertEnvelopeSuccess(envelope, "list");
+			return envelope.issues.map(normalizeIssue);
+		},
+
+		async sync() {
+			await runSd(["sync"], cwd, "sync");
+		},
+	};
+}

package/src/tracker/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Unified tracker types — shared across beads and sprout backends.
+ * This module is self-contained and does NOT import from src/types.ts.
+ */
+
+/**
+ * A tracker issue — unified across beads and sprout backends.
+ */
+export interface TrackerIssue {
+	id: string;
+	title: string;
+	status: string;
+	priority: number;
+	type: string;
+	assignee?: string;
+	description?: string;
+	blocks?: string[];
+	blockedBy?: string[];
+}
+
+/**
+ * Unified tracker client interface.
+ * Both beads and sprout backends implement this.
+ */
+export interface TrackerClient {
+	/** List issues that are ready for work (open, unblocked). */
+	ready(): Promise<TrackerIssue[]>;
+
+	/** Show details for a specific issue. */
+	show(id: string): Promise<TrackerIssue>;
+
+	/** 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<TrackerIssue[]>;
+
+	/** Sync tracker state with git (if supported). */
+	sync(): Promise<void>;
+}
+
+/** Which tracker backend to use. */
+export type TrackerBackend = "beads" | "sprout";