@ag-eco/agentplate-cli 0.13.0

package/src/insights/quality-gates.test.ts

@@ -0,0 +1,141 @@
+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 {
+	cleanupTempDir,
+	commitFile,
+	createTempGitRepo,
+	getDefaultBranch,
+} from "../test-helpers.ts";
+import type { QualityGate } from "../types.ts";
+import { hasWorkToVerify, runQualityGates } from "./quality-gates.ts";
+
+describe("runQualityGates", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "qg-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("returns null when gates list is empty", async () => {
+		const result = await runQualityGates([], tempDir);
+		expect(result).toBeNull();
+	});
+
+	test("status is 'success' when all gates exit 0", async () => {
+		const gates: QualityGate[] = [
+			{ name: "True", command: "true", description: "always passes" },
+			{ name: "Echo", command: "echo ok", description: "always passes" },
+		];
+		const result = await runQualityGates(gates, tempDir);
+		expect(result).not.toBeNull();
+		expect(result?.status).toBe("success");
+		expect(result?.results).toHaveLength(2);
+		expect(result?.results.every((r) => r.passed)).toBe(true);
+	});
+
+	test("status is 'failure' when no gates exit 0", async () => {
+		const gates: QualityGate[] = [
+			{ name: "False1", command: "false", description: "always fails" },
+			{ name: "False2", command: "false", description: "always fails" },
+		];
+		const result = await runQualityGates(gates, tempDir);
+		expect(result).not.toBeNull();
+		expect(result?.status).toBe("failure");
+		expect(result?.results.every((r) => !r.passed)).toBe(true);
+	});
+
+	test("status is 'partial' on mixed exit codes", async () => {
+		const gates: QualityGate[] = [
+			{ name: "Pass", command: "true", description: "passes" },
+			{ name: "Fail", command: "false", description: "fails" },
+		];
+		const result = await runQualityGates(gates, tempDir);
+		expect(result).not.toBeNull();
+		expect(result?.status).toBe("partial");
+		expect(result?.results.filter((r) => r.passed)).toHaveLength(1);
+		expect(result?.results.filter((r) => !r.passed)).toHaveLength(1);
+	});
+
+	test("a gate that hangs past the timeout is treated as failed", async () => {
+		const gates: QualityGate[] = [
+			{ name: "Sleeper", command: "sleep 5", description: "intentionally slow" },
+		];
+		const result = await runQualityGates(gates, tempDir, { timeoutMs: 200 });
+		expect(result).not.toBeNull();
+		expect(result?.status).toBe("failure");
+		expect(result?.results[0]?.passed).toBe(false);
+		expect(result?.results[0]?.exitCode).toBe(-1);
+		// Should return well before the 5s the gate would otherwise take
+		expect(result?.totalDurationMs).toBeLessThan(2_000);
+	});
+
+	test("captures per-gate duration and exit code", async () => {
+		const gates: QualityGate[] = [{ name: "Quick", command: "true", description: "passes fast" }];
+		const result = await runQualityGates(gates, tempDir);
+		expect(result?.results[0]?.exitCode).toBe(0);
+		expect(result?.results[0]?.durationMs).toBeGreaterThanOrEqual(0);
+		expect(result?.totalDurationMs).toBeGreaterThanOrEqual(result?.results[0]?.durationMs ?? 0);
+	});
+});
+
+describe("hasWorkToVerify", () => {
+	let repoDir: string;
+
+	beforeEach(async () => {
+		repoDir = await createTempGitRepo();
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(repoDir);
+	});
+
+	test("returns false on a fresh repo with no commits past base and a clean tree", async () => {
+		const branch = await getDefaultBranch(repoDir);
+		const result = await hasWorkToVerify(repoDir, branch);
+		expect(result).toBe(false);
+	});
+
+	test("returns true when worktree has uncommitted changes", async () => {
+		const branch = await getDefaultBranch(repoDir);
+		await Bun.write(join(repoDir, "dirty.txt"), "uncommitted content");
+		const result = await hasWorkToVerify(repoDir, branch);
+		expect(result).toBe(true);
+	});
+
+	test("returns true when there are commits past base", async () => {
+		// Pin a "base-ref" branch at the initial commit, then add a new commit
+		// on the working branch so HEAD is one commit ahead of base-ref.
+		const proc = Bun.spawn(["git", "branch", "base-ref", "HEAD"], { cwd: repoDir });
+		await proc.exited;
+		await commitFile(repoDir, "new-file.txt", "second commit", "second commit");
+
+		const result = await hasWorkToVerify(repoDir, "base-ref");
+		expect(result).toBe(true);
+	});
+
+	test("returns true when base ref cannot be resolved (fail open)", async () => {
+		const result = await hasWorkToVerify(repoDir, "definitely-not-a-real-ref");
+		expect(result).toBe(true);
+	});
+
+	test("defaults baseRef to 'main' when not provided", async () => {
+		// On a clean repo with default branch 'main' the function should resolve
+		// 'main' successfully and report no work to verify.
+		const branch = await getDefaultBranch(repoDir);
+		// Skip this assertion if the default branch isn't 'main' (e.g., master on
+		// some CI runners) — fall back to passing the explicit branch.
+		if (branch === "main") {
+			const result = await hasWorkToVerify(repoDir);
+			expect(result).toBe(false);
+		} else {
+			const result = await hasWorkToVerify(repoDir, branch);
+			expect(result).toBe(false);
+		}
+	});
+});

