fix(devframe): only accept a JSON object as connection meta

`probeDevframeOrigin` took any 2xx answer as a live devframe and fell back
to `{}` when the body did not parse. A host with an SPA fallback (Vite
serving `index.html` for unknown paths) therefore passed as a devframe
with no MCP route: `devframe connect --port` listed a phantom instance and
failed with DF0051 instead of DF0050, and registry liveness checks kept
stale records whose port now serves an unrelated app.

A candidate now counts only when it answers with a JSON object.

Refs #403

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: zahidzorbaz

packages/devframe/src/node/instance-registry.test.ts

@@ -7,6 +7,7 @@ import { join } from 'pathe'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import {
   listLiveDevframeInstances,
+  probeDevframeOrigin,
   readDevframeInstances,
   registerDevframeInstance,
 } from './instance-registry'
@@ -142,3 +143,82 @@ describe('instance registry', () => {
     }
   })
 })
+
+describe('probeDevframeOrigin', () => {
+  // A host with an SPA fallback: every unknown path answers `200 text/html`
+  // (Vite serving `index.html`); the real meta lives under `/__devtools/`.
+  async function startSpaFallbackServer(): Promise<{ origin: string, port: number, close: () => Promise<void> }> {
+    const server = createServer((req, res) => {
+      if (req.url === '/__devtools/__connection.json') {
+        res.writeHead(200, { 'content-type': 'application/json' })
+        res.end('{"backend":"websocket","mcp":{"path":"__mcp"}}')
+        return
+      }
+      if (req.url === '/array/__connection.json') {
+        res.writeHead(200, { 'content-type': 'application/json' })
+        res.end('[]')
+        return
+      }
+      res.writeHead(200, { 'content-type': 'text/html' })
+      res.end('<!doctype html><html><body><div id="app"></div></body></html>')
+    })
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+    const port = (server.address() as AddressInfo).port
+    return {
+      origin: `http://127.0.0.1:${port}`,
+      port,
+      close: () => new Promise<void>(resolve => server.close(() => resolve())),
+    }
+  }
+
+  it('does not take an HTML SPA fallback for a devframe', async () => {
+    const spa = await startSpaFallbackServer()
+    try {
+      expect(await probeDevframeOrigin(spa.origin, '/', 2000)).toBeNull()
+    }
+    finally {
+      await spa.close()
+    }
+  })
+
+  it('does not take a non-object JSON body for connection meta', async () => {
+    const spa = await startSpaFallbackServer()
+    try {
+      expect(await probeDevframeOrigin(spa.origin, '/array/', 2000)).toBeNull()
+    }
+    finally {
+      await spa.close()
+    }
+  })
+
+  it('finds the connection meta under a non-root base', async () => {
+    const spa = await startSpaFallbackServer()
+    try {
+      const probed = await probeDevframeOrigin(spa.origin, '/__devtools/', 2000)
+      expect(probed).toEqual({ origin: spa.origin, meta: { backend: 'websocket', mcp: { path: '__mcp' } } })
+    }
+    finally {
+      await spa.close()
+    }
+  })
+
+  it('prunes a registry record whose port now serves an unrelated SPA', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'devframe-registry-'))
+    const spa = await startSpaFallbackServer()
+    try {
+      registerDevframeInstance(makeRecord({
+        pid: 2000,
+        port: spa.port,
+        origin: spa.origin,
+      }), { instancesDir: dir })
+
+      const { live, pruned } = await listLiveDevframeInstances({ instancesDir: dir, timeoutMs: 2000 })
+      expect(live).toEqual([])
+      expect(pruned.map(r => r.pid)).toEqual([2000])
+      expect(readdirSync(dir)).toEqual([])
+    }
+    finally {
+      await spa.close()
+    }
+  })
+})

packages/devframe/src/node/instance-registry.ts

@@ -180,15 +180,17 @@ function originCandidates(origin: string): string[] {
 export interface ProbedDevframeOrigin {
   /** The origin that answered (may be an explicit address family for a `localhost` bind). */
   origin: string
-  /** The parsed `__connection.json` payload (`{}` when unparseable). */
+  /** The parsed `__connection.json` payload (always a JSON object). */
   meta: { mcp?: { path: string, port?: number } }
 }
 
 /**
  * Probe `<origin><basePath>__connection.json`, trying each dialable
  * candidate for the origin (see {@link originCandidates}). The single
  * probe primitive behind both registry liveness checks and the
- * connector's explicit `--port` probes.
+ * connector's explicit `--port` probes. A candidate counts only when it
+ * answers `2xx` with a JSON object; anything else (an HTML SPA fallback, a
+ * JSON array, an unparseable body) is treated as "no devframe here".
  *
  * @internal
  */
@@ -205,8 +207,14 @@ export async function probeDevframeOrigin(
       })
       if (!response.ok)
         continue
-      const meta = await response.json().catch(() => ({})) as ProbedDevframeOrigin['meta']
-      return { origin: candidate, meta }
+      // Only a JSON object is connection meta. Host frameworks with an SPA
+      // fallback (Vite serving `index.html` for any unknown path) answer a
+      // wrong base with `200 text/html`; that is not a devframe, so it must
+      // not pass as a live instance with no MCP route.
+      const meta: unknown = await response.json().catch(() => undefined)
+      if (!meta || typeof meta !== 'object' || Array.isArray(meta))
+        continue
+      return { origin: candidate, meta: meta as ProbedDevframeOrigin['meta'] }
     }
     catch {
       // Try the next candidate.