codex-plugin-doctor 1.46.1 → 1.48.0

package/README.md

@@ -79,6 +79,7 @@ Runtime MCP validation with `--runtime`:
 - runtime capability scorecard
 - redacted verbose transcript with `--verbose-runtime`
 - optional runtime approval gating with a precomputed `doctor runtime-plan` digest
+- optional Docker isolation for local Node.js stdio servers with `--sandbox docker`
 
 Output formats:
 
@@ -195,6 +196,9 @@ codex-plugin-doctor doctor contract
 codex-plugin-doctor doctor contract --json --output output-contract.json
 codex-plugin-doctor doctor corpus
 codex-plugin-doctor doctor corpus --json --output validation-corpus.json
+codex-plugin-doctor doctor corpus --manifest ../private-corpus/corpus.json --json
+codex-plugin-doctor doctor corpus metrics --manifest ../private-corpus/metrics.json --markdown
+codex-plugin-doctor doctor corpus metrics --manifest ../private-corpus/metrics.json --json --min-precision 0.90 --min-recall 0.85 --max-false-positive-rate 0.10
 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 .
@@ -216,8 +220,10 @@ codex-plugin-doctor doctor perf . --max-total-ms 2500 --max-stage-ms validation=
 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-plan . --sandbox docker --json
 codex-plugin-doctor doctor runtime-policy .
 codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json
+codex-plugin-doctor doctor runtime-policy . --sandbox docker --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
@@ -285,13 +291,16 @@ codex-plugin-doctor check . --badge-markdown
 codex-plugin-doctor check . --sarif --output results.sarif
 codex-plugin-doctor check . --ascii
 codex-plugin-doctor check . --no-animations
-codex-plugin-doctor check . --runtime
-codex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
-codex-plugin-doctor release check .
-codex-plugin-doctor release check . --json
-codex-plugin-doctor release check . --runtime
-codex-plugin-doctor release check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
-codex-plugin-doctor check . --config .codex-doctor.json
+codex-plugin-doctor check . --runtime
+codex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
+codex-plugin-doctor check . --runtime --sandbox docker
+codex-plugin-doctor check . --runtime --sandbox docker --require-runtime-approval --runtime-approval-digest sha256:<approved-docker-plan-digest>
+codex-plugin-doctor release check .
+codex-plugin-doctor release check . --json
+codex-plugin-doctor release check . --runtime
+codex-plugin-doctor release check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
+codex-plugin-doctor release check . --runtime --sandbox docker --require-runtime-approval --runtime-approval-digest sha256:<approved-docker-plan-digest>
+codex-plugin-doctor check . --config .codex-doctor.json
 codex-plugin-doctor baseline create . --output .codex-doctor-baseline.json
 codex-plugin-doctor check . --baseline .codex-doctor-baseline.json
 codex-plugin-doctor check . --history validation-history.jsonl
@@ -304,6 +313,12 @@ codex-plugin-doctor fix . --apply --backup
 codex-plugin-doctor check . --json --runtime --verbose-runtime
 ```
 
+Docker runtime mode supports local Node.js stdio MCP servers. It uses a digest-pinned image, no network, read-only container and package filesystems, an unprivileged user, dropped capabilities, bounded resources, and a limited writable `/tmp`. It fails closed without native fallback and rejects package roots containing commas. The Docker daemon, base image, and host kernel remain trusted boundaries. Generate approval digests with the same `--sandbox docker` backend used for execution. See [Runtime Approval And Sandboxing](./docs/security/runtime-approval-and-sandboxing.md).
+
+External corpus evaluation is static and offline. `doctor corpus --manifest <corpus.json>` validates anonymized local snapshots using stable content digests and exact finding fingerprints without downloading dependencies or starting target servers. Reports omit manifest and package paths and fail on digest drift, missing expected findings, present disputed findings, or unreviewed findings. See [Real-World Validation](./docs/guides/real-world-validation.md).
+
+`doctor corpus metrics --manifest <corpus.json>` measures reviewed true positives, false positives, and false negatives as precision, recall, and emitted-finding false-positive share. Optional thresholds make the measurement release-gating; incomplete reviews and digest drift return exit `2` instead of producing a favorable score. The dedicated metrics manifest stays offline, requires contained snapshot paths, and may record immutable HTTPS Git provenance without fetching it.
+
 `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. The JSON report includes tarball metadata such as filename, path, integrity, shasum, sizes, file count, and extracted package root so automation can prove which archive was scanned. 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, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, 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.
