Add admin foundation + Users resource (Filament replacement, slice 1)

Plain App Router admin (aligned to habbo-next, no Refine):
- rank surfaced on the NextAuth session; staff guard isStaff() [pure,
  unit-tested] + requireStaff() reading min_staff_rank, gating /admin.
- /admin dashboard (counts), /admin/users (paginated + search),
  /admin/users/[id] detail.
- src/actions/admin-users.ts: staff-gated server actions wiring the user editor
  to the existing services — giveCurrency (RCON or DB fallback), setMotto/setRank
  (DB + RCON), alertUser, disconnectUser.

Verified: tsc exit 0, vitest 45/45, next build exit 0 (/admin routes).

src/actions/admin-users.ts

@@ -0,0 +1,56 @@
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { requireStaff } from "@/lib/admin/guard";
+import { prisma } from "@/lib/prisma";
+import { rcon } from "@/lib/services/rcon";
+import { type CurrencyName, sendCurrency } from "@/lib/services/send-currency";
+
+const CURRENCIES: ReadonlySet<string> = new Set(["credits", "duckets", "diamonds", "points"]);
+
+export async function giveCurrency(formData: FormData): Promise<void> {
+  await requireStaff();
+  const userId = Number(formData.get("userId"));
+  const type = String(formData.get("type"));
+  const amount = Number(formData.get("amount"));
+  if (userId > 0 && amount > 0 && CURRENCIES.has(type)) {
+    await sendCurrency({ rcon, db: prisma }, userId, type as CurrencyName, amount);
+  }
+  revalidatePath(`/admin/users/${userId}`);
+}
+
+export async function setMotto(formData: FormData): Promise<void> {
+  await requireStaff();
+  const userId = Number(formData.get("userId"));
+  const motto = String(formData.get("motto") ?? "").slice(0, 127);
+  if (userId > 0) {
+    await prisma.user.update({ where: { id: userId }, data: { motto } });
+    await rcon.setMotto(userId, motto);
+  }
+  revalidatePath(`/admin/users/${userId}`);
+}
+
+export async function setRank(formData: FormData): Promise<void> {
+  await requireStaff();
+  const userId = Number(formData.get("userId"));
+  const rank = Number(formData.get("rank"));
+  if (userId > 0 && rank > 0) {
+    await prisma.user.update({ where: { id: userId }, data: { rank } });
+    await rcon.setRank(userId, rank);
+  }
+  revalidatePath(`/admin/users/${userId}`);
+}
+
+export async function alertUser(formData: FormData): Promise<void> {
+  await requireStaff();
+  const userId = Number(formData.get("userId"));
+  const message = String(formData.get("message") ?? "").trim();
+  if (userId > 0 && message) await rcon.alertUser(userId, message);
+}
+
+export async function disconnectUser(formData: FormData): Promise<void> {
+  await requireStaff();
+  const userId = Number(formData.get("userId"));
+  const username = String(formData.get("username") ?? "");
+  if (userId > 0) await rcon.disconnectUser(userId, username);
+}

src/app/admin/layout.tsx

@@ -0,0 +1,24 @@
+import Link from "next/link";
+import type { ReactNode } from "react";
+import { requireStaff } from "@/lib/admin/guard";
+
+export const dynamic = "force-dynamic";
+
+export default async function AdminLayout({ children }: { children: ReactNode }) {
+  const staff = await requireStaff();
+
+  return (
+    <div style={{ display: "grid", gridTemplateColumns: "190px 1fr", gap: "1.5rem" }}>
+      <aside className="card" style={{ height: "fit-content" }}>
+        <p className="muted" style={{ marginTop: 0 }}>
+          Staff · {staff.username} (rank {staff.rank})
+        </p>
+        <nav style={{ display: "grid", gap: "0.45rem" }}>
+          <Link href="/admin">Dashboard</Link>
+          <Link href="/admin/users">Users</Link>
+        </nav>
+      </aside>
+      <section>{children}</section>
+    </div>
+  );
+}

src/app/admin/page.tsx

