devframe 0.0.0 → 0.1.16

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-PRESENT Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# devframe
+
+Framework-neutral foundation for building generic DevTools — RPC layer (birpc + valibot + WS presets), six hosts (RPC / docks / views / terminals / logs / commands / agent), and adapters under `devframe/adapters/*` (cli / build / spa / vite / kit / embedded / mcp). Part of the [Vite DevTools](https://devtools.vite.dev) monorepo.
+
+## Install
+
+```sh
+pnpm add devframe
+```
+
+## Docs
+
+See the [DevFrame documentation](https://devtools.vite.dev/devframe/) for the full guide and API reference.
+
+## Agent-Native (experimental)
+
+> ⚠️ **Experimental.** The agent-native surface — the `agent` field on `defineRpcFunction`, `DevToolsAgentHost`, and the `devframe/adapters/mcp` adapter — is experimental and may change without a major version bump until it stabilizes.
+
+DevFrame can expose a devtool's RPC functions, tools, and resources to coding agents over [MCP](https://modelcontextprotocol.io). Flag an RPC function with `agent: { description }` to surface it, then spin up an MCP server:
+
+```ts
+import { defineDevtool, defineRpcFunction } from 'devframe'
+import { createMcpServer } from 'devframe/adapters/mcp'
+
+const getSummary = defineRpcFunction({
+  name: 'my-plugin:get-summary',
+  type: 'query',
+  agent: {
+    description: 'Return a short summary of the current build state.',
+  },
+  setup: ctx => ({ handler: async () => buildSummary() }),
+})
+
+const devtool = defineDevtool({
+  id: 'my-plugin',
+  setup(ctx) {
+    ctx.rpc.register(getSummary)
+    // Optional: register tools or resources directly.
+    ctx.agent.registerResource({
+      id: 'latest-build',
+      name: 'Latest build',
+      read: () => ({ text: renderMarkdown(latestBuild) }),
+    })
+  },
+})
+
+await createMcpServer(devtool, { transport: 'stdio' })
+```
+
+Or via the CLI:
+
+```sh
+devframe mcp
+```
+
+`@modelcontextprotocol/sdk` is a peer dependency — add it to your package when you want to ship MCP support.
+
+See the [Agent-Native guide](https://devtools.vite.dev/devframe/agent-native) for the full API, safety model, and Claude Desktop integration example.
+
+## License
+
+[MIT](./LICENSE.md)

package/dist/_shared-CU6dE-VX.mjs

@@ -0,0 +1,20 @@
+//#region src/adapters/_shared.ts
+/**
+* Resolve the mount base path for a devtool's SPA. Hosted adapters
+* (`vite`, `kit`, `embedded`) default to `/.<id>/` so they don't
+* collide with the host app; standalone adapters (`cli`, `spa`,
+* `build`) default to `/` because they own the origin.
+*
+* The devtool 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) {
+	let out = base.startsWith("/") ? base : `/${base}`;
+	if (!out.endsWith("/")) out = `${out}/`;
+	return out.replace(/\/+/g, "/");
+}
+//#endregion
+export { resolveBasePath as t };

package/dist/adapters/build.d.mts

@@ -0,0 +1,37 @@
+import { r as DevtoolDefinition } from "../devtool-OJ3QW0ns.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 `devtool.cli?.distDir` — authors typically set this
+   * once on the definition itself.
+   */
+  distDir?: string;
+  /**
+   * Pretty-print RPC dump JSON files. Defaults to `false` so payload
+   * shards (which can be multiple MB for graph-heavy tools) ship
+   * minified. Set `true` when you need to diff / read the dumps by hand.
+   */
+  pretty?: boolean;
+}
+/**
+ * Produce a self-contained static deploy of a devtool:
+ *
+ *   - Build a `mode: 'build'` context and run `devtool.setup(ctx)`.
+ *   - 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 `/`, `/devtools/`, or any base, no rewriting required.
+ */
+declare function createBuild(d: DevtoolDefinition, options?: CreateBuildOptions): Promise<void>;
+//#endregion
+export { CreateBuildOptions, createBuild };

package/dist/adapters/build.mjs

@@ -0,0 +1,61 @@
+import { t as createHostContext } from "../context-BrePWeyd.mjs";
+import { DEVTOOLS_CONNECTION_META_FILENAME, DEVTOOLS_RPC_DUMP_DIRNAME, DEVTOOLS_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
+import { n as createH3DevToolsHost, t as collectStaticRpcDump } from "../static-dump-CQUC1aIW.mjs";
+import { t as resolveBasePath } from "../_shared-CU6dE-VX.mjs";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "pathe";
+import process from "node:process";
+import c from "ansis";
+import fs$1 from "node:fs/promises";
+//#region src/adapters/build.ts
+/**
+* Produce a self-contained static deploy of a devtool:
+*
+*   - Build a `mode: 'build'` context and run `devtool.setup(ctx)`.
+*   - 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 `/`, `/devtools/`, or any base, no rewriting required.
+*/
+async function createBuild(d, options = {}) {
+	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.`);
+	if (existsSync(outDir)) await fs$1.rm(outDir, { recursive: true });
+	await fs$1.mkdir(outDir, { recursive: true });
+	console.log(c.cyan`[devframe] copying SPA from ${distDir} -> ${outDir}`);
+	await fs$1.cp(distDir, outDir, { recursive: true });
+	const ctx = await createHostContext({
+		cwd: process.cwd(),
+		mode: "build",
+		host: createH3DevToolsHost({ origin: "http://localhost" })
+	});
+	await d.setup(ctx);
+	await fs$1.mkdir(resolve(outDir, DEVTOOLS_RPC_DUMP_DIRNAME), { recursive: true });
+	await fs$1.writeFile(resolve(outDir, DEVTOOLS_CONNECTION_META_FILENAME), JSON.stringify({ backend: "static" }, null, 2), "utf-8");
+	console.log(c.cyan`[devframe] writing RPC dump to ${resolve(outDir, DEVTOOLS_RPC_DUMP_MANIFEST_FILENAME)}`);
+	const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx);
+	const indent = options.pretty ? 2 : void 0;
+	for (const [filepath, data] of Object.entries(dump.files)) {
+		const fullpath = resolve(outDir, filepath);
+		await fs$1.mkdir(dirname(fullpath), { recursive: true });
+		await fs$1.writeFile(fullpath, JSON.stringify(data, null, indent), "utf-8");
+	}
+	await fs$1.writeFile(resolve(outDir, DEVTOOLS_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(c.green`[devframe] built "${d.id}" -> ${outDir}`);
+}
+//#endregion
+export { createBuild };

package/dist/adapters/cli.d.mts

@@ -0,0 +1,35 @@
+import { r as DevtoolDefinition } from "../devtool-OJ3QW0ns.mjs";
+import { App } from "h3";
+import { CAC } from "cac";
+
+//#region src/adapters/cli.d.ts
+interface CreateCliOptions {
+  /** Default port for `dev` (default: 9999). */
+  defaultPort?: number;
+  /**
+   * Final CAC hook invoked after devframe's built-in subcommands and
+   * after the definition's `cli.configure`. Use this to add app-level
+   * flags and commands at the assembly stage.
+   */
+  configureCli?: (cli: CAC) => void;
+  /**
+   * Called once the dev server is listening. Use this to print a
+   * startup banner or trigger side-effects that depend on the live URL.
+   */
+  onReady?: (info: {
+    origin: string;
+    port: number;
+    app: App;
+  }) => void | Promise<void>;
+}
+interface CliHandle {
+  /**
+   * Raw CAC instance. Mutate before calling `parse()` for last-mile
+   * flag or command additions that don't fit `configureCli`.
+   */
+  cli: CAC;
+  parse: (argv?: string[]) => Promise<void>;
+}
+declare function createCli(d: DevtoolDefinition, options?: CreateCliOptions): CliHandle;
+//#endregion
+export { CliHandle, CreateCliOptions, createCli };

package/dist/adapters/cli.mjs

@@ -0,0 +1,357 @@
+import { a as flagKeyToOption, o as isBooleanFlag, s as parseCliFlags } from "../src-BoIqXRc9.mjs";
+import { t as createHostContext } from "../context-BrePWeyd.mjs";
+import { DEVTOOLS_CONNECTION_META_FILENAME } from "../constants.mjs";
+import { n as createH3DevToolsHost } from "../static-dump-CQUC1aIW.mjs";
+import { t as startHttpAndWs } from "../server-DrBxa6ZV.mjs";
+import { t as resolveBasePath } from "../_shared-CU6dE-VX.mjs";
+import { createBuild } from "./build.mjs";
+import { resolve } from "pathe";
+import process$1 from "node:process";
+import c from "ansis";
+import { networkInterfaces } from "node:os";
+import { createApp, eventHandler, fromNodeMiddleware } from "h3";
+import { createServer } from "node:net";
+import cac from "cac";
+import sirv from "sirv";
+//#region ../../../node_modules/.pnpm/get-port-please@3.2.0/node_modules/get-port-please/dist/index.mjs
+const unsafePorts = /* @__PURE__ */ new Set([
+	1,
+	7,
+	9,
+	11,
+	13,
+	15,
+	17,
+	19,
+	20,
+	21,
+	22,
+	23,
+	25,
+	37,
+	42,
+	43,
+	53,
+	69,
+	77,
+	79,
+	87,
+	95,
+	101,
+	102,
+	103,
+	104,
+	109,
+	110,
+	111,
+	113,
+	115,
+	117,
+	119,
+	123,
+	135,
+	137,
+	139,
+	143,
+	161,
+	179,
+	389,
+	427,
+	465,
+	512,
+	513,
+	514,
+	515,
+	526,
+	530,
+	531,
+	532,
+	540,
+	548,
+	554,
+	556,
+	563,
+	587,
+	601,
+	636,
+	989,
+	990,
+	993,
+	995,
+	1719,
+	1720,
+	1723,
+	2049,
+	3659,
+	4045,
+	5060,
+	5061,
+	6e3,
+	6566,
+	6665,
+	6666,
+	6667,
+	6668,
+	6669,
+	6697,
+	10080
+]);
+function isUnsafePort(port) {
+	return unsafePorts.has(port);
+}
+function isSafePort(port) {
+	return !isUnsafePort(port);
+}
+var GetPortError = class extends Error {
+	constructor(message, opts) {
+		super(message, opts);
+		this.message = message;
+	}
+	name = "GetPortError";
+};
+function _log(verbose, message) {
+	if (verbose) console.log(`[get-port] ${message}`);
+}
+function _generateRange(from, to) {
+	if (to < from) return [];
+	const r = [];
+	for (let index = from; index <= to; index++) r.push(index);
+	return r;
+}
+function _tryPort(port, host) {
+	return new Promise((resolve) => {
+		const server = createServer();
+		server.unref();
+		server.on("error", () => {
+			resolve(false);
+		});
+		server.listen({
+			port,
+			host
+		}, () => {
+			const { port: port2 } = server.address();
+			server.close(() => {
+				resolve(isSafePort(port2) && port2);
+			});
+		});
+	});
+}
+function _getLocalHosts(additional) {
+	const hosts = new Set(additional);
+	for (const _interface of Object.values(networkInterfaces())) for (const config of _interface || []) if (config.address && !config.internal && !config.address.startsWith("fe80::") && !config.address.startsWith("169.254")) hosts.add(config.address);
+	return [...hosts];
+}
+async function _findPort(ports, host) {
+	for (const port of ports) {
+		const r = await _tryPort(port, host);
+		if (r) return r;
+	}
+}
+function _fmtOnHost(hostname) {
+	return hostname ? `on host ${JSON.stringify(hostname)}` : "on any host";
+}
+const HOSTNAME_RE = /^(?!-)[\d.:A-Za-z-]{1,63}(?<!-)$/;
+function _validateHostname(hostname, _public, verbose) {
+	if (hostname && !HOSTNAME_RE.test(hostname)) {
+		const fallbackHost = _public ? "0.0.0.0" : "127.0.0.1";
+		_log(verbose, `Invalid hostname: ${JSON.stringify(hostname)}. Using ${JSON.stringify(fallbackHost)} as fallback.`);
+		return fallbackHost;
+	}
+	return hostname;
+}
+async function getPort(_userOptions = {}) {
+	if (typeof _userOptions === "number" || typeof _userOptions === "string") _userOptions = { port: Number.parseInt(_userOptions + "") || 0 };
+	const _port = Number(_userOptions.port ?? process.env.PORT);
+	const _userSpecifiedAnyPort = Boolean(_userOptions.port || _userOptions.ports?.length || _userOptions.portRange?.length);
+	const options = {
+		random: _port === 0,
+		ports: [],
+		portRange: [],
+		alternativePortRange: _userSpecifiedAnyPort ? [] : [3e3, 3100],
+		verbose: false,
+		..._userOptions,
+		port: _port,
+		host: _validateHostname(_userOptions.host ?? process.env.HOST, _userOptions.public, _userOptions.verbose)
+	};
+	if (options.random && !_userSpecifiedAnyPort) return getRandomPort(options.host);
+	const portsToCheck = [
+		options.port,
+		...options.ports,
+		..._generateRange(...options.portRange)
+	].filter((port) => {
+		if (!port) return false;
+		if (!isSafePort(port)) {
+			_log(options.verbose, `Ignoring unsafe port: ${port}`);
+			return false;
+		}
+		return true;
+	});
+	if (portsToCheck.length === 0) portsToCheck.push(3e3);
+	let availablePort = await _findPort(portsToCheck, options.host);
+	if (!availablePort && options.alternativePortRange.length > 0) {
+		availablePort = await _findPort(_generateRange(...options.alternativePortRange), options.host);
+		if (portsToCheck.length > 0) {
+			let message = `Unable to find an available port (tried ${portsToCheck.join("-")} ${_fmtOnHost(options.host)}).`;
+			if (availablePort) message += ` Using alternative port ${availablePort}.`;
+			_log(options.verbose, message);
+		}
+	}
+	if (!availablePort && _userOptions.random !== false) {
+		availablePort = await getRandomPort(options.host);
+		if (availablePort) _log(options.verbose, `Using random port ${availablePort}`);
+	}
+	if (!availablePort) {
+		const triedRanges = [
+			options.port,
+			options.portRange.join("-"),
+			options.alternativePortRange.join("-")
+		].filter(Boolean).join(", ");
+		throw new GetPortError(`Unable to find an available port ${_fmtOnHost(options.host)} (tried ${triedRanges})`);
+	}
+	return availablePort;
+}
+async function getRandomPort(host) {
+	const port = await checkPort(0, host);
+	if (port === false) throw new GetPortError(`Unable to find a random port ${_fmtOnHost(host)}`);
+	return port;
+}
+async function checkPort(port, host = process.env.HOST, verbose) {
+	if (!host) host = _getLocalHosts([void 0, "0.0.0.0"]);
+	if (!Array.isArray(host)) return _tryPort(port, host);
+	for (const _host of host) {
+		const _port = await _tryPort(port, _host);
+		if (_port === false) {
+			if (port < 1024 && verbose) _log(verbose, `Unable to listen to the privileged port ${port} ${_fmtOnHost(_host)}`);
+			return false;
+		}
+		if (port === 0 && _port !== 0) port = _port;
+	}
+	return port;
+}
+//#endregion
+//#region src/adapters/cli.ts
+function createCli(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 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");
+	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 portOptions = {
+			port: defaultPort,
+			host
+		};
+		if (d.cli?.portRange) portOptions.portRange = d.cli.portRange;
+		if (d.cli?.random) portOptions.random = d.cli.random;
+		await runDevServer(d, {
+			host,
+			port: flags.port ?? await getPort(portOptions),
+			flags
+		}, options);
+	});
+	cli.command("build", "Build a self-contained static deploy of the devtool").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,
+			pretty: flags.pretty
+		});
+	});
+	cli.command("mcp", "Start an MCP server exposing agent-facing tools (stdio) [experimental]").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$1.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(c.red`[devframe] invalid flag — ${issue}`);
+		process$1.exit(1);
+	}
+	return flags;
+}
+async function runDevServer(d, serverOptions, cliOptions) {
+	const distDir = d.cli?.distDir;
+	if (!distDir) throw new Error(`[devframe] dev: no cli.distDir for "${d.id}". Set \`cli.distDir\` on the definition.`);
+	const app = createApp();
+	const origin = `http://${serverOptions.host}:${serverOptions.port}`;
+	const basePath = resolveBasePath(d, "standalone");
+	const host = createH3DevToolsHost({
+		origin,
+		mount: (base, dir) => {
+			app.use(base, fromNodeMiddleware(sirv(dir, {
+				dev: true,
+				single: true
+			})));
+		}
+	});
+	const ctx = await createHostContext({
+		cwd: process$1.cwd(),
+		mode: "dev",
+		host
+	});
+	const setupInfo = { flags: serverOptions.flags };
+	await d.setup(ctx, setupInfo);
+	const connectionMetaPath = `${basePath}${DEVTOOLS_CONNECTION_META_FILENAME}`;
+	app.use(connectionMetaPath, eventHandler((event) => {
+		event.node.res.setHeader("Content-Type", "application/json");
+		return event.node.res.end(JSON.stringify({
+			backend: "websocket",
+			websocket: serverOptions.port
+		}));
+	}));
+	app.use(basePath, fromNodeMiddleware(sirv(resolve(distDir), {
+		dev: true,
+		single: true
+	})));
+	await startHttpAndWs({
+		context: ctx,
+		host: serverOptions.host,
+		port: serverOptions.port,
+		app,
+		auth: d.cli?.auth,
+		onReady: async (info) => {
+			await cliOptions.onReady?.(info);
+			await maybeOpenBrowser(d, serverOptions.flags, `${info.origin}${basePath}`);
+		}
+	});
+}
+async function maybeOpenBrowser(d, flags, origin) {
+	const cliOpen = d.cli?.open;
+	if (!(flags.open ?? (cliOpen !== void 0 && cliOpen !== false))) return;
+	const target = typeof flags.open === "string" ? resolveOpenTarget(origin, flags.open) : typeof cliOpen === "string" ? resolveOpenTarget(origin, cliOpen) : origin;
+	try {
+		const { default: open } = await import("../open-BtOOEldu.mjs");
+		await open(target);
+	} catch {}
+}
+function resolveOpenTarget(origin, target) {
+	if (/^https?:/.test(target)) return target;
+	if (target.startsWith("/")) return origin.replace(/\/$/, "") + target;
+	return origin.replace(/\/$/, "") + (target ? `/${target}` : "");
+}
+//#endregion
+export { createCli };

package/dist/adapters/embedded.d.mts

@@ -0,0 +1,19 @@
+import { d as DevToolsNodeContext, r as DevtoolDefinition } from "../devtool-OJ3QW0ns.mjs";
+
+//#region src/adapters/embedded.d.ts
+interface CreateEmbeddedOptions {
+  /** Target context the devtool is registered into. Required. */
+  ctx: DevToolsNodeContext;
+}
+/**
+ * Register a devtool into an already-running devframe/Kit context at
+ * runtime. Mirrors what the Vite plugin scan does for devtools passed
+ * as plugin options, but exposes the same flow to callers that need
+ * dynamic, post-startup registration.
+ *
+ * The host owns the mount path; when a hosted mount is needed the
+ * effective default follows the hosted rule of `def.basePath ?? '/.<id>/'`.
+ */
+declare function createEmbedded(d: DevtoolDefinition, options: CreateEmbeddedOptions): Promise<void>;
+//#endregion
+export { CreateEmbeddedOptions, createEmbedded };

package/dist/adapters/embedded.mjs

@@ -0,0 +1,15 @@
+//#region src/adapters/embedded.ts
+/**
+* Register a devtool into an already-running devframe/Kit context at
+* runtime. Mirrors what the Vite plugin scan does for devtools passed
+* as plugin options, but exposes the same flow to callers that need
+* dynamic, post-startup registration.
+*
+* The host owns the mount path; when a hosted mount is needed the
+* effective default follows the hosted rule of `def.basePath ?? '/.<id>/'`.
+*/
+async function createEmbedded(d, options) {
+	await d.setup(options.ctx);
+}
+//#endregion
+export { createEmbedded };

package/dist/adapters/kit.d.mts

@@ -0,0 +1,23 @@
+import { r as DevtoolDefinition } from "../devtool-OJ3QW0ns.mjs";
+
+//#region src/adapters/kit.d.ts
+interface CreateKitPluginOptions {
+  /**
+   * Optional plugin name override. Defaults to `devframe:<devtool-id>`.
+   */
+  name?: string;
+}
+interface KitPlugin {
+  name: string;
+  devtools: {
+    setup: DevtoolDefinition['setup'];
+    capabilities?: DevtoolDefinition['capabilities'];
+  };
+}
+/**
+ * Produce a Vite plugin object that Kit's plugin-scan picks up via
+ * `Plugin.devtools`.
+ */
+declare function createKitPlugin(d: DevtoolDefinition, options?: CreateKitPluginOptions): KitPlugin;
+//#endregion
+export { CreateKitPluginOptions, KitPlugin, createKitPlugin };

package/dist/adapters/kit.mjs

@@ -0,0 +1,16 @@
+//#region src/adapters/kit.ts
+/**
+* Produce a Vite plugin object that Kit's plugin-scan picks up via
+* `Plugin.devtools`.
+*/
+function createKitPlugin(d, options = {}) {
+	return {
+		name: options.name ?? `devframe:${d.id}`,
+		devtools: {
+			setup: d.setup,
+			capabilities: d.capabilities
+		}
+	};
+}
+//#endregion
+export { createKitPlugin };