@@ -410,9 +425,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.46.1
+      - uses: Esquetta/CodexPluginDoctor@v1.48.0
         with:
-          version: "1.46.1"
+          version: "1.48.0"
           path: .
           runtime: "true"
           policy: codex-publish
@@ -439,7 +454,6 @@ docs/                 Public architecture, guides, rules, security, and contribu
 examples/             Manual plugin packs for local CLI testing
 src/                  CLI, validation logic, runtime probing, reports
 tests/                Fixture-based regression tests
-validation-sessions/  Real-world validation waves and tuning notes
 ```
 
 ## Validation Evidence
@@ -447,7 +461,6 @@ validation-sessions/  Real-world validation waves and tuning notes
 The validator is tuned against local fixtures and real marketplace-style plugin packages. See:
 
 - [Real-World Validation Workflow](./docs/guides/real-world-validation.md)
-- [Validation Sessions](./validation-sessions/README.md)
 - [Examples](./examples/README.md)
 - [Rule Catalog](./docs/rules/catalog.md)
 
@@ -467,9 +480,9 @@ npm run prepare-release
 npm run release-check
 ```
 
-`prepare-release` runs tests, builds the TypeScript output, and performs `npm pack --dry-run`. `release-check` adds release preflight checks for a clean git tree, existing npm versions, existing version tags, package/lockfile/changelog version consistency, tests, build, pack dry-run, fresh temp install audit, and publish dry-run.
-
-For plugin packages, `codex-plugin-doctor release check .` performs static readiness checks by default. Runtime probing executes package-local MCP servers and therefore requires an explicit `--runtime`; protected workflows can also require the approved runtime-plan digest.
+`prepare-release` runs tests, builds the TypeScript output, and performs `npm pack --dry-run`. `release-check` adds release preflight checks for a clean git tree, existing npm versions, existing version tags, package/lockfile/changelog version consistency, tests, build, pack dry-run, fresh temp install audit, and publish dry-run.
+
+For plugin packages, `codex-plugin-doctor release check .` performs static readiness checks by default. Runtime probing executes package-local MCP servers and therefore requires an explicit `--runtime`; protected workflows can also require the approved runtime-plan digest.
 
 Related docs:
 

package/dist/core/attestation.d.ts

@@ -95,6 +95,7 @@ export interface VerifyDoctorAttestationOptions {
     signingKey: string;
     artifactPath?: string;
 }
+export declare function buildPackageFingerprint(rootPath: string): Promise<PackageFingerprint>;
 export declare function buildDoctorAttestation(targetPath: string, options?: BuildDoctorAttestationOptions): Promise<DoctorAttestation>;
 export declare function verifyDoctorAttestation(artifactPath: string, targetPath: string, options: VerifyDoctorAttestationOptions): Promise<DoctorAttestationVerificationReport>;
 export declare function verifyDoctorAttestationObject(artifact: unknown, targetPath: string, options: VerifyDoctorAttestationOptions): Promise<DoctorAttestationVerificationReport>;

package/dist/core/attestation.js

@@ -61,7 +61,7 @@ async function collectFileEntries(rootPath, currentPath = rootPath) {
     }));
     return fileEntries.flat().sort((left, right) => left.relativePath.localeCompare(right.relativePath));
 }
