codex-plugin-doctor 0.1.1

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

@@ -0,0 +1,44 @@
+export function buildMarkdownReport(result, options) {
+    const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
+    const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
+    const lines = [
+        "# Codex Plugin Doctor Report",
+        "",
+        "| Field | Value |",
+        "| --- | --- |",
+        `| Target | \`${result.targetPath}\` |`,
+        `| Status | ${result.status.toUpperCase()} |`,
+        `| Exit Code | ${result.exitCode} |`,
+        `| Runtime Probe | ${options.runtimeProbeEnabled ? "enabled" : "disabled"} |`,
+        `| Fail Findings | ${failCount} |`,
+        `| Warn Findings | ${warnCount} |`,
+        `| Total Findings | ${result.findings.length} |`
+    ];
+    if (result.findings.length === 0) {
+        lines.push("", "No findings.");
+        return lines.join("\n");
+    }
+    if (result.runtimeScorecard) {
+        lines.push("", "## Runtime Scorecard", "");
+        lines.push("| Operation | Status |");
+        lines.push("| --- | --- |");
+        lines.push(`| initialize | ${result.runtimeScorecard.initialize.toUpperCase()} |`);
+        lines.push(`| tools/list | ${result.runtimeScorecard.toolsList.toUpperCase()} |`);
+        lines.push(`| tools/call | ${result.runtimeScorecard.toolsCall.toUpperCase()} |`);
+        lines.push(`| resources/list | ${result.runtimeScorecard.resourcesList.toUpperCase()} |`);
+        lines.push(`| resources/read | ${result.runtimeScorecard.resourceRead.toUpperCase()} |`);
+        lines.push(`| resources/templates/list | ${result.runtimeScorecard.resourceTemplatesList.toUpperCase()} |`);
+        lines.push(`| prompts/list | ${result.runtimeScorecard.promptsList.toUpperCase()} |`);
+        lines.push(`| prompts/get | ${result.runtimeScorecard.promptGet.toUpperCase()} |`);
+    }
+    lines.push("", "## Findings", "");
+    for (const finding of result.findings) {
+        lines.push(`### ${finding.severity.toUpperCase()} \`${finding.id}\``);
+        lines.push("");
+        lines.push(`- Message: ${finding.message}`);
+        lines.push(`- Impact: ${finding.impact}`);
+        lines.push(`- Suggested fix: ${finding.suggestedFix}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,4 @@
+import type { CheckResult } from "../domain/types.js";
+export declare function renderTextReport(result: CheckResult, options?: {
+    ascii?: boolean;
+}): string;

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

@@ -0,0 +1,77 @@
+function getCounts(result) {
+    const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
+    const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
+    return {
+        failCount,
+        warnCount,
+        totalCount: result.findings.length
+    };
+}
+function getGlyphs(ascii) {
+    return ascii
+        ? {
+            fail: "x",
+            warn: "!",
+            ok: "ok"
+        }
+        : {
+            fail: "✖",
+            warn: "!",
+            ok: "✔"
+        };
+}
+export function renderTextReport(result, options = {}) {
+    const ascii = options.ascii ?? false;
+    const glyphs = getGlyphs(ascii);
+    const { failCount, warnCount, totalCount } = getCounts(result);
+    const lines = [
+        "Codex Plugin Doctor",
+        "===================",
+        `Status: ${result.status.toUpperCase()}`,
+        `Target: ${result.targetPath}`,
+        `Summary: ${failCount} fail, ${warnCount} warn, ${totalCount} total`
+    ];
+    if (result.findings.length === 0) {
+        if (result.runtimeScorecard) {
+            lines.push("", "Runtime Scorecard", "----------------");
+            lines.push(`initialize: ${result.runtimeScorecard.initialize}`);
+            lines.push(`tools/list: ${result.runtimeScorecard.toolsList}`);
+            lines.push(`tools/call: ${result.runtimeScorecard.toolsCall}`);
+            lines.push(`resources/list: ${result.runtimeScorecard.resourcesList}`);
+            lines.push(`resources/read: ${result.runtimeScorecard.resourceRead}`);
+            lines.push(`resources/templates/list: ${result.runtimeScorecard.resourceTemplatesList}`);
+            lines.push(`prompts/list: ${result.runtimeScorecard.promptsList}`);
+            lines.push(`prompts/get: ${result.runtimeScorecard.promptGet}`);
+        }
+        lines.push("", "No findings.");
+        return lines.join("\n");
+    }
+    const failures = result.findings.filter((finding) => finding.severity === "fail");
+    const warnings = result.findings.filter((finding) => finding.severity === "warn");
+    const appendSection = (title, items, marker) => {
+        if (items.length === 0) {
+            return;
+        }
+        lines.push("", title, "--------");
+        for (const finding of items) {
+            lines.push(`${marker} ${finding.id}`);
+            lines.push(`  Message: ${finding.message}`);
+            lines.push(`  Impact: ${finding.impact}`);
+            lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+        }
+    };
+    appendSection("Failures", failures, glyphs.fail);
+    appendSection("Warnings", warnings, glyphs.warn);
+    if (result.runtimeScorecard) {
+        lines.push("", "Runtime Scorecard", "----------------");
+        lines.push(`initialize: ${result.runtimeScorecard.initialize}`);
+        lines.push(`tools/list: ${result.runtimeScorecard.toolsList}`);
+        lines.push(`tools/call: ${result.runtimeScorecard.toolsCall}`);
+        lines.push(`resources/list: ${result.runtimeScorecard.resourcesList}`);
+        lines.push(`resources/read: ${result.runtimeScorecard.resourceRead}`);
+        lines.push(`resources/templates/list: ${result.runtimeScorecard.resourceTemplatesList}`);
+        lines.push(`prompts/list: ${result.runtimeScorecard.promptsList}`);
+        lines.push(`prompts/get: ${result.runtimeScorecard.promptGet}`);
+    }
+    return lines.join("\n");
+}

package/dist/run-cli.d.ts

@@ -0,0 +1,15 @@
+import { runCheck } from "./index.js";
+export interface CliIo {
+    writeStdout(message: string): void;
+    writeStderr(message: string): void;
+}
+export interface CliTerminalContext {
+    stdoutIsTTY: boolean;
+    stderrIsTTY: boolean;
+    env: Record<string, string | undefined>;
+}
+export interface RunCliOptions {
+    terminalContext?: CliTerminalContext;
+    runCheckImpl?: typeof runCheck;
+}
+export declare function runCli(args: string[], io?: CliIo, options?: RunCliOptions): Promise<number>;

package/dist/run-cli.js

@@ -0,0 +1,87 @@
+import { writeFile } from "node:fs/promises";
+import { runCheck } from "./index.js";
+import { renderJsonReport } from "./reporting/render-json-report.js";
+import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
+import { renderTextReport } from "./reporting/render-text-report.js";
+import { createLiveStatusRenderer } from "./terminal/live-status-renderer.js";
+import { determineOutputPolicy } from "./terminal/output-policy.js";
+import { getSpinner } from "./terminal/spinner-registry.js";
+const defaultIo = {
+    writeStdout(message) {
+        process.stdout.write(`${message}\n`);
+    },
+    writeStderr(message) {
+        process.stderr.write(`${message}\n`);
+    }
+};
+function printUsage(io) {
+    io.writeStderr("Usage: codex-plugin-doctor check <path> [--json|--markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]");
+}
+export async function runCli(args, io = defaultIo, options = {}) {
+    const [command, maybePath, ...remainingArgs] = args;
+    if (command !== "check") {
+        printUsage(io);
+        return 2;
+    }
+    const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+    const normalizedFlags = maybePath && maybePath.startsWith("--")
+        ? [maybePath, ...remainingArgs]
+        : remainingArgs;
+    const jsonOutput = normalizedFlags.includes("--json");
+    const markdownOutput = normalizedFlags.includes("--markdown");
+    const runtimeProbeEnabled = normalizedFlags.includes("--runtime");
+    const verboseRuntime = normalizedFlags.includes("--verbose-runtime");
+    const noAnimations = normalizedFlags.includes("--no-animations");
+    const asciiMode = normalizedFlags.includes("--ascii");
+    const outputIndex = normalizedFlags.indexOf("--output");
+    const outputPath = outputIndex === -1 ? null : normalizedFlags[outputIndex + 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
+    };
+    const outputPolicy = determineOutputPolicy({
+        jsonOutput,
+        markdownOutput,
+        outputPath,
+        noAnimations,
+        asciiMode,
+        stdoutIsTTY: terminalContext.stdoutIsTTY,
+        stderrIsTTY: terminalContext.stderrIsTTY,
+        env: terminalContext.env
+    });
+    const runCheckImpl = options.runCheckImpl ?? runCheck;
+    const renderer = outputPolicy.interactive
+        && !verboseRuntime
+        ? createLiveStatusRenderer(io, getSpinner(outputPolicy.style === "ascii" ? "ascii" : "doctor"))
+        : null;
+    renderer?.start("Validating package");
+    const result = await runCheckImpl(targetPath, {
+        runtime: runtimeProbeEnabled,
+        runtimeTranscript: runtimeProbeEnabled && verboseRuntime
+            ? (line) => io.writeStderr(line)
+            : undefined
+    });
+    if (renderer) {
+        if (result.status === "fail") {
+            renderer.stopFailure("Validation failed");
+        }
+        else {
+            renderer.stopSuccess("Validation complete");
+        }
+    }
+    const report = markdownOutput
+        ? buildMarkdownReport(result, { runtimeProbeEnabled })
+        : jsonOutput
+            ? renderJsonReport(result, { runtimeProbeEnabled })
+            : renderTextReport(result, { ascii: outputPolicy.style === "ascii" });
+    if (outputPath) {
+        await writeFile(outputPath, report, "utf8");
+    }
+    io.writeStdout(report);
+    return result.exitCode;
+}

package/dist/terminal/live-status-renderer.d.ts

@@ -0,0 +1,9 @@
+import type { CliIo } from "../run-cli.js";
+import type { SpinnerDefinition } from "./spinner-registry.js";
+export interface LiveStatusRenderer {
+    start(label: string): void;
+    update(label: string): void;
+    stopSuccess(label: string): void;
+    stopFailure(label: string): void;
+}
+export declare function createLiveStatusRenderer(io: Pick<CliIo, "writeStderr">, spinner: SpinnerDefinition): LiveStatusRenderer;

package/dist/terminal/live-status-renderer.js

@@ -0,0 +1,38 @@
+function clearLine() {
+    return "\r\x1B[2K";
+}
+export function createLiveStatusRenderer(io, spinner) {
+    let frameIndex = 0;
+    let currentLabel = "";
+    let timer = null;
+    const renderFrame = () => {
+        const frame = spinner.frames[frameIndex % spinner.frames.length];
+        frameIndex += 1;
+        io.writeStderr(`${clearLine()}${frame} ${currentLabel}`);
+    };
+    const stopTimer = () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+    };
+    return {
+        start(label) {
+            currentLabel = label;
+            renderFrame();
+            timer = setInterval(renderFrame, spinner.intervalMs);
+        },
+        update(label) {
+            currentLabel = label;
+            renderFrame();
+        },
+        stopSuccess(label) {
+            stopTimer();
+            io.writeStderr(`${clearLine()}✔ ${label}\n`);
+        },
+        stopFailure(label) {
+            stopTimer();
+            io.writeStderr(`${clearLine()}✖ ${label}\n`);
+        }
+    };
+}

package/dist/terminal/output-policy.d.ts

@@ -0,0 +1,16 @@
+export interface OutputPolicyInput {
+    jsonOutput: boolean;
+    markdownOutput: boolean;
+    outputPath: string | null;
+    noAnimations: boolean;
+    asciiMode: boolean;
+    stdoutIsTTY: boolean;
+    stderrIsTTY: boolean;
+    env: Record<string, string | undefined>;
+}
+export interface OutputPolicy {
+    interactive: boolean;
+    style: "unicode" | "ascii";
+    reason: "tty" | "machine_output" | "redirected_output" | "ci" | "dumb_terminal" | "non_tty" | "disabled_by_flag";
+}
+export declare function determineOutputPolicy(input: OutputPolicyInput): OutputPolicy;

package/dist/terminal/output-policy.js

@@ -0,0 +1,50 @@
+export function determineOutputPolicy(input) {
+    const style = input.asciiMode ? "ascii" : "unicode";
+    if (input.jsonOutput || input.markdownOutput) {
+        return {
+            interactive: false,
+            style,
+            reason: "machine_output"
+        };
+    }
+    if (input.outputPath) {
+        return {
+            interactive: false,
+            style,
+            reason: "redirected_output"
+        };
+    }
+    if (input.env.CI) {
+        return {
+            interactive: false,
+            style,
+            reason: "ci"
+        };
+    }
+    if (input.env.TERM === "dumb") {
+        return {
+            interactive: false,
+            style: "ascii",
+            reason: "dumb_terminal"
+        };
+    }
+    if (!input.stdoutIsTTY || !input.stderrIsTTY) {
+        return {
+            interactive: false,
+            style,
+            reason: "non_tty"
+        };
+    }
+    if (input.noAnimations) {
+        return {
+            interactive: false,
+            style,
+            reason: "disabled_by_flag"
+        };
+    }
+    return {
+        interactive: true,
+        style,
+        reason: "tty"
+    };
+}

package/dist/terminal/spinner-registry.d.ts

@@ -0,0 +1,8 @@
+export interface SpinnerDefinition {
+    name: string;
+    frames: string[];
+    intervalMs: number;
+}
+declare const spinners: Record<string, SpinnerDefinition>;
+export declare function getSpinner(name: keyof typeof spinners): SpinnerDefinition;
+export {};

package/dist/terminal/spinner-registry.js

@@ -0,0 +1,30 @@
+const spinners = {
+    braille: {
+        name: "braille",
+        frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+        intervalMs: 80
+    },
+    doctor: {
+        name: "doctor",
+        frames: ["⠑", "⠒", "⠲", "⠴", "⠦", "⠖", "⠒", "⠐"],
+        intervalMs: 75
+    },
+    dots: {
+        name: "dots",
+        frames: ["⠁", "⠂", "⠄", "⠂"],
+        intervalMs: 90
+    },
+    scan: {
+        name: "scan",
+        frames: ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█", "▇", "▆", "▅", "▄", "▃", "▂"],
+        intervalMs: 70
+    },
+    ascii: {
+        name: "ascii",
+        frames: ["-", "\\", "|", "/"],
+        intervalMs: 90
+    }
+};
+export function getSpinner(name) {
+    return spinners[name];
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "codex-plugin-doctor",
+  "version": "0.1.1",
+  "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "codex-plugin-doctor": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "generate-validation-artifacts": "node scripts/generate-validation-artifacts.mjs",
+    "prepare-rc": "tsx scripts/prepare-release-candidate.ts",
+    "prepare-release": "npm test && npm run build && npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "packageManager": "npm@11.11.1",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "codex",
+    "mcp",
+    "plugin",
+    "skills",
+    "validation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Esquetta/CodexPluginDoctor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Esquetta/CodexPluginDoctor/issues"
+  },
+  "homepage": "https://github.com/Esquetta/CodexPluginDoctor#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.1",
+    "tsx": "^4.20.4",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}