@os-eco/overstory-cli 0.8.7 → 0.9.2

package/src/canopy/client.ts

@@ -0,0 +1,179 @@
+/**
+ * Canopy CLI client.
+ *
+ * Wraps the `cn` command-line tool for prompt management operations.
+ * All methods use Bun.spawn to invoke the CLI directly.
+ */
+
+import { AgentError } from "../errors.ts";
+import type {
+	CanopyListResult,
+	CanopyRenderResult,
+	CanopyShowResult,
+	CanopyValidateResult,
+} from "../types.ts";
+
+export interface CanopyClient {
+	/** Render a prompt, resolving inheritance. */
+	render(name: string, options?: { format?: "md" | "json" }): Promise<CanopyRenderResult>;
+
+	/** Validate a prompt (or all prompts) against its schema. */
+	validate(name?: string, options?: { all?: boolean }): Promise<CanopyValidateResult>;
+
+	/** List all prompts. */
+	list(options?: {
+		tag?: string;
+		status?: string;
+		extends?: string;
+		mixin?: string;
+	}): Promise<CanopyListResult>;
+
+	/** Show a prompt record. */
+	show(name: string): Promise<CanopyShowResult>;
+}
+
+/**
+ * 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 CanopyClient bound to the given working directory.
+ *
+ * @param cwd - Working directory where cn commands should run
+ * @returns A CanopyClient instance wrapping the cn CLI
+ */
+export function createCanopyClient(cwd: string): CanopyClient {
+	async function runCanopy(
+		args: string[],
+		context: string,
+	): Promise<{ stdout: string; stderr: string }> {
+		const { stdout, stderr, exitCode } = await runCommand(["cn", ...args], cwd);
+		if (exitCode !== 0) {
+			throw new AgentError(`canopy ${context} failed (exit ${exitCode}): ${stderr.trim()}`);
+		}
+		return { stdout, stderr };
+	}
+
+	return {
+		async render(name, _options) {
+			// Always use --json for structured output; format param reserved for future use
+			const { stdout } = await runCanopy(["render", name, "--json"], `render ${name}`);
+			const trimmed = stdout.trim();
+			try {
+				const raw = JSON.parse(trimmed) as {
+					success: boolean;
+					name: string;
+					version: number;
+					sections: Array<{ name: string; body: string }>;
+				};
+				return {
+					success: raw.success,
+					name: raw.name,
+					version: raw.version,
+					sections: raw.sections,
+				};
+			} catch {
+				throw new AgentError(
+					`Failed to parse JSON from cn render ${name}: ${trimmed.slice(0, 200)}`,
+				);
+			}
+		},
+
+		async validate(name, options) {
+			const args = ["validate"];
+			if (options?.all) {
+				args.push("--all");
+			} else if (name) {
+				args.push(name);
+			}
+			// cn validate does not support --json; parse exit code and stdout/stderr
+			const { stdout, stderr, exitCode } = await runCommand(["cn", ...args], cwd);
+			const output = (stdout + stderr).trim();
+			const errors: string[] = [];
+			if (exitCode !== 0) {
+				// Extract error lines from output (lines containing "error:")
+				for (const line of output.split("\n")) {
+					const trimmedLine = line.trim();
+					if (trimmedLine.includes("error:")) {
+						errors.push(trimmedLine);
+					}
+				}
+				if (errors.length === 0 && output) {
+					errors.push(output);
+				}
+			}
+			return { success: exitCode === 0, errors };
+		},
+
+		async list(options) {
+			const args = ["list", "--json"];
+			if (options?.tag) {
+				args.push("--tag", options.tag);
+			}
+			if (options?.status) {
+				args.push("--status", options.status);
+			}
+			if (options?.extends) {
+				args.push("--extends", options.extends);
+			}
+			if (options?.mixin) {
+				args.push("--mixin", options.mixin);
+			}
+			const { stdout } = await runCanopy(args, "list");
+			const trimmed = stdout.trim();
+			try {
+				const raw = JSON.parse(trimmed) as {
+					success: boolean;
+					prompts: Array<{
+						id: string;
+						name: string;
+						version: number;
+						sections: Array<{ name: string; body: string }>;
+					}>;
+				};
+				return {
+					success: raw.success,
+					prompts: raw.prompts,
+				};
+			} catch {
+				throw new AgentError(`Failed to parse JSON from cn list: ${trimmed.slice(0, 200)}`);
+			}
+		},
+
+		async show(name) {
+			const { stdout } = await runCanopy(["show", name, "--json"], `show ${name}`);
+			const trimmed = stdout.trim();
+			try {
+				const raw = JSON.parse(trimmed) as {
+					success: boolean;
+					prompt: {
+						id: string;
+						name: string;
+						version: number;
+						sections: Array<{ name: string; body: string }>;
+					};
+				};
+				return {
+					success: raw.success,
+					prompt: raw.prompt,
+				};
+			} catch {
+				throw new AgentError(`Failed to parse JSON from cn show ${name}: ${trimmed.slice(0, 200)}`);
+			}
+		},
+	};
+}

