@terpjs/react-core 0.1.0

package/src/admin/admin.test.tsx

@@ -0,0 +1,537 @@
+// @vitest-environment jsdom
+import { RouterProvider, createMemoryHistory } from "@tanstack/react-router";
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { useEffect } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ModuleManifest } from "@terpjs/contract";
+import type { ComponentType } from "react";
+
+import { withAdminArea } from "../bootstrap";
+import type { AdminAreaSections } from "../bootstrap";
+import { buildAppRouter } from "../router";
+import { Page } from "../Page";
+import { TerpProvider, useAuth } from "../TerpProvider";
+import { ToastProvider } from "../toast";
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  window.localStorage.clear();
+});
+
+// --- withAdminArea: the injection rules ------------------------------------- //
+
+describe("withAdminArea", () => {
+  const appManifests = (): ModuleManifest[] => [
+    { name: "notes", routes: [{ path: "/", view: "NotesList" }], nav: [] },
+  ];
+  const appViews = (): Record<string, ComponentType> => ({ NotesList: () => null });
+
+  it("appends the packaged admin module by default", () => {
+    const { manifests, views } = withAdminArea(appManifests(), appViews(), true);
+    const admin = manifests.find((manifest) => manifest.name === "terp-admin");
+    expect(admin).toBeDefined();
+    expect(admin?.routes.map((route) => route.path)).toContain("/admin");
+    expect(admin?.routes.map((route) => route.path)).toEqual(expect.arrayContaining([
+      "/admin/users/new",
+      "/admin/users/$userId",
+      "/admin/groups/new",
+      "/admin/groups/$groupId",
+    ]));
+    expect(admin?.nav?.[0]?.label).toBe("Admin");
+    expect(views.TerpAdminHub).toBeDefined();
+  });
+
+  it("returns the inputs untouched when disabled", () => {
+    const manifests = appManifests();
+    const views = appViews();
+    const result = withAdminArea(manifests, views, false);
+    expect(result.manifests).toBe(manifests);
+    expect(result.views).toBe(views);
+  });
+
+  it("lets an app route claim a packaged path (that screen is dropped, the rest stay)", () => {
+    const manifests = [
+      ...appManifests(),
+      {
+        name: "custom",
+        routes: [{ path: "/admin/users", view: "MyUsers" }],
+        nav: [],
+      },
+    ];
+    const views = { ...appViews(), MyUsers: (() => null) as ComponentType };
+    const merged = withAdminArea(manifests, views, true);
+    const admin = merged.manifests.find((manifest) => manifest.name === "terp-admin");
+    expect(admin?.routes.map((route) => route.path)).not.toContain("/admin/users");
+    expect(admin?.routes.map((route) => route.path)).toContain("/admin/groups");
+    expect(merged.views.TerpAdminUsers).toBeUndefined();
+    expect(merged.views.MyUsers).toBeDefined();
+  });
+
+  it("drops the Admin nav entry when the app claims the hub itself", () => {
+    const manifests = [
+      ...appManifests(),
+      { name: "custom", routes: [{ path: "/admin", view: "MyHub" }], nav: [] },
+    ];
+    const views = { ...appViews(), MyHub: (() => null) as ComponentType };
+    const merged = withAdminArea(manifests, views, true);
+    const admin = merged.manifests.find((manifest) => manifest.name === "terp-admin");
+    expect(admin?.nav).toEqual([]);
+    expect(admin?.routes.map((route) => route.path)).toContain("/admin/users");
+  });
+
+  it("ships a capability-selective area from a sections object", () => {
+    const { manifests, views } = withAdminArea(appManifests(), appViews(), {
+      groups: false,
+    });
+    const admin = manifests.find((manifest) => manifest.name === "terp-admin");
+    const paths = admin?.routes.map((route) => route.path) ?? [];
+    expect(paths).toContain("/admin");
+    expect(paths).toContain("/admin/users");
+    expect(paths).toContain("/admin/audit");
+    expect(paths.some((path) => path.startsWith("/admin/groups"))).toBe(false);
+    expect(views.TerpAdminGroups).toBeUndefined();
+    expect(views.TerpAdminGroupCreate).toBeUndefined();
+    expect(views.TerpAdminHub).toBeDefined();
+    // Omitted flags default to true: an empty object is the full area.
+    const full = withAdminArea(appManifests(), appViews(), {});
+    const fullAdmin = full.manifests.find((manifest) => manifest.name === "terp-admin");
+    expect(fullAdmin?.routes).toHaveLength(8);
+    expect(full.views.TerpAdminHub).toBe(withAdminArea(appManifests(), appViews(), true).views.TerpAdminHub);
+  });
+
+  it("keeps the Admin nav and hub when only some sections are dropped", () => {
+    const { manifests } = withAdminArea(appManifests(), appViews(), {
+      users: false,
+      groups: false,
+    });
+    const admin = manifests.find((manifest) => manifest.name === "terp-admin");
+    expect(admin?.nav?.[0]?.label).toBe("Admin");
+    expect(admin?.routes.map((route) => route.path)).toEqual(["/admin", "/admin/audit"]);
+  });
+
+  it("refuses a view-id collision that claims no path (a silent drop would dead-link the hub)", () => {
+    const manifests = [
+      ...appManifests(),
+      { name: "custom", routes: [{ path: "/other", view: "TerpAdminUsers" }], nav: [] },
+    ];
+    const views = { ...appViews(), TerpAdminUsers: (() => null) as ComponentType };
+    expect(() => withAdminArea(manifests, views, true)).toThrow(/TerpAdminUsers/);
+  });
+});
+
+// --- the packaged screens, end to end through the router --------------------- //
+
+function LogInOnMount() {
+  const auth = useAuth();
+  useEffect(() => {
+    void auth.login({ email: "admin@example.com", password: "pw" });
+  }, []);
+  return null;
+}
+
+const emptyPage = { items: [], total: 0, skip: 0, limit: 1 };
+
+function stubAdminFetch() {
+  const fetchMock = vi.fn<typeof fetch>(async (input) => {
+    const request = input as Request;
+    const url = new URL(request.url);
+    const path = url.pathname;
+    if (path.endsWith("/api/v1/auth/login")) {
+      return jsonResponse({ access_token: "t", token_type: "bearer" });
+    }
+    if (path.endsWith("/api/v1/me/")) {
+      return jsonResponse({
+        id: "a1",
+        email: "admin@example.com",
+        role_rank: 30,
+        role_name: "admin",
+      });
+    }
+    if (path.endsWith("/api/v1/users/u1")) {
+      if (request.method === "PATCH") {
+        return jsonResponse({
+          id: "u1",
+          email: "jane.doe@example.com",
+          role: 10,
+          is_active: true,
+          created_at: "2026-07-01T10:00:00Z",
+          updated_at: "2026-07-02T10:00:00Z",
+          version: 2,
+        });
+      }
+      return jsonResponse({
+        id: "u1",
+        email: "jane.doe@example.com",
+        role: 20,
+        is_active: true,
+        created_at: "2026-07-01T10:00:00Z",
+        updated_at: "2026-07-01T10:00:00Z",
+        version: 1,
+      });
+    }
+    if (path.endsWith("/api/v1/users/u2")) {
+      return jsonResponse({
+        id: "u2",
+        email: "new.account@example.com",
+        role: 10,
+        is_active: true,
+        created_at: "2026-07-02T10:00:00Z",
+        updated_at: "2026-07-02T10:00:00Z",
+        version: 1,
+      });
+    }
+    if (path.endsWith("/api/v1/users/")) {
+      if (request.method === "POST") {
+        return jsonResponse({
+          id: "u2",
+          email: "new.account@example.com",
+          role: 10,
+          is_active: true,
+          created_at: "2026-07-02T10:00:00Z",
+          updated_at: "2026-07-02T10:00:00Z",
+          version: 1,
+        });
+      }
+      // The directory search behind the member picker filters by email substring.
+      if (url.searchParams.get("email") === "new.user") {
+        return jsonResponse({
+          items: [
+            {
+              id: "u9",
+              email: "new.user@example.com",
+              role: 10,
+              is_active: true,
+              created_at: "2026-07-01T10:00:00Z",
+              updated_at: "2026-07-01T10:00:00Z",
+              version: 1,
+            },
+          ],
+          total: 1,
+          skip: 0,
+          limit: 20,
+        });
+      }
+      return jsonResponse({
+        items: [
+          {
+            id: "u1",
+            email: "jane.doe@example.com",
+            role: 20,
+            is_active: true,
+            created_at: "2026-07-01T10:00:00Z",
+            updated_at: "2026-07-01T10:00:00Z",
+            version: 1,
+          },
+        ],
+        total: 7,
+        skip: 0,
+        limit: 10,
+      });
+    }
+    if (path.endsWith("/members") && request.method === "POST") {
+      return jsonResponse({
+        id: "m2",
+        group_id: "g1",
+        user_id: "u9",
+        email: "new.user@example.com",
+        created_at: "2026-07-02T10:00:00Z",
+      });
+    }
+    if (path.endsWith("/members")) {
+      return jsonResponse({
+        items: [
+          {
+            id: "m1",
+            group_id: "g1",
+            user_id: "u1",
+            email: "jane.doe@example.com",
+            created_at: "2026-07-01T10:00:00Z",
+          },
+        ],
+        total: 1,
+        skip: 0,
+        limit: 200,
+      });
+    }
+    if (path.endsWith("/api/v1/groups/g1")) {
+      return jsonResponse({
+        id: "g1",
+        name: "Finance",
+        description: "money",
+        member_count: 1,
+        version: 1,
+        created_at: "2026-07-01T10:00:00Z",
+        updated_at: "2026-07-01T10:00:00Z",
+      });
+    }
+    if (path.endsWith("/api/v1/groups/g2")) {
+      return jsonResponse({
+        id: "g2",
+        name: "Operations",
+        description: "Daily operations",
+        member_count: 0,
+        version: 1,
+        created_at: "2026-07-02T10:00:00Z",
+        updated_at: "2026-07-02T10:00:00Z",
+      });
+    }
+    if (path.endsWith("/api/v1/groups/")) {
+      if (request.method === "POST") {
+        return jsonResponse({
+          id: "g2",
+          name: "Operations",
+          description: "Daily operations",
+          member_count: 0,
+          version: 1,
+          created_at: "2026-07-02T10:00:00Z",
+          updated_at: "2026-07-02T10:00:00Z",
+        });
+      }
+      return jsonResponse({
+        items: [
+          {
+            id: "g1",
+            name: "Finance",
+            description: "money",
+            member_count: 1,
+            version: 1,
+            created_at: "2026-07-01T10:00:00Z",
+            updated_at: "2026-07-01T10:00:00Z",
+          },
+        ],
+        total: 3,
+        skip: 0,
+        limit: 10,
+      });
+    }
+    if (path.endsWith("/api/v1/audit/")) {
+      return jsonResponse(emptyPage);
+    }
+    return jsonResponse(emptyPage);
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+function renderAdminApp(
+  initialPath: string,
+  roleRank = 30,
+  adminArea: boolean | AdminAreaSections = true,
+) {
+  const manifests: ModuleManifest[] = [
+    { name: "notes", routes: [{ path: "/", view: "NotesList" }], nav: [] },
+  ];
+  const views: Record<string, ComponentType> = {
+    NotesList: () => <Page title="Notes">notes</Page>,
+  };
+  const merged = withAdminArea(manifests, views, adminArea);
+  const router = buildAppRouter(merged.manifests, {
+    views: merged.views,
+    title: "Terp",
+    history: createMemoryHistory({ initialEntries: [initialPath] }),
+  });
+  const fetchMock = stubAdminFetch();
+  if (roleRank !== 30) {
+    fetchMock.mockImplementation(async (input) => {
+      const url = (input as Request).url;
+      if (url.endsWith("/api/v1/auth/login")) {
+        return jsonResponse({ access_token: "t", token_type: "bearer" });
+      }
+      return jsonResponse({
+        id: "v1",
+        email: "viewer@example.com",
+        role_rank: roleRank,
+        role_name: "viewer",
+      });
+    });
+  }
+  render(
+    <TerpProvider baseUrl="https://api.test">
+      <ToastProvider>
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </ToastProvider>
+    </TerpProvider>,
+  );
+  return { fetchMock, router };
+}
+
+describe("the packaged admin area", () => {
+  it("serves the hub at /admin with cards into users, groups and audit", async () => {
+    renderAdminApp("/admin");
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { level: 1, name: "Admin" })).toBeInTheDocument(),
+    );
+    expect(screen.getByRole("link", { name: /Users/ })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: /Groups/ })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: /Audit log/ })).toBeInTheDocument();
+    // Live totals from the limit=1 probes reach the cards.
+    await waitFor(() => expect(screen.getByText("7")).toBeInTheDocument());
+    expect(screen.getByText("3")).toBeInTheDocument();
+    // The sidebar carries the single admin-gated entry.
+    expect(screen.getByRole("link", { name: "Admin" })).toBeInTheDocument();
+  });
+
+  it("serves a capability-selective hub: dropped sections lose card, route and stat call", async () => {
+    const { fetchMock } = renderAdminApp("/admin", 30, { groups: false });
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { level: 1, name: "Admin" })).toBeInTheDocument(),
+    );
+    expect(screen.getByRole("link", { name: /Users/ })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: /Audit log/ })).toBeInTheDocument();
+    expect(screen.queryByRole("link", { name: /Groups/ })).not.toBeInTheDocument();
+    // The users stat still arrives; the groups endpoint is never probed (its
+    // capability may not be mounted at all).
+    await waitFor(() => expect(screen.getByText("7")).toBeInTheDocument());
+    const probed = fetchMock.mock.calls.map((call) => (call[0] as Request).url);
+    expect(probed.some((url) => url.includes("/api/v1/groups/"))).toBe(false);
+  });
+
+  it("uses the users overview action and clickable rows for dedicated pages", async () => {
+    renderAdminApp("/admin/users");
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { level: 1, name: "Users" })).toBeInTheDocument(),
+    );
+    expect(screen.getByRole("button", { name: "Provision user" })).toBeInTheDocument();
+    await waitFor(() => expect(screen.getByText("jane.doe@example.com")).toBeInTheDocument());
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toHaveTextContent("Admin");
+
+    fireEvent.click(screen.getByText("jane.doe@example.com"));
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { level: 1, name: "jane.doe@example.com" })).toBeInTheDocument(),
+    );
+    expect(screen.getByRole("button", { name: "Reset password" })).toBeInTheDocument();
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toHaveTextContent("Users");
+  });
+
+  it("provisions a user on a dedicated create page and redirects to its detail", async () => {
+    const { fetchMock } = renderAdminApp("/admin/users");
+    await screen.findByRole("heading", { level: 1, name: "Users" });
+    fireEvent.click(screen.getByRole("button", { name: "Provision user" }));
+    await screen.findByRole("heading", { level: 1, name: "Provision user" });
+
+    fireEvent.change(screen.getByLabelText("Email"), {
+      target: { value: "new.account@example.com" },
+    });
+    fireEvent.change(screen.getByLabelText("Password"), { target: { value: "strong-password" } });
+    fireEvent.click(screen.getByRole("button", { name: "Provision user" }));
+
+    await screen.findByRole("heading", { level: 1, name: "new.account@example.com" });
+    expect(fetchMock.mock.calls.some(([input]) => {
+      const request = input as Request;
+      return request.method === "POST" && request.url.endsWith("/api/v1/users/");
+    })).toBe(true);
+  });
+
+  it("confirms lifecycle mutations from the user detail action slot", async () => {
+    const { fetchMock } = renderAdminApp("/admin/users/u1");
+    await screen.findByRole("heading", { level: 1, name: "jane.doe@example.com" });
+    fireEvent.click(screen.getByRole("button", { name: "More actions" }));
+    fireEvent.click(screen.getByRole("menuitem", { name: "Make viewer" }));
+    expect(screen.getByRole("dialog", { name: "Make viewer" })).toBeInTheDocument();
+    expect(fetchMock.mock.calls.some(([input]) => (input as Request).method === "PATCH")).toBe(false);
+
+    fireEvent.click(screen.getByRole("button", { name: "Confirm" }));
+    await waitFor(() =>
+      expect(fetchMock.mock.calls.some(([input]) => (input as Request).method === "PATCH")).toBe(true),
+    );
+  });
+
+  it("clears user mutation state when navigating between detail records in place", async () => {
+    const { router } = renderAdminApp("/admin/users/u1");
+    await screen.findByRole("heading", { level: 1, name: "jane.doe@example.com" });
+    fireEvent.click(screen.getByRole("button", { name: "Reset password" }));
+    fireEvent.change(screen.getByLabelText("New password"), {
+      target: { value: "must-not-cross-records" },
+    });
+    expect(screen.getByRole("dialog", { name: /Reset password/ })).toBeInTheDocument();
+
+    await act(async () => {
+      await router.navigate({
+        to: "/admin/users/$userId",
+        params: { userId: "u2" },
+      });
+    });
+    await screen.findByRole("heading", { level: 1, name: "new.account@example.com" });
+    expect(screen.queryByRole("dialog", { name: /Reset password/ })).not.toBeInTheDocument();
+    expect(screen.queryByDisplayValue("must-not-cross-records")).not.toBeInTheDocument();
+  });
+
+  it("uses the groups overview action and rows for create/detail navigation", async () => {
+    renderAdminApp("/admin/groups");
+    await screen.findByRole("heading", { level: 1, name: "Groups" });
+    await screen.findByText("Finance");
+
+    fireEvent.click(screen.getByRole("button", { name: "Create group" }));
+    await screen.findByRole("heading", { level: 1, name: "Create group" });
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toHaveTextContent("Groups");
+  });
+
+  it("serves the group detail: API-resolved member emails and a searched member picker", async () => {
+    const { fetchMock } = renderAdminApp("/admin/groups/g1");
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { level: 1, name: "Finance" })).toBeInTheDocument(),
+    );
+    // The member row shows the email the backend resolved (no client-side directory).
+    await waitFor(() => expect(screen.getByText("jane.doe@example.com")).toBeInTheDocument());
+
+    // Typing searches the directory server-side (debounced) and suggests matches…
+    fireEvent.change(screen.getByPlaceholderText("Email"), {
+      target: { value: "new.user" },
+    });
+    await waitFor(() =>
+      expect(
+        fetchMock.mock.calls.some(([input]) =>
+          (input as Request).url.includes("email=new.user"),
+        ),
+      ).toBe(true),
+    );
+
+    // …and submitting the full address resolves it to the account id for the POST.
+    fireEvent.change(screen.getByPlaceholderText("Email"), {
+      target: { value: "new.user@example.com" },
+    });
+    fireEvent.submit(screen.getByRole("button", { name: "Add member" }).closest("form")!);
+    await waitFor(() =>
+      expect(
+        fetchMock.mock.calls.some(([input]) => {
+          const request = input as Request;
+          return request.method === "POST" && request.url.endsWith("/groups/g1/members");
+        }),
+      ).toBe(true),
+    );
+  });
+
+  it("clears group destructive state when navigating between detail records in place", async () => {
+    const { router } = renderAdminApp("/admin/groups/g1");
+    await screen.findByRole("heading", { level: 1, name: "Finance" });
+    fireEvent.click(screen.getAllByRole("button", { name: "More actions" })[0]!);
+    fireEvent.click(screen.getByRole("menuitem", { name: "Delete group" }));
+    expect(screen.getByRole("dialog", { name: /Delete group/ })).toBeInTheDocument();
+
+    await act(async () => {
+      await router.navigate({
+        to: "/admin/groups/$groupId",
+        params: { groupId: "g2" },
+      });
+    });
+    await screen.findByRole("heading", { level: 1, name: "Operations" });
+    expect(screen.queryByRole("dialog", { name: /Delete group/ })).not.toBeInTheDocument();
+  });
+
+  it("denies the area to a non-admin (nav hidden, route refused)", async () => {
+    renderAdminApp("/admin", 10);
+    await waitFor(() =>
+      expect(screen.getByText("You do not have access to this page.")).toBeInTheDocument(),
+    );
+    expect(screen.queryByRole("link", { name: "Admin" })).not.toBeInTheDocument();
+  });
+});

