@ultimat3/admin 22.15.0 → 24.0.0

package/src/list.tsx

@@ -1,33 +1,46 @@
-// 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.
+// The list view: scope tabs, the filter bar, the batch bar, derived and computed columns, keyset
+// pagination, and the states a server-rendered table has (rows, empty, error). Every control is a
+// link or a native form — a row opens through a real `<a href>`, a header sorts through one,
+// paging is `<Pagination hrefFor>`, a row is selected by a checkbox the batch form owns — so the
+// page ships no script and there is nothing to hydrate.
+// 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 { decideAction } from './action-gate';
 import { AdminActions } from './actions';
 import type { AdminActor, AdminAuthz } from './authz';
+import { AdminBatchBar, BatchCheckbox } from './batch-bar';
 import { type AdminErrorParts, adminErrorFrom } from './errors';
+import { resourceColumns } from './list-columns';
+import { AdminFilterBar } from './list-filter-bar';
+import type { ListLocation } from './list-request';
+import type { AdminListRequest } from './list-scope';
+import { AdminScopeTabs } from './list-scope-tabs';
 import type { AdminPage } from './pagination';
-import type { AdminRow, AdminSort } from './registry';
+import type { AdminRow } from './registry';
 import { rowId } from './registry';
 import type { AdminResource } from './resource';
+import type { AdminScope } from './resource-list';
 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 page: AdminPage<Row>;
   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;
+  /** The list as it was asked for — its scope, filters and sort ride every link on the page. */
+  readonly request: AdminListRequest;
+  /** The scope the page was READ under: the request's, or the resource's default. */
+  readonly scope: AdminScope | null;
+  /** The count of each scope that declared `count: true`, and of no other. */
+  readonly counts: ReadonlyMap<string, number>;
+  /** The URL of one list state — `listHref()`, bound to this admin and this resource. */
+  readonly hrefFor: (location: ListLocation) => string;
 }
 
 export function AdminList<Row extends AdminRow>(props: AdminListProps<Row>): JSX.Element {
@@ -38,83 +51,109 @@ export function AdminList<Row extends AdminRow>(props: AdminListProps<Row>): JSX
     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;
+  // The base `AdminResource`: this component's own `Row` is the app's, the pieces below read rows
+  // as `AdminRow`, and a resource is the same object either way.
+  const resource: AdminResource = props.resource as unknown as AdminResource;
+  const acts = resource.actions.length > 0;
+  const sealed = resource.secretFields.map((field) => field.name);
+  // The batch actions THIS actor may run — the gate's own answer, asked once for the list. A row
+  // the action's `when` excludes is still selectable: the server counts it `refused`, by name.
+  const batch = resource.actions.filter(
+    (action) =>
+      action.batch !== undefined &&
+      decideAction(action, props.actor, props.authz, { entity: resource.name }).allowed,
+  );
+  const { scope, filters, sort } = props.request;
+  /** Everything but the cursor: a cursor is a position IN this state, never part of it. */
+  const state: ListLocation = {
+    ...(scope === undefined ? {} : { scope }),
+    ...(filters === undefined ? {} : { filters }),
+    ...(sort === undefined ? {} : { sort }),
+  };
 
   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)}
+    <Card header={<h2>{t(resource.titleKey)}</h2>}>
+      <AdminScopeTabs
+        resource={resource}
+        active={props.scope}
+        counts={props.counts}
+        locale={props.ctx.locale}
+        hrefFor={(name) => props.hrefFor({ ...state, scope: name })}
       />
-
+      <AdminFilterBar
+        resource={resource}
+        request={props.request}
+        ctx={props.ctx}
+        action={props.hrefFor({})}
+        clearHref={props.hrefFor({
+          ...(scope === undefined ? {} : { scope }),
+          ...(sort === undefined ? {} : { sort }),
+        })}
+        returnTo={props.hrefFor(state)}
+      />
+      <AdminBatchBar actions={batch} href={props.hrefFor(state)} />
       {page.rows.length === 0 ? (
         <p class="x-admin-empty">{t('admin.list.empty')}</p>
       ) : (
         <DataTable
-          caption={t(props.resource.titleKey)}
+          caption={t(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" />
-              ),
-            })),
+            ...(batch.length === 0
+              ? []
+              : [
+                  {
+                    key: 'select',
+                    header: t('admin.batch.select'),
+                    cell: (row: Row) => (
+                      <BatchCheckbox
+                        id={idOf(row)}
+                        label={t('admin.batch.select-row', { id: idOf(row) })}
+                      />
+                    ),
+                  },
+                ]),
+            // The resource's columns, the same ones a related card on another detail page draws.
+            ...resourceColumns({ resource, ctx: props.ctx, hrefOf: href }),
+            // Decided per ROW, with the row on the subject: a rule that reads it (ownership, a
+            // state) answers for this row and not for the table.
+            ...(acts
+              ? [
+                  {
+                    key: 'actions',
+                    header: t('admin.actions.label'),
+                    cell: (row: Row) => (
+                      <AdminActions
+                        actions={resource.actions}
+                        actor={props.actor}
+                        authz={props.authz}
+                        subject={{ entity: resource.name, id: idOf(row), row }}
+                        sealed={sealed}
+                        href={href(idOf(row))}
+                      />
+                    ),
+                  },
+                ]
+              : []),
           ]}
           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 });
