codex-plugin-doctor 0.11.0 → 0.13.0

package/dist/mcp/generic-mcp-doctor.js

@@ -0,0 +1,166 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { buildCompatibilityMatrix, readMcpConfigPath } from "../compatibility/compatibility-matrix.js";
+import { readJsonFile } from "../core/read-json-file.js";
+import { auditMcpServerConfig, buildSecurityAuditFromFindings } from "../security/security-audit.js";
+function buildFinding(severity, id, message, impact, suggestedFix) {
+    return {
+        id,
+        severity,
+        message,
+        impact,
+        suggestedFix
+    };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function fileExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
+}
+function buildStaticMcpFindings(mcpConfigPath, parsedConfig) {
+    if (!mcpConfigPath) {
+        return {
+            serverCount: 0,
+            findings: [
+                buildFinding("fail", "mcp.config.missing", "No MCP config was found for this target.", "A generic MCP package needs a `.mcp.json` file or a Codex manifest `mcpServers` reference before clients can discover servers.", "Add `.mcp.json` with a non-empty top-level `mcpServers` object.")
+            ]
+        };
+    }
+    if (!isPlainObject(parsedConfig)) {
+        return {
+            serverCount: 0,
+            findings: [
+                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must be a JSON object.", "MCP clients expect object-shaped configuration so server entries can be resolved deterministically.", `Wrap the MCP config in a top-level object inside \`${mcpConfigPath}\`.`)
+            ]
+        };
+    }
+    const servers = parsedConfig.mcpServers;
+    if (!isPlainObject(servers) || Object.keys(servers).length === 0) {
+        return {
+            serverCount: 0,
+            findings: [
+                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must contain a non-empty `mcpServers` object.", "Without server entries, MCP clients cannot discover any package capabilities.", `Define MCP servers under \`mcpServers\` in \`${mcpConfigPath}\`.`)
+            ]
+        };
+    }
+    const findings = [];
+    for (const [serverName, serverConfig] of Object.entries(servers)) {
+        if (!isPlainObject(serverConfig)) {
+            findings.push(buildFinding("fail", "mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "MCP clients cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`));
+            continue;
+        }
+        if (typeof serverConfig.command !== "string" && typeof serverConfig.url !== "string") {
+            findings.push(buildFinding("fail", "mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "MCP clients need a process command for stdio servers or a URL for remote servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${mcpConfigPath}\`.`));
+        }
+    }
+    return {
+        serverCount: Object.keys(servers).length,
+        findings
+    };
+}
+function mergeReportStatus(staticFindings, security) {
+    if (staticFindings.some((finding) => finding.severity === "fail") || security.status === "fail") {
+        return "fail";
+    }
+    if (staticFindings.some((finding) => finding.severity === "warn") || security.status === "warn") {
+        return "warn";
+    }
+    return "pass";
+}
+export async function buildGenericMcpDoctor(targetPath, environment = {}) {
+    const rootPath = path.resolve(targetPath);
+    const compatibility = await buildCompatibilityMatrix(rootPath, environment);
+    const mcpConfigPath = await readMcpConfigPath(rootPath);
+    let parsedConfig = null;
+    let staticFindings = [];
+    let serverCount = 0;
+    if (!mcpConfigPath || !(await fileExists(mcpConfigPath))) {
+        staticFindings = buildStaticMcpFindings(null, null).findings;
+    }
+    else if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+        staticFindings = [
+            buildFinding("fail", "mcp.config.path_outside_root", "The MCP config path resolves outside the target root.", "A package that reads MCP configuration outside its root is harder to audit and can depend on unreviewed local files.", "Keep `.mcp.json` or the manifest `mcpServers` reference inside the package root.")
+        ];
+    }
+    else {
+        try {
+            parsedConfig = await readJsonFile(mcpConfigPath);
+            const staticResult = buildStaticMcpFindings(mcpConfigPath, parsedConfig);
+            staticFindings = staticResult.findings;
+            serverCount = staticResult.serverCount;
+        }
+        catch {
+            staticFindings = [
+                buildFinding("fail", "mcp.config.invalid_json", "The MCP config is not valid JSON.", "MCP clients cannot parse server configuration until the JSON syntax is valid.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`)
+            ];
+        }
+    }
+    const security = buildSecurityAuditFromFindings(rootPath, mcpConfigPath && parsedConfig !== null
+        ? auditMcpServerConfig(rootPath, parsedConfig)
+        : []);
+    const status = mergeReportStatus(staticFindings, security);
+    return {
+        targetPath: rootPath,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        mcpConfigPath,
+        serverCount,
+        findings: [...staticFindings, ...security.findings],
+        security,
+        compatibility
+    };
+}
+export function renderGenericMcpDoctorJson(report) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        ...report
+    }, null, 2);
+}
+export function renderGenericMcpDoctor(report) {
+    const lines = [
+        "Generic MCP Doctor",
+        "==================",
+        `Target: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `MCP config: ${report.mcpConfigPath ?? "not found"}`,
+        `Servers: ${report.serverCount}`,
+        `Security: ${report.security.status.toUpperCase()} (${report.security.score}/100)`,
+        `Compatibility: ${report.compatibility.results
+            .map((result) => `${result.client}=${result.status}`)
+            .join(", ")}`
+    ];
+    if (report.findings.length === 0) {
+        lines.push("", "No findings.");
+        return lines.join("\n");
+    }
+    const failures = report.findings.filter((finding) => finding.severity === "fail");
+    const warnings = report.findings.filter((finding) => finding.severity === "warn");
+    const appendFindings = (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}`);
+        }
+    };
+    appendFindings("Failures", failures, "x");
+    appendFindings("Warnings", warnings, "!");
+    return lines.join("\n");
+}

