@mainahq/core 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mainahq/core",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Maina core engines — Context, Prompt, and Verify for verification-first development",

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

@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { checkAIAvailability } from "../availability";
+
+describe("checkAIAvailability", () => {
+	const originalEnv = { ...process.env };
+
+	beforeEach(() => {
+		// Clear all relevant env vars before each test
+		delete process.env.MAINA_API_KEY;
+		delete process.env.OPENROUTER_API_KEY;
+		delete process.env.ANTHROPIC_API_KEY;
+		delete process.env.MAINA_HOST_MODE;
+		delete process.env.CLAUDECODE;
+		delete process.env.CLAUDE_CODE_ENTRYPOINT;
+		delete process.env.CURSOR;
+	});
+
+	afterEach(() => {
+		// Restore original env
+		for (const key of [
+			"MAINA_API_KEY",
+			"OPENROUTER_API_KEY",
+			"ANTHROPIC_API_KEY",
+			"MAINA_HOST_MODE",
+			"CLAUDECODE",
+			"CLAUDE_CODE_ENTRYPOINT",
+			"CURSOR",
+		]) {
+			if (originalEnv[key] !== undefined) {
+				process.env[key] = originalEnv[key];
+			} else {
+				delete process.env[key];
+			}
+		}
+	});
+
+	it("returns api-key method when MAINA_API_KEY is set", () => {
+		process.env.MAINA_API_KEY = "test-key-123";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("api-key");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns api-key method when OPENROUTER_API_KEY is set", () => {
+		process.env.OPENROUTER_API_KEY = "or-key-456";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("api-key");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns api-key method when ANTHROPIC_API_KEY is set", () => {
+		process.env.ANTHROPIC_API_KEY = "sk-ant-test";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("api-key");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns host-delegation when CLAUDECODE env is set", () => {
+		process.env.CLAUDECODE = "1";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("host-delegation");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns host-delegation when CLAUDE_CODE_ENTRYPOINT is set", () => {
+		process.env.CLAUDE_CODE_ENTRYPOINT = "cli";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("host-delegation");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns host-delegation when CURSOR is set", () => {
+		process.env.CURSOR = "1";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("host-delegation");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns host-delegation when MAINA_HOST_MODE is true", () => {
+		process.env.MAINA_HOST_MODE = "true";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("host-delegation");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns none when no key and no host environment", () => {
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(false);
+		expect(result.method).toBe("none");
+	});
+
+	it("includes a reason message when method is none", () => {
+		const result = checkAIAvailability();
+
+		expect(result.reason).toBeDefined();
+		expect(result.reason).toContain("No API key found");
+		expect(result.reason).toContain("maina init");
+	});
+
+	it("prefers api-key over host-delegation when both available", () => {
+		process.env.MAINA_API_KEY = "test-key";
+		process.env.CLAUDECODE = "1";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("api-key");
+	});
+});

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

@@ -1,7 +1,8 @@
-import { describe, expect, it } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import {
 	type DelegationRequest,
 	formatDelegationRequest,
+	outputDelegationRequest,
 	parseDelegationRequest,
 } from "../delegation";
 
