@miragon/pulse-widget-shell 0.0.0-bootstrap.0 → 0.21.0

package/dist/font-assets.d.ts

@@ -0,0 +1,47 @@
+import type { AppResourceCsp } from "@miragon/mcp-toolkit-core";
+import type { HttpRouteHost } from "./health.js";
+/** A served file: its name under the route and its bytes. */
+export interface FontAsset {
+    file: string;
+    body: Uint8Array<ArrayBuffer>;
+}
+/** A year, and never revalidated: a new font release is a new URL. */
+export declare const FONT_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/**
+ * Where the `@fontsource-variable` packages keep the files, by served name.
+ * `require.resolve` with literal specifiers, so the dependency stays visible
+ * to the dead-code check; `font-assets.test.ts` holds the names equal to
+ * {@link SERVED_FONT_FILES}.
+ */
+export declare function servedFontPaths(): Record<string, string>;
+/** The woff2 files, read once (boot). */
+export declare function loadServedFonts(paths?: () => Record<string, string>): FontAsset[];
+/** The answer for one file — a fresh `Response` per request (a body is read once). */
+export declare function fontResponse(body: Uint8Array<ArrayBuffer>): Response;
+export interface FontAssetsOptions {
+    /** Route prefix (default {@link SERVED_FONT_PATH} — the views load from there). */
+    path?: string;
+    /** The files (default {@link loadServedFonts}). */
+    load?: () => FontAsset[];
+    /** Log prefix for the warning when the files cannot be read (default `fonts`). */
+    label?: string;
+}
+/**
+ * Register `GET <path>/<file>` for each served font. Returns the registered
+ * routes — none when the files cannot be read: the boot goes on with a
+ * warning and the views render the host's font (Geist is cosmetic, never a
+ * reason to refuse service).
+ */
+export declare function installFontAssets(server: HttpRouteHost, options?: FontAssetsOptions): string[];
+/**
+ * The view CSP that admits the font origin explicitly: `MCP_URL`'s origin in
+ * `resourceDomains` — the origin a view resolves its font URLs against
+ * (`servedFontBaseUrl`). Handed to `createFrameworkApp` as `app.csp`, it
+ * reaches `render-view` and every module widget tool (`honorWidgetMetaDefaults`),
+ * on `resources/list` too, and the Apps SDK `openai/widgetCSP`. `undefined`
+ * without `MCP_URL` (local dev): mcp-use still appends the request-resolved
+ * server origin on every `resources/read`, which is where the view loads from.
+ * Call it after `resolveHttpEdgePolicy` validated `MCP_URL`.
+ */
+export declare function fontAssetsCsp(env: NodeJS.ProcessEnv): AppResourceCsp | undefined;
+//# sourceMappingURL=font-assets.d.ts.map

package/dist/font-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-assets.d.ts","sourceRoot":"","sources":["../src/font-assets.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAGhD,6DAA6D;AAC7D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,CAAA;CAC9B;AAED,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,wCAAwC,CAAA;AAIvE;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxD;AAED,yCAAyC;AACzC,wBAAgB,eAAe,CAC7B,KAAK,GAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAmB,GACpD,SAAS,EAAE,CAEb;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,QAAQ,CAapE;AAED,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,SAAS,EAAE,CAAA;IACxB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,iBAAsB,GAC9B,MAAM,EAAE,CAcV;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,cAAc,GAAG,SAAS,CAGhF"}

package/dist/font-assets.js

