refactor: move snapshotRpc under rpc.snapshot on DevframeDefinition

Group the RPC static-build opt-in under a new `rpc` config object:
`DevframeDefinition.rpc.snapshot` (new `DevframeRpcOptions`) replaces the
top-level `snapshotRpc`. Entry types and the `applySnapshotRpc` build
helper are unchanged; the git plugin, build adapter, DF0072 message, tests,
and docs are updated to the new shape.

Author: antfubot

docs/guide/devframe-definition.md

@@ -54,7 +54,7 @@ export default defineDevframe({
 | `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? }` | Per-runtime feature flags. A `boolean` applies to the runtime as a whole; an object enables individual features. |
 | `services` | `DevframeServiceInput[]` | Wire services this devframe consumes — descriptors (`{ package, version?, required?, options? }`) the adapter imports against the plugin's own dependencies, or ready definitions. See [Cross-Plugin Services](./services#wire-services). |
-| `snapshotRpc` | `(string \| { method, inputs })[]` | Opt an RPC function this devframe doesn't own (e.g. a wire service's) into the static build's dump. A bare method id bakes the no-argument call; `{ method, inputs }` bakes one record per argument-tuple, where `inputs` is a list of tuples or an async `(ctx) => tuples` provider (so it can enumerate at build time via the service's node API). The first tuple's result becomes the fallback. |
+| `rpc` | `{ snapshot?: (string \| { method, inputs })[] }` | RPC-level config. `rpc.snapshot` opts an RPC function this devframe doesn't own (e.g. a wire service's) into the static build's dump. A bare method id bakes the no-argument call; `{ method, inputs }` bakes one record per argument-tuple, where `inputs` is a list of tuples or an async `(ctx) => tuples` provider (so it can enumerate at build time via the service's node API). The first tuple's result becomes the fallback. |
 | `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 `createCac`. |
 | `cli` | `DevframeCliOptions` | Defaults for the CLI adapter. See [CLI options](#cli-options) below. |
 

docs/guide/services.md

@@ -155,7 +155,7 @@ state.on('updated', render)
 
 **`@devframes/service-open`** (`devframes:service:open`) opens files in the user's editor (`open-in-editor`, with optional `line`/`column`) or reveals them in the OS file explorer (`open-in-finder`). Paths may be absolute or relative to the workspace root (so a client with only a workspace-relative path — a message's file position, say — calls it directly); the service refuses anything outside the workspace root and the configured extra `roots` (`DS_OPEN_0002`), and gates editor commands to the `KNOWN_EDITORS` picklist. Options: `{ editor?, roots? }` — the preferred editor (later installer wins) and additional openable directories (merged as a union). It supersedes the per-plugin `devframe/recipes/common-rpc-functions` registrations, now deprecated.
 
-**`@devframes/service-git`** (`devframes:service:git`) runs read/write git operations over RPC — `status`, `log`, `show`, `diff`, `branches`, `stage`, `unstage`, `commit` — with parsed, typed results, so a devframe (the git plugin, or any tool) consumes git without shelling out itself. It operates on a single repo fixed at install (`{ cwd? }`, defaulting to the context cwd; root discovered once). Write ops are always exposed — authorization is the host's connection-trust boundary. The service defines no `dump`/`snapshot`; a devframe bakes the read ops it wants into a static build via [`snapshotRpc`](./devframe-definition). Client-supplied revisions are guarded against option injection.
+**`@devframes/service-git`** (`devframes:service:git`) runs read/write git operations over RPC — `status`, `log`, `show`, `diff`, `branches`, `stage`, `unstage`, `commit` — with parsed, typed results, so a devframe (the git plugin, or any tool) consumes git without shelling out itself. It operates on a single repo fixed at install (`{ cwd? }`, defaulting to the context cwd; root discovered once). Write ops are always exposed — authorization is the host's connection-trust boundary. The service defines no `dump`/`snapshot`; a devframe bakes the read ops it wants into a static build via [`rpc.snapshot`](./devframe-definition). Client-supplied revisions are guarded against option injection.
 
 **`@devframes/service-shiki`** (`devframes:service:shiki`) renders [Shiki](https://shiki.style) syntax highlighting on the server, so plugin bundles stop shipping grammars and themes. Three RPC queries — `highlight` (dual-theme HTML), `code-to-hast`, and `code-to-tokens` (for renderers that own their DOM, e.g. diff views) — all client-`cacheable` and LRU-cached server-side per `(code, lang, themes)`. Unknown languages degrade to plain text. Options: `{ themes?, langs? }` — the default light/dark pair (defaults `vitesse-light`/`vitesse-dark`, matching the design system; later installer wins) and languages to eagerly load (merged as a union).
 

packages/devframe/src/adapters/__tests__/build.test.ts

@@ -62,10 +62,10 @@ describe('adapters/build', () => {
     }
   })
 
-  it('bakes snapshotRpc methods a devframe does not own into the dump', async () => {
+  it('bakes rpc.snapshot methods a devframe does not own into the dump', async () => {
     const outDir = mkdtempSync(join(tmpdir(), 'devframe-build-test-out-'))
     // A dump-less query RPC (as a wire service would register) that the
-    // devframe opts into baking via `snapshotRpc` — string (no-arg), static
+    // devframe opts into baking via `rpc.snapshot` — string (no-arg), static
     // inputs, and an async provider.
     const def = baseDevframe({
       setup: (ctx) => {
@@ -79,11 +79,13 @@ describe('adapters/build', () => {
           handler: (input: { value: string }) => input,
         })
       },
-      snapshotRpc: [
-        'demo:ping',
-        { method: 'demo:echo', inputs: [[{ value: 'a' }]] },
-        { method: 'demo:echo', inputs: async () => [[{ value: 'b' }]] },
-      ],
+      rpc: {
+        snapshot: [
+          'demo:ping',
+          { method: 'demo:echo', inputs: [[{ value: 'a' }]] },
+          { method: 'demo:echo', inputs: async () => [[{ value: 'b' }]] },
+        ],
+      },
     })
     try {
       await createBuild(def, { outDir })
@@ -92,7 +94,7 @@ describe('adapters/build', () => {
       expect(manifest['demo:ping']?.type).toBe('query')
       expect(manifest['demo:ping'].fallback).toBeTruthy()
       // `demo:echo` baked a record per provided tuple (static + provider merged
-      // — the last snapshotRpc entry for a method wins).
+      // — the last rpc.snapshot entry for a method wins).
       expect(manifest['demo:echo']?.type).toBe('query')
       expect(Object.keys(manifest['demo:echo'].records).length).toBeGreaterThanOrEqual(1)
     }
@@ -101,12 +103,12 @@ describe('adapters/build', () => {
     }
   })
 
-  it('warns (DF0072) when snapshotRpc names an unregistered method', async () => {
+  it('warns (DF0072) when rpc.snapshot names an unregistered method', async () => {
     const outDir = mkdtempSync(join(tmpdir(), 'devframe-build-test-out-'))
     try {
       // Does not throw — a missing target is a warning, the build proceeds.
       await expect(
-        createBuild(baseDevframe({ snapshotRpc: ['does:not:exist'] }), { outDir }),
+        createBuild(baseDevframe({ rpc: { snapshot: ['does:not:exist'] } }), { outDir }),
       ).resolves.toBeUndefined()
     }
     finally {

packages/devframe/src/adapters/build.ts

@@ -96,10 +96,10 @@ export async function createBuild(d: DevframeDefinition, options: CreateBuildOpt
   await ctx.services.ready()
   await d.setup(ctx)
 
-  // Bake declared `snapshotRpc` methods (typically a wire service's RPC the
+  // Bake declared `rpc.snapshot` methods (typically a wire service's RPC the
   // devframe doesn't own) into the static dump by attaching a `dump` to their
   // registered definitions — the service itself defines none.
-  applySnapshotRpc(ctx, d.snapshotRpc)
+  applySnapshotRpc(ctx, d.rpc?.snapshot)
 
   await fs.mkdir(resolve(outDir, DEVFRAME_RPC_DUMP_DIRNAME), { recursive: true })
 
@@ -142,7 +142,7 @@ export async function createBuild(d: DevframeDefinition, options: CreateBuildOpt
 }
 
 /**
- * Attach a `dump` to each {@link DevframeDefinition.snapshotRpc} target so the
+ * Attach a `dump` to each {@link DevframeRpcOptions.snapshot} target so the
  * static collector bakes it, even though the (service-owned) definition
  * declares no dump of its own. A bare method id becomes `snapshot: true`
  * (bakes the no-arg call); `{ method, inputs }` bakes one record per resolved

packages/devframe/src/node/diagnostics.ts

@@ -196,7 +196,7 @@ export const diagnostics = defineDiagnostics({
     },
     DF0072: {
       why: (p: { method: string }) =>
-        `\`snapshotRpc\` names "${p.method}", but no RPC function is registered under that id — nothing to bake into the static build.`,
+        `\`rpc.snapshot\` names "${p.method}", but no RPC function is registered under that id — nothing to bake into the static build.`,
       fix: 'Check the method id, and ensure the service/plugin that registers it is installed (e.g. declared in `services`) before the build collects the dump.',
     },
   },