+          nextCursor={page.hasMore ? (page.nextCursor ?? undefined) : undefined}
+          prevCursor={page.prevCursor ?? undefined}
+          hrefFor={(cursor) => props.hrefFor({ ...state, cursor })}
+          // The header's NEXT state, as a URL. "Unsorted" is the list with no sort in it — the
+          // resource's own default order.
+          sortHrefFor={(next) => {
+            const { sort: _current, ...rest } = state;
+            return props.hrefFor(
+              next === undefined
+                ? rest
+                : { ...rest, sort: { 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

@@ -11,6 +11,7 @@ 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 { AdminAction } from './registry';
 import type { AdminResource } from './resource';
 
 export type AdminToolKind = 'list' | 'read' | 'search' | 'create' | 'update' | 'delete' | 'action';
@@ -19,6 +20,8 @@ export interface AdminToolField {
   readonly name: string;
   readonly type: AdminFieldType;
   readonly required: boolean;
+  /** The argument is a LIST of `type`: the list tool's `where` is a list of predicates. */
+  readonly list?: true;
 }
 
 export interface AdminMcpTool {
@@ -49,11 +52,30 @@ const ID_FIELD: AdminToolField = { name: 'id', type: 'text', required: true };
  * description of the same contract. `mcp.ts` leaves an action tool's schema OPEN instead, so the
  * action's own validation is the one that decides.
  */
-const actionEnvelope = (destructive: boolean): readonly AdminToolField[] => [
+const actionEnvelope = (action: AdminAction): readonly AdminToolField[] => [
   { name: 'id', type: 'text', required: false },
-  ...(destructive ? [{ name: 'confirmation', type: 'text', required: true } as const] : []),
+  // A batch action is the SAME tool, given a list of rows instead of one: run once per row through
+  // the button's gate, answered with the counts the batch bar shows.
+  ...(action.batch === undefined
+    ? []
+    : [{ name: 'ids', type: 'text', required: false, list: true } as const]),
+  ...(action.destructive === true
+    ? [{ name: 'confirmation', type: 'text', required: true } as const]
+    : []),
 ];
 
+/** What an agent reads about when and over what an action runs — the schema cannot say it. */
+const actionDescription = (action: AdminAction): string =>
+  [
+    action.mcp?.description ?? `Run the ${action.name} action.`,
+    action.when === undefined
+      ? ''
+      : ' Applies only to some rows: a row it does not apply to is refused with X_ADMIN_ACTION_NOT_APPLICABLE.',
+    action.batch === undefined
+      ? ''
+      : ` Pass ids: [...] to run it once per row; the answer counts done, refused and failed${action.destructive === true ? ', and confirmation is "<entity>:<n> rows"' : ''}.`,
+  ].join('');
+
 const formFields = (resource: AdminResource): readonly AdminToolField[] =>
   resource.formFields.map((field) => ({
     name: field.name,
@@ -61,18 +83,40 @@ const formFields = (resource: AdminResource): readonly AdminToolField[] =>
     required: field.required,
   }));
 
+/**
+ * The list tool says what it filters by, because a schema cannot: `where` is a list of
+ * `{ field, op?, value }` and the fields and scopes are this resource's own. The same names the
+ * list screen's URL takes — one grammar, two transports.
+ */
+const listDescription = (resource: AdminResource): string => {
+  const filters = resource.filters.map((field) => field.name);
+  const scopes = resource.scopes.map((scope) => scope.name);
+  return [
+    `List ${resource.name} rows, cursor-paginated.`,
+    filters.length === 0
+      ? ''
+      : ` where: [{ field, op?, value }] over ${filters.join(', ')}; op defaults per field.`,
+    scopes.length === 0 ? '' : ` scope: one of ${scopes.join(', ')}.`,
+  ].join('');
+};
+
 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.`,
+        description: listDescription(resource),
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'list'),
+        permissions: permissionsForOperation(resource.permission, 'list'),
         destructive: false,
-        input: [CURSOR_FIELD, { name: 'limit', type: 'number', required: false }],
+        input: [
+          CURSOR_FIELD,
+          { name: 'limit', type: 'number', required: false },
+          { name: 'scope', type: 'text', required: false },
+          { name: 'where', type: 'json', required: false, list: true },
+        ],
       };
     case 'detail':
       return {
@@ -81,7 +125,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         description: `Read one ${resource.name} row by id.`,
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'detail'),
+        permissions: permissionsForOperation(resource.permission, 'detail'),
         destructive: false,
         input: [ID_FIELD],
       };
@@ -92,7 +136,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         description: `Create a ${resource.name} row. Validated by the entity's schema.`,
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'create'),
+        permissions: permissionsForOperation(resource.permission, 'create'),
         destructive: false,
         input: formFields(resource),
       };
@@ -103,7 +147,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         description: `Update fields of one ${resource.name} row.`,
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'update'),
+        permissions: permissionsForOperation(resource.permission, 'update'),
         destructive: false,
         input: [ID_FIELD, ...formFields(resource)],
       };
@@ -114,7 +158,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         description: `Delete one ${resource.name} row. Requires confirmation "<entity>:<id>".`,
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'delete'),
+        permissions: permissionsForOperation(resource.permission, 'delete'),
         destructive: true,
         input: [ID_FIELD, { name: 'confirmation', type: 'text', required: true }],
       };
@@ -154,12 +198,12 @@ function toolGates(app: AdminApp): readonly ToolGate[] {
         tool: {
           name: `admin.action.${action.name}`,
           kind: 'action',
-          description: action.mcp?.description ?? `Run the ${action.name} action.`,
+          description: actionDescription(action),
           entity: action.entity ?? null,
           action: action.name,
           permissions: permissionsForAction(action),
           destructive: action.destructive === true,
-          input: actionEnvelope(action.destructive === true),
+          input: actionEnvelope(action),
         },
         gate: (ctx) => decideAction(action, ctx.actor, ctx.authz),
       });
