@ultimat3/admin 1.0.0

package/src/policy-bridge.ts

@@ -0,0 +1,64 @@
+// The ONLY place the admin talks to @ultimat3/policy. Everything else in the package depends
+// on the `AdminAuthz` interface, so there is exactly one adaptation point between the app's
+// policies and the dashboard — and no second authz implementation can grow next to it.
+
+import { type Actor, userActor } from '@ultimat3/core';
+import { definePermissions, evaluate, type Policy } from '@ultimat3/policy';
+import { type AdminActor, type AdminAuthz, type AdminDecision, allowed, denied } from './authz';
+import { ADMIN_PERMISSIONS } from './permissions';
+
+/** The admin's own permission set, registered with the policy layer at import time. */
+export const adminPermissions = definePermissions(ADMIN_PERMISSIONS);
+
+/**
+ * The admin carries its own actor shape; @ultimat3/policy evaluates core's `Actor`. The
+ * mapping lives here because this file is the only one allowed to speak to the policy layer.
+ */
+const policyActor = (actor: AdminActor): Actor =>
+  userActor({ id: actor.id, roles: actor.roles ?? [] });
+
+/**
+ * `evaluate()`'s result is read structurally: the policy layer owns its own decision type,
+ * and the admin only needs the verdict, a reason key, and the trace it prints in `/_x`.
+ */
+function readDecision(permission: string, result: unknown): AdminDecision {
+  const bag = (typeof result === 'object' && result !== null ? result : {}) as {
+    allowed?: unknown;
+    reason?: unknown;
+    trace?: unknown;
+  };
+  const verdict = result === true || bag.allowed === true;
+  const reason = typeof bag.reason === 'string' ? bag.reason : 'admin.policy.evaluated';
+  const trace = Array.isArray(bag.trace) ? bag.trace.map((line) => String(line)) : [];
+  return verdict ? allowed(permission, reason, trace) : denied(permission, reason, trace);
+}
+
+export interface PolicyAuthzInput {
+  /** Permission name → the policy that decides it. `describeActions()` supplies these. */
+  readonly policies: Readonly<Record<string, Policy>>;
+}
+
+/**
+ * Closed by default: a permission with no registered policy is denied, with the fix in the
+ * trace. An admin that fails open is worse than an admin that fails visibly.
+ */
+export function policyAuthz(input: PolicyAuthzInput): AdminAuthz {
+  return {
+    decide({ permission, actor, subject }): AdminDecision {
+      const policy = input.policies[permission];
+      if (policy === undefined) {
+        return denied(permission, 'admin.policy.missing', [
+          `no policy registered for "${permission}"`,
+          `fix: definePermissions({ '${permission}': … }) or can('${permission}') on the action`,
+        ]);
+      }
+      // `EvaluateArgs` carries exactly one payload. An admin subject with no action input IS
+      // that payload: a row-level rule has nothing but the entity and id to decide on.
+      const payload = subject?.input ?? subject;
+      return readDecision(
+        permission,
+        evaluate(policy, { actor: policyActor(actor), input: payload }),
+      );
+    },
+  };
+}

package/src/registry.ts

