@ggui-ai/mcp-server 0.2.0-alpha.4 → 0.3.0-rc.0

package/dist/console-session-routes.js

@@ -0,0 +1,385 @@
+/**
+ * Console render-viewer session routes (cookie mint + resource +
+ * meta + observation).
+ *
+ *   POST /ggui/console/session-cookie
+ *     — resolve shortCode → render and mint the same-origin HTTP-only
+ *       cookie the viewer authenticates to the live channel with.
+ *
+ *   GET /ggui/console/session-resource?session=<sessionId>
+ *     — production thin-shell HTML, wrapped as a ResourceContents
+ *       blob (`text` IS `GGUI_RENDER_SHELL_HTML`, byte-identical to
+ *       what Claude Desktop fetches via MCP `resources/read
+ *       ui://ggui/render`). NO inlined bootstrap — console fetches
+ *       the bootstrap separately (meta route below) and replies to
+ *       the iframe's `ui/initialize` postMessage with it.
+ *
+ *   GET /ggui/console/sessions/:sessionId/meta
+ *     — slice-envelope JSON (`{ "ai.ggui/render": {...} }`, the same
+ *       shape as the wire `_meta`). The console forwards this to the
+ *       iframe as the `_meta` slice of a spec-canonical
+ *       `ui/notifications/tool-result` notification (per
+ *       `docs/protocol/extensions/ai.ggui-meta.md`). Requires
+ *       `mcpApps: true` (mintBootstrap presence) — 503 otherwise.
+ *
+ *   GET /ggui/console/session?session=<sessionId>
+ *     — `{render, eventSequence}` JSON. Console-only observation
+ *       surface for `<GguiSessionViewer>` to mount `<RenderInspector>`.
+ *
+ * Named parties (all routes):
+ *   - console (SPA caller) — holds the same-origin cookie.
+ *   - mcp-server (these handlers) — gates auth + scope; mints the
+ *     bootstrap on the meta route.
+ *   - host wrapper (bootstrap forwarder; `<AppRenderer>` on web,
+ *     `<McpAppIframe>` on RN) — receives the bootstrap JSON and
+ *     forwards it as a `ui/notifications/tool-result` `_meta` slice.
+ *   - renderer bundle (inside the iframe) — runs the same boot
+ *     code path as production; reads the single `ai.ggui/render`
+ *     slice meta.
+ *
+ * Auth + scope obligations (uniform):
+ *   - Cookie-auth via `readDevtoolCookieFromHeaders` +
+ *     `verifyDevtoolCookie`. Invalid / missing → 401.
+ *   - Scope: `cookie.sessionId` MUST equal the requested session.
+ *     Cross-render access with a valid cookie → 403.
+ *   - GguiSession existence + appId match: 404 / 403 respectively.
+ *
+ * The mount RETURNS the `GguiSessionChannelCookieAuth` binding the
+ * composer threads into `createGguiSessionChannelServer`, so the
+ * cookie minted here authenticates the live-channel WS upgrade.
+ */
+import { deriveContractBundle } from "@ggui-ai/mcp-server-handlers/renders";
+import { GGUI_RENDER_RESOURCE_MIME, GGUI_RENDER_RESOURCE_URI, MCP_APP_AI_GGUI_RENDER_META_KEY, } from "@ggui-ai/protocol/integrations/mcp-apps";
+import { CONSOLE_COOKIE_NAME, mintDevtoolCookie, readDevtoolCookieFromHeaders, verifyDevtoolCookie, } from "./console-auth.js";
+import { applyDevtoolSecurityHeaders } from "./console-headers.js";
+import { GGUI_RENDER_SHELL_HTML } from "./mcp-apps-outbound.js";
+import { singleParam } from "./route-param.js";
+/**
+ * Mount the console session routes onto the express app and return
+ * the cookie-auth binding for the live channel.
+ */
+export function mountConsoleSessionRoutes(opts) {
+    const { app, secret, shortCodeIndex, cookieTtlSec, cookieSecure, renderStore, mintBootstrap, runtimeBootstrapUrl, codeStore, publicBaseUrl, logger, } = opts;
+    const cookieLogger = logger.child({
+        component: "console-cookie",
+    });
+    app.post("/ggui/console/session-cookie", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const body = (req.body ?? {});
+        if (typeof body.shortCode !== "string" || body.shortCode.length === 0) {
+            res.status(400).json({
+                error: "invalid_request",
+                message: "`shortCode` (string) is required",
+            });
+            return;
+        }
+        let binding;
+        try {
+            binding = await shortCodeIndex.lookup(body.shortCode);
+        }
+        catch (err) {
+            cookieLogger.error("short_code_lookup_failed", {
+                error: String(err),
+            });
+            res.status(500).json({ error: "internal_error" });
+            return;
+        }
+        if (!binding) {
+            res.status(404).json({
+                error: "unknown_short_code",
+                message: "Short-code does not resolve to any render on this server",
+            });
+            return;
+        }
+        const mint = mintDevtoolCookie({
+            sessionId: binding.sessionId,
+            appId: binding.appId,
+            secret,
+            ...(cookieTtlSec !== undefined ? { ttlSec: cookieTtlSec } : {}),
+            secure: cookieSecure,
+        });
+        res.setHeader("Set-Cookie", mint.setCookieHeader);
+        res.json({
+            sessionId: mint.sessionId,
+            appId: mint.appId,
+            expiresAt: mint.expiresAt,
+        });
+    });
+    /**
+     * Shared auth + scope gate for the console render routes.
+     * Returns the verified `(sessionId, appId)` pair on success or
+     * `null` after writing an HTTP error response on failure.
+     *
+     * Internal — closure-scoped to the route block; not exported.
+     */
+    const gateDevtoolRenderRequest = async (req, res, explicitSessionId) => {
+        const sessionIdRaw = explicitSessionId !== undefined ? explicitSessionId : req.query["session"];
+        if (typeof sessionIdRaw !== "string" || sessionIdRaw.length === 0) {
+            res.status(400).json({
+                error: "invalid_request",
+                message: "`render` query parameter (or :sessionId path parameter on the meta route) is required",
+            });
+            return null;
+        }
+        const rawCookie = readDevtoolCookieFromHeaders(req.headers);
+        if (!rawCookie) {
+            res.status(401).json({
+                error: "missing_cookie",
+                message: `${CONSOLE_COOKIE_NAME} cookie required (mint via POST /ggui/console/session-cookie first)`,
+            });
+            return null;
+        }
+        const claims = verifyDevtoolCookie(rawCookie, secret);
+        if (!claims) {
+            res.status(401).json({
+                error: "invalid_cookie",
+                message: "Console cookie is invalid, expired, or for another server",
+            });
+            return null;
+        }
+        if (claims.sessionId !== sessionIdRaw) {
+            res.status(403).json({
+                error: "cookie_session_mismatch",
+                message: `Console cookie is bound to render '${claims.sessionId}' but request targets '${sessionIdRaw}'`,
+            });
+            return null;
+        }
+        // GguiSession existence + appId match — even on the static-shell
+        // route we honestly answer 404 instead of leaking an HTML blob
+        // for a render the server doesn't know about.
+        let render = null;
+        if (renderStore) {
+            try {
+                render = await renderStore.get(claims.sessionId);
+            }
+            catch (err) {
+                cookieLogger.error("render_resource_store_failed", {
+                    error: String(err),
+                    sessionId: claims.sessionId,
+                });
+                res.status(500).json({ error: "internal_error" });
+                return null;
+            }
+        }
+        if (!render) {
+            res.status(404).json({
+                error: "session_not_found",
+                message: `GguiSession '${claims.sessionId}' is not on this server`,
+            });
+            return null;
+        }
+        if (render.appId !== claims.appId) {
+            res.status(403).json({
+                error: "app_mismatch",
+                message: `Cookie bound to app '${claims.appId}' but render is on app '${render.appId}'`,
+            });
+            return null;
+        }
+        return { sessionId: claims.sessionId, appId: claims.appId };
+    };
+    // GET /ggui/console/session-resource?session=<sessionId>
+    // → production thin-shell HTML, wrapped as a ResourceContents
+    //   blob. NO inlined bootstrap — console fetches the bootstrap
+    //   separately (route below) and replies to the iframe's
+    //   `ui/initialize` postMessage with it.
+    app.get("/ggui/console/session-resource", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        res.setHeader("Content-Type", "application/json; charset=utf-8");
+        const verified = await gateDevtoolRenderRequest(req, res);
+        if (!verified)
+            return;
+        res.status(200).json({
+            contents: [
+                {
+                    uri: GGUI_RENDER_RESOURCE_URI,
+                    mimeType: GGUI_RENDER_RESOURCE_MIME,
+                    text: GGUI_RENDER_SHELL_HTML,
+                },
+            ],
+        });
+    });
+    // GET /ggui/console/sessions/:sessionId/meta
+    // → slice-envelope JSON (`{ "ai.ggui/render": {...} }`, the same
+    //   shape as the wire `_meta`). Required when the console is
+    //   hosting the renderer in a srcdoc iframe and needs to feed
+    //   the iframe a meta payload via `ui/initialize`. `mcpApps:
+    //   true` is required (mintWsToken/mintBootstrap presence) —
+    //   503 otherwise.
+    app.get("/ggui/console/sessions/:sessionId/meta", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        res.setHeader("Content-Type", "application/json; charset=utf-8");
+        const sessionIdFromPath = singleParam(req.params["sessionId"]);
+        const verified = await gateDevtoolRenderRequest(req, res, sessionIdFromPath);
+        if (!verified)
+            return;
+        if (!mintBootstrap) {
+            res.status(503).json({
+                error: "mcp_apps_disabled",
+                message: "renders/:sessionId/meta requires mcpApps: true on the server so the renderer can receive a valid WS auth token. Enable `mcpApps` on createGguiServer() and retry.",
+            });
+            return;
+        }
+        const minted = mintBootstrap(verified.sessionId, verified.appId);
+        // Console/srcdoc absolute-URL fix: `<McpAppIframe>`
+        // mounts the resource via `srcdoc`, so the iframe's URL
+        // is `about:srcdoc` and any relative URL would resolve
+        // against that, not the dev server. Rewrite the
+        // same-origin `runtimeUrl` to absolute based on the
+        // request host. The `wsUrl` minted at server-boot
+        // defaults to `ws://localhost/ws` — also rewrite that
+        // to the request-host's actual host:port when its
+        // hostname is `localhost`, so the iframe's WebSocket
+        // open lands on the same listener. Operators who
+        // configured a CDN / external `wsUrl` / `runtime.url`
+        // are passed through unchanged.
+        const requestHost = req.get("host") ?? "";
+        const absoluteRendererUrl = /^https?:\/\//i.test(runtimeBootstrapUrl)
+            ? runtimeBootstrapUrl
+            : `${req.protocol}://${requestHost}${runtimeBootstrapUrl}`;
+        let resolvedWsUrl = minted.wsUrl;
+        try {
+            const wsParsed = new URL(minted.wsUrl);
+            if ((wsParsed.hostname === "localhost" || wsParsed.hostname === "127.0.0.1") &&
+                requestHost.length > 0) {
+                const wsScheme = req.protocol === "https" ? "wss" : "ws";
+                resolvedWsUrl = `${wsScheme}://${requestHost}${wsParsed.pathname}${wsParsed.search}`;
+            }
+        }
+        catch {
+            // Malformed `wsUrl` — leave it as-is so the renderer
+            // surfaces the failure through its own bootstrap-failed
+            // envelope rather than us silently rewriting a string
+            // we don't understand.
+        }
+        // Content-addressable contract-validator bundle (#109) for
+        // the active render. The renderer iframe's strict CSP
+        // forbids the `new Function` codegen `ajv.compile()` needs,
+        // so the server compiles + writes the bundle to its
+        // CodeStore at render time and threads the URL here. The
+        // iframe fetches the URL + dynamic-imports to resolve
+        // validators. Best-effort: a missing bundle degrades to no
+        // client-side validation; server-side `assertActionContract`
+        // remains authoritative.
+        let renderContractHash;
+        let renderValidatorsUrl;
+        if (renderStore && codeStore) {
+            try {
+                const stored = await renderStore.get(verified.sessionId);
+                if (stored !== null &&
+                    stored.render.type !== "mcpApps" &&
+                    stored.render.type !== "system" &&
+                    typeof stored.render.componentCode === "string" &&
+                    stored.render.componentCode.length > 0) {
+                    const bundle = await deriveContractBundle(stored.render);
+                    if (bundle) {
+                        await codeStore.put(bundle.contractHash, bundle.bundleSource);
+                        renderContractHash = bundle.contractHash;
+                        const baseForValidators = publicBaseUrl
+                            ? publicBaseUrl.replace(/\/$/, "")
+                            : `${req.protocol}://${requestHost}`;
+                        renderValidatorsUrl = `${baseForValidators}/contract/${bundle.contractHash}.js`;
+                    }
+                }
+            }
+            catch (err) {
+                cookieLogger.warn("render_meta_validators_failed", {
+                    error: String(err),
+                    sessionId: verified.sessionId,
+                });
+            }
+        }
+        // Slice-envelope response (Phase B: single ai.ggui/render
+        // slice) — same shape as the wire `_meta` and the inline
+        // `__GGUI_META__` global the `/r/<shortCode>` shell carries.
+        // GguiSessionViewer parses with `parseMcpAppAiGguiRenderMeta`.
+        const renderMeta = {
+            sessionId: verified.sessionId,
+            appId: verified.appId,
+            runtimeUrl: absoluteRendererUrl,
+            wsUrl: resolvedWsUrl,
+            wsToken: minted.token,
+            expiresAt: minted.expiresAt,
+            ...(renderContractHash !== undefined && renderValidatorsUrl !== undefined
+                ? {
+                    contractHash: renderContractHash,
+                    validatorsUrl: renderValidatorsUrl,
+                }
+                : {}),
+        };
+        res.status(200).json({
+            [MCP_APP_AI_GGUI_RENDER_META_KEY]: renderMeta,
+        });
+    });
+    // GET /ggui/console/session?session=<sessionId>
+    // → `{render, eventSequence}` JSON.
+    //
+    // Console-only observation surface for `<GguiSessionViewer>` to mount
+    // `<RenderInspector>`. The iframe owns the live WS subscription
+    // + the bootstrap token (single-use), so the OUTER console DOM
+    // has no live source for render data — without this endpoint
+    // the inspector can't render contract / test-action panels.
+    //
+    // Failure modes:
+    //   - 401 missing/invalid cookie · 403 cross-render/app · 404
+    //     unknown render · 500 store failure (all delegated to
+    //     `gateDevtoolRenderRequest`).
+    //   - 503 if `renderStore` is not wired (zero-config server).
+    //
+    // Shape note: Phase B collapsed the prior session-stack array to
+    // a single `GguiSession` row. The response now returns the resolved
+    // `GguiSession` directly; console narrows on `render.type` before
+    // passing into `<RenderInspector>` (which only accepts the
+    // ComponentGguiSession variant since the inspector reads actionSpec /
+    // streamSpec / propsSpec — fields McpAppsGguiSession doesn't carry).
+    app.get("/ggui/console/session", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        res.setHeader("Content-Type", "application/json; charset=utf-8");
+        const verified = await gateDevtoolRenderRequest(req, res);
+        if (!verified)
+            return;
+        if (!renderStore) {
+            res.status(503).json({
+                error: "session_store_unavailable",
+                message: "GguiSession observation requires renderChannel: true on the server so the render store is wired. Enable `renderChannel` on createGguiServer() and retry.",
+            });
+            return;
+        }
+        let stored = null;
+        try {
+            stored = await renderStore.get(verified.sessionId);
+        }
+        catch (err) {
+            cookieLogger.error("render_store_failed", {
+                error: String(err),
+                sessionId: verified.sessionId,
+            });
+            res.status(500).json({ error: "internal_error" });
+            return;
+        }
+        if (!stored) {
+            // Race: gate verified existence above but the render
+            // could expire between calls. Honest 404.
+            res.status(404).json({
+                error: "session_not_found",
+                message: `GguiSession '${verified.sessionId}' is not on this server`,
+            });
+            return;
+        }
+        res.status(200).json({
+            render: stored.render,
+            eventSequence: stored.eventSequence,
+        });
+    });
+    // Reference the cookie name to keep the export alive for
+    // downstream consumers + lint. The name is the single source
+    // of truth; avoid duplicating the string anywhere.
+    cookieLogger.debug?.("console_cookie_ready", {
+        cookieName: CONSOLE_COOKIE_NAME,
+    });
+    // Cookie-auth binding for the render channel — the composer
+    // threads this into `createGguiSessionChannelServer`.
+    return {
+        readCookie: readDevtoolCookieFromHeaders,
+        verify: (cookieValue) => verifyDevtoolCookie(cookieValue, secret),
+    };
+}

