|
| 1 | +import type { DevframeHubContext } from '@devframes/hub/node' |
| 2 | +import type { ClientScriptEntry } from '@devframes/hub/types' |
| 3 | +import type { DevframeDefinition, DevframeHost } from 'devframe/types' |
| 4 | +import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite' |
| 5 | +import { homedir } from 'node:os' |
| 6 | +import { createHubContext, mountDevframe } from '@devframes/hub/node' |
| 7 | +import { DEVFRAME_CONNECTION_META_FILENAME } from 'devframe/constants' |
| 8 | +import { startHttpAndWs } from 'devframe/node' |
| 9 | +import { serveStaticNodeMiddleware } from 'devframe/utils/serve-static' |
| 10 | +import { getPort } from 'get-port-please' |
| 11 | +import { join } from 'pathe' |
| 12 | + |
| 13 | +export interface A11yMessagesPlaygroundOptions { |
| 14 | + /** Mount path for the hub's connection-meta endpoint. Default: `/__hub/`. */ |
| 15 | + base?: string |
| 16 | + /** Preferred port for the side-car RPC/WS server. Default: a free port near 9878. */ |
| 17 | + port?: number |
| 18 | + /** Devframes to mount as docks (here: a11y + messages). */ |
| 19 | + devframes?: DevframeDefinition[] |
| 20 | + /** |
| 21 | + * Per-dock client scripts, keyed by devframe id. Attached to the mounted |
| 22 | + * iframe dock so the hub client runtime imports them into the host page — |
| 23 | + * this is how the a11y inspector's in-page agent gets into the page it scans. |
| 24 | + */ |
| 25 | + clientScripts?: Record<string, ClientScriptEntry> |
| 26 | +} |
| 27 | + |
| 28 | +/** |
| 29 | + * A tiny Vite plugin that runs `@devframes/hub` inside the Vite dev server — |
| 30 | + * the same shape as `examples/minimal-vite-devframe-hub`, trimmed to the two |
| 31 | + * plugins this playground pairs (a11y + messages). It creates a hub context, |
| 32 | + * implements the framework-neutral `DevframeHost` surface, mounts each devframe |
| 33 | + * as a dock (attaching the a11y agent as its client script), and exposes the |
| 34 | + * side-car WS endpoint at `<base>__connection.json`. |
| 35 | + */ |
| 36 | +export function a11yMessagesPlayground(options: A11yMessagesPlaygroundOptions = {}): Plugin { |
| 37 | + const base = normalizeBase(options.base ?? '/__hub/') |
| 38 | + let viteConfig: ResolvedConfig | undefined |
| 39 | + let started: { close: () => Promise<void> } | undefined |
| 40 | + |
| 41 | + return { |
| 42 | + name: 'a11y-messages-playground', |
| 43 | + apply: 'serve', |
| 44 | + |
| 45 | + configResolved(config) { |
| 46 | + viteConfig = config |
| 47 | + }, |
| 48 | + |
| 49 | + async configureServer(server: ViteDevServer) { |
| 50 | + // Vite re-invokes `configureServer` on restart — tear the old server down |
| 51 | + // so we don't leak the WS port. |
| 52 | + await started?.close().catch(() => {}) |
| 53 | + started = undefined |
| 54 | + |
| 55 | + const cwd = viteConfig!.root |
| 56 | + const port = options.port ?? await getPort({ port: 9878, portRange: [9878, 9978] }) |
| 57 | + |
| 58 | + const serveConnectionMeta = (metaBase: string): void => { |
| 59 | + const metaPath = `${metaBase}${DEVFRAME_CONNECTION_META_FILENAME}` |
| 60 | + server.middlewares.use(metaPath, (_req, res) => { |
| 61 | + res.setHeader('Content-Type', 'application/json') |
| 62 | + res.end(JSON.stringify({ backend: 'websocket', websocket: port })) |
| 63 | + }) |
| 64 | + } |
| 65 | + |
| 66 | + const host: DevframeHost = { |
| 67 | + mountStatic(base, distDir) { |
| 68 | + server.middlewares.use(base, serveStaticNodeMiddleware(distDir)) |
| 69 | + }, |
| 70 | + mountConnectionMeta(base) { |
| 71 | + serveConnectionMeta(base) |
| 72 | + }, |
| 73 | + resolveOrigin() { |
| 74 | + const resolved = server.resolvedUrls?.local?.[0] |
| 75 | + return resolved ? new URL(resolved).origin : 'http://localhost:5173' |
| 76 | + }, |
| 77 | + getStorageDir(scope) { |
| 78 | + if (scope === 'workspace') |
| 79 | + return join(cwd, '.devframe') |
| 80 | + if (scope === 'project') |
| 81 | + return join(cwd, 'node_modules/.a11y-messages-playground') |
| 82 | + return join(homedir(), '.a11y-messages-playground') |
| 83 | + }, |
| 84 | + } |
| 85 | + |
| 86 | + const context: DevframeHubContext = await createHubContext({ |
| 87 | + cwd, |
| 88 | + workspaceRoot: cwd, |
| 89 | + mode: 'dev', |
| 90 | + host, |
| 91 | + }) |
| 92 | + |
| 93 | + // Mount each devframe as a dock, attaching its client script when one is |
| 94 | + // configured (the a11y agent). `mountDevframe` runs the def's `setup(ctx)`, |
| 95 | + // so `setupA11y` / `setupMessages` register their RPCs automatically. |
| 96 | + for (const def of options.devframes ?? []) { |
| 97 | + const clientScript = options.clientScripts?.[def.id] |
| 98 | + await mountDevframe(context, def, clientScript ? { dock: { clientScript } } : undefined) |
| 99 | + } |
| 100 | + |
| 101 | + started = await startHttpAndWs({ context, port, auth: false }) |
| 102 | + |
| 103 | + // Tell the hub UI (served at `base`) where to find the WS endpoint. |
| 104 | + serveConnectionMeta(base) |
| 105 | + |
| 106 | + server.httpServer?.once('close', () => { |
| 107 | + void started?.close().catch(() => {}) |
| 108 | + }) |
| 109 | + }, |
| 110 | + |
| 111 | + async closeBundle() { |
| 112 | + await started?.close().catch(() => {}) |
| 113 | + started = undefined |
| 114 | + }, |
| 115 | + } |
| 116 | +} |
| 117 | + |
| 118 | +function normalizeBase(base: string): string { |
| 119 | + let out = base.startsWith('/') ? base : `/${base}` |
| 120 | + if (!out.endsWith('/')) |
| 121 | + out = `${out}/` |
| 122 | + return out |
| 123 | +} |
0 commit comments