@agentplate/cli 1.0.0

package/src/commands/merge.ts

@@ -0,0 +1,127 @@
+/**
+ * `agentplate merge` — fold agent branches into the canonical (or chosen) branch.
+ *
+ * Supports a single `--branch`, `--all` completed agent branches, and a
+ * side-effect-free `--dry-run` that predicts the resolution tier and conflicts.
+ * Merges run under a sentinel lock so two `merge` invocations never race on the
+ * same target.
+ */
+
+import { Command } from "commander";
+import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { printError, printInfo, printSuccess } from "../logging/color.ts";
+import { withMergeLock } from "../merge/lock.ts";
+import { createMergeQueue } from "../merge/queue.ts";
+import { mergeBranch, predictMerge } from "../merge/resolver.ts";
+import { mergeDbPath, sessionsDbPath } from "../paths.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import type { AgentSession, MergeResult } from "../types.ts";
+
+export function createMergeCommand(): Command {
+	return new Command("merge")
+		.description("Merge agent branches into the canonical branch")
+		.option("--branch <name>", "merge a specific branch")
+		.option("--all", "merge all completed agent branches")
+		.option("--into <branch>", "target branch (default: project canonical branch)")
+		.option("--dry-run", "predict conflicts/tier without merging")
+		.option("--json", "output JSON")
+		.action(
+			async (
+				opts: {
+					branch?: string;
+					all?: boolean;
+					into?: string;
+					dryRun?: boolean;
+					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 config = loadConfig(root);
+				const target = opts.into ?? config.project.canonicalBranch;
+
+				const store = createSessionStore(sessionsDbPath(root));
+				let branches: Array<{ branch: string; session?: AgentSession }> = [];
+				try {
+					if (opts.branch) {
+						const session = store.listSessions().find((s) => s.branchName === opts.branch);
+						branches = [{ branch: opts.branch, session }];
+					} else if (opts.all) {
+						branches = store
+							.listSessions({ state: "completed" })
+							.map((s) => ({ branch: s.branchName, session: s }));
+					} else {
+						throw new ValidationError("Pass --branch <name> or --all.");
+					}
+				} finally {
+					store.close();
+				}
+
+				if (branches.length === 0) {
+					if (useJson) jsonOutput({ merged: [], message: "no branches to merge" });
+					else printInfo("No branches to merge.");
+					return;
+				}
+
+				// Dry-run: predict only, no mutation, no lock needed.
+				if (opts.dryRun) {
+					const predictions: MergeResult[] = [];
+					for (const { branch } of branches) {
+						predictions.push(await predictMerge(root, branch, target));
+					}
+					if (useJson) {
+						jsonOutput({ dryRun: true, target, predictions });
+						return;
+					}
+					for (const p of predictions) {
+						printInfo(
+							`${p.branchName} → ${target}: predicted ${p.tier ?? "conflict"}` +
+								(p.conflictFiles.length ? ` (${p.conflictFiles.length} conflict file(s))` : ""),
+						);
+					}
+					return;
+				}
+
+				const queue = createMergeQueue(mergeDbPath(root));
+				const results: MergeResult[] = [];
+				try {
+					for (const { branch, session } of branches) {
+						const entry = queue.enqueue({
+							branchName: branch,
+							agentName: session?.agentName ?? "unknown",
+							taskId: session?.taskId ?? "unknown",
+							targetBranch: target,
+						});
+						const result = await withMergeLock(root, () =>
+							mergeBranch(root, branch, target, { autoResolve: config.merge.aiResolveEnabled }),
+						);
+						queue.markStatus(entry.id, result.status);
+						results.push(result);
+					}
+				} finally {
+					queue.close();
+				}
+
+				if (useJson) {
+					jsonOutput({ target, results });
+					return;
+				}
+				for (const r of results) {
+					if (r.status === "merged") {
+						printSuccess(`${r.branchName} → ${target}: ${r.tier}`);
+					} else {
+						printError(
+							`${r.branchName} → ${target}: ${r.status}` +
+								(r.conflictFiles.length ? ` (${r.conflictFiles.join(", ")})` : ""),
+						);
+					}
+				}
+			},
+		);
+}

package/src/commands/model.ts

@@ -0,0 +1,58 @@
+/**
+ * `agentplate model` — switch the active provider/model after initial setup.
+ *
+ * Reuses the same wizard as `agentplate setup` (à la Hermes' `hermes model`), so
+ * provider/model/runtime changes go through one consistent flow.
+ */
+
+import { Command } from "commander";
+import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { brand, printHint, printInfo, printSuccess } from "../logging/color.ts";
+import { getProviderSpec } from "../providers/registry.ts";
+import { scaffoldAgentplateDir } from "../scaffold.ts";
+import { setSecret } from "../secrets.ts";
+import { runSetupWizard } from "../wizard/setup.ts";
+
+export function createModelCommand(): Command {
+	return new Command("model")
+		.description("Change the active AI provider and model")
+		.option("--json", "print the current provider/model and exit")
+		.action(async (_opts: { 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 config = loadConfig(root);
+
+			// `--json` is a read-only query of the current selection.
+			if (useJson) {
+				const active = config.providers[config.activeProvider];
+				jsonOutput({
+					activeProvider: config.activeProvider,
+					model: active?.model ?? null,
+					runtime: config.runtime.default,
+				});
+				return;
+			}
+
+			if (!process.stdin.isTTY) {
+				const active = config.providers[config.activeProvider];
+				const spec = getProviderSpec(config.activeProvider);
+				printInfo(`Active provider: ${spec?.label ?? config.activeProvider}`);
+				printInfo(`Model:           ${active?.model ?? "(unset)"}`);
+				printInfo(`Runtime:         ${config.runtime.default}`);
+				printHint("Run in a terminal to change these interactively.");
+				return;
+			}
+
+			const result = await runSetupWizard(config);
+			scaffoldAgentplateDir(root, result.config);
+			if (result.secret) {
+				setSecret(root, result.secret.key, result.secret.value);
+			}
+			printSuccess(`${brand("Agentplate")} provider updated to ${result.config.activeProvider}.`);
+		});
+}

package/src/commands/prime.ts

@@ -0,0 +1,61 @@
+/**
+ * `agentplate prime` — load orchestration context (SessionStart hook target).
+ *
+ * Emits a concise snapshot of the project: provider/runtime, the current run,
+ * and active sessions — so a fresh Claude Code session starts oriented.
+ */
+
+import { Command } from "commander";
+import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { brand, muted, printInfo } from "../logging/color.ts";
+import { sessionsDbPath } from "../paths.ts";
+import { createSessionStore } from "../sessions/store.ts";
+
+export function createPrimeCommand(): Command {
+	return new Command("prime")
+		.description("Load orchestration context")
+		.option("--json", "output JSON")
+		.action((_opts: { 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 config = loadConfig(root);
+			const store = createSessionStore(sessionsDbPath(root));
+			try {
+				const runs = store.listRuns(1);
+				const currentRun = runs[0] ?? null;
+				const active = currentRun
+					? store.listSessions({ runId: currentRun.id }).filter((s) => s.state === "working")
+					: [];
+				const provider = config.providers[config.activeProvider];
+
+				if (useJson) {
+					jsonOutput({
+						project: config.project.name,
+						runtime: config.runtime.default,
+						provider: config.activeProvider,
+						model: provider?.model ?? null,
+						currentRun,
+						activeAgents: active.map((s) => s.agentName),
+					});
+					return;
+				}
+				printInfo(brand(`Agentplate — ${config.project.name}`));
+				printInfo(
+					`runtime: ${config.runtime.default}  provider: ${config.activeProvider}  model: ${provider?.model ?? "(unset)"}`,
+				);
+				printInfo(
+					currentRun ? `run: ${currentRun.id} (${currentRun.status})` : muted("no active run"),
+				);
+				printInfo(
+					`active agents: ${active.length ? active.map((s) => s.agentName).join(", ") : muted("none")}`,
+				);
+			} finally {
+				store.close();
+			}
+		});
+}

package/src/commands/reap.ts

@@ -0,0 +1,87 @@
+/**
+ * `agentplate reap` — terminate agents idle past the timeout.
+ *
+ * Sweeps the session store for workers with no activity for the idle window
+ * (default `config.agents.idleTimeoutMinutes`, 10), marks each `stopped`, kills any
+ * live process, and removes its worktree + branch. The coordinator is never
+ * reaped. Run it manually or on a cron; `agentplate serve` also reaps on its own
+ * loop. Use `--dry-run` to preview and `--keep-worktrees` to leave worktrees.
+ */
+
+import { Command } from "commander";
+import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { muted, printInfo, printSuccess } from "../logging/color.ts";
+import { sessionsDbPath } from "../paths.ts";
+import { reapIdleSessions, selectIdleSessions } from "../sessions/reaper.ts";
+import { createSessionStore } from "../sessions/store.ts";
+
+export function createReapCommand(): Command {
+	return new Command("reap")
+		.description("Terminate agents idle past the timeout (stop + kill + remove worktree)")
+		.option("--minutes <n>", "idle timeout in minutes (default: config.agents.idleTimeoutMinutes)")
+		.option("--keep-worktrees", "mark stopped + kill process but keep worktrees/branches")
+		.option("--dry-run", "list which agents would be reaped without changing anything")
+		.option("--json", "output JSON")
+		.action(
+			async (
+				opts: { minutes?: string; keepWorktrees?: boolean; dryRun?: boolean; 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 config = loadConfig(root);
+
+				const minutes =
+					opts.minutes !== undefined ? Number(opts.minutes) : config.agents.idleTimeoutMinutes;
+				if (!Number.isFinite(minutes) || minutes < 0) {
+					throw new ValidationError("--minutes must be a number >= 0");
+				}
+				const idleMs = minutes * 60_000;
+
+				const store = createSessionStore(sessionsDbPath(root));
+				try {
+					if (opts.dryRun) {
+						const candidates = selectIdleSessions(store.listSessions(), {
+							idleMs,
+							now: Date.now(),
+						}).map((s) => ({ agent: s.agentName, capability: s.capability, state: s.state }));
+						if (useJson) {
+							jsonOutput({ dryRun: true, minutes, candidates });
+						} else if (candidates.length === 0) {
+							printInfo(`No agents idle longer than ${minutes}m.`);
+						} else {
+							printInfo(`Would reap ${candidates.length} agent(s) idle >${minutes}m:`);
+							for (const c of candidates) {
+								process.stdout.write(`  ${c.agent} ${muted(`(${c.capability}, ${c.state})`)}\n`);
+							}
+						}
+						return;
+					}
+
+					const reaped = await reapIdleSessions(store, root, {
+						idleMs,
+						removeWorktrees: opts.keepWorktrees !== true,
+					});
+
+					if (useJson) {
+						jsonOutput({ minutes, reapedCount: reaped.length, reaped });
+					} else if (reaped.length === 0) {
+						printInfo(`No agents idle longer than ${minutes}m.`);
+					} else {
+						printSuccess(`Reaped ${reaped.length} idle agent(s) (>${minutes}m):`);
+						for (const r of reaped) {
+							const wt = r.worktreeRemoved ? "worktree removed" : "worktree kept";
+							process.stdout.write(`  ${r.agentName} ${muted(`(${r.capability}, ${wt})`)}\n`);
+						}
+					}
+				} finally {
+					store.close();
+				}
+			},
+		);
+}

package/src/commands/serve.ts

@@ -0,0 +1,61 @@
+/**
+ * `agentplate serve` — HTTP + WebSocket surface for the web UI.
+ *
+ * Serves the REST API, a live WebSocket snapshot feed, and the built SPA from
+ * `ui/dist`. All data is read from the same SQLite stores the CLI uses.
+ */
+
+import { join } from "node:path";
+import { Command } from "commander";
+import { findProjectRoot, isInitialized } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { brand, printHint, printInfo, printSuccess } from "../logging/color.ts";
+import { packageRootDir } from "../paths.ts";
+import { startServer } from "../serve/server.ts";
+
+export function createServeCommand(): Command {
+	return new Command("serve")
+		.description("Serve the web UI (HTTP + WebSocket) over the project's state")
+		.option("--port <n>", "port", "7551")
+		.option("--host <addr>", "bind host", "127.0.0.1")
+		.option("--ui-dir <path>", "directory of the built SPA (default: bundled ui/dist)")
+		.option("--json", "output JSON (prints the URL and exits non-blocking info)")
+		.action(
+			async (
+				opts: { port: string; host: string; uiDir?: 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 uiDir = opts.uiDir ?? join(packageRootDir(), "ui", "dist");
+				const handle = startServer({
+					root,
+					port: Number(opts.port),
+					host: opts.host,
+					uiDir,
+				});
+
+				if (useJson) {
+					jsonOutput({ url: handle.url, healthz: `${handle.url}/healthz`, uiDir });
+				} else {
+					printSuccess(`${brand("agentplate serve")} → ${handle.url}`);
+					printInfo(`  REST:    ${handle.url}/api/overview`);
+					printInfo(`  health:  ${handle.url}/healthz`);
+					printHint("  Press Ctrl+C to stop.");
+				}
+
+				// Keep the process alive until interrupted.
+				const shutdown = () => {
+					handle.stop();
+					process.exit(0);
+				};
+				process.on("SIGINT", shutdown);
+				process.on("SIGTERM", shutdown);
+				await new Promise<never>(() => {});
+			},
+		);
+}

package/src/commands/setup.ts

@@ -0,0 +1,48 @@
+/**
+ * `agentplate setup` — interactive onboarding.
+ *
+ * Ensures `.agentplate/` exists, then runs the provider/runtime/model wizard and
+ * persists the resulting config and (optionally) an API key into the gitignored
+ * secrets store.
+ */
+
+import { Command } from "commander";
+import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { brand, printHint, printSuccess } from "../logging/color.ts";
+import { ensureAgentplateDirs, scaffoldAgentplateDir } from "../scaffold.ts";
+import { setSecret } from "../secrets.ts";
+import { runSetupWizard } from "../wizard/setup.ts";
+import { buildInitialConfig } from "./init.ts";
+
+export function createSetupCommand(): Command {
+	return new Command("setup")
+		.description("Interactive setup — choose an AI provider, add your API key, pick a runtime")
+		.option("--name <name>", "set the project name (default: auto-detect)")
+		.action(async (opts: { name?: string }) => {
+			if (!process.stdin.isTTY) {
+				throw new ValidationError(
+					"`agentplate setup` is interactive and needs a terminal. Use `agentplate init` for non-interactive scaffolding.",
+				);
+			}
+
+			const root = findProjectRoot();
+			ensureAgentplateDirs(root);
+
+			const currentConfig = isInitialized(root)
+				? loadConfig(root)
+				: await buildInitialConfig(root, opts.name);
+
+			const result = await runSetupWizard(currentConfig);
+
+			// Write config (+ supporting files), then the secret (after .gitignore exists).
+			scaffoldAgentplateDir(root, result.config);
+			if (result.secret) {
+				setSecret(root, result.secret.key, result.secret.value);
+			}
+
+			printSuccess(`${brand("Agentplate")} is configured.`);
+			printHint("Verify with `agentplate doctor`. Your API key (if entered) is in");
+			printHint("  .agentplate/secrets.local.yaml  (gitignored — never committed).");
+		});
+}

package/src/commands/ship.test.ts

@@ -0,0 +1,106 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, 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 { createShipCommand, runShip } from "./ship.ts";
+
+let root: string;
+
+/** Stand up a minimal initialized project with a Node app and docker-gha default. */
+function initProject(): void {
+	mkdirSync(join(root, ".agentplate"), { recursive: true });
+	const config = structuredClone(DEFAULT_CONFIG);
+	config.project.name = "ship-test";
+	config.project.root = root;
+	config.deploy.default = "docker-gha";
+	config.deploy.gates = { preview: "auto", production: "confirm", staging: "auto" };
+	writeFileSync(join(root, ".agentplate", "config.yaml"), serializeConfig(config), "utf8");
+	writeFileSync(
+		join(root, "package.json"),
+		JSON.stringify(
+			{ name: "demo", scripts: { build: "echo build", start: "echo start" } },
+			null,
+			2,
+		),
+		"utf8",
+	);
+}
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-ship-"));
+	setProjectRootOverride(root);
+	initProject();
+});
+
+afterEach(() => {
+	setProjectRootOverride(null);
+	rmSync(root, { recursive: true, force: true });
+});
+
+describe("createShipCommand", () => {
+	test("builds without throwing and exposes options", () => {
+		const cmd = createShipCommand();
+		expect(cmd.name()).toBe("ship");
+		const flags = cmd.options.map((o) => o.long);
+		expect(flags).toContain("--target");
+		expect(flags).toContain("--dry-run");
+		expect(flags).toContain("--no-build");
+	});
+});
+
+describe("runShip (dry-run)", () => {
+	test("plans a deploy without mutation and writes artifacts", async () => {
+		const result = await runShip(root, "a tiny web app", {
+			target: "docker-gha",
+			env: "preview",
+			dryRun: true,
+			yes: false,
+			build: true,
+		});
+		expect(result.target).toBe("docker-gha");
+		expect(result.dryRun).toBe(true);
+		// Build stages ran (architect/builder/devops), deploy planned, verify skipped.
+		const names = result.stages.map((s) => s.name);
+		expect(names).toContain("architect");
+		expect(names).toContain("deploy");
+		const deployStage = result.stages.find((s) => s.name === "deploy");
+		expect(deployStage?.status).toBe("ok");
+		// A dry-run records a dryRun audit row, never a success deploy.
+		expect(result.deploy?.dryRun).toBe(true);
+		// docker-gha generateConfig wrote a Dockerfile to the project root.
+		expect(existsSync(join(root, "Dockerfile"))).toBe(true);
+		expect(existsSync(join(root, ".github", "workflows", "deploy.yml"))).toBe(true);
+		// No real deployment URL in dry-run.
+		expect(result.urls).toEqual([]);
+	});
+
+	test("--no-build skips build stages", async () => {
+		const result = await runShip(root, "current tree", {
+			target: "docker-gha",
+			env: "preview",
+			dryRun: true,
+			yes: false,
+			build: false,
+		});
+		const names = result.stages.map((s) => s.name);
+		expect(names).toContain("build");
+		expect(names).not.toContain("architect");
+	});
+});
+
+describe("runShip (gate)", () => {
+	test("production gate refuses a real deploy without --yes", async () => {
+		const result = await runShip(root, "prod app", {
+			target: "docker-gha",
+			env: "production",
+			dryRun: false,
+			yes: false,
+			build: false,
+		});
+		expect(result.deploy?.refused).toBe(true);
+		expect(result.deploy?.gateDecision).toBe("denied");
+		const deployStage = result.stages.find((s) => s.name === "deploy");
+		expect(deployStage?.status).toBe("refused");
+	});
+});