@ag-eco/agentplate-cli 0.13.0

package/src/commands/spec.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Tests for the `agentplate spec` command.
+ *
+ * Uses real filesystem (temp dirs) for all tests. No mocks.
+ * Philosophy: "never mock what you can use for real" (mx-252b16).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import { specWriteCommand, writeSpec } from "./spec.ts";
+
+let tempDir: string;
+let agentplateDir: string;
+let originalCwd: string;
+let stdoutOutput: string;
+let _stderrOutput: string;
+let originalStdoutWrite: typeof process.stdout.write;
+let originalStderrWrite: typeof process.stderr.write;
+
+beforeEach(async () => {
+	tempDir = await createTempGitRepo();
+	agentplateDir = join(tempDir, ".agentplate");
+	await mkdir(agentplateDir, { recursive: true });
+
+	// Write minimal config.yaml so resolveProjectRoot works
+	await Bun.write(
+		join(agentplateDir, "config.yaml"),
+		`project:\n  name: test-project\n  root: ${tempDir}\n  canonicalBranch: main\n`,
+	);
+
+	originalCwd = process.cwd();
+	process.chdir(tempDir);
+
+	// Capture stdout/stderr
+	stdoutOutput = "";
+	_stderrOutput = "";
+	originalStdoutWrite = process.stdout.write;
+	originalStderrWrite = process.stderr.write;
+	process.stdout.write = ((chunk: string) => {
+		stdoutOutput += chunk;
+		return true;
+	}) as typeof process.stdout.write;
+	process.stderr.write = ((chunk: string) => {
+		_stderrOutput += chunk;
+		return true;
+	}) as typeof process.stderr.write;
+});
+
+afterEach(async () => {
+	process.chdir(originalCwd);
+	process.stdout.write = originalStdoutWrite;
+	process.stderr.write = originalStderrWrite;
+	await cleanupTempDir(tempDir);
+});
+
+// === validation ===
+
+describe("validation", () => {
+	test("write without task-id throws ValidationError", async () => {
+		await expect(specWriteCommand("", {})).rejects.toThrow("Task ID is required");
+	});
+
+	test("write without body throws ValidationError", async () => {
+		await expect(specWriteCommand("task-abc", { agent: "scout-1" })).rejects.toThrow(
+			"Spec body is required",
+		);
+	});
+
+	test("write with empty body throws ValidationError", async () => {
+		await expect(specWriteCommand("task-abc", { body: "  " })).rejects.toThrow(
+			"Spec body is required",
+		);
+	});
+});
+
+// === writeSpec (core function) ===
+
+describe("writeSpec", () => {
+	test("writes spec file to .agentplate/specs/<bead-id>.md", async () => {
+		const specPath = await writeSpec(tempDir, "task-abc", "# My Spec\n\nDetails here.");
+
+		expect(specPath).toBe(join(tempDir, ".agentplate", "specs", "task-abc.md"));
+
+		const content = await Bun.file(specPath).text();
+		expect(content).toBe("# My Spec\n\nDetails here.\n");
+	});
+
+	test("creates specs directory if it does not exist", async () => {
+		// Verify specs dir does not exist yet
+		const specsDir = join(agentplateDir, "specs");
+		expect(await Bun.file(join(specsDir, ".gitkeep")).exists()).toBe(false);
+
+		await writeSpec(tempDir, "task-xyz", "content");
+
+		const content = await Bun.file(join(specsDir, "task-xyz.md")).text();
+		expect(content).toBe("content\n");
+	});
+
+	test("adds attribution header when agent is provided", async () => {
+		const specPath = await writeSpec(tempDir, "task-123", "# Spec body", "scout-1");
+
+		const content = await Bun.file(specPath).text();
+		expect(content).toContain("<!-- written-by: scout-1 -->");
+		expect(content).toContain("# Spec body");
+	});
+
+	test("does not add attribution header when agent is omitted", async () => {
+		const specPath = await writeSpec(tempDir, "task-456", "# Spec body");
+
+		const content = await Bun.file(specPath).text();
+		expect(content).not.toContain("written-by");
+		expect(content).toBe("# Spec body\n");
+	});
+
+	test("ensures trailing newline", async () => {
+		const specPath = await writeSpec(tempDir, "task-nl", "no newline at end");
+
+		const content = await Bun.file(specPath).text();
+		expect(content.endsWith("\n")).toBe(true);
+	});
+
+	test("does not double trailing newline", async () => {
+		const specPath = await writeSpec(tempDir, "task-nl2", "already has newline\n");
+
+		const content = await Bun.file(specPath).text();
+		expect(content).toBe("already has newline\n");
+		expect(content.endsWith("\n\n")).toBe(false);
+	});
+
+	test("overwrites existing spec file", async () => {
+		await writeSpec(tempDir, "task-ow", "version 1");
+		await writeSpec(tempDir, "task-ow", "version 2");
+
+		const specPath = join(agentplateDir, "specs", "task-ow.md");
+		const content = await Bun.file(specPath).text();
+		expect(content).toBe("version 2\n");
+	});
+});
+
+// === specWriteCommand (CLI integration) ===
+
+describe("specWriteCommand (integration)", () => {
+	test("writes spec and prints success", async () => {
+		await specWriteCommand("task-cmd", { body: "# CLI Spec" });
+
+		expect(stdoutOutput).toContain("Spec written");
+		expect(stdoutOutput).toContain("task-cmd");
+
+		const specPath = join(tempDir, ".agentplate", "specs", "task-cmd.md");
+		const content = await Bun.file(specPath).text();
+		expect(content).toBe("# CLI Spec\n");
+	});
+
+	test("writes spec with agent attribution", async () => {
+		await specWriteCommand("task-attr", { body: "# Attributed", agent: "scout-2" });
+
+		expect(stdoutOutput).toContain("Spec written");
+		expect(stdoutOutput).toContain("task-attr");
+
+		const specPath = join(tempDir, ".agentplate", "specs", "task-attr.md");
+		const content = await Bun.file(specPath).text();
+		expect(content).toContain("<!-- written-by: scout-2 -->");
+		expect(content).toContain("# Attributed");
+	});
+
+	test("writes spec without agent when agent is omitted", async () => {
+		await specWriteCommand("task-noagent", { body: "# No Agent" });
+
+		expect(stdoutOutput).toContain("Spec written");
+		expect(stdoutOutput).toContain("task-noagent");
+
+		const specPath = join(tempDir, ".agentplate", "specs", "task-noagent.md");
+		const content = await Bun.file(specPath).text();
+		expect(content).not.toContain("written-by");
+		expect(content).toBe("# No Agent\n");
+	});
+});

