@mainahq/core 0.2.0

package/src/config/index.ts

@@ -0,0 +1,198 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface MainaConfig {
+	models: {
+		mechanical: string;
+		standard: string;
+		architectural: string;
+		local: string;
+	};
+	provider: string;
+	budget: {
+		daily: number;
+		perTask: number;
+		alertAt: number;
+	};
+	apiKey?: string;
+}
+
+const DEFAULT_CONFIG: MainaConfig = {
+	models: {
+		mechanical: "google/gemini-2.5-flash",
+		standard: "anthropic/claude-sonnet-4",
+		architectural: "anthropic/claude-sonnet-4",
+		local: "ollama/qwen3-coder-8b",
+	},
+	provider: "openrouter",
+	budget: {
+		daily: 5.0,
+		perTask: 0.5,
+		alertAt: 0.8,
+	},
+};
+
+/**
+ * Returns a deep copy of the default config so callers cannot mutate the
+ * internal defaults.
+ */
+export function getDefaultConfig(): MainaConfig {
+	return {
+		...DEFAULT_CONFIG,
+		models: { ...DEFAULT_CONFIG.models },
+		budget: { ...DEFAULT_CONFIG.budget },
+	};
+}
+
+/**
+ * Walks up the directory tree starting at `startDir` (defaults to
+ * process.cwd()) looking for `maina.config.ts` then `maina.config.js`.
+ * Returns the absolute path of the first match, or null if none found.
+ */
+export function findConfigFile(startDir?: string): string | null {
+	let dir = startDir ?? process.cwd();
+	const names = ["maina.config.ts", "maina.config.js"];
+
+	while (true) {
+		for (const name of names) {
+			const candidate = join(dir, name);
+			if (existsSync(candidate)) {
+				return candidate;
+			}
+		}
+
+		const parent = dirname(dir);
+		// Reached filesystem root — stop
+		if (parent === dir) {
+			return null;
+		}
+		dir = parent;
+	}
+}
+
+/**
+ * Finds and dynamically imports the maina config file, then deep-merges it
+ * with the defaults.  Falls back to defaults silently on any error.
+ */
+export async function loadConfig(startDir?: string): Promise<MainaConfig> {
+	const configPath = findConfigFile(startDir);
+
+	if (configPath === null) {
+		return getDefaultConfig();
+	}
+
+	try {
+		const mod = await import(configPath);
+		const userConfig: Partial<MainaConfig> = mod.default ?? mod;
+		return { ...DEFAULT_CONFIG, ...userConfig };
+	} catch {
+		return getDefaultConfig();
+	}
+}
+
+/**
+ * Returns the API key from environment variables, preferring MAINA_API_KEY
+ * over OPENROUTER_API_KEY.  When MAINA_HOST_MODE is set, also checks for
+ * ANTHROPIC_API_KEY (set by Claude Code and similar host agents).
+ * Returns null when no key is found.
+ */
+export function getApiKey(): string | null {
+	return (
+		process.env.MAINA_API_KEY ??
+		process.env.OPENROUTER_API_KEY ??
+		process.env.ANTHROPIC_API_KEY ??
+		null
+	);
+}
+
+/**
+ * Resolves the active provider, allowing the MAINA_PROVIDER environment
+ * variable to override whatever is in the config.
+ *
+ * When running in host mode (MAINA_HOST_MODE=true or ANTHROPIC_API_KEY is set
+ * without explicit provider), auto-detects the appropriate provider:
+ * - ANTHROPIC_API_KEY → "anthropic"
+ * - Otherwise → config default
+ */
+export function resolveProvider(config: MainaConfig): string {
+	// Explicit override always wins
+	if (process.env.MAINA_PROVIDER) {
+		return process.env.MAINA_PROVIDER;
+	}
+
+	// Host mode auto-detection: if running inside Claude Code or similar,
+	// ANTHROPIC_API_KEY is available but no explicit Maina key
+	if (isHostMode()) {
+		if (
+			process.env.ANTHROPIC_API_KEY &&
+			!process.env.MAINA_API_KEY &&
+			!process.env.OPENROUTER_API_KEY
+		) {
+			return "anthropic";
+		}
+	}
+
+	return config.provider;
+}
+
+/**
+ * Detect if Maina is running inside a host agent environment
+ * (e.g., Claude Code, Cursor, Codex).
+ *
+ * Checks for:
+ * - MAINA_HOST_MODE=true (explicit opt-in)
+ * - CLAUDECODE=1 (Claude Code sets this — note: no underscore)
+ * - CLAUDE_CODE_ENTRYPOINT (Claude Code sets this to "cli")
+ * - CURSOR=1 (Cursor sets this)
+ * - ANTHROPIC_API_KEY without MAINA_API_KEY
+ */
+export function isHostMode(): boolean {
+	if (process.env.MAINA_HOST_MODE === "true") return true;
+	// Claude Code sets CLAUDECODE=1 (no underscore) and CLAUDE_CODE_ENTRYPOINT
+	if (process.env.CLAUDECODE === "1") return true;
+	if (process.env.CLAUDE_CODE_ENTRYPOINT) return true;
+	if (process.env.CURSOR === "1") return true;
+	// Infer host mode when we have an Anthropic key but no explicit Maina config
+	if (
+		process.env.ANTHROPIC_API_KEY &&
+		!process.env.MAINA_API_KEY &&
+		!process.env.OPENROUTER_API_KEY
+	) {
+		return true;
+	}
+	return false;
+}
+
+/**
+ * When running inside a host agent (Claude Code, Cursor), AI calls should
+ * be delegated to the host rather than making direct API calls.
+ *
+ * Returns structured prompt data that the host agent can process.
+ * The MCP server or skills package uses this to pass context to the host.
+ *
+ * NOTE: Currently unused — retained for MCP/skills host delegation (Sprint 10+).
+ */
+export interface HostDelegation {
+	mode: "host";
+	systemPrompt: string;
+	userPrompt: string;
+	task: string;
+}
+
+/**
+ * Check if AI should be delegated to host instead of direct API call.
+ *
+ * NOTE: In practice this currently returns true only when MAINA_HOST_MODE=true
+ * is set explicitly with no API keys. The common Claude Code scenario
+ * (CLAUDECODE=1 without API keys) triggers isHostMode() but also triggers
+ * this function's delegation. The generate() function handles this by
+ * returning a [HOST_DELEGATION] prompt string.
+ */
+export function shouldDelegateToHost(): boolean {
+	if (!isHostMode()) return false;
+	// If user has their own API key, use it directly
+	if (process.env.MAINA_API_KEY || process.env.OPENROUTER_API_KEY) return false;
+	if (process.env.ANTHROPIC_API_KEY) return false;
+	// In host mode with no key — delegate to host agent
+	return true;
+}

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

