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

package/dist/console-registry-routes.js

@@ -0,0 +1,276 @@
+/**
+ * Console blueprint-catalog read/maintenance routes.
+ *
+ *   GET    /ggui/console/registry                  — declared-blueprint +
+ *          primitive catalog (boot-time content).
+ *   GET    /ggui/console/blueprints/cached         — intent-keyed
+ *          generation-cache listing (legacy surface).
+ *   DELETE /ggui/console/blueprints/cached/:id     — invalidate one entry.
+ *   POST   /ggui/console/blueprints/cached/clear   — bulk-clear the scope.
+ *   GET    /ggui/console/blueprints/registry       — contract-keyed runtime
+ *          registry the matcher actually consults (per-row tier
+ *          diagnostics: kind, contractKey, hitCount, lastHitAt,
+ *          provenance).
+ *
+ * `/registry` sources:
+ *   - `blueprints[]`  ← `uiRegistry?.list()` (full manifest entries;
+ *     surfaces `name` + `description?` + `category?`). Same registry
+ *     the `/ggui/console/blueprint/:id` endpoint resolves against, so
+ *     the /registry click-through to /preview/<id> is guaranteed to
+ *     hit the same dataset.
+ *   - `primitives[]` ← `primitiveCatalogs` (`DiscoveredPrimitiveCatalog`
+ *     shape from `@ggui-ai/project-config`). Each entry flattens
+ *     one primitive per row, tagging it with its catalog's
+ *     `source` ('package' | 'local') + `import` specifier.
+ *
+ * Scope: read-only on `/registry` (authoring happens on disk and the
+ * server re-reads on boot; zero-config is an honest empty shape).
+ * The cache/registry surfaces are scoped to `DEFAULT_BUILDER_APP_ID`
+ * because the OSS server is single-tenant by construction — same
+ * scope the render handler writes to, so list/invalidate/clear see
+ * what the real cache writes.
+ *
+ * Enumeration gate: `listGenerationCache` + `clearGenerationCache` +
+ * `listBlueprints` require an EnumerableVectorStore. Every OSS
+ * default satisfies it (`InMemoryVectorStore`, `SqliteVectorStore`);
+ * deployments that wire a non-enumerable backend get an honest `501`
+ * with a reason code rather than a silent empty list or a runtime
+ * throw.
+ *
+ * No bearer auth (same rule as the other console endpoints —
+ * same-origin operator-facing).
+ */
+import { isEnumerableVectorStore } from "@ggui-ai/mcp-server-core";
+import { clearGenerationCache, invalidateGenerationCache, listBlueprints, listGenerationCache, } from "@ggui-ai/mcp-server-handlers/renders";
+import { DEFAULT_BUILDER_APP_ID } from "./auth.js";
+import { applyDevtoolSecurityHeaders } from "./console-headers.js";
+/**
+ * Mount the console catalog routes onto the express app. Returns
+ * nothing — the routes self-register.
+ */
+export function mountConsoleRegistryRoutes(opts) {
+    const { app, uiRegistry, primitiveCatalogs, vectors, logger } = opts;
+    // GET /ggui/console/registry — declared catalog. Output is
+    // stable-sorted by id / name so the SPA's filter-as-you-type UI
+    // doesn't need a second sort pass.
+    app.get("/ggui/console/registry", async (_req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const blueprints = [];
+        if (uiRegistry) {
+            try {
+                const entries = await uiRegistry.list();
+                for (const entry of entries) {
+                    const summary = {
+                        id: entry.id,
+                        name: entry.manifest.name,
+                        ...(entry.manifest.description !== undefined
+                            ? { description: entry.manifest.description }
+                            : {}),
+                        ...(entry.manifest.category !== undefined ? { category: entry.manifest.category } : {}),
+                    };
+                    blueprints.push(summary);
+                }
+                blueprints.sort((a, b) => a.id.localeCompare(b.id));
+            }
+            catch (err) {
+                logger.warn("console_registry_blueprint_list_failed", {
+                    error: String(err),
+                });
+                res.status(500).json({
+                    error: "registry_unavailable",
+                    message: err instanceof Error
+                        ? `Blueprint registry failed to list — ${err.message}`
+                        : `Blueprint registry failed to list — ${String(err)}`,
+                });
+                return;
+            }
+        }
+        const primitives = [];
+        for (const catalog of primitiveCatalogs ?? []) {
+            for (const primitive of catalog.manifest.primitives) {
+                primitives.push({
+                    name: primitive.name,
+                    source: catalog.source,
+                    catalog: catalog.import,
+                });
+            }
+        }
+        // Stable sort: primary by catalog import (packages first, then
+        // locals under their own groups), secondary by primitive name.
+        // Operator reads "everything from @ggui-ai/design" as one block
+        // rather than having @ggui-ai/design's Button interleaved with
+        // a local-catalog Button at the letter-b slot.
+        primitives.sort((a, b) => {
+            const byCatalog = a.catalog.localeCompare(b.catalog);
+            if (byCatalog !== 0)
+                return byCatalog;
+            return a.name.localeCompare(b.name);
+        });
+        res.json({ blueprints, primitives });
+    });
+    // GET /ggui/console/blueprints/cached — list cached generation
+    // entries. Rejects with 501 when the vector store doesn't
+    // support enumeration. Empty scope returns
+    // `{entries: [], total: 0}` — not an error.
+    app.get("/ggui/console/blueprints/cached", async (_req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        if (!isEnumerableVectorStore(vectors)) {
+            res.status(501).json({
+                error: "enumeration_unsupported",
+                message: "The configured vector store does not support enumeration. " +
+                    "Wire an EnumerableVectorStore (default InMemoryVectorStore " +
+                    "or SqliteVectorStore) to surface the cache in the console.",
+            });
+            return;
+        }
+        try {
+            const entries = await listGenerationCache({ vectorStore: vectors }, DEFAULT_BUILDER_APP_ID);
+            const payload = entries;
+            res.json({ entries: payload, total: payload.length });
+        }
+        catch (err) {
+            logger.warn("console_blueprints_cached_list_failed", {
+                error: String(err),
+            });
+            res.status(500).json({
+                error: "cache_unavailable",
+                message: err instanceof Error
+                    ? `Generation cache failed to list — ${err.message}`
+                    : `Generation cache failed to list — ${String(err)}`,
+            });
+        }
+    });
+    // DELETE /ggui/console/blueprints/cached/:id — invalidate one
+    // cached entry. Idempotent — 204 whether the id was present or
+    // not (same contract as VectorStore.deleteVector). No enumerable
+    // gate — delete works on every vector-store implementation.
+    app.delete("/ggui/console/blueprints/cached/:id", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const id = req.params.id;
+        if (!id || id.length === 0) {
+            res.status(400).json({
+                error: "missing_id",
+                message: "Cache entry id required in path segment.",
+            });
+            return;
+        }
+        try {
+            await invalidateGenerationCache({ vectorStore: vectors }, DEFAULT_BUILDER_APP_ID, id);
+            res.status(204).end();
+        }
+        catch (err) {
+            logger.warn("console_blueprints_cached_invalidate_failed", {
+                error: String(err),
+                id,
+            });
+            res.status(500).json({
+                error: "cache_invalidate_failed",
+                message: err instanceof Error
+                    ? `Invalidate failed — ${err.message}`
+                    : `Invalidate failed — ${String(err)}`,
+            });
+        }
+    });
+    // POST /ggui/console/blueprints/cached/clear — bulk-delete every
+    // cached entry in the scope. Returns the count. Requires
+    // EnumerableVectorStore (we enumerate to find keys to delete).
+    app.post("/ggui/console/blueprints/cached/clear", async (_req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        if (!isEnumerableVectorStore(vectors)) {
+            res.status(501).json({
+                error: "enumeration_unsupported",
+                message: "Bulk-clear requires a vector store that supports " +
+                    "enumeration. Invalidate entries individually via " +
+                    "DELETE /ggui/console/blueprints/cached/:id, or wire an " +
+                    "EnumerableVectorStore to unlock bulk-clear.",
+            });
+            return;
+        }
+        try {
+            const result = await clearGenerationCache({ vectorStore: vectors }, DEFAULT_BUILDER_APP_ID);
+            res.json(result);
+        }
+        catch (err) {
+            logger.warn("console_blueprints_cached_clear_failed", {
+                error: String(err),
+            });
+            res.status(500).json({
+                error: "cache_clear_failed",
+                message: err instanceof Error ? `Clear failed — ${err.message}` : `Clear failed — ${String(err)}`,
+            });
+        }
+    });
+    // GET /ggui/console/blueprints/registry — list every blueprint
+    // registered in the three-tier matcher's storage.
+    // Sibling of `/blueprints/cached` and intentionally distinct from
+    // the declared-blueprint catalog at `/ggui/console/registry`:
+    //   - `/registry` (above) — operator-declared static catalog
+    //     (uiRegistry sources + primitiveCatalogs). Boot-time content.
+    //   - `/blueprints/cached` (legacy) — intent-keyed generation
+    //     cache. Retired.
+    //   - `/blueprints/registry` (this) — contract-keyed runtime
+    //     registry the matcher actually consults. Per-row tier
+    //     diagnostics: kind, contractKey, hitCount, lastHitAt.
+    //
+    // Optional `?kind=template|organism|molecule|atom` filter narrows
+    // by atomic-design level — kindless query returns everything.
+    app.get("/ggui/console/blueprints/registry", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        if (!isEnumerableVectorStore(vectors)) {
+            res.status(501).json({
+                error: "enumeration_unsupported",
+                message: "The configured vector store does not support enumeration. " +
+                    "Wire an EnumerableVectorStore (default InMemoryVectorStore " +
+                    "or SqliteVectorStore) to surface the registry in the console.",
+            });
+            return;
+        }
+        const rawKind = typeof req.query.kind === "string" ? req.query.kind : undefined;
+        const allowedKinds = ["template", "organism", "molecule", "atom"];
+        const kind = rawKind !== undefined
+            ? allowedKinds.find((k) => k === rawKind)
+            : undefined;
+        if (rawKind !== undefined && kind === undefined) {
+            res.status(400).json({
+                error: "invalid_kind",
+                message: `kind must be one of ${allowedKinds.join(", ")}; got '${rawKind}'.`,
+            });
+            return;
+        }
+        try {
+            const blueprints = await listBlueprints({ vectorStore: vectors }, DEFAULT_BUILDER_APP_ID, kind);
+            // Project to a wire-friendly view — `componentCode` is large
+            // and not load-bearing for the operator listing; surface a
+            // length signal instead so the UI can show "12 KB" without
+            // parsing 12 KB.
+            const entries = blueprints.map((bp) => ({
+                id: bp.id,
+                kind: bp.kind,
+                contractKey: bp.contractKey,
+                intent: bp.intent,
+                createdAt: bp.createdAt,
+                hitCount: bp.hitCount,
+                ...(bp.lastHitAt !== undefined ? { lastHitAt: bp.lastHitAt } : {}),
+                // Surface provenance (the BlueprintSource union — llm rows
+                // carry engine slug + model) plus the install-bridge
+                // lifecycle marker so operators can distinguish cold-gen vs.
+                // operator-registered vs. marketplace-installed rows on
+                // `/ggui/console/blueprints/registry`. Matcher behaviour is
+                // unchanged — provenance is purely informational.
+                source: bp.source,
+                ...(bp.installed === true ? { installed: true } : {}),
+                componentCodeBytes: bp.componentCode.length,
+            }));
+            res.json({ entries, total: entries.length });
+        }
+        catch (err) {
+            logger.warn("console_registry_list_failed", { error: String(err) });
+            res.status(500).json({
+                error: "registry_unavailable",
+                message: err instanceof Error
+                    ? `Registry list failed — ${err.message}`
+                    : `Registry list failed — ${String(err)}`,
+            });
+        }
+    });
+}

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

