codex-plugin-doctor 1.59.0 → 1.61.0

package/dist/run-cli.js

@@ -19,7 +19,10 @@ 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 { buildSubmissionArchivePreflight, submissionArchiveExitCode } from "./core/submission-archive-preflight.js";
 import { buildSubmissionPreflight } from "./core/submission-preflight.js";
+import { discoverMcpServer } from "./core/mcp-discovery.js";
+import { renderMcpDiscoveryReport } from "./reporting/render-mcp-discovery-report.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";
@@ -58,6 +61,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 { renderSubmissionArchiveJson, renderSubmissionArchiveMarkdown, renderSubmissionArchiveText } from "./reporting/render-submission-archive-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";
@@ -97,6 +101,7 @@ function writeExactStdout(io, message) {
 }
 class CliUsageError extends Error {
 }
+const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json]";
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
     const index = flags.indexOf("--sandbox");
     if (index === -1) {
@@ -179,6 +184,7 @@ function parseRemoteNetworkFlags(flags, runtime) {
 }
 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>] [--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(discoveryUsage);
     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]");
@@ -186,7 +192,8 @@ 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]");
+    io.writeStderr("       codex-plugin-doctor doctor submission <path> [--json|--markdown] [--output <path>] [--require-ready]"
+        + "\n       codex-plugin-doctor doctor submission archive <zip> [--json|--markdown] [--output <path>] [--require-ready]");
 }
 const suppressUsageText = [
     "Usage:",
@@ -1048,6 +1055,90 @@ function parseSubmissionCommandArgs(args) {
         return new CliUsageError("Use either --json or --markdown, not both.");
     return { targetPath, jsonOutput, markdownOutput, outputPath, requireReady };
 }
+function parseSubmissionArchiveCommandArgs(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 archive argument: ${argument}.`);
+        }
+        else if (argument === "--json") {
+            if (jsonOutput)
+                return new CliUsageError("Duplicate submission archive flag: --json.");
+            jsonOutput = true;
+        }
+        else if (argument === "--markdown") {
+            if (markdownOutput)
+                return new CliUsageError("Duplicate submission archive flag: --markdown.");
+            markdownOutput = true;
+        }
+        else if (argument === "--require-ready") {
+            if (requireReady)
+                return new CliUsageError("Duplicate submission archive flag: --require-ready.");
+            requireReady = true;
+        }
+        else if (argument === "--output" || argument.startsWith("--output=")) {
+            if (outputPath !== null)
+                return new CliUsageError("Duplicate submission archive flag: --output.");
+            const value = argument === "--output" ? args[index + 1] : argument.slice("--output=".length);
+            if (!value || (argument === "--output" && value.startsWith("--")))
+                return new CliUsageError("Missing path after --output.");
+            outputPath = value;
+            if (argument === "--output")
+                index += 1;
+        }
+        else if (argument.startsWith("--"))
+            return new CliUsageError(`Unknown submission archive flag: ${argument}.`);
+        else if (targetPath === null)
+            targetPath = argument;
+        else
+            return new CliUsageError(`Unexpected submission archive argument: ${argument}.`);
+    }
+    if (targetPath === null)
+        return new CliUsageError("Missing archive path for submission.");
+    if (jsonOutput && markdownOutput)
+        return new CliUsageError("Use either --json or --markdown, not both.");
+    return { targetPath, jsonOutput, markdownOutput, outputPath, requireReady };
+}
+function hasArchiveSubcommandTarget(args) {
+    let optionsEnded = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (optionsEnded)
+            return true;
+        if (argument === "--") {
+            optionsEnded = true;
+        }
+        else if (argument === "--output") {
+            index += 1;
+        }
+        else if (!argument.startsWith("--")) {
+            return true;
+        }
+    }
+    return false;
+}
+async function submissionTargetExists(targetPath) {
+    try {
+        const { stat } = await import("node:fs/promises");
+        await stat(targetPath);
+        return true;
+    }
+    catch (error) {
+        return !(typeof error === "object" && error !== null && "code" in error
+            && error.code === "ENOENT");
+    }
+}
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
     const runtimeSandboxSupported = (command === "check" &&
@@ -1104,6 +1195,34 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return 0;
     }
     if (command === "doctor") {
+        if (maybePath === "discover") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${discoveryUsage}\nHTTP discovery only; runtime behavior is not tested.`);
+                return 0;
+            }
+            const [url, ...flags] = remainingArgs;
+            if (!url || url.startsWith("-")) {
+                io.writeStderr(discoveryUsage);
+                return 2;
+            }
+            const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
+            if (flags.some((flag) => !allowedFlags.has(flag)) || new Set(flags).size !== flags.length) {
+                io.writeStderr(`Invalid or duplicate discovery arguments. ${discoveryUsage}`);
+                return 2;
+            }
+            if (!flags.includes("--allow-network")) {
+                io.writeStderr("doctor discover requires explicit --allow-network consent.");
+                return 2;
+            }
+            const report = await (options.discoverMcpServerImpl ?? discoverMcpServer)(url, {
+                allowNetwork: true,
+                allowLocalNetwork: flags.includes("--allow-local-network")
+            });
+            io.writeStdout(flags.includes("--json")
+                ? JSON.stringify(report, null, 2)
+                : renderMcpDiscoveryReport(report));
+            return report.status === "discovered" ? 0 : report.status === "unsupported" ? 1 : 2;
+        }
         const doctorFlags = maybePath?.startsWith("--")
             ? [maybePath, ...remainingArgs]
             : remainingArgs;
@@ -1158,6 +1277,25 @@ export async function runCli(args, io = defaultIo, options = {}) {
             return 0;
         }
         if (maybePath === "submission") {
+            if (remainingArgs[0] === "archive") {
+                const useLegacyDirectoryTarget = !hasArchiveSubcommandTarget(remainingArgs.slice(1))
+                    && await submissionTargetExists("archive");
+                if (!useLegacyDirectoryTarget) {
+                    const parsedArchiveArgs = parseSubmissionArchiveCommandArgs(remainingArgs.slice(1));
+                    if (parsedArchiveArgs instanceof CliUsageError) {
+                        io.writeStderr(parsedArchiveArgs.message);
+                        return 2;
+                    }
+                    const report = await buildSubmissionArchivePreflight(parsedArchiveArgs.targetPath);
+                    const renderedReport = parsedArchiveArgs.jsonOutput
+                        ? renderSubmissionArchiveJson(report)
+                        : parsedArchiveArgs.markdownOutput ? renderSubmissionArchiveMarkdown(report) : renderSubmissionArchiveText(report);
+                    if (parsedArchiveArgs.outputPath)
+                        await writeFile(parsedArchiveArgs.outputPath, renderedReport, "utf8");
+                    writeExactStdout(io, renderedReport);
+                    return submissionArchiveExitCode(report, parsedArchiveArgs.requireReady);
+                }
+            }
             const parsedSubmissionArgs = parseSubmissionCommandArgs(remainingArgs);
             if (parsedSubmissionArgs instanceof CliUsageError) {
                 io.writeStderr(parsedSubmissionArgs.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.59.0",
+  "version": "1.61.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -57,12 +57,15 @@
   },
   "devDependencies": {
     "@types/node": "^24.2.1",
+    "@types/yauzl": "^3.4.0",
     "tsx": "^4.20.4",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },
   "dependencies": {
     "fast-xml-parser": "^5.11.0",
-    "yaml": "^2.9.0"
+    "iconv-lite": "^0.7.3",
+    "yaml": "^2.9.0",
+    "yauzl": "^3.4.0"
   }
 }