codex-plugin-doctor 0.3.0 → 0.5.0

package/dist/compatibility/apply-install-preview.js

@@ -0,0 +1,71 @@
+import { copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { readJsonFile } from "../core/read-json-file.js";
+async function fileExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function buildBackupPath(configPath) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${configPath}.${timestamp}.bak`;
+}
+export async function applyInstallPreview(client, preview) {
+    await mkdir(path.dirname(preview.configPath), { recursive: true });
+    const configExists = await fileExists(preview.configPath);
+    const currentConfig = configExists
+        ? await readJsonFile(preview.configPath)
+        : {};
+    if (!isRecord(currentConfig)) {
+        throw new Error(`${client} MCP config must be a JSON object.`);
+    }
+    const currentServers = currentConfig.mcpServers;
+    if (currentServers !== undefined && !isRecord(currentServers)) {
+        throw new Error(`${client} MCP config has an invalid \`mcpServers\` shape.`);
+    }
+    const existingServers = currentServers ?? {};
+    const incomingServers = preview.snippet.mcpServers;
+    const duplicateServers = Object.keys(incomingServers).filter((serverName) => Object.prototype.hasOwnProperty.call(existingServers, serverName));
+    if (duplicateServers.length > 0) {
+        throw new Error(`Refusing to overwrite existing MCP server names: ${duplicateServers.join(", ")}`);
+    }
+    const backupPath = configExists ? buildBackupPath(preview.configPath) : null;
+    if (backupPath) {
+        await copyFile(preview.configPath, backupPath);
+    }
+    const nextConfig = {
+        ...currentConfig,
+        mcpServers: {
+            ...existingServers,
+            ...incomingServers
+        }
+    };
+    await writeFile(preview.configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+    return {
+        client,
+        configPath: preview.configPath,
+        backupPath,
+        appliedServers: Object.keys(incomingServers)
+    };
+}
+export function renderApplyInstallResult(result) {
+    const lines = [
+        `Applied ${result.client} MCP config`,
+        "==============================",
+        `Config: ${result.configPath}`,
+        `Backup: ${result.backupPath ?? "No existing config file was present."}`,
+        "",
+        "Applied servers:"
+    ];
+    for (const serverName of result.appliedServers) {
+        lines.push(`- ${serverName}`);
+    }
+    return lines.join("\n");
+}

package/dist/compatibility/compatibility-matrix.js

