codex-plugin-doctor 0.1.4 → 0.2.0

package/README.md

@@ -82,7 +82,9 @@ If you already have Codex installed locally and do not know plugin paths, discov
 ```bash
 codex-plugin-doctor list --installed
 codex-plugin-doctor check --installed
+codex-plugin-doctor check --installed --all-summary
 codex-plugin-doctor check --installed github
+codex-plugin-doctor explain plugin.manifest.missing
 ```
 
 Run from source:
@@ -154,23 +156,61 @@ Run these from a Codex plugin package root:
 
 ```bash
 codex-plugin-doctor --version
+codex-plugin-doctor init my-plugin
+codex-plugin-doctor compat .
+codex-plugin-doctor compat . --client codex
+codex-plugin-doctor compat . --client generic-mcp
+codex-plugin-doctor compat . --json
+codex-plugin-doctor compat . --json --output compatibility.json
 codex-plugin-doctor check .
 codex-plugin-doctor check . --json
 codex-plugin-doctor check . --json --output report.json
 codex-plugin-doctor check . --markdown --output report.md
+codex-plugin-doctor check . --sarif --output results.sarif
 codex-plugin-doctor check . --ascii
 codex-plugin-doctor check . --no-animations
 codex-plugin-doctor check . --runtime
+codex-plugin-doctor check . --config .codex-doctor.json
 codex-plugin-doctor check . --json --runtime --verbose-runtime
 ```
 
+Optional local policy file:
+
+```json
+{
+  "ignoreRules": ["plugin.heuristic.description.too_long"],
+  "failOnWarnings": true
+}
+```
+
 Run these when you want Codex Plugin Doctor to find plugins from the local Codex installation:
 
 ```bash
 codex-plugin-doctor list --installed
 codex-plugin-doctor check --installed
+codex-plugin-doctor check --installed --all-summary
 codex-plugin-doctor check --installed github
 codex-plugin-doctor check --installed github --runtime --no-animations
+codex-plugin-doctor explain plugin.security.hard_coded_secret
+```
+
+## GitHub Action
+
+```yaml
+name: Validate Codex plugin
+
+on:
+  pull_request:
+
+jobs:
+  doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Esquetta/CodexPluginDoctor@v0.2.0
+        with:
+          path: .
+          runtime: "false"
 ```
 
 To self-test this repository after cloning it:
@@ -196,6 +236,7 @@ The validator is tuned against local fixtures and real marketplace-style plugin
 - [Real-World Validation Workflow](./docs/engineering/real-world-validation-workflow.md)
 - [Validation Sessions](./validation-sessions/README.md)
 - [Examples](./examples/README.md)
+- [Rule Catalog](./docs/rules/catalog.md)
 
 Recent validation waves covered:
 

package/dist/compatibility/compatibility-matrix.d.ts

@@ -0,0 +1,13 @@
+export type CompatibilityStatus = "pass" | "warn" | "fail" | "skipped";
+export interface CompatibilityResult {
+    client: string;
+    status: CompatibilityStatus;
+    summary: string;
+    details: string[];
+}
+export interface CompatibilityMatrix {
+    targetPath: string;
+    results: CompatibilityResult[];
+}
+export declare function buildCompatibilityMatrix(targetPath: string): Promise<CompatibilityMatrix>;
+export declare function matrixExitCode(matrix: CompatibilityMatrix): 0 | 1;

package/dist/compatibility/compatibility-matrix.js