@@ -0,0 +1,93 @@
+/**
+ * The font route of a composed server (server path only): Geist and Geist
+ * Mono as woff2, served by THIS server so the views render the Miragon type
+ * without a CDN (design system §4: self-hosted, offline-capable, GDPR-safe)
+ * and without inlining ~50 KB of base64 into every view resource.
+ *
+ * A view runs in the host's sandboxed iframe on a foreign origin, so the
+ * files travel cross-origin: the response allows any origin (CORS, CORP —
+ * public static files, no credentials), and the view's CSP must admit the
+ * server's origin in `resourceDomains` (`fontAssetsCsp` + mcp-use's own
+ * request-resolved append). The URL is versioned (`SERVED_FONT_PATH`), so the
+ * files are cached `immutable` for a year. Where a host blocks the origin or
+ * cannot reach the server, `font-display: swap` keeps the text in the host's
+ * font, then the system's — nothing waits for the files.
+ *
+ * Registered after the HTTP edge guard (`installHttpEdgeGuard`): a font GET
+ * passes the `Origin` half (safe method) but not a foreign `Host`, like every
+ * other non-operational route.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { SERVED_FONT_FILES, SERVED_FONT_PATH } from "./served-fonts.js";
+/** A year, and never revalidated: a new font release is a new URL. */
+export const FONT_CACHE_CONTROL = "public, max-age=31536000, immutable";
+const require = createRequire(import.meta.url);
+/**
+ * Where the `@fontsource-variable` packages keep the files, by served name.
+ * `require.resolve` with literal specifiers, so the dependency stays visible
+ * to the dead-code check; `font-assets.test.ts` holds the names equal to
+ * {@link SERVED_FONT_FILES}.
+ */
+export function servedFontPaths() {
+    return {
+        [SERVED_FONT_FILES.sans]: require.resolve("@fontsource-variable/geist/files/geist-latin-wght-normal.woff2"),
+        [SERVED_FONT_FILES.mono]: require.resolve("@fontsource-variable/geist-mono/files/geist-mono-latin-wght-normal.woff2"),
+    };
+}
+/** The woff2 files, read once (boot). */
+export function loadServedFonts(paths = servedFontPaths) {
+    return Object.entries(paths()).map(([file, path]) => ({ file, body: readFileSync(path) }));
+}
+/** The answer for one file — a fresh `Response` per request (a body is read once). */
+export function fontResponse(body) {
+    return new Response(body, {
+        headers: {
+            "content-type": "font/woff2",
+            "content-length": String(body.byteLength),
+            "cache-control": FONT_CACHE_CONTROL,
+            // Fonts are fetched in CORS mode from the view's sandboxed (often
+            // opaque, `null`) origin; public files, so any origin and no credentials.
+            "access-control-allow-origin": "*",
+            "cross-origin-resource-policy": "cross-origin",
+            "x-content-type-options": "nosniff",
+        },
+    });
+}
+/**
+ * Register `GET <path>/<file>` for each served font. Returns the registered
+ * routes — none when the files cannot be read: the boot goes on with a
+ * warning and the views render the host's font (Geist is cosmetic, never a
+ * reason to refuse service).
+ */
+export function installFontAssets(server, options = {}) {
+    const { path = SERVED_FONT_PATH, load = loadServedFonts, label = "fonts" } = options;
+    let assets;
+    try {
+        assets = load();
+    }
+    catch (error) {
+        console.warn(`[${label}] Geist is not served (views use the host's font):`, error);
+        return [];
+    }
+    return assets.map(({ file, body }) => {
+        const route = `${path}/${file}`;
+        server.get(route, () => fontResponse(body));
+        return route;
+    });
+}
+/**
+ * The view CSP that admits the font origin explicitly: `MCP_URL`'s origin in
+ * `resourceDomains` — the origin a view resolves its font URLs against
+ * (`servedFontBaseUrl`). Handed to `createFrameworkApp` as `app.csp`, it
+ * reaches `render-view` and every module widget tool (`honorWidgetMetaDefaults`),
+ * on `resources/list` too, and the Apps SDK `openai/widgetCSP`. `undefined`
+ * without `MCP_URL` (local dev): mcp-use still appends the request-resolved
+ * server origin on every `resources/read`, which is where the view loads from.
+ * Call it after `resolveHttpEdgePolicy` validated `MCP_URL`.
+ */
+export function fontAssetsCsp(env) {
+    const url = env.MCP_URL?.trim();
+    return url ? { resourceDomains: [new URL(url).origin] } : undefined;
+}
+//# sourceMappingURL=font-assets.js.map

