@mainahq/core 0.2.0

package/src/benchmark/types.ts

@@ -0,0 +1,95 @@
+export interface StoryConfig {
+	name: string;
+	description: string;
+	tier: number;
+	source: string;
+	testFiles: string[];
+	/** Hidden validation tests — not shown to AI during implementation */
+	validationFiles?: string[];
+	metrics: {
+		expectedTests: number;
+		expectedValidationTests?: number;
+		originalLOC: number;
+		complexity: "easy" | "medium" | "hard";
+	};
+}
+
+export interface BenchmarkMetrics {
+	pipeline: "maina" | "speckit";
+	storyName: string;
+	wallClockMs: number;
+	tokensInput: number;
+	tokensOutput: number;
+	testsTotal: number;
+	testsPassed: number;
+	testsFailed: number;
+	verifyFindings: number;
+	specQualityScore: number;
+	// Extended metrics from tier 1 learnings
+	implLOC: number;
+	attemptsToPass: number;
+	bugsIntroduced: number;
+	toolsUsed: string[];
+	stepTimings?: Record<string, number>;
+}
+
+export interface BenchmarkReport {
+	story: StoryConfig;
+	maina: BenchmarkMetrics | null;
+	speckit: BenchmarkMetrics | null;
+	timestamp: string;
+	winner: "maina" | "speckit" | "tie" | "incomplete";
+}
+
+export interface LoadedStory {
+	config: StoryConfig;
+	specContent: string;
+	testFiles: Array<{ name: string; content: string }>;
+	storyDir: string;
+}
+
+export interface StepMetrics {
+	name: string;
+	durationMs: number;
+	tokensInput: number;
+	tokensOutput: number;
+	artifacts: string[];
+	// Optional per-step data
+	questionsAsked?: number;
+	testsGenerated?: number;
+	approachesProposed?: number;
+	loc?: number;
+	attempts?: number;
+	findings?: number;
+	findingsBySeverity?: Record<string, number>;
+	issuesFound?: number;
+	passed?: boolean;
+}
+
+export interface Tier3Totals {
+	durationMs: number;
+	tokensInput: number;
+	tokensOutput: number;
+	bugsIntroduced: number;
+	bugsCaught: number;
+	testsPassed: number;
+	testsTotal: number;
+	/** Validation-only metrics (hidden tests, not shown during implementation) */
+	validationPassed?: number;
+	validationTotal?: number;
+}
+
+export interface Tier3Results {
+	story: StoryConfig;
+	timestamp: string;
+	maina: {
+		steps: Record<string, StepMetrics>;
+		totals: Tier3Totals;
+	};
+	speckit: {
+		steps: Record<string, StepMetrics>;
+		totals: Tier3Totals;
+	};
+	winner: "maina" | "speckit" | "tie" | "incomplete";
+	learnings: string[];
+}

package/src/cache/__tests__/keys.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "bun:test";
+import { buildCacheKey, hashContent, hashFile, hashFiles } from "../keys";
+
+describe("hashContent", () => {
+	it("returns a consistent hex string", () => {
+		const result = hashContent("hello");
+		expect(typeof result).toBe("string");
+		expect(result).toMatch(/^[0-9a-f]{64}$/);
+	});
+
+	it("returns the same hash for the same input", () => {
+		expect(hashContent("hello")).toBe(hashContent("hello"));
+	});
+
+	it("returns different hashes for different inputs", () => {
+		expect(hashContent("hello")).not.toBe(hashContent("world"));
+	});
+});
+
+describe("hashFile", () => {
+	it("returns a hash for an existing file", async () => {
+		// Use this test file itself as the existing file
+		const result = await hashFile(import.meta.path);
+		expect(typeof result).toBe("string");
+		expect(result).toMatch(/^[0-9a-f]{64}$/);
+		expect(result.length).toBeGreaterThan(0);
+	});
+
+	it("returns empty string for a non-existent file", async () => {
+		const result = await hashFile("/this/path/does/not/exist/at/all.ts");
+		expect(result).toBe("");
+	});
+});
+
+describe("hashFiles", () => {
+	it("returns a string hash for a list of files", async () => {
+		const result = await hashFiles([import.meta.path]);
+		expect(typeof result).toBe("string");
+		expect(result).toMatch(/^[0-9a-f]{64}$/);
+	});
+
+	it("is order-independent (sorted internally)", async () => {
+		const thisFile = import.meta.path;
+		// Use two real files that exist in the repo
+		const otherFile = import.meta.path.replace("keys.test.ts", "ttl.test.ts");
+		const result1 = await hashFiles([thisFile, otherFile]);
+		const result2 = await hashFiles([otherFile, thisFile]);
+		expect(result1).toBe(result2);
+	});
+
+	it("returns empty string for empty array", async () => {
+		const result = await hashFiles([]);
+		expect(result).toBe("");
+	});
+});
+
+describe("buildCacheKey", () => {
+	it("returns a string", async () => {
+		const key = await buildCacheKey({ task: "review" });
+		expect(typeof key).toBe("string");
+		expect(key.length).toBeGreaterThan(0);
+	});
+
+	it("same input produces same key", async () => {
+		const input = { task: "review", model: "gpt-4o", extra: "abc" };
+		const key1 = await buildCacheKey(input);
+		const key2 = await buildCacheKey(input);
+		expect(key1).toBe(key2);
+	});
+
+	it("different task produces different key", async () => {
+		const key1 = await buildCacheKey({ task: "review" });
+		const key2 = await buildCacheKey({ task: "commit" });
+		expect(key1).not.toBe(key2);
+	});
+
+	it("different files produce different key", async () => {
+		const key1 = await buildCacheKey({
+			task: "review",
+			files: [import.meta.path],
+		});
+		const key2 = await buildCacheKey({
+			task: "review",
+			files: ["/nonexistent/path.ts"],
+		});
+		expect(key1).not.toBe(key2);
+	});
+
+	it("returns a hex string of 64 characters", async () => {
+		const key = await buildCacheKey({
+			task: "explain",
+			model: "claude-3",
+			promptHash: "abc123",
+		});
+		expect(key).toMatch(/^[0-9a-f]{64}$/);
+	});
+});

