devframe 0.8.2 → 0.9.0-beta.10

package/dist/dev--rAPzbvO.mjs

@@ -0,0 +1,239 @@
+import { DEVFRAME_CONNECTION_META_FILENAME } from "./constants.mjs";
+import { t as diagnostics } from "./diagnostics-DOQPnQmX.mjs";
+import { t as createHostContext } from "./context-CEe4PBz1.mjs";
+import { t as resolveStaticAssetsSource } from "./remote-assets-nTTxY2MU.mjs";
+import { i as resolveMcpConnectionMeta, n as resolveBasePath, r as resolveDevServerPort, t as normalizeBasePath } from "./_shared-CbZ_yhbz.mjs";
+import { t as createH3DevframeHost } from "./host-h3-Crkzm42q.mjs";
+import { i as normalizeHttpServerUrl, n as resolveInstanceRegister, t as createInstanceShell } from "./instance-shell-CMFyszWJ.mjs";
+import { open } from "./utils/open.mjs";
+import { mountStaticHandler } from "./utils/serve-static.mjs";
+import { createServer } from "node:http";
+import { resolve } from "pathe";
+import process from "node:process";
+import { joinURL, withBase } from "ufo";
+import { H3, toNodeHandler } from "h3";
+//#region src/adapters/initiate.ts
+const INSTANCE_INTERNALS = /* @__PURE__ */ new WeakMap();
+/** @internal */
+function getInstanceInternals(handler) {
+	return INSTANCE_INTERNALS.get(handler) ?? {};
+}
+/**
+* Serve a devframe through one framework-agnostic, web-standard handler —
+* the SPA, `__connection.json` discovery, the WebSocket RPC endpoint, the
+* auth gate, and the optional MCP route, all under a single mount base.
+* Mount `handler` on any framework's catch-all route (or `nodeMiddleware` on
+* a connect stack) and the devframe is live inside that app.
+*
+* The factory is synchronous and kicks off initialization eagerly;
+* `handler`/`nodeMiddleware` await readiness internally. Nothing binds a port
+* on its own: the WebSocket resolves in precedence order — `ws.port` (pinned
+* side-car) > `server` (shared upgrade at `<base>__ws`) > `ws.sidecar`
+* (auto-port side-car) > the host driving upgrades itself through
+* {@link DevframeInstance.attach} — while `ws.url`, when set, overrides the
+* advertised* endpoint (the tunnel pattern) and on its own hands the whole
+* transport to an external server. `__connection.json` reflects whichever
+* combination is active.
+*/
+function initDevframe(def, options) {
+	const base = normalizeBasePath(options.base);
+	const distDir = options.distDir === false ? void 0 : options.distDir ?? def.cli?.distDir;
+	const app = options.app ?? new H3();
+	const shell = createInstanceShell({
+		base,
+		app,
+		host: options.host ?? def.cli?.host ?? "localhost",
+		origin: options.origin,
+		auth: options.auth !== void 0 ? options.auth : def.cli?.auth,
+		server: options.server,
+		ws: options.ws ?? def.cli?.ws,
+		sse: options.sse ?? def.cli?.sse,
+		allowedOrigins: options.allowedOrigins,
+		destroyUnmatchedUpgrades: options.destroyUnmatchedUpgrades,
+		onPeerConnect: options.onPeerConnect,
+		onPeerDisconnect: options.onPeerDisconnect,
+		register: resolveInstanceRegister(options.register, {
+			id: def.id,
+			name: def.name
+		}),
+		resolveSidecarPort: (sidecarHost) => resolveDevServerPort(def, { host: sidecarHost }),
+		onMetaUnavailable: () => {
+			throw diagnostics.DF0054({ id: def.id });
+		},
+		async init(api) {
+			const h3Host = createH3DevframeHost({
+				origin: () => api.origin() ?? "http://localhost",
+				appName: def.id,
+				mount: (mountBase, dir) => {
+					mountStaticHandler(app, mountBase, dir);
+				}
+			});
+			const hostImpl = options.getStorageDir ? {
+				...h3Host,
+				getStorageDir: options.getStorageDir
+			} : h3Host;
+			const context = await createHostContext({
+				cwd: process.cwd(),
+				mode: "dev",
+				host: hostImpl
+			});
+			const setupInfo = { flags: options.flags ?? {} };
+			await def.setup(context, setupInfo);
+			const mcpOption = options.mcp ?? def.cli?.mcp;
+			const mcpMeta = resolveMcpConnectionMeta(def, mcpOption);
+			let mcpDispose;
+			if (mcpMeta) {
+				const mcpConfig = mcpOption === true || mcpOption === void 0 ? {} : mcpOption;
+				const mcpPath = joinURL(base, mcpMeta.path);
+				let mountMcpHttp;
+				try {
+					({mountMcpHttp} = await import("./http-DYpK0cUi.mjs").then((n) => n.t));
+				} catch (error) {
+					const reason = error instanceof Error ? error.message : String(error);
+					throw diagnostics.DF0017({
+						transport: "http",
+						reason,
+						cause: error
+					});
+				}
+				mcpDispose = mountMcpHttp(app, context, mcpPath, {
+					serverName: `${def.id} (devframe)`,
+					serverVersion: def.version ?? "0.0.0",
+					exposeSharedState: true,
+					allowedOrigins: mcpConfig.allowedOrigins
+				}).dispose;
+			}
+			return {
+				context,
+				...mcpMeta ? { mcp: mcpMeta } : {},
+				...mcpDispose ? { dispose: mcpDispose } : {}
+			};
+		},
+		mount(context, meta) {
+			app.use(joinURL(base, DEVFRAME_CONNECTION_META_FILENAME), () => meta);
+			if (distDir) {
+				const source = resolveStaticAssetsSource(distDir, context.host.getStorageDir("project"));
+				mountStaticHandler(app, base, typeof source === "string" ? resolve(source) : source);
+			}
+		}
+	});
+	const instance = {
+		base: shell.base,
+		handler: shell.handler,
+		nodeMiddleware: shell.nodeMiddleware,
+		attach: shell.attach,
+		handleUpgrade: shell.handleUpgrade,
+		ready: shell.ready,
+		context: shell.context,
+		connectionMeta: shell.connectionMeta,
+		close: shell.close
+	};
+	INSTANCE_INTERNALS.set(instance, shell.internals);
+	return instance;
+}
+//#endregion
+//#region src/adapters/dev.ts
+/**
+* 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 `def.cli?.distDir` is 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
+* `devframeViteBridge` from `@devframes/vite`.
+*
+* Returns the underlying {@link StartedServer} handle so callers can
+* close it gracefully (SIGINT, hot-reload, test teardown).
+*
+* Use this directly when integrating devframe into an existing CLI
+* framework (commander, yargs, hand-rolled CAC). For the all-in-one
+* `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
+*/
+async function createDevServer(def, options = {}) {
+	if (def.capabilities?.dev === false && !options.force) throw diagnostics.DF0058({ id: def.id });
+	const host = options.host ?? def.cli?.host ?? "localhost";
+	const requestedPort = options.port ?? await resolveDevServerPort(def, { host });
+	const flags = options.flags ?? {};
+	const basePath = options.basePath ? normalizeBasePath(options.basePath) : resolveBasePath(def, "standalone");
+	const app = options.app ?? new H3();
+	const server = createServer(toNodeHandler(app));
+	try {
+		await new Promise((resolveListen, rejectListen) => {
+			const onError = (error) => rejectListen(error);
+			server.once("error", onError);
+			server.listen(requestedPort, host, () => {
+				server.removeListener("error", onError);
+				resolveListen();
+			});
+		});
+	} catch (error) {
+		throw diagnostics.DF0052({
+			host,
+			port: requestedPort,
+			reason: error instanceof Error ? error.message : String(error),
+			cause: error
+		});
+	}
+	const address = server.address();
+	const port = typeof address === "object" && address ? address.port : requestedPort;
+	const origin = normalizeHttpServerUrl(host, port);
+	const devframe = initDevframe(def, {
+		base: basePath,
+		distDir: options.distDir,
+		app,
+		server,
+		host,
+		origin,
+		ws: options.ws,
+		allowedOrigins: options.allowedOrigins,
+		sse: options.sse,
+		auth: flags.auth === false ? false : options.auth,
+		mcp: options.mcp,
+		flags,
+		onPeerConnect: options.onPeerConnect,
+		onPeerDisconnect: options.onPeerDisconnect,
+		register: true,
+		destroyUnmatchedUpgrades: true
+	});
+	try {
+		await devframe.ready;
+	} catch (error) {
+		await new Promise((resolveClose) => server.close(() => resolveClose()));
+		throw error;
+	}
+	const internals = getInstanceInternals(devframe);
+	const transport = internals.started;
+	await options.onReady?.({
+		origin,
+		port,
+		app
+	});
+	await maybeOpenBrowser(def, flags, `${origin}${basePath}`, options.openBrowser, internals.authHandler);
+	return {
+		origin,
+		port,
+		app,
+		ws: transport.ws,
+		rpcGroup: transport.rpcGroup,
+		connectionMeta: transport.connectionMeta,
+		async close() {
+			await devframe.close();
+			await new Promise((resolveClose) => server.close(() => resolveClose()));
+		}
+	};
+}
+async function maybeOpenBrowser(def, flags, origin, override, authHandler) {
+	const flagsOpen = flags.open;
+	const cliOpen = def.cli?.open;
+	const resolved = override ?? flagsOpen ?? cliOpen;
+	if (resolved === void 0 || resolved === false) return;
+	const target = typeof resolved === "string" ? withBase(resolved, origin) : origin;
+	const authorizedTarget = authHandler?.buildOpenUrl?.(target) ?? target;
+	try {
+		await open(authorizedTarget);
+	} catch {}
+}
+//#endregion
+export { getInstanceInternals as n, initDevframe as r, createDevServer as t };