@mainahq/core 0.2.0

package/src/init/index.ts

@@ -0,0 +1,364 @@
+/**
+ * Init module — bootstraps Maina in a repository.
+ *
+ * Creates `.maina/` directory structure and scaffolds default files.
+ * Detects project type from package.json and customizes templates.
+ * Never overwrites existing files unless `force: true`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Result } from "../db/index";
+import type { DetectedTool } from "../verify/detect";
+import { detectTools } from "../verify/detect";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface InitOptions {
+	force?: boolean;
+}
+
+export interface InitReport {
+	created: string[];
+	skipped: string[];
+	directory: string;
+	detectedStack: DetectedStack;
+	detectedTools: DetectedTool[];
+}
+
+export interface DetectedStack {
+	runtime: "bun" | "node" | "deno" | "unknown";
+	language: "typescript" | "javascript" | "unknown";
+	testRunner: string;
+	linter: string;
+	framework: string;
+}
+
+// ── Project Detection ───────────────────────────────────────────────────────
+
+function detectStack(repoRoot: string): DetectedStack {
+	const stack: DetectedStack = {
+		runtime: "unknown",
+		language: "unknown",
+		testRunner: "unknown",
+		linter: "unknown",
+		framework: "none",
+	};
+
+	// Try reading package.json
+	const pkgPath = join(repoRoot, "package.json");
+	if (!existsSync(pkgPath)) return stack;
+
+	let pkg: Record<string, unknown>;
+	try {
+		pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+	} catch {
+		return stack;
+	}
+
+	const allDeps = {
+		...(pkg.dependencies as Record<string, string> | undefined),
+		...(pkg.devDependencies as Record<string, string> | undefined),
+		...(pkg.peerDependencies as Record<string, string> | undefined),
+	};
+
+	// Runtime detection
+	if (
+		allDeps["@types/bun"] ||
+		allDeps["bun-types"] ||
+		existsSync(join(repoRoot, "bun.lock"))
+	) {
+		stack.runtime = "bun";
+	} else if (
+		existsSync(join(repoRoot, "deno.json")) ||
+		existsSync(join(repoRoot, "deno.jsonc"))
+	) {
+		stack.runtime = "deno";
+	} else {
+		stack.runtime = "node";
+	}
+
+	// Language detection
+	if (existsSync(join(repoRoot, "tsconfig.json")) || allDeps.typescript) {
+		stack.language = "typescript";
+	} else {
+		stack.language = "javascript";
+	}
+
+	// Test runner detection
+	if (stack.runtime === "bun") {
+		stack.testRunner = "bun:test";
+	} else if (allDeps.vitest) {
+		stack.testRunner = "vitest";
+	} else if (allDeps.jest || allDeps["@jest/core"]) {
+		stack.testRunner = "jest";
+	} else if (allDeps.mocha) {
+		stack.testRunner = "mocha";
+	}
+
+	// Linter detection
+	if (allDeps["@biomejs/biome"]) {
+		stack.linter = "biome";
+	} else if (allDeps.eslint) {
+		stack.linter = "eslint";
+	} else if (allDeps.prettier) {
+		stack.linter = "prettier";
+	}
+
+	// Framework detection
+	if (allDeps.next) {
+		stack.framework = "next.js";
+	} else if (allDeps.express) {
+		stack.framework = "express";
+	} else if (allDeps.hono) {
+		stack.framework = "hono";
+	} else if (allDeps.react && !allDeps.next) {
+		stack.framework = "react";
+	} else if (allDeps.vue) {
+		stack.framework = "vue";
+	} else if (allDeps.svelte) {
+		stack.framework = "svelte";
+	}
+
+	return stack;
+}
+
+// ── Templates ────────────────────────────────────────────────────────────────
+
+function buildConstitution(stack: DetectedStack): string {
+	const runtimeLine =
+		stack.runtime !== "unknown"
+			? `- Runtime: ${stack.runtime === "bun" ? "Bun (NOT Node.js)" : stack.runtime}`
+			: "- Runtime: [NEEDS CLARIFICATION]";
+
+	const langLine =
+		stack.language !== "unknown"
+			? `- Language: ${stack.language === "typescript" ? "TypeScript strict mode" : "JavaScript"}`
+			: "- Language: [NEEDS CLARIFICATION]";
+
+	const lintLine =
+		stack.linter !== "unknown"
+			? `- Lint/Format: ${stack.linter}`
+			: "- Lint/Format: [NEEDS CLARIFICATION]";
+
+	const testLine =
+		stack.testRunner !== "unknown"
+			? `- Test: ${stack.testRunner}`
+			: "- Test: [NEEDS CLARIFICATION]";
+
+	const frameworkLine =
+		stack.framework !== "none" ? `- Framework: ${stack.framework}\n` : "";
+
+	return `# Project Constitution
+
+Non-negotiable rules. Injected into every AI call.
+
+## Stack
+${runtimeLine}
+${langLine}
+${lintLine}
+${testLine}
+${frameworkLine}
+## Architecture
+- [NEEDS CLARIFICATION] Define architectural constraints.
+
+## Verification
+- All commits pass: lint + typecheck + test
+- Diff-only: only report findings on changed lines
+
+## Conventions
+- [NEEDS CLARIFICATION] Add project-specific conventions.
+`;
+}
+
+function buildAgentsMd(stack: DetectedStack): string {
+	const runCmd = stack.runtime === "bun" ? "bun" : "npm";
+	const installCmd = stack.runtime === "bun" ? "bun install" : "npm install";
+
+	return `# AGENTS.md
+
+This repo uses [Maina](https://github.com/beeeku/maina) for verification-first development.
+
+## Quick Start
+\`\`\`bash
+${installCmd}
+maina doctor    # check tool health
+maina verify    # run verification pipeline
+maina commit    # verify + commit
+\`\`\`
+
+## Commands
+| Command | Purpose |
+|---------|---------|
+| \`maina commit\` | Verify staged changes and commit |
+| \`maina verify\` | Run full verification pipeline |
+| \`maina context\` | Generate focused codebase context |
+| \`maina plan <name>\` | Create feature with spec/plan/tasks |
+| \`maina analyze\` | Check spec/plan consistency |
+| \`maina review\` | Two-stage code review |
+| \`maina stats\` | Show verification metrics |
+| \`maina doctor\` | Check tool health |
+
+## Config Files
+| File | Purpose | Who Edits |
+|------|---------|-----------|
+| \`.maina/constitution.md\` | Project DNA — stack, rules, gates | Team (stable, rarely changes) |
+| \`AGENTS.md\` | Agent instructions — commands, conventions | Team |
+| \`CLAUDE.md\` | Claude Code specific instructions | Optional, Claude Code users |
+| \`.maina/prompts/*.md\` | Prompt overrides for review/commit/etc | Maina (via \`maina learn\`) |
+
+## Runtime
+- Package manager: \`${runCmd}\`
+- Test: \`${runCmd} test\`
+`;
+}
+
+const REVIEW_PROMPT_TEMPLATE = `# Review Prompt
+
+Review the following code changes for:
+1. Correctness — does the code do what it claims?
+2. Style — does it follow project conventions?
+3. Safety — are there security or performance concerns?
+4. Tests — are changes adequately tested?
+`;
+
+const COMMIT_PROMPT_TEMPLATE = `# Commit Message Prompt
+
+Generate a conventional commit message for the staged changes.
+
+Format: <type>(<scope>): <description>
+
+Types: feat, fix, refactor, test, docs, chore, ci, perf
+`;
+
+function buildCiWorkflow(stack: DetectedStack): string {
+	const isBun = stack.runtime === "bun";
+	const setup = isBun
+		? "      - uses: oven-sh/setup-bun@v2"
+		: "      - uses: actions/setup-node@v4";
+	const install = isBun ? "bun install" : "npm ci";
+	const check = isBun ? "bun run check" : "npm run lint";
+	const typecheck =
+		stack.language === "typescript"
+			? `      - run: ${isBun ? "bun run typecheck" : "npx tsc --noEmit"}\n`
+			: "";
+	const test = isBun ? "bun test" : "npm test";
+
+	return `name: Maina CI
+on: [push, pull_request]
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${setup}
+      - run: ${install}
+      - run: ${check}
+${typecheck}      - run: ${test}
+`;
+}
+
+// ── File Manifest ────────────────────────────────────────────────────────────
+
+interface FileEntry {
+	/** Path relative to repoRoot */
+	relativePath: string;
+	content: string;
+}
+
+function getFileManifest(stack: DetectedStack): FileEntry[] {
+	return [
+		{
+			relativePath: ".maina/constitution.md",
+			content: buildConstitution(stack),
+		},
+		{
+			relativePath: ".maina/prompts/review.md",
+			content: REVIEW_PROMPT_TEMPLATE,
+		},
+		{
+			relativePath: ".maina/prompts/commit.md",
+			content: COMMIT_PROMPT_TEMPLATE,
+		},
+		{
+			relativePath: "AGENTS.md",
+			content: buildAgentsMd(stack),
+		},
+		{
+			relativePath: ".github/workflows/maina-ci.yml",
+			content: buildCiWorkflow(stack),
+		},
+	];
+}
+
+/** Directories to create even if they have no files */
+const EXTRA_DIRS = [".maina/hooks"];
+
+// ── Core Function ────────────────────────────────────────────────────────────
+
+/**
+ * Bootstrap Maina in the given repository root.
+ *
+ * Detects project type from package.json and customizes templates.
+ * Creates `.maina/` directory structure and scaffolds default files.
+ * Never overwrites existing files unless `force: true`.
+ * Returns a report of what was created vs skipped.
+ */
+export async function bootstrap(
+	repoRoot: string,
+	options?: InitOptions,
+): Promise<Result<InitReport>> {
+	const force = options?.force ?? false;
+	const mainaDir = join(repoRoot, ".maina");
+	const created: string[] = [];
+	const skipped: string[] = [];
+
+	try {
+		// Detect project stack from package.json
+		const detectedStack = detectStack(repoRoot);
+
+		// Detect available verification tools on PATH
+		const detectedToolsList = await detectTools();
+
+		// Ensure .maina/ exists
+		mkdirSync(mainaDir, { recursive: true });
+
+		// Create extra directories (e.g. hooks)
+		for (const dir of EXTRA_DIRS) {
+			mkdirSync(join(repoRoot, dir), { recursive: true });
+		}
+
+		// Scaffold each file with stack-aware templates
+		const manifest = getFileManifest(detectedStack);
+		for (const entry of manifest) {
+			const fullPath = join(repoRoot, entry.relativePath);
+			const dirPath = join(fullPath, "..");
+
+			// Ensure parent directory exists
+			mkdirSync(dirPath, { recursive: true });
+
+			if (existsSync(fullPath) && !force) {
+				skipped.push(entry.relativePath);
+			} else {
+				writeFileSync(fullPath, entry.content, "utf-8");
+				created.push(entry.relativePath);
+			}
+		}
+
+		return {
+			ok: true,
+			value: {
+				created,
+				skipped,
+				directory: mainaDir,
+				detectedStack,
+				detectedTools: detectedToolsList,
+			},
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e),
+		};
+	}
+}

