@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.1

package/dist/tool-schemas.js

@@ -99,11 +99,13 @@ export const resolveArtifactTargetSchema = z.discriminatedUnion("kind", [
     workspaceTargetSchema,
     dependencyTargetSchema
 ]);
-// Extended target schema for the source-lookup tools (get-class-source / get-class-members):
-// the same kind-based shape as resolveArtifactTargetSchema, PLUS a `kind:"artifact"` variant
-// that short-circuits resolution by reusing an already-resolved artifactId. The shared
-// resolveArtifactTargetSchema is intentionally NOT widened — the artifact kind has no
-// resolution meaning for resolve-artifact / verify-mixin-target / the batch tools.
+// Extended target schema for the source-lookup tools (get-class-source / get-class-members)
+// and the batch tools that fan out over one shared artifact (batch-class-source /
+// batch-class-members): the same kind-based shape as resolveArtifactTargetSchema, PLUS a
+// `kind:"artifact"` variant that short-circuits resolution by reusing an already-resolved
+// artifactId. The shared resolveArtifactTargetSchema is intentionally NOT widened —
+// the artifact kind has no resolution meaning for resolve-artifact / verify-mixin-target,
+// which resolve a target rather than reuse one.
 export const sourceLookupTargetSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("version"), value: nonEmptyString }),
     z.object({ kind: z.literal("jar"), value: nonEmptyString }),
@@ -238,7 +240,7 @@ export const batchClassSourceEntrySchema = z.object({
     outputFile: optionalNonEmptyString
 });
 export const batchClassSourceShape = {
-    target: resolveArtifactTargetSchema.describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
+    target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     mapping: sourceMappingSchema.optional(),
     sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().optional(),
@@ -294,7 +296,7 @@ export const batchClassMembersEntrySchema = z.object({
     maxMembers: optionalPositiveInt
 });
 export const batchClassMembersShape = {
-    target: resolveArtifactTargetSchema.describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
+    target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     mapping: sourceMappingSchema.optional(),
     sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().optional(),

package/dist/types.d.ts

@@ -75,6 +75,15 @@ export interface ArtifactProvenance {
         repoUrl?: string;
     };
     transformChain: string[];
+    /**
+     * The artifact's runtime names ship unobfuscated (Minecraft 26.1+): set for a
+     * 26.1+ version target, a 26.1+ Minecraft runtime coordinate, and a jar target
+     * proven to be a 26.1+ runtime jar; absent otherwise. `mappingApplied` keeps the
+     * label the caller asked for, so on such an artifact "obfuscated" names the
+     * as-shipped names, which are already Mojang names. Same flag name as
+     * `mappingContext.unobfuscatedRuntime`.
+     */
+    unobfuscatedRuntime?: boolean;
     workspaceResolution?: WorkspaceResolutionProvenance;
     dependencyResolution?: DependencyResolutionProvenance;
     warnings?: string[];

package/dist/v1-parity-schemas.js

@@ -446,9 +446,26 @@ export const V1_PARITY_SCHEMAS = {
                             "name"
                         ],
                         "additionalProperties": false
+                    },
+                    {
+                        "type": "object",
+                        "properties": {
+                            "kind": {
+                                "type": "string",
+                                "const": "artifact"
+                            },
+                            "artifactId": {
+                                "$ref": "#/properties/target/anyOf/0/properties/value"
+                            }
+                        },
+                        "required": [
+                            "kind",
+                            "artifactId"
+                        ],
+                        "additionalProperties": false
                     }
                 ],
