@adhisang/minecraft-modding-mcp 1.2.1 → 2.1.0

package/dist/registry-service.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
@@ -6,6 +6,40 @@ import { createError, ERROR_CODES } from "./errors.js";
 import { log } from "./logger.js";
 const DATAGEN_TIMEOUT_MS = 5 * 60 * 1000;
 const MAX_STDIO_SNAPSHOT = 6_240;
+function clampPositiveInt(value) {
+    if (!Number.isFinite(value) || value == null) {
+        return undefined;
+    }
+    return Math.max(1, Math.trunc(value));
+}
+function sortedRegistryEntryNames(entries) {
+    return Object.keys(entries).sort((left, right) => left.localeCompare(right));
+}
+function limitRegistryEntries(data, maxEntries) {
+    const entryNames = sortedRegistryEntryNames(data.entries);
+    const total = entryNames.length;
+    if (maxEntries == null || total <= maxEntries) {
+        return {
+            data,
+            total,
+            returned: total,
+            truncated: false
+        };
+    }
+    const limitedEntries = {};
+    for (const entryName of entryNames.slice(0, maxEntries)) {
+        limitedEntries[entryName] = data.entries[entryName];
+    }
+    return {
+        data: {
+            default: data.default,
+            entries: limitedEntries
+        },
+        total,
+        returned: maxEntries,
+        truncated: true
+    };
+}
 function limitOutput(text) {
     if (text.length <= MAX_STDIO_SNAPSHOT)
         return text;
@@ -25,6 +59,31 @@ function findRegistryFile(registryDir) {
     }
     return undefined;
 }
