v0.10.1

Patch release for safe-fix path hardening.

Fixed

• Prevented fix --apply --backup and fix --interactive --backup from creating or modifying files outside the plugin root when manifest paths contain traversal attempts.
• Stopped fix-plan generation from reading/scaffolding skills through root-escaping skills paths.

Release Validation

• npm package codex-plugin-doctor@0.10.1 is published with the latest dist-tag.
• GitHub Actions CI passed on the release commit.
• npm test passed with 151 tests.
• npm audit --audit-level=moderate reported 0 vulnerabilities.
• npm run release-check passed before publication.

v0.10.0

Feature release for version awareness, local client readiness checks, installed plugin compatibility summaries, targeted starter templates, and selective safe fixes.

Added

• doctor --update-check compares the installed CLI version with the latest npm version.
• doctor clients reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness.
• check --installed --compat --all-summary combines installed plugin validation with cross-client compatibility summaries.
• init [path] --template skill-only|mcp-stdio|mcp-http|full-runtime scaffolds targeted starter packages.
• fix --interactive --backup now accepts selected action numbers such as 1,3.

Release Validation

• npm package codex-plugin-doctor@0.10.0 is published with latest dist-tag.
• GitHub Actions CI passed on the release commit.
• npm publish --dry-run --access public passed before publication.

v0.9.0

v0.9.0 Release Notes

Release Focus

v0.9.0 improves the day-one operator experience around Codex Plugin Doctor. The release makes all-client compatibility checks explicit, adds inline finding explanations, improves first-run guidance, adds prompted safe fixes, and introduces a release preflight script for maintainers.

Highlights

• compat <path> --all makes the full Codex, Generic MCP, Claude Desktop, Cursor, Cline, and Windsurf matrix explicit.
• check <path> --explain adds rule-catalog context directly to text reports.
• Empty CLI usage and doctor text output now include recommended next commands.
• npm run release-check validates clean git state, npm version availability, tag availability, tests, build, and pack dry-run before release.
• fix <path> --interactive --backup shows the safe fix plan first, then applies only after a yes confirmation.

Interactive Fix Safety

Interactive fix mode keeps the existing safe-fix constraints. It still requires --backup, shows the planned deterministic actions first, and cancels without file changes unless the user types yes.

Release Preflight

Use this before tagging and publishing a new version:

npm run release-check

The script is intentionally stricter than prepare-release: it rejects dirty worktrees, already-published package versions, and existing local or remote version tags before running tests, build, and npm pack --dry-run.

Verification

• npm test
• npm run build
• npm pack --dry-run
• GitHub Actions CI

Upgrade Notes

Pin both the action ref and npm CLI version for reproducible CI:

- uses: Esquetta/CodexPluginDoctor@v0.9.0
  with:
    version: "0.9.0"
    path: .
    runtime: "true"

v0.8.0

v0.8.0 Release Notes

Release Focus

v0.8.0 makes Codex Plugin Doctor easier to wire into automation and new plugin repositories. The release adds JSON output for fix and environment doctor workflows, expands guarded scaffolding, introduces Windsurf compatibility checks, and adds a CI workflow initializer.

Highlights

• fix <path> --dry-run --json emits machine-readable safe fix plans for scripts and CI dashboards.
• doctor --json reports local package, Node, npm, Codex home, and plugin cache diagnostics as structured JSON.
• compat --client windsurf checks Windsurf MCP config readiness.
• compat --client windsurf --install-preview emits a non-mutating Windsurf config snippet.
• init-ci [path] creates .github/workflows/codex-plugin-doctor.yml with a pinned action ref and npm CLI version.
• Safe fix scaffolding now covers missing SKILL.md, missing skill frontmatter, and default .mcp.json creation when declared MCP servers are missing.

Fix Scope

The fix engine remains intentionally conservative. --apply --backup only writes deterministic scaffolding changes and backs up changed files first. Security findings, malformed user-authored configs, secret handling, and ambiguous runtime failures remain manual.

Windsurf Compatibility

