codex-plugin-doctor 0.1.3 → 0.1.5

package/README.md

@@ -71,11 +71,22 @@ Global install from npm:
 
 ```bash
 npm install -g codex-plugin-doctor
+codex-plugin-doctor --version
 codex-plugin-doctor check path/to/plugin-package
 ```
 
 Run `codex-plugin-doctor check .` from the root of a Codex plugin package that contains `.codex-plugin/plugin.json`. The Codex Plugin Doctor source repository is not itself a plugin package.
 
+If you already have Codex installed locally and do not know plugin paths, discover the installed plugin cache:
+
+```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:
 
 ```bash
@@ -144,16 +155,59 @@ x plugin.security.hard_coded_secret
 Run these from a Codex plugin package root:
 
 ```bash
+codex-plugin-doctor --version
+codex-plugin-doctor init my-plugin
 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.1.4
+        with:
+          path: .
+          runtime: "false"
+```
+
 To self-test this repository after cloning it:
 
 ```bash
@@ -177,6 +231,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/core/discover-installed-plugins.d.ts

@@ -0,0 +1,12 @@
+export interface InstalledPlugin {
+    name: string;
+    version?: string;
+    rootPath: string;
+    manifestPath: string;
+    relativePath: string;
+}
+export interface InstalledPluginDiscoveryOptions {
+    env?: Record<string, string | undefined>;
+}
+export declare function discoverInstalledPlugins(options?: InstalledPluginDiscoveryOptions): Promise<InstalledPlugin[]>;
+export declare function filterInstalledPlugins(plugins: InstalledPlugin[], query: string | null): InstalledPlugin[];

package/dist/core/discover-installed-plugins.js

@@ -0,0 +1,69 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+async function directoryExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function getCodexHomeCandidates(env) {
+    const candidates = env.CODEX_HOME
+        ? [env.CODEX_HOME]
+        : [path.join(os.homedir(), ".codex")];
+    return [...new Set(candidates.map((candidate) => path.resolve(candidate)))];
+}
+async function findManifestPaths(rootPath) {
+    const entries = await readdir(rootPath, { withFileTypes: true });
+    const manifestPaths = [];
+    for (const entry of entries) {
+        const entryPath = path.join(rootPath, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === ".codex-plugin") {
+                manifestPaths.push(path.join(entryPath, "plugin.json"));
+                continue;
+            }
+            manifestPaths.push(...(await findManifestPaths(entryPath)));
+        }
+    }
+    return manifestPaths;
+}
+export async function discoverInstalledPlugins(options = {}) {
+    const env = options.env ?? process.env;
+    const plugins = [];
+    for (const codexHome of getCodexHomeCandidates(env)) {
+        const cacheRoot = path.join(codexHome, "plugins", "cache");
+        if (!(await directoryExists(cacheRoot))) {
+            continue;
+        }
+        for (const manifestPath of await findManifestPaths(cacheRoot)) {
+            try {
+                const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+                const rootPath = path.dirname(path.dirname(manifestPath));
+                const relativePath = path.relative(cacheRoot, rootPath);
+                plugins.push({
+                    name: typeof manifest.name === "string" ? manifest.name : path.basename(rootPath),
+                    version: typeof manifest.version === "string" ? manifest.version : undefined,
+                    rootPath,
+                    manifestPath,
+                    relativePath
+                });
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return plugins.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+export function filterInstalledPlugins(plugins, query) {
+    if (!query) {
+        return plugins;
+    }
+    const normalizedQuery = query.toLowerCase();
+    return plugins.filter((plugin) => [plugin.name, plugin.relativePath, plugin.rootPath]
+        .some((value) => value.toLowerCase().includes(normalizedQuery)));
+}

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-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,11 +1,19 @@
 import { writeFile } from "node:fs/promises";
+import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.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 { 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";
+import { packageVersion } from "./version.js";
 const defaultIo = {
     writeStdout(message) {
         process.stdout.write(`${message}\n`);
@@ -15,35 +23,106 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path> [--json|--markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]");
+    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 explain <finding-id>\n       codex-plugin-doctor --version");
+}
+function renderInstalledPlugins(plugins) {
+    const lines = [
+        "Installed Codex Plugins",
+        "======================="
+    ];
+    if (plugins.length === 0) {
+        lines.push("", "No installed Codex plugins found.");
+        return lines.join("\n");
+    }
+    for (const plugin of plugins) {
+        const version = plugin.version ? `@${plugin.version}` : "";
+        lines.push("", `- ${plugin.name}${version}`);
+        lines.push(`  Path: ${plugin.rootPath}`);
+        lines.push(`  Cache: ${plugin.relativePath}`);
+    }
+    return lines.join("\n");
 }
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
+    if (command === "--version" || command === "-v" || command === "version") {
+        io.writeStdout(packageVersion);
+        return 0;
+    }
+    const terminalContext = options.terminalContext ?? {
+        stdoutIsTTY: Boolean(process.stdout.isTTY),
+        stderrIsTTY: Boolean(process.stderr.isTTY),
+        env: process.env
+    };
+    if (command === "list" && maybePath === "--installed") {
+        const installedPlugins = await discoverInstalledPlugins({
+            env: terminalContext.env
+        });
+        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 !== "check") {
         printUsage(io);
         return 2;
     }
-    const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
-    const normalizedFlags = maybePath && maybePath.startsWith("--")
-        ? [maybePath, ...remainingArgs]
+    const checkInstalled = maybePath === "--installed";
+    const installedFilter = checkInstalled && remainingArgs[0] && !remainingArgs[0].startsWith("--")
+        ? remainingArgs[0]
+        : null;
+    const flagsAfterInstalledFilter = checkInstalled && installedFilter
+        ? remainingArgs.slice(1)
         : remainingArgs;
+    const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+    const normalizedFlags = checkInstalled
+        ? [maybePath, ...flagsAfterInstalledFilter]
+        : maybePath && maybePath.startsWith("--")
+            ? [maybePath, ...remainingArgs]
+            : 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;
     }
-    const terminalContext = options.terminalContext ?? {
-        stdoutIsTTY: Boolean(process.stdout.isTTY),
-        stderrIsTTY: Boolean(process.stderr.isTTY),
-        env: process.env
-    };
+    if (configIndex !== -1 && (!configPath || configPath.startsWith("--"))) {
+        io.writeStderr("Missing path after --config.");
+        return 2;
+    }
     const outputPolicy = determineOutputPolicy({
         jsonOutput,
         markdownOutput,
@@ -55,17 +134,55 @@ export async function runCli(args, io = defaultIo, options = {}) {
         env: terminalContext.env
     });
     const runCheckImpl = options.runCheckImpl ?? runCheck;
+    if (checkInstalled) {
+        const installedPlugins = filterInstalledPlugins(await discoverInstalledPlugins({ env: terminalContext.env }), installedFilter);
+        if (installedPlugins.length === 0) {
+            io.writeStderr(installedFilter
+                ? `No installed Codex plugins matched '${installedFilter}'.`
+                : "No installed Codex plugins found.");
+            return 1;
+        }
+        const checkedPlugins = [];
+        for (const plugin of installedPlugins) {
+            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 = 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 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");
@@ -76,9 +193,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/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const packageVersion: string;

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+export const packageVersion = packageJson.version;

package/package.json

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