codex-plugin-doctor 1.76.0 → 1.78.0

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

@@ -29,18 +29,18 @@ export function hasMatchingEnvelope(message, requestId) {
     return message.jsonrpc === "2.0" && message.id === requestId
         && Object.hasOwn(message, "result") !== Object.hasOwn(message, "error");
 }
-export function parseToolsResult(message, requestId) {
+export function parseListResult(message, requestId, resultKey) {
     if (!hasMatchingEnvelope(message, requestId)) {
         return null;
     }
-    if (!Object.hasOwn(message, "result") || !isPlainObject(message.result) || !validCacheMetadata(message.result) || !Array.isArray(message.result.tools)) {
+    if (!Object.hasOwn(message, "result") || !isPlainObject(message.result) || !validCacheMetadata(message.result) || !Array.isArray(message.result[resultKey])) {
         return null;
     }
     if (Object.hasOwn(message.result, "nextCursor") && typeof message.result.nextCursor !== "string") {
         return null;
     }
     return {
-        tools: message.result.tools,
+        items: message.result[resultKey],
         cursor: message.result.nextCursor,
         cache: { ttlMs: message.result.ttlMs, cacheScope: message.result.cacheScope }
     };
@@ -70,6 +70,18 @@ export function finalCatalogStatus(findings) {
             ? "warn"
             : "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.`);
+}
+export function modernInvalidFix(list) {
+    return `Return a matching JSON-RPC complete result with valid ${list.capability} 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);
+}
+export function listCursorLoop(list, server) {
+    return catalogFinding("plugin.catalog.cursor.loop", "warn", `The ${server} repeated a ${list.method} cursor.`, "The bounded catalog enumeration cannot determine a complete result set.", "Return each continuation cursor at most once for a single enumeration.");
+}
 function isAuthorizationFinding(discovery) {
     return discovery.findings.some((item) => item.id === "plugin.discovery.authorization.required" || item.id === "plugin.discovery.authorization.rejected");
 }
@@ -124,11 +136,36 @@ export function createMcpToolCatalogInspector() {
         }
     };
 }
-export function serializeToolsListRequest(id, cursor) {
+export const MCP_TOOLS_LIST = {
+    method: "tools/list",
+    capability: "tools",
+    noun: "tool",
+    createInspector() {
+        const inspector = createMcpToolCatalogInspector();
+        return {
+            findings: inspector.findings,
+            items: inspector.tools,
+            get checked() {
+                return inspector.toolsChecked;
+            },
+            addFindings: inspector.addFindings,
+            inspectPage: inspector.inspectPage
+        };
+    }
+};
+function toolCatalogSnapshot(capture) {
+    const { complete, pagesRead, checked, reason } = capture.catalog;
+    return {
+        report: buildMcpToolCatalogReport(capture.discovery, capture.status, { complete, pagesRead, toolsChecked: checked, reason }, capture.enumeration, capture.findings),
+        tools: capture.items,
+        cache: capture.cache
+    };
+}
+export function serializeListRequest(method, id, cursor) {
     return JSON.stringify({
         jsonrpc: "2.0",
         id,
-        method: "tools/list",
+        method,
         params: {
             ...(cursor === undefined ? {} : { cursor }),
             _meta: {
@@ -144,6 +181,10 @@ export async function inspectMcpToolCatalog(rawUrl, options = {}) {
 }
 // Tools and cache metadata are returned only for a complete enumeration.
 export async function captureMcpToolCatalog(rawUrl, options = {}) {
+    return toolCatalogSnapshot(await captureMcpCatalog(rawUrl, MCP_TOOLS_LIST, options));
+}
+// Definitions and cache metadata are returned only for a complete enumeration.
+export async function captureMcpCatalog(rawUrl, list, options = {}) {
     const request = options.request ?? requestBoundedHttp;
     const now = options.now ?? (() => performance.now());
     const deadline = now() + TOTAL_TIMEOUT_MS;
@@ -186,31 +227,31 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             return response;
         }
     });
-    const partial = (report) => ({ report, tools: null, cache: null });
-    const emptyCatalog = { complete: false, pagesRead: 0, toolsChecked: 0, reason: null };
+    const partial = (status, catalog, enumeration, findings) => ({ discovery, status, catalog, enumeration, findings, items: null, cache: null });
+    const emptyCatalog = { complete: false, pagesRead: 0, checked: 0, reason: null };
     if (discovery.status === "blocked") {
         const reason = discovery.findings.some((item) => item.id === "plugin.discovery.credentials.insecure_transport")
             ? "credentials-insecure-transport"
             : "network-blocked";
-        return partial(buildMcpToolCatalogReport(discovery, "blocked", { ...emptyCatalog, reason }, "not-tested", []));
+        return partial("blocked", { ...emptyCatalog, reason }, "not-tested", []);
     }
     if (isAuthorizationFinding(discovery)) {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []));
+        return partial("incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []);
     }
     if (discovery.status === "unsupported") {
-        return partial(buildMcpToolCatalogReport(discovery, "unsupported", { ...emptyCatalog, reason: "discovery-unsupported" }, "not-tested", []));
+        return partial("unsupported", { ...emptyCatalog, reason: "discovery-unsupported" }, "not-tested", []);
     }
     if (discovery.status !== "discovered") {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { ...emptyCatalog, reason: budgetReason ?? "discovery-failed" }, "not-tested", []));
+        return partial("incomplete", { ...emptyCatalog, reason: budgetReason ?? "discovery-failed" }, "not-tested", []);
     }
     const capabilities = discoveryResponse === null ? null : discoverMcpCapabilities(discoveryResponse);
     if (capabilities === null) {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "discovery-response-unavailable" }, "not-tested", []));
+        return partial("incomplete", { ...emptyCatalog, reason: "discovery-response-unavailable" }, "not-tested", []);
     }
-    if (!Object.hasOwn(capabilities, "tools")) {
-        return partial(buildMcpToolCatalogReport(discovery, "not-applicable", emptyCatalog, "not-tested", []));
+    if (!Object.hasOwn(capabilities, list.capability)) {
+        return partial("not-applicable", emptyCatalog, "not-tested", []);
     }
-    const inspector = createMcpToolCatalogInspector();
+    const inspector = list.createInspector();
     const findings = inspector.findings;
     const seenCursors = new Set();
     let pagesRead = 0;
@@ -233,7 +274,7 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             incompleteReason = "total-time-limit";
             break;
         }
-        const requestId = `tools-list-${pagesRead + 1}`;
+        const requestId = `${list.capability}-list-${pagesRead + 1}`;
         let response;
         try {
             response = await requestWithinBudget(rawUrl, {
@@ -241,12 +282,12 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
                 lookup: options.lookup,
                 bearerToken: options.bearerToken,
                 method: "POST",
-                body: serializeToolsListRequest(requestId, cursor),
+                body: serializeListRequest(list.method, requestId, cursor),
                 headers: {
                     Accept: "application/json, text/event-stream",
                     "Content-Type": "application/json",
                     "MCP-Protocol-Version": REQUESTED_VERSION,
-                    "Mcp-Method": "tools/list"
+                    "Mcp-Method": list.method
                 },
                 stopAfter: (received) => findMcpSseResponse(received, requestId) !== null
             });
@@ -273,18 +314,18 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
         const message = parseMcpResponse(response, requestId);
         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([catalogFinding("plugin.catalog.tools_list.method_unsupported", "warn", "The endpoint advertised tools but does not implement tools/list.", "Tool definitions cannot be enumerated from the advertised capability.", "Implement tools/list for the advertised modern MCP tools capability.")]))
-                incompleteReason = "tools-list-method-unsupported";
+            if (addFindings([listMethodUnsupported(list, "endpoint")]))
+                incompleteReason = `${list.capability}-list-method-unsupported`;
             break;
         }
         if (response.statusCode !== 200) {
-            if (addFindings([catalogFinding("plugin.catalog.http_status.invalid", "fail", "The endpoint returned an unexpected tools/list HTTP status.", "The tool catalog cannot be safely enumerated from this response.", "Return HTTP 200 for a tools/list response after authorization succeeds.")]))
+            if (addFindings([catalogFinding("plugin.catalog.http_status.invalid", "fail", `The endpoint returned an unexpected ${list.method} HTTP status.`, `The ${list.noun} catalog cannot be safely enumerated from this response.`, `Return HTTP 200 for a ${list.method} response after authorization succeeds.`)]))
                 incompleteReason = "http-status-invalid";
             break;
         }
-        const page = message === null ? null : parseToolsResult(message, requestId);
+        const page = message === null ? null : parseListResult(message, requestId, list.capability);
         if (page === null) {
-            if (addFindings([catalogFinding("plugin.catalog.response.invalid", "fail", "The endpoint returned an invalid tools/list response.", "The tool catalog cannot be safely enumerated from this response.", "Return a matching JSON-RPC complete result with valid tools and cache metadata.")]))
+            if (addFindings([listResponseInvalid(list, "endpoint", modernInvalidFix(list))]))
                 incompleteReason = "response-invalid";
             break;
         }
@@ -293,32 +334,36 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             ttlMs: Math.min(cache.ttlMs, page.cache.ttlMs),
             cacheScope: cache.cacheScope === "private" ? "private" : page.cache.cacheScope
         };
-        incompleteReason = inspector.inspectPage(page.tools, pagesRead, () => deadline - now() <= 0);
+        incompleteReason = inspector.inspectPage(page.items, pagesRead, () => deadline - now() <= 0);
         if (incompleteReason !== null)
             break;
         if (page.cursor === undefined)
             break;
         if (seenCursors.has(page.cursor)) {
-            if (addFindings([catalogFinding("plugin.catalog.cursor.loop", "warn", "The endpoint repeated a tools/list cursor.", "The bounded catalog enumeration cannot determine a complete result set.", "Return each continuation cursor at most once for a single enumeration.")]))
+            if (addFindings([listCursorLoop(list, "endpoint")]))
                 incompleteReason = "cursor-loop";
             break;
         }
         seenCursors.add(page.cursor);
         cursor = page.cursor;
     }
-    const toolsChecked = inspector.toolsChecked;
+    const checked = inspector.checked;
     if (blocked) {
-        return partial(buildMcpToolCatalogReport(discovery, "blocked", { complete: false, pagesRead, toolsChecked, reason: "network-blocked" }, "incomplete", findings));
+        return partial("blocked", { complete: false, pagesRead, checked, reason: "network-blocked" }, "incomplete", findings);
     }
     if (incompleteReason !== null) {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: incompleteReason }, "incomplete", findings));
+        return partial("incomplete", { complete: false, pagesRead, checked, reason: incompleteReason }, "incomplete", findings);
     }
     if (deadline - now() <= 0) {
-        return partial(buildMcpToolCatalogReport(discovery, "incomplete", { complete: false, pagesRead, toolsChecked, reason: "total-time-limit" }, "incomplete", findings));
+        return partial("incomplete", { complete: false, pagesRead, checked, reason: "total-time-limit" }, "incomplete", findings);
     }
     return {
-        report: buildMcpToolCatalogReport(discovery, finalCatalogStatus(findings), { complete: true, pagesRead, toolsChecked, reason: null }, "complete", findings),
-        tools: inspector.tools,
+        discovery,
+        status: finalCatalogStatus(findings),
+        catalog: { complete: true, pagesRead, checked, reason: null },
+        enumeration: "complete",
+        findings,
+        items: inspector.items,
         cache
     };
 }

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

@@ -39,5 +39,6 @@ export interface McpToolDiffReport {
 export interface McpToolDiffOptions {
     showNames?: boolean;
 }
+export declare function structurallyEqual(left: unknown, right: unknown): boolean;
 export declare function compareMcpToolFiles(beforePath: string, afterPath: string, options?: McpToolDiffOptions): Promise<McpToolDiffReport>;
 export {};

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

@@ -11,7 +11,7 @@ const EXCLUDED_OTHER_FIELDS = new Set(["name", ...FIXED_FIELDS]);
 function isJsonObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function structurallyEqual(left, right) {
+export function structurallyEqual(left, right) {
     const pending = [[left, right]];
     while (pending.length > 0) {
         const [currentLeft, currentRight] = pending.pop();

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

@@ -30,5 +30,25 @@ export interface McpToolFileSnapshot {
     tools: unknown[] | null;
 }
 export declare function isBlockedOfflinePath(filePath: string): boolean;
+export declare function readBoundedRegularFile(filePath: string): Promise<{
+    kind: "content";
+    content: Buffer;
+    bytesRead: number;
+} | {
+    kind: "unavailable";
+    bytesRead: number;
+} | {
+    kind: "too-large";
+    bytesRead: number;
+} | {
+    kind: "changed";
+    bytesRead: number;
+} | {
+    kind: "symlink";
+    bytesRead: number;
+} | {
+    kind: "not-regular";
+    bytesRead: number;
+}>;
 export declare function loadMcpToolFileSnapshot(filePath: string): Promise<McpToolFileSnapshot>;
 export declare function inspectMcpToolFile(filePath: string): Promise<McpToolFileReport>;

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

@@ -90,7 +90,7 @@ function parseToolsResult(value) {
         return null;
     return { tools: value.result.tools, hasNextCursor };
 }
-async function readBoundedRegularFile(filePath) {
+export async function readBoundedRegularFile(filePath) {
     let initial;
     try {
         initial = await lstat(filePath);

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

@@ -1,10 +1,12 @@
 import type { McpToolCatalogCache } from "./mcp-tool-catalog.js";
-export type McpToolResponseSaveResult = {
+export type McpListResponseSaveResult = {
     kind: "saved";
     bytes: number;
-    tools: number;
+    count: number;
 } | {
     kind: "path-blocked" | "not-regular" | "too-large" | "write-failed";
 };
-export declare function serializeMcpToolsListResponse(tools: unknown[], cache: McpToolCatalogCache): string;
-export declare function saveMcpToolsListResponse(filePath: string, tools: unknown[], cache: McpToolCatalogCache): Promise<McpToolResponseSaveResult>;
+type ListKey = "tools" | "prompts";
+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,21 +2,21 @@ 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 response that doctor tools-file and tools-diff accept.
-export function serializeMcpToolsListResponse(tools, cache) {
+// Serializes an enumerated catalog as one complete tools/list or prompts/list response that the offline file and diff commands accept.
+export function serializeMcpListResponse(key, items, cache) {
     return `${JSON.stringify({
         jsonrpc: "2.0",
-        id: "tools-list",
-        result: { resultType: "complete", tools, ttlMs: cache.ttlMs, cacheScope: cache.cacheScope }
+        id: `${key}-list`,
+        result: { resultType: "complete", [key]: items, ttlMs: cache.ttlMs, cacheScope: cache.cacheScope }
     }, null, 2)}\n`;
 }
-export async function saveMcpToolsListResponse(filePath, tools, cache) {
+export async function saveMcpListResponse(filePath, key, items, cache) {
     if (isBlockedOfflinePath(filePath))
         return { kind: "path-blocked" };
     let content;
     let bytes;
     try {
-        content = serializeMcpToolsListResponse(tools, cache);
+        content = serializeMcpListResponse(key, items, cache);
         bytes = Buffer.byteLength(content);
     }
     catch {
@@ -38,7 +38,7 @@ export async function saveMcpToolsListResponse(filePath, tools, cache) {
     // Write beside the target and rename so a failed write never leaves a partial response file.
     const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
     try {
-        // Create with the replaced baseline's permission bits, which may protect private tool definitions.
+        // Create with the replaced baseline's permission bits, which may protect private definitions.
         await writeFile(tempPath, content, { encoding: "utf8", flag: "wx", mode: existingMode ?? 0o666 });
         if (existingMode !== null)
             await chmod(tempPath, existingMode);
@@ -48,5 +48,5 @@ export async function saveMcpToolsListResponse(filePath, tools, cache) {
         await rm(tempPath, { force: true }).catch(() => undefined);
         return { kind: "write-failed" };
     }
-    return { kind: "saved", bytes, tools: tools.length };
+    return { kind: "saved", bytes, count: items.length };
 }

package/dist/core/output-contract.js

@@ -1,5 +1,6 @@
 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_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 = {
@@ -852,6 +853,182 @@ publicSchemaDefinitions.push({
         }
     }
 });
+// The prompt catalog shares 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",
+    command: "codex-plugin-doctor doctor prompts <url> --allow-network --json",
+    required: ["schemaVersion", "scope", "status", "discovery", "catalog", "coverage", "findings"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "prompt-catalog-structure" },
+        // transport, protocol, and execution appear only on reports from `doctor prompts <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", "promptsChecked", "reason"],
+            properties: {
+                complete: { type: "boolean" },
+                pagesRead: { type: "integer", minimum: 0, maximum: 5 },
+                promptsChecked: { type: "integer", minimum: 0, maximum: 500 },
+                reason: { type: ["string", "null"] }
+            },
+            additionalProperties: false
+        },
+        coverage: {
+            type: "object", required: ["discovery", "catalogEnumeration", "definitions", "promptRetrieval", "fullConformance"],
+            properties: {
+                discovery: { enum: ["pass", "fail", "skipped"] },
+                catalogEnumeration: { enum: ["complete", "incomplete", "not-tested"] },
+                definitions: { const: "shape-only" },
+                promptRetrieval: { 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", "promptIndex"],
+                        properties: {
+                            page: { type: "integer", minimum: 1, maximum: 5 },
+                            promptIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            argumentIndex: { type: "integer", minimum: 1 },
+                            relatedPromptIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            relatedArgumentIndex: { type: "integer", minimum: 1 }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                additionalProperties: false
+            }
+        }
+    }
+});
+const promptFileReportDefinition = {
+    id: "doctor.prompts.file.json",
+    command: "codex-plugin-doctor doctor prompts-file <path> --json",
+    required: ["schemaVersion", "scope", "status", "source", "inspection", "coverage", "findings"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "prompt-definitions-file" },
+        status: { enum: ["pass", "warn", "fail", "incomplete", "blocked"] },
+        source: {
+            type: "object", required: ["kind", "format", "bytesRead"],
+            properties: {
+                kind: { const: "file" }, format: { const: "mcp-prompts-list-response" },
+                bytesRead: { type: "integer", minimum: 0, maximum: 1048577 }
+            }, additionalProperties: false
+        },
+        inspection: {
+            type: "object", required: ["complete", "promptsChecked", "hasNextCursor", "reason"],
+            properties: {
+                complete: { type: "boolean" }, promptsChecked: { type: "integer", minimum: 0, maximum: 500 },
+                hasNextCursor: { type: ["boolean", "null"] }, reason: { type: ["string", "null"] }
+            }, additionalProperties: false
+        },
+        coverage: {
+            type: "object", required: ["definitions", "discovery", "serverCatalog", "promptRetrieval", "fullConformance"],
+            properties: {
+                definitions: { const: "shape-only" }, discovery: { const: "not-tested" },
+                serverCatalog: { const: "not-tested" }, promptRetrieval: { 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|prompts_file)\\." },
+                    severity: { enum: ["warn", "fail"] },
+                    message: { type: "string" }, impact: { type: "string" }, suggestedFix: { type: "string" },
+                    location: {
+                        type: "object", required: ["page", "promptIndex"],
+                        properties: {
+                            page: { const: 1 }, promptIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            argumentIndex: { type: "integer", minimum: 1 },
+                            relatedPromptIndex: { type: "integer", minimum: 1, maximum: 500 },
+                            relatedArgumentIndex: { type: "integer", minimum: 1 }
+                        }, additionalProperties: false
+                    }
+                }, additionalProperties: false
+            }
+        }
+    }
+};
+const embeddedPromptFileReportSchema = {
+    type: "object",
+    required: promptFileReportDefinition.required,
+    properties: promptFileReportDefinition.properties,
+    additionalProperties: true
+};
+publicSchemaDefinitions.push(promptFileReportDefinition, {
+    id: "doctor.prompts.diff.json",
+    command: "codex-plugin-doctor doctor prompts-diff --before <path> --after <path> --json",
+    required: ["schemaVersion", "scope", "status", "before", "after", "comparison", "coverage", "changes"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "prompt-definitions-diff" },
+        status: { enum: ["pass", "warn", "incomplete", "blocked"] },
+        before: embeddedPromptFileReportSchema,
+        after: embeddedPromptFileReportSchema,
+        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", "promptRetrieval", "impactClassification"],
+            properties: {
+                comparison: { const: "structural-only" }, definitions: { const: "shape-only" },
+                compatibility: { const: "not-tested" }, serverCatalog: { const: "not-tested" },
+                promptRetrieval: { const: "not-tested" }, impactClassification: { const: "heuristic" }
+            }, additionalProperties: false
+        },
+        changes: {
+            type: "array", maxItems: 1000,
+            items: {
+                type: "object", required: ["kind", "beforePromptIndex", "afterPromptIndex", "fields", "impact", "reasons"],
+                properties: {
+                    kind: { enum: ["added", "removed", "changed"] },
+                    beforePromptIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    afterPromptIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    fields: { type: "array", maxItems: 4, uniqueItems: true, items: { enum: ["arguments", "description", "title", "other"] } },
+                    impact: { enum: ["breaking", "compatible", "unclassified"] },
+                    reasons: { type: "array", maxItems: PROMPT_CHANGE_REASONS.length, uniqueItems: true, items: { enum: [...PROMPT_CHANGE_REASONS] } },
+                    // Only with --show-names.
+                    name: { type: "string" },
+                    locations: {
+                        type: "array", maxItems: MAX_PROMPT_CHANGE_LOCATIONS,
+                        items: {
+                            type: "object", required: ["reason", "argument"],
+                            properties: { reason: { enum: [...PROMPT_CHANGE_REASONS] }, argument: { type: ["string", "null"] } },
+                            additionalProperties: false
+                        }
+                    }
+                }, additionalProperties: false
+            }
+        }
+    }
+});
 function sha256(value) {
     return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }

