devframe 0.4.0 → 0.5.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.4.0",
-  "description": "Framework for building generic DevTools",
+  "version": "0.5.0",
+  "description": "Framework for building generic devframes",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
   "homepage": "https://github.com/devframes/devframe#readme",
@@ -30,7 +30,7 @@
     "./helpers/vite": "./dist/helpers/vite.mjs",
     "./node": "./dist/node/index.mjs",
     "./node/auth": "./dist/node/auth.mjs",
-    "./node/internal": "./dist/node/internal.mjs",
+    "./node/hub-internals": "./dist/node/hub-internals.mjs",
     "./recipes/open-helpers": "./dist/recipes/open-helpers.mjs",
     "./rpc": "./dist/rpc/index.mjs",
     "./rpc/client": "./dist/rpc/client.mjs",
@@ -75,8 +75,8 @@
     "mrmime": "^2.0.1",
     "nostics": "^0.2.0",
     "pathe": "^2.0.3",
-    "valibot": "^1.4.0",
-    "ws": "^8.20.0"
+    "valibot": "^1.4.1",
+    "ws": "^8.21.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -90,6 +90,7 @@
     "p-limit": "^7.3.0",
     "perfect-debounce": "^2.1.0",
     "structured-clone-es": "^2.0.0",
+    "tinyglobby": "^0.2.16",
     "tsdown": "^0.22.0",
     "ua-parser-modern": "^0.1.1",
     "whenexpr": "^0.1.2"

package/skills/devframe/SKILL.md

