@agentplate/cli 1.0.0

package/src/runtimes/registry.ts

@@ -0,0 +1,63 @@
+/**
+ * Runtime registry — the single place that knows about concrete adapter classes.
+ *
+ * Everything else resolves a runtime by name through {@link getRuntime} and then
+ * talks only to the {@link AgentRuntime} interface, so adding a new runtime is a
+ * one-line registration here plus its adapter file. Resolution is deliberately
+ * tiny: an explicit name, else a caller-supplied fallback, else `"claude"`.
+ */
+
+import { ValidationError } from "../errors.ts";
+import { ClaudeRuntime } from "./claude.ts";
+import { CodexRuntime } from "./codex.ts";
+import { CursorRuntime } from "./cursor.ts";
+import { GeminiRuntime } from "./gemini.ts";
+import { MockRuntime } from "./mock.ts";
+import { OpenCodeRuntime } from "./opencode.ts";
+import type { AgentRuntime } from "./types.ts";
+
+/**
+ * Name → factory map. Factories return a *fresh* instance per call so adapters
+ * can never accidentally share mutable state between resolutions. Insertion
+ * order here defines the order reported by {@link getRuntimeNames} and in error
+ * messages.
+ */
+const runtimes = new Map<string, () => AgentRuntime>([
+	["claude", () => new ClaudeRuntime()],
+	["codex", () => new CodexRuntime()],
+	["gemini", () => new GeminiRuntime()],
+	["cursor", () => new CursorRuntime()],
+	["opencode", () => new OpenCodeRuntime()],
+	["mock", () => new MockRuntime()],
+]);
+
+/**
+ * Resolve a runtime adapter by name.
+ *
+ * Lookup order:
+ *   1. explicit `name` (e.g. from `--runtime`),
+ *   2. `fallback` (typically `config.runtime.default`),
+ *   3. `"claude"` (the built-in default).
+ *
+ * Throws {@link ValidationError} listing the valid names when the resolved name
+ * is unknown, so a typo at the CLI yields an actionable message rather than a
+ * bare `undefined`.
+ */
+export function getRuntime(name?: string, fallback?: string): AgentRuntime {
+	const resolved = name ?? fallback ?? "claude";
+	const factory = runtimes.get(resolved);
+	if (!factory) {
+		throw new ValidationError(
+			`Unknown runtime: "${resolved}". Valid runtimes: ${getRuntimeNames().join(", ")}`,
+		);
+	}
+	return factory();
+}
+
+/**
+ * Names of all registered runtimes, in registration order. Used to validate a
+ * user-supplied runtime name and to render the choices in help / errors.
+ */
+export function getRuntimeNames(): string[] {
+	return [...runtimes.keys()];
+}

package/src/runtimes/resolve.ts

@@ -0,0 +1,45 @@
+/**
+ * Model resolution — bridge between the agent manifest (which names models by
+ * alias) and a concrete {@link ResolvedModel} the runtime can spawn.
+ *
+ * Phase 2 keeps this deliberately simple: the active provider's configured
+ * `model` (set by `agentplate setup`) is the concrete model, and the provider's
+ * `authTokenEnv` secret is injected as an env var. Per-capability model tiering
+ * (opus/sonnet/haiku) is a later refinement; for now the manifest alias is the
+ * fallback when no provider model is configured.
+ *
+ * Auth mode matters here: only `api-key`/`env` providers inject a credential env
+ * var. `subscription` providers delegate to the runtime CLI's own login (e.g. a
+ * Claude Pro/Max OAuth session), so injecting an empty/leftover key would
+ * actively break that login — we deliberately inject nothing.
+ */
+
+import { getSecret } from "../secrets.ts";
+import type { AgentplateConfig, ResolvedModel } from "../types.ts";
+
+/**
+ * Resolve the concrete model + provider env for a manifest model alias.
+ *
+ * @param config  loaded Agentplate config
+ * @param root    project root (to read the gitignored secret value)
+ * @param manifestModel the model alias/id from the agent definition
+ */
+export function resolveModel(
+	config: AgentplateConfig,
+	root: string,
+	manifestModel: string,
+): ResolvedModel {
+	const provider = config.providers[config.activeProvider];
+	const model = provider?.model ?? manifestModel;
+	const env: Record<string, string> = {};
+
+	// Default to "api-key" for legacy configs written before authMode existed.
+	const authMode = provider?.authMode ?? (provider?.authTokenEnv ? "api-key" : "none");
+	const usesKey = authMode === "api-key" || authMode === "env";
+
+	if (usesKey && provider?.authTokenEnv) {
+		const secret = getSecret(root, provider.authTokenEnv);
+		if (secret) env[provider.authTokenEnv] = secret;
+	}
+	return { model, env };
+}

