feat(examples): dogfood the built-in plugins in the minimal hubs

Mount @devframes/plugin-git, -terminals, and -code-server in both the Vite and Next minimal hub examples so they exercise real RPC, streaming, and child-process integrations end to end.

Both hosts now serve per-devframe connection meta. The Next host loads the plugins through a bundler-ignored dynamic import and skips trailing-slash redirects so the published SPAs resolve their assets and connect. Adds a bundled-host recipe to the hub guide and the missing plugin-git source alias.

Author: antfubot

alias.ts

@@ -60,6 +60,7 @@ export const alias = {
   '@devframes/plugin-terminals/cli': p('terminals/src/cli.ts'),
   '@devframes/plugin-terminals/vite': p('terminals/src/vite.ts'),
   '@devframes/plugin-terminals': p('terminals/src/index.ts'),
+  '@devframes/plugin-git': p('git/src/index.ts'),
   'devframe/recipes/open-helpers': r('devframe/src/recipes/open-helpers.ts'),
   'devframe/client': r('devframe/src/client/index.ts'),
   'devframe': r('devframe/src'),

docs/guide/hub.md

@@ -43,6 +43,46 @@ await mountDevframe(ctx, myDevframe)
 
 Framework kits typically wrap this in a plugin shell. `@vitejs/devtools-kit`'s `createPluginFromDevframe` returns a Vite `Plugin` whose `devtools.setup` calls into `mountDevframe`.
 
+### Connecting embedded SPAs
+
+A mounted devframe's SPA loads in an iframe at its base (`/__<id>/`) and calls `connectDevframe()`, which fetches `./__connection.json` relative to that base. `mountDevframe` serves it there by calling the host's `mountConnectionMeta(base)` alongside `mountStatic`, so the SPA discovers the RPC/WS endpoint directly. Implement `mountConnectionMeta` on your `DevframeHost` to serve the same connection meta you expose at the hub's own base:
+
+```ts
+const host: DevframeHost = {
+  mountStatic(base, distDir) { /* serve files */ },
+  mountConnectionMeta(base) {
+    // serve `${base}__connection.json` → { backend: 'websocket', websocket: port }
+  },
+  resolveOrigin() { /* … */ },
+  getStorageDir(scope) { /* … */ },
+}
+```
+
+Hosts that omit `mountConnectionMeta` fall back to same-origin window inheritance, which connects an embedded SPA only when it shares an origin with the hub UI.
+
+### Bundled hosts (Next.js)
+
+Dev servers with a module bundler (Next's Turbopack/webpack) statically analyse server imports. Plugin packages resolve their SPA dist with `new URL('../dist/...', import.meta.url)` and lazy-load node-side code — child processes, the native `node-pty` PTY backend — that resolves at runtime, not at bundle time. Load them with a dynamic `import()` carrying ignore comments so the bundler keeps them as a runtime Node import:
+
+```ts
+const pkgs = ['@devframes/plugin-git', '@devframes/plugin-terminals']
+const defs = await Promise.all(
+  pkgs.map(p => import(/* webpackIgnore: true */ /* turbopackIgnore: true */ p)),
+).then(mods => mods.map(m => m.default))
+
+for (const def of defs)
+  await mountDevframe(ctx, def)
+```
+
+Each mounted SPA is served at `/__<id>/` and references its assets relatively (`./_next/…`, `./assets/…`). Disable the bundler's trailing-slash redirect so those paths resolve under the mount base:
+
+```js
+// next.config.mjs
+export default { skipTrailingSlashRedirect: true }
+```
+
+[`examples/minimal-next-devframe-hub/`](https://github.com/devframes/devframe/tree/main/examples/minimal-next-devframe-hub) is a working Next.js App Router host that mounts the built-in plugins this way.
+
 ### Duplicate devframes
 
 When a devframe sharing an already-mounted `id` is mounted onto the same hub, its `duplicationStrategy` decides what happens. By default the first registration wins:

examples/minimal-next-devframe-hub/package.json

@@ -6,12 +6,15 @@
   "description": "Protocol-witness example — a tiny Next.js Devframe Hub built on @devframes/hub that exercises every hub subsystem end-to-end.",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/minimal-next-devframe-hub",
   "scripts": {
-    "dev": "next dev src/client",
+    "dev": "next dev src/client -H 0.0.0.0",
     "build": "next build src/client",
     "test": "vitest run --config vitest.config.ts"
   },
   "dependencies": {
     "@devframes/hub": "workspace:*",
+    "@devframes/plugin-code-server": "workspace:*",
+    "@devframes/plugin-git": "workspace:*",
+    "@devframes/plugin-terminals": "workspace:*",
     "devframe": "workspace:*",
     "next": "catalog:frontend",
     "react": "catalog:frontend",

examples/minimal-next-devframe-hub/src/client/app/%5F_[id]/[[...path]]/route.ts

@@ -2,7 +2,7 @@ import { createReadStream } from 'node:fs'
 import { stat } from 'node:fs/promises'
 import { Readable } from 'node:stream'
 import { extname, join, normalize, resolve, sep } from 'pathe'
-import { ensureMinimalNextDevframeHub, getStaticMount } from '../../../devframe/minimal-next-devframe-hub'
+import { ensureMinimalNextDevframeHub, getStaticMount, isConnectionMetaPath } from '../../../devframe/minimal-next-devframe-hub'
 
 export const runtime = 'nodejs'
 export const dynamic = 'force-dynamic'
@@ -80,9 +80,15 @@ async function resolveTarget(absDir: string, urlPath: string): Promise<ResolvedF
 }
 
 export async function GET(request: Request): Promise<Response> {
-  await ensureMinimalNextDevframeHub()
+  const hub = await ensureMinimalNextDevframeHub()
 
   const pathname = new URL(request.url).pathname
+
+  // A mounted devframe SPA fetches `<base>/__connection.json` to discover the
+  // side-car WS endpoint. Answer it with the hub's connection meta.
+  if (isConnectionMetaPath(pathname))
+    return Response.json(hub.connectionMeta)
+
   const hit = getStaticMount(pathname)
   if (!hit)
     return new Response(null, { status: 404 })

examples/minimal-next-devframe-hub/src/client/devframe/minimal-next-devframe-hub.ts

@@ -5,12 +5,39 @@ import { homedir } from 'node:os'
 import process from 'node:process'
 import { defineHubRpcFunction } from '@devframes/hub'
 import { createHubContext, mountDevframe } from '@devframes/hub/node'
+import { DEVFRAME_CONNECTION_META_FILENAME } from 'devframe/constants'
 import { startHttpAndWs } from 'devframe/node'
 import { getPort } from 'get-port-please'
 import { join } from 'pathe'
 import demoDevframe from './demo-devframe'
 import demoDevframeB from './demo-devframe-b'
 
+/**
+ * Built-in plugin packages dogfooded through the hub mount path.
+ *
+ * They are loaded with a runtime dynamic `import()` carrying
+ * `webpackIgnore` / `turbopackIgnore` magic comments so Next's bundler leaves
+ * them alone: Node resolves the published `dist` at request time, where the
+ * plugins' node-side code (git shell-outs, child-process supervisors, the
+ * native `node-pty` PTY backend) and their `new URL('../dist/...',
+ * import.meta.url)` SPA-dist lookups all work — none of which survive being
+ * statically bundled into a Next server chunk.
+ */
+const BUILTIN_PLUGIN_PACKAGES = [
+  '@devframes/plugin-git',
+  '@devframes/plugin-terminals',
+  '@devframes/plugin-code-server',
+] as const
+
+async function loadBuiltinPlugins(): Promise<DevframeDefinition[]> {
+  const mods = await Promise.all(
+    BUILTIN_PLUGIN_PACKAGES.map(
+      pkg => import(/* webpackIgnore: true */ /* turbopackIgnore: true */ pkg),
+    ),
+  )
+  return mods.map(mod => mod.default as DevframeDefinition)
+}
+
 const STATIC_MOUNTS = new Map<string, string>()
 
 export interface StaticMountHit {
@@ -32,6 +59,23 @@ export function getStaticMount(pathname: string): StaticMountHit | null {
   return { distDir: best.distDir, relative }
 }
 
+// Bases (without trailing slash, e.g. `/__git`) under which the catch-all
+// route should serve the hub's connection meta at `<base>/__connection.json`.
+const CONNECTION_META_BASES = new Set<string>()
+const META_SUFFIX = `/${DEVFRAME_CONNECTION_META_FILENAME}`
+
+/**
+ * If `pathname` is a `<base>/__connection.json` request for a base the hub
+ * registered via `DevframeHost.mountConnectionMeta`, return that base;
+ * otherwise `null`. The catch-all route uses this to answer the connection-meta
+ * fetch a mounted devframe SPA makes from inside its iframe.
+ */
+export function isConnectionMetaPath(pathname: string): boolean {
+  if (!pathname.endsWith(META_SUFFIX))
+    return false
+  return CONNECTION_META_BASES.has(pathname.slice(0, -META_SUFFIX.length))
+}
+
 export interface MinimalNextDevframeHubOptions {
   /** Preferred port for the side-car RPC/WS server. Default: a free port near 9877. */
   port?: number
@@ -85,6 +129,12 @@ export async function minimalNextDevframeHub(
     mountStatic(base, distDir) {
       STATIC_MOUNTS.set(base.replace(/\/$/, ''), distDir)
     },
+    // Record the base so the catch-all route can answer `<base>/__connection.json`
+    // with the hub's connection meta — letting the mounted SPA connect without
+    // relying on same-origin parent-window inheritance.
+    mountConnectionMeta(base) {
+      CONNECTION_META_BASES.add(base.replace(/\/$/, ''))
+    },
     resolveOrigin() {
       return `http://${hostName}:3000`
     },
@@ -116,13 +166,17 @@ export async function minimalNextDevframeHub(
     handler: () => 'pong',
   })
 
+  // Demo devframes alongside the dogfooded built-in plugin packages.
+  const devframes = options.devframes
+    ?? [demoDevframe, demoDevframeB, ...await loadBuiltinPlugins()]
+
   await context.messages.add({
     level: 'success',
     message: 'Minimal Next Devframe Hub started',
-    description: `Side-car WS on port ${port}. ${options.devframes?.length ?? 1} devframe(s) registered.`,
+    description: `Side-car WS on port ${port}. ${devframes.length} devframe(s) registered.`,
   })
 
-  for (const def of options.devframes ?? [demoDevframe, demoDevframeB]) {
+  for (const def of devframes) {
     await mountDevframe(context, def)
   }
 

examples/minimal-next-devframe-hub/src/client/next.config.mjs

@@ -3,6 +3,12 @@ const nextConfig = {
   images: { unoptimized: true },
   // The workspace typecheck owns source-level project references.
   typescript: { ignoreBuildErrors: true },
+  // Mounted devframe SPAs are served at `/__<id>/` and reference their assets
+  // relatively (`./_next/…`, `./assets/…`). Next's default trailing-slash
+  // redirect (`/__git/` → `/__git`) would re-root those relative paths and 404
+  // every asset, leaving the panel unstyled and unable to connect. Serving the
+  // base path verbatim keeps the SPA's relative asset resolution intact.
+  skipTrailingSlashRedirect: true,
 }
 
 export default nextConfig

examples/minimal-vite-devframe-hub/package.json

@@ -6,11 +6,14 @@
   "description": "Protocol-witness example — a tiny Vite Devframe Hub built on @devframes/hub that exercises every hub subsystem end-to-end.",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/minimal-vite-devframe-hub",
   "scripts": {
-    "dev": "vite",
+    "dev": "vite --host",
     "build": "vite build"
   },
   "dependencies": {
     "@devframes/hub": "workspace:*",
+    "@devframes/plugin-code-server": "workspace:*",
+    "@devframes/plugin-git": "workspace:*",
+    "@devframes/plugin-terminals": "workspace:*",
     "devframe": "workspace:*"
   },
   "devDependencies": {

examples/minimal-vite-devframe-hub/src/minimal-vite-devframe-hub.ts

@@ -77,11 +77,29 @@ export function minimalViteDevframeHub(options: MinimalViteDevframeHubOptions =
       started = undefined
 
       const cwd = viteConfig!.root
+      const port = options.port ?? await getPort({ port: 9777, random: false })
+
+      // Serve the side-car's connection meta (`__connection.json`) at a URL
+      // base so a browser loaded there can discover the WS endpoint via
+      // `connectDevframe()`'s relative `./__connection.json` fetch.
+      const serveConnectionMeta = (metaBase: string): void => {
+        const metaPath = `${metaBase}${DEVFRAME_CONNECTION_META_FILENAME}`
+        server.middlewares.use(metaPath, (_req, res) => {
+          res.setHeader('Content-Type', 'application/json')
+          res.end(JSON.stringify({ backend: 'websocket', websocket: port }))
+        })
+      }
 
       const host: DevframeHost = {
         mountStatic(base, distDir) {
           server.middlewares.use(base, serveStaticNodeMiddleware(distDir))
         },
+        // Serve `<base>__connection.json` for each mounted devframe so its
+        // SPA connects to the hub without relying on same-origin parent-window
+        // inheritance — which breaks for cross-origin / sandboxed iframes.
+        mountConnectionMeta(base) {
+          serveConnectionMeta(base)
+        },
         resolveOrigin() {
           const resolved = server.resolvedUrls?.local?.[0]
           return resolved ? new URL(resolved).origin : 'http://localhost:5173'
@@ -93,8 +111,6 @@ export function minimalViteDevframeHub(options: MinimalViteDevframeHubOptions =
         },
       }
 
-      const port = options.port ?? await getPort({ port: 9777, random: false })
-
       const context = await createHubContext({
         cwd,
         workspaceRoot: cwd,
@@ -135,13 +151,8 @@ export function minimalViteDevframeHub(options: MinimalViteDevframeHubOptions =
         auth: false,
       })
 
-      // Tell the browser where to find the WS endpoint. `connectDevframe`
-      // resolves this URL relative to its `baseURL` option.
-      const metaPath = `${base}${DEVFRAME_CONNECTION_META_FILENAME}`
-      server.middlewares.use(metaPath, (_req, res) => {
-        res.setHeader('Content-Type', 'application/json')
-        res.end(JSON.stringify({ backend: 'websocket', websocket: port }))
-      })
+      // Tell the hub UI (served at `base`) where to find the WS endpoint.
+      serveConnectionMeta(base)
 
       server.httpServer?.once('close', () => {
         void started?.close().catch(() => {})

examples/minimal-vite-devframe-hub/vite.config.ts

@@ -1,3 +1,6 @@
+import codeServerDevframe from '@devframes/plugin-code-server'
+import gitDevframe from '@devframes/plugin-git'
+import terminalsDevframe from '@devframes/plugin-terminals'
 import { defineConfig } from 'vite'
 import { alias } from '../../alias'
 import demoDevframe from './src/devframe'
@@ -8,7 +11,14 @@ export default defineConfig({
   resolve: { alias },
   plugins: [
     minimalViteDevframeHub({
-      devframes: [demoDevframe, demoDevframeB],
+      devframes: [
+        demoDevframe,
+        demoDevframeB,
+        // Built-in plugins, dogfooded end-to-end through the hub mount path.
+        gitDevframe,
+        terminalsDevframe,
+        codeServerDevframe,
+      ],
     }),
   ],
 })