@adhisang/minecraft-modding-mcp 3.2.0 → 4.1.0

package/dist/entry-tools/verify-mixin-target-service.js

@@ -0,0 +1,323 @@
+import { z } from "zod";
+import { buildSuggestedCall } from "../build-suggested-call.js";
+import { createError, ERROR_CODES, isAppError } from "../errors.js";
+import { suggestSimilar } from "../mixin-validator.js";
+export const VERIFY_MIXIN_TARGET_OFF = process.env.VERIFY_MIXIN_TARGET_OFF === "1";
+const ACCESSOR_NAME_RE = /^(get|set|is)([A-Z]\w*)$/;
+const INVOKER_NAME_RE = /^(invoke|call)([A-Z]\w*)$/;
+function decodeAccessFlags(flags) {
+    const labels = [];
+    if (flags == null) {
+        return labels;
+    }
+    if ((flags & 0x0001) !== 0)
+        labels.push("public");
+    if ((flags & 0x0002) !== 0)
+        labels.push("private");
+    if ((flags & 0x0004) !== 0)
+        labels.push("protected");
+    if ((flags & 0x0008) !== 0)
+        labels.push("static");
+    if ((flags & 0x0010) !== 0)
+        labels.push("final");
+    if ((flags & 0x0020) !== 0)
+        labels.push("synchronized");
+    if ((flags & 0x0040) !== 0)
+        labels.push("volatile");
+    if ((flags & 0x0080) !== 0)
+        labels.push("transient");
+    if ((flags & 0x0100) !== 0)
+        labels.push("native");
+    if ((flags & 0x0400) !== 0)
+        labels.push("abstract");
+    if ((flags & 0x0800) !== 0)
+        labels.push("strictfp");
+    if (labels.length === 0) {
+        labels.push("package-private");
+    }
+    return labels;
+}
+function visibilityFromFlags(flags) {
+    if (flags == null)
+        return "package-private";
+    if ((flags & 0x0001) !== 0)
+        return "public";
+    if ((flags & 0x0004) !== 0)
+        return "protected";
+    if ((flags & 0x0002) !== 0)
+        return "private";
+    return "package-private";
+}
+function buildExampleSnippet(annotation, member, match, mixinMemberName) {
+    const accessFlags = match?.accessFlags ?? [];
+    const isFinal = accessFlags.includes("final");
+    const targetName = member.name;
+    if (annotation === "@Inject-only") {
+        return `// "${targetName}" is already visible to the mixin (target access: ${accessFlags.filter((f) => f === "public" || f === "protected" || f === "private" || f === "package-private")[0] ?? "unknown"}); use @Inject directly without @Shadow.`;
+    }
+    if (annotation === "@Shadow") {
+        if (member.kind === "field") {
+            const finalTag = isFinal ? "@Shadow @Final\n" : "@Shadow\n";
+            return `${finalTag}private <type> ${targetName};`;
+        }
+        return `@Shadow\nprivate <returnType> ${targetName}(<params>);`;
+    }
+    if (annotation === "@Accessor") {
+        const accessorName = mixinMemberName ?? `get${targetName.charAt(0).toUpperCase()}${targetName.slice(1)}`;
+        const isSetter = mixinMemberName !== undefined && /^set[A-Z]/.test(mixinMemberName);
+        if (isSetter) {
+            return `@Accessor("${targetName}")\nvoid ${accessorName}(<type> value);`;
+        }
+        return `@Accessor("${targetName}")\n<returnType> ${accessorName}();`;
+    }
+    const invokerName = mixinMemberName ?? `invoke${targetName.charAt(0).toUpperCase()}${targetName.slice(1)}`;
+    return `@Invoker("${targetName}")\n<returnType> ${invokerName}(<params>);`;
+}
+function inferAnnotation(member, match, mixinMemberName) {
+    const visibility = match ? deriveVisibility(match.accessFlags) : "private";
+    if (visibility === "public" || visibility === "protected") {
+        return {
+            suggestedAnnotation: "@Inject-only",
+            reasoning: `Target "${member.name}" is ${visibility}; it is already visible to the mixin without @Shadow. Use @Inject directly.`,
+            exampleSnippet: buildExampleSnippet("@Inject-only", member, match, mixinMemberName)
+        };
+    }
+    if (mixinMemberName) {
+        if (member.kind === "field" && ACCESSOR_NAME_RE.test(mixinMemberName)) {
+            return {
+                suggestedAnnotation: "@Accessor",
+                reasoning: `mixin member "${mixinMemberName}" follows the get/set/is convention — inferred field "${member.name}" via prefix removal.`,
+                exampleSnippet: buildExampleSnippet("@Accessor", member, match, mixinMemberName)
+            };
+        }
+        if (member.kind === "method" && INVOKER_NAME_RE.test(mixinMemberName)) {
+            return {
+                suggestedAnnotation: "@Invoker",
+                reasoning: `mixin member "${mixinMemberName}" follows the invoke/call convention — inferred method "${member.name}" via prefix removal.`,
+                exampleSnippet: buildExampleSnippet("@Invoker", member, match, mixinMemberName)
+            };
+        }
+        return {
+            suggestedAnnotation: "@Shadow",
+            reasoning: `Target "${member.name}" is private. mixin member "${mixinMemberName}" does not match accessor/invoker prefix conventions; @Shadow is appropriate.`,
+            exampleSnippet: buildExampleSnippet("@Shadow", member, match, mixinMemberName)
+        };
+    }
+    if (member.kind === "field") {
+        return {
+            suggestedAnnotation: "@Shadow",
+            reasoning: `Target "${member.name}" is private; use @Shadow to access it from the mixin.`,
+            exampleSnippet: buildExampleSnippet("@Shadow", member, match, mixinMemberName)
+        };
+    }
+    return {
+        suggestedAnnotation: null,
+        reasoning: `Target method "${member.name}" is private and no mixinMemberName was supplied; cannot decide between @Shadow and @Invoker. Choose @Shadow when the mixin overrides the method, @Invoker when it only needs to call it.`,
+        exampleSnippet: "// Provide mixinMemberName to receive a concrete @Shadow or @Invoker template.",
+        candidates: [
+            {
+                annotation: "@Shadow",
+                reasoning: "Use @Shadow to override or read the private method body from the mixin.",
+                exampleSnippet: buildExampleSnippet("@Shadow", member, match, mixinMemberName)
+            },
+            {
+                annotation: "@Invoker",
+                reasoning: "Use @Invoker when the mixin only needs to invoke the private method without redeclaring the body.",
+                exampleSnippet: buildExampleSnippet("@Invoker", member, match, mixinMemberName)
+            }
+        ]
+    };
+}
+function deriveVisibility(accessFlags) {
+    if (accessFlags.includes("public"))
+        return "public";
+    if (accessFlags.includes("protected"))
+        return "protected";
+    if (accessFlags.includes("private"))
+        return "private";
+    return "package-private";
+}
+function buildMatch(member) {
+    return {
+        name: member.name,
+        descriptor: member.jvmDescriptor,
+        accessFlags: decodeAccessFlags(member.accessFlags),
+        javaSignature: member.javaSignature,
+        ...(member.sourceLine ? { sourceLine: member.sourceLine } : {})
+    };
+}
+export class VerifyMixinTargetService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        if (VERIFY_MIXIN_TARGET_OFF) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "verify-mixin-target is disabled by VERIFY_MIXIN_TARGET_OFF=1.",
+                details: { fieldErrors: [{ path: "tool", message: "verify-mixin-target is disabled." }] }
+            });
+        }
+        if (!input.target) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "verify-mixin-target requires a target.",
+                details: { fieldErrors: [{ path: "target", message: "target is required" }] }
+            });
+        }
+        const owner = input.owner.trim();
+        if (!owner) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "owner must be non-empty."
+            });
+        }
+        const memberName = input.member.name.trim();
+        if (!memberName) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "member.name must be non-empty."
+            });
+        }
+        const resolved = await this.deps.resolveArtifact({
+            target: input.target,
+            mapping: input.mapping,
+            sourcePriority: input.sourcePriority,
+            projectPath: input.projectPath,
+            scope: input.scope,
+            preferProjectVersion: input.preferProjectVersion,
+            strictVersion: input.strictVersion
+        });
+        const warnings = [...(resolved.warnings ?? [])];
+        if (input.mapping && input.mapping !== resolved.mappingApplied) {
+            throw createError({
+                code: ERROR_CODES.NAMESPACE_MISMATCH,
+                message: `verify-mixin-target requires owner and member.name to be in the artifact's namespace `
+                    + `("${resolved.mappingApplied}"), but the request supplied mapping="${input.mapping}". `
+                    + `Automatic name/descriptor translation is not yet supported; supply owner+member in the artifact namespace, `
+                    + `or omit the mapping argument so the resolver picks the namespace automatically.`,
+                details: {
+                    owner,
+                    requestedMapping: input.mapping,
+                    mappingApplied: resolved.mappingApplied,
+                    artifactId: resolved.artifactId,
+                    nextAction: `Retry with mapping="${resolved.mappingApplied}" and owner/member translated to that namespace, `
+                        + `or use find-mapping to translate before calling verify-mixin-target.`
+                }
+            });
+        }
+        if (!resolved.binaryJarPath) {
+            throw createError({
+                code: ERROR_CODES.CONTEXT_UNRESOLVED,
+                message: `verify-mixin-target requires a binary jar but artifact "${resolved.artifactId}" has none.`,
+                details: { artifactId: resolved.artifactId, owner }
+            });
+        }
+        let signature;
+        try {
+            signature = await this.deps.getSignature({
+                fqn: owner,
+                jarPath: resolved.binaryJarPath,
+                access: "all",
+                includeSynthetic: false,
+                includeInherited: false
+            });
+        }
+        catch (error) {
+            if (isAppError(error) && error.code === ERROR_CODES.CLASS_NOT_FOUND) {
+                throw createError({
+                    code: ERROR_CODES.CLASS_NOT_FOUND,
+                    message: error.message,
+                    details: {
+                        ...(error.details ?? {}),
+                        owner,
+                        artifactId: resolved.artifactId,
+                        nextAction: `Use find-class to locate the canonical FQCN for "${owner}" before retrying verify-mixin-target.`,
+                        ...buildSuggestedCall({
+                            tool: "find-class",
+                            params: {
+                                artifactId: resolved.artifactId,
+                                className: owner.includes(".") ? owner.slice(owner.lastIndexOf(".") + 1) : owner
+                            }
+                        })
+                    }
+                });
+            }
+            throw error;
+        }
+        warnings.push(...(signature.warnings ?? []));
+        const memberPool = input.member.kind === "method"
+            ? [...signature.constructors, ...signature.methods]
+            : [...signature.fields];
+        const allMemberNames = memberPool.map((m) => m.name);
+        const exactNameHits = memberPool.filter((m) => m.name === memberName);
+        let matches;
+        let candidates = [];
+        if (input.member.descriptor) {
+            const descriptorHits = exactNameHits.filter((m) => m.jvmDescriptor === input.member.descriptor);
+            if (descriptorHits.length > 0) {
+                matches = descriptorHits.map(buildMatch);
+            }
+            else {
+                matches = [];
+                candidates = exactNameHits.map((m) => ({
+                    name: m.name,
+                    descriptor: m.jvmDescriptor,
+                    reason: `name match, descriptor ${m.jvmDescriptor} differs from requested ${input.member.descriptor}`
+                }));
+            }
+        }
+        else {
+            matches = exactNameHits.map(buildMatch);
+        }
+        if (matches.length === 0 && candidates.length === 0) {
+            const suggestions = suggestSimilar(memberName, allMemberNames);
+            candidates = suggestions.flatMap((suggestion) => memberPool
+                .filter((m) => m.name === suggestion)
+                .map((m) => ({
+                name: m.name,
+                descriptor: m.jvmDescriptor,
+                reason: `name "${m.name}" is similar to requested "${memberName}"`
+            })));
+        }
+        const exists = matches.length > 0;
+        let accessorAdvice;
+        if (matches.length === 1) {
+            accessorAdvice = inferAnnotation(input.member, matches[0], input.mixinMemberName);
+        }
+        return {
+            exists,
+            resolvedOwner: { className: owner, mapping: resolved.mappingApplied },
+            matches,
+            candidates,
+            ...(accessorAdvice ? { accessorAdvice } : {}),
+            warnings,
+            provenance: {
+                artifactId: resolved.artifactId,
+                mappingNamespace: resolved.mappingApplied,
+                ...(resolved.provenance?.workspaceResolution
+                    ? { workspaceResolution: resolved.provenance.workspaceResolution }
+                    : {}),
+                ...(resolved.provenance?.dependencyResolution
+                    ? { dependencyResolution: resolved.provenance.dependencyResolution }
+                    : {})
+            }
+        };
+    }
+}
+const memberDescriptorSchema = z.string().trim().min(1).optional();
+const verifyMixinTargetMemberSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("method"),
+        name: z.string().trim().min(1),
+        descriptor: memberDescriptorSchema
+    }),
+    z.object({
+        kind: z.literal("field"),
+        name: z.string().trim().min(1),
+        descriptor: memberDescriptorSchema
+    })
+]);
+export const verifyMixinTargetMemberSchemaExport = verifyMixinTargetMemberSchema;
+//# sourceMappingURL=verify-mixin-target-service.js.map