package/src/language/__tests__/detect.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "bun:test";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { detectLanguages } from "../detect";
+
+describe("detectLanguages", () => {
+	const testDir = join(import.meta.dir, "__fixtures__/detect");
+
+	function setup(files: Record<string, string>) {
+		if (existsSync(testDir)) rmSync(testDir, { recursive: true });
+		mkdirSync(testDir, { recursive: true });
+		for (const [name, content] of Object.entries(files)) {
+			writeFileSync(join(testDir, name), content);
+		}
+	}
+
+	function cleanup() {
+		if (existsSync(testDir)) rmSync(testDir, { recursive: true });
+	}
+
+	it("should detect TypeScript from tsconfig.json", () => {
+		setup({ "tsconfig.json": "{}" });
+		const result = detectLanguages(testDir);
+		expect(result).toContain("typescript");
+		cleanup();
+	});
+
+	it("should detect Python from pyproject.toml", () => {
+		setup({ "pyproject.toml": "[tool.ruff]" });
+		const result = detectLanguages(testDir);
+		expect(result).toContain("python");
+		cleanup();
+	});
+
+	it("should detect Go from go.mod", () => {
+		setup({ "go.mod": "module example.com/foo" });
+		const result = detectLanguages(testDir);
+		expect(result).toContain("go");
+		cleanup();
+	});
+
+	it("should detect Rust from Cargo.toml", () => {
+		setup({ "Cargo.toml": '[package]\nname = "test"' });
+		const result = detectLanguages(testDir);
+		expect(result).toContain("rust");
+		cleanup();
+	});
+
+	it("should detect multiple languages in polyglot repo", () => {
+		setup({ "tsconfig.json": "{}", "pyproject.toml": "" });
+		const result = detectLanguages(testDir);
+		expect(result).toContain("typescript");
+		expect(result).toContain("python");
+		cleanup();
+	});
+
+	it("should return empty array for unknown project", () => {
+		setup({ "README.md": "hello" });
+		const result = detectLanguages(testDir);
+		expect(result).toHaveLength(0);
+		cleanup();
+	});
+
+	it("should detect Python from requirements.txt", () => {
+		setup({ "requirements.txt": "flask==2.0" });
+		const result = detectLanguages(testDir);
+		expect(result).toContain("python");
+		cleanup();
+	});
+
+	it("should detect Python from setup.py", () => {
+		setup({ "setup.py": "from setuptools import setup" });
+		const result = detectLanguages(testDir);
+		expect(result).toContain("python");
+		cleanup();
+	});
+});

