codex-plugin-doctor 1.68.0 → 1.70.0

package/dist/run-cli.js

@@ -21,11 +21,14 @@ import { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestatio
 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 { isValidBearerToken } from "./core/bounded-http-client.js";
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { captureMcpToolCatalog, inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
+import { captureStdioMcpToolCatalog, resolveMcpStdioServer } from "./core/mcp-stdio-tool-catalog.js";
 import { inspectMcpToolFile, isBlockedOfflinePath } from "./core/mcp-tool-file.js";
 import { saveMcpToolsListResponse } from "./core/mcp-tool-response-file.js";
 import { compareMcpToolFiles } from "./core/mcp-tool-diff.js";
+import { renderMcpToolDiffMarkdown } from "./reporting/render-mcp-tool-diff-markdown.js";
 import { renderMcpToolDiffReport } from "./reporting/render-mcp-tool-diff-report.js";
 import { renderMcpToolFileReport } from "./reporting/render-mcp-tool-file-report.js";
 import { renderMcpToolCatalogReport } from "./reporting/render-mcp-tool-catalog-report.js";
@@ -108,10 +111,123 @@ function writeExactStdout(io, message) {
 }
 class CliUsageError extends Error {
 }
-const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json] [--fail-on any|breaking]";
+const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json|--markdown] [--fail-on any|breaking]";
 const toolsFileUsage = "Usage: codex-plugin-doctor doctor tools-file <path> [--json]";
