@mainahq/core 1.0.2 → 1.1.0

package/src/feedback/capture.ts

@@ -0,0 +1,102 @@
+/**
+ * MCP result capture — connects tool outputs to cache, feedback, and stats.
+ * This is the core of the round-trip flywheel.
+ */
+
+import { hashContent } from "../cache/keys";
+import { createCacheManager } from "../cache/manager";
+import { trackToolUsage } from "../stats/tracker";
+import { recordFeedback } from "./collector";
+import { emitRejectSignal } from "./signals";
+
+export interface CaptureInput {
+	tool: string;
+	input: Record<string, unknown>;
+	output: string;
+	promptHash?: string;
+	durationMs: number;
+	mainaDir: string;
+	workflowId?: string;
+}
+
+export function buildToolCacheKey(
+	tool: string,
+	input: Record<string, unknown>,
+): string {
+	const inputHash = hashContent(JSON.stringify(input));
+	return hashContent(`mcp:${tool}:${inputHash}`);
+}
+
+export function getCachedResult(
+	tool: string,
+	input: Record<string, unknown>,
+	mainaDir: string,
+): string | null {
+	try {
+		const cache = createCacheManager(mainaDir);
+		const key = buildToolCacheKey(tool, input);
+		const entry = cache.get(key);
+		if (entry !== null) {
+			const inputHash = hashContent(JSON.stringify(input));
+			trackToolUsage(mainaDir, {
+				tool,
+				inputHash,
+				durationMs: 0,
+				cacheHit: true,
+			});
+			return entry.value;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export function captureResult(input: CaptureInput): void {
+	const inputHash = hashContent(JSON.stringify(input.input));
+
+	// 1. Cache (synchronous — fast SQLite write)
+	try {
+		const cache = createCacheManager(input.mainaDir);
+		const key = buildToolCacheKey(input.tool, input.input);
+		cache.set(key, input.output, { ttl: 0 });
+	} catch {
+		// Cache failure is non-fatal
+	}
+
+	// 2. Reject previous result for same tool+workflow (re-run implies rejection)
+	if (input.workflowId) {
+		try {
+			emitRejectSignal(input.mainaDir, input.tool, input.workflowId);
+		} catch {
+			// Reject failure is non-fatal
+		}
+	}
+
+	// 3. Feedback (fire-and-forget via microtask)
+	queueMicrotask(() => {
+		try {
+			recordFeedback(input.mainaDir, {
+				promptHash: input.promptHash ?? `${input.tool}-mcp`,
+				task: input.tool,
+				accepted: true,
+				timestamp: new Date().toISOString(),
+			});
+		} catch {
+			// Never throw from background feedback
+		}
+	});
+
+	// 4. Stats (synchronous — fast SQLite write)
+	try {
+		trackToolUsage(input.mainaDir, {
+			tool: input.tool,
+			inputHash,
+			durationMs: input.durationMs,
+			cacheHit: false,
+			workflowId: input.workflowId,
+		});
+	} catch {
+		// Stats failure is non-fatal
+	}
+}

package/src/feedback/signals.ts

@@ -0,0 +1,68 @@
+/**
+ * Implicit accept/reject signals for the RL flywheel.
+ * Infers outcomes from downstream user behavior instead of requiring explicit action.
+ */
+
+import { join } from "node:path";
+import { getFeedbackDb } from "../db/index";
+import { recordWikiUsage } from "../wiki/signals";
+
+const DEFAULT_ACCEPT_TOOLS = ["reviewCode", "verify", "checkSlop"];
+
+export function emitAcceptSignal(
+	mainaDir: string,
+	workflowId: string,
+	tools?: string[],
+	wikiArticles?: string[],
+): void {
+	try {
+		const dbResult = getFeedbackDb(mainaDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		const targetTools = tools ?? DEFAULT_ACCEPT_TOOLS;
+		const placeholders = targetTools.map(() => "?").join(",");
+		db.prepare(
+			`UPDATE feedback SET accepted = 1
+			 WHERE workflow_id = ?
+			 AND command IN (${placeholders})`,
+		).run(workflowId, ...targetTools);
+
+		// Record wiki effectiveness signal for loaded articles
+		if (wikiArticles && wikiArticles.length > 0) {
+			const wikiDir = join(mainaDir, "wiki");
+			recordWikiUsage(wikiDir, wikiArticles, "accept", true);
+		}
+	} catch {
+		// Never throw from signals
+	}
+}
+
+export function emitRejectSignal(
+	mainaDir: string,
+	tool: string,
+	workflowId: string,
+	wikiArticles?: string[],
+): void {
+	try {
+		const dbResult = getFeedbackDb(mainaDir);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+		db.prepare(
+			`UPDATE feedback SET accepted = 0
+			 WHERE command = ? AND workflow_id = ?
+			 AND id = (
+				 SELECT id FROM feedback
+				 WHERE command = ? AND workflow_id = ?
+				 ORDER BY created_at DESC, rowid DESC LIMIT 1
+			 )`,
+		).run(tool, workflowId, tool, workflowId);
+
+		// Record wiki effectiveness signal for loaded articles
+		if (wikiArticles && wikiArticles.length > 0) {
+			const wikiDir = join(mainaDir, "wiki");
+			recordWikiUsage(wikiDir, wikiArticles, tool, false);
+		}
+	} catch {
+		// Never throw from signals
+	}
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export const VERSION = "0.1.0";
 
 // AI
+export { type AIAvailability, checkAIAvailability } from "./ai/availability";
 export { generateCommitMessage } from "./ai/commit-msg";
 // AI — Delegation
 export {
@@ -99,8 +100,9 @@ export {
 	setVerificationResult,
 	trackFile,
 } from "./context/working";
-// DB (Result type)
+// DB
 export type { Result } from "./db/index";
+export { getFeedbackDb } from "./db/index";
 // Design (ADR)
 export {
 	type AdrSummary,
@@ -152,6 +154,12 @@ export type {
 	TraceDeps,
 } from "./features/traceability";
 export { traceFeature } from "./features/traceability";
+export {
+	buildToolCacheKey,
+	type CaptureInput,
+	captureResult,
+	getCachedResult,
+} from "./feedback/capture";
 // Feedback
 export {
 	type FeedbackRecord,
@@ -174,6 +182,7 @@ export {
 	type RulePreference,
 	savePreferences,
 } from "./feedback/preferences";
+export { emitAcceptSignal, emitRejectSignal } from "./feedback/signals";
 export {
 	exportEpisodicForCloud,
 	exportFeedbackForCloud,
@@ -211,6 +220,7 @@ export {
 // Init
 export {
 	bootstrap,
+	buildMainaSection,
 	type DetectedStack,
 	type InitOptions,
 	type InitReport,
@@ -284,12 +294,16 @@ export {
 	getLatest,
 	getSkipRate,
 	getStats,
+	getToolUsageStats,
 	getTrends,
 	recordSnapshot,
 	type SnapshotInput,
 	type StatsReport,
+	type ToolUsageInput,
+	type ToolUsageStats,
 	type TrendDirection,
 	type TrendsReport,
+	trackToolUsage,
 } from "./stats/tracker";
 // Ticket
 export {
@@ -424,8 +438,101 @@ export {
 	type ZapOptions,
 	type ZapResult,
 } from "./verify/zap";
+// Wiki — Compiler
+export {
+	type CompilationResult as WikiCompilationResult,
+	type CompileOptions as WikiCompileOptions,
+	compile as compileWiki,
+} from "./wiki/compiler";
+export { type CodeEntity, extractCodeEntities } from "./wiki/extractors/code";
+export {
+	extractDecisions,
+	extractSingleDecision,
+} from "./wiki/extractors/decision";
+export {
+	extractFeatures,
+	extractSingleFeature,
+} from "./wiki/extractors/feature";
+export { extractWorkflowTrace } from "./wiki/extractors/workflow";
+// Wiki — Graph
+export {
+	buildKnowledgeGraph,
+	computePageRank,
+	type GraphEdge,
+	type GraphNode,
+	type KnowledgeGraph,
+	mapToArticles,
+} from "./wiki/graph";
+// Wiki — Indexer
+export { generateIndex } from "./wiki/indexer";
+// Wiki — Linker
+export { generateLinks, type LinkResult } from "./wiki/linker";
+// Wiki — Louvain
+export {
+	detectCommunities,
+	type LouvainNode,
+	type LouvainResult,
+} from "./wiki/louvain";
+// Wiki — Query
+export {
+	queryWiki,
+	type WikiQueryOptions,
+	type WikiQueryResult,
+} from "./wiki/query";
+export {
+	DEFAULT_SCHEMA,
+	getArticleMaxLength,
+	getLinkSyntax,
+	validateArticleStructure,
+	type WikiSchema,
+} from "./wiki/schema";
+// Wiki — Signals
+export {
+	type ArticleLoadSignal,
+	type CompilationPromptSignal,
+	calculateEbbinghausScore,
+	getPromptEffectiveness,
+	getWikiEffectivenessReport,
+	recordArticlesLoaded,
+	recordWikiUsage,
+	type WikiEffectivenessReport,
+	type WikiEffectivenessSignal,
+} from "./wiki/signals";
+export {
+	createEmptyState,
+	getChangedFiles as getWikiChangedFiles,
+	hashContent,
+	hashFile,
+	loadState as loadWikiState,
+	saveState as saveWikiState,
+} from "./wiki/state";
+// Wiki — Tracking
+export {
+	trackWikiRefsRead,
+	trackWikiRefsWritten,
+} from "./wiki/tracking";
+// Wiki
+export type {
+	ArticleType,
+	DecisionStatus,
+	EdgeType,
+	ExtractedDecision,
+	ExtractedFeature,
+	ExtractedWorkflowTrace,
+	RLSignal,
+	TaskItem,
+	WikiArticle,
+	WikiLink,
+	WikiLintCheck,
+	WikiLintFinding,
+	WikiLintResult,
+	WikiState,
+	WorkflowStep as WikiWorkflowStep,
+} from "./wiki/types";
+export { DECAY_HALF_LIVES } from "./wiki/types";
 // Workflow
 export {
+	appendWikiRefs,
 	appendWorkflowStep,
 	loadWorkflowContext,
 	resetWorkflowContext,