codex-plugin-doctor 1.77.0 → 1.79.0

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 {};

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

@@ -0,0 +1,74 @@
+import { parseUriTemplate } from "./mcp-resource-template-definition.js";
+export const RESOURCE_TEMPLATE_CHANGE_REASONS = [
+    "resource-template-removed",
+    "resource-template-uri-changed",
+    "resource-template-variable-removed",
+    "resource-template-variable-added",
+    "resource-template-mime-type-changed",
+    "other-fields-unclassified"
+];
+export const MAX_RESOURCE_TEMPLATE_CHANGE_LOCATIONS = 100;
+const UNCLASSIFIED_REASONS = new Set(["resource-template-mime-type-changed", "other-fields-unclassified"]);
+function classifyUriTemplate(before, after, equal, add) {
+    const beforeTemplate = typeof before === "string" ? parseUriTemplate(before) : null;
+    const afterTemplate = typeof after === "string" ? parseUriTemplate(after) : null;
+    // Inspected definitions always have parseable templates; anything else cannot be compared by variable.
+    if (beforeTemplate === null || afterTemplate === null) {
+        add("resource-template-uri-changed", null);
+        return;
+    }
+    const beforeVariables = new Set(beforeTemplate.variables);
+    const afterVariables = new Set(afterTemplate.variables);
+    let variablesChanged = false;
+    for (const variable of beforeVariables) {
+        if (!afterVariables.has(variable)) {
+            variablesChanged = true;
+            add("resource-template-variable-removed", variable);
+        }
+    }
+    // Clients do not supply a new variable, so the server receives URIs without it.
+    for (const variable of afterVariables) {
+        if (!beforeVariables.has(variable)) {
+            variablesChanged = true;
+            add("resource-template-variable-added", variable);
+        }
+    }
+    // With the same variables, any other difference, such as order, modifiers, or literals, changes the URIs clients build.
+    if (beforeTemplate.skeleton !== afterTemplate.skeleton || (!variablesChanged && !equal(before, after))) {
+        add("resource-template-uri-changed", null);
+    }
+}
+function result(reasons, locations) {
+    const ordered = RESOURCE_TEMPLATE_CHANGE_REASONS.filter((reason) => reasons.has(reason));
+    const impact = ordered.some((reason) => !UNCLASSIFIED_REASONS.has(reason))
+        ? "breaking"
+        : ordered.length > 0 ? "unclassified" : "compatible";
+    return locations === null ? { impact, reasons: ordered } : { impact, reasons: ordered, locations };
+}
+export function classifyRemovedResourceTemplate() {
+    return { impact: "breaking", reasons: ["resource-template-removed"] };
+}
+export function classifyAddedResourceTemplate() {
+    return { impact: "compatible", reasons: [] };
+}
+export function classifyChangedResourceTemplate(before, after, fields, equal, options = {}) {
+    const reasons = new Set();
+    // In comparison order: removed variables in before order, then added variables in after order, then the template itself.
+    const locations = options.locate ? [] : null;
+    const seen = new Set();
+    const add = (reason, variable) => {
+        reasons.add(reason);
+        const key = JSON.stringify([reason, variable]);
+        if (locations !== null && locations.length < MAX_RESOURCE_TEMPLATE_CHANGE_LOCATIONS && !seen.has(key)) {
+            seen.add(key);
+            locations.push({ reason, variable });
+        }
+    };
+    if (fields.includes("uriTemplate"))
+        classifyUriTemplate(before.uriTemplate, after.uriTemplate, equal, add);
+    if (fields.includes("mimeType"))
+        add("resource-template-mime-type-changed", null);
+    if (fields.includes("other"))
+        add("other-fields-unclassified", null);
+    return result(reasons, locations);
+}

package/dist/core/mcp-stdio-tool-catalog.d.ts

@@ -28,7 +28,7 @@ export interface McpStdioToolCatalogOptions {
         shutdownMs?: number;
     };
 }
