@ultimat3/admin 🛠️

Two dashboards live here. They are not the same thing — and they have two doors.

| | /_x — framework dev dashboard | admin — generated app admin | |---|---|---| | Import | @ultimat3/admin/dev | @ultimat3/admin | | Audience | you, debugging the framework | your operators, and their agents | | Environment | development only — mounting it with env=production or role=production throws X_DEV_DASHBOARD_IN_PROD | production | | Authz | none: it is your own machine | the app's policies, one decision per surface | | Data | introspection calls (describeRoutes, inspect, dependentsOf, …) | the entity registry + repos | | Shipped in the app image | never mounted | mounted at /admin |

/_x panels

One panel per file. Each kills one question, and each is available as --json — the tab is a rendering of the payload, not a second source.

| Panel | Kills | |---|---| | routes | which handler serves this? — render mode, offline strategy, revalidate tags, budget | | timeline | where did the time go? — flamegraph of SQL, cache, action, policy spans + the N+1 count | | live | what does each subscriber receive, and why — the matcher's decision trace | | jobs | queue depth, step traces, retry-from-step target, dead letter | | db | psql in a tab (read-only; assertReadOnly refuses DML), schema + drift (null unless a host wires the check) | | mail | caught mail, rendered, per locale, with the locale gaps listed | | cache | the tag graph — what invalidated what, and which tags are orphans | | policy | the permission matrix per actor, every cell carrying its trace | | manifest | emitted x.manifest.json diffed against the committed one |

import { devDashboard, defaultDevSources } from '@ultimat3/admin/dev';

const dev = devDashboard({ sources: defaultDevSources({ authz, actors }) }); // throws in prod
const response = await dev.handle(request); // null when the path is not /_x
await dev.json('jobs'); // the same payload /_x/jobs renders from

The root barrel does not re-export any of this: x dev mounts /_x without pulling a Solid component tree into the process, and an admin view cannot reach a dev panel by accident.

The generated admin

One call, a working CRUD admin: columns from the entity's columns, filters from indexed columns, validation from the entity's schema, labels from i18n keys.

entities takes the entities themselves — the objects entity() returned, not their describeEntities() projection. The admin reads $columns, $primaryKey, $schema and $describe() off them; RegisteredEntity in registry.ts is the compile-time check that it may.

import { defineAdmin, adminRoutes, policyAuthz, memoryAuditLog } from '@ultimat3/admin';
import { posts, users } from '@app/db/schema';

export const admin = defineAdmin({
  entities: [posts, users],
  // `AdminAction` is the admin's own shape: a `permission` (never optional) plus a handler.
  actions: [{ name: 'post.publish', permission: 'post:publish', entity: 'posts', handle }],
  resources: { posts: { repo: postsAdminRepo, listFields: ['title', 'status', 'publishedAt'] } },
  branding: { nameKey: 'admin.brand.name', accent: '--x-color-brand', mode: 'system' },
  auth: { actor: (request) => session(request), authz: policyAuthz({ policies }) },
  audit: memoryAuditLog({ sinks: [auditTable] }),
});

export const routes = adminRoutes(admin); // every view `ssr`, gated — an admin screen is per-actor

The views are TSX, and the pieces come apart

There is no view DSL here, and there will not be one. Every renderer is an ordinary SolidJS component in an ordinary .tsx file importing @ultimat3/ui — AdminList, AdminForm, AdminDetail, Widget, AdminLayout are each exported on their own, so a table can be lifted out of its page and dropped into a screen the generator never wrote:

import { AdminList, AdminForm, Widget } from '@ultimat3/admin';

<AdminList resource={admin.resource('posts')} page={page} ctx={ctx} … />;   // just the table
<Widget field={field} value={row.total} ctx={ctx} mode="read" />;          // just one cell

Widget takes the field and the raw row value, not pre-derived props: widgetProps() is the guard (money is minor units, a timestamp has an IANA zone) and the component calls it, so there is no way to render a cell that skipped it. mode is read or edit; an edit cell also takes the control the surrounding <Field> hands its child, and onInput.

An admin route is an ordinary route primitive; an admin action is an ordinary action. Nothing in this package is written in a second language that only the dashboard understands — the escape hatch is the same TSX as the main path, which is why there is no cliff to fall off when a screen stops being CRUD.

Custom pages

The bespoke ops screen is the common case, not the corner: a reconciliation fixer, a proxy health board, a deploy button. Declare it in pages: and it becomes a real admin route.

// admin/ops/page.tsx — a component, nothing framework-shaped about it
export function OpsPage(props: AdminPageProps) {
  return <OpsBoard counts={await mediaStateCounts()} />;
}

// admin/index.ts
defineAdmin({
  entities: [posts],
  pages: [
    {
      path: '/ops',                       // rooted at basePath → /admin/ops
      titleKey: 'admin.ops.title',
      navGroup: 'admin.group.operations', // omit to keep it out of the nav
      permissions: ['ops:read'],          // `admin:read` is composed in front of it
      component: OpsPage,
    },
  ],
  auth,
});

| What you get | How | |---|---| | a row in app.routes, adminRoutes(), x manifest | pageRoutes() folds it in beside the generated screens | | a nav item that disappears for an actor who cannot open it | NavItem.permissions → visibleNav | | a defineRoute({ policy }) you never wrote and cannot omit | adminRouteConfig composes permissions[0] into it | | a per-request refusal, audited, before your component runs | guardedPage() wraps it in decideAll |

