@podosoft/podokit 0.3.0 → 0.5.0

package/dist/templates/modules/admin-dashboard/files/tests/helpers/hydration.ts

@@ -0,0 +1,9 @@
+import type { Page } from "@playwright/test";
+
+// SvelteKit dev hydration can attach event handlers slightly after load;
+// wait for the page to settle before driving client-only interactions.
+export async function ready(page: Page, path: string): Promise<void> {
+  await page.goto(path);
+  await page.waitForLoadState("load");
+  await page.waitForTimeout(400);
+}

package/dist/templates/modules/admin-dashboard/files/tests/helpers/mailpit.ts

@@ -0,0 +1,49 @@
+// Helpers for the local Mailpit catcher (docker-compose / CI service). Tests that
+// exercise email flows skip when it isn't reachable (see MAILPIT_URL).
+const MAILPIT = process.env.MAILPIT_URL ?? "http://localhost:8025";
+
+export async function mailpitReachable(): Promise<boolean> {
+  try {
+    return (await fetch(`${MAILPIT}/readyz`)).ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function clearMailpit(): Promise<void> {
+  try {
+    await fetch(`${MAILPIT}/api/v1/messages`, { method: "DELETE" });
+  } catch {
+    /* ignore */
+  }
+}
+
+type MailpitList = { messages: Array<{ ID: string; To: Array<{ Address: string }> }> };
+type MailpitMessage = { Text?: string; HTML?: string };
+
+// Poll for the newest message addressed to `to` and return the first match of
+// `pattern` in its text/HTML body.
+async function waitForMatch(to: string, pattern: RegExp, label: string, timeoutMs: number): Promise<string> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const list = (await (await fetch(`${MAILPIT}/api/v1/messages`)).json()) as MailpitList;
+    const msg = list.messages?.find((m) => m.To?.some((t) => t.Address === to));
+    if (msg) {
+      const full = (await (await fetch(`${MAILPIT}/api/v1/message/${msg.ID}`)).json()) as MailpitMessage;
+      const match = `${full.Text ?? ""} ${full.HTML ?? ""}`.match(pattern);
+      if (match) return match[0];
+    }
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  throw new Error(`no email with ${label} to ${to} within ${timeoutMs}ms`);
+}
+
+/** The first link in the newest email addressed to `to`. */
+export function waitForLink(to: string, timeoutMs = 10000): Promise<string> {
+  return waitForMatch(to, /https?:\/\/[^\s"<>]+/, "a link", timeoutMs);
+}
+
+/** The one-time numeric code in the newest email addressed to `to`. */
+export function waitForOtp(to: string, timeoutMs = 10000): Promise<string> {
+  return waitForMatch(to, /\b\d{4,8}\b/, "a one-time code", timeoutMs);
+}

package/dist/templates/modules/admin-dashboard/files/tests/helpers/sms.ts

@@ -0,0 +1,35 @@
+// Read-back helper for the dev SMS sink (the "Mailpit for SMS"). The app posts
+// outgoing SMS to the sink via SMS_WEBHOOK_URL; tests poll it here to obtain the
+// delivered code, so the phone-number flow is verified for real (not just "sent").
+const SINK = process.env.SMS_SINK_URL ?? "http://localhost:8095";
+
+type SinkMessage = { to: string; body: string; receivedAt: string };
+
+export async function smsSinkReachable(): Promise<boolean> {
+  try {
+    const res = await fetch(`${SINK}/readyz`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function clearSms(): Promise<void> {
+  await fetch(`${SINK}/messages`, { method: "DELETE" }).catch(() => undefined);
+}
+
+/** Poll the sink until an SMS to `to` arrives, then return the first 4–8 digit code. */
+export async function waitForSmsOtp(to: string, timeoutMs = 10_000): Promise<string> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await fetch(`${SINK}/messages`).catch(() => null);
+    if (res?.ok) {
+      const messages = (await res.json()) as SinkMessage[];
+      const match = messages.find((m) => m.to === to);
+      const code = match?.body.match(/\b\d{4,8}\b/)?.[0];
+      if (code) return code;
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  throw new Error(`No SMS OTP for ${to} within ${timeoutMs}ms`);
+}

package/dist/templates/modules/admin-dashboard/files/tests/helpers/totp.ts

@@ -0,0 +1,9 @@
+import { URI, type TOTP } from "otpauth";
+
+/** Compute the current 6-digit code from an otpauth:// URI (the `totpURI` that
+ *  two-factor/enable returns), the same way an authenticator app would. Lets
+ *  tests complete the real 2FA verification flow. */
+export function totpCode(otpauthUri: string): string {
+  const totp = URI.parse(otpauthUri) as TOTP;
+  return totp.generate();
+}

package/dist/templates/modules/admin-dashboard/files/tests/playwright.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig, devices } from "@playwright/test";
+
+// admin-dashboard overlay: adds a `setup` project that seeds admin/user sessions
+// (storageState) which the `ui` project reuses. Serial + single worker because
+// tests share one backend/DB. Runs against a live stack on E2E_BASE_URL.
+const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+
+export default defineConfig({
+  testDir: ".",
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: [["list"], ["html", { open: "never" }]],
+  use: { baseURL, trace: "on-first-retry", screenshot: "only-on-failure" },
+  projects: [
+    { name: "api", testMatch: /.*\.api\.spec\.ts/, dependencies: ["setup"] },
+    { name: "setup", testMatch: /.*\.setup\.ts/ },
+    {
+      name: "ui",
+      testMatch: /.*\.ui\.spec\.ts/,
+      dependencies: ["setup"],
+      use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/admin.json" },
+    },
+  ],
+});

package/dist/templates/modules/admin-dashboard/files/tests/seed.setup.ts

@@ -0,0 +1,40 @@
+import { test as setup, expect } from "@playwright/test";
+import { ADMIN, USER, adminState, userState, type Account } from "./helpers/accounts";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+
+// Seed a session via the API (reliable, no UI hydration races) and save its
+// cookies as storageState for the browser `ui` project to reuse.
+async function seedSession(
+  playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
+  account: Account,
+  path: string,
+): Promise<void> {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: { origin: base } });
+  await ctx.post("/api/auth/sign-up/email", { data: account }).catch(() => undefined); // idempotent
+  const res = await ctx.post("/api/auth/sign-in/email", {
+    data: { email: account.email, password: account.password },
+  });
+  expect(res.ok(), `sign-in ${account.email}`).toBeTruthy();
+  await ctx.storageState({ path });
+  await ctx.dispose();
+}
+
+setup("seed admin session", async ({ playwright }) => {
+  await seedSession(playwright, ADMIN, adminState);
+});
+
+// Feature flags are DB-backed (seeded by the app_setting migration). phoneNumber
+// ships off (needs an SMS provider); turn it on here so its specs run — this also
+// exercises the admin settings API on every suite run.
+setup("enable optional features", async ({ playwright }) => {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: { origin: base } });
+  await ctx.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
+  const res = await ctx.put("/api/account/settings", { data: { phoneNumber: true } });
+  expect(res.ok(), "enable optional features via settings").toBeTruthy();
+  await ctx.dispose();
+});
+
+setup("seed user session", async ({ playwright }) => {
+  await seedSession(playwright, USER, userState);
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/account.ui.spec.ts

@@ -0,0 +1,126 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// admin storageState (project default)
+test("account opens on the profile section @smoke", async ({ page }) => {
+  await ready(page, "/admin/account");
+  await expect(page.getByRole("heading", { name: "Account" })).toBeVisible();
+  await expect(page.getByLabel("Name", { exact: true })).toBeVisible();
+  await expect(page.getByLabel("Email")).toHaveValue("admin@example.com");
+  // save is enabled only once the name changes
+  await expect(page.getByRole("button", { name: "Save changes" })).toBeDisabled();
+  await page.getByLabel("Name", { exact: true }).fill("Admin Renamed");
+  await expect(page.getByRole("button", { name: "Save changes" })).toBeEnabled();
+});
+
+test("account exposes a change-email action when the address is edited @smoke", async ({ page }) => {
+  await ready(page, "/admin/account");
+  const email = page.getByLabel("Email");
+  await expect(email).toHaveValue("admin@example.com");
+  // no action until the address actually changes
+  await expect(page.getByRole("button", { name: "Change email" })).toHaveCount(0);
+  await email.fill("admin+changed@example.com");
+  await expect(page.getByRole("button", { name: "Change email" })).toBeVisible();
+  // revert without submitting — don't mutate the shared admin session
+  await email.fill("admin@example.com");
+  await expect(page.getByRole("button", { name: "Change email" })).toHaveCount(0);
+});
+
+test("account shows a username field when enabled @smoke", async ({ page }) => {
+  await ready(page, "/admin/account");
+  const username = page.getByLabel("Username", { exact: true });
+  test.skip((await username.count()) === 0, "username not enabled");
+  await expect(username).toBeVisible();
+});
+
+test("account can create and revoke an API key when enabled @smoke", async ({ page }) => {
+  await ready(page, "/admin/account");
+  const nav = page.getByRole("button", { name: "API keys" });
+  test.skip((await nav.count()) === 0, "api keys not enabled");
+  await nav.click();
+  const name = `ui-${Date.now()}`;
+  await page.getByLabel("Name", { exact: true }).fill(name);
+  await page.getByRole("button", { name: "Create key" }).click();
+  // the full key is shown once in a dialog
+  await expect(page.getByText("API key created")).toBeVisible();
+  await page.getByRole("button", { name: "Done" }).click();
+  // it now appears in the list; revoke it to clean up
+  const row = page.getByRole("row", { name: new RegExp(name) });
+  await expect(row).toBeVisible();
+  await row.getByRole("button", { name: "Revoke" }).click();
+  await expect(page.getByText("Key revoked")).toBeVisible();
+});
+
+test("account can register and remove a passkey when enabled @smoke", async ({ page }) => {
+  await ready(page, "/admin/account");
+  await page.getByRole("button", { name: "Security" }).click();
+  const addBtn = page.getByRole("button", { name: "Add passkey" });
+  test.skip((await addBtn.count()) === 0, "passkeys not enabled");
+  // A virtual authenticator lets the WebAuthn ceremony resolve without hardware.
+  const client = await page.context().newCDPSession(page);
+  await client.send("WebAuthn.enable");
+  await client.send("WebAuthn.addVirtualAuthenticator", {
+    options: { protocol: "ctap2", transport: "internal", hasResidentKey: true, hasUserVerification: true, isUserVerified: true, automaticPresenceSimulation: true },
+  });
+  const pkName = `pk-${Date.now()}`;
+  await page.getByLabel("Name", { exact: true }).fill(pkName);
+  await addBtn.click();
+  await expect(page.getByText("Passkey added")).toBeVisible();
+  const row = page.getByRole("row", { name: new RegExp(pkName) });
+  await expect(row).toBeVisible();
+  // remove it so the shared admin account keeps no leftover credential
+  await row.getByRole("button", { name: "Remove" }).click();
+  await expect(page.getByText("Passkey removed")).toBeVisible();
+});
+
+test("account shows a phone field when enabled @smoke", async ({ page }) => {
+  await ready(page, "/admin/account");
+  const phone = page.getByLabel("Phone number", { exact: true });
+  test.skip((await phone.count()) === 0, "phone number not enabled");
+  await expect(phone).toBeVisible();
+});
+
+test("admin can update their profile name", async ({ page }) => {
+  await ready(page, "/admin/account");
+  await page.getByLabel("Name", { exact: true }).fill("Admin Renamed");
+  await page.getByRole("button", { name: "Save changes" }).click();
+  await expect(page.getByText("Profile updated")).toBeVisible();
+});
+
+test("account security and sessions sub-navigation", async ({ page }) => {
+  await ready(page, "/admin/account");
+  await page.getByRole("button", { name: "Security" }).click();
+  await expect(page.getByLabel("Current password")).toBeVisible();
+  await page.getByRole("button", { name: "Sessions" }).click();
+  await expect(page.getByText("Active sessions")).toBeVisible();
+  await expect(page.getByText("Current", { exact: true })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Sign out other sessions" })).toBeVisible();
+});
+
+test("account nav shows the core sections", async ({ page }) => {
+  await ready(page, "/admin/account");
+  await expect(page.getByRole("button", { name: "Profile" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Security" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Sessions" })).toBeVisible();
+});
+
+test("two-factor setup shows a scannable QR code when enabled @smoke", async ({ page }) => {
+  await ready(page, "/admin/account");
+  await page.getByRole("button", { name: "Security" }).click();
+  const heading = page.getByText("Two-factor authentication");
+  test.skip((await heading.count()) === 0, "two-factor not enabled");
+  await expect(page.getByRole("button", { name: "Enable", exact: true })).toBeVisible();
+  // Start setup (password + Enable) and confirm the QR renders. Stop before
+  // verifying so 2FA stays inactive and the shared admin session keeps working.
+  await page.locator("#tf-on-pw").fill("Podokit3e-Str0ng!pw");
+  await page.getByRole("button", { name: "Enable", exact: true }).click();
+  await expect(page.getByRole("img", { name: "TOTP QR code" })).toBeVisible();
+});
+
+test("danger zone offers account deletion when enabled", async ({ page }) => {
+  await ready(page, "/admin/account");
+  const danger = page.getByRole("button", { name: "Danger zone" });
+  test.skip((await danger.count()) === 0, "account deletion not enabled");
+  await danger.click();
+  await expect(page.getByRole("button", { name: "Delete account" })).toBeVisible();
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/audit.ui.spec.ts

@@ -0,0 +1,16 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// admin storageState (project default). The Audit log page is gated by the
+// audit-log module; skip when it isn't installed in the generated app.
+test("admin can view audit entries when the module is installed", async ({ page }) => {
+  await ready(page, "/admin");
+  const auditNav = page.getByRole("link", { name: "Audit log" });
+  test.skip((await auditNav.count()) === 0, "audit-log module not installed");
+
+  await auditNav.click();
+  await expect(page).toHaveURL(/\/admin\/audit/);
+  await expect(page.getByRole("heading", { name: "Audit log" })).toBeVisible();
+  // seed sign-ins are audited via the better-auth hook, so an action row is present
+  await expect(page.getByText("auth.login").first()).toBeVisible();
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/auth.ui.spec.ts

@@ -0,0 +1,45 @@
+import { expect, test } from "@playwright/test";
+import { anonState, ADMIN } from "../helpers/accounts";
+import { ready } from "../helpers/hydration";
+
+test.use({ storageState: anonState });
+
+test("login page renders @smoke", async ({ page }) => {
+  await page.goto("/login");
+  await expect(page.getByLabel("Email")).toBeVisible();
+  await expect(page.getByLabel("Password")).toBeVisible();
+  await expect(page.getByRole("button", { name: "Sign in", exact: true })).toBeVisible();
+  await expect(page.getByRole("link", { name: "Sign up" })).toBeVisible();
+  await expect(page.getByRole("link", { name: "Forgot?" })).toBeVisible();
+});
+
+test("invalid credentials show an error", async ({ page }) => {
+  await ready(page, "/login");
+  await page.getByLabel("Email").fill("nobody@example.com");
+  await page.getByLabel("Password").fill("wrong-password");
+  await page.getByRole("button", { name: "Sign in", exact: true }).click();
+  await expect(page.getByRole("alert")).toBeVisible();
+  await expect(page).toHaveURL(/\/login/);
+});
+
+test("signup page renders", async ({ page }) => {
+  await page.goto("/signup");
+  await expect(page.getByLabel("Name")).toBeVisible();
+  await expect(page.getByRole("button", { name: "Create account" })).toBeVisible();
+});
+
+test("forgot-password shows a sent confirmation", async ({ page }) => {
+  await ready(page, "/forgot-password");
+  // Retry the submit to absorb any first-load hydration timing.
+  await expect(async () => {
+    await page.getByLabel("Email").fill(ADMIN.email);
+    await page.getByRole("button", { name: "Send reset link" }).click();
+    await expect(page.getByRole("alert")).toBeVisible({ timeout: 2000 });
+  }).toPass({ timeout: 15000 });
+});
+
+test("reset-password without a token is disabled", async ({ page }) => {
+  await page.goto("/reset-password");
+  await expect(page.getByRole("alert")).toBeVisible();
+  await expect(page.getByRole("button", { name: "Update password" })).toBeDisabled();
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/dashboard.ui.spec.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "@playwright/test";
+import { ADMIN } from "../helpers/accounts";
+import { ready } from "../helpers/hydration";
+
+// admin storageState (project default)
+test("overview shows the signed-in admin @smoke", async ({ page }) => {
+  await page.goto("/admin");
+  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+  // email appears in the sidebar user menu too — scope to the main content.
+  await expect(page.getByRole("main").getByText(ADMIN.email)).toBeVisible();
+});
+
+test("sidebar navigates to sessions and account", async ({ page }) => {
+  await ready(page, "/admin");
+  await page.getByRole("link", { name: "Sessions" }).click();
+  await expect(page).toHaveURL(/\/admin\/sessions/);
+  await expect(page.getByRole("heading", { name: "User sessions" })).toBeVisible();
+  // Account is reached from the user menu at the bottom of the sidebar, not the nav
+  await expect(page.getByRole("link", { name: "Account" })).toHaveCount(0);
+  await page.getByRole("button", { name: /admin@example.com/ }).click();
+  await page.getByRole("menuitem", { name: "Account" }).click();
+  await expect(page).toHaveURL(/\/admin\/account/);
+  await expect(page.getByRole("heading", { name: "Account" })).toBeVisible();
+  await expect(page.getByLabel("Name", { exact: true })).toBeVisible(); // profile section (exact: "Username" also contains "Name")
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/data-table.ui.spec.ts

@@ -0,0 +1,32 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+
+// Sorting via the shared DataTable. Users is server-sorted (manual), audit is
+// client-sorted — both drive the same clickable headers + aria-sort.
+test("users table sorts by a column header (server) @smoke", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const header = page.getByRole("columnheader", { name: /Name/ });
+  // Click the sort button *inside* the header — a bare name match collides with
+  // the sidebar user button (a "Renamed" account contains "name").
+  const sortByName = header.getByRole("button");
+  const firstName = () => page.getByRole("row").nth(1).getByRole("cell").first().innerText();
+
+  await sortByName.click();
+  await expect(header).toHaveAttribute("aria-sort", "ascending");
+  await page.waitForTimeout(400); // server refetch
+  const asc = await firstName();
+
+  await sortByName.click();
+  await expect(header).toHaveAttribute("aria-sort", "descending");
+  await page.waitForTimeout(400);
+  const desc = await firstName();
+
+  expect(asc).not.toBe(desc); // order flipped
+});
+
+test("audit table sorts client-side", async ({ page }) => {
+  await ready(page, "/admin/audit");
+  test.skip((await page.getByRole("row").count()) < 3, "not enough audit entries");
+  await page.getByRole("button", { name: "When" }).click(); // default desc -> asc
+  await expect(page.getByRole("columnheader", { name: /When/ })).toHaveAttribute("aria-sort", "ascending");
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/email-admin.ui.spec.ts

@@ -0,0 +1,60 @@
+import { expect, test } from "@playwright/test";
+import { ready } from "../helpers/hydration";
+import { clearMailpit, mailpitReachable, waitForLink } from "../helpers/mailpit";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+// Verification badges/actions are gated by the emailVerification capability. The
+// seeded suite runs with verification off, so assert the gating here (nothing
+// leaks in); the enabled state is covered manually / under a verification run.
+test("verification badges stay hidden when the feature is off", async ({ page }) => {
+  await ready(page, "/admin/users");
+  const caps = await (await page.request.get("/api/account/capabilities")).json();
+  test.skip(caps.emailVerification === true, "email verification enabled");
+  await expect(page.getByText("Verified", { exact: true })).toHaveCount(0);
+  await expect(page.getByText("Unverified", { exact: true })).toHaveCount(0);
+});
+
+// Admin can trigger a password-reset email for a user (not verification-gated).
+test("admin sends a password reset email to a user", async ({ page }) => {
+  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  await ready(page, "/admin/users");
+  const email = `admin-reset-${Date.now()}@example.com`;
+  await page.request.post("/api/auth/admin/create-user", {
+    headers: { origin: base },
+    data: { email, password: "Podokit3e-Str0ng!pw", name: "AR", role: "user" },
+  });
+  await clearMailpit();
+  await page.locator("#toolbar-search").fill(email);
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  await page.getByRole("row", { name: new RegExp(email) }).getByRole("button").click();
+  await page.getByRole("menuitem", { name: "Manage" }).click();
+  const dialog = page.getByRole("dialog");
+  await dialog.getByRole("button", { name: "Security" }).click();
+  await dialog.getByRole("button", { name: "Send password reset email" }).click();
+  await expect(page.getByText("Password reset email sent")).toBeVisible();
+  await waitForLink(email); // a reset email actually arrived for this user
+});
+
+test("login shows a verification hint for unverified users", async ({ page, browser }) => {
+  const caps = await (await page.request.get("/api/account/capabilities")).json();
+  test.skip(caps.emailVerification !== true, "email verification disabled");
+  const email = `login-unv-${Date.now()}@example.com`;
+  await page.request.post("/api/auth/sign-up/email", { headers: { origin: base }, data: { email, password: "Podokit3e-Str0ng!pw", name: "LU" } });
+  const anon = await browser.newContext();
+  const p2 = await anon.newPage();
+  await p2.goto(`${base}/login`);
+  await p2.getByLabel("Email").fill(email);
+  await p2.getByLabel("Password").fill("Podokit3e-Str0ng!pw");
+  await p2.getByRole("button", { name: "Sign in" }).click();
+  await expect(p2.getByRole("link", { name: /resend verification/i })).toBeVisible();
+  await anon.close();
+});
+
+test("overview omits the unverified-users card when the feature is off", async ({ page }) => {
+  await ready(page, "/admin");
+  const caps = await (await page.request.get("/api/account/capabilities")).json();
+  test.skip(caps.emailVerification === true, "email verification enabled");
+  await expect(page.getByText("Unverified users")).toHaveCount(0);
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/email.ui.spec.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "@playwright/test";
+import { anonState } from "../helpers/accounts";
+import { ready } from "../helpers/hydration";
+import { clearMailpit, mailpitReachable, waitForLink } from "../helpers/mailpit";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+// The reset flow is for signed-out users — run without the seeded session.
+test.use({ storageState: anonState });
+
+test("forgot password: request, open the emailed link, set a new password, sign in @smoke", async ({ page, playwright }) => {
+  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  const email = `ui-reset-${Date.now()}@example.com`;
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const signup = await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "UIReset" } });
+  expect(signup.ok()).toBeTruthy();
+  const verificationOn = !(await signup.json())?.token;
+  await ctx.dispose();
+  // The happy path ends by signing in; when verification is required that would be
+  // blocked, so this UI walkthrough only applies with verification off.
+  test.skip(verificationOn, "email verification enabled");
+  await clearMailpit();
+
+  await ready(page, "/forgot-password");
+  await page.getByLabel("Email").fill(email);
+  await page.getByRole("button", { name: "Send reset link" }).click();
+  await expect(page.getByText(/reset link is on its way/i)).toBeVisible();
+
+  // Open the emailed link: the API validates it and redirects to the reset page.
+  await page.goto(await waitForLink(email));
+  await page.waitForLoadState("load");
+  await page.waitForTimeout(400);
+  await page.getByLabel("New password").fill("Podokit3e-N3wStr0ng!pw");
+  await page.getByRole("button", { name: "Update password" }).click();
+  await expect(page).toHaveURL(/\/login/);
+
+  await page.getByLabel("Email").fill(email);
+  await page.getByLabel("Password").fill("Podokit3e-N3wStr0ng!pw");
+  await page.getByRole("button", { name: "Sign in" }).click();
+  await expect(page).toHaveURL(/\/admin/);
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/guards.ui.spec.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "@playwright/test";
+import { anonState, userState } from "../helpers/accounts";
+
+test.describe("unauthenticated", () => {
+  test.use({ storageState: anonState });
+  test("protected route redirects to login @smoke", async ({ page }) => {
+    await page.goto("/admin");
+    await expect(page).toHaveURL(/\/login\?redirect=/);
+  });
+});
+
+test.describe("normal user (non-admin)", () => {
+  test.use({ storageState: userState });
+  test("admin-only nav is hidden and admin routes are forbidden", async ({ page }) => {
+    await page.goto("/admin");
+    await expect(page.getByRole("link", { name: "Users" })).toHaveCount(0);
+    await expect(page.getByRole("link", { name: "Sessions" })).toHaveCount(0);
+    expect((await page.goto("/admin/users"))?.status()).toBe(403);
+    expect((await page.goto("/admin/sessions"))?.status()).toBe(403);
+    expect((await page.goto("/admin/settings"))?.status()).toBe(403);
+  });
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/i18n.ui.spec.ts

@@ -0,0 +1,13 @@
+import { expect, test } from "@playwright/test";
+import { anonState } from "../helpers/accounts";
+import { ready } from "../helpers/hydration";
+
+test.use({ storageState: anonState });
+
+test("language switch toggles Korean and sets <html lang>", async ({ page }) => {
+  await ready(page, "/login");
+  await page.getByRole("button", { name: "Language" }).click();
+  await page.getByRole("menuitem", { name: /한국어/ }).click();
+  await expect(page.locator("html")).toHaveAttribute("lang", "ko");
+  await expect(page.getByRole("button", { name: "로그인", exact: true })).toBeVisible();
+});

package/dist/templates/modules/admin-dashboard/files/tests/ui/oidc.ui.spec.ts

@@ -0,0 +1,57 @@
+import { expect, test } from "@playwright/test";
+import { createHash, randomBytes } from "node:crypto";
+
+// admin storageState (project default) — the admin is the resource owner.
+const b64url = (b: Buffer): string => b.toString("base64url");
+const REDIRECT = "http://localhost:9999/callback";
+
+// Verifies the provider is correctly configured end to end on the front channel:
+// signed discovery + JWKS, dynamic client registration, and an authorize request
+// (with PKCE) that validates the client and hands off to the consent page. The
+// back-channel token exchange is driven by an OIDC client SDK / real RP — see
+// docs/modules.md for the manual round-trip checklist.
+test("OIDC provider: discovery, JWKS, client registration, authorize handoff @smoke", async ({ page, baseURL }) => {
+  const headers = { origin: baseURL ?? "" };
+  await page.request.put("/api/account/settings", { data: { oidcProvider: true }, headers });
+  await expect
+    .poll(async () => (await page.request.get("/api/auth/.well-known/openid-configuration")).status(), { timeout: 8000 })
+    .toBe(200);
+
+  try {
+    const disc = await (await page.request.get("/api/auth/.well-known/openid-configuration")).json();
+    for (const field of ["issuer", "authorization_endpoint", "token_endpoint", "userinfo_endpoint", "jwks_uri"]) {
+      expect(typeof disc[field]).toBe("string");
+    }
+    // JWKS exposes at least one signing key (the OAuth provider needs it for id_tokens).
+    const jwks = await (await page.request.get(disc.jwks_uri)).json();
+    expect(Array.isArray(jwks.keys) && jwks.keys.length).toBeTruthy();
+
+    // Dynamic client registration returns usable credentials.
+    const reg = await (
+      await page.request.post("/api/auth/oauth2/create-client", {
+        data: { client_name: "E2E RP", redirect_uris: [REDIRECT] },
+        headers,
+      })
+    ).json();
+    expect(reg.client_id).toBeTruthy();
+    expect(reg.client_secret).toBeTruthy();
+
+    // Authorize validates the client + PKCE and hands off to the consent page with
+    // the signed authorization request.
+    const verifier = b64url(randomBytes(40));
+    const challenge = b64url(createHash("sha256").update(verifier).digest());
+    const authorizeUrl =
+      `/api/auth/oauth2/authorize?client_id=${reg.client_id}&redirect_uri=${encodeURIComponent(REDIRECT)}` +
+      `&response_type=code&scope=${encodeURIComponent("openid profile email")}&state=st` +
+      `&code_challenge=${challenge}&code_challenge_method=S256`;
+    const authz = await (await page.request.get(authorizeUrl, { headers })).json();
+    expect(String(authz.url)).toContain("/oauth2/consent");
+    expect(String(authz.url)).toContain("client_id=");
+
+    // The consent page renders (reached in a real browser navigation).
+    await page.goto(authz.url);
+    await expect(page.getByRole("button", { name: "Allow" })).toBeVisible();
+  } finally {
+    await page.request.put("/api/account/settings", { data: { oidcProvider: false }, headers });
+  }
+});