codex-plugin-doctor 1.33.0 → 1.34.1

package/README.md

@@ -234,10 +234,12 @@ codex-plugin-doctor audit --installed
 codex-plugin-doctor audit --installed --security --compat
 codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json
 codex-plugin-doctor audit --installed --security --compat --cache
-codex-plugin-doctor audit --installed --changed --cache
-codex-plugin-doctor audit deps .
-codex-plugin-doctor audit deps . --json --output dependency-audit.json
-codex-plugin-doctor watch .
+codex-plugin-doctor audit --installed --changed --cache
+codex-plugin-doctor audit deps .
+codex-plugin-doctor audit deps . --json --output dependency-audit.json
+codex-plugin-doctor audit deps . --recommend
+codex-plugin-doctor audit deps . --recommend --json --output dependency-remediation.json
+codex-plugin-doctor watch .
 codex-plugin-doctor watch . --json --output watch-latest.json --debounce-ms 500
 codex-plugin-doctor init-git-hooks .
 codex-plugin-doctor init-git-hooks . --json
@@ -302,7 +304,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `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.
 
-`audit deps <path>` runs `npm audit --json` for the target package and normalizes dependency vulnerability results into a stable `schemaVersion: "1.0.0"` report. Use `--json --output dependency-audit.json` when CI needs machine-readable status, vulnerability counts, and the raw npm audit payload.
+`audit deps <path>` runs `npm audit --json` for the target package and normalizes dependency vulnerability results into a stable `schemaVersion: "1.0.0"` report. Use `--json --output dependency-audit.json` when CI needs machine-readable status, vulnerability counts, and the raw npm audit payload. Add `--recommend` to include prioritized remediation actions for direct upgrades, direct no-fix packages, transitive parent updates, and manual transitive review.
 
 `watch <path>` continuously validates a plugin package after file changes. Use `--debounce-ms <ms>` to tune noisy repositories, `--runtime` when runtime probes are required, and `--json --output watch-latest.json` when another process should consume the latest validation snapshot.
 
@@ -400,9 +402,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.33.0
-        with:
-          version: "1.33.0"
+      - uses: Esquetta/CodexPluginDoctor@v1.34.1
+        with:
+          version: "1.34.1"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/compatibility/compatibility-matrix.js

@@ -30,6 +30,11 @@ function statusFromCheckResult(result) {
     }
     return "pass";
 }
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
+}
 export async function readMcpConfigPath(targetPath) {
     const rootPath = path.resolve(targetPath);
     const directMcpPath = path.join(rootPath, ".mcp.json");
@@ -40,21 +45,38 @@ export async function readMcpConfigPath(targetPath) {
     if (!(await fileExists(manifestPath))) {
         return null;
     }
+    let manifest;
     try {
-        const manifest = await readJsonFile(manifestPath);
-        return typeof manifest.mcpServers === "string"
-            ? path.resolve(rootPath, manifest.mcpServers)
-            : null;
+        manifest = await readJsonFile(manifestPath);
     }
     catch {
         return null;
     }
+    if (typeof manifest.mcpServers !== "string") {
+        return null;
+    }
+    const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
+    if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+        throw new Error("Manifest MCP config path resolves outside the package root.");
+    }
+    return mcpConfigPath;
 }
 async function hasCodexManifest(targetPath) {
     return fileExists(path.join(path.resolve(targetPath), ".codex-plugin", "plugin.json"));
 }
 async function checkGenericMcp(targetPath) {
-    const mcpConfigPath = await readMcpConfigPath(targetPath);
+    let mcpConfigPath;
+    try {
+        mcpConfigPath = await readMcpConfigPath(targetPath);
+    }
+    catch (error) {
+        return {
+            client: "Generic MCP",
+            status: "fail",
+            summary: error instanceof Error ? error.message : "MCP config path is unsafe.",
+            details: ["Keep `.mcp.json` or manifest `mcpServers` references inside the package root."]
+        };
+    }
     if (!mcpConfigPath || !(await fileExists(mcpConfigPath))) {
         return {
             client: "Generic MCP",

package/dist/core/dep-audit.d.ts

@@ -12,7 +12,19 @@ export interface DepAuditReport {
     totalVulnerabilities: number;
     auditJson: unknown;
 }
+export interface DepAuditRecommendation {
+    packageName: string;
+    priority: "critical" | "high" | "moderate" | "low";
+    action: "upgrade_direct" | "replace_direct" | "update_parent" | "review_transitive";
+    summary: string;
+    breakingChangeRisk: "low" | "medium" | "high" | "unknown";
+}
+export declare function buildDepAuditRecommendations(vulnerabilities: DepAuditVulnerability[]): DepAuditRecommendation[];
 export declare function buildDepAudit(targetPath: string): Promise<DepAuditReport>;
-export declare function renderDepAudit(report: DepAuditReport): string;
-export declare function renderDepAuditJson(report: DepAuditReport): string;
+export declare function renderDepAudit(report: DepAuditReport, options?: {
+    recommendations?: boolean;
+}): string;
+export declare function renderDepAuditJson(report: DepAuditReport, options?: {
+    recommendations?: boolean;
+}): string;
 export declare function renderDepAuditSarif(report: DepAuditReport): string;

package/dist/core/dep-audit.js

@@ -82,6 +82,66 @@ function computeStatus(vulnerabilities) {
     }
     return "warn";
 }
+function severityRank(severity) {
+    return severity === "critical" ? 0 :
+        severity === "high" ? 1 :
+            severity === "moderate" ? 2 : 3;
+}
+function remediationRank(vulnerability) {
+    if (vulnerability.isDirect && vulnerability.fixAvailable) {
+        return 0;
+    }
+    if (vulnerability.isDirect) {
+        return 1;
+    }
+    return vulnerability.fixAvailable ? 2 : 3;
+}
+export function buildDepAuditRecommendations(vulnerabilities) {
+    return [...vulnerabilities]
+        .sort((left, right) => {
+        const remediationDelta = remediationRank(left) - remediationRank(right);
+        if (remediationDelta !== 0) {
+            return remediationDelta;
+        }
+        return severityRank(left.severity) - severityRank(right.severity);
+    })
+        .map((vuln) => {
+        if (vuln.isDirect && vuln.fixAvailable) {
+            return {
+                packageName: vuln.name,
+                priority: vuln.severity,
+                action: "upgrade_direct",
+                summary: `Upgrade direct dependency \`${vuln.name}\` with \`npm update ${vuln.name}\` or an explicit package upgrade.`,
+                breakingChangeRisk: vuln.severity === "critical" ? "high" : "medium"
+            };
+        }
+        if (vuln.isDirect) {
+            return {
+                packageName: vuln.name,
+                priority: vuln.severity,
+                action: "replace_direct",
+                summary: `Replace or pin direct dependency \`${vuln.name}\`; npm did not report an automatic fix.`,
+                breakingChangeRisk: "high"
+            };
+        }
+        if (vuln.fixAvailable) {
+            return {
+                packageName: vuln.name,
+                priority: vuln.severity,
+                action: "update_parent",
+                summary: `Update the parent dependency for transitive package \`${vuln.name}\`.`,
+                breakingChangeRisk: "medium"
+            };
+        }
+        return {
+            packageName: vuln.name,
+            priority: vuln.severity,
+            action: "review_transitive",
+            summary: `Review transitive package \`${vuln.name}\`; npm did not report an automatic fix.`,
+            breakingChangeRisk: "unknown"
+        };
+    });
+}
 export async function buildDepAudit(targetPath) {
     const resolvedPath = path.resolve(targetPath);
     const packageJsonPath = resolvePackageJson(resolvedPath);
@@ -140,7 +200,7 @@ export async function buildDepAudit(targetPath) {
         auditJson
     };
 }
