@os-eco/seeds-cli 0.2.0

package/README.md

@@ -0,0 +1,226 @@
+# Seeds
+
+Git-native issue tracker for AI agent workflows. Zero dependencies, JSONL storage, Bun runtime.
+
+Replaces [beads](https://github.com/steveyegge/beads) in the [overstory](https://github.com/jayminwest/overstory)/[mulch](https://github.com/jayminwest/mulch) ecosystem. No Dolt, no daemon, no binary DB files. **The JSONL file IS the database.**
+
+## Why
+
+Beads works but carries baggage overstory doesn't need:
+
+| Problem | Beads | Seeds |
+|---------|-------|-------|
+| Storage | 2.8MB binary `beads.db` (can't diff/merge) | JSONL (diffable, mergeable) |
+| Sync | 286 export-state tracking files | No sync — file IS the DB |
+| Concurrency | `beads.db` lock contention | Advisory locks + atomic writes |
+| Dependencies | Dolt embedded | Zero runtime deps |
+
+## Installation
+
+```bash
+git clone https://github.com/jayminwest/seeds
+cd seeds
+bun install
+bun link   # Makes 'sd' available globally
+```
+
+Requires [Bun](https://bun.sh) v1.0+.
+
+## Quick Start
+
+```bash
+# Initialize in your project
+sd init
+
+# Create an issue
+sd create --title "Add retry logic to mail client" --type task --priority 1
+
+# List open issues
+sd list
+
+# Find work (open, unblocked)
+sd ready
+
+# Claim and complete
+sd update seeds-a1b2 --status in_progress
+sd close seeds-a1b2 --reason "Implemented with exponential backoff"
+
+# Commit .seeds/ changes to git
+sd sync
+```
+
+## CLI Reference
+
+Every command supports `--json` for structured output. ANSI colors respect `NO_COLOR`.
+
+### Issue Commands
+
+```
+sd init                                Initialize .seeds/ in current directory
+
+sd create                              Create a new issue
+  --title <text>       (required)
+  --type <type>        task|bug|feature|epic  (default: task)
+  --priority <n>       0-4 or P0-P4          (default: 2)
+  --description <text>
+  --assignee <name>
+
+sd show <id>                           Show issue details
+
+sd list                                List issues with filters
+  --status <status>    open|in_progress|closed
+  --type <type>        task|bug|feature|epic
+  --assignee <name>
+  --limit <n>          Max results (default: 50)
+
+sd ready                               Open issues with no unresolved blockers
+
+sd update <id>                         Update issue fields
+  --status --title --priority --assignee --description
+
+sd close <id> [<id2> ...]              Close one or more issues
+  --reason <text>      Closure summary
+
+sd dep add <issue> <depends-on>        Add dependency
+sd dep remove <issue> <depends-on>     Remove dependency
+sd dep list <issue>                    Show deps for an issue
+
+sd blocked                             Show all blocked issues
+
+sd stats                               Project statistics
+
+sd sync                                Stage and commit .seeds/ changes
+  --status             Check without committing
+```
+
+### Template (Molecule) Commands
+
+```
+sd tpl create --name <text>            Create a template
+sd tpl step add <id> --title <text>    Add step (supports {prefix} interpolation)
+sd tpl list                            List all templates
+sd tpl show <id>                       Show template with steps
+sd tpl pour <id> --prefix <text>       Instantiate template into issues
+sd tpl status <id>                     Show convoy completion status
+```
+
+### Project Health
+
+```
+sd doctor                              Check project health and data integrity
+  --fix                Fix auto-fixable issues
+```
+
+### Agent Integration
+
+```
+sd prime                               Output AI agent context (PRIME.md or built-in)
+  --compact            Condensed quick-reference output
+sd onboard                             Add seeds section to CLAUDE.md / AGENTS.md
+```
+
+### Migration
+
+```bash
+sd migrate-from-beads    # Import .beads/issues.jsonl → .seeds/issues.jsonl
+```
+
+## Priority Scale
+
+| Value | Label    | Use |
+|-------|----------|-----|
+| 0     | Critical | System-breaking, drop everything |
+| 1     | High     | Core functionality |
+| 2     | Medium   | Default — important but not urgent |
+| 3     | Low      | Nice-to-have |
+| 4     | Backlog  | Future consideration |
+
+## On-Disk Format
+
+```
+.seeds/
+  config.yaml          # Project config: project name, version
+  issues.jsonl         # All issues, one JSON object per line
+  templates.jsonl      # Template definitions
+  .gitignore           # Ignores *.lock files
+```
+
+Add to your `.gitattributes` (done automatically by `sd init`):
+
+```
+.seeds/issues.jsonl merge=union
+.seeds/templates.jsonl merge=union
+```
+
+The `merge=union` strategy handles parallel agent branch merges. Seeds deduplicates by ID on read (last occurrence wins), so conflicts resolve automatically.
+
+## JSON Output
+
+Success:
+```json
+{ "success": true, "command": "create", "id": "myproject-a1b2" }
+```
+
+Error:
+```json
+{ "success": false, "command": "create", "error": "Title is required" }
+```
+
+## Concurrency
+
+Seeds is safe for concurrent multi-agent use:
+
+- **Advisory file locks** — `O_CREAT | O_EXCL`, 30s stale threshold, 50ms retry, 5s timeout
+- **Atomic writes** — temp file + rename under lock
+- **Dedup on read** — last occurrence wins after `merge=union` git merges
+
+## Integration with Overstory
+
+Overstory wraps `sd` via `Bun.spawn(["sd", ...])` with `--json` parsing, identical to how it wraps `bd`:
+
+| BeadsClient method | sd command |
+|--------------------|------------|
+| `ready()` | `sd ready --json` |
+| `show(id)` | `sd show <id> --json` |
+| `create(title, opts)` | `sd create --title "..." --json` |
+| `claim(id)` | `sd update <id> --status=in_progress --json` |
+| `close(id, reason)` | `sd close <id> --reason "..." --json` |
+
+## Development
+
+```bash
+bun test                      # Run all tests
+bun test src/store.test.ts    # Single test file
+bun run lint                  # Biome check
+bun run typecheck             # tsc --noEmit
+
+# Quality gates (run before committing)
+bun test && bun run lint && bun run typecheck
+```
+
+## Version Bump
+
+```bash
+bun run version:bump patch    # 0.1.0 → 0.1.1
+bun run version:bump minor    # 0.1.0 → 0.2.0
+bun run version:bump major    # 0.1.0 → 1.0.0
+```
+
+Updates both `package.json` and `src/index.ts` atomically.
+
+## Tech Stack
+
+| Concern | Choice |
+|---------|--------|
+| Runtime | Bun (runs TS directly, no build) |
+| Language | TypeScript strict (`noUncheckedIndexedAccess`, no `any`) |
+| Storage | JSONL (git-native) |
+| Config | YAML (minimal built-in parser) |
+| Locking | Advisory file locks |
+| Formatting | Biome (tabs, 100 char width) |
+| Testing | `bun test` with real I/O, temp dirs |
+| Dependencies | Zero runtime |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@os-eco/seeds-cli",
+	"version": "0.2.0",
+	"description": "Git-native issue tracker for AI agent workflows",
+	"type": "module",
+	"bin": {
+		"sd": "./src/index.ts"
+	},
+	"main": "src/index.ts",
+	"files": ["src"],
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"bun": ">=1.0.0"
+	},
+	"keywords": [
+		"issue-tracking",
+		"git",
+		"ai",
+		"agents",
+		"cli",
+		"developer-tools"
+	],
+	"author": "Jaymin West",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/jayminwest/seeds.git"
+	},
+	"scripts": {
+		"test": "bun test",
+		"lint": "bunx biome check .",
+		"typecheck": "tsc --noEmit",
+		"version:bump": "bun run scripts/version-bump.ts"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.0",
+		"@types/bun": "latest",
+		"typescript": "^5.0.0"
+	}
+}