Windsurf support checks the documented MCP config file path: ~/.codeium/windsurf/mcp_config.json, or <WINDSURF_DIR>/mcp_config.json when WINDSURF_DIR is set.

CI Bootstrap

Run this in a plugin repository to add a validation workflow:

codex-plugin-doctor init-ci .

The generated workflow pins both the GitHub Action ref and npm CLI version for reproducible checks.

Verification

• npm test
• npm run build
• npm pack --dry-run

Upgrade Notes

Pin both the action ref and npm CLI version for reproducible CI:

- uses: Esquetta/CodexPluginDoctor@v0.8.0
  with:
    version: "0.8.0"
    path: .
    runtime: "true"

v0.7.0

v0.7.0 Release Notes

Release Focus

v0.7.0 moves Codex Plugin Doctor from reporting problems toward helping users act on them. The release adds safe fix planning, guarded apply flows, named validation profiles, a local environment doctor, and the first Cline compatibility adapter.

Highlights

• fix <path> --dry-run renders a safe automatic fix plan without changing files.
• fix <path> --apply --backup applies supported safe fixes only after creating backups.
• check --profile ci|strict|publish gives CI and release workflows named validation policies.
• doctor reports local package, Node, npm, Codex home, and plugin cache diagnostics.
• compat --client cline checks Cline MCP config readiness.
• compat --client cline --install-preview emits a non-mutating Cline config snippet.

Fix Scope

The first fix engine intentionally handles only deterministic safe fixes: manifest defaults and missing skills directory creation. Security-sensitive findings, malformed MCP configs, hard-coded secrets, and path traversal findings remain manual.

Cline Compatibility

Cline support uses the documented MCP settings file path: ~/.cline/data/settings/cline_mcp_settings.json, or <CLINE_DIR>/data/settings/cline_mcp_settings.json when CLINE_DIR is set.

Verification

• npm test
• npm run build
• npm pack --dry-run

Upgrade Notes

Pin both the action ref and npm CLI version for reproducible CI:

- uses: Esquetta/CodexPluginDoctor@v0.7.0
  with:
    version: "0.7.0"
    path: .
    runtime: "true"

v0.6.0

v0.6.0 Release Notes

Release Focus

v0.6.0 turns local validation history into a CI-ready signal. Plugin authors can append JSONL snapshots, inspect the latest trend, emit machine-readable summaries, and fail pipelines when validation quality regresses.

Highlights

• check --history <path> appends compact JSONL validation snapshots for single-package checks.
• history <path> renders latest vs previous status and finding-count deltas.
• history <path> --json emits automation-friendly latest, previous, delta, and regression fields.
• history <path> --fail-on-regression exits non-zero when the latest run is worse than the previous run.
• The GitHub Action now accepts history: validation-history.jsonl and passes it to the CLI.

Regression Definition

The history gate treats the latest run as regressed when the status gets worse (PASS to WARN or FAIL, WARN to FAIL) or when fail/warn finding counts increase compared with the previous run.

Verification

• npm test -- tests/cli-command.test.ts
• npm test -- tests/action-metadata.test.ts
• npm test
• npm run build
• npm pack --dry-run

Upgrade Notes

Pin both the action ref and npm CLI version for reproducible CI:

- uses: Esquetta/CodexPluginDoctor@v0.6.0
  with:
    version: "0.6.0"
    path: .
    runtime: "true"
    history: validation-history.jsonl

v0.5.0

Codex Plugin Doctor v0.5.0 Release Notes

Release Focus

v0.5.0 improves public adoption by making validation status easier to surface in GitHub workflows and project READMEs.

The release adds badge output formats and strengthens GitHub Action consumer documentation.

Highlights

• check --badge-json emits Shields endpoint-compatible JSON.
• check --badge-markdown emits a static shields.io Markdown badge.
• Badge output maps PASS to brightgreen, WARN to yellow, and FAIL to red.
• Badge output is intentionally limited to single package checks, avoiding ambiguous installed-cache summaries.
• The composite GitHub Action now accepts a version input so consumers can pin the npm CLI version independently from the action ref.
• GitHub Action docs now include pinned usage, runtime probing, SARIF, installed-cache, and badge artifact examples.

