@mainahq/core 0.2.0

package/README.md

@@ -0,0 +1,31 @@
+# @maina/core
+
+Core engines for the Maina verification-first developer OS.
+
+Three engines: **Context** (observes), **Prompt** (learns), **Verify** (verifies).
+
+## Features
+
+- **Context Engine** — 4-layer retrieval (Working, Episodic, Semantic, Retrieval) with PageRank relevance and dynamic token budget
+- **Prompt Engine** — Constitution + custom prompts + A/B testing + feedback-driven evolution
+- **Verify Engine** — 12-tool pipeline (Biome, Semgrep, Trivy, Secretlint, SonarQube, Stryker, diff-cover, AI review, slop detection, visual regression) with diff-only filtering
+- **Multi-language** — TypeScript, Python, Go, Rust with language-specific profiles
+- **Workflow context** — rolling summary forwarded between lifecycle steps
+- **Background RL** — async feedback recording at each workflow step
+
+## Requirements
+
+**Runtime: Bun** (not Node.js). This package ships TypeScript source directly and requires a TypeScript-aware runtime.
+
+## Usage
+
+```typescript
+import { runPipeline, detectLanguages, tryAIGenerate } from "@maina/core";
+
+const result = await runPipeline({ cwd: ".", diffOnly: true });
+console.log(result.passed ? "Clean" : `${result.findings.length} findings`);
+```
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@mainahq/core",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Maina core engines — Context, Prompt, and Verify for verification-first development",
+  "homepage": "https://beeeku.github.io/maina/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beeeku/maina.git",
+    "directory": "packages/core"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "src",
+    "package.json",
+    "README.md"
+  ],
+  "keywords": [
+    "maina",
+    "verification",
+    "context-engine",
+    "prompt-engine",
+    "ai-code-review"
+  ],
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.50",
+    "ai": "^6.0.145",
+    "drizzle-orm": "^0.45.2"
+  }
+}

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

