codex-plugin-doctor 1.76.0 → 1.77.0

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

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

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

@@ -0,0 +1,48 @@
+import { describePromptLocation } from "./render-mcp-prompt-file-report.js";
+import { quoteServerText } from "./quote-server-text.js";
+export function renderMcpPromptDiffReport(report) {
+    const comparison = report.comparison;
+    return [
+        "Offline MCP Prompt 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}`,
+        `Prompt retrieval: ${report.coverage.promptRetrieval}`,
+        `Impact classification: ${report.coverage.impactClassification}`,
+        "Only the supplied responses are compared. Impact labels are argument 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}; prompts checked: ${source.inspection.promptsChecked}; bytes read: ${source.source.bytesRead}`,
+                ...(source.inspection.reason === null ? [] : [`${label} reason: ${source.inspection.reason}`]),
+                ...source.findings.map((finding) => {
+                    const locator = finding.location ? ` [${side} ${describePromptLocation(finding.location)}]` : "";
+                    return `${label} ${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+                })
+            ];
+        }),
+        ...report.changes.map((change) => {
+            const locations = [
+                ...(change.beforePromptIndex === null ? [] : [`before prompt ${change.beforePromptIndex}`]),
+                ...(change.afterPromptIndex === null ? [] : [`after prompt ${change.afterPromptIndex}`])
+            ];
+            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.argument === null ? "(prompt)" : `argument ${quoteServerText(location.argument)}`}: ${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-prompt-file-report.d.ts

@@ -0,0 +1,5 @@
+import type { PromptCatalogLocation } from "../core/mcp-prompt-definition.js";
+import type { McpPromptFileReport } from "../core/mcp-prompt-file.js";
+/** Describes a finding location by one-based positions only, such as "prompt 2, argument 1, related argument 3". */
+export declare function describePromptLocation(location: PromptCatalogLocation): string;
+export declare function renderMcpPromptFileReport(report: McpPromptFileReport): string;

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

@@ -0,0 +1,33 @@
+/** Describes a finding location by one-based positions only, such as "prompt 2, argument 1, related argument 3". */
+export function describePromptLocation(location) {
+    return [
+        `prompt ${location.promptIndex}`,
+        ...(location.argumentIndex === undefined ? [] : [`argument ${location.argumentIndex}`]),
+        ...(location.relatedPromptIndex === undefined ? [] : [`related prompt ${location.relatedPromptIndex}`]),
+        ...(location.relatedArgumentIndex === undefined ? [] : [`related argument ${location.relatedArgumentIndex}`])
+    ].join(", ");
+}
+export function renderMcpPromptFileReport(report) {
+    return [
+        "Offline MCP Prompt Definitions",
+        "==============================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Source: ${report.source.kind} (${report.source.format})`,
+        `Bytes read: ${report.source.bytesRead}`,
+        `Inspection complete: ${report.inspection.complete}`,
+        `Prompts checked: ${report.inspection.promptsChecked}`,
+        `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}`,
+        `Prompt retrieval: ${report.coverage.promptRetrieval}`,
+        `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 ? ` [${describePromptLocation(finding.location)}]` : "";
+            return `${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+        })
+    ].join("\n");
+}

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

@@ -1,23 +1,10 @@
-import { quoteServerText } from "./quote-server-text.js";
+import { markdownCodeSpan } from "./quote-server-text.js";
 function count(value) {
     return value === null || value === undefined ? "not compared" : String(value);
 }
 function toolIndex(value) {
     return value === null ? "-" : String(value);
 }
-// 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.
-function code(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}`;
-}
 export function renderMcpToolDiffMarkdown(report) {
     const comparison = report.comparison;
     const named = report.changes.some((change) => change.name !== undefined);
@@ -31,9 +18,9 @@ export function renderMcpToolDiffMarkdown(report) {
         `| ${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 | Tool | Before tool | After tool | Fields | Impact | Reasons |" : "| Change | Before tool | After tool | Fields | Impact | Reasons |", named ? "| --- | --- | --- | --- | --- | --- | --- |" : "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind}${named ? ` | ${change.name === undefined ? "-" : code(change.name)}` : ""} | ${toolIndex(change.beforeToolIndex)} | ${toolIndex(change.afterToolIndex)} | ${change.fields.map((field) => `\`${field}\``).join(", ") || "-"} | **${change.impact}** | ${change.reasons.map((reason) => `\`${reason}\``).join(", ") || "-"} |`));
+        lines.push("", "### Changes", "", named ? "| Change | Tool | Before tool | After tool | Fields | Impact | Reasons |" : "| Change | Before tool | After tool | Fields | Impact | Reasons |", named ? "| --- | --- | --- | --- | --- | --- | --- |" : "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind}${named ? ` | ${change.name === undefined ? "-" : markdownCodeSpan(change.name)}` : ""} | ${toolIndex(change.beforeToolIndex)} | ${toolIndex(change.afterToolIndex)} | ${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 ? "-" : code(change.name)} | \`${location.reason}\` | ${location.pointer === "" ? "(tool)" : code(location.pointer)} |`));
+    const located = report.changes.flatMap((change) => (change.locations ?? []).map((location) => `| ${change.name === undefined ? "-" : markdownCodeSpan(change.name)} | \`${location.reason}\` | ${location.pointer === "" ? "(tool)" : markdownCodeSpan(location.pointer)} |`));
     if (located.length > 0) {
         lines.push("", "### Locations", "", "| Tool | Reason | Location |", "| --- | --- | --- |", ...located);
     }

