devframe 0.0.0 → 0.1.16

package/dist/adapters/mcp.d.mts

@@ -0,0 +1,39 @@
+import { r as DevtoolDefinition } from "../devtool-OJ3QW0ns.mjs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+
+//#region src/node/mcp/build-server.d.ts
+interface CreateMcpServerOptions {
+  /**
+   * Transport to use. Only `'stdio'` is implemented today; HTTP support
+   * is planned in a follow-up PR.
+   */
+  transport?: 'stdio';
+  /**
+   * Expose shared-state keys as MCP resources.
+   * - `true` (default) — every key the host publishes
+   * - `false` — none
+   * - `(key) => boolean` — filter
+   */
+  exposeSharedState?: boolean | ((key: string) => boolean);
+  /** Override the name reported in the MCP handshake. */
+  serverName?: string;
+  /** Override the version reported in the MCP handshake. Defaults to `definition.version ?? '0.0.0'`. */
+  serverVersion?: string;
+  /** Called once the transport is connected. */
+  onReady?: (info: {
+    transport: 'stdio';
+  }) => void;
+}
+interface McpServerHandle {
+  stop: () => Promise<void>;
+}
+/**
+ * Build an MCP server over the agent surface of a devtool definition.
+ * Currently supports `stdio` transport only.
+ *
+ * @experimental The agent-native surface is experimental and may change
+ * without a major version bump until it stabilizes.
+ */
+declare function createMcpServer(definition: DevtoolDefinition, options?: CreateMcpServerOptions): Promise<McpServerHandle>;
+//#endregion
+export { type CreateMcpServerOptions, type McpServerHandle, createMcpServer };

package/dist/adapters/mcp.mjs

