@miragon/pulse-widget-shell 0.0.0-stage → 0.21.0

package/dist/oauth-env.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `MCP_OAUTH` → the OAuth provider a composition root installs. Every root —
+ * the stock server, the composed-server template, a customer fork — wires it
+ * the SAME way:
+ *
+ * ```ts
+ * const oauth = oauthFromEnv({ env, label })   // boot-time parse + warning
+ * createComposedServer({ …, oauth })           // installs it, decides toolsets
+ * const APP_ENV_VARS = [...OAUTH_ENV_VARS, …]  // known to the typo warner
+ * ```
+ *
+ * With a provider the server is an OAuth resource server: mcp-use validates
+ * the bearer token on every `/mcp` request (401 + `WWW-Authenticate`
+ * otherwise) against the IdP's JWKS, checks the RFC 8707 resource audience
+ * (the server's canonical MCP URL, `MCP_URL`) and serves the `.well-known`
+ * discovery metadata; the server never mints tokens. It is also the ONLY
+ * caller-identity source: per-user settings and dashboards exist only with it
+ * (`resolveProfileKey`), and an installed provider raises every module's
+ * no-suffix toolset from the read-only floor to its standard set. A gateway
+ * that terminates auth in front of the server is invisible here — identity
+ * reaches the server only through this OAuth.
+ *
+ * Server path only (`@miragon/pulse-widget-shell/server`).
+ */
+import type { OAuthProvider } from "mcp-use/oauth";
+/** The env vars {@link oauthFromEnv} reads — spread them into the root's known-var list. */
+export declare const OAUTH_ENV_VARS: readonly ["MCP_OAUTH"];
+export interface OAuthFromEnvOptions {
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Log prefix, e.g. `pulse`. */
+    label?: string;
+}
+/**
+ * Builds the mcp-use OAuth provider from `MCP_OAUTH` (`keycloak` or `auth0`).
+ * Unset or blank → `undefined` plus ONE boot warning naming what that means:
+ * an unauthenticated endpoint, read-only defaults, and no saved settings.
+ * Invalid JSON, schema violations and stray `MCP_USE_OAUTH_*` fallbacks throw:
+ * a deployment that asked for auth must never silently come up without it.
+ */
+export declare function oauthFromEnv(options?: OAuthFromEnvOptions): OAuthProvider<unknown> | undefined;
+//# sourceMappingURL=oauth-env.d.ts.map

package/dist/oauth-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-env.d.ts","sourceRoot":"","sources":["../src/oauth-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAKlD,4FAA4F;AAC5F,eAAO,MAAM,cAAc,wBAAyB,CAAA;AA2BpD,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAaD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,GAAE,mBAAwB,GAChC,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,CA2CpC"}

package/dist/oauth-env.js

@@ -0,0 +1,78 @@
+import { oauthAuth0Provider } from "mcp-use/oauth/auth0";
+import { oauthKeycloakProvider } from "mcp-use/oauth/keycloak";
+import { z } from "zod";
+/** The env vars {@link oauthFromEnv} reads — spread them into the root's known-var list. */
+export const OAUTH_ENV_VARS = ["MCP_OAUTH"];
+const keycloakSchema = z.strictObject({
+    provider: z.literal("keycloak"),
+    serverUrl: z.url(),
+    realm: z.string().min(1),
+});
+const auth0Schema = z.strictObject({
+    provider: z.literal("auth0"),
+    // Bare hostname, no scheme/path — the form mcp-use's provider builds the
+    // issuer from; a scheme-prefixed value would only 401 at the first call.
+    domain: z
+        .string()
+        .min(1)
+        .refine((d) => !d.includes("://") && !d.includes("/"), {
+        message: 'domain must be a bare hostname, e.g. "tenant.eu.auth0.com" (no scheme, no path)',
+    }),
+});
+/**
+ * Strict on purpose: a key the server does not honor (an `audience`, a
+ * client secret) fails the boot instead of being dropped silently — a
+ * deployment that asked for a check must never come up without it.
+ */
+const oauthConfigSchema = z.discriminatedUnion("provider", [keycloakSchema, auth0Schema]);
+/**
+ * The provider in the `unknown` user slot `createComposedServer` takes. Since
+ * mcp-use 2.7 the provider's optional `setup(host)` hook takes the user type
+ * in parameter position, which makes `OAuthProvider<TUser>` invariant — a
+ * Keycloak- or Auth0-typed provider no longer widens on its own. Sound: every
+ * user the host hands out went through the provider's own `mapAuthInfo`, and
+ * every consumer reads it structurally (`resolveCaller`).
+ */
+const withUnknownUser = (provider) => provider;
+/**
+ * Builds the mcp-use OAuth provider from `MCP_OAUTH` (`keycloak` or `auth0`).
+ * Unset or blank → `undefined` plus ONE boot warning naming what that means:
+ * an unauthenticated endpoint, read-only defaults, and no saved settings.
+ * Invalid JSON, schema violations and stray `MCP_USE_OAUTH_*` fallbacks throw:
+ * a deployment that asked for auth must never silently come up without it.
+ */
+export function oauthFromEnv(options = {}) {
+    const { env = process.env, label = "oauth" } = options;
+    const raw = env.MCP_OAUTH?.trim();
+    if (!raw) {
+        console.warn(`[${label}] MCP_OAUTH is unset — there is no caller identity: modules without an explicit toolset run read-only, and user settings cannot be saved. Set MCP_OAUTH, or widen with MCP_ACTIVE_MODULES=<module>:<toolset> (anyone who reaches this port gets that surface).`);
+        return undefined;
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`MCP_OAUTH is not valid JSON. Expected e.g. {"provider":"keycloak","serverUrl":"https://kc.example.com","realm":"my-realm"}`);
+    }
+    const parsed = oauthConfigSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new Error(`MCP_OAUTH is invalid:\n${z.prettifyError(parsed.error)}`);
+    }
+    // mcp-use's provider factories silently fall back to their own
+    // MCP_USE_OAUTH_* variables for omitted fields — read from `process.env`,
+    // whatever `env` this call was handed. MCP_OAUTH is the single config
+    // surface: fail fast on strays.
+    const strays = Object.keys(process.env).filter((k) => k.startsWith("MCP_USE_OAUTH_"));
+    if (strays.length > 0) {
+        throw new Error(`MCP_OAUTH is the single OAuth config surface — unset ${strays.join(", ")} (mcp-use would silently use them as fallbacks for omitted fields).`);
+    }
+    const config = parsed.data;
+    switch (config.provider) {
+        case "keycloak":
+            return withUnknownUser(oauthKeycloakProvider({ serverUrl: config.serverUrl, realm: config.realm }));
+        case "auth0":
+            return withUnknownUser(oauthAuth0Provider({ domain: config.domain }));
+    }
+}
+//# sourceMappingURL=oauth-env.js.map

