devframe 0.9.0-beta.1 → 0.9.0-beta.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.9.0-beta.1",
+  "version": "0.9.0-beta.10",
   "description": "Framework for building one portable devtool integration that runs in any viewer.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -27,7 +27,6 @@
     "./adapters/mcp": "./dist/adapters/mcp.mjs",
     "./client": "./dist/client/index.mjs",
     "./constants": "./dist/constants.mjs",
-    "./helpers/vite": "./dist/helpers/vite.mjs",
     "./initiate": "./dist/adapters/initiate.mjs",
     "./internal": "./dist/internal/index.mjs",
     "./node": "./dist/node/index.mjs",
@@ -49,10 +48,13 @@
     "./utils/colors": "./dist/utils/colors.mjs",
     "./utils/crypto-token": "./dist/utils/crypto-token.mjs",
     "./utils/events": "./dist/utils/events.mjs",
+    "./utils/get-port": "./dist/utils/get-port.mjs",
     "./utils/hash": "./dist/utils/hash.mjs",
     "./utils/launch-editor": "./dist/utils/launch-editor.mjs",
     "./utils/nanoid": "./dist/utils/nanoid.mjs",
+    "./utils/nostics": "./dist/utils/nostics.mjs",
     "./utils/open": "./dist/utils/open.mjs",
+    "./utils/remote-assets": "./dist/utils/remote-assets.mjs",
     "./utils/simple-schema": "./dist/utils/simple-schema.mjs",
     "./utils/serve-static": "./dist/utils/serve-static.mjs",
     "./utils/shared-state": "./dist/utils/shared-state.mjs",
@@ -90,7 +92,6 @@
     "@standard-schema/spec": "^1.1.0",
     "birpc": "^4.1.0",
     "crossws": "^0.4.10",
-    "destr": "^2.0.5",
     "h3": "^2.0.1-rc.26",
     "mrmime": "^2.0.1",
     "nostics": "^1.2.0",
@@ -107,7 +108,6 @@
     "mlly": "^1.8.2",
     "obug": "^2.1.4",
     "ohash": "^2.0.11",
-    "open": "^11.0.0",
     "p-limit": "^7.3.1",
     "perfect-debounce": "^2.1.0",
     "structured-clone-es": "^2.0.1",

package/skills/devframe/SKILL.md

@@ -5,7 +5,7 @@ description: >
   framework- and build-tool-agnostic foundation for defining a
   devtool once and serving it in many places. Covers
   DevframeDefinition, picking the right deployment adapter
-  (cli / build / spa / vite / embedded / mcp), designing RPC
+  (cli / build / vite / embedded / mcp), designing RPC
   contracts, exposing an agent-native surface over MCP, and
   wiring the author's SPA client. For host-level features (docks,
   terminals, palette, etc.), the devframe can be mounted into a
