codex-plugin-doctor 0.4.0 → 0.5.0

package/README.md

@@ -1,308 +1,316 @@
-# Codex Plugin Doctor
-
-[![CI](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml/badge.svg)](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/codex-plugin-doctor.svg)](https://www.npmjs.com/package/codex-plugin-doctor)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
-[![GitHub release](https://img.shields.io/github/v/release/Esquetta/CodexPluginDoctor)](https://github.com/Esquetta/CodexPluginDoctor/releases)
-
-Codex Plugin Doctor is a local CLI validator for Codex plugin packages, skills, and MCP server bundles.
-
-It catches packaging, metadata, security, and runtime protocol problems before a plugin reaches users, teammates, or release workflows.
-
-## Status
-
-Codex Plugin Doctor is an early public CLI release.
-
-- Primary surface: GitHub repository and npm package
-- Distribution today: `npm install -g`, local source install, `npm link`, `npm pack`, GitHub Releases
-- Public npm package: `codex-plugin-doctor`
-- License: [MIT](./LICENSE)
-
-## Why This Exists
-
-Codex plugin packages can fail in several places:
-
-- the package manifest is missing or points outside the package root
-- skills exist but do not expose valid `SKILL.md` metadata
-- `.mcp.json` is malformed or references unsafe secrets
-- an MCP server starts but does not complete the protocol handshake
-- tools, resources, or prompts list successfully but fail deeper runtime checks
-- verbose metadata creates noisy matching and unnecessary context cost
-
-This tool gives plugin authors a repeatable preflight check before distribution.
-
-## What It Checks
-
-Static validation:
-
-- required `.codex-plugin/plugin.json`
-- manifest fields: `name`, `version`, `description`
-- skill directory wiring
-- `SKILL.md` presence and frontmatter fields
-- YAML single-line and block-scalar skill descriptions
-- `.mcp.json` structure
-- path traversal risks
-- hard-coded secret-like env values
-- description quality heuristics tuned against real plugin packages
-
-Runtime MCP validation with `--runtime`:
-
-- `initialize`
-- `notifications/initialized`
-- `tools/list`
-- `tools/call`
-- `resources/list`
-- `resources/read`
-- `resources/templates/list`
-- `prompts/list`
-- `prompts/get`
-- paginated list responses
-- runtime capability scorecard
-- redacted verbose transcript with `--verbose-runtime`
-
-Output formats:
-
-- human text output
-- JSON reports
-- Markdown reports
-- `--output` file writing
-- CI summary and artifact generation
-
-## Quick Start
-
-Global install from npm:
-
-```bash
-npm install -g codex-plugin-doctor
-codex-plugin-doctor --version
-codex-plugin-doctor self-test
-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
-npm install
-npm run build
-node dist/cli.js check examples/codex-doctor-runtime --runtime
-```
-
-For local global usage:
-
-```bash
-npm link
-codex-plugin-doctor check examples/codex-doctor-runtime --runtime
-```
-
-Generate validation artifacts locally:
-
-```bash
-npm run generate-validation-artifacts -- --target examples/codex-doctor-runtime --runtime-target examples/codex-doctor-runtime --out-dir validation-artifacts-local
-```
-
-## Example Output
-
-Passing runtime package:
-
-```text
-Codex Plugin Doctor
-===================
-Status: PASS
-Target: <repo>\examples\codex-doctor-runtime
-Summary: 0 fail, 0 warn, 0 total
-
-Runtime Scorecard
-----------------
-initialize: pass
-tools/list: pass
-tools/call: pass
-resources/list: pass
-resources/read: pass
-resources/templates/list: pass
-prompts/list: pass
-prompts/get: pass
-
-No findings.
-```
-
-Risky package:
-
-```text
-Codex Plugin Doctor
-===================
-Status: FAIL
-Target: <repo>\examples\codex-doctor-risky
-Summary: 1 fail, 0 warn, 1 total
-
-Failures
---------
-x plugin.security.hard_coded_secret
-  Message: The MCP server `dangerServer` contains a hard-coded secret-like env value for `OPENAI_API_KEY`.
-  Impact: Hard-coded credentials inside plugin bundles increase leakage risk and make secure rotation difficult.
-  Suggested fix: Replace the literal value for `OPENAI_API_KEY` with an environment reference or injected secret outside the package.
-```
-
-## Useful Commands
-
-Run these from a Codex plugin package root:
-
-```bash
-codex-plugin-doctor --version
-codex-plugin-doctor self-test
-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 . --client claude-desktop
-codex-plugin-doctor compat . --client claude-desktop --install-preview
-codex-plugin-doctor compat . --client claude-desktop --apply --backup
-codex-plugin-doctor compat . --client cursor
-codex-plugin-doctor compat . --client cursor --install-preview
-codex-plugin-doctor compat . --client cursor --apply --backup
-codex-plugin-doctor compat . --scorecard
-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
-```
-
-`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`.
-
-`compat --client claude-desktop` checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it looks for `~/Library/Application Support/Claude/claude_desktop_config.json`. A valid existing config returns `PASS`, a missing Claude Desktop install returns `WARN`, and a malformed local config returns `FAIL` so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns `WARN` with the duplicate server name. Add `--install-preview` to print the JSON snippet that should be merged into `claude_desktop_config.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
-
-`compat --client cursor` checks whether the MCP package can be added to Cursor. It prefers a project-level `.cursor/mcp.json` when one already exists in the target package, then falls back to the global `~/.cursor/mcp.json` path. A valid existing config returns `PASS`, a missing Cursor config returns `WARN`, malformed JSON returns `FAIL`, and duplicate MCP server names return `WARN`. Add `--install-preview` to print the JSON snippet that should be merged into Cursor's `mcp.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
-
-`compat --scorecard` turns the compatibility matrix into a compact score summary. `PASS` maps to `100`, `WARN` maps to `70`, and `FAIL` or `SKIPPED` maps to `0`.
-
-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:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-runtime --runtime --no-animations
-```
-
-## Repository Layout
-
-```text
-docs/                 Product, engineering, security, and release docs
-examples/             Manual plugin packs for local CLI testing
-src/                  CLI, validation logic, runtime probing, reports
-tests/                Fixture-based regression tests
-validation-sessions/  Real-world validation waves and tuning notes
-```
-
-## Validation Evidence
-
-The validator is tuned against local fixtures and real marketplace-style plugin packages. See:
-
-- [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:
-
-- curated Codex plugin cache packages
-- marketplace-style plugin snapshots
-- YAML block-scalar skill metadata
-- media and visual workflow metadata
-
-## Release Readiness
-
-Release preparation is reproducible from the repository:
-
-```bash
-npm run prepare-release
-```
-
-This runs tests, builds the TypeScript output, and performs `npm pack --dry-run`.
-
-Related docs:
-
-- [Changelog](./CHANGELOG.md)
-- [Contributing](./CONTRIBUTING.md)
-- [Security Policy](./SECURITY.md)
-- [Code of Conduct](./CODE_OF_CONDUCT.md)
-- [NPM Release Checklist](./docs/engineering/npm-release-checklist.md)
-- [Release Candidate Workflow](./docs/engineering/release-candidate-workflow.md)
-- [v0.1.0 Release Notes](./docs/engineering/v0.1.0-final-release-notes.md)
-
-## Contributing
-
-Contributions are welcome once the repository is public. Start with:
-
-- [Contributing](./CONTRIBUTING.md)
-- [Security Policy](./SECURITY.md)
-- [Validation tuning issue template](./.github/ISSUE_TEMPLATE/validation_tuning.yml)
-
-## Support
-
-If this tool saves you time, GitHub stars and sponsorship help signal that the project is worth continuing.
-
-- Star the repository on GitHub.
-- Use GitHub Sponsors through the repository funding link.
-- Open validation tuning issues for false positives or false negatives.
-
-## Product Direction
-
-Codex Plugin Doctor starts as a Codex-specific validator and can grow into a broader MCP Doctor over time.
-
-The immediate goal is not a marketplace, dashboard, or hosted website. The immediate goal is a trustworthy local preflight check for Codex-compatible plugin bundles.
+# Codex Plugin Doctor
+
+[![CI](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml/badge.svg)](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/codex-plugin-doctor.svg)](https://www.npmjs.com/package/codex-plugin-doctor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![GitHub release](https://img.shields.io/github/v/release/Esquetta/CodexPluginDoctor)](https://github.com/Esquetta/CodexPluginDoctor/releases)
+
+Codex Plugin Doctor is a local CLI validator for Codex plugin packages, skills, and MCP server bundles.
+
+It catches packaging, metadata, security, and runtime protocol problems before a plugin reaches users, teammates, or release workflows.
+
+## Status
+
+Codex Plugin Doctor is an early public CLI release.
+
+- Primary surface: GitHub repository and npm package
+- Distribution today: `npm install -g`, local source install, `npm link`, `npm pack`, GitHub Releases
+- Public npm package: `codex-plugin-doctor`
+- License: [MIT](./LICENSE)
+
+## Why This Exists
+
+Codex plugin packages can fail in several places:
+
+- the package manifest is missing or points outside the package root
+- skills exist but do not expose valid `SKILL.md` metadata
+- `.mcp.json` is malformed or references unsafe secrets
+- an MCP server starts but does not complete the protocol handshake
+- tools, resources, or prompts list successfully but fail deeper runtime checks
+- verbose metadata creates noisy matching and unnecessary context cost
+
+This tool gives plugin authors a repeatable preflight check before distribution.
+
+## What It Checks
+
+Static validation:
+
+- required `.codex-plugin/plugin.json`
+- manifest fields: `name`, `version`, `description`
+- skill directory wiring
+- `SKILL.md` presence and frontmatter fields
+- YAML single-line and block-scalar skill descriptions
+- `.mcp.json` structure
+- path traversal risks
+- hard-coded secret-like env values
+- description quality heuristics tuned against real plugin packages
+
+Runtime MCP validation with `--runtime`:
+
+- `initialize`
+- `notifications/initialized`
+- `tools/list`
+- `tools/call`
+- `resources/list`
+- `resources/read`
+- `resources/templates/list`
+- `prompts/list`
+- `prompts/get`
+- paginated list responses
+- runtime capability scorecard
+- redacted verbose transcript with `--verbose-runtime`
+
+Output formats:
+
+- human text output
+- JSON reports
+- Markdown reports
+- Shields-compatible badge JSON and static badge Markdown
+- `--output` file writing
+- CI summary and artifact generation
+
+## Quick Start
+
+Global install from npm:
+
+```bash
+npm install -g codex-plugin-doctor
+codex-plugin-doctor --version
+codex-plugin-doctor self-test
+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
+npm install
+npm run build
+node dist/cli.js check examples/codex-doctor-runtime --runtime
+```
+
+For local global usage:
+
+```bash
+npm link
+codex-plugin-doctor check examples/codex-doctor-runtime --runtime
+```
+
+Generate validation artifacts locally:
+
+```bash
+npm run generate-validation-artifacts -- --target examples/codex-doctor-runtime --runtime-target examples/codex-doctor-runtime --out-dir validation-artifacts-local
+```
+
+## Example Output
+
+Passing runtime package:
+
+```text
+Codex Plugin Doctor
+===================
+Status: PASS
+Target: <repo>\examples\codex-doctor-runtime
+Summary: 0 fail, 0 warn, 0 total
+
+Runtime Scorecard
+----------------
+initialize: pass
+tools/list: pass
+tools/call: pass
+resources/list: pass
+resources/read: pass
+resources/templates/list: pass
+prompts/list: pass
+prompts/get: pass
+
+No findings.
+```
+
+Risky package:
+
+```text
+Codex Plugin Doctor
+===================
+Status: FAIL
+Target: <repo>\examples\codex-doctor-risky
+Summary: 1 fail, 0 warn, 1 total
+
+Failures
+--------
+x plugin.security.hard_coded_secret
+  Message: The MCP server `dangerServer` contains a hard-coded secret-like env value for `OPENAI_API_KEY`.
+  Impact: Hard-coded credentials inside plugin bundles increase leakage risk and make secure rotation difficult.
+  Suggested fix: Replace the literal value for `OPENAI_API_KEY` with an environment reference or injected secret outside the package.
+```
+
+## Useful Commands
+
+Run these from a Codex plugin package root:
+
+```bash
+codex-plugin-doctor --version
+codex-plugin-doctor self-test
+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 . --client claude-desktop
+codex-plugin-doctor compat . --client claude-desktop --install-preview
+codex-plugin-doctor compat . --client claude-desktop --apply --backup
+codex-plugin-doctor compat . --client cursor
+codex-plugin-doctor compat . --client cursor --install-preview
+codex-plugin-doctor compat . --client cursor --apply --backup
+codex-plugin-doctor compat . --scorecard
+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 . --badge-json --output doctor-badge.json
+codex-plugin-doctor check . --badge-markdown
+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
+```
+
+`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`.
+
+`compat --client claude-desktop` checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it looks for `~/Library/Application Support/Claude/claude_desktop_config.json`. A valid existing config returns `PASS`, a missing Claude Desktop install returns `WARN`, and a malformed local config returns `FAIL` so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns `WARN` with the duplicate server name. Add `--install-preview` to print the JSON snippet that should be merged into `claude_desktop_config.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
+
+`compat --client cursor` checks whether the MCP package can be added to Cursor. It prefers a project-level `.cursor/mcp.json` when one already exists in the target package, then falls back to the global `~/.cursor/mcp.json` path. A valid existing config returns `PASS`, a missing Cursor config returns `WARN`, malformed JSON returns `FAIL`, and duplicate MCP server names return `WARN`. Add `--install-preview` to print the JSON snippet that should be merged into Cursor's `mcp.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
+
+`compat --scorecard` turns the compatibility matrix into a compact score summary. `PASS` maps to `100`, `WARN` maps to `70`, and `FAIL` or `SKIPPED` maps to `0`.
+
+`check --badge-json` emits Shields endpoint-compatible JSON such as `{"schemaVersion":1,"label":"doctor","message":"PASS","color":"brightgreen"}`. `check --badge-markdown` emits a static shields.io Markdown badge for README or release notes. Badge output is intentionally limited to single package checks, not `check --installed`.
+
+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.5.0
+        with:
+          version: "0.5.0"
+          path: .
+          runtime: "false"
+```
+
+For runtime probing, SARIF output, installed plugin cache checks, and pinned release examples, see [GitHub Action Usage](./docs/engineering/github-action-usage.md).
+
+To self-test this repository after cloning it:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-runtime --runtime --no-animations
+```
+
+## Repository Layout
+
+```text
+docs/                 Product, engineering, security, and release docs
+examples/             Manual plugin packs for local CLI testing
+src/                  CLI, validation logic, runtime probing, reports
+tests/                Fixture-based regression tests
+validation-sessions/  Real-world validation waves and tuning notes
+```
+
+## Validation Evidence
+
+The validator is tuned against local fixtures and real marketplace-style plugin packages. See:
+
+- [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:
+
+- curated Codex plugin cache packages
+- marketplace-style plugin snapshots
+- YAML block-scalar skill metadata
+- media and visual workflow metadata
+
+## Release Readiness
+
+Release preparation is reproducible from the repository:
+
+```bash
+npm run prepare-release
+```
+
+This runs tests, builds the TypeScript output, and performs `npm pack --dry-run`.
+
+Related docs:
+
+- [Changelog](./CHANGELOG.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Security Policy](./SECURITY.md)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [NPM Release Checklist](./docs/engineering/npm-release-checklist.md)
+- [Release Candidate Workflow](./docs/engineering/release-candidate-workflow.md)
+- [v0.1.0 Release Notes](./docs/engineering/v0.1.0-final-release-notes.md)
+
+## Contributing
+
+Contributions are welcome once the repository is public. Start with:
+
+- [Contributing](./CONTRIBUTING.md)
+- [Security Policy](./SECURITY.md)
+- [Validation tuning issue template](./.github/ISSUE_TEMPLATE/validation_tuning.yml)
+
+## Support
+
+If this tool saves you time, GitHub stars and sponsorship help signal that the project is worth continuing.
+
+- Star the repository on GitHub.
+- Use GitHub Sponsors through the repository funding link.
+- Open validation tuning issues for false positives or false negatives.
+
+## Product Direction
+
+Codex Plugin Doctor starts as a Codex-specific validator and can grow into a broader MCP Doctor over time.
+
+The immediate goal is not a marketplace, dashboard, or hosted website. The immediate goal is a trustworthy local preflight check for Codex-compatible plugin bundles.

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

@@ -0,0 +1,10 @@
+import type { CheckResult } from "../domain/types.js";
+export interface BadgeReport {
+    schemaVersion: 1;
+    label: "doctor";
+    message: "PASS" | "WARN" | "FAIL";
+    color: "brightgreen" | "yellow" | "red";
+}
+export declare function buildBadgeReport(result: CheckResult): BadgeReport;
+export declare function renderBadgeJson(result: CheckResult): string;
+export declare function renderBadgeMarkdown(result: CheckResult): string;

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

@@ -0,0 +1,32 @@
+function badgeForStatus(status) {
+    if (status === "pass") {
+        return {
+            message: "PASS",
+            color: "brightgreen"
+        };
+    }
+    if (status === "warn") {
+        return {
+            message: "WARN",
+            color: "yellow"
+        };
+    }
+    return {
+        message: "FAIL",
+        color: "red"
+    };
+}
+export function buildBadgeReport(result) {
+    return {
+        schemaVersion: 1,
+        label: "doctor",
+        ...badgeForStatus(result.status)
+    };
+}
+export function renderBadgeJson(result) {
+    return JSON.stringify(buildBadgeReport(result), null, 2);
+}
+export function renderBadgeMarkdown(result) {
+    const badge = buildBadgeReport(result);
+    return `![Codex Plugin Doctor](https://img.shields.io/badge/${badge.label}-${badge.message}-${badge.color})`;
+}

package/dist/run-cli.d.ts

@@ -7,6 +7,7 @@ export interface CliTerminalContext {
     stdoutIsTTY: boolean;
     stderrIsTTY: boolean;
     env: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
 }
 export interface RunCliOptions {
     terminalContext?: CliTerminalContext;

package/dist/run-cli.js

@@ -10,6 +10,7 @@ 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 { renderBadgeJson, renderBadgeMarkdown } from "./reporting/render-badge-report.js";
 import { renderCompatibilityScorecard } from "./reporting/render-compatibility-scorecard.js";
 import { renderCompatibilityReport } from "./reporting/render-compatibility-report.js";
 import { renderJsonReport } from "./reporting/render-json-report.js";
@@ -31,7 +32,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 compat <path> [--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -94,7 +95,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const terminalContext = options.terminalContext ?? {
         stdoutIsTTY: Boolean(process.stdout.isTTY),
         stderrIsTTY: Boolean(process.stderr.isTTY),
-        env: process.env
+        env: process.env,
+        platform: process.platform
     };
     if (command === "list" && maybePath === "--installed") {
         const installedPlugins = await discoverInstalledPlugins({
@@ -121,7 +123,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const runCheckImpl = options.runCheckImpl ?? runCheck;
         const result = applyDoctorConfig(await runCheckImpl(targetPath, { runtime: true }), await loadDoctorConfig(targetPath));
         const compatibilityMatrix = await buildCompatibilityMatrix(targetPath, {
-            env: terminalContext.env
+            env: terminalContext.env,
+            platform: terminalContext.platform
         });
         io.writeStdout(renderSelfTestReport(targetPath, result.status, result.findings.length, compatibilityMatrix));
         return result.exitCode === 1 || matrixExitCode(compatibilityMatrix) === 1 ? 1 : 0;
@@ -179,10 +182,12 @@ export async function runCli(args, io = defaultIo, options = {}) {
             try {
                 const preview = clientFilter?.toLowerCase() === "cursor"
                     ? await buildCursorInstallPreview(targetPath, {
-                        env: terminalContext.env
+                        env: terminalContext.env,
+                        platform: terminalContext.platform
                     })
                     : await buildClaudeDesktopInstallPreview(targetPath, {
-                        env: terminalContext.env
+                        env: terminalContext.env,
+                        platform: terminalContext.platform
                     });
                 const report = applyInstall
                     ? renderApplyInstallResult(await applyInstallPreview(clientFilter?.toLowerCase() === "cursor" ? "Cursor" : "Claude Desktop", preview))
@@ -202,7 +207,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
             }
         }
         let matrix = await buildCompatibilityMatrix(targetPath, {
-            env: terminalContext.env
+            env: terminalContext.env,
+            platform: terminalContext.platform
         });
         if (clientFilter) {
             const filteredMatrix = filterCompatibilityMatrix(matrix, clientFilter);
@@ -242,6 +248,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
             : remainingArgs;
     const jsonOutput = normalizedFlags.includes("--json");
     const markdownOutput = normalizedFlags.includes("--markdown");
+    const badgeJsonOutput = normalizedFlags.includes("--badge-json");
+    const badgeMarkdownOutput = normalizedFlags.includes("--badge-markdown");
     const sarifOutput = normalizedFlags.includes("--sarif");
     const runtimeProbeEnabled = normalizedFlags.includes("--runtime");
     const verboseRuntime = normalizedFlags.includes("--verbose-runtime");
@@ -260,9 +268,13 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("Missing path after --config.");
         return 2;
     }
+    if (checkInstalled && (badgeJsonOutput || badgeMarkdownOutput)) {
+        io.writeStderr("Badge output requires a single package target.");
+        return 2;
+    }
     const outputPolicy = determineOutputPolicy({
-        jsonOutput,
-        markdownOutput,
+        jsonOutput: jsonOutput || badgeJsonOutput,
+        markdownOutput: markdownOutput || badgeMarkdownOutput,
         outputPath,
         noAnimations,
         asciiMode,
@@ -334,7 +346,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
             ? renderSarifReport(result)
             : jsonOutput
                 ? renderJsonReport(result, { runtimeProbeEnabled })
-                : renderTextReport(result, { ascii: outputPolicy.style === "ascii" });
+                : badgeJsonOutput
+                    ? renderBadgeJson(result)
+                    : badgeMarkdownOutput
+                        ? renderBadgeMarkdown(result)
+                        : 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.4.0",
+  "version": "0.5.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",