next.js

52008001 - Include `--port` in `next internal query-trace` startup hint and help example (#93961)

Include `--port` in `next internal query-trace` startup hint and help example (#93961) ### What? When the Turbopack trace server starts (via `next internal trace <file>`), it prints a hint suggesting users run `next internal query-trace --help` from another terminal. That suggestion doesn't include the actual MCP port the server is listening on, so anyone who copies it verbatim ends up querying the default port (`5748`) — which is wrong as soon as the server picked a non-default `--mcp-port`. This PR threads the running MCP port into both the startup hint and the `query-trace --help` output so the suggested command lines target the server that's actually running. Before: ``` Trace file opened Turbopack trace server started. View trace at https://trace.nextjs.org?port=5750 Query this trace from the command line: next internal query-trace --help Alternatively, connect an MCP client to http://127.0.0.1:5751/mcp ``` After: ``` Trace file opened Turbopack trace server started. View trace at https://trace.nextjs.org?port=5750 Query this trace from the command line: next internal query-trace --help --port 5751 Alternatively, connect an MCP client to http://127.0.0.1:5751/mcp ``` And `next internal query-trace --help --port 5751` now ends with: ``` Example: next internal query-trace --port 5751 --parent <id> ``` ### Why? The MCP HTTP port is dynamic (defaults to `wsPort + 1`, and `--mcp-port` can override it). Without echoing it into the hint, the suggested follow-up command silently connects to the wrong port and the user gets a confusing "Could not connect to trace server on port 5748" error instead of a useful response. Surfacing the right `--port` value at the point the user copies the command keeps the discovery flow self-consistent. ### How? - `packages/next/src/cli/internal/turbo-trace-server.ts`: the startup hint now interpolates the actual `httpPort` the MCP server bound to, so it prints `next internal query-trace --help --port <httpPort>`. - `packages/next/src/bin/next.ts`: the `query-trace` command gains an `.addHelpText('after', …)` block that reads the parsed `--port` option (falling back to the default `5748`) and appends an `Example:` section using that value. Passing `--port <port>` alongside `--help` therefore produces an immediately-runnable example for that specific server. The `--port` CLI option itself, its default, and parsing/validation are unchanged. ### Verification Built `next` and ran: - `next internal query-trace --help` → example shows `--port 5748` (default). - `next internal query-trace --help --port 5751` → example shows `--port 5751`. - `next internal query-trace --port 5751 --help` → example shows `--port 5751`. The existing `test/e2e/turbopack-trace-server-query/turbopack-trace-server.test.ts` suite still matches the substrings it asserts on (`next internal trace <file>` and `next internal query-trace --help`). <!-- NEXT_JS_LLM_PR --> Co-authored-by: v-work-app[bot] <262237222+v-work-app[bot]@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Tobias Koppers <sokra@users.noreply.github.com>