@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/lib/biome-host/create-biome-orval-config.ts

@@ -1,82 +0,0 @@
-/**
- * Shared Orval-client wiring for frontend biomes.
- *
- * Every biome that calls a platform API through an Orval-generated client must
- * configure that client with the SAME auth/header/401 behavior the host shell
- * uses for its own clients. Hand-copying a `configureOrgDbClient`-style helper
- * into each biome (as `org-databases` did across three hook files) duplicates
- * the correlation-id + org-header + token logic and lets it drift from the
- * host. This factory centralizes it: a biome builds one config from its
- * `HostBridge` and feeds it straight into the client's `configureClient(...)`.
- *
- * Auth/refresh/redirect stay HOST-owned — this only READS the bridge's
- * host-implemented methods (`getActorToken`, `ensureFreshToken`,
- * `onUnauthorized`, `getOrgId`). It owns no auth state of its own.
- */
-import type { HostBridge } from './host-bridge';
-
-/**
- * The Orval client config shape every generated `configureClient(...)` accepts.
- * Kept structural (not imported from a client package) so the kernel stays free
- * of any concrete service-client dependency — biomes pass the result straight
- * into their own client's `configureClient`, which validates the shape.
- */
-export interface BiomeOrvalConfig {
-  readonly baseUrl: string;
-  readonly maxRetries: number;
-  getAuthToken(): Promise<string>;
-  getHeaders(): Promise<Record<string, string>>;
-  onUnauthorized(): Promise<void>;
-}
-
-export interface CreateBiomeOrvalConfigOptions {
-  /** Absolute base URL of the target service. */
-  readonly baseUrl: string;
-  /**
-   * Retry budget for the underlying fetch wrapper. Defaults to 1 — a single
-   * retry covers the `onUnauthorized` refresh-then-retry path without turning
-   * a hard failure into a retry storm.
-   */
-  readonly maxRetries?: number;
-}
-
-/**
- * Build an Orval client config from a `HostBridge`. Wires:
- *   - `getAuthToken` → `bridge.auth.ensureFreshToken()` (proactive refresh;
- *     the host owns the refresh + login-redirect single-flight).
- *   - `getHeaders` → a fresh `X-Correlation-Id` per call, plus `X-Xema-Org-Id`
- *     (the canonical Xema-platform tenant header every platform service reads
- *     via `RequestContext`) when an org is selected. Biome web clients only ever
- *     call Xema-platform biome-apis, so this is the single correct tenant
- *     header; the previously-sent legacy `X-Org-Id` was dead (the central
- *     read-side was decommissioned) and left context-derived reads without an
- *     org. Per-call headers set by the caller still win in the client's own
- *     header merge.
- *   - `onUnauthorized` → `bridge.auth.onUnauthorized()` (host force-refresh +
- *     redirect-on-failure).
- *
- * @example
- *   configureClient(createBiomeOrvalConfig(bridge, { baseUrl: API_BASE_URL }));
- */
-export function createBiomeOrvalConfig(
-  bridge: HostBridge,
-  opts: CreateBiomeOrvalConfigOptions,
-): BiomeOrvalConfig {
-  return {
-    baseUrl: opts.baseUrl,
-    maxRetries: opts.maxRetries ?? 1,
-    getAuthToken: () => bridge.auth.ensureFreshToken(),
-    getHeaders: () => {
-      const headers: Record<string, string> = {
-        'X-Correlation-Id': crypto.randomUUID(),
-      };
-      const orgId = bridge.auth.getOrgId();
-      if (orgId) {
-        // Canonical header read by every Xema-platform service's RequestContext.
-        headers['X-Xema-Org-Id'] = orgId;
-      }
-      return Promise.resolve(headers);
-    },
-    onUnauthorized: () => bridge.auth.onUnauthorized(),
-  };
-}

package/src/lib/biome-host/define-web-biome.spec.ts