-async function buildPackageFingerprint(rootPath) {
+export async function buildPackageFingerprint(rootPath) {
     const files = await collectFileEntries(rootPath);
     const bytes = files.reduce((total, file) => total + file.size, 0);
     const digest = sha256(stableStringify(files));

package/dist/core/corpus-quality-metrics.d.ts

@@ -0,0 +1,125 @@
+import type { ExternalCorpusMode, ExternalCorpusProfile, ExternalCorpusSourceType, FindingReviewClassification } from "./external-validation-corpus.js";
+export interface CorpusMetricThresholds {
+    minPrecision?: number;
+    minRecall?: number;
+    maxFalsePositiveRate?: number;
+}
+export interface CorpusMetricFindingReview {
+    findingId: string;
+    fingerprint: string;
+    classification: FindingReviewClassification;
+}
+export interface CorpusMetricSource {
+    repository: string;
+    revision: string;
+}
+export interface CorpusMetricTarget {
+    id: string;
+    profile: ExternalCorpusProfile;
+    sourceType: ExternalCorpusSourceType;
+    disclosure: "anonymized";
+    path: string;
+    mode: ExternalCorpusMode;
+    contentDigest: string;
+    source?: CorpusMetricSource;
+    reviews: CorpusMetricFindingReview[];
+}
+export interface CorpusMetricsManifest {
+    schemaVersion: "1.0.0";
+    thresholds?: CorpusMetricThresholds;
+    targets: CorpusMetricTarget[];
+}
+interface LoadedCorpusMetricTarget extends CorpusMetricTarget {
+    resolvedPath: string;
+}
+interface LoadedCorpusMetricsManifest extends CorpusMetricsManifest {
+    targets: LoadedCorpusMetricTarget[];
+}
+export interface CorpusMetricFinding {
+    findingId: string;
+    fingerprint: string;
+}
+export interface CorpusMetricCounts {
+    truePositives: number;
+    falsePositives: number;
+    falseNegatives: number;
+    resolvedFalsePositives: number;
+    unreviewed: number;
+    unclear: number;
+}
+export interface CorpusMetricValues {
+    precision: number | null;
+    recall: number | null;
+    falsePositiveRate: number | null;
+}
+export interface CorpusMetricOutcome extends CorpusMetricFinding {
+    classification: FindingReviewClassification | "unreviewed";
+    emitted: boolean;
+}
+export interface CorpusMetricReconciliation {
+    counts: CorpusMetricCounts;
+    metrics: CorpusMetricValues;
+    complete: boolean;
+    outcomes: CorpusMetricOutcome[];
+}
+export interface CorpusMetricThresholdCheck {
+    metric: keyof CorpusMetricValues;
+    operator: ">=" | "<=";
+    threshold: number;
+    actual: number | null;
+    passed: boolean;
+}
+export interface CorpusQualityMetricsTargetResult {
+    id: string;
+    profile: ExternalCorpusProfile;
+    sourceType: ExternalCorpusSourceType;
+    disclosure: "anonymized";
+    mode: ExternalCorpusMode;
+    source?: CorpusMetricSource;
+    digestMatched: boolean;
+    counts: CorpusMetricCounts;
+    metrics: CorpusMetricValues;
+    complete: boolean;
+    outcomes: CorpusMetricOutcome[];
+}
+export interface CorpusQualityMetricsReport {
+    schemaVersion: "1.0.0";
+    kind: "doctor.validation.corpus.metrics";
+    generatedAt: string;
+    version: string;
+    status: "pass" | "fail" | "incomplete";
+    exitCode: 0 | 1 | 2;
+    summary: CorpusMetricCounts & CorpusMetricValues & {
+        targetCount: number;
+        completeTargets: number;
+        incompleteTargets: number;
+    };
+    thresholds: CorpusMetricThresholds;
+    thresholdChecks: CorpusMetricThresholdCheck[];
+    targets: CorpusQualityMetricsTargetResult[];
+}
+export interface BuildCorpusMetricsOptions {
+    thresholds?: CorpusMetricThresholds;
+    environment?: {
+        env?: NodeJS.ProcessEnv;
+        platform?: NodeJS.Platform;
+    };
+    analyzeTarget?: (targetPath: string, mode: ExternalCorpusMode) => Promise<{
+        findings: CorpusMetricFinding[];
+    }>;
+    buildFingerprint?: (targetPath: string) => Promise<{
+        digest: string;
+    }>;
+}
+export declare class CorpusMetricsManifestError extends Error {
+    constructor(message: string);
+}
+export declare function loadCorpusMetricsManifest(manifestPath: string): Promise<LoadedCorpusMetricsManifest>;
+export declare function reconcileCorpusMetricFindings(reviews: CorpusMetricFindingReview[], actualFindings: CorpusMetricFinding[]): CorpusMetricReconciliation;
+export declare function buildCorpusQualityMetricsReport(manifestPath: string, options?: BuildCorpusMetricsOptions): Promise<CorpusQualityMetricsReport>;
+export declare function renderCorpusQualityMetricsJson(report: CorpusQualityMetricsReport): string;
+export declare function renderCorpusQualityMetricsText(report: CorpusQualityMetricsReport, options?: {
+    outputPath?: string | null;
+}): string;
+export declare function renderCorpusQualityMetricsMarkdown(report: CorpusQualityMetricsReport): string;
+export {};