devframe 0.7.15 → 0.8.0

package/bin/devframe.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import process from 'node:process'
+import { runDevframeCli } from '../dist/cli/main.mjs'
+
+runDevframeCli().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/dist/adapters/build.d.mts

@@ -1,4 +1,4 @@
-import { r as DevframeDefinition } from "../devframe-BADsX91-.mjs";
+import { r as DevframeDefinition } from "../devframe-Dsjn_Xtq.mjs";
 //#region src/adapters/build.d.ts
 interface CreateBuildOptions {
   /** Output directory. Defaults to `dist-static`. */
@@ -17,6 +17,13 @@ interface CreateBuildOptions {
    * minified. Set `true` when you need to diff / read the dumps by hand.
    */
   pretty?: boolean;
+  /**
+   * 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`
+   * directly, bypassing the CLI.
+   */
+  force?: boolean;
 }
 /**
  * Produce a self-contained static deploy of a devframe:

package/dist/adapters/build.mjs

@@ -1,9 +1,10 @@
-import { t as collectStaticRpcDump } from "../dump-Cz7yVvsB.mjs";
+import { t as collectStaticRpcDump } from "../dump-CgZShDRB.mjs";
 import { n as colors } from "../diagnostics-reporter-CsIG85Q5.mjs";
 import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
-import { n as strictJsonStringify } from "../serialization-DpLXCy13.mjs";
+import { n as strictJsonStringify } from "../serialization-C8Mnw9hK.mjs";
 import { n as structuredCloneStringify } from "../structured-clone-CbAV5rFI.mjs";
-import { n as createHostContext, t as createH3DevframeHost } from "../host-h3-SjwRTwkE.mjs";
+import { n as createHostContext, t as createH3DevframeHost } from "../host-h3-Kz7t5Xab.mjs";
+import { t as diagnostics } from "../diagnostics-B5-qHeqD.mjs";
 import { n as resolveBasePath } from "../_shared-bWRzeSa0.mjs";
 import { existsSync } from "node:fs";
 import { dirname, resolve } from "pathe";
@@ -24,6 +25,7 @@ import fs$1 from "node:fs/promises";
 *     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.`);

package/dist/adapters/cac.d.mts

@@ -1,4 +1,4 @@
-import { Ft as parseCliFlags, Mt as CliFlagsSchema, Nt as InferCliFlags, Pt as defineCliFlags, r as DevframeDefinition } from "../devframe-BADsX91-.mjs";
+import { Ft as InferCliFlags, It as defineCliFlags, Lt as parseCliFlags, Pt as CliFlagsSchema, r as DevframeDefinition } from "../devframe-Dsjn_Xtq.mjs";
 import { CAC } from "cac";
 import { H3 } from "h3";
 //#region src/adapters/cac.d.ts

package/dist/adapters/cac.mjs

@@ -1,2 +1,2 @@
-import { n as defineCliFlags, r as parseCliFlags, t as createCac } from "../cac-CjF0haJ6.mjs";
+import { n as defineCliFlags, r as parseCliFlags, t as createCac } from "../cac-B-R_tDGJ.mjs";
 export { createCac, defineCliFlags, parseCliFlags };

package/dist/adapters/cli.d.mts

@@ -1,4 +1,4 @@
-import { Ft as parseCliFlags, Mt as CliFlagsSchema, Nt as InferCliFlags, Pt as defineCliFlags } from "../devframe-BADsX91-.mjs";
+import { Ft as InferCliFlags, It as defineCliFlags, Lt as parseCliFlags, Pt as CliFlagsSchema } from "../devframe-Dsjn_Xtq.mjs";
 import { CacHandle, CreateCacOptions, createCac } from "./cac.mjs";
 //#region src/adapters/cli.d.ts
 /** @deprecated Use `createCac` from `devframe/adapters/cac` instead. */

package/dist/adapters/cli.mjs

@@ -1,4 +1,4 @@
-import { n as defineCliFlags, r as parseCliFlags, t as createCac } from "../cac-CjF0haJ6.mjs";
+import { n as defineCliFlags, r as parseCliFlags, t as createCac } from "../cac-B-R_tDGJ.mjs";
 //#region src/adapters/cli.ts
 /** @deprecated Use `createCac` from `devframe/adapters/cac` instead. */
 const createCli = createCac;

package/dist/adapters/dev.d.mts

@@ -1,5 +1,5 @@
-import { _ as ConnectionMeta, d as McpRouteOptions, p as DevframeAuthHandler, r as DevframeDefinition, u as DevframeWsOptions } from "../devframe-BADsX91-.mjs";
-import { n as StartedServer } from "../server-Bu5iB3aV.mjs";
+import { _ as ConnectionMeta, d as McpRouteOptions, p as DevframeAuthHandler, r as DevframeDefinition, u as DevframeWsOptions } from "../devframe-Dsjn_Xtq.mjs";
+import { n as StartedServer } from "../server-VLQJouOO.mjs";
 import { H3 } from "h3";
 //#region src/adapters/dev.d.ts
 interface CreateDevServerOptions {

package/dist/adapters/dev.mjs

@@ -1,2 +1,2 @@
-import { n as resolveDevServerPort, r as resolveMcpConnectionMeta, t as createDevServer } from "../dev-OJFr4rx8.mjs";
+import { n as resolveDevServerPort, r as resolveMcpConnectionMeta, t as createDevServer } from "../dev-D4M7Veo7.mjs";
 export { createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };

package/dist/adapters/embedded.d.mts

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

package/dist/adapters/mcp.d.mts

@@ -1,5 +1,5 @@
-import { r as DevframeDefinition } from "../devframe-BADsX91-.mjs";
-import "@modelcontextprotocol/sdk/server/index.js";
+import { b as DevframeNodeContext, r as DevframeDefinition } from "../devframe-Dsjn_Xtq.mjs";
+import "@modelcontextprotocol/server";
 //#region src/adapters/mcp/build-server.d.ts
 interface CreateMcpServerOptions {
   /**
@@ -37,4 +37,46 @@ interface McpServerHandle {
  */
 declare function createMcpServer(definition: DevframeDefinition, options?: CreateMcpServerOptions): Promise<McpServerHandle>;
 //#endregion
-export { type CreateMcpServerOptions, type McpServerHandle, createMcpServer };
+//#region src/adapters/mcp/fetch.d.ts
+interface CreateMcpFetchHandlerOptions {
+  /** Name reported in the MCP handshake. */
+  serverName: string;
+  /** Version reported in the MCP handshake. */
+  serverVersion: string;
+  /** Expose shared-state keys as MCP resources — see `buildMcpServerFromContext`. */
+  exposeSharedState: boolean | ((key: string) => boolean);
+  /**
+   * Origin allow-list beyond the loopback default. `false` disables the
+   * origin gate entirely. Default: loopback-only (mirrors the WS transport).
+   */
+  allowedOrigins?: readonly string[] | false;
+}
+interface McpFetchHandler {
+  /**
+   * WHATWG-`fetch` handler for the MCP Streamable-HTTP endpoint. Hand every
+   * method (POST/GET/DELETE) on the endpoint's path to it — routing by path
+   * is the host's job.
+   */
+  fetch: (request: Request) => Promise<Response>;
+  /** Tear down every live MCP session (closes servers, drops subscriptions). */
+  dispose: () => Promise<void>;
+}
+/**
+ * Build a framework-agnostic MCP Streamable-HTTP endpoint over a devframe
+ * context: a web-standard `Request → Response` handler any host can mount —
+ * h3 (see `mountMcpHttp`), a Next.js App Router route, or any other
+ * fetch-shaped server.
+ *
+ * Each MCP session gets its own {@link WebStandardStreamableHTTPServerTransport}
+ * and MCP server (built from the shared, live `ctx` via
+ * `buildMcpServerFromContext`), correlated by the `Mcp-Session-Id` header: an
+ * `initialize` POST spins up a session; later requests route to it; a `DELETE`
+ * (or client disconnect) tears it down. The origin gate applies devframe's
+ * loopback-default DNS-rebinding protection (identical semantics to the WS
+ * upgrade's `isAllowedOrigin`).
+ *
+ * @experimental
+ */
+declare function createMcpFetchHandler(ctx: DevframeNodeContext, options: CreateMcpFetchHandlerOptions): McpFetchHandler;
+//#endregion
+export { type CreateMcpFetchHandlerOptions, type CreateMcpServerOptions, type McpFetchHandler, type McpServerHandle, createMcpFetchHandler, createMcpServer };

package/dist/adapters/mcp.mjs

@@ -1,2 +1,2 @@
-import { n as createMcpServer } from "../build-server-cANnMwg0.mjs";
-export { createMcpServer };
+import { n as createMcpServer, t as createMcpFetchHandler } from "../fetch-BZyK4v6W.mjs";
+export { createMcpFetchHandler, createMcpServer };

package/dist/agent-tool-name-C3b5vEwJ.mjs

@@ -0,0 +1,34 @@
+//#region src/utils/agent-tool-name.ts
+/**
+* Maximum tool-name length several MCP clients enforce (the Anthropic API
+* pattern is `^[a-zA-Z0-9_-]{1,128}$`).
+*/
+const MAX_TOOL_NAME_LENGTH = 128;
+/**
+* Derive the wire-safe agent tool name for an internal tool id.
+*
+* Devframe tool ids are colon-namespaced — `devframe:<area>:<fn>` for
+* built-ins, `devframes:plugin:<slug>:<fn>` for plugin RPCs, and hub
+* command ids for command-derived tools. MCP clients constrain tool names
+* to `^[a-zA-Z0-9_-]{1,128}$`, so the agent/MCP boundary derives the wire
+* name automatically: every run of characters outside `[a-zA-Z0-9_-]`
+* becomes a single `_`, truncated to 128 characters. Internal ids never
+* change — resolution back to the id happens at the boundary.
+*
+* ```
+* devframe:state:read          → devframe_state_read
+* devframes:plugin:git:status  → devframes_plugin_git_status
+* ```
+*
+* A plain string transform with no node dependency, so browser-side UIs
+* that display a tool's id (e.g. the inspect plugin's agent view) can
+* import it too and show the name a client actually calls.
+*
+* @experimental The agent-native surface is experimental and may change
+* without a major version bump until it stabilizes.
+*/
+function toAgentToolName(id) {
+	return id.replace(/[^\w-]+/g, "_").slice(0, MAX_TOOL_NAME_LENGTH);
+}
+//#endregion
+export { toAgentToolName as t };

package/dist/{cac-CjF0haJ6.mjs → cac-B-R_tDGJ.mjs}

@@ -1,9 +1,8 @@
 import { n as colors } from "./diagnostics-reporter-CsIG85Q5.mjs";
 import { createBuild } from "./adapters/build.mjs";
-import { n as resolveDevServerPort, t as createDevServer } from "./dev-OJFr4rx8.mjs";
+import { n as resolveDevServerPort, t as createDevServer } from "./dev-D4M7Veo7.mjs";
 import process from "node:process";
-import cac from "cac";
-import { safeParse } from "valibot";
+import cac$1 from "cac";
 //#region src/adapters/flags.ts
 /**
 * Identity helper that preserves the literal schema-map type — use this
@@ -29,10 +28,12 @@ function defineCliFlags(flags) {
 	return flags;
 }
 /**
-* Best-effort probe of a valibot schema to decide whether the
-* corresponding CAC option takes a value. Unwraps `optional` / `nullable`
-* / `nullish` / `default` / `pipe` wrappers then matches on the inner
-* type's kind.
+* 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;
@@ -46,7 +47,7 @@ function getSchemaKind(schema) {
 			current = current.pipe[0];
 			continue;
 		}
-		return kind;
+		return kind ?? "unknown";
 	}
 	return "unknown";
 }
@@ -54,14 +55,18 @@ function getSchemaKind(schema) {
 function isBooleanFlag(schema) {
 	return getSchemaKind(schema) === "boolean";
 }
-/** Validate and coerce the raw cac-parsed bag against a {@link CliFlagsSchema}. */
+/** 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 = safeParse(fieldSchema, raw[key]);
-		if (result.success) flags[key] = result.output;
-		else issues.push(`--${toKebab(key)}: ${result.issues.map((i) => i.message).join(", ")}`);
+		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 ? {
@@ -87,7 +92,7 @@ function flagKeyToOption(camel) {
 function createCac(d, options = {}) {
 	const defaultPort = options.defaultPort ?? d.cli?.port ?? 9999;
 	const defaultHost = d.cli?.host ?? "localhost";
-	const cli = cac(d.cli?.command ?? d.id);
+	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) [experimental]");
 	if (d.cli?.flags) for (const [key, schema] of Object.entries(d.cli.flags)) {
 		const optionName = flagKeyToOption(key);
@@ -111,7 +116,7 @@ function createCac(d, options = {}) {
 			onReady: options.onReady
 		});
 	});
-	cli.command("build", "Build a self-contained static deploy of the devframe").option("--out-dir <outDir>", "Output directory", { default: "dist-static" }).option("--base <base>", "URL base", { default: "/" }).option("--pretty", "Pretty-print dump JSON (larger on disk)").action(async (flags) => {
+	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("--base <base>", "URL base", { default: "/" }).option("--pretty", "Pretty-print dump JSON (larger on disk)").action(async (flags) => {
 		await createBuild(d, {
 			outDir: flags.outDir,
 			base: flags.base,

package/dist/cli/main.d.mts

@@ -0,0 +1,11 @@
+//#region src/cli/main.d.ts
+/**
+ * The `devframe` bin — the framework's own CLI, distinct from the per-app
+ * CLI shells authors build with `createCac(definition)`. It hosts the
+ * app-independent commands; today that is `connect`, the MCP connector.
+ *
+ * @experimental
+ */
+declare function runDevframeCli(argv?: string[]): Promise<void>;
+//#endregion
+export { runDevframeCli };

package/dist/cli/main.mjs

@@ -0,0 +1,283 @@
+import { t as diagnostics } from "../diagnostics-B5-qHeqD.mjs";
+import { n as probeDevframeOrigin, t as listLiveDevframeInstances } from "../instance-registry-D6fxYu36.mjs";
+import { t as toAgentToolName } from "../agent-tool-name-C3b5vEwJ.mjs";
+import { Diagnostic } from "nostics";
+import process from "node:process";
+import { joinURL } from "ufo";
+import { cac } from "cac";
+//#region src/cli/connect.ts
+const INDEX_TOOL = toAgentToolName("devframe:connect:list-instances");
+const CALL_TOOL = toAgentToolName("devframe:connect:call-tool");
+const MCP_DISABLED_HINT = "This instance runs without an MCP route. Restart it with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again.";
+const GATEWAY_TOOLS = [{
+	name: INDEX_TOOL,
+	title: "Discover running devframes",
+	description: "Discover every running devframe dev server on this machine and list each one's MCP tools. Call this FIRST, before assuming which devtools are available — the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.",
+	inputSchema: {
+		type: "object",
+		properties: {}
+	},
+	annotations: {
+		readOnlyHint: true,
+		destructiveHint: false
+	}
+}, {
+	name: CALL_TOOL,
+	title: "Call a devframe tool",
+	description: "Invoke one MCP tool on one running devframe instance discovered via the list-instances tool. Pass the instance's port, the tool name, and the tool's arguments object.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			port: {
+				type: "number",
+				description: "The instance's port, from the list-instances tool."
+			},
+			tool: {
+				type: "string",
+				description: "Tool name, from the instance's tool list."
+			},
+			args: {
+				type: "object",
+				description: "Arguments object for the tool. Omit for zero-argument tools."
+			}
+		},
+		required: ["port", "tool"],
+		additionalProperties: false
+	}
+}];
+/**
+* Start the devframe MCP connector on stdio: a thin discovery + proxy server
+* in the shape Vercel's next-devtools-mcp (https://github.com/vercel/next-devtools-mcp)
+* validated — credit due there for the architecture this connector follows.
+* It exposes two gateway tools —
+* `devframe_connect_list-instances` (discover running devframe instances via
+* the instance registry and list each one's MCP tools) and
+* `devframe_connect_call-tool` (invoke one tool on one instance over its
+* Streamable-HTTP endpoint) — and holds no domain knowledge of its own.
+*
+* @experimental
+*/
+async function startConnectServer(options = {}) {
+	const sdk = await importSdk();
+	const server = new sdk.Server({
+		name: "devframe-connect",
+		version: "0.0.0"
+	}, { capabilities: { tools: {} } });
+	server.setRequestHandler("tools/list", async () => ({ tools: GATEWAY_TOOLS }));
+	server.setRequestHandler("tools/call", async (request) => {
+		const { name, arguments: args } = request.params;
+		try {
+			if (name === INDEX_TOOL) return textResult(await index(sdk, options));
+			if (name === CALL_TOOL) return textResult(await call(sdk, options, args ?? {}));
+			return errorResult({
+				message: `unknown tool "${name}"`,
+				fix: `Call ${INDEX_TOOL} or ${CALL_TOOL}.`
+			});
+		} catch (error) {
+			return errorResult(toErrorPayload(error));
+		}
+	});
+	const transport = new sdk.StdioServerTransport();
+	await server.connect(transport);
+	return { stop: async () => {
+		await server.close();
+	} };
+}
+async function importSdk() {
+	try {
+		const [serverMod, stdioMod, clientMod] = await Promise.all([
+			import("@modelcontextprotocol/server"),
+			import("@modelcontextprotocol/server/stdio"),
+			import("@modelcontextprotocol/client")
+		]);
+		return {
+			Server: serverMod.Server,
+			StdioServerTransport: stdioMod.StdioServerTransport,
+			Client: clientMod.Client,
+			StreamableHTTPClientTransport: clientMod.StreamableHTTPClientTransport
+		};
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw diagnostics.DF0046({
+			reason,
+			cause: error
+		});
+	}
+}
+/** Discover instances: registry (prune-on-read) + explicit port probes. */
+async function index(sdk, options) {
+	const { live } = await listLiveDevframeInstances({
+		instancesDir: options.instancesDir,
+		timeoutMs: options.timeoutMs
+	});
+	const records = [...live];
+	for (const port of options.ports ?? []) {
+		if (records.some((r) => r.port === port)) continue;
+		const probed = await probePort(port, options.timeoutMs);
+		if (probed) records.push(probed);
+	}
+	const instances = await Promise.all(records.map(async (record) => {
+		const { mcp, ...rest } = record;
+		const entry = {
+			...rest,
+			mcp: null
+		};
+		if (!mcp) {
+			entry.hint = MCP_DISABLED_HINT;
+			return entry;
+		}
+		const url = `${record.origin}${mcp.path}`;
+		try {
+			entry.mcp = {
+				url,
+				tools: await listInstanceTools(sdk, url)
+			};
+		} catch (error) {
+			entry.mcp = {
+				url,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+		return entry;
+	}));
+	return {
+		instances,
+		...instances.length === 0 ? { hint: "No running devframe instances found. Start a devframe dev server (with --mcp for tools), or pass --port <n> to devframe connect if the instance predates the registry." } : {}
+	};
+}
+/**
+* Probe an explicit port for a devframe serving `__connection.json` at `/`,
+* reusing the registry's origin-candidate probe (a `localhost`-bound server
+* may listen on either address family).
+*/
+async function probePort(port, timeoutMs) {
+	const probed = await probeDevframeOrigin(`http://localhost:${port}`, "/", timeoutMs);
+	if (!probed) return null;
+	const mcpPath = probed.meta.mcp ? joinURL("/", probed.meta.mcp.path) : null;
+	return {
+		pid: -1,
+		port,
+		origin: probed.origin,
+		basePath: "/",
+		id: `port-${port}`,
+		rootDir: "",
+		mcp: mcpPath ? { path: mcpPath } : null,
+		startedAt: 0
+	};
+}
+async function listInstanceTools(sdk, url) {
+	return withInstanceClient(sdk, url, async (client) => {
+		return (await client.listTools()).tools.map((tool) => ({
+			name: tool.name,
+			description: tool.description
+		}));
+	});
+}
+async function call(sdk, options, args) {
+	if (typeof args.port !== "number" || typeof args.tool !== "string") throw diagnostics.DF0049();
+	const { live } = await listLiveDevframeInstances({
+		instancesDir: options.instancesDir,
+		timeoutMs: options.timeoutMs
+	});
+	const record = live.find((r) => r.port === args.port) ?? await probePort(args.port, options.timeoutMs);
+	if (!record) throw diagnostics.DF0050({ port: args.port });
+	if (!record.mcp) throw diagnostics.DF0051({ port: args.port });
+	return withInstanceClient(sdk, `${record.origin}${record.mcp.path}`, async (client) => {
+		const result = await client.callTool({
+			name: args.tool,
+			arguments: args.args ?? {}
+		});
+		return {
+			instance: {
+				id: record.id,
+				port: record.port
+			},
+			tool: args.tool,
+			isError: result.isError ?? false,
+			content: result.content,
+			...result.structuredContent ? { structuredContent: result.structuredContent } : {}
+		};
+	});
+}
+async function withInstanceClient(sdk, url, fn) {
+	const transport = new sdk.StreamableHTTPClientTransport(new URL(url));
+	const client = new sdk.Client({
+		name: "devframe-connect",
+		version: "0.0.0"
+	});
+	await client.connect(transport);
+	try {
+		return await fn(client);
+	} finally {
+		await client.close().catch(() => {});
+	}
+}
+function textResult(value) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(value, null, 2)
+	}] };
+}
+/**
+* Project a thrown value into the connector's structured error payload. A
+* nostics `Diagnostic` carries its code, `fix`, and docs URL across so the
+* calling agent gets the actionable next step.
+*/
+function toErrorPayload(error) {
+	if (error instanceof Diagnostic) return {
+		code: error.code,
+		message: error.message,
+		...error.fix ? { fix: error.fix } : {},
+		...error.docs ? { docs: error.docs } : {}
+	};
+	return {
+		message: error instanceof Error ? error.message : String(error),
+		...error && typeof error === "object" && "fix" in error && typeof error.fix === "string" ? { fix: error.fix } : {}
+	};
+}
+function errorResult(error) {
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: JSON.stringify({ error }, null, 2)
+		}]
+	};
+}
+/** Parse the repeatable `--port` flag value(s) from cac into numbers. */
+function parsePortsFlag(value) {
+	return (Array.isArray(value) ? value : value === void 0 ? [] : [value]).map((v) => Number(v)).filter((n) => Number.isInteger(n) && n > 0 && n < 65536);
+}
+/** Keep the connector process alive until the stdio transport closes it. */
+function keepAlive() {
+	process.stdin.resume();
+}
+//#endregion
+//#region src/cli/main.ts
+/**
+* The `devframe` bin — the framework's own CLI, distinct from the per-app
+* CLI shells authors build with `createCac(definition)`. It hosts the
+* app-independent commands; today that is `connect`, the MCP connector.
+*
+* @experimental
+*/
+async function runDevframeCli(argv = process.argv) {
+	const cli = cac("devframe");
+	cli.command("connect", "Run the devframe MCP connector on stdio (discovers running devframe dev servers and proxies their tools)").option("--port <port>", "Probe an explicit port besides the instance registry (repeatable)").option("--instances-dir <dir>", "Override the instance registry directory (default: ~/.devframe/instances, or $DEVFRAME_INSTANCES_DIR)").option("--timeout <ms>", "Probe timeout per instance in milliseconds", { default: 1e3 }).action(async (options) => {
+		await startConnectServer({
+			ports: parsePortsFlag(options.port),
+			instancesDir: options.instancesDir,
+			timeoutMs: options.timeout
+		});
+		keepAlive();
+	});
+	cli.help();
+	cli.parse(argv, { run: false });
+	if (!cli.matchedCommand) {
+		if (!cli.options.help) cli.outputHelp();
+		return;
+	}
+	await cli.runMatchedCommand();
+}
+//#endregion
+export { runDevframeCli };

