Merge branch 'main' of https://github.com/devframes/devframe into feat/plugin-inspect

Author: antfubot

AGENTS.md

@@ -22,13 +22,15 @@ pnpm install      # requires pnpm@11.x
 pnpm build        # tsdown
 pnpm dev          # tsdown --watch
 pnpm test         # pnpm build && vitest (api snapshot guards against stale dist)
-pnpm typecheck    # tsc --noEmit
+pnpm typecheck    # turbo run typecheck (per-package tsc --noEmit)
 pnpm lint --fix   # ESLint via @antfu/eslint-config
 pnpm start        # tsx src/index.ts
 ```
 
 The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots compare against fresh `dist/`. `tsdown-stale-guard` enforces this in `test/api-snapshot.test.ts`.
 
+`pnpm typecheck` fans out through Turbo: every workspace package owns a `"typecheck": "tsc --noEmit"` script and its own `tsconfig.json` (extending `tsconfig.base.json` with an explicit `include`). Cross-package imports resolve to source through the `paths` aliases in `tsconfig.base.json`, so no prior build is needed. Any package added under `packages/*` or `plugins/*` is typechecked automatically once it ships that `typecheck` script — add one to every new package so it can't silently skip type errors.
+
 ## Conventions
 
 - RPC functions must use `defineRpcFunction`; always namespace IDs (`my-plugin:fn-name`).

alias.ts

@@ -26,6 +26,7 @@ export const alias = {
   '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/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/.vitepress/config.ts

@@ -21,6 +21,7 @@ function guideItems(prefix: string): DefaultTheme.NavItemWithLink[] {
     { text: 'Introduction', link: `${prefix}/guide/` },
     { text: 'Built with Devframe', link: `${prefix}/guide/built-with` },
     { text: 'Devframe Definition', link: `${prefix}/guide/devframe-definition` },
+    { text: 'Scoped Context', link: `${prefix}/guide/scoped-context` },
     { text: 'RPC', link: `${prefix}/guide/rpc` },
     { text: 'Shared State', link: `${prefix}/guide/shared-state` },
     { text: 'Streaming', link: `${prefix}/guide/streaming` },

docs/errors/DF0034.md

@@ -0,0 +1,34 @@
+---
+outline: deep
+---
+
+# DF0034: Already-Namespaced Scoped Registration
+
+## Message
+
+> Scoped RPC registration for namespace "`{namespace}`" received an already-namespaced function name "`{name}`".
+
+## Cause
+
+A [scoped context](../guide/scoped-context) auto-namespaces the ids you pass it. `ctx.scope('my-plugin').rpc.register(...)` therefore expects a **bare** function name and stores it as `my-plugin:<name>`. Passing a name that already contains a `:` separator would produce a double-prefixed id, so registration throws instead.
+
+## Example
+
+```ts
+const my = ctx.scope('my-plugin')
+
+// ✗ Bad — already namespaced
+my.rpc.register(defineRpcFunction({ name: 'my-plugin:get-cwd', type: 'query', handler }))
+
+// ✓ Good — bare name, stored as `my-plugin:get-cwd`
+my.rpc.register(defineRpcFunction({ name: 'get-cwd', type: 'query', handler }))
+```
+
+## Fix
+
+- Pass a bare name (no `:` separator) to the scoped `register`.
+- To register a fully-qualified name on purpose, use the unscoped host: `ctx.base.rpc.register(...)` (server) or `client.scope(...).base.client.register(...)` (browser).
+
+## Source
+
+- [`packages/devframe/src/node/scope.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/scope.ts) — `register()` / `update()` throw this when the supplied definition name is already namespaced.

docs/errors/DF8101.md

@@ -6,7 +6,7 @@ outline: deep
 
 ## Message
 
-> Cannot change the id of a dock. Use register() to add new docks.
+> Cannot change the id of dock "`{id}`" to "`{attempted}`". Dock ids are immutable once registered
 
 ## Cause
 

docs/errors/DF8102.md

@@ -6,7 +6,7 @@ outline: deep
 
 ## Message
 
-> Dock with id "`{id}`" is not registered. Use register() to add new docks.
+> Dock with id "`{id}`" is not registered and cannot be updated
 
 ## Cause
 

docs/errors/DF8103.md

@@ -0,0 +1,22 @@
+---
+outline: deep
+---
+
+# DF8103: Dock Entry Cannot Group Itself
+
+## Message
+
+> Dock entry "`{id}`" cannot set groupId to its own id
+
+## Cause
+
+A dock entry registered with `groupId` pointing at its own `id`. `groupId` is a pointer to a *different* group entry the entry belongs to, so a self-reference would describe an entry that collapses under itself.
+
+## Fix
+
+- Point `groupId` at the `id` of a `type: 'group'` entry, such as `groupId: 'nuxt'`.
+- Omit `groupId` entirely to keep the entry as a normal top-level dock entry.
+
+## Source
+
+- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts) — `DevframeDocksHost.register()` and `update()` throw this when `view.groupId === view.id`.

docs/errors/DF8104.md

@@ -0,0 +1,22 @@
+---
+outline: deep
+---
+
+# DF8104: Nested Dock Groups Unsupported
+
+## Message
+
+> Dock group "`{id}`" cannot itself belong to a group (nested groups are unsupported)
+
+## Cause
+
+A `type: 'group'` entry was registered with `groupId` set. Dock grouping is one level deep: a group collects member entries, but a group cannot itself be a member of another group.
+
+## Fix
+
+- Remove `groupId` from the group entry so it stays a top-level dock-bar button.
+- Keep members one level under their group; place each member's `groupId` on the leaf entry, not on another group.
+
+## Source
+
+- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts) — `DevframeDocksHost.register()` and `update()` throw this when `view.type === 'group'` and `view.groupId` is set.

docs/errors/DF8105.md

@@ -0,0 +1,28 @@
+---
+outline: deep
+---
+
+# DF8105: Devframe Already Mounted
+
+## Message
+
+> Devframe "`{name}`" (id "`{id}`") is already mounted on this hub
+
+## Cause
+
+`mountDevframe(ctx, def)` was called with a devframe whose `id` already belongs to another devframe mounted on the same hub. Devframes are deduplicated by `id`, and the definition's `duplicationStrategy` is `'warn'` (the default) or `'throw'`.
+
+## Fix
+
+Set `duplicationStrategy` on the definition to choose how duplicates are handled:
+
+- `'warn'` (default) — keep the first registration, drop the later one, and emit this warning.
+- `'silent'` — drop the later one without warning.
+- `'throw'` — surface duplicates as a thrown error.
+- `'duplicate'` — let every instance coexist under a disambiguated dock id (`my-tool`, `my-tool-2`, …).
+
+Otherwise, remove the redundant `mountDevframe` call so each devframe is mounted once.
+
+## Source
+
+- [`packages/hub/src/node/mount-devframe.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/mount-devframe.ts) — `mountDevframe()` emits this when a devframe sharing an already-mounted `id` is mounted and the strategy is not `'duplicate'`.

docs/guide/client.md

@@ -93,30 +93,32 @@ const ok = await rpc.requestTrustWithToken('another-token')
 
 ## Calling functions
 
+Derive a [scoped client](./scoped-context) so ids are namespaced for you:
+
 ```ts
-const rpc = await connectDevframe()
+const my = (await connectDevframe()).scope('my-devframe')
 
 // Standard call — awaits a response or throws.
-const modules = await rpc.call('my-devframe:get-modules', { limit: 10 })
+const modules = await my.rpc.call('get-modules', { limit: 10 })
 
 // Optional — returns undefined when no handler responds (useful while HMR is restarting).
-const maybe = await rpc.callOptional('my-devframe:get-modules', { limit: 10 })
+const maybe = await my.rpc.callOptional('get-modules', { limit: 10 })
 
 // Event — fire-and-forget, no response expected.
-rpc.callEvent('my-devframe:notify', { message: 'hello' })
+my.rpc.callEvent('notify', { message: 'hello' })
 ```
 
-TypeScript types flow through from the server's `defineRpcFunction` definitions, so argument and return shapes are known at the call site.
+The unscoped `rpc.call('my-devframe:get-modules', ...)` works too. Either way, TypeScript types flow through from the server's `defineRpcFunction` definitions, so argument and return shapes are known at the call site.
 
 ## Registering client functions
 
-The client can register functions that the server calls via `ctx.rpc.broadcast`:
+The client can register functions that the server calls via `rpc.broadcast`:
 
 ```ts
 import { defineRpcFunction } from 'devframe'
 
-rpc.client.register(defineRpcFunction({
-  name: 'my-devframe:on-file-changed',
+my.rpc.register(defineRpcFunction({
+  name: 'on-file-changed', // -> my-devframe:on-file-changed
   type: 'event',
   setup: () => ({
     handler: async ({ file }: { file: string }) => {
@@ -131,7 +133,7 @@ That's how the server pushes live updates into the UI — file-watcher events, s
 ## Shared state
 
 ```ts
-const state = await rpc.sharedState.get('my-devframe:state')
+const state = await my.rpc.sharedState('state') // -> my-devframe:state
 
 console.log(state.value())
 
@@ -146,6 +148,17 @@ state.on('updated', (next) => {
 
 Client-side mutations round-trip through the server before reappearing locally. See [Shared State](./shared-state) for the full API.
 
+## Settings
+
+A scoped client also exposes a top-level persisted `settings` store, synced from the server. Read and write per-user (`global`) or per-workspace (`project`) values:
+
+```ts
+await my.settings.project.set('theme', 'dark')
+const theme = await my.settings.project.get('theme')
+```
+
+See [Scoped Context](./scoped-context#settings) for the full API.
+
 ## Caching
 
 Set `cacheOptions: true` (or an options object) when constructing the client: