@adhisang/minecraft-modding-mcp 1.0.0

package/dist/java-process.d.ts

@@ -0,0 +1,16 @@
+export interface JavaProcessOptions {
+    jarPath: string;
+    args: string[];
+    cwd?: string;
+    timeoutMs?: number;
+    maxMemoryMb?: number;
+    minMemoryMb?: number;
+    normalizePathArgs?: boolean;
+}
+export interface JavaProcessResult {
+    exitCode: number;
+    stdoutTail: string;
+    stderrTail: string;
+}
+export declare function assertJavaAvailable(): Promise<void>;
+export declare function runJavaProcess(options: JavaProcessOptions): Promise<JavaProcessResult>;

package/dist/java-process.js

@@ -0,0 +1,120 @@
+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) {
+    if (text.length <= MAX_STDIO_SNAPSHOT) {
+        return text;
+    }
+    return text.slice(-MAX_STDIO_SNAPSHOT);
+}
+function isAbsolutePath(value) {
+    return value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value);
+}
+function isOptionArg(value) {
+    return value.startsWith("-");
+}
+function normalizeArgs(args) {
+    return args.map((arg) => {
+        if (isOptionArg(arg)) {
+            return arg;
+        }
+        if (isAbsolutePath(arg)) {
+            return normalizePathForHost(arg);
+        }
+        return arg;
+    });
+}
+export async function assertJavaAvailable() {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("java", ["-version"], { stdio: "ignore" });
+        const timer = setTimeout(() => {
+            proc.kill();
+            reject(createError({
+                code: ERROR_CODES.JAVA_UNAVAILABLE,
+                message: "java was not available within timeout."
+            }));
+        }, JAVA_CHECK_TIMEOUT_MS);
+        proc.once("error", () => {
+            clearTimeout(timer);
+            reject(createError({
+                code: ERROR_CODES.JAVA_UNAVAILABLE,
+                message: "java command is not available."
+            }));
+        });
+        proc.once("exit", (code) => {
+            clearTimeout(timer);
+            if (code !== 0 && code !== null) {
+                reject(createError({
+                    code: ERROR_CODES.JAVA_UNAVAILABLE,
+                    message: "java -version failed."
+                }));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+export function runJavaProcess(options) {
+    const { jarPath, args, cwd, timeoutMs = 120_000, maxMemoryMb, minMemoryMb, normalizePathArgs = false } = options;
+    const jvmArgs = [];
+    if (maxMemoryMb) {
+        jvmArgs.push(`-Xmx${maxMemoryMb}m`);
+    }
+    if (minMemoryMb) {
+        jvmArgs.push(`-Xms${minMemoryMb}m`);
+    }
+    const normalizedJar = normalizePathArgs ? normalizePathForHost(jarPath) : jarPath;
+    const processedArgs = normalizePathArgs ? normalizeArgs(args) : args;
+    const spawnArgs = [...jvmArgs, "-jar", normalizedJar, ...processedArgs];
+    return new Promise((resolve, reject) => {
+        const proc = spawn("java", spawnArgs, {
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(cwd ? { cwd } : {})
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => {
+            proc.kill();
+            reject(createError({
+                code: ERROR_CODES.JAVA_PROCESS_FAILED,
+                message: "Java process timed out.",
+                details: {
+                    jarPath: normalizedJar,
+                    reason: "timeout",
+                    timeoutMs,
+                    stderrTail: limitStdio(stderr)
+                }
+            }));
+        }, timeoutMs);
+        proc.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+            stdout = limitStdio(stdout);
+        });
+        proc.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+            stderr = limitStdio(stderr);
+        });
+        proc.once("error", (error) => {
+            clearTimeout(timer);
+            reject(createError({
+                code: ERROR_CODES.JAVA_PROCESS_FAILED,
+                message: "Java process failed to start.",
+                details: {
+                    jarPath: normalizedJar,
+                    error: error instanceof Error ? error.message : String(error)
+                }
+            }));
+        });
+        proc.once("exit", (code) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: code ?? -1,
+                stdoutTail: limitStdio(stdout),
+                stderrTail: limitStdio(stderr)
+            });
+        });
+    });
+}
+//# sourceMappingURL=java-process.js.map

package/dist/logger.d.ts

@@ -0,0 +1,3 @@
+export type LogLevel = "info" | "warn" | "error";
+export type LogDetails = Record<string, unknown>;
+export declare function log(level: LogLevel, event: string, details?: LogDetails): void;

package/dist/logger.js

