@agentplate/cli 1.0.0

package/src/commands/worktree.ts

@@ -0,0 +1,77 @@
+/**
+ * `agentplate worktree` — list and clean agent git worktrees.
+ */
+
+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 { sessionsDbPath, worktreesDir } from "../paths.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import { listWorktrees, removeWorktree } from "../worktree/manager.ts";
+
+function requireInit(): string {
+	const root = findProjectRoot();
+	if (!isInitialized(root)) {
+		throw new ValidationError("Not initialized. Run `agentplate setup` first.");
+	}
+	return root;
+}
+
+function listCommand(): Command {
+	return new Command("list")
+		.description("List git worktrees")
+		.option("--json", "output JSON")
+		.action(async (_opts: { json?: boolean }, command: Command) => {
+			const useJson = command.optsWithGlobals().json === true;
+			const root = requireInit();
+			const worktrees = await listWorktrees(root);
+			if (useJson) {
+				jsonOutput(worktrees);
+				return;
+			}
+			for (const w of worktrees) printInfo(`${w.branch || "(detached)"}  ${muted(w.path)}`);
+		});
+}
+
+function cleanCommand(): Command {
+	return new Command("clean")
+		.description("Remove agent worktrees")
+		.option("--completed", "only worktrees of completed/stopped agents")
+		.option("--all", "all agent worktrees")
+		.option("--force", "remove even if dirty/unmerged")
+		.action(async (opts: { completed?: boolean; all?: boolean; force?: boolean }) => {
+			const root = requireInit();
+			if (!opts.completed && !opts.all) {
+				throw new ValidationError("Pass --completed or --all.");
+			}
+			const base = worktreesDir(root);
+			const worktrees = (await listWorktrees(root)).filter((w) => w.path.startsWith(base));
+
+			const store = createSessionStore(sessionsDbPath(root));
+			let removed = 0;
+			try {
+				const sessions = store.listSessions();
+				for (const w of worktrees) {
+					if (opts.completed) {
+						const session = sessions.find((s) => s.worktreePath === w.path);
+						const done = session && (session.state === "completed" || session.state === "stopped");
+						if (!done) continue;
+					}
+					await removeWorktree(root, w.path, { force: opts.force });
+					removed++;
+				}
+			} finally {
+				store.close();
+			}
+			printSuccess(`Removed ${removed} worktree(s)`);
+		});
+}
+
+export function createWorktreeCommand(): Command {
+	return new Command("worktree")
+		.description("Manage agent git worktrees")
+		.addCommand(listCommand())
+		.addCommand(cleanCommand());
+}

package/src/config.test.ts

