codex-plugin-doctor 0.5.0 → 0.7.0

package/README.md

@@ -65,8 +65,9 @@ Output formats:
 - human text output
 - JSON reports
 - Markdown reports
-- Shields-compatible badge JSON and static badge Markdown
-- `--output` file writing
+- Shields-compatible badge JSON and static badge Markdown
+- validation history JSONL and trend summaries
+- `--output` file writing
 - CI summary and artifact generation
 
 ## Quick Start
@@ -161,45 +162,67 @@ Run these from a Codex plugin package root:
 
 ```bash
 codex-plugin-doctor --version
-codex-plugin-doctor self-test
-codex-plugin-doctor init my-plugin
-codex-plugin-doctor compat .
-codex-plugin-doctor compat . --client codex
-codex-plugin-doctor compat . --client generic-mcp
+codex-plugin-doctor self-test
+codex-plugin-doctor doctor
+codex-plugin-doctor init my-plugin
+codex-plugin-doctor compat .
+codex-plugin-doctor compat . --client codex
+codex-plugin-doctor compat . --client generic-mcp
 codex-plugin-doctor compat . --client claude-desktop
 codex-plugin-doctor compat . --client claude-desktop --install-preview
 codex-plugin-doctor compat . --client claude-desktop --apply --backup
-codex-plugin-doctor compat . --client cursor
-codex-plugin-doctor compat . --client cursor --install-preview
-codex-plugin-doctor compat . --client cursor --apply --backup
-codex-plugin-doctor compat . --scorecard
-codex-plugin-doctor compat . --json
-codex-plugin-doctor compat . --json --output compatibility.json
-codex-plugin-doctor check .
-codex-plugin-doctor check . --json
-codex-plugin-doctor check . --json --output report.json
-codex-plugin-doctor check . --markdown --output report.md
+codex-plugin-doctor compat . --client cursor
+codex-plugin-doctor compat . --client cursor --install-preview
+codex-plugin-doctor compat . --client cursor --apply --backup
+codex-plugin-doctor compat . --client cline
+codex-plugin-doctor compat . --client cline --install-preview
+codex-plugin-doctor compat . --scorecard
+codex-plugin-doctor compat . --json
+codex-plugin-doctor compat . --json --output compatibility.json
+codex-plugin-doctor check .
+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 . --json --output report.json
+codex-plugin-doctor check . --markdown --output report.md
 codex-plugin-doctor check . --badge-json --output doctor-badge.json
 codex-plugin-doctor check . --badge-markdown
 codex-plugin-doctor check . --sarif --output results.sarif
 codex-plugin-doctor check . --ascii
 codex-plugin-doctor check . --no-animations
-codex-plugin-doctor check . --runtime
-codex-plugin-doctor check . --config .codex-doctor.json
-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`.
-
-`compat --client claude-desktop` checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it looks for `~/Library/Application Support/Claude/claude_desktop_config.json`. A valid existing config returns `PASS`, a missing Claude Desktop install returns `WARN`, and a malformed local config returns `FAIL` so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns `WARN` with the duplicate server name. Add `--install-preview` to print the JSON snippet that should be merged into `claude_desktop_config.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
-
-`compat --client cursor` checks whether the MCP package can be added to Cursor. It prefers a project-level `.cursor/mcp.json` when one already exists in the target package, then falls back to the global `~/.cursor/mcp.json` path. A valid existing config returns `PASS`, a missing Cursor config returns `WARN`, malformed JSON returns `FAIL`, and duplicate MCP server names return `WARN`. Add `--install-preview` to print the JSON snippet that should be merged into Cursor's `mcp.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
-
-`compat --scorecard` turns the compatibility matrix into a compact score summary. `PASS` maps to `100`, `WARN` maps to `70`, and `FAIL` or `SKIPPED` maps to `0`.
-
-`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`.
-
-Optional local policy file:
+codex-plugin-doctor check . --runtime
+codex-plugin-doctor check . --config .codex-doctor.json
+codex-plugin-doctor check . --history validation-history.jsonl
+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 . --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.
+
+`compat --client claude-desktop` checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it looks for `~/Library/Application Support/Claude/claude_desktop_config.json`. A valid existing config returns `PASS`, a missing Claude Desktop install returns `WARN`, and a malformed local config returns `FAIL` so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns `WARN` with the duplicate server name. Add `--install-preview` to print the JSON snippet that should be merged into `claude_desktop_config.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
+
+`compat --client cursor` checks whether the MCP package can be added to Cursor. It prefers a project-level `.cursor/mcp.json` when one already exists in the target package, then falls back to the global `~/.cursor/mcp.json` path. A valid existing config returns `PASS`, a missing Cursor config returns `WARN`, malformed JSON returns `FAIL`, and duplicate MCP server names return `WARN`. Add `--install-preview` to print the JSON snippet that should be merged into Cursor's `mcp.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
+
+`compat --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`.
+
+`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 --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.
+
+Optional local policy file:
 
 ```json
 {
@@ -232,11 +255,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: Esquetta/CodexPluginDoctor@v0.5.0
-        with:
-          version: "0.5.0"
-          path: .
-          runtime: "false"
+      - uses: Esquetta/CodexPluginDoctor@v0.7.0
+        with:
+          version: "0.7.0"
+          path: .
+          runtime: "false"
 ```
 
 For runtime probing, SARIF output, installed plugin cache checks, and pinned release examples, see [GitHub Action Usage](./docs/engineering/github-action-usage.md).

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

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

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

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

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

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

@@ -134,6 +134,13 @@ export async function getCursorMcpConfigPath(targetPath, environment = {}) {
     }
     return path.join(getHomeDirectory(environment), ".cursor", "mcp.json");
 }
+export function getClineMcpConfigPath(environment = {}) {
+    const env = environment.env ?? process.env;
+    const clineDirectory = env.CLINE_DIR
+        ? path.resolve(env.CLINE_DIR)
+        : path.join(getHomeDirectory(environment), ".cline");
+    return path.join(clineDirectory, "data", "settings", "cline_mcp_settings.json");
+}
 async function checkClaudeDesktop(targetPath, genericMcpResult, environment = {}) {
     if (genericMcpResult.status !== "pass") {
         return {
@@ -286,11 +293,84 @@ async function checkCursor(targetPath, genericMcpResult, environment = {}) {
         };
     }
 }
+async function checkCline(targetPath, genericMcpResult, environment = {}) {
+    if (genericMcpResult.status !== "pass") {
+        return {
+            client: "Cline",
+            status: "skipped",
+            summary: "No valid MCP package config is available for Cline.",
+            details: ["Add a valid `.mcp.json` with a non-empty `mcpServers` object first."]
+        };
+    }
+    const configPath = getClineMcpConfigPath(environment);
+    if (!(await fileExists(configPath))) {
+        const configDirectory = path.dirname(configPath);
+        return {
+            client: "Cline",
+            status: await directoryExists(configDirectory) ? "pass" : "warn",
+            summary: await directoryExists(configDirectory)
+                ? "Cline MCP settings directory exists and a config file can be created."
+                : "Cline was not detected on this machine.",
+            details: [
+                configPath,
+                "Cline stores MCP servers in `cline_mcp_settings.json` under its settings directory."
+            ]
+        };
+    }
+    try {
+        const parsed = await readJsonFile(configPath);
+        const servers = parsed.mcpServers;
+        if (servers !== undefined && (typeof servers !== "object" ||
+            servers === null ||
+            Array.isArray(servers))) {
+            return {
+                client: "Cline",
+                status: "fail",
+                summary: "Cline 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: "Cline",
+                status: "warn",
+                summary: "Cline already has MCP server names from this package.",
+                details: [
+                    configPath,
+                    ...duplicateServerNames.map((serverName) => `Duplicate server: ${serverName}`)
+                ]
+            };
+        }
+        return {
+            client: "Cline",
+            status: "pass",
+            summary: "Cline MCP config is valid and this package can be added.",
+            details: [
+                configPath,
+                `Source package: ${path.resolve(targetPath)}`
+            ]
+        };
+    }
+    catch {
+        return {
+            client: "Cline",
+            status: "fail",
+            summary: "Cline MCP config is not valid JSON.",
+            details: [configPath, "Repair the local Cline 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 codexResult = await validatePlugin(rootPath);
     const codexStatus = statusFromCheckResult(codexResult);
     const codexCompatibility = !await hasCodexManifest(rootPath)
@@ -313,7 +393,8 @@ export async function buildCompatibilityMatrix(targetPath, environment = {}) {
         codexCompatibility,
         genericMcpResult,
         claudeDesktopResult,
-        cursorResult
+        cursorResult,
+        clineResult
     ];
     return {
         targetPath: rootPath,

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

@@ -0,0 +1,2 @@
+import type { CliTerminalContext } from "../run-cli.js";
+export declare function renderEnvironmentDoctor(terminalContext: CliTerminalContext): Promise<string>;

package/dist/core/environment-doctor.js

@@ -0,0 +1,41 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { packageVersion } from "../version.js";
+async function pathExists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveCodexHome(env) {
+    if (env.CODEX_HOME) {
+        return path.resolve(env.CODEX_HOME);
+    }
+    if (env.USERPROFILE) {
+        return path.join(env.USERPROFILE, ".codex");
+    }
+    if (env.HOME) {
+        return path.join(env.HOME, ".codex");
+    }
+    return null;
+}
+export async function renderEnvironmentDoctor(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");
+}

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

@@ -0,0 +1,20 @@
+export interface FixPlanAction {
+    id: string;
+    title: string;
+    targetPath: string;
+    operation: "update-json" | "mkdir";
+    details: string;
+}
+export interface FixPlan {
+    targetPath: string;
+    actions: FixPlanAction[];
+}
+export interface ApplyFixPlanResult {
+    plan: FixPlan;
+    filesChanged: number;
+    backupDirectory: 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;

package/dist/core/fix-plan.js

@@ -0,0 +1,114 @@
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { validatePlugin } from "./validate-plugin.js";
+function relativeToTarget(targetPath, candidatePath) {
+    return path.relative(targetPath, candidatePath).replace(/\\/g, "/");
+}
+export async function buildFixPlan(targetPath) {
+    const result = await validatePlugin(targetPath);
+    const rootPath = result.targetPath;
+    const actions = [];
+    const findingIds = new Set(result.findings.map((finding) => finding.id));
+    const manifestPath = path.join(rootPath, ".codex-plugin", "plugin.json");
+    if (findingIds.has("plugin.manifest.version.missing") ||
+        findingIds.has("plugin.manifest.description.missing")) {
+        const fields = [
+            findingIds.has("plugin.manifest.version.missing") ? "`version`" : null,
+            findingIds.has("plugin.manifest.description.missing") ? "`description`" : null
+        ].filter(Boolean);
+        actions.push({
+            id: "manifest.safe_defaults",
+            title: "Add missing safe manifest defaults",
+            targetPath: manifestPath,
+            operation: "update-json",
+            details: `Set ${fields.join(" and ")} in ${relativeToTarget(rootPath, manifestPath)}.`
+        });
+    }
+    if (findingIds.has("plugin.skills.path.missing")) {
+        actions.push({
+            id: "skills.create_directory",
+            title: "Create missing skills directory",
+            targetPath: path.join(rootPath, "skills"),
+            operation: "mkdir",
+            details: "Create the skills directory referenced by the manifest."
+        });
+    }
+    return {
+        targetPath: rootPath,
+        actions
+    };
+}
+export function renderFixPlan(plan, mode) {
+    const lines = [
+        "Fix Plan",
+        "========",
+        `Mode: ${mode}`,
+        `Target: ${plan.targetPath}`
+    ];
+    if (plan.actions.length === 0) {
+        lines.push("", "No safe automatic fixes available.");
+        return lines.join("\n");
+    }
+    lines.push("", "Actions");
+    lines.push("-------");
+    plan.actions.forEach((action, index) => {
+        lines.push(`${index + 1}. ${action.title}`);
+        lines.push(`   Path: ${relativeToTarget(plan.targetPath, action.targetPath)}`);
+        lines.push(`   Operation: ${action.operation}`);
+        lines.push(`   Details: ${action.details}`);
+    });
+    lines.push("", "No files changed.");
+    return lines.join("\n");
+}
+function timestampForPath() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+function defaultManifestDescription() {
+    return "Codex plugin package.";
+}
+async function backupFile(rootPath, backupDirectory, filePath) {
+    const relativePath = path.relative(rootPath, filePath);
+    const backupPath = path.join(backupDirectory, relativePath);
+    await mkdir(path.dirname(backupPath), { recursive: true });
+    await copyFile(filePath, backupPath);
+}
+export async function applyFixPlan(targetPath) {
+    const plan = await buildFixPlan(targetPath);
+    const backupDirectory = path.join(plan.targetPath, ".codex-doctor-backups", timestampForPath());
+    let filesChanged = 0;
+    for (const action of plan.actions) {
+        if (action.operation === "update-json" && action.id === "manifest.safe_defaults") {
+            await backupFile(plan.targetPath, backupDirectory, action.targetPath);
+            const manifest = JSON.parse(await readFile(action.targetPath, "utf8"));
+            if (typeof manifest.version !== "string" || manifest.version.trim() === "") {
+                manifest.version = "0.1.0";
+            }
+            if (typeof manifest.description !== "string" ||
+                manifest.description.trim() === "") {
+                manifest.description = defaultManifestDescription();
+            }
+            await writeFile(action.targetPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+            filesChanged += 1;
+            continue;
+        }
+        if (action.operation === "mkdir" && action.id === "skills.create_directory") {
+            await mkdir(action.targetPath, { recursive: true });
+            filesChanged += 1;
+        }
+    }
+    return {
+        plan,
+        filesChanged,
+        backupDirectory
+    };
+}
+export function renderApplyFixResult(result) {
+    return [
+        "Fix Plan",
+        "========",
+        "Mode: apply",
+        `Target: ${result.plan.targetPath}`,
+        `Files changed: ${result.filesChanged}`,
+        `Backup: ${relativeToTarget(result.plan.targetPath, result.backupDirectory)}`
+    ].join("\n");
+}

package/dist/core/validation-history.d.ts

@@ -0,0 +1,33 @@
+import type { CheckResult } from "../domain/types.js";
+export interface ValidationHistoryEntry {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    targetPath: string;
+    status: CheckResult["status"];
+    runtimeProbeEnabled: boolean;
+    findingCounts: {
+        fail: number;
+        warn: number;
+        total: number;
+    };
+}
+export interface ValidationHistorySummary {
+    schemaVersion: "1.0.0";
+    runs: number;
+    latest: ValidationHistoryEntry;
+    previous: ValidationHistoryEntry | null;
+    delta: {
+        fail: number;
+        warn: number;
+        total: number;
+    };
+    regression: boolean;
+}
+export declare function buildValidationHistoryEntry(result: CheckResult, options: {
+    runtimeProbeEnabled: boolean;
+}): ValidationHistoryEntry;
+export declare function appendValidationHistoryEntry(historyPath: string, result: CheckResult, options: {
+    runtimeProbeEnabled: boolean;
+}): Promise<void>;
+export declare function readValidationHistory(historyPath: string): Promise<ValidationHistoryEntry[]>;
+export declare function summarizeValidationHistory(entries: ValidationHistoryEntry[]): ValidationHistorySummary;

package/dist/core/validation-history.js

@@ -0,0 +1,64 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+const statusRank = {
+    pass: 0,
+    warn: 1,
+    fail: 2
+};
+function countFindings(result) {
+    return {
+        fail: result.findings.filter((finding) => finding.severity === "fail").length,
+        warn: result.findings.filter((finding) => finding.severity === "warn").length,
+        total: result.findings.length
+    };
+}
+export function buildValidationHistoryEntry(result, options) {
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        targetPath: result.targetPath,
+        status: result.status,
+        runtimeProbeEnabled: options.runtimeProbeEnabled,
+        findingCounts: countFindings(result)
+    };
+}
+export async function appendValidationHistoryEntry(historyPath, result, options) {
+    const absoluteHistoryPath = path.resolve(historyPath);
+    await mkdir(path.dirname(absoluteHistoryPath), { recursive: true });
+    await writeFile(absoluteHistoryPath, `${JSON.stringify(buildValidationHistoryEntry(result, options))}\n`, { encoding: "utf8", flag: "a" });
+}
+export async function readValidationHistory(historyPath) {
+    const content = await readFile(path.resolve(historyPath), "utf8");
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export function summarizeValidationHistory(entries) {
+    if (entries.length === 0) {
+        throw new Error("No validation history entries found.");
+    }
+    const latest = entries[entries.length - 1];
+    const previous = entries.length > 1 ? entries[entries.length - 2] : null;
+    const delta = previous
+        ? {
+            fail: latest.findingCounts.fail - previous.findingCounts.fail,
+            warn: latest.findingCounts.warn - previous.findingCounts.warn,
+            total: latest.findingCounts.total - previous.findingCounts.total
+        }
+        : { fail: 0, warn: 0, total: 0 };
+    const regression = previous
+        ? statusRank[latest.status] > statusRank[previous.status]
+            || delta.fail > 0
+            || delta.warn > 0
+        : false;
+    return {
+        schemaVersion: "1.0.0",
+        runs: entries.length,
+        latest,
+        previous,
+        delta,
+        regression
+    };
+}

package/dist/reporting/render-history-summary.d.ts

@@ -0,0 +1,2 @@
+import { type ValidationHistoryEntry } from "../core/validation-history.js";
+export declare function renderHistorySummary(entries: ValidationHistoryEntry[]): string;

package/dist/reporting/render-history-summary.js

@@ -0,0 +1,23 @@
+import { summarizeValidationHistory } from "../core/validation-history.js";
+function formatDelta(value) {
+    return value > 0 ? `+${value}` : String(value);
+}
+export function renderHistorySummary(entries) {
+    const summary = summarizeValidationHistory(entries);
+    const { latest, previous } = summary;
+    const lines = [
+        "Validation History",
+        "==================",
+        `Runs: ${summary.runs}`,
+        `Latest: ${latest.status.toUpperCase()}`,
+        `Target: ${latest.targetPath}`,
+        `Generated: ${latest.generatedAt}`,
+        `Fail findings: ${latest.findingCounts.fail}`,
+        `Warn findings: ${latest.findingCounts.warn}`,
+        `Regression: ${summary.regression ? "YES" : "NO"}`
+    ];
+    if (previous) {
+        lines.push("", `Previous: ${previous.status.toUpperCase()}`, `Fail findings: ${formatDelta(summary.delta.fail)}`, `Warn findings: ${formatDelta(summary.delta.warn)}`);
+    }
+    return lines.join("\n");
+}

package/dist/run-cli.js

@@ -2,17 +2,22 @@ import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
+import { appendValidationHistoryEntry, readValidationHistory, summarizeValidationHistory } from "./core/validation-history.js";
 import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.js";
 import { applyInstallPreview, renderApplyInstallResult } from "./compatibility/apply-install-preview.js";
 import { buildClaudeDesktopInstallPreview, renderClaudeDesktopInstallPreview } from "./compatibility/claude-desktop-install-preview.js";
 import { buildCursorInstallPreview, renderCursorInstallPreview } from "./compatibility/cursor-install-preview.js";
+import { buildClineInstallPreview, renderClineInstallPreview } from "./compatibility/cline-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 { initPluginPackage } from "./core/init-plugin.js";
 import { runCheck } from "./index.js";
 import { renderInstalledSummary } from "./reporting/render-installed-summary.js";
 import { renderBadgeJson, renderBadgeMarkdown } from "./reporting/render-badge-report.js";
 import { renderCompatibilityScorecard } from "./reporting/render-compatibility-scorecard.js";
 import { renderCompatibilityReport } from "./reporting/render-compatibility-report.js";
+import { renderHistorySummary } from "./reporting/render-history-summary.js";
 import { renderJsonReport } from "./reporting/render-json-report.js";
 import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
 import { renderRuleExplanation } from "./reporting/render-rule-explanation.js";
@@ -32,7 +37,7 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
+    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");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -58,8 +63,27 @@ const compatibilityClientAliases = {
     mcp: "Generic MCP",
     "claude-desktop": "Claude Desktop",
     claude: "Claude Desktop",
-    cursor: "Cursor"
+    cursor: "Cursor",
+    cline: "Cline"
 };
+const checkProfiles = ["ci", "strict", "publish"];
+function parseCheckProfile(value) {
+    if (!value) {
+        return null;
+    }
+    return checkProfiles.includes(value)
+        ? value
+        : null;
+}
+function applyCheckProfile(config, profile) {
+    if (profile === "strict" || profile === "publish") {
+        return {
+            ...config,
+            failOnWarnings: true
+        };
+    }
+    return config;
+}
 function filterCompatibilityMatrix(matrix, clientFilter) {
     const client = compatibilityClientAliases[clientFilter.toLowerCase()];
     if (!client) {
@@ -105,6 +129,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStdout(renderInstalledPlugins(installedPlugins));
         return 0;
     }
+    if (command === "doctor") {
+        io.writeStdout(await renderEnvironmentDoctor(terminalContext));
+        return 0;
+    }
     if (command === "explain") {
         if (!maybePath || maybePath.startsWith("--")) {
             io.writeStderr("Missing finding id. Usage: codex-plugin-doctor explain <finding-id>");
@@ -118,6 +146,31 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStdout(renderRuleExplanation(rule));
         return 0;
     }
+    if (command === "history") {
+        if (!maybePath || maybePath.startsWith("--")) {
+            io.writeStderr("Missing history path. Usage: codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]");
+            return 2;
+        }
+        try {
+            const entries = await readValidationHistory(maybePath);
+            const summary = summarizeValidationHistory(entries);
+            const jsonOutput = remainingArgs.includes("--json");
+            const failOnRegression = remainingArgs.includes("--fail-on-regression");
+            io.writeStdout(jsonOutput
+                ? JSON.stringify(summary, null, 2)
+                : renderHistorySummary(entries));
+            if (failOnRegression && summary.regression) {
+                io.writeStderr("Validation history regression detected.");
+                return 1;
+            }
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unable to read validation history.";
+            io.writeStderr(message);
+            return 1;
+        }
+    }
     if (command === "self-test" || command === "demo") {
         const targetPath = resolveBundledSelfTestTarget();
         const runCheckImpl = options.runCheckImpl ?? runCheck;
@@ -142,6 +195,27 @@ export async function runCli(args, io = defaultIo, options = {}) {
         ].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)");
+            return 2;
+        }
+        const dryRun = remainingArgs.includes("--dry-run");
+        const apply = remainingArgs.includes("--apply");
+        const backup = remainingArgs.includes("--backup");
+        if (apply && !backup) {
+            io.writeStderr("Fix apply requires --backup.");
+            return 2;
+        }
+        if (dryRun === apply) {
+            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)));
+        return 0;
+    }
     if (command === "compat") {
         const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
         const compatFlags = maybePath && maybePath.startsWith("--")
@@ -166,8 +240,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         if ((installPreview || applyInstall) &&
             clientFilter?.toLowerCase() !== "claude-desktop" &&
-            clientFilter?.toLowerCase() !== "cursor") {
-            io.writeStderr("--install-preview and --apply require --client claude-desktop or --client cursor.");
+            clientFilter?.toLowerCase() !== "cursor" &&
+            clientFilter?.toLowerCase() !== "cline") {
+            io.writeStderr("--install-preview and --apply require --client claude-desktop, cursor, or cline.");
             return 2;
         }
         if (installPreview && applyInstall) {
@@ -180,20 +255,32 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         if (installPreview || applyInstall) {
             try {
-                const preview = clientFilter?.toLowerCase() === "cursor"
+                const normalizedClient = clientFilter?.toLowerCase();
+                const preview = normalizedClient === "cursor"
                     ? await buildCursorInstallPreview(targetPath, {
                         env: terminalContext.env,
                         platform: terminalContext.platform
                     })
-                    : await buildClaudeDesktopInstallPreview(targetPath, {
-                        env: terminalContext.env,
-                        platform: terminalContext.platform
-                    });
+                    : normalizedClient === "cline"
+                        ? await buildClineInstallPreview(targetPath, {
+                            env: terminalContext.env,
+                            platform: terminalContext.platform
+                        })
+                        : await buildClaudeDesktopInstallPreview(targetPath, {
+                            env: terminalContext.env,
+                            platform: terminalContext.platform
+                        });
                 const report = applyInstall
-                    ? renderApplyInstallResult(await applyInstallPreview(clientFilter?.toLowerCase() === "cursor" ? "Cursor" : "Claude Desktop", preview))
-                    : clientFilter?.toLowerCase() === "cursor"
+                    ? renderApplyInstallResult(await applyInstallPreview(normalizedClient === "cursor"
+                        ? "Cursor"
+                        : normalizedClient === "cline"
+                            ? "Cline"
+                            : "Claude Desktop", preview))
+                    : normalizedClient === "cursor"
                         ? renderCursorInstallPreview(preview)
-                        : renderClaudeDesktopInstallPreview(preview);
+                        : normalizedClient === "cline"
+                            ? renderClineInstallPreview(preview)
+                            : renderClaudeDesktopInstallPreview(preview);
                 if (outputPath) {
                     await writeFile(outputPath, report, "utf8");
                 }
@@ -260,6 +347,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const outputPath = outputIndex === -1 ? null : normalizedFlags[outputIndex + 1];
     const configIndex = normalizedFlags.indexOf("--config");
     const configPath = configIndex === -1 ? null : normalizedFlags[configIndex + 1];
+    const profileIndex = normalizedFlags.indexOf("--profile");
+    const profileName = profileIndex === -1 ? null : normalizedFlags[profileIndex + 1];
+    const checkProfile = parseCheckProfile(profileName);
+    const historyIndex = normalizedFlags.indexOf("--history");
+    const historyPath = historyIndex === -1 ? null : normalizedFlags[historyIndex + 1];
     if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
         io.writeStderr("Missing path after --output.");
         return 2;
@@ -268,10 +360,27 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("Missing path after --config.");
         return 2;
     }
+    if (profileIndex !== -1 && (!profileName || profileName.startsWith("--"))) {
+        io.writeStderr("Missing profile after --profile.");
+        return 2;
+    }
+    if (profileIndex !== -1 && !checkProfile) {
+        io.writeStderr("Unknown profile. Supported profiles: ci, strict, publish.");
+        return 2;
+    }
+    if (historyIndex !== -1 && (!historyPath || historyPath.startsWith("--"))) {
+        io.writeStderr("Missing path after --history.");
+        return 2;
+    }
     if (checkInstalled && (badgeJsonOutput || badgeMarkdownOutput)) {
         io.writeStderr("Badge output requires a single package target.");
         return 2;
     }
+    if (checkInstalled && historyPath) {
+        io.writeStderr("History output requires a single package target.");
+        return 2;
+    }
+    const effectiveRuntimeProbeEnabled = runtimeProbeEnabled || checkProfile === "publish";
     const outputPolicy = determineOutputPolicy({
         jsonOutput: jsonOutput || badgeJsonOutput,
         markdownOutput: markdownOutput || badgeMarkdownOutput,
@@ -297,11 +406,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
             checkedPlugins.push({
                 plugin,
                 result: applyDoctorConfig(await runCheckImpl(plugin.rootPath, {
-                    runtime: runtimeProbeEnabled,
-                    runtimeTranscript: runtimeProbeEnabled && verboseRuntime
+                    runtime: effectiveRuntimeProbeEnabled,
+                    runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
                         ? (line) => io.writeStderr(line)
                         : undefined
-                }), config)
+                }), applyCheckProfile(config, checkProfile))
             });
         }
         const report = installedSummary
@@ -310,9 +419,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 .map((item) => sarifOutput
                 ? renderSarifReport(item.result)
                 : markdownOutput
-                    ? buildMarkdownReport(item.result, { runtimeProbeEnabled })
+                    ? buildMarkdownReport(item.result, { runtimeProbeEnabled: effectiveRuntimeProbeEnabled })
                     : jsonOutput
-                        ? renderJsonReport(item.result, { runtimeProbeEnabled })
+                        ? renderJsonReport(item.result, { runtimeProbeEnabled: effectiveRuntimeProbeEnabled })
                         : renderTextReport(item.result, { ascii: outputPolicy.style === "ascii" }))
                 .join("\n\n");
         if (outputPath) {
@@ -327,11 +436,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
         : null;
     renderer?.start("Validating package");
     const result = applyDoctorConfig(await runCheckImpl(targetPath, {
-        runtime: runtimeProbeEnabled,
-        runtimeTranscript: runtimeProbeEnabled && verboseRuntime
+        runtime: effectiveRuntimeProbeEnabled,
+        runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
             ? (line) => io.writeStderr(line)
             : undefined
-    }), await loadDoctorConfig(targetPath, configPath));
+    }), applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile));
     if (renderer) {
         if (result.status === "fail") {
             renderer.stopFailure("Validation failed");
@@ -341,11 +450,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
     }
     const report = markdownOutput
-        ? buildMarkdownReport(result, { runtimeProbeEnabled })
+        ? buildMarkdownReport(result, { runtimeProbeEnabled: effectiveRuntimeProbeEnabled })
         : sarifOutput
             ? renderSarifReport(result)
             : jsonOutput
-                ? renderJsonReport(result, { runtimeProbeEnabled })
+                ? renderJsonReport(result, { runtimeProbeEnabled: effectiveRuntimeProbeEnabled })
                 : badgeJsonOutput
                     ? renderBadgeJson(result)
                     : badgeMarkdownOutput
@@ -354,6 +463,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
     if (outputPath) {
         await writeFile(outputPath, report, "utf8");
     }
+    if (historyPath) {
+        await appendValidationHistoryEntry(historyPath, result, {
+            runtimeProbeEnabled: effectiveRuntimeProbeEnabled
+        });
+    }
     io.writeStdout(report);
     return result.exitCode;
 }

package/package.json

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