package/dist/reporting/quote-server-text.d.ts

@@ -1,2 +1,3 @@
 /** Quotes server-supplied text, such as a tool name or a JSON Pointer, as a JSON string that only holds printable characters. */
 export declare function quoteServerText(text: string): string;
+export declare function markdownCodeSpan(text: string): string;

package/dist/reporting/quote-server-text.js

@@ -5,3 +5,16 @@ const UNSAFE_TEXT = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
 export function quoteServerText(text) {
     return JSON.stringify(text).replace(UNSAFE_TEXT, (character) => Array.from({ length: character.length }, (_, index) => `\\u${character.charCodeAt(index).toString(16).padStart(4, "0")}`).join(""));
 }
+// Names and pointers come from the server, so they are quoted and put in a code span, where Markdown,
+// HTML, mentions, and links stay inert; the fence outgrows any backtick run, and pipes are escaped for the table.
+export function markdownCodeSpan(text) {
+    const quoted = quoteServerText(text);
+    let run = 0;
+    let longest = 0;
+    for (const character of quoted) {
+        run = character === "`" ? run + 1 : 0;
+        longest = Math.max(longest, run);
+    }
+    const fence = "`".repeat(longest + 1);
+    return `${fence}${quoted.replace(/\|/gu, "\\|")}${fence}`;
+}

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

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

