@agentplate/cli 1.0.0

package/src/commands/doctor.test.ts

@@ -0,0 +1,106 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_CONFIG, serializeConfig, setProjectRootOverride } from "../config.ts";
+import { setSecret } from "../secrets.ts";
+import { createDoctorCommand } from "./doctor.ts";
+
+let root: string;
+
+/** Run a doctor subcommand and capture its JSON stdout (unwrapping the envelope). */
+async function runDoctorJson(args: string[]): Promise<{ ok: boolean; checks: Check[] }> {
+	const original = process.stdout.write.bind(process.stdout);
+	let buffer = "";
+	process.stdout.write = ((chunk: unknown): boolean => {
+		buffer += typeof chunk === "string" ? chunk : String(chunk);
+		return true;
+	}) as typeof process.stdout.write;
+	try {
+		const program = createDoctorCommand();
+		program.exitOverride();
+		await program.parseAsync(["node", "doctor", ...args, "--json"]);
+	} finally {
+		process.stdout.write = original;
+	}
+	// jsonOutput wraps payloads as { ok: true, data: <payload> }.
+	const envelope = JSON.parse(buffer) as { ok: boolean; data: { ok: boolean; checks: Check[] } };
+	return envelope.data;
+}
+
+interface Check {
+	category: string;
+	name: string;
+	ok: boolean;
+	detail: string;
+}
+
+function initProject(deployTarget?: string): void {
+	mkdirSync(join(root, ".agentplate"), { recursive: true });
+	const config = structuredClone(DEFAULT_CONFIG);
+	config.project.name = "doctor-test";
+	config.project.root = root;
+	if (deployTarget) {
+		config.deploy.default = deployTarget;
+		config.deploy.targets[deployTarget] = {
+			settings: { registry: "ghcr.io/acme" },
+			secretEnv: { GHCR_TOKEN: { fromEnv: "GHCR_TOKEN" } },
+			environments: ["preview", "production"],
+		};
+	}
+	writeFileSync(join(root, ".agentplate", "config.yaml"), serializeConfig(config), "utf8");
+}
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-doctor-"));
+	setProjectRootOverride(root);
+});
+
+afterEach(() => {
+	setProjectRootOverride(null);
+	rmSync(root, { recursive: true, force: true });
+	delete process.env.GHCR_TOKEN;
+});
+
+describe("doctor providers category", () => {
+	test("reports missing credentials before a key is set", async () => {
+		initProject();
+		const result = await runDoctorJson(["--category", "providers"]);
+		const creds = result.checks.find((c) => c.name === "credentials");
+		expect(creds?.ok).toBe(false);
+	});
+
+	test("flips to ok once the provider key is present", async () => {
+		initProject();
+		setSecret(root, "ANTHROPIC_API_KEY", "sk-ant-doctor-test-value");
+		const result = await runDoctorJson(["--category", "providers"]);
+		const creds = result.checks.find((c) => c.name === "credentials");
+		expect(creds?.ok).toBe(true);
+	});
+});
+
+describe("doctor deploy category", () => {
+	test("reports a configured target with missing secrets", async () => {
+		initProject("docker-gha");
+		const result = await runDoctorJson(["--category", "deploy"]);
+		const target = result.checks.find((c) => c.name === "target docker-gha");
+		expect(target).toBeDefined();
+		expect(target?.ok).toBe(false);
+		expect(target?.detail).toContain("GHCR_TOKEN");
+	});
+
+	test("target is ok once its secret is present", async () => {
+		initProject("docker-gha");
+		setSecret(root, "GHCR_TOKEN", "ghp_doctor_test_token_value_1234");
+		const result = await runDoctorJson(["--category", "deploy"]);
+		const target = result.checks.find((c) => c.name === "target docker-gha");
+		expect(target?.ok).toBe(true);
+	});
+
+	test("default target check reflects config", async () => {
+		initProject("docker-gha");
+		const result = await runDoctorJson(["--category", "deploy"]);
+		const def = result.checks.find((c) => c.name === "default target");
+		expect(def?.detail).toBe("docker-gha");
+	});
+});

package/src/commands/doctor.ts