package/dist/oauth-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-env.js","sourceRoot":"","sources":["../src/oauth-env.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,4FAA4F;AAC5F,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,WAAW,CAAU,CAAA;AAEpD,MAAM,cAAc,GAAG,CAAC,CAAC,YAAY,CAAC;IACpC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IAC/B,SAAS,EAAE,CAAC,CAAC,GAAG,EAAE;IAClB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACzB,CAAC,CAAA;AAEF,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC;IACjC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC5B,yEAAyE;IACzE,yEAAyE;IACzE,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;QACrD,OAAO,EAAE,iFAAiF;KAC3F,CAAC;CACL,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,CAAC,CAAC,kBAAkB,CAAC,UAAU,EAAE,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAA;AASzF;;;;;;;GAOG;AACH,MAAM,eAAe,GAAG,CAAQ,QAA8B,EAA0B,EAAE,CACxF,QAA6C,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,UAA+B,EAAE;IAEjC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,OAAO,EAAE,GAAG,OAAO,CAAA;IACtD,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,CAAA;IACjC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,CAAC,IAAI,CACV,IAAI,KAAK,gQAAgQ,CAC1Q,CAAA;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,IAAI,IAAa,CAAA;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,4HAA4H,CAC7H,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IAChD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAC5E,CAAC;IAED,+DAA+D;IAC/D,0EAA0E;IAC1E,sEAAsE;IACtE,gCAAgC;IAChC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAA;IACrF,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,wDAAwD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,qEAAqE,CAC/I,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAA;IAC1B,QAAQ,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,KAAK,UAAU;YACb,OAAO,eAAe,CACpB,qBAAqB,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAC5E,CAAA;QACH,KAAK,OAAO;YACV,OAAO,eAAe,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IACzE,CAAC;AACH,CAAC"}

package/dist/oauth-env.test.d.ts

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

package/dist/oauth-env.test.d.ts.map

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

