devframe 0.4.1 → 0.5.1

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
 

package/dist/node/internal.mjs

@@ -1,49 +0,0 @@
-import { t as createStorage } from "../storage-CZVTPKsw.mjs";
-import { n as revokeActiveConnectionsForToken, r as revokeAuthToken, t as humanId } from "../human-id-Dq-qgtES.mjs";
-import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-CUFqO4kJ.mjs";
-import { join } from "pathe";
-//#region src/node/internal/context.ts
-const internalContextMap = /* @__PURE__ */ new WeakMap();
-function getInternalContext(context) {
-	if (!internalContextMap.has(context)) {
-		const storage = createStorage({
-			filepath: join(context.host.getStorageDir("global"), "auth.json"),
-			initialValue: { trusted: {} }
-		});
-		const remoteTokens = /* @__PURE__ */ new Map();
-		function revokeRemoteToken(token) {
-			if (!remoteTokens.delete(token)) return;
-			revokeActiveConnectionsForToken(context, token);
-		}
-		const internalContext = {
-			storage: { auth: storage },
-			revokeAuthToken: (token) => revokeAuthToken(context, storage, token),
-			remoteTokens,
-			allocateRemoteToken(dockId, origin, originLock) {
-				const token = humanId();
-				remoteTokens.set(token, {
-					dockId,
-					origin,
-					originLock
-				});
-				return token;
-			},
-			revokeRemoteToken,
-			revokeRemoteTokensForDock(dockId) {
-				const tokensToRevoke = [];
-				for (const [token, record] of remoteTokens) if (record.dockId === dockId) tokensToRevoke.push(token);
-				for (const token of tokensToRevoke) revokeRemoteToken(token);
-			},
-			isRemoteTokenTrusted(token, requestOrigin) {
-				const record = remoteTokens.get(token);
-				if (!record) return false;
-				if (!record.originLock) return true;
-				return !!requestOrigin && record.origin === requestOrigin;
-			}
-		};
-		internalContextMap.set(context, internalContext);
-	}
-	return internalContextMap.get(context);
-}
-//#endregion
-export { getInternalContext, internalContextMap, normalizeBasePath, resolveBasePath };