@adhisang/minecraft-modding-mcp 4.2.0 → 4.2.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.2.1] - 2026-05-23
+
+### Fixed
+- Mojang binary-remap cache writes recover from corrupt `<cacheDir>/remapped/<artifactId>.jar` directories instead of surfacing raw `ENOTEMPTY`, and `manage-cache` can list and delete those corrupt `binary-remap` entries by `selector.artifactId`.
+- `isAppError(value)` now narrows to `AppError` via `instanceof AppError` instead of `Error & { code: string }`. Plain `Error` objects that happen to carry a `code` field no longer pass the guard, so unrelated errors can no longer leak through `AppError`-specific error handling.
+- Java NBT `TAG_String` now encodes/decodes via MUTF-8 to match Mojang's `DataInputStream.readUTF` / `DataOutputStream.writeUTF` contract. Supplementary characters (emoji, supplementary CJK) and the NUL character (`U+0000`) now round-trip correctly. ASCII and common BMP byte sequences are byte-identical to the previous UTF-8 output, so existing NBT payloads are unaffected.
+
 ## [4.2.0] - 2026-05-17
 
 ### Added

package/README.md

@@ -164,6 +164,7 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - `validate-mixin` and `validate-project` keep `mapping-health` lightweight for `obfuscated` and `mojang` validation, avoiding full Tiny mapping graph loads unless `intermediary` or `yarn` namespaces are requested.
 - `validate-project task="project-summary"` uses a lightweight artifact probe for `tasks["minecraft.artifact.resolved"]`; it does not decompile Minecraft or rebuild the source index just to report per-probe status. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the additive `tasks` field.
 - If a workspace was built with `GRADLE_USER_HOME=/tmp/...` or another isolated Gradle home, pass that path as `gradleUserHome` so source, mapping, runtime, and project validation lookups use the same Loom cache instead of stale caches under the MCP process home.
+- `manage-cache` reports corrupt Mojang binary-remap cache directories under `cacheKinds: ["binary-remap"]` with `status: "corrupt"`, and can delete them by `selector.artifactId` in preview/apply workflows.
 
 ### Inspect Minecraft source from a version
 

package/dist/cache-registry.js

@@ -442,6 +442,9 @@ function workspaceCacheEntries(workspaceCache) {
     }));
 }
 async function fileBackedEntries(config, cacheKind) {
+    if (cacheKind === "binary-remap") {
+        return binaryRemapEntries(config);
+    }
     const root = kindRoot(config, cacheKind);
     const files = await listFilesRecursive(root);
     const entries = [];
@@ -466,17 +469,91 @@ async function fileBackedEntries(config, cacheKind) {
                 inUse: filePath.endsWith(".lock") ||
                     filePath.endsWith(".wal") ||
                     filePath.endsWith(".journal"),
-                ...(cacheKind === "downloads" || cacheKind === "mod-remap" || cacheKind === "binary-remap"
+                ...(cacheKind === "downloads" || cacheKind === "mod-remap"
                     ? { jarPath: filePath }
-                    : {}),
-                ...(cacheKind === "binary-remap"
-                    ? { artifactId: normalizedEntryId.replace(/\.jar$/i, "") }
                     : {})
             }
         });
     }
     return entries;
 }