package/dist/policy/policy-packs.d.ts

@@ -0,0 +1,9 @@
+import type { DoctorConfig } from "../core/doctor-config.js";
+import type { SecurityAudit } from "../security/security-audit.js";
+export declare const policyPackNames: readonly ["codex-publish", "mcp-strict", "security"];
+export type PolicyPackName = (typeof policyPackNames)[number];
+export declare function parsePolicyPack(value: string | null): PolicyPackName | null;
+export declare function policyEnablesRuntime(policy: PolicyPackName | null): boolean;
+export declare function policyFailsOnWarnings(policy: PolicyPackName | null): boolean;
+export declare function applyPolicyToDoctorConfig(config: DoctorConfig, policy: PolicyPackName | null): DoctorConfig;
+export declare function applyPolicyToSecurityAudit(audit: SecurityAudit, policy: PolicyPackName | null): SecurityAudit;

package/dist/policy/policy-packs.js

@@ -0,0 +1,33 @@
+export const policyPackNames = ["codex-publish", "mcp-strict", "security"];
+export function parsePolicyPack(value) {
+    if (!value) {
+        return null;
+    }
+    return policyPackNames.includes(value)
+        ? value
+        : null;
+}
+export function policyEnablesRuntime(policy) {
+    return policy === "codex-publish" || policy === "mcp-strict";
+}
+export function policyFailsOnWarnings(policy) {
+    return policy !== null;
+}
+export function applyPolicyToDoctorConfig(config, policy) {
+    if (!policyFailsOnWarnings(policy)) {
+        return config;
+    }
+    return {
+        ...config,
+        failOnWarnings: true
+    };
+}
+export function applyPolicyToSecurityAudit(audit, policy) {
+    if (!policyFailsOnWarnings(policy) || audit.status !== "warn") {
+        return audit;
+    }
+    return {
+        ...audit,
+        status: "fail"
+    };
+}

package/dist/run-cli.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
+import { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } from "./audit/ecosystem-audit.js";
 import { appendValidationHistoryEntry, readValidationHistory, summarizeValidationHistory } from "./core/validation-history.js";
 import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.js";
 import { applyInstallPreview, renderApplyInstallResult } from "./compatibility/apply-install-preview.js";
@@ -13,11 +14,14 @@ 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";
 import { initPluginPackage, initPluginTemplates, isInitPluginTemplate } from "./core/init-plugin.js";
 import { runCheck } from "./index.js";
+import { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";
 import { renderInstalledSummary } from "./reporting/render-installed-summary.js";
 import { renderBadgeJson, renderBadgeMarkdown } from "./reporting/render-badge-report.js";
 import { renderCompatibilityScorecard } from "./reporting/render-compatibility-scorecard.js";
@@ -28,8 +32,10 @@ import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
 import { renderRuleExplanation } from "./reporting/render-rule-explanation.js";
 import { renderSarifReport } from "./reporting/render-sarif-report.js";
 import { renderTextReport } from "./reporting/render-text-report.js";
+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";
@@ -55,7 +61,7 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor security <path> [--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 = [
@@ -188,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");
@@ -379,16 +470,107 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         const jsonOutput = remainingArgs.includes("--json");
         const scorecardOutput = remainingArgs.includes("--scorecard");
+        const policyIndex = remainingArgs.indexOf("--policy");
+        const policyName = policyIndex === -1 ? null : remainingArgs[policyIndex + 1];
+        const policy = parsePolicyPack(policyName);
         if (jsonOutput && scorecardOutput) {
             io.writeStderr("Use either --json or --scorecard, not both.");
             return 2;
         }
-        const audit = await buildSecurityAudit(maybePath);
+        if (policyIndex !== -1 && (!policyName || policyName.startsWith("--"))) {
+            io.writeStderr("Missing policy after --policy.");
+            return 2;
+        }
+        if (policyIndex !== -1 && !policy) {
+            io.writeStderr(`Unknown policy: ${policyName}. Supported policies: ${policyPackNames.join(", ")}.`);
+            return 2;
+        }
+        const audit = applyPolicyToSecurityAudit(await buildSecurityAudit(maybePath), policy);
         io.writeStdout(jsonOutput
             ? renderSecurityAuditJson(audit)
             : renderSecurityScorecard(audit, { includeFindings: !scorecardOutput }));
         return audit.status === "fail" ? 1 : 0;
     }
+    if (command === "mcp") {
+        if (!maybePath || maybePath.startsWith("--")) {
+            io.writeStderr("Missing target path. Usage: codex-plugin-doctor mcp <path> [--json] [--output <path>]");
+            return 2;
+        }
+        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 report = await buildGenericMcpDoctor(maybePath, {
+            env: terminalContext.env,
+            platform: terminalContext.platform
+        });
+        const renderedReport = jsonOutput
+            ? renderGenericMcpDoctorJson(report)
+            : renderGenericMcpDoctor(report);
+        if (outputPath) {
+            await writeFile(outputPath, renderedReport, "utf8");
+        }
+        io.writeStdout(renderedReport);
+        return report.exitCode;
+    }
+    if (command === "audit") {
+        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>]");
+            return 2;
+        }
+        const installedIndex = auditFlags.indexOf("--installed");
+        const installedFilter = auditFlags[installedIndex + 1] && !auditFlags[installedIndex + 1].startsWith("--")
+            ? auditFlags[installedIndex + 1]
+            : null;
+        const jsonOutput = auditFlags.includes("--json");
+        const includeSecurity = auditFlags.includes("--security");
+        const includeCompatibility = auditFlags.includes("--compat");
+        const outputIndex = auditFlags.indexOf("--output");
+        const outputPath = outputIndex === -1 ? null : auditFlags[outputIndex + 1];
+        const policyIndex = auditFlags.indexOf("--policy");
+        const policyName = policyIndex === -1 ? null : auditFlags[policyIndex + 1];
+        const policy = parsePolicyPack(policyName);
+        if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+            io.writeStderr("Missing path after --output.");
+            return 2;
+        }
+        if (policyIndex !== -1 && (!policyName || policyName.startsWith("--"))) {
+            io.writeStderr("Missing policy after --policy.");
+            return 2;
+        }
+        if (policyIndex !== -1 && !policy) {
+            io.writeStderr(`Unknown policy: ${policyName}. Supported policies: ${policyPackNames.join(", ")}.`);
+            return 2;
+        }
+        const report = await buildEcosystemAudit({
+            env: terminalContext.env,
+            platform: terminalContext.platform,
+            filter: installedFilter,
+            includeSecurity,
+            includeCompatibility,
+            failOnWarnings: policyFailsOnWarnings(policy),
+            validatePlugin: options.runCheckImpl ?? runCheck
+        });
+        if (report.summary.totalPlugins === 0) {
+            io.writeStderr(installedFilter
+                ? `No installed Codex plugins matched '${installedFilter}'.`
+                : "No installed Codex plugins found.");
+            return 1;
+        }
+        const renderedReport = jsonOutput
+            ? renderEcosystemAuditJson(report)
+            : renderEcosystemAudit(report);
+        if (outputPath) {
+            await writeFile(outputPath, renderedReport, "utf8");
+        }
+        io.writeStdout(renderedReport);
+        return report.status === "fail" ? 1 : 0;
+    }
     if (command === "compat") {
         const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
         const compatFlags = maybePath && maybePath.startsWith("--")
@@ -540,6 +722,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const profileIndex = normalizedFlags.indexOf("--profile");
     const profileName = profileIndex === -1 ? null : normalizedFlags[profileIndex + 1];
     const checkProfile = parseCheckProfile(profileName);
+    const policyIndex = normalizedFlags.indexOf("--policy");
+    const policyName = policyIndex === -1 ? null : normalizedFlags[policyIndex + 1];
+    const policy = parsePolicyPack(policyName);
     const historyIndex = normalizedFlags.indexOf("--history");
     const historyPath = historyIndex === -1 ? null : normalizedFlags[historyIndex + 1];
     if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
@@ -558,6 +743,14 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("Unknown profile. Supported profiles: ci, strict, publish.");
         return 2;
     }
