codex-plugin-doctor 0.14.0 → 0.16.0

package/README.md

@@ -176,6 +176,12 @@ Run these from a Codex plugin package root:
 codex-plugin-doctor --version
 codex-plugin-doctor self-test
 codex-plugin-doctor doctor
+codex-plugin-doctor doctor npm codex-plugin-doctor
+codex-plugin-doctor doctor npm codex-plugin-doctor --json --output npm-preinstall.json
+codex-plugin-doctor doctor inspector .
+codex-plugin-doctor doctor inspector . --server context7 --json --output inspector-command.json
+codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin
+codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin --json --output risk-diff.json
 codex-plugin-doctor doctor recommend .
 codex-plugin-doctor doctor recommend . --json --output recommendations.json
 codex-plugin-doctor doctor trust .
@@ -250,7 +256,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 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. `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 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. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `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. `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.
 

package/dist/core/inspector-bridge.d.ts

@@ -0,0 +1,23 @@
+export interface DoctorInspectorReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    kind: "doctor.inspector";
+    targetPath: string;
+    status: "pass" | "fail";
+    exitCode: 0 | 1;
+    mcpConfigPath: string | null;
+    serverName: string | null;
+    command: {
+        executable: string;
+        args: string[];
+    } | null;
+    message: string;
+}
+export interface BuildDoctorInspectorReportOptions {
+    serverName?: string | null;
+}
+export declare function buildDoctorInspectorReport(targetPath: string, options?: BuildDoctorInspectorReportOptions): Promise<DoctorInspectorReport>;
+export declare function renderDoctorInspectorReportJson(report: DoctorInspectorReport): string;
+export declare function renderDoctorInspectorReport(report: DoctorInspectorReport, options?: {
+    outputPath?: string | null;
+}): string;

package/dist/core/inspector-bridge.js

@@ -0,0 +1,100 @@
+import path from "node:path";
+import { readJsonFile } from "./read-json-file.js";
+import { discoverPackage } from "./discover-package.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
+}
+function buildFailure(targetPath, message, mcpConfigPath = null) {
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        kind: "doctor.inspector",
+        targetPath: path.resolve(targetPath),
+        status: "fail",
+        exitCode: 1,
+        mcpConfigPath,
+        serverName: null,
+        command: null,
+        message
+    };
+}
+export async function buildDoctorInspectorReport(targetPath, options = {}) {
+    const discoveredPackage = await discoverPackage(targetPath);
+    if (!discoveredPackage?.manifest.mcpServers) {
+        return buildFailure(targetPath, "The target package does not declare an MCP server config in `.codex-plugin/plugin.json`.");
+    }
+    const mcpConfigPath = path.resolve(discoveredPackage.rootPath, discoveredPackage.manifest.mcpServers);
+    if (!isPathWithinRoot(discoveredPackage.rootPath, mcpConfigPath)) {
+        return buildFailure(discoveredPackage.rootPath, "The target package points the MCP server config outside the package root.", mcpConfigPath);
+    }
+    let parsedConfig;
+    try {
+        parsedConfig = await readJsonFile(mcpConfigPath);
+    }
+    catch {
+        return buildFailure(discoveredPackage.rootPath, "The MCP server config could not be parsed as JSON.", mcpConfigPath);
+    }
+    if (!isPlainObject(parsedConfig) || !isPlainObject(parsedConfig.mcpServers)) {
+        return buildFailure(discoveredPackage.rootPath, "The MCP server config does not contain a valid `mcpServers` object.", mcpConfigPath);
+    }
+    const serverNames = Object.keys(parsedConfig.mcpServers).sort();
+    const selectedServerName = options.serverName ?? serverNames[0] ?? null;
+    if (!selectedServerName || !serverNames.includes(selectedServerName)) {
+        return buildFailure(discoveredPackage.rootPath, options.serverName
+            ? `The MCP server config does not contain server \`${options.serverName}\`.`
+            : "The MCP server config does not contain any server entries.", mcpConfigPath);
+    }
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        kind: "doctor.inspector",
+        targetPath: discoveredPackage.rootPath,
+        status: "pass",
+        exitCode: 0,
+        mcpConfigPath,
+        serverName: selectedServerName,
+        command: {
+            executable: "npx",
+            args: [
+                "-y",
+                "@modelcontextprotocol/inspector",
+                "--config",
+                mcpConfigPath,
+                "--server",
+                selectedServerName
+            ]
+        },
+        message: "Run this command to open the MCP Inspector for the selected packaged server."
+    };
+}
+export function renderDoctorInspectorReportJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorInspectorReport(report, options = {}) {
+    const lines = [
+        "Doctor MCP Inspector",
+        "====================",
+        `Target: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Message: ${report.message}`
+    ];
+    if (report.mcpConfigPath) {
+        lines.push(`Config: ${report.mcpConfigPath}`);
+    }
+    if (report.serverName) {
+        lines.push(`Server: ${report.serverName}`);
+    }
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    if (report.command) {
+        lines.push("", "Command", "-------");
+        lines.push([report.command.executable, ...report.command.args].join(" "));
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,33 @@
+import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
+import type { JsonReport } from "../domain/types.js";
+import type { SecurityAudit } from "../security/security-audit.js";
+import type { TrustScoreReport } from "../security/trust-score.js";
+import type { DoctorRecommendationsReport } from "./doctor-recommendations.js";
+export interface DoctorNpmPackageReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    kind: "doctor.npm";
+    packageSpec: string;
+    package: {
+        name: string | null;
+        version: string | null;
+        fileCount: number | null;
+    };
+    summary: {
+        status: "pass" | "warn" | "fail";
+        exitCode: 0 | 1;
+        safeToInstall: boolean;
+    };
+    validation: JsonReport;
+    security: SecurityAudit;
+    trust: TrustScoreReport;
+    recommendations: DoctorRecommendationsReport;
+}
+export interface BuildDoctorNpmPackageReportOptions {
+    environment?: CompatibilityEnvironment;
+}
+export declare function buildDoctorNpmPackageReport(packageSpec: string, options?: BuildDoctorNpmPackageReportOptions): Promise<DoctorNpmPackageReport>;
+export declare function renderDoctorNpmPackageReportJson(report: DoctorNpmPackageReport): string;
+export declare function renderDoctorNpmPackageReport(report: DoctorNpmPackageReport, options?: {
+    outputPath?: string | null;
+}): string;

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

@@ -0,0 +1,173 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+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 isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
+}
+function readTarString(buffer, start, length) {
+    const slice = buffer.subarray(start, start + length);
+    const end = slice.indexOf(0);
+    const finalSlice = end === -1 ? slice : slice.subarray(0, end);
+    return finalSlice.toString("utf8").trim();
+}
+function readTarSize(buffer) {
+    const rawSize = readTarString(buffer, 124, 12).replace(/\0/g, "").trim();
+    const parsedSize = Number.parseInt(rawSize, 8);
+    return Number.isFinite(parsedSize) ? parsedSize : 0;
+}
+function isEmptyHeader(header) {
+    return header.every((byte) => byte === 0);
+}
+async function extractTarGz(tarballPath, destinationPath) {
+    const tarBuffer = await gunzipAsync(await readFile(tarballPath));
+    let offset = 0;
+    await mkdir(destinationPath, { recursive: true });
+    while (offset + 512 <= tarBuffer.length) {
+        const header = tarBuffer.subarray(offset, offset + 512);
+        if (isEmptyHeader(header)) {
+            break;
+        }
+        const name = readTarString(header, 0, 100);
+        const prefix = readTarString(header, 345, 155);
+        const entryName = prefix ? `${prefix}/${name}` : name;
+        const size = readTarSize(header);
+        const typeFlag = readTarString(header, 156, 1);
+        const fileStart = offset + 512;
+        const fileEnd = fileStart + size;
+        const targetPath = path.resolve(destinationPath, entryName);
+        if (!isPathWithinRoot(destinationPath, targetPath)) {
+            throw new Error(`Refusing to extract tar entry outside destination: ${entryName}`);
+        }
+        if (typeFlag === "5") {
+            await mkdir(targetPath, { recursive: true });
+        }
+        else if (typeFlag === "" || typeFlag === "0") {
+            await mkdir(path.dirname(targetPath), { recursive: true });
+            await writeFile(targetPath, tarBuffer.subarray(fileStart, fileEnd));
+        }
+        offset = fileStart + Math.ceil(size / 512) * 512;
+    }
+}
+async function directoryExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function resolvePackageSpecForPack(packageSpec) {
+    const candidatePath = path.resolve(packageSpec);
+    try {
+        await stat(candidatePath);
+        return candidatePath;
+    }
+    catch {
+        return packageSpec;
+    }
+}
+async function packNpmPackage(packageSpec, destinationPath) {
+    const resolvedPackageSpec = await resolvePackageSpecForPack(packageSpec);
+    const { stdout } = await execFileAsync(npmCommand(), [
+        "pack",
+        resolvedPackageSpec,
+        "--json",
+        "--ignore-scripts",
+        "--pack-destination",
+        destinationPath
+    ], {
+        cwd: destinationPath,
+        maxBuffer: 10 * 1024 * 1024,
+        shell: process.platform === "win32"
+    });
+    const packEntries = JSON.parse(stdout);
+    const metadata = packEntries[0];
+    if (!metadata?.filename) {
+        throw new Error(`npm pack did not return a tarball for ${packageSpec}`);
+    }
+    return {
+        tarballPath: path.isAbsolute(metadata.filename)
+            ? metadata.filename
+            : path.join(destinationPath, metadata.filename),
+        metadata
+    };
+}
+export async function buildDoctorNpmPackageReport(packageSpec, options = {}) {
+    const workspacePath = await mkdtemp(path.join(os.tmpdir(), "codex-plugin-doctor-npm-"));
+    try {
+        const { tarballPath, metadata } = await packNpmPackage(packageSpec, workspacePath);
+        const extractPath = path.join(workspacePath, "extract");
+        await extractTarGz(tarballPath, extractPath);
+        const packageRoot = await directoryExists(path.join(extractPath, "package"))
+            ? path.join(extractPath, "package")
+            : extractPath;
+        const analysis = await buildPackageAnalysis(packageRoot, {
+            environment: options.environment
+        });
+        const recommendations = buildDoctorRecommendationsFromAnalysis(analysis);
+        return {
+            schemaVersion: "1.0.0",
+            generatedAt: analysis.generatedAt,
+            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
+            },
+            summary: {
+                status: recommendations.status,
+                exitCode: recommendations.exitCode,
+                safeToInstall: recommendations.status === "pass"
+            },
+            validation: analysis.validationJson,
+            security: analysis.security,
+            trust: analysis.trust,
+            recommendations
+        };
+    }
+    finally {
+        await rm(workspacePath, { recursive: true, force: true });
+    }
+}
+export function renderDoctorNpmPackageReportJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorNpmPackageReport(report, options = {}) {
+    const packageLabel = report.package.name
+        ? `${report.package.name}${report.package.version ? `@${report.package.version}` : ""}`
+        : report.packageSpec;
+    const lines = [
+        "Doctor npm Preinstall Scan",
+        "==========================",
+        `Package: ${packageLabel}`,
+        `Spec: ${report.packageSpec}`,
+        `Status: ${report.summary.status.toUpperCase()}`,
+        `Safe to install: ${report.summary.safeToInstall ? "yes" : "no"}`,
+        `Security: ${report.security.status.toUpperCase()} (${report.security.score}/100)`,
+        `Trust: ${report.trust.status.toUpperCase()} (${report.trust.score}/100)`,
+        `Actions: ${report.recommendations.actions.length}`
+    ];
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    if (report.recommendations.actions.length > 0) {
+        lines.push("", "Top Actions", "-----------");
+        for (const action of report.recommendations.actions.slice(0, 5)) {
+            lines.push(`[${action.priority.toUpperCase()}] ${action.title}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/core/risk-diff.d.ts

@@ -0,0 +1,33 @@
+import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
+import type { Finding } from "../domain/types.js";
+export type RiskFindingCategory = "validation" | "security";
+export interface RiskDiffFinding extends Finding {
+    category: RiskFindingCategory;
+}
+export interface DoctorRiskDiffReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    kind: "doctor.risk.diff";
+    beforePath: string;
+    afterPath: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    summary: {
+        riskIncreased: boolean;
+        newFindings: number;
+        resolvedFindings: number;
+        trustScoreBefore: number;
+        trustScoreAfter: number;
+        trustScoreDelta: number;
+    };
+    newFindings: RiskDiffFinding[];
+    resolvedFindings: RiskDiffFinding[];
+}
+export interface BuildDoctorRiskDiffReportOptions {
+    environment?: CompatibilityEnvironment;
+}
+export declare function buildDoctorRiskDiffReport(beforePath: string, afterPath: string, options?: BuildDoctorRiskDiffReportOptions): Promise<DoctorRiskDiffReport>;
+export declare function renderDoctorRiskDiffReportJson(report: DoctorRiskDiffReport): string;
+export declare function renderDoctorRiskDiffReport(report: DoctorRiskDiffReport, options?: {
+    outputPath?: string | null;
+}): string;

package/dist/core/risk-diff.js

@@ -0,0 +1,102 @@
+import { buildPackageAnalysis } from "./package-analysis.js";
+function findingKey(finding) {
+    return `${finding.category}\n${finding.id}\n${finding.message}`;
+}
+function collectComparableFindings(analysis) {
+    const findings = [
+        ...analysis.validation.findings.map((finding) => ({
+            ...finding,
+            category: "validation"
+        })),
+        ...analysis.security.findings.map((finding) => ({
+            ...finding,
+            category: "security"
+        }))
+    ];
+    const seen = new Set();
+    return findings.filter((finding) => {
+        const key = findingKey(finding);
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function compareFindings(beforeFindings, afterFindings) {
+    const beforeKeys = new Set(beforeFindings.map(findingKey));
+    const afterKeys = new Set(afterFindings.map(findingKey));
+    return {
+        newFindings: afterFindings.filter((finding) => !beforeKeys.has(findingKey(finding))),
+        resolvedFindings: beforeFindings.filter((finding) => !afterKeys.has(findingKey(finding)))
+    };
+}
+export async function buildDoctorRiskDiffReport(beforePath, afterPath, options = {}) {
+    const [beforeAnalysis, afterAnalysis] = await Promise.all([
+        buildPackageAnalysis(beforePath, { environment: options.environment }),
+        buildPackageAnalysis(afterPath, { environment: options.environment })
+    ]);
+    const { newFindings, resolvedFindings } = compareFindings(collectComparableFindings(beforeAnalysis), collectComparableFindings(afterAnalysis));
+    const trustScoreDelta = afterAnalysis.trust.score - beforeAnalysis.trust.score;
+    const hasNewFailure = newFindings.some((finding) => finding.severity === "fail");
+    const hasNewWarning = newFindings.some((finding) => finding.severity === "warn");
+    const riskIncreased = hasNewFailure || trustScoreDelta < 0;
+    const status = riskIncreased
+        ? "fail"
+        : hasNewWarning
+            ? "warn"
+            : "pass";
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        kind: "doctor.risk.diff",
+        beforePath: beforeAnalysis.targetPath,
+        afterPath: afterAnalysis.targetPath,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        summary: {
+            riskIncreased,
+            newFindings: newFindings.length,
+            resolvedFindings: resolvedFindings.length,
+            trustScoreBefore: beforeAnalysis.trust.score,
+            trustScoreAfter: afterAnalysis.trust.score,
+            trustScoreDelta
+        },
+        newFindings,
+        resolvedFindings
+    };
+}
+export function renderDoctorRiskDiffReportJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorRiskDiffReport(report, options = {}) {
+    const lines = [
+        "Doctor Risk Diff",
+        "================",
+        `Status: ${report.status.toUpperCase()}`,
+        `Before: ${report.beforePath}`,
+        `After: ${report.afterPath}`,
+        `Risk increased: ${report.summary.riskIncreased ? "yes" : "no"}`,
+        `Trust score delta: ${report.summary.trustScoreDelta}`,
+        `New findings: ${report.summary.newFindings}`,
+        `Resolved findings: ${report.summary.resolvedFindings}`
+    ];
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    if (report.newFindings.length > 0) {
+        lines.push("", "New Findings", "------------");
+        for (const finding of report.newFindings) {
+            lines.push(`[${finding.severity.toUpperCase()}] ${finding.category}: ${finding.id}`);
+            lines.push(`  Message: ${finding.message}`);
+        }
+    }
+    if (report.resolvedFindings.length > 0) {
+        lines.push("", "Resolved Findings", "-----------------");
+        for (const finding of report.resolvedFindings) {
+            lines.push(`[${finding.severity.toUpperCase()}] ${finding.category}: ${finding.id}`);
+            lines.push(`  Message: ${finding.message}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -6,6 +6,9 @@ export { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRe
 export { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson, type DoctorExportBundle } from "./core/doctor-export-bundle.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis, type PackageAnalysis, type PackageAnalysisOptions, type PackageAnalysisStage, type PackageAnalysisTiming } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.js";
+export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson, type BuildDoctorNpmPackageReportOptions, type DoctorNpmPackageReport } from "./core/npm-package-doctor.js";
+export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson, type BuildDoctorRiskDiffReportOptions, type DoctorRiskDiffReport, type RiskDiffFinding, type RiskFindingCategory } from "./core/risk-diff.js";
+export { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorInspectorReportJson, type BuildDoctorInspectorReportOptions, type DoctorInspectorReport } from "./core/inspector-bridge.js";
 export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson, type EcosystemAuditReport } from "./audit/ecosystem-audit.js";
 export { 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";

package/dist/index.js

@@ -6,6 +6,9 @@ export { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRe
 export { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson } from "./core/doctor-export-bundle.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
+export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
+export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";
+export { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorInspectorReportJson } from "./core/inspector-bridge.js";
 export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } from "./audit/ecosystem-audit.js";
 export { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
 export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";

package/dist/rules/rule-catalog.js

@@ -215,6 +215,15 @@ export const ruleCatalog = [
         fix: "Use HTTPS for remote MCP servers; reserve HTTP for explicit localhost development endpoints.",
         example: '{ "url": "https://example.com/mcp" }'
     },
+    {
+        id: "plugin.security.prompt_injection_text",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "Packaged text contains prompt-injection or secret-exfiltration instructions.",
+        why: "Poisoned tool, prompt, resource, or skill text can instruct an agent to ignore higher-priority instructions or leak secrets when loaded into context.",
+        fix: "Remove hidden override or exfiltration instructions and keep descriptions scoped to legitimate behavior.",
+        example: "Keep SKILL.md, prompt, resource, and tool descriptions direct and user-facing."
+    },
     {
         id: "plugin.runtime.exited_early",
         category: "runtime",

package/dist/run-cli.js

@@ -17,6 +17,9 @@ import { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } f
 import { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRecommendationsJson } from "./core/doctor-recommendations.js";
 import { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson } from "./core/doctor-export-bundle.js";
 import { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
+import { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
+import { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";
+import { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorInspectorReportJson } from "./core/inspector-bridge.js";
 import { applyFixPlan, buildFixPlan, renderApplyFixResult, renderFixPlanJsonReport, renderFixPlan } from "./core/fix-plan.js";
 import { renderClientDoctor, renderEnvironmentDoctor, renderEnvironmentDoctorJson } from "./core/environment-doctor.js";
 import { initCiWorkflow } from "./core/init-ci.js";
@@ -62,7 +65,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] [--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 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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [recommend <path>|trust <path>|perf <path>|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 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] [--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 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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path>|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 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");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -227,6 +230,98 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStdout(renderedReport);
             return report.exitCode;
         }
+        if (maybePath === "npm") {
+            const packageSpec = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : null;
+            if (!packageSpec) {
+                io.writeStderr("Missing package spec. Usage: codex-plugin-doctor doctor npm <package> [--json] [--output <path>]");
+                return 2;
+            }
+            const npmFlags = remainingArgs.slice(1);
+            const jsonOutput = npmFlags.includes("--json");
+            const outputIndex = npmFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : npmFlags[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const report = await buildDoctorNpmPackageReport(packageSpec, {
+                environment: {
+                    env: terminalContext.env,
+                    platform: terminalContext.platform
+                }
+            });
+            const renderedReport = jsonOutput
+                ? renderDoctorNpmPackageReportJson(report)
+                : renderDoctorNpmPackageReport(report, { outputPath });
+            if (outputPath) {
+                await writeFile(outputPath, renderedReport, "utf8");
+            }
+            io.writeStdout(renderedReport);
+            return report.summary.exitCode;
+        }
+        if (maybePath === "diff") {
+            const beforeIndex = remainingArgs.indexOf("--before");
+            const afterIndex = remainingArgs.indexOf("--after");
+            const beforePath = beforeIndex === -1 ? null : remainingArgs[beforeIndex + 1];
+            const afterPath = afterIndex === -1 ? null : remainingArgs[afterIndex + 1];
+            if (!beforePath || beforePath.startsWith("--") || !afterPath || afterPath.startsWith("--")) {
+                io.writeStderr("Usage: codex-plugin-doctor doctor diff --before <path> --after <path> [--json] [--output <path>]");
+                return 2;
+            }
+            const jsonOutput = remainingArgs.includes("--json");
+            const outputIndex = remainingArgs.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : remainingArgs[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const report = await buildDoctorRiskDiffReport(beforePath, afterPath, {
+                environment: {
+                    env: terminalContext.env,
+                    platform: terminalContext.platform
+                }
+            });
+            const renderedReport = jsonOutput
+                ? renderDoctorRiskDiffReportJson(report)
+                : renderDoctorRiskDiffReport(report, { outputPath });
+            if (outputPath) {
+                await writeFile(outputPath, renderedReport, "utf8");
+            }
+            io.writeStdout(renderedReport);
+            return report.exitCode;
+        }
+        if (maybePath === "inspector") {
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : ".";
+            const inspectorFlags = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs.slice(1)
+                : remainingArgs;
+            const jsonOutput = inspectorFlags.includes("--json");
+            const outputIndex = inspectorFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : inspectorFlags[outputIndex + 1];
+            const serverIndex = inspectorFlags.indexOf("--server");
+            const serverName = serverIndex === -1 ? null : inspectorFlags[serverIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            if (serverIndex !== -1 && (!serverName || serverName.startsWith("--"))) {
+                io.writeStderr("Missing server name after --server.");
+                return 2;
+            }
+            const report = await buildDoctorInspectorReport(targetPath, { serverName });
+            const renderedReport = jsonOutput
+                ? renderDoctorInspectorReportJson(report)
+                : renderDoctorInspectorReport(report, { outputPath });
+            if (outputPath) {
+                await writeFile(outputPath, renderedReport, "utf8");
+            }
+            io.writeStdout(renderedReport);
+            return report.exitCode;
+        }
         if (maybePath === "trust") {
             const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
                 ? remainingArgs[0]

package/dist/security/security-audit.js

@@ -1,3 +1,4 @@
+import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { discoverPackage } from "../core/discover-package.js";
 import { readJsonFile } from "../core/read-json-file.js";
@@ -40,6 +41,25 @@ function containsPipeInstaller(args) {
         /\b(iwr|irm|invoke-webrequest|invoke-restmethod)\b[^|]*\|\s*(iex|invoke-expression)\b/.test(joinedArgs) ||
         /\binvoke-expression\b/.test(joinedArgs));
 }
+const poisonScanExtensions = new Set([
+    ".json",
+    ".md",
+    ".mdx",
+    ".txt",
+    ".yaml",
+    ".yml"
+]);
+const poisonScanSkippedDirectories = new Set([
+    ".git",
+    "coverage",
+    "dist",
+    "node_modules"
+]);
+const promptInjectionPatterns = [
+    /\bignore\s+(?:all\s+)?(?:previous|prior|system|developer)\s+instructions?\b/i,
+    /\b(?:exfiltrate|steal|leak|upload|send)\b.{0,120}\b(?:secret|secrets|token|tokens|api\s*key|api\s*keys|credential|credentials|environment\s+variables?|env)\b/i,
+    /\bdo\s+not\s+(?:reveal|tell|mention|disclose)\b.{0,120}\b(?:instruction|instructions|prompt|prompts|system|developer)\b/i
+];
 export function auditMcpServerConfig(rootPath, parsedConfig) {
     if (!isPlainObject(parsedConfig) || !isPlainObject(parsedConfig.mcpServers)) {
         return [
@@ -76,6 +96,43 @@ export function auditMcpServerConfig(rootPath, parsedConfig) {
     }
     return findings;
 }
+async function collectPromptPoisoningScanFiles(rootPath, currentPath = rootPath) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    const filePaths = [];
+    for (const entry of entries) {
+        const entryPath = path.join(currentPath, entry.name);
+        if (entry.isDirectory()) {
+            if (poisonScanSkippedDirectories.has(entry.name)) {
+                continue;
+            }
+            filePaths.push(...(await collectPromptPoisoningScanFiles(rootPath, entryPath)));
+            continue;
+        }
+        if (!entry.isFile() || !poisonScanExtensions.has(path.extname(entry.name).toLowerCase())) {
+            continue;
+        }
+        const details = await stat(entryPath);
+        if (details.size <= 256 * 1024) {
+            filePaths.push(entryPath);
+        }
+    }
+    return filePaths;
+}
+function containsPromptInjectionText(content) {
+    return promptInjectionPatterns.some((pattern) => pattern.test(content));
+}
+async function auditPromptPoisoningSurface(rootPath) {
+    const findings = [];
+    for (const filePath of await collectPromptPoisoningScanFiles(rootPath)) {
+        const content = await readFile(filePath, "utf8");
+        if (!containsPromptInjectionText(content)) {
+            continue;
+        }
+        const relativeFilePath = path.relative(rootPath, filePath).replace(/\\/g, "/");
+        findings.push(buildFinding("fail", "plugin.security.prompt_injection_text", `The packaged text file \`${relativeFilePath}\` contains prompt-injection or secret-exfiltration style instructions.`, "Malicious or poisoned tool, prompt, resource, or skill text can instruct an agent to ignore higher-priority instructions or leak secrets when loaded into context.", "Remove hidden override or exfiltration instructions, then keep tool/prompt/resource descriptions scoped to the legitimate user-facing behavior."));
+    }
+    return findings;
+}
 async function auditMcpCommandSurface(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
     if (!manifest.mcpServers) {
@@ -154,7 +211,8 @@ export async function buildSecurityAudit(targetPath) {
     const validationSecurityFindings = validationResult.findings.filter((finding) => finding.id.startsWith("plugin.security."));
     const findings = [
         ...validationSecurityFindings,
-        ...(await auditMcpCommandSurface(discoveredPackage))
+        ...(await auditMcpCommandSurface(discoveredPackage)),
+        ...(await auditPromptPoisoningSurface(discoveredPackage.rootPath))
     ];
     return buildSecurityAuditFromFindings(discoveredPackage.rootPath, findings);
 }

package/package.json

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