codex-plugin-doctor 0.8.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.8.0
+      - uses: Esquetta/CodexPluginDoctor@v0.9.0
         with:
-          version: "0.8.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/core/environment-doctor.js

@@ -32,7 +32,15 @@ export async function renderEnvironmentDoctor(terminalContext) {
         `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})` : ""}`
+        `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) {

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

@@ -25,7 +25,7 @@ export interface FixPlanJsonReport {
     }>;
 }
 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: {

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";
@@ -36,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 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");
+    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 = [
@@ -212,19 +225,24 @@ export async function runCli(args, io = defaultIo, options = {}) {
     }
     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");
         const jsonOutput = remainingArgs.includes("--json");
-        if (apply && !backup) {
-            io.writeStderr("Fix apply requires --backup.");
+        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;
         }
         if (dryRun) {
@@ -234,6 +252,21 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 : 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, {
@@ -254,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");
@@ -262,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;
@@ -378,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");
@@ -460,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");
@@ -497,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.8.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"