@adhisang/minecraft-modding-mcp 1.0.0

package/dist/storage/files-repo.js

@@ -0,0 +1,437 @@
+import { createHash } from "node:crypto";
+import { log } from "../logger.js";
+function buildCursor(sortKey) {
+    return Buffer.from(JSON.stringify({ sortKey }), "utf8").toString("base64");
+}
+function parseCursor(cursor) {
+    if (!cursor) {
+        return undefined;
+    }
+    try {
+        const decoded = Buffer.from(cursor, "base64").toString("utf8");
+        const parsed = JSON.parse(decoded);
+        if (typeof parsed.sortKey !== "string") {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        log("warn", "storage.files.invalid_list_cursor", { cursor });
+        return undefined;
+    }
+}
+function buildSearchCursor(score, filePath) {
+    return Buffer.from(JSON.stringify({ score, filePath }), "utf8").toString("base64");
+}
+function parseSearchCursor(cursor) {
+    if (!cursor) {
+        return undefined;
+    }
+    try {
+        const decoded = Buffer.from(cursor, "base64").toString("utf8");
+        const parsed = JSON.parse(decoded);
+        if (typeof parsed.score !== "number" || typeof parsed.filePath !== "string") {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        log("warn", "storage.files.invalid_search_cursor", { cursor });
+        return undefined;
+    }
+}
+function nextCursorFromRows(rows) {
+    if (rows.length === 0) {
+        return undefined;
+    }
+    const last = rows[rows.length - 1];
+    return buildCursor(last.file_path);
+}
+function compareSearchOrdering(left, right) {
+    if (right.score !== left.score) {
+        return right.score - left.score;
+    }
+    return left.filePath.localeCompare(right.filePath);
+}
+function isAfterSearchCursor(hit, cursor) {
+    if (hit.score < cursor.score) {
+        return true;
+    }
+    if (hit.score > cursor.score) {
+        return false;
+    }
+    return hit.filePath.localeCompare(cursor.filePath) > 0;
+}
+function buildPreview(content, query) {
+    const normalizedQuery = query.toLowerCase();
+    const normalizedContent = content.toLowerCase();
+    const index = normalizedContent.indexOf(normalizedQuery);
+    if (index < 0) {
+        return content.slice(0, 120);
+    }
+    const start = Math.max(0, index - 24);
+    const end = Math.min(content.length, index + normalizedQuery.length + 24);
+    const prefix = start > 0 ? "..." : "";
+    const suffix = end < content.length ? "..." : "";
+    return `${prefix}${content.slice(start, end)}${suffix}`.replace(/\s+/g, " ").trim();
+}
+export class FilesRepo {
+    db;
+    deleteStmt;
+    insertFilesStmt;
+    insertFtsStmt;
+    deleteFtsStmt;
+    getContentStmt;
+    listStmt;
+    listRowsStmt;
+    searchPathStmt;
+    searchFtsStmt;
+    getByPathsStmtCache = new Map();
+    constructor(db) {
+        this.db = db;
+        this.deleteStmt = this.db.prepare(`
+      DELETE FROM files WHERE artifact_id = ?
+    `);
+        this.deleteFtsStmt = this.db.prepare(`
+      DELETE FROM files_fts WHERE artifact_id = ?
+    `);
+        this.insertFilesStmt = this.db.prepare(`
+      INSERT INTO files (artifact_id, file_path, content, content_bytes, content_hash)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+        this.insertFtsStmt = this.db.prepare(`
+      INSERT INTO files_fts (artifact_id, file_path, content)
+      VALUES (?, ?, ?)
+    `);
+        this.getContentStmt = this.db.prepare(`
+      SELECT artifact_id, file_path, content, content_bytes, content_hash
+      FROM files
+      WHERE artifact_id = ? AND file_path = ?
+      LIMIT 1
+    `);
+        this.listStmt = this.db.prepare(`
+      SELECT artifact_id, file_path
+      FROM files
+      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? || '%')
+      ORDER BY file_path ASC
+      LIMIT ?
+    `);
+        this.listRowsStmt = this.db.prepare(`
+      SELECT artifact_id, file_path, content, content_bytes, content_hash
+      FROM files
+      WHERE artifact_id = ? AND file_path > ? AND (? IS NULL OR file_path LIKE ? || '%')
+      ORDER BY file_path ASC
+      LIMIT ?
+    `);
+        this.searchPathStmt = this.db.prepare(`
+      SELECT file_path
+      FROM files
+      WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\'
+      ORDER BY file_path ASC
+      LIMIT ?
+    `);
+        this.searchFtsStmt = this.db.prepare(`
+      SELECT file_path, rank
+      FROM files_fts
+      WHERE artifact_id = ? AND files_fts MATCH ?
+      ORDER BY rank
+      LIMIT ?
+    `);
+    }
+    clearFilesForArtifact(artifactId) {
+        this.deleteStmt.run([artifactId]);
+        this.deleteFtsStmt.run([artifactId]);
+    }
+    insertFilesForArtifact(artifactId, files) {
+        for (const file of files) {
+            const contentHash = file.contentHash || createHash("sha256").update(file.content).digest("hex");
+            this.insertFilesStmt.run([
+                artifactId,
+                file.filePath,
+                file.content,
+                file.contentBytes,
+                contentHash
+            ]);
+            this.insertFtsStmt.run([artifactId, file.filePath, file.content]);
+        }
+    }
+    replaceFilesForArtifact(artifactId, files) {
+        const transaction = this.db.transaction(() => {
+            this.clearFilesForArtifact(artifactId);
+            this.insertFilesForArtifact(artifactId, files);
+        });
+        transaction();
+    }
+    deleteFilesForArtifact(artifactId) {
+        const transaction = this.db.transaction(() => {
+            this.clearFilesForArtifact(artifactId);
+        });
+        transaction();
+    }
+    getFileContent(artifactId, filePath) {
+        const row = this.getContentStmt.get([artifactId, filePath]);
+        if (!row) {
+            return undefined;
+        }
+        return {
+            artifactId: row.artifact_id,
+            filePath: row.file_path,
+            content: row.content,
+            contentBytes: row.content_bytes,
+            contentHash: row.content_hash
+        };
+    }
+    listFiles(artifactId, options) {
+        const cursor = parseCursor(options.cursor);
+        const rows = this.listStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix ?? "", Math.max(1, options.limit));
+        return {
+            items: rows.map((row) => row.file_path),
+            nextCursor: nextCursorFromRows(rows)
+        };
+    }
+    listFileRows(artifactId, options) {
+        const cursor = parseCursor(options.cursor);
+        const rows = this.listRowsStmt.all(artifactId, cursor?.sortKey ?? "", options.prefix ?? null, options.prefix ?? "", Math.max(1, options.limit));
+        return {
+            items: rows.map((row) => ({
+                artifactId: row.artifact_id,
+                filePath: row.file_path,
+                content: row.content,
+                contentBytes: row.content_bytes,
+                contentHash: row.content_hash
+            })),
+            nextCursor: nextCursorFromRows(rows)
+        };
+    }
+    getFileContentsByPaths(artifactId, filePaths) {
+        if (filePaths.length === 0) {
+            return [];
+        }
+        const uniquePaths = [...new Set(filePaths)];
+        const stmt = this.getFileContentsByPathsStmt(uniquePaths.length);
+        const rows = stmt.all(artifactId, ...uniquePaths);
+        const byPath = new Map(rows.map((row) => [
+            row.file_path,
+            {
+                artifactId: row.artifact_id,
+                filePath: row.file_path,
+                content: row.content,
+                contentBytes: row.content_bytes,
+                contentHash: row.content_hash
+            }
+        ]));
+        return uniquePaths.map((path) => byPath.get(path)).filter((row) => row != null);
+    }
+    searchFileCandidates(artifactId, options) {
+        const normalized = options.query.trim();
+        if (!normalized) {
+            return { items: [], nextCursor: undefined, scannedRows: 0, dbRoundtrips: 0 };
+        }
+        const cursor = parseSearchCursor(options.cursor);
+        const likeQuery = `%${normalized}%`;
+        const mode = options.mode ?? "mixed";
+        // Cursor-adaptive fetch limit: when no cursor, use a generous limit;
+        // with cursor + SQL pushdown, we need far fewer rows.
+        const baseFetchLimit = options.fetchLimitOverride
+            ?? (cursor ? Math.max(options.limit * 3, 50) : Math.max(options.limit * 5, 200));
+        const fetchLimit = baseFetchLimit;
+        // When cursor score is below all possible bands, skip both queries
+        const cursorExhausted = cursor != null && cursor.score < 100;
+        // Skip path query entirely when cursor is within the content-only tier
+        const cursorPastPath = cursor != null && cursor.score < 120;
+        const includePath = mode !== "text" && !cursorExhausted && !cursorPastPath;
+        const includeContent = mode !== "path" && !cursorExhausted;
+        // Path query: push cursor into SQL when cursor.score == 120 (within path tier)
+        let pathRows;
+        if (includePath && cursor && cursor.score === 120) {
+            // Cursor is within the path tier — only fetch paths after cursor.filePath
+            pathRows = this.db.prepare(`
+        SELECT file_path
+        FROM files
+        WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\' AND file_path > ?
+        ORDER BY file_path ASC
+        LIMIT ?
+      `).all(artifactId, likeQuery, cursor.filePath, fetchLimit);
+        }
+        else if (includePath) {
+            pathRows = this.searchPathStmt.all(artifactId, likeQuery, fetchLimit);
+        }
+        else {
+            pathRows = [];
+        }
+        const merged = pathRows.map((row) => ({
+            filePath: row.file_path,
+            score: 120,
+            matchedIn: "path"
+        }));
+        const mergedByPath = new Map(merged.map((hit) => [hit.filePath, hit]));
+        let contentRows = [];
+        if (includeContent) {
+            try {
+                contentRows = this.searchFtsStmt.all(artifactId, normalized, fetchLimit);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (!/fts5:\s*syntax error/i.test(message)) {
+                    throw error;
+                }
+                log("warn", "storage.files.fts_syntax_error", {
+                    artifactId,
+                    query: normalized,
+                    message
+                });
+            }
+        }
+        for (const row of contentRows) {
+            // BM25 rank is negative (lower = better). Clamp -rank to [0, 19] for sub-tier scoring.
+            const rankBonus = Math.min(19, Math.max(0, Math.round(-row.rank)));
+            const existing = mergedByPath.get(row.file_path);
+            if (existing) {
+                existing.matchedIn = "both";
+                existing.score = 140 + rankBonus;
+                continue;
+            }
+            merged.push({
+                filePath: row.file_path,
+                score: 100 + rankBonus,
+                matchedIn: "content"
+            });
+            mergedByPath.set(row.file_path, merged[merged.length - 1]);
+        }
+        const ordered = merged.sort(compareSearchOrdering);
+        // Safety-net: still apply cursor filter for any rows that slipped through
+        const filtered = cursor ? ordered.filter((hit) => isAfterSearchCursor(hit, cursor)) : ordered;
+        const page = filtered.slice(0, options.limit);
+        const hasMore = filtered.length > page.length;
+        const nextCursor = hasMore && page.length > 0
+            ? buildSearchCursor(page[page.length - 1].score, page[page.length - 1].filePath)
+            : undefined;
+        return {
+            items: page,
+            nextCursor,
+            scannedRows: pathRows.length + contentRows.length,
+            dbRoundtrips: (includePath ? 1 : 0) + (includeContent ? 1 : 0)
+        };
+    }
+    searchFilesWithContent(artifactId, options) {
+        const page = this.searchFileCandidates(artifactId, options);
+        if (page.items.length === 0) {
+            return {
+                items: [],
+                nextCursor: page.nextCursor,
+                scannedRows: page.scannedRows,
+                dbRoundtrips: page.dbRoundtrips
+            };
+        }
+        const rows = this.getFileContentsByPaths(artifactId, page.items.map((item) => item.filePath));
+        const byPath = new Map(rows.map((row) => [row.filePath, row]));
+        return {
+            items: page.items
+                .map((item) => {
+                const contentRow = byPath.get(item.filePath);
+                if (!contentRow) {
+                    return undefined;
+                }
+                return {
+                    filePath: item.filePath,
+                    score: item.score,
+                    matchedIn: item.matchedIn,
+                    preview: buildPreview(contentRow.content, options.query),
+                    content: contentRow.content
+                };
+            })
+                .filter((row) => row != null),
+            nextCursor: page.nextCursor,
+            scannedRows: page.scannedRows + rows.length,
+            dbRoundtrips: page.dbRoundtrips + 1
+        };
+    }
+    countTextCandidates(artifactId, query) {
+        const normalized = query.trim();
+        if (!normalized) {
+            return 0;
+        }
+        try {
+            const row = this.db.prepare(`SELECT COUNT(*) AS cnt FROM files_fts WHERE artifact_id = ? AND files_fts MATCH ?`).get(artifactId, normalized);
+            return row?.cnt ?? 0;
+        }
+        catch {
+            log("warn", "storage.files.count_text_candidates_failed", {
+                artifactId,
+                query: normalized
+            });
+            return 0;
+        }
+    }
+    countPathCandidates(artifactId, query) {
+        const normalized = query.trim();
+        if (!normalized) {
+            return 0;
+        }
+        const likeQuery = `%${normalized}%`;
+        const row = this.db.prepare(`SELECT COUNT(*) AS cnt FROM files WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\'`).get(artifactId, likeQuery);
+        return row?.cnt ?? 0;
+    }
+    findFirstFilePathByName(artifactId, fileName) {
+        const normalized = fileName.trim();
+        if (!normalized) {
+            return undefined;
+        }
+        const row = this.db
+            .prepare(`
+        SELECT file_path
+        FROM files
+        WHERE artifact_id = ?
+          AND (file_path = ? OR file_path LIKE ? ESCAPE '\\')
+        ORDER BY file_path ASC
+        LIMIT 1
+      `)
+            .get(artifactId, normalized, `%/${normalized}`);
+        return row?.file_path;
+    }
+    searchFiles(artifactId, options) {
+        const page = this.searchFilesWithContent(artifactId, options);
+        return {
+            items: page.items.map(({ content: _content, ...rest }) => rest),
+            nextCursor: page.nextCursor
+        };
+    }
+    totalContentBytes() {
+        const row = this.db
+            .prepare(`
+        SELECT COALESCE(SUM(content_bytes), 0) AS total
+        FROM files
+      `)
+            .get();
+        return row?.total ?? 0;
+    }
+    contentBytesForArtifact(artifactId) {
+        const row = this.db
+            .prepare(`
+        SELECT COALESCE(SUM(content_bytes), 0) AS total
+        FROM files
+        WHERE artifact_id = ?
+      `)
+            .get([artifactId]);
+        return row?.total ?? 0;
+    }
+    getFileContentsByPathsStmt(pathCount) {
+        const normalizedCount = Math.max(1, Math.trunc(pathCount));
+        const cached = this.getByPathsStmtCache.get(normalizedCount);
+        if (cached) {
+            return cached;
+        }
+        if (this.getByPathsStmtCache.size >= 64) {
+            this.getByPathsStmtCache.clear();
+        }
+        const placeholders = Array.from({ length: normalizedCount }, () => "?").join(", ");
+        const stmt = this.db.prepare(`
+      SELECT artifact_id, file_path, content, content_bytes, content_hash
+      FROM files
+      WHERE artifact_id = ? AND file_path IN (${placeholders})
+    `);
+        this.getByPathsStmtCache.set(normalizedCount, stmt);
+        return stmt;
+    }
+}
+//# sourceMappingURL=files-repo.js.map

package/dist/storage/index-meta-repo.d.ts

@@ -0,0 +1,35 @@
+import Database from "./sqlite.js";
+type SqliteDatabase = InstanceType<typeof Database>;
+export interface ArtifactIndexMetaRow {
+    artifactId: string;
+    artifactSignature: string;
+    indexSchemaVersion: number;
+    filesCount: number;
+    symbolsCount: number;
+    ftsRowsCount: number;
+    indexedAt: string;
+    indexDurationMs: number;
+    lastError?: string;
+}
+export interface UpsertArtifactIndexMetaInput {
+    artifactId: string;
+    artifactSignature: string;
+    indexSchemaVersion: number;
+    filesCount: number;
+    symbolsCount: number;
+    ftsRowsCount: number;
+    indexedAt: string;
+    indexDurationMs: number;
+    lastError?: string;
+}
+export declare class IndexMetaRepo {
+    private readonly db;
+    private readonly getStmt;
+    private readonly upsertStmt;
+    private readonly deleteStmt;
+    constructor(db: SqliteDatabase);
+    get(artifactId: string): ArtifactIndexMetaRow | undefined;
+    upsert(input: UpsertArtifactIndexMetaInput): void;
+    delete(artifactId: string): void;
+}
+export {};

package/dist/storage/index-meta-repo.js

@@ -0,0 +1,97 @@
+function toRow(record) {
+    return {
+        artifactId: record.artifact_id,
+        artifactSignature: record.artifact_signature,
+        indexSchemaVersion: record.index_schema_version,
+        filesCount: record.files_count,
+        symbolsCount: record.symbols_count,
+        ftsRowsCount: record.fts_rows_count,
+        indexedAt: record.indexed_at,
+        indexDurationMs: record.index_duration_ms,
+        lastError: record.last_error ?? undefined
+    };
+}
+export class IndexMetaRepo {
+    db;
+    getStmt;
+    upsertStmt;
+    deleteStmt;
+    constructor(db) {
+        this.db = db;
+        this.getStmt = this.db.prepare(`
+      SELECT
+        artifact_id,
+        artifact_signature,
+        index_schema_version,
+        files_count,
+        symbols_count,
+        fts_rows_count,
+        indexed_at,
+        index_duration_ms,
+        last_error
+      FROM artifact_index_meta
+      WHERE artifact_id = ?
+      LIMIT 1
+    `);
+        this.upsertStmt = this.db.prepare(`
+      INSERT INTO artifact_index_meta (
+        artifact_id,
+        artifact_signature,
+        index_schema_version,
+        files_count,
+        symbols_count,
+        fts_rows_count,
+        indexed_at,
+        index_duration_ms,
+        last_error
+      ) VALUES (
+        @artifact_id,
+        @artifact_signature,
+        @index_schema_version,
+        @files_count,
+        @symbols_count,
+        @fts_rows_count,
+        @indexed_at,
+        @index_duration_ms,
+        @last_error
+      )
+      ON CONFLICT(artifact_id) DO UPDATE SET
+        artifact_signature = excluded.artifact_signature,
+        index_schema_version = excluded.index_schema_version,
+        files_count = excluded.files_count,
+        symbols_count = excluded.symbols_count,
+        fts_rows_count = excluded.fts_rows_count,
+        indexed_at = excluded.indexed_at,
+        index_duration_ms = excluded.index_duration_ms,
+        last_error = excluded.last_error
+    `);
+        this.deleteStmt = this.db.prepare(`
+      DELETE FROM artifact_index_meta
+      WHERE artifact_id = ?
+    `);
+    }
+    get(artifactId) {
+        const row = this.getStmt.get([artifactId]);
+        if (!row) {
+            return undefined;
+        }
+        return toRow(row);
+    }
+    upsert(input) {
+        this.upsertStmt.run({
+            artifact_id: input.artifactId,
+            artifact_signature: input.artifactSignature,
+            index_schema_version: input.indexSchemaVersion,
+            files_count: input.filesCount,
+            symbols_count: input.symbolsCount,
+            fts_rows_count: input.ftsRowsCount,
+            indexed_at: input.indexedAt,
+            index_duration_ms: Math.max(0, Math.trunc(input.indexDurationMs)),
+            last_error: input.lastError ?? null
+        });
+    }
+    delete(artifactId) {
+        this.deleteStmt.run([artifactId]);
+    }
+}
+//# sourceMappingURL=index-meta-repo.js.map

package/dist/storage/migrations.d.ts

@@ -0,0 +1,11 @@
+type MigrationRunner = {
+    prepare: (sql: string) => {
+        run: (...params: unknown[]) => unknown;
+        get: (...params: unknown[]) => unknown;
+        all: (...params: unknown[]) => unknown[];
+    };
+    transaction<T>(fn: () => T): () => T;
+};
+export declare const LATEST_SCHEMA_VERSION = 1;
+export declare function runMigrations(db: MigrationRunner): number;
+export {};

package/dist/storage/migrations.js

@@ -0,0 +1,71 @@
+import { createError, ERROR_CODES } from "../errors.js";
+import { SCHEMA_V1_STATEMENTS } from "./schema.js";
+export const LATEST_SCHEMA_VERSION = 1;
+const migrations = [
+    {
+        version: 1,
+        statements: SCHEMA_V1_STATEMENTS
+    }
+];
+function selectSchemaVersion(tx) {
+    tx.prepare(`CREATE TABLE IF NOT EXISTS cache_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )`).run();
+    const row = tx.prepare(`SELECT value FROM cache_meta WHERE key = ?`).get(["schema_version"]);
+    if (!row?.value) {
+        return 0;
+    }
+    const parsed = Number.parseInt(row.value, 10);
+    if (!Number.isFinite(parsed)) {
+        throw createError({
+            code: ERROR_CODES.DB_FAILURE,
+            message: `Invalid SQLite schema version '${row.value}'.`,
+            details: {
+                reason: "schema_version_invalid",
+                schemaVersion: row.value
+            }
+        });
+    }
+    return parsed;
+}
+function assertSchemaVersionSupported(version) {
+    if (version > LATEST_SCHEMA_VERSION) {
+        throw createError({
+            code: ERROR_CODES.DB_FAILURE,
+            message: `SQLite schema version ${version} exceeds supported version ${LATEST_SCHEMA_VERSION}.`,
+            details: {
+                reason: "schema_version_unsupported",
+                schemaVersion: version,
+                latestSchemaVersion: LATEST_SCHEMA_VERSION
+            }
+        });
+    }
+}
+function setSchemaVersion(tx, version) {
+    tx.prepare(`
+    INSERT INTO cache_meta(key, value)
+    VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run(["schema_version", String(version)]);
+}
+export function runMigrations(db) {
+    const txn = db.transaction(() => {
+        const initialVersion = selectSchemaVersion(db);
+        assertSchemaVersionSupported(initialVersion);
+        let currentVersion = initialVersion;
+        for (const migration of migrations) {
+            if (migration.version <= currentVersion) {
+                continue;
+            }
+            for (const statement of migration.statements) {
+                db.prepare(statement).run();
+            }
+            setSchemaVersion(db, migration.version);
+            currentVersion = migration.version;
+        }
+        return currentVersion;
+    });
+    return txn();
+}
+//# sourceMappingURL=migrations.js.map

package/dist/storage/schema.d.ts

@@ -0,0 +1 @@
+export declare const SCHEMA_V1_STATEMENTS: string[];