devframe 0.9.8 → 0.9.10

package/dist/_shared-CCzf9Hub.d.mts

@@ -0,0 +1,83 @@
+import { F as DevframeDefinition, G as McpAuthorization, I as DevframeDeploymentKind, q as McpSetting, t as ConnectionMeta, zt as DevframeAgentHost } from "./context-CHW4BZOj.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>;
+/**
+ * A fully-resolved MCP route configuration: the concrete authorization policy
+ * (never the `mcp: true` shorthand), plus the optional route path and origin
+ * allow-list. Every route mount consumes this shape.
+ */
+interface ResolvedMcpConfig {
+  /** Route segment, relative to the base. Default resolved by the caller. */
+  path?: string;
+  /** Origin allow-list, or `false` to disable the origin gate. */
+  allowedOrigins?: readonly string[] | false;
+  /** The resolved identity policy: a bearer token, callback, or `false`. */
+  authorization: McpAuthorization;
+}
+/**
+ * Normalize an *explicit* `mcp` setting into a fully-resolved config, or
+ * `undefined` when the MCP route is disabled. `'auto'` also resolves to
+ * `undefined` here: whether it mounts depends on the live agent surface,
+ * which only the mounting adapter can consult (through
+ * {@link loadAutoMcpAdapter}) - static resolvers like
+ * `resolveMcpConnectionMeta` treat it as unadvertisable.
+ *
+ * An enabled route trusts same-machine callers by default: the authorization
+ * resolves to origin-only (`false`) unless the object config opts into a
+ * bearer/callback identity check. An empty-string bearer is treated as no
+ * bearer (origin-only) rather than a usable credential.
+ */
+declare function resolveMcpConfig(mcp: McpSetting | undefined): ResolvedMcpConfig | undefined;
+/**
+ * Resolve the `mcp: 'auto'` default at mount time: import the MCP adapter
+ * when the devframe's agent surface is non-empty, or return `undefined`
+ * (mount nothing) when the surface is empty - the zero-cost path, loading
+ * no MCP code at all. The adapter (and the MCP SDK behind it) loads through
+ * `importRuntimeModule`, so it never enters a consumer's bundle graph.
+ *
+ * Generic like `importRuntimeModule`: the caller names the module type
+ * (`typeof import('devframe/adapters/mcp')`) so this shared helper carries
+ * no type-level dependency on the MCP adapter.
+ */
+declare function loadAutoMcpAdapter<T>(agent: Pick<DevframeAgentHost, 'hasSurface'>): Promise<T | undefined>;
+/**
+ * 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. `'auto'` (the omitted default) resolves at mount time against
+ * the live agent surface, so hand-rolled meta advertises it only for an
+ * explicit setting; the adapters advertise the actually-mounted route
+ * themselves.
+ *
+ * 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: McpSetting | undefined, port?: number): ConnectionMeta['mcp'];
+//#endregion
+export { resolveBasePath as a, resolveMcpConnectionMeta as c, normalizeBasePath as i, ResolvedMcpConfig as n, resolveDevServerPort as o, loadAutoMcpAdapter as r, resolveMcpConfig as s, ResolveDevServerPortOptions as t };

package/dist/_shared-U8D-xzrp.mjs

@@ -0,0 +1,115 @@
+import "./constants.mjs";
+import { r as importServicePackage } from "./services-install-Ben4yh52.mjs";
+import { n as getPort } from "./dist-CZXfGEkd.mjs";
+import { cleanDoubleSlashes, withLeadingSlash, withTrailingSlash, withoutLeadingSlash } from "ufo";
+//#region src/node/import-runtime-module.ts
+/**
+* Resolve and import a package at runtime without adding it to a consumer's
+* bundle graph. First-party adapters use this for modules whose code is
+* needed only when the matching feature is enabled (optional peers, and the
+* MCP adapter with the SDK behind it).
+*
+* @internal
+*/
+async function importRuntimeModule(specifier) {
+	return await importServicePackage(specifier, [import.meta.url]);
+}
+//#endregion
+//#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 an *explicit* `mcp` setting into a fully-resolved config, or
+* `undefined` when the MCP route is disabled. `'auto'` also resolves to
+* `undefined` here: whether it mounts depends on the live agent surface,
+* which only the mounting adapter can consult (through
+* {@link loadAutoMcpAdapter}) - static resolvers like
+* `resolveMcpConnectionMeta` treat it as unadvertisable.
+*
+* An enabled route trusts same-machine callers by default: the authorization
+* resolves to origin-only (`false`) unless the object config opts into a
+* bearer/callback identity check. An empty-string bearer is treated as no
+* bearer (origin-only) rather than a usable credential.
+*/
+function resolveMcpConfig(mcp) {
+	if (!mcp || mcp === "auto") return void 0;
+	if (mcp === true) return { authorization: false };
+	const authorization = typeof mcp.authorization === "string" && mcp.authorization.length === 0 ? false : mcp.authorization ?? false;
+	return {
+		...mcp.path !== void 0 ? { path: mcp.path } : {},
+		...mcp.allowedOrigins !== void 0 ? { allowedOrigins: mcp.allowedOrigins } : {},
+		authorization
+	};
+}
+/**
+* Resolve the `mcp: 'auto'` default at mount time: import the MCP adapter
+* when the devframe's agent surface is non-empty, or return `undefined`
+* (mount nothing) when the surface is empty - the zero-cost path, loading
+* no MCP code at all. The adapter (and the MCP SDK behind it) loads through
+* `importRuntimeModule`, so it never enters a consumer's bundle graph.
+*
+* Generic like `importRuntimeModule`: the caller names the module type
+* (`typeof import('devframe/adapters/mcp')`) so this shared helper carries
+* no type-level dependency on the MCP adapter.
+*/
+async function loadAutoMcpAdapter(agent) {
+	if (!agent.hasSurface()) return void 0;
+	return await importRuntimeModule("devframe/adapters/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. `'auto'` (the omitted default) resolves at mount time against
+* the live agent surface, so hand-rolled meta advertises it only for an
+* explicit setting; the adapters advertise the actually-mounted route
+* themselves.
+*
+* 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 { resolveMcpConfig as a, resolveDevServerPort as i, normalizeBasePath as n, resolveMcpConnectionMeta as o, resolveBasePath as r, importRuntimeModule as s, loadAutoMcpAdapter as t };

package/dist/adapters/build.d.mts

@@ -1,14 +1,14 @@
-import { F as DevframeDefinition, V as DevframeSnapshotRpcEntry, o as DevframeNodeContext } from "../context-CLF4-8Pp.mjs";
-import { o as StaticAssetsSource } from "../remote-assets-B13_vRkJ.mjs";
+import { F as DevframeDefinition, V as DevframeSnapshotRpcEntry, o as DevframeNodeContext } from "../context-CHW4BZOj.mjs";
+import { o as StaticAssetsSource } from "../remote-assets-eBvSKZMS.mjs";
 //#region src/adapters/build.d.ts
 interface CreateBuildOptions {
   /** Output directory. Defaults to `dist-static`. */
   outDir?: string;
   /**
-   * Override the SPA dist to copy into `outDir` — a local directory or a
+   * 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.clientAssets` (or the deprecated
-   * `devframe.cli?.distDir`) — authors typically set this once on the
+   * `devframe.cli?.distDir`); authors typically set this once on the
    * definition itself.
    */
   distDir?: StaticAssetsSource;
@@ -21,7 +21,7 @@ interface CreateBuildOptions {
   /**
    * Proceed even when the definition declares `capabilities.build: false`.
    * `createCac` already skips registering the `build` subcommand for such
-   * a definition — this only matters for a caller invoking `createBuild`
+   * a definition; this only matters for a caller invoking `createBuild`
    * directly, bypassing the CLI.
    */
   force?: boolean;
@@ -34,7 +34,7 @@ interface CreateBuildOptions {
  *   - 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`. The
- *     output is mount-path agnostic — the same bundle works at `/`,
+ *     output is mount-path agnostic, so the same bundle works at `/`,
  *     `/devframe/`, or any base, no rewriting required.
  */
 declare function createBuild(d: DevframeDefinition, options?: CreateBuildOptions): Promise<void>;

package/dist/adapters/build.mjs

@@ -1,17 +1,15 @@
-import { s as colors } from "../nostics-CzECRXpE.mjs";
-import { n as strictJsonStringify } from "../serialization-BGzEwAdr.mjs";
-import { t as resolveClientAssets } from "../client-assets-C7SXgTWY.mjs";
-import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
-import { t as collectStaticRpcDump } from "../static-DV_qUSRS.mjs";
-import { n as structuredCloneStringify } from "../structured-clone-CbAV5rFI.mjs";
-import { t as diagnostics } from "../diagnostics-BXWW3VK-.mjs";
-import { t as createHostContext } from "../context-omlma_1n.mjs";
-import { t as resolveStaticAssetsSource } from "../remote-assets-DezQmPQU.mjs";
-import { t as createH3DevframeHost } from "../host-h3-fRbF9yor.mjs";
+import { s as colors } from "../nostics-D0PvLZsn.mjs";
+import { t as resolveClientAssets } from "../client-assets-DNdhagGm.mjs";
+import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
+import { n as collectStaticRpcDump, t as writeStaticRpcDump } from "../write-BuLCrn9h.mjs";
+import { t as diagnostics } from "../diagnostics-DZA6KQ_Z.mjs";
+import { t as createHostContext } from "../context-B29Oh0oA.mjs";
+import { t as resolveStaticAssetsSource } from "../remote-assets-DMFzLSoH.mjs";
+import { t as createH3DevframeHost } from "../host-h3-BROI6SQ4.mjs";
+import fs from "node:fs/promises";
+import { resolve } from "pathe";
 import process from "node:process";
-import { dirname, resolve } from "pathe";
 import { existsSync } from "node:fs";
-import fs$1 from "node:fs/promises";
 //#region src/adapters/build.ts
 /**
 * Produce a self-contained static deploy of a devframe:
@@ -21,7 +19,7 @@ import fs$1 from "node:fs/promises";
 *   - 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`. The
-*     output is mount-path agnostic — the same bundle works at `/`,
+*     output is mount-path agnostic, so the same bundle works at `/`,
 *     `/devframe/`, or any base, no rewriting required.
 */
 async function createBuild(d, options = {}) {
@@ -29,20 +27,13 @@ async function createBuild(d, options = {}) {
 	const outDir = resolve(options.outDir ?? "dist-static");
 	const distSource = options.distDir ?? resolveClientAssets(d);
 	if (!distSource) throw new Error(`[devframe] createBuild: no client assets for "${d.id}". Set \`clientAssets\` 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 });
+	if (existsSync(outDir)) await fs.rm(outDir, { recursive: true });
+	await fs.mkdir(outDir, { recursive: true });
 	const host = createH3DevframeHost({
 		origin: "http://localhost",
 		appName: d.id
 	});
-	const resolved = resolveStaticAssetsSource(distSource, host.getStorageDir("project"), d.importMetaUrl);
-	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);
-	}
+	await materializeSpa(resolveStaticAssetsSource(distSource, host.getStorageDir("project"), d.importMetaUrl), outDir);
 	const ctx = await createHostContext({
 		cwd: process.cwd(),
 		mode: "build",
@@ -53,24 +44,30 @@ async function createBuild(d, options = {}) {
 	await ctx.services.ready();
 	await d.setup(ctx);
 	applySnapshotRpc(ctx, d.rpc?.snapshot);
-	await fs$1.mkdir(resolve(outDir, DEVFRAME_RPC_DUMP_DIRNAME), { recursive: true });
+	await writeConnectionMeta(ctx, outDir);
+	console.log(colors.cyan`[devframe] writing RPC dump to ${resolve(outDir, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME)}`);
+	const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx);
+	await writeStaticRpcDump(dump, outDir, { pretty: options.pretty });
+	console.log(colors.green`[devframe] built "${d.id}" -> ${outDir}`);
+}
+/** Copy a local SPA dist, or materialize a remote assets source, into `outDir`. */
+async function materializeSpa(resolved, outDir) {
+	if (typeof resolved === "string") {
+		console.log(colors.cyan`[devframe] copying SPA from ${resolved} -> ${outDir}`);
+		await fs.cp(resolved, outDir, { recursive: true });
+		return;
+	}
+	console.log(colors.cyan`[devframe] materializing SPA from ${resolved.assets.package}@${resolved.assets.version} -> ${outDir}`);
+	await resolved.materialize(outDir);
+}
+/** Write `__connection.json` with the JSON-serializable method allow-list. */
+async function writeConnectionMeta(ctx, outDir) {
 	const jsonSerializableMethods = [];
 	for (const def of ctx.rpc.definitions.values()) if (def.jsonSerializable === true) jsonSerializableMethods.push(def.name);
-	await fs$1.writeFile(resolve(outDir, DEVFRAME_CONNECTION_META_FILENAME), JSON.stringify({
+	await fs.writeFile(resolve(outDir, DEVFRAME_CONNECTION_META_FILENAME), JSON.stringify({
 		backend: "static",
 		jsonSerializableMethods
 	}, null, 2), "utf-8");
-	console.log(colors.cyan`[devframe] writing RPC dump to ${resolve(outDir, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME)}`);
-	const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx);
-	const indent = options.pretty ? 2 : void 0;
-	for (const [filepath, file] of Object.entries(dump.files)) {
-		const fullpath = resolve(outDir, filepath);
-		await fs$1.mkdir(dirname(fullpath), { recursive: true });
-		const text = file.serialization === "structured-clone" ? structuredCloneStringify(file.data) : strictJsonStringify(file.data, file.fnName);
-		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");
-	console.log(colors.green`[devframe] built "${d.id}" -> ${outDir}`);
 }
 /**
 * Attach a `dump` to each {@link DevframeRpcOptions.snapshot} target so the

package/dist/adapters/cac.d.mts

@@ -1,10 +1,21 @@
-import { Dt as parseCliFlags, Et as defineCliFlags, F as DevframeDefinition, Tt as InferCliFlags, wt as CliFlagsSchema } from "../context-CLF4-8Pp.mjs";
+import { Dt as InferCliFlags, Et as CliFlagsSchema, F as DevframeDefinition, Ot as defineCliFlags, kt as parseCliFlags, q as McpSetting } from "../context-CHW4BZOj.mjs";
 import { CAC } from "cac";
 import { H3 } from "h3";
 //#region src/adapters/cac.d.ts
 interface CreateCacOptions {
   /** Default port for `dev` (default: 9999). */
   defaultPort?: number;
+  /**
+   * Expose a route-based MCP server alongside the dev server, speaking the
+   * MCP Streamable-HTTP transport at `<base>__mcp`. Whether to expose MCP is
+   * a hosting decision made at the CLI assembly stage, so it lives here rather
+   * than on the definition. When unset, falls back to the definition's
+   * deprecated `cli.mcp`, then to the `'auto'` default (mount once the agent
+   * surface is non-empty). See {@link McpSetting}.
+   *
+   * The `--mcp` / `--no-mcp` flags override this per run.
+   */
+  mcp?: McpSetting;
   /**
    * Final CAC hook invoked after devframe's built-in subcommands and
    * after the definition's `cli.configure`. Use this to add app-level

package/dist/adapters/cac.mjs

@@ -1,13 +1,12 @@
-import { s as colors } from "../nostics-CzECRXpE.mjs";
-import { r as resolveDevServerPort } from "../_shared-BM3PdYli.mjs";
-import { a as importRuntimeModule } from "../instance-shell-CpVW4zG0.mjs";
+import { s as colors } from "../nostics-D0PvLZsn.mjs";
+import { i as resolveDevServerPort, s as importRuntimeModule } from "../_shared-U8D-xzrp.mjs";
 import { createBuild } from "./build.mjs";
-import { t as createDevServer } from "../dev-CzkPCJwi.mjs";
+import { t as createDevServer } from "../dev-CRYHx7iG.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
+* Identity helper that preserves the literal schema-map type; use this
 * so `InferCliFlags<typeof myFlags>` resolves to the right object shape.
 *
 * ```ts
@@ -96,7 +95,7 @@ function createCac(d, options = {}) {
 	const defaultHost = d.cli?.host ?? "localhost";
 	const command = d.cli?.command ?? d.id;
 	const cli = cac$1(command);
-	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)");
+	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", "Force the MCP route on (use --no-mcp to disable; default mounts it once agent tools exist)");
 	if (d.cli?.flags) for (const [key, schema] of Object.entries(d.cli.flags)) {
 		const optionName = flagKeyToOption(key);
 		const description = schema.description ?? "";
@@ -110,7 +109,7 @@ function createCac(d, options = {}) {
 			host,
 			defaultPort
 		});
-		const mcp = flags.mcp;
+		const mcp = flags.mcp ?? options.mcp;
 		await createDevServer(d, {
 			host,
 			port,
@@ -129,6 +128,7 @@ function createCac(d, options = {}) {
 		const { createMcpServer } = await importRuntimeModule("devframe/adapters/mcp");
 		await createMcpServer(d, {
 			transport: "stdio",
+			/** Deliberately go to stderr: stdout is the MCP transport. */
 			onReady: ({ transport }) => {
 				console.error(`[devframe] "${d.id}" MCP server ready (${transport})`);
 			}
@@ -150,7 +150,7 @@ 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}`);
+		for (const issue of issues) console.error(colors.red`[devframe] invalid flag: ${issue}`);
 		process.exit(1);
 	}
 	return flags;

package/dist/adapters/dev.d.mts

@@ -1,8 +1,8 @@
-import { d as DevframeRpcConnection, n as WsOriginRegistry, u as DevframeNodeRpcSessionMeta } from "../ws-server-VyHlanzy.mjs";
-import { Ct as DevframeAuthHandler, F as DevframeDefinition, G as McpRouteOptions, U as DevframeSseOptions, W as DevframeWsOptions, s as DevframeNodeRpcSession } from "../context-CLF4-8Pp.mjs";
-import { o as StaticAssetsSource } from "../remote-assets-B13_vRkJ.mjs";
-import { c as StartedServer } from "../instance-shell-Tcp5hGoq.mjs";
-import { a as resolveMcpConnectionMeta, i as resolveDevServerPort, t as ResolveDevServerPortOptions } from "../_shared-mtXpcJIv.mjs";
+import { c as DevframeNodeRpcSessionMeta, l as DevframeRpcConnection, n as WsOriginRegistry } from "../ws-server-D2nv68Hg.mjs";
+import { F as DevframeDefinition, Tt as DevframeAuthHandler, U as DevframeSseOptions, W as DevframeWsOptions, q as McpSetting, s as DevframeNodeRpcSession } from "../context-CHW4BZOj.mjs";
+import { o as StaticAssetsSource } from "../remote-assets-eBvSKZMS.mjs";
+import { c as StartedServer } from "../instance-shell-DZipaP9k.mjs";
+import { c as resolveMcpConnectionMeta, o as resolveDevServerPort, t as ResolveDevServerPortOptions } from "../_shared-CCzf9Hub.mjs";
 import { H3 } from "h3";
 //#region src/adapters/dev.d.ts
 interface CreateDevServerOptions {
@@ -23,7 +23,7 @@ interface CreateDevServerOptions {
   /**
    * Override the definition's `clientAssets` (or deprecated `cli.distDir`).
    * When neither this option nor the definition's client assets are set, the
-   * dev server runs in **bridge mode** — only `__connection.json` and the WS
+   * 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 `devframeViteBridge` from
    * `@devframes/vite`).
@@ -37,7 +37,7 @@ 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. Pass `false` to serve no WebSocket at all —
+   * port, or a remote origin. Pass `false` to serve no WebSocket at all;
    * clients connect over the SSE endpoint instead (`backend: 'sse'`).
    */
   ws?: DevframeWsOptions | false;
@@ -49,7 +49,7 @@ interface CreateDevServerOptions {
    */
   allowedOrigins?: readonly string[] | WsOriginRegistry | false;
   /**
-   * Override the SSE RPC endpoint control (`def.cli?.sse`) — enabled by
+   * 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.
    */
@@ -71,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
+   * choice for a **hosted** deployment where the host manages auth; see
    * {@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
@@ -81,11 +81,11 @@ interface CreateDevServerOptions {
   auth?: boolean | DevframeAuthHandler;
   /**
    * Expose a route-based MCP server on the dev server (Streamable-HTTP).
-   * Overrides `def.cli?.mcp`; `undefined` falls through to it. `false`
-   * disables the route regardless of the definition default. See
-   * {@link McpRouteOptions}.
+   * Overrides `def.cli?.mcp`; `undefined` falls through to it, then to the
+   * `'auto'` default (mount once the agent surface is non-empty). `false`
+   * disables the route regardless. See {@link McpSetting}.
    */
-  mcp?: boolean | McpRouteOptions;
+  mcp?: McpSetting;
   /**
    * Called once per new RPC connection, right after its session is created.
    * Forwarded verbatim to the underlying transport binding.
@@ -99,7 +99,7 @@ interface CreateDevServerOptions {
   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.
+   * otherwise, so wire this if you want a startup banner.
    */
   onReady?: (info: {
     origin: string;
@@ -108,20 +108,20 @@ interface CreateDevServerOptions {
   }) => void | Promise<void>;
   /**
    * Proceed even when the definition declares `capabilities.dev: false`.
-   * `createDevServer` otherwise refuses such a definition (`DF0058`) — this
+   * `createDevServer` otherwise refuses such a definition (`DF0058`); this
    * only matters for a caller invoking it directly, bypassing the CLI.
    */
   force?: boolean;
 }
 /**
- * Start a devframe dev server for a {@link DevframeDefinition} —
+ * Start a devframe dev server for a {@link DevframeDefinition}:
  * h3 + WebSocket RPC + (optionally) the author's SPA mounted at the
  * resolved base path.
  *
  * When `distDir` is omitted (and the definition's client assets are unset) the
  * 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
+ * hosted elsewhere (e.g. by a parent Vite/Nuxt dev server); see
  * `devframeViteBridge` from `@devframes/vite`.
  *
  * Returns the underlying {@link StartedServer} handle so callers can

package/dist/adapters/dev.mjs

@@ -1,3 +1,3 @@
-import { i as resolveMcpConnectionMeta, r as resolveDevServerPort } from "../_shared-BM3PdYli.mjs";
-import { t as createDevServer } from "../dev-CzkPCJwi.mjs";
+import { i as resolveDevServerPort, o as resolveMcpConnectionMeta } from "../_shared-U8D-xzrp.mjs";
+import { t as createDevServer } from "../dev-CRYHx7iG.mjs";
 export { createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };

package/dist/adapters/embedded.d.mts

@@ -1,4 +1,4 @@
-import { F as DevframeDefinition, o as DevframeNodeContext } from "../context-CLF4-8Pp.mjs";
+import { F as DevframeDefinition, o as DevframeNodeContext } from "../context-CHW4BZOj.mjs";
 //#region src/adapters/embedded.d.ts
 interface CreateEmbeddedOptions {
   /** Target context the devframe is registered into. Required. */