@@ -189,12 +233,12 @@ function toolGates(app: AdminApp): readonly ToolGate[] {
       tool: {
         name: `admin.action.${action.name}`,
         kind: 'action',
-        description: action.mcp?.description ?? `Run the ${action.name} action.`,
+        description: actionDescription(action),
         entity: null,
         action: action.name,
         permissions: permissionsForAction(action),
         destructive: action.destructive === true,
-        input: actionEnvelope(action.destructive === true),
+        input: actionEnvelope(action),
       },
       gate: (ctx) => decideAction(action, ctx.actor, ctx.authz),
     });

package/src/mcp.ts

@@ -22,8 +22,11 @@ import {
   type ToolArgs,
 } from '@ultimat3/mcp';
 import { invokeAdminAction } from './action-gate';
+import { invokeRowAction } from './action-row';
 import type { AdminApp } from './admin';
 import type { AdminActor } from './authz';
+import { batchPlan, runAdminBatch } from './batch';
+import { batchEnqueue } from './batch-job';
 import {
   adminCreate,
   adminDestroy,
@@ -33,11 +36,13 @@ import {
   type CrudCtx,
   type CrudResult,
 } from './crud';
+import { AdminFilterInvalidError } from './errors';
 import type { AdminFieldType } from './fields';
+import { type AskedFilter, checkedFilter } from './list-filters';
 import { type AdminMcpTool, adminMcpTools, adminToolCatalog } from './mcp-tools';
 import type { AdminAction, AdminRow } from './registry';
-import { repoOf } from './resource';
 import { adminSearch } from './search';
+import type { ValidationIssue } from './validate';
 
 export type McpInput = Readonly<Record<string, unknown>>;
 
@@ -63,6 +68,22 @@ const withoutKeys = (input: McpInput, keys: readonly string[]): Record<string, u
   return out;
 };
 