@@ -0,0 +1,181 @@
+// The structural subset of a registered entity the admin reads, and the query IR it speaks.
+//
+// WHY a subset instead of importing `Entity` itself: the admin must keep deriving after an
+// entity gains a column kind it has never heard of, so the surface is named — `$columns`,
+// `$primaryKey`, `$describe()` — and one file changes when it grows. `RegisteredEntity` below
+// is the compile-time proof that a real `entity()` result satisfies it; it is checked by
+// `tsc`, not asserted in a comment, because the admin used to read fields no entity had.
+
+import type { Entity, Repo } from '@ultimat3/entity';
+
+/**
+ * What the author declared about one column — `@ultimat3/entity`'s `ColumnMeta`, narrowed to
+ * what the admin reads. `kind` stays `string`: a kind with no widget is a loud
+ * X_ADMIN_FIELD_UNSUPPORTED at derive time, never a type error in the app that declared it.
+ */
+export interface AdminColumnMeta {
+  /** `uuid` · `text` · `char` · `boolean` · `integer` · `bigint` · `timestamptz` · `jsonb` · `money`. */
+  readonly kind: string;
+  readonly notNull: boolean;
+  readonly primaryKey: boolean;
+  readonly unique: boolean;
+  /** Indexed columns become the list filters — a filter with no index is a table scan. */
+  readonly index: boolean;
+  /** Declared max length. A bounded string is one line; an unbounded one is prose. */
+  readonly length?: number;
+  /** A closed set — `enumerated`, `locale`, `tz`. Forces the `select` widget. */
+  readonly values?: readonly string[];
+  /**
+   * `kind: 'generated'` means the DB or the framework writes it (`id`, `createdAt`), which is
+   * what makes a field read-only. A literal `.default('free')` is a starting value, not that.
+   */
+  readonly default?: { readonly kind: string };
+  readonly onUpdate?: { readonly kind: string };
+  /**
+   * A thunk, because schema modules import each other in a cycle. The admin never calls it —
+   * the column→entity binding that resolves it is private to @ultimat3/entity, so `$describe()`
+   * hands back the resolved target — but its presence is what makes the column a foreign key.
+   */
+  readonly references?: () => unknown;
+}
+
+/** One column of a registered entity. An `@ultimat3/entity` `Column` satisfies this. */
+export interface AdminColumn {
+  readonly $meta: AdminColumnMeta;
+}
+
+/** One column of `$describe()` output. Money is the one property that becomes two of these. */
+export interface AdminColumnDescription {
+  /** The property key on the row, which is what the admin renders and filters by. */
+  readonly property: string;
+  /** `"<entity>.<column>"` for a foreign key, else `null`. Already resolved. */
+  readonly references: string | null;
+}
+
+/** The plain-data projection of an entity. The admin reads it for FK targets only. */
+export interface AdminEntityDescription {
+  readonly columns: readonly AdminColumnDescription[];
+}
+
+export interface AdminEntity {
+  readonly $name: string;
+  /** Property keys of the primary key. Composite for a join table; the admin addresses rows
+   * by the first, which is the only column a single-id URL and an `AdminRepo` can carry. */
+  readonly $primaryKey: readonly string[];
+  readonly $columns: Readonly<Record<string, AdminColumn>>;
+  /** The Standard Schema the entity validates with; forms hand input straight to it. */
+  readonly $schema: unknown;
+  /** Resolves foreign-key targets. See `entity-columns.ts` for what the admin takes from it. */
+  $describe(): AdminEntityDescription;
+}
+
+/** `T` must satisfy `Surface` or this does not compile. The whole point of the two below. */
+type Satisfies<Surface, T extends Surface> = T;
+
+/**
+ * The claim, checked: a real `entity()` result IS an `AdminEntity`. The day `entity()` renames
+ * a member, `tsc` fails here — instead of `Object.keys(entity.columns)` failing in the first
+ * request the dashboard serves.
+ */
+export type RegisteredEntity = Satisfies<AdminEntity, Entity<AdminRow>>;
+
+/**
+ * A repo as `@ultimat3/entity` registers it — deliberately NOT claimed to be an `AdminRepo`:
+ * the verbs differ (`findMany`/`insert` vs `list`/`create`) and its cursor is an opaque signed
+ * string where the admin speaks a keyset bound, so the host binds an adapter over it.
+ */
+export type RegisteredRepo = Repo;
+
+export type FilterOp = 'eq' | 'neq' | 'contains' | 'gt' | 'lt' | 'in' | 'is-null';
+
+export interface AdminFilter {
+  readonly field: string;
+  readonly op: FilterOp;
+  readonly value: string | number | boolean | null | readonly string[];
+}
+
+export interface AdminSort {
+  readonly field: string;
+  readonly direction: 'asc' | 'desc';
+}
+
+export interface KeysetBound {
+  readonly field: string;
+  readonly value: string;
+  readonly id: string;
+}
+
+/**
+ * The read query the admin sends a repo. There is no `offset` and there never will be:
+ * offset pagination re-scans on every page and skips rows when the table is written to
+ * while an operator is paging through it.
+ */
+export interface AdminListQuery {
+  readonly where?: readonly AdminFilter[];
+  readonly sort: AdminSort;
+  /** Rows to return. The repo is asked for `limit + 1` to detect a next page. */
+  readonly limit: number;
+  /**
+   * Keyset bound: the sort-field value of the last row of the previous page, plus that
+   * row's id as the tie-break so pages stay stable when the sort column has duplicates.
+   */
+  readonly after?: KeysetBound;
+  readonly before?: KeysetBound;
+}
+
+export interface AdminRepo<Row> {
+  list(query: AdminListQuery): Promise<readonly Row[]>;
+  find(id: string): Promise<Row | null>;
+  create(input: Readonly<Record<string, unknown>>): Promise<Row>;
+  update(id: string, patch: Readonly<Record<string, unknown>>): Promise<Row>;
+  destroy(id: string): Promise<void>;
+  count?(where?: readonly AdminFilter[]): Promise<number>;
+}
+
+/** What the admin runs an action with. The action's own `ctx` is richer; this is the slice
+ * the admin can honestly provide from an HTTP request or an MCP call. */
+export interface AdminActionCtx {
+  readonly requestId: string;
+  readonly actorId: string;
+  readonly locale: string;
+  readonly timeZone: string;
+}
+
+/**
+ * A registered `action` as the admin surfaces it. `permission` is not optional: an action
+ * with no policy is an open door, and the admin refuses to render one
+ * (X_ADMIN_POLICY_MISSING).
+ */
+export interface AdminAction<Input = Readonly<Record<string, unknown>>, Output = unknown> {
+  readonly name: string;
+  readonly permission: string;
+  /** The entity the button belongs to. Absent = a global action in the toolbar. */
+  readonly entity?: string;
+  readonly destructive?: boolean;
+  readonly labelKey?: string;
+  /** Mirrors the action's own `mcp` block; the admin MCP surface honours `expose`. */
+  readonly mcp?: { readonly expose?: boolean; readonly description?: string };
+  /** The action's Standard Schema, handed to the form and to the MCP tool definition. */
+  readonly input?: unknown;
+  handle(args: { input: Input; ctx: AdminActionCtx }): Promise<Output>;
+}
+
+/** A registered `job` as the admin's Jobs page needs it — `describeJobs()` output. */
+export interface AdminJobSummary {
+  readonly name: string;
+  readonly queue?: string;
+  readonly steps?: readonly string[];
+  readonly retry?: { readonly attempts: number; readonly backoff: string };
+}
+
+/** A row as the admin handles it: an opaque record it reads fields out of by name. */
+export type AdminRow = Readonly<Record<string, unknown>>;
+
+export function readField(row: AdminRow, field: string): unknown {
+  return row[field];
+}
+
+export function rowId(row: AdminRow, idField: string): string {
+  const value = row[idField];
+  return typeof value === 'string' ? value : String(value ?? '');
+}