The guard is not yours to remember. adminRoutes() hands the router the wrapped component, never the one you wrote, and AdminPageProps.ctx is required by the type — a page component cannot be called without the handle the guard decides on. permissions: [] throws X_ADMIN_PAGE_UNGUARDED where it is written, not on the first unauthenticated request. A path that shadows a generated screen throws X_ADMIN_PAGE_PATH_INVALID the same way.

Custom pages are render: 'ssr', hydrate: 'never': the guard runs on the server, so there is no shell to ship and nothing to decide twice.

Serving an admin URL from your own route file

A host whose router is file-based writes its own page.tsx for an admin URL. Take the gate from the route table — never type it a second time:

import { adminRouteFor } from '@ultimat3/admin';
import { admin } from './admin';

const route = adminRouteFor(admin, `${admin.basePath}/users`);

export const config = defineRoute({
  render: 'ssr',
  hydrate: 'never',
  offline: 'network-only',
  policy: route.policy, // `defineAdmin()`'s, from `permissionsForOperation('users', 'list')`
  meta: () => ({ title: t('admin.users.title') }),
});

route.policy is the same object route.config.policy carries, so the gate has one declaration and one reader. A path the admin does not declare throws X_ADMIN_PAGE_PATH_INVALID listing the paths that would have worked — a page serving an admin URL the admin never built is a screen whose permissions nothing composed.

Splitting the admin across files

defineAdmin takes plain values — entities, resources, actions, jobs, pages, nav, branding, auth, audit. Every one of them can be imported from its own module, so the cut is along the input's own keys and there is exactly one layout:

app/admin/
  index.ts              defineAdmin({ … }) — composition only, no logic
  auth.ts               actor() + policyAuthz({ policies })
  nav.ts                groups, order, extras
  <resource>/
    resource.ts         the AdminResourceOptions entry (listFields, sensitive, labelField)
    repo.ts             the AdminRepo binding
    actions.ts          the AdminAction[] for this entity
    pages/<name>.tsx    a custom page component for this entity, if any
  pages/<name>.tsx      an app-wide custom page (ops, reconciliation, deploy)

index.ts imports each and composes. Nothing here is a framework rule — it is what the input shape already is, written down once so two apps do not invent two layouts. x g admin emits it.

Derived from the entity, and only from it

| Admin decision | Read from | |---|---| | field type + widget | $meta.kind, refined by values (select) and references (reference) | | one line vs prose | text({ max }) has a length; text() does not | | read-only | a generated default (uuid(), defaultNow(), onUpdateNow()) or a key column | | filters, sort | $meta.index / unique / primaryKey — never an unindexed column | | row address | $primaryKey[0], composite keys included | | validation | $schema, the entity's own Standard Schema |

sensitive, a fixed currency and labelField have no entity source and are never guessed: declare them in resources: { <entity>: { … } } or they are absent.

Rules it enforces for you

| Rule | Where | |---|---| | Money is { minor, currency } — a float throws X_ADMIN_FIELD_UNSUPPORTED | widgetProps | | A timestamp never renders without an IANA zone | assertZone | | Pagination is keyset — AdminListQuery has no offset field | pagination.ts | | A cursor is signed by @ultimat3/core and scoped to its resource — a forged or borrowed one is page one, never another table's position | pagination.ts | | A button an actor cannot press is never rendered, and the call is refused by the same decision | action-gate.ts | | Destructive operations re-confirm (<entity>:<id>) and are always audited | permissions.ts, crud.ts | | Every mutation and every denial is on the audit log, with a before/after diff | audit.ts | | Branding aliases tokens only — accent: '#7c3aed' is a compile error | theme.ts |

Reads are audited too, and on both branches: adminDetail keys its entry on the row, adminList and adminSearch key theirs on the table (entityId: null), and a refusal is an entry of its own. AdminSearchResult.audit carries one entry per resource the call decided about — searched or refused — so a jump box that walked every readable entity leaves a trace.

AI-first

The admin exposes its own MCP surface, derived from the same resources and gated by the same authz — an agent sees exactly the tools its actor could have clicked.

import { adminMcp, adminMcpTools } from '@ultimat3/admin';

export const mcp = adminMcp({ app: admin, actor: (session) => actorFor(session.token) });
adminMcpTools(admin, ctx); // admin.post.list · admin.post.read · admin.search · admin.action.post.publish

Opt-in AI panes, each declaring the scope it needs (aiPanes({ enable: ['anomaly'] })):

| Pane | Scope | |---|---| | anomaly | jobs:read, metrics:read | | nl-query | db:read-only | | backlog-forecast | jobs:read, metrics:read |

Panes are off until enabled, and runAiPane refuses (never no-ops) without a runner.

Errors

X_ADMIN_ENTITY_UNKNOWN · X_ADMIN_FIELD_UNSUPPORTED · X_ADMIN_POLICY_MISSING · X_ADMIN_PAGE_UNGUARDED · X_ADMIN_PAGE_PATH_INVALID · X_ADMIN_DENIED · X_ADMIN_TOOL_FORBIDDEN · X_ADMIN_INVALID · X_DEV_DASHBOARD_IN_PROD · X_NOT_IMPLEMENTED (an unwired /_x source, carrying the wiring line).