@mainahq/core 0.2.0

package/src/ai/__tests__/tiers.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import type { MainaConfig } from "../../config/index";
+import { getTaskTier, resolveModel } from "../tiers";
+
+const TEST_CONFIG: MainaConfig = {
+	models: {
+		mechanical: "google/gemini-2.5-flash",
+		standard: "anthropic/claude-sonnet-4",
+		architectural: "anthropic/claude-sonnet-4-5",
+		local: "ollama/qwen3-coder-8b",
+	},
+	provider: "openrouter",
+	budget: {
+		daily: 5.0,
+		perTask: 0.5,
+		alertAt: 0.8,
+	},
+};
+
+describe("getTaskTier", () => {
+	test("commit maps to mechanical", () => {
+		expect(getTaskTier("commit")).toBe("mechanical");
+	});
+
+	test("tests maps to mechanical", () => {
+		expect(getTaskTier("tests")).toBe("mechanical");
+	});
+
+	test("slop maps to mechanical", () => {
+		expect(getTaskTier("slop")).toBe("mechanical");
+	});
+
+	test("compress maps to mechanical", () => {
+		expect(getTaskTier("compress")).toBe("mechanical");
+	});
+
+	test("review maps to standard", () => {
+		expect(getTaskTier("review")).toBe("standard");
+	});
+
+	test("plan maps to standard", () => {
+		expect(getTaskTier("plan")).toBe("standard");
+	});
+
+	test("design maps to standard", () => {
+		expect(getTaskTier("design")).toBe("standard");
+	});
+
+	test("fix maps to standard", () => {
+		expect(getTaskTier("fix")).toBe("standard");
+	});
+
+	test("design-review maps to architectural", () => {
+		expect(getTaskTier("design-review")).toBe("architectural");
+	});
+
+	test("architecture maps to architectural", () => {
+		expect(getTaskTier("architecture")).toBe("architectural");
+	});
+
+	test("learn maps to architectural", () => {
+		expect(getTaskTier("learn")).toBe("architectural");
+	});
+
+	test("unknown task defaults to standard", () => {
+		expect(getTaskTier("unknown")).toBe("standard");
+	});
+
+	test("empty string defaults to standard", () => {
+		expect(getTaskTier("")).toBe("standard");
+	});
+});
+
+describe("resolveModel", () => {
+	test("returns correct modelId for mechanical tier task", () => {
+		const result = resolveModel("commit", TEST_CONFIG);
+		expect(result.tier).toBe("mechanical");
+		expect(result.modelId).toBe("google/gemini-2.5-flash");
+		expect(result.provider).toBe("openrouter");
+	});
+
+	test("returns correct modelId for standard tier task", () => {
+		const result = resolveModel("review", TEST_CONFIG);
+		expect(result.tier).toBe("standard");
+		expect(result.modelId).toBe("anthropic/claude-sonnet-4");
+		expect(result.provider).toBe("openrouter");
+	});
+
+	test("returns correct modelId for architectural tier task", () => {
+		const result = resolveModel("architecture", TEST_CONFIG);
+		expect(result.tier).toBe("architectural");
+		expect(result.modelId).toBe("anthropic/claude-sonnet-4-5");
+		expect(result.provider).toBe("openrouter");
+	});
+
+	test("provider comes from config", () => {
+		const customConfig: MainaConfig = {
+			...TEST_CONFIG,
+			provider: "custom-provider",
+		};
+		const result = resolveModel("commit", customConfig);
+		expect(result.provider).toBe("custom-provider");
+	});
+
+	test("unknown task resolves to standard tier model", () => {
+		const result = resolveModel("bogus-task", TEST_CONFIG);
+		expect(result.tier).toBe("standard");
+		expect(result.modelId).toBe("anthropic/claude-sonnet-4");
+	});
+});

package/src/ai/commit-msg.ts

