@ag-eco/agentplate-cli 0.13.0

package/src/commands/metrics.test.ts

@@ -0,0 +1,458 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createMetricsStore } from "../metrics/store.ts";
+import { cleanupTempDir } from "../test-helpers.ts";
+import type { SessionMetrics } from "../types.ts";
+import { metricsCommand } from "./metrics.ts";
+
+/**
+ * Tests for `agentplate metrics` command.
+ *
+ * Uses real bun:sqlite (temp files) to test the metrics command end-to-end.
+ * Captures process.stdout.write to verify output formatting.
+ */
+
+describe("metricsCommand", () => {
+	let chunks: string[];
+	let originalWrite: typeof process.stdout.write;
+	let tempDir: string;
+	let originalCwd: string;
+
+	beforeEach(async () => {
+		// Spy on stdout
+		chunks = [];
+		originalWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		// Create temp dir with .agentplate/config.yaml structure
+		tempDir = await mkdtemp(join(tmpdir(), "metrics-test-"));
+		const agentplateDir = join(tempDir, ".agentplate");
+		await Bun.write(
+			join(agentplateDir, "config.yaml"),
+			`project:\n  name: test\n  root: ${tempDir}\n  canonicalBranch: main\n`,
+		);
+
+		// Change to temp dir so loadConfig() works
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+	});
+
+	afterEach(async () => {
+		process.stdout.write = originalWrite;
+		process.chdir(originalCwd);
+		await cleanupTempDir(tempDir);
+	});
+
+	function output(): string {
+		return chunks.join("");
+	}
+
+	function makeSession(overrides: Partial<SessionMetrics> = {}): SessionMetrics {
+		return {
+			agentName: "test-agent",
+			taskId: "bead-001",
+			capability: "builder",
+			startedAt: new Date(Date.now() - 120_000).toISOString(),
+			completedAt: new Date().toISOString(),
+			durationMs: 120_000,
+			exitCode: 0,
+			mergeResult: "clean-merge",
+			parentAgent: null,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheCreationTokens: 0,
+			estimatedCostUsd: null,
+			modelUsed: null,
+			runId: null,
+			...overrides,
+		};
+	}
+
+	test("--help flag shows help text", async () => {
+		await metricsCommand(["--help"]);
+		const out = output();
+
+		expect(out).toContain("metrics");
+		expect(out).toContain("--last <n>");
+		expect(out).toContain("--json");
+		expect(out).toContain("--help");
+	});
+
+	test("-h flag shows help text", async () => {
+		await metricsCommand(["-h"]);
+		const out = output();
+
+		expect(out).toContain("metrics");
+		expect(out).toContain("--last <n>");
+	});
+
+	test("no metrics DB returns empty message (text)", async () => {
+		await metricsCommand([]);
+		const out = output();
+
+		expect(out).toBe("No metrics data yet.\n");
+	});
+
+	test("no metrics DB returns empty JSON (--json)", async () => {
+		await metricsCommand(["--json"]);
+		const out = output();
+
+		const parsed = JSON.parse(out.trim()) as {
+			success: boolean;
+			command: string;
+			sessions: unknown[];
+		};
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("metrics");
+		expect(parsed.sessions).toEqual([]);
+	});
+
+	test("empty DB with no sessions", async () => {
+		// Create the DB but don't insert any sessions
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+		store.close();
+
+		await metricsCommand([]);
+		const out = output();
+
+		expect(out).toBe("No sessions recorded yet.\n");
+	});
+
+	test("basic output with sample sessions", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+
+		// Insert sample sessions
+		store.recordSession(
+			makeSession({
+				agentName: "builder-1",
+				capability: "builder",
+				durationMs: 45_000,
+			}),
+		);
+		store.recordSession(
+			makeSession({
+				agentName: "scout-1",
+				capability: "scout",
+				durationMs: 90_000,
+			}),
+		);
+		store.recordSession(
+			makeSession({
+				agentName: "builder-2",
+				capability: "builder",
+				durationMs: 30_000,
+				completedAt: null, // Still running
+			}),
+		);
+
+		store.close();
+
+		await metricsCommand([]);
+		const out = output();
+
+		// Check summary stats
+		expect(out).toContain("Session Metrics");
+		expect(out).toContain("Total sessions: 3");
+		expect(out).toContain("Completed: 2");
+		expect(out).toContain("Avg duration:");
+
+		// Check capability breakdown
+		expect(out).toContain("By capability:");
+		expect(out).toContain("builder:");
+		expect(out).toContain("scout:");
+
+		// Check recent sessions table
+		expect(out).toContain("Recent sessions:");
+		expect(out).toContain("builder-1");
+		expect(out).toContain("scout-1");
+		expect(out).toContain("builder-2");
+		expect(out).toContain("done");
+		expect(out).toContain("running");
+	});
+
+	test("--json flag returns structured JSON", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+
+		store.recordSession(
+			makeSession({
+				agentName: "test-builder",
+				taskId: "bead-123",
+				capability: "builder",
+			}),
+		);
+
+		store.close();
+
+		await metricsCommand(["--json"]);
+		const out = output();
+
+		const parsed = JSON.parse(out.trim()) as {
+			success: boolean;
+			command: string;
+			sessions: SessionMetrics[];
+		};
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("metrics");
+		expect(parsed.sessions).toHaveLength(1);
+		expect(parsed.sessions[0]?.agentName).toBe("test-builder");
+		expect(parsed.sessions[0]?.taskId).toBe("bead-123");
+		expect(parsed.sessions[0]?.capability).toBe("builder");
+	});
+
+	test("--last flag limits number of sessions", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+
+		// Insert 5 sessions
+		for (let i = 0; i < 5; i++) {
+			store.recordSession(
+				makeSession({
+					agentName: `agent-${i}`,
+					taskId: `bead-${i}`,
+					startedAt: new Date(Date.now() - (5 - i) * 1000).toISOString(),
+				}),
+			);
+		}
+
+		store.close();
+
+		await metricsCommand(["--last", "2"]);
+		const out = output();
+
+		// Should only show 2 sessions
+		expect(out).toContain("Total sessions: 2");
+	});
+
+	test("--last flag with --json limits sessions", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+
+		// Insert 5 sessions
+		for (let i = 0; i < 5; i++) {
+			store.recordSession(
+				makeSession({
+					agentName: `agent-${i}`,
+					taskId: `bead-${i}`,
+				}),
+			);
+		}
+
+		store.close();
+
+		await metricsCommand(["--last", "3", "--json"]);
+		const out = output();
+
+		const parsed = JSON.parse(out.trim()) as { sessions: SessionMetrics[] };
+		expect(parsed.sessions).toHaveLength(3);
+	});
+
+	test("merge tier distribution shows in output", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+
+		// Insert sessions with different merge tiers
+		store.recordSession(
+			makeSession({
+				agentName: "agent-1",
+				mergeResult: "clean-merge",
+			}),
+		);
+		store.recordSession(
+			makeSession({
+				agentName: "agent-2",
+				mergeResult: "clean-merge",
+			}),
+		);
+		store.recordSession(
+			makeSession({
+				agentName: "agent-3",
+				mergeResult: "auto-resolve",
+			}),
+		);
+		store.recordSession(
+			makeSession({
+				agentName: "agent-4",
+				mergeResult: "ai-resolve",
+			}),
+		);
+
+		store.close();
+
+		await metricsCommand([]);
+		const out = output();
+
+		// Check merge tier counts
+		expect(out).toContain("Merge tiers:");
+		expect(out).toContain("clean-merge: 2");
+		expect(out).toContain("auto-resolve: 1");
+		expect(out).toContain("ai-resolve: 1");
+	});
+
+	test("sessions without merge results don't show in tier distribution", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+
+		// Insert sessions: one with merge result, two without
+		store.recordSession(
+			makeSession({
+				agentName: "agent-1",
+				mergeResult: "clean-merge",
+			}),
+		);
+		store.recordSession(
+			makeSession({
+				agentName: "agent-2",
+				mergeResult: null,
+			}),
+		);
+		store.recordSession(
+			makeSession({
+				agentName: "agent-3",
+				mergeResult: null,
+				completedAt: null,
+			}),
+		);
+
+		store.close();
+
+		await metricsCommand([]);
+		const out = output();
+
+		expect(out).toContain("Merge tiers:");
+		expect(out).toContain("clean-merge: 1");
+		// Should not include sessions without merge results
+		expect(out).toContain("Total sessions: 3");
+		expect(out).toContain("Completed: 2");
+	});
+});
+
+describe("formatDuration helper", () => {
+	// We need to test the formatDuration helper directly, but it's not exported.
+	// We can infer its behavior from the output format.
+	// Alternatively, we can test it indirectly through the command output.
+
+	let chunks: string[];
+	let originalWrite: typeof process.stdout.write;
+	let tempDir: string;
+	let originalCwd: string;
+
+	beforeEach(async () => {
+		chunks = [];
+		originalWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		tempDir = await mkdtemp(join(tmpdir(), "metrics-test-"));
+		const agentplateDir = join(tempDir, ".agentplate");
+		await Bun.write(
+			join(agentplateDir, "config.yaml"),
+			`project:\n  name: test\n  root: ${tempDir}\n  canonicalBranch: main\n`,
+		);
+
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+	});
+
+	afterEach(async () => {
+		process.stdout.write = originalWrite;
+		process.chdir(originalCwd);
+		await cleanupTempDir(tempDir);
+	});
+
+	function output(): string {
+		return chunks.join("");
+	}
+
+	function makeSession(durationMs: number): SessionMetrics {
+		return {
+			agentName: "test-agent",
+			taskId: "bead-001",
+			capability: "builder",
+			startedAt: new Date(Date.now() - durationMs).toISOString(),
+			completedAt: new Date().toISOString(),
+			durationMs,
+			exitCode: 0,
+			mergeResult: "clean-merge",
+			parentAgent: null,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheCreationTokens: 0,
+			estimatedCostUsd: null,
+			modelUsed: null,
+			runId: null,
+		};
+	}
+
+	test("0ms formats as 0s", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+		store.recordSession(makeSession(0));
+		store.close();
+
+		await metricsCommand([]);
+		const out = output();
+
+		// Should contain "0s" somewhere in the output
+		expect(out).toContain("0s");
+	});
+
+	test("45000ms formats as 45s", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+		store.recordSession(makeSession(45_000));
+		store.close();
+
+		await metricsCommand([]);
+		const out = output();
+
+		expect(out).toContain("45s");
+	});
+
+	test("90000ms formats as 1m 30s", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+		store.recordSession(makeSession(90_000));
+		store.close();
+
+		await metricsCommand([]);
+		const out = output();
+
+		expect(out).toContain("1m 30s");
+	});
+
+	test("3720000ms formats as 1h 2m", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+		store.recordSession(makeSession(3_720_000));
+		store.close();
+
+		await metricsCommand([]);
+		const out = output();
+
+		expect(out).toContain("1h 2m");
+	});
+
+	test("3600000ms formats as 1h", async () => {
+		const dbPath = join(tempDir, ".agentplate", "metrics.db");
+		const store = createMetricsStore(dbPath);
+		store.recordSession(makeSession(3_600_000));
+		store.close();
+
+		await metricsCommand([]);
+		const out = output();
+
+		expect(out).toContain("1h");
+	});
+});