package/dist/error-mapping.d.ts

@@ -0,0 +1,40 @@
+import { type ErrorCode } from "./errors.js";
+export type ProblemFieldError = {
+    path: string;
+    message: string;
+    code?: string;
+};
+export type SuggestedCall = {
+    tool: string;
+    params: Record<string, unknown>;
+};
+export type ExampleCall = {
+    tool: string;
+    params: Record<string, unknown>;
+    reason: string;
+};
+export type ProblemDetails = {
+    type: string;
+    title: string;
+    detail: string;
+    status: number;
+    code: string;
+    instance: string;
+    fieldErrors?: ProblemFieldError[];
+    hints?: string[];
+    suggestedCall?: SuggestedCall;
+    exampleCalls?: ExampleCall[];
+    failedStage?: string;
+};
+export declare function statusForErrorCode(code: string): number;
+/**
+ * Per-entry subset of `mapErrorToProblem` for batch tools. ZodErrors are not
+ * handled here (per-entry input has already cleared the batch tool's schema
+ * gate); the optional `suggestedCall` is attached as-is for the caller's
+ * synthesized retry payload.
+ */
+export declare function errorToBatchEntryProblem(caughtError: unknown, instance: string, options?: {
+    suggestedCall?: SuggestedCall;
+}): ProblemDetails;
+export declare function buildBatchAbortedProblem(instance: string): ProblemDetails;
+export type { ErrorCode };