package/dist/run-cli.d.ts

@@ -1,6 +1,9 @@
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { captureMcpToolCatalog, inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
 import { captureStdioMcpToolCatalog } from "./core/mcp-stdio-tool-catalog.js";
+import { captureMcpPromptCatalog, captureStdioMcpPromptCatalog } from "./core/mcp-prompt-catalog.js";
+import { compareMcpPromptFiles } from "./core/mcp-prompt-diff.js";
+import { inspectMcpPromptFile } from "./core/mcp-prompt-file.js";
 import { inspectMcpToolFile } from "./core/mcp-tool-file.js";
 import { compareMcpToolFiles } from "./core/mcp-tool-diff.js";
 import { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport } from "./core/corpus-quality-metrics.js";
@@ -23,6 +26,10 @@ export interface RunCliOptions {
     inspectMcpToolCatalogImpl?: typeof inspectMcpToolCatalog;
     captureMcpToolCatalogImpl?: typeof captureMcpToolCatalog;
     captureStdioMcpToolCatalogImpl?: typeof captureStdioMcpToolCatalog;
+    compareMcpPromptFilesImpl?: typeof compareMcpPromptFiles;
+    inspectMcpPromptFileImpl?: typeof inspectMcpPromptFile;
+    captureMcpPromptCatalogImpl?: typeof captureMcpPromptCatalog;
+    captureStdioMcpPromptCatalogImpl?: typeof captureStdioMcpPromptCatalog;
     discoverMcpServerImpl?: typeof discoverMcpServer;
     terminalContext?: CliTerminalContext;
     runCheckImpl?: typeof runCheck;

package/dist/run-cli.js

@@ -25,13 +25,20 @@ import { isValidBearerToken } from "./core/bounded-http-client.js";
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { captureMcpToolCatalog, inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
 import { captureStdioMcpToolCatalog, resolveMcpStdioServer } from "./core/mcp-stdio-tool-catalog.js";
+import { captureMcpPromptCatalog, captureStdioMcpPromptCatalog } from "./core/mcp-prompt-catalog.js";
+import { compareMcpPromptFiles } from "./core/mcp-prompt-diff.js";
+import { inspectMcpPromptFile } from "./core/mcp-prompt-file.js";
 import { inspectMcpToolFile, isBlockedOfflinePath } from "./core/mcp-tool-file.js";
-import { saveMcpToolsListResponse } from "./core/mcp-tool-response-file.js";
+import { saveMcpListResponse } from "./core/mcp-tool-response-file.js";
 import { compareMcpToolFiles } from "./core/mcp-tool-diff.js";
 import { renderMcpToolDiffMarkdown } from "./reporting/render-mcp-tool-diff-markdown.js";
 import { renderMcpToolDiffReport } from "./reporting/render-mcp-tool-diff-report.js";
 import { renderMcpToolFileReport } from "./reporting/render-mcp-tool-file-report.js";
 import { renderMcpToolCatalogReport } from "./reporting/render-mcp-tool-catalog-report.js";
+import { renderMcpPromptCatalogReport } from "./reporting/render-mcp-prompt-catalog-report.js";
+import { renderMcpPromptDiffMarkdown } from "./reporting/render-mcp-prompt-diff-markdown.js";
+import { renderMcpPromptDiffReport } from "./reporting/render-mcp-prompt-diff-report.js";
+import { renderMcpPromptFileReport } from "./reporting/render-mcp-prompt-file-report.js";
 import { renderMcpDiscoveryReport } from "./reporting/render-mcp-discovery-report.js";
 import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 import { buildExternalValidationCorpusReport, ExternalCorpusManifestError } from "./core/external-validation-corpus.js";
@@ -113,7 +120,12 @@ class CliUsageError extends Error {
 }
 const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json|--markdown] [--fail-on any|breaking] [--show-names]";
 const toolsFileUsage = "Usage: codex-plugin-doctor doctor tools-file <path> [--json]";
+const promptsDiffUsage = "Usage: codex-plugin-doctor doctor prompts-diff --before <path> --after <path> [--json|--markdown] [--fail-on any|breaking] [--show-names]";
+const promptsFileUsage = "Usage: codex-plugin-doctor doctor prompts-file <path> [--json]";
 const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json] [--save-response <path>] [--bearer-token-env <NAME>]\n       codex-plugin-doctor doctor tools <path> --server <name> --runtime [--sandbox docker [--env <NAME>]...] [--require-runtime-approval [--runtime-approval-digest <digest>]] [--json] [--save-response <path>]";
+const promptsUsage = "Usage: codex-plugin-doctor doctor prompts <url> --allow-network [--allow-local-network] [--json] [--save-response <path>] [--bearer-token-env <NAME>]\n       codex-plugin-doctor doctor prompts <path> --server <name> --runtime [--sandbox docker [--env <NAME>]...] [--require-runtime-approval [--runtime-approval-digest <digest>]] [--json] [--save-response <path>]";
+const TOOL_CATALOG_COMMAND = { name: "tools", noun: "Tool", method: "tools/list", usage: toolsUsage };
+const PROMPT_CATALOG_COMMAND = { name: "prompts", noun: "Prompt", method: "prompts/list", usage: promptsUsage };
 const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json] [--bearer-token-env <NAME>]";
 const bearerTokenHelp = "--bearer-token-env reads a bearer token from the named environment variable and sends it only over HTTPS or to an approved loopback target; the token is never printed or saved.";
 const ENVIRONMENT_VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