@@ -0,0 +1,179 @@
+import { describe, expect, test } from "bun:test";
+import type { BudgetAllocation, LayerContent } from "../budget";
+import {
+	assembleBudget,
+	calculateTokens,
+	getBudgetRatio,
+	truncateToFit,
+} from "../budget";
+
+describe("calculateTokens", () => {
+	test("returns approximately chars/3.5", () => {
+		const text = "hello world"; // 11 chars → ceil(11/3.5) = ceil(3.14) = 4
+		expect(calculateTokens(text)).toBe(Math.ceil(text.length / 3.5));
+	});
+
+	test("returns 0 for empty string", () => {
+		expect(calculateTokens("")).toBe(0);
+	});
+
+	test("always returns a whole number", () => {
+		const text = "abcde"; // 5 chars → ceil(5/3.5) = ceil(1.43) = 2
+		const result = calculateTokens(text);
+		expect(Number.isInteger(result)).toBe(true);
+		expect(result).toBe(2);
+	});
+});
+
+describe("getBudgetRatio", () => {
+	test("focused mode returns 0.4", () => {
+		expect(getBudgetRatio("focused")).toBe(0.4);
+	});
+
+	test("default mode returns 0.6", () => {
+		expect(getBudgetRatio("default")).toBe(0.6);
+	});
+
+	test("explore mode returns 0.8", () => {
+		expect(getBudgetRatio("explore")).toBe(0.8);
+	});
+});
+
+describe("assembleBudget", () => {
+	test("allocations sum correctly for default mode with default context window", () => {
+		const allocation = assembleBudget("default");
+		// working + episodic + semantic + retrieval + headroom === total
+		const layerSum =
+			allocation.working +
+			allocation.episodic +
+			allocation.semantic +
+			allocation.retrieval +
+			allocation.headroom;
+		expect(layerSum).toBe(allocation.total);
+	});
+
+	test("total equals model context window", () => {
+		const allocation = assembleBudget("default", 100_000);
+		expect(allocation.total).toBe(100_000);
+	});
+
+	test("headroom is correct for focused mode", () => {
+		const modelContext = 200_000;
+		const allocation = assembleBudget("focused", modelContext);
+		const ratio = 0.4;
+		const budget = Math.floor(modelContext * ratio);
+		const expectedHeadroom = modelContext - budget;
+		expect(allocation.headroom).toBe(expectedHeadroom);
+	});
+
+	test("layer allocations sum to budget (not total) for explore mode", () => {
+		const modelContext = 200_000;
+		const allocation = assembleBudget("explore", modelContext);
+		const ratio = 0.8;
+		const budget = Math.floor(modelContext * ratio);
+		const layerSum =
+			allocation.working +
+			allocation.episodic +
+			allocation.semantic +
+			allocation.retrieval;
+		expect(layerSum).toBe(budget);
+	});
+
+	test("working layer is always fully allocated", () => {
+		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
+		expect(allocationFocused.working).toBe(
+			Math.floor(Math.floor(modelContext * 0.4) * 0.25),
+		);
+		expect(allocationDefault.working).toBe(
+			Math.floor(Math.floor(modelContext * 0.6) * 0.25),
+		);
+	});
+});
+
+describe("truncateToFit", () => {
+	const makeLayers = (): LayerContent[] => [
+		{ name: "working", text: "working context", tokens: 100, priority: 0 },
+		{ name: "semantic", text: "semantic context", tokens: 200, priority: 1 },
+		{ name: "episodic", text: "episodic context", tokens: 300, priority: 2 },
+		{ name: "retrieval", text: "retrieval context", tokens: 400, priority: 3 },
+	];
+
+	const makeBudget = (
+		overrides: Partial<BudgetAllocation> = {},
+	): BudgetAllocation => ({
+		working: 100,
+		semantic: 200,
+		episodic: 300,
+		retrieval: 400,
+		headroom: 0,
+		total: 1000,
+		...overrides,
+	});
+
+	test("returns all layers unchanged when within budget", () => {
+		const layers = makeLayers(); // total 1000 tokens
+		const budget = makeBudget(); // total 1000
+		const result = truncateToFit(layers, budget);
+		expect(result).toHaveLength(4);
+	});
+
+	test("removes retrieval first when over budget", () => {
+		const layers = makeLayers(); // total 1000 tokens
+		// Budget only allows 600 tokens total (working+semantic+episodic = 600)
+		const budget = makeBudget({ retrieval: 0, total: 600 });
+		const result = truncateToFit(layers, budget);
+		const names = result.map((l) => l.name);
+		expect(names).not.toContain("retrieval");
+	});
+
+	test("removes episodic after retrieval when still over budget", () => {
+		const layers = makeLayers(); // total 1000 tokens
+		// Budget only allows 300 tokens (working+semantic = 300)
+		const budget = makeBudget({ retrieval: 0, episodic: 0, total: 300 });
+		const result = truncateToFit(layers, budget);
+		const names = result.map((l) => l.name);
+		expect(names).not.toContain("retrieval");
+		expect(names).not.toContain("episodic");
+	});
+
+	test("never removes working context", () => {
+		const layers = makeLayers();
+		// Tiny budget — only enough for working
+		const budget = makeBudget({
+			semantic: 0,
+			episodic: 0,
+			retrieval: 0,
+			total: 100,
+		});
+		const result = truncateToFit(layers, budget);
+		const names = result.map((l) => l.name);
+		expect(names).toContain("working");
+	});
+
+	test("working context is always present even when over budget", () => {
+		const layers = makeLayers();
+		// Absurdly small budget
+		const budget = makeBudget({
+			working: 1,
+			semantic: 0,
+			episodic: 0,
+			retrieval: 0,
+			total: 1,
+		});
+		const result = truncateToFit(layers, budget);
+		expect(result.some((l) => l.name === "working")).toBe(true);
+	});
+
+	test("returns layers sorted by priority after truncation", () => {
+		const layers = makeLayers();
+		const budget = makeBudget({ retrieval: 0, total: 600 });
+		const result = truncateToFit(layers, budget);
+		const priorities = result.map((l) => l.priority);
+		const sorted = [...priorities].sort((a, b) => a - b);
+		expect(priorities).toEqual(sorted);
+	});
+});

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

