@agentplate/cli 1.0.0

package/src/index.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env bun
+
+/**
+ * Agentplate CLI — main entry point and command router.
+ *
+ * Usage: agentplate <command> [args...]   (alias: ap)
+ *
+ * Phase 0 wires the program shell, global flags, version handling, a consistent
+ * top-level error handler, and the first real command (`doctor`). Subsequent
+ * phases register their commands here.
+ */
+
+import { Command } from "commander";
+import { createCoordinatorCommand } from "./commands/coordinator.ts";
+import {
+	createDeployCommand,
+	createRollbackCommand,
+	createTargetCommand,
+} from "./commands/deploy.ts";
+import { createDoctorCommand } from "./commands/doctor.ts";
+import { createInitCommand } from "./commands/init.ts";
+import { createLogCommand } from "./commands/log.ts";
+import { createMailCommand } from "./commands/mail.ts";
+import { createMergeCommand } from "./commands/merge.ts";
+import { createModelCommand } from "./commands/model.ts";
+import { createPrimeCommand } from "./commands/prime.ts";
+import { createReapCommand } from "./commands/reap.ts";
+import { createServeCommand } from "./commands/serve.ts";
+import { createSetupCommand } from "./commands/setup.ts";
+import { createShipCommand } from "./commands/ship.ts";
+import { createSkillCommand } from "./commands/skill.ts";
+import { createSlingCommand } from "./commands/sling.ts";
+import { createStatusCommand } from "./commands/status.ts";
+import { createStopCommand } from "./commands/stop.ts";
+import { createTuiCommand } from "./commands/tui.ts";
+import { createWorktreeCommand } from "./commands/worktree.ts";
+import { setProjectRootOverride } from "./config.ts";
+import { isAgentplateError } from "./errors.ts";
+import { jsonError } from "./json.ts";
+import { brand, muted, printError, setQuiet } from "./logging/color.ts";
+import { VERSION } from "./version.ts";
+
+export { VERSION };
+
+interface GlobalOptions {
+	json?: boolean;
+	verbose?: boolean;
+	quiet?: boolean;
+	project?: string;
+}
+
+const rawArgs = process.argv.slice(2);
+
+// Handle `--version --json` before Commander consumes the flag.
+if ((rawArgs.includes("-v") || rawArgs.includes("--version")) && rawArgs.includes("--json")) {
+	process.stdout.write(
+		`${JSON.stringify({
+			name: "agentplate",
+			version: VERSION,
+			runtime: "bun",
+			platform: `${process.platform}-${process.arch}`,
+		})}\n`,
+	);
+	process.exit(0);
+}
+
+function buildProgram(): Command {
+	const program = new Command();
+
+	program
+		.name("agentplate")
+		.description(
+			`${brand("Agentplate")} — self-improving multi-agent orchestration, from build to deploy.`,
+		)
+		.version(VERSION, "-v, --version", "output the version number")
+		.option("--json", "output machine-readable JSON")
+		.option("--verbose", "verbose output")
+		.option("-q, --quiet", "suppress non-error output")
+		.option("--project <path>", "target project root (overrides auto-detection)")
+		.configureHelp({ showGlobalOptions: true });
+
+	// Apply global flags before any subcommand action runs. optsWithGlobals()
+	// merges the subcommand's options with the program's global options.
+	program.hook("preAction", (thisCommand) => {
+		const opts = thisCommand.optsWithGlobals<GlobalOptions>();
+		if (opts.quiet) setQuiet(true);
+		if (opts.project) setProjectRootOverride(opts.project);
+	});
+
+	// Onboarding
+	program.addCommand(createSetupCommand());
+	program.addCommand(createInitCommand());
+	program.addCommand(createModelCommand());
+	program.addCommand(createDoctorCommand());
+	// Orchestration
+	program.addCommand(createCoordinatorCommand());
+	program.addCommand(createSlingCommand());
+	program.addCommand(createStatusCommand());
+	program.addCommand(createMailCommand());
+	program.addCommand(createMergeCommand());
+	program.addCommand(createWorktreeCommand());
+	program.addCommand(createStopCommand());
+	program.addCommand(createReapCommand());
+	program.addCommand(createPrimeCommand());
+	program.addCommand(createLogCommand());
+	// Self-improving skills
+	program.addCommand(createSkillCommand());
+	// Build → CI/CD → Deploy
+	program.addCommand(createShipCommand());
+	program.addCommand(createTargetCommand());
+	program.addCommand(createDeployCommand());
+	program.addCommand(createRollbackCommand());
+	// Surfaces
+	program.addCommand(createServeCommand());
+	program.addCommand(createTuiCommand());
+
+	program.addHelpText(
+		"after",
+		`\n${muted("More commands (ship, skill, deploy, …) arrive as Agentplate grows.")}`,
+	);
+
+	return program;
+}
+
+async function main(): Promise<void> {
+	const program = buildProgram();
+	await program.parseAsync(process.argv);
+}
+
+main().catch((error: unknown) => {
+	if (rawArgs.includes("--json")) {
+		jsonError(error);
+	} else {
+		printError(error instanceof Error ? error.message : String(error));
+	}
+	process.exit(isAgentplateError(error) ? error.exitCode : 1);
+});