@@ -0,0 +1,89 @@
+/**
+ * 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 type { CodeStore, GguiSessionStore, ShortCodeIndex } from "@ggui-ai/mcp-server-core";
+import type { Express } from "express";
+import type { GguiSessionChannelCookieAuth } from "./ggui-session-channel.js";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** Shared HMAC secret backing the console cookie mint/verify pair. */
+    readonly secret: string;
+    /** shortCode → render binding the cookie-mint route resolves through. */
+    readonly shortCodeIndex: ShortCodeIndex;
+    /** Cookie TTL override (undefined → helper default, 8h). */
+    readonly cookieTtlSec?: number;
+    /** Mark the cookie Secure (TLS-terminating deployments). */
+    readonly cookieSecure: boolean;
+    /** GguiSession store the gate + observation routes read. */
+    readonly renderStore?: GguiSessionStore;
+    /** Live-mode credential minter (`mcpApps: true` at construction). */
+    readonly mintBootstrap?: (sessionId: string, appId: string) => {
+        wsUrl: string;
+        token: string;
+        expiresAt: string;
+    };
+    /** Runtime-bundle bootstrap URL (rewritten absolute on meta reads). */
+    readonly runtimeBootstrapUrl: string;
+    /** Content-addressable store for the validator-bundle emission. */
+    readonly codeStore?: CodeStore;
+    /** Operator-configured public origin for absolute URL composition. */
+    readonly publicBaseUrl?: string;
+    /** Parent logger; the mount derives its `console-cookie` child. */
+    readonly logger: Logger;
+}
+/**
+ * Mount the console session routes onto the express app and return
+ * the cookie-auth binding for the live channel.
+ */
+export declare function mountConsoleSessionRoutes(opts: MountOptions): GguiSessionChannelCookieAuth;
+export {};
+//# sourceMappingURL=console-session-routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"console-session-routes.d.ts","sourceRoot":"","sources":["../src/console-session-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAQ5F,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAQ1D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,qEAAqE;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,KACV;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,uEAAuE;IACvE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,4BAA4B,CA0V1F"}