@@ -0,0 +1,163 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { assembleContext } from "../engine";
+
+// Create a temporary .maina dir for tests
+let tempMainaDir: string;
+const repoRoot = process.cwd();
+
+beforeAll(() => {
+	tempMainaDir = join(tmpdir(), `maina-engine-test-${Date.now()}`);
+	mkdirSync(join(tempMainaDir, "context"), { recursive: true });
+});
+
+afterAll(() => {
+	try {
+		rmSync(tempMainaDir, { recursive: true, force: true });
+	} catch {
+		// ignore cleanup errors
+	}
+});
+
+describe("assembleContext", () => {
+	test("assembleContext('commit') returns an AssembledContext object", async () => {
+		const result = await assembleContext("commit", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+		});
+
+		expect(result).toBeDefined();
+		expect(typeof result.text).toBe("string");
+		expect(typeof result.tokens).toBe("number");
+		expect(Array.isArray(result.layers)).toBe(true);
+		expect(result.mode).toBeDefined();
+		expect(result.budget).toBeDefined();
+	});
+
+	test("assembleContext('commit') has budget mode 'focused'", async () => {
+		const result = await assembleContext("commit", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+		});
+
+		expect(result.mode).toBe("focused");
+	});
+
+	test("assembleContext('commit') includes working layer", async () => {
+		const result = await assembleContext("commit", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+		});
+
+		const workingLayer = result.layers.find((l) => l.name === "working");
+		expect(workingLayer).toBeDefined();
+		expect(workingLayer?.included).toBe(true);
+	});
+
+	test("assembleContext returns tokens count > 0", async () => {
+		const result = await assembleContext("commit", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+		});
+
+		expect(result.tokens).toBeGreaterThan(0);
+	});
+
+	test("assembleContext returns layer reports", async () => {
+		const result = await assembleContext("commit", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+		});
+
+		expect(result.layers.length).toBeGreaterThan(0);
+		for (const layer of result.layers) {
+			expect(typeof layer.name).toBe("string");
+			expect(typeof layer.tokens).toBe("number");
+			expect(typeof layer.entries).toBe("number");
+			expect(typeof layer.included).toBe("boolean");
+		}
+	});
+
+	test("assembled text is non-empty", async () => {
+		const result = await assembleContext("commit", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+		});
+
+		expect(result.text.length).toBeGreaterThan(0);
+	});
+
+	test("working layer is always present in layer reports", async () => {
+		const result = await assembleContext("commit", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+		});
+
+		const workingLayer = result.layers.find((l) => l.name === "working");
+		expect(workingLayer).toBeDefined();
+	});
+
+	test("assembleContext('context') includes more layers than 'commit'", async () => {
+		const [commitResult, contextResult] = await Promise.all([
+			assembleContext("commit", { repoRoot, mainaDir: tempMainaDir }),
+			assembleContext("context", { repoRoot, mainaDir: tempMainaDir }),
+		]);
+
+		const commitIncluded = commitResult.layers.filter((l) => l.included).length;
+		const contextIncluded = contextResult.layers.filter(
+			(l) => l.included,
+		).length;
+
+		expect(contextIncluded).toBeGreaterThanOrEqual(commitIncluded);
+	});
+
+	test("assembleContext('context') has budget mode 'explore'", async () => {
+		const result = await assembleContext("context", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+		});
+
+		expect(result.mode).toBe("explore");
+	});
+
+	test("assembleContext is resilient — returns valid result even with bad mainaDir", async () => {
+		const result = await assembleContext("commit", {
+			repoRoot,
+			mainaDir: join(tmpdir(), "nonexistent-maina-dir-xyz"),
+		});
+
+		// Should not throw; should return a valid (possibly minimal) context
+		expect(result).toBeDefined();
+		expect(typeof result.text).toBe("string");
+		expect(typeof result.tokens).toBe("number");
+	});
+
+	test("assembleContext with searchQuery includes retrieval layer for 'context' command", async () => {
+		const result = await assembleContext("context", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+			searchQuery: "assembleContext",
+		});
+
+		const retrievalLayer = result.layers.find((l) => l.name === "retrieval");
+		// retrieval layer should be present (included or not depending on results)
+		expect(retrievalLayer).toBeDefined();
+	});
+
+	test("budget allocation is populated with numeric values", async () => {
+		const result = await assembleContext("commit", {
+			repoRoot,
+			mainaDir: tempMainaDir,
+		});
+
+		expect(typeof result.budget.working).toBe("number");
+		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.total).toBe("number");
+		expect(typeof result.budget.headroom).toBe("number");
+		expect(result.budget.total).toBeGreaterThan(0);
+	});
+});