codex-plugin-doctor 1.0.0 → 1.0.1

package/README.md

@@ -196,9 +196,10 @@ codex-plugin-doctor doctor corpus
 codex-plugin-doctor doctor corpus --json --output validation-corpus.json
 codex-plugin-doctor doctor npm <published-plugin-package>
 codex-plugin-doctor doctor npm <published-plugin-package> --json --output npm-preinstall.json
-codex-plugin-doctor doctor attest .
-codex-plugin-doctor doctor attest . --json --output attestation.json
-codex-plugin-doctor doctor inspector .
+codex-plugin-doctor doctor attest .
+codex-plugin-doctor doctor attest . --json --output attestation.json
+codex-plugin-doctor doctor attest . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY --output attestation.json
+codex-plugin-doctor doctor inspector .
 codex-plugin-doctor doctor inspector . --server context7 --json --output inspector-command.json
 codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin
 codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin --json --output risk-diff.json
@@ -206,9 +207,12 @@ codex-plugin-doctor doctor recommend .
 codex-plugin-doctor doctor recommend . --json --output recommendations.json
 codex-plugin-doctor doctor trust .
 codex-plugin-doctor doctor trust . --json --output trust-score.json
-codex-plugin-doctor doctor perf .
-codex-plugin-doctor doctor perf . --json --output perf.json
-codex-plugin-doctor doctor export --bundle .
+codex-plugin-doctor doctor perf .
+codex-plugin-doctor doctor perf . --json --output perf.json
+codex-plugin-doctor doctor perf . --max-total-ms 2500 --max-stage-ms validation=500
+codex-plugin-doctor doctor mcp .
+codex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json
+codex-plugin-doctor doctor export --bundle .
 codex-plugin-doctor doctor export --bundle . --output doctor-bundle.json
 codex-plugin-doctor doctor snapshot
 codex-plugin-doctor doctor snapshot --json
@@ -276,7 +280,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
-`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, and starter skill packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a deterministic local attestation with a package fingerprint, report digest, validation/security/compatibility/trust summary, and unsigned verification metadata. Add `--json` for automation or `--output attestation.json` to write the artifact to disk. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a deterministic local attestation with a package fingerprint, report digest, validation/security/compatibility/trust summary, and unsigned verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
 
 `audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
 
@@ -342,9 +346,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.0.0
-        with:
-          version: "1.0.0"
+      - uses: Esquetta/CodexPluginDoctor@v1.0.1
+        with:
+          version: "1.0.1"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/attestation.d.ts

@@ -50,12 +50,24 @@ export interface DoctorAttestation {
         recomputeCommand: string;
         notes: string[];
     };
-    signature: {
-        status: "unsigned";
-        reason: string;
-    };
+    signature: DoctorAttestationSignature;
+}
+export type DoctorAttestationSignature = {
+    status: "unsigned";
+    reason: string;
+} | {
+    status: "signed";
+    algorithm: "hmac-sha256";
+    digest: string;
+    payloadDigest: string;
+    keyHint: string;
+};
+export interface BuildDoctorAttestationOptions {
+    signingKey?: string;
+    signingKeyHint?: string;
+    recomputeKeyEnv?: string;
 }
-export declare function buildDoctorAttestation(targetPath: string): Promise<DoctorAttestation>;
+export declare function buildDoctorAttestation(targetPath: string, options?: BuildDoctorAttestationOptions): Promise<DoctorAttestation>;
 export declare function renderDoctorAttestationJson(attestation: DoctorAttestation): string;
 export declare function renderDoctorAttestation(attestation: DoctorAttestation, options?: {
     outputPath?: string | null;

package/dist/core/attestation.js

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
@@ -181,7 +181,7 @@ function buildSummary(analysis) {
         }
     };
 }
