@adhisang/minecraft-modding-mcp 7.1.0 → 7.1.1

package/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [7.1.1] - 2026-09-25
+
+### Fixed
+
+- `validate-mixin` checks each member against the targets of its own `@Mixin` class. In a file with more than one `@Mixin` class, nested or top-level, every `@Shadow`, `@Accessor`, `@Invoker` and injection was checked against every target in the file, so members were reported missing from the other classes' targets. When a target cannot be mapped or loaded, only the members of the class that names it are skipped. For files with one `@Mixin` class, this per-class checking gives the same results as before. A `@Mixin` that follows other code on the same line, such as `@Pseudo @Mixin(A.class)`, and a second `@Mixin` class on a line that starts with `@Mixin` are now recognized. `@Mixin(value = Foo.class, targets = "pkg.Bar")` checks `pkg.Bar` as well as `Foo`, the only target checked before, and a string target containing `.class`, such as `targets = "net.minecraft.class_1234"`, no longer adds a nonexistent `net.minecraft` target that was reported missing.
+- `validate-mixin` no longer drops members because of how their annotations are written. It reads `@Shadow`, `@Inject` and the other injection annotations, `@Accessor` and `@Invoker` when another annotation precedes them on the same line (`@Final @Shadow private int foo;`, `@Environment(EnvType.CLIENT) @Inject(...)`), when their arguments wrap onto later lines, and, wherever they appear, when an argument string contains a parenthesis, such as `args = "stringValue=)"`. It also keeps a member whose declaration shares the closing line of a wrapped annotation. Such members were skipped, so a mixin with a misspelled `@Shadow` after another annotation was reported clean, their `prefix` and `aliases` were ignored, or their `method` was reported missing. `@Shadow`-like text inside a Java text block (`"""…"""`) no longer creates members, a `'"'` character literal no longer makes the comments after it misread, and annotation-like text inside a preceding annotation's string argument is still ignored.
+- `validate-mixin` reads target-selector quantifiers the way Mixin does: `*`, `+`, `{n}`, `{n,}` and `{n,m}` count the methods of exactly that name. They matched any method whose name started with the text, so `render*` against a class with only `renderItem` was reported valid; it is now reported as a missing method. A descriptor in the selector is still checked, also in name-less selectors such as `*(D)V`. When `+` or `{n}` finds fewer methods than required, the result is an uncertain warning. Whitespace inside a quantifier (`tick{1, 3}`) is accepted, a quantifier that allows no match (`{}`, `{0}`) is flagged as malformed, one whose maximum is below its minimum (`{3,1}`) requires the minimum as in Mixin, and regex selectors (`/pattern/`) are reported as skipped rather than missing. A `method = {"tick{2}", "jump"}` array whose selectors contain braces is read instead of being reported as empty, and a `method` value that is a constant or an expression such as `"a" + "b"` gets a warning that it could not be parsed instead of a check of a fragment of it.
+- `validate-mixin` no longer reports these target members as missing: a `@Shadow` method written with Mixin's `shadow$` prefix or an explicit `prefix = "..."`, a name listed in `aliases`, a synthetic injector target such as the lambda body `lambda$tick$0`, and a synthetic `@Shadow`, `@Accessor` or `@Invoker` member such as an enum's `$VALUES` or an inner class's `this$0`. An explicit `prefix = ""` keeps the declared name, and a `@Shadow` field keeps its declared name because Mixin allows the prefix only on methods. Synthetic and bridge methods also count toward quantified selectors, as in Mixin.
+- `validate-mixin` no longer reports a mixin as valid because `warningCategoryFilter` hid its only error. The filter now narrows `issues`, `structuredWarnings` and the `summary` counts only: `valid`, `validationStatus` and `quickSummary` are what the same call reports without the filter, `unfilteredSummary` keeps the true counts, and the automatic retry with Maven-first mapping sources is decided as if no category filter were set. `toolHealth.overallHealthy` now reflects only the mappings the request needs: Mojang mappings for `mojang`, Tiny mappings for `yarn` and `intermediary`, and only the game jar for `obfuscated`. It reported unhealthy whenever Mojang mappings were missing, which lowered the confidence score and turned descriptor mismatches into warnings even for requests that never use them.
+- `validate-mixin` and `validate-project` validate a nested mixin listed in a mixins config as `Outer$Inner` (or `Outer$Mid$Inner`): the class is read from `Outer.java`, and only its own members, `@Mixin` targets and priority are checked. Such an entry was reported as a missing `Outer$Inner.java`. A nested name that `Outer.java` does not declare is reported as a processing error naming the class and the file; a class declared inside a method cannot be addressed this way. Every config entry now validates only its own class, so an entry `Outer` no longer checks the nested mixins declared inside `Outer.java`, whether or not they are listed as their own entries.
+- `validate-mixin` in config mode rejects a config that is not a JSON object, whose `mixins`, `client` or `server` is not an array of strings, or whose `package` is not a string, with `ERR_INVALID_INPUT` naming the config path and the offending key. Such configs crashed with `ERR_INTERNAL` or were silently misread.
+- `validate-project` with `task: "mixin"` or `task: "project-summary"` reports `status: "partial"` when mixin inputs could not be loaded, counts them under `counts.processingErrors`, and says how many could not be processed (in the headline for `project-summary`). Both reported `status: "ok"`, and `task: "mixin"` said `Validated N mixin input(s).`
+- `validate-project` with `task: "access-widener"` returns the invalid entries in its `issues` block under `detail: "standard"` or `"full"`, or with `include: ["issues"]`. The block was always omitted, so the counts said `invalid: 1` with no way to learn which line failed.
+- `validate-access-widener` and `validate-project` with `task: "access-widener"` report a file invalid when it breaks the Fabric access-widener grammar: `mutable` on a class or method, `extendable` on a field, a `transitive-` entry under a `v1` header, an unsupported header version, a missing header, or a line before the header that is neither blank nor a comment. Such files were reported valid whenever their symbols existed. `validate-access-widener`, `validate-access-transformer` and their `validate-project` tasks also report a file invalid when it contains a line they cannot understand, naming the line; a file whose only line was malformed was reported valid with zero entries. A file with a `classTweaker` header is reported as an unsupported format rather than an invalid access widener: `ERR_INVALID_INPUT` from `validate-access-widener` and from `validate-project` with `task: "access-widener"`, and a processing error with a warning in `validate-project` `project-summary`.
+- `verify-mixin-target` suggests `@Shadow` for a public or protected field, since mixin code needs `@Shadow` to reference any target field; it suggested `@Inject-only`, which applies only to methods. For a visible method, the reasoning says no `@Invoker` is needed and that `@Inject` hooks it while `@Shadow` calls it. The `@Shadow` example for a static field keeps `static`. A package-private target is named `package-private` in the reasoning text instead of private; `suggestedAnnotation` is unchanged. The rule matrix in `docs/tool-reference.md` lists fields and methods separately and lists package-private alongside private.
+- Mapping lookups return only symbols of the kind that was asked for. A field whose name equals a same-class method's name, such as a record component and its accessor or a reused obfuscated name, was remapped to the method's mapped name with no warning, which reached `get-class-members`, `validate-mixin`, `validate-access-widener` and `diff-class-signatures`. A `find-mapping` field query whose name equals a class's simple name resolved to the class.
+- A mapped method's `symbol` string and `descriptor` are now in the same namespace. After the descriptor was translated, `symbol` still embedded the source-namespace descriptor.
+- `find-mapping` with `signatureMode: "exact"` and `resolve-method-mapping-exact` resolve a Mojang-to-Yarn method whose mappings are split across separate per-namespace files (a Mojang ProGuard file plus `official → intermediary` and `intermediary → named` Tiny files). They answered `not_found`.
+- A pre-release Minecraft jar is no longer served as an exact match for the release it precedes: `1.21` no longer matches a `1.21-rc1` artifact and `26.1` no longer matches `26.1-pre-1`, so `strictVersion: true` refuses the substitution and the served version is flagged as approximate instead of being accepted silently.
+- Runtime jars for Minecraft 26.1 and later are recognized by version, so `validate-access-widener`, `validate-access-transformer` and `resolve-artifact` provenance report the version actually served, with `requestedVersion` and the approximation flag, instead of echoing the requested one. A jar named `minecraft-merged-26.2-pre-6.jar` is read as its full version, `26.2-pre-6`. Neither a loader's own version number, such as Forge `47.3.0`, nor a version in the name of a directory above the build tool's own folders, such as a project checked out as `mymod-1.21`, is taken for the jar's Minecraft version; that directory name made the access-widener and access-transformer checks look up another version's mappings and report a false approximation.
+- Workspace detection ignores commented-out Gradle lines. `resolve-workspace-symbol` and the other workspace-aware tools skip commented-out `mappings` declarations in `build.gradle` and `build.gradle.kts`, so a Yarn project that keeps a `// mappings loom.officialMojangMappings()` line is detected as Yarn instead of refused with conflicting mappings. Kotlin nested block comments, Kotlin raw strings and Groovy `$/…/$` strings are read by their own rules; text inside ordinary string literals, such as a repository URL, is still treated as code. Loader detection for workspace targets and `validate-project` no longer counts a `// id 'fabric-loom'` line or an `accessTransformer` mention inside a block comment as evidence of a loader.
+- A workspace's detected Minecraft version, mapping and loader are refreshed as soon as `gradle.properties`, the project's root `build.gradle` or `build.gradle.kts`, or a subproject build script or mod descriptor that declared a mapping or loader changes, instead of being served from the 5-minute workspace cache. Other subproject build scripts are still picked up when the cache expires; the tool reference lists the exact files.
+- Windows-style and WSL paths are translated on WSL in three more places. `projectPath` on `target.kind: "workspace"` and `"dependency"` targets and with `preferProjectVersion` is accepted as on the other routes; `C:\dev\mymod` on a WSL host failed to find `gradle.properties`. A `GRADLE_USER_HOME` written as `C:\...` or `\\wsl$\...` is used wherever the Gradle cache is searched; resolving a Maven coordinate from the Gradle cache and inferring a `target.kind: "dependency"` version found nothing. The recovery advice after a mapping could not be applied suggests retrying against the workspace for a Windows or UNC `projectPath`, as it already did for a Linux path, instead of generic advice.
+- Text search (`search-class-source`, `inspect-minecraft` with `task: "search"`) finds a query whose words are full-text search operators, such as `BooleanOp.AND`. Such a query silently returned no hits, and a query like `a NOT b` quietly searched for something else.
+- Text and path search (`search-class-source`, `inspect-minecraft` with `task: "search"`) with `scope.packagePrefix`, or with a `scope.fileGlob` that starts with a literal directory such as `net/minecraft/world/**`, finds in-scope matches even when many out-of-scope files also match; those matches could come back as no hits at all. A glob without a literal directory prefix still filters only the bounded set of candidates a search checks; the tool reference describes that limit and how to search past it. A `search-class-source` text or path search that returns fewer hits than `limit` while the index matched more files than the search checks in one pass (500 for `match: "exact"`/`"prefix"`, 1,000 by default for `"contains"`) now says so in `warnings`, suggesting `queryMode: "literal"` for text, `match: "regex"` for paths, or a narrower `packagePrefix` or literal-prefixed `fileGlob`. It returned the short page silently; the hits and their order are unchanged.
+- `get-signature` and every tool built on it report a truncated or corrupted class file, including a bad magic number, an unsupported constant-pool tag, a class cut short inside its last attribute, or a malformed member descriptor in the bytecode, as `ERR_CLASS_NOT_FOUND` naming the class and jar. These cases answered `ERR_INTERNAL`, `ERR_INVALID_INPUT` (blaming the caller for a third-party jar's content), or parsed the truncated class as if it were complete.
+- `get-class-members` honors `includeAnnotations: true`. The option was accepted but had no effect when called through the MCP tool, so member annotations such as `@Deprecated` were never returned.
+- `find-class` reports `nested: true` and `enclosingClass` for an inner class looked up by a qualified name such as `a.b.Outer.Inner`, and for one found through a Jar-in-Jar shell jar. It already did so for an unqualified lookup and for a class found in the artifact's own index.
+- An unusable file path reports `ERR_INVALID_INPUT`, naming the path and the OS error code, instead of `ERR_INTERNAL`: in `get-class-source` and `get-mod-class-source` when the `outputFile` path cannot be written because its parent directory does not exist, it is a directory, or it is not writable, and in `validate-project` with a `task` of `access-widener` or `access-transformer` and a `subject.input.mode` of `path` when the file cannot be read.
+- Recovery suggestions now propose calls that can succeed. When a `mapping` request on a `target.kind: "jar"` source jar is refused because the jar's Minecraft version is unknown, the advice is a fillable `resolve-artifact` example with a version placeholder; it fed the jar path back as a Minecraft version. `ERR_WORKSPACE_VERSION_UNRESOLVED` carries `exampleCalls` with a `target.kind: "version"` retry to fill in; it carried no retry suggestion at all, although the tool reference said it did, and the tool reference now also names the `exampleCalls` field for `ERR_DEPENDENCY_VERSION_UNRESOLVED`. `inspect-minecraft` with `task: "versions"` omits its follow-up suggestion when the version manifest lists no release, instead of suggesting a call with no version.
+- `manage-cache` with `action: "rebuild"` reports that it rebuilt nothing and points at `action: "delete"` instead, since deleted entries are rebuilt from source the next time they are needed. It reported `status: "changed"` and a count of rebuilt entries without rebuilding anything, and the preview offered an apply follow-up that would change nothing. The README tool table no longer lists rebuild among the cache operations.
+- `manage-cache` with `action: "verify"` no longer reports every artifact-index entry as `in_use` while the server has its cache database open, so artifact-index entries show their real health (`healthy`, `stale`, `partial` or `orphaned`) and a `selector.status` other than `in_use` matches them, including for `delete` and `prune`. Deleting or pruning file caches no longer opens and integrity-checks the whole cache database when no artifact-index entry was selected.
+- `remap-mod-jar` without `outputJar` returns the same output path, next to the input jar, whether or not the remapped jar was already cached. A cached result was returned from the server's internal cache directory instead.
+- Detecting whether a mod jar uses intermediary or Mojang names no longer falls back to a low-confidence result for a jar that repeats an entry name.
+- When the server's worker process restarts and the client re-sends `initialize`, tool calls that queued in the meantime are no longer delivered to the replacement worker ahead of the handshake. The re-sent `initialize` now goes first, and the queued calls are released once it is answered.
+- When the server's worker process crashes or is killed from outside on Linux or macOS, the processes it started, such as a Java decompiler, are stopped with it instead of being left running. On Windows, processes started by a worker that has already exited are still not cleaned up. A Java subprocess (the decompiler and the other Java helpers) that is stopped for exceeding its time limit but ignores the stop request is now force-killed after 3 seconds; it was left running.
+- A failed Minecraft version-manifest request releases its response body instead of holding the connection until garbage collection, and a nested (Jar-in-Jar) jar that cannot be moved into the cache after extraction no longer leaves its temporary file there.
+
+### Documentation
+
+- The tool reference documents a known issue: `get-class-source` with `mode: "metadata"` returns a generated outline of the class's symbols, yet reports `returnedRange` as the whole source file and, unless `maxChars` cut the outline, `truncated: false`. Do not use those values to address lines of the outline; use `mode: "snippet"` or `"full"` for line numbers. A future major release will replace them with fields specific to the metadata mode.
+
 ## [7.1.0] - 2026-09-19
 
 ### Added

package/README.md

@@ -279,7 +279,7 @@ Start with these top-level workflow tools unless you already know the exact spec
 | `compare-minecraft` | Compare version pairs, class diffs, registry diffs, and migration-oriented summaries |
 | `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, read class members from bytecode, and preview or apply remaps |
 | `validate-project` | Summarize workspaces and run direct Mixin, Access Widener, or Access Transformer validation |
-| `manage-cache` | List, verify, and preview or apply cache cleanup and rebuild operations |
+| `manage-cache` | List, verify, and preview or apply cache cleanup operations |
 <!-- END GENERATED TOOL TABLE: top-level-workflow-tools -->
 
 ### Source Exploration

package/dist/access-transformer-parser.d.ts

@@ -14,5 +14,13 @@ export type AccessTransformerEntry = {
 export type ParsedAccessTransformer = {
     entries: AccessTransformerEntry[];
     parseWarnings: string[];
+    /**
+     * Count of lines the parser had to drop for malformed syntax (unsupported
+     * access declaration, incomplete entry, missing member name/descriptor). A
+     * caller-visible validator uses this to force its verdict invalid even when
+     * `entries` is empty. Optional (defaults to 0) so hand-built
+     * `ParsedAccessTransformer` fixtures that predate this field keep working.
+     */
+    rejectedEntryCount?: number;
 };
 export declare function parseAccessTransformer(content: string): ParsedAccessTransformer;

package/dist/access-transformer-parser.js

@@ -50,6 +50,7 @@ export function parseAccessTransformer(content) {
     const entries = [];
     const parseWarnings = [];
     const lines = content.split(/\r?\n/);
+    let rejectedEntryCount = 0;
     for (let index = 0; index < lines.length; index++) {
         const lineNumber = index + 1;
         const rawLine = (lines[index] ?? "").trim();
@@ -63,25 +64,30 @@ export function parseAccessTransformer(content) {
         const parts = withoutComment.split(/\s+/);
         if (parts.length < 2) {
             parseWarnings.push(`Line ${lineNumber}: Incomplete access transformer entry "${withoutComment}".`);
+            rejectedEntryCount++;
             continue;
         }
         const declaration = parseAccessDeclaration(parts[0] ?? "");
         if (!declaration) {
             parseWarnings.push(`Line ${lineNumber}: Unsupported access declaration "${parts[0]}".`);
+            rejectedEntryCount++;
             continue;
         }
         const owner = parts[1] ?? "";
         if (!owner) {
             parseWarnings.push(`Line ${lineNumber}: Incomplete access transformer entry "${withoutComment}".`);
+            rejectedEntryCount++;
             continue;
         }
         const member = splitMemberToken(parts.slice(2));
         if (member.targetKind === "method" && (!member.name || !member.descriptor)) {
             parseWarnings.push(`Line ${lineNumber}: Method entry requires a method name and JVM descriptor.`);
+            rejectedEntryCount++;
             continue;
         }
         if ((member.targetKind === "field" || member.targetKind === "method") && !member.name) {
             parseWarnings.push(`Line ${lineNumber}: Member entry requires a target name.`);
+            rejectedEntryCount++;
             continue;
         }
         const target = member.targetKind === "class"
@@ -100,7 +106,8 @@ export function parseAccessTransformer(content) {
     }
     return {
         entries,
-        parseWarnings
+        parseWarnings,
+        rejectedEntryCount
     };
 }
 //# sourceMappingURL=access-transformer-parser.js.map

package/dist/access-widener-parser.d.ts

@@ -21,5 +21,22 @@ export type ParsedAccessWidener = {
     namespace: string;
     entries: AccessWidenerEntry[];
     parseWarnings: string[];
+    /**
+     * Count of entry lines the parser had to drop for malformed syntax (unknown
+     * kind/target kind, incomplete entry, missing descriptor), plus any
+     * non-comment line preceding the header. Excludes the header-line warnings
+     * of a file that has no header at all. A caller-visible validator
+     * uses this to force its verdict invalid even when `entries` is empty.
+     * Optional (defaults to 0) so hand-built `ParsedAccessWidener` fixtures
+     * that predate this field keep working.
+     */
+    rejectedEntryCount?: number;
+    /**
+     * The line number the `accessWidener <version> <namespace>` header was
+     * found on, when a syntactically well-formed header line was found (set
+     * even when its version is unsupported). Undefined when no header line
+     * matched the expected format at all; callers fall back to line 1.
+     */
+    headerLine?: number;
 };
 export declare function parseAccessWidener(content: string): ParsedAccessWidener;

package/dist/access-widener-parser.js

@@ -14,6 +14,10 @@ export function parseAccessWidener(content) {
     const entries = [];
     let headerVersion = "";
     let namespace = "";
+    let rejectedEntryCount = 0;
+    let headerLine;
+    // Fabric requires the header first, so lines before a later header are rejected once it appears.
+    let preHeaderLineCount = 0;
     for (let i = 0; i < lines.length; i++) {
         const raw = lines[i].trim();
         const lineNum = i + 1;
@@ -26,9 +30,12 @@ export function parseAccessWidener(content) {
             if (parts[0] === "accessWidener" && parts.length >= 3) {
                 headerVersion = parts[1];
                 namespace = parts[2];
+                headerLine = lineNum;
+                rejectedEntryCount += preHeaderLineCount;
             }
             else {
                 parseWarnings.push(`Line ${lineNum}: Expected accessWidener header, got: "${raw}"`);
+                preHeaderLineCount++;
             }
             continue;
         }
@@ -36,6 +43,7 @@ export function parseAccessWidener(content) {
         const parts = raw.split(/\s+/);
         if (parts.length < 3) {
             parseWarnings.push(`Line ${lineNum}: Incomplete entry: "${raw}"`);
+            rejectedEntryCount++;
             continue;
         }
         const kind = parts[0];
@@ -44,10 +52,12 @@ export function parseAccessWidener(content) {
         const baseKind = transitive ? kind.slice("transitive-".length) : kind;
         if (!VALID_KINDS.has(baseKind)) {
             parseWarnings.push(`Line ${lineNum}: Unknown access kind "${kind}".`);
+            rejectedEntryCount++;
             continue;
         }
         if (!VALID_TARGET_KINDS.has(targetKind)) {
             parseWarnings.push(`Line ${lineNum}: Unknown target kind "${targetKind}".`);
+            rejectedEntryCount++;
             continue;
         }
         const validKind = baseKind;
@@ -70,11 +80,12 @@ export function parseAccessWidener(content) {
         }
         else {
             parseWarnings.push(`Line ${lineNum}: ${validTargetKind} entry requires owner, name, and descriptor.`);
+            rejectedEntryCount++;
         }
     }
     if (!headerVersion) {
         parseWarnings.push("Missing accessWidener header.");
     }
-    return { headerVersion, namespace, entries, parseWarnings };
+    return { headerVersion, namespace, entries, parseWarnings, rejectedEntryCount, headerLine };
 }
 //# sourceMappingURL=access-widener-parser.js.map

package/dist/cache-registry.js

@@ -414,7 +414,6 @@ async function artifactIndexEntries(config) {
         ON artifact_content_bytes.artifact_id = artifacts.artifact_id
       ORDER BY artifacts.updated_at DESC
     `).all();