@@ -0,0 +1,208 @@
+/**
+ * `agentplate doctor` — health checks for the Agentplate setup.
+ *
+ * Checks are grouped into categories. Phase 0/1 ship `core` (toolchain + repo +
+ * initialization) and `providers` (active provider + credential presence, by env
+ * var name only — values are never read into the report). Later phases register
+ * more categories (databases, deploy, …).
+ */
+
+import { Command } from "commander";
+import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
+import { jsonOutput } from "../json.ts";
+import { brand, printError, printHint, printInfo, printSuccess } from "../logging/color.ts";
+import { getProviderSpec } from "../providers/registry.ts";
+import { hasSecret } from "../secrets.ts";
+import { commandOnPath, resolveArgv } from "../utils/detect.ts";
+
+interface DoctorCheck {
+	category: string;
+	name: string;
+	ok: boolean;
+	detail: string;
+}
+
+async function commandOutput(cmd: string, args: string[]): Promise<string | null> {
+	try {
+		const proc = Bun.spawn(resolveArgv([cmd, ...args]), { stdout: "pipe", stderr: "pipe" });
+		const code = await proc.exited;
+		if (code !== 0) return null;
+		return (await new Response(proc.stdout).text()).trim();
+	} catch {
+		return null;
+	}
+}
+
+async function coreChecks(root: string): Promise<DoctorCheck[]> {
+	const checks: DoctorCheck[] = [];
+	checks.push({ category: "core", name: "bun", ok: true, detail: `v${Bun.version}` });
+
+	const gitVersion = await commandOutput("git", ["--version"]);
+	checks.push({
+		category: "core",
+		name: "git",
+		ok: gitVersion !== null,
+		detail: gitVersion ?? "not found on PATH",
+	});
+
+	const isRepo = (await commandOutput("git", ["rev-parse", "--is-inside-work-tree"])) === "true";
+	checks.push({
+		category: "core",
+		name: "git repository",
+		ok: isRepo,
+		detail: isRepo ? root : "not inside a git repository",
+	});
+
+	const initialized = isInitialized(root);
+	checks.push({
+		category: "core",
+		name: "agentplate initialized",
+		ok: initialized,
+		detail: initialized ? `${root}/.agentplate` : "run `agentplate setup` to get started",
+	});
+	return checks;
+}
+
+async function providerChecks(root: string): Promise<DoctorCheck[]> {
+	if (!isInitialized(root)) {
+		return [
+			{
+				category: "providers",
+				name: "provider",
+				ok: false,
+				detail: "not initialized — run `agentplate setup`",
+			},
+		];
+	}
+	const config = loadConfig(root);
+	const providerId = config.activeProvider;
+	const providerConfig = config.providers[providerId];
+	const spec = getProviderSpec(providerId);
+	const checks: DoctorCheck[] = [];
+
+	checks.push({
+		category: "providers",
+		name: "active provider",
+		ok: providerConfig !== undefined,
+		detail: providerConfig
+			? `${spec?.label ?? providerId} (model: ${providerConfig.model ?? "unset"})`
+			: `"${providerId}" is not configured`,
+	});
+
+	// Auth-mode-aware credentials check. Legacy configs (no authMode) are treated
+	// as api-key when a token env var is present, else none.
+	const authMode =
+		providerConfig?.authMode ??
+		(spec?.keyless ? "none" : providerConfig?.authTokenEnv ? "api-key" : "none");
+	const envVar = providerConfig?.authTokenEnv ?? spec?.authEnvVar;
+
+	if (authMode === "none") {
+		checks.push({
+			category: "providers",
+			name: "credentials",
+			ok: true,
+			detail: "no credentials required (local provider)",
+		});
+	} else if (authMode === "subscription") {
+		const cli = spec?.subscriptionRuntime ?? config.runtime.default;
+		const installed = await commandOnPath(cli);
+		checks.push({
+			category: "providers",
+			name: "credentials",
+			ok: installed,
+			detail: installed
+				? `subscription via \`${cli}\` (ensure it is logged in)`
+				: `subscription auth needs \`${cli}\` on PATH — install/login first`,
+		});
+	} else if (envVar) {
+		const present = hasSecret(root, envVar);
+		checks.push({
+			category: "providers",
+			name: "credentials",
+			ok: present,
+			detail: present
+				? `${envVar} is set`
+				: `${envVar} not found (add it via \`agentplate setup\` or the environment)`,
+		});
+	}
+	return checks;
+}
+
+/**
+ * Deploy checks: report each configured deploy target and whether its required
+ * secrets are present (by env-var NAME only — values are never read here).
+ */
+function deployChecks(root: string): DoctorCheck[] {
+	if (!isInitialized(root)) return [];
+	const config = loadConfig(root);
+	const checks: DoctorCheck[] = [];
+	const defaultTarget = config.deploy.default;
+	checks.push({
+		category: "deploy",
+		name: "default target",
+		ok: true,
+		detail: defaultTarget || "(none — set with `agentplate target configure`)",
+	});
+	for (const [name, targetConfig] of Object.entries(config.deploy.targets)) {
+		const required = Object.values(targetConfig.secretEnv).map((b) => b.fromEnv);
+		const missing = required.filter((envVar) => !hasSecret(root, envVar));
+		checks.push({
+			category: "deploy",
+			name: `target ${name}`,
+			ok: missing.length === 0,
+			detail:
+				missing.length === 0
+					? `secrets present (${required.join(", ") || "none required"})`
+					: `missing secrets: ${missing.join(", ")}`,
+		});
+	}
+	return checks;
+}
+
+export function createDoctorCommand(): Command {
+	return new Command("doctor")
+		.description("Run health checks on the Agentplate setup")
+		.option("--category <name>", "run a single category: core | providers | deploy")
+		.option("--json", "output JSON")
+		.action(async (opts: { category?: string; json?: boolean }, command: Command) => {
+			const useJson = command.optsWithGlobals().json === true;
+			const root = findProjectRoot();
+			const category = opts.category;
+
+			const checks: DoctorCheck[] = [];
+			if (!category || category === "core") checks.push(...(await coreChecks(root)));
+			if (!category || category === "providers") checks.push(...(await providerChecks(root)));
+			if (!category || category === "deploy") checks.push(...deployChecks(root));
+
+			if (category && checks.length === 0) {
+				printError(`Unknown category "${category}". Try: core, providers, deploy`);
+				process.exitCode = 2;
+				return;
+			}
+
+			const allOk = checks.every((c) => c.ok);
+
+			if (useJson) {
+				jsonOutput({ ok: allOk, checks });
+				return;
+			}
+
+			printInfo(brand("agentplate doctor"));
+			let currentCategory = "";
+			for (const check of checks) {
+				if (check.category !== currentCategory) {
+					currentCategory = check.category;
+					printInfo(`\n${currentCategory}`);
+				}
+				if (check.ok) {
+					printSuccess(`${check.name}: ${check.detail}`);
+				} else {
+					printError(`${check.name}: ${check.detail}`);
+				}
+			}
+			if (!allOk) {
+				printHint("\nSome checks failed. Address the items above and re-run `agentplate doctor`.");
+				process.exitCode = 1;
+			}
+		});
+}