package/src/language/__tests__/profile.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "bun:test";
+import { getProfile, TYPESCRIPT_PROFILE } from "../profile";
+
+describe("LanguageProfile", () => {
+	it("should return TypeScript profile by default", () => {
+		const profile = getProfile("typescript");
+		expect(profile.id).toBe("typescript");
+		expect(profile.extensions).toContain(".ts");
+		expect(profile.extensions).toContain(".tsx");
+		expect(profile.syntaxTool).toBe("biome");
+		expect(profile.commentPrefixes).toContain("//");
+	});
+
+	it("should return Python profile", () => {
+		const profile = getProfile("python");
+		expect(profile.id).toBe("python");
+		expect(profile.extensions).toContain(".py");
+		expect(profile.syntaxTool).toBe("ruff");
+		expect(profile.commentPrefixes).toContain("#");
+	});
+
+	it("should return Go profile", () => {
+		const profile = getProfile("go");
+		expect(profile.id).toBe("go");
+		expect(profile.extensions).toContain(".go");
+		expect(profile.syntaxTool).toBe("go-vet");
+		expect(profile.commentPrefixes).toContain("//");
+	});
+
+	it("should return Rust profile", () => {
+		const profile = getProfile("rust");
+		expect(profile.id).toBe("rust");
+		expect(profile.extensions).toContain(".rs");
+		expect(profile.syntaxTool).toBe("clippy");
+		expect(profile.commentPrefixes).toContain("//");
+	});
+
+	it("should have test file pattern for each language", () => {
+		expect(TYPESCRIPT_PROFILE.testFilePattern.test("app.test.ts")).toBe(true);
+		expect(getProfile("python").testFilePattern.test("test_app.py")).toBe(true);
+		expect(getProfile("go").testFilePattern.test("app_test.go")).toBe(true);
+		expect(getProfile("rust").testFilePattern.test("tests/mod.rs")).toBe(true);
+	});
+
+	it("should have console/print patterns for slop detection", () => {
+		expect(TYPESCRIPT_PROFILE.printPattern.test("console.log('x')")).toBe(true);
+		expect(getProfile("python").printPattern.test("print('x')")).toBe(true);
+		expect(getProfile("go").printPattern.test("fmt.Println(x)")).toBe(true);
+		expect(getProfile("rust").printPattern.test("println!(x)")).toBe(true);
+	});
+});