-        const dbInUse = existsSync(`${config.sqlitePath}-wal`) || existsSync(`${config.sqlitePath}-journal`);
         return rows.map((row) => {
             const qualityFlags = parseStringArray(row.quality_flags_json);
             const binaryJarPath = row.binary_jar_path ?? undefined;
@@ -437,7 +436,9 @@ async function artifactIndexEntries(config) {
                     projectPath: inferProjectPath(binaryJarPath ?? sourceJarPath, config.pathRuntimeInfo),
                     scope: inferScope(binaryJarPath, sourceJarPath, ...qualityFlags) ?? "vanilla",
                     partial: qualityFlags.some((flag) => flag.includes("partial")),
-                    inUse: dbInUse
+                    // A WAL file only shows that a connection (usually ours) has the database open.
+                    // SQLite transactions already serialize row deletes; it says nothing about this entry.
+                    inUse: false
                 }
             };
         });
@@ -722,7 +723,11 @@ export function createCacheRegistry(config) {
                         downloadIdentities.set(entry.path, await readDownloadEntryIdentity(entry.path));
                     }
                 }
-                const db = openDb(config);
+                // Opening the index runs a PRAGMA quick_check over the whole file, so
+                // only pay for it when a row of it is actually going to be deleted.
+                const db = entries.some((entry) => entry.cacheKind === "artifact-index")
+                    ? openDb(config)
+                    : undefined;
                 try {
                     for (const entry of entries) {
                         if (entry.cacheKind === "artifact-index") {
@@ -791,10 +796,18 @@ export function createCacheRegistry(config) {
             return this.deleteEntries(input);
         },
         async rebuildEntries(input) {
-            const entries = await collectEntries(input.cacheKinds, input.selector);
+            // No cache kind knows how to rebuild itself from here: the previous
+            // implementation only counted the entries a selector matched and reported
+            // that count as "rebuilt", so apply mode claimed a change it never made.
+            // Validate the selector the way every other action does - the inventory
+            // itself would be thrown away - then say what actually happened.
+            prepareSelector(input.selector, config.pathRuntimeInfo);
+            const selectedKinds = input.cacheKinds?.length ? input.cacheKinds : [...PUBLIC_CACHE_KINDS];
             return {
-                rebuiltEntries: entries.length,
-                warnings: []
+                rebuiltEntries: 0,
+                warnings: [
+                    `rebuild is not implemented for cache kind(s): ${selectedKinds.join(", ")}. Nothing was rebuilt. Delete the matching entries instead (manage-cache action="delete"); each one is rebuilt from source the next time it is needed.`
+                ]
             };
         }
     };

package/dist/entry-tools/inspect-minecraft/handlers/versions.js

@@ -5,6 +5,10 @@ export async function handleVersions(deps, input, detail, include) {
         includeSnapshots: input.includeSnapshots,
         limit: input.limit
     });
+    // versions.latest.release and releases[0] can both be absent for an effectively
+    // empty version manifest; omit the nextAction rather than suggest an unusable
+    // follow-up call with no version.
+    const resolvedNextVersion = versions.latest.release ?? versions.releases[0]?.id;
     const summary = {
         status: "ok",
         headline: `Found ${versions.totalAvailable} Minecraft versions.`,
@@ -18,15 +22,17 @@ export async function handleVersions(deps, input, detail, include) {
             releases: versions.releases.length,
             snapshots: versions.snapshots?.length ?? 0
         },
-        nextActions: nextActionsOrUndefined([
-            createNextAction("inspect-minecraft", {
-                task: "artifact",
-                subject: {
-                    kind: "version",
-                    version: versions.latest.release ?? versions.releases[0]?.id
-                }
-            })
-        ])
+        nextActions: nextActionsOrUndefined(resolvedNextVersion !== undefined
+            ? [
+                createNextAction("inspect-minecraft", {
+                    task: "artifact",
+                    subject: {
+                        kind: "version",
+                        version: resolvedNextVersion
+                    }
+                })
+            ]
+            : [])
     };
     return {
         ...buildEntryToolResult({

package/dist/entry-tools/manage-cache-service.js

@@ -225,23 +225,19 @@ export class ManageCacheService {
                         include,
                         summary: {
                             status: output.rebuiltEntries > 0 && executionMode === "apply" ? "changed" : "unchanged",
-                            headline: `${executionMode === "apply" ? "Applied" : "Previewed"} rebuild for ${cacheKinds.length} cache kind(s).`,
+                            // Neither headline may read as work done: rebuild is not
+                            // implemented for any cache kind, so apply changes nothing and
+                            // preview has nothing to promise.
+                            headline: executionMode === "apply"
+                                ? `Rebuild is not implemented for ${cacheKinds.length} cache kind(s); nothing changed.`
+                                : `Previewed rebuild for ${cacheKinds.length} cache kind(s): nothing would change.`,
                             subject: summarySubject,
                             counts: {
                                 rebuiltEntries: output.rebuiltEntries
-                            },
-                            ...(executionMode === "preview"
-                                ? {
-                                    nextActions: [
-                                        createNextAction("manage-cache", {
-                                            action: "rebuild",
-                                            cacheKinds,
-                                            executionMode: "apply",
-                                            selector: input.selector
-                                        })
-                                    ]
-                                }
-                                : {})
+                            }
+                            // No apply follow-up: rebuild is not implemented for any cache
+                            // kind, so advertising one would promise a call that changes
+                            // nothing. The registry's warning names what to do instead.
                         },
                         blocks: {
                             operation: {

package/dist/entry-tools/validate-project/cases/access-transformer.js

@@ -34,9 +34,28 @@ export async function handleAccessTransformer(deps, input, detail, include) {
             }
         });
     }
-    const content = input.subject.input.mode === "inline"
-        ? input.subject.input.content
-        : await readFile(input.subject.input.path, "utf8");
+    let content;
+    if (input.subject.input.mode === "inline") {
+        content = input.subject.input.content;
+    }
+    else {
+        const atPath = input.subject.input.path;
+        try {
+            content = await readFile(atPath, "utf8");
+        }
+        catch (err) {
+            const osCode = err?.code ?? "UNKNOWN";
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `Could not read access transformer file "${atPath}": ${osCode} - ${err instanceof Error ? err.message : String(err)}`,
+                details: {
+                    task: "access-transformer",
+                    failedStage: "input-validation",
+                    nextAction: `Verify the file exists and is readable at "${atPath}".`
+                }
+            });
+        }
+    }
     if (!deps.validateAccessTransformer) {
         throw createError({
             code: ERROR_CODES.CONTEXT_UNRESOLVED,

package/dist/entry-tools/validate-project/cases/access-widener.js

@@ -34,9 +34,28 @@ export async function handleAccessWidener(deps, input, detail, include) {
             }
         });
     }
-    const content = input.subject.input.mode === "inline"
-        ? input.subject.input.content
-        : await readFile(input.subject.input.path, "utf8");
+    let content;
+    if (input.subject.input.mode === "inline") {
+        content = input.subject.input.content;
+    }
+    else {
+        const awPath = input.subject.input.path;
+        try {
+            content = await readFile(awPath, "utf8");
+        }
+        catch (err) {
+            const osCode = err?.code ?? "UNKNOWN";
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `Could not read access widener file "${awPath}": ${osCode} - ${err instanceof Error ? err.message : String(err)}`,
+                details: {
+                    task: "access-widener",
+                    failedStage: "input-validation",
+                    nextAction: `Verify the file exists and is readable at "${awPath}".`
+                }
+            });
+        }
+    }
     const output = await deps.validateAccessWidener({
         content,
         version: input.version,
@@ -45,6 +64,14 @@ export async function handleAccessWidener(deps, input, detail, include) {
         scope: input.scope,
         preferProjectVersion: input.preferProjectVersion
     });
+    const issueEntries = Array.isArray(output.entries)
+        ? output.entries.filter((entry) => {
+            if (!entry || typeof entry !== "object" || !("valid" in entry)) {
+                return true;
+            }
+            return entry.valid !== true;
+        })
+        : undefined;
     return {
         ...buildEntryToolResult({
             task: "access-widener",
@@ -76,7 +103,7 @@ export async function handleAccessWidener(deps, input, detail, include) {
                         invalid: output.valid ? 0 : 1
                     }
                 },
-                issues: include.includes("issues") || detail !== "summary" ? output.issues : undefined
+                issues: include.includes("issues") || detail !== "summary" ? issueEntries : undefined
             },
             alwaysBlocks: ["project"]
         }),

