@zerotal/admin 1.0.0

package/src/relations/RelationManager.ts

@@ -0,0 +1,114 @@
+/**
+ * Relation managers — related-record tables shown on a record's View page.
+ * A HasMany relation renders the children as a table that links into their own
+ * resource, so full CRUD lives there rather than being duplicated here.
+ *
+ *   class UserResource extends Resource {
+ *     static relations() {
+ *       return [hasMany(PostResource, "user_id").title("Posts")];
+ *     }
+ *   }
+ */
+import type { ResourceClass } from "../Panel.ts";
+
+export type RelationKind = "hasMany" | "belongsToMany";
+
+/** A pivot-table column surfaced on a BelongsToMany relation table. */
+export interface PivotColumn {
+  key: string;
+  label?: string;
+}
+
+export class RelationManager {
+  /** @internal */ _resource: ResourceClass;
+  /** @internal HasMany: the child's foreign-key column. */
+  _foreignKey: string;
+  /** @internal */ _kind: RelationKind = "hasMany";
+  /** @internal BelongsToMany: the relationship method on the parent model. */
+  _relationName?: string;
+  /** @internal BelongsToMany: pivot columns to display. */
+  _pivotColumns: PivotColumn[] = [];
+  /** @internal BelongsToMany: max related options offered in the Attach select. */
+  _attachLimit = 50;
+  /** @internal */ _title?: string;
+  /** @internal */ _icon?: string;
+  /** @internal */ _perPage = 10;
+  /** @internal */ _canCreate = true;
+  /** @internal BelongsToMany: allow attach/detach. */
+  _canAttach = true;
+
+  constructor(resource: ResourceClass, foreignKey: string) {
+    this._resource = resource;
+    this._foreignKey = foreignKey;
+  }
+
+  title(title: string): this {
+    this._title = title;
+    return this;
+  }
+
+  /** Disable the "New" button for this relation (HasMany). */
+  canCreate(value: boolean): this {
+    this._canCreate = value;
+    return this;
+  }
+
+  /** Disable attach/detach (BelongsToMany). */
+  canAttach(value: boolean): this {
+    this._canAttach = value;
+    return this;
+  }
+
+  icon(name: string): this {
+    this._icon = name;
+    return this;
+  }
+
+  perPage(n: number): this {
+    this._perPage = Math.max(1, n);
+    return this;
+  }
+
+  /** Pivot columns to show on a BelongsToMany table (read from `row.pivot`). */
+  pivotColumns(columns: PivotColumn[]): this {
+    this._pivotColumns = columns;
+    return this;
+  }
+
+  /** Cap the number of options listed in the Attach select. */
+  attachLimit(n: number): this {
+    this._attachLimit = Math.max(1, n);
+    return this;
+  }
+
+  isBelongsToMany(): boolean {
+    return this._kind === "belongsToMany";
+  }
+
+  getTitle(): string {
+    return this._title ?? this._resource.getPluralLabel();
+  }
+}
+
+/** A HasMany relation manager (children referencing the parent via `foreignKey`). */
+export function hasMany(resource: ResourceClass, foreignKey: string): RelationManager {
+  return new RelationManager(resource, foreignKey);
+}
+
+/**
+ * A BelongsToMany relation manager. `relationName` is the relationship method on
+ * the *parent* model (e.g. `"roles"`) — its `attach()`/`detach()`/`get()` drive
+ * the pivot. Renders the attached records with Detach + an Attach picker.
+ *
+ *   class UserResource extends Resource {
+ *     static relations() {
+ *       return [belongsToMany(RoleResource, "roles").pivotColumns([{ key: "assigned_at" }])];
+ *     }
+ *   }
+ */
+export function belongsToMany(resource: ResourceClass, relationName: string): RelationManager {
+  const rm = new RelationManager(resource, "");
+  rm._kind = "belongsToMany";
+  rm._relationName = relationName;
+  return rm;
+}

package/src/renderHooks.ts

