codex-plugin-doctor 1.28.0 → 1.30.0

package/README.md

@@ -400,9 +400,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.28.0
+      - uses: Esquetta/CodexPluginDoctor@v1.30.0
         with:
-          version: "1.28.0"
+          version: "1.30.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/output-contract.js

@@ -73,6 +73,12 @@ const publicSchemaDefinitions = [
         outputKind: "doctor.suppress.remove",
         required: ["schemaVersion", "kind", "command", "configPath", "index", "suppression"]
     },
+    {
+        id: "doctor.suppress.prune.json",
+        command: "codex-plugin-doctor suppress prune <path> --apply --json",
+        outputKind: "doctor.suppress.prune",
+        required: ["schemaVersion", "kind", "command", "configPath", "applied", "removedCount", "removed"]
+    },
     {
         id: "doctor.history.json",
         command: "codex-plugin-doctor history <history.jsonl> --json",

package/dist/core/suppression-management.d.ts

@@ -13,6 +13,10 @@ export interface SuppressionMutationResult {
     index: number;
     suppression: unknown;
 }
+export interface SuppressionPruneResult {
+    config: RawDoctorConfig;
+    removed: ManagedSuppressionRecord[];
+}
 export type SuppressionManagementErrorCode = "suppression_non_array" | "suppression_invalid_record" | "suppression_duplicate_fingerprint" | "suppression_invalid_index" | "suppression_invalid_fingerprint" | "suppression_fingerprint_not_found" | "suppression_fingerprint_ambiguous";
 type SuppressionManagementErrorDetails = {
     code: SuppressionManagementErrorCode;
@@ -31,4 +35,5 @@ export declare function listSuppressions(config: RawDoctorConfig, now?: Date): M
 export declare function addSuppression(config: RawDoctorConfig, record: unknown): SuppressionMutationResult;
 export declare function removeSuppressionByIndex(config: RawDoctorConfig, index: number): SuppressionMutationResult;
 export declare function removeSuppressionByFingerprint(config: RawDoctorConfig, fingerprint: string): SuppressionMutationResult;
+export declare function pruneSuppressions(config: RawDoctorConfig, now?: Date): SuppressionPruneResult;
 export {};

package/dist/core/suppression-management.js

@@ -168,3 +168,14 @@ export function removeSuppressionByFingerprint(config, fingerprint) {
     }
     return removeSuppressionByIndex(config, matches[0]);
 }
+export function pruneSuppressions(config, now = new Date()) {
+    const { suppressions } = readSuppressions(config);
+    const managedSuppressions = listSuppressions(config, now);
+    const removed = managedSuppressions.filter((suppression) => suppression.status !== "active");
+    const removedIndexes = new Set(removed.map((suppression) => suppression.index));
+    const nextSuppressions = suppressions.filter((_suppression, index) => !removedIndexes.has(index));
+    return {
+        config: copyConfigWithSuppressions(config, nextSuppressions),
+        removed
+    };
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { CheckOptions, CheckResult } from "./domain/types.js";
 export { applyDoctorConfig, loadDoctorConfig, type DoctorConfig } from "./core/doctor-config.js";
 export { readRawDoctorConfig, resolveDoctorConfigPath, writeRawDoctorConfig, type LoadedDoctorConfig, type RawDoctorConfig } from "./core/doctor-config-store.js";
 export { classifySuppressionRecord, isValidSuppressionFingerprint, isSuppressionExpired, validateSuppressionRecord, type ClassifiedSuppressionRecord, type InvalidSuppressionRecord, type SuppressionRecordField, type ValidSuppressionRecord } from "./core/suppression-record.js";
-export { addSuppression, listSuppressions, removeSuppressionByFingerprint, removeSuppressionByIndex, SuppressionManagementError, type ManagedSuppressionRecord, type SuppressionManagementErrorCode, type SuppressionMutationResult } from "./core/suppression-management.js";
+export { addSuppression, listSuppressions, pruneSuppressions, removeSuppressionByFingerprint, removeSuppressionByIndex, SuppressionManagementError, type ManagedSuppressionRecord, type SuppressionManagementErrorCode, type SuppressionMutationResult, type SuppressionPruneResult } from "./core/suppression-management.js";
 export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard, type SecurityAudit } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson, type BuildTrustScoreOptions, type TrustScoreReport } from "./security/trust-score.js";