@@ -103,3 +104,56 @@ Some output after`;
 		expect(parsed?.prompt).toBe("hello");
 	});
 });
+
+describe("outputDelegationRequest", () => {
+	let stderrChunks: string[];
+	let stdoutChunks: string[];
+	let originalStderrWrite: typeof process.stderr.write;
+	let originalStdoutWrite: typeof process.stdout.write;
+
+	beforeEach(() => {
+		stderrChunks = [];
+		stdoutChunks = [];
+		originalStderrWrite = process.stderr.write;
+		originalStdoutWrite = process.stdout.write;
+
+		process.stderr.write = ((chunk: string | Uint8Array) => {
+			stderrChunks.push(
+				typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk),
+			);
+			return true;
+		}) as typeof process.stderr.write;
+
+		process.stdout.write = ((chunk: string | Uint8Array) => {
+			stdoutChunks.push(
+				typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk),
+			);
+			return true;
+		}) as typeof process.stdout.write;
+	});
+
+	afterEach(() => {
+		process.stderr.write = originalStderrWrite;
+		process.stdout.write = originalStdoutWrite;
+	});
+
+	it("writes to stderr, not stdout (prevents MCP protocol corruption)", () => {
+		const req: DelegationRequest = {
+			task: "review",
+			context: "test context",
+			prompt: "test prompt",
+			expectedFormat: "text",
+		};
+
+		outputDelegationRequest(req);
+
+		// Must write to stderr
+		expect(stderrChunks.length).toBeGreaterThan(0);
+		const stderrOutput = stderrChunks.join("");
+		expect(stderrOutput).toContain("---MAINA_AI_REQUEST---");
+		expect(stderrOutput).toContain("task: review");
+
+		// Must NOT write to stdout (stdout is reserved for JSON-RPC in MCP)
+		expect(stdoutChunks.length).toBe(0);
+	});
+});

package/src/ai/availability.ts

@@ -0,0 +1,23 @@
+import { getApiKey, isHostMode } from "../config/index";
+
+export interface AIAvailability {
+	available: boolean;
+	method: "api-key" | "host-delegation" | "none";
+	reason?: string;
+}
+
+export function checkAIAvailability(): AIAvailability {
+	const apiKey = getApiKey();
+	if (apiKey !== null) {
+		return { available: true, method: "api-key" };
+	}
+	if (isHostMode()) {
+		return { available: true, method: "host-delegation" };
+	}
+	return {
+		available: false,
+		method: "none",
+		reason:
+			"No API key found and not running inside an AI agent. Run `maina init` to set up or run inside Claude Code/Cursor.",
+	};
+}

package/src/ai/delegation.ts

@@ -102,10 +102,12 @@ export function parseDelegationRequest(text: string): DelegationRequest | null {
 }
 
 /**
- * Output a delegation request to stdout.
- * Used by tryAIGenerate when in host mode.
+ * 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.
  */
 export function outputDelegationRequest(req: DelegationRequest): void {
 	const formatted = formatDelegationRequest(req);
-	process.stdout.write(`\n${formatted}\n`);
+	process.stderr.write(`\n${formatted}\n`);
 }

package/src/context/__tests__/budget.test.ts

@@ -42,12 +42,13 @@ describe("getBudgetRatio", () => {
 describe("assembleBudget", () => {
 	test("allocations sum correctly for default mode with default context window", () => {
 		const allocation = assembleBudget("default");
-		// working + episodic + semantic + retrieval + headroom === total
+		// working + episodic + semantic + retrieval + wiki + headroom === total
 		const layerSum =
 			allocation.working +
 			allocation.episodic +
 			allocation.semantic +
 			allocation.retrieval +
+			allocation.wiki +
 			allocation.headroom;
 		expect(layerSum).toBe(allocation.total);
 	});
@@ -75,7 +76,8 @@ describe("assembleBudget", () => {
 			allocation.working +
 			allocation.episodic +
 			allocation.semantic +
-			allocation.retrieval;
+			allocation.retrieval +
+			allocation.wiki;
 		expect(layerSum).toBe(budget);
 	});
 
@@ -83,15 +85,35 @@ describe("assembleBudget", () => {
 		const modelContext = 200_000;
 		const allocationDefault = assembleBudget("default", modelContext);
 		const allocationFocused = assembleBudget("focused", modelContext);
-		// working = ~25% of budget; for focused: budget = 0.4 * 200_000 = 80_000
-		// working = floor(80_000 * 0.25) = 20_000
+		// working = ~12% of budget; for focused: budget = 0.4 * 200_000 = 80_000
+		// working = floor(80_000 * 0.12) = 9_600
 		expect(allocationFocused.working).toBe(
-			Math.floor(Math.floor(modelContext * 0.4) * 0.25),
+			Math.floor(Math.floor(modelContext * 0.4) * 0.12),
 		);
 		expect(allocationDefault.working).toBe(
-			Math.floor(Math.floor(modelContext * 0.6) * 0.25),
+			Math.floor(Math.floor(modelContext * 0.6) * 0.12),
 		);
 	});
+
+	test("wiki allocation is ~12% of usable budget", () => {
+		const modelContext = 200_000;
+		const allocation = assembleBudget("default", modelContext);
+		const budget = Math.floor(modelContext * 0.6);
+		expect(allocation.wiki).toBe(Math.floor(budget * 0.12));
+	});
+
+	test("all 5 layers sum to budget for default mode", () => {
+		const modelContext = 200_000;
+		const allocation = assembleBudget("default", modelContext);
+		const budget = Math.floor(modelContext * 0.6);
+		const layerSum =
+			allocation.working +
+			allocation.episodic +
+			allocation.semantic +
+			allocation.retrieval +
+			allocation.wiki;
+		expect(layerSum).toBe(budget);
+	});
 });
 
 describe("truncateToFit", () => {
@@ -109,6 +131,7 @@ describe("truncateToFit", () => {
 		semantic: 200,
 		episodic: 300,
 		retrieval: 400,
+		wiki: 0,
 		headroom: 0,
 		total: 1000,
 		...overrides,

package/src/context/__tests__/engine.test.ts

@@ -156,6 +156,7 @@ describe("assembleContext", () => {
 		expect(typeof result.budget.episodic).toBe("number");
 		expect(typeof result.budget.semantic).toBe("number");
 		expect(typeof result.budget.retrieval).toBe("number");
+		expect(typeof result.budget.wiki).toBe("number");
 		expect(typeof result.budget.total).toBe("number");
 		expect(typeof result.budget.headroom).toBe("number");
 		expect(result.budget.total).toBeGreaterThan(0);

package/src/context/__tests__/selector.test.ts

@@ -3,28 +3,31 @@ import type { BudgetMode } from "../budget.ts";
 import { getBudgetMode, getContextNeeds, needsLayer } from "../selector.ts";
 
 describe("getContextNeeds", () => {
-	it("commit needs only working + conventions", () => {
+	it("commit needs only working + conventions + wiki", () => {
 		const needs = getContextNeeds("commit");
 		expect(needs.working).toBe(true);
 		expect(needs.episodic).toBe(false);
 		expect(needs.semantic).toEqual(["conventions"]);
 		expect(needs.retrieval).toBe(false);
+		expect(needs.wiki).toBe(true);
 	});
 
-	it("context command needs all 4 layers", () => {
+	it("context command needs all 5 layers", () => {
 		const needs = getContextNeeds("context");
 		expect(needs.working).toBe(true);
 		expect(needs.episodic).toBe(true);
 		expect(needs.semantic).toBe(true);
 		expect(needs.retrieval).toBe(true);
+		expect(needs.wiki).toBe(true);
 	});
 
-	it("verify needs working + recent-reviews + adrs + conventions", () => {
+	it("verify needs working + recent-reviews + adrs + conventions + wiki", () => {
 		const needs = getContextNeeds("verify");
 		expect(needs.working).toBe(true);
 		expect(needs.episodic).toEqual(["recent-reviews"]);
 		expect(needs.semantic).toEqual(["adrs", "conventions"]);
 		expect(needs.retrieval).toBe(false);
+		expect(needs.wiki).toBe(true);
 	});
 
 	it("review returns correct context needs", () => {
@@ -33,6 +36,7 @@ describe("getContextNeeds", () => {
 		expect(needs.episodic).toEqual(["past-reviews"]);
 		expect(needs.semantic).toEqual(["adrs"]);
 		expect(needs.retrieval).toBe(false);
+		expect(needs.wiki).toBe(true);
 	});
 
 	it("plan returns correct context needs", () => {
@@ -41,6 +45,7 @@ describe("getContextNeeds", () => {
 		expect(needs.semantic).toEqual(["adrs", "conventions"]);
 		expect(needs.episodic).toBe(false);
 		expect(needs.retrieval).toBe(false);
+		expect(needs.wiki).toBe(true);
 	});
 
 	it("explain returns correct context needs", () => {
@@ -49,6 +54,7 @@ describe("getContextNeeds", () => {
 		expect(needs.episodic).toBe(false);
 		expect(needs.semantic).toBe(true);
 		expect(needs.retrieval).toBe(true);
+		expect(needs.wiki).toBe(true);
 	});
 
 	it("design returns correct context needs", () => {
@@ -57,6 +63,7 @@ describe("getContextNeeds", () => {
 		expect(needs.episodic).toBe(false);
 		expect(needs.semantic).toEqual(["adrs"]);
 		expect(needs.retrieval).toBe(false);
+		expect(needs.wiki).toBe(true);
 	});
 
 	it("ticket returns correct context needs", () => {
@@ -65,6 +72,7 @@ describe("getContextNeeds", () => {
 		expect(needs.episodic).toBe(false);
 		expect(needs.semantic).toEqual(["modules"]);
 		expect(needs.retrieval).toBe(false);
+		expect(needs.wiki).toBe(false);
 	});
 
 	it("analyze returns correct context needs", () => {
@@ -73,6 +81,7 @@ describe("getContextNeeds", () => {
 		expect(needs.episodic).toBe(true);
 		expect(needs.semantic).toBe(true);
 		expect(needs.retrieval).toBe(false);
+		expect(needs.wiki).toBe(true);
 	});
 
 	it("pr returns correct context needs", () => {
@@ -81,6 +90,7 @@ describe("getContextNeeds", () => {
 		expect(needs.episodic).toEqual(["past-reviews"]);
 		expect(needs.semantic).toBe(true);
 		expect(needs.retrieval).toBe(true);
+		expect(needs.wiki).toBe(true);
 	});
 });
 
@@ -129,6 +139,16 @@ describe("needsLayer", () => {
 		const needs = getContextNeeds("commit");
 		expect(needsLayer(needs, "retrieval")).toBe(false);
 	});
+
+	it("correctly identifies when wiki layer is needed", () => {
+		const needs = getContextNeeds("commit");
+		expect(needsLayer(needs, "wiki")).toBe(true);
+	});
+
+	it("correctly identifies when wiki layer is not needed", () => {
+		const needs = getContextNeeds("ticket");
+		expect(needsLayer(needs, "wiki")).toBe(false);
+	});
 });
 
 describe("getBudgetMode", () => {