codex-plugin-doctor 1.42.0 → 1.44.0

package/README.md

@@ -287,8 +287,10 @@ 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 check . --config .codex-doctor.json
-codex-plugin-doctor check . --history validation-history.jsonl
+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
 codex-plugin-doctor history validation-history.jsonl
 codex-plugin-doctor history validation-history.jsonl --json
 codex-plugin-doctor history validation-history.jsonl --fail-on-regression
@@ -334,9 +336,11 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `check --badge-json` emits Shields endpoint-compatible JSON such as `{"schemaVersion":1,"label":"doctor","message":"PASS","color":"brightgreen"}`. `check --badge-markdown` emits a static shields.io Markdown badge for README or release notes. Badge output is intentionally limited to single package checks, not `check --installed`.
 
-`check --history <path>` appends a compact JSONL validation snapshot after a single package check. `history <path>` reads the JSONL file and compares the latest run to the previous run, including status, finding-count deltas, and whether the latest run regressed. Add `history --json` for automation output or `history --fail-on-regression` when CI should fail after a worse latest run.
-
-`fix --dry-run` renders safe automatic fix plans without changing files. `fix --interactive --backup` shows the same numbered plan, then applies everything after `yes` or only selected action numbers such as `1,3`. `fix --apply --backup` applies supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
+`check --history <path>` appends a compact JSONL validation snapshot after a single package check. `history <path>` reads the JSONL file and compares the latest run to the previous run, including status, finding-count deltas, and whether the latest run regressed. Add `history --json` for automation output or `history --fail-on-regression` when CI should fail after a worse latest run.
+
+`baseline create <path> --output <path>` records the current fingerprinted findings for gradual CI adoption. A later `check <path> --baseline <path>` keeps matched findings visible in baseline metadata but gates only new active findings; reports summarize new, matched, and resolved counts. Commit the baseline for review and regenerate it deliberately after accepted findings change.
+
+`fix --dry-run` renders safe automatic fix plans without changing files. `fix --interactive --backup` shows the same numbered plan, then applies everything after `yes` or only selected action numbers such as `1,3`. `fix --apply --backup` applies supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
 
 Optional local policy file:
 
@@ -402,9 +406,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.42.0
+      - uses: Esquetta/CodexPluginDoctor@v1.44.0
         with:
-          version: "1.42.0"
+          version: "1.44.0"
           path: .
           runtime: "true"
           policy: codex-publish

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

@@ -0,0 +1,17 @@
+import type { CheckResult, FindingSeverity } from "../domain/types.js";
+export interface ValidationBaselineFinding {
+    id: string;
+    severity: FindingSeverity;
+    fingerprint: string;
+}
+export interface ValidationBaseline {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    findings: ValidationBaselineFinding[];
+}
+export declare function buildValidationBaseline(result: CheckResult): ValidationBaseline;
+export declare function writeValidationBaseline(baselinePath: string, baseline: ValidationBaseline): Promise<void>;
+export declare function readValidationBaseline(baselinePath: string): Promise<ValidationBaseline>;
+export declare function applyValidationBaseline(result: CheckResult, baseline: ValidationBaseline, options: {
+    failOnWarnings: boolean;
+}): CheckResult;

package/dist/core/validation-baseline.js

