docs: clarify README and demo smoke test scope by koriym · Pull Request #76 · koriym/xdebug-mcp

koriym · 2026-04-28T09:22:20Z

Summary

Clarify the README so the project positioning matches the current implementation: CLI is the primary interface, while MCP remains supported for the core one-shot analysis tools.
Tighten demo/run-demo.sh so composer demo is a reliable smoke test for the non-interactive CLI tools.

Changes

README: describe AI integrations through Claude Code plugin, Codex Skill, or MCP-capable clients.
README: document the MCP/CLI boundary explicitly. MCP exposes xtrace, xprofile, xstep, xcoverage, and xback; xcompare and xrepl are CLI-only.
demo/run-demo.sh: clarify that interactive xrepl and the long-running xdebug-mcp server are out of scope for the smoke test, while xrepl --help is checked for command availability.
demo/run-demo.sh: fail fast if changing to the repository root fails.
demo/run-demo.sh: preserve the actual command exit code before reporting failures.
demo/run-demo.sh: use a separator that does not look like a Git conflict marker.

Test plan

composer demo
composer test
composer tests
printf "%s\n" "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}" | php bin/xdebug-mcp returns the MCP tool list

koriym · 2026-04-28T09:22:25Z

@coderabbitai review

coderabbitai · 2026-04-28T09:22:51Z

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai · 2026-04-28T09:24:06Z

📝 Walkthrough

Walkthrough

The pull request adds two new CLI entrypoints (xrepl and xcompare) to the Composer package configuration and updates README documentation examples to reflect current debugging workflows, including clarifications on tool usage and command options.

Changes

Cohort / File(s)	Summary
Documentation `README.md`	Updated CLI examples: `check-env` discovery via Composer bin-dir, removed `--exit-on-break` flag from `xstep` examples, added JSON output example with truncation, clarified `xrepl` as the interactive debugger and replaced REPL example accordingly.
Package Configuration `composer.json`	Added `bin/xrepl` and `bin/xcompare` to the `"bin"` list to expose these commands as installable Composer executables.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

PR #3: Updates README documentation content and CLI examples; directly related to the documentation changes in this PR.
PR #71: Modifies bin/xcompare implementation and tests; related to exposing bin/xcompare as a new CLI entrypoint in this PR.
PR #38: Updates CLI surface by modifying README examples and the Composer bin list; related to the entrypoint configuration and documentation changes.

Suggested reviewers

sourcery-ai

Poem

🐰✨ Two new commands hop into view,
xrepl and xcompare—fresh paths to pursue!
The README now gleams with examples refined,
A debugger's delight, more clearly defined.
Composer knows well these companions so bright! 🎯

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title 'docs: clarify README and demo smoke test scope' is vague and does not accurately reflect the main changes, which include both README CLI example fixes and exposing new CLI commands via composer.json.	Revise the title to something more specific like 'docs: fix README CLI examples and expose xrepl/xcompare via composer bin' to clearly convey the actual changes made.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch readme-cli-discoverability

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

This PR aligns the repository’s CLI documentation with what a composer global require koriym/xdebug-mcp installation actually exposes, and adds a demo runner script to exercise the documented CLI tools.

Changes:

Expose xrepl and xcompare as Composer-installed binaries by adding them to composer.json’s bin array.
Update README CLI examples to remove an unsupported xstep flag, document new xstep JSON flags, and correct the recommended check-env path resolution.
Add demo/run-demo.sh plus a composer demo script to run the README’s demo commands as a smoke test.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
demo/run-demo.sh	Adds a bash smoke-test runner for the README demo commands with PASS/FAIL reporting.
composer.json	Publishes `bin/xrepl` and `bin/xcompare` via Composer bin shims; adds a `demo` Composer script.
README.md	Fixes CLI examples (xrepl vs xstep REPL usage, removes unsupported flag), documents new flags, and makes `check-env` path robust across Composer homes.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-28T09:33:21Z

+# Run every CLI command documented in README.md against the demo scripts
+# and report PASS/FAIL for each. Used both as a developer smoke test
+# (`composer demo`) and as a hands-on tour of every tool.