@@ -0,0 +1,92 @@
+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,
+	isInitialized,
+	loadConfig,
+	serializeConfig,
+	setProjectRootOverride,
+	validateConfig,
+} from "./config.ts";
+
+let root: string;
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-cfg-"));
+	mkdirSync(join(root, ".agentplate"), { recursive: true });
+});
+
+afterEach(() => {
+	setProjectRootOverride(null);
+	rmSync(root, { recursive: true, force: true });
+});
+
+function writeConfig(dir: string, file: string, contents: string): void {
+	writeFileSync(join(dir, ".agentplate", file), contents, "utf8");
+}
+
+describe("loadConfig", () => {
+	test("returns defaults when only an empty config.yaml exists", () => {
+		writeConfig(root, "config.yaml", "");
+		const cfg = loadConfig(root);
+		expect(cfg.runtime.default).toBe(DEFAULT_CONFIG.runtime.default);
+		expect(cfg.project.root).toBe(root);
+		expect(cfg.agents.maxDepth).toBe(2);
+	});
+
+	test("merges config.yaml over defaults", () => {
+		writeConfig(root, "config.yaml", "project:\n  name: my-app\nruntime:\n  default: codex\n");
+		const cfg = loadConfig(root);
+		expect(cfg.project.name).toBe("my-app");
+		expect(cfg.runtime.default).toBe("codex");
+		// Untouched defaults remain.
+		expect(cfg.merge.aiResolveEnabled).toBe(true);
+	});
+
+	test("config.local.yaml overrides config.yaml", () => {
+		writeConfig(root, "config.yaml", "runtime:\n  default: claude\n");
+		writeConfig(root, "config.local.yaml", "runtime:\n  default: gemini\n");
+		const cfg = loadConfig(root);
+		expect(cfg.runtime.default).toBe("gemini");
+	});
+
+	test("throws ConfigError on invalid YAML", () => {
+		writeConfig(root, "config.yaml", "project:\n  name: [unclosed\n");
+		expect(() => loadConfig(root)).toThrow();
+	});
+});
+
+describe("validateConfig", () => {
+	test("rejects negative maxDepth", () => {
+		const cfg = structuredClone(DEFAULT_CONFIG);
+		cfg.agents.maxDepth = -1;
+		expect(() => validateConfig(cfg)).toThrow();
+	});
+
+	test("rejects maxConcurrent below 1", () => {
+		const cfg = structuredClone(DEFAULT_CONFIG);
+		cfg.agents.maxConcurrent = 0;
+		expect(() => validateConfig(cfg)).toThrow();
+	});
+
+	test("accepts the defaults", () => {
+		expect(() => validateConfig(structuredClone(DEFAULT_CONFIG))).not.toThrow();
+	});
+});
+
+describe("isInitialized / serializeConfig", () => {
+	test("isInitialized reflects presence of config.yaml", () => {
+		expect(isInitialized(root)).toBe(false);
+		writeConfig(root, "config.yaml", "");
+		expect(isInitialized(root)).toBe(true);
+	});
+
+	test("serializeConfig round-trips through loadConfig", () => {
+		const yamlText = serializeConfig(DEFAULT_CONFIG);
+		writeConfig(root, "config.yaml", yamlText);
+		const cfg = loadConfig(root);
+		expect(cfg.runtime.default).toBe(DEFAULT_CONFIG.runtime.default);
+	});
+});

package/src/config.ts