package/dist/error-mapping.js

@@ -0,0 +1,139 @@
+import { ERROR_CODES, isAppError } from "./errors.js";
+import { log } from "./logger.js";
+export function statusForErrorCode(code) {
+    if (code === ERROR_CODES.BATCH_ABORTED) {
+        return 412;
+    }
+    if (code === ERROR_CODES.STAGE_BUDGET_PRE_PARSE) {
+        // 408 (Request Timeout): caller-recoverable stage-budget exhaustion,
+        // not an internal server failure.
+        return 408;
+    }
+    if (code === ERROR_CODES.INVALID_INPUT ||
+        code === ERROR_CODES.COORDINATE_PARSE_FAILED ||
+        code === ERROR_CODES.INVALID_LINE_RANGE ||
+        code === ERROR_CODES.NBT_PARSE_FAILED ||
+        code === ERROR_CODES.NBT_INVALID_TYPED_JSON ||
+        code === ERROR_CODES.JSON_PATCH_INVALID ||
+        code === ERROR_CODES.NBT_ENCODE_FAILED ||
+        code === ERROR_CODES.NBT_UNSUPPORTED_FEATURE) {
+        return 400;
+    }
+    if (code === ERROR_CODES.JSON_PATCH_CONFLICT || code === ERROR_CODES.CONTEXT_UNRESOLVED) {
+        return 409;
+    }
+    if (code === ERROR_CODES.SOURCE_NOT_FOUND ||
+        code === ERROR_CODES.FILE_NOT_FOUND ||
+        code === ERROR_CODES.JAR_NOT_FOUND ||
+        code === ERROR_CODES.VERSION_NOT_FOUND ||
+        code === ERROR_CODES.CLASS_NOT_FOUND) {
+        return 404;
+    }
+    if (code === ERROR_CODES.MAPPING_NOT_APPLIED ||
+        code === ERROR_CODES.MAPPING_UNAVAILABLE ||
+        code === ERROR_CODES.NAMESPACE_MISMATCH ||
+        code === ERROR_CODES.DECOMPILE_DISABLED ||
+        code === ERROR_CODES.REMAP_FAILED ||
+        code === ERROR_CODES.WORKSPACE_VERSION_UNRESOLVED ||
+        code === ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED) {
+        return 422;
+    }
+    if (code === ERROR_CODES.REMAPPER_UNAVAILABLE ||
+        code === ERROR_CODES.JAVA_PROCESS_FAILED) {
+        return 503;
+    }
+    if (code === ERROR_CODES.LIMIT_EXCEEDED) {
+        return 413;
+    }
+    if (code === ERROR_CODES.REPO_FETCH_FAILED) {
+        return 502;
+    }
+    if (code === ERROR_CODES.DECOMPILER_UNAVAILABLE ||
+        code === ERROR_CODES.DECOMPILER_FAILED ||
+        code === ERROR_CODES.JAVA_UNAVAILABLE ||
+        code === ERROR_CODES.REGISTRY_GENERATION_FAILED) {
+        return 503;
+    }
+    return 500;
+}
+function extractFieldErrors(details) {
+    if (typeof details !== "object" || details == null)
+        return undefined;
+    const raw = details.fieldErrors;
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== "object" || entry == null)
+            continue;
+        const rec = entry;
+        if (typeof rec.path !== "string" || typeof rec.message !== "string")
+            continue;
+        out.push({
+            path: rec.path,
+            message: rec.message,
+            ...(typeof rec.code === "string" ? { code: rec.code } : {})
+        });
+    }
+    return out.length > 0 ? out : undefined;
+}
+function extractHints(details) {
+    if (typeof details !== "object" || details == null)
+        return undefined;
+    const next = details.nextAction;
+    if (typeof next !== "string" || !next.trim())
+        return undefined;
+    return [next.trim()];
+}
+/**
+ * Per-entry subset of `mapErrorToProblem` for batch tools. ZodErrors are not
+ * handled here (per-entry input has already cleared the batch tool's schema
+ * gate); the optional `suggestedCall` is attached as-is for the caller's
+ * synthesized retry payload.
+ */
+export function errorToBatchEntryProblem(caughtError, instance, options) {
+    if (isAppError(caughtError)) {
+        const baseHints = extractHints(caughtError.details);
+        const fieldErrors = extractFieldErrors(caughtError.details);
+        return {
+            type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
+            title: "Tool execution error",
+            detail: caughtError.message,
+            status: statusForErrorCode(caughtError.code),
+            code: caughtError.code,
+            instance,
+            ...(fieldErrors ? { fieldErrors } : {}),
+            ...(baseHints ? { hints: baseHints } : {}),
+            ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {})
+        };
+    }
+    // Generic-error sanitization: fixed public detail, raw message logged
+    // server-side keyed by `instance`. Mirrors `mapErrorToProblem` so the
+    // public envelope cannot leak filesystem paths, parser internals, or
+    // assertion text on a non-AppError path.
+    const rawMessage = caughtError instanceof Error ? caughtError.message : String(caughtError);
+    log("error", "batch.entry.unhandled", {
+        instance,
+        reason: rawMessage
+    });
+    return {
+        type: "https://minecraft-modding-mcp.dev/problems/internal",
+        title: "Internal server error",
+        detail: "Unexpected server error.",
+        status: 500,
+        code: ERROR_CODES.INTERNAL,
+        instance,
+        ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {})
+    };
+}
+export function buildBatchAbortedProblem(instance) {
+    return {
+        type: `https://minecraft-modding-mcp.dev/problems/${ERROR_CODES.BATCH_ABORTED.toLowerCase()}`,
+        title: "Batch aborted",
+        detail: "Earlier entry failed and failFast=true.",
+        status: 412,
+        code: ERROR_CODES.BATCH_ABORTED,
+        instance
+    };
+}
+//# sourceMappingURL=error-mapping.js.map