package/dist/console-sessions-routes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Console active-render list route.
+ *
+ *   GET /ggui/console/sessions?limit=<n> — active-render list for
+ *   the console SPA's `/admin/sessions` page. Operator-facing "what's
+ *   live right now?" surface, enriched with each render's current
+ *   shortCode so rows can link through to `/s/<shortCode>` (the
+ *   existing render viewer).
+ *
+ * Scope: active renders only. The `GguiSessionFilter.status`
+ * taxonomy ('active' | 'completed' | 'expired') requires the
+ * store's private `closed` bucket flag to disambiguate completed
+ * from expired — that flag isn't on the `GguiSession` protocol type,
+ * so exposing mixed-status listings honestly requires a seam
+ * extension we don't need for the "live right now" use case.
+ * Future slices (historical renders, closed-renders triage)
+ * can opt in via query-param.
+ *
+ * Sources:
+ *   - `renderStore.list({ status: 'active', limit })` — single
+ *     page, limit default 25, clamped to [1, 100].
+ *   - `shortCodeIndex.findBySessionId(render.id)` — best-effort
+ *     enrichment; absent shortCode is a valid row (displays
+ *     without a click-through link).
+ *
+ * Sort: most-recent `lastActivityAt` first — matches operator
+ * intent "show me what I was just looking at."
+ *
+ * Zero-config shape: `{ sessions: [], total: 0 }` when no
+ * renderStore is wired (e.g. pure-MCP dev boot with neither
+ * renderChannel nor mcpApps enabled).
+ */
+import type { GguiSessionStore, ShortCodeIndex } from "@ggui-ai/mcp-server-core";
+import type { Express } from "express";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** GguiSession store the list reads (absent = honest empty list). */
+    readonly renderStore?: GguiSessionStore;
+    /** shortCode index for best-effort row enrichment. */
+    readonly shortCodeIndex?: ShortCodeIndex;
+    /** Structured logger. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `GET /ggui/console/sessions` onto the express app. Returns
+ * nothing — the route self-registers.
+ */
+export declare function mountConsoleSessionsRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=console-sessions-routes.d.ts.map