@@ -66,6 +66,83 @@ export default defineDevframe({
 
 See `templates/counter-devframe.ts` for a runnable counter example, `templates/spa-devframe.ts` for an SPA-ready shape, and `templates/vite-client.ts` for the author's client entry.
 
+## Project layout
+
+Once a devframe grows past a handful of RPC functions, split them out — one file per function under `src/rpc/functions/`, with `src/rpc/index.ts` as the barrel. The `functions/` subdirectory leaves room for sibling files like `src/rpc/utils.ts` (helpers, type aliases) as the surface grows. Each function file exports a named const; the barrel collects them into a `const serverFunctions = [...] as const` that feeds the type-safe client registry recipe (`RpcDefinitionsToFunctions<typeof serverFunctions>`).
+
+```ts
+// src/rpc/functions/list-files.ts
+import { defineRpcFunction } from 'devframe'
+import { getMyToolContext } from '../../context'
+
+export const listFiles = defineRpcFunction({
+  name: 'my-tool:list-files',
+  type: 'query',
+  jsonSerializable: true,
+  setup: (ctx) => {
+    const { loaders } = getMyToolContext(ctx)
+    return { handler: () => loaders.list() }
+  },
+})
+```
+
+```ts
+// src/rpc/index.ts
+import { getCwd } from './functions/get-cwd'
+import { listFiles } from './functions/list-files'
+
+export const serverFunctions = [getCwd, listFiles] as const
+
+declare module 'devframe' {
+  interface DevframeRpcServerFunctions
+    extends import('devframe/rpc').RpcDefinitionsToFunctions<typeof serverFunctions> {}
+}
+```
+
+```ts
+// src/devframe.ts
+import { defineDevframe } from 'devframe/types'
+import { setMyToolContext } from './context'
+import { serverFunctions } from './rpc'
+
+export default defineDevframe({
+  id: 'my-tool',
+  setup(ctx) {
+    setMyToolContext(ctx, { loaders: createLoaders() })
+    serverFunctions.forEach(fn => ctx.rpc.register(fn))
+  },
+})
+```
+
+### Sharing setup-time state via `src/context.ts`
+
+When per-file RPCs need access to runtime values that `setup(ctx)` constructs once — streaming channels, shared state handles, watchers, loaders, caches — expose them through a `WeakMap<DevframeNodeContext, T>` in a sibling `src/context.ts`. This mirrors the framework's own `internalContextMap` in `packages/devframe/src/node/hub-internals/context.ts`. The WeakMap keys off the existing `DevframeNodeContext` so contexts are garbage-collected automatically when the host tears down.
+
+```ts
+// src/context.ts
+import type { DevframeNodeContext } from 'devframe/types'
+
+export interface MyToolContext {
+  loaders: { list: () => Promise<string[]> }
+  // …channels, shared state handles, watchers, etc.
+}
+
+const map = new WeakMap<DevframeNodeContext, MyToolContext>()
+
+export function setMyToolContext(ctx: DevframeNodeContext, value: MyToolContext): void {
+  map.set(ctx, value)
+}
+
+export function getMyToolContext(ctx: DevframeNodeContext): MyToolContext {
+  const value = map.get(ctx)
+  if (!value)
+    throw new Error('my-tool context not initialised — call setMyToolContext in devframe.setup')
+  return value
+}
+```
+
+Stateless RPCs and tiny demos can keep the inline shorthand inside `setup(ctx)` — reach for `src/rpc/functions/` and `src/context.ts` once you have more than one or two functions, or any shared setup state.
+
 ## Namespacing
 
 **Always prefix** RPC names, dock IDs, command IDs, shared-state keys, and agent tool IDs with the devframe `id`:
@@ -76,7 +153,7 @@ See `templates/counter-devframe.ts` for a runnable counter example, `templates/s
 'get-modules' // ✗ — may collide with other devframes sharing the host
 ```
 
-## DevToolsNodeContext at a glance
+## DevframeNodeContext at a glance
 
 `setup(ctx)` receives the framework-neutral server-side surface. Each host corresponds to a [docs](https://devfra.me/) page:
 
@@ -340,9 +417,9 @@ const rpc = await connectDevframe()
 const data = await rpc.call('my-inspector:get-stats', { limit: 10 })
 ```
 
-`connectDevframe` auto-detects the backend via `/.devtools/.connection.json`:
+`connectDevframe` auto-detects the backend via `/.devframe/.connection.json`:
 
-- **websocket** (dev mode) — full read/write, requires auth handshake. Listen for token updates on the `vite-devtools-auth` BroadcastChannel.
+- **websocket** (dev mode) — full read/write, requires auth handshake. Listen for token updates on the `devframe-auth` BroadcastChannel.
 - **static** (build / spa output) — read-only, resolves calls from the baked RPC dump.
 
 Use `rpc.sharedState.get(key)` for observable state, `rpc.client.register(defineRpcFunction(...))` to receive server broadcasts, and `rpc.callOptional(...)` when a missing handler should resolve to `undefined` instead of throwing.
@@ -373,7 +450,7 @@ At runtime, static clients look up the argument hash in the dump; misses resolve
 
 | Subcommand | Action |
 |------------|--------|
-| *(default)* | Dev server on port 9999 (or `--port`) — WebSocket RPC, `cli.distDir` served at `/.devtools/` |
+| *(default)* | Dev server on port 9999 (or `--port`) — WebSocket RPC, `cli.distDir` served at `/.devframe/` |
 | `build` | Static snapshot → `./dist-static/` (configurable via `--out-dir`) |
 | `spa` | Deployable SPA → `./dist-spa/` |
 | `mcp` | stdio MCP server (experimental) |
@@ -405,7 +482,7 @@ For "open file in editor" + "reveal in finder", prefer the prebuilt `openHelpers
 
 - Unit-test host classes with fake contexts.
 - Run `templates/counter-devframe.ts` under each adapter for integration coverage.
-- Snapshot the build-static RPC dump (`<outDir>/.devtools/.rpc-dump/index.json`) to catch accidental drift in `static` function outputs.
+- Snapshot the build-static RPC dump (`<outDir>/.devframe/.rpc-dump/index.json`) to catch accidental drift in `static` function outputs.
 
 ## Further reading