feat(agentic): add --base to devframe connect port probes

[zahidzorbaz]

Description

devframe connect --port <n> couldn't reach a devframe mounted below the root of its host, such as Vite DevTools at /__devtools/. When it failed, it reported the misleading DF0051 ("no MCP endpoint, restart with --mcp"). This PR fixes both parts of the problem.

• fix(devframe): only accept a JSON object as connection meta. probeDevframeOrigin counted any 2xx answer as a devframe and fell back to {} for an unparseable body. A host with an SPA fallback (Vite serving index.html) therefore passed as a devframe with no MCP route. A candidate now counts only when it answers with a JSON object. With this change:
  • a --port probe on the wrong path yields "no instance" (DF0050) instead of a phantom mcp: null instance;
  • registry liveness checks prune a stale record whose port now serves an unrelated app.
• feat(agentic): --base <path> for devframe connect port probes. There is a new base option in ConnectServerOptions, exposed as the --base CLI flag (default /). The explicit port probes look for __connection.json under that base. The advertised MCP path is resolved against the same base, as instance-shell already does for registry records. No mount path is hardcoded. Registry records keep their own basePath and ignore --base. The CLI help, the "no instances" hint and the MCP adapter's Discovery section document the flag. probePort is exported for focused tests, following the precedent of resolveAuthToken and buildInstanceRequestHeaders, and the tsnapi snapshot for @devframes/agentic/connect is updated to match.

Verified against a live Vite 8.3 + @vitejs/devtools 0.7.5 dev server with an empty registry:

	before	after
--port 5174	phantom port-5174, mcp: null, call-tool → DF0051	no instance, call-tool → DF0050
--port 5174 --base /__devtools/	flag doesn't exist	mcp.url …/__devtools/__mcp, 11 tools, read-only call-tool succeeds

Linked Issues

Closes #403

Additional context

• fix: register Vite DevTools for devframe discovery vitejs/devtools#579 (merged, not yet released) registers Vite DevTools in the instance registry, so default discovery will work there once it ships. This PR covers the --port fallback and the probe itself.
• Tests:
  • instance-registry.test.ts covers an HTML SPA fallback, a non-object JSON body, meta under a non-root base, and pruning a record whose port serves an SPA.
  • connect.test.ts covers probePort with a base, base normalization, and a root that serves only the SPA fallback.
  • cli/main.test.ts checks the help output.
  • The registry tests fail on main. The new probePort tests fail on main only because probePort isn't exported there.
• Gates run locally on Windows 11 / Node 24.21: pnpm lint, pnpm knip, pnpm typecheck and pnpm build pass. pnpm test has two failures unrelated to this change:
  • tests/exports.test.ts > devframe > dts: ./internal also fails on a clean main checkout. It's an ordering difference in the snapshot (importAgenticMcp sorted differently). This PR doesn't touch that snapshot.
  • src/utils/serve-static.test.ts hits intermittent ETIMEDOUT connecting to its local server under full-suite load. A different test fails on each run, and the file passes on its own, both on main and on this branch.

🤖 Generated with Claude Code

[coldtea-pr-lens]

◈ PR Lens

🟢 +0 new · 🟠 ~3 changed · 🔴 -0 removed · 1 flow · 3 files · commit f8ee937

Architecture

3 components touched across 3 lanes.

Play the interactive walkthrough

Inside the changed components — 2 views

Component view — CLI base path resolution

How CLI connect passes the base path and resolves relative MCP tool endpoints.

Component view — Origin probe and JSON validation

How the instance registry validates JSON connection metadata and ignores HTML SPA fallbacks.

Data flow

Probing instance with base path

Follow each request, response and payload

View

• Architecture lens
• Data flow lens
• Expand every detail

Tip

Run npx skills add coldteadotai/pr-lens, then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."

🪧 More tips

• Run npx @coldtea/pr-lens-cli analyze --base origin/main on a branch, then npx @coldtea/pr-lens-cli render .pr-lens/graph.json. Same lenses, your own model key, before the pull request exists
• Untick Architecture lens or Data flow lens under View to hide a diagram, or tick Expand every detail to open every section. The comment redraws in a few seconds
• Click the link under each diagram to open it on a canvas you can zoom, pan and step through
• The diagrams are links. Click one to open it on the canvas, then press W or click play to walk through the change
• Open a diagram on the canvas, then press W or click play to walk through the change one step at a time
• The CLI's render reads .github/pr-lens.yml and applies your renames, exclusions and lane pins at draw time
• Set github.comment.collapsed: true in .github/pr-lens.yml to fold the comment behind one View architecture and data flow row. Drawing still runs on every push
• Set github.draw: on-demand in .github/pr-lens.yml and PR Lens stops drawing every push. Comment @pr-lens draw on a pull request when you want that one drawn
• Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and your model provider's key as its api-key to run PR Lens from your own CI. Any /chat/completions endpoint works
• Push a commit and the comment redraws for the new head. A slow older run never overwrites a newer one
• Switch GitHub to dark mode and the diagrams follow. The moving dots are this pull request's data in motion

---

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

❤️ Share

• X
• Bluesky
• Mastodon
• Reddit
• LinkedIn

[vercel]

@zahidzorbaz is attempting to deploy a commit to the NuxtLabs Team on Vercel.

A member of the Team first needs to authorize it.