@os-eco/overstory-cli 0.6.1

package/src/mulch/client.ts

@@ -0,0 +1,332 @@
+/**
+ * Mulch CLI client.
+ *
+ * Wraps the `mulch` command-line tool for structured expertise operations.
+ * Uses Bun.spawn — zero runtime dependencies.
+ */
+
+import { AgentError } from "../errors.ts";
+import type {
+	MulchCompactResult,
+	MulchDiffResult,
+	MulchDoctorResult,
+	MulchLearnResult,
+	MulchPruneResult,
+	MulchReadyResult,
+	MulchStatus,
+} from "../types.ts";
+
+export interface MulchClient {
+	/** Generate a priming prompt, optionally scoped to specific domains. */
+	prime(
+		domains?: string[],
+		format?: "markdown" | "xml" | "json",
+		options?: {
+			files?: string[];
+			excludeDomain?: string[];
+		},
+	): Promise<string>;
+
+	/** Show domain statistics. */
+	status(): Promise<MulchStatus>;
+
+	/** Record an expertise entry for a domain. */
+	record(
+		domain: string,
+		options: {
+			type: string;
+			name?: string;
+			description?: string;
+			title?: string;
+			rationale?: string;
+			tags?: string[];
+			classification?: string;
+			stdin?: boolean;
+			evidenceBead?: string;
+			outcomeStatus?: "success" | "failure";
+			outcomeDuration?: number;
+			outcomeTestResults?: string;
+			outcomeAgent?: string;
+		},
+	): Promise<void>;
+
+	/** Query expertise records, optionally scoped to a domain. */
+	query(domain?: string): Promise<string>;
+
+	/** Search records across all domains. */
+	search(query: string, options?: { file?: string; sortByScore?: boolean }): Promise<string>;
+
+	/** Show expertise record changes since a git ref. */
+	diff(options?: { since?: string }): Promise<MulchDiffResult>;
+
+	/** Show changed files and suggest domains for recording learnings. */
+	learn(options?: { since?: string }): Promise<MulchLearnResult>;
+
+	/** Remove unused or stale records. */
+	prune(options?: { dryRun?: boolean }): Promise<MulchPruneResult>;
+
+	/** Run health checks on mulch repository. */
+	doctor(options?: { fix?: boolean }): Promise<MulchDoctorResult>;
+
+	/** Show recently added or updated expertise records. */
+	ready(options?: { limit?: number; domain?: string; since?: string }): Promise<MulchReadyResult>;
+
+	/** Compact and optimize domain storage. */
+	compact(
+		domain?: string,
+		options?: {
+			analyze?: boolean;
+			apply?: boolean;
+			auto?: boolean;
+			dryRun?: boolean;
+			minGroup?: number;
+			maxRecords?: number;
+			yes?: boolean;
+			records?: string[];
+		},
+	): Promise<MulchCompactResult>;
+}
+
+/**
+ * Run a shell command and capture its output.
+ */
+async function runCommand(
+	cmd: string[],
+	cwd: string,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	const proc = Bun.spawn(cmd, {
+		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;
+	return { stdout, stderr, exitCode };
+}
+
+/**
+ * Create a MulchClient bound to the given working directory.
+ *
+ * @param cwd - Working directory where mulch commands should run
+ * @returns A MulchClient instance wrapping the mulch CLI
+ */
+export function createMulchClient(cwd: string): MulchClient {
+	async function runMulch(
+		args: string[],
+		context: string,
+	): Promise<{ stdout: string; stderr: string }> {
+		const { stdout, stderr, exitCode } = await runCommand(["mulch", ...args], cwd);
+		if (exitCode !== 0) {
+			throw new AgentError(`mulch ${context} failed (exit ${exitCode}): ${stderr.trim()}`);
+		}
+		return { stdout, stderr };
+	}
+
+	return {
+		async prime(domains, format, options) {
+			const args = ["prime"];
+			if (domains && domains.length > 0) {
+				args.push(...domains);
+			}
+			if (format) {
+				args.push("--format", format);
+			}
+			if (options?.files && options.files.length > 0) {
+				args.push("--files", ...options.files);
+			}
+			if (options?.excludeDomain && options.excludeDomain.length > 0) {
+				args.push("--exclude-domain", ...options.excludeDomain);
+			}
+			const { stdout } = await runMulch(args, "prime");
+			return stdout;
+		},
+
+		async status() {
+			const { stdout } = await runMulch(["status", "--json"], "status");
+			const trimmed = stdout.trim();
+			if (trimmed === "") {
+				return { domains: [] };
+			}
+			try {
+				return JSON.parse(trimmed) as MulchStatus;
+			} catch {
+				throw new AgentError(
+					`Failed to parse JSON output from mulch status: ${trimmed.slice(0, 200)}`,
+				);
+			}
+		},
+
+		async record(domain, options) {
+			const args = ["record", domain, "--type", options.type];
+			if (options.name) {
+				args.push("--name", options.name);
+			}
+			if (options.description) {
+				args.push("--description", options.description);
+			}
+			if (options.title) {
+				args.push("--title", options.title);
+			}
+			if (options.rationale) {
+				args.push("--rationale", options.rationale);
+			}
+			if (options.tags && options.tags.length > 0) {
+				args.push("--tags", options.tags.join(","));
+			}
+			if (options.classification) {
+				args.push("--classification", options.classification);
+			}
+			if (options.stdin) {
+				args.push("--stdin");
+			}
+			if (options.evidenceBead) {
+				args.push("--evidence-bead", options.evidenceBead);
+			}
+			if (options.outcomeStatus) {
+				args.push("--outcome-status", options.outcomeStatus);
+			}
+			if (options.outcomeDuration !== undefined) {
+				args.push("--outcome-duration", String(options.outcomeDuration));
+			}
+			if (options.outcomeTestResults) {
+				args.push("--outcome-test-results", options.outcomeTestResults);
+			}
+			if (options.outcomeAgent) {
+				args.push("--outcome-agent", options.outcomeAgent);
+			}
+			await runMulch(args, `record ${domain}`);
+		},
+
+		async query(domain) {
+			const args = ["query"];
+			if (domain) {
+				args.push(domain);
+			}
+			const { stdout } = await runMulch(args, "query");
+			return stdout;
+		},
+
+		async search(query, options) {
+			const args = ["search", query];
+			if (options?.file) args.push("--file", options.file);
+			if (options?.sortByScore) args.push("--sort-by-score");
+			const { stdout } = await runMulch(args, "search");
+			return stdout;
+		},
+
+		async diff(options) {
+			const args = ["diff", "--json"];
+			if (options?.since) {
+				args.push("--since", options.since);
+			}
+			const { stdout } = await runMulch(args, "diff");
+			const trimmed = stdout.trim();
+			try {
+				return JSON.parse(trimmed) as MulchDiffResult;
+			} catch {
+				throw new AgentError(`Failed to parse JSON from mulch diff: ${trimmed.slice(0, 200)}`);
+			}
+		},
+
+		async learn(options) {
+			const args = ["learn", "--json"];
+			if (options?.since) {
+				args.push("--since", options.since);
+			}
+			const { stdout } = await runMulch(args, "learn");
+			const trimmed = stdout.trim();
+			try {
+				return JSON.parse(trimmed) as MulchLearnResult;
+			} catch {
+				throw new AgentError(`Failed to parse JSON from mulch learn: ${trimmed.slice(0, 200)}`);
+			}
+		},
+
+		async prune(options) {
+			const args = ["prune", "--json"];
+			if (options?.dryRun) {
+				args.push("--dry-run");
+			}
+			const { stdout } = await runMulch(args, "prune");
+			const trimmed = stdout.trim();
+			try {
+				return JSON.parse(trimmed) as MulchPruneResult;
+			} catch {
+				throw new AgentError(`Failed to parse JSON from mulch prune: ${trimmed.slice(0, 200)}`);
+			}
+		},
+
+		async doctor(options) {
+			const args = ["doctor", "--json"];
+			if (options?.fix) {
+				args.push("--fix");
+			}
+			const { stdout } = await runMulch(args, "doctor");
+			const trimmed = stdout.trim();
+			try {
+				return JSON.parse(trimmed) as MulchDoctorResult;
+			} catch {
+				throw new AgentError(`Failed to parse JSON from mulch doctor: ${trimmed.slice(0, 200)}`);
+			}
+		},
+
+		async ready(options) {
+			const args = ["ready", "--json"];
+			if (options?.limit !== undefined) {
+				args.push("--limit", String(options.limit));
+			}
+			if (options?.domain) {
+				args.push("--domain", options.domain);
+			}
+			if (options?.since) {
+				args.push("--since", options.since);
+			}
+			const { stdout } = await runMulch(args, "ready");
+			const trimmed = stdout.trim();
+			try {
+				return JSON.parse(trimmed) as MulchReadyResult;
+			} catch {
+				throw new AgentError(`Failed to parse JSON from mulch ready: ${trimmed.slice(0, 200)}`);
+			}
+		},
+
+		async compact(domain, options) {
+			const args = ["compact", "--json"];
+			if (domain) {
+				args.push(domain);
+			}
+			if (options?.analyze) {
+				args.push("--analyze");
+			}
+			if (options?.apply) {
+				args.push("--apply");
+			}
+			if (options?.auto) {
+				args.push("--auto");
+			}
+			if (options?.dryRun) {
+				args.push("--dry-run");
+			}
+			if (options?.minGroup !== undefined) {
+				args.push("--min-group", String(options.minGroup));
+			}
+			if (options?.maxRecords !== undefined) {
+				args.push("--max-records", String(options.maxRecords));
+			}
+			if (options?.yes) {
+				args.push("--yes");
+			}
+			if (options?.records && options.records.length > 0) {
+				args.push("--records", options.records.join(","));
+			}
+			const { stdout } = await runMulch(args, domain ? `compact ${domain}` : "compact");
+			const trimmed = stdout.trim();
+			try {
+				return JSON.parse(trimmed) as MulchCompactResult;
+			} catch {
+				throw new AgentError(`Failed to parse JSON from mulch compact: ${trimmed.slice(0, 200)}`);
+			}
+		},
+	};
+}

package/src/sessions/compat.test.ts

@@ -0,0 +1,280 @@
+/**
+ * Tests for the session compat shim (JSON -> SQLite migration).
+ *
+ * Uses real filesystem and bun:sqlite. No mocks.
+ * Tests file-based migration behavior, so temp files are required (not :memory:).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openSessionStore } from "./compat.ts";
+
+let tempDir: string;
+let overstoryDir: string;
+
+beforeEach(async () => {
+	tempDir = await mkdtemp(join(tmpdir(), "overstory-compat-test-"));
+	overstoryDir = join(tempDir, ".overstory");
+	const { mkdir } = await import("node:fs/promises");
+	await mkdir(overstoryDir, { recursive: true });
+});
+
+afterEach(async () => {
+	await rm(tempDir, { recursive: true, force: true });
+});
+
+/** Create a sessions.json with the given entries. */
+async function writeSessionsJson(sessions: Record<string, unknown>[]): Promise<void> {
+	const jsonPath = join(overstoryDir, "sessions.json");
+	await writeFile(jsonPath, `${JSON.stringify(sessions, null, "\t")}\n`, "utf-8");
+}
+
+/** A valid session object as it would appear in sessions.json. */
+function makeJsonSession(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+	return {
+		id: "session-001-test-agent",
+		agentName: "test-agent",
+		capability: "builder",
+		worktreePath: "/tmp/worktrees/test-agent",
+		branchName: "overstory/test-agent/task-1",
+		beadId: "task-1",
+		tmuxSession: "overstory-test-agent",
+		state: "working",
+		pid: 12345,
+		parentAgent: null,
+		depth: 0,
+		startedAt: "2026-01-15T10:00:00.000Z",
+		lastActivity: "2026-01-15T10:05:00.000Z",
+		escalationLevel: 0,
+		stalledSince: null,
+		...overrides,
+	};
+}
+
+// === Migration from sessions.json ===
+
+describe("openSessionStore", () => {
+	test("creates empty DB when neither sessions.json nor sessions.db exist", () => {
+		const { store, migrated } = openSessionStore(overstoryDir);
+
+		expect(migrated).toBe(false);
+		expect(store.getAll()).toEqual([]);
+		store.close();
+	});
+
+	test("imports sessions from sessions.json when sessions.db does not exist", async () => {
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "agent-a", id: "s-a" }),
+			makeJsonSession({ agentName: "agent-b", id: "s-b", state: "completed" }),
+		]);
+
+		const { store, migrated } = openSessionStore(overstoryDir);
+
+		expect(migrated).toBe(true);
+		const all = store.getAll();
+		expect(all).toHaveLength(2);
+
+		const agentA = store.getByName("agent-a");
+		expect(agentA).not.toBeNull();
+		expect(agentA?.id).toBe("s-a");
+		expect(agentA?.state).toBe("working");
+
+		const agentB = store.getByName("agent-b");
+		expect(agentB).not.toBeNull();
+		expect(agentB?.state).toBe("completed");
+
+		store.close();
+	});
+
+	test("migration adds runId=null when sessions.json entries lack runId", async () => {
+		// Write a session WITHOUT runId (old format)
+		const oldFormatSession = makeJsonSession();
+		(oldFormatSession as Record<string, unknown>).runId = undefined;
+
+		await writeSessionsJson([oldFormatSession]);
+
+		const { store, migrated } = openSessionStore(overstoryDir);
+
+		expect(migrated).toBe(true);
+		const session = store.getByName("test-agent");
+		expect(session).not.toBeNull();
+		expect(session?.runId).toBeNull();
+
+		store.close();
+	});
+
+	test("does not re-migrate when sessions.db already exists", async () => {
+		// First call: create the DB with migration
+		await writeSessionsJson([makeJsonSession({ agentName: "original", id: "s-1" })]);
+
+		const { store: store1, migrated: migrated1 } = openSessionStore(overstoryDir);
+		expect(migrated1).toBe(true);
+		store1.close();
+
+		// Modify sessions.json to add a new entry
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "original", id: "s-1" }),
+			makeJsonSession({ agentName: "new-agent", id: "s-2" }),
+		]);
+
+		// Second call: DB exists, so no migration
+		const { store: store2, migrated: migrated2 } = openSessionStore(overstoryDir);
+		expect(migrated2).toBe(false);
+
+		// Should still have only the original session from the first migration
+		const all = store2.getAll();
+		expect(all).toHaveLength(1);
+		expect(all[0]?.agentName).toBe("original");
+
+		store2.close();
+	});
+
+	test("imports from sessions.json when sessions.db exists but is empty", async () => {
+		// Simulate the scenario where sessions.db was created (e.g., by init) but
+		// no sessions were ever written to it, while sessions.json has records from
+		// a previous coordinator start that used the old code path (overstory-036f).
+		const { store: emptyStore } = openSessionStore(overstoryDir);
+		expect(emptyStore.getAll()).toHaveLength(0);
+		emptyStore.close();
+
+		// Now write records to sessions.json (simulating old code path)
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "orphaned-coordinator", id: "s-orphan", state: "booting" }),
+		]);
+
+		// Re-open: DB exists but is empty, so JSON records should be imported
+		const { store: store2, migrated } = openSessionStore(overstoryDir);
+		expect(migrated).toBe(true);
+
+		const all = store2.getAll();
+		expect(all).toHaveLength(1);
+		expect(all[0]?.agentName).toBe("orphaned-coordinator");
+		expect(all[0]?.state).toBe("booting");
+		store2.close();
+	});
+
+	test("handles empty sessions.json (no migration needed)", async () => {
+		await writeSessionsJson([]);
+
+		const { store, migrated } = openSessionStore(overstoryDir);
+
+		expect(migrated).toBe(false);
+		expect(store.getAll()).toEqual([]);
+		store.close();
+	});
+
+	test("handles malformed sessions.json gracefully", async () => {
+		const jsonPath = join(overstoryDir, "sessions.json");
+		await writeFile(jsonPath, "this is not json", "utf-8");
+
+		const { store, migrated } = openSessionStore(overstoryDir);
+
+		expect(migrated).toBe(false);
+		expect(store.getAll()).toEqual([]);
+		store.close();
+	});
+
+	test("handles sessions.json with non-array content gracefully", async () => {
+		const jsonPath = join(overstoryDir, "sessions.json");
+		await writeFile(jsonPath, '{"not": "an array"}', "utf-8");
+
+		const { store, migrated } = openSessionStore(overstoryDir);
+
+		expect(migrated).toBe(false);
+		expect(store.getAll()).toEqual([]);
+		store.close();
+	});
+});
+
+// === Data integrity after migration ===
+
+describe("data integrity", () => {
+	test("all fields from sessions.json are preserved in SQLite", async () => {
+		const fullSession = makeJsonSession({
+			id: "session-full",
+			agentName: "full-agent",
+			capability: "scout",
+			worktreePath: "/tmp/worktrees/full-agent",
+			branchName: "overstory/full-agent/task-42",
+			beadId: "task-42",
+			tmuxSession: "overstory-full-agent",
+			state: "stalled",
+			pid: 99999,
+			parentAgent: "lead-agent",
+			depth: 2,
+			startedAt: "2026-02-01T08:00:00.000Z",
+			lastActivity: "2026-02-01T09:00:00.000Z",
+			escalationLevel: 3,
+			stalledSince: "2026-02-01T08:50:00.000Z",
+		});
+
+		await writeSessionsJson([fullSession]);
+
+		const { store } = openSessionStore(overstoryDir);
+		const result = store.getByName("full-agent");
+
+		expect(result).not.toBeNull();
+		expect(result?.id).toBe("session-full");
+		expect(result?.agentName).toBe("full-agent");
+		expect(result?.capability).toBe("scout");
+		expect(result?.worktreePath).toBe("/tmp/worktrees/full-agent");
+		expect(result?.branchName).toBe("overstory/full-agent/task-42");
+		expect(result?.beadId).toBe("task-42");
+		expect(result?.tmuxSession).toBe("overstory-full-agent");
+		expect(result?.state).toBe("stalled");
+		expect(result?.pid).toBe(99999);
+		expect(result?.parentAgent).toBe("lead-agent");
+		expect(result?.depth).toBe(2);
+		expect(result?.runId).toBeNull(); // Not in old JSON format
+		expect(result?.startedAt).toBe("2026-02-01T08:00:00.000Z");
+		expect(result?.lastActivity).toBe("2026-02-01T09:00:00.000Z");
+		expect(result?.escalationLevel).toBe(3);
+		expect(result?.stalledSince).toBe("2026-02-01T08:50:00.000Z");
+
+		store.close();
+	});
+
+	test("migrated store supports all SessionStore operations", async () => {
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "agent-a", id: "s-a", state: "working" }),
+			makeJsonSession({ agentName: "agent-b", id: "s-b", state: "completed" }),
+		]);
+
+		const { store } = openSessionStore(overstoryDir);
+
+		// getActive should return only "working" sessions
+		const active = store.getActive();
+		expect(active).toHaveLength(1);
+		expect(active[0]?.agentName).toBe("agent-a");
+
+		// updateState should work on migrated data
+		store.updateState("agent-a", "completed");
+		expect(store.getByName("agent-a")?.state).toBe("completed");
+
+		// remove should work on migrated data
+		store.remove("agent-b");
+		expect(store.getByName("agent-b")).toBeNull();
+
+		store.close();
+	});
+
+	test("multiple sessions with same agent name in JSON: last one wins", async () => {
+		// This edge case shouldn't happen in practice, but test defensive behavior
+		await writeSessionsJson([
+			makeJsonSession({ agentName: "dupe", id: "s-1", state: "booting" }),
+			makeJsonSession({ agentName: "dupe", id: "s-2", state: "working" }),
+		]);
+
+		const { store } = openSessionStore(overstoryDir);
+
+		const all = store.getAll();
+		expect(all).toHaveLength(1);
+		// Last upsert wins (s-2)
+		expect(all[0]?.id).toBe("s-2");
+		expect(all[0]?.state).toBe("working");
+
+		store.close();
+	});
+});