@os-eco/overstory-cli 0.6.1 → 0.6.4

package/src/doctor/databases.test.ts

@@ -51,13 +51,15 @@ describe("checkDatabases", () => {
 	test("fails when database files do not exist", () => {
 		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
 
-		expect(checks).toHaveLength(3);
+		expect(checks).toHaveLength(4);
 		expect(checks[0]?.status).toBe("fail");
 		expect(checks[0]?.name).toBe("mail.db exists");
 		expect(checks[1]?.status).toBe("fail");
 		expect(checks[1]?.name).toBe("metrics.db exists");
 		expect(checks[2]?.status).toBe("fail");
 		expect(checks[2]?.name).toBe("sessions.db exists");
+		expect(checks[3]?.status).toBe("fail");
+		expect(checks[3]?.name).toBe("merge-queue.db exists");
 	});
 
 	test("passes when databases exist with correct schema", () => {
@@ -141,13 +143,31 @@ describe("checkDatabases", () => {
 		`);
 		sessionsDb.close();
 
+		// Create merge-queue.db
+		const mergeDb = new Database(join(tempDir, "merge-queue.db"));
+		mergeDb.exec("PRAGMA journal_mode=WAL");
+		mergeDb.exec(`
+			CREATE TABLE merge_queue (
+				id INTEGER PRIMARY KEY AUTOINCREMENT,
+				branch_name TEXT NOT NULL,
+				task_id TEXT NOT NULL,
+				agent_name TEXT NOT NULL,
+				files_modified TEXT NOT NULL DEFAULT '[]',
+				enqueued_at TEXT NOT NULL,
+				status TEXT NOT NULL DEFAULT 'pending',
+				resolved_tier TEXT
+			)
+		`);
+		mergeDb.close();
+
 		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
 
-		expect(checks).toHaveLength(3);
+		expect(checks).toHaveLength(4);
 		expect(checks.every((c) => c?.status === "pass")).toBe(true);
 		expect(checks[0]?.name).toBe("mail.db health");
 		expect(checks[1]?.name).toBe("metrics.db health");
 		expect(checks[2]?.name).toBe("sessions.db health");
+		expect(checks[3]?.name).toBe("merge-queue.db health");
 	});
 
 	test("fails when table is missing", () => {

package/src/doctor/databases.ts

@@ -85,6 +85,22 @@ export const checkDatabases: DoctorCheckFn = (_config, overstoryDir): DoctorChec
 				],
 			},
 		},
+		{
+			name: "merge-queue.db",
+			tables: ["merge_queue"],
+			requiredColumns: {
+				merge_queue: [
+					"id",
+					"branch_name",
+					"task_id",
+					"agent_name",
+					"files_modified",
+					"enqueued_at",
+					"status",
+					"resolved_tier",
+				],
+			},
+		},
 	];
 
 	for (const dbSpec of databases) {

package/src/doctor/dependencies.test.ts

@@ -57,7 +57,7 @@ describe("checkDependencies", () => {
 		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
 
 		expect(checks).toBeArray();
-		expect(checks.length).toBeGreaterThanOrEqual(5);
+		expect(checks.length).toBeGreaterThanOrEqual(7);
 
 		// Verify we have checks for each required tool
 		const toolNames = checks.map((c) => c.name);
@@ -66,6 +66,8 @@ describe("checkDependencies", () => {
 		expect(toolNames).toContain("tmux availability");
 		expect(toolNames).toContain("sd availability");
 		expect(toolNames).toContain("mulch availability");
+		expect(toolNames).toContain("overstory availability");
+		expect(toolNames).toContain("cn availability");
 	});
 
 	test("includes bd CGO support check when bd is available", async () => {
@@ -181,4 +183,56 @@ describe("checkDependencies", () => {
 		const cgoCheck = checks.find((c) => c.name === "bd CGO support");
 		expect(cgoCheck).toBeUndefined();
 	});
+
+	test("cn check is warn (not fail) when missing", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		const cnCheck = checks.find((c) => c.name === "cn availability");
+		expect(cnCheck).toBeDefined();
+		// cn is optional — should never be "fail", only "pass" or "warn"
+		expect(cnCheck?.status).not.toBe("fail");
+	});
+
+	test("checks short aliases for available tools", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		const mulchCheck = checks.find((c) => c.name === "mulch availability");
+		if (mulchCheck?.status === "pass") {
+			const mlAlias = checks.find((c) => c.name === "ml alias");
+			expect(mlAlias).toBeDefined();
+			expect(mlAlias?.category).toBe("dependencies");
+			expect(["pass", "warn"]).toContain(mlAlias?.status ?? "");
+		}
+		const ovCheck = checks.find((c) => c.name === "overstory availability");
+		if (ovCheck?.status === "pass") {
+			const ovAlias = checks.find((c) => c.name === "ov alias");
+			expect(ovAlias).toBeDefined();
+			expect(["pass", "warn"]).toContain(ovAlias?.status ?? "");
+		}
+	});
+
+	test("alias checks are only run when primary tool passes", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		// If mulch failed, ml alias should NOT be present
+		const mulchCheck = checks.find((c) => c.name === "mulch availability");
+		const mlAlias = checks.find((c) => c.name === "ml alias");
+		if (mulchCheck?.status !== "pass") {
+			expect(mlAlias).toBeUndefined();
+		}
+	});
+
+	test("install hints appear in details for missing tools", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		// Check any failing/warning check with an installHint has npm install guidance
+		const cnCheck = checks.find((c) => c.name === "cn availability");
+		if (cnCheck?.status === "warn" || cnCheck?.status === "fail") {
+			const hasInstallHint = cnCheck.details?.some((d) => d.includes("npm install -g"));
+			expect(hasInstallHint).toBe(true);
+		}
+	});
+
+	test("includes overstory availability check", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		const ovCheck = checks.find((c) => c.name === "overstory availability");
+		expect(ovCheck).toBeDefined();
+		expect(ovCheck?.category).toBe("dependencies");
+	});
 });

package/src/doctor/dependencies.ts

@@ -1,10 +1,20 @@
 import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
 import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
 
+interface ToolSpec {
+	name: string;
+	versionFlag: string;
+	required: boolean;
+	/** Short alias to check if the primary tool is available. */
+	alias?: string;
+	/** npm package name for install hint (e.g. "@os-eco/mulch-cli"). */
+	installHint?: string;
+}
+
 /**
  * External dependency checks.
- * Validates that required CLI tools (git, bun, tmux, bd, mulch) are available
- * and that bd has functional CGO support for its Dolt database backend.
+ * Validates that required CLI tools (git, bun, tmux, tracker, mulch, overstory)
+ * and optional tools (cn) are available, including short alias availability.
  */
 export const checkDependencies: DoctorCheckFn = async (
 	config,
@@ -12,30 +22,56 @@ export const checkDependencies: DoctorCheckFn = async (
 ): Promise<DoctorCheck[]> => {
 	// Determine which tracker CLI to check based on config backend (resolve "auto")
 	const resolvedBackend = await resolveBackend(config.taskTracker.backend, config.project.root);
-	const trackerTool = {
-		name: trackerCliName(resolvedBackend),
-		versionFlag: "--version",
-		required: true,
-	};
+	const trackerName = trackerCliName(resolvedBackend);
 
-	const requiredTools = [
+	const tools: ToolSpec[] = [
 		{ name: "git", versionFlag: "--version", required: true },
 		{ name: "bun", versionFlag: "--version", required: true },
 		{ name: "tmux", versionFlag: "-V", required: true },
-		trackerTool,
-		{ name: "mulch", versionFlag: "--version", required: true },
+		{
+			name: trackerName,
+			versionFlag: "--version",
+			required: true,
+			installHint: trackerName === "sd" ? "@os-eco/seeds-cli" : undefined,
+		},
+		{
+			name: "mulch",
+			versionFlag: "--version",
+			required: true,
+			alias: "ml",
+			installHint: "@os-eco/mulch-cli",
+		},
+		{
+			name: "overstory",
+			versionFlag: "--version",
+			required: true,
+			alias: "ov",
+			installHint: "@os-eco/overstory-cli",
+		},
+		{
+			name: "cn",
+			versionFlag: "--version",
+			required: false,
+			installHint: "@os-eco/canopy-cli",
+		},
 	];
 
 	const checks: DoctorCheck[] = [];
 
-	for (const tool of requiredTools) {
-		const check = await checkTool(tool.name, tool.versionFlag, tool.required);
+	for (const tool of tools) {
+		const check = await checkTool(tool.name, tool.versionFlag, tool.required, tool.installHint);
 		checks.push(check);
+
+		// Check short alias availability if the main tool is available
+		if (tool.alias && check.status === "pass") {
+			const aliasCheck = await checkAlias(tool.name, tool.alias, tool.installHint);
+			checks.push(aliasCheck);
+		}
 	}
 
 	// If bd is available, probe for CGO/Dolt backend functionality.
 	// Only run for beads backend (CGO check is beads-specific).
-	if (trackerTool.name === "bd") {
+	if (trackerName === "bd") {
 		const bdCheck = checks.find((c) => c.name === "bd availability");
 		if (bdCheck?.status === "pass") {
 			const cgoCheck = await checkBdCgoSupport();
@@ -119,6 +155,57 @@ async function checkBdCgoSupport(): Promise<DoctorCheck> {
 	}
 }
 
+/**
+ * Check if a short alias for a CLI tool is available.
+ */
+async function checkAlias(
+	toolName: string,
+	alias: string,
+	installHint?: string,
+): Promise<DoctorCheck> {
+	try {
+		const proc = Bun.spawn([alias, "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+
+		if (exitCode === 0) {
+			return {
+				name: `${alias} alias`,
+				category: "dependencies",
+				status: "pass",
+				message: `${alias} alias for ${toolName} is available`,
+				details: [`Short alias '${alias}' is configured`],
+			};
+		}
+
+		const hint = installHint
+			? `Reinstall ${installHint} to get the '${alias}' alias.`
+			: `Ensure '${alias}' alias is in your PATH.`;
+		return {
+			name: `${alias} alias`,
+			category: "dependencies",
+			status: "warn",
+			message: `${alias} alias for ${toolName} not working`,
+			details: [hint],
+			fixable: true,
+		};
+	} catch {
+		const hint = installHint
+			? `Reinstall ${installHint} to get the '${alias}' alias.`
+			: `Ensure '${alias}' alias is in your PATH.`;
+		return {
+			name: `${alias} alias`,
+			category: "dependencies",
+			status: "warn",
+			message: `${alias} alias for ${toolName} is not available`,
+			details: [`'${toolName}' works but short alias '${alias}' was not found.`, hint],
+			fixable: true,
+		};
+	}
+}
+
 /**
  * Check if a CLI tool is available by attempting to run it with a version flag.
  */
@@ -126,6 +213,7 @@ async function checkTool(
 	name: string,
 	versionFlag: string,
 	required: boolean,
+	installHint?: string,
 ): Promise<DoctorCheck> {
 	try {
 		const proc = Bun.spawn([name, versionFlag], {
@@ -150,25 +238,32 @@ async function checkTool(
 
 		// Non-zero exit code
 		const stderr = await new Response(proc.stderr).text();
+		const details: string[] = [];
+		if (stderr) details.push(stderr.trim());
+		if (installHint) details.push(`Install: npm install -g ${installHint}`);
 		return {
 			name: `${name} availability`,
 			category: "dependencies",
 			status: required ? "fail" : "warn",
 			message: `${name} command failed (exit code ${exitCode})`,
-			details: stderr ? [stderr.trim()] : undefined,
+			details: details.length > 0 ? details : undefined,
 			fixable: true,
 		};
 	} catch (error) {
 		// Command not found or spawn failed
+		const details: string[] = [];
+		if (installHint) {
+			details.push(`Install: npm install -g ${installHint}`);
+		} else {
+			details.push(`Install ${name} or ensure it is in your PATH`);
+		}
+		details.push(error instanceof Error ? error.message : String(error));
 		return {
 			name: `${name} availability`,
 			category: "dependencies",
 			status: required ? "fail" : "warn",
 			message: `${name} is not installed or not in PATH`,
-			details: [
-				`Install ${name} or ensure it is in your PATH`,
-				error instanceof Error ? error.message : String(error),
-			],
+			details,
 			fixable: true,
 		};
 	}

package/src/e2e/init-sling-lifecycle.test.ts

@@ -52,7 +52,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("init creates all expected artifacts", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const overstoryDir = join(tempDir, ".overstory");
 
@@ -92,7 +92,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("loadConfig returns valid config pointing to temp dir", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const config = await loadConfig(tempDir);
 
@@ -110,7 +110,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("manifest loads successfully with all 8 agents", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const manifestPath = join(tempDir, ".overstory", "agent-manifest.json");
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");
@@ -145,7 +145,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("manifest capability index is consistent", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const manifestPath = join(tempDir, ".overstory", "agent-manifest.json");
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");
@@ -167,7 +167,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("overlay generation works for external project", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");
 		const baseDefinition = await Bun.file(join(agentDefsDir, "builder.md")).text();
@@ -215,7 +215,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 		// init → load config → load manifest → generate overlay
 
 		// Step 1: Init
-		await initCommand([]);
+		await initCommand({});
 
 		// Step 2: Load config
 		const config = await loadConfig(tempDir);