feat!: reduce devframe + @devframes/hub public API surface for 0.9 (#190)

Author: antfubot

alias.ts

@@ -18,6 +18,7 @@ export const alias = {
   'devframe/node/auth': r('devframe/src/node/auth/index.ts'),
   'devframe/node/hub-internals': r('devframe/src/node/hub-internals/index.ts'),
   'devframe/node': r('devframe/src/node/index.ts'),
+  'devframe/internal': r('devframe/src/internal/index.ts'),
   'devframe/constants': r('devframe/src/constants.ts'),
   'devframe/utils/agent-tool-name': r('devframe/src/utils/agent-tool-name.ts'),
   'devframe/utils/colors': r('devframe/src/utils/colors.ts'),
@@ -27,9 +28,7 @@ export const alias = {
   'devframe/utils/launch-editor': r('devframe/src/utils/launch-editor.ts'),
   'devframe/utils/nanoid': r('devframe/src/utils/nanoid.ts'),
   'devframe/utils/open': r('devframe/src/utils/open.ts'),
-  'devframe/utils/promise': r('devframe/src/utils/promise.ts'),
   'devframe/utils/simple-schema': r('devframe/src/utils/simple-schema.ts'),
-  'devframe/utils/scope': r('devframe/src/utils/scope.ts'),
   'devframe/utils/serve-static': r('devframe/src/utils/serve-static.ts'),
   'devframe/utils/shared-state': r('devframe/src/utils/shared-state.ts'),
   'devframe/utils/streaming-channel': r('devframe/src/utils/streaming-channel.ts'),

docs/guide/migration-0.9.md

@@ -4,7 +4,7 @@ outline: deep
 
 # Migrating to 0.9
 
-0.9 removes the compatibility shims that were deprecated across the 0.7 series. Each removed export has a drop-in replacement that has shipped alongside it since 0.7, so migrating is a matter of updating import paths and a handful of call sites. This page covers the changes between 0.8.x and 0.9.
+0.9 removes the compatibility shims that were deprecated across the 0.7 series and trims the public API surface of `devframe` and `@devframes/hub` down to what integrations actually consume. Each change has a drop-in replacement, so migrating is a matter of updating import paths and a handful of call sites. This page covers the changes between 0.8.x and 0.9.
 
 ## `devframe/adapters/cli` is removed
 
@@ -96,3 +96,69 @@ const view = createJsonRenderView(ctx, {
 `createJsonRenderView` returns a view carrying a serializable `ref` (a shared-state key or an inline spec). Project it onto a hub dock with `toJsonRenderDockEntry` from `@devframes/json-render/hub`, which contributes the `'json-render'` dock type to the hub's open dock union. A dock entry now carries that serializable `view` ref rather than a live renderer handle — a client reads `entry.view.stateKey` (or `entry.view.spec`) to render it.
 
 See [JSON-Render](./json-render) for the full integration reference.
+
+## `defineDevframe` moves to the package root
+
+`defineDevframe` — the primary authoring helper — now lives on the `devframe` entry point alongside `defineRpcFunction`. `devframe/types` is now strictly type-only. Import both values and types from `devframe`:
+
+| 0.8.x | 0.9 |
+|-------|-----|
+| `import { defineDevframe } from 'devframe/types'` | `import { defineDevframe } from 'devframe'` |
+| `import type { DevframeNodeContext } from 'devframe/types'` | `import type { DevframeNodeContext } from 'devframe'` |
+
+```ts
+import type { DevframeNodeContext } from 'devframe'
+// 0.9
+import { defineDevframe, defineRpcFunction } from 'devframe'
+```
+
+`devframe/types` still resolves as the type-only subpath — useful for `declare module 'devframe/types'` augmentations — but `devframe` is the canonical import for both values and types.
+
+## `devframe/utils/{promise,scope}` are removed
+
+Two utility subpaths with no integration consumers are removed:
+
+| Removed | Replacement |
+|---------|-------------|
+| `import { promiseWithResolver } from 'devframe/utils/promise'` | `Promise.withResolvers()` (native) |
+| `import { isQualifiedName, qualifyName } from 'devframe/utils/scope'` | Inline the check (`name.includes(':')`) |
+
+The other `devframe/utils/*` helpers — `colors`, `open`, `launch-editor`, `hash`, `nanoid`, `crypto-token`, `structured-clone`, `events`, `shared-state`, `streaming-channel`, `when`, `simple-schema`, `serve-static`, `agent-tool-name` — are unchanged.
+
+## `devframe/node` is slimmed to the context surface
+
+`devframe/node` keeps just the context-building API — `createHostContext` (+ `CreateHostContextOptions`), `createStorage` (+ `CreateStorageOptions`), and the `RpcFunctionsHost` type. Serve a devframe through the adapters (`createDevServer`, `createBuild`, `createCac`) or [`devframe/initiate`](../adapters/initiate); build a context to embed one with `createHostContext`.
+
+The internal host implementations and low-level factories are no longer exported at all:
+
+| Removed from `devframe/node` | Notes |
+|---|---|
+| `DevframeDiagnosticsHost`, `DevframeServicesHostImpl`, `DevframeViewHost` (classes) | Internal host implementations. The same-named **types** remain on `devframe/types`. |
+| `createRpcSharedStateServerHost`, `createRpcStreamingServerHost` | Wired internally by `createContextRpcServer`. |
+| `createScopedNodeContext`, `createNodeSettings` | Internal to context assembly. |
+| `toDialableHost`, `formatHostForUrl`, `isObject` | Internal helpers (`isObject` is removed entirely — inline `typeof x === 'object' && x !== null`). |
+
+## Cross-package internals move to `devframe/internal`
+
+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 |
+|---|---|---|
+| `createH3DevframeHost` (+ `CreateH3DevframeHostOptions`) | `devframe/node` | `devframe/internal` |
+| `startHttpAndWs` (+ `StartedServer`, `StartHttpAndWsOptions`) | `devframe/node` | `devframe/internal` |
+| `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` |
+| `normalizeHttpServerUrl` | `devframe/node` | `devframe/internal` |
+
+A host that stands up its own server composes from `devframe/internal` — `createH3DevframeHost` for the node `DevframeHost`, `startHttpAndWs` (or `createContextRpcServer` + `devframe/rpc/server` + `devframe/rpc/transports/*`) to bind a transport — plus `devframe/node`'s `createHostContext` and `devframe/node/hub-internals`. This is 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/initiate`.
+
+## `@devframes/hub` category order lives only on `/constants`
+
+`DEFAULT_CATEGORIES_ORDER` is now exported only from `@devframes/hub/constants` (its documented single source of truth). The redundant re-exports from `@devframes/hub`, `@devframes/hub/node`, and `@devframes/hub/client` are removed:
+
+```ts
+// 0.9
+import { DEFAULT_CATEGORIES_ORDER } from '@devframes/hub/constants'
+```

docs/helpers/utilities.md

@@ -97,16 +97,6 @@ randomDigits(6) // '047204' — uniform, leading zeros preserved
 timingSafeEqual(input, secret) // constant-time string comparison
 ```
 
-### `devframe/utils/promise`
-
-Promise constructor with externally-controlled resolution.
-
-```ts
-import { promiseWithResolver } from 'devframe/utils/promise'
-
-const { promise, resolve, reject } = promiseWithResolver<number>()
-```
-
 ### `devframe/utils/events`
 
 Generic typed event emitter — `on(event, cb)` returns an unsubscribe function. Used as the eventing primitive across devframe's hosts.

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

@@ -1,13 +1,13 @@
 import type { DevframeHubContext } from '@devframes/hub/node'
 import type { ClientScriptEntry } from '@devframes/hub/types'
-import type { DevframeInstanceRegistration } from 'devframe/node'
-import type { DevframeDefinition, DevframeHost } from 'devframe/types'
+import type { DevframeDefinition, DevframeHost } from 'devframe'
+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, startHttpAndWs } from 'devframe/internal'
 import { serveStaticNodeMiddleware } from 'devframe/utils/serve-static'
 import { getPort } from 'get-port-please'
 import { join } from 'pathe'

examples/files-inspector/src/devframe.ts

@@ -1,5 +1,5 @@
 import { fileURLToPath } from 'node:url'
-import { defineDevframe } from 'devframe/types'
+import { defineDevframe } from 'devframe'
 import pkg from '../package.json' with { type: 'json' }
 import { NAMESPACE, serverFunctions } from './rpc/index.ts'
 

examples/files-inspector/tests/_utils.ts

@@ -1,4 +1,4 @@
-import type { StartedServer } from 'devframe/node'
+import type { StartedServer } from 'devframe/internal'
 import { existsSync } from 'node:fs'
 import { mkdtemp, writeFile } from 'node:fs/promises'
 import os from 'node:os'
@@ -7,11 +7,8 @@ import { fileURLToPath } from 'node:url'
 import {
   DEVFRAME_CONNECTION_META_FILENAME,
 } from 'devframe/constants'
-import {
-  createH3DevframeHost,
-  createHostContext,
-  startHttpAndWs,
-} from 'devframe/node'
+import { createH3DevframeHost, startHttpAndWs } from 'devframe/internal'
+import { createHostContext } from 'devframe/node'
 import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { getPort } from 'get-port-please'
 import { H3 } from 'h3'

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

@@ -1,6 +1,6 @@
 import type { createUi as CreateUi } from '@devframes/hub-ui'
 import type { HubInstance } from '@devframes/hub/initiate'
-import type { DevframeDefinition } from 'devframe/types'
+import type { DevframeDefinition } from 'devframe'
 import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
 
 // The plugin packages and `@devframes/hub-ui` resolve their prebuilt `dist`

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

@@ -1,6 +1,6 @@
 import type { DevframeHubContext } from '@devframes/hub/node'
 import { fileURLToPath } from 'node:url'
-import { defineDevframe } from 'devframe/types'
+import { defineDevframe } from 'devframe'
 import { dirname, resolve } from 'pathe'
 import pkg from '../../../package.json' with { type: 'json' }
 

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

@@ -1,6 +1,6 @@
 import type { DevframeHubContext } from '@devframes/hub/node'
 import { fileURLToPath } from 'node:url'
-import { defineDevframe } from 'devframe/types'
+import { defineDevframe } from 'devframe'
 import { dirname, resolve } from 'pathe'
 import pkg from '../../../package.json' with { type: 'json' }
 

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 { DevframeInstanceRegistration } from 'devframe/node'
-import type { DevframeDefinition } from 'devframe/types'
+import type { DevframeDefinition } from 'devframe'
+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'