@adhisang/minecraft-modding-mcp 6.3.0 → 7.0.0-rc.1

package/dist/registration-adapter.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { V1_PARITY_SCHEMAS } from "./v1-parity-schemas.js";
+/**
+ * Validation-bypassing Standard Schema adapter for MCP SDK v2 tool
+ * registration.
+ *
+ * The v2 SDK validates tool arguments through `schema["~standard"].validate`
+ * before invoking the handler and returns generic InvalidParams text on
+ * failure. This adapter's identity `validate` passes ALL object args through
+ * raw so runTool() remains the single source of truth for validation and
+ * error envelopes (matching pre-migration behavior, where the equivalent v1
+ * layer was bypassed).
+ *
+ * `jsonSchema` is a Converter object whose `input()` serves the pinned
+ * pre-migration wire schema for the tool (V1_PARITY_SCHEMAS), advertised
+ * VERBATIM in tools/list. The zod fallback only applies to tools without a
+ * frozen fixture (none today).
+ */
+export function appValidated(name, schema) {
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "app",
+            validate: (value) => ({ value: value }),
+            jsonSchema: {
+                input: () => V1_PARITY_SCHEMAS[name] ?? z.toJSONSchema(schema, { io: "input" })
+            }
+        }
+    };
+}
+/**
+ * Registers a tool through the v2 `registerTool` API with the
+ * validation-bypassing adapter, preserving the v1 registration surface
+ * (name, description, zod raw shape, annotations, handler).
+ */
+export function registerAppTool(server, name, description, shape, annotations, handler) {
+    server.registerTool(name, {
+        description,
+        inputSchema: appValidated(name, z.object(shape)),
+        annotations
+    }, handler);
+}
+// Low-level/expert tools duplicate capability that the six entry tools expose
+// in a single resolve+fetch call. registerExpertTool() registers them exactly
+// like registerAppTool() but appends a note steering agents to the entry tools
+// first. Entry tools, batch tools, and the NBT/runtime utilities (which have no
+// entry equivalent) keep their plain descriptions via registerAppTool().
+export const EXPERT_TOOL_NOTE = " Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.";
+export function registerExpertTool(server, name, description, shape, annotations, handler) {
+    registerAppTool(server, name, description + EXPERT_TOOL_NOTE, shape, annotations, handler);
+}
+//# sourceMappingURL=registration-adapter.js.map

package/dist/repo-downloader.d.ts

