codex-plugin-doctor 0.11.0 → 0.12.0

package/README.md

@@ -98,9 +98,12 @@ codex-plugin-doctor list --installed
 codex-plugin-doctor check --installed
 codex-plugin-doctor check --installed --all-summary
 codex-plugin-doctor check --installed --compat --all-summary
+codex-plugin-doctor audit --installed --security --compat
+codex-plugin-doctor audit --installed --security --compat --policy security
+codex-plugin-doctor mcp path/to/mcp-package
 codex-plugin-doctor check --installed github
-codex-plugin-doctor explain plugin.manifest.missing
-```
+codex-plugin-doctor explain plugin.manifest.missing
+```
 
 Run from source:
 
@@ -178,6 +181,12 @@ codex-plugin-doctor doctor snapshot --json
 codex-plugin-doctor doctor snapshot --output doctor-snapshot.json
 codex-plugin-doctor doctor clients
 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 mcp .
+codex-plugin-doctor mcp . --json
+codex-plugin-doctor mcp . --json --output mcp-doctor.json
 codex-plugin-doctor init my-plugin
 codex-plugin-doctor init my-mcp --template mcp-stdio
 codex-plugin-doctor init remote-mcp --template mcp-http
@@ -185,6 +194,7 @@ codex-plugin-doctor init runtime-demo --template full-runtime
 codex-plugin-doctor security .
 codex-plugin-doctor security . --scorecard
 codex-plugin-doctor security . --json
+codex-plugin-doctor security . --policy security
 codex-plugin-doctor compat .
 codex-plugin-doctor compat . --all --scorecard
 codex-plugin-doctor compat . --client codex
@@ -204,6 +214,9 @@ codex-plugin-doctor check .
 codex-plugin-doctor check . --profile ci
 codex-plugin-doctor check . --profile strict
 codex-plugin-doctor check . --profile publish
+codex-plugin-doctor check . --policy codex-publish
+codex-plugin-doctor check . --policy mcp-strict
+codex-plugin-doctor check . --policy security
 codex-plugin-doctor check . --json
 codex-plugin-doctor check . --explain
 codex-plugin-doctor check . --json --output report.json
