refactor(devframe)!: move remaining low-level node exports to devframe/internal

Reduce the public `devframe/node` barrel to the server-assembly surface only
(`createHostContext`, `createH3DevframeHost`, `startHttpAndWs`, `createStorage`,
`RpcFunctionsHost`). Relocate the low-level primitives that only first-party
integrations use to the unstable `devframe/internal` surface:

- the instance registry (`registerDevframeInstance` / `listLiveDevframeInstances`
  + `DevframeInstanceRecord` / `DevframeInstanceRegistration`)
- `isObject`, `normalizeHttpServerUrl`

`startHttpAndWs` stays on `devframe/node` — it's the primary programmatic
server entry (used as real code by several plugins, examples, and the hub), not
a low-level util. The inspect plugin and the hub host examples now import the
instance registry from `devframe/internal`; `@vitejs/devtools` picks up
`isObject`/`normalizeHttpServerUrl` from there too.

Co-authored-by: opencode <noreply@opencode.ai>

Author: antfubot

docs/guide/migration-0.9.md

@@ -127,7 +127,7 @@ The other `devframe/utils/*` helpers — `colors`, `open`, `launch-editor`, `has
 
 ## `devframe/node` is slimmed to the server-assembly surface
 
-`devframe/node` keeps the API that hosts wiring up their own runtime actually use — `createHostContext`, `createH3DevframeHost`, `startHttpAndWs`, `createStorage`, `registerDevframeInstance` / `listLiveDevframeInstances`, `isObject`, `normalizeHttpServerUrl`, and the `RpcFunctionsHost` / instance-record types.
+`devframe/node` keeps the server-assembly API hosts actually use — `createHostContext`, `createH3DevframeHost`, `startHttpAndWs` (+ `StartedServer`), `createStorage`, and the `RpcFunctionsHost` type.
 
 The internal host implementations and low-level factories are no longer exported:
 
@@ -140,15 +140,17 @@ The internal host implementations and low-level factories are no longer exported
 
 ## Cross-package internals move to `devframe/internal`
 
-The low-level primitives that only exist for the `devframe` ↔ `@devframes/hub` boundary now live at the new `devframe/internal` entry point, which is explicitly **unstable** (it can change in any minor release). They were previously on `devframe/node`:
+The low-level primitives shared between `devframe` and its first-party integrations (`@devframes/hub`, the inspect plugin, `@vitejs/devtools`, custom hosts) now live at the new `devframe/internal` entry point, which is explicitly **unstable** (it can change in any minor release). They were previously on `devframe/node`:
 
 | Moved | From | To |
 |---|---|---|
 | `createContextRpcServer` (+ `ContextRpcServer`, `CreateContextRpcServerOptions`) | `devframe/node` | `devframe/internal` |
 | `DevframeAgentHost` (class) | `devframe/node` | `devframe/internal` |
 | `coerceAgentPositionalArgs` (+ `AgentArgsFallback`) | `devframe/node` | `devframe/internal` |
+| `registerDevframeInstance` / `listLiveDevframeInstances` (+ `DevframeInstanceRecord`, `DevframeInstanceRegistration`) | `devframe/node` | `devframe/internal` |
+| `isObject`, `normalizeHttpServerUrl` | `devframe/node` | `devframe/internal` |
 
-A host that binds its own transport composes from `createContextRpcServer` (`devframe/internal`) plus `devframe/rpc/server`, `devframe/rpc/transports/*`, and `devframe/node/hub-internals` — the path `@devframes/hub`'s `initHub` takes. Application code should prefer the adapters and `devframe/node`.
+A host that binds its own transport composes from `createContextRpcServer` (`devframe/internal`) plus `devframe/rpc/server`, `devframe/rpc/transports/*`, and `devframe/node/hub-internals` — the path `@devframes/hub`'s `initHub` takes. A custom host advertises itself with `registerDevframeInstance`, and a devtool enumerates running instances with `listLiveDevframeInstances`. Application code should prefer the adapters and `devframe/node`.
 
 ## `@devframes/hub` category order lives only on `/constants`
 

examples/a11y-messages-playground/src/a11y-messages-playground.ts

@@ -1,13 +1,14 @@
 import type { DevframeHubContext } from '@devframes/hub/node'
 import type { ClientScriptEntry } from '@devframes/hub/types'
 import type { DevframeDefinition, DevframeHost } from 'devframe'
-import type { DevframeInstanceRegistration } from 'devframe/node'
+import type { DevframeInstanceRegistration } from 'devframe/internal'
 import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite'
 import { homedir } from 'node:os'
 import process from 'node:process'
 import { createHubContext, mountDevframe } from '@devframes/hub/node'
 import { DEVFRAME_CONNECTION_META_FILENAME } from 'devframe/constants'
-import { registerDevframeInstance, startHttpAndWs } from 'devframe/node'
+import { registerDevframeInstance } from 'devframe/internal'
+import { startHttpAndWs } from 'devframe/node'
 import { serveStaticNodeMiddleware } from 'devframe/utils/serve-static'
 import { getPort } from 'get-port-please'
 import { join } from 'pathe'

examples/hub-next/src/client/devframe/next-devframe-hub.ts

@@ -1,14 +1,14 @@
 import type { HubDevframeEntry, HubInstance } from '@devframes/hub/initiate'
 import type { DevframeHubContext } from '@devframes/hub/node'
 import type { DevframeDefinition } from 'devframe'
-import type { DevframeInstanceRegistration } from 'devframe/node'
+import type { DevframeInstanceRegistration } from 'devframe/internal'
 import { homedir } from 'node:os'
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { defineHubRpcFunction } from '@devframes/hub'
 import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
 import { toJsonRenderDockEntry } from '@devframes/json-render/hub'
-import { registerDevframeInstance } from 'devframe/node'
+import { registerDevframeInstance } from 'devframe/internal'
 import { createDashboardView } from 'json-render/dashboard'
 import { dirname, join } from 'pathe'
 import demoDevframe from './demo-devframe'

examples/hub-vite/src/vite-devframe-hub.ts

@@ -2,14 +2,14 @@ import type { HubDevframeEntry, HubInstance } from '@devframes/hub/initiate'
 import type { DevframeHubContext } from '@devframes/hub/node'
 import type { ClientScriptEntry } from '@devframes/hub/types'
 import type { DevframeDefinition } from 'devframe'
-import type { DevframeInstanceRegistration } from 'devframe/node'
+import type { DevframeInstanceRegistration } from 'devframe/internal'
 import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite'
 import { Server as NodeHttpServer } from 'node:http'
 import { homedir } from 'node:os'
 import process from 'node:process'
 import { defineHubRpcFunction } from '@devframes/hub'
 import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
-import { registerDevframeInstance } from 'devframe/node'
+import { registerDevframeInstance } from 'devframe/internal'
 import { join } from 'pathe'
 
 export interface ViteDevframeHubOptions {

packages/devframe/src/internal/index.ts

@@ -1,8 +1,8 @@
-// Internal cross-package surface: low-level host primitives shared between
-// `devframe` and `@devframes/hub` (and any first-party host built on the same
-// wiring). These are NOT part of the stable public API — they can change in any
-// minor release. Application code should use `devframe/node` and the adapters
-// instead.
+// Internal cross-package surface: low-level primitives shared between
+// `devframe` and its first-party integrations (`@devframes/hub`, the inspect
+// plugin, `@vitejs/devtools`, custom hosts). These are NOT part of the stable
+// public API — they can change in any minor release. Application code should
+// use `devframe/node` and the adapters instead.
 //
 // - `createContextRpcServer` — the transport-agnostic RPC core; a host that
 //   binds its own transport (e.g. the hub's `initHub`) reuses the exact
@@ -11,8 +11,16 @@
 //   its own commands host.
 // - `coerceAgentPositionalArgs` — positional-arg coercion the hub applies when
 //   invoking agent tools as commands.
+// - `registerDevframeInstance` / `listLiveDevframeInstances` — the instance
+//   registry: a custom host advertises itself; a devtool (the inspect plugin's
+//   Instances tab, the connector) enumerates what's running.
+// - `isObject` / `normalizeHttpServerUrl` — small host-side helpers a
+//   hand-rolled host reuses to match devframe's own config/URL handling.
 export { coerceAgentPositionalArgs } from '../node/agent-args'
 export type { AgentArgsFallback } from '../node/agent-args'
 export { DevframeAgentHost } from '../node/host-agent'
+export { listLiveDevframeInstances, registerDevframeInstance } from '../node/instance-registry'
+export type { DevframeInstanceRecord, DevframeInstanceRegistration } from '../node/instance-registry'
 export { createContextRpcServer } from '../node/rpc-core'
 export type { ContextRpcServer, CreateContextRpcServerOptions } from '../node/rpc-core'
+export { isObject, normalizeHttpServerUrl } from '../node/utils'

packages/devframe/src/node/index.ts

@@ -1,28 +1,19 @@
 // Node-side public API for hosts that wire up their own runtime — the
-// server-assembly surface (`createHostContext` → `startHttpAndWs`), the
-// instance registry, storage, and the two URL/host helpers consumers use.
+// server-assembly surface (`createHostContext` → `createH3DevframeHost` →
+// `startHttpAndWs`) and storage.
 //
-// The diagnostics/services/views hosts, the streaming/shared-state/scope/
-// settings factories, and the internal host helpers (`toDialableHost`,
-// `formatHostForUrl`) stay internal. `toAgentToolName` lives at
-// `devframe/utils/agent-tool-name` (a client-safe string transform).
-//
-// The low-level primitives shared only between `devframe` and `@devframes/hub`
-// — `createContextRpcServer`, `DevframeAgentHost`, `coerceAgentPositionalArgs`
-// — live at `devframe/internal` (an explicitly-unstable cross-package surface),
-// not here.
+// Everything lower-level lives at `devframe/internal` (an explicitly-unstable
+// cross-package surface): the transport-agnostic RPC core, the agent host, the
+// instance registry (host self-registration + live discovery), and the
+// `isObject` / `normalizeHttpServerUrl` helpers. The diagnostics/services/views
+// hosts, the streaming/shared-state/scope/settings factories, and the internal
+// host-URL helpers stay fully internal (relative imports only).
+// `toAgentToolName` lives at `devframe/utils/agent-tool-name`.
 export * from './context'
 // `RpcFunctionsHostImpl` stays internal; expose only the structural
 // `RpcFunctionsHost` type so consumers can type/cast `ctx.rpc` without
 // pulling in the implementation's `@internal` members.
 export type { RpcFunctionsHost } from './host-functions'
 export * from './host-h3'
-// Registration is public — custom hosts (e.g. @devframes/next) record
-// themselves — and live discovery is public too, so surfaces like the
-// inspect plugin's Instances tab can enumerate running instances. The
-// lower-level read/probe/prune helpers stay internal to the connector.
-export { listLiveDevframeInstances, registerDevframeInstance } from './instance-registry'
-export type { DevframeInstanceRecord, DevframeInstanceRegistration } from './instance-registry'
 export * from './server'
 export * from './storage'
-export { isObject, normalizeHttpServerUrl } from './utils'

plans/032-0.9-public-api-surface-reduction.md

@@ -95,12 +95,18 @@ Net effect (after maintainer follow-ups):
 - Dead-subpath removals are `utils/promise` and `utils/scope` only. `ws-bun` is
   kept (hub uses it); `utils/hash` is kept (maintainer request); `embedded` is
   kept (maintainer request — a named, discoverable adapter).
-- The `devframe/node` trim drops **12** exports again — but the three
-  hub-only low-level APIs (`createContextRpcServer`, `DevframeAgentHost`,
-  `coerceAgentPositionalArgs`) are **relocated** to a new **`devframe/internal`**
-  entry (an explicitly-unstable cross-package surface) rather than kept on the
-  public `devframe/node`, and the hub imports them from there. The other 9 stay
-  fully internal (relative imports only).
+- The public `devframe/node` barrel is reduced to the server-assembly surface
+  only: `createHostContext`, `createH3DevframeHost`, `startHttpAndWs`
+  (+ `StartedServer`), `createStorage`, and the `RpcFunctionsHost` type.
+- A new **`devframe/internal`** entry (an explicitly-unstable cross-package
+  surface) holds the low-level primitives first-party integrations need:
+  `createContextRpcServer`, `DevframeAgentHost`, `coerceAgentPositionalArgs`,
+  the instance registry (`registerDevframeInstance` / `listLiveDevframeInstances`
+  + types), and `isObject` / `normalizeHttpServerUrl`. The hub, the inspect
+  plugin, and the host examples import from there. The remaining node internals
+  (diagnostics/services/views hosts, the streaming/shared-state/scope/settings
+  factories, `toDialableHost`/`formatHostForUrl`) stay fully internal (relative
+  imports only).
 
 ### ⚠️ One item to confirm during review
 

plugins/inspect/src/rpc/functions/list-instances.ts

@@ -1,6 +1,6 @@
 import type { DevframeInspectInstanceInfo } from '../../types'
 import process from 'node:process'
-import { listLiveDevframeInstances } from 'devframe/node'
+import { listLiveDevframeInstances } from 'devframe/internal'
 import { defineInspectRpc } from './_define'
 
 /**

tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts

@@ -1,6 +1,26 @@
 /**
  * Generated by tsnapi — public API snapshot of `devframe/internal`
  */
