codex-plugin-doctor 0.12.0 → 0.13.0

package/README.md

@@ -176,6 +176,12 @@ 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 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
@@ -240,7 +246,7 @@ 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 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.
 

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

@@ -0,0 +1,22 @@
+import { type CompatibilityEnvironment, type 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,79 @@
+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";
+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 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
+    };
+}
+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,161 @@
+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);
+    });
+}
+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
+    };
+}
+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/index.d.ts

@@ -1,6 +1,9 @@
 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 { 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 { 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,9 @@
 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 { 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,8 @@ 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 { 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 +35,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 +61,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>]\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");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -191,6 +194,91 @@ 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 === "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");

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

@@ -0,0 +1,23 @@
+import type { Finding } from "../domain/types.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 declare function buildTrustScore(targetPath: string): 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,196 @@
+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) {
+    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 discoveredPackage = await discoverPackage(rootPath);
+    const securityAudit = discoveredPackage
+        ? 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.13.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",