package/src/resource.ts

@@ -0,0 +1,321 @@
+// Entity registry → a working CRUD resource, with nothing configured. Columns become
+// fields, indexed columns become filters, text columns become search, `createdAt` becomes
+// the default sort, i18n keys become labels. Every derived decision is overridable per
+// field, but the zero-config result is the one the generator emits and the one the docs show.
+
+import { type AdminColumnFacts, adminColumnsOf } from './entity-columns';
+import {
+  AdminEntityUnknownError,
+  AdminFieldUnsupportedError,
+  AdminPolicyMissingError,
+} from './errors';
+import {
+  type AdminField,
+  type AdminFieldType,
+  type AdminWidget,
+  fieldTypeFromColumn,
+  filterable,
+  listable,
+  searchable,
+  sortable,
+  widgetFor,
+} from './fields';
+import { ADMIN_OPERATIONS, type AdminOperation } from './permissions';
+import type { AdminAction, AdminEntity, AdminRepo, AdminRow, AdminSort } from './registry';
+
+/** Six columns is what fits a laptop viewport without horizontal scroll. */
+const MAX_LIST_FIELDS = 6;
+const DEFAULT_PAGE_SIZE = 25;
+const LABEL_CANDIDATES = ['name', 'title', 'slug', 'label', 'email'] as const;
+const SORT_CANDIDATES = ['createdAt', 'created_at', 'updatedAt', 'updated_at'] as const;
+
+export interface AdminFieldOverride {
+  readonly type?: AdminFieldType;
+  readonly widget?: AdminWidget;
+  readonly labelKey?: string;
+  /** Out of every surface: list, detail, form, MCP schema. */
+  readonly hidden?: boolean;
+  readonly inList?: boolean;
+  readonly readOnly?: boolean;
+  readonly required?: boolean;
+  readonly sensitive?: boolean;
+  readonly filterable?: boolean;
+  readonly sortable?: boolean;
+  readonly searchable?: boolean;
+  readonly currency?: string;
+  readonly values?: readonly string[];
+  readonly relation?: { readonly entity: string; readonly labelField?: string };
+}
+
+export interface AdminResourceOptions<Row extends AdminRow = AdminRow> {
+  readonly repo?: AdminRepo<Row>;
+  readonly path?: string;
+  readonly titleKey?: string;
+  readonly group?: string;
+  /**
+   * The field that names a row in a reference widget, a search hit, a breadcrumb. An entity
+   * declares no such thing, so this is the only way to say it out loud; omitted, it is derived
+   * from the conventional names below.
+   */
+  readonly labelField?: string;
+  readonly fields?: Readonly<Record<string, AdminFieldOverride>>;
+  /** Explicit list columns, in order. Omit to let the derivation pick. */
+  readonly listFields?: readonly string[];
+  readonly defaultSort?: AdminSort;
+  readonly pageSize?: number;
+  readonly operations?: readonly AdminOperation[];
+  readonly actions?: readonly AdminAction[];
+}
+
+export interface AdminResource<Row extends AdminRow = AdminRow> {
+  readonly name: string;
+  /** Mount-relative, e.g. `/posts`. */
+  readonly path: string;
+  readonly titleKey: string;
+  readonly group: string;
+  readonly idField: string;
+  /** The column that names a row in a reference widget, a search hit, or a breadcrumb. */
+  readonly labelField: string;
+  readonly entity: AdminEntity;
+  readonly fields: readonly AdminField[];
+  readonly listFields: readonly AdminField[];
+  readonly formFields: readonly AdminField[];
+  readonly filters: readonly AdminField[];
+  readonly searchFields: readonly AdminField[];
+  readonly defaultSort: AdminSort;
+  readonly pageSize: number;
+  readonly operations: readonly AdminOperation[];
+  readonly actions: readonly AdminAction[];
+  readonly repo?: AdminRepo<Row>;
+  field(name: string): AdminField;
+}
+
+const pluralize = (name: string): string => {
+  if (/[sxz]$/.test(name) || /(ch|sh)$/.test(name)) return `${name}es`;
+  if (/[^aeiou]y$/.test(name)) return `${name.slice(0, -1)}ies`;
+  return `${name}s`;
+};
+
+function deriveField(
+  entity: AdminEntity,
+  column: AdminColumnFacts,
+  override: AdminFieldOverride | undefined,
+): AdminField {
+  const name = column.name;
+  const type = override?.type ?? fieldTypeFromColumn(entity.$name, name, column);
+  const widget = override?.widget ?? widgetFor(type);
+  const generated = column.generated || column.primaryKey;
+  // An entity has no notion of a secret column, and a currency belongs to the value rather
+  // than the column, so both are admin-side declarations or they are absent. Never guessed.
+  const sensitive = override?.sensitive ?? false;
+  const currency = override?.currency;
+  const values = override?.values ?? column.values;
+  const relation =
+    override?.relation ??
+    // The FK's value IS the target column's value, so that column is the honest default label.
+    (column.references === undefined
+      ? undefined
+      : { entity: column.references.entity, labelField: column.references.column });
+
+  return {
+    entity: entity.$name,
+    name,
+    type,
+    widget,
+    labelKey: override?.labelKey ?? `admin.${entity.$name}.field.${name}`,
+    required: override?.required ?? (!column.nullable && !generated),
+    readOnly: override?.readOnly ?? generated,
+    sensitive,
+    inList: override?.inList ?? (listable(type) && !sensitive),
+    filterable: override?.filterable ?? filterable(type, column),
+    sortable: override?.sortable ?? sortable(type, column),
+    // Generated columns are excluded from search: an id is found by exact lookup, and a
+    // `contains` over a uuid column is a scan that returns nothing useful.
+    searchable: override?.searchable ?? (searchable(type) && !sensitive && !generated),
+    ...(values === undefined ? {} : { values }),
+    ...(currency === undefined ? {} : { currency }),
+    ...(relation === undefined ? {} : { relation }),
+  };
+}
+
+/**
+ * The declared key wins — but a composite one is refused outright, never silently reduced to
+ * its first member: a route id and an `AdminRepo` id both carry exactly one string, so two rows
+ * sharing only that first member would become indistinguishable for read, update and delete.
+ */
+function idFieldOf(entity: AdminEntity, columns: readonly AdminColumnFacts[]): string {
+  if (entity.$primaryKey.length > 1) {
+    throw new AdminFieldUnsupportedError({
+      entity: entity.$name,
+      field: entity.$primaryKey.join(','),
+      cause:
+        'has a composite primary key; the admin addresses a row by a single id and cannot yet carry every key part',
+      fix: 'give the entity a single-column id, or wait for composite-key support in AdminRepo',
+    });
+  }
+  const declared = entity.$primaryKey[0] ?? columns.find((column) => column.primaryKey)?.name;
+  if (declared !== undefined) return declared;
+  if (columns.some((column) => column.name === 'id')) return 'id';
+  throw new AdminEntityUnknownError({
+    entity: entity.$name,
+    known: columns.map((column) => column.name),
+    cause: `entity "${entity.$name}" has no primary key and no "id" column, so the admin cannot address a row`,
+  });
+}
+
+function labelFieldOf(
+  entity: AdminEntity,
+  fields: readonly AdminField[],
+  idField: string,
+  declared: string | undefined,
+): string {
+  if (declared !== undefined) {
+    // A label nobody can read is a table of ids and a search that returns them: say so here,
+    // not by silently falling back to the id column three surfaces later.
+    if (!fields.some((field) => field.name === declared)) {
+      throw new AdminFieldUnsupportedError({
+        entity: entity.$name,
+        field: declared,
+        cause: 'named as labelField but not a visible field of this resource',
+        fix: `adminResource(${entity.$name}, { labelField: '${idField}' })   # a field that is not hidden`,
+      });
+    }
+    return declared;
+  }
+  for (const candidate of LABEL_CANDIDATES) {
+    if (fields.some((field) => field.name === candidate)) return candidate;
+  }
+  const firstText = fields.find(
+    (field) => (field.type === 'text' || field.type === 'textarea') && field.name !== idField,
+  );
+  return firstText?.name ?? idField;
+}
+
+function defaultSortOf(fields: readonly AdminField[], idField: string): AdminSort {
+  for (const candidate of SORT_CANDIDATES) {
+    const field = fields.find((f) => f.name === candidate && f.sortable);
+    if (field !== undefined) return { field: field.name, direction: 'desc' };
+  }
+  return { field: idField, direction: 'desc' };
+}
+
+function pickListFields(
+  fields: readonly AdminField[],
+  labelField: string,
+  explicit: readonly string[] | undefined,
+  entityName: string,
+): readonly AdminField[] {
+  if (explicit !== undefined) {
+    return explicit.map((name) => {
+      const field = fields.find((f) => f.name === name);
+      if (field === undefined) {
+        throw new AdminFieldUnsupportedError({
+          entity: entityName,
+          field: name,
+          cause: 'listed in listFields but not a column of the entity',
+          fix: `remove "${name}" from listFields, or add the column with x g migration`,
+        });
+      }
+      return field;
+    });
+  }
+  const label = fields.filter((field) => field.name === labelField);
+  const rest = fields.filter((field) => field.inList && field.name !== labelField);
+  return [...label, ...rest].slice(0, MAX_LIST_FIELDS);
+}
+
+function assertActionsHavePolicies(actions: readonly AdminAction[]): void {
+  for (const action of actions) {
+    // Widened because the registry is JSON at the boundary: a hand-written action object
+    // that forgot `policy` reaches us with the field absent, not just empty.
+    const permission: string | undefined = action.permission;
+    if (permission === undefined || permission.trim() === '') {
+      throw new AdminPolicyMissingError({ subject: action.name, kind: 'action' });
+    }
+  }
+}
+
+/** Derive list / detail / create / edit / delete from one registered entity. */
+export function adminResource<Row extends AdminRow = AdminRow>(
+  entity: AdminEntity,
+  opts: AdminResourceOptions<Row> = {},
+): AdminResource<Row> {
+  const columns = adminColumnsOf(entity);
+  if (columns.length === 0) {
+    throw new AdminEntityUnknownError({
+      entity: entity.$name,
+      known: [],
+      cause: `entity "${entity.$name}" declares no columns`,
+    });
+  }
+
+  const idField = idFieldOf(entity, columns);
+  const overrides = opts.fields ?? {};
+  const fields = columns
+    .filter((column) => overrides[column.name]?.hidden !== true)
+    .map((column) => deriveField(entity, column, overrides[column.name]));
+
+  const labelField = labelFieldOf(entity, fields, idField, opts.labelField);
+  const actions = opts.actions ?? [];
+  assertActionsHavePolicies(actions);
+
+  const resource: AdminResource<Row> = {
+    name: entity.$name,
+    path: opts.path ?? `/${pluralize(entity.$name)}`,
+    titleKey: opts.titleKey ?? `admin.${entity.$name}.title`,
+    group: opts.group ?? 'admin.group.data',
+    idField,
+    labelField,
+    entity,
+    fields,
+    listFields: pickListFields(fields, labelField, opts.listFields, entity.$name),
+    formFields: fields.filter((field) => !field.readOnly && !field.sensitive),
+    filters: fields.filter((field) => field.filterable),
+    searchFields: fields.filter((field) => field.searchable),
+    defaultSort: opts.defaultSort ?? defaultSortOf(fields, idField),
+    pageSize: opts.pageSize ?? DEFAULT_PAGE_SIZE,
+    operations: opts.operations ?? ADMIN_OPERATIONS,
+    actions,
+    ...(opts.repo === undefined ? {} : { repo: opts.repo }),
+    field(name: string): AdminField {
+      const field = fields.find((f) => f.name === name);
+      if (field === undefined) {
+        throw new AdminFieldUnsupportedError({
+          entity: entity.$name,
+          field: name,
+          cause: 'not a field of this resource (hidden, or not a column)',
+          fix: `x manifest   # then check adminResource(${entity.$name}).fields`,
+        });
+      }
+      return field;
+    },
+  };
+  return resource;
+}
+
+/** The bound repo, or the one error that says which resource forgot it. */
+export function repoOf<Row extends AdminRow>(resource: AdminResource<Row>): AdminRepo<Row> {
+  if (resource.repo === undefined) {
+    throw new AdminEntityUnknownError({
+      entity: resource.name,
+      known: [],
+      cause: `resource "${resource.name}" has no repo bound, so the admin cannot read or write rows`,
+    });
+  }
+  return resource.repo;
+}
+
+/** Look a resource up by entity name. The only place a name→resource miss is reported. */
+export function resourceFor<Row extends AdminRow = AdminRow>(
+  resources: readonly AdminResource<Row>[],
+  name: string,
+): AdminResource<Row> {
+  const found = resources.find((resource) => resource.name === name);
+  if (found === undefined) {
+    throw new AdminEntityUnknownError({
+      entity: name,
+      known: resources.map((resource) => resource.name),
+    });
+  }
+  return found;
+}

