codex-plugin-doctor 1.63.0 → 1.65.0

package/dist/core/output-contract.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { packageVersion } from "../version.js";
+import { TOOL_CHANGE_REASONS } from "./mcp-tool-impact.js";
 import { ruleCatalog } from "../rules/rule-catalog.js";
 const runtimeCapabilityStatusSchema = {
     type: "string",
@@ -767,6 +768,60 @@ const publicSchemaDefinitions = [
         }
     }
 ];
+const toolFileReportDefinition = publicSchemaDefinitions.find((definition) => definition.id === "doctor.tools.file.json");
+const embeddedToolFileReportSchema = {
+    type: "object",
+    required: toolFileReportDefinition.required,
+    properties: toolFileReportDefinition.properties,
+    additionalProperties: true
+};
+publicSchemaDefinitions.push({
+    id: "doctor.tools.diff.json",
+    command: "codex-plugin-doctor doctor tools-diff --before <path> --after <path> --json",
+    required: ["schemaVersion", "scope", "status", "before", "after", "comparison", "coverage", "changes"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "tool-definitions-diff" },
+        status: { enum: ["pass", "warn", "incomplete", "blocked"] },
+        before: embeddedToolFileReportSchema,
+        after: embeddedToolFileReportSchema,
+        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", "schema", "compatibility", "serverCatalog", "toolExecution", "impactClassification"],
+            properties: {
+                comparison: { const: "structural-only" }, schema: { const: "root-shape-only" },
+                compatibility: { const: "not-tested" }, serverCatalog: { const: "not-tested" },
+                toolExecution: { const: "not-tested" }, impactClassification: { const: "heuristic" }
+            }, additionalProperties: false
+        },
+        changes: {
+            type: "array", maxItems: 1000,
+            items: {
+                type: "object", required: ["kind", "beforeToolIndex", "afterToolIndex", "fields", "impact", "reasons"],
+                properties: {
+                    kind: { enum: ["added", "removed", "changed"] },
+                    beforeToolIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    afterToolIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    fields: { type: "array", maxItems: 6, uniqueItems: true, items: { enum: ["inputSchema", "outputSchema", "description", "title", "annotations", "other"] } },
+                    impact: { enum: ["breaking", "compatible", "unclassified"] },
+                    reasons: { type: "array", maxItems: TOOL_CHANGE_REASONS.length, uniqueItems: true, items: { enum: [...TOOL_CHANGE_REASONS] } }
+                }, additionalProperties: false
+            }
+        }
+    }
+});
 function sha256(value) {
     return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }

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

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

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

