@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/dist/source-jar-reader.js

@@ -3,6 +3,15 @@ import { createError, ERROR_CODES } from "./errors.js";
 import { log } from "./logger.js";
 import { isSecureJarEntryPath } from "./path-resolver.js";
 const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+// Test-only instrumentation: counts real jar opens at the single openZipFile
+// chokepoint so perf tests can assert N-opens-per-call collapses to 1.
+let zipOpenCount = 0;
+export function __getZipOpenCount() {
+    return zipOpenCount;
+}
+export function __resetZipOpenCount() {
+    zipOpenCount = 0;
+}
 function toErrorMessage(value) {
     if (value instanceof Error) {
         return value.message;
@@ -23,7 +32,7 @@ export function hasJavaSourceExtension(entryPath) {
     }
     return true;
 }
-function openZipFile(jarPath) {
+export function openZipFile(jarPath) {
     return new Promise((resolve, reject) => {
         yauzl.open(jarPath, {
             lazyEntries: true,
@@ -33,6 +42,7 @@ function openZipFile(jarPath) {
                 reject(new Error(`Failed to read jar "${jarPath}": ${toErrorMessage(error)}`));
                 return;
             }
+            zipOpenCount += 1;
             resolve(zipFile);
         });
     });
@@ -193,6 +203,66 @@ export async function readJarEntryAsBuffer(jarPath, entryPath) {
         }
     });
 }
+/**
+ * Opens a jar ONCE, drains its central directory into a name->entry index, and
+ * serves repeated entry reads via O(1) lookup + openReadStream. Use this when a
+ * single logical operation reads many entries from the same jar (e.g. walking a
+ * class hierarchy) instead of calling {@link readJarEntryAsBuffer} per entry,
+ * which re-opens and re-scans the jar each time. Callers MUST close() the reader
+ * (in a finally) to release the file descriptor. getEntryBuffer throws the same
+ * INVALID_INPUT (unsafe path) / SOURCE_NOT_FOUND (missing entry) errors as
+ * readJarEntryAsBuffer; duplicate entry names resolve to the first occurrence.
+ */
+export async function createJarEntryReader(jarPath) {
+    const zipFile = await openZipFile(jarPath);
+    let closed = false;
+    const index = new Map();
+    try {
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                break;
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (!index.has(entry.fileName)) {
+                index.set(entry.fileName, entry);
+            }
+        }
+    }
+    catch (error) {
+        zipFile.close();
+        throw error;
+    }
+    return {
+        async getEntryBuffer(entryPath) {
+            const normalizedTargetPath = entryPath.replaceAll("\\", "/");
+            if (!isSecureJarEntryPath(normalizedTargetPath)) {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `Entry path "${normalizedTargetPath}" is not allowed.`,
+                    details: { jarPath, entryPath: normalizedTargetPath }
+                });
+            }
+            const entry = index.get(normalizedTargetPath);
+            if (!entry) {
+                throw createError({
+                    code: ERROR_CODES.SOURCE_NOT_FOUND,
+                    message: `Entry "${normalizedTargetPath}" was not found in "${jarPath}".`,
+                    details: { jarPath, entryPath: normalizedTargetPath }
+                });
+            }
+            return readEntryStream(zipFile, entry, jarPath);
+        },
+        close() {
+            if (!closed) {
+                closed = true;
+                zipFile.close();
+            }
+        }
+    };
+}
 export async function collectMatchedJarEntriesAsUtf8(jarPath, predicate, options = {}) {
     return withZipFile(jarPath, async (zipFile) => {
         const entries = [];
@@ -226,6 +296,48 @@ export async function collectMatchedJarEntriesAsUtf8(jarPath, predicate, options
         }
     });
 }
