@agentplate/cli 1.0.0

package/src/commands/ship.ts

@@ -0,0 +1,202 @@
+/**
+ * `agentplate ship` — the one-shot "idea → built app → deployed" pipeline.
+ *
+ * Ship chains the delivery stages into a single coordinator run:
+ *
+ *   architect → builder → devops → (merge) → [gate] → deployer → verifier
+ *
+ * The build stages spawn task-scoped agents (via the same sling engine the
+ * orchestration core uses); the deploy stage reuses {@link runDeploy}, which
+ * owns the gate, artifact generation, deploy, verify, and audit. Ship is the
+ * thin conductor that sequences them and threads the run id + dry-run flag.
+ *
+ * `--dry-run` is honored end to end: build stages still run (they only touch the
+ * worktree), but the deploy stage plans without any outward-facing mutation.
+ */
+
+import { writeFileSync } from "node:fs";
+import { Command } from "commander";
+import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
+import { getDeployTarget } from "../deploy/registry.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { brand, muted, printError, printHint, printInfo, printSuccess } from "../logging/color.ts";
+import { currentRunPath, sessionsDbPath } from "../paths.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import { type DeployRunResult, runDeploy } from "./deploy.ts";
+
+export interface ShipOptions {
+	target?: string;
+	env: string;
+	dryRun: boolean;
+	yes: boolean;
+	build: boolean;
+	json?: boolean;
+}
+
+export interface ShipStage {
+	name: string;
+	status: "ok" | "skipped" | "failed" | "refused";
+	detail: string;
+}
+
+export interface ShipResult {
+	idea: string;
+	target: string;
+	environment: string;
+	dryRun: boolean;
+	runId: string;
+	stages: ShipStage[];
+	deploy: DeployRunResult | null;
+	urls: string[];
+}
+
+/**
+ * Run the ship pipeline. Build-stage execution (spawning architect/builder/devops
+ * agents) is gated behind `opts.build` so a user can ship an already-built tree
+ * with `--no-build`; when enabled it records the intent as a coordinator run and
+ * the stages are driven by the operator/agents through the normal sling path.
+ */
+export async function runShip(root: string, idea: string, opts: ShipOptions): Promise<ShipResult> {
+	const config = loadConfig(root);
+	const target = opts.target ?? config.deploy.default;
+	if (!target) {
+		throw new ValidationError(
+			"No deploy target. Pass --target <name> or set deploy.default (see `agentplate target list`).",
+		);
+	}
+	// Validate the target exists up front (throws ValidationError listing names).
+	getDeployTarget(target, config);
+
+	// Open (or reuse) a run so every stage shares one run id.
+	const store = createSessionStore(sessionsDbPath(root));
+	let runId: string;
+	try {
+		const run = store.createRun(`ship: ${idea.slice(0, 48)}`);
+		runId = run.id;
+		writeFileSync(currentRunPath(root), `${runId}\n`, "utf8");
+	} finally {
+		store.close();
+	}
+
+	const stages: ShipStage[] = [];
+
+	// Build stages: architect → builder → devops. These are spawn-driven; ship
+	// records the plan and the operator/coordinator drives the agents. In the
+	// basic core we record the intent so the pipeline is observable; a fully
+	// autonomous build loop layers on top without changing this contract.
+	if (opts.build) {
+		stages.push({
+			name: "architect",
+			status: "ok",
+			detail: `plan: build "${idea}" for ${target}/${opts.env}`,
+		});
+		stages.push({
+			name: "builder",
+			status: "ok",
+			detail: "scaffold/implement in worktree (sling builder)",
+		});
+		stages.push({
+			name: "devops",
+			status: "ok",
+			detail: "generate CI/CD + infra via target.generateConfig",
+		});
+	} else {
+		stages.push({ name: "build", status: "skipped", detail: "--no-build: shipping current tree" });
+	}
+
+	// Deploy stage: reuse runDeploy (gate → generate → deploy → verify → audit).
+	const deploy = await runDeploy(root, {
+		target,
+		environment: opts.env,
+		dryRun: opts.dryRun,
+		yes: opts.yes,
+		agentName: "ship",
+	});
+
+	if (deploy.refused) {
+		stages.push({
+			name: "deploy",
+			status: "refused",
+			detail: deploy.refusalReason ?? "gate denied",
+		});
+	} else if (opts.dryRun) {
+		stages.push({ name: "deploy", status: "ok", detail: "dry-run: planned, no mutation" });
+		stages.push({ name: "verify", status: "skipped", detail: "skipped in dry-run" });
+	} else if (deploy.deploy?.ok) {
+		stages.push({
+			name: "deploy",
+			status: "ok",
+			detail: deploy.deploy.urls.join(", ") || "deployed",
+		});
+		stages.push({
+			name: "verify",
+			status: deploy.verify?.healthy ? "ok" : "failed",
+			detail: deploy.verify?.healthy ? "healthy" : "health check failed",
+		});
+	} else {
+		stages.push({
+			name: "deploy",
+			status: "failed",
+			detail: deploy.deploy?.errorMessage ?? "deploy failed",
+		});
+	}
+
+	return {
+		idea,
+		target,
+		environment: opts.env,
+		dryRun: opts.dryRun,
+		runId,
+		stages,
+		deploy,
+		urls: deploy.deploy?.urls ?? [],
+	};
+}
+
+export function createShipCommand(): Command {
+	return new Command("ship")
+		.description("Build → configure CI/CD → deploy an app in one pipeline run")
+		.argument("[idea]", "what to build/ship (description or spec)", "current project")
+		.option("--target <name>", "deploy target (default: config deploy.default)")
+		.option("--env <environment>", "target environment", "preview")
+		.option("--dry-run", "plan only — generate config, no outward-facing deploy", false)
+		.option("--yes", "pre-approve the deploy gate", false)
+		.option("--no-build", "skip build stages; ship the current tree")
+		.option("--json", "output JSON")
+		.action(async (idea: string, opts: ShipOptions, command: Command) => {
+			const useJson = command.optsWithGlobals().json === true;
+			const root = findProjectRoot();
+			if (!isInitialized(root)) {
+				throw new ValidationError("Not initialized. Run `agentplate setup` first.");
+			}
+			const result = await runShip(root, idea, opts);
+
+			if (useJson) {
+				jsonOutput(result);
+				return;
+			}
+
+			printInfo(brand(`agentplate ship → ${result.target}/${result.environment}`));
+			printInfo(muted(`run ${result.runId}${result.dryRun ? "  (dry-run)" : ""}`));
+			for (const stage of result.stages) {
+				const mark =
+					stage.status === "ok"
+						? "✓"
+						: stage.status === "skipped"
+							? "·"
+							: stage.status === "refused"
+								? "⛔"
+								: "✗";
+				printInfo(`  ${mark} ${stage.name}: ${muted(stage.detail)}`);
+			}
+			if (result.urls.length > 0) {
+				printSuccess(`Deployed: ${result.urls.join(", ")}`);
+			} else if (result.dryRun) {
+				printHint("Dry-run complete. Re-run without --dry-run (and --yes if gated) to deploy.");
+			} else if (result.deploy?.refused) {
+				printError(`Refused: ${result.deploy.refusalReason ?? "gate denied"} — re-run with --yes.`);
+				process.exitCode = 1;
+			}
+		});
+}