@@ -0,0 +1,21 @@
+function serializeLog(level, event, details) {
+    return JSON.stringify({
+        timestamp: new Date().toISOString(),
+        level,
+        event,
+        ...(details ?? {})
+    });
+}
+export function log(level, event, details) {
+    const line = serializeLog(level, event, details);
+    if (level === "error") {
+        console.error(line);
+        return;
+    }
+    if (level === "warn") {
+        console.warn(line);
+        return;
+    }
+    console.info(line);
+}
+//# sourceMappingURL=logger.js.map

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

@@ -0,0 +1,18 @@
+import type { ResolvedSourceArtifact, SourceMapping, SourceTargetInput } from "./types.js";
+export interface MappingPipelineInput {
+    requestedMapping: SourceMapping;
+    target: SourceTargetInput;
+    resolved: ResolvedSourceArtifact;
+}
+export interface MappingPipelineResult {
+    mappingApplied: SourceMapping;
+    qualityFlags: string[];
+    transformChain: string[];
+}
+/**
+ * Mapping pipeline for v0.3.
+ * Current implementation enforces explicit guarantees:
+ * - official: always pass-through
+ * - mojang: requires source-backed artifact; decompile-only artifacts are rejected
+ */
+export declare function applyMappingPipeline(input: MappingPipelineInput): MappingPipelineResult;

package/dist/mapping-pipeline-service.js

@@ -0,0 +1,60 @@
+import { createError, ERROR_CODES } from "./errors.js";
+/**
+ * Mapping pipeline for v0.3.
+ * Current implementation enforces explicit guarantees:
+ * - official: always pass-through
+ * - mojang: requires source-backed artifact; decompile-only artifacts are rejected
+ */
+export function applyMappingPipeline(input) {
+    const transformChain = [];
+    const qualityFlags = [];
+    if (input.requestedMapping === "official") {
+        transformChain.push("mapping:official-pass-through");
+        if (input.resolved.isDecompiled) {
+            qualityFlags.push("decompiled");
+        }
+        else {
+            qualityFlags.push("source-backed");
+        }
+        return {
+            mappingApplied: "official",
+            qualityFlags,
+            transformChain
+        };
+    }
+    if (input.requestedMapping !== "mojang" &&
+        input.requestedMapping !== "intermediary" &&
+        input.requestedMapping !== "yarn") {
+        throw createError({
+            code: ERROR_CODES.MAPPING_UNAVAILABLE,
+            message: `Unsupported mapping "${input.requestedMapping}".`,
+            details: {
+                requestedMapping: input.requestedMapping,
+                target: input.target
+            }
+        });
+    }
+    const hasSource = Boolean(input.resolved.sourceJarPath);
+    if (!hasSource) {
+        throw createError({
+            code: ERROR_CODES.MAPPING_NOT_APPLIED,
+            message: `Requested ${input.requestedMapping} mapping cannot be guaranteed for this artifact because only decompile path is available.`,
+            details: {
+                requestedMapping: input.requestedMapping,
+                target: input.target,
+                origin: input.resolved.origin,
+                binaryJarPath: input.resolved.binaryJarPath,
+                sourceJarPath: input.resolved.sourceJarPath,
+                nextAction: "Provide a source-backed artifact (source jar) or use mapping=official."
+            }
+        });
+    }
+    transformChain.push(`mapping:${input.requestedMapping}-source-backed`);
+    qualityFlags.push("source-backed");
+    return {
+        mappingApplied: input.requestedMapping,
+        qualityFlags,
+        transformChain
+    };
+}
+//# sourceMappingURL=mapping-pipeline-service.js.map

package/dist/mapping-service.d.ts

