@adhisang/minecraft-modding-mcp 2.1.0 → 3.1.0

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

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { type CacheRegistry } from "../cache-registry.js";
+export declare const manageCacheShape: {
+    action: z.ZodEnum<["summary", "list", "inspect", "delete", "prune", "rebuild", "verify"]>;
+    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap"]>, "many">>;
+    selector: z.ZodOptional<z.ZodObject<{
+        artifactId: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        jarPath: z.ZodOptional<z.ZodString>;
+        entryId: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<["healthy", "partial", "stale", "orphaned", "corrupt", "in_use"]>>;
+        olderThan: z.ZodOptional<z.ZodString>;
+        mapping: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodString>;
+        projectPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mapping?: string | undefined;
+        jarPath?: string | undefined;
+        projectPath?: string | undefined;
+        entryId?: string | undefined;
+        artifactId?: string | undefined;
+        status?: "healthy" | "partial" | "stale" | "orphaned" | "corrupt" | "in_use" | undefined;
+        version?: string | undefined;
+        scope?: string | undefined;
+        olderThan?: string | undefined;
+    }, {
+        mapping?: string | undefined;
+        jarPath?: string | undefined;
+        projectPath?: string | undefined;
+        entryId?: string | undefined;
+        artifactId?: string | undefined;
+        status?: "healthy" | "partial" | "stale" | "orphaned" | "corrupt" | "in_use" | undefined;
+        version?: string | undefined;
+        scope?: string | undefined;
+        olderThan?: string | undefined;
+    }>>;
+    detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    executionMode: z.ZodDefault<z.ZodEnum<["preview", "apply"]>>;
+};
+export declare const manageCacheSchema: z.ZodObject<{
+    action: z.ZodEnum<["summary", "list", "inspect", "delete", "prune", "rebuild", "verify"]>;
+    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap"]>, "many">>;
+    selector: z.ZodOptional<z.ZodObject<{
+        artifactId: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        jarPath: z.ZodOptional<z.ZodString>;
+        entryId: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<["healthy", "partial", "stale", "orphaned", "corrupt", "in_use"]>>;
+        olderThan: z.ZodOptional<z.ZodString>;
+        mapping: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodString>;
+        projectPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mapping?: string | undefined;
+        jarPath?: string | undefined;
+        projectPath?: string | undefined;
+        entryId?: string | undefined;
+        artifactId?: string | undefined;
+        status?: "healthy" | "partial" | "stale" | "orphaned" | "corrupt" | "in_use" | undefined;
+        version?: string | undefined;
+        scope?: string | undefined;
+        olderThan?: string | undefined;
+    }, {
+        mapping?: string | undefined;
+        jarPath?: string | undefined;
+        projectPath?: string | undefined;
+        entryId?: string | undefined;
+        artifactId?: string | undefined;
+        status?: "healthy" | "partial" | "stale" | "orphaned" | "corrupt" | "in_use" | undefined;
+        version?: string | undefined;
+        scope?: string | undefined;
+        olderThan?: string | undefined;
+    }>>;
+    detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    executionMode: z.ZodDefault<z.ZodEnum<["preview", "apply"]>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    executionMode: "preview" | "apply";
+    action: "list" | "summary" | "inspect" | "verify" | "delete" | "prune" | "rebuild";
+    cursor?: string | undefined;
+    detail?: "full" | "summary" | "standard" | undefined;
+    include?: string[] | undefined;
+    cacheKinds?: ("artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap")[] | undefined;
+    selector?: {
+        mapping?: string | undefined;
+        jarPath?: string | undefined;
+        projectPath?: string | undefined;
+        entryId?: string | undefined;
+        artifactId?: string | undefined;
+        status?: "healthy" | "partial" | "stale" | "orphaned" | "corrupt" | "in_use" | undefined;
+        version?: string | undefined;
+        scope?: string | undefined;
+        olderThan?: string | undefined;
+    } | undefined;
+}, {
+    action: "list" | "summary" | "inspect" | "verify" | "delete" | "prune" | "rebuild";
+    limit?: number | undefined;
+    cursor?: string | undefined;
+    detail?: "full" | "summary" | "standard" | undefined;
+    include?: string[] | undefined;
+    executionMode?: "preview" | "apply" | undefined;
+    cacheKinds?: ("artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap")[] | undefined;
+    selector?: {
+        mapping?: string | undefined;
+        jarPath?: string | undefined;
+        projectPath?: string | undefined;
+        entryId?: string | undefined;
+        artifactId?: string | undefined;
+        status?: "healthy" | "partial" | "stale" | "orphaned" | "corrupt" | "in_use" | undefined;
+        version?: string | undefined;
+        scope?: string | undefined;
+        olderThan?: string | undefined;
+    } | undefined;
+}>;
+export type ManageCacheInput = z.infer<typeof manageCacheSchema>;
+export declare class ManageCacheService {
+    private readonly deps;
+    constructor(deps: {
+        registry: CacheRegistry;
+    });
+    execute(input: ManageCacheInput): Promise<Record<string, unknown> & {
+        warnings?: string[];
+    }>;
+}