Verification

Release verification should include:

• npm test
• npm run build
• node dist/cli.js check tests/fixtures/valid-plugin-with-mcp --badge-json
• node dist/cli.js check tests/fixtures/heuristic-long-plugin-description --badge-markdown
• npm pack --dry-run

Operator Notes

Use --badge-json when another service will host or consume Shields endpoint JSON. Use --badge-markdown when a static README or release note should show the current validation result directly.

v0.4.0

Codex Plugin Doctor v0.4.0 Release Notes

Release Focus

v0.4.0 turns compatibility guidance into safer local action.

The release adds explicit apply flows for Claude Desktop and Cursor, keeps non-mutating install previews, and gives new users a one-command self-test after npm installation.

Highlights

• compat --client claude-desktop --apply --backup merges MCP servers into Claude Desktop config after creating a timestamped backup.
• compat --client cursor --apply --backup merges MCP servers into Cursor config after creating a timestamped backup.
• Apply mode refuses to overwrite duplicate MCP server names.
• codex-plugin-doctor self-test runs the bundled runtime sample through static validation, runtime MCP probes, and compatibility scoring.
• JSON config parsing now tolerates UTF-8 BOMs commonly produced by Windows tooling.
• The runtime sample is included in the npm package so self-test works after global install.

Verification

Release verification should include:

• npm test
• npm run build
• node dist/cli.js self-test --no-animations
• temp-profile apply smoke for Cursor or Claude Desktop
• npm pack --dry-run

Operator Notes

Apply mode is intentionally conservative. Users must pass both --apply and --backup, and duplicate server names are treated as a blocking safety condition.

v0.3.0

v0.3.0 Release Notes

Release date: 2026-04-30

Summary

v0.3.0 expands the compatibility matrix with a real Cursor adapter and adds scorecard reporting for quick cross-client readiness checks.

The release keeps the same safe-by-default posture: Cursor install preview prints a mergeable snippet but never writes to local MCP config files.

Highlights

• Added compat --client cursor for Cursor MCP compatibility checks.
• Added Cursor project/global config detection.
• Added malformed Cursor mcp.json detection.
• Added Cursor duplicate MCP server name warnings.
• Added compat --client cursor --install-preview for non-mutating Cursor config snippets.
• Added compat --scorecard for compact client scores.

Example Commands

codex-plugin-doctor compat . --client cursor
codex-plugin-doctor compat . --client cursor --install-preview
codex-plugin-doctor compat . --scorecard
codex-plugin-doctor compat . --client cursor --scorecard

Verification

Release preparation should pass:

npm test
npm run build
npm pack --dry-run
node dist/cli.js compat examples/codex-doctor-runtime --client cursor --install-preview
node dist/cli.js compat examples/codex-doctor-runtime --scorecard

v0.2.1

v0.2.1 Release Notes

Release date: 2026-04-30

Summary

v0.2.1 makes the Claude Desktop compatibility row practical for local developer machines.

The release checks whether Claude Desktop can accept a package, detects broken local config files before users add new servers, warns on duplicate MCP server names, and can print a non-mutating install preview snippet.

Highlights

• Added local Claude Desktop config discovery for compat --client claude-desktop.
• Added malformed claude_desktop_config.json detection.
• Added duplicate MCP server name warnings.
• Added compat --client claude-desktop --install-preview to print the JSON snippet that should be merged into Claude Desktop config.
• Kept install preview non-mutating: it never writes to claude_desktop_config.json.

Example Commands

codex-plugin-doctor compat . --client claude-desktop
codex-plugin-doctor compat . --client claude-desktop --install-preview
codex-plugin-doctor compat . --client claude-desktop --json

Verification

Release preparation should pass:

npm test
npm run build
npm pack --dry-run
node dist/cli.js compat examples/codex-doctor-runtime --client claude-desktop --install-preview