refactor(devframe)!: make cac an optional peer dependency of the cli adapter

cac is now an optional peer dependency, pulled in only through the
devframe/adapters/cli entry. Tools that assemble their own command-line
shell from the createDevServer / createBuild / createMcpServer factories
run without installing cac.

A new cac-free devframe/adapters/flags entry exposes the typed-flag
helpers (defineCliFlags / parseCliFlags) so bring-your-own-CLI tools get
flag validation without depending on cac. The helpers stay re-exported
from adapters/cli for back-compat.

Plugins and examples that ship a createCli-backed binary now declare cac
directly.

PR created with the help of an agent.

Author: antfubot

docs/adapters/cli.md

@@ -6,6 +6,14 @@ outline: deep
 
 The CLI adapter wraps a `DevframeDefinition` in a `cac`-powered command-line interface. From one entry it spins up an `h3` dev server with WebSocket RPC, builds static snapshots, builds SPA bundles, or starts an MCP server.
 
+`cac` is an optional peer dependency, pulled in only through this adapter — install it alongside `devframe` to opt into `createCli`:
+
+```sh
+npm install devframe cac
+```
+
+Tools that assemble their own command-line shell from the [lower-level factories](#use-your-own-cli-framework) never import this adapter, so they run without `cac`.
+
 ```ts
 import { defineDevframe } from 'devframe'
 import { createCli } from 'devframe/adapters/cli'
@@ -105,6 +113,6 @@ To integrate devframe into an existing commander / yargs program — or to expos
 | [`createDevServer(def, opts?)`](./dev) | `devframe/adapters/dev` | h3 + WebSocket RPC + SPA mount |
 | [`createBuild(def, opts?)`](./build) | `devframe/adapters/build` | Static deploy |
 | [`createMcpServer(def, opts?)`](./mcp) | `devframe/adapters/mcp` | stdio MCP server |
-| `parseCliFlags(schema, raw)` | `devframe/adapters/cli` | Validate a flag bag against a `CliFlagsSchema` |
+| `parseCliFlags(schema, raw)` | `devframe/adapters/flags` | Validate a flag bag against a `CliFlagsSchema` (no `cac` required) |
 
 See the [Standalone CLI guide](/guide/standalone-cli#use-your-own-cli-framework) for a worked commander example.

docs/adapters/index.md

@@ -6,7 +6,7 @@ outline: deep
 
 An adapter takes a `DevframeDefinition` and deploys it into a specific runtime — a standalone CLI, a Vite plugin, a static snapshot, an embedded host, or an MCP server. Each adapter ships at its own entry point (`devframe/adapters/<name>`); the bundler pulls in only the ones you use.
 
-Every adapter factory has the shape `createXxx(devframeDef, options?)`.
+Every adapter factory has the shape `createXxx(devframeDef, options?)`. Some adapters draw on an optional peer dependency, installed only when you opt into that adapter: `cli` pulls in [`cac`](https://github.com/cacjs/cac), and `mcp` pulls in [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk).
 
 ## Comparison
 

docs/guide/standalone-cli.md

@@ -342,7 +342,7 @@ await program.parseAsync()
 
 `createDevServer` returns the underlying `StartedServer` handle (`origin`, `port`, `app`, `ws`, `rpcGroup`, `connectionMeta()`, `close()`) so the surrounding program can drive graceful shutdown — SIGINT, hot reload, integration tests.
 
-For typed flag schemas, `parseCliFlags(schema, rawBag)` (from `devframe/adapters/cli`) validates a commander/yargs flag bag against a `CliFlagsSchema` (the same `defineCliFlags(...)` value you'd put on `cli.flags`). Typed-schema validation works with any CLI framework.
+For typed flag schemas, `parseCliFlags(schema, rawBag)` (from `devframe/adapters/flags`) validates a commander/yargs flag bag against a `CliFlagsSchema` (the same `defineCliFlags(...)` value you'd put on `cli.flags`). This entry carries no `cac` dependency, so typed-schema validation works with any CLI framework.
 
 ## Why this shape
 

examples/files-inspector/package.json

@@ -18,6 +18,7 @@
   },
   "dependencies": {
     "@antfu/design": "catalog:frontend",
+    "cac": "catalog:deps",
     "colorjs.io": "catalog:frontend",
     "devframe": "workspace:*",
     "preact": "catalog:frontend",

examples/next-runtime-snapshot/package.json

@@ -19,6 +19,7 @@
   },
   "dependencies": {
     "@antfu/design": "catalog:frontend",
+    "cac": "catalog:deps",
     "colorjs.io": "catalog:frontend",
     "devframe": "workspace:*",
     "next": "catalog:frontend",

examples/streaming-chat/package.json

@@ -18,6 +18,7 @@
   },
   "dependencies": {
     "@antfu/design": "catalog:frontend",
+    "cac": "catalog:deps",
     "colorjs.io": "catalog:frontend",
     "devframe": "workspace:*",
     "preact": "catalog:frontend"

packages/devframe/package.json

@@ -24,6 +24,7 @@
     "./adapters/cli": "./dist/adapters/cli.mjs",
     "./adapters/dev": "./dist/adapters/dev.mjs",
     "./adapters/embedded": "./dist/adapters/embedded.mjs",
+    "./adapters/flags": "./dist/adapters/flags.mjs",
     "./adapters/mcp": "./dist/adapters/mcp.mjs",
     "./client": "./dist/client/index.mjs",
     "./constants": "./dist/constants.mjs",
@@ -68,17 +69,20 @@
     "prepack": "pnpm build && mkdir -p ./skills && cp -r ../../skills/devframe ./skills/devframe"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "cac": "^7.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
       "optional": true
+    },
+    "cac": {
+      "optional": true
     }
   },
   "dependencies": {
     "@valibot/to-json-schema": "catalog:deps",
     "birpc": "catalog:deps",
-    "cac": "catalog:deps",
     "crossws": "catalog:deps",
     "destr": "catalog:deps",
     "h3": "catalog:deps",
@@ -90,6 +94,7 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "catalog:deps",
+    "cac": "catalog:deps",
     "get-port-please": "catalog:deps",
     "immer": "catalog:deps",
     "launch-editor": "catalog:deps",

packages/devframe/src/adapters/cli.ts

@@ -1,3 +1,12 @@
+// The `cac` command-line framework is an optional peer dependency: it's
+// only pulled in through this adapter entry, so tools that assemble their
+// own CLI from the lower-level `createDevServer` / `createBuild` /
+// `createMcpServer` factories never need it installed. Install `cac`
+// alongside `devframe` to opt into `createCli`; importing this entry
+// without it throws at load time with the usual Node module-not-found
+// error. The cac-independent flag helpers are re-exported below for
+// convenience, and also ship from the cac-free `devframe/adapters/flags`
+// entry for tools that only want typed-flag validation.
 import type { CAC } from 'cac'
 import type { H3 } from 'h3'
 import type { DevframeDefinition } from '../types/devframe'

packages/devframe/tsdown.config.ts

@@ -89,6 +89,7 @@ const serverEntries = {
   'utils/open': 'src/utils/open.ts',
   'utils/serve-static': 'src/utils/serve-static.ts',
   'adapters/cli': 'src/adapters/cli.ts',
+  'adapters/flags': 'src/adapters/flags.ts',
   'adapters/dev': 'src/adapters/dev.ts',
   'adapters/build': 'src/adapters/build.ts',
   'adapters/embedded': 'src/adapters/embedded.ts',

plugins/a11y/package.json

@@ -63,6 +63,7 @@
   },
   "dependencies": {
     "axe-core": "catalog:frontend",
+    "cac": "catalog:deps",
     "solid-js": "catalog:frontend"
   },
   "devDependencies": {