package/dist/errors.d.ts

@@ -30,6 +30,12 @@ export declare const ERROR_CODES: {
     readonly JAVA_PROCESS_FAILED: "ERR_JAVA_PROCESS_FAILED";
     readonly REMAP_FAILED: "ERR_REMAP_FAILED";
     readonly REMAPPER_UNAVAILABLE: "ERR_REMAPPER_UNAVAILABLE";
+    readonly WORKER_RESTART: "ERR_WORKER_RESTART";
+    readonly MIXIN_PARSE_FAILED: "ERR_MIXIN_PARSE_FAILED";
+    readonly STAGE_BUDGET_PRE_PARSE: "ERR_STAGE_BUDGET_PRE_PARSE";
+    readonly WORKSPACE_VERSION_UNRESOLVED: "ERR_WORKSPACE_VERSION_UNRESOLVED";
+    readonly DEPENDENCY_VERSION_UNRESOLVED: "ERR_DEPENDENCY_VERSION_UNRESOLVED";
+    readonly BATCH_ABORTED: "ERR_BATCH_ABORTED";
     readonly INTERNAL: "ERR_INTERNAL";
 };
 export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];

package/dist/errors.js

@@ -30,6 +30,12 @@ export const ERROR_CODES = {
     JAVA_PROCESS_FAILED: "ERR_JAVA_PROCESS_FAILED",
     REMAP_FAILED: "ERR_REMAP_FAILED",
     REMAPPER_UNAVAILABLE: "ERR_REMAPPER_UNAVAILABLE",
+    WORKER_RESTART: "ERR_WORKER_RESTART",
+    MIXIN_PARSE_FAILED: "ERR_MIXIN_PARSE_FAILED",
+    STAGE_BUDGET_PRE_PARSE: "ERR_STAGE_BUDGET_PRE_PARSE",
+    WORKSPACE_VERSION_UNRESOLVED: "ERR_WORKSPACE_VERSION_UNRESOLVED",
+    DEPENDENCY_VERSION_UNRESOLVED: "ERR_DEPENDENCY_VERSION_UNRESOLVED",
+    BATCH_ABORTED: "ERR_BATCH_ABORTED",
     INTERNAL: "ERR_INTERNAL"
 };
 export class AppError extends Error {

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SourceService } from "./source-service.js";
+import { applyErrorMetaExtensions, mapErrorToProblem } from "./tool-guidance.js";
+export { mapErrorToProblem, applyErrorMetaExtensions };
 declare const SERVER_VERSION: string;
 declare const server: McpServer;
 declare const config: import("./types.js").Config;