@adhisang/minecraft-modding-mcp 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+export type SourceOrigin = "local-jar" | "local-m2" | "remote-repo" | "decompiled";
+export type SourceMapping = "official" | "mojang" | "intermediary" | "yarn";
+export type MappingSourcePriority = "loom-first" | "maven-first";
+export type ArtifactTargetKind = "version" | "jar" | "coordinate";
+export interface SourceTargetInput {
+    kind: ArtifactTargetKind;
+    value: string;
+}
+export interface ResolvedSourceArtifact {
+    artifactId: string;
+    artifactSignature: string;
+    origin: SourceOrigin;
+    binaryJarPath?: string;
+    sourceJarPath?: string;
+    adjacentSourceCandidates?: string[];
+    coordinate?: string;
+    version?: string;
+    requestedMapping?: SourceMapping;
+    mappingApplied?: SourceMapping;
+    repoUrl?: string;
+    provenance?: ArtifactProvenance;
+    qualityFlags?: string[];
+    isDecompiled: boolean;
+    resolvedAt: string;
+}
+export interface ArtifactProvenance {
+    target: SourceTargetInput;
+    resolvedAt: string;
+    resolvedFrom: {
+        origin: SourceOrigin;
+        sourceJarPath?: string;
+        binaryJarPath?: string;
+        coordinate?: string;
+        version?: string;
+        repoUrl?: string;
+    };
+    transformChain: string[];
+}
+export interface ErrorEnvelope {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface Config {
+    cacheDir: string;
+    sqlitePath: string;
+    sourceRepos: string[];
+    localM2Path: string;
+    vineflowerJarPath: string | undefined;
+    indexedSearchEnabled: boolean;
+    mappingSourcePriority: MappingSourcePriority;
+    maxContentBytes: number;
+    maxSearchHits: number;
+    maxArtifacts: number;
+    maxCacheBytes: number;
+    fetchTimeoutMs: number;
+    fetchRetries: number;
+    searchScanPageSize: number;
+    indexInsertChunkSize: number;
+    maxMappingGraphCache: number;
+    maxSignatureCache: number;
+    maxVersionDetailCache: number;
+    maxNbtInputBytes: number;
+    maxNbtInflatedBytes: number;
+    maxNbtResponseBytes: number;
+    tinyRemapperJarPath: string | undefined;
+    remapTimeoutMs: number;
+    remapMaxMemoryMb: number;
+}
+export interface ArtifactSignature {
+    sourcePath: string;
+    sourceArtifactId: string;
+    signature: string;
+    signatureParts: {
+        mtimeMs: number;
+        size: number;
+    };
+}
+export interface SourceSearchHit {
+    filePath: string;
+    score: number;
+    matchedIn: "path" | "content" | "both";
+    preview: string;
+}
+export interface ArtifactRow {
+    artifactId: string;
+    origin: SourceOrigin;
+    coordinate: string | undefined;
+    version: string | undefined;
+    binaryJarPath: string | undefined;
+    sourceJarPath: string | undefined;
+    repoUrl: string | undefined;
+    requestedMapping: SourceMapping | undefined;
+    mappingApplied: SourceMapping | undefined;
+    provenance: ArtifactProvenance | undefined;
+    qualityFlags: string[];
+    artifactSignature: string | undefined;
+    isDecompiled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface FileRow {
+    artifactId: string;
+    filePath: string;
+    content: string;
+    contentBytes: number;
+    contentHash: string;
+}
+export interface SymbolRow {
+    artifactId: string;
+    filePath: string;
+    symbolKind: string;
+    symbolName: string;
+    qualifiedName: string | undefined;
+    line: number;
+}
+export interface PagedResult<T> {
+    items: T[];
+    nextCursor: string | undefined;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,41 @@
+import { VersionService } from "./version-service.js";
+import { RegistryService } from "./registry-service.js";
+import type { Config } from "./types.js";
+export type CompareVersionsCategory = "classes" | "registry" | "all";
+export type CompareVersionsInput = {
+    fromVersion: string;
+    toVersion: string;
+    category?: CompareVersionsCategory;
+    packageFilter?: string;
+    maxClassResults?: number;
+};
+export type CompareVersionsOutput = {
+    fromVersion: string;
+    toVersion: string;
+    classes?: {
+        added: string[];
+        removed: string[];
+        addedCount: number;
+        removedCount: number;
+        unchanged: number;
+    };
+    registry?: {
+        added: Record<string, string[]>;
+        removed: Record<string, string[]>;
+        newRegistries: string[];
+        removedRegistries: string[];
+        summary: {
+            registriesChanged: number;
+            totalAdded: number;
+            totalRemoved: number;
+        };
+    };
+    warnings: string[];
+};
+export declare class VersionDiffService {
+    private readonly config;
+    private readonly versionService;
+    private readonly registryService;
+    constructor(config: Config, versionService: VersionService, registryService: RegistryService);
+    compareVersions(input: CompareVersionsInput): Promise<CompareVersionsOutput>;
+}

package/dist/version-diff-service.js

@@ -0,0 +1,222 @@
+import { createError, ERROR_CODES } from "./errors.js";
+import { log } from "./logger.js";
+import { listJarEntries } from "./source-jar-reader.js";
+const DEFAULT_MAX_CLASS_RESULTS = 500;
+const MAX_CLASS_RESULTS_LIMIT = 5000;
+function classInternalToFqn(internalPath) {
+    // Remove .class suffix and convert / to .
+    return internalPath.replace(/\.class$/, "").replaceAll("/", ".");
+}
+function extractClassEntries(entries) {
+    const classes = new Set();
+    for (const entry of entries) {
+        if (entry.endsWith(".class") &&
+            !entry.includes("META-INF/") &&
+            !entry.includes("$")) {
+            classes.add(classInternalToFqn(entry));
+        }
+    }
+    return classes;
+}
+function filterByPackage(classes, prefix) {
+    const normalized = prefix.endsWith(".") ? prefix : `${prefix}.`;
+    return classes.filter((fqn) => fqn.startsWith(normalized));
+}
+function diffSets(from, to) {
+    const added = [];
+    const removed = [];
+    let unchanged = 0;
+    for (const entry of to) {
+        if (!from.has(entry))
+            added.push(entry);
+        else
+            unchanged++;
+    }
+    for (const entry of from) {
+        if (!to.has(entry))
+            removed.push(entry);
+    }
+    added.sort();
+    removed.sort();
+    return { added, removed, unchanged };
+}
+function diffRegistries(fromRegistries, toRegistries) {
+    const fromKeys = new Set(Object.keys(fromRegistries));
+    const toKeys = new Set(Object.keys(toRegistries));
+    const newRegistries = [];
+    const removedRegistries = [];
+    for (const key of toKeys) {
+        if (!fromKeys.has(key))
+            newRegistries.push(key);
+    }
+    for (const key of fromKeys) {
+        if (!toKeys.has(key))
+            removedRegistries.push(key);
+    }
+    newRegistries.sort();
+    removedRegistries.sort();
+    const added = {};
+    const removed = {};
+    let totalAdded = 0;
+    let totalRemoved = 0;
+    let registriesChanged = 0;
+    // Compare entries in registries present in both versions
+    const commonRegistries = [...fromKeys].filter((key) => toKeys.has(key));
+    for (const registryName of commonRegistries) {
+        const fromEntries = new Set(Object.keys(fromRegistries[registryName].entries));
+        const toEntries = new Set(Object.keys(toRegistries[registryName].entries));
+        const addedEntries = [];
+        const removedEntries = [];
+        for (const entry of toEntries) {
+            if (!fromEntries.has(entry))
+                addedEntries.push(entry);
+        }
+        for (const entry of fromEntries) {
+            if (!toEntries.has(entry))
+                removedEntries.push(entry);
+        }
+        if (addedEntries.length > 0 || removedEntries.length > 0) {
+            registriesChanged++;
+            if (addedEntries.length > 0) {
+                addedEntries.sort();
+                added[registryName] = addedEntries;
+                totalAdded += addedEntries.length;
+            }
+            if (removedEntries.length > 0) {
+                removedEntries.sort();
+                removed[registryName] = removedEntries;
+                totalRemoved += removedEntries.length;
+            }
+        }
+    }
+    // Count new registries' entries as added
+    for (const regName of newRegistries) {
+        const entries = Object.keys(toRegistries[regName].entries);
+        if (entries.length > 0) {
+            entries.sort();
+            added[regName] = entries;
+            totalAdded += entries.length;
+            registriesChanged++;
+        }
+    }
+    // Count removed registries' entries as removed
+    for (const regName of removedRegistries) {
+        const entries = Object.keys(fromRegistries[regName].entries);
+        if (entries.length > 0) {
+            entries.sort();
+            removed[regName] = entries;
+            totalRemoved += entries.length;
+            registriesChanged++;
+        }
+    }
+    return {
+        added,
+        removed,
+        newRegistries,
+        removedRegistries,
+        summary: {
+            registriesChanged,
+            totalAdded,
+            totalRemoved
+        }
+    };
+}
+export class VersionDiffService {
+    config;
+    versionService;
+    registryService;
+    constructor(config, versionService, registryService) {
+        this.config = config;
+        this.versionService = versionService;
+        this.registryService = registryService;
+    }
+    async compareVersions(input) {
+        const fromVersion = input.fromVersion.trim();
+        const toVersion = input.toVersion.trim();
+        const category = input.category ?? "all";
+        const maxClassResults = Math.min(input.maxClassResults ?? DEFAULT_MAX_CLASS_RESULTS, MAX_CLASS_RESULTS_LIMIT);
+        if (!fromVersion || !toVersion) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "fromVersion and toVersion must be non-empty."
+            });
+        }
+        const warnings = [];
+        const startedAt = Date.now();
+        log("info", "version-diff.start", { fromVersion, toVersion, category });
+        const includeClasses = category === "classes" || category === "all";
+        const includeRegistry = category === "registry" || category === "all";
+        let classesResult;
+        let registryResult;
+        // Run class and registry comparisons in parallel where possible
+        const tasks = [];
+        if (includeClasses) {
+            tasks.push((async () => {
+                const [fromJar, toJar] = await Promise.all([
+                    this.versionService.resolveVersionJar(fromVersion),
+                    this.versionService.resolveVersionJar(toVersion)
+                ]);
+                const [fromEntries, toEntries] = await Promise.all([
+                    listJarEntries(fromJar.jarPath),
+                    listJarEntries(toJar.jarPath)
+                ]);
+                const fromClasses = extractClassEntries(fromEntries);
+                const toClasses = extractClassEntries(toEntries);
+                let { added, removed, unchanged } = diffSets(fromClasses, toClasses);
+                if (input.packageFilter) {
+                    added = filterByPackage(added, input.packageFilter);
+                    removed = filterByPackage(removed, input.packageFilter);
+                }
+                const truncatedAdded = added.slice(0, maxClassResults);
+                const truncatedRemoved = removed.slice(0, maxClassResults);
+                if (added.length > maxClassResults) {
+                    warnings.push(`Class additions truncated: showing ${maxClassResults} of ${added.length}. Use packageFilter to narrow results.`);
+                }
+                if (removed.length > maxClassResults) {
+                    warnings.push(`Class removals truncated: showing ${maxClassResults} of ${removed.length}. Use packageFilter to narrow results.`);
+                }
+                classesResult = {
+                    added: truncatedAdded,
+                    removed: truncatedRemoved,
+                    addedCount: added.length,
+                    removedCount: removed.length,
+                    unchanged
+                };
+            })());
+        }
+        if (includeRegistry) {
+            tasks.push((async () => {
+                try {
+                    const [fromReg, toReg] = await Promise.all([
+                        this.registryService.getRegistryData({ version: fromVersion }),
+                        this.registryService.getRegistryData({ version: toVersion })
+                    ]);
+                    const fromData = fromReg.data;
+                    const toData = toReg.data;
+                    registryResult = diffRegistries(fromData, toData);
+                }
+                catch (error) {
+                    if (category === "registry") {
+                        throw error;
+                    }
+                    const msg = error instanceof Error ? error.message : String(error);
+                    warnings.push(`Registry comparison failed: ${msg}`);
+                }
+            })());
+        }
+        await Promise.all(tasks);
+        log("info", "version-diff.done", {
+            fromVersion,
+            toVersion,
+            durationMs: Date.now() - startedAt
+        });
+        return {
+            fromVersion,
+            toVersion,
+            classes: classesResult,
+            registry: registryResult,
+            warnings
+        };
+    }
+}
+//# sourceMappingURL=version-diff-service.js.map

