@mainahq/core 1.0.3 → 1.1.0

package/src/init/index.ts

@@ -332,7 +332,9 @@ const MCP_TOOLS_TABLE = `| Tool | When to use |
 | \`suggestTests\` | When implementing — generate TDD test stubs |
 | \`getConventions\` | Understand project coding conventions |
 | \`explainModule\` | Understand a module's purpose and dependencies |
-| \`analyzeFeature\` | Analyze a feature directory for consistency |`;
+| \`analyzeFeature\` | Analyze a feature directory for consistency |
+| \`wikiQuery\` | Search wiki for codebase knowledge — "how does auth work?" |
+| \`wikiStatus\` | Wiki health check — article counts, staleness, coverage |`;
 
 // ── Templates ────────────────────────────────────────────────────────────────
 
@@ -465,6 +467,13 @@ maina commit    # verify + commit
 
 ${MCP_TOOLS_TABLE}
 
+## Wiki
+
+If \`.maina/wiki/\` exists, use wiki tools for context:
+- \`wikiQuery\` before coding — understand existing patterns and decisions
+- \`wikiStatus\` to check health
+- Wiki articles are loaded automatically as Context Engine Layer 5
+
 ## Config Files
 | File | Purpose | Who Edits |
 |------|---------|-----------|
@@ -474,6 +483,13 @@ ${MCP_TOOLS_TABLE}
 | \`CLAUDE.md\` | Claude Code specific instructions | Optional, Claude Code users |
 | \`GEMINI.md\` | Gemini CLI specific instructions | Optional, Gemini CLI users |
 | \`.cursorrules\` | Cursor specific instructions | Optional, Cursor users |
+| \`.windsurfrules\` | Windsurf specific instructions | Optional, Windsurf users |
+| \`.clinerules\` | Cline specific instructions | Optional, Cline users |
+| \`.continue/\` | Continue.dev config + MCP | Optional, Continue.dev users |
+| \`.roo/\` | Roo Code MCP config + rules | Optional, Roo Code users |
+| \`.amazonq/mcp.json\` | Amazon Q MCP config | Optional, Amazon Q users |
+| \`.aider.conf.yml\` | Aider config | Optional, Aider users |
+| \`CONVENTIONS.md\` | Project conventions (Aider, generic) | Team |
 | \`.mcp.json\` | MCP server configuration | Team |
 | \`.maina/prompts/*.md\` | Prompt overrides for review/commit/etc | Maina (via \`maina learn\`) |
 
@@ -506,6 +522,13 @@ Follow this order for every feature:
 
 ${MCP_TOOLS_TABLE}
 
+## Wiki
+
+If \`.maina/wiki/\` exists, use wiki tools for context:
+- \`wikiQuery\` before coding — understand existing patterns and decisions
+- \`wikiStatus\` to check health
+- Wiki articles are loaded automatically as Context Engine Layer 5
+
 ## Conventions
 
 - Runtime: ${stack.runtime}
@@ -529,6 +552,10 @@ const MERGEABLE_AGENT_FILES = [
 	"GEMINI.md",
 	".cursorrules",
 	".github/copilot-instructions.md",
+	".windsurfrules",
+	".clinerules",
+	".roo/rules/maina.md",
+	"CONVENTIONS.md",
 ];
 
 /**
@@ -551,13 +578,32 @@ ${MCP_TOOLS_TABLE}
 
 // ── .mcp.json ───────────────────────────────────────────────────────────────
 
-function buildMcpJson(): string {
+function buildMcpJson(stack: DetectedStack): string {
+	const command = stack.runtime === "bun" ? "bunx" : "npx";
 	return JSON.stringify(
 		{
 			mcpServers: {
 				maina: {
-					command: "maina",
-					args: ["--mcp"],
+					command,
+					args: ["@mainahq/cli", "--mcp"],
+				},
+			},
+		},
+		null,
+		2,
+	);
+}
+
+// ── .claude/settings.json (Claude Code MCP config) ─────────────────────────
+
+function buildClaudeSettings(stack: DetectedStack): string {
+	const command = stack.runtime === "bun" ? "bunx" : "npx";
+	return JSON.stringify(
+		{
+			mcpServers: {
+				maina: {
+					command,
+					args: ["@mainahq/cli", "--mcp"],
 				},
 			},
 		},
@@ -586,16 +632,42 @@ Maina exposes MCP tools — use them in every session:
 
 ${MCP_TOOLS_TABLE}
 
+## Wiki
+
+If \`.maina/wiki/\` exists, use wiki tools for context:
+- \`wikiQuery\` before coding — understand existing patterns and decisions
+- \`wikiStatus\` to check health
+- Wiki articles are loaded automatically as Context Engine Layer 5
+
 ## Commands
 
 \`\`\`bash
-maina verify    # run full verification pipeline
-maina commit    # verify + commit
-maina review    # two-stage code review
-maina context   # generate focused codebase context
-maina doctor    # check tool health
-maina plan      # create feature with spec/plan/tasks
-maina stats     # show verification metrics
+# Workflow
+maina brainstorm  # explore ideas interactively
+maina ticket      # create GitHub issue with module tagging
+maina plan <name> # scaffold feature branch + directory
+maina design      # create ADR (architecture decision record)
+maina spec        # generate TDD test stubs from plan
+
+# Verify & Review
+maina verify      # run full verification pipeline (12+ tools)
+maina review      # two-stage code review
+maina slop        # detect AI-generated slop patterns
+maina commit      # verify + commit staged changes
+
+# Wiki (codebase knowledge)
+maina wiki init    # compile codebase knowledge wiki
+maina wiki query   # ask questions about the codebase
+maina wiki compile # recompile wiki (incremental)
+maina wiki status  # wiki health dashboard
+maina wiki lint    # check wiki for issues
+
+# Context & Info
+maina context     # generate focused codebase context
+maina explain     # explain a module with wiki context
+maina doctor      # check tool health
+maina stats       # verification metrics
+maina status      # branch health overview
 \`\`\`
 
 ## Conventions
@@ -629,6 +701,13 @@ Maina exposes MCP tools via \`.mcp.json\`. Use them:
 
 ${MCP_TOOLS_TABLE}
 
+## Wiki
+
+If \`.maina/wiki/\` exists, use wiki tools for context:
+- \`wikiQuery\` before coding — understand existing patterns and decisions
+- \`wikiStatus\` to check health
+- Wiki articles are loaded automatically as Context Engine Layer 5
+
 ## Key Commands
 
 - \`maina verify\` — run full verification pipeline
@@ -661,6 +740,89 @@ ${WORKFLOW_ORDER}
 ## MCP Tools (via .mcp.json)
 ${MCP_TOOLS_TABLE}
 
+## Wiki
+
+If \`.maina/wiki/\` exists, use wiki tools for context:
+- \`wikiQuery\` before coding — understand existing patterns and decisions
+- \`wikiStatus\` to check health
+- Wiki articles are loaded automatically as Context Engine Layer 5
+
+## Commands
+- maina verify — run full verification pipeline
+- maina commit — verify + commit
+- maina review — two-stage code review
+- maina context — generate focused codebase context
+
+## Conventions
+- Runtime: ${stack.runtime}
+- Test: ${runCmd} test
+- Conventional commits
+- No console.log in production
+- Diff-only: only report findings on changed lines
+- TDD: write tests first, then implement
+`;
+}
+
+// ── Windsurf ────────────────────────────────────────────────────────────────
+
+function buildWindsurfRules(stack: DetectedStack): string {
+	const runCmd = stack.runtime === "bun" ? "bun" : "npm";
+	return `# Windsurf Rules
+
+This repo uses Maina for verification-first development.
+Read \`.maina/constitution.md\` for project DNA.
+
+## Workflow Order
+${WORKFLOW_ORDER}
+
+## MCP Tools (via .mcp.json)
+${MCP_TOOLS_TABLE}
+
+## Wiki
+
+If \`.maina/wiki/\` exists, use wiki tools for context:
+- \`wikiQuery\` before coding — understand existing patterns and decisions
+- \`wikiStatus\` to check health
+- Wiki articles are loaded automatically as Context Engine Layer 5
+
+## Commands
+- maina verify — run full verification pipeline
+- maina commit — verify + commit
+- maina review — two-stage code review
+- maina context — generate focused codebase context
+
+## Conventions
+- Runtime: ${stack.runtime}
+- Test: ${runCmd} test
+- Conventional commits
+- No console.log in production
+- Diff-only: only report findings on changed lines
+- TDD: write tests first, then implement
+`;
+}
+
+// ── Cline ───────────────────────────────────────────────────────────────────
+
+function buildClineRules(stack: DetectedStack): string {
+	const runCmd = stack.runtime === "bun" ? "bun" : "npm";
+	return `# Cline Rules
+
+This repo uses Maina for verification-first development.
+Read \`.maina/constitution.md\` for project DNA.
+
+## Workflow Order
+${WORKFLOW_ORDER}
+
+## MCP Tools (via .mcp.json)
+${MCP_TOOLS_TABLE}
+
+## Wiki
+
+If \`.maina/wiki/\` exists, use wiki tools for context:
+- \`wikiQuery\` before coding — understand existing patterns and decisions
+- \`wikiStatus\` to check health
+- Wiki articles are loaded automatically as Context Engine Layer 5
+
 ## Commands
 - maina verify — run full verification pipeline
 - maina commit — verify + commit
@@ -677,6 +839,160 @@ ${MCP_TOOLS_TABLE}
 `;
 }
 
