@mainahq/core 1.1.1 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mainahq/core",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Maina core engines — Context, Prompt, and Verify for verification-first development",
@@ -31,6 +31,7 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "^3.0.50",
+    "@orama/orama": "^3.1.18",
     "ai": "^6.0.145",
     "drizzle-orm": "^0.45.2"
   },

package/src/ai/__tests__/delegation.test.ts

@@ -137,7 +137,12 @@ describe("outputDelegationRequest", () => {
 		process.stdout.write = originalStdoutWrite;
 	});
 
-	it("writes to stderr, not stdout (prevents MCP protocol corruption)", () => {
+	it("writes to stderr when inside AI tool, not stdout (prevents MCP corruption)", () => {
+		// Simulate running inside Claude Code
+		const origClaudeCode = process.env.CLAUDE_CODE;
+		process.env.CLAUDE_CODE = "1";
+		delete process.env.MAINA_MCP_SERVER;
+
 		const req: DelegationRequest = {
 			task: "review",
 			context: "test context",
@@ -153,7 +158,46 @@ describe("outputDelegationRequest", () => {
 		expect(stderrOutput).toContain("---MAINA_AI_REQUEST---");
 		expect(stderrOutput).toContain("task: review");
 
-		// Must NOT write to stdout (stdout is reserved for JSON-RPC in MCP)
+		// Must NOT write to stdout
+		expect(stdoutChunks.length).toBe(0);
+
+		// Restore
+		if (origClaudeCode) process.env.CLAUDE_CODE = origClaudeCode;
+		else delete process.env.CLAUDE_CODE;
+	});
+
+	it("suppresses output in MCP server mode", () => {
+		process.env.MAINA_MCP_SERVER = "1";
+		process.env.CLAUDE_CODE = "1";
+
+		outputDelegationRequest({
+			task: "test",
+			context: "ctx",
+			prompt: "p",
+			expectedFormat: "text",
+		});
+
+		expect(stderrChunks.length).toBe(0);
+		expect(stdoutChunks.length).toBe(0);
+
+		delete process.env.MAINA_MCP_SERVER;
+		delete process.env.CLAUDE_CODE;
+	});
+
+	it("suppresses output in bare terminal (no AI tool env vars)", () => {
+		delete process.env.CLAUDE_CODE;
+		delete process.env.CLAUDE_PROJECT_DIR;
+		delete process.env.CURSOR_TRACE_ID;
+		delete process.env.MAINA_MCP_SERVER;
+
+		outputDelegationRequest({
+			task: "test",
+			context: "ctx",
+			prompt: "p",
+			expectedFormat: "text",
+		});
+
+		expect(stderrChunks.length).toBe(0);
 		expect(stdoutChunks.length).toBe(0);
 	});
 });

package/src/ai/delegation.ts

@@ -103,11 +103,27 @@ export function parseDelegationRequest(text: string): DelegationRequest | null {
 
 /**
  * Output a delegation request to stderr.
- * Uses stderr so that MCP stdio transport (which uses stdout for JSON-RPC)
- * is never corrupted by delegation text.
- * In CLI mode, stderr is still visible in the terminal.
+ * Only outputs when running inside an AI tool that can process it
+ * (detected via CLAUDE_CODE, CURSOR, or similar env vars).
+ * Silent in bare terminal to avoid confusing users.
  */
 export function outputDelegationRequest(req: DelegationRequest): void {
+	// Never output in MCP mode — corrupts JSON-RPC communication
+	if (process.env.MAINA_MCP_SERVER === "1") {
+		return;
+	}
+
+	// Only output in bare CLI when inside an AI tool that can process it
+	const inAITool =
+		process.env.CLAUDE_CODE === "1" ||
+		process.env.CLAUDE_PROJECT_DIR ||
+		process.env.CURSOR_TRACE_ID ||
+		process.env.CONTINUE_GLOBAL_DIR;
+
+	if (!inAITool) {
+		return;
+	}
+
 	const formatted = formatDelegationRequest(req);
 	process.stderr.write(`\n${formatted}\n`);
 }

package/src/cloud/client.ts

@@ -244,7 +244,17 @@ export function createCloudClient(config: CloudConfig): CloudClient {
 
 		getPrompts: () => request<PromptRecord[]>("GET", "/prompts"),
 
-		putPrompts: (prompts) => request<void>("PUT", "/prompts", { prompts }),
+		putPrompts: async (prompts) => {
+			for (const p of prompts) {
+				const result = await request<void>("PUT", "/prompts", {
+					name: p.id ?? p.path?.replace(/\.md$/, "") ?? "unknown",
+					content: p.content,
+					hash: p.hash,
+				});
+				if (!result.ok) return result;
+			}
+			return { ok: true as const, value: undefined };
+		},
 
 		getTeam: () => request<TeamInfo>("GET", "/team"),
 

package/src/index.ts

@@ -444,6 +444,15 @@ export {
 	type CompileOptions as WikiCompileOptions,
 	compile as compileWiki,
 } from "./wiki/compiler";
+// Wiki — Consult
+export {
+	consultWikiForBrainstorm,
+	consultWikiForDesign,
+	consultWikiForPlan,
+	type WikiBrainstormContext,
+	type WikiConsultResult,
+	type WikiDesignConsultResult,
+} from "./wiki/consult";
 export { type CodeEntity, extractCodeEntities } from "./wiki/extractors/code";
 export {
 	extractDecisions,
@@ -486,6 +495,15 @@ export {
 	validateArticleStructure,
 	type WikiSchema,
 } from "./wiki/schema";
+// Wiki — Search
+export {
+	buildSearchIndex,
+	loadSearchIndex,
+	saveSearchIndex,
+	searchWiki,
+	type WikiSearchIndex,
+	type WikiSearchResult,
+} from "./wiki/search";
 // Wiki — Signals
 export {
 	type ArticleLoadSignal,

package/src/init/index.ts

@@ -1063,6 +1063,13 @@ async function tryGenerateConstitution(
 	stack: DetectedStack,
 ): Promise<string | null> {
 	try {
+		// Only attempt AI generation if we have an actual API key.
+		// Host delegation just dumps prompts to stderr which confuses users.
+		const { getApiKey } = await import("../config/index");
+		if (!getApiKey()) {
+			return null;
+		}
+
 		const { tryAIGenerate } = await import("../ai/try-generate");
 		const mainaDir = join(repoRoot, ".maina");
 		const summary = buildProjectSummary(repoRoot, stack);

package/src/review/index.ts

@@ -7,6 +7,9 @@
  * Deterministic checks only — no AI calls.
  */
 
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
 // ── Types ────────────────────────────────────────────────────────────────────
 
 export interface ReviewStageResult {
@@ -28,6 +31,8 @@ export interface ReviewOptions {
 	planContent?: string | null;
 	conventions?: string | null;
 	mainaDir?: string; // enables AI review when provided
+	/** Accepted ADR summaries for spec compliance checking */
+	decisionSummaries?: string[] | null;
 }
 
 export interface ReviewResult {
@@ -171,6 +176,7 @@ function extractAddedLines(
 export function reviewSpecCompliance(
 	diff: string,
 	planContent: string | null,
+	decisionSummaries?: string[] | null,
 ): ReviewStageResult {
 	const findings: ReviewFinding[] = [];
 
@@ -229,6 +235,34 @@ export function reviewSpecCompliance(
 		}
 	}
 
+	// Check if changes align with accepted ADRs
+	if (decisionSummaries && decisionSummaries.length > 0) {
+		const addedLines = extractAddedLines(diff);
+		const addedText = addedLines.map((l) => l.text.toLowerCase()).join(" ");
+
+		for (const summary of decisionSummaries) {
+			// Extract tool/technology mentions from ADR summary
+			const summaryLower = summary.toLowerCase();
+			// Check for contradictions: if ADR mentions tool A but added code uses conflicting tool B
+			const knownConflicts: Array<[string, string]> = [
+				["biome", "eslint"],
+				["biome", "prettier"],
+				["bun:test", "jest"],
+				["bun:test", "vitest"],
+			];
+
+			for (const [preferred, rejected] of knownConflicts) {
+				if (summaryLower.includes(preferred) && addedText.includes(rejected)) {
+					findings.push({
+						stage: "spec-compliance",
+						severity: "warning",
+						message: `ADR requires ${preferred} but added code references ${rejected}: "${summary.slice(0, 80)}"`,
+					});
+				}
+			}
+		}
+	}
+
 	const hasWarningsOrErrors = findings.some(
 		(f) => f.severity === "warning" || f.severity === "error",
 	);
@@ -376,6 +410,51 @@ export async function reviewCodeQualityWithAI(
 	return deterministicResult;
 }
 
+// ── Decision Loader ─────────────────────────────────────────────────────────
+
+/**
+ * Load accepted ADR summaries from the wiki decisions directory.
+ * Returns an array of one-line summaries for each accepted decision.
+ */
+function loadDecisionSummaries(mainaDir: string): string[] | null {
+	const decisionsDir = join(mainaDir, "wiki", "decisions");
+	if (!existsSync(decisionsDir)) return null;
+
+	let entries: string[];
+	try {
+		entries = readdirSync(decisionsDir);
+	} catch {
+		return null;
+	}
+
+	const summaries: string[] = [];
+	for (const entry of entries) {
+		if (!entry.endsWith(".md")) continue;
+		try {
+			const content = readFileSync(join(decisionsDir, entry), "utf-8");
+			const statusMatch = content.match(/>\s*Status:\s*\*\*(\w+)\*\*/);
+			const status = statusMatch?.[1] ?? "";
+			if (status !== "accepted") continue;
+
+			const titleMatch = content.match(/^#\s+(.+)/);
+			const title =
+				titleMatch?.[1]?.replace(/^Decision:\s*/i, "").trim() ?? entry;
+
+			// Extract key constraint from decision section
+			const decisionMatch = content.match(
+				/## Decision\n\n([\s\S]*?)(?=\n## |\n---|$)/,
+			);
+			const decision = decisionMatch?.[1]?.trim().split("\n")[0] ?? "";
+
+			summaries.push(`${title}: ${decision}`);
+		} catch {
+			// skip unreadable files
+		}
+	}
+
+	return summaries.length > 0 ? summaries : null;
+}
+
 // ── Two-Stage Review ────────────────────────────────────────────────────────
 
 /**
@@ -388,9 +467,16 @@ export async function reviewCodeQualityWithAI(
 export async function runTwoStageReview(
 	options: ReviewOptions,
 ): Promise<ReviewResult> {
+	// Load decision summaries from wiki if mainaDir is provided
+	let decisionSummaries = options.decisionSummaries ?? null;
+	if (!decisionSummaries && options.mainaDir) {
+		decisionSummaries = loadDecisionSummaries(options.mainaDir);
+	}
+
 	const stage1 = reviewSpecCompliance(
 		options.diff,
 		options.planContent ?? null,
+		decisionSummaries,
 	);
 
 	if (!stage1.passed) {

package/src/wiki/__tests__/consult.test.ts

@@ -0,0 +1,341 @@
+/**
+ * Tests for wiki consult — pre-command wiki consultation.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	consultWikiForBrainstorm,
+	consultWikiForDesign,
+	consultWikiForPlan,
+} from "../consult";
+
+// ── Test Helpers ────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+let wikiDir: string;
+
+function createTmpDir(): string {
+	const dir = join(
+		import.meta.dir,
+		`tmp-consult-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function seedWiki(wiki: string): void {
+	const subdirs = [
+		"modules",
+		"entities",
+		"features",
+		"decisions",
+		"architecture",
+	];
+	for (const subdir of subdirs) {
+		mkdirSync(join(wiki, subdir), { recursive: true });
+	}
+
+	// Module: verify with 11 entities
+	writeFileSync(
+		join(wiki, "modules", "verify.md"),
+		[
+			"# Module: verify",
+			"",
+			"> Auto-generated module article for `verify`.",
+			"",
+			"## Entities",
+			"",
+			"- **runPipeline** (function) — `verify/pipeline.ts:10`",
+			"- **syntaxGuard** (function) — `verify/syntax.ts:5`",
+			"- **diffFilter** (function) — `verify/diff.ts:1`",
+			"- **slopDetector** (function) — `verify/slop.ts:8`",
+			"- **reviewCode** (function) — `verify/review.ts:3`",
+			"- **PipelineResult** (interface) — `verify/types.ts:1`",
+			"- **Finding** (interface) — `verify/types.ts:20`",
+			"- **ToolRunner** (interface) — `verify/types.ts:40`",
+			"- **SyntaxError** (interface) — `verify/types.ts:60`",
+			"- **DiffFilter** (interface) — `verify/types.ts:80`",
+			"- **SlopPattern** (interface) — `verify/types.ts:100`",
+		].join("\n"),
+	);
+
+	// Module: context with 8 entities
+	writeFileSync(
+		join(wiki, "modules", "context.md"),
+		[
+			"# Module: context",
+			"",
+			"> Auto-generated module article for `context`.",
+			"",
+			"## Entities",
+			"",
+			"- **assembleContext** (function) — `context/engine.ts:10`",
+			"- **parseFile** (function) — `context/treesitter.ts:5`",
+			"- **extractEntities** (function) — `context/treesitter.ts:50`",
+			"- **ContextResult** (interface) — `context/types.ts:1`",
+			"- **TokenBudget** (interface) — `context/budget.ts:1`",
+			"- **SemanticLayer** (class) — `context/semantic.ts:10`",
+			"- **EpisodicLayer** (class) — `context/episodic.ts:10`",
+			"- **WorkingLayer** (class) — `context/working.ts:10`",
+		].join("\n"),
+	);
+
+	// Decision: accepted — multi-language with Biome
+	writeFileSync(
+		join(wiki, "decisions", "0002-multi-language-verify-pipeline.md"),
+		[
+			"# Decision: Multi-language verify pipeline",
+			"",
+			"> Status: **accepted**",
+			"",
+			"## Context",
+			"",
+			"Maina needs multi-language support for the verify pipeline.",
+			"",
+			"## Decision",
+			"",
+			"Use Biome for TypeScript linting. Use ruff for Python. Use clippy for Rust.",
+			"Introduce LanguageProfile abstraction for each supported language.",
+		].join("\n"),
+	);
+
+	// Decision: proposed — spec quality
+	writeFileSync(
+		join(wiki, "decisions", "0001-spec-quality.md"),
+		[
+			"# Decision: Spec quality system",
+			"",
+			"> Status: **proposed**",
+			"",
+			"## Context",
+			"",
+			"Specifications need quality scoring to prevent bad specs.",
+			"",
+			"## Decision",
+			"",
+			"Build a spec scoring system with measurability and testability checks.",
+		].join("\n"),
+	);
+
+	// Feature: similar to hardening
+	writeFileSync(
+		join(wiki, "features", "024-v03x-hardening.md"),
+		[
+			"# Feature: Implementation Plan — v0.3.x Hardening",
+			"",
+			"## Status",
+			"",
+			"Verify pipeline improvements, gap fixes, RL loop integration.",
+		].join("\n"),
+	);
+
+	// Feature: benchmark
+	writeFileSync(
+		join(wiki, "features", "010-benchmark-harness.md"),
+		[
+			"# Feature: Benchmark harness",
+			"",
+			"## Status",
+			"",
+			"Full lifecycle benchmark comparison framework.",
+		].join("\n"),
+	);
+
+	// Architecture
+	writeFileSync(
+		join(wiki, "architecture", "three-engines.md"),
+		[
+			"# Architecture: Three Engines",
+			"",
+			"Maina uses three engines: Context, Prompt, and Verify.",
+			"Context observes, Prompt learns, Verify verifies.",
+		].join("\n"),
+	);
+
+	writeFileSync(
+		join(wiki, "architecture", "verification-pipeline.md"),
+		[
+			"# Architecture: Verification Pipeline",
+			"",
+			"The verify pipeline has multiple stages: syntax guard, parallel tools, diff filter, AI fix, review.",
+		].join("\n"),
+	);
+}
+
+beforeEach(() => {
+	tmpDir = createTmpDir();
+	wikiDir = join(tmpDir, "wiki");
+});
+
+afterEach(() => {
+	try {
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		// ignore
+	}
+});
+
+// ── consultWikiForPlan ─────────────────────────────────────────────────────
+
+describe("consultWikiForPlan", () => {
+	test("finds related modules by keyword", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForPlan(
+			wikiDir,
+			"improve the verify pipeline syntax checking",
+		);
+
+		expect(result.relatedModules.length).toBeGreaterThan(0);
+		const verifyMod = result.relatedModules.find((m) => m.name === "verify");
+		expect(verifyMod).toBeDefined();
+		expect(verifyMod?.entities).toBe(11);
+	});
+
+	test("returns suggestions for modules with many entities", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForPlan(
+			wikiDir,
+			"improve the verify pipeline syntax checking",
+		);
+
+		const extendSuggestion = result.suggestions.find((s) =>
+			s.includes("consider extending"),
+		);
+		expect(extendSuggestion).toBeDefined();
+		expect(extendSuggestion).toContain("verify");
+	});
+
+	test("finds related decisions", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForPlan(
+			wikiDir,
+			"add multi-language linting support",
+		);
+
+		expect(result.relatedDecisions.length).toBeGreaterThan(0);
+		const multiLang = result.relatedDecisions.find(
+			(d) => d.id === "0002-multi-language-verify-pipeline",
+		);
+		expect(multiLang).toBeDefined();
+		expect(multiLang?.status).toBe("accepted");
+	});
+
+	test("finds related features", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForPlan(
+			wikiDir,
+			"hardening improvements for verify gaps",
+		);
+
+		expect(result.relatedFeatures.length).toBeGreaterThan(0);
+		const hardening = result.relatedFeatures.find((f) => f.id.includes("024"));
+		expect(hardening).toBeDefined();
+	});
+
+	test("generates feature similarity suggestions", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForPlan(
+			wikiDir,
+			"hardening improvements for verify gaps",
+		);
+
+		const featureSuggestion = result.suggestions.find((s) =>
+			s.includes("did something similar"),
+		);
+		expect(featureSuggestion).toBeDefined();
+	});
+
+	test("handles missing wiki gracefully", () => {
+		const result = consultWikiForPlan("/nonexistent/wiki", "some feature");
+		expect(result.relatedModules).toEqual([]);
+		expect(result.relatedDecisions).toEqual([]);
+		expect(result.relatedFeatures).toEqual([]);
+		expect(result.suggestions).toEqual([]);
+	});
+
+	test("handles empty description", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForPlan(wikiDir, "");
+		expect(result.relatedModules).toEqual([]);
+	});
+});
+
+// ── consultWikiForDesign ───────────────────────────────────────────────────
+
+describe("consultWikiForDesign", () => {
+	test("detects conflicts with existing ADRs", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForDesign(
+			wikiDir,
+			"Use ESLint for linting TypeScript code instead of current tools",
+		);
+
+		expect(result.conflicts.length).toBeGreaterThan(0);
+		const biomeConflict = result.conflicts.find((c) =>
+			c.reason.includes("biome"),
+		);
+		expect(biomeConflict).toBeDefined();
+	});
+
+	test("detects alignments with existing ADRs", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForDesign(
+			wikiDir,
+			"Extend the verify pipeline to support multi-language linting with ruff",
+		);
+
+		expect(result.alignments.length).toBeGreaterThan(0);
+	});
+
+	test("handles missing wiki gracefully", () => {
+		const result = consultWikiForDesign("/nonexistent/wiki", "some decision");
+		expect(result.conflicts).toEqual([]);
+		expect(result.alignments).toEqual([]);
+	});
+
+	test("handles empty proposal", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForDesign(wikiDir, "");
+		expect(result.conflicts).toEqual([]);
+		expect(result.alignments).toEqual([]);
+	});
+});
+
+// ── consultWikiForBrainstorm ───────────────────────────────────────────────
+
+describe("consultWikiForBrainstorm", () => {
+	test("loads architecture context", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForBrainstorm(wikiDir);
+
+		expect(result.architecture).toContain("Three Engines");
+		expect(result.architecture).toContain("Verification Pipeline");
+	});
+
+	test("counts modules and decisions", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForBrainstorm(wikiDir);
+
+		expect(result.moduleCount).toBe(2);
+		expect(result.decisionCount).toBe(2);
+	});
+
+	test("loads recent features", () => {
+		seedWiki(wikiDir);
+		const result = consultWikiForBrainstorm(wikiDir);
+
+		expect(result.recentFeatures.length).toBe(2);
+		// Sorted descending by ID, so 024 comes first
+		expect(result.recentFeatures[0]).toContain("024");
+	});
+
+	test("handles missing wiki gracefully", () => {
+		const result = consultWikiForBrainstorm("/nonexistent/wiki");
+		expect(result.architecture).toBe("");
+		expect(result.moduleCount).toBe(0);
+		expect(result.decisionCount).toBe(0);
+		expect(result.recentFeatures).toEqual([]);
+	});
+});