package/dist/oauth-env.test.js

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { OAUTH_ENV_VARS, oauthFromEnv } from "./oauth-env.js";
+const KEYCLOAK = { provider: "keycloak", serverUrl: "https://kc.example.com", realm: "platform" };
+/** `oauthFromEnv` over a given `MCP_OAUTH` value (an object is JSON-encoded). */
+const fromEnv = (raw) => oauthFromEnv({
+    env: { MCP_OAUTH: typeof raw === "object" ? JSON.stringify(raw) : raw },
+    label: "test-root",
+});
+afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+});
+describe("oauthFromEnv", () => {
+    it("names the one env var it reads", () => {
+        expect(OAUTH_ENV_VARS).toEqual(["MCP_OAUTH"]);
+    });
+    it("installs nothing when MCP_OAUTH is unset or blank — and says what that means, once", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        for (const raw of [undefined, "", "   "])
+            expect(fromEnv(raw)).toBeUndefined();
+        expect(warn).toHaveBeenCalledTimes(3);
+        expect(warn.mock.calls[0][0]).toMatch(/^\[test-root\] MCP_OAUTH is unset — there is no caller identity/);
+        expect(warn.mock.calls[0][0]).toContain("user settings cannot be saved");
+    });
+    it("reads process.env by default", () => {
+        vi.spyOn(console, "warn").mockImplementation(() => { });
+        vi.stubEnv("MCP_OAUTH", JSON.stringify(KEYCLOAK));
+        expect(oauthFromEnv()?.oauthMetadata.issuer).toBe("https://kc.example.com/realms/platform");
+    });
+    // Exact assertions on purpose: the Keycloak factory interpolates
+    // serverUrl/realm, so swapped arguments would still construct — only exact
+    // endpoint values catch that.
+    it("builds a Keycloak provider with the exact realm endpoints", () => {
+        const provider = fromEnv(KEYCLOAK);
+        expect(provider?.oauthMetadata.issuer).toBe("https://kc.example.com/realms/platform");
+        expect(provider?.oauthMetadata.authorization_endpoint).toBe("https://kc.example.com/realms/platform/protocol/openid-connect/auth");
+        expect(provider?.oauthMetadata.token_endpoint).toBe("https://kc.example.com/realms/platform/protocol/openid-connect/token");
+    });
+    it("maps the token subject as the caller id (`user.id`, the spelling resolveCaller reads)", () => {
+        const extra = fromEnv(KEYCLOAK).mapAuthInfo({
+            token: "t",
+            clientId: "c",
+            scopes: [],
+            extra: { payload: { sub: "user-123", realm_access: { roles: [] } } },
+        });
+        expect(extra.user).toMatchObject({ id: "user-123" });
+        expect(extra.user).not.toHaveProperty("userId");
+    });
+    it("builds an Auth0 provider from the bare tenant domain", () => {
+        const provider = fromEnv({ provider: "auth0", domain: "tenant.auth0.com" });
+        expect(provider?.oauthMetadata.issuer).toBe("https://tenant.auth0.com/");
+        expect(provider?.oauthMetadata.authorization_endpoint).toBe("https://tenant.auth0.com/authorize");
+        expect(provider?.oauthMetadata.token_endpoint).toBe("https://tenant.auth0.com/oauth/token");
+    });
+    it("rejects a scheme-prefixed auth0 domain at boot instead of 401ing later", () => {
+        expect(() => fromEnv({ provider: "auth0", domain: "https://tenant.auth0.com" })).toThrow(/bare hostname/);
+        expect(() => fromEnv({ provider: "auth0", domain: "tenant.auth0.com/x" })).toThrow(/bare hostname/);
+    });
+    it("rejects invalid JSON with an actionable message", () => {
+        expect(() => fromEnv("keycloak")).toThrow(/MCP_OAUTH is not valid JSON/);
+    });
+    it("rejects unknown providers, missing fields and keys it would not honor", () => {
+        expect(() => fromEnv({ provider: "okta" })).toThrow(/MCP_OAUTH is invalid/);
+        expect(() => fromEnv({ provider: "oidc", issuer: "https://idp.example.com" })).toThrow(/MCP_OAUTH is invalid/);
+        expect(() => fromEnv({ provider: "keycloak", serverUrl: "https://kc.example.com" })).toThrow(/realm/);
+        expect(() => fromEnv({ ...KEYCLOAK, serverUrl: "not a url" })).toThrow(/serverUrl/);
+        expect(() => fromEnv({ ...KEYCLOAK, realm: "" })).toThrow(/realm/);
+        // An audience mcp-use 2 cannot check must fail loudly, not be dropped.
+        expect(() => fromEnv({ ...KEYCLOAK, audience: "https://mcp.example.com/mcp" })).toThrow(/audience/);
+    });
+    it("fails fast when stray MCP_USE_OAUTH_* env vars could silently alter the config", () => {
+        vi.stubEnv("MCP_USE_OAUTH_KEYCLOAK_AUDIENCE", "https://other-api.example.com");
+        expect(() => fromEnv(KEYCLOAK)).toThrow(/unset MCP_USE_OAUTH_KEYCLOAK_AUDIENCE/);
+    });
+});
+//# sourceMappingURL=oauth-env.test.js.map