@@ -0,0 +1,278 @@
+import { p as logger, t as createHostContext } from "../context-BrePWeyd.mjs";
+import process from "node:process";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { toJsonSchema } from "@valibot/to-json-schema";
+//#region src/node/mcp/to-json-schema.ts
+const FALLBACK_OBJECT_SCHEMA = Object.freeze({
+	type: "object",
+	additionalProperties: true
+});
+/**
+* Convert a valibot return schema to JSON Schema.
+* @internal
+*/
+function valibotReturnToJsonSchema(schema) {
+	if (!schema) return void 0;
+	try {
+		return toJsonSchema(schema);
+	} catch {
+		return FALLBACK_OBJECT_SCHEMA;
+	}
+}
+/**
+* Convert positional RPC args schemas to a single MCP-friendly object
+* schema. When the RPC declares `args: [v.object(...)]`, unwrap the
+* single-object schema directly (nicer agent UX than `{ arg0: {...} }`).
+*
+* Returns `undefined` when there are no args (the MCP SDK treats this
+* as `{ type: 'object', properties: {} }`).
+* @internal
+*/
+function valibotArgsToJsonSchema(args) {
+	if (!args || args.length === 0) return {
+		schema: {
+			type: "object",
+			properties: {}
+		},
+		unwrapped: false
+	};
+	if (args.length === 1) {
+		const inner = safeToJsonSchema(args[0]);
+		if (isObjectJsonSchema(inner)) return {
+			schema: inner,
+			unwrapped: true
+		};
+	}
+	const properties = {};
+	const required = [];
+	for (let i = 0; i < args.length; i++) {
+		const key = `arg${i}`;
+		properties[key] = safeToJsonSchema(args[i]);
+		required.push(key);
+	}
+	return {
+		schema: {
+			type: "object",
+			properties,
+			required,
+			additionalProperties: false
+		},
+		unwrapped: false
+	};
+}
+function safeToJsonSchema(schema) {
+	try {
+		return toJsonSchema(schema);
+	} catch {
+		return FALLBACK_OBJECT_SCHEMA;
+	}
+}
+function isObjectJsonSchema(value) {
+	return !!value && typeof value === "object" && value.type === "object";
+}
+//#endregion
+//#region src/node/mcp/build-server.ts
+/**
+* Wire an MCP {@link Server} to a devframe context. Returns the server
+* plus a disposal function for the subscriptions it sets up. The
+* transport is the caller's responsibility — `createMcpServer` connects
+* stdio; tests can connect an {@link InMemoryTransport} instead.
+*
+* @internal
+*/
+function buildMcpServerFromContext(ctx, options) {
+	const server = new Server({
+		name: options.serverName,
+		version: options.serverVersion
+	}, { capabilities: {
+		tools: { listChanged: true },
+		resources: { listChanged: true }
+	} });
+	registerToolHandlers(server, ctx);
+	registerResourceHandlers(server, ctx, options.exposeSharedState);
+	const notify = (method) => {
+		server.notification({ method }).catch(() => {});
+	};
+	const offManifest = ctx.agent.events.on("agent:manifest:changed", () => {
+		notify("notifications/tools/list_changed");
+		notify("notifications/resources/list_changed");
+	});
+	const offKeyAdded = ctx.rpc.sharedState.onKeyAdded(() => {
+		notify("notifications/resources/list_changed");
+	});
+	return {
+		server,
+		dispose: () => {
+			offManifest();
+			offKeyAdded();
+		}
+	};
+}
+/**
+* Build an MCP server over the agent surface of a devtool definition.
+* Currently supports `stdio` transport only.
+*
+* @experimental The agent-native surface is experimental and may change
+* without a major version bump until it stabilizes.
+*/
+async function createMcpServer(definition, options = {}) {
+	const transport = options.transport ?? "stdio";
+	if (transport !== "stdio") throw logger.DF0017({
+		transport,
+		reason: "Only stdio transport is supported in this release."
+	}).throw();
+	const ctx = await createHostContext({
+		cwd: process.cwd(),
+		mode: "dev",
+		host: {
+			mountStatic: () => {},
+			resolveOrigin: () => "mcp://devframe"
+		}
+	});
+	await definition.setup(ctx);
+	const { server, dispose } = buildMcpServerFromContext(ctx, {
+		serverName: options.serverName ?? `${definition.id} (devframe)`,
+		serverVersion: options.serverVersion ?? definition.version ?? "0.0.0",
+		exposeSharedState: options.exposeSharedState ?? true
+	});
+	const { startStdioTransport } = await import("../transports-BPUzHhI2.mjs");
+	let stop;
+	try {
+		stop = await startStdioTransport(server);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw logger.DF0017({
+			transport,
+			reason
+		}, { cause: error }).throw();
+	}
+	options.onReady?.({ transport: "stdio" });
+	return { async stop() {
+		dispose();
+		await stop();
+	} };
+}
+function registerToolHandlers(server, ctx) {
+	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		return { tools: ctx.agent.list().tools.map((tool) => projectTool(tool, ctx)) };
+	});
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const { name, arguments: args } = request.params;
+		try {
+			return { content: [{
+				type: "text",
+				text: stringify(await ctx.agent.invoke(name, args ?? {}))
+			}] };
+		} catch (error) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `Error invoking "${name}": ${error instanceof Error ? error.message : String(error)}`
+				}]
+			};
+		}
+	});
+}
+function registerResourceHandlers(server, ctx, exposeSharedState) {
+	server.setRequestHandler(ListResourcesRequestSchema, async () => {
+		const resources = ctx.agent.list().resources.map((resource) => ({
+			uri: resource.uri,
+			name: resource.name,
+			description: resource.description,
+			mimeType: resource.mimeType
+		}));
+		if (exposeSharedState !== false) {
+			const filter = typeof exposeSharedState === "function" ? exposeSharedState : () => true;
+			for (const key of ctx.rpc.sharedState.keys()) {
+				if (!filter(key)) continue;
+				resources.push({
+					uri: `devframe://state/${encodeURIComponent(key)}`,
+					name: key,
+					description: `Shared state: ${key}`,
+					mimeType: "application/json"
+				});
+			}
+		}
+		return { resources };
+	});
+	server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+		const { uri } = request.params;
+		const parsed = parseResourceUri(uri);
+		if (parsed.kind === "resource") {
+			const content = await ctx.agent.read(parsed.id);
+			return { contents: [{
+				uri,
+				mimeType: content.mimeType ?? "application/json",
+				text: content.text ?? stringify(content.json)
+			}] };
+		}
+		if (parsed.kind === "state") return { contents: [{
+			uri,
+			mimeType: "application/json",
+			text: stringify((await ctx.rpc.sharedState.get(parsed.key)).value())
+		}] };
+		throw new Error(`[devframe/mcp] unknown resource URI "${uri}"`);
+	});
+}
+function projectTool(tool, ctx) {
+	const inputSchema = tool.inputSchema ?? computeInputSchema(tool, ctx);
+	const outputSchema = tool.outputSchema ?? computeOutputSchema(tool, ctx);
+	return {
+		name: tool.id,
+		title: tool.title,
+		description: tool.description,
+		inputSchema,
+		...outputSchema ? { outputSchema } : {},
+		annotations: {
+			title: tool.title,
+			readOnlyHint: tool.safety === "read",
+			destructiveHint: tool.safety === "destructive"
+		}
+	};
+}
+function computeInputSchema(tool, ctx) {
+	if (tool.kind !== "rpc" || !tool.rpcName) return {
+		type: "object",
+		properties: {}
+	};
+	const def = ctx.rpc.definitions.get(tool.rpcName);
+	if (!def) return {
+		type: "object",
+		properties: {}
+	};
+	const args = def.args;
+	return valibotArgsToJsonSchema(args).schema;
+}
+function computeOutputSchema(tool, ctx) {
+	if (tool.kind !== "rpc" || !tool.rpcName) return void 0;
+	const def = ctx.rpc.definitions.get(tool.rpcName);
+	if (!def) return void 0;
+	return valibotReturnToJsonSchema(def.returns);
+}
+function parseResourceUri(uri) {
+	const match = uri.match(/^devframe:\/\/(resource|state)\/(.+)$/);
+	if (!match) return { kind: "unknown" };
+	const [, kind, rest] = match;
+	const decoded = decodeURIComponent(rest);
+	if (kind === "resource") return {
+		kind: "resource",
+		id: decoded
+	};
+	return {
+		kind: "state",
+		key: decoded
+	};
+}
+function stringify(value) {
+	if (value === void 0) return "undefined";
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value, null, 2);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+export { createMcpServer };

