codex-plugin-doctor 1.78.0 → 1.79.0

package/README.md

@@ -191,6 +191,19 @@ inputs and comments on pull requests, and
 `init-ci --tools-diff-server <name> --prompts-baseline <path>` writes that workflow.
 See [MCP Prompt Catalog and Diff](docs/guides/mcp-prompts.md).
 
+### MCP Resource Template Catalog and Diff
+
+```bash
+codex-plugin-doctor doctor resource-templates https://mcp.example.com/mcp --allow-network --save-response ./mcp/resource-templates-baseline.json
+codex-plugin-doctor doctor resource-templates-diff --before ./mcp/resource-templates-baseline.json --after ./resource-templates-current.json --fail-on breaking
+```
+
+`doctor resource-templates` reads `resources/templates/list` the same way, without
+reading any resource; `resource-templates-file` inspects a saved list, and
+`resource-templates-diff` labels a removed template, a changed URI template, or an
+added or removed template variable as breaking. Reports never include URI templates,
+and names appear only with `--show-names`. See [MCP Resource Template Catalog and Diff](docs/guides/mcp-resource-templates.md).
+
 ### Remote MCP Readiness
 
 Remote MCP runtime probing is disabled until you explicitly pass `--runtime --allow-network`. Loopback endpoints also require `--allow-local-network`:
@@ -609,9 +622,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.78.0
+      - uses: Esquetta/CodexPluginDoctor@v1.79.0
         with:
-          version: "1.78.0"
+          version: "1.79.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/mcp-prompt-catalog.js

