refactor(adapters)!: rebuild createDevServer, viteDevBridge, and @devframes/next on initDevframe

One wiring underneath every serving path: the adapters become thin
assemblies over the devframe/initiate instance.

- createDevServer = initDevframe + a node listener (listen-first so the
  shared WS tier reports the real port; DF0052 rejection preserved;
  registry/openBrowser/onReady unchanged; ws/rpcGroup/connectionMeta
  surfaced from the instance transport)
- viteDevBridge bridge mode = instance.nodeMiddleware on Vite's stack;
  the WS upgrade now shares Vite's own http server at <base>__ws (zero
  extra ports; pinned devMiddleware.port keeps the explicit side-car)
  and MCP moves onto the Vite origin at <base>__mcp
- @devframes/next reduces to memoization + defaults sugar (key-memoized
  instance; MCP same-origin through the catch-all route)
- initDevframe grows the host-integration options the adapters need:
  app, distDir: false, origin getter, getStorageDir,
  destroyUnmatchedUpgrades, onPeerConnect/onPeerDisconnect passthrough
- resolveDevServerPort / resolveMcpConnectionMeta move to adapters/_shared
  (re-exported from adapters/dev unchanged)

BREAKING CHANGE: viteDevBridge and @devframes/next advertise same-origin
relative endpoints now — websocket { path: '__ws' } on the host origin
(or { port, path: '__ws' } for a pinned side-car) and mcp
{ path: '__mcp' } — instead of side-car-port absolute paths.

Author: antfubot

packages/devframe/src/adapters/_shared.ts

@@ -1,5 +1,10 @@
-import type { DevframeDefinition, DevframeDeploymentKind } from '../types/devframe'
-import { cleanDoubleSlashes, withLeadingSlash, withTrailingSlash } from 'ufo'
+import type { ConnectionMeta } from '../types/context'
+import type { DevframeDefinition, DevframeDeploymentKind, McpRouteOptions } from '../types/devframe'
+import { getPort } from 'get-port-please'
+import { cleanDoubleSlashes, withLeadingSlash, withoutLeadingSlash, withTrailingSlash } from 'ufo'
+import { DEVFRAME_MCP_ROUTE } from '../constants'
+
+const DEFAULT_PORT = 9999
 
 /**
  * Resolve the mount base path for a devframe's SPA. Hosted adapters
@@ -18,3 +23,72 @@ export function resolveBasePath(def: DevframeDefinition, kind: DevframeDeploymen
 export function normalizeBasePath(base: string): string {
   return cleanDoubleSlashes(withTrailingSlash(withLeadingSlash(base)))
 }
+
+export interface ResolveDevServerPortOptions {
+  /** Bind host (passed to `get-port-please` for in-use detection). */
+  host?: string
+  /** Override the preferred port. Default: `def.cli?.port ?? 9999`. */
+  defaultPort?: number
+}
+
+/**
+ * Resolve the listening port for `createDevServer` (and `createHandler`'s
+ * side-car tiers), honoring the definition's `cli.port` / `cli.portRange` /
+ * `cli.random` settings. Exposed separately so authors who run their own
+ * argv parsing can resolve a port up-front (to print it, log it, etc.)
+ * before starting the server.
+ */
+export async function resolveDevServerPort(
+  def: DevframeDefinition,
+  options: ResolveDevServerPortOptions = {},
+): Promise<number> {
+  const host = options.host ?? def.cli?.host ?? 'localhost'
+  const port = options.defaultPort ?? def.cli?.port ?? DEFAULT_PORT
+  // Only include optional fields when set — `get-port-please` spreads
+  // user options over its defaults, so `portRange: undefined` would
+  // wipe out the internal `[]` and crash on iteration.
+  const portOptions: Parameters<typeof getPort>[0] = { port, host }
+  if (def.cli?.portRange)
+    portOptions.portRange = def.cli.portRange
+  if (def.cli?.random)
+    portOptions.random = def.cli.random
+  return getPort(portOptions)
+}
+
+/**
+ * Normalize the `cli.mcp` / `mcp` option (`boolean | McpRouteOptions`) into
+ * concrete options, or `undefined` when the MCP route is disabled.
+ */
+export function resolveMcpConfig(mcp: boolean | McpRouteOptions | undefined): McpRouteOptions | undefined {
+  if (!mcp)
+    return undefined
+  return mcp === true ? {} : mcp
+}
+
+/**
+ * Resolve the `mcp` entry a `__connection.json` should advertise for a dev
+ * server started with the given `mcp` option (falling back to `def.cli?.mcp`,
+ * exactly like `createDevServer`), or `undefined` when the route is
+ * disabled.
+ *
+ * Hosted bridges that hand-roll their connection meta pass the side-car
+ * `port`: the advertised path becomes absolute (the side-car mounts at `/`)
+ * and the client dials `<page-host>:<port><path>`. Without `port` the path
+ * stays relative, resolved against `__connection.json`'s own location (the
+ * same-server default).
+ *
+ * @experimental
+ */
+export function resolveMcpConnectionMeta(
+  def: DevframeDefinition,
+  mcp: boolean | McpRouteOptions | undefined,
+  port?: number,
+): ConnectionMeta['mcp'] {
+  const config = resolveMcpConfig(mcp ?? def.cli?.mcp)
+  if (!config)
+    return undefined
+  const route = withoutLeadingSlash(config.path ?? DEVFRAME_MCP_ROUTE)
+  return port != null
+    ? { path: withLeadingSlash(route), port }
+    : { path: route }
+}