package/src/admin/crumbs.tsx

@@ -0,0 +1,14 @@
+import { Link } from "@tanstack/react-router";
+
+import type { BreadcrumbItem, RenderBreadcrumbLink } from "../Breadcrumbs";
+import type { TerpStrings } from "../uiText";
+
+/** The admin hub's crumb — every admin overview breadcrumbs back to `/admin`. */
+export function adminCrumb(strings: TerpStrings): BreadcrumbItem {
+  return { label: strings.admin, to: "/admin" };
+}
+
+/** Ancestor crumbs link through the TanStack router (no raw same-app anchors). */
+export const renderAdminCrumb: RenderBreadcrumbLink = (item) => (
+  <Link to={item.to}>{item.label}</Link>
+);

package/src/admin/module.tsx

@@ -0,0 +1,51 @@
+import { defineModuleManifest } from "@terpjs/contract";
+
+import type { TerpModule } from "../bootstrap";
+
+import { AdminHub } from "./AdminHub";
+import { AuditLogAdmin } from "./AuditLogAdmin";
+import { GroupDetail } from "./GroupDetail";
+import { GroupCreate } from "./GroupCreate";
+import { GroupsAdmin } from "./GroupsAdmin";
+import { UserCreate } from "./UserCreate";
+import { UserDetail } from "./UserDetail";
+import { UsersAdmin } from "./UsersAdmin";
+
+/**
+ * The packaged administration area every Terp app ships: one admin-gated "Admin"
+ * sidebar entry opening a hub (`/admin`) whose cards lead to the users, groups and
+ * audit-log overviews — the UI over the base-profile capabilities the backend
+ * mounts in every app (users, groups + access, audit; ADR 0074). The whole area is
+ * `role: "admin"` end to end; the backend re-checks every call regardless.
+ *
+ * `renderTerpApp` injects it by default (`adminArea: false` opts out; an app
+ * manifest claiming one of its paths overrides that screen). An L2 composition
+ * (`buildAppRouter`) spreads it in explicitly: append `adminModule.manifest` to the
+ * manifests and merge `adminModule.views` into the views map.
+ */
+export const adminModule: TerpModule = {
+  manifest: defineModuleManifest({
+    name: "terp-admin",
+    routes: [
+      { path: "/admin", view: "TerpAdminHub", role: "admin" },
+      { path: "/admin/users", view: "TerpAdminUsers", role: "admin" },
+      { path: "/admin/users/new", view: "TerpAdminUserCreate", role: "admin" },
+      { path: "/admin/users/$userId", view: "TerpAdminUserDetail", role: "admin" },
+      { path: "/admin/groups", view: "TerpAdminGroups", role: "admin" },
+      { path: "/admin/groups/new", view: "TerpAdminGroupCreate", role: "admin" },
+      { path: "/admin/groups/$groupId", view: "TerpAdminGroupDetail", role: "admin" },
+      { path: "/admin/audit", view: "TerpAdminAudit", role: "admin" },
+    ],
+    nav: [{ label: "Admin", to: "/admin", icon: "shield", role: "admin" }],
+  }),
+  views: {
+    TerpAdminHub: AdminHub,
+    TerpAdminUsers: UsersAdmin,
+    TerpAdminUserCreate: UserCreate,
+    TerpAdminUserDetail: UserDetail,
+    TerpAdminGroups: GroupsAdmin,
+    TerpAdminGroupCreate: GroupCreate,
+    TerpAdminGroupDetail: GroupDetail,
+    TerpAdminAudit: AuditLogAdmin,
+  },
+};