+/**
+ * Binary-remap cache entries are keyed by the final artifact id even when the
+ * on-disk entry is a corrupt final directory or a leftover temp path.
+ */
+function parseBinaryRemapEntryName(name) {
+    const legacyTempMatch = /^(.+)\.jar\.tmp\..+$/.exec(name);
+    if (legacyTempMatch?.[1]) {
+        return { artifactId: legacyTempMatch[1], corrupt: true };
+    }
+    const tempMatch = /^(.+)\.tmp\.\d+\.\d+\.[A-Za-z0-9_-]+\.jar$/.exec(name);
+    if (tempMatch?.[1]) {
+        return { artifactId: tempMatch[1], corrupt: true };
+    }
+    const finalJarMatch = /^(.+)\.jar$/.exec(name);
+    if (finalJarMatch?.[1]) {
+        return { artifactId: finalJarMatch[1], corrupt: false };
+    }
+    return undefined;
+}
+async function binaryRemapEntries(config) {
+    const root = kindRoot(config, "binary-remap");
+    if (!existsSync(root)) {
+        return [];
+    }
+    const entries = [];
+    // Do not recurse here: a corrupt `<artifactId>.jar` directory must remain one
+    // selectable cache entry so `selector.artifactId` can remove it recursively.
+    const dirents = await readdir(root, { withFileTypes: true });
+    for (const entry of dirents.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isFile() && !entry.isDirectory()) {
+            continue;
+        }
+        const parsed = parseBinaryRemapEntryName(entry.name);
+        if (!parsed) {
+            continue;
+        }
+        const filePath = join(root, entry.name);
+        const fileStat = await stat(filePath);
+        const corrupt = parsed.corrupt || entry.isDirectory();
+        const sizeBytes = entry.isDirectory()
+            ? await directoryFileSizeBytes(filePath)
+            : fileStat.size;
+        entries.push({
+            cacheKind: "binary-remap",
+            entryId: entry.name,
+            path: filePath,
+            sizeBytes,
+            status: corrupt ? "corrupt" : "healthy",
+            meta: {
+                updatedAt: fileStat.mtime.toISOString(),
+                version: inferVersion(filePath, entry.name),
+                mapping: inferMapping(filePath, entry.name),
+                scope: inferScope(filePath, entry.name),
+                projectPath: inferProjectPath(filePath, config.pathRuntimeInfo),
+                partial: entry.isFile() && fileStat.size === 0,
+                corrupt,
+                inUse: false,
+                jarPath: filePath,
+                artifactId: parsed.artifactId
+            }
+        });
+    }
+    return entries;
+}
+async function directoryFileSizeBytes(root) {
+    const files = await listFilesRecursive(root);
+    let totalBytes = 0;
+    for (const filePath of files) {
+        try {
+            totalBytes += (await stat(filePath)).size;
+        }
+        catch {
+            // The entry may disappear during cleanup or a concurrent cache write.
+        }
+    }
+    return totalBytes;
+}
 export function createCacheRegistry(config) {
     const workspaceCache = config.workspaceContextCache ?? getProcessWorkspaceContextCache();
     async function collectEntries(cacheKinds, selector) {
@@ -564,7 +641,9 @@ export function createCacheRegistry(config) {
                             continue;
                         }
                         if (existsSync(entry.path)) {
-                            await rm(entry.path, { force: true });
+                            // Only binary-remap inventory can return directories as entries;
+                            // other file-backed kinds keep their existing file-only contract.
+                            await rm(entry.path, { recursive: entry.cacheKind === "binary-remap", force: true });
                         }
                     }
                 }

package/dist/errors.js

@@ -49,7 +49,10 @@ export class AppError extends Error {
     }
 }
 export const createError = (payload) => new AppError(payload);
+// Narrow strictly by class identity. Duck-typing on `code` would also accept
+// arbitrary Errors whose `details` may leak unsanitised context (paths, tokens)
+// into AppError handling paths.
 export const isAppError = (value) => {
-    return value instanceof Error && value.code !== undefined;
+    return value instanceof AppError;
 };
 //# sourceMappingURL=errors.js.map

package/dist/java-process.d.ts

