@mainahq/core 0.2.0

package/src/context/working.ts

@@ -0,0 +1,192 @@
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getCurrentBranch } from "../git/index";
+import { loadWorkflowContext } from "../workflow/context";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface VerificationResult {
+	passed: boolean;
+	checks: { name: string; passed: boolean; output?: string }[];
+	timestamp: string;
+}
+
+export interface WorkingContext {
+	branch: string;
+	planContent: string | null;
+	workflowContext: string | null;
+	touchedFiles: string[];
+	lastVerification: VerificationResult | null;
+	updatedAt: string;
+}
+
+// ── Internal helpers ─────────────────────────────────────────────────────────
+
+function contextFilePath(mainaDir: string): string {
+	return join(mainaDir, "context", "working.json");
+}
+
+function freshContext(branch: string): WorkingContext {
+	return {
+		branch,
+		planContent: null,
+		workflowContext: null,
+		touchedFiles: [],
+		lastVerification: null,
+		updatedAt: new Date().toISOString(),
+	};
+}
+
+async function readPlanContent(repoRoot: string): Promise<string | null> {
+	try {
+		const planPath = join(repoRoot, "PLAN.md");
+		const file = Bun.file(planPath);
+		if (await file.exists()) {
+			return await file.text();
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Load the working context from disk.
+ *
+ * - If no file exists, returns a fresh context for the current branch.
+ * - If the saved branch differs from the current git branch, resets to a fresh
+ *   context (branch switch detected).
+ * - Always refreshes planContent from PLAN.md on load.
+ */
+export async function loadWorkingContext(
+	mainaDir: string,
+	repoRoot: string,
+): Promise<WorkingContext> {
+	const currentBranch = await getCurrentBranch(repoRoot);
+
+	const planContent = await readPlanContent(repoRoot);
+	const workflowContext = loadWorkflowContext(mainaDir);
+
+	try {
+		const filePath = contextFilePath(mainaDir);
+		const file = Bun.file(filePath);
+		if (!(await file.exists())) {
+			return { ...freshContext(currentBranch), planContent, workflowContext };
+		}
+
+		const raw = await file.text();
+		const saved: WorkingContext = JSON.parse(raw);
+
+		// Branch switch — discard stale session state
+		if (saved.branch !== currentBranch) {
+			return { ...freshContext(currentBranch), planContent, workflowContext };
+		}
+
+		// Refresh plan content and workflow context from disk
+		return { ...saved, planContent, workflowContext };
+	} catch {
+		return { ...freshContext(currentBranch), planContent, workflowContext };
+	}
+}
+
+/**
+ * Persist the working context to `.maina/context/working.json`.
+ * Creates parent directories as needed. Never throws.
+ */
+export async function saveWorkingContext(
+	mainaDir: string,
+	context: WorkingContext,
+): Promise<void> {
+	try {
+		const filePath = contextFilePath(mainaDir);
+		mkdirSync(dirname(filePath), { recursive: true });
+		// planContent is runtime-only — no need to persist it (we re-read on load)
+		// but we DO persist it so round-trip tests work without git side-effects
+		const payload = { ...context, updatedAt: new Date().toISOString() };
+		await Bun.write(filePath, JSON.stringify(payload, null, 2));
+	} catch {
+		// Intentionally swallowed — never throw
+	}
+}
+
+/**
+ * Add a file path to the touchedFiles list (deduplicating) and save.
+ */
+export async function trackFile(
+	mainaDir: string,
+	repoRoot: string,
+	filePath: string,
+): Promise<WorkingContext> {
+	const ctx = await loadWorkingContext(mainaDir, repoRoot);
+	if (!ctx.touchedFiles.includes(filePath)) {
+		ctx.touchedFiles = [...ctx.touchedFiles, filePath];
+	}
+	ctx.updatedAt = new Date().toISOString();
+	await saveWorkingContext(mainaDir, ctx);
+	return ctx;
+}
+
+/**
+ * Record the latest verification run result and save.
+ */
+export async function setVerificationResult(
+	mainaDir: string,
+	repoRoot: string,
+	result: VerificationResult,
+): Promise<WorkingContext> {
+	const ctx = await loadWorkingContext(mainaDir, repoRoot);
+	ctx.lastVerification = result;
+	ctx.updatedAt = new Date().toISOString();
+	await saveWorkingContext(mainaDir, ctx);
+	return ctx;
+}
+
+/**
+ * Return a brand-new empty WorkingContext without touching disk.
+ * The branch field is set to an empty string — caller should fill it in.
+ */
+export function resetWorkingContext(mainaDir: string): WorkingContext {
+	// mainaDir accepted for API symmetry / future use
+	void mainaDir;
+	return freshContext("");
+}
+
+/**
+ * Format the working context as a human/LLM-readable string.
+ */
+export function assembleWorkingText(context: WorkingContext): string {
+	const lines: string[] = [];
+
+	lines.push(`Current branch: ${context.branch}`);
+	lines.push(`Touched files: ${context.touchedFiles.length}`);
+
+	if (context.touchedFiles.length > 0) {
+		lines.push("Files modified this session:");
+		for (const f of context.touchedFiles) {
+			lines.push(`  - ${f}`);
+		}
+	}
+
+	if (context.lastVerification !== null) {
+		const v = context.lastVerification;
+		const status = v.passed ? "passed" : "failed";
+		lines.push(`Last verification: ${status} (${v.timestamp})`);
+		for (const check of v.checks) {
+			const checkStatus = check.passed ? "pass" : "fail";
+			const detail = check.output ? ` — ${check.output}` : "";
+			lines.push(`  [${checkStatus}] ${check.name}${detail}`);
+		}
+	}
+
+	if (context.planContent !== null) {
+		lines.push("");
+		lines.push("PLAN.md:");
+		lines.push(context.planContent);
+	}
+
+	lines.push(`Updated at: ${context.updatedAt}`);
+
+	return lines.join("\n");
+}

package/src/db/__tests__/db.test.ts

@@ -0,0 +1,151 @@
+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 {
+	getCacheDb,
+	getContextDb,
+	getFeedbackDb,
+	initDatabase,
+} from "../index.ts";
+
+const TEST_DIR = join(tmpdir(), `maina-test-${Date.now()}`);
+
+beforeAll(() => {
+	mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterAll(() => {
+	rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe("initDatabase", () => {
+	test("creates a database file on first access", () => {
+		const dbPath = join(TEST_DIR, "test.db");
+		const result = initDatabase(dbPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		const { db } = result.value;
+		expect(db).toBeDefined();
+		db.close();
+	});
+
+	test("all expected tables exist after init (context db)", () => {
+		const mainaDir = join(TEST_DIR, "tables-test");
+		const result = getContextDb(mainaDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		const { db } = result.value;
+
+		const rows = db
+			.prepare(
+				"SELECT name FROM sqlite_master WHERE type='table' ORDER BY name",
+			)
+			.all() as Array<{ name: string }>;
+		const tableNames = rows.map((r) => r.name);
+
+		expect(tableNames).toContain("episodic_entries");
+		expect(tableNames).toContain("semantic_entities");
+		expect(tableNames).toContain("dependency_edges");
+		db.close();
+	});
+
+	test("all expected tables exist after init (cache db)", () => {
+		const mainaDir = join(TEST_DIR, "cache-tables-test");
+		const result = getCacheDb(mainaDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		const { db } = result.value;
+
+		const rows = db
+			.prepare(
+				"SELECT name FROM sqlite_master WHERE type='table' ORDER BY name",
+			)
+			.all() as Array<{ name: string }>;
+		const tableNames = rows.map((r) => r.name);
+
+		expect(tableNames).toContain("cache_entries");
+		db.close();
+	});
+
+	test("all expected tables exist after init (feedback db)", () => {
+		const mainaDir = join(TEST_DIR, "feedback-tables-test");
+		const result = getFeedbackDb(mainaDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		const { db } = result.value;
+
+		const rows = db
+			.prepare(
+				"SELECT name FROM sqlite_master WHERE type='table' ORDER BY name",
+			)
+			.all() as Array<{ name: string }>;
+		const tableNames = rows.map((r) => r.name);
+
+		expect(tableNames).toContain("feedback");
+		expect(tableNames).toContain("prompt_versions");
+		db.close();
+	});
+});
+
+describe("episodic_entries CRUD", () => {
+	test("can insert and query episodic_entries", async () => {
+		const mainaDir = join(TEST_DIR, "episodic-crud");
+		const result = getContextDb(mainaDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		const { drizzle: orm, db } = result.value;
+
+		const { episodicEntries } = await import("../schema.ts");
+
+		const id = "test-entry-1";
+		await orm.insert(episodicEntries).values({
+			id,
+			content: "User added auth module",
+			summary: "Auth",
+			relevance: 0.9,
+			accessCount: 1,
+			createdAt: new Date().toISOString(),
+			lastAccessedAt: new Date().toISOString(),
+			type: "observation",
+		});
+
+		const rows = await orm.select().from(episodicEntries);
+		expect(rows.length).toBe(1);
+		expect(rows[0]?.id).toBe(id);
+		expect(rows[0]?.content).toBe("User added auth module");
+		expect(rows[0]?.relevance).toBeCloseTo(0.9);
+		db.close();
+	});
+});
+
+describe("cache_entries CRUD", () => {
+	test("can insert and query cache_entries", async () => {
+		const mainaDir = join(TEST_DIR, "cache-crud");
+		const result = getCacheDb(mainaDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		const { drizzle: orm, db } = result.value;
+
+		const { cacheEntries } = await import("../schema.ts");
+
+		const id = "cache-entry-1";
+		await orm.insert(cacheEntries).values({
+			id,
+			key: "prompt-hash-abc123",
+			value: '{"tokens": 500}',
+			promptVersion: "v1.0",
+			contextHash: "ctx-hash-xyz",
+			model: "claude-3-5-sonnet",
+			createdAt: new Date().toISOString(),
+			ttl: 3600,
+		});
+
+		const rows = await orm.select().from(cacheEntries);
+		expect(rows.length).toBe(1);
+		expect(rows[0]?.id).toBe(id);
+		expect(rows[0]?.key).toBe("prompt-hash-abc123");
+		expect(rows[0]?.ttl).toBe(3600);
+		db.close();
+	});
+});

package/src/db/index.ts

@@ -0,0 +1,211 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import * as schema from "./schema.ts";
+
+export type DbHandle = {
+	db: Database;
+	drizzle: ReturnType<typeof drizzle<typeof schema>>;
+};
+
+export type Result<T, E = string> =
+	| { ok: true; value: T }
+	| { ok: false; error: E };
+
+function ok<T>(value: T): Result<T, never> {
+	return { ok: true, value };
+}
+
+function err<E>(error: E): Result<never, E> {
+	return { ok: false, error };
+}
+
+/**
+ * Create context tables: episodic_entries, semantic_entities, dependency_edges.
+ */
+function createContextTables(db: Database): void {
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS episodic_entries (
+			id TEXT PRIMARY KEY,
+			content TEXT NOT NULL,
+			summary TEXT,
+			relevance REAL,
+			access_count INTEGER,
+			created_at TEXT NOT NULL,
+			last_accessed_at TEXT,
+			type TEXT NOT NULL
+		);
+
+		CREATE TABLE IF NOT EXISTS semantic_entities (
+			id TEXT PRIMARY KEY,
+			file_path TEXT NOT NULL,
+			name TEXT NOT NULL,
+			kind TEXT NOT NULL,
+			start_line INTEGER NOT NULL,
+			end_line INTEGER NOT NULL,
+			updated_at TEXT NOT NULL
+		);
+
+		CREATE TABLE IF NOT EXISTS dependency_edges (
+			id TEXT PRIMARY KEY,
+			source_file TEXT NOT NULL,
+			target_file TEXT NOT NULL,
+			weight REAL,
+			type TEXT NOT NULL
+		);
+	`);
+}
+
+/**
+ * Create cache tables: cache_entries.
+ */
+function createCacheTables(db: Database): void {
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS cache_entries (
+			id TEXT PRIMARY KEY,
+			key TEXT NOT NULL UNIQUE,
+			value TEXT NOT NULL,
+			prompt_version TEXT,
+			context_hash TEXT,
+			model TEXT,
+			created_at TEXT NOT NULL,
+			ttl INTEGER
+		);
+	`);
+}
+
+/**
+ * Create feedback tables: feedback, prompt_versions.
+ */
+function createFeedbackTables(db: Database): void {
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS feedback (
+			id TEXT PRIMARY KEY,
+			prompt_hash TEXT NOT NULL,
+			command TEXT NOT NULL,
+			accepted INTEGER NOT NULL,
+			context TEXT,
+			created_at TEXT NOT NULL
+		);
+
+		CREATE TABLE IF NOT EXISTS prompt_versions (
+			id TEXT PRIMARY KEY,
+			task TEXT NOT NULL,
+			hash TEXT NOT NULL,
+			content TEXT NOT NULL,
+			version INTEGER NOT NULL,
+			accept_rate REAL,
+			usage_count INTEGER,
+			created_at TEXT NOT NULL
+		);
+	`);
+
+	// Add workflow columns (nullable — backward compatible)
+	try {
+		db.exec(`ALTER TABLE feedback ADD COLUMN workflow_step TEXT`);
+	} catch {
+		// Column already exists — safe to ignore
+	}
+	try {
+		db.exec(`ALTER TABLE feedback ADD COLUMN workflow_id TEXT`);
+	} catch {
+		// Column already exists — safe to ignore
+	}
+}
+
+/**
+ * Create stats tables: commit_snapshots.
+ */
+function createStatsTables(db: Database): void {
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS commit_snapshots (
+			id TEXT PRIMARY KEY,
+			timestamp TEXT NOT NULL,
+			branch TEXT NOT NULL,
+			commit_hash TEXT NOT NULL,
+			verify_duration_ms INTEGER NOT NULL,
+			total_duration_ms INTEGER NOT NULL,
+			context_tokens INTEGER NOT NULL,
+			context_budget INTEGER NOT NULL,
+			context_utilization REAL NOT NULL,
+			cache_hits INTEGER NOT NULL,
+			cache_misses INTEGER NOT NULL,
+			findings_total INTEGER NOT NULL,
+			findings_errors INTEGER NOT NULL,
+			findings_warnings INTEGER NOT NULL,
+			tools_run INTEGER NOT NULL,
+			syntax_passed INTEGER NOT NULL,
+			pipeline_passed INTEGER NOT NULL,
+			skipped INTEGER NOT NULL DEFAULT 0
+		);
+	`);
+
+	// Migration: add skipped column to existing tables
+	try {
+		db.exec(
+			"ALTER TABLE commit_snapshots ADD COLUMN skipped INTEGER NOT NULL DEFAULT 0",
+		);
+	} catch {
+		// Column already exists — safe to ignore
+	}
+}
+
+/**
+ * Initialise a SQLite database at the given path, creating parent directories as needed.
+ * Accepts an optional table creator function; if omitted no tables are created.
+ * Returns a Result containing the raw Database and the Drizzle ORM instance.
+ * Never throws — all errors are returned as Err values.
+ */
+export function initDatabase(
+	dbPath: string,
+	tableCreator?: (db: Database) => void,
+): Result<DbHandle> {
+	try {
+		mkdirSync(dirname(dbPath), { recursive: true });
+		const db = new Database(dbPath, { create: true });
+		db.exec("PRAGMA journal_mode=WAL;");
+		if (tableCreator) {
+			tableCreator(db);
+		}
+		const orm = drizzle(db, { schema });
+		return ok({ db, drizzle: orm });
+	} catch (e) {
+		return err(e instanceof Error ? e.message : String(e));
+	}
+}
+
+/**
+ * Open the context database (.maina/context/index.db).
+ * Contains: episodic_entries, semantic_entities, dependency_edges.
+ */
+export function getContextDb(mainaDir: string): Result<DbHandle> {
+	return initDatabase(
+		join(mainaDir, "context", "index.db"),
+		createContextTables,
+	);
+}
+
+/**
+ * Open the cache database (.maina/cache/cache.db).
+ * Contains: cache_entries.
+ */
+export function getCacheDb(mainaDir: string): Result<DbHandle> {
+	return initDatabase(join(mainaDir, "cache", "cache.db"), createCacheTables);
+}
+
+/**
+ * Open the feedback database (.maina/feedback.db).
+ * Contains: feedback, prompt_versions.
+ */
+export function getFeedbackDb(mainaDir: string): Result<DbHandle> {
+	return initDatabase(join(mainaDir, "feedback.db"), createFeedbackTables);
+}
+
+/**
+ * Open the stats database (.maina/stats.db).
+ * Contains: commit_snapshots.
+ */
+export function getStatsDb(mainaDir: string): Result<DbHandle> {
+	return initDatabase(join(mainaDir, "stats.db"), createStatsTables);
+}

package/src/db/schema.ts

@@ -0,0 +1,84 @@
+import { integer, real, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const episodicEntries = sqliteTable("episodic_entries", {
+	id: text("id").primaryKey(),
+	content: text("content").notNull(),
+	summary: text("summary"),
+	relevance: real("relevance"),
+	accessCount: integer("access_count"),
+	createdAt: text("created_at").notNull(),
+	lastAccessedAt: text("last_accessed_at"),
+	type: text("type").notNull(),
+});
+
+export const semanticEntities = sqliteTable("semantic_entities", {
+	id: text("id").primaryKey(),
+	filePath: text("file_path").notNull(),
+	name: text("name").notNull(),
+	kind: text("kind", {
+		enum: ["function", "class", "interface", "type", "variable"],
+	}).notNull(),
+	startLine: integer("start_line").notNull(),
+	endLine: integer("end_line").notNull(),
+	updatedAt: text("updated_at").notNull(),
+});
+
+export const dependencyEdges = sqliteTable("dependency_edges", {
+	id: text("id").primaryKey(),
+	sourceFile: text("source_file").notNull(),
+	targetFile: text("target_file").notNull(),
+	weight: real("weight"),
+	type: text("type", { enum: ["import", "reference"] }).notNull(),
+});
+
+export const cacheEntries = sqliteTable("cache_entries", {
+	id: text("id").primaryKey(),
+	key: text("key").notNull().unique(),
+	value: text("value").notNull(),
+	promptVersion: text("prompt_version"),
+	contextHash: text("context_hash"),
+	model: text("model"),
+	createdAt: text("created_at").notNull(),
+	ttl: integer("ttl"),
+});
+
+export const feedback = sqliteTable("feedback", {
+	id: text("id").primaryKey(),
+	promptHash: text("prompt_hash").notNull(),
+	command: text("command").notNull(),
+	accepted: integer("accepted", { mode: "boolean" }).notNull(),
+	context: text("context"),
+	createdAt: text("created_at").notNull(),
+});
+
+export const commitSnapshots = sqliteTable("commit_snapshots", {
+	id: text("id").primaryKey(),
+	timestamp: text("timestamp").notNull(),
+	branch: text("branch").notNull(),
+	commitHash: text("commit_hash").notNull(),
+	verifyDurationMs: integer("verify_duration_ms").notNull(),
+	totalDurationMs: integer("total_duration_ms").notNull(),
+	contextTokens: integer("context_tokens").notNull(),
+	contextBudget: integer("context_budget").notNull(),
+	contextUtilization: real("context_utilization").notNull(),
+	cacheHits: integer("cache_hits").notNull(),
+	cacheMisses: integer("cache_misses").notNull(),
+	findingsTotal: integer("findings_total").notNull(),
+	findingsErrors: integer("findings_errors").notNull(),
+	findingsWarnings: integer("findings_warnings").notNull(),
+	toolsRun: integer("tools_run").notNull(),
+	syntaxPassed: integer("syntax_passed", { mode: "boolean" }).notNull(),
+	pipelinePassed: integer("pipeline_passed", { mode: "boolean" }).notNull(),
+	skipped: integer("skipped", { mode: "boolean" }).notNull().default(false),
+});
+
+export const promptVersions = sqliteTable("prompt_versions", {
+	id: text("id").primaryKey(),
+	task: text("task").notNull(),
+	hash: text("hash").notNull(),
+	content: text("content").notNull(),
+	version: integer("version").notNull(),
+	acceptRate: real("accept_rate"),
+	usageCount: integer("usage_count"),
+	createdAt: text("created_at").notNull(),
+});