package/src/commands/metrics.ts

@@ -0,0 +1,129 @@
+/**
+ * CLI command: ap metrics [--last <n>] [--json]
+ *
+ * Shows metrics summary from SQLite store: session durations, success rates,
+ * merge tier distribution, agent utilization.
+ */
+
+import { join } from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../config.ts";
+import { jsonOutput } from "../json.ts";
+import { formatDuration } from "../logging/format.ts";
+import { renderHeader } from "../logging/theme.ts";
+import { createMetricsStore } from "../metrics/store.ts";
+
+interface MetricsOpts {
+	last?: string;
+	json?: boolean;
+}
+
+async function executeMetrics(opts: MetricsOpts): Promise<void> {
+	const limit = opts.last ? Number.parseInt(opts.last, 10) : 20;
+	const json = opts.json ?? false;
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const dbPath = join(config.project.root, ".agentplate", "metrics.db");
+
+	const dbFile = Bun.file(dbPath);
+	if (!(await dbFile.exists())) {
+		if (json) {
+			jsonOutput("metrics", { sessions: [] });
+		} else {
+			process.stdout.write("No metrics data yet.\n");
+		}
+		return;
+	}
+
+	const store = createMetricsStore(dbPath);
+
+	try {
+		const sessions = store.getRecentSessions(limit);
+
+		if (json) {
+			jsonOutput("metrics", { sessions } as Record<string, unknown>);
+			return;
+		}
+
+		if (sessions.length === 0) {
+			process.stdout.write("No sessions recorded yet.\n");
+			return;
+		}
+
+		process.stdout.write(`${renderHeader("Session Metrics")}\n\n`);
+
+		// Summary stats
+		const completed = sessions.filter((s) => s.completedAt !== null);
+		const avgDuration = store.getAverageDuration();
+
+		process.stdout.write(`Total sessions: ${sessions.length}\n`);
+		process.stdout.write(`Completed: ${completed.length}\n`);
+		process.stdout.write(`Avg duration: ${formatDuration(avgDuration)}\n\n`);
+
+		// Merge tier distribution
+		const tierCounts: Record<string, number> = {};
+		for (const s of completed) {
+			if (s.mergeResult) {
+				tierCounts[s.mergeResult] = (tierCounts[s.mergeResult] ?? 0) + 1;
+			}
+		}
+		if (Object.keys(tierCounts).length > 0) {
+			process.stdout.write("Merge tiers:\n");
+			for (const [tier, count] of Object.entries(tierCounts)) {
+				process.stdout.write(`  ${tier}: ${count}\n`);
+			}
+			process.stdout.write("\n");
+		}
+
+		// Capability breakdown
+		const capCounts: Record<string, number> = {};
+		for (const s of sessions) {
+			capCounts[s.capability] = (capCounts[s.capability] ?? 0) + 1;
+		}
+		process.stdout.write("By capability:\n");
+		for (const [cap, count] of Object.entries(capCounts)) {
+			const capAvg = store.getAverageDuration(cap);
+			process.stdout.write(`  ${cap}: ${count} sessions (avg ${formatDuration(capAvg)})\n`);
+		}
+		process.stdout.write("\n");
+
+		// Recent sessions table
+		process.stdout.write("Recent sessions:\n");
+		for (const s of sessions) {
+			const status = s.completedAt ? "done" : "running";
+			const duration = formatDuration(s.durationMs);
+			process.stdout.write(
+				`  ${s.agentName} [${s.capability}] ${s.taskId} | ${status} | ${duration}\n`,
+			);
+		}
+	} finally {
+		store.close();
+	}
+}
+
+export function createMetricsCommand(): Command {
+	return new Command("metrics")
+		.description("Show session metrics")
+		.option("--last <n>", "Number of recent sessions to show (default: 20)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: MetricsOpts) => {
+			await executeMetrics(opts);
+		});
+}
+
+export async function metricsCommand(args: string[]): Promise<void> {
+	const cmd = createMetricsCommand();
+	cmd.exitOverride();
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+		}
+		throw err;
+	}
+}