package/dist/entry-tools/validate-project/cases/mixin.js

@@ -74,14 +74,21 @@ export async function handleMixin(deps, input, detail, include) {
     const summary = output.summary;
     const invalidCount = summary?.invalid ?? 0;
     const partialCount = summary?.partial ?? 0;
+    const processingErrorsCount = summary?.processingErrors ?? 0;
     return {
         ...buildEntryToolResult({
             task: "mixin",
             detail,
             include,
             summary: {
-                status: invalidCount > 0 ? "invalid" : partialCount > 0 ? "partial" : "ok",
-                headline: `Validated ${summary?.total ?? 0} mixin input(s).`,
+                status: invalidCount > 0
+                    ? "invalid"
+                    : partialCount > 0 || processingErrorsCount > 0
+                        ? "partial"
+                        : "ok",
+                headline: processingErrorsCount > 0
+                    ? `Validated ${summary?.total ?? 0} mixin input(s); ${processingErrorsCount} could not be processed.`
+                    : `Validated ${summary?.total ?? 0} mixin input(s).`,
                 subject: createSummarySubject({
                     task: "mixin",
                     kind: input.subject.kind,
@@ -94,7 +101,8 @@ export async function handleMixin(deps, input, detail, include) {
                 counts: {
                     valid: summary?.valid ?? 0,
                     partial: partialCount,
-                    invalid: invalidCount
+                    invalid: invalidCount,
+                    processingErrors: processingErrorsCount
                 }
             },
             blocks: {

package/dist/entry-tools/validate-project/cases/project-summary.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { mapWithConcurrencyLimit } from "../../../concurrency.js";
 import { buildEntryToolResult, createSummarySubject } from "../../response-contract.js";
-import { ERROR_CODES, createError } from "../../../errors.js";
+import { ERROR_CODES, createError, isAppError } from "../../../errors.js";
 import { buildEarlyTasksForBlocked, buildFullTaskStatusReport } from "../internal.js";
 // Telemetry failures must not change validation outcomes; swallow rejections
 // so a broken emitter does not abort the summary or count as a validation error.
@@ -248,6 +248,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
     let validMixins = 0;
     let partialMixins = 0;
     let invalidMixins = 0;
+    let mixinProcessingErrors = 0;
     let mixinCaughtErrors = 0;
     await safeEmit(options.stageEmitter, "validate-project:mixin-validation", {
         targetTotal: mixinConfigs.length
@@ -296,6 +297,8 @@ export async function handleProjectSummary(deps, input, detail, include, options
                 valid: summary?.valid ?? 0,
                 partial: summary?.partial ?? 0,
                 invalid: summary?.invalid ?? 0,
+                // Mixin sources that failed to load count in none of valid/partial/invalid.
+                processingErrors: summary?.processingErrors ?? 0,
                 caught: 0,
                 warnings: Array.isArray(mixinResult.warnings) ? [...mixinResult.warnings] : []
             };
@@ -305,6 +308,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
                 valid: 0,
                 partial: 0,
                 invalid: 1,
+                processingErrors: 0,
                 caught: 1,
                 warnings: error instanceof Error ? [`${configPath}: ${error.message}`] : []
             };
@@ -314,6 +318,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
         validMixins += result.valid;
         partialMixins += result.partial;
         invalidMixins += result.invalid;
+        mixinProcessingErrors += result.processingErrors;
         mixinCaughtErrors += result.caught;
         warnings.push(...result.warnings);
     }
@@ -322,6 +327,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
     let validAw = 0;
     let invalidAw = 0;
     let awCaughtErrors = 0;
+    let awProcessingErrors = 0;
     await safeEmit(options.stageEmitter, "validate-project:access-widener-validation", {
         targetTotal: accessWideners.length
     });
@@ -353,6 +359,12 @@ export async function handleProjectSummary(deps, input, detail, include, options
             }
         }
         catch (error) {
+            if (isAppError(error) && error.details?.unsupportedFormat === "classTweaker") {
+                // A format this server does not read is not a verdict on the file.
+                awProcessingErrors += 1;
+                warnings.push(`${awPath}: ${error.message}`);
+                continue;
+            }
             invalidAw += 1;
             awCaughtErrors += 1;
             if (error instanceof Error) {
@@ -412,7 +424,12 @@ export async function handleProjectSummary(deps, input, detail, include, options
     const atDurationMs = Date.now() - atDurationStart;
     const invalidCount = invalidMixins + invalidAw + invalidAt;
     const partialCount = partialMixins;
-    const status = invalidCount > 0 ? "invalid" : partialCount > 0 ? "partial" : "ok";
+    const processingErrors = mixinProcessingErrors + awProcessingErrors;
+    const status = invalidCount > 0
+        ? "invalid"
+        : partialCount > 0 || processingErrors > 0
+            ? "partial"
+            : "ok";
     const nothingToValidate = mixinConfigs.length === 0 && accessWideners.length === 0 && accessTransformers.length === 0
         ? describeNothingToValidate(discover, projectPath)
         : undefined;
@@ -426,7 +443,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
         summary: {
             status,
             headline: nothingToValidate?.headline ??
-                `Validated ${mixinConfigs.length} mixin config(s), ${accessWideners.length} access widener(s), and ${accessTransformers.length} access transformer(s).`,
+                `Validated ${mixinConfigs.length} mixin config(s), ${accessWideners.length} access widener(s), and ${accessTransformers.length} access transformer(s)${mixinProcessingErrors > 0 ? `; ${mixinProcessingErrors} mixin input(s) could not be processed` : ""}${awProcessingErrors > 0 ? `; ${awProcessingErrors} access widener(s) could not be processed` : ""}.`,
             subject: createSummarySubject({
                 task: "project-summary",
                 kind: input.subject.kind,
@@ -440,7 +457,8 @@ export async function handleProjectSummary(deps, input, detail, include, options
             counts: {
                 valid: validMixins + validAw + validAt,
                 partial: partialCount,
-                invalid: invalidCount
+                invalid: invalidCount,
+                processingErrors
             }
         },
         blocks: {
@@ -448,7 +466,8 @@ export async function handleProjectSummary(deps, input, detail, include, options
                 summary: {
                     valid: validMixins + validAw + validAt,
                     partial: partialCount,
-                    invalid: invalidCount
+                    invalid: invalidCount,
+                    processingErrors
                 }
             },
             workspace: {