@@ -165,33 +177,90 @@ function resolveBearerToken(name, env) {
         return { error: `Bearer token environment variable does not hold a valid bearer token: ${name}` };
     return { token };
 }
-async function finishToolCatalogCommand(io, snapshot, json, savePath) {
-    const report = snapshot.report;
-    io.writeStdout(json
-        ? JSON.stringify(report, null, 2)
-        : renderMcpToolCatalogReport(report));
-    const exitCode = report.status === "pass" ? 0
-        : report.status === "incomplete" || report.status === "blocked" ? 2 : 1;
+// Writes the catalog report and, when asked, saves a complete enumeration as one list response.
+async function finishCatalogCommand(io, kind, status, output, items, cache, savePath) {
+    io.writeStdout(output);
+    const exitCode = status === "pass" ? 0
+        : status === "incomplete" || status === "blocked" ? 2 : 1;
     if (savePath === undefined)
         return exitCode;
-    if (snapshot.tools === null || snapshot.cache === null) {
-        io.writeStderr("Tool catalog response was not saved because enumeration did not complete.");
+    if (items === null || cache === null) {
+        io.writeStderr(`${kind.noun} catalog response was not saved because enumeration did not complete.`);
         return 2;
     }
-    const saved = await saveMcpToolsListResponse(savePath, snapshot.tools, snapshot.cache);
+    const saved = await saveMcpListResponse(savePath, kind.name, items, cache);
     if (saved.kind !== "saved") {
         io.writeStderr({
-            "path-blocked": "Tool catalog response was not saved because the path is not a local file path.",
-            "not-regular": "Tool catalog response was not saved because the existing target is not a regular file.",
-            "too-large": "Tool catalog response was not saved because it exceeds the one MiB tools-file limit.",
-            "write-failed": "Tool catalog response could not be written."
+            "path-blocked": `${kind.noun} catalog response was not saved because the path is not a local file path.`,
+            "not-regular": `${kind.noun} catalog response was not saved because the existing target is not a regular file.`,
+            "too-large": `${kind.noun} catalog response was not saved because it exceeds the one MiB ${kind.name}-file limit.`,
+            "write-failed": `${kind.noun} catalog response could not be written.`
         }[saved.kind]);
         return 2;
     }
-    io.writeStderr(`Saved a complete tools/list response with ${saved.tools} tools (${saved.bytes} bytes).`);
+    io.writeStderr(`Saved a complete ${kind.method} response with ${saved.count} ${kind.name} (${saved.bytes} bytes).`);
     return exitCode;
 }
-async function runStdioToolCatalogCommand(targetPath, flags, io, options, env) {
+function finishToolCatalogCommand(io, snapshot, json, savePath) {
+    const report = snapshot.report;
+    return finishCatalogCommand(io, TOOL_CATALOG_COMMAND, report.status, json ? JSON.stringify(report, null, 2) : renderMcpToolCatalogReport(report), snapshot.tools, snapshot.cache, savePath);
+}
+function finishPromptCatalogCommand(io, snapshot, json, savePath) {
+    const report = snapshot.report;
+    return finishCatalogCommand(io, PROMPT_CATALOG_COMMAND, report.status, json ? JSON.stringify(report, null, 2) : renderMcpPromptCatalogReport(report), snapshot.prompts, snapshot.cache, savePath);
+}
+async function runHttpCatalogCommand(url, flags, io, env, kind, run) {
+    const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
+    const switches = [];
+    let savePath;
+    let tokenEnv;
+    let invalid = false;
+    for (let index = 0; index < flags.length; index += 1) {
+        const flag = flags[index];
+        if ((flag === "--save-response" && savePath === undefined) || (flag === "--bearer-token-env" && tokenEnv === undefined)) {
+            const value = flags[index + 1];
+            if (!value || value.startsWith("-")) {
+                invalid = true;
+                break;
+            }
+            if (flag === "--save-response")
+                savePath = value;
+            else
+                tokenEnv = value;
+            index += 1;
+        }
+        else if (allowedFlags.has(flag) && !switches.includes(flag)) {
+            switches.push(flag);
+        }
+        else {
+            invalid = true;
+            break;
+        }
+    }
+    if (invalid) {
+        io.writeStderr(`Invalid or duplicate ${kind.noun.toLowerCase()} catalog arguments. ${kind.usage}`);
+        return 2;
+    }
+    if (!switches.includes("--allow-network")) {
+        io.writeStderr(`doctor ${kind.name} requires explicit --allow-network consent.`);
+        return 2;
+    }
+    if (savePath !== undefined && isBlockedOfflinePath(savePath)) {
+        io.writeStderr(`doctor ${kind.name} --save-response requires a local file path.`);
+        return 2;
+    }
+    const bearer = resolveBearerToken(tokenEnv, env);
+    if ("error" in bearer) {
+        io.writeStderr(bearer.error);
+        return 2;
+    }
+    return run(url, {
+        allowNetwork: true,
+        allowLocalNetwork: switches.includes("--allow-local-network"),
+        ...(bearer.token === undefined ? {} : { bearerToken: bearer.token })
+    }, switches.includes("--json"), savePath);
+}
+async function runStdioCatalogCommand(targetPath, flags, io, env, kind, run) {
     const allowedSwitches = new Set(["--runtime", "--json", "--require-runtime-approval"]);
     const switches = [];
     const values = new Map();
@@ -231,11 +300,11 @@ async function runStdioToolCatalogCommand(targetPath, flags, io, options, env) {
     const approvalDigest = values.get("--runtime-approval-digest");
     const requireApproval = switches.includes("--require-runtime-approval");
     if (invalid || serverName === undefined || (sandbox !== undefined && sandbox !== "docker")) {
-        io.writeStderr(`Invalid or duplicate tool catalog arguments. ${toolsUsage}`);
+        io.writeStderr(`Invalid or duplicate ${kind.noun.toLowerCase()} catalog arguments. ${kind.usage}`);
         return 2;
     }
     if (!switches.includes("--runtime")) {
-        io.writeStderr("doctor tools --server starts a local MCP server and requires explicit --runtime consent.");
+        io.writeStderr(`doctor ${kind.name} --server starts a local MCP server and requires explicit --runtime consent.`);
         return 2;
     }
     if (approvalDigest !== undefined && !requireApproval) {
@@ -262,14 +331,14 @@ async function runStdioToolCatalogCommand(targetPath, flags, io, options, env) {
         }
     }
     if (isBlockedOfflinePath(targetPath)) {
-        io.writeStderr("doctor tools --server requires a local package path.");
+        io.writeStderr(`doctor ${kind.name} --server requires a local package path.`);
         return 2;
     }
     if (savePath !== undefined && isBlockedOfflinePath(savePath)) {
-        io.writeStderr("doctor tools --save-response requires a local file path.");
+        io.writeStderr(`doctor ${kind.name} --save-response requires a local file path.`);
         return 2;
     }
-    const resolved = await resolveMcpStdioServer(targetPath, serverName);
+    const resolved = await resolveMcpStdioServer(targetPath, serverName, kind.name);
     if (!resolved.ok) {
         io.writeStderr(resolved.message);
         return 2;
@@ -290,8 +359,74 @@ async function runStdioToolCatalogCommand(targetPath, flags, io, options, env) {
             return 1;
         }
     }
-    const snapshot = await (options.captureStdioMcpToolCatalogImpl ?? captureStdioMcpToolCatalog)(resolved.server, sandbox !== "docker" ? {} : environment.length > 0 ? { sandbox: "docker", environment } : { sandbox: "docker" });
-    return finishToolCatalogCommand(io, snapshot, switches.includes("--json"), savePath);
+    return run(resolved.server, sandbox !== "docker" ? {} : environment.length > 0 ? { sandbox: "docker", environment } : { sandbox: "docker" }, switches.includes("--json"), savePath);
+}
+// Runs tools-diff or prompts-diff, which share their options and exit codes.
+async function runOfflineDiffCommand(args, io, usage, compare, render) {
+    let beforePath;
+    let afterPath;
+    let format;
+    let failOn;
+    let showNames = false;
+    let invalid = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag === "--show-names" && !showNames) {
+            showNames = true;
+        }
+        else if ((flag === "--json" || flag === "--markdown") && format === undefined) {
+            format = flag === "--json" ? "json" : "markdown";
+        }
+        else if (flag === "--fail-on" && failOn === undefined) {
+            const value = args[index + 1];
+            if (value !== "any" && value !== "breaking") {
+                invalid = true;
+                break;
+            }
+            failOn = value;
+            index += 1;
+        }
+        else if ((flag === "--before" && beforePath === undefined) || (flag === "--after" && afterPath === undefined)) {
+            const value = args[index + 1];
+            if (!value || value.startsWith("-")) {
+                invalid = true;
+                break;
+            }
+            if (flag === "--before")
+                beforePath = value;
+            else
+                afterPath = value;
+            index += 1;
+        }
+        else {
+            invalid = true;
+            break;
+        }
+    }
+    if (invalid || !beforePath || !afterPath) {
+        io.writeStderr(`Invalid comparison arguments. ${usage}`);
+        return 2;
+    }
+    const report = await compare(beforePath, afterPath, showNames);
+    io.writeStdout(format === "json" ? JSON.stringify(report, null, 2) : render(report, format === "markdown"));
+    if (report.status !== "pass" && report.status !== "warn")
+        return 2;
+    if (failOn === "breaking") {
+        return (report.comparison.breaking ?? 0) + (report.comparison.unclassified ?? 0) > 0 ? 1 : 0;
+    }
+    return report.status === "pass" ? 0 : 1;
+}
+// Runs tools-file or prompts-file, which share their options and exit codes.
+async function runOfflineFileCommand(args, io, usage, inspect, render) {
+    const [filePath, ...flags] = args;
+    if (!filePath || filePath.startsWith("-") || flags.some((flag) => flag !== "--json") || flags.length > 1) {
+        io.writeStderr(`Invalid file inspection arguments. ${usage}`);
+        return 2;
+    }
+    const report = await inspect(filePath);
+    io.writeStdout(flags.includes("--json") ? JSON.stringify(report, null, 2) : render(report));
+    return report.status === "pass" ? 0
+        : report.status === "warn" || report.status === "fail" ? 1 : 2;
 }
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
     const index = flags.indexOf("--sandbox");
@@ -377,8 +512,11 @@ function printUsage(io) {
     io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>] [--fail-on <rule-id>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--runtime [--allow-network [--allow-local-network]]] [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>] [--upload]|mcp <path> [--runtime [--allow-network [--allow-local-network]]]|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path] [--tools-diff-server <name> [--baseline <path>] [--sandbox docker]]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
     io.writeStderr(discoveryUsage);
     io.writeStderr(toolsUsage);
+    io.writeStderr(promptsUsage);
     io.writeStderr(toolsFileUsage);
     io.writeStderr(toolsDiffUsage);
+    io.writeStderr(promptsFileUsage);
+    io.writeStderr(promptsDiffUsage);
     io.writeStderr("Registry readiness: codex-plugin-doctor registry check <server.json|directory> [--json] [--output <path>] [--require-registry-readiness]\n"
         + "       codex-plugin-doctor registry inspect <server-name> --allow-network [--json] [--output <path>] [--require-registry-readiness]\n"
         + "Registry publication preflight: codex-plugin-doctor registry preflight <server.json|directory> [--allow-network] [--json] [--output <path>] [--require-publish-ready]");
@@ -1342,10 +1480,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
         (command === "doctor" &&
             (["runtime-plan", "runtime-policy"].includes(maybePath ?? "") ||
                 (maybePath === "release-evidence" && remainingArgs[0] !== "verify") ||
-                (maybePath === "tools" && remainingArgs.includes("--server")))) ||
+                ((maybePath === "tools" || maybePath === "prompts") && remainingArgs.includes("--server")))) ||
         (command === "init-ci" && args.includes("--tools-diff-server"));
     if (args.includes("--sandbox") && !runtimeSandboxSupported) {
-        io.writeStderr("--sandbox is supported only by single-package check, release check, runtime-plan, runtime-policy, release-evidence, doctor tools --server, and init-ci --tools-diff-server.");
+        io.writeStderr("--sandbox is supported only by single-package check, release check, runtime-plan, runtime-policy, release-evidence, doctor tools --server, doctor prompts --server, and init-ci --tools-diff-server.");
         return 2;
     }
     if (command === "--version" || command === "-v" || command === "version") {
@@ -1397,78 +1535,35 @@ export async function runCli(args, io = defaultIo, options = {}) {
 --show-names adds tool names and the JSON Pointer of each reason; reports omit both by default, so keep it out of public output such as pull request comments.`);
                 return 0;
             }
-            let beforePath;
-            let afterPath;
-            let format;
-            let failOn;
-            let showNames = false;
-            let invalid = false;
-            for (let index = 0; index < remainingArgs.length; index += 1) {
-                const flag = remainingArgs[index];
-                if (flag === "--show-names" && !showNames) {
-                    showNames = true;
-                }
-                else if ((flag === "--json" || flag === "--markdown") && format === undefined) {
-                    format = flag === "--json" ? "json" : "markdown";
-                }
-                else if (flag === "--fail-on" && failOn === undefined) {
-                    const value = remainingArgs[index + 1];
-                    if (value !== "any" && value !== "breaking") {
-                        invalid = true;
-                        break;
-                    }
-                    failOn = value;
-                    index += 1;
-                }
-                else if ((flag === "--before" && beforePath === undefined) || (flag === "--after" && afterPath === undefined)) {
-                    const value = remainingArgs[index + 1];
-                    if (!value || value.startsWith("-")) {
-                        invalid = true;
-                        break;
-                    }
-                    if (flag === "--before")
-                        beforePath = value;
-                    else
-                        afterPath = value;
-                    index += 1;
-                }
-                else {
-                    invalid = true;
-                    break;
-                }
-            }
-            if (invalid || !beforePath || !afterPath) {
-                io.writeStderr(`Invalid comparison arguments. ${toolsDiffUsage}`);
-                return 2;
-            }
-            const compare = options.compareMcpToolFilesImpl ?? compareMcpToolFiles;
-            const report = await (showNames ? compare(beforePath, afterPath, { showNames: true }) : compare(beforePath, afterPath));
-            io.writeStdout(format === "json" ? JSON.stringify(report, null, 2)
-                : format === "markdown" ? renderMcpToolDiffMarkdown(report)
-                    : renderMcpToolDiffReport(report));
-            if (report.status !== "pass" && report.status !== "warn")
-                return 2;
-            if (failOn === "breaking") {
-                return (report.comparison.breaking ?? 0) + (report.comparison.unclassified ?? 0) > 0 ? 1 : 0;
+            return runOfflineDiffCommand(remainingArgs, io, toolsDiffUsage, (beforePath, afterPath, showNames) => {
+                const compare = options.compareMcpToolFilesImpl ?? compareMcpToolFiles;
+                return showNames ? compare(beforePath, afterPath, { showNames: true }) : compare(beforePath, afterPath);
+            }, (report, markdown) => markdown ? renderMcpToolDiffMarkdown(report) : renderMcpToolDiffReport(report));
+        }
+        if (maybePath === "prompts-diff") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${promptsDiffUsage}\nCompares two saved MCP prompts/list responses offline. Changes are classified heuristically as breaking, compatible, or unclassified; prompts are not retrieved and compatibility is not tested.\n--fail-on breaking exits 1 only for breaking or unclassified changes (default: any change or input warning).
+--show-names adds prompt names and the argument behind each reason; reports omit both by default, so keep it out of public output such as pull request comments.`);
+                return 0;
             }
