Report actual and requested debug port in xstep JSON output

[koriym]

Summary

Split out from an independent review of PR #89 (merged): a Nit noting that when the debug listener falls back from the configured port (9004) to an OS-assigned ephemeral port (see listenOnAvailablePort() / effectiveDebugPort, introduced in #89), that fact is only surfaced through log(), which is a silent no-op in --json mode (the default for xstep). A caller that only sees the JSON output - e.g. an AI client - had no way to learn a fallback happened or which port Xdebug actually bound to.

This PR adds two fields to xstep's JSON output:

• debug_port - the port the listener actually bound to. Always present.
• requested_port - the originally configured port. Present only when it differs from debug_port, i.e. only when a fallback occurred.

Both outputStepRecordingResults() and outputMultipleBreakResults() (the two JSON emission paths) now populate these via a shared addPortInfoToResult() helper, keeping the two paths consistent. The XstepJsonOutput phpstan-type and the public docs/schemas/xstep.json schema are updated to match. Field naming follows the existing debug_port precedent in getCurrentDebugContext().

Note: this was originally planned as a stacked PR on top of PR #89's branch, but #89 merged into 1.x while this change was being prepared, so it is now rebased directly onto 1.x as a normal PR.

Test plan

• vendor/bin/phpunit --no-coverage - full suite passes (312 tests, 851 assertions, 7 pre-existing skips)
• composer cs (phpcs) - 0 violations
• composer sa (phpstan level max, src/) - 0 errors
• Added 4 unit tests in tests/Unit/DebugServerTest.php covering both output methods x both cases (no fallback / fallback), using reflection to set effectiveDebugPort/debugPort directly (no mocks)
• Manually verified with a real Xdebug session: ran bin/xstep normally and confirmed debug_port appears without requested_port; then occupied port 9004 with another process and confirmed both debug_port (ephemeral) and requested_port: 9004 appear correctly

Summary by CodeRabbit

• New Features

  • Step/debug JSON output now includes the actual port being used for debugging.
  • When a fallback port is assigned, the original requested port is also included for clarity.

• Documentation

  • Updated the JSON schema to describe the new port-related fields in step output.

• Bug Fixes

  • Improved consistency in debug output across single-step and multi-breakpoint flows.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7f028f39-b3ad-4430-99e0-f569e10886a3

📥 Commits

Reviewing files that changed from the base of the PR and between 96534e4 and 4a5a855.

📒 Files selected for processing (3)

• docs/schemas/xstep.json
• src/DebugServer.php
• tests/Unit/DebugServerTest.php

---

📝 Walkthrough

Walkthrough

This PR adds debug_port and requested_port fields to DebugServer's JSON output, documenting the actual Xdebug listener port and any fallback from the originally requested port. Includes schema updates, a new helper method, wiring into two output paths, and regression tests.

Changes

Debug Port Reporting

Layer / File(s)	Summary
Schema and port info helper docs/schemas/xstep.json, src/DebugServer.php	Adds debug_port/requested_port schema properties and PHPStan type doc, plus a new addPortInfoToResult() helper that injects debug_port always and requested_port only on fallback.
Wiring into JSON output paths src/DebugServer.php	Calls addPortInfoToResult() from both outputStepRecordingResults() and outputMultipleBreakResults() before JSON emission.
Regression tests for port fields tests/Unit/DebugServerTest.php	Adds four tests verifying debug_port/requested_port behavior with and without port fallback across both output paths.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• koriym/xdebug-mcp#68: Both PRs modify JSON emission logic in outputMultipleBreakResults() in src/DebugServer.php.

Poem

A port once hopped when its home was full,
Now the JSON tells the tale, clear and lawful.
debug_port shows where the listener stands,
requested_port notes the fallback plans.
Hop hop hooray, the tests all pass! 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding actual and requested debug port fields to xstep JSON output.
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.

✨ 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 xstep-json-report-effective-port

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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