@adhisang/minecraft-modding-mcp 1.0.0

package/dist/nbt/typed-json.js

@@ -0,0 +1,205 @@
+import { createError, ERROR_CODES } from "../errors.js";
+const NODE_TYPES = [
+    "byte",
+    "short",
+    "int",
+    "long",
+    "float",
+    "double",
+    "byteArray",
+    "string",
+    "list",
+    "compound",
+    "intArray",
+    "longArray"
+];
+const LIST_ELEMENT_TYPES = ["end", ...NODE_TYPES];
+const NODE_TYPE_SET = new Set(NODE_TYPES);
+const LIST_ELEMENT_TYPE_SET = new Set(LIST_ELEMENT_TYPES);
+const INT64_MIN = -9223372036854775808n;
+const INT64_MAX = 9223372036854775807n;
+function isRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !ArrayBuffer.isView(value));
+}
+function describeType(value) {
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (value === null) {
+        return "null";
+    }
+    return typeof value;
+}
+function fail(jsonPointer, expectedType, actualValue) {
+    return {
+        ok: false,
+        issue: {
+            jsonPointer,
+            expectedType,
+            actualType: describeType(actualValue)
+        }
+    };
+}
+function escapePointerToken(token) {
+    return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function validateIntegerInRange(value, min, max, pointer, expectedType) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+        return fail(pointer, expectedType, value);
+    }
+    return { ok: true };
+}
+function validateLongString(value, pointer) {
+    if (typeof value !== "string") {
+        return fail(pointer, "int64-decimal-string", value);
+    }
+    if (!/^-?(0|[1-9][0-9]*)$/.test(value)) {
+        return fail(pointer, "int64-decimal-string", value);
+    }
+    let parsed;
+    try {
+        parsed = BigInt(value);
+    }
+    catch {
+        return fail(pointer, "int64-decimal-string", value);
+    }
+    if (parsed < INT64_MIN || parsed > INT64_MAX) {
+        return fail(pointer, "int64-decimal-string", value);
+    }
+    return { ok: true };
+}
+function validateLongStringArray(value, pointer) {
+    if (!Array.isArray(value)) {
+        return fail(pointer, "int64-decimal-string-array", value);
+    }
+    for (let i = 0; i < value.length; i += 1) {
+        const result = validateLongString(value[i], `${pointer}/${i}`);
+        if (!result.ok) {
+            return result;
+        }
+    }
+    return { ok: true };
+}
+function validateNumericArray(value, pointer, expectedType, min, max) {
+    if (!Array.isArray(value)) {
+        return fail(pointer, expectedType, value);
+    }
+    for (let i = 0; i < value.length; i += 1) {
+        const result = validateIntegerInRange(value[i], min, max, `${pointer}/${i}`, expectedType);
+        if (!result.ok) {
+            return result;
+        }
+    }
+    return { ok: true };
+}
+function validateNode(value, pointer) {
+    if (!isRecord(value)) {
+        return fail(pointer, "nbt-node", value);
+    }
+    if (!("type" in value)) {
+        return fail(`${pointer}/type`, "nbt-node-type", undefined);
+    }
+    const nodeTypeRaw = value.type;
+    if (typeof nodeTypeRaw !== "string" || !NODE_TYPE_SET.has(nodeTypeRaw)) {
+        return fail(`${pointer}/type`, "nbt-node-type", nodeTypeRaw);
+    }
+    const nodeType = nodeTypeRaw;
+    const node = value;
+    switch (nodeType) {
+        case "byte":
+            return validateIntegerInRange(node.value, -128, 127, `${pointer}/value`, "int8");
+        case "short":
+            return validateIntegerInRange(node.value, -32768, 32767, `${pointer}/value`, "int16");
+        case "int":
+            return validateIntegerInRange(node.value, -2147483648, 2147483647, `${pointer}/value`, "int32");
+        case "long":
+            return validateLongString(node.value, `${pointer}/value`);
+        case "float":
+        case "double":
+            if (typeof node.value !== "number" || !Number.isFinite(node.value)) {
+                return fail(`${pointer}/value`, "finite-number", node.value);
+            }
+            return { ok: true };
+        case "string":
+            if (typeof node.value !== "string") {
+                return fail(`${pointer}/value`, "string", node.value);
+            }
+            return { ok: true };
+        case "byteArray":
+            return validateNumericArray(node.value, `${pointer}/value`, "int8-array", -128, 127);
+        case "intArray":
+            return validateNumericArray(node.value, `${pointer}/value`, "int32-array", -2147483648, 2147483647);
+        case "longArray":
+            return validateLongStringArray(node.value, `${pointer}/value`);
+        case "list": {
+            const elementType = node.elementType;
+            if (typeof elementType !== "string" || !LIST_ELEMENT_TYPE_SET.has(elementType)) {
+                return fail(`${pointer}/elementType`, "nbt-list-element-type", elementType);
+            }
+            const listValue = node.value;
+            if (!Array.isArray(listValue)) {
+                return fail(`${pointer}/value`, "nbt-node-array", listValue);
+            }
+            if (elementType === "end" && listValue.length > 0) {
+                return fail(`${pointer}/value`, "empty-array-for-end-list", listValue);
+            }
+            for (let i = 0; i < listValue.length; i += 1) {
+                const childPointer = `${pointer}/value/${i}`;
+                const childValidation = validateNode(listValue[i], childPointer);
+                if (!childValidation.ok) {
+                    return childValidation;
+                }
+                if (!isRecord(listValue[i])) {
+                    return fail(childPointer, "nbt-node", listValue[i]);
+                }
+                const childType = listValue[i].type;
+                if (typeof childType !== "string" || childType !== elementType) {
+                    return fail(`${childPointer}/type`, elementType, childType);
+                }
+            }
+            return { ok: true };
+        }
+        case "compound": {
+            const compoundValue = node.value;
+            if (!isRecord(compoundValue)) {
+                return fail(`${pointer}/value`, "object", compoundValue);
+            }
+            for (const [key, childValue] of Object.entries(compoundValue)) {
+                const childPointer = `${pointer}/value/${escapePointerToken(key)}`;
+                const childValidation = validateNode(childValue, childPointer);
+                if (!childValidation.ok) {
+                    return childValidation;
+                }
+            }
+            return { ok: true };
+        }
+        default:
+            return fail(`${pointer}/type`, "nbt-node-type", nodeType);
+    }
+}
+export function validateTypedNbtDocument(value) {
+    if (!isRecord(value)) {
+        return fail("", "typed-nbt-document", value);
+    }
+    if (typeof value.rootName !== "string") {
+        return fail("/rootName", "string", value.rootName);
+    }
+    if (!("root" in value)) {
+        return fail("/root", "nbt-node", undefined);
+    }
+    return validateNode(value.root, "/root");
+}
+export function assertValidTypedNbtDocument(value) {
+    const validation = validateTypedNbtDocument(value);
+    if (!validation.ok) {
+        throw createError({
+            code: ERROR_CODES.NBT_INVALID_TYPED_JSON,
+            message: "Invalid typed NBT JSON document.",
+            details: { ...validation.issue }
+        });
+    }
+}
+//# sourceMappingURL=typed-json.js.map

