Unverified Commit 52008001 authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

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: 's avatarv-work-app[bot] <262237222+v-work-app[bot]@users.noreply.github.com>
Co-authored-by: 's avatarClaude <noreply@anthropic.com>
Co-authored-by: 's avatarTobias Koppers <sokra@users.noreply.github.com>
parent 11c865c1
......@@ -669,6 +669,10 @@ internal
parseValidPositiveInteger
)
)
.addHelpText('after', ({ command }) => {
const port = (command.opts() as { port?: number }).port ?? 5748
return `\nExample:\n next internal query-trace --port ${port} --parent <id>`
})
.action((options) =>
import('../cli/internal/query-trace.js').then((mod) =>
mod.queryTraceCli(options)
......
......@@ -288,7 +288,7 @@ export async function startTurboTraceServerCli(
server.listen(httpPort, '127.0.0.1', () => {
console.log(
`Query this trace from the command line: next internal query-trace --help`
`Query this trace from the command line: next internal query-trace --help --port ${httpPort}`
)
console.log(
`Alternatively, connect an MCP client to http://127.0.0.1:${httpPort}/mcp`
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment