@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/lib/biome-host/errors.ts

@@ -1,220 +0,0 @@
-/**
- * Canonical user-facing error decoder — ONE implementation biomes, the host
- * shell, and the kernel's {@link ErrorCard} default all share.
- *
- * Biomes were each re-implementing "pull a human message off an error"
- * (envelope shapes, status-code copy, "failed to fetch"). This is the single
- * host-agnostic decoder. It is a PURE function: no fetch, no i18n, no config,
- * no `instanceof` against host classes. It recognises the two error shapes the
- * Xema frontend produces by their structural signature:
- *
- *   - the host's `ApiClientError` (`name === 'ApiClientError'`, `statusCode`,
- *     `message`, optional `errorType`), thrown by the hand-rolled HTTP client;
- *   - Orval's generated `ClientError` (`name === 'ClientError'`, `status`,
- *     `message`, `body`), thrown by the generated clients. Its `body` carries
- *     the backend `{ message, code, details }` envelope (and the workflow
- *     wallet-missing / `session_busy` special cases).
- *
- * Hosts that previously kept their own `getUserFacingErrorMessage` should
- * re-export THIS one (or delete theirs and import it) so there is a single
- * decoder. {@link ErrorCard} defaults to it, so biomes get envelope-aware copy
- * without wiring anything.
- */
-
-function collapseWhitespace(value: string): string {
-  return value.split(/\s+/).join(' ').trim();
-}
-
-function getGenericErrorMessage(message: string, fallback: string): string {
-  const normalized = collapseWhitespace(message);
-  if (/failed to fetch/i.test(normalized)) {
-    return 'Could not reach the service. Check your connection and try again.';
-  }
-  return normalized || fallback;
-}
-
-function normalizeValidationMessage(rawMessage: string): string {
-  const parts = rawMessage
-    .split(',')
-    .map((part) => collapseWhitespace(part))
-    .filter(Boolean);
-
-  if (parts.length === 0) {
-    return 'Some required fields are missing or invalid. Please review your input and try again.';
-  }
-
-  const preview = parts.slice(0, 2).join('; ');
-  const suffix = parts.length > 2 ? '; and more.' : '.';
-  return `Some required fields are missing or invalid (${preview}${suffix})`;
-}
-
-/** Structural signature of the host's `ApiClientError`. */
-interface ApiClientErrorLike {
-  readonly name: string;
-  readonly statusCode: number;
-  readonly message: string;
-  readonly errorType?: string;
-}
-
-function isApiClientErrorLike(error: unknown): error is ApiClientErrorLike {
-  if (!error || typeof error !== 'object') {
-    return false;
-  }
-  const record = error as Record<string, unknown>;
-  return (
-    record['name'] === 'ApiClientError' &&
-    typeof record['statusCode'] === 'number' &&
-    typeof record['message'] === 'string'
-  );
-}
-
-/** Structural signature of an Orval-generated `ClientError`. */
-interface OrvalClientErrorLike {
-  readonly name: string;
-  readonly status: number;
-  readonly message: string;
-  readonly body: unknown;
-}
-
-function isOrvalClientErrorLike(error: unknown): error is OrvalClientErrorLike {
-  if (!error || typeof error !== 'object') {
-    return false;
-  }
-  const record = error as Record<string, unknown>;
-  return (
-    record['name'] === 'ClientError' &&
-    typeof record['status'] === 'number' &&
-    typeof record['message'] === 'string' &&
-    Object.hasOwn(record, 'body')
-  );
-}
-
-interface WorkflowErrorEnvelope {
-  readonly code?: string;
-  readonly message?: string;
-  readonly details?: Record<string, unknown>;
-}
-
-function readStringList(value: unknown): string[] | null {
-  if (!Array.isArray(value)) {
-    return null;
-  }
-  if (value.some((entry) => typeof entry !== 'string')) {
-    return null;
-  }
-  return value;
-}
-
-function normalizeWorkflowWalletMissingMessage(envelope: WorkflowErrorEnvelope): string | null {
-  if (envelope.code !== 'WORKFLOW_WALLET_NOT_FOUND') {
-    return null;
-  }
-  const missing = readStringList(envelope.details?.['missing']);
-  if (missing === null || missing.length === 0) {
-    return 'One or more required wallets are missing for this project.';
-  }
-  return `Missing wallet${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}. Add ${
-    missing.length > 1 ? 'them' : 'it'
-  } in Project Settings -> Wallets.`;
-}
-
-function getApiClientErrorMessage(error: ApiClientErrorLike, fallback: string): string {
-  if (error.statusCode === 0) {
-    return collapseWhitespace(error.message) || fallback;
-  }
-  if (error.statusCode === 400) {
-    const raw = collapseWhitespace(error.message);
-    if (raw.includes(' must ') || raw.includes('regular expression')) {
-      return normalizeValidationMessage(raw);
-    }
-    return raw || 'The request is invalid. Please check your input and try again.';
-  }
-  if (error.statusCode === 401) {
-    return 'Your session expired. Please sign in again.';
-  }
-  if (error.statusCode === 403) {
-    return 'You do not have permission to perform this action.';
-  }
-  if (error.statusCode === 404) {
-    return 'The requested resource was not found.';
-  }
-  if (error.statusCode >= 500) {
-    return 'The service is temporarily unavailable. Please try again in a moment.';
-  }
-  return collapseWhitespace(error.message) || fallback;
-}
-
-function getOrvalClientErrorMessage(error: OrvalClientErrorLike, fallback: string): string {
-  if (error.status >= 500) {
-    return 'The service is temporarily unavailable. Please try again in a moment.';
-  }
-  // session-api refuses mutations while a prompt turn is in flight; the 409
-  // body is `{ error: 'session_busy', retryAfterTurnDone: true }`. Surface a
-  // clear retry hint instead of the generic "Conflict" copy.
-  if (error.status === 409) {
-    const body = error.body;
-    if (body && typeof body === 'object') {
-      const record = body as Record<string, unknown>;
-      if (record['error'] === 'session_busy') {
-        return 'Your last message is still running. Wait for the agent to finish, then try again.';
-      }
-    }
-  }
-  const body = error.body;
-  if (body && typeof body === 'object') {
-    const record = body as Record<string, unknown>;
-    const payload: WorkflowErrorEnvelope = (() => {
-      const message = record['message'];
-      if (message && typeof message === 'object') {
-        return message;
-      }
-      return {
-        code: typeof record['code'] === 'string' ? record['code'] : undefined,
-        message: typeof record['message'] === 'string' ? record['message'] : undefined,
-        details:
-          record['details'] && typeof record['details'] === 'object'
-            ? (record['details'] as Record<string, unknown>)
-            : undefined,
-      };
-    })();
-
-    const workflowWalletMessage = normalizeWorkflowWalletMissingMessage(payload);
-    if (workflowWalletMessage !== null) {
-      return workflowWalletMessage;
-    }
-    if (typeof payload.message === 'string' && payload.message.trim().length > 0) {
-      return collapseWhitespace(payload.message);
-    }
-    if (typeof record['message'] === 'string' && record['message'].trim().length > 0) {
-      return collapseWhitespace(record['message']);
-    }
-  }
-  return getGenericErrorMessage(error.message, fallback);
-}
-
-/**
- * Decode any thrown value into a human, user-facing message. The single decoder
- * for biomes, the host shell, and {@link ErrorCard}'s default.
- *
- * @param error Any thrown value (string, `Error`, `ApiClientError`, Orval
- *   `ClientError`, or unknown).
- * @param fallback Copy returned when nothing better can be extracted.
- */
-export function getUserFacingErrorMessage(
-  error: unknown,
-  fallback = 'Something went wrong. Please try again.',
-): string {
-  if (typeof error === 'string') {
-    return collapseWhitespace(error) || fallback;
-  }
-  if (isApiClientErrorLike(error)) {
-    return getApiClientErrorMessage(error, fallback);
-  }
-  if (isOrvalClientErrorLike(error)) {
-    return getOrvalClientErrorMessage(error, fallback);
-  }
-  if (error instanceof Error) {
-    return getGenericErrorMessage(error.message, fallback);
-  }
-  return fallback;
-}

