@ggui-ai/cli 0.1.0-rc.1

package/dist/mcp-backend.js

@@ -0,0 +1,668 @@
+/**
+ * `ggui serve` → `@ggui-ai/mcp-server` composition.
+ *
+ * Split out from `cli.ts` so tests can import the factory without
+ * triggering the CLI `main()` side-effect at module load. The banner /
+ * signal / lifecycle wiring stays in `cli.ts` / `serve-command.ts`;
+ * this module owns exactly one thing: the option bundle that turns
+ * `createGguiServer()` into the canonical OSS first-run server.
+ *
+ * What gets wired by default — see OSS-split §2 (the five server
+ * responsibilities):
+ *
+ *   - `sessionChannel: true` — live-channel `/ws` endpoint. Required for
+ *     MCP Apps iframes AND the console session viewer.
+ *   - `pairing: true` — `POST /pair` + `POST /admin/pair/init` so
+ *     remote clients (Portal, third-party) can pair with this server.
+ *     The default `InMemoryAuthAdapter` registers pairing tokens
+ *     through `onTokenIssued` automatically.
+ *   - `console: { sessionCookie: true }` — landing page at `/` +
+ *     `/s/<shortCode>` viewer + same-origin HTTP-only cookie flow.
+ *   - `shortCodeIndex: new InMemoryShortCodeIndex()` — required by
+ *     the `sessionCookie` flow so `POST /ggui/console/session-cookie`
+ *     can resolve a posted shortCode to `{sessionId, appId}`.
+ *     In-memory is correct for the OSS first-run: session state lives
+ *     in memory unless the operator opts into sqlite, so a matching
+ *     index lifetime is what operators expect.
+ *   - `mcpApps: { renderBaseUrl, wsUrl }` — registers the `ggui_push`
+ *     tool with MCP Apps `_meta.ui.*` declaration, serves
+ *     `ui://ggui/session`, and advertises the `io.modelcontextprotocol/ui`
+ *     capability. Without this the console `/s/<shortCode>` viewer
+ *     is orphaned — there's no tool minting shortCodes. Resolved host +
+ *     port are mandatory so the agent-returned `url` resolves to this
+ *     same server's `/s/` endpoint. See §2.4.1 "sole entry-point tool"
+ *     lock in the OSS-split plan.
+ *
+ * Embedding hosts that want a different shape (no landing page, no
+ * pairing, programmatic control) compose `createGguiServer()` directly
+ * rather than going through `ggui serve`.
+ */
+import { createServer as createNetServer } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { composeWiredActionRouterFromMounts, createGguiServer, DEFAULT_BUILDER_APP_ID, FileSystemCodeStore, FixedWindowRateLimiter, InMemoryAuthAdapter, InMemoryQuotaStore, InMemoryShortCodeIndex, selectEmailSenderFromEnv, } from '@ggui-ai/mcp-server';
+import { createDeterministicPreviewEmitter } from '@ggui-ai/preview-a2ui/emitters';
+import { RUNTIME_BUNDLE_URL_PATH } from '@ggui-ai/iframe-runtime/server';
+import { createLocalEmbeddingProvider } from '@ggui-ai/embedding-local';
+import { PlaintextFileProviderKeyStore } from '@ggui-ai/mcp-server-core/plaintext';
+import { InMemoryAppMetadataStore, InMemoryVectorStore } from '@ggui-ai/mcp-server-core/in-memory';
+import { listThemes } from '@ggui-ai/design/themes';
+import { createInstalledBlueprintsProvider, } from '@ggui-ai/mcp-server-handlers/session-mutations';
+import { compileUiOnDemand } from '@ggui-ai/dev-stack';
+import { getCodeCacheDir, getCredentialsFile, getEmbeddingCacheDir, } from './paths.js';
+import { readOrMintHexSecret } from './persistent-secrets.js';
+import { join } from 'node:path';
+/**
+ * Pick a free localhost TCP port by letting the OS assign one on a
+ * throwaway listener. Close the listener immediately and return the
+ * chosen number. Exported so the CLI (`cli.ts::runServeCommand`) and
+ * the integration tests can resolve `--port 0` to a concrete port
+ * BEFORE constructing the backend — {@link buildMcpServerBackend}
+ * captures the port in the composed `mcpApps.renderBaseUrl` / `wsUrl`
+ * at construction time, so the caller must know it up-front.
+ *
+ * Tiny race window: another process could claim the port between our
+ * `close()` and the caller's `listen()`. The CLI surfaces bind errors
+ * as a fatal exit; the OSS first-run path recovers by re-running.
+ */
+export function pickFreePort(host = '127.0.0.1') {
+    return new Promise((resolve, reject) => {
+        const probe = createNetServer();
+        probe.once('error', (err) => {
+            probe.close();
+            reject(err);
+        });
+        probe.listen(0, host, () => {
+            const addr = probe.address();
+            if (addr === null || typeof addr === 'string') {
+                probe.close();
+                reject(new Error(`pickFreePort: could not resolve a free port (got ${String(addr)})`));
+                return;
+            }
+            const chosen = addr.port;
+            probe.close(() => resolve(chosen));
+        });
+    });
+}
+/**
+ * Build the `ServeBackend` that `runServe` drives. Returns a thin
+ * adapter around `createGguiServer` — the factory is invoked here so
+ * preconditions that throw (e.g. missing auth bridge support for
+ * `pairing: true`) surface synchronously, before `runServe` bothers
+ * binding a port.
+ */
+export function buildMcpServerBackend(opts) {
+    const storage = opts.storage ?? {};
+    if (!Number.isInteger(opts.port) || opts.port <= 0 || opts.port > 65535) {
+        throw new Error(`buildMcpServerBackend: \`port\` must be a concrete TCP port (1..65535), got ${opts.port}. Resolve \`--port 0\` via pickFreePort() before composing.`);
+    }
+    // `baseUrl` feeds `mcpApps.renderBaseUrl` + `runtime.url`; `wsBaseUrl`
+    // feeds `mcpApps.wsUrl`. With `--public-base-url`, both derive from
+    // the operator-provided tunnel URL so the agent emits links that
+    // resolve from the remote host's perspective. Without it, both fall
+    // back to the local bind. The shape was validated at flag-parse
+    // time (`http://`/`https://`, no trailing slash); we just substitute
+    // the scheme for ws/wss to derive the live-channel URL.
+    const baseUrl = opts.publicBaseUrl ?? `http://${opts.host}:${opts.port}`;
+    const wsBaseUrl = baseUrl.replace(/^http(s?):\/\//, 'ws$1://');
+    // Router over the mount handler bundle. Computed once; absent
+    // (`null`) when no mounts are declared so the server falls through
+    // to agent-routed behavior.
+    const wiredActionRouter = composeWiredActionRouterFromMounts(opts.mcpMounts, () => ({
+        appId: DEFAULT_BUILDER_APP_ID,
+        requestId: randomUUID(),
+    }));
+    // Strict-auth OSS default (`devAllowAll: false`). `createGguiServer`
+    // would otherwise fall back to `InMemoryAuthAdapter({ devAllowAll:
+    // true })`, which authenticates any non-empty bearer as builder — a
+    // permissive seam that makes the `/mcp` ingress indistinguishable
+    // from "no auth at all" for operators running `ggui serve`. Pairing
+    // is on by default (see `pairing: true` below), so the honest
+    // first-run story is: mint an initial pair code → complete `/pair`
+    // → use the resulting token. The CLI surfaces that initial code as
+    // the `PAIR_CODE` boot beacon + banner line; see `runServe` in
+    // `./serve-command.ts`.
+    //
+    // `--dev-allow-all` flips this to `true` for local-dev / tunnel
+    // smoke against MCP custom connectors that probe `/mcp` without
+    // bearer (claude.ai, ChatGPT). The banner prints a loud warning
+    // and pair-code emission is suppressed (meaningless under allow-all)
+    // so operators don't accidentally take the dev posture to production.
+    // `--public-demo` shares the auth shape with `--dev-allow-all`
+    // (every bearer = builder). The CLI guarantees these are mutually
+    // exclusive at parse time; only one is ever true here.
+    const auth = new InMemoryAuthAdapter({
+        devAllowAll: (opts.devAllowAll ?? false) || (opts.publicDemo ?? false),
+    });
+    // Per-IP rate limiter — only bound under `--public-demo` so an
+    // anonymous visitor can't burn the operator's BYOK budget by pumping
+    // ggui_push. Defaults: 30 generations / 10 minutes per IP. Operators
+    // who need different ceilings construct their own backend
+    // programmatically (calling `createGguiServer({ rateLimiter })`
+    // directly). Skipped under `--dev-allow-all` because that's the
+    // single-operator escape hatch where rate limits add noise without
+    // protection.
+    const rateLimiter = opts.publicDemo
+        ? new FixedWindowRateLimiter({
+            store: new InMemoryQuotaStore(),
+            limit: 30,
+            windowMs: 10 * 60 * 1000,
+        })
+        : undefined;
+    // Local-transformer embedder default. Replaces the server's
+    // `MockEmbeddingProvider` last-resort fallback for the user-facing
+    // OSS path. `bge-small-en-v1.5` (~33MB ONNX) downloads lazily into
+    // `~/.ggui/models/` on first embed; `cacheDir` resolves to that
+    // path via the CLI's own paths helper. `warmup: true` (the default
+    // inside the provider) embeds a dummy string after the pipeline
+    // first loads so the first real embedding doesn't pay the ~200-
+    // 400ms transformers cold-start tax.
+    //
+    // Programmatic embedders calling `createGguiServer` directly still
+    // get `MockEmbeddingProvider` if they don't bind an embedder — that
+    // keeps the 60MB `@huggingface/transformers` install surface off
+    // the unit-test path.
+    const embedding = createLocalEmbeddingProvider({
+        cacheDir: getEmbeddingCacheDir(),
+    });
+    // BYOK provider-key store — same `~/.ggui/credentials.json` that
+    // `byok-resolver.ts` reads on every `resolve()`. Threading the store
+    // here makes the operator-facing `/ggui/console/llm-keys` admin API
+    // write to the same file generation later reads, with no in-process
+    // sync needed (`PlaintextFileProviderKeyStore` re-reads on every
+    // `get()`). Operators who set `GGUI_CONFIG_DIR` for a clean-room get
+    // the override automatically via `getCredentialsFile()`.
+    const providerKeys = new PlaintextFileProviderKeyStore({
+        filename: getCredentialsFile(),
+    });
+    // Email-login sender selection. Reads `GGUI_EMAIL_SENDER`
+    // (default: `console`) and provider-specific env vars
+    // (`RESEND_API_KEY`, `SMTP_URL` / `SMTP_HOST` + auth, etc.). Misconfig
+    // (e.g. `=resend` without `RESEND_API_KEY`) logs a warning and falls
+    // back to console rather than crashing — the rest of the server still
+    // boots and operators can fix the env without losing other surfaces.
+    // Programmatic embedders that want a different shape compose
+    // `createGguiServer({emailLogin: {sender: ...}})` directly.
+    const emailSenderSelection = selectEmailSenderFromEnv();
+    let emailSender;
+    let emailFromAddress;
+    const defaultFromAddress = 'ggui-serve <noreply@localhost>';
+    if (emailSenderSelection.kind === 'ok') {
+        emailSender = emailSenderSelection.sender;
+        emailFromAddress = emailSenderSelection.fromAddress ?? defaultFromAddress;
+    }
+    else {
+        // eslint-disable-next-line no-console -- one-shot boot warning, mirrors banner output
+        console.warn(`[ggui-cli] email-login: ${emailSenderSelection.reason}; falling back to ConsoleEmailSender (magic links print to terminal).`);
+        const fallback = selectEmailSenderFromEnv({
+            env: { GGUI_EMAIL_SENDER: 'console' },
+        });
+        if (fallback.kind !== 'ok') {
+            throw new Error(`[ggui-cli] email-login: console fallback selection failed: ${fallback.reason}`);
+        }
+        emailSender = fallback.sender;
+        emailFromAddress = process.env.GGUI_EMAIL_FROM?.trim() || defaultFromAddress;
+    }
+    // Resolve cross-restart HMAC secrets. When the caller declared a
+    // persistent dir, read-or-mint `bootstrap-secret.hex` +
+    // `render-signer-secret.hex` (32 bytes / 64 hex chars, 0600). Both
+    // get threaded into `createGguiServer` below so the server stops
+    // minting fresh process-local secrets every boot — the precondition
+    // for any cached `_meta.ggui.bootstrap.token` or `/r/<code>?sig=&exp=`
+    // URL surviving a restart. Absent dir = legacy ephemeral behavior.
+    let persistedBootstrapSecret;
+    let persistedRenderSignerSecret;
+    if (opts.persistentDir !== undefined) {
+        persistedBootstrapSecret = readOrMintHexSecret(join(opts.persistentDir, 'bootstrap-secret.hex'));
+        persistedRenderSignerSecret = readOrMintHexSecret(join(opts.persistentDir, 'render-signer-secret.hex'));
+    }
+    // Resolve mcpInstructions: CLI flag wins over env var. Validated
+    // env-var values pass through to createGguiServer; invalid values
+    // fall through to the no-preset default with a one-line warning.
+    const envInstructions = process.env.GGUI_MCP_INSTRUCTIONS?.trim();
+    let resolvedMcpInstructions = opts.mcpInstructions;
+    if (resolvedMcpInstructions === undefined && envInstructions) {
+        if (envInstructions === 'default' ||
+            envInstructions === 'aggressive' ||
+            envInstructions === 'always' ||
+            envInstructions === 'minimal' ||
+            envInstructions === 'off') {
+            resolvedMcpInstructions = envInstructions;
+        }
+        else {
+            // eslint-disable-next-line no-console -- one-shot boot warning
+            console.warn(`[ggui-cli] GGUI_MCP_INSTRUCTIONS='${envInstructions}' not recognized; falling back to default preset.`);
+        }
+    }
+    // Per-app metadata store seeded from `ggui.json#theme.preset` (when
+    // the manifest declares a preset variant). Single-tenant OSS: any
+    // appId the handlers see picks up this default theme via
+    // `InMemoryAppMetadataStore.get`'s defaults fall-through. File-mode
+    // themes don't have a registry id to surface here — agents pick from
+    // `listThemes()` either way; the file-mode override only affects the
+    // server's bound `theme` (rendered CSS variables), not the
+    // session/handler-side `themeId` chain.
+    const manifestThemePreset = opts.theme?.source === 'preset' ? opts.theme.preset : undefined;
+    const appMetadataStore = new InMemoryAppMetadataStore({
+        ...(manifestThemePreset !== undefined
+            ? { defaultThemeId: manifestThemePreset }
+            : {}),
+        // `ggui.json#app.gadgets` declarations (Leaflet, Mapbox, …). When
+        // omitted, the InMemoryAppMetadataStore falls back to
+        // STDLIB_GADGETS from @ggui-ai/protocol so the first-party hooks
+        // remain available without explicit declaration. The constructor
+        // expects this on `defaultGadgets`, not `gadgets`.
+        ...(opts.gadgets !== undefined && opts.gadgets.length > 0
+            ? { defaultGadgets: opts.gadgets }
+            : {}),
+        // `ggui.json#app.publicEnv` operator-stamped values for wrapper
+        // hooks to read via `getPublicEnv()`. The push gate
+        // (`assertPublicEnvSatisfied`) verifies every declared wrapper's
+        // `requires` keys are present in this map BEFORE the iframe boots.
+        ...(opts.publicEnv !== undefined && Object.keys(opts.publicEnv).length > 0
+            ? { defaultPublicEnv: opts.publicEnv }
+            : {}),
+        // `ggui.json#app.defaultMcpAppsMode`. `'canvas'` makes
+        // `ggui_new_session` mint a session-scoped iframe + route
+        // subsequent pushes through the session channel; absent ⇒ inline.
+        ...(opts.defaultMcpAppsMode !== undefined
+            ? { defaultMcpAppsMode: opts.defaultMcpAppsMode }
+            : {}),
+    });
+    // Materialize the vectorStore here so the marketplace-install
+    // bridge writes into the SAME instance the matcher reads. Without
+    // this, calling `createGguiServer({ vectors })`
+    // when no `storage.vectors` is declared leaves vectorStore
+    // construction inside the server, hidden from us, so the provider
+    // would have no handle to register into. Mint an `InMemoryVectorStore`
+    // here on the absent-storage path; threaded back as `vectors` to
+    // `createGguiServer` so server + provider share state.
+    const vectorStore = storage.vectors ?? new InMemoryVectorStore();
+    // Construct the marketplace-install bridge BEFORE `createGguiServer`
+    // so we can fold it into `opts.generation.installedBlueprints` below.
+    // Per design lock (project_slices_5_6_7_plan.md), the provider
+    // lazily compiles every installed-blueprint entry on the first
+    // `matchBlueprint` call per scope. Idempotent + best-effort per
+    // entry — a broken installed-blueprint never sinks the match flow.
+    let installedBlueprintsProvider;
+    if (opts.installedBlueprints && opts.installedBlueprints.entries.length > 0) {
+        const { projectRoot, entries } = opts.installedBlueprints;
+        const byId = new Map(entries.map((e) => [e.id, e]));
+        const providerOptions = {
+            installedBlueprints: () => entries.flatMap((entry) => {
+                if (entry.manifest.contract === undefined)
+                    return [];
+                const intent = entry.manifest.description ??
+                    entry.manifest.name ??
+                    entry.id;
+                return [
+                    {
+                        id: entry.id,
+                        manifestPath: entry.manifestPath,
+                        contract: entry.manifest.contract,
+                        intent,
+                    },
+                ];
+            }),
+            compile: async (entry) => {
+                const ui = byId.get(entry.id);
+                if (!ui) {
+                    return { kind: 'missing-entry', tried: [] };
+                }
+                const result = await compileUiOnDemand({
+                    projectRoot,
+                    manifestPath: ui.manifestPath,
+                    manifest: ui.manifest,
+                });
+                if (result.kind === 'ok') {
+                    return { kind: 'ok', code: result.code };
+                }
+                if (result.kind === 'missing-entry') {
+                    return { kind: 'missing-entry', tried: result.tried };
+                }
+                return {
+                    kind: 'failure',
+                    errors: result.errors.map((m) => m.text),
+                };
+            },
+            deps: { embedding, vectorStore },
+            onIssue: (issue) => {
+                process.stderr.write(`[ggui serve] installed-blueprint ${issue.id}: ${issue.kind}: ${issue.message}\n`);
+            },
+        };
+        installedBlueprintsProvider =
+            createInstalledBlueprintsProvider(providerOptions);
+    }
+    // Fold the bridge into the generation deps so the push handler +
+    // handshake negotiator both consume it via `MatchBlueprintDeps.
+    // installedBlueprints`. Two-step pattern keeps the createGguiServer
+    // call below unchanged when no provider is wired.
+    const generationWithInstalled = opts.generation
+        ? installedBlueprintsProvider
+            ? {
+                ...opts.generation,
+                installedBlueprints: installedBlueprintsProvider,
+            }
+            : opts.generation
+        : undefined;
+    const server = createGguiServer({
+        auth,
+        embedding,
+        providerKeys,
+        // Seeded per-app metadata store. Threaded so the in-process
+        // singleton is shared across `ggui_list_gadgets`,
+        // `ggui_list_themes`, `ggui_new_session` (theme default
+        // resolution), and the handshake (gadgets lookup).
+        appMetadataStore,
+        // Theme catalog resolver. Reads from `@ggui-ai/design`'s registry
+        // each call so runtime additions surface without a restart.
+        // Co-binding with `appMetadataStore` mounts `ggui_list_themes` on
+        // the agent route.
+        themes: () => listThemes(),
+        // Cross-restart HMAC secrets. Present iff the caller declared a
+        // persistent dir. Both threaded so the next restart can verify
+        // tokens minted by the previous run instead of regenerating per
+        // process. Render-signer.secret rides on the `renderSigning`
+        // discriminated union (the `false` shape disables the layer
+        // entirely; we always want it on here, so build the object form).
+        ...(persistedBootstrapSecret !== undefined
+            ? { bootstrapSecret: persistedBootstrapSecret }
+            : {}),
+        ...(persistedRenderSignerSecret !== undefined
+            ? { renderSigning: { secret: persistedRenderSignerSecret } }
+            : {}),
+        ...(resolvedMcpInstructions !== undefined
+            ? { mcpInstructions: resolvedMcpInstructions }
+            : {}),
+        // `--multi-tenant` flips the `/ggui/console/llm-keys` gate from
+        // admin-token to auth-adapter. Default scope derivation in the
+        // server picks up `userId` / `appId` from the resolved identity;
+        // operators with composite scopes pass their own `providerKeyScope`
+        // by composing `createGguiServer` directly.
+        ...(opts.multiTenant
+            ? { providerKeysGate: 'auth-adapter' }
+            : {}),
+        // Gate OAuth login routes on publicBaseUrl. Without it the
+        // redirect_uri can't be composed; the admin transport still mounts
+        // so operators can paste credentials in advance.
+        ...(opts.publicBaseUrl ? { publicBaseUrl: opts.publicBaseUrl } : {}),
+        ...(rateLimiter ? { rateLimiter } : {}),
+        ...(storage.sessionStore ? { sessionStore: storage.sessionStore } : {}),
+        // Always pass the materialized vectorStore so the install bridge
+        // and the matcher share state. Passing only `storage.vectors`
+        // (set when the manifest declares sqlite) would, on an absent
+        // declaration, leave the server to mint its own internal
+        // InMemoryVectorStore that the bridge couldn't see.
+        vectors: vectorStore,
+        // `threads:` is an opt-in on createGguiServer (no zero-config
+        // fallback — threads without an explicit store wouldn't mount
+        // routes at all). We only pass it when the manifest declares a
+        // store; absent declaration → no thread routes.
+        //
+        // Durability claim is whatever the resolver surfaced: `'durable'`
+        // for sqlite, `'ephemeral'` for memory. The server echoes this
+        // through `/ggui/health`, so Portal's caveat logic stays honest.
+        ...(storage.threadStore
+            ? {
+                threads: {
+                    store: storage.threadStore,
+                    ...(storage.threadDurability
+                        ? { durability: storage.threadDurability }
+                        : {}),
+                },
+            }
+            : {}),
+        sessionChannel: true,
+        pairing: opts.keysFile
+            ? { persistencePath: opts.keysFile }
+            : true,
+        // Email magic-link login. OSS first-run default mirrors
+        // `provisionalPreview` — wire a sender so magic links can be
+        // delivered. `selectEmailSenderFromEnv` reads
+        // `GGUI_EMAIL_SENDER` (default: `console`, terminal-only) and
+        // optionally `RESEND_API_KEY` / `SMTP_*` to construct a real
+        // sender. Misconfig is non-fatal: we log a warning + fall back
+        // to console so the boot path stays alive.
+        //
+        // Routes only mount when `publicBaseUrl` is set (the verify URL
+        // can't resolve otherwise) — the server logs
+        // `email_login_skipped` in that case and `/login` falls back to
+        // OAuth + pair-code. Hosted + programmatic embedders pass their
+        // own sender by composing `createGguiServer` directly.
+        emailLogin: {
+            sender: emailSender,
+            fromAddress: emailFromAddress,
+        },
+        // OAuth 2.1 + PKCE + DCR. Opt-in via `--oauth` because the routes
+        // add an HTML paste-key page + 4 well-known endpoints — not free
+        // attack surface for operators who only consume from pure-bearer
+        // clients (Claude Desktop, the console). Required for MCP custom-
+        // connector hosts (claude.ai, ChatGPT) whose form has no bearer
+        // field; flag flips on `oauth: true` defaults (in-memory storage,
+        // built-in paste-key consent page).
+        ...(opts.oauth ? { oauth: true } : {}),
+        console: {
+            sessionCookie: true,
+            ...(opts.adminToken !== undefined ? { adminToken: opts.adminToken } : {}),
+            // First-run onboarding redirect. When neither the credentials
+            // file (`~/.ggui/credentials.json`) nor any provider env var
+            // (ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY /
+            // OPENROUTER_API_KEY) is present, send `GET /` to the
+            // **admin** onboarding flow — the operator running `ggui serve`
+            // IS the admin on first-run, so they need the operator-key
+            // plane (`/admin/llm-keys`) and the assistant-connection card
+            // surfaced there. Cookie-gated end-user `/settings` is for a
+            // *separate* user paired with the server later, not the
+            // first-run operator. Once any key is configured, the next
+            // visit serves the SPA normally. Scoped to the root path;
+            // deep links bypass the redirect.
+            landingRedirect: () => {
+                try {
+                    const credsFileExists = existsSync(getCredentialsFile());
+                    const anyEnvKey = !!process.env.ANTHROPIC_API_KEY ||
+                        !!process.env.OPENAI_API_KEY ||
+                        !!process.env.GOOGLE_API_KEY ||
+                        !!process.env.OPENROUTER_API_KEY;
+                    if (!credsFileExists && !anyEnvKey) {
+                        return '/admin-login?next=%2Fadmin%2Fllm-keys';
+                    }
+                    return null;
+                }
+                catch {
+                    return null;
+                }
+            },
+        },
+        // Public welcome page at `/` — operator identification + public
+        // deep-link surfaces + operator-login affordance. Resolved from
+        // `ggui.json#operator` + `ggui.json#app.name` by serve-command.ts;
+        // absent = no welcome page (SPA index handler still owns `/`).
+        ...(opts.welcomePage ? { welcomePage: opts.welcomePage } : {}),
+        // Default to in-memory; caller substitutes a persistent impl
+        // (SqliteShortCodeIndex under `persistentDir`) so cached
+        // `/api/bootstrap/<code>` lookups survive a restart. Without
+        // that, /r/<code> 404s the moment the agent's host (claude.ai)
+        // replays its cached `_meta.ggui.bootstrap` envelope.
+        shortCodeIndex: opts.shortCodeIndex ?? new InMemoryShortCodeIndex(),
+        // Content-addressable componentCode delivery. The OSS dev default
+        // is filesystem-backed at `~/.ggui/code-cache/` (override via
+        // `GGUI_CODE_CACHE_DIR`). Survives `ggui serve` restart so
+        // claude.ai's iframe cache still resolves URLs minted before the
+        // restart. Operators can `rm -rf` the cache at any time —
+        // immutable URLs guarantee a fresh push repopulates as needed.
+        codeStore: new FileSystemCodeStore({ root: getCodeCacheDir() }),
+        // Manifest-declared blueprints. Only present when `ggui serve`
+        // found UIs in `blueprints.include`; absent = the server's
+        // `ggui_list_featured_blueprints` returns an empty catalog (the
+        // zero-config default).
+        ...(opts.blueprintProvider
+            ? { blueprintProvider: opts.blueprintProvider }
+            : {}),
+        // Manifest-backed UI registry — resolves blueprint ids to
+        // compiled bundles for `ggui_render_blueprint`. Paired with
+        // `blueprintProvider` above (metadata vs. bundle resolution on
+        // the same source). Absent = render tool not registered.
+        ...(opts.uiRegistry ? { uiRegistry: opts.uiRegistry } : {}),
+        // Manifest-declared primitive catalogs. Present when `ggui serve`
+        // resolved `primitives.{packages,local}`; absent = in-memory-only
+        // server with an empty `server.primitiveCatalogs`.
+        ...(opts.primitiveCatalogs
+            ? { primitiveCatalogs: opts.primitiveCatalogs }
+            : {}),
+        // Manifest-declared theme. Present when `ggui serve` resolved
+        // `ggui.json#theme`; absent = `createGguiServer` falls back to its
+        // `lightTheme`-backed default internally.
+        ...(opts.theme ? { theme: opts.theme } : {}),
+        // Console theme picker writer — paired with the admin-gated
+        // `/ggui/console/theme` POST. Absent = picker UI surfaces a
+        // read-only banner + POST returns 501. CLI sets this when
+        // `plan.projectRoot` resolved to a manifest path on disk.
+        ...(opts.themeWriter ? { themeWriter: opts.themeWriter } : {}),
+        // Live-theme wiring — `themeProvider` reads from a shared cell
+        // that `onThemeConfigChange` writes to on every console save,
+        // so the picker's "Save to ggui.json" reaches the next push's
+        // bootstrap envelope without a restart. Both threaded through
+        // when present; absent = boot-baked behaviour (legacy).
+        ...(opts.themeProvider ? { themeProvider: opts.themeProvider } : {}),
+        ...(opts.onThemeConfigChange
+            ? { onThemeConfigChange: opts.onThemeConfigChange }
+            : {}),
+        // Register `ggui_push` + serve `ui://ggui/session`. URLs point at
+        // this server's own console viewer + live channel — same-origin,
+        // same process. Without this, `ggui_push` is absent and the `/s/`
+        // viewer can never resolve (nothing mints shortCodes).
+        mcpApps: {
+            // The `/r/` route serves the public self-contained shell that
+            // any MCP Apps host (Claude Desktop, Claude Code, claude.ai)
+            // can render directly — `structuredContent.url` lands on it
+            // as a full HTML page. First-party hosts (Studio, Portal,
+            // console) consume `_meta.ui.resourceUri` and never hit the
+            // URL directly, so the same prefix works for everyone.
+            renderBaseUrl: `${baseUrl}/r/`,
+            wsUrl: `${wsBaseUrl}/ws`,
+        },
+        // Task #382 — `runtimeUrl` MUST be absolute. The thin-shell HTML
+        // served from `ui://ggui/session` is mounted via `srcdoc` in most
+        // consumers (`<McpAppIframe>` default path for inline text), which
+        // gives the iframe `about:srcdoc` as its URL — a relative path
+        // like `/_ggui/iframe-runtime.js` resolves against `about:` and the
+        // `<script src>` fetch silently fails. Publishing the absolute
+        // URL built from the CLI's own known `baseUrl` makes srcdoc mount
+        // work without operator action. The server still serves the bundle
+        // at `/_ggui/iframe-runtime.js` under `runtimePath`; this overrides
+        // only the URL published on `_meta.ggui.bootstrap.runtimeUrl`.
+        runtime: { url: `${baseUrl}${RUNTIME_BUNDLE_URL_PATH}` },
+        // OSS first-run default: provisional A2UI preview is on. The
+        // deterministic emitter from `@ggui-ai/preview-a2ui/emitters`
+        // adapts each push's `story.intent` into a small A2UI surface
+        // (heading → shell → teardown) and streams it on
+        // `_ggui:preview`. Embedded-ui's `/s/<shortCode>` viewer mounts
+        // `<ProvisionalRenderer>` to paint the frames as they arrive,
+        // so operators see a live UI build-up the first time they
+        // invoke `ggui_push` — before any LLM generation lands on OSS.
+        //
+        // Hosted + programmatic hosts opt-in by composing
+        // `createGguiServer()` directly and supplying their own
+        // emitter (e.g. Haiku-backed); the CLI keeps the OSS story
+        // honest with a zero-config default that fires.
+        provisionalPreview: {
+            enabled: true,
+            emitter: createDeterministicPreviewEmitter(),
+        },
+        // Generation wiring. Threaded through to
+        // `defaultHandlers.push.generation` → `createGguiPushHandler`.
+        // Absent = placeholder mode: push creates sessions + shortCodes
+        // + preview but does NOT produce componentCode. The CLI's
+        // `runServeCommand` probes BYOK (env → credentials file) at
+        // boot and only supplies this opt on a hit. See
+        // `./generation-probe.ts`.
+        ...(generationWithInstalled ? { generation: generationWithInstalled } : {}),
+        // Mount aggregation. External SharedHandler bundles appended onto
+        // `/mcp` alongside ggui-native tools. No CLI config loader yet —
+        // programmatic hosts + integration tests compose mounts through
+        // this opt directly.
+        ...(opts.mcpMounts && opts.mcpMounts.length > 0
+            ? { mcpMounts: opts.mcpMounts }
+            : {}),
+        // wiredActionRouter composed from the same mount handlers. With
+        // mounts present, every mounted tool becomes wire-dispatchable
+        // from a generated UI's `actionSpec[name].dispatch.tool` (when
+        // `dispatch.kind === 'tool'`) — the "zero agent code" path.
+        // Without mounts, no router is wired and inbound actions stay on
+        // the agent-routed path.
+        ...(wiredActionRouter ? { wiredActionRouter } : {}),
+        // Schema-compat mode. Defaults to `'reject'` inside
+        // `createGguiServer`; the env override is the operator's escape
+        // hatch for scenarios that intentionally ship a blueprint with a
+        // schema mismatch (e.g. contract-probe fixtures that test runtime
+        // TOOL_THREW / SCHEMA_VIOLATION error paths — `'reject'` would
+        // otherwise block the stack item at push/try-live time before
+        // runtime gets to emit the envelope under test).
+        //
+        // Accepted values match `SchemaCompatMode`: `'reject' | 'warn' |
+        // 'off'`. Unrecognized values fall through to the server's
+        // default. Keeping the parse narrow so a typo yields default
+        // behavior (reject) rather than silent relaxation.
+        ...(process.env['GGUI_SCHEMA_COMPAT_MODE'] === 'warn' ||
+            process.env['GGUI_SCHEMA_COMPAT_MODE'] === 'off' ||
+            process.env['GGUI_SCHEMA_COMPAT_MODE'] === 'reject'
+            ? {
+                schemaCompatCheck: process.env['GGUI_SCHEMA_COMPAT_MODE'],
+            }
+            : {}),
+        // Wired-tool per-call timeout override (default 30 s in
+        // `session-channel.ts::DEFAULT_WIRED_TOOL_TIMEOUT_MS`). Mirrors the
+        // `GGUI_SCHEMA_COMPAT_MODE` escape-hatch shape: env-only; absent or
+        // unparseable falls through to the server's default. Test harnesses
+        // exercising TOOL_TIMEOUT envelopes lower this to keep per-test
+        // budgets small (the conformance fixture
+        // `wired-action-tool-timeout.json` deliberately wires a hanging
+        // tool; the default 30 s wait would dominate a Lane-1 spec budget).
+        //
+        // Parse uses `Number()` + finite + positive-integer checks; a typo
+        // (`"abc"`, `"-100"`, `"NaN"`) falls through silently to default.
+        // Operators that need a different production timeout SHOULD compose
+        // `createGguiServer` directly rather than rely on env coupling.
+        ...(() => {
+            const raw = process.env['GGUI_WIRED_TIMEOUT_MS'];
+            if (raw === undefined || raw === '')
+                return {};
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed) || parsed <= 0)
+                return {};
+            return { wiredActionTimeoutMs: Math.floor(parsed) };
+        })(),
+    });
+    return {
+        listen: async (port, host) => {
+            const httpServer = await server.listen(port, host);
+            const addr = httpServer.address();
+            if (!addr || typeof addr === 'string') {
+                throw new Error('server.address() returned an unexpected shape');
+            }
+            return addr.port;
+        },
+        close: () => server.close(),
+        toolCount: server.toolCount,
+        serverName: 'ggui-mcp-server',
+        serverVersion: opts.cliVersion,
+        primitiveCatalogCount: server.primitiveCatalogs.length,
+        themeSource: server.theme.source,
+        // Always non-null in the CLI bundle because `pairing: true` is
+        // wired above. Exposed through the narrow `ServeBackend` contract
+        // so `runServe` can pre-mint an initial pair code after bind
+        // without reaching into `GguiServer`.
+        pairingService: server.pairingService,
+        // Always non-null in the CLI bundle because `console` is wired
+        // above (sessionCookie: true). Surfaced so the CLI banner can
+        // print the operator-facing value alongside PAIR_CODE.
+        adminToken: server.adminToken,
+        // Surface the embedding model id so `describeServeBanner` can
+        // print a `rag` line. Read off the provider's `id` field — local
+        // provider returns the model id (e.g. `Xenova/bge-small-en-v1.5`);
+        // MockEmbeddingProvider returns `'mock-sine'`. The banner only
+        // shows the line for real models (this CLI bundle always wires
+        // the local provider, so the line always appears in `ggui serve`).
+        embeddingModel: embedding.id,
+    };
+}