package/dist/reporting/render-mcp-prompt-catalog-report.js

@@ -0,0 +1,31 @@
+import { describePromptLocation } from "./render-mcp-prompt-file-report.js";
+export function renderMcpPromptCatalogReport(report) {
+    return [
+        "MCP Prompt 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}`,
+        `Prompts checked: ${report.catalog.promptsChecked}`,
+        ...(report.catalog.reason === null ? [] : [`Reason: ${report.catalog.reason}`]),
+        `Enumeration: ${report.coverage.catalogEnumeration}`,
+        `Definition coverage: ${report.coverage.definitions}`,
+        `Prompt retrieval: ${report.coverage.promptRetrieval}`,
+        `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 locator = finding.location ? ` [page ${finding.location.page}, ${describePromptLocation(finding.location)}]` : "";
+            return `${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+        })
+    ].join("\n");
+}

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

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

package/dist/reporting/render-mcp-prompt-diff-markdown.js

@@ -0,0 +1,39 @@
+import { markdownCodeSpan } from "./quote-server-text.js";
+import { describePromptLocation } from "./render-mcp-prompt-file-report.js";
+function count(value) {
+    return value === null || value === undefined ? "not compared" : String(value);
+}
+function promptIndex(value) {
+    return value === null ? "-" : String(value);
+}
+export function renderMcpPromptDiffMarkdown(report) {
+    const comparison = report.comparison;
+    const named = report.changes.some((change) => change.name !== undefined);
+    const lines = [
+        "## MCP Prompt 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 | Prompt | Before prompt | After prompt | Fields | Impact | Reasons |" : "| Change | Before prompt | After prompt | Fields | Impact | Reasons |", named ? "| --- | --- | --- | --- | --- | --- | --- |" : "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind}${named ? ` | ${change.name === undefined ? "-" : markdownCodeSpan(change.name)}` : ""} | ${promptIndex(change.beforePromptIndex)} | ${promptIndex(change.afterPromptIndex)} | ${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.argument === null ? "-" : markdownCodeSpan(location.argument)} |`));
+    if (located.length > 0) {
+        lines.push("", "### Locations", "", "| Prompt | Reason | Argument |", "| --- | --- | --- |", ...located);
+    }
+    const findings = ["before", "after"].flatMap((side) => report[side].findings.map((finding) => {
+        const locator = finding.location ? `${side} ${describePromptLocation(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
+        ? `Prompt and argument names are shown because --show-names was used; descriptions and other values are not reported. Impact labels are ${report.coverage.impactClassification} argument checks, not proof of compatibility.`
+        : `Prompt numbers are one-based positions in the before and after files; names and descriptions are not reported. Impact labels are ${report.coverage.impactClassification} argument checks, not proof of compatibility.`);
+    return lines.join("\n");
+}