package/dist/client/index.d.mts

@@ -1,9 +1,42 @@
-import { $ as DevframeRpcServerFunctions, F as ScopedSharedStates, I as SettingsForNamespace, J as RpcSharedStateHost, N as ScopedRpcFn, O as DevframeSettings, P as ScopedServerFunctions, Q as DevframeRpcClientFunctions, _ as ConnectionMeta, at as StreamReader, ht as SharedState, kt as EventEmitter, ot as StreamSink, q as RpcSharedStateGetOptions } from "../devframe-BADsX91-.mjs";
-import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-CrzNxXKq.mjs";
-import { C as RpcCacheManager, w as RpcCacheOptions } from "../index-DgsLFhZg.mjs";
-import { t as WsRpcChannelOptions } from "../ws-client-DSXiI2h7.mjs";
+import { $ as DevframeRpcServerFunctions, F as ScopedSharedStates, I as SettingsForNamespace, J as RpcSharedStateHost, N as ScopedRpcFn, O as DevframeSettings, P as ScopedServerFunctions, Q as DevframeRpcClientFunctions, _ as ConnectionMeta, at as StreamReader, ht as SharedState, jt as EventEmitter, ot as StreamSink, q as RpcSharedStateGetOptions } from "../devframe-Dsjn_Xtq.mjs";
+import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-CnJSgRVa.mjs";
+import { E as RpcCacheOptions, T as RpcCacheManager } from "../index-Dbw1p5ch.mjs";
+import { t as WsRpcChannelOptions } from "../ws-client-B6Tnr0ic.mjs";
 import { BirpcOptions, BirpcReturn } from "birpc";
 //#region src/client/connection.d.ts