package/src/insights/quality-gates.ts

@@ -0,0 +1,156 @@
+/**
+ * Quality-gate runner used at session-end to determine the outcome status
+ * threaded into loam record writes (success / partial / failure).
+ *
+ * Used by `src/commands/log.ts` session-end handler. Cheap precheck via
+ * `hasWorkToVerify()` lets read-only agents (scout/reviewer) skip gate
+ * execution entirely when no commits or uncommitted changes exist.
+ */
+
+import type { QualityGate } from "../types.ts";
+
+export interface QualityGateResult {
+	name: string;
+	command: string;
+	passed: boolean;
+	durationMs: number;
+	exitCode: number;
+}
+
+export interface QualityGateOutcome {
+	status: "success" | "partial" | "failure";
+	results: QualityGateResult[];
+	totalDurationMs: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+/**
+ * Run each configured quality gate against `cwd` and aggregate the result.
+ *
+ * Returns null when `gates` is empty.
+ *
+ * - all passed -> "success"
+ * - none passed -> "failure"
+ * - mixed -> "partial"
+ */
+export async function runQualityGates(
+	gates: QualityGate[],
+	cwd: string,
+	options?: { timeoutMs?: number },
+): Promise<QualityGateOutcome | null> {
+	if (gates.length === 0) return null;
+
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const results: QualityGateResult[] = [];
+	const totalStart = Date.now();
+
+	for (const gate of gates) {
+		const argv = gate.command.split(/\s+/).filter((s) => s.length > 0);
+		if (argv.length === 0) {
+			results.push({
+				name: gate.name,
+				command: gate.command,
+				passed: false,
+				durationMs: 0,
+				exitCode: -1,
+			});
+			continue;
+		}
+
+		const start = Date.now();
+		let proc: ReturnType<typeof Bun.spawn> | undefined;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let timedOut = false;
+		try {
+			proc = Bun.spawn(argv, {
+				cwd,
+				stdout: "ignore",
+				stderr: "ignore",
+			});
+			timer = setTimeout(() => {
+				timedOut = true;
+				try {
+					proc?.kill();
+				} catch {
+					// best-effort kill
+				}
+			}, timeoutMs);
+			const exitCode = await proc.exited;
+			const durationMs = Date.now() - start;
+			results.push({
+				name: gate.name,
+				command: gate.command,
+				passed: !timedOut && exitCode === 0,
+				durationMs,
+				exitCode: timedOut ? -1 : exitCode,
+			});
+		} catch {
+			results.push({
+				name: gate.name,
+				command: gate.command,
+				passed: false,
+				durationMs: Date.now() - start,
+				exitCode: -1,
+			});
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+
+	const passedCount = results.filter((r) => r.passed).length;
+	let status: "success" | "partial" | "failure";
+	if (passedCount === results.length) {
+		status = "success";
+	} else if (passedCount === 0) {
+		status = "failure";
+	} else {
+		status = "partial";
+	}
+
+	return {
+		status,
+		results,
+		totalDurationMs: Date.now() - totalStart,
+	};
+}
+
+/**
+ * Cheap precheck: returns true when the worktree has commits beyond `baseRef`
+ * or any uncommitted modifications. Used to skip gate execution for read-only
+ * agents that produced no work.
+ *
+ * Fails open: if HEAD or `baseRef` cannot be resolved, returns true so that
+ * gates still run rather than silently skipping.
+ */
+export async function hasWorkToVerify(cwd: string, baseRef = "main"): Promise<boolean> {
+	const head = await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+	const base = await runGit(cwd, ["rev-parse", "--verify", baseRef]);
+	if (head.exitCode !== 0 || base.exitCode !== 0) return true;
+
+	const ahead = await runGit(cwd, ["rev-list", "--count", `${baseRef}..HEAD`]);
+	if (ahead.exitCode === 0) {
+		const count = Number.parseInt(ahead.stdout.trim(), 10);
+		if (Number.isFinite(count) && count > 0) return true;
+	}
+
+	const status = await runGit(cwd, ["status", "--porcelain"]);
+	if (status.exitCode === 0 && status.stdout.trim().length > 0) return true;
+
+	return false;
+}
+
+async function runGit(cwd: string, args: string[]): Promise<{ stdout: string; exitCode: number }> {
+	try {
+		const proc = Bun.spawn(["git", ...args], {
+			cwd,
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		const stdout = await new Response(proc.stdout).text();
+		const exitCode = await proc.exited;
+		return { stdout, exitCode };
+	} catch {
+		return { stdout: "", exitCode: -1 };
+	}
+}

package/src/json.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { jsonError, jsonOutput } from "./json.ts";
+
+describe("jsonOutput", () => {
+	let written: string[] = [];
+	let writeSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		written = [];
+		writeSpy = spyOn(process.stdout, "write").mockImplementation((chunk: unknown) => {
+			written.push(String(chunk));
+			return true;
+		});
+	});
+
+	afterEach(() => {
+		writeSpy.mockRestore();
+	});
+
+	test("writes success envelope to stdout", () => {
+		jsonOutput("status", { agents: [] });
+		expect(written).toEqual(['{"success":true,"command":"status","agents":[]}\n']);
+	});
+
+	test("spreads data properties into top-level envelope", () => {
+		jsonOutput("agents discover", { count: 3, names: ["a", "b", "c"] });
+		const parsed = JSON.parse(written[0] ?? "{}");
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("agents discover");
+		expect(parsed.count).toBe(3);
+		expect(parsed.names).toEqual(["a", "b", "c"]);
+		// Data is NOT nested under a "data" key
+		expect(parsed.data).toBeUndefined();
+	});
+
+	test("produces single-line JSON (no pretty printing)", () => {
+		jsonOutput("status", { agents: [] });
+		const line = written[0] ?? "";
+		expect(line).not.toContain("\n\t");
+		expect(line.trimEnd()).toBe('{"success":true,"command":"status","agents":[]}');
+	});
+});
+
+describe("jsonError", () => {
+	let written: string[] = [];
+	let writeSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		written = [];
+		writeSpy = spyOn(process.stdout, "write").mockImplementation((chunk: unknown) => {
+			written.push(String(chunk));
+			return true;
+		});
+	});
+
+	afterEach(() => {
+		writeSpy.mockRestore();
+	});
+
+	test("writes error envelope to stdout", () => {
+		jsonError("status", "no config");
+		expect(written).toEqual(['{"success":false,"command":"status","error":"no config"}\n']);
+	});
+
+	test("writes to stdout not stderr", () => {
+		const stderrSpy = spyOn(process.stderr, "write").mockImplementation(() => true);
+		jsonError("mail send", "connection failed");
+		expect(written.length).toBe(1);
+		expect(stderrSpy).not.toHaveBeenCalled();
+		stderrSpy.mockRestore();
+	});
+});

package/src/json.ts

@@ -0,0 +1,53 @@
+/**
+ * Standard JSON envelope for CLI output.
+ *
+ * Success: { success: true, command: "<name>", ...data }
+ * Error: { success: false, command: "<name>", error: "<message>" }
+ *
+ * Matches the ecosystem convention used by loam, sprout, and trellis.
+ */
+
+/**
+ * Write a JSON success envelope to stdout.
+ * Spreads data properties into the top-level envelope.
+ */
+export function jsonOutput(command: string, data: Record<string, unknown>): void {
+	process.stdout.write(`${JSON.stringify({ success: true, command, ...data })}\n`);
+}
+
+/**
+ * Write a JSON error envelope to stdout (not stderr).
+ * With --json, errors go to stdout inside the envelope per cli-standards.md.
+ */
+export function jsonError(command: string, error: string): void {
+	process.stdout.write(`${JSON.stringify({ success: false, command, error })}\n`);
+}
+
+/**
+ * Build a JSON success Response for HTTP API handlers.
+ * Envelope: { success: true, command: 'serve', data, nextCursor? }
+ */
+export function apiJson(
+	data: unknown,
+	init?: { status?: number; nextCursor?: string | null },
+): Response {
+	const envelope: Record<string, unknown> = { success: true, command: "serve", data };
+	if (init?.nextCursor != null) {
+		envelope.nextCursor = init.nextCursor;
+	}
+	return new Response(JSON.stringify(envelope), {
+		status: init?.status ?? 200,
+		headers: { "Content-Type": "application/json" },
+	});
+}
+
+/**
+ * Build a JSON error Response for HTTP API handlers.
+ * Envelope: { success: false, command: 'serve', error }
+ */
+export function apiError(message: string, status: number): Response {
+	return new Response(JSON.stringify({ success: false, command: "serve", error: message }), {
+		status,
+		headers: { "Content-Type": "application/json" },
+	});
+}