@os-eco/overstory-cli 0.6.1

package/src/commands/spec.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Tests for the `overstory 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 { specCommand, writeSpec } from "./spec.ts";
+
+let tempDir: string;
+let overstoryDir: 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();
+	overstoryDir = join(tempDir, ".overstory");
+	await mkdir(overstoryDir, { recursive: true });
+
+	// Write minimal config.yaml so resolveProjectRoot works
+	await Bun.write(
+		join(overstoryDir, "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);
+});
+
+// === help ===
+
+describe("help", () => {
+	test("--help shows usage", async () => {
+		await specCommand(["--help"]);
+		expect(stdoutOutput).toContain("overstory spec");
+		expect(stdoutOutput).toContain("write");
+		expect(stdoutOutput).toContain("--body");
+		expect(stdoutOutput).toContain("--agent");
+	});
+
+	test("-h shows usage", async () => {
+		await specCommand(["-h"]);
+		expect(stdoutOutput).toContain("overstory spec");
+	});
+
+	test("no args shows help", async () => {
+		await specCommand([]);
+		expect(stdoutOutput).toContain("overstory spec");
+	});
+});
+
+// === validation ===
+
+describe("validation", () => {
+	test("unknown subcommand throws ValidationError", async () => {
+		await expect(specCommand(["unknown"])).rejects.toThrow("Unknown spec subcommand");
+	});
+
+	test("write without bead-id throws ValidationError", async () => {
+		await expect(specCommand(["write"])).rejects.toThrow("Bead ID is required");
+	});
+
+	test("write without body throws ValidationError", async () => {
+		await expect(specCommand(["write", "task-abc", "--agent", "scout-1"])).rejects.toThrow(
+			"Spec body is required",
+		);
+	});
+
+	test("write with empty body throws ValidationError", async () => {
+		await expect(specCommand(["write", "task-abc", "--body", "  "])).rejects.toThrow(
+			"Spec body is required",
+		);
+	});
+});
+
+// === writeSpec (core function) ===
+
+describe("writeSpec", () => {
+	test("writes spec file to .overstory/specs/<bead-id>.md", async () => {
+		const specPath = await writeSpec(tempDir, "task-abc", "# My Spec\n\nDetails here.");
+
+		expect(specPath).toBe(join(tempDir, ".overstory", "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(overstoryDir, "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(overstoryDir, "specs", "task-ow.md");
+		const content = await Bun.file(specPath).text();
+		expect(content).toBe("version 2\n");
+	});
+});
+
+// === specCommand (CLI integration) ===
+
+describe("specCommand write", () => {
+	test("writes spec and prints path", async () => {
+		await specCommand(["write", "task-cmd", "--body", "# CLI Spec"]);
+
+		// Path may differ due to macOS /var -> /private/var symlink resolution
+		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-cmd.md");
+
+		const specPath = stdoutOutput.trim();
+		const content = await Bun.file(specPath).text();
+		expect(content).toBe("# CLI Spec\n");
+	});
+
+	test("writes spec with agent attribution", async () => {
+		await specCommand(["write", "task-attr", "--body", "# Attributed", "--agent", "scout-2"]);
+
+		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-attr.md");
+
+		const specPath = stdoutOutput.trim();
+		const content = await Bun.file(specPath).text();
+		expect(content).toContain("<!-- written-by: scout-2 -->");
+		expect(content).toContain("# Attributed");
+	});
+
+	test("flags can appear in any order", async () => {
+		await specCommand(["write", "--agent", "scout-3", "--body", "# Content", "task-order"]);
+
+		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-order.md");
+
+		const specPath = stdoutOutput.trim();
+		const content = await Bun.file(specPath).text();
+		expect(content).toContain("<!-- written-by: scout-3 -->");
+		expect(content).toContain("# Content");
+	});
+});

package/src/commands/spec.ts

@@ -0,0 +1,168 @@
+/**
+ * CLI command: overstory spec write <bead-id> --body <content>
+ *
+ * Writes a task specification to `.overstory/specs/<bead-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";
+
+/** Boolean flags that do NOT consume the next arg. */
+const BOOLEAN_FLAGS = new Set(["--help", "-h"]);
+
+/**
+ * Parse a named flag value from args.
+ */
+function getFlag(args: string[], flag: string): string | undefined {
+	const idx = args.indexOf(flag);
+	if (idx === -1 || idx + 1 >= args.length) {
+		return undefined;
+	}
+	return args[idx + 1];
+}
+
+/**
+ * Extract positional arguments, skipping flag-value pairs.
+ */
+function getPositionalArgs(args: string[]): string[] {
+	const positional: string[] = [];
+	let i = 0;
+	while (i < args.length) {
+		const arg = args[i];
+		if (arg?.startsWith("-")) {
+			if (BOOLEAN_FLAGS.has(arg)) {
+				i += 1;
+			} else {
+				i += 2;
+			}
+		} else {
+			if (arg !== undefined) {
+				positional.push(arg);
+			}
+			i += 1;
+		}
+	}
+	return positional;
+}
+
+/**
+ * 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();
+}
+
+const SPEC_HELP = `overstory spec -- Manage task specifications
+
+Usage: overstory spec <subcommand> [args...]
+
+Subcommands:
+  write <bead-id>          Write a spec file to .overstory/specs/<bead-id>.md
+
+Options for 'write':
+  --body <content>         Spec content (or pipe via stdin)
+  --agent <name>           Agent writing the spec (for attribution)
+  --help, -h               Show this help
+
+Examples:
+  overstory spec write task-abc --body "# Spec\\nDetails here..."
+  echo "# Spec" | overstory spec write task-abc
+  overstory spec write task-abc --body "..." --agent scout-1`;
+
+/**
+ * Write a spec file to .overstory/specs/<bead-id>.md.
+ *
+ * Exported for direct use in tests.
+ */
+export async function writeSpec(
+	projectRoot: string,
+	beadId: string,
+	body: string,
+	agent?: string,
+): Promise<string> {
+	const specsDir = join(projectRoot, ".overstory", "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, `${beadId}.md`);
+	await Bun.write(specPath, content);
+
+	return specPath;
+}
+
+/**
+ * Entry point for `overstory spec <subcommand>`.
+ */
+export async function specCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+		process.stdout.write(`${SPEC_HELP}\n`);
+		return;
+	}
+
+	const subcommand = args[0];
+	const subArgs = args.slice(1);
+
+	switch (subcommand) {
+		case "write": {
+			const positional = getPositionalArgs(subArgs);
+			const beadId = positional[0];
+			if (!beadId || beadId.trim().length === 0) {
+				throw new ValidationError(
+					"Bead ID is required: overstory spec write <bead-id> --body <content>",
+					{ field: "beadId" },
+				);
+			}
+
+			const agent = getFlag(subArgs, "--agent");
+			let body = getFlag(subArgs, "--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, beadId, body, agent);
+			process.stdout.write(`${specPath}\n`);
+			break;
+		}
+
+		default:
+			throw new ValidationError(
+				`Unknown spec subcommand: ${subcommand}. Run 'overstory spec --help' for usage.`,
+				{ field: "subcommand", value: subcommand },
+			);
+	}
+}