package/src/commands/spec.ts

@@ -0,0 +1,105 @@
+/**
+ * CLI command: ap spec write <bead-id> --body <content>
+ *
+ * Writes a task specification to `.agentplate/specs/<task-id>.md`.
+ * Scouts use this to persist spec documents as files instead of
+ * sending entire specs via mail messages.
+ *
+ * Supports reading body content from --body flag or stdin.
+ */
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { printSuccess } from "../logging/color.ts";
+
+export interface SpecWriteOptions {
+	body?: string;
+	agent?: string;
+	json?: boolean;
+}
+
+/**
+ * Read all of stdin as a string. Returns empty string if stdin is a TTY
+ * (no piped input).
+ */
+async function readStdin(): Promise<string> {
+	// Bun.stdin is a ReadableStream when piped, a TTY otherwise
+	if (process.stdin.isTTY) {
+		return "";
+	}
+	return await new Response(Bun.stdin.stream()).text();
+}
+
+/**
+ * Write a spec file to .agentplate/specs/<task-id>.md.
+ *
+ * Exported for direct use in tests.
+ */
+export async function writeSpec(
+	projectRoot: string,
+	taskId: string,
+	body: string,
+	agent?: string,
+): Promise<string> {
+	const specsDir = join(projectRoot, ".agentplate", "specs");
+	await mkdir(specsDir, { recursive: true });
+
+	// Build the spec content with optional attribution header
+	let content = "";
+	if (agent) {
+		content += `<!-- written-by: ${agent} -->\n`;
+	}
+	content += body;
+
+	// Ensure trailing newline
+	if (!content.endsWith("\n")) {
+		content += "\n";
+	}
+
+	const specPath = join(specsDir, `${taskId}.md`);
+	await Bun.write(specPath, content);
+
+	return specPath;
+}
+
+/**
+ * Entry point for `ap spec write <bead-id> [flags]`.
+ *
+ * @param taskId - The task ID for the spec file
+ * @param opts - Command options
+ */
+export async function specWriteCommand(taskId: string, opts: SpecWriteOptions): Promise<void> {
+	if (!taskId || taskId.trim().length === 0) {
+		throw new ValidationError("Task ID is required: ap spec write <task-id> --body <content>", {
+			field: "taskId",
+		});
+	}
+
+	let body = opts.body;
+
+	// If no --body flag, try reading from stdin
+	if (body === undefined) {
+		const stdinContent = await readStdin();
+		if (stdinContent.trim().length > 0) {
+			body = stdinContent;
+		}
+	}
+
+	if (body === undefined || body.trim().length === 0) {
+		throw new ValidationError("Spec body is required: use --body <content> or pipe via stdin", {
+			field: "body",
+		});
+	}
+
+	const { resolveProjectRoot } = await import("../config.ts");
+	const projectRoot = await resolveProjectRoot(process.cwd());
+
+	const specPath = await writeSpec(projectRoot, taskId, body, opts.agent);
+	if (opts.json) {
+		jsonOutput("spec-write", { taskId, path: specPath });
+	} else {
+		printSuccess("Spec written", taskId);
+	}
+}