@@ -0,0 +1,83 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+const fingerprintPattern = /^[a-f0-9]{64}$/;
+export function buildValidationBaseline(result) {
+    const findings = new Map();
+    for (const finding of result.findings) {
+        if (finding.fingerprint && !findings.has(finding.fingerprint)) {
+            findings.set(finding.fingerprint, {
+                id: finding.id,
+                severity: finding.severity,
+                fingerprint: finding.fingerprint
+            });
+        }
+    }
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        findings: [...findings.values()]
+    };
+}
+export async function writeValidationBaseline(baselinePath, baseline) {
+    const absolutePath = path.resolve(baselinePath);
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, JSON.stringify(baseline, null, 2), "utf8");
+}
+export async function readValidationBaseline(baselinePath) {
+    const value = JSON.parse(await readFile(path.resolve(baselinePath), "utf8"));
+    if (!isValidationBaseline(value)) {
+        throw new Error("expected schemaVersion 1.0.0 and valid fingerprinted findings");
+    }
+    return value;
+}
+export function applyValidationBaseline(result, baseline, options) {
+    const baselineFingerprints = new Set(baseline.findings.map((finding) => finding.fingerprint));
+    const currentFingerprints = new Set(result.findings.flatMap((finding) => finding.fingerprint ? [finding.fingerprint] : []));
+    const baselinedFindings = [];
+    const findings = [];
+    for (const finding of result.findings) {
+        if (finding.fingerprint && baselineFingerprints.has(finding.fingerprint)) {
+            baselinedFindings.push(finding);
+        }
+        else {
+            findings.push(finding);
+        }
+    }
+    const hasFailures = findings.some((finding) => finding.severity === "fail");
+    const hasWarnings = findings.some((finding) => finding.severity === "warn");
+    const status = hasFailures || (options.failOnWarnings && hasWarnings)
+        ? "fail"
+        : hasWarnings
+            ? "warn"
+            : "pass";
+    return {
+        ...result,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        findings,
+        baselinedFindings,
+        baselineSummary: {
+            matched: baselinedFindings.length,
+            new: findings.length,
+            resolved: baseline.findings.filter((finding) => !currentFingerprints.has(finding.fingerprint)).length
+        }
+    };
+}
+function isValidationBaseline(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return candidate.schemaVersion === "1.0.0"
+        && typeof candidate.generatedAt === "string"
+        && !Number.isNaN(Date.parse(candidate.generatedAt))
+        && Array.isArray(candidate.findings)
+        && candidate.findings.every((finding) => finding
+            && typeof finding.id === "string"
+            && finding.id.length > 0
+            && (finding.severity === "warn" || finding.severity === "fail")
+            && typeof finding.fingerprint === "string"
+            && fingerprintPattern.test(finding.fingerprint))
+        && new Set(candidate.findings.map((finding) => finding.fingerprint)).size
+            === candidate.findings.length;
+}

package/dist/domain/types.d.ts

@@ -30,6 +30,13 @@ export interface CheckResult {
     suppressedFindings?: SuppressedFinding[];
     suppressionSummary?: SuppressionSummary;
     runtimeScorecard?: RuntimeScorecard;
+    baselinedFindings?: Finding[];
+    baselineSummary?: BaselineSummary;
+}
+export interface BaselineSummary {
+    matched: number;
+    new: number;
+    resolved: number;
 }
 export interface CheckOptions {
     runtime?: boolean;
@@ -59,6 +66,7 @@ export interface JsonReportSummary {
         warn: number;
         total: number;
     };
+    baseline?: BaselineSummary;
 }
 export interface JsonReport {
     schemaVersion: "1.0.0";
@@ -67,6 +75,7 @@ export interface JsonReport {
     findings: Finding[];
     suppressedFindings?: SuppressedFinding[];
     suppressionSummary?: SuppressionSummary;
+    baselinedFindings?: Finding[];
 }
 export type RuntimeCapabilityStatus = "pass" | "fail" | "warn" | "skipped" | "unsupported";
 export interface RuntimeScorecard {

package/dist/reporting/recommended-commands.d.ts

@@ -0,0 +1,2 @@
+import type { CheckResult } from "../domain/types.js";
+export declare function buildRecommendedCommands(result: CheckResult): string[];

package/dist/reporting/recommended-commands.js

@@ -0,0 +1,17 @@
+function quoteCliArg(value) {
+    return JSON.stringify(value);
+}
+export function buildRecommendedCommands(result) {
+    if (result.findings.length === 0) {
+        return [];
+    }
+    const target = quoteCliArg(result.targetPath);
+    const commands = [
+        `codex-plugin-doctor doctor recommend ${target}`,
+        `codex-plugin-doctor fix ${target} --dry-run`
+    ];
+    if (result.findings.some((finding) => finding.fingerprint)) {
+        commands.push(`codex-plugin-doctor suppress add ${target}`);
+    }
+    return commands;
+}

package/dist/reporting/render-json-report.js

@@ -16,7 +16,8 @@ export function buildJsonReport(result, options) {
                 fail: failCount,
                 warn: warnCount,
                 total: result.findings.length
-            }
+            },
+            ...(result.baselineSummary ? { baseline: result.baselineSummary } : {})
         },
         findings: result.findings,
         ...(result.suppressedFindings
@@ -24,6 +25,9 @@ export function buildJsonReport(result, options) {
             : {}),
         ...(result.suppressionSummary
             ? { suppressionSummary: result.suppressionSummary }
+            : {}),
+        ...(result.baselinedFindings
+            ? { baselinedFindings: result.baselinedFindings }
             : {})
     };
 }

package/dist/reporting/render-markdown-report.js

@@ -1,5 +1,6 @@
 import { formatFindingEvidenceLine } from "./format-finding-evidence.js";
 import { formatFindingFingerprintLine } from "./finding-fingerprint.js";
