codex-plugin-doctor 0.13.0 → 0.14.0

package/README.md

@@ -180,6 +180,8 @@ codex-plugin-doctor doctor recommend .
 codex-plugin-doctor doctor recommend . --json --output recommendations.json
 codex-plugin-doctor doctor trust .
 codex-plugin-doctor doctor trust . --json --output trust-score.json
+codex-plugin-doctor doctor perf .
+codex-plugin-doctor doctor perf . --json --output perf.json
 codex-plugin-doctor doctor export --bundle .
 codex-plugin-doctor doctor export --bundle . --output doctor-bundle.json
 codex-plugin-doctor doctor snapshot
@@ -190,6 +192,8 @@ codex-plugin-doctor doctor --update-check
 codex-plugin-doctor audit --installed
 codex-plugin-doctor audit --installed --security --compat
 codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json
+codex-plugin-doctor audit --installed --security --compat --cache
+codex-plugin-doctor audit --installed --changed --cache
 codex-plugin-doctor mcp .
 codex-plugin-doctor mcp . --json
 codex-plugin-doctor mcp . --json --output mcp-doctor.json
@@ -246,9 +250,9 @@ 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 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 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 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. `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.
+`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.
 
 `--policy codex-publish|mcp-strict|security` applies opinionated gates without requiring a local `.codex-doctor.json`. `codex-publish` fails warnings and enables runtime probes for release checks, `mcp-strict` does the same for MCP-heavy packages, and `security` fails warning-level security findings so advisory risks can block a local audit or CI gate.
 

package/dist/audit/ecosystem-audit-cache.d.ts

@@ -0,0 +1,15 @@
+import type { EcosystemAuditPluginResult } from "./ecosystem-audit.js";
+import type { InstalledPlugin } from "../core/discover-installed-plugins.js";
+export interface EcosystemAuditCacheEntry {
+    fingerprint: string;
+    cachedAt: string;
+    result: EcosystemAuditPluginResult;
+}
+export interface EcosystemAuditCacheFile {
+    schemaVersion: "1.0.0";
+    entries: Record<string, EcosystemAuditCacheEntry>;
+}
+export declare function resolveEcosystemAuditCachePath(env?: Record<string, string | undefined>, cachePath?: string | null): string;
+export declare function loadEcosystemAuditCache(cachePath: string): Promise<EcosystemAuditCacheFile>;
+export declare function writeEcosystemAuditCache(cachePath: string, cache: EcosystemAuditCacheFile): Promise<void>;
+export declare function fingerprintInstalledPlugin(plugin: InstalledPlugin): Promise<string>;

package/dist/audit/ecosystem-audit-cache.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const skippedDirectories = new Set([
+    ".git",
+    "coverage",
+    "dist",
+    "node_modules",
+    "validation-artifacts-local",
+    "validation-sessions"
+]);
+export function resolveEcosystemAuditCachePath(env = process.env, cachePath) {
+    if (cachePath) {
+        return path.resolve(cachePath);
+    }
+    const codexHome = env.CODEX_HOME
+        ? path.resolve(env.CODEX_HOME)
+        : path.join(os.homedir(), ".codex");
+    return path.join(codexHome, "plugin-doctor", "audit-cache.json");
+}
+export async function loadEcosystemAuditCache(cachePath) {
+    try {
+        const parsed = JSON.parse(await readFile(cachePath, "utf8"));
+        if (parsed.schemaVersion === "1.0.0" && parsed.entries && typeof parsed.entries === "object") {
+            return {
+                schemaVersion: "1.0.0",
+                entries: parsed.entries
+            };
+        }
+    }
+    catch {
+        // Invalid or missing cache files are treated as cold caches.
+    }
+    return {
+        schemaVersion: "1.0.0",
+        entries: {}
+    };
+}
+export async function writeEcosystemAuditCache(cachePath, cache) {
+    await mkdir(path.dirname(cachePath), { recursive: true });
+    await writeFile(cachePath, JSON.stringify(cache, null, 2), "utf8");
+}
+async function walkFingerprintEntries(rootPath, currentPath = rootPath) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    const fingerprintEntries = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const entryPath = path.join(currentPath, entry.name);
+        if (entry.isDirectory()) {
+            if (skippedDirectories.has(entry.name)) {
+                continue;
+            }
+            fingerprintEntries.push(...(await walkFingerprintEntries(rootPath, entryPath)));
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        const details = await stat(entryPath);
+        const relativePath = path.relative(rootPath, entryPath).replace(/\\/g, "/");
+        fingerprintEntries.push(`${relativePath}\t${details.size}\t${Math.trunc(details.mtimeMs)}`);
+    }
+    return fingerprintEntries;
+}
+export async function fingerprintInstalledPlugin(plugin) {
+    const hash = createHash("sha256");
+    hash.update(plugin.name);
+    hash.update("\n");
+    hash.update(plugin.version ?? "");
+    hash.update("\n");
+    hash.update(plugin.relativePath);
+    hash.update("\n");
+    for (const entry of await walkFingerprintEntries(plugin.rootPath)) {
+        hash.update(entry);
+        hash.update("\n");
+    }
+    return hash.digest("hex");
+}

package/dist/audit/ecosystem-audit.d.ts