The header comment says this script runs every CLI command documented in README.md, but the script currently only exercises xstep/xtrace/xprofile/xcoverage/xback/xcompare (and skips xdebug-mcp/check-env; xrepl is interactive). Consider either updating the comment to reflect the actual scope (e.g., non-interactive tools only) or adding coverage for the missing commands where feasible.

Suggested change

# Run every CLI command documented in README.md against the demo scripts

# and report PASS/FAIL for each. Used both as a developer smoke test

# (`composer demo`) and as a hands-on tour of every tool.

# Run the non-interactive CLI demo commands against the demo scripts

# and report PASS/FAIL for each. Used both as a developer smoke test

# (`composer demo`) and as a hands-on tour of the tools exercised here.

@copilot Fixed in commit 4b5a55a: header now states the script exercises only the non-interactive CLI tools, calls out xrepl/xdebug-mcp as out of scope, and adds a presence-check run for xrepl --help. check-env is intentionally excluded — it returns non-zero when warnings exist (e.g. Xdebug always loaded), so it can't be a hard PASS check.

koriym · 2026-04-28T22:10:51Z

@coderabbitai full review

coderabbitai · 2026-04-28T22:10:57Z

✅ Actions performed

Full review triggered.

- Narrow header comment to non-interactive CLI tools, document the xrepl/xdebug-mcp scope exclusion (Copilot review on #76). - Fail fast if cd to repo root fails (Copilot review on #76). - Fix run() so the FAIL message reports the failing command's exit status; previously $? after the if was always 0, masking the real code. - Add xrepl --help presence smoke check (CodeRabbit review on #77).

…lity # Conflicts: # demo/run-demo.sh

coderabbitai Bot approved these changes Apr 28, 2026

View reviewed changes

koriym requested a review from Copilot April 28, 2026 09:29

Copilot started reviewing on behalf of koriym April 28, 2026 09:29 View session

Copilot AI reviewed Apr 28, 2026

View reviewed changes

koriym mentioned this pull request Apr 28, 2026

chore: prepare release notes and clean up stale 8.1 references #77

Merged

4 tasks

Copilot started work on behalf of koriym April 28, 2026 22:25 View session

Copilot finished work on behalf of koriym April 28, 2026 22:28

Copilot started work on behalf of koriym April 28, 2026 22:28 View session

Copilot finished work on behalf of koriym April 28, 2026 22:29

koriym added 3 commits April 30, 2026 00:56

Merge remote-tracking branch 'origin/1.x' into readme-cli-discoverabi…

ae4607e

…lity # Conflicts: # demo/run-demo.sh

test(demo): avoid conflict marker-like separator

77b3bbd

docs: clarify MCP and CLI tool boundaries

327f93f

koriym changed the title ~~docs: fix README CLI examples and expose xrepl/xcompare via composer bin~~ docs: clarify README and demo smoke test scope Apr 29, 2026

koriym merged commit 7b5883a into 1.x Apr 29, 2026
7 checks passed

koriym deleted the readme-cli-discoverability branch April 29, 2026 16:07

koriym mentioned this pull request Apr 29, 2026

chore: release v0.9.0 #78

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: clarify README and demo smoke test scope#76

docs: clarify README and demo smoke test scope#76
koriym merged 4 commits into
1.xfrom
readme-cli-discoverability

koriym commented Apr 28, 2026 •

edited

Loading

Uh oh!

koriym commented Apr 28, 2026

Uh oh!

coderabbitai Bot commented Apr 28, 2026

Uh oh!

coderabbitai Bot commented Apr 28, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

koriym Apr 28, 2026

Uh oh!

Uh oh!

koriym commented Apr 28, 2026

Uh oh!

coderabbitai Bot commented Apr 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

koriym commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test plan

Uh oh!

koriym commented Apr 28, 2026

Uh oh!

coderabbitai Bot commented Apr 28, 2026

Uh oh!

coderabbitai Bot commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

koriym Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

koriym commented Apr 28, 2026

Uh oh!

coderabbitai Bot commented Apr 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

koriym commented Apr 28, 2026 •

edited

Loading

coderabbitai Bot commented Apr 28, 2026 •

edited

Loading