package/src/commands/blocked.ts

@@ -0,0 +1,31 @@
+import { findSeedsDir } from "../config.ts";
+import { outputJson, printIssueOneLine } from "../output.ts";
+import { readIssues } from "../store.ts";
+import type { Issue } from "../types.ts";
+
+export async function run(args: string[], seedsDir?: string): Promise<void> {
+	const jsonMode = args.includes("--json");
+	const dir = seedsDir ?? (await findSeedsDir());
+	const issues = await readIssues(dir);
+
+	const closedIds = new Set(issues.filter((i: Issue) => i.status === "closed").map((i) => i.id));
+
+	const blocked = issues.filter((i: Issue) => {
+		if (i.status === "closed") return false;
+		const blockers = i.blockedBy ?? [];
+		return blockers.some((bid) => !closedIds.has(bid));
+	});
+
+	if (jsonMode) {
+		outputJson({ success: true, command: "blocked", issues: blocked, count: blocked.length });
+	} else {
+		if (blocked.length === 0) {
+			console.log("No blocked issues.");
+			return;
+		}
+		for (const issue of blocked) {
+			printIssueOneLine(issue);
+		}
+		console.log(`\n${blocked.length} blocked issue(s)`);
+	}
+}

package/src/commands/close.ts

@@ -0,0 +1,80 @@
+import { findSeedsDir } from "../config.ts";
+import { outputJson, printSuccess } from "../output.ts";
+import { issuesPath, readIssues, withLock, writeIssues } from "../store.ts";
+import type { Issue } from "../types.ts";
+
+function parseArgs(args: string[]) {
+	const flags: Record<string, string | boolean> = {};
+	const positional: string[] = [];
+	let i = 0;
+	while (i < args.length) {
+		const arg = args[i];
+		if (!arg) {
+			i++;
+			continue;
+		}
+		if (arg.startsWith("--")) {
+			const key = arg.slice(2);
+			const eqIdx = key.indexOf("=");
+			if (eqIdx !== -1) {
+				flags[key.slice(0, eqIdx)] = key.slice(eqIdx + 1);
+				i++;
+			} else {
+				const next = args[i + 1];
+				if (next !== undefined && !next.startsWith("--")) {
+					flags[key] = next;
+					i += 2;
+				} else {
+					flags[key] = true;
+					i++;
+				}
+			}
+		} else {
+			positional.push(arg);
+			i++;
+		}
+	}
+	return { flags, positional };
+}
+
+export async function run(args: string[], seedsDir?: string): Promise<void> {
+	const jsonMode = args.includes("--json");
+	const { flags, positional } = parseArgs(args);
+
+	if (positional.length === 0) throw new Error("Usage: sd close <id> [ids...] [--reason text]");
+
+	const reason = typeof flags.reason === "string" ? flags.reason : undefined;
+	const ids = positional;
+
+	const dir = seedsDir ?? (await findSeedsDir());
+	const closed: string[] = [];
+
+	await withLock(issuesPath(dir), async () => {
+		const issues = await readIssues(dir);
+		const now = new Date().toISOString();
+
+		for (const id of ids) {
+			const idx = issues.findIndex((i) => i.id === id);
+			if (idx === -1) throw new Error(`Issue not found: ${id}`);
+			const issue = issues[idx]!;
+			const updated: Issue = {
+				...issue,
+				status: "closed",
+				closedAt: now,
+				updatedAt: now,
+				...(reason ? { closeReason: reason } : {}),
+			};
+			issues[idx] = updated;
+			closed.push(id);
+		}
+		await writeIssues(dir, issues);
+	});
+
+	if (jsonMode) {
+		outputJson({ success: true, command: "close", closed });
+	} else {
+		for (const id of closed) {
+			printSuccess(`Closed ${id}${reason ? ` — ${reason}` : ""}`);
+		}
+	}
+}