@os-eco/seeds-cli 0.2.0

package/src/config.ts

@@ -0,0 +1,39 @@
+import { dirname, join } from "node:path";
+import type { Config } from "./types.ts";
+import { CONFIG_FILE, SEEDS_DIR_NAME } from "./types.ts";
+import { parseYaml, stringifyYaml } from "./yaml.ts";
+
+export async function readConfig(seedsDir: string): Promise<Config> {
+	const file = Bun.file(join(seedsDir, CONFIG_FILE));
+	const content = await file.text();
+	const data = parseYaml(content);
+	return {
+		project: data.project ?? "seeds",
+		version: data.version ?? "1",
+	};
+}
+
+export async function writeConfig(seedsDir: string, config: Config): Promise<void> {
+	const content = stringifyYaml({ project: config.project, version: config.version });
+	await Bun.write(join(seedsDir, CONFIG_FILE), content);
+}
+
+export async function findSeedsDir(startDir?: string): Promise<string> {
+	let dir = startDir ?? process.cwd();
+	while (true) {
+		const configPath = join(dir, SEEDS_DIR_NAME, CONFIG_FILE);
+		const file = Bun.file(configPath);
+		if (await file.exists()) {
+			return join(dir, SEEDS_DIR_NAME);
+		}
+		const parent = dirname(dir);
+		if (parent === dir) {
+			throw new Error("Not in a seeds project. Run `sd init` first.");
+		}
+		dir = parent;
+	}
+}
+
+export function projectRootFromSeedsDir(seedsDir: string): string {
+	return dirname(seedsDir);
+}

package/src/id.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { generateId } from "./id";
+
+describe("generateId", () => {
+	test("returns id matching project-{4hex} pattern", () => {
+		const id = generateId("myproject", []);
+		expect(id).toMatch(/^myproject-[0-9a-f]{4}$/);
+	});
+
+	test("uses project name as prefix", () => {
+		const id = generateId("overstory", []);
+		expect(id.startsWith("overstory-")).toBe(true);
+	});
+
+	test("generates different ids on repeated calls", () => {
+		const ids = new Set<string>();
+		for (let i = 0; i < 20; i++) {
+			ids.add(generateId("proj", []));
+		}
+		// With 4 hex chars (65536 possibilities), 20 calls should almost certainly produce multiple unique values
+		// This test is probabilistic but reliable in practice
+		expect(ids.size).toBeGreaterThan(1);
+	});
+
+	test("avoids collisions with existing ids", () => {
+		// Fill all possible 1-char hex suffixes to force collision avoidance
+		// In practice, with 4 hex = 65536 options, collisions are extremely rare
+		const id1 = generateId("proj", []);
+		const id2 = generateId("proj", [id1]);
+		expect(id2).not.toBe(id1);
+	});
+
+	test("falls back to 8-char hex after many collisions", () => {
+		// Simulate 100 collisions by pre-filling many IDs
+		// The function should eventually produce a longer ID or succeed
+		// We just verify it doesn't throw and returns a valid id
+		const existing: string[] = [];
+		// This is a functional test — just ensure it completes
+		const id = generateId("p", existing);
+		expect(id).toMatch(/^p-[0-9a-f]{4,}$/);
+	});
+
+	test("handles project names with hyphens", () => {
+		const id = generateId("my-project", []);
+		expect(id).toMatch(/^my-project-[0-9a-f]{4}$/);
+	});
+
+	test("hex suffix uses lowercase letters", () => {
+		for (let i = 0; i < 10; i++) {
+			const id = generateId("proj", []);
+			const suffix = id.replace("proj-", "");
+			expect(suffix).toMatch(/^[0-9a-f]+$/);
+		}
+	});
+});

package/src/id.ts

