codex-plugin-doctor 1.78.0 → 1.79.0

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;

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

@@ -0,0 +1,39 @@
+import { markdownCodeSpan } from "./quote-server-text.js";
+import { describeResourceTemplateLocation } from "./render-mcp-resource-template-file-report.js";
+function count(value) {
+    return value === null || value === undefined ? "not compared" : String(value);
+}
+function templateIndex(value) {
+    return value === null ? "-" : String(value);
+}
+export function renderMcpResourceTemplateDiffMarkdown(report) {
+    const comparison = report.comparison;
+    const named = report.changes.some((change) => change.name !== undefined);
+    const lines = [
+        "## MCP Resource Template Definition Diff",
+        "",
+        `**Status:** \`${report.status}\` · **Comparison complete:** ${comparison.complete ? "yes" : "no"}${comparison.reason === null ? "" : ` · **Reason:** \`${comparison.reason}\``}`,
+        "",
+        "| Added | Removed | Changed | Unchanged | Breaking | Unclassified |",
+        "| --- | --- | --- | --- | --- | --- |",
+        `| ${count(comparison.added)} | ${count(comparison.removed)} | ${count(comparison.changed)} | ${count(comparison.unchanged)} | ${count(comparison.breaking)} | ${count(comparison.unclassified)} |`
+    ];
+    if (report.changes.length > 0) {
+        lines.push("", "### Changes", "", named ? "| Change | Template | Before template | After template | Fields | Impact | Reasons |" : "| Change | Before template | After template | Fields | Impact | Reasons |", named ? "| --- | --- | --- | --- | --- | --- | --- |" : "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind}${named ? ` | ${change.name === undefined ? "-" : markdownCodeSpan(change.name)}` : ""} | ${templateIndex(change.beforeTemplateIndex)} | ${templateIndex(change.afterTemplateIndex)} | ${change.fields.map((field) => `\`${field}\``).join(", ") || "-"} | **${change.impact}** | ${change.reasons.map((reason) => `\`${reason}\``).join(", ") || "-"} |`));
+    }
+    const located = report.changes.flatMap((change) => (change.locations ?? []).map((location) => `| ${change.name === undefined ? "-" : markdownCodeSpan(change.name)} | \`${location.reason}\` | ${location.variable === null ? "-" : markdownCodeSpan(location.variable)} |`));
+    if (located.length > 0) {
+        lines.push("", "### Locations", "", "| Template | Reason | Variable |", "| --- | --- | --- |", ...located);
+    }
+    const findings = ["before", "after"].flatMap((side) => report[side].findings.map((finding) => {
+        const locator = finding.location ? `${side} ${describeResourceTemplateLocation(finding.location)}` : side;
+        return `| ${finding.severity} | \`${finding.id}\` | ${locator} | ${finding.message} |`;
+    }));
+    if (findings.length > 0) {
+        lines.push("", "### Input Findings", "", "| Severity | Finding | Location | Message |", "| --- | --- | --- | --- |", ...findings);
+    }
+    lines.push("", named
+        ? `Template and variable names are shown because --show-names was used; URI templates, descriptions, and other values are not reported. Impact labels are ${report.coverage.impactClassification} URI template checks, not proof of compatibility.`
+        : `Template numbers are one-based positions in the before and after files; names, URI templates, and descriptions are not reported. Impact labels are ${report.coverage.impactClassification} URI template checks, not proof of compatibility.`);
+    return lines.join("\n");
+}

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

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

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

