@mainahq/core 0.2.0

package/src/context/engine.ts

@@ -0,0 +1,394 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getChangedFiles, getStagedFiles } from "../git/index";
+import {
+	assembleBudget,
+	type BudgetAllocation,
+	type BudgetMode,
+	calculateTokens,
+	type LayerContent,
+	truncateToFit,
+} from "./budget";
+import { assembleEpisodicText, decayAllEntries, getEntries } from "./episodic";
+import {
+	assembleRetrievalText,
+	type RetrievalOptions,
+	search,
+} from "./retrieval";
+import type { MainaCommand } from "./selector";
+import { getBudgetMode, getContextNeeds, needsLayer } from "./selector";
+import { assembleWorkingText, loadWorkingContext } from "./working";
+
+// ── Public types ──────────────────────────────────────────────────────────────
+
+export interface LayerReport {
+	name: string;
+	tokens: number;
+	entries: number;
+	included: boolean;
+}
+
+export interface AssembledContext {
+	text: string;
+	tokens: number;
+	layers: LayerReport[];
+	mode: BudgetMode;
+	budget: BudgetAllocation;
+}
+
+export interface ContextOptions {
+	repoRoot?: string; // defaults to process.cwd()
+	mainaDir?: string; // defaults to join(repoRoot, '.maina')
+	searchQuery?: string; // for retrieval layer
+	scope?: string; // limit to specific directory
+	modeOverride?: BudgetMode; // override the command-derived budget mode
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Escape regex metacharacters in a string so it can be safely used
+ * as a literal term inside a ripgrep/grep alternation pattern.
+ */
+function escapeRegex(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Try to read a file as text. Returns empty string on any failure.
+ */
+function tryReadFile(filePath: string): string {
+	try {
+		if (existsSync(filePath)) {
+			return readFileSync(filePath, "utf8");
+		}
+	} catch {
+		// intentionally swallowed
+	}
+	return "";
+}
+
+/**
+ * Minimal fallback for the semantic layer: constitution.md + conventions.md if present.
+ */
+function fallbackSemanticText(mainaDir: string): string {
+	const parts: string[] = [];
+
+	const constitutionPath = join(mainaDir, "constitution.md");
+	const constitutionText = tryReadFile(constitutionPath);
+	if (constitutionText) {
+		parts.push("## Constitution\n");
+		parts.push(constitutionText);
+	}
+
+	const conventionsPath = join(mainaDir, "conventions.md");
+	const conventionsText = tryReadFile(conventionsPath);
+	if (conventionsText) {
+		parts.push("## Conventions\n");
+		parts.push(conventionsText);
+	}
+
+	return parts.join("\n");
+}
+
+/**
+ * Attempt to load and assemble the semantic layer.
+ * Uses dynamic import so the engine works even if semantic.ts is not yet built.
+ */
+async function loadSemanticLayer(
+	repoRoot: string,
+	mainaDir: string,
+	filter?: string[],
+): Promise<string> {
+	try {
+		const {
+			buildSemanticContext,
+			assembleSemanticText,
+			persistSemanticContext,
+		} = await import("./semantic");
+
+		// Populate task context from git for PageRank personalization
+		const [staged, changed] = await Promise.all([
+			getStagedFiles(repoRoot),
+			getChangedFiles("HEAD~5", repoRoot),
+		]);
+		const touchedRelative = [...new Set([...staged, ...changed])];
+		// Graph uses absolute paths, so convert for personalization lookup
+		const touchedAbsolute = touchedRelative.map((f) => join(repoRoot, f));
+
+		const taskContext = {
+			touchedFiles: touchedAbsolute,
+			mentionedFiles: [],
+			currentTicketTerms: filter ?? [],
+		};
+
+		const semanticContext = await buildSemanticContext(
+			repoRoot,
+			mainaDir,
+			taskContext,
+		);
+
+		// Persist entities + dependency graph to DB for cross-session recall
+		persistSemanticContext(mainaDir, semanticContext, repoRoot);
+
+		return assembleSemanticText(semanticContext, filter);
+	} catch {
+		// semantic module not available or failed — use minimal fallback
+		return fallbackSemanticText(mainaDir);
+	}
+}
+
+/**
+ * Build the working layer content. Never throws.
+ */
+async function buildWorkingLayer(
+	mainaDir: string,
+	repoRoot: string,
+): Promise<LayerContent> {
+	try {
+		const context = await loadWorkingContext(mainaDir, repoRoot);
+
+		// Backfill touchedFiles from git if empty (so working layer is useful
+		// even without explicit trackFile() calls)
+		if (context.touchedFiles.length === 0) {
+			const [staged, changed] = await Promise.all([
+				getStagedFiles(repoRoot),
+				getChangedFiles("HEAD~3", repoRoot),
+			]);
+			context.touchedFiles = [...new Set([...staged, ...changed])];
+		}
+
+		const text = assembleWorkingText(context);
+		const tokens = calculateTokens(text);
+		return { name: "working", text, tokens, priority: 0 };
+	} catch {
+		const text = "Working context unavailable.";
+		return {
+			name: "working",
+			text,
+			tokens: calculateTokens(text),
+			priority: 0,
+		};
+	}
+}
+
+/**
+ * Build the episodic layer content. Never throws.
+ */
+function buildEpisodicLayer(mainaDir: string, filter?: string[]): LayerContent {
+	try {
+		decayAllEntries(mainaDir);
+
+		let entries: import("./episodic").EpisodicEntry[];
+		if (filter !== undefined && filter.length > 0) {
+			// When filter is a string[], fetch entries for each type and merge
+			const allEntries = filter.flatMap((type) => getEntries(mainaDir, type));
+			// Deduplicate by id
+			const seen = new Set<string>();
+			entries = allEntries.filter((e) => {
+				if (seen.has(e.id)) return false;
+				seen.add(e.id);
+				return true;
+			});
+		} else {
+			entries = getEntries(mainaDir);
+		}
+
+		const text = assembleEpisodicText(entries);
+		return {
+			name: "episodic",
+			text,
+			tokens: calculateTokens(text),
+			priority: 2,
+		};
+	} catch {
+		return { name: "episodic", text: "", tokens: 0, priority: 2 };
+	}
+}
+
+/**
+ * Build the semantic layer content. Never throws.
+ */
+async function buildSemanticLayer(
+	repoRoot: string,
+	mainaDir: string,
+	filter?: string[],
+): Promise<LayerContent> {
+	try {
+		const text = await loadSemanticLayer(repoRoot, mainaDir, filter);
+		return {
+			name: "semantic",
+			text,
+			tokens: calculateTokens(text),
+			priority: 1,
+		};
+	} catch {
+		return { name: "semantic", text: "", tokens: 0, priority: 1 };
+	}
+}
+
+/**
+ * Build the retrieval layer content. Never throws.
+ */
+async function buildRetrievalLayer(
+	query: string,
+	options: RetrievalOptions,
+): Promise<LayerContent> {
+	try {
+		const results = await search(query, options);
+		const text = assembleRetrievalText(results);
+		return {
+			name: "retrieval",
+			text,
+			tokens: calculateTokens(text),
+			priority: 3,
+		};
+	} catch {
+		return { name: "retrieval", text: "", tokens: 0, priority: 3 };
+	}
+}
+
+// ── Main entry point ──────────────────────────────────────────────────────────
+
+/**
+ * Assemble context for a Maina command.
+ *
+ * 1. Determines which layers are needed via the selector.
+ * 2. Builds a budget allocation for the command's mode.
+ * 3. Loads each needed layer in parallel (resilient — failures produce empty layers).
+ * 4. Runs truncateToFit to stay within token budget.
+ * 5. Returns the combined text plus reporting metadata.
+ */
+export async function assembleContext(
+	command: MainaCommand,
+	options: ContextOptions = {},
+): Promise<AssembledContext> {
+	const repoRoot = options.repoRoot ?? process.cwd();
+	const mainaDir = options.mainaDir ?? join(repoRoot, ".maina");
+
+	const needs = getContextNeeds(command);
+	const mode = options.modeOverride ?? getBudgetMode(command);
+	const budget = assembleBudget(mode);
+
+	// Determine which layers to build
+	const layerPromises: Promise<LayerContent>[] = [];
+
+	// Working layer
+	if (needsLayer(needs, "working")) {
+		layerPromises.push(buildWorkingLayer(mainaDir, repoRoot));
+	}
+
+	// Semantic layer — filter may be a string[]
+	if (needsLayer(needs, "semantic")) {
+		const semanticFilter = Array.isArray(needs.semantic)
+			? needs.semantic
+			: undefined;
+		layerPromises.push(buildSemanticLayer(repoRoot, mainaDir, semanticFilter));
+	}
+
+	// Episodic layer — filter may be a string[]
+	if (needsLayer(needs, "episodic")) {
+		const episodicFilter = Array.isArray(needs.episodic)
+			? needs.episodic
+			: undefined;
+		layerPromises.push(
+			Promise.resolve(buildEpisodicLayer(mainaDir, episodicFilter)),
+		);
+	}
+
+	// Retrieval layer — auto-generates search query from staged/changed files if not provided
+	if (needsLayer(needs, "retrieval")) {
+		let query = options.searchQuery;
+
+		// Auto-generate query from recent changes if none provided
+		if (!query) {
+			try {
+				const [staged, changed] = await Promise.all([
+					getStagedFiles(repoRoot),
+					getChangedFiles("HEAD~3", repoRoot),
+				]);
+				const recentFiles = [...new Set([...staged, ...changed])];
+				if (recentFiles.length > 0) {
+					// Extract meaningful terms, escape regex metacharacters in each,
+					// then join with | for ripgrep alternation
+					const terms = recentFiles
+						.flatMap(
+							(f) =>
+								f
+									.split("/")
+									.pop()
+									?.replace(/\.\w+$/, "")
+									.split(/[-_.]/) ?? [],
+						)
+						.filter((t) => t.length > 3)
+						.map(escapeRegex)
+						.slice(0, 5);
+					if (terms.length > 0) {
+						query = terms.join("|");
+					}
+				}
+			} catch {
+				// Failed to auto-generate — leave as empty
+			}
+		}
+
+		if (query) {
+			const retrievalOptions: RetrievalOptions = {
+				cwd: options.scope ?? repoRoot,
+				tokenBudget: budget.retrieval,
+			};
+			layerPromises.push(buildRetrievalLayer(query, retrievalOptions));
+		} else {
+			// No query possible — add empty placeholder so it appears in reports
+			layerPromises.push(
+				Promise.resolve({
+					name: "retrieval",
+					text: "",
+					tokens: 0,
+					priority: 3,
+				}),
+			);
+		}
+	}
+
+	// Build all layers in parallel
+	const builtLayers = await Promise.all(layerPromises);
+
+	// Filter out completely empty non-working layers before truncation
+	// (keep working even if empty so it's always reported)
+	const nonEmptyOrWorking = builtLayers.filter(
+		(l) => l.name === "working" || l.tokens > 0,
+	);
+
+	// Also keep retrieval in reports even if empty (for test expectations)
+	const includedInTruncation =
+		nonEmptyOrWorking.length > 0 ? nonEmptyOrWorking : builtLayers;
+
+	// Apply budget truncation
+	const surviving = truncateToFit(includedInTruncation, budget);
+	const survivingNames = new Set(surviving.map((l) => l.name));
+
+	// Build layer reports (all built layers, marked included/excluded)
+	const layerReports: LayerReport[] = builtLayers.map((layer) => ({
+		name: layer.name,
+		tokens: layer.tokens,
+		entries: layer.text.split("\n").filter((line) => line.trim()).length,
+		included: survivingNames.has(layer.name),
+	}));
+
+	// Combine surviving layer texts
+	const combinedParts = surviving
+		.filter((l) => l.text.length > 0)
+		.map((l) => l.text);
+
+	const text = combinedParts.join("\n\n");
+	const tokens = calculateTokens(text);
+
+	return {
+		text,
+		tokens,
+		layers: layerReports,
+		mode,
+		budget,
+	};
+}

package/src/context/episodic.ts

@@ -0,0 +1,251 @@
+import { getContextDb } from "../db/index.ts";
+
+export interface EpisodicEntry {
+	id: string;
+	content: string;
+	summary: string;
+	relevance: number;
+	accessCount: number;
+	createdAt: string; // ISO timestamp
+	lastAccessedAt: string; // ISO timestamp
+	type: string; // "review" | "session" | "commit" | "feedback"
+}
+
+// Raw row shape returned from SQLite
+interface EpisodicRow {
+	id: string;
+	content: string;
+	summary: string | null;
+	relevance: number | null;
+	access_count: number | null;
+	created_at: string;
+	last_accessed_at: string | null;
+	type: string;
+}
+
+function rowToEntry(row: EpisodicRow): EpisodicEntry {
+	return {
+		id: row.id,
+		content: row.content,
+		summary: row.summary ?? "",
+		relevance: row.relevance ?? 1.0,
+		accessCount: row.access_count ?? 0,
+		createdAt: row.created_at,
+		lastAccessedAt: row.last_accessed_at ?? row.created_at,
+		type: row.type,
+	};
+}
+
+/**
+ * Opens (or creates) the context database for the given mainaDir.
+ * Returns the raw bun:sqlite Database instance.
+ * Never throws — returns null on failure.
+ */
+function openDb(mainaDir: string) {
+	const result = getContextDb(mainaDir);
+	if (!result.ok) return null;
+	return result.value.db;
+}
+
+/**
+ * Implements the Ebbinghaus forgetting curve for relevance decay.
+ * Formula: exp(-0.1 * daysSinceAccess) + 0.1 * min(accessCount, 5)
+ * Clamped to [0, 1].
+ */
+export function calculateDecay(
+	daysSinceAccess: number,
+	accessCount: number,
+): number {
+	const raw = Math.exp(-0.1 * daysSinceAccess) + 0.1 * Math.min(accessCount, 5);
+	return Math.min(1, Math.max(0, raw));
+}
+
+/**
+ * Adds a new episodic entry to the database.
+ * Sets id (crypto.randomUUID), relevance=1.0, accessCount=0, timestamps=now.
+ */
+export function addEntry(
+	mainaDir: string,
+	entry: Omit<
+		EpisodicEntry,
+		"id" | "relevance" | "accessCount" | "createdAt" | "lastAccessedAt"
+	>,
+): EpisodicEntry {
+	const db = openDb(mainaDir);
+	const now = new Date().toISOString();
+	const id = crypto.randomUUID();
+
+	const newEntry: EpisodicEntry = {
+		id,
+		content: entry.content,
+		summary: entry.summary,
+		type: entry.type,
+		relevance: 1.0,
+		accessCount: 0,
+		createdAt: now,
+		lastAccessedAt: now,
+	};
+
+	if (db) {
+		db.prepare(
+			`INSERT INTO episodic_entries
+				(id, content, summary, relevance, access_count, created_at, last_accessed_at, type)
+			VALUES
+				(?, ?, ?, ?, ?, ?, ?, ?)`,
+		).run(
+			newEntry.id,
+			newEntry.content,
+			newEntry.summary,
+			newEntry.relevance,
+			newEntry.accessCount,
+			newEntry.createdAt,
+			newEntry.lastAccessedAt,
+			newEntry.type,
+		);
+	}
+
+	return newEntry;
+}
+
+/**
+ * Finds an entry by ID, increments accessCount, updates lastAccessedAt,
+ * recalculates relevance, saves, and returns the updated entry.
+ * Returns null if the entry is not found or db is unavailable.
+ */
+export function accessEntry(
+	mainaDir: string,
+	id: string,
+): EpisodicEntry | null {
+	const db = openDb(mainaDir);
+	if (!db) return null;
+
+	const row = db
+		.prepare("SELECT * FROM episodic_entries WHERE id = ?")
+		.get(id) as EpisodicRow | undefined;
+
+	if (!row) return null;
+
+	const entry = rowToEntry(row);
+	const now = new Date().toISOString();
+	const newAccessCount = entry.accessCount + 1;
+
+	// Recalculate relevance: days since last accessed = 0 (we're accessing now)
+	const newRelevance = calculateDecay(0, newAccessCount);
+
+	db.prepare(
+		`UPDATE episodic_entries
+		SET access_count = ?, last_accessed_at = ?, relevance = ?
+		WHERE id = ?`,
+	).run(newAccessCount, now, newRelevance, id);
+
+	return {
+		...entry,
+		accessCount: newAccessCount,
+		lastAccessedAt: now,
+		relevance: newRelevance,
+	};
+}
+
+/**
+ * Returns all entries (optionally filtered by type), sorted by relevance descending.
+ */
+export function getEntries(mainaDir: string, type?: string): EpisodicEntry[] {
+	const db = openDb(mainaDir);
+	if (!db) return [];
+
+	let rows: EpisodicRow[];
+	if (type !== undefined) {
+		rows = db
+			.prepare(
+				"SELECT * FROM episodic_entries WHERE type = ? ORDER BY relevance DESC",
+			)
+			.all(type) as EpisodicRow[];
+	} else {
+		rows = db
+			.prepare("SELECT * FROM episodic_entries ORDER BY relevance DESC")
+			.all() as EpisodicRow[];
+	}
+
+	return rows.map(rowToEntry);
+}
+
+/**
+ * Removes entries with relevance < 0.1, then enforces a max of 100 entries
+ * by removing the lowest-relevance entries above that count.
+ * Returns the total count of pruned entries.
+ */
+export function pruneEntries(mainaDir: string): number {
+	const db = openDb(mainaDir);
+	if (!db) return 0;
+
+	// Remove entries below relevance threshold
+	const lowRelevance = db
+		.prepare("DELETE FROM episodic_entries WHERE relevance < 0.1")
+		.run();
+	let pruned = lowRelevance.changes;
+
+	// Count remaining entries
+	const countRow = db
+		.prepare("SELECT COUNT(*) as count FROM episodic_entries")
+		.get() as { count: number };
+	const total = countRow.count;
+
+	if (total > 100) {
+		const excess = total - 100;
+		// Delete the lowest-relevance entries beyond the top 100
+		const overLimit = db
+			.prepare(
+				`DELETE FROM episodic_entries WHERE id IN (
+					SELECT id FROM episodic_entries ORDER BY relevance ASC LIMIT ?
+				)`,
+			)
+			.run(excess);
+		pruned += overLimit.changes;
+	}
+
+	return pruned;
+}
+
+/**
+ * Recalculates relevance for all entries based on current time.
+ */
+export function decayAllEntries(mainaDir: string): void {
+	const db = openDb(mainaDir);
+	if (!db) return;
+
+	const rows = db
+		.prepare("SELECT * FROM episodic_entries")
+		.all() as EpisodicRow[];
+	const now = Date.now();
+
+	const update = db.prepare(
+		"UPDATE episodic_entries SET relevance = ? WHERE id = ?",
+	);
+
+	for (const row of rows) {
+		const entry = rowToEntry(row);
+		const lastAccessed = new Date(entry.lastAccessedAt).getTime();
+		const daysSinceAccess = (now - lastAccessed) / (1000 * 60 * 60 * 24);
+		const newRelevance = calculateDecay(daysSinceAccess, entry.accessCount);
+		update.run(newRelevance, entry.id);
+	}
+}
+
+/**
+ * Formats a list of episodic entries as text for LLM consumption.
+ */
+export function assembleEpisodicText(entries: EpisodicEntry[]): string {
+	if (entries.length === 0) return "";
+
+	const lines: string[] = ["## Episodic Context\n"];
+
+	for (const entry of entries) {
+		lines.push(
+			`### [${entry.type}] ${entry.summary} (relevance: ${entry.relevance.toFixed(2)})`,
+		);
+		lines.push(entry.content);
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}