@@ -1,221 +0,0 @@
-/**
- * `defineWebBiome` — define-time scope/access locking, the fail-closed
- * defaults, and closed-set completeness.
- *
- * This suite replaces an earlier `define-web-biome.test.js` written for
- * Node's test runner against `dist/`. That file ran NOWHERE: the package's
- * `test` script is a notice (the kernel carries no test runner by design) and
- * the host-web vitest `include` is `*.{test,spec}.{ts,tsx}` — so a `.js` file
- * was invisible to both. A security test that never executes reads as
- * coverage while proving nothing, so it is gone; this vitest spec is synced
- * into the host mirror by the frontend bridge and runs there with everything
- * else.
- *
- * The invariant under test is the security one: a route is public ONLY when
- * its author said so twice, explicitly. Nothing defaulted, inferred, or
- * coerced can produce a public route.
- */
-import { describe, expect, it } from 'vitest';
-
-import { defineWebBiome } from './define-web-biome';
-import {
-  PAGE_CHROME_VALUES,
-  ROUTE_ACCESS_VALUES,
-  ROUTE_SCOPE_VALUES,
-  type PageChrome,
-  type RouteAccess,
-  type RouteScope,
-} from './frontend-biome';
-
-import type { HostBridge } from './host-bridge';
-
-const load = () => Promise.resolve({ default: () => null });
-const bridge = {} as HostBridge;
-
-describe('defineWebBiome — public/chromeless scope', () => {
-  it('rejects a public page whose access defaults to member', () => {
-    expect(() =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [{ slug: 'ext/:id', label: 'Ext', scope: 'public', load }],
-      }),
-    ).toThrow(/a 'public' scope page MUST declare access: 'public'/);
-  });
-
-  it('rejects a public page with an explicit non-public access tier', () => {
-    expect(() =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [
-          {
-            slug: 'ext/:id',
-            label: 'Ext',
-            scope: 'public',
-            access: 'org-admin',
-            load,
-          },
-        ],
-      }),
-    ).toThrow(/a 'public' scope page MUST declare access: 'public'/);
-  });
-
-  it('rejects a non-public page that declares access public', () => {
-    expect(() =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [{ slug: 'system/x', label: 'X', access: 'public', load }],
-      }),
-    ).toThrow(/access: 'public' is only valid on a 'public' scope page/);
-  });
-
-  it('accepts a public + access:public page and emits no nav item', () => {
-    const biome = defineWebBiome({
-      id: 'test-biome',
-      displayName: 'Test',
-      pages: [
-        {
-          slug: 'ext/:id',
-          label: 'Ext',
-          scope: 'public',
-          access: 'public',
-          load,
-        },
-      ],
-    })(bridge);
-
-    expect(biome.routes).toHaveLength(1);
-    const route = biome.routes?.[0];
-    expect(route?.path).toBe('ext/:id');
-    expect(route?.access).toBe('public');
-    expect(route?.projectScoped).toBe(false);
-    // A public route is un-authenticated; it never belongs in the authed rail.
-    expect(biome.navItems).toHaveLength(0);
-  });
-
-  it('chrome defaults to host and none passes through', () => {
-    const biome = defineWebBiome({
-      id: 'test-biome',
-      displayName: 'Test',
-      pages: [
-        { slug: 'system/a', label: 'A', load },
-        { slug: 'system/b', label: 'B', chrome: 'none', load },
-      ],
-    })(bridge);
-
-    expect(biome.routes?.find((r) => r.path === 'system/a')?.chrome).toBe(
-      'host',
-    );
-    expect(biome.routes?.find((r) => r.path === 'system/b')?.chrome).toBe(
-      'none',
-    );
-  });
-});
-
-describe('defineWebBiome — public is opt-in, never a default', () => {
-  /**
-   * THE fail-closed invariant. An ordinarily-declared page (no `scope`, no
-   * `access`) must emit a route that carries NO `access` marker at all — the
-   * host then applies its own `member` default. If the kernel ever started
-   * defaulting `access` (or `scope`) to `'public'`, every existing biome route
-   * in the fleet would silently become reachable without a session.
-   *
-   * Mutation-proof (recorded 2026-07-22): flipping the emit in
-   * `defineWebBiome` to `access: page.access ?? 'public'` turns this test RED
-   * ("expected 'public' to be undefined"), and flipping the validator default
-   * `page.access ?? 'member'` to `?? 'public'` makes the ordinary page throw
-   * at define time — RED in this test and in the two below. There is no
-   * mutation of a default that makes a route public and keeps the suite green.
-   */
-  it('an ordinary page emits NO access marker (host defaults to member)', () => {
-    const biome = defineWebBiome({
-      id: 'test-biome',
-      displayName: 'Test',
-      pages: [{ slug: 'system/a', label: 'A', load }],
-    })(bridge);
-
-    const route = biome.routes?.[0];
-    expect(route?.access).toBeUndefined();
-    expect(route?.projectScoped).toBe(false);
-    // …and it DOES contribute a nav item, unlike a public route.
-    expect(biome.navItems).toHaveLength(1);
-  });
-
-  it('an authenticated page can be chromeless without becoming public', () => {
-    // Chrome and access are orthogonal axes: the embedded-app case.
-    const biome = defineWebBiome({
-      id: 'test-biome',
-      displayName: 'Test',
-      pages: [
-        {
-          slug: 'apps/:appId/embed',
-          label: 'Embedded app',
-          chrome: 'none',
-          navHidden: true,
-          load,
-        },
-      ],
-    })(bridge);
-
-    const route = biome.routes?.[0];
-    expect(route?.chrome).toBe('none');
-    expect(route?.access).toBeUndefined();
-  });
-
-  it('every non-public access tier is rejected on a public page', () => {
-    for (const access of ROUTE_ACCESS_VALUES.filter((a) => a !== 'public')) {
-      expect(() =>
-        defineWebBiome({
-          id: 'test-biome',
-          displayName: 'Test',
-          pages: [{ slug: 'ext', label: 'Ext', scope: 'public', access, load }],
-        }),
-      ).toThrow(/MUST declare access: 'public'/);
-    }
-  });
-
-  it('every non-public scope rejects access public', () => {
-    for (const scope of ROUTE_SCOPE_VALUES.filter((s) => s !== 'public')) {
-      expect(() =>
-        defineWebBiome({
-          id: 'test-biome',
-          displayName: 'Test',
-          pages: [{ slug: 'x', label: 'X', scope, access: 'public', load }],
-        }),
-      ).toThrow(/only valid on a 'public' scope page/);
-    }
-  });
-});
-
-describe('closed-set completeness', () => {
-  /**
-   * The runtime tuples ARE the types (`RouteAccess = typeof
-   * ROUTE_ACCESS_VALUES[number]`), so a new member cannot be added to the type
-   * without appearing here — which is what makes the exhaustive iteration in
-   * this file, and the host resolver's `default`-less switch, complete by
-   * construction. These assertions are the compile-time proof made executable:
-   * the `satisfies` widening below fails to compile if a tuple ever drifts
-   * from its type.
-   */
-  it('the access tuple enumerates exactly the RouteAccess union', () => {
-    const all: readonly RouteAccess[] =
-      ROUTE_ACCESS_VALUES satisfies readonly RouteAccess[];
-    expect([...all].sort()).toEqual(
-      ['member', 'org-admin', 'platform-admin', 'public'].sort(),
-    );
-  });
-
-  it('the scope tuple enumerates exactly the RouteScope union', () => {
-    const all: readonly RouteScope[] =
-      ROUTE_SCOPE_VALUES satisfies readonly RouteScope[];
-    expect([...all].sort()).toEqual(['org', 'project', 'public'].sort());
-  });
-
-  it('the chrome tuple enumerates exactly the PageChrome union', () => {
-    const all: readonly PageChrome[] =
-      PAGE_CHROME_VALUES satisfies readonly PageChrome[];
-    expect([...all].sort()).toEqual(['host', 'none'].sort());
-  });
-});

