@zerotal/admin 1.0.0

package/src/authRoles.ts

@@ -0,0 +1,141 @@
+/**
+ * The roles page, driven by the RBAC that `@zerotal/auth` already provides.
+ *
+ * {@link RoleProvider} is deliberately open, because where roles live is the
+ * app's decision. When the answer is the framework's own role-based access
+ * control — roles, permissions, and the `role_permissions` pivot between them —
+ * this builds the provider for you:
+ *
+ *   import { authRoles } from "@zerotal/admin";
+ *
+ *   Panel.roles(authRoles());
+ *
+ * The result is a matrix over the real permissions, not a copy of them: ticking
+ * a box calls `syncPermissions`, so the same checks that already guard the app
+ * start passing immediately.
+ *
+ * `@zerotal/auth` is resolved lazily, so it stays an optional peer.
+ */
+import { frameworkLog } from "@zerotal/core/logger";
+import type { Role, RoleProvider } from "./roles.ts";
+
+export interface AuthRolesOptions {
+  /**
+   * Guard the roles belong to. Defaults to `"web"`, matching the framework's
+   * own default, so most apps need not think about it.
+   */
+  guard?: string;
+  /**
+   * Role names that hold every permission.
+   *
+   * Named rather than inferred, because "administrator" is a convention and not
+   * something the data can tell you. A superuser role is shown as holding
+   * everything and cannot be edited or deleted from the panel.
+   */
+  superusers?: string[];
+}
+
+/** The role surface this needs, kept structural so `auth` stays optional. */
+interface RoleModelLike {
+  id: unknown;
+  name: string;
+  label?: string | null;
+  permissionNames(): Promise<string[]>;
+  syncPermissions(permissions: string[]): Promise<unknown>;
+  delete(): Promise<unknown>;
+}
+
+interface RoleStatics {
+  query(): {
+    where(
+      column: string,
+      value: unknown,
+    ): {
+      orderBy(column: string, direction: string): { get(): Promise<RoleModelLike[]> };
+      first<T>(): Promise<T | null>;
+    };
+  };
+  find(id: unknown): Promise<RoleModelLike | null>;
+  resolve(name: string, guard?: string): Promise<RoleModelLike>;
+}
+
+async function roleModel(): Promise<RoleStatics | null> {
+  try {
+    const mod = (await import(/* @vite-ignore */ "@zerotal/auth" as string)) as {
+      Role?: RoleStatics;
+    };
+    return mod.Role ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a {@link RoleProvider} over the framework's roles and permissions.
+ *
+ * Listing fails soft — an unconfigured database or a missing table yields an
+ * empty page rather than a broken panel — while writes report their failures,
+ * because silently not saving a permission change is the worst outcome here.
+ */
+export function authRoles(options: AuthRolesOptions = {}): RoleProvider {
+  const guard = options.guard ?? "web";
+  const superusers = new Set(
+    (options.superusers ?? ["admin", "administrator"]).map((n) => n.toLowerCase()),
+  );
+
+  const isSuper = (name: string): boolean => superusers.has(name.toLowerCase());
+
+  return {
+    async list(): Promise<Role[]> {
+      try {
+        const Role = await roleModel();
+        if (!Role) return [];
+        const rows = await Role.query().where("guard", guard).orderBy("name", "asc").get();
+        return rows.map((row) => ({
+          id: String(row.id),
+          name: row.label || row.name,
+          superuser: isSuper(row.name),
+        }));
+      } catch (error) {
+        frameworkLog("admin").warn("Roles unavailable", { guard }, error);
+        return [];
+      }
+    },
+
+    async permissionsFor(roleId): Promise<string[]> {
+      try {
+        const Role = await roleModel();
+        const role = await Role?.find(roleId);
+        return (await role?.permissionNames()) ?? [];
+      } catch (error) {
+        frameworkLog("admin").warn("Could not read a role's permissions", { roleId }, error);
+        return [];
+      }
+    },
+
+    async setPermissions(roleId, keys): Promise<void> {
+      const Role = await roleModel();
+      if (!Role) throw new Error("Roles need @zerotal/auth.");
+      const role = await Role.find(roleId);
+      if (!role) return;
+      // Names that do not exist yet are created by `syncPermissions`, which is
+      // what lets the matrix offer a permission before anything has used it.
+      await role.syncPermissions(keys);
+    },
+
+    async create(role): Promise<void> {
+      const Role = await roleModel();
+      if (!Role) throw new Error("Roles need @zerotal/auth.");
+      await Role.resolve(role.name, guard);
+    },
+
+    async remove(roleId): Promise<void> {
+      const Role = await roleModel();
+      if (!Role) throw new Error("Roles need @zerotal/auth.");
+      const role = await Role.find(roleId);
+      // A superuser role is the one nobody should be able to delete themselves
+      // out of, so it is refused here rather than only hidden in the UI.
+      if (role && !isSuper(role.name)) await role.delete();
+    },
+  };
+}

package/src/commands/MakeAdminResourceCommand.ts

@@ -0,0 +1,181 @@
+import { Command } from "@zerotal/core";
+import type { FlagDef } from "@zerotal/core";
+import { pluralize } from "@zerotal/core/helpers";
+
+/**
+ * Scaffolds an admin resource (`bun zt make:admin-resource`).
+ *
+ * Named `make:admin-resource` rather than `make:resource` because that name
+ * already belongs to the API transformer generator — two different things that
+ * would otherwise collide.
+ *
+ * @example
+ * ```bash
+ * bun zt make:admin-resource Product
+ * bun zt make:admin-resource Comment --parent=Post --foreign-key=post_id
+ * bun zt make:admin-resource Setting --singular
+ * ```
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeAdminResourceCommand extends Command {
+  static commandName = "make:admin-resource";
+  static description = "Create an admin panel resource for a model";
+  static needsApp = false;
+  static args = [{ name: "name", required: true, description: "Model name (e.g. Product)" }];
+  static flags: FlagDef[] = [
+    {
+      name: "cluster",
+      type: "string",
+      description: "Cluster class to file the resource under (e.g. ShopCluster)",
+    },
+    {
+      name: "parent",
+      type: "string",
+      description: "Parent resource's model name, for a nested resource",
+    },
+    {
+      name: "foreign-key",
+      type: "string",
+      description: "Foreign key linking to the parent (e.g. post_id)",
+    },
+    {
+      name: "singular",
+      type: "boolean",
+      description: "Back a single row — no list, no create page",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const path = `app/admin/${name}Resource.ts`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    const cluster = this.flags["cluster"] as string | undefined;
+    const parent = this.flags["parent"] as string | undefined;
+    const singular = Boolean(this.flags["singular"]);
+    const foreignKey =
+      (this.flags["foreign-key"] as string | undefined) ?? defaultForeignKey(parent);
+
+    if (parent && !foreignKey) {
+      this.error("A nested resource needs --foreign-key (e.g. --foreign-key=post_id).");
+      return;
+    }
+
+    await Bun.write(path, adminResourceStub({ name, cluster, parent, foreignKey, singular }));
+    this.info(`Created: ${path}`);
+    this.dim(`Register it in app/admin/index.ts:  Panel.register(${name}Resource)`);
+    if (parent || cluster) {
+      // The stub guesses flat paths; a panel split into folders needs them fixed.
+      this.dim("Check the imports at the top if your panel is organised into folders.");
+    }
+  }
+}
+
+/** `Post` → `post_id`, the conventional foreign key naming. */
+function defaultForeignKey(parent: string | undefined): string | undefined {
+  if (!parent) return undefined;
+  return `${parent.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase()}_id`;
+}
+
+export interface AdminResourceStubOptions {
+  name: string;
+  cluster?: string | undefined;
+  parent?: string | undefined;
+  foreignKey?: string | undefined;
+  singular?: boolean | undefined;
+}
+
+/** Returns the source text of an admin resource for `name`. */
+export function adminResourceStub(options: AdminResourceStubOptions): string {
+  const { name, cluster, parent, foreignKey, singular } = options;
+
+  // A singular resource has no list, so it needs neither the read-only view
+  // schema nor an empty state — and importing what it doesn't use would leave
+  // every generated file with a lint warning to clean up.
+  const imports = ["Resource", "text", "textInput", "formSection"];
+  if (!singular) imports.push("section", "textEntry", "createAction");
+
+  const statics: string[] = [`  static override model = ${name};`];
+  const extraImports: string[] = [`import { ${name} } from "@app/models/${name}";`];
+
+  if (cluster) {
+    statics.push(`  static override cluster = ${cluster};`);
+    extraImports.push(`import { ${cluster} } from "@app/admin/clusters";`);
+  }
+  if (parent) {
+    // The parent is named by a function: the two resources reference each other,
+    // and a direct reference would be undefined on one side of the cycle.
+    statics.push(
+      `  static override parent = { resource: () => ${parent}Resource, foreignKey: "${foreignKey}" };`,
+    );
+    extraImports.push(`import { ${parent}Resource } from "@app/admin/${parent}Resource";`);
+  }
+  if (singular) {
+    statics.push("  static override singular = true;");
+  }
+  statics.push('  static override navigationIcon = "collection";');
+  statics.push('  static override recordTitleAttribute = "name";');
+
+  const listBits = singular
+    ? ""
+    : `
+  static override emptyState() {
+    return {
+      heading: "No ${pluralize(name).toLowerCase()} yet",
+      description: "Describe what will fill this list, and how.",
+      icon: "inbox",
+      actions: [createAction()],
+    };
+  }
+`;
+
+  const infolist = singular
+    ? ""
+    : `
+  static override infolist() {
+    return [
+      section("${name}")
+        .columns(2)
+        .schema([textEntry("name").weight("semibold").size("lg")]),
+    ];
+  }
+`;
+
+  return `import {
+${imports.map((i) => `  ${i},`).join("\n")}
+} from "@zerotal/admin";
+${extraImports.join("\n")}
+
+/**
+ * The admin interface for {@link ${name}}.
+ *
+ * Register it in \`app/admin/index.ts\` and its pages exist: a list, a view, and
+ * create/edit forms built from \`form()\`.
+ */
+export class ${name}Resource extends Resource {
+${statics.join("\n")}
+
+  static override columns() {
+    return [
+      text("id").sortable(),
+      text("name").searchable().sortable(),
+      text("createdAt").label("Created").sortable(),
+    ];
+  }
+
+  static override form() {
+    return [
+      formSection("${name}")
+        .columns(2)
+        .schema([textInput("name").required().maxLength(120).columnSpan(2)]),
+    ];
+  }
+${infolist}${listBits}}
+`;
+}

package/src/config.ts

@@ -0,0 +1,128 @@
+import { deepMerge } from "@zerotal/core";
+import type { MiddlewareClass } from "@zerotal/core";
+import type { AdminThemeConfig } from "./theme.ts";
+import type { AdminAuthorizer } from "./support/ability.ts";
+
+/** A single entry in the top-bar user menu. */
+export interface UserMenuItem {
+  label: string;
+  href: string;
+  icon?: string;
+}
+
+/** Top-bar user menu (avatar/identity dropdown). */
+export interface UserMenu {
+  /** Heading shown at the top of the menu (e.g. the signed-in user's name). */
+  label?: string;
+  items: UserMenuItem[];
+}
+
+/**
+ * Auth-pages configuration. When `enabled`, the panel mounts a login screen
+ * (using `@zerotal/auth`'s `Auth.attempt`) and an in-panel profile page (update
+ * details + change password + sign out). Password-reset and email-verification
+ * pages are mounted when their broker hooks are supplied (the admin owns the UI;
+ * the app supplies the data — same split as the notification provider).
+ */
+export interface AdminAuthConfig {
+  /** Mount the auth pages. */
+  enabled?: boolean;
+  /** Login route (relative to the panel path). Default `/login`. */
+  loginPath?: string;
+  /** Profile route (relative to the panel path). Default `/profile`. */
+  profilePath?: string;
+  /** Where to send the user after a successful login. Default the panel root. */
+  redirectTo?: string;
+  /** The credential column users log in with. Default `"email"`. */
+  identifier?: string;
+  /** Show a "remember me" checkbox. Default `true`. */
+  remember?: boolean;
+  /** Heading on the auth screens. Defaults to the panel brand. */
+  heading?: string;
+  /** Extra gate after the password check (e.g. "is the account active?"). */
+  authenticateWhen?: (user: unknown) => boolean | Promise<boolean>;
+  /** Persist profile edits (name/email). Defaults to `user.fill(data); user.save()`. */
+  updateProfile?: (user: unknown, data: Record<string, unknown>) => Promise<void> | void;
+  /** Middleware guarding the guest screens (login/forgot/reset). Default none. */
+  guestMiddleware?: MiddlewareClass[];
+  /** Middleware guarding the profile/verify screens. Defaults to the panel guard. */
+  authMiddleware?: MiddlewareClass[];
+  /** Password-reset broker — mounting the forgot/reset pages when provided. */
+  passwordReset?: {
+    sendResetLink(email: string): Promise<boolean> | boolean;
+    reset(input: { email: string; token: string; password: string }): Promise<boolean> | boolean;
+  };
+  /** Email-verification hooks — mounting the verify page when provided. */
+  emailVerification?: {
+    isVerified(user: unknown): boolean;
+    resend(user: unknown): Promise<void> | void;
+  };
+}
+
+/** Admin panel configuration (read from `config/admin.ts`, with defaults). */
+export interface AdminConfigShape {
+  /** URL prefix the panel mounts under. */
+  path: string;
+  /** Brand name shown in the sidebar. */
+  brand: string;
+  /** Optional short tagline under the brand. */
+  tagline?: string;
+  /**
+   * Middleware guarding every panel route. When left empty, the panel is
+   * default-denied in production-like environments (fail closed) and open only
+   * for local exploration (`APP_ENV=development|local|test`). Set an
+   * auth/authorization middleware before shipping to production, e.g.
+   * `[AuthMiddleware.with({ ... })]`. To deliberately expose it without auth,
+   * pass an explicit pass-through middleware.
+   */
+  middleware?: MiddlewareClass[];
+  /** Optional top-bar user menu (Profile / Logout / …). */
+  userMenu?: UserMenu;
+  /** Styling source — Tailwind Play CDN (default) or a prebuilt stylesheet. */
+  theme?: AdminThemeConfig;
+  /** Auth pages (login / profile / password-reset / email-verification). */
+  auth?: AdminAuthConfig;
+  /**
+   * Decide the abilities named by pages, widgets, nav entries and search
+   * providers. Set this when the app models permissions itself; leave it unset to
+   * resolve through `@zerotal/auth`'s Gate when that package is installed.
+   *
+   * With neither configured, every ability is denied outside a development
+   * environment — a panel with no authorization wired stays closed in production.
+   */
+  authorize?: AdminAuthorizer;
+  /**
+   * Switch contributing packages off by id — `{ monitor: false }` keeps the
+   * monitor provider installed but drops its pages, widgets and nav entries from
+   * the panel. Anything absent here is on.
+   */
+  plugins?: Record<string, boolean>;
+}
+
+export const DEFAULT_ADMIN_CONFIG: AdminConfigShape = {
+  path: "/admin",
+  brand: "Zerotal",
+  tagline: "Admin",
+  middleware: [],
+};
+
+/**
+ * Create a typed admin configuration object with defaults. Function-valued
+ * fields (middleware classes, `authorize`, the auth hooks) pass through by
+ * reference — deepMerge treats them as atomic values.
+ *
+ * @example
+ * // config/admin.ts
+ * import { AdminConfig } from '@zerotal/admin';
+ * export default AdminConfig({ path: '/admin', brand: 'Acme', middleware: [AuthMiddleware] });
+ */
+export function AdminConfig(options: Partial<AdminConfigShape> = {}): AdminConfigShape {
+  return deepMerge(DEFAULT_ADMIN_CONFIG, options);
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    admin: AdminConfigShape;
+  }
+}

package/src/dashboardLayout.ts

@@ -0,0 +1,101 @@
+/**
+ * A dashboard each person can arrange for themselves.
+ *
+ * The dashboard is the page most people look at most often, and what belongs at
+ * the top of it differs by role: the finance lead wants revenue first, support
+ * wants the open-tickets table, and neither wants to scroll past the other's
+ * widget every morning. So the order and visibility of widgets are a per-user
+ * preference, not a code change.
+ *
+ * Deliberately order and visibility, and not a free-form canvas. Dragging boxes
+ * around a grid is a large amount of machinery to maintain, and it mostly
+ * produces layouts that break at the next screen width. Reordering and hiding
+ * covers what people actually ask for, and it stays responsive by construction.
+ *
+ * Storage is the app's, for the same reason the saved views' is:
+ *
+ *   Panel.dashboardLayout({
+ *     async load() { return Auth.user()?.dashboard ?? null; },
+ *     async save(layout) { await Auth.user()?.update({ dashboard: layout }); },
+ *   });
+ *
+ * With no store configured the dashboard renders in declaration order and the
+ * arrange controls do not appear.
+ */
+
+/** One person's arrangement of the dashboard. */
+export interface DashboardLayout {
+  /** Widget keys in the order they should render. */
+  order: string[];
+  /** Widget keys this person has hidden. */
+  hidden: string[];
+}
+
+/** Where a per-user layout is read from and written to. */
+export interface DashboardLayoutStore {
+  /** The current user's layout, or null when they have never arranged it. */
+  load(): Promise<DashboardLayout | null> | DashboardLayout | null;
+  /** Persist the current user's layout. */
+  save(layout: DashboardLayout): Promise<void> | void;
+}
+
+/** An empty layout — the state before anyone has arranged anything. */
+export const EMPTY_LAYOUT: DashboardLayout = { order: [], hidden: [] };
+
+/**
+ * Apply a layout to the widgets a panel declares.
+ *
+ * The declaration is the source of truth for *which* widgets exist; the layout
+ * only says how to arrange them. So a widget added since the layout was saved
+ * still appears (at the end, where it is noticeable rather than lost), and a
+ * widget since removed does not resurrect because a stale key mentions it.
+ */
+export function applyLayout<T>(
+  widgets: T[],
+  keyOf: (widget: T, index: number) => string,
+  layout: DashboardLayout | null,
+): { visible: T[]; hidden: { key: string; widget: T }[] } {
+  const keyed = widgets.map((widget, index) => ({ widget, key: keyOf(widget, index) }));
+  if (!layout) return { visible: widgets, hidden: [] };
+
+  const hiddenKeys = new Set(layout.hidden);
+  const position = new Map(layout.order.map((key, index) => [key, index]));
+
+  const ordered = [...keyed].sort((a, b) => {
+    // Anything the layout does not mention is new, and sorts after everything
+    // it does — so a widget added today is visible without being intrusive.
+    const ai = position.get(a.key) ?? Number.MAX_SAFE_INTEGER;
+    const bi = position.get(b.key) ?? Number.MAX_SAFE_INTEGER;
+    return ai - bi;
+  });
+
+  return {
+    visible: ordered.filter((k) => !hiddenKeys.has(k.key)).map((k) => k.widget),
+    hidden: ordered.filter((k) => hiddenKeys.has(k.key)),
+  };
+}
+
+/** Move one key up or down, returning the new order. */
+export function moveKey(order: string[], key: string, direction: -1 | 1): string[] {
+  const from = order.indexOf(key);
+  if (from === -1) return order;
+  const to = from + direction;
+  if (to < 0 || to >= order.length) return order;
+  const next = [...order];
+  const [moved] = next.splice(from, 1);
+  next.splice(to, 0, moved!);
+  return next;
+}
+
+/**
+ * Fill in a layout's order from the widgets that actually exist.
+ *
+ * A layout saved when there were three widgets cannot reorder a fourth, so the
+ * order is reconciled against the current keys before anything is moved.
+ */
+export function reconcile(layout: DashboardLayout | null, keys: string[]): DashboardLayout {
+  const known = new Set(keys);
+  const order = (layout?.order ?? []).filter((k) => known.has(k));
+  for (const key of keys) if (!order.includes(key)) order.push(key);
+  return { order, hidden: (layout?.hidden ?? []).filter((k) => known.has(k)) };
+}