@@ -4,6 +4,8 @@ import { captureMcpCatalog } from "./mcp-tool-catalog.js";
 export const MCP_PROMPTS_LIST = {
     method: "prompts/list",
     capability: "prompts",
+    resultKey: "prompts",
+    slug: "prompts",
     noun: "prompt",
     createInspector() {
         const inspector = createMcpPromptCatalogInspector();

package/dist/core/mcp-resource-template-catalog.d.ts

@@ -0,0 +1,36 @@
+import type { RuntimeExecutionEvidence } from "../domain/types.js";
+import type { McpDiscoveryReport } from "./mcp-discovery.js";
+import { type ResourceTemplateCatalogFinding } from "./mcp-resource-template-definition.js";
+import { type McpStdioServer, type McpStdioToolCatalogOptions } from "./mcp-stdio-tool-catalog.js";
+import { type CatalogStatus, type EnumerationCoverage, type McpCatalogList, type McpToolCatalogCache, type McpToolCatalogOptions, type McpToolCatalogProtocol } from "./mcp-tool-catalog.js";
+export declare const MCP_RESOURCE_TEMPLATES_LIST: McpCatalogList<ResourceTemplateCatalogFinding>;
+export interface McpResourceTemplateCatalogReport {
+    schemaVersion: 1;
+    scope: "resource-template-catalog-structure";
+    transport?: "stdio";
+    status: CatalogStatus;
+    protocol?: McpToolCatalogProtocol;
+    execution?: RuntimeExecutionEvidence | null;
+    discovery: McpDiscoveryReport;
+    catalog: {
+        complete: boolean;
+        pagesRead: number;
+        templatesChecked: number;
+        reason: string | null;
+    };
+    coverage: {
+        discovery: "pass" | "fail" | "skipped";
+        catalogEnumeration: EnumerationCoverage;
+        definitions: "shape-only";
+        resourceRead: "not-tested";
+        fullConformance: "not-tested";
+    };
+    findings: ResourceTemplateCatalogFinding[];
+}
+export interface McpResourceTemplateCatalogSnapshot {
+    report: McpResourceTemplateCatalogReport;
+    templates: unknown[] | null;
+    cache: McpToolCatalogCache | null;
+}
+export declare function captureMcpResourceTemplateCatalog(rawUrl: string, options?: McpToolCatalogOptions): Promise<McpResourceTemplateCatalogSnapshot>;
+export declare function captureStdioMcpResourceTemplateCatalog(server: McpStdioServer, options?: McpStdioToolCatalogOptions): Promise<McpResourceTemplateCatalogSnapshot>;

package/dist/core/mcp-resource-template-catalog.js

@@ -0,0 +1,55 @@
+import { createMcpResourceTemplateCatalogInspector } from "./mcp-resource-template-definition.js";
+import { captureStdioMcpCatalog } from "./mcp-stdio-tool-catalog.js";
+import { captureMcpCatalog } from "./mcp-tool-catalog.js";
+export const MCP_RESOURCE_TEMPLATES_LIST = {
+    method: "resources/templates/list",
+    capability: "resources",
+    resultKey: "resourceTemplates",
+    slug: "resource-templates",
+    noun: "resource template",
+    createInspector() {
+        const inspector = createMcpResourceTemplateCatalogInspector();
+        return {
+            findings: inspector.findings,
+            items: inspector.templates,
+            get checked() {
+                return inspector.templatesChecked;
+            },
+            addFindings: inspector.addFindings,
+            inspectPage: inspector.inspectPage
+        };
+    }
+};
+function templateSnapshot(capture, stdio) {
+    const { complete, pagesRead, checked, reason } = capture.catalog;
+    return {
+        report: {
+            schemaVersion: 1,
+            scope: "resource-template-catalog-structure",
+            ...(stdio === undefined ? {} : { transport: "stdio" }),
+            status: capture.status,
+            ...(stdio === undefined ? {} : { protocol: stdio.protocol, execution: stdio.execution }),
+            discovery: capture.discovery,
+            catalog: { complete, pagesRead, templatesChecked: checked, reason },
+            coverage: {
+                discovery: capture.discovery.coverage.discovery,
+                catalogEnumeration: capture.enumeration,
+                definitions: "shape-only",
+                resourceRead: "not-tested",
+                fullConformance: "not-tested"
+            },
+            findings: capture.findings
+        },
+        templates: capture.items,
+        cache: capture.cache
+    };
+}
+// Templates and cache metadata are returned only for a complete enumeration; no resource is read.
+export async function captureMcpResourceTemplateCatalog(rawUrl, options = {}) {
+    return templateSnapshot(await captureMcpCatalog(rawUrl, MCP_RESOURCE_TEMPLATES_LIST, options));
+}
+// Starts one configured stdio server, reads its resource template list without reading resources, and stops it.
+export async function captureStdioMcpResourceTemplateCatalog(server, options = {}) {
+    const { capture, protocol, execution } = await captureStdioMcpCatalog(server, MCP_RESOURCE_TEMPLATES_LIST, options);
+    return templateSnapshot(capture, { protocol, execution });
+}

package/dist/core/mcp-resource-template-definition.d.ts

@@ -0,0 +1,28 @@
+import type { Finding } from "../domain/types.js";
+export interface ResourceTemplateCatalogLocation {
+    page: number;
+    templateIndex: number;
+    relatedTemplateIndex?: number;
+}
+export interface ResourceTemplateCatalogFinding extends Finding {
+    location?: ResourceTemplateCatalogLocation;
+}
+export declare const MAX_RESOURCE_TEMPLATES = 500;
+export interface ParsedUriTemplate {
+    skeleton: string;
+    variables: string[];
+}
+/** Parses an RFC 6570 URI template; null when it is not one. */
+export declare function parseUriTemplate(template: string): ParsedUriTemplate | null;
+export declare function inspectMcpResourceTemplateDefinition(value: unknown, location: {
+    page: number;
+    templateIndex: number;
+}): ResourceTemplateCatalogFinding[];
+export interface McpResourceTemplateCatalogInspector {
+    readonly findings: ResourceTemplateCatalogFinding[];
+    readonly templates: unknown[];
+    readonly templatesChecked: number;
+    addFindings(items: ResourceTemplateCatalogFinding[]): boolean;
+    inspectPage(pageTemplates: unknown[], page: number, timeExpired: () => boolean): "template-limit" | "finding-limit" | "total-time-limit" | null;
+}
+export declare function createMcpResourceTemplateCatalogInspector(): McpResourceTemplateCatalogInspector;

package/dist/core/mcp-resource-template-definition.js

@@ -0,0 +1,116 @@
+export const MAX_RESOURCE_TEMPLATES = 500;
+const MAX_FINDINGS = 100;
+const DUPLICATE_TEMPLATE_NAME = "plugin.catalog.resource_template.name.duplicate";
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// RFC 6570 expressions: an optional operator, then comma-separated variable names with an optional
+// prefix (":1" to ":9999") or explode ("*") modifier. Names are letters, digits, "_", percent-encoded
+// octets, and single dots between them.
+const OPERATORS = new Set(["+", "#", ".", "/", ";", "?", "&"]);
+const VARSPEC = /^((?:[A-Za-z0-9_]|%[0-9A-Fa-f]{2})(?:\.?(?:[A-Za-z0-9_]|%[0-9A-Fa-f]{2}))*)(?::[1-9][0-9]{0,3}|\*)?$/u;
+// What RFC 6570 excludes from literals: controls, the space, a "%" that does not start a percent-encoded
+// octet, lone surrogates, and the listed ASCII characters. Other Unicode, including non-ASCII spaces, is allowed.
+const INVALID_LITERAL = /[ \u0000-\u001F\u007F-\u009F"'<>\\^`|\uD800-\uDFFF]|%(?![0-9A-Fa-f]{2})/u;
+/** Parses an RFC 6570 URI template; null when it is not one. */
+export function parseUriTemplate(template) {
+    let skeleton = "";
+    const variables = [];
+    let index = 0;
+    while (index < template.length) {
+        const open = template.indexOf("{", index);
+        const literal = template.slice(index, open === -1 ? template.length : open);
+        if (literal.includes("}") || INVALID_LITERAL.test(literal))
+            return null;
+        skeleton += literal;
+        if (open === -1)
+            break;
+        const close = template.indexOf("}", open + 1);
+        if (close === -1)
+            return null;
+        let body = template.slice(open + 1, close);
+        if (body.includes("{"))
+            return null;
+        const operator = OPERATORS.has(body[0] ?? "") ? body[0] : "";
+        body = body.slice(operator.length);
+        if (body === "")
+            return null;
+        for (const varspec of body.split(",")) {
+            const match = VARSPEC.exec(varspec);
+            if (match === null)
+                return null;
+            variables.push(match[1]);
+        }
+        skeleton += `{${operator}}`;
+        index = close + 1;
+    }
+    return { skeleton, variables };
+}
+function finding(id, message, impact, suggestedFix, location) {
+    return { id, severity: id === DUPLICATE_TEMPLATE_NAME ? "warn" : "fail", message, impact, suggestedFix, location };
+}
+export function inspectMcpResourceTemplateDefinition(value, location) {
+    const findings = [];
+    const baseLocation = { page: location.page, templateIndex: location.templateIndex };
+    if (!isJsonObject(value)) {
+        findings.push(finding("plugin.catalog.resource_template.invalid_object", "A catalog resource template entry must be an object.", "The validator cannot inspect a resource template that is not an object.", "Return each resources/templates/list entry as an object.", baseLocation));
+        return findings;
+    }
+    if (typeof value.name !== "string" || value.name === "") {
+        findings.push(finding("plugin.catalog.resource_template.name.invalid", "A catalog resource template name must be a non-empty string.", "Clients cannot identify a resource template without a name.", "Provide a non-empty string name for the resource template.", baseLocation));
+    }
+    if (typeof value.uriTemplate !== "string" || parseUriTemplate(value.uriTemplate) === null) {
+        findings.push(finding("plugin.catalog.resource_template.uri_template.invalid", "A catalog resource template uriTemplate must be an RFC 6570 URI template string.", "Clients cannot build resource URIs from a missing or malformed template.", "Provide uriTemplate as an RFC 6570 URI template, such as file:///{path}.", baseLocation));
+    }
+    for (const [field, id] of [["title", "title"], ["description", "description"], ["mimeType", "mime_type"]]) {
+        if (Object.hasOwn(value, field) && typeof value[field] !== "string") {
+            findings.push(finding(`plugin.catalog.resource_template.${id}.invalid`, `A catalog resource template ${field} must be a string when provided.`, `Clients cannot reliably use a non-string resource template ${field}.`, `Provide a string ${field} or omit the field.`, baseLocation));
+        }
+    }
+    return findings;
+}
+// Shared by saved-file inspection and the HTTP and stdio catalogs so all apply the same template, finding, and duplicate-name rules.
+export function createMcpResourceTemplateCatalogInspector() {
+    const findings = [];
+    const templates = [];
+    const names = new Map();
+    let templatesChecked = 0;
+    const addFindings = (items) => {
+        if (findings.length + items.length > MAX_FINDINGS) {
+            findings.push(...items.slice(0, MAX_FINDINGS - findings.length));
+            return false;
+        }
+        findings.push(...items);
+        return true;
+    };
+    return {
+        findings,
+        templates,
+        get templatesChecked() {
+            return templatesChecked;
+        },
+        addFindings,
+        inspectPage(pageTemplates, page, timeExpired) {
+            for (const template of pageTemplates) {
+                if (templatesChecked >= MAX_RESOURCE_TEMPLATES)
+                    return "template-limit";
+                templatesChecked += 1;
+                templates.push(template);
+                const location = { page, templateIndex: templatesChecked };
+                if (!addFindings(inspectMcpResourceTemplateDefinition(template, location)))
+                    return "finding-limit";
+                if (isJsonObject(template) && typeof template.name === "string" && template.name !== "") {
+                    const previous = names.get(template.name);
+                    if (previous !== undefined && !addFindings([finding(DUPLICATE_TEMPLATE_NAME, "Two enumerated resource templates use the same name.", "Duplicate resource template names can make client selection ambiguous.", "Use a unique name for each resource template.", { ...location, relatedTemplateIndex: previous })])) {
+                        return "finding-limit";
+                    }
+                    if (previous === undefined)
+                        names.set(template.name, templatesChecked);
+                }
+                if (timeExpired())
+                    return "total-time-limit";
+            }
+            return null;
+        }
+    };
+}

package/dist/core/mcp-resource-template-diff.d.ts

@@ -0,0 +1,43 @@
+import { type McpResourceTemplateFileReport } from "./mcp-resource-template-file.js";
+import { type ResourceTemplateChangeImpact, type ResourceTemplateChangeLocation, type ResourceTemplateChangeReason } from "./mcp-resource-template-impact.js";
+type DiffField = "uriTemplate" | "mimeType" | "description" | "title" | "other";
+export interface McpResourceTemplateDiffReport {
+    schemaVersion: 1;
+    scope: "resource-template-definitions-diff";
+    status: "pass" | "warn" | "incomplete" | "blocked";
+    before: McpResourceTemplateFileReport;
+    after: McpResourceTemplateFileReport;
+    comparison: {
+        complete: boolean;
+        reason: "input-blocked" | "input-incomplete" | "invalid-definitions" | "ambiguous-names" | null;
+        added: number | null;
+        removed: number | null;
+        changed: number | null;
+        unchanged: number | null;
+        breaking: number | null;
+        unclassified: number | null;
+    };
+    coverage: {
+        comparison: "structural-only";
+        definitions: "shape-only";
+        compatibility: "not-tested";
+        serverCatalog: "not-tested";
+        resourceRead: "not-tested";
+        impactClassification: "heuristic";
+    };
+    changes: Array<{
+        kind: "added" | "removed" | "changed";
+        beforeTemplateIndex: number | null;
+        afterTemplateIndex: number | null;
+        fields: DiffField[];
+        impact: ResourceTemplateChangeImpact;
+        reasons: ResourceTemplateChangeReason[];
+        name?: string;
+        locations?: ResourceTemplateChangeLocation[];
+    }>;
+}
+export interface McpResourceTemplateDiffOptions {
+    showNames?: boolean;
+}
+export declare function compareMcpResourceTemplateFiles(beforePath: string, afterPath: string, options?: McpResourceTemplateDiffOptions): Promise<McpResourceTemplateDiffReport>;
+export {};

package/dist/core/mcp-resource-template-diff.js

@@ -0,0 +1,136 @@
+import { loadMcpResourceTemplateFileSnapshot } from "./mcp-resource-template-file.js";
+import { classifyAddedResourceTemplate, classifyChangedResourceTemplate, classifyRemovedResourceTemplate } from "./mcp-resource-template-impact.js";
+import { structurallyEqual } from "./mcp-tool-diff.js";
+const FIXED_FIELDS = ["uriTemplate", "mimeType", "description", "title"];
+const EXCLUDED_OTHER_FIELDS = new Set(["name", ...FIXED_FIELDS]);
+const COVERAGE = {
+    comparison: "structural-only",
+    definitions: "shape-only",
+    compatibility: "not-tested",
+    serverCatalog: "not-tested",
+    resourceRead: "not-tested",
+    impactClassification: "heuristic"
+};
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function filteredOther(definition) {
+    const other = Object.create(null);
+    for (const key of Object.keys(definition)) {
+        if (!EXCLUDED_OTHER_FIELDS.has(key))
+            other[key] = definition[key];
+    }
+    return other;
+}
+function changedFields(before, after) {
+    const fields = [];
+    for (const field of FIXED_FIELDS) {
+        if (!structurallyEqual(before[field], after[field]))
+            fields.push(field);
+    }
+    if (!structurallyEqual(filteredOther(before), filteredOther(after)))
+        fields.push("other");
+    return fields;
+}
+function templateDefinitions(templates) {
+    const definitions = new Map();
+    for (let offset = 0; offset < templates.length; offset += 1) {
+        const value = templates[offset];
+        if (!isJsonObject(value) || typeof value.name !== "string" || definitions.has(value.name))
+            return null;
+        definitions.set(value.name, { index: offset + 1, value });
+    }
+    return definitions;
+}
+function incompleteReport(before, after, status, reason) {
+    return {
+        schemaVersion: 1,
+        scope: "resource-template-definitions-diff",
+        status,
+        before,
+        after,
+        comparison: { complete: false, reason, added: null, removed: null, changed: null, unchanged: null, breaking: null, unclassified: null },
+        coverage: { ...COVERAGE },
+        changes: []
+    };
+}
+export async function compareMcpResourceTemplateFiles(beforePath, afterPath, options = {}) {
+    const [beforeSnapshot, afterSnapshot] = await Promise.all([
+        loadMcpResourceTemplateFileSnapshot(beforePath),
+        loadMcpResourceTemplateFileSnapshot(afterPath)
+    ]);
+    const { report: before } = beforeSnapshot;
+    const { report: after } = afterSnapshot;
+    if (before.status === "blocked" || after.status === "blocked") {
+        return incompleteReport(before, after, "blocked", "input-blocked");
+    }
+    if (!before.inspection.complete || !after.inspection.complete) {
+        return incompleteReport(before, after, "incomplete", "input-incomplete");
+    }
+    if (before.status === "fail" || after.status === "fail" || beforeSnapshot.templates === null || afterSnapshot.templates === null) {
+        return incompleteReport(before, after, "incomplete", "invalid-definitions");
+    }
+    const beforeDefinitions = templateDefinitions(beforeSnapshot.templates);
+    const afterDefinitions = templateDefinitions(afterSnapshot.templates);
+    if (beforeDefinitions === null || afterDefinitions === null) {
+        return incompleteReport(before, after, "incomplete", "ambiguous-names");
+    }
+    const named = (name) => (options.showNames === true ? { name } : {});
+    const changes = [];
+    let added = 0;
+    let removed = 0;
+    let changed = 0;
+    let unchanged = 0;
+    for (const [name, beforeDefinition] of beforeDefinitions) {
+        const afterDefinition = afterDefinitions.get(name);
+        if (afterDefinition === undefined) {
+            removed += 1;
+            changes.push({
+                kind: "removed", ...named(name), beforeTemplateIndex: beforeDefinition.index, afterTemplateIndex: null, fields: [], ...classifyRemovedResourceTemplate()
+            });
+            continue;
+        }
+        const fields = changedFields(beforeDefinition.value, afterDefinition.value);
+        if (fields.length === 0) {
+            unchanged += 1;
+        }
+        else {
+            changed += 1;
+            changes.push({
+                kind: "changed",
+                ...named(name),
+                beforeTemplateIndex: beforeDefinition.index,
+                afterTemplateIndex: afterDefinition.index,
+                fields,
+                ...classifyChangedResourceTemplate(beforeDefinition.value, afterDefinition.value, fields, structurallyEqual, { locate: options.showNames === true })
+            });
+        }
+    }
+    for (const [name, afterDefinition] of afterDefinitions) {
+        if (!beforeDefinitions.has(name)) {
+            added += 1;
+            changes.push({
+                kind: "added", ...named(name), beforeTemplateIndex: null, afterTemplateIndex: afterDefinition.index, fields: [], ...classifyAddedResourceTemplate()
+            });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        scope: "resource-template-definitions-diff",
+        status: changes.length === 0 && before.status === "pass" && after.status === "pass" ? "pass" : "warn",
+        before,
+        after,
+        comparison: {
+            complete: true,
+            reason: null,
+            added,
+            removed,
+            changed,
+            unchanged,
+            breaking: changes.filter((change) => change.impact === "breaking").length,
+            unclassified: changes.filter((change) => change.impact === "unclassified").length
+        },
+        coverage: { ...COVERAGE },
+        changes
+    };
+}

package/dist/core/mcp-resource-template-file.d.ts

@@ -0,0 +1,31 @@
+import { type ResourceTemplateCatalogFinding } from "./mcp-resource-template-definition.js";
+export interface McpResourceTemplateFileReport {
+    schemaVersion: 1;
+    scope: "resource-template-definitions-file";
+    status: "pass" | "warn" | "fail" | "incomplete" | "blocked";
+    source: {
+        kind: "file";
+        format: "mcp-resource-templates-list-response";
+        bytesRead: number;
+    };
+    inspection: {
+        complete: boolean;
+        templatesChecked: number;
+        hasNextCursor: boolean | null;
+        reason: string | null;
+    };
+    coverage: {
+        definitions: "shape-only";
+        discovery: "not-tested";
+        serverCatalog: "not-tested";
+        resourceRead: "not-tested";
+        fullConformance: "not-tested";
+    };
+    findings: ResourceTemplateCatalogFinding[];
+}
+export interface McpResourceTemplateFileSnapshot {
+    report: McpResourceTemplateFileReport;
+    templates: unknown[] | null;
+}
+export declare function loadMcpResourceTemplateFileSnapshot(filePath: string): Promise<McpResourceTemplateFileSnapshot>;
+export declare function inspectMcpResourceTemplateFile(filePath: string): Promise<McpResourceTemplateFileReport>;

package/dist/core/mcp-resource-template-file.js

@@ -0,0 +1,118 @@
+import { createMcpResourceTemplateCatalogInspector } from "./mcp-resource-template-definition.js";
+import { isBlockedOfflinePath, readBoundedRegularFile } from "./mcp-tool-file.js";
+function snapshot(report, templates = null) {
+    return { report, templates };
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function report(bytesRead, status, inspection, findings) {
+    return {
+        schemaVersion: 1,
+        scope: "resource-template-definitions-file",
+        status,
+        source: { kind: "file", format: "mcp-resource-templates-list-response", bytesRead },
+        inspection,
+        coverage: {
+            definitions: "shape-only",
+            discovery: "not-tested",
+            serverCatalog: "not-tested",
+            resourceRead: "not-tested",
+            fullConformance: "not-tested"
+        },
+        findings
+    };
+}
+function fileFinding(id, message, impact, suggestedFix) {
+    return { id, severity: "fail", message, impact, suggestedFix };
+}
+function incompleteFileReport(bytesRead, reason, finding) {
+    return report(bytesRead, "incomplete", { complete: false, templatesChecked: 0, hasNextCursor: null, reason }, [finding]);
+}
+function blockedFileReport(reason, finding) {
+    return report(0, "blocked", { complete: false, templatesChecked: 0, hasNextCursor: null, reason }, [finding]);
+}
+function finalStatus(findings) {
+    if (findings.some((finding) => finding.severity === "fail"))
+        return "fail";
+    return findings.some((finding) => finding.severity === "warn") ? "warn" : "pass";
+}
+function parseResourceTemplatesResult(value) {
+    if (!isJsonObject(value)
+        || value.jsonrpc !== "2.0"
+        || !Object.hasOwn(value, "id")
+        || !(typeof value.id === "string" || (typeof value.id === "number" && Number.isFinite(value.id)))
+        || !Object.hasOwn(value, "result")
+        || Object.hasOwn(value, "error")
+        || !isJsonObject(value.result)
+        || value.result.resultType !== "complete"
+        || !Array.isArray(value.result.resourceTemplates)
+        || typeof value.result.ttlMs !== "number"
+        || !Number.isFinite(value.result.ttlMs)
+        || value.result.ttlMs < 0
+        || (value.result.cacheScope !== "public" && value.result.cacheScope !== "private")) {
+        return null;
+    }
+    const hasNextCursor = Object.hasOwn(value.result, "nextCursor");
+    if (hasNextCursor && typeof value.result.nextCursor !== "string")
+        return null;
+    return { templates: value.result.resourceTemplates, hasNextCursor };
+}
+export async function loadMcpResourceTemplateFileSnapshot(filePath) {
+    if (isBlockedOfflinePath(filePath)) {
+        return snapshot(blockedFileReport("offline-path-blocked", fileFinding("plugin.resource_templates_file.path.blocked", "The local resource template definition path is not permitted for offline inspection.", "The offline resource template definition inspection does not access remote or device paths.", "Provide a local regular file path.")));
+    }
+    const file = await readBoundedRegularFile(filePath);
+    if (file.kind === "unavailable") {
+        return snapshot(incompleteFileReport(file.bytesRead, "file-unavailable", fileFinding("plugin.resource_templates_file.file.unavailable", "The local resource template definition file could not be read.", "The offline resource template definition inspection could not start.", "Provide a readable local regular file.")));
+    }
+    if (file.kind === "too-large") {
+        return snapshot(incompleteFileReport(file.bytesRead, "file-size-limit", fileFinding("plugin.resource_templates_file.file.too_large", "The local resource template definition file exceeds the one MiB inspection limit.", "The offline resource template definition inspection cannot safely read this file within its byte limit.", "Provide a resource template definition file no larger than one MiB.")));
+    }
+    if (file.kind === "changed") {
+        return snapshot(incompleteFileReport(file.bytesRead, "file-changed", fileFinding("plugin.resource_templates_file.file.changed", "The local resource template definition file changed during inspection.", "The offline resource template definition inspection cannot rely on an inconsistent file snapshot.", "Retry after the file is stable.")));
+    }
+    if (file.kind === "symlink") {
+        return snapshot(blockedFileReport("final-symlink", fileFinding("plugin.resource_templates_file.file.symlink", "The local resource template definition target is a symbolic link.", "The offline resource template definition inspection does not follow final symbolic links.", "Provide a regular file directly.")));
+    }
+    if (file.kind === "not-regular") {
+        return snapshot(blockedFileReport("non-regular-file", fileFinding("plugin.resource_templates_file.file.not_regular", "The local resource template definition target is not a regular file.", "The offline resource template definition inspection reads only bounded regular files.", "Provide a regular file directly.")));
+    }
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true }).decode(file.content);
+    }
+    catch {
+        return snapshot(incompleteFileReport(file.bytesRead, "invalid-utf8", fileFinding("plugin.resource_templates_file.encoding.invalid", "The local resource template definition file is not valid UTF-8.", "The offline resource template definition inspection cannot parse the file safely.", "Save the resources/templates/list response as UTF-8 JSON.")));
+    }
+    let value;
+    try {
+        value = JSON.parse(decoded);
+    }
+    catch {
+        return snapshot(incompleteFileReport(file.bytesRead, "invalid-json", fileFinding("plugin.resource_templates_file.json.invalid", "The local resource template definition file is not valid JSON.", "The offline resource template definition inspection cannot parse the file safely.", "Provide one UTF-8 JSON-RPC resources/templates/list response.")));
+    }
+    const parsed = parseResourceTemplatesResult(value);
+    if (parsed === null) {
+        return snapshot(incompleteFileReport(file.bytesRead, "response-invalid", fileFinding("plugin.resource_templates_file.response.invalid", "The local JSON value is not a supported complete resources/templates/list response.", "The offline resource template definition inspection cannot identify a valid resource template list.", "Provide one JSON-RPC 2.0 complete resources/templates/list result with valid cache metadata.")));
+    }
+    const inspector = createMcpResourceTemplateCatalogInspector();
+    const reason = inspector.inspectPage(parsed.templates, 1, () => false) ?? (parsed.hasNextCursor ? "more-pages-present" : null);
+    if (reason !== null) {
+        return snapshot(report(file.bytesRead, "incomplete", {
+            complete: false,
+            templatesChecked: inspector.templatesChecked,
+            hasNextCursor: parsed.hasNextCursor,
+            reason
+        }, inspector.findings), parsed.templates);
+    }
+    return snapshot(report(file.bytesRead, finalStatus(inspector.findings), {
+        complete: true,
+        templatesChecked: inspector.templatesChecked,
+        hasNextCursor: false,
+        reason: null
+    }, inspector.findings), parsed.templates);
+}
+export async function inspectMcpResourceTemplateFile(filePath) {
+    return (await loadMcpResourceTemplateFileSnapshot(filePath)).report;
+}

package/dist/core/mcp-resource-template-impact.d.ts

@@ -0,0 +1,21 @@
+type JsonObject = Record<string, unknown>;
+type Equal = (left: unknown, right: unknown) => boolean;
+export type ResourceTemplateChangeImpact = "breaking" | "compatible" | "unclassified";
+export declare const RESOURCE_TEMPLATE_CHANGE_REASONS: readonly ["resource-template-removed", "resource-template-uri-changed", "resource-template-variable-removed", "resource-template-variable-added", "resource-template-mime-type-changed", "other-fields-unclassified"];
+export type ResourceTemplateChangeReason = (typeof RESOURCE_TEMPLATE_CHANGE_REASONS)[number];
+export interface ResourceTemplateChangeLocation {
+    reason: ResourceTemplateChangeReason;
+    variable: string | null;
+}
+export interface ResourceTemplateChangeClassification {
+    impact: ResourceTemplateChangeImpact;
+    reasons: ResourceTemplateChangeReason[];
+    locations?: ResourceTemplateChangeLocation[];
+}
+export declare const MAX_RESOURCE_TEMPLATE_CHANGE_LOCATIONS = 100;
+export declare function classifyRemovedResourceTemplate(): ResourceTemplateChangeClassification;
+export declare function classifyAddedResourceTemplate(): ResourceTemplateChangeClassification;
+export declare function classifyChangedResourceTemplate(before: JsonObject, after: JsonObject, fields: readonly string[], equal: Equal, options?: {
+    locate?: boolean;
+}): ResourceTemplateChangeClassification;
+export {};