package/src/language/detect.ts

@@ -0,0 +1,70 @@
+/**
+ * Language Detection — detects project languages from marker files.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { LanguageId } from "./profile";
+
+const LANGUAGE_MARKERS: Record<LanguageId, string[]> = {
+	typescript: ["tsconfig.json", "tsconfig.build.json"],
+	python: [
+		"pyproject.toml",
+		"setup.py",
+		"setup.cfg",
+		"requirements.txt",
+		"Pipfile",
+	],
+	go: ["go.mod", "go.sum"],
+	rust: ["Cargo.toml", "Cargo.lock"],
+};
+
+/**
+ * Detect languages present in a project directory by checking for marker files.
+ * Returns an array of detected LanguageIds.
+ * Also detects TypeScript from package.json "typescript" dependency.
+ */
+export function detectLanguages(cwd: string): LanguageId[] {
+	const detected: LanguageId[] = [];
+
+	for (const [lang, markers] of Object.entries(LANGUAGE_MARKERS) as [
+		LanguageId,
+		string[],
+	][]) {
+		for (const marker of markers) {
+			if (existsSync(join(cwd, marker))) {
+				detected.push(lang);
+				break;
+			}
+		}
+	}
+
+	// Also check package.json for TypeScript dependency
+	if (!detected.includes("typescript")) {
+		const pkgPath = join(cwd, "package.json");
+		if (existsSync(pkgPath)) {
+			try {
+				const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+				const allDeps = {
+					...pkg.dependencies,
+					...pkg.devDependencies,
+				};
+				if (allDeps?.typescript) {
+					detected.push("typescript");
+				}
+			} catch {
+				// Malformed package.json — skip
+			}
+		}
+	}
+
+	return detected;
+}
+
+/**
+ * Get the primary (first detected) language, or "typescript" as fallback.
+ */
+export function getPrimaryLanguage(cwd: string): LanguageId {
+	const languages = detectLanguages(cwd);
+	return languages[0] ?? "typescript";
+}