@@ -0,0 +1,161 @@
+import type { Config, MappingSourcePriority, SourceMapping } from "./types.js";
+import { VersionService } from "./version-service.js";
+type MappingLookupSource = "loom-cache" | "maven" | "mojang-client-mappings";
+type MappingSymbolKind = "class" | "field" | "method";
+type VersionMappingsResolver = Pick<VersionService, "resolveVersionMappings">;
+export type MappingMatchKind = "exact" | "normalized" | "simple-name";
+export type MappingLookupCandidate = {
+    symbol: string;
+    matchKind: MappingMatchKind;
+    confidence: number;
+    kind: MappingSymbolKind;
+    owner?: string;
+    name: string;
+    descriptor?: string;
+};
+export type MappingLookupProvenance = {
+    source: MappingLookupSource;
+    mappingArtifact: string;
+    version: string;
+    priority: MappingSourcePriority;
+};
+export type SymbolQueryKind = MappingSymbolKind;
+export type SymbolQueryInput = {
+    kind: SymbolQueryKind;
+    name: string;
+    owner?: string;
+    descriptor?: string;
+};
+export type SymbolReference = {
+    kind: SymbolQueryKind;
+    name: string;
+    owner?: string;
+    descriptor?: string;
+    symbol: string;
+};
+export type SymbolResolutionStatus = "resolved" | "not_found" | "ambiguous" | "mapping_unavailable";
+export type SymbolResolutionOutput = {
+    querySymbol: SymbolReference;
+    mappingContext: {
+        version: string;
+        sourceMapping: SourceMapping;
+        targetMapping?: SourceMapping;
+        sourcePriorityApplied: MappingSourcePriority;
+    };
+    resolved: boolean;
+    status: SymbolResolutionStatus;
+    resolvedSymbol?: SymbolReference;
+    candidates: Array<SymbolReference & Pick<MappingLookupCandidate, "matchKind" | "confidence">>;
+    warnings: string[];
+    provenance?: MappingLookupProvenance;
+};
+export type FindMappingInput = {
+    version: string;
+    kind: SymbolQueryKind;
+    name: string;
+    owner?: string;
+    descriptor?: string;
+    sourceMapping: SourceMapping;
+    targetMapping: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+};
+export type FindMappingOutput = SymbolResolutionOutput;
+export type EnsureMappingAvailableInput = {
+    version: string;
+    sourceMapping: SourceMapping;
+    targetMapping: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+};
+export type EnsureMappingAvailableOutput = {
+    transformChain: string[];
+    warnings: string[];
+    provenance?: MappingLookupProvenance;
+};
+export type ResolveMethodMappingExactInput = {
+    version: string;
+    kind: SymbolQueryKind;
+    name: string;
+    owner?: string;
+    descriptor?: string;
+    sourceMapping: SourceMapping;
+    targetMapping: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+};
+export type ResolveMethodMappingExactOutput = SymbolResolutionOutput;
+export type ClassApiMatrixKind = "class" | "field" | "method";
+export type ClassApiMatrixInput = {
+    version: string;
+    className: string;
+    classNameMapping: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+    includeKinds?: ClassApiMatrixKind[];
+};
+export type ClassApiMatrixEntry = {
+    symbol: string;
+    owner?: string;
+    name: string;
+    descriptor?: string;
+};
+export type ClassApiMatrixRow = {
+    kind: ClassApiMatrixKind;
+    descriptor?: string;
+    official?: ClassApiMatrixEntry;
+    mojang?: ClassApiMatrixEntry;
+    intermediary?: ClassApiMatrixEntry;
+    yarn?: ClassApiMatrixEntry;
+    completeness: boolean;
+};
+export type ClassApiMatrixOutput = {
+    version: string;
+    className: string;
+    classNameMapping: SourceMapping;
+    classIdentity: Partial<Record<SourceMapping, string>>;
+    rows: ClassApiMatrixRow[];
+    warnings: string[];
+};
+export type SymbolExistenceInput = {
+    version: string;
+    kind: SymbolQueryKind;
+    name: string;
+    owner?: string;
+    descriptor?: string;
+    sourceMapping: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+};
+export type SymbolExistenceOutput = SymbolResolutionOutput;
+export declare class MappingService {
+    private readonly config;
+    private readonly versionService;
+    private readonly fetchFn;
+    private readonly graphCache;
+    private readonly buildLocks;
+    constructor(config: Config, versionService?: VersionMappingsResolver, fetchFn?: typeof fetch);
+    findMapping(input: FindMappingInput): Promise<FindMappingOutput>;
+    ensureMappingAvailable(input: EnsureMappingAvailableInput): Promise<EnsureMappingAvailableOutput>;
+    resolveMethodMappingExact(input: ResolveMethodMappingExactInput): Promise<ResolveMethodMappingExactOutput>;
+    getClassApiMatrix(input: ClassApiMatrixInput): Promise<ClassApiMatrixOutput>;
+    checkSymbolExists(input: SymbolExistenceInput): Promise<SymbolExistenceOutput>;
+    private mapRecordBetweenMappings;
+    private mapCandidatesAlongPath;
+    private provenanceForPath;
+    private loadGraph;
+    private buildGraph;
+    private mergePairs;
+    private loadMojangPairs;
+    private loadTinyPairsFromLoom;
+    private loadTinyPairsFromMaven;
+    private parseTinyFromJar;
+    private fetchYarnCoordinates;
+    private trimGraphCache;
+}
+/**
+ * Resolve and cache a Tiny v2 mapping file for the given Minecraft version.
+ *
+ * @param version - Minecraft version (e.g. "1.20.4")
+ * @param mapping - "intermediary" or "yarn"
+ * @param cacheDir - The application cache directory
+ * @param fetchFn - Optional fetch implementation for testing
+ * @returns Path to the extracted Tiny v2 file
+ */
+export declare function resolveTinyMappingFile(version: string, mapping: "intermediary" | "yarn", cacheDir: string, fetchFn?: typeof fetch): Promise<string>;
+export {};