package/src/routes.ts

@@ -0,0 +1,35 @@
+// The one bridge from the admin's route table to @ultimat3/render. Every admin page is
+// `spa`: it is behind auth, so there is nothing to prerender and nothing a CDN may hold —
+// and `network-only` keeps a stale org's rows out of a service worker cache.
+
+import { t } from '@ultimat3/i18n';
+import { defineRoute } from '@ultimat3/render';
+import type { AdminApp, AdminRoute } from './admin';
+
+export interface AdminRouteConfig {
+  readonly path: string;
+  readonly view: AdminRoute['view'];
+  readonly entity: string | null;
+  readonly permissions: readonly string[];
+  readonly config: ReturnType<typeof defineRoute>;
+}
+
+export function adminRouteConfig(route: AdminRoute): AdminRouteConfig {
+  return {
+    path: route.path,
+    view: route.view,
+    entity: route.entity,
+    permissions: route.permissions,
+    config: defineRoute({
+      render: 'spa',
+      offline: 'network-only',
+      hydrate: 'idle',
+      meta: () => ({ title: t(route.titleKey) }),
+    }),
+  };
+}
+
+/** Hand these to the router. Auth stays the host app's: see `AdminApp.auth`. */
+export function adminRoutes(app: AdminApp): readonly AdminRouteConfig[] {
+  return app.routes.map(adminRouteConfig);
+}