-                "description": "Object, not string. e.g. {\"kind\":\"version\",\"value\":\"1.21.10\"}, {\"kind\":\"workspace\"}, or to inspect a loader/Fabric dependency like vanilla: {\"kind\":\"dependency\",\"group\":\"net.fabricmc.fabric-api\",\"name\":\"fabric-api\",\"versionFromProject\":true} (needs projectPath) or with an explicit \"version\"."
+                "description": "Same shape as resolve-artifact target (incl. {\"kind\":\"dependency\",...} to read a Fabric/loader dependency class like vanilla), plus {\"kind\":\"artifact\",\"artifactId\":\"...\"} to reuse a resolved artifact. Object, not string."
             },
             "mapping": {
                 "type": "string",
@@ -706,9 +723,26 @@ export const V1_PARITY_SCHEMAS = {
                             "name"
                         ],
                         "additionalProperties": false
+                    },
+                    {
+                        "type": "object",
+                        "properties": {
+                            "kind": {
+                                "type": "string",
+                                "const": "artifact"
+                            },
+                            "artifactId": {
+                                "$ref": "#/properties/target/anyOf/0/properties/value"
+                            }
+                        },
+                        "required": [
+                            "kind",
+                            "artifactId"
+                        ],
+                        "additionalProperties": false
                     }
                 ],
-                "description": "Object, not string. e.g. {\"kind\":\"version\",\"value\":\"1.21.10\"}, {\"kind\":\"workspace\"}, or to inspect a loader/Fabric dependency like vanilla: {\"kind\":\"dependency\",\"group\":\"net.fabricmc.fabric-api\",\"name\":\"fabric-api\",\"versionFromProject\":true} (needs projectPath) or with an explicit \"version\"."
+                "description": "Same shape as resolve-artifact target (incl. {\"kind\":\"dependency\",...} to read a Fabric/loader dependency class like vanilla), plus {\"kind\":\"artifact\",\"artifactId\":\"...\"} to reuse a resolved artifact. Object, not string."
             },
             "mapping": {
                 "type": "string",

package/dist/version-diff-service.d.ts

@@ -52,6 +52,29 @@ export type CompareVersionsOutput = {
     };
     warnings: string[];
 };