package/src/runtimes/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Runtime adapter contract.
+ *
+ * A *runtime* is the coding-agent CLI that drives a worker (Claude Code, Codex,
+ * …). Agentplate is headless-first: workers run as spawn-per-turn subprocesses, so
+ * the core method is {@link AgentRuntime.buildDirectSpawn}, which returns the
+ * argv for a single turn. Adapters are stateless; one file per CLI, resolved by
+ * the registry. Auth flows through {@link AgentRuntime.buildEnv} — never
+ * hardcoded.
+ */
+
+import type { ResolvedModel } from "../types.ts";
+
+/** A normalized event parsed from a runtime's headless event stream. */
+export interface AgentEvent {
+	/** Coarse event kind: "assistant" | "tool_use" | "tool_result" | "result" | "session" | "error". */
+	type: string;
+	/** Tool name for tool events. */
+	tool?: string;
+	/** Runtime session id (emitted once near the start; used for --resume). */
+	sessionId?: string;
+	/**
+	 * Token usage + USD cost, when the runtime reports it (e.g. a Claude Code
+	 * `result` event carries `usage` + `total_cost_usd`). Recorded into the event
+	 * store so the Costs page can aggregate real per-agent spend.
+	 */
+	usage?: { tokens: number; costUsd: number };
+	/**
+	 * Human-readable error message when this is an error event (e.g. OpenCode's
+	 * `error.data.message`, a Claude error result). Recorded into the event store
+	 * so a failed agent's reason is visible in the feed/logs instead of a blank
+	 * "error" with no detail.
+	 */
+	error?: string;
+	/** The raw parsed JSON line, for callers that need more detail. */
+	raw: unknown;
+}
+
+/** Options for a single headless turn. */
+export interface DirectSpawnOpts {
+	/** Working directory (the worktree path). */
+	cwd: string;
+	/** Concrete model id. */
+	model: string;
+	/** Relative path to the instruction file within the worktree. */
+	instructionPath: string;
+	/** Resume a prior turn's session (omit for the first turn). */
+	resumeSessionId?: string;
+	/** Extra env vars (merged over process.env by the caller). */
+	env?: Record<string, string>;
+	/** Initial user-turn text (the prompt for this turn). */
+	prompt?: string;
+}
+
+/** Options for an attended (foreground, stdio-inherited) interactive session. */
+export interface InteractiveSpawnOpts {
+	/** Concrete model id. */
+	model: string;
+	/** System prompt text to append (the agent's role definition). */
+	systemPrompt?: string;
+	/** Permission posture: "default" (prompts) | "bypass" (unattended). */
+	permissionMode?: "default" | "bypass";
+	/** A first user message to seed the session with (non-empty → seeded). */
+	initialMessage?: string;
+}
+
+/** The contract every runtime adapter implements. */
+export interface AgentRuntime {
+	/** Unique adapter id (e.g. "claude"). */
+	id: string;
+	/** Stability tier. */
+	readonly stability: "stable" | "beta" | "experimental";
+	/** Relative path where the overlay instructions are written in the worktree. */
+	readonly instructionPath: string;
+
+	/** Build argv for a single headless turn (run via Bun.spawn). */
+	buildDirectSpawn(opts: DirectSpawnOpts): string[];
+
+	/**
+	 * Build argv for an ATTENDED interactive session (foreground, stdio inherited).
+	 * Used by `coordinator start` to hand the terminal to a live agent chat.
+	 * Optional: runtimes that cannot run interactively omit it.
+	 */
+	buildInteractiveSpawn?(opts: InteractiveSpawnOpts): string[];
+
+	/** Build provider env vars (API keys, base URLs) for the resolved model. */
+	buildEnv(model: ResolvedModel): Record<string, string>;
+
+	/** Build argv for a one-shot non-interactive call (used by AI merge/distill later). */
+	buildPrintCommand(prompt: string, model?: string): string[];
+
+	/** Parse a headless stdout byte stream into normalized events. */
+	parseEvents?(stream: ReadableStream<Uint8Array>): AsyncIterable<AgentEvent>;
+
+	/** Deploy any runtime-specific guards/config into the worktree before spawn. */
+	deployConfig?(worktreePath: string): Promise<void>;
+}