package/src/language/profile.ts

@@ -0,0 +1,110 @@
+/**
+ * Language Profiles — maps each supported language to its tools,
+ * file patterns, and slop detection rules.
+ */
+
+export type LanguageId = "typescript" | "python" | "go" | "rust";
+
+export interface LanguageProfile {
+	id: LanguageId;
+	displayName: string;
+	extensions: string[];
+	syntaxTool: string;
+	syntaxArgs: (files: string[], cwd: string) => string[];
+	commentPrefixes: string[];
+	testFilePattern: RegExp;
+	printPattern: RegExp;
+	lintIgnorePattern: RegExp;
+	importPattern: RegExp;
+	fileGlobs: string[];
+}
+
+export const TYPESCRIPT_PROFILE: LanguageProfile = {
+	id: "typescript",
+	displayName: "TypeScript",
+	extensions: [".ts", ".tsx", ".js", ".jsx"],
+	syntaxTool: "biome",
+	syntaxArgs: (files, _cwd) => [
+		"biome",
+		"check",
+		"--reporter=json",
+		"--no-errors-on-unmatched",
+		"--colors=off",
+		...files,
+	],
+	commentPrefixes: ["//", "/*"],
+	testFilePattern: /\.(test|spec)\.[jt]sx?$/,
+	printPattern: /console\.(log|warn|error|debug|info)\s*\(/,
+	lintIgnorePattern: /@ts-ignore|@ts-expect-error|noinspection/,
+	importPattern:
+		/^import\s+(?:type\s+)?(?:\{[^}]+\}|\*\s+as\s+\w+|\w+)\s+from\s+["']([^"']+)["']/,
+	fileGlobs: ["*.ts", "*.tsx", "*.js", "*.jsx"],
+};
+
+export const PYTHON_PROFILE: LanguageProfile = {
+	id: "python",
+	displayName: "Python",
+	extensions: [".py", ".pyi"],
+	syntaxTool: "ruff",
+	syntaxArgs: (files, _cwd) => [
+		"ruff",
+		"check",
+		"--output-format=json",
+		...files,
+	],
+	commentPrefixes: ["#"],
+	testFilePattern: /(?:^test_|_test\.py$|tests\/)/,
+	printPattern: /\bprint\s*\(/,
+	lintIgnorePattern: /# type:\s*ignore|# noqa|# pragma:\s*no cover/,
+	importPattern: /^(?:from\s+(\S+)\s+import|import\s+(\S+))/,
+	fileGlobs: ["*.py", "*.pyi"],
+};
+
+export const GO_PROFILE: LanguageProfile = {
+	id: "go",
+	displayName: "Go",
+	extensions: [".go"],
+	syntaxTool: "go-vet",
+	syntaxArgs: (files, _cwd) => ["go", "vet", ...files],
+	commentPrefixes: ["//"],
+	testFilePattern: /_test\.go$/,
+	printPattern: /fmt\.Print(?:ln|f)?\s*\(/,
+	lintIgnorePattern: /\/\/\s*nolint/,
+	importPattern: /^\s*"([^"]+)"/,
+	fileGlobs: ["*.go"],
+};
+
+export const RUST_PROFILE: LanguageProfile = {
+	id: "rust",
+	displayName: "Rust",
+	extensions: [".rs"],
+	syntaxTool: "clippy",
+	syntaxArgs: (files, _cwd) => [
+		"cargo",
+		"clippy",
+		"--message-format=json",
+		"--",
+		...files,
+	],
+	commentPrefixes: ["//"],
+	testFilePattern: /(?:tests\/|_test\.rs$|#\[cfg\(test\)\])/,
+	printPattern: /(?:println!|print!|eprintln!|eprint!)\s*\(/,
+	lintIgnorePattern: /#\[allow\(|#!\[allow\(/,
+	importPattern: /^use\s+(\S+)/,
+	fileGlobs: ["*.rs"],
+};
+
+const PROFILES: Record<LanguageId, LanguageProfile> = {
+	typescript: TYPESCRIPT_PROFILE,
+	python: PYTHON_PROFILE,
+	go: GO_PROFILE,
+	rust: RUST_PROFILE,
+};
+
+export function getProfile(id: LanguageId): LanguageProfile {
+	return PROFILES[id];
+}
+
+export function getSupportedLanguages(): LanguageId[] {
+	return Object.keys(PROFILES) as LanguageId[];
+}