@@ -0,0 +1,202 @@
+/**
+ * Configuration loading, defaults, and validation.
+ *
+ * Resolution order (later overrides earlier):
+ *   DEFAULT_CONFIG  ←  .agentplate/config.yaml  ←  .agentplate/config.local.yaml
+ *
+ * `config.local.yaml` is gitignored and holds machine-specific overrides.
+ * Secrets never live in any of these files — only the *names* of env vars that
+ * hold them (see {@link ProviderConfig.authTokenEnv}).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import yaml from "js-yaml";
+import { ConfigError } from "./errors.ts";
+import type { AgentplateConfig } from "./types.ts";
+
+/** Directory (relative to project root) holding all Agentplate state. */
+export const AGENTPLATE_DIR = ".agentplate";
+/** Primary committed config file. */
+export const CONFIG_FILE = "config.yaml";
+/** Gitignored machine-specific overrides. */
+export const CONFIG_LOCAL_FILE = "config.local.yaml";
+
+/** Built-in defaults applied beneath any on-disk config. */
+export const DEFAULT_CONFIG: AgentplateConfig = {
+	project: {
+		name: "",
+		root: "",
+		canonicalBranch: "main",
+	},
+	runtime: {
+		default: "claude",
+	},
+	activeProvider: "anthropic",
+	providers: {
+		anthropic: { type: "native", authTokenEnv: "ANTHROPIC_API_KEY" },
+	},
+	agents: {
+		manifestPath: ".agentplate/agent-manifest.json",
+		baseDir: ".agentplate/agent-defs",
+		maxConcurrent: 10,
+		maxDepth: 2,
+		maxAgentsPerLead: 5,
+		idleTimeoutMinutes: 10,
+	},
+	merge: {
+		aiResolveEnabled: true,
+	},
+	skills: {
+		enabled: true,
+		retrieval: {
+			budgetChars: 6000,
+			maxFull: 4,
+		},
+		distill: {
+			onlyOnGatesPass: true,
+			model: null,
+		},
+		prune: {
+			quarantineBelow: 0.25,
+			minSamples: 4,
+			maxAgeDays: 30,
+		},
+	},
+	deploy: {
+		default: "",
+		targets: {},
+		gates: {
+			production: "confirm",
+			staging: "auto",
+			preview: "auto",
+		},
+	},
+	logging: {
+		verbose: false,
+		redactSecrets: true,
+	},
+};
+
+let projectRootOverride: string | null = null;
+
+/** Override project-root auto-detection (used by `--project` and tests). */
+export function setProjectRootOverride(root: string | null): void {
+	projectRootOverride = root === null ? null : resolve(root);
+}
+
+/**
+ * Find the project root by walking up from `start` looking for a `.agentplate/`
+ * directory. Falls back to the override or the current working directory.
+ */
+export function findProjectRoot(start: string = process.cwd()): string {
+	if (projectRootOverride) return projectRootOverride;
+	let dir = resolve(start);
+	while (true) {
+		if (existsSync(join(dir, AGENTPLATE_DIR))) return dir;
+		const parent = resolve(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return resolve(start);
+}
+
+/** Has Agentplate been initialized at `root`? */
+export function isInitialized(root: string): boolean {
+	return existsSync(join(root, AGENTPLATE_DIR, CONFIG_FILE));
+}
+
+/** Deep-merge plain objects from `source` into a clone of `base`. */
+function deepMerge<T>(base: T, source: unknown): T {
+	if (source === null || source === undefined) return base;
+	if (typeof base !== "object" || base === null || Array.isArray(base)) {
+		return source as T;
+	}
+	if (typeof source !== "object" || Array.isArray(source)) {
+		return source as T;
+	}
+	const result: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+	for (const [key, value] of Object.entries(source as Record<string, unknown>)) {
+		const baseValue = (base as Record<string, unknown>)[key];
+		result[key] = deepMerge(baseValue, value);
+	}
+	return result as T;
+}
+
+/** Parse a YAML file into a plain object, or return `{}` if it is absent. */
+function readYamlIfExists(path: string): Record<string, unknown> {
+	if (!existsSync(path)) return {};
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new ConfigError(`Failed to read ${path}: ${(error as Error).message}`);
+	}
+	let parsed: unknown;
+	try {
+		parsed = yaml.load(raw);
+	} catch (error) {
+		throw new ConfigError(`Invalid YAML in ${path}: ${(error as Error).message}`);
+	}
+	if (parsed === null || parsed === undefined) return {};
+	if (typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new ConfigError(`Expected a mapping at the top of ${path}`);
+	}
+	return parsed as Record<string, unknown>;
+}
+
+/**
+ * Validate a fully-merged config. Throws {@link ConfigError} on the first
+ * problem found. Kept intentionally small in Phase 0; extended per phase.
+ */
+export function validateConfig(config: AgentplateConfig): void {
+	if (!config.project || typeof config.project.canonicalBranch !== "string") {
+		throw new ConfigError("config.project.canonicalBranch must be a string");
+	}
+	if (!config.runtime || typeof config.runtime.default !== "string") {
+		throw new ConfigError("config.runtime.default must be a string");
+	}
+	if (typeof config.activeProvider !== "string" || config.activeProvider === "") {
+		throw new ConfigError("config.activeProvider must be a non-empty string");
+	}
+	if (!config.providers[config.activeProvider]) {
+		throw new ConfigError(
+			`config.activeProvider "${config.activeProvider}" is not present in config.providers`,
+		);
+	}
+	if (config.agents.maxDepth < 0) {
+		throw new ConfigError("config.agents.maxDepth must be >= 0");
+	}
+	if (config.agents.maxConcurrent < 1) {
+		throw new ConfigError("config.agents.maxConcurrent must be >= 1");
+	}
+	if (config.agents.idleTimeoutMinutes < 0) {
+		throw new ConfigError(
+			"config.agents.idleTimeoutMinutes must be >= 0 (0 disables idle reaping)",
+		);
+	}
+}
+
+/**
+ * Load and validate the Agentplate config for the given project root (auto-detected
+ * if omitted). Merges defaults ← config.yaml ← config.local.yaml and stamps the
+ * resolved `project.root`.
+ */
+export function loadConfig(root?: string): AgentplateConfig {
+	const projectRoot = root ? resolve(root) : findProjectRoot();
+	const dir = join(projectRoot, AGENTPLATE_DIR);
+	const base = readYamlIfExists(join(dir, CONFIG_FILE));
+	const local = readYamlIfExists(join(dir, CONFIG_LOCAL_FILE));
+
+	let merged = deepMerge(DEFAULT_CONFIG, base);
+	merged = deepMerge(merged, local);
+	merged.project.root = projectRoot;
+
+	validateConfig(merged);
+	return merged;
+}
+
+/** Serialize a config object to YAML for writing to `config.yaml`. */
+export function serializeConfig(config: AgentplateConfig): string {
+	return yaml.dump(config, { indent: 2, lineWidth: 100, sortKeys: false });
+}

package/src/db/sqlite.test.ts

@@ -0,0 +1,77 @@
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openDatabase } from "./sqlite.ts";
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "agentplate-db-"));
+});
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("openDatabase", () => {
+	test("opens a fresh DB with WAL", () => {
+		const path = join(dir, "fresh.db");
+		const db = openDatabase(path);
+		const mode = db.query("PRAGMA journal_mode").get() as { journal_mode: string };
+		expect(mode.journal_mode.toLowerCase()).toBe("wal");
+		db.close();
+	});
+
+	test("guard leaves a compatible DB untouched", () => {
+		const path = join(dir, "ok.db");
+		// Seed a DB whose `runs` table HAS the required column.
+		const seed = new Database(path, { create: true });
+		seed.exec("CREATE TABLE runs (id TEXT PRIMARY KEY, created_at TEXT NOT NULL)");
+		seed.exec("INSERT INTO runs (id, created_at) VALUES ('r1', 'now')");
+		seed.close();
+
+		const db = openDatabase(path, { guard: { table: "runs", columns: ["created_at"] } });
+		const row = db.query("SELECT id FROM runs WHERE id = 'r1'").get() as { id: string } | null;
+		expect(row?.id).toBe("r1"); // data preserved — no recreation
+		db.close();
+		// No backup file created.
+		expect(readdirSync(dir).some((f) => f.includes("incompatible"))).toBe(false);
+	});
+
+	test("guard backs up and recreates an incompatible (foreign) DB", () => {
+		const path = join(dir, "foreign.db");
+		// Seed a DB shaped like the OTHER agentplate: `runs` has `started_at`,
+		// not `created_at`.
+		const seed = new Database(path, { create: true });
+		seed.exec(
+			"CREATE TABLE runs (id TEXT PRIMARY KEY, started_at TEXT NOT NULL, agent_count INTEGER)",
+		);
+		seed.exec("INSERT INTO runs (id, started_at, agent_count) VALUES ('old', 'then', 3)");
+		seed.close();
+
+		const db = openDatabase(path, { guard: { table: "runs", columns: ["created_at"] } });
+		// The foreign `runs` table is gone; we can now create ours and insert.
+		db.exec("CREATE TABLE IF NOT EXISTS runs (id TEXT PRIMARY KEY, created_at TEXT NOT NULL)");
+		db.exec("INSERT INTO runs (id, created_at) VALUES ('new', 'now')");
+		const cols = db.query("PRAGMA table_info(runs)").all() as Array<{ name: string }>;
+		expect(cols.map((c) => c.name)).toContain("created_at");
+		// The old row is NOT present (fresh DB).
+		const old = db.query("SELECT id FROM runs WHERE id = 'old'").get();
+		expect(old).toBeNull();
+		db.close();
+
+		// A backup of the incompatible file exists.
+		expect(readdirSync(dir).some((f) => f.startsWith("foreign.db.incompatible-"))).toBe(true);
+	});
+
+	test("guard ignores an absent table (fresh project)", () => {
+		const path = join(dir, "empty.db");
+		const db = openDatabase(path, { guard: { table: "runs", columns: ["created_at"] } });
+		// No backup, no error — our CREATE TABLE will make it correctly.
+		db.exec("CREATE TABLE runs (id TEXT PRIMARY KEY, created_at TEXT NOT NULL)");
+		db.close();
+		expect(readdirSync(dir).some((f) => f.includes("incompatible"))).toBe(false);
+	});
+});

