refactor(rpc): rename schema builder to simple-schema; use it in plugins; docs use valibot

- Rename devframe/utils/schema -> devframe/utils/simple-schema and rename
  the exported type DevframeSchema -> SimpleSchema. The builder is now
  explicitly documented as discouraged for app code (a minimal, best-effort
  validator for devframe's own first-party packages).
- Extend the builder with record/union/literal and make object() infer
  optional keys for optional() fields (matching valibot/zod).
- Migrate the built-in plugins (assets, og, terminals) off valibot onto
  devframe/utils/simple-schema, and drop valibot from their dependencies.
- Docs: never reference the built-in builder; all schema examples use
  valibot with an explicit install hint (npm i valibot).

BREAKING CHANGE: devframe/utils/schema is renamed to
devframe/utils/simple-schema and its exported type DevframeSchema is
renamed to SimpleSchema.

Author: antfubot

alias.ts

@@ -26,7 +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/schema': r('devframe/src/utils/schema.ts'),
+  'devframe/utils/simple-schema': r('devframe/src/utils/simple-schema.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'),

docs/guide/devframe-definition.md

@@ -10,7 +10,7 @@ Every Devframe tool starts with a single `defineDevframe` call. The returned `De
 
 ```ts twoslash
 import { defineDevframe, defineRpcFunction } from 'devframe'
-import * as v from 'valibot'
+import * as v from 'valibot' // npm i valibot
 
 export default defineDevframe({
   id: 'my-devframe',

docs/guide/rpc.md

@@ -22,13 +22,13 @@ sequenceDiagram
 
 ```ts
 import { defineRpcFunction } from 'devframe'
-import { s } from 'devframe/utils/schema' // or bring your own: valibot / zod / arktype
+import * as v from 'valibot' // npm i valibot (or use zod / arktype)
 
 export const getModules = defineRpcFunction({
   name: 'get-modules', // bare — the scope namespaces it to `my-devframe:get-modules`
   type: 'query',
-  args: [s.object({ limit: s.number() })],
-  returns: s.array(s.object({ id: s.string(), size: s.number() })),
+  args: [v.object({ limit: v.number() })],
+  returns: v.array(v.object({ id: v.string(), size: v.number() })),
   setup: ctx => ({
     handler: async ({ limit }) => {
       // `ctx` is the full DevframeNodeContext.
@@ -77,14 +77,14 @@ Use `static` for data collected once during `setup` and shipped to read-only sta
 
 Handlers accept any serializable arguments. Declare `args` schemas — any [Standard Schema](https://standardschema.dev/) validator (valibot, zod, arktype, …) — and each argument is validated at the boundary before the handler runs; a mismatch is rejected with a coded diagnostic. Validation guards the payload without rewriting it, so extra object fields the schema doesn't mention still reach the handler.
 
-Devframe forces no validator on you. Bring the one you already use, or reach for the built-in zero-dependency builder at `devframe/utils/schema` (imported as `s` below):
+Devframe forces no validator on you: bring whichever [Standard Schema](https://standardschema.dev/) validator you prefer (valibot, zod, arktype) and install it yourself. The examples here use valibot (`npm i valibot`):
 
 ```ts
 defineRpcFunction({
   name: 'get-file',
   type: 'query',
-  args: [s.object({ path: s.string(), includeSource: s.optional(s.boolean()) })],
-  returns: s.object({ path: s.string(), source: s.optional(s.string()) }),
+  args: [v.object({ path: v.string(), includeSource: v.optional(v.boolean()) })],
+  returns: v.object({ path: v.string(), source: v.optional(v.string()) }),
   setup: () => ({
     handler: async ({ path, includeSource }) => ({
       path,
@@ -94,7 +94,7 @@ defineRpcFunction({
 })
 ```
 
-Prefer a single object argument (`args: [s.object({ ... })]`) over positional args — property names are self-describing and agents/IDEs work best with object shapes.
+Prefer a single object argument (`args: [v.object({ ... })]`) over positional args — property names are self-describing and agents/IDEs work best with object shapes.
 
 > [!WARNING]
 > Declared `args`/`returns` schemas are enforced at runtime — a call whose arguments, or a handler whose return value, fail the schema is rejected with `DF0043` / `DF0044`. Make sure each schema matches what the function actually accepts and returns; a schema stricter than reality will now reject calls that previously ran.
@@ -247,7 +247,7 @@ defineRpcFunction({
   name: 'build-meta',
   type: 'static',
   args: [],
-  returns: s.object({ version: s.string(), builtAt: s.number() }),
+  returns: v.object({ version: v.string(), builtAt: v.number() }),
   setup: () => ({
     handler: async () => ({ version: '1.0.0', builtAt: Date.now() }),
   }),
@@ -311,8 +311,8 @@ defineRpcFunction({
   name: 'get-modules',
   type: 'query',
   jsonSerializable: true,
-  args: [s.object({ limit: s.number() })],
-  returns: s.array(s.object({ id: s.string(), size: s.number() })),
+  args: [v.object({ limit: v.number() })],
+  returns: v.array(v.object({ id: v.string(), size: v.number() })),
   agent: {
     description: 'List the N largest modules in the current build. Safe to call freely.',
     title: 'List modules',

docs/guide/standalone-cli.md

@@ -168,13 +168,13 @@ const payload = await my.rpc.call('get-payload')
 
 ## Typed CLI flags
 
-For flags that are specific to your tool, declare them with any [Standard Schema](https://standardschema.dev/) validator (valibot below, or zod / arktype / devframe's built-in `s`) so they're validated at parse time and typed at the call site:
+For flags that are specific to your tool, declare them with any [Standard Schema](https://standardschema.dev/) validator (valibot below — `npm i valibot` — or zod / arktype) so they're validated at parse time and typed at the call site:
 
 ```ts
 import type { InferCliFlags } from 'devframe/adapters/cac'
 import { defineDevframe } from 'devframe'
 import { defineCliFlags } from 'devframe/adapters/cac'
-import * as v from 'valibot'
+import * as v from 'valibot' // npm i valibot
 
 const appFlags = defineCliFlags({
   depth: v.pipe(v.number(), v.integer()),

docs/guide/streaming.md

@@ -29,7 +29,7 @@ Create the channel once in `setup`. Channels are framework-neutral, so the same
 
 ```ts
 import { defineDevframe, defineRpcFunction } from 'devframe'
-import * as v from 'valibot'
+import * as v from 'valibot' // npm i valibot
 
 export default defineDevframe({
   id: 'my-devframe',

docs/helpers/common-rpc-functions.md

@@ -28,7 +28,7 @@ defineDevframe({
 | `KNOWN_EDITORS` | — | `readonly string[]` | — | The editor commands `openInEditor`'s `editor` argument accepts (`code`, `vim`, `subl`, `idea`, …). |
 | `KnownEditor` | — | type | — | Union of `KNOWN_EDITORS`. |
 
-Both functions are `action`-type RPCs returning `void` and declare their arguments with devframe's built-in zero-dependency `s` builder from `devframe/utils/schema` — `openInEditor`'s `editor` argument is `s.optional(s.picklist(KNOWN_EDITORS))`, so a value outside `KNOWN_EDITORS` fails validation rather than reaching the underlying `launch-editor` process spawn. Both handlers dynamically `import()` their underlying `devframe/utils/*` implementation, so the `launch-editor` and `open` dependencies only load when the recipe actually runs.
+Both functions are `action`-type RPCs returning `void`, and their arguments are schema-validated — `openInEditor`'s `editor` argument is restricted to `KNOWN_EDITORS`, so a value outside that list fails validation rather than reaching the underlying `launch-editor` process spawn. Both handlers dynamically `import()` their underlying `devframe/utils/*` implementation, so the `launch-editor` and `open` dependencies only load when the recipe actually runs.
 
 The `devframe/recipes/open-helpers` entry (`openHelpers`) remains as a deprecated alias for this module — new code should import `commonRpcFunctions` from `devframe/recipes/common-rpc-functions`.
 

packages/devframe/package.json

@@ -50,7 +50,7 @@
     "./utils/nanoid": "./dist/utils/nanoid.mjs",
     "./utils/open": "./dist/utils/open.mjs",
     "./utils/promise": "./dist/utils/promise.mjs",
-    "./utils/schema": "./dist/utils/schema.mjs",
+    "./utils/simple-schema": "./dist/utils/simple-schema.mjs",
     "./utils/scope": "./dist/utils/scope.mjs",
     "./utils/serve-static": "./dist/utils/serve-static.mjs",
     "./utils/shared-state": "./dist/utils/shared-state.mjs",

packages/devframe/src/adapters/mcp/__tests__/to-json-schema.test.ts

@@ -1,4 +1,4 @@
-import { s } from 'devframe/utils/schema'
+import { s } from 'devframe/utils/simple-schema'
 import { describe, expect, it } from 'vitest'
 import { argsToJsonSchema, returnToJsonSchema } from '../to-json-schema'
 

packages/devframe/src/recipes/common-rpc-functions.ts

@@ -1,4 +1,4 @@
-import { s } from 'devframe/utils/schema'
+import { s } from 'devframe/utils/simple-schema'
 import { defineRpcFunction } from '../rpc/define'
 
 /**

packages/devframe/src/recipes/interactive-auth.ts

@@ -1,7 +1,7 @@
 import type { DevframeNodeContext, DevframeNodeRpcSession } from 'devframe/types'
 import type { DevframeAuthHandler } from '../node/auth'
 import { colors } from 'devframe/utils/colors'
-import { s } from 'devframe/utils/schema'
+import { s } from 'devframe/utils/simple-schema'
 import { DEVFRAME_AUTH_TOKEN_QUERY_PARAM, isAnonymousRpcMethod } from '../constants'
 import { buildOtpAuthUrl, exchangeTempAuthCode, getTempAuthCode, verifyAuthToken } from '../node/auth/state'
 import { getInternalContext } from '../node/hub-internals/context'