package/src/commands/init.ts

@@ -0,0 +1,71 @@
+/**
+ * `agentplate init` — non-interactive scaffold.
+ *
+ * Creates `.agentplate/` with a sensible auto-detected config and exits. For an
+ * interactive provider/runtime walkthrough, use `agentplate setup` instead.
+ */
+
+import { Command } from "commander";
+import { DEFAULT_CONFIG, findProjectRoot, isInitialized } from "../config.ts";
+import { jsonOutput } from "../json.ts";
+import { brand, printHint, printInfo, printSuccess, printWarning } from "../logging/color.ts";
+import { scaffoldAgentplateDir } from "../scaffold.ts";
+import type { AgentplateConfig } from "../types.ts";
+import { detectCanonicalBranch, detectDefaultRuntime, detectProjectName } from "../utils/detect.ts";
+
+export interface InitOptions {
+	yes?: boolean;
+	name?: string;
+	json?: boolean;
+}
+
+/** Build an auto-detected config for a fresh project (no secrets touched). */
+export async function buildInitialConfig(
+	root: string,
+	nameOverride?: string,
+): Promise<AgentplateConfig> {
+	const [name, canonicalBranch, runtime] = await Promise.all([
+		nameOverride ? Promise.resolve(nameOverride) : detectProjectName(root),
+		detectCanonicalBranch(root),
+		detectDefaultRuntime(),
+	]);
+	const config = structuredClone(DEFAULT_CONFIG);
+	config.project.name = name;
+	config.project.root = root;
+	config.project.canonicalBranch = canonicalBranch;
+	config.runtime.default = runtime;
+	return config;
+}
+
+export async function runInit(opts: InitOptions): Promise<AgentplateConfig> {
+	const root = findProjectRoot();
+	const already = isInitialized(root);
+	if (already && !opts.yes && !opts.json) {
+		printWarning(`Agentplate is already initialized at ${root}/.agentplate`);
+		printHint("Re-running will refresh config.yaml. Pass --yes to silence this notice.");
+	}
+	const config = await buildInitialConfig(root, opts.name);
+	scaffoldAgentplateDir(root, config);
+	return config;
+}
+
+export function createInitCommand(): Command {
+	return new Command("init")
+		.description("Initialize .agentplate/ with an auto-detected config (non-interactive)")
+		.option("-y, --yes", "skip the already-initialized notice")
+		.option("--name <name>", "set the project name (default: auto-detect)")
+		.option("--json", "output JSON")
+		.action(async (opts: InitOptions, command: Command) => {
+			const useJson = command.optsWithGlobals().json === true;
+			const config = await runInit({ ...opts, json: useJson });
+			if (useJson) {
+				jsonOutput({ initialized: true, root: config.project.root, config });
+				return;
+			}
+			printSuccess(`Initialized ${brand("Agentplate")} at ${config.project.root}/.agentplate`);
+			printInfo(`  project:  ${config.project.name}`);
+			printInfo(`  branch:   ${config.project.canonicalBranch}`);
+			printInfo(`  runtime:  ${config.runtime.default}`);
+			printHint("\nNext: run `agentplate setup` to choose your AI provider and add your API key.");
+		});
+}