package/src/scaffold.ts

@@ -0,0 +1,68 @@
+/**
+ * Project scaffolding — create the `.agentplate/` directory structure and write the
+ * initial config. Shared by `agentplate init` (non-interactive) and `agentplate setup`
+ * (interactive).
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENTPLATE_DIR, CONFIG_FILE, serializeConfig } from "./config.ts";
+import type { AgentplateConfig } from "./types.ts";
+
+/** Subdirectories created under `.agentplate/`. */
+const SUBDIRS = ["agents", "agent-defs", "worktrees", "specs", "logs", "skills"] as const;
+
+/** The `.agentplate/.gitignore` that keeps runtime state and secrets out of git. */
+const AGENTPLATE_GITIGNORE = `# Agentplate runtime state — do not commit.
+worktrees/
+logs/
+*.db
+*.db-shm
+*.db-wal
+config.local.yaml
+secrets.local.yaml
+agents/*/checkpoint.json
+`;
+
+const AGENTPLATE_README = `# .agentplate/
+
+This directory holds Agentplate's per-project state: configuration, agent
+definitions, git worktrees for agent workers, task specs, logs, distilled
+skills, and SQLite databases (mail, sessions, events, skills, deploys).
+
+Committed: \`config.yaml\`, \`agent-manifest.json\`, \`agent-defs/\`.
+Gitignored (see \`.gitignore\` here): \`config.local.yaml\`, \`secrets.local.yaml\`,
+\`worktrees/\`, \`logs/\`, and all \`*.db\` files.
+
+Managed by the \`agentplate\` CLI — you generally don't edit these by hand.
+`;
+
+/** Create the `.agentplate/` directory tree (idempotent). */
+export function ensureAgentplateDirs(root: string): void {
+	const base = join(root, AGENTPLATE_DIR);
+	mkdirSync(base, { recursive: true });
+	for (const sub of SUBDIRS) {
+		mkdirSync(join(base, sub), { recursive: true });
+	}
+}
+
+/** Write `.agentplate/config.yaml`. */
+export function writeConfig(root: string, config: AgentplateConfig): void {
+	writeFileSync(join(root, AGENTPLATE_DIR, CONFIG_FILE), serializeConfig(config), "utf8");
+}
+
+/**
+ * Scaffold `.agentplate/` and write the config + supporting files. Idempotent: safe
+ * to run on an already-initialized project (it overwrites config.yaml with the
+ * provided config and (re)writes the .gitignore/README).
+ */
+export function scaffoldAgentplateDir(root: string, config: AgentplateConfig): void {
+	ensureAgentplateDirs(root);
+	writeConfig(root, config);
+	const base = join(root, AGENTPLATE_DIR);
+	writeFileSync(join(base, ".gitignore"), AGENTPLATE_GITIGNORE, "utf8");
+	const readmePath = join(base, "README.md");
+	if (!existsSync(readmePath)) {
+		writeFileSync(readmePath, AGENTPLATE_README, "utf8");
+	}
+}

