codex-plugin-doctor 1.57.0 → 1.59.0

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/reporting/render-submission-report.d.ts

@@ -0,0 +1,5 @@
+import type { SubmissionPreflightReport } from "../core/submission-preflight.js";
+export declare function renderSubmissionPreflightJson(report: SubmissionPreflightReport): string;
+export declare function renderSubmissionPreflightText(report: SubmissionPreflightReport): string;
+export declare function renderSubmissionPreflightMarkdown(report: SubmissionPreflightReport): string;
+export declare function submissionPreflightExitCode(report: SubmissionPreflightReport, requireReady: boolean): 0 | 1;

package/dist/reporting/render-submission-report.js

@@ -0,0 +1,68 @@
+function upper(value) {
+    return value.replace(/[-_]/gu, " ").toUpperCase();
+}
+function findingsByCheck(report) {
+    const findings = new Map(report.findings.map((finding) => [finding.id, finding]));
+    return report.checks.map((check) => ({
+        check,
+        findings: check.findingIds.flatMap((id) => {
+            const finding = findings.get(id);
+            return finding ? [finding] : [];
+        })
+    }));
+}
+function escapeMarkdown(value) {
+    return value.replace(/[\\`*_{}\[\]()<>#+\-.!|]/gu, "\\$&");
+}
+function textSummary(report) {
+    return [
+        `Ruleset: ${report.rulesetVersion}`,
+        `Target: ${report.targetType}`,
+        `Automatic status: ${upper(report.status)}`,
+        `Readiness: ${upper(report.readiness)}`,
+        `Summary: ${report.summary.passed} passed, ${report.summary.warnings} warnings, ${report.summary.blockers} blockers, ${report.summary.manualChecks} manual checks`,
+        "Manual review is required; automatic checks do not complete directory review."
+    ];
+}
+export function renderSubmissionPreflightJson(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}
+export function renderSubmissionPreflightText(report) {
+    const lines = ["Submission preflight", "====================", ...textSummary(report), "", "Findings by check"];
+    for (const { check, findings } of findingsByCheck(report)) {
+        lines.push(`${check.id} (${upper(check.status)})`);
+        lines.push(...(findings.length === 0
+            ? ["  None"]
+            : findings.map((finding) => `  ${upper(finding.severity)} ${finding.id}: ${finding.message}`)));
+    }
+    lines.push("", "Manual checklist");
+    lines.push(...report.manualChecklist.map((item) => `  ${upper(item.state)} ${item.id}: ${item.label}`));
+    return `${lines.join("\n")}\n`;
+}
+export function renderSubmissionPreflightMarkdown(report) {
+    const lines = [
+        "# Submission preflight",
+        "",
+        `- Ruleset: ${escapeMarkdown(report.rulesetVersion)}`,
+        `- Target: ${escapeMarkdown(report.targetType)}`,
+        `- Automatic status: ${escapeMarkdown(upper(report.status))}`,
+        `- Readiness: ${escapeMarkdown(upper(report.readiness))}`,
+        `- Summary: ${report.summary.passed} passed, ${report.summary.warnings} warnings, ${report.summary.blockers} blockers, ${report.summary.manualChecks} manual checks`,
+        "",
+        "Manual review is required; automatic checks do not complete directory review.",
+        "",
+        "## Findings by check"
+    ];
+    for (const { check, findings } of findingsByCheck(report)) {
+        lines.push("", `### ${escapeMarkdown(check.id)} (${escapeMarkdown(upper(check.status))})`);
+        lines.push(...(findings.length === 0
+            ? ["- None"]
+            : findings.map((finding) => `- **${escapeMarkdown(upper(finding.severity))}** ${escapeMarkdown(finding.id)}: ${escapeMarkdown(finding.message)}`)));
+    }
+    lines.push("", "## Manual checklist");
+    lines.push(...report.manualChecklist.map((item) => `- ${escapeMarkdown(upper(item.state))}: ${escapeMarkdown(item.id)} — ${escapeMarkdown(item.label)}`));
+    return `${lines.join("\n")}\n`;
+}
+export function submissionPreflightExitCode(report, requireReady) {
+    return requireReady && report.status === "fail" ? 1 : 0;
+}

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

@@ -19,6 +19,7 @@ import { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRe
 import { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson } from "./core/doctor-export-bundle.js";
 import { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestationJson, renderDoctorAttestationVerification, renderDoctorAttestationVerificationJson, verifyDoctorAttestation } from "./core/attestation.js";
 import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
+import { buildSubmissionPreflight } from "./core/submission-preflight.js";
 import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 import { buildExternalValidationCorpusReport, ExternalCorpusManifestError } from "./core/external-validation-corpus.js";
 import { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport, CorpusMetricsDiffError, CorpusMetricsManifestError, renderCorpusQualityMetricsDiffJson, renderCorpusQualityMetricsDiffMarkdown, renderCorpusQualityMetricsDiffText, renderCorpusQualityMetricsJson, renderCorpusQualityMetricsMarkdown, renderCorpusQualityMetricsText } from "./core/corpus-quality-metrics.js";
@@ -57,6 +58,7 @@ import { renderSuppressionList, renderSuppressionListJson, renderSuppressionMuta
 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 { renderSubmissionPreflightJson, renderSubmissionPreflightMarkdown, renderSubmissionPreflightText, submissionPreflightExitCode } from "./reporting/render-submission-report.js";
 import { applyPolicyToDepAudit, 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";
@@ -86,6 +88,13 @@ const defaultIo = {
         }
     }
 };
+function writeExactStdout(io, message) {
+    if (io === defaultIo) {
+        process.stdout.write(message);
+        return;
+    }
+    io.writeStdout(message);
+}
 class CliUsageError extends Error {
 }
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
@@ -177,6 +186,7 @@ function printUsage(io) {
     io.writeStderr("Suppression governance: codex-plugin-doctor suppress list <path> [--fail-on-expired] [--fail-on-invalid] [--warn-expiring-within-days <days>]\n       codex-plugin-doctor suppress prune <path> [--apply] [--json]");
     io.writeStderr("Baseline gating: codex-plugin-doctor baseline create <path> --output <path> [--runtime]\n       codex-plugin-doctor check <path> --baseline <path>");
     io.writeStderr("Remote MCP runtime flags (check, mcp, release check, and doctor release-evidence): --runtime --allow-network [--allow-local-network] [--allow-session-lifecycle] [--require-remote-reliability]\n       --allow-session-lifecycle requires --runtime --allow-network and can terminate a remote session.\n       --require-remote-reliability requires --runtime --allow-network, blocks non-pass reliability, and does not grant network consent.");
+    io.writeStderr("       codex-plugin-doctor doctor submission <path> [--json|--markdown] [--output <path>] [--require-ready]");
 }
 const suppressUsageText = [
     "Usage:",
@@ -970,6 +980,74 @@ function parseSelectedFixActionIndexes(answer, actionCount) {
         ? actionIndexes
         : null;
 }
+function parseSubmissionCommandArgs(args) {
+    let targetPath = null;
+    let jsonOutput = false;
+    let markdownOutput = false;
+    let outputPath = null;
+    let requireReady = false;
+    let optionsEnded = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--" && !optionsEnded) {
+            optionsEnded = true;
+        }
+        else if (optionsEnded) {
+            if (targetPath === null) {
+                targetPath = argument;
+            }
+            else {
+                return new CliUsageError(`Unexpected submission argument: ${argument}.`);
+            }
+        }
+        else if (argument === "--json") {
+            if (jsonOutput)
+                return new CliUsageError("Duplicate submission flag: --json.");
+            jsonOutput = true;
+        }
+        else if (argument === "--markdown") {
+            if (markdownOutput)
+                return new CliUsageError("Duplicate submission flag: --markdown.");
+            markdownOutput = true;
+        }
+        else if (argument === "--require-ready") {
+            if (requireReady)
+                return new CliUsageError("Duplicate submission flag: --require-ready.");
+            requireReady = true;
+        }
+        else if (argument === "--output") {
+            if (outputPath !== null)
+                return new CliUsageError("Duplicate submission flag: --output.");
+            const value = args[index + 1];
+            if (!value || value.startsWith("--"))
+                return new CliUsageError("Missing path after --output.");
+            outputPath = value;
+            index += 1;
+        }
+        else if (argument.startsWith("--output=")) {
+            if (outputPath !== null)
+                return new CliUsageError("Duplicate submission flag: --output.");
+            const value = argument.slice("--output=".length);
+            if (!value)
+                return new CliUsageError("Missing path after --output.");
+            outputPath = value;
+        }
+        else if (argument.startsWith("--")) {
+            return new CliUsageError(`Unknown submission flag: ${argument}.`);
+        }
+        else if (targetPath === null) {
+            targetPath = argument;
+        }
+        else {
+            return new CliUsageError(`Unexpected submission argument: ${argument}.`);
+        }
+    }
+    if (targetPath === null)
+        return new CliUsageError("Missing target path for submission.");
+    if (jsonOutput && markdownOutput)
+        return new CliUsageError("Use either --json or --markdown, not both.");
+    return { targetPath, jsonOutput, markdownOutput, outputPath, requireReady };
+}
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
     const runtimeSandboxSupported = (command === "check" &&
@@ -1079,6 +1157,24 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 : renderDoctorOutputContract(contract, { outputPath }));
             return 0;
         }