package/src/commands/log.ts

@@ -0,0 +1,51 @@
+/**
+ * `agentplate log <event>` — record an agent lifecycle/tool event (hook target).
+ *
+ * Called by runtime hooks (e.g. PreToolUse/PostToolUse/Stop) to feed the event
+ * store that powers `agentplate status` and observability. Kept minimal in the
+ * basic core; session-end quality-gate scoring layers on in a later phase.
+ */
+
+import { Command } from "commander";
+import { findProjectRoot, isInitialized } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { createEventStore } from "../events/store.ts";
+import { jsonOutput } from "../json.ts";
+import { eventsDbPath } from "../paths.ts";
+
+export function createLogCommand(): Command {
+	return new Command("log")
+		.description("Record an agent event (hook target)")
+		.argument("<event>", "event type, e.g. tool-start | tool-end | session-end")
+		.option("--agent <name>", "agent name", "unknown")
+		.option("--tool <name>", "tool name (for tool events)")
+		.option("--detail <json>", "JSON detail blob")
+		.option("--run <id>", "run id")
+		.option("--json", "output JSON")
+		.action(
+			(
+				event: string,
+				opts: { agent: string; tool?: string; detail?: string; run?: string; json?: boolean },
+				command: Command,
+			) => {
+				const useJson = command.optsWithGlobals().json === true;
+				const root = findProjectRoot();
+				if (!isInitialized(root)) {
+					throw new ValidationError("Not initialized. Run `agentplate setup` first.");
+				}
+				const events = createEventStore(eventsDbPath(root));
+				try {
+					const record = events.record({
+						agentName: opts.agent,
+						runId: opts.run ?? null,
+						type: event,
+						tool: opts.tool ?? null,
+						detail: opts.detail ?? null,
+					});
+					if (useJson) jsonOutput(record);
+				} finally {
+					events.close();
+				}
+			},
+		);
+}

package/src/commands/mail.ts