packages/devframe/src/types/devframe.ts

@@ -363,6 +363,14 @@ export interface DevframeDefinition {
    * `client.services.has(pkg)` and degrade.
    */
   services?: DevframeServiceInput[]
+  /** RPC-level configuration for this devframe (see {@link DevframeRpcOptions}). */
+  rpc?: DevframeRpcOptions
+  /** Server-side setup — the primary entrypoint. Runs in every runtime. */
+  setup: (ctx: DevframeNodeContext, info?: DevframeSetupInfo) => void | Promise<void>
+  cli?: DevframeCliOptions
+}
+
+export interface DevframeRpcOptions {
   /**
    * Opt an RPC function into the static-build snapshot **without owning its
    * definition** — the mechanism a devframe uses to bake a wire service's
@@ -377,10 +385,7 @@ export interface DevframeDefinition {
    * executes the target's own handler per tuple; the first tuple's result
    * becomes the fallback so any call variant resolves to a baked value.
    */
-  snapshotRpc?: DevframeSnapshotRpcEntry[]
-  /** Server-side setup — the primary entrypoint. Runs in every runtime. */
-  setup: (ctx: DevframeNodeContext, info?: DevframeSetupInfo) => void | Promise<void>
-  cli?: DevframeCliOptions
+  snapshot?: DevframeSnapshotRpcEntry[]
 }
 
 /** Argument-tuples to bake for a {@link DevframeSnapshotRpcEntry}, or a provider that computes them at build time. */
