codex-plugin-doctor 0.1.5 → 0.2.0

package/README.md

@@ -157,6 +157,11 @@ Run these from a Codex plugin package root:
 ```bash
 codex-plugin-doctor --version
 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 . --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
@@ -202,7 +207,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: Esquetta/CodexPluginDoctor@v0.1.4
+      - uses: Esquetta/CodexPluginDoctor@v0.2.0
         with:
           path: .
           runtime: "false"

package/dist/compatibility/compatibility-matrix.d.ts

@@ -0,0 +1,13 @@
+export type CompatibilityStatus = "pass" | "warn" | "fail" | "skipped";
+export interface CompatibilityResult {
+    client: string;
+    status: CompatibilityStatus;
+    summary: string;
+    details: string[];
+}
+export interface CompatibilityMatrix {
+    targetPath: string;
+    results: CompatibilityResult[];
+}
+export declare function buildCompatibilityMatrix(targetPath: string): Promise<CompatibilityMatrix>;
+export declare function matrixExitCode(matrix: CompatibilityMatrix): 0 | 1;

package/dist/compatibility/compatibility-matrix.js

@@ -0,0 +1,129 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { validatePlugin } from "../core/validate-plugin.js";
+async function fileExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function statusFromCheckResult(result) {
+    if (result.status === "fail") {
+        return "fail";
+    }
+    if (result.status === "warn") {
+        return "warn";
+    }
+    return "pass";
+}
+async function readMcpConfigPath(targetPath) {
+    const rootPath = path.resolve(targetPath);
+    const directMcpPath = path.join(rootPath, ".mcp.json");
+    if (await fileExists(directMcpPath)) {
+        return directMcpPath;
+    }
+    const manifestPath = path.join(rootPath, ".codex-plugin", "plugin.json");
+    if (!(await fileExists(manifestPath))) {
+        return null;
+    }
+    try {
+        const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+        return typeof manifest.mcpServers === "string"
+            ? path.resolve(rootPath, manifest.mcpServers)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function hasCodexManifest(targetPath) {
+    return fileExists(path.join(path.resolve(targetPath), ".codex-plugin", "plugin.json"));
+}
+async function checkGenericMcp(targetPath) {
+    const mcpConfigPath = await readMcpConfigPath(targetPath);
+    if (!mcpConfigPath || !(await fileExists(mcpConfigPath))) {
+        return {
+            client: "Generic MCP",
+            status: "skipped",
+            summary: "No MCP config found.",
+            details: ["Expected `.mcp.json` or manifest `mcpServers` reference."]
+        };
+    }
+    try {
+        const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
+        const servers = parsed.mcpServers;
+        if (typeof servers !== "object" ||
+            servers === null ||
+            Array.isArray(servers) ||
+            Object.keys(servers).length === 0) {
+            return {
+                client: "Generic MCP",
+                status: "fail",
+                summary: "MCP config does not contain a non-empty `mcpServers` object.",
+                details: [mcpConfigPath]
+            };
+        }
+        return {
+            client: "Generic MCP",
+            status: "pass",
+            summary: "MCP server config is valid.",
+            details: [mcpConfigPath]
+        };
+    }
+    catch {
+        return {
+            client: "Generic MCP",
+            status: "fail",
+            summary: "MCP config is not valid JSON.",
+            details: [mcpConfigPath]
+        };
+    }
+}
+export async function buildCompatibilityMatrix(targetPath) {
+    const rootPath = path.resolve(targetPath);
+    const genericMcpResult = await checkGenericMcp(rootPath);
+    const codexResult = await validatePlugin(rootPath);
+    const codexStatus = statusFromCheckResult(codexResult);
+    const codexCompatibility = !await hasCodexManifest(rootPath)
+        && genericMcpResult.status === "pass"
+        ? {
+            client: "Codex",
+            status: "skipped",
+            summary: "No Codex plugin manifest found; treating target as a standalone MCP package.",
+            details: ["Add `.codex-plugin/plugin.json` if this package should be installable as a Codex plugin."]
+        }
+        : {
+            client: "Codex",
+            status: codexStatus,
+            summary: codexStatus === "pass"
+                ? "Codex plugin package validation passed."
+                : "Codex plugin package validation produced findings.",
+            details: codexResult.findings.map((finding) => finding.id)
+        };
+    const results = [
+        codexCompatibility,
+        genericMcpResult,
+        {
+            client: "Claude Desktop",
+            status: "skipped",
+            summary: "Client-specific package adapter is not implemented yet.",
+            details: ["Planned adapter after generic MCP compatibility is stable."]
+        },
+        {
+            client: "Cursor",
+            status: "skipped",
+            summary: "Client-specific package adapter is not implemented yet.",
+            details: ["Planned adapter after generic MCP compatibility is stable."]
+        }
+    ];
+    return {
+        targetPath: rootPath,
+        results
+    };
+}
+export function matrixExitCode(matrix) {
+    return matrix.results.some((result) => result.status === "fail") ? 1 : 0;
+}

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

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

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

@@ -0,0 +1,18 @@
+function statusLabel(status) {
+    return status.toUpperCase();
+}
+export function renderCompatibilityReport(matrix) {
+    const lines = [
+        "Compatibility Matrix",
+        "====================",
+        `Target: ${matrix.targetPath}`,
+        ""
+    ];
+    for (const result of matrix.results) {
+        lines.push(`${result.client}: ${statusLabel(result.status)} - ${result.summary}`);
+        for (const detail of result.details) {
+            lines.push(`  - ${detail}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/run-cli.js