package/src/commands/agents.ts

@@ -223,7 +223,7 @@ export function createAgentsCommand(): Command {
 		.description("Find active agents by capability")
 		.option(
 			"--capability <type>",
-			"Filter by capability (builder, scout, reviewer, lead, merger, coordinator, supervisor)",
+			"Filter by capability (builder, scout, reviewer, lead, merger, orchestrator, coordinator, supervisor)",
 		)
 		.option("--all", "Include completed and zombie agents (default: active only)")
 		.option("--json", "Output as JSON")

package/src/commands/clean.test.ts

@@ -792,3 +792,6 @@ describe("--agent", () => {
 		expect(stdoutOutput).toContain("Agent cleaned");
 	});
 });
+
+// fs utility tests (wipeSqliteDb, resetJsonFile, clearDirectory, deleteFile)
+// moved to src/utils/fs.test.ts

package/src/commands/clean.ts

@@ -20,7 +20,6 @@
  */
 
 import { existsSync } from "node:fs";
-import { readdir, rm, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
@@ -30,6 +29,7 @@ import { printHint, printSuccess } from "../logging/color.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, MulchDoctorResult, MulchPruneResult, MulchStatus } from "../types.ts";
+import { clearDirectory, deleteFile, resetJsonFile, wipeSqliteDb } from "../utils/fs.ts";
 import { listWorktrees, removeWorktree } from "../worktree/manager.ts";
 import {
 	isProcessAlive,
@@ -274,63 +274,6 @@ async function deleteOrphanedBranches(root: string): Promise<number> {
 	return deleted;
 }
 
-/**
- * Delete a SQLite database file and its WAL/SHM companions.
- */
-async function wipeSqliteDb(dbPath: string): Promise<boolean> {
-	const extensions = ["", "-wal", "-shm"];
-	let wiped = false;
-	for (const ext of extensions) {
-		try {
-			await unlink(`${dbPath}${ext}`);
-			if (ext === "") wiped = true;
-		} catch {
-			// File may not exist
-		}
-	}
-	return wiped;
-}
-
-/**
- * Reset a JSON file to an empty array.
- */
-async function resetJsonFile(path: string): Promise<boolean> {
-	const file = Bun.file(path);
-	if (await file.exists()) {
-		await Bun.write(path, "[]\n");
-		return true;
-	}
-	return false;
-}
-
-/**
- * Clear all entries inside a directory but keep the directory itself.
- */
-async function clearDirectory(dirPath: string): Promise<boolean> {
-	try {
-		const entries = await readdir(dirPath);
-		for (const entry of entries) {
-			await rm(join(dirPath, entry), { recursive: true, force: true });
-		}
-		return entries.length > 0;
-	} catch {
-		// Directory may not exist
-		return false;
-	}
-}
-
-/**
- * Delete a single file if it exists.
- */
-async function deleteFile(path: string): Promise<boolean> {
-	try {
-		await unlink(path);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
 /**
  * Check mulch repository health and return diagnostic information.
  *

package/src/commands/completions.test.ts

@@ -2,7 +2,7 @@
  * Tests for shell completion generation.
  */
 
-import { describe, expect, it, mock } from "bun:test";
+import { afterEach, describe, expect, it, mock } from "bun:test";
 import {
 	COMMANDS,
 	completionsCommand,
@@ -11,9 +11,13 @@ import {
 	generateZsh,
 } from "./completions.ts";
 
+afterEach(() => {
+	process.exitCode = undefined;
+});
+
 describe("COMMANDS array", () => {
-	it("should have exactly 33 commands", () => {
-		expect(COMMANDS).toHaveLength(33);
+	it("should have exactly 34 commands", () => {
+		expect(COMMANDS).toHaveLength(34);
 	});
 
 	it("should include all expected command names", () => {
@@ -37,6 +41,7 @@ describe("COMMANDS array", () => {
 		expect(names).toContain("costs");
 		expect(names).toContain("metrics");
 		expect(names).toContain("spec");
+		expect(names).toContain("orchestrator");
 		expect(names).toContain("coordinator");
 		expect(names).toContain("supervisor");
 		expect(names).toContain("hooks");
@@ -62,7 +67,7 @@ describe("generateBash", () => {
 		expect(script).toContain("_init_completion");
 	});
 
-	it("should include all 33 command names", () => {
+	it("should include all 34 command names", () => {
 		const script = generateBash();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -96,7 +101,7 @@ describe("generateZsh", () => {
 		expect(script).toContain("_arguments");
 	});
 
-	it("should include all 33 command names", () => {
+	it("should include all 34 command names", () => {
 		const script = generateZsh();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -126,7 +131,7 @@ describe("generateFish", () => {
 		expect(script).toContain("__fish_use_subcommand");
 	});
 
-	it("should include all 33 command names", () => {
+	it("should include all 34 command names", () => {
 		const script = generateFish();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -148,6 +153,13 @@ describe("generateFish", () => {
 		expect(script).toContain("error");
 		expect(script).toContain("worker_done");
 	});
+
+	it("should include orchestrator command with start/stop/status subcommands", () => {
+		const orchestrator = COMMANDS.find((c) => c.name === "orchestrator");
+		expect(orchestrator).toBeDefined();
+		const subcommands = orchestrator?.subcommands?.map((s) => s.name);
+		expect(subcommands).toEqual(["start", "stop", "status"]);
+	});
 });
 
 describe("completionsCommand", () => {

package/src/commands/completions.ts

@@ -44,7 +44,16 @@ export const COMMANDS: readonly CommandDef[] = [
 						name: "--capability",
 						desc: "Filter by capability",
 						takesValue: true,
-						values: ["builder", "scout", "reviewer", "lead", "merger", "coordinator", "supervisor"],
+						values: [
+							"builder",
+							"scout",
+							"reviewer",
+							"lead",
+							"merger",
+							"orchestrator",
+							"coordinator",
+							"supervisor",
+						],
 					},
 					{ name: "--all", desc: "Include completed and zombie agents" },
 					{ name: "--json", desc: "JSON output" },
@@ -343,6 +352,36 @@ export const COMMANDS: readonly CommandDef[] = [
 			},
 		],
 	},
+	{
+		name: "orchestrator",
+		desc: "Persistent ecosystem orchestrator agent",
+		flags: [
+			{ name: "--json", desc: "JSON output" },
+			{ name: "--help", desc: "Show help" },
+		],
+		subcommands: [
+			{
+				name: "start",
+				desc: "Start orchestrator",
+				flags: [
+					{ name: "--attach", desc: "Attach to tmux session" },
+					{ name: "--no-attach", desc: "Do not attach to tmux session" },
+					{ name: "--watchdog", desc: "Auto-start watchdog daemon" },
+					{ name: "--json", desc: "JSON output" },
+				],
+			},
+			{
+				name: "stop",
+				desc: "Stop orchestrator",
+				flags: [{ name: "--json", desc: "JSON output" }],
+			},
+			{
+				name: "status",
+				desc: "Show orchestrator state",
+				flags: [{ name: "--json", desc: "JSON output" }],
+			},
+		],
+	},
 	{
 		name: "coordinator",
 		desc: "Persistent coordinator agent",

package/src/commands/coordinator.test.ts

@@ -29,6 +29,11 @@ import {
 	createCoordinatorCommand,
 	resolveAttach,
 } from "./coordinator.ts";
+import {
+	buildOrchestratorBeacon,
+	createOrchestratorCommand,
+	orchestratorCommand,
+} from "./orchestrator.ts";
 
 // --- Fake Tmux ---
 
@@ -272,14 +277,26 @@ beforeEach(async () => {
 				canSpawn: true,
 				constraints: [],
 			},
+			orchestrator: {
+				file: "orchestrator.md",
+				model: "opus",
+				tools: ["Read", "Bash"],
+				capabilities: ["orchestrate", "coordinate"],
+				canSpawn: true,
+				constraints: [],
+			},
+		},
+		capabilityIndex: {
+			coordinate: ["coordinator", "orchestrator"],
+			orchestrate: ["orchestrator"],
 		},
-		capabilityIndex: { coordinate: ["coordinator"] },
 	};
 	await Bun.write(
 		join(overstoryDir, "agent-manifest.json"),
 		`${JSON.stringify(manifest, null, "\t")}\n`,
 	);
 	await Bun.write(join(agentDefsDir, "coordinator.md"), "# Coordinator\n");
+	await Bun.write(join(agentDefsDir, "orchestrator.md"), "# Orchestrator\n");
 
 	// Override cwd so coordinator commands find our temp project
 	process.chdir(tempDir);
@@ -1255,14 +1272,16 @@ describe("buildCoordinatorBeacon", () => {
 
 	test("includes hierarchy enforcement instruction", () => {
 		const beacon = buildCoordinatorBeacon();
-		expect(beacon).toContain("ONLY spawn leads");
-		expect(beacon).toContain("NEVER spawn non-lead agents directly");
+		expect(beacon).toContain("Default to leads");
+		expect(beacon).toContain("spawn scout/builder directly");
+		expect(beacon).toContain("NEVER spawn reviewer or merger directly");
 	});
 
 	test("includes delegation instruction", () => {
 		const beacon = buildCoordinatorBeacon();
 		expect(beacon).toContain("DELEGATION");
-		expect(beacon).toContain("spawn a lead who will spawn scouts");
+		expect(beacon).toContain("spawn a lead who will handle scouts/builders/reviewers");
+		expect(beacon).toContain("--dispatch-max-agents 1/2");
 	});
 
 	test("parts are joined with em-dash separator", () => {
@@ -1273,6 +1292,60 @@ describe("buildCoordinatorBeacon", () => {
 	});
 });
 
+describe("orchestratorCommand", () => {
+	test("help shows orchestrator command name", async () => {
+		const output = await captureStdout(() => orchestratorCommand(["--help"]));
+		expect(output).toContain("orchestrator");
+	});
+
+	test("start creates orchestrator session with orchestrator capability", async () => {
+		const { deps, calls } = makeDeps({ "overstory-test-project-orchestrator": true });
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			const output = await captureStdout(() =>
+				orchestratorCommand(["start", "--no-attach", "--json"], deps),
+			);
+			const parsed = JSON.parse(output) as Record<string, unknown>;
+
+			expect(parsed.agentName).toBe("orchestrator");
+			expect(parsed.capability).toBe("orchestrator");
+			expect(parsed.tmuxSession).toBe("overstory-test-project-orchestrator");
+			expect(calls.createSession[0]?.name).toBe("overstory-test-project-orchestrator");
+			expect(calls.createSession[0]?.command).toContain("orchestrator.md");
+
+			const session = loadSessionsFromDb().find((entry) => entry.agentName === "orchestrator");
+			expect(session?.capability).toBe("orchestrator");
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+	});
+
+	test("command registration includes orchestrator start/stop/status", () => {
+		const cmd = createOrchestratorCommand({});
+		const subcommandNames = cmd.commands.map((c) => c.name());
+		expect(subcommandNames).toContain("start");
+		expect(subcommandNames).toContain("stop");
+		expect(subcommandNames).toContain("status");
+		expect(subcommandNames).not.toContain("check-complete");
+	});
+});
+
+describe("buildOrchestratorBeacon", () => {
+	test("includes orchestrator identity in header", () => {
+		const beacon = buildOrchestratorBeacon();
+		expect(beacon).toContain("[OVERSTORY] orchestrator (orchestrator)");
+	});
+
+	test("includes ecosystem startup instructions", () => {
+		const beacon = buildOrchestratorBeacon("sd");
+		expect(beacon).toContain("ov mail check --agent orchestrator");
+		expect(beacon).toContain("sd ready");
+		expect(beacon).toContain("inspect ecosystem status");
+	});
+});
+
 describe("resolveAttach", () => {
 	test("--attach flag forces attach regardless of TTY", () => {
 		expect(resolveAttach(["--attach"], false)).toBe(true);