@@ -1,7 +1,8 @@
-import { readFile, stat } from "node:fs/promises";
+import { stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { validatePlugin } from "../core/validate-plugin.js";
+import { readJsonFile } from "../core/read-json-file.js";
 async function fileExists(targetPath) {
     try {
         const details = await stat(targetPath);
@@ -40,7 +41,7 @@ export async function readMcpConfigPath(targetPath) {
         return null;
     }
     try {
-        const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+        const manifest = await readJsonFile(manifestPath);
         return typeof manifest.mcpServers === "string"
             ? path.resolve(rootPath, manifest.mcpServers)
             : null;
@@ -63,7 +64,7 @@ async function checkGenericMcp(targetPath) {
         };
     }
     try {
-        const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
+        const parsed = await readJsonFile(mcpConfigPath);
         const servers = parsed.mcpServers;
         if (typeof servers !== "object" ||
             servers === null ||
@@ -98,7 +99,7 @@ async function readMcpServerNames(targetPath) {
         return [];
     }
     try {
-        const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
+        const parsed = await readJsonFile(mcpConfigPath);
         const servers = parsed.mcpServers;
         return typeof servers === "object" && servers !== null && !Array.isArray(servers)
             ? Object.keys(servers)
@@ -166,7 +167,7 @@ async function checkClaudeDesktop(targetPath, genericMcpResult, environment = {}
         };
     }
     try {
-        const parsed = JSON.parse(await readFile(configPath, "utf8"));
+        const parsed = await readJsonFile(configPath);
         const servers = parsed.mcpServers;
         if (servers !== undefined && (typeof servers !== "object" ||
             servers === null ||
@@ -238,7 +239,7 @@ async function checkCursor(targetPath, genericMcpResult, environment = {}) {
         };
     }
     try {
-        const parsed = JSON.parse(await readFile(configPath, "utf8"));
+        const parsed = await readJsonFile(configPath);
         const servers = parsed.mcpServers;
         if (servers !== undefined && (typeof servers !== "object" ||
             servers === null ||

package/dist/core/read-json-file.d.ts

@@ -0,0 +1,2 @@
+export declare function parseJsonText<T>(text: string): T;
+export declare function readJsonFile<T>(filePath: string): Promise<T>;

package/dist/core/read-json-file.js

@@ -0,0 +1,8 @@
+import { readFile } from "node:fs/promises";
+export function parseJsonText(text) {
+    const normalizedText = text.startsWith("\uFEFF") ? text.slice(1) : text;
+    return JSON.parse(normalizedText);
+}
+export async function readJsonFile(filePath) {
+    return parseJsonText(await readFile(filePath, "utf8"));
+}

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

@@ -1,12 +1,16 @@
 import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
 import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.js";
+import { applyInstallPreview, renderApplyInstallResult } from "./compatibility/apply-install-preview.js";
 import { buildClaudeDesktopInstallPreview, renderClaudeDesktopInstallPreview } from "./compatibility/claude-desktop-install-preview.js";
 import { buildCursorInstallPreview, renderCursorInstallPreview } from "./compatibility/cursor-install-preview.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 { 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";
@@ -28,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]\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 = [
@@ -66,6 +70,22 @@ function filterCompatibilityMatrix(matrix, clientFilter) {
         results: matrix.results.filter((result) => result.client === client)
     };
 }
+function resolveBundledSelfTestTarget() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "examples", "codex-doctor-runtime");
+}
+function renderSelfTestReport(targetPath, validationStatus, findingsCount, compatibilityMatrix) {
+    return [
+        "Codex Plugin Doctor Self-Test",
+        "=============================",
+        `Version: ${packageVersion}`,
+        `Sample: ${targetPath}`,
+        `Validation: ${validationStatus.toUpperCase()}`,
+        "Runtime probes: enabled",
+        `Findings: ${findingsCount}`,
+        "",
+        renderCompatibilityScorecard(compatibilityMatrix)
+    ].join("\n");
+}
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
     if (command === "--version" || command === "-v" || command === "version") {
@@ -75,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({
@@ -97,6 +118,17 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStdout(renderRuleExplanation(rule));
         return 0;
     }
+    if (command === "self-test" || command === "demo") {
+        const targetPath = resolveBundledSelfTestTarget();
+        const runCheckImpl = options.runCheckImpl ?? runCheck;
+        const result = applyDoctorConfig(await runCheckImpl(targetPath, { runtime: true }), await loadDoctorConfig(targetPath));
+        const compatibilityMatrix = await buildCompatibilityMatrix(targetPath, {
+            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;
+    }
     if (command === "init") {
         const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
         const result = await initPluginPackage(targetPath);
@@ -118,6 +150,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const jsonOutput = compatFlags.includes("--json");
         const scorecardOutput = compatFlags.includes("--scorecard");
         const installPreview = compatFlags.includes("--install-preview");
+        const applyInstall = compatFlags.includes("--apply");
+        const backupInstall = compatFlags.includes("--backup");
         const clientIndex = compatFlags.indexOf("--client");
         const clientFilter = clientIndex === -1 ? null : compatFlags[clientIndex + 1];
         const outputIndex = compatFlags.indexOf("--output");
@@ -130,21 +164,36 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStderr("Missing path after --output.");
             return 2;
         }
-        if (installPreview &&
+        if ((installPreview || applyInstall) &&
             clientFilter?.toLowerCase() !== "claude-desktop" &&
             clientFilter?.toLowerCase() !== "cursor") {
-            io.writeStderr("--install-preview requires --client claude-desktop or --client cursor.");
+            io.writeStderr("--install-preview and --apply require --client claude-desktop or --client cursor.");
+            return 2;
+        }
+        if (installPreview && applyInstall) {
+            io.writeStderr("Use either --install-preview or --apply, not both.");
             return 2;
         }
-        if (installPreview) {
+        if (applyInstall && !backupInstall) {
+            io.writeStderr("--apply requires --backup.");
+            return 2;
+        }
+        if (installPreview || applyInstall) {
             try {
-                const report = clientFilter?.toLowerCase() === "cursor"
-                    ? renderCursorInstallPreview(await buildCursorInstallPreview(targetPath, {
-                        env: terminalContext.env
-                    }))
-                    : renderClaudeDesktopInstallPreview(await buildClaudeDesktopInstallPreview(targetPath, {
-                        env: terminalContext.env
-                    }));
+                const preview = clientFilter?.toLowerCase() === "cursor"
+                    ? await buildCursorInstallPreview(targetPath, {
+                        env: terminalContext.env,
+                        platform: terminalContext.platform
+                    })
+                    : await buildClaudeDesktopInstallPreview(targetPath, {
+                        env: terminalContext.env,
+                        platform: terminalContext.platform
+                    });
+                const report = applyInstall
+                    ? renderApplyInstallResult(await applyInstallPreview(clientFilter?.toLowerCase() === "cursor" ? "Cursor" : "Claude Desktop", preview))
+                    : clientFilter?.toLowerCase() === "cursor"
+                        ? renderCursorInstallPreview(preview)
+                        : renderClaudeDesktopInstallPreview(preview);
                 if (outputPath) {
                     await writeFile(outputPath, report, "utf8");
                 }
@@ -158,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);
@@ -198,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");
@@ -216,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,
@@ -290,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/examples/README.md

@@ -0,0 +1,73 @@
+# Examples
+
+This folder contains manual example packs for local testing. Unlike `tests/fixtures`, these examples are meant for humans to run directly against the CLI.
+
+## Example Packs
+
+### `codex-doctor-starter`
+
+Minimal valid Codex plugin package with one skill and no runtime MCP server.
+
+Expected result:
+
+- static validation passes
+- no runtime probing needed
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-starter
+```
+
+### `codex-doctor-runtime`
+
+Valid Codex plugin package with:
+
+- skill metadata
+- `.mcp.json`
+- mock MCP stdio server
+- `tools/list`
+- `tools/call`
+- `resources/list`
+- `resources/read`
+- `resources/templates/list`
+- `prompts/list`
+- `prompts/get`
+
+Expected result:
+
+- static validation passes
+- runtime validation passes
+- runtime scorecard shows all supported runtime capabilities as `pass`
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
+```
+
+### `codex-doctor-risky`
+
+Intentionally flawed package for showing failure output.
+
+Expected result:
+
+- security finding for hard-coded secret
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-risky --ascii
+```
+
+## Suggested Local Flow
+
+```bash
+npm install
+npm run build
+npm link
+codex-plugin-doctor check examples/codex-doctor-starter
+codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
+codex-plugin-doctor check examples/codex-doctor-risky --ascii
+```
+

package/examples/codex-doctor-risky/.codex-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "codex-doctor-risky",
+  "version": "1.0.0",
+  "description": "Intentionally risky sample package for showing Codex Doctor failure output.",
+  "mcpServers": "./.mcp.json"
+}
+

package/examples/codex-doctor-risky/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "dangerServer": {
+      "command": "node",
+      "args": ["./mock-server.js"],
+      "env": {
+        "OPENAI_API_KEY": "sk-live-example-secret-value"
+      }
+    }
+  }
+}
+

package/examples/codex-doctor-risky/mock-server.js

@@ -0,0 +1 @@
+process.stdin.resume();

package/examples/codex-doctor-runtime/.codex-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "codex-doctor-runtime",
+  "version": "1.0.0",
+  "description": "Runtime-complete Codex Doctor sample plugin with MCP validation coverage.",
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json"
+}
+

package/examples/codex-doctor-runtime/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "doctorRuntime": {
+      "command": "node",
+      "args": ["./mock-server.js"]
+    }
+  }
+}
+