import type { DevframeHubUi, DockRendererRegistration, HubDevframeEntry, HubInstance, InitHubOptions } from '@devframes/hub/initiate' import type { DevframeHubContext } from '@devframes/hub/node' import type { ClientScriptEntry } from '@devframes/hub/types' import type { DevframeDefinition } from 'devframe' import type { Server as NodeHttpServer } from 'node:http' import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite' import process from 'node:process' import { DEVFRAMES_HUB_BASE, normalizeHubBase } from '@devframes/hub/constants' import { initHub } from '@devframes/hub/initiate' import { resolve } from 'pathe' export interface ViteDevframeHubOptions { /** * Mount base the hub answers under; every frame lives at `/`. * Default: `/__devframes/`. */ base?: string /** * Pin a side-car port for the RPC/WS server. By default the WebSocket * shares Vite's own HTTP server, upgrading at `__ws`. */ port?: number /** Bind host for a pinned side-car server. Default: `localhost`. */ host?: string /** * Devframes to mount as docks. Wrap an entry in `{ devframe, dock }` to * customize its synthesized iframe dock (category, `frameId`, `subTabs`, …). */ devframes?: InitHubOptions['devframes'] /** * Per-dock client scripts, keyed by devframe id. Attached to the mounted * iframe dock so the hub client runtime imports them into the host page * (e.g. the a11y inspector's in-page agent). */ clientScripts?: Record /** * Prebuilt dock-renderer modules forwarded to `initHub({ renderers })`, * each served at `__renderers/.mjs` and published in the * renderer manifest (e.g. `jsonRenderUiRenderer()` from * `@devframes/json-render-ui/hub`). */ renderers?: readonly DockRendererRegistration[] /** * Extra RPC declarations registered at context creation, alongside the hub * built-ins. */ rpcDeclarations?: InitHubOptions['rpcDeclarations'] /** * Runs once the context exists and every `devframes` entry is mounted; * register docks, commands, terminals, and messages surfaces here. */ configure?: (ctx: DevframeHubContext) => void | Promise /** * The hub's UI slot. Defaults to `@devframes/hub-ui`'s `createUi()` (the * reference floating dock + standalone viewer) when omitted, so install * `@devframes/hub-ui` for that default. Pass your own {@link DevframeHubUi} * to swap the hub UI provider, or `false` for a headless hub (serve your own UI * against `@devframes/hub/client`). */ ui?: DevframeHubUi | false /** * The hub's single auth gate. Gates by default (interactive OTP); `false` * opts out for a single-user localhost host. */ auth?: InitHubOptions['auth'] /** * Expose the aggregate MCP endpoint at `__mcp`. Defaults to `'auto'` * (mount once any mounted devframe exposes an agent surface); `true` * forces it on, `false` off. */ mcp?: InitHubOptions['mcp'] /** Publish this hub in the global instance registry. Default: off. */ register?: InitHubOptions['register'] /** Public origin the host app is reachable at, or a getter. */ origin?: InitHubOptions['origin'] /** Working directory for the hub context. Default: Vite's project root. */ cwd?: string /** Override where persisted devframe state lives. */ getStorageDir?: InitHubOptions['getStorageDir'] /** Name for the hub instance (logs, diagnostics, MCP server). */ name?: string /** Version for the hub instance (logs, diagnostics, MCP server). */ version?: string /** * Silence the notice recommending Vite DevTools. See {@link viteDevframeHub}. * * @default false */ quiet?: boolean /** * Also bake the hub into `vite build` output: `buildHub` writes the whole * static hub subtree (each devframe's SPA, the RPC dump, `embedded.js`, …) * into ``, and the UI's `embedded.js` script tag is injected * into the built HTML, so the deployed app ships working devtools against * a `static` backend (baked reads, no live server). Off by default: a * production bundle only carries devtools when the host opts in. * * @default false */ build?: boolean } let recommendedViteDevtools = false function recommendViteDevtools(): void { if (recommendedViteDevtools) return recommendedViteDevtools = true console.warn( '[@devframes/vite/hub] Serving a devframes-hub directly inside Vite works, ' + 'but Vite DevTools (`@vitejs/devtools-kit`) integrates the hub protocol ' + 'natively, so prefer it for a first-class, multi-integration experience. ' + 'Pass `{ quiet: true }` to silence this notice.', ) } /** * Mount a whole **devframes-hub** (many integrations under one namespace, * one merged RPC registry, one WebSocket) inside an existing Vite dev * server. One `initHub()` call, mounted as connect middleware; the WebSocket * shares Vite's own HTTP server (upgrading at `__ws`) unless a `port` * pins a side-car. The UI defaults to `@devframes/hub-ui` (its `embedded.js` * bootstrap is injected into the host page automatically); pass `ui` to swap * it or `ui: false` for a headless hub you drive with `@devframes/hub/client`. * * This mounts one integration-agnostic hub. Vite DevTools * (`@vitejs/devtools-kit`) integrates the same hub protocol natively and is * the recommended path for a Vite app, so this plugin emits a one-time notice * to that effect (silence it with `{ quiet: true }`). For dev-serving a * single devframe's own SPA, reach for `@devframes/vite/single` instead. */ export function viteDevframeHub(options: ViteDevframeHubOptions = {}): Plugin { const base = normalizeHubBase(options.base ?? DEVFRAMES_HUB_BASE) let viteConfig: ResolvedConfig | undefined let instance: HubInstance | undefined // Set once the hub is up if its UI ships an `embedded.js` bootstrap: the // host-page script tag `transformIndexHtml` injects. let embeddedSrc: string | undefined // Resolved once for a static build, shared by `buildStart` (embedded.js // injection) and `closeBundle` (the buildHub emit). let buildUi: DevframeHubUi | undefined const teardown = async (): Promise => { const previous = instance instance = undefined await previous?.close().catch(() => {}) } const resolveUi = async (): Promise => options.ui === false ? undefined : options.ui ?? await loadDefaultUi() return { name: 'devframes:hub', /** * Dev middleware by default; a production bundle only carries the hub * when the host opts into the static build. */ apply: (_, env) => env.command === 'serve' || options.build === true, configResolved(config) { viteConfig = config }, async configureServer(server: ViteDevServer) { if (!options.quiet) recommendViteDevtools() // Vite re-invokes `configureServer` on each restart, so tear down the // previous instance so we don't leak the WS binding or a registry record. await teardown() const cwd = options.cwd ?? viteConfig?.root ?? process.cwd() // Resolve the UI slot: default to `@devframes/hub-ui`'s `createUi()` // (lazy import so `@devframes/hub-ui` stays an optional dependency), // honor an explicit object, or stay headless on `false`. const ui = await resolveUi() // Attach each configured client script to its devframe's mount entry so // the hub client runtime imports it into the host page. const devframes = attachClientScripts(options.devframes, options.clientScripts) // `server.https` makes Vite use an `Http2SecureServer`, not a `node:http` // `Server`. It still emits `upgrade` for HTTP/1.1, so the cast is safe. const httpServer = (server.httpServer ?? undefined) as NodeHttpServer | undefined const hub = initHub({ base, cwd, /** * Bare-specifier client scripts resolve through Vite's own module * graph: `/@id/` routes the import (and its transitive * bare imports) through Vite's resolution and import-analysis. */ clientModuleResolution: '/@id/{specifier}', origin: options.origin ?? (() => { const resolved = server.resolvedUrls?.local?.[0] return resolved ? new URL(resolved).origin : '' }), auth: options.auth, /** * Share Vite's own HTTP server for the WS upgrade at `__ws`, with no * side-car port to discover. A pinned `port` uses a side-car instead, * and a middleware-mode Vite (no `httpServer`) asks for an auto-port * side-car. Clients discover either via `__connection.json`. */ server: httpServer, ...resolveWsBinding(options.port, httpServer), ...(ui ? { ui } : {}), devframes, ...pickDefined(options, [ 'host', 'renderers', 'rpcDeclarations', 'mcp', 'register', 'getStorageDir', 'name', 'version', 'configure', ]), }) instance = hub embeddedSrc = ui?.embedded ? `${base}embedded.js` : undefined // One namespace, one catch-all: the middleware serves everything under // `base` and `next()`s the rest back to Vite. server.middlewares.use(hub.nodeMiddleware) server.httpServer?.once('close', () => { if (instance !== hub) return void teardown() }) }, async buildStart() { // Static build: resolve the UI slot up front so `transformIndexHtml` // (which runs before the bundle closes) knows whether to inject the // `embedded.js` bootstrap into the built HTML. if (viteConfig?.command !== 'build' || !options.build) return buildUi = await resolveUi() embeddedSrc = buildUi?.embedded ? `${base}embedded.js` : undefined }, transformIndexHtml() { // Inject the floating-dock bootstrap when the resolved UI ships one. if (!embeddedSrc) return return [ { tag: 'script', attrs: { type: 'module', src: embeddedSrc }, injectTo: 'body', }, ] }, async closeBundle() { await teardown() // Static build: bake the whole hub into the app's build output at // ``, so the deployed bundle serves working devtools // (baked reads over the `static` backend) from any static file server. if (viteConfig?.command !== 'build' || !options.build) return const cwd = options.cwd ?? viteConfig.root const { buildHub } = await import('@devframes/hub/build') await buildHub({ base, cwd, outDir: resolve(viteConfig.root, viteConfig.build.outDir, base.slice(1)), devframes: attachClientScripts(options.devframes, options.clientScripts) ?? [], ...(buildUi ? { ui: buildUi } : {}), ...pickDefined(options, [ 'renderers', 'rpcDeclarations', 'getStorageDir', 'name', 'version', 'configure', ]), }) }, } } /** * Share Vite's own HTTP server for the WS upgrade unless a `port` pins a * side-car, or there is no server to share (middleware mode), which needs an * auto-port side-car. */ function resolveWsBinding(port: number | undefined, httpServer: NodeHttpServer | undefined): { ws?: { port: number } | { sidecar: true } } { if (port != null) { return { ws: { port }, } } return httpServer ? {} : { ws: { sidecar: true }, } } /** Forward only the options a caller actually set. */ function pickDefined(source: T, keys: readonly K[]): Partial> { const out: Partial> = {} for (const key of keys) { const value = source[key] if (value != null) out[key] = value } return out } /** Lazy-load `@devframes/hub-ui`'s default UI so it stays an optional dep. */ async function loadDefaultUi(): Promise { const { createUi } = await import('@devframes/hub-ui') return createUi() } /** Attach per-id client scripts to their devframe mount entries. */ function attachClientScripts( devframes: InitHubOptions['devframes'], clientScripts: Record | undefined, ): InitHubOptions['devframes'] { if (!devframes || !clientScripts) return devframes return devframes.map((entry) => { // Leave thenables / factories untouched; they resolve to their own entries. if (typeof entry === 'function' || entry instanceof Promise) return entry const def = (entry && typeof entry === 'object' && 'devframe' in entry ? (entry as HubDevframeEntry).devframe : entry) as DevframeDefinition | undefined const clientScript = def ? clientScripts[def.id] : undefined if (!def || !clientScript) return entry return 'devframe' in (entry as object) ? { ...(entry as HubDevframeEntry), dock: { clientScript, ...(entry as HubDevframeEntry).dock }, } : { devframe: def, dock: { clientScript }, } }) }