@adhisang/minecraft-modding-mcp 6.1.1 → 6.3.0

package/dist/source/indexer.js

@@ -7,6 +7,7 @@ import { decompileBinaryJar } from "../decompiler/vineflower.js";
 import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import { log } from "../logger.js";
 import { resolveMojangTinyFile } from "../mojang-tiny-mapping-service.js";
+import { detectShellJarInventory } from "./nested-jars.js";
 import { iterateJavaEntriesAsUtf8 } from "../source-jar-reader.js";
 import { extractSymbolsFromSource } from "../symbols/symbol-extractor.js";
 import { remapJar } from "../tiny-remapper-service.js";
@@ -44,7 +45,11 @@ export async function indexArtifact(svc, input) {
     const artifact = svc.getArtifact(artifactId);
     const force = input.force ?? false;
     const meta = svc.indexMetaRepo.get(artifact.artifactId);
-    const hasFiles = meta ? meta.filesCount > 0 : false;
+    // Shell jars legitimately index zero files; without force they count as
+    // current instead of re-running shell detection on every reindex call.
+    const hasFiles = meta
+        ? meta.filesCount > 0 || artifact.qualityFlags.includes("shell-jar")
+        : false;
     const expectedSignature = artifact.artifactSignature ?? fallbackArtifactSignature(artifact.artifactId);
     const reason = resolveIndexRebuildReason({
         force,
@@ -180,8 +185,56 @@ export async function buildRebuiltArtifactData(svc, resolved) {
     let files = [];
     if (resolved.sourceJarPath) {
         files = await loadFromSourceJar(svc, resolved.sourceJarPath);
+        // Loom split-source pairs (common/clientOnly) publish the version across
+        // two sources jars; index the companion half too so neither side's
+        // classes go missing. The primary jar wins on duplicate paths. Note the
+        // artifact signature derives from the primary jar only: a regenerated
+        // companion lands at a new hash-addressed path, so persisted provenance
+        // can point at a deleted companion — that must degrade to a primary-only
+        // index, never fail the primary rebuild.
+        for (const companion of resolved.provenance?.companionSourceJars ?? []) {
+            let extra;
+            try {
+                extra = await loadFromSourceJar(svc, companion);
+            }
+            catch (companionError) {
+                log("warn", "index.companion_source_skipped", {
+                    artifactId: resolved.artifactId,
+                    companion,
+                    reason: companionError instanceof Error ? companionError.message : String(companionError)
+                });
+                continue;
+            }
+            const seenPaths = new Set(files.map((file) => file.filePath));
+            files.push(...extra.filter((file) => !seenPaths.has(file.filePath)));
+        }
     }
     else if (resolved.binaryJarPath) {
+        // Jar-in-Jar shells (near-zero own classes, all content in nested jars)
+        // would decompile to zero Java files and dead-end in
+        // ERR_DECOMPILER_FAILED. Detect them before remap/decompile: the artifact
+        // is created with an empty file index, the nested-jar inventory persisted
+        // in provenance, and class-family lookups redirect into the nested jars.
+        const shellInventory = await detectShellJarInventory(resolved.binaryJarPath);
+        if (shellInventory) {
+            const qualityFlags = resolved.qualityFlags ?? [];
+            resolved.qualityFlags = qualityFlags.includes("shell-jar")
+                ? qualityFlags
+                : [...qualityFlags, "shell-jar"];
+            if (resolved.provenance) {
+                // Mutate in place: resolveArtifact holds a reference to this object
+                // for its response, mirroring the binaryJarPath swap below.
+                resolved.provenance.nestedJars = shellInventory;
+            }
+            resolved.isDecompiled = false;
+            return {
+                files: [],
+                symbols: [],
+                totalContentBytes: 0,
+                indexedAt: new Date().toISOString(),
+                indexDurationMs: Date.now() - indexStartedAt
+            };
+        }
         const decompileInputJarPath = await maybeRemapBinaryForMojang(svc, resolved);
         // When the binary jar was remapped from obfuscated to mojang, swap the resolved
         // artifact's binaryJarPath to the remapped jar so downstream bytecode consumers
@@ -298,7 +351,11 @@ export async function ingestIfNeeded(svc, resolved) {
     // Derive hasFiles from meta instead of a separate listFiles probe: when meta is
     // absent the reason is "missing_meta" regardless of hasFiles, and when present
     // meta.filesCount is the authoritative count written alongside the file rows.
-    const hasFiles = meta ? meta.filesCount > 0 : false;
+    // Shell jars legitimately index zero files (their content lives in nested
+    // jars), so their empty index counts as current instead of forcing a
+    // re-detection rebuild on every warm resolve.
+    const existingIsShell = existing?.qualityFlags.includes("shell-jar") ?? false;
+    const hasFiles = meta ? meta.filesCount > 0 || existingIsShell : false;
     const reason = resolveIndexRebuildReason({
         force: false,
         expectedSignature: resolved.artifactSignature,
@@ -306,6 +363,19 @@ export async function ingestIfNeeded(svc, resolved) {
         meta
     });
     if (existing && reason === "already_current") {
+        if (existingIsShell) {
+            // Reconcile shell state onto the freshly-resolved object so warm-cache
+            // responses carry the same flag and inventory as the first resolve.
+            const qualityFlags = resolved.qualityFlags ?? [];
+            if (!qualityFlags.includes("shell-jar")) {
+                resolved.qualityFlags = [...qualityFlags, "shell-jar"];
+            }
+            const persistedInventory = existing.provenance?.nestedJars;
+            if (resolved.provenance && persistedInventory && !resolved.provenance.nestedJars) {
+                resolved.provenance.nestedJars = persistedInventory;
+            }
+            resolved.isDecompiled = false;
+        }
         // Mojang binary-remap reconciliation on the warm cache hit path:
         // resolveSourceTargetInternal always returns the original binary jar
         // (resolver does not know about prior remap output), so without this

package/dist/source/lifecycle/runtime-check.js

@@ -73,13 +73,16 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
             ]
         };
     }
-    const warnings = [
-        ...fallbackBase.warnings,
-        ...signature.warnings,
-        `Version ${version} is unobfuscated; validated symbol existence against runtime bytecode.`
-    ];
+    const warnings = [...fallbackBase.warnings, ...signature.warnings];
+    // Runtime validation is reported as the structured
+    // mappingContext.runtimeValidated flag instead of a per-response sentence.
+    const runtimeValidatedContext = {
+        ...fallbackBase.mappingContext,
+        runtimeValidated: true
+    };
     const buildResolved = (resolvedSymbol) => ({
         ...fallbackBase,
+        mappingContext: runtimeValidatedContext,
         querySymbol,
         resolved: true,
         status: "resolved",
@@ -96,6 +99,7 @@ export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbac
     });
     const buildUnresolved = (status) => ({
         ...fallbackBase,
+        mappingContext: runtimeValidatedContext,
         querySymbol,
         resolved: false,
         status,

package/dist/source/nested-jars.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A jar with at most this many own `.class` entries can qualify as a
+ * Jar-in-Jar shell. Real Fabric API umbrella jars carry zero to a handful of
+ * marker classes while every API class lives in META-INF/jars.
+ */
+export declare const SHELL_JAR_MAX_OUTER_CLASSES = 8;
+export declare const NESTED_JAR_CACHE_DIRNAME = "nested-jars";
+export interface NestedJarMatch {
+    entryName: string;
+    extractedPath: string;
+}
+export interface NestedClassMatch {
+    qualifiedName: string;
+    filePath: string;
+    line: number;
+    symbolKind: "class";
+}
+/**
+ * Finds exact class-name matches across a shell's nested bytecode inventory.
+ * Results use the same binary-backed class representation as entry-tool search:
+ * an inferred outer Java path, line 1, and the broad class symbol kind.
+ */
+export declare function findNestedJarClasses(args: {
+    cacheDir: string;
+    outerJarPath: string;
+    outerSignature: string;
+    inventory: string[];
+    className: string;
+    limit: number;
+}): Promise<NestedClassMatch[]>;
+/**
+ * Shell detection with both required signals: near-zero own classes AND
+ * bundled nested jars (META-INF/jars scan or fabric.mod.json "jars"
+ * declarations that really exist in the archive). Returns the inventory for
+ * shells and undefined for every regular jar.
+ */
+export declare function detectShellJarInventory(jarPath: string): Promise<string[] | undefined>;
+/**
+ * Content-addressed on-disk location of an extracted nested jar. The digest
+ * covers the outer jar path, its signature, and the entry name, so the same
+ * shell always maps to the same extracted file and re-resolution reuses it.
+ */
+export declare function nestedJarCachePath(cacheDir: string, outerJarPath: string, outerSignature: string, entryName: string): string;
+/**
+ * Extracts one nested jar to the content-addressed cache (no-op when already
+ * present). Entry-name safety is enforced by readJarEntryAsBuffer, and the
+ * on-disk name is the digest — never derived from the entry name — so a
+ * hostile entry name cannot escape the cache directory.
+ */
+export declare function extractNestedJar(cacheDir: string, outerJarPath: string, outerSignature: string, entryName: string): Promise<string>;
+/**
+ * Finds every nested jar of a shell that contains the class. Zero matches
+ * means the class genuinely is not bundled; more than one means the caller
+ * must return candidates instead of picking silently.
+ *
+ * The lookup is deliberately single-level: it inspects each nested jar's own
+ * class list only. A nested jar that is itself a shell surfaces its content
+ * when resolved directly as its own artifact.
+ */
+export declare function findNestedJarsContainingClass(args: {
+    cacheDir: string;
+    outerJarPath: string;
+    outerSignature: string;
+    inventory: string[];
+    internalName: string;
+}): Promise<NestedJarMatch[]>;
+/**
+ * Resolves the single nested jar containing a class. Zero matches returns
+ * undefined (the caller keeps its not-found contract); several matches throw
+ * candidates instead of picking one silently.
+ */
+export declare function resolveUniqueNestedJarForClass(args: {
+    cacheDir: string;
+    outerJarPath: string;
+    outerArtifactId: string;
+    inventory: string[];
+    className: string;
+}): Promise<NestedJarMatch | undefined>;

package/dist/source/nested-jars.js

@@ -0,0 +1,267 @@
+import { createHash, randomBytes } from "node:crypto";
+import { access, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { buildSuggestedCall } from "../build-suggested-call.js";
+import { ERROR_CODES, createError } from "../errors.js";
+import { collectNestedJars } from "../mod-analyzer.js";
+import { isSecureJarEntryPath } from "../path-resolver.js";
+import { listJarEntries, readJarEntryAsBuffer, readJarEntryAsUtf8 } from "../source-jar-reader.js";
+/**
+ * A jar with at most this many own `.class` entries can qualify as a
+ * Jar-in-Jar shell. Real Fabric API umbrella jars carry zero to a handful of
+ * marker classes while every API class lives in META-INF/jars.
+ */
+export const SHELL_JAR_MAX_OUTER_CLASSES = 8;
+export const NESTED_JAR_CACHE_DIRNAME = "nested-jars";
+// In-process cache of class listings per extracted nested jar, so repeated
+// class lookups against the same shell never re-open its nested jars. The
+// shell's own inventory is persisted with the artifact record; this cache is
+// only the per-nested-jar class membership.
+const classSetCache = new Map();
+const CLASS_SET_CACHE_MAX = 32;
+function rememberClassSet(key, value) {
+    classSetCache.delete(key);
+    classSetCache.set(key, value);
+    while (classSetCache.size > CLASS_SET_CACHE_MAX) {
+        const oldest = classSetCache.keys().next().value;
+        if (oldest === undefined) {
+            break;
+        }
+        classSetCache.delete(oldest);
+    }
+}
+async function loadNestedJarClassSet(args) {
+    let extractedPath;
+    try {
+        extractedPath = await extractNestedJar(args.cacheDir, args.outerJarPath, args.outerSignature, args.entryName);
+    }
+    catch {
+        return undefined;
+    }
+    let classSet = classSetCache.get(extractedPath);
+    if (!classSet) {
+        try {
+            const entries = await listJarEntries(extractedPath);
+            classSet = new Set(entries.filter((entry) => entry.endsWith(".class") && isSecureJarEntryPath(entry)));
+        }
+        catch {
+            return undefined;
+        }
+        rememberClassSet(extractedPath, classSet);
+    }
+    return { extractedPath, classSet };
+}
+function nestedClassMatch(entry) {
+    const internalName = entry.slice(0, -".class".length);
+    if (internalName.startsWith("META-INF/versions/")) {
+        return undefined;
+    }
+    const binarySimpleName = internalName.split("/").at(-1) ?? internalName;
+    if (binarySimpleName === "module-info" || binarySimpleName === "package-info") {
+        return undefined;
+    }
+    const innerSegments = binarySimpleName.split("$").slice(1);
+    if (innerSegments.some((segment) => segment.length === 0 || /^\d/.test(segment))) {
+        return undefined;
+    }
+    return {
+        qualifiedName: internalName.replaceAll("/", ".").replaceAll("$", "."),
+        filePath: `${internalName.split("$")[0]}.java`,
+        line: 1,
+        symbolKind: "class"
+    };
+}
+/**
+ * Finds exact class-name matches across a shell's nested bytecode inventory.
+ * Results use the same binary-backed class representation as entry-tool search:
+ * an inferred outer Java path, line 1, and the broad class symbol kind.
+ */
+export async function findNestedJarClasses(args) {
+    const normalizedQuery = args.className.trim().replaceAll("/", ".").replaceAll("$", ".");
+    const isQualified = normalizedQuery.includes(".");
+    const matches = new Map();
+    inventory: for (const entryName of args.inventory) {
+        const loaded = await loadNestedJarClassSet({
+            cacheDir: args.cacheDir,
+            outerJarPath: args.outerJarPath,
+            outerSignature: args.outerSignature,
+            entryName
+        });
+        if (!loaded) {
+            continue;
+        }
+        for (const classEntry of [...loaded.classSet].sort((left, right) => left.localeCompare(right))) {
+            const match = nestedClassMatch(classEntry);
+            if (!match) {
+                continue;
+            }
+            const simpleName = match.qualifiedName.split(".").at(-1) ?? match.qualifiedName;
+            if ((isQualified && match.qualifiedName !== normalizedQuery) ||
+                (!isQualified && simpleName !== normalizedQuery)) {
+                continue;
+            }
+            matches.set(match.qualifiedName, match);
+            if (isQualified || matches.size >= args.limit) {
+                break inventory;
+            }
+        }
+    }
+    return [...matches.values()];
+}
+/**
+ * Shell detection with both required signals: near-zero own classes AND
+ * bundled nested jars (META-INF/jars scan or fabric.mod.json "jars"
+ * declarations that really exist in the archive). Returns the inventory for
+ * shells and undefined for every regular jar.
+ */
+export async function detectShellJarInventory(jarPath) {
+    let entries;
+    try {
+        entries = await listJarEntries(jarPath);
+    }
+    catch {
+        return undefined;
+    }
+    let ownClassCount = 0;
+    for (const entry of entries) {
+        if (entry.endsWith(".class")) {
+            ownClassCount += 1;
+            if (ownClassCount > SHELL_JAR_MAX_OUTER_CLASSES) {
+                return undefined;
+            }
+        }
+    }
+    let declared;
+    if (entries.includes("fabric.mod.json")) {
+        try {
+            const parsed = JSON.parse(await readJarEntryAsUtf8(jarPath, "fabric.mod.json"));
+            const jars = parsed?.jars;
+            if (Array.isArray(jars)) {
+                declared = jars
+                    .map((entry) => entry?.file)
+                    .filter((file) => typeof file === "string");
+            }
+        }
+        catch {
+            // Unreadable metadata leaves only the META-INF/jars scan signal.
+        }
+    }
+    const inventory = collectNestedJars(entries, declared);
+    return inventory.length > 0 ? inventory : undefined;
+}
+/**
+ * Content-addressed on-disk location of an extracted nested jar. The digest
+ * covers the outer jar path, its signature, and the entry name, so the same
+ * shell always maps to the same extracted file and re-resolution reuses it.
+ */
+export function nestedJarCachePath(cacheDir, outerJarPath, outerSignature, entryName) {
+    const digest = createHash("sha256")
+        .update(`${outerJarPath}|${outerSignature}|${entryName}`)
+        .digest("hex");
+    return join(cacheDir, NESTED_JAR_CACHE_DIRNAME, `${digest}.jar`);
+}
+/**
+ * Extracts one nested jar to the content-addressed cache (no-op when already
+ * present). Entry-name safety is enforced by readJarEntryAsBuffer, and the
+ * on-disk name is the digest — never derived from the entry name — so a
+ * hostile entry name cannot escape the cache directory.
+ */
+export async function extractNestedJar(cacheDir, outerJarPath, outerSignature, entryName) {
+    const finalPath = nestedJarCachePath(cacheDir, outerJarPath, outerSignature, entryName);
+    try {
+        await access(finalPath);
+        return finalPath;
+    }
+    catch {
+        // fall through to extraction
+    }
+    const bytes = await readJarEntryAsBuffer(outerJarPath, entryName);
+    await mkdir(dirname(finalPath), { recursive: true });
+    const tempPath = `${finalPath}.tmp.${process.pid}.${Date.now()}.${randomBytes(6).toString("hex")}`;
+    await writeFile(tempPath, bytes);
+    try {
+        await rename(tempPath, finalPath);
+    }
+    catch (renameError) {
+        // A concurrent extraction of the same entry may have won the rename.
+        // The content-addressed final file being present makes this call a
+        // success; anything else is a real failure.
+        try {
+            await access(finalPath);
+        }
+        catch {
+            throw renameError;
+        }
+        await rm(tempPath, { force: true });
+    }
+    return finalPath;
+}
+/**
+ * Finds every nested jar of a shell that contains the class. Zero matches
+ * means the class genuinely is not bundled; more than one means the caller
+ * must return candidates instead of picking silently.
+ *
+ * The lookup is deliberately single-level: it inspects each nested jar's own
+ * class list only. A nested jar that is itself a shell surfaces its content
+ * when resolved directly as its own artifact.
+ */
+export async function findNestedJarsContainingClass(args) {
+    const classEntry = `${args.internalName}.class`;
+    const qualifiedName = args.internalName.replaceAll("/", ".").replaceAll("$", ".");
+    const matches = [];
+    for (const entryName of args.inventory) {
+        const loaded = await loadNestedJarClassSet({
+            cacheDir: args.cacheDir,
+            outerJarPath: args.outerJarPath,
+            outerSignature: args.outerSignature,
+            entryName
+        });
+        const containsClass = loaded?.classSet.has(classEntry) || [...(loaded?.classSet ?? [])].some((entry) => entry.endsWith(".class") &&
+            entry.slice(0, -".class".length).replaceAll("/", ".").replaceAll("$", ".") === qualifiedName);
+        if (loaded && containsClass) {
+            matches.push({ entryName, extractedPath: loaded.extractedPath });
+        }
+    }
+    return matches;
+}
+/**
+ * Resolves the single nested jar containing a class. Zero matches returns
+ * undefined (the caller keeps its not-found contract); several matches throw
+ * candidates instead of picking one silently.
+ */
+export async function resolveUniqueNestedJarForClass(args) {
+    const internalName = args.className.replace(/\./g, "/");
+    const matches = await findNestedJarsContainingClass({
+        cacheDir: args.cacheDir,
+        outerJarPath: args.outerJarPath,
+        outerSignature: args.outerArtifactId,
+        inventory: args.inventory,
+        internalName
+    });
+    if (matches.length === 0) {
+        return undefined;
+    }
+    const single = matches.length === 1 ? matches[0] : undefined;
+    if (single) {
+        return single;
+    }
+    throw createError({
+        code: ERROR_CODES.NESTED_JAR_AMBIGUOUS,
+        message: `Class "${args.className}" exists in ${matches.length} nested jars bundled by this shell jar; refusing to pick one automatically.`,
+        details: {
+            className: args.className,
+            shellArtifactId: args.outerArtifactId,
+            nestedJarCandidates: matches.map((match) => match.entryName),
+            nextAction: "Resolve the intended nested jar as its own artifact, then query the class against that artifactId.",
+            ...buildSuggestedCall({
+                tool: "resolve-artifact",
+                params: undefined,
+                examples: matches.map((match) => ({
+                    params: { target: { kind: "jar", value: match.extractedPath } },
+                    reason: `Query classes inside "${match.entryName}" directly.`
+                }))
+            })
+        }
+    });
+}
+//# sourceMappingURL=nested-jars.js.map

package/dist/source/workspace-target.js

@@ -243,7 +243,7 @@ export async function synthesizeDependencyTarget(svc, input, dep) {
             ? `Multiple cached versions for ${group}:${name} in ~/.gradle/caches/modules-2 (${result.candidatesSeen.join(", ")}); refusing to pick without project-specific evidence.`
             : `Could not resolve a version for dependency ${group}:${name} from gradle.properties or modules-2 cache.`;
         const nextAction = ambiguous
-            ? `Set ${name}_version (or another supported gradle.properties key) so the project's intended version is unambiguous, or pass an explicit version on the dependency target.`
+            ? `Set ${name}_version (or another supported gradle.properties key) so the project's intended version is unambiguous, pass an explicit version on the dependency target, or declare the umbrella version property so the cached umbrella POM can supply the submodule version.`
             : "Provide an explicit version on the dependency target, or add a property to gradle.properties so detectDependencyVersion can find it.";
         throw createError({
             code: ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED,
@@ -305,7 +305,10 @@ export async function synthesizeDependencyTarget(svc, input, dep) {
             source: result.source,
             candidatesSeen: result.candidatesSeen,
             attempts: result.attempts,
-            cacheHit: false
+            cacheHit: false,
+            ...(result.submoduleVersionSource
+                ? { submoduleVersionSource: result.submoduleVersionSource }
+                : {})
         }
     };
 }

package/dist/source-jar-reader.d.ts

@@ -3,6 +3,7 @@ export declare function __getZipOpenCount(): number;
 export declare function __resetZipOpenCount(): void;
 interface ZipEntry {
     fileName: string;
+    uncompressedSize: number;
 }
 export interface ZipFile {
     readEntry(): void;
@@ -38,6 +39,21 @@ export declare function listJavaEntries(jarPath: string): Promise<string[]>;
 export declare function hasAnyJarEntry(jarPath: string, predicate: (entryPath: string) => boolean): Promise<boolean>;
 export declare function readJarEntryAsUtf8(jarPath: string, entryPath: string): Promise<string>;
 export declare function readJarEntryAsBuffer(jarPath: string, entryPath: string): Promise<Buffer>;
+export interface CappedJarEntry {
+    /** At most the requested byte budget of the entry (empty when maxBytes<=0). */
+    buffer: Buffer;
+    /** Full uncompressed size from the zip metadata, independent of the cap. */
+    entrySize: number;
+}
+/**
+ * Reads at most maxBytes of one entry, reporting the full uncompressed size
+ * from the zip metadata. Unlike readJarEntryAsBuffer, an oversized entry is
+ * never fully materialized: the stream is destroyed once the budget is
+ * exceeded and the collected prefix is returned. maxBytes<=0 skips the read
+ * entirely (metadata-only probe).
+ */
+export declare function readJarEntryCapped(jarPath: string, entryPath: string, maxBytes: number): Promise<CappedJarEntry>;
+export declare function decodeJarEntryUtf8OrThrow(contentBuffer: Buffer, jarPath: string, entryPath: string): string;
 export interface JarEntryReader {
     getEntryBuffer(entryPath: string): Promise<Buffer>;
     close(): void;

package/dist/source-jar-reader.js

@@ -203,6 +203,88 @@ export async function readJarEntryAsBuffer(jarPath, entryPath) {
         }
     });
 }
+/**
+ * Reads at most maxBytes of one entry, reporting the full uncompressed size
+ * from the zip metadata. Unlike readJarEntryAsBuffer, an oversized entry is
+ * never fully materialized: the stream is destroyed once the budget is
+ * exceeded and the collected prefix is returned. maxBytes<=0 skips the read
+ * entirely (metadata-only probe).
+ */
+export async function readJarEntryCapped(jarPath, entryPath, maxBytes) {
+    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 }
+        });
+    }
+    return withZipFile(jarPath, async (zipFile) => {
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                throw createError({
+                    code: ERROR_CODES.SOURCE_NOT_FOUND,
+                    message: `Entry "${normalizedTargetPath}" was not found in "${jarPath}".`,
+                    details: { jarPath, entryPath: normalizedTargetPath }
+                });
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (entry.fileName !== normalizedTargetPath) {
+                continue;
+            }
+            const entrySize = entry.uncompressedSize;
+            if (maxBytes <= 0) {
+                return { buffer: Buffer.alloc(0), entrySize };
+            }
+            const buffer = await readEntryStreamPrefix(zipFile, entry, jarPath, maxBytes);
+            return { buffer: buffer.length > maxBytes ? buffer.slice(0, maxBytes) : buffer, entrySize };
+        }
+    });
+}
+/** Like readEntryStream, but resolves with the collected prefix instead of rejecting when the budget is exceeded. */
+function readEntryStreamPrefix(zipFile, entry, jarPath, maxBytes) {
+    return new Promise((resolve, reject) => {
+        zipFile.openReadStream(entry, (error, stream) => {
+            if (error || !stream) {
+                reject(new Error(`Failed to read entry "${entry.fileName}" from "${jarPath}": ${toErrorMessage(error)}`));
+                return;
+            }
+            let settled = false;
+            let totalBytes = 0;
+            const chunks = [];
+            stream.on("data", (chunk) => {
+                if (settled)
+                    return;
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                totalBytes += buf.length;
+                chunks.push(buf);
+                if (totalBytes >= maxBytes) {
+                    settled = true;
+                    stream.destroy();
+                    resolve(Buffer.concat(chunks));
+                }
+            });
+            stream.once("error", (streamError) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new Error(`Failed to read entry "${entry.fileName}" from "${jarPath}": ${toErrorMessage(streamError)}`));
+            });
+            stream.once("end", () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(Buffer.concat(chunks));
+            });
+        });
+    });
+}
+export function decodeJarEntryUtf8OrThrow(contentBuffer, jarPath, entryPath) {
+    return decodeUtf8OrThrow(contentBuffer, 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