+/** The `where` argument as a list of asked filters; anything else in it is refused by name. */
+const askedFilters = (where: unknown): readonly AskedFilter[] => {
+  if (where === undefined || where === null) return [];
+  const list: readonly unknown[] = Array.isArray(where) ? where : [where];
+  return list.map((one) => {
+    const bag = (typeof one === 'object' && one !== null ? one : {}) as Record<string, unknown>;
+    const op = bag['op'];
+    return {
+      // A predicate with no `field` names the empty one, which no resource derives.
+      field: typeof bag['field'] === 'string' ? bag['field'] : '',
+      ...(typeof op === 'string' ? { op } : {}),
+      value: bag['value'],
+    };
+  });
+};
+
 const actionByName = (app: AdminApp, name: string): AdminAction | undefined =>
   [...app.resources.flatMap((resource) => resource.actions), ...app.globalActions].find(
     (action) => action.name === name,
@@ -110,46 +131,77 @@ async function dispatch(
     if (action === undefined) {
       return { ok: false, error: 'X_ADMIN_TOOL_FORBIDDEN', reason: 'action is not registered' };
     }
-    const id = str(input, 'id');
-    // The row a row-level rule decides about, loaded through the resource that OWNS the action —
-    // what the UI's action button does. Without it the subject carried an id and no row, so an
-    // ownership rule could never allow. `null` for a row that does not exist: no evidence of
-    // permission, same contract as an action's `row:` loader. A global action names no resource.
     const owner = app.resources.find((resource) => resource.actions.includes(action));
-    const row =
-      owner === undefined || id === '' ? undefined : ((await repoOf(owner).find(id)) ?? null);
-    const result = await invokeAdminAction({
-      action,
-      input: withoutKeys(input, ['confirmation']),
-      actor: ctx.actor,
-      authz: ctx.authz,
-      audit: ctx.audit,
-      requestId: ctx.requestId,
-      subject: {
-        ...(action.entity === undefined ? {} : { entity: action.entity }),
-        ...(id === '' ? {} : { id }),
-        ...(row === undefined ? {} : { row }),
-      },
-      // The agent must echo the token, exactly as the UI makes an operator type it — and the gate
-      // derives the token it expects from the entity and `subject.id` above.
-      confirmation: str(input, 'confirmation'),
-    });
-    return result.ok
-      ? { ok: true, data: result.value }
-      : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+    const own = withoutKeys(input, ['id', 'ids', 'confirmation']);
+    const confirmation = str(input, 'confirmation');
+    // `ids`: the same tool as a batch — the bar's own path, row by row through the gate.
+    if (owner !== undefined && action.batch !== undefined && Array.isArray(input['ids'])) {
+      const ids = (input['ids'] as readonly unknown[]).filter(
+        (one): one is string => typeof one === 'string',
+      );
+      const result = await runAdminBatch({
+        resource: owner,
+        action,
+        ctx,
+        selection: { kind: 'ids', ids },
+        input: own,
+        confirmation,
+        ...(batchPlan(action) === null ? {} : { enqueue: batchEnqueue(app.basePath) }),
+      });
+      if (result.ok) return { ok: true, data: result };
+      if (result.kind === 'invalid') return invalidIssues(result.issues);
+      return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+    }
+    const id = str(input, 'id');
+    // The row a row-level rule — and the action's own `when` — decides about, loaded through the
+    // resource that OWNS the action: what the UI's button does. A global action names no row.
+    const result =
+      owner !== undefined && id !== ''
+        ? await invokeRowAction({ resource: owner, action, id, ctx, input: own, confirmation })
+        : await invokeAdminAction({
+            action,
+            input: { ...own, ...(id === '' ? {} : { id }) },
+            actor: ctx.actor,
+            authz: ctx.authz,
+            audit: ctx.audit,
+            requestId: ctx.requestId,
+            subject: {
+              ...(action.entity === undefined ? {} : { entity: action.entity }),
+              ...(id === '' ? {} : { id }),
+            },
+            // The agent must echo the token, exactly as the UI makes an operator type it.
+            confirmation,
+          });
+    if (result.ok) return { ok: true, data: result.value };
+    if (result.kind === 'not-applicable') {
+      return { ok: false, error: result.error.code, reason: result.error.cause };
+    }
+    if (result.kind === 'invalid') return invalidIssues(result.issues);
+    return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
   }
 
   const resource = app.resource(tool.entity ?? '');
   switch (tool.kind) {
     case 'list': {
       const limit = num(input, 'limit');
-      const result = await adminList(resource, ctx, {
-        cursor: str(input, 'cursor'),
-        ...(limit === undefined ? {} : { limit }),
-      });
-      return result.ok
-        ? { ok: true, data: result.page }
-        : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+      const scope = str(input, 'scope');
+      try {
+        // `where` through the same validator a URL's `f.<field>` passes, and the scope by name:
+        // an agent filters by exactly what an operator can, and the resource's row scope rides
+        // the read inside `adminList` whatever the agent sends.
+        const result = await adminList(resource, ctx, {
+          cursor: str(input, 'cursor'),
+          ...(limit === undefined ? {} : { limit }),
+          ...(scope === '' ? {} : { scope }),
+          filters: askedFilters(input['where']).map((asked) => checkedFilter(resource, asked)),
+        });
+        return result.ok
+          ? { ok: true, data: result.page }
+          : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+      } catch (error) {
+        if (!(error instanceof AdminFilterInvalidError)) throw error;
+        return { ok: false, error: error.code, reason: error.cause };
+      }
     }
     case 'read':
       return crudResult(await adminDetail(resource, ctx, str(input, 'id')));
@@ -166,11 +218,27 @@ async function dispatch(
   }
 }
 
+/** The schema's issues, as the one string an agent's result carries. */
+const invalidIssues = (issues: readonly ValidationIssue[]): AdminToolResult => ({
+  ok: false,
+  error: 'X_ADMIN_INVALID',
+  reason: JSON.stringify(issues),
+});
+
 function crudResult(result: CrudResult<AdminRow>): AdminToolResult {
   if (result.ok) return { ok: true, data: result.row };
-  return result.kind === 'denied'
-    ? { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason }
-    : { ok: false, error: 'X_ADMIN_INVALID', reason: JSON.stringify(result.issues) };
+  if (result.kind === 'denied') {
+    return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+  }
+  // No row by that id — or none this caller's row scope lets them see, which reads the same.
+  if (result.kind === 'missing') {
+    return { ok: false, error: 'X_ADMIN_INVALID', reason: 'no row has that id' };
+  }
+  // Reached only by a caller that sent a version; the update tool sends none.
+  if (result.kind === 'stale') {
+    return { ok: false, error: 'X_ADMIN_INVALID', reason: 'the row changed since it was read' };
+  }
+  return invalidIssues(result.issues);
 }
 
 export interface AdminMcpOptions {
@@ -195,6 +263,9 @@ const JSON_TYPE: Readonly<Record<AdminFieldType, NonNullable<JsonSchema['type']>
   json: 'object',
   relation: 'string',
   file: 'string',
+  // A sealed column travels as the text an agent sends. It is in no tool schema today — the
+  // CRUD tools are built from `formFields`, which never holds one.
+  secret: 'string',
 };
 
 /**
@@ -210,7 +281,10 @@ const JSON_TYPE: Readonly<Record<AdminFieldType, NonNullable<JsonSchema['type']>
 const inputSchema = (tool: AdminMcpTool): JsonSchema => ({
   type: 'object',
   properties: Object.fromEntries(
-    tool.input.map((field) => [field.name, { type: JSON_TYPE[field.type] }]),
+    tool.input.map((field) => {
+      const one = { type: JSON_TYPE[field.type] };
+      return [field.name, field.list === true ? { type: 'array', items: one } : one];
+    }),
   ),
   required: tool.input.filter((field) => field.required).map((field) => field.name),
   additionalProperties: tool.kind === 'action',

package/src/mounts.ts

@@ -0,0 +1,44 @@
+// Which admins this process declared, by base path — what a host reads to MOUNT them. Kept on the
+// global symbol registry rather than in a module variable so the host can ask "did this app
+// declare an admin?" WITHOUT importing this package: importing it loads every screen, and an app
+// with no admin must not pay for one (axiom 6).
+
+import type { AdminApp } from './admin';
+
+/** The global key. `@ultimat3/cli`'s `runtime-admin.ts` restates the string; a test holds them equal. */
+export const ADMIN_MOUNTS: symbol = Symbol.for('ultimate.admin.mounts');
+
+type Mounts = Map<string, AdminApp>;
+
+const mounts = (): Mounts => {
+  const scope = globalThis as { [key: symbol]: unknown };
+  const held = scope[ADMIN_MOUNTS];
+  if (held instanceof Map) return held as Mounts;
+  const created: Mounts = new Map();
+  scope[ADMIN_MOUNTS] = created;
+  return created;
+};
+
+/**
+ * Called by `defineAdmin()`. Keyed by base path and last-wins: `x dev` re-evaluates the module
+ * that declares the admin when it changes, and the admin a request then meets has to be the one
+ * the author just saved.
+ */
+export function registerAdminMount(app: AdminApp): void {
+  mounts().set(app.basePath, app);
+}
+
+/** Every declared admin, in declaration order. */
+export function adminMounts(): readonly AdminApp[] {
+  return [...mounts().values()];
+}
+
+/** The admin declared at `basePath` NOW, or `undefined`. Read per request, never captured. */
+export function adminMountAt(basePath: string): AdminApp | undefined {
+  return mounts().get(basePath);
+}
+
+/** Test seam; a running process never forgets an admin it declared. */
+export function clearAdminMounts(): void {
+  mounts().clear();
+}