@@ -0,0 +1,86 @@
+/**
+ * Render hooks — named positions in the panel's chrome that anything can render
+ * into, without owning the page it appears on.
+ *
+ * A contributed page can only add a *page*. A hook can add a banner above every
+ * table, a badge beside the brand, a compliance notice under every form — the
+ * small insertions that otherwise force a fork of the layout:
+ *
+ *   Panel.renderHook("page.header.end", () => <TrialBanner />);
+ *   Panel.renderHook("table.start", (ctx) =>
+ *     ctx.resource === "orders" ? <ShippingNotice /> : null,
+ *   );
+ *
+ * A hook returning `null` renders nothing, which is what makes conditional
+ * placement practical: register once, decide per render.
+ */
+import type { HtmlNode } from "@zerotal/flow";
+
+/**
+ * Where a hook renders. Named for the position rather than the markup, so the
+ * panel's internals can change without breaking a registration.
+ */
+export type RenderHookName =
+  /** Immediately inside the shell, above everything. */
+  | "body.start"
+  /** At the very end of the shell. */
+  | "body.end"
+  /** Beside the brand, at the top of the sidebar. */
+  | "sidebar.start"
+  /** Below the navigation, at the foot of the sidebar. */
+  | "sidebar.end"
+  /** In the top bar, before the panel's own controls. */
+  | "topbar.start"
+  /** In the top bar, after the notification bell and theme toggle. */
+  | "topbar.end"
+  /** Above a page's heading. */
+  | "page.header.start"
+  /** Below a page's heading and actions. */
+  | "page.header.end"
+  /** Directly above a resource's table. */
+  | "table.start"
+  /** Directly below a resource's table. */
+  | "table.end"
+  /** Above a create/edit form's fields. */
+  | "form.start"
+  /** Below a form's fields, above its buttons. */
+  | "form.end"
+  /** Above a record's infolist. */
+  | "record.start"
+  /** Below a record's infolist. */
+  | "record.end";
+
+/** What a hook knows about where it is rendering. */
+export interface RenderHookContext {
+  /** Slug of the resource being rendered, when there is one. */
+  resource?: string | undefined;
+  /** Which screen: the list, a record, a form, or the dashboard. */
+  page?: "list" | "record" | "form" | "dashboard" | undefined;
+  /** The record's id, on a record or edit screen. */
+  recordId?: string | undefined;
+}
+
+export type RenderHook = (context: RenderHookContext) => HtmlNode | string | null;
+
+/**
+ * Resolve every hook registered at `name`, dropping the ones that declined to
+ * render and the ones that threw.
+ *
+ * A hook is decoration: it must not be able to take down the page it decorates,
+ * so a throwing hook is logged and skipped rather than propagated.
+ */
+export function resolveRenderHooks(
+  hooks: RenderHook[],
+  context: RenderHookContext = {},
+): (HtmlNode | string)[] {
+  const out: (HtmlNode | string)[] = [];
+  for (const hook of hooks) {
+    try {
+      const node = hook(context);
+      if (node !== null && node !== undefined) out.push(node);
+    } catch (error) {
+      console.error("[Zerotal Admin] render hook failed:", error);
+    }
+  }
+  return out;
+}

package/src/roles.ts

@@ -0,0 +1,175 @@
+/**
+ * Roles and permissions, as something you can see and change.
+ *
+ * Authorization already works without this: a resource's `can()` answers every
+ * question the panel asks, usually by delegating to a gate. What is missing is
+ * the other direction — being able to look at who can do what, and change it,
+ * without editing code or writing SQL by hand.
+ *
+ * Two halves make that possible.
+ *
+ * The **catalogue** is derived, not declared. {@link panelPermissions} walks the
+ * registered resources, pages and actions and reports every ability the panel
+ * actually checks. That matters because a hand-maintained permission list drifts
+ * the moment somebody adds a resource, and a matrix missing a row is worse than
+ * no matrix — it quietly suggests a permission does not exist.
+ *
+ * The **assignments** are the app's, through a {@link RoleProvider}. Where roles
+ * live and how a user is attached to one differs per application, and the panel
+ * has no business assuming a schema:
+ *
+ *   Panel.roles({ list, permissionsFor, setPermissions });
+ *
+ * With no provider configured the page does not appear, and authorization keeps
+ * working exactly as it did.
+ */
+import type { PanelInstance } from "./PanelInstance.ts";
+import { Action, ActionGroup } from "./actions/Action.ts";
+
+/** One thing a role may be permitted to do. */
+export interface Permission {
+  /** `products.update` — what a `can()` check would be asked. */
+  key: string;
+  /** Human label for the matrix cell's row. */
+  label: string;
+  /** Which resource or page this belongs to, for grouping the matrix. */
+  group: string;
+}
+
+/** A named set of permissions. */
+export interface Role {
+  id: string;
+  name: string;
+  /** Optional description, shown under the name. */
+  description?: string;
+  /**
+   * A role that holds every permission, present and future.
+   *
+   * Worth modelling explicitly rather than by ticking every box: an
+   * administrator should not silently lose access to a resource added next week.
+   */
+  superuser?: boolean;
+}
+
+/** What the app supplies so roles can be listed and edited. */
+export interface RoleProvider {
+  /** Every role, in the order they should appear. */
+  list(): Promise<Role[]> | Role[];
+  /** The permission keys one role currently holds. */
+  permissionsFor(roleId: string): Promise<string[]> | string[];
+  /** Replace a role's permissions with exactly this set. */
+  setPermissions(roleId: string, keys: string[]): Promise<void> | void;
+  /** Create a role. Omit to make roles read-only in the panel. */
+  create?(role: Omit<Role, "id">): Promise<void> | void;
+  /** Delete a role. Omit to forbid deletion from the panel. */
+  remove?(roleId: string): Promise<void> | void;
+}
+
+/** The abilities every resource is checked for, whatever else it declares. */
+const RESOURCE_ABILITIES: { suffix: string; label: string }[] = [
+  { suffix: "viewAny", label: "List" },
+  { suffix: "view", label: "View" },
+  { suffix: "create", label: "Create" },
+  { suffix: "update", label: "Edit" },
+  { suffix: "delete", label: "Delete" },
+];
+
+/** The soft-delete abilities, only meaningful where the model has them. */
+const TRASH_ABILITIES: { suffix: string; label: string }[] = [
+  { suffix: "restore", label: "Restore" },
+  { suffix: "forceDelete", label: "Delete permanently" },
+];
+
+/** Turn an action key into a readable label. */
+function titleCase(key: string): string {
+  return key
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+}
+
+/** Every action a resource offers, with groups flattened into their members. */
+function actionsOf(resource: {
+  recordActions(): unknown[];
+  headerActions(): unknown[];
+  bulkActions(): unknown[];
+}): Action[] {
+  const flatten = (items: unknown[]): Action[] =>
+    items.flatMap((item) =>
+      item instanceof ActionGroup
+        ? (item._actions as Action[])
+        : item instanceof Action
+          ? [item]
+          : [],
+    );
+  return [
+    ...flatten(resource.recordActions()),
+    ...flatten(resource.headerActions()),
+    ...flatten(resource.bulkActions()),
+  ];
+}
+
+/**
+ * Every permission this panel checks, derived from what it has registered.
+ *
+ * Grouped by resource so the matrix reads as one block per thing being
+ * administered. Custom actions come last within their group, because the five
+ * standard abilities are what someone scans for first.
+ */
+export function panelPermissions(panel: PanelInstance): Permission[] {
+  const out: Permission[] = [];
+  const seen = new Set<string>();
+  const add = (key: string, label: string, group: string): void => {
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ key, label, group });
+  };
+
+  for (const resource of panel.resources()) {
+    const slug = resource.getSlug();
+    const group = resource.getPluralLabel();
+
+    for (const { suffix, label } of RESOURCE_ABILITIES) add(`${slug}.${suffix}`, label, group);
+    if (resource.usesSoftDeletes()) {
+      for (const { suffix, label } of TRASH_ABILITIES) add(`${slug}.${suffix}`, label, group);
+    }
+    // An action's key is what `can()` is asked for it, so it belongs in the
+    // matrix on the same footing as the standard abilities.
+    for (const action of actionsOf(resource)) {
+      add(`${slug}.${action._key}`, action.getLabel(), group);
+    }
+  }
+
+  // Pages carry their own ability when they declare one; that is the only thing
+  // guarding them, so it must be visible here.
+  for (const page of panel.registeredPages()) {
+    const ability = page.ability;
+    if (ability) add(ability, titleCase(ability.split(".").pop() ?? ability), "Pages");
+  }
+
+  return out;
+}
+
+/** Group a flat permission list for rendering, preserving order. */
+export function groupPermissions(
+  permissions: Permission[],
+): { group: string; items: Permission[] }[] {
+  const groups: { group: string; items: Permission[] }[] = [];
+  for (const permission of permissions) {
+    const existing = groups.find((g) => g.group === permission.group);
+    if (existing) existing.items.push(permission);
+    else groups.push({ group: permission.group, items: [permission] });
+  }
+  return groups;
+}
+
+/**
+ * Whether a role holds a permission.
+ *
+ * A superuser holds everything by definition, which is what keeps the matrix
+ * honest about what such a role can actually do.
+ */
+export function roleHas(role: Role, held: string[], key: string): boolean {
+  return role.superuser === true || held.includes(key);
+}

