feat(admin): add IA shell and protected section skeleton routes

TODO.md

@@ -32,20 +32,20 @@ This file is the single source of truth for roadmap and delivery progress.
 - [x] [P1] First-start onboarding route for initial owner creation (`/welcome`)
 - [x] [P1] Split auth entry points (`/welcome`, `/login`, `/register`) with cross-links
 - [x] [P2] Support fallback sign-in route (`/support/:key`) as break-glass access
-- [~] [P1] Reusable CRUD base patterns (list/detail/editor/service/repository)
-- [~] [P1] Shared CRUD validation strategy (Zod + server-side enforcement)
-- [~] [P1] Shared error and audit hooks for CRUD mutations
+- [x] [P1] Reusable CRUD base patterns (list/detail/editor/service/repository)
+- [x] [P1] Shared CRUD validation strategy (Zod + server-side enforcement)
+- [x] [P1] Shared error and audit hooks for CRUD mutations
 
 ### Admin App
 
 - [x] [P1] Separate Next.js admin app in monorepo
 - [x] [P1] App Router + TypeScript + `src/` structure
 - [x] [P1] Shared DB access via `@cms/db`
-- [~] [P2] Base admin dashboard shell and roadmap page (`/todo`)
+- [x] [P2] Base admin dashboard shell and roadmap page (`/todo`)
 - [x] [P1] Authentication and session model (`admin`, `editor`, `manager`)
 - [x] [P1] Protected admin routes and session handling
-- [~] [P1] Temporary admin posts CRUD sandbox for baseline functional validation
-- [~] [P1] Core admin IA (pages/media/users/commissions/settings)
+- [x] [P1] Temporary admin posts CRUD sandbox for baseline functional validation
+- [x] [P1] Core admin IA (pages/media/users/commissions/settings)
 
 ### Public App
 
@@ -203,6 +203,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [2026-02-10] Admin self-registration policy is now managed via `/settings` and persisted in `system_setting`; env var is fallback/default only.
 - [2026-02-10] E2E now runs with deterministic preparation (`test:e2e:prepare`: generate + migrate deploy + seed) before Playwright execution.
 - [2026-02-10] CI quality workflow `.gitea/workflows/ci.yml` enforces `check`, `typecheck`, `test`, and `test:e2e` against a PostgreSQL service.
+- [2026-02-10] Admin app now uses a shared shell with permission-aware navigation and dedicated IA routes (`/pages`, `/media`, `/users`, `/commissions`).
 
 ## How We Use This File
 

apps/admin/src/app/commissions/page.tsx

@@ -0,0 +1,34 @@
+import { AdminSectionPlaceholder } from "@/components/admin-section-placeholder"
+import { AdminShell } from "@/components/admin-shell"
+import { requirePermissionForRoute } from "@/lib/route-guards"
+
+export const dynamic = "force-dynamic"
+
+export default async function CommissionsManagementPage() {
+  const role = await requirePermissionForRoute({
+    nextPath: "/commissions",
+    permission: "commissions:read",
+    scope: "own",
+  })
+
+  return (
+    <AdminShell
+      role={role}
+      activePath="/commissions"
+      badge="Admin App"
+      title="Commissions"
+      description="Prepare commissions intake and kanban workflow tooling."
+    >
+      <AdminSectionPlaceholder
+        feature="Commissions Workflow"
+        summary="This route is reserved for request intake, ownership assignment, and kanban transitions."
+        requiredPermission="commissions:read (own)"
+        nextSteps={[
+          "Add commissions board with status columns.",
+          "Add assignment, due-date, and notes editing.",
+          "Add transition rules and audit history.",
+        ]}
+      />
+    </AdminShell>
+  )
+}

apps/admin/src/app/media/page.tsx

@@ -0,0 +1,34 @@
+import { AdminSectionPlaceholder } from "@/components/admin-section-placeholder"
+import { AdminShell } from "@/components/admin-shell"
+import { requirePermissionForRoute } from "@/lib/route-guards"
+
+export const dynamic = "force-dynamic"
+
+export default async function MediaManagementPage() {
+  const role = await requirePermissionForRoute({
+    nextPath: "/media",
+    permission: "media:read",
+    scope: "team",
+  })
+
+  return (
+    <AdminShell
+      role={role}
+      activePath="/media"
+      badge="Admin App"
+      title="Media"
+      description="Prepare media library and enrichment workflows."
+    >
+      <AdminSectionPlaceholder
+        feature="Media Library"
+        summary="This route is ready for media browsing, upload, and metadata refinement features."
+        requiredPermission="media:read (team)"
+        nextSteps={[
+          "Add media upload and asset listing.",
+          "Add enrichment fields (alt text, source, tags).",
+          "Add artwork-specific refinement fields.",
+        ]}
+      />
+    </AdminShell>
+  )
+}