@@ -0,0 +1,129 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { validatePlugin } from "../core/validate-plugin.js";
+async function fileExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function statusFromCheckResult(result) {
+    if (result.status === "fail") {
+        return "fail";
+    }
+    if (result.status === "warn") {
+        return "warn";
+    }
+    return "pass";
+}
+async function readMcpConfigPath(targetPath) {
+    const rootPath = path.resolve(targetPath);
+    const directMcpPath = path.join(rootPath, ".mcp.json");
+    if (await fileExists(directMcpPath)) {
+        return directMcpPath;
+    }
+    const manifestPath = path.join(rootPath, ".codex-plugin", "plugin.json");
+    if (!(await fileExists(manifestPath))) {
+        return null;
+    }
+    try {
+        const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+        return typeof manifest.mcpServers === "string"
+            ? path.resolve(rootPath, manifest.mcpServers)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function hasCodexManifest(targetPath) {
+    return fileExists(path.join(path.resolve(targetPath), ".codex-plugin", "plugin.json"));
+}
+async function checkGenericMcp(targetPath) {
+    const mcpConfigPath = await readMcpConfigPath(targetPath);
+    if (!mcpConfigPath || !(await fileExists(mcpConfigPath))) {
+        return {
+            client: "Generic MCP",
+            status: "skipped",
+            summary: "No MCP config found.",
+            details: ["Expected `.mcp.json` or manifest `mcpServers` reference."]
+        };
+    }
+    try {
+        const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
+        const servers = parsed.mcpServers;
+        if (typeof servers !== "object" ||
+            servers === null ||
+            Array.isArray(servers) ||
+            Object.keys(servers).length === 0) {
+            return {
+                client: "Generic MCP",
+                status: "fail",
+                summary: "MCP config does not contain a non-empty `mcpServers` object.",
+                details: [mcpConfigPath]
+            };
+        }
+        return {
+            client: "Generic MCP",
+            status: "pass",
+            summary: "MCP server config is valid.",
+            details: [mcpConfigPath]
+        };
+    }
+    catch {
+        return {
+            client: "Generic MCP",
+            status: "fail",
+            summary: "MCP config is not valid JSON.",
+            details: [mcpConfigPath]
+        };
+    }
+}
+export async function buildCompatibilityMatrix(targetPath) {
+    const rootPath = path.resolve(targetPath);
+    const genericMcpResult = await checkGenericMcp(rootPath);
+    const codexResult = await validatePlugin(rootPath);
+    const codexStatus = statusFromCheckResult(codexResult);
+    const codexCompatibility = !await hasCodexManifest(rootPath)
+        && genericMcpResult.status === "pass"
+        ? {
+            client: "Codex",
+            status: "skipped",
+            summary: "No Codex plugin manifest found; treating target as a standalone MCP package.",
+            details: ["Add `.codex-plugin/plugin.json` if this package should be installable as a Codex plugin."]
+        }
+        : {
+            client: "Codex",
+            status: codexStatus,
+            summary: codexStatus === "pass"
+                ? "Codex plugin package validation passed."
+                : "Codex plugin package validation produced findings.",
+            details: codexResult.findings.map((finding) => finding.id)
+        };
+    const results = [
+        codexCompatibility,
+        genericMcpResult,
+        {
+            client: "Claude Desktop",
+            status: "skipped",
+            summary: "Client-specific package adapter is not implemented yet.",
+            details: ["Planned adapter after generic MCP compatibility is stable."]
+        },
+        {
+            client: "Cursor",
+            status: "skipped",
+            summary: "Client-specific package adapter is not implemented yet.",
+            details: ["Planned adapter after generic MCP compatibility is stable."]
+        }
+    ];
+    return {
+        targetPath: rootPath,
+        results
+    };
+}
+export function matrixExitCode(matrix) {
+    return matrix.results.some((result) => result.status === "fail") ? 1 : 0;
+}

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

@@ -0,0 +1,7 @@
+import type { CheckResult } from "../domain/types.js";
+export interface DoctorConfig {
+    ignoreRules: string[];
+    failOnWarnings: boolean;
+}
+export declare function loadDoctorConfig(targetPath: string, explicitConfigPath?: string | null): Promise<DoctorConfig>;
+export declare function applyDoctorConfig(result: CheckResult, config: DoctorConfig): CheckResult;

package/dist/core/doctor-config.js

@@ -0,0 +1,45 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+const defaultConfig = {
+    ignoreRules: [],
+    failOnWarnings: false
+};
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+export async function loadDoctorConfig(targetPath, explicitConfigPath) {
+    const configPath = explicitConfigPath
+        ? path.resolve(explicitConfigPath)
+        : path.join(path.resolve(targetPath), ".codex-doctor.json");
+    try {
+        const parsed = JSON.parse(await readFile(configPath, "utf8"));
+        return {
+            ignoreRules: isStringArray(parsed.ignoreRules)
+                ? parsed.ignoreRules
+                : defaultConfig.ignoreRules,
+            failOnWarnings: typeof parsed.failOnWarnings === "boolean"
+                ? parsed.failOnWarnings
+                : defaultConfig.failOnWarnings
+        };
+    }
+    catch {
+        return defaultConfig;
+    }
+}
+export function applyDoctorConfig(result, config) {
+    const findings = result.findings.filter((finding) => !config.ignoreRules.includes(finding.id));
+    const hasFailures = findings.some((finding) => finding.severity === "fail");
+    const hasWarnings = findings.some((finding) => finding.severity === "warn");
+    const warningFailure = config.failOnWarnings && hasWarnings;
+    const status = hasFailures || warningFailure
+        ? "fail"
+        : hasWarnings
+            ? "warn"
+            : "pass";
+    return {
+        ...result,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        findings
+    };
+}

package/dist/core/init-plugin.d.ts

@@ -0,0 +1,6 @@
+export interface InitPluginResult {
+    rootPath: string;
+    manifestPath: string;
+    skillPath: string;
+}
+export declare function initPluginPackage(targetPath: string): Promise<InitPluginResult>;

package/dist/core/init-plugin.js

@@ -0,0 +1,39 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+function toPackageName(inputPath) {
+    return path.basename(path.resolve(inputPath))
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "codex-plugin";
+}
+export async function initPluginPackage(targetPath) {
+    const rootPath = path.resolve(targetPath);
+    const manifestDirectory = path.join(rootPath, ".codex-plugin");
+    const skillsDirectory = path.join(rootPath, "skills", "hello");
+    const manifestPath = path.join(manifestDirectory, "plugin.json");
+    const skillPath = path.join(skillsDirectory, "SKILL.md");
+    await mkdir(manifestDirectory, { recursive: true });
+    await mkdir(skillsDirectory, { recursive: true });
+    await writeFile(manifestPath, `${JSON.stringify({
+        name: toPackageName(rootPath),
+        version: "0.1.0",
+        description: "A Codex plugin package scaffolded by Codex Plugin Doctor.",
+        skills: "skills"
+    }, null, 2)}\n`, "utf8");
+    await writeFile(skillPath, [
+        "---",
+        "name: hello",
+        "description: Use when verifying that this Codex plugin package loads correctly.",
+        "---",
+        "",
+        "# Hello",
+        "",
+        "This starter skill confirms the plugin package structure is valid.",
+        ""
+    ].join("\n"), "utf8");
+    return {
+        rootPath,
+        manifestPath,
+        skillPath
+    };
+}

package/dist/core/validate-plugin.js

@@ -131,6 +131,12 @@ function countMatches(input, pattern) {
     const matches = input.match(pattern);
     return matches ? matches.length : 0;
 }
+function extractSupportAssetReferences(content) {
+    const references = [...content.matchAll(/`((?:scripts|templates|assets|examples)\/[^`]+)`/g)]
+        .map((match) => match[1].trim())
+        .filter((reference) => reference.length > 0);
+    return [...new Set(references)];
+}
 function isDescriptionLikelyVerbose(description, mode) {
     const trimmed = description.trim();
     const length = trimmed.length;
@@ -252,6 +258,14 @@ async function validateSkillDefinitions(discoveredPackage) {
             isDescriptionLikelyVerbose(frontmatter.description, "skill")) {
             findings.push(buildWarning("plugin.heuristic.skill_description.too_long", `The skill \`${skillDirectory.name}\` description is likely too verbose.`, "Overly long skill descriptions increase context cost and reduce the precision of skill matching.", `Shorten the \`description\` field in \`${skillFilePath}\` to a tightly scoped summary.`));
         }