@@ -36,11 +36,11 @@ All adapter factories share the shape `createXxx(devframeDef, options?)`.
 | 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` |
 | Register dynamically at runtime | `createEmbedded(def, { ctx })` | `devframe/adapters/embedded` |
-| Expose to coding agents (MCP) | `createMcpServer(def, options?)` | `devframe/adapters/mcp` *(experimental)* |
+| Expose to coding agents (MCP) | `createMcpServer(def, options?)` | `devframe/adapters/mcp` |
 
 The same `DevframeDefinition` runs under every adapter - pick based on deployment, not on what the tool does.
 
-For Vite-based hosts that don't use the kit (Nuxt, Astro, SolidStart, plain Vite apps), `devframe/helpers/vite` exports `viteDevBridge(def, options?)` - a Vite plugin that mounts the SPA (static mode) or starts the RPC + WS bridge alongside the host's dev server (`devMiddleware: true`). Not an adapter; just a Vite integration helper.
+For Vite-based hosts that don't use the kit (Nuxt, Astro, SolidStart, plain Vite apps), `@devframes/vite` exports `devframeVitePlugin(def, options?)` (static SPA mount) and `devframeViteBridge(def, options?)` (RPC + WS bridge alongside the host's dev server) - plus `devframeVite(def, { bridge, ...options })` as a convenience wrapper over both. Not an adapter; just a Vite integration helper.
 
 ## Minimum viable devframe
 
@@ -85,7 +85,7 @@ export default defineDevframe({
 
 `setup(ctx)` registers RPC functions, shared state, diagnostics, and any other devframe-level wiring. Host adapters can augment `ctx` with extra surfaces - for example, mounting into Vite DevTools via `createPluginFromDevframe(d)` exposes `docks`, `terminals`, `messages`, and `commands` on the augmented context, and the kit auto-derives an iframe dock entry from `id` / `name` / `icon` / `basePath`. For richer host-side behaviour (custom-render, terminals, palette commands) pass `options.setup` to `createPluginFromDevframe`.
 
-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.
+See `templates/counter-devframe.ts` for a runnable counter example and `templates/vite-client.ts` for the author's client entry.
 
 ## Scoped context (preferred)
 
@@ -243,7 +243,7 @@ A [scoped context](#scoped-context-preferred) applies this prefix for you - `ctx
 | `ctx.rpc` | Register RPC functions, broadcast, shared state, streaming channels |
 | `ctx.views` | Serve static files via `hostStatic(base, distDir)` |
 | `ctx.diagnostics` | Structured diagnostics host (nostics) - register custom error codes |
-| `ctx.agent` | Expose tools + resources to coding agents (experimental) |
+| `ctx.agent` | Expose tools + resources to coding agents |
 | `ctx.host` | Runtime abstraction - `mountStatic`, `resolveOrigin`, `getStorageDir` |
 | `ctx.mode` | `'dev'` or `'build'` - gate setup work per runtime |
 
@@ -440,7 +440,7 @@ when: 'my-inspector.ready && count >= 10'
 
 Built-in context: `clientType` (`'embedded' | 'standalone'`), `dockOpen`, `paletteOpen`, `dockSelectedId`. Plugins can add namespaced keys (`.` or `:` separators). Both the types (`WhenExpression<Ctx, S>`) and runtime (`evaluateWhen`, `resolveContextValue`) come from `devframe/utils/when`.
 
-## Agent-native surface (experimental)
+## Agent-native surface
 
 Opt an RPC function into the agent surface with an `agent` field - default-deny otherwise. Agent-exposed functions **must declare `jsonSerializable: true`** (registration throws `DF0019` otherwise):
 
@@ -504,7 +504,7 @@ const data = await my.rpc.call('get-stats', { limit: 10 })
 `connectDevframe` auto-detects the backend via `/.devframe/.connection.json`:
 
 - **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.
+- **static** (build output) - read-only, resolves calls from the baked RPC dump.
 
 Use `my.rpc.sharedState(key)` for observable state, `my.rpc.register(defineRpcFunction(...))` to receive server broadcasts, `my.rpc.callOptional(...)` when a missing handler should resolve to `undefined` instead of throwing, and `my.settings.{project,global}` for persisted per-workspace / per-user settings synced from the server.
 
@@ -530,14 +530,13 @@ At runtime, static clients look up the argument hash in the dump; misses resolve
 
 ## CLI adapter subcommands
 
-`createCac(devframe).parse()` gives the tool four subcommands out of the box:
+`createCac(devframe).parse()` gives the tool three subcommands out of the box:
 
 | Subcommand | Action |
 |------------|--------|
 | *(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) |
+| `mcp` | stdio MCP server |
 
 **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. `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.
 
@@ -572,7 +571,7 @@ RPC handlers run with the full privileges of the host process, so the boundary t
 - **Tokens are secrets.** The bearer token rides the WS URL (`?devframe_auth_token=…`) - serve over `wss://`/`https://` beyond loopback. Never log the token or code, never bake them into build output. Revoke via `revokeAuthToken(...)`; clients drop to untrusted on `devframe:auth:revoked`.
 - **Authorize handlers.** Any trusted client can call any registered function - validate inputs, and mark state-changing functions `type: 'destructive'` so MCP/agent clients prompt first.
 - **Origin-lock remote docks** (`originLock`, on by default) so a dock's session token is honored only on a connection whose `Origin` matches the dock - the connect-time gate enforces it.
