codex-plugin-doctor 1.6.0 → 1.7.0

package/README.md

@@ -220,6 +220,7 @@ codex-plugin-doctor doctor runtime-policy .
 codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json
 codex-plugin-doctor doctor review-bundle . --output review-bundle --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
 codex-plugin-doctor doctor review-bundle verify review-bundle --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
+codex-plugin-doctor doctor review-bundle diff --before old-review-bundle --after review-bundle
 codex-plugin-doctor doctor mcp .
 codex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json
 codex-plugin-doctor doctor export --bundle .
@@ -291,7 +292,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. 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. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, and Markdown summary files. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `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. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, and Markdown summary files. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before <dir> --after <dir>` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `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.
 
@@ -357,9 +358,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.6.0
+      - uses: Esquetta/CodexPluginDoctor@v1.7.0
         with:
-          version: "1.6.0"
+          version: "1.7.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/output-contract.js

@@ -95,6 +95,12 @@ const publicSchemaDefinitions = [
         outputKind: "doctor.review.bundle.verification",
         required: ["schemaVersion", "kind", "generatedAt", "bundleDirectory", "targetPath", "status", "exitCode", "summary", "checks", "attestation", "releaseEvidence"]
     },
+    {
+        id: "doctor.review.bundle.diff.json",
+        command: "codex-plugin-doctor doctor review-bundle diff --before <dir> --after <dir> --json",
+        outputKind: "doctor.review.bundle.diff",
+        required: ["schemaVersion", "kind", "generatedAt", "beforeDirectory", "afterDirectory", "status", "exitCode", "summary", "before", "after", "changes"]
+    },
     {
         id: "doctor.export.bundle.json",
         command: "codex-plugin-doctor doctor export --bundle <path> --json",

package/dist/core/review-bundle.d.ts

@@ -66,12 +66,54 @@ export interface DoctorReviewBundleVerificationReport {
     attestation: DoctorAttestationVerificationReport | null;
     releaseEvidence: DoctorReleaseEvidenceVerificationReport | null;
 }
+export interface DoctorReviewBundleDiffReport {
+    schemaVersion: "1.0.0";
+    kind: "doctor.review.bundle.diff";
+    generatedAt: string;
+    beforeDirectory: string;
+    afterDirectory: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    summary: {
+        changed: boolean;
+        statusChanged: boolean;
+        runtimePolicyChanged: boolean;
+        releaseReadyChanged: boolean;
+        riskIncreased: boolean;
+        changeCount: number;
+    };
+    before: DoctorReviewBundleDiffSnapshot | null;
+    after: DoctorReviewBundleDiffSnapshot | null;
+    changes: DoctorReviewBundleDiffChange[];
+}
+export interface DoctorReviewBundleDiffSnapshot {
+    targetPath: string;
+    version: string;
+    status: DoctorReviewBundleManifest["status"];
+    runtimePolicy: DoctorReviewBundleManifest["summary"]["runtimePolicy"];
+    releaseReady: boolean;
+    attestation: DoctorReviewBundleManifest["summary"]["attestation"];
+    releaseEvidence: DoctorReviewBundleManifest["summary"]["releaseEvidence"];
+    runtimePlanDigest: string | null;
+    releaseEvidenceStatus: DoctorReleaseEvidenceReport["status"] | null;
+    releaseEvidenceReady: boolean | null;
+}
+export interface DoctorReviewBundleDiffChange {
+    field: string;
+    before: string | boolean | null;
+    after: string | boolean | null;
+    severity: "info" | "warn" | "fail";
+    message: string;
+}
 export declare function buildDoctorReviewBundle(targetPath: string, options: BuildDoctorReviewBundleOptions): Promise<DoctorReviewBundle>;
 export declare function renderDoctorReviewBundleJson(bundle: DoctorReviewBundle): string;
+export declare function diffDoctorReviewBundles(beforeDirectory: string, afterDirectory: string): Promise<DoctorReviewBundleDiffReport>;
 export declare function verifyDoctorReviewBundle(bundleDirectory: string, options: {
     signingKey: string;
     targetPath: string;
 }): Promise<DoctorReviewBundleVerificationReport>;
 export declare function renderDoctorReviewBundleVerificationJson(report: DoctorReviewBundleVerificationReport): string;
 export declare function renderDoctorReviewBundleVerification(report: DoctorReviewBundleVerificationReport): string;
+export declare function renderDoctorReviewBundleDiffJson(report: DoctorReviewBundleDiffReport): string;
+export declare function renderDoctorReviewBundleDiff(report: DoctorReviewBundleDiffReport): string;
 export declare function renderDoctorReviewBundle(bundle: DoctorReviewBundle): string;

package/dist/core/review-bundle.js

@@ -18,6 +18,18 @@ function isDoctorReviewBundleManifest(value) {
         isPlainObject(value.summary) &&
         isPlainObject(value.files);
 }
+function statusRank(status) {
+    return status === "fail" ? 2 : status === "warn" ? 1 : 0;
+}
+function runtimePolicyRank(policy) {
+    return policy === "deny"
+        ? 3
+        : policy === "sandbox_recommended"
+            ? 2
+            : policy === "review"
+                ? 1
+                : 0;
+}
 function relativeBundleFiles() {
     return {
         manifest: "manifest.json",
@@ -133,6 +145,143 @@ export function renderDoctorReviewBundleJson(bundle) {
 async function readBundleJsonFile(bundleDirectory, relativePath) {
     return readJsonFile(path.join(bundleDirectory, relativePath));
 }
+async function readBundleDiffSnapshot(bundleDirectory) {
+    const manifestArtifact = await readBundleJsonFile(bundleDirectory, "manifest.json");
+    if (!isDoctorReviewBundleManifest(manifestArtifact)) {
+        return null;
+    }
+    const files = manifestArtifact.files;
+    let runtimePlanDigest = null;
+    let releaseEvidenceStatus = null;
+    let releaseEvidenceReady = null;
+    try {
+        const runtimePlan = await readBundleJsonFile(bundleDirectory, files.runtimePlanJson);
+        runtimePlanDigest = isPlainObject(runtimePlan) && typeof runtimePlan.digest === "string"
+            ? runtimePlan.digest
+            : null;
+    }
+    catch {
+        runtimePlanDigest = null;
+    }
+    try {
+        const releaseEvidence = await readBundleJsonFile(bundleDirectory, files.releaseEvidenceJson);
+        releaseEvidenceStatus = isPlainObject(releaseEvidence) &&
+            (releaseEvidence.status === "pass" || releaseEvidence.status === "fail")
+            ? releaseEvidence.status
+            : null;
+        releaseEvidenceReady = isPlainObject(releaseEvidence) && typeof releaseEvidence.releaseReady === "boolean"
+            ? releaseEvidence.releaseReady
+            : null;
+    }
+    catch {
+        releaseEvidenceStatus = null;
+        releaseEvidenceReady = null;
+    }
+    return {
+        targetPath: manifestArtifact.targetPath,
+        version: manifestArtifact.version,
+        status: manifestArtifact.status,
+        runtimePolicy: manifestArtifact.summary.runtimePolicy,
+        releaseReady: manifestArtifact.summary.releaseReady,
+        attestation: manifestArtifact.summary.attestation,
+        releaseEvidence: manifestArtifact.summary.releaseEvidence,
+        runtimePlanDigest,
+        releaseEvidenceStatus,
+        releaseEvidenceReady
+    };
+}
+function createDiffChange(field, before, after, severity, message) {
+    return before === after
+        ? null
+        : {
+            field,
+            before,
+            after,
+            severity,
+            message
+        };
+}
+function diffBundleSnapshots(before, after) {
+    const changes = [
+        createDiffChange("targetPath", before.targetPath, after.targetPath, "warn", "The bundle target path changed."),
+        createDiffChange("version", before.version, after.version, "info", "The doctor version changed."),
+        createDiffChange("status", before.status, after.status, statusRank(after.status) > statusRank(before.status) ? "fail" : "info", "The review bundle status changed."),
+        createDiffChange("runtimePolicy", before.runtimePolicy, after.runtimePolicy, runtimePolicyRank(after.runtimePolicy) > runtimePolicyRank(before.runtimePolicy) ? "warn" : "info", "The runtime policy decision changed."),
+        createDiffChange("releaseReady", before.releaseReady, after.releaseReady, before.releaseReady && !after.releaseReady ? "fail" : "info", "The release readiness flag changed."),
+        createDiffChange("attestation", before.attestation, after.attestation, statusRank(after.attestation) > statusRank(before.attestation) ? "fail" : "info", "The attestation summary changed."),
+        createDiffChange("releaseEvidence", before.releaseEvidence, after.releaseEvidence, statusRank(after.releaseEvidence) > statusRank(before.releaseEvidence) ? "fail" : "info", "The release evidence summary changed."),
+        createDiffChange("runtimePlanDigest", before.runtimePlanDigest, after.runtimePlanDigest, "warn", "The runtime plan digest changed."),
+        createDiffChange("releaseEvidenceStatus", before.releaseEvidenceStatus, after.releaseEvidenceStatus, after.releaseEvidenceStatus === "fail" ? "fail" : "info", "The embedded release evidence status changed."),
+        createDiffChange("releaseEvidenceReady", before.releaseEvidenceReady, after.releaseEvidenceReady, before.releaseEvidenceReady === true && after.releaseEvidenceReady === false ? "fail" : "info", "The embedded release evidence readiness changed.")
+    ];
+    return changes.filter((change) => change !== null);
+}
+export async function diffDoctorReviewBundles(beforeDirectory, afterDirectory) {
+    const resolvedBeforeDirectory = path.resolve(beforeDirectory);
+    const resolvedAfterDirectory = path.resolve(afterDirectory);
+    const [before, after] = await Promise.all([
+        readBundleDiffSnapshot(resolvedBeforeDirectory),
+        readBundleDiffSnapshot(resolvedAfterDirectory)
+    ]);
+    if (!before || !after) {
+        const changes = [
+            {
+                field: before ? "after" : "before",
+                before: before ? "valid" : "invalid",
+                after: after ? "valid" : "invalid",
+                severity: "fail",
+                message: "One or more review bundles could not be read as valid bundle directories."
+            }
+        ];
+        return {
+            schemaVersion: "1.0.0",
+            kind: "doctor.review.bundle.diff",
+            generatedAt: new Date().toISOString(),
+            beforeDirectory: resolvedBeforeDirectory,
+            afterDirectory: resolvedAfterDirectory,
+            status: "fail",
+            exitCode: 1,
+            summary: {
+                changed: true,
+                statusChanged: false,
+                runtimePolicyChanged: false,
+                releaseReadyChanged: false,
+                riskIncreased: true,
+                changeCount: changes.length
+            },
+            before,
+            after,
+            changes
+        };
+    }
+    const changes = diffBundleSnapshots(before, after);
+    const riskIncreased = changes.some((change) => change.severity === "fail" || change.severity === "warn");
+    const status = changes.some((change) => change.severity === "fail")
+        ? "fail"
+        : riskIncreased
+            ? "warn"
+            : "pass";
+    return {
+        schemaVersion: "1.0.0",
+        kind: "doctor.review.bundle.diff",
+        generatedAt: new Date().toISOString(),
+        beforeDirectory: resolvedBeforeDirectory,
+        afterDirectory: resolvedAfterDirectory,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        summary: {
+            changed: changes.length > 0,
+            statusChanged: before.status !== after.status,
+            runtimePolicyChanged: before.runtimePolicy !== after.runtimePolicy,
+            releaseReadyChanged: before.releaseReady !== after.releaseReady,
+            riskIncreased,
+            changeCount: changes.length
+        },
+        before,
+        after,
+        changes
+    };
+}
 export async function verifyDoctorReviewBundle(bundleDirectory, options) {
     const resolvedBundleDirectory = path.resolve(bundleDirectory);
     const targetPath = path.resolve(options.targetPath);
@@ -310,6 +459,35 @@ export function renderDoctorReviewBundleVerification(report) {
     }
     return lines.join("\n");
 }
+export function renderDoctorReviewBundleDiffJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorReviewBundleDiff(report) {
+    const lines = [
+        "Doctor Review Bundle Diff",
+        "=========================",
+        `Before: ${report.beforeDirectory}`,
+        `After: ${report.afterDirectory}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Changed: ${report.summary.changed ? "yes" : "no"}`,
+        `Risk increased: ${report.summary.riskIncreased ? "yes" : "no"}`,
+        `Changes: ${report.summary.changeCount}`,
+        "",
+        "Changes",
+        "-------"
+    ];
+    if (report.changes.length === 0) {
+        lines.push("No changes.");
+        return lines.join("\n");
+    }
+    for (const change of report.changes) {
+        lines.push(`${change.severity.toUpperCase()} ${change.field}`);
+        lines.push(`  Before: ${change.before ?? "unknown"}`);
+        lines.push(`  After: ${change.after ?? "unknown"}`);
+        lines.push(`  ${change.message}`);
+    }
+    return lines.join("\n");
+}
 export function renderDoctorReviewBundle(bundle) {
     return [
         "Doctor Review Bundle",

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnal
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.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 { buildDoctorReviewBundle, renderDoctorReviewBundle, renderDoctorReviewBundleJson, renderDoctorReviewBundleVerification, renderDoctorReviewBundleVerificationJson, verifyDoctorReviewBundle, type BuildDoctorReviewBundleOptions, type DoctorReviewBundle, type DoctorReviewBundleManifest, type DoctorReviewBundleVerificationReport } from "./core/review-bundle.js";
+export { buildDoctorReviewBundle, diffDoctorReviewBundles, renderDoctorReviewBundle, renderDoctorReviewBundleDiff, renderDoctorReviewBundleDiffJson, renderDoctorReviewBundleJson, renderDoctorReviewBundleVerification, renderDoctorReviewBundleVerificationJson, verifyDoctorReviewBundle, type BuildDoctorReviewBundleOptions, type DoctorReviewBundle, type DoctorReviewBundleDiffChange, type DoctorReviewBundleDiffReport, type DoctorReviewBundleDiffSnapshot, type DoctorReviewBundleManifest, type DoctorReviewBundleVerificationReport } from "./core/review-bundle.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

@@ -11,7 +11,7 @@ export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnal
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
 export { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanMarkdown, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
 export { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson } from "./core/runtime-policy.js";
-export { buildDoctorReviewBundle, renderDoctorReviewBundle, renderDoctorReviewBundleJson, renderDoctorReviewBundleVerification, renderDoctorReviewBundleVerificationJson, verifyDoctorReviewBundle } from "./core/review-bundle.js";
+export { buildDoctorReviewBundle, diffDoctorReviewBundles, renderDoctorReviewBundle, renderDoctorReviewBundleDiff, renderDoctorReviewBundleDiffJson, renderDoctorReviewBundleJson, renderDoctorReviewBundleVerification, renderDoctorReviewBundleVerificationJson, verifyDoctorReviewBundle } from "./core/review-bundle.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

@@ -22,7 +22,7 @@ import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, re
 import { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
 import { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanMarkdown, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
 import { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson } from "./core/runtime-policy.js";
-import { buildDoctorReviewBundle, renderDoctorReviewBundle, renderDoctorReviewBundleJson, renderDoctorReviewBundleVerification, renderDoctorReviewBundleVerificationJson, verifyDoctorReviewBundle } from "./core/review-bundle.js";
+import { buildDoctorReviewBundle, diffDoctorReviewBundles, renderDoctorReviewBundle, renderDoctorReviewBundleDiff, renderDoctorReviewBundleDiffJson, renderDoctorReviewBundleJson, renderDoctorReviewBundleVerification, renderDoctorReviewBundleVerificationJson, verifyDoctorReviewBundle } from "./core/review-bundle.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";
@@ -73,7 +73,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> [--json|--markdown] [--output <path>]|runtime-policy <path> [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json]|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>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--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",
@@ -414,6 +414,35 @@ export async function runCli(args, io = defaultIo, options = {}) {
             return report.exitCode;
         }
         if (maybePath === "review-bundle") {
+            if (remainingArgs[0] === "diff") {
+                const diffFlags = remainingArgs.slice(1);
+                const jsonOutput = diffFlags.includes("--json");
+                const beforeIndex = diffFlags.indexOf("--before");
+                const afterIndex = diffFlags.indexOf("--after");
+                const beforeDirectory = beforeIndex === -1 ? null : diffFlags[beforeIndex + 1];
+                const afterDirectory = afterIndex === -1 ? null : diffFlags[afterIndex + 1];
+                if (beforeIndex === -1) {
+                    io.writeStderr("Missing before bundle directory. Use --before <dir>.");
+                    return 2;
+                }
+                if (!beforeDirectory || beforeDirectory.startsWith("--")) {
+                    io.writeStderr("Missing directory after --before.");
+                    return 2;
+                }
+                if (afterIndex === -1) {
+                    io.writeStderr("Missing after bundle directory. Use --after <dir>.");
+                    return 2;
+                }
+                if (!afterDirectory || afterDirectory.startsWith("--")) {
+                    io.writeStderr("Missing directory after --after.");
+                    return 2;
+                }
+                const report = await diffDoctorReviewBundles(beforeDirectory, afterDirectory);
+                io.writeStdout(jsonOutput
+                    ? renderDoctorReviewBundleDiffJson(report)
+                    : renderDoctorReviewBundleDiff(report));
+                return report.exitCode;
+            }
             if (remainingArgs[0] === "verify") {
                 const bundleDirectory = remainingArgs[1] && !remainingArgs[1].startsWith("--")
                     ? remainingArgs[1]

package/package.json

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