@ag-eco/agentplate-cli 0.13.0

package/src/commands/trace.ts

@@ -0,0 +1,205 @@
+/**
+ * CLI command: ap trace <target> [--json] [--since <ts>] [--until <ts>] [--limit <n>]
+ *
+ * Shows a chronological timeline of events for an agent or task.
+ * Target can be an agent name or a task ID (resolved to agent name via SessionStore).
+ */
+
+import { join } from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { createEventStore } from "../events/store.ts";
+import { jsonOutput } from "../json.ts";
+import { accent, color } from "../logging/color.ts";
+import {
+	buildEventDetail,
+	formatAbsoluteTime,
+	formatDate,
+	formatRelativeTime,
+} from "../logging/format.ts";
+import { eventLabel, renderHeader } from "../logging/theme.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import type { StoredEvent } from "../types.ts";
+
+/**
+ * Detect whether a target string looks like a task ID.
+ * Task IDs follow the pattern: word-alphanumeric (e.g., "agentplate-rj1k", "myproject-abc1").
+ */
+function looksLikeTaskId(target: string): boolean {
+	return /^[a-z][a-z0-9]*-[a-z0-9]{3,}$/i.test(target);
+}
+
+/**
+ * Print events as a formatted timeline with ANSI colors.
+ */
+function printTimeline(events: StoredEvent[], agentName: string, useAbsoluteTime: boolean): void {
+	const w = process.stdout.write.bind(process.stdout);
+
+	w(`${renderHeader(`Timeline for ${accent(agentName)}`)}\n`);
+
+	if (events.length === 0) {
+		w(`${color.dim("No events found.")}\n`);
+		return;
+	}
+
+	w(`${color.dim(`${events.length} event${events.length === 1 ? "" : "s"}`)}\n\n`);
+
+	let lastDate = "";
+
+	for (const event of events) {
+		// Print date separator when the date changes
+		const date = formatDate(event.createdAt);
+		if (date && date !== lastDate) {
+			if (lastDate !== "") {
+				w("\n");
+			}
+			w(`${color.dim(`--- ${date} ---`)}\n`);
+			lastDate = date;
+		}
+
+		const timeStr = useAbsoluteTime
+			? formatAbsoluteTime(event.createdAt)
+			: formatRelativeTime(event.createdAt);
+
+		const label = eventLabel(event.eventType);
+
+		const levelColorFn =
+			event.level === "error" ? color.red : event.level === "warn" ? color.yellow : null;
+		const applyLevel = (text: string) => (levelColorFn ? levelColorFn(text) : text);
+
+		const detail = buildEventDetail(event);
+		const detailSuffix = detail ? ` ${color.dim(detail)}` : "";
+
+		const agentLabel = event.agentName !== agentName ? ` ${color.dim(`[${event.agentName}]`)}` : "";
+
+		w(
+			`${color.dim(timeStr.padStart(10))} ` +
+				`${applyLevel(label.color(color.bold(label.full)))}` +
+				`${agentLabel}${detailSuffix}\n`,
+		);
+	}
+}
+
+interface TraceOpts {
+	json?: boolean;
+	since?: string;
+	until?: string;
+	limit?: string;
+}
+
+async function executeTrace(target: string, opts: TraceOpts): Promise<void> {
+	const json = opts.json ?? false;
+	const sinceStr = opts.since;
+	const untilStr = opts.until;
+	const limitStr = opts.limit;
+	const limit = limitStr ? Number.parseInt(limitStr, 10) : 100;
+
+	if (Number.isNaN(limit) || limit < 1) {
+		throw new ValidationError("--limit must be a positive integer", {
+			field: "limit",
+			value: limitStr,
+		});
+	}
+
+	// Validate timestamps if provided
+	if (sinceStr !== undefined && Number.isNaN(new Date(sinceStr).getTime())) {
+		throw new ValidationError("--since must be a valid ISO 8601 timestamp", {
+			field: "since",
+			value: sinceStr,
+		});
+	}
+	if (untilStr !== undefined && Number.isNaN(new Date(untilStr).getTime())) {
+		throw new ValidationError("--until must be a valid ISO 8601 timestamp", {
+			field: "until",
+			value: untilStr,
+		});
+	}
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const agentplateDir = join(config.project.root, ".agentplate");
+
+	// Resolve target to agent name
+	let agentName = target;
+
+	if (looksLikeTaskId(target)) {
+		// Try to resolve task ID to agent name via SessionStore
+		const { store: sessionStore } = openSessionStore(agentplateDir);
+		try {
+			const allSessions = sessionStore.getAll();
+			const matchingSession = allSessions.find((s) => s.taskId === target);
+			if (matchingSession) {
+				agentName = matchingSession.agentName;
+			} else {
+				// No session found for this task ID; treat it as an agent name anyway
+				// (the event query will return empty results if no events match)
+				agentName = target;
+			}
+		} finally {
+			sessionStore.close();
+		}
+	}
+
+	// Open event store and query events
+	const eventsDbPath = join(agentplateDir, "events.db");
+	const eventsFile = Bun.file(eventsDbPath);
+	if (!(await eventsFile.exists())) {
+		if (json) {
+			jsonOutput("trace", { events: [] });
+		} else {
+			process.stdout.write("No events data yet.\n");
+		}
+		return;
+	}
+
+	const eventStore = createEventStore(eventsDbPath);
+
+	try {
+		const events = eventStore.getByAgent(agentName, {
+			since: sinceStr,
+			until: untilStr,
+			limit,
+		});
+
+		if (json) {
+			jsonOutput("trace", { events });
+			return;
+		}
+
+		// Use absolute time if --since is specified, relative otherwise
+		const useAbsoluteTime = sinceStr !== undefined;
+		printTimeline(events, agentName, useAbsoluteTime);
+	} finally {
+		eventStore.close();
+	}
+}
+
+export function createTraceCommand(): Command {
+	return new Command("trace")
+		.description("Chronological event timeline for agent or task")
+		.argument("<target>", "Agent name or task ID")
+		.option("--json", "Output as JSON array of StoredEvent objects")
+		.option("--since <timestamp>", "Start time filter (ISO 8601)")
+		.option("--until <timestamp>", "End time filter (ISO 8601)")
+		.option("--limit <n>", "Max events to show (default: 100)")
+		.action(async (target: string, opts: TraceOpts) => {
+			await executeTrace(target, opts);
+		});
+}
+
+export async function traceCommand(args: string[]): Promise<void> {
+	const cmd = createTraceCommand();
+	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;
+	}
+}