+// ── Continue.dev ─────────────────────────────────────────────────────────────
+
+function buildContinueConfig(_stack: DetectedStack): string {
+	return `# Continue.dev configuration — auto-generated by maina init
+# See https://docs.continue.dev/reference/config
+
+customInstructions: |
+  This repo uses Maina for verification-first development.
+  Read .maina/constitution.md for project DNA.
+  Workflow: ${WORKFLOW_ORDER}
+  Always run maina verify before committing.
+  Use MCP tools: getContext, verify, checkSlop, reviewCode, suggestTests.
+`;
+}
+
+function buildContinueMcpJson(stack: DetectedStack): string {
+	const command = stack.runtime === "bun" ? "bunx" : "npx";
+	return JSON.stringify(
+		{
+			maina: {
+				command,
+				args: ["@mainahq/cli", "--mcp"],
+			},
+		},
+		null,
+		2,
+	);
+}
+
+// ── Roo Code ────────────────────────────────────────────────────────────────
+
+function buildRooMcpJson(stack: DetectedStack): string {
+	const command = stack.runtime === "bun" ? "bunx" : "npx";
+	return JSON.stringify(
+		{
+			mcpServers: {
+				maina: {
+					command,
+					args: ["@mainahq/cli", "--mcp"],
+				},
+			},
+		},
+		null,
+		2,
+	);
+}
+
+function buildRooRules(stack: DetectedStack): string {
+	const runCmd = stack.runtime === "bun" ? "bun" : "npm";
+	return `# Maina
+
+This repo uses [Maina](https://mainahq.com) for verification-first development.
+Read \`.maina/constitution.md\` for project DNA.
+
+## Workflow Order
+${WORKFLOW_ORDER}
+
+## MCP Tools
+${MCP_TOOLS_TABLE}
+
+## Wiki
+
+If \`.maina/wiki/\` exists, use wiki tools for context:
+- \`wikiQuery\` before coding — understand existing patterns and decisions
+- \`wikiStatus\` to check health
+- Wiki articles are loaded automatically as Context Engine Layer 5
+
+## Commands
+- maina verify — run full verification pipeline
+- maina commit — verify + commit
+- maina review — two-stage code review
+- maina context — generate focused codebase context
+
+## Conventions
+- Runtime: ${stack.runtime}
+- Test: ${runCmd} test
+- Conventional commits
+- No console.log in production
+- Diff-only: only report findings on changed lines
+- TDD: write tests first, then implement
+`;
+}
+
+// ── Amazon Q ────────────────────────────────────────────────────────────────
+
+function buildAmazonQMcpJson(stack: DetectedStack): string {
+	const command = stack.runtime === "bun" ? "bunx" : "npx";
+	return JSON.stringify(
+		{
+			mcpServers: {
+				maina: {
+					command,
+					args: ["@mainahq/cli", "--mcp"],
+				},
+			},
+		},
+		null,
+		2,
+	);
+}
+
+// ── Aider ───────────────────────────────────────────────────────────────────
+
+function buildAiderConfig(_stack: DetectedStack): string {
+	return `# Maina conventions — auto-generated by maina init
+read: [CONVENTIONS.md, .maina/constitution.md]
+auto-commits: false
+`;
+}
+
+function buildConventionsMd(stack: DetectedStack): string {
+	const runCmd = stack.runtime === "bun" ? "bun" : "npm";
+	return `# Conventions
+
+This repo uses [Maina](https://mainahq.com) for verification-first development.
+Read \`.maina/constitution.md\` for project DNA — stack rules, conventions, and gates.
+
+## Maina Workflow
+
+Follow this order for every feature:
+\`${WORKFLOW_ORDER}\`
+
+## MCP Tools
+
+Maina exposes MCP tools — use them in every session:
+
+${MCP_TOOLS_TABLE}
+
+## Wiki
+
+If \`.maina/wiki/\` exists, use wiki tools for context:
+- \`wikiQuery\` before coding — understand existing patterns and decisions
+- \`wikiStatus\` to check health
+- Wiki articles are loaded automatically as Context Engine Layer 5
+
+## Key Commands
+
+- \`maina verify\` — run full verification pipeline
+- \`maina commit\` — verify + commit
+- \`maina review\` — two-stage code review
+- \`maina context\` — generate focused codebase context
+- \`maina doctor\` — check tool health
+
+## Conventions
+
+- Runtime: ${stack.runtime}
+- Test: \`${runCmd} test\`
+- Conventional commits (feat, fix, refactor, test, docs, chore)
+- No \`console.log\` in production code
+- Diff-only: only report findings on changed lines
+- TDD always — write tests first
+`;
+}
+
 // ── AI-Generated Constitution ───────────────────────────────────────────────
 
 function buildProjectSummary(repoRoot: string, stack: DetectedStack): string {
@@ -869,7 +1185,11 @@ function getFileManifest(
 		},
 		{
 			relativePath: ".mcp.json",
-			content: buildMcpJson(),
+			content: buildMcpJson(stack),
+		},
+		{
+			relativePath: ".claude/settings.json",
+			content: buildClaudeSettings(stack),
 		},
 		{
 			relativePath: "CLAUDE.md",
@@ -883,6 +1203,42 @@ function getFileManifest(
 			relativePath: ".cursorrules",
 			content: buildCursorRules(stack),
 		},
+		{
+			relativePath: ".windsurfrules",
+			content: buildWindsurfRules(stack),
+		},
+		{
+			relativePath: ".clinerules",
+			content: buildClineRules(stack),
+		},
+		{
+			relativePath: ".continue/config.yaml",
+			content: buildContinueConfig(stack),
+		},
+		{
+			relativePath: ".continue/mcpServers/maina.json",
+			content: buildContinueMcpJson(stack),
+		},
+		{
+			relativePath: ".roo/mcp.json",
+			content: buildRooMcpJson(stack),
+		},
+		{
+			relativePath: ".roo/rules/maina.md",
+			content: buildRooRules(stack),
+		},
+		{
+			relativePath: ".amazonq/mcp.json",
+			content: buildAmazonQMcpJson(stack),
+		},
+		{
+			relativePath: ".aider.conf.yml",
+			content: buildAiderConfig(stack),
+		},
+		{
+			relativePath: "CONVENTIONS.md",
+			content: buildConventionsMd(stack),
+		},
 	];
 }
 