package/dist/oauth-env.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-env.test.js","sourceRoot":"","sources":["../src/oauth-env.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE7D,MAAM,QAAQ,GAAG,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,wBAAwB,EAAE,KAAK,EAAE,UAAU,EAAE,CAAA;AAEjG,iFAAiF;AACjF,MAAM,OAAO,GAAG,CAAC,GAAgC,EAAE,EAAE,CACnD,YAAY,CAAC;IACX,GAAG,EAAE,EAAE,SAAS,EAAE,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE;IACvE,KAAK,EAAE,WAAW;CACnB,CAAC,CAAA;AAEJ,SAAS,CAAC,GAAG,EAAE;IACb,EAAE,CAAC,aAAa,EAAE,CAAA;IAClB,EAAE,CAAC,eAAe,EAAE,CAAA;AACtB,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,oFAAoF,EAAE,GAAG,EAAE;QAC5F,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACnE,KAAK,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,EAAE,EAAE,KAAK,CAAC;YAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;QAC9E,MAAM,CAAC,IAAI,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAA;QACrC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CACnC,iEAAiE,CAClE,CAAA;QACD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,+BAA+B,CAAC,CAAA;IAC1E,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACtD,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAA;QACjD,MAAM,CAAC,YAAY,EAAE,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAA;IAC7F,CAAC,CAAC,CAAA;IAEF,iEAAiE;IACjE,2EAA2E;IAC3E,8BAA8B;IAC9B,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;QAClC,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAA;QACrF,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC,IAAI,CACzD,qEAAqE,CACtE,CAAA;QACD,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC,IAAI,CACjD,sEAAsE,CACvE,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,uFAAuF,EAAE,GAAG,EAAE;QAC/F,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAE,CAAC,WAAW,CAAC;YAC3C,KAAK,EAAE,GAAG;YACV,QAAQ,EAAE,GAAG;YACb,MAAM,EAAE,EAAE;YACV,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE;SACrE,CAAC,CAAA;QACF,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAA;QACpD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAA;IACjD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,QAAQ,GAAG,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAA;QAC3E,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;QACxE,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC,IAAI,CACzD,oCAAoC,CACrC,CAAA;QACD,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAA;IAC7F,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC,CAAC,CAAC,OAAO,CACtF,eAAe,CAChB,CAAA;QACD,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,OAAO,CAChF,eAAe,CAChB,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,6BAA6B,CAAC,CAAA;IAC1E,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,uEAAuE,EAAE,GAAG,EAAE;QAC/E,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAA;QAC3E,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC,CAAC,OAAO,CACpF,sBAAsB,CACvB,CAAA;QACD,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,wBAAwB,EAAE,CAAC,CAAC,CAAC,OAAO,CAC1F,OAAO,CACR,CAAA;QACD,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;QACnF,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAClE,uEAAuE;QACvE,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,EAAE,QAAQ,EAAE,6BAA6B,EAAE,CAAC,CAAC,CAAC,OAAO,CACrF,UAAU,CACX,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gFAAgF,EAAE,GAAG,EAAE;QACxF,EAAE,CAAC,OAAO,CAAC,iCAAiC,EAAE,+BAA+B,CAAC,CAAA;QAC9E,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,uCAAuC,CAAC,CAAA;IAClF,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/postgres.d.ts