-export declare function resolveMcpStdioServer(targetPath: string, serverName: string, command?: "tools" | "prompts"): Promise<McpStdioServerResolution>;
+export declare function resolveMcpStdioServer(targetPath: string, serverName: string, command?: "tools" | "prompts" | "resource-templates"): Promise<McpStdioServerResolution>;
 export declare function captureStdioMcpToolCatalog(server: McpStdioServer, options?: McpStdioToolCatalogOptions): Promise<McpToolCatalogSnapshot>;
 export interface McpStdioCatalogCapture<F extends Finding> {
     capture: McpCatalogCapture<F>;

package/dist/core/mcp-stdio-tool-catalog.js

@@ -330,7 +330,7 @@ function stopFinding(reason, docker, noun) {
 function modernEra(list) {
     return {
         request: (id, cursor) => serializeListRequest(list.method, id, cursor),
-        parse: (message, id) => parseListResult(message, id, list.capability),
+        parse: (message, id) => parseListResult(message, id, list.resultKey),
         invalidFix: modernInvalidFix(list)
     };
 }
@@ -344,14 +344,14 @@ function legacyEra(list) {
         }),
         parse: (message, id) => {
             if (!hasMatchingEnvelope(message, id) || !Object.hasOwn(message, "result") || !isPlainObject(message.result)
-                || !Array.isArray(message.result[list.capability])) {
+                || !Array.isArray(message.result[list.resultKey])) {
                 return null;
             }
             if (Object.hasOwn(message.result, "nextCursor") && typeof message.result.nextCursor !== "string")
                 return null;
-            return { items: message.result[list.capability], cursor: message.result.nextCursor, cache: LEGACY_CACHE };
+            return { items: message.result[list.resultKey], cursor: message.result.nextCursor, cache: LEGACY_CACHE };
         },
-        invalidFix: `Return a matching JSON-RPC result with a ${list.capability} array and an optional string nextCursor.`
+        invalidFix: `Return a matching JSON-RPC result with a ${list.resultKey} array and an optional string nextCursor.`
     };
 }
 function legacyInitializeRequest() {
@@ -463,7 +463,7 @@ export async function captureStdioMcpCatalog(server, list, options = {}) {
                 reason = "page-limit";
                 break;
             }
-            const id = `${list.capability}-list-${pagesRead + 1}`;
+            const id = `${list.slug}-list-${pagesRead + 1}`;
             const outcome = await send(id, era.request(id, cursor), requestMs);
             if (outcome.kind !== "message") {
                 if (outcome.kind === "stopped")
@@ -475,7 +475,7 @@ export async function captureStdioMcpCatalog(server, list, options = {}) {
             const message = outcome.message;
             if (hasMatchingEnvelope(message, id) && Object.hasOwn(message, "error") && validJsonRpcError(message.error) && message.error.code === -32601) {
                 if (addFindings([listMethodUnsupported(list, "MCP server")]))
-                    reason = `${list.capability}-list-method-unsupported`;
+                    reason = `${list.slug}-list-method-unsupported`;
                 break;
             }
             const page = era.parse(message, id);

package/dist/core/mcp-tool-catalog.d.ts

@@ -59,14 +59,14 @@ export declare function validJsonRpcError(value: unknown): value is McpJsonObjec
     message: string;
 };
 export declare function hasMatchingEnvelope(message: McpJsonObject, requestId: string): boolean;
-export declare function parseListResult(message: McpJsonObject, requestId: string, resultKey: McpCatalogList<Finding>["capability"]): {
+export declare function parseListResult(message: McpJsonObject, requestId: string, resultKey: McpCatalogList<Finding>["resultKey"]): {
     items: unknown[];
     cursor: string | undefined;
     cache: McpToolCatalogCache;
 } | null;
 export declare function buildMcpToolCatalogReport(discovery: McpDiscoveryReport, status: CatalogStatus, catalog: McpToolCatalogReport["catalog"], catalogEnumeration: EnumerationCoverage, findings: CatalogFinding[]): McpToolCatalogReport;
 export declare function finalCatalogStatus(findings: Finding[]): "pass" | "warn" | "fail";
-type CatalogListName = Pick<McpCatalogList<Finding>, "method" | "capability" | "noun">;
+type CatalogListName = Pick<McpCatalogList<Finding>, "method" | "capability" | "resultKey" | "slug" | "noun">;
 type CatalogServer = "endpoint" | "MCP server";
 export declare function listMethodUnsupported(list: CatalogListName, server: CatalogServer): CatalogFinding;
 export declare function modernInvalidFix(list: CatalogListName): string;
@@ -88,11 +88,13 @@ export interface McpCatalogInspector<F extends Finding> {
     addFindings(items: Finding[]): boolean;
     inspectPage(items: unknown[], page: number, timeExpired: () => boolean): string | null;
 }
-/** What differs between enumerating tool and prompt definitions; discovery, limits, paging, and findings are shared. */
+/** What differs between enumerating tool, prompt, and resource template definitions; discovery, limits, paging, and findings are shared. */
 export interface McpCatalogList<F extends Finding> {
-    method: "tools/list" | "prompts/list";
-    capability: "tools" | "prompts";
-    noun: "tool" | "prompt";
+    method: "tools/list" | "prompts/list" | "resources/templates/list";
+    capability: "tools" | "prompts" | "resources";
+    resultKey: "tools" | "prompts" | "resourceTemplates";
+    slug: "tools" | "prompts" | "resource-templates";
+    noun: "tool" | "prompt" | "resource template";
     createInspector(): McpCatalogInspector<F>;
 }
 export declare const MCP_TOOLS_LIST: McpCatalogList<CatalogFinding>;

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

@@ -71,10 +71,10 @@ export function finalCatalogStatus(findings) {
             : "pass";
 }
 export function listMethodUnsupported(list, server) {
-    return catalogFinding(`plugin.catalog.${list.capability}_list.method_unsupported`, "warn", `The ${server} advertised ${list.capability} but does not implement ${list.method}.`, `${list.noun === "tool" ? "Tool" : "Prompt"} definitions cannot be enumerated from the advertised capability.`, `Implement ${list.method} for the advertised ${server === "endpoint" ? "modern " : ""}MCP ${list.capability} capability.`);
+    return catalogFinding(`plugin.catalog.${list.slug.replaceAll("-", "_")}_list.method_unsupported`, "warn", `The ${server} advertised ${list.capability} but does not implement ${list.method}.`, `${list.noun[0].toUpperCase()}${list.noun.slice(1)} definitions cannot be enumerated from the advertised capability.`, `Implement ${list.method} for the advertised ${server === "endpoint" ? "modern " : ""}MCP ${list.capability} capability.`);
 }
 export function modernInvalidFix(list) {
-    return `Return a matching JSON-RPC complete result with valid ${list.capability} and cache metadata.`;
+    return `Return a matching JSON-RPC complete result with valid ${list.resultKey} and cache metadata.`;
 }
 export function listResponseInvalid(list, server, suggestedFix) {
     return catalogFinding("plugin.catalog.response.invalid", "fail", `The ${server} returned an invalid ${list.method} response.`, `The ${list.noun} catalog cannot be safely enumerated from this response.`, suggestedFix);
@@ -139,6 +139,8 @@ export function createMcpToolCatalogInspector() {
 export const MCP_TOOLS_LIST = {
     method: "tools/list",
     capability: "tools",
+    resultKey: "tools",
+    slug: "tools",
     noun: "tool",
     createInspector() {
         const inspector = createMcpToolCatalogInspector();
@@ -274,7 +276,7 @@ export async function captureMcpCatalog(rawUrl, list, options = {}) {
             incompleteReason = "total-time-limit";
             break;
         }
-        const requestId = `${list.capability}-list-${pagesRead + 1}`;
+        const requestId = `${list.slug}-list-${pagesRead + 1}`;
         let response;
         try {
             response = await requestWithinBudget(rawUrl, {
@@ -315,7 +317,7 @@ export async function captureMcpCatalog(rawUrl, list, options = {}) {
         if (message !== null && hasMatchingEnvelope(message, requestId) && Object.hasOwn(message, "error")
             && validJsonRpcError(message.error) && message.error.code === -32601 && (response.statusCode === 200 || response.statusCode === 404)) {
             if (addFindings([listMethodUnsupported(list, "endpoint")]))
-                incompleteReason = `${list.capability}-list-method-unsupported`;
+                incompleteReason = `${list.slug}-list-method-unsupported`;
             break;
         }
         if (response.statusCode !== 200) {
@@ -323,7 +325,7 @@ export async function captureMcpCatalog(rawUrl, list, options = {}) {
                 incompleteReason = "http-status-invalid";
             break;
         }
-        const page = message === null ? null : parseListResult(message, requestId, list.capability);
+        const page = message === null ? null : parseListResult(message, requestId, list.resultKey);
         if (page === null) {
             if (addFindings([listResponseInvalid(list, "endpoint", modernInvalidFix(list))]))
                 incompleteReason = "response-invalid";

package/dist/core/mcp-tool-response-file.d.ts

@@ -6,7 +6,7 @@ export type McpListResponseSaveResult = {
 } | {
     kind: "path-blocked" | "not-regular" | "too-large" | "write-failed";
 };
-type ListKey = "tools" | "prompts";
+type ListKey = "tools" | "prompts" | "resourceTemplates";
 export declare function serializeMcpListResponse(key: ListKey, items: unknown[], cache: McpToolCatalogCache): string;
 export declare function saveMcpListResponse(filePath: string, key: ListKey, items: unknown[], cache: McpToolCatalogCache): Promise<McpListResponseSaveResult>;
 export {};

package/dist/core/mcp-tool-response-file.js

@@ -2,11 +2,12 @@ import { randomUUID } from "node:crypto";
 import { chmod, lstat, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { isBlockedOfflinePath, MAX_TOOL_FILE_BYTES } from "./mcp-tool-file.js";
-// Serializes an enumerated catalog as one complete tools/list or prompts/list response that the offline file and diff commands accept.
+const RESPONSE_IDS = { tools: "tools-list", prompts: "prompts-list", resourceTemplates: "resource-templates-list" };
+// Serializes an enumerated catalog as one complete list response, keyed by its result array, that the offline file and diff commands accept.
 export function serializeMcpListResponse(key, items, cache) {
     return `${JSON.stringify({
         jsonrpc: "2.0",
-        id: `${key}-list`,
+        id: RESPONSE_IDS[key],
         result: { resultType: "complete", [key]: items, ttlMs: cache.ttlMs, cacheScope: cache.cacheScope }
     }, null, 2)}\n`;
 }

package/dist/core/output-contract.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { packageVersion } from "../version.js";
 import { MAX_PROMPT_CHANGE_LOCATIONS, PROMPT_CHANGE_REASONS } from "./mcp-prompt-impact.js";
+import { MAX_RESOURCE_TEMPLATE_CHANGE_LOCATIONS, RESOURCE_TEMPLATE_CHANGE_REASONS } from "./mcp-resource-template-impact.js";
 import { MAX_TOOL_CHANGE_LOCATIONS, MAX_TOOL_CHANGE_POINTER_LENGTH, TOOL_CHANGE_REASONS } from "./mcp-tool-impact.js";
 import { ruleCatalog } from "../rules/rule-catalog.js";
 const runtimeCapabilityStatusSchema = {
@@ -853,7 +854,7 @@ publicSchemaDefinitions.push({
         }
     }
 });
-// The prompt catalog shares discovery, protocol, and execution evidence with the tool catalog.
+// The prompt and resource template catalogs share discovery, protocol, and execution evidence with the tool catalog.
 const toolCatalogProperties = publicSchemaDefinitions.find((definition) => definition.id === "doctor.tools.json").properties;
 publicSchemaDefinitions.push({
     id: "doctor.prompts.json",
@@ -914,6 +915,63 @@ publicSchemaDefinitions.push({
         }
     }
 });
+publicSchemaDefinitions.push({
+    id: "doctor.resource-templates.json",
+    command: "codex-plugin-doctor doctor resource-templates <url> --allow-network --json",
+    required: ["schemaVersion", "scope", "status", "discovery", "catalog", "coverage", "findings"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "resource-template-catalog-structure" },
+        // transport, protocol, and execution appear only on reports from `doctor resource-templates <path> --server <name> --runtime`.
+        transport: { const: "stdio" },
+        status: toolCatalogProperties.status,
+        protocol: toolCatalogProperties.protocol,
+        execution: toolCatalogProperties.execution,
+        discovery: toolCatalogProperties.discovery,
+        catalog: {
+            type: "object", required: ["complete", "pagesRead", "templatesChecked", "reason"],
+            properties: {
+                complete: { type: "boolean" },
+                pagesRead: { type: "integer", minimum: 0, maximum: 5 },
+                templatesChecked: { type: "integer", minimum: 0, maximum: 500 },
+                reason: { type: ["string", "null"] }
+            },
+            additionalProperties: false
+        },
+        coverage: {
+            type: "object", required: ["discovery", "catalogEnumeration", "definitions", "resourceRead", "fullConformance"],
+            properties: {
+                discovery: { enum: ["pass", "fail", "skipped"] },
+                catalogEnumeration: { enum: ["complete", "incomplete", "not-tested"] },
+                definitions: { const: "shape-only" },
+                resourceRead: { const: "not-tested" },
+                fullConformance: { const: "not-tested" }
+            },
+            additionalProperties: false
+        },
+        findings: {
+            type: "array", maxItems: 100,
+            items: {
+                type: "object", required: ["id", "severity", "message", "impact", "suggestedFix"],
+                properties: {
+                    id: { type: "string", pattern: "^plugin\\.catalog\\." },
+                    severity: { enum: ["warn", "fail"] },
+                    message: { type: "string" }, impact: { type: "string" }, suggestedFix: { type: "string" },
+                    location: {
+                        type: "object", required: ["page", "templateIndex"],
+                        properties: {
+                            page: { type: "integer", minimum: 1, maximum: 5 },
+                            templateIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            relatedTemplateIndex: { type: "integer", minimum: 1, maximum: 500 }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                additionalProperties: false
+            }
+        }
+    }
+});
 const promptFileReportDefinition = {
     id: "doctor.prompts.file.json",
     command: "codex-plugin-doctor doctor prompts-file <path> --json",
@@ -1029,6 +1087,119 @@ publicSchemaDefinitions.push(promptFileReportDefinition, {
         }
     }
 });
+const resourceTemplateFileReportDefinition = {
+    id: "doctor.resource-templates.file.json",
+    command: "codex-plugin-doctor doctor resource-templates-file <path> --json",
+    required: ["schemaVersion", "scope", "status", "source", "inspection", "coverage", "findings"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "resource-template-definitions-file" },
+        status: { enum: ["pass", "warn", "fail", "incomplete", "blocked"] },
+        source: {
+            type: "object", required: ["kind", "format", "bytesRead"],
+            properties: {
+                kind: { const: "file" }, format: { const: "mcp-resource-templates-list-response" },
+                bytesRead: { type: "integer", minimum: 0, maximum: 1048577 }
+            }, additionalProperties: false
+        },
+        inspection: {
+            type: "object", required: ["complete", "templatesChecked", "hasNextCursor", "reason"],
+            properties: {
+                complete: { type: "boolean" }, templatesChecked: { type: "integer", minimum: 0, maximum: 500 },
+                hasNextCursor: { type: ["boolean", "null"] }, reason: { type: ["string", "null"] }
+            }, additionalProperties: false
+        },
+        coverage: {
+            type: "object", required: ["definitions", "discovery", "serverCatalog", "resourceRead", "fullConformance"],
+            properties: {
+                definitions: { const: "shape-only" }, discovery: { const: "not-tested" },
+                serverCatalog: { const: "not-tested" }, resourceRead: { const: "not-tested" },
+                fullConformance: { const: "not-tested" }
+            }, additionalProperties: false
+        },
+        findings: {
+            type: "array", maxItems: 100,
+            items: {
+                type: "object", required: ["id", "severity", "message", "impact", "suggestedFix"],
+                properties: {
+                    id: { type: "string", pattern: "^plugin\\.(catalog|resource_templates_file)\\." },
+                    severity: { enum: ["warn", "fail"] },
+                    message: { type: "string" }, impact: { type: "string" }, suggestedFix: { type: "string" },
+                    location: {
+                        type: "object", required: ["page", "templateIndex"],
+                        properties: {
+                            page: { const: 1 }, templateIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            relatedTemplateIndex: { type: "integer", minimum: 1, maximum: 500 }
+                        }, additionalProperties: false
+                    }
+                }, additionalProperties: false
+            }
+        }
+    }
+};
+const embeddedResourceTemplateFileReportSchema = {
+    type: "object",
+    required: resourceTemplateFileReportDefinition.required,
+    properties: resourceTemplateFileReportDefinition.properties,
+    additionalProperties: true
+};
+publicSchemaDefinitions.push(resourceTemplateFileReportDefinition, {
+    id: "doctor.resource-templates.diff.json",
+    command: "codex-plugin-doctor doctor resource-templates-diff --before <path> --after <path> --json",
+    required: ["schemaVersion", "scope", "status", "before", "after", "comparison", "coverage", "changes"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "resource-template-definitions-diff" },
+        status: { enum: ["pass", "warn", "incomplete", "blocked"] },
+        before: embeddedResourceTemplateFileReportSchema,
+        after: embeddedResourceTemplateFileReportSchema,
+        comparison: {
+            type: "object", required: ["complete", "reason", "added", "removed", "changed", "unchanged", "breaking", "unclassified"],
+            properties: {
+                complete: { type: "boolean" },
+                reason: { enum: [null, "input-blocked", "input-incomplete", "invalid-definitions", "ambiguous-names"] },
+                added: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                removed: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                changed: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                unchanged: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                breaking: { type: ["integer", "null"], minimum: 0, maximum: 1000 },
+                unclassified: { type: ["integer", "null"], minimum: 0, maximum: 1000 }
+            }, additionalProperties: false
+        },
+        coverage: {
+            type: "object", required: ["comparison", "definitions", "compatibility", "serverCatalog", "resourceRead", "impactClassification"],
+            properties: {
+                comparison: { const: "structural-only" }, definitions: { const: "shape-only" },
+                compatibility: { const: "not-tested" }, serverCatalog: { const: "not-tested" },
+                resourceRead: { const: "not-tested" }, impactClassification: { const: "heuristic" }
+            }, additionalProperties: false
+        },
+        changes: {
+            type: "array", maxItems: 1000,
+            items: {
+                type: "object", required: ["kind", "beforeTemplateIndex", "afterTemplateIndex", "fields", "impact", "reasons"],
+                properties: {
+                    kind: { enum: ["added", "removed", "changed"] },
+                    beforeTemplateIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    afterTemplateIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    fields: { type: "array", maxItems: 5, uniqueItems: true, items: { enum: ["uriTemplate", "mimeType", "description", "title", "other"] } },
+                    impact: { enum: ["breaking", "compatible", "unclassified"] },
+                    reasons: { type: "array", maxItems: RESOURCE_TEMPLATE_CHANGE_REASONS.length, uniqueItems: true, items: { enum: [...RESOURCE_TEMPLATE_CHANGE_REASONS] } },
+                    // Only with --show-names; URI templates are never reported.
+                    name: { type: "string" },
+                    locations: {
+                        type: "array", maxItems: MAX_RESOURCE_TEMPLATE_CHANGE_LOCATIONS,
+                        items: {
+                            type: "object", required: ["reason", "variable"],
+                            properties: { reason: { enum: [...RESOURCE_TEMPLATE_CHANGE_REASONS] }, variable: { type: ["string", "null"] } },
+                            additionalProperties: false
+                        }
+                    }
+                }, additionalProperties: false
+            }
+        }
+    }
+});
 function sha256(value) {
     return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }

package/dist/reporting/render-mcp-resource-template-catalog-report.d.ts

@@ -0,0 +1,2 @@
+import type { McpResourceTemplateCatalogReport } from "../core/mcp-resource-template-catalog.js";
+export declare function renderMcpResourceTemplateCatalogReport(report: McpResourceTemplateCatalogReport): string;

package/dist/reporting/render-mcp-resource-template-catalog-report.js

@@ -0,0 +1,33 @@
+export function renderMcpResourceTemplateCatalogReport(report) {
+    return [
+        "MCP Resource Template Catalog",
+        "=============================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        ...(report.transport === "stdio"
+            ? [
+                "Transport: stdio",
+                `Protocol: ${report.protocol?.era ?? "not established"}${report.protocol?.version ? ` (${report.protocol.version})` : ""}`,
+                `Execution: ${report.execution?.backend ?? "not started"}`
+            ]
+            : []),
+        `Discovery: ${report.discovery.status}`,
+        `Catalog complete: ${report.catalog.complete}`,
+        `Pages read: ${report.catalog.pagesRead}`,
+        `Resource templates checked: ${report.catalog.templatesChecked}`,
+        ...(report.catalog.reason === null ? [] : [`Reason: ${report.catalog.reason}`]),
+        `Enumeration: ${report.coverage.catalogEnumeration}`,
+        `Definition coverage: ${report.coverage.definitions}`,
+        `Resource read: ${report.coverage.resourceRead}`,
+        `Full conformance: ${report.coverage.fullConformance}`,
+        "Counts describe inspected content, not a guaranteed server-wide inventory.",
+        ...report.discovery.findings.map((finding) => `${finding.severity.toUpperCase()} ${finding.id}: ${finding.message}\n  ${finding.suggestedFix}`),
+        ...report.findings.map((finding) => {
+            const location = finding.location;
+            const locator = location
+                ? ` [page ${location.page}, template ${location.templateIndex}${location.relatedTemplateIndex === undefined ? "" : `, related template ${location.relatedTemplateIndex}`}]`
+                : "";
+            return `${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+        })
+    ].join("\n");
+}

package/dist/reporting/render-mcp-resource-template-diff-markdown.d.ts

@@ -0,0 +1,2 @@
+import type { McpResourceTemplateDiffReport } from "../core/mcp-resource-template-diff.js";
+export declare function renderMcpResourceTemplateDiffMarkdown(report: McpResourceTemplateDiffReport): string;