@os-eco/overstory-cli 0.6.1

package/src/test-helpers.ts

@@ -0,0 +1,126 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Git environment variables for test repos.
+ * Using env vars instead of per-repo `git config` eliminates 2 subprocess
+ * spawns per repo creation.
+ */
+const GIT_TEST_ENV = {
+	GIT_AUTHOR_NAME: "Overstory Test",
+	GIT_AUTHOR_EMAIL: "test@overstory.dev",
+	GIT_COMMITTER_NAME: "Overstory Test",
+	GIT_COMMITTER_EMAIL: "test@overstory.dev",
+};
+
+/** Cached template repo path. Created lazily on first call. */
+let _templateDir: string | null = null;
+
+/**
+ * Get or create a template git repo with an initial commit.
+ * All test repos clone from this template (1 subprocess instead of 5).
+ */
+async function getTemplateRepo(): Promise<string> {
+	if (_templateDir) return _templateDir;
+
+	const dir = await mkdtemp(join(tmpdir(), "overstory-template-"));
+	await runGitInDir(dir, ["init", "-b", "main"]);
+	await Bun.write(join(dir, ".gitkeep"), "");
+	await runGitInDir(dir, ["add", ".gitkeep"]);
+	await runGitInDir(dir, ["commit", "-m", "initial commit"]);
+
+	_templateDir = dir;
+	return dir;
+}
+
+/**
+ * Create a temporary directory with a real git repo initialized.
+ * Includes an initial commit so branches can be created immediately.
+ *
+ * Uses a cached template repo + `git clone --local` for speed:
+ * 1 subprocess per call instead of 5.
+ *
+ * @returns The absolute path to the temp git repo.
+ */
+export async function createTempGitRepo(): Promise<string> {
+	const template = await getTemplateRepo();
+	const dir = await mkdtemp(join(tmpdir(), "overstory-test-"));
+	// Clone into the empty dir. Avoid --local (hardlinks trigger EFAULT in Bun's rm).
+	await runGitInDir(".", ["clone", template, dir]);
+	// Set git identity at repo level so code that doesn't use GIT_TEST_ENV
+	// (e.g., resolver's runGit) can still commit. Locally this is covered by
+	// ~/.gitconfig, but CI runners have no global git identity.
+	await runGitInDir(dir, ["config", "user.name", "Overstory Test"]);
+	await runGitInDir(dir, ["config", "user.email", "test@overstory.dev"]);
+	return dir;
+}
+
+/**
+ * Add and commit a file to a git repo.
+ *
+ * @param repoDir - Absolute path to the git repo
+ * @param filePath - Relative path within the repo (e.g. "src/foo.ts")
+ * @param content - File content to write
+ * @param message - Commit message (defaults to "add {filePath}")
+ */
+export async function commitFile(
+	repoDir: string,
+	filePath: string,
+	content: string,
+	message?: string,
+): Promise<void> {
+	const fullPath = join(repoDir, filePath);
+
+	// Ensure parent directories exist
+	const parentDir = join(fullPath, "..");
+	const { mkdir } = await import("node:fs/promises");
+	await mkdir(parentDir, { recursive: true });
+
+	await Bun.write(fullPath, content);
+	await runGitInDir(repoDir, ["add", filePath]);
+	await runGitInDir(repoDir, ["commit", "-m", message ?? `add ${filePath}`]);
+}
+
+/**
+ * Get the default branch name of a git repo (e.g., "main" or "master").
+ * Uses `git symbolic-ref --short HEAD` to read the current branch.
+ *
+ * Useful in tests to avoid hardcoding "main" -- CI runners may default to "master".
+ */
+export async function getDefaultBranch(repoDir: string): Promise<string> {
+	const stdout = await runGitInDir(repoDir, ["symbolic-ref", "--short", "HEAD"]);
+	return stdout.trim();
+}
+
+/**
+ * Remove a temp directory. Safe to call even if the directory doesn't exist.
+ */
+export async function cleanupTempDir(dir: string): Promise<void> {
+	await rm(dir, { recursive: true, force: true });
+}
+
+/**
+ * Run a git command in the given directory. Throws on non-zero exit.
+ * Passes GIT_AUTHOR/COMMITTER env vars so repos don't need per-repo config.
+ */
+export async function runGitInDir(cwd: string, args: string[]): Promise<string> {
+	const proc = Bun.spawn(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+		env: { ...process.env, ...GIT_TEST_ENV },
+	});
+
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+
+	if (exitCode !== 0) {
+		throw new Error(`git ${args.join(" ")} failed (exit ${exitCode}): ${stderr.trim()}`);
+	}
+
+	return stdout;
+}

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,80 @@
+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 seeds tracker for seeds backend", () => {
+		const client = createTrackerClient("seeds", "/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 seeds for seeds backend", async () => {
+		expect(await resolveBackend("seeds", "/tmp")).toBe("seeds");
+	});
+	test("returns seeds for auto when no tracker dirs exist", async () => {
+		const tempDir = await mkdtemp(join(tmpdir(), "tracker-test-"));
+		try {
+			expect(await resolveBackend("auto", tempDir)).toBe("seeds");
+		} finally {
+			await rm(tempDir, { recursive: true });
+		}
+	});
+	test("returns seeds for auto when .seeds/ exists", async () => {
+		const tempDir = await mkdtemp(join(tmpdir(), "tracker-test-"));
+		try {
+			await mkdir(join(tempDir, ".seeds"));
+			expect(await resolveBackend("auto", tempDir)).toBe("seeds");
+		} 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 });
+		}
+	});
+});
+
+describe("trackerCliName", () => {
+	test("returns bd for beads", () => {
+		expect(trackerCliName("beads")).toBe("bd");
+	});
+	test("returns sd for seeds", () => {
+		expect(trackerCliName("seeds")).toBe("sd");
+	});
+});