@@ -0,0 +1,33 @@
+import { prisma } from "@/lib/prisma";
+
+export const dynamic = "force-dynamic";
+
+export default async function AdminDashboard() {
+  const [users, online, articles] = await Promise.all([
+    prisma.user.count(),
+    prisma.user.count({ where: { online: "1" } }),
+    prisma.websiteArticles.count(),
+  ]);
+
+  const stats = [
+    { label: "Users", value: users },
+    { label: "Online now", value: online },
+    { label: "Articles", value: articles },
+  ];
+
+  return (
+    <main>
+      <h1>Dashboard</h1>
+      <div className="grid cols-2">
+        {stats.map((s) => (
+          <div key={s.label} className="card">
+            <h2 style={{ margin: 0 }}>{s.value}</h2>
+            <p className="muted" style={{ margin: 0 }}>
+              {s.label}
+            </p>
+          </div>
+        ))}
+      </div>
+    </main>
+  );
+}

src/app/admin/users/[id]/page.tsx

@@ -0,0 +1,82 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import {
+  alertUser,
+  disconnectUser,
+  giveCurrency,
+  setMotto,
+  setRank,
+} from "@/actions/admin-users";
+import { prisma } from "@/lib/prisma";
+
+export const dynamic = "force-dynamic";
+
+export default async function AdminUserDetail({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  const userId = Number(id);
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { id: true, username: true, motto: true, rank: true, credits: true, look: true, online: true },
+  });
+  if (!user) notFound();
+
+  return (
+    <main>
+      <p className="muted">
+        <Link href="/admin/users">← Users</Link>
+      </p>
+      <h1>{user.username}</h1>
+      <p className="muted">
+        ID {user.id} · rank {user.rank} · {user.credits} credits ·{" "}
+        {user.online === "1" ? "Online" : "Offline"}
+      </p>
+
+      <div className="grid cols-2">
+        <form action={giveCurrency} className="card">
+          <input type="hidden" name="userId" value={user.id} />
+          <h3 style={{ marginTop: 0 }}>Give currency</h3>
+          <select name="type">
+            <option value="credits">Credits</option>
+            <option value="duckets">Duckets</option>
+            <option value="diamonds">Diamonds</option>
+            <option value="points">Points</option>
+          </select>{" "}
+          <input name="amount" type="number" min={1} placeholder="Amount" />{" "}
+          <button type="submit">Give</button>
+        </form>
+
+        <form action={setMotto} className="card">
+          <input type="hidden" name="userId" value={user.id} />
+          <h3 style={{ marginTop: 0 }}>Set motto</h3>
+          <input name="motto" defaultValue={user.motto} maxLength={127} />{" "}
+          <button type="submit">Save</button>
+        </form>
+
+        <form action={setRank} className="card">
+          <input type="hidden" name="userId" value={user.id} />
+          <h3 style={{ marginTop: 0 }}>Set rank</h3>
+          <input name="rank" type="number" min={1} defaultValue={user.rank} />{" "}
+          <button type="submit">Set</button>
+        </form>
+
+        <form action={alertUser} className="card">
+          <input type="hidden" name="userId" value={user.id} />
+          <h3 style={{ marginTop: 0 }}>Alert</h3>
+          <input name="message" placeholder="Message" />{" "}
+          <button type="submit">Send</button>
+        </form>
+
+        <form action={disconnectUser} className="card">
+          <input type="hidden" name="userId" value={user.id} />
+          <input type="hidden" name="username" value={user.username} />
+          <h3 style={{ marginTop: 0 }}>Disconnect</h3>
+          <button type="submit">Disconnect from hotel</button>
+        </form>
+      </div>
+    </main>
+  );
+}

src/app/admin/users/page.tsx

