refactor: unify plugin RPC namespaces to devframes:plugin:<slug>:<fn> (#105)

Co-authored-by: opencode <noreply@opencode.ai>

Author: antfubot

AGENTS.md

@@ -35,7 +35,7 @@ The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots co
 
 ## Conventions
 
-- RPC functions must use `defineRpcFunction`; always namespace IDs (`my-plugin:fn-name`).
+- RPC functions must use `defineRpcFunction`; always namespace IDs `devframes:plugin:<slug>:<fn-name>` (matching the plugin's `@devframes/plugin-<slug>` package name).
 - Shared state via `devframe/utils/shared-state`; keep values serializable.
 - Utility imports use the package-path form `devframe/utils/*`, never relative `../utils/*`.
 - Dependencies go through the pnpm catalogs in `pnpm-workspace.yaml` (`cli`, `inlined`, `testing`, `types`) — add to a catalog and reference as `catalog:<name>`, don't pin versions in `package.json`.

docs/errors/DF8107.md

@@ -16,11 +16,11 @@ This is a warning, not a thrown error: the activation is still broadcast so a do
 
 ## Fix
 
-Pass a `dockId` that matches a registered dock entry. Ids are case-sensitive, so check for typos, and make sure the target dock is registered before activating it. For the terminals dock the id is `devframes-plugin-terminals`:
+Pass a `dockId` that matches a registered dock entry. Ids are case-sensitive, so check for typos, and make sure the target dock is registered before activating it. For the terminals dock the id is `devframes_plugin_terminals`:
 
 ```ts
 await rpc.call('hub:docks:activate', {
-  dockId: 'devframes-plugin-terminals',
+  dockId: 'devframes_plugin_terminals',
   params: { sessionId },
 })
 ```

docs/guide/hub.md

@@ -35,7 +35,7 @@ The viewer's active dock is client-local state — which dock is on screen lives
 ```ts
 // From inside a mounted devframe's iframe (its own RPC client):
 await rpc.call('hub:docks:activate', {
-  dockId: 'devframes-plugin-terminals',
+  dockId: 'devframes_plugin_terminals',
   params: { sessionId }, // opaque bag the target dock interprets
 })
 ```

docs/plugins/code-server.md

@@ -49,7 +49,7 @@ export default createCodeServerDevframe({
 
 ## RPC surface
 
-All functions are namespaced `devframes-plugin-code-server:*`:
+All functions are namespaced `devframes:plugin:code-server:*`:
 
 | Function | Type | Purpose |
 |----------|------|---------|

docs/plugins/git.md

@@ -41,12 +41,12 @@ await createCac(createGitDevframe({ repoRoot: process.cwd() })).parse()
 
 The read functions are each a `query` with `snapshot: true` — resolved live over WebSocket in dev, and served from a snapshot baked at build time for static deploys. Each degrades to an empty, `isRepo: false` result outside a git repository.
 
-- `git:status` — branch, upstream tracking, and staged / unstaged / untracked files.
-- `git:log` — paginated commit history including parent hashes, which drive the commit graph.
-- `git:branches` — local branches with SHA, upstream, ahead / behind, and tip subject.
-- `git:diff` — per-file added / deleted counts plus a unified patch for a selected file.
+- `devframes:plugin:git:status` — branch, upstream tracking, and staged / unstaged / untracked files.
+- `devframes:plugin:git:log` — paginated commit history including parent hashes, which drive the commit graph.
+- `devframes:plugin:git:branches` — local branches with SHA, upstream, ahead / behind, and tip subject.
+- `devframes:plugin:git:diff` — per-file added / deleted counts plus a unified patch for a selected file.
 
-Write actions (`git:stage`, `git:unstage`, `git:commit`) are `action` functions, registered only when write mode is enabled.
+Write actions (`devframes:plugin:git:stage`, `devframes:plugin:git:unstage`, `devframes:plugin:git:commit`) are `action` functions, registered only when write mode is enabled.
 
 ## Source
 

docs/plugins/inspect.md

@@ -52,7 +52,7 @@ await createCac(createInspectDevframe({ port: 9100 })).parse()
 
 ## RPC surface
 
-All functions are namespaced `devframes-plugin-inspect:*`:
+All functions are namespaced `devframes:plugin:inspect:*`:
 
 | Function | Type | Returns |
 |----------|------|---------|

docs/plugins/terminals.md

@@ -52,20 +52,20 @@ export default createTerminalsDevframe({
 
 ## Hub aggregation
 
-Mounted into a hub, the plugin owns PTY/child-process spawning and its own streaming channel (`devframes-plugin-terminals:output`) — that's what the panel renders. It also mirrors every session it spawns into `ctx.terminals` (the hub's aggregate registry, streaming on `devframe:terminals`) so other tools — a launcher dock, a custom panel — see the same session list without depending on the plugin's own types. A session started the other way, via `ctx.terminals.startChildProcess` / `startPtySession` directly (e.g. from a launcher dock), shows up in the terminals panel too — the plugin reads foreign hub sessions read-only and renders them alongside its own, subscribing to the hub's channel for their output.
+Mounted into a hub, the plugin owns PTY/child-process spawning and its own streaming channel (`devframes:plugin:terminals:output`) — that's what the panel renders. It also mirrors every session it spawns into `ctx.terminals` (the hub's aggregate registry, streaming on `devframe:terminals`) so other tools — a launcher dock, a custom panel — see the same session list without depending on the plugin's own types. A session started the other way, via `ctx.terminals.startChildProcess` / `startPtySession` directly (e.g. from a launcher dock), shows up in the terminals panel too — the plugin reads foreign hub sessions read-only and renders them alongside its own, subscribing to the hub's channel for their output.
 
 `ctx.terminals` is the source of truth for "what sessions exist"; the plugin is the panel that renders them and the one PTY-capable provider among possibly several session sources. The plugin never imports `@devframes/hub`'s types to stay mountable without a hub — it duck-types the minimal `register` / `update` / `events` shape it needs.
 
 A session from `ctx.terminals.startChildProcess()` carries a `getResult()` accessor shaped like `tinyexec`'s `Result` — `await`able to `{ stdout, stderr, exitCode }` (captured separately from the merged display stream), with live `pid` / `exitCode` / `killed` getters and `kill()` in the meantime. That's the seam for migrating an existing `tinyexec`/`execa`-based "run a subprocess and get its result" API onto the hub's terminals: keep the same calling code, swap the runner for `startChildProcess()`, and the session's output shows up in every hub-aware terminal panel for free.
 
 ## Focusing a session
 
-The panel reacts to the hub's [cross-iframe dock activation](/guide/hub#cross-iframe-dock-activation): when an activation targets this dock (`dockId: 'devframes-plugin-terminals'`) and carries a `sessionId`, the panel selects that session. This lets another tool spawn a build and jump the user straight to its output:
+The panel reacts to the hub's [cross-iframe dock activation](/guide/hub#cross-iframe-dock-activation): when an activation targets this dock (`dockId: 'devframes_plugin_terminals'`) and carries a `sessionId`, the panel selects that session. This lets another tool spawn a build and jump the user straight to its output:
 
 ```ts
 // e.g. right after ctx.terminals.startChildProcess(..., { id: sessionId, ... })
 await rpc.call('hub:docks:activate', {
-  dockId: 'devframes-plugin-terminals',
+  dockId: 'devframes_plugin_terminals',
   params: { sessionId },
 })
 ```

examples/minimal-next-devframe-hub/tests/minimal-next-devframe-hub.test.ts

@@ -39,8 +39,8 @@ describe('minimal-next-devframe-hub (example)', () => {
     expect(dockIds).toContain('~settings')
     expect(docks.find(d => d.id === '~settings')?.category).toBe('~builtin')
     // The dogfooded built-in plugin packages mount their own docks.
-    expect(dockIds).toContain('devframes-plugin-terminals')
-    expect(dockIds).toContain('devframes-plugin-messages')
+    expect(dockIds).toContain('devframes_plugin_terminals')
+    expect(dockIds).toContain('devframes_plugin_messages')
   })
 
   it('lists startup and demo messages through the kit-local RPC', async () => {

packages/hub/src/client/__tests__/host.test.ts

@@ -125,17 +125,17 @@ describe('createDevframeClientHost', () => {
   it('switches the active dock when the hub broadcasts devframe:docks:activate', async () => {
     const { rpc, states, definitions } = createStubRpc()
     const host = await createDevframeClientHost({ rpc })
-    states.get('devframe:docks')!.push([iframeEntry('one'), iframeEntry('devframes-plugin-terminals')])
+    states.get('devframe:docks')!.push([iframeEntry('one'), iframeEntry('devframes_plugin_terminals')])
 
     // Simulate the hub's server→client broadcast.
     const handler = definitions.get('devframe:docks:activate')!.handler!
-    handler({ dockId: 'devframes-plugin-terminals', params: { sessionId: 'sess-1' } })
-    await vi.waitFor(() => expect(host.context.docks.selectedId).toBe('devframes-plugin-terminals'))
+    handler({ dockId: 'devframes_plugin_terminals', params: { sessionId: 'sess-1' } })
+    await vi.waitFor(() => expect(host.context.docks.selectedId).toBe('devframes_plugin_terminals'))
 
     // Unknown dock ids degrade to a no-op (the previous selection stands).
     handler({ dockId: 'ghost' })
     await new Promise(r => setTimeout(r, 0))
-    expect(host.context.docks.selectedId).toBe('devframes-plugin-terminals')
+    expect(host.context.docks.selectedId).toBe('devframes_plugin_terminals')
     host.dispose()
   })
 

packages/hub/src/node/__tests__/context.test.ts

@@ -37,23 +37,23 @@ describe('createHubContext dock activation', () => {
     })
     context.docks.register({
       type: 'iframe',
-      id: 'devframes-plugin-terminals',
+      id: 'devframes_plugin_terminals',
       title: 'Terminals',
       icon: 'ph:terminal-window-duotone',
-      url: '/__devframes-plugin-terminals/',
+      url: '/__devframes_plugin_terminals/',
     })
 
     const broadcast = vi.spyOn(context.rpc, 'broadcast').mockResolvedValue()
-    context.docks.activate('devframes-plugin-terminals', { sessionId: 'sess-1' })
+    context.docks.activate('devframes_plugin_terminals', { sessionId: 'sess-1' })
 
     const active = await context.rpc.sharedState.get<{ activation: unknown }>('devframe:docks:active')
     expect(active.value().activation).toEqual({
-      dockId: 'devframes-plugin-terminals',
+      dockId: 'devframes_plugin_terminals',
       params: { sessionId: 'sess-1' },
     })
     expect(broadcast).toHaveBeenCalledWith({
       method: 'devframe:docks:activate',
-      args: [{ dockId: 'devframes-plugin-terminals', params: { sessionId: 'sess-1' } }],
+      args: [{ dockId: 'devframes_plugin_terminals', params: { sessionId: 'sess-1' } }],
     })
     broadcast.mockRestore()
   })