+function parseRegistrySnapshot(raw, version, registryFile) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw createError({
+            code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
+            message: `Failed to parse registries.json for version "${version}".`,
+            details: {
+                version,
+                registryFile,
+                reason: error instanceof Error ? error.message : String(error)
+            }
+        });
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw createError({
+            code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
+            message: `registries.json for version "${version}" has invalid structure.`,
+            details: { version, registryFile }
+        });
+    }
+    return parsed;
+}
 function runDataGen(serverJarPath, outputDir, version) {
     return new Promise((resolve, reject) => {
         // MC 1.18+ uses bundler format, older versions use -cp with main class directly.
@@ -131,6 +190,12 @@ export class RegistryService {
         const warnings = [];
         const allRegistries = await this.loadRegistries(version, warnings);
         const registryNames = Object.keys(allRegistries).sort();
+        const includeData = input.includeData ?? true;
+        const maxEntriesPerRegistry = clampPositiveInt(input.maxEntriesPerRegistry);
+        const registryEntryCounts = Object.fromEntries(registryNames.map((registryName) => [
+            registryName,
+            Object.keys(allRegistries[registryName].entries).length
+        ]));
         if (input.registry) {
             const registryName = normalizeRegistryName(input.registry);
             const data = allRegistries[registryName];
@@ -145,11 +210,17 @@ export class RegistryService {
                     }
                 });
             }
+            const limited = limitRegistryEntries(data, maxEntriesPerRegistry);
             return {
                 version,
                 registry: registryName,
-                data,
-                entryCount: Object.keys(data.entries).length,
+                ...(includeData ? { data: limited.data } : {}),
+                entryCount: limited.total,
+                returnedEntryCount: includeData ? limited.returned : 0,
+                registryEntryCounts: {
+                    [registryName]: limited.total
+                },
+                ...(limited.truncated ? { dataTruncated: true } : {}),
                 warnings
             };
         }
@@ -157,11 +228,25 @@ export class RegistryService {
         for (const registry of Object.values(allRegistries)) {
             totalEntries += Object.keys(registry.entries).length;
         }
+        let returnedEntryCount = 0;
+        let dataTruncated = false;
+        const limitedData = {};
+        if (includeData) {
+            for (const registryName of registryNames) {
+                const limited = limitRegistryEntries(allRegistries[registryName], maxEntriesPerRegistry);
+                limitedData[registryName] = limited.data;
+                returnedEntryCount += limited.returned;
+                dataTruncated ||= limited.truncated;
+            }
+        }
         return {
             version,
             registries: registryNames,
-            data: allRegistries,
+            ...(includeData ? { data: limitedData } : {}),
             entryCount: totalEntries,
+            returnedEntryCount: includeData ? returnedEntryCount : 0,
+            registryEntryCounts,
+            ...(dataTruncated ? { dataTruncated: true } : {}),
             warnings
         };
     }
@@ -170,31 +255,79 @@ export class RegistryService {
         if (cached)
             return cached;
         const registryDir = join(this.config.cacheDir, "registries", version);
-        // Check if we already have generated data
-        let registryFile = findRegistryFile(registryDir);
+        const cachedRegistries = this.loadExistingRegistries(registryDir, version, warnings);
+        if (cachedRegistries) {
+            this.cacheRegistries(version, cachedRegistries);
+            return cachedRegistries;
+        }
+        await mkdir(registryDir, { recursive: true });
+        const serverJar = await this.versionService.resolveServerJar(version);
+        await runDataGen(serverJar.jarPath, registryDir, version);
+        const registryFile = findRegistryFile(registryDir);
         if (!registryFile) {
-            await mkdir(registryDir, { recursive: true });
-            const serverJar = await this.versionService.resolveServerJar(version);
-            await runDataGen(serverJar.jarPath, registryDir, version);
-            registryFile = findRegistryFile(registryDir);
-            if (!registryFile) {
-                throw createError({
-                    code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
-                    message: `Registry data generation did not produce registries.json for version "${version}".`,
-                    details: { version, registryDir }
+            throw createError({
+                code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
+                message: `Registry data generation did not produce registries.json for version "${version}".`,
+                details: { version, registryDir }
+            });
+        }
+        const parsed = this.readRegistryFileOrThrow(registryFile, version);
+        this.cacheRegistries(version, parsed);
+        return parsed;
+    }
+    loadExistingRegistries(registryDir, version, warnings) {
+        for (const candidate of resolveRegistryPaths(registryDir)) {
+            if (!existsSync(candidate)) {
+                continue;
+            }
+            try {
+                return this.readRegistryFileOrThrow(candidate, version);
+            }
+            catch (error) {
+                if (!this.isInvalidRegistrySnapshot(error)) {
+                    throw error;
+                }
+                warnings.push(`Ignored corrupt cached registry snapshot and regenerated it: ${candidate}`);
+                log("warn", "registry.cache.invalidated", {
+                    version,
+                    registryFile: candidate,
+                    reason: error.message
                 });
+                try {
+                    rmSync(candidate, { force: true });
+                }
+                catch {
+                    // best-effort cleanup
+                }
             }
         }
-        const raw = readFileSync(registryFile, "utf8");
-        const parsed = JSON.parse(raw);
-        // Validate structure
-        if (typeof parsed !== "object" || parsed === null) {
+        return undefined;
+    }
+    readRegistryFileOrThrow(registryFile, version) {
+        let raw;
+        try {
+            raw = readFileSync(registryFile, "utf8");
+        }
+        catch (error) {
             throw createError({
                 code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
-                message: `registries.json for version "${version}" has invalid structure.`,
-                details: { version }
+                message: `Failed to read registries.json for version "${version}".`,
+                details: {
+                    version,
+                    registryFile,
+                    reason: error instanceof Error ? error.message : String(error)
+                }
             });
         }
+        return parseRegistrySnapshot(raw, version, registryFile);
+    }
+    isInvalidRegistrySnapshot(error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === ERROR_CODES.REGISTRY_GENERATION_FAILED);
+    }
+    cacheRegistries(version, parsed) {
         this.registryCache.set(version, parsed);
         // Trim cache to avoid unbounded growth
         if (this.registryCache.size > 8) {
@@ -202,7 +335,6 @@ export class RegistryService {
             if (oldest !== undefined)
                 this.registryCache.delete(oldest);
         }
-        return parsed;
     }
 }
 function normalizeRegistryName(name) {

package/dist/resources.js

@@ -30,7 +30,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, e.message);
+                return errorResource(uri.href, { message: e.message, code: e.code });
             throw e;
         }
     });
@@ -41,7 +41,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, e.message);
+                return errorResource(uri.href, { message: e.message, code: e.code });
             throw e;
         }
     });
@@ -56,7 +56,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, e.message);
+                return errorResource(uri.href, { message: e.message, code: e.code });
             throw e;
         }
     });
@@ -70,7 +70,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, e.message);
+                return errorResource(uri.href, { message: e.message, code: e.code });
             throw e;
         }
     });