+interface DevframeConnection {
+  /** Server-advertised transport and serialization metadata. */
+  connectionMeta: ConnectionMeta;
+  /**
+   * Absolute URL of the `__connection.json` that produced
+   * {@link connectionMeta}. Relative transport paths and side-car ports are
+   * resolved from this URL, rather than from an external viewer's location.
+   */
+  metaBaseUrl: string;
+  /** Previously issued bearer token, when the connection is already trusted. */
+  authToken?: string;
+}
+interface SetupDevframeConnectionOptions {
+  /** Reuse a complete connection prepared in another viewer or JavaScript realm. */
+  connection?: DevframeConnection;
+  /** Use a pre-known descriptor while deriving its source URL from `baseURL`. */
+  connectionMeta?: ConnectionMeta;
+  /** Base URL, or fallback list, used to locate `__connection.json`. */
+  baseURL?: string | string[];
+  /** Override the locally stored auth token. */
+  authToken?: string;
+}
+/**
+ * Return connection information previously prepared in this window or an
+ * accessible parent window.
+ */
+declare function getDevframeConnection(): DevframeConnection | undefined;
+/**
+ * Prepare the connection information shared by a devframe client and external
+ * viewers. Reuses an explicit or previously prepared connection before
+ * fetching `__connection.json` from the configured base URLs.
+ */
+declare function setupDevframeConnection(options?: SetupDevframeConnectionOptions): Promise<DevframeConnection>;
 /**
  * The connection lifecycle of a devframe client, as a single value a UI can
  * render from. Derived from the transport (WebSocket open/close/error) and the
@@ -183,9 +216,7 @@ interface RpcClientEvents {
    */
   'rpc:error': (error: Error, method: string) => void;
 }