-- **The MCP route requires an Origin.** The route-based MCP server (`cli.mcp`, `viteDevBridge`/Next handler `mcp`, `createMcpFetchHandler`) rejects `Origin`-less requests - a request must carry a loopback (or allow-listed) `Origin`, so it isn't reachable by an arbitrary local process. `devframe connect` sends each instance's own loopback origin automatically.
+- **The MCP route requires an Origin.** The route-based MCP server (`cli.mcp`, `devframeViteBridge`/Next handler `mcp`, `createMcpFetchHandler`) rejects `Origin`-less requests - a request must carry a loopback (or allow-listed) `Origin`, so it isn't reachable by an arbitrary local process. `devframe connect` sends each instance's own loopback origin automatically.
 
 See [Security](https://devfra.me/security) for the full reference.
 

package/dist/diagnostics-reporter-CsIG85Q5.mjs

@@ -1,38 +0,0 @@
-import { ansiFormatter } from "nostics/formatters/ansi";
-//#region src/utils/colors.ts
-function makeColor(open, close) {
-	const o = `\x1B[${open}m`;
-	const c = `\x1B[${close}m`;
-	return ((arg, ...values) => {
-		if (Array.isArray(arg) && "raw" in arg) {
-			const strings = arg;
-			let out = "";
-			for (let i = 0; i < strings.length; i++) {
-				out += strings[i];
-				if (i < values.length) out += String(values[i]);
-			}
-			return `${o}${out}${c}`;
-		}
-		return `${o}${String(arg)}${c}`;
-	});
-}
-const colors = {
-	blue: makeColor(34, 39),
-	cyan: makeColor(36, 39),
-	gray: makeColor(90, 39),
-	green: makeColor(32, 39),
-	red: makeColor(31, 39),
-	yellow: makeColor(33, 39),
-	bold: makeColor(1, 22),
-	dim: makeColor(2, 22),
-	reset: makeColor(0, 0),
-	underline: makeColor(4, 24)
-};
-//#endregion
-//#region src/utils/diagnostics-reporter.ts
-const formatAnsi = ansiFormatter(colors);
-function devframeReporter(d, { method = "warn" } = {}) {
-	console[method](formatAnsi(d));
-}
-//#endregion
-export { colors as n, devframeReporter as t };

package/dist/helpers/vite.d.mts

@@ -1,104 +0,0 @@
-import { f as McpRouteOptions, p as DevframeAuthHandler, r as DevframeDefinition } from "../devframe-Bdd9YXTy.mjs";
-import { IncomingMessage, Server, ServerResponse } from "node:http";
-//#region src/helpers/vite.d.ts
-interface ViteDevBridgeOptions {
-  /**
-   * Mount base. Defaults to `def.basePath ?? '/__<id>/'` for this hosted
-   * adapter — the devframe shares the origin with the host Vite app.
-   *
-   * Relative spellings like `'./'` (common for base-agnostic Nuxt builds)
-   * are normalized to absolute paths so they compose with Vite's connect
-   * router.
-   */
-  base?: string;
-  /**
-   * Dev-time middleware mode. When set, the host app owns the SPA and
-   * devframe serves the RPC surface through the Vite dev server itself —
-   * `<base>__connection.json` for discovery and the WebSocket upgrade at
-   * `<base>__ws` on Vite's own HTTP server (zero extra ports, proxy/HTTPS
-   * friendly). When Vite runs in middleware mode (no `httpServer`) — or a
-   * `port` is pinned — the socket falls back to a side-car server on its
-   * own port instead.
-   *
-   *  - `false` (default) — static-mount the SPA at `base` with SPA
-   *    fallback. No RPC server is started.
-   *  - `true` — bridge mode with all defaults.
-   *  - object — bridge mode with explicit overrides.
-   */
-  devMiddleware?: boolean | {
-    /**
-     * Pin a side-car port for the RPC socket instead of sharing Vite's
-     * server. Default: share Vite's HTTP server (side-car only when Vite
-     * has none).
-     */
-    port?: number;
-    /** Override the side-car bind host. Default: `def.cli?.host ?? 'localhost'`. */
-    host?: string;
-    /** Flag bag forwarded to `def.setup(ctx, { flags })`. */
-    flags?: Record<string, unknown>;
-  };
-  /**
-   * Whether the bridged devframe runs its own auth gate. The RPC endpoint is
-   * reachable by anything that can open its socket, so it **gates by
-   * default**: when unset, authentication resolves through devframe's
-   * interactive OTP gate (unless the definition's `cli.auth` opts out), and
-   * the bridge prints its code/link banner to stdout. Pass a
-   * {@link DevframeAuthHandler} to install a custom scheme, or `false` to opt
-   * out for a single-user localhost host that owns the trust boundary another
-   * way. Only applies in bridge mode (`devMiddleware`); the static-mount mode
-   * starts no RPC server.
-   *
-   * @default gated (devframe's interactive OTP, unless `cli.auth` opts out)
-   */
-  auth?: boolean | DevframeAuthHandler;
-  /**
-   * Expose the bridge's route-based MCP server (Streamable-HTTP) at
-   * `<base>__mcp` — on the Vite app's own origin — and advertise it in the
-   * bridge's `__connection.json`. Overrides `def.cli?.mcp`, `undefined`
-   * falls through to it, `false` disables the route regardless. Only applies
-   * in bridge mode (`devMiddleware`); the static-mount mode starts no server.
-   *
-   * @experimental
-   */
-  mcp?: boolean | McpRouteOptions;
-}
-/** The slice of a Vite dev server the bridge plugin touches. */
-interface DevframeViteDevServerLike {
-  middlewares: {
-    use: ((path: string, handler: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void) => void) & ((handler: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void) => void);
-  };
-  httpServer?: Server | null;
-}
-interface DevframeVitePlugin {
-  name: string;
-  apply: 'serve';
-  configureServer: (server: DevframeViteDevServerLike) => void | Promise<void>;
-  closeBundle?: () => void | Promise<void>;
-}
-/**
- * Bridge a devframe into an existing Vite dev server. Returns a Vite
- * plugin with two modes, picked via `options.devMiddleware`:
- *
- *   - **static-mount mode** (default) — mounts `def.cli.distDir` at
- *     `options.base` with SPA fallback enabled. No RPC server is started.
- *
- *   - **bridge mode** (`devMiddleware: true | {…}`) — skips the static
- *     mount; the host app owns the SPA. Devframe serves discovery
- *     (`<base>__connection.json`), the WebSocket RPC upgrade
- *     (`<base>__ws`, shared on Vite's own HTTP server), and the optional
- *     MCP route through {@link initDevframe}'s node middleware, so the
- *     host-served SPA can discover the endpoint via {@link connectDevframe}.
- *
- * The bridge **gates by default** (devframe's interactive OTP unless the
- * definition's `cli.auth` opts out), printing its code/link banner to stdout,
- * so a bridged devframe isn't silently reachable by anything that can open
- * its socket. Pass `options.auth: false` to opt out for a single-user
- * localhost host, or a {@link DevframeAuthHandler} for a custom scheme.
- *
- * Use bridge mode when integrating with frameworks that own the SPA
- * (Nuxt, Astro, SolidStart, plain Vite apps). For the all-in-one
- * `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
- */
-declare function viteDevBridge(d: DevframeDefinition, options?: ViteDevBridgeOptions): DevframeVitePlugin;
-//#endregion
-export { DevframeViteDevServerLike, DevframeVitePlugin, ViteDevBridgeOptions, viteDevBridge };

package/dist/helpers/vite.mjs

@@ -1,93 +0,0 @@
-import { t as diagnostics } from "../diagnostics-DLYH5oD3.mjs";
-import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-CttmCMBi.mjs";
-import { serveStaticNodeMiddleware } from "../utils/serve-static.mjs";
-import { r as initDevframe } from "../dev-BEveeA5H.mjs";
-import { resolve } from "pathe";
-//#region src/helpers/vite.ts
-/**
-* Bridge a devframe into an existing Vite dev server. Returns a Vite
-* plugin with two modes, picked via `options.devMiddleware`:
-*
-*   - **static-mount mode** (default) — mounts `def.cli.distDir` at
-*     `options.base` with SPA fallback enabled. No RPC server is started.
-*
-*   - **bridge mode** (`devMiddleware: true | {…}`) — skips the static
-*     mount; the host app owns the SPA. Devframe serves discovery
-*     (`<base>__connection.json`), the WebSocket RPC upgrade
-*     (`<base>__ws`, shared on Vite's own HTTP server), and the optional
-*     MCP route through {@link initDevframe}'s node middleware, so the
-*     host-served SPA can discover the endpoint via {@link connectDevframe}.
-*
-* The bridge **gates by default** (devframe's interactive OTP unless the
-* definition's `cli.auth` opts out), printing its code/link banner to stdout,
-* so a bridged devframe isn't silently reachable by anything that can open
-* its socket. Pass `options.auth: false` to opt out for a single-user
-* localhost host, or a {@link DevframeAuthHandler} for a custom scheme.
-*
-* Use bridge mode when integrating with frameworks that own the SPA
-* (Nuxt, Astro, SolidStart, plain Vite apps). For the all-in-one
-* `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
-*/
-function viteDevBridge(d, options = {}) {
-	const base = normalizeMountBase(options.base ?? resolveBasePath(d, "hosted"));
-	if (!options.devMiddleware) {
-		const distDir = d.cli?.distDir;
-		return {
-			name: `devframe:${d.id}`,
-			apply: "serve",
-			configureServer(server) {
-				if (!distDir) return;
-				server.middlewares.use(base, serveStaticNodeMiddleware(resolve(distDir)));
-			}
-		};
-	}
-	const mw = options.devMiddleware === true ? {} : options.devMiddleware;
-	let instance;
-	return {
-		name: `devframe:${d.id}`,
-		apply: "serve",
-		async configureServer(server) {
-			await instance?.close().catch(() => {});
-			instance = void 0;
-			try {
-				const created = initDevframe(d, {
-					base,
-					distDir: false,
-					flags: mw.flags,
-					host: mw.host,
-					...mw.port != null ? { ws: { port: mw.port } } : server.httpServer ? { server: server.httpServer } : { ws: { sidecar: true } },
-					auth: options.auth,
-					mcp: options.mcp
-				});
-				server.middlewares.use(created.nodeMiddleware);
-				await created.ready;
-				instance = created;
-			} catch (e) {
-				diagnostics.DF0033({
-					id: d.id,
-					reason: String(e),
-					cause: e
-				}, { method: "warn" });
-				return;
-			}
-			server.httpServer?.once("close", () => {
-				instance?.close().catch(() => {});
-			});
-		},
-		async closeBundle() {
-			await instance?.close().catch(() => {});
-			instance = void 0;
-		}
-	};
-}
-/**
-* Make `base` safe for `server.middlewares.use(path, …)`. Vite's connect
-* router matches by absolute URL prefix, so relative spellings like
-* `'./'` (commonly used for base-agnostic Nuxt builds) collapse to the
-* origin root before the shared leading/trailing-slash normalization.
-*/
-function normalizeMountBase(base) {
-	return normalizeBasePath(base.replace(/^\.\/?/, "/"));
-}
-//#endregion
-export { viteDevBridge };