@@ -0,0 +1,207 @@
+import {
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	test,
+} from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildCacheKey, hashContent } from "../../cache/keys";
+import { createCacheManager } from "../../cache/manager";
+import { generate } from "../index";
+import { getTaskTier } from "../tiers";
+
+const TEST_DIR = join(tmpdir(), `maina-ai-test-${Date.now()}`);
+
+/** Env vars that can trigger host-mode delegation, provide API keys, or override config. */
+const HOST_ENV_VARS = [
+	"MAINA_API_KEY",
+	"OPENROUTER_API_KEY",
+	"ANTHROPIC_API_KEY",
+	"CLAUDECODE",
+	"CLAUDE_CODE_ENTRYPOINT",
+	"CURSOR",
+	"MAINA_HOST_MODE",
+	"MAINA_PROVIDER",
+] as const;
+
+/** Saved env values restored after each test. */
+let savedEnv: Record<string, string | undefined> = {};
+
+beforeAll(() => {
+	mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterAll(() => {
+	rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+	savedEnv = {};
+	for (const key of HOST_ENV_VARS) {
+		savedEnv[key] = process.env[key];
+	}
+});
+
+afterEach(() => {
+	for (const key of HOST_ENV_VARS) {
+		const original = savedEnv[key];
+		if (original !== undefined) {
+			process.env[key] = original;
+		} else {
+			delete process.env[key];
+		}
+	}
+});
+
+function makeDir(sub: string): string {
+	const d = join(TEST_DIR, sub);
+	mkdirSync(d, { recursive: true });
+	return d;
+}
+
+describe("generate — cache hit", () => {
+	test("returns cached result when cache has matching entry", async () => {
+		// Clear all env vars that can influence model resolution / host delegation
+		for (const key of HOST_ENV_VARS) {
+			delete process.env[key];
+		}
+
+		const mainaDir = makeDir("cache-hit");
+		const cache = createCacheManager(mainaDir);
+
+		const task = "commit";
+		const systemPrompt = "You are a helpful assistant.";
+		const userPrompt = "Write a commit message for adding tests.";
+		const promptHash = hashContent(systemPrompt + userPrompt);
+		const cacheKey = await buildCacheKey({
+			task,
+			promptHash,
+			model: "google/gemini-2.5-flash",
+		});
+
+		// Pre-populate cache
+		const cachedValue = JSON.stringify({
+			text: "feat: add test suite",
+			model: "google/gemini-2.5-flash",
+			tokens: { input: 100, output: 20 },
+		});
+		cache.set(cacheKey, cachedValue);
+
+		const result = await generate({
+			task,
+			systemPrompt,
+			userPrompt,
+			mainaDir,
+		});
+
+		expect(result.cached).toBe(true);
+		expect(result.text).toBe("feat: add test suite");
+		expect(result.model).toBe("google/gemini-2.5-flash");
+	});
+});
+
+describe("generate — no API key", () => {
+	test("returns helpful error message when no API key is set", async () => {
+		// Clear ALL env vars that could provide keys or trigger host delegation
+		for (const key of HOST_ENV_VARS) {
+			delete process.env[key];
+		}
+
+		const mainaDir = makeDir("no-api-key");
+
+		const result = await generate({
+			task: "review",
+			systemPrompt: "You are a code reviewer.",
+			userPrompt: "Review this code: const x = 1;",
+			mainaDir,
+		});
+
+		expect(result.cached).toBe(false);
+		expect(result.text).toContain("API key");
+		expect(result.model).toBe("");
+	});
+});
+
+describe("generate — cache key construction", () => {
+	test("same inputs produce same cache key (idempotent)", async () => {
+		const task = "tests";
+		const systemPrompt = "Generate tests.";
+		const userPrompt = "Write tests for add(a, b).";
+		const promptHash = hashContent(systemPrompt + userPrompt);
+
+		const key1 = await buildCacheKey({
+			task,
+			promptHash,
+			model: "google/gemini-2.5-flash",
+		});
+		const key2 = await buildCacheKey({
+			task,
+			promptHash,
+			model: "google/gemini-2.5-flash",
+		});
+
+		expect(key1).toBe(key2);
+	});
+
+	test("different prompts produce different cache keys", async () => {
+		const task = "commit";
+		const promptHash1 = hashContent("system1" + "user1");
+		const promptHash2 = hashContent("system2" + "user2");
+
+		const key1 = await buildCacheKey({
+			task,
+			promptHash: promptHash1,
+			model: "google/gemini-2.5-flash",
+		});
+		const key2 = await buildCacheKey({
+			task,
+			promptHash: promptHash2,
+			model: "google/gemini-2.5-flash",
+		});
+
+		expect(key1).not.toBe(key2);
+	});
+
+	test("different tasks produce different cache keys", async () => {
+		const promptHash = hashContent("system" + "user");
+		const key1 = await buildCacheKey({
+			task: "commit",
+			promptHash,
+			model: "google/gemini-2.5-flash",
+		});
+		const key2 = await buildCacheKey({
+			task: "review",
+			promptHash,
+			model: "anthropic/claude-sonnet-4",
+		});
+
+		expect(key1).not.toBe(key2);
+	});
+});
+
+describe("getTaskTier — code-review tasks", () => {
+	it("should map code-review to mechanical tier", () => {
+		expect(getTaskTier("code-review")).toBe("mechanical");
+	});
+
+	it("should map deep-code-review to standard tier", () => {
+		expect(getTaskTier("deep-code-review")).toBe("standard");
+	});
+});
+
+describe("tryAIGenerate host delegation", () => {
+	it("should extract user prompt from delegation text", async () => {
+		// This tests the extraction logic directly
+		const delegationText =
+			"[HOST_DELEGATION] Task: design-hld-lld\n\nSystem: system prompt\n\nUser: Generate HLD and LLD sections";
+		const userIdx = delegationText.indexOf("\n\nUser: ");
+		const extracted = userIdx !== -1 ? delegationText.slice(userIdx + 8) : null;
+		expect(extracted).toBe("Generate HLD and LLD sections");
+	});
+});

package/src/ai/__tests__/design-approaches.test.ts

@@ -0,0 +1,192 @@
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ── Mock State ──────────────────────────────────────────────────────────────
+
+let mockAIResponse: string | null = null;
+
+// ── Mocks ───────────────────────────────────────────────────────────────────
+
+mock.module("../try-generate", () => ({
+	tryAIGenerate: async (
+		_task: string,
+		_mainaDir: string,
+		_variables: Record<string, string>,
+		_userPrompt: string,
+	) => ({
+		text: mockAIResponse,
+		fromAI: mockAIResponse !== null,
+		hostDelegation: false,
+	}),
+}));
+
+afterAll(() => {
+	mock.restore();
+});
+
+// ── Import after mocks ──────────────────────────────────────────────────────
+
+const { generateDesignApproaches } = await import("../design-approaches");
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("generateDesignApproaches", () => {
+	beforeEach(() => {
+		mockAIResponse = null;
+	});
+
+	// ── Happy Path ──────────────────────────────────────────────────────────
+
+	describe("happy path", () => {
+		test("returns parsed approaches from valid AI JSON response", async () => {
+			mockAIResponse = JSON.stringify([
+				{
+					name: "Event-driven",
+					description: "Steps emit events consumed by next step.",
+					pros: ["Parallel", "Decoupled"],
+					cons: ["Complex debugging"],
+					recommended: true,
+				},
+				{
+					name: "Middleware chain",
+					description: "Sequential middleware functions.",
+					pros: ["Simple"],
+					cons: ["No parallelism"],
+					recommended: false,
+				},
+			]);
+
+			const result = await generateDesignApproaches(
+				"Design a verification pipeline",
+				".maina",
+			);
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(2);
+				expect(result.value[0]?.name).toBe("Event-driven");
+				expect(result.value[0]?.recommended).toBe(true);
+				expect(result.value[0]?.pros).toEqual(["Parallel", "Decoupled"]);
+				expect(result.value[1]?.name).toBe("Middleware chain");
+				expect(result.value[1]?.recommended).toBe(false);
+			}
+		});
+
+		test("returns empty array when AI says no approaches needed", async () => {
+			mockAIResponse = "[]";
+
+			const result = await generateDesignApproaches(
+				"Simple decision",
+				".maina",
+			);
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(0);
+			}
+		});
+	});
+
+	// ── Edge Cases ──────────────────────────────────────────────────────────
+
+	describe("edge cases", () => {
+		test("returns empty array when context is empty", async () => {
+			const result = await generateDesignApproaches("", ".maina");
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(0);
+			}
+		});
+
+		test("handles AI response with markdown fences around JSON", async () => {
+			mockAIResponse =
+				'```json\n[{"name":"A","description":"D","pros":["p"],"cons":["c"],"recommended":true}]\n```';
+
+			const result = await generateDesignApproaches("Test context", ".maina");
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(1);
+				expect(result.value[0]?.name).toBe("A");
+			}
+		});
+
+		test("caps approaches at 3 even if AI returns more", async () => {
+			const fourApproaches = Array.from({ length: 4 }, (_, i) => ({
+				name: `Approach ${i + 1}`,
+				description: `Description ${i + 1}`,
+				pros: ["pro"],
+				cons: ["con"],
+				recommended: i === 0,
+			}));
+			mockAIResponse = JSON.stringify(fourApproaches);
+
+			const result = await generateDesignApproaches("Test context", ".maina");
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value.length).toBeLessThanOrEqual(3);
+			}
+		});
+	});
+
+	// ── Error Handling ──────────────────────────────────────────────────────
+
+	describe("error handling", () => {
+		test("returns empty array when AI is not available", async () => {
+			mockAIResponse = null;
+
+			const result = await generateDesignApproaches("Test context", ".maina");
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(0);
+			}
+		});
+
+		test("returns empty array when AI returns malformed JSON", async () => {
+			mockAIResponse = "not valid json at all";
+
+			const result = await generateDesignApproaches("Test context", ".maina");
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(0);
+			}
+		});
+
+		test("filters out approaches missing required fields", async () => {
+			mockAIResponse = JSON.stringify([
+				{
+					name: "Valid",
+					description: "D",
+					pros: ["p"],
+					cons: ["c"],
+					recommended: true,
+				},
+				{
+					description: "Missing name",
+					pros: ["p"],
+					cons: ["c"],
+					recommended: false,
+				},
+				{
+					name: "Also valid",
+					description: "D2",
+					pros: ["p"],
+					cons: ["c"],
+					recommended: false,
+				},
+			]);
+
+			const result = await generateDesignApproaches("Test context", ".maina");
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(2);
+				expect(result.value[0]?.name).toBe("Valid");
+				expect(result.value[1]?.name).toBe("Also valid");
+			}
+		});
+	});
+});