package/src/savedViews.ts

@@ -0,0 +1,79 @@
+/**
+ * Saved views — a list, the way someone left it.
+ *
+ * Every bit of list state already lives in the URL: search, filters, tab, sort,
+ * column visibility, grouping, page size. Saving a view is therefore saving a
+ * query string, and restoring one is a link. That is the whole idea.
+ *
+ * Persistence is the app's, for the same reason the notification centre's is:
+ * where a view belongs — a table, a user preference blob, local config — depends
+ * on the application, not on the panel.
+ *
+ *   Panel.savedViews({
+ *     async list(resource) {
+ *       return (await View.query().where("resource", resource).get()).map(toView);
+ *     },
+ *     async save(view) { await View.create({ ...view, userId: Auth.user()!.id }); },
+ *     async remove(id) { await View.destroy(id); },
+ *   });
+ *
+ * With no provider configured the Views control simply doesn't appear.
+ */
+
+/** A stored view: a name, the resource it belongs to, and the query it restores. */
+export interface SavedView {
+  id: string;
+  /** Resource slug this view belongs to. */
+  resource: string;
+  name: string;
+  /** The list's query string, without the leading `?`. */
+  query: string;
+  /** Show this view to everyone rather than only its author. */
+  shared?: boolean;
+}
+
+/** What the app supplies so views can be listed, saved and deleted. */
+export interface SavedViewProvider {
+  /** Views for a resource, in the order they should appear. */
+  list(resource: string): Promise<SavedView[]> | SavedView[];
+  /** Persist a new view. The panel supplies everything but the id. */
+  save(view: Omit<SavedView, "id">): Promise<void> | void;
+  /** Delete one by id. */
+  remove(id: string): Promise<void> | void;
+}
+
+/**
+ * The query-string keys a saved view carries.
+ *
+ * Deliberately explicit rather than "everything in the URL": a saved view should
+ * restore how the list was *shaped*, not which page of it happened to be open,
+ * so `page` is excluded and a restored view always starts at the top.
+ */
+export const VIEW_PARAMS = [
+  "search",
+  "filters",
+  "tab",
+  "sortBy",
+  "sortDir",
+  "sort",
+  "trashed",
+  "perPage",
+  "cols",
+  "group",
+] as const;
+
+/** Reduce a full query string to just the parts a view restores. */
+export function viewQuery(params: URLSearchParams | string): string {
+  const source = typeof params === "string" ? new URLSearchParams(params) : params;
+  const out = new URLSearchParams();
+  for (const key of VIEW_PARAMS) {
+    const value = source.get(key);
+    if (value != null && value !== "") out.set(key, value);
+  }
+  return out.toString();
+}
+
+/** Whether a view matches the list's current state — used to mark the active one. */
+export function viewIsActive(view: SavedView, current: URLSearchParams | string): boolean {
+  return viewQuery(view.query) === viewQuery(current);
+}

package/src/support/ability.ts