@@ -389,7 +394,7 @@ export type DevframeSnapshotRpcInputs
     | ((ctx: DevframeNodeContext) => readonly (readonly unknown[])[] | Promise<readonly (readonly unknown[])[]>)
 
 /**
- * One {@link DevframeDefinition.snapshotRpc} entry: a bare method id (bakes
+ * One {@link DevframeRpcOptions.snapshot} entry: a bare method id (bakes
  * the no-argument call) or a method plus the argument-tuples to bake.
  */
 export type DevframeSnapshotRpcEntry

plugins/git/README.md

@@ -55,7 +55,7 @@ All git work runs through the [`@devframes/service-git`](../../services/git)
 wire service, which this devframe declares (`services`) and its SPA calls
 directly over `devframes:service:git:*`. The read functions are `query`
 functions that degrade to an empty, `isRepo: false` result outside a git
-repository; the definition opts them into the static build via `snapshotRpc`
+repository; the definition opts them into the static build via `rpc.snapshot`
 (resolved live over WebSocket in dev, served from a build-time snapshot for
 static deploys).
 

plugins/git/src/index.ts

@@ -1,5 +1,5 @@
 // Types-only: loads service-git's registry augmentation so
-// `ctx.services.get('@devframes/service-git')` is typed in `snapshotRpc`.
+// `ctx.services.get('@devframes/service-git')` is typed in `rpc.snapshot`.
 import type {} from '@devframes/service-git'
 import type { DevframeDefinition, RemoteAssets } from 'devframe'
 import process from 'node:process'
