codex-plugin-doctor 1.56.0 → 1.58.0

package/dist/core/validate-plugin.js

@@ -2,6 +2,9 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 import { discoverPackage } from "./discover-package.js";
+import { normalizeMcpConfig } from "./mcp-config-normalizer.js";
+import { validatePluginComponents } from "./plugin-components.js";
+import { validatePluginHooks } from "./plugin-hooks.js";
 import { inspectRemoteMcpUrl } from "./remote-url-policy.js";
 import { probeRuntime, remoteReliabilityGatePassed } from "./runtime-probe.js";
 function buildFailure(id, message, impact, suggestedFix, evidence) {
@@ -24,6 +27,9 @@ function buildWarning(id, message, impact, suggestedFix, evidence) {
         ...(evidence ? { evidence } : {})
     };
 }
+function hasInvalidComponentPath(findings, field) {
+    return findings.some((finding) => finding.id === "plugin.manifest.invalid_path" && finding.evidence?.field === field);
+}
 function remoteUrlIssueFindingId(issue) {
     return issue === "insecure_non_loopback"
         ? "plugin.security.insecure_http_url"
@@ -223,9 +229,11 @@ function validateRequiredManifestFields(discoveredPackage) {
 }
 async function validateSkillsDirectory(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.skills) {
+    if (manifest.skills === undefined) {
         return [];
     }
+    if (typeof manifest.skills !== "string")
+        return [];
     const skillsPath = path.resolve(rootPath, manifest.skills);
     if (!isPathWithinRoot(rootPath, skillsPath)) {
         return [
@@ -233,7 +241,7 @@ async function validateSkillsDirectory(discoveredPackage) {
                 manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
                 field: "skills",
                 configuredPath: manifest.skills,
-                resolvedPath: skillsPath
+                resolvedPath: relativePackagePath(rootPath, skillsPath)
             })
         ];
     }
@@ -246,13 +254,13 @@ async function validateSkillsDirectory(discoveredPackage) {
             manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
             field: "skills",
             configuredPath: manifest.skills,
-            resolvedPath: skillsPath
+            resolvedPath: relativePackagePath(rootPath, skillsPath)
         })
     ];
 }
 async function validateSkillDefinitions(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.skills) {
+    if (typeof manifest.skills !== "string") {
         return [];
     }
     const skillsPath = path.resolve(rootPath, manifest.skills);
@@ -319,7 +327,7 @@ async function validateSkillDefinitions(discoveredPackage) {
 }
 async function validateMcpConfig(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.mcpServers) {
+    if (typeof manifest.mcpServers !== "string") {
         return [];
     }
     const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
@@ -353,20 +361,28 @@ async function validateMcpConfig(discoveredPackage) {
             buildFailure("plugin.mcp.invalid_json", "The referenced `.mcp.json` file is not valid JSON.", "Codex will not be able to parse bundled MCP server configuration.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "json" })
         ];
     }
-    if (!isPlainObject(parsedConfig)) {
-        return [
-            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a JSON object.", "Codex expects bundled MCP configuration to be object-shaped so server entries can be resolved reliably.", `Wrap the MCP configuration in a top-level object inside \`${mcpConfigPath}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "root" })
-        ];
-    }
-    const servers = parsedConfig.mcpServers;
-    if (!isPlainObject(servers) || Object.keys(servers).length === 0) {
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    if (!normalizedConfig.ok) {
+        if (normalizedConfig.reason === "ambiguous_shape") {
+            return [
+                buildFailure("plugin.mcp.ambiguous_shape", "The referenced `.mcp.json` file uses an ambiguous MCP config layout.", "Codex cannot safely choose between multiple wrapper layouts when they appear in one configuration file.", "Use exactly one supported layout: a direct server map, `mcp_servers`, or `mcpServers`.", { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "root" })
+            ];
+        }
+        if (normalizedConfig.field === "server" && normalizedConfig.invalidServerNames) {
+            return normalizedConfig.invalidServerNames.map((serverName) => buildFailure("plugin.mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "Codex cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`, {
+                configPath: relativePackagePath(rootPath, mcpConfigPath),
+                serverName,
+                field: "server"
+            }));
+        }
         return [
-            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a non-empty `mcpServers` object.", "Without a valid `mcpServers` object, Codex cannot discover the bundled MCP server definitions.", `Define bundled servers under \`mcpServers\` in \`${mcpConfigPath}\`.`, {
+            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a valid MCP server map.", "Without valid server entries, Codex cannot discover the bundled MCP server definitions.", `Use a direct server map, \`mcp_servers\`, or \`mcpServers\` in \`${mcpConfigPath}\`.`, {
                 configPath: relativePackagePath(rootPath, mcpConfigPath),
-                field: "mcpServers"
+                field: normalizedConfig.field
             })
         ];
     }
+    const servers = normalizedConfig.servers;
     const findings = [];
     for (const [serverName, serverConfig] of Object.entries(servers)) {
         if (!isPlainObject(serverConfig)) {
@@ -433,11 +449,17 @@ export async function validatePlugin(targetPath, options = {}) {
             findings: withFindingFingerprints([await buildMissingManifestFailure(rootPath)], rootPath)
         };
     }
+    const componentFindings = await validatePluginComponents(discoveredPackage);
+    const hookFindings = await validatePluginHooks(discoveredPackage);
+    const hasInvalidSkillsPath = hasInvalidComponentPath(componentFindings, "skills");
+    const hasInvalidMcpPath = hasInvalidComponentPath(componentFindings, "mcpServers");
     const staticFindings = [
         ...validateRequiredManifestFields(discoveredPackage),
-        ...(await validateSkillsDirectory(discoveredPackage)),
-        ...(await validateSkillDefinitions(discoveredPackage)),
-        ...(await validateMcpConfig(discoveredPackage))
+        ...componentFindings,
+        ...hookFindings,
+        ...(hasInvalidSkillsPath ? [] : await validateSkillsDirectory(discoveredPackage)),
+        ...(hasInvalidSkillsPath ? [] : await validateSkillDefinitions(discoveredPackage)),
+        ...(hasInvalidMcpPath ? [] : await validateMcpConfig(discoveredPackage))
     ];
     const staticFailed = staticFindings.some((finding) => finding.severity === "fail");
     const runtimeResult = options.runtime && !staticFailed

package/dist/domain/types.d.ts

@@ -55,7 +55,41 @@ export interface PluginManifest {
     description?: string;
     skills?: string;
     mcpServers?: string;
+    author?: unknown;
+    homepage?: unknown;
+    repository?: unknown;
+    license?: unknown;
+    keywords?: unknown;
+    apps?: unknown;
+    hooks?: PluginHooks;
+    interface?: unknown;
+}
+export declare const pluginHookEvents: readonly ["PreToolUse", "PermissionRequest", "PostToolUse", "PreCompact", "PostCompact", "UserPromptSubmit", "SubagentStop", "Stop", "SessionStart", "SubagentStart", "SessionEnd"];
+export type PluginHookEvent = (typeof pluginHookEvents)[number];
+export interface PluginHookCommandHandler {
+    type: "command";
+    command: string;
+    commandWindows?: string;
+    timeout?: number;
+    statusMessage?: string;
+    additionalContextLimit?: number;
+    async?: boolean;
+}
+export interface PluginHookUnsupportedHandler {
+    type: "prompt" | "agent";
+    async?: boolean;
+    [key: string]: unknown;
+}
+export type PluginHookHandler = PluginHookCommandHandler | PluginHookUnsupportedHandler;
+export interface PluginHookMatcherGroup {
+    matcher?: string;
+    hooks: PluginHookHandler[];
+}
+export interface PluginHookConfig {
+    description?: string;
+    hooks: Partial<Record<PluginHookEvent, PluginHookMatcherGroup[]>>;
 }
+export type PluginHooks = string | string[] | PluginHookConfig | PluginHookConfig[];
 export interface DiscoveredPackage {
     rootPath: string;
     manifestPath: string;

package/dist/domain/types.js

@@ -1 +1,13 @@
-export {};
+export const pluginHookEvents = [
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PreCompact",
+    "PostCompact",
+    "UserPromptSubmit",
+    "SubagentStop",
+    "Stop",
+    "SessionStart",
+    "SubagentStart",
+    "SessionEnd"
+];

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

@@ -1,6 +1,7 @@
 import { realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { buildCompatibilityMatrix, readMcpConfigPath } from "../compatibility/compatibility-matrix.js";
+import { normalizeMcpConfig } from "../core/mcp-config-normalizer.js";
 import { readJsonFile } from "../core/read-json-file.js";
 import { probeRuntimeConfig, remoteReliabilityGatePassed } from "../core/runtime-probe.js";
 import { formatFindingFingerprintLine, withFindingFingerprints } from "../reporting/finding-fingerprint.js";
@@ -15,9 +16,6 @@ function buildFinding(severity, id, message, impact, suggestedFix, evidence) {
         ...(evidence ? { evidence } : {})
     };
 }
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 async function fileExists(targetPath) {
     try {
         const details = await stat(targetPath);
@@ -32,6 +30,13 @@ function isPathWithinRoot(rootPath, candidatePath) {
     return (relativePath === "" ||
         (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
 }
+function isMcpConfigPathOutsideRootError(error) {
+    return error instanceof Error && (error.message === "MCP config path resolves outside the package root." ||
+        error.message === "Manifest MCP config path resolves outside the package root.");
+}
+function buildMcpConfigPathOutsideRootFinding(configPath) {
+    return 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.", { configPath, field: "configPath" });
+}
 function buildStaticMcpFindings(configPath, parsedConfig) {
     if (!configPath) {
         return {
@@ -41,29 +46,24 @@ function buildStaticMcpFindings(configPath, parsedConfig) {
             ]
         };
     }
-    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 \`${configPath}\`.`, { configPath, field: "root" })
-            ]
-        };
-    }
-    const servers = parsedConfig.mcpServers;
-    if (!isPlainObject(servers) || Object.keys(servers).length === 0) {
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    if (!normalizedConfig.ok) {
+        if (normalizedConfig.field === "server" && normalizedConfig.invalidServerNames) {
+            return {
+                serverCount: 0,
+                findings: normalizedConfig.invalidServerNames.map((serverName) => 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 \`${configPath}\` to an object.`, { configPath, serverName, field: "server" }))
+            };
+        }
         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 \`${configPath}\`.`, { configPath, field: "mcpServers" })
+                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must contain a valid MCP server map.", "Without server entries, MCP clients cannot discover any package capabilities.", `Use a direct server map, \`mcp_servers\`, or \`mcpServers\` in \`${configPath}\`.`, { configPath, field: normalizedConfig.field })
             ]
         };
     }
+    const servers = normalizedConfig.servers;
     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 \`${configPath}\` to an object.`, { configPath, serverName, field: "server" }));
-            continue;
-        }
         const command = serverConfig.command;
         const url = serverConfig.url;
         if (typeof command !== "string" && typeof url !== "string") {
@@ -90,7 +90,18 @@ function mergeReportStatus(findings, security) {
 export async function buildGenericMcpDoctor(targetPath, environment = {}, options = {}) {
     const rootPath = path.resolve(targetPath);
     const compatibility = await buildCompatibilityMatrix(rootPath, environment);
-    const mcpConfigPath = await readMcpConfigPath(rootPath);
+    let mcpConfigPath;
+    let mcpConfigPathOutsideRoot = false;
+    try {
+        mcpConfigPath = await readMcpConfigPath(rootPath);
+    }
+    catch (error) {
+        if (!isMcpConfigPathOutsideRootError(error)) {
+            throw error;
+        }
+        mcpConfigPath = null;
+        mcpConfigPathOutsideRoot = true;
+    }
     const canonicalRootPath = await realpath(rootPath).catch(() => null);
     const canonicalMcpConfigPath = mcpConfigPath
         ? await realpath(mcpConfigPath).catch(() => null)
@@ -98,18 +109,17 @@ export async function buildGenericMcpDoctor(targetPath, environment = {}, option
     let parsedConfig = null;
     let staticFindings = [];
     let serverCount = 0;
-    if (!mcpConfigPath || !(await fileExists(mcpConfigPath))) {
+    if (mcpConfigPathOutsideRoot) {
+        staticFindings = [buildMcpConfigPathOutsideRootFinding(".mcp.json")];
+    }
+    else if (!mcpConfigPath || !(await fileExists(mcpConfigPath))) {
         staticFindings = buildStaticMcpFindings(null, null).findings;
     }
     else if (!canonicalRootPath ||
         !canonicalMcpConfigPath ||
         !isPathWithinRoot(canonicalRootPath, canonicalMcpConfigPath)) {
         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.", {
-                configPath: path.relative(rootPath, mcpConfigPath).replaceAll("\\", "/"),
-                resolvedPath: canonicalMcpConfigPath ?? mcpConfigPath,
-                field: "configPath"
-            })
+            buildMcpConfigPathOutsideRootFinding(path.relative(rootPath, mcpConfigPath).replaceAll("\\", "/"))
         ];
     }
     else {
@@ -128,9 +138,12 @@ export async function buildGenericMcpDoctor(targetPath, environment = {}, option
             ];
         }
     }
-    const security = buildSecurityAuditFromFindings(rootPath, mcpConfigPath && parsedConfig !== null
-        ? auditMcpServerConfig(rootPath, parsedConfig, { configPath: mcpConfigPath })
-        : []);
+    const security = buildSecurityAuditFromFindings(rootPath, [
+        ...staticFindings.filter((finding) => finding.id === "mcp.config.path_outside_root"),
+        ...(mcpConfigPath && parsedConfig !== null
+            ? auditMcpServerConfig(rootPath, parsedConfig, { configPath: mcpConfigPath })
+            : [])
+    ]);
     const runtimeResult = options.runtime &&
         mcpConfigPath !== null &&
         parsedConfig !== null &&
@@ -156,7 +169,10 @@ export async function buildGenericMcpDoctor(targetPath, environment = {}, option
         exitCode: status === "fail" ? 1 : 0,
         mcpConfigPath,
         serverCount,
-        findings: [...fingerprintedFindings, ...security.findings],
+        findings: [
+            ...fingerprintedFindings,
+            ...security.findings.filter((finding) => !fingerprintedFindings.some((staticFinding) => staticFinding.fingerprint === finding.fingerprint))
+        ],
         security,
         compatibility,
         ...(runtimeResult ? { runtimeScorecard: runtimeResult.scorecard } : {}),

package/dist/rules/rule-catalog.js

@@ -53,6 +53,123 @@ export const ruleCatalog = [
         fix: "Add a short, specific `description` field to `.codex-plugin/plugin.json`.",
         example: '{ "description": "Validates GitHub PR automation workflows before release." }'
     },
+    {
+        id: "plugin.manifest.invalid_field",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "A plugin manifest optional field is invalid.",
+        why: "Malformed optional metadata cannot be interpreted reliably by Codex clients.",
+        fix: "Use the official type for the affected field in `.codex-plugin/plugin.json`.",
+        example: '{ "keywords": ["validation", "mcp"] }'
+    },
+    {
+        id: "plugin.manifest.invalid_path",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "A plugin manifest path is not a safe package-relative path.",
+        why: "Paths outside the plugin package can expose files that are not part of the plugin bundle.",
+        fix: "Use a `./` path that remains inside the plugin package.",
+        example: '{ "skills": "./skills" }'
+    },
+    {
+        id: "plugin.app.missing_file",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The plugin manifest points to a missing .app.json file.",
+        why: "Codex cannot load an app manifest that is absent or not a regular file.",
+        fix: "Create the referenced app manifest as a regular JSON file inside the plugin package.",
+        example: '{ "apps": "./apps/example.app.json" }'
+    },
+    {
+        id: "plugin.app.invalid_json",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The referenced .app.json file is not valid JSON.",
+        why: "Codex cannot parse the app manifest.",
+        fix: "Fix the JSON syntax in the referenced app manifest.",
+        example: "Use syntactically valid JSON in the referenced .app.json file."
+    },
+    {
+        id: "plugin.app.invalid_path",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "A plugin app path is not a safe package-relative path.",
+        why: "Paths outside the plugin package can expose files that are not part of the plugin bundle.",
+        fix: "Use an `./` app path that remains inside the plugin package.",
+        example: '{ "apps": "./apps/example.app.json" }'
+    },
+    {
+        id: "plugin.hook.missing_file",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The plugin lifecycle hook source file is missing.",
+        why: "Codex cannot load a hook configuration file that is absent or not a regular file.",
+        fix: "Create the referenced hook configuration JSON file inside the plugin package.",
+        example: '{ "hooks": "./hooks/hooks.json" }'
+    },
+    {
+        id: "plugin.hook.invalid_json",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The plugin lifecycle hook source is not valid JSON.",
+        why: "Codex cannot parse the hook configuration.",
+        fix: "Fix the JSON syntax in the hook configuration file.",
+        example: "Use syntactically valid JSON in the hook configuration file."
+    },
+    {
+        id: "plugin.hook.invalid_shape",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The plugin lifecycle hook configuration has an invalid shape.",
+        why: "Codex cannot safely interpret malformed lifecycle hook metadata.",
+        fix: "Use the official hook configuration schema for the affected field.",
+        example: '{ "hooks": { "PreToolUse": [{ "hooks": [{ "type": "command", "command": "node hooks/check.js" }] }] } }'
+    },
+    {
+        id: "plugin.hook.invalid_path",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The plugin lifecycle hook source is not a safe package-relative path.",
+        why: "Paths outside the plugin package can expose unreviewed files to hook configuration loading.",
+        fix: "Use a `./` hook configuration path that stays within the plugin package.",
+        example: '{ "hooks": "./hooks/hooks.json" }'
+    },
+    {
+        id: "plugin.hook.unsupported_event",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "A plugin lifecycle hook event is not supported.",
+        why: "Codex will not invoke hook events outside the official lifecycle event set.",
+        fix: "Use one of the official plugin lifecycle hook events.",
+        example: '{ "hooks": { "SessionStart": [] } }'
+    },
+    {
+        id: "plugin.hook.unsupported_handler",
+        category: "package",
+        defaultSeverity: "warn",
+        summary: "A plugin lifecycle hook uses a handler type the host skips.",
+        why: "Prompt and agent lifecycle handlers are not executed by this host.",
+        fix: "Use a command handler for behavior that must run in this host.",
+        example: '{ "type": "command", "command": "node hooks/check.js" }'
+    },
+    {
+        id: "plugin.hook.async_unsupported",
+        category: "package",
+        defaultSeverity: "warn",
+        summary: "A plugin lifecycle hook requests unsupported asynchronous execution.",
+        why: "The host does not support asynchronous lifecycle hook execution.",
+        fix: "Remove `async: true` or run the command synchronously.",
+        example: '{ "type": "command", "command": "node hooks/check.js" }'
+    },
+    {
+        id: "plugin.hook.matcher_ignored",
+        category: "package",
+        defaultSeverity: "warn",
+        summary: "A plugin lifecycle hook matcher is ignored for this event.",
+        why: "This lifecycle event does not use matcher filtering.",
+        fix: "Remove the matcher from this event group.",
+        example: '{ "hooks": { "Stop": [{ "hooks": [] }] } }'
+    },
     {
         id: "plugin.heuristic.description.too_long",
         category: "package",
@@ -138,10 +255,19 @@ export const ruleCatalog = [
         id: "plugin.mcp.invalid_shape",
         category: "mcp",
         defaultSeverity: "fail",
-        summary: "The `.mcp.json` file does not expose a valid `mcpServers` object.",
-        why: "Codex expects MCP configuration to be object-shaped with named server entries.",
-        fix: "Define a non-empty top-level `mcpServers` object.",
-        example: '{ "mcpServers": { "doctor": { "command": "node", "args": ["server.js"] } } }'
+        summary: "The `.mcp.json` file does not contain one non-empty supported server map.",
+        why: "Codex accepts exactly a direct server map, an `mcp_servers` wrapper, or the legacy `mcpServers` wrapper.",
+        fix: "Use exactly one non-empty direct server map, `mcp_servers`, or legacy `mcpServers` wrapper.",
+        example: '{ "doctor": { "command": "node", "args": ["server.js"] } }'
+    },
+    {
+        id: "plugin.mcp.ambiguous_shape",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "The `.mcp.json` file uses an ambiguous MCP config layout.",
+        why: "Codex cannot safely choose between multiple wrapper layouts when they appear in one configuration file.",
+        fix: "Use exactly one supported layout: a direct server map, `mcp_servers`, or `mcpServers`.",
+        example: '{ "weather": { "command": "node", "args": ["server.js"] } }'
     },
     {
         id: "plugin.mcp.server.invalid",

package/dist/run-cli.js

@@ -169,7 +169,7 @@ function parseRemoteNetworkFlags(flags, runtime) {
     return { allowNetwork, allowLocalNetwork, allowSessionLifecycle, requireRemoteReliability };
 }
 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 [--allow-network [--allow-local-network]]] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--runtime [--allow-network [--allow-local-network]]] [--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 suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\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 watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>] [--upload]|mcp <path> [--runtime [--allow-network [--allow-local-network]]]|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|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 init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker]\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 [--allow-network [--allow-local-network]]] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>] [--fail-on <rule-id>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--runtime [--allow-network [--allow-local-network]]] [--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 suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\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 watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>] [--upload]|mcp <path> [--runtime [--allow-network [--allow-local-network]]]|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|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 init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker]\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("Registry readiness: codex-plugin-doctor registry check <server.json|directory> [--json] [--output <path>] [--require-registry-readiness]\n"
         + "       codex-plugin-doctor registry inspect <server-name> --allow-network [--json] [--output <path>] [--require-registry-readiness]\n"
         + "Registry publication preflight: codex-plugin-doctor registry preflight <server.json|directory> [--allow-network] [--json] [--output <path>] [--require-publish-ready]");
