docs(plans): add 032 \u2014 0.9 public API surface reduction spec

Author: antfubot

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

@@ -0,0 +1,371 @@
+# Plan 032: Reduce the `devframe` + `@devframes/hub` public API surface for 0.9 ⚠️
+
+> **Executor instructions**: Follow this plan step by step. Run every
+> verification command and confirm the expected result before moving on. If a
+> STOP condition occurs, stop and report. When done, update this plan's row in
+> `plans/README.md`.
+>
+> **Drift check (run first)**: `git diff --stat ffdb690..HEAD -- packages/devframe/package.json packages/devframe/tsdown.config.ts packages/devframe/src/index.ts packages/devframe/src/node/index.ts packages/hub/src/index.ts`
+> On any change since this plan was written, compare against the "Current state"
+> excerpts below before proceeding; on a mismatch, STOP.
+
+## Status
+
+- **Priority**: P2
+- **Effort**: L (touches both packages' export maps + ~80 consumer import sites + docs)
+- **Risk**: MEDIUM (breaking, but 0.9 is already the breaking-cleanup release; every removed export is either unused or has a documented replacement)
+- **Depends on**: none (extends the 0.9 cleanup already started in #180 / `migration-0.9.md`)
+- **Category**: direction / tech-debt
+- **Planned at**: commit `ffdb690`, 2026-08-10
+
+## Why this matters
+
+`devframe` publishes **39** entry points and `@devframes/hub` **6**. An audit of
+every consumer — the in-repo `plugins/*`, `examples/*`,
+`packages/next|nuxt|hub-ui|json-render*`, and the canonical external consumer
+`vitejs/devtools` (`packages/core` = node/server host, `packages/kit` =
+re-exports the whole hub surface under `DevTools*` aliases) — found:
+
+- Entry points **nobody imports anywhere** (code, docs, skills, templates).
+- The **primary authoring function `defineDevframe` is missing from the main
+  barrel** and only reachable via `devframe/types`, making `devframe/types` the
+  single most-imported entry point (78 files) for the wrong reason.
+- `devframe/node` exports **16 values, 12 of them internal impl with zero
+  consumer usage** (host classes, rpc/scope/settings factories, host helpers).
+- `@devframes/hub` exports `DEFAULT_CATEGORIES_ORDER` from **four** entry points
+  when consumers only ever import it from one.
+
+0.9 is already the breaking-cleanup release. This plan shrinks the surface to
+what consumers actually use, moves the primary author API to the front door, and
+records every change in `docs/guide/migration-0.9.md`.
+
+Consumer usage was measured across in-repo `plugins/*`, `examples/*`,
+`packages/*` and the external `vitejs/devtools` source; "unused" below means no
+consumer in any of those imports it.
+
+## Scope
+
+**In scope**: `packages/devframe` and `packages/hub` `exports` maps + `tsdown`
+entries + barrel source; the `defineDevframe` relocation; the `devframe/node`
+trim; the hub `DEFAULT_CATEGORIES_ORDER` de-dup; rewriting in-repo consumer
+imports; updating `docs/**`, `skills/devframe/**`, and templates; extending
+`docs/guide/migration-0.9.md`.
+
+**Out of scope**: any rename of a widely-used, well-placed export
+(`defineRpcFunction`, `createHostContext`, `startHttpAndWs`, the hub
+client/type surface); version bumps / releasing (needs separate human
+approval); changing `vitejs/devtools` (external — it follows the migration
+guide).
+
+## Decisions locked in (from the design consult)
+
+| Area | Decision |
+|------|----------|
+| Ambition | Remove dead subpaths **and** redesign the core shape. |
+| `defineDevframe` | Move onto the main `devframe` barrel; make `devframe/types` strictly type-only; steer all consumers to `devframe`. |
+| `devframe/node` | Drop all 12 internal exports; keep only the used server-assembly API. |
+| `devframe/node/auth` | **Keep public** (low-level auth layer). |
+| `devframe/rpc/client` + `rpc/transports/ws-client` | **Keep both**, document as the low-level / test client. |
+| `devframe/rpc/server` + `rpc/transports/ws-server` | **Keep** (hand-rolled-server hosts use them). |
+| `devframe/adapters/embedded` | **Remove** (one-liner `d.setup(ctx)`). |
+| `devframe/rpc/transports/ws-bun` | **Remove** (zero refs). |
+| `devframe/utils/hash`, `utils/promise`, `utils/scope` | **Remove** (zero refs). |
+| `devframe/utils/structured-clone` | **Keep**. |
+| `devframe/utils/agent-tool-name`, `utils/crypto-token`, `utils/streaming-channel` | **Keep all three** (internal primitives w/ occasional external use). |
+| `@devframes/hub` `DEFAULT_CATEGORIES_ORDER` | Keep only on `/constants`; drop from `.`, `/node`, `/client`. |
+| `@devframes/hub/initiate` (`initHub`) | **Keep as-is** (deliberate parallel to `devframe/initiate`). |
+
+### ⚠️ One item to confirm during review
+
+`packages/devframe/src/node/index.ts` documents `createContextRpcServer`
+(`./rpc-core`) as intentionally public "so hosts that bind their own transports
+reuse the exact session/auth wiring." No consumer uses it — `vitejs/devtools`
+rebuilds that wiring itself from the lower `devframe/rpc/server` +
+`devframe/rpc/transports/ws-server` primitives (`packages/core/src/node/ws.ts`),
+which this plan **keeps public**. The locked decision ("drop all 12") therefore
+removes `rpc-core` too. If the reviewer wants to preserve the documented
+custom-transport contract, split it out: keep `createContextRpcServer` and drop
+only the other 11. **Default: drop it with the rest.**
+
+---
+
+## Current state
+
+### `packages/devframe/src/index.ts`
+```ts
+// Public API. The full defineDevframe + adapter surface lands in later commits.
+export * from './define'
+export type * from './types'
+```
+`./define` exports only `defineRpcFunction`. `export type *` strips the
+`defineDevframe` **value** that lives in `./types/devframe.ts`, so it never
+reaches the main barrel.
+
+### `packages/devframe/src/define.ts`
+```ts
+import type { DevframeNodeContext } from 'devframe/types'
+import { createDefineWrapperWithContext } from 'devframe/rpc'
+
+export const defineRpcFunction = createDefineWrapperWithContext<DevframeNodeContext>()
+```
+
+### `packages/devframe/src/types/devframe.ts` (tail)
+```ts
+export function defineDevframe(d: DevframeDefinition): DevframeDefinition {
+  return d
+}
+```
+`src/types/index.ts` does `export * from './devframe'`, so this function is the
+**only value** on the `devframe/types` entry.
+
+### `packages/devframe/src/node/index.ts`
+Barrels `./context`, `./host-agent`, `./host-diagnostics`, `./host-services`,
+`./host-views`, `./host-h3`, `./rpc-core`, `./rpc-shared-state`,
+`./rpc-streaming`, `./scope`, `./server`, `./settings`, `./storage`, `./utils`,
+`./agent-args`, a selective `RpcFunctionsHost` type, and the instance-registry
+pair. See the file for the exact lines.
+
+### `packages/hub/src/index.ts`
+```ts
+export { DEFAULT_CATEGORIES_ORDER } from './constants'
+export * from './define'
+export type * from './types'
+```
+`DEFAULT_CATEGORIES_ORDER` is **also** re-exported by `src/node/index.ts:3` and
+`src/client/index.ts:3`; its canonical home is `src/constants.ts`.
+
+---
+
+## Changes
+
+### A. Remove dead `devframe` subpaths
+
+Delete these keys from `packages/devframe/package.json` `exports` **and** their
+entries from `packages/devframe/tsdown.config.ts` (`serverEntries` /
+`clientEntries` / the client-dist check list, as applicable):
+
+| Entry | package.json key | tsdown entry key |
+|-------|------------------|------------------|
+| embedded adapter | `./adapters/embedded` | `adapters/embedded` (serverEntries) |
+| Bun WS transport | `./rpc/transports/ws-bun` | `rpc/transports/ws-bun` (serverEntries) |
+| hash util | `./utils/hash` | `utils/hash` (clientEntries **and** the `check-client-dist` list) |
+| promise util | `./utils/promise` | `utils/promise` (clientEntries **and** the `check-client-dist` list) |
+| scope util | `./utils/scope` | `utils/scope` (clientEntries **and** the `check-client-dist` list) |
+
+Then handle the now-orphaned source:
+- `src/adapters/embedded.ts` — delete (and its `__tests__` if any).
+- `src/rpc/transports/ws-bun.ts` — delete (and `ws-bun*.test.ts` if any).
+- `src/utils/hash.ts`, `src/utils/promise.ts`, `src/utils/scope.ts` — if
+  nothing imports them internally (verify with the STOP check below), delete;
+  otherwise switch the internal importer(s) to a relative import and leave the
+  file un-exported. Verify:
+  ```sh
+  rg -n "utils/hash|utils/promise|utils/scope" packages/devframe/src --glob '!**/*.test.ts'
+  ```
+  Expected: no non-test hits outside the files themselves. If a hit exists,
+  STOP and report (a keeper was misclassified).
+
+`DevframeRuntime` in `types/devframe.ts` includes the string literal
+`'embedded'`. Leave the literal (it names a runtime mode, not the adapter). Only
+the `createEmbedded` adapter goes away.
+
+### B. Move `defineDevframe` to the main barrel; make `devframe/types` type-only
+
+1. In `src/types/devframe.ts`, **delete** the `defineDevframe` function (keep the
+   `DevframeDefinition` interface and every option type).
+2. In `src/define.ts`, **add** it next to `defineRpcFunction`:
+   ```ts
+   import type { DevframeDefinition, DevframeNodeContext } from 'devframe/types'
+   import { createDefineWrapperWithContext } from 'devframe/rpc'
+
+   export const defineRpcFunction = createDefineWrapperWithContext<DevframeNodeContext>()
+
+   /** Identity helper that types a devframe definition. */
+   export function defineDevframe(d: DevframeDefinition): DevframeDefinition {
+     return d
+   }
+   ```
+   (`src/index.ts` already does `export * from './define'`, so `defineDevframe`
+   now reaches the main barrel as a value. Drop the stale "lands in later
+   commits" comment.)
+3. `src/types/index.ts` is unchanged; with the function gone it now re-exports
+   **types only** — `devframe/types` becomes strictly type-only, matching its
+   name. Keep the `devframe/types` entry point (kept per decision).
+
+**Consumer migration.** All types already reach the main barrel via
+`export type *`, so the canonical import is now `devframe`. Rewrite in-repo
+consumers:
+- Find value importers:
+  ```sh
+  rg -n "defineDevframe" plugins examples packages --glob '!**/dist/**'
+  ```
+  Change `import { defineDevframe } from 'devframe/types'` →
+  `import { defineDevframe } from 'devframe'`.
+- Steer type importers off `devframe/types` to `devframe`:
+  ```sh
+  rg -n "from 'devframe/types'" plugins examples packages --glob '!**/dist/**'
+  ```
+  Rewrite each to `from 'devframe'` (preserving `import type` / inline `type`).
+  ~78 files reference `devframe/types`; the change is mechanical. Do **not**
+  touch `packages/hub/src/**` re-exports of `devframe/types` — those are the
+  hub's own type barrel and stay.
+
+STOP condition: if any consumer imports a **value** (not a type) from
+`devframe/types` other than `defineDevframe`, STOP — the audit says there is
+none, so a hit means the surface changed.
+
+### C. Trim `devframe/node` to the used server-assembly API
+
+Rewrite `src/node/index.ts` to:
+```ts
+// Node-side public API for hosts that wire up their own runtime.
+export * from './context'                 // createHostContext (+ CreateHostContextOptions)
+export type { RpcFunctionsHost } from './host-functions'
+export * from './host-h3'                 // createH3DevframeHost (+ CreateH3DevframeHostOptions)
+export { listLiveDevframeInstances, registerDevframeInstance } from './instance-registry'
+export type { DevframeInstanceRecord, DevframeInstanceRegistration } from './instance-registry'
+export * from './server'                  // startHttpAndWs (+ StartHttpAndWsOptions, StartedServer)
+export * from './storage'                 // createStorage (+ CreateStorageOptions)
+export { isObject, normalizeHttpServerUrl } from './utils'
+```
+Removed from the public barrel (source files **stay** for internal use):
+- Host classes: `./host-agent` (`DevframeAgentHost`), `./host-diagnostics`
+  (`DevframeDiagnosticsHost`), `./host-services` (`DevframeServicesHostImpl`),
+  `./host-views` (`DevframeViewHost`).
+- Factories: `./rpc-core` (`createContextRpcServer` + its option/result types —
+  see the ⚠️ confirm note), `./rpc-shared-state`
+  (`createRpcSharedStateServerHost`), `./rpc-streaming`
+  (`createRpcStreamingServerHost`), `./scope` (`createScopedNodeContext`),
+  `./settings` (`createNodeSettings`).
+- Helpers: `./agent-args` (`coerceAgentPositionalArgs`, `AgentArgsFallback`),
+  and `toDialableHost` / `formatHostForUrl` from `./utils` (keep only `isObject`
+  + `normalizeHttpServerUrl`, both used by `vitejs/devtools`).
+
+These are single-package internals reached via relative imports inside
+`packages/devframe/src` (e.g. `node/context.ts` news up the host classes);
+removing them from the barrel does not break internal wiring. Verify no consumer
+depended on them:
+```sh
+rg -n "DevframeAgentHost|DevframeServicesHostImpl|createContextRpcServer|createRpcSharedStateServerHost|createRpcStreamingServerHost|createScopedNodeContext|createNodeSettings|coerceAgentPositionalArgs|toDialableHost|formatHostForUrl" plugins examples packages/next packages/nuxt packages/hub-ui packages/json-render packages/json-render-ui --glob '!**/dist/**'
+```
+Expected: no hits. (The `DevframeViewHost` / `DevframeDiagnosticsHost` **types**
+remain exported from `devframe/types` and re-exported by the hub — that is
+separate from these node **class** exports.)
+
+The `devframe/node` **entry point itself stays** (only its member set shrinks);
+no `package.json`/`tsdown` change here.
+
+### D. De-dup `@devframes/hub` `DEFAULT_CATEGORIES_ORDER`
+
+- `packages/hub/src/index.ts`: delete line
+  `export { DEFAULT_CATEGORIES_ORDER } from './constants'`.
+- `packages/hub/src/node/index.ts`: delete line 3
+  (`export { DEFAULT_CATEGORIES_ORDER } from '../constants'`) and its 2-line
+  comment.
+- `packages/hub/src/client/index.ts`: delete line 3 (same).
+- Keep the definition + export in `packages/hub/src/constants.ts`.
+
+Zero consumer churn: hub-ui (`src/client/constants.ts`) and the
+`vitejs/devtools` kit (`packages/kit/src/constants.ts`) already import it from
+`@devframes/hub/constants`. Verify:
+```sh
+rg -n "DEFAULT_CATEGORIES_ORDER" plugins examples packages --glob '!**/dist/**' | rg -v "packages/hub/src"
+```
+Expected: only `/constants` imports.
+
+### E. Docs, skills, templates
+
+- `docs/adapters/embedded.md` — delete the page; drop it from
+  `docs/adapters/index.md` and any sidebar/nav config. Where dynamic
+  registration is described, show `await devframe.setup(ctx)` (standalone) or
+  `mountDevframe` (hub) instead.
+- `skills/devframe/SKILL.md` — remove `createEmbedded` / `adapters/embedded`
+  references; update any `defineDevframe` import example to `from 'devframe'`;
+  ensure no example imports from `devframe/types`, `utils/hash|promise|scope`,
+  or `rpc/transports/ws-bun`.
+- `skills/devframe/templates/*` and `docs/**` code samples — same import sweep:
+  ```sh
+  rg -n "from 'devframe/types'|adapters/embedded|createEmbedded|utils/hash|utils/promise|utils/scope|ws-bun" docs skills
+  ```
+- Node reference (`docs/**` node page) — remove the dropped node exports from
+  any documented list.
+
+### F. Migration guide
+
+Append sections to `docs/guide/migration-0.9.md` (style: short prose + a
+before/after import table, matching the existing sections):
+
+1. **`defineDevframe` moves to the main entry** — `from 'devframe/types'` →
+   `from 'devframe'`; note `devframe/types` is now type-only and types are
+   importable from `devframe` directly.
+2. **`devframe/adapters/embedded` is removed** — replace
+   `createEmbedded(d, { ctx })` with `await d.setup(ctx)` (or `mountDevframe` in
+   a hub).
+3. **`devframe/rpc/transports/ws-bun` is removed** — build a Bun WS route with
+   `createRpcServer` + `attachWsRpcTransport` (`devframe/rpc/server` +
+   `devframe/rpc/transports/ws-server`), which remain public.
+4. **`devframe/utils/{hash,promise,scope}` are removed** — use
+   `Promise.withResolvers()` for `promise`; inline the trivial `hash` / `scope`
+   helpers if needed.
+5. **`devframe/node` slimmed** — list the removed host classes / factories /
+   helpers; note hand-rolled-server hosts should compose from
+   `devframe/rpc/server` + `devframe/rpc/transports/ws-server` +
+   `devframe/node/hub-internals` (the path `vitejs/devtools` already uses).
+6. **`@devframes/hub` `DEFAULT_CATEGORIES_ORDER`** — import from
+   `@devframes/hub/constants` (removed from `.`, `/node`, `/client`).
+
+---
+
+## Verification
+
+Run from the repo root, in order:
+
+```sh
+pnpm lint --fix
+pnpm knip          # must report no newly-unused files/exports; a deleted export that
+                   # left a dangling source file will surface here
+pnpm test          # runs build first (tsnapi api-snapshot compares fresh dist)
+pnpm typecheck
+pnpm build
+```
+
+Expected:
+- `knip` clean (if a kept-internal source file is now unused, either it was
+  truly dead → delete it, or a relative importer is missing → fix it).
+- `pnpm test` regenerates the `tsnapi` API snapshots under
+  `test/__snapshots__/`; **review the snapshot diff** — it is the authoritative
+  record of the surface change and must show exactly the removed/moved exports
+  and nothing else. Commit the updated snapshots.
+- `typecheck` clean across all workspaces (the consumer import rewrites in B are
+  the main risk; a missed `devframe/types` value import fails here).
+
+STOP conditions:
+- `knip` flags an unexpected unused export → a consumer rewrite was missed.
+- The API snapshot shows a surface change **not** in this plan → investigate
+  before committing.
+- Any `vitejs/devtools`-relied entry point (`devframe/rpc/server`,
+  `devframe/rpc/transports/ws-server`, `devframe/node/hub-internals`,
+  `devframe/node` {`isObject`,`normalizeHttpServerUrl`,`RpcFunctionsHost`},
+  `@devframes/hub/{client,node,types,constants}`) changed → revert that part;
+  it must stay.
+
+## Suggested commit sequence (one PR)
+
+1. `feat(devframe)!: remove dead subpaths (embedded, ws-bun, utils hash/promise/scope)`
+2. `feat(devframe)!: slim the node barrel to the server-assembly API`
+3. `feat(devframe)!: move defineDevframe to the main entry; make /types type-only` (+ consumer rewrites)
+4. `feat(hub)!: export DEFAULT_CATEGORIES_ORDER only from /constants`
+5. `docs: 0.9 migration notes + skill/template/adapters-doc sweep`
+
+Each commit must pass `pnpm build && pnpm typecheck` on its own so the API
+snapshot updates land with the change that causes them.
+
+## Maintenance notes
+
+**Breaking (⚠️), intentional, all covered by `migration-0.9.md`.** Every removed
+export is either unused across all audited consumers or has a documented
+in-tree replacement. The kept low-level layer (`node/auth`, `rpc/client` +
+`ws-client`, `rpc/server` + `ws-server`, `utils/{agent-tool-name,crypto-token,
+streaming-channel,structured-clone}`) is retained deliberately as the primitives
+the ergonomic APIs are built on and that test harnesses / hand-rolled hosts
+consume. Releasing 0.9.0 itself requires separate human approval.

plans/README.md

@@ -43,6 +43,7 @@ changes are allowed as long as they're marked).
 | 029 | Bring `@devframes/plugin-git` to the host baseline | direction/dx | P3 | S-M | — | TODO |
 | 030 | Spike: server-side auth enforcement ⚠️ | security | P2 | L | 003, 007, 015 | DONE |
 | 031 | Agent-native MCP wave (bridges, core surface, connector) | direction | P2 | L | — | IN PROGRESS (phases 1–3 implemented on PR #145; DONE at merge) |
+| 032 | Reduce the devframe + @devframes/hub public API surface for 0.9 ⚠️ | direction/tech-debt | P2 | L | — | TODO |
 
 Status values: TODO | IN PROGRESS | DONE | BLOCKED (one-line reason) | REJECTED (one-line rationale).