@@ -0,0 +1,22 @@
+import { randomBytes } from "node:crypto";
+
+export function generateId(prefix: string, existingIds: Set<string> | string[]): string {
+	const idSet = existingIds instanceof Set ? existingIds : new Set(existingIds);
+	const makeId = (hexLen: number) =>
+		`${prefix}-${randomBytes(Math.ceil(hexLen / 2))
+			.toString("hex")
+			.slice(0, hexLen)}`;
+
+	let attempts = 0;
+	while (attempts < 100) {
+		const id = makeId(4);
+		if (!idSet.has(id)) return id;
+		attempts++;
+	}
+	// Fallback to 8 hex chars after 100 collisions
+	let id = makeId(8);
+	while (idSet.has(id)) {
+		id = makeId(8);
+	}
+	return id;
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env bun
+export const VERSION = "0.2.0";
+
+const USAGE = `seeds — git-native issue tracker
+
+Usage: sd <command> [options]
+
+Issue commands:
+  init                    Initialize .seeds/ in current directory
+  create                  Create a new issue
+  show <id>               Show issue details
+  list                    List issues with filters
+  ready                   Show open issues with no unresolved blockers
+  update <id>             Update issue fields
+  close <id> [ids...]     Close one or more issues
+  dep <add|remove|list>   Manage dependencies
+  blocked                 Show all blocked issues
+  stats                   Project statistics
+  sync                    Stage and commit .seeds/ changes
+  doctor                  Check project health and data integrity
+
+Template commands:
+  tpl create              Create a template
+  tpl step add <id>       Add a step to a template
+  tpl list                List all templates
+  tpl show <id>           Show template with steps
+  tpl pour <id>           Instantiate template into issues
+  tpl status <id>         Show convoy status
+
+Migration:
+  migrate-from-beads      Migrate issues from beads
+
+Agent integration:
+  prime                   Output AI agent context
+  onboard                 Add seeds section to CLAUDE.md
+
+Global flags:
+  --json                  Output as JSON
+  --version               Show version
+  --help                  Show this help
+`;
+
+const argv = process.argv;
+const cmd = argv[2];
+
+if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+	process.stdout.write(USAGE);
+	process.exit(0);
+}
+
+if (cmd === "--version" || cmd === "-V") {
+	console.log(VERSION);
+	process.exit(0);
+}
+
+const args = argv.slice(3);
+const jsonMode = args.includes("--json") || argv.slice(2).includes("--json");
+
+async function main(): Promise<void> {
+	switch (cmd) {
+		case "init":
+			await (await import("./commands/init.ts")).run(args);
+			break;
+		case "create":
+			await (await import("./commands/create.ts")).run(args);
+			break;
+		case "show":
+			await (await import("./commands/show.ts")).run(args);
+			break;
+		case "list":
+			await (await import("./commands/list.ts")).run(args);
+			break;
+		case "ready":
+			await (await import("./commands/ready.ts")).run(args);
+			break;
+		case "update":
+			await (await import("./commands/update.ts")).run(args);
+			break;
+		case "close":
+			await (await import("./commands/close.ts")).run(args);
+			break;
+		case "dep":
+			await (await import("./commands/dep.ts")).run(args);
+			break;
+		case "blocked":
+			await (await import("./commands/blocked.ts")).run(args);
+			break;
+		case "stats":
+			await (await import("./commands/stats.ts")).run(args);
+			break;
+		case "sync":
+			await (await import("./commands/sync.ts")).run(args);
+			break;
+		case "doctor":
+			await (await import("./commands/doctor.ts")).run(args);
+			break;
+		case "tpl":
+			await (await import("./commands/tpl.ts")).run(args);
+			break;
+		case "migrate-from-beads":
+			await (await import("./commands/migrate.ts")).run(args);
+			break;
+		case "prime":
+			await (await import("./commands/prime.ts")).run(args);
+			break;
+		case "onboard":
+			await (await import("./commands/onboard.ts")).run(args);
+			break;
+		default:
+			throw new Error(`Unknown command: ${cmd}. Run \`sd --help\` for usage.`);
+	}
+}
+
+main().catch((err: unknown) => {
+	const msg = err instanceof Error ? err.message : String(err);
+	if (jsonMode) {
+		console.log(JSON.stringify({ success: false, command: cmd, error: msg }));
+	} else {
+		console.error(`Error: ${msg}`);
+	}
+	process.exit(1);
+});