@@ -0,0 +1,197 @@
+/**
+ * `agentplate mail` — inter-agent messaging over the SQLite mail bus.
+ *
+ * Subcommands: send, check, list, read, reply, purge. Used by agents (from
+ * inside worktrees, via `--project`) and by operators.
+ */
+
+import { Command } from "commander";
+import { findProjectRoot, isInitialized } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { muted, printInfo, printSuccess } from "../logging/color.ts";
+import { createMailClient } from "../mail/client.ts";
+import type { MailMessage, MailType } from "../types.ts";
+
+function requireInit(): string {
+	const root = findProjectRoot();
+	if (!isInitialized(root)) {
+		throw new ValidationError("Not initialized. Run `agentplate setup` first.");
+	}
+	return root;
+}
+
+function printMessage(m: MailMessage): void {
+	printInfo(`${m.read ? " " : "•"} [${m.type}] ${m.from} → ${m.to}: ${m.subject}`);
+	printInfo(muted(`    ${m.body.replace(/\n/g, "\n    ")}`));
+}
+
+function sendCommand(): Command {
+	return new Command("send")
+		.description("Send a message")
+		.requiredOption("--to <agent>", "recipient")
+		.requiredOption("--subject <text>", "subject")
+		.requiredOption("--body <text>", "body")
+		.option("--from <name>", "sender", "operator")
+		.option("--type <type>", "message type", "status")
+		.option("--priority <level>", "low|normal|high|urgent", "normal")
+		.option("--payload <json>", "structured JSON payload")
+		.option("--json", "output JSON")
+		.action(
+			(
+				opts: {
+					to: string;
+					subject: string;
+					body: string;
+					from: string;
+					type: string;
+					priority: string;
+					payload?: string;
+					json?: boolean;
+				},
+				command: Command,
+			) => {
+				const useJson = command.optsWithGlobals().json === true;
+				const root = requireInit();
+				const client = createMailClient(root);
+				try {
+					const message = client.send({
+						from: opts.from,
+						to: opts.to,
+						subject: opts.subject,
+						body: opts.body,
+						type: opts.type as MailType,
+						priority: opts.priority as MailMessage["priority"],
+						payload: opts.payload ?? null,
+					});
+					if (useJson) jsonOutput(message);
+					else printSuccess(`Sent ${message.id} to ${opts.to}`);
+				} finally {
+					client.close();
+				}
+			},
+		);
+}
+
+function checkCommand(): Command {
+	return new Command("check")
+		.description("Check an agent's inbox")
+		.requiredOption("--agent <name>", "agent whose inbox to check")
+		.option("--inject", "format unread for prompt injection and mark read")
+		.option("--json", "output JSON")
+		.action((opts: { agent: string; inject?: boolean; json?: boolean }, command: Command) => {
+			const useJson = command.optsWithGlobals().json === true;
+			const root = requireInit();
+			const client = createMailClient(root);
+			try {
+				if (opts.inject) {
+					const text = client.checkInject(opts.agent);
+					if (useJson) jsonOutput({ injected: text });
+					else printInfo(text || muted("(no new mail)"));
+					return;
+				}
+				const messages = client.check(opts.agent, { unreadOnly: true });
+				if (useJson) {
+					jsonOutput(messages);
+					return;
+				}
+				if (messages.length === 0) printInfo(muted("(no unread mail)"));
+				for (const m of messages) printMessage(m);
+			} finally {
+				client.close();
+			}
+		});
+}
+
+function listCommand(): Command {
+	return new Command("list")
+		.description("List messages")
+		.option("--from <name>")
+		.option("--to <name>")
+		.option("--unread", "only unread")
+		.option("--json", "output JSON")
+		.action(
+			(
+				opts: { from?: string; to?: string; unread?: boolean; json?: boolean },
+				command: Command,
+			) => {
+				const useJson = command.optsWithGlobals().json === true;
+				const root = requireInit();
+				const client = createMailClient(root);
+				try {
+					const messages = client.list({ from: opts.from, to: opts.to, unread: opts.unread });
+					if (useJson) jsonOutput(messages);
+					else for (const m of messages) printMessage(m);
+				} finally {
+					client.close();
+				}
+			},
+		);
+}
+
+function readCommand(): Command {
+	return new Command("read")
+		.description("Mark a message as read")
+		.argument("<id>", "message id")
+		.action((id: string) => {
+			const root = requireInit();
+			const client = createMailClient(root);
+			try {
+				client.markRead(id);
+				printSuccess(`Marked ${id} read`);
+			} finally {
+				client.close();
+			}
+		});
+}
+
+function replyCommand(): Command {
+	return new Command("reply")
+		.description("Reply to a message in the same thread")
+		.argument("<id>", "message id to reply to")
+		.requiredOption("--body <text>", "reply body")
+		.option("--from <name>", "sender", "operator")
+		.action((id: string, opts: { body: string; from: string }) => {
+			const root = requireInit();
+			const client = createMailClient(root);
+			try {
+				const message = client.reply(id, opts.body, opts.from);
+				printSuccess(`Replied (${message.id})`);
+			} finally {
+				client.close();
+			}
+		});
+}
+
+function purgeCommand(): Command {
+	return new Command("purge")
+		.description("Delete old messages")
+		.option("--all", "delete everything")
+		.option("--days <n>", "delete older than N days")
+		.option("--agent <name>", "delete for one agent")
+		.action((opts: { all?: boolean; days?: string; agent?: string }) => {
+			const root = requireInit();
+			const client = createMailClient(root);
+			try {
+				const count = client.purge({
+					all: opts.all,
+					olderThanDays: opts.days ? Number(opts.days) : undefined,
+					agent: opts.agent,
+				});
+				printSuccess(`Purged ${count} message(s)`);
+			} finally {
+				client.close();
+			}
+		});
+}
+
+export function createMailCommand(): Command {
+	return new Command("mail")
+		.description("Inter-agent messaging")
+		.addCommand(sendCommand())
+		.addCommand(checkCommand())
+		.addCommand(listCommand())
+		.addCommand(readCommand())
+		.addCommand(replyCommand())
+		.addCommand(purgeCommand());
+}