codex-plugin-doctor 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,9 @@
 # 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.
 
@@ -72,6 +75,7 @@ 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
 ```
 
@@ -156,12 +160,18 @@ 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 .
@@ -176,7 +186,13 @@ codex-plugin-doctor check . --config .codex-doctor.json
 codex-plugin-doctor check . --json --runtime --verbose-runtime
 ```
 
-`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.
+`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:
 
@@ -262,6 +278,9 @@ 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)

package/dist/compatibility/apply-install-preview.d.ts

@@ -0,0 +1,15 @@
+export interface McpInstallPreviewLike {
+    targetPath: string;
+    configPath: string;
+    snippet: {
+        mcpServers: Record<string, unknown>;
+    };
+}
+export interface ApplyInstallResult {
+    client: string;
+    configPath: string;
+    backupPath: string | null;
+    appliedServers: string[];
+}
+export declare function applyInstallPreview(client: string, preview: McpInstallPreviewLike): Promise<ApplyInstallResult>;
+export declare function renderApplyInstallResult(result: ApplyInstallResult): string;

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.d.ts

@@ -16,5 +16,6 @@ export interface CompatibilityEnvironment {
 }
 export declare function readMcpConfigPath(targetPath: string): Promise<string | null>;
 export declare function getClaudeDesktopConfigPath(environment?: CompatibilityEnvironment): string | null;
+export declare function getCursorMcpConfigPath(targetPath: string, environment?: CompatibilityEnvironment): Promise<string>;
 export declare function buildCompatibilityMatrix(targetPath: string, environment?: CompatibilityEnvironment): Promise<CompatibilityMatrix>;
 export declare function matrixExitCode(matrix: CompatibilityMatrix): 0 | 1;

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)
@@ -121,6 +122,18 @@ export function getClaudeDesktopConfigPath(environment = {}) {
     }
     return null;
 }