package/src/markers.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import {
+	END_MARKER,
+	START_MARKER,
+	hasMarkerSection,
+	replaceMarkerSection,
+	wrapInMarkers,
+} from "./markers.ts";
+
+describe("markers", () => {
+	test("START_MARKER and END_MARKER are correct", () => {
+		expect(START_MARKER).toBe("<!-- seeds:start -->");
+		expect(END_MARKER).toBe("<!-- seeds:end -->");
+	});
+
+	describe("hasMarkerSection", () => {
+		test("returns true when both markers present", () => {
+			const content = `before\n${START_MARKER}\nstuff\n${END_MARKER}\nafter`;
+			expect(hasMarkerSection(content)).toBe(true);
+		});
+
+		test("returns false when only start marker present", () => {
+			const content = `before\n${START_MARKER}\nstuff`;
+			expect(hasMarkerSection(content)).toBe(false);
+		});
+
+		test("returns false when only end marker present", () => {
+			const content = `stuff\n${END_MARKER}\nafter`;
+			expect(hasMarkerSection(content)).toBe(false);
+		});
+
+		test("returns false when no markers present", () => {
+			expect(hasMarkerSection("just some text")).toBe(false);
+		});
+	});
+
+	describe("wrapInMarkers", () => {
+		test("wraps content with start and end markers", () => {
+			const result = wrapInMarkers("hello world");
+			expect(result).toBe(`${START_MARKER}\nhello world\n${END_MARKER}`);
+		});
+
+		test("handles multi-line content", () => {
+			const result = wrapInMarkers("line 1\nline 2\nline 3");
+			expect(result).toBe(`${START_MARKER}\nline 1\nline 2\nline 3\n${END_MARKER}`);
+		});
+	});
+
+	describe("replaceMarkerSection", () => {
+		test("replaces content between markers", () => {
+			const content = `before\n${START_MARKER}\nold stuff\n${END_MARKER}\nafter`;
+			const result = replaceMarkerSection(content, "new stuff");
+			expect(result).toBe(`before\n${START_MARKER}\nnew stuff\n${END_MARKER}\nafter`);
+		});
+
+		test("preserves surrounding content", () => {
+			const content = `# Title\n\nsome text\n${START_MARKER}\nold\n${END_MARKER}\n\n## Footer`;
+			const result = replaceMarkerSection(content, "replaced");
+			expect(result).toContain("# Title");
+			expect(result).toContain("## Footer");
+			expect(result).toContain("replaced");
+			expect(result).not.toContain("old");
+		});
+
+		test("returns null when no markers present", () => {
+			expect(replaceMarkerSection("no markers here", "new")).toBeNull();
+		});
+
+		test("returns null when only start marker present", () => {
+			expect(replaceMarkerSection(`${START_MARKER}\nstuff`, "new")).toBeNull();
+		});
+	});
+});

package/src/markers.ts

@@ -0,0 +1,19 @@
+export const START_MARKER = "<!-- seeds:start -->";
+export const END_MARKER = "<!-- seeds:end -->";
+
+export function hasMarkerSection(content: string): boolean {
+	return content.includes(START_MARKER) && content.includes(END_MARKER);
+}
+
+export function replaceMarkerSection(content: string, newSection: string): string | null {
+	const startIdx = content.indexOf(START_MARKER);
+	const endIdx = content.indexOf(END_MARKER);
+	if (startIdx === -1 || endIdx === -1) return null;
+	const before = content.slice(0, startIdx);
+	const after = content.slice(endIdx + END_MARKER.length);
+	return before + wrapInMarkers(newSection) + after;
+}
+
+export function wrapInMarkers(section: string): string {
+	return `${START_MARKER}\n${section}\n${END_MARKER}`;
+}

package/src/output.ts