@@ -0,0 +1,74 @@
+import Link from "next/link";
+import { prisma } from "@/lib/prisma";
+
+export const dynamic = "force-dynamic";
+
+const PER_PAGE = 25;
+
+export default async function AdminUsers({
+  searchParams,
+}: {
+  searchParams: Promise<{ q?: string; page?: string }>;
+}) {
+  const sp = await searchParams;
+  const q = (sp.q ?? "").trim();
+  const page = Math.max(1, Number(sp.page ?? "1") || 1);
+  const where = q ? { username: { contains: q } } : {};
+
+  const [users, total] = await Promise.all([
+    prisma.user.findMany({
+      where,
+      select: { id: true, username: true, rank: true, credits: true, online: true },
+      orderBy: { id: "desc" },
+      skip: (page - 1) * PER_PAGE,
+      take: PER_PAGE,
+    }),
+    prisma.user.count({ where }),
+  ]);
+  const pages = Math.max(1, Math.ceil(total / PER_PAGE));
+
+  return (
+    <main>
+      <h1>Users</h1>
+      <form style={{ display: "flex", gap: "0.5rem", marginBottom: "1rem" }}>
+        <input name="q" defaultValue={q} placeholder="Search username" />
+        <button type="submit">Search</button>
+      </form>
+
+      <table style={{ width: "100%", borderCollapse: "collapse" }}>
+        <thead>
+          <tr style={{ textAlign: "left", color: "var(--muted)" }}>
+            <th>ID</th>
+            <th>Username</th>
+            <th>Rank</th>
+            <th>Credits</th>
+            <th>Online</th>
+          </tr>
+        </thead>
+        <tbody>
+          {users.map((u) => (
+            <tr key={u.id} style={{ borderTop: "1px solid var(--border)" }}>
+              <td>{u.id}</td>
+              <td>
+                <Link href={`/admin/users/${u.id}`}>{u.username}</Link>
+              </td>
+              <td>{u.rank}</td>
+              <td>{u.credits}</td>
+              <td>{u.online === "1" ? "●" : "○"}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      <p className="muted">
+        Page {page} / {pages} · {total} users
+        {page < pages ? (
+          <>
+            {" · "}
+            <Link href={`/admin/users?q=${encodeURIComponent(q)}&page=${page + 1}`}>Next →</Link>
+          </>
+        ) : null}
+      </p>
+    </main>
+  );
+}

src/lib/admin/guard.ts

@@ -0,0 +1,33 @@
+import { redirect } from "next/navigation";
+import { isStaff } from "@/lib/admin/is-staff";
+import { auth } from "@/lib/auth";
+import { siteSettings } from "@/lib/services/site-settings";
+
+export { isStaff };
+
+export async function getMinStaffRank(): Promise<number> {
+  const n = Number(await siteSettings.get("min_staff_rank", "7"));
+  return Number.isFinite(n) ? n : 7;
+}
+
+export interface StaffUser {
+  id: number;
+  rank: number;
+  username: string;
+}
+
+/**
+ * Gate for admin pages and actions: redirects to /login when unauthenticated
+ * and to / when authenticated but not staff. Returns the staff user otherwise.
+ */
+export async function requireStaff(): Promise<StaffUser> {
+  const session = await auth();
+  if (!session?.user?.id) redirect("/login");
+  const minRank = await getMinStaffRank();
+  if (!isStaff(session.user.rank, minRank)) redirect("/");
+  return {
+    id: Number(session.user.id),
+    rank: session.user.rank,
+    username: session.user.name ?? "",
+  };
+}

src/lib/admin/is-staff.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { isStaff } from "./is-staff";
+
+describe("isStaff", () => {
+  it("is true at or above the min staff rank", () => {
+    expect(isStaff(7, 7)).toBe(true);
+    expect(isStaff(10, 7)).toBe(true);
+  });
+
+  it("is false below the min staff rank", () => {
+    expect(isStaff(6, 7)).toBe(false);
+    expect(isStaff(1, 7)).toBe(false);
+  });
+});

src/lib/admin/is-staff.ts

@@ -0,0 +1,4 @@
+/** AtomCMS housekeeping gate: staff are users with rank >= min_staff_rank. */
+export function isStaff(rank: number, minStaffRank: number): boolean {
+  return rank >= minStaffRank;
+}

src/lib/auth.ts

@@ -35,14 +35,19 @@ export const { handlers, signIn, signOut, auth } = NextAuth({
           });
         }
 
-        return { id: String(user.id), name: user.username };
+        return { id: String(user.id), name: user.username, rank: user.rank };
       },
     }),
   ],
   callbacks: {
-    // NextAuth stores the user id in token.sub automatically; surface it on the session.
+    jwt({ token, user }) {
+      if (user) token.rank = (user as { rank?: number }).rank;
+      return token;
+    },
+    // NextAuth stores the user id in token.sub automatically; surface id + rank.
     session({ session, token }) {
       if (token.sub && session.user) session.user.id = token.sub;
+      if (typeof token.rank === "number" && session.user) session.user.rank = token.rank;
       return session;
     },
   },

src/types/next-auth.d.ts

@@ -2,6 +2,12 @@ import type { DefaultSession } from "next-auth";
 
 declare module "next-auth" {
   interface Session {
-    user: { id: string } & DefaultSession["user"];
+    user: { id: string; rank: number } & DefaultSession["user"];
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    rank?: number;
   }
 }