@adhisang/minecraft-modding-mcp 4.2.1 → 5.0.0

package/dist/error-mapping.js

@@ -56,6 +56,153 @@ export function statusForErrorCode(code) {
     }
     return 500;
 }
+const RETRY_CLASS_INPUT = new Set([
+    ERROR_CODES.INVALID_INPUT,
+    ERROR_CODES.COORDINATE_PARSE_FAILED,
+    ERROR_CODES.INVALID_LINE_RANGE,
+    ERROR_CODES.NBT_PARSE_FAILED,
+    ERROR_CODES.NBT_INVALID_TYPED_JSON,
+    ERROR_CODES.JSON_PATCH_INVALID,
+    ERROR_CODES.JSON_PATCH_CONFLICT,
+    ERROR_CODES.NBT_ENCODE_FAILED,
+    ERROR_CODES.NBT_UNSUPPORTED_FEATURE,
+    ERROR_CODES.NAMESPACE_MISMATCH,
+    ERROR_CODES.CONTEXT_UNRESOLVED,
+    ERROR_CODES.MIXIN_PARSE_FAILED
+]);
+const RETRY_CLASS_PERMANENT = new Set([
+    ERROR_CODES.SOURCE_NOT_FOUND,
+    ERROR_CODES.FILE_NOT_FOUND,
+    ERROR_CODES.JAR_NOT_FOUND,
+    ERROR_CODES.VERSION_NOT_FOUND,
+    ERROR_CODES.CLASS_NOT_FOUND,
+    ERROR_CODES.MAPPING_NOT_APPLIED,
+    ERROR_CODES.MAPPING_UNAVAILABLE,
+    ERROR_CODES.DECOMPILE_DISABLED,
+    ERROR_CODES.REMAP_FAILED,
+    ERROR_CODES.WORKSPACE_VERSION_UNRESOLVED,
+    ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED,
+    ERROR_CODES.PROVENANCE_INCOMPLETE,
+    ERROR_CODES.BATCH_ABORTED
+]);
+const RETRY_CLASS_ENVIRONMENT = new Set([
+    ERROR_CODES.JAVA_UNAVAILABLE,
+    ERROR_CODES.DECOMPILER_UNAVAILABLE,
+    ERROR_CODES.DECOMPILER_FAILED,
+    ERROR_CODES.REMAPPER_UNAVAILABLE,
+    ERROR_CODES.REGISTRY_GENERATION_FAILED
+]);
+// Non-recoverable internal server faults: a deterministic defect where retrying
+// the identical call cannot help. ERR_INTERNAL covers sanitized programming
+// bugs / unexpected throws; ERR_DB_FAILURE covers SQLite integrity/migration
+// failures (the open-failure path can be a transient file lock, but corruption
+// and migration failures dominate, so it is classified server by default).
+const RETRY_CLASS_SERVER = new Set([
+    ERROR_CODES.INTERNAL,
+    ERROR_CODES.DB_FAILURE
+]);
+/**
+ * Single source of truth mapping an error code to its {@link RetryClass}. Used
+ * by every public problem builder so callers can branch on recovery strategy
+ * without parsing prose. Non-recoverable server faults (`ERR_INTERNAL`,
+ * `ERR_DB_FAILURE`) classify as `server`. Codes not explicitly classified
+ * (genuinely-transient failures such as `ERR_REPO_FETCH_FAILED` and unknown
+ * codes) default to `transient`: a temporary failure where one retry is
+ * reasonable.
+ */
+export function retryClassForErrorCode(code) {
+    if (RETRY_CLASS_INPUT.has(code)) {
+        return "input";
+    }
+    if (RETRY_CLASS_PERMANENT.has(code)) {
+        return "permanent";
+    }
+    if (RETRY_CLASS_SERVER.has(code)) {
+        return "server";
+    }
+    if (RETRY_CLASS_ENVIRONMENT.has(code)) {
+        return "environment";
+    }
+    return "transient";
+}
+// "Your request is wrong or names something absent" — the caller can fix it.
+const ISSUE_ORIGIN_CODE = new Set([
+    ERROR_CODES.INVALID_INPUT,
+    ERROR_CODES.COORDINATE_PARSE_FAILED,
+    ERROR_CODES.INVALID_LINE_RANGE,
+    ERROR_CODES.NBT_PARSE_FAILED,
+    ERROR_CODES.NBT_INVALID_TYPED_JSON,
+    ERROR_CODES.JSON_PATCH_INVALID,
+    ERROR_CODES.JSON_PATCH_CONFLICT,
+    ERROR_CODES.NBT_ENCODE_FAILED,
+    ERROR_CODES.NBT_UNSUPPORTED_FEATURE,
+    ERROR_CODES.NAMESPACE_MISMATCH,
+    ERROR_CODES.CONTEXT_UNRESOLVED,
+    ERROR_CODES.MIXIN_PARSE_FAILED,
+    ERROR_CODES.CLASS_NOT_FOUND,
+    ERROR_CODES.SOURCE_NOT_FOUND,
+    ERROR_CODES.FILE_NOT_FOUND,
+    ERROR_CODES.JAR_NOT_FOUND,
+    ERROR_CODES.VERSION_NOT_FOUND,
+    ERROR_CODES.WORKSPACE_VERSION_UNRESOLVED,
+    ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED
+]);
+/**
+ * Single source of truth mapping an error code to its {@link IssueOrigin}.
+ * Environment failures reuse the retry classifier; the input-family above is
+ * `code_issue`; everything else is a `tool_issue` (valid input the tool could
+ * not satisfy).
+ */
+export function issueOriginForErrorCode(code) {
+    if (RETRY_CLASS_ENVIRONMENT.has(code)) {
+        return "environment";
+    }
+    if (ISSUE_ORIGIN_CODE.has(code)) {
+        return "code_issue";
+    }
+    return "tool_issue";
+}
+// Non-sensitive AppError.details fields that are safe to echo to callers as
+// machine-readable repair context. Filesystem paths and free-form text are
+// intentionally excluded.
+const CONTEXT_ALLOWLIST = new Set([
+    "queryLength",
+    "maxLength",
+    "artifactId",
+    "registry",
+    "registryName",
+    "stage",
+    "version",
+    "mapping",
+    "namespace",
+    "kind",
+    "owner",
+    "limit",
+    "count",
+    "maxMembers",
+    "candidateCount",
+    "candidatesSeen",
+    "ambiguous"
+]);
+/**
+ * Pick the allowlisted, primitive-valued fields out of an AppError's `details`
+ * so the public envelope can carry structured repair context without leaking
+ * paths, parser internals, or other sensitive data.
+ */
+export function extractAllowlistedContext(details) {
+    if (typeof details !== "object" || details == null) {
+        return undefined;
+    }
+    const record = details;
+    const out = {};
+    for (const key of CONTEXT_ALLOWLIST) {
+        const value = record[key];
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            out[key] = value;
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function extractFieldErrors(details) {
     if (typeof details !== "object" || details == null)
         return undefined;
@@ -95,6 +242,7 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
     if (isAppError(caughtError)) {
         const baseHints = extractHints(caughtError.details);
         const fieldErrors = extractFieldErrors(caughtError.details);
+        const context = extractAllowlistedContext(caughtError.details);
         return {
             type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
             title: "Tool execution error",
@@ -102,9 +250,12 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
             status: statusForErrorCode(caughtError.code),
             code: caughtError.code,
             instance,
+            retryClass: retryClassForErrorCode(caughtError.code),
+            issueOrigin: issueOriginForErrorCode(caughtError.code),
             ...(fieldErrors ? { fieldErrors } : {}),
             ...(baseHints ? { hints: baseHints } : {}),
-            ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {})
+            ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {}),
+            ...(context ? { context } : {})
         };
     }
     // Generic-error sanitization: fixed public detail, raw message logged
@@ -123,6 +274,8 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
         status: 500,
         code: ERROR_CODES.INTERNAL,
         instance,
+        retryClass: retryClassForErrorCode(ERROR_CODES.INTERNAL),
+        issueOrigin: issueOriginForErrorCode(ERROR_CODES.INTERNAL),
         ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {})
     };
 }
@@ -133,7 +286,9 @@ export function buildBatchAbortedProblem(instance) {
         detail: "Earlier entry failed and failFast=true.",
         status: 412,
         code: ERROR_CODES.BATCH_ABORTED,
-        instance
+        instance,
+        retryClass: retryClassForErrorCode(ERROR_CODES.BATCH_ABORTED),
+        issueOrigin: issueOriginForErrorCode(ERROR_CODES.BATCH_ABORTED)
     };
 }
 //# sourceMappingURL=error-mapping.js.map