@adhisang/minecraft-modding-mcp 7.0.0-rc.0 → 7.0.0-rc.2

package/dist/cache-registry.js

@@ -4,6 +4,7 @@ import { join, resolve } from "node:path";
 import { mapWithConcurrencyLimit } from "./concurrency.js";
 import { createError, ERROR_CODES } from "./errors.js";
 import { normalizeOptionalPathForHost } from "./path-converter.js";
+import { downloadSidecarPath, isDownloadSidecarPath } from "./repo-downloader.js";
 import { openDatabase } from "./storage/db.js";
 import { getProcessWorkspaceContextCache } from "./workspace-context-cache.js";
 export const PUBLIC_CACHE_KINDS = [
@@ -226,7 +227,11 @@ function openDb(config) {
     if (!existsSync(config.sqlitePath)) {
         return undefined;
     }
-    return openDatabase(config).db;
+    return openDatabase({
+        sqlitePath: config.sqlitePath,
+        sqliteCacheKb: config.sqliteCacheKb,
+        sqliteMmapSize: config.sqliteMmapSize
+    }).db;
 }
 function candidatePathsForEntry(entry) {
     const paths = new Set();
@@ -467,15 +472,28 @@ async function fileBackedEntries(config, cacheKind, detectCorruption) {
     }
     const root = kindRoot(config, cacheKind);
     const files = await listFilesRecursive(root);
-    return mapWithConcurrencyLimit(files, CACHE_STAT_CONCURRENCY, async (filePath) => {
+    // A download sidecar (`<jar>.cache.json`, or the `.<hex>.tmp` leftover of an
+    // interrupted write) is the identity record of the jar beside it, not a cached
+    // artifact in its own right. Listing one would report a `downloads` entry whose
+    // jarPath is a JSON file and would let a jarPath selector delete a description
+    // instead of the thing described. The finished record's bytes are folded into
+    // the jar's entry below, so a listed entry weighs everything that belongs to
+    // it; bytes that describe nothing - an orphan record, a half-written one - are
+    // deliberately unaccounted, because there is no entry for them to belong to.
+    // Only this kind names files that way; every other kind keeps every file.
+    const entryFiles = cacheKind === "downloads"
+        ? files.filter((filePath) => !isDownloadSidecarPath(filePath))
+        : files;
+    return mapWithConcurrencyLimit(entryFiles, CACHE_STAT_CONCURRENCY, async (filePath) => {
         const fileStat = await stat(filePath);
+        const sidecarBytes = cacheKind === "downloads" ? await downloadSidecarSizeBytes(filePath) : 0;
         const normalizedEntryId = filePath.slice(root.length + 1);
         const inferredScope = inferScope(filePath, normalizedEntryId) ?? (cacheKind === "decompiled-source" ? "vanilla" : undefined);
         return {
             cacheKind,
             entryId: normalizedEntryId,
             path: filePath,
-            sizeBytes: fileStat.size,
+            sizeBytes: fileStat.size + sidecarBytes,
             status: "healthy",
             meta: {
                 updatedAt: fileStat.mtime.toISOString(),
@@ -483,6 +501,8 @@ async function fileBackedEntries(config, cacheKind, detectCorruption) {
                 mapping: inferMapping(filePath, normalizedEntryId),
                 scope: inferredScope,
                 projectPath: inferProjectPath(filePath, config.pathRuntimeInfo),
+                // Health follows the cached artifact's own bytes: a zero-byte jar stays
+                // partial no matter how much its sidecar weighs.
                 partial: fileStat.size === 0,
                 corrupt: cacheKind === "registry" && detectCorruption ? await isCorruptRegistryJson(filePath) : false,
                 inUse: filePath.endsWith(".lock") ||
@@ -495,6 +515,19 @@ async function fileBackedEntries(config, cacheKind, detectCorruption) {
         };
     });
 }
+/**
+ * Bytes of the sidecar describing `downloadPath`, or 0 when there is none.
+ * A download cached before sidecars existed, or one whose sidecar write failed,
+ * is a normal state and must not fail the inventory.
+ */
+async function downloadSidecarSizeBytes(downloadPath) {
+    try {
+        return (await stat(downloadSidecarPath(downloadPath))).size;
+    }
+    catch {
+        return 0;
+    }
+}
 /**
  * Binary-remap cache entries are keyed by the final artifact id even when the
  * on-disk entry is a corrupt final directory or a leftover temp path.
@@ -661,6 +694,14 @@ export function createCacheRegistry(config) {
                             workspaceCache.invalidate(entry.entryId);
                             continue;
                         }
+                        if (entry.cacheKind === "downloads") {
+                            // The sidecar is part of this entry, so it goes with the jar —
+                            // outside the existsSync guard below, so a jar that vanished
+                            // out-of-band since the listing still takes its sidecar with it
+                            // instead of leaving an orphan behind. `force` makes a missing
+                            // sidecar a no-op.
+                            await rm(downloadSidecarPath(entry.path), { force: true });
+                        }
                         if (existsSync(entry.path)) {
                             // Only binary-remap inventory can return directories as entries;
                             // other file-backed kinds keep their existing file-only contract.

package/dist/entry-tools/batch-class-members-service.js

@@ -48,6 +48,14 @@ export class BatchClassMembersService {
                 }
                 const raw = (await this.deps.getClassMembers({
                     artifactId: sharedArtifact.artifactId,
+                    // This artifactId is OURS, not the caller's: the shared target was
+                    // resolved above and every entry is dispatched by the result. Without
+                    // saying so, get-class-members reads the bare presence of an
+                    // artifactId as the caller having named the artifact, and reports a
+                    // missing binary jar as their mistake - once per entry - though
+                    // `target` here cannot name an artifact at all. Only a jar the caller
+                    // named themselves is genuinely their choice.
+                    artifactSelectedBy: input.target.kind === "jar" ? "caller" : "tool",
                     className: entry.className,
                     access: entry.access,
                     includeSynthetic: entry.includeSynthetic,

package/dist/entry-tools/inspect-minecraft/handlers/class-members.js

@@ -1,5 +1,17 @@
 import { buildEntryToolResult, buildEntryToolMeta, createNextAction, createSummarySubject, createTruncationMeta } from "../../response-contract.js";
 import { buildClassSubject, resolveClassArtifactReference, invalidTaskSubjectError } from "../internal.js";
+function artifactSelectedByFor(ref) {
+    if (!ref) {
+        return "tool";
+    }
+    // A `resolved-id` reference is NOT a caller choice, despite being written by
+    // the caller. The id is an opaque handle some earlier resolve produced: it
+    // says nothing about whether the artifact carries a binary jar, and it cannot
+    // be re-resolved into one that does. Only `target: { kind: "jar", ... }`
+    // names a jar the caller actually picked and can pick differently, which is
+    // the same line `get-class-members` draws for its own `artifact` target.
+    return ref.type === "resolve-target" && ref.target.kind === "jar" ? "caller" : "tool";
+}
 export async function handleClassMembers(deps, subject, detail, include, limit) {
     if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
         invalidTaskSubjectError("class-members", subject);
@@ -9,6 +21,15 @@ export async function handleClassMembers(deps, subject, detail, include, limit)
     const members = await deps.getClassMembers({
         className: classSubject.className,
         artifactId: artifact.artifactId || undefined,
+        // The artifactId above is one WE produced - resolveClassArtifactReference
+        // collapses every subject shape to one, including the workspace
+        // auto-resolution that happens with no artifact reference at all. Only the
+        // caller's own reference says whether they picked the artifact, and only a
+        // jar target does: it names an exact jar they can name differently.
+        // Anything else (a resolved-id handle, a version/coordinate target, or an
+        // omitted reference) leaves the artifact effectively ours, so a missing
+        // binary jar is not their input to fix.
+        artifactSelectedBy: artifactSelectedByFor(classSubject.artifact),
         mapping: classSubject.mapping,
         scope: classSubject.scope,
         projectPath: classSubject.projectPath,

package/dist/entry-tools/inspect-minecraft/internal.d.ts

@@ -424,6 +424,10 @@ export type InspectMinecraftDeps = {
         strictVersion?: boolean;
         maxMembers?: number;
         includeDescriptors?: boolean;
+        /** Who chose the artifact: see `GetClassMembersInput.artifactSelectedBy`.
+         * This tool always collapses its subject to an artifactId before calling,
+         * so without it every failure would be attributed to the caller. */
+        artifactSelectedBy?: "caller" | "tool";
     }) => Promise<GetClassMembersOutput>;
     searchClassSource: (input: {
         artifactId: string;

package/dist/entry-tools/manage-cache-service.d.ts

@@ -27,9 +27,9 @@ export declare const manageCacheShape: {
         jarPath: z.ZodOptional<z.ZodString>;
         entryId: z.ZodOptional<z.ZodString>;
         status: z.ZodOptional<z.ZodEnum<{
+            stale: "stale";
             healthy: "healthy";
             partial: "partial";
-            stale: "stale";
             orphaned: "orphaned";
             corrupt: "corrupt";
             in_use: "in_use";
@@ -81,9 +81,9 @@ export declare const manageCacheSchema: z.ZodObject<{
         jarPath: z.ZodOptional<z.ZodString>;
         entryId: z.ZodOptional<z.ZodString>;
         status: z.ZodOptional<z.ZodEnum<{
+            stale: "stale";
             healthy: "healthy";
             partial: "partial";
-            stale: "stale";
             orphaned: "orphaned";
             corrupt: "corrupt";
             in_use: "in_use";

package/dist/entry-tools/validate-project/cases/mixin.js

@@ -21,14 +21,34 @@ export async function handleMixin(deps, input, detail, include) {
             details: {
                 task: "mixin",
                 failedStage: "input-validation",
-                nextAction: "Pass version explicitly (e.g. \"1.21.10\"). task=\"project-summary\" supports preferProjectVersion for auto-detection from gradle.properties, but direct task=\"mixin\" requires an explicit version.",
+                nextAction: "Pass version explicitly: the Minecraft version this project targets. task=\"project-summary\" supports preferProjectVersion for auto-detection from gradle.properties, but direct task=\"mixin\" requires an explicit version. Call the suggested list-versions to see what is available, then replay the exampleCalls template with that version substituted.",
+                // No concrete version can be derived here -- the caller omitted it and this
+                // task does not auto-detect one. A `suggestedCall` is a payload the caller
+                // may replay verbatim, so filling the hole with a made-up version produced
+                // a call that RUNS and validates the mixin against the wrong Minecraft
+                // version, which is worse than no suggestion.
+                //
+                // So the two roles are split, following what the sibling "a version is
+                // required but none was resolved" site already does in
+                // src/source/class-source.ts: `suggestedCall` is a REAL next step that
+                // needs nothing the caller does not have (list-versions takes no
+                // arguments and answers exactly the question blocking them), while the
+                // task="mixin" retry shape travels as an `exampleCalls` template whose
+                // placeholder makes the substitution the caller must perform obvious.
+                ...buildSuggestedCall({ tool: "list-versions", params: {} }),
                 ...buildSuggestedCall({
                     tool: "validate-project",
-                    params: {
-                        task: "mixin",
-                        subject: input.subject,
-                        version: "1.21.10"
-                    }
+                    params: undefined,
+                    examples: [
+                        {
+                            params: {
+                                task: "mixin",
+                                subject: input.subject,
+                                version: "<your-mc-version>"
+                            },
+                            reason: "Replace <your-mc-version> with the Minecraft version this project targets (gradle.properties, or task=\"project-summary\" with preferProjectVersion=true reports it)."
+                        }
+                    ]
                 })
             }
         });

package/dist/entry-tools/validate-project/cases/project-summary.d.ts

@@ -9,7 +9,7 @@ export declare function handleProjectSummary(deps: ValidateProjectDeps, input: V
     warnings: string[];
     tasks?: {
         "workspace.detected": {
-            status: "error" | "ok" | "missing" | "skipped";
+            status: "ok" | "error" | "missing" | "skipped";
             durationMs?: number;
             error?: {
                 code: string;
@@ -20,7 +20,7 @@ export declare function handleProjectSummary(deps: ValidateProjectDeps, input: V
             evidence?: string[];
         };
         "gradle.readable": {
-            status: "error" | "ok" | "missing" | "skipped";
+            status: "ok" | "error" | "missing" | "skipped";
             durationMs?: number;
             error?: {
                 code: string;
@@ -32,7 +32,7 @@ export declare function handleProjectSummary(deps: ValidateProjectDeps, input: V
             buildScripts?: string[];
         };
         "loom.cache.found": {
-            status: "error" | "ok" | "missing" | "skipped";
+            status: "ok" | "error" | "missing" | "skipped";
             durationMs?: number;
             error?: {
                 code: string;
@@ -43,7 +43,7 @@ export declare function handleProjectSummary(deps: ValidateProjectDeps, input: V
             cachePath?: string;
         };
         "minecraft.artifact.resolved": {
-            status: "error" | "ok" | "missing" | "skipped";
+            status: "ok" | "error" | "missing" | "skipped";
             durationMs?: number;
             error?: {
                 code: string;
@@ -55,7 +55,7 @@ export declare function handleProjectSummary(deps: ValidateProjectDeps, input: V
             mapping?: import("../../../types.js").SourceMapping;
         };
         "mixins.validated": {
-            status: "error" | "ok" | "missing" | "skipped";
+            status: "ok" | "error" | "missing" | "skipped";
             durationMs?: number;
             error?: {
                 code: string;
@@ -70,7 +70,7 @@ export declare function handleProjectSummary(deps: ValidateProjectDeps, input: V
             };
         };
         "accessWideners.validated": {
-            status: "error" | "ok" | "missing" | "skipped";
+            status: "ok" | "error" | "missing" | "skipped";
             durationMs?: number;
             error?: {
                 code: string;
@@ -84,7 +84,7 @@ export declare function handleProjectSummary(deps: ValidateProjectDeps, input: V
             };
         };
         "accessTransformers.validated": {
-            status: "error" | "ok" | "missing" | "skipped";
+            status: "ok" | "error" | "missing" | "skipped";
             durationMs?: number;
             error?: {
                 code: string;

package/dist/entry-tools/validate-project-service.d.ts

@@ -134,8 +134,8 @@ export declare const validateProjectShape: {
     sourceRoots: z.ZodOptional<z.ZodArray<z.ZodString>>;
     configPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     minSeverity: z.ZodDefault<z.ZodEnum<{
-        all: "all";
         error: "error";
+        all: "all";
         warning: "warning";
     }>>;
     hideUncertain: z.ZodDefault<z.ZodBoolean>;
@@ -246,8 +246,8 @@ export declare const validateProjectSchema: z.ZodObject<{
     sourceRoots: z.ZodOptional<z.ZodArray<z.ZodString>>;
     configPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     minSeverity: z.ZodDefault<z.ZodEnum<{
-        all: "all";
         error: "error";
+        all: "all";
         warning: "warning";
     }>>;
     hideUncertain: z.ZodDefault<z.ZodBoolean>;

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

@@ -221,7 +221,25 @@ export class VerifyMixinTargetService {
             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 }
+                details: {
+                    artifactId: resolved.artifactId,
+                    owner,
+                    // `ERR_CONTEXT_UNRESOLVED` classifies as `code_issue` by code, which
+                    // is right for the sibling case (a caller naming a version no
+                    // artifact carries) and for a `target: { kind: "jar", ... }` request:
+                    // there the caller named the exact jar, and having none for its own
+                    // sources is exactly the input the caller can change. It is wrong
+                    // only when the artifact was picked by the TOOL from a non-jar target
+                    // (version/coordinate/workspace/dependency), where whether it ships a
+                    // binary jar is not something the request can express. Published as
+                    // caller-fixable in that case it invites an endless retry of an input
+                    // that was never at fault, so this site overrides the default only
+                    // then.
+                    issueOrigin: input.target?.kind === "jar" ? undefined : "tool_issue",
+                    nextAction: `verify-mixin-target reads the target's members from bytecode, so it needs an artifact with a binary jar. `
+                        + `Re-target with target: { kind: "jar", value: "<path to the jar>" }, or with a version whose artifact carries one `
+                        + `(resolve-artifact reports binaryJarPath for the target you pass).`
+                }
             });
         }
         let signature;

package/dist/error-mapping.d.ts

@@ -57,6 +57,23 @@ export type ProblemDetails = {
     exampleCalls?: ExampleCall[];
     /** Ranked near-miss candidates for a class/symbol that was not found. */
     didYouMean?: DidYouMeanCandidate[];
+    /**
+     * Nested-jar inventory of the shell jar the lookup ran against, as jar-entry
+     * names (e.g. "META-INF/jars/api.jar"). A shell jar holds no classes of its
+     * own, so a class-not-found error on one is only actionable with the list of
+     * inner jars the caller can target next. Like `didYouMean`, it travels as a
+     * dedicated typed field: `context` is primitive-only and can never carry it.
+     */
+    nestedJars?: string[];
+    /**
+     * True when `nestedJars` is a SHORTENED view of the shell's inventory —
+     * entries were dropped by the count cap, the per-entry length cap, or the
+     * total-bytes cap. Without it a caller cannot tell a complete inventory from
+     * a trimmed one and may conclude a class is bundled nowhere. Additive and
+     * omitted entirely when the published list is complete, matching the
+     * `candidatesTruncated` precedent.
+     */
+    nestedJarsTruncated?: boolean;
     failedStage?: string;
     context?: Record<string, string | number | boolean>;
 };
@@ -67,6 +84,67 @@ export type ProblemDetails = {
  * whole rather than partially published.
  */
 export declare function extractDidYouMean(details: unknown): DidYouMeanCandidate[] | undefined;
+/**
+ * The `nestedJars` pair as published: the inventory plus the additive flag that
+ * says whether it is complete. Both keys are omitted when there is nothing to
+ * publish, so the object spreads directly into a ProblemDetails.
+ */
+export type NestedJarsField = {
+    nestedJars?: string[];
+    nestedJarsTruncated?: boolean;
+};
+/**
+ * Validates and extracts a `nestedJars` inventory from error details.
+ * `buildClassSourceNotFoundError` records it whenever the lookup ran against a
+ * shell jar, but `context` is primitive-only, so without this the inventory
+ * never left the process.
+ *
+ * Two distinct dispositions, deliberately not conflated:
+ *  - MALFORMED (a non-string or empty-string element, anywhere in the array):
+ *    the whole array is dropped, matching {@link extractDidYouMean}. The scan
+ *    deliberately continues past the caps so a malformed element beyond them is
+ *    still found — the upstream array is a real jar's own entry list, bounded by
+ *    the archive, so the full scan is not an exposure.
+ *  - OVERSIZED (an entry longer than {@link MAX_NESTED_JAR_ENTRY_BYTES}, an
+ *    entry past the count cap, or one that would push the list past the total
+ *    byte budget): that ENTRY alone is excluded and `nestedJarsTruncated` is
+ *    set. An implausible name is not evidence that the rest of the inventory is
+ *    untrustworthy, so it must not drop the array.
+ *
+ * An empty inventory is dropped as before: the producing site omits the key
+ * entirely in that case, so an empty array carries no information a caller could
+ * act on. If the caps leave nothing publishable, both keys are omitted rather
+ * than publishing a truncation flag with no list beside it.
+ */
+export declare function extractNestedJarsField(details: unknown): NestedJarsField;
+/**
+ * Inventory-only view of {@link extractNestedJarsField}.
+ *
+ * NOT for an emission site. All three - the tool envelope, the batch entry, the
+ * error resource - publish the field pair, because dropping the flag makes a
+ * shortened inventory indistinguishable from a complete one. This remains for
+ * callers that want the list alone (tests pinning the validation and capping
+ * rules), and a new publisher should reach for the field-returning form.
+ */
+export declare function extractNestedJars(details: unknown): string[] | undefined;
+/**
+ * Per-throw-site {@link IssueOrigin} override carried on an AppError's
+ * `details.issueOrigin`.
+ *
+ * The default classification is keyed purely on the error CODE, which is right
+ * for codes whose every throw site shares one origin. A few codes do not:
+ * `ERR_CONTEXT_UNRESOLVED` covers both a caller naming a version no artifact
+ * carries (genuinely `code_issue`) and the tool resolving an artifact with no
+ * binary jar behind the caller's back (`tool_issue`). Publishing the latter as
+ * caller-fixable sends an agent into a retry loop over input it cannot repair.
+ *
+ * This override is deliberately opt-in and per-error: `issueOriginForErrorCode`
+ * and its default sets stay untouched, so the exhaustive classification map in
+ * tests/runtime/error-mapping.test.ts keeps forcing a conscious decision for
+ * every new code. The key is not in `CONTEXT_ALLOWLIST`, so it cannot leak into
+ * the public `context` blob.
+ */
+export declare function extractIssueOriginOverride(details: unknown): IssueOrigin | undefined;
 export declare function statusForErrorCode(code: string): number;
 /**
  * Single source of truth mapping an error code to its {@link RetryClass}. Used
@@ -85,6 +163,46 @@ export declare function retryClassForErrorCode(code: string): RetryClass;
  * not satisfy).
  */
 export declare function issueOriginForErrorCode(code: string): IssueOrigin;
+/**
+ * The single source of truth for a ProblemDetails classification pair, and the
+ * ONLY supported way to compute one for an error the server caught. Every site
+ * that turns a caught error into a published envelope spreads this result — the
+ * tool envelope (`mapErrorToProblem`), batch entries, the batch-aborted
+ * sentinel, and the `mc://` resource read — so one failure always publishes the
+ * same `{ retryClass, issueOrigin }` no matter which access path the caller
+ * used.
+ *
+ * KNOWN EXCEPTION — the synthetic supervisor replies in `src/stdio-supervisor.ts`
+ * (`buildSupervisorQueueLimitReply`, `buildValidateProjectTimeoutReply`) write
+ * the pair as literals and never import this builder. They are not emission
+ * sites for a caught error at all: the supervisor answers a request the worker
+ * never got to run, so there is no source `AppError` whose `details` could carry
+ * an override and nothing to pass as the required `details` argument. Their
+ * literals are `transient` / `tool_issue`, which is exactly what this function
+ * returns for `ERR_LIMIT_EXCEEDED` and `ERR_TOOL_TIMEOUT` today — but that is a
+ * duplicated value held in agreement by hand, not a second call into this
+ * classifier. Reclassifying either code here must be mirrored there.
+ *
+ * It exists because that pair used to be assembled by hand at each site. The
+ * `issueOrigin` half has a per-throw-site override (see
+ * {@link extractIssueOriginOverride}), and honouring it was copy-pasted into
+ * some sites and forgotten in others — which is exactly how one identical
+ * AppError came to publish `tool_issue` through a tool call and `code_issue`
+ * through a resource read. Composing the pair here removes the opportunity:
+ * emission modules import this function and no longer reach the component
+ * classifiers at all.
+ *
+ * `details` is REQUIRED, deliberately without a default. A site that genuinely
+ * has no AppError behind it (a ZodError, a sanitized non-AppError, the
+ * batch-aborted sentinel) must pass `undefined` explicitly, so skipping the
+ * override can only ever be a written-down decision rather than an omission.
+ *
+ * Only `issueOrigin` is overridable per throw site. `retryClass` stays purely
+ * code-derived: it is a documented wire contract, and changing the value an
+ * existing code publishes is a Breaking change, so a `retryClass` override seam
+ * was deliberately deferred rather than added alongside this one.
+ */
+export declare function problemClassification(code: string, details: unknown): Pick<ProblemDetails, "retryClass" | "issueOrigin">;
 /**
  * Pick the allowlisted, primitive-valued fields out of an AppError's `details`
  * so the public envelope can carry structured repair context without leaking