apps/admin/src/app/page.tsx

@@ -5,11 +5,10 @@ import { revalidatePath } from "next/cache"
 import Link from "next/link"
 import { redirect } from "next/navigation"
 
-import { AdminLocaleSwitcher } from "@/components/admin-locale-switcher"
+import { AdminShell } from "@/components/admin-shell"
 import { translateMessage } from "@/i18n/messages"
 import { getAdminMessages, resolveAdminLocale } from "@/i18n/server"
-import { resolveRoleFromServerContext } from "@/lib/access-server"
-import { LogoutButton } from "./logout-button"
+import { requirePermissionForRoute } from "@/lib/route-guards"
 
 export const dynamic = "force-dynamic"
 
@@ -39,11 +38,11 @@ function readOptionalField(formData: FormData, field: string): string | undefine
 }
 
 async function requireNewsWritePermission() {
-  const role = await resolveRoleFromServerContext()
-
-  if (!role || !hasPermission(role, "news:write", "team")) {
-    redirect("/unauthorized?required=news:write&scope=team")
-  }
+  await requirePermissionForRoute({
+    nextPath: "/",
+    permission: "news:write",
+    scope: "team",
+  })
 }
 
 function redirectWithState(params: { notice?: string; error?: string }) {
@@ -156,15 +155,11 @@ export default async function AdminHomePage({
 }: {
   searchParams: Promise<SearchParamsInput>
 }) {
-  const role = await resolveRoleFromServerContext()
-
-  if (!role) {
-    redirect("/login?next=/")
-  }
-
-  if (!hasPermission(role, "news:read", "team")) {
-    redirect("/unauthorized?required=news:read&scope=team")
-  }
+  const role = await requirePermissionForRoute({
+    nextPath: "/",
+    permission: "news:read",
+    scope: "team",
+  })
 
   const [resolvedSearchParams, locale, posts] = await Promise.all([
     searchParams,
@@ -179,21 +174,14 @@ export default async function AdminHomePage({
   const canCreatePost = hasPermission(role, "news:write", "team")
 
   return (
-    <main className="mx-auto flex min-h-screen w-full max-w-4xl flex-col gap-8 px-6 py-16">
-      <header className="space-y-3">
-        <div className="flex items-center justify-between gap-3">
-          <p className="text-sm uppercase tracking-[0.2em] text-neutral-500">
-            {t("dashboard.badge", "Admin App")}
-          </p>
-          <AdminLocaleSwitcher />
-        </div>
-        <h1 className="text-4xl font-semibold tracking-tight">
-          {t("dashboard.title", "Content Dashboard")}
-        </h1>
-        <p className="text-neutral-600">
-          {t("dashboard.description", "Manage posts from a dedicated admin surface.")}
-        </p>
-        <div className="flex items-center gap-3 pt-2">
+    <AdminShell
+      role={role}
+      activePath="/"
+      badge={t("dashboard.badge", "Admin App")}
+      title={t("dashboard.title", "Content Dashboard")}
+      description={t("dashboard.description", "Manage posts from a dedicated admin surface.")}
+      actions={
+        <>
           <Link
             href="/todo"
             className="inline-flex rounded-md border border-neutral-300 px-4 py-2 text-sm font-medium hover:bg-neutral-100"
@@ -206,10 +194,9 @@ export default async function AdminHomePage({
           >
             {t("settings.title", "Settings")}
           </Link>
-          <LogoutButton />
-        </div>
-      </header>
-
+        </>
+      }
+    >
       {notice ? (
         <section className="rounded-xl border border-emerald-300 bg-emerald-50 px-4 py-3 text-sm text-emerald-800">
           {notice}
@@ -413,6 +400,6 @@ export default async function AdminHomePage({
           ))}
         </div>
       </section>
-    </main>
+    </AdminShell>
   )
 }

apps/admin/src/app/pages/page.tsx

@@ -0,0 +1,34 @@
+import { AdminSectionPlaceholder } from "@/components/admin-section-placeholder"
+import { AdminShell } from "@/components/admin-shell"
+import { requirePermissionForRoute } from "@/lib/route-guards"
+
+export const dynamic = "force-dynamic"
+
+export default async function PagesManagementPage() {
+  const role = await requirePermissionForRoute({
+    nextPath: "/pages",
+    permission: "pages:read",
+    scope: "team",
+  })
+
+  return (
+    <AdminShell
+      role={role}
+      activePath="/pages"
+      badge="Admin App"
+      title="Pages"
+      description="Manage page entities and publication workflows."
+    >
+      <AdminSectionPlaceholder
+        feature="Page Management"
+        summary="This MVP0 scaffold defines information architecture and access boundaries for future page CRUD."
+        requiredPermission="pages:read (team)"
+        nextSteps={[
+          "Add page entity list and search.",
+          "Add create/edit draft flows with validation.",
+          "Add publish/unpublish scheduling controls.",
+        ]}
+      />
+    </AdminShell>
+  )
+}

apps/admin/src/app/settings/page.tsx

@@ -1,14 +1,13 @@
-import { hasPermission } from "@cms/content/rbac"
 import { isAdminSelfRegistrationEnabled, setAdminSelfRegistrationEnabled } from "@cms/db"
 import { Button } from "@cms/ui/button"
 import { revalidatePath } from "next/cache"
 import Link from "next/link"
 import { redirect } from "next/navigation"
 
-import { AdminLocaleSwitcher } from "@/components/admin-locale-switcher"
+import { AdminShell } from "@/components/admin-shell"
 import { translateMessage } from "@/i18n/messages"
 import { getAdminMessages, resolveAdminLocale } from "@/i18n/server"
-import { resolveRoleFromServerContext } from "@/lib/access-server"
+import { requirePermissionForRoute } from "@/lib/route-guards"
 
 type SearchParamsInput = Promise<Record<string, string | string[] | undefined>>
 
@@ -21,15 +20,11 @@ function toSingleValue(input: string | string[] | undefined): string | null {
 }
 
 async function requireSettingsPermission() {
-  const role = await resolveRoleFromServerContext()
-
-  if (!role) {
-    redirect("/login?next=/settings")
-  }
-
-  if (!hasPermission(role, "users:manage_roles", "global")) {
-    redirect("/unauthorized?required=users:manage_roles&scope=global")
-  }
+  await requirePermissionForRoute({
+    nextPath: "/settings",
+    permission: "users:manage_roles",
+    scope: "global",
+  })
 }
 
 async function getSettingsTranslator() {
@@ -85,7 +80,11 @@ async function updateRegistrationPolicyAction(formData: FormData) {
 }
 
 export default async function SettingsPage({ searchParams }: { searchParams: SearchParamsInput }) {
-  await requireSettingsPermission()
+  const role = await requirePermissionForRoute({
+    nextPath: "/settings",
+    permission: "users:manage_roles",
+    scope: "global",
+  })
 
   const [params, locale, isRegistrationEnabled] = await Promise.all([
     searchParams,
@@ -99,31 +98,24 @@ export default async function SettingsPage({ searchParams }: { searchParams: Sea
   const error = toSingleValue(params.error)
 
   return (
-    <main className="mx-auto flex min-h-screen w-full max-w-4xl flex-col gap-8 px-6 py-16">
-      <header className="space-y-3">
-        <div className="flex items-center justify-between gap-3">
-          <p className="text-sm uppercase tracking-[0.2em] text-neutral-500">
-            {t("settings.badge", "Admin Settings")}
-          </p>
-          <AdminLocaleSwitcher />
-        </div>
-        <h1 className="text-4xl font-semibold tracking-tight">{t("settings.title", "Settings")}</h1>
-        <p className="text-neutral-600">
-          {t(
-            "settings.description",
-            "Manage runtime policies for the admin authentication and onboarding flow.",
-          )}
-        </p>
-        <div className="flex items-center gap-3 pt-2">
-          <Link
-            href="/"
-            className="inline-flex rounded-md border border-neutral-300 px-4 py-2 text-sm font-medium hover:bg-neutral-100"
-          >
-            {t("settings.actions.backToDashboard", "Back to dashboard")}
-          </Link>
-        </div>
-      </header>
-
+    <AdminShell
+      role={role}
+      activePath="/settings"
+      badge={t("settings.badge", "Admin Settings")}
+      title={t("settings.title", "Settings")}
+      description={t(
+        "settings.description",
+        "Manage runtime policies for the admin authentication and onboarding flow.",
+      )}
+      actions={
+        <Link
+          href="/"
+          className="inline-flex rounded-md border border-neutral-300 px-4 py-2 text-sm font-medium hover:bg-neutral-100"
+        >
+          {t("settings.actions.backToDashboard", "Back to dashboard")}
+        </Link>
+      }
+    >
       {notice ? (
         <section className="rounded-xl border border-emerald-300 bg-emerald-50 px-4 py-3 text-sm text-emerald-800">
           {notice}
@@ -183,6 +175,6 @@ export default async function SettingsPage({ searchParams }: { searchParams: Sea
           </form>
         </div>
       </section>
-    </main>
+    </AdminShell>
   )
 }

apps/admin/src/app/todo/page.tsx

@@ -1,10 +1,9 @@
 import { readFile } from "node:fs/promises"
 import path from "node:path"
-import { hasPermission } from "@cms/content/rbac"
 import Link from "next/link"
-import { redirect } from "next/navigation"
 
-import { resolveRoleFromServerContext } from "@/lib/access-server"
+import { AdminShell } from "@/components/admin-shell"
+import { requirePermissionForRoute } from "@/lib/route-guards"
 
 export const dynamic = "force-dynamic"
 
@@ -405,15 +404,11 @@ function filterButtonClass(active: boolean): string {
 export default async function AdminTodoPage(props: {
   searchParams?: SearchParamsInput | Promise<SearchParamsInput>
 }) {
-  const role = await resolveRoleFromServerContext()
-
-  if (!role) {
-    redirect("/login?next=/todo")
-  }
-
-  if (!hasPermission(role, "roadmap:read", "global")) {
-    redirect("/unauthorized?required=roadmap:read&scope=global")
-  }
+  const role = await requirePermissionForRoute({
+    nextPath: "/todo",
+    permission: "roadmap:read",
+    scope: "global",
+  })
 
   const content = await getTodoMarkdown()
   const sections = parseTodo(content)
@@ -434,26 +429,21 @@ export default async function AdminTodoPage(props: {
   }
 
   return (
-    <main className="mx-auto flex min-h-screen w-full max-w-6xl flex-col gap-8 px-6 py-12">
-      <header className="space-y-4">
-        <p className="text-sm uppercase tracking-[0.2em] text-neutral-500">Admin App</p>
-        <div className="flex flex-wrap items-end justify-between gap-4">
-          <div className="space-y-2">
-            <h1 className="text-4xl font-semibold tracking-tight">Roadmap and Progress</h1>
-            <p className="text-neutral-600">
-              Structured view from root `TODO.md` (single source of truth).
-            </p>
-          </div>
-
-          <Link
-            href="/"
-            className="inline-flex rounded-md border border-neutral-300 px-4 py-2 text-sm font-medium hover:bg-neutral-100"
-          >
-            Back to dashboard
-          </Link>
-        </div>
-      </header>
-
+    <AdminShell
+      role={role}
+      activePath="/todo"
+      badge="Admin App"
+      title="Roadmap and Progress"
+      description="Structured view from root TODO.md (single source of truth)."
+      actions={
+        <Link
+          href="/"
+          className="inline-flex rounded-md border border-neutral-300 px-4 py-2 text-sm font-medium hover:bg-neutral-100"
+        >
+          Back to dashboard
+        </Link>
+      }
+    >
       <section className="rounded-xl border border-neutral-200 bg-neutral-50 p-5">
         <div className="mb-4 flex items-center justify-between gap-4">
           <p className="text-sm font-medium text-neutral-600">Weighted completion</p>
@@ -607,6 +597,6 @@ export default async function AdminTodoPage(props: {
           {content}
         </pre>
       </details>
-    </main>
+    </AdminShell>
   )
 }

apps/admin/src/app/users/page.tsx

@@ -0,0 +1,34 @@
+import { AdminSectionPlaceholder } from "@/components/admin-section-placeholder"
+import { AdminShell } from "@/components/admin-shell"
+import { requirePermissionForRoute } from "@/lib/route-guards"
+
+export const dynamic = "force-dynamic"
+
+export default async function UsersManagementPage() {
+  const role = await requirePermissionForRoute({
+    nextPath: "/users",
+    permission: "users:read",
+    scope: "own",
+  })
+
+  return (
+    <AdminShell
+      role={role}
+      activePath="/users"
+      badge="Admin App"
+      title="Users"
+      description="Prepare user lifecycle and role management operations."
+    >
+      <AdminSectionPlaceholder
+        feature="Users Management"
+        summary="This route sets the guardrail and UX entrypoint for role assignment, status, and invitation flows."
+        requiredPermission="users:read (own)"
+        nextSteps={[
+          "Add user list, filter, and detail views.",
+          "Add role and permission editing actions with owner/support safety rules.",
+          "Add disable/ban and invite workflows.",
+        ]}
+      />
+    </AdminShell>
+  )
+}

apps/admin/src/components/admin-section-placeholder.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react"
+
+type AdminSectionPlaceholderProps = {
+  feature: string
+  summary: string
+  requiredPermission: string
+  nextSteps: string[]
+  children?: ReactNode
+}
+
+export function AdminSectionPlaceholder({
+  feature,
+  summary,
+  requiredPermission,
+  nextSteps,
+  children,
+}: AdminSectionPlaceholderProps) {
+  return (
+    <section className="space-y-5 rounded-xl border border-neutral-200 p-6">
+      <div className="space-y-2">
+        <h2 className="text-xl font-medium">{feature}</h2>
+        <p className="text-sm text-neutral-600">{summary}</p>
+        <p className="text-xs uppercase tracking-wide text-neutral-500">
+          Required permission: {requiredPermission}
+        </p>
+      </div>
+
+      {children}
+
+      <div className="rounded-lg border border-neutral-200 bg-neutral-50 p-4">
+        <p className="text-sm font-medium text-neutral-800">Planned next steps</p>
+        <ul className="mt-2 list-disc space-y-1 pl-5 text-sm text-neutral-600">
+          {nextSteps.map((step) => (
+            <li key={step}>{step}</li>
+          ))}
+        </ul>
+      </div>
+    </section>
+  )
+}

apps/admin/src/components/admin-shell.tsx

@@ -0,0 +1,117 @@
+import { hasPermission, type Permission, type PermissionScope, type Role } from "@cms/content/rbac"
+import Link from "next/link"
+import type { ReactNode } from "react"
+
+import { LogoutButton } from "@/app/logout-button"
+import { AdminLocaleSwitcher } from "@/components/admin-locale-switcher"
+
+type AdminShellProps = {
+  role: Role
+  activePath: string
+  badge: string
+  title: string
+  description: string
+  actions?: ReactNode
+  children: ReactNode
+}
+
+type NavItem = {
+  href: string
+  label: string
+  permission: Permission
+  scope: PermissionScope
+}
+
+const navItems: NavItem[] = [
+  { href: "/", label: "Dashboard", permission: "dashboard:read", scope: "global" },
+  { href: "/pages", label: "Pages", permission: "pages:read", scope: "team" },
+  { href: "/media", label: "Media", permission: "media:read", scope: "team" },
+  { href: "/users", label: "Users", permission: "users:read", scope: "own" },
+  { href: "/commissions", label: "Commissions", permission: "commissions:read", scope: "own" },
+  { href: "/settings", label: "Settings", permission: "users:manage_roles", scope: "global" },
+  { href: "/todo", label: "Roadmap", permission: "roadmap:read", scope: "global" },
+]
+
+function navItemClass(active: boolean): string {
+  if (active) {
+    return "bg-neutral-900 text-white border-neutral-900"
+  }
+
+  return "bg-white text-neutral-700 border-neutral-300 hover:bg-neutral-100"
+}
+
+function isActiveRoute(activePath: string, href: string): boolean {
+  if (href === "/") {
+    return activePath === "/"
+  }
+
+  return activePath === href || activePath.startsWith(`${href}/`)
+}
+
+export function AdminShell({
+  role,
+  activePath,
+  badge,
+  title,
+  description,
+  actions,
+  children,
+}: AdminShellProps) {
+  return (
+    <div className="mx-auto flex min-h-screen w-full max-w-7xl gap-8 px-6 py-10">
+      <aside className="sticky top-0 hidden h-fit w-64 shrink-0 space-y-4 lg:block">
+        <div className="rounded-xl border border-neutral-200 bg-white p-4">
+          <p className="text-xs font-semibold uppercase tracking-[0.2em] text-neutral-500">
+            CMS Admin
+          </p>
+          <p className="mt-2 text-sm text-neutral-600">Role: {role}</p>
+        </div>
+
+        <nav className="space-y-2">
+          {navItems
+            .filter((item) => hasPermission(role, item.permission, item.scope))
+            .map((item) => (
+              <Link
+                key={item.href}
+                href={item.href}
+                className={`block rounded-md border px-3 py-2 text-sm font-medium ${navItemClass(isActiveRoute(activePath, item.href))}`}
+              >
+                {item.label}
+              </Link>
+            ))}
+        </nav>
+      </aside>
+
+      <div className="min-w-0 flex-1 space-y-8">
+        <nav className="flex flex-wrap gap-2 lg:hidden">
+          {navItems
+            .filter((item) => hasPermission(role, item.permission, item.scope))
+            .map((item) => (
+              <Link
+                key={`mobile-${item.href}`}
+                href={item.href}
+                className={`rounded-md border px-3 py-2 text-sm font-medium ${navItemClass(isActiveRoute(activePath, item.href))}`}
+              >
+                {item.label}
+              </Link>
+            ))}
+        </nav>
+
+        <header className="space-y-3">
+          <div className="flex flex-wrap items-center justify-between gap-3">
+            <p className="text-sm uppercase tracking-[0.2em] text-neutral-500">{badge}</p>
+            <div className="flex items-center gap-2">
+              <AdminLocaleSwitcher />
+              <LogoutButton />
+            </div>
+          </div>
+          <h1 className="text-4xl font-semibold tracking-tight">{title}</h1>
+          <p className="text-neutral-600">{description}</p>
+          {actions ? <div className="flex flex-wrap items-center gap-3 pt-1">{actions}</div> : null}
+        </header>
+
+        {children}
+      </div>
+    </div>
+  )
+}

apps/admin/src/lib/access.test.ts

@@ -21,4 +21,23 @@ describe("admin route access rules", () => {
       scope: "global",
     })
   })
+
+  it("maps new admin IA routes to dedicated permissions", () => {
+    expect(getRequiredPermission("/pages")).toEqual({
+      permission: "pages:read",
+      scope: "team",
+    })
+    expect(getRequiredPermission("/media")).toEqual({
+      permission: "media:read",
+      scope: "team",
+    })
+    expect(getRequiredPermission("/users")).toEqual({
+      permission: "users:read",
+      scope: "own",
+    })
+    expect(getRequiredPermission("/commissions")).toEqual({
+      permission: "commissions:read",
+      scope: "own",
+    })
+  })
 })

apps/admin/src/lib/access.ts

@@ -43,6 +43,34 @@ const guardRules: GuardRule[] = [
       scope: "global",
     },
   },
+  {
+    route: /^\/pages(?:\/|$)/,
+    requirement: {
+      permission: "pages:read",
+      scope: "team",
+    },
+  },
+  {
+    route: /^\/media(?:\/|$)/,
+    requirement: {
+      permission: "media:read",
+      scope: "team",
+    },
+  },
+  {
+    route: /^\/users(?:\/|$)/,
+    requirement: {
+      permission: "users:read",
+      scope: "own",
+    },
+  },
+  {
+    route: /^\/commissions(?:\/|$)/,
+    requirement: {
+      permission: "commissions:read",
+      scope: "own",
+    },
+  },
   {
     route: /^\/settings(?:\/|$)/,
     requirement: {

apps/admin/src/lib/route-guards.ts

@@ -0,0 +1,30 @@
+import { hasPermission, type Permission, type PermissionScope, type Role } from "@cms/content/rbac"
+import { redirect } from "next/navigation"
+
+import { resolveRoleFromServerContext } from "@/lib/access-server"
+
+type RequirePermissionParams = {
+  nextPath: string
+  permission: Permission
+  scope: PermissionScope
+}
+
+export async function requireRoleForRoute(nextPath: string): Promise<Role> {
+  const role = await resolveRoleFromServerContext()
+
+  if (!role) {
+    redirect(`/login?next=${encodeURIComponent(nextPath)}`)
+  }
+
+  return role
+}
+
+export async function requirePermissionForRoute(params: RequirePermissionParams): Promise<Role> {
+  const role = await requireRoleForRoute(params.nextPath)
+
+  if (!hasPermission(role, params.permission, params.scope)) {
+    redirect(`/unauthorized?required=${params.permission}&scope=${params.scope}`)
+  }
+
+  return role
+}

docs/product-engineering/crud-baseline.md

@@ -7,6 +7,8 @@ MVP0 now includes a shared CRUD foundation package: `@cms/crud`.
 Current baseline:
 
 - Shared service factory: `createCrudService`
+- Repository contract: `list`, `findById`, `create`, `update`, `delete`
+- Service surface for list/detail/editor flows: `list`, `getById`, `create`, `update`, `delete`
 - Shared validation error type: `CrudValidationError`
 - Shared not-found error type: `CrudNotFoundError`
 - Shared mutation audit hook contract: `CrudAuditHook`
@@ -24,6 +26,11 @@ Current baseline:
 - `registerPostCrudAuditHook`
 
 Validation for create/update is enforced by `@cms/content` schemas.
+Contract tests validate:
+
+- repository list/detail behavior via CRUD service
+- validation and not-found errors
+- audit payload propagation (`actor`, `metadata`)
 
 The admin dashboard currently includes a temporary posts CRUD sandbox to validate this flow through a real app UI.
 

packages/crud/src/service.test.ts

@@ -63,6 +63,32 @@ function createMemoryRepository() {
 }
 
 describe("createCrudService", () => {
+  it("supports list and detail lookups through the repository contract", async () => {
+    const service = createCrudService({
+      resource: "fake-entity",
+      repository: createMemoryRepository(),
+      schemas: {
+        create: z.object({
+          title: z.string().min(3),
+        }),
+        update: z.object({
+          title: z.string().min(3).optional(),
+        }),
+      },
+    })
+
+    const createdA = await service.create({ title: "First" })
+    const createdB = await service.create({ title: "Second" })
+
+    expect(await service.getById(createdA.id)).toEqual(createdA)
+    expect(await service.getById("missing")).toBeNull()
+
+    const listed = await service.list()
+    expect(listed).toHaveLength(2)
+    expect(listed).toContainEqual(createdA)
+    expect(listed).toContainEqual(createdB)
+  })
+
   it("validates create and update payloads", async () => {
     const service = createCrudService({
       resource: "fake-entity",
@@ -106,8 +132,13 @@ describe("createCrudService", () => {
   })
 
   it("emits audit events for create, update and delete", async () => {
-    const events: Array<{ action: string; beforeTitle: string | null; afterTitle: string | null }> =
-      []
+    const events: Array<{
+      action: string
+      beforeTitle: string | null
+      afterTitle: string | null
+      actorRole: string | null
+      requestId: string | null
+    }> = []
     const service = createCrudService({
       resource: "fake-entity",
       repository: createMemoryRepository(),
@@ -125,6 +156,9 @@ describe("createCrudService", () => {
             action: event.action,
             beforeTitle: event.before?.title ?? null,
             afterTitle: event.after?.title ?? null,
+            actorRole: event.actor?.role ?? null,
+            requestId:
+              typeof event.metadata?.requestId === "string" ? event.metadata.requestId : null,
           })
         },
       ],
@@ -134,6 +168,9 @@ describe("createCrudService", () => {
       { title: "Created" },
       {
         actor: { id: "u-1", role: "owner" },
+        metadata: {
+          requestId: "req-1",
+        },
       },
     )
 
@@ -145,16 +182,22 @@ describe("createCrudService", () => {
         action: "create",
         beforeTitle: null,
         afterTitle: "Created",
+        actorRole: "owner",
+        requestId: "req-1",
       },
       {
         action: "update",
         beforeTitle: "Created",
         afterTitle: "Updated",
+        actorRole: null,
+        requestId: null,
       },
       {
         action: "delete",
         beforeTitle: "Updated",
         afterTitle: null,
+        actorRole: null,
+        requestId: null,
       },
     ])
   })