package/src/ai/__tests__/spec-questions.test.ts

@@ -0,0 +1,191 @@
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ── Mock State ──────────────────────────────────────────────────────────────
+
+let mockAIResponse: string | null = null;
+
+// ── Mocks ───────────────────────────────────────────────────────────────────
+
+mock.module("../try-generate", () => ({
+	tryAIGenerate: async (
+		_task: string,
+		_mainaDir: string,
+		_variables: Record<string, string>,
+		_userPrompt: string,
+	) => ({
+		text: mockAIResponse,
+		fromAI: mockAIResponse !== null,
+		hostDelegation: false,
+	}),
+}));
+
+afterAll(() => {
+	mock.restore();
+});
+
+// ── Import after mocks ──────────────────────────────────────────────────────
+
+const { generateSpecQuestions } = await import("../spec-questions");
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("generateSpecQuestions", () => {
+	beforeEach(() => {
+		mockAIResponse = null;
+	});
+
+	// ── Happy Path ──────────────────────────────────────────────────────────
+
+	describe("happy path", () => {
+		test("returns parsed questions from valid AI JSON response", async () => {
+			mockAIResponse = JSON.stringify([
+				{
+					question: "Should cache invalidate on branch switch?",
+					type: "select",
+					options: ["Yes", "No", "Both"],
+					reason: "Not specified in plan",
+				},
+				{
+					question: "What error message for missing API key?",
+					type: "text",
+					reason: "Error handling unspecified",
+				},
+			]);
+
+			const result = await generateSpecQuestions(
+				"## Tasks\n- T001: Add cache",
+				".maina",
+			);
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(2);
+				expect(result.value[0]?.question).toBe(
+					"Should cache invalidate on branch switch?",
+				);
+				expect(result.value[0]?.type).toBe("select");
+				expect(result.value[0]?.options).toEqual(["Yes", "No", "Both"]);
+				expect(result.value[1]?.type).toBe("text");
+			}
+		});
+
+		test("returns empty array when AI says plan is clear", async () => {
+			mockAIResponse = "[]";
+
+			const result = await generateSpecQuestions(
+				"## Tasks\n- T001: Clear task",
+				".maina",
+			);
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(0);
+			}
+		});
+	});
+
+	// ── Edge Cases ──────────────────────────────────────────────────────────
+
+	describe("edge cases", () => {
+		test("returns empty array when plan content is empty", async () => {
+			const result = await generateSpecQuestions("", ".maina");
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(0);
+			}
+		});
+
+		test("handles AI response with markdown fences around JSON", async () => {
+			mockAIResponse =
+				'```json\n[{"question":"Test?","type":"text","reason":"r"}]\n```';
+
+			const result = await generateSpecQuestions(
+				"## Tasks\n- T001: Test",
+				".maina",
+			);
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(1);
+				expect(result.value[0]?.question).toBe("Test?");
+			}
+		});
+
+		test("caps questions at 5 even if AI returns more", async () => {
+			const sixQuestions = Array.from({ length: 6 }, (_, i) => ({
+				question: `Question ${i + 1}?`,
+				type: "text",
+				reason: `Reason ${i + 1}`,
+			}));
+			mockAIResponse = JSON.stringify(sixQuestions);
+
+			const result = await generateSpecQuestions(
+				"## Tasks\n- T001: Test",
+				".maina",
+			);
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value.length).toBeLessThanOrEqual(5);
+			}
+		});
+	});
+
+	// ── Error Handling ──────────────────────────────────────────────────────
+
+	describe("error handling", () => {
+		test("returns empty array when AI is not available (null response)", async () => {
+			mockAIResponse = null;
+
+			const result = await generateSpecQuestions(
+				"## Tasks\n- T001: Test",
+				".maina",
+			);
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(0);
+			}
+		});
+
+		test("returns empty array when AI returns malformed JSON", async () => {
+			mockAIResponse = "not valid json at all";
+
+			const result = await generateSpecQuestions(
+				"## Tasks\n- T001: Test",
+				".maina",
+			);
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(0);
+			}
+		});
+
+		test("filters out questions missing required fields", async () => {
+			mockAIResponse = JSON.stringify([
+				{ question: "Valid?", type: "text", reason: "Valid reason" },
+				{ type: "text", reason: "Missing question field" },
+				{
+					question: "Also valid?",
+					type: "select",
+					options: ["A", "B"],
+					reason: "OK",
+				},
+			]);
+
+			const result = await generateSpecQuestions(
+				"## Tasks\n- T001: Test",
+				".maina",
+			);
+
+			expect(result.ok).toBe(true);
+			if (result.ok) {
+				expect(result.value).toHaveLength(2);
+				expect(result.value[0]?.question).toBe("Valid?");
+				expect(result.value[1]?.question).toBe("Also valid?");
+			}
+		});
+	});
+});