@ultimat3/admin 1.0.0

package/src/layout.tsx

@@ -0,0 +1,104 @@
+// The admin shell: skip link, header, permission-filtered nav, main region. Landmarks and a
+// visible focus order are the accessibility contract; the theme attributes come from the
+// token system, so nothing here knows a colour.
+
+import { type Locale, registeredLocales, t } from '@ultimat3/i18n';
+import { LocaleSwitcher, ThemeToggle } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import type { AdminApp } from './admin';
+import type { NavGroup } from './nav';
+
+export interface AdminLayoutProps {
+  readonly app: AdminApp;
+  /** Already filtered by `app.navFor(ctx)`. The layout does not decide visibility. */
+  readonly nav: readonly NavGroup[];
+  readonly currentPath: string;
+  readonly onSearch?: (term: string) => void;
+  readonly onLocaleChange?: (locale: Locale) => void;
+  readonly children: JSX.Element;
+}
+
+export function AdminLayout(props: AdminLayoutProps): JSX.Element {
+  const theme = props.app.theme;
+  return (
+    <div
+      class="x-admin"
+      data-theme={theme['data-theme']}
+      data-density={theme['data-density']}
+      style={theme.style}
+    >
+      <a class="x-admin-skip" href="#x-admin-main">
+        {t('admin.a11y.skip-to-content')}
+      </a>
+
+      <header class="x-admin-header">
+        <a class="x-admin-brand" href={props.app.basePath}>
+          {props.app.branding.logo === undefined ? null : (
+            <img
+              src={props.app.branding.logo.src}
+              alt={t(props.app.branding.logo.altKey)}
+              width={props.app.branding.logo.width ?? 24}
+            />
+          )}
+          <span>{t(props.app.branding.nameKey)}</span>
+        </a>
+
+        <search class="x-admin-search">
+          <form
+            onSubmit={(event: SubmitEvent) => {
+              event.preventDefault();
+              const field = (event.currentTarget as HTMLFormElement).elements.namedItem('term');
+              props.onSearch?.(field instanceof HTMLInputElement ? field.value : '');
+            }}
+          >
+            <label class="x-admin-visually-hidden" for="x-admin-search-input">
+              {t('admin.search.label')}
+            </label>
+            <input
+              id="x-admin-search-input"
+              name="term"
+              type="search"
+              placeholder={t('admin.search.placeholder')}
+            />
+          </form>
+        </search>
+
+        <div class="x-admin-header-tools">
+          {/* The locales with a catalog: an option nobody translated is a broken page. */}
+          <LocaleSwitcher locales={registeredLocales()} onLocaleChange={props.onLocaleChange} />
+          <ThemeToggle />
+        </div>
+      </header>
+
+      <div class="x-admin-body">
+        <nav class="x-admin-nav" aria-label={t('admin.nav.label')}>
+          {props.nav.map((group) => (
+            <section>
+              <h2>{t(group.labelKey)}</h2>
+              <ul>
+                {group.items.map((item) => (
+                  <li>
+                    <a
+                      href={`${props.app.basePath}${item.href}`}
+                      aria-current={
+                        props.currentPath === `${props.app.basePath}${item.href}`
+                          ? 'page'
+                          : undefined
+                      }
+                    >
+                      {t(item.labelKey)}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </nav>
+
+        <main id="x-admin-main" class="x-admin-main" tabindex={-1}>
+          {props.children}
+        </main>
+      </div>
+    </div>
+  );
+}

package/src/list.tsx

@@ -0,0 +1,120 @@
+// The list view: derived columns, keyset pagination, and the three states a table actually
+// has (loading, empty, error) instead of the one it usually ships with. Prev/Next are the
+// only navigation — there is no page number, because there is no offset.
+
+import { t } from '@ultimat3/i18n';
+import { Card, DataTable, ErrorState } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import { AdminActions } from './actions';
+import type { AdminActor, AdminAuthz } from './authz';
+import { type AdminErrorParts, adminErrorFrom } from './errors';
+import type { AdminPage } from './pagination';
+import type { AdminRow, AdminSort } from './registry';
+import { rowId } from './registry';
+import type { AdminResource } from './resource';
+import type { WidgetContext } from './widget-value';
+import { Widget } from './widgets';
+
+export interface AdminListProps<Row extends AdminRow> {
+  readonly resource: AdminResource<Row>;
+  readonly page: AdminPage<Row> | null;
+  readonly loading: boolean;
+  readonly error: AdminErrorParts | null;
+  readonly ctx: WidgetContext;
+  readonly actor: AdminActor;
+  readonly authz: AdminAuthz;
+  readonly basePath: string;
+  readonly onCursor: (cursor: string | null) => void;
+  readonly onOpen: (id: string) => void;
+  /** Absent means the table renders its current order without sortable headers. */
+  readonly onSort?: (sort: AdminSort) => void;
+}
+
+export function AdminList<Row extends AdminRow>(props: AdminListProps<Row>): JSX.Element {
+  const href = (id: string): string => `${props.basePath}${props.resource.path}/${id}`;
+  const idOf = (row: Row): string => rowId(row, props.resource.idField);
+
+  if (props.error !== null) {
+    return <ErrorState error={adminErrorFrom(props.error)} />;
+  }
+
+  if (props.loading || props.page === null) {
+    return (
+      <Card header={<h2>{t(props.resource.titleKey)}</h2>}>
+        <p aria-busy="true">{t('admin.list.loading')}</p>
+      </Card>
+    );
+  }
+
+  const page = props.page;
+
+  return (
+    <Card header={<h2>{t(props.resource.titleKey)}</h2>}>
+      <AdminActions
+        actions={props.resource.actions}
+        actor={props.actor}
+        authz={props.authz}
+        subject={{ entity: props.resource.name }}
+        onRun={() => props.onCursor(null)}
+      />
+
+      {page.rows.length === 0 ? (
+        <p class="x-admin-empty">{t('admin.list.empty')}</p>
+      ) : (
+        <DataTable
+          caption={t(props.resource.titleKey)}
+          columns={[
+            // A real link, not a row click handler: the detail view has to survive a
+            // middle-click, a keyboard, and a crawler that never runs the onClick.
+            {
+              key: 'open',
+              header: t('admin.list.open'),
+              cell: (row: Row) => (
+                <a
+                  href={href(idOf(row))}
+                  onClick={(event) => {
+                    event.preventDefault();
+                    props.onOpen(idOf(row));
+                  }}
+                >
+                  {idOf(row)}
+                </a>
+              ),
+            },
+            ...props.resource.listFields.map((field) => ({
+              key: field.name,
+              header: t(field.labelKey),
+              sortable: field.sortable && props.onSort !== undefined,
+              cell: (row: Row) => (
+                <Widget field={field} value={row[field.name]} ctx={props.ctx} mode="read" />
+              ),
+            })),
+          ]}
+          rows={page.rows}
+          rowKey={idOf}
+          sort={{ key: page.sort.field, direction: page.sort.direction }}
+          onSortChange={(next) => {
+            if (next !== undefined) props.onSort?.({ field: next.key, direction: next.direction });
+          }}
+        />
+      )}
+
+      <nav class="x-admin-pager" aria-label={t('admin.list.pagination')}>
+        <button
+          type="button"
+          disabled={page.prevCursor === null}
+          onClick={() => props.onCursor(page.prevCursor)}
+        >
+          {t('admin.list.previous')}
+        </button>
+        <button
+          type="button"
+          disabled={!page.hasMore}
+          onClick={() => props.onCursor(page.nextCursor)}
+        >
+          {t('admin.list.next')}
+        </button>
+      </nav>
+    </Card>
+  );
+}

package/src/mcp-tools.ts

@@ -0,0 +1,201 @@
+// The admin's MCP surface, derived from the same resources and actions the UI renders and
+// gated by the same authz. An agent therefore sees exactly the tools its actor could have
+// clicked — no more, and never a tool whose call would then 403.
+//
+// Tool descriptions are literal English on purpose: they are protocol payload read by a
+// model, not UI copy read by a person, so they are not `t()` keys.
+
+import { decideAction, permissionsForAction } from './action-gate';
+import type { AdminApp } from './admin';
+import { type AdminDecision, decideAll } from './authz';
+import { type CrudCtx, decideOperation, permissionsForOperation } from './crud';
+import type { AdminFieldType } from './fields';
+import type { AdminOperation } from './permissions';
+import type { AdminResource } from './resource';
+
+export type AdminToolKind = 'list' | 'read' | 'search' | 'create' | 'update' | 'delete' | 'action';
+
+export interface AdminToolField {
+  readonly name: string;
+  readonly type: AdminFieldType;
+  readonly required: boolean;
+}
+
+export interface AdminMcpTool {
+  /** `admin.<entity>.<kind>`, or `admin.action.<name>`. Stable: agents cache tool names. */
+  readonly name: string;
+  readonly kind: AdminToolKind;
+  readonly description: string;
+  readonly entity: string | null;
+  readonly action: string | null;
+  readonly permissions: readonly string[];
+  /** Destructive tools require the confirmation token; agents must read before they delete. */
+  readonly destructive: boolean;
+  readonly input: readonly AdminToolField[];
+}
+
+const CURSOR_FIELD: AdminToolField = { name: 'cursor', type: 'text', required: false };
+const ID_FIELD: AdminToolField = { name: 'id', type: 'text', required: true };
+
+const formFields = (resource: AdminResource): readonly AdminToolField[] =>
+  resource.formFields.map((field) => ({
+    name: field.name,
+    type: field.type,
+    required: field.required,
+  }));
+
+function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | null {
+  switch (op) {
+    case 'list':
+      return {
+        name: `admin.${resource.name}.list`,
+        kind: 'list',
+        description: `List ${resource.name} rows, cursor-paginated, newest first.`,
+        entity: resource.name,
+        action: null,
+        permissions: permissionsForOperation(resource.name, 'list'),
+        destructive: false,
+        input: [CURSOR_FIELD, { name: 'limit', type: 'number', required: false }],
+      };
+    case 'detail':
+      return {
+        name: `admin.${resource.name}.read`,
+        kind: 'read',
+        description: `Read one ${resource.name} row by id.`,
+        entity: resource.name,
+        action: null,
+        permissions: permissionsForOperation(resource.name, 'detail'),
+        destructive: false,
+        input: [ID_FIELD],
+      };
+    case 'create':
+      return {
+        name: `admin.${resource.name}.create`,
+        kind: 'create',
+        description: `Create a ${resource.name} row. Validated by the entity's schema.`,
+        entity: resource.name,
+        action: null,
+        permissions: permissionsForOperation(resource.name, 'create'),
+        destructive: false,
+        input: formFields(resource),
+      };
+    case 'update':
+      return {
+        name: `admin.${resource.name}.update`,
+        kind: 'update',
+        description: `Update fields of one ${resource.name} row.`,
+        entity: resource.name,
+        action: null,
+        permissions: permissionsForOperation(resource.name, 'update'),
+        destructive: false,
+        input: [ID_FIELD, ...formFields(resource)],
+      };
+    case 'delete':
+      return {
+        name: `admin.${resource.name}.delete`,
+        kind: 'delete',
+        description: `Delete one ${resource.name} row. Requires confirmation "<entity>:<id>".`,
+        entity: resource.name,
+        action: null,
+        permissions: permissionsForOperation(resource.name, 'delete'),
+        destructive: true,
+        input: [ID_FIELD, { name: 'confirmation', type: 'text', required: true }],
+      };
+    case 'search':
+      return null;
+  }
+}
+
+/** One exposable tool and the decision that gates it, for whichever actor asks. */
+interface ToolGate {
+  readonly tool: AdminMcpTool;
+  gate(ctx: CrudCtx): AdminDecision;
+}
+
+/**
+ * The catalog and its gates, derived once. Two callers need different halves of it — the
+ * transport needs every tool's name and schema before any caller exists, an actor needs the
+ * subset it may call — and they must not be two derivations that can disagree.
+ */
+function toolGates(app: AdminApp): readonly ToolGate[] {
+  const out: ToolGate[] = [];
+
+  for (const resource of app.resources) {
+    for (const op of resource.operations) {
+      const tool = toolFor(resource, op);
+      if (tool === null) continue;
+      out.push({ tool, gate: (ctx) => decideOperation(resource, op, ctx) });
+    }
+    for (const action of resource.actions) {
+      if (action.mcp?.expose === false) continue;
+      out.push({
+        tool: {
+          name: `admin.action.${action.name}`,
+          kind: 'action',
+          description: action.mcp?.description ?? `Run the ${action.name} action.`,
+          entity: action.entity ?? null,
+          action: action.name,
+          permissions: permissionsForAction(action),
+          destructive: action.destructive === true,
+          input: [],
+        },
+        gate: (ctx) => decideAction(action, ctx.actor, ctx.authz),
+      });
+    }
+  }
+
+  // Search is one tool over every resource, not one per entity: an agent looking for a row
+  // should not have to fan out over the registry itself.
+  out.push({
+    tool: {
+      name: 'admin.search',
+      kind: 'search',
+      description: 'Search every readable entity by its text fields. Returns ids and labels.',
+      entity: null,
+      action: null,
+      permissions: permissionsForOperation('admin', 'search'),
+      destructive: false,
+      input: [{ name: 'term', type: 'text', required: true }],
+    },
+    gate: (ctx) => decideAll(ctx.authz, permissionsForOperation('admin', 'search'), ctx.actor),
+  });
+
+  for (const action of app.globalActions) {
+    if (action.mcp?.expose === false) continue;
+    out.push({
+      tool: {
+        name: `admin.action.${action.name}`,
+        kind: 'action',
+        description: action.mcp?.description ?? `Run the ${action.name} action.`,
+        entity: null,
+        action: action.name,
+        permissions: permissionsForAction(action),
+        destructive: action.destructive === true,
+        input: [],
+      },
+      gate: (ctx) => decideAction(action, ctx.actor, ctx.authz),
+    });
+  }
+
+  return out;
+}
+
+/** Every tool the surface could expose, ungated. The transport's `tools/list` payload. */
+export function adminToolCatalog(app: AdminApp): readonly AdminMcpTool[] {
+  return toolGates(app).map(({ tool }) => tool);
+}
+
+/** Every tool the surface could expose, each with the decision that would gate it. */
+export function adminToolDecisions(
+  app: AdminApp,
+  ctx: CrudCtx,
+): readonly { readonly tool: AdminMcpTool; readonly decision: AdminDecision }[] {
+  return toolGates(app).map(({ tool, gate }) => ({ tool, decision: gate(ctx) }));
+}
+
+/** The tools this actor may call. The UI's visibility rule, applied to the MCP surface. */
+export function adminMcpTools(app: AdminApp, ctx: CrudCtx): readonly AdminMcpTool[] {
+  return adminToolDecisions(app, ctx)
+    .filter(({ decision }) => decision.allowed)
+    .map(({ tool }) => tool);
+}