@@ -0,0 +1,59 @@
+import type postgres from "postgres";
+import type { ReadinessCheck } from "./health.js";
+/**
+ * The Postgres infrastructure shared by every store in this package: the one
+ * place a postgres.js client is constructed, plus the migration runner that
+ * executes the DDL each store exports (`PROFILE_STORE_MIGRATIONS`,
+ * `DASHBOARD_STORE_MIGRATIONS`). A composed server that persists to Postgres
+ * needs both — exporting the migration arrays without the runner would force
+ * every consumer to copy it.
+ */
+/**
+ * Connections are lazy (opened on first query), but a root that persists to
+ * Postgres runs `runMigrations` before it listens (the app's `initRuntime`),
+ * so an unreachable database fails the
+ * boot once the 10 s `connect_timeout` runs out (under a restart policy: a
+ * restart loop until the database answers). After boot, reconnects after a
+ * scale-to-zero wake need no extra handling.
+ *
+ * The driver is loaded through a DYNAMIC import and every other reference in
+ * this package is `import type` — deliberately, and the reason this function
+ * is async: `postgres` is an OPTIONAL peer dependency, but `/server`
+ * re-exports this module, so a static import would execute on every consumer's
+ * boot and crash the ones that persist to disk or memory (the composed-server
+ * template installs no `postgres`) with ERR_MODULE_NOT_FOUND. Never "simplify"
+ * it back to a top-level import.
+ */
+export declare function createSql(databaseUrl: string): Promise<postgres.Sql>;
+/**
+ * The `/health/ready` check for a postgres.js client: one `SELECT 1` round
+ * trip through the pool, so a database that goes away after boot turns the
+ * server not ready instead of failing the next save. Lives next to `createSql` so
+ * every composition root that persists to Postgres wires the same probe.
+ */
+export declare function postgresReadinessCheck(sql: postgres.Sql): ReadinessCheck;
+/**
+ * One named, append-only migration. Statements are plain SQL strings compiled
+ * into the bundle — .sql files would not survive a `pnpm deploy` + dist-copy
+ * packaging. Store owners export their own migrations; the composition root
+ * concatenates them in a fixed order.
+ *
+ * `name` is the identity recorded in `schema_migrations`, so it is a permanent
+ * key, not a label: renaming one re-runs it against every existing database
+ * (harmless only because the shipped DDL is `IF NOT EXISTS`), and reusing a
+ * name for different DDL silently skips it. Numeric prefixes are ordering
+ * hints for readers only — the array order decides.
+ */
+export interface Migration {
+    name: string;
+    statements: readonly string[];
+}
+/**
+ * Apply all not-yet-applied migrations in order, tracked by name in
+ * `schema_migrations`. Runs as a single transaction under
+ * `pg_advisory_xact_lock`, so two instances booting against the same database
+ * cannot interleave DDL; the lock releases with the commit. Returns the names
+ * that were newly applied (for boot logging).
+ */
+export declare function runMigrations(sql: postgres.Sql, migrations: readonly Migration[]): Promise<string[]>;
+//# sourceMappingURL=postgres.d.ts.map

package/dist/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAA;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAW1E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,GAAG,cAAc,CAIxE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B;AAMD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,QAAQ,CAAC,GAAG,EACjB,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBnB"}

package/dist/postgres.js

@@ -0,0 +1,80 @@
+/**
+ * The Postgres infrastructure shared by every store in this package: the one
+ * place a postgres.js client is constructed, plus the migration runner that
+ * executes the DDL each store exports (`PROFILE_STORE_MIGRATIONS`,
+ * `DASHBOARD_STORE_MIGRATIONS`). A composed server that persists to Postgres
+ * needs both — exporting the migration arrays without the runner would force
+ * every consumer to copy it.
+ */
+/**
+ * Connections are lazy (opened on first query), but a root that persists to
+ * Postgres runs `runMigrations` before it listens (the app's `initRuntime`),
+ * so an unreachable database fails the
+ * boot once the 10 s `connect_timeout` runs out (under a restart policy: a
+ * restart loop until the database answers). After boot, reconnects after a
+ * scale-to-zero wake need no extra handling.
+ *
+ * The driver is loaded through a DYNAMIC import and every other reference in
+ * this package is `import type` — deliberately, and the reason this function
+ * is async: `postgres` is an OPTIONAL peer dependency, but `/server`
+ * re-exports this module, so a static import would execute on every consumer's
+ * boot and crash the ones that persist to disk or memory (the composed-server
+ * template installs no `postgres`) with ERR_MODULE_NOT_FOUND. Never "simplify"
+ * it back to a top-level import.
+ */
+export async function createSql(databaseUrl) {
+    const { default: postgres } = await import("postgres");
+    return postgres(databaseUrl, {
+        // A handful of connections is plenty: every store call is a single short
+        // statement or one SELECT…FOR UPDATE transaction.
+        max: 5,
+        idle_timeout: 30,
+        connect_timeout: 10,
+        // NOTICEs (e.g. from CREATE TABLE IF NOT EXISTS) are noise on the server log.
+        onnotice: () => { },
+    });
+}
+/**
+ * The `/health/ready` check for a postgres.js client: one `SELECT 1` round
+ * trip through the pool, so a database that goes away after boot turns the
+ * server not ready instead of failing the next save. Lives next to `createSql` so
+ * every composition root that persists to Postgres wires the same probe.
+ */
+export function postgresReadinessCheck(sql) {
+    return async () => {
+        await sql `SELECT 1`;
+    };
+}
+// Arbitrary but stable app-wide key ("mira" in hex) for the boot-time advisory
+// lock — it serializes concurrently booting instances, not tables.
+const MIGRATION_LOCK_KEY = 0x6d697261;
+/**
+ * Apply all not-yet-applied migrations in order, tracked by name in
+ * `schema_migrations`. Runs as a single transaction under
+ * `pg_advisory_xact_lock`, so two instances booting against the same database
+ * cannot interleave DDL; the lock releases with the commit. Returns the names
+ * that were newly applied (for boot logging).
+ */
+export async function runMigrations(sql, migrations) {
+    return await sql.begin(async (tx) => {
+        await tx `SELECT pg_advisory_xact_lock(${MIGRATION_LOCK_KEY})`;
+        await tx.unsafe(`CREATE TABLE IF NOT EXISTS schema_migrations (
+        name TEXT PRIMARY KEY,
+        applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      )`);
+        const appliedRows = await tx `SELECT name FROM schema_migrations`;
+        const applied = new Set(appliedRows.map((row) => row.name));
+        const newlyApplied = [];
+        for (const migration of migrations) {
+            if (applied.has(migration.name))
+                continue;
+            for (const statement of migration.statements) {
+                await tx.unsafe(statement);
+            }
+            await tx `INSERT INTO schema_migrations (name) VALUES (${migration.name})`;
+            newlyApplied.push(migration.name);
+        }
+        return newlyApplied;
+    });
+}
+//# sourceMappingURL=postgres.js.map