@@ -87,7 +87,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, e.message);
+                return errorResource(uri.href, { message: e.message, code: e.code });
             throw e;
         }
     });
@@ -101,7 +101,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, e.message);
+                return errorResource(uri.href, { message: e.message, code: e.code });
             throw e;
         }
     });
@@ -112,7 +112,7 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, e.message);
+                return errorResource(uri.href, { message: e.message, code: e.code });
             throw e;
         }
     });

package/dist/search-hit-accumulator.d.ts

@@ -9,9 +9,6 @@ export type SearchSourceHit = {
     filePath: string;
     score: number;
     matchedIn: "symbol" | "path" | "content";
-    startLine: number;
-    endLine: number;
-    snippet: string;
     reasonCodes: string[];
     symbol?: SearchResultSymbol;
 };

package/dist/search-hit-accumulator.js

@@ -12,8 +12,8 @@ export function scoreHitOrder(left, right) {
     if (symbolCompare !== 0) {
         return symbolCompare;
     }
-    const leftLine = left.symbol?.line ?? left.startLine;
-    const rightLine = right.symbol?.line ?? right.startLine;
+    const leftLine = left.symbol?.line ?? 0;
+    const rightLine = right.symbol?.line ?? 0;
     return leftLine - rightLine;
 }
 export function encodeSearchCursor(hit, contextKey) {
@@ -21,7 +21,7 @@ export function encodeSearchCursor(hit, contextKey) {
         score: hit.score,
         filePath: hit.filePath,
         symbolName: hit.symbol?.symbolName ?? "",
-        line: hit.symbol?.line ?? hit.startLine,
+        line: hit.symbol?.line ?? 0,
         contextKey
     }), "utf8").toString("base64");
 }
