@zerotal/admin 1.0.0

package/src/plugin.ts

@@ -0,0 +1,283 @@
+/**
+ * The panel's contribution surface — how packages other than the app itself add
+ * functionality to the admin.
+ *
+ * The panel is a *host*: it publishes the write surface below, binds it into the
+ * container as `admin.panel`, and never names a single contributor. A package
+ * contributes by resolving that binding at boot and pushing into it:
+ *
+ *   // packages/queue/src/admin.ts
+ *   interface AdminHost {                       // declared locally — no admin dependency
+ *     enabled(id: string): boolean;
+ *     page(c: { slug: string; page: unknown; title: string; ability: string }): void;
+ *   }
+ *
+ *   export function installQueueAdmin(app: Application): void {
+ *     const panel = app.container.tryMake("admin.panel" as never) as AdminHost | undefined;
+ *     if (!panel?.enabled("queue")) return;
+ *     panel.page({ slug: "jobs", page: JobsPage, title: "Jobs", ability: "queue.view" });
+ *   }
+ *
+ * Called from the contributing provider's `onBooted`, this is zero-config for the
+ * app — installing both providers is enough — and costs nothing when the admin
+ * isn't installed, because the binding simply isn't there. It mirrors how the
+ * observability sinks are wired, so there is one extension idiom to learn.
+ *
+ * Apps use the more direct door: an {@link AdminPlugin} passed to `Panel.plugin()`,
+ * or an {@link AdminPage} subclass passed to `Panel.pages()`.
+ */
+import type { HtmlNode } from "@zerotal/flow";
+import type { DashboardWidget } from "./widgets/Widget.ts";
+import type { BadgeTone } from "./table/Column.ts";
+import type { ClusterClass } from "./Cluster.ts";
+import type { RenderHookContext } from "./renderHooks.ts";
+
+/**
+ * A page component class, structurally — a Flow `Component` subclass.
+ *
+ * Typed as a bare zero-argument constructor on purpose. It's what Flow's router
+ * actually does with a page class, and it lets a contributing package hand one
+ * over without importing anything from `@zerotal/admin`. The panel gives the page
+ * its own layout when it mounts the route, so a contributed page renders only its
+ * content and inherits the panel's chrome.
+ */
+export type PanelPageClass = new () => object;
+
+/**
+ * A page contributed by a package.
+ *
+ * `ability` is **required** here, unlike on an app-authored {@link AdminPage}.
+ * Contributions register themselves without the app asking, so the ability is the
+ * only thing standing between a package's page and every user who can reach the
+ * panel — a contributed page with no ability would be a package deciding who sees
+ * production internals, which is not the package's decision to make.
+ */
+export interface PageContribution {
+  /** Path under the panel root, without leading slash — `"jobs"`, `"monitor/requests"`. */
+  slug: string;
+  /** The page component class. Mounted with the panel's layout and guard. */
+  page: PanelPageClass;
+  /** Page title, and the navigation label unless `navigationLabel` overrides it. */
+  title: string;
+  /** Ability required to see the nav entry and open the route. */
+  ability: string;
+  /** Sidebar label, when it should differ from the title. */
+  navigationLabel?: string;
+  /** Icon name from the panel's icon set. */
+  navigationIcon?: string;
+  /** Sidebar group heading. Ungrouped entries sort above every group. */
+  navigationGroup?: string;
+  /** A cluster to file this page under, sharing its URL segment and nav entry. */
+  cluster?: ClusterClass;
+  /** Sort weight within the group. Ties break alphabetically. */
+  navigationSort?: number;
+  /** Mount the route but keep it out of the sidebar (detail pages, drill-ins). */
+  showInNavigation?: boolean;
+  /**
+   * Extra route patterns mounted onto the same page, relative to `slug` — e.g.
+   * `[":section"]` so one page serves `/jobs` and `/jobs/failed`.
+   */
+  routeParams?: string[];
+  /** A count pill beside the sidebar entry. Failures are swallowed. */
+  navigationBadge?: () => Promise<string | number | null> | string | number | null;
+  /** Tone of the navigation badge. */
+  navigationBadgeColor?: BadgeTone;
+}
+
+// ── Consoles ─────────────────────────────────────────────────────────────────
+
+/**
+ * A row in a console table — whatever shape the contributing package hands over.
+ */
+export type ConsoleRow = Record<string, unknown>;
+
+/** One column of a console table. */
+export interface ConsoleColumn {
+  /** Property read from the row. */
+  key: string;
+  label: string;
+  align?: "start" | "center" | "end";
+  /** Render in a monospace face — ids, class names, error text. */
+  mono?: boolean;
+  /** Turn the raw value into display text. Defaults to `String(value)`. */
+  format?: (value: unknown, row: ConsoleRow) => string;
+  /** Render the cell as a badge in this tone, or `null` for plain text. */
+  badge?: (value: unknown, row: ConsoleRow) => BadgeTone | null;
+}
+
+/** An action offered on every row of a console table. */
+export interface ConsoleAction {
+  key: string;
+  label: string;
+  icon?: string;
+  danger?: boolean;
+  /** Ask for confirmation with this message before running. */
+  confirm?: string;
+  /** Run against one row. Return a message to flash on success. */
+  run: (row: ConsoleRow) => Promise<string | void> | string | void;
+}
+
+/** An action in a console tab's header — operating on the tab, not on a row. */
+export interface ConsoleHeaderAction {
+  key: string;
+  label: string;
+  icon?: string;
+  danger?: boolean;
+  confirm?: string;
+  run: () => Promise<string | void> | string | void;
+}
+
+/** One tab of a console — a table, plus what can be done to it. */
+export interface ConsoleTab {
+  key: string;
+  label: string;
+  /** Explanatory line under the heading. */
+  description?: string;
+  columns: ConsoleColumn[];
+  rows: () => Promise<ConsoleRow[]> | ConsoleRow[];
+  /** Property identifying a row, used for morph keys. Defaults to `"id"`. */
+  rowKey?: string;
+  rowActions?: ConsoleAction[];
+  headerActions?: ConsoleHeaderAction[];
+  /** Shown in place of an empty table. */
+  empty?: string;
+  /** A count pill on the tab itself. */
+  badge?: () => Promise<number | null> | number | null;
+}
+
+/**
+ * A read-and-act page described as data rather than built as a component.
+ *
+ * Most packages want the same page: some tables, a few buttons, no bespoke
+ * layout. Describing that instead of rendering it means the contributing package
+ * needs no JSX, no `@zerotal/flow` dependency and no build configuration —
+ * the panel owns the markup, so every console also looks like the rest of the
+ * admin without trying to.
+ *
+ * Reach for {@link PageContribution} instead when a page genuinely needs its own
+ * component: charts, a custom layout, its own reactive state.
+ */
+export interface ConsoleContribution {
+  /** Path under the panel root, without leading slash. */
+  slug: string;
+  title: string;
+  /** Ability required to see the nav entry and open the route. */
+  ability: string;
+  tabs: ConsoleTab[];
+  navigationLabel?: string;
+  navigationIcon?: string;
+  navigationGroup?: string;
+  navigationSort?: number;
+  showInNavigation?: boolean;
+  /** A count pill beside the sidebar entry. Failures are swallowed. */
+  navigationBadge?: () => Promise<string | number | null> | string | number | null;
+  /** Tone of the navigation badge. */
+  navigationBadgeColor?: BadgeTone;
+}
+
+/** A dashboard widget contributed by a package. */
+export interface WidgetContribution {
+  widget: DashboardWidget;
+  /** Ability required to see this widget on the dashboard. */
+  ability: string;
+  /** Sort weight among contributed widgets. Lower renders first. */
+  sort?: number;
+}
+
+/** A sidebar link that points somewhere the panel doesn't mount itself. */
+export interface NavContribution {
+  label: string;
+  href: string;
+  icon?: string;
+  group?: string;
+  sort?: number;
+  /** Ability required to see the link. */
+  ability: string;
+  /** Open in a new tab and skip client-side navigation. */
+  external?: boolean;
+}
+
+/** One result row from a contributed search provider. */
+export interface SearchHit {
+  label: string;
+  href: string;
+  description?: string;
+}
+
+/**
+ * A source of global-search results beyond the registered resources — log lines,
+ * jobs, audit entries, anything with a stable URL.
+ */
+export interface PanelSearchProvider {
+  /** Stable id, used for the opt-out check and as the result group key. */
+  id: string;
+  /** Group heading shown above this provider's hits. */
+  label: string;
+  icon?: string;
+  /** Ability required to search this source. */
+  ability: string;
+  search(term: string): Promise<SearchHit[]> | SearchHit[];
+}
+
+/** A status pill, indicator, or control rendered in the panel's top bar. */
+export interface TopbarSlot {
+  id: string;
+  /** Ability required to render the slot. */
+  ability: string;
+  /** Lower renders further left. */
+  sort?: number;
+  render(): HtmlNode | Promise<HtmlNode>;
+}
+
+/** An extra entry in the top-bar user menu. */
+export interface UserMenuContribution {
+  label: string;
+  href: string;
+  icon?: string;
+  sort?: number;
+  /** Ability required to see the entry. */
+  ability: string;
+}
+
+/**
+ * The panel's write surface, bound into the container as `admin.panel`.
+ *
+ * Contributors should declare their own minimal copy of the members they use
+ * rather than importing this type, so they depend on the admin package at build
+ * time not at all.
+ */
+export interface AdminPanelHost {
+  /**
+   * Whether the app has left this contributor switched on. Check it first and
+   * return early — `plugins: { monitor: false }` in `config/admin.ts` turns a
+   * contributor off without uninstalling its provider.
+   */
+  enabled(id: string): boolean;
+  page(contribution: PageContribution): void;
+  /**
+   * Add a table-and-actions page described as data. The cheaper door — no
+   * component, no JSX, no dependency on Flow.
+   */
+  console(contribution: ConsoleContribution): void;
+  widget(contribution: WidgetContribution): void;
+  navItem(contribution: NavContribution): void;
+  searchProvider(provider: PanelSearchProvider): void;
+  topbarSlot(slot: TopbarSlot): void;
+  userMenuItem(item: UserMenuContribution): void;
+  /**
+   * Render into a named position in the panel's chrome — a banner above every
+   * table, a notice under every form. See `RenderHookName` for the positions.
+   */
+  renderHook(name: string, hook: (context: RenderHookContext) => HtmlNode | string | null): void;
+}
+
+/**
+ * The app-side door into the same registry. Where a package pushes itself in via
+ * the container binding, an app names what it wants:
+ *
+ *   Panel.plugin({ id: "billing", install: (panel) => panel.page({ … }) });
+ */
+export interface AdminPlugin {
+  id: string;
+  install(panel: AdminPanelHost): void | Promise<void>;
+}

