codex-plugin-doctor 1.2.0 → 1.4.0

package/README.md

@@ -215,6 +215,9 @@ 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 runtime-plan .
 codex-plugin-doctor doctor runtime-plan . --json --output runtime-plan.json
+codex-plugin-doctor doctor runtime-plan . --markdown --output runtime-plan.md
+codex-plugin-doctor doctor runtime-policy .
+codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json
 codex-plugin-doctor doctor mcp .
 codex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json
 codex-plugin-doctor doctor export --bundle .
@@ -286,7 +289,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, 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 local attestation with stable package/report digests, validation/security/compatibility/trust summary, and 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 attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `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.
+`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 local attestation with stable package/report digests, validation/security/compatibility/trust summary, and 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 attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy <path>` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `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.
 
@@ -352,9 +355,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.2.0
+      - uses: Esquetta/CodexPluginDoctor@v1.4.0
         with:
-          version: "1.2.0"
+          version: "1.4.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/output-contract.js

@@ -77,6 +77,12 @@ const publicSchemaDefinitions = [
         outputKind: "doctor.runtime.plan",
         required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "digest", "summary", "servers", "findings"]
     },
+    {
+        id: "doctor.runtime.policy.json",
+        command: "codex-plugin-doctor doctor runtime-policy <path> --json",
+        outputKind: "doctor.runtime.policy",
+        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "planDigest", "recommendation", "summary", "servers"]
+    },
     {
         id: "doctor.export.bundle.json",
         command: "codex-plugin-doctor doctor export --bundle <path> --json",

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

@@ -47,5 +47,6 @@ export declare function evaluateRuntimeApproval(plan: DoctorRuntimePlan, options
 }): RuntimeApprovalReport;
 export declare function runtimeApprovalPassed(approval: RuntimeApprovalReport): boolean;
 export declare function renderDoctorRuntimePlanJson(plan: DoctorRuntimePlan): string;
+export declare function renderDoctorRuntimePlanMarkdown(plan: DoctorRuntimePlan): string;
 export declare function renderDoctorRuntimePlan(plan: DoctorRuntimePlan): string;
 export {};

package/dist/core/runtime-plan.js