package/dist/nbt/types.d.ts

@@ -0,0 +1,66 @@
+export type NbtTagName = "end" | "byte" | "short" | "int" | "long" | "float" | "double" | "byteArray" | "string" | "list" | "compound" | "intArray" | "longArray";
+export type NbtNodeType = Exclude<NbtTagName, "end">;
+export type NbtListElementType = NbtTagName;
+export type NbtNode = {
+    type: "byte";
+    value: number;
+} | {
+    type: "short";
+    value: number;
+} | {
+    type: "int";
+    value: number;
+} | {
+    type: "long";
+    value: string;
+} | {
+    type: "float";
+    value: number;
+} | {
+    type: "double";
+    value: number;
+} | {
+    type: "byteArray";
+    value: number[];
+} | {
+    type: "string";
+    value: string;
+} | {
+    type: "list";
+    elementType: NbtListElementType;
+    value: NbtNode[];
+} | {
+    type: "compound";
+    value: Record<string, NbtNode>;
+} | {
+    type: "intArray";
+    value: number[];
+} | {
+    type: "longArray";
+    value: string[];
+};
+export interface TypedNbtDocument {
+    rootName: string;
+    root: NbtNode;
+}
+export interface TypedNbtValidationIssue {
+    jsonPointer: string;
+    expectedType: string;
+    actualType: string;
+}
+export type JsonPatchOpCode = "add" | "remove" | "replace" | "test";
+export interface JsonPatchOperation {
+    op: string;
+    path: string;
+    from?: string;
+    value?: unknown;
+}
+export interface ApplyJsonPatchMeta {
+    appliedOps: number;
+    testOps: number;
+    changed: boolean;
+}
+export interface ApplyJsonPatchResult {
+    typedJson: TypedNbtDocument;
+    meta: ApplyJsonPatchMeta;
+}