@@ -0,0 +1,28 @@
+import { tryAIGenerate } from "./try-generate";
+
+/**
+ * Generate a conventional commit message from a diff using AI.
+ *
+ * Returns null when no API key is available or on any failure,
+ * allowing callers to fall back to manual message entry.
+ */
+export async function generateCommitMessage(
+	diff: string,
+	stagedFiles: string[],
+	mainaDir: string,
+): Promise<string | null> {
+	const aiResult = await tryAIGenerate(
+		"commit",
+		mainaDir,
+		{ diff, files: stagedFiles.join(", ") },
+		`Generate a conventional commit message for this diff:\n\n${diff}\n\nFiles: ${stagedFiles.join(", ")}`,
+	);
+
+	if (aiResult.text && aiResult.fromAI) {
+		// Clean up: extract first line as commit message
+		const firstLine = aiResult.text.trim().split("\n")[0] ?? "";
+		return firstLine.replace(/^["'`]|["'`]$/g, "").trim() || null;
+	}
+
+	return null;
+}

package/src/ai/design-approaches.ts

@@ -0,0 +1,76 @@
+import type { Result } from "../db/index";
+import { tryAIGenerate } from "./try-generate";
+
+export interface DesignApproach {
+	name: string;
+	description: string;
+	pros: string[];
+	cons: string[];
+	recommended: boolean;
+}
+
+const MAX_APPROACHES = 3;
+
+/**
+ * Generates 2-3 design approaches with pros/cons/recommendation by asking
+ * the AI to analyze the design context and propose alternatives.
+ *
+ * Returns an empty array when:
+ * - Context is empty
+ * - AI is not available (no API key)
+ * - AI returns malformed JSON
+ */
+export async function generateDesignApproaches(
+	designContext: string,
+	mainaDir: string,
+): Promise<Result<DesignApproach[], string>> {
+	if (!designContext.trim()) {
+		return { ok: true, value: [] };
+	}
+
+	const result = await tryAIGenerate(
+		"design-approaches",
+		mainaDir,
+		{ context: designContext },
+		`Propose 2-3 architectural approaches for this design decision as a JSON array.\n\n${designContext}`,
+	);
+
+	if (!result.text) {
+		return { ok: true, value: [] };
+	}
+
+	try {
+		const parsed = parseApproachesJSON(result.text);
+		const validated = parsed.filter(isValidApproach);
+		return { ok: true, value: validated.slice(0, MAX_APPROACHES) };
+	} catch {
+		return { ok: true, value: [] };
+	}
+}
+
+function parseApproachesJSON(text: string): unknown[] {
+	let cleaned = text.trim();
+	const fenceMatch = cleaned.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+	if (fenceMatch?.[1]) {
+		cleaned = fenceMatch[1].trim();
+	}
+
+	const parsed: unknown = JSON.parse(cleaned);
+	if (!Array.isArray(parsed)) {
+		return [];
+	}
+	return parsed;
+}
+
+function isValidApproach(item: unknown): item is DesignApproach {
+	if (typeof item !== "object" || item === null) return false;
+	const obj = item as Record<string, unknown>;
+	return (
+		typeof obj.name === "string" &&
+		obj.name.length > 0 &&
+		typeof obj.description === "string" &&
+		Array.isArray(obj.pros) &&
+		Array.isArray(obj.cons) &&
+		typeof obj.recommended === "boolean"
+	);
+}

package/src/ai/index.ts

@@ -0,0 +1,205 @@
+import { buildCacheKey, hashContent } from "../cache/keys";
+import { createCacheManager } from "../cache/manager";
+import { getTtl } from "../cache/ttl";
+import {
+	getApiKey,
+	loadConfig,
+	resolveProvider,
+	shouldDelegateToHost,
+} from "../config/index";
+import { resolveModel } from "./tiers";
+import { validateAIOutput } from "./validate";
+
+export interface GenerateOptions {
+	task: string;
+	systemPrompt: string;
+	userPrompt: string;
+	files?: string[]; // for cache key
+	mainaDir?: string; // for cache storage
+}
+
+export interface GenerateResult {
+	text: string;
+	cached: boolean;
+	model: string;
+	tokens?: { input: number; output: number };
+	slopWarnings?: string[];
+}
+
+interface StoredResult {
+	text: string;
+	model: string;
+	tokens?: { input: number; output: number };
+}
+
+/**
+ * Performs the actual AI SDK call. Isolated here so tests never need to invoke it.
+ * Returns null on any error so callers can handle gracefully.
+ */
+export async function callModel(
+	modelId: string,
+	provider: string,
+	apiKey: string,
+	system: string,
+	user: string,
+): Promise<{
+	text: string;
+	tokens?: { input: number; output: number };
+} | null> {
+	try {
+		const { generateText } = await import("ai");
+		const { createOpenAI } = await import("@ai-sdk/openai");
+
+		// Provider-specific base URLs
+		let baseURL: string | undefined;
+		if (provider === "openrouter") {
+			baseURL = "https://openrouter.ai/api/v1";
+		} else if (provider === "anthropic") {
+			baseURL = "https://api.anthropic.com/v1";
+		}
+
+		const openai = createOpenAI({
+			apiKey,
+			baseURL,
+		});
+
+		const result = await generateText({
+			model: openai(modelId),
+			system,
+			prompt: user,
+		});
+
+		return {
+			text: result.text,
+			tokens:
+				result.usage != null
+					? {
+							input: result.usage.inputTokens ?? 0,
+							output: result.usage.outputTokens ?? 0,
+						}
+					: undefined,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Main AI generation function with cache-first strategy.
+ *
+ * 1. Hash the prompts to build a stable cache key.
+ * 2. Return cached result if available.
+ * 3. If no API key, return a helpful error result (never throw).
+ * 4. Call the model, cache the result, and return it.
+ */
+export async function generate(
+	options: GenerateOptions,
+): Promise<GenerateResult> {
+	const { task, systemPrompt, userPrompt, files, mainaDir } = options;
+
+	const config = await loadConfig();
+	const resolved = resolveModel(task, config);
+	const provider = resolveProvider(config);
+	// In host mode with Anthropic, use a sensible model instead of OpenRouter model IDs
+	const modelId =
+		provider === "anthropic" && resolved.modelId.startsWith("google/")
+			? "claude-sonnet-4-20250514"
+			: provider === "anthropic" && resolved.modelId.includes("/")
+				? (resolved.modelId.split("/")[1] ?? resolved.modelId)
+				: resolved.modelId;
+
+	// Build cache key
+	const promptHash = hashContent(systemPrompt + userPrompt);
+	const cacheKey = await buildCacheKey({
+		task,
+		files,
+		promptHash,
+		model: modelId,
+	});
+
+	// Set up cache (no-op manager if mainaDir not provided)
+	const effectiveMainaDir = mainaDir ?? ".maina";
+	const cache = createCacheManager(effectiveMainaDir);
+
+	// Cache hit
+	const cached = cache.get(cacheKey);
+	if (cached !== null) {
+		try {
+			const stored = JSON.parse(cached.value) as StoredResult;
+			return {
+				text: stored.text,
+				cached: true,
+				model: stored.model,
+				tokens: stored.tokens,
+			};
+		} catch {
+			// Corrupted cache entry — fall through to re-generate
+		}
+	}
+
+	// Host delegation: when running inside Claude Code/Cursor without own API key,
+	// return the prompt so the host agent can process it via MCP or skills
+	if (shouldDelegateToHost()) {
+		const delegationText = `[HOST_DELEGATION] Task: ${task}\n\nSystem: ${systemPrompt}\n\nUser: ${userPrompt}`;
+		// Cache the delegation prompt to avoid rebuilding on repeat calls
+		const ttl = getTtl(task as Parameters<typeof getTtl>[0]);
+		const storedDelegation = { text: delegationText, model: "host" };
+		cache.set(cacheKey, JSON.stringify(storedDelegation), {
+			ttl,
+			model: "host",
+		});
+		return {
+			text: delegationText,
+			cached: false,
+			model: "host",
+		};
+	}
+
+	// Check for API key
+	const apiKey = getApiKey();
+	if (apiKey === null) {
+		return {
+			text: "No API key found. Set MAINA_API_KEY or OPENROUTER_API_KEY environment variable to use AI features.",
+			cached: false,
+			model: "",
+		};
+	}
+
+	// Call the model
+	const aiResult = await callModel(
+		modelId,
+		provider,
+		apiKey,
+		systemPrompt,
+		userPrompt,
+	);
+
+	if (aiResult === null) {
+		return {
+			text: "AI call failed. Check your API key and network connection.",
+			cached: false,
+			model: modelId,
+		};
+	}
+
+	// Store in cache
+	const ttl = getTtl(task as Parameters<typeof getTtl>[0]);
+	const storedResult: StoredResult = {
+		text: aiResult.text,
+		model: modelId,
+		tokens: aiResult.tokens,
+	};
+	cache.set(cacheKey, JSON.stringify(storedResult), { ttl, model: modelId });
+
+	// Validate AI output for slop patterns
+	const validation = validateAIOutput(aiResult.text);
+
+	return {
+		text: validation.sanitized,
+		cached: false,
+		model: modelId,
+		tokens: aiResult.tokens,
+		slopWarnings:
+			validation.warnings.length > 0 ? validation.warnings : undefined,
+	};
+}

package/src/ai/pr-summary.ts

@@ -0,0 +1,60 @@
+import { tryAIGenerate } from "./try-generate";
+
+/**
+ * Generate a structured PR summary from a diff and commit list.
+ *
+ * Returns a markdown body with ## Summary, ## What Changed, and ## Review sections.
+ * Falls back to commit list if AI is unavailable.
+ */
+export async function generatePrSummary(
+	diff: string,
+	commits: Array<{ hash: string; message: string }>,
+	reviewSummary: string,
+	mainaDir: string,
+): Promise<string> {
+	const commitList = commits
+		.map((c) => `- ${c.message} (${c.hash.slice(0, 7)})`)
+		.join("\n");
+
+	const aiResult = await tryAIGenerate(
+		"pr",
+		mainaDir,
+		{ diff, commits: commitList },
+		`Write a concise PR description for the following changes.
+
+## Commits
+${commitList}
+
+## Diff (truncated)
+${diff.slice(0, 8000)}
+
+Instructions:
+- Start with a 1-2 sentence summary of WHAT this PR does and WHY
+- Then a "## What Changed" section with 3-6 bullet points grouped by theme (not one per commit)
+- Focus on user-visible impact, not implementation details
+- Do not repeat commit hashes or the full commit log
+- Do not include a review section (that's added separately)
+- Use markdown formatting`,
+	);
+
+	if (aiResult.text && aiResult.fromAI) {
+		return `${aiResult.text.trim()}
+
+## Review
+
+${reviewSummary}`;
+	}
+
+	// Fallback: structured commit list
+	return `## Summary
+
+${commits.length} commit(s) in this PR.
+
+## What Changed
+
+${commitList}
+
+## Review
+
+${reviewSummary}`;
+}

package/src/ai/spec-questions.ts

@@ -0,0 +1,74 @@
+import type { Result } from "../db/index";
+import { tryAIGenerate } from "./try-generate";
+
+export interface SpecQuestion {
+	question: string;
+	type: "text" | "select";
+	options?: string[];
+	reason: string;
+}
+
+const MAX_QUESTIONS = 5;
+
+/**
+ * Generates clarifying questions from plan.md content by asking the AI
+ * to identify ambiguities, missing edge cases, and unstated assumptions.
+ *
+ * Returns an empty array when:
+ * - Plan content is empty
+ * - AI is not available (no API key)
+ * - AI returns malformed JSON
+ */
+export async function generateSpecQuestions(
+	planContent: string,
+	mainaDir: string,
+): Promise<Result<SpecQuestion[], string>> {
+	if (!planContent.trim()) {
+		return { ok: true, value: [] };
+	}
+
+	const result = await tryAIGenerate(
+		"spec-questions",
+		mainaDir,
+		{ plan: planContent },
+		`Analyze this implementation plan and return 3-5 clarifying questions as a JSON array.\n\n${planContent}`,
+	);
+
+	if (!result.text) {
+		return { ok: true, value: [] };
+	}
+
+	try {
+		const parsed = parseQuestionsJSON(result.text);
+		const validated = parsed.filter(isValidQuestion);
+		return { ok: true, value: validated.slice(0, MAX_QUESTIONS) };
+	} catch {
+		return { ok: true, value: [] };
+	}
+}
+
+function parseQuestionsJSON(text: string): unknown[] {
+	// Strip markdown code fences if present
+	let cleaned = text.trim();
+	const fenceMatch = cleaned.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+	if (fenceMatch?.[1]) {
+		cleaned = fenceMatch[1].trim();
+	}
+
+	const parsed: unknown = JSON.parse(cleaned);
+	if (!Array.isArray(parsed)) {
+		return [];
+	}
+	return parsed;
+}
+
+function isValidQuestion(item: unknown): item is SpecQuestion {
+	if (typeof item !== "object" || item === null) return false;
+	const obj = item as Record<string, unknown>;
+	return (
+		typeof obj.question === "string" &&
+		obj.question.length > 0 &&
+		(obj.type === "text" || obj.type === "select") &&
+		typeof obj.reason === "string"
+	);
+}

package/src/ai/tiers.ts

@@ -0,0 +1,52 @@
+import type { MainaConfig } from "../config/index";
+
+export type ModelTier = "mechanical" | "standard" | "architectural" | "local";
+
+export interface ModelResolution {
+	tier: ModelTier;
+	modelId: string;
+	provider: string;
+}
+
+const MECHANICAL_TASKS = new Set([
+	"commit",
+	"tests",
+	"slop",
+	"compress",
+	"code-review",
+]);
+const ARCHITECTURAL_TASKS = new Set(["design-review", "architecture", "learn"]);
+
+/**
+ * Maps a task name to its model tier.
+ * - mechanical: commit, tests, slop, compress
+ * - standard: review, plan, design, fix (and any unknown task)
+ * - architectural: design-review, architecture, learn
+ * - local: not auto-assigned; user must explicitly set
+ */
+export function getTaskTier(task: string): ModelTier {
+	if (MECHANICAL_TASKS.has(task)) {
+		return "mechanical";
+	}
+	if (ARCHITECTURAL_TASKS.has(task)) {
+		return "architectural";
+	}
+	// standard is the default for known standard tasks and all unknowns
+	return "standard";
+}
+
+/**
+ * Resolves the model ID and provider for a given task using the provided config.
+ */
+export function resolveModel(
+	task: string,
+	config: MainaConfig,
+): ModelResolution {
+	const tier = getTaskTier(task);
+	const modelId = config.models[tier];
+	return {
+		tier,
+		modelId,
+		provider: config.provider,
+	};
+}

package/src/ai/try-generate.ts

@@ -0,0 +1,89 @@
+import { getApiKey, isHostMode } from "../config/index";
+
+export interface DelegationPrompt {
+	task: string;
+	systemPrompt: string;
+	userPrompt: string;
+	promptHash: string;
+}
+
+export interface TryAIResult {
+	text: string | null;
+	fromAI: boolean;
+	hostDelegation: boolean;
+	promptHash?: string;
+	/** Structured prompt for host to process when hostDelegation is true */
+	delegation?: DelegationPrompt;
+}
+
+/**
+ * Single entry point for all AI calls.
+ *
+ * Returns:
+ * - { text, fromAI: true } when AI generates a response (has API key)
+ * - { text: null, hostDelegation: true, delegation } when in host mode (no key)
+ *   The delegation contains structured prompts for the host agent to process.
+ * - { text: null } when AI is not available and not in host mode
+ */
+export async function tryAIGenerate(
+	task: string,
+	mainaDir: string,
+	variables: Record<string, string>,
+	userPrompt: string,
+): Promise<TryAIResult> {
+	const apiKey = getApiKey();
+
+	// Not in host mode and no key → unavailable
+	if (!apiKey && !isHostMode()) {
+		return { text: null, fromAI: false, hostDelegation: false };
+	}
+
+	try {
+		const { buildSystemPrompt } = await import("../prompts/engine");
+
+		// Build the prompt (needed for both direct call and delegation)
+		const builtPrompt = await buildSystemPrompt(task, mainaDir, variables);
+
+		// If we have an API key, make the direct call
+		if (apiKey) {
+			const { generate } = await import("./index");
+			const result = await generate({
+				task,
+				systemPrompt: builtPrompt.prompt,
+				userPrompt,
+				mainaDir,
+			});
+
+			// Skip delegation responses from generate() — we handle it below
+			if (
+				result.text &&
+				!result.text.startsWith("[HOST_DELEGATION]") &&
+				!result.text.includes("API key")
+			) {
+				return {
+					text: result.text,
+					fromAI: true,
+					hostDelegation: false,
+					promptHash: builtPrompt.hash,
+				};
+			}
+		}
+
+		// Host mode — return structured delegation for host agent to process
+		return {
+			text: null,
+			fromAI: false,
+			hostDelegation: true,
+			promptHash: builtPrompt.hash,
+			delegation: {
+				task,
+				systemPrompt: builtPrompt.prompt,
+				userPrompt,
+				promptHash: builtPrompt.hash,
+			},
+		};
+	} catch {
+		// AI failure — return null for fallback
+	}
+	return { text: null, fromAI: false, hostDelegation: false };
+}