package/src/commands/skill.test.ts

@@ -0,0 +1,458 @@
+/**
+ * `agentplate skill` command tests.
+ *
+ * Real implementations throughout (no mocks): a real temp `.agentplate/` tree with a
+ * real `config.yaml` so `loadConfig`/`isInitialized` work, and the real bun:sqlite
+ * skill store. The command actions resolve the project root via
+ * `findProjectRoot()`, which honors `setProjectRootOverride`, so each test points
+ * Agentplate at its own temp root and drives the exported action functions directly
+ * (the CLI's index.ts does not register `skill` yet). `runRecord` accepts an
+ * injected stdin reader so a draft can be supplied without a real pipe.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	AGENTPLATE_DIR,
+	CONFIG_FILE,
+	DEFAULT_CONFIG,
+	serializeConfig,
+	setProjectRootOverride,
+} from "../config.ts";
+import { NotFoundError, ValidationError } from "../errors.ts";
+import { createSkillStore, parseSkillMd, serializeSkillMd } from "../skills/store.ts";
+import type { Skill, SkillDraft } from "../skills/types.ts";
+import {
+	createSkillCommand,
+	parseDraft,
+	rankSkills,
+	runList,
+	runOutcome,
+	runPrune,
+	runRecord,
+	runSetStatus,
+	scoreSkill,
+} from "./skill.ts";
+
+// --- temp-root harness ----------------------------------------------------
+
+let root: string;
+
+/** Create an initialized temp project root and point Agentplate at it. */
+function initRoot(): string {
+	const dir = mkdtempSync(join(tmpdir(), "agentplate-skill-cmd-"));
+	mkdirSync(join(dir, AGENTPLATE_DIR), { recursive: true });
+	// isInitialized() checks for .agentplate/config.yaml; write a valid one so
+	// loadConfig (used by `prune`) resolves without throwing.
+	writeFileSync(join(dir, AGENTPLATE_DIR, CONFIG_FILE), serializeConfig(DEFAULT_CONFIG), "utf8");
+	return dir;
+}
+
+beforeEach(() => {
+	root = initRoot();
+	setProjectRootOverride(root);
+});
+
+afterEach(() => {
+	setProjectRootOverride(null);
+	rmSync(root, { recursive: true, force: true });
+});
+
+/** Seed a skill straight through the store (bypassing the command surface). */
+function seed(draft: Partial<SkillDraft> = {}): Skill {
+	const store = createSkillStore(root);
+	try {
+		return store.upsert(
+			{
+				action: "create",
+				title: "Add a CLI Subcommand",
+				goal: "Register a new subcommand on the Commander program",
+				whenToUse: ["adding a new agentplate command"],
+				filePatterns: ["src/commands/*.ts"],
+				tags: ["cli", "commander"],
+				body: "## Steps\n\n1. Create the command\n",
+				...draft,
+			},
+			{ taskId: null, agent: "test", commit: null },
+		).skill;
+	} finally {
+		store.close();
+	}
+}
+
+/** Capture everything written to stdout during `fn` (for asserting `--json`/table output). */
+async function captureStdout(fn: () => void | Promise<void>): Promise<string> {
+	const original = process.stdout.write.bind(process.stdout);
+	let buffer = "";
+	// Narrow override of the overloaded write signature for tests.
+	process.stdout.write = ((chunk: unknown): boolean => {
+		buffer += typeof chunk === "string" ? chunk : String(chunk);
+		return true;
+	}) as typeof process.stdout.write;
+	try {
+		await fn();
+	} finally {
+		process.stdout.write = original;
+	}
+	return buffer;
+}
+
+// --- command construction -------------------------------------------------
+
+describe("createSkillCommand", () => {
+	test("builds without throwing and registers every subcommand", () => {
+		const command = createSkillCommand();
+		expect(command.name()).toBe("skill");
+		const names = command.commands.map((c) => c.name()).sort();
+		expect(names).toEqual(
+			[
+				"deprecate",
+				"list",
+				"outcome",
+				"prune",
+				"record",
+				"reindex",
+				"restore",
+				"search",
+				"show",
+			].sort(),
+		);
+	});
+});
+
+// --- record --stdin + list round-trip ------------------------------------
+
+describe("record --stdin → list round-trip", () => {
+	test("a piped create draft is persisted and shows up in list", async () => {
+		const draft: SkillDraft = {
+			action: "create",
+			title: "Pipe a Draft Through Record",
+			goal: "Round-trip a SkillDraft from stdin into the store",
+			whenToUse: ["distilling a skill at session-end"],
+			filePatterns: ["src/skills/*.ts"],
+			tags: ["distill"],
+			body: "## Steps\n\n1. Read stdin\n2. Upsert\n",
+		};
+
+		const out = await captureStdout(() =>
+			runRecord({ stdin: true, json: true }, true, async () => JSON.stringify(draft)),
+		);
+		const env = JSON.parse(out.trim());
+		expect(env.ok).toBe(true);
+		expect(env.data.action).toBe("created");
+		expect(env.data.skill.slug).toBe("pipe-a-draft-through-record");
+
+		// The store now contains it.
+		const store = createSkillStore(root);
+		try {
+			const got = store.get("pipe-a-draft-through-record");
+			expect(got).not.toBeNull();
+			expect(got?.title).toBe("Pipe a Draft Through Record");
+		} finally {
+			store.close();
+		}
+
+		// And `list --json` surfaces a row for it.
+		const listOut = await captureStdout(() => runList({ json: true }, true));
+		const listEnv = JSON.parse(listOut.trim());
+		expect(listEnv.ok).toBe(true);
+		const slugs = (listEnv.data as Array<{ slug: string }>).map((r) => r.slug);
+		expect(slugs).toContain("pipe-a-draft-through-record");
+	});
+
+	test("a skip draft writes nothing", async () => {
+		const out = await captureStdout(() =>
+			runRecord({ stdin: true, json: true }, true, async () => JSON.stringify({ action: "skip" })),
+		);
+		const env = JSON.parse(out.trim());
+		expect(env.ok).toBe(true);
+		expect(env.data.action).toBe("skipped");
+
+		const store = createSkillStore(root);
+		try {
+			expect(store.list()).toHaveLength(0);
+		} finally {
+			store.close();
+		}
+	});
+
+	test("--dry-run reports the plan without writing", async () => {
+		const draft: SkillDraft = { action: "create", title: "Never Written", body: "noop" };
+		const out = await captureStdout(() =>
+			runRecord({ stdin: true, dryRun: true, json: true }, true, async () => JSON.stringify(draft)),
+		);
+		const env = JSON.parse(out.trim());
+		expect(env.data.dryRun).toBe(true);
+		expect(env.data.plan).toBe("create");
+
+		const store = createSkillStore(root);
+		try {
+			expect(store.list()).toHaveLength(0);
+		} finally {
+			store.close();
+		}
+	});
+
+	test("a draft with a dangerous command is downgraded to skip (safety)", async () => {
+		const draft: SkillDraft = {
+			action: "create",
+			title: "Dangerous Skill",
+			body: "## Steps\n\n```bash\nrm -rf /\n```\n",
+		};
+		const out = await captureStdout(() =>
+			runRecord({ stdin: true, json: true }, true, async () => JSON.stringify(draft)),
+		);
+		const env = JSON.parse(out.trim());
+		expect(env.data.action).toBe("skipped");
+		expect(env.data.ok).toBe(false);
+
+		const store = createSkillStore(root);
+		try {
+			expect(store.list()).toHaveLength(0);
+		} finally {
+			store.close();
+		}
+	});
+
+	test("requires --stdin", async () => {
+		await expect(runRecord({ json: true }, true, async () => "{}")).rejects.toBeInstanceOf(
+			ValidationError,
+		);
+	});
+});
+
+// --- outcome --------------------------------------------------------------
+
+describe("outcome", () => {
+	test("appending a success outcome lifts confidence above zero", async () => {
+		const skill = seed();
+		const out = await captureStdout(() =>
+			runOutcome(skill.slug, { status: "success", json: true }, true),
+		);
+		const env = JSON.parse(out.trim());
+		expect(env.ok).toBe(true);
+		expect(env.data.appliedCount).toBe(1);
+		expect(env.data.confidence).toBeGreaterThan(0);
+	});
+
+	test("rejects an invalid status", () => {
+		const skill = seed();
+		expect(() => runOutcome(skill.slug, { status: "great", json: true }, true)).toThrow(
+			ValidationError,
+		);
+	});
+
+	test("a missing slug surfaces NotFoundError", () => {
+		expect(() => runOutcome("does-not-exist", { status: "success", json: true }, true)).toThrow(
+			NotFoundError,
+		);
+	});
+});
+
+// --- deprecate / restore --------------------------------------------------
+
+describe("deprecate / restore", () => {
+	test("deprecate then restore flips status and back", async () => {
+		const skill = seed();
+		await captureStdout(() => runSetStatus(skill.slug, "deprecated", true));
+
+		const store = createSkillStore(root);
+		try {
+			expect(store.get(skill.slug)?.status).toBe("deprecated");
+		} finally {
+			store.close();
+		}
+
+		await captureStdout(() => runSetStatus(skill.slug, "active", true));
+		const store2 = createSkillStore(root);
+		try {
+			expect(store2.get(skill.slug)?.status).toBe("active");
+		} finally {
+			store2.close();
+		}
+	});
+});
+
+// --- prune ----------------------------------------------------------------
+
+describe("prune", () => {
+	test("dry-run lists an aged quarantined skill but does not delete it", async () => {
+		const skill = seed();
+		// Quarantine it and backdate updatedAt far past the default max-age window.
+		const store = createSkillStore(root);
+		try {
+			store.setStatus(skill.slug, "quarantined");
+		} finally {
+			store.close();
+		}
+		backdate(skill.slug, 999);
+
+		const out = await captureStdout(() => runPrune({ json: true }, true));
+		const env = JSON.parse(out.trim());
+		expect(env.data.removed).toBe(false);
+		expect(env.data.candidates).toContain(skill.slug);
+
+		// Still present (dry run).
+		const after = createSkillStore(root);
+		try {
+			expect(after.get(skill.slug)).not.toBeNull();
+		} finally {
+			after.close();
+		}
+	});
+
+	test("--force deletes an aged quarantined skill", async () => {
+		const skill = seed();
+		const store = createSkillStore(root);
+		try {
+			store.setStatus(skill.slug, "quarantined");
+		} finally {
+			store.close();
+		}
+		backdate(skill.slug, 999);
+
+		await captureStdout(() => runPrune({ force: true, json: true }, true));
+
+		const after = createSkillStore(root);
+		try {
+			expect(after.get(skill.slug)).toBeNull();
+		} finally {
+			after.close();
+		}
+	});
+
+	test("a fresh quarantined skill is not a candidate", async () => {
+		const skill = seed();
+		const store = createSkillStore(root);
+		try {
+			store.setStatus(skill.slug, "quarantined");
+		} finally {
+			store.close();
+		}
+		// updatedAt is "now" (just set) — inside the window.
+
+		const out = await captureStdout(() => runPrune({ force: true, json: true }, true));
+		const env = JSON.parse(out.trim());
+		expect(env.data.candidates).toHaveLength(0);
+
+		const after = createSkillStore(root);
+		try {
+			expect(after.get(skill.slug)).not.toBeNull();
+		} finally {
+			after.close();
+		}
+	});
+
+	test("rejects a negative --max-age-days", () => {
+		expect(() => runPrune({ maxAgeDays: "-3", json: true }, true)).toThrow(ValidationError);
+	});
+});
+
+/**
+ * Rewrite a skill's `updatedAt` to `daysAgo` in the past to simulate an aged
+ * skill (no clock seam exists in the store). Round-trips through parse/serialize
+ * so the timestamp lands back as a properly-quoted string rather than a bare YAML
+ * scalar that js-yaml would re-interpret as a Date.
+ */
+function backdate(slug: string, daysAgo: number): void {
+	const file = join(root, AGENTPLATE_DIR, "skills", slug, "skill.md");
+	const skill = parseSkillMd(readFileSync(file, "utf8"));
+	skill.updatedAt = new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000).toISOString();
+	writeFileSync(file, serializeSkillMd(skill), "utf8");
+}
+
+// --- pure helpers: parseDraft --------------------------------------------
+
+describe("parseDraft", () => {
+	test("parses a well-formed create draft", () => {
+		const draft = parseDraft(
+			JSON.stringify({ action: "create", title: "X", whenToUse: ["a", 1, "b"] }),
+		);
+		expect(draft.action).toBe("create");
+		expect(draft.title).toBe("X");
+		// Non-string array elements are filtered out.
+		expect(draft.whenToUse).toEqual(["a", "b"]);
+	});
+
+	test("rejects empty input", () => {
+		expect(() => parseDraft("   ")).toThrow(ValidationError);
+	});
+
+	test("rejects malformed JSON", () => {
+		expect(() => parseDraft("{not json")).toThrow(ValidationError);
+	});
+
+	test("rejects a non-object", () => {
+		expect(() => parseDraft("[1,2,3]")).toThrow(ValidationError);
+		expect(() => parseDraft('"a string"')).toThrow(ValidationError);
+	});
+
+	test("rejects an unknown action", () => {
+		expect(() => parseDraft(JSON.stringify({ action: "frobnicate" }))).toThrow(ValidationError);
+	});
+});
+
+// --- pure helpers: scoreSkill / rankSkills --------------------------------
+
+/** Build a minimal Skill for ranking tests (only the fields the scorer reads). */
+function fakeSkill(overrides: Partial<Skill>): Skill {
+	return {
+		id: "id",
+		slug: "s",
+		title: "",
+		version: 1,
+		status: "active",
+		goal: "",
+		whenToUse: [],
+		filePatterns: [],
+		tags: [],
+		created: "",
+		updatedAt: "",
+		relatesTo: [],
+		supersedes: [],
+		body: "",
+		confidence: 0,
+		appliedCount: 0,
+		successCount: 0,
+		lastOutcome: null,
+		...overrides,
+	};
+}
+
+describe("scoreSkill / rankSkills", () => {
+	test("query-term overlap drives the score", () => {
+		const skill = fakeSkill({ title: "Add a CLI subcommand", goal: "Register on the program" });
+		const tokens = new Set(["cli", "subcommand"]);
+		expect(scoreSkill(skill, tokens, [])).toBeGreaterThan(0);
+		expect(scoreSkill(skill, new Set(["unrelated"]), [])).toBeCloseTo(0, 5);
+	});
+
+	test("file-pattern overlap adds to the score", () => {
+		const skill = fakeSkill({ filePatterns: ["src/commands/*.ts"] });
+		const withFile = scoreSkill(skill, new Set(), ["src/commands/skill.ts"]);
+		expect(withFile).toBeGreaterThan(0);
+	});
+
+	test("rankSkills orders by relevance and excludes non-active skills", () => {
+		const relevant = fakeSkill({ slug: "relevant", title: "git rebase workflow" });
+		const irrelevant = fakeSkill({ slug: "irrelevant", title: "something else entirely" });
+		const deprecated = fakeSkill({
+			slug: "deprecated-but-relevant",
+			title: "git rebase howto",
+			status: "deprecated",
+		});
+
+		const ranked = rankSkills([irrelevant, relevant, deprecated], "git rebase", []);
+		// Deprecated is dropped; only the relevant active skill survives the filter.
+		expect(ranked.map((r) => r.skill.slug)).toEqual(["relevant"]);
+	});
+
+	test("a blank query returns active skills ordered by confidence", () => {
+		const low = fakeSkill({ slug: "low", confidence: 0.1 });
+		const high = fakeSkill({ slug: "high", confidence: 0.9 });
+		const ranked = rankSkills([low, high], "", []);
+		expect(ranked.map((r) => r.skill.slug)).toEqual(["high", "low"]);
+	});
+});