@@ -203,6 +203,67 @@ export function runtimeApprovalPassed(approval) {
 export function renderDoctorRuntimePlanJson(plan) {
     return JSON.stringify(plan, null, 2);
 }
+function markdownList(items, emptyValue) {
+    if (items.length === 0) {
+        return `- ${emptyValue}`;
+    }
+    return items.map((item) => `- ${item}`).join("\n");
+}
+function markdownEscape(value) {
+    return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+export function renderDoctorRuntimePlanMarkdown(plan) {
+    const lines = [
+        "# Doctor Runtime Review Plan",
+        "",
+        "This artifact records the intended MCP runtime probe boundary before any package-local server is started.",
+        "",
+        "## Summary",
+        "",
+        `- Target: \`${plan.targetPath}\``,
+        `- Status: **${plan.status.toUpperCase()}**`,
+        `- Runtime execution: \`${plan.runtimeExecution}\``,
+        `- Approval digest: \`${plan.digest}\``,
+        `- Servers: ${plan.summary.serverCount}`,
+        `- Executable servers: ${plan.summary.executableServerCount}`,
+        `- High-risk servers: ${plan.summary.highRiskServerCount}`,
+        `- Findings: ${plan.summary.findings.fail} fail, ${plan.summary.findings.warn} warn, ${plan.summary.findings.total} total`,
+        "",
+        "## Execution Boundary",
+        "",
+        "- This plan is non-executing.",
+        "- 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.",
+        "",
+        "## Review Checklist",
+        "",
+        "- Confirm every command, argument, and working directory is expected.",
+        "- Confirm remote URLs and network expectations are acceptable for the task.",
+        "- Confirm high-risk findings are resolved or intentionally accepted before runtime probing.",
+        "- Use the approval digest with `check --runtime --require-runtime-approval --runtime-approval-digest <digest>`.",
+        "- Preserve this artifact with release evidence when runtime execution is part of the release gate."
+    ];
+    if (plan.servers.length === 0) {
+        lines.push("", "## Servers", "", "No MCP runtime servers found.");
+    }
+    else {
+        lines.push("", "## Servers", "", "| Risk | Name | Transport | Command or URL | Cwd |", "| --- | --- | --- | --- | --- |");
+        for (const server of plan.servers) {
+            lines.push(`| ${server.riskLevel.toUpperCase()} | ${markdownEscape(server.name)} | ${server.transport} | ${markdownEscape(server.command ?? server.url ?? "not executable by runtime probe")} | ${markdownEscape(server.cwd ?? "n/a")} |`);
+        }
+        for (const server of plan.servers) {
+            lines.push("", `### ${server.name}`, "", "**Probe methods**", "", markdownList(server.probeMethods, "none"), "", "**Risk reasons**", "", markdownList(server.riskReasons, "none"));
+        }
+    }
+    if (plan.findings.length > 0) {
+        lines.push("", "## Findings", "");
+        for (const finding of plan.findings) {
+            lines.push(`- **${finding.severity.toUpperCase()}** \`${finding.id}\`: ${finding.message}`);
+        }
+    }
+    return lines.join("\n");
+}
 export function renderDoctorRuntimePlan(plan) {
     const lines = [
         "Doctor Runtime Plan",

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

@@ -0,0 +1,34 @@
+import { type DoctorRuntimePlan, type RuntimePlanServer } from "./runtime-plan.js";
+export type RuntimePolicyDecision = "allow" | "review" | "sandbox_recommended" | "deny";
+export interface RuntimePolicyRecommendation {
+    decision: RuntimePolicyDecision;
+    reason: string;
+    actions: string[];
+}
+export interface DoctorRuntimePolicyReport {
+    schemaVersion: "1.0.0";
+    kind: "doctor.runtime.policy";
+    generatedAt: string;
+    version: string;
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    runtimeExecution: "not_started";
+    planDigest: string;
+    recommendation: RuntimePolicyRecommendation;
+    summary: {
+        serverCount: number;
+        executableServerCount: number;
+        highRiskServerCount: number;
+        findingCounts: DoctorRuntimePlan["summary"]["findings"];
+    };
+    servers: Array<{
+        name: string;
+        decision: RuntimePolicyDecision;
+        riskLevel: RuntimePlanServer["riskLevel"];
+        reasons: string[];
+    }>;
+}
+export declare function buildDoctorRuntimePolicyReport(targetPath: string, generatedAt?: string): Promise<DoctorRuntimePolicyReport>;
+export declare function renderDoctorRuntimePolicyJson(report: DoctorRuntimePolicyReport): string;
+export declare function renderDoctorRuntimePolicy(report: DoctorRuntimePolicyReport): string;

package/dist/core/runtime-policy.js

@@ -0,0 +1,167 @@
+import { packageVersion } from "../version.js";
+import { buildDoctorRuntimePlan } from "./runtime-plan.js";
+const denyFindingIds = new Set([
+    "plugin.security.encoded_command",
+    "plugin.security.remote_pipe_install",
+    "plugin.security.cwd_outside_root",
+    "plugin.security.hard_coded_secret",
+    "plugin.security.prompt_injection_text",
+    "plugin.security.path_traversal"
+]);
+function unique(values) {
+    return [...new Set(values)];
+}
+function serverDecision(server) {
+    if (server.riskReasons.some((reason) => denyFindingIds.has(reason))) {
+        return "deny";
+    }
+    if (server.riskLevel === "high") {
+        return "sandbox_recommended";
+    }
+    if (server.riskLevel === "medium" ||
+        server.riskReasons.includes("runtime.executes_local_command") ||
+        server.riskReasons.includes("runtime.connects_remote_server")) {
+        return "review";
+    }
+    return "allow";
+}
+function strongestDecision(decisions) {
+    if (decisions.includes("deny")) {
+        return "deny";
+    }
+    if (decisions.includes("sandbox_recommended")) {
+        return "sandbox_recommended";
+    }
+    if (decisions.includes("review")) {
+        return "review";
+    }
+    return "allow";
+}
+function buildRecommendation(plan, decision, reasons) {
+    if (plan.summary.executableServerCount === 0) {
+        return {
+            decision: "allow",
+            reason: "No executable local MCP runtime servers were found.",
+            actions: [
+                "Use static validation and security checks; runtime probing is not needed for this package."
+            ]
+        };
+    }
+    if (decision === "deny") {
+        return {
+            decision,
+            reason: "One or more runtime servers include high-confidence unsafe execution signals.",
+            actions: [
+                "Do not start runtime probes until deny-level findings are resolved.",
+                "Remove encoded commands, remote pipe-to-shell startup, cwd escapes, hard-coded secrets, or prompt-injection text.",
+                "Regenerate `doctor runtime-plan` after fixes and review the new approval digest."
+            ]
+        };
+    }
+    if (decision === "sandbox_recommended") {
+        return {
+            decision,
+            reason: "Runtime execution has high-risk findings or failed security checks that need isolation before probing.",
+            actions: [
+                "Prefer an isolated container, VM, or managed sandbox before starting this MCP server.",
+                "Keep network egress allowlists explicit and minimal.",
+                "Attach the runtime plan digest and review artifact to the release or CI evidence."
+            ]
+        };
+    }
+    if (decision === "review") {
+        return {
+            decision,
+            reason: reasons.length > 0
+                ? `Runtime probing requires human review: ${unique(reasons).join(", ")}.`
+                : "Runtime probing starts local or remote MCP server surfaces and should be explicitly reviewed.",
+            actions: [
+                "Review command, args, cwd, URL, probe methods, and risk reasons before execution.",
+                "Approve the exact plan digest with `check --runtime --require-runtime-approval --runtime-approval-digest <digest>`.",
+                "Use `doctor runtime-plan --markdown` when the approval needs to be preserved with release evidence."
+            ]
+        };
+    }
+    return {
+        decision,
+        reason: "Runtime plan is clean and contains only low-risk executable server entries.",
+        actions: [
+            "Runtime probes can run after normal operator approval.",
+            "Keep the runtime plan digest with CI or release evidence when reproducibility matters."
+        ]
+    };
+}
+export async function buildDoctorRuntimePolicyReport(targetPath, generatedAt = new Date().toISOString()) {
+    const plan = await buildDoctorRuntimePlan(targetPath, generatedAt);
+    const servers = plan.servers.map((server) => ({
+        name: server.name,
+        decision: serverDecision(server),
+        riskLevel: server.riskLevel,
+        reasons: server.riskReasons
+    }));
+    const findingReasons = plan.findings.map((finding) => finding.id);
+    const decision = plan.summary.findings.fail > 0 && servers.length === 0
+        ? "deny"
+        : strongestDecision(servers.map((server) => server.decision));
+    const recommendation = buildRecommendation(plan, decision, unique([...findingReasons, ...servers.flatMap((server) => server.reasons)]));
+    const status = recommendation.decision === "deny"
+        ? "fail"
+        : recommendation.decision === "allow"
+            ? "pass"
+            : "warn";
+    return {
+        schemaVersion: "1.0.0",
+        kind: "doctor.runtime.policy",
+        generatedAt,
+        version: packageVersion,
+        targetPath: plan.targetPath,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        runtimeExecution: "not_started",
+        planDigest: plan.digest,
+        recommendation,
+        summary: {
+            serverCount: plan.summary.serverCount,
+            executableServerCount: plan.summary.executableServerCount,
+            highRiskServerCount: plan.summary.highRiskServerCount,
+            findingCounts: plan.summary.findings
+        },
+        servers
+    };
+}
+export function renderDoctorRuntimePolicyJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorRuntimePolicy(report) {
+    const lines = [
+        "Doctor Runtime Policy",
+        "=====================",
+        `Target: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Decision: ${report.recommendation.decision.toUpperCase()}`,
+        `Runtime execution: ${report.runtimeExecution}`,
+        `Plan digest: ${report.planDigest}`,
+        `Servers: ${report.summary.serverCount}`,
+        `Executable servers: ${report.summary.executableServerCount}`,
+        `High-risk servers: ${report.summary.highRiskServerCount}`,
+        "",
+        "Reason",
+        "------",
+        report.recommendation.reason,
+        "",
+        "Actions",
+        "-------"
+    ];
+    for (const action of report.recommendation.actions) {
+        lines.push(`- ${action}`);
+    }
+    if (report.servers.length > 0) {
+        lines.push("", "Servers", "-------");
+        for (const server of report.servers) {
+            lines.push(`${server.decision.toUpperCase()} ${server.name}`);
+            lines.push(`  Risk: ${server.riskLevel}`);
+            lines.push(`  Reasons: ${server.reasons.length > 0 ? server.reasons.join(", ") : "none"}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -9,7 +9,8 @@ export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutp
 export { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport, type BuildDoctorValidationCorpusOptions, type DoctorValidationCorpusReport, type ValidationCorpusCaseDefinition, type ValidationCorpusCaseResult } from "./core/validation-corpus.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis, type PackageAnalysis, type PackageAnalysisOptions, type PackageAnalysisStage, type PackageAnalysisTiming } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.js";
-export { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanJson, runtimeApprovalPassed, type DoctorRuntimePlan, type RuntimeApprovalReport, type RuntimePlanServer } from "./core/runtime-plan.js";
+export { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanMarkdown, renderDoctorRuntimePlanJson, runtimeApprovalPassed, type DoctorRuntimePlan, type RuntimeApprovalReport, type RuntimePlanServer } from "./core/runtime-plan.js";
+export { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson, type DoctorRuntimePolicyReport, type RuntimePolicyDecision, type RuntimePolicyRecommendation } from "./core/runtime-policy.js";
 export { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence, type BuildDoctorReleaseEvidenceOptions, type DoctorReleaseEvidenceAssetReport, type DoctorReleaseEvidenceGitMetadata, type DoctorReleaseEvidencePackageMetadata, type DoctorReleaseEvidenceReport, type DoctorReleaseEvidenceVerificationReport } from "./core/release-evidence.js";
 export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson, type BuildDoctorNpmPackageReportOptions, type DoctorNpmPackageReport } from "./core/npm-package-doctor.js";
 export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson, type BuildDoctorRiskDiffReportOptions, type DoctorRiskDiffReport, type RiskDiffFinding, type RiskFindingCategory } from "./core/risk-diff.js";

package/dist/index.js

@@ -9,7 +9,8 @@ export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutp
 export { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
-export { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
+export { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanMarkdown, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
+export { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson } from "./core/runtime-policy.js";
 export { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence } from "./core/release-evidence.js";
 export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
 export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";

package/dist/run-cli.js

@@ -20,7 +20,8 @@ import { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestatio
 import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
 import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 import { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
-import { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
+import { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanMarkdown, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
+import { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson } from "./core/runtime-policy.js";
 import { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence } from "./core/release-evidence.js";
 import { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
 import { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";
@@ -71,7 +72,7 @@ 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] [--require-runtime-approval --runtime-approval-digest <digest>] [--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|runtime-plan <path>|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--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 [--upload]|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");
+    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] [--require-runtime-approval --runtime-approval-digest <digest>] [--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|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--json] [--output <path>]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--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 [--upload]|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",
@@ -358,6 +359,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 : null;
             const runtimePlanFlags = targetPath ? remainingArgs.slice(1) : remainingArgs;
             const jsonOutput = runtimePlanFlags.includes("--json");
+            const markdownOutput = runtimePlanFlags.includes("--markdown");
             const outputIndex = runtimePlanFlags.indexOf("--output");
             const outputPath = outputIndex === -1 ? null : runtimePlanFlags[outputIndex + 1];
             if (!targetPath) {
@@ -368,16 +370,48 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr("Missing path after --output.");
                 return 2;
             }
+            if (jsonOutput && markdownOutput) {
+                io.writeStderr("Use either --json or --markdown, not both.");
+                return 2;
+            }
             const plan = await buildDoctorRuntimePlan(targetPath);
             const renderedPlan = jsonOutput
                 ? renderDoctorRuntimePlanJson(plan)
-                : renderDoctorRuntimePlan(plan);
+                : markdownOutput
+                    ? renderDoctorRuntimePlanMarkdown(plan)
+                    : renderDoctorRuntimePlan(plan);
             if (outputPath) {
-                await writeFile(outputPath, renderDoctorRuntimePlanJson(plan), "utf8");
+                await writeFile(outputPath, markdownOutput ? renderDoctorRuntimePlanMarkdown(plan) : renderDoctorRuntimePlanJson(plan), "utf8");
             }
             io.writeStdout(renderedPlan);
             return plan.exitCode;
         }
+        if (maybePath === "runtime-policy") {
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : null;
+            const runtimePolicyFlags = targetPath ? remainingArgs.slice(1) : remainingArgs;
+            const jsonOutput = runtimePolicyFlags.includes("--json");
+            const outputIndex = runtimePolicyFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : runtimePolicyFlags[outputIndex + 1];
+            if (!targetPath) {
+                io.writeStderr("Missing target path for runtime policy.");
+                return 2;
+            }
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const report = await buildDoctorRuntimePolicyReport(targetPath);
+            const renderedReport = jsonOutput
+                ? renderDoctorRuntimePolicyJson(report)
+                : renderDoctorRuntimePolicy(report);
+            if (outputPath) {
+                await writeFile(outputPath, renderedReport, "utf8");
+            }
+            io.writeStdout(renderedReport);
+            return report.exitCode;
+        }
         if (maybePath === "release-evidence") {
             if (remainingArgs[0] === "asset") {
                 const targetPath = remainingArgs[1] && !remainingArgs[1].startsWith("--")

package/package.json

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