+/**
+ * `added`/`removed` entries are `group:artifact:<versions>`, where
+ * `<versions>` is the sorted, comma-joined set of distinct versions seen for
+ * that key on the side it was diffed from or to (a single version renders
+ * as before, e.g. "g:a:1"; multiple platform-specific versions render as
+ * "g:a:1,2").
+ */
+export type LibraryDiffResult = {
+    added: string[];
+    removed: string[];
+    addedCount: number;
+    removedCount: number;
+    /** Count only (per design contract) — no list of which libraries bumped. */
+    versionChangedCount: number;
+};
+/**
+ * Pure diff of two versions' `libraries` name lists, keyed by
+ * `group:artifact` so a per-release version bump or a per-platform natives
+ * classifier never reads as churn. Used by migration-overview to surface
+ * library swaps (e.g. LWJGL GLFW replaced by SDL) that a class/registry diff
+ * cannot see.
+ */
+export declare function diffLibraries(fromNames: string[], toNames: string[]): LibraryDiffResult;
 export declare class VersionDiffService {
     private readonly config;
     private readonly versionService;

package/dist/version-diff-service.js

@@ -88,6 +88,107 @@ function diffSets(from, to) {
     removed.sort();
     return { added, removed, unchanged };
 }
+// Matches a Maven-style library coordinate "group:artifact:version" with an
+// optional trailing classifier ("...:natives-linux"). Group/artifact/version
+// segments must be non-empty and colon-free; anything else is not a library
+// name this diff can key on, so it is silently ignored rather than crashing
+// or reading as a spurious added/removed entry. A trailing "@extension"
+// (e.g. "...@jar") is stripped by the caller before this regex runs, so it
+// never leaks into the captured version.
+const LIBRARY_NAME_RE = /^([^:\s]+):([^:\s]+):([^:\s]+)(?::[^:\s]*)?$/;
+function parseLibraryName(name) {
+    // Strip a trailing "@extension" (e.g. "g:a:1@jar", "g:a:1:natives-linux@jar")
+    // before parsing, so it never gets captured as part of the version.
+    const withoutExtension = name.trim().replace(/@[^@]*$/, "");
+    const match = LIBRARY_NAME_RE.exec(withoutExtension);
+    if (!match) {
+        return undefined;
+    }
+    const [, group, artifact, version] = match;
+    return { key: `${group}:${artifact}`, version };
+}
+/**
+ * Collapses a version's raw library name list to the set of distinct
+ * versions seen per `group:artifact` key, dropping the per-platform natives
+ * classifier and any entry whose name does not parse as a library
+ * coordinate. Real Mojang manifests can list the same `group:artifact` with
+ * different versions under different platform rules, so every version seen
+ * is kept (not just the first) — collapsing to one would make the diff
+ * depend on input order.
+ */
+function collapseLibraryNames(names) {
+    const map = new Map();
+    for (const name of names) {
+        if (typeof name !== "string") {
+            continue;
+        }
+        const parsed = parseLibraryName(name);
+        if (!parsed) {
+            continue;
+        }
+        let versions = map.get(parsed.key);
+        if (!versions) {
+            versions = new Set();
+            map.set(parsed.key, versions);
+        }
+        versions.add(parsed.version);
+    }
+    return map;
+}
+/** Renders a key's version set as the sorted, comma-joined suffix used in `added`/`removed`. */
+function renderVersions(versions) {
+    return Array.from(versions).sort().join(",");
+}
+function versionSetsEqual(a, b) {
+    if (a.size !== b.size) {
+        return false;
+    }
+    for (const version of a) {
+        if (!b.has(version)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Pure diff of two versions' `libraries` name lists, keyed by
+ * `group:artifact` so a per-release version bump or a per-platform natives
+ * classifier never reads as churn. Used by migration-overview to surface
+ * library swaps (e.g. LWJGL GLFW replaced by SDL) that a class/registry diff
+ * cannot see.
+ */
+export function diffLibraries(fromNames, toNames) {
+    const fromMap = collapseLibraryNames(fromNames ?? []);
+    const toMap = collapseLibraryNames(toNames ?? []);
+    const added = [];
+    const removed = [];
+    let versionChangedCount = 0;
+    for (const [key, versions] of toMap) {
+        if (!fromMap.has(key)) {
+            added.push(`${key}:${renderVersions(versions)}`);
+        }
+    }
+    for (const [key, versions] of fromMap) {
+        if (!toMap.has(key)) {
+            removed.push(`${key}:${renderVersions(versions)}`);
+        }
+    }
+    for (const [key, fromVersions] of fromMap) {
+        const toVersions = toMap.get(key);
+        if (toVersions !== undefined && !versionSetsEqual(fromVersions, toVersions)) {
+            versionChangedCount += 1;
+        }
+    }
+    added.sort();
+    removed.sort();
+    return {
+        added,
+        removed,
+        addedCount: added.length,
+        removedCount: removed.length,
+        versionChangedCount
+    };
+}
 function diffRegistries(fromRegistries, toRegistries) {
     const fromKeys = new Set(Object.keys(fromRegistries));
     const toKeys = new Set(Object.keys(toRegistries));

package/dist/version-service.d.ts

@@ -54,6 +54,14 @@ export declare class VersionService {
     listVersionIds(input?: ListVersionIdsInput): Promise<string[]>;
     resolveVersionJar(version: string): Promise<ResolvedVersionJar>;
     resolveVersionMappings(version: string): Promise<ResolvedVersionMappings>;
+    /**
+     * Raw `libraries[].name` coordinates (e.g. "org.lwjgl:lwjgl-glfw:3.4.1")
+     * for one version's per-version JSON, in manifest order. Entries missing a
+     * non-empty string `name` are dropped here at the JSON boundary; further
+     * validation (does the name actually parse as a library coordinate) is the
+     * caller's job — see diffLibraries in version-diff-service.ts.
+     */
+    getVersionLibraries(version: string): Promise<string[]>;
     resolveServerJar(version: string): Promise<ResolvedServerJar>;
     private fetchManifest;
     private resolveVersionJarInternal;
@@ -69,5 +77,11 @@ export declare class VersionService {
  * MC 26.1+ uses new YY.N version format and ships unobfuscated source.
  * Legacy 1.x.y versions remain obfuscated.
  * Snapshots: "26w01a" (year >= 26) → unobfuscated, "24w01a" → obfuscated.
+ *
+ * Pre-release / rc / snapshot suffixes: Mojang's real version-manifest ids
+ * use a hyphenated "-pre-N" / "-rc-N" / "-snapshot-N" form (e.g.
+ * "26.2-pre-6", "26.2-rc-2", "26.3-snapshot-6"). The older no-hyphen
+ * "-preN"/"-rcN" form is also accepted for backwards compatibility, but an
+ * arbitrary or numberless suffix (e.g. "26.1-foo", "26.1-snapshot") is not.
  */
 export declare function isUnobfuscatedVersion(version: string): boolean;

package/dist/version-service.js

@@ -136,6 +136,39 @@ export class VersionService {
             mappingsUrl: clientMappingsUrl
         };
     }
+    /**
+     * Raw `libraries[].name` coordinates (e.g. "org.lwjgl:lwjgl-glfw:3.4.1")
+     * for one version's per-version JSON, in manifest order. Entries missing a
+     * non-empty string `name` are dropped here at the JSON boundary; further
+     * validation (does the name actually parse as a library coordinate) is the
+     * caller's job — see diffLibraries in version-diff-service.ts.
+     */
+    async getVersionLibraries(version) {
+        const normalizedVersion = version.trim();
+        if (!normalizedVersion) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "version must be non-empty."
+            });
+        }
+        const manifest = await this.fetchManifest();
+        const versionEntry = (manifest.versions ?? []).find((entry) => entry.id === normalizedVersion);
+        if (!versionEntry) {
+            throw createError({
+                code: ERROR_CODES.VERSION_NOT_FOUND,
+                message: `Minecraft version "${normalizedVersion}" was not found in version manifest.`,
+                details: {
+                    version: normalizedVersion,
+                    nextAction: "Use list-versions to see available Minecraft versions.",
+                    ...buildSuggestedCall({ tool: "list-versions", params: {} })
+                }
+            });
+        }
+        const details = await this.fetchVersionDetails(versionEntry.url, normalizedVersion);
+        return (details.libraries ?? [])
+            .map((lib) => lib?.name)
+            .filter((name) => typeof name === "string" && name.length > 0);
+    }
     async resolveServerJar(version) {
         const normalizedVersion = version.trim();
         if (!normalizedVersion) {
@@ -357,6 +390,13 @@ export class VersionService {
         try {
             const response = await this.fetchFn(url, { signal: timeout.signal });
             if (!response.ok) {
+                // Nothing reads an error body here, and an unread one pins its socket
+                // until GC reaches it. Released best-effort, exactly as `releaseBody`
+                // in repo-downloader.ts: a body that refuses to be cancelled is not a
+                // reason to lose the status the caller actually needs.
+                void response.body?.cancel().catch(() => {
+                    // best-effort release
+                });
                 throw createError({
                     code: ERROR_CODES.REPO_FETCH_FAILED,
                     message: `Request failed for "${url}" with status ${response.status}.`,
@@ -473,6 +513,12 @@ export class VersionService {
  * MC 26.1+ uses new YY.N version format and ships unobfuscated source.
  * Legacy 1.x.y versions remain obfuscated.
  * Snapshots: "26w01a" (year >= 26) → unobfuscated, "24w01a" → obfuscated.
+ *
+ * Pre-release / rc / snapshot suffixes: Mojang's real version-manifest ids
+ * use a hyphenated "-pre-N" / "-rc-N" / "-snapshot-N" form (e.g.
+ * "26.2-pre-6", "26.2-rc-2", "26.3-snapshot-6"). The older no-hyphen
+ * "-preN"/"-rcN" form is also accepted for backwards compatibility, but an
+ * arbitrary or numberless suffix (e.g. "26.1-foo", "26.1-snapshot") is not.
  */
 export function isUnobfuscatedVersion(version) {
     if (!version)
@@ -482,9 +528,12 @@ export function isUnobfuscatedVersion(version) {
     if (snapshotMatch) {
         return Number(snapshotMatch[1]) >= 26;
     }
-    // New format: YY.N or YY.N.P, optionally with -preN/-rcN suffix.
-    // Examples: "26.1", "27.3.1", "26.1-pre1", "26.1-rc1"
-    const newFormatMatch = version.match(/^(\d{2,})\.\d+(?:\.\d+)?(?:-(?:pre|rc)\d+)?$/);
+    // New format: YY.N or YY.N.P, optionally with a pre-release/rc/snapshot
+    // suffix in either the legacy no-hyphen form (-preN, -rcN) or Mojang's
+    // real hyphenated form (-pre-N, -rc-N, -snapshot-N).
+    // Examples: "26.1", "27.3.1", "26.1-pre1", "26.1-rc1", "26.2-pre-6",
+    // "26.2-rc-2", "26.3-snapshot-6"
+    const newFormatMatch = version.match(/^(\d{2,})\.\d+(?:\.\d+)?(?:-(?:pre|rc)\d+|-(?:pre|rc|snapshot)-\d+)?$/);
     if (newFormatMatch) {
         return Number(newFormatMatch[1]) >= 26;
     }

package/dist/workspace-context-cache.d.ts

@@ -5,6 +5,22 @@ export type WorkspaceContextEvidence = {
     field: string;
     value?: string;
 };
+/**
+ * A stat-based snapshot of one file the detection that produced a
+ * `WorkspaceContext` actually read, taken at write time. `read()` re-stats
+ * every entry and treats any difference - a changed mtime/size, a file that
+ * appeared, or one that disappeared - as a cache miss, so an edit to a
+ * project's build files invalidates the cached context immediately instead
+ * of waiting out the TTL.
+ */
+export type WorkspaceContextFingerprintEntry = {
+    path: string;
+    mtimeMs: number;
+    size: number;
+} | {
+    path: string;
+    absent: true;
+};
 export type WorkspaceContext = {
     projectPath: string;
     minecraftVersion?: string;
@@ -14,6 +30,7 @@ export type WorkspaceContext = {
     evidence: WorkspaceContextEvidence[];
     dependencyVersions: Map<string, string>;
     partial?: boolean;
+    fingerprint?: WorkspaceContextFingerprintEntry[];
 };
 export interface WorkspaceContextCache {
     read(projectPath: string): WorkspaceContext | undefined;
@@ -27,6 +44,14 @@ export type WorkspaceContextCacheOptions = {
     ttlMs?: number;
     clock?: () => number;
 };
+/**
+ * Stat-snapshot the given file paths (deduplicated, order-independent) for a
+ * `WorkspaceContext.fingerprint`. Exported so the workspace-context populator
+ * (the only place that knows which files a detection actually read) can build
+ * the same shape `read()` compares against, without duplicating the stat
+ * logic or its absent-file handling.
+ */
+export declare function computeWorkspaceContextFingerprint(paths: readonly string[]): WorkspaceContextFingerprintEntry[];
 export declare function createWorkspaceContextCache(opts?: WorkspaceContextCacheOptions): WorkspaceContextCache;
 export declare function getProcessWorkspaceContextCache(): WorkspaceContextCache;
 export declare function resetProcessWorkspaceContextCacheForTesting(): void;

package/dist/workspace-context-cache.js

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
 import { LruList } from "./lru-list.js";
 const DEFAULT_MAX_ENTRIES = 16;
@@ -5,6 +6,55 @@ const DEFAULT_TTL_MS = 5 * 60_000;
 function normalizeKey(projectPath) {
     return resolvePath(projectPath);
 }
+function currentFingerprintEntry(path) {
+    try {
+        const stats = statSync(path);
+        return { path, mtimeMs: stats.mtimeMs, size: stats.size };
+    }
+    catch {
+        // Missing, unreadable, or a broken symlink - all the same "not there"
+        // state as far as invalidation cares about.
+        return { path, absent: true };
+    }
+}
+/**
+ * Stat-snapshot the given file paths (deduplicated, order-independent) for a
+ * `WorkspaceContext.fingerprint`. Exported so the workspace-context populator
+ * (the only place that knows which files a detection actually read) can build
+ * the same shape `read()` compares against, without duplicating the stat
+ * logic or its absent-file handling.
+ */
+export function computeWorkspaceContextFingerprint(paths) {
+    const unique = Array.from(new Set(paths.map((path) => resolvePath(path))));
+    return unique.map((path) => currentFingerprintEntry(path));
+}
+/**
+ * Whether any file recorded in `ctx.fingerprint` no longer matches its
+ * recorded size/mtime (or its recorded/current absence disagrees). A context
+ * with no fingerprint (nothing was recorded, e.g. a dependency-only partial
+ * entry) never invalidates on this check - only the TTL applies to it.
+ */
+function fingerprintStale(ctx) {
+    if (!ctx.fingerprint || ctx.fingerprint.length === 0) {
+        return false;
+    }
+    for (const recorded of ctx.fingerprint) {
+        const current = currentFingerprintEntry(recorded.path);
+        const recordedAbsent = "absent" in recorded && recorded.absent === true;
+        const currentAbsent = "absent" in current && current.absent === true;
+        if (recordedAbsent !== currentAbsent) {
+            return true;
+        }
+        if (!recordedAbsent && !currentAbsent) {
+            const recordedStat = recorded;
+            const currentStat = current;
+            if (recordedStat.mtimeMs !== currentStat.mtimeMs || recordedStat.size !== currentStat.size) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 export function createWorkspaceContextCache(opts = {}) {
     const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
     const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
@@ -29,7 +79,7 @@ export function createWorkspaceContextCache(opts = {}) {
             if (!value) {
                 return undefined;
             }
-            if (isExpired(value)) {
+            if (isExpired(value) || fingerprintStale(value)) {
                 lru.remove(key);
                 return undefined;
             }
@@ -46,7 +96,7 @@ export function createWorkspaceContextCache(opts = {}) {
         },
         list() {
             const all = lru.toArray().map((entry) => entry.value);
-            return all.filter((value) => !isExpired(value));
+            return all.filter((value) => !isExpired(value) && !fingerprintStale(value));
         },
         clear() {
             lru.clear();

package/dist/workspace-mapping-service.d.ts

@@ -50,6 +50,14 @@ export type DependencyVersionOptions = {
 export { isSafeMavenVersionToken };
 export declare class WorkspaceMappingService {
     detectCompileMapping(input: WorkspaceCompileMappingInput): Promise<WorkspaceCompileMappingOutput>;
+    /**
+     * Whether `projectPath` holds at least one build.gradle(.kts) that
+     * `detectCompileMapping` reads: the same files, found the same way, and readable.
+     * `detectCompileMapping` answers "no evidence" both when a build declares no
+     * mappings and when there was no build to read (a missing, mistyped or empty
+     * directory); this tells the two apart without changing that output.
+     */
+    hasReadableBuildScript(projectPath: string): Promise<boolean>;
     detectProjectMinecraftVersion(projectPath: string): Promise<string | undefined>;
     detectDependencyVersion(projectPath: string, group: string, name: string, opts?: DependencyVersionOptions): Promise<DependencyVersionResolution>;
     detectProjectLoader(projectPath: string): Promise<WorkspaceProjectLoaderOutput>;