devframe 0.8.2 → 0.9.0-beta.10

package/dist/_shared-BPmX9fqK.d.mts

@@ -0,0 +1,41 @@
+import { d as ConnectionMeta, l as McpRouteOptions, n as DevframeDefinition, r as DevframeDeploymentKind } from "./devframe-DJMg0WLe.mjs";
+//#region src/adapters/_shared.d.ts
+/**
+ * Resolve the mount base path for a devframe's SPA. Hosted adapters
+ * (`vite`, `embedded`) default to `/__<id>/` so they don't collide
+ * with the host app; standalone adapters (`cli`, `build`)
+ * default to `/` because they own the origin.
+ *
+ * The devframe author can override with `basePath` on the definition.
+ */
+declare function resolveBasePath(def: DevframeDefinition, kind: DevframeDeploymentKind): string;
+declare function normalizeBasePath(base: string): string;
+interface ResolveDevServerPortOptions {
+  /** Bind host (passed to `get-port-please` for in-use detection). */
+  host?: string;
+  /** Override the preferred port. Default: `def.cli?.port ?? 9999`. */
+  defaultPort?: number;
+}
+/**
+ * Resolve the listening port for `createDevServer` (and `createHandler`'s
+ * side-car tiers), honoring the definition's `cli.port` / `cli.portRange` /
+ * `cli.random` settings. Exposed separately so authors who run their own
+ * argv parsing can resolve a port up-front (to print it, log it, etc.)
+ * before starting the server.
+ */
+declare function resolveDevServerPort(def: DevframeDefinition, options?: ResolveDevServerPortOptions): Promise<number>;
+/**
+ * Resolve the `mcp` entry a `__connection.json` should advertise for a dev
+ * server started with the given `mcp` option (falling back to `def.cli?.mcp`,
+ * exactly like `createDevServer`), or `undefined` when the route is
+ * disabled.
+ *
+ * Hosted bridges that hand-roll their connection meta pass the side-car
+ * `port`: the advertised path becomes absolute (the side-car mounts at `/`)
+ * and the client dials `<page-host>:<port><path>`. Without `port` the path
+ * stays relative, resolved against `__connection.json`'s own location (the
+ * same-server default).
+ */
+declare function resolveMcpConnectionMeta(def: DevframeDefinition, mcp: boolean | McpRouteOptions | undefined, port?: number): ConnectionMeta['mcp'];
+//#endregion
+export { resolveMcpConnectionMeta as a, resolveDevServerPort as i, normalizeBasePath as n, resolveBasePath as r, ResolveDevServerPortOptions as t };

package/dist/_shared-CbZ_yhbz.mjs

@@ -0,0 +1,68 @@
+import "./constants.mjs";
+import { n as getPort } from "./dist-eNI9qM_I.mjs";
+import { cleanDoubleSlashes, withLeadingSlash, withTrailingSlash, withoutLeadingSlash } from "ufo";
+//#region src/adapters/_shared.ts
+const DEFAULT_PORT = 9999;
+/**
+* Resolve the mount base path for a devframe's SPA. Hosted adapters
+* (`vite`, `embedded`) default to `/__<id>/` so they don't collide
+* with the host app; standalone adapters (`cli`, `build`)
+* default to `/` because they own the origin.
+*
+* The devframe author can override with `basePath` on the definition.
+*/
+function resolveBasePath(def, kind) {
+	if (def.basePath) return normalizeBasePath(def.basePath);
+	return kind === "standalone" ? "/" : `/__${def.id}/`;
+}
+function normalizeBasePath(base) {
+	return cleanDoubleSlashes(withTrailingSlash(withLeadingSlash(base)));
+}
+/**
+* Resolve the listening port for `createDevServer` (and `createHandler`'s
+* side-car tiers), honoring the definition's `cli.port` / `cli.portRange` /
+* `cli.random` settings. Exposed separately so authors who run their own
+* argv parsing can resolve a port up-front (to print it, log it, etc.)
+* before starting the server.
+*/
+async function resolveDevServerPort(def, options = {}) {
+	const host = options.host ?? def.cli?.host ?? "localhost";
+	const portOptions = {
+		port: options.defaultPort ?? def.cli?.port ?? DEFAULT_PORT,
+		host
+	};
+	if (def.cli?.portRange) portOptions.portRange = def.cli.portRange;
+	if (def.cli?.random) portOptions.random = def.cli.random;
+	return getPort(portOptions);
+}
+/**
+* Normalize the `cli.mcp` / `mcp` option (`boolean | McpRouteOptions`) into
+* concrete options, or `undefined` when the MCP route is disabled.
+*/
+function resolveMcpConfig(mcp) {
+	if (!mcp) return void 0;
+	return mcp === true ? {} : mcp;
+}
+/**
+* Resolve the `mcp` entry a `__connection.json` should advertise for a dev
+* server started with the given `mcp` option (falling back to `def.cli?.mcp`,
+* exactly like `createDevServer`), or `undefined` when the route is
+* disabled.
+*
+* Hosted bridges that hand-roll their connection meta pass the side-car
+* `port`: the advertised path becomes absolute (the side-car mounts at `/`)
+* and the client dials `<page-host>:<port><path>`. Without `port` the path
+* stays relative, resolved against `__connection.json`'s own location (the
+* same-server default).
+*/
+function resolveMcpConnectionMeta(def, mcp, port) {
+	const config = resolveMcpConfig(mcp ?? def.cli?.mcp);
+	if (!config) return void 0;
+	const route = withoutLeadingSlash(config.path ?? "__mcp");
+	return port != null ? {
+		path: withLeadingSlash(route),
+		port
+	} : { path: route };
+}
+//#endregion
+export { resolveMcpConnectionMeta as i, resolveBasePath as n, resolveDevServerPort as r, normalizeBasePath as t };

