@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.0

package/dist/storage/db.js

@@ -1,22 +1,131 @@
-import { existsSync, renameSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { mkdirSync } from "node:fs";
-import Database from "./sqlite.js";
+import { randomUUID } from "node:crypto";
+import Database, { isRawSqliteCorruptionError } from "./sqlite.js";
 import { runMigrations } from "./migrations.js";
 import { createError, ERROR_CODES, isAppError } from "../errors.js";
 import { log } from "../logger.js";
+// Re-exported for callers that already import the predicate from this module
+// (it now lives in ./sqlite.js so the Database wrapper can call it directly
+// without a module cycle back to this file).
+export { isRawSqliteCorruptionError };
 const DEFAULT_SQLITE_CACHE_KB = 8_000;
 const DEFAULT_SQLITE_MMAP_SIZE = 268_435_456;
+// Per-request escalation files created by the runtime-corruption recovery
+// path (see attachRuntimeCorruptionObserver / convertRuntimeSqliteCorruption
+// below): a SQLite error surfaced while serving a tool call - not at open
+// time - means quick_check already passed for this file, so the NEXT open
+// must pay for the full integrity_check instead of trusting quick_check
+// again.
+//
+// Each request is its OWN immutable, uniquely-named file (exclusive-create,
+// never overwritten), rather than one shared marker whose content gets
+// replaced. That is what makes two requests race-free even across processes
+// sharing one cache directory: an open lists whatever request files exist at
+// its OWN decision point and remembers those exact names; after honoring
+// them, it deletes only those names. A request file created by someone else
+// AFTER that decision (a concurrent process, or a second corruption event)
+// is simply a name that open never saw, so it can never be swept up by a
+// clear meant for a different, earlier decision - it waits for the NEXT
+// open. (An earlier single shared marker file, `<sqlitePath>.integrity-check-
+// requested`, was never released, so there is no old name to keep reading
+// for compatibility; it is dropped outright rather than special-cased.)
+const INTEGRITY_CHECK_REQUEST_INFIX = ".integrity-check-requested.";
 function ensureParentDirectory(path) {
     mkdirSync(dirname(path), { recursive: true });
 }
-function runIntegrityCheck(db) {
-    const result = db.prepare("PRAGMA integrity_check").get();
-    if (!result || result.integrity_check !== "ok") {
+function integrityCheckRequestFileName(sqlitePath, token) {
+    return `${basename(sqlitePath)}${INTEGRITY_CHECK_REQUEST_INFIX}${token}`;
+}
+function integrityCheckRequestFileNamePrefix(sqlitePath) {
+    return `${basename(sqlitePath)}${INTEGRITY_CHECK_REQUEST_INFIX}`;
+}
+/**
+ * Best-effort request that the NEXT `openDatabase` for `sqlitePath` run the
+ * full `PRAGMA integrity_check` instead of the default `quick_check`. Creates
+ * a new, uniquely-named request file (see the block comment above) with
+ * exclusive-create so it can never collide with or overwrite another
+ * pending request. Never throws: a failure to write the file only means the
+ * escalation is missed, which is logged rather than allowed to mask the
+ * caller's real error. Returns whether the file was actually written, so a
+ * caller that cannot schedule the follow-up check can say so instead of
+ * promising one.
+ */
+export function requestFullIntegrityCheck(sqlitePath, logger = buildDefaultLogger()) {
+    const token = `${Date.now()}-${process.pid}-${randomUUID()}`;
+    const requestPath = join(dirname(sqlitePath), integrityCheckRequestFileName(sqlitePath, token));
+    try {
+        ensureParentDirectory(sqlitePath);
+        writeFileSync(requestPath, "", { flag: "wx" });
+        return true;
+    }
+    catch (writeError) {
+        logger.warn("Failed to request a full SQLite integrity check", {
+            sqlitePath,
+            reason: writeError instanceof Error ? writeError.message : String(writeError)
+        });
+        return false;
+    }
+}
+/**
+ * Lists the full paths of every currently pending full-integrity-check
+ * request file for `sqlitePath`. Best-effort: a missing or unreadable
+ * directory is treated as "no requests pending" rather than as an error,
+ * since the fallback (a quick_check) is always safe to run.
+ */
+export function listIntegrityCheckRequestFiles(sqlitePath) {
+    const dir = dirname(sqlitePath);
+    const prefix = integrityCheckRequestFileNamePrefix(sqlitePath);
+    try {
+        return readdirSync(dir)
+            .filter((name) => name.startsWith(prefix))
+            .map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Deletes EXACTLY the given request file paths - the ones an earlier
+ * `listIntegrityCheckRequestFiles` call returned, never a fresh listing - so
+ * a request file created after that decision point is never deleted by a
+ * clear that only ever meant to honor the requests it actually acted on.
+ * Best-effort per file: ENOENT (already gone) is ignored, anything else is
+ * logged, not thrown.
+ *
+ * Exported so a unit test can exercise the race guard directly:
+ * `openDatabase` lists-then-clears synchronously with no `await` in between,
+ * so there is no way to interleave a concurrent request file appearing
+ * between "decide" and "clear" from outside that call.
+ */
+export function clearIntegrityCheckRequestFiles(requestFiles, logger = buildDefaultLogger()) {
+    for (const requestFile of requestFiles) {
+        try {
+            unlinkSync(requestFile);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT") {
+                continue;
+            }
+            logger.warn("Failed to clear a SQLite full-integrity-check request file", {
+                requestFile,
+                reason: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+}
+function runIntegrityCheck(db, logger, mode = "quick") {
+    const resultKey = mode === "full" ? "integrity_check" : "quick_check";
+    const startedAt = Date.now();
+    const result = db.prepare(`PRAGMA ${resultKey}`).get();
+    const durationMs = Date.now() - startedAt;
+    logger.info("SQLite consistency check completed", { durationMs, check: resultKey });
+    if (!result || result[resultKey] !== "ok") {
         throw createError({
             code: ERROR_CODES.DB_FAILURE,
             message: "SQLite integrity check failed.",
-            details: { reason: "integrity_check_failed", integrityCheck: result }
+            details: { reason: "integrity_check_failed", check: resultKey, checkResult: result }
         });
     }
 }
@@ -60,21 +169,59 @@ function isSchemaVersionMismatchError(error) {
     return (error.details?.reason === "schema_version_unsupported" ||
         error.details?.reason === "schema_version_invalid");
 }
-const SQLITE_CORRUPT_ERRCODE = 11;
-const SQLITE_NOTADB_ERRCODE = 26;
 function isCorruptionError(error) {
     if (isAppError(error)) {
         return (error.code === ERROR_CODES.DB_FAILURE && error.details?.reason === "integrity_check_failed");
     }
-    const sqliteError = error;
-    if (sqliteError?.code === "SQLITE_CORRUPT" || sqliteError?.code === "SQLITE_NOTADB") {
-        return true;
-    }
-    if (typeof sqliteError?.errcode !== "number") {
-        return false;
+    return isRawSqliteCorruptionError(error);
+}
+/**
+ * Wires a Database instance's corruption observer (see sqlite.ts) so that a
+ * raw corruption error thrown by ANY later statement on this handle - no
+ * matter what catches and wraps it further up the call stack, including a
+ * tool-specific error wrapper that never reaches runTool's own catch block -
+ * still schedules the next open's full integrity_check. Exported so a unit
+ * test can attach the same wiring to a Database instance opened directly
+ * (bypassing openDatabase's own open-time check, which would otherwise catch
+ * a test's injected corruption before a "successfully opened" handle ever
+ * existed to query against).
+ */
+export function attachRuntimeCorruptionObserver(db, sqlitePath, logger = buildDefaultLogger()) {
+    db.setCorruptionObserver(() => {
+        requestFullIntegrityCheck(sqlitePath, logger);
+    });
+}
+/**
+ * runTool catch-path helper: when `caughtError` is a raw SQLite corruption
+ * error observed while serving a tool call (not at open time - open-time
+ * corruption is already an AppError by the time it reaches here), this
+ * requests a full integrity check on the next open and returns a typed
+ * ERR_DB_FAILURE the caller should report instead of the raw error. Any other
+ * error is returned unchanged so non-corruption failures are unaffected.
+ *
+ * The marker request here is redundant with the Database corruption observer
+ * (attachRuntimeCorruptionObserver) for an UNWRAPPED raw error, since that
+ * observer already fired deeper in the call stack; it is kept because
+ * `convertRuntimeSqliteCorruption` is the only place with reliable access to
+ * whether scheduling succeeded, which decides which `nextAction` to publish.
+ */
+export function convertRuntimeSqliteCorruption(error, sqlitePath, logger = buildDefaultLogger()) {
+    if (!isRawSqliteCorruptionError(error)) {
+        return error;
     }
-    const primaryErrcode = sqliteError.errcode & 0xff;
-    return primaryErrcode === SQLITE_CORRUPT_ERRCODE || primaryErrcode === SQLITE_NOTADB_ERRCODE;
+    const scheduled = requestFullIntegrityCheck(sqlitePath, logger);
+    const nextAction = scheduled
+        ? "Restart the MCP server so the cache database is fully checked and rebuilt if necessary, then retry the request."
+        : `The automatic full check could not be scheduled. Stop every MCP server process that uses this cache, delete the cache database at ${sqlitePath} together with its -wal and -shm files, then restart; the cache is rebuilt on the next start.`;
+    return createError({
+        code: ERROR_CODES.DB_FAILURE,
+        message: "A SQLite consistency error occurred while serving this request.",
+        details: {
+            sqlitePath,
+            reason: "runtime_corruption",
+            nextAction
+        }
+    });
 }
 function buildDefaultLogger() {
     return {
@@ -100,12 +247,21 @@ function buildDefaultLogger() {
 }
 export function openDatabase(config, logger = buildDefaultLogger()) {
     let db;
+    const pendingRequestFiles = listIntegrityCheckRequestFiles(config.sqlitePath);
     try {
         ensureParentDirectory(config.sqlitePath);
         db = new Database(config.sqlitePath);
         applyPragmas(db, config);
         const schemaVersion = runMigrations(db);
-        runIntegrityCheck(db);
+        runIntegrityCheck(db, logger, pendingRequestFiles.length > 0 ? "full" : "quick");
+        if (pendingRequestFiles.length > 0) {
+            clearIntegrityCheckRequestFiles(pendingRequestFiles, logger);
+        }
+        // Only attach the runtime-corruption observer once the open itself
+        // (migrations + consistency check) has fully succeeded: open-time
+        // failures must keep going through the backup/rebuild path below, not
+        // silently re-request a check that is about to happen anyway.
+        attachRuntimeCorruptionObserver(db, config.sqlitePath, logger);
         return { db, schemaVersion };
     }
     catch (caughtError) {
@@ -152,12 +308,17 @@ export function openDatabase(config, logger = buildDefaultLogger()) {
                 const backupPath = backupCorruptedDb(config.sqlitePath);
                 logger.warn("SQLite database integrity check failed. Recreated database after backup", {
                     sqlitePath: config.sqlitePath,
-                    backupPath
+                    backupPath,
+                    reason: errorMessage
                 });
                 rebuilt = new Database(config.sqlitePath);
                 applyPragmas(rebuilt, config);
                 const schemaVersion = runMigrations(rebuilt);
-                runIntegrityCheck(rebuilt);
+                runIntegrityCheck(rebuilt, logger);
+                if (pendingRequestFiles.length > 0) {
+                    clearIntegrityCheckRequestFiles(pendingRequestFiles, logger);
+                }
+                attachRuntimeCorruptionObserver(rebuilt, config.sqlitePath, logger);
                 return { db: rebuilt, schemaVersion };
             }
             catch (rebuildError) {

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-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;
         }