@@ -1,9 +1,11 @@
 import { writeFile } from "node:fs/promises";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
+import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.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 { renderCompatibilityReport } from "./reporting/render-compatibility-report.js";
 import { renderJsonReport } from "./reporting/render-json-report.js";
 import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
 import { renderRuleExplanation } from "./reporting/render-rule-explanation.js";
@@ -23,7 +25,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 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> [--json] [--output <path>]\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -42,6 +44,25 @@ function renderInstalledPlugins(plugins) {
     }
     return lines.join("\n");
 }
+const compatibilityClientAliases = {
+    codex: "Codex",
+    "generic-mcp": "Generic MCP",
+    generic: "Generic MCP",
+    mcp: "Generic MCP",
+    "claude-desktop": "Claude Desktop",
+    claude: "Claude Desktop",
+    cursor: "Cursor"
+};
+function filterCompatibilityMatrix(matrix, clientFilter) {
+    const client = compatibilityClientAliases[clientFilter.toLowerCase()];
+    if (!client) {
+        return null;
+    }
+    return {
+        ...matrix,
+        results: matrix.results.filter((result) => result.client === client)
+    };
+}
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
     if (command === "--version" || command === "-v" || command === "version") {
@@ -86,6 +107,42 @@ export async function runCli(args, io = defaultIo, options = {}) {
         ].join("\n"));
         return 0;
     }
+    if (command === "compat") {
+        const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+        const compatFlags = maybePath && maybePath.startsWith("--")
+            ? [maybePath, ...remainingArgs]
+            : remainingArgs;
+        const jsonOutput = compatFlags.includes("--json");
+        const clientIndex = compatFlags.indexOf("--client");
+        const clientFilter = clientIndex === -1 ? null : compatFlags[clientIndex + 1];
+        const outputIndex = compatFlags.indexOf("--output");
+        const outputPath = outputIndex === -1 ? null : compatFlags[outputIndex + 1];
+        if (clientIndex !== -1 && (!clientFilter || clientFilter.startsWith("--"))) {
+            io.writeStderr("Missing client after --client.");
+            return 2;
+        }
+        if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+            io.writeStderr("Missing path after --output.");
+            return 2;
+        }
+        let matrix = await buildCompatibilityMatrix(targetPath);
+        if (clientFilter) {
+            const filteredMatrix = filterCompatibilityMatrix(matrix, clientFilter);
+            if (!filteredMatrix) {
+                io.writeStderr(`Unknown compatibility client: ${clientFilter}`);
+                return 2;
+            }
+            matrix = filteredMatrix;
+        }
+        const report = jsonOutput
+            ? JSON.stringify({ schemaVersion: "1.0.0", ...matrix }, null, 2)
+            : renderCompatibilityReport(matrix);
+        if (outputPath) {
+            await writeFile(outputPath, report, "utf8");
+        }
+        io.writeStdout(report);
+        return matrixExitCode(matrix);
+    }
     if (command !== "check") {
         printUsage(io);
         return 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",