+        if (maybePath === "submission") {
+            const parsedSubmissionArgs = parseSubmissionCommandArgs(remainingArgs);
+            if (parsedSubmissionArgs instanceof CliUsageError) {
+                io.writeStderr(parsedSubmissionArgs.message);
+                return 2;
+            }
+            const report = await buildSubmissionPreflight(parsedSubmissionArgs.targetPath);
+            const renderedReport = parsedSubmissionArgs.jsonOutput
+                ? renderSubmissionPreflightJson(report)
+                : parsedSubmissionArgs.markdownOutput
+                    ? renderSubmissionPreflightMarkdown(report)
+                    : renderSubmissionPreflightText(report);
+            if (parsedSubmissionArgs.outputPath) {
+                await writeFile(parsedSubmissionArgs.outputPath, renderedReport, "utf8");
+            }
+            writeExactStdout(io, renderedReport);
+            return submissionPreflightExitCode(report, parsedSubmissionArgs.requireReady);
+        }
         if (maybePath === "mcp") {
             const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
                 ? remainingArgs[0]

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[];

package/dist/security/security-audit.js

@@ -1,6 +1,7 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { discoverPackage } from "../core/discover-package.js";
+import { normalizeMcpConfig } from "../core/mcp-config-normalizer.js";
 import { readJsonFile } from "../core/read-json-file.js";
 import { inspectRemoteMcpUrl } from "../core/remote-url-policy.js";
 import { validatePlugin } from "../core/validate-plugin.js";
@@ -58,6 +59,101 @@ function containsPipeInstaller(args) {
         /\b(iwr|irm|invoke-webrequest|invoke-restmethod)\b[^|]*\|\s*(iex|invoke-expression)\b/.test(joinedArgs) ||
         /\binvoke-expression\b/.test(joinedArgs));
 }