@@ -2108,7 +2108,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 ? remainingArgs
                 : remainingArgs.slice(1);
             const jsonOutput = sizeFlags.includes("--json");
-            const report = await buildDoctorSize(sizeTarget);
+            const npmPack = sizeFlags.includes("--npm");
+            const report = await buildDoctorSize(sizeTarget, { npmPack });
             const output = jsonOutput
                 ? renderDoctorSizeJson(report)
                 : renderDoctorSize(report);
@@ -2905,6 +2906,13 @@ export async function runCli(args, io = defaultIo, options = {}) {
         : normalizedFlags[runtimeApprovalDigestIndex + 1];
     const changedSinceIndex = normalizedFlags.indexOf("--changed-since");
     const changedSinceRef = changedSinceIndex === -1 ? null : normalizedFlags[changedSinceIndex + 1];
+    const failOnRules = [];
+    for (let i = 0; i < normalizedFlags.length; i += 1) {
+        if (normalizedFlags[i] === "--fail-on" && normalizedFlags[i + 1] && !normalizedFlags[i + 1].startsWith("--")) {
+            failOnRules.push(normalizedFlags[i + 1]);
+            i += 1;
+        }
+    }
     const baselineIndex = normalizedFlags.indexOf("--baseline");
     const baselinePath = baselineIndex === -1 ? null : normalizedFlags[baselineIndex + 1];
     if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
@@ -3150,6 +3158,28 @@ export async function runCli(args, io = defaultIo, options = {}) {
             failOnWarnings: doctorConfig.failOnWarnings
         })
         : configuredResult;
+    if (failOnRules.length > 0) {
+        result.findings = result.findings.map((finding) => {
+            if (finding.severity === "warn" && failOnRules.includes(finding.id)) {
+                return { ...finding, severity: "fail" };
+            }
+            return finding;
+        });
+        const hasFail = result.findings.some((f) => f.severity === "fail");
+        const hasWarn = result.findings.some((f) => f.severity === "warn");
+        if (hasFail) {
+            result.status = "fail";
+            result.exitCode = 1;
+        }
+        else if (hasWarn) {
+            result.status = "warn";
+            result.exitCode = 0;
+        }
+        else {
+            result.status = "pass";
+            result.exitCode = 0;
+        }
+    }
     if (renderer) {
         if (result.status === "fail") {
             renderer.stopFailure("Validation failed");

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

@@ -10,6 +10,7 @@ export interface SecurityAudit {
     };
     findings: Finding[];
 }
+export declare function auditHookCommand(rootPath: string, sourcePath: string, event: string, field: string, command: string): Finding[];
 export declare function auditMcpServerConfig(rootPath: string, parsedConfig: unknown, options?: {
     configPath?: string;
 }): Finding[];