package/dist/console-sessions-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-sessions-routes.d.ts","sourceRoot":"","sources":["../src/console-sessions-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA8EnE"}

package/dist/console-sessions-routes.js

@@ -0,0 +1,106 @@
+/**
+ * Console active-render list route.
+ *
+ *   GET /ggui/console/sessions?limit=<n> — active-render list for
+ *   the console SPA's `/admin/sessions` page. Operator-facing "what's
+ *   live right now?" surface, enriched with each render's current
+ *   shortCode so rows can link through to `/s/<shortCode>` (the
+ *   existing render viewer).
+ *
+ * Scope: active renders only. The `GguiSessionFilter.status`
+ * taxonomy ('active' | 'completed' | 'expired') requires the
+ * store's private `closed` bucket flag to disambiguate completed
+ * from expired — that flag isn't on the `GguiSession` protocol type,
+ * so exposing mixed-status listings honestly requires a seam
+ * extension we don't need for the "live right now" use case.
+ * Future slices (historical renders, closed-renders triage)
+ * can opt in via query-param.
+ *
+ * Sources:
+ *   - `renderStore.list({ status: 'active', limit })` — single
+ *     page, limit default 25, clamped to [1, 100].
+ *   - `shortCodeIndex.findBySessionId(render.id)` — best-effort
+ *     enrichment; absent shortCode is a valid row (displays
+ *     without a click-through link).
+ *
+ * Sort: most-recent `lastActivityAt` first — matches operator
+ * intent "show me what I was just looking at."
+ *
+ * Zero-config shape: `{ sessions: [], total: 0 }` when no
+ * renderStore is wired (e.g. pure-MCP dev boot with neither
+ * renderChannel nor mcpApps enabled).
+ */
+import { applyDevtoolSecurityHeaders } from "./console-headers.js";
+/**
+ * Mount `GET /ggui/console/sessions` onto the express app. Returns
+ * nothing — the route self-registers.
+ */
+export function mountConsoleSessionsRoutes(opts) {
+    const { app, renderStore, shortCodeIndex, logger } = opts;
+    app.get("/ggui/console/sessions", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const limitRaw = req.query["limit"];
+        let limit = 25;
+        if (typeof limitRaw === "string") {
+            const parsed = Number.parseInt(limitRaw, 10);
+            if (Number.isFinite(parsed) && parsed > 0) {
+                limit = Math.min(100, parsed);
+            }
+        }
+        if (!renderStore) {
+            res.json({ sessions: [], total: 0 });
+            return;
+        }
+        try {
+            const renders = await renderStore.list({
+                status: "active",
+                limit,
+            });
+            const summaries = [];
+            for (const render of renders) {
+                let shortCode = null;
+                if (shortCodeIndex) {
+                    try {
+                        shortCode = await shortCodeIndex.findBySessionId(render.id);
+                    }
+                    catch (err) {
+                        // Best-effort — the render row is still honest
+                        // without a shortCode.
+                        logger.warn("console_renders_shortcode_lookup_failed", {
+                            sessionId: render.id,
+                            error: String(err),
+                        });
+                    }
+                }
+                summaries.push({
+                    sessionId: render.id,
+                    ...(shortCode ? { shortCode } : {}),
+                    appId: render.appId,
+                    lastActivityAt: render.lastActivityAt,
+                    createdAt: render.createdAt,
+                    status: "active",
+                });
+            }
+            // Most-recent activity first. Tiebreak on sessionId for
+            // stability when multiple rows share the same ms timestamp.
+            summaries.sort((a, b) => {
+                const byRecency = b.lastActivityAt - a.lastActivityAt;
+                if (byRecency !== 0)
+                    return byRecency;
+                return a.sessionId.localeCompare(b.sessionId);
+            });
+            res.json({ sessions: summaries, total: summaries.length });
+        }
+        catch (err) {
+            logger.warn("console_renders_list_failed", {
+                error: String(err),
+            });
+            res.status(500).json({
+                error: "renders_unavailable",
+                message: err instanceof Error
+                    ? `GguiSession store failed to list — ${err.message}`
+                    : `GguiSession store failed to list — ${String(err)}`,
+            });
+        }
+    });
+}

