codex-plugin-doctor 0.7.0 → 0.9.0

package/README.md

@@ -166,6 +166,7 @@ codex-plugin-doctor self-test
 codex-plugin-doctor doctor
 codex-plugin-doctor init my-plugin
 codex-plugin-doctor compat .
+codex-plugin-doctor compat . --all --scorecard
 codex-plugin-doctor compat . --client codex
 codex-plugin-doctor compat . --client generic-mcp
 codex-plugin-doctor compat . --client claude-desktop
@@ -184,6 +185,7 @@ codex-plugin-doctor check . --profile ci
 codex-plugin-doctor check . --profile strict
 codex-plugin-doctor check . --profile publish
 codex-plugin-doctor check . --json
+codex-plugin-doctor check . --explain
 codex-plugin-doctor check . --json --output report.json
 codex-plugin-doctor check . --markdown --output report.md
 codex-plugin-doctor check . --badge-json --output doctor-badge.json
@@ -198,13 +200,14 @@ codex-plugin-doctor history validation-history.jsonl
 codex-plugin-doctor history validation-history.jsonl --json
 codex-plugin-doctor history validation-history.jsonl --fail-on-regression
 codex-plugin-doctor fix . --dry-run
+codex-plugin-doctor fix . --interactive --backup
 codex-plugin-doctor fix . --apply --backup
 codex-plugin-doctor check . --json --runtime --verbose-runtime
 ```
 
 `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`.
 
-`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility.
+`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup.
 
 `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.
 
@@ -212,15 +215,17 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `compat --client cline` checks whether the MCP package can be added to Cline. It uses `CLINE_DIR/data/settings/cline_mcp_settings.json` when `CLINE_DIR` is set, otherwise `~/.cline/data/settings/cline_mcp_settings.json`. Add `--install-preview` to print the JSON snippet that should be merged into `cline_mcp_settings.json`.
 
-`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`.
+`compat --all` makes the all-client matrix explicit when you want Codex, Generic MCP, Claude Desktop, Cursor, Cline, and Windsurf in one run. `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`.
 
 `check --profile ci|strict|publish` applies named validation policies. `ci` keeps default behavior, `strict` fails on warnings, and `publish` fails on warnings while enabling runtime probing by default.
 
+`check --explain` adds inline rule catalog context to text reports, including why a finding matters, a more detailed fix path, and a compact example.
+
 `check --badge-json` emits Shields endpoint-compatible JSON such as `{"schemaVersion":1,"label":"doctor","message":"PASS","color":"brightgreen"}`. `check --badge-markdown` emits a static shields.io Markdown badge for README or release notes. Badge output is intentionally limited to single package checks, not `check --installed`.
 
 `check --history <path>` appends a compact JSONL validation snapshot after a single package check. `history <path>` reads the JSONL file and compares the latest run to the previous run, including status, finding-count deltas, and whether the latest run regressed. Add `history --json` for automation output or `history --fail-on-regression` when CI should fail after a worse latest run.
 
-`fix --dry-run` renders safe automatic fix plans without changing files. `fix --apply --backup` applies only supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
+`fix --dry-run` renders safe automatic fix plans without changing files. `fix --interactive --backup` shows the same plan, then applies only after you type `yes`. `fix --apply --backup` applies supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
 
 Optional local policy file:
 
@@ -255,9 +260,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: Esquetta/CodexPluginDoctor@v0.7.0
+      - uses: Esquetta/CodexPluginDoctor@v0.9.0
         with:
