@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.1

package/dist/mod-decompile-service.js

@@ -135,7 +135,17 @@ export class ModDecompileService {
             const outPath = isAbsolute(input.outputFile)
                 ? input.outputFile
                 : resolvePath(input.outputFile);
-            await writeFile(outPath, content, "utf8");
+            try {
+                await writeFile(outPath, content, "utf8");
+            }
+            catch (writeError) {
+                const errno = writeError?.code;
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `outputFile "${outPath}" could not be written (${errno ?? "unknown error"}).`,
+                    details: { field: "outputFile", value: outPath, osErrorCode: errno }
+                });
+            }
             outputFilePath = outPath;
             content = `[Written to ${outPath}]`;
         }

package/dist/mod-remap-service.js

@@ -149,13 +149,13 @@ export async function remapModJar(input, config, deps = {}) {
     mkdirSync(cacheDir, { recursive: true });
     const cachedOutput = join(cacheDir, `${cacheKey}.jar`);
     if (!input.forceRemap && existsSync(cachedOutput)) {
-        const cacheHitOutputJar = input.outputJar
-            ? outputJar
-            : cachedOutput;
-        copyJarToDestination(cachedOutput, cacheHitOutputJar);
-        log("info", "remap.cache-hit", { inputJar: normalizedInput, outputJar: cacheHitOutputJar });
+        // Always copy to the same `outputJar` location a cold run would use (the
+        // caller-supplied path, or resolveOutputJarPath's "next to input" default),
+        // so a cache hit and a cold run return the same path convention.
+        copyJarToDestination(cachedOutput, outputJar);
+        log("info", "remap.cache-hit", { inputJar: normalizedInput, outputJar });
         return {
-            outputJar: cacheHitOutputJar,
+            outputJar,
             mcVersion,
             fromMapping: fromNamespace,
             targetMapping: input.targetMapping,

package/dist/nbt/java-nbt-codec.js

@@ -480,7 +480,13 @@ export function decodeJavaNbt(buffer) {
                 throw error;
             }
         }
-        throw parseError("Failed to decode Java NBT payload.");
+        // Unlike every other parseError() call site in this module, nothing here
+        // has an offset to report - do not inherit PARSE_NEXT_ACTION's "at the
+        // reported offset" promise.
+        throw parseError("Failed to decode Java NBT payload.", {
+            nextAction: "The payload is not a well-formed Java NBT stream. Check that nbtBase64 holds the whole " +
+                'file and that compression matches how it was written (use compression "auto" to detect gzip).'
+        });
     }
 }
 export function encodeJavaNbt(document) {

package/dist/source/access-validate.js

@@ -80,6 +80,16 @@ export async function validateAccessWidener(svc, input) {
     if (!content.trim()) {
         throw createError({ code: ERROR_CODES.INVALID_INPUT, message: "content must be non-empty." });
     }
+    // Fabric Loader also reads the classTweaker format; it is out of scope here rather than an
+    // accessWidener file with a bad header, so it gets no verdict.
+    const header = content.split(/\r?\n/).map((line) => line.trim()).find((line) => line && !line.startsWith("#"));
+    if (header && /^classTweaker(\s|$)/.test(header)) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `The classTweaker format is not supported (header "${header}"); only accessWidener v1/v2 files can be validated.`,
+            details: { unsupportedFormat: "classTweaker", header }
+        });
+    }
     const warnings = [];
     const parsed = parseAccessWidener(content);
     const headerNamespaceRaw = normalizeOptionalString(parsed.namespace);

package/dist/source/artifact-resolver.d.ts

