@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.1

package/dist/storage/files-repo.js

@@ -108,6 +108,15 @@ function buildPreview(content, query) {
 function tokenizeIndexedQuery(query) {
     return query.match(/[\p{L}\p{N}]+/gu) ?? [];
 }
+/**
+ * Quote a token so FTS5 reads it as a string literal instead of grammar. Real
+ * Minecraft identifiers tokenize into operator keywords (`BooleanOp.AND` ->
+ * `BooleanOp AND`), which unquoted is either a syntax error or - mid-query, as
+ * in `a NOT b` - a silent change of meaning.
+ */
+function quoteIndexedToken(token) {
+    return `"${token.replace(/"/g, '""')}"`;
+}
 function buildIndexedMatchQuery(query, match) {
     const tokens = tokenizeIndexedQuery(query.trim());
     if (tokens.length === 0) {
@@ -118,10 +127,11 @@ function buildIndexedMatchQuery(query, match) {
     // path while SourceService re-checks hydrated path/content matches before
     // returning hits. Callers can still use literal mode for exact substring scans.
     return tokens.map((token, index) => {
+        const quoted = quoteIndexedToken(token);
         if (match === "prefix" && index === tokens.length - 1) {
-            return `${token}*`;
+            return `${quoted}*`;
         }
-        return token;
+        return quoted;
     }).join(" ");
 }
 /** Escape LIKE wildcards so the needle is matched literally under ESCAPE '\'. */
@@ -177,6 +187,7 @@ export class FilesRepo {
       SELECT file_path
       FROM files
       WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\'
+        AND (? IS NULL OR file_path LIKE ? ESCAPE '\\')
       ORDER BY file_path ASC
       LIMIT ?
     `);
@@ -191,6 +202,7 @@ export class FilesRepo {
       SELECT file_path, rank
       FROM files_fts
       WHERE artifact_id = ? AND files_fts MATCH ?
+        AND (? IS NULL OR file_path LIKE ? ESCAPE '\\')
       ORDER BY rank
       LIMIT ?
     `);
@@ -314,6 +326,7 @@ export class FilesRepo {
         const cursor = parseSearchCursor(options.cursor);
         const likeQuery = `%${escapeLikeNeedle(normalized)}%`;
         const ftsQuery = buildIndexedMatchQuery(normalized, options.match);
+        const scopePattern = options.pathPrefix ? `${escapeLikeNeedle(options.pathPrefix)}%` : null;
         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.
@@ -325,7 +338,7 @@ export class FilesRepo {
         const includePath = mode !== "text" && !cursorExhausted;
         const includeContent = mode !== "path" && !cursorExhausted;
         const pathRows = includePath
-            ? this.searchPathStmt.all(artifactId, likeQuery, fetchLimit)
+            ? this.searchPathStmt.all(artifactId, likeQuery, scopePattern, scopePattern, fetchLimit)
             : [];
         const merged = pathRows.map((row) => ({
             filePath: row.file_path,
@@ -336,7 +349,7 @@ export class FilesRepo {
         let contentRows = [];
         if (includeContent && ftsQuery) {
             try {
-                contentRows = this.searchFtsStmt.all(artifactId, ftsQuery, fetchLimit);
+                contentRows = this.searchFtsStmt.all(artifactId, ftsQuery, scopePattern, scopePattern, fetchLimit);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);

package/dist/storage/sqlite.d.ts

@@ -1,17 +1,47 @@
 import { type StatementSync } from "node:sqlite";
+/**
+ * Recognizes a raw (non-AppError) SQLite corruption error - the shape
+ * node:sqlite throws mid-query, e.g. `{ code: "ERR_SQLITE_ERROR", errcode: 11 }`.
+ * Lives here (rather than storage/db.ts, which imports this module) so the
+ * Database wrapper below can call it directly without a module cycle; db.ts
+ * re-exports it for callers that used to import it from there.
+ */
+export declare function isRawSqliteCorruptionError(error: unknown): boolean;
+/**
+ * Notified, at most once per `Database` instance, the first time a raw SQLite
+ * corruption error is thrown by any statement/pragma/transaction path on that
+ * instance. Called BEFORE the triggering error is rethrown unchanged, so it
+ * runs regardless of how (or whether) a caller further up the stack wraps or
+ * swallows that error - a wrapping catch block elsewhere in the codebase can
+ * no longer hide a runtime corruption from this observer.
+ */
+export type SqliteCorruptionObserver = (error: unknown) => void;
 export declare class Statement<T = unknown> {
     private readonly stmt;
-    constructor(stmt: StatementSync);
+    private readonly notifyCorruption;
+    constructor(stmt: StatementSync, notifyCorruption: (error: unknown) => void);
     run(...params: unknown[]): unknown;
     get(...params: unknown[]): T | undefined;
     all(...params: unknown[]): T[];
     iterate(...params: unknown[]): Iterable<T>;
+    private wrapIterable;
     private invoke;
 }
 export default class Database {
     private readonly inner;
     private transactionDepth;
+    private corruptionObserver;
+    private corruptionNotified;
     constructor(path: string);
+    /**
+     * Registers (or clears, with `undefined`) the observer notified on this
+     * instance's first raw corruption error. Best-effort: an observer that
+     * throws is swallowed so it can never mask the real SQLite error being
+     * rethrown, and it fires at most once per instance.
+     */
+    setCorruptionObserver(observer: SqliteCorruptionObserver | undefined): void;
+    private notifyCorruption;
+    private runRaw;
     pragma(pragma: string): unknown;
     prepare<T = Record<string, unknown>>(sql: string): Statement<T>;
     transaction<T>(fn: () => T): () => T;

package/dist/storage/sqlite.js

@@ -1,4 +1,5 @@
 import { DatabaseSync } from "node:sqlite";
+import { isAppError } from "../errors.js";
 function isPlainObject(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value) || ArrayBuffer.isView(value)) {
         return false;
@@ -18,10 +19,35 @@ function normalizeParameters(args) {
     }
     return { positional: args };
 }
+const SQLITE_CORRUPT_ERRCODE = 11;
+const SQLITE_NOTADB_ERRCODE = 26;
+/**
+ * Recognizes a raw (non-AppError) SQLite corruption error - the shape
+ * node:sqlite throws mid-query, e.g. `{ code: "ERR_SQLITE_ERROR", errcode: 11 }`.
+ * Lives here (rather than storage/db.ts, which imports this module) so the
+ * Database wrapper below can call it directly without a module cycle; db.ts
+ * re-exports it for callers that used to import it from there.
+ */
+export function isRawSqliteCorruptionError(error) {
+    if (isAppError(error)) {
+        return false;
+    }
+    const sqliteError = error;
+    if (sqliteError?.code === "SQLITE_CORRUPT" || sqliteError?.code === "SQLITE_NOTADB") {
+        return true;
+    }
+    if (typeof sqliteError?.errcode !== "number") {
+        return false;
+    }
+    const primaryErrcode = sqliteError.errcode & 0xff;
+    return primaryErrcode === SQLITE_CORRUPT_ERRCODE || primaryErrcode === SQLITE_NOTADB_ERRCODE;
+}
 export class Statement {
     stmt;
-    constructor(stmt) {
+    notifyCorruption;
+    constructor(stmt, notifyCorruption) {
         this.stmt = stmt;
+        this.notifyCorruption = notifyCorruption;
     }
     run(...params) {
         return this.invoke("run", params);
@@ -33,34 +59,116 @@ export class Statement {
         return this.invoke("all", params);
     }
     iterate(...params) {
-        return this.invoke("iterate", params);
+        const rawIterable = this.invoke("iterate", params);
+        return this.wrapIterable(rawIterable);
+    }
+    // node:sqlite's iterate() returns lazily: the corrupted page is only ever
+    // touched once the consumer actually pulls a row, i.e. inside next(), not
+    // at the call above. Wrap the iterator itself so a mid-iteration corruption
+    // error still reaches the observer before propagating to the consumer.
+    wrapIterable(iterable) {
+        const notifyCorruption = this.notifyCorruption;
+        return {
+            [Symbol.iterator]() {
+                const inner = iterable[Symbol.iterator]();
+                const wrapped = {
+                    next() {
+                        try {
+                            return inner.next();
+                        }
+                        catch (error) {
+                            notifyCorruption(error);
+                            throw error;
+                        }
+                    }
+                };
+                // Forward early termination (a `break` out of for...of, or a consuming
+                // generator being closed) so the underlying statement is reset instead
+                // of being left mid-iteration with its read snapshot open.
+                if (typeof inner.return === "function") {
+                    wrapped.return = (value) => inner.return(value);
+                }
+                return wrapped;
+            }
+        };
     }
     invoke(method, params) {
         const normalized = normalizeParameters(params);
         const target = this.stmt[method];
-        if (normalized.named !== undefined) {
-            return target.call(this.stmt, normalized.named);
+        try {
+            if (normalized.named !== undefined) {
+                return target.call(this.stmt, normalized.named);
+            }
+            return target.call(this.stmt, ...(normalized.positional ?? []));
+        }
+        catch (error) {
+            this.notifyCorruption(error);
+            throw error;
         }
-        return target.call(this.stmt, ...(normalized.positional ?? []));
     }
 }
 let transactionSerial = 0;
 export default class Database {
     inner;
     transactionDepth = 0;
+    corruptionObserver;
+    corruptionNotified = false;
     constructor(path) {
         this.inner = new DatabaseSync(path);
     }
+    /**
+     * Registers (or clears, with `undefined`) the observer notified on this
+     * instance's first raw corruption error. Best-effort: an observer that
+     * throws is swallowed so it can never mask the real SQLite error being
+     * rethrown, and it fires at most once per instance.
+     */
+    setCorruptionObserver(observer) {
+        this.corruptionObserver = observer;
+    }
+    notifyCorruption(error) {
+        if (this.corruptionNotified) {
+            return;
+        }
+        const observer = this.corruptionObserver;
+        if (!observer) {
+            return;
+        }
+        if (!isRawSqliteCorruptionError(error)) {
+            return;
+        }
+        this.corruptionNotified = true;
+        try {
+            observer(error);
+        }
+        catch {
+            // best-effort: never let the observer mask the real error being rethrown
+        }
+    }
+    runRaw(fn) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            this.notifyCorruption(error);
+            throw error;
+        }
+    }
     pragma(pragma) {
         const sql = `PRAGMA ${pragma}`;
         if (pragma.includes("=")) {
-            this.inner.exec(sql);
+            this.runRaw(() => this.inner.exec(sql));
             return undefined;
         }
-        return this.inner.prepare(sql).all();
+        return this.runRaw(() => this.inner.prepare(sql).all());
     }
     prepare(sql) {
-        return new Statement(this.inner.prepare(sql));
+        // Wrapped in runRaw: PREPARING a statement can itself throw a raw
+        // corruption error - e.g. damage to the schema (sqlite_master) that a
+        // fresh connection only discovers while compiling its first statement -
+        // not just running one. Without this, that error skipped the observer
+        // entirely (reproduced: errcode 11, observer never notified).
+        const stmt = this.runRaw(() => this.inner.prepare(sql));
+        return new Statement(stmt, (error) => this.notifyCorruption(error));
     }
     transaction(fn) {
         return () => this.runInTransaction(fn);
@@ -74,19 +182,19 @@ export default class Database {
         const savepoint = `sp_${++transactionSerial}`;
         try {
             if (isOutermost) {
-                this.inner.exec("BEGIN");
+                this.runRaw(() => this.inner.exec("BEGIN"));
             }
             else {
-                this.inner.exec(`SAVEPOINT ${savepoint}`);
+                this.runRaw(() => this.inner.exec(`SAVEPOINT ${savepoint}`));
             }
             this.transactionDepth = initialDepth + 1;
             const result = fn();
             this.transactionDepth = initialDepth;
             if (isOutermost) {
-                this.inner.exec("COMMIT");
+                this.runRaw(() => this.inner.exec("COMMIT"));
             }
             else {
-                this.inner.exec(`RELEASE SAVEPOINT ${savepoint}`);
+                this.runRaw(() => this.inner.exec(`RELEASE SAVEPOINT ${savepoint}`));
             }
             return result;
         }
@@ -94,15 +202,16 @@ export default class Database {
             this.transactionDepth = initialDepth;
             try {
                 if (isOutermost) {
-                    this.inner.exec("ROLLBACK");
+                    this.runRaw(() => this.inner.exec("ROLLBACK"));
                 }
                 else {
-                    this.inner.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`);
-                    this.inner.exec(`RELEASE SAVEPOINT ${savepoint}`);
+                    this.runRaw(() => this.inner.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`));
+                    this.runRaw(() => this.inner.exec(`RELEASE SAVEPOINT ${savepoint}`));
                 }
             }
             catch {
-                // best-effort rollback cleanup
+                // best-effort rollback cleanup - runRaw already notified the
+                // observer (if any) before this catch swallows the rollback failure
             }
             throw error;
         }

package/dist/tool-contract-manifest.js

@@ -17,7 +17,7 @@ const SECTION_ROWS = {
             "| `compare-minecraft` | Compare version pairs, class diffs, registry diffs, and migration-oriented summaries |",
             "| `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, read class members from bytecode, and preview or apply remaps |",
             "| `validate-project` | Summarize workspaces and run direct Mixin, Access Widener, or Access Transformer validation |",
-            "| `manage-cache` | List, verify, and preview or apply cache cleanup and rebuild operations |"
+            "| `manage-cache` | List, verify, and preview or apply cache cleanup operations |"
         ],
         ja: [
             "| `inspect-minecraft` | バージョン、アーティファクト、クラス、ファイル、ソース本文、ワークスペース文脈の調査フローをまとめて扱う |",
@@ -25,7 +25,7 @@ const SECTION_ROWS = {
             "| `compare-minecraft` | バージョン差分、クラス差分、レジストリ差分、移行向け概要を比較する |",
             "| `analyze-mod` | Mod メタデータの要約、Mod コードのデコンパイル / 検索、クラスソース確認、リマップのプレビュー / 実行を扱う |",
             "| `validate-project` | ワークスペース要約と、Mixin / Access Widener / Access Transformer の直接検証を行う |",
-            "| `manage-cache` | キャッシュの一覧、検証、クリーンアップ / 再構築のプレビュー / 実行を行う |"
+            "| `manage-cache` | キャッシュの一覧、検証、クリーンアップのプレビュー / 実行を行う |"
         ]
     },
     "source-exploration": {

package/dist/tool-execution-gate.js

@@ -4,7 +4,8 @@ const DEFAULT_OPTIONS = {
     maxQueue: 2
 };
 // Heavy tools that have a batch equivalent able to collapse many same-kind
-// queries into a single gated call. Used to point overflow guidance at the
+// queries into one call. The batch-* tools are NOT in the heavy set, so that
+// one call bypasses this gate entirely. Used to point overflow guidance at the
 // right batch-* tool instead of just telling the caller to retry serially.
 const BATCH_EQUIVALENTS = {
     "find-mapping": "batch-mappings",

package/dist/tool-guidance.js

@@ -800,7 +800,10 @@ export function buildValidateProjectSuggestedParams(normalizedInput) {
     for (const field of booleanFields) {
         const value = record[field];
         if (typeof value === "boolean" &&
-            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+            // project-summary infers an omitted version, so an explicit
+            // preferProjectVersion=false is an opt-out, not a droppable default.
+            (field === "preferProjectVersion" ||
+                !Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
                 !isSuggestedCallDefault(field, value))) {
             result[field] = value;
         }