@@ -82,22 +82,24 @@ export function createGitDevframe(options: GitDevframeOptions = {}): DevframeDef
     // their no-arg call; log bakes the 200-commit head; show bakes one
     // (patch-less) record per commit, enumerated at build time via the
     // service's node API.
-    snapshotRpc: [
-      'devframes:service:git:status',
-      'devframes:service:git:branches',
-      'devframes:service:git:diff',
-      { method: 'devframes:service:git:log', inputs: [[{ limit: 200 }]] },
-      {
-        method: 'devframes:service:git:show',
-        inputs: async (ctx) => {
-          const git = ctx.services.get(GIT_SERVICE)
-          if (!git)
-            return []
-          const { commits } = await git.log({ limit: 200 })
-          return commits.map(commit => [{ hash: commit.hash, patch: false }])
+    rpc: {
+      snapshot: [
+        'devframes:service:git:status',
+        'devframes:service:git:branches',
+        'devframes:service:git:diff',
+        { method: 'devframes:service:git:log', inputs: [[{ limit: 200 }]] },
+        {
+          method: 'devframes:service:git:show',
+          inputs: async (ctx) => {
+            const git = ctx.services.get(GIT_SERVICE)
+            if (!git)
+              return []
+            const { commits } = await git.log({ limit: 200 })
+            return commits.map(commit => [{ hash: commit.hash, patch: false }])
+          },
         },
-      },
-    ],
+      ],
+    },
     setup() {},
   })
 }

plugins/git/test/git.test.ts

@@ -69,13 +69,13 @@ describe('@devframes/plugin-git', () => {
   })
 })
 
-describe('@devframes/plugin-git (snapshotRpc build baking)', () => {
-  it('bakes the git service read ops declared in snapshotRpc', async () => {
+describe('@devframes/plugin-git (rpc.snapshot build baking)', () => {
+  it('bakes the git service read ops declared in rpc.snapshot', async () => {
     const repo = createTempRepo()
     try {
       const ctx = await createDashboardContext(repo.dir, 'build')
-      // Mirror `createBuild`: honor the definition's `snapshotRpc` before collecting.
-      applySnapshotRpc(ctx, createGitDevframe().snapshotRpc)
+      // Mirror `createBuild`: honor the definition's `rpc.snapshot` before collecting.
+      applySnapshotRpc(ctx, createGitDevframe().rpc?.snapshot)
       const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx)
 
       const status = dump.manifest['devframes:service:git:status']

tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts

@@ -147,7 +147,7 @@ export interface DevframeDefinition {
     build?: boolean;
   };
   services?: DevframeServiceInput[];
-  snapshotRpc?: DevframeSnapshotRpcEntry[];
+  rpc?: DevframeRpcOptions;
   setup: (_: DevframeNodeContext, _?: DevframeSetupInfo) => void | Promise<void>;
   cli?: DevframeCliOptions;
 }
@@ -229,6 +229,9 @@ export interface DevframeRpcConnectionRequest {
     get: (_: string) => string | null | undefined;
   };
 }
+export interface DevframeRpcOptions {
+  snapshot?: DevframeSnapshotRpcEntry[];
+}
 export interface DevframeRpcServerFunctions {
   'anonymous:devframe:auth': (_: {
     authToken: string;