@adhisang/minecraft-modding-mcp 4.1.1 → 4.2.1

package/dist/source/indexer.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, open, rename, stat, unlink } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir, open, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { buildSuggestedCall } from "../build-suggested-call.js";
 import { decompileBinaryJar } from "../decompiler/vineflower.js";
 import { ERROR_CODES, createError, isAppError } from "../errors.js";
@@ -15,6 +15,13 @@ import { resolveVineflowerJar } from "../vineflower-resolver.js";
 import { enforceCacheLimits, recordRemappedJarBytes, releaseRemappedJarBytes, touchCacheMetrics, upsertCacheMetrics } from "./cache-metrics.js";
 import { normalizePathStyle } from "./shared-utils.js";
 export const INDEX_SCHEMA_VERSION = 1;
+const defaultBinaryRemapDeps = {
+    resolveTinyRemapperJar,
+    resolveMojangTinyFile,
+    remapJar,
+    now: () => Date.now(),
+    randomSuffix: () => Math.random().toString(36).slice(2, 8) || "0"
+};
 function chunkArray(items, chunkSize) {
     const size = Math.max(1, Math.trunc(chunkSize));
     if (items.length === 0) {
@@ -354,13 +361,12 @@ async function rebuildMissingArtifactIndex(svc, resolved, reason) {
  * binary remap, run tiny-remapper now and return the remapped jar path.
  * Otherwise return the original binaryJarPath unchanged.
  *
- * Cache safety: writes to a per-attempt temp file then atomic-renames into
- * <cacheDir>/remapped/<artifactId>.jar. A per-target inflight Promise map
- * collapses concurrent calls so two simultaneous resolveArtifact calls for
- * the same artifactId share one tiny-remapper run instead of racing on the
- * same output path.
+ * Cache safety: writes to a per-attempt `.jar` temp path, validates ZIP magic,
+ * then atomic-renames into <cacheDir>/remapped/<artifactId>.jar. A per-target
+ * inflight Promise map collapses concurrent calls so simultaneous
+ * resolveArtifact calls for the same artifactId share one tiny-remapper run.
  */
-export async function maybeRemapBinaryForMojang(svc, resolved) {
+export async function maybeRemapBinaryForMojang(svc, resolved, deps = defaultBinaryRemapDeps) {
     const binaryJarPath = resolved.binaryJarPath;
     if (!binaryJarPath) {
         throw createError({
@@ -400,10 +406,19 @@ export async function maybeRemapBinaryForMojang(svc, resolved) {
             remappedJarPath
         });
         try {
-            await unlink(remappedJarPath);
+            await rm(remappedJarPath, { recursive: true, force: true });
         }
-        catch {
-            // ignore: race with another process or already-deleted file.
+        catch (caughtError) {
+            releaseRemappedJarBytes(svc, resolved.artifactId);
+            throw createError({
+                code: ERROR_CODES.REMAP_FAILED,
+                message: "Failed to remove corrupt binary remap cache entry.",
+                details: {
+                    artifactId: resolved.artifactId,
+                    remappedJarPath,
+                    cause: caughtError instanceof Error ? caughtError.message : String(caughtError)
+                }
+            });
         }
         releaseRemappedJarBytes(svc, resolved.artifactId);
     }
@@ -411,12 +426,12 @@ export async function maybeRemapBinaryForMojang(svc, resolved) {
     if (inflight) {
         return inflight;
     }
-    const remapPromise = runBinaryRemap(svc, {
+    const remapPromise = runBinaryRemapWithDeps(svc, {
         version: resolved.version,
         inputJar: binaryJarPath,
         remappedDir,
         remappedJarPath
-    });
+    }, deps);
     svc.state.inflightRemaps.set(remappedJarPath, remapPromise);
     try {
         const path = await remapPromise;
@@ -430,6 +445,9 @@ export async function maybeRemapBinaryForMojang(svc, resolved) {
 export async function recordRemappedJarBytesFromDisk(svc, artifactId, path) {
     try {
         const fileStat = await stat(path);
+        if (!fileStat.isFile()) {
+            return;
+        }
         recordRemappedJarBytes(svc, artifactId, fileStat.size);
     }
     catch {
@@ -467,14 +485,45 @@ export async function isUsableJarFile(path) {
         await handle?.close().catch(() => undefined);
     }
 }
+export function buildBinaryRemapTempPath(remappedJarPath, input) {
+    // Keep the final extension as `.jar`; the remap output is rejected unless it
+    // is a regular ZIP/JAR file, and manage-cache recognizes this temp shape.
+    const fileName = basename(remappedJarPath);
+    const artifactId = fileName.endsWith(".jar")
+        ? fileName.slice(0, -".jar".length)
+        : fileName;
+    return join(dirname(remappedJarPath), `${artifactId}.tmp.${input.pid}.${input.now}.${input.randomSuffix}.jar`);
+}
+async function describePathKind(path) {
+    try {
+        const stats = await stat(path);
+        if (stats.isFile()) {
+            return "file";
+        }
+        if (stats.isDirectory()) {
+            return "directory";
+        }
+        return "other";
+    }
+    catch {
+        return "missing";
+    }
+}
 export async function runBinaryRemap(svc, input) {
-    const tinyRemapperJarPath = await resolveTinyRemapperJar(svc.config.cacheDir, svc.config.tinyRemapperJarPath);
-    const mojangTiny = await resolveMojangTinyFile(input.version, svc.config);
+    return runBinaryRemapWithDeps(svc, input, defaultBinaryRemapDeps);
+}
+export async function runBinaryRemapWithDeps(svc, input, deps) {
+    const tinyRemapperJarPath = await deps.resolveTinyRemapperJar(svc.config.cacheDir, svc.config.tinyRemapperJarPath);
+    const mojangTiny = await deps.resolveMojangTinyFile(input.version, svc.config);
     await mkdir(input.remappedDir, { recursive: true });
-    const tempPath = `${input.remappedJarPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+    const tempPath = buildBinaryRemapTempPath(input.remappedJarPath, {
+        pid: process.pid,
+        now: deps.now(),
+        randomSuffix: deps.randomSuffix()
+    });
     const remapStartedAt = Date.now();
     try {
-        await remapJar(tinyRemapperJarPath, {
+        await deps.remapJar(tinyRemapperJarPath, {
             inputJar: input.inputJar,
             outputJar: tempPath,
             mappingsFile: mojangTiny.path,
@@ -483,20 +532,38 @@ export async function runBinaryRemap(svc, input) {
             timeoutMs: svc.config.remapTimeoutMs,
             maxMemoryMb: svc.config.remapMaxMemoryMb
         });
-        const tempStats = await stat(tempPath);
-        if (tempStats.size === 0) {
+        if (!(await isUsableJarFile(tempPath))) {
+            throw createError({
+                code: ERROR_CODES.REMAP_FAILED,
+                message: "tiny-remapper produced an invalid output jar.",
+                details: {
+                    inputJar: input.inputJar,
+                    tempPath,
+                    outputKind: await describePathKind(tempPath)
+                }
+            });
+        }
+        try {
+            await rename(tempPath, input.remappedJarPath);
+        }
+        catch (caughtError) {
             throw createError({
                 code: ERROR_CODES.REMAP_FAILED,
-                message: "tiny-remapper produced an empty output jar.",
-                details: { inputJar: input.inputJar, tempPath }
+                message: "Failed to finalize binary remap cache entry.",
+                details: {
+                    inputJar: input.inputJar,
+                    tempPath,
+                    remappedJarPath: input.remappedJarPath,
+                    outputKind: await describePathKind(input.remappedJarPath),
+                    cause: caughtError instanceof Error ? caughtError.message : String(caughtError)
+                }
             });
         }
-        await rename(tempPath, input.remappedJarPath);
         return input.remappedJarPath;
     }
     catch (caughtError) {
         try {
-            await unlink(tempPath);
+            await rm(tempPath, { recursive: true, force: true });
         }
         catch {
             // tempPath may not exist if remapJar failed before writing anything; ignore.

package/dist/source/lifecycle/diff.js

@@ -63,10 +63,10 @@ export async function diffClassSignatures(svc, input) {
         });
     }
     const mappingWarnings = [];
-    const obfuscatedFromClassName = await resolveToObfuscatedClassName(svc, className, fromVersion, mapping, input.sourcePriority, mappingWarnings);
+    const obfuscatedFromClassName = await resolveToObfuscatedClassName(svc, className, fromVersion, mapping, input.sourcePriority, mappingWarnings, input.gradleUserHome);
     const obfuscatedToClassName = fromVersion === toVersion
         ? obfuscatedFromClassName
-        : await resolveToObfuscatedClassName(svc, className, toVersion, mapping, input.sourcePriority, mappingWarnings);
+        : await resolveToObfuscatedClassName(svc, className, toVersion, mapping, input.sourcePriority, mappingWarnings, input.gradleUserHome);
     const [fromResolved, toResolved] = await Promise.all([
         svc.versionService.resolveVersionJar(fromVersion),
         svc.versionService.resolveVersionJar(toVersion)
@@ -176,8 +176,8 @@ export async function diffClassSignatures(svc, input) {
     // Remap diff delta members for non-obfuscated mappings
     const remapDelta = async (delta, kind) => {
         const [addedResult, removedResult] = await Promise.all([
-            svc.remapSignatureMembers(delta.added, kind, toVersion, "obfuscated", mapping, input.sourcePriority, warnings),
-            svc.remapSignatureMembers(delta.removed, kind, fromVersion, "obfuscated", mapping, input.sourcePriority, warnings)
+            svc.remapSignatureMembers(delta.added, kind, toVersion, "obfuscated", mapping, input.sourcePriority, warnings, undefined, input.gradleUserHome),
+            svc.remapSignatureMembers(delta.removed, kind, fromVersion, "obfuscated", mapping, input.sourcePriority, warnings, undefined, input.gradleUserHome)
         ]);
         const remappedModified = await Promise.all(delta.modified.map(async (change) => {
             if (!change.from || !change.to) {
@@ -194,8 +194,8 @@ export async function diffClassSignatures(svc, input) {
                 });
             }
             const [fromResult, toResult] = await Promise.all([
-                svc.remapSignatureMembers([change.from], kind, fromVersion, "obfuscated", mapping, input.sourcePriority, warnings),
-                svc.remapSignatureMembers([change.to], kind, toVersion, "obfuscated", mapping, input.sourcePriority, warnings)
+                svc.remapSignatureMembers([change.from], kind, fromVersion, "obfuscated", mapping, input.sourcePriority, warnings, undefined, input.gradleUserHome),
+                svc.remapSignatureMembers([change.to], kind, toVersion, "obfuscated", mapping, input.sourcePriority, warnings, undefined, input.gradleUserHome)
             ]);
             const fromMember = fromResult.members[0];
             const toMember = toResult.members[0];

package/dist/source/lifecycle/mapping-helpers.d.ts

@@ -11,12 +11,12 @@ export declare function rejectLifecycleClassLikeInput(svc: SourceService, input:
     sourcePriority?: MappingSourcePriority;
 }): void;
 export declare function releaseLifecycleMappingGraph(svc: SourceService, version: string, sourcePriority: MappingSourcePriority | undefined): void;
-export declare function resolveToObfuscatedClassName(svc: SourceService, className: string, version: string, mapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[]): Promise<string>;
-export declare function resolveToObfuscatedMemberName(svc: SourceService, name: string, ownerInSourceMapping: string, descriptor: string | undefined, kind: "field" | "method", version: string, mapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[]): Promise<{
+export declare function resolveToObfuscatedClassName(svc: SourceService, className: string, version: string, mapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], gradleUserHome?: string): Promise<string>;
+export declare function resolveToObfuscatedMemberName(svc: SourceService, name: string, ownerInSourceMapping: string, descriptor: string | undefined, kind: "field" | "method", version: string, mapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], gradleUserHome?: string): Promise<{
     name: string;
     descriptor?: string;
 }>;
-export declare function remapSignatureMembers(svc: SourceService, members: SignatureMember[], kind: "field" | "method", version: string, sourceMapping: SourceMapping, targetMapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], projectPath?: string): Promise<{
+export declare function remapSignatureMembers(svc: SourceService, members: SignatureMember[], kind: "field" | "method", version: string, sourceMapping: SourceMapping, targetMapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], projectPath?: string, gradleUserHome?: string): Promise<{
     members: SignatureMember[];
     failedNames: Set<string>;
 }>;

package/dist/source/lifecycle/mapping-helpers.js

@@ -58,18 +58,19 @@ export function releaseLifecycleMappingGraph(svc, version, sourcePriority) {
         svc.mappingService.releaseGraphCacheEntry(version, sourcePriority);
     }
 }
-export async function resolveToObfuscatedClassName(svc, className, version, mapping, sourcePriority, warnings) {
+export async function resolveToObfuscatedClassName(svc, className, version, mapping, sourcePriority, warnings, gradleUserHome) {
     return svc.resolveClassNameForLookup({
         className,
         version,
         sourceMapping: mapping,
         targetMapping: "obfuscated",
         sourcePriority,
+        gradleUserHome,
         warnings,
         context: "bytecode lookup"
     });
 }
-export async function resolveToObfuscatedMemberName(svc, name, ownerInSourceMapping, descriptor, kind, version, mapping, sourcePriority, warnings) {
+export async function resolveToObfuscatedMemberName(svc, name, ownerInSourceMapping, descriptor, kind, version, mapping, sourcePriority, warnings, gradleUserHome) {
     if (mapping === "obfuscated") {
         return {
             name,
@@ -89,7 +90,8 @@ export async function resolveToObfuscatedMemberName(svc, name, ownerInSourceMapp
                 descriptor,
                 sourceMapping: mapping,
                 targetMapping: "obfuscated",
-                sourcePriority
+                sourcePriority,
+                gradleUserHome
             })
             : await svc.mappingService.findMapping({
                 version,
@@ -108,7 +110,8 @@ export async function resolveToObfuscatedMemberName(svc, name, ownerInSourceMapp
                     : undefined,
                 sourceMapping: mapping,
                 targetMapping: "obfuscated",
-                sourcePriority
+                sourcePriority,
+                gradleUserHome
             });
         warnings.push(...mapped.warnings);
         if (mapped.resolved && mapped.resolvedSymbol) {
@@ -127,7 +130,8 @@ export async function resolveToObfuscatedMemberName(svc, name, ownerInSourceMapp
                 signatureMode: "exact",
                 sourceMapping: mapping,
                 targetMapping: "obfuscated",
-                sourcePriority
+                sourcePriority,
+                gradleUserHome
             });
             warnings.push(...fallbackMapped.warnings);
             if (fallbackMapped.resolved && fallbackMapped.resolvedSymbol) {
@@ -147,7 +151,7 @@ export async function resolveToObfuscatedMemberName(svc, name, ownerInSourceMapp
         descriptor: kind === "method" ? descriptor : undefined
     };
 }
-export async function remapSignatureMembers(svc, members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath) {
+export async function remapSignatureMembers(svc, members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath, gradleUserHome) {
     const failedNames = new Set();
     if (sourceMapping === targetMapping) {
         return { members, failedNames };
@@ -174,7 +178,8 @@ export async function remapSignatureMembers(svc, members, kind, version, sourceM
                 sourceMapping,
                 targetMapping,
                 sourcePriority,
-                projectPath
+                projectPath,
+                gradleUserHome
             });
             if (mapped.resolved && mapped.resolvedSymbol) {
                 ownerToRemapped.set(obfuscatedFqn, mapped.resolvedSymbol.name);
@@ -207,7 +212,8 @@ export async function remapSignatureMembers(svc, members, kind, version, sourceM
                     sourceMapping,
                     targetMapping,
                     sourcePriority,
-                    projectPath
+                    projectPath,
+                    gradleUserHome
                 });
                 if (mapped.resolved && mapped.resolvedSymbol) {
                     ownerToRemapped.set(dotFqn, mapped.resolvedSymbol.name);
@@ -242,7 +248,8 @@ export async function remapSignatureMembers(svc, members, kind, version, sourceM
                         sourceMapping,
                         targetMapping,
                         sourcePriority,
-                        projectPath
+                        projectPath,
+                        gradleUserHome
                     });
                     if (exactResult.resolved && exactResult.resolvedSymbol) {
                         memberKeyToRemapped.set(key, exactResult.resolvedSymbol.name);
@@ -270,6 +277,7 @@ export async function remapSignatureMembers(svc, members, kind, version, sourceM
                 targetMapping,
                 sourcePriority,
                 projectPath,
+                gradleUserHome,
                 disambiguation: {
                     ownerHint: targetOwner,
                     descriptorHint: remappedDescriptorHint

package/dist/source/lifecycle/trace.js

@@ -123,8 +123,8 @@ export async function traceSymbolLifecycle(svc, input) {
         const versionWarnings = [];
         try {
             const [obfuscatedClassName, obfuscatedMethod, resolvedJar] = await Promise.all([
-                resolveToObfuscatedClassName(svc, userClassName, version, mapping, input.sourcePriority, versionWarnings),
-                resolveToObfuscatedMemberName(svc, userMethodName, userClassName, descriptor, "method", version, mapping, input.sourcePriority, versionWarnings),
+                resolveToObfuscatedClassName(svc, userClassName, version, mapping, input.sourcePriority, versionWarnings, input.gradleUserHome),
+                resolveToObfuscatedMemberName(svc, userMethodName, userClassName, descriptor, "method", version, mapping, input.sourcePriority, versionWarnings, input.gradleUserHome),
                 svc.versionService.resolveVersionJar(version)
             ]);
             const signature = await svc.explorerService.getSignature({

package/dist/source/search.js

@@ -250,6 +250,7 @@ export async function searchClassSource(svc, input) {
                         sourceMapping: input.queryNamespace,
                         targetMapping: artifactMapping,
                         sourcePriority: input.sourcePriority,
+                        gradleUserHome: input.gradleUserHome,
                         signatureMode: "name-only",
                         maxCandidates: 5
                     });

package/dist/source/symbol-resolver.js

@@ -106,6 +106,7 @@ export async function resolveWorkspaceSymbol(svc, input) {
             sourceMapping: input.sourceMapping,
             targetMapping: mappingApplied,
             sourcePriority: input.sourcePriority,
+            gradleUserHome: input.gradleUserHome,
             maxCandidates: input.maxCandidates
         });
         return {
@@ -121,7 +122,8 @@ export async function resolveWorkspaceSymbol(svc, input) {
             className,
             classNameMapping: input.sourceMapping,
             includeKinds: ["class"],
-            sourcePriority: input.sourcePriority
+            sourcePriority: input.sourcePriority,
+            gradleUserHome: input.gradleUserHome
         });
         const resolvedClass = matrix.classIdentity[mappingApplied];
         if (!resolvedClass) {
@@ -180,6 +182,7 @@ export async function resolveWorkspaceSymbol(svc, input) {
         sourceMapping: input.sourceMapping,
         targetMapping: mappingApplied,
         sourcePriority: input.sourcePriority,
+        gradleUserHome: input.gradleUserHome,
         maxCandidates: input.maxCandidates
     });
     const filtered = mapped.candidates.filter((candidate) => candidate.kind === kind);

package/dist/source/validate-mixin/pipeline/mapping-health.js

@@ -5,7 +5,8 @@ export async function runMappingHealthStage(svc, ctx) {
         const health = await svc.mappingService.checkMappingHealth({
             version: ctx.version,
             requestedMapping: ctx.requestedMapping,
-            sourcePriority: ctx.currentSourcePriority
+            sourcePriority: ctx.currentSourcePriority,
+            gradleUserHome: ctx.input.gradleUserHome
         });
         const jarAvailable = existsSync(ctx.jarPath);
         ctx.healthReport = {

package/dist/source/validate-mixin/pipeline/resolve.js

@@ -36,6 +36,7 @@ export async function runResolveStage(svc, ctx) {
                 mapping: ctx.requestedMapping,
                 sourcePriority: ctx.currentSourcePriority,
                 projectPath: ctx.input.projectPath,
+                gradleUserHome: ctx.input.gradleUserHome,
                 scope: ctx.input.scope,
                 preferProjectVersion: false
             });

package/dist/source/validate-mixin/pipeline/target-lookup.js

@@ -9,7 +9,8 @@ function findValidateMixinClassMapping(svc, input) {
             sourceMapping: input.sourceMapping,
             targetMapping: input.targetMapping,
             sourcePriority: input.sourcePriority,
-            projectPath: input.projectPath
+            projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome
         });
     }
     const cacheKey = [
@@ -18,7 +19,8 @@ function findValidateMixinClassMapping(svc, input) {
         input.sourceMapping,
         input.targetMapping,
         input.sourcePriority,
-        input.projectPath ?? ""
+        input.projectPath ?? "",
+        input.gradleUserHome ?? ""
     ].join("\0");
     const cached = cache.get(cacheKey);
     if (cached) {
@@ -31,7 +33,8 @@ function findValidateMixinClassMapping(svc, input) {
         sourceMapping: input.sourceMapping,
         targetMapping: input.targetMapping,
         sourcePriority: input.sourcePriority,
-        projectPath: input.projectPath
+        projectPath: input.projectPath,
+        gradleUserHome: input.gradleUserHome
     }).catch((error) => {
         cache.delete(cacheKey);
         throw error;
@@ -78,6 +81,7 @@ export async function processSingleMixinTarget(svc, ctx, target, targetIndex) {
                 targetMapping: ctx.signatureLookupMapping,
                 sourcePriority: ctx.currentSourcePriority,
                 projectPath: ctx.input.projectPath,
+                gradleUserHome: ctx.input.gradleUserHome,
                 batchCaches: ctx.input.batchCaches
             });
             if (mapped.resolved && mapped.resolvedSymbol) {
@@ -110,9 +114,9 @@ export async function processSingleMixinTarget(svc, ctx, target, targetIndex) {
         if (ctx.requestedMapping !== ctx.signatureLookupMapping) {
             try {
                 const [ctorResult, methodResult, fieldResult] = await Promise.all([
-                    svc.remapSignatureMembers(sig.constructors, "method", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath),
-                    svc.remapSignatureMembers(sig.methods, "method", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath),
-                    svc.remapSignatureMembers(sig.fields, "field", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath)
+                    svc.remapSignatureMembers(sig.constructors, "method", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath, ctx.input.gradleUserHome),
+                    svc.remapSignatureMembers(sig.methods, "method", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath, ctx.input.gradleUserHome),
+                    svc.remapSignatureMembers(sig.fields, "field", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath, ctx.input.gradleUserHome)
                 ]);
                 constructors = ctorResult.members;
                 methods = methodResult.members;
@@ -160,7 +164,8 @@ export async function processSingleMixinTarget(svc, ctx, target, targetIndex) {
         try {
             const existenceCheck = await svc.mappingService.checkSymbolExists({
                 version: ctx.version, kind: "class", name: resolvedClassName,
-                sourceMapping: ctx.requestedMapping, nameMode: "auto", sourcePriority: ctx.currentSourcePriority
+                sourceMapping: ctx.requestedMapping, nameMode: "auto", sourcePriority: ctx.currentSourcePriority,
+                gradleUserHome: ctx.input.gradleUserHome
             });
             if (existenceCheck.resolved) {
                 ctx.symbolExistsButSignatureFailed.add(target.className);

package/dist/source-service.d.ts

@@ -26,6 +26,7 @@ export type ResolveArtifactInput = {
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
@@ -58,6 +59,7 @@ export type ProbeMinecraftArtifactInput = {
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
 };
@@ -105,6 +107,7 @@ export type SearchClassSourceInput = {
     cursor?: string;
     queryNamespace?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    gradleUserHome?: string;
 };
 export type SearchClassSourceOutput = {
     hits: SearchSourceHit[];
@@ -165,6 +168,7 @@ export type ResolveWorkspaceSymbolInput = {
     descriptor?: string;
     sourceMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    gradleUserHome?: string;
     maxCandidates?: number;
 };
 export type ResolveWorkspaceSymbolOutput = MappingSymbolResolutionOutput & {
@@ -180,6 +184,7 @@ export type GetClassSourceInput = {
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
@@ -241,6 +246,7 @@ export type GetClassMembersInput = {
     memberPattern?: string;
     maxMembers?: number;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
@@ -302,6 +308,7 @@ export type TraceSymbolLifecycleInput = {
     toVersion?: string;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    gradleUserHome?: string;
     includeSnapshots?: boolean;
     maxVersions?: number;
     includeTimeline?: boolean;
@@ -352,6 +359,7 @@ export type DiffClassSignaturesInput = {
     toVersion: string;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    gradleUserHome?: string;
     includeFullDiff?: boolean;
 };
 export type DiffClassSignaturesOutput = {
@@ -417,6 +425,7 @@ export type ValidateMixinInput = {
     sourcePriority?: MappingSourcePriority;
     scope?: ArtifactScope;
     projectPath?: string;
+    gradleUserHome?: string;
     preferProjectVersion?: boolean;
     minSeverity?: "error" | "warning" | "all";
     hideUncertain?: boolean;
@@ -488,6 +497,7 @@ export type ValidateAccessWidenerInput = {
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
 };
@@ -498,6 +508,7 @@ export type ValidateAccessTransformerInput = {
     atNamespace?: AccessTransformerNamespace;
     sourcePriority?: MappingSourcePriority;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
 };
@@ -532,6 +543,7 @@ export declare class SourceService {
         version: string;
         awNamespace: SourceMapping;
         projectPath?: string;
+        gradleUserHome?: string;
         scope?: ArtifactScope;
         preferProjectVersion?: boolean;
     }): Promise<RuntimeValidationProvenance<SourceMapping>>;
@@ -543,6 +555,7 @@ export declare class SourceService {
         version: string;
         atNamespace: AccessTransformerNamespace;
         projectPath?: string;
+        gradleUserHome?: string;
         scope?: ArtifactScope;
         preferProjectVersion?: boolean;
     }): Promise<RuntimeValidationProvenance<AccessTransformerNamespace>>;
@@ -555,15 +568,18 @@ export declare class SourceService {
     discoverVersionSourceJar(input: {
         version: string;
         projectPath?: string;
+        gradleUserHome?: string;
     }): ReturnType<typeof artifactResolver.discoverVersionSourceJar>;
     discoverAccessWidenerRuntimeCandidates(input: {
         version: string;
         projectPath?: string;
+        gradleUserHome?: string;
         requestedScope: ArtifactScope;
     }): ReturnType<typeof artifactResolver.discoverAccessWidenerRuntimeCandidates>;
     discoverAccessTransformerRuntimeCandidates(input: {
         version: string;
         projectPath?: string;
+        gradleUserHome?: string;
         requestedScope: ArtifactScope;
         atNamespace: AccessTransformerNamespace;
         loader: import("./workspace-mapping-service.js").WorkspaceProjectLoader | "unknown";
@@ -597,7 +613,7 @@ export declare class SourceService {
     getClassMembers(input: GetClassMembersInput): Promise<GetClassMembersOutput>;
     validateMixin(input: ValidateMixinInput, options?: ValidateMixinOptions): Promise<ValidateMixinOutput>;
     validateMixinSingle(input: validateMixinModule.ValidateMixinSingleInput): Promise<MixinValidationResult>;
-    remapSignatureMembers(members: SignatureMember[], kind: "field" | "method", version: string, sourceMapping: SourceMapping, targetMapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], projectPath?: string): Promise<{
+    remapSignatureMembers(members: SignatureMember[], kind: "field" | "method", version: string, sourceMapping: SourceMapping, targetMapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], projectPath?: string, gradleUserHome?: string): Promise<{
         members: SignatureMember[];
         failedNames: Set<string>;
     }>;
@@ -612,6 +628,7 @@ export declare class SourceService {
         sourceMapping: SourceMapping;
         targetMapping: SourceMapping;
         sourcePriority: MappingSourcePriority | undefined;
+        gradleUserHome?: string;
         warnings: string[];
         context: string;
     }): Promise<string>;

package/dist/source-service.js

@@ -176,8 +176,8 @@ export class SourceService {
     async validateMixinSingle(input) {
         return validateMixinModule.validateMixinSingle(this, input);
     }
-    async remapSignatureMembers(members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath) {
-        return lifecycle.remapSignatureMembers(this, members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath);
+    async remapSignatureMembers(members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath, gradleUserHome) {
+        return lifecycle.remapSignatureMembers(this, members, kind, version, sourceMapping, targetMapping, sourcePriority, warnings, projectPath, gradleUserHome);
     }
     async validateAccessWidener(input) {
         return accessValidate.validateAccessWidener(this, input);

package/dist/tiny-remapper-service.js

@@ -1,10 +1,10 @@
 import { existsSync } from "node:fs";
 import { createError, ERROR_CODES } from "./errors.js";
-import { assertJavaAvailable, runJavaProcess } from "./java-process.js";
+import { javaRunner } from "./java-process.js";
 import { log } from "./logger.js";
 export async function remapJar(tinyRemapperJarPath, options) {
     const { inputJar, outputJar, mappingsFile, fromNamespace, toNamespace, threads = 4, rebuildSourceFilenames = false, timeoutMs = 600_000, maxMemoryMb = 4096 } = options;
-    await assertJavaAvailable();
+    await javaRunner.assertAvailable();
     log("info", "remap.start", {
         inputJar,
         outputJar,
@@ -21,7 +21,7 @@ export async function remapJar(tinyRemapperJarPath, options) {
         args.push("--rebuildSourceFilenames");
     }
     try {
-        const result = await runJavaProcess({
+        const result = await javaRunner.run({
             jarPath: tinyRemapperJarPath,
             args,
             timeoutMs,

package/dist/tool-contract-manifest.d.ts

@@ -1,4 +1,4 @@
-export declare const TOOL_SURFACE_SECTION_IDS: readonly ["v3-entry-tools", "source-exploration", "version-comparison-symbol-tracking", "mapping-symbols", "nbt-utilities", "mod-analysis", "validation", "registry-diagnostics", "batch-lookup"];
+export declare const TOOL_SURFACE_SECTION_IDS: readonly ["top-level-workflow-tools", "source-exploration", "version-comparison-symbol-tracking", "mapping-symbols", "nbt-utilities", "mod-analysis", "validation", "registry-diagnostics", "batch-lookup"];
 export type ToolSurfaceSectionId = (typeof TOOL_SURFACE_SECTION_IDS)[number];
 export type ToolSurfaceLocale = "en" | "ja";
 export declare function renderToolSurfaceSection(locale: ToolSurfaceLocale, sectionId: ToolSurfaceSectionId): string;

package/dist/tool-contract-manifest.js

@@ -1,5 +1,5 @@
 export const TOOL_SURFACE_SECTION_IDS = [
-    "v3-entry-tools",
+    "top-level-workflow-tools",
     "source-exploration",
     "version-comparison-symbol-tracking",
     "mapping-symbols",
@@ -10,7 +10,7 @@ export const TOOL_SURFACE_SECTION_IDS = [
     "batch-lookup"
 ];
 const SECTION_ROWS = {
-    "v3-entry-tools": {
+    "top-level-workflow-tools": {
         en: [
             "| `inspect-minecraft` | Inspect versions, artifacts, classes, files, source text, and workspace-aware lookup flows |",
             "| `analyze-symbol` | Handle symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol resolution, and API overviews |",