package/src/insights/quality-gates.ts

@@ -0,0 +1,73 @@
+/**
+ * Quality gates — run the project's configured test/lint/typecheck commands and
+ * fold their results into a single {@link OutcomeStatus}.
+ *
+ * The status threads through the self-improving loop: skills are only distilled
+ * from work that passed, and applied-skill outcomes are scored by it, so the
+ * confidence track record reflects whether changes actually held up.
+ */
+
+import type { OutcomeStatus, QualityGate } from "../types.ts";
+
+export interface GateResult {
+	name: string;
+	command: string;
+	passed: boolean;
+	exitCode: number;
+	durationMs: number;
+}
+
+export interface QualityGateOutcome {
+	status: OutcomeStatus;
+	results: GateResult[];
+	totalDurationMs: number;
+}
+
+/**
+ * Run each gate as a shell command in `cwd`. A gate passes on exit code 0.
+ * Aggregate status: all pass → success, all fail → failure, mixed → partial.
+ * Returns null when there are no gates configured (nothing to score).
+ */
+export async function runQualityGates(
+	gates: QualityGate[],
+	cwd: string,
+): Promise<QualityGateOutcome | null> {
+	if (gates.length === 0) return null;
+
+	const results: GateResult[] = [];
+	let total = 0;
+	for (const gate of gates) {
+		const started = performance.now();
+		let exitCode = 1;
+		try {
+			// Run the gate through the platform shell: `cmd /c` on Windows (no bash
+			// there), `bash -lc` elsewhere. `.cmd` shims (biome/tsc) resolve under both.
+			const shellArgv =
+				process.platform === "win32"
+					? ["cmd", "/d", "/s", "/c", gate.command]
+					: ["bash", "-lc", gate.command];
+			const proc = Bun.spawn(shellArgv, {
+				cwd,
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			exitCode = await proc.exited;
+		} catch {
+			exitCode = 1;
+		}
+		const durationMs = Math.round(performance.now() - started);
+		total += durationMs;
+		results.push({
+			name: gate.name,
+			command: gate.command,
+			passed: exitCode === 0,
+			exitCode,
+			durationMs,
+		});
+	}
+
+	const passed = results.filter((r) => r.passed).length;
+	const status: OutcomeStatus =
+		passed === results.length ? "success" : passed === 0 ? "failure" : "partial";
+	return { status, results, totalDurationMs: total };
+}

package/src/json.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { ConfigError } from "./errors.ts";
+import { jsonFailure, jsonSuccess } from "./json.ts";
+
+describe("json envelopes", () => {
+	test("jsonSuccess wraps data", () => {
+		expect(jsonSuccess({ a: 1 })).toEqual({ ok: true, data: { a: 1 } });
+	});
+
+	test("jsonFailure preserves AgentplateError code", () => {
+		const env = jsonFailure(new ConfigError("bad config"));
+		expect(env.ok).toBe(false);
+		expect(env.error.code).toBe("CONFIG_ERROR");
+		expect(env.error.message).toBe("bad config");
+	});
+
+	test("jsonFailure handles plain errors", () => {
+		const env = jsonFailure(new Error("oops"));
+		expect(env.error.code).toBe("UNKNOWN_ERROR");
+		expect(env.error.message).toBe("oops");
+	});
+
+	test("jsonFailure handles non-error throwables", () => {
+		const env = jsonFailure("string thrown");
+		expect(env.error.code).toBe("UNKNOWN_ERROR");
+		expect(env.error.message).toBe("string thrown");
+	});
+});

package/src/json.ts

@@ -0,0 +1,50 @@
+/**
+ * Standardized JSON output envelopes for `--json` mode.
+ *
+ * Every command that supports `--json` should emit exactly one envelope on
+ * stdout via {@link jsonOutput} or {@link jsonError}, so machine consumers get a
+ * predictable, versioned shape: `{ ok, data? , error? }`.
+ */
+
+import { isAgentplateError } from "./errors.ts";
+
+/** Successful JSON envelope. */
+export interface JsonSuccess<T> {
+	ok: true;
+	data: T;
+}
+
+/** Error JSON envelope. */
+export interface JsonFailure {
+	ok: false;
+	error: {
+		code: string;
+		message: string;
+	};
+}
+
+export type JsonEnvelope<T> = JsonSuccess<T> | JsonFailure;
+
+/** Build (do not print) a success envelope. */
+export function jsonSuccess<T>(data: T): JsonSuccess<T> {
+	return { ok: true, data };
+}
+
+/** Build (do not print) an error envelope from any thrown value. */
+export function jsonFailure(error: unknown): JsonFailure {
+	if (isAgentplateError(error)) {
+		return { ok: false, error: { code: error.code, message: error.message } };
+	}
+	const message = error instanceof Error ? error.message : String(error);
+	return { ok: false, error: { code: "UNKNOWN_ERROR", message } };
+}
+
+/** Print a success envelope to stdout. */
+export function jsonOutput<T>(data: T): void {
+	process.stdout.write(`${JSON.stringify(jsonSuccess(data))}\n`);
+}
+
+/** Print an error envelope to stderr. */
+export function jsonError(error: unknown): void {
+	process.stderr.write(`${JSON.stringify(jsonFailure(error))}\n`);
+}

package/src/logging/color.ts

@@ -0,0 +1,62 @@
+/**
+ * Central color + console output control.
+ *
+ * Wraps `chalk` so color can be disabled globally (via `NO_COLOR`, a non-TTY
+ * stdout, or `--quiet`) from one place, and exposes a small palette + a set of
+ * semantic printers used across commands for a consistent look.
+ */
+
+import chalk from "chalk";
+
+let quiet = false;
+
+/** Enable/disable quiet mode (suppresses non-error output). */
+export function setQuiet(value: boolean): void {
+	quiet = value;
+}
+
+/** Is quiet mode active? */
+export function isQuiet(): boolean {
+	return quiet;
+}
+
+/** Re-export chalk so callers don't import it directly. */
+export { chalk };
+
+// Palette ------------------------------------------------------------------
+/** Brand color (primary). */
+export const brand = chalk.hex("#e07a3f");
+/** Accent color (secondary highlights). */
+export const accent = chalk.hex("#f0b429");
+/** Muted color (de-emphasized text). */
+export const muted = chalk.dim;
+
+// Semantic printers --------------------------------------------------------
+/** Print a success line (skipped in quiet mode). */
+export function printSuccess(message: string): void {
+	if (quiet) return;
+	process.stdout.write(`${chalk.green("✓")} ${message}\n`);
+}
+
+/** Print an informational line (skipped in quiet mode). */
+export function printInfo(message: string): void {
+	if (quiet) return;
+	process.stdout.write(`${message}\n`);
+}
+
+/** Print a warning line (skipped in quiet mode). */
+export function printWarning(message: string): void {
+	if (quiet) return;
+	process.stdout.write(`${accent("!")} ${message}\n`);
+}
+
+/** Print a de-emphasized hint line (skipped in quiet mode). */
+export function printHint(message: string): void {
+	if (quiet) return;
+	process.stdout.write(`${muted(message)}\n`);
+}
+
+/** Print an error line to stderr (always shown). */
+export function printError(message: string): void {
+	process.stderr.write(`${chalk.red("✗")} ${message}\n`);
+}

package/src/logging/logger.ts

@@ -0,0 +1,60 @@
+/**
+ * Minimal structured logger.
+ *
+ * Phase 0 provides a lightweight, dependency-free logger that writes
+ * human-readable lines to stderr and respects the global redaction setting.
+ * Later phases can extend this with NDJSON file sinks per agent without changing
+ * the call sites.
+ */
+
+import { sanitize } from "./sanitizer.ts";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40,
+};
+
+export interface LoggerOptions {
+	/** Minimum level to emit. */
+	level?: LogLevel;
+	/** Redact secrets from messages before writing. */
+	redact?: boolean;
+	/** Component name prefixed to each line. */
+	scope?: string;
+}
+
+export interface Logger {
+	debug(message: string): void;
+	info(message: string): void;
+	warn(message: string): void;
+	error(message: string): void;
+	child(scope: string): Logger;
+}
+
+/** Create a logger. Defaults: `info` level, redaction on, no scope. */
+export function createLogger(options: LoggerOptions = {}): Logger {
+	const level: LogLevel = options.level ?? "info";
+	const redact = options.redact ?? true;
+	const scope = options.scope;
+	const threshold = LEVEL_ORDER[level];
+
+	function emit(messageLevel: LogLevel, message: string): void {
+		if (LEVEL_ORDER[messageLevel] < threshold) return;
+		const text = redact ? sanitize(message) : message;
+		const prefix = scope ? `[${scope}] ` : "";
+		process.stderr.write(`${messageLevel.toUpperCase()} ${prefix}${text}\n`);
+	}
+
+	return {
+		debug: (message) => emit("debug", message),
+		info: (message) => emit("info", message),
+		warn: (message) => emit("warn", message),
+		error: (message) => emit("error", message),
+		child: (childScope) =>
+			createLogger({ level, redact, scope: scope ? `${scope}:${childScope}` : childScope }),
+	};
+}

package/src/logging/sanitizer.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { containsSecret, sanitize } from "./sanitizer.ts";
+
+describe("sanitizer", () => {
+	test("redacts Anthropic-style keys", () => {
+		const out = sanitize("key is sk-ant-abcdef0123456789ABCDEF done");
+		expect(out).not.toContain("abcdef0123456789");
+		expect(out).toContain("[REDACTED]");
+	});
+
+	test("redacts KEY=value assignments but keeps the key prefix", () => {
+		const out = sanitize("ANTHROPIC_API_KEY=supersecretvalue123");
+		expect(out).toContain("ANTHROPIC_API_KEY=");
+		expect(out).not.toContain("supersecretvalue123");
+	});
+
+	test("redacts bearer tokens", () => {
+		const out = sanitize("Authorization: Bearer abc.def.ghi");
+		expect(out).not.toContain("abc.def.ghi");
+	});
+
+	test("redacts PEM private key blocks", () => {
+		const pem = "-----BEGIN PRIVATE KEY-----\nMIIBVgIBADANBg\n-----END PRIVATE KEY-----";
+		expect(sanitize(pem)).toBe("[REDACTED]");
+	});
+
+	test("leaves clean text untouched", () => {
+		const clean = "just a normal log line with no secrets";
+		expect(sanitize(clean)).toBe(clean);
+		expect(containsSecret(clean)).toBe(false);
+	});
+
+	test("containsSecret detects secrets", () => {
+		expect(containsSecret("token: ghp_0123456789abcdefghij0123")).toBe(true);
+	});
+});

package/src/logging/sanitizer.ts

@@ -0,0 +1,57 @@
+/**
+ * Secret redaction.
+ *
+ * Best-effort scrubbing of credentials from text before it is logged, stored,
+ * or surfaced in mail/audit records. This is defense-in-depth, not a guarantee:
+ * the architecture keeps secrets out of these channels in the first place, and
+ * this is the backstop.
+ */
+
+const REDACTED = "[REDACTED]";
+
+/**
+ * Patterns whose ENTIRE match is a secret. The full match is replaced. Ordered
+ * most-specific first so a narrower pattern (sk-ant-) wins before a broader one.
+ */
+const WHOLE_SECRET_PATTERNS: RegExp[] = [
+	// PEM private key blocks.
+	/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+	// Provider API keys with recognizable prefixes.
+	/\bsk-ant-[a-zA-Z0-9_-]{16,}\b/g,
+	/\bsk-[a-zA-Z0-9]{20,}\b/g,
+	/\bghp_[a-zA-Z0-9]{20,}\b/g,
+	/\bgho_[a-zA-Z0-9]{20,}\b/g,
+	// AWS access key ids.
+	/\bAKIA[0-9A-Z]{16}\b/g,
+];
+
+/**
+ * Patterns where capture group 1 is a prefix to KEEP and the rest is the secret
+ * to redact (so logs stay readable: `ANTHROPIC_API_KEY=[REDACTED]`).
+ */
+const PREFIXED_SECRET_PATTERNS: RegExp[] = [
+	// Bearer tokens in Authorization headers.
+	/\b(Authorization:\s*Bearer\s+)[^\s"']+/gi,
+	// `KEY=value` / `TOKEN: value` / `SECRET="value"` assignments.
+	/\b([A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)[A-Z0-9_]*\s*[=:]\s*)["']?[^\s"']+["']?/gi,
+];
+
+/**
+ * Return `text` with recognized secrets redacted. Whole-secret matches are
+ * replaced entirely; prefixed matches keep their key and redact the value.
+ */
+export function sanitize(text: string): string {
+	let result = text;
+	for (const pattern of WHOLE_SECRET_PATTERNS) {
+		result = result.replace(pattern, REDACTED);
+	}
+	for (const pattern of PREFIXED_SECRET_PATTERNS) {
+		result = result.replace(pattern, (_match, prefix: string) => `${prefix}${REDACTED}`);
+	}
+	return result;
+}
+
+/** True if the text appears to contain a secret (after-the-fact safety check). */
+export function containsSecret(text: string): boolean {
+	return sanitize(text) !== text;
+}