package/dist/nbt/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/observability.d.ts

@@ -0,0 +1,88 @@
+export interface MetricTimingSnapshot {
+    count: number;
+    totalMs: number;
+    avgMs: number;
+    lastMs: number;
+}
+export interface CacheArtifactByteAccountingRow {
+    artifact_id: string;
+    content_bytes: number;
+    updated_at: string;
+}
+export interface RuntimeMetricSnapshot {
+    resolve_duration_ms: MetricTimingSnapshot;
+    search_duration_ms: MetricTimingSnapshot;
+    get_file_duration_ms: MetricTimingSnapshot;
+    list_files_duration_ms: MetricTimingSnapshot;
+    decompile_duration_ms: MetricTimingSnapshot;
+    search_intent_symbol_duration_ms: MetricTimingSnapshot;
+    search_intent_text_duration_ms: MetricTimingSnapshot;
+    search_intent_path_duration_ms: MetricTimingSnapshot;
+    search_regex_fallback_count: number;
+    search_token_bytes_returned: number;
+    onehop_expand_count: number;
+    search_indexed_hit_count: number;
+    search_fallback_count: number;
+    indexed_disabled_count: number;
+    search_db_roundtrips: number;
+    search_rows_scanned: number;
+    search_rows_returned: number;
+    search_indexed_zero_shortcircuit_count: number;
+    reindex_count: number;
+    reindex_skip_count: number;
+    cache_evictions: number;
+    cache_entries: number;
+    cache_total_content_bytes: number;
+    cache_artifact_bytes_lru: CacheArtifactByteAccountingRow[];
+    cache_hit_rate: number;
+    repo_failover_count: number;
+}
+type DurationMetricName = keyof Pick<RuntimeMetricSnapshot, "resolve_duration_ms" | "search_duration_ms" | "get_file_duration_ms" | "list_files_duration_ms" | "decompile_duration_ms" | "search_intent_symbol_duration_ms" | "search_intent_text_duration_ms" | "search_intent_path_duration_ms">;
+export declare class RuntimeMetrics {
+    private readonly timings;
+    private cacheHits;
+    private cacheMisses;
+    private repoFailoverCount;
+    private searchRegexFallbackCount;
+    private searchTokenBytesReturned;
+    private oneHopExpandCount;
+    private searchIndexedHitCount;
+    private searchFallbackCount;
+    private indexedDisabledCount;
+    private searchDbRoundtrips;
+    private searchRowsScanned;
+    private searchRowsReturned;
+    private searchIndexedZeroShortcircuitCount;
+    private reindexCount;
+    private reindexSkipCount;
+    private cacheEvictions;
+    private cacheEntries;
+    private cacheTotalContentBytes;
+    private cacheArtifactBytesLru;
+    constructor();
+    recordDuration(name: DurationMetricName, durationMs: number): void;
+    recordArtifactCacheHit(): void;
+    recordArtifactCacheMiss(): void;
+    recordRepoFailover(): void;
+    recordSearchIntentDuration(intent: "symbol" | "text" | "path", durationMs: number): void;
+    recordSearchRegexFallback(): void;
+    recordSearchTokenBytesReturned(tokenBytes: number): void;
+    recordOneHopExpansion(count: number): void;
+    recordSearchIndexedHit(): void;
+    recordSearchFallback(): void;
+    recordIndexedDisabled(): void;
+    recordSearchDbRoundtrip(count?: number): void;
+    recordSearchRowsScanned(count: number): void;
+    recordSearchRowsReturned(count: number): void;
+    recordSearchIndexedZeroShortcircuit(): void;
+    recordReindex(): void;
+    recordReindexSkip(): void;
+    recordCacheEviction(count?: number): void;
+    setCacheEntries(entries: number): void;
+    setCacheTotalContentBytes(totalBytes: number): void;
+    setCacheArtifactByteAccounting(entries: CacheArtifactByteAccountingRow[]): void;
+    snapshot(): RuntimeMetricSnapshot;
+    private toSnapshot;
+    private resolveCacheHitRate;
+}
+export {};