package/dist/font-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-assets.js","sourceRoot":"","sources":["../src/font-assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAQvE,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,qCAAqC,CAAA;AAEvE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,CAAC,iBAAiB,CAAC,IAAI,CAAC,EACtB,OAAO,CAAC,OAAO,CAAC,gEAAgE,CAAC;QACnF,CAAC,iBAAiB,CAAC,IAAI,CAAC,EACtB,OAAO,CAAC,OAAO,CAAC,0EAA0E,CAAC;KAC9F,CAAA;AACH,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,eAAe,CAC7B,QAAsC,eAAe;IAErD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;AAC5F,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,IAA6B;IACxD,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;QACxB,OAAO,EAAE;YACP,cAAc,EAAE,YAAY;YAC5B,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;YACzC,eAAe,EAAE,kBAAkB;YACnC,kEAAkE;YAClE,0EAA0E;YAC1E,6BAA6B,EAAE,GAAG;YAClC,8BAA8B,EAAE,cAAc;YAC9C,wBAAwB,EAAE,SAAS;SACpC;KACF,CAAC,CAAA;AACJ,CAAC;AAWD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAqB,EACrB,UAA6B,EAAE;IAE/B,MAAM,EAAE,IAAI,GAAG,gBAAgB,EAAE,IAAI,GAAG,eAAe,EAAE,KAAK,GAAG,OAAO,EAAE,GAAG,OAAO,CAAA;IACpF,IAAI,MAAmB,CAAA;IACvB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,EAAE,CAAA;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,oDAAoD,EAAE,KAAK,CAAC,CAAA;QAClF,OAAO,EAAE,CAAA;IACX,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE;QACnC,MAAM,KAAK,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAA;QAC/B,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;QAC3C,OAAO,KAAK,CAAA;IACd,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,GAAsB;IAClD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,CAAA;IAC/B,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AACrE,CAAC"}

package/dist/font-assets.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=font-assets.test.d.ts.map

package/dist/font-assets.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-assets.test.d.ts","sourceRoot":"","sources":["../src/font-assets.test.ts"],"names":[],"mappings":""}

package/dist/font-assets.test.js