@@ -9,12 +9,18 @@ export interface EcosystemAuditOptions {
     includeSecurity?: boolean;
     includeCompatibility?: boolean;
     failOnWarnings?: boolean;
+    cache?: {
+        enabled?: boolean;
+        changedOnly?: boolean;
+        cachePath?: string | null;
+    };
     validatePlugin: (targetPath: string) => Promise<CheckResult>;
 }
 export interface EcosystemAuditPluginResult {
     plugin: InstalledPlugin;
     status: "pass" | "warn" | "fail";
     validation: CheckResult;
+    cached?: boolean;
     security?: SecurityAudit;
     compatibility?: CompatibilityMatrix;
 }
@@ -27,6 +33,8 @@ export interface EcosystemAuditReport {
         pass: number;
         warn: number;
         fail: number;
+        cached: number;
+        skippedUnchanged: number;
     };
     plugins: EcosystemAuditPluginResult[];
     priorityActions: string[];

package/dist/audit/ecosystem-audit.js

@@ -1,6 +1,9 @@
+import path from "node:path";
 import { buildCompatibilityMatrix, matrixExitCode } from "../compatibility/compatibility-matrix.js";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "../core/discover-installed-plugins.js";
 import { buildSecurityAudit } from "../security/security-audit.js";
+import { packageVersion } from "../version.js";
+import { fingerprintInstalledPlugin, loadEcosystemAuditCache, resolveEcosystemAuditCachePath, writeEcosystemAuditCache } from "./ecosystem-audit-cache.js";
 function mergeStatus(statuses) {
     if (statuses.includes("fail")) {
         return "fail";
@@ -19,12 +22,23 @@ function compatibilityStatus(matrix) {
     }
     return matrix.results.some((result) => result.status === "warn") ? "warn" : "pass";
 }
-function summarizePlugins(plugins) {
+function cacheKeyForPlugin(plugin, options) {
+    return [
+        path.resolve(plugin.rootPath).toLowerCase(),
+        `version=${packageVersion}`,
+        `security=${Boolean(options.includeSecurity)}`,
+        `compatibility=${Boolean(options.includeCompatibility)}`,
+        `failOnWarnings=${Boolean(options.failOnWarnings)}`
+    ].join("\n");
+}
+function summarizePlugins(plugins, skippedUnchanged) {
     return {
         totalPlugins: plugins.length,
         pass: plugins.filter((plugin) => plugin.status === "pass").length,
         warn: plugins.filter((plugin) => plugin.status === "warn").length,
-        fail: plugins.filter((plugin) => plugin.status === "fail").length
+        fail: plugins.filter((plugin) => plugin.status === "fail").length,
+        cached: plugins.filter((plugin) => plugin.cached).length,
+        skippedUnchanged
     };
 }
 function buildPriorityActions(plugins) {
@@ -58,7 +72,35 @@ export async function buildEcosystemAudit(options) {
         platform: options.platform
     };
     const plugins = [];
+    const cacheEnabled = Boolean(options.cache?.enabled);
+    const changedOnly = Boolean(options.cache?.changedOnly);
+    const cachePath = cacheEnabled
+        ? resolveEcosystemAuditCachePath(options.env, options.cache?.cachePath)
+        : null;
+    const cache = cachePath
+        ? await loadEcosystemAuditCache(cachePath)
+        : null;
+    let skippedUnchanged = 0;
     for (const plugin of installedPlugins) {
+        const cacheKey = cacheKeyForPlugin(plugin, options);
+        const fingerprint = cache
+            ? await fingerprintInstalledPlugin(plugin)
+            : null;
+        const cachedEntry = cache && fingerprint
+            ? cache.entries[cacheKey]
+            : undefined;
+        if (cachedEntry && cachedEntry.fingerprint === fingerprint) {
+            if (changedOnly) {
+                skippedUnchanged += 1;
+                continue;
+            }
+            plugins.push({
+                ...cachedEntry.result,
+                plugin,
+                cached: true
+            });
+            continue;
+        }
         const validation = await options.validatePlugin(plugin.rootPath);
         const security = options.includeSecurity
             ? await buildSecurityAudit(plugin.rootPath)
@@ -74,15 +116,26 @@ export async function buildEcosystemAudit(options) {
         const status = options.failOnWarnings && rawStatus === "warn"
             ? "fail"
             : rawStatus;
-        plugins.push({
+        const result = {
             plugin,
             status,
             validation,
             ...(security ? { security } : {}),
             ...(compatibility ? { compatibility } : {})
-        });
+        };
+        plugins.push(result);
+        if (cache && fingerprint) {
+            cache.entries[cacheKey] = {
+                fingerprint,
+                cachedAt: new Date().toISOString(),
+                result
+            };
+        }
+    }
+    if (cache && cachePath) {
+        await writeEcosystemAuditCache(cachePath, cache);
     }
-    const summary = summarizePlugins(plugins);
+    const summary = summarizePlugins(plugins, skippedUnchanged);
     const status = summary.fail > 0
         ? "fail"
         : summary.warn > 0
@@ -106,7 +159,8 @@ export function renderEcosystemAudit(report) {
         "=====================",
         `Status: ${report.status.toUpperCase()}`,
         `Installed plugins: ${report.summary.totalPlugins}`,
-        `Summary: ${report.summary.fail} fail, ${report.summary.warn} warn, ${report.summary.pass} pass`
+        `Summary: ${report.summary.fail} fail, ${report.summary.warn} warn, ${report.summary.pass} pass`,
+        `Cache: ${report.summary.cached} reused, ${report.summary.skippedUnchanged} skipped unchanged`
     ];
     if (report.plugins.length === 0) {
         lines.push("", "No installed Codex plugins found.");
@@ -126,6 +180,9 @@ export function renderEcosystemAudit(report) {
                 .join(", ");
             lines.push(`  Compatibility: ${compatibilitySummary}`);
         }
+        if (item.cached) {
+            lines.push("  Cache: reused");
+        }
     }
     if (report.priorityActions.length > 0) {
         lines.push("", "Priority Actions", "----------------");

package/dist/core/doctor-export-bundle.d.ts

@@ -1,8 +1,8 @@
-import { type CompatibilityEnvironment, type CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+import type { CompatibilityEnvironment, CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
 import type { JsonReport } from "../domain/types.js";
-import { type DoctorRecommendationsReport } from "./doctor-recommendations.js";
-import { type SecurityAudit } from "../security/security-audit.js";
-import { type TrustScoreReport } from "../security/trust-score.js";
+import type { DoctorRecommendationsReport } from "./doctor-recommendations.js";
+import type { SecurityAudit } from "../security/security-audit.js";
+import type { TrustScoreReport } from "../security/trust-score.js";
 export interface DoctorExportBundle {
     schemaVersion: "1.0.0";
     generatedAt: string;

package/dist/core/doctor-export-bundle.js

@@ -1,12 +1,4 @@
-import path from "node:path";
-import { buildCompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
-import { applyDoctorConfig, loadDoctorConfig } from "./doctor-config.js";
-import { buildJsonReport } from "../reporting/render-json-report.js";
-import { buildDoctorRecommendations } from "./doctor-recommendations.js";
-import { buildSecurityAudit } from "../security/security-audit.js";
-import { buildTrustScore } from "../security/trust-score.js";
-import { validatePlugin } from "./validate-plugin.js";
-import { packageVersion } from "../version.js";
+import { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
 function redactString(value) {
     return value
         .replace(/sk-[A-Za-z0-9_-]{12,}/g, "[REDACTED_SECRET]")
@@ -30,27 +22,8 @@ function redactValue(value) {
     return value;
 }
 export async function buildDoctorExportBundle(targetPath, environment = {}) {
-    const rootPath = path.resolve(targetPath);
-    const [rawValidation, security, compatibility, recommendations, trust] = await Promise.all([
-        validatePlugin(rootPath),
-        buildSecurityAudit(rootPath),
-        buildCompatibilityMatrix(rootPath, environment),
-        buildDoctorRecommendations(rootPath, { environment }),
-        buildTrustScore(rootPath)
-    ]);
-    const validation = applyDoctorConfig(rawValidation, await loadDoctorConfig(rootPath));
-    return {
-        schemaVersion: "1.0.0",
-        generatedAt: new Date().toISOString(),
-        kind: "doctor.export.bundle",
-        version: packageVersion,
-        targetPath: rootPath,
-        validation: buildJsonReport(validation, { runtimeProbeEnabled: false }),
-        security,
-        compatibility,
-        recommendations,
-        trust
-    };
+    const analysis = await buildPackageAnalysis(targetPath, { environment });
+    return buildDoctorExportBundleFromAnalysis(analysis, buildDoctorRecommendationsFromAnalysis(analysis));
 }
 export function renderDoctorExportBundleJson(bundle) {
     return JSON.stringify(redactValue(bundle), null, 2);

package/dist/core/doctor-recommendations.d.ts

@@ -1,6 +1,6 @@
-import { type CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
+import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
 import type { CheckResult } from "../domain/types.js";
-import { type SecurityAudit } from "../security/security-audit.js";
+import type { SecurityAudit } from "../security/security-audit.js";
 export type RecommendationPriority = "blocker" | "high" | "medium" | "info";
 export type RecommendationCategory = "validation" | "security" | "compatibility" | "release";
 export interface DoctorRecommendationAction {

package/dist/core/doctor-recommendations.js

@@ -1,139 +1,9 @@
-import path from "node:path";
-import { buildCompatibilityMatrix, matrixExitCode } from "../compatibility/compatibility-matrix.js";
-import { applyDoctorConfig, loadDoctorConfig } from "./doctor-config.js";
-import { buildSecurityAudit } from "../security/security-audit.js";
-import { validatePlugin } from "./validate-plugin.js";
-const priorityRank = {
-    blocker: 0,
-    high: 1,
-    medium: 2,
-    info: 3
-};
-function countActions(actions) {
-    return {
-        blocker: actions.filter((action) => action.priority === "blocker").length,
-        high: actions.filter((action) => action.priority === "high").length,
-        medium: actions.filter((action) => action.priority === "medium").length,
-        info: actions.filter((action) => action.priority === "info").length
-    };
-}
-function priorityForFinding(finding) {
-    if (finding.severity === "fail") {
-        return "blocker";
-    }
-    return finding.id.startsWith("plugin.security.") ? "high" : "medium";
-}
-function categoryForFinding(finding) {
-    return finding.id.startsWith("plugin.security.") ? "security" : "validation";
-}
-function commandForCategory(category, targetPath) {
-    if (category === "security") {
-        return `codex-plugin-doctor security ${targetPath} --scorecard`;
-    }
-    if (category === "compatibility") {
-        return `codex-plugin-doctor compat ${targetPath} --all --scorecard`;
-    }
-    return `codex-plugin-doctor check ${targetPath} --explain`;
-}
-function actionFromFinding(finding, targetPath) {
-    const category = categoryForFinding(finding);
-    return {
-        priority: priorityForFinding(finding),
-        category,
-        findingId: finding.id,
-        title: finding.message,
-        reason: finding.impact,
-        nextCommand: commandForCategory(category, targetPath)
-    };
-}
-function dedupeActions(actions) {
-    const seen = new Set();
-    return actions.filter((action) => {
-        const key = `${action.category}\n${action.findingId ?? action.title}\n${action.reason}`;
-        if (seen.has(key)) {
-            return false;
-        }
-        seen.add(key);
-        return true;
-    });
-}
-function actionsFromCompatibility(matrix, targetPath) {
-    return matrix.results
-        .filter((result) => result.status === "fail")
-        .map((result) => ({
-        priority: "high",
-        category: "compatibility",
-        title: `${result.client} compatibility failed.`,
-        reason: result.summary,
-        nextCommand: commandForCategory("compatibility", targetPath)
-    }));
-}
-function sortActions(actions) {
-    return [...actions].sort((left, right) => {
-        const priorityDelta = priorityRank[left.priority] - priorityRank[right.priority];
-        if (priorityDelta !== 0) {
-            return priorityDelta;
-        }
-        return left.category.localeCompare(right.category);
-    });
-}
+import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
 export async function buildDoctorRecommendations(targetPath, options = {}) {
-    const rootPath = path.resolve(targetPath);
-    const runCheck = options.runCheck ?? validatePlugin;
-    const [rawValidation, security, compatibility] = await Promise.all([
-        runCheck(rootPath),
-        buildSecurityAudit(rootPath),
-        buildCompatibilityMatrix(rootPath, options.environment ?? {})
-    ]);
-    const validation = applyDoctorConfig(rawValidation, await loadDoctorConfig(rootPath));
-    const actions = sortActions(dedupeActions([
-        ...validation.findings.map((finding) => actionFromFinding(finding, rootPath)),
-        ...security.findings.map((finding) => actionFromFinding(finding, rootPath)),
-        ...actionsFromCompatibility(compatibility, rootPath)
-    ]));
-    const finalActions = actions.length > 0
-        ? actions
-        : [
-            {
-                priority: "info",
-                category: "release",
-                title: "No blocker actions.",
-                reason: "The package has no validation, security, or compatibility blockers in this recommendation pass.",
-                nextCommand: `codex-plugin-doctor check ${rootPath} --profile publish`
-            }
-        ];
-    const status = finalActions.some((action) => action.priority === "blocker")
-        ? "fail"
-        : finalActions.some((action) => action.priority === "high" || action.priority === "medium")
-            ? "warn"
-            : "pass";
-    return {
-        schemaVersion: "1.0.0",
-        generatedAt: new Date().toISOString(),
-        targetPath: rootPath,
-        status,
-        exitCode: status === "fail" ? 1 : 0,
-        summary: {
-            actionCounts: countActions(finalActions)
-        },
-        validation: {
-            status: validation.status,
-            findingCount: validation.findings.length
-        },
-        security: {
-            status: security.status,
-            score: security.score,
-            findingCount: security.findings.length
-        },
-        compatibility: {
-            failedClients: matrixExitCode(compatibility) === 1
-                ? compatibility.results
-                    .filter((result) => result.status === "fail")
-                    .map((result) => result.client)
-                : []
-        },
-        actions: finalActions
-    };
+    return buildDoctorRecommendationsFromAnalysis(await buildPackageAnalysis(targetPath, {
+        environment: options.environment,
+        runCheck: options.runCheck
+    }));
 }
 export function renderDoctorRecommendationsJson(report) {
     return JSON.stringify(report, null, 2);

package/dist/core/package-analysis.d.ts

@@ -0,0 +1,28 @@
+import { type CompatibilityEnvironment, type CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+import type { CheckResult, JsonReport } from "../domain/types.js";
+import type { DoctorRecommendationsReport } from "./doctor-recommendations.js";
+import type { DoctorExportBundle } from "./doctor-export-bundle.js";
+import { type SecurityAudit } from "../security/security-audit.js";
+import { type TrustScoreReport } from "../security/trust-score.js";
+export interface PackageAnalysis {
+    generatedAt: string;
+    targetPath: string;
+    validation: CheckResult;
+    validationJson: JsonReport;
+    security: SecurityAudit;
+    compatibility: CompatibilityMatrix;
+    trust: TrustScoreReport;
+}
+export type PackageAnalysisStage = "validation" | "doctorConfig" | "security" | "compatibility" | "trust";
+export interface PackageAnalysisTiming {
+    stage: PackageAnalysisStage;
+    durationMs: number;
+}
+export interface PackageAnalysisOptions {
+    environment?: CompatibilityEnvironment;
+    recordTiming?: (timing: PackageAnalysisTiming) => void;
+    runCheck?: (targetPath: string) => Promise<CheckResult>;
+}
+export declare function buildPackageAnalysis(targetPath: string, options?: PackageAnalysisOptions): Promise<PackageAnalysis>;
+export declare function buildDoctorRecommendationsFromAnalysis(analysis: PackageAnalysis): DoctorRecommendationsReport;
+export declare function buildDoctorExportBundleFromAnalysis(analysis: PackageAnalysis, recommendations?: DoctorRecommendationsReport): DoctorExportBundle;

package/dist/core/package-analysis.js

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { buildCompatibilityMatrix, matrixExitCode } from "../compatibility/compatibility-matrix.js";
+import { applyDoctorConfig, loadDoctorConfig } from "./doctor-config.js";
+import { buildJsonReport } from "../reporting/render-json-report.js";
+import { buildSecurityAudit } from "../security/security-audit.js";
+import { buildTrustScore } from "../security/trust-score.js";
+import { validatePlugin } from "./validate-plugin.js";
+import { packageVersion } from "../version.js";
+const priorityRank = {
+    blocker: 0,
+    high: 1,
+    medium: 2,
+    info: 3
+};
+function countActions(actions) {
+    return {
+        blocker: actions.filter((action) => action.priority === "blocker").length,
+        high: actions.filter((action) => action.priority === "high").length,
+        medium: actions.filter((action) => action.priority === "medium").length,
+        info: actions.filter((action) => action.priority === "info").length
+    };
+}
+function priorityForFinding(finding) {
+    if (finding.severity === "fail") {
+        return "blocker";
+    }
+    return finding.id.startsWith("plugin.security.") ? "high" : "medium";
+}
+function categoryForFinding(finding) {
+    return finding.id.startsWith("plugin.security.") ? "security" : "validation";
+}
+function commandForCategory(category, targetPath) {
+    if (category === "security") {
+        return `codex-plugin-doctor security ${targetPath} --scorecard`;
+    }
+    if (category === "compatibility") {
+        return `codex-plugin-doctor compat ${targetPath} --all --scorecard`;
+    }
+    return `codex-plugin-doctor check ${targetPath} --explain`;
+}
+function actionFromFinding(finding, targetPath) {
+    const category = categoryForFinding(finding);
+    return {
+        priority: priorityForFinding(finding),
+        category,
+        findingId: finding.id,
+        title: finding.message,
+        reason: finding.impact,
+        nextCommand: commandForCategory(category, targetPath)
+    };
+}
+function dedupeActions(actions) {
+    const seen = new Set();
+    return actions.filter((action) => {
+        const key = `${action.category}\n${action.findingId ?? action.title}\n${action.reason}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function actionsFromCompatibility(matrix, targetPath) {
+    return matrix.results
+        .filter((result) => result.status === "fail")
+        .map((result) => ({
+        priority: "high",
+        category: "compatibility",
+        title: `${result.client} compatibility failed.`,
+        reason: result.summary,
+        nextCommand: commandForCategory("compatibility", targetPath)
+    }));
+}
+function sortActions(actions) {
+    return [...actions].sort((left, right) => {
+        const priorityDelta = priorityRank[left.priority] - priorityRank[right.priority];
+        if (priorityDelta !== 0) {
+            return priorityDelta;
+        }
+        return left.category.localeCompare(right.category);
+    });
+}
+async function measureStage(stage, operation, recordTiming) {
+    const startedAt = performance.now();
+    try {
+        return await operation();
+    }
+    finally {
+        recordTiming?.({
+            stage,
+            durationMs: performance.now() - startedAt
+        });
+    }
+}
+export async function buildPackageAnalysis(targetPath, options = {}) {
+    const rootPath = path.resolve(targetPath);
+    const runCheck = options.runCheck ?? validatePlugin;
+    const [rawValidation, doctorConfig, security, compatibility] = await Promise.all([
+        measureStage("validation", () => runCheck(rootPath), options.recordTiming),
+        measureStage("doctorConfig", () => loadDoctorConfig(rootPath), options.recordTiming),
+        measureStage("security", () => buildSecurityAudit(rootPath), options.recordTiming),
+        measureStage("compatibility", () => buildCompatibilityMatrix(rootPath, options.environment ?? {}), options.recordTiming)
+    ]);
+    const validation = applyDoctorConfig(rawValidation, doctorConfig);
+    const trust = await measureStage("trust", () => buildTrustScore(rootPath, { securityAudit: security }), options.recordTiming);
+    return {
+        generatedAt: new Date().toISOString(),
+        targetPath: rootPath,
+        validation,
+        validationJson: buildJsonReport(validation, { runtimeProbeEnabled: false }),
+        security,
+        compatibility,
+        trust
+    };
+}
+export function buildDoctorRecommendationsFromAnalysis(analysis) {
+    const actions = sortActions(dedupeActions([
+        ...analysis.validation.findings.map((finding) => actionFromFinding(finding, analysis.targetPath)),
+        ...analysis.security.findings.map((finding) => actionFromFinding(finding, analysis.targetPath)),
+        ...actionsFromCompatibility(analysis.compatibility, analysis.targetPath)
+    ]));
+    const finalActions = actions.length > 0
+        ? actions
+        : [
+            {
+                priority: "info",
+                category: "release",
+                title: "No blocker actions.",
+                reason: "The package has no validation, security, or compatibility blockers in this recommendation pass.",
+                nextCommand: `codex-plugin-doctor check ${analysis.targetPath} --profile publish`
+            }
+        ];
+    const status = finalActions.some((action) => action.priority === "blocker")
+        ? "fail"
+        : finalActions.some((action) => action.priority === "high" || action.priority === "medium")
+            ? "warn"
+            : "pass";
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: analysis.generatedAt,
+        targetPath: analysis.targetPath,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        summary: {
+            actionCounts: countActions(finalActions)
+        },
+        validation: {
+            status: analysis.validation.status,
+            findingCount: analysis.validation.findings.length
+        },
+        security: {
+            status: analysis.security.status,
+            score: analysis.security.score,
+            findingCount: analysis.security.findings.length
+        },
+        compatibility: {
+            failedClients: matrixExitCode(analysis.compatibility) === 1
+                ? analysis.compatibility.results
+                    .filter((result) => result.status === "fail")
+                    .map((result) => result.client)
+                : []
+        },
+        actions: finalActions
+    };
+}
+export function buildDoctorExportBundleFromAnalysis(analysis, recommendations = buildDoctorRecommendationsFromAnalysis(analysis)) {
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: analysis.generatedAt,
+        kind: "doctor.export.bundle",
+        version: packageVersion,
+        targetPath: analysis.targetPath,
+        validation: analysis.validationJson,
+        security: analysis.security,
+        compatibility: analysis.compatibility,
+        recommendations,
+        trust: analysis.trust
+    };
+}

package/dist/core/performance-report.d.ts

@@ -0,0 +1,37 @@
+import { type CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
+import type { CheckResult } from "../domain/types.js";
+import { type PackageAnalysisStage } from "./package-analysis.js";
+export type DoctorPerformanceStageName = PackageAnalysisStage | "recommendations" | "total";
+export interface DoctorPerformanceStage {
+    name: DoctorPerformanceStageName;
+    durationMs: number;
+    status?: "pass" | "warn" | "fail";
+    itemCount?: number;
+}
+export interface DoctorPerformanceReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    kind: "doctor.perf";
+    targetPath: string;
+    status: "pass";
+    exitCode: 0;
+    summary: {
+        stageCount: number;
+        slowestStage: DoctorPerformanceStageName;
+        totalDurationMs: number;
+        validationStatus: "pass" | "warn" | "fail";
+        securityStatus: "pass" | "warn" | "fail";
+        trustScore: number;
+        compatibilityFailures: number;
+    };
+    stages: DoctorPerformanceStage[];
+}
+export interface BuildDoctorPerformanceReportOptions {
+    environment?: CompatibilityEnvironment;
+    runCheck?: (targetPath: string) => Promise<CheckResult>;
+}
+export declare function buildDoctorPerformanceReport(targetPath: string, options?: BuildDoctorPerformanceReportOptions): Promise<DoctorPerformanceReport>;
+export declare function renderDoctorPerformanceReportJson(report: DoctorPerformanceReport): string;
+export declare function renderDoctorPerformanceReport(report: DoctorPerformanceReport, options?: {
+    outputPath?: string | null;
+}): string;

package/dist/core/performance-report.js

@@ -0,0 +1,141 @@
+import { performance } from "node:perf_hooks";
+import { matrixExitCode } from "../compatibility/compatibility-matrix.js";
+import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
+const stageOrder = [
+    "validation",
+    "doctorConfig",
+    "security",
+    "compatibility",
+    "trust",
+    "recommendations",
+    "total"
+];
+function roundDuration(durationMs) {
+    return Number(durationMs.toFixed(3));
+}
+function compatibilityStatus(exitCode, warningCount) {
+    if (exitCode === 1) {
+        return "fail";
+    }
+    return warningCount > 0 ? "warn" : "pass";
+}
+function slowestStage(stages) {
+    return stages
+        .filter((stage) => stage.name !== "total")
+        .reduce((slowest, stage) => (stage.durationMs > slowest.durationMs ? stage : slowest), stages[0]).name;
+}
+export async function buildDoctorPerformanceReport(targetPath, options = {}) {
+    const timings = [];
+    const startedAt = performance.now();
+    const analysis = await buildPackageAnalysis(targetPath, {
+        environment: options.environment,
+        recordTiming: (timing) => timings.push(timing),
+        runCheck: options.runCheck
+    });
+    const recommendationsStartedAt = performance.now();
+    const recommendations = buildDoctorRecommendationsFromAnalysis(analysis);
+    const recommendationTiming = performance.now() - recommendationsStartedAt;
+    const totalDurationMs = performance.now() - startedAt;
+    const compatibilityFailures = analysis.compatibility.results
+        .filter((result) => result.status === "fail").length;
+    const compatibilityWarnings = analysis.compatibility.results
+        .filter((result) => result.status === "warn").length;
+    const timingByStage = new Map(timings.map((timing) => [timing.stage, timing.durationMs]));
+    const stages = stageOrder.map((stageName) => {
+        if (stageName === "validation") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: analysis.validation.status,
+                itemCount: analysis.validation.findings.length
+            };
+        }
+        if (stageName === "doctorConfig") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: "pass"
+            };
+        }
+        if (stageName === "security") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: analysis.security.status,
+                itemCount: analysis.security.findings.length
+            };
+        }
+        if (stageName === "compatibility") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: compatibilityStatus(matrixExitCode(analysis.compatibility), compatibilityWarnings),
+                itemCount: analysis.compatibility.results.length
+            };
+        }
+        if (stageName === "trust") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: analysis.trust.status,
+                itemCount: analysis.trust.findings.length
+            };
+        }
+        if (stageName === "recommendations") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(recommendationTiming),
+                status: recommendations.status,
+                itemCount: recommendations.actions.length
+            };
+        }
+        return {
+            name: "total",
+            durationMs: roundDuration(totalDurationMs)
+        };
+    });
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: analysis.generatedAt,
+        kind: "doctor.perf",
+        targetPath: analysis.targetPath,
+        status: "pass",
+        exitCode: 0,
+        summary: {
+            stageCount: stages.length,
+            slowestStage: slowestStage(stages),
+            totalDurationMs: roundDuration(totalDurationMs),
+            validationStatus: analysis.validation.status,
+            securityStatus: analysis.security.status,
+            trustScore: analysis.trust.score,
+            compatibilityFailures
+        },
+        stages
+    };
+}
+export function renderDoctorPerformanceReportJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorPerformanceReport(report, options = {}) {
+    const lines = [
+        "Doctor Performance",
+        "==================",
+        `Target: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Total: ${report.summary.totalDurationMs}ms`,
+        `Slowest: ${report.summary.slowestStage}`,
+        `Validation: ${report.summary.validationStatus.toUpperCase()}`,
+        `Security: ${report.summary.securityStatus.toUpperCase()}`,
+        `Trust: ${report.summary.trustScore}/100`
+    ];
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    lines.push("", "Stages", "------");
+    for (const stage of report.stages) {
+        const status = stage.status ? ` (${stage.status.toUpperCase()})` : "";
+        const count = stage.itemCount === undefined ? "" : `, items: ${stage.itemCount}`;
+        lines.push(`${stage.name}: ${stage.durationMs}ms${status}${count}`);
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import type { CheckOptions, CheckResult } from "./domain/types.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard, type SecurityAudit } from "./security/security-audit.js";
-export { buildTrustScore, renderTrustScore, renderTrustScoreJson, type TrustScoreReport } from "./security/trust-score.js";
+export { buildTrustScore, renderTrustScore, renderTrustScoreJson, type BuildTrustScoreOptions, type TrustScoreReport } from "./security/trust-score.js";
 export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson, type DoctorSnapshot } from "./core/doctor-snapshot.js";
 export { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRecommendationsJson, type DoctorRecommendationAction, type DoctorRecommendationsReport } from "./core/doctor-recommendations.js";
 export { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson, type DoctorExportBundle } from "./core/doctor-export-bundle.js";
+export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis, type PackageAnalysis, type PackageAnalysisOptions, type PackageAnalysisStage, type PackageAnalysisTiming } from "./core/package-analysis.js";
+export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.js";
 export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson, type EcosystemAuditReport } from "./audit/ecosystem-audit.js";
 export { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames, type PolicyPackName } from "./policy/policy-packs.js";
 export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson, type GenericMcpDoctorReport } from "./mcp/generic-mcp-doctor.js";

package/dist/index.js

@@ -4,6 +4,8 @@ export { buildTrustScore, renderTrustScore, renderTrustScoreJson } from "./secur
 export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } from "./core/doctor-snapshot.js";
 export { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRecommendationsJson } from "./core/doctor-recommendations.js";
 export { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson } from "./core/doctor-export-bundle.js";
+export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./core/package-analysis.js";
+export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
 export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } from "./audit/ecosystem-audit.js";
 export { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
 export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";

package/dist/run-cli.js

@@ -16,6 +16,7 @@ import { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
 import { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } from "./core/doctor-snapshot.js";
 import { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRecommendationsJson } from "./core/doctor-recommendations.js";
 import { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson } from "./core/doctor-export-bundle.js";
+import { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
 import { applyFixPlan, buildFixPlan, renderApplyFixResult, renderFixPlanJsonReport, renderFixPlan } from "./core/fix-plan.js";
 import { renderClientDoctor, renderEnvironmentDoctor, renderEnvironmentDoctorJson } from "./core/environment-doctor.js";
 import { initCiWorkflow } from "./core/init-ci.js";
@@ -61,7 +62,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] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [recommend <path>|trust <path>|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] [--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 [recommend <path>|trust <path>|perf <path>|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");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -250,6 +251,38 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStdout(renderedReport);
             return report.exitCode;
         }
+        if (maybePath === "perf") {
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : ".";
+            const perfFlags = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs.slice(1)
+                : remainingArgs;
+            const jsonOutput = perfFlags.includes("--json");
+            const outputIndex = perfFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : perfFlags[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const report = await buildDoctorPerformanceReport(targetPath, {
+                environment: {
+                    env: terminalContext.env,
+                    platform: terminalContext.platform
+                },
+                runCheck: options.runCheckImpl
+                    ? (pathToCheck) => options.runCheckImpl(pathToCheck)
+                    : undefined
+            });
+            const renderedReport = jsonOutput
+                ? renderDoctorPerformanceReportJson(report)
+                : renderDoctorPerformanceReport(report, { outputPath });
+            if (outputPath) {
+                await writeFile(outputPath, renderedReport, "utf8");
+            }
+            io.writeStdout(renderedReport);
+            return report.exitCode;
+        }
         if (maybePath === "export") {
             const bundleIndex = remainingArgs.indexOf("--bundle");
             if (bundleIndex === -1) {
@@ -520,7 +553,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const auditFlags = maybePath ? [maybePath, ...remainingArgs] : remainingArgs;
         const installed = auditFlags.includes("--installed");
         if (!installed) {
-            io.writeStderr("Usage: codex-plugin-doctor audit --installed [filter] [--security] [--compat] [--json] [--output <path>]");
+            io.writeStderr("Usage: codex-plugin-doctor audit --installed [filter] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]");
             return 2;
         }
         const installedIndex = auditFlags.indexOf("--installed");
@@ -535,6 +568,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const policyIndex = auditFlags.indexOf("--policy");
         const policyName = policyIndex === -1 ? null : auditFlags[policyIndex + 1];
         const policy = parsePolicyPack(policyName);
+        const cacheEnabled = auditFlags.includes("--cache") || auditFlags.includes("--changed");
+        const changedOnly = auditFlags.includes("--changed");
+        const cacheFileIndex = auditFlags.indexOf("--cache-file");
+        const cachePath = cacheFileIndex === -1 ? null : auditFlags[cacheFileIndex + 1];
         if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
             io.writeStderr("Missing path after --output.");
             return 2;
@@ -543,6 +580,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStderr("Missing policy after --policy.");
             return 2;
         }
+        if (cacheFileIndex !== -1 && (!cachePath || cachePath.startsWith("--"))) {
+            io.writeStderr("Missing path after --cache-file.");
+            return 2;
+        }
         if (policyIndex !== -1 && !policy) {
             io.writeStderr(`Unknown policy: ${policyName}. Supported policies: ${policyPackNames.join(", ")}.`);
             return 2;
@@ -554,9 +595,14 @@ export async function runCli(args, io = defaultIo, options = {}) {
             includeSecurity,
             includeCompatibility,
             failOnWarnings: policyFailsOnWarnings(policy),
+            cache: {
+                enabled: cacheEnabled,
+                changedOnly,
+                cachePath
+            },
             validatePlugin: options.runCheckImpl ?? runCheck
         });
-        if (report.summary.totalPlugins === 0) {
+        if (report.summary.totalPlugins === 0 && !changedOnly) {
             io.writeStderr(installedFilter
                 ? `No installed Codex plugins matched '${installedFilter}'.`
                 : "No installed Codex plugins found.");

package/dist/security/trust-score.d.ts

@@ -1,4 +1,5 @@
 import type { Finding } from "../domain/types.js";
+import { type SecurityAudit } from "./security-audit.js";
 export interface TrustScoreReport {
     schemaVersion: "1.0.0";
     generatedAt: string;
@@ -18,6 +19,9 @@ export interface TrustScoreReport {
     };
     findings: Finding[];
 }
-export declare function buildTrustScore(targetPath: string): Promise<TrustScoreReport>;
+export interface BuildTrustScoreOptions {
+    securityAudit?: SecurityAudit | null;
+}
+export declare function buildTrustScore(targetPath: string, options?: BuildTrustScoreOptions): Promise<TrustScoreReport>;
 export declare function renderTrustScoreJson(report: TrustScoreReport): string;
 export declare function renderTrustScore(report: TrustScoreReport): string;

package/dist/security/trust-score.js

@@ -116,7 +116,7 @@ function scoreFindings(findings) {
     const warnCount = findings.filter((finding) => finding.severity === "warn").length;
     return Math.max(0, 100 - (failCount * 35) - (warnCount * 10));
 }
-export async function buildTrustScore(targetPath) {
+export async function buildTrustScore(targetPath, options = {}) {
     const rootPath = path.resolve(targetPath);
     const packageJson = await readPackageJson(rootPath);
     const scriptAudit = packageJson
@@ -125,10 +125,11 @@ export async function buildTrustScore(targetPath) {
     const dependencyAudit = packageJson
         ? auditDependencies(packageJson)
         : { findings: [], dependenciesChecked: 0 };
-    const discoveredPackage = await discoverPackage(rootPath);
-    const securityAudit = discoveredPackage
-        ? await buildSecurityAudit(rootPath)
-        : null;
+    const securityAudit = options.securityAudit !== undefined
+        ? options.securityAudit
+        : await discoverPackage(rootPath)
+            ? await buildSecurityAudit(rootPath)
+            : null;
     const findings = dedupeFindings([
         ...scriptAudit.findings,
         ...dependencyAudit.findings,

package/package.json

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