+function getHomeDirectory(environment = {}) {
+    const env = environment.env ?? process.env;
+    return env.USERPROFILE ?? env.HOME ?? environment.homedir ?? os.homedir();
+}
+export async function getCursorMcpConfigPath(targetPath, environment = {}) {
+    const rootPath = path.resolve(targetPath);
+    const projectConfigPath = path.join(rootPath, ".cursor", "mcp.json");
+    if (await fileExists(projectConfigPath)) {
+        return projectConfigPath;
+    }
+    return path.join(getHomeDirectory(environment), ".cursor", "mcp.json");
+}
 async function checkClaudeDesktop(targetPath, genericMcpResult, environment = {}) {
     if (genericMcpResult.status !== "pass") {
         return {
@@ -154,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 ||
@@ -201,10 +214,83 @@ async function checkClaudeDesktop(targetPath, genericMcpResult, environment = {}
         };
     }
 }
+async function checkCursor(targetPath, genericMcpResult, environment = {}) {
+    if (genericMcpResult.status !== "pass") {
+        return {
+            client: "Cursor",
+            status: "skipped",
+            summary: "No valid MCP package config is available for Cursor.",
+            details: ["Add a valid `.mcp.json` with a non-empty `mcpServers` object first."]
+        };
+    }
+    const configPath = await getCursorMcpConfigPath(targetPath, environment);
+    if (!(await fileExists(configPath))) {
+        const configDirectory = path.dirname(configPath);
+        return {
+            client: "Cursor",
+            status: await directoryExists(configDirectory) ? "pass" : "warn",
+            summary: await directoryExists(configDirectory)
+                ? "Cursor MCP config directory exists and a config file can be created."
+                : "Cursor was not detected on this machine.",
+            details: [
+                configPath,
+                "Cursor supports project `.cursor/mcp.json` and global `~/.cursor/mcp.json` MCP configs."
+            ]
+        };
+    }
+    try {
+        const parsed = await readJsonFile(configPath);
+        const servers = parsed.mcpServers;
+        if (servers !== undefined && (typeof servers !== "object" ||
+            servers === null ||
+            Array.isArray(servers))) {
+            return {
+                client: "Cursor",
+                status: "fail",
+                summary: "Cursor MCP config has an invalid `mcpServers` shape.",
+                details: [configPath, "`mcpServers` must be an object before this package can be added safely."]
+            };
+        }
+        const packageServerNames = await readMcpServerNames(targetPath);
+        const existingServerNames = typeof servers === "object" && servers !== null
+            ? Object.keys(servers)
+            : [];
+        const duplicateServerNames = packageServerNames.filter((serverName) => existingServerNames.includes(serverName));
+        if (duplicateServerNames.length > 0) {
+            return {
+                client: "Cursor",
+                status: "warn",
+                summary: "Cursor already has MCP server names from this package.",
+                details: [
+                    configPath,
+                    ...duplicateServerNames.map((serverName) => `Duplicate server: ${serverName}`)
+                ]
+            };
+        }
+        return {
+            client: "Cursor",
+            status: "pass",
+            summary: "Cursor global MCP config is valid and this package can be added.",
+            details: [
+                configPath,
+                `Source package: ${path.resolve(targetPath)}`
+            ]
+        };
+    }
+    catch {
+        return {
+            client: "Cursor",
+            status: "fail",
+            summary: "Cursor MCP config is not valid JSON.",
+            details: [configPath, "Repair the local Cursor MCP config before adding new MCP servers."]
+        };
+    }
+}
 export async function buildCompatibilityMatrix(targetPath, environment = {}) {
     const rootPath = path.resolve(targetPath);
     const genericMcpResult = await checkGenericMcp(rootPath);
     const claudeDesktopResult = await checkClaudeDesktop(rootPath, genericMcpResult, environment);
+    const cursorResult = await checkCursor(rootPath, genericMcpResult, environment);
     const codexResult = await validatePlugin(rootPath);
     const codexStatus = statusFromCheckResult(codexResult);
     const codexCompatibility = !await hasCodexManifest(rootPath)
@@ -227,12 +313,7 @@ export async function buildCompatibilityMatrix(targetPath, environment = {}) {
         codexCompatibility,
         genericMcpResult,
         claudeDesktopResult,
-        {
-            client: "Cursor",
-            status: "skipped",
-            summary: "Client-specific package adapter is not implemented yet.",
-            details: ["Planned adapter after generic MCP compatibility is stable."]
-        }
+        cursorResult
     ];
     return {
         targetPath: rootPath,

package/dist/compatibility/cursor-install-preview.d.ts

@@ -0,0 +1,10 @@
+import { type CompatibilityEnvironment } from "./compatibility-matrix.js";
+export interface CursorInstallPreview {
+    targetPath: string;
+    configPath: string;
+    snippet: {
+        mcpServers: Record<string, unknown>;
+    };
+}
+export declare function buildCursorInstallPreview(targetPath: string, environment?: CompatibilityEnvironment): Promise<CursorInstallPreview>;
+export declare function renderCursorInstallPreview(preview: CursorInstallPreview): string;

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

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { getCursorMcpConfigPath, readMcpConfigPath } from "./compatibility-matrix.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRelativeLocalPath(value) {
+    return value.startsWith("./") ||
+        value.startsWith("../") ||
+        value.startsWith(".\\") ||
+        value.startsWith("..\\");
+}
+function normalizeLocalPathArgument(value, rootPath) {
+    return typeof value === "string" && isRelativeLocalPath(value)
+        ? path.resolve(rootPath, value)
+        : value;
+}
+function normalizeServerConfig(serverConfig, rootPath) {
+    if (!isRecord(serverConfig)) {
+        return serverConfig;
+    }
+    const normalized = { ...serverConfig };
+    if (typeof normalized.command === "string" && isRelativeLocalPath(normalized.command)) {
+        normalized.command = path.resolve(rootPath, normalized.command);
+    }
+    if (Array.isArray(normalized.args)) {
+        normalized.args = normalized.args.map((argument) => normalizeLocalPathArgument(argument, rootPath));
+    }
+    return normalized;
+}
+export async function buildCursorInstallPreview(targetPath, environment = {}) {
+    const rootPath = path.resolve(targetPath);
+    const mcpConfigPath = await readMcpConfigPath(rootPath);
+    if (!mcpConfigPath) {
+        throw new Error("No MCP config found for install preview.");
+    }
+    const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
+    const servers = parsed.mcpServers;
+    if (!isRecord(servers) || Object.keys(servers).length === 0) {
+        throw new Error("MCP config does not contain a non-empty `mcpServers` object.");
+    }
+    return {
+        targetPath: rootPath,
+        configPath: await getCursorMcpConfigPath(rootPath, environment),
+        snippet: {
+            mcpServers: Object.fromEntries(Object.entries(servers).map(([serverName, serverConfig]) => [
+                serverName,
+                normalizeServerConfig(serverConfig, rootPath)
+            ]))
+        }
+    };
+}
+export function renderCursorInstallPreview(preview) {
+    return [
+        "Cursor Install Preview",
+        "======================",
+        `Target: ${preview.targetPath}`,
+        `Config: ${preview.configPath}`,
+        "",
+        "Add or merge this snippet into `mcp.json`:",
+        JSON.stringify(preview.snippet, null, 2),
+        "",
+        "No files were modified."
+    ].join("\n");
+}

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-compatibility-scorecard.d.ts

@@ -0,0 +1,2 @@
+import type { CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+export declare function renderCompatibilityScorecard(matrix: CompatibilityMatrix): string;

package/dist/reporting/render-compatibility-scorecard.js

@@ -0,0 +1,21 @@
+function scoreForStatus(status) {
+    if (status === "pass") {
+        return 100;
+    }
+    if (status === "warn") {
+        return 70;
+    }
+    return 0;
+}
+export function renderCompatibilityScorecard(matrix) {
+    const lines = [
+        "Compatibility Scorecard",
+        "=======================",
+        `Target: ${matrix.targetPath}`,
+        ""
+    ];
+    for (const result of matrix.results) {
+        lines.push(`${result.client}: ${scoreForStatus(result.status)} (${result.status.toUpperCase()})`);
+    }
+    return lines.join("\n");
+}

package/dist/run-cli.js

@@ -1,11 +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 { renderCompatibilityScorecard } from "./reporting/render-compatibility-scorecard.js";
 import { renderCompatibilityReport } from "./reporting/render-compatibility-report.js";
 import { renderJsonReport } from "./reporting/render-json-report.js";
 import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
@@ -26,7 +31,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] [--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] [--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 = [
@@ -64,6 +69,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") {
@@ -95,6 +116,16 @@ 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
+        });
+        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);
@@ -114,7 +145,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
             ? [maybePath, ...remainingArgs]
             : remainingArgs;
         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");
@@ -127,16 +161,34 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStderr("Missing path after --output.");
             return 2;
         }
