@podosoft/podokit 0.13.0 → 0.15.0

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

@@ -30,3 +30,16 @@ test("audit table sorts client-side", async ({ page }) => {
   await page.getByRole("button", { name: "When" }).click(); // default desc -> asc
   await expect(page.getByRole("columnheader", { name: /When/ })).toHaveAttribute("aria-sort", "ascending");
 });
+
+test("users table keeps responsive headers and cells aligned", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await ready(page, "/admin/users");
+  const table = page.getByRole("table", { name: "Users" });
+  const visibleHeaders = table.locator("thead th:visible");
+  const visibleCells = table.locator("tbody tr").first().locator("td:visible");
+
+  await expect(table.getByRole("columnheader", { name: "Role" })).toBeHidden();
+  await expect(table.getByRole("columnheader", { name: "Status" })).toBeHidden();
+  await expect(table.getByRole("columnheader", { name: "Joined" })).toBeHidden();
+  expect(await visibleHeaders.count()).toBe(await visibleCells.count());
+});

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

@@ -1,4 +1,4 @@
-import { expect, test } from "@playwright/test";
+import { expect, test } from "../helpers/disposable-users";
 import { ready } from "../helpers/hydration";
 import { clearMailpit, mailpitReachable, waitForLink } from "../helpers/mailpit";
 
@@ -17,14 +17,11 @@ test("verification badges stay hidden when the feature is off", async ({ page })
 });
 
 // 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("admin sends a password reset email to a user", async ({ page, disposableUsers }) => {
   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 disposableUsers.create({ email, name: "AR" });
   await clearMailpit();
   await page.locator("#toolbar-search").fill(email);
   await page.getByRole("button", { name: "Search", exact: true }).click();

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