package/src/db/sqlite.ts

@@ -0,0 +1,102 @@
+/**
+ * SQLite helper.
+ *
+ * Every Agentplate store (mail, sessions, events, skills, deploys, merge queue)
+ * opens its database through {@link openDatabase} so WAL mode and a busy timeout
+ * are applied consistently — both required for safe concurrent access from
+ * multiple agent processes.
+ *
+ * Self-healing schema guard: `.agentplate/*.db` files are gitignored, regenerable
+ * runtime state. Because this tool shares the `.agentplate/` directory name (and
+ * db filenames) with the unrelated `@ag-eco/agentplate-cli`, a project that used
+ * the other tool can leave behind a `sessions.db`/`mail.db` with a *different*
+ * schema. `CREATE TABLE IF NOT EXISTS` then silently keeps the foreign table and
+ * later inserts fail (e.g. "table runs has no column named created_at"). The
+ * optional {@link OpenDatabaseOptions.guard} detects that case, backs up the
+ * incompatible file, and recreates a clean database.
+ */
+
+import { Database } from "bun:sqlite";
+import { existsSync, renameSync } from "node:fs";
+
+/** A required-columns check used to detect a foreign/stale schema. */
+export interface SchemaGuard {
+	/** Table that must exist with the listed columns (if it exists at all). */
+	table: string;
+	/** Columns our schema requires on that table. */
+	columns: string[];
+}
+
+export interface OpenDatabaseOptions {
+	/** Open read-only (no schema creation). */
+	readonly?: boolean;
+	/** Busy timeout in milliseconds (default 5000). */
+	busyTimeoutMs?: number;
+	/**
+	 * Verify an existing file-backed DB has our schema. If the guarded table
+	 * exists but is missing any required column, the DB was created by a
+	 * different tool/version; the file (and -wal/-shm) is renamed to a
+	 * `.incompatible-<ts>` backup and a fresh DB is created in its place.
+	 */
+	guard?: SchemaGuard;
+}
+
+/** Apply our standard PRAGMAs to a freshly opened connection. */
+function applyPragmas(db: Database, busyTimeoutMs: number): void {
+	db.exec("PRAGMA journal_mode = WAL");
+	db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
+	db.exec("PRAGMA foreign_keys = ON");
+}
+
+/** Does `table` exist but lack one of the required columns? */
+function tableIsIncompatible(db: Database, guard: SchemaGuard): boolean {
+	const exists = db
+		.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+		.get(guard.table);
+	if (!exists) return false; // absent → our CREATE TABLE will make it correctly
+	const cols = db.query(`PRAGMA table_info(${guard.table})`).all() as Array<{ name: string }>;
+	const present = new Set(cols.map((c) => c.name));
+	return guard.columns.some((c) => !present.has(c));
+}
+
+/** Rename a stale DB file plus its WAL/SHM sidecars out of the way. */
+function backupStaleDb(path: string): string {
+	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+	const backup = `${path}.incompatible-${stamp}`;
+	for (const suffix of ["", "-wal", "-shm"]) {
+		const file = `${path}${suffix}`;
+		if (existsSync(file)) {
+			try {
+				renameSync(file, `${backup}${suffix}`);
+			} catch {
+				// Best-effort: if a sidecar can't be moved, continue; the main file
+				// rename is what matters for recreating a clean DB.
+			}
+		}
+	}
+	return backup;
+}
+
+/**
+ * Open (or create) a SQLite database with WAL journaling and a busy timeout.
+ * Pass `":memory:"` as the path for ephemeral test databases. When `guard` is
+ * provided and an existing file has an incompatible schema, the file is backed
+ * up and recreated.
+ */
+export function openDatabase(path: string, options: OpenDatabaseOptions = {}): Database {
+	const busyTimeoutMs = options.busyTimeoutMs ?? 5000;
+	const readonly = options.readonly ?? false;
+
+	let db = new Database(path, { readonly, create: true });
+	applyPragmas(db, busyTimeoutMs);
+
+	// Self-heal a foreign/stale schema (file-backed DBs only; never :memory:).
+	if (options.guard && !readonly && path !== ":memory:" && tableIsIncompatible(db, options.guard)) {
+		db.close();
+		backupStaleDb(path);
+		db = new Database(path, { readonly: false, create: true });
+		applyPragmas(db, busyTimeoutMs);
+	}
+
+	return db;
+}