devframe 0.6.2 → 0.7.2

package/dist/utils/when.d.mts

@@ -1,333 +1,4 @@
-//#region ../../node_modules/.pnpm/whenexpr@0.1.2/node_modules/whenexpr/dist/index.d.mts
-//#region src/paths.d.ts
-/**
- * Union of valid context paths for `T` — both flat keys (`keyof T`) and
- * `.`/`:`-separated nested paths. Mirrors the runtime `resolve()` lookup:
- * first a flat literal key, then a segmented path.
- *
- * @example
- * type P = ContextPaths<{ editor: { lang: string }, debug: boolean }>
- * // 'editor' | 'debug' | 'editor.lang' | 'editor:lang'
- */
-type ContextPaths<T, P extends string = ''> = { [K in keyof T & string]: `${P}${K}` | (T[K] extends readonly unknown[] ? never : T[K] extends ((...args: never[]) => unknown) ? never : T[K] extends object ? ContextPaths<T[K], `${P}${K}.`> | ContextPaths<T[K], `${P}${K}:`> : never) }[keyof T & string]; //#endregion
-//#region src/types.d.ts
-/**
- * Branded error type surfaced at the call site of `evaluateWhen` when the
- * expression string fails static validation. The embedded message appears in
- * the TS error tooltip because `WhenExpressionError<M>` is not assignable from a
- * plain string literal.
- */
-type WhenExpressionError<M extends string> = string & {
-  readonly __whenExpressionError: M;
-};
-type Ws = ' ' | '\t' | '\n' | '\r';
-type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
-type Lower = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
-type Upper = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
-type IdentStart = Lower | Upper | '_' | '$';
-type IdentCont = IdentStart | Digit | '.' | ':';
-type Op = '===' | '!==' | '==' | '!=' | '<=' | '>=' | '&&' | '||' | '<' | '>' | '+' | '-' | '*' | '/' | '%' | '!';
-type Tok = {
-  k: 'num';
-  v: string;
-} | {
-  k: 'str';
-  v: string;
-} | {
-  k: 'id';
-  v: string;
-} | {
-  k: 'bool';
-  v: 'true' | 'false';
-} | {
-  k: 'op';
-  v: Op;
-} | {
-  k: 'lp';
-} | {
-  k: 'rp';
-} | {
-  k: 'eof';
-};
-interface TokErr {
-  __err: string;
-}
-type Tokenize<S extends string, Acc extends Tok[] = []> = S extends '' ? [...Acc, {
-  k: 'eof';
-}] : S extends `${Ws}${infer R}` ? Tokenize<R, Acc> : S extends `===${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '===';
-}]> : S extends `!==${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '!==';
-}]> : S extends `==${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '==';
-}]> : S extends `!=${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '!=';
-}]> : S extends `<=${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '<=';
-}]> : S extends `>=${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '>=';
-}]> : S extends `&&${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '&&';
-}]> : S extends `||${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '||';
-}]> : S extends `<${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '<';
-}]> : S extends `>${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '>';
-}]> : S extends `+${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '+';
-}]> : S extends `-${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '-';
-}]> : S extends `*${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '*';
-}]> : S extends `/${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '/';
-}]> : S extends `%${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '%';
-}]> : S extends `!${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'op';
-  v: '!';
-}]> : S extends `(${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'lp';
-}]> : S extends `)${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'rp';
-}]> : S extends `"${infer R}` ? ConsumeStr<R, '', '"', Acc> : S extends `'${infer R}` ? ConsumeStr<R, '', '\'', Acc> : S extends `${infer C extends Digit}${infer R}` ? ConsumeNum<R, C, Acc> : S extends `${infer C extends IdentStart}${infer R}` ? ConsumeIdent<R, C, Acc> : {
-  __err: `Unexpected character in "${S}"`;
-};
-type ConsumeNum<S extends string, N extends string, Acc extends Tok[]> = S extends `${infer C extends Digit}${infer R}` ? ConsumeNum<R, `${N}${C}`, Acc> : S extends `.${infer C extends Digit}${infer R}` ? ConsumeNumFrac<R, `${N}.${C}`, Acc> : Tokenize<S, [...Acc, {
-  k: 'num';
-  v: N;
-}]>;
-type ConsumeNumFrac<S extends string, N extends string, Acc extends Tok[]> = S extends `${infer C extends Digit}${infer R}` ? ConsumeNumFrac<R, `${N}${C}`, Acc> : Tokenize<S, [...Acc, {
-  k: 'num';
-  v: N;
-}]>;
-type ConsumeIdent<S extends string, N extends string, Acc extends Tok[]> = S extends `${infer C extends IdentCont}${infer R}` ? ConsumeIdent<R, `${N}${C}`, Acc> : Tokenize<S, [...Acc, ClassifyIdent<N>]>;
-type ClassifyIdent<N extends string> = N extends 'true' ? {
-  k: 'bool';
-  v: 'true';
-} : N extends 'false' ? {
-  k: 'bool';
-  v: 'false';
-} : {
-  k: 'id';
-  v: N;
-};
-type ConsumeStr<S extends string, V extends string, Q extends '"' | '\'', Acc extends Tok[]> = S extends `${Q}${infer R}` ? Tokenize<R, [...Acc, {
-  k: 'str';
-  v: V;
-}]> : S extends `\\${infer C}${infer R}` ? ConsumeStr<R, `${V}${C}`, Q, Acc> : S extends `${infer C}${infer R}` ? ConsumeStr<R, `${V}${C}`, Q, Acc> : {
-  __err: 'Unterminated string literal';
-};
-type BinOp = '||' | '&&' | '==' | '!=' | '===' | '!==' | '<' | '>' | '<=' | '>=' | '+' | '-' | '*' | '/' | '%';
-type UnOp = '!' | '-' | '+';
-interface LitNode {
-  t: 'lit';
-  v: string;
-}
-interface KeyNode {
-  t: 'key';
-  v: string;
-}
-interface UnNode {
-  t: 'un';
-  op: UnOp;
-  x: Ast;
-}
-interface BinNode {
-  t: 'bin';
-  op: BinOp;
-  l: Ast;
-  r: Ast;
-}
-type Ast = LitNode | KeyNode | UnNode | BinNode;
-type Parse<Toks extends Tok[]> = ParseOr<Toks>;
-type ParseOr<T extends Tok[]> = OrTail<ParseAnd<T>>;
-type OrTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
-  k: 'op';
-  v: '||';
-}, ...infer After extends Tok[]] ? ParseAnd<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? OrTail<[{
-  t: 'bin';
-  op: '||';
-  l: L;
-  r: Rh;
-}, Next]> : 'err' : R : R;
-type ParseAnd<T extends Tok[]> = AndTail<ParseEq<T>>;
-type AndTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
-  k: 'op';
-  v: '&&';
-}, ...infer After extends Tok[]] ? ParseEq<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? AndTail<[{
-  t: 'bin';
-  op: '&&';
-  l: L;
-  r: Rh;
-}, Next]> : 'err' : R : R;
-type ParseEq<T extends Tok[]> = EqTail<ParseRel<T>>;
-type EqTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
-  k: 'op';
-  v: infer O extends '==' | '!=';
-}, ...infer After extends Tok[]] ? ParseValueRhs<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? EqTail<[{
-  t: 'bin';
-  op: O;
-  l: L;
-  r: Rh;
-}, Next]> : 'err' : Rest extends [{
-  k: 'op';
-  v: infer O extends '===' | '!==';
-}, ...infer After extends Tok[]] ? ParseRel<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? EqTail<[{
-  t: 'bin';
-  op: O;
-  l: L;
-  r: Rh;
-}, Next]> : 'err' : R : R;
-type ParseValueRhs<T extends Tok[]> = T extends [{
-  k: 'id';
-  v: infer V extends string;
-}, ...infer R extends Tok[]] ? [{
-  t: 'lit';
-  v: V;
-}, R] : T extends [{
-  k: 'str';
-  v: infer V extends string;
-}, ...infer R extends Tok[]] ? [{
-  t: 'lit';
-  v: V;
-}, R] : T extends [{
-  k: 'num';
-  v: infer V extends string;
-}, ...infer R extends Tok[]] ? [{
-  t: 'lit';
-  v: V;
-}, R] : T extends [{
-  k: 'bool';
-  v: infer V extends string;
-}, ...infer R extends Tok[]] ? [{
-  t: 'lit';
-  v: V;
-}, R] : 'err';
-type ParseRel<T extends Tok[]> = RelTail<ParseAdd<T>>;
-type RelTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
-  k: 'op';
-  v: infer O extends '<=' | '>=' | '<' | '>';
-}, ...infer After extends Tok[]] ? ParseAdd<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? RelTail<[{
-  t: 'bin';
-  op: O;
-  l: L;
-  r: Rh;
-}, Next]> : 'err' : R : R;
-type ParseAdd<T extends Tok[]> = AddTail<ParseMul<T>>;
-type AddTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
-  k: 'op';
-  v: infer O extends '+' | '-';
-}, ...infer After extends Tok[]] ? ParseMul<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? AddTail<[{
-  t: 'bin';
-  op: O;
-  l: L;
-  r: Rh;
-}, Next]> : 'err' : R : R;
-type ParseMul<T extends Tok[]> = MulTail<ParseUnary<T>>;
-type MulTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
-  k: 'op';
-  v: infer O extends '*' | '/' | '%';
-}, ...infer After extends Tok[]] ? ParseUnary<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? MulTail<[{
-  t: 'bin';
-  op: O;
-  l: L;
-  r: Rh;
-}, Next]> : 'err' : R : R;
-type ParseUnary<T extends Tok[]> = T extends [{
-  k: 'op';
-  v: infer O extends UnOp;
-}, ...infer Rest extends Tok[]] ? ParseUnary<Rest> extends [infer X extends Ast, infer Next extends Tok[]] ? [{
-  t: 'un';
-  op: O;
-  x: X;
-}, Next] : 'err' : ParsePrimary<T>;
-type ParsePrimary<T extends Tok[]> = T extends [{
-  k: 'num';
-  v: infer V extends string;
-}, ...infer R extends Tok[]] ? [{
-  t: 'lit';
-  v: V;
-}, R] : T extends [{
-  k: 'str';
-  v: infer V extends string;
-}, ...infer R extends Tok[]] ? [{
-  t: 'lit';
-  v: V;
-}, R] : T extends [{
-  k: 'bool';
-  v: infer V extends string;
-}, ...infer R extends Tok[]] ? [{
-  t: 'lit';
-  v: V;
-}, R] : T extends [{
-  k: 'id';
-  v: infer V extends string;
-}, ...infer R extends Tok[]] ? [{
-  t: 'key';
-  v: V;
-}, R] : T extends [{
-  k: 'lp';
-}, ...infer Rest extends Tok[]] ? ParseOr<Rest> extends [infer N extends Ast, infer After extends Tok[]] ? After extends [{
-  k: 'rp';
-}, ...infer Next extends Tok[]] ? [N, Next] : 'err' : 'err' : 'err';
-type CollectKeys<N> = N extends KeyNode ? N['v'] : N extends UnNode ? CollectKeys<N['x']> : N extends {
-  t: 'bin';
-  op: '==' | '!=';
-  l: infer L;
-} ? CollectKeys<L> : N extends BinNode ? CollectKeys<N['l']> | CollectKeys<N['r']> : never;
-/**
- * Validate a when-clause expression string `S` against context type `T`.
- * Returns `S` on success, or a `WhenExpressionError<Msg>` branded error string
- * that surfaces at the call site with a human-readable message.
- *
- * - Dynamic `string` expressions skip all validation.
- * - Wide context types (`object`, `any`, `unknown`, `Record<string, unknown>`,
- *   empty `{}`, etc.) still run **syntax** checking but skip **key** checking.
- * - Specific context types run full validation (syntax + keys).
- */
-type ValidateExpression<S extends string, T> = string extends S ? S : Tokenize<S> extends infer Toks ? Toks extends TokErr ? WhenExpressionError<`Syntax error: ${Toks['__err']}`> : Toks extends Tok[] ? Parse<Toks> extends [infer N extends Ast, [{
-  k: 'eof';
-}]] ? [keyof T] extends [never] ? S : string extends keyof T ? S : Exclude<CollectKeys<N>, ContextPaths<T>> extends infer Missing ? [Missing] extends [never] ? S : WhenExpressionError<`Unknown context key: "${Extract<Missing, string>}"`> : never : WhenExpressionError<'Syntax error in expression'> : never : never;
-/**
- * A when-clause expression string validated against context type `T`.
- * Use inside your own typed define helpers to have TypeScript check `when`
- * fields at the call site.
- *
- * @example
- * interface AppCtx { mode: 'dev' | 'prod', debug: boolean }
- *
- * function defineCommand<const W extends string>(cmd: {
- *   name: string
- *   title: string
- *   when?: WhenExpression<AppCtx, W>
- * }): typeof cmd {
- *   return cmd
- * }
- *
- * defineCommand({ name: 'x', title: 'X', when: 'debug && mode == dev' })
- * defineCommand({ name: 'x', title: 'X', when: 'typo' })
- * //                                            ^^^^^ type error
- */
-type WhenExpression$1<T, S extends string> = S & ValidateExpression<S, T>; //#endregion
-//#region src/index.d.ts
-//#endregion
+import { WhenExpression as WhenExpression$1 } from "whenexpr";
 //#region src/utils/when.d.ts
 /**
  * Context object for evaluating `when` expressions.

package/dist/{ws-client-nBjpin71.d.mts → ws-client-DSXiI2h7.d.mts}

@@ -1,6 +1,5 @@
-import { v as RpcFunctionDefinitionAny } from "./types-oEqKqUC9.mjs";
+import { v as RpcFunctionDefinitionAny } from "./types-CrzNxXKq.mjs";
 import { ChannelOptions } from "birpc";
-
 //#region src/rpc/transports/ws-client.d.ts
 interface WsRpcChannelOptions {
   url: string;

package/dist/{ws-server-BUgJpdX4.d.mts → ws-server-CceOy6He.d.mts}

@@ -1,10 +1,9 @@
-import { v as RpcFunctionDefinitionAny } from "./types-oEqKqUC9.mjs";
+import { v as RpcFunctionDefinitionAny } from "./types-CrzNxXKq.mjs";
 import { BirpcGroup, ChannelOptions } from "birpc";
 import { Peer } from "crossws";
 import { NodeAdapter } from "crossws/adapters/node";
 import { Server } from "node:http";
 import { Server as Server$1, ServerOptions } from "node:https";
-
 //#region src/rpc/transports/ws-server.d.ts
 interface DevframeNodeRpcSessionMeta {
   id: number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.6.2",
+  "version": "0.7.2",
   "description": "Framework for building generic devframes",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -21,6 +21,7 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./adapters/build": "./dist/adapters/build.mjs",
+    "./adapters/cac": "./dist/adapters/cac.mjs",
     "./adapters/cli": "./dist/adapters/cli.mjs",
     "./adapters/dev": "./dist/adapters/dev.mjs",
     "./adapters/embedded": "./dist/adapters/embedded.mjs",
@@ -62,18 +63,21 @@
     "skills"
   ],
   "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": "^1.7.1",
     "birpc": "^4.0.0",
-    "cac": "^7.0.0",
-    "crossws": "^0.4.9",
+    "crossws": "^0.4.10",
     "destr": "^2.0.5",
     "h3": "2.0.1-rc.22",
     "mrmime": "^2.0.1",
@@ -84,6 +88,7 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "cac": "^7.0.0",
     "get-port-please": "^3.2.0",
     "immer": "^11.1.11",
     "launch-editor": "^2.14.1",
@@ -95,10 +100,10 @@
     "perfect-debounce": "^2.1.0",
     "structured-clone-es": "^2.0.0",
     "tinyglobby": "^0.2.17",
-    "tsdown": "^0.22.3",
+    "tsdown": "^0.22.7",
     "ua-parser-modern": "^0.1.1",
     "whenexpr": "^0.1.2",
-    "ws": "^8.21.0"
+    "ws": "^8.21.1"
   },
   "inlinedDependencies": {
     "bundle-name": "4.1.0",

package/skills/devframe/SKILL.md

@@ -11,7 +11,7 @@ description: >
   terminals, palette, etc.), the devframe can be mounted into a
   host that provides them — Vite DevTools is one supported target,
   reached via the `vite` adapter. Triggers on `devframe` imports,
-  `defineDevframe`, `createCli`, `createMcpServer`,
+  `defineDevframe`, `createCac`, `createMcpServer`,
   `connectDevframe`, and on migrations of existing inspectors
   (eslint-config-inspector, unocss-inspector,
   node-modules-inspector-style tools) to devframe.
@@ -31,7 +31,7 @@ All adapter factories share the shape `createXxx(devframeDef, options?)`.
 
 | Author goal | Factory | Entry |
 |-------------|---------|-------|
-| Standalone CLI for local use | `createCli(def, options?)` | `devframe/adapters/cli` |
+| Standalone CLI for local use | `createCac(def, options?)` | `devframe/adapters/cac` |
 | Run the dev server programmatically (any CLI framework) | `createDevServer(def, options?)` | `devframe/adapters/dev` |
 | Self-contained static deploy with baked data | `createBuild(def, options?)` | `devframe/adapters/build` |
 | Mount into a host (Vite DevTools or any compatible host) | `createPluginFromDevframe(def, options?)` | `@vitejs/devtools-kit/node` |
@@ -530,7 +530,7 @@ At runtime, static clients look up the argument hash in the dump; misses resolve
 
 ## CLI adapter subcommands
 
-`createCli(devframe).parse()` gives the tool four subcommands out of the box:
+`createCac(devframe).parse()` gives the tool four subcommands out of the box:
 
 | Subcommand | Action |
 |------------|--------|
@@ -539,7 +539,7 @@ At runtime, static clients look up the argument hash in the dump; misses resolve
 | `spa` | Deployable SPA → `./dist-spa/` |
 | `mcp` | stdio MCP server (experimental) |
 
-**Bring your own CLI framework?** `createCli` is just a cac wrapper around three peer factories — `createDevServer` (`devframe/adapters/dev`), `createBuild` (`devframe/adapters/build`), and `createMcpServer` (`devframe/adapters/mcp`). Use them directly with commander/yargs/oclif when `createCli`'s baked-in command structure doesn't fit. `createDevServer` returns a `StartedServer` handle (`origin`, `port`, `app`, `wss`, `close()`) so you can wire SIGINT / hot-reload teardown into the surrounding program. `parseCliFlags(schema, raw)` and `defineCliFlags(...)` (both from `devframe/adapters/cli`) validate an arbitrary flag bag against a `CliFlagsSchema` — typed flags aren't tied to cac.
+**Bring your own CLI framework?** `createCac` (`devframe/adapters/cac`) is just a cac wrapper around three peer factories — `createDevServer` (`devframe/adapters/dev`), `createBuild` (`devframe/adapters/build`), and `createMcpServer` (`devframe/adapters/mcp`). Use them directly with commander/yargs/oclif when `createCac`'s baked-in command structure doesn't fit. `cac` is an optional peer dependency pulled in only through `devframe/adapters/cac`, so bring-your-own-CLI tools run without installing it. (The legacy `devframe/adapters/cli` entry / `createCli` remains as a deprecated alias.) `createDevServer` returns a `StartedServer` handle (`origin`, `port`, `app`, `wss`, `close()`) so you can wire SIGINT / hot-reload teardown into the surrounding program. `parseCliFlags(schema, raw)` and `defineCliFlags(...)` (both from `devframe/adapters/cac`) validate an arbitrary flag bag against a `CliFlagsSchema` — the helpers are framework-agnostic.
 
 ## Bundled utilities