codex-plugin-doctor 0.12.0 → 0.14.0

package/README.md

@@ -176,6 +176,14 @@ Run these from a Codex plugin package root:
 codex-plugin-doctor --version
 codex-plugin-doctor self-test
 codex-plugin-doctor doctor
+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
 codex-plugin-doctor doctor snapshot --json
 codex-plugin-doctor doctor snapshot --output doctor-snapshot.json
@@ -184,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
@@ -240,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 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

@@ -0,0 +1,22 @@
+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";
+export interface DoctorExportBundle {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    kind: "doctor.export.bundle";
+    version: string;
+    targetPath: string;
+    validation: JsonReport;
+    security: SecurityAudit;
+    compatibility: CompatibilityMatrix;
+    recommendations: DoctorRecommendationsReport;
+    trust: TrustScoreReport;
+}
+export declare function buildDoctorExportBundle(targetPath: string, environment?: CompatibilityEnvironment): Promise<DoctorExportBundle>;
+export declare function renderDoctorExportBundleJson(bundle: DoctorExportBundle): string;
+export declare function renderDoctorExportBundle(bundle: DoctorExportBundle, options?: {
+    outputPath?: string | null;
+}): string;

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

@@ -0,0 +1,52 @@
+import { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
+function redactString(value) {
+    return value
+        .replace(/sk-[A-Za-z0-9_-]{12,}/g, "[REDACTED_SECRET]")
+        .replace(/npm_[A-Za-z0-9_-]{12,}/g, "[REDACTED_SECRET]")
+        .replace(/gh[pousr]_[A-Za-z0-9_]{12,}/g, "[REDACTED_SECRET]")
+        .replace(/SHOULD_NOT_LEAK/g, "[REDACTED_SECRET]");
+}
+function redactValue(value) {
+    if (typeof value === "string") {
+        return redactString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(redactValue);
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, nestedValue]) => [
+            key,
+            redactValue(nestedValue)
+        ]));
+    }
+    return value;
+}
+export async function buildDoctorExportBundle(targetPath, environment = {}) {
+    const analysis = await buildPackageAnalysis(targetPath, { environment });
+    return buildDoctorExportBundleFromAnalysis(analysis, buildDoctorRecommendationsFromAnalysis(analysis));
+}
+export function renderDoctorExportBundleJson(bundle) {
+    return JSON.stringify(redactValue(bundle), null, 2);
+}
+export function renderDoctorExportBundle(bundle, options = {}) {
+    const lines = [
+        "Doctor Export Bundle",
+        "====================",
+        `Target: ${bundle.targetPath}`,
+        `Version: ${bundle.version}`,
+        `Validation: ${bundle.validation.summary.status.toUpperCase()}`,
+        `Security: ${bundle.security.status.toUpperCase()} (${bundle.security.score}/100)`,
+        `Trust: ${bundle.trust.status.toUpperCase()} (${bundle.trust.score}/100)`,
+        `Recommendations: ${bundle.recommendations.actions.length}`
+    ];
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    lines.push("", "Bundle sections", "---------------");
+    lines.push("validation");
+    lines.push("security");
+    lines.push("compatibility");
+    lines.push("recommendations");
+    lines.push("trust");
+    return lines.join("\n");
+}

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

@@ -0,0 +1,42 @@
+import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
+import type { CheckResult } from "../domain/types.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 {
+    priority: RecommendationPriority;
+    category: RecommendationCategory;
+    title: string;
+    reason: string;
+    nextCommand: string;
+    findingId?: string;
+}
+export interface DoctorRecommendationsReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    summary: {
+        actionCounts: Record<RecommendationPriority, number>;
+    };
+    validation: {
+        status: CheckResult["status"];
+        findingCount: number;
+    };
+    security: {
+        status: SecurityAudit["status"];
+        score: number;
+        findingCount: number;
+    };
+    compatibility: {
+        failedClients: string[];
+    };
+    actions: DoctorRecommendationAction[];
+}
+export declare function buildDoctorRecommendations(targetPath: string, options?: {
+    environment?: CompatibilityEnvironment;
+    runCheck?: (targetPath: string) => Promise<CheckResult>;
+}): Promise<DoctorRecommendationsReport>;
+export declare function renderDoctorRecommendationsJson(report: DoctorRecommendationsReport): string;
+export declare function renderDoctorRecommendations(report: DoctorRecommendationsReport): string;