@@ -0,0 +1,123 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FONT_CACHE_CONTROL, fontAssetsCsp, fontResponse, installFontAssets, loadServedFonts, servedFontPaths, } from "./font-assets.js";
+import { SERVED_FONT_FILES } from "./served-fonts.js";
+/** A woff2 file starts with the signature `wOF2`. */
+const WOFF2_SIGNATURE = [0x77, 0x4f, 0x46, 0x32];
+/** Records `server.get(path, handler)` like the health suite's fake host. */
+function fakeHost() {
+    const routes = new Map();
+    const host = {
+        get: (path, handler) => {
+            routes.set(path, handler);
+        },
+    };
+    return { host, routes };
+}
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("loadServedFonts", () => {
+    it("reads Geist and Geist Mono (latin, variable) from the fontsource packages", () => {
+        const fonts = loadServedFonts();
+        expect(fonts.map((font) => font.file)).toEqual([
+            "geist-latin-wght-normal.woff2",
+            "geist-mono-latin-wght-normal.woff2",
+        ]);
+        for (const { file, body } of fonts) {
+            expect([...body.subarray(0, 4)], file).toEqual(WOFF2_SIGNATURE);
+            // Latin subsets, not the full families: tens of KB, not hundreds.
+            expect(body.byteLength, file).toBeGreaterThan(10_000);
+            expect(body.byteLength, file).toBeLessThan(60_000);
+        }
+    });
+    it("finds each served file in its fontsource package under the name the views load", () => {
+        const paths = servedFontPaths();
+        expect(Object.keys(paths)).toEqual(Object.values(SERVED_FONT_FILES));
+        expect(paths[SERVED_FONT_FILES.sans]).toMatch(/@fontsource-variable\/geist\/files\/geist-latin-wght-normal\.woff2$/);
+        expect(paths[SERVED_FONT_FILES.mono]).toMatch(/@fontsource-variable\/geist-mono\/files\/geist-mono-latin-wght-normal\.woff2$/);
+    });
+    it("reads the files it is pointed at and fails loudly on a missing one", () => {
+        expect(() => loadServedFonts(() => ({ "x.woff2": "/nonexistent/x.woff2" }))).toThrow(/ENOENT/);
+    });
+});
+describe("fontResponse", () => {
+    it("answers woff2, cached immutable for a year, readable from any origin", async () => {
+        const body = new Uint8Array([0x77, 0x4f, 0x46, 0x32, 1, 2]);
+        const res = fontResponse(body);
+        expect(res.status).toBe(200);
+        expect(Object.fromEntries(res.headers)).toEqual({
+            "content-type": "font/woff2",
+            "content-length": "6",
+            "cache-control": "public, max-age=31536000, immutable",
+            "access-control-allow-origin": "*",
+            "cross-origin-resource-policy": "cross-origin",
+            "x-content-type-options": "nosniff",
+        });
+        expect(FONT_CACHE_CONTROL).toBe("public, max-age=31536000, immutable");
+        expect(new Uint8Array(await res.arrayBuffer())).toEqual(body);
+    });
+});
+describe("installFontAssets", () => {
+    it("registers one GET route per file under the versioned font path", async () => {
+        const { host, routes } = fakeHost();
+        const installed = installFontAssets(host);
+        expect(installed).toEqual([
+            "/fonts/geist-5.3.0/geist-latin-wght-normal.woff2",
+            "/fonts/geist-5.3.0/geist-mono-latin-wght-normal.woff2",
+        ]);
+        expect([...routes.keys()]).toEqual(installed);
+        // A fresh Response per request: a body can be read only once.
+        const handler = routes.get(installed[0]);
+        const first = await handler({});
+        const second = await handler({});
+        expect(first).not.toBe(second);
+        expect((await first.arrayBuffer()).byteLength).toBe((await second.arrayBuffer()).byteLength);
+    });
+    it("serves what the loader returns under the path it is given", async () => {
+        const { host, routes } = fakeHost();
+        const fonts = [{ file: "x.woff2", body: new Uint8Array([1, 2, 3]) }];
+        expect(installFontAssets(host, { path: "/assets", load: () => fonts })).toEqual([
+            "/assets/x.woff2",
+        ]);
+        const res = await routes.get("/assets/x.woff2")({});
+        expect(new Uint8Array(await res.arrayBuffer())).toEqual(new Uint8Array([1, 2, 3]));
+    });
+    it("boots on without the route when the files cannot be read — the views use the host's font", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const { host, routes } = fakeHost();
+        const failure = new Error("ENOENT");
+        const installed = installFontAssets(host, {
+            label: "edge",
+            load: () => {
+                throw failure;
+            },
+        });
+        expect(installed).toEqual([]);
+        expect(routes.size).toBe(0);
+        expect(warn).toHaveBeenCalledWith("[edge] Geist is not served (views use the host's font):", failure);
+    });
+    it("labels its warning `fonts` by default", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        installFontAssets(fakeHost().host, {
+            load: () => {
+                throw new Error("x");
+            },
+        });
+        expect(warn).toHaveBeenCalledWith(expect.stringMatching(/^\[fonts\] /), expect.any(Error));
+    });
+});
+describe("fontAssetsCsp", () => {
+    it("admits MCP_URL's origin in resourceDomains — the origin the views load fonts from", () => {
+        expect(fontAssetsCsp({ MCP_URL: "https://mcp.example.com/mcp" })).toEqual({
+            resourceDomains: ["https://mcp.example.com"],
+        });
+        expect(fontAssetsCsp({ MCP_URL: "  http://10.0.0.7:8400/  " })).toEqual({
+            resourceDomains: ["http://10.0.0.7:8400"],
+        });
+    });
+    it("declares nothing without MCP_URL: mcp-use appends the request-resolved origin itself", () => {
+        expect(fontAssetsCsp({})).toBeUndefined();
+        expect(fontAssetsCsp({ MCP_URL: "  " })).toBeUndefined();
+    });
+});
+//# sourceMappingURL=font-assets.test.js.map