-export async function buildDoctorAttestation(targetPath) {
+export async function buildDoctorAttestation(targetPath, options = {}) {
     const analysis = await buildPackageAnalysis(targetPath);
     const [packageFingerprint, packageJson, manifest] = await Promise.all([
         buildPackageFingerprint(analysis.targetPath),
@@ -189,30 +189,58 @@ export async function buildDoctorAttestation(targetPath) {
         readManifestSubject(analysis.targetPath)
     ]);
     const reportDigest = sha256(stableStringify(buildReportDigestPayload(analysis, packageFingerprint)));
+    const subject = buildSubject(analysis, packageJson, manifest);
+    const summary = buildSummary(analysis);
+    const signingPayload = {
+        schemaVersion: "1.0.0",
+        kind: "doctor.attestation.signature.v1",
+        version: packageVersion,
+        subject,
+        packageFingerprint,
+        reportDigest,
+        summary
+    };
+    const signature = options.signingKey
+        ? {
+            status: "signed",
+            algorithm: "hmac-sha256",
+            digest: `sha256:${createHmac("sha256", options.signingKey)
+                .update(stableStringify(signingPayload))
+                .digest("hex")}`,
+            payloadDigest: sha256(stableStringify(signingPayload)),
+            keyHint: options.signingKeyHint ?? "inline"
+        }
+        : {
+            status: "unsigned",
+            reason: "No signing key was provided. Use --sign-key-env for reproducible local signing."
+        };
+    const recomputeCommand = signature.status === "signed"
+        ? `codex-plugin-doctor doctor attest ${analysis.targetPath} --json --sign-key-env ${options.recomputeKeyEnv ?? "CODEX_PLUGIN_DOCTOR_SIGNING_KEY"}`
+        : `codex-plugin-doctor doctor attest ${analysis.targetPath} --json`;
     return {
         schemaVersion: "1.0.0",
         kind: "doctor.attestation",
         generatedAt: analysis.generatedAt,
         version: packageVersion,
         targetPath: analysis.targetPath,
-        subject: buildSubject(analysis, packageJson, manifest),
+        subject,
         packageFingerprint,
         reportDigest: {
             algorithm: "sha256",
             digest: reportDigest
         },
-        summary: buildSummary(analysis),
+        summary,
         verification: {
-            recomputeCommand: `codex-plugin-doctor doctor attest ${analysis.targetPath} --json`,
+            recomputeCommand,
             notes: [
                 "Compare packageFingerprint.digest to confirm the same local package contents.",
-                "Compare reportDigest.digest to confirm the same validation, security, compatibility, trust, and recommendation signals."
+                "Compare reportDigest.digest to confirm the same validation, security, compatibility, trust, and recommendation signals.",
+                signature.status === "signed"
+                    ? "Recompute the signed attestation with the same HMAC key stored in an environment variable."
+                    : "Signing is optional and local; unsigned attestations remain deterministic without key material."
             ]
         },
-        signature: {
-            status: "unsigned",
-            reason: "v0.17 creates deterministic local attestations without key management or hosted signing."
-        }
+        signature
     };
 }
 export function renderDoctorAttestationJson(attestation) {
@@ -227,7 +255,7 @@ export function renderDoctorAttestation(attestation, options = {}) {
         `Status: ${attestation.summary.status.toUpperCase()}`,
         `Package fingerprint: ${attestation.packageFingerprint.digest}`,
         `Report digest: ${attestation.reportDigest.digest}`,
-        `Signature: ${attestation.signature.status}`
+        `Signature: ${attestation.signature.status}${attestation.signature.status === "signed" ? ` (${attestation.signature.algorithm})` : ""}`
     ];
     if (options.outputPath) {
         lines.push(`Output: ${options.outputPath}`);

package/dist/core/output-contract.js

@@ -26,7 +26,8 @@ const publicSchemaDefinitions = [
     {
         id: "doctor.mcp.json",
         command: "codex-plugin-doctor mcp <path> --json",
-        required: ["schemaVersion", "targetPath", "status", "summary", "findings"]
+        outputKind: "doctor.mcp.healthcheck",
+        required: ["schemaVersion", "kind", "generatedAt", "targetPath", "status", "serverCount", "findings", "security", "compatibility"]
     },
     {
         id: "doctor.audit.json",
@@ -68,7 +69,7 @@ const publicSchemaDefinitions = [
         id: "doctor.performance.json",
         command: "codex-plugin-doctor doctor perf <path> --json",
         outputKind: "doctor.perf",
-        required: ["schemaVersion", "kind", "generatedAt", "targetPath", "summary", "stages"]
+        required: ["schemaVersion", "kind", "generatedAt", "targetPath", "status", "exitCode", "summary", "stages", "thresholds"]
     },
     {
         id: "doctor.export.bundle.json",

package/dist/core/performance-report.d.ts

@@ -13,8 +13,8 @@ export interface DoctorPerformanceReport {
     generatedAt: string;
     kind: "doctor.perf";
     targetPath: string;
-    status: "pass";
-    exitCode: 0;
+    status: "pass" | "fail";
+    exitCode: 0 | 1;
     summary: {
         stageCount: number;
         slowestStage: DoctorPerformanceStageName;
@@ -23,12 +23,25 @@ export interface DoctorPerformanceReport {
         securityStatus: "pass" | "warn" | "fail";
         trustScore: number;
         compatibilityFailures: number;
+        thresholdFailures: number;
     };
     stages: DoctorPerformanceStage[];
+    thresholds: DoctorPerformanceThresholdResult[];
 }
 export interface BuildDoctorPerformanceReportOptions {
     environment?: CompatibilityEnvironment;
     runCheck?: (targetPath: string) => Promise<CheckResult>;
+    thresholds?: DoctorPerformanceThresholdOptions;
+}
+export interface DoctorPerformanceThresholdOptions {
+    totalMs?: number;
+    stages?: Partial<Record<DoctorPerformanceStageName, number>>;
+}
+export interface DoctorPerformanceThresholdResult {
+    stage: DoctorPerformanceStageName;
+    limitMs: number;
+    actualMs: number;
+    status: "pass" | "fail";
 }
 export declare function buildDoctorPerformanceReport(targetPath: string, options?: BuildDoctorPerformanceReportOptions): Promise<DoctorPerformanceReport>;
 export declare function renderDoctorPerformanceReportJson(report: DoctorPerformanceReport): string;

package/dist/core/performance-report.js

@@ -24,6 +24,34 @@ function slowestStage(stages) {
         .filter((stage) => stage.name !== "total")
         .reduce((slowest, stage) => (stage.durationMs > slowest.durationMs ? stage : slowest), stages[0]).name;
 }
+function evaluateThresholds(stages, thresholds = {}) {
+    const thresholdResults = [];
+    const stageByName = new Map(stages.map((stage) => [stage.name, stage]));
+    if (thresholds.totalMs !== undefined) {
+        const totalStage = stageByName.get("total");
+        if (totalStage) {
+            thresholdResults.push({
+                stage: "total",
+                limitMs: thresholds.totalMs,
+                actualMs: totalStage.durationMs,
+                status: totalStage.durationMs > thresholds.totalMs ? "fail" : "pass"
+            });
+        }
+    }
+    for (const [stageName, limitMs] of Object.entries(thresholds.stages ?? {})) {
+        const stage = stageByName.get(stageName);
+        if (!stage) {
+            continue;
+        }
+        thresholdResults.push({
+            stage: stageName,
+            limitMs,
+            actualMs: stage.durationMs,
+            status: stage.durationMs > limitMs ? "fail" : "pass"
+        });
+    }
+    return thresholdResults;
+}
 export async function buildDoctorPerformanceReport(targetPath, options = {}) {
     const timings = [];
     const startedAt = performance.now();
@@ -94,13 +122,16 @@ export async function buildDoctorPerformanceReport(targetPath, options = {}) {
             durationMs: roundDuration(totalDurationMs)
         };
     });
+    const thresholdResults = evaluateThresholds(stages, options.thresholds);
+    const thresholdFailures = thresholdResults
+        .filter((threshold) => threshold.status === "fail").length;
     return {
         schemaVersion: "1.0.0",
         generatedAt: analysis.generatedAt,
         kind: "doctor.perf",
         targetPath: analysis.targetPath,
-        status: "pass",
-        exitCode: 0,
+        status: thresholdFailures > 0 ? "fail" : "pass",
+        exitCode: thresholdFailures > 0 ? 1 : 0,
         summary: {
             stageCount: stages.length,
             slowestStage: slowestStage(stages),
@@ -108,9 +139,11 @@ export async function buildDoctorPerformanceReport(targetPath, options = {}) {
             validationStatus: analysis.validation.status,
             securityStatus: analysis.security.status,
             trustScore: analysis.trust.score,
-            compatibilityFailures
+            compatibilityFailures,
+            thresholdFailures
         },
-        stages
+        stages,
+        thresholds: thresholdResults
     };
 }
 export function renderDoctorPerformanceReportJson(report) {
@@ -137,5 +170,12 @@ export function renderDoctorPerformanceReport(report, options = {}) {
         const count = stage.itemCount === undefined ? "" : `, items: ${stage.itemCount}`;
         lines.push(`${stage.name}: ${stage.durationMs}ms${status}${count}`);
     }
+    if (report.thresholds.length > 0) {
+        lines.push("", "Thresholds", "----------");
+        for (const threshold of report.thresholds) {
+            lines.push(`${threshold.stage}: ${threshold.actualMs}ms <= ${threshold.limitMs}ms ` +
+                `(${threshold.status.toUpperCase()})`);
+        }
+    }
     return lines.join("\n");
 }

package/dist/core/validation-corpus.d.ts

@@ -7,6 +7,7 @@ export interface ValidationCorpusCaseDefinition {
     sourceType: "bundled-example";
     relativePath: string;
     runtimeEnabled: boolean;
+    mode?: "codex-plugin" | "generic-mcp";
     expected: {
         validationStatus: ValidationStatus;
         findingIds?: string[];

package/dist/core/validation-corpus.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import { buildPackageAnalysis } from "./package-analysis.js";
 import { validatePlugin } from "./validate-plugin.js";
 import { matrixExitCode } from "../compatibility/compatibility-matrix.js";
+import { buildGenericMcpDoctor } from "../mcp/generic-mcp-doctor.js";
 import { packageVersion } from "../version.js";
 const bundledCorpusCases = [
     {
@@ -38,6 +39,18 @@ const bundledCorpusCases = [
         expected: {
             validationStatus: "pass"
         }
+    },
+    {
+        id: "bundled-generic-mcp",
+        label: "Bundled generic MCP package",
+        profile: "generic-mcp",
+        sourceType: "bundled-example",
+        relativePath: "examples/codex-doctor-generic-mcp",
+        runtimeEnabled: false,
+        mode: "generic-mcp",
+        expected: {
+            validationStatus: "pass"
+        }
     }
 ];
 function resolvePackageRoot() {
@@ -48,6 +61,36 @@ function includesExpectedFindings(actualFindingIds, expectedFindingIds) {
 }
 async function runCorpusCase(caseDefinition, options) {
     const targetPath = path.resolve(resolvePackageRoot(), caseDefinition.relativePath);
+    const expectedFindingIds = [...(caseDefinition.expected.findingIds ?? [])].sort();
+    if (caseDefinition.mode === "generic-mcp") {
+        const report = await buildGenericMcpDoctor(targetPath, options.environment);
+        const findingIds = report.findings.map((finding) => finding.id).sort();
+        const compatibilityFailedClients = report.compatibility.results
+            .filter((result) => result.status === "fail")
+            .map((result) => result.client);
+        const expectationMatched = report.status === caseDefinition.expected.validationStatus &&
+            includesExpectedFindings(findingIds, expectedFindingIds);
+        return {
+            id: caseDefinition.id,
+            label: caseDefinition.label,
+            profile: caseDefinition.profile,
+            sourceType: caseDefinition.sourceType,
+            targetPath,
+            runtimeEnabled: caseDefinition.runtimeEnabled,
+            expected: {
+                validationStatus: caseDefinition.expected.validationStatus,
+                findingIds: expectedFindingIds
+            },
+            actual: {
+                validationStatus: report.status,
+                findingIds,
+                securityStatus: report.security.status,
+                trustStatus: "pass",
+                compatibilityFailedClients
+            },
+            expectationMatched
+        };
+    }
     const analysis = await buildPackageAnalysis(targetPath, {
         environment: options.environment,
         runCheck: (pathToCheck) => validatePlugin(pathToCheck, {
@@ -55,7 +98,6 @@ async function runCorpusCase(caseDefinition, options) {
         })
     });
     const findingIds = analysis.validation.findings.map((finding) => finding.id).sort();
-    const expectedFindingIds = [...(caseDefinition.expected.findingIds ?? [])].sort();
     const compatibilityFailedClients = analysis.compatibility.results
         .filter((result) => result.status === "fail")
         .map((result) => result.client);

package/dist/mcp/generic-mcp-doctor.js

@@ -125,6 +125,7 @@ export async function buildGenericMcpDoctor(targetPath, environment = {}) {
 export function renderGenericMcpDoctorJson(report) {
     return JSON.stringify({
         schemaVersion: "1.0.0",
+        kind: "doctor.mcp.healthcheck",
         generatedAt: new Date().toISOString(),
         ...report
     }, null, 2);

package/dist/run-cli.js

@@ -69,7 +69,71 @@ const defaultIo = {
     }
 };
 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] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor mcp <path> [--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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|attest <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path>|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]\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("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] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor mcp <path> [--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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|attest <path> [--sign-key-env NAME]|mcp <path>|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]\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");
+}
+const performanceStageNames = new Set([
+    "validation",
+    "doctorConfig",
+    "security",
+    "compatibility",
+    "trust",
+    "recommendations",
+    "total"
+]);
+function parseNonNegativeNumber(value) {
+    if (value === undefined || value.startsWith("--")) {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+function buildGenericMcpDoctorCommandArgs(commandTarget, flags) {
+    if (!commandTarget || commandTarget.startsWith("--")) {
+        return "Missing target path. Usage: codex-plugin-doctor mcp <path> [--json] [--output <path>]";
+    }
+    const outputIndex = flags.indexOf("--output");
+    const outputPath = outputIndex === -1 ? null : flags[outputIndex + 1];
+    if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+        return "Missing path after --output.";
+    }
+    return {
+        targetPath: commandTarget,
+        jsonOutput: flags.includes("--json"),
+        outputPath
+    };
+}
+function parsePerformanceThresholds(flags) {
+    const thresholds = {};
+    const totalIndex = flags.indexOf("--max-total-ms");
+    if (totalIndex !== -1) {
+        const totalMs = parseNonNegativeNumber(flags[totalIndex + 1]);
+        if (totalMs === null) {
+            return "Missing or invalid number after --max-total-ms.";
+        }
+        thresholds.totalMs = totalMs;
+    }
+    for (let index = 0; index < flags.length; index += 1) {
+        if (flags[index] !== "--max-stage-ms") {
+            continue;
+        }
+        const value = flags[index + 1];
+        if (!value || value.startsWith("--") || !value.includes("=")) {
+            return "Missing or invalid stage threshold after --max-stage-ms. Use stage=milliseconds.";
+        }
+        const [stageName, rawLimit] = value.split("=", 2);
+        if (!performanceStageNames.has(stageName)) {
+            return `Unknown performance stage: ${stageName}.`;
+        }
+        const limitMs = parseNonNegativeNumber(rawLimit);
+        if (limitMs === null) {
+            return "Missing or invalid number after --max-stage-ms.";
+        }
+        thresholds.stages = {
+            ...thresholds.stages,
+            [stageName]: limitMs
+        };
+    }
+    return { thresholds };
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -252,6 +316,29 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 : renderDoctorOutputContract(contract, { outputPath }));
             return 0;
         }
+        if (maybePath === "mcp") {
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : "";
+            const mcpFlags = targetPath ? remainingArgs.slice(1) : remainingArgs;
+            const parsedMcpArgs = buildGenericMcpDoctorCommandArgs(targetPath, mcpFlags);
+            if (typeof parsedMcpArgs === "string") {
+                io.writeStderr(parsedMcpArgs);
+                return 2;
+            }
+            const report = await buildGenericMcpDoctor(parsedMcpArgs.targetPath, {
+                env: terminalContext.env,
+                platform: terminalContext.platform
+            });
+            const renderedReport = parsedMcpArgs.jsonOutput
+                ? renderGenericMcpDoctorJson(report)
+                : renderGenericMcpDoctor(report);
+            if (parsedMcpArgs.outputPath) {
+                await writeFile(parsedMcpArgs.outputPath, renderedReport, "utf8");
+            }
+            io.writeStdout(renderedReport);
+            return report.exitCode;
+        }
         if (maybePath === "corpus") {
             const jsonOutput = remainingArgs.includes("--json");
             const outputIndex = remainingArgs.indexOf("--output");
@@ -285,11 +372,36 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const jsonOutput = attestFlags.includes("--json");
             const outputIndex = attestFlags.indexOf("--output");
             const outputPath = outputIndex === -1 ? null : attestFlags[outputIndex + 1];
+            const signKeyIndex = attestFlags.indexOf("--sign-key");
+            const signKeyEnvIndex = attestFlags.indexOf("--sign-key-env");
+            const signKey = signKeyIndex === -1 ? null : attestFlags[signKeyIndex + 1];
+            const signKeyEnv = signKeyEnvIndex === -1 ? null : attestFlags[signKeyEnvIndex + 1];
             if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
                 io.writeStderr("Missing path after --output.");
                 return 2;
             }
-            const attestation = await buildDoctorAttestation(targetPath);
+            if (signKeyIndex !== -1 && (!signKey || signKey.startsWith("--"))) {
+                io.writeStderr("Missing key after --sign-key.");
+                return 2;
+            }
+            if (signKeyEnvIndex !== -1 && (!signKeyEnv || signKeyEnv.startsWith("--"))) {
+                io.writeStderr("Missing environment variable name after --sign-key-env.");
+                return 2;
+            }
+            if (signKeyIndex !== -1 && signKeyEnvIndex !== -1) {
+                io.writeStderr("Use either --sign-key or --sign-key-env, not both.");
+                return 2;
+            }
+            const envSigningKey = signKeyEnv ? terminalContext.env[signKeyEnv] : undefined;
+            if (signKeyEnv && !envSigningKey) {
+                io.writeStderr(`Environment variable ${signKeyEnv} is not set.`);
+                return 2;
+            }
+            const attestation = await buildDoctorAttestation(targetPath, {
+                signingKey: signKey ?? envSigningKey,
+                signingKeyHint: signKeyEnv ? `env:${signKeyEnv}` : signKey ? "inline" : undefined,
+                recomputeKeyEnv: signKeyEnv ?? undefined
+            });
             const attestationJson = renderDoctorAttestationJson(attestation);
             if (outputPath) {
                 await writeFile(outputPath, attestationJson, "utf8");
@@ -429,6 +541,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr("Missing path after --output.");
                 return 2;
             }
+            const parsedThresholds = parsePerformanceThresholds(perfFlags);
+            if (typeof parsedThresholds === "string") {
+                io.writeStderr(parsedThresholds);
+                return 2;
+            }
             const report = await buildDoctorPerformanceReport(targetPath, {
                 environment: {
                     env: terminalContext.env,
@@ -436,7 +553,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 },
                 runCheck: options.runCheckImpl
                     ? (pathToCheck) => options.runCheckImpl(pathToCheck)
-                    : undefined
+                    : undefined,
+                thresholds: parsedThresholds.thresholds
             });
             const renderedReport = jsonOutput
                 ? renderDoctorPerformanceReportJson(report)
@@ -689,26 +807,20 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return audit.status === "fail" ? 1 : 0;
     }
     if (command === "mcp") {
-        if (!maybePath || maybePath.startsWith("--")) {
-            io.writeStderr("Missing target path. Usage: codex-plugin-doctor mcp <path> [--json] [--output <path>]");
-            return 2;
-        }
-        const jsonOutput = remainingArgs.includes("--json");
-        const outputIndex = remainingArgs.indexOf("--output");
-        const outputPath = outputIndex === -1 ? null : remainingArgs[outputIndex + 1];
-        if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
-            io.writeStderr("Missing path after --output.");
+        const parsedMcpArgs = buildGenericMcpDoctorCommandArgs(maybePath ?? "", remainingArgs);
+        if (typeof parsedMcpArgs === "string") {
+            io.writeStderr(parsedMcpArgs);
             return 2;
         }
-        const report = await buildGenericMcpDoctor(maybePath, {
+        const report = await buildGenericMcpDoctor(parsedMcpArgs.targetPath, {
             env: terminalContext.env,
             platform: terminalContext.platform
         });
-        const renderedReport = jsonOutput
+        const renderedReport = parsedMcpArgs.jsonOutput
             ? renderGenericMcpDoctorJson(report)
             : renderGenericMcpDoctor(report);
-        if (outputPath) {
-            await writeFile(outputPath, renderedReport, "utf8");
+        if (parsedMcpArgs.outputPath) {
+            await writeFile(parsedMcpArgs.outputPath, renderedReport, "utf8");
         }
         io.writeStdout(renderedReport);
         return report.exitCode;

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

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

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

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

package/package.json

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