Merge remote-tracking branch 'upstream/main' into feat/auth-otp-token-exchange

# Conflicts:
#	tests/__snapshots__/tsnapi/devframe/client.snapshot.d.ts
#	tests/__snapshots__/tsnapi/devframe/client.snapshot.js

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

@@ -25,6 +25,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/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

@@ -105,30 +105,32 @@ const ok = await rpc.requestTrustWithToken('a1b2c3…')
 
 ## 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 }) => {
@@ -143,7 +145,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())
 
@@ -158,6 +160,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:

docs/guide/devframe-definition.md

@@ -15,11 +15,18 @@ import * as v from 'valibot'
 export default defineDevframe({
   id: 'my-devframe',
   name: 'My Devframe',
+  version: '1.0.0',
+  packageName: 'my-devframe',
+  homepage: 'https://github.com/me/my-devframe',
+  description: 'A one-line summary of what the tool does.',
   icon: 'ph:gauge-duotone',
   setup(ctx) {
+    // A scoped context auto-namespaces ids with your devframe `id`.
+    const my = ctx.scope('my-devframe')
+
     // Register your RPC functions, shared state, etc. here.
-    ctx.rpc.register(defineRpcFunction({
-      name: 'my-devframe:hello',
+    my.rpc.register(defineRpcFunction({
+      name: 'hello', // stored as `my-devframe:hello`
       type: 'static',
       jsonSerializable: true,
       handler: () => ({ message: 'hello' }),
@@ -28,23 +35,47 @@ export default defineDevframe({
 })
 ```
 
-Host adapters (such as the [`vite` adapter](/adapters/vite) for Vite DevTools) derive their mount entry from `id`, `name`, `icon`, and `basePath` automatically.
+`ctx.scope(id)` is the preferred way to consume the context — see [Scoped Context](./scoped-context). Host adapters (such as the [`vite` adapter](/adapters/vite) for Vite DevTools) derive their mount entry from `id`, `name`, `icon`, and `basePath` automatically.
 
 ## Definition fields
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | `string` | **Required.** Unique, namespaced identifier (kebab-case). Used as a prefix for RPC names, dock IDs, and MCP tool names. |
 | `name` | `string` | **Required.** Display name shown in the dock and agent manifests. |
+| `version` | `string` | **Required.** Semver of the tool, surfaced in hub UIs and diagnostics. |
+| `packageName` | `string` | **Required.** npm package name the devframe ships in (e.g. `@scope/my-tool`). |
+| `homepage` | `string` | **Required.** Project homepage or documentation URL. |
+| `description` | `string` | **Required.** One-line summary of what the tool does. |
 | `icon` | `string \| { light, dark }` | Optional Iconify name or URL; supports light/dark pairs. |
-| `version` | `string` | Optional version string surfaced to clients. |
 | `basePath` | `string` | Optional mount path override. Defaults depend on the adapter: `/` for standalone (`cli` / `spa` / `build`), `/.<id>/` for hosted (`vite` / `embedded`). |
+| `duplicationStrategy` | `'warn' \| 'silent' \| 'throw' \| 'duplicate'` | How a hub reacts when another devframe sharing this `id` is mounted onto the same hub. Defaults to `'warn'`. See [Hub](./hub). Hub adapters consult it; standalone adapters ignore it. |
 | `capabilities` | `{ dev?, build?, spa? }` | Per-runtime feature flags. A `boolean` applies to the runtime as a whole; an object enables individual features. |
 | `setup` | `(ctx, info?) => void \| Promise<void>` | **Required.** Server-side entry point. Runs in every runtime. The optional second argument carries runtime metadata — most notably the parsed CLI `flags` when running under `createCli`. |
 | `setupBrowser` | `(ctx) => void \| Promise<void>` | Browser-only entry used by the SPA adapter. |
 | `cli` | `DevframeCliOptions` | Defaults for the CLI adapter. See [CLI options](#cli-options) below. |
 | `spa` | `DevframeSpaOptions` | Defaults for the SPA adapter (`base`, `loader`). |
 
+### Sourcing metadata from `package.json`
+
+Keep `version`, `packageName`, `homepage`, and `description` in sync with the package you publish by importing them straight from its `package.json`. Note that the package's `name` field maps to `packageName` — the devframe `name` is a separate display label.
+
+```ts
+import pkg from '../package.json' with { type: 'json' }
+
+export default defineDevframe({
+  id: 'my-devframe',
+  name: 'My Devframe', // display label
+  version: pkg.version,
+  packageName: pkg.name,
+  homepage: pkg.homepage,
+  description: pkg.description,
+  setup(ctx) { /* … */ },
+})
+```
+
+The default import with a `with { type: 'json' }` attribute resolves under both bundlers and Node's native TypeScript execution. Bundlers also support the destructured `import { version } from '../package.json'` form when the devframe is always bundled before it runs.
+
 ### Runtime flags
 
 The `ctx.mode` field is either `'dev'` or `'build'`. Use it to gate work that should only run in one runtime:
@@ -81,12 +112,17 @@ interface DevframeNodeContext {
   views: DevframeViewHost // static file hosting (`hostStatic`)
   diagnostics: DevframeDiagnosticsHost
   agent: DevframeAgentHost // experimental
+
+  scope: (id) => DevframeScopedNodeContext // namespaced view (preferred)
 }
 ```
 
+`ctx.scope(id)` returns a namespace-scoped view that auto-prefixes every RPC id, shared-state key, and streaming channel and adds a persisted top-level `settings` store. It's the recommended entry point from a single tool's setup code — see [Scoped Context](./scoped-context).
+
 Host adapters can augment `ctx` with additional surfaces. For example, the [`vite` adapter](/adapters/vite) exposes Vite DevTools' dock, command, message, and terminal hosts via an optional `setup` hook on `createPluginFromDevframe` — consult the host's docs for those extras.
 
 Each devframe-level host has a dedicated page:
+- [Scoped Context](./scoped-context) — `ctx.scope(id)`, `settings`
 - [RPC](./rpc) — `ctx.rpc`
 - [Shared State](./shared-state) — `ctx.rpc.sharedState`
 - [Diagnostics](./diagnostics) — `ctx.diagnostics`

docs/guide/hub.md

@@ -43,6 +43,25 @@ await mountDevframe(ctx, myDevframe)
 
 Framework kits typically wrap this in a plugin shell. `@vitejs/devtools-kit`'s `createPluginFromDevframe` returns a Vite `Plugin` whose `devtools.setup` calls into `mountDevframe`.
 
+### Duplicate devframes
+
+When a devframe sharing an already-mounted `id` is mounted onto the same hub, its `duplicationStrategy` decides what happens. By default the first registration wins:
+
+| Strategy | Behavior |
+|---|---|
+| `'warn'` (default) | Keep the first registration, drop the later one, and emit `DF8105`. |
+| `'silent'` | Drop the later one without warning. |
+| `'throw'` | Throw `DF8105`. |
+| `'duplicate'` | Let every instance coexist under a disambiguated dock id (`my-tool`, `my-tool-2`, …). |
+
+```ts
+defineDevframe({
+  id: 'my-tool',
+  // …
+  duplicationStrategy: 'duplicate',
+})
+```
+
 ## Grouping dock entries
 
 When a hub combines many integrations, related dock entries can collapse under a single dock-bar button. A `type: 'group'` entry is that button; any entry pointing its `groupId` at the group's `id` becomes a member.