package/dist/adapters/vite.d.mts

@@ -0,0 +1,32 @@
+import { r as DevtoolDefinition } from "../devtool-OJ3QW0ns.mjs";
+
+//#region src/adapters/vite.d.ts
+interface CreateVitePluginOptions {
+  /**
+   * Mount base. Defaults to `def.basePath ?? '/.<id>/'` for this hosted
+   * adapter — the devtool shares the origin with the host Vite app.
+   */
+  base?: string;
+}
+interface DevframeVitePlugin {
+  name: string;
+  apply: 'serve';
+  configureServer: (server: {
+    middlewares: {
+      use: (path: string, handler: any) => void;
+    };
+  }) => void;
+}
+/**
+ * Plain Vite plugin — mounts a devframe devtool's SPA into a user's
+ * Vite dev server at `options.base` (default: `def.basePath ?? '/.<id>/'`).
+ * Use this for tools that want the Vite dev experience without
+ * pulling the full Vite DevTools Kit.
+ *
+ * Note: this does not yet spin up the RPC WS server — for the full
+ * RPC path, use `createKitPlugin` alongside `@vitejs/devtools`, or the
+ * standalone `createCli`.
+ */
+declare function createVitePlugin(d: DevtoolDefinition, options?: CreateVitePluginOptions): DevframeVitePlugin;
+//#endregion
+export { CreateVitePluginOptions, DevframeVitePlugin, createVitePlugin };

package/dist/adapters/vite.mjs

@@ -0,0 +1,31 @@
+import { t as resolveBasePath } from "../_shared-CU6dE-VX.mjs";
+import { resolve } from "pathe";
+import sirv from "sirv";
+//#region src/adapters/vite.ts
+/**
+* Plain Vite plugin — mounts a devframe devtool's SPA into a user's
+* Vite dev server at `options.base` (default: `def.basePath ?? '/.<id>/'`).
+* Use this for tools that want the Vite dev experience without
+* pulling the full Vite DevTools Kit.
+*
+* Note: this does not yet spin up the RPC WS server — for the full
+* RPC path, use `createKitPlugin` alongside `@vitejs/devtools`, or the
+* standalone `createCli`.
+*/
+function createVitePlugin(d, options = {}) {
+	const base = options.base ?? resolveBasePath(d, "hosted");
+	const distDir = d.cli?.distDir;
+	return {
+		name: `devframe:${d.id}`,
+		apply: "serve",
+		configureServer(server) {
+			if (!distDir) return;
+			server.middlewares.use(base, sirv(resolve(distDir), {
+				dev: true,
+				single: true
+			}));
+		}
+	};
+}
+//#endregion
+export { createVitePlugin };

package/dist/client/index.d.mts

@@ -0,0 +1,227 @@
+import { H as DevToolsRpcClientFunctions, St as DevToolsCommandEntry, U as DevToolsRpcServerFunctions, V as DevToolsDocksUserSettings, bt as DevToolsClientCommand, ct as DevToolsDockUserEntry, l as ConnectionMeta, nt as DevToolsDockEntriesGrouped, rt as DevToolsDockEntry, v as RpcSharedStateHost, w as SharedState, wt as DevToolsCommandKeybinding, zt as EventEmitter } from "../devtool-OJ3QW0ns.mjs";
+import { F as RpcCacheManager, I as RpcCacheOptions, M as RpcFunctionsCollector } from "../index-DvKDO5H8.mjs";
+import { t as WhenContext } from "../when-CGLewRtm.mjs";
+import { t as WsRpcChannelOptions } from "../ws-client-CklfxUHE.mjs";
+import { BirpcOptions, BirpcReturn } from "birpc";
+
+//#region src/client/rpc.d.ts
+interface DevToolsRpcClientOptions {
+  connectionMeta?: ConnectionMeta;
+  baseURL?: string | string[];
+  /**
+   * The auth token to use for the client
+   */
+  authToken?: string;
+  wsOptions?: Partial<WsRpcChannelOptions>;
+  rpcOptions?: Partial<BirpcOptions<DevToolsRpcServerFunctions, DevToolsRpcClientFunctions, boolean>>;
+  cacheOptions?: boolean | Partial<RpcCacheOptions>;
+}
+type DevToolsRpcClientCall = BirpcReturn<DevToolsRpcServerFunctions, DevToolsRpcClientFunctions>['$call'];
+type DevToolsRpcClientCallEvent = BirpcReturn<DevToolsRpcServerFunctions, DevToolsRpcClientFunctions>['$callEvent'];
+type DevToolsRpcClientCallOptional = BirpcReturn<DevToolsRpcServerFunctions, DevToolsRpcClientFunctions>['$callOptional'];
+interface DevToolsRpcClient {
+  /**
+   * The events of the client
+   */
+  events: EventEmitter<RpcClientEvents>;
+  /**
+   * Whether the client is trusted
+   */
+  readonly isTrusted: boolean | null;
+  /**
+   * The connection meta
+   */
+  readonly connectionMeta: ConnectionMeta;
+  /**
+   * Return a promise that resolves when the client is trusted
+   *
+   * Rejects with an error if the timeout is reached
+   *
+   * @param timeout - The timeout in milliseconds, default to 60 seconds
+   */
+  ensureTrusted: (timeout?: number) => Promise<boolean>;
+  /**
+   * Request trust from the server
+   */
+  requestTrust: () => Promise<boolean>;
+  /**
+   * Request trust from the server using a specific auth token.
+   * Updates the stored token and re-requests trust without reloading the page.
+   */
+  requestTrustWithToken: (token: string) => Promise<boolean>;
+  /**
+   * Call a RPC function on the server
+   */
+  call: DevToolsRpcClientCall;
+  /**
+   * Call a RPC event on the server, and does not expect a response
+   */
+  callEvent: DevToolsRpcClientCallEvent;
+  /**
+   * Call a RPC optional function on the server
+   */
+  callOptional: DevToolsRpcClientCallOptional;
+  /**
+   * The client RPC host
+   */
+  client: DevToolsClientRpcHost;
+  /**
+   * The shared state host
+   */
+  sharedState: RpcSharedStateHost;
+  /**
+   * The RPC cache manager
+   */
+  cacheManager: RpcCacheManager;
+}
+interface DevToolsRpcClientMode {
+  readonly isTrusted: boolean;
+  ensureTrusted: DevToolsRpcClient['ensureTrusted'];
+  requestTrust: DevToolsRpcClient['requestTrust'];
+  requestTrustWithToken: DevToolsRpcClient['requestTrustWithToken'];
+  call: DevToolsRpcClient['call'];
+  callEvent: DevToolsRpcClient['callEvent'];
+  callOptional: DevToolsRpcClient['callOptional'];
+}
+declare function getDevToolsRpcClient(options?: DevToolsRpcClientOptions): Promise<DevToolsRpcClient>;
+//#endregion
+//#region src/client/docks.d.ts
+interface DockPanelStorage {
+  mode: 'float' | 'edge';
+  width: number;
+  height: number;
+  top: number;
+  left: number;
+  position: 'left' | 'right' | 'bottom' | 'top';
+  open: boolean;
+  inactiveTimeout: number;
+}
+type DockClientType = 'embedded' | 'standalone';
+interface DevToolsRpcContext {
+  /**
+   * The RPC client to interact with the server
+   */
+  readonly rpc: DevToolsRpcClient;
+}
+interface DocksContext extends DevToolsRpcContext {
+  /**
+   * Type of the client environment
+   *
+   * 'embedded' - running inside an embedded floating panel
+   * 'standalone' - running inside a standalone window (no user app)
+   */
+  readonly clientType: 'embedded' | 'standalone';
+  /**
+   * The panel context
+   */
+  readonly panel: DocksPanelContext;
+  /**
+   * The docks entries context
+   */
+  readonly docks: DocksEntriesContext;
+  /**
+   * The commands context for command palette and shortcuts
+   */
+  readonly commands: CommandsContext;
+  /**
+   * The when-clause context for conditional visibility
+   */
+  readonly when: WhenClauseContext;
+}
+interface WhenClauseContext {
+  /**
+   * Get the current when-clause context snapshot.
+   * Returns a reactive object with built-in variables and any custom plugin variables.
+   */
+  readonly context: WhenContext;
+}
+type DevToolsClientRpcHost = RpcFunctionsCollector<DevToolsRpcClientFunctions, DevToolsRpcContext>;
+type DevToolsClientContext = DocksContext;
+interface DocksPanelContext {
+  store: DockPanelStorage;
+  isDragging: boolean;
+  isResizing: boolean;
+  readonly isVertical: boolean;
+}
+interface DocksEntriesContext {
+  selectedId: string | null;
+  readonly selected: DevToolsDockEntry | null;
+  entries: DevToolsDockEntry[];
+  entryToStateMap: Map<string, DockEntryState>;
+  groupedEntries: DevToolsDockEntriesGrouped;
+  settings: SharedState<DevToolsDocksUserSettings>;
+  /**
+   * Get the state of a dock entry by its ID
+   */
+  getStateById: (id: string) => DockEntryState | undefined;
+  /**
+   * Switch to the selected dock entry, pass `null` to clear the selection
+   *
+   * @returns Whether the selection was changed successfully
+   */
+  switchEntry: (id?: string | null) => Promise<boolean>;
+  /**
+   * Toggle the selected dock entry
+   *
+   * @returns Whether the selection was changed successfully
+   */
+  toggleEntry: (id: string) => Promise<boolean>;
+}
+interface DockEntryState {
+  entryMeta: DevToolsDockEntry;
+  readonly isActive: boolean;
+  domElements: {
+    iframe?: HTMLIFrameElement | null;
+    panel?: HTMLDivElement | null;
+  };
+  events: EventEmitter<DockEntryStateEvents>;
+}
+interface DockEntryStateEvents {
+  'entry:activated': () => void;
+  'entry:deactivated': () => void;
+  'entry:updated': (newMeta: DevToolsDockUserEntry) => void;
+  'dom:panel:mounted': (panel: HTMLDivElement) => void;
+  'dom:iframe:mounted': (iframe: HTMLIFrameElement) => void;
+}
+interface RpcClientEvents {
+  'rpc:is-trusted:updated': (isTrusted: boolean) => void;
+}
+interface CommandsContext {
+  /**
+   * All commands (server + client)
+   */
+  readonly commands: DevToolsCommandEntry[];
+  /**
+   * Palette-visible commands only (filtered by `showInPalette !== false`)
+   */
+  readonly paletteCommands: DevToolsCommandEntry[];
+  /**
+   * Register client-side command(s). Returns cleanup function.
+   */
+  register: (cmd: DevToolsClientCommand | DevToolsClientCommand[]) => () => void;
+  /**
+   * Execute a command by ID. Delegates to RPC for server commands.
+   */
+  execute: (id: string, ...args: any[]) => Promise<unknown>;
+  /**
+   * Get effective keybindings for a command (defaults merged with overrides)
+   */
+  getKeybindings: (id: string) => DevToolsCommandKeybinding[];
+  /**
+   * User settings store (persisted, includes command shortcuts)
+   */
+  settings: SharedState<DevToolsDocksUserSettings>;
+  /**
+   * Whether the command palette is open
+   */
+  paletteOpen: boolean;
+}
+//#endregion
+//#region src/client/context.d.ts
+declare const CLIENT_CONTEXT_KEY = "__VITE_DEVTOOLS_CLIENT_CONTEXT__";
+/**
+ * Get the global DevTools client context, or `undefined` if not yet initialized.
+ */
+declare function getDevToolsClientContext(): DevToolsClientContext | undefined;
+//#endregion
+export { CLIENT_CONTEXT_KEY, CommandsContext, DevToolsClientContext, DevToolsClientRpcHost, DevToolsRpcClient, DevToolsRpcClientCall, DevToolsRpcClientCallEvent, DevToolsRpcClientCallOptional, DevToolsRpcClientMode, DevToolsRpcClientOptions, DevToolsRpcContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DocksContext, DocksEntriesContext, DocksPanelContext, RpcClientEvents, WhenClauseContext, getDevToolsRpcClient as connectDevtool, getDevToolsRpcClient, getDevToolsClientContext };

package/dist/client/index.mjs

@@ -0,0 +1,2 @@
+import { n as CLIENT_CONTEXT_KEY, r as getDevToolsClientContext, t as getDevToolsRpcClient } from "../client-4WrEozlH.mjs";
+export { CLIENT_CONTEXT_KEY, getDevToolsRpcClient as connectDevtool, getDevToolsRpcClient, getDevToolsClientContext };