package/dist/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,WAAmB;IACjD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAA;IACtD,OAAO,QAAQ,CAAC,WAAW,EAAE;QAC3B,yEAAyE;QACzE,kDAAkD;QAClD,GAAG,EAAE,CAAC;QACN,YAAY,EAAE,EAAE;QAChB,eAAe,EAAE,EAAE;QACnB,8EAA8E;QAC9E,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC;KACnB,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAiB;IACtD,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,GAAG,CAAA,UAAU,CAAA;IACrB,CAAC,CAAA;AACH,CAAC;AAmBD,+EAA+E;AAC/E,mEAAmE;AACnE,MAAM,kBAAkB,GAAG,UAAU,CAAA;AAErC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAiB,EACjB,UAAgC;IAEhC,OAAO,MAAM,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;QAClC,MAAM,EAAE,CAAA,gCAAgC,kBAAkB,GAAG,CAAA;QAC7D,MAAM,EAAE,CAAC,MAAM,CACb;;;QAGE,CACH,CAAA;QACD,MAAM,WAAW,GAAG,MAAM,EAAE,CAAoB,oCAAoC,CAAA;QACpF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;QAC3D,MAAM,YAAY,GAAa,EAAE,CAAA;QACjC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC;gBAAE,SAAQ;YACzC,KAAK,MAAM,SAAS,IAAI,SAAS,CAAC,UAAU,EAAE,CAAC;gBAC7C,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;YAC5B,CAAC;YACD,MAAM,EAAE,CAAA,gDAAgD,SAAS,CAAC,IAAI,GAAG,CAAA;YACzE,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QACnC,CAAC;QACD,OAAO,YAAY,CAAA;IACrB,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/profile-advisory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Advisory profile reads — for paths that only PREFER the profile (the
+ * summary locale, a saved default engine) and must keep working without it.
+ *
+ * With `DATABASE_URL` the profile store is a network call, and a preferences
+ * outage must never fail a tool whose data comes from the engine or
+ * Prometheus — nor put the driver's error text (internal host:port) into a
+ * tool result. Save paths and the settings views stay strict: a write must
+ * fail visibly.
+ */
+/**
+ * Read `key`'s record, degrading every failure to "no record": no key, or a
+ * store that throws (logged once per outage with a sanitized line, and once
+ * when it recovers). Never throws.
+ */
+export declare function readProfileAdvisory<T>(store: {
+    get(key: string): Promise<T | undefined>;
+}, key: string | undefined): Promise<T | undefined>;
+//# sourceMappingURL=profile-advisory.d.ts.map

package/dist/profile-advisory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-advisory.d.ts","sourceRoot":"","sources":["../src/profile-advisory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiBH;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,KAAK,EAAE;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;CAAE,EACnD,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAiBxB"}

package/dist/profile-advisory.js