-          version: "0.7.0"
+          version: "0.9.0"
           path: .
           runtime: "false"
 ```
@@ -300,11 +305,12 @@ Recent validation waves covered:
 
 Release preparation is reproducible from the repository:
 
-```bash
-npm run prepare-release
-```
-
-This runs tests, builds the TypeScript output, and performs `npm pack --dry-run`.
+```bash
+npm run prepare-release
+npm run release-check
+```
+
+`prepare-release` runs tests, builds the TypeScript output, and performs `npm pack --dry-run`. `release-check` adds release preflight checks for a clean git tree, existing npm versions, existing version tags, tests, build, and pack dry-run.
 
 Related docs:
 

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,48 @@ 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})` : ""}`,
+        "",
+        "Recommended next commands",
+        "-------------------------",
+        "codex-plugin-doctor self-test",
+        "codex-plugin-doctor list --installed",
+        "codex-plugin-doctor check . --runtime --explain",
+        "codex-plugin-doctor compat . --all --scorecard",
+        "codex-plugin-doctor init-ci ."
+    ].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 renderFixPlan(plan: FixPlan, mode: "dry-run" | "interactive"): 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/reporting/render-text-report.d.ts

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

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

@@ -1,3 +1,4 @@
+import { findRuleDefinition } from "../rules/rule-catalog.js";
 function getCounts(result) {
     const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
     const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
@@ -22,6 +23,7 @@ function getGlyphs(ascii) {
 }
 export function renderTextReport(result, options = {}) {
     const ascii = options.ascii ?? false;
+    const explain = options.explain ?? false;
     const glyphs = getGlyphs(ascii);
     const { failCount, warnCount, totalCount } = getCounts(result);
     const lines = [
@@ -58,6 +60,14 @@ export function renderTextReport(result, options = {}) {
             lines.push(`  Message: ${finding.message}`);
             lines.push(`  Impact: ${finding.impact}`);
             lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+            if (explain) {
+                const rule = findRuleDefinition(finding.id);
+                if (rule) {
+                    lines.push(`  Why: ${rule.why}`);
+                    lines.push(`  Fix detail: ${rule.fix}`);
+                    lines.push(`  Example: ${rule.example}`);
+                }
+            }
         }
     };
     appendSection("Failures", failures, glyphs.fail);

package/dist/run-cli.d.ts

@@ -2,6 +2,7 @@ import { runCheck } from "./index.js";
 export interface CliIo {
     writeStdout(message: string): void;
     writeStderr(message: string): void;
+    readStdin?(prompt: string): Promise<string>;
 }
 export interface CliTerminalContext {
     stdoutIsTTY: boolean;

package/dist/run-cli.js

@@ -1,5 +1,6 @@
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
 import { appendValidationHistoryEntry, readValidationHistory, summarizeValidationHistory } from "./core/validation-history.js";
@@ -8,9 +9,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";
@@ -34,10 +37,22 @@ const defaultIo = {
     },
     writeStderr(message) {
         process.stderr.write(`${message}\n`);
+    },
+    async readStdin(prompt) {
+        const readline = createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+        try {
+            return await readline.question(prompt);
+        }
+        finally {
+            readline.close();
+        }
     }
 };
 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] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--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\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -64,7 +79,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 +146,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,25 +213,68 @@ 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)");
+            io.writeStderr("Missing target path. Usage: codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)");
             return 2;
         }
         const dryRun = remainingArgs.includes("--dry-run");
         const apply = remainingArgs.includes("--apply");
+        const interactive = remainingArgs.includes("--interactive");
         const backup = remainingArgs.includes("--backup");
-        if (apply && !backup) {
-            io.writeStderr("Fix apply requires --backup.");
+        const jsonOutput = remainingArgs.includes("--json");
+        if ((apply || interactive) && !backup) {
+            io.writeStderr("Fix mode requires --backup.");
+            return 2;
+        }
+        if ([dryRun, apply, interactive].filter(Boolean).length !== 1) {
+            io.writeStderr("Choose exactly one fix mode: --dry-run, --interactive --backup, or --apply --backup.");
             return 2;
         }
-        if (dryRun === apply) {
-            io.writeStderr("Choose exactly one fix mode: --dry-run or --apply --backup.");
+        if (interactive && jsonOutput) {
+            io.writeStderr("Interactive fix mode does not support --json.");
             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;
+        }
+        if (interactive) {
+            const plan = await buildFixPlan(maybePath);
+            io.writeStdout([
+                renderFixPlan(plan, "interactive"),
+                "",
+                "Type yes to apply these fixes with a backup. Anything else cancels."
+            ].join("\n"));
+            const answer = (await io.readStdin?.("Apply fixes? ") ?? "").trim().toLowerCase();
+            if (answer !== "yes") {
+                io.writeStdout("Fix cancelled. No files changed.");
+                return 0;
+            }
+            io.writeStdout(renderApplyFixResult(await applyFixPlan(maybePath)));
+            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") {
@@ -226,6 +287,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const installPreview = compatFlags.includes("--install-preview");
         const applyInstall = compatFlags.includes("--apply");
         const backupInstall = compatFlags.includes("--backup");
+        const allClients = compatFlags.includes("--all");
         const clientIndex = compatFlags.indexOf("--client");
         const clientFilter = clientIndex === -1 ? null : compatFlags[clientIndex + 1];
         const outputIndex = compatFlags.indexOf("--output");
@@ -234,6 +296,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStderr("Missing client after --client.");
             return 2;
         }
+        if (allClients && clientFilter) {
+            io.writeStderr("Use either --all or --client, not both.");
+            return 2;
+        }
         if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
             io.writeStderr("Missing path after --output.");
             return 2;
@@ -241,8 +307,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 +333,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");
                 }
@@ -340,6 +416,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const sarifOutput = normalizedFlags.includes("--sarif");
     const runtimeProbeEnabled = normalizedFlags.includes("--runtime");
     const verboseRuntime = normalizedFlags.includes("--verbose-runtime");
+    const explainFindings = normalizedFlags.includes("--explain");
     const noAnimations = normalizedFlags.includes("--no-animations");
     const asciiMode = normalizedFlags.includes("--ascii");
     const installedSummary = normalizedFlags.includes("--all-summary");
@@ -422,7 +499,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     ? buildMarkdownReport(item.result, { runtimeProbeEnabled: effectiveRuntimeProbeEnabled })
                     : jsonOutput
                         ? renderJsonReport(item.result, { runtimeProbeEnabled: effectiveRuntimeProbeEnabled })
-                        : renderTextReport(item.result, { ascii: outputPolicy.style === "ascii" }))
+                        : renderTextReport(item.result, {
+                            ascii: outputPolicy.style === "ascii",
+                            explain: explainFindings
+                        }))
                 .join("\n\n");
         if (outputPath) {
             await writeFile(outputPath, report, "utf8");
@@ -459,7 +539,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     ? renderBadgeJson(result)
                     : badgeMarkdownOutput
                         ? renderBadgeMarkdown(result)
-                        : renderTextReport(result, { ascii: outputPolicy.style === "ascii" });
+                        : renderTextReport(result, {
+                            ascii: outputPolicy.style === "ascii",
+                            explain: explainFindings
+                        });
     if (outputPath) {
         await writeFile(outputPath, report, "utf8");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,7 @@
     "generate-validation-artifacts": "node scripts/generate-validation-artifacts.mjs",
     "prepare-rc": "tsx scripts/prepare-release-candidate.ts",
     "prepare-release": "npm test && npm run build && npm pack --dry-run",
+    "release-check": "node scripts/release-check.mjs",
     "prepublishOnly": "npm test && npm run build",
     "test": "vitest run",
     "test:watch": "vitest"