package/dist/console-static-routes.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Console static-bundle + SPA serving routes.
+ *
+ *   GET <consolePath>            — mode-meta-injected `index.html`,
+ *                                  welcome page, or onboarding redirect.
+ *   <consolePath>/* (static)     — `express.static` over the package's
+ *                                  built `dist/` (HTML + JS + CSS).
+ *   GET /admin/* + /devtools/*   — admin-HTML gate (302 to
+ *                                  `/admin-login?next=…` on miss).
+ *   GET <consolePath>/* (SPA)    — fallback to the rewritten
+ *                                  `index.html` so the React router
+ *                                  takes over for client-side routes.
+ *
+ * When the `distDir` doesn't exist on disk (e.g. operator forgot
+ * to run `pnpm --filter @ggui-ai/console build`), the static
+ * route is replaced with a 503 that points at the missing build —
+ * silent 404 would be mistaken for "console is broken" rather
+ * than "console wasn't built yet," which is a real debugging
+ * trap for self-hosted operators.
+ */
+import type { Express } from "express";
+import express from "express";
+import { type WelcomePageInputs } from "./console-welcome.js";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** Mount path for the console (default `/`). */
+    readonly consolePath: string;
+    /** Built console bundle directory on disk. */
+    readonly consoleDistDir: string;
+    /** Operator mode stamped into `<meta name="ggui-mode">`. */
+    readonly mode: "dev" | "prod";
+    /** Server identity name (welcome-page fallback title). */
+    readonly serverName: string;
+    /** Welcome-page inputs — enables the server-rendered landing. */
+    readonly welcomePage?: WelcomePageInputs;
+    /** Onboarding redirect resolver (runs before welcome/SPA index). */
+    readonly landingRedirect?: () => string | null;
+    /**
+     * Admin gate for the SPA's `/admin/*` + `/devtools/*` zones. `null`
+     * = console disabled / no admin token resolved → gate unmounted.
+     */
+    readonly requestHasAdminAuth: ((req: express.Request) => boolean) | null;
+    /** Structured logger for the missing-dist boot warning. */
+    readonly logger: Logger;
+}
+/**
+ * Mount the console static + SPA routes onto the express app.
+ * Returns nothing — the routes self-register.
+ */
+export declare function mountConsoleStaticRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=console-static-routes.d.ts.map

package/dist/console-static-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-static-routes.d.ts","sourceRoot":"","sources":["../src/console-static-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,SAAS,CAAC;AACjD,OAAO,OAAO,MAAM,SAAS,CAAC;AAI9B,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;IACzC,oEAAoE;IACpE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IACzE,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA8KjE"}