package/src/commands/update.test.ts

@@ -0,0 +1,466 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import type { Spawner } from "./init.ts";
+import {
+	AGENTPLATE_GITIGNORE,
+	AGENTPLATE_README,
+	buildAgentManifest,
+	buildHooksJson,
+	initCommand,
+} from "./init.ts";
+import { executeUpdate } from "./update.ts";
+
+/**
+ * Tests for `ap update` — refresh .agentplate/ managed files.
+ *
+ * Uses real temp git repos. Suppresses stdout to keep test output clean.
+ * Requires a pre-initialized .agentplate/ directory (via initCommand).
+ */
+
+/** No-op spawner that treats all ecosystem tools as "not installed". */
+const noopSpawner: Spawner = async () => ({ exitCode: 1, stdout: "", stderr: "not found" });
+
+const AGENT_DEF_FILES = [
+	"ap-co-creation.md",
+	"builder.md",
+	"coordinator.md",
+	"lead.md",
+	"merger.md",
+	"monitor.md",
+	"orchestrator.md",
+	"reviewer.md",
+	"scout.md",
+];
+
+/** Resolve the source agents directory (same logic as init.ts). */
+const SOURCE_AGENTS_DIR = join(import.meta.dir, "..", "..", "agents");
+
+describe("executeUpdate: not initialized", () => {
+	let tempDir: string;
+	let originalCwd: string;
+	let originalWrite: typeof process.stdout.write;
+
+	beforeEach(async () => {
+		tempDir = await createTempGitRepo();
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+
+		originalWrite = process.stdout.write;
+		process.stdout.write = (() => true) as typeof process.stdout.write;
+	});
+
+	afterEach(async () => {
+		process.chdir(originalCwd);
+		process.stdout.write = originalWrite;
+		await cleanupTempDir(tempDir);
+	});
+
+	test("errors when .agentplate/config.yaml does not exist", async () => {
+		await expect(executeUpdate({})).rejects.toThrow("Not initialized");
+	});
+
+	test("error message hints to run ap init", async () => {
+		try {
+			await executeUpdate({});
+			expect.unreachable("Should have thrown");
+		} catch (err) {
+			expect((err as Error).message).toContain("ap init");
+		}
+	});
+});
+
+describe("executeUpdate: refresh all (no flags)", () => {
+	let tempDir: string;
+	let originalCwd: string;
+	let originalWrite: typeof process.stdout.write;
+
+	beforeEach(async () => {
+		tempDir = await createTempGitRepo();
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+
+		originalWrite = process.stdout.write;
+		process.stdout.write = (() => true) as typeof process.stdout.write;
+
+		// Initialize .agentplate/
+		await initCommand({ _spawner: noopSpawner });
+	});
+
+	afterEach(async () => {
+		process.chdir(originalCwd);
+		process.stdout.write = originalWrite;
+		await cleanupTempDir(tempDir);
+	});
+
+	test("refreshes all managed files when no flags given", async () => {
+		// Tamper with agent defs
+		const scoutPath = join(tempDir, ".agentplate", "agent-defs", "scout.md");
+		await Bun.write(scoutPath, "# tampered\n");
+
+		// Tamper with manifest
+		await Bun.write(join(tempDir, ".agentplate", "agent-manifest.json"), "{}");
+
+		// Tamper with hooks
+		await Bun.write(join(tempDir, ".agentplate", "hooks.json"), "{}");
+
+		// Tamper with gitignore
+		await Bun.write(join(tempDir, ".agentplate", ".gitignore"), "# old\n");
+
+		// Tamper with readme
+		await Bun.write(join(tempDir, ".agentplate", "README.md"), "# old\n");
+
+		await executeUpdate({});
+
+		// Verify all files restored
+		const scoutContent = await Bun.file(scoutPath).text();
+		const sourceScout = await Bun.file(join(SOURCE_AGENTS_DIR, "scout.md")).text();
+		expect(scoutContent).toBe(sourceScout);
+
+		const manifestContent = await Bun.file(
+			join(tempDir, ".agentplate", "agent-manifest.json"),
+		).text();
+		const expectedManifest = `${JSON.stringify(buildAgentManifest(), null, "\t")}\n`;
+		expect(manifestContent).toBe(expectedManifest);
+
+		const hooksContent = await Bun.file(join(tempDir, ".agentplate", "hooks.json")).text();
+		expect(hooksContent).toBe(buildHooksJson());
+
+		const gitignoreContent = await Bun.file(join(tempDir, ".agentplate", ".gitignore")).text();
+		expect(gitignoreContent).toBe(AGENTPLATE_GITIGNORE);
+
+		const readmeContent = await Bun.file(join(tempDir, ".agentplate", "README.md")).text();
+		expect(readmeContent).toBe(AGENTPLATE_README);
+	});
+
+	test("does not touch config.yaml", async () => {
+		const configPath = join(tempDir, ".agentplate", "config.yaml");
+		const originalConfig = await Bun.file(configPath).text();
+
+		await executeUpdate({});
+
+		const afterUpdate = await Bun.file(configPath).text();
+		expect(afterUpdate).toBe(originalConfig);
+	});
+
+	test("does not touch databases", async () => {
+		// Create fake database files
+		const mailDbPath = join(tempDir, ".agentplate", "mail.db");
+		const sessionsDbPath = join(tempDir, ".agentplate", "sessions.db");
+		await Bun.write(mailDbPath, "fake-mail-db");
+		await Bun.write(sessionsDbPath, "fake-sessions-db");
+
+		await executeUpdate({});
+
+		const mailDb = await Bun.file(mailDbPath).text();
+		expect(mailDb).toBe("fake-mail-db");
+
+		const sessionsDb = await Bun.file(sessionsDbPath).text();
+		expect(sessionsDb).toBe("fake-sessions-db");
+	});
+
+	test("handles already-up-to-date files gracefully (idempotent)", async () => {
+		// Run update twice — second should report nothing changed
+		await executeUpdate({});
+
+		// Capture JSON output of second run
+		let captured = "";
+		const restoreWrite = process.stdout.write;
+		process.stdout.write = ((chunk: unknown) => {
+			captured += String(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		await executeUpdate({ json: true });
+
+		process.stdout.write = restoreWrite;
+
+		const parsed = JSON.parse(captured.trim()) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+
+		const agentDefs = parsed.agentDefs as { updated: string[]; unchanged: string[] };
+		expect(agentDefs.updated).toHaveLength(0);
+		expect(agentDefs.unchanged.length).toBeGreaterThan(0);
+
+		expect(parsed.manifest).toEqual({ updated: false });
+		expect(parsed.hooks).toEqual({ updated: false });
+		expect(parsed.gitignore).toEqual({ updated: false });
+		expect(parsed.readme).toEqual({ updated: false });
+	});
+});
+
+describe("executeUpdate: granular flags", () => {
+	let tempDir: string;
+	let originalCwd: string;
+	let originalWrite: typeof process.stdout.write;
+
+	beforeEach(async () => {
+		tempDir = await createTempGitRepo();
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+
+		originalWrite = process.stdout.write;
+		process.stdout.write = (() => true) as typeof process.stdout.write;
+
+		await initCommand({ _spawner: noopSpawner });
+	});
+
+	afterEach(async () => {
+		process.chdir(originalCwd);
+		process.stdout.write = originalWrite;
+		await cleanupTempDir(tempDir);
+	});
+
+	test("--agents only refreshes agent-defs", async () => {
+		// Tamper with agent def and manifest
+		await Bun.write(join(tempDir, ".agentplate", "agent-defs", "scout.md"), "# tampered\n");
+		await Bun.write(join(tempDir, ".agentplate", "agent-manifest.json"), "{}");
+		await Bun.write(join(tempDir, ".agentplate", "hooks.json"), "{}");
+
+		await executeUpdate({ agents: true });
+
+		// Agent def should be restored
+		const scoutContent = await Bun.file(
+			join(tempDir, ".agentplate", "agent-defs", "scout.md"),
+		).text();
+		const sourceScout = await Bun.file(join(SOURCE_AGENTS_DIR, "scout.md")).text();
+		expect(scoutContent).toBe(sourceScout);
+
+		// Manifest should NOT be restored (--agents only)
+		const manifestContent = await Bun.file(
+			join(tempDir, ".agentplate", "agent-manifest.json"),
+		).text();
+		expect(manifestContent).toBe("{}");
+
+		// Hooks should NOT be restored (--agents only)
+		const hooksContent = await Bun.file(join(tempDir, ".agentplate", "hooks.json")).text();
+		expect(hooksContent).toBe("{}");
+	});
+
+	test("--manifest only refreshes agent-manifest.json", async () => {
+		await Bun.write(join(tempDir, ".agentplate", "agent-manifest.json"), "{}");
+		await Bun.write(join(tempDir, ".agentplate", "agent-defs", "scout.md"), "# tampered\n");
+
+		await executeUpdate({ manifest: true });
+
+		// Manifest should be restored
+		const manifestContent = await Bun.file(
+			join(tempDir, ".agentplate", "agent-manifest.json"),
+		).text();
+		const expectedManifest = `${JSON.stringify(buildAgentManifest(), null, "\t")}\n`;
+		expect(manifestContent).toBe(expectedManifest);
+
+		// Agent def should NOT be restored
+		const scoutContent = await Bun.file(
+			join(tempDir, ".agentplate", "agent-defs", "scout.md"),
+		).text();
+		expect(scoutContent).toBe("# tampered\n");
+	});
+
+	test("--hooks only refreshes hooks.json", async () => {
+		await Bun.write(join(tempDir, ".agentplate", "hooks.json"), "{}");
+		await Bun.write(join(tempDir, ".agentplate", "agent-manifest.json"), "{}");
+
+		await executeUpdate({ hooks: true });
+
+		// Hooks should be restored
+		const hooksContent = await Bun.file(join(tempDir, ".agentplate", "hooks.json")).text();
+		expect(hooksContent).toBe(buildHooksJson());
+
+		// Manifest should NOT be restored
+		const manifestContent = await Bun.file(
+			join(tempDir, ".agentplate", "agent-manifest.json"),
+		).text();
+		expect(manifestContent).toBe("{}");
+	});
+
+	test("granular flags do not refresh gitignore or readme", async () => {
+		await Bun.write(join(tempDir, ".agentplate", ".gitignore"), "# old\n");
+		await Bun.write(join(tempDir, ".agentplate", "README.md"), "# old\n");
+
+		await executeUpdate({ agents: true });
+
+		const gitignoreContent = await Bun.file(join(tempDir, ".agentplate", ".gitignore")).text();
+		expect(gitignoreContent).toBe("# old\n");
+
+		const readmeContent = await Bun.file(join(tempDir, ".agentplate", "README.md")).text();
+		expect(readmeContent).toBe("# old\n");
+	});
+});
+
+describe("executeUpdate: --dry-run", () => {
+	let tempDir: string;
+	let originalCwd: string;
+	let originalWrite: typeof process.stdout.write;
+
+	beforeEach(async () => {
+		tempDir = await createTempGitRepo();
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+
+		originalWrite = process.stdout.write;
+		process.stdout.write = (() => true) as typeof process.stdout.write;
+
+		await initCommand({ _spawner: noopSpawner });
+	});
+
+	afterEach(async () => {
+		process.chdir(originalCwd);
+		process.stdout.write = originalWrite;
+		await cleanupTempDir(tempDir);
+	});
+
+	test("reports changes without writing files", async () => {
+		// Tamper with files
+		await Bun.write(join(tempDir, ".agentplate", "agent-defs", "scout.md"), "# tampered\n");
+		await Bun.write(join(tempDir, ".agentplate", "agent-manifest.json"), "{}");
+
+		let captured = "";
+		const restoreWrite = process.stdout.write;
+		process.stdout.write = ((chunk: unknown) => {
+			captured += String(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		await executeUpdate({ dryRun: true, json: true });
+
+		process.stdout.write = restoreWrite;
+
+		const parsed = JSON.parse(captured.trim()) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.dryRun).toBe(true);
+
+		const agentDefs = parsed.agentDefs as { updated: string[]; unchanged: string[] };
+		expect(agentDefs.updated).toContain("scout.md");
+
+		expect(parsed.manifest).toEqual({ updated: true });
+
+		// Verify files were NOT actually modified
+		const scoutContent = await Bun.file(
+			join(tempDir, ".agentplate", "agent-defs", "scout.md"),
+		).text();
+		expect(scoutContent).toBe("# tampered\n");
+
+		const manifestContent = await Bun.file(
+			join(tempDir, ".agentplate", "agent-manifest.json"),
+		).text();
+		expect(manifestContent).toBe("{}");
+	});
+});
+
+describe("executeUpdate: --json output", () => {
+	let tempDir: string;
+	let originalCwd: string;
+	let originalWrite: typeof process.stdout.write;
+
+	beforeEach(async () => {
+		tempDir = await createTempGitRepo();
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+
+		originalWrite = process.stdout.write;
+		process.stdout.write = (() => true) as typeof process.stdout.write;
+
+		await initCommand({ _spawner: noopSpawner });
+	});
+
+	afterEach(async () => {
+		process.chdir(originalCwd);
+		process.stdout.write = originalWrite;
+		await cleanupTempDir(tempDir);
+	});
+
+	test("outputs correct JSON envelope", async () => {
+		let captured = "";
+		const restoreWrite = process.stdout.write;
+		process.stdout.write = ((chunk: unknown) => {
+			captured += String(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		await executeUpdate({ json: true });
+
+		process.stdout.write = restoreWrite;
+
+		const parsed = JSON.parse(captured.trim()) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("update");
+		expect(parsed.dryRun).toBe(false);
+		expect(parsed.agentDefs).toBeDefined();
+		expect(parsed.manifest).toBeDefined();
+		expect(parsed.hooks).toBeDefined();
+		expect(parsed.gitignore).toBeDefined();
+		expect(parsed.readme).toBeDefined();
+	});
+
+	test("JSON envelope includes updated file lists", async () => {
+		// Tamper with scout
+		await Bun.write(join(tempDir, ".agentplate", "agent-defs", "scout.md"), "# tampered\n");
+
+		let captured = "";
+		const restoreWrite = process.stdout.write;
+		process.stdout.write = ((chunk: unknown) => {
+			captured += String(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		await executeUpdate({ json: true });
+
+		process.stdout.write = restoreWrite;
+
+		const parsed = JSON.parse(captured.trim()) as Record<string, unknown>;
+		const agentDefs = parsed.agentDefs as { updated: string[]; unchanged: string[] };
+		expect(agentDefs.updated).toContain("scout.md");
+		expect(agentDefs.unchanged.length).toBeGreaterThan(0);
+	});
+});
+
+describe("executeUpdate: agent def exclusions", () => {
+	let tempDir: string;
+	let originalCwd: string;
+	let originalWrite: typeof process.stdout.write;
+
+	beforeEach(async () => {
+		tempDir = await createTempGitRepo();
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+
+		originalWrite = process.stdout.write;
+		process.stdout.write = (() => true) as typeof process.stdout.write;
+
+		await initCommand({ _spawner: noopSpawner });
+	});
+
+	afterEach(async () => {
+		process.chdir(originalCwd);
+		process.stdout.write = originalWrite;
+		await cleanupTempDir(tempDir);
+	});
+
+	test("does not deploy supervisor.md (deprecated)", async () => {
+		await executeUpdate({ agents: true });
+
+		const agentDefsDir = join(tempDir, ".agentplate", "agent-defs");
+		const files = await readdir(agentDefsDir);
+		expect(files).not.toContain("supervisor.md");
+	});
+
+	test("deploys all non-deprecated agent defs", async () => {
+		// Delete all agent defs first
+		for (const f of AGENT_DEF_FILES) {
+			try {
+				const { unlink } = await import("node:fs/promises");
+				await unlink(join(tempDir, ".agentplate", "agent-defs", f));
+			} catch {
+				// May not exist
+			}
+		}
+
+		await executeUpdate({ agents: true });
+
+		const agentDefsDir = join(tempDir, ".agentplate", "agent-defs");
+		const files = (await readdir(agentDefsDir)).filter((f) => f.endsWith(".md")).sort();
+		expect(files).toEqual(AGENT_DEF_FILES);
+	});
+});