-const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json] [--save-response <path>]";
-const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json]";
+const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json] [--save-response <path>] [--bearer-token-env <NAME>]\n       codex-plugin-doctor doctor tools <path> --server <name> --runtime [--sandbox docker] [--require-runtime-approval [--runtime-approval-digest <digest>]] [--json] [--save-response <path>]";
+const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json] [--bearer-token-env <NAME>]";
+const bearerTokenHelp = "--bearer-token-env reads a bearer token from the named environment variable and sends it only over HTTPS or to an approved loopback target; the token is never printed or saved.";
+const ENVIRONMENT_VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+function resolveBearerToken(name, env) {
+    if (name === undefined)
+        return {};
+    if (!ENVIRONMENT_VARIABLE_NAME.test(name))
+        return { error: "--bearer-token-env requires an environment variable name." };
+    const token = env[name];
+    if (token === undefined || token === "")
+        return { error: `Bearer token environment variable is not set: ${name}` };
+    if (!isValidBearerToken(token))
+        return { error: `Bearer token environment variable does not hold a valid bearer token: ${name}` };
+    return { token };
+}
+async function finishToolCatalogCommand(io, snapshot, json, savePath) {
+    const report = snapshot.report;
+    io.writeStdout(json
+        ? JSON.stringify(report, null, 2)
+        : renderMcpToolCatalogReport(report));
+    const exitCode = report.status === "pass" ? 0
+        : report.status === "incomplete" || report.status === "blocked" ? 2 : 1;
+    if (savePath === undefined)
+        return exitCode;
+    if (snapshot.tools === null || snapshot.cache === null) {
+        io.writeStderr("Tool catalog response was not saved because enumeration did not complete.");
+        return 2;
+    }
+    const saved = await saveMcpToolsListResponse(savePath, snapshot.tools, snapshot.cache);
+    if (saved.kind !== "saved") {
+        io.writeStderr({
+            "path-blocked": "Tool catalog response was not saved because the path is not a local file path.",
+            "not-regular": "Tool catalog response was not saved because the existing target is not a regular file.",
+            "too-large": "Tool catalog response was not saved because it exceeds the one MiB tools-file limit.",
+            "write-failed": "Tool catalog response could not be written."
+        }[saved.kind]);
+        return 2;
+    }
+    io.writeStderr(`Saved a complete tools/list response with ${saved.tools} tools (${saved.bytes} bytes).`);
+    return exitCode;
+}
+async function runStdioToolCatalogCommand(targetPath, flags, io, options) {
+    const allowedSwitches = new Set(["--runtime", "--json", "--require-runtime-approval"]);
+    const switches = [];
+    const values = new Map();
+    let invalid = false;
+    for (let index = 0; index < flags.length; index += 1) {
+        const flag = flags[index];
+        if (["--server", "--save-response", "--sandbox", "--runtime-approval-digest"].includes(flag) && !values.has(flag)) {
+            const value = flags[index + 1];
+            if (!value || value.startsWith("-")) {
+                invalid = true;
+                break;
+            }
+            values.set(flag, value);
+            index += 1;
+        }
+        else if (allowedSwitches.has(flag) && !switches.includes(flag)) {
+            switches.push(flag);
+        }
+        else {
+            invalid = true;
+            break;
+        }
+    }
+    const serverName = values.get("--server");
+    const savePath = values.get("--save-response");
+    const sandbox = values.get("--sandbox");
+    const approvalDigest = values.get("--runtime-approval-digest");
+    const requireApproval = switches.includes("--require-runtime-approval");
+    if (invalid || serverName === undefined || (sandbox !== undefined && sandbox !== "docker")) {
+        io.writeStderr(`Invalid or duplicate tool catalog arguments. ${toolsUsage}`);
+        return 2;
+    }
+    if (!switches.includes("--runtime")) {
+        io.writeStderr("doctor tools --server starts a local MCP server and requires explicit --runtime consent.");
+        return 2;
+    }
+    if (approvalDigest !== undefined && !requireApproval) {
+        io.writeStderr("--runtime-approval-digest requires --require-runtime-approval.");
+        return 2;
+    }
+    if (isBlockedOfflinePath(targetPath)) {
+        io.writeStderr("doctor tools --server requires a local package path.");
+        return 2;
+    }
+    if (savePath !== undefined && isBlockedOfflinePath(savePath)) {
+        io.writeStderr("doctor tools --save-response requires a local file path.");
+        return 2;
+    }
+    const resolved = await resolveMcpStdioServer(targetPath, serverName);
+    if (!resolved.ok) {
+        io.writeStderr(resolved.message);
+        return 2;
+    }
+    if (requireApproval) {
+        // Runtime plan digests cover only the manifest mcpServers file, so .mcp.json servers cannot be approved.
+        if (resolved.server.source !== "manifest") {
+            io.writeStderr("Runtime approval covers servers from the plugin manifest mcpServers file; this server comes from .mcp.json.");
+            return 2;
+        }
+        const runtimePlan = await buildDoctorRuntimePlan(targetPath, new Date().toISOString(), sandbox === "docker" ? { sandbox: "docker" } : {});
+        const approval = evaluateRuntimeApproval(runtimePlan, {
+            required: true,
+            approvedDigest: approvalDigest ?? null
+        });
+        if (!runtimeApprovalPassed(approval)) {
+            io.writeStderr(`${approval.message}\nCurrent runtime plan digest: ${runtimePlan.digest}`);
+            return 1;
+        }
+    }
+    const snapshot = await (options.captureStdioMcpToolCatalogImpl ?? captureStdioMcpToolCatalog)(resolved.server, sandbox === "docker" ? { sandbox: "docker" } : {});
+    return finishToolCatalogCommand(io, snapshot, switches.includes("--json"), savePath);
+}
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
     const index = flags.indexOf("--sandbox");
     if (index === -1) {
@@ -1160,9 +1276,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
         (command === "release" && maybePath === "check") ||
         (command === "doctor" &&
             (["runtime-plan", "runtime-policy"].includes(maybePath ?? "") ||
-                (maybePath === "release-evidence" && remainingArgs[0] !== "verify")));
+                (maybePath === "release-evidence" && remainingArgs[0] !== "verify") ||
+                (maybePath === "tools" && remainingArgs.includes("--server"))));
     if (args.includes("--sandbox") && !runtimeSandboxSupported) {
-        io.writeStderr("--sandbox is supported only by single-package check, release check, runtime-plan, runtime-policy, and release-evidence.");
+        io.writeStderr("--sandbox is supported only by single-package check, release check, runtime-plan, runtime-policy, release-evidence, and doctor tools --server.");
         return 2;
     }
     if (command === "--version" || command === "-v" || command === "version") {
@@ -1215,13 +1332,13 @@ export async function runCli(args, io = defaultIo, options = {}) {
             }
             let beforePath;
             let afterPath;
-            let json = false;
+            let format;
             let failOn;
             let invalid = false;
             for (let index = 0; index < remainingArgs.length; index += 1) {
                 const flag = remainingArgs[index];
-                if (flag === "--json" && !json) {
-                    json = true;
+                if ((flag === "--json" || flag === "--markdown") && format === undefined) {
+                    format = flag === "--json" ? "json" : "markdown";
                 }
                 else if (flag === "--fail-on" && failOn === undefined) {
                     const value = remainingArgs[index + 1];
@@ -1254,7 +1371,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 return 2;
             }
             const report = await (options.compareMcpToolFilesImpl ?? compareMcpToolFiles)(beforePath, afterPath);
-            io.writeStdout(json ? JSON.stringify(report, null, 2) : renderMcpToolDiffReport(report));
+            io.writeStdout(format === "json" ? JSON.stringify(report, null, 2)
+                : format === "markdown" ? renderMcpToolDiffMarkdown(report)
+                    : renderMcpToolDiffReport(report));
             if (report.status !== "pass" && report.status !== "warn")
                 return 2;
             if (failOn === "breaking") {
@@ -1281,7 +1400,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         if (maybePath === "tools") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
-                io.writeStdout(`${toolsUsage}\nHTTP tool catalog structure only; tools are not executed.\n--save-response writes a complete enumeration as one tools/list response for doctor tools-file and tools-diff; nothing is written when enumeration is incomplete.`);
+                io.writeStdout(`${toolsUsage}\nTool catalog structure only; tools are not executed.\n--server starts the named stdio server from the package MCP configuration after explicit --runtime consent and stops it after reading the tool list.\n--save-response writes a complete enumeration as one tools/list response for doctor tools-file and tools-diff; nothing is written when enumeration is incomplete.\n${bearerTokenHelp}`);
                 return 0;
             }
             const [url, ...flags] = remainingArgs;
@@ -1289,19 +1408,26 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr(toolsUsage);
                 return 2;
             }
+            if (flags.includes("--server")) {
+                return runStdioToolCatalogCommand(url, flags, io, options);
+            }
             const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
             const switches = [];
             let savePath;
+            let tokenEnv;
             let invalid = false;
             for (let index = 0; index < flags.length; index += 1) {
                 const flag = flags[index];
-                if (flag === "--save-response" && savePath === undefined) {
+                if ((flag === "--save-response" && savePath === undefined) || (flag === "--bearer-token-env" && tokenEnv === undefined)) {
                     const value = flags[index + 1];
                     if (!value || value.startsWith("-")) {
                         invalid = true;
                         break;
                     }
-                    savePath = value;
+                    if (flag === "--save-response")
+                        savePath = value;
+                    else
+                        tokenEnv = value;
                     index += 1;
                 }
                 else if (allowedFlags.has(flag) && !switches.includes(flag)) {
@@ -1324,38 +1450,24 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr("doctor tools --save-response requires a local file path.");
                 return 2;
             }
-            const catalogOptions = { allowNetwork: true, allowLocalNetwork: switches.includes("--allow-local-network") };
+            const bearer = resolveBearerToken(tokenEnv, terminalContext.env);
+            if ("error" in bearer) {
+                io.writeStderr(bearer.error);
+                return 2;
+            }
+            const catalogOptions = {
+                allowNetwork: true,
+                allowLocalNetwork: switches.includes("--allow-local-network"),
+                ...(bearer.token === undefined ? {} : { bearerToken: bearer.token })
+            };
             const snapshot = savePath === undefined
                 ? { report: await (options.inspectMcpToolCatalogImpl ?? inspectMcpToolCatalog)(url, catalogOptions), tools: null, cache: null }
                 : await (options.captureMcpToolCatalogImpl ?? captureMcpToolCatalog)(url, catalogOptions);
-            const report = snapshot.report;
-            io.writeStdout(switches.includes("--json")
-                ? JSON.stringify(report, null, 2)
-                : renderMcpToolCatalogReport(report));
-            const exitCode = report.status === "pass" ? 0
-                : report.status === "incomplete" || report.status === "blocked" ? 2 : 1;
-            if (savePath === undefined)
-                return exitCode;
-            if (snapshot.tools === null || snapshot.cache === null) {
-                io.writeStderr("Tool catalog response was not saved because enumeration did not complete.");
-                return 2;
-            }
-            const saved = await saveMcpToolsListResponse(savePath, snapshot.tools, snapshot.cache);
-            if (saved.kind !== "saved") {
-                io.writeStderr({
-                    "path-blocked": "Tool catalog response was not saved because the path is not a local file path.",
-                    "not-regular": "Tool catalog response was not saved because the existing target is not a regular file.",
-                    "too-large": "Tool catalog response was not saved because it exceeds the one MiB tools-file limit.",
-                    "write-failed": "Tool catalog response could not be written."
-                }[saved.kind]);
-                return 2;
-            }
-            io.writeStderr(`Saved a complete tools/list response with ${saved.tools} tools (${saved.bytes} bytes).`);
-            return exitCode;
+            return finishToolCatalogCommand(io, snapshot, switches.includes("--json"), savePath);
         }
         if (maybePath === "discover") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
-                io.writeStdout(`${discoveryUsage}\nHTTP discovery only; runtime behavior is not tested.`);
+                io.writeStdout(`${discoveryUsage}\nHTTP discovery only; runtime behavior is not tested.\n${bearerTokenHelp}`);
                 return 0;
             }
             const [url, ...flags] = remainingArgs;
@@ -1364,19 +1476,47 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 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) {
+            const switches = [];
+            let tokenEnv;
+            let invalid = false;
+            for (let index = 0; index < flags.length; index += 1) {
+                const flag = flags[index];
+                if (flag === "--bearer-token-env" && tokenEnv === undefined) {
+                    const value = flags[index + 1];
+                    if (!value || value.startsWith("-")) {
+                        invalid = true;
+                        break;
+                    }
+                    tokenEnv = value;
+                    index += 1;
+                }
+                else if (allowedFlags.has(flag) && !switches.includes(flag)) {
+                    switches.push(flag);
+                }
+                else {
+                    invalid = true;
+                    break;
+                }
+            }
+            if (invalid) {
                 io.writeStderr(`Invalid or duplicate discovery arguments. ${discoveryUsage}`);
                 return 2;
             }
-            if (!flags.includes("--allow-network")) {
+            if (!switches.includes("--allow-network")) {
                 io.writeStderr("doctor discover requires explicit --allow-network consent.");
                 return 2;
             }
+            const bearer = resolveBearerToken(tokenEnv, terminalContext.env);
+            if ("error" in bearer) {
+                io.writeStderr(bearer.error);
+                return 2;
+            }
             const report = await (options.discoverMcpServerImpl ?? discoverMcpServer)(url, {
                 allowNetwork: true,
-                allowLocalNetwork: flags.includes("--allow-local-network")
+                allowLocalNetwork: switches.includes("--allow-local-network"),
+                ...(bearer.token === undefined ? {} : { bearerToken: bearer.token })
             });
-            io.writeStdout(flags.includes("--json")
+            io.writeStdout(switches.includes("--json")
                 ? JSON.stringify(report, null, 2)
                 : renderMcpDiscoveryReport(report));
             return report.status === "discovered" ? 0 : report.status === "unsupported" ? 1 : 2;

package/package.json

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