package/dist/version-service.d.ts

@@ -0,0 +1,70 @@
+import type { Config } from "./types.js";
+export type ListVersionsInput = {
+    includeSnapshots?: boolean;
+    limit?: number;
+};
+export type VersionEntry = {
+    id: string;
+    unobfuscated: boolean;
+};
+export type ListVersionsOutput = {
+    latest: {
+        release?: string;
+        snapshot?: string;
+    };
+    releases: VersionEntry[];
+    snapshots?: VersionEntry[];
+    cached: string[];
+    totalAvailable: number;
+};
+export type ResolvedVersionJar = {
+    version: string;
+    jarPath: string;
+    source: "downloaded";
+    clientJarUrl: string;
+};
+export type ResolvedServerJar = {
+    version: string;
+    jarPath: string;
+    source: "downloaded";
+    serverJarUrl: string;
+};
+export type ResolvedVersionMappings = {
+    version: string;
+    versionManifestUrl: string;
+    versionDetailUrl: string;
+    clientMappingsUrl?: string;
+    serverMappingsUrl?: string;
+    mappingsUrl?: string;
+};
+export type ListVersionIdsInput = {
+    includeSnapshots?: boolean;
+};
+export declare class VersionService {
+    private readonly config;
+    private readonly fetchFn;
+    private readonly manifestUrl;
+    private manifestCache;
+    private readonly versionDetailCache;
+    private readonly resolveLocks;
+    constructor(config: Config, fetchFn?: typeof fetch);
+    listVersions(input?: ListVersionsInput): Promise<ListVersionsOutput>;
+    listVersionIds(input?: ListVersionIdsInput): Promise<string[]>;
+    resolveVersionJar(version: string): Promise<ResolvedVersionJar>;
+    resolveVersionMappings(version: string): Promise<ResolvedVersionMappings>;
+    resolveServerJar(version: string): Promise<ResolvedServerJar>;
+    private fetchManifest;
+    private resolveVersionJarInternal;
+    private fetchVersionDetails;
+    private fetchJson;
+    private cacheIndexPath;
+    private loadCacheIndex;
+    private recordCacheEntry;
+    private trimVersionDetailCache;
+}
+/**
+ * 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.
+ */
+export declare function isUnobfuscatedVersion(version: string): boolean;