+        for (const supportReference of extractSupportAssetReferences(skillContent)) {
+            const supportPath = path.resolve(skillRoot, supportReference);
+            const supportFileExists = await fileExists(supportPath);
+            const supportDirectoryExists = await directoryExists(supportPath);
+            if (!supportFileExists && !supportDirectoryExists) {
+                findings.push(buildWarning("plugin.skill.asset_reference.missing", `The skill \`${skillDirectory.name}\` references missing support asset \`${supportReference}\`.`, "Skills that point to missing scripts, templates, assets, or examples are harder to execute and can fail when an agent follows the instructions.", `Create \`${supportPath}\` or update the reference in \`${skillFilePath}\`.`));
+            }
+        }
     }
     return findings;
 }

package/dist/reporting/render-compatibility-report.d.ts

@@ -0,0 +1,2 @@
+import type { CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+export declare function renderCompatibilityReport(matrix: CompatibilityMatrix): string;

package/dist/reporting/render-compatibility-report.js

@@ -0,0 +1,18 @@
+function statusLabel(status) {
+    return status.toUpperCase();
+}
+export function renderCompatibilityReport(matrix) {
+    const lines = [
+        "Compatibility Matrix",
+        "====================",
+        `Target: ${matrix.targetPath}`,
+        ""
+    ];
+    for (const result of matrix.results) {
+        lines.push(`${result.client}: ${statusLabel(result.status)} - ${result.summary}`);
+        for (const detail of result.details) {
+            lines.push(`  - ${detail}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/reporting/render-installed-summary.d.ts

@@ -0,0 +1,7 @@
+import type { CheckResult } from "../domain/types.js";
+import type { InstalledPlugin } from "../core/discover-installed-plugins.js";
+export interface InstalledPluginCheckResult {
+    plugin: InstalledPlugin;
+    result: CheckResult;
+}
+export declare function renderInstalledSummary(checkedPlugins: InstalledPluginCheckResult[]): string;

package/dist/reporting/render-installed-summary.js

@@ -0,0 +1,22 @@
+export function renderInstalledSummary(checkedPlugins) {
+    const passCount = checkedPlugins.filter((item) => item.result.status === "pass").length;
+    const warnCount = checkedPlugins.filter((item) => item.result.status === "warn").length;
+    const failCount = checkedPlugins.filter((item) => item.result.status === "fail").length;
+    const lines = [
+        "Installed Plugin Summary",
+        "========================",
+        `Checked: ${checkedPlugins.length}`,
+        `Pass: ${passCount}`,
+        `Warn: ${warnCount}`,
+        `Fail: ${failCount}`,
+        "",
+        "Plugins",
+        "-------"
+    ];
+    for (const item of checkedPlugins) {
+        const findingIds = item.result.findings.map((finding) => finding.id);
+        const suffix = findingIds.length > 0 ? ` (${findingIds.join(", ")})` : "";
+        lines.push(`${item.result.status.toUpperCase()} ${item.plugin.name} - ${item.plugin.relativePath}${suffix}`);
+    }
+    return lines.join("\n");
+}

package/dist/reporting/render-rule-explanation.d.ts

@@ -0,0 +1,2 @@
+import type { RuleDefinition } from "../rules/rule-catalog.js";
+export declare function renderRuleExplanation(rule: RuleDefinition): string;

package/dist/reporting/render-rule-explanation.js

@@ -0,0 +1,26 @@
+export function renderRuleExplanation(rule) {
+    return [
+        `Rule: ${rule.id}`,
+        "==============================",
+        `Category: ${rule.category}`,
+        `Default severity: ${rule.defaultSeverity}`,
+        "",
+        "Summary",
+        "-------",
+        rule.summary,
+        "",
+        "Why it matters",
+        "--------------",
+        rule.why,
+        "",
+        "Suggested fix",
+        "-------------",
+        rule.fix,
+        "",
+        "Example",
+        "-------",
+        rule.example,
+        "",
+        "Full catalog: docs/rules/catalog.md"
+    ].join("\n");
+}

package/dist/reporting/render-sarif-report.d.ts

@@ -0,0 +1,2 @@
+import type { CheckResult } from "../domain/types.js";
+export declare function renderSarifReport(result: CheckResult): string;

package/dist/reporting/render-sarif-report.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { findRuleDefinition } from "../rules/rule-catalog.js";
+function levelForFinding(finding) {
+    return finding.severity === "fail" ? "error" : "warning";
+}
+export function renderSarifReport(result) {
+    const rules = [...new Set(result.findings.map((finding) => finding.id))]
+        .map((ruleId) => {
+        const catalogEntry = findRuleDefinition(ruleId);
+        return {
+            id: ruleId,
+            name: ruleId,
+            shortDescription: {
+                text: catalogEntry?.summary ?? ruleId
+            },
+            help: {
+                text: catalogEntry
+                    ? `${catalogEntry.why}\n\nSuggested fix: ${catalogEntry.fix}`
+                    : "See the Codex Plugin Doctor report for remediation guidance."
+            }
+        };
+    });
+    const sarif = {
+        version: "2.1.0",
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "Codex Plugin Doctor",
+                        informationUri: "https://github.com/Esquetta/CodexPluginDoctor",
+                        rules
+                    }
+                },
+                results: result.findings.map((finding) => ({
+                    ruleId: finding.id,
+                    level: levelForFinding(finding),
+                    message: {
+                        text: `${finding.message} Suggested fix: ${finding.suggestedFix}`
+                    },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: {
+                                    uri: path.basename(result.targetPath)
+                                }
+                            }
+                        }
+                    ]
+                }))
+            }
+        ]
+    };
+    return JSON.stringify(sarif, null, 2);
+}

package/dist/rules/rule-catalog.d.ts

@@ -0,0 +1,13 @@
+export type RuleCategory = "package" | "skill" | "mcp" | "runtime" | "security";
+export type RuleSeverity = "fail" | "warn";
+export interface RuleDefinition {
+    id: string;
+    category: RuleCategory;
+    defaultSeverity: RuleSeverity;
+    summary: string;
+    why: string;
+    fix: string;
+    example: string;
+}
+export declare const ruleCatalog: RuleDefinition[];
+export declare function findRuleDefinition(id: string): RuleDefinition | null;

package/dist/rules/rule-catalog.js

@@ -0,0 +1,194 @@
+export const ruleCatalog = [
+    {
+        id: "plugin.manifest.missing",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The target directory is missing `.codex-plugin/plugin.json`.",
+        why: "Codex needs the plugin manifest as the package entry point. Without it, the directory cannot be treated as a plugin package.",
+        fix: "Run the doctor against a plugin package root, or create `.codex-plugin/plugin.json` with at least `name`, `version`, and `description`.",
+        example: '{ "name": "my-plugin", "version": "0.1.0", "description": "Adds focused Codex workflow helpers." }'
+    },
+    {
+        id: "plugin.manifest.name.missing",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The plugin manifest is missing a stable `name` field.",
+        why: "Codex and release tooling need a stable package name for display, matching, and diagnostics.",
+        fix: "Add a kebab-case `name` field to `.codex-plugin/plugin.json`.",
+        example: '{ "name": "github-workflow-doctor" }'
+    },
+    {
+        id: "plugin.manifest.version.missing",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The plugin manifest is missing a `version` field.",
+        why: "Compatibility checks and release workflows cannot reason about package changes without a version.",
+        fix: "Add a semantic `version` field to `.codex-plugin/plugin.json`.",
+        example: '{ "version": "0.1.0" }'
+    },
+    {
+        id: "plugin.manifest.description.missing",
+        category: "package",
+        defaultSeverity: "fail",
+        summary: "The plugin manifest is missing a `description` field.",
+        why: "Plugin surfaces and reviewers need concise package metadata to understand what the plugin does.",
+        fix: "Add a short, specific `description` field to `.codex-plugin/plugin.json`.",
+        example: '{ "description": "Validates GitHub PR automation workflows before release." }'
+    },
+    {
+        id: "plugin.heuristic.description.too_long",
+        category: "package",
+        defaultSeverity: "warn",
+        summary: "The plugin manifest description is likely too verbose.",
+        why: "Verbose package metadata increases context cost and can dilute plugin discovery quality.",
+        fix: "Shorten the manifest description to a precise one- or two-sentence summary.",
+        example: "Good: `Audits Codex plugin packages before publishing.`"
+    },
+    {
+        id: "plugin.skills.path.missing",
+        category: "skill",
+        defaultSeverity: "fail",
+        summary: "The manifest points to a missing skills directory.",
+        why: "Codex cannot load packaged skills when the manifest references a directory that does not exist.",
+        fix: "Create the referenced skills directory or update the `skills` path in `.codex-plugin/plugin.json`.",
+        example: '{ "skills": "skills" }'
+    },
+    {
+        id: "plugin.skill.skill_md.missing",
+        category: "skill",
+        defaultSeverity: "fail",
+        summary: "A skill directory does not contain `SKILL.md`.",
+        why: "`SKILL.md` is the required entry point for Codex to load skill instructions and metadata.",
+        fix: "Add `SKILL.md` with frontmatter containing at least `name` and `description`.",
+        example: "---\nname: repo-auditor\ndescription: Use when auditing repository health.\n---"
+    },
+    {
+        id: "plugin.skill.name.missing",
+        category: "skill",
+        defaultSeverity: "fail",
+        summary: "A skill `SKILL.md` file is missing `name` frontmatter.",
+        why: "Codex needs a stable skill name for matching, display, and diagnostics.",
+        fix: "Add a `name` field to the skill frontmatter.",
+        example: "---\nname: release-checker\n---"
+    },
+    {
+        id: "plugin.skill.description.missing",
+        category: "skill",
+        defaultSeverity: "fail",
+        summary: "A skill `SKILL.md` file is missing `description` frontmatter.",
+        why: "Skill descriptions drive discovery and implicit matching, so missing descriptions make skills harder to use.",
+        fix: "Add a scoped `description` field that says when the skill should be used.",
+        example: "---\ndescription: Use when preparing an npm release with verification gates.\n---"
+    },
+    {
+        id: "plugin.heuristic.skill_description.too_long",
+        category: "skill",
+        defaultSeverity: "warn",
+        summary: "A skill description is likely too verbose.",
+        why: "Long, vague descriptions increase context cost and reduce skill matching precision.",
+        fix: "Shorten the description while keeping concrete triggers, inputs, and output expectations.",
+        example: "Good: `Use when creating GitHub Actions release workflows for Node CLIs.`"
+    },
+    {
+        id: "plugin.skill.asset_reference.missing",
+        category: "skill",
+        defaultSeverity: "warn",
+        summary: "A skill references a missing local support asset.",
+        why: "Skills that point to missing scripts, templates, assets, or examples can fail when an agent follows the instructions.",
+        fix: "Create the referenced support file or update the backticked reference in `SKILL.md`.",
+        example: "If `SKILL.md` says `scripts/setup.ps1`, make sure that file exists inside the skill directory."
+    },
+    {
+        id: "plugin.mcp.path.missing",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "The manifest points to a missing `.mcp.json` file.",
+        why: "Codex cannot load bundled MCP server definitions if the referenced config file does not exist.",
+        fix: "Create the referenced `.mcp.json` file or update the `mcpServers` path in the manifest.",
+        example: '{ "mcpServers": ".mcp.json" }'
+    },
+    {
+        id: "plugin.mcp.invalid_json",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "The referenced `.mcp.json` file is not valid JSON.",
+        why: "Codex must parse MCP configuration before it can start bundled servers.",
+        fix: "Fix the JSON syntax in the referenced `.mcp.json` file.",
+        example: '{ "mcpServers": { "doctor": { "command": "node", "args": ["server.js"] } } }'
+    },
+    {
+        id: "plugin.mcp.invalid_shape",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "The `.mcp.json` file does not expose a valid `mcpServers` object.",
+        why: "Codex expects MCP configuration to be object-shaped with named server entries.",
+        fix: "Define a non-empty top-level `mcpServers` object.",
+        example: '{ "mcpServers": { "doctor": { "command": "node", "args": ["server.js"] } } }'
+    },
+    {
+        id: "plugin.mcp.server.invalid",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "An MCP server entry is not an object.",
+        why: "Codex cannot interpret server settings unless each server is represented as an object.",
+        fix: "Change the server entry to an object with transport options.",
+        example: '{ "mcpServers": { "doctor": { "command": "node" } } }'
+    },
+    {
+        id: "plugin.mcp.server.transport.missing",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "An MCP server entry is missing both `command` and `url`.",
+        why: "Codex needs either a stdio command or a streamable HTTP URL to connect to a server.",
+        fix: "Add `command` for stdio servers or `url` for remote servers.",
+        example: '{ "command": "node", "args": ["server.js"] }'
+    },
+    {
+        id: "plugin.security.path_traversal",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "A manifest path escapes the plugin package root.",
+        why: "Paths outside the package root can expose unintended files and make package review unreliable.",
+        fix: "Keep manifest paths such as `skills` and `mcpServers` inside the plugin root.",
+        example: '{ "skills": "skills", "mcpServers": ".mcp.json" }'
+    },
+    {
+        id: "plugin.security.hard_coded_secret",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server config contains a hard-coded secret-like env value.",
+        why: "Bundled credentials can leak through source control, npm packages, logs, or support bundles.",
+        fix: "Replace literal secrets with environment references or externally injected secrets.",
+        example: '{ "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" } }'
+    },
+    {
+        id: "plugin.runtime.exited_early",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "An MCP server exited before the startup probe completed.",
+        why: "A server that exits immediately is unlikely to remain available during normal Codex use.",
+        fix: "Run the configured command manually, inspect stderr, and fix startup exceptions or missing dependencies.",
+        example: "node server.js"
+    },
+    {
+        id: "plugin.runtime.initialize.timeout",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "An MCP server did not answer `initialize` in time.",
+        why: "Codex cannot negotiate capabilities with a server that does not complete initialization.",
+        fix: "Ensure the server reads JSON-RPC from stdin, writes responses to stdout, and avoids slow startup work.",
+        example: "Respond to the `initialize` request before starting expensive background tasks."
+    },
+    {
+        id: "plugin.runtime.protocol.invalid_message",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "An MCP server wrote invalid JSON-RPC data to stdout.",
+        why: "MCP stdio transport requires newline-delimited JSON-RPC messages on stdout.",
+        fix: "Send logs to stderr and reserve stdout for JSON-RPC protocol messages only.",
+        example: "Use `console.error` for diagnostics in Node stdio servers."
+    }
+];
+export function findRuleDefinition(id) {
+    return ruleCatalog.find((rule) => rule.id === id) ?? null;
+}

package/dist/run-cli.js

@@ -1,9 +1,17 @@
 import { writeFile } from "node:fs/promises";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
+import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.js";
+import { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
+import { initPluginPackage } from "./core/init-plugin.js";
 import { runCheck } from "./index.js";
+import { renderInstalledSummary } from "./reporting/render-installed-summary.js";
+import { renderCompatibilityReport } from "./reporting/render-compatibility-report.js";
 import { renderJsonReport } from "./reporting/render-json-report.js";
 import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
+import { renderRuleExplanation } from "./reporting/render-rule-explanation.js";
+import { renderSarifReport } from "./reporting/render-sarif-report.js";
 import { renderTextReport } from "./reporting/render-text-report.js";
+import { findRuleDefinition } from "./rules/rule-catalog.js";
 import { createLiveStatusRenderer } from "./terminal/live-status-renderer.js";
 import { determineOutputPolicy } from "./terminal/output-policy.js";
 import { getSpinner } from "./terminal/spinner-registry.js";
@@ -17,7 +25,7 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor --version");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--json] [--output <path>]\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -36,6 +44,25 @@ function renderInstalledPlugins(plugins) {
     }
     return lines.join("\n");
 }
+const compatibilityClientAliases = {
+    codex: "Codex",
+    "generic-mcp": "Generic MCP",
+    generic: "Generic MCP",
+    mcp: "Generic MCP",
+    "claude-desktop": "Claude Desktop",
+    claude: "Claude Desktop",
+    cursor: "Cursor"
+};
+function filterCompatibilityMatrix(matrix, clientFilter) {
+    const client = compatibilityClientAliases[clientFilter.toLowerCase()];
+    if (!client) {
+        return null;
+    }
+    return {
+        ...matrix,
+        results: matrix.results.filter((result) => result.client === client)
+    };
+}
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
     if (command === "--version" || command === "-v" || command === "version") {
@@ -54,6 +81,68 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStdout(renderInstalledPlugins(installedPlugins));
         return 0;
     }
+    if (command === "explain") {
+        if (!maybePath || maybePath.startsWith("--")) {
+            io.writeStderr("Missing finding id. Usage: codex-plugin-doctor explain <finding-id>");
+            return 2;
+        }
+        const rule = findRuleDefinition(maybePath);
+        if (!rule) {
+            io.writeStderr(`Unknown finding id: ${maybePath}`);
+            return 1;
+        }
+        io.writeStdout(renderRuleExplanation(rule));
+        return 0;
+    }
+    if (command === "init") {
+        const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+        const result = await initPluginPackage(targetPath);
+        io.writeStdout([
+            "Initialized Codex plugin package",
+            `Root: ${result.rootPath}`,
+            `Manifest: ${result.manifestPath}`,
+            `Skill: ${result.skillPath}`,
+            "",
+            `Next: codex-plugin-doctor check ${result.rootPath}`
+        ].join("\n"));
+        return 0;
+    }
+    if (command === "compat") {
+        const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+        const compatFlags = maybePath && maybePath.startsWith("--")
+            ? [maybePath, ...remainingArgs]
+            : remainingArgs;
+        const jsonOutput = compatFlags.includes("--json");
+        const clientIndex = compatFlags.indexOf("--client");
+        const clientFilter = clientIndex === -1 ? null : compatFlags[clientIndex + 1];
+        const outputIndex = compatFlags.indexOf("--output");
+        const outputPath = outputIndex === -1 ? null : compatFlags[outputIndex + 1];
+        if (clientIndex !== -1 && (!clientFilter || clientFilter.startsWith("--"))) {
+            io.writeStderr("Missing client after --client.");
+            return 2;
+        }
+        if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+            io.writeStderr("Missing path after --output.");
+            return 2;
+        }
+        let matrix = await buildCompatibilityMatrix(targetPath);
+        if (clientFilter) {
+            const filteredMatrix = filterCompatibilityMatrix(matrix, clientFilter);
+            if (!filteredMatrix) {
+                io.writeStderr(`Unknown compatibility client: ${clientFilter}`);
+                return 2;
+            }
+            matrix = filteredMatrix;
+        }
+        const report = jsonOutput
+            ? JSON.stringify({ schemaVersion: "1.0.0", ...matrix }, null, 2)
+            : renderCompatibilityReport(matrix);
+        if (outputPath) {
+            await writeFile(outputPath, report, "utf8");
+        }
+        io.writeStdout(report);
+        return matrixExitCode(matrix);
+    }
     if (command !== "check") {
         printUsage(io);
         return 2;
@@ -73,16 +162,24 @@ export async function runCli(args, io = defaultIo, options = {}) {
             : remainingArgs;
     const jsonOutput = normalizedFlags.includes("--json");
     const markdownOutput = normalizedFlags.includes("--markdown");
+    const sarifOutput = normalizedFlags.includes("--sarif");
     const runtimeProbeEnabled = normalizedFlags.includes("--runtime");
     const verboseRuntime = normalizedFlags.includes("--verbose-runtime");
     const noAnimations = normalizedFlags.includes("--no-animations");
     const asciiMode = normalizedFlags.includes("--ascii");
+    const installedSummary = normalizedFlags.includes("--all-summary");
     const outputIndex = normalizedFlags.indexOf("--output");
     const outputPath = outputIndex === -1 ? null : normalizedFlags[outputIndex + 1];
+    const configIndex = normalizedFlags.indexOf("--config");
+    const configPath = configIndex === -1 ? null : normalizedFlags[configIndex + 1];
     if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
         io.writeStderr("Missing path after --output.");
         return 2;
     }
+    if (configIndex !== -1 && (!configPath || configPath.startsWith("--"))) {
+        io.writeStderr("Missing path after --config.");
+        return 2;
+    }
     const outputPolicy = determineOutputPolicy({
         jsonOutput,
         markdownOutput,
@@ -102,39 +199,47 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 : "No installed Codex plugins found.");
             return 1;
         }
-        const results = [];
+        const checkedPlugins = [];
         for (const plugin of installedPlugins) {
-            results.push(await runCheckImpl(plugin.rootPath, {
-                runtime: runtimeProbeEnabled,
-                runtimeTranscript: runtimeProbeEnabled && verboseRuntime
-                    ? (line) => io.writeStderr(line)
-                    : undefined
-            }));
+            const config = await loadDoctorConfig(plugin.rootPath, configPath);
+            checkedPlugins.push({
+                plugin,
+                result: applyDoctorConfig(await runCheckImpl(plugin.rootPath, {
+                    runtime: runtimeProbeEnabled,
+                    runtimeTranscript: runtimeProbeEnabled && verboseRuntime
+                        ? (line) => io.writeStderr(line)
+                        : undefined
+                }), config)
+            });
         }
-        const report = results
-            .map((result) => markdownOutput
-            ? buildMarkdownReport(result, { runtimeProbeEnabled })
-            : jsonOutput
-                ? renderJsonReport(result, { runtimeProbeEnabled })
-                : renderTextReport(result, { ascii: outputPolicy.style === "ascii" }))
-            .join("\n\n");
+        const report = installedSummary
+            ? renderInstalledSummary(checkedPlugins)
+            : checkedPlugins
+                .map((item) => sarifOutput
+                ? renderSarifReport(item.result)
+                : markdownOutput
+                    ? buildMarkdownReport(item.result, { runtimeProbeEnabled })
+                    : jsonOutput
+                        ? renderJsonReport(item.result, { runtimeProbeEnabled })
+                        : renderTextReport(item.result, { ascii: outputPolicy.style === "ascii" }))
+                .join("\n\n");
         if (outputPath) {
             await writeFile(outputPath, report, "utf8");
         }
         io.writeStdout(report);
-        return results.some((result) => result.exitCode === 1) ? 1 : 0;
+        return checkedPlugins.some((item) => item.result.exitCode === 1) ? 1 : 0;
     }
     const renderer = outputPolicy.interactive
         && !verboseRuntime
         ? createLiveStatusRenderer(io, getSpinner(outputPolicy.style === "ascii" ? "ascii" : "doctor"))
         : null;
     renderer?.start("Validating package");
-    const result = await runCheckImpl(targetPath, {
+    const result = applyDoctorConfig(await runCheckImpl(targetPath, {
         runtime: runtimeProbeEnabled,
         runtimeTranscript: runtimeProbeEnabled && verboseRuntime
             ? (line) => io.writeStderr(line)
             : undefined
-    });
+    }), await loadDoctorConfig(targetPath, configPath));
     if (renderer) {
         if (result.status === "fail") {
             renderer.stopFailure("Validation failed");
@@ -145,9 +250,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
     }
     const report = markdownOutput
         ? buildMarkdownReport(result, { runtimeProbeEnabled })
-        : jsonOutput
-            ? renderJsonReport(result, { runtimeProbeEnabled })
-            : renderTextReport(result, { ascii: outputPolicy.style === "ascii" });
+        : sarifOutput
+            ? renderSarifReport(result)
+            : jsonOutput
+                ? renderJsonReport(result, { runtimeProbeEnabled })
+                : renderTextReport(result, { ascii: outputPolicy.style === "ascii" });
     if (outputPath) {
         await writeFile(outputPath, report, "utf8");
     }

package/package.json

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