@@ -0,0 +1,48 @@
+/**
+ * Advisory profile reads — for paths that only PREFER the profile (the
+ * summary locale, a saved default engine) and must keep working without it.
+ *
+ * With `DATABASE_URL` the profile store is a network call, and a preferences
+ * outage must never fail a tool whose data comes from the engine or
+ * Prometheus — nor put the driver's error text (internal host:port) into a
+ * tool result. Save paths and the settings views stay strict: a write must
+ * fail visibly.
+ */
+/** Stores currently failing, so an outage logs once instead of once per call. */
+const failingStores = new WeakSet();
+/**
+ * The error's class and code only — never its message: driver messages carry
+ * the database host:port (and can carry user names), and this line must be
+ * safe for any log sink. The readiness probe logs the full error for
+ * operators.
+ */
+function describeStoreError(err) {
+    if (!(err instanceof Error))
+        return typeof err;
+    const code = err.code;
+    return typeof code === "string" || typeof code === "number" ? `${err.name} ${code}` : err.name;
+}
+/**
+ * Read `key`'s record, degrading every failure to "no record": no key, or a
+ * store that throws (logged once per outage with a sanitized line, and once
+ * when it recovers). Never throws.
+ */
+export async function readProfileAdvisory(store, key) {
+    if (key === undefined)
+        return undefined;
+    try {
+        const record = await store.get(key);
+        if (failingStores.delete(store)) {
+            console.warn("[profile-store] reachable again — saved preferences apply again");
+        }
+        return record;
+    }
+    catch (err) {
+        if (!failingStores.has(store)) {
+            failingStores.add(store);
+            console.warn(`[profile-store] read failed (${describeStoreError(err)}) — preference lookups fall back to defaults until the store recovers`);
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=profile-advisory.js.map

package/dist/profile-advisory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-advisory.js","sourceRoot":"","sources":["../src/profile-advisory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iFAAiF;AACjF,MAAM,aAAa,GAAG,IAAI,OAAO,EAAU,CAAA;AAE3C;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,GAAY;IACtC,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,OAAO,GAAG,CAAA;IAC9C,MAAM,IAAI,GAAI,GAA0B,CAAC,IAAI,CAAA;IAC7C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAA;AAChG,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAmD,EACnD,GAAuB;IAEvB,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAA;QACjF,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YACxB,OAAO,CAAC,IAAI,CACV,gCAAgC,kBAAkB,CAAC,GAAG,CAAC,uEAAuE,CAC/H,CAAA;QACH,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC"}

package/dist/profile-advisory.test.d.ts

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

package/dist/profile-advisory.test.d.ts.map

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

package/dist/profile-advisory.test.js

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { readProfileAdvisory } from "./profile-advisory.js";
+/** A driver-shaped outage: the message carries the database host:port. */
+function driverError() {
+    return Object.assign(new Error("connect ECONNREFUSED 10.1.2.3:5432"), { code: "ECONNREFUSED" });
+}
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("readProfileAdvisory", () => {
+    it("returns the stored record", async () => {
+        const store = { get: (key) => Promise.resolve({ key }) };
+        expect(await readProfileAdvisory(store, "user-1")).toEqual({ key: "user-1" });
+    });
+    it("skips the store entirely without a key", async () => {
+        const get = vi.fn(() => Promise.resolve({}));
+        expect(await readProfileAdvisory({ get }, undefined)).toBeUndefined();
+        expect(get).not.toHaveBeenCalled();
+    });
+    it("degrades an outage to 'no record' and logs ONE sanitized line per outage", async () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        let down = true;
+        const store = {
+            get: () => (down ? Promise.reject(driverError()) : Promise.resolve({ language: "de" })),
+        };
+        expect(await readProfileAdvisory(store, "user-1")).toBeUndefined();
+        expect(await readProfileAdvisory(store, "user-1")).toBeUndefined();
+        expect(warn).toHaveBeenCalledTimes(1);
+        const line = String(warn.mock.calls[0][0]);
+        expect(line).toContain("Error ECONNREFUSED");
+        expect(line).not.toMatch(/10\.1\.2\.3|5432/);
+        // Recovery is announced once, and the next outage logs again.
+        down = false;
+        expect(await readProfileAdvisory(store, "user-1")).toEqual({ language: "de" });
+        expect(await readProfileAdvisory(store, "user-1")).toEqual({ language: "de" });
+        expect(warn).toHaveBeenCalledTimes(2);
+        expect(String(warn.mock.calls[1][0])).toContain("reachable again");
+        down = true;
+        await readProfileAdvisory(store, "user-1");
+        expect(warn).toHaveBeenCalledTimes(3);
+    });
+    it("names only the error class (or type) when there is no code", async () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        await readProfileAdvisory({ get: () => Promise.reject(new TypeError("at 10.1.2.3")) }, "k");
+        // A driver rejecting with a bare string (typed as Error only to satisfy the lint).
+        const bare = "10.1.2.3:5432";
+        await readProfileAdvisory({ get: () => Promise.reject(bare) }, "k");
+        expect(String(warn.mock.calls[0][0])).toContain("(TypeError)");
+        expect(String(warn.mock.calls[1][0])).toContain("(string)");
+        expect(warn.mock.calls.flat().join(" ")).not.toContain("10.1.2.3");
+    });
+});
+//# sourceMappingURL=profile-advisory.test.js.map

package/dist/profile-advisory.test.js.map

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

package/dist/profile-constants.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Enumerated profile option sets, kept in a zod-free module so widget code can
+ * import the runtime arrays (for select/checkbox option lists) without pulling
+ * zod into the UI bundle. `profile-record.ts` builds its `z.enum(...)`s from
+ * these, so the two never drift. Exported from BOTH `/server` and `/widgets`.
+ */
+/** UI + summary languages. Extend deliberately — every locale needs a catalog. */
+export declare const LOCALES: readonly ["en", "de"];
+export type Locale = (typeof LOCALES)[number];
+/**
+ * Language preference: an explicit locale, or `system` — follow the host's
+ * locale (`hostContext.locale`, normalized to a supported language), then
+ * English. Server-side summaries have no host locale, so `system` reads as
+ * English there (`explicitLocale(...) ?? "en"`).
+ */
+export declare const LANGUAGES: readonly ["system", "en", "de"];
+export type LanguagePref = (typeof LANGUAGES)[number];
+/**
+ * The supported locale a language preference names explicitly — `undefined`
+ * for `system`, a missing value, or anything this build ships no catalog for.
+ * Loose input on purpose: profile feeds arrive untyped.
+ */
+export declare function explicitLocale(language: string | undefined): Locale | undefined;
+/**
+ * Bumped when the persisted profile shape changes in a migration-relevant way.
+ * Every bump needs a matching entry in `PROFILE_MIGRATIONS`
+ * (`profile-migrations.ts`) so stored records upgrade on read instead of
+ * losing their preferences.
+ *
+ * v3 is the migration baseline (`PROFILE_MIGRATION_BASELINE`): a
+ * connector-free record — language, `modules.<module>` slices + metadata —
+ * owned by this core package. The theme preference it once carried is gone
+ * (widgets follow the host's theme); a stored `theme` key stays inert in the
+ * raw document, so it needed no migration.
+ */
+export declare const PROFILE_SCHEMA_VERSION = 3;
+//# sourceMappingURL=profile-constants.d.ts.map

package/dist/profile-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-constants.d.ts","sourceRoot":"","sources":["../src/profile-constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kFAAkF;AAClF,eAAO,MAAM,OAAO,uBAAwB,CAAA;AAC5C,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,SAAS,iCAAkC,CAAA;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAE/E;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA"}

package/dist/profile-constants.js

@@ -0,0 +1,37 @@
+/**
+ * Enumerated profile option sets, kept in a zod-free module so widget code can
+ * import the runtime arrays (for select/checkbox option lists) without pulling
+ * zod into the UI bundle. `profile-record.ts` builds its `z.enum(...)`s from
+ * these, so the two never drift. Exported from BOTH `/server` and `/widgets`.
+ */
+/** UI + summary languages. Extend deliberately — every locale needs a catalog. */
+export const LOCALES = ["en", "de"];
+/**
+ * Language preference: an explicit locale, or `system` — follow the host's
+ * locale (`hostContext.locale`, normalized to a supported language), then
+ * English. Server-side summaries have no host locale, so `system` reads as
+ * English there (`explicitLocale(...) ?? "en"`).
+ */
+export const LANGUAGES = ["system", ...LOCALES];
+/**
+ * The supported locale a language preference names explicitly — `undefined`
+ * for `system`, a missing value, or anything this build ships no catalog for.
+ * Loose input on purpose: profile feeds arrive untyped.
+ */
+export function explicitLocale(language) {
+    return LOCALES.find((locale) => locale === language);
+}
+/**
+ * Bumped when the persisted profile shape changes in a migration-relevant way.
+ * Every bump needs a matching entry in `PROFILE_MIGRATIONS`
+ * (`profile-migrations.ts`) so stored records upgrade on read instead of
+ * losing their preferences.
+ *
+ * v3 is the migration baseline (`PROFILE_MIGRATION_BASELINE`): a
+ * connector-free record — language, `modules.<module>` slices + metadata —
+ * owned by this core package. The theme preference it once carried is gone
+ * (widgets follow the host's theme); a stored `theme` key stays inert in the
+ * raw document, so it needed no migration.
+ */
+export const PROFILE_SCHEMA_VERSION = 3;
+//# sourceMappingURL=profile-constants.js.map

package/dist/profile-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-constants.js","sourceRoot":"","sources":["../src/profile-constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kFAAkF;AAClF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,IAAI,CAAU,CAAA;AAG5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,GAAG,OAAO,CAAU,CAAA;AAGxD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,QAA4B;IACzD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAA;AACtD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAA"}