-            return report.status === "pass" ? 0 : 1;
+            return runOfflineDiffCommand(remainingArgs, io, promptsDiffUsage, (beforePath, afterPath, showNames) => {
+                const compare = options.compareMcpPromptFilesImpl ?? compareMcpPromptFiles;
+                return showNames ? compare(beforePath, afterPath, { showNames: true }) : compare(beforePath, afterPath);
+            }, (report, markdown) => markdown ? renderMcpPromptDiffMarkdown(report) : renderMcpPromptDiffReport(report));
         }
         if (maybePath === "tools-file") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
                 io.writeStdout(`${toolsFileUsage}\nInspects one saved UTF-8 MCP tools/list response. No server connection or tool execution.`);
                 return 0;
             }
-            const [filePath, ...flags] = remainingArgs;
-            if (!filePath || filePath.startsWith("-") || flags.some((flag) => flag !== "--json") || flags.length > 1) {
-                io.writeStderr(`Invalid file inspection arguments. ${toolsFileUsage}`);
-                return 2;
+            return runOfflineFileCommand(remainingArgs, io, toolsFileUsage, options.inspectMcpToolFileImpl ?? inspectMcpToolFile, renderMcpToolFileReport);
+        }
+        if (maybePath === "prompts-file") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${promptsFileUsage}\nInspects one saved UTF-8 MCP prompts/list response. No server connection or prompt retrieval.`);
+                return 0;
             }
-            const report = await (options.inspectMcpToolFileImpl ?? inspectMcpToolFile)(filePath);
-            io.writeStdout(flags.includes("--json")
-                ? JSON.stringify(report, null, 2)
-                : renderMcpToolFileReport(report));
-            return report.status === "pass" ? 0
-                : report.status === "warn" || report.status === "fail" ? 1 : 2;
+            return runOfflineFileCommand(remainingArgs, io, promptsFileUsage, options.inspectMcpPromptFileImpl ?? inspectMcpPromptFile, renderMcpPromptFileReport);
         }
         if (maybePath === "tools") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
@@ -1481,61 +1576,29 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 return 2;
             }
             if (flags.includes("--server")) {
-                return runStdioToolCatalogCommand(url, flags, io, options, terminalContext.env);
+                return runStdioCatalogCommand(url, flags, io, terminalContext.env, TOOL_CATALOG_COMMAND, async (server, captureOptions, json, savePath) => finishToolCatalogCommand(io, await (options.captureStdioMcpToolCatalogImpl ?? captureStdioMcpToolCatalog)(server, captureOptions), json, savePath));
             }
-            const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
-            const switches = [];
-            let savePath;
-            let tokenEnv;
-            let invalid = false;
-            for (let index = 0; index < flags.length; index += 1) {
-                const flag = flags[index];
-                if ((flag === "--save-response" && savePath === undefined) || (flag === "--bearer-token-env" && tokenEnv === undefined)) {
-                    const value = flags[index + 1];
-                    if (!value || value.startsWith("-")) {
-                        invalid = true;
-                        break;
-                    }
-                    if (flag === "--save-response")
-                        savePath = value;
-                    else
-                        tokenEnv = value;
-                    index += 1;
-                }
-                else if (allowedFlags.has(flag) && !switches.includes(flag)) {
-                    switches.push(flag);
-                }
-                else {
-                    invalid = true;
-                    break;
-                }
-            }
-            if (invalid) {
-                io.writeStderr(`Invalid or duplicate tool catalog arguments. ${toolsUsage}`);
-                return 2;
-            }
-            if (!switches.includes("--allow-network")) {
-                io.writeStderr("doctor tools requires explicit --allow-network consent.");
-                return 2;
+            return runHttpCatalogCommand(url, flags, io, terminalContext.env, TOOL_CATALOG_COMMAND, async (target, catalogOptions, json, savePath) => {
+                const snapshot = savePath === undefined
+                    ? { report: await (options.inspectMcpToolCatalogImpl ?? inspectMcpToolCatalog)(target, catalogOptions), tools: null, cache: null }
+                    : await (options.captureMcpToolCatalogImpl ?? captureMcpToolCatalog)(target, catalogOptions);
+                return finishToolCatalogCommand(io, snapshot, json, savePath);
+            });
+        }
+        if (maybePath === "prompts") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${promptsUsage}\nPrompt catalog structure only; prompts are not retrieved.\n--server starts the named stdio server from the package MCP configuration after explicit --runtime consent and stops it after reading the prompt list.\n${forwardedEnvironmentHelp}\n--save-response writes a complete enumeration as one prompts/list response for doctor prompts-file and prompts-diff; nothing is written when enumeration is incomplete.\n${bearerTokenHelp}`);
+                return 0;
             }
