codex-plugin-doctor 1.49.0 → 1.51.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Furkan Tasci
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Furkan Tasci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -427,9 +427,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.49.0
+      - uses: Esquetta/CodexPluginDoctor@v1.51.0
         with:
-          version: "1.49.0"
+          version: "1.51.0"
           path: .
           runtime: "true"
           policy: codex-publish
@@ -441,7 +441,7 @@ jobs:
           review-bundle-verify: "true"
 ```
 
-The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional `validation-corpus.json`, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/guides/github-action.md).
+The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional validation corpus and quality metrics reports, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus quality regression gates, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/guides/github-action.md).
 
 To self-test this repository after cloning it:
 

package/dist/core/mcp-conformance.d.ts

@@ -0,0 +1,2 @@
+import type { McpConformanceObservation, McpConformanceResult } from "../domain/types.js";
+export declare function evaluateMcpConformance(observation: McpConformanceObservation): McpConformanceResult;

package/dist/core/mcp-conformance.js

@@ -0,0 +1,215 @@
+const LATEST_PROTOCOL_VERSION = "2025-11-25";
+const LEGACY_PROTOCOL_VERSIONS = new Set([
+    "2024-11-05",
+    "2025-03-26",
+    "2025-06-18"
+]);
+const CANONICAL_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function buildFinding(id, severity, message, impact, suggestedFix, evidence) {
+    return {
+        id,
+        severity,
+        message,
+        impact,
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
+    };
+}
+function classifyProtocolVersion(protocolVersion) {
+    if (LEGACY_PROTOCOL_VERSIONS.has(protocolVersion)) {
+        return "legacy";
+    }
+    if (protocolVersion === LATEST_PROTOCOL_VERSION) {
+        return "2025-11-25";
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(protocolVersion) && protocolVersion > LATEST_PROTOCOL_VERSION) {
+        return "future-compatible";
+    }
+    return "legacy";
+}
+function addTaskCapabilityFailure(findings, field) {
+    findings.push(buildFinding("mcp.conformance.tasks.capability_invalid", "fail", `The Tasks capability field \`${field}\` must be an object when present.`, "Codex cannot safely determine whether the server supports task-aware tool calls.", `Return an object for \`${field}\`, or omit the capability until it is implemented.`, { field }));
+}
+function getTaskToolsCallCapabilityState(capabilities, findings) {
+    if (!isPlainObject(capabilities)) {
+        addTaskCapabilityFailure(findings, "capabilities");
+        return "malformed";
+    }
+    const tasks = capabilities.tasks;
+    if (tasks === undefined) {
+        return "missing";
+    }
+    if (!isPlainObject(tasks)) {
+        addTaskCapabilityFailure(findings, "capabilities.tasks");
+        return "malformed";
+    }
+    for (const key of ["list", "cancel"]) {
+        if (tasks[key] !== undefined && !isPlainObject(tasks[key])) {
+            addTaskCapabilityFailure(findings, `capabilities.tasks.${key}`);
+        }
+    }
+    const requests = tasks.requests;
+    if (requests === undefined) {
+        return "missing";
+    }
+    if (!isPlainObject(requests)) {
+        addTaskCapabilityFailure(findings, "capabilities.tasks.requests");
+        return "malformed";
+    }
+    const tools = requests.tools;
+    if (tools === undefined) {
+        return "missing";
+    }
+    if (!isPlainObject(tools)) {
+        addTaskCapabilityFailure(findings, "capabilities.tasks.requests.tools");
+        return "malformed";
+    }
+    const call = tools.call;
+    if (call === undefined) {
+        return "missing";
+    }
+    if (!isPlainObject(call)) {
+        addTaskCapabilityFailure(findings, "capabilities.tasks.requests.tools.call");
+        return "malformed";
+    }
+    return "present-valid";
+}
+function collectTaskDeclarationFindings(observation, taskCallCapabilityState, findings) {
+    for (const tool of observation.tools) {
+        let taskSupport = "forbidden";
+        if (tool.execution !== undefined) {
+            if (!isPlainObject(tool.execution)) {
+                findings.push(buildFinding("mcp.conformance.tasks.task_support_invalid", "fail", `Tool \`${tool.name}\` has a non-object execution declaration.`, "Codex cannot safely interpret the tool's task support contract.", "Return an object for `execution` with taskSupport set to required, optional, or forbidden.", { toolName: tool.name }));
+                continue;
+            }
+            taskSupport = tool.execution.taskSupport ?? "forbidden";
+        }
+        if (taskSupport !== "required" &&
+            taskSupport !== "optional" &&
+            taskSupport !== "forbidden") {
+            findings.push(buildFinding("mcp.conformance.tasks.task_support_invalid", "fail", `Tool \`${tool.name}\` declares an unsupported taskSupport value.`, "Codex cannot determine whether task-aware tool calls are required or optional.", "Set execution.taskSupport to required, optional, or forbidden.", { toolName: tool.name }));
+            continue;
+        }
+        if (taskSupport !== "forbidden" && taskCallCapabilityState === "missing") {
+            findings.push(buildFinding("mcp.conformance.tasks.capability_mismatch", "fail", `Tool \`${tool.name}\` declares task support without tasks.requests.tools.call capability.`, "Codex may attempt task-aware tool calls that the server did not advertise as supported.", "Advertise capabilities.tasks.requests.tools.call as an object, or set execution.taskSupport to forbidden.", { toolName: tool.name, taskSupport }));
+        }
+    }
+}
+function isAbsoluteUri(value) {
+    try {
+        return new URL(value).protocol.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function collectSchemaFindings(observation, findings) {
+    for (const tool of observation.tools) {
+        const schemas = [
+            ["inputSchema", tool.inputSchema]
+        ];
+        if (tool.outputSchema !== undefined) {
+            schemas.push(["outputSchema", tool.outputSchema]);
+        }
+        for (const [schemaName, schema] of schemas) {
+            if (!isPlainObject(schema)) {
+                findings.push(buildFinding("mcp.conformance.schema.dialect_invalid", "fail", `Tool \`${tool.name}\` has a non-object ${schemaName} container.`, "Codex cannot interpret a tool schema that is not represented as an object.", `Return an object for ${schemaName}.`, { toolName: tool.name, schema: schemaName }));
+                continue;
+            }
+            const dialect = schema.$schema;
+            if (dialect === undefined) {
+                continue;
+            }
+            if (typeof dialect !== "string" || !isAbsoluteUri(dialect)) {
+                findings.push(buildFinding("mcp.conformance.schema.dialect_invalid", "fail", `Tool \`${tool.name}\` has an invalid ${schemaName} $schema URI.`, "Codex cannot reliably select a schema dialect for this tool.", `Omit $schema or provide an absolute URI in ${schemaName}.`, { toolName: tool.name, schema: schemaName }));
+                continue;
+            }
+            if (dialect !== CANONICAL_SCHEMA_DIALECT && dialect !== `${CANONICAL_SCHEMA_DIALECT}#`) {
+                findings.push(buildFinding("mcp.conformance.schema.dialect_unsupported", "warn", `Tool \`${tool.name}\` uses a non-canonical ${schemaName} $schema dialect.`, "The schema may be valid, but its dialect is outside the validator's latest compatibility baseline.", `Use ${CANONICAL_SCHEMA_DIALECT} or omit $schema.`, { toolName: tool.name, schema: schemaName }));
+            }
+        }
+    }
+}
+function collectTasksListFinding(observation, findings) {
+    if (!observation || observation.status === "skipped") {
+        return "skipped";
+    }
+    if (observation.status === "pass") {
+        return "pass";
+    }
+    const timeout = observation.failure === "timeout";
+    findings.push(buildFinding(timeout
+        ? "mcp.conformance.tasks_list.timeout"
+        : "mcp.conformance.tasks_list.invalid", "fail", timeout
+        ? "The server did not complete tasks/list within the observation window."
+        : "The server returned an invalid tasks/list observation.", "Codex cannot rely on task discovery when tasks/list cannot complete with a valid response.", timeout
+        ? "Reduce tasks/list latency and verify pagination completes."
+        : "Return a valid tasks/list response with well-formed task items and pagination."));
+    return "fail";
+}
+function statusForFindings(findings) {
+    if (findings.some((finding) => finding.severity === "fail")) {
+        return "fail";
+    }
+    if (findings.some((finding) => finding.severity === "warn")) {
+        return "warn";
+    }
+    return "pass";
+}
+function overallStatus(scorecard, findings) {
+    const statuses = [
+        scorecard.capabilityConsistency,
+        scorecard.taskDeclarations,
+        scorecard.tasksList,
+        scorecard.schemaDialect
+    ];
+    if (statuses.includes("fail") || findings.some((finding) => finding.severity === "fail")) {
+        return "fail";
+    }
+    if (statuses.includes("warn") || findings.some((finding) => finding.severity === "warn")) {
+        return "warn";
+    }
+    return "pass";
+}
+export function evaluateMcpConformance(observation) {
+    const profile = classifyProtocolVersion(observation.protocolVersion);
+    const findings = [];
+    const scorecard = {
+        protocolVersion: observation.protocolVersion,
+        profile,
+        capabilityConsistency: "skipped",
+        taskDeclarations: "skipped",
+        tasksList: "skipped",
+        schemaDialect: "skipped",
+        overall: "pass"
+    };
+    if (profile === "future-compatible") {
+        findings.push(buildFinding("mcp.conformance.protocol.unknown_newer", "warn", `The server advertises newer MCP protocol version \`${observation.protocolVersion}\`.`, "The validator applies the 2025-11-25 structural baseline, which may not cover newer protocol requirements.", "Confirm the server's newer protocol changes remain compatible with the 2025-11-25 MCP contract.", { protocolVersion: observation.protocolVersion }));
+    }
+    if (profile === "legacy") {
+        scorecard.overall = overallStatus(scorecard, findings);
+        return { findings, scorecard };
+    }
+    if (!observation.skipToolDerivedChecks) {
+        const capabilityFindings = [];
+        const taskCallCapabilityState = getTaskToolsCallCapabilityState(observation.capabilities, capabilityFindings);
+        findings.push(...capabilityFindings);
+        scorecard.capabilityConsistency = statusForFindings(capabilityFindings);
+        const declarationFindings = [];
+        collectTaskDeclarationFindings(observation, taskCallCapabilityState, declarationFindings);
+        findings.push(...declarationFindings);
+        scorecard.taskDeclarations = statusForFindings(declarationFindings);
+    }
+    scorecard.tasksList = collectTasksListFinding(observation.tasksList, findings);
+    if (!observation.skipToolDerivedChecks) {
+        const schemaFindings = [];
+        collectSchemaFindings(observation, schemaFindings);
+        findings.push(...schemaFindings);
+        scorecard.schemaDialect = statusForFindings(schemaFindings);
+    }
+    scorecard.overall = overallStatus(scorecard, findings);
+    return { findings, scorecard };
+}

package/dist/core/npm-package-doctor.d.ts

@@ -38,6 +38,17 @@ export interface DoctorNpmPackageReport {
 export interface BuildDoctorNpmPackageReportOptions {
     environment?: CompatibilityEnvironment;
 }
+export interface NpmPackEntry {
+    filename?: string;
+    name?: string;
+    version?: string;
+    files?: unknown[];
+    integrity?: string;
+    shasum?: string;
+    size?: number;
+    unpackedSize?: number;
+}
+export declare function parseNpmPackOutput(stdout: string): NpmPackEntry[];
 export declare function buildDoctorNpmPackageReport(packageSpec: string, options?: BuildDoctorNpmPackageReportOptions): Promise<DoctorNpmPackageReport>;
 export declare function renderDoctorNpmPackageReportJson(report: DoctorNpmPackageReport): string;
 export declare function renderDoctorNpmPackageReport(report: DoctorNpmPackageReport, options?: {

package/dist/core/npm-package-doctor.js

@@ -7,6 +7,16 @@ import { gunzip } from "node:zlib";
 import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
 const execFileAsync = promisify(execFile);
 const gunzipAsync = promisify(gunzip);
+export function parseNpmPackOutput(stdout) {
+    const parsed = JSON.parse(stdout);
+    if (Array.isArray(parsed)) {
+        return parsed.filter((entry) => typeof entry === "object" && entry !== null);
+    }
+    if (typeof parsed === "object" && parsed !== null) {
+        return Object.values(parsed).filter((entry) => typeof entry === "object" && entry !== null);
+    }
+    return [];
+}
 function npmCommand(args) {
     if (process.platform === "win32") {
         const npmCliPath = process.env.npm_execpath ??
@@ -108,8 +118,8 @@ async function packNpmPackage(packageSpec, destinationPath) {
         env: npmPackEnvironment(),
         maxBuffer: 10 * 1024 * 1024
     });
-    const packEntries = JSON.parse(stdout);
-    const metadata = packEntries[0];
+    const packEntries = parseNpmPackOutput(stdout);
+    const metadata = packEntries.find((entry) => typeof entry.filename === "string");
     if (!metadata?.filename) {
         throw new Error(`npm pack did not return a tarball for ${packageSpec}`);
     }

package/dist/core/output-contract.js

@@ -1,11 +1,79 @@
 import { createHash } from "node:crypto";
 import { packageVersion } from "../version.js";
 import { ruleCatalog } from "../rules/rule-catalog.js";
+const runtimeCapabilityStatusSchema = {
+    type: "string",
+    enum: ["pass", "fail", "warn", "skipped", "unsupported"]
+};
+const runtimeConformanceSchema = {
+    type: "object",
+    properties: {
+        protocolVersion: {
+            type: ["string", "null"]
+        },
+        profile: {
+            type: ["string", "null"],
+            enum: ["legacy", "2025-11-25", "future-compatible", null]
+        },
+        capabilityConsistency: runtimeCapabilityStatusSchema,
+        taskDeclarations: runtimeCapabilityStatusSchema,
+        tasksList: runtimeCapabilityStatusSchema,
+        schemaDialect: runtimeCapabilityStatusSchema,
+        overall: {
+            type: "string",
+            enum: ["pass", "warn", "fail", "skipped"]
+        }
+    },
+    required: [
+        "protocolVersion",
+        "profile",
+        "capabilityConsistency",
+        "taskDeclarations",
+        "tasksList",
+        "schemaDialect",
+        "overall"
+    ],
+    additionalProperties: false
+};
+const runtimeScorecardSchema = {
+    type: "object",
+    properties: {
+        initialize: runtimeCapabilityStatusSchema,
+        toolsList: runtimeCapabilityStatusSchema,
+        toolsCall: runtimeCapabilityStatusSchema,
+        resourcesList: runtimeCapabilityStatusSchema,
+        resourceRead: runtimeCapabilityStatusSchema,
+        resourceTemplatesList: runtimeCapabilityStatusSchema,
+        promptsList: runtimeCapabilityStatusSchema,
+        promptGet: runtimeCapabilityStatusSchema,
+        conformance: runtimeConformanceSchema
+    },
+    required: [
+        "initialize",
+        "toolsList",
+        "toolsCall",
+        "resourcesList",
+        "resourceRead",
+        "resourceTemplatesList",
+        "promptsList",
+        "promptGet"
+    ],
+    additionalProperties: false
+};
 const publicSchemaDefinitions = [
     {
         id: "doctor.check.json",
         command: "codex-plugin-doctor check <path> --json",
-        required: ["schemaVersion", "generatedAt", "summary", "findings"]
+        required: ["schemaVersion", "generatedAt", "summary", "findings"],
+        properties: {
+            summary: {
+                type: "object",
+                properties: {
+                    runtimeScorecard: runtimeScorecardSchema
+                },
+                additionalProperties: true
+            }
+        }
     },
     {
         id: "doctor.installed.check.json",
@@ -27,7 +95,13 @@ const publicSchemaDefinitions = [
         id: "doctor.mcp.json",
         command: "codex-plugin-doctor mcp <path> --json",
         outputKind: "doctor.mcp.healthcheck",
-        required: ["schemaVersion", "kind", "generatedAt", "targetPath", "status", "serverCount", "findings", "security", "compatibility"]
+        required: ["schemaVersion", "kind", "generatedAt", "targetPath", "status", "serverCount", "findings", "security", "compatibility"],
+        properties: {
+            runtimeScorecard: {
+                ...runtimeScorecardSchema,
+                description: "Present only when codex-plugin-doctor mcp <path> --runtime is used."
+            }
+        }
     },
     {
         id: "doctor.audit.json",
@@ -271,7 +345,7 @@ function contractRules(rules) {
     }))
         .sort((left, right) => left.id.localeCompare(right.id));
 }
-function buildSchema(id, outputKind, required) {
+function buildSchema(id, outputKind, required, schemaProperties = {}) {
     const properties = {
         schemaVersion: {
             const: "1.0.0"
@@ -288,7 +362,10 @@ function buildSchema(id, outputKind, required) {
         title: id,
         type: "object",
         required: [...new Set(["schemaVersion", ...required])],
-        properties,
+        properties: {
+            ...properties,
+            ...schemaProperties
+        },
         additionalProperties: true
     };
 }
@@ -301,7 +378,7 @@ function buildSchemas() {
             schemaVersion: "1.0.0",
             stability: "stable-through-1.0",
             outputKind,
-            schema: buildSchema(definition.id, outputKind, definition.required ?? [])
+            schema: buildSchema(definition.id, outputKind, definition.required ?? [], definition.properties)
         };
     });
 }

package/dist/core/runtime-plan.js

@@ -133,6 +133,7 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
                     "initialize",
                     "tools/list",
                     "tools/call:safe-only",
+                    "tasks/list:declared-2025-11-only",
                     "resources/list",
                     "resources/read:first-resource-only",
                     "resources/templates/list",
@@ -244,6 +245,7 @@ export function renderDoctorRuntimePlanMarkdown(plan) {
         "## Execution Boundary",
         "",
         "- This plan is non-executing.",
+        "- Probe methods explicitly exclude task create, get, result, and cancel operations, plus sampling and elicitation requests.",
         "- Runtime probes require explicit operator approval before local MCP servers are started.",
         "- The approval digest changes when command, args, cwd, probe methods, risk reasons, or findings change.",
         "- Runtime approval is a review gate, not an OS, VM, or container sandbox.",

package/dist/core/runtime-probe.d.ts

@@ -1,6 +1,8 @@
 import type { DiscoveredPackage, RuntimeProbeResult, RuntimeSandboxMode } from "../domain/types.js";
-export declare function probeRuntime(discoveredPackage: DiscoveredPackage, options?: {
+export declare function probeRuntime(discoveredPackage: DiscoveredPackage, options?: RuntimeProbeOptions): Promise<RuntimeProbeResult>;
+export interface RuntimeProbeOptions {
     startupTimeoutMs?: number;
     sandbox?: RuntimeSandboxMode;
     transcript?: (line: string) => void;
-}): Promise<RuntimeProbeResult>;
+}
+export declare function probeRuntimeConfig(rootPath: string, mcpConfigPath: string, options?: RuntimeProbeOptions): Promise<RuntimeProbeResult>;