-export function renderDepAudit(report) {
+export function renderDepAudit(report, options = {}) {
     const lines = [
         "Dependency Vulnerability Audit",
         "=============================",
@@ -159,15 +219,28 @@ export function renderDepAudit(report) {
                 vuln.severity === "moderate" ? "MODERATE" : "LOW";
         lines.push(`${tag.padEnd(10)} ${vuln.name}`, `          Direct: ${vuln.isDirect ? "yes" : "no"}`, `          Fix available: ${vuln.fixAvailable ? "yes" : "no"}`, vuln.via.length > 0 ? `          Via: ${vuln.via.join(", ")}` : "", "");
     }
+    if (options.recommendations) {
+        const recommendations = buildDepAuditRecommendations(report.vulnerabilities);
+        lines.push("Next actions", "------------");
+        if (recommendations.length === 0) {
+            lines.push("No remediation actions needed.");
+        }
+        for (const [index, recommendation] of recommendations.entries()) {
+            lines.push(`${index + 1}. ${recommendation.summary}`);
+        }
+    }
     return lines.join("\n");
 }
-export function renderDepAuditJson(report) {
+export function renderDepAuditJson(report, options = {}) {
     return JSON.stringify({
         schemaVersion: "1.0.0",
         targetPath: report.targetPath,
         status: report.status,
         totalVulnerabilities: report.totalVulnerabilities,
         vulnerabilities: report.vulnerabilities,
+        ...(options.recommendations
+            ? { recommendations: buildDepAuditRecommendations(report.vulnerabilities) }
+            : {}),
         audit: report.auditJson
     }, null, 2);
 }

package/dist/core/runtime-probe.js

@@ -193,12 +193,20 @@ async function fileExists(targetPath) {
         return false;
     }
 }
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
+}
 async function loadMcpServers(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
     if (!manifest.mcpServers) {
         return null;
     }
     const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
+    if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+        return null;
+    }
     const exists = await fileExists(mcpConfigPath);
     if (!exists) {
         return null;

package/dist/index.d.ts

@@ -25,6 +25,6 @@ export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson, ty
 export { applyPolicyToDepAudit, applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames, type PolicyPackName } from "./policy/policy-packs.js";
 export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson, type GenericMcpDoctorReport } from "./mcp/generic-mcp-doctor.js";
 export { watchPlugin, type WatchPluginOptions, type WatchPluginResult } from "./core/watch-plugin.js";
-export { buildDepAudit, renderDepAudit, renderDepAuditJson, renderDepAuditSarif, type DepAuditReport, type DepAuditVulnerability } from "./core/dep-audit.js";
+export { buildDepAudit, buildDepAuditRecommendations, renderDepAudit, renderDepAuditJson, renderDepAuditSarif, type DepAuditRecommendation, type DepAuditReport, type DepAuditVulnerability } from "./core/dep-audit.js";
 export { initGitHooks, removeGitHooks, type InitGitHooksResult, type RemoveGitHooksResult } from "./core/init-git-hooks.js";
 export declare function runCheck(targetPath: string, options?: CheckOptions): Promise<CheckResult>;

package/dist/index.js

@@ -25,7 +25,7 @@ export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } f
 export { applyPolicyToDepAudit, applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
 export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";
 export { watchPlugin } from "./core/watch-plugin.js";
-export { buildDepAudit, renderDepAudit, renderDepAuditJson, renderDepAuditSarif } from "./core/dep-audit.js";
+export { buildDepAudit, buildDepAuditRecommendations, renderDepAudit, renderDepAuditJson, renderDepAuditSarif } from "./core/dep-audit.js";
 export { initGitHooks, removeGitHooks } from "./core/init-git-hooks.js";
 export async function runCheck(targetPath, options = {}) {
     return validatePlugin(targetPath, options);

package/dist/run-cli.js

@@ -78,7 +78,7 @@ const defaultIo = {
     }
 };
 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] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\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] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--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|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--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 [--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 [--upload]|mcp <path>|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 self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\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> [--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|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--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 [--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 [--upload]|mcp <path>|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 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("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]");
 }
 const suppressUsageText = [
@@ -1964,6 +1964,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 : remainingArgs.slice(1);
             const jsonOutput = depsFlags.includes("--json");
             const sarifOutput = depsFlags.includes("--sarif");
+            const recommendationsOutput = depsFlags.includes("--recommend");
             const outputIndex = depsFlags.indexOf("--output");
             const outputPath = outputIndex === -1 ? null : depsFlags[outputIndex + 1];
             const policyIndex = depsFlags.indexOf("--policy");
@@ -1992,8 +1993,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const renderedReport = sarifOutput
                 ? renderDepAuditSarif(report)
                 : jsonOutput
-                    ? renderDepAuditJson(report)
-                    : renderDepAudit(report);
+                    ? renderDepAuditJson(report, { recommendations: recommendationsOutput })
+                    : renderDepAudit(report, { recommendations: recommendationsOutput });
             if (outputPath) {
                 await writeFile(outputPath, renderedReport, "utf8");
             }

package/package.json

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