@@ -66,7 +66,7 @@ export function isAfterSearchCursor(hit, cursor) {
     if (symbolCompare < 0) {
         return false;
     }
-    const hitLine = hit.symbol?.line ?? hit.startLine;
+    const hitLine = hit.symbol?.line ?? 0;
     return hitLine > cursor.line;
 }
 /**
@@ -107,6 +107,21 @@ function heapSiftUp(heap, index) {
         index = parent;
     }
 }
+function heapPopWorst(heap) {
+    if (heap.length === 0) {
+        return undefined;
+    }
+    const root = heap[0];
+    const tail = heap.pop();
+    if (heap.length === 0) {
+        return root;
+    }
+    if (tail) {
+        heap[0] = tail;
+        heapSiftDown(heap, 0, heap.length);
+    }
+    return root;
+}
 export function createSearchHitAccumulator(limit, cursor) {
     const pageLimit = Math.max(1, limit);
     const keepLimit = pageLimit + 1;
@@ -141,8 +156,14 @@ export function createSearchHitAccumulator(limit, cursor) {
             return heap.length;
         },
         finalize() {
-            // Sort heap contents by scoreHitOrder (best first)
-            const sorted = heap.slice().sort(scoreHitOrder);
+            const sorted = new Array(heap.length);
+            const heapCopy = heap.slice();
+            for (let index = heapCopy.length - 1; index >= 0; index -= 1) {
+                const next = heapPopWorst(heapCopy);
+                if (next) {
+                    sorted[index] = next;
+                }
+            }
             const page = sorted.slice(0, pageLimit);
             const hasMore = totalAfterCursor > page.length;
             return {

package/dist/source-jar-reader.js

@@ -9,6 +9,20 @@ function toErrorMessage(value) {
     }
     return String(value);
 }
+function hasJavaSourceExtension(entryPath) {
+    const suffix = ".java";
+    if (entryPath.length < suffix.length) {
+        return false;
+    }
+    for (let index = 0; index < suffix.length; index += 1) {
+        const charCode = entryPath.charCodeAt(entryPath.length - suffix.length + index);
+        const normalizedCharCode = charCode >= 65 && charCode <= 90 ? charCode + 32 : charCode;
+        if (normalizedCharCode !== suffix.charCodeAt(index)) {
+            return false;
+        }
+    }
+    return true;
+}
 function openZipFile(jarPath) {
     return new Promise((resolve, reject) => {
         yauzl.open(jarPath, {
@@ -128,7 +142,7 @@ export async function listJarEntries(jarPath) {
 }
 export async function listJavaEntries(jarPath) {
     const entries = await listJarEntries(jarPath);
-    return entries.filter((entry) => entry.toLowerCase().endsWith(".java") && isSecureJarEntryPath(entry));
+    return entries.filter((entry) => hasJavaSourceExtension(entry) && isSecureJarEntryPath(entry));
 }
 export async function readJarEntryAsUtf8(jarPath, entryPath) {
     const contentBuffer = await readJarEntryAsBuffer(jarPath, entryPath);
@@ -171,7 +185,7 @@ export async function* iterateJavaEntriesAsUtf8(jarPath, maxBytes) {
             if (!entry) {
                 break;
             }
-            if (!entry.fileName.toLowerCase().endsWith(".java")) {
+            if (!hasJavaSourceExtension(entry.fileName)) {
                 continue;
             }
             if (!isSecureJarEntryPath(entry.fileName)) {

package/dist/source-resolver.d.ts

@@ -1,6 +1,7 @@
 import type { Config, ResolvedSourceArtifact, SourceTargetInput } from "./types.js";
 export interface ResolveSourceTargetOptions {
     allowDecompile: boolean;
+    preferBinaryOnly?: boolean;
     preferredRepos?: string[];
     onRepoFailover?: (event: {
         stage: "source" | "binary";

package/dist/source-resolver.js

@@ -1,5 +1,7 @@
 import { readdirSync } from "node:fs";
 import { basename, dirname, join, resolve as resolvePath } from "node:path";
+import { homedir } from "node:os";
+import fastGlob from "fast-glob";
 import { createError, ERROR_CODES } from "./errors.js";
 import { buildRemoteBinaryUrls, buildRemoteSourceUrls, hasExistingJar, parseCoordinate, normalizedCoordinateValue } from "./maven-resolver.js";
 import { defaultDownloadPath, downloadToCache } from "./repo-downloader.js";
@@ -23,6 +25,16 @@ function resolveExactJarSourceCandidate(inputJarPath) {
     const base = jarName.endsWith(".jar") ? jarName.slice(0, -4) : jarName;
     return join(directory, `${base}-sources.jar`);
 }
+function resolveSiblingBinaryJarCandidate(inputJarPath) {
+    const directory = dirname(inputJarPath);
+    const jarName = basename(inputJarPath);
+    if (!jarName.endsWith("-sources.jar")) {
+        return undefined;
+    }
+    const binaryName = `${jarName.slice(0, -"-sources.jar".length)}.jar`;
+    const candidate = join(directory, binaryName);
+    return hasExistingJar(candidate) ? candidate : undefined;
+}
 function listAdjacentJarSourceCandidates(inputJarPath) {
     const directory = dirname(inputJarPath);
     const exact = resolveExactJarSourceCandidate(inputJarPath);
@@ -59,6 +71,66 @@ function resolveLocalCoordinateCandidates(localM2Path, coordinate) {
     }
     return [...existing];
 }
+function resolveLocalCoordinateBinaryCandidate(localM2Path, coordinate) {
+    const parsed = parseCoordinate(coordinate);
+    const groupPath = parsed.groupId.replace(/\./g, "/");
+    const baseDir = resolvePath(localM2Path, groupPath, parsed.artifactId, parsed.version);
+    const base = `${parsed.artifactId}-${parsed.version}`;
+    const classifierSuffix = parsed.classifier ? `-${parsed.classifier}` : "";
+    const candidates = [
+        resolvePath(baseDir, `${base}${classifierSuffix}.jar`),
+        ...(classifierSuffix ? [resolvePath(baseDir, `${base}.jar`)] : [])
+    ];
+    return candidates.find((candidate) => hasExistingJar(candidate));
+}
+function resolveGradleUserHome() {
+    const configured = process.env.GRADLE_USER_HOME?.trim();
+    if (configured) {
+        return configured;
+    }
+    return resolvePath(homedir(), ".gradle");
+}
+function resolveGradleCacheCoordinateCandidate(coordinate) {
+    const parsed = parseCoordinate(coordinate);
+    const baseDir = resolvePath(resolveGradleUserHome(), "caches", "modules-2", "files-2.1", parsed.groupId, parsed.artifactId, parsed.version);
+    const base = `${parsed.artifactId}-${parsed.version}`;
+    const classifierSuffix = parsed.classifier ? `-${parsed.classifier}` : "";
+    const preferredSourceNames = [
+        `${base}${classifierSuffix}-sources.jar`,
+        ...(classifierSuffix ? [`${base}-sources.jar`] : [])
+    ];
+    const preferredBinaryNames = [
+        `${base}${classifierSuffix}.jar`,
+        ...(classifierSuffix ? [`${base}.jar`] : [])
+    ];
+    let discoveredFiles = [];
+    try {
+        discoveredFiles = fastGlob.sync("*/*", {
+            cwd: baseDir,
+            absolute: true,
+            onlyFiles: true
+        });
+    }
+    catch {
+        return undefined;
+    }
+    discoveredFiles = discoveredFiles.filter((entry) => hasExistingJar(entry)).sort((left, right) => left.localeCompare(right));
+    const pickFirst = (candidates) => {
+        for (const fileName of candidates) {
+            const match = discoveredFiles.find((entry) => basename(entry) === fileName);
+            if (match) {
+                return match;
+            }
+        }
+        return undefined;
+    };
+    const sourceJarPath = pickFirst(preferredSourceNames);
+    const binaryJarPath = pickFirst(preferredBinaryNames);
+    if (!sourceJarPath && !binaryJarPath) {
+        return undefined;
+    }
+    return { sourceJarPath, binaryJarPath };
+}
 function resolveRemoteBinaryCandidate(coordinate, repos) {
     return buildRemoteBinaryUrls(repos, coordinate);
 }