-        if (installPreview && clientFilter?.toLowerCase() !== "claude-desktop") {
-            io.writeStderr("--install-preview requires --client claude-desktop.");
+        if ((installPreview || applyInstall) &&
+            clientFilter?.toLowerCase() !== "claude-desktop" &&
+            clientFilter?.toLowerCase() !== "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 (applyInstall && !backupInstall) {
+            io.writeStderr("--apply requires --backup.");
             return 2;
         }
-        if (installPreview) {
+        if (installPreview || applyInstall) {
             try {
-                const preview = await buildClaudeDesktopInstallPreview(targetPath, {
-                    env: terminalContext.env
-                });
-                const report = renderClaudeDesktopInstallPreview(preview);
+                const preview = clientFilter?.toLowerCase() === "cursor"
+                    ? await buildCursorInstallPreview(targetPath, {
+                        env: terminalContext.env
+                    })
+                    : await buildClaudeDesktopInstallPreview(targetPath, {
+                        env: terminalContext.env
+                    });
+                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");
                 }
@@ -162,7 +214,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         const report = jsonOutput
             ? JSON.stringify({ schemaVersion: "1.0.0", ...matrix }, null, 2)
-            : renderCompatibilityReport(matrix);
+            : scorecardOutput
+                ? renderCompatibilityScorecard(matrix)
+                : renderCompatibilityReport(matrix);
         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"]
+    }
+  }
+}
+

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

