@mainahq/core 1.0.2 → 1.1.0

package/src/context/wiki.ts

@@ -0,0 +1,296 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { recordArticlesLoaded } from "../wiki/signals";
+import { calculateTokens, type LayerContent } from "./budget";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface WikiContextOptions {
+	wikiDir: string;
+	workingFiles?: string[]; // from L1 — find their wiki articles
+	command?: string; // current command — determines which articles to load
+}
+
+interface WikiArticle {
+	path: string; // relative path within wiki dir (e.g. "decisions/adr-001.md")
+	title: string;
+	content: string;
+	category: string; // "decision" | "module" | "feature" | "architecture" | "index" | "other"
+	score: number;
+}
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+/** Categories of wiki articles mapped to directory names. */
+const CATEGORY_DIRS: Record<string, string> = {
+	decisions: "decision",
+	modules: "module",
+	features: "feature",
+	architecture: "architecture",
+};
+
+/**
+ * Commands that trigger specific article categories.
+ * Missing commands get the default behavior (index + top articles).
+ */
+const COMMAND_CATEGORIES: Record<string, string[]> = {
+	review: ["decision", "module"],
+	verify: ["decision", "module"],
+	explain: ["decision", "module", "feature", "architecture"],
+	context: ["decision", "module", "feature", "architecture"],
+	commit: ["feature", "architecture"],
+	plan: ["feature", "architecture"],
+	design: ["decision"],
+	analyze: ["decision", "module", "feature", "architecture"],
+	pr: ["decision", "module", "feature"],
+};
+
+// ── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Extracts a title from Markdown content.
+ * Uses the first `# ` heading, or falls back to the filename.
+ */
+function extractTitle(content: string, filename: string): string {
+	const firstLine = content.split("\n").find((line) => line.startsWith("# "));
+	if (firstLine) {
+		return firstLine.replace(/^#\s+/, "").trim();
+	}
+	return basename(filename, ".md");
+}
+
+/**
+ * Simple Ebbinghaus-style score based on file modification time.
+ * More recently modified files get higher scores.
+ * Formula: exp(-0.05 * daysSinceModified) clamped to [0.1, 1.0].
+ */
+function fileRecencyScore(filePath: string): number {
+	try {
+		const stat = statSync(filePath);
+		const daysSinceModified =
+			(Date.now() - stat.mtimeMs) / (1000 * 60 * 60 * 24);
+		const raw = Math.exp(-0.05 * daysSinceModified);
+		return Math.min(1, Math.max(0.1, raw));
+	} catch {
+		return 0.5; // fallback if stat fails
+	}
+}
+
+/**
+ * Determines the category of a wiki article from its directory path.
+ */
+function categorizeArticle(relPath: string): string {
+	const firstDir = relPath.split("/")[0] ?? "";
+	return CATEGORY_DIRS[firstDir] ?? "other";
+}
+
+/**
+ * Recursively collects all .md files from a directory.
+ * Excludes index.md (loaded separately).
+ */
+function collectArticles(dir: string, baseDir: string): string[] {
+	const results: string[] = [];
+
+	let entries: string[];
+	try {
+		entries = readdirSync(dir) as unknown as string[];
+	} catch {
+		return results;
+	}
+
+	for (const entry of entries) {
+		const fullPath = join(dir, entry);
+		let stat: ReturnType<typeof statSync> | undefined;
+		try {
+			stat = statSync(fullPath);
+		} catch {
+			continue;
+		}
+
+		if (stat.isDirectory()) {
+			results.push(...collectArticles(fullPath, baseDir));
+		} else if (stat.isFile() && entry.endsWith(".md")) {
+			const rel = relative(baseDir, fullPath);
+			// Skip top-level index.md (loaded separately)
+			if (rel !== "index.md") {
+				results.push(fullPath);
+			}
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Reads a file safely. Returns empty string on failure.
+ */
+function tryReadFileSync(filePath: string): string {
+	try {
+		if (!existsSync(filePath)) return "";
+		return readFileSync(filePath, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Checks if a wiki article is relevant to the given working files.
+ * Matches module articles whose name appears in working file paths.
+ */
+function isRelevantToWorkingFiles(
+	articleRelPath: string,
+	workingFiles: string[],
+): boolean {
+	if (workingFiles.length === 0) return false;
+
+	// Extract the article's base name (e.g., "context-engine" from "modules/context-engine.md")
+	const articleName = basename(articleRelPath, ".md").toLowerCase();
+
+	return workingFiles.some((f) => {
+		const lower = f.toLowerCase();
+		// Check if any working file path contains the article name
+		return (
+			lower.includes(articleName) ||
+			articleName.includes(basename(lower).replace(/\.\w+$/, ""))
+		);
+	});
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Load wiki context from `.maina/wiki/`.
+ *
+ * 1. Checks if wiki dir exists with articles. Returns null if not initialized.
+ * 2. Always loads index.md (overview of what's available).
+ * 3. Loads relevant articles based on command context.
+ * 4. Scores articles by recency (Ebbinghaus-style) + working file relevance.
+ * 5. Returns a formatted LayerContent.
+ */
+export function loadWikiContext(
+	options: WikiContextOptions,
+): LayerContent | null {
+	const { wikiDir, workingFiles, command } = options;
+
+	// Check if wiki directory exists
+	if (!existsSync(wikiDir)) {
+		return null;
+	}
+
+	// Check if there are any files at all
+	let dirEntries: string[];
+	try {
+		dirEntries = readdirSync(wikiDir) as unknown as string[];
+	} catch {
+		return null;
+	}
+
+	if (dirEntries.length === 0) {
+		return null;
+	}
+
+	// Load index.md if it exists
+	const indexPath = join(wikiDir, "index.md");
+	const indexContent = tryReadFileSync(indexPath);
+
+	// Collect all articles
+	const articlePaths = collectArticles(wikiDir, wikiDir);
+
+	// No articles and no index — wiki is empty
+	if (articlePaths.length === 0 && indexContent.length === 0) {
+		return null;
+	}
+
+	// Build article objects with scores
+	const articles: WikiArticle[] = [];
+	for (const fullPath of articlePaths) {
+		const relPath = relative(wikiDir, fullPath);
+		const content = tryReadFileSync(fullPath);
+		if (content.length === 0) continue;
+
+		const category = categorizeArticle(relPath);
+		const recency = fileRecencyScore(fullPath);
+
+		// Boost score if article is relevant to working files
+		const workingBoost =
+			workingFiles !== undefined &&
+			isRelevantToWorkingFiles(relPath, workingFiles)
+				? 0.3
+				: 0;
+
+		const score = Math.min(1, recency + workingBoost);
+
+		articles.push({
+			path: relPath,
+			title: extractTitle(content, relPath),
+			content,
+			category,
+			score,
+		});
+	}
+
+	// Filter by command-relevant categories
+	const relevantCategories = command ? (COMMAND_CATEGORIES[command] ?? []) : [];
+
+	let filteredArticles: WikiArticle[];
+	if (relevantCategories.length > 0) {
+		filteredArticles = articles.filter(
+			(a) => relevantCategories.includes(a.category) || a.category === "other",
+		);
+	} else {
+		// Default: all articles
+		filteredArticles = articles;
+	}
+
+	// Sort by score descending
+	filteredArticles.sort((a, b) => b.score - a.score);
+
+	// Assemble text
+	const text = assembleWikiText(indexContent, filteredArticles);
+	const tokens = calculateTokens(text);
+
+	// Record which articles were loaded for RL tracking (non-blocking)
+	if (filteredArticles.length > 0) {
+		const signalsPath = join(wikiDir, ".signals.json");
+		const loadedArticlePaths = filteredArticles.map((a) => a.path);
+		recordArticlesLoaded(signalsPath, loadedArticlePaths, command ?? "unknown");
+	}
+
+	return {
+		name: "wiki",
+		text,
+		tokens,
+		priority: 4,
+	};
+}
+
+/**
+ * Formats wiki content into an LLM-readable text block.
+ */
+export function assembleWikiText(
+	indexContent: string,
+	articles: WikiArticle[],
+): string {
+	const parts: string[] = [];
+
+	parts.push("## Wiki Knowledge (Layer 5)");
+	parts.push("");
+
+	if (indexContent.length > 0) {
+		parts.push("### Index");
+		parts.push(indexContent);
+		parts.push("");
+	}
+
+	if (articles.length > 0) {
+		parts.push("### Relevant Articles");
+
+		for (const article of articles) {
+			parts.push(`#### ${article.title} (wiki/${article.path})`);
+			parts.push(article.content);
+			parts.push("---");
+		}
+	}
+
+	return parts.join("\n");
+}

package/src/db/index.ts

@@ -149,6 +149,18 @@ function createStatsTables(db: Database): void {
 	} catch {
 		// Column already exists — safe to ignore
 	}
+
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS tool_usage (
+			id TEXT PRIMARY KEY,
+			tool TEXT NOT NULL,
+			input_hash TEXT NOT NULL,
+			duration_ms INTEGER NOT NULL,
+			cache_hit INTEGER NOT NULL DEFAULT 0,
+			timestamp TEXT NOT NULL,
+			workflow_id TEXT
+		);
+	`);
 }
 
 /**

package/src/feedback/__tests__/capture.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { createCacheManager } from "../../cache/manager";
+import { buildToolCacheKey, captureResult, getCachedResult } from "../capture";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		import.meta.dir,
+		`tmp-capture-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+	try {
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		/* ignore */
+	}
+});
+
+describe("buildToolCacheKey", () => {
+	test("returns consistent hash for same inputs", () => {
+		const key1 = buildToolCacheKey("reviewCode", { diff: "hello" });
+		const key2 = buildToolCacheKey("reviewCode", { diff: "hello" });
+		expect(key1).toBe(key2);
+	});
+
+	test("returns different hash for different tool names", () => {
+		const key1 = buildToolCacheKey("reviewCode", { diff: "hello" });
+		const key2 = buildToolCacheKey("verify", { diff: "hello" });
+		expect(key1).not.toBe(key2);
+	});
+
+	test("returns different hash for different inputs", () => {
+		const key1 = buildToolCacheKey("reviewCode", { diff: "hello" });
+		const key2 = buildToolCacheKey("reviewCode", { diff: "world" });
+		expect(key1).not.toBe(key2);
+	});
+});
+
+describe("getCachedResult", () => {
+	test("returns null on cache miss", () => {
+		const result = getCachedResult("reviewCode", { diff: "test" }, tmpDir);
+		expect(result).toBeNull();
+	});
+
+	test("returns cached value after captureResult stores it", () => {
+		captureResult({
+			tool: "reviewCode",
+			input: { diff: "test-diff" },
+			output: '{"passed": true}',
+			durationMs: 100,
+			mainaDir: tmpDir,
+		});
+		const cached = getCachedResult("reviewCode", { diff: "test-diff" }, tmpDir);
+		expect(cached).toBe('{"passed": true}');
+	});
+
+	test("returns null for different input", () => {
+		captureResult({
+			tool: "reviewCode",
+			input: { diff: "original" },
+			output: '{"passed": true}',
+			durationMs: 100,
+			mainaDir: tmpDir,
+		});
+		const cached = getCachedResult("reviewCode", { diff: "modified" }, tmpDir);
+		expect(cached).toBeNull();
+	});
+});
+
+describe("captureResult", () => {
+	test("stores result in cache", () => {
+		captureResult({
+			tool: "verify",
+			input: { files: ["a.ts"] },
+			output: '{"passed": true, "findings": []}',
+			durationMs: 50,
+			mainaDir: tmpDir,
+		});
+		const cache = createCacheManager(tmpDir);
+		const key = buildToolCacheKey("verify", { files: ["a.ts"] });
+		const entry = cache.get(key);
+		expect(entry).not.toBeNull();
+		expect(entry?.value).toBe('{"passed": true, "findings": []}');
+	});
+
+	test("records tool usage in stats", () => {
+		const { getStatsDb } = require("../../db/index");
+		captureResult({
+			tool: "reviewCode",
+			input: { diff: "test" },
+			output: "result",
+			durationMs: 250,
+			mainaDir: tmpDir,
+		});
+		const dbResult = getStatsDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const rows = db.query("SELECT * FROM tool_usage").all() as Array<{
+			tool: string;
+			duration_ms: number;
+			cache_hit: number;
+		}>;
+		expect(rows).toHaveLength(1);
+		expect(rows[0]?.tool).toBe("reviewCode");
+		expect(rows[0]?.duration_ms).toBe(250);
+		expect(rows[0]?.cache_hit).toBe(0);
+	});
+
+	test("rejects previous result on re-run with workflowId", () => {
+		const { getFeedbackDb } = require("../../db/index");
+		const { recordFeedback } = require("../collector");
+
+		// Simulate a prior tool call with workflow context
+		recordFeedback(tmpDir, {
+			promptHash: "reviewCode-mcp",
+			task: "reviewCode",
+			accepted: true,
+			timestamp: new Date().toISOString(),
+		});
+		// Set workflow_id on the row
+		const dbResult = getFeedbackDb(tmpDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		db.prepare(
+			"UPDATE feedback SET workflow_id = ? WHERE id = (SELECT id FROM feedback ORDER BY rowid DESC LIMIT 1)",
+		).run("wf-test");
+
+		// Re-run the tool (different input) — should reject previous
+		captureResult({
+			tool: "reviewCode",
+			input: { diff: "new-diff" },
+			output: "new-result",
+			durationMs: 100,
+			mainaDir: tmpDir,
+			workflowId: "wf-test",
+		});
+
+		const rows = db
+			.query(
+				"SELECT accepted FROM feedback WHERE command = ? AND workflow_id = ? ORDER BY created_at ASC",
+			)
+			.all("reviewCode", "wf-test") as Array<{ accepted: number }>;
+
+		// First entry should be rejected (0), new entry recorded via microtask
+		expect(rows[0]?.accepted).toBe(0);
+	});
+
+	test("does not throw on any failure", () => {
+		expect(() => {
+			captureResult({
+				tool: "reviewCode",
+				input: { diff: "test" },
+				output: "result",
+				durationMs: 100,
+				mainaDir: "/nonexistent/path/that/should/not/exist",
+			});
+		}).not.toThrow();
+	});
+});

package/src/feedback/__tests__/signals.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { getFeedbackDb } from "../../db/index";
+import { recordFeedback } from "../collector";
+import { emitAcceptSignal, emitRejectSignal } from "../signals";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		import.meta.dir,
+		`tmp-signals-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+	try {
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		/* ignore */
+	}
+});
+
+/** Insert a feedback row and set its workflow_id. */
+function insertFeedback(
+	tool: string,
+	workflowId: string,
+	accepted: boolean,
+): void {
+	recordFeedback(tmpDir, {
+		promptHash: `${tool}-mcp`,
+		task: tool,
+		accepted,
+		timestamp: new Date().toISOString(),
+	});
+	const dbResult = getFeedbackDb(tmpDir);
+	if (!dbResult.ok) return;
+	const { db } = dbResult.value;
+	db.prepare(
+		`UPDATE feedback SET workflow_id = ?
+		 WHERE id = (SELECT id FROM feedback ORDER BY rowid DESC LIMIT 1)`,
+	).run(workflowId);
+}
+
+describe("emitAcceptSignal", () => {
+	test("marks recent review/verify entries as accepted", () => {
+		insertFeedback("reviewCode", "wf-1", false);
+		insertFeedback("verify", "wf-1", false);
+
+		emitAcceptSignal(tmpDir, "wf-1");
+
+		const dbResult = getFeedbackDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const rows = db
+			.query("SELECT command, accepted FROM feedback WHERE workflow_id = ?")
+			.all("wf-1") as Array<{ command: string; accepted: number }>;
+		for (const row of rows) {
+			expect(row.accepted).toBe(1);
+		}
+	});
+
+	test("does not affect entries from a different workflow", () => {
+		insertFeedback("reviewCode", "wf-1", false);
+		insertFeedback("reviewCode", "wf-2", false);
+
+		emitAcceptSignal(tmpDir, "wf-1");
+
+		const dbResult = getFeedbackDb(tmpDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const wf2 = db
+			.query("SELECT accepted FROM feedback WHERE workflow_id = ?")
+			.get("wf-2") as { accepted: number } | null;
+		expect(wf2?.accepted).toBe(0);
+	});
+
+	test("accepts custom tool list", () => {
+		insertFeedback("reviewCode", "wf-1", false);
+		insertFeedback("verify", "wf-1", false);
+
+		emitAcceptSignal(tmpDir, "wf-1", ["reviewCode"]);
+
+		const dbResult = getFeedbackDb(tmpDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const review = db
+			.query(
+				"SELECT accepted FROM feedback WHERE command = ? AND workflow_id = ?",
+			)
+			.get("reviewCode", "wf-1") as { accepted: number } | null;
+		expect(review?.accepted).toBe(1);
+		const verify = db
+			.query(
+				"SELECT accepted FROM feedback WHERE command = ? AND workflow_id = ?",
+			)
+			.get("verify", "wf-1") as { accepted: number } | null;
+		expect(verify?.accepted).toBe(0);
+	});
+});
+
+describe("emitRejectSignal", () => {
+	test("marks the most recent entry for a tool+workflow as rejected", () => {
+		insertFeedback("reviewCode", "wf-1", true);
+		emitRejectSignal(tmpDir, "reviewCode", "wf-1");
+
+		const dbResult = getFeedbackDb(tmpDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const row = db
+			.query(
+				"SELECT accepted FROM feedback WHERE command = ? AND workflow_id = ? ORDER BY created_at DESC LIMIT 1",
+			)
+			.get("reviewCode", "wf-1") as { accepted: number } | null;
+		expect(row?.accepted).toBe(0);
+	});
+
+	test("only rejects the most recent entry, not older ones", () => {
+		insertFeedback("reviewCode", "wf-1", true);
+		insertFeedback("reviewCode", "wf-1", true);
+		emitRejectSignal(tmpDir, "reviewCode", "wf-1");
+
+		const dbResult = getFeedbackDb(tmpDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const rows = db
+			.query(
+				"SELECT accepted FROM feedback WHERE command = ? AND workflow_id = ? ORDER BY created_at ASC",
+			)
+			.all("reviewCode", "wf-1") as Array<{ accepted: number }>;
+		expect(rows).toHaveLength(2);
+		expect(rows[0]?.accepted).toBe(1);
+		expect(rows[1]?.accepted).toBe(0);
+	});
+
+	test("does not throw when no matching entries exist", () => {
+		expect(() => {
+			emitRejectSignal(tmpDir, "reviewCode", "nonexistent");
+		}).not.toThrow();
+	});
+});