@adhisang/minecraft-modding-mcp 6.1.1 → 6.3.0

package/dist/source/class-source.js

@@ -6,7 +6,9 @@ import * as artifactResolver from "./artifact-resolver.js";
 import * as classSourceHelpers from "./class-source-helpers.js";
 import { buildClassSourceSnippet } from "./class-source/snippet-builder.js";
 import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire, projectMembersByLevel } from "./class-source/members-builder.js";
+import { collectDidYouMeanCandidates } from "./did-you-mean.js";
 import { matchesMemberPattern } from "./member-pattern.js";
+import { findNestedJarClasses, resolveUniqueNestedJarForClass } from "./nested-jars.js";
 import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
@@ -80,6 +82,14 @@ function obfuscatedNamespaceHint(className) {
 function hasPartialNetMinecraftCoverage(qualityFlags) {
     return qualityFlags.includes("partial-source-no-net-minecraft");
 }
+function shouldSuggestObfuscatedMapping(artifact, className) {
+    const nativeDependency = artifact.provenance?.dependencyResolution != null;
+    const shellArtifact = artifact.qualityFlags.includes("shell-jar");
+    return (artifact.mappingApplied === "obfuscated" &&
+        !nativeDependency &&
+        !shellArtifact &&
+        looksLikeDeobfuscatedClassName(className));
+}
 function classNameToClassPath(className) {
     const normalized = normalizePathStyle(className.trim()).replace(/\//g, ".");
     const segments = normalized.split(".").filter((segment) => segment.length > 0);
@@ -165,7 +175,7 @@ export function buildFallbackProvenance(svc, input) {
         transformChain
     };
 }
-export function buildClassSourceNotFoundError(_svc, input) {
+export function buildClassSourceNotFoundError(svc, input) {
     const simpleName = input.className.split(/[.$]/).at(-1) ?? input.className;
     const details = {
         artifactId: input.artifactId,
@@ -177,7 +187,11 @@ export function buildClassSourceNotFoundError(_svc, input) {
         ...(input.scope ? { scope: input.scope } : {}),
         ...(input.targetKind ? { targetKind: input.targetKind } : {}),
         ...(input.targetValue ? { targetValue: input.targetValue } : {}),
-        ...(input.attemptedBinaryFallback ? { binaryFallbackAttempted: true } : {})
+        ...(input.attemptedBinaryFallback ? { binaryFallbackAttempted: true } : {}),
+        ...(input.nestedJars && input.nestedJars.length > 0 ? { nestedJars: input.nestedJars } : {}),
+        // Candidates are hints from the symbol index, never assertions that the
+        // class exists at the suggested location; empty when nothing usable.
+        didYouMean: collectDidYouMeanCandidates(svc, input.artifactId, input.className)
     };
     let nextAction = `Use find-class to resolve the correct fully-qualified name for "${simpleName}".`;
     let suggestionSpec = {
@@ -220,6 +234,29 @@ export function buildClassSourceNotFoundError(_svc, input) {
     }
     details.nextAction = nextAction;
     Object.assign(details, buildSuggestedCall(suggestionSpec));
+    // Split-source workspaces can omit client-only classes from merged indexes;
+    // the vanilla scope decompiles the client jar, which contains them. Offer
+    // the retry as an example using existing scope enum values only.
+    if (input.targetKind === "version" && input.version && input.scope !== "vanilla") {
+        const scopeRetry = buildSuggestedCall({
+            tool: "get-class-source",
+            params: undefined,
+            examples: [
+                {
+                    params: {
+                        className: input.className,
+                        target: { kind: "version", value: input.version },
+                        scope: "vanilla"
+                    },
+                    reason: "Client-only classes can be missing from merged split-source indexes; scope \"vanilla\" decompiles the client jar, which contains them."
+                }
+            ]
+        });
+        if (scopeRetry.exampleCalls?.length) {
+            const existing = Array.isArray(details.exampleCalls) ? details.exampleCalls : [];
+            details.exampleCalls = [...existing, ...scopeRetry.exampleCalls];
+        }
+    }
     return createError({
         code: ERROR_CODES.CLASS_NOT_FOUND,
         message: `Source for class "${input.className}" was not found.`,
@@ -369,7 +406,7 @@ export function findClass(svc, input) {
         if (filteredMatches.length === 0 && partialVanillaLookup) {
             warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
         }
-        if (filteredMatches.length === 0 && artifact.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(className)) {
+        if (filteredMatches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
             warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
         }
         return { matches: filteredMatches, total: filteredMatches.length, warnings };
@@ -403,11 +440,39 @@ export function findClass(svc, input) {
     if (filteredMatches.length === 0 && partialVanillaLookup) {
         warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
     }
-    if (filteredMatches.length === 0 && artifact.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(className)) {
+    if (filteredMatches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
         warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
     }
     return { matches: filteredMatches, total: filteredMatches.length, warnings };
 }
+export async function findClassIncludingNested(svc, input) {
+    const indexed = findClass(svc, input);
+    if (indexed.total > 0) {
+        return indexed;
+    }
+    const artifact = svc.getArtifact(input.artifactId.trim());
+    const inventory = artifact.provenance?.nestedJars;
+    if (!artifact.qualityFlags.includes("shell-jar") ||
+        !artifact.binaryJarPath ||
+        !inventory ||
+        inventory.length === 0) {
+        return indexed;
+    }
+    const limit = Math.max(1, Math.min(input.limit ?? 20, 200));
+    const matches = await findNestedJarClasses({
+        cacheDir: svc.config.cacheDir,
+        outerJarPath: artifact.binaryJarPath,
+        outerSignature: artifact.artifactId,
+        inventory,
+        className: input.className,
+        limit
+    });
+    return {
+        matches,
+        total: matches.length,
+        warnings: indexed.warnings
+    };
+}
 export async function getClassSource(svc, input) {
     const className = input.className.trim();
     if (!className) {
@@ -547,6 +612,53 @@ export async function getClassSource(svc, input) {
         }
         return true;
     };
+    let attemptedNestedJarRedirect = false;
+    const tryNestedJarRedirect = async (lookupClassName) => {
+        if (attemptedNestedJarRedirect) {
+            return false;
+        }
+        const inventory = activeProvenance?.nestedJars;
+        const outerJarPath = normalizeOptionalString(binaryJarPath);
+        if (!inventory || inventory.length === 0 || !outerJarPath) {
+            return false;
+        }
+        attemptedNestedJarRedirect = true;
+        const shellArtifactId = activeArtifactId;
+        const match = await resolveUniqueNestedJarForClass({
+            cacheDir: svc.config.cacheDir,
+            outerJarPath,
+            outerArtifactId: shellArtifactId,
+            inventory,
+            className: lookupClassName
+        });
+        if (!match) {
+            return false;
+        }
+        const redirectResolved = await svc.resolveArtifact({
+            target: { kind: "jar", value: match.extractedPath },
+            mapping: input.mapping,
+            sourcePriority: input.sourcePriority,
+            allowDecompile: input.allowDecompile,
+            projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome
+        });
+        activeArtifactId = redirectResolved.artifactId;
+        activeOrigin = redirectResolved.origin;
+        activeMappingApplied = redirectResolved.mappingApplied ?? activeMappingApplied;
+        activeProvenance = redirectResolved.provenance
+            ? {
+                ...redirectResolved.provenance,
+                nestedJar: { entryName: match.entryName, shellArtifactId }
+            }
+            : activeProvenance;
+        activeQualityFlags = dedupeQualityFlags([
+            ...redirectResolved.qualityFlags,
+            "nested-jar-redirect"
+        ]);
+        activeSourceJarPath = redirectResolved.resolvedSourceJarPath;
+        warnings.push(`Class "${className}" lives in nested jar "${match.entryName}" bundled by the shell jar; the lookup was redirected there automatically.`);
+        return true;
+    };
     let activeLookupClassName = await svc.resolveClassNameForLookup({
         className,
         version,
@@ -558,6 +670,9 @@ export async function getClassSource(svc, input) {
         context: "source lookup"
     });
     let filePath = resolveClassFilePath(svc, activeArtifactId, activeLookupClassName);
+    if (!filePath && (await tryNestedJarRedirect(activeLookupClassName))) {
+        filePath = resolveClassFilePath(svc, activeArtifactId, activeLookupClassName);
+    }
     if (!filePath && (await tryBinaryFallback())) {
         activeLookupClassName = await svc.resolveClassNameForLookup({
             className,
@@ -584,10 +699,18 @@ export async function getClassSource(svc, input) {
             targetValue: input.target && "value" in input.target ? input.target.value : undefined,
             scope: input.scope,
             projectPath: input.projectPath,
-            version
+            version,
+            nestedJars: activeProvenance?.nestedJars
         });
     }
     let row = svc.filesRepo.getFileContent(activeArtifactId, filePath);
+    if (!row && (await tryNestedJarRedirect(activeLookupClassName))) {
+        const redirectedFilePath = resolveClassFilePath(svc, activeArtifactId, activeLookupClassName);
+        if (redirectedFilePath) {
+            filePath = redirectedFilePath;
+            row = svc.filesRepo.getFileContent(activeArtifactId, filePath);
+        }
+    }
     if (!row && (await tryBinaryFallback())) {
         activeLookupClassName = await svc.resolveClassNameForLookup({
             className,
@@ -616,7 +739,8 @@ export async function getClassSource(svc, input) {
             targetValue: input.target && "value" in input.target ? input.target.value : undefined,
             scope: input.scope,
             projectPath: input.projectPath,
-            version
+            version,
+            nestedJars: activeProvenance?.nestedJars
         });
     }
     const snippet = buildClassSourceSnippet({
@@ -841,22 +965,67 @@ export async function getClassMembers(svc, input) {
     let signatureMethods;
     let binaryExtractionFailed = false;
     let binaryExtractionFailureReason;
+    let nestedJarRedirect;
+    const fetchSignature = (jarPath) => svc.explorerService.getSignature({
+        fqn: lookupClassName,
+        jarPath,
+        access,
+        includeSynthetic,
+        includeInherited,
+        memberPattern: requestedMapping === mappingApplied ? memberPattern : undefined
+    });
     try {
-        const signature = await svc.explorerService.getSignature({
-            fqn: lookupClassName,
-            jarPath: binaryJarPath,
-            access,
-            includeSynthetic,
-            includeInherited,
-            memberPattern: requestedMapping === mappingApplied ? memberPattern : undefined
-        });
+        let signature;
+        try {
+            signature = await fetchSignature(binaryJarPath);
+        }
+        catch (missError) {
+            const inventory = provenance?.nestedJars;
+            if (!isAppError(missError) ||
+                missError.code !== ERROR_CODES.CLASS_NOT_FOUND ||
+                !inventory ||
+                inventory.length === 0) {
+                throw missError;
+            }
+            const match = await resolveUniqueNestedJarForClass({
+                cacheDir: svc.config.cacheDir,
+                outerJarPath: binaryJarPath,
+                outerArtifactId: artifactId,
+                inventory,
+                className: lookupClassName
+            });
+            if (!match) {
+                throw missError;
+            }
+            nestedJarRedirect = { entryName: match.entryName, shellArtifactId: artifactId };
+            warnings.push(`Class "${className}" lives in nested jar "${match.entryName}" bundled by the shell jar; members were read from it.`);
+            signature = await fetchSignature(match.extractedPath);
+        }
         warnings.push(...signature.warnings);
         signatureContext = signature.context;
-        signatureConstructors = signature.constructors;
-        signatureFields = signature.fields;
-        signatureMethods = signature.methods;
+        // Member annotations are opt-in: strip them unless requested. The
+        // annotationDefault of annotation-type members is always kept. Cached
+        // signature objects must not be mutated, so stripping copies.
+        const stripAnnotations = (member) => {
+            if (!member.annotations) {
+                return member;
+            }
+            const { annotations: _omitted, ...rest } = member;
+            return rest;
+        };
+        const includeAnnotations = input.includeAnnotations ?? false;
+        signatureConstructors = includeAnnotations
+            ? signature.constructors
+            : signature.constructors.map(stripAnnotations);
+        signatureFields = includeAnnotations ? signature.fields : signature.fields.map(stripAnnotations);
+        signatureMethods = includeAnnotations ? signature.methods : signature.methods.map(stripAnnotations);
     }
     catch (error) {
+        if (isAppError(error) && error.code === ERROR_CODES.NESTED_JAR_AMBIGUOUS) {
+            // A class living in several nested jars needs the caller's choice; the
+            // candidates error must not degrade into a members_unavailable response.
+            throw error;
+        }
         if (isAppError(error) && error.code === ERROR_CODES.CLASS_NOT_FOUND) {
             // Re-raise with the shared recovery shape (find-class/api-matrix
             // suggestedCall, namespace + scope hints) instead of the sparse bytecode
@@ -873,7 +1042,8 @@ export async function getClassMembers(svc, input) {
                 targetValue: input.target && "value" in input.target ? input.target.value : undefined,
                 scope: input.scope,
                 projectPath: input.projectPath,
-                version
+                version,
+                nestedJars: provenance?.nestedJars
             });
         }
         binaryExtractionFailed = true;
@@ -926,13 +1096,16 @@ export async function getClassMembers(svc, input) {
     const projectedMembers = projectMembersByLevel(projectMembersForWire({ constructors, fields, methods }, includeInherited, input.includeDescriptors ?? false), projection);
     const truncated = sliced.truncated;
     const nextCursor = sliced.nextOffset != null ? encodeOffsetCursor(sliced.nextOffset, memberCursorContext) : undefined;
-    const normalizedProvenance = provenance ??
+    const baseProvenance = provenance ??
         buildFallbackProvenance(svc, {
             artifactId,
             origin,
             requestedMapping,
             mappingApplied
         });
+    const normalizedProvenance = nestedJarRedirect
+        ? { ...baseProvenance, nestedJar: nestedJarRedirect }
+        : baseProvenance;
     let decompiledFallback;
     let decompiledMemberCounts;
     let fallbackQualityFlags = qualityFlags;

package/dist/source/did-you-mean.d.ts

@@ -0,0 +1,14 @@
+import type { SourceService } from "../source-service.js";
+export interface DidYouMeanCandidate {
+    className: string;
+    matchReason: string;
+}
+/**
+ * Collects ranked near-miss class candidates from the artifact's symbol
+ * index for a class that was not found: exact simple-name matches first
+ * (the moved-FQN case), then case-insensitive matches, then bounded
+ * edit-distance suggestions. Candidates are hints, never assertions that the
+ * class exists at the suggested location. Returns an empty array when the
+ * index has nothing usable.
+ */
+export declare function collectDidYouMeanCandidates(svc: SourceService, artifactId: string, className: string): DidYouMeanCandidate[];

package/dist/source/did-you-mean.js

@@ -0,0 +1,79 @@
+import { levenshteinDistance, suggestSimilar } from "../mixin/helpers.js";
+const TYPE_SYMBOL_KINDS = ["class", "interface", "enum", "record"];
+const MAX_CANDIDATES = 8;
+// Near-miss candidates come from a bounded prefix pool: typos inside the
+// first characters are rare compared to suffix/mid-word slips, and an
+// unbounded scan over every type symbol would not stay index-backed.
+const EDIT_DISTANCE_POOL_PREFIX = 4;
+function fqnOfRow(row) {
+    return row.qualifiedName ?? row.filePath.replace(/\.java$/, "").replaceAll("/", ".");
+}
+/**
+ * Collects ranked near-miss class candidates from the artifact's symbol
+ * index for a class that was not found: exact simple-name matches first
+ * (the moved-FQN case), then case-insensitive matches, then bounded
+ * edit-distance suggestions. Candidates are hints, never assertions that the
+ * class exists at the suggested location. Returns an empty array when the
+ * index has nothing usable.
+ */
+export function collectDidYouMeanCandidates(svc, artifactId, className) {
+    try {
+        const simpleName = className.split(/[.$]/).at(-1) ?? className;
+        if (!simpleName) {
+            return [];
+        }
+        const out = [];
+        const seen = new Set([className]);
+        const push = (fqn, matchReason) => {
+            if (seen.has(fqn) || out.length >= MAX_CANDIDATES) {
+                return;
+            }
+            seen.add(fqn);
+            out.push({ className: fqn, matchReason });
+        };
+        const exact = svc.symbolsRepo.findScopedSymbols({
+            artifactId,
+            query: simpleName,
+            match: "exact",
+            symbolKinds: TYPE_SYMBOL_KINDS,
+            limit: 50
+        });
+        for (const row of exact.items) {
+            push(fqnOfRow(row), "exact-simple-name");
+        }
+        // One index-backed prefix query (lower(symbol_name) LIKE 'pref%') feeds
+        // both the case-insensitive and the edit-distance tiers: a case variant
+        // shares the lowercased prefix, and a leading-wildcard `contains` scan
+        // would defeat the symbol-name index on every not-found error.
+        const prefixPool = svc.symbolsRepo.findScopedSymbols({
+            artifactId,
+            query: simpleName.slice(0, EDIT_DISTANCE_POOL_PREFIX),
+            match: "prefix",
+            symbolKinds: TYPE_SYMBOL_KINDS,
+            limit: 200
+        });
+        for (const row of prefixPool.items) {
+            if (row.symbolName === simpleName)
+                continue;
+            if (row.symbolName.toLowerCase() !== simpleName.toLowerCase())
+                continue;
+            push(fqnOfRow(row), "case-insensitive");
+        }
+        const poolNames = [...new Set(prefixPool.items.map((row) => row.symbolName))];
+        for (const suggestion of suggestSimilar(simpleName, poolNames)) {
+            const distance = levenshteinDistance(simpleName.toLowerCase(), suggestion.toLowerCase());
+            for (const row of prefixPool.items) {
+                if (row.symbolName !== suggestion)
+                    continue;
+                push(fqnOfRow(row), `edit-distance:${distance}`);
+            }
+        }
+        return out;
+    }
+    catch {
+        // Candidate collection must never turn the not-found error into a
+        // different failure; a broken index simply yields no suggestions.
+        return [];
+    }
+}
+//# sourceMappingURL=did-you-mean.js.map

package/dist/source/file-access.js

@@ -1,6 +1,64 @@
-import { ERROR_CODES, createError } from "../errors.js";
+import { basename } from "node:path";
+import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import { log } from "../logger.js";
+import { decodeJarEntryUtf8OrThrow, listJarEntries, readJarEntryCapped } from "../source-jar-reader.js";
 import { normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
+// Read-through delivery for non-indexed jar resources: text files under these
+// prefixes are served directly from the backing jar when the source index has
+// no row for them. The per-file cap bounds response size; binary entries
+// answer with metadata only.
+const READ_THROUGH_PREFIXES = ["assets/", "data/"];
+const READ_THROUGH_MAX_BYTES = 512 * 1024;
+const READ_THROUGH_TEXT_EXTENSIONS = new Set([
+    ".json",
+    ".mcmeta",
+    ".txt",
+    ".properties",
+    ".lang",
+    ".cfg",
+    ".toml",
+    ".snbt",
+    ".yml",
+    ".yaml",
+    ".csv",
+    ".md",
+    ".fsh",
+    ".vsh",
+    ".glsl"
+]);
+const NEARBY_PATH_HINT_LIMIT = 5;
+function isTraversalShapedPath(filePath) {
+    return (filePath.startsWith("/") ||
+        filePath.includes("\u0000") ||
+        filePath.split(/[\\/]/).includes(".."));
+}
+function hasReadThroughPrefix(filePath) {
+    return READ_THROUGH_PREFIXES.some((prefix) => filePath.startsWith(prefix));
+}
+function readThroughTextExtension(filePath) {
+    const dot = filePath.lastIndexOf(".");
+    if (dot < 0) {
+        return false;
+    }
+    return READ_THROUGH_TEXT_EXTENSIONS.has(filePath.slice(dot).toLowerCase());
+}
+/**
+ * Same-basename entries elsewhere in the jar, for not-found hints. Covers
+ * directory relocations across versions (e.g. assets/minecraft/models/item/*
+ * moving to assets/minecraft/items/*).
+ */
+async function collectNearbyPaths(binaryJarPath, missingPath) {
+    try {
+        const wanted = basename(missingPath);
+        const entries = await listJarEntries(binaryJarPath);
+        return entries
+            .filter((entry) => hasReadThroughPrefix(entry) && basename(entry) === wanted)
+            .slice(0, NEARBY_PATH_HINT_LIMIT);
+    }
+    catch {
+        return [];
+    }
+}
 function clampLimit(limit, fallback, max) {
     if (limit === undefined || limit === null) {
         return fallback;
@@ -24,8 +82,28 @@ function truncateUtf8ToMaxBytes(content, maxBytes) {
 export async function getArtifactFile(svc, input) {
     const startedAt = Date.now();
     try {
+        if (isTraversalShapedPath(input.filePath)) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `filePath "${input.filePath}" must be a plain in-archive path (no absolute paths or ".." segments).`,
+                details: {
+                    filePath: input.filePath,
+                    nextAction: "Pass the entry path exactly as it appears inside the jar, e.g. assets/minecraft/models/block/stone.json."
+                }
+            });
+        }
         const artifact = svc.getArtifact(input.artifactId);
-        const row = svc.filesRepo.getFileContent(artifact.artifactId, normalizePathStyle(input.filePath));
+        const normalizedPath = normalizePathStyle(input.filePath);
+        const row = svc.filesRepo.getFileContent(artifact.artifactId, normalizedPath);
+        if (!row && hasReadThroughPrefix(normalizedPath) && artifact.binaryJarPath) {
+            return await readFileThroughJar(svc, {
+                artifact,
+                binaryJarPath: artifact.binaryJarPath,
+                filePath: normalizedPath,
+                maxBytes: input.maxBytes,
+                artifactId: input.artifactId
+            });
+        }
         if (!row) {
             throw createError({
                 code: ERROR_CODES.FILE_NOT_FOUND,
@@ -65,6 +143,84 @@ export async function getArtifactFile(svc, input) {
         svc.metrics.recordDuration("get_file_duration_ms", Date.now() - startedAt);
     }
 }
+async function readFileThroughJar(svc, args) {
+    const { artifact, binaryJarPath, filePath, artifactId } = args;
+    const isText = readThroughTextExtension(filePath);
+    const cap = isText
+        ? Math.min(clampLimit(args.maxBytes, svc.config.maxContentBytes, Number.MAX_SAFE_INTEGER), READ_THROUGH_MAX_BYTES)
+        : 0;
+    let capped;
+    try {
+        // Read at most the cap (+ slack to trim back to a UTF-8 boundary); an
+        // oversized entry is never fully materialized in memory. Binary entries
+        // are metadata-only probes (no content read at all).
+        capped = await readJarEntryCapped(binaryJarPath, filePath, isText ? cap + 4 : 0);
+    }
+    catch (error) {
+        if (!isAppError(error) || error.code !== ERROR_CODES.SOURCE_NOT_FOUND) {
+            // Unsafe paths and unreadable/corrupt jars are their own failures;
+            // only a genuinely-missing entry becomes file-not-found with hints.
+            throw error;
+        }
+        const nearbyPaths = await collectNearbyPaths(binaryJarPath, filePath);
+        throw createError({
+            code: ERROR_CODES.FILE_NOT_FOUND,
+            message: `File "${filePath}" was not found in the source index or the backing jar.`,
+            details: {
+                artifactId,
+                filePath,
+                ...(nearbyPaths.length > 0
+                    ? {
+                        nearbyPaths,
+                        nextAction: `Same-named entries exist at: ${nearbyPaths.join(", ")}. Directory layouts move between versions; retry with one of those paths.`
+                    }
+                    : {})
+            }
+        });
+    }
+    const base = {
+        filePath,
+        mappingApplied: artifact.mappingApplied ?? "obfuscated",
+        returnedNamespace: artifact.mappingApplied ?? "obfuscated",
+        artifactContents: svc.buildArtifactContentsSummary({
+            origin: artifact.origin,
+            sourceJarPath: artifact.sourceJarPath,
+            isDecompiled: artifact.isDecompiled,
+            qualityFlags: artifact.qualityFlags
+        }),
+        deliveryMode: "jar-read-through"
+    };
+    if (!isText) {
+        return {
+            ...base,
+            content: "",
+            contentBytes: capped.entrySize,
+            truncated: false,
+            contentOmittedReason: "Entry is not a known text format; binary content is not delivered. Size and existence are reported instead."
+        };
+    }
+    const truncated = capped.entrySize > cap;
+    let content;
+    if (truncated) {
+        // Trim the capped prefix back to a UTF-8 character boundary before
+        // decoding; the tail past the cap is dropped by design.
+        const buffer = capped.buffer;
+        let cut = Math.min(cap, buffer.length);
+        while (cut > 0 && ((buffer[cut] ?? 0) & 0xc0) === 0x80) {
+            cut -= 1;
+        }
+        content = buffer.slice(0, cut).toString("utf8");
+    }
+    else {
+        content = decodeJarEntryUtf8OrThrow(capped.buffer, binaryJarPath, filePath);
+    }
+    return {
+        ...base,
+        content,
+        contentBytes: capped.entrySize,
+        truncated
+    };
+}
 export async function listArtifactFiles(svc, input) {
     const startedAt = Date.now();
     try {
@@ -81,7 +237,7 @@ export async function listArtifactFiles(svc, input) {
         if (normalizedPrefix &&
             page.items.length === 0 &&
             (normalizedPrefix.startsWith("assets/") || normalizedPrefix.startsWith("data/"))) {
-            warnings.push("Indexed artifacts currently include Java source only; non-Java resources are not indexed. Inspect the original jar on disk if you need assets or data files.");
+            warnings.push("Indexed artifacts currently include Java source only; non-Java resources are not indexed. Text files under assets/ and data/ are served directly from the backing jar — request them by exact path with get-artifact-file (read-through delivery).");
         }
         return {
             items: page.items,