@@ -0,0 +1,48 @@
+import { describeResourceTemplateLocation } from "./render-mcp-resource-template-file-report.js";
+import { quoteServerText } from "./quote-server-text.js";
+export function renderMcpResourceTemplateDiffReport(report) {
+    const comparison = report.comparison;
+    return [
+        "Offline MCP Resource Template Diff",
+        "==================================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Comparison complete: ${comparison.complete}`,
+        ...(comparison.reason === null ? [] : [`Reason: ${comparison.reason}`]),
+        `Added: ${comparison.added ?? "not compared"}`,
+        `Removed: ${comparison.removed ?? "not compared"}`,
+        `Changed: ${comparison.changed ?? "not compared"}`,
+        `Unchanged: ${comparison.unchanged ?? "not compared"}`,
+        `Breaking: ${comparison.breaking ?? "not compared"}`,
+        `Unclassified: ${comparison.unclassified ?? "not compared"}`,
+        `Comparison coverage: ${report.coverage.comparison}`,
+        `Definition coverage: ${report.coverage.definitions}`,
+        `Compatibility: ${report.coverage.compatibility}`,
+        `Server catalog: ${report.coverage.serverCatalog}`,
+        `Resource read: ${report.coverage.resourceRead}`,
+        `Impact classification: ${report.coverage.impactClassification}`,
+        "Only the supplied responses are compared. Impact labels are URI template heuristics: a compatible label or an unchanged result does not establish compatibility.",
+        ...["before", "after"].flatMap((side) => {
+            const source = report[side];
+            const label = side === "before" ? "Before" : "After";
+            return [
+                `${label} input: ${source.status}; templates checked: ${source.inspection.templatesChecked}; bytes read: ${source.source.bytesRead}`,
+                ...(source.inspection.reason === null ? [] : [`${label} reason: ${source.inspection.reason}`]),
+                ...source.findings.map((finding) => {
+                    const locator = finding.location ? ` [${side} ${describeResourceTemplateLocation(finding.location)}]` : "";
+                    return `${label} ${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+                })
+            ];
+        }),
+        ...report.changes.map((change) => {
+            const locations = [
+                ...(change.beforeTemplateIndex === null ? [] : [`before template ${change.beforeTemplateIndex}`]),
+                ...(change.afterTemplateIndex === null ? [] : [`after template ${change.afterTemplateIndex}`])
+            ];
+            const impact = `${change.impact}${change.reasons.length ? ` (${change.reasons.join(", ")})` : ""}`;
+            const name = change.name === undefined ? "" : ` ${quoteServerText(change.name)}`;
+            const at = (change.locations ?? []).map((location) => `\n  At ${location.variable === null ? "(template)" : `variable ${quoteServerText(location.variable)}`}: ${location.reason}`).join("");
+            return `${change.kind.toUpperCase()}${name} [${locations.join(" -> ")}]${change.fields.length ? `: ${change.fields.join(", ")}` : ""}\n  Impact: ${impact}${at}`;
+        })
+    ].join("\n");
+}

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

@@ -0,0 +1,5 @@
+import type { ResourceTemplateCatalogLocation } from "../core/mcp-resource-template-definition.js";
+import type { McpResourceTemplateFileReport } from "../core/mcp-resource-template-file.js";
+/** Describes a finding location by one-based positions only, such as "template 2, related template 1". */
+export declare function describeResourceTemplateLocation(location: ResourceTemplateCatalogLocation): string;
+export declare function renderMcpResourceTemplateFileReport(report: McpResourceTemplateFileReport): string;

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

@@ -0,0 +1,31 @@
+/** Describes a finding location by one-based positions only, such as "template 2, related template 1". */
+export function describeResourceTemplateLocation(location) {
+    return [
+        `template ${location.templateIndex}`,
+        ...(location.relatedTemplateIndex === undefined ? [] : [`related template ${location.relatedTemplateIndex}`])
+    ].join(", ");
+}
+export function renderMcpResourceTemplateFileReport(report) {
+    return [
+        "Offline MCP Resource Template Definitions",
+        "=========================================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Source: ${report.source.kind} (${report.source.format})`,
+        `Bytes read: ${report.source.bytesRead}`,
+        `Inspection complete: ${report.inspection.complete}`,
+        `Templates checked: ${report.inspection.templatesChecked}`,
+        `More pages advertised: ${report.inspection.hasNextCursor ?? "unknown"}`,
+        ...(report.inspection.reason === null ? [] : [`Reason: ${report.inspection.reason}`]),
+        `Definition coverage: ${report.coverage.definitions}`,
+        `Discovery: ${report.coverage.discovery}`,
+        `Server catalog: ${report.coverage.serverCatalog}`,
+        `Resource read: ${report.coverage.resourceRead}`,
+        `Full conformance: ${report.coverage.fullConformance}`,
+        "Only the supplied file was inspected. Its provenance and server completeness are not established.",
+        ...report.findings.map((finding) => {
+            const locator = finding.location ? ` [${describeResourceTemplateLocation(finding.location)}]` : "";
+            return `${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+        })
+    ].join("\n");
+}