+import { buildRecommendedCommands } from "./recommended-commands.js";
 export function buildMarkdownReport(result, options) {
     const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
     const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
@@ -19,8 +20,11 @@ export function buildMarkdownReport(result, options) {
     if (result.suppressionSummary) {
         lines.push(`| Suppressions Applied | ${result.suppressionSummary.applied} |`, `| Suppressions Expired | ${result.suppressionSummary.expired} |`, `| Suppressions Invalid | ${result.suppressionSummary.invalid} |`);
     }
+    if (result.baselineSummary) {
+        lines.push(`| Baseline New | ${result.baselineSummary.new} |`, `| Baseline Matched | ${result.baselineSummary.matched} |`, `| Baseline Resolved | ${result.baselineSummary.resolved} |`);
+    }
     if (result.findings.length === 0 && !result.suppressedFindings?.length) {
-        lines.push("", "No findings.");
+        lines.push("", result.baselineSummary ? "No new findings." : "No findings.");
         return lines.join("\n");
     }
     if (result.runtimeScorecard) {
@@ -77,5 +81,12 @@ export function buildMarkdownReport(result, options) {
             lines.push("");
         }
     }
+    const recommendedCommands = buildRecommendedCommands(result);
+    if (recommendedCommands.length > 0) {
+        lines.push("", "## Recommended Commands", "");
+        for (const command of recommendedCommands) {
+            lines.push(`- \`${command}\``);
+        }
+    }
     return lines.join("\n");
 }

package/dist/reporting/render-text-report.js

@@ -1,6 +1,7 @@
 import { findRuleDefinition } from "../rules/rule-catalog.js";
 import { formatFindingEvidenceLine } from "./format-finding-evidence.js";
 import { formatFindingFingerprintLine } from "./finding-fingerprint.js";
+import { buildRecommendedCommands } from "./recommended-commands.js";
 function getCounts(result) {
     const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
     const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
@@ -38,6 +39,9 @@ export function renderTextReport(result, options = {}) {
     if (result.suppressionSummary) {
         lines.push(`Suppressions: ${result.suppressionSummary.applied} applied, ${result.suppressionSummary.expired} expired, ${result.suppressionSummary.invalid} invalid`);
     }
+    if (result.baselineSummary) {
+        lines.push(`Baseline: ${result.baselineSummary.new} new, ${result.baselineSummary.matched} matched, ${result.baselineSummary.resolved} resolved`);
+    }
     if (result.findings.length === 0 && !result.suppressedFindings?.length) {
         if (result.runtimeScorecard) {
             lines.push("", "Runtime Scorecard", "----------------");
@@ -50,7 +54,7 @@ export function renderTextReport(result, options = {}) {
             lines.push(`prompts/list: ${result.runtimeScorecard.promptsList}`);
             lines.push(`prompts/get: ${result.runtimeScorecard.promptGet}`);
         }
-        lines.push("", "No findings.");
+        lines.push("", result.baselineSummary ? "No new findings." : "No findings.");
         return lines.join("\n");
     }
     const failures = result.findings.filter((finding) => finding.severity === "fail");
@@ -118,5 +122,12 @@ export function renderTextReport(result, options = {}) {
         lines.push(`prompts/list: ${result.runtimeScorecard.promptsList}`);
         lines.push(`prompts/get: ${result.runtimeScorecard.promptGet}`);
     }
+    const recommendedCommands = buildRecommendedCommands(result);
+    if (recommendedCommands.length > 0) {
+        lines.push("", "Recommended Commands", "--------------------");
+        for (const command of recommendedCommands) {
+            lines.push(`- ${command}`);
+        }
+    }
     return lines.join("\n");
 }

package/dist/run-cli.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
 import { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } from "./audit/ecosystem-audit.js";
 import { appendValidationHistoryEntry, readValidationHistory, summarizeValidationHistory } from "./core/validation-history.js";
+import { applyValidationBaseline, buildValidationBaseline, readValidationBaseline, writeValidationBaseline } from "./core/validation-baseline.js";
 import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.js";
 import { applyInstallPreview, renderApplyInstallResult } from "./compatibility/apply-install-preview.js";
 import { buildClaudeDesktopInstallPreview, renderClaudeDesktopInstallPreview } from "./compatibility/claude-desktop-install-preview.js";
@@ -80,6 +81,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] [--changed-since <ref>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\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 suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\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 watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\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] [--output <path>] [--failures-only]|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 init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\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("Suppression governance: codex-plugin-doctor suppress list <path> [--fail-on-expired] [--fail-on-invalid] [--warn-expiring-within-days <days>]\n       codex-plugin-doctor suppress prune <path> [--apply] [--json]");
+    io.writeStderr("Baseline gating: codex-plugin-doctor baseline create <path> --output <path> [--runtime]\n       codex-plugin-doctor check <path> --baseline <path>");
 }
 const suppressUsageText = [
     "Usage:",
@@ -817,6 +819,31 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStdout(renderInstalledPlugins(installedPlugins));
         return 0;
     }
+    if (command === "baseline") {
+        if (maybePath !== "create") {
+            io.writeStderr("Usage: codex-plugin-doctor baseline create <path> --output <path> [--runtime]");
+            return 2;
+        }
+        const targetPath = remainingArgs[0];
+        const baselineFlags = remainingArgs.slice(1);
+        const outputIndex = baselineFlags.indexOf("--output");
+        const outputPath = outputIndex === -1 ? null : baselineFlags[outputIndex + 1];
+        if (!targetPath || targetPath.startsWith("--")) {
+            io.writeStderr("Missing target path for baseline create.");
+            return 2;
+        }
+        if (!outputPath || outputPath.startsWith("--")) {
+            io.writeStderr("baseline create requires --output <path>.");
+            return 2;
+        }
+        const result = await (options.runCheckImpl ?? runCheck)(targetPath, {
+            runtime: baselineFlags.includes("--runtime")
+        });
+        const baseline = buildValidationBaseline(result);
+        await writeValidationBaseline(outputPath, baseline);
+        io.writeStdout(`Baseline created: ${path.resolve(outputPath)}\nFindings: ${baseline.findings.length}`);
+        return 0;
+    }
     if (command === "doctor") {
         const doctorFlags = maybePath?.startsWith("--")
             ? [maybePath, ...remainingArgs]
@@ -2256,6 +2283,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
         : normalizedFlags[runtimeApprovalDigestIndex + 1];
     const changedSinceIndex = normalizedFlags.indexOf("--changed-since");
     const changedSinceRef = changedSinceIndex === -1 ? null : normalizedFlags[changedSinceIndex + 1];
+    const baselineIndex = normalizedFlags.indexOf("--baseline");
+    const baselinePath = baselineIndex === -1 ? null : normalizedFlags[baselineIndex + 1];
     if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
         io.writeStderr("Missing path after --output.");
         return 2;
@@ -2292,6 +2321,18 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("--changed-since requires a single package target.");
         return 2;
     }
+    if (baselineIndex !== -1 && (!baselinePath || baselinePath.startsWith("--"))) {
+        io.writeStderr("Missing path after --baseline.");
+        return 2;
+    }
+    if (baselinePath && checkInstalled) {
+        io.writeStderr("Baseline gating requires a single package target.");
+        return 2;
+    }
+    if (baselinePath && changedSinceRef) {
+        io.writeStderr("Use either --baseline or --changed-since, not both.");
+        return 2;
+    }
     if (runtimeApprovalDigestIndex !== -1 &&
         (!runtimeApprovalDigest || runtimeApprovalDigest.startsWith("--"))) {
         io.writeStderr("Missing digest after --runtime-approval-digest.");
@@ -2316,6 +2357,16 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("Runtime approval gating requires a single package target, not --installed.");
         return 2;
     }
+    let baseline = null;
+    if (baselinePath) {
+        try {
+            baseline = await readValidationBaseline(baselinePath);
+        }
+        catch (error) {
+            io.writeStderr(`Invalid baseline file: ${error.message}`);
+            return 2;
+        }
+    }
     const outputPolicy = determineOutputPolicy({
         jsonOutput: jsonOutput || badgeJsonOutput,
         markdownOutput: markdownOutput || badgeMarkdownOutput,
@@ -2447,12 +2498,18 @@ export async function runCli(args, io = defaultIo, options = {}) {
             return 2;
         }
     }
-    const result = applyDoctorConfig(await runCheckImpl(targetPath, {
+    const doctorConfig = applyPolicyToDoctorConfig(applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile), policy);
+    const configuredResult = applyDoctorConfig(await runCheckImpl(targetPath, {
         runtime: effectiveRuntimeProbeEnabled,
         runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
             ? (line) => io.writeStderr(line)
             : undefined
-    }), applyPolicyToDoctorConfig(applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile), policy));
+    }), doctorConfig);
+    const result = baseline
+        ? applyValidationBaseline(configuredResult, baseline, {
+            failOnWarnings: doctorConfig.failOnWarnings
+        })
+        : configuredResult;
     if (renderer) {
         if (result.status === "fail") {
             renderer.stopFailure("Validation failed");

package/package.json

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