package/src/language/__tests__/__fixtures__/detect/composer.lock

@@ -0,0 +1 @@
+{"packages": []}

package/src/prompts/defaults/index.ts

@@ -11,7 +11,9 @@ export type PromptTask =
 	| "spec-questions"
 	| "design-approaches"
 	| "ai-review"
-	| "design-hld-lld";
+	| "design-hld-lld"
+	| "wiki-query"
+	| "wiki-compile";
 
 const FALLBACK_TEMPLATE = `You are a helpful AI assistant completing the "{{task}}" task.
 

package/src/prompts/defaults/wiki-compile.md

@@ -0,0 +1,20 @@
+You are enhancing a wiki article with natural language descriptions.
+
+## Constitution (non-negotiable)
+{{constitution}}
+
+## Instructions
+Enhance this wiki article with natural language descriptions. Keep all existing structured data.
+Add a brief overview paragraph and usage context. Do not remove any existing content.
+
+Rules:
+1. Preserve ALL existing markdown structure, headings, lists, and wikilinks
+2. Add a concise overview paragraph after the title heading
+3. Add natural language descriptions to sections that are purely data-driven
+4. Infer relationships not visible from code structure alone where possible
+5. Add brief usage examples if the context provides enough information
+6. Keep the tone technical and factual — do not add filler or marketing language
+7. If anything is ambiguous, use [NEEDS CLARIFICATION: specific question]
+
+## Input
+{{input}}

package/src/prompts/defaults/wiki-query.md

@@ -0,0 +1,18 @@
+You are answering a question about a codebase using wiki documentation.
+
+## Constitution (non-negotiable)
+{{constitution}}
+
+## Instructions
+Answer the user's question based on the provided wiki articles.
+
+Rules:
+1. Provide a clear, concise answer that directly addresses the question
+2. Cite relevant articles using [[article_path]] notation (e.g., [[modules/core.md]])
+3. If the articles don't contain enough information, say so explicitly
+4. Do NOT guess or hallucinate information not present in the articles
+5. If anything is ambiguous, use [NEEDS CLARIFICATION: specific question]
+6. Prioritize accuracy over completeness
+
+## Input
+{{input}}

package/src/stats/__tests__/tool-usage.test.ts

@@ -0,0 +1,133 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { getStatsDb } from "../../db/index";
+import { getToolUsageStats, trackToolUsage } from "../tracker";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		import.meta.dir,
+		`tmp-tool-usage-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+	try {
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		/* ignore */
+	}
+});
+
+describe("tool_usage table", () => {
+	test("getStatsDb creates tool_usage table", () => {
+		const result = getStatsDb(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		const { db } = result.value;
+		const tables = db
+			.query(
+				"SELECT name FROM sqlite_master WHERE type='table' AND name='tool_usage'",
+			)
+			.all();
+		expect(tables).toHaveLength(1);
+	});
+});
+
+describe("trackToolUsage", () => {
+	test("inserts a tool usage row", () => {
+		trackToolUsage(tmpDir, {
+			tool: "reviewCode",
+			inputHash: "abc123",
+			durationMs: 150,
+			cacheHit: false,
+		});
+		const result = getStatsDb(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		const { db } = result.value;
+		const rows = db.query("SELECT * FROM tool_usage").all() as Array<{
+			tool: string;
+			duration_ms: number;
+			cache_hit: number;
+		}>;
+		expect(rows).toHaveLength(1);
+		const row = rows[0];
+		expect(row).toBeDefined();
+		expect(row?.tool).toBe("reviewCode");
+		expect(row?.duration_ms).toBe(150);
+		expect(row?.cache_hit).toBe(0);
+	});
+
+	test("tracks cache hit", () => {
+		trackToolUsage(tmpDir, {
+			tool: "reviewCode",
+			inputHash: "abc123",
+			durationMs: 0,
+			cacheHit: true,
+		});
+		const result = getStatsDb(tmpDir);
+		if (!result.ok) return;
+		const { db } = result.value;
+		const rows = db.query("SELECT * FROM tool_usage WHERE cache_hit = 1").all();
+		expect(rows).toHaveLength(1);
+	});
+
+	test("stores workflow_id when provided", () => {
+		trackToolUsage(tmpDir, {
+			tool: "verify",
+			inputHash: "def456",
+			durationMs: 200,
+			cacheHit: false,
+			workflowId: "wf-123",
+		});
+		const result = getStatsDb(tmpDir);
+		if (!result.ok) return;
+		const { db } = result.value;
+		const row = db.query("SELECT workflow_id FROM tool_usage").get() as {
+			workflow_id: string;
+		} | null;
+		expect(row?.workflow_id).toBe("wf-123");
+	});
+});
+
+describe("getToolUsageStats", () => {
+	test("returns stats across multiple tool calls", () => {
+		trackToolUsage(tmpDir, {
+			tool: "reviewCode",
+			inputHash: "a",
+			durationMs: 100,
+			cacheHit: false,
+		});
+		trackToolUsage(tmpDir, {
+			tool: "reviewCode",
+			inputHash: "b",
+			durationMs: 200,
+			cacheHit: true,
+		});
+		trackToolUsage(tmpDir, {
+			tool: "verify",
+			inputHash: "c",
+			durationMs: 50,
+			cacheHit: false,
+		});
+		const stats = getToolUsageStats(tmpDir);
+		expect(stats.totalCalls).toBe(3);
+		expect(stats.cacheHits).toBe(1);
+		expect(stats.cacheHitRate).toBeCloseTo(1 / 3, 2);
+		expect(stats.byTool.reviewCode).toBeDefined();
+		expect(stats.byTool.reviewCode?.calls).toBe(2);
+		expect(stats.byTool.reviewCode?.cacheHits).toBe(1);
+		expect(stats.byTool.verify).toBeDefined();
+		expect(stats.byTool.verify?.calls).toBe(1);
+	});
+
+	test("returns empty stats when no data", () => {
+		const stats = getToolUsageStats(tmpDir);
+		expect(stats.totalCalls).toBe(0);
+		expect(stats.cacheHitRate).toBe(0);
+	});
+});