package/dist/core/doctor-recommendations.js

@@ -0,0 +1,31 @@
+import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
+export async function buildDoctorRecommendations(targetPath, options = {}) {
+    return buildDoctorRecommendationsFromAnalysis(await buildPackageAnalysis(targetPath, {
+        environment: options.environment,
+        runCheck: options.runCheck
+    }));
+}
+export function renderDoctorRecommendationsJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorRecommendations(report) {
+    const lines = [
+        "Doctor Recommendations",
+        "======================",
+        `Target: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Actions: ${report.summary.actionCounts.blocker} blocker, ${report.summary.actionCounts.high} high, ${report.summary.actionCounts.medium} medium, ${report.summary.actionCounts.info} info`,
+        `Security: ${report.security.status.toUpperCase()} (${report.security.score}/100)`
+    ];
+    lines.push("", "Actions", "-------");
+    for (const action of report.actions) {
+        lines.push(`[${action.priority.toUpperCase()}] ${action.title}`);
+        if (action.findingId) {
+            lines.push(`  Finding: ${action.findingId}`);
+        }
+        lines.push(`  Category: ${action.category}`);
+        lines.push(`  Reason: ${action.reason}`);
+        lines.push(`  Next: ${action.nextCommand}`);
+    }
+    return lines.join("\n");
+}

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,6 +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 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

@@ -1,6 +1,11 @@
 import { validatePlugin } from "./core/validate-plugin.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
+export { buildTrustScore, renderTrustScore, renderTrustScoreJson } from "./security/trust-score.js";
 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

@@ -14,6 +14,9 @@ import { buildClineInstallPreview, renderClineInstallPreview } from "./compatibi
 import { buildWindsurfInstallPreview, renderWindsurfInstallPreview } from "./compatibility/windsurf-install-preview.js";
 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";