@@ -0,0 +1,45 @@
+export function renderMcpToolDiffReport(report) {
+    const comparison = report.comparison;
+    return [
+        "Offline MCP Tool 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}`,
+        `Schema coverage: ${report.coverage.schema}`,
+        `Compatibility: ${report.coverage.compatibility}`,
+        `Server catalog: ${report.coverage.serverCatalog}`,
+        `Tool execution: ${report.coverage.toolExecution}`,
+        `Impact classification: ${report.coverage.impactClassification}`,
+        "Only the supplied responses are compared. Impact labels are root-level schema 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}; tools checked: ${source.inspection.toolsChecked}; bytes read: ${source.source.bytesRead}`,
+                ...(source.inspection.reason === null ? [] : [`${label} reason: ${source.inspection.reason}`]),
+                ...source.findings.map((finding) => {
+                    const location = finding.location;
+                    const locator = location ? ` [${side} tool ${location.toolIndex}${location.schema ? `, ${location.schema}` : ""}${location.relatedToolIndex ? `, related tool ${location.relatedToolIndex}` : ""}]` : "";
+                    return `${label} ${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+                })
+            ];
+        }),
+        ...report.changes.map((change) => {
+            const locations = [
+                ...(change.beforeToolIndex === null ? [] : [`before tool ${change.beforeToolIndex}`]),
+                ...(change.afterToolIndex === null ? [] : [`after tool ${change.afterToolIndex}`])
+            ];
+            const impact = `${change.impact}${change.reasons.length ? ` (${change.reasons.join(", ")})` : ""}`;
+            return `${change.kind.toUpperCase()} [${locations.join(" -> ")}]${change.fields.length ? `: ${change.fields.join(", ")}` : ""}\n  Impact: ${impact}`;
+        })
+    ].join("\n");
+}

package/dist/run-cli.d.ts

@@ -1,6 +1,7 @@
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.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";
 import { runCheck } from "./index.js";
 import { writeRawDoctorConfig } from "./index.js";
@@ -16,6 +17,7 @@ export interface CliTerminalContext {
     platform?: NodeJS.Platform;
 }
 export interface RunCliOptions {
+    compareMcpToolFilesImpl?: typeof compareMcpToolFiles;
     inspectMcpToolFileImpl?: typeof inspectMcpToolFile;
     inspectMcpToolCatalogImpl?: typeof inspectMcpToolCatalog;
     discoverMcpServerImpl?: typeof discoverMcpServer;

package/dist/run-cli.js

@@ -24,6 +24,8 @@ import { buildSubmissionPreflight } from "./core/submission-preflight.js";
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
 import { inspectMcpToolFile } from "./core/mcp-tool-file.js";
+import { compareMcpToolFiles } from "./core/mcp-tool-diff.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 { renderMcpDiscoveryReport } from "./reporting/render-mcp-discovery-report.js";
@@ -105,6 +107,7 @@ function writeExactStdout(io, message) {
 }
 class CliUsageError extends Error {
 }
+const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json] [--fail-on any|breaking]";
 const toolsFileUsage = "Usage: codex-plugin-doctor doctor tools-file <path> [--json]";
 const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json]";
 const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json]";
@@ -193,6 +196,7 @@ function printUsage(io) {
     io.writeStderr(discoveryUsage);
     io.writeStderr(toolsUsage);
     io.writeStderr(toolsFileUsage);
+    io.writeStderr(toolsDiffUsage);
     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]");
@@ -1203,6 +1207,60 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return 0;
     }
     if (command === "doctor") {
+        if (maybePath === "tools-diff") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${toolsDiffUsage}\nCompares two saved MCP tools/list responses offline. Changes are classified heuristically as breaking, compatible, or unclassified; compatibility is not tested.\n--fail-on breaking exits 1 only for breaking or unclassified changes (default: any change or input warning).`);
+                return 0;
+            }
+            let beforePath;
+            let afterPath;
+            let json = false;
+            let failOn;
+            let invalid = false;
+            for (let index = 0; index < remainingArgs.length; index += 1) {
+                const flag = remainingArgs[index];
+                if (flag === "--json" && !json) {
+                    json = true;
+                }
+                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 report = await (options.compareMcpToolFilesImpl ?? compareMcpToolFiles)(beforePath, afterPath);
+            io.writeStdout(json ? JSON.stringify(report, null, 2) : 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 report.status === "pass" ? 0 : 1;
+        }
         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.`);

package/examples/README.md

@@ -1,94 +1,94 @@
-# Examples
-
-This folder contains manual example packs for local testing. Unlike `tests/fixtures`, these examples are meant for humans to run directly against the CLI.
-
-## Example Packs
-
-Use the smallest example that matches what you need to prove:
-
-- `codex-doctor-starter` for static manifest and skill validation.
-- `codex-doctor-runtime` for full MCP runtime probing and compatibility scoring.
-- `codex-doctor-risky` for security finding output.
-- `codex-doctor-generic-mcp` for MCP-only packages without a Codex plugin manifest.
-
-### `codex-doctor-starter`
-
-Minimal valid Codex plugin package with one skill and no runtime MCP server.
-
-Expected result:
-
-- static validation passes
-- no runtime probing needed
-
-Command:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-starter
-```
-
-### `codex-doctor-runtime`
-
-Valid Codex plugin package with:
-
-- skill metadata
-- `.mcp.json`
-- mock MCP stdio server
-- `tools/list`
-- `tools/call`
-- `resources/list`
-- `resources/read`
-- `resources/templates/list`
-- `prompts/list`
-- `prompts/get`
-
-Expected result:
-
-- static validation passes
-- runtime validation passes
-- runtime scorecard shows all supported runtime capabilities as `pass`
-
-Command:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
-```
-
-### `codex-doctor-risky`
-
-Intentionally flawed package for showing failure output.
-
-Expected result:
-
-- security finding for hard-coded secret
-
-Command:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-risky --ascii
-```
-
-### `codex-doctor-generic-mcp`
-
-Generic MCP package with a `.mcp.json` file and no Codex plugin manifest.
-
-Expected result:
-
-- `codex-plugin-doctor mcp` passes generic MCP static health checks
-- `codex-plugin-doctor check` still reports the missing Codex plugin manifest
-
-Command:
-
-```bash
-codex-plugin-doctor mcp examples/codex-doctor-generic-mcp
-```
-
-## Suggested Local Flow
-
-```bash
-npm install
-npm run build
-npm link
-codex-plugin-doctor check examples/codex-doctor-starter
-codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
-codex-plugin-doctor check examples/codex-doctor-risky --ascii
-```
+# Examples
+
+This folder contains manual example packs for local testing. Unlike `tests/fixtures`, these examples are meant for humans to run directly against the CLI.
+
+## Example Packs
+
+Use the smallest example that matches what you need to prove:
+
+- `codex-doctor-starter` for static manifest and skill validation.
+- `codex-doctor-runtime` for full MCP runtime probing and compatibility scoring.
+- `codex-doctor-risky` for security finding output.
+- `codex-doctor-generic-mcp` for MCP-only packages without a Codex plugin manifest.
+
+### `codex-doctor-starter`
+
+Minimal valid Codex plugin package with one skill and no runtime MCP server.
+
+Expected result:
+
+- static validation passes
+- no runtime probing needed
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-starter
+```
+
+### `codex-doctor-runtime`
+
+Valid Codex plugin package with:
+
+- skill metadata
+- `.mcp.json`
+- mock MCP stdio server
+- `tools/list`
+- `tools/call`
+- `resources/list`
+- `resources/read`
+- `resources/templates/list`
+- `prompts/list`
+- `prompts/get`
+
+Expected result:
+
+- static validation passes
+- runtime validation passes
+- runtime scorecard shows all supported runtime capabilities as `pass`
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
+```
+
+### `codex-doctor-risky`
+
+Intentionally flawed package for showing failure output.
+
+Expected result:
+
+- security finding for hard-coded secret
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-risky --ascii
+```
+
+### `codex-doctor-generic-mcp`
+
+Generic MCP package with a `.mcp.json` file and no Codex plugin manifest.
+
+Expected result:
+
+- `codex-plugin-doctor mcp` passes generic MCP static health checks
+- `codex-plugin-doctor check` still reports the missing Codex plugin manifest
+
+Command:
+
+```bash
+codex-plugin-doctor mcp examples/codex-doctor-generic-mcp
+```
+
+## Suggested Local Flow
+
+```bash
+npm install
+npm run build
+npm link
+codex-plugin-doctor check examples/codex-doctor-starter
+codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
+codex-plugin-doctor check examples/codex-doctor-risky --ascii
+```

package/examples/codex-doctor-generic-mcp/.mcp.json

@@ -1,10 +1,10 @@
-{
-  "mcpServers": {
-    "genericRuntime": {
-      "command": "node",
-      "args": [
-        "server.js"
-      ]
-    }
-  }
-}
+{
+  "mcpServers": {
+    "genericRuntime": {
+      "command": "node",
+      "args": [
+        "server.js"
+      ]
+    }
+  }
+}

package/examples/codex-doctor-generic-mcp/server.js

@@ -1 +1 @@
-process.stdin.resume();
+process.stdin.resume();

package/examples/codex-doctor-risky/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
-{
-  "name": "codex-doctor-risky",
-  "version": "1.0.0",
-  "description": "Intentionally risky sample package for showing Codex Doctor failure output.",
-  "mcpServers": "./.mcp.json"
-}
-
+{
+  "name": "codex-doctor-risky",
+  "version": "1.0.0",
+  "description": "Intentionally risky sample package for showing Codex Doctor failure output.",
+  "mcpServers": "./.mcp.json"
+}
+

package/examples/codex-doctor-risky/.mcp.json

@@ -1,12 +1,12 @@
-{
-  "mcpServers": {
-    "dangerServer": {
-      "command": "node",
-      "args": ["./mock-server.js"],
-      "env": {
-        "OPENAI_API_KEY": "sk-live-example-secret-value"
-      }
-    }
-  }
-}
-
+{
+  "mcpServers": {
+    "dangerServer": {
+      "command": "node",
+      "args": ["./mock-server.js"],
+      "env": {
+        "OPENAI_API_KEY": "sk-live-example-secret-value"
+      }
+    }
+  }
+}
+

package/examples/codex-doctor-risky/mock-server.js

@@ -1 +1 @@
-process.stdin.resume();
+process.stdin.resume();

package/examples/codex-doctor-runtime/.codex-plugin/plugin.json

@@ -1,8 +1,8 @@
-{
-  "name": "codex-doctor-runtime",
-  "version": "1.0.0",
-  "description": "Runtime-complete Codex Doctor sample plugin with MCP validation coverage.",
-  "skills": "./skills/",
-  "mcpServers": "./.mcp.json"
-}
-
+{
+  "name": "codex-doctor-runtime",
+  "version": "1.0.0",
+  "description": "Runtime-complete Codex Doctor sample plugin with MCP validation coverage.",
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json"
+}
+

package/examples/codex-doctor-runtime/.mcp.json

@@ -1,9 +1,9 @@
-{
-  "mcpServers": {
-    "doctorRuntime": {
-      "command": "node",
-      "args": ["./mock-server.js"]
-    }
-  }
-}
-
+{
+  "mcpServers": {
+    "doctorRuntime": {
+      "command": "node",
+      "args": ["./mock-server.js"]
+    }
+  }
+}
+