codex-plugin-doctor 0.7.0 → 0.8.0

package/README.md

@@ -255,9 +255,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: Esquetta/CodexPluginDoctor@v0.7.0
+      - uses: Esquetta/CodexPluginDoctor@v0.8.0
         with:
-          version: "0.7.0"
+          version: "0.8.0"
           path: .
           runtime: "false"
 ```

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

@@ -18,5 +18,6 @@ export declare function readMcpConfigPath(targetPath: string): Promise<string |
 export declare function getClaudeDesktopConfigPath(environment?: CompatibilityEnvironment): string | null;
 export declare function getCursorMcpConfigPath(targetPath: string, environment?: CompatibilityEnvironment): Promise<string>;
 export declare function getClineMcpConfigPath(environment?: CompatibilityEnvironment): string;
+export declare function getWindsurfMcpConfigPath(environment?: CompatibilityEnvironment): 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

@@ -141,6 +141,9 @@ export function getClineMcpConfigPath(environment = {}) {
         : path.join(getHomeDirectory(environment), ".cline");
     return path.join(clineDirectory, "data", "settings", "cline_mcp_settings.json");
 }
+export function getWindsurfMcpConfigPath(environment = {}) {
+    return path.join(getHomeDirectory(environment), ".codeium", "windsurf", "mcp_config.json");
+}
 async function checkClaudeDesktop(targetPath, genericMcpResult, environment = {}) {
     if (genericMcpResult.status !== "pass") {
         return {
@@ -365,12 +368,85 @@ async function checkCline(targetPath, genericMcpResult, environment = {}) {
         };
     }
 }
+async function checkWindsurf(targetPath, genericMcpResult, environment = {}) {
+    if (genericMcpResult.status !== "pass") {
+        return {
+            client: "Windsurf",
+            status: "skipped",
+            summary: "No valid MCP package config is available for Windsurf.",
+            details: ["Add a valid `.mcp.json` with a non-empty `mcpServers` object first."]
+        };
+    }
+    const configPath = getWindsurfMcpConfigPath(environment);
+    if (!(await fileExists(configPath))) {
+        const configDirectory = path.dirname(configPath);
+        return {
+            client: "Windsurf",
+            status: await directoryExists(configDirectory) ? "pass" : "warn",
+            summary: await directoryExists(configDirectory)
+                ? "Windsurf MCP config directory exists and a config file can be created."
+                : "Windsurf was not detected on this machine.",
+            details: [
+                configPath,
+                "Windsurf stores Cascade MCP servers in `mcp_config.json` under `~/.codeium/windsurf`."
+            ]
+        };
+    }
+    try {
+        const parsed = await readJsonFile(configPath);
+        const servers = parsed.mcpServers;
+        if (servers !== undefined && (typeof servers !== "object" ||
+            servers === null ||
+            Array.isArray(servers))) {
+            return {
+                client: "Windsurf",
+                status: "fail",
+                summary: "Windsurf 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: "Windsurf",
+                status: "warn",
+                summary: "Windsurf already has MCP server names from this package.",
+                details: [
+                    configPath,
+                    ...duplicateServerNames.map((serverName) => `Duplicate server: ${serverName}`)
+                ]
+            };
+        }
+        return {
+            client: "Windsurf",
+            status: "pass",
+            summary: "Windsurf MCP config is valid and this package can be added.",
+            details: [
+                configPath,
+                `Source package: ${path.resolve(targetPath)}`
+            ]
+        };
+    }
+    catch {
+        return {
+            client: "Windsurf",
+            status: "fail",
+            summary: "Windsurf MCP config is not valid JSON.",
+            details: [configPath, "Repair the local Windsurf 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 clineResult = await checkCline(rootPath, genericMcpResult, environment);
+    const windsurfResult = await checkWindsurf(rootPath, genericMcpResult, environment);
     const codexResult = await validatePlugin(rootPath);
     const codexStatus = statusFromCheckResult(codexResult);
     const codexCompatibility = !await hasCodexManifest(rootPath)
@@ -394,7 +470,8 @@ export async function buildCompatibilityMatrix(targetPath, environment = {}) {
         genericMcpResult,
         claudeDesktopResult,
         cursorResult,
-        clineResult
+        clineResult,
+        windsurfResult
     ];
     return {
         targetPath: rootPath,

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

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

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

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { getWindsurfMcpConfigPath, 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 buildWindsurfInstallPreview(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: getWindsurfMcpConfigPath(environment),
+        snippet: {
+            mcpServers: Object.fromEntries(Object.entries(servers).map(([serverName, serverConfig]) => [
+                serverName,
+                normalizeServerConfig(serverConfig, rootPath)
+            ]))
+        }
+    };
+}
+export function renderWindsurfInstallPreview(preview) {
+    return [
+        "Windsurf Install Preview",
+        "========================",
+        `Target: ${preview.targetPath}`,
+        `Config: ${preview.configPath}`,
+        "",
+        "Add or merge this snippet into `mcp_config.json`:",
+        JSON.stringify(preview.snippet, null, 2),
+        "",
+        "No files were modified."
+    ].join("\n");
+}

package/dist/core/environment-doctor.d.ts

@@ -1,2 +1,19 @@
 import type { CliTerminalContext } from "../run-cli.js";
+export interface EnvironmentDoctorReport {
+    schemaVersion: "1.0.0";
+    version: string;
+    platform: string;
+    node: string;
+    npmGlobalPrefix: string;
+    codexHome: {
+        status: "pass" | "warn";
+        path: string | null;
+    };
+    codexPluginCache: {
+        status: "pass" | "warn";
+        path: string | null;
+    };
+}
 export declare function renderEnvironmentDoctor(terminalContext: CliTerminalContext): Promise<string>;
+export declare function buildEnvironmentDoctorReport(terminalContext: CliTerminalContext): Promise<EnvironmentDoctorReport>;
+export declare function renderEnvironmentDoctorJson(terminalContext: CliTerminalContext): Promise<string>;

package/dist/core/environment-doctor.js

@@ -23,19 +23,40 @@ function resolveCodexHome(env) {
     return null;
 }
 export async function renderEnvironmentDoctor(terminalContext) {
+    const report = await buildEnvironmentDoctorReport(terminalContext);
+    return [
+        "Codex Plugin Doctor Environment",
+        "===============================",
+        `Version: ${report.version}`,
+        `Platform: ${report.platform}`,
+        `Node: ${report.node}`,
+        `npm global prefix: ${report.npmGlobalPrefix}`,
+        `Codex home: ${report.codexHome.status.toUpperCase()}${report.codexHome.path ? ` (${report.codexHome.path})` : ""}`,
+        `Codex plugin cache: ${report.codexPluginCache.status.toUpperCase()}${report.codexPluginCache.path ? ` (${report.codexPluginCache.path})` : ""}`
+    ].join("\n");
+}
+export async function buildEnvironmentDoctorReport(terminalContext) {
     const codexHome = resolveCodexHome(terminalContext.env);
     const codexHomeExists = codexHome ? await pathExists(codexHome) : false;
     const pluginCache = codexHome ? path.join(codexHome, "plugins", "cache") : null;
     const pluginCacheExists = pluginCache ? await pathExists(pluginCache) : false;
     const npmPrefix = terminalContext.env.npm_config_prefix ?? "(unknown)";
-    return [
-        "Codex Plugin Doctor Environment",
-        "===============================",
-        `Version: ${packageVersion}`,
-        `Platform: ${terminalContext.platform ?? process.platform}`,
-        `Node: ${process.version}`,
-        `npm global prefix: ${npmPrefix}`,
-        `Codex home: ${codexHomeExists ? "PASS" : "WARN"}${codexHome ? ` (${codexHome})` : ""}`,
-        `Codex plugin cache: ${pluginCacheExists ? "PASS" : "WARN"}${pluginCache ? ` (${pluginCache})` : ""}`
-    ].join("\n");
+    return {
+        schemaVersion: "1.0.0",
+        version: packageVersion,
+        platform: terminalContext.platform ?? process.platform,
+        node: process.version,
+        npmGlobalPrefix: npmPrefix,
+        codexHome: {
+            status: codexHomeExists ? "pass" : "warn",
+            path: codexHome
+        },
+        codexPluginCache: {
+            status: pluginCacheExists ? "pass" : "warn",
+            path: pluginCache
+        }
+    };
+}
+export async function renderEnvironmentDoctorJson(terminalContext) {
+    return JSON.stringify(await buildEnvironmentDoctorReport(terminalContext), null, 2);
 }

package/dist/core/fix-plan.d.ts

@@ -14,7 +14,22 @@ export interface ApplyFixPlanResult {
     filesChanged: number;
     backupDirectory: string;
 }
+export interface FixPlanJsonReport {
+    schemaVersion: "1.0.0";
+    mode: "dry-run" | "apply";
+    targetPath: string;
+    filesChanged: number;
+    backupDirectory: string | null;
+    actions: Array<FixPlanAction & {
+        relativePath: string;
+    }>;
+}
 export declare function buildFixPlan(targetPath: string): Promise<FixPlan>;
 export declare function renderFixPlan(plan: FixPlan, mode: "dry-run"): string;
 export declare function applyFixPlan(targetPath: string): Promise<ApplyFixPlanResult>;
 export declare function renderApplyFixResult(result: ApplyFixPlanResult): string;
+export declare function renderFixPlanJsonReport(plan: FixPlan, options: {
+    mode: "dry-run" | "apply";
+    filesChanged?: number;
+    backupDirectory?: string | null;
+}): string;

package/dist/core/fix-plan.js

@@ -1,4 +1,4 @@
-import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { validatePlugin } from "./validate-plugin.js";
 function relativeToTarget(targetPath, candidatePath) {
@@ -33,6 +33,53 @@ export async function buildFixPlan(targetPath) {
             details: "Create the skills directory referenced by the manifest."
         });
     }
+    const manifest = await readFile(manifestPath, "utf8")
+        .then((content) => JSON.parse(content))
+        .catch(() => ({}));
+    if (typeof manifest.skills === "string") {
+        const skillsPath = path.resolve(rootPath, manifest.skills);
+        if (await directoryExists(skillsPath)) {
+            for (const entry of await readdir(skillsPath, { withFileTypes: true })) {
+                if (!entry.isDirectory()) {
+                    continue;
+                }
+                const skillFilePath = path.join(skillsPath, entry.name, "SKILL.md");
+                if (!(await fileExists(skillFilePath))) {
+                    actions.push({
+                        id: "skill.scaffold_skill_md",
+                        title: `Create missing SKILL.md for ${entry.name}`,
+                        targetPath: skillFilePath,
+                        operation: "update-json",
+                        details: `Create ${relativeToTarget(rootPath, skillFilePath)} with safe frontmatter.`
+                    });
+                    continue;
+                }
+                const skillContent = await readFile(skillFilePath, "utf8");
+                const frontmatter = skillContent.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "";
+                if (!/^name\s*:/im.test(frontmatter) || !/^description\s*:/im.test(frontmatter)) {
+                    actions.push({
+                        id: "skill.safe_frontmatter_defaults",
+                        title: `Add missing skill frontmatter defaults for ${entry.name}`,
+                        targetPath: skillFilePath,
+                        operation: "update-json",
+                        details: `Set missing name/description fields in ${relativeToTarget(rootPath, skillFilePath)}.`
+                    });
+                }
+            }
+        }
+    }
+    if (typeof manifest.mcpServers === "string") {
+        const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
+        if (!(await fileExists(mcpConfigPath))) {
+            actions.push({
+                id: "mcp.scaffold_config",
+                title: "Create missing MCP config",
+                targetPath: mcpConfigPath,
+                operation: "update-json",
+                details: `Create ${relativeToTarget(rootPath, mcpConfigPath)} with an empty mcpServers object.`
+            });
+        }
+    }
     return {
         targetPath: rootPath,
         actions
@@ -66,6 +113,54 @@ function timestampForPath() {
 function defaultManifestDescription() {
     return "Codex plugin package.";
 }
+async function fileExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function directoryExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function skillDescription(skillName) {
+    return `Use when running the ${skillName} skill.`;
+}
+function renderSkillScaffold(skillName, body = "") {
+    return [
+        "---",
+        `name: ${skillName}`,
+        `description: ${skillDescription(skillName)}`,
+        "---",
+        "",
+        body.trim() || `# ${skillName}`
+    ].join("\n") + "\n";
+}
+function replaceFrontmatter(content, skillName) {
+    const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    const frontmatter = frontmatterMatch?.[1] ?? "";
+    const body = frontmatterMatch ? content.slice(frontmatterMatch[0].length) : content;
+    const lines = frontmatter.split(/\r?\n/).filter((line) => line.trim());
+    const hasName = lines.some((line) => /^name\s*:/i.test(line));
+    const hasDescription = lines.some((line) => /^description\s*:/i.test(line));
+    return [
+        "---",
+        ...(hasName ? [] : [`name: ${skillName}`]),
+        ...(hasDescription ? [] : [`description: ${skillDescription(skillName)}`]),
+        ...lines,
+        "---",
+        "",
+        body.trim() || `# ${skillName}`
+    ].join("\n") + "\n";
+}
 async function backupFile(rootPath, backupDirectory, filePath) {
     const relativePath = path.relative(rootPath, filePath);
     const backupPath = path.join(backupDirectory, relativePath);
@@ -94,6 +189,24 @@ export async function applyFixPlan(targetPath) {
         if (action.operation === "mkdir" && action.id === "skills.create_directory") {
             await mkdir(action.targetPath, { recursive: true });
             filesChanged += 1;
+            continue;
+        }
+        if (action.operation === "update-json" && action.id === "skill.scaffold_skill_md") {
+            await mkdir(path.dirname(action.targetPath), { recursive: true });
+            await writeFile(action.targetPath, renderSkillScaffold(path.basename(path.dirname(action.targetPath))), "utf8");
+            filesChanged += 1;
+            continue;
+        }
+        if (action.operation === "update-json" && action.id === "skill.safe_frontmatter_defaults") {
+            await backupFile(plan.targetPath, backupDirectory, action.targetPath);
+            await writeFile(action.targetPath, replaceFrontmatter(await readFile(action.targetPath, "utf8"), path.basename(path.dirname(action.targetPath))), "utf8");
+            filesChanged += 1;
+            continue;
+        }
+        if (action.operation === "update-json" && action.id === "mcp.scaffold_config") {
+            await mkdir(path.dirname(action.targetPath), { recursive: true });
+            await writeFile(action.targetPath, `${JSON.stringify({ mcpServers: {} }, null, 2)}\n`, "utf8");
+            filesChanged += 1;
         }
     }
     return {
@@ -112,3 +225,17 @@ export function renderApplyFixResult(result) {
         `Backup: ${relativeToTarget(result.plan.targetPath, result.backupDirectory)}`
     ].join("\n");
 }
+export function renderFixPlanJsonReport(plan, options) {
+    const report = {
+        schemaVersion: "1.0.0",
+        mode: options.mode,
+        targetPath: plan.targetPath,
+        filesChanged: options.filesChanged ?? 0,
+        backupDirectory: options.backupDirectory ?? null,
+        actions: plan.actions.map((action) => ({
+            ...action,
+            relativePath: relativeToTarget(plan.targetPath, action.targetPath)
+        }))
+    };
+    return JSON.stringify(report, null, 2);
+}

package/dist/core/init-ci.d.ts

@@ -0,0 +1,5 @@
+export interface InitCiResult {
+    rootPath: string;
+    workflowPath: string;
+}
+export declare function initCiWorkflow(targetPath: string): Promise<InitCiResult>;

package/dist/core/init-ci.js

@@ -0,0 +1,36 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { packageVersion } from "../version.js";
+function buildWorkflow() {
+    return [
+        "name: Validate Codex plugin",
+        "",
+        "on:",
+        "  pull_request:",
+        "  push:",
+        "    branches:",
+        "      - main",
+        "",
+        "jobs:",
+        "  doctor:",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        "      - uses: actions/checkout@v4",
+        `      - uses: Esquetta/CodexPluginDoctor@v${packageVersion}`,
+        "        with:",
+        `          version: \"${packageVersion}\"`,
+        "          path: .",
+        "          runtime: \"true\"",
+        ""
+    ].join("\n");
+}
+export async function initCiWorkflow(targetPath) {
+    const rootPath = path.resolve(targetPath);
+    const workflowPath = path.join(rootPath, ".github", "workflows", "codex-plugin-doctor.yml");
+    await mkdir(path.dirname(workflowPath), { recursive: true });
+    await writeFile(workflowPath, buildWorkflow(), "utf8");
+    return {
+        rootPath,
+        workflowPath
+    };
+}

package/dist/run-cli.js

@@ -8,9 +8,11 @@ import { applyInstallPreview, renderApplyInstallResult } from "./compatibility/a
 import { buildClaudeDesktopInstallPreview, renderClaudeDesktopInstallPreview } from "./compatibility/claude-desktop-install-preview.js";
 import { buildCursorInstallPreview, renderCursorInstallPreview } from "./compatibility/cursor-install-preview.js";
 import { buildClineInstallPreview, renderClineInstallPreview } from "./compatibility/cline-install-preview.js";
+import { buildWindsurfInstallPreview, renderWindsurfInstallPreview } from "./compatibility/windsurf-install-preview.js";
 import { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
-import { applyFixPlan, buildFixPlan, renderApplyFixResult, renderFixPlan } from "./core/fix-plan.js";
-import { renderEnvironmentDoctor } from "./core/environment-doctor.js";
+import { applyFixPlan, buildFixPlan, renderApplyFixResult, renderFixPlanJsonReport, renderFixPlan } from "./core/fix-plan.js";
+import { renderEnvironmentDoctor, renderEnvironmentDoctorJson } from "./core/environment-doctor.js";
+import { initCiWorkflow } from "./core/init-ci.js";
 import { initPluginPackage } from "./core/init-plugin.js";
 import { runCheck } from "./index.js";
 import { renderInstalledSummary } from "./reporting/render-installed-summary.js";
@@ -37,7 +39,7 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <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 fix <path> (--dry-run|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\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>] [--history <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 fix <path> (--dry-run|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor\n       codex-plugin-doctor init-ci [path]\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,7 +66,8 @@ const compatibilityClientAliases = {
     "claude-desktop": "Claude Desktop",
     claude: "Claude Desktop",
     cursor: "Cursor",
-    cline: "Cline"
+    cline: "Cline",
+    windsurf: "Windsurf"
 };
 const checkProfiles = ["ci", "strict", "publish"];
 function parseCheckProfile(value) {
@@ -130,7 +133,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return 0;
     }
     if (command === "doctor") {
-        io.writeStdout(await renderEnvironmentDoctor(terminalContext));
+        io.writeStdout(maybePath === "--json"
+            ? await renderEnvironmentDoctorJson(terminalContext)
+            : await renderEnvironmentDoctor(terminalContext));
         return 0;
     }
     if (command === "explain") {
@@ -195,6 +200,16 @@ export async function runCli(args, io = defaultIo, options = {}) {
         ].join("\n"));
         return 0;
     }
+    if (command === "init-ci") {
+        const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+        const result = await initCiWorkflow(targetPath);
+        io.writeStdout([
+            "Initialized Codex Plugin Doctor workflow",
+            `Root: ${result.rootPath}`,
+            `Workflow: ${result.workflowPath}`
+        ].join("\n"));
+        return 0;
+    }
     if (command === "fix") {
         if (!maybePath || maybePath.startsWith("--")) {
             io.writeStderr("Missing target path. Usage: codex-plugin-doctor fix <path> (--dry-run|--apply --backup)");
@@ -203,6 +218,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const dryRun = remainingArgs.includes("--dry-run");
         const apply = remainingArgs.includes("--apply");
         const backup = remainingArgs.includes("--backup");
+        const jsonOutput = remainingArgs.includes("--json");
         if (apply && !backup) {
             io.writeStderr("Fix apply requires --backup.");
             return 2;
@@ -211,9 +227,21 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStderr("Choose exactly one fix mode: --dry-run or --apply --backup.");
             return 2;
         }
-        io.writeStdout(dryRun
-            ? renderFixPlan(await buildFixPlan(maybePath), "dry-run")
-            : renderApplyFixResult(await applyFixPlan(maybePath)));
+        if (dryRun) {
+            const plan = await buildFixPlan(maybePath);
+            io.writeStdout(jsonOutput
+                ? renderFixPlanJsonReport(plan, { mode: "dry-run" })
+                : renderFixPlan(plan, "dry-run"));
+            return 0;
+        }
+        const result = await applyFixPlan(maybePath);
+        io.writeStdout(jsonOutput
+            ? renderFixPlanJsonReport(result.plan, {
+                mode: "apply",
+                filesChanged: result.filesChanged,
+                backupDirectory: result.backupDirectory
+            })
+            : renderApplyFixResult(result));
         return 0;
     }
     if (command === "compat") {
@@ -241,8 +269,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
         if ((installPreview || applyInstall) &&
             clientFilter?.toLowerCase() !== "claude-desktop" &&
             clientFilter?.toLowerCase() !== "cursor" &&
-            clientFilter?.toLowerCase() !== "cline") {
-            io.writeStderr("--install-preview and --apply require --client claude-desktop, cursor, or cline.");
+            clientFilter?.toLowerCase() !== "cline" &&
+            clientFilter?.toLowerCase() !== "windsurf") {
+            io.writeStderr("--install-preview and --apply require --client claude-desktop, cursor, cline, or windsurf.");
             return 2;
         }
         if (installPreview && applyInstall) {
@@ -266,21 +295,30 @@ export async function runCli(args, io = defaultIo, options = {}) {
                             env: terminalContext.env,
                             platform: terminalContext.platform
                         })
-                        : await buildClaudeDesktopInstallPreview(targetPath, {
-                            env: terminalContext.env,
-                            platform: terminalContext.platform
-                        });
+                        : normalizedClient === "windsurf"
+                            ? await buildWindsurfInstallPreview(targetPath, {
+                                env: terminalContext.env,
+                                platform: terminalContext.platform
+                            })
+                            : await buildClaudeDesktopInstallPreview(targetPath, {
+                                env: terminalContext.env,
+                                platform: terminalContext.platform
+                            });
                 const report = applyInstall
                     ? renderApplyInstallResult(await applyInstallPreview(normalizedClient === "cursor"
                         ? "Cursor"
                         : normalizedClient === "cline"
                             ? "Cline"
-                            : "Claude Desktop", preview))
+                            : normalizedClient === "windsurf"
+                                ? "Windsurf"
+                                : "Claude Desktop", preview))
                     : normalizedClient === "cursor"
                         ? renderCursorInstallPreview(preview)
                         : normalizedClient === "cline"
                             ? renderClineInstallPreview(preview)
-                            : renderClaudeDesktopInstallPreview(preview);
+                            : normalizedClient === "windsurf"
+                                ? renderWindsurfInstallPreview(preview)
+                                : renderClaudeDesktopInstallPreview(preview);
                 if (outputPath) {
                     await writeFile(outputPath, report, "utf8");
                 }

package/package.json

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