package/dist/observability.js

@@ -0,0 +1,165 @@
+export class RuntimeMetrics {
+    timings = new Map();
+    cacheHits = 0;
+    cacheMisses = 0;
+    repoFailoverCount = 0;
+    searchRegexFallbackCount = 0;
+    searchTokenBytesReturned = 0;
+    oneHopExpandCount = 0;
+    searchIndexedHitCount = 0;
+    searchFallbackCount = 0;
+    indexedDisabledCount = 0;
+    searchDbRoundtrips = 0;
+    searchRowsScanned = 0;
+    searchRowsReturned = 0;
+    searchIndexedZeroShortcircuitCount = 0;
+    reindexCount = 0;
+    reindexSkipCount = 0;
+    cacheEvictions = 0;
+    cacheEntries = 0;
+    cacheTotalContentBytes = 0;
+    cacheArtifactBytesLru = [];
+    constructor() {
+        const names = [
+            "resolve_duration_ms",
+            "search_duration_ms",
+            "get_file_duration_ms",
+            "list_files_duration_ms",
+            "decompile_duration_ms",
+            "search_intent_symbol_duration_ms",
+            "search_intent_text_duration_ms",
+            "search_intent_path_duration_ms"
+        ];
+        for (const name of names) {
+            this.timings.set(name, { count: 0, totalMs: 0, lastMs: 0 });
+        }
+    }
+    recordDuration(name, durationMs) {
+        const timing = this.timings.get(name);
+        if (!timing) {
+            return;
+        }
+        const normalizedDuration = Math.max(0, Math.trunc(durationMs));
+        timing.count += 1;
+        timing.totalMs += normalizedDuration;
+        timing.lastMs = normalizedDuration;
+    }
+    recordArtifactCacheHit() {
+        this.cacheHits += 1;
+    }
+    recordArtifactCacheMiss() {
+        this.cacheMisses += 1;
+    }
+    recordRepoFailover() {
+        this.repoFailoverCount += 1;
+    }
+    recordSearchIntentDuration(intent, durationMs) {
+        const metricName = intent === "symbol"
+            ? "search_intent_symbol_duration_ms"
+            : intent === "text"
+                ? "search_intent_text_duration_ms"
+                : "search_intent_path_duration_ms";
+        this.recordDuration(metricName, durationMs);
+    }
+    recordSearchRegexFallback() {
+        this.searchRegexFallbackCount += 1;
+    }
+    recordSearchTokenBytesReturned(tokenBytes) {
+        this.searchTokenBytesReturned += Math.max(0, Math.trunc(tokenBytes));
+    }
+    recordOneHopExpansion(count) {
+        this.oneHopExpandCount += Math.max(0, Math.trunc(count));
+    }
+    recordSearchIndexedHit() {
+        this.searchIndexedHitCount += 1;
+    }
+    recordSearchFallback() {
+        this.searchFallbackCount += 1;
+    }
+    recordIndexedDisabled() {
+        this.indexedDisabledCount += 1;
+    }
+    recordSearchDbRoundtrip(count = 1) {
+        this.searchDbRoundtrips += Math.max(0, Math.trunc(count));
+    }
+    recordSearchRowsScanned(count) {
+        this.searchRowsScanned += Math.max(0, Math.trunc(count));
+    }
+    recordSearchRowsReturned(count) {
+        this.searchRowsReturned += Math.max(0, Math.trunc(count));
+    }
+    recordSearchIndexedZeroShortcircuit() {
+        this.searchIndexedZeroShortcircuitCount += 1;
+    }
+    recordReindex() {
+        this.reindexCount += 1;
+    }
+    recordReindexSkip() {
+        this.reindexSkipCount += 1;
+    }
+    recordCacheEviction(count = 1) {
+        this.cacheEvictions += Math.max(0, Math.trunc(count));
+    }
+    setCacheEntries(entries) {
+        this.cacheEntries = Math.max(0, Math.trunc(entries));
+    }
+    setCacheTotalContentBytes(totalBytes) {
+        this.cacheTotalContentBytes = Math.max(0, Math.trunc(totalBytes));
+    }
+    setCacheArtifactByteAccounting(entries) {
+        this.cacheArtifactBytesLru = entries.map((entry) => ({
+            artifact_id: entry.artifact_id,
+            content_bytes: Math.max(0, Math.trunc(entry.content_bytes)),
+            updated_at: entry.updated_at
+        }));
+    }
+    snapshot() {
+        return {
+            resolve_duration_ms: this.toSnapshot("resolve_duration_ms"),
+            search_duration_ms: this.toSnapshot("search_duration_ms"),
+            get_file_duration_ms: this.toSnapshot("get_file_duration_ms"),
+            list_files_duration_ms: this.toSnapshot("list_files_duration_ms"),
+            decompile_duration_ms: this.toSnapshot("decompile_duration_ms"),
+            search_intent_symbol_duration_ms: this.toSnapshot("search_intent_symbol_duration_ms"),
+            search_intent_text_duration_ms: this.toSnapshot("search_intent_text_duration_ms"),
+            search_intent_path_duration_ms: this.toSnapshot("search_intent_path_duration_ms"),
+            search_regex_fallback_count: this.searchRegexFallbackCount,
+            search_token_bytes_returned: this.searchTokenBytesReturned,
+            onehop_expand_count: this.oneHopExpandCount,
+            search_indexed_hit_count: this.searchIndexedHitCount,
+            search_fallback_count: this.searchFallbackCount,
+            indexed_disabled_count: this.indexedDisabledCount,
+            search_db_roundtrips: this.searchDbRoundtrips,
+            search_rows_scanned: this.searchRowsScanned,
+            search_rows_returned: this.searchRowsReturned,
+            search_indexed_zero_shortcircuit_count: this.searchIndexedZeroShortcircuitCount,
+            reindex_count: this.reindexCount,
+            reindex_skip_count: this.reindexSkipCount,
+            cache_evictions: this.cacheEvictions,
+            cache_entries: this.cacheEntries,
+            cache_total_content_bytes: this.cacheTotalContentBytes,
+            cache_artifact_bytes_lru: this.cacheArtifactBytesLru,
+            cache_hit_rate: this.resolveCacheHitRate(),
+            repo_failover_count: this.repoFailoverCount
+        };
+    }
+    toSnapshot(name) {
+        const timing = this.timings.get(name);
+        const count = timing?.count ?? 0;
+        const totalMs = timing?.totalMs ?? 0;
+        return {
+            count,
+            totalMs,
+            avgMs: count > 0 ? totalMs / count : 0,
+            lastMs: timing?.lastMs ?? 0
+        };
+    }
+    resolveCacheHitRate() {
+        const denominator = this.cacheHits + this.cacheMisses;
+        if (denominator === 0) {
+            return 0;
+        }
+        return this.cacheHits / denominator;
+    }
+}
+//# sourceMappingURL=observability.js.map

package/dist/path-converter.d.ts

@@ -0,0 +1,12 @@
+export interface PathRuntimeInfo {
+    platform: NodeJS.Platform;
+    isWsl: boolean;
+    wslDistro?: string;
+}
+export declare function detectPathRuntime(): PathRuntimeInfo;
+export declare function isWindowsDrivePath(pathValue: string): boolean;
+export declare function isWslMountPath(pathValue: string): boolean;
+export declare function isUncWslPath(pathValue: string): boolean;
+export declare function validatePathFormat(pathValue: string, runtimeInfo?: PathRuntimeInfo): string | undefined;
+export declare function normalizePathForHost(pathValue: string, runtimeInfo?: PathRuntimeInfo, field?: string): string;
+export declare function normalizeOptionalPathForHost(pathValue: string | undefined, runtimeInfo?: PathRuntimeInfo, field?: string): string | undefined;