package/dist/index.js

@@ -2,7 +2,7 @@ import { validatePlugin } from "./core/validate-plugin.js";
 export { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
 export { readRawDoctorConfig, resolveDoctorConfigPath, writeRawDoctorConfig } from "./core/doctor-config-store.js";
 export { classifySuppressionRecord, isValidSuppressionFingerprint, isSuppressionExpired, validateSuppressionRecord } from "./core/suppression-record.js";
-export { addSuppression, listSuppressions, removeSuppressionByFingerprint, removeSuppressionByIndex, SuppressionManagementError } from "./core/suppression-management.js";
+export { addSuppression, listSuppressions, pruneSuppressions, removeSuppressionByFingerprint, removeSuppressionByIndex, SuppressionManagementError } from "./core/suppression-management.js";
 export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson } from "./security/trust-score.js";

package/dist/reporting/render-suppression-management.d.ts

@@ -1,7 +1,13 @@
-import type { ManagedSuppressionRecord, SuppressionMutationResult } from "../core/suppression-management.js";
+import type { ManagedSuppressionRecord, SuppressionMutationResult, SuppressionPruneResult } from "../core/suppression-management.js";
 type SuppressionMutationCommand = "suppress.add" | "suppress.remove";
 export declare function renderSuppressionList(configPath: string, suppressions: ManagedSuppressionRecord[]): string;
 export declare function renderSuppressionListJson(configPath: string, suppressions: ManagedSuppressionRecord[]): string;
 export declare function renderSuppressionMutation(command: SuppressionMutationCommand, configPath: string, result: SuppressionMutationResult): string;
 export declare function renderSuppressionMutationJson(command: SuppressionMutationCommand, configPath: string, result: SuppressionMutationResult): string;
+export declare function renderSuppressionPrune(configPath: string, result: SuppressionPruneResult, options: {
+    applied: boolean;
+}): string;
+export declare function renderSuppressionPruneJson(configPath: string, result: SuppressionPruneResult, options: {
+    applied: boolean;
+}): string;
 export {};

package/dist/reporting/render-suppression-management.js

@@ -115,3 +115,38 @@ export function renderSuppressionMutationJson(command, configPath, result) {
         suppression: buildMutationSummary(result.suppression)
     }, null, 2);
 }
+export function renderSuppressionPrune(configPath, result, options) {
+    const lines = [
+        "Action: Prune",
+        `Mode: ${options.applied ? "apply" : "dry-run"}`,
+        `Config: ${configPath}`,
+        `Removed suppressions: ${result.removed.length}`
+    ];
+    if (result.removed.length === 0) {
+        lines.push("", "No expired or invalid suppressions to prune.");
+        return lines.join("\n");
+    }
+    lines.push("", "Removed", "-------");
+    for (const suppression of result.removed) {
+        const entry = buildListEntry(suppression);
+        if (entry.status === "invalid") {
+            lines.push(`[${entry.index}] INVALID ${entry.invalidField}`);
+            continue;
+        }
+        lines.push(`[${entry.index}] ${entry.status.toUpperCase()} ${entry.fingerprint}`);
+        lines.push(`  Reason: ${entry.reason}`);
+        lines.push(`  Expires: ${entry.expiresAt}`);
+    }
+    return lines.join("\n");
+}
+export function renderSuppressionPruneJson(configPath, result, options) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        kind: "doctor.suppress.prune",
+        command: "suppress.prune",
+        configPath,
+        applied: options.applied,
+        removedCount: result.removed.length,
+        removed: result.removed.map(buildListEntry)
+    }, null, 2);
+}

package/dist/run-cli.js

@@ -44,7 +44,7 @@ import { renderCompatibilityReport } from "./reporting/render-compatibility-repo
 import { renderHistorySummary } from "./reporting/render-history-summary.js";
 import { renderJsonReport } from "./reporting/render-json-report.js";
 import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