package/src/tracker/factory.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 { createSeedsTracker } from "./seeds.ts";
+import type { TrackerBackend, TrackerClient } from "./types.ts";
+
+/**
+ * Create a tracker client for the specified backend.
+ *
+ * @param backend - Which backend to use ("beads" or "seeds")
+ * @param cwd - Working directory for CLI commands
+ */
+export function createTrackerClient(backend: TrackerBackend, cwd: string): TrackerClient {
+	switch (backend) {
+		case "beads":
+			return createBeadsTracker(cwd);
+		case "seeds":
+			return createSeedsTracker(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 "seeds" values pass through unchanged.
+ */
+export async function resolveBackend(
+	configBackend: TaskTrackerBackend,
+	cwd: string,
+): Promise<TrackerBackend> {
+	if (configBackend === "beads") return "beads";
+	if (configBackend === "seeds") return "seeds";
+	// "auto" detection: check for .seeds/ directory first (newer tool), then .beads/
+	const dirExists = async (path: string): Promise<boolean> => {
+		try {
+			const s = await stat(path);
+			return s.isDirectory();
+		} catch {
+			return false;
+		}
+	};
+	if (await dirExists(join(cwd, ".seeds"))) return "seeds";
+	if (await dirExists(join(cwd, ".beads"))) return "beads";
+	// Default fallback — seeds is the preferred tracker
+	return "seeds";
+}
+
+/**
+ * Return the CLI tool name for a resolved backend.
+ */
+export function trackerCliName(backend: TrackerBackend): string {
+	return backend === "seeds" ? "sd" : "bd";
+}
+
+// Re-export types for convenience
+export type { TrackerBackend, TrackerClient, TrackerIssue } from "./types.ts";

package/src/tracker/seeds.ts

@@ -0,0 +1,182 @@
+/**
+ * Seeds tracker adapter.
+ *
+ * Implements the unified TrackerClient interface by calling the `sd` CLI directly
+ * via Bun.spawn. Seeds uses a { success, command, ...data } JSON envelope.
+ */
+
+import { AgentError } from "../errors.ts";
+import type { TrackerClient, TrackerIssue } from "./types.ts";
+
+/**
+ * Run an sd command and return its output.
+ */
+async function runSd(
+	args: string[],
+	cwd: string,
+	context: string,
+): Promise<{ stdout: string; stderr: string }> {
+	const proc = Bun.spawn(["sd", ...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(`sd ${context} failed (exit ${exitCode}): ${stderr.trim()}`);
+	}
+	return { stdout, stderr };
+}
+
+/**
+ * Parse JSON from sd 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 sd ${context}`);
+	}
+	// Seeds 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 sd ${context}: ${trimmed.slice(0, 200)}`,
+		);
+	}
+}
+
+/** Base envelope shape shared by all sd JSON responses. */
+interface SdEnvelopeBase {
+	success: boolean;
+	command: string;
+	error?: string;
+}
+
+/** Seeds JSON envelope for list-style responses. */
+interface SdListEnvelope extends SdEnvelopeBase {
+	issues: SdRawIssue[];
+}
+
+/** Seeds JSON envelope for single-issue responses. */
+interface SdShowEnvelope extends SdEnvelopeBase {
+	issue: SdRawIssue;
+}
+
+/** Seeds JSON envelope for create responses. */
+interface SdCreateEnvelope extends SdEnvelopeBase {
+	id?: string;
+	issue?: { id: string };
+}
+
+/**
+ * Validate that an sd 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(`sd ${context} returned failure: ${detail}`);
+	}
+}
+
+/** Raw issue shape from the sd CLI. Seeds 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 seeds (sd) CLI.
+ *
+ * @param cwd - Working directory for sd commands
+ */
+export function createSeedsTracker(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("sd 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 seeds backends.
+ * This module is self-contained and does NOT import from src/types.ts.
+ */
+
+/**
+ * A tracker issue — unified across beads and seeds 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 seeds 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" | "seeds";