package/dist/adapters/build.d.mts

@@ -1,16 +1,16 @@
-import { r as DevframeDefinition } from "../devframe-mQ4qZAuo.mjs";
+import { n as DevframeDefinition } from "../devframe-DJMg0WLe.mjs";
+import { o as StaticAssetsSource } from "../remote-assets-Bg4gCUZ_.mjs";
 //#region src/adapters/build.d.ts
 interface CreateBuildOptions {
   /** Output directory. Defaults to `dist-static`. */
   outDir?: string;
-  /** Absolute URL base the output is served from (default: `/`). */
-  base?: string;
   /**
-   * Override the SPA dist directory to copy into `outDir`. When omitted
-   * the adapter reads `devframe.cli?.distDir` — authors typically set this
-   * once on the definition itself.
+   * Override the SPA dist to copy into `outDir` — a local directory or a
+   * remote-assets declaration (materialized in full at build time). When
+   * omitted the adapter reads `devframe.cli?.distDir` — authors typically
+   * set this once on the definition itself.
    */
-  distDir?: string;
+  distDir?: StaticAssetsSource;
   /**
    * Pretty-print RPC dump JSON files. Defaults to `false` so payload
    * shards (which can be multiple MB for graph-heavy tools) ship
@@ -32,11 +32,9 @@ interface CreateBuildOptions {
  *   - Copy the author's SPA dist into `<outDir>/`.
  *   - Write `<outDir>/__connection.json` (`{ backend: 'static' }`) and the
  *     sharded RPC dump under `<outDir>/__rpc-dump/` so the deployed SPA
- *     discovers both via relative paths from `document.baseURI`.
- *   - When `def.spa` is configured, also write `<outDir>/spa-loader.json`
- *     describing the SPA's data-loader mode (`'query'` / `'upload'` /
- *     `'none'`). The output is mount-path agnostic — the same bundle
- *     works at `/`, `/devframe/`, or any base, no rewriting required.
+ *     discovers both via relative paths from `document.baseURI`. The
+ *     output is mount-path agnostic — the same bundle works at `/`,
+ *     `/devframe/`, or any base, no rewriting required.
  */
 declare function createBuild(d: DevframeDefinition, options?: CreateBuildOptions): Promise<void>;
 //#endregion

package/dist/adapters/build.mjs

@@ -1,15 +1,16 @@
-import { t as collectStaticRpcDump } from "../dump-CgZShDRB.mjs";
-import { n as colors } from "../diagnostics-reporter-CsIG85Q5.mjs";
+import { s as colors } from "../nostics-CzECRXpE.mjs";
+import { n as strictJsonStringify } from "../serialization-BGzEwAdr.mjs";
 import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
-import { n as strictJsonStringify } from "../serialization-C8Mnw9hK.mjs";
+import { t as collectStaticRpcDump } from "../static-BPZ1_OPA.mjs";
 import { n as structuredCloneStringify } from "../structured-clone-CbAV5rFI.mjs";
-import { n as createHostContext, t as createH3DevframeHost } from "../host-h3-D2hYZvDK.mjs";
-import { t as diagnostics } from "../diagnostics-D7wM2cwM.mjs";
-import { n as resolveBasePath } from "../_shared-bWRzeSa0.mjs";
+import { t as diagnostics } from "../diagnostics-DOQPnQmX.mjs";
+import { t as createHostContext } from "../context-CEe4PBz1.mjs";
+import { t as resolveStaticAssetsSource } from "../remote-assets-nTTxY2MU.mjs";
+import { t as createH3DevframeHost } from "../host-h3-Crkzm42q.mjs";
 import { existsSync } from "node:fs";
+import fs$1 from "node:fs/promises";
 import { dirname, resolve } from "pathe";
 import process from "node:process";
-import fs$1 from "node:fs/promises";
 //#region src/adapters/build.ts
 /**
 * Produce a self-contained static deploy of a devframe:
@@ -18,28 +19,33 @@ import fs$1 from "node:fs/promises";
 *   - Copy the author's SPA dist into `<outDir>/`.
 *   - Write `<outDir>/__connection.json` (`{ backend: 'static' }`) and the
 *     sharded RPC dump under `<outDir>/__rpc-dump/` so the deployed SPA
-*     discovers both via relative paths from `document.baseURI`.
-*   - When `def.spa` is configured, also write `<outDir>/spa-loader.json`
-*     describing the SPA's data-loader mode (`'query'` / `'upload'` /
-*     `'none'`). The output is mount-path agnostic — the same bundle
-*     works at `/`, `/devframe/`, or any base, no rewriting required.
+*     discovers both via relative paths from `document.baseURI`. The
+*     output is mount-path agnostic — the same bundle works at `/`,
+*     `/devframe/`, or any base, no rewriting required.
 */
 async function createBuild(d, options = {}) {
 	if (d.capabilities?.build === false && !options.force) throw diagnostics.DF0042({ id: d.id });
 	const outDir = resolve(options.outDir ?? "dist-static");
-	const distDir = options.distDir ?? d.cli?.distDir;
-	if (!distDir) throw new Error(`[devframe] createBuild: no distDir for "${d.id}". Set \`cli.distDir\` on the definition or pass it as an option.`);
+	const distSource = options.distDir ?? d.cli?.distDir;
+	if (!distSource) throw new Error(`[devframe] createBuild: no distDir for "${d.id}". Set \`cli.distDir\` on the definition or pass it as an option.`);
 	if (existsSync(outDir)) await fs$1.rm(outDir, { recursive: true });
 	await fs$1.mkdir(outDir, { recursive: true });
-	console.log(colors.cyan`[devframe] copying SPA from ${distDir} -> ${outDir}`);
-	await fs$1.cp(distDir, outDir, { recursive: true });
+	const host = createH3DevframeHost({
+		origin: "http://localhost",
+		appName: d.id
+	});
+	const resolved = resolveStaticAssetsSource(distSource, host.getStorageDir("project"));
+	if (typeof resolved === "string") {
+		console.log(colors.cyan`[devframe] copying SPA from ${resolved} -> ${outDir}`);
+		await fs$1.cp(resolved, outDir, { recursive: true });
+	} else {
+		console.log(colors.cyan`[devframe] materializing SPA from ${resolved.assets.package}@${resolved.assets.version} -> ${outDir}`);
+		await resolved.materialize(outDir);
+	}
 	const ctx = await createHostContext({
 		cwd: process.cwd(),
 		mode: "build",
-		host: createH3DevframeHost({
-			origin: "http://localhost",
-			appName: d.id
-		})
+		host
 	});
 	await d.setup(ctx);
 	await fs$1.mkdir(resolve(outDir, DEVFRAME_RPC_DUMP_DIRNAME), { recursive: true });
@@ -59,15 +65,6 @@ async function createBuild(d, options = {}) {
 		await fs$1.writeFile(fullpath, file.serialization === "json" && indent != null ? JSON.stringify(JSON.parse(text), null, indent) : text, "utf-8");
 	}
 	await fs$1.writeFile(resolve(outDir, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME), JSON.stringify(dump.manifest, null, 2), "utf-8");
-	if (d.spa) {
-		const base = options.base ?? resolveBasePath(d, "standalone");
-		const spaLoader = {
-			version: 1,
-			mode: d.spa.loader ?? "none",
-			base
-		};
-		await fs$1.writeFile(resolve(outDir, "spa-loader.json"), JSON.stringify(spaLoader, null, 2), "utf-8");
-	}
 	console.log(colors.green`[devframe] built "${d.id}" -> ${outDir}`);
 }
 //#endregion

package/dist/adapters/cac.d.mts

@@ -1,4 +1,4 @@
-import { Ft as InferCliFlags, It as defineCliFlags, Lt as parseCliFlags, Pt as CliFlagsSchema, r as DevframeDefinition } from "../devframe-mQ4qZAuo.mjs";
+import { At as defineCliFlags, Ot as CliFlagsSchema, jt as parseCliFlags, kt as InferCliFlags, n as DevframeDefinition } from "../devframe-DJMg0WLe.mjs";
 import { CAC } from "cac";
 import { H3 } from "h3";
 //#region src/adapters/cac.d.ts

package/dist/adapters/cac.mjs

@@ -1,2 +1,157 @@
-import { n as defineCliFlags, r as parseCliFlags, t as createCac } from "../cac-D4_9ok0z.mjs";
+import { s as colors } from "../nostics-CzECRXpE.mjs";
+import { r as resolveDevServerPort } from "../_shared-CbZ_yhbz.mjs";
+import { createBuild } from "./build.mjs";
+import { t as createDevServer } from "../dev--rAPzbvO.mjs";
+import process from "node:process";
+import cac$1 from "cac";
+//#region src/adapters/flags.ts
+/**
+* Identity helper that preserves the literal schema-map type — use this
+* so `InferCliFlags<typeof myFlags>` resolves to the right object shape.
+*
+* ```ts
+* const appFlags = defineCliFlags({
+*   depth: v.pipe(v.number(), v.integer()),
+*   config: v.optional(v.string()),
+* })
+*
+* defineDevframe({
+*   cli: { flags: appFlags },
+*   setup(ctx, info) {
+*     const flags = info.flags as InferCliFlags<typeof appFlags>
+*     flags.depth // number
+*     flags.config // string | undefined
+*   },
+* })
+* ```
+*/
+function defineCliFlags(flags) {
+	return flags;
+}
+/**
+* Best-effort, dependency-free probe of a schema to decide whether the
+* corresponding CAC option takes a value. Duck-types the `type` /
+* `wrapped` / `inner` / `pipe` fields exposed by valibot and by devframe's
+* built-in `s` builder, unwrapping `optional` / `nullable` / `nullish` /
+* `pipe` wrappers then matching on the inner kind. Validators that don't
+* expose these fields (e.g. zod) fall through to a value-taking option.
+*/
+function getSchemaKind(schema) {
+	let current = schema;
+	while (current) {
+		const kind = current.type;
+		if (kind === "optional" || kind === "nullable" || kind === "nullish" || kind === "undefined") {
+			current = current.wrapped ?? current.inner;
+			continue;
+		}
+		if (kind === "pipe" && Array.isArray(current.pipe) && current.pipe.length > 0) {
+			current = current.pipe[0];
+			continue;
+		}
+		return kind ?? "unknown";
+	}
+	return "unknown";
+}
+/** Whether the CAC option for this schema should be a boolean flag. */
+function isBooleanFlag(schema) {
+	return getSchemaKind(schema) === "boolean";
+}
+/** Validate the raw cac-parsed bag against a {@link CliFlagsSchema}. */
+function parseCliFlags(schema, raw) {
+	const flags = {};
+	const issues = [];
+	for (const [key, fieldSchema] of Object.entries(schema)) {
+		const result = fieldSchema["~standard"].validate(raw[key]);
+		if (result instanceof Promise) {
+			issues.push(`--${toKebab(key)}: async flag validation is not supported`);
+			continue;
+		}
+		if (result.issues) issues.push(`--${toKebab(key)}: ${result.issues.map((i) => i.message).join(", ")}`);
+		else flags[key] = result.value;
+	}
+	for (const [key, value] of Object.entries(raw)) if (!(key in schema) && !(key in flags)) flags[key] = value;
+	return issues.length ? {
+		flags,
+		issues
+	} : { flags };
+}
+function toKebab(camel) {
+	return camel.replaceAll(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** Kebab-case a schema key for CAC option registration. */
+function flagKeyToOption(camel) {
+	return toKebab(camel);
+}
+//#endregion
+//#region src/adapters/cac.ts
+/**
+* Wrap a {@link DevframeDefinition} in a `cac`-powered command-line
+* interface exposing `dev` / `build` / `mcp` subcommands.
+*
+* Requires the optional `cac` peer dependency.
+*/
+function createCac(d, options = {}) {
+	const defaultPort = options.defaultPort ?? d.cli?.port ?? 9999;
+	const defaultHost = d.cli?.host ?? "localhost";
+	const cli = cac$1(d.cli?.command ?? d.id);
+	const devCommand = cli.command("[...args]", "Start a local dev server").option("--port <port>", "Port to listen on").option("--host <host>", "Host to bind to", { default: defaultHost }).option("--open", "Open the browser on start").option("--no-open", "Do not open the browser").option("--no-auth", "Disable the interactive authentication gate").option("--mcp", "Expose an MCP server over HTTP at /__mcp (use --no-mcp to disable)");
+	if (d.cli?.flags) for (const [key, schema] of Object.entries(d.cli.flags)) {
+		const optionName = flagKeyToOption(key);
+		const description = schema.description ?? "";
+		if (isBooleanFlag(schema)) devCommand.option(`--${optionName}`, description);
+		else devCommand.option(`--${optionName} <value>`, description);
+	}
+	devCommand.action(async (_args, rawFlags) => {
+		const flags = resolveTypedFlags(d, rawFlags);
+		const host = flags.host ?? defaultHost;
+		const port = flags.port ?? await resolveDevServerPort(d, {
+			host,
+			defaultPort
+		});
+		const mcp = flags.mcp;
+		await createDevServer(d, {
+			host,
+			port,
+			flags,
+			mcp,
+			onReady: options.onReady
+		});
+	});
+	if (d.capabilities?.build !== false) cli.command("build", "Build a self-contained static deploy of the devframe").option("--out-dir <outDir>", "Output directory", { default: "dist-static" }).option("--pretty", "Pretty-print dump JSON (larger on disk)").action(async (flags) => {
+		await createBuild(d, {
+			outDir: flags.outDir,
+			pretty: flags.pretty
+		});
+	});
+	cli.command("mcp", "Start an MCP server exposing agent-facing tools (stdio)").action(async () => {
+		const { createMcpServer } = await import("./mcp.mjs");
+		await createMcpServer(d, {
+			transport: "stdio",
+			onReady: ({ transport }) => {
+				console.error(`[devframe] "${d.id}" MCP server ready (${transport})`);
+			}
+		});
+	});
+	d.cli?.configure?.(cli);
+	options.configureCli?.(cli);
+	cli.help();
+	cli.version("0.0.0");
+	return {
+		cli,
+		async parse(argv = process.argv) {
+			cli.parse(argv, { run: false });
+			await cli.runMatchedCommand();
+		}
+	};
+}
+function resolveTypedFlags(d, raw) {
+	if (!d.cli?.flags) return raw;
+	const { flags, issues } = parseCliFlags(d.cli.flags, raw);
+	if (issues?.length) {
+		for (const issue of issues) console.error(colors.red`[devframe] invalid flag — ${issue}`);
+		process.exit(1);
+	}
+	return flags;
+}
+//#endregion
 export { createCac, defineCliFlags, parseCliFlags };

package/dist/adapters/dev.d.mts

@@ -1,7 +1,8 @@
-import { W as DevframeNodeRpcSession, _ as ConnectionMeta, d as McpRouteOptions, p as DevframeAuthHandler, r as DevframeDefinition, u as DevframeWsOptions } from "../devframe-mQ4qZAuo.mjs";
-import { n as DevframeNodeRpcSessionMeta } from "../ws-server-uKQcClcJ.mjs";
-import { n as StartedServer } from "../server-UHWae43Q.mjs";
-import { Peer } from "crossws";
+import { R as DevframeNodeRpcSession, c as DevframeWsOptions, l as McpRouteOptions, n as DevframeDefinition, s as DevframeSseOptions, u as DevframeAuthHandler } from "../devframe-DJMg0WLe.mjs";
+import { d as DevframeRpcConnection, n as WsOriginRegistry, u as DevframeNodeRpcSessionMeta } from "../ws-server-D1d3QM9f.mjs";
+import { o as StaticAssetsSource } from "../remote-assets-Bg4gCUZ_.mjs";
+import { c as StartedServer } from "../instance-shell-CljiKq1c.mjs";
+import { a as resolveMcpConnectionMeta, i as resolveDevServerPort, t as ResolveDevServerPortOptions } from "../_shared-BPmX9fqK.mjs";
 import { H3 } from "h3";
 //#region src/adapters/dev.d.ts
 interface CreateDevServerOptions {
@@ -24,9 +25,9 @@ interface CreateDevServerOptions {
    * `def.cli?.distDir` is set, the dev server runs in **bridge mode** —
    * only `__connection.json` and the WS endpoint are mounted; the SPA
    * is expected to be hosted elsewhere (e.g. by a parent Vite/Nuxt
-   * dev server via `viteDevBridge({ devMiddleware })`).
+   * dev server via `devframeViteBridge` from `@devframes/vite`).
    */
-  distDir?: string;
+  distDir?: StaticAssetsSource;
   /**
    * Override the SPA mount path. Defaults to
    * `resolveBasePath(def, 'standalone')` (i.e. `def.basePath` or `/`).
@@ -35,9 +36,23 @@ interface CreateDevServerOptions {
   /**
    * Override how the browser reaches the RPC WebSocket (`def.cli?.ws`).
    * See {@link DevframeWsOptions}: same-server route (default), a dedicated
-   * port, or a remote origin.
+   * port, or a remote origin. Pass `false` to serve no WebSocket at all —
+   * clients connect over the SSE endpoint instead (`backend: 'sse'`).
    */
-  ws?: DevframeWsOptions;
+  ws?: DevframeWsOptions | false;
+  /**
+   * Extra origins to accept on the WS upgrade beyond the loopback default.
+   * Add your LAN/tunnel origin here when reaching the tool from another
+   * host. Pass `false` to disable origin checking entirely (not
+   * recommended). Default: loopback-only.
+   */
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false;
+  /**
+   * Override the SSE RPC endpoint control (`def.cli?.sse`) — enabled by
+   * default at `<base>__sse`. Pass `false` to disable, or a
+   * {@link DevframeSseOptions} to rename the route.
+   */
+  sse?: boolean | DevframeSseOptions;
   /**
    * h3 app to mount the SPA + connection-meta routes on. When omitted
    * a fresh app is created. Pass a pre-configured app to attach custom
@@ -56,7 +71,7 @@ interface CreateDevServerOptions {
    * Override how authentication resolves, taking precedence over
    * `def.cli?.auth`. Pass `false` to skip the gate entirely (the standard
    * choice for a **hosted** deployment where the host manages auth — see
-   * {@link viteDevBridge}); a {@link DevframeAuthHandler} to install a custom
+   * {@link devframeViteBridge} from `@devframes/vite`); a {@link DevframeAuthHandler} to install a custom
    * scheme; or `true` to force devframe's interactive OTP gate on. When
    * omitted, auth resolves from `flags.auth` / `def.cli?.auth` (the standalone
    * default: gated). The `--no-auth` flag (`flags.auth === false`) still forces
@@ -71,16 +86,16 @@ interface CreateDevServerOptions {
    */
   mcp?: boolean | McpRouteOptions;
   /**
-   * Called once per new WS connection, right after its session is created.
-   * Forwarded verbatim to the underlying `startHttpAndWs`.
+   * Called once per new RPC connection, right after its session is created.
+   * Forwarded verbatim to the underlying transport binding.
    */
-  onPeerConnect?: (peer: Peer, session: DevframeNodeRpcSession) => void;
+  onPeerConnect?: (connection: DevframeRpcConnection, session: DevframeNodeRpcSession) => void;
   /**
-   * Called once per closed WS connection, right after its session's
+   * Called once per closed RPC connection, right after its session's
    * disconnect bookkeeping runs. Forwarded verbatim to the underlying
-   * `startHttpAndWs`.
+   * transport binding.
    */
-  onPeerDisconnect?: (peer: Peer, meta: DevframeNodeRpcSessionMeta) => void;
+  onPeerDisconnect?: (connection: DevframeRpcConnection, meta: DevframeNodeRpcSessionMeta) => void;
   /**
    * Called once the WS server is bound. Devframe stays headless
    * otherwise — wire this if you want a startup banner.
@@ -90,21 +105,13 @@ interface CreateDevServerOptions {
     port: number;
     app: H3;
   }) => void | Promise<void>;
+  /**
+   * Proceed even when the definition declares `capabilities.dev: false`.
+   * `createDevServer` otherwise refuses such a definition (`DF0058`) — this
+   * only matters for a caller invoking it directly, bypassing the CLI.
+   */
+  force?: boolean;
 }
-interface ResolveDevServerPortOptions {
-  /** Bind host (passed to `get-port-please` for in-use detection). */
-  host?: string;
-  /** Override the preferred port. Default: `def.cli?.port ?? 9999`. */
-  defaultPort?: number;
-}
-/**
- * Resolve the listening port for {@link createDevServer}, honoring the
- * definition's `cli.port` / `cli.portRange` / `cli.random` settings.
- * Exposed separately so authors who run their own argv parsing can
- * resolve a port up-front (to print it, log it, etc.) before starting
- * the server.
- */
-declare function resolveDevServerPort(def: DevframeDefinition, options?: ResolveDevServerPortOptions): Promise<number>;
 /**
  * Start a devframe dev server for a {@link DevframeDefinition} —
  * h3 + WebSocket RPC + (optionally) the author's SPA mounted at the
@@ -114,7 +121,7 @@ declare function resolveDevServerPort(def: DevframeDefinition, options?: Resolve
  * server runs in **bridge mode**: only `__connection.json` and the WS
  * endpoint are mounted, with no SPA mount. The SPA is expected to be
  * hosted elsewhere (e.g. by a parent Vite/Nuxt dev server) — see
- * `viteDevBridge({ devMiddleware })`.
+ * `devframeViteBridge` from `@devframes/vite`.
  *
  * Returns the underlying {@link StartedServer} handle so callers can
  * close it gracefully (SIGINT, hot-reload, test teardown).
@@ -124,20 +131,5 @@ declare function resolveDevServerPort(def: DevframeDefinition, options?: Resolve
  * `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
  */
 declare function createDevServer(def: DevframeDefinition, options?: CreateDevServerOptions): Promise<StartedServer>;
-/**
- * Resolve the `mcp` entry a `__connection.json` should advertise for a dev
- * server started with the given `mcp` option (falling back to `def.cli?.mcp`,
- * exactly like {@link createDevServer}), or `undefined` when the route is
- * disabled.
- *
- * Hosted bridges that hand-roll their connection meta (`viteDevBridge`,
- * `@devframes/next`'s handler) pass the side-car `port`: the advertised path
- * becomes absolute (the side-car mounts at `/`) and the client dials
- * `<page-host>:<port><path>`. Without `port` the path stays relative, resolved
- * against `__connection.json`'s own location (the same-server default).
- *
- * @experimental
- */
-declare function resolveMcpConnectionMeta(def: DevframeDefinition, mcp: boolean | McpRouteOptions | undefined, port?: number): ConnectionMeta['mcp'];
 //#endregion
-export { CreateDevServerOptions, ResolveDevServerPortOptions, createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };
+export { CreateDevServerOptions, type ResolveDevServerPortOptions, createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };

package/dist/adapters/dev.mjs

@@ -1,2 +1,3 @@
-import { n as resolveDevServerPort, r as resolveMcpConnectionMeta, t as createDevServer } from "../dev-Bc49u3qg.mjs";
+import { i as resolveMcpConnectionMeta, r as resolveDevServerPort } from "../_shared-CbZ_yhbz.mjs";
+import { t as createDevServer } from "../dev--rAPzbvO.mjs";
 export { createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };

package/dist/adapters/embedded.d.mts

@@ -1,4 +1,4 @@
-import { b as DevframeNodeContext, r as DevframeDefinition } from "../devframe-mQ4qZAuo.mjs";
+import { g as DevframeNodeContext, n as DevframeDefinition } from "../devframe-DJMg0WLe.mjs";
 //#region src/adapters/embedded.d.ts
 interface CreateEmbeddedOptions {
   /** Target context the devframe is registered into. Required. */