-import { renderSuppressionList, renderSuppressionListJson, renderSuppressionMutation, renderSuppressionMutationJson } from "./reporting/render-suppression-management.js";
+import { renderSuppressionList, renderSuppressionListJson, renderSuppressionMutation, renderSuppressionMutationJson, renderSuppressionPrune, renderSuppressionPruneJson } from "./reporting/render-suppression-management.js";
 import { renderRuleExplanation } from "./reporting/render-rule-explanation.js";
 import { renderSarifReport } from "./reporting/render-sarif-report.js";
 import { renderTextReport } from "./reporting/render-text-report.js";
@@ -56,7 +56,7 @@ import { createLiveStatusRenderer } from "./terminal/live-status-renderer.js";
 import { determineOutputPolicy } from "./terminal/output-policy.js";
 import { getSpinner } from "./terminal/spinner-registry.js";
 import { packageVersion } from "./version.js";
-import { addSuppression, listSuppressions, readRawDoctorConfig, removeSuppressionByFingerprint, removeSuppressionByIndex, SuppressionManagementError, writeRawDoctorConfig } from "./index.js";
+import { addSuppression, listSuppressions, pruneSuppressions, readRawDoctorConfig, removeSuppressionByFingerprint, removeSuppressionByIndex, SuppressionManagementError, writeRawDoctorConfig } from "./index.js";
 const defaultIo = {
     writeStdout(message) {
         process.stdout.write(`${message}\n`);
@@ -79,12 +79,14 @@ 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 audit deps <path> [--json] [--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>]\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 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]");
 }
 const suppressUsageText = [
     "Usage:",
     "       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]",
-    "       codex-plugin-doctor suppress list <path> [--config <path>] [--json]",
-    "       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]"
+    "       codex-plugin-doctor suppress list <path> [--config <path>] [--json] [--fail-on-expired] [--fail-on-invalid] [--warn-expiring-within-days <days>]",
+    "       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]",
+    "       codex-plugin-doctor suppress prune <path> [--config <path>] [--apply] [--json]"
 ].join("\n");
 function printSuppressUsage(io) {
     io.writeStderr(suppressUsageText);
@@ -113,7 +115,10 @@ function parseSuppressCommand(args) {
             showUsage: true
         };
     }