@@ -1,6 +1,32 @@
+/**
+ * Identity versus freshness.
+ *
+ * Everything {@link resolveCachedDownload} parks in the URL-keyed downloads
+ * cache is identified by a sha256 of its bytes, recorded in the `.cache.json`
+ * sidecar beside the file. HTTP validators (ETag / Last-Modified) are
+ * *freshness* data only: a CDN swap or a repository migration rotates them
+ * while the bytes stay byte-identical, so a validator must never leak into an
+ * artifact id.
+ *
+ * That claim is scoped to this entry point, not to the `downloads/` directory.
+ * Callers that reach for raw {@link downloadToCache} - the version service's
+ * Mojang jars, the mapping service's mapping archives - park files under the
+ * same root, write no sidecar, and keep their own identity on purpose: a Mojang
+ * artifact already carries an upstream SHA-1 contract, and a version jar keeps
+ * an `mtimeMs:size` signature. They are a different cache layer, not a
+ * migration this module is waiting on. Artifacts on local disk outside the
+ * cache entirely (`~/.m2`, the Gradle module cache) likewise keep their own
+ * stat signature.
+ */
 export interface DownloadResult {
     ok: boolean;
     statusCode?: number;
+    /**
+     * True only for an HTTP 304 answer to a conditional request. `ok` stays false
+     * because no bytes were written; callers that send no validators can never
+     * observe it.
+     */
+    notModified?: boolean;
     etag?: string;
     lastModified?: string;
     contentLength?: number;
@@ -10,6 +36,145 @@ export interface DownloadOptions {
     timeoutMs?: number;
     retries?: number;
     fetchFn?: typeof fetch;
+    /** Extra request headers, e.g. the conditional validators of a revalidation. */
+    requestHeaders?: Record<string, string>;
 }
+/**
+ * How a cached download may be reused.
+ *
+ * - `"immutable"`: the bytes behind the URL can never change, so a cached file
+ *   is authoritative and no request is made.
+ * - `"revalidate"`: the bytes may change, so a cached file is confirmed with a
+ *   conditional request before it is reused.
+ */
+export type CacheFreshness = "immutable" | "revalidate";
+/**
+ * Where the bytes of a successful {@link resolveCachedDownload} came from.
+ *
+ * - `"downloaded"`: written by this call.
+ * - `"hit"`: served from cache with no request at all (an immutable url).
+ * - `"revalidated"`: the repository confirmed the cached bytes with a 304.
+ * - `"stale"`: revalidation failed *transiently* - the request threw, the
+ *   repository answered 5xx, or we were rate limited - and the cached bytes
+ *   were served anyway. Byte for byte they are as good as a `"hit"`, but
+ *   nothing confirmed them on this call, which is exactly the difference a
+ *   caller reporting freshness (or a test pinning the fallback) needs to see.
+ *   A *definitive* rejection never lands here: see
+ *   {@link DEFINITIVE_REJECTION_STATUS_CODES}.
+ */
+export type DownloadCacheStatus = "downloaded" | "hit" | "revalidated" | "stale";
+export interface CachedDownloadSuccess {
+    ok: true;
+    cacheStatus: DownloadCacheStatus;
+    statusCode?: number;
+    /** The cached file. Always present on success, cache hit or not. */
+    path: string;
+    /** The real on-disk byte count. Never a Content-Length header value. */
+    contentLength: number;
+    /** sha256 of the bytes on disk. The identity of this artifact. */
+    contentSha256: string;
+    /** Freshness data only. Never feed this into an identity hash. */
+    etag?: string;
+    /** Freshness data only. Never feed this into an identity hash. */
+    lastModified?: string;
+}
+export interface CachedDownloadFailure {
+    ok: false;
+    statusCode?: number;
+    etag?: string;
+    lastModified?: string;
+    contentLength?: number;
+}
+/**
+ * The result of a cache-aware download. The success arm carries `path`,
+ * `contentLength` and `contentSha256` no matter which leg produced it, so a
+ * caller cannot accidentally derive a different identity for a cache hit than
+ * for a fresh download.
+ */
+export type CachedDownloadResult = CachedDownloadSuccess | CachedDownloadFailure;
+/** The persisted identity and freshness record for one cached download. */
+export interface DownloadSidecar {
+    version: number;
+    url: string;
+    contentSha256: string;
+    contentLength: number;
+    /**
+     * `mtimeMs` of the described file when the record was written. Together with
+     * `contentLength` this is what binds the digest to a specific set of bytes, so
+     * a replacement - accidental or racing - retires the record instead of
+     * outliving the bytes it describes.
+     */
+    contentMtimeMs: number;
+    etag?: string;
+    lastModified?: string;
+}
+/** Location of the sidecar describing `destinationPath`. Destination-adjacent. */
+export declare function downloadSidecarPath(destinationPath: string): string;
+/**
+ * Whether `filePath` is a download sidecar - finished or half-written - rather
+ * than a downloaded artifact.
+ *
+ * This module owns the sidecar naming scheme, so consumers that walk the
+ * download cache (the cache registry inventory) ask here instead of matching
+ * the suffix themselves. The in-flight form counts: a process killed inside
+ * {@link writeDownloadSidecar} leaves `<jar>.cache.json.<hex>.tmp`, which is
+ * still a description of a jar and must never be inventoried as a cached
+ * artifact in its own right. Widening the predicate rather than renaming the
+ * temp into the plain suffix is what also covers the leftovers already sitting
+ * in caches written by earlier builds - the only leftovers that exist today.
+ *
+ * The jar temps {@link downloadToCache} writes (`<jar>.<hex>.tmp`, no sidecar
+ * suffix) are deliberately not matched: those are truncated *artifacts*, and
+ * the inventory has always listed them as such.
+ */
+export declare function isDownloadSidecarPath(filePath: string): boolean;
+/**
+ * Evict a cached download and its identity record.
+ *
+ * For a caller that got its bytes and then found them unusable - a 200 carrying
+ * an HTML error page instead of a jar, say. The transfer succeeded, so nothing
+ * in here can tell it apart from a real artifact, and for an immutable url the
+ * entry would otherwise be served straight back on every later run with no
+ * request made at all: the poison would outlive the outage that produced it.
+ *
+ * Record first, bytes second, matching {@link writeDownloadSidecar}'s ordering
+ * in reverse: no window ever holds a record describing bytes that are gone. Both
+ * steps are best-effort - a file we could not remove is at worst re-validated
+ * and re-evicted next time.
+ */
+export declare function discardCachedDownload(destinationPath: string): void;
+/**
+ * Resolve a URL into a cached file, deciding here - inside the module that owns
+ * the download cache - whether the network is needed at all.
+ *
+ * `freshness: "immutable"` never asks the network once the file exists.
+ * `freshness: "revalidate"` confirms known validators with a conditional
+ * request and keeps the cached bytes on a 304. When revalidation fails
+ * *transiently* (offline repo, 5xx, rate limiting) the cached bytes are still
+ * served - they are a byte-exact copy of what the repository handed out before,
+ * and losing them to a passing failure would be a regression over the previous
+ * unconditional "file exists -> reuse it" behaviour - but they are reported as
+ * `cacheStatus: "stale"`, never as a confirmed hit. A definitive rejection
+ * ({@link DEFINITIVE_REJECTION_STATUS_CODES}) is reported as the failure it is,
+ * so the caller can fail over to another repository.
+ *
+ * A zero-byte answer is refused rather than cached: see {@link cachedByteCount}.
+ *
+ * @param url - The artifact URL; also the identity the sidecar is bound to.
+ * @param destinationPath - Where the bytes live; the sidecar sits next to it.
+ * @param options - Download options plus the required freshness policy.
+ * @returns A result whose success arm always carries `path`, the real on-disk
+ *   `contentLength`, and `contentSha256`, regardless of which leg produced it.
+ */
+export declare function resolveCachedDownload(url: string, destinationPath: string, options: DownloadOptions & {
+    freshness: CacheFreshness;
+}): Promise<CachedDownloadResult>;
+/**
+ * Fetch `url` unconditionally and stream it into `destinationPath`.
+ *
+ * This is the raw transfer: it knows nothing about what is already cached.
+ * Prefer {@link resolveCachedDownload} for anything keyed by URL in the
+ * downloads cache.
+ */
 export declare function downloadToCache(url: string, destinationPath: string, opts?: DownloadOptions): Promise<DownloadResult>;
 export declare function defaultDownloadPath(cacheDir: string, url: string): string;