codex-plugin-doctor 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Furkan Tasci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# Codex Plugin Doctor
+
+[![CI](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml/badge.svg)](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml)
+
+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 check .
+```
+
+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
+
+```bash
+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 . --ascii
+codex-plugin-doctor check . --no-animations
+codex-plugin-doctor check . --runtime
+codex-plugin-doctor check . --json --runtime --verbose-runtime
+```
+
+## 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)
+
+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)
+- [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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from "./run-cli.js";
+runCli(process.argv.slice(2)).then((exitCode) => {
+    process.exitCode = exitCode;
+}).catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    console.error(`codex-plugin-doctor failed: ${message}`);
+    process.exitCode = 2;
+});

package/dist/core/discover-package.d.ts

@@ -0,0 +1,2 @@
+import type { DiscoveredPackage } from "../domain/types.js";
+export declare function discoverPackage(targetPath: string): Promise<DiscoveredPackage | null>;

package/dist/core/discover-package.js

@@ -0,0 +1,18 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export async function discoverPackage(targetPath) {
+    const rootPath = path.resolve(targetPath);
+    const manifestPath = path.join(rootPath, ".codex-plugin", "plugin.json");
+    try {
+        const manifestContent = await readFile(manifestPath, "utf8");
+        const manifest = JSON.parse(manifestContent);
+        return {
+            rootPath,
+            manifestPath,
+            manifest
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/runtime-probe.d.ts

@@ -0,0 +1,5 @@
+import type { DiscoveredPackage, RuntimeProbeResult } from "../domain/types.js";
+export declare function probeRuntime(discoveredPackage: DiscoveredPackage, options?: {
+    startupTimeoutMs?: number;
+    transcript?: (line: string) => void;
+}): Promise<RuntimeProbeResult>;