codex-plugin-doctor 1.20.0 → 1.22.0

package/README.md

@@ -298,7 +298,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
-`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy <path>` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before <dir> --after <dir>` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. The JSON report includes tarball metadata such as filename, path, integrity, shasum, sizes, file count, and extracted package root so automation can prove which archive was scanned. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy <path>` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before <dir> --after <dir>` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
 
 `audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
 
@@ -370,9 +370,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.20.0
+      - uses: Esquetta/CodexPluginDoctor@v1.22.0
         with:
-          version: "1.20.0"
+          version: "1.22.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/dep-audit.js

@@ -15,7 +15,11 @@ async function fileExists(filePath) {
 }
 async function runNpmAudit(cwd) {
     return new Promise((resolve, reject) => {
-        execFile("npm", ["audit", "--json"], { cwd, shell: process.platform === "win32", timeout: 120_000 }, (error, stdout, stderr) => {
+        const command = process.platform === "win32" ? process.env.ComSpec ?? "cmd.exe" : "npm";
+        const args = process.platform === "win32"
+            ? ["/d", "/s", "/c", "npm", "audit", "--json"]
+            : ["audit", "--json"];
+        execFile(command, args, { cwd, timeout: 120_000 }, (error, stdout, stderr) => {
             const parsed = (() => {
                 try {
                     return JSON.parse(stdout);

package/dist/core/npm-package-doctor.d.ts

@@ -13,6 +13,18 @@ export interface DoctorNpmPackageReport {
         version: string | null;
         fileCount: number | null;
     };
+    tarball: {
+        filename: string;
+        path: string;
+        integrity: string | null;
+        shasum: string | null;
+        size: number | null;
+        unpackedSize: number | null;
+        fileCount: number | null;
+        packageRoot: string;
+        packageName: string | null;
+        packageVersion: string | null;
+    };
     summary: {
         status: "pass" | "warn" | "fail";
         exitCode: 0 | 1;

package/dist/core/npm-package-doctor.js

@@ -7,8 +7,14 @@ import { gunzip } from "node:zlib";
 import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
 const execFileAsync = promisify(execFile);
 const gunzipAsync = promisify(gunzip);
-function npmCommand() {
-    return "npm";
+function npmCommand(args) {
+    if (process.platform === "win32") {
+        return {
+            command: process.env.ComSpec ?? "cmd.exe",
+            args: ["/d", "/s", "/c", "npm", ...args]
+        };
+    }
+    return { command: "npm", args };
 }
 function isPathWithinRoot(rootPath, candidatePath) {
     const relativePath = path.relative(rootPath, candidatePath);
@@ -80,17 +86,17 @@ async function resolvePackageSpecForPack(packageSpec) {
 }
 async function packNpmPackage(packageSpec, destinationPath) {
     const resolvedPackageSpec = await resolvePackageSpecForPack(packageSpec);
-    const { stdout } = await execFileAsync(npmCommand(), [
+    const npmPackCommand = npmCommand([
         "pack",
         resolvedPackageSpec,
         "--json",
         "--ignore-scripts",
         "--pack-destination",
         destinationPath
-    ], {
+    ]);
+    const { stdout } = await execFileAsync(npmPackCommand.command, npmPackCommand.args, {
         cwd: destinationPath,
-        maxBuffer: 10 * 1024 * 1024,
-        shell: process.platform === "win32"
+        maxBuffer: 10 * 1024 * 1024
     });
     const packEntries = JSON.parse(stdout);
     const metadata = packEntries[0];
@@ -113,6 +119,9 @@ export async function buildDoctorNpmPackageReport(packageSpec, options = {}) {
         const packageRoot = await directoryExists(path.join(extractPath, "package"))
             ? path.join(extractPath, "package")
             : extractPath;
+        const packageName = typeof metadata.name === "string" ? metadata.name : null;
+        const packageVersion = typeof metadata.version === "string" ? metadata.version : null;
+        const fileCount = Array.isArray(metadata.files) ? metadata.files.length : null;
         const analysis = await buildPackageAnalysis(packageRoot, {
             environment: options.environment
         });
@@ -123,9 +132,21 @@ export async function buildDoctorNpmPackageReport(packageSpec, options = {}) {
             kind: "doctor.npm",
             packageSpec,
             package: {
-                name: typeof metadata.name === "string" ? metadata.name : null,
-                version: typeof metadata.version === "string" ? metadata.version : null,
-                fileCount: Array.isArray(metadata.files) ? metadata.files.length : null
+                name: packageName,
+                version: packageVersion,
+                fileCount
+            },
+            tarball: {
+                filename: path.basename(tarballPath),
+                path: tarballPath,
+                integrity: typeof metadata.integrity === "string" ? metadata.integrity : null,
+                shasum: typeof metadata.shasum === "string" ? metadata.shasum : null,
+                size: typeof metadata.size === "number" ? metadata.size : null,
+                unpackedSize: typeof metadata.unpackedSize === "number" ? metadata.unpackedSize : null,
+                fileCount,
+                packageRoot,
+                packageName,
+                packageVersion
             },
             summary: {
                 status: recommendations.status,
@@ -154,6 +175,7 @@ export function renderDoctorNpmPackageReport(report, options = {}) {
         "==========================",
         `Package: ${packageLabel}`,
         `Spec: ${report.packageSpec}`,
+        `Tarball: ${report.tarball.filename}`,
         `Status: ${report.summary.status.toUpperCase()}`,
         `Safe to install: ${report.summary.safeToInstall ? "yes" : "no"}`,
         `Security: ${report.security.status.toUpperCase()} (${report.security.score}/100)`,

package/dist/core/output-contract.js

@@ -157,7 +157,7 @@ const publicSchemaDefinitions = [
         id: "doctor.npm.json",
         command: "codex-plugin-doctor doctor npm <package> --json",
         outputKind: "doctor.npm",
-        required: ["schemaVersion", "kind", "generatedAt", "package", "summary", "validation", "security", "trust", "recommendations"]
+        required: ["schemaVersion", "kind", "generatedAt", "package", "tarball", "summary", "validation", "security", "trust", "recommendations"]
     },
     {
         id: "doctor.risk.diff.json",

package/package.json

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