package/dist/entry-tools/manage-cache-service.js

@@ -0,0 +1,264 @@
+import { z } from "zod";
+import { PUBLIC_CACHE_KINDS } from "../cache-registry.js";
+import { createError, ERROR_CODES } from "../errors.js";
+import { buildIncludeSchema, detailSchema, executionModeSchema, positiveIntSchema } from "./entry-tool-schema.js";
+import { buildEntryToolResult, createNextAction, createSummarySubject } from "./response-contract.js";
+import { normalizeReadOnlyExecutionMode, requireNonEmptyObject, resolveDetail, resolveInclude } from "./request-normalizers.js";
+const nonEmptyString = z.string().trim().min(1);
+const INCLUDE_GROUPS = ["warnings", "cacheEntries", "paths", "owners", "health", "preview", "timings"];
+export const manageCacheShape = {
+    action: z.enum(["summary", "list", "inspect", "delete", "prune", "rebuild", "verify"]),
+    cacheKinds: z.array(z.enum(PUBLIC_CACHE_KINDS)).optional(),
+    selector: z.object({
+        artifactId: nonEmptyString.optional(),
+        version: nonEmptyString.optional(),
+        jarPath: nonEmptyString.optional(),
+        entryId: nonEmptyString.optional(),
+        status: z.enum(["healthy", "partial", "stale", "orphaned", "corrupt", "in_use"]).optional(),
+        olderThan: nonEmptyString.optional(),
+        mapping: nonEmptyString.optional(),
+        scope: nonEmptyString.optional(),
+        projectPath: nonEmptyString.optional()
+    }).optional(),
+    detail: detailSchema.optional(),
+    include: buildIncludeSchema(INCLUDE_GROUPS),
+    limit: positiveIntSchema.default(50),
+    cursor: nonEmptyString.optional(),
+    executionMode: executionModeSchema.default("preview")
+};
+export const manageCacheSchema = z.object(manageCacheShape);
+export class ManageCacheService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const detail = resolveDetail(input.detail);
+        const include = resolveInclude(input.include);
+        const executionMode = normalizeReadOnlyExecutionMode(input.action, input.executionMode);
+        const cacheKinds = input.cacheKinds?.length ? input.cacheKinds : [...PUBLIC_CACHE_KINDS];
+        const summarySubject = createSummarySubject({
+            action: input.action,
+            cacheKinds,
+            executionMode,
+            selector: input.selector
+        });
+        if (executionMode === "apply" &&
+            (input.action === "delete" || input.action === "prune" || input.action === "rebuild")) {
+            requireNonEmptyObject(input.selector, `${input.action} apply requires a non-empty selector.`);
+        }
+        switch (input.action) {
+            case "summary": {
+                const summary = await this.deps.registry.summarize({
+                    cacheKinds,
+                    selector: input.selector
+                });
+                const hasUnhealthyKinds = Object.values(summary.kinds).some((item) => item && item.status !== "healthy");
+                const entryCount = Object.values(summary.kinds).reduce((total, item) => total + (item?.entryCount ?? 0), 0);
+                const totalBytes = Object.values(summary.kinds).reduce((total, item) => total + (item?.totalBytes ?? 0), 0);
+                return {
+                    ...buildEntryToolResult({
+                        task: "summary",
+                        detail,
+                        include,
+                        summary: {
+                            status: hasUnhealthyKinds ? "partial" : "ok",
+                            headline: `Summarized ${cacheKinds.length} cache kind(s).`,
+                            subject: summarySubject,
+                            counts: {
+                                entries: entryCount,
+                                bytes: totalBytes
+                            }
+                        },
+                        blocks: {
+                            stats: summary.kinds,
+                            operation: {
+                                executionMode
+                            }
+                        },
+                        alwaysBlocks: ["operation"]
+                    }),
+                    warnings: []
+                };
+            }
+            case "list":
+            case "inspect": {
+                const page = input.action === "list"
+                    ? await this.deps.registry.listEntries({
+                        cacheKinds,
+                        selector: input.selector,
+                        limit: input.limit,
+                        cursor: input.cursor
+                    })
+                    : {
+                        entries: await this.deps.registry.inspectEntries({
+                            cacheKinds,
+                            selector: input.selector,
+                            limit: input.limit
+                        }),
+                        nextCursor: undefined
+                    };
+                const hasUnhealthyEntries = page.entries.some((entry) => entry.status !== "healthy");
+                return {
+                    ...buildEntryToolResult({
+                        task: input.action,
+                        detail,
+                        include,
+                        summary: {
+                            status: hasUnhealthyEntries ? "partial" : "ok",
+                            headline: `${input.action === "list" ? "Listed" : "Inspected"} ${page.entries.length} cache entr${page.entries.length === 1 ? "y" : "ies"}.`,
+                            subject: summarySubject,
+                            counts: {
+                                entries: page.entries.length
+                            }
+                        },
+                        blocks: {
+                            cacheEntries: page.entries,
+                            operation: {
+                                executionMode
+                            }
+                        },
+                        alwaysBlocks: ["operation"]
+                    }),
+                    warnings: [],
+                    ...(input.action === "list" && page.nextCursor
+                        ? {
+                            meta: {
+                                pagination: {
+                                    nextCursor: page.nextCursor
+                                }
+                            }
+                        }
+                        : {})
+                };
+            }
+            case "verify": {
+                const output = await this.deps.registry.verifyEntries({
+                    cacheKinds,
+                    selector: input.selector
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "verify",
+                        detail,
+                        include,
+                        summary: {
+                            status: output.unhealthyEntries > 0 ? "partial" : "ok",
+                            headline: `Verified ${output.checkedEntries} cache entr${output.checkedEntries === 1 ? "y" : "ies"}.`,
+                            subject: summarySubject,
+                            counts: {
+                                checkedEntries: output.checkedEntries,
+                                unhealthyEntries: output.unhealthyEntries
+                            }
+                        },
+                        blocks: {
+                            operation: {
+                                executionMode
+                            }
+                        },
+                        alwaysBlocks: ["operation"]
+                    }),
+                    warnings: output.warnings
+                };
+            }
+            case "delete":
+            case "prune": {
+                const output = input.action === "delete"
+                    ? await this.deps.registry.deleteEntries({
+                        cacheKinds,
+                        selector: input.selector,
+                        executionMode
+                    })
+                    : await this.deps.registry.pruneEntries({
+                        cacheKinds,
+                        selector: input.selector,
+                        executionMode
+                    });
+                return {
+                    ...buildEntryToolResult({
+                        task: input.action,
+                        detail,
+                        include,
+                        summary: {
+                            status: output.deletedEntries > 0 && executionMode === "apply" ? "changed" : "unchanged",
+                            headline: `${executionMode === "apply" ? "Applied" : "Previewed"} ${input.action} across ${cacheKinds.length} cache kind(s).`,
+                            subject: summarySubject,
+                            counts: {
+                                deletedEntries: output.deletedEntries,
+                                deletedBytes: output.deletedBytes
+                            },
+                            ...(executionMode === "preview"
+                                ? {
+                                    nextActions: [
+                                        createNextAction("manage-cache", {
+                                            action: input.action,
+                                            cacheKinds,
+                                            executionMode: "apply",
+                                            selector: input.selector
+                                        })
+                                    ]
+                                }
+                                : {})
+                        },
+                        blocks: {
+                            operation: {
+                                executionMode,
+                                deletedEntries: output.deletedEntries,
+                                deletedBytes: output.deletedBytes
+                            }
+                        },
+                        alwaysBlocks: ["operation"]
+                    }),
+                    warnings: output.warnings
+                };
+            }
+            case "rebuild": {
+                const output = await this.deps.registry.rebuildEntries({
+                    cacheKinds,
+                    selector: input.selector,
+                    executionMode
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "rebuild",
+                        detail,
+                        include,
+                        summary: {
+                            status: output.rebuiltEntries > 0 && executionMode === "apply" ? "changed" : "unchanged",
+                            headline: `${executionMode === "apply" ? "Applied" : "Previewed"} rebuild for ${cacheKinds.length} cache kind(s).`,
+                            subject: summarySubject,
+                            counts: {
+                                rebuiltEntries: output.rebuiltEntries
+                            },
+                            ...(executionMode === "preview"
+                                ? {
+                                    nextActions: [
+                                        createNextAction("manage-cache", {
+                                            action: "rebuild",
+                                            cacheKinds,
+                                            executionMode: "apply",
+                                            selector: input.selector
+                                        })
+                                    ]
+                                }
+                                : {})
+                        },
+                        blocks: {
+                            operation: {
+                                executionMode,
+                                rebuiltEntries: output.rebuiltEntries
+                            }
+                        },
+                        alwaysBlocks: ["operation"]
+                    }),
+                    warnings: output.warnings
+                };
+            }
+        }
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Unsupported manage-cache action "${input.action}".`
+        });
+    }
+}
+//# sourceMappingURL=manage-cache-service.js.map

package/dist/entry-tools/request-normalizers.d.ts

@@ -0,0 +1,10 @@
+import type { DetailLevel, NextAction } from "./response-contract.js";
+export declare function resolveDetail(detail: DetailLevel | undefined): DetailLevel;
+export declare function resolveInclude(include: readonly string[] | undefined): string[];
+export declare function normalizeReadOnlyExecutionMode(action: string, executionMode: "preview" | "apply" | undefined): "preview" | "apply";
+export declare function capArray<T>(values: readonly T[], maxItems: number): {
+    items: T[];
+    truncated: boolean;
+};
+export declare function requireNonEmptyObject(selector: Record<string, unknown> | undefined, message: string): Record<string, unknown>;
+export declare function nextActionsOrUndefined(actions: NextAction[]): NextAction[] | undefined;

package/dist/entry-tools/request-normalizers.js

@@ -0,0 +1,36 @@
+import { createError, ERROR_CODES } from "../errors.js";
+import { normalizeIncludeGroups } from "./response-contract.js";
+export function resolveDetail(detail) {
+    return detail ?? "summary";
+}
+export function resolveInclude(include) {
+    return normalizeIncludeGroups(include);
+}
+export function normalizeReadOnlyExecutionMode(action, executionMode) {
+    if (action === "summary" || action === "list" || action === "inspect" || action === "verify") {
+        return "preview";
+    }
+    return executionMode ?? "preview";
+}
+export function capArray(values, maxItems) {
+    if (values.length <= maxItems) {
+        return { items: [...values], truncated: false };
+    }
+    return {
+        items: [...values.slice(0, maxItems)],
+        truncated: true
+    };
+}
+export function requireNonEmptyObject(selector, message) {
+    if (!selector || Object.keys(selector).length === 0) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message
+        });
+    }
+    return selector;
+}
+export function nextActionsOrUndefined(actions) {
+    return actions.length > 0 ? actions : undefined;
+}
+//# sourceMappingURL=request-normalizers.js.map

package/dist/entry-tools/response-contract.d.ts

@@ -0,0 +1,45 @@
+export declare const DETAIL_LEVELS: readonly ["summary", "standard", "full"];
+export type DetailLevel = (typeof DETAIL_LEVELS)[number];
+export declare const CANONICAL_INCLUDE_GROUPS: readonly ["warnings", "provenance", "candidates", "members", "source", "files", "samples", "diff", "issues", "timeline", "matrix", "entries", "workspace", "health", "recovery", "paths", "owners", "preview", "cacheEntries", "timings", "artifact", "classes", "registry"];
+export type IncludeGroup = (typeof CANONICAL_INCLUDE_GROUPS)[number];
+export type SummaryStatus = "ok" | "partial" | "ambiguous" | "not_found" | "invalid" | "blocked" | "changed" | "unchanged";
+export type NextAction = {
+    tool: string;
+    params: Record<string, unknown>;
+};
+export type Summary = {
+    status: SummaryStatus;
+    headline: string;
+    subject?: Record<string, unknown>;
+    counts?: Record<string, number>;
+    nextActions?: NextAction[];
+    notes?: string[];
+};
+export type TruncationMeta = {
+    didTruncate: true;
+    reason: "limit";
+    omittedGroups?: string[];
+    nextActions?: NextAction[];
+};
+export declare function normalizeIncludeGroups(include: readonly string[] | undefined): string[];
+export declare function createNextAction(tool: string, params: Record<string, unknown>): NextAction;
+export declare function createSummarySubject(fields: Record<string, unknown>): Record<string, unknown>;
+export declare function createTruncationMeta(input: {
+    omittedGroups?: string[];
+    nextActions?: NextAction[];
+}): TruncationMeta;
+export declare function buildEntryToolMeta(input: {
+    detail: DetailLevel;
+    include?: readonly string[];
+    warnings?: readonly string[];
+    truncated?: TruncationMeta;
+    pagination?: Record<string, unknown>;
+}): Record<string, unknown>;
+export declare function buildEntryToolResult(input: {
+    task: string;
+    summary: Summary;
+    detail: DetailLevel;
+    include?: readonly string[];
+    blocks?: Record<string, unknown>;
+    alwaysBlocks?: readonly string[];
+}): Record<string, unknown>;

package/dist/entry-tools/response-contract.js

@@ -0,0 +1,99 @@
+export const DETAIL_LEVELS = ["summary", "standard", "full"];
+export const CANONICAL_INCLUDE_GROUPS = [
+    "warnings",
+    "provenance",
+    "candidates",
+    "members",
+    "source",
+    "files",
+    "samples",
+    "diff",
+    "issues",
+    "timeline",
+    "matrix",
+    "entries",
+    "workspace",
+    "health",
+    "recovery",
+    "paths",
+    "owners",
+    "preview",
+    "cacheEntries",
+    "timings",
+    "artifact",
+    "classes",
+    "registry"
+];
+const INCLUDE_ORDER = new Map(CANONICAL_INCLUDE_GROUPS.map((group, index) => [group, index]));
+export function normalizeIncludeGroups(include) {
+    if (!include || include.length === 0) {
+        return [];
+    }
+    const seen = new Set();
+    const deduped = [];
+    for (const group of include) {
+        if (!group || seen.has(group)) {
+            continue;
+        }
+        seen.add(group);
+        deduped.push(group);
+    }
+    deduped.sort((left, right) => {
+        const leftIndex = INCLUDE_ORDER.get(left);
+        const rightIndex = INCLUDE_ORDER.get(right);
+        if (leftIndex == null && rightIndex == null) {
+            return left.localeCompare(right);
+        }
+        if (leftIndex == null) {
+            return 1;
+        }
+        if (rightIndex == null) {
+            return -1;
+        }
+        return leftIndex - rightIndex;
+    });
+    return deduped;
+}
+export function createNextAction(tool, params) {
+    return { tool, params };
+}
+export function createSummarySubject(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+export function createTruncationMeta(input) {
+    return {
+        didTruncate: true,
+        reason: "limit",
+        ...(input.omittedGroups?.length ? { omittedGroups: [...input.omittedGroups] } : {}),
+        ...(input.nextActions?.length ? { nextActions: [...input.nextActions] } : {})
+    };
+}
+export function buildEntryToolMeta(input) {
+    return {
+        warnings: [...(input.warnings ?? [])],
+        detailApplied: input.detail,
+        ...(input.include && input.include.length > 0
+            ? { includeApplied: normalizeIncludeGroups(input.include) }
+            : {}),
+        ...(input.truncated ? { truncated: input.truncated } : {}),
+        ...(input.pagination ? { pagination: input.pagination } : {})
+    };
+}
+export function buildEntryToolResult(input) {
+    const result = {
+        task: input.task,
+        summary: input.summary
+    };
+    const include = new Set(normalizeIncludeGroups(input.include));
+    const alwaysBlocks = new Set(input.alwaysBlocks ?? []);
+    for (const [key, value] of Object.entries(input.blocks ?? {})) {
+        if (value === undefined) {
+            continue;
+        }
+        if (alwaysBlocks.has(key) || input.detail !== "summary" || include.has(key)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=response-contract.js.map