package/src/provider/AdminAbilityMiddleware.ts

@@ -0,0 +1,25 @@
+import { BaseMiddleware } from "@zerotal/core";
+import type { NextFn, HttpContext } from "@zerotal/core";
+import { Panel } from "../Panel.ts";
+
+/**
+ * Enforces a page's declared ability at the route.
+ *
+ * The sidebar already hides destinations the user may not reach, but hiding a
+ * link is presentation, not access control — the URL is still typeable. This
+ * middleware runs the *same* {@link Panel.can} check the sidebar used, so the two
+ * can't drift: what you cannot see, you cannot open.
+ *
+ * Mounted per page by {@link AdminProvider}, on top of the panel-wide guard.
+ */
+export class AdminAbilityMiddleware extends BaseMiddleware<{ ability?: string | undefined }> {
+  protected options: { ability?: string | undefined } = {};
+
+  async handle(_http: HttpContext, next: NextFn): Promise<Response | void> {
+    if (await Panel.can(this.options.ability)) return next();
+    return new Response("Not authorized.\n", {
+      status: 403,
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+    });
+  }
+}

package/src/provider/AdminGuardMiddleware.ts

@@ -0,0 +1,29 @@
+import { BaseMiddleware, isDevSurfaceAllowed } from "@zerotal/core";
+import type { NextFn, HttpContext } from "@zerotal/core";
+
+/**
+ * Fail-closed default guard for the admin panel.
+ *
+ * The panel exposes full CRUD, so shipping it with no guard is a footgun. When
+ * `config/admin.ts` declares no `middleware`, the provider installs this guard
+ * so the panel is **denied by default** in any production-like environment
+ * (unset/unknown `APP_ENV`, `staging`, `production`). Local exploration
+ * (`APP_ENV=development|local|test`) still passes through.
+ *
+ * To run the panel in production, set `middleware` in `config/admin.ts` to a
+ * real auth/authorization stack (e.g. `[AuthMiddleware.with({ ... })]`). To
+ * *deliberately* expose it without auth, set an explicit pass-through
+ * middleware — an intentional, visible opt-out rather than a silent default.
+ */
+export class AdminGuardMiddleware extends BaseMiddleware {
+  protected options = {};
+
+  async handle(_http: HttpContext, next: NextFn): Promise<Response | void> {
+    if (isDevSurfaceAllowed(Bun.env["APP_ENV"] ?? "")) return next();
+    return new Response(
+      "Admin panel is not accessible: no authentication is configured.\n" +
+        "Set `middleware` in config/admin.ts to a real auth guard before exposing it.\n",
+      { status: 403, headers: { "Content-Type": "text/plain; charset=utf-8" } },
+    );
+  }
+}

