@os-eco/overstory-cli 0.6.8 → 0.6.10

package/src/agents/overlay.test.ts

@@ -4,7 +4,15 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AgentError } from "../errors.ts";
 import type { OverlayConfig, QualityGate } from "../types.ts";
-import { generateOverlay, isCanonicalRoot, writeOverlay } from "./overlay.ts";
+import {
+	formatQualityGatesBash,
+	formatQualityGatesCapabilities,
+	formatQualityGatesInline,
+	formatQualityGatesSteps,
+	generateOverlay,
+	isCanonicalRoot,
+	writeOverlay,
+} from "./overlay.ts";
 
 const SAMPLE_BASE_DEFINITION = `# Builder Agent
 
@@ -674,3 +682,150 @@ describe("isCanonicalRoot", () => {
 		expect(isCanonicalRoot(worktreePath, canonicalRoot)).toBe(false);
 	});
 });
+
+describe("formatQualityGatesInline", () => {
+	test("formats default gates as inline backtick list", () => {
+		const result = formatQualityGatesInline(undefined);
+		expect(result).toBe("`bun test`, `bun run lint`, `bun run typecheck`");
+	});
+
+	test("formats custom gates as inline backtick list", () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+			{ name: "Lint", command: "ruff check .", description: "no lint errors" },
+		];
+		const result = formatQualityGatesInline(gates);
+		expect(result).toBe("`pytest`, `ruff check .`");
+	});
+
+	test("falls back to defaults for empty array", () => {
+		const result = formatQualityGatesInline([]);
+		expect(result).toContain("`bun test`");
+	});
+});
+
+describe("formatQualityGatesSteps", () => {
+	test("formats default gates as numbered steps", () => {
+		const result = formatQualityGatesSteps(undefined);
+		expect(result).toContain("1. Run `bun test`");
+		expect(result).toContain("2. Run `bun run lint`");
+		expect(result).toContain("3. Run `bun run typecheck`");
+	});
+
+	test("formats custom gates as numbered steps", () => {
+		const gates: QualityGate[] = [
+			{ name: "Build", command: "cargo build", description: "compilation succeeds" },
+			{ name: "Test", command: "cargo test", description: "all tests pass" },
+		];
+		const result = formatQualityGatesSteps(gates);
+		expect(result).toBe(
+			"1. Run `cargo build` -- compilation succeeds.\n2. Run `cargo test` -- all tests pass.",
+		);
+	});
+});
+
+describe("formatQualityGatesBash", () => {
+	test("formats as fenced bash block with aligned comments", () => {
+		const result = formatQualityGatesBash(undefined);
+		expect(result).toContain("```bash");
+		expect(result).toContain("bun test");
+		expect(result).toContain("bun run lint");
+		expect(result).toContain("bun run typecheck");
+		expect(result).toContain("```");
+	});
+
+	test("capitalizes first letter of description in comments", () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+		];
+		const result = formatQualityGatesBash(gates);
+		expect(result).toContain("# All tests pass");
+	});
+
+	test("custom gates produce correct bash block", () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "npm test", description: "tests pass" },
+			{ name: "Lint", command: "npm run lint", description: "lint clean" },
+		];
+		const result = formatQualityGatesBash(gates);
+		expect(result).toContain("npm test");
+		expect(result).toContain("npm run lint");
+		expect(result).not.toContain("bun");
+	});
+});
+
+describe("formatQualityGatesCapabilities", () => {
+	test("formats as indented bullet list", () => {
+		const result = formatQualityGatesCapabilities(undefined);
+		expect(result).toContain("  - `bun test`");
+		expect(result).toContain("  - `bun run lint`");
+		expect(result).toContain("  - `bun run typecheck`");
+	});
+
+	test("custom gates produce correct capability bullets", () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "pytest", description: "run tests" },
+			{ name: "Type", command: "mypy .", description: "type check" },
+		];
+		const result = formatQualityGatesCapabilities(gates);
+		expect(result).toBe("  - `pytest` (run tests)\n  - `mypy .` (type check)");
+	});
+});
+
+describe("quality gate placeholders in base definitions", () => {
+	test("QUALITY_GATE_INLINE in base definition gets replaced", async () => {
+		const config = makeConfig({
+			baseDefinition: "Run {{QUALITY_GATE_INLINE}} before closing.",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("`bun test`, `bun run lint`, `bun run typecheck`");
+		expect(output).not.toContain("{{QUALITY_GATE_INLINE}}");
+	});
+
+	test("QUALITY_GATE_STEPS in base definition gets replaced", async () => {
+		const config = makeConfig({
+			baseDefinition: "## Steps\n{{QUALITY_GATE_STEPS}}",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("1. Run `bun test`");
+		expect(output).not.toContain("{{QUALITY_GATE_STEPS}}");
+	});
+
+	test("QUALITY_GATE_BASH in base definition gets replaced", async () => {
+		const config = makeConfig({
+			baseDefinition: "## Workflow\n{{QUALITY_GATE_BASH}}",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("```bash");
+		expect(output).toContain("bun test");
+		expect(output).not.toContain("{{QUALITY_GATE_BASH}}");
+	});
+
+	test("QUALITY_GATE_CAPABILITIES in base definition gets replaced", async () => {
+		const config = makeConfig({
+			baseDefinition: "## Caps\n{{QUALITY_GATE_CAPABILITIES}}",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("  - `bun test`");
+		expect(output).not.toContain("{{QUALITY_GATE_CAPABILITIES}}");
+	});
+
+	test("custom quality gates in base definition get custom commands", async () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+			{ name: "Lint", command: "ruff check .", description: "no lint errors" },
+		];
+		const config = makeConfig({
+			capability: "builder",
+			qualityGates: gates,
+			baseDefinition:
+				"Run {{QUALITY_GATE_INLINE}} before closing.\n{{QUALITY_GATE_BASH}}\n{{QUALITY_GATE_STEPS}}",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("`pytest`, `ruff check .`");
+		expect(output).toContain("pytest");
+		expect(output).toContain("ruff check .");
+		expect(output).not.toContain("bun test");
+		expect(output).not.toContain("{{QUALITY_GATE");
+	});
+});

package/src/agents/overlay.ts

@@ -1,5 +1,6 @@
 import { mkdir } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { DEFAULT_QUALITY_GATES } from "../config.ts";
 import { AgentError } from "../errors.ts";
 import type { OverlayConfig, QualityGate } from "../types.ts";
 
@@ -76,12 +77,65 @@ Your parent has already gathered the context you need.
  * a lightweight section that only tells them to close the issue and report.
  * Writable agents get the full quality gates (tests, lint, build, commit).
  */
-/** Default quality gates used when none are configured. */
-const DEFAULT_GATES: QualityGate[] = [
-	{ name: "Tests", command: "bun test", description: "all tests must pass" },
-	{ name: "Lint", command: "bun run lint", description: "zero errors" },
-	{ name: "Typecheck", command: "bun run typecheck", description: "no TypeScript errors" },
-];
+/**
+ * Resolve quality gates: use provided gates if non-empty, otherwise fall back to defaults.
+ */
+function resolveGates(gates: QualityGate[] | undefined): QualityGate[] {
+	return gates && gates.length > 0 ? gates : DEFAULT_QUALITY_GATES;
+}
+
+/**
+ * Format quality gates as inline backtick-delimited commands for prose sections.
+ * Example: `bun test`, `bun run lint`, `bun run typecheck`
+ */
+export function formatQualityGatesInline(gates: QualityGate[] | undefined): string {
+	return resolveGates(gates)
+		.map((g) => `\`${g.command}\``)
+		.join(", ");
+}
+
+/**
+ * Format quality gates as a numbered step list for completion-protocol sections.
+ * Example:
+ *   1. Run `bun test` -- all tests must pass.
+ *   2. Run `bun run lint` -- lint and formatting must be clean.
+ */
+export function formatQualityGatesSteps(gates: QualityGate[] | undefined): string {
+	return resolveGates(gates)
+		.map((g, i) => `${i + 1}. Run \`${g.command}\` -- ${g.description}.`)
+		.join("\n");
+}
+
+/**
+ * Format quality gates as a bash code block for workflow sections.
+ * Example:
+ *   ```bash
+ *   bun test              # All tests must pass
+ *   bun run lint          # Lint and format must be clean
+ *   ```
+ */
+export function formatQualityGatesBash(gates: QualityGate[] | undefined): string {
+	const resolved = resolveGates(gates);
+	// Pad commands to align comments
+	const maxLen = Math.max(...resolved.map((g) => g.command.length));
+	const lines = resolved.map((g) => {
+		const padded = g.command.padEnd(maxLen + 2);
+		return `${padded}# ${g.description[0]?.toUpperCase() ?? ""}${g.description.slice(1)}`;
+	});
+	return ["```bash", ...lines, "```"].join("\n");
+}
+
+/**
+ * Format quality gates as a bullet list for capabilities sections.
+ * Example:
+ *   - `bun test` (run tests)
+ *   - `bun run lint` (lint and format check via biome)
+ */
+export function formatQualityGatesCapabilities(gates: QualityGate[] | undefined): string {
+	return resolveGates(gates)
+		.map((g) => `  - \`${g.command}\` (${g.description})`)
+		.join("\n");
+}
 
 function formatQualityGates(config: OverlayConfig): string {
 	if (READ_ONLY_CAPABILITIES.has(config.capability)) {
@@ -99,7 +153,9 @@ function formatQualityGates(config: OverlayConfig): string {
 	}
 
 	const gates =
-		config.qualityGates && config.qualityGates.length > 0 ? config.qualityGates : DEFAULT_GATES;
+		config.qualityGates && config.qualityGates.length > 0
+			? config.qualityGates
+			: DEFAULT_QUALITY_GATES;
 
 	const gateLines = gates.map(
 		(gate, i) => `${i + 1}. **${gate.name}:** \`${gate.command}\` — ${gate.description}`,
@@ -220,6 +276,10 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 		"{{SPEC_INSTRUCTION}}": specInstruction,
 		"{{SKIP_SCOUT}}": config.skipScout ? SKIP_SCOUT_SECTION : "",
 		"{{BASE_DEFINITION}}": config.baseDefinition,
+		"{{QUALITY_GATE_INLINE}}": formatQualityGatesInline(config.qualityGates),
+		"{{QUALITY_GATE_STEPS}}": formatQualityGatesSteps(config.qualityGates),
+		"{{QUALITY_GATE_BASH}}": formatQualityGatesBash(config.qualityGates),
+		"{{QUALITY_GATE_CAPABILITIES}}": formatQualityGatesCapabilities(config.qualityGates),
 		"{{TRACKER_CLI}}": config.trackerCli ?? "bd",
 		"{{TRACKER_NAME}}": config.trackerName ?? "beads",
 	};

package/src/commands/agents.ts

@@ -8,7 +8,8 @@ import { join } from "node:path";
 import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
-import { color } from "../logging/color.ts";
+import { jsonOutput } from "../json.ts";
+import { accent, color } from "../logging/color.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { type AgentSession, SUPPORTED_CAPABILITIES } from "../types.ts";
 
@@ -166,10 +167,12 @@ function printAgents(agents: DiscoveredAgent[]): void {
 
 	for (const agent of agents) {
 		const icon = getStateIcon(agent.state);
-		w(`  ${icon} ${agent.agentName} [${agent.capability}]\n`);
-		w(`    State: ${agent.state} | Task: ${agent.taskId}\n`);
-		w(`    Branch: ${agent.branchName}\n`);
-		w(`    Parent: ${agent.parentAgent ?? "none"} | Depth: ${agent.depth}\n`);
+		w(`  ${icon} ${accent(agent.agentName)} [${agent.capability}]\n`);
+		w(`    State: ${agent.state} | Task: ${accent(agent.taskId)}\n`);
+		w(`    Branch: ${accent(agent.branchName)}\n`);
+		w(
+			`    Parent: ${agent.parentAgent ? accent(agent.parentAgent) : "none"} | Depth: ${agent.depth}\n`,
+		);
 
 		if (agent.fileScope.length === 0) {
 			w("    Files: (unrestricted)\n");
@@ -220,7 +223,7 @@ export function createAgentsCommand(): Command {
 			});
 
 			if (opts.json) {
-				process.stdout.write(`${JSON.stringify(agents, null, "\t")}\n`);
+				jsonOutput("agents discover", { agents });
 			} else {
 				printAgents(agents);
 			}

package/src/commands/clean.ts

@@ -25,6 +25,7 @@ import { join } from "node:path";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
+import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess } from "../logging/color.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
@@ -518,7 +519,7 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 
 	// Output
 	if (json) {
-		process.stdout.write(`${JSON.stringify(result, null, "\t")}\n`);
+		jsonOutput("clean", { ...result });
 		return;
 	}
 

package/src/commands/completions.test.ts

@@ -203,54 +203,42 @@ describe("completionsCommand", () => {
 	});
 
 	it("should exit with error for missing shell argument", () => {
-		const originalExit = process.exit;
+		const originalExitCode = process.exitCode;
 		const originalStderr = process.stderr.write;
-		let exitCode: number | undefined;
 		let stderrOutput = "";
 
-		process.exit = mock((code?: string | number | null | undefined) => {
-			exitCode = typeof code === "number" ? code : 1;
-			throw new Error("process.exit called");
-		}) as never;
-
 		process.stderr.write = mock((chunk: unknown) => {
 			stderrOutput += String(chunk);
 			return true;
 		});
 
 		try {
-			expect(() => completionsCommand([])).toThrow("process.exit called");
-			expect(exitCode).toBe(1);
+			completionsCommand([]);
+			expect(process.exitCode).toBe(1);
 			expect(stderrOutput).toContain("missing shell argument");
 		} finally {
-			process.exit = originalExit;
+			process.exitCode = originalExitCode;
 			process.stderr.write = originalStderr;
 		}
 	});
 
 	it("should exit with error for unknown shell", () => {
-		const originalExit = process.exit;
+		const originalExitCode = process.exitCode;
 		const originalStderr = process.stderr.write;
-		let exitCode: number | undefined;
 		let stderrOutput = "";
 
-		process.exit = mock((code?: string | number | null | undefined) => {
-			exitCode = typeof code === "number" ? code : 1;
-			throw new Error("process.exit called");
-		}) as never;
-
 		process.stderr.write = mock((chunk: unknown) => {
 			stderrOutput += String(chunk);
 			return true;
 		});
 
 		try {
-			expect(() => completionsCommand(["powershell"])).toThrow("process.exit called");
-			expect(exitCode).toBe(1);
+			completionsCommand(["powershell"]);
+			expect(process.exitCode).toBe(1);
 			expect(stderrOutput).toContain("unknown shell");
 			expect(stderrOutput).toContain("powershell");
 		} finally {
-			process.exit = originalExit;
+			process.exitCode = originalExitCode;
 			process.stderr.write = originalStderr;
 		}
 	});

package/src/commands/completions.ts

@@ -5,6 +5,7 @@
  */
 
 import { Command } from "commander";
+import { printError } from "../logging/color.ts";
 
 interface FlagDef {
 	name: string;
@@ -872,9 +873,9 @@ export function completionsCommand(args: string[]): void {
 	const shell = args[0];
 
 	if (!shell) {
-		process.stderr.write("Error: missing shell argument\n");
-		process.stderr.write("Usage: ov --completions <bash|zsh|fish>\n");
-		process.exit(1);
+		printError("missing shell argument", "Usage: ov --completions <bash|zsh|fish>");
+		process.exitCode = 1;
+		return;
 	}
 
 	let script: string;
@@ -889,9 +890,9 @@ export function completionsCommand(args: string[]): void {
 			script = generateFish();
 			break;
 		default:
-			process.stderr.write(`Error: unknown shell '${shell}'\n`);
-			process.stderr.write("Supported shells: bash, zsh, fish\n");
-			process.exit(1);
+			printError(`unknown shell '${shell}'`, "Supported shells: bash, zsh, fish");
+			process.exitCode = 1;
+			return;
 	}
 
 	process.stdout.write(script);

package/src/commands/coordinator.test.ts

@@ -592,6 +592,8 @@ describe("startCoordinator", () => {
 		}
 
 		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("coordinator start");
 		expect(parsed.agentName).toBe("coordinator");
 		expect(parsed.capability).toBe("coordinator");
 		expect(parsed.tmuxSession).toBe("overstory-test-project-coordinator");
@@ -761,6 +763,8 @@ describe("stopCoordinator", () => {
 
 		const output = await captureStdout(() => coordinatorCommand(["stop", "--json"], deps));
 		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("coordinator stop");
 		expect(parsed.stopped).toBe(true);
 		expect(parsed.sessionId).toBe(session.id);
 	});
@@ -930,6 +934,8 @@ describe("statusCoordinator", () => {
 		const { deps } = makeDeps();
 		const output = await captureStdout(() => coordinatorCommand(["status", "--json"], deps));
 		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("coordinator status");
 		expect(parsed.running).toBe(false);
 	});
 
@@ -951,6 +957,8 @@ describe("statusCoordinator", () => {
 
 		const output = await captureStdout(() => coordinatorCommand(["status", "--json"], deps));
 		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("coordinator status");
 		expect(parsed.running).toBe(true);
 		expect(parsed.sessionId).toBe(session.id);
 		expect(parsed.state).toBe("working");

package/src/commands/coordinator.ts

@@ -20,6 +20,7 @@ import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
 import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess, printWarning } from "../logging/color.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
@@ -462,7 +463,7 @@ async function startCoordinator(
 		};
 
 		if (json) {
-			process.stdout.write(`${JSON.stringify(output)}\n`);
+			jsonOutput("coordinator start", output);
 		} else {
 			printSuccess("Coordinator started");
 			process.stdout.write(`  Tmux:    ${tmuxSession}\n`);
@@ -564,9 +565,13 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
 		}
 
 		if (json) {
-			process.stdout.write(
-				`${JSON.stringify({ stopped: true, sessionId: session.id, watchdogStopped, monitorStopped, runCompleted })}\n`,
-			);
+			jsonOutput("coordinator stop", {
+				stopped: true,
+				sessionId: session.id,
+				watchdogStopped,
+				monitorStopped,
+				runCompleted,
+			});
 		} else {
 			printSuccess("Coordinator stopped", session.id);
 			if (watchdogStopped) {
@@ -629,9 +634,7 @@ async function statusCoordinator(
 			session.state === "zombie"
 		) {
 			if (json) {
-				process.stdout.write(
-					`${JSON.stringify({ running: false, watchdogRunning, monitorRunning })}\n`,
-				);
+				jsonOutput("coordinator status", { running: false, watchdogRunning, monitorRunning });
 			} else {
 				printHint("Coordinator is not running");
 				if (watchdogRunning) {
@@ -668,7 +671,7 @@ async function statusCoordinator(
 		};
 
 		if (json) {
-			process.stdout.write(`${JSON.stringify(status)}\n`);
+			jsonOutput("coordinator status", status);
 		} else {
 			const stateLabel = alive ? "running" : session.state;
 			process.stdout.write(`Coordinator: ${stateLabel}\n`);