@@ -229,6 +242,12 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `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.
 
+`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.
+
+`--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.
+
+`mcp <path>` diagnoses generic MCP packages that may not have a Codex plugin manifest. It looks for `.mcp.json` or a manifest `mcpServers` reference, validates the top-level `mcpServers` object and server transports, adds MCP command-surface security findings, and includes the all-client compatibility matrix in the same report.
+
 `init [path] --template ...` creates targeted starter packages. `skill-only` is the default minimal skill package, `mcp-stdio` adds a local stdio MCP config and mock server, `mcp-http` scaffolds a streamable HTTP MCP config, and `full-runtime` generates a stdio sample that passes the runtime protocol probes.
 
 `security <path>` renders a focused package security scorecard. It reuses the existing package security findings, then adds deeper MCP command-surface checks for shell wrappers, encoded shell payloads, remote pipe-to-shell startup patterns, `cwd` values outside the plugin root, and plain HTTP URLs. Use `--json` for automation or `--scorecard` for a compact status view.

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

@@ -0,0 +1,36 @@
+import type { CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+import type { InstalledPlugin } from "../core/discover-installed-plugins.js";
+import type { CheckResult } from "../domain/types.js";
+import type { SecurityAudit } from "../security/security-audit.js";
+export interface EcosystemAuditOptions {
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    filter?: string | null;
+    includeSecurity?: boolean;
+    includeCompatibility?: boolean;
+    failOnWarnings?: boolean;
+    validatePlugin: (targetPath: string) => Promise<CheckResult>;
+}
+export interface EcosystemAuditPluginResult {
+    plugin: InstalledPlugin;
+    status: "pass" | "warn" | "fail";
+    validation: CheckResult;
+    security?: SecurityAudit;
+    compatibility?: CompatibilityMatrix;
+}
+export interface EcosystemAuditReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    status: "pass" | "warn" | "fail";
+    summary: {
+        totalPlugins: number;
+        pass: number;
+        warn: number;
+        fail: number;
+    };
+    plugins: EcosystemAuditPluginResult[];
+    priorityActions: string[];
+}
+export declare function buildEcosystemAudit(options: EcosystemAuditOptions): Promise<EcosystemAuditReport>;
+export declare function renderEcosystemAuditJson(report: EcosystemAuditReport): string;
+export declare function renderEcosystemAudit(report: EcosystemAuditReport): string;

package/dist/audit/ecosystem-audit.js

@@ -0,0 +1,135 @@
+import { buildCompatibilityMatrix, matrixExitCode } from "../compatibility/compatibility-matrix.js";
+import { discoverInstalledPlugins, filterInstalledPlugins } from "../core/discover-installed-plugins.js";
+import { buildSecurityAudit } from "../security/security-audit.js";
+function mergeStatus(statuses) {
+    if (statuses.includes("fail")) {
+        return "fail";
+    }
+    if (statuses.includes("warn")) {
+        return "warn";
+    }
+    return "pass";
+}
+function compatibilityStatus(matrix) {
+    if (!matrix) {
+        return "pass";
+    }
+    if (matrixExitCode(matrix) === 1) {
+        return "fail";
+    }
+    return matrix.results.some((result) => result.status === "warn") ? "warn" : "pass";
+}
+function summarizePlugins(plugins) {
+    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
+    };
+}
+function buildPriorityActions(plugins) {
+    const actions = [];
+    const cleanReason = (reason) => reason.replace(/[.。]+$/u, "");
+    for (const plugin of plugins.filter((item) => item.status === "fail")) {
+        const validationFinding = plugin.validation.findings[0];
+        const securityFinding = plugin.security?.findings[0];
+        const compatibilityFinding = plugin.compatibility?.results.find((result) => result.status === "fail");
+        const reason = validationFinding?.id ??
+            securityFinding?.id ??
+            compatibilityFinding?.summary ??
+            "unknown failure";
+        actions.push(`${plugin.plugin.name}: fix ${cleanReason(reason)}.`);
+    }
+    for (const plugin of plugins.filter((item) => item.status === "warn")) {
+        const securityFinding = plugin.security?.findings[0];
+        const compatibilityFinding = plugin.compatibility?.results.find((result) => result.status === "warn");
+        const reason = securityFinding?.id ??
+            compatibilityFinding?.summary ??
+            plugin.validation.findings[0]?.id ??
+            "warning";
+        actions.push(`${plugin.plugin.name}: review ${cleanReason(reason)}.`);
+    }
+    return actions;
+}
+export async function buildEcosystemAudit(options) {
+    const installedPlugins = filterInstalledPlugins(await discoverInstalledPlugins({ env: options.env }), options.filter ?? null);
+    const environment = {
+        env: options.env,
+        platform: options.platform
+    };
+    const plugins = [];
+    for (const plugin of installedPlugins) {
+        const validation = await options.validatePlugin(plugin.rootPath);
+        const security = options.includeSecurity
+            ? await buildSecurityAudit(plugin.rootPath)
+            : undefined;
+        const compatibility = options.includeCompatibility
+            ? await buildCompatibilityMatrix(plugin.rootPath, environment)
+            : undefined;
+        const rawStatus = mergeStatus([
+            validation.status,
+            security?.status ?? "pass",
+            compatibilityStatus(compatibility)
+        ]);
+        const status = options.failOnWarnings && rawStatus === "warn"
+            ? "fail"
+            : rawStatus;
+        plugins.push({
+            plugin,
+            status,
+            validation,
+            ...(security ? { security } : {}),
+            ...(compatibility ? { compatibility } : {})
+        });
+    }
+    const summary = summarizePlugins(plugins);
+    const status = summary.fail > 0
+        ? "fail"
+        : summary.warn > 0
+            ? "warn"
+            : "pass";
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        status,
+        summary,
+        plugins,
+        priorityActions: buildPriorityActions(plugins)
+    };
+}
+export function renderEcosystemAuditJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderEcosystemAudit(report) {
+    const lines = [
+        "Local Ecosystem Audit",
+        "=====================",
+        `Status: ${report.status.toUpperCase()}`,
+        `Installed plugins: ${report.summary.totalPlugins}`,
+        `Summary: ${report.summary.fail} fail, ${report.summary.warn} warn, ${report.summary.pass} pass`
+    ];
+    if (report.plugins.length === 0) {
+        lines.push("", "No installed Codex plugins found.");
+        return lines.join("\n");
+    }
+    lines.push("", "Plugins", "-------");
+    for (const item of report.plugins) {
+        const version = item.plugin.version ? `@${item.plugin.version}` : "";
+        lines.push(`- ${item.plugin.name}${version}: ${item.status.toUpperCase()}`);
+        lines.push(`  Validation: ${item.validation.status.toUpperCase()}`);
+        if (item.security) {
+            lines.push(`  Security: ${item.security.status.toUpperCase()} (${item.security.score}/100)`);
+        }
+        if (item.compatibility) {
+            const compatibilitySummary = item.compatibility.results
+                .map((result) => `${result.client}=${result.status}`)
+                .join(", ");
+            lines.push(`  Compatibility: ${compatibilitySummary}`);
+        }
+    }
+    if (report.priorityActions.length > 0) {
+        lines.push("", "Priority Actions", "----------------");
+        lines.push(...report.priorityActions.map((action) => `- ${action}`));
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 import type { CheckOptions, CheckResult } from "./domain/types.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard, type SecurityAudit } from "./security/security-audit.js";
 export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson, type DoctorSnapshot } from "./core/doctor-snapshot.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";
 export declare function runCheck(targetPath: string, options?: CheckOptions): Promise<CheckResult>;

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 { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } from "./core/doctor-snapshot.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";
 export async function runCheck(targetPath, options = {}) {
     return validatePlugin(targetPath, options);
 }

package/dist/mcp/generic-mcp-doctor.d.ts

@@ -0,0 +1,16 @@
+import { type CompatibilityEnvironment, type CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+import type { Finding } from "../domain/types.js";
+import { type SecurityAudit } from "../security/security-audit.js";
+export interface GenericMcpDoctorReport {
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    mcpConfigPath: string | null;
+    serverCount: number;
+    findings: Finding[];
+    security: SecurityAudit;
+    compatibility: CompatibilityMatrix;
+}
+export declare function buildGenericMcpDoctor(targetPath: string, environment?: CompatibilityEnvironment): Promise<GenericMcpDoctorReport>;
+export declare function renderGenericMcpDoctorJson(report: GenericMcpDoctorReport): string;
+export declare function renderGenericMcpDoctor(report: GenericMcpDoctorReport): string;

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";
@@ -18,6 +19,7 @@ import { renderClientDoctor, renderEnvironmentDoctor, renderEnvironmentDoctorJso
 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,6 +30,7 @@ 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 { createLiveStatusRenderer } from "./terminal/live-status-renderer.js";
@@ -55,7 +58,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 [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 = [
@@ -379,16 +382,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 +634,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 +655,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 +675,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 +713,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 +750,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/package.json

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