package/src/secrets.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getSecret, hasSecret, loadSecrets, secretsPath, setSecret } from "./secrets.ts";
+
+let root: string;
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-sec-"));
+	mkdirSync(join(root, ".agentplate"), { recursive: true });
+});
+
+afterEach(() => {
+	rmSync(root, { recursive: true, force: true });
+	delete process.env.AGENTPLATE_TEST_KEY;
+});
+
+describe("secrets store", () => {
+	test("loadSecrets is empty when no file exists", () => {
+		expect(loadSecrets(root)).toEqual({});
+	});
+
+	test("setSecret then loadSecrets round-trips", () => {
+		setSecret(root, "ANTHROPIC_API_KEY", "sk-test-value");
+		expect(loadSecrets(root).ANTHROPIC_API_KEY).toBe("sk-test-value");
+	});
+
+	test("secrets file is written with 0600 permissions", () => {
+		setSecret(root, "TOKEN", "abc");
+		const mode = statSync(secretsPath(root)).mode & 0o777;
+		expect(mode).toBe(0o600);
+	});
+
+	test("getSecret prefers the file over the environment", () => {
+		process.env.AGENTPLATE_TEST_KEY = "from-env";
+		setSecret(root, "AGENTPLATE_TEST_KEY", "from-file");
+		expect(getSecret(root, "AGENTPLATE_TEST_KEY")).toBe("from-file");
+	});
+
+	test("getSecret falls back to the environment", () => {
+		process.env.AGENTPLATE_TEST_KEY = "from-env";
+		expect(getSecret(root, "AGENTPLATE_TEST_KEY")).toBe("from-env");
+	});
+
+	test("hasSecret reflects availability", () => {
+		expect(hasSecret(root, "MISSING")).toBe(false);
+		setSecret(root, "PRESENT", "x");
+		expect(hasSecret(root, "PRESENT")).toBe(true);
+	});
+});

package/src/secrets.ts

@@ -0,0 +1,78 @@
+/**
+ * Secret storage.
+ *
+ * Secrets (API keys, deploy tokens) are stored as `ENV_VAR_NAME: value` pairs in
+ * `.agentplate/secrets.local.yaml`, which is gitignored and never committed. The
+ * rest of Agentplate references secrets only by their env-var *name*; values are
+ * read here at the moment they are needed and injected into a child process env.
+ *
+ * Resolution order for {@link getSecret}: the secrets file first, then
+ * `process.env` (so CI can supply credentials via the environment without a
+ * file).
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import { AGENTPLATE_DIR } from "./config.ts";
+import { ConfigError } from "./errors.ts";
+
+/** Filename of the gitignored secrets store. */
+export const SECRETS_FILE = "secrets.local.yaml";
+
+/** Absolute path to the secrets file for a project root. */
+export function secretsPath(root: string): string {
+	return join(root, AGENTPLATE_DIR, SECRETS_FILE);
+}
+
+/** Load all stored secrets for a project root (empty object if none). */
+export function loadSecrets(root: string): Record<string, string> {
+	const path = secretsPath(root);
+	if (!existsSync(path)) return {};
+	let parsed: unknown;
+	try {
+		parsed = yaml.load(readFileSync(path, "utf8"));
+	} 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 in ${path}`);
+	}
+	const result: Record<string, string> = {};
+	for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+		if (typeof value === "string") result[key] = value;
+	}
+	return result;
+}
+
+/**
+ * Persist a secret under an env-var name. Writes the gitignored secrets file
+ * with restrictive (0600) permissions.
+ */
+export function setSecret(root: string, key: string, value: string): void {
+	const path = secretsPath(root);
+	const current = loadSecrets(root);
+	current[key] = value;
+	const header =
+		"# Agentplate secrets — gitignored, never commit this file.\n" +
+		"# Maps ENV_VAR_NAME: value. Values are injected into agent/deploy processes on demand.\n";
+	writeFileSync(path, header + yaml.dump(current, { indent: 2 }), { mode: 0o600 });
+}
+
+/**
+ * Read a secret by env-var name. Checks the secrets file, then `process.env`.
+ * Returns `undefined` if neither has it.
+ */
+export function getSecret(root: string, key: string): string | undefined {
+	const fromFile = loadSecrets(root)[key];
+	if (fromFile !== undefined && fromFile !== "") return fromFile;
+	const fromEnv = process.env[key];
+	if (fromEnv !== undefined && fromEnv !== "") return fromEnv;
+	return undefined;
+}
+
+/** True if a secret is available (file or env) for the given env-var name. */
+export function hasSecret(root: string, key: string): boolean {
+	return getSecret(root, key) !== undefined;
+}