-interface DevframeRpcClientOptions {
-  connectionMeta?: ConnectionMeta;
-  baseURL?: string | string[];
+interface DevframeRpcClientOptions extends SetupDevframeConnectionOptions {
   /**
    * The auth token to use for the client
    */
@@ -250,7 +281,12 @@ interface DevframeRpcClient {
    */
   readonly connectionError: Error | null;
   /**
-   * The connection meta
+   * The complete connection used by this client, including the metadata source
+   * URL external viewers use to resolve relative resources.
+   */
+  readonly connection: DevframeConnection;
+  /**
+   * The server-advertised connection metadata.
    */
   readonly connectionMeta: ConnectionMeta;
   /**
@@ -376,4 +412,4 @@ declare function createClientSettings<T extends Record<string, any> = Record<str
 //#region src/client/index.d.ts
 declare const connectDevframe: typeof getDevframeRpcClient;
 //#endregion
-export { DevframeClientRpcHost, DevframeConnectionError, DevframeConnectionErrorKind, DevframeConnectionStatus, DevframeRpcClient, DevframeRpcClientCall, DevframeRpcClientCallEvent, DevframeRpcClientCallOptional, DevframeRpcClientMode, DevframeRpcClientOptions, DevframeRpcContext, DevframeScopedClientContext, DevframeScopedClientRpc, DevframeScopedClientStreamingHost, RpcClientEvents, RpcStreamingClientHost, StreamingSubscribeOptions, authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeRpcClient, isCallableStatus, readOtpFromUrl };
+export { DevframeClientRpcHost, DevframeConnection, DevframeConnectionError, DevframeConnectionErrorKind, DevframeConnectionStatus, DevframeRpcClient, DevframeRpcClientCall, DevframeRpcClientCallEvent, DevframeRpcClientCallOptional, DevframeRpcClientMode, DevframeRpcClientOptions, DevframeRpcContext, DevframeScopedClientContext, DevframeScopedClientRpc, DevframeScopedClientStreamingHost, RpcClientEvents, RpcStreamingClientHost, SetupDevframeConnectionOptions, StreamingSubscribeOptions, authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeConnection, getDevframeRpcClient, isCallableStatus, readOtpFromUrl, setupDevframeConnection };