@mainahq/core 0.2.0

package/src/cache/manager.ts

@@ -0,0 +1,231 @@
+import { getCacheDb } from "../db/index";
+
+export interface CacheEntry {
+	key: string;
+	value: string;
+	createdAt: number; // Unix timestamp ms
+	ttl: number; // seconds, 0 = forever
+	promptVersion?: string;
+	contextHash?: string;
+	model?: string;
+}
+
+export interface CacheStats {
+	l1Hits: number;
+	l2Hits: number;
+	misses: number;
+	totalQueries: number;
+	entriesL1: number;
+	entriesL2: number;
+}
+
+interface CacheSetOptions {
+	ttl?: number;
+	promptVersion?: string;
+	contextHash?: string;
+	model?: string;
+}
+
+/** Returns true when the entry has exceeded its TTL. */
+function isExpired(entry: CacheEntry): boolean {
+	if (entry.ttl <= 0) return false;
+	return Date.now() - entry.createdAt > entry.ttl * 1000;
+}
+
+/** Raw row shape returned by SQLite queries. */
+interface RawRow {
+	key: string;
+	value: string;
+	created_at: string;
+	ttl: number | null;
+	prompt_version: string | null;
+	context_hash: string | null;
+	model: string | null;
+}
+
+function rowToEntry(row: RawRow): CacheEntry {
+	return {
+		key: row.key,
+		value: row.value,
+		createdAt: Number(row.created_at),
+		ttl: row.ttl ?? 0,
+		promptVersion: row.prompt_version ?? undefined,
+		contextHash: row.context_hash ?? undefined,
+		model: row.model ?? undefined,
+	};
+}
+
+const L1_MAX = 100;
+
+export interface CacheManager {
+	get(key: string): CacheEntry | null;
+	set(key: string, value: string, options?: CacheSetOptions): void;
+	has(key: string): boolean;
+	invalidate(key: string): void;
+	clear(): void;
+	stats(): CacheStats;
+}
+
+export function createCacheManager(mainaDir: string): CacheManager {
+	// Initialise L2 (SQLite)
+	const dbResult = getCacheDb(mainaDir);
+	if (!dbResult.ok) {
+		// Return a no-op manager that always misses — never throw
+		const noop: CacheManager = {
+			get: () => null,
+			set: () => {
+				/* no-op */
+			},
+			has: () => false,
+			invalidate: () => {
+				/* no-op */
+			},
+			clear: () => {
+				/* no-op */
+			},
+			stats: () => ({
+				l1Hits: 0,
+				l2Hits: 0,
+				misses: 0,
+				totalQueries: 0,
+				entriesL1: 0,
+				entriesL2: 0,
+			}),
+		};
+		return noop;
+	}
+
+	const { db } = dbResult.value;
+
+	// Prepared statements
+	const stmtGet = db.prepare<RawRow, [string]>(
+		`SELECT key, value, created_at, ttl, prompt_version, context_hash, model
+		 FROM cache_entries WHERE key = ?`,
+	);
+	const stmtInsert = db.prepare(
+		`INSERT OR REPLACE INTO cache_entries
+		 (id, key, value, created_at, ttl, prompt_version, context_hash, model)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+	);
+	const stmtDelete = db.prepare(`DELETE FROM cache_entries WHERE key = ?`);
+	const stmtClear = db.prepare(`DELETE FROM cache_entries`);
+	const stmtCount = db.prepare<{ cnt: number }, []>(
+		`SELECT COUNT(*) as cnt FROM cache_entries`,
+	);
+
+	// L1 in-memory map (maintains insertion order for eviction)
+	const l1 = new Map<string, CacheEntry>();
+
+	// Stats counters
+	let l1Hits = 0;
+	let l2Hits = 0;
+	let misses = 0;
+
+	function evictIfNeeded(): void {
+		if (l1.size >= L1_MAX) {
+			// Delete the first (oldest) key
+			const firstKey = l1.keys().next().value;
+			if (firstKey !== undefined) {
+				l1.delete(firstKey);
+			}
+		}
+	}
+
+	function get(key: string): CacheEntry | null {
+		// Check L1
+		const l1Entry = l1.get(key);
+		if (l1Entry !== undefined) {
+			if (isExpired(l1Entry)) {
+				l1.delete(key);
+				// Fall through to check L2 (it will also be expired, but be consistent)
+			} else {
+				l1Hits++;
+				return l1Entry;
+			}
+		}
+
+		// Check L2
+		const row = stmtGet.get(key);
+		if (row == null) {
+			misses++;
+			return null;
+		}
+
+		const entry = rowToEntry(row);
+		if (isExpired(entry)) {
+			misses++;
+			return null;
+		}
+
+		// Promote to L1
+		l2Hits++;
+		evictIfNeeded();
+		l1.set(key, entry);
+		return entry;
+	}
+
+	function set(key: string, value: string, options?: CacheSetOptions): void {
+		const now = Date.now();
+		const ttl = options?.ttl ?? 0;
+		const entry: CacheEntry = {
+			key,
+			value,
+			createdAt: now,
+			ttl,
+			promptVersion: options?.promptVersion,
+			contextHash: options?.contextHash,
+			model: options?.model,
+		};
+
+		// Write to L2 first
+		const id = `${key}-${now}`;
+		stmtInsert.run(
+			id,
+			key,
+			value,
+			String(now),
+			ttl,
+			options?.promptVersion ?? null,
+			options?.contextHash ?? null,
+			options?.model ?? null,
+		);
+
+		// Write to L1 (evict oldest if needed)
+		if (l1.has(key)) {
+			// Update in-place without changing insertion order (delete + re-insert)
+			l1.delete(key);
+		} else {
+			evictIfNeeded();
+		}
+		l1.set(key, entry);
+	}
+
+	function has(key: string): boolean {
+		return get(key) !== null;
+	}
+
+	function invalidate(key: string): void {
+		l1.delete(key);
+		stmtDelete.run(key);
+	}
+
+	function clear(): void {
+		l1.clear();
+		stmtClear.run();
+	}
+
+	function stats(): CacheStats {
+		const countRow = stmtCount.get();
+		const entriesL2 = countRow?.cnt ?? 0;
+		return {
+			l1Hits,
+			l2Hits,
+			misses,
+			totalQueries: l1Hits + l2Hits + misses,
+			entriesL1: l1.size,
+			entriesL2,
+		};
+	}
+
+	return { get, set, has, invalidate, clear, stats };
+}

package/src/cache/ttl.ts

@@ -0,0 +1,77 @@
+export type TaskType =
+	| "review"
+	| "tests"
+	| "fix"
+	| "commit"
+	| "context"
+	| "explain"
+	| "design"
+	| "plan";
+
+export interface TtlRule {
+	task: TaskType;
+	ttl: number;
+	description: string;
+}
+
+const TTL_RULES: TtlRule[] = [
+	{
+		task: "review",
+		ttl: 0,
+		description: "Code review — cached forever, keyed by content hash",
+	},
+	{
+		task: "tests",
+		ttl: 0,
+		description: "Test generation — cached forever, keyed by content hash",
+	},
+	{
+		task: "fix",
+		ttl: 0,
+		description: "Bug fix — cached forever, keyed by content hash",
+	},
+	{
+		task: "commit",
+		ttl: 0,
+		description: "Commit message — cached forever, keyed by content hash",
+	},
+	{
+		task: "context",
+		ttl: 3600,
+		description: "Context assembly — cached for 1 hour",
+	},
+	{
+		task: "explain",
+		ttl: 86400,
+		description: "Code explanation — cached for 24 hours",
+	},
+	{
+		task: "design",
+		ttl: 86400,
+		description: "Design advice — cached for 24 hours",
+	},
+	{
+		task: "plan",
+		ttl: 86400,
+		description: "Planning — cached for 24 hours",
+	},
+];
+
+const TTL_MAP: Record<TaskType, number> = Object.fromEntries(
+	TTL_RULES.map((r) => [r.task, r.ttl]),
+) as Record<TaskType, number>;
+
+export function getTtl(task: TaskType): number {
+	return TTL_MAP[task] ?? 0;
+}
+
+export function isExpired(createdAt: number, ttl: number): boolean {
+	if (ttl === 0) {
+		return false;
+	}
+	return Date.now() - createdAt > ttl * 1000;
+}
+
+export function getAllRules(): TtlRule[] {
+	return TTL_RULES;
+}

package/src/config/__tests__/config.test.ts

@@ -0,0 +1,376 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	findConfigFile,
+	getApiKey,
+	getDefaultConfig,
+	isHostMode,
+	loadConfig,
+	resolveProvider,
+} from "../index";
+
+// ─── getDefaultConfig ────────────────────────────────────────────────────────
+
+describe("getDefaultConfig", () => {
+	test("returns a config with all required top-level fields", () => {
+		const config = getDefaultConfig();
+		expect(config).toHaveProperty("models");
+		expect(config).toHaveProperty("provider");
+		expect(config).toHaveProperty("budget");
+	});
+
+	test("models has all four required keys", () => {
+		const { models } = getDefaultConfig();
+		expect(models).toHaveProperty("mechanical");
+		expect(models).toHaveProperty("standard");
+		expect(models).toHaveProperty("architectural");
+		expect(models).toHaveProperty("local");
+	});
+
+	test("budget has daily, perTask, and alertAt", () => {
+		const { budget } = getDefaultConfig();
+		expect(budget).toHaveProperty("daily");
+		expect(budget).toHaveProperty("perTask");
+		expect(budget).toHaveProperty("alertAt");
+	});
+
+	test("returns a copy — mutations do not affect subsequent calls", () => {
+		const first = getDefaultConfig();
+		first.provider = "mutated";
+		const second = getDefaultConfig();
+		expect(second.provider).toBe("openrouter");
+	});
+
+	test("default provider is openrouter", () => {
+		expect(getDefaultConfig().provider).toBe("openrouter");
+	});
+
+	test("default daily budget is 5.0", () => {
+		expect(getDefaultConfig().budget.daily).toBe(5.0);
+	});
+});
+
+// ─── findConfigFile ───────────────────────────────────────────────────────────
+
+describe("findConfigFile", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = join(
+			tmpdir(),
+			`maina-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+		);
+		mkdirSync(tmpDir, { recursive: true });
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	test("returns null when no config file exists", () => {
+		const result = findConfigFile(tmpDir);
+		expect(result).toBeNull();
+	});
+
+	test("finds maina.config.ts in the start directory", () => {
+		const configPath = join(tmpDir, "maina.config.ts");
+		writeFileSync(configPath, "export default {};");
+		const result = findConfigFile(tmpDir);
+		expect(result).toBe(configPath);
+	});
+
+	test("finds maina.config.js in the start directory", () => {
+		const configPath = join(tmpDir, "maina.config.js");
+		writeFileSync(configPath, "module.exports = {};");
+		const result = findConfigFile(tmpDir);
+		expect(result).toBe(configPath);
+	});
+
+	test("finds config in a parent directory", () => {
+		const subDir = join(tmpDir, "nested", "deep");
+		mkdirSync(subDir, { recursive: true });
+		const configPath = join(tmpDir, "maina.config.ts");
+		writeFileSync(configPath, "export default {};");
+		const result = findConfigFile(subDir);
+		expect(result).toBe(configPath);
+	});
+
+	test("prefers maina.config.ts over maina.config.js when both exist", () => {
+		const tsPath = join(tmpDir, "maina.config.ts");
+		const jsPath = join(tmpDir, "maina.config.js");
+		writeFileSync(tsPath, "export default {};");
+		writeFileSync(jsPath, "module.exports = {};");
+		const result = findConfigFile(tmpDir);
+		expect(result).toBe(tsPath);
+	});
+});
+
+// ─── loadConfig ──────────────────────────────────────────────────────────────
+
+describe("loadConfig", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = join(
+			tmpdir(),
+			`maina-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+		);
+		mkdirSync(tmpDir, { recursive: true });
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	test("returns defaults when no config file is found", async () => {
+		const config = await loadConfig(tmpDir);
+		const defaults = getDefaultConfig();
+		expect(config.provider).toBe(defaults.provider);
+		expect(config.budget.daily).toBe(defaults.budget.daily);
+		expect(config.models.standard).toBe(defaults.models.standard);
+	});
+
+	test("merges a partial config with defaults", async () => {
+		const configPath = join(tmpDir, "maina.config.js");
+		// CJS: module.exports becomes mod.default when dynamically imported
+		writeFileSync(
+			configPath,
+			`module.exports = { provider: "custom-provider" };`,
+		);
+		const config = await loadConfig(tmpDir);
+		expect(config.provider).toBe("custom-provider");
+		// Defaults are preserved for unspecified fields
+		expect(config.budget.daily).toBe(5.0);
+		expect(config.models.standard).toBe("anthropic/claude-sonnet-4");
+	});
+
+	test("never throws — returns defaults on any import error", async () => {
+		// Point at an empty temp dir where no config exists
+		const emptyDir = join(tmpDir, "empty");
+		mkdirSync(emptyDir, { recursive: true });
+		const config = await loadConfig(emptyDir);
+		expect(config).toBeDefined();
+		expect(config.provider).toBe("openrouter");
+	});
+});
+
+// ─── getApiKey ────────────────────────────────────────────────────────────────
+
+describe("getApiKey", () => {
+	test("returns null when neither env var is set", () => {
+		// Temporarily unset both vars for isolation
+		const saved1 = process.env.MAINA_API_KEY;
+		const saved2 = process.env.OPENROUTER_API_KEY;
+		delete process.env.MAINA_API_KEY;
+		delete process.env.OPENROUTER_API_KEY;
+
+		const result = getApiKey();
+
+		// Restore
+		if (saved1 !== undefined) process.env.MAINA_API_KEY = saved1;
+		if (saved2 !== undefined) process.env.OPENROUTER_API_KEY = saved2;
+
+		expect(result).toBeNull();
+	});
+
+	test("returns MAINA_API_KEY when set", () => {
+		const saved1 = process.env.MAINA_API_KEY;
+		const saved2 = process.env.OPENROUTER_API_KEY;
+		process.env.MAINA_API_KEY = "test-maina-key";
+		delete process.env.OPENROUTER_API_KEY;
+
+		const result = getApiKey();
+
+		if (saved1 !== undefined) process.env.MAINA_API_KEY = saved1;
+		else delete process.env.MAINA_API_KEY;
+		if (saved2 !== undefined) process.env.OPENROUTER_API_KEY = saved2;
+
+		expect(result).toBe("test-maina-key");
+	});
+
+	test("returns OPENROUTER_API_KEY when MAINA_API_KEY is not set", () => {
+		const saved1 = process.env.MAINA_API_KEY;
+		const saved2 = process.env.OPENROUTER_API_KEY;
+		delete process.env.MAINA_API_KEY;
+		process.env.OPENROUTER_API_KEY = "test-openrouter-key";
+
+		const result = getApiKey();
+
+		if (saved1 !== undefined) process.env.MAINA_API_KEY = saved1;
+		if (saved2 !== undefined) process.env.OPENROUTER_API_KEY = saved2;
+		else delete process.env.OPENROUTER_API_KEY;
+
+		expect(result).toBe("test-openrouter-key");
+	});
+
+	test("MAINA_API_KEY takes precedence over OPENROUTER_API_KEY", () => {
+		const saved1 = process.env.MAINA_API_KEY;
+		const saved2 = process.env.OPENROUTER_API_KEY;
+		process.env.MAINA_API_KEY = "maina-wins";
+		process.env.OPENROUTER_API_KEY = "openrouter-loses";
+
+		const result = getApiKey();
+
+		if (saved1 !== undefined) process.env.MAINA_API_KEY = saved1;
+		else delete process.env.MAINA_API_KEY;
+		if (saved2 !== undefined) process.env.OPENROUTER_API_KEY = saved2;
+		else delete process.env.OPENROUTER_API_KEY;
+
+		expect(result).toBe("maina-wins");
+	});
+});
+
+// ─── resolveProvider ─────────────────────────────────────────────────────────
+
+describe("resolveProvider", () => {
+	test("returns config provider by default", () => {
+		const config = getDefaultConfig();
+		const saved = process.env.MAINA_PROVIDER;
+		delete process.env.MAINA_PROVIDER;
+
+		const result = resolveProvider(config);
+
+		if (saved !== undefined) process.env.MAINA_PROVIDER = saved;
+
+		expect(result).toBe("openrouter");
+	});
+
+	test("MAINA_PROVIDER env var overrides config provider", () => {
+		const config = getDefaultConfig();
+		const saved = process.env.MAINA_PROVIDER;
+		process.env.MAINA_PROVIDER = "env-provider";
+
+		const result = resolveProvider(config);
+
+		if (saved !== undefined) process.env.MAINA_PROVIDER = saved;
+		else delete process.env.MAINA_PROVIDER;
+
+		expect(result).toBe("env-provider");
+	});
+
+	test("returns custom config provider when no env var", () => {
+		const config = { ...getDefaultConfig(), provider: "my-custom-provider" };
+		const saved = process.env.MAINA_PROVIDER;
+		delete process.env.MAINA_PROVIDER;
+
+		const result = resolveProvider(config);
+
+		if (saved !== undefined) process.env.MAINA_PROVIDER = saved;
+
+		expect(result).toBe("my-custom-provider");
+	});
+
+	test("auto-detects anthropic provider in host mode", () => {
+		const saved = {
+			provider: process.env.MAINA_PROVIDER,
+			maina: process.env.MAINA_API_KEY,
+			openrouter: process.env.OPENROUTER_API_KEY,
+			anthropic: process.env.ANTHROPIC_API_KEY,
+			hostMode: process.env.MAINA_HOST_MODE,
+		};
+		delete process.env.MAINA_PROVIDER;
+		delete process.env.MAINA_API_KEY;
+		delete process.env.OPENROUTER_API_KEY;
+		process.env.ANTHROPIC_API_KEY = "sk-ant-test";
+		process.env.MAINA_HOST_MODE = "true";
+
+		const config = getDefaultConfig();
+		const result = resolveProvider(config);
+
+		// Restore
+		if (saved.provider !== undefined)
+			process.env.MAINA_PROVIDER = saved.provider;
+		if (saved.maina !== undefined) process.env.MAINA_API_KEY = saved.maina;
+		if (saved.openrouter !== undefined)
+			process.env.OPENROUTER_API_KEY = saved.openrouter;
+		if (saved.anthropic !== undefined)
+			process.env.ANTHROPIC_API_KEY = saved.anthropic;
+		else delete process.env.ANTHROPIC_API_KEY;
+		if (saved.hostMode !== undefined)
+			process.env.MAINA_HOST_MODE = saved.hostMode;
+		else delete process.env.MAINA_HOST_MODE;
+
+		expect(result).toBe("anthropic");
+	});
+});
+
+// ─── isHostMode ─────────────────────────────────────────────────────────────
+
+describe("isHostMode", () => {
+	test("returns true when MAINA_HOST_MODE=true", () => {
+		const saved = process.env.MAINA_HOST_MODE;
+		process.env.MAINA_HOST_MODE = "true";
+
+		const result = isHostMode();
+
+		if (saved !== undefined) process.env.MAINA_HOST_MODE = saved;
+		else delete process.env.MAINA_HOST_MODE;
+
+		expect(result).toBe(true);
+	});
+
+	test("returns true when ANTHROPIC_API_KEY set without Maina keys", () => {
+		const saved = {
+			maina: process.env.MAINA_API_KEY,
+			openrouter: process.env.OPENROUTER_API_KEY,
+			anthropic: process.env.ANTHROPIC_API_KEY,
+			hostMode: process.env.MAINA_HOST_MODE,
+		};
+		delete process.env.MAINA_API_KEY;
+		delete process.env.OPENROUTER_API_KEY;
+		delete process.env.MAINA_HOST_MODE;
+		process.env.ANTHROPIC_API_KEY = "sk-ant-test";
+
+		const result = isHostMode();
+
+		if (saved.maina !== undefined) process.env.MAINA_API_KEY = saved.maina;
+		if (saved.openrouter !== undefined)
+			process.env.OPENROUTER_API_KEY = saved.openrouter;
+		if (saved.anthropic !== undefined)
+			process.env.ANTHROPIC_API_KEY = saved.anthropic;
+		else delete process.env.ANTHROPIC_API_KEY;
+		if (saved.hostMode !== undefined)
+			process.env.MAINA_HOST_MODE = saved.hostMode;
+
+		expect(result).toBe(true);
+	});
+
+	test("returns false when no host indicators present", () => {
+		const saved = {
+			maina: process.env.MAINA_API_KEY,
+			openrouter: process.env.OPENROUTER_API_KEY,
+			anthropic: process.env.ANTHROPIC_API_KEY,
+			hostMode: process.env.MAINA_HOST_MODE,
+			claude: process.env.CLAUDECODE,
+			claudeEntrypoint: process.env.CLAUDE_CODE_ENTRYPOINT,
+			cursor: process.env.CURSOR,
+		};
+		delete process.env.MAINA_HOST_MODE;
+		delete process.env.ANTHROPIC_API_KEY;
+		delete process.env.CLAUDECODE;
+		delete process.env.CLAUDE_CODE_ENTRYPOINT;
+		delete process.env.CURSOR;
+		process.env.MAINA_API_KEY = "test";
+
+		const result = isHostMode();
+
+		// Restore
+		if (saved.maina !== undefined) process.env.MAINA_API_KEY = saved.maina;
+		else delete process.env.MAINA_API_KEY;
+		if (saved.openrouter !== undefined)
+			process.env.OPENROUTER_API_KEY = saved.openrouter;
+		if (saved.anthropic !== undefined)
+			process.env.ANTHROPIC_API_KEY = saved.anthropic;
+		if (saved.hostMode !== undefined)
+			process.env.MAINA_HOST_MODE = saved.hostMode;
+		if (saved.claude !== undefined) process.env.CLAUDECODE = saved.claude;
+		if (saved.claudeEntrypoint !== undefined)
+			process.env.CLAUDE_CODE_ENTRYPOINT = saved.claudeEntrypoint;
+		else delete process.env.CLAUDE_CODE_ENTRYPOINT;
+		if (saved.cursor !== undefined) process.env.CURSOR = saved.cursor;
+
+		expect(result).toBe(false);
+	});
+});