@@ -0,0 +1,63 @@
+import type { Issue } from "./types.ts";
+import { PRIORITY_LABELS } from "./types.ts";
+
+const useColor = !process.env.NO_COLOR && process.stdout.isTTY;
+
+export const c = {
+	reset: useColor ? "\x1b[0m" : "",
+	bold: useColor ? "\x1b[1m" : "",
+	dim: useColor ? "\x1b[2m" : "",
+	red: useColor ? "\x1b[31m" : "",
+	green: useColor ? "\x1b[32m" : "",
+	yellow: useColor ? "\x1b[33m" : "",
+	blue: useColor ? "\x1b[34m" : "",
+	cyan: useColor ? "\x1b[36m" : "",
+	magenta: useColor ? "\x1b[35m" : "",
+	gray: useColor ? "\x1b[90m" : "",
+};
+
+export function outputJson(data: unknown): void {
+	console.log(JSON.stringify(data, null, 2));
+}
+
+export function printSuccess(msg: string): void {
+	console.log(`${c.green}✓${c.reset} ${msg}`);
+}
+
+export function printError(msg: string): void {
+	console.error(`${c.red}✗${c.reset} ${msg}`);
+}
+
+export function printIssueOneLine(issue: Issue): void {
+	const statusIcon =
+		issue.status === "closed"
+			? `${c.gray}●${c.reset}`
+			: issue.status === "in_progress"
+				? `${c.cyan}◐${c.reset}`
+				: `${c.green}○${c.reset}`;
+	const priorityLabel = PRIORITY_LABELS[issue.priority] ?? String(issue.priority);
+	const assignee = issue.assignee ? ` · ${c.dim}@${issue.assignee}${c.reset}` : "";
+	const blocked = (issue.blockedBy?.length ?? 0) > 0 ? ` ${c.yellow}[blocked]${c.reset}` : "";
+	console.log(
+		`${statusIcon} ${c.bold}${issue.id}${c.reset} · ${issue.title}   ${c.gray}[${priorityLabel} · ${issue.type}]${c.reset}${assignee}${blocked}`,
+	);
+}
+
+export function printIssueFull(issue: Issue): void {
+	const statusColor =
+		issue.status === "closed" ? c.gray : issue.status === "in_progress" ? c.cyan : c.green;
+	const priorityLabel = PRIORITY_LABELS[issue.priority] ?? String(issue.priority);
+
+	console.log(`${c.bold}${issue.id}${c.reset}  ${statusColor}${issue.status}${c.reset}`);
+	console.log(`Title:    ${issue.title}`);
+	console.log(`Type:     ${issue.type}   Priority: ${priorityLabel}`);
+	if (issue.assignee) console.log(`Assignee: ${issue.assignee}`);
+	if (issue.description) console.log(`\n${issue.description}`);
+	if (issue.blockedBy?.length) console.log(`Blocked by: ${issue.blockedBy.join(", ")}`);
+	if (issue.blocks?.length) console.log(`Blocks:     ${issue.blocks.join(", ")}`);
+	if (issue.convoy) console.log(`Convoy:   ${issue.convoy}`);
+	if (issue.closeReason) console.log(`Reason:   ${issue.closeReason}`);
+	console.log(`Created:  ${issue.createdAt}`);
+	console.log(`Updated:  ${issue.updatedAt}`);
+	if (issue.closedAt) console.log(`Closed:   ${issue.closedAt}`);
+}

package/src/store.test.ts