@@ -80,19 +152,23 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
         const exactSourceJarPath = resolveExactJarSourceCandidate(resolvedJarPath);
         const adjacentSourceCandidates = listAdjacentJarSourceCandidates(resolvedJarPath);
         const maybeAdjacentSourceCandidates = adjacentSourceCandidates.length > 0 ? adjacentSourceCandidates : undefined;
+        const preferBinaryOnly = options.preferBinaryOnly ?? false;
         if (await hasJavaSources(resolvedJarPath)) {
+            const siblingBinaryJarPath = resolveSiblingBinaryJarCandidate(resolvedJarPath);
+            const binaryJarPath = siblingBinaryJarPath ??
+                (basename(resolvedJarPath).endsWith("-sources.jar") ? undefined : resolvedJarPath);
             return {
                 artifactId: artifactIdForJar("jar", resolvedJarPath, binarySignature),
                 artifactSignature: binarySignature,
                 origin: "local-jar",
-                binaryJarPath: resolvedJarPath,
+                binaryJarPath,
                 sourceJarPath: resolvedJarPath,
                 adjacentSourceCandidates: maybeAdjacentSourceCandidates,
                 isDecompiled: false,
                 resolvedAt: resolvedAtNow()
             };
         }
-        if (await hasJavaSources(exactSourceJarPath)) {
+        if (!preferBinaryOnly && await hasJavaSources(exactSourceJarPath)) {
             const sourceSignature = readStatsSignature(exactSourceJarPath);
             return {
                 artifactId: artifactIdForJar("jar", exactSourceJarPath, sourceSignature),
@@ -142,12 +218,27 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
                 artifactSignature: signature,
                 origin: "local-m2",
                 sourceJarPath: candidate,
+                binaryJarPath: resolveLocalCoordinateBinaryCandidate(explicitConfig.localM2Path, coordinate),
                 coordinate,
                 isDecompiled: false,
                 resolvedAt: resolvedAtNow()
             };
         }
     }
+    const gradleCacheCandidate = resolveGradleCacheCoordinateCandidate(coordinate);
+    if (gradleCacheCandidate?.sourceJarPath && (await hasJavaSources(gradleCacheCandidate.sourceJarPath))) {
+        const signature = readStatsSignature(gradleCacheCandidate.sourceJarPath);
+        return {
+            artifactId: artifactIdForCoordinate(coordinate, "local-m2", signature),
+            artifactSignature: signature,
+            origin: "local-m2",
+            sourceJarPath: gradleCacheCandidate.sourceJarPath,
+            binaryJarPath: gradleCacheCandidate.binaryJarPath,
+            coordinate,
+            isDecompiled: false,
+            resolvedAt: resolvedAtNow()
+        };
+    }
     const remoteSourceUrls = buildRemoteSourceUrls(repos, coordinate);
     for (let index = 0; index < remoteSourceUrls.length; index++) {
         const sourceUrl = remoteSourceUrls[index];