package/src/admin/roles.ts

@@ -0,0 +1,19 @@
+import type { TerpStrings } from "../uiText";
+
+export interface AdminRoleOption {
+  rank: number;
+  label: string;
+}
+
+/** The packaged role ladder, localized through the active framework catalog. */
+export function adminRoleOptions(strings: TerpStrings): AdminRoleOption[] {
+  return [
+    { rank: 10, label: strings.roleViewer },
+    { rank: 20, label: strings.roleEditor },
+    { rank: 30, label: strings.roleAdmin },
+  ];
+}
+
+export function adminRoleLabel(strings: TerpStrings, rank: number): string {
+  return adminRoleOptions(strings).find((option) => option.rank === rank)?.label ?? `rank ${rank}`;
+}

package/src/bootstrap.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+import { cleanup, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { defineModuleManifest } from "@terpjs/contract";
+
+import { collectModules, renderTerpApp } from "./bootstrap";
+
+afterEach(() => {
+  cleanup();
+});
+
+const notesModule = {
+  manifest: defineModuleManifest({
+    name: "notes",
+    routes: [{ path: "/", view: "NotesList" }],
+    nav: [{ label: "Notes", to: "/" }],
+  }),
+  views: { NotesList: () => <h1>Notes</h1> },
+};
+
+describe("collectModules", () => {
+  it("merges manifests and views from module files", () => {
+    const { manifests, views } = collectModules({
+      "./modules/notes/module.tsx": notesModule,
+    });
+    expect(manifests.map((manifest) => manifest.name)).toEqual(["notes"]);
+    expect(Object.keys(views)).toEqual(["NotesList"]);
+  });
+
+  it("rejects a module that does not export manifest/views", () => {
+    expect(() => collectModules({ "./modules/bad/module.tsx": {} })).toThrow(/must export/);
+  });
+
+  it("rejects duplicate view ids instead of silently overwriting a module", () => {
+    expect(() =>
+      collectModules({
+        "./modules/notes/module.tsx": notesModule,
+        "./modules/tasks/module.tsx": {
+          manifest: defineModuleManifest({
+            name: "tasks",
+            routes: [{ path: "/tasks", view: "NotesList" }],
+            nav: [{ label: "Tasks", to: "/tasks" }],
+          }),
+          views: { NotesList: () => <h1>Tasks</h1> },
+        },
+      }),
+    ).toThrow(/exported by more than one module/);
+  });
+});
+
+describe("renderTerpApp", () => {
+  it("mounts the app and shows the login view while signed out", async () => {
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+
+    renderTerpApp({
+      title: "Test",
+      modules: { "./modules/notes/module.tsx": notesModule },
+      rootElement: root,
+    });
+
+    await waitFor(() =>
+      expect(screen.getByRole("button", { name: /sign in/i })).toBeInTheDocument(),
+    );
+    root.remove();
+  });
+});