@@ -1,3 +1,4 @@
+import { type JavaSourceScan } from "../source-jar-reader.js";
 import type { SourceService } from "../source-service.js";
 import type { ArtifactContentsSummary, ProbeMinecraftArtifactInput, ProbeMinecraftArtifactOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
 import type { AccessTransformerNamespace, ArtifactProvenance, ArtifactScope, ArtifactTargetKind, ResolvedSourceArtifact, RuntimeLoader, RuntimeValidationProvenance, SourceMapping } from "../types.js";
@@ -139,10 +140,31 @@ export declare function hasLoaderRuntimeVersionToken(path: string, mcVersion: st
 /**
  * Minecraft version a runtime jar path carries, or undefined when the path
  * names none. Loom lays its cache out as
- * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first `1.x[.y]` token
- * of the path is the version the jar was built for.
+ * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first token of the
+ * tool-written part of the path ({@link runtimeJarLayoutTail}; the whole path
+ * when it enters no layout root) that names a Minecraft version is the version the jar was built for — in
+ * either id family, and a pre-release names itself and not the release it
+ * precedes. Reading only `1.x[.y]` left every 26.x jar versionless, so no
+ * approximation was ever reported for one.
+ *
+ * A legacy `1.x` token is self-identifying; a 26.1+ token shares its shape with
+ * every loader's own version number, so it additionally has to sit where
+ * {@link tokenPositionNamesMinecraft} says Minecraft's version sits.
  */
 export declare function inferRuntimeJarMinecraftVersion(path: string): string | undefined;
+/**
+ * The Minecraft version a `kind: "jar"` target PROVES it is the unobfuscated
+ * runtime of, or undefined. The file path is never evidence: Loom and other
+ * tools lay jars out in ways that path heuristics have misread before.
+ *
+ * All three must hold: the walk met no `.java` entry, the jar ships
+ * `net/minecraft/SharedConstants.class`, and its root `version.json` parses with a
+ * string `id` that `isUnobfuscatedVersion` accepts. The id is put to that test
+ * only once the other two hold, so it is the id a Minecraft `version.json`
+ * declares, never a library's own release number. A Loom-mapped 1.x jar carries
+ * both signals too; its `1.x` id is what keeps it out. The path is never read.
+ */
+export declare function provenUnobfuscatedRuntimeJarVersion(scan: JavaSourceScan | undefined): string | undefined;
 /**
  * Loader a runtime jar belongs to, read from the tool-written part of its path.
  *
@@ -163,7 +185,9 @@ export declare function inferRuntimeJarLoader(path: string): RuntimeLoader;
  * `version` becomes the version the SERVED jar carries; the caller's original
  * request is preserved under `requestedVersion` and flagged. A served loader
  * that contradicts a KNOWN expected loader is flagged too — never silently
- * dropped.
+ * dropped. When the jar's path names no version at all, the request stands as
+ * the answer and nothing is flagged: there is no served version to contradict
+ * it with.
  */
 export declare function describeServedRuntimeJar(input: {
     jarPath: string;

package/dist/source/artifact-resolver.js

@@ -170,16 +170,30 @@ export function looksLikeMinecraftArtifactPath(path) {
 function looksLikeMinecraftSourceArtifact(path, hasMinecraftNamespace) {
     return hasMinecraftNamespace || looksLikeMinecraftArtifactPath(path);
 }
+/**
+ * What a Minecraft version id may be FOLLOWED by and still be the same id:
+ * nothing. A pre-release suffix extends the id rather than decorating it —
+ * `26.1-pre-1` is its own version and not `26.1` — so the hyphen forms Mojang
+ * publishes (`-pre1`, `-rc1`, `-pre-6`, `-rc-2`, `-snapshot-6`) have to close
+ * the token as firmly as a trailing digit does. Any OTHER hyphen is ordinary
+ * path decoration (`minecraft-1.21.1-merged.jar`) and must keep matching.
+ *
+ * The suffix grammar is `isUnobfuscatedVersion`'s in version-service.ts; the
+ * two are read together whenever either changes.
+ */
+const VERSION_ID_SUFFIX_LOOKAHEAD = "-(?:pre|rc)[0-9]|-(?:pre|rc|snapshot)-[0-9]";
 export function hasExactVersionToken(path, version) {
     const normalizedPath = normalizePathStyle(path).toLowerCase();
     const normalizedVersion = version.trim().toLowerCase();
     if (!normalizedVersion) {
         return false;
     }
-    // Avoid prefix false-positives like "1.21.1" matching "1.21.10".
-    const cached = VERSION_TOKEN_REGEX_CACHE.get(normalizedVersion);
+    // Avoid prefix false-positives like "1.21.1" matching "1.21.10", and
+    // pre-release false-positives like "26.1" matching "26.1-pre-1".
+    const cacheKey = normalizedVersion;
+    const cached = VERSION_TOKEN_REGEX_CACHE.get(cacheKey);
     const pattern = cached
-        ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, normalizedVersion, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}(?![0-9a-z]|\\.[0-9])`, "i"));
+        ?? rememberCachedRegex(VERSION_TOKEN_REGEX_CACHE, cacheKey, new RegExp(`(^|[^0-9a-z])${escapeRegexLiteral(normalizedVersion)}(?![0-9a-z]|\\.[0-9]|${VERSION_ID_SUFFIX_LOOKAHEAD})`, "i"));
     return pattern.test(normalizedPath);
 }
 /**
@@ -209,15 +223,119 @@ export function hasLoaderRuntimeVersionToken(path, mcVersion) {
         ?? rememberCachedRegex(LOADER_VERSION_TOKEN_REGEX_CACHE, cacheKey, new RegExp(`(^|[^0-9a-z.])${minor}\\.${patch}\\.\\d`, "i"));
     return pattern.test(normalizedPath);
 }
-const RUNTIME_JAR_VERSION_REGEX = /(?:^|[^0-9.])(1\.\d+(?:\.\d+)?)(?![0-9.])/;
+/**
+ * Every version-SHAPED token a path carries, in both id families: `<a>.<b>[.<c>]`
+ * with an optional pre-release suffix, and the `YYwNNa` snapshot form. Shape
+ * only — `inferRuntimeJarMinecraftVersion` decides which of them is Minecraft's.
+ *
+ * The alternatives are greedy, so the LONGEST token at a position is the one
+ * offered, suffix included. What closes it is another version component — a
+ * digit, or a dot that starts one — and nothing else: a dot that starts a file
+ * extension ends the token instead. Refusing every following dot made
+ * `minecraft-merged-26.1.jar` name no version and made
+ * `minecraft-merged-26.2-pre-6.jar` backtrack off its own suffix down to
+ * "26.2", the release that jar is not.
+ */
+const RUNTIME_JAR_VERSION_TOKEN_REGEX = /(?:^|[^0-9.])(\d+\.\d+(?:\.\d+)?(?:-(?:pre|rc)\d+|-(?:pre|rc|snapshot)-\d+)?|\d{2}w\d{2}[a-z])(?![0-9]|\.[0-9])/g;
+/** The legacy obfuscated line, `1.21` / `1.21.10` / `1.14.4-pre7`. */
+const LEGACY_MINECRAFT_VERSION_REGEX = /^1\.\d+(?:\.\d+)?(?:-(?:pre|rc)\d+|-(?:pre|rc|snapshot)-\d+)?$/;
+/** Loom's cache root: the directory whose immediate children are Minecraft versions. */
+const LOOM_CACHE_ROOT_SEGMENT_REGEX = /^(?:fabric-loom|loom-cache)$/;
+/**
+ * Does the path POSITION a 26.1+ token sits at vouch for it being Minecraft's
+ * version?
+ *
+ * The new-format grammar is only a shape: `isUnobfuscatedVersion` accepts any
+ * id from year 26 up, and Forge's own versions have long since passed it
+ * (`forge-47.3.0-srg.jar`), so the token needs the same kind of corroboration
+ * the loader-version exclusions elsewhere in this file rely on. Three positions
+ * carry it, and they are the layouts the discovery helpers already walk: the
+ * artifact itself names Minecraft (`minecraft-merged-26.1.jar`), the entry
+ * directly inside the version directory does (neoformruntime's
+ * `<version>/minecraft-joined.jar`), or the version directory is a child of
+ * Loom's cache root (`<...>/fabric-loom/<mcVersion>/`).
+ *
+ * Only the token's own neighbourhood counts, never an ancestor — for the reason
+ * `runtimeJarLayoutRelativePath` exists: a checkout under `~/dev/minecraft/`
+ * names the user's directory, not the jar.
+ */
+function tokenPositionNamesMinecraft(segments, index) {
+    return ((segments[index]?.includes("minecraft") ?? false) ||
+        (segments[index + 1]?.includes("minecraft") ?? false) ||
+        LOOM_CACHE_ROOT_SEGMENT_REGEX.test(segments[index - 1] ?? ""));
+}
 /**
  * Minecraft version a runtime jar path carries, or undefined when the path
  * names none. Loom lays its cache out as
- * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first `1.x[.y]` token
- * of the path is the version the jar was built for.
+ * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first token of the
+ * tool-written part of the path ({@link runtimeJarLayoutTail}; the whole path
+ * when it enters no layout root) that names a Minecraft version is the version the jar was built for — in
+ * either id family, and a pre-release names itself and not the release it
+ * precedes. Reading only `1.x[.y]` left every 26.x jar versionless, so no
+ * approximation was ever reported for one.
+ *
+ * A legacy `1.x` token is self-identifying; a 26.1+ token shares its shape with
+ * every loader's own version number, so it additionally has to sit where
+ * {@link tokenPositionNamesMinecraft} says Minecraft's version sits.
  */
 export function inferRuntimeJarMinecraftVersion(path) {
-    return RUNTIME_JAR_VERSION_REGEX.exec(normalizePathStyle(path))?.[1];
+    // A path that enters no layout root, such as a custom Gradle home's `loom-cache`, is read whole.
+    const normalizedPath = runtimeJarLayoutTail(path) ?? normalizePathStyle(path).toLowerCase();
+    const segments = normalizedPath.split("/");
+    for (const match of normalizedPath.matchAll(RUNTIME_JAR_VERSION_TOKEN_REGEX)) {
+        const token = match[1];
+        if (!token) {
+            continue;
+        }
+        if (LEGACY_MINECRAFT_VERSION_REGEX.test(token)) {
+            return token;
+        }
+        if (!isUnobfuscatedVersion(token)) {
+            continue;
+        }
+        // `match[0]` carries the leading boundary character, so the token starts at
+        // its end minus the token's own length.
+        const tokenStart = (match.index ?? 0) + match[0].length - token.length;
+        const segmentIndex = normalizedPath.slice(0, tokenStart).split("/").length - 1;
+        if (tokenPositionNamesMinecraft(segments, segmentIndex)) {
+            return token;
+        }
+    }
+    return undefined;
+}
+/**
+ * The Minecraft version a `kind: "jar"` target PROVES it is the unobfuscated
+ * runtime of, or undefined. The file path is never evidence: Loom and other
+ * tools lay jars out in ways that path heuristics have misread before.
+ *
+ * All three must hold: the walk met no `.java` entry, the jar ships
+ * `net/minecraft/SharedConstants.class`, and its root `version.json` parses with a
+ * string `id` that `isUnobfuscatedVersion` accepts. The id is put to that test
+ * only once the other two hold, so it is the id a Minecraft `version.json`
+ * declares, never a library's own release number. A Loom-mapped 1.x jar carries
+ * both signals too; its `1.x` id is what keeps it out. The path is never read.
+ */
+export function provenUnobfuscatedRuntimeJarVersion(scan) {
+    const signals = scan?.minecraftRuntimeSignals;
+    if (!scan || scan.hasJavaSources || !signals?.hasSharedConstantsClass || signals.versionJsonText === undefined) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(signals.versionJsonText);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return undefined;
+    }
+    const id = parsed.id;
+    if (typeof id !== "string") {
+        return undefined;
+    }
+    const version = id.trim();
+    return isUnobfuscatedVersion(version) ? version : undefined;
 }
 /**
  * Segment that opens a directory tree a BUILD TOOL wrote: a dot-directory
@@ -237,6 +355,10 @@ const RUNTIME_JAR_LAYOUT_ROOT_RE = /^(?:\.[^/]*|caches|build)$/;
  * loader for an artifact that names none.
  */
 function runtimeJarLayoutRelativePath(path) {
+    return runtimeJarLayoutTail(path) ?? normalizePathStyle(path).toLowerCase().split("/").filter(Boolean).at(-1) ?? "";
+}
+/** Everything below the deepest layout root, or undefined when the path enters none. */
+function runtimeJarLayoutTail(path) {
     const segments = normalizePathStyle(path)
         .toLowerCase()
         .split("/")
@@ -246,7 +368,7 @@ function runtimeJarLayoutRelativePath(path) {
             return segments.slice(index + 1).join("/");
         }
     }
-    return segments[segments.length - 1] ?? "";
+    return undefined;
 }
 /**
  * Loader a runtime jar belongs to, read from the tool-written part of its path.
@@ -286,7 +408,9 @@ export function inferRuntimeJarLoader(path) {
  * `version` becomes the version the SERVED jar carries; the caller's original
  * request is preserved under `requestedVersion` and flagged. A served loader
  * that contradicts a KNOWN expected loader is flagged too — never silently
- * dropped.
+ * dropped. When the jar's path names no version at all, the request stands as
+ * the answer and nothing is flagged: there is no served version to contradict
+ * it with.
  */
 export function describeServedRuntimeJar(input) {
     const notes = [];
@@ -378,7 +502,8 @@ function buildProvenance(input) {
             version: input.resolved.version,
             repoUrl: input.resolved.repoUrl
         },
-        transformChain: [...input.transformChain]
+        transformChain: [...input.transformChain],
+        ...(input.unobfuscatedRuntime ? { unobfuscatedRuntime: true } : {})
     };
     if (!provenance.resolvedAt || !provenance.target.kind || !provenance.target.value) {
         throw createError({
@@ -492,8 +617,9 @@ export async function probeMinecraftArtifact(svc, input) {
     let value = input.target.value.trim();
     const warnings = [];
     const requestedMapping = normalizeMapping(input.mapping);
-    if (input.preferProjectVersion && input.projectPath) {
-        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+    const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+    if (input.preferProjectVersion && normalizedProjectPath) {
+        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
         if (detected && detected !== value) {
             warnings.push(`Overriding version "${value}" with project version "${detected}" from gradle.properties.`);
         }
@@ -545,7 +671,7 @@ export async function probeMinecraftArtifact(svc, input) {
         }
         const versionSourceDiscovery = await svc.discoverVersionSourceJar({
             version: resolvedVersion,
-            projectPath: input.projectPath,
+            projectPath: normalizedProjectPath,
             gradleUserHome: input.gradleUserHome
         });
         if (!versionSourceDiscovery.selectedSourceJarPath) {
@@ -1093,10 +1219,11 @@ export async function resolveVersionContext(svc, input) {
     if (inferredVersion) {
         return inferredVersion;
     }
-    if (!input.preferProjectVersion || !input.projectPath) {
+    const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
+    if (!input.preferProjectVersion || !normalizedProjectPath) {
         return undefined;
     }
-    const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+    const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(normalizedProjectPath);
     if (detected) {
         input.warnings.push(`Using project version "${detected}" from gradle.properties because the artifact metadata did not include a version.`);
     }
@@ -1233,12 +1360,19 @@ export async function buildMappingFallbackSuggestedCall(svc, args) {
     if (process.env.WORKSPACE_FALLBACK_LEGACY === "1") {
         return buildLegacyMappingFallback({ kind, value, scope, isVanillaMojang, projectPath: input.projectPath });
     }
-    const projectPath = input.projectPath?.trim();
+    const projectPath = normalizeOptionalProjectPath(input.projectPath);
     if (!projectPath) {
         return buildLegacyMappingFallback({ kind, value, scope, isVanillaMojang, projectPath: undefined });
     }
     if (kind !== "version") {
-        return buildLegacyMappingFallback({ kind, value, scope, isVanillaMojang, projectPath });
+        return buildLegacyMappingFallback({
+            kind,
+            value,
+            scope,
+            isVanillaMojang,
+            projectPath,
+            projectRuntimeUnobfuscated: isVanillaMojang && (await projectNamesUnobfuscatedMinecraft(svc, projectPath))
+        });
     }
     const cached = svc.workspaceContextCache.read(projectPath);
     if (cached &&
@@ -1299,9 +1433,28 @@ export async function buildMappingFallbackSuggestedCall(svc, args) {
     }
     return buildLegacyMappingFallback({ kind, value, scope, isVanillaMojang, projectPath });
 }
+/**
+ * Whether the project's gradle.properties names a Minecraft 26.1+ release. The
+ * property is a Minecraft version by name (`minecraft_version` and its aliases), so
+ * it may be put to `isUnobfuscatedVersion`. Unreadable or absent answers false.
+ */
+async function projectNamesUnobfuscatedMinecraft(svc, projectPath) {
+    try {
+        const version = await svc.workspaceMappingService.detectProjectMinecraftVersion(projectPath);
+        return version !== undefined && isUnobfuscatedVersion(version);
+    }
+    catch {
+        return false;
+    }
+}
 function buildLegacyMappingFallback(args) {
     const { kind, value, scope, isVanillaMojang, projectPath } = args;
-    if (isVanillaMojang && projectPath) {
+    // scope=merged reaches Loom source discovery only for a version target. For a
+    // jar or coordinate in a 26.1+ project, re-suggesting mojang+merged on the same
+    // target repeats the request that was just refused, so that case takes the
+    // generic retry below instead.
+    const mergedRetryWouldRepeat = kind !== "version" && args.projectRuntimeUnobfuscated === true;
+    if (isVanillaMojang && projectPath && !mergedRetryWouldRepeat) {
         return {
             ...buildSuggestedCall({
                 tool: "resolve-artifact",
@@ -1311,7 +1464,7 @@ function buildLegacyMappingFallback(args) {
                 "Retry with scope=merged to allow source-jar resolution from the project cache."
         };
     }
-    if (isVanillaMojang) {
+    if (isVanillaMojang && !projectPath) {
         return {
             ...buildSuggestedCall({
                 tool: "resolve-artifact",
@@ -1326,7 +1479,14 @@ function buildLegacyMappingFallback(args) {
             tool: "resolve-artifact",
             params: buildResolveArtifactParams({ kind, value }, { mapping: "obfuscated", ...(scope ? { scope } : {}) })
         }),
-        nextAction: "Retry with mapping=obfuscated to use the runtime obfuscated namespace."
+        // A jar reaches here only when it was NOT proven to be a Minecraft runtime jar,
+        // so its version is unknown and "obfuscated" must not be described as
+        // obfuscated names: on 26.1+ the as-shipped names are Mojang names. Version and
+        // coordinate refusals keep their established wording.
+        nextAction: kind === "jar"
+            ? "Retry with mapping=obfuscated to read this jar's names as shipped (already Mojang names on Minecraft 26.1+). " +
+                "For a vanilla Minecraft release, use target kind \"version\" instead."
+            : "Retry with mapping=obfuscated to use the runtime obfuscated namespace."
     };
 }
 export async function resolveArtifact(svc, input) {
@@ -1360,8 +1520,15 @@ export async function resolveArtifact(svc, input) {
     const mapping = normalizeMapping(input.mapping);
     const scope = input.scope;
     const warnings = [...synthesisWarnings];
-    if (input.preferProjectVersion && input.projectPath && kind === "version") {
-        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+    // Normalized only for the readers that need it: every other use of
+    // projectPath below reaches a helper that normalizes on its own, and doing it
+    // here unconditionally would newly refuse a malformed path on calls that
+    // never read one.
+    const preferProjectVersionPath = input.preferProjectVersion
+        ? normalizeOptionalProjectPath(input.projectPath)
+        : undefined;
+    if (preferProjectVersionPath && kind === "version") {
+        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(preferProjectVersionPath);
         if (detected && detected !== value) {
             warnings.push(`Overriding version "${value}" with project version "${detected}" from gradle.properties.`);
         }
@@ -1431,13 +1598,19 @@ export async function resolveArtifact(svc, input) {
         // below), so its mapping is never actually enforced either way.
         const versionNamesMinecraft = kind === "version" ||
             (kind === "coordinate" && !dependencyOrigin && coordinateIsMinecraftRuntime);
-        const minecraftVersion = versionNamesMinecraft ? resolvedVersion : undefined;
-        const runtimeNamesUnobfuscated = minecraftVersion !== undefined && isUnobfuscatedVersion(minecraftVersion);
+        // A kind="jar" target names no version at all. It joins this gate only AFTER its
+        // archive has been walked and proved to be a Minecraft 26.1+ runtime jar (see
+        // `provenUnobfuscatedRuntimeJarVersion` below); until then it stays out.
+        let minecraftVersion = versionNamesMinecraft ? resolvedVersion : undefined;
+        let runtimeNamesUnobfuscated = minecraftVersion !== undefined && isUnobfuscatedVersion(minecraftVersion);
         let effectiveMapping = mapping;
-        if ((mapping === "intermediary" || mapping === "yarn") && runtimeNamesUnobfuscated) {
-            warnings.push(`Version ${minecraftVersion} is unobfuscated; ${mapping} mappings are not applicable. Using the obfuscated namespace label for the deobfuscated runtime names.`);
-            effectiveMapping = "obfuscated";
-        }
+        const dropInapplicableUnobfuscatedMapping = () => {
+            if ((effectiveMapping === "intermediary" || effectiveMapping === "yarn") && runtimeNamesUnobfuscated) {
+                warnings.push(`Version ${minecraftVersion} is unobfuscated; ${effectiveMapping} mappings are not applicable. Using the obfuscated namespace label for the deobfuscated runtime names.`);
+                effectiveMapping = "obfuscated";
+            }
+        };
+        dropInapplicableUnobfuscatedMapping();
         if (kind === "version" &&
             resolvedVersion &&
             effectiveMapping === "mojang" &&
@@ -1471,9 +1644,21 @@ export async function resolveArtifact(svc, input) {
         if (binaryRemapGate.warnings.length > 0) {
             warnings.push(...binaryRemapGate.warnings);
         }
+        // Only a jar the caller named directly can be proved from its contents. A
+        // dependency-origin jar is excluded for the reason given above, and a version
+        // target is rewritten into a jar but already carries its version.
+        const proveRuntimeJar = kind === "jar" && !dependencyOrigin;
+        let subjectJarScan = undefined;
         const resolved = await resolveSourceTargetInternal(resolvedTarget, {
             allowDecompile: effectiveMapping === "mojang" ? true : input.allowDecompile ?? true,
             mappingVariant: binaryRemapGate.mappingVariant,
+            ...(proveRuntimeJar
+                ? {
+                    onSubjectJarScanned: (scan) => {
+                        subjectJarScan = scan;
+                    }
+                }
+                : {}),
             onRepoFailover: (event) => {
                 svc.metrics.recordRepoFailover();
                 log("warn", "repo.failover", {
@@ -1486,6 +1671,13 @@ export async function resolveArtifact(svc, input) {
                 });
             }
         }, svc.config);
+        const provenJarVersion = proveRuntimeJar ? provenUnobfuscatedRuntimeJarVersion(subjectJarScan) : undefined;
+        if (provenJarVersion) {
+            resolvedVersion = provenJarVersion;
+            minecraftVersion = provenJarVersion;
+            runtimeNamesUnobfuscated = true;
+            dropInapplicableUnobfuscatedMapping();
+        }
         resolved.version = resolvedVersion;
         let mappingDecision;
         try {
@@ -1547,9 +1739,21 @@ export async function resolveArtifact(svc, input) {
                         mapping: effectiveMapping,
                         target: { kind, value },
                         nextAction: "Use target: { kind: \"version\", value } or a versioned Maven coordinate so mapping artifacts can be resolved.",
+                        // This branch is reached precisely because no version is known, and
+                        // `value` is whatever the caller's own target carried - a jar path
+                        // for the kind that gets here. Replaying it as a version target
+                        // produced a `suggestedCall` that could never succeed, so the
+                        // version goes out as a placeholder the caller must fill in;
+                        // buildSuggestedCall routes such a template to exampleCalls.
                         ...buildSuggestedCall({
                             tool: "resolve-artifact",
-                            params: buildResolveArtifactParams({ kind: "version", value }, { ...(scope ? { scope } : {}) })
+                            params: undefined,
+                            examples: [
+                                {
+                                    params: buildResolveArtifactParams({ kind: "version", value: "<your-mc-version>" }, { ...(scope ? { scope } : {}) }),
+                                    reason: `Replace <your-mc-version> with the Minecraft version this artifact belongs to; ${effectiveMapping} mappings are resolved per version.`
+                                }
+                            ]
                         })
                     }
                 });
@@ -1569,7 +1773,8 @@ export async function resolveArtifact(svc, input) {
         const provenance = buildProvenance({
             requestedTarget: { kind, value },
             resolved,
-            transformChain: [...mappingDecision.transformChain, ...additionalTransformChain]
+            transformChain: [...mappingDecision.transformChain, ...additionalTransformChain],
+            unobfuscatedRuntime: runtimeNamesUnobfuscated
         });
         if (workspaceProvenance) {
             provenance.workspaceResolution = workspaceProvenance;

package/dist/source/class-source/members-builder.d.ts

@@ -17,6 +17,13 @@ export type RemapMembersInput = {
     signatureFields: SignatureMember[];
     signatureMethods: SignatureMember[];
     version: string | undefined;
+    /**
+     * `version` when it is a Minecraft version, else undefined: a dependency
+     * artifact's `version` is its own release number, which must not reach the
+     * 26.1+ obfuscated<->mojang identity shortcut, which may only be asked about a
+     * string proven to be a Minecraft version.
+     */
+    minecraftVersion: string | undefined;
     mappingApplied: SourceMapping;
     requestedMapping: SourceMapping;
     sourcePriority: MappingSourcePriority | undefined;

package/dist/source/class-source/members-builder.js

@@ -1,10 +1,13 @@
+import { remapSignatureMembers } from "../lifecycle/mapping-helpers.js";
 import { matchesMemberPattern } from "../member-pattern.js";
 export async function remapAndCountMembers(svc, input) {
     const remap = async (members, kind) => {
         if (input.version == null) {
             return members;
         }
-        const result = await svc.remapSignatureMembers(members, kind, input.version, input.mappingApplied, input.requestedMapping, input.sourcePriority, input.warnings, undefined, input.gradleUserHome);
+        // Called directly rather than through svc.remapSignatureMembers, whose fixed
+        // parameter list cannot carry minecraftVersion.
+        const result = await remapSignatureMembers(svc, members, kind, input.version, input.mappingApplied, input.requestedMapping, input.sourcePriority, input.warnings, undefined, input.gradleUserHome, { minecraftVersion: input.minecraftVersion });
         return result.members;
     };
     let constructors = await remap(input.signatureConstructors, "method");

package/dist/source/class-source.d.ts

@@ -21,7 +21,7 @@ import type { ArtifactProvenance, ArtifactScope, MappingSourcePriority, Resolved
  */
 export declare function reconcileUnobfuscatedNamespace(version: string | undefined, requestedMapping: SourceMapping, mappingApplied: SourceMapping): SourceMapping;
 export declare function resolveClassFilePath(svc: SourceService, artifactId: string, className: string): string | undefined;
-export declare function resolveClassNameForLookup(svc: SourceService, input: {
+type ClassNameLookupInput = {
     className: string;
     version?: string;
     sourceMapping: SourceMapping;
@@ -30,7 +30,13 @@ export declare function resolveClassNameForLookup(svc: SourceService, input: {
     gradleUserHome?: string;
     warnings: string[];
     context: string;
-}): Promise<string>;
+};
+/**
+ * The class-name translation behind `svc.resolveClassNameForLookup`, whose callers
+ * (the lifecycle tools) pass a Minecraft version, so `version` also keys the 26.1+
+ * identity shortcut.
+ */
+export declare function resolveClassNameForLookup(svc: SourceService, input: ClassNameLookupInput): Promise<string>;
 export declare function buildFallbackProvenance(svc: SourceService, input: {
     artifactId: string;
     origin: ResolvedSourceArtifact["origin"];
@@ -98,3 +104,4 @@ export declare function findClass(svc: SourceService, input: FindClassInput): Fi
 export declare function findClassIncludingNested(svc: SourceService, input: FindClassInput): Promise<FindClassOutput>;
 export declare function getClassSource(svc: SourceService, input: GetClassSourceInput): Promise<GetClassSourceOutput>;
 export declare function getClassMembers(svc: SourceService, input: GetClassMembersInput): Promise<GetClassMembersOutput>;
+export {};