@@ -0,0 +1,73 @@
+/**
+ * Ability resolution for panel destinations.
+ *
+ * Resources, pages, widgets and nav entries each name an ability; the panel
+ * consults it twice — once to decide whether to *draw* the entry, and again in
+ * the route guard to decide whether to *serve* it. Drawing and serving share
+ * this one resolver so a hidden destination is also an unreachable one.
+ *
+ * Resolution order, first match wins:
+ *
+ *   1. `authorize` in `config/admin.ts` — the app's own hook, for panels that
+ *      model permissions themselves.
+ *   2. The `gate` binding (`@zerotal/auth`'s `GateService`), resolved from the
+ *      container by name so the auth package stays an optional dependency.
+ *   3. Neither configured — allow only where dev surfaces are allowed. A panel
+ *      with no authorization wired is closed in production-like environments,
+ *      matching {@link AdminGuardMiddleware}'s posture.
+ *
+ * Rule 3 is what makes contributed pages safe to auto-register: a package can
+ * put a page in the sidebar, but it cannot put one in front of a production user
+ * who has no authorization configured.
+ */
+import { tryCurrentApp, isDevSurfaceAllowed } from "@zerotal/core";
+
+/**
+ * The slice of `@zerotal/auth`'s `GateService` the panel uses. Declared locally
+ * and resolved by binding name, so admin never imports the auth package.
+ *
+ * The async form is deliberate: abilities that hit the database return a promise,
+ * and the sync `allows()` treats a promise as truthy — which would wrongly allow.
+ */
+interface GateLike {
+  allowsAsync(ability: string, model?: object): Promise<boolean>;
+}
+
+/** The app's own authorization hook, supplied as `authorize` in `config/admin.ts`. */
+export type AdminAuthorizer = (ability: string) => boolean | Promise<boolean>;
+
+/** Resolve the `gate` binding, or `undefined` when `@zerotal/auth` isn't installed. */
+function gate(): GateLike | undefined {
+  const app = tryCurrentApp();
+  if (!app) return undefined;
+  // `gate` is only a known binding when auth's module augmentation is loaded, which
+  // admin does not import — resolve by name and re-type against the local shape.
+  return app.container.tryMake("gate" as never) as GateLike | undefined;
+}
+
+/**
+ * Whether the current user holds `ability`.
+ *
+ * An `undefined` ability means the destination declares no requirement of its own
+ * and is governed solely by the panel guard — app-authored pages may do this;
+ * package contributions may not (see {@link PageContribution}).
+ *
+ * Never throws: any error resolving the ability denies, so a broken policy closes
+ * the door rather than opening it.
+ */
+export async function resolveAbility(
+  ability: string | undefined,
+  authorizer: AdminAuthorizer | undefined,
+): Promise<boolean> {
+  if (ability === undefined) return true;
+
+  try {
+    if (authorizer) return await authorizer(ability);
+    const g = gate();
+    if (g) return await g.allowsAsync(ability);
+  } catch {
+    return false;
+  }
+
+  return isDevSurfaceAllowed(Bun.env["APP_ENV"] ?? "");
+}

package/src/support/authorize.ts