package/src/cache/__tests__/manager.test.ts

@@ -0,0 +1,312 @@
+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 { createCacheManager } from "../manager";
+
+const TEST_DIR = join(tmpdir(), `maina-cache-test-${Date.now()}`);
+
+beforeAll(() => {
+	mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterAll(() => {
+	rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+function makeDir(sub: string): string {
+	const d = join(TEST_DIR, sub);
+	mkdirSync(d, { recursive: true });
+	return d;
+}
+
+describe("set + get", () => {
+	test("set then get returns cached value", () => {
+		const cache = createCacheManager(makeDir("set-get"));
+		cache.set("k1", "hello");
+		const entry = cache.get("k1");
+		expect(entry).not.toBeNull();
+		expect(entry?.value).toBe("hello");
+		expect(entry?.key).toBe("k1");
+	});
+
+	test("get returns null for missing key", () => {
+		const cache = createCacheManager(makeDir("missing"));
+		const entry = cache.get("nonexistent");
+		expect(entry).toBeNull();
+	});
+
+	test("set stores optional fields", () => {
+		const cache = createCacheManager(makeDir("optional-fields"));
+		cache.set("k2", "world", {
+			ttl: 3600,
+			promptVersion: "v1",
+			contextHash: "abc",
+			model: "claude-3-5-sonnet",
+		});
+		const entry = cache.get("k2");
+		expect(entry).not.toBeNull();
+		expect(entry?.ttl).toBe(3600);
+		expect(entry?.promptVersion).toBe("v1");
+		expect(entry?.contextHash).toBe("abc");
+		expect(entry?.model).toBe("claude-3-5-sonnet");
+	});
+});
+
+describe("L1 vs L2 hit behaviour", () => {
+	test("L1 hit does not query L2 (entry stays in memory map)", () => {
+		const cache = createCacheManager(makeDir("l1-hit"));
+		cache.set("k1", "value");
+
+		// First get populates L1; subsequent gets should be L1 hits
+		cache.get("k1"); // primes L1
+
+		const stats1 = cache.stats();
+		cache.get("k1"); // L1 hit
+		const stats2 = cache.stats();
+
+		// l1Hits should have incremented
+		expect(stats2.l1Hits).toBeGreaterThan(stats1.l1Hits);
+		// l2Hits should not have changed
+		expect(stats2.l2Hits).toBe(stats1.l2Hits);
+	});
+
+	test("L2 hit promotes entry to L1", () => {
+		const mainaDir = makeDir("l2-promote");
+		// Populate L2 directly via a first manager instance
+		const cache1 = createCacheManager(mainaDir);
+		cache1.set("k1", "from-l2");
+
+		// Create a fresh manager (empty L1) pointing to the same DB
+		const cache2 = createCacheManager(mainaDir);
+
+		// get should find it in L2 and promote to L1
+		const entry = cache2.get("k1");
+		expect(entry).not.toBeNull();
+		expect(entry?.value).toBe("from-l2");
+
+		const stats = cache2.stats();
+		expect(stats.l2Hits).toBe(1);
+		expect(stats.l1Hits).toBe(0);
+
+		// Second get should now be an L1 hit
+		cache2.get("k1");
+		const stats2 = cache2.stats();
+		expect(stats2.l1Hits).toBe(1);
+	});
+});
+
+describe("TTL expiry", () => {
+	test("expired entry returns null", () => {
+		const _cache = createCacheManager(makeDir("ttl"));
+		const _past = Date.now() - 10_000; // 10 seconds ago
+
+		// Manually insert with a past createdAt via set then manipulate via get
+		// We test expiry by setting ttl=1 and forging createdAt in the future check.
+		// Instead we use a negative ttl trick: we'll insert with ttl=1s and
+		// backdate by injecting via the DB. Use a fresh manager whose L2 we write to.
+		const m = createCacheManager(makeDir("ttl2"));
+
+		// Use internal set to write an "already expired" entry
+		// We can't easily backdated via the public API, so we verify via the
+		// has() method after testing with a ttl=0 (never expires) and ttl that
+		// hasn't elapsed.
+
+		// ttl=0 means forever
+		m.set("forever", "val", { ttl: 0 });
+		expect(m.get("forever")).not.toBeNull();
+
+		// ttl=100s — should not be expired yet
+		m.set("soon", "val", { ttl: 100 });
+		expect(m.get("soon")).not.toBeNull();
+	});
+
+	test("entry with elapsed TTL is treated as expired", () => {
+		// We create a cache manager, write an entry, then manually poke the
+		// underlying SQLite to backdate it so TTL appears elapsed.
+		const mainaDir = makeDir("ttl-elapsed");
+		const cache = createCacheManager(mainaDir);
+		cache.set("oldkey", "oldval", { ttl: 1 }); // 1 second TTL
+
+		// The entry is fresh right now — still valid
+		expect(cache.get("oldkey")).not.toBeNull();
+
+		// Now create a second manager instance that shares the DB.
+		// We'll insert a raw row with a very old createdAt so it looks expired.
+		const { initDatabase } = require("../../db/index");
+		const { join: pjoin } = require("node:path");
+		const dbResult = initDatabase(pjoin(mainaDir, "cache", "cache.db"));
+		if (!dbResult.ok) throw new Error("db failed");
+		const db = dbResult.value.db;
+		const nowMs = Date.now() - 5_000; // 5 seconds ago
+		db.prepare(
+			`INSERT OR REPLACE INTO cache_entries (id, key, value, created_at, ttl)
+			 VALUES (?, ?, ?, ?, ?)`,
+		).run("expired-id", "expiredkey", "expiredval", String(nowMs), 1);
+		db.close();
+
+		// Fresh manager: L1 is empty, will look up L2
+		const cache2 = createCacheManager(mainaDir);
+		const result = cache2.get("expiredkey");
+		expect(result).toBeNull();
+	});
+});
+
+describe("L1 eviction at capacity", () => {
+	test("L1 evicts oldest entry when at capacity (100 entries)", () => {
+		const cache = createCacheManager(makeDir("eviction"));
+
+		// Insert 100 entries
+		for (let i = 0; i < 100; i++) {
+			cache.set(`key-${i}`, `value-${i}`);
+		}
+
+		// At this point L1 has 100 entries (full)
+		expect(cache.stats().entriesL1).toBe(100);
+
+		// Insert one more — should evict key-0 (oldest)
+		cache.set("key-new", "value-new");
+
+		expect(cache.stats().entriesL1).toBe(100);
+
+		// key-0 should no longer be in L1 but still in L2
+		// We verify by checking that stats show it was evicted from L1
+		// A direct L1-only check: create a spy scenario or just trust the
+		// stats count and that key-new is now present.
+		const newEntry = cache.get("key-new");
+		expect(newEntry).not.toBeNull();
+
+		// The total entriesL1 should stay bounded at 100
+		expect(cache.stats().entriesL1).toBe(100);
+	});
+});
+
+describe("invalidate", () => {
+	test("invalidate removes from both L1 and L2", () => {
+		const cache = createCacheManager(makeDir("invalidate"));
+		cache.set("del", "gone");
+		expect(cache.get("del")).not.toBeNull();
+
+		cache.invalidate("del");
+
+		// Create fresh manager to confirm L2 removal
+		const _cache2 = createCacheManager(makeDir("invalidate")); // same dir
+		// Actually use same mainaDir
+		const mainaDir = makeDir("invalidate2");
+		const c = createCacheManager(mainaDir);
+		c.set("del2", "gone2");
+		expect(c.get("del2")).not.toBeNull();
+		c.invalidate("del2");
+		expect(c.get("del2")).toBeNull();
+
+		// Verify L2 is also gone via a fresh manager
+		const c2 = createCacheManager(mainaDir);
+		expect(c2.get("del2")).toBeNull();
+		expect(c2.stats().l2Hits).toBe(0);
+		expect(c2.stats().misses).toBe(1);
+	});
+});
+
+describe("clear", () => {
+	test("clear removes all entries from both layers", () => {
+		const mainaDir = makeDir("clear");
+		const cache = createCacheManager(mainaDir);
+		cache.set("a", "1");
+		cache.set("b", "2");
+		cache.set("c", "3");
+		expect(cache.stats().entriesL1).toBe(3);
+
+		cache.clear();
+
+		expect(cache.get("a")).toBeNull();
+		expect(cache.get("b")).toBeNull();
+		expect(cache.get("c")).toBeNull();
+		expect(cache.stats().entriesL1).toBe(0);
+
+		// Verify L2 cleared via fresh manager
+		const cache2 = createCacheManager(mainaDir);
+		expect(cache2.get("a")).toBeNull();
+		expect(cache2.stats().misses).toBe(1);
+	});
+});
+
+describe("stats", () => {
+	test("stats tracks l1Hits, l2Hits, misses, totalQueries accurately", () => {
+		const mainaDir = makeDir("stats");
+
+		// Seed L2 via first manager
+		const seed = createCacheManager(mainaDir);
+		seed.set("x", "xval");
+
+		// Fresh manager: empty L1
+		const cache = createCacheManager(mainaDir);
+
+		// miss
+		cache.get("nonexistent");
+		let s = cache.stats();
+		expect(s.misses).toBe(1);
+		expect(s.totalQueries).toBe(1);
+		expect(s.l1Hits).toBe(0);
+		expect(s.l2Hits).toBe(0);
+
+		// L2 hit (promotes to L1)
+		cache.get("x");
+		s = cache.stats();
+		expect(s.l2Hits).toBe(1);
+		expect(s.l1Hits).toBe(0);
+		expect(s.misses).toBe(1);
+		expect(s.totalQueries).toBe(2);
+
+		// L1 hit
+		cache.get("x");
+		s = cache.stats();
+		expect(s.l1Hits).toBe(1);
+		expect(s.l2Hits).toBe(1);
+		expect(s.misses).toBe(1);
+		expect(s.totalQueries).toBe(3);
+	});
+
+	test("stats.entriesL2 reflects number of rows in SQLite", () => {
+		const mainaDir = makeDir("stats-l2");
+		const cache = createCacheManager(mainaDir);
+		cache.set("p", "1");
+		cache.set("q", "2");
+		const s = cache.stats();
+		expect(s.entriesL2).toBe(2);
+		expect(s.entriesL1).toBe(2);
+	});
+});
+
+describe("has", () => {
+	test("has returns true for existing non-expired key", () => {
+		const cache = createCacheManager(makeDir("has-true"));
+		cache.set("exists", "yes");
+		expect(cache.has("exists")).toBe(true);
+	});
+
+	test("has returns false for missing key", () => {
+		const cache = createCacheManager(makeDir("has-false"));
+		expect(cache.has("nope")).toBe(false);
+	});
+
+	test("has returns false for expired key", () => {
+		const mainaDir = makeDir("has-expired");
+		const _cache = createCacheManager(mainaDir);
+
+		// Insert an expired row directly into SQLite
+		const { initDatabase } = require("../../db/index");
+		const { join: pjoin } = require("node:path");
+		const dbResult = initDatabase(pjoin(mainaDir, "cache", "cache.db"));
+		if (!dbResult.ok) throw new Error("db failed");
+		const db = dbResult.value.db;
+		const oldMs = Date.now() - 10_000; // 10 seconds ago
+		db.prepare(
+			`INSERT OR REPLACE INTO cache_entries (id, key, value, created_at, ttl)
+			 VALUES (?, ?, ?, ?, ?)`,
+		).run("exp-id", "expkey", "expval", String(oldMs), 1);
+		db.close();
+
+		const cache2 = createCacheManager(mainaDir);
+		expect(cache2.has("expkey")).toBe(false);
+	});
+});

package/src/cache/__tests__/ttl.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "bun:test";
+import { getAllRules, getTtl, isExpired } from "../ttl";
+
+describe("getTtl", () => {
+	it("review TTL is 0 (forever)", () => {
+		expect(getTtl("review")).toBe(0);
+	});
+
+	it("tests TTL is 0 (forever)", () => {
+		expect(getTtl("tests")).toBe(0);
+	});
+
+	it("fix TTL is 0 (forever)", () => {
+		expect(getTtl("fix")).toBe(0);
+	});
+
+	it("commit TTL is 0 (forever)", () => {
+		expect(getTtl("commit")).toBe(0);
+	});
+
+	it("context TTL is 3600 (1 hour)", () => {
+		expect(getTtl("context")).toBe(3600);
+	});
+
+	it("explain TTL is 86400 (24 hours)", () => {
+		expect(getTtl("explain")).toBe(86400);
+	});
+
+	it("design TTL is 86400 (24 hours)", () => {
+		expect(getTtl("design")).toBe(86400);
+	});
+
+	it("plan TTL is 86400 (24 hours)", () => {
+		expect(getTtl("plan")).toBe(86400);
+	});
+});
+
+describe("isExpired", () => {
+	it("returns false when TTL is 0 (never expires)", () => {
+		// Even if createdAt is very old, TTL=0 means forever
+		expect(isExpired(0, 0)).toBe(false);
+	});
+
+	it("returns false when within TTL", () => {
+		const now = Date.now();
+		const createdAt = now - 1000; // 1 second ago
+		expect(isExpired(createdAt, 3600)).toBe(false); // TTL is 1 hour
+	});
+
+	it("returns true when past TTL", () => {
+		const now = Date.now();
+		const createdAt = now - 7200 * 1000; // 2 hours ago
+		expect(isExpired(createdAt, 3600)).toBe(true); // TTL is 1 hour
+	});
+
+	it("returns false exactly at TTL boundary", () => {
+		const now = Date.now();
+		const createdAt = now - 3600 * 1000; // exactly 1 hour ago
+		// Not strictly greater than, so at boundary it's not expired
+		// (Date.now() - createdAt) === ttl * 1000, not >
+		// This is a boundary condition — implementation uses >, so false
+		expect(isExpired(createdAt + 1, 3600)).toBe(false);
+	});
+});
+
+describe("getAllRules", () => {
+	it("returns all 8 task types", () => {
+		const rules = getAllRules();
+		expect(rules.length).toBe(8);
+	});
+
+	it("each rule has task, ttl, and description", () => {
+		const rules = getAllRules();
+		for (const rule of rules) {
+			expect(typeof rule.task).toBe("string");
+			expect(typeof rule.ttl).toBe("number");
+			expect(typeof rule.description).toBe("string");
+			expect(rule.description.length).toBeGreaterThan(0);
+		}
+	});
+
+	it("includes all expected task types", () => {
+		const rules = getAllRules();
+		const tasks = rules.map((r) => r.task);
+		expect(tasks).toContain("review");
+		expect(tasks).toContain("tests");
+		expect(tasks).toContain("fix");
+		expect(tasks).toContain("commit");
+		expect(tasks).toContain("context");
+		expect(tasks).toContain("explain");
+		expect(tasks).toContain("design");
+		expect(tasks).toContain("plan");
+	});
+});

package/src/cache/keys.ts

@@ -0,0 +1,44 @@
+export interface CacheKeyInput {
+	task: string;
+	files?: string[];
+	promptHash?: string;
+	model?: string;
+	extra?: string;
+}
+
+export function hashContent(content: string): string {
+	const hasher = new Bun.CryptoHasher("sha256");
+	hasher.update(content);
+	return hasher.digest("hex");
+}
+
+export async function hashFile(path: string): Promise<string> {
+	try {
+		const file = Bun.file(path);
+		const exists = await file.exists();
+		if (!exists) {
+			return "";
+		}
+		const content = await file.text();
+		return hashContent(content);
+	} catch {
+		return "";
+	}
+}
+
+export async function hashFiles(paths: string[]): Promise<string> {
+	if (paths.length === 0) {
+		return "";
+	}
+	const sorted = [...paths].sort();
+	const hashes = await Promise.all(sorted.map((p) => hashFile(p)));
+	const combined = hashes.join("");
+	return hashContent(combined);
+}
+
+export async function buildCacheKey(input: CacheKeyInput): Promise<string> {
+	const { task, files, promptHash = "", model = "", extra = "" } = input;
+	const filesHash = files && files.length > 0 ? await hashFiles(files) : "";
+	const combined = `${task}:${promptHash}:${model}:${filesHash}:${extra}`;
+	return hashContent(combined);
+}