@@ -0,0 +1,237 @@
+import readline from "node:readline";
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  crlfDelay: Infinity
+});
+
+rl.on("line", (line) => {
+  const message = JSON.parse(line);
+  const cursor = message.params?.cursor;
+
+  if (message.method === "initialize") {
+    process.stdout.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          protocolVersion: "2025-11-25",
+          capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {}
+          },
+          serverInfo: {
+            name: "doctor-runtime-server",
+            version: "1.0.0"
+          }
+        }
+      })}\n`
+    );
+    return;
+  }
+
+  if (message.method === "tools/list") {
+    process.stdout.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: message.id,
+        result:
+          cursor === "tools-page-2"
+            ? {
+                tools: [
+                  {
+                    name: "format_status",
+                    description: "Return a formatted health status.",
+                    inputSchema: {
+                      type: "object",
+                      properties: {},
+                      required: []
+                    }
+                  }
+                ]
+              }
+            : {
+                tools: [
+                  {
+                    name: "ping",
+                    description: "Return a healthcheck response.",
+                    inputSchema: {
+                      type: "object",
+                      properties: {},
+                      required: []
+                    }
+                  }
+                ],
+                nextCursor: "tools-page-2"
+              }
+      })}\n`
+    );
+    return;
+  }
+
+  if (message.method === "tools/call") {
+    process.stdout.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          content: [
+            {
+              type: "text",
+              text: "doctor-runtime-ok"
+            }
+          ]
+        }
+      })}\n`
+    );
+    return;
+  }
+
+  if (message.method === "resources/list") {
+    process.stdout.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: message.id,
+        result:
+          cursor === "resources-page-2"
+            ? {
+                resources: [
+                  {
+                    name: "workspace-license",
+                    uri: "file:///workspace/LICENSE"
+                  }
+                ]
+              }
+            : {
+                resources: [
+                  {
+                    name: "workspace-readme",
+                    uri: "file:///workspace/README.md"
+                  }
+                ],
+                nextCursor: "resources-page-2"
+              }
+      })}\n`
+    );
+    return;
+  }
+
+  if (message.method === "resources/read") {
+    process.stdout.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          contents: [
+            {
+              uri: "file:///workspace/README.md",
+              text: "# Workspace README"
+            }
+          ]
+        }
+      })}\n`
+    );
+    return;
+  }
+
+  if (message.method === "resources/templates/list") {
+    process.stdout.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: message.id,
+        result:
+          cursor === "templates-page-2"
+            ? {
+                resourceTemplates: [
+                  {
+                    name: "log",
+                    uriTemplate: "file:///workspace/logs/{name}.log"
+                  }
+                ]
+              }
+            : {
+                resourceTemplates: [
+                  {
+                    name: "doc",
+                    uriTemplate: "file:///workspace/docs/{name}.md"
+                  }
+                ],
+                nextCursor: "templates-page-2"
+              }
+      })}\n`
+    );
+    return;
+  }
+
+  if (message.method === "prompts/list") {
+    process.stdout.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: message.id,
+        result:
+          cursor === "prompts-page-2"
+            ? {
+                prompts: [
+                  {
+                    name: "summary",
+                    description: "Summarize the current change."
+                  }
+                ]
+              }
+            : {
+                prompts: [
+                  {
+                    name: "code_review",
+                    description: "Review code for bugs.",
+                    arguments: [
+                      {
+                        name: "diff",
+                        required: true
+                      }
+                    ]
+                  }
+                ],
+                nextCursor: "prompts-page-2"
+              }
+      })}\n`
+    );
+    return;
+  }
+
+  if (message.method === "prompts/get") {
+    if (message.params?.arguments?.diff !== "codex-plugin-doctor-probe") {
+      process.stdout.write(
+        `${JSON.stringify({
+          jsonrpc: "2.0",
+          id: message.id,
+          error: {
+            code: -32602,
+            message: "Missing required diff argument"
+          }
+        })}\n`
+      );
+      return;
+    }
+
+    process.stdout.write(
+      `${JSON.stringify({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          description: "Prompt for code review",
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: "Review this diff for bugs."
+              }
+            }
+          ]
+        }
+      })}\n`
+    );
+  }
+});
+

package/examples/codex-doctor-runtime/skills/context-check/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: context-check
+description: Validate the current repository context before taking action.
+---
+
+Use this skill when you need to confirm repository structure, expected files, and project readiness before deeper work begins.
+

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

@@ -0,0 +1,7 @@
+{
+  "name": "codex-doctor-starter",
+  "version": "1.0.0",
+  "description": "Minimal Codex Doctor sample plugin for local validation.",
+  "skills": "./skills/"
+}
+

package/examples/codex-doctor-starter/skills/repo-scan/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: repo-scan
+description: Scan the repository and summarize the main components.
+---
+
+Use this skill when you need a quick high-level map of the current repository.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,7 +16,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "examples"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",