@os-eco/overstory-cli 0.6.1

package/src/agents/overlay.ts

@@ -0,0 +1,308 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { AgentError } from "../errors.ts";
+import type { OverlayConfig, QualityGate } from "../types.ts";
+
+/**
+ * Resolve the path to the overlay template file.
+ * The template lives at `templates/overlay.md.tmpl` relative to the repo root.
+ */
+function getTemplatePath(): string {
+	// src/agents/overlay.ts -> repo root is ../../
+	return join(dirname(import.meta.dir), "..", "templates", "overlay.md.tmpl");
+}
+
+/**
+ * Format the file scope list as a markdown bullet list.
+ * Returns a human-readable fallback if no files are scoped.
+ */
+function formatFileScope(fileScope: readonly string[]): string {
+	if (fileScope.length === 0) {
+		return "No file scope restrictions";
+	}
+	return fileScope.map((f) => `- \`${f}\``).join("\n");
+}
+
+/**
+ * Format mulch domains as a `mulch prime` command.
+ * Returns a human-readable fallback if no domains are configured.
+ */
+function formatMulchDomains(domains: readonly string[]): string {
+	if (domains.length === 0) {
+		return "No specific expertise domains configured";
+	}
+	return `\`\`\`bash\nmulch prime ${domains.join(" ")}\n\`\`\``;
+}
+
+/**
+ * Format pre-fetched mulch expertise for embedding in the overlay.
+ * Returns empty string if no expertise was provided (omits the section entirely).
+ * When expertise IS provided, renders it under a 'Pre-loaded Expertise' heading
+ * with a brief intro explaining it was loaded at spawn time based on file scope.
+ */
+function formatMulchExpertise(expertise: string | undefined): string {
+	if (!expertise || expertise.trim().length === 0) {
+		return "";
+	}
+	return [
+		"### Pre-loaded Expertise",
+		"",
+		"The following expertise was automatically loaded at spawn time based on your file scope:",
+		"",
+		expertise,
+	].join("\n");
+}
+
+/** Capabilities that are read-only and should not get quality gates for commits/tests/lint. */
+const READ_ONLY_CAPABILITIES = new Set(["scout", "reviewer"]);
+
+/**
+ * The skip-scout section injected into lead overlays when --skip-scout is passed.
+ * Instructs the lead to bypass Phase 1 (exploration) and go straight to Phase 2 (build).
+ */
+const SKIP_SCOUT_SECTION = `
+## Skip Scout Mode
+
+**IMPORTANT**: You have been spawned with \`--skip-scout\`. Skip Phase 1 (Scout) entirely.
+Go directly to Phase 2 (Build): write specs from your existing knowledge and the
+pre-loaded expertise above, then spawn builders immediately.
+
+Do NOT spawn scout agents. Do NOT explore the codebase extensively.
+Your parent has already gathered the context you need.
+`;
+
+/**
+ * Format the quality gates section. Read-only agents (scout, reviewer) get
+ * a lightweight section that only tells them to close the issue and report.
+ * Writable agents get the full quality gates (tests, lint, build, commit).
+ */
+/** Default quality gates used when none are configured. */
+const DEFAULT_GATES: QualityGate[] = [
+	{ name: "Tests", command: "bun test", description: "all tests must pass" },
+	{ name: "Lint", command: "bun run lint", description: "zero errors" },
+	{ name: "Typecheck", command: "bun run typecheck", description: "no TypeScript errors" },
+];
+
+function formatQualityGates(config: OverlayConfig): string {
+	if (READ_ONLY_CAPABILITIES.has(config.capability)) {
+		return [
+			"## Completion",
+			"",
+			"Before reporting completion:",
+			"",
+			`1. **Record mulch learnings:** \`mulch record <domain> --type <convention|pattern|reference> --description "..."\` — capture reusable knowledge from your work`,
+			`2. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.beadId} --reason "summary of findings"\``,
+			`3. **Send results:** \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "done" --body "Summary" --type result --agent ${config.agentName}\``,
+			"",
+			"You are a read-only agent. Do NOT commit, modify files, or run quality gates.",
+		].join("\n");
+	}
+
+	const gates =
+		config.qualityGates && config.qualityGates.length > 0 ? config.qualityGates : DEFAULT_GATES;
+
+	const gateLines = gates.map(
+		(gate, i) => `${i + 1}. **${gate.name}:** \`${gate.command}\` — ${gate.description}`,
+	);
+
+	return [
+		"## Quality Gates",
+		"",
+		"Before reporting completion, you MUST pass all quality gates:",
+		"",
+		...gateLines,
+		`${gateLines.length + 1}. **Commit:** all changes committed to your branch (${config.branchName})`,
+		`${gateLines.length + 2}. **Record mulch learnings:** \`mulch record <domain> --type <convention|pattern|failure|decision> --description "..." --outcome-status success --outcome-agent ${config.agentName}\` — capture insights from your work`,
+		`${gateLines.length + 3}. **Signal completion:** send \`worker_done\` mail to ${config.parentAgent ?? "coordinator"}: \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "Worker done: ${config.beadId}" --body "Quality gates passed." --type worker_done --agent ${config.agentName}\``,
+		`${gateLines.length + 4}. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.beadId} --reason "summary of changes"\``,
+		"",
+		"Do NOT push to the canonical branch. Your work will be merged by the",
+		"coordinator via `overstory merge`.",
+	].join("\n");
+}
+
+/**
+ * Format the constraints section. Read-only agents get read-only constraints.
+ * Writable agents get file-scope and branch constraints.
+ */
+function formatConstraints(config: OverlayConfig): string {
+	if (READ_ONLY_CAPABILITIES.has(config.capability)) {
+		return [
+			"## Constraints",
+			"",
+			"- You are **read-only**: do NOT modify, create, or delete any files",
+			"- Do NOT commit, push, or make any git state changes",
+			`- Report completion via \`${config.trackerCli ?? "bd"} close\` AND \`overstory mail send --type result\``,
+			"- If you encounter a blocking issue, send mail with `--priority urgent --type error`",
+		].join("\n");
+	}
+
+	return [
+		"## Constraints",
+		"",
+		`- **WORKTREE ISOLATION**: All writes MUST target files within your worktree at \`${config.worktreePath}\``,
+		"- NEVER write to the canonical repo root — all writes go to your worktree copy",
+		"- Only modify files in your File Scope",
+		`- Commit only to your branch: ${config.branchName}`,
+		"- Never push to the canonical branch",
+		`- Report completion via \`${config.trackerCli ?? "bd"} close\` AND \`overstory mail send --type result\``,
+		"- If you encounter a blocking issue, send mail with `--priority urgent --type error`",
+	].join("\n");
+}
+
+/**
+ * Format the can-spawn section. If the agent can spawn sub-workers,
+ * include an example sling command. Otherwise, state the restriction.
+ */
+function formatCanSpawn(config: OverlayConfig): string {
+	if (!config.canSpawn) {
+		return "You may NOT spawn sub-workers.";
+	}
+	return [
+		"You may spawn sub-workers using `overstory sling`. Example:",
+		"",
+		"```bash",
+		"overstory sling <task-id> --capability builder --name <worker-name> \\",
+		`  --parent ${config.agentName} --depth ${config.depth + 1}`,
+		"```",
+	].join("\n");
+}
+
+/**
+ * Generate a per-worker CLAUDE.md overlay from the template.
+ *
+ * Reads `templates/overlay.md.tmpl` and replaces all `{{VARIABLE}}`
+ * placeholders with values derived from the provided config.
+ *
+ * @param config - The overlay configuration for this agent/task
+ * @returns The rendered overlay content as a string
+ * @throws {AgentError} If the template file cannot be found or read
+ */
+export async function generateOverlay(config: OverlayConfig): Promise<string> {
+	const templatePath = getTemplatePath();
+	const file = Bun.file(templatePath);
+	const exists = await file.exists();
+
+	if (!exists) {
+		throw new AgentError(`Overlay template not found: ${templatePath}`, {
+			agentName: config.agentName,
+		});
+	}
+
+	let template: string;
+	try {
+		template = await file.text();
+	} catch (err) {
+		throw new AgentError(`Failed to read overlay template: ${templatePath}`, {
+			agentName: config.agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	const specInstruction = config.specPath
+		? "Read your task spec at the path above. It contains the full description of\nwhat you need to build or review."
+		: "No task spec was provided. Check your mail or ask your parent agent for details.";
+
+	const replacements: Record<string, string> = {
+		"{{AGENT_NAME}}": config.agentName,
+		"{{BEAD_ID}}": config.beadId,
+		"{{SPEC_PATH}}": config.specPath ?? "No spec file provided",
+		"{{BRANCH_NAME}}": config.branchName,
+		"{{WORKTREE_PATH}}": config.worktreePath,
+		"{{PARENT_AGENT}}": config.parentAgent ?? "coordinator",
+		"{{DEPTH}}": String(config.depth),
+		"{{FILE_SCOPE}}": formatFileScope(config.fileScope),
+		"{{MULCH_DOMAINS}}": formatMulchDomains(config.mulchDomains),
+		"{{MULCH_EXPERTISE}}": formatMulchExpertise(config.mulchExpertise),
+		"{{CAN_SPAWN}}": formatCanSpawn(config),
+		"{{QUALITY_GATES}}": formatQualityGates(config),
+		"{{CONSTRAINTS}}": formatConstraints(config),
+		"{{SPEC_INSTRUCTION}}": specInstruction,
+		"{{SKIP_SCOUT}}": config.skipScout ? SKIP_SCOUT_SECTION : "",
+		"{{BASE_DEFINITION}}": config.baseDefinition,
+		"{{TRACKER_CLI}}": config.trackerCli ?? "bd",
+		"{{TRACKER_NAME}}": config.trackerName ?? "beads",
+	};
+
+	let result = template;
+	for (const [placeholder, value] of Object.entries(replacements)) {
+		// Replace all occurrences — some placeholders appear multiple times
+		while (result.includes(placeholder)) {
+			result = result.replace(placeholder, value);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Check whether a directory is the canonical project root by comparing resolved paths.
+ *
+ * Agent overlays must NEVER be written to the canonical repo root -- they belong
+ * in worktrees. Writing an overlay to the project root overwrites the orchestrator's
+ * `.claude/CLAUDE.md`, breaking the user's own Claude Code session (overstory-uwg4).
+ *
+ * Uses deterministic path comparison instead of checking for `.overstory/config.yaml`
+ * because when dogfooding (running overstory on its own repo), that file is tracked
+ * in git and appears in every worktree checkout (overstory-p4st).
+ *
+ * @param dir - Absolute path to check
+ * @param canonicalRoot - Absolute path to the canonical project root
+ * @returns true if dir resolves to the same path as canonicalRoot
+ */
+export function isCanonicalRoot(dir: string, canonicalRoot: string): boolean {
+	return resolve(dir) === resolve(canonicalRoot);
+}
+
+/**
+ * Generate the overlay and write it to `{worktreePath}/.claude/CLAUDE.md`.
+ * Creates the `.claude/` directory if it does not exist.
+ *
+ * Includes a safety guard that prevents writing to the canonical project root.
+ * Agent overlays belong in worktrees, never at the orchestrator's root.
+ *
+ * @param worktreePath - Absolute path to the agent's git worktree
+ * @param config - The overlay configuration for this agent/task
+ * @param canonicalRoot - Absolute path to the canonical project root (for guard check)
+ * @throws {AgentError} If worktreePath is the canonical project root, or if
+ *   the directory cannot be created or the file cannot be written
+ */
+export async function writeOverlay(
+	worktreePath: string,
+	config: OverlayConfig,
+	canonicalRoot: string,
+): Promise<void> {
+	// Guard: never write agent overlays to the canonical project root.
+	// The project root's .claude/CLAUDE.md belongs to the orchestrator/user.
+	// Uses path comparison instead of file-existence heuristic to handle
+	// dogfooding scenarios where .overstory/config.yaml is tracked in git
+	// and appears in every worktree checkout (overstory-p4st).
+	if (isCanonicalRoot(worktreePath, canonicalRoot)) {
+		throw new AgentError(
+			`Refusing to write overlay to canonical project root: ${worktreePath}. Agent overlays must target a worktree, not the orchestrator's root directory. This prevents overwriting the user's .claude/CLAUDE.md.`,
+			{ agentName: config.agentName },
+		);
+	}
+
+	const content = await generateOverlay(config);
+	const claudeDir = join(worktreePath, ".claude");
+	const outputPath = join(claudeDir, "CLAUDE.md");
+
+	try {
+		await mkdir(claudeDir, { recursive: true });
+	} catch (err) {
+		throw new AgentError(`Failed to create .claude/ directory at: ${claudeDir}`, {
+			agentName: config.agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	try {
+		await Bun.write(outputPath, content);
+	} catch (err) {
+		throw new AgentError(`Failed to write overlay to: ${outputPath}`, {
+			agentName: config.agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}

package/src/beads/client.test.ts

@@ -0,0 +1,217 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { realpathSync } from "node:fs";
+import { AgentError } from "../errors.ts";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import { type BeadsClient, createBeadsClient } from "./client.ts";
+
+/**
+ * Check if the bd CLI is available on this machine (synchronous).
+ * Uses Bun.spawnSync so the result is available at test registration time
+ * for use with test.skipIf().
+ */
+function isBdAvailable(): boolean {
+	try {
+		const result = Bun.spawnSync(["bd", "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		return result.exitCode === 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Initialize beads in a git repo directory.
+ */
+async function initBeads(cwd: string): Promise<void> {
+	const proc = Bun.spawn(["bd", "init"], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		const stderr = await new Response(proc.stderr).text();
+		throw new Error(`bd init failed: ${stderr}`);
+	}
+}
+
+const bdAvailable = isBdAvailable();
+
+/**
+ * Optimized test suite: uses a single shared repo (beforeAll) instead of
+ * creating a fresh repo per test. All 16 original tests share one repo
+ * since they create issues with unique IDs and use toContain/not.toContain
+ * assertions. This reduces setup from ~96 subprocess spawns to ~6.
+ */
+describe("createBeadsClient (integration)", () => {
+	let tempDir: string;
+	let client: BeadsClient;
+
+	// Pre-created issue IDs for tests that need existing issues
+	let openIssueId: string;
+	let claimedIssueId: string;
+	let closedIssueId: string;
+
+	beforeAll(async () => {
+		if (!bdAvailable) return;
+		// realpathSync resolves macOS /var -> /private/var symlink so paths match
+		tempDir = realpathSync(await createTempGitRepo());
+		await initBeads(tempDir);
+		client = createBeadsClient(tempDir);
+
+		// Pre-create issues used by read-only tests (list, ready, show)
+		openIssueId = await client.create("Pre-created open issue");
+		claimedIssueId = await client.create("Pre-created claimed issue");
+		await client.claim(claimedIssueId);
+		closedIssueId = await client.create("Pre-created closed issue");
+		await client.close(closedIssueId);
+	});
+
+	afterAll(async () => {
+		if (!bdAvailable) return;
+		await cleanupTempDir(tempDir);
+	});
+
+	describe("create", () => {
+		test.skipIf(!bdAvailable)("returns an issue ID", async () => {
+			const id = await client.create("Integration test issue");
+
+			expect(typeof id).toBe("string");
+			expect(id.length).toBeGreaterThan(0);
+		});
+
+		test.skipIf(!bdAvailable)("returns ID with type and priority options", async () => {
+			const id = await client.create("Typed issue", {
+				type: "bug",
+				priority: 1,
+			});
+
+			expect(typeof id).toBe("string");
+			expect(id.length).toBeGreaterThan(0);
+		});
+
+		test.skipIf(!bdAvailable)("returns ID with description option", async () => {
+			const id = await client.create("Described issue", {
+				description: "A detailed description",
+			});
+
+			expect(typeof id).toBe("string");
+			expect(id.length).toBeGreaterThan(0);
+		});
+	});
+
+	describe("show", () => {
+		test.skipIf(!bdAvailable)("returns issue details for a valid ID", async () => {
+			const id = await client.create("Show test issue", {
+				type: "task",
+				priority: 2,
+			});
+
+			const issue = await client.show(id);
+
+			expect(issue.id).toBe(id);
+			expect(issue.title).toBe("Show test issue");
+			expect(issue.status).toBe("open");
+			expect(issue.priority).toBe(2);
+			expect(issue.type).toBe("task");
+		});
+	});
+
+	describe("claim", () => {
+		test.skipIf(!bdAvailable)("changes issue status to in_progress and returns void", async () => {
+			const id = await client.create("Claim test issue");
+
+			const result = await client.claim(id);
+			expect(result).toBeUndefined();
+
+			const issue = await client.show(id);
+			expect(issue.status).toBe("in_progress");
+		});
+	});
+
+	describe("close", () => {
+		test.skipIf(!bdAvailable)("closes issues with and without reason", async () => {
+			const id1 = await client.create("Close test issue");
+			const id2 = await client.create("Close reason test");
+
+			await client.close(id1);
+			await client.close(id2, "Completed all acceptance criteria");
+
+			const issue1 = await client.show(id1);
+			expect(issue1.status).toBe("closed");
+
+			const issue2 = await client.show(id2);
+			expect(issue2.status).toBe("closed");
+		});
+	});
+
+	describe("list", () => {
+		test.skipIf(!bdAvailable)("returns all issues", async () => {
+			const issues = await client.list();
+
+			// Pre-created issues should be present (plus any from other tests)
+			expect(issues.length).toBeGreaterThanOrEqual(3);
+			const titles = issues.map((i) => i.title);
+			expect(titles).toContain("Pre-created open issue");
+			expect(titles).toContain("Pre-created claimed issue");
+		});
+
+		test.skipIf(!bdAvailable)("filters by status", async () => {
+			const openIssues = await client.list({ status: "open" });
+			const openIds = openIssues.map((i) => i.id);
+			expect(openIds).toContain(openIssueId);
+			expect(openIds).not.toContain(claimedIssueId);
+			expect(openIds).not.toContain(closedIssueId);
+
+			const inProgressIssues = await client.list({ status: "in_progress" });
+			const inProgressIds = inProgressIssues.map((i) => i.id);
+			expect(inProgressIds).toContain(claimedIssueId);
+			expect(inProgressIds).not.toContain(openIssueId);
+		});
+
+		test.skipIf(!bdAvailable)("respects limit option", async () => {
+			const limited = await client.list({ limit: 1 });
+			expect(limited).toHaveLength(1);
+		});
+	});
+
+	describe("ready", () => {
+		test.skipIf(!bdAvailable)(
+			"returns open unblocked issues but not claimed or closed",
+			async () => {
+				const readyIssues = await client.ready();
+				const readyIds = readyIssues.map((i) => i.id);
+
+				// Open issue should appear in ready
+				expect(readyIds).toContain(openIssueId);
+				// Claimed issue should not appear in ready
+				expect(readyIds).not.toContain(claimedIssueId);
+				// Closed issue should not appear in ready
+				expect(readyIds).not.toContain(closedIssueId);
+			},
+		);
+	});
+
+	describe("error handling", () => {
+		test.skipIf(!bdAvailable)("show throws AgentError for nonexistent ID", async () => {
+			await expect(client.show("nonexistent-id")).rejects.toThrow(AgentError);
+		});
+
+		test.skipIf(!bdAvailable)(
+			"throws AgentError when bd is run without beads initialized",
+			async () => {
+				// Create a git repo without bd init — independent from shared repo
+				const bareDir = realpathSync(await createTempGitRepo());
+				const bareClient = createBeadsClient(bareDir);
+
+				try {
+					await expect(bareClient.list()).rejects.toThrow(AgentError);
+				} finally {
+					await cleanupTempDir(bareDir);
+				}
+			},
+		);
+	});
+});