+/**
+ * Raw-buffer counterpart of {@link collectMatchedJarEntriesAsUtf8}: opens the jar
+ * ONCE and returns the matched entries as raw Buffers (no UTF-8 decode), so binary
+ * inputs like `.class` bytes survive intact. Used to avoid re-opening the jar per
+ * sampled entry. Mirrors the sibling's maxBytes/maxEntries/continueOnError semantics
+ * and its finally-close, but takes an injectable open seam for open-count assertions.
+ */
+export async function collectMatchedJarEntriesAsBuffers(jarPath, predicate, options = {}, deps = {}) {
+    const open = deps.openZipFile ?? openZipFile;
+    const zipFile = await open(jarPath);
+    try {
+        const entries = [];
+        const maxEntries = options.maxEntries == null ? undefined : Math.max(1, Math.trunc(options.maxEntries));
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                return entries;
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (!predicate(entry.fileName)) {
+                continue;
+            }
+            try {
+                const contentBuffer = await readEntryStream(zipFile, entry, jarPath, options.maxBytes);
+                entries.push({ filePath: entry.fileName, content: contentBuffer });
+                if (maxEntries != null && entries.length >= maxEntries) {
+                    return entries;
+                }
+            }
+            catch (error) {
+                if (!options.continueOnError) {
+                    throw error;
+                }
+            }
+        }
+    }
+    finally {
+        zipFile.close();
+    }
+}
 export async function* iterateJavaEntriesAsUtf8(jarPath, maxBytes) {
     const zipFile = await openZipFile(jarPath);
     try {
@@ -285,7 +397,7 @@ function countMatches(input, pattern) {
     }
     return count;
 }
-export async function detectFabricLikeInputNamespace(inputJar) {
+export async function detectFabricLikeInputNamespace(inputJar, deps = {}) {
     const warnings = [];
     const classEntries = (await listJarEntries(inputJar))
         .filter((entry) => entry.endsWith(".class"))
@@ -297,16 +409,15 @@ export async function detectFabricLikeInputNamespace(inputJar) {
             warnings
         };
     }
+    // Read all sampled class entries in a SINGLE jar open instead of re-opening the
+    // jar once per entry. The sample set and latin1 decode are unchanged, so scores —
+    // and therefore the detected namespace — are identical.
+    const sampleSet = new Set(classEntries);
+    const matched = await collectMatchedJarEntriesAsBuffers(inputJar, (name) => sampleSet.has(name), { continueOnError: true }, deps);
     let mojangScore = 0;
     let intermediaryScore = 0;
-    for (const entry of classEntries) {
-        let text = "";
-        try {
-            text = (await readJarEntryAsBuffer(inputJar, entry)).toString("latin1");
-        }
-        catch {
-            continue;
-        }
+    for (const { content } of matched) {
+        const text = content.toString("latin1");
         mojangScore += countMatches(text, /net\/minecraft\/(?:advancements|client|commands|core|data|gametest|nbt|network|recipe|resources|server|sounds|stats|tags|util|world)\//g) * 3;
         intermediaryScore += countMatches(text, /net\/minecraft\/class_\d+/g) * 3;
         intermediaryScore += countMatches(text, /\b(?:method|field)_\d+\b/g);

package/dist/source-resolver.js

@@ -260,7 +260,7 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
                     ? false
                     : download.statusCode !== 404 && isTransientFailure(download.statusCode);
                 sawRemoteRepoFailure = sawRemoteRepoFailure || transient;
-                if (hasNextAttempt && transient) {
+                if (hasNextAttempt && (transient || download.ok)) {
                     options.onRepoFailover?.({
                         stage: "source",
                         repoUrl: sourceUrl,
@@ -320,7 +320,7 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
                     ? false
                     : downloaded.statusCode !== 404 && isTransientFailure(downloaded.statusCode);
                 sawRemoteRepoFailure = sawRemoteRepoFailure || transient;
-                if (hasNextAttempt && transient) {
+                if (hasNextAttempt && (transient || downloaded.ok)) {
                     options.onRepoFailover?.({
                         stage: "binary",
                         repoUrl: binaryUrl,

package/dist/source-service.d.ts

@@ -11,6 +11,7 @@ import * as indexer from "./source/indexer.js";
 import * as workspaceTarget from "./source/workspace-target.js";
 import * as validateMixinModule from "./source/validate-mixin.js";
 import * as artifactResolver from "./source/artifact-resolver.js";
+import type { WireMembersBlock } from "./source/class-source/members-builder.js";
 import { type StageEmitter } from "./stage-emitter.js";
 import { WorkspaceMappingService, type WorkspaceCompileMappingOutput } from "./workspace-mapping-service.js";
 import { type WorkspaceContextCache } from "./workspace-context-cache.js";
@@ -30,7 +31,8 @@ export type ResolveArtifactInput = {
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
-    compact?: boolean;
+    /** When true, compute the optional `sampleEntries` listing (detail=full / include=samples). */
+    includeSampleEntries?: boolean;
 };
 export type ResolveArtifactOutput = {
     artifactId: string;
@@ -112,6 +114,8 @@ export type SearchClassSourceInput = {
 export type SearchClassSourceOutput = {
     hits: SearchSourceHit[];
     nextCursor?: string;
+    /** True when a provided cursor was malformed or belonged to a different query and was ignored (results restart from page one). */
+    cursorIgnored?: boolean;
     mappingApplied: SourceMapping;
     returnedNamespace: SourceMapping;
     artifactContents: ArtifactContentsSummary;
@@ -205,6 +209,10 @@ export type GetClassSourceOutput = {
     };
     truncated: boolean;
     charsTruncated?: boolean;
+    /** True when startLine begins past EOF; the returned range is empty (not clamped). */
+    outOfRange?: boolean;
+    /** First not-yet-returned line when truncated; pass back as startLine to continue. */
+    nextStartLine?: number;
     origin: ResolvedSourceArtifact["origin"];
     artifactId: string;
     requestedMapping: SourceMapping;
@@ -213,6 +221,11 @@ export type GetClassSourceOutput = {
     provenance: ArtifactProvenance;
     qualityFlags: string[];
     artifactContents: ArtifactContentsSummary;
+    /** Replayable get-class-source call that reads from nextStartLine (truncated, non-file output only). */
+    suggestedCall?: {
+        tool: string;
+        params: Record<string, unknown>;
+    };
     outputFile?: string;
     warnings: string[];
 };
@@ -245,11 +258,14 @@ export type GetClassMembersInput = {
     includeInherited?: boolean;
     memberPattern?: string;
     maxMembers?: number;
+    cursor?: string;
     projectPath?: string;
     gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
+    /** When true, keep jvmDescriptor on FIELD members (always kept on methods/constructors). */
+    includeDescriptors?: boolean;
 };
 export type DecompiledMember = {
     name: string;
@@ -265,11 +281,7 @@ export type DecompiledFallback = {
 export type GetClassMembersStatus = "ok" | "members_unavailable" | "partial";
 export type GetClassMembersOutput = {
     className: string;
-    members: {
-        constructors: SignatureMember[];
-        fields: SignatureMember[];
-        methods: SignatureMember[];
-    };
+    members: WireMembersBlock;
     counts: {
         constructors: number;
         fields: number;
@@ -277,6 +289,10 @@ export type GetClassMembersOutput = {
         total: number;
     };
     truncated: boolean;
+    /** Continuation cursor when more members remain; pass back as cursor to fetch the next page. */
+    nextCursor?: string;
+    /** True when a provided cursor was malformed or belonged to a different query and was ignored. */
+    cursorIgnored?: boolean;
     context: ExplorerResponseContext;
     origin: ResolvedSourceArtifact["origin"];
     artifactId: string;
@@ -420,7 +436,12 @@ export type ValidateMixinInput = {
         path: string;
     };
     sourceRoots?: string[];
-    version: string;
+    /**
+     * Optional when input.mode='project', or preferProjectVersion=true with a
+     * projectPath set: the dispatcher detects the Minecraft version from
+     * gradle.properties before any version-dependent stage runs.
+     */
+    version?: string;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     scope?: ArtifactScope;

package/dist/source-service.js

@@ -141,7 +141,15 @@ export class SourceService {
     }
     async checkSymbolExists(input) {
         const result = await this.mappingService.checkSymbolExists(input);
-        if (result.status !== "mapping_unavailable" ||
+        // On unobfuscated versions the mapping graph is empty, so the mapping service can
+        // only ever report symbols as missing. We then validate against runtime bytecode.
+        // Classes/fields surface as `mapping_unavailable` when the graph yields nothing, but
+        // a method query with a non-empty graph returns `not_found` (empty member lookup) —
+        // which previously skipped the runtime fallback and produced false negatives for
+        // methods that genuinely exist (B1). Treat `not_found` methods as fallback-eligible.
+        const fallbackEligible = result.status === "mapping_unavailable" ||
+            (result.status === "not_found" && input.kind === "method");
+        if (!fallbackEligible ||
             !isUnobfuscatedVersion(input.version) ||
             (input.sourceMapping !== "mojang" && input.sourceMapping !== "obfuscated")) {
             return result;

package/dist/stdio-supervisor.d.ts

@@ -90,8 +90,8 @@ export declare class StdioSupervisor {
     private readonly handleWorkerData;
     private readonly handleWorkerStdinError;
     private readonly handleWorkerStderr;
-    private readonly handleWorkerProcessError;
-    private readonly handleWorkerExit;
+    private handleWorkerProcessError;
+    private handleWorkerExit;
     private handleWorkerMessage;
     private applyStageUpdate;
     private handleWorkerReady;

package/dist/stdio-supervisor.js

@@ -408,6 +408,13 @@ export class StdioSupervisor {
         if (this.shuttingDown) {
             return;
         }
+        const stale = this.child;
+        if (stale) {
+            this.detachChild();
+            if (stale.exitCode === null) {
+                stale.kill("SIGTERM");
+            }
+        }
         const child = spawn(process.execPath, [...process.execArgv, this.entryFile], {
             env: {
                 ...process.env,
@@ -423,8 +430,8 @@ export class StdioSupervisor {
         child.stdout.on("data", this.handleWorkerData);
         child.stderr.on("data", this.handleWorkerStderr);
         child.stdin.on("error", this.handleWorkerStdinError);
-        child.once("error", this.handleWorkerProcessError);
-        child.once("exit", this.handleWorkerExit);
+        child.once("error", (error) => this.handleWorkerProcessError(child, error));
+        child.once("exit", (code, signal) => this.handleWorkerExit(child, code, signal));
         log("info", "supervisor.worker_spawn", { pid: child.pid });
     }
     handleWorkerData = (chunk) => {
@@ -455,10 +462,23 @@ export class StdioSupervisor {
             process.stderr.write(`${line}\n`);
         }
     };
-    handleWorkerProcessError = (error) => {
+    handleWorkerProcessError(child, error) {
         log("error", "supervisor.worker_process_error", { message: error.message });
-    };
-    handleWorkerExit = (code, signal) => {
+        if (child !== this.child) {
+            return;
+        }
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill("SIGTERM");
+        }
+        this.handleWorkerExit(child, null, null);
+    }
+    handleWorkerExit(child, code, signal) {
+        if (child !== this.child) {
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGTERM");
+            }
+            return;
+        }
         const childPid = this.child?.pid;
         this.detachChild();
         if (this.shuttingDown) {
@@ -472,7 +492,7 @@ export class StdioSupervisor {
         });
         this.failPendingRequestsOnWorkerExit({ code, signal });
         this.scheduleRestart();
-    };
+    }
     handleWorkerMessage(message) {
         debugSupervisor("worker_message", {
             hasMethod: "method" in message,
@@ -580,7 +600,7 @@ export class StdioSupervisor {
         }
     }
     failPendingRequestsOnWorkerExit(exit) {
-        const preservedInitializeKey = this.initializeRequest && !this.clientInitialized
+        const preservedInitializeKey = this.initializeRequest
             ? requestKey(this.initializeRequest.id)
             : undefined;
         const now = performance.now();
@@ -635,8 +655,8 @@ export class StdioSupervisor {
         child.stdout.off("data", this.handleWorkerData);
         child.stderr.off("data", this.handleWorkerStderr);
         child.stdin.off("error", this.handleWorkerStdinError);
-        child.off("error", this.handleWorkerProcessError);
-        child.off("exit", this.handleWorkerExit);
+        child.removeAllListeners("error");
+        child.removeAllListeners("exit");
         this.child = undefined;
         this.childReady = false;
     }

package/dist/storage/db.js

@@ -14,7 +14,7 @@ function runIntegrityCheck(db) {
         throw createError({
             code: ERROR_CODES.DB_FAILURE,
             message: "SQLite integrity check failed.",
-            details: { integrityCheck: result }
+            details: { reason: "integrity_check_failed", integrityCheck: result }
         });
     }
 }
@@ -47,6 +47,22 @@ 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;
+    }
+    const primaryErrcode = sqliteError.errcode & 0xff;
+    return primaryErrcode === SQLITE_CORRUPT_ERRCODE || primaryErrcode === SQLITE_NOTADB_ERRCODE;
+}
 function buildDefaultLogger() {
     return {
         warn: (message, details) => {
@@ -104,6 +120,13 @@ export function openDatabase(config, logger = buildDefaultLogger()) {
             throw caughtError;
         }
         if (!isMissingPath(config.sqlitePath)) {
+            if (!isCorruptionError(caughtError)) {
+                logger.error("SQLite initialization failed", {
+                    path: config.sqlitePath,
+                    reason: errorMessage
+                });
+                throw caughtError;
+            }
             const backupPath = backupCorruptedDb(config.sqlitePath);
             logger.warn("SQLite database integrity check failed. Recreated database after backup", {
                 sqlitePath: config.sqlitePath,

package/dist/storage/files-repo.d.ts

@@ -47,10 +47,14 @@ export declare class FilesRepo {
     private readonly listStmt;
     private readonly listRowsStmt;
     private readonly searchPathStmt;
+    private readonly searchContentLikePathsStmt;
     private readonly searchFtsStmt;
     private readonly getByPathsStmtCache;
     private readonly classLookupStmtCache;
+    private readonly dynamicStmtCache;
+    private static readonly DYNAMIC_STMT_CACHE_MAX;
     constructor(db: SqliteDatabase);
+    private prepareCached;
     clearFilesForArtifact(artifactId: string): void;
     insertFilesForArtifact(artifactId: string, files: IndexedFile[]): void;
     replaceFilesForArtifact(artifactId: string, files: IndexedFile[]): void;
@@ -58,6 +62,17 @@ export declare class FilesRepo {
     getFileContent(artifactId: string, filePath: string): FileRow | undefined;
     listFiles(artifactId: string, options: ListFilesOptions): PagedResult<string>;
     listFileRows(artifactId: string, options: ListFileRowsOptions): PagedResult<FileRow>;
+    /**
+     * Narrow the literal/contains text-scan candidate set without hydrating content:
+     * returns the file_paths whose content matches `content LIKE %needle%` (ASCII
+     * case-insensitive). The result is a SUPERSET of the JS contains/exact match set
+     * for an ASCII needle, so callers MUST still run the exact JS post-verify. Only
+     * file_path is selected — content stays in the DB until getFileContentsByPaths.
+     */
+    searchContentLikeCandidatePaths(artifactId: string, needle: string, limit: number): {
+        filePaths: string[];
+        scannedRows: number;
+    };
     getFileContentsByPaths(artifactId: string, filePaths: string[]): FileRow[];
     searchFileCandidates(artifactId: string, options: SearchFilesOptions): PagedResult<SearchFileCandidateResult> & {
         scannedRows: number;