@os-eco/overstory-cli 0.8.7 → 0.9.2

package/src/commands/dashboard.ts

@@ -59,10 +59,13 @@ const PKG_VERSION: string = JSON.parse(await Bun.file(pkgPath).text()).version ?
  * These are not colors, so they stay separate from the color module.
  */
 const CURSOR = {
-	clear: "\x1b[2J\x1b[H", // Clear screen and home cursor
+	clear: "\x1b[H\x1b[J", // Home cursor then clear from cursor to end
+	home: "\x1b[H", // Home cursor only (for redraw without full clear)
 	cursorTo: (row: number, col: number) => `\x1b[${row};${col}H`,
 	hideCursor: "\x1b[?25l",
 	showCursor: "\x1b[?25h",
+	enterAltScreen: "\x1b[?1049h", // Enter alternate screen buffer
+	leaveAltScreen: "\x1b[?1049l", // Leave alternate screen buffer
 } as const;
 
 /**
@@ -960,11 +963,13 @@ function renderMetricsPanel(
 /**
  * Render the full dashboard.
  */
-function renderDashboard(data: DashboardData, interval: number): void {
+function renderDashboard(data: DashboardData, interval: number, isFirstRender: boolean): void {
 	const width = process.stdout.columns ?? 100;
 	const height = process.stdout.rows ?? 30;
 
-	let output = CURSOR.clear;
+	// First render: clear entire alt screen. Subsequent: just home cursor
+	// and overwrite in-place (avoids Warp's block-per-clear issue).
+	let output = isFirstRender ? CURSOR.clear : CURSOR.home;
 
 	// Header (rows 1-2)
 	output += renderHeader(width, interval, data.currentRunId);
@@ -1050,20 +1055,44 @@ async function executeDashboard(opts: DashboardOpts): Promise<void> {
 		zombieMs: config.watchdog.zombieThresholdMs,
 	};
 
-	// Hide cursor
+	// Enter alternate screen buffer (like vim/htop) + hide cursor + raw stdin
+	process.stdout.write(CURSOR.enterAltScreen);
 	process.stdout.write(CURSOR.hideCursor);
+	if (process.stdin.isTTY) {
+		process.stdin.setRawMode(true);
+		process.stdin.resume();
+	}
 
-	// Clean exit on Ctrl+C
+	// Clean exit on Ctrl+C or 'q': restore original screen
 	let running = true;
-	process.on("SIGINT", () => {
+	const cleanup = () => {
 		running = false;
+		if (process.stdin.isTTY) {
+			process.stdin.setRawMode(false);
+			process.stdin.pause();
+		}
 		closeDashboardStores(stores);
 		process.stdout.write(CURSOR.showCursor);
-		process.stdout.write(CURSOR.clear);
-		process.exit(0);
+		process.stdout.write(CURSOR.leaveAltScreen);
+	};
+
+	process.on("SIGINT", () => {
+		cleanup();
+		process.exitCode = 0;
+	});
+
+	// Allow 'q' to quit the dashboard
+	process.stdin.on("data", (data: Buffer) => {
+		const key = data.toString();
+		if (key === "q" || key === "\x03") {
+			// 'q' or Ctrl+C
+			cleanup();
+			process.exitCode = 0;
+		}
 	});
 
 	// Poll loop — errors are caught per-tick so transient DB failures never crash the dashboard.
+	let isFirstRender = true;
 	let lastGoodData: DashboardData | null = null;
 	let lastErrorMsg: string | null = null;
 	while (running) {
@@ -1077,12 +1106,20 @@ async function executeDashboard(opts: DashboardOpts): Promise<void> {
 				config.runtime,
 			);
 			lastGoodData = data;
+			// If recovering from an error, clear the stale error line at the bottom
+			if (lastErrorMsg !== null) {
+				const w = process.stdout.columns ?? 100;
+				const h = process.stdout.rows ?? 30;
+				process.stdout.write(`${CURSOR.cursorTo(h, 1)}${" ".repeat(w)}`);
+			}
 			lastErrorMsg = null;
-			renderDashboard(data, interval);
+			renderDashboard(data, interval, isFirstRender);
+			isFirstRender = false;
 		} catch (err) {
 			// Render last good frame so the TUI stays alive, then show the error inline.
 			if (lastGoodData) {
-				renderDashboard(lastGoodData, interval);
+				renderDashboard(lastGoodData, interval, isFirstRender);
+				isFirstRender = false;
 			}
 			lastErrorMsg = err instanceof Error ? err.message : String(err);
 			const w = process.stdout.columns ?? 100;

package/src/commands/discover.test.ts

@@ -0,0 +1,288 @@
+/**
+ * Tests for ov discover command.
+ *
+ * Tests cover the pure functions and command structure.
+ * The coordinator session startup is not tested here (requires tmux and
+ * external processes). Use dependency injection via DiscoverDeps to test
+ * that discoverCommand() delegates correctly.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { ValidationError } from "../errors.ts";
+import type { CoordinatorSessionOptions } from "./coordinator.ts";
+import {
+	buildDiscoveryBeacon,
+	buildScoutArgs,
+	createDiscoverCommand,
+	DISCOVERY_CATEGORIES,
+	type DiscoverDeps,
+	discoverCommand,
+	VALID_CATEGORY_NAMES,
+} from "./discover.ts";
+
+describe("DISCOVERY_CATEGORIES", () => {
+	test("has exactly 6 categories", () => {
+		expect(DISCOVERY_CATEGORIES).toHaveLength(6);
+	});
+
+	test("each category has name, subject, and body", () => {
+		for (const category of DISCOVERY_CATEGORIES) {
+			expect(category.name).toBeTruthy();
+			expect(category.subject).toBeTruthy();
+			expect(category.body).toBeTruthy();
+		}
+	});
+
+	test("contains all expected category names", () => {
+		const names = DISCOVERY_CATEGORIES.map((c) => c.name);
+		expect(names).toContain("architecture");
+		expect(names).toContain("dependencies");
+		expect(names).toContain("testing");
+		expect(names).toContain("apis");
+		expect(names).toContain("config");
+		expect(names).toContain("implicit");
+	});
+});
+
+describe("VALID_CATEGORY_NAMES", () => {
+	test("contains all 6 category names", () => {
+		expect(VALID_CATEGORY_NAMES.size).toBe(6);
+		expect(VALID_CATEGORY_NAMES.has("architecture")).toBe(true);
+		expect(VALID_CATEGORY_NAMES.has("dependencies")).toBe(true);
+		expect(VALID_CATEGORY_NAMES.has("testing")).toBe(true);
+		expect(VALID_CATEGORY_NAMES.has("apis")).toBe(true);
+		expect(VALID_CATEGORY_NAMES.has("config")).toBe(true);
+		expect(VALID_CATEGORY_NAMES.has("implicit")).toBe(true);
+	});
+
+	test("does not contain invalid category names", () => {
+		expect(VALID_CATEGORY_NAMES.has("unknown")).toBe(false);
+		expect(VALID_CATEGORY_NAMES.has("")).toBe(false);
+	});
+});
+
+describe("buildScoutArgs()", () => {
+	test("returns correct args array for a category", () => {
+		const category = DISCOVERY_CATEGORIES[0];
+		if (!category) throw new Error("DISCOVERY_CATEGORIES is empty");
+		const args = buildScoutArgs(category, "task-123", "discover-coordinator");
+		expect(args).toContain("ov");
+		expect(args).toContain("sling");
+		expect(args).toContain("task-123");
+		expect(args).toContain("--capability");
+		expect(args).toContain("scout");
+		expect(args).toContain("--name");
+		expect(args).toContain(`discover-${category.name}`);
+		expect(args).toContain("--profile");
+		expect(args).toContain("ov-discovery");
+		expect(args).toContain("--parent");
+		expect(args).toContain("discover-coordinator");
+		expect(args).toContain("--skip-task-check");
+	});
+});
+
+describe("buildDiscoveryBeacon()", () => {
+	test("includes coordinator name", () => {
+		const beacon = buildDiscoveryBeacon(DISCOVERY_CATEGORIES, "discover-coordinator");
+		expect(beacon).toContain("discover-coordinator");
+	});
+
+	test("includes all active category names", () => {
+		const beacon = buildDiscoveryBeacon(DISCOVERY_CATEGORIES, "discover-coordinator");
+		for (const cat of DISCOVERY_CATEGORIES) {
+			expect(beacon).toContain(cat.name);
+		}
+	});
+
+	test("includes timestamp marker", () => {
+		const beacon = buildDiscoveryBeacon(DISCOVERY_CATEGORIES, "discover-coordinator");
+		expect(beacon).toContain("[OVERSTORY]");
+	});
+
+	test("excludes skipped categories", () => {
+		const active = DISCOVERY_CATEGORIES.filter((c) => c.name !== "testing");
+		const beacon = buildDiscoveryBeacon(active, "discover-coordinator");
+		// All active categories present
+		for (const cat of active) {
+			expect(beacon).toContain(cat.name);
+		}
+		// The skipped category body text should not appear as a standalone discovery target
+		// (the name "testing" may appear inside other category descriptions, so check body)
+		const testingCat = DISCOVERY_CATEGORIES.find((c) => c.name === "testing");
+		if (!testingCat) throw new Error("testing category not found");
+		expect(beacon).not.toContain(testingCat.body);
+	});
+
+	test("includes startup instructions", () => {
+		const beacon = buildDiscoveryBeacon(DISCOVERY_CATEGORIES, "discover-coordinator");
+		expect(beacon).toContain("mulch prime");
+		expect(beacon).toContain("spawn one lead per");
+	});
+});
+
+describe("createDiscoverCommand()", () => {
+	test("returns a Command with name 'discover'", () => {
+		const cmd = createDiscoverCommand();
+		expect(cmd.name()).toBe("discover");
+	});
+
+	test("has --skip option", () => {
+		const cmd = createDiscoverCommand();
+		const option = cmd.options.find((o) => o.long === "--skip");
+		expect(option).toBeDefined();
+	});
+
+	test("has --name option", () => {
+		const cmd = createDiscoverCommand();
+		const option = cmd.options.find((o) => o.long === "--name");
+		expect(option).toBeDefined();
+	});
+
+	test("has --task-id option", () => {
+		const cmd = createDiscoverCommand();
+		const option = cmd.options.find((o) => o.long === "--task-id");
+		expect(option).toBeDefined();
+	});
+
+	test("has --json option", () => {
+		const cmd = createDiscoverCommand();
+		const option = cmd.options.find((o) => o.long === "--json");
+		expect(option).toBeDefined();
+	});
+
+	test("has --attach option", () => {
+		const cmd = createDiscoverCommand();
+		const option = cmd.options.find((o) => o.long === "--attach");
+		expect(option).toBeDefined();
+	});
+
+	test("has --watchdog option", () => {
+		const cmd = createDiscoverCommand();
+		const option = cmd.options.find((o) => o.long === "--watchdog");
+		expect(option).toBeDefined();
+	});
+
+	test("has a description", () => {
+		const cmd = createDiscoverCommand();
+		expect(cmd.description()).toBeTruthy();
+	});
+});
+
+describe("discoverCommand() skip validation", () => {
+	test("throws ValidationError for invalid category name", async () => {
+		await expect(discoverCommand({ skip: "notacategory" })).rejects.toThrow(ValidationError);
+	});
+
+	test("throws ValidationError for mixed valid and invalid categories", async () => {
+		await expect(discoverCommand({ skip: "architecture,notacategory" })).rejects.toThrow(
+			ValidationError,
+		);
+	});
+
+	test("throws ValidationError when all categories are skipped", async () => {
+		const allCategories = DISCOVERY_CATEGORIES.map((c) => c.name).join(",");
+		await expect(discoverCommand({ skip: allCategories })).rejects.toThrow(ValidationError);
+	});
+
+	test("throws ValidationError with helpful message for invalid category", async () => {
+		let thrownError: unknown;
+		try {
+			await discoverCommand({ skip: "badcategory" });
+		} catch (err) {
+			thrownError = err;
+		}
+		expect(thrownError).toBeInstanceOf(ValidationError);
+		const ve = thrownError as ValidationError;
+		expect(ve.message).toContain("badcategory");
+		expect(ve.message).toContain("Valid categories");
+	});
+});
+
+describe("discoverCommand() delegation", () => {
+	test("calls startCoordinatorSession with ov-discovery profile", async () => {
+		let capturedOpts: CoordinatorSessionOptions | undefined;
+		const deps: DiscoverDeps = {
+			_startCoordinatorSession: async (opts) => {
+				capturedOpts = opts;
+			},
+		};
+
+		await discoverCommand({ attach: false }, deps);
+
+		expect(capturedOpts).toBeDefined();
+		expect(capturedOpts?.profile).toBe("ov-discovery");
+	});
+
+	test("uses default coordinator name 'discover-coordinator'", async () => {
+		let capturedOpts: CoordinatorSessionOptions | undefined;
+		const deps: DiscoverDeps = {
+			_startCoordinatorSession: async (opts) => {
+				capturedOpts = opts;
+			},
+		};
+
+		await discoverCommand({ attach: false }, deps);
+
+		expect(capturedOpts?.coordinatorName).toBe("discover-coordinator");
+	});
+
+	test("uses custom name when provided", async () => {
+		let capturedOpts: CoordinatorSessionOptions | undefined;
+		const deps: DiscoverDeps = {
+			_startCoordinatorSession: async (opts) => {
+				capturedOpts = opts;
+			},
+		};
+
+		await discoverCommand({ name: "my-discover", attach: false }, deps);
+
+		expect(capturedOpts?.coordinatorName).toBe("my-discover");
+	});
+
+	test("beacon builder returns string containing active category names", async () => {
+		let capturedOpts: CoordinatorSessionOptions | undefined;
+		const deps: DiscoverDeps = {
+			_startCoordinatorSession: async (opts) => {
+				capturedOpts = opts;
+			},
+		};
+
+		await discoverCommand({ skip: "testing,config,implicit", attach: false }, deps);
+
+		expect(capturedOpts?.beaconBuilder).toBeDefined();
+		const beacon = capturedOpts?.beaconBuilder?.("bd") ?? "";
+		expect(beacon).toContain("architecture");
+		expect(beacon).toContain("dependencies");
+		expect(beacon).toContain("apis");
+		// Skipped categories should not appear as category targets in the beacon
+		const testingCat = DISCOVERY_CATEGORIES.find((c) => c.name === "testing");
+		if (!testingCat) throw new Error("testing category not found");
+		expect(beacon).not.toContain(testingCat.body);
+	});
+
+	test("sets monitor: false", async () => {
+		let capturedOpts: CoordinatorSessionOptions | undefined;
+		const deps: DiscoverDeps = {
+			_startCoordinatorSession: async (opts) => {
+				capturedOpts = opts;
+			},
+		};
+
+		await discoverCommand({ attach: false }, deps);
+
+		expect(capturedOpts?.monitor).toBe(false);
+	});
+
+	test("forwards watchdog option", async () => {
+		let capturedOpts: CoordinatorSessionOptions | undefined;
+		const deps: DiscoverDeps = {
+			_startCoordinatorSession: async (opts) => {
+				capturedOpts = opts;
+			},
+		};
+
+		await discoverCommand({ watchdog: true, attach: false }, deps);
+
+		expect(capturedOpts?.watchdog).toBe(true);
+	});
+});

package/src/commands/discover.ts

@@ -0,0 +1,202 @@
+/**
+ * CLI command: ov discover
+ *
+ * Launches a coordinator session with the ov-discovery profile to explore a
+ * brownfield codebase and produce structured mulch records. The coordinator
+ * autonomously spawns leads, which spawn scouts per category, synthesizes
+ * results, and writes mulch records.
+ */
+
+import { Command } from "commander";
+import { ValidationError } from "../errors.ts";
+import type { CoordinatorDeps, CoordinatorSessionOptions } from "./coordinator.ts";
+import { startCoordinatorSession } from "./coordinator.ts";
+
+/** A single discovery category with its research focus. */
+export interface DiscoveryCategory {
+	name: string;
+	subject: string;
+	body: string;
+}
+
+/** All discovery categories that scouts will explore. */
+export const DISCOVERY_CATEGORIES: DiscoveryCategory[] = [
+	{
+		name: "architecture",
+		subject: "Discover: architecture",
+		body: "Explore directory structure, module boundaries, layering conventions, and design patterns. Identify the core architectural style (monolith, layered, hexagonal, etc.), note major subsystems and their relationships, and document any implicit layering rules or boundary conventions.",
+	},
+	{
+		name: "dependencies",
+		subject: "Discover: dependencies",
+		body: "Catalog all npm packages, CLI tool dependencies, and version constraints. Identify runtime vs dev dependencies, note any unusual or pinned versions, and flag deprecated or potentially problematic packages. Document any external CLIs invoked as subprocesses.",
+	},
+	{
+		name: "testing",
+		subject: "Discover: testing",
+		body: "Map the test framework, file locations, mock strategy, and coverage gaps. Identify what test runner is used, where tests live relative to source, what mocking patterns are used (and why), and which subsystems lack adequate test coverage.",
+	},
+	{
+		name: "apis",
+		subject: "Discover: apis",
+		body: "Document exported functions and types, interfaces, error handling patterns, and CLI structure. Identify the public API surface, note how errors are typed and propagated, and document any conventions around return types or async patterns.",
+	},
+	{
+		name: "config",
+		subject: "Discover: config",
+		body: "Catalog config file formats, environment variables, loading and validation patterns, and default values. Note how configuration is structured (YAML, JSON, env), how it's validated at runtime, and what the expected defaults are.",
+	},
+	{
+		name: "implicit",
+		subject: "Discover: implicit",
+		body: "Surface naming conventions, error handling style, TODOs, and unwritten rules. Look for patterns in variable naming, file naming, comment style, and any informal conventions that aren't documented. Note recurring TODOs or FIXMEs that indicate known debt.",
+	},
+];
+
+/** Set of valid category names for validation. */
+export const VALID_CATEGORY_NAMES: ReadonlySet<string> = new Set(
+	DISCOVERY_CATEGORIES.map((c) => c.name),
+);
+
+export interface DiscoverOptions {
+	skip?: string;
+	name?: string;
+	taskId?: string;
+	attach?: boolean;
+	watchdog?: boolean;
+	json?: boolean;
+}
+
+/** Dependency injection for discoverCommand. Used in tests. */
+export interface DiscoverDeps {
+	_startCoordinatorSession?: (
+		opts: CoordinatorSessionOptions,
+		deps: CoordinatorDeps,
+	) => Promise<void>;
+}
+
+/** Parse and validate the --skip option, returning a set of category names to skip. */
+function parseSkipCategories(skip: string | undefined): Set<string> {
+	if (!skip) return new Set();
+	const names = skip
+		.split(",")
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+	const invalid = names.filter((n) => !VALID_CATEGORY_NAMES.has(n));
+	if (invalid.length > 0) {
+		throw new ValidationError(
+			`Invalid category name(s): ${invalid.join(", ")}. Valid categories: ${[...VALID_CATEGORY_NAMES].join(", ")}`,
+		);
+	}
+	return new Set(names);
+}
+
+/**
+ * Build the discovery beacon — the initial prompt sent to the discover coordinator
+ * after Claude Code initializes. Instructs it to spawn one lead per category.
+ */
+export function buildDiscoveryBeacon(
+	categories: DiscoveryCategory[],
+	coordinatorName: string,
+): string {
+	const timestamp = new Date().toISOString();
+	const categoryNames = categories.map((c) => c.name).join(", ");
+	const categoryDetails = categories.map((c) => `${c.name}: ${c.body}`).join(" | ");
+	const parts = [
+		`[OVERSTORY] ${coordinatorName} (coordinator) ${timestamp}`,
+		`Role: discovery coordinator | Categories: ${categoryNames}`,
+		`Startup: run mulch prime, then spawn one lead per active category. Each lead spawns a scout to explore its category area. After all scouts report back, synthesize findings into mulch records.`,
+		`Categories: ${categoryDetails}`,
+	];
+	return parts.join(" — ");
+}
+
+/**
+ * Build the scout args for a given discovery category and task ID.
+ * Kept for reference and for callers that need per-category sling arguments.
+ */
+export function buildScoutArgs(
+	category: DiscoveryCategory,
+	taskId: string,
+	parentName: string,
+): string[] {
+	return [
+		"ov",
+		"sling",
+		taskId,
+		"--capability",
+		"scout",
+		"--name",
+		`discover-${category.name}`,
+		"--profile",
+		"ov-discovery",
+		"--parent",
+		parentName,
+		"--depth",
+		"1",
+		"--skip-task-check",
+	];
+}
+
+/** Main handler for ov discover. */
+export async function discoverCommand(
+	opts: DiscoverOptions,
+	deps: DiscoverDeps = {},
+): Promise<void> {
+	const json = opts.json ?? false;
+	const coordinatorName = opts.name ?? "discover-coordinator";
+
+	// Validate and parse skip list
+	const skipSet = parseSkipCategories(opts.skip);
+	const categories = DISCOVERY_CATEGORIES.filter((c) => !skipSet.has(c.name));
+
+	if (categories.length === 0) {
+		throw new ValidationError("All categories skipped — nothing to discover.");
+	}
+
+	const attach = opts.attach !== undefined ? opts.attach : !!process.stdout.isTTY;
+
+	const startSession = deps._startCoordinatorSession ?? startCoordinatorSession;
+
+	await startSession(
+		{
+			json,
+			attach,
+			watchdog: opts.watchdog ?? false,
+			monitor: false,
+			profile: "ov-discovery",
+			coordinatorName,
+			beaconBuilder: (_trackerCli) => buildDiscoveryBeacon(categories, coordinatorName),
+		},
+		{},
+	);
+}
+
+/** Commander command factory. */
+export function createDiscoverCommand(): Command {
+	return new Command("discover")
+		.description("Discover a brownfield codebase via coordinator-driven scout swarm")
+		.option(
+			"--skip <categories>",
+			"Skip specific categories (comma-separated: architecture,dependencies,testing,apis,config,implicit)",
+		)
+		.option("--name <name>", "Coordinator agent name (default: discover-coordinator)")
+		.option("--task-id <id>", "Task ID (unused — kept for backward compatibility)")
+		.option("--attach", "Always attach to tmux session after start")
+		.option("--no-attach", "Never attach to tmux session after start")
+		.option("--watchdog", "Auto-start watchdog daemon with coordinator")
+		.option("--json", "Output as JSON")
+		.action(
+			async (opts: {
+				skip?: string;
+				name?: string;
+				taskId?: string;
+				attach?: boolean;
+				watchdog?: boolean;
+				json?: boolean;
+			}) => {
+				const attach = opts.attach !== undefined ? opts.attach : !!process.stdout.isTTY;
+				await discoverCommand({ ...opts, attach });
+			},
+		);
+}

package/src/commands/doctor.ts

@@ -19,6 +19,7 @@ import { checkProviders } from "../doctor/providers.ts";
 import { checkStructure } from "../doctor/structure.ts";
 import type { DoctorCategory, DoctorCheck, DoctorCheckFn } from "../doctor/types.ts";
 import { checkVersion } from "../doctor/version.ts";
+import { checkWatchdog } from "../doctor/watchdog.ts";
 import { ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
 import { color } from "../logging/color.ts";
@@ -37,6 +38,7 @@ const ALL_CHECKS: Array<{ category: DoctorCategory; fn: DoctorCheckFn }> = [
 	{ category: "version", fn: checkVersion },
 	{ category: "ecosystem", fn: checkEcosystem },
 	{ category: "providers", fn: checkProviders },
+	{ category: "watchdog", fn: checkWatchdog },
 ];
 
 /**
@@ -168,7 +170,7 @@ export function createDoctorCommand(options?: DoctorCommandOptions): Command {
 		.option("--fix", "Attempt to auto-fix issues")
 		.addHelpText(
 			"after",
-			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers",
+			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers, watchdog",
 		)
 		.action(
 			async (opts: { json?: boolean; verbose?: boolean; category?: string; fix?: boolean }) => {