-            if (savePath !== undefined && isBlockedOfflinePath(savePath)) {
-                io.writeStderr("doctor tools --save-response requires a local file path.");
+            const [target, ...flags] = remainingArgs;
+            if (!target || target.startsWith("-")) {
+                io.writeStderr(promptsUsage);
                 return 2;
             }
-            const bearer = resolveBearerToken(tokenEnv, terminalContext.env);
-            if ("error" in bearer) {
-                io.writeStderr(bearer.error);
-                return 2;
+            if (flags.includes("--server")) {
+                return runStdioCatalogCommand(target, flags, io, terminalContext.env, PROMPT_CATALOG_COMMAND, async (server, captureOptions, json, savePath) => finishPromptCatalogCommand(io, await (options.captureStdioMcpPromptCatalogImpl ?? captureStdioMcpPromptCatalog)(server, captureOptions), json, savePath));
             }
-            const catalogOptions = {
-                allowNetwork: true,
-                allowLocalNetwork: switches.includes("--allow-local-network"),
-                ...(bearer.token === undefined ? {} : { bearerToken: bearer.token })
-            };
-            const snapshot = savePath === undefined
-                ? { report: await (options.inspectMcpToolCatalogImpl ?? inspectMcpToolCatalog)(url, catalogOptions), tools: null, cache: null }
-                : await (options.captureMcpToolCatalogImpl ?? captureMcpToolCatalog)(url, catalogOptions);
-            return finishToolCatalogCommand(io, snapshot, switches.includes("--json"), savePath);
+            return runHttpCatalogCommand(target, flags, io, terminalContext.env, PROMPT_CATALOG_COMMAND, async (url, catalogOptions, json, savePath) => finishPromptCatalogCommand(io, await (options.captureMcpPromptCatalogImpl ?? captureMcpPromptCatalog)(url, catalogOptions), json, savePath));
         }
         if (maybePath === "discover") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.76.0",
+  "version": "1.77.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",