-    if (action !== "add" && action !== "list" && action !== "remove") {
+    if (action !== "add" &&
+        action !== "list" &&
+        action !== "remove" &&
+        action !== "prune") {
         return {
             message: `Unknown suppress action: ${action}.`,
             showUsage: true
@@ -131,6 +136,10 @@ function parseSuppressCommand(args) {
     let reason = null;
     let expiresAt = null;
     let indexValue = null;
+    let failOnExpired = false;
+    let failOnInvalid = false;
+    let apply = false;
+    let warnExpiringWithinDays = null;
     const seenFlags = new Set();
     const markSeenFlag = (flag) => {
         if (seenFlags.has(flag)) {
@@ -168,6 +177,59 @@ function parseSuppressCommand(args) {
             index += 1;
             continue;
         }
+        if (action === "list" && flag === "--fail-on-expired") {
+            const duplicateError = markSeenFlag(flag);
+            if (duplicateError) {
+                return duplicateError;
+            }
+            failOnExpired = true;
+            continue;
+        }
+        if (action === "list" && flag === "--fail-on-invalid") {
+            const duplicateError = markSeenFlag(flag);
+            if (duplicateError) {
+                return duplicateError;
+            }
+            failOnInvalid = true;
+            continue;
+        }
+        if (action === "list" && flag === "--warn-expiring-within-days") {
+            const duplicateError = markSeenFlag(flag);
+            if (duplicateError) {
+                return duplicateError;
+            }
+            const value = flags[index + 1];
+            if (!value || value.startsWith("--")) {
+                return {
+                    message: "Missing days after --warn-expiring-within-days.",
+                    showUsage: false
+                };
+            }
+            if (!/^\d+$/.test(value)) {
+                return {
+                    message: "--warn-expiring-within-days must be a non-negative integer.",
+                    showUsage: false
+                };
+            }
+            const parsedDays = Number(value);
+            if (!Number.isSafeInteger(parsedDays)) {
+                return {
+                    message: "--warn-expiring-within-days must be a non-negative integer.",
+                    showUsage: false
+                };
+            }
+            warnExpiringWithinDays = parsedDays;
+            index += 1;
+            continue;
+        }
+        if (action === "prune" && flag === "--apply") {
+            const duplicateError = markSeenFlag(flag);
+            if (duplicateError) {
+                return duplicateError;
+            }
+            apply = true;
+            continue;
+        }
         if (action === "add" && flag === "--fingerprint") {
             const duplicateError = markSeenFlag(flag);
             if (duplicateError) {
@@ -258,7 +320,19 @@ function parseSuppressCommand(args) {
             action,
             targetPath,
             configPath,
-            jsonOutput
+            jsonOutput,
+            failOnExpired,
+            failOnInvalid,
+            warnExpiringWithinDays
+        };
+    }
+    if (action === "prune") {
+        return {
+            action,
+            targetPath,
+            configPath,
+            jsonOutput,
+            apply
         };
     }
     if (action === "add") {
@@ -353,6 +427,38 @@ function defaultSuppressionExpiry(now) {
     expiry.setDate(expiry.getDate() + 30);
     return formatLocalDate(expiry);
 }
+function parseSuppressionDateUtcStart(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match) {
+        return null;
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const timestamp = Date.UTC(year, month - 1, day);
+    const date = new Date(timestamp);
+    return date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day
+        ? timestamp
+        : null;
+}
+function listExpiringSuppressionIndexes(suppressions, now, withinDays) {
+    const dayMs = 24 * 60 * 60 * 1000;
+    const todayUtc = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    const cutoffUtc = todayUtc + withinDays * dayMs;
+    return suppressions.flatMap((suppression) => {
+        if (suppression.status !== "active" || !suppression.expiresAt) {
+            return [];
+        }
+        const expiresAtUtc = parseSuppressionDateUtcStart(suppression.expiresAt);
+        return expiresAtUtc !== null &&
+            expiresAtUtc >= todayUtc &&
+            expiresAtUtc <= cutoffUtc
+            ? [suppression.index]
+            : [];
+    });
+}
 function parseInteractiveSelection(answer, count) {
     const trimmed = answer.trim();
     if (!/^\d+$/.test(trimmed)) {
@@ -380,7 +486,8 @@ function renderInteractiveSuppressionCandidates(suppressions) {
 }
 async function executeSuppressCommand(command, io, options = {}) {
     const writeConfig = options.writeRawDoctorConfigImpl ?? writeRawDoctorConfig;
-    if (command.action !== "list" && command.interactive) {
+    if ((command.action === "add" || command.action === "remove") &&
+        command.interactive) {
         if (command.jsonOutput) {
             io.writeStderr(`Interactive suppress ${command.action} does not support --json.`);
             return 2;
@@ -395,9 +502,34 @@ async function executeSuppressCommand(command, io, options = {}) {
         const now = options.now?.() ?? new Date();
         if (command.action === "list") {
             const suppressions = listSuppressions(rawConfig.value, now);
+            const expiredCount = suppressions.filter((suppression) => suppression.status === "expired").length;
+            const invalidCount = suppressions.filter((suppression) => suppression.status === "invalid").length;
             io.writeStdout(command.jsonOutput
                 ? renderSuppressionListJson(rawConfig.configPath, suppressions)
                 : renderSuppressionList(rawConfig.configPath, suppressions));
+            if (command.warnExpiringWithinDays !== null) {
+                const expiringIndexes = listExpiringSuppressionIndexes(suppressions, now, command.warnExpiringWithinDays);
+                if (expiringIndexes.length > 0) {
+                    io.writeStderr(`Warning: ${expiringIndexes.length} suppression(s) expire within ${command.warnExpiringWithinDays} day(s): indexes ${expiringIndexes.join(", ")}.`);
+                }
+            }
+            return (command.failOnExpired && expiredCount > 0) ||
+                (command.failOnInvalid && invalidCount > 0)
+                ? 1
+                : 0;
+        }
+        if (command.action === "prune") {
+            const result = pruneSuppressions(rawConfig.value, now);
+            if (command.apply && result.removed.length > 0) {
+                await writeConfig(rawConfig.configPath, result.config);
+            }
+            io.writeStdout(command.jsonOutput
+                ? renderSuppressionPruneJson(rawConfig.configPath, result, {
+                    applied: command.apply
+                })
+                : renderSuppressionPrune(rawConfig.configPath, result, {
+                    applied: command.apply
+                }));
             return 0;
         }
         if (command.action === "add") {

package/package.json

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