package/src/provider/AdminProvider.ts

@@ -0,0 +1,334 @@
+/**
+ * AdminProvider — wires the admin panel into the application.
+ *
+ * Just register `AdminProvider`; it depends on `FlowProvider` (which installs the
+ * `Router.flow()` macro and the WebSocket runtime the pages rely on), so Flow is
+ * pulled in automatically and guaranteed to boot first — you do not have to list it:
+ *
+ *   import { AdminProvider } from "@zerotal/admin";
+ *   export default [AdminProvider];   // FlowProvider comes along via dependsOn
+ *
+ * On boot it loads `app/admin.ts` (where you call `Panel.register(...)`), then
+ * mounts a Dashboard page plus one List page per registered resource under the
+ * configured path (default `/admin`).
+ *
+ * It also publishes the panel as a *host*: `admin.panel` is bound during
+ * `onRegister`, so any provider can contribute pages, widgets, nav entries and
+ * search providers from its own `onBooting` without depending on this package.
+ * Routes are mounted in `onBooted`, once every contribution is in.
+ */
+import { ServiceProvider, Router, FrameworkEvents } from "@zerotal/core";
+import type { ModelChanged } from "@zerotal/orm";
+import type { AppEnvironment, MiddlewareClass, HttpContext } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import { FlowProvider } from "@zerotal/flow";
+import { Panel } from "../Panel.ts";
+import type { PanelInstance } from "../PanelInstance.ts";
+import { pagePath } from "../PanelInstance.ts";
+import { AdminGuardMiddleware } from "./AdminGuardMiddleware.ts";
+import { AdminAbilityMiddleware } from "./AdminAbilityMiddleware.ts";
+import type { AdminPanelHost } from "../plugin.ts";
+import type { AdminConfigShape } from "../config.ts";
+import { makeDashboardPage } from "../pages/DashboardPage.tsx";
+import { makeSearchPage } from "../pages/SearchPage.tsx";
+import { makeNotificationsPage } from "../pages/NotificationsPage.tsx";
+import { makeMediaPage } from "../pages/MediaPage.tsx";
+import { makeRolesPage } from "../pages/RolesPage.tsx";
+import { makeResourceListPage } from "../pages/ResourceListPage.tsx";
+import { makeRecordViewPage } from "../pages/RecordViewPage.tsx";
+import { ResourceFormPage, registerResourceForm } from "../pages/ResourceFormPage.tsx";
+import { makeConsolePage } from "../pages/ConsolePage.tsx";
+import { makeResourceForm } from "../form/index.ts";
+import { forgetTabCounts } from "../support/countCache.ts";
+import { hostedPage } from "../support/hostPage.ts";
+import { frameworkLog } from "@zerotal/core/logger";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    /** The panel's contribution surface — see `plugin.ts`. */
+    "admin.panel": AdminPanelHost;
+  }
+}
+
+export class AdminProvider extends ServiceProvider {
+  static override provides = ["admin.panel"] as const;
+  // The panel mounts HTTP routes via Flow's `Router.flow()` macro, so Flow must
+  // boot first — declared here so registering AdminProvider pulls it in automatically.
+  static override dependsOn = [FlowProvider];
+
+  // The panel mounts HTTP routes via Flow's `Router.flow()` macro, so serving
+  // only happens where Flow serves. `console` boots this provider anyway, but
+  // solely to register `make:admin-resource` — see `_servesHttp()`, which returns
+  // before any route mounting there.
+  static override environments: AppEnvironment[] = ["web", "test", "console"];
+
+  override onRegister(): void {
+    // Merge config/admin.ts (if present) into the panel configuration. This runs
+    // before any provider's onBooting, so the `plugins` opt-out is already in
+    // place by the time a contributor asks whether it is enabled — which is why
+    // that flag belongs in config/admin.ts rather than app/admin.ts.
+    try {
+      const config = this.app.container.makeSync("config") as ConfigManager;
+      const adminCfg = config.get<Partial<AdminConfigShape>>("admin");
+      if (adminCfg) Panel.configure(adminCfg);
+    } catch {
+      // No config bound (e.g. in isolated tests) — defaults apply.
+    }
+
+    // Publish the contribution surface. Bound here, in the registration phase, so
+    // every other provider can reach it from onBooting regardless of boot order —
+    // contributors deliberately do not (and must not) depend on this provider.
+    this.app.container.singleton("admin.panel", () => Panel.host());
+  }
+
+  private _disposeCountInvalidation: (() => void) | undefined;
+
+  override async onBooting(): Promise<void> {
+    // CLI generators first: `console` boots this provider only to register them,
+    // and returns before any of the serving work below.
+    this._registerCommands();
+    if (!this._servesHttp()) return;
+
+    await this._autodiscover();
+    this._watchModelChanges();
+  }
+
+  /**
+   * True only where the panel actually serves. `console`/`repl` boot this
+   * provider just for its generators — there is no `Router.flow()` there, and
+   * nothing to serve.
+   */
+  private _servesHttp(): boolean {
+    const env = this.app.environment;
+    return env !== "console" && env !== "repl";
+  }
+
+  /**
+   * Register the panel's generator. Lazy, so the command's module — and the stub
+   * text it carries — stays out of the serving path.
+   */
+  private _registerCommands(): void {
+    const runner = this.app.container.tryMake("commands");
+    if (!runner) return;
+    runner.registerLazy("make:admin-resource", () =>
+      import("../commands/MakeAdminResourceCommand.ts").then((m) => m.MakeAdminResourceCommand),
+    );
+  }
+
+  /**
+   * Mount the panel's routes.
+   *
+   * Deferred to `onBooted` because contributions arrive during the booting phase:
+   * every provider's `onBooting` has run by now, so the page registry is complete
+   * and each contributed page gets a route.
+   */
+  override async onBooted(): Promise<void> {
+    if (!this._servesHttp()) return;
+    for (const panel of Panel.all()) {
+      this._registerRoutes(panel);
+      await this._registerAuthRoutes(panel);
+    }
+  }
+
+  /**
+   * Mount a panel's auth pages when it called `auth({ enabled: true })`. Loaded
+   * via a dynamic import so the `@zerotal/auth` dependency stays optional
+   * otherwise.
+   */
+  private async _registerAuthRoutes(panel: PanelInstance): Promise<void> {
+    if (!panel.authConfig()) return;
+    try {
+      const { registerAuthRoutes } = await import("../auth/register.ts");
+      registerAuthRoutes(panel.base(), this._effectiveGuard(panel.config().middleware));
+    } catch (err) {
+      frameworkLog("admin").warn(
+        "Auth pages require @zerotal/auth to be installed",
+        undefined,
+        err,
+      );
+    }
+  }
+
+  /**
+   * Invalidate a resource's cached tab counts whenever one of its records is
+   * created / updated / deleted — wherever that write originates (the admin,
+   * a controller, a seeder). Matches by model name, then backing table.
+   */
+  private _watchModelChanges(): void {
+    this._disposeCountInvalidation = FrameworkEvents.on<ModelChanged>("ModelChanged", (e) => {
+      for (const panel of Panel.all()) {
+        for (const resource of panel.resources()) {
+          const model = resource.model as { name?: string; table?: string } | undefined;
+          if (model?.name === e.model || model?.table === e.table) {
+            void forgetTabCounts(resource.getSlug());
+          }
+        }
+      }
+    });
+  }
+
+  override async onStopping(): Promise<void> {
+    this._disposeCountInvalidation?.();
+    this._disposeCountInvalidation = undefined;
+  }
+
+  /**
+   * Load the app's panel wiring so its `Panel.register(...)` /
+   * `Panel.configure(...)` calls run.
+   *
+   * A single `app/admin.ts` is enough for a handful of resources. Past that,
+   * apps split the panel into `app/admin/` — a file per resource and an
+   * `index.ts` that registers them — so both spellings are honoured, the file
+   * first.
+   */
+  private async _autodiscover(): Promise<void> {
+    const candidates = [`${process.cwd()}/app/admin.ts`, `${process.cwd()}/app/admin/index.ts`];
+    for (const file of candidates) {
+      try {
+        if (!(await Bun.file(file).exists())) continue;
+        await import(file);
+        return;
+      } catch (err) {
+        frameworkLog("admin").warn(`Failed to load ${file}`, { file }, err);
+        return;
+      }
+    }
+  }
+
+  /**
+   * Resolve the guard applied to panel routes. An explicit, non-empty
+   * `middleware` from config/admin.ts is used as-is. Otherwise the panel is
+   * default-denied in production-like environments via {@link AdminGuardMiddleware}
+   * — the secure default is closed. Set an explicit pass-through middleware to
+   * intentionally expose the panel without auth.
+   */
+  private _effectiveGuard(configured: MiddlewareClass[] | undefined): MiddlewareClass[] {
+    if (configured && configured.length > 0) return configured;
+    return [AdminGuardMiddleware];
+  }
+
+  /** Mount the dashboard + a List page per resource under one panel's path. */
+  private _registerRoutes(panel: PanelInstance): void {
+    const path = panel.base();
+    // Guard every panel route with the configured middleware. When none is set,
+    // fall back to a fail-closed default guard that denies the panel in any
+    // production-like environment — so an app that forgets to configure auth
+    // does not silently expose full CRUD. See _effectiveGuard().
+    const guard: MiddlewareClass[] = this._effectiveGuard(panel.config().middleware);
+
+    const flow = (
+      Router as unknown as {
+        flow?: (p: string, page: unknown, mw?: MiddlewareClass[]) => unknown;
+      }
+    ).flow;
+    if (typeof flow !== "function") {
+      throw new Error(
+        "[Zerotal Admin] Router.flow() is unavailable — register FlowProvider before AdminProvider.",
+      );
+    }
+
+    Router.group({ prefix: path, middleware: guard }, () => {
+      flow("", makeDashboardPage(panel));
+      flow("/search", makeSearchPage(panel));
+      flow("/notifications", makeNotificationsPage(panel));
+      // Mounted only when the panel has somewhere to catalogue files; without a
+      // provider the page would be a permanent empty state.
+      if (panel.mediaProvider()) flow("/media", makeMediaPage(panel));
+      if (panel.roleProvider()) flow("/roles", makeRolesPage(panel));
+
+      // Leaving an impersonation. A plain GET rather than a page: it does one
+      // thing and sends you back, so there is nothing to render. Inside the
+      // group, so it carries the panel's prefix and guard already.
+      class StopImpersonating {
+        async handle(http: HttpContext): Promise<void> {
+          const { stopImpersonating } = await import("../impersonation.ts");
+          await stopImpersonating();
+          http.redirect(path || "/");
+        }
+      }
+      Router.get("/stop-impersonating", StopImpersonating, "handle");
+
+      // Custom pages — the app's own AdminPage subclasses and anything packages
+      // contributed. Each carries its declared ability as a second guard on top
+      // of the panel-wide one, so the route enforces exactly what the sidebar
+      // used to decide whether to draw the link.
+      for (const page of panel.registeredPages()) {
+        const pageGuard: MiddlewareClass[] = [
+          AdminAbilityMiddleware.with({ ability: page.ability }),
+        ];
+        // A clustered page also answers to its cluster's ability.
+        if (page.cluster?.ability) {
+          pageGuard.push(AdminAbilityMiddleware.with({ ability: page.cluster.ability }));
+        }
+        const hosted = hostedPage(page.page);
+        const path = pagePath(page);
+        flow(`/${path}`, hosted, pageGuard);
+        for (const param of page.routeParams) {
+          flow(`/${path}/${param.replace(/^\//, "")}`, hosted, pageGuard);
+        }
+      }
+
+      // Consoles — contributed table-and-action pages, rendered by the panel from
+      // the description the package handed over.
+      for (const console of panel.consoles()) {
+        flow(`/${console.slug}`, makeConsolePage(console, panel), [
+          AdminAbilityMiddleware.with({ ability: console.ability }),
+        ]);
+      }
+
+      for (const resource of panel.resources()) {
+        const slug = resource.getSlug();
+        const model = resource.getModelName();
+        // Where this resource's pages live: bare, inside a cluster, or under a
+        // parent record. The resource owns that decision — see `routePath()`.
+        const path = `/${resource.routePath()}`;
+        // A cluster's ability gates every route inside it, so a member never has
+        // to restate it. Resources carry their own record-level `can()` too.
+        const clusterGuard: MiddlewareClass[] = resource.cluster?.ability
+          ? [AdminAbilityMiddleware.with({ ability: resource.cluster.ability })]
+          : [];
+
+        const fields = resource.isEditable() ? resource.form() : [];
+        if (resource.isEditable()) {
+          const create = makeResourceForm(fields, "create", `${model}CreateForm`);
+          const edit = makeResourceForm(fields, "edit", `${model}EditForm`);
+          // One shared page class serves every resource's Create/Edit route; it
+          // resolves which panel/resource/mode it is serving from the URL via
+          // this registry.
+          registerResourceForm(panel.id, slug, {
+            resource,
+            create: { FormClass: create.FormClass, fields: create.fields },
+            edit: { FormClass: edit.FormClass, fields: edit.fields },
+          });
+        }
+
+        // A singular resource is one row: its index *is* the edit form, and it
+        // has no list, no create page and no id segment.
+        if (resource.singular) {
+          if (resource.isEditable()) flow(path, ResourceFormPage, clusterGuard);
+          continue;
+        }
+
+        flow(path, makeResourceListPage(resource, panel), clusterGuard);
+
+        // The static `/create` route is registered before the `:id` view so it
+        // wins over the param segment.
+        if (resource.isEditable()) {
+          flow(`${path}/create`, ResourceFormPage, clusterGuard);
+          flow(
+            `${path}/:${resource.primaryKey}`,
+            makeRecordViewPage(resource, panel),
+            clusterGuard,
+          );
+          flow(`${path}/:${resource.primaryKey}/edit`, ResourceFormPage, clusterGuard);
+        } else {
+          flow(
+            `${path}/:${resource.primaryKey}`,
+            makeRecordViewPage(resource, panel),
+            clusterGuard,
+          );
+        }
+      }
+    });
+  }
+}