package/dist/font-assets.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-assets.test.js","sourceRoot":"","sources":["../src/font-assets.test.ts"],"names":[],"mappings":"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"}

package/dist/health.d.ts

@@ -0,0 +1,59 @@
+/**
+ * HTTP health endpoints for composed-server hosts (server path only).
+ *
+ * Kubernetes-style split: `<path>/live` answers as soon as the process serves
+ * HTTP (only a wedged event loop fails it); `<path>/ready` additionally runs
+ * the host's readiness checks — the server's OWN dependencies (the profile/
+ * dashboard database), deliberately never the engines or Prometheus: those
+ * are upstreams whose outages the tools report as error results, and taking
+ * the server out of rotation for them would turn a visible error into a
+ * silent absence. The bare `<path>` aliases readiness for probes that know
+ * only one URL (Docker HEALTHCHECK, Fly, Compose `service_healthy`).
+ *
+ * Outside mcp-use's OAuth gate by construction: the bearer check is scoped
+ * to the MCP base path, so probes need no token.
+ */
+/**
+ * The narrow structural route surface (`server.get(path, handler)`) — hosts
+ * pass an `MCPServer` without this module importing mcp-use or hono. Handlers
+ * return Web-standard `Response`s, which hono passes through untouched.
+ */
+export interface HttpRouteHost {
+    get(path: string, handler: (ctx: unknown) => Response | Promise<Response>): unknown;
+}
+/** Resolves when the dependency is usable; throws or rejects when it is not. */
+export type ReadinessCheck = () => void | Promise<void>;
+export interface HealthOptions {
+    /** Route prefix (default `/health` → `/health`, `/health/live`, `/health/ready`). */
+    path?: string;
+    /** Named readiness checks; every one must pass for `ready` to answer 200. */
+    readiness?: Record<string, ReadinessCheck>;
+    /** Per-check budget in ms (default 2000) — a hung dependency must fail the probe, not hang it. */
+    timeoutMs?: number;
+    /** Log prefix for failed checks (default `health`). */
+    label?: string;
+    /**
+     * True once the host is shutting down: readiness then answers 503
+     * `draining` (liveness stays 200), so a load balancer stops routing new
+     * traffic while in-flight requests finish.
+     */
+    draining?: () => boolean;
+}
+export type HealthStatus = "up" | "down";
+/** The readiness body: the overall verdict plus one entry per check. */
+export interface HealthReport {
+    /** `draining` while the host shuts down, whatever the checks say. */
+    status: HealthStatus | "draining";
+    checks: Record<string, HealthStatus>;
+}
+/**
+ * Register `<path>/live`, `<path>/ready` and `<path>` (= ready). Readiness
+ * answers 200 with `{ status: "up", checks }` or 503 with `status: "down"`
+ * and the failing checks marked (`status: "draining"` once `draining()`
+ * holds); the checks run in parallel, each under
+ * `timeoutMs`. Register `installMetrics` first if probe traffic should show
+ * up in the HTTP metrics (hono only wraps routes registered after the
+ * middleware).
+ */
+export declare function installHealthEndpoints(server: HttpRouteHost, options?: HealthOptions): void;
+//# sourceMappingURL=health.d.ts.map

package/dist/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAA;CACpF;AAED,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEvD,MAAM,WAAW,aAAa;IAC5B,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IAC1C,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAA;CACzB;AAED,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,CAAA;AAExC,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,MAAM,EAAE,YAAY,GAAG,UAAU,CAAA;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CACrC;AA2CD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI,CAmB/F"}

package/dist/health.js