@@ -23,13 +23,10 @@ test.describe("unauthenticated", () => {
 
 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);
+  test("admin route group is forbidden to non-admin users @smoke", async ({ page }) => {
+    for (const route of ["/admin", "/admin/users", "/admin/sessions", "/admin/settings"]) {
+      expect((await page.goto(route))?.status()).toBe(403);
+    }
   });
 
   test("account is available without the admin shell", async ({ page }) => {

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

@@ -9,7 +9,10 @@ test("settings: add and remove a social login provider", async ({ page }) => {
   const openConfigure = async (): Promise<void> => {
     await page.waitForLoadState("networkidle");
     await page.getByRole("tab", { name: "Authentication" }).click();
-    await page.getByRole("button", { name: "Configure" }).click();
+    const socialCard = page
+      .getByText("Social login", { exact: true })
+      .locator('xpath=ancestor::div[@data-slot="card"]');
+    await socialCard.getByRole("button", { name: "Configure" }).click();
   };
 
   await ready(page, "/admin/settings");

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

@@ -1,16 +1,13 @@
-import { expect, test, type Page } from "@playwright/test";
+import { type Page } from "@playwright/test";
+import { expect, test, type DisposableUsers } from "../helpers/disposable-users";
 import { ready } from "../helpers/hydration";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 
 // Seed a throwaway user via the API (admin cookies come from storageState) so
 // the mutating UI tests don't touch the shared admin/user seed accounts.
-async function seedUser(page: Page, email: string): Promise<void> {
-  const res = await page.request.post("/api/auth/admin/create-user", {
-    headers: { origin: base },
-    data: { email, password: "Podokit3e-Str0ng!pw", name: "Throwaway", role: "user" },
-  });
-  expect(res.ok()).toBeTruthy();
+async function seedUser(disposableUsers: DisposableUsers, email: string): Promise<string> {
+  return disposableUsers.create({ email });
 }
 
 // Open the Manage two-pane modal for a seeded user.
@@ -21,7 +18,7 @@ async function openManage(page: Page, email: string): Promise<void> {
   await page.getByRole("menuitem", { name: "Manage" }).click();
 }
 
-test("admin can create a user via the dialog @smoke", async ({ page }) => {
+test("admin can create a user via the dialog @smoke", async ({ page, disposableUsers }) => {
   await ready(page, "/admin/users");
   const email = `ui-create-${Date.now()}@example.com`;
   await page.getByRole("button", { name: "Add user" }).click();
@@ -30,7 +27,13 @@ test("admin can create a user via the dialog @smoke", async ({ page }) => {
   await dialog.getByLabel("Email").fill(email);
   await dialog.getByLabel("Password", { exact: true }).fill("Podokit3e-Str0ng!pw");
   await dialog.getByLabel("Confirm password").fill("Podokit3e-Str0ng!pw");
+  const created = page.waitForResponse(
+    (response) =>
+      response.url().endsWith("/api/auth/admin/create-user") &&
+      response.request().method() === "POST",
+  );
   await dialog.getByRole("button", { name: "Create" }).click();
+  await disposableUsers.trackResponse(await created);
   // Wait for the create to settle (dialog closes + list reloads) before searching,
   // otherwise the search input can be refilled by the post-create reload.
   await expect(page.getByRole("dialog")).toBeHidden();
@@ -51,10 +54,10 @@ test("create rejects mismatched passwords", async ({ page }) => {
   await expect(dialog.getByText("Passwords do not match")).toBeVisible();
 });
 
-test("manage: edit profile name", async ({ page }) => {
+test("manage: edit profile name", async ({ page, disposableUsers }) => {
   await ready(page, "/admin/users");
   const email = `ui-edit-${Date.now()}@example.com`;
-  await seedUser(page, email);
+  await seedUser(disposableUsers, email);
   await openManage(page, email);
   const dialog = page.getByRole("dialog");
   await dialog.getByLabel("Name").fill("Edited Name");
@@ -62,10 +65,10 @@ test("manage: edit profile name", async ({ page }) => {
   await expect(page.getByText("User updated")).toBeVisible();
 });
 
-test("manage: set a password (and reject mismatch)", async ({ page }) => {
+test("manage: set a password (and reject mismatch)", async ({ page, disposableUsers }) => {
   await ready(page, "/admin/users");
   const email = `ui-setpw-${Date.now()}@example.com`;
-  await seedUser(page, email);
+  await seedUser(disposableUsers, email);
   await openManage(page, email);
   const dialog = page.getByRole("dialog");
   await dialog.getByRole("button", { name: "Security" }).click();
@@ -78,10 +81,10 @@ test("manage: set a password (and reject mismatch)", async ({ page }) => {
   await expect(page.getByText("Password updated")).toBeVisible();
 });
 
-test("manage: ban a user with a reason", async ({ page }) => {
+test("manage: ban a user with a reason", async ({ page, disposableUsers }) => {
   await ready(page, "/admin/users");
   const email = `ui-ban-${Date.now()}@example.com`;
-  await seedUser(page, email);
+  await seedUser(disposableUsers, email);
   await openManage(page, email);
   const dialog = page.getByRole("dialog");
   await dialog.getByRole("button", { name: "Security" }).click();
@@ -90,10 +93,10 @@ test("manage: ban a user with a reason", async ({ page }) => {
   await expect(page.getByText("User banned", { exact: true })).toBeVisible();
 });
 
-test("manage: revoke a user's session", async ({ page, playwright }) => {
+test("manage: revoke a user's session", async ({ page, playwright, disposableUsers }) => {
   await ready(page, "/admin/users");
   const email = `ui-sess-${Date.now()}@example.com`;
-  await seedUser(page, email);
+  await seedUser(disposableUsers, email);
   // create a session for the user in an isolated context (don't touch the admin cookie)
   const uctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: { origin: base } });
   expect((await uctx.post("/api/auth/sign-in/email", { data: { email, password: "Podokit3e-Str0ng!pw" } })).ok()).toBeTruthy();
@@ -105,39 +108,42 @@ test("manage: revoke a user's session", async ({ page, playwright }) => {
   await expect(page.getByText("Session revoked")).toBeVisible();
 });
 
-test("manage: delete a user from the danger zone", async ({ page }) => {
+test("manage: delete a user from the danger zone", async ({ page, disposableUsers }) => {
   await ready(page, "/admin/users");
   const email = `ui-delete-${Date.now()}@example.com`;
-  await seedUser(page, email);
+  const userId = await seedUser(disposableUsers, email);
   await openManage(page, email);
   const dialog = page.getByRole("dialog");
   await dialog.getByRole("button", { name: "Danger zone" }).click();
   await dialog.getByRole("button", { name: "Delete" }).click(); // arm
   await dialog.getByRole("button", { name: "Delete" }).click(); // confirm
   await expect(page.getByText("User deleted")).toBeVisible();
+  disposableUsers.forget(userId);
   await page.locator("#toolbar-search").fill(email);
   await page.getByRole("button", { name: "Search", exact: true }).click();
   await expect(page.getByRole("cell", { name: email })).toHaveCount(0);
 });
 
-test("users list shows pagination beyond one page", async ({ page }) => {
+test("users list shows pagination beyond one page", async ({ page, disposableUsers }) => {
   await ready(page, "/admin/users");
-  for (let i = 0; i < 6; i += 1) {
-    await page.request.post("/api/auth/admin/create-user", {
-      headers: { origin: base },
-      data: { email: `pg-${Date.now()}-${i}@example.com`, password: "Podokit3e-Str0ng!pw", name: `Pg${i}`, role: "user" },
+  const prefix = `pg-${Date.now()}`;
+  for (let i = 0; i < 16; i += 1) {
+    await disposableUsers.create({
+      email: `${prefix}-${i}@example.com`,
+      name: `Page user ${i}`,
     });
   }
-  await page.reload();
-  const nav = page.getByRole("navigation", { name: "pagination" });
+  await page.locator("#toolbar-search").fill(prefix);
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  const nav = page.getByRole("navigation", { name: "pagination" }).first();
   await expect(nav).toBeVisible();
-  await expect(nav.getByRole("button", { name: "Page 2" })).toBeVisible();
+  await expect(nav.getByRole("button", { name: "Page 2", exact: true }).first()).toBeVisible();
 });
 
-test("manage modal closes from its footer", async ({ page }) => {
+test("manage modal closes from its footer", async ({ page, disposableUsers }) => {
   await ready(page, "/admin/users");
   const email = `ui-close-${Date.now()}@example.com`;
-  await seedUser(page, email);
+  await seedUser(disposableUsers, email);
   await openManage(page, email);
   // footer Close (a visible button, distinct from the header X) dismisses the modal
   await page.getByRole("dialog").getByRole("button", { name: "Close", exact: true }).last().click();

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

@@ -1,9 +1,9 @@
-import { expect, test } from "@playwright/test";
+import { expect, test } from "../helpers/disposable-users";
 import { ready } from "../helpers/hydration";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 
-test("admin can create a user with a custom role", async ({ page }) => {
+test("admin can create a user with a custom role", async ({ page, disposableUsers }) => {
   await ready(page, "/admin/users");
   await page.getByRole("button", { name: "Add user" }).click();
   const role = page.locator("#c-role");
@@ -16,7 +16,13 @@ test("admin can create a user with a custom role", async ({ page }) => {
   // pick the Moderator role from the select
   await role.click();
   await page.getByRole("option", { name: "Moderator" }).click();
+  const created = page.waitForResponse(
+    (response) =>
+      response.url().endsWith("/api/auth/admin/create-user") &&
+      response.request().method() === "POST",
+  );
   await page.getByRole("button", { name: "Create", exact: true }).click();
+  await disposableUsers.trackResponse(await created);
   await expect(page.getByText("User created")).toBeVisible();
   // it appears in the list, filterable by the Moderator role
   await page.locator("#toolbar-search").fill(email);
@@ -52,43 +58,27 @@ test("row menu exposes admin actions", async ({ page }) => {
   await expect(page.getByRole("menuitem", { name: "Impersonate" })).toBeVisible();
 });
 
-test("admin can approve a pending registration from the user list", async ({ page }) => {
+test("admin can approve a pending registration from the user list", async ({ page, disposableUsers }) => {
   const email = `pending-ui-${Date.now()}@example.com`;
-  const created = await page.request.post("/api/auth/admin/create-user", {
-    headers: { origin: base },
-    data: { email, password: "Podokit3e-Str0ng!pw", name: "Pending UI", role: "user" },
-  });
-  expect(created.ok()).toBeTruthy();
-  const userId = ((await created.json()).user?.id ?? "") as string;
+  const userId = await disposableUsers.create({ email, name: "Pending UI" });
+  expect(
+    (await page.request.post("/api/auth/admin/update-user", {
+      headers: { origin: base },
+      data: { userId, data: { signupApproved: false } },
+    })).ok(),
+  ).toBeTruthy();
 
-  try {
-    expect(userId).toBeTruthy();
-    expect(
-      (await page.request.post("/api/auth/admin/update-user", {
-        headers: { origin: base },
-        data: { userId, data: { signupApproved: false } },
-      })).ok(),
-    ).toBeTruthy();
-
-    await ready(page, "/admin/users");
-    await page.locator("#toolbar-search").fill(email);
-    await page.getByRole("button", { name: "Search", exact: true }).click();
-    const row = page.getByRole("row", { name: new RegExp(email) });
-    await expect(row.getByText("Pending approval")).toBeVisible();
-    await row.getByRole("button").click();
-    const response = page.waitForResponse(
-      (res) => res.url().endsWith("/api/auth/admin/update-user") && res.request().method() === "POST",
-    );
-    await page.getByRole("menuitem", { name: "Approve sign-up" }).click();
-    expect((await response).ok()).toBeTruthy();
-    await expect(page.getByText("Sign-up approved")).toBeVisible();
-    await expect(row.getByText("Active")).toBeVisible();
-  } finally {
-    if (userId) {
-      await page.request.post("/api/auth/admin/remove-user", {
-        headers: { origin: base },
-        data: { userId },
-      });
-    }
-  }
+  await ready(page, "/admin/users");
+  await page.locator("#toolbar-search").fill(email);
+  await page.getByRole("button", { name: "Search", exact: true }).click();
+  const row = page.getByRole("row", { name: new RegExp(email) });
+  await expect(row.getByText("Pending approval")).toBeVisible();
+  await row.getByRole("button").click();
+  const response = page.waitForResponse(
+    (res) => res.url().endsWith("/api/auth/admin/update-user") && res.request().method() === "POST",
+  );
+  await page.getByRole("menuitem", { name: "Approve sign-up" }).click();
+  expect((await response).ok()).toBeTruthy();
+  await expect(page.getByText("Sign-up approved")).toBeVisible();
+  await expect(row.getByText("Active")).toBeVisible();
 });

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -1,6 +1,7 @@
 {
+  "manifestVersion": 2,
   "name": "admin-dashboard",
-  "description": "Admin dashboard UI (SvelteKit + shadcn-svelte): login/signup/password-reset, a sidebar shell, and user + session management via the better-auth admin plugin. Requires auth.",
+  "description": "Admin console UI (SvelteKit + shadcn-svelte): the `(admin)` route group and `admin-sidebar.svelte` are reserved for `/admin/*`; put protected product pages in `(app)` or their own guarded layout. Requires auth.",
   "requires": [
     "auth",
     "object-storage-s3"
@@ -10,21 +11,22 @@
     "qrcode": "^1.5.4"
   },
   "devDependencies": {
-    "@types/qrcode": "^1.5.5",
-    "@types/multer": "^1.4.12"
+    "@types/qrcode": "^1.5.5"
   },
   "ownedGlobs": [
     "apps/web/src/lib/i18n/locales/**",
     "apps/web/src/lib/i18n/catalogs/app/**"
   ],
   "managedOverrides": [
+    "apps/web/src/lib/components/ui/input/input.svelte",
     "apps/web/src/routes/(app)/+layout.server.ts",
-    "apps/web/src/routes/(app)/admin/account/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/audit/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/organizations/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/sessions/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/settings/+page.server.ts",
-    "apps/web/src/routes/(app)/admin/users/+page.server.ts",
+    "apps/web/src/routes/(admin)/+layout.server.ts",
+    "apps/web/src/routes/(admin)/admin/account/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/audit/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/organizations/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/sessions/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/settings/+page.server.ts",
+    "apps/web/src/routes/(admin)/admin/users/+page.server.ts",
     "apps/web/src/routes/(auth)/login/+page.server.ts",
     "apps/web/src/routes/(auth)/signup/+page.server.ts",
     "apps/web/src/routes/account/+page.server.ts",
@@ -32,6 +34,12 @@
   ],
   "packageOverlays": {
     "api": {
+      "dependencies": {
+        "image-size": "^2.0.2"
+      },
+      "devDependencies": {
+        "@types/multer": "^1.4.12"
+      },
       "scripts": {
         "admin:bootstrap": "node scripts/bootstrap-admin.mjs"
       }
@@ -41,7 +49,52 @@
     "# admin-dashboard: emails auto-promoted to the admin role on sign-up (comma-separated)",
     "ADMIN_EMAILS=admin@example.com"
   ],
+  "migrations": [
+    {
+      "id": "admin-route-group",
+      "moves": [
+        {
+          "from": "apps/web/src/routes/(app)/+layout.svelte",
+          "to": "apps/web/src/routes/(admin)/+layout.svelte"
+        },
+        {
+          "from": "apps/web/src/routes/(app)/admin",
+          "to": "apps/web/src/routes/(admin)/admin"
+        },
+        {
+          "from": "apps/web/src/lib/components/app-sidebar.svelte",
+          "to": "apps/web/src/lib/components/admin-sidebar.svelte"
+        }
+      ],
+      "replacements": [
+        {
+          "path": "apps/web/src/routes/(admin)/+layout.svelte",
+          "from": "AppSidebar",
+          "to": "AdminSidebar",
+          "expected": 2
+        },
+        {
+          "path": "apps/web/src/routes/(admin)/+layout.svelte",
+          "from": "$lib/components/app-sidebar.svelte",
+          "to": "$lib/components/admin-sidebar.svelte",
+          "expected": 1
+        }
+      ]
+    }
+  ],
   "inject": [
+    {
+      "file": "apps/web/src/routes/+page.svelte",
+      "marker": "// podokit:end:landing-imports",
+      "optional": true,
+      "text": "import { page } from \"$app/state\";\n  import AccountMenu from \"$lib/components/account-menu.svelte\";\n  import LanguageSwitch from \"$lib/components/language-switch.svelte\";\n  import ThemeToggle from \"$lib/components/theme-toggle.svelte\";"
+    },
+    {
+      "file": "apps/web/src/routes/+page.svelte",
+      "marker": "<!-- podokit:end:landing-actions -->",
+      "optional": true,
+      "text": "<header class=\"flex items-center justify-end gap-2 p-4\">\n  <LanguageSwitch />\n  <ThemeToggle />\n  <AccountMenu user={page.data.user ?? null} />\n</header>"
+    },
     {
       "file": "apps/api/src/auth/auth.ts",
       "marker": "// podokit:end:auth-imports",
@@ -66,24 +119,34 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `$lib/server/guards` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand.\n"
+      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `$lib/server/guards` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
     },
     {
       "file": "apps/api/src/app.module.ts",
       "marker": "// podokit:end:imports",
       "text": "import { SiteSettingsModule } from \"./site-settings/site-settings.module\";"
     },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:imports",
+      "text": "import { ProfileImageModule } from \"./profile-image/profile-image.module\";"
+    },
     {
       "file": "apps/api/src/app.module.ts",
       "marker": "// podokit:end:module-imports",
       "text": "SiteSettingsModule,"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:end:module-imports",
+      "text": "ProfileImageModule,"
     }
   ],
   "instructions": [
     "Set ADMIN_EMAILS in .env (comma-separated). After building and migrating, inject ADMIN_BOOTSTRAP_EMAIL and ADMIN_BOOTSTRAP_PASSWORD for one command only, then run npm run admin:bootstrap -w <app>-api. The command creates a verified, approved admin or safely verifies an existing one.",
     "Re-run the auth migration to add the admin and sign-up approval columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
     "Remove ADMIN_BOOTSTRAP_PASSWORD from the environment after bootstrap. Keep ADMIN_EMAILS so matching future sign-ups are promoted consistently.",
-    "Admin pages: /admin/users (list, approve pending registrations, ban, set role, revoke sessions). Signed-in users manage their profile and security at /account; /admin/account remains available in the admin shell. Admin, account, authentication, maintenance, and API responses include X-Robots-Tag: noindex, nofollow by default.",
+    "Admin pages: /admin/users (list, approve pending registrations, ban, set role, revoke sessions). Signed-in users manage their profile, profile image, and security at /account; /admin/account remains available in the admin shell. Profile images accept PNG, JPEG, and WebP up to 2 MB and 2048 by 2048 pixels. Admin, account, authentication, maintenance, and API responses include X-Robots-Tag: noindex, nofollow by default.",
     "Password reset emails go through the mailer module (installed automatically with auth); in dev without SMTP they are logged to the API console. Configure SMTP in admin settings or via SMTP_* env for production."
   ]
 }

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -11,6 +11,7 @@ import { apiKey } from "@better-auth/api-key";
 import { passkey } from "@better-auth/passkey";
 import { oauthProvider } from "@better-auth/oauth-provider";
 import { SIGNUP_APPROVAL_REQUIRED } from "@podosoft/podokit-contracts";
+import { runUserDeletedHandlers } from "./user-delete-handlers";
 // podokit:begin:auth-imports
 // podokit:end:auth-imports
 
@@ -259,7 +260,10 @@ export function buildAuth(config: AuthConfig) {
         },
       },
       // Self-service account deletion — admin-toggleable (auth_config), applied live.
-      deleteUser: { enabled: config.allowDelete },
+      deleteUser: {
+        enabled: config.allowDelete,
+        afterDelete: runUserDeletedHandlers,
+      },
     },
     databaseHooks,
     // podokit:begin:auth-options

package/dist/templates/modules/auth/files/apps/api/src/auth/user-delete-handlers.spec.ts

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it, jest } from "@jest/globals";
+import {
+  registerUserDeletedHandler,
+  runUserDeletedHandlers,
+  type UserDeletedHandler,
+} from "./user-delete-handlers";
+
+describe("user deletion handlers", () => {
+  const unregister: Array<() => void> = [];
+
+  afterEach(() => {
+    for (const remove of unregister.splice(0)) remove();
+    jest.restoreAllMocks();
+  });
+
+  function register(handler: UserDeletedHandler): void {
+    unregister.push(registerUserDeletedHandler(handler));
+  }
+
+  it("runs registered module cleanup with the deleted user", async () => {
+    const handler: UserDeletedHandler = jest.fn(async () => undefined);
+    register(handler);
+    const user = { id: "user-1", image: "/api/profile-images/avatar.png" };
+
+    await runUserDeletedHandlers(user);
+
+    expect(handler).toHaveBeenCalledWith(user);
+  });
+
+  it("does not fail account deletion when one cleanup rejects", async () => {
+    jest.spyOn(console, "error").mockImplementation(() => undefined);
+    register(async () => {
+      throw new Error("storage unavailable");
+    });
+
+    await expect(runUserDeletedHandlers({ id: "user-1" })).resolves.toBeUndefined();
+    expect(console.error).toHaveBeenCalledWith(
+      "Run user deletion cleanup failed",
+      expect.objectContaining({ userId: "user-1", error: "storage unavailable" }),
+    );
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/user-delete-handlers.ts

@@ -0,0 +1,27 @@
+export interface DeletedUser {
+  id: string;
+  image?: string | null;
+}
+
+export type UserDeletedHandler = (user: DeletedUser) => Promise<void>;
+
+const handlers = new Set<UserDeletedHandler>();
+
+/** Register module-owned cleanup that should run after better-auth removes a user. */
+export function registerUserDeletedHandler(handler: UserDeletedHandler): () => void {
+  handlers.add(handler);
+  return () => handlers.delete(handler);
+}
+
+/** Run every cleanup without turning a completed account deletion into an error. */
+export async function runUserDeletedHandlers(user: DeletedUser): Promise<void> {
+  const results = await Promise.allSettled([...handlers].map((handler) => handler(user)));
+  for (const result of results) {
+    if (result.status === "rejected") {
+      console.error("Run user deletion cleanup failed", {
+        userId: user.id,
+        error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+      });
+    }
+  }
+}

package/dist/templates/modules/auth/module.manifest.json

@@ -8,7 +8,7 @@
   ],
   "dependencies": {
     "@podosoft/podokit-auth": "^0.3.0",
-    "@podosoft/podokit-contracts": "^0.3.0",
+    "@podosoft/podokit-contracts": "^0.4.0",
     "better-auth": "^1.6.23",
     "@thallesp/nestjs-better-auth": "^2.7.0",
     "pg": "^8.12.0",

package/dist/templates/todo/Dockerfile.dev

@@ -17,7 +17,9 @@ WORKDIR /app
 COPY package.json ./
 COPY apps/api/package.json ./apps/api/package.json
 COPY apps/web/package.json ./apps/web/package.json
-RUN npm install
+ARG PODOKIT_NPM_REGISTRY=""
+RUN if [ -n "$PODOKIT_NPM_REGISTRY" ]; then npm config set registry "$PODOKIT_NPM_REGISTRY"; fi \
+  && npm install
 
 # Baked source (kept in sync during development by `docker compose watch`).
 COPY . .

package/dist/templates/todo/apps/api/package.json

@@ -14,7 +14,7 @@
     "migration:generate": "npm run typeorm -- migration:generate"
   },
   "dependencies": {
-    "@podosoft/podokit-contracts": "^0.3.0",
+    "@podosoft/podokit-contracts": "^0.4.0",
     "@nestjs/common": "^11.1.27",
     "@nestjs/config": "^4.0.4",
     "@nestjs/core": "^11.1.27",

package/dist/templates/todo/apps/web/package.json

@@ -13,7 +13,7 @@
   "dependencies": {
     "@internationalized/date": "^3.12.2",
     "@lucide/svelte": "^1.23.0",
-    "@podosoft/podokit-api-client": "^0.7.0",
+    "@podosoft/podokit-api-client": "^0.8.0",
     "bits-ui": "^2.18.1",
     "clsx": "^2.1.1",
     "mode-watcher": "^1.1.0",

package/dist/templates/todo/compose.dev.yaml

@@ -41,6 +41,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile.dev
+      args:
+        PODOKIT_NPM_REGISTRY: ${PODOKIT_NPM_REGISTRY:-}
     command: npm run dev -w {{projectName}}-web -- --host 0.0.0.0
     working_dir: /app
     env_file: .env.docker
@@ -64,6 +66,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile.dev
+      args:
+        PODOKIT_NPM_REGISTRY: ${PODOKIT_NPM_REGISTRY:-}
     init: true
     command: npm run dev -w {{projectName}}-api
     working_dir: /app
@@ -87,6 +91,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile.dev
+      args:
+        PODOKIT_NPM_REGISTRY: ${PODOKIT_NPM_REGISTRY:-}
     init: true
     command: npm run dev:worker -w {{projectName}}-api
     working_dir: /app