@@ -33,6 +36,7 @@ import { renderTextReport } from "./reporting/render-text-report.js";
 import { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
 import { findRuleDefinition } from "./rules/rule-catalog.js";
 import { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
+import { buildTrustScore, renderTrustScore, renderTrustScoreJson } from "./security/trust-score.js";
 import { createLiveStatusRenderer } from "./terminal/live-status-renderer.js";
 import { determineOutputPolicy } from "./terminal/output-policy.js";
 import { getSpinner } from "./terminal/spinner-registry.js";
@@ -58,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 [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 = [
@@ -191,6 +195,123 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const doctorFlags = maybePath?.startsWith("--")
             ? [maybePath, ...remainingArgs]
             : remainingArgs;
+        if (maybePath === "recommend") {
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : ".";
+            const recommendFlags = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs.slice(1)
+                : remainingArgs;
+            const jsonOutput = recommendFlags.includes("--json");
+            const outputIndex = recommendFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : recommendFlags[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const report = await buildDoctorRecommendations(targetPath, {
+                environment: {
+                    env: terminalContext.env,
+                    platform: terminalContext.platform
+                },
+                runCheck: options.runCheckImpl
+                    ? (pathToCheck) => options.runCheckImpl(pathToCheck)
+                    : undefined
+            });
+            const renderedReport = jsonOutput
+                ? renderDoctorRecommendationsJson(report)
+                : renderDoctorRecommendations(report);
+            if (outputPath) {
+                await writeFile(outputPath, renderedReport, "utf8");
+            }
+            io.writeStdout(renderedReport);
+            return report.exitCode;
+        }
+        if (maybePath === "trust") {
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : ".";
+            const trustFlags = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs.slice(1)
+                : remainingArgs;
+            const jsonOutput = trustFlags.includes("--json");
+            const outputIndex = trustFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : trustFlags[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const report = await buildTrustScore(targetPath);
+            const renderedReport = jsonOutput
+                ? renderTrustScoreJson(report)
+                : renderTrustScore(report);
+            if (outputPath) {
+                await writeFile(outputPath, renderedReport, "utf8");
+            }
+            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) {
+                io.writeStderr("Usage: codex-plugin-doctor doctor export --bundle <path> [--json] [--output <path>]");
+                return 2;
+            }
+            const targetPath = remainingArgs[bundleIndex + 1] && !remainingArgs[bundleIndex + 1].startsWith("--")
+                ? remainingArgs[bundleIndex + 1]
+                : ".";
+            const jsonOutput = remainingArgs.includes("--json");
+            const outputIndex = remainingArgs.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : remainingArgs[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const bundle = await buildDoctorExportBundle(targetPath, {
+                env: terminalContext.env,
+                platform: terminalContext.platform
+            });
+            const bundleJson = renderDoctorExportBundleJson(bundle);
+            if (outputPath) {
+                await writeFile(outputPath, bundleJson, "utf8");
+            }
+            io.writeStdout(jsonOutput
+                ? bundleJson
+                : renderDoctorExportBundle(bundle, { outputPath }));
+            return 0;
+        }
         if (maybePath === "snapshot") {
             const jsonOutput = doctorFlags.includes("--json");
             const outputIndex = doctorFlags.indexOf("--output");
@@ -432,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");
@@ -447,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;
@@ -455,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;
@@ -466,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

@@ -0,0 +1,27 @@
+import type { Finding } from "../domain/types.js";
+import { type SecurityAudit } from "./security-audit.js";
+export interface TrustScoreReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    score: number;
+    findingCounts: {
+        fail: number;
+        warn: number;
+        total: number;
+    };
+    packageJson: {
+        present: boolean;
+        scriptsChecked: number;
+        dependenciesChecked: number;
+    };
+    findings: Finding[];
+}
+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

@@ -0,0 +1,197 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { discoverPackage } from "../core/discover-package.js";
+import { parseJsonText } from "../core/read-json-file.js";
+import { buildSecurityAudit } from "./security-audit.js";
+const lifecycleScripts = new Set([
+    "preinstall",
+    "install",
+    "postinstall",
+    "prepublish",
+    "prepare"
+]);
+function buildFinding(severity, id, message, impact, suggestedFix) {
+    return {
+        id,
+        severity,
+        message,
+        impact,
+        suggestedFix
+    };
+}
+async function fileExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function containsRemotePipeInstall(script) {
+    const normalized = script.toLowerCase();
+    return (/\b(curl|wget)\b[^|]*\|\s*(sh|bash)\b/.test(normalized) ||
+        /\b(iwr|irm|invoke-webrequest|invoke-restmethod)\b[^|]*\|\s*(iex|invoke-expression)\b/.test(normalized) ||
+        /\binvoke-expression\b/.test(normalized));
+}
+async function readPackageJson(rootPath) {
+    const packageJsonPath = path.join(rootPath, "package.json");
+    if (!(await fileExists(packageJsonPath))) {
+        return null;
+    }
+    try {
+        const parsed = parseJsonText(await readFile(packageJsonPath, "utf8"));
+        return isPlainObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function auditScripts(packageJson) {
+    const scripts = isPlainObject(packageJson.scripts) ? packageJson.scripts : {};
+    const findings = [];
+    let scriptsChecked = 0;
+    for (const [scriptName, scriptValue] of Object.entries(scripts)) {
+        if (!lifecycleScripts.has(scriptName) || typeof scriptValue !== "string") {
+            continue;
+        }
+        scriptsChecked += 1;
+        if (containsRemotePipeInstall(scriptValue)) {
+            findings.push(buildFinding("fail", "trust.package.remote_pipe_install", `The package lifecycle script \`${scriptName}\` pipes remote content into a shell.`, "Remote download-and-execute scripts can run unreviewed code during install or publish workflows.", "Replace remote pipe execution with pinned package dependencies or a checked-in reviewed setup script."));
+            continue;
+        }
+        findings.push(buildFinding("warn", "trust.package.lifecycle_script", `The package defines lifecycle script \`${scriptName}\`.`, "Lifecycle scripts execute automatically during package manager workflows and increase supply-chain review scope.", "Keep lifecycle scripts minimal, documented, and covered by release review."));
+    }
+    return {
+        findings,
+        scriptsChecked
+    };
+}
+function dependencySections(packageJson) {
+    return [
+        packageJson.dependencies,
+        packageJson.devDependencies,
+        packageJson.optionalDependencies,
+        packageJson.peerDependencies
+    ].filter(isPlainObject);
+}
+function auditDependencies(packageJson) {
+    const findings = [];
+    let dependenciesChecked = 0;
+    for (const dependencies of dependencySections(packageJson)) {
+        for (const [dependencyName, versionSpec] of Object.entries(dependencies)) {
+            if (typeof versionSpec !== "string") {
+                continue;
+            }
+            dependenciesChecked += 1;
+            if (versionSpec === "*" || versionSpec.toLowerCase() === "latest") {
+                findings.push(buildFinding("warn", "trust.package.unpinned_dependency", `The dependency \`${dependencyName}\` uses broad version spec \`${versionSpec}\`.`, "Broad dependency ranges make package resolution less reproducible across installs and releases.", "Pin the dependency to a specific compatible range or exact version."));
+            }
+            if (/^(git\+|github:|http:\/\/|https:\/\/)/i.test(versionSpec)) {
+                findings.push(buildFinding("warn", "trust.package.remote_dependency", `The dependency \`${dependencyName}\` resolves from remote spec \`${versionSpec}\`.`, "Remote dependency specs can change outside the npm registry's normal version and integrity workflow.", "Prefer registry-published dependencies with pinned semver ranges."));
+            }
+        }
+    }
+    return {
+        findings,
+        dependenciesChecked
+    };
+}
+function dedupeFindings(findings) {
+    const seen = new Set();
+    return findings.filter((finding) => {
+        const key = `${finding.id}\n${finding.message}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function scoreFindings(findings) {
+    const failCount = findings.filter((finding) => finding.severity === "fail").length;
+    const warnCount = findings.filter((finding) => finding.severity === "warn").length;
+    return Math.max(0, 100 - (failCount * 35) - (warnCount * 10));
+}
+export async function buildTrustScore(targetPath, options = {}) {
+    const rootPath = path.resolve(targetPath);
+    const packageJson = await readPackageJson(rootPath);
+    const scriptAudit = packageJson
+        ? auditScripts(packageJson)
+        : { findings: [], scriptsChecked: 0 };
+    const dependencyAudit = packageJson
+        ? auditDependencies(packageJson)
+        : { findings: [], dependenciesChecked: 0 };
+    const securityAudit = options.securityAudit !== undefined
+        ? options.securityAudit
+        : await discoverPackage(rootPath)
+            ? await buildSecurityAudit(rootPath)
+            : null;
+    const findings = dedupeFindings([
+        ...scriptAudit.findings,
+        ...dependencyAudit.findings,
+        ...(securityAudit?.findings ?? [])
+    ]);
+    const fail = findings.filter((finding) => finding.severity === "fail").length;
+    const warn = findings.filter((finding) => finding.severity === "warn").length;
+    const score = scoreFindings(findings);
+    const status = fail > 0
+        ? "fail"
+        : warn > 0
+            ? "warn"
+            : "pass";
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        targetPath: rootPath,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        score,
+        findingCounts: {
+            fail,
+            warn,
+            total: findings.length
+        },
+        packageJson: {
+            present: packageJson !== null,
+            scriptsChecked: scriptAudit.scriptsChecked,
+            dependenciesChecked: dependencyAudit.dependenciesChecked
+        },
+        findings
+    };
+}
+export function renderTrustScoreJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderTrustScore(report) {
+    const lines = [
+        "Doctor Trust Score",
+        "==================",
+        `Target: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Score: ${report.score}/100`,
+        `Summary: ${report.findingCounts.fail} fail, ${report.findingCounts.warn} warn, ${report.findingCounts.total} total`
+    ];
+    if (report.findings.length === 0) {
+        lines.push("", "No trust findings.");
+        return lines.join("\n");
+    }
+    const appendSection = (title, findings, marker) => {
+        if (findings.length === 0) {
+            return;
+        }
+        lines.push("", title, "--------");
+        for (const finding of findings) {
+            lines.push(`${marker} ${finding.id}`);
+            lines.push(`  Message: ${finding.message}`);
+            lines.push(`  Impact: ${finding.impact}`);
+            lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+        }
+    };
+    appendSection("Failures", report.findings.filter((finding) => finding.severity === "fail"), "x");
+    appendSection("Warnings", report.findings.filter((finding) => finding.severity === "warn"), "!");
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "0.12.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",