@getmikk/core 1.7.1 → 1.8.1

package/src/parser/typescript/ts-extractor.ts

@@ -3,7 +3,7 @@ import type { ParsedFunction, ParsedClass, ParsedImport, ParsedExport, ParsedPar
 import { hashContent } from '../../hash/file-hasher.js'
 
 /**
- * TypeScript AST extractor — walks the TypeScript AST using the TS Compiler API
+ * TypeScript AST extractor walks the TypeScript AST using the TS Compiler API
  * and extracts functions, classes, imports, exports and call relationships.
  */
 export class TypeScriptExtractor {
@@ -286,7 +286,7 @@ export class TypeScriptExtractor {
                                 middlewares.push(arg.text)
                             }
                         } else if (ts.isCallExpression(arg)) {
-                            // e.g. upload.single("file") — middleware call
+                            // e.g. upload.single("file") middleware call
                             middlewares.push(arg.expression.getText(this.sourceFile))
                         } else if (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg)) {
                             handler = 'anonymous'
@@ -309,7 +309,7 @@ export class TypeScriptExtractor {
         return routes
     }
 
-    // ─── Protected Helpers ─────────────────────────────────────
+    // Protected Helpers ------------------------------------------------------
 
     protected parseFunctionDeclaration(node: ts.FunctionDeclaration): ParsedFunction {
         const name = node.name!.text
@@ -511,11 +511,11 @@ export class TypeScriptExtractor {
                 if (ts.isIdentifier(callee)) {
                     calls.push(callee.text)
                 } else if (ts.isPropertyAccessExpression(callee)) {
-                    // e.g., obj.method() — we capture the full dotted name
+                    // e.g., obj.method() we capture the full dotted name
                     calls.push(callee.getText(this.sourceFile))
                 }
             }
-            // Track constructor calls: new Foo(...) → "Foo"
+            // Track constructor calls: new Foo(...) -> "Foo"
             if (ts.isNewExpression(n)) {
                 const callee = n.expression
                 if (ts.isIdentifier(callee)) {
@@ -547,12 +547,12 @@ export class TypeScriptExtractor {
                 }
 
                 // Skip divider lines (lines with 3+ repeated special characters)
-                if (/^[─\-_=\*]{3,}$/.test(clean)) continue
+                if (/^[\-_=\*]{3,}$/.test(clean)) continue
 
                 if (clean) meaningfulLines.push(clean)
             }
 
-            // Return the first meaningful line — in JSDoc, the first line is the summary.
+            // Return the first meaningful line in JSDoc, the first line is the summary.
             const fromComment = meaningfulLines.length > 0 ? meaningfulLines[0].split('\n')[0].trim() : ''
             if (fromComment) return fromComment
         }
@@ -662,10 +662,10 @@ export class TypeScriptExtractor {
         if (modifiers) {
             for (const decorator of modifiers) {
                 if (ts.isCallExpression(decorator.expression)) {
-                    // @Injectable() — decorator with arguments
+                    // @Injectable() decorator with arguments
                     decorators.push(decorator.expression.expression.getText(this.sourceFile))
                 } else if (ts.isIdentifier(decorator.expression)) {
-                    // @Sealed — decorator without arguments
+                    // @Sealed decorator without arguments
                     decorators.push(decorator.expression.text)
                 }
             }
@@ -694,7 +694,7 @@ export class TypeScriptExtractor {
         return this.sourceFile.getLineAndCharacterOfPosition(pos).line + 1
     }
 
-    /** Walk the top-level children of a node (non-recursive — callbacks decide depth) */
+    /** Walk the top-level children of a node (non-recursive callbacks decide depth) */
     protected walkNode(node: ts.Node, callback: (node: ts.Node) => void): void {
         ts.forEachChild(node, (child) => {
             callback(child)
@@ -702,15 +702,15 @@ export class TypeScriptExtractor {
     }
 }
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
+// 
 
 /**
  * Derive a human-readable purpose sentence from a camelCase/PascalCase identifier.
  * Examples:
- *   validateJwtToken   → "Validate jwt token"
- *   buildGraphFromLock → "Build graph from lock"
- *   UserRepository     → "User repository"
- *   parseFiles         → "Parse files"
+ *   validateJwtToken   -> "Validate jwt token"
+ *   buildGraphFromLock -> "Build graph from lock"
+ *   UserRepository     -> "User repository"
+ *   parseFiles         -> "Parse files"
  */
 function normalizeTypeAnnotation(type: string): string {
     return type.replace(/\s*\n\s*/g, ' ').replace(/\s{2,}/g, ' ').trim()

package/src/parser/typescript/ts-parser.ts

@@ -12,7 +12,7 @@ import type { ParsedFile } from '../types.js'
  */
 export class TypeScriptParser extends BaseParser {
     /** Parse a single TypeScript file */
-    parse(filePath: string, content: string): ParsedFile {
+    async parse(filePath: string, content: string): Promise<ParsedFile> {
         const extractor = new TypeScriptExtractor(filePath, content)
         const functions = extractor.extractFunctions()
         const classes = extractor.extractClasses()

package/src/parser/typescript/ts-resolver.ts

@@ -33,7 +33,7 @@ export class TypeScriptResolver {
     private resolvePath(source: string, fromFile: string, allProjectFiles: string[]): string {
         let resolvedSource = source
 
-        // 1. Handle path aliases: @/utils/jwt → src/utils/jwt
+        // 1. Handle path aliases: @/utils/jwt -> src/utils/jwt
         for (const [alias, targets] of Object.entries(this.aliases)) {
             const aliasPrefix = alias.replace('/*', '')
             if (source.startsWith(aliasPrefix)) {
@@ -57,7 +57,7 @@ export class TypeScriptResolver {
         resolved = resolved.replace(/\\/g, '/')
 
         // 3. Try to find exact match with extensions
-        const extensions = ['.ts', '.tsx', '/index.ts', '/index.tsx']
+        const extensions = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '/index.ts', '/index.tsx', '/index.js', '/index.jsx']
 
         // If the path already has an extension, return it
         if (resolved.endsWith('.ts') || resolved.endsWith('.tsx')) {

package/src/search/bm25.ts

@@ -0,0 +1,206 @@
+/**
+ * BM25 Search Index — Okapi BM25 ranking for function search.
+ *
+ * BM25 is a probabilistic ranking function that considers:
+ *   - Term frequency (TF) — how often query terms appear in a document
+ *   - Inverse document frequency (IDF) — rarity of terms across all documents
+ *   - Document length normalization — penalizes very long documents
+ *
+ * This gives dramatically better search results than naive substring matching.
+ * Combined with substring matching via Reciprocal Rank Fusion (RRF), it
+ * produces GitNexus-quality hybrid search.
+ *
+ * @module
+ */
+
+/** A searchable document with an ID and tokenized content */
+interface BM25Document {
+    id: string
+    tokens: string[]
+    length: number
+}
+
+/** A single search result with score */
+export interface BM25Result {
+    id: string
+    score: number
+}
+
+/** BM25 parameters */
+const K1 = 1.2    // Term frequency saturation — higher = more weight on TF
+const B = 0.75    // Document length normalization — 0 = no normalization, 1 = full
+
+/**
+ * In-memory BM25 index. Build once, query many times.
+ *
+ * Usage:
+ *   const index = new BM25Index()
+ *   index.addDocument('fn:auth.ts:verify', ['verify', 'token', 'jwt', 'auth'])
+ *   index.addDocument('fn:user.ts:getUser', ['get', 'user', 'fetch', 'database'])
+ *   const results = index.search('verify jwt token')
+ */
+export class BM25Index {
+    private documents: BM25Document[] = []
+    private documentFrequency = new Map<string, number>()  // term → how many docs contain it
+    private avgDocLength = 0
+
+    /** Clear the index */
+    clear(): void {
+        this.documents = []
+        this.documentFrequency.clear()
+        this.avgDocLength = 0
+    }
+
+    /** Add a document with pre-tokenized terms */
+    addDocument(id: string, tokens: string[]): void {
+        const normalizedTokens = tokens.map(t => t.toLowerCase())
+        this.documents.push({ id, tokens: normalizedTokens, length: normalizedTokens.length })
+
+        // Count unique terms for IDF
+        const uniqueTerms = new Set(normalizedTokens)
+        for (const term of uniqueTerms) {
+            this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1)
+        }
+
+        // Recompute average document length
+        this.avgDocLength = this.documents.reduce((sum, d) => sum + d.length, 0) / this.documents.length
+    }
+
+    /** Search the index and return ranked results */
+    search(query: string, limit = 20): BM25Result[] {
+        const queryTokens = tokenize(query)
+        if (queryTokens.length === 0 || this.documents.length === 0) return []
+
+        const N = this.documents.length
+        const results: BM25Result[] = []
+
+        for (const doc of this.documents) {
+            let score = 0
+
+            for (const term of queryTokens) {
+                const df = this.documentFrequency.get(term) ?? 0
+                if (df === 0) continue
+
+                // IDF: log((N - df + 0.5) / (df + 0.5) + 1)
+                const idf = Math.log((N - df + 0.5) / (df + 0.5) + 1)
+
+                // TF in this document
+                let tf = 0
+                for (const t of doc.tokens) {
+                    if (t === term) tf++
+                }
+
+                // BM25 score component
+                const tfNorm = (tf * (K1 + 1)) / (tf + K1 * (1 - B + B * (doc.length / this.avgDocLength)))
+                score += idf * tfNorm
+            }
+
+            if (score > 0) {
+                results.push({ id: doc.id, score })
+            }
+        }
+
+        // Sort by score descending
+        results.sort((a, b) => b.score - a.score)
+        return results.slice(0, limit)
+    }
+}
+
+/**
+ * Reciprocal Rank Fusion — merge multiple ranked lists into one.
+ *
+ * RRF is used by GitNexus to combine BM25 + semantic search. We use it
+ * to combine BM25 + substring match results.
+ *
+ * Formula: score = Σ 1 / (k + rank_i)  where k = 60 (standard)
+ */
+export function reciprocalRankFusion(
+    ...rankedLists: { id: string; score: number }[][]
+): { id: string; score: number }[] {
+    const K = 60 // Standard RRF constant
+    const scores = new Map<string, number>()
+
+    for (const list of rankedLists) {
+        for (let rank = 0; rank < list.length; rank++) {
+            const item = list[rank]
+            scores.set(item.id, (scores.get(item.id) ?? 0) + 1 / (K + rank + 1))
+        }
+    }
+
+    return [...scores.entries()]
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score)
+}
+
+/**
+ * Tokenize a string into searchable terms.
+ *
+ * Handles:
+ *   - camelCase splitting: "parseFiles" → ["parse", "files"]
+ *   - snake_case splitting: "parse_files" → ["parse", "files"]
+ *   - kebab-case splitting: "parse-files" → ["parse", "files"]
+ *   - Lowercasing
+ *   - Minimum 2-char filter
+ */
+export function tokenize(text: string): string[] {
+    const tokens: string[] = []
+
+    // Split on non-alphanumeric chars
+    const words = text.split(/[^a-zA-Z0-9]+/).filter(Boolean)
+
+    for (const word of words) {
+        // Split camelCase: "parseFiles" → ["parse", "Files"]
+        const camelParts = word.replace(/([a-z])([A-Z])/g, '$1 $2').split(' ')
+
+        for (const part of camelParts) {
+            const lower = part.toLowerCase()
+            if (lower.length >= 2) {
+                tokens.push(lower)
+            }
+        }
+    }
+
+    return tokens
+}
+
+/**
+ * Build search tokens for a function — combines name, purpose, params, file path.
+ * This gives BM25 rich content to index beyond just the function name.
+ */
+export function buildFunctionTokens(fn: {
+    name: string
+    file: string
+    purpose?: string
+    params?: { name: string; type: string }[]
+    returnType?: string
+}): string[] {
+    const parts: string[] = []
+
+    // Function name tokens (highest signal)
+    parts.push(...tokenize(fn.name))
+    parts.push(...tokenize(fn.name)) // Double-weight the name
+
+    // File path tokens
+    const filename = fn.file.split('/').pop() ?? fn.file
+    parts.push(...tokenize(filename.replace(/\.[^.]+$/, ''))) // Strip extension
+
+    // Purpose tokens
+    if (fn.purpose) {
+        parts.push(...tokenize(fn.purpose))
+    }
+
+    // Parameter name tokens
+    if (fn.params) {
+        for (const p of fn.params) {
+            parts.push(...tokenize(p.name))
+            parts.push(...tokenize(p.type))
+        }
+    }
+
+    // Return type tokens
+    if (fn.returnType) {
+        parts.push(...tokenize(fn.returnType))
+    }
+
+    return parts
+}

package/src/search/index.ts

@@ -0,0 +1,3 @@
+// @getmikk/core search module
+export { BM25Index, reciprocalRankFusion, tokenize, buildFunctionTokens } from './bm25.js'
+export type { BM25Result } from './bm25.js'

package/src/utils/fs.ts

@@ -2,27 +2,27 @@ import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
 import fg from 'fast-glob'
 
-// ─── Well-known patterns for schema/config/route files ─────────────
+// --- Well-known patterns for schema/config/route files ---------------------
 // These are structural files an AI agent needs but aren't source code.
 // Mikk auto-discovers them so the AI doesn't have to explore the filesystem.
-// Patterns are language-agnostic — unused patterns simply return zero matches.
+// Patterns are language-agnostic -- unused patterns simply return zero matches.
 const CONTEXT_FILE_PATTERNS = [
-    // Data models / schemas — JS/TS
+    // Data models / schemas -- JS/TS
     '**/prisma/schema.prisma',
     '**/drizzle/**/*.ts',
     '**/schema/**/*.{ts,js,graphql,gql,sql}',
     '**/models/**/*.{ts,js}',
     '**/*.schema.{ts,js}',
     '**/*.model.{ts,js}',
-    // Data models / schemas — Python
+    // Data models / schemas -- Python
     '**/models.py',
     '**/schemas.py',
     '**/serializers.py',
     '**/models/**/*.py',
-    // Data models / schemas — Ruby
+    // Data models / schemas -- Ruby
     '**/app/models/**/*.rb',
     '**/db/schema.rb',
-    // Data models / schemas — Go / Rust / Java / PHP
+    // Data models / schemas -- Go / Rust / Java / PHP
     '**/models/*.go',
     '**/*_model.go',
     '**/schema.rs',
@@ -42,7 +42,7 @@ const CONTEXT_FILE_PATTERNS = [
     // Route definitions
     '**/routes/**/*.{ts,js}',
     '**/router.{ts,js}',
-    // Database migrations (latest only) — multi-language
+    // Database migrations (latest only) -- multi-language
     '**/migrations/**/migration.sql',
     '**/db/migrate/**/*.rb',
     '**/alembic/**/*.py',
@@ -56,7 +56,7 @@ const CONTEXT_FILE_PATTERNS = [
     '**/Dockerfile',
     '.env.example',
     '.env.local.example',
-    // Schema definitions — general
+    // Schema definitions -- general
     '**/schema.{yaml,yml,json}',
     '**/*.avsc',
     '**/*.thrift',
@@ -115,10 +115,10 @@ export interface ContextFile {
     size: number
 }
 
-/** Maximum size (in bytes) for a single context file — skip huge files */
+/** Maximum size (in bytes) for a single context file -- skip huge files */
 const MAX_CONTEXT_FILE_SIZE = 50_000 // ~50KB
 
-// ─── .mikkignore support ───────────────────────────────────────────
+// --- .mikkignore support ----------------------------------------------------
 
 /**
  * Read a .mikkignore file from the project root and parse it into
@@ -138,7 +138,7 @@ export async function readMikkIgnore(projectRoot: string): Promise<string[]> {
         const content = await fs.readFile(ignorePath, 'utf-8')
         return parseMikkIgnore(content)
     } catch {
-        return [] // no .mikkignore — that's fine
+        return [] // no .mikkignore -- that's fine
     }
 }
 
@@ -151,24 +151,24 @@ export function parseMikkIgnore(content: string): string[] {
         if (line.startsWith('!')) continue // negations not yet supported
 
         const isDir = line.endsWith('/')
-        // If pattern has no slash (ignoring trailing slash), match anywhere → prepend **/
+        // If pattern has no slash (ignoring trailing slash), match anywhere -> prepend **/
         const stripped = isDir ? line.slice(0, -1) : line
         const hasSlash = stripped.includes('/')
 
         if (!hasSlash) {
             if (isDir) {
-                // e.g. "dist/" → "**/{dist}/**" — ignore the directory and everything within it
+                // e.g. "dist/" -> "**/{dist}/**" -- ignore the directory and everything within it
                 patterns.push(`**/${stripped}/**`)
             } else {
-                // e.g. "*.svg" → "**/*.svg"
+                // e.g. "*.svg" -> "**/*.svg"
                 patterns.push(`**/${line}`)
             }
         } else {
             if (isDir) {
-                // e.g. "packages/*/tests/" → "packages/*/tests/**"
+                // e.g. "packages/*/tests/" -> "packages/*/tests/**"
                 patterns.push(`${stripped}/**`)
             } else {
-                // e.g. "components/ui/**" — relative to root, already valid
+                // e.g. "components/ui/**" -- relative to root, already valid
                 patterns.push(line)
             }
         }
@@ -181,7 +181,7 @@ export function parseMikkIgnore(content: string): string[] {
  * the project's data models, API definitions, route structure, and config.
  *
  * This is technology-agnostic: it works for Prisma, Drizzle, GraphQL, SQL,
- * Protobuf, Docker, OpenAPI, and more — anything with a well-known file pattern.
+ * Protobuf, Docker, OpenAPI, and more -- anything with a well-known file pattern.
  */
 export async function discoverContextFiles(projectRoot: string): Promise<ContextFile[]> {
     const mikkIgnore = await readMikkIgnore(projectRoot)
@@ -194,7 +194,7 @@ export async function discoverContextFiles(projectRoot: string): Promise<Context
 
     const normalised = files.map(f => f.replace(/\\/g, '/'))
 
-    // Deduplicate — some patterns overlap (e.g. models/*.ts also matched by source discovery)
+    // Deduplicate -- some patterns overlap (e.g. models/*.ts also matched by source discovery)
     const unique = [...new Set(normalised)]
 
     const results: ContextFile[] = []
@@ -211,7 +211,7 @@ export async function discoverContextFiles(projectRoot: string): Promise<Context
 
             results.push({ path: relPath, content, type, size: stat.size })
         } catch {
-            // File unreadable — skip
+            // File unreadable -- skip
         }
     }
 
@@ -229,7 +229,7 @@ export async function discoverContextFiles(projectRoot: string): Promise<Context
     results.sort((a, b) => priority[a.type] - priority[b.type])
 
     // If we have a schema file (e.g. prisma/schema.prisma), the migrations
-    // are redundant — they represent historical deltas, not the current state.
+    // are redundant -- they represent historical deltas, not the current state.
     // Including them wastes AI tokens and can be actively misleading.
     const hasSchema = results.some(f => f.type === 'schema')
     if (hasSchema) {
@@ -242,7 +242,7 @@ export async function discoverContextFiles(projectRoot: string): Promise<Context
 /** Infer the context file's category from its path */
 function inferContextFileType(filePath: string): ContextFileType {
     const lower = filePath.toLowerCase()
-    // Schema files — multi-language
+    // Schema files -- multi-language
     if (lower.includes('prisma/schema') || lower.endsWith('.prisma')) return 'schema'
     if (lower.includes('drizzle/') || lower.includes('.schema.')) return 'schema'
     if (lower.endsWith('.graphql') || lower.endsWith('.gql')) return 'schema'
@@ -251,12 +251,12 @@ function inferContextFileType(filePath: string): ContextFileType {
     if (lower.endsWith('schema.rs')) return 'schema'
     if (lower.endsWith('.proto')) return 'api-spec'
     if (lower.includes('openapi') || lower.includes('swagger')) return 'api-spec'
-    // Migrations — multi-language
+    // Migrations -- multi-language
     if (lower.endsWith('.sql') && lower.includes('migration')) return 'migration'
     if (lower.includes('db/migrate/')) return 'migration'
     if (lower.includes('alembic/')) return 'migration'
     if (lower.endsWith('.sql')) return 'schema'
-    // Models — any language
+    // Models -- any language
     if (lower.includes('/models/') || lower.includes('/model/')) return 'model'
     if (lower.endsWith('.model.ts') || lower.endsWith('.model.js') || lower.endsWith('.model.go')) return 'model'
     if (lower.endsWith('models.py') || lower.endsWith('serializers.py') || lower.endsWith('schemas.py')) return 'model'
@@ -286,7 +286,7 @@ export async function detectProjectLanguage(projectRoot: string): Promise<Projec
         const matches = await fg(pattern, { cwd: projectRoot, onlyFiles: true, deep: 1 })
         return matches.length > 0
     }
-    // Check in priority order — most specific first
+    // Check in priority order -- most specific first
     if (await exists('tsconfig.json') || await hasGlob('tsconfig.*.json')) return 'typescript'
     if (await exists('Cargo.toml')) return 'rust'
     if (await exists('go.mod')) return 'go'
@@ -432,7 +432,7 @@ export async function setupMikkDirectory(projectRoot: string): Promise<void> {
     }
 }
 
-// ─── .mikkignore auto-generation ────────────────────────────────────
+// --- .mikkignore auto-generation --------------------------------------------
 
 /** Default ignore patterns shared across all languages */
 const COMMON_IGNORE_PATTERNS = [
@@ -520,7 +520,7 @@ const LANGUAGE_IGNORE_TEMPLATES: Record<ProjectLanguage, string[]> = {
         '',
     ],
     rust: [
-        '# Test files (inline tests are kept — only test binaries excluded)',
+        '# Test files (inline tests are kept -- only test binaries excluded)',
         'target/',
         'tests/fixtures/',
         '',
@@ -589,7 +589,7 @@ export async function generateMikkIgnore(projectRoot: string, language: ProjectL
     if (await fileExists(ignorePath)) return false
 
     const lines: string[] = [
-        '# .mikkignore — files/directories Mikk should skip during analysis',
+        '# .mikkignore -- files/directories Mikk should skip during analysis',
         '# Syntax: gitignore-style patterns. Lines starting with # are comments.',
         '# Paths without / match anywhere. Paths with / are relative to project root.',
         '',
@@ -607,7 +607,7 @@ export async function generateMikkIgnore(projectRoot: string, language: ProjectL
             : pkg.workspaces?.packages
 
         if (workspaces && workspaces.length > 0) {
-            lines.push('# Monorepo — test/fixture directories across all packages')
+            lines.push('# Monorepo -- test/fixture directories across all packages')
             for (const ws of workspaces) {
                 // ws is like "packages/*" or "apps/*"
                 const base = ws.replace(/\/?\*$/, '')
@@ -618,13 +618,13 @@ export async function generateMikkIgnore(projectRoot: string, language: ProjectL
             lines.push('')
         }
     } catch {
-        // No package.json or not JSON — skip monorepo detection
+        // No package.json or not JSON -- skip monorepo detection
     }
 
     // Turbo / pnpm workspace detection
     try {
         const turboRaw = await fs.readFile(path.join(projectRoot, 'turbo.json'), 'utf-8')
-        // turbo.json exists — likely a monorepo already handled above
+        // turbo.json exists -- likely a monorepo already handled above
         void turboRaw
     } catch {
         // not a turbo project
@@ -639,7 +639,7 @@ export async function generateMikkIgnore(projectRoot: string, language: ProjectL
             .map(l => l.replace(/^\s*-\s*['"]?/, '').replace(/['"]?\s*$/, '').trim())
 
         if (packageLines.length > 0 && !lines.some(l => l.includes('Monorepo'))) {
-            lines.push('# Monorepo (pnpm) — test/fixture directories across all packages')
+            lines.push('# Monorepo (pnpm) -- test/fixture directories across all packages')
             for (const ws of packageLines) {
                 const base = ws.replace(/\/?\*$/, '')
                 lines.push(`${base}/*/tests/`)
@@ -655,3 +655,67 @@ export async function generateMikkIgnore(projectRoot: string, language: ProjectL
     await fs.writeFile(ignorePath, lines.join('\n'), 'utf-8')
     return true
 }
+
+/**
+ * Automatically add .mikk/ to the project's .gitignore file if it exists.
+ * Returns true if the file was modified, false otherwise.
+ */
+export async function updateGitIgnore(projectRoot: string): Promise<boolean> {
+    const gitIgnorePath = path.join(projectRoot, '.gitignore')
+    
+    // If no .gitignore, we don't create one (don't assume the project uses Git)
+    if (!await fileExists(gitIgnorePath)) return false
+
+    try {
+        const content = await fs.readFile(gitIgnorePath, 'utf-8')
+        const lines = content.split('\n')
+
+        // Check if already ignored
+        const alreadyIgnored = lines.some(line => {
+            const trimmed = line.trim()
+            return trimmed === '.mikk' || trimmed === '.mikk/' || trimmed === '**/.mikk/**'
+        })
+
+        if (alreadyIgnored) return false
+
+        // Append to .gitignore
+        const newContent = content.endsWith('\n') 
+            ? `${content}\n# Mikk internal\n.mikk/\n`
+            : `${content}\n\n# Mikk internal\n.mikk/\n`
+        
+        await fs.writeFile(gitIgnorePath, newContent, 'utf-8')
+        return true
+    } catch {
+        return false
+    }
+}
+
+/**
+ * Remove Mikk entries from .gitignore.
+ */
+export async function cleanupGitIgnore(projectRoot: string): Promise<boolean> {
+    const gitIgnorePath = path.join(projectRoot, '.gitignore')
+    if (!await fileExists(gitIgnorePath)) return false
+
+    try {
+        const content = await fs.readFile(gitIgnorePath, 'utf-8')
+        const lines = content.split('\n')
+        
+        let modified = false
+        const filtered = lines.filter(line => {
+            const trimmed = line.trim()
+            const isMikkEntry = trimmed === '.mikk' || trimmed === '.mikk/' || trimmed === '**/.mikk/**' || trimmed === '# Mikk internal'
+            if (isMikkEntry) modified = true
+            return !isMikkEntry
+        })
+
+        if (!modified) return false
+
+        // Joins lines and trim trailing newlines to avoid growing whitespace
+        const newContent = filtered.join('\n').trim() + '\n'
+        await fs.writeFile(gitIgnorePath, newContent, 'utf-8')
+        return true
+    } catch {
+        return false
+    }
+}