@@ -1,3 +1,4 @@
+export declare const MAX_STDIO_SNAPSHOT = 6240;
 export interface JavaProcessOptions {
     jarPath: string;
     args: string[];
@@ -12,5 +13,13 @@ export interface JavaProcessResult {
     stdoutTail: string;
     stderrTail: string;
 }
+export declare function limitStdio(text: string): string;
+export declare function isAbsolutePath(value: string): boolean;
+export declare function isOptionArg(value: string): boolean;
+export declare function normalizeArgs(args: string[]): string[];
 export declare function assertJavaAvailable(): Promise<void>;
 export declare function runJavaProcess(options: JavaProcessOptions): Promise<JavaProcessResult>;
+export declare const javaRunner: {
+    run: (options: JavaProcessOptions) => Promise<JavaProcessResult>;
+    assertAvailable: () => Promise<void>;
+};

package/dist/java-process.js

@@ -2,20 +2,20 @@ import { spawn } from "node:child_process";
 import { createError, ERROR_CODES } from "./errors.js";
 import { normalizePathForHost } from "./path-converter.js";
 const JAVA_CHECK_TIMEOUT_MS = 2_000;
-const MAX_STDIO_SNAPSHOT = 6_240;
-function limitStdio(text) {
+export const MAX_STDIO_SNAPSHOT = 6_240;
+export function limitStdio(text) {
     if (text.length <= MAX_STDIO_SNAPSHOT) {
         return text;
     }
     return text.slice(-MAX_STDIO_SNAPSHOT);
 }
-function isAbsolutePath(value) {
+export function isAbsolutePath(value) {
     return value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value);
 }
-function isOptionArg(value) {
+export function isOptionArg(value) {
     return value.startsWith("-");
 }
-function normalizeArgs(args) {
+export function normalizeArgs(args) {
     return args.map((arg) => {
         if (isOptionArg(arg)) {
             return arg;
@@ -117,4 +117,10 @@ export function runJavaProcess(options) {
         });
     });
 }
+// Mutable container that lets tests stub the Java subprocess boundary via
+// `mock.method(javaRunner, "run", ...)` without rewriting ESM named imports.
+export const javaRunner = {
+    run: runJavaProcess,
+    assertAvailable: assertJavaAvailable
+};
 //# sourceMappingURL=java-process.js.map

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

@@ -37,6 +37,85 @@ function resolveTagName(tagId, pointer) {
     }
     return tagName;
 }
+// Java NBT TAG_String uses MUTF-8 (Mojang's on-disk format matches the JVM
+// `DataInput/OutputStream.{read,write}UTF` contract), which differs from UTF-8
+// for two ranges: `U+0000` encodes as `C0 80`, and supplementary code points
+// (`U+10000`+) encode as two 3-byte sequences for the UTF-16 surrogate pair
+// (6 bytes total). All other characters share the UTF-8 byte sequence.
+function mutf8ByteLength(value) {
+    let length = 0;
+    for (let i = 0; i < value.length; i += 1) {
+        const c = value.charCodeAt(i);
+        if (c === 0x0000) {
+            length += 2;
+        }
+        else if (c <= 0x007f) {
+            length += 1;
+        }
+        else if (c <= 0x07ff) {
+            length += 2;
+        }
+        else {
+            length += 3;
+        }
+    }
+    return length;
+}
+function encodeMutf8(value) {
+    const buffer = Buffer.allocUnsafe(mutf8ByteLength(value));
+    let offset = 0;
+    for (let i = 0; i < value.length; i += 1) {
+        const c = value.charCodeAt(i);
+        if (c === 0x0000) {
+            buffer[offset++] = 0xc0;
+            buffer[offset++] = 0x80;
+        }
+        else if (c <= 0x007f) {
+            buffer[offset++] = c;
+        }
+        else if (c <= 0x07ff) {
+            buffer[offset++] = 0xc0 | (c >> 6);
+            buffer[offset++] = 0x80 | (c & 0x3f);
+        }
+        else {
+            buffer[offset++] = 0xe0 | (c >> 12);
+            buffer[offset++] = 0x80 | ((c >> 6) & 0x3f);
+            buffer[offset++] = 0x80 | (c & 0x3f);
+        }
+    }
+    return buffer;
+}
+function decodeMutf8(buffer, start, end) {
+    const codeUnits = [];
+    let i = start;
+    while (i < end) {
+        const b0 = buffer[i++];
+        if ((b0 & 0x80) === 0) {
+            codeUnits.push(b0);
+        }
+        else if ((b0 & 0xe0) === 0xc0) {
+            if (i >= end) {
+                throw parseError("Truncated MUTF-8 2-byte sequence.", { offset: i - 1 });
+            }
+            const b1 = buffer[i++];
+            codeUnits.push(((b0 & 0x1f) << 6) | (b1 & 0x3f));
+        }
+        else if ((b0 & 0xf0) === 0xe0) {
+            if (i + 1 >= end) {
+                throw parseError("Truncated MUTF-8 3-byte sequence.", { offset: i - 1 });
+            }
+            const b1 = buffer[i++];
+            const b2 = buffer[i++];
+            codeUnits.push(((b0 & 0x0f) << 12) | ((b1 & 0x3f) << 6) | (b2 & 0x3f));
+        }
+        else {
+            throw parseError("Invalid MUTF-8 lead byte.", { byte: b0, offset: i - 1 });
+        }
+    }
+    // NBT TAG_String is bounded by uint16 length so codeUnits.length <= 65535,
+    // safely within String.fromCharCode's argument cap.
+    return String.fromCharCode(...codeUnits);
+}
 class NbtReader {
     buffer;
     offset = 0;
@@ -103,7 +182,7 @@ class NbtReader {
     readString() {
         const byteLength = this.readUInt16();
         this.ensure(byteLength);
-        const value = this.buffer.toString("utf8", this.offset, this.offset + byteLength);
+        const value = decodeMutf8(this.buffer, this.offset, this.offset + byteLength);
         this.offset += byteLength;
         return value;
     }
@@ -154,7 +233,7 @@ class NbtWriter {
         this.chunks.push(chunk);
     }
     writeString(value) {
-        const encoded = Buffer.from(value, "utf8");
+        const encoded = encodeMutf8(value);
         if (encoded.length > 0xffff) {
             throw encodeError("NBT string length exceeds uint16.", { byteLength: encoded.length });
         }

package/dist/source/cache-metrics.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { log } from "../logger.js";
 export function hasAnyFiles(svc, artifactId) {
@@ -17,7 +17,7 @@ export function unlinkRemappedJarForArtifact(svc, artifactId) {
     const remappedJarPath = join(svc.config.cacheDir, "remapped", `${artifactId}.jar`);
     try {
         if (existsSync(remappedJarPath)) {
-            unlinkSync(remappedJarPath);
+            rmSync(remappedJarPath, { recursive: true, force: true });
         }
     }
     catch {

package/dist/source/indexer.d.ts

@@ -1,7 +1,22 @@
+import { resolveMojangTinyFile } from "../mojang-tiny-mapping-service.js";
 import type { SourceService } from "../source-service.js";
 import type { ArtifactIndexMetaRow } from "../storage/index-meta-repo.js";
 import type { ArtifactRow, ResolvedSourceArtifact } from "../types.js";
+import { remapJar } from "../tiny-remapper-service.js";
+import { resolveTinyRemapperJar } from "../tiny-remapper-resolver.js";
 export declare const INDEX_SCHEMA_VERSION = 1;
+/**
+ * Injectable dependencies let remap-cache regression tests run without Java.
+ * Production callers use `defaultBinaryRemapDeps`; this is not a public MCP
+ * extension point.
+ */
+export type BinaryRemapDeps = {
+    resolveTinyRemapperJar: typeof resolveTinyRemapperJar;
+    resolveMojangTinyFile: typeof resolveMojangTinyFile;
+    remapJar: typeof remapJar;
+    now: () => number;
+    randomSuffix: () => string;
+};
 export type IndexRebuildReason = "force" | "missing_meta" | "schema_mismatch" | "signature_mismatch" | "already_current";
 export interface IndexedFileRecord {
     filePath: string;
@@ -57,13 +72,12 @@ export declare function ingestIfNeeded(svc: SourceService, resolved: ResolvedSou
  * 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 declare function maybeRemapBinaryForMojang(svc: SourceService, resolved: ResolvedSourceArtifact): Promise<string>;
+export declare function maybeRemapBinaryForMojang(svc: SourceService, resolved: ResolvedSourceArtifact, deps?: BinaryRemapDeps): Promise<string>;
 export declare function recordRemappedJarBytesFromDisk(svc: SourceService, artifactId: string, path: string): Promise<void>;
 /**
  * Best-effort structural check that `path` is a non-empty file beginning with
@@ -73,10 +87,21 @@ export declare function recordRemappedJarBytesFromDisk(svc: SourceService, artif
  * are not (a corrupt cache hit must be evicted).
  */
 export declare function isUsableJarFile(path: string): Promise<boolean>;
+export declare function buildBinaryRemapTempPath(remappedJarPath: string, input: {
+    pid: number;
+    now: number;
+    randomSuffix: string;
+}): string;
 export declare function runBinaryRemap(svc: SourceService, input: {
     version: string;
     inputJar: string;
     remappedDir: string;
     remappedJarPath: string;
 }): Promise<string>;
+export declare function runBinaryRemapWithDeps(svc: SourceService, input: {
+    version: string;
+    inputJar: string;
+    remappedDir: string;
+    remappedJarPath: string;
+}, deps: BinaryRemapDeps): Promise<string>;
 export declare function loadFromSourceJar(svc: SourceService, sourceJarPath: string): Promise<IndexedFileRecord[]>;

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/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/docs/tool-reference.md

@@ -72,6 +72,7 @@ Workspace detection is memoised in a process-resident `WorkspaceContextCache` (1
 ## Common Pitfalls
 
 - `mapping="mojang"` requires source-backed artifacts on legacy obfuscated versions. For unobfuscated releases such as `26.1+`, the runtime/decompile path is accepted directly for version and versioned-coordinate targets. When source jars are not available but the version's Mojang tiny mappings, the tiny-remapper jar, and `MappingService.checkMappingHealth` are all healthy, `resolve-artifact` with `target.kind="version"` will transparently tiny-remap the binary jar (`obfuscated -> mojang`) and decompile the result, and the response carries `qualityFlags` `"binary-remapped"` and `"decompiled"` plus `provenance.transformChain` `"binary-remap:obf->mojang"` and `"decompile:vineflower"`. Coordinate and jar targets are not eligible for this fallback and still surface `ERR_MAPPING_NOT_APPLIED`. Source-backed and obfuscated artifacts keep their existing `artifactId` hashes — only the new mojang-remapped variant lives in a separate cache slot.
+- Mojang binary-remap cache entries live under `<cacheDir>/remapped`. `manage-cache` lists valid files plus corrupt directories and leftover temp entries under `cacheKinds: ["binary-remap"]`; corrupt entries carry `status: "corrupt"` and `meta.artifactId`, so callers can preview or apply cleanup with `selector.artifactId`.
 - `list-artifact-files` indexes Java source paths only. Probing `assets/` or `data/` prefixes will not return non-Java resources.
 - `search-class-source` defaults to `queryMode="auto"`. Use `queryMode="literal"` for explicit substring scans. `match="regex"` enforces `query.length <= 200` and caps results at `100`.
 - `search-class-source` returns compact hits only. Use `get-artifact-file` or `get-class-source` to inspect returned files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "description": "MCP server for AI-assisted Minecraft modding: inspect decompiled source, resolve Mojang/Yarn/Intermediary mappings, diff versions, analyze Fabric/Forge/NeoForge mod JARs, and validate Mixin, Access Widener, and Access Transformer files.",
   "type": "module",
   "main": "dist/index.js",