@mainahq/core 0.2.0

package/src/design/index.ts

@@ -0,0 +1,297 @@
+/**
+ * Architecture Decision Record (ADR) management.
+ *
+ * Handles auto-numbering, scaffolding MADR templates, and listing ADRs.
+ * ADRs capture WHAT and WHY — no implementation details.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tryAIGenerate } from "../ai/try-generate";
+import type { Result } from "../db/index";
+import { toKebabCase } from "../utils";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface AdrSummary {
+	number: string;
+	title: string;
+	status: string;
+	path: string;
+}
+
+/**
+ * Extract numeric prefix from an ADR filename.
+ * Returns the number if the name matches NNNN-*.md pattern, or null.
+ */
+function extractNumber(name: string): number | null {
+	const match = name.match(/^(\d{4})-.*\.md$/);
+	if (!match?.[1]) return null;
+	return Number.parseInt(match[1], 10);
+}
+
+// ── MADR Template ────────────────────────────────────────────────────────────
+
+function buildMadrTemplate(number: string, title: string): string {
+	const today = new Date().toISOString().split("T")[0];
+	return `# ${number}. ${title}
+
+Date: ${today}
+
+## Status
+
+Proposed
+
+## Context
+
+What is the issue that we're seeing that is motivating this decision or change?
+
+[NEEDS CLARIFICATION] Describe the context.
+
+## Decision
+
+What is the change that we're proposing and/or doing?
+
+[NEEDS CLARIFICATION] Describe the decision.
+
+## Consequences
+
+What becomes easier or more difficult to do because of this change?
+
+### Positive
+
+- [NEEDS CLARIFICATION]
+
+### Negative
+
+- [NEEDS CLARIFICATION]
+
+### Neutral
+
+- [NEEDS CLARIFICATION]
+
+## High-Level Design
+
+### System Overview
+
+[NEEDS CLARIFICATION]
+
+### Component Boundaries
+
+[NEEDS CLARIFICATION]
+
+### Data Flow
+
+[NEEDS CLARIFICATION]
+
+### External Dependencies
+
+[NEEDS CLARIFICATION]
+
+## Low-Level Design
+
+### Interfaces & Types
+
+[NEEDS CLARIFICATION]
+
+### Function Signatures
+
+[NEEDS CLARIFICATION]
+
+### DB Schema Changes
+
+[NEEDS CLARIFICATION]
+
+### Sequence of Operations
+
+[NEEDS CLARIFICATION]
+
+### Error Handling
+
+[NEEDS CLARIFICATION]
+
+### Edge Cases
+
+[NEEDS CLARIFICATION]
+`;
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Scan `adr/` directory for existing ADRs (files named NNNN-*.md),
+ * and return the next number zero-padded to 4 digits.
+ *
+ * Empty dir -> "0001". Existing 0001, 0002 -> "0003".
+ * Creates adr/ if it doesn't exist.
+ */
+export async function getNextAdrNumber(
+	adrDir: string,
+): Promise<Result<string>> {
+	try {
+		if (!existsSync(adrDir)) {
+			mkdirSync(adrDir, { recursive: true });
+			return { ok: true, value: "0001" };
+		}
+
+		const entries = readdirSync(adrDir);
+		let maxNumber = 0;
+
+		for (const entry of entries) {
+			const num = extractNumber(entry);
+			if (num !== null && num > maxNumber) {
+				maxNumber = num;
+			}
+		}
+
+		const next = (maxNumber + 1).toString().padStart(4, "0");
+		return { ok: true, value: next };
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		return {
+			ok: false,
+			error: `Failed to get next ADR number: ${message}`,
+		};
+	}
+}
+
+/**
+ * Create `adr/NNNN-kebab-title.md` using the MADR template.
+ * Returns the file path on success.
+ */
+export async function scaffoldAdr(
+	adrDir: string,
+	number: string,
+	title: string,
+): Promise<Result<string>> {
+	try {
+		const kebabTitle = toKebabCase(title);
+		const filename = `${number}-${kebabTitle}.md`;
+		const filePath = join(adrDir, filename);
+
+		if (!existsSync(adrDir)) {
+			mkdirSync(adrDir, { recursive: true });
+		}
+
+		const content = buildMadrTemplate(number, title);
+		await Bun.write(filePath, content);
+
+		return { ok: true, value: filePath };
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		return {
+			ok: false,
+			error: `Failed to scaffold ADR: ${message}`,
+		};
+	}
+}
+
+/**
+ * List existing ADRs with number, title, status.
+ * Reads each NNNN-*.md file to extract title (line 1) and status (after ## Status).
+ * Returns sorted by number.
+ */
+export async function listAdrs(adrDir: string): Promise<Result<AdrSummary[]>> {
+	try {
+		if (!existsSync(adrDir)) {
+			return {
+				ok: false,
+				error: `ADR directory does not exist: ${adrDir}`,
+			};
+		}
+
+		const entries = readdirSync(adrDir);
+		const summaries: AdrSummary[] = [];
+
+		for (const entry of entries) {
+			const num = extractNumber(entry);
+			if (num === null) continue;
+
+			const filePath = join(adrDir, entry);
+			const content = readFileSync(filePath, "utf-8");
+			const lines = content.split("\n");
+
+			// Extract title from first line: "# NNNN. Title"
+			let title = "";
+			const titleMatch = lines[0]?.match(/^#\s+\d{4}\.\s+(.+)/);
+			if (titleMatch?.[1]) {
+				title = titleMatch[1];
+			}
+
+			// Extract status: find "## Status" header, then take next non-empty line
+			let status = "Unknown";
+			const statusIdx = lines.findIndex((l) =>
+				l.trim().toLowerCase().startsWith("## status"),
+			);
+			if (statusIdx !== -1) {
+				for (let i = statusIdx + 1; i < lines.length; i++) {
+					const line = lines[i]?.trim();
+					if (line && line.length > 0) {
+						status = line;
+						break;
+					}
+				}
+			}
+
+			summaries.push({
+				number: num.toString().padStart(4, "0"),
+				title,
+				status,
+				path: filePath,
+			});
+		}
+
+		summaries.sort((a, b) => a.number.localeCompare(b.number));
+
+		return { ok: true, value: summaries };
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		return {
+			ok: false,
+			error: `Failed to list ADRs: ${message}`,
+		};
+	}
+}
+
+/**
+ * Generate HLD/LLD sections from a spec using AI (standard tier).
+ * Returns the generated markdown content, or null if AI is unavailable.
+ */
+export async function generateHldLld(
+	specContent: string,
+	mainaDir: string,
+): Promise<Result<string | null>> {
+	try {
+		const variables: Record<string, string> = {
+			spec: specContent,
+			conventions: "",
+		};
+
+		const aiResult = await tryAIGenerate(
+			"design-hld-lld",
+			mainaDir,
+			variables,
+			`Generate HLD and LLD sections for this spec:\n\n${specContent}`,
+		);
+
+		if (!aiResult.text) {
+			if (aiResult.delegation) {
+				// Return delegation prompt for host to process
+				return {
+					ok: true,
+					value: `<!-- AI delegation: process this prompt to generate HLD/LLD -->\n\n${aiResult.delegation.userPrompt}`,
+				};
+			}
+			return {
+				ok: false,
+				error:
+					"AI generation unavailable — set MAINA_API_KEY or OPENROUTER_API_KEY to enable HLD/LLD generation",
+			};
+		}
+
+		return { ok: true, value: aiResult.text };
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		return { ok: false, error: `HLD/LLD generation failed: ${message}` };
+	}
+}

package/src/design/review.ts

@@ -0,0 +1,327 @@
+/**
+ * ADR Design Review.
+ *
+ * Reviews an Architecture Decision Record against existing ADRs and
+ * the project constitution. Performs deterministic checks for MADR
+ * section completeness and [NEEDS CLARIFICATION] markers.
+ *
+ * Single LLM call per command — deterministic checks run without AI.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Result } from "../db/index";
+import { loadConstitution } from "../prompts/loader";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface ReviewContext {
+	targetAdr: { path: string; content: string; title: string };
+	existingAdrs: Array<{ path: string; content: string; title: string }>;
+	constitution: string | null;
+}
+
+export interface ReviewOptions {
+	aiAvailable?: boolean;
+}
+
+export interface ReviewFinding {
+	severity: "error" | "warning" | "info";
+	message: string;
+	section?: string;
+}
+
+export interface ReviewResult {
+	adrPath: string;
+	findings: ReviewFinding[];
+	passed: boolean; // true if no errors
+	sectionsPresent: string[];
+	sectionsMissing: string[];
+}
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+const REQUIRED_SECTIONS = ["Status", "Context", "Decision", "Consequences"];
+
+const HLD_SECTIONS = [
+	"System Overview",
+	"Component Boundaries",
+	"Data Flow",
+	"External Dependencies",
+];
+
+const LLD_SECTIONS = [
+	"Interfaces & Types",
+	"Function Signatures",
+	"DB Schema Changes",
+	"Sequence of Operations",
+	"Error Handling",
+	"Edge Cases",
+];
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extract the title from an ADR's first line.
+ * Expects format: `# NNNN. Title`
+ */
+function extractTitle(content: string): string {
+	const firstLine = content.split("\n")[0] ?? "";
+	const match = firstLine.match(/^#\s+\d{4}\.\s+(.+)/);
+	return match?.[1]?.trim() ?? "";
+}
+
+/**
+ * Extract numeric prefix from an ADR filename.
+ * Returns the number if the name matches NNNN-*.md pattern, or null.
+ */
+function extractNumber(name: string): number | null {
+	const match = name.match(/^(\d{4})-.*\.md$/);
+	if (!match?.[1]) return null;
+	return Number.parseInt(match[1], 10);
+}
+
+/**
+ * Check which MADR sections are present in the content.
+ */
+function detectSections(content: string): {
+	present: string[];
+	missing: string[];
+} {
+	const present: string[] = [];
+	const missing: string[] = [];
+
+	for (const section of REQUIRED_SECTIONS) {
+		// Match ## Section as a heading (case-insensitive)
+		const pattern = new RegExp(`^##\\s+${section}\\s*$`, "im");
+		if (pattern.test(content)) {
+			present.push(section);
+		} else {
+			missing.push(section);
+		}
+	}
+
+	return { present, missing };
+}
+
+/**
+ * Count occurrences of [NEEDS CLARIFICATION] in content.
+ */
+function countClarificationMarkers(content: string): number {
+	const matches = content.match(/\[NEEDS CLARIFICATION\]/g);
+	return matches?.length ?? 0;
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Build the review context by reading the target ADR, all existing ADRs,
+ * and the constitution.
+ */
+export async function buildReviewContext(
+	adrPath: string,
+	adrDir: string,
+	mainaDir: string,
+): Promise<Result<ReviewContext>> {
+	try {
+		// Read target ADR
+		if (!existsSync(adrPath)) {
+			return {
+				ok: false,
+				error: `Target ADR not found: ${adrPath}`,
+			};
+		}
+
+		const targetContent = readFileSync(adrPath, "utf-8");
+		const targetTitle = extractTitle(targetContent);
+
+		// Read all other ADRs from adrDir
+		const existingAdrs: ReviewContext["existingAdrs"] = [];
+
+		if (existsSync(adrDir)) {
+			const entries = readdirSync(adrDir);
+			const targetBasename = basename(adrPath);
+
+			for (const entry of entries) {
+				// Skip target ADR and non-ADR files
+				if (entry === targetBasename) continue;
+				if (extractNumber(entry) === null) continue;
+
+				const filePath = join(adrDir, entry);
+				const content = readFileSync(filePath, "utf-8");
+				const title = extractTitle(content);
+
+				existingAdrs.push({ path: filePath, content, title });
+			}
+		}
+
+		// Read constitution
+		const constitutionContent = await loadConstitution(mainaDir);
+		const constitution =
+			constitutionContent.length > 0 ? constitutionContent : null;
+
+		return {
+			ok: true,
+			value: {
+				targetAdr: {
+					path: adrPath,
+					content: targetContent,
+					title: targetTitle,
+				},
+				existingAdrs,
+				constitution,
+			},
+		};
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		return {
+			ok: false,
+			error: `Failed to build review context: ${message}`,
+		};
+	}
+}
+
+/**
+ * Find an ADR file in the adr directory by its number (e.g., "0001").
+ */
+export async function findAdrByNumber(
+	adrDir: string,
+	number: string,
+): Promise<Result<string>> {
+	try {
+		if (!existsSync(adrDir)) {
+			return {
+				ok: false,
+				error: `ADR directory does not exist: ${adrDir}`,
+			};
+		}
+
+		const paddedNumber = number.padStart(4, "0");
+		const entries = readdirSync(adrDir);
+
+		for (const entry of entries) {
+			if (entry.startsWith(`${paddedNumber}-`) && entry.endsWith(".md")) {
+				return { ok: true, value: join(adrDir, entry) };
+			}
+		}
+
+		return {
+			ok: false,
+			error: `No ADR found with number ${paddedNumber}`,
+		};
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		return {
+			ok: false,
+			error: `Failed to find ADR: ${message}`,
+		};
+	}
+}
+
+/**
+ * Review an ADR using deterministic checks.
+ *
+ * Checks:
+ * 1. Required MADR sections present (Status, Context, Decision, Consequences)
+ * 2. [NEEDS CLARIFICATION] markers flagged as incomplete
+ */
+export function reviewDesign(
+	context: ReviewContext,
+	_options?: ReviewOptions,
+): Result<ReviewResult> {
+	try {
+		const findings: ReviewFinding[] = [];
+		const { content } = context.targetAdr;
+
+		// Check required sections
+		const { present, missing } = detectSections(content);
+
+		for (const section of missing) {
+			findings.push({
+				severity: "error",
+				message: `Missing required section: "## ${section}"`,
+				section,
+			});
+		}
+
+		// Check for [NEEDS CLARIFICATION] markers
+		// >5 markers means the ADR is effectively empty — error, not warning
+		const clarificationCount = countClarificationMarkers(content);
+		if (clarificationCount > 5) {
+			findings.push({
+				severity: "error",
+				message: `Contains ${clarificationCount} [NEEDS CLARIFICATION] markers — ADR is effectively empty and should not be committed`,
+			});
+		} else if (clarificationCount > 0) {
+			findings.push({
+				severity: "warning",
+				message: `Contains ${clarificationCount} [NEEDS CLARIFICATION] marker${clarificationCount > 1 ? "s" : ""} — ADR is incomplete`,
+			});
+		}
+
+		// Check HLD sections (warning, not error — these are optional for simple ADRs)
+		const hasHldHeader = /^##\s+High-Level Design/im.test(content);
+		if (!hasHldHeader) {
+			findings.push({
+				severity: "warning",
+				message:
+					"Missing High-Level Design section — consider adding for complex decisions",
+				section: "High-Level Design",
+			});
+		} else {
+			for (const sub of HLD_SECTIONS) {
+				const escaped = sub.replace(/[&]/g, "\\$&");
+				const pattern = new RegExp(`^###\\s+${escaped}\\s*$`, "im");
+				if (!pattern.test(content)) {
+					findings.push({
+						severity: "warning",
+						message: `High-Level Design missing subsection: "${sub}"`,
+						section: `High-Level Design / ${sub}`,
+					});
+				}
+			}
+		}
+
+		// Check LLD sections
+		const hasLldHeader = /^##\s+Low-Level Design/im.test(content);
+		if (!hasLldHeader) {
+			findings.push({
+				severity: "warning",
+				message:
+					"Missing Low-Level Design section — consider adding for complex decisions",
+				section: "Low-Level Design",
+			});
+		} else {
+			for (const sub of LLD_SECTIONS) {
+				const escaped = sub.replace(/[&]/g, "\\$&");
+				const pattern = new RegExp(`^###\\s+${escaped}\\s*$`, "im");
+				if (!pattern.test(content)) {
+					findings.push({
+						severity: "warning",
+						message: `Low-Level Design missing subsection: "${sub}"`,
+						section: `Low-Level Design / ${sub}`,
+					});
+				}
+			}
+		}
+
+		const hasErrors = findings.some((f) => f.severity === "error");
+
+		return {
+			ok: true,
+			value: {
+				adrPath: context.targetAdr.path,
+				findings,
+				passed: !hasErrors,
+				sectionsPresent: present,
+				sectionsMissing: missing,
+			},
+		};
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		return {
+			ok: false,
+			error: `Review failed: ${message}`,
+		};
+	}
+}