package/src/lib/biome-host/define-web-biome.ts

@@ -1,222 +0,0 @@
-/**
- * `defineWebBiome` — the authoring helper for `target: 'web'` biomes.
- *
- * Every web biome used to hand-repeat the same ~30 lines: one
- * `lazy(() => import('./pages/X'))` per page, a `navItems` array, and a
- * parallel `routes` array — writing the slug TWICE (once as `navItem.route`,
- * once as `route.path`), the classic source of "nav points at a path no route
- * serves" bugs.
- *
- * `defineWebBiome` collapses that to one declarative page list. Each
- * {@link WebBiomePage} single-sources its `slug` for BOTH the nav route and the
- * route path, so they can never drift. The helper emits one nav item (unless
- * `navHidden`) and one route per page, wrapping the lazily-loaded page in a
- * `<Suspense fallback={null}>` boundary via {@link lazyRoute}.
- *
- * Authors declare WHAT each surface is (`category`) and let the HOST own WHERE
- * it renders in the global menu. `init`/`dispose`/`panels`/`session`/
- * `outputRenderers` pass through to the `FrontendBiome` untouched, so bespoke
- * biomes (one-shot registrations, slot fillers, session contributions) still
- * use this helper.
- *
- * Host-framework-agnostic: pure React (`lazy`/`Suspense`/`createElement` via
- * `lazyRoute`), no router and no Next.js.
- *
- * @example
- *   export default defineWebBiome({
- *     id: 'spaces-web',
- *     displayName: 'Spaces',
- *     pages: [
- *       {
- *         slug: 'system/spaces',
- *         label: 'Spaces',
- *         icon: Layers,
- *         category: 'knowledge',
- *         load: () => import('./pages/SpacesPage'),
- *       },
- *     ],
- *   });
- */
-
-import { lazyRoute } from './biome-builders';
-
-import type {
-  FrontendBiome,
-  FrontendBiomeFactory,
-  NavItemContribution,
-  PageChrome,
-  RouteAccess,
-  RouteContribution,
-  RouteScope,
-} from './frontend-biome';
-import type { ComponentType } from 'react';
-
-export interface WebBiomePage {
-  /**
-   * Single source of truth for BOTH the nav route AND the route path — the
-   * helper sets `navItem.route === route.path === slug`, so they can never
-   * diverge. May include `:param` segments (e.g. `system/concepts/:slug`).
-   */
-  readonly slug: string;
-  /**
-   * Stable nav-item id used for active-state matching + analytics. Defaults to
-   * {@link slug} when omitted — pass it explicitly only to preserve a
-   * pre-existing short id (e.g. `grants`) that differs from the route slug
-   * (`system/grants`). Must be unique across the biome's pages.
-   */
-  readonly id?: string;
-  /** Displayed nav label. */
-  readonly label: string;
-  /** Optional nav icon. Typed to match {@link NavItemContribution.icon}. */
-  readonly icon?: ComponentType<{ className?: string | undefined }>;
-  /**
-   * Host menu category — the biome's INTENT (`primary` | `build` | `operate` |
-   * `knowledge` | `admin` | `account`). The host maps it to a concrete rail
-   * group + order.
-   */
-  readonly category?: string;
-  /**
-   * Route scope. `'org'` (default) mounts at the org root; `'project'` mounts
-   * under the canonical project-scoped route prefix; `'public'` mounts OUTSIDE
-   * the host's authenticated group (no Keycloak session, no login redirect, no
-   * org switcher). Maps to {@link RouteContribution.projectScoped} for the
-   * authenticated scopes; a `'public'` page MUST also declare
-   * `access: 'public'` (enforced at define time).
-   */
-  readonly scope?: RouteScope;
-  /**
-   * Access tier required to render the route. Defaults to `'member'`. A
-   * `'public'` page (scope `'public'`) MUST set this to `'public'`; a non-public
-   * page MUST NOT — both contradictions are rejected at define time.
-   */
-  readonly access?: RouteAccess;
-  /**
-   * Whether the host wraps the page in its application shell. Defaults to
-   * `'host'`; `'none'` renders with no app rail, topbar, or org switcher.
-   */
-  readonly chrome?: PageChrome;
-  /** Dynamic import of the page module (`() => import('./pages/X')`). */
-  readonly load: () => Promise<{ default: ComponentType<unknown> }>;
-  /**
-   * When true the route is registered but NO nav item is emitted — for hidden
-   * surfaces such as a `:param` detail route reached only by deeplink.
-   */
-  readonly navHidden?: boolean;
-}
-
-export interface DefineWebBiomeOptions {
-  /** Stable biome id; matches `xema-biome.json` `xema.id`. */
-  readonly id: string;
-  /** Displayed name. */
-  readonly displayName: string;
-  /** One-shot initializer; passed through to {@link FrontendBiome.init}. */
-  readonly init?: FrontendBiome['init'];
-  /** Teardown counterpart; passed through to {@link FrontendBiome.dispose}. */
-  readonly dispose?: FrontendBiome['dispose'];
-  /** The biome's pages — one nav item (unless `navHidden`) + one route each. */
-  readonly pages: readonly WebBiomePage[];
-  /** Slot fillers; passed through to {@link FrontendBiome.panels}. */
-  readonly panels?: FrontendBiome['panels'];
-  /** Session-shell contributions; passed through to {@link FrontendBiome.session}. */
-  readonly session?: FrontendBiome['session'];
-  /** Output renderers; passed through to {@link FrontendBiome.outputRenderers}. */
-  readonly outputRenderers?: FrontendBiome['outputRenderers'];
-}
-
-/** Default host-shell mode a page renders in when it omits `chrome`. */
-const DEFAULT_PAGE_CHROME: PageChrome = 'host';
-
-/**
- * Reject the two `scope`/`access` contradictions at define time (module load,
- * when the biome calls `defineWebBiome(...)` at its top level) — fail fast, do
- * NOT silently coerce:
- *
- *   1. A `public` page with any `access` other than `'public'`: a public route
- *      is un-authenticated, so a privilege tier is meaningless. The author must
- *      set `access: 'public'` explicitly (an omitted `access` defaults to
- *      `'member'`, which is exactly this contradiction).
- *   2. A non-`public` page declaring `access: 'public'`: `'public'` is the
- *      no-auth marker; an org/project route is always authenticated.
- *
- * `scope` defaults to `'org'` and `access` defaults to `'member'` for the
- * purpose of this check, matching the emit defaults below.
- */
-function assertPageScopeAccessLocked(biomeId: string, page: WebBiomePage): void {
-  const scope: RouteScope = page.scope ?? 'org';
-  const access: RouteAccess = page.access ?? 'member';
-  const where = `web biome '${biomeId}' page '${page.slug}'`;
-
-  if (scope === 'public' && access !== 'public') {
-    throw new Error(
-      `${where}: a 'public' scope page MUST declare access: 'public' ` +
-        `(got access: '${access}'). A public route is un-authenticated, so an ` +
-        `authenticated privilege tier is a contradiction. Set access: 'public' ` +
-        `or change the scope.`,
-    );
-  }
-  if (scope !== 'public' && access === 'public') {
-    throw new Error(
-      `${where}: access: 'public' is only valid on a 'public' scope page ` +
-        `(got scope: '${scope}'). '${access}' is the no-auth marker; an ` +
-        `org/project route is always authenticated. Set scope: 'public' or ` +
-        `change the access tier.`,
-    );
-  }
-}
-
-/**
- * Build the `FrontendBiomeFactory` a web biome default-exports. See the
- * module doc-comment for the rationale and an example.
- */
-export function defineWebBiome(
-  options: DefineWebBiomeOptions,
-): FrontendBiomeFactory {
-  // Validate every page's scope/access pairing NOW, at module load, so a
-  // contradiction surfaces the instant the biome module is imported — not
-  // lazily when the host first calls the factory.
-  for (const page of options.pages) {
-    assertPageScopeAccessLocked(options.id, page);
-  }
-
-  return () => {
-    const navItems: NavItemContribution[] = [];
-    const routes: RouteContribution[] = [];
-
-    for (const page of options.pages) {
-      routes.push({
-        path: page.slug,
-        projectScoped: page.scope === 'project',
-        element: lazyRoute(page.load),
-        chrome: page.chrome ?? DEFAULT_PAGE_CHROME,
-        ...(page.access ? { access: page.access } : {}),
-      });
-
-      // Public routes mount OUTSIDE the authenticated group and never belong in
-      // the authenticated app rail — so they contribute no nav item regardless
-      // of `navHidden`. Authenticated pages emit a nav item unless hidden.
-      if (!page.navHidden && page.scope !== 'public') {
-        navItems.push({
-          id: page.id ?? page.slug,
-          label: page.label,
-          route: page.slug,
-          ...(page.icon ? { icon: page.icon } : {}),
-          ...(page.category !== undefined ? { category: page.category } : {}),
-        });
-      }
-    }
-
-    return {
-      id: options.id,
-      displayName: options.displayName,
-      navItems,
-      routes,
-      ...(options.init ? { init: options.init } : {}),
-      ...(options.dispose ? { dispose: options.dispose } : {}),
-      ...(options.panels ? { panels: options.panels } : {}),
-      ...(options.session ? { session: options.session } : {}),
-      ...(options.outputRenderers
-        ? { outputRenderers: options.outputRenderers }
-        : {}),
-    };
-  };
-}