+    if (policyIndex !== -1 && (!policyName || policyName.startsWith("--"))) {
+        io.writeStderr("Missing policy after --policy.");
+        return 2;
+    }
+    if (policyIndex !== -1 && !policy) {
+        io.writeStderr(`Unknown policy: ${policyName}. Supported policies: ${policyPackNames.join(", ")}.`);
+        return 2;
+    }
     if (historyIndex !== -1 && (!historyPath || historyPath.startsWith("--"))) {
         io.writeStderr("Missing path after --history.");
         return 2;
@@ -570,7 +763,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("History output requires a single package target.");
         return 2;
     }
-    const effectiveRuntimeProbeEnabled = runtimeProbeEnabled || checkProfile === "publish";
+    const effectiveRuntimeProbeEnabled = runtimeProbeEnabled ||
+        checkProfile === "publish" ||
+        policyEnablesRuntime(policy);
     const outputPolicy = determineOutputPolicy({
         jsonOutput: jsonOutput || badgeJsonOutput,
         markdownOutput: markdownOutput || badgeMarkdownOutput,
@@ -606,7 +801,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
                         ? (line) => io.writeStderr(line)
                         : undefined
-                }), applyCheckProfile(config, checkProfile)),
+                }), applyPolicyToDoctorConfig(applyCheckProfile(config, checkProfile), policy)),
                 compatibilityMatrix
             });
         }
@@ -643,7 +838,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
             ? (line) => io.writeStderr(line)
             : undefined