@@ -0,0 +1,74 @@
+/**
+ * HTTP health endpoints for composed-server hosts (server path only).
+ *
+ * Kubernetes-style split: `<path>/live` answers as soon as the process serves
+ * HTTP (only a wedged event loop fails it); `<path>/ready` additionally runs
+ * the host's readiness checks — the server's OWN dependencies (the profile/
+ * dashboard database), deliberately never the engines or Prometheus: those
+ * are upstreams whose outages the tools report as error results, and taking
+ * the server out of rotation for them would turn a visible error into a
+ * silent absence. The bare `<path>` aliases readiness for probes that know
+ * only one URL (Docker HEALTHCHECK, Fly, Compose `service_healthy`).
+ *
+ * Outside mcp-use's OAuth gate by construction: the bearer check is scoped
+ * to the MCP base path, so probes need no token.
+ */
+const jsonResponse = (status, body) => new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
+});
+async function withTimeout(check, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+        timer.unref();
+    });
+    try {
+        // `.then(check)` turns a synchronous throw into a rejection like any other.
+        await Promise.race([Promise.resolve().then(check), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function runReadinessChecks(checks, timeoutMs, label) {
+    const entries = await Promise.all(Object.entries(checks).map(async ([name, check]) => {
+        try {
+            await withTimeout(check, timeoutMs);
+            return [name, "up"];
+        }
+        catch (error) {
+            // The reason goes to the log, not the (unauthenticated) response body.
+            console.warn(`[${label}] readiness check "${name}" failed:`, error);
+            return [name, "down"];
+        }
+    }));
+    const status = entries.every(([, s]) => s === "up") ? "up" : "down";
+    return { status, checks: Object.fromEntries(entries) };
+}
+/**
+ * Register `<path>/live`, `<path>/ready` and `<path>` (= ready). Readiness
+ * answers 200 with `{ status: "up", checks }` or 503 with `status: "down"`
+ * and the failing checks marked (`status: "draining"` once `draining()`
+ * holds); the checks run in parallel, each under
+ * `timeoutMs`. Register `installMetrics` first if probe traffic should show
+ * up in the HTTP metrics (hono only wraps routes registered after the
+ * middleware).
+ */
+export function installHealthEndpoints(server, options = {}) {
+    const { path = "/health", readiness = {}, timeoutMs = 2000, label = "health", draining = () => false, } = options;
+    const live = () => jsonResponse(200, { status: "up" });
+    const ready = async () => {
+        if (draining())
+            return jsonResponse(503, { status: "draining", checks: {} });
+        const report = await runReadinessChecks(readiness, timeoutMs, label);
+        // Re-checked: a probe in flight when the drain began must not report up.
+        if (draining())
+            return jsonResponse(503, { ...report, status: "draining" });
+        return jsonResponse(report.status === "up" ? 200 : 503, report);
+    };
+    server.get(`${path}/live`, live);
+    server.get(`${path}/ready`, ready);
+    server.get(path, ready);
+}
+//# sourceMappingURL=health.js.map

package/dist/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"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"}

package/dist/health.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=health.test.d.ts.map

package/dist/health.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.test.d.ts","sourceRoot":"","sources":["../src/health.test.ts"],"names":[],"mappings":""}

package/dist/health.test.js

@@ -0,0 +1,140 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { installHealthEndpoints } from "./health.js";
+function install(options) {
+    const routes = new Map();
+    const server = {
+        get: (path, handler) => routes.set(path, handler),
+    };
+    installHealthEndpoints(server, options);
+    const call = async (path) => {
+        const handler = routes.get(path);
+        if (!handler)
+            throw new Error(`no route registered for ${path}`);
+        const res = await handler({});
+        return { status: res.status, body: (await res.json()), headers: res.headers };
+    };
+    return { routes, call };
+}
+describe("installHealthEndpoints", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("registers live, ready and the bare prefix", () => {
+        const { routes } = install();
+        expect([...routes.keys()].sort()).toEqual(["/health", "/health/live", "/health/ready"]);
+    });
+    it("honors a custom prefix", () => {
+        const { routes } = install({ path: "/healthz" });
+        expect([...routes.keys()].sort()).toEqual(["/healthz", "/healthz/live", "/healthz/ready"]);
+    });
+    it("live answers up without running any readiness check", async () => {
+        const check = vi.fn();
+        const { call } = install({ readiness: { db: check } });
+        const res = await call("/health/live");
+        expect(res.status).toBe(200);
+        expect(res.body).toEqual({ status: "up" });
+        expect(check).not.toHaveBeenCalled();
+    });
+    it("marks probe responses uncacheable JSON", async () => {
+        const { call } = install();
+        const res = await call("/health/live");
+        expect(res.headers.get("cache-control")).toBe("no-store");
+        expect(res.headers.get("content-type")).toBe("application/json; charset=utf-8");
+    });
+    it("ready is up with no checks configured", async () => {
+        const { call } = install();
+        const res = await call("/health/ready");
+        expect(res.status).toBe(200);
+        expect(res.body).toEqual({ status: "up", checks: {} });
+    });
+    it("ready is up when every check passes (sync and async)", async () => {
+        const { call } = install({ readiness: { db: async () => { }, disk: () => { } } });
+        const res = await call("/health/ready");
+        expect(res.status).toBe(200);
+        expect(res.body).toEqual({ status: "up", checks: { db: "up", disk: "up" } });
+    });
+    it("ready is 503 naming the failing check, and logs the reason instead of exposing it", async () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        const { call } = install({
+            label: "test-app",
+            readiness: {
+                db: async () => {
+                    throw new Error("connect ECONNREFUSED");
+                },
+                disk: () => { },
+            },
+        });
+        const res = await call("/health/ready");
+        expect(res.status).toBe(503);
+        expect(res.body).toEqual({ status: "down", checks: { db: "down", disk: "up" } });
+        expect(JSON.stringify(res.body)).not.toContain("ECONNREFUSED");
+        expect(warn).toHaveBeenCalledOnce();
+        expect(warn.mock.calls[0][0]).toBe('[test-app] readiness check "db" failed:');
+        expect(String(warn.mock.calls[0][1])).toContain("ECONNREFUSED");
+    });
+    it("treats a synchronous throw like a rejection", async () => {
+        vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        const { call } = install({
+            readiness: {
+                boom: () => {
+                    throw new Error("sync");
+                },
+            },
+        });
+        const res = await call("/health/ready");
+        expect(res.status).toBe(503);
+        expect(res.body).toEqual({ status: "down", checks: { boom: "down" } });
+    });
+    it("fails a check that exceeds the timeout instead of hanging the probe", async () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        const { call } = install({
+            timeoutMs: 10,
+            readiness: { hung: () => new Promise(() => { }) },
+        });
+        const res = await call("/health/ready");
+        expect(res.status).toBe(503);
+        expect(res.body).toEqual({ status: "down", checks: { hung: "down" } });
+        expect(String(warn.mock.calls[0][1])).toContain("timed out after 10ms");
+    });
+    it("answers 503 draining once the host drains — without running the checks — while live stays up", async () => {
+        const check = vi.fn();
+        let draining = false;
+        const { call } = install({ readiness: { db: check }, draining: () => draining });
+        expect((await call("/health/ready")).status).toBe(200);
+        draining = true;
+        const ready = await call("/health/ready");
+        expect(ready.status).toBe(503);
+        expect(ready.body).toEqual({ status: "draining", checks: {} });
+        expect((await call("/health")).status).toBe(503);
+        expect(check).toHaveBeenCalledTimes(1);
+        expect((await call("/health/live")).status).toBe(200);
+    });
+    it("reports draining for a probe that was in flight when the drain began", async () => {
+        let draining = false;
+        const { call } = install({
+            readiness: {
+                db: () => {
+                    draining = true;
+                },
+            },
+            draining: () => draining,
+        });
+        const res = await call("/health/ready");
+        expect(res.status).toBe(503);
+        expect(res.body).toEqual({ status: "draining", checks: { db: "up" } });
+    });
+    it("the bare prefix aliases readiness", async () => {
+        vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        const { call } = install({
+            readiness: {
+                db: async () => {
+                    throw new Error("down");
+                },
+            },
+        });
+        const res = await call("/health");
+        expect(res.status).toBe(503);
+        expect(res.body).toEqual({ status: "down", checks: { db: "down" } });
+    });
+});
+//# sourceMappingURL=health.test.js.map

package/dist/health.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.test.js","sourceRoot":"","sources":["../src/health.test.ts"],"names":[],"mappings":"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"}