+// #region Interfaces
+export interface DevframeInstanceRecord {
+  pid: number;
+  port: number;
+  origin: string;
+  basePath: string;
+  id: string;
+  name?: string;
+  rootDir: string;
+  mcp: {
+    path: string;
+  } | null;
+  startedAt: number;
+}
+export interface DevframeInstanceRegistration {
+  readonly file: string;
+  unregister: () => void;
+}
+// #endregion
+
 // #region Types
 export type AgentArgsFallback = 'wrap' | 'drop';
 // #endregion
@@ -35,6 +55,18 @@ export declare class DevframeAgentHost implements DevframeAgentHost$1 {
 
 // #region Functions
 export declare function coerceAgentPositionalArgs(_: unknown, _: readonly unknown[] | undefined, _?: AgentArgsFallback): unknown[];
+export declare function isObject(_: unknown): value is Record<string, any>;
+export declare function listLiveDevframeInstances(_?: {
+  instancesDir?: string;
+  timeoutMs?: number;
+}): Promise<{
+  live: DevframeInstanceRecord[];
+  pruned: DevframeInstanceRecord[];
+}>;
+export declare function normalizeHttpServerUrl(_: string, _: number | string): string;
+export declare function registerDevframeInstance(_: DevframeInstanceRecord, _?: {
+  instancesDir?: string;
+}): DevframeInstanceRegistration;
 // #endregion
 
 // #region Other

tests/__snapshots__/tsnapi/devframe/internal.snapshot.js

@@ -5,4 +5,8 @@
 export { coerceAgentPositionalArgs }
 export { createContextRpcServer }
 export { DevframeAgentHost }
+export { isObject }
+export { listLiveDevframeInstances }
+export { normalizeHttpServerUrl }
+export { registerDevframeInstance }
 // #endregion