-    }), applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile));
+    }), applyPolicyToDoctorConfig(applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile), policy));
     if (renderer) {
         if (result.status === "fail") {
             renderer.stopFailure("Validation failed");

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

@@ -10,6 +10,8 @@ export interface SecurityAudit {
     };
     findings: Finding[];
 }
+export declare function auditMcpServerConfig(rootPath: string, parsedConfig: unknown): Finding[];
+export declare function buildSecurityAuditFromFindings(targetPath: string, findings: Finding[]): SecurityAudit;
 export declare function buildSecurityAudit(targetPath: string): Promise<SecurityAudit>;
 export declare function renderSecurityAuditJson(audit: SecurityAudit): string;
 export declare function renderSecurityScorecard(audit: SecurityAudit, options?: {

package/dist/security/security-audit.js

@@ -40,24 +40,7 @@ function containsPipeInstaller(args) {
         /\b(iwr|irm|invoke-webrequest|invoke-restmethod)\b[^|]*\|\s*(iex|invoke-expression)\b/.test(joinedArgs) ||
         /\binvoke-expression\b/.test(joinedArgs));
 }
-async function auditMcpCommandSurface(discoveredPackage) {
-    const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.mcpServers) {
-        return [];
-    }
-    const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
-    if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
-        return [];
-    }
-    let parsedConfig;
-    try {
-        parsedConfig = await readJsonFile(mcpConfigPath);
-    }
-    catch {
-        return [
-            buildFinding("fail", "plugin.security.audit_unavailable", "The MCP security audit could not parse the referenced MCP config.", "Unreadable MCP configuration prevents review of server commands, URLs, and working directories before install.", "Fix the `.mcp.json` syntax, then rerun `codex-plugin-doctor security <path>`.")
-        ];
-    }
+export function auditMcpServerConfig(rootPath, parsedConfig) {
     if (!isPlainObject(parsedConfig) || !isPlainObject(parsedConfig.mcpServers)) {
         return [
             buildFinding("fail", "plugin.security.audit_unavailable", "The MCP security audit could not find a valid `mcpServers` object.", "Without server entries, the audit cannot evaluate command execution or remote transport risk.", "Define MCP servers under a top-level `mcpServers` object.")
@@ -93,6 +76,26 @@ async function auditMcpCommandSurface(discoveredPackage) {
     }
     return findings;
 }
+async function auditMcpCommandSurface(discoveredPackage) {
+    const { manifest, rootPath } = discoveredPackage;
+    if (!manifest.mcpServers) {
+        return [];
+    }
+    const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
+    if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+        return [];
+    }
+    let parsedConfig;
+    try {
+        parsedConfig = await readJsonFile(mcpConfigPath);
+    }
+    catch {
+        return [
+            buildFinding("fail", "plugin.security.audit_unavailable", "The MCP security audit could not parse the referenced MCP config.", "Unreadable MCP configuration prevents review of server commands, URLs, and working directories before install.", "Fix the `.mcp.json` syntax, then rerun `codex-plugin-doctor security <path>`.")
+        ];
+    }
+    return auditMcpServerConfig(rootPath, parsedConfig);
+}
 function dedupeFindings(findings) {
     const seen = new Set();
     return findings.filter((finding) => {
@@ -116,6 +119,22 @@ function buildFindingCounts(findings) {
 function scoreSecurityAudit(findingCounts) {
     return Math.max(0, 100 - (findingCounts.fail * 35) - (findingCounts.warn * 10));
 }
+export function buildSecurityAuditFromFindings(targetPath, findings) {
+    const dedupedFindings = dedupeFindings(findings);
+    const findingCounts = buildFindingCounts(dedupedFindings);
+    const status = findingCounts.fail > 0
+        ? "fail"
+        : findingCounts.warn > 0
+            ? "warn"
+            : "pass";
+    return {
+        targetPath: path.resolve(targetPath),
+        status,
+        score: scoreSecurityAudit(findingCounts),
+        findingCounts,
+        findings: dedupedFindings
+    };
+}
 export async function buildSecurityAudit(targetPath) {
     const discoveredPackage = await discoverPackage(targetPath);
     if (!discoveredPackage) {
@@ -133,23 +152,11 @@ export async function buildSecurityAudit(targetPath) {
     }
     const validationResult = await validatePlugin(discoveredPackage.rootPath);
     const validationSecurityFindings = validationResult.findings.filter((finding) => finding.id.startsWith("plugin.security."));
-    const findings = dedupeFindings([
+    const findings = [
         ...validationSecurityFindings,
         ...(await auditMcpCommandSurface(discoveredPackage))
-    ]);
-    const findingCounts = buildFindingCounts(findings);
-    const status = findingCounts.fail > 0
-        ? "fail"
-        : findingCounts.warn > 0
-            ? "warn"
-            : "pass";
-    return {
-        targetPath: discoveredPackage.rootPath,
-        status,
-        score: scoreSecurityAudit(findingCounts),
-        findingCounts,
-        findings
-    };
+    ];
+    return buildSecurityAuditFromFindings(discoveredPackage.rootPath, findings);
 }
 export function renderSecurityAuditJson(audit) {
     return JSON.stringify({

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;