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

package/dist/build-mcp.js

@@ -10,7 +10,9 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
+import { isRecord } from '@ggui-ai/protocol';
 import { z } from 'zod';
+import { isHandlerFailure, } from '@ggui-ai/mcp-server-handlers';
 import { installMcpAppsOutbound, } from './mcp-apps-outbound.js';
 /**
  * Build a fresh MCP server with every handler registered.
@@ -74,16 +76,42 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
             // deadline. Both ride the canonical context without leaking the
             // SDK type into the handlers package.
             const baseCtx = getContext();
+            // `_meta` is `unknown` at the SDK seam; per JSON-RPC it MUST be
+            // an object, so narrow with the validating predicate and DROP
+            // anything else rather than asserting.
+            const requestMeta = extra?._meta;
             const ctx = {
                 ...baseCtx,
-                ...(extra?._meta !== undefined
-                    ? { requestMeta: extra._meta }
-                    : {}),
+                ...(isRecord(requestMeta) ? { requestMeta } : {}),
                 ...(extra?.signal !== undefined ? { signal: extra.signal } : {}),
             };
             const start = Date.now();
             try {
                 const data = await handler.handler(input, ctx);
+                // First-class in-result failure channel. A handler that
+                // returns the `HandlerFailure` marker gets an `isError: true`
+                // TOOL RESULT (never a thrown/JSON-RPC error): the marker's
+                // `errorText` is the model-visible content, and its `data` is
+                // validated against the SAME outputSchema as a success — MCP
+                // SDK clients validate structuredContent against outputSchema
+                // even when isError is set, so the envelope stays
+                // schema-conformant. NO `_meta` on failures: `resultMeta` is
+                // not invoked, so no mount affordance / bootstrap slice is
+                // emitted for a failed call.
+                if (isHandlerFailure(data)) {
+                    const validated = z.object(handler.outputSchema).parse(data.data);
+                    logger.warn('tool_invoked', {
+                        tool: handler.name,
+                        appId: ctx.appId,
+                        outcome: 'tool_error',
+                        elapsedMs: Date.now() - start,
+                    });
+                    return {
+                        isError: true,
+                        structuredContent: validated,
+                        content: [{ type: 'text', text: data.errorText }],
+                    };
+                }
                 const validated = z.object(handler.outputSchema).parse(data);
                 // Per-result `_meta` — NOT merged into structuredContent, so
                 // agents that typecheck against the tool signature never see
@@ -128,11 +156,18 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
         // single canonical key only; the helper owns the back-compat
         // shape. Handlers without `_meta.ui` fall through to plain
         // `registerTool` — the ext-apps helper requires `_meta.ui` to be
-        // typed.
+        // typed. A declared-but-malformed `_meta.ui` is a programming
+        // error on the handler author's side — fail loud rather than
+        // silently registering the tool without its UI surface.
         if (handler._meta && 'ui' in handler._meta) {
+            const ui = handler._meta['ui'];
+            if (!isMcpUiToolMeta(ui)) {
+                throw new Error(`Tool ${handler.name} declares _meta.ui with an invalid shape — ` +
+                    `expected { resourceUri?: string; visibility?: ('model' | 'app')[] }.`);
+            }
             registerAppTool(server, handler.name, {
                 ...baseConfig,
-                _meta: handler._meta,
+                _meta: { ...handler._meta, ui },
             }, cb);
         }
         else {
@@ -144,6 +179,30 @@ export function buildMcpServer(info, handlers, getContext, logger, opts = {}) {
     }
     return server;
 }
+/**
+ * Validating narrower for declaration-level MCP-Apps UI meta. The
+ * `SharedHandler` seam types `_meta` as `Record<string, unknown>`;
+ * `registerAppTool` requires `_meta.ui` typed as `McpUiToolMeta`.
+ * Validates the two fields the ext-apps helper actually reads —
+ * `resourceUri` (string when present) and `visibility`
+ * (`"model"`/`"app"` array when present) — instead of asserting
+ * blindly across the SDK seam.
+ */
+function isMcpUiToolMeta(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.resourceUri !== undefined && typeof value.resourceUri !== 'string') {
+        return false;
+    }
+    if (value.visibility !== undefined) {
+        if (!Array.isArray(value.visibility))
+            return false;
+        if (!value.visibility.every((v) => v === 'model' || v === 'app')) {
+            return false;
+        }
+    }
+    return true;
+}
 function errorClassName(err) {
     if (err instanceof Error) {
         if (err.name && err.name !== 'Error')

package/dist/code-routes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Content-addressable code delivery routes.
+ *
+ * GET /code/:hash.js — content-addressable componentCode delivery.
+ * GET /contract/:hash.js — content-addressable contract-validator-bundle
+ *   delivery (#109).
+ *
+ * Both routes serve from the same {@link CodeStore} keyed by
+ * `sha256(bytes)`. The same store is safe to share — content-addressable
+ * hashes can't collide across kinds unless the bytes are identical
+ * (in which case the cached value is equally valid for either path).
+ * Two separate URLs exist for debuggability + protocol clarity: a
+ * request to `/code/<hash>.js` is unambiguously a component fetch;
+ * `/contract/<hash>.js` is unambiguously a validator-bundle fetch.
+ *
+ * Cache posture: `Cache-Control: public, max-age=31536000, immutable` —
+ * hash is content-derived, the bytes can NEVER change for a given URL,
+ * so browsers + CDNs cache forever (immutable means "don't even
+ * revalidate"). A second render with the same componentCode / contract
+ * hits browser cache for free.
+ *
+ * CORS: same `*` posture as `/r/:shortCode` (JSON branch) — bytes are
+ * public-by-shortCode anyway (the agent already shared the URL with
+ * the host), and the bytes carry no credentials.
+ *
+ * Validation: hash MUST match `[a-f0-9]{64}` — strict charset gate
+ * closes path-traversal (`..`, `/`) and other shenanigans before the
+ * store sees the parameter.
+ */
+import type { CodeStore } 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;
+    /** Content-addressable store both routes serve from. */
+    readonly codeStore: CodeStore;
+    /** Structured logger for fetch-failure warnings. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `GET /code/:hash.js` + `GET /contract/:hash.js` onto the
+ * express app. Returns nothing — the routes self-register.
+ */
+export declare function mountCodeRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=code-routes.d.ts.map

package/dist/code-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-routes.d.ts","sourceRoot":"","sources":["../src/code-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA6CxD"}

package/dist/code-routes.js

@@ -0,0 +1,81 @@
+/**
+ * Content-addressable code delivery routes.
+ *
+ * GET /code/:hash.js — content-addressable componentCode delivery.
+ * GET /contract/:hash.js — content-addressable contract-validator-bundle
+ *   delivery (#109).
+ *
+ * Both routes serve from the same {@link CodeStore} keyed by
+ * `sha256(bytes)`. The same store is safe to share — content-addressable
+ * hashes can't collide across kinds unless the bytes are identical
+ * (in which case the cached value is equally valid for either path).
+ * Two separate URLs exist for debuggability + protocol clarity: a
+ * request to `/code/<hash>.js` is unambiguously a component fetch;
+ * `/contract/<hash>.js` is unambiguously a validator-bundle fetch.
+ *
+ * Cache posture: `Cache-Control: public, max-age=31536000, immutable` —
+ * hash is content-derived, the bytes can NEVER change for a given URL,
+ * so browsers + CDNs cache forever (immutable means "don't even
+ * revalidate"). A second render with the same componentCode / contract
+ * hits browser cache for free.
+ *
+ * CORS: same `*` posture as `/r/:shortCode` (JSON branch) — bytes are
+ * public-by-shortCode anyway (the agent already shared the URL with
+ * the host), and the bytes carry no credentials.
+ *
+ * Validation: hash MUST match `[a-f0-9]{64}` — strict charset gate
+ * closes path-traversal (`..`, `/`) and other shenanigans before the
+ * store sees the parameter.
+ */
+import { CODE_HASH_REGEX } from "@ggui-ai/mcp-server-core";
+/**
+ * Mount `GET /code/:hash.js` + `GET /contract/:hash.js` onto the
+ * express app. Returns nothing — the routes self-register.
+ */
+export function mountCodeRoutes(opts) {
+    const { app, codeStore, logger } = opts;
+    const mountContentAddressableRoute = (mountPath, label) => {
+        app.get(mountPath, async (req, res) => {
+            res.setHeader("Access-Control-Allow-Origin", "*");
+            const hash = req.params["hash"];
+            if (typeof hash !== "string" || !CODE_HASH_REGEX.test(hash)) {
+                res.setHeader("Cache-Control", "no-store");
+                res.status(400).json({
+                    error: {
+                        code: "invalid_request",
+                        message: "hash path parameter must be 64-char lowercase hex",
+                    },
+                });
+                return;
+            }
+            try {
+                const code = await codeStore.get(hash);
+                if (code === null) {
+                    res.setHeader("Cache-Control", "no-store");
+                    res.status(404).json({
+                        error: {
+                            code: "not_found",
+                            message: `unknown ${label} hash`,
+                        },
+                    });
+                    return;
+                }
+                res.setHeader("Content-Type", "application/javascript; charset=utf-8");
+                res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+                res.status(200).send(code);
+            }
+            catch (err) {
+                logger.warn(`${label}_route_failed`, { hash, error: String(err) });
+                res.setHeader("Cache-Control", "no-store");
+                res.status(500).json({
+                    error: {
+                        code: "internal",
+                        message: `${label} fetch failed`,
+                    },
+                });
+            }
+        });
+    };
+    mountContentAddressableRoute("/code/:hash.js", "code");
+    mountContentAddressableRoute("/contract/:hash.js", "contract");
+}

package/dist/code-store-fs.js

@@ -29,7 +29,7 @@
  * The store grows unbounded. Operators who care can periodically
  * `rm -rf ~/.ggui/code-cache/` — every entry is content-addressable
  * and immutable, so a re-fetch will repopulate from upstream code on
- * next push. There is no eviction policy in the seam itself.
+ * next render. There is no eviction policy in the seam itself.
  *
  * ## Permissions
  *
@@ -61,7 +61,7 @@ export class FileSystemCodeStore {
         const absPath = this.absPath(hash);
         // Idempotent: if the file already exists, skip rewrite. Cheap fast
         // path that avoids unnecessary disk churn when the same blueprint
-        // is pushed repeatedly.
+        // is rendered repeatedly.
         if (await fileExists(absPath))
             return;
         await mkdir(dirname(absPath), { recursive: true });

package/dist/console-auth.d.ts

@@ -33,23 +33,23 @@
  * so the cookie never leaves the console's origin in the first
  * place.
  *
- * Lifecycle. Cookie is minted at `POST /ggui/console/render-cookie`
+ * Lifecycle. Cookie is minted at `POST /ggui/console/session-cookie`
  * (operator posts a shortCode → server resolves → sets Set-Cookie).
  * Cookie is consumed at `GET /ws` upgrade (if the server composition
- * wires `cookieAuth` to the session-channel). Never mutated in
+ * wires `cookieAuth` to the render-channel). Never mutated in
  * between.
  */
 import type { IncomingHttpHeaders } from 'node:http';
 /**
  * Cookie name. Chosen deliberately to NOT conflict with common framework
  * cookies (Express session, CSRF, etc.). Change carries a compat
- * concern — the console SPA + the session-channel upgrade read by
+ * concern — the console SPA + the render-channel upgrade read by
  * this exact name. Keep this export as the single source of truth.
  */
 export declare const CONSOLE_COOKIE_NAME = "ggui_console_session";
 /**
  * Result of minting a cookie. Callers set the cookie on their response
- * (the cookie endpoint) and echo the bound `renderId`/`appId` back in
+ * (the cookie endpoint) and echo the bound `sessionId`/`appId` back in
  * the response body so the client SPA can bootstrap the viewer without
  * a follow-up round-trip.
  */
@@ -57,11 +57,11 @@ export interface DevtoolCookieMint {
     readonly cookieValue: string;
     readonly setCookieHeader: string;
     readonly expiresAt: number;
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly appId: string;
 }
 export interface MintDevtoolCookieInput {
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly appId: string;
     /** HMAC secret. Shared with bootstrap + session tokens by design. */
     readonly secret: string;
@@ -84,7 +84,7 @@ export interface MintDevtoolCookieInput {
     readonly sameSite?: 'Strict' | 'Lax' | 'None';
 }
 /**
- * Mint a cookie value bound to `{ renderId, appId }` and the formatted
+ * Mint a cookie value bound to `{ sessionId, appId }` and the formatted
  * `Set-Cookie` header to send on the response. Caller does
  * `res.setHeader('Set-Cookie', result.setCookieHeader)`.
  */
@@ -117,11 +117,11 @@ export declare function extractDevtoolCookie(cookieHeader: string | undefined):
 export declare function readDevtoolCookieFromHeaders(headers: IncomingHttpHeaders): string | null;
 /**
  * Verified claims extracted from an console cookie. Scope is
- * deliberately narrow: just the binding the session-channel upgrade
- * needs to enforce `subscribe.renderId === cookie.renderId`.
+ * deliberately narrow: just the binding the render-channel upgrade
+ * needs to enforce `subscribe.sessionId === cookie.sessionId`.
  */
 export interface DevtoolCookieClaims {
-    readonly renderId: string;
+    readonly sessionId: string;
     readonly appId: string;
 }
 /**

package/dist/console-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"console-auth.d.ts","sourceRoot":"","sources":["../src/console-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAOrD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CAC/C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,sBAAsB,GAC5B,iBAAiB,CAqBnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAcf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mBAAmB,GAC3B,MAAM,GAAG,IAAI,CAIf;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,mBAAmB,GAAG,IAAI,CAO5B"}
+{"version":3,"file":"console-auth.d.ts","sourceRoot":"","sources":["../src/console-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAOrD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CAC/C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,sBAAsB,GAC5B,iBAAiB,CAqBnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAcf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mBAAmB,GAC3B,MAAM,GAAG,IAAI,CAIf;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,mBAAmB,GAAG,IAAI,CAO5B"}

package/dist/console-auth.js

@@ -2,18 +2,18 @@ import { DEFAULT_DEVTOOL_SESSION_TTL_SEC, mintDevtoolSessionToken, verifyToken,
 /**
  * Cookie name. Chosen deliberately to NOT conflict with common framework
  * cookies (Express session, CSRF, etc.). Change carries a compat
- * concern — the console SPA + the session-channel upgrade read by
+ * concern — the console SPA + the render-channel upgrade read by
  * this exact name. Keep this export as the single source of truth.
  */
 export const CONSOLE_COOKIE_NAME = 'ggui_console_session';
 /**
- * Mint a cookie value bound to `{ renderId, appId }` and the formatted
+ * Mint a cookie value bound to `{ sessionId, appId }` and the formatted
  * `Set-Cookie` header to send on the response. Caller does
  * `res.setHeader('Set-Cookie', result.setCookieHeader)`.
  */
 export function mintDevtoolCookie(input) {
     const ttlSec = input.ttlSec ?? DEFAULT_DEVTOOL_SESSION_TTL_SEC;
-    const { token, claims } = mintDevtoolSessionToken({ renderId: input.renderId, appId: input.appId, ttlSec }, input.secret);
+    const { token, claims } = mintDevtoolSessionToken({ sessionId: input.sessionId, appId: input.appId, ttlSec }, input.secret);
     const attrs = [
         `${CONSOLE_COOKIE_NAME}=${token}`,
         `Path=${input.path ?? '/'}`,
@@ -27,7 +27,7 @@ export function mintDevtoolCookie(input) {
         cookieValue: token,
         setCookieHeader: attrs.join('; '),
         expiresAt: claims.exp * 1000,
-        renderId: input.renderId,
+        sessionId: input.sessionId,
         appId: input.appId,
     };
 }
@@ -96,7 +96,7 @@ export function verifyDevtoolCookie(cookieValue, secret) {
     if (!result.ok)
         return null;
     return {
-        renderId: result.claims.renderId,
+        sessionId: result.claims.sessionId,
         appId: result.claims.appId,
     };
 }

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

@@ -0,0 +1,71 @@
+/**
+ * Console blueprint resolution + try-live routes.
+ *
+ *   GET  /ggui/console/blueprint/:id       — same-origin HTTP mirror of
+ *        the `ggui_render_blueprint` MCP tool. Resolves a
+ *        manifest-declared blueprint id to its compiled bundle +
+ *        metadata via the wired `UiRegistry`; lets the SPA's
+ *        `/preview/<id>` route mount the blueprint with a single fetch
+ *        instead of negotiating a full MCP round-trip from the browser.
+ *   POST /ggui/console/blueprint/:id/try   — create a render, compile
+ *        the blueprint's componentCode, commit a render with its full
+ *        contract (actionSpec/streamSpec/propsSpec from the manifest),
+ *        mint a shortCode, and return `{sessionId, shortCode, url}`.
+ *        The returned `/s/<shortCode>` lands on the console's render
+ *        viewer + subscribes to the render over `/ws`.
+ *
+ * Scope: registered only when a `UiRegistry` is present (same gate
+ * as the MCP render handler — no registry = no render path, no
+ * endpoint). No bearer auth: console routes are same-origin
+ * operator-facing; the operator already has OS access to the TSX
+ * sources this endpoint serves back.
+ *
+ * GET failure shape: { error, message } with a matching HTTP code.
+ *   - 404 for unknown id OR known-id-no-bundle (source-only /
+ *     compile-failed). The operator's remediation is the same in
+ *     both cases (fix the manifest / fix the entry / fix the
+ *     compile); splitting codes would add noise without signal.
+ *   - 400 for malformed id parameters (empty, oversized).
+ *
+ * Shape symmetry: GET matches `GguiRenderBlueprintOutput` exactly, so
+ * the browser-side fetch can share a type import with MCP-tool
+ * callers without a translation layer.
+ *
+ * Try-live gates (all three required):
+ *   - `uiRegistry`     — blueprint resolution
+ *   - `renderStore`    — render persistence
+ *   - `shortCodeIndex` — shortCode → render binding
+ *
+ * Partial gate (uiRegistry alone) → 503 with a remediation hint.
+ */
+import type { GguiSessionStore, ShortCodeIndex } from "@ggui-ai/mcp-server-core";
+import type { SharedHandler } from "@ggui-ai/mcp-server-handlers";
+import type { UiRegistry } from "@ggui-ai/ui-registry";
+import type { Express } from "express";
+import type { ZodRawShape } from "zod";
+import type { Logger } from "./logger.js";
+import { type SchemaCompatMode } from "./schema-compat.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** Blueprint registry both routes resolve against. */
+    readonly uiRegistry: UiRegistry;
+    /** GguiSession store the try route commits into (gate 2 of 3). */
+    readonly renderStore?: GguiSessionStore;
+    /** shortCode → render binding for the try route (gate 3 of 3). */
+    readonly shortCodeIndex?: ShortCodeIndex;
+    /** Composed handler list the schema-compat check validates against. */
+    readonly handlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
+    /** Schema-compat posture (`reject` default / `warn` / `off`). */
+    readonly schemaCompatMode: SchemaCompatMode;
+    /** Structured logger. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `GET /ggui/console/blueprint/:id` +
+ * `POST /ggui/console/blueprint/:id/try` onto the express app.
+ * Returns nothing — the routes self-register.
+ */
+export declare function mountConsoleBlueprintRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=console-blueprint-routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"console-blueprint-routes.d.ts","sourceRoot":"","sources":["../src/console-blueprint-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAGvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAqB5B,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E,iEAAiE;IACjE,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAwRpE"}