@ultimat3/admin 22.15.0 → 24.0.0

package/src/index.ts

@@ -2,7 +2,9 @@
 // Explicit exports only — a barrel that re-exports everything is how internal helpers become
 // someone's dependency.
 
+export { AdminActionForm, type AdminActionFormProps } from './action-form';
 export {
+  ACTION_NOT_APPLICABLE_REASON,
   type ActionGateInput,
   type AdminActionButton,
   actionButtons,
@@ -13,7 +15,30 @@ export {
   invokeAdminAction,
   permissionsForAction,
 } from './action-gate';
-export { AdminActions, type AdminActionsProps } from './actions';
+export {
+  ACTION_INPUT_PREFIX,
+  type ActionInputControl,
+  type ActionInputField,
+  actionInputFields,
+  decodeActionInput,
+} from './action-input';
+export { invokeRowAction, type RowActionInput } from './action-row';
+export {
+  ACTION_OPERATION,
+  ACTION_PARAM,
+  AdminActions,
+  type AdminActionsProps,
+  actionFormHref,
+  BATCH_OPERATION,
+  DELETE_OPERATION,
+  OPERATION_FIELD,
+} from './actions';
+export {
+  type AdminRequestActor,
+  ANONYMOUS_ADMIN_ACTOR,
+  adminActorFrom,
+  requestActor,
+} from './actor';
 export {
   type AdminApp,
   type AdminAuth,
@@ -36,19 +61,30 @@ export {
   runAiPane,
 } from './ai-panes';
 export {
+  AUDIT_PAGE_DEFAULT,
+  AUDIT_PAGE_MAX,
+  type AuditCursor,
   type AuditDraft,
   type AuditEntry,
   type AuditFieldDiff,
   type AuditLog,
   type AuditLogOptions,
   type AuditOutcome,
+  type AuditQuery,
   type AuditSink,
+  auditCursorOf,
   auditEntry,
   deniedDraft,
   diffRows,
   memoryAuditLog,
   REDACTED,
 } from './audit';
+export {
+  type PostgresAuditLogOptions,
+  postgresAuditLog,
+  SQL_ADMIN_AUDIT_INSERT,
+} from './audit-pg';
+export { ADMIN_AUDIT_TABLE, SQL_ADMIN_AUDIT_TABLE } from './audit-schema';
 export {
   type AdminActor,
   type AdminAuthz,
@@ -64,6 +100,32 @@ export {
   staticAuthz,
 } from './authz';
 export {
+  type AdminBatchAnswer,
+  type AdminBatchInput,
+  type AdminBatchResult,
+  BATCH_NOT_OFFERED_REASON,
+  type BatchEnqueue,
+  type BatchRow,
+  type BatchRowOutcome,
+  type BatchSelection,
+  batchConfirmationToken,
+  batchPlan,
+  MAX_BATCH_QUEUED_ROWS,
+  MAX_BATCH_ROWS,
+  runAdminBatch,
+} from './batch';
+export {
+  AdminBatchBar,
+  type AdminBatchBarProps,
+} from './batch-bar';
+export {
+  ADMIN_BATCH_JOB,
+  batchEnqueue,
+} from './batch-job';
+export { BATCH_MATCHING_REASON, matchingConfirmationToken } from './batch-matching';
+export { BATCH_QUEUED_REASON } from './batch-queue';
+export {
+  type AdminUpdateOptions,
   adminCreate,
   adminDestroy,
   adminDetail,
@@ -76,11 +138,25 @@ export {
   type ListResult,
   permissionsForOperation,
 } from './crud';
-export { AdminDetail, type AdminDetailProps } from './detail';
+export {
+  type AdminActionDescription,
+  type AdminDescription,
+  type AdminResourceDescription,
+  type AdminRouteDescription,
+  type AdminScopeDescription,
+  type AdminSectionDescription,
+  describeAdmin,
+} from './describe';
+export {
+  AdminDetail,
+  type AdminDetailProps,
+  HISTORY_PARAM,
+} from './detail';
 export {
   type AdminColumnFacts,
   type AdminColumnReference,
   adminColumnsOf,
+  adminSealedColumnsOf,
 } from './entity-columns';
 // The /_x dashboard is NOT re-exported here — it has its own door, `@ultimat3/admin/dev`, so a
 // host that only mounts the dev panels never loads a production admin component.
@@ -88,13 +164,17 @@ export {
   ADMIN_ERROR_CODES,
   ADMIN_ERROR_TITLES,
   AdminActionDuplicateError,
+  AdminActionNotApplicableError,
   AdminEntityUnknownError,
   type AdminErrorCode,
   type AdminErrorParts,
   AdminFieldUnsupportedError,
+  AdminFilterInvalidError,
+  AdminMountMissingError,
   AdminPagePathInvalidError,
   AdminPageUnguardedError,
   AdminPolicyMissingError,
+  AdminRepoUnboundError,
   adminErrorFrom,
   DevDashboardInProdError,
   DevSourceUnavailableError,
@@ -102,18 +182,53 @@ export {
 export {
   type AdminField,
   type AdminFieldType,
+  type AdminFilterKind,
   type AdminWidget,
   fieldTypeFromColumn,
   filterable,
+  filterKindFor,
   listable,
   searchable,
   sortable,
   WIDGET_BY_FIELD_TYPE,
   widgetFor,
 } from './fields';
-export { AdminForm, type AdminFormProps } from './form';
-export { AdminLayout, type AdminLayoutProps } from './layout';
+export { AdminForm, type AdminFormProps, issueText } from './form';
+export { currencyFieldOf, decodeForm, posted } from './form-decode';
+export { JOB_MANAGE, JOB_READ } from './jobs/job-actions';
+export { JOB_ENTITY } from './jobs/job-entities';
+export { JOBS_PATH, jobRowScope } from './jobs/job-resources';
+export { AdminLayout, type AdminLayoutProps, actorLabel } from './layout';
 export { AdminList, type AdminListProps } from './list';
+export { type ResourceColumnsInput, resourceColumns } from './list-columns';
+export { AdminFilterBar, type AdminFilterBarProps } from './list-filter-bar';
+export {
+  type AskedFilter,
+  checkedFilter,
+  declaredFilters,
+  FILTER_PREFIX,
+  filterOpsOf,
+  filterParam,
+  knownFilterParams,
+} from './list-filters';
+export {
+  CURSOR_PARAM,
+  type ListLocation,
+  listHref,
+  pageRequestOf,
+  SCOPE_PARAM,
+  SORT_PARAM,
+} from './list-request';
+export {
+  type AdminListRequest,
+  findRow,
+  type ListWhere,
+  listWhere,
+  rowWhere,
+  scopeCounts,
+  scopeNamed,
+} from './list-scope';
+export { AdminScopeTabs, type AdminScopeTabsProps } from './list-scope-tabs';
 export {
   type AdminMcpOptions,
   type AdminToolResult,
@@ -129,8 +244,15 @@ export {
   adminToolCatalog,
   adminToolDecisions,
 } from './mcp-tools';
+export {
+  ADMIN_MOUNTS,
+  adminMountAt,
+  adminMounts,
+  clearAdminMounts,
+  registerAdminMount,
+} from './mounts';
 export { adminNav, type NavGroup, type NavItem, type NavOptions, visibleNav } from './nav';
-export { AdminPageDenied, guardedPage } from './page-guard';
+export { AdminPageDenied, auditRefusal } from './page-guard';
 export {
   type AdminCustomPage,
   type AdminPageComponent,
@@ -168,48 +290,115 @@ export {
   isDestructive,
   ruleFor,
 } from './permissions';
-export { adminPermissions, type PolicyAuthzInput, policyAuthz } from './policy-bridge';
+export {
+  declareAdminPermissions,
+  type PolicyAuthzInput,
+  policyAuthz,
+  roleAuthz,
+  singlePolicyAuthz,
+} from './policy-bridge';
 export {
   type AdminAction,
   type AdminActionCtx,
+  type AdminBatchOptions,
   type AdminColumn,
   type AdminColumnDescription,
   type AdminColumnMeta,
+  type AdminDb,
   type AdminEntity,
   type AdminEntityDescription,
   type AdminFilter,
   type AdminJobSummary,
   type AdminListQuery,
+  type AdminMatchingResult,
   type AdminRepo,
   type AdminRow,
   type AdminSort,
+  type AdminTable,
+  type AdminTableRead,
+  computedRow,
+  FILTER_OPS,
   type FilterOp,
   type KeysetBound,
   type RegisteredEntity,
-  type RegisteredRepo,
+  type RegisteredTable,
   readField,
   rowId,
 } from './registry';
 export {
-  type AdminFieldOverride,
+  type AdminRelated,
+  type AdminRelatedList,
+  RELATED_PAGE_SIZE,
+  relatedLists,
+  relatedOf,
+} from './related';
+export {
+  type AdminLookupRequest,
+  type AdminLookupResult,
+  type AdminOption,
+  adminLookup,
+  LOOKUP_SELECT_MAX,
+  labelOf,
+  type RelationData,
+  type RelationNeed,
+  relationNeeds,
+  relationsFor,
+} from './relations';
+export { ComputedCell, TRUNCATE_AT } from './renderers';
+export { adminEntitiesOf, adminRepoFor, adminTablesOf } from './repo-entity';
+export {
   type AdminResource,
   type AdminResourceOptions,
   adminResource,
   repoOf,
   resourceFor,
 } from './resource';
+export type { AdminFieldOverride } from './resource-fields';
+export {
+  type AdminFormGroupOptions,
+  type AdminSection,
+  type AdminSectionOptions,
+  DEFAULT_SECTION_KEY,
+} from './resource-layout';
+export {
+  ADMIN_RENDERERS,
+  type AdminColumnComponent,
+  type AdminColumnRenderProps,
+  type AdminComputedColumn,
+  type AdminComputedColumnOptions,
+  type AdminRenderer,
+  type AdminRowScope,
+  type AdminScope,
+  type AdminScopeOptions,
+  type AdminScopeWhere,
+  LOOKUP_SEGMENT,
+} from './resource-list';
 export {
   type AdminRouteConfig,
+  type AdminRouteMatch,
   adminRouteConfig,
   adminRouteFor,
+  adminRouteMatch,
   adminRoutes,
 } from './routes';
+export { ROW_OUT_OF_SCOPE_REASON } from './row-scope-write';
+export { ROW_CHANGED_REASON, rowVersion, VERSION_FIELD } from './row-version';
+export {
+  type AdminRouteRequest,
+  type AdminRouteResponse,
+  type AdminScreen,
+  guardedScreen,
+  lookupHref,
+  widgetContextOf,
+} from './screen-frame';
+export { type OperationDecision, OperationMatrix, operationMatrix } from './screen-home';
 export {
   type AdminSearchHit,
   type AdminSearchInput,
   type AdminSearchResult,
   adminSearch,
 } from './search';
+export { type AdminTestCtxInput, adminTestCtx } from './test-ctx';
 export {
   type AdminBranding,
   adminBranding,
@@ -223,9 +412,10 @@ export { type ValidationIssue, type ValidationResult, validateInput } from './va
 export {
   assertMoney,
   assertZone,
+  type GuardedField,
   type SelectOption,
   type WidgetContext,
   type WidgetProps,
   widgetProps,
 } from './widget-value';
-export { Widget, type WidgetInput } from './widgets';
+export { optionLabel, Widget, type WidgetInput } from './widgets';

package/src/jobs/fleet-repo.ts

@@ -0,0 +1,155 @@
+// The queues, the tasks and the workers as `AdminRepo`s. Each is a SMALL set the store answers
+// whole — one `stats()`, one registry read — so a page is that set, filtered by the package's one
+// predicate evaluator (`outsideRowScope`), ordered and cut by keyset here. Read-only.
+
+import { assert } from '@ultimat3/core';
+import { inspectManifest, nextTaskRun, registeredJobs } from '@ultimat3/jobs';
+import type { AdminFilter, AdminListQuery, AdminRepo, AdminRow, KeysetBound } from '../registry';
+import { outsideRowScope } from '../row-scope-write';
+import { jobsOperator } from './operator';
+
+type Load = () => Promise<readonly AdminRow[]>;
+
+const comparable = (value: unknown): string | number => {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'number') return value;
+  if (typeof value === 'boolean') return value ? 1 : 0;
+  return String(value);
+};
+
+const absent = (value: unknown): boolean => value === null || value === undefined;
+
+/**
+ * Code-unit order, never a collation: the same set reads the same way on every machine. NULL is
+ * the LARGEST value — last ascending, first descending — as the database orders a nullable sort
+ * key and as `repo-entity.ts` seeks one; it read as `''` here, which sorted it as a zero.
+ */
+const order = (a: unknown, b: unknown): number => {
+  if (absent(a) || absent(b)) return absent(a) && absent(b) ? 0 : absent(a) ? 1 : -1;
+  const x = comparable(a);
+  const y = comparable(b);
+  return x < y ? -1 : x > y ? 1 : 0;
+};
+
+/**
+ * A cursor carries its value as text (`pagination.ts`), or `null` for a row that held none; read
+ * back as the type of the row it is compared with. A `null` bound stays `null` — `new Date(null)`
+ * is the epoch and `new Date('')` is NaN, and either made the page after a NULL row the wrong one.
+ */
+const boundValue = (row: AdminRow, bound: KeysetBound, field: string): unknown => {
+  if (bound.value === null) return null;
+  const held = row[field];
+  if (held instanceof Date) return new Date(bound.value);
+  if (typeof held === 'number') return Number(bound.value);
+  if (typeof held === 'boolean') return bound.value === 'true';
+  return bound.value;
+};
+
+export function fleetRepo(idField: string, load: Load): AdminRepo<AdminRow> {
+  const matching = async (where: readonly AdminFilter[] | undefined): Promise<AdminRow[]> =>
+    (await load()).filter((row) => outsideRowScope(row, where ?? []) === null);
+
+  /** `(sort value, id)` against a bound, in the query's own direction. */
+  const versus = (row: AdminRow, bound: KeysetBound, query: AdminListQuery): number => {
+    const sign = query.sort.direction === 'asc' ? 1 : -1;
+    const field = query.sort.field;
+    const primary = order(row[field], boundValue(row, bound, field));
+    return sign * (primary !== 0 ? primary : order(row[idField], bound.id));
+  };
+
+  const readOnly = async (): Promise<never> => {
+    assert(
+      false,
+      'a queue, task or worker row was written through the admin repo, and none offers a write',
+      'change it through its actions: admin.action.job.queue.pause, admin.action.job.task.run-now, …',
+    );
+  };
+
+  return {
+    async list(query) {
+      const sign = query.sort.direction === 'asc' ? 1 : -1;
+      const rows = (await matching(query.where)).sort(
+        (a, b) =>
+          sign * (order(a[query.sort.field], b[query.sort.field]) || order(a[idField], b[idField])),
+      );
+      const { after, before } = query;
+      if (before !== undefined) {
+        const earlier = rows.filter((row) => versus(row, before, query) < 0);
+        return earlier.slice(Math.max(0, earlier.length - query.limit));
+      }
+      const later =
+        after === undefined ? rows : rows.filter((row) => versus(row, after, query) > 0);
+      return later.slice(0, query.limit);
+    },
+    async find(id) {
+      return (await load()).find((row) => row[idField] === id) ?? null;
+    },
+    async count(where) {
+      return (await matching(where)).length;
+    },
+    create: readOnly,
+    update: readOnly,
+    destroy: readOnly,
+  };
+}
+
+const at = (ms: number | undefined): Date | null => (ms === undefined ? null : new Date(ms));
+
+/** Every queue with rows, every paused one and every one a registered job names. */
+export const queueRepo = fleetRepo('name', async () => {
+  const { driver, introspect } = jobsOperator();
+  const [stats, paused] = await Promise.all([driver.stats(), introspect.pausedQueues()]);
+  const pausedAt = new Map(paused.map((entry) => [entry.name, entry.pausedAt]));
+  const names = new Set([
+    ...stats.map((queue) => queue.queue),
+    ...pausedAt.keys(),
+    ...registeredJobs().map((handle) => handle.queue),
+  ]);
+  return [...names].map((name) => {
+    const queue = stats.find((one) => one.queue === name);
+    return {
+      name,
+      ready: queue?.ready ?? 0,
+      delayed: queue?.delayed ?? 0,
+      running: queue?.running ?? 0,
+      suspended: queue?.suspended ?? 0,
+      failed: queue?.failed ?? 0,
+      dead: queue?.dead ?? 0,
+      oldestReadyMs: queue?.oldestReadyMs ?? 0,
+      paused: pausedAt.has(name),
+      pausedAt: at(pausedAt.get(name)),
+    };
+  });
+});
+
+/** Every registered task: its schedule, its zone, the last occurrence that fired and the next. */
+export const taskRepo = fleetRepo('name', async () => {
+  const { introspect } = jobsOperator();
+  const [paused, fires] = await Promise.all([introspect.pausedTasks(), introspect.taskFires()]);
+  const pausedNames = new Set(paused.map((entry) => entry.name));
+  const now = new Date();
+  return inspectManifest().tasks.map((task) => ({
+    name: task.name,
+    cron: task.cron,
+    tz: task.tz,
+    catchUp: task.catchUp,
+    enqueues: task.enqueues.join(', '),
+    lastFireAt: at(fires.find((fire) => fire.task === task.name)?.firedAt),
+    nextFireAt: nextTaskRun(task, now),
+    paused: pausedNames.has(task.name),
+  }));
+});
+
+/** Every worker whose heartbeat has not expired. */
+export const workerRepo = fleetRepo('id', async () => {
+  const { introspect } = jobsOperator();
+  return (await introspect.workers()).map((worker) => ({
+    id: worker.id,
+    host: worker.host,
+    queues: worker.queues.join(', '),
+    concurrency: worker.concurrency,
+    inFlight: worker.inFlight.length,
+    startedAt: new Date(worker.startedAt),
+    heartbeatAt: new Date(worker.heartbeatAt),
+  }));
+});

package/src/jobs/job-actions.ts

@@ -0,0 +1,172 @@
+// Every change an operator makes to the queue, as an `AdminAction`: the button on a row, the batch
+// bar's "checked" and "all matching", the MCP tool and the audit entry come from these declarations
+// and from nothing jobs-specific. One permission gates them all — `job:manage`; reading is
+// `job:read`, so an operator without the first sees every screen and no control.
+
+import {
+  cancelJob,
+  getTask,
+  type JobRecord,
+  pauseQueue,
+  promoteJob,
+  removeJob,
+  resumeQueue,
+  retryFromStep,
+} from '@ultimat3/jobs';
+import { t } from '@ultimat3/schema';
+import { AdminFilterInvalidError } from '../errors';
+import type { AdminAction, AdminFilter, AdminMatchingResult, AdminRow } from '../registry';
+import { JOB_ENTITY } from './job-entities';
+import { bulkWhere, JOBS_RESOURCE } from './job-where';
+import { jobsOperator } from './operator';
+
+/** Reading the jobs screens. The admin's own `<noun>:read`, for every jobs resource. */
+export const JOB_READ = 'job:read';
+/** Every action on the queue. Without it the screens render no control and refuse the call. */
+export const JOB_MANAGE = 'job:manage';
+
+const LIVE: ReadonlySet<unknown> = new Set(['ready', 'delayed', 'running', 'suspended']);
+
+const idOf = (input: Readonly<Record<string, unknown>>): string => String(input['id'] ?? '');
+
+const waitingOnClock = (row: AdminRow): boolean => {
+  const runAt = row['runAt'];
+  return (
+    (row['state'] === 'ready' || row['state'] === 'delayed') &&
+    runAt instanceof Date &&
+    runAt.getTime() > Date.now()
+  );
+};
+
+/** A bulk verb over the list's `where`, held to the one state the action is for. */
+function bulk(
+  where: readonly AdminFilter[],
+  states: readonly JobRecord['state'][],
+  run: (filter: NonNullable<ReturnType<typeof bulkWhere>>) => Promise<AdminMatchingResult>,
+): Promise<AdminMatchingResult> {
+  const filter = bulkWhere(where);
+  if (filter === null) return Promise.resolve({ affected: 0, remaining: 0 });
+  if (!new Set<string>(states).has(filter.state)) {
+    throw new AdminFilterInvalidError({
+      entity: JOBS_RESOURCE,
+      asked: `all matching in scope=${filter.state}`,
+      cause: 'is not a state this action applies to',
+      known: states.map((state) => `scope=${state}`),
+    });
+  }
+  return run(filter);
+}
+
+const jobAction = (action: Omit<AdminAction, 'permission' | 'entity'>): AdminAction => ({
+  ...action,
+  permission: JOB_MANAGE,
+  entity: JOB_ENTITY.jobs,
+});
+
+export const jobActions: readonly AdminAction[] = [
+  jobAction({
+    name: 'job.retry',
+    // A dead letter, and only one: a finished `done` row run again is a second side effect.
+    when: (row) => row['state'] === 'dead',
+    batch: true,
+    matching: ({ where }) =>
+      bulk(where, ['dead'], (filter) => jobsOperator().introspect.requeueMany(filter)),
+    async handle({ input }) {
+      return { id: (await jobsOperator().introspect.requeue(idOf(input))).id };
+    },
+  }),
+  jobAction({
+    name: 'job.retry-from-step',
+    when: (row) => row['state'] === 'dead' || row['state'] === 'failed',
+    input: t.object({ step: t.string.min(1) }),
+    async handle({ input }) {
+      const step = String(input['step'] ?? '');
+      return { id: (await retryFromStep(jobsOperator().driver, idOf(input), step))?.id ?? null };
+    },
+  }),
+  jobAction({
+    name: 'job.run-now',
+    when: waitingOnClock,
+    batch: true,
+    matching: ({ where }) =>
+      bulk(where, ['delayed', 'ready'], (filter) => jobsOperator().introspect.promoteMany(filter)),
+    async handle({ input }) {
+      return { id: (await promoteJob(jobsOperator().driver, idOf(input))).id };
+    },
+  }),
+  jobAction({
+    name: 'job.cancel',
+    when: (row) => LIVE.has(row['state']),
+    async handle({ input }) {
+      return { id: (await cancelJob(jobsOperator().driver, idOf(input)))?.id ?? null };
+    },
+  }),
+  jobAction({
+    name: 'job.remove',
+    destructive: true,
+    // A running job is a worker's: cancel it first, as the store itself insists.
+    when: (row) => row['state'] !== 'running',
+    batch: true,
+    matching: ({ where }) =>
+      bulk(
+        where,
+        ['ready', 'delayed', 'suspended', 'done', 'failed', 'dead', 'cancelled'],
+        (filter) => jobsOperator().introspect.removeMany(filter),
+      ),
+    async handle({ input }) {
+      return { id: (await removeJob(jobsOperator().driver, idOf(input)))?.id ?? null };
+    },
+  }),
+];
+
+const fleetAction = (
+  entity: string,
+  action: Omit<AdminAction, 'permission' | 'entity'>,
+): AdminAction => ({ ...action, permission: JOB_MANAGE, entity });
+
+export const queueActions: readonly AdminAction[] = [
+  fleetAction(JOB_ENTITY.queues, {
+    name: 'job.queue.pause',
+    when: (row) => row['paused'] !== true,
+    async handle({ input }) {
+      await pauseQueue(jobsOperator().driver, idOf(input));
+      return { queue: idOf(input), paused: true };
+    },
+  }),
+  fleetAction(JOB_ENTITY.queues, {
+    name: 'job.queue.resume',
+    when: (row) => row['paused'] === true,
+    async handle({ input }) {
+      await resumeQueue(jobsOperator().driver, idOf(input));
+      return { queue: idOf(input), paused: false };
+    },
+  }),
+];
+
+export const taskActions: readonly AdminAction[] = [
+  fleetAction(JOB_ENTITY.tasks, {
+    name: 'job.task.pause',
+    when: (row) => row['paused'] !== true,
+    async handle({ input }) {
+      await jobsOperator().introspect.pauseTask(idOf(input));
+      return { task: idOf(input), paused: true };
+    },
+  }),
+  fleetAction(JOB_ENTITY.tasks, {
+    name: 'job.task.resume',
+    when: (row) => row['paused'] === true,
+    async handle({ input }) {
+      await jobsOperator().introspect.resumeTask(idOf(input));
+      return { task: idOf(input), paused: false };
+    },
+  }),
+  fleetAction(JOB_ENTITY.tasks, {
+    name: 'job.task.run-now',
+    async handle({ input }) {
+      // The row came from the registry, so a task that is gone is a task renamed since the page.
+      const handle = getTask(idOf(input));
+      const jobs = handle === undefined ? [] : await handle.enqueue();
+      return { task: idOf(input), jobs: jobs.length };
+    },
+  }),
+];