@@ -0,0 +1,105 @@
+import { ZerotalError } from "@zerotal/core";
+import type { Action } from "../actions/Action.ts";
+import type { ActionContext } from "../actions/Action.ts";
+import type { AdminRecord } from "../Resource.ts";
+import type { ResourceClass } from "../Panel.ts";
+import type { RelationManager } from "../relations/RelationManager.ts";
+
+/**
+ * Server-side authorization for admin RPCs.
+ *
+ * The admin panel exposes its mutations as Flow `@expose` methods, which are dispatched
+ * straight from a client frame: `FlowProvider` resolves the method by name and applies the
+ * client-supplied arguments. Authorization used to be consulted in exactly one place —
+ * `Action.isVisibleFor()`, called while *rendering* the row-action column — so hiding a button
+ * was the entire control. Any user who could load an admin page could call `runAction`,
+ * `runBulkAction`, `deleteRecord` or `deleteRelated` directly with arguments of their choosing.
+ *
+ * The helpers here are the enforcement point. They are deliberately small, deliberately
+ * fail-closed, and deliberately called at the *top* of every exposed handler, before any
+ * argument is used to look something up.
+ */
+
+/**
+ * Raised when an admin RPC is refused. Carries a 403 so the framework's exception handler
+ * renders it correctly if it escapes a Flow action.
+ */
+export class AdminForbiddenError extends ZerotalError {
+  constructor(what: string) {
+    super(`Not authorized: ${what}.`, "E_ADMIN_FORBIDDEN", 403);
+  }
+}
+
+/**
+ * Assert the current user may perform `ability` on `record` for this resource.
+ *
+ * Delegates to `Resource.can()`, which apps override to hit their Gate/policy layer. The
+ * built-in default returns `true`, so this is only as strong as the app's implementation —
+ * but it is now actually *called*, which it previously was not on any mutating path.
+ */
+export function assertCan(
+  resource: ResourceClass,
+  ability: string,
+  record?: AdminRecord | Record<string, unknown>,
+): void {
+  if (!resource.can(ability, record as AdminRecord | undefined)) {
+    throw new AdminForbiddenError(`${ability} on ${resource.getLabel()}`);
+  }
+}
+
+/**
+ * Assert an action may run for this record, applying the same `visible` + `authorize`
+ * predicates the renderer uses to decide whether to draw the button.
+ *
+ * Passing the action through the same gate as the UI is the point: a button the user cannot
+ * see is now a call the user cannot make.
+ */
+export function assertActionAllowed(
+  action: Action,
+  record: AdminRecord | Record<string, unknown> | undefined,
+  ctx: ActionContext,
+): void {
+  if (!action.isVisibleFor(record as AdminRecord | undefined, ctx)) {
+    throw new AdminForbiddenError(`action "${action._key}"`);
+  }
+}
+
+/**
+ * Resolve a relation manager by the slug of the resource it points at, restricted to the
+ * relations this resource actually declares.
+ *
+ * `deleteRelated(slug, id)` used to call `Panel.find(String(slug))`, which resolves *any*
+ * registered resource — so from a page like `/admin/posts/1` a crafted frame could invoke
+ * `deleteRelated("users", 1)` and destroy an unrelated record. Resolving from
+ * `resource.relations()` instead means the slug can only name something this page genuinely
+ * manages.
+ *
+ * @returns the matching relation manager, or `null` when the slug is not a declared relation.
+ */
+export function resolveDeclaredRelation(
+  resource: ResourceClass,
+  slug: string,
+): RelationManager | null {
+  return (
+    resource.relations().find((rel: RelationManager) => rel._resource.getSlug() === slug) ?? null
+  );
+}
+
+/**
+ * Resolve a relation manager by the parent model's relationship *method* name, restricted to
+ * the relations this resource declares as BelongsToMany.
+ *
+ * `attachRelated`/`detachRelated` took a raw method name and invoked it on the parent model,
+ * so any zero-argument method reachable on the model could be called. Only names a relation
+ * manager declares via `_relationName` are accepted now.
+ */
+export function resolveDeclaredRelationByName(
+  resource: ResourceClass,
+  relationName: string,
+): RelationManager | null {
+  return (
+    resource
+      .relations()
+      .find((rel: RelationManager) => rel._relationName === relationName && rel._canAttach) ?? null
+  );
+}

package/src/support/countCache.ts

@@ -0,0 +1,37 @@
+/**
+ * Tab-count caching. The list page's filter-tab badges (`COUNT(*) … WHERE …`)
+ * are read on every list view but only change when a record is created /
+ * updated / deleted. We cache the per-resource count map and let the
+ * {@link AdminProvider} invalidate it from the ORM's `ModelChanged` event, so
+ * counts stay correct no matter where the write came from (admin or otherwise).
+ *
+ * Cache is best-effort: if no cache driver is bound (e.g. isolated tests), the
+ * counts are simply computed each time.
+ */
+import { Cache } from "@zerotal/cache";
+
+const PREFIX = "zerotal:admin:counts:";
+/** Safety-net TTL (1h) in case an invalidation is ever missed. */
+const TTL = 3600;
+
+/** Return the cached tab-count map for a slug, computing + caching on a miss. */
+export async function rememberTabCounts(
+  slug: string,
+  compute: () => Promise<Record<string, number>>,
+): Promise<Record<string, number>> {
+  try {
+    return await Cache.remember(`${PREFIX}${slug}`, TTL, compute);
+  } catch {
+    // No cache bound — fall back to a direct computation.
+    return compute();
+  }
+}
+
+/** Drop the cached counts for a slug (called when its records change). */
+export async function forgetTabCounts(slug: string): Promise<void> {
+  try {
+    await Cache.forget(`${PREFIX}${slug}`);
+  } catch {
+    /* best-effort */
+  }
+}