+function relativeSourcePath(rootPath, sourcePath) {
+    return relativePackagePath(rootPath, path.resolve(rootPath, sourcePath));
+}
+export function auditHookCommand(rootPath, sourcePath, event, field, command) {
+    const evidence = { sourcePath: relativeSourcePath(rootPath, sourcePath), event, field };
+    const findings = [];
+    if (/(?:^|\s)[/-]enc(?:odedcommand)?(?=\s|$)/i.test(command)) {
+        findings.push(buildFinding("fail", "plugin.security.encoded_command", "A plugin lifecycle hook uses an encoded shell command flag.", "Encoded command payloads hide the executed script from reviewers and increase supply-chain risk.", "Replace encoded shell payloads with a checked-in script or readable direct command.", evidence));
+    }
+    if (containsHookRemotePipeInstaller(command)) {
+        findings.push(buildFinding("fail", "plugin.security.remote_pipe_install", "A plugin lifecycle hook appears to pipe remote content into a shell.", "Download-and-execute patterns can run unreviewed remote code when a host invokes the hook.", "Pin dependencies through the package manager or use a reviewed local script instead of piping remote content to a shell.", evidence));
+    }
+    if (/^\s*(?:cmd(?:\.exe)?\s+\/c|(?:powershell|pwsh)(?:\.exe)?\s+-(?:command|c)\b)/i.test(command)) {
+        findings.push(buildFinding("warn", "plugin.security.command_shell_wrapper", "A plugin lifecycle hook starts through a shell wrapper.", "Shell wrappers expand quoting, pipes, aliases, and platform-specific behavior, which makes the execution path harder to audit.", "Prefer a concrete executable or checked-in script with explicit arguments.", evidence));
+    }
+    return findings;
+}
+function containsHookRemotePipeInstaller(command) {
+    const firstPipeIndex = command.indexOf("|");
+    if (firstPipeIndex === -1)
+        return false;
+    const leftHandSide = command.slice(0, firstPipeIndex);
+    const rightHandSide = command.slice(firstPipeIndex + 1).trim();
+    const interpreter = /^(?:\/(?:[^/\s|]+\/)*(?:sh|bash)\b|(?:sh|bash)\b|(?:powershell|pwsh)(?:\.exe)?\s+-(?:command|c)\s+-\s*(?:$|[;&|])|(?:iex|invoke-expression)\b)/i;
+    return isInvokedHookDownloader(leftHandSide) && interpreter.test(rightHandSide);
+}
+function isInvokedHookDownloader(command) {
+    const tokens = command.trim().split(/\s+/).filter(Boolean);
+    let index = 0;
+    while (index < tokens.length) {
+        const token = tokens[index].toLowerCase();
+        if (token === "env") {
+            index += 1;
+            while (index < tokens.length) {
+                const envToken = tokens[index];
+                if (envToken === "--") {
+                    index += 1;
+                    break;
+                }
+                if (envToken === "-i" || envToken === "--ignore-environment") {
+                    index += 1;
+                    continue;
+                }
+                if (envToken === "-u" || envToken === "--unset") {
+                    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tokens[index + 1] ?? "")) {
+                        return false;
+                    }
+                    index += 2;
+                    continue;
+                }
+                if (/^--unset=[A-Za-z_][A-Za-z0-9_]*$/.test(envToken)) {
+                    index += 1;
+                    continue;
+                }
+                if (envToken === "-C" || envToken === "--chdir") {
+                    if (!tokens[index + 1] || tokens[index + 1].startsWith("-")) {
+                        return false;
+                    }
+                    index += 2;
+                    continue;
+                }
+                if (/^--chdir=\S+$/.test(envToken)) {
+                    index += 1;
+                    continue;
+                }
+                if (/^[A-Za-z_][A-Za-z0-9_]*=\S*$/.test(envToken)) {
+                    index += 1;
+                    continue;
+                }
+                break;
+            }
+            continue;
+        }
+        if (token === "command") {
+            index += 1;
+            if (tokens[index] === "-p" || tokens[index]?.toLowerCase() === "--default-search-path") {
+                index += 1;
+            }
+            if (tokens[index] === "--") {
+                index += 1;
+            }
+            continue;
+        }
+        break;
+    }
+    const downloader = normalizeCommandName(tokens[index] ?? "");
+    if (new Set(["curl", "wget", "iwr", "irm", "invoke-webrequest", "invoke-restmethod"]).has(downloader)) {
+        return true;
+    }
+    const shell = normalizeCommandName(tokens[index] ?? "");
+    return ((shell === "powershell" || shell === "pwsh") &&
+        /^-(?:command|c)$/i.test(tokens[index + 1] ?? "") &&
+        new Set(["curl", "wget", "iwr", "irm", "invoke-webrequest", "invoke-restmethod"])
+            .has(normalizeCommandName(tokens[index + 2] ?? "")));
+}
 const pathLikeArgFlags = new Set([
     "--config",
     "--config-path",
@@ -200,16 +296,14 @@ export function auditMcpServerConfig(rootPath, parsedConfig, options = {}) {
     const configPath = options.configPath
         ? relativePackagePath(rootPath, options.configPath)
         : ".mcp.json";
-    if (!isPlainObject(parsedConfig) || !isPlainObject(parsedConfig.mcpServers)) {
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    if (!normalizedConfig.ok) {
         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.", { configPath })
+            buildFinding("fail", "plugin.security.audit_unavailable", "The MCP security audit could not find a valid MCP server map.", "Without server entries, the audit cannot evaluate command execution or remote transport risk.", "Use a direct server map, `mcp_servers`, or `mcpServers`.", { configPath })
         ];
     }
     const findings = [];
-    for (const [serverName, serverConfig] of Object.entries(parsedConfig.mcpServers)) {
-        if (!isPlainObject(serverConfig)) {
-            continue;
-        }
+    for (const [serverName, serverConfig] of Object.entries(normalizedConfig.servers)) {
         const command = serverConfig.command;
         const args = serverConfig.args;
         const cwd = serverConfig.cwd;
@@ -395,7 +489,10 @@ async function auditMcpCommandSurface(discoveredPackage) {
 function dedupeFindings(findings) {
     const seen = new Set();
     return findings.filter((finding) => {
-        const key = `${finding.id}\n${finding.message}`;
+        const hookLocation = finding.evidence?.sourcePath && finding.evidence.event && finding.evidence.field
+            ? `${finding.evidence.sourcePath}\n${finding.evidence.event}\n${finding.evidence.field}`
+            : "";
+        const key = `${finding.id}\n${finding.message}\n${hookLocation}`;
         if (seen.has(key)) {
             return false;
         }