@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { appendIssue, readIssues, withLock, writeIssues } from "./store";
+import type { Issue } from "./types";
+
+function makeIssue(overrides: Partial<Issue> = {}): Issue {
+	const now = new Date().toISOString();
+	return {
+		id: "test-a1b2",
+		title: "Test issue",
+		status: "open",
+		type: "task",
+		priority: 2,
+		createdAt: now,
+		updatedAt: now,
+		...overrides,
+	};
+}
+
+let tmpDir: string;
+let seedsDir: string;
+
+beforeEach(async () => {
+	tmpDir = await mkdtemp(join(tmpdir(), "seeds-store-test-"));
+	seedsDir = join(tmpDir, ".seeds");
+	await Bun.write(join(seedsDir, ".gitignore"), "*.lock\n");
+});
+
+afterEach(async () => {
+	await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("readIssues", () => {
+	test("returns empty array when issues.jsonl does not exist", async () => {
+		const issues = await readIssues(seedsDir);
+		expect(issues).toEqual([]);
+	});
+
+	test("returns empty array for empty file", async () => {
+		await Bun.write(join(seedsDir, "issues.jsonl"), "");
+		const issues = await readIssues(seedsDir);
+		expect(issues).toEqual([]);
+	});
+
+	test("reads single issue", async () => {
+		const issue = makeIssue();
+		await Bun.write(join(seedsDir, "issues.jsonl"), `${JSON.stringify(issue)}\n`);
+		const issues = await readIssues(seedsDir);
+		expect(issues).toHaveLength(1);
+		expect(issues[0]).toEqual(issue);
+	});
+
+	test("reads multiple issues", async () => {
+		const issue1 = makeIssue({ id: "test-a1b2", title: "First" });
+		const issue2 = makeIssue({ id: "test-c3d4", title: "Second" });
+		const content = [JSON.stringify(issue1), JSON.stringify(issue2), ""].join("\n");
+		await Bun.write(join(seedsDir, "issues.jsonl"), content);
+		const issues = await readIssues(seedsDir);
+		expect(issues).toHaveLength(2);
+		expect(issues[0]?.id).toBe("test-a1b2");
+		expect(issues[1]?.id).toBe("test-c3d4");
+	});
+
+	test("deduplicates by id — last occurrence wins", async () => {
+		const original = makeIssue({ id: "test-a1b2", title: "Original" });
+		const updated = makeIssue({ id: "test-a1b2", title: "Updated" });
+		const content = [JSON.stringify(original), JSON.stringify(updated), ""].join("\n");
+		await Bun.write(join(seedsDir, "issues.jsonl"), content);
+		const issues = await readIssues(seedsDir);
+		expect(issues).toHaveLength(1);
+		expect(issues[0]?.title).toBe("Updated");
+	});
+
+	test("skips blank lines", async () => {
+		const issue = makeIssue();
+		const content = `\n${JSON.stringify(issue)}\n\n`;
+		await Bun.write(join(seedsDir, "issues.jsonl"), content);
+		const issues = await readIssues(seedsDir);
+		expect(issues).toHaveLength(1);
+	});
+});
+
+describe("appendIssue", () => {
+	test("creates issues.jsonl if it does not exist", async () => {
+		const issue = makeIssue();
+		await appendIssue(seedsDir, issue);
+		const issues = await readIssues(seedsDir);
+		expect(issues).toHaveLength(1);
+		expect(issues[0]).toEqual(issue);
+	});
+
+	test("appends to existing file", async () => {
+		const issue1 = makeIssue({ id: "test-a1b2" });
+		const issue2 = makeIssue({ id: "test-c3d4" });
+		await appendIssue(seedsDir, issue1);
+		await appendIssue(seedsDir, issue2);
+		const issues = await readIssues(seedsDir);
+		expect(issues).toHaveLength(2);
+	});
+
+	test("each appended issue is on its own line", async () => {
+		const issue = makeIssue();
+		await appendIssue(seedsDir, issue);
+		const content = await Bun.file(join(seedsDir, "issues.jsonl")).text();
+		const lines = content.split("\n").filter((l) => l.trim() !== "");
+		expect(lines).toHaveLength(1);
+		expect(JSON.parse(lines[0] ?? "{}")).toEqual(issue);
+	});
+});
+
+describe("writeIssues", () => {
+	test("writes issues atomically (overwrites file)", async () => {
+		const original = makeIssue({ id: "test-a1b2", title: "Original" });
+		await appendIssue(seedsDir, original);
+
+		const updated = makeIssue({ id: "test-a1b2", title: "Updated" });
+		await writeIssues(seedsDir, [updated]);
+
+		const issues = await readIssues(seedsDir);
+		expect(issues).toHaveLength(1);
+		expect(issues[0]?.title).toBe("Updated");
+	});
+
+	test("writes empty array as empty file", async () => {
+		const issue = makeIssue();
+		await appendIssue(seedsDir, issue);
+		await writeIssues(seedsDir, []);
+		const issues = await readIssues(seedsDir);
+		expect(issues).toHaveLength(0);
+	});
+
+	test("each issue serialized to its own line", async () => {
+		const issues = [makeIssue({ id: "test-a1b2" }), makeIssue({ id: "test-c3d4" })];
+		await writeIssues(seedsDir, issues);
+		const content = await Bun.file(join(seedsDir, "issues.jsonl")).text();
+		const lines = content.split("\n").filter((l) => l.trim() !== "");
+		expect(lines).toHaveLength(2);
+	});
+});
+
+describe("withLock", () => {
+	test("executes function and returns result", async () => {
+		const result = await withLock(seedsDir, async () => 42);
+		expect(result).toBe(42);
+	});
+
+	test("serializes concurrent operations", async () => {
+		// Run multiple concurrent withLock calls and verify they all succeed
+		let counter = 0;
+		await Promise.all(
+			Array.from({ length: 5 }, () =>
+				withLock(seedsDir, async () => {
+					counter++;
+				}),
+			),
+		);
+		expect(counter).toBe(5);
+	});
+
+	test("releases lock even if function throws", async () => {
+		await expect(
+			withLock(seedsDir, async () => {
+				throw new Error("intentional error");
+			}),
+		).rejects.toThrow("intentional error");
+
+		// Lock should be released — another withLock should succeed
+		const result = await withLock(seedsDir, async () => "ok");
+		expect(result).toBe("ok");
+	});
+});