feat(devframe): promote cli.distDir to top-level clientAssets (#270)

Author: antfubot

docs/adapters/build.md

@@ -6,7 +6,7 @@ outline: deep
 
 Produces a self-contained static deploy of a devframe:
 
-1. Copies the author's SPA dist (`cli.distDir` or `options.distDir`) into `<outDir>`.
+1. Copies the author's SPA dist (`clientAssets` or `options.distDir`) into `<outDir>`.
 2. Runs `setup(ctx)` with `mode: 'build'`.
 3. Collects RPC dumps for every `'static'` function and any `'query'` function with `dump.inputs` / `snapshot: true`.
 4. Writes `<outDir>/__connection.json` (`{ backend: 'static' }`) and sharded dump files under `<outDir>/__rpc-dump/` — both at the SPA root so the deployed client discovers them via relative paths from `document.baseURI`.
@@ -23,7 +23,7 @@ await createBuild(devframe, {
 | Option | Default | Description |
 |--------|---------|-------------|
 | `outDir` | `dist-static` | Output directory. Cleared on each build. |
-| `distDir` | `def.cli?.distDir` | Override the SPA dist directory (a local path or a [remote assets](/guide/client-assets) package, materialized in full at build time). |
+| `distDir` | `def.clientAssets` (falls back to deprecated `def.cli?.distDir`) | Override the SPA dist directory (a local path or a [remote assets](/guide/client-assets) package, materialized in full at build time). |
 | `pretty` | `false` | Pretty-print dump JSON (larger on disk). |
 
 The resulting directory hosts on any static web server (`serve`, nginx, GitHub Pages, …). The client auto-detects `static` mode by resolving `./__connection.json` against `document.baseURI` and runs in read-only form.

docs/adapters/cac.md

@@ -21,7 +21,7 @@ import { createCac } from 'devframe/adapters/cac'
 const devframe = defineDevframe({
   id: 'my-devframe',
   name: 'My Devframe',
-  cli: { distDir: './client/dist' },
+  clientAssets: './client/dist',
   setup(ctx) { /* register docks, RPC, etc. */ },
 })
 
@@ -66,9 +66,9 @@ The `cli` property lets the caller add ad-hoc commands and flags right before `p
 ```ts
 defineDevframe({
   id: 'my-devframe',
+  clientAssets: './client/dist', // built SPA served as the UI
   cli: {
     command: 'my-devframe', // binary name; default: the id
-    distDir: './client/dist', // required for dev/build
     port: 7777, // preferred port
     portRange: [7777, 9000], // passed through to get-port-please
     random: false, // passed through to get-port-please
@@ -87,7 +87,7 @@ defineDevframe({
 })
 ```
 
-`distDir` is the only required field; everything else has sensible defaults. The `configure` hook runs *before* the `configureCli` option passed to `createCac`, so the final tool author always has the last word on flags.
+The top-level [`clientAssets`](/guide/client-assets) supplies the SPA the dev/build commands serve; everything under `cli` has sensible defaults. The `configure` hook runs *before* the `configureCli` option passed to `createCac`, so the final tool author always has the last word on flags.
 
 ## Headless logging
 

docs/adapters/dev.md

@@ -26,7 +26,7 @@ process.on('SIGINT', () => handle.close().then(() => process.exit(0)))
 | `host` | `def.cli?.host ?? 'localhost'` | Bind host. |
 | `port` | resolved via `resolveDevServerPort` | Port to listen on. |
 | `flags` | `{}` | Parsed flag bag forwarded to `setup(ctx, { flags })`. |
-| `distDir` | `def.cli?.distDir` | Required — throws when neither is set. |
+| `distDir` | `def.clientAssets` (falls back to deprecated `def.cli?.distDir`) | SPA dist override. When unset the server runs in bridge mode (meta + WS only). |
 | `basePath` | `resolveBasePath(def, 'standalone')` | Mount path override. |
 | `app` | fresh h3 app | Pre-configured h3 app to mount onto (custom middleware, auth, extra static assets). |
 | `openBrowser` | resolves from `flags.open` / `def.cli?.open` | Explicit on/off override. `false` disables; a string opens that relative path. |

docs/errors/DF0059.md

@@ -16,11 +16,9 @@ A remote-assets source (`{ package, version }` passed where a static mount accep
 
 ```ts
 defineDevframe({
-  cli: {
-    distDir: {
-      package: '@devframes/plugin-git-client',
-      version: '1.2.3',
-    },
+  clientAssets: {
+    package: '@devframes/plugin-git-client',
+    version: '1.2.3',
   },
 })
 ```

docs/errors/DF0060.md

@@ -16,11 +16,9 @@ A file of a remote-assets source was requested that is neither in the locally in
 
 ```ts
 defineDevframe({
-  cli: {
-    distDir: {
-      package: '@devframes/plugin-git-client',
-      version: '1.2.3',
-    },
+  clientAssets: {
+    package: '@devframes/plugin-git-client',
+    version: '1.2.3',
   },
 })
 ```

docs/errors/DF0061.md

@@ -16,12 +16,10 @@ A remote-assets source found a locally installed copy of its assets package (res
 
 ```ts
 defineDevframe({
-  cli: {
-    distDir: {
-      package: '@devframes/plugin-git-client',
-      version: '2.0.0',
-      resolveFrom: import.meta.url,
-    },
+  clientAssets: {
+    package: '@devframes/plugin-git-client',
+    version: '2.0.0',
+    resolveFrom: import.meta.url,
   },
 })
 ```

docs/errors/DF0064.md

@@ -10,7 +10,7 @@ outline: deep
 
 ## Cause
 
-A static build (`createBuild`) with a remote-assets `distDir` needs every asset file up front — the output must be self-contained. Materialization walks the provider's file listing and downloads each file, and one of those steps failed: the provider has no `listFiles` (custom providers may omit it), the listing request failed, or an individual file download errored.
+A static build (`createBuild`) with remote-assets `clientAssets` needs every asset file up front — the output must be self-contained. Materialization walks the provider's file listing and downloads each file, and one of those steps failed: the provider has no `listFiles` (custom providers may omit it), the listing request failed, or an individual file download errored.
 
 ## Example
 

docs/errors/DF0065.md

@@ -16,11 +16,9 @@ A remote-assets source's `package` and `version` are interpolated into CDN URLs
 
 ```ts
 defineDevframe({
-  cli: {
-    distDir: {
-      package: '@devframes/plugin-git-client',
-      version: '../etc', // ✗ not a semver version
-    },
+  clientAssets: {
+    package: '@devframes/plugin-git-client',
+    version: '../etc', // ✗ not a semver version
   },
 })
 ```
@@ -31,11 +29,9 @@ Use a valid npm package name and an exact version:
 
 ```ts
 defineDevframe({
-  cli: {
-    distDir: {
-      package: '@devframes/plugin-git-client',
-      version: '1.2.3',
-    },
+  clientAssets: {
+    package: '@devframes/plugin-git-client',
+    version: '1.2.3',
   },
 })
 ```

docs/errors/DF8106.md

@@ -12,7 +12,7 @@ outline: deep
 
 A mounted devframe's SPA loads in an iframe at its own base (e.g. `/__terminals/`) and calls `connectDevframe()`, which fetches `./__connection.json` relative to that base to discover the RPC/WebSocket endpoint. `ctx.install` serves that file at each base by calling the host's `mountConnectionMeta(base)` alongside `mountStatic`.
 
-This diagnostic is reported when a devframe with a servable `cli.distDir` is mounted on a `DevframeHost` that does not implement `mountConnectionMeta`. The SPA's `./__connection.json` fetch then falls through to the host's HTML fallback, so the SPA cannot discover the endpoint and its panel stays empty or stuck loading — previously a silent failure.
+This diagnostic is reported when a devframe with servable `clientAssets` is mounted on a `DevframeHost` that does not implement `mountConnectionMeta`. The SPA's `./__connection.json` fetch then falls through to the host's HTML fallback, so the SPA cannot discover the endpoint and its panel stays empty or stuck loading — previously a silent failure.
 
 The SPA can still connect when it shares an origin with the hub UI, by inheriting the connection meta from the parent window. Cross-origin, sandboxed, or directly-opened iframes have no such parent to inherit from.
 
@@ -35,4 +35,4 @@ A static-snapshot host that bakes `__connection.json` into its served files can
 
 ## Source
 
-- [`packages/hub/src/node/install-devframe.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/install-devframe.ts) — `ctx.install()` emits this when a devframe with a servable `distDir` is installed on a host lacking `mountConnectionMeta`.
+- [`packages/hub/src/node/install-devframe.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/install-devframe.ts) — `ctx.install()` emits this when a devframe with servable `clientAssets` is installed on a host lacking `mountConnectionMeta`.

docs/examples/json-render.md

@@ -20,7 +20,7 @@ Package: `json-render` · frontend: **prebuilt `@devframes/json-render-ui/spa`**
 - **Action bridge** — the `Refresh` button's `press` action is dispatched as an
   RPC call of the same name; the handler bumps a counter and patches state, with
   per-action loading and error surfacing.
-- **Out-of-box SPA** — `createJsonRenderDevframe` points `cli.distDir` at the
+- **Out-of-box SPA** — `createJsonRenderDevframe` points `clientAssets` at the
   prebuilt `@devframes/json-render-ui/spa`, which discovers the view from the
   view index and renders it — no client build in the example.
 - **Static output** — `cli:build` snapshots the spec + state as a read-only