package/src/lib/biome-host/frontend-biome.ts

@@ -1,256 +0,0 @@
-import type { HostBridge } from './host-bridge';
-import type { SessionContributions } from './session-contributions';
-import type { ComponentType, ReactNode } from 'react';
-
-/**
- * Runtime contribution types a `target: 'web'` biome composes. Web
- * biomes default-export a `FrontendBiomeFactory` from their package
- * (the import specifier is `xema-biome.json#name`); the SPA's
- * auto-generated `xema:web-biome-loaders` virtual module imports each
- * factory at bootstrap, calls it with the host's `HostBridge`, and
- * registers the resulting `FrontendBiome` into the singleton
- * `biomeRegistry`.
- */
-
-export interface NavItemContribution {
-  /** Stable id used for active-state matching + analytics. */
-  readonly id: string;
-  /** Displayed label. */
-  readonly label: string;
-  /** Route path the nav item links to. */
-  readonly route: string;
-  /**
-   * Optional icon component. Typed with `className: string | undefined` so
-   * any host icon kit whose props include `className` (lucide-react,
-   * heroicons, custom SVG components) is assignable under
-   * `exactOptionalPropertyTypes: true`. The host renders with whatever
-   * className it computes from its own theme.
-   */
-  readonly icon?: ComponentType<{ className?: string | undefined }>;
-  /**
-   * Semantic menu category the biome declares its INTENT to live in (e.g.
-   * `build`, `operate`, `knowledge`, `account`). The HOST owns the menu
-   * information-architecture: it maps a category to a concrete rail group,
-   * heading, and order. Authors declare WHAT a surface is, not WHERE in the
-   * global menu it renders — so the platform can re-organise the menu without
-   * editing every biome. When omitted, the host falls back to its own
-   * taxonomy (keyed on the nav-item id).
-   */
-  readonly category?: string;
-}
-
-/**
- * Access tier required to render a route. The host resolver enforces it
- * declaratively — nav-hide is NOT a security boundary, a deeplink bypasses it.
- * Precedence (least → most privileged): `member` < `org-admin` <
- * `platform-admin`. Defaults to `member` when a route omits the field.
- *
- * `public` is NOT a privilege tier — it is the *no-auth* marker: a `public`
- * route requires no Keycloak session at all and mounts OUTSIDE the host's
- * authenticated route group. It is value-locked to `RouteScope` `'public'`
- * (`defineWebBiome` rejects any other pairing at define time), so a route is
- * public in BOTH senses or in neither. Closed set — a new member is a
- * one-line change to {@link ROUTE_ACCESS_VALUES} and one `case` in the host
- * resolver's exhaustive `hasRouteAccess` switch (the switch has no `default`,
- * so an unhandled member is a compile error, never a silent allow).
- *
- * The tuple below is the SINGLE source of truth: the type is derived from it,
- * so a member cannot exist in the type without also being enumerable at
- * runtime — which is what lets a host prove exhaustiveness in a test rather
- * than by inspection. Order is least → most privileged; `public` is the
- * no-auth marker and is deliberately last.
- */
-export const ROUTE_ACCESS_VALUES = [
-  'member',
-  'org-admin',
-  'platform-admin',
-  'public',
-] as const;
-
-/** Access tier required to render a route. See {@link ROUTE_ACCESS_VALUES}. */
-export type RouteAccess = (typeof ROUTE_ACCESS_VALUES)[number];
-
-/**
- * Where a route mounts in the host's URL/auth topology. Closed set — adding a
- * member is a one-line change here (and the single mapping in `defineWebBiome`
- * plus one resolver partition in the host).
- *
- * - `org` — mounts at the org root, inside the authenticated group.
- * - `project` — mounts under the project-scoped route prefix, inside the
- *   authenticated group.
- * - `public` — mounts OUTSIDE the authenticated group; no Keycloak session,
- *   no login redirect, no org switcher. Locked to `RouteAccess` `'public'`.
- *
- * Single source of truth for the closed set; the type is derived from it.
- */
-export const ROUTE_SCOPE_VALUES = ['org', 'project', 'public'] as const;
-
-/** Where a route mounts. See {@link ROUTE_SCOPE_VALUES}. */
-export type RouteScope = (typeof ROUTE_SCOPE_VALUES)[number];
-
-/**
- * Whether a page renders wrapped in the host application shell (app rail,
- * topbar, org switcher) or standalone. Closed set — a new member is a one-line
- * change here. Defaults to `'host'` when a page omits it.
- *
- * - `host` — the default; the host renders its chrome around the page.
- * - `none` — the host renders the page with NO app rail, topbar, or org
- *   switcher (a full-bleed surface). `public` routes are structurally
- *   chromeless (their route group ships no shell); `none` also lets an
- *   authenticated route opt out of the shell.
- *
- * Single source of truth for the closed set; the type is derived from it.
- * Chrome is ORTHOGONAL to access: `chrome: 'none'` on an authenticated route
- * is the embedded-app case and grants no privilege change whatsoever.
- */
-export const PAGE_CHROME_VALUES = ['host', 'none'] as const;
-
-/** Host-shell mode a page renders in. See {@link PAGE_CHROME_VALUES}. */
-export type PageChrome = (typeof PAGE_CHROME_VALUES)[number];
-
-export interface RouteContribution {
-  /** React-router path. May include params. */
-  readonly path: string;
-  /** Element factory — host calls it inside the route tree. */
-  readonly element: () => ReactNode;
-  /**
-   * Whether the route is project-scoped (mounted under /projects/:projectId)
-   * or org-scoped (mounted at the org root). REQUIRED — the host nav resolver
-   * partitions the rail strictly by this flag and drops any nav item whose
-   * route can't be matched (fail-loud). A silent default would re-introduce the
-   * "project pages showing at org level" class of bug, so every route MUST
-   * declare its scope explicitly.
-   */
-  readonly projectScoped: boolean;
-  /**
-   * Access tier required to render this route. The host resolver enforces it
-   * declaratively. Defaults to `'member'` when omitted. `'public'` marks a
-   * no-auth route the host mounts outside its authenticated group.
-   */
-  readonly access?: RouteAccess;
-  /**
-   * Whether the host wraps this route in its application shell. Defaults to
-   * `'host'` when omitted; `'none'` renders the page with no app rail,
-   * topbar, or org switcher. See {@link PageChrome}.
-   */
-  readonly chrome?: PageChrome;
-}
-
-/**
- * Slot fillers — biomes contribute UI fragments rendered by named
- * `<BiomeSlot name="…">` boundaries placed in the host app shell.
- * Initial slots: 'org-header-actions', 'project-overview-cards',
- * 'run-detail-side-panel', 'settings-tabs', 'session-actions'.
- */
-export interface PanelContribution {
-  /** Slot name the contribution renders into. */
-  readonly slot: string;
-  /** Stable id for ordering + replacement. */
-  readonly id: string;
-  /** React node factory — host calls it inside the slot. */
-  readonly render: () => ReactNode;
-  /** Sort weight within the slot (lower first). Defaults to 100. */
-  readonly weight?: number;
-}
-
-/**
- * Lifecycle context passed to `FrontendBiome.init`. The host invokes
- * `init()` exactly once after the biome's factory returns and before
- * any session contribution is read. Biomes use it to wire any
- * imperative one-time work (Orval client setup, feature-flag registration,
- * background-cache prefetch) — declarative contributions go on the
- * `FrontendBiome` itself, not here.
- */
-export interface BiomeInitContext {
-  readonly bridge: HostBridge;
-  /** Biome id, mirrored from `FrontendBiome.id` for convenience. */
-  readonly biomeId: string;
-}
-
-export interface FrontendBiome {
-  /** Stable biome id; matches xema-biome.json `xema.id`. */
-  readonly id: string;
-  /** Displayed name. */
-  readonly displayName: string;
-  /**
-   * One-shot initializer invoked after registration. Used for imperative
-   * setup that doesn't fit a declarative contribution (e.g. seeding a
-   * shared cache, mounting a side-effect listener). Idempotent: the
-   * registry guarantees `init()` runs at most once per biome per SPA
-   * session, even across HMR reloads.
-   */
-  readonly init?: (ctx: BiomeInitContext) => void | Promise<void>;
-  /**
-   * Optional teardown counterpart to `init()`. Invoked when the biome
-   * is explicitly unregistered (admin disable flow). Biomes MUST NOT
-   * rely on `dispose()` running on tab close — browsers don't guarantee
-   * it. Use it for live-subscription cleanup, not for persistence.
-   */
-  readonly dispose?: () => void | Promise<void>;
-  readonly navItems?: readonly NavItemContribution[];
-  readonly routes?: readonly RouteContribution[];
-  readonly panels?: readonly PanelContribution[];
-  /**
-   * Declarative contributions to the agent-session shell. See
-   * `session-contributions.ts` for the full taxonomy. Each contribution
-   * is a small data object; the host's session components read them
-   * through typed selector hooks and render the matching primitives.
-   */
-  readonly session?: SessionContributions;
-  /**
-   * Output renderer contributions. Each entry binds a biome-defined
-   * artifact `OutputKind` (e.g. `catalog_entity_info`) to the React
-   * component that renders it inside `<OutputCard>`. The host's renderer
-   * registry overlays biome contributions on top of the built-in set —
-   * built-in kinds (`markdown_doc`, `json_payload`, …) cannot be
-   * overridden, but new kinds light up the moment the biome's frontend
-   * loads.
-   *
-   * See `packages/output-contracts` for the `OutputKind` taxonomy and
-   * `submodules/xema-host-web/src/components/outputs/renderer-registry.tsx`
-   * for the resolver. Biome renderers receive the same `OutputItem`
-   * shape as built-ins.
-   */
-  readonly outputRenderers?: readonly OutputRendererContribution[];
-}
-
-/**
- * One biome → one renderer for a biome-defined `OutputKind`. The
- * `outputKind` string MUST be unique across all biomes; the renderer
- * registry refuses to register a duplicate at bootstrap (fail-fast,
- * surfaced in the dev console + biome admin UI).
- *
- * The `render` factory mirrors `RouteContribution.element` /
- * `PanelContribution.render` — typed as a thunk so the host can defer
- * import-cost until the renderer actually fires.
- */
-export interface OutputRendererContribution {
-  /**
-   * The artifact `OutputKind` this renderer handles. Free-form string
-   * because biome-defined kinds are not in the built-in enum; the
-   * registry validates it doesn't collide with a built-in kind at
-   * registration time.
-   */
-  readonly outputKind: string;
-  /**
-   * React component that renders the artifact body inside `<OutputCard>`.
-   * Receives the resolved `OutputItem` as a prop. Biomes import the
-   * `OutputRendererProps` type from
-   * `submodules/xema-host-web/src/components/outputs/renderer-registry.tsx`
-   * (re-exported through the host's biome SDK barrel).
-   */
-  readonly render: () => ComponentType<{ readonly output: unknown }>;
-}
-
-/**
- * Biome module export contract. Each biome's entry module exports a
- * default function of this shape; the host bootstrap calls it with its
- * concrete `HostBridge` implementation, then registers the returned
- * `FrontendBiome` with `biomeRegistry`.
- *
- * This factory shape keeps biome code free of any direct dependency
- * on host-shell primitives (router, auth client, toast library), which
- * is what allows the same biome package to load into one host runtime
- * today and a different host runtime tomorrow.
- */
-export type FrontendBiomeFactory = (bridge: HostBridge) => FrontendBiome;