@podosoft/podokit 0.13.0 → 0.14.0

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(app)/+layout.server.ts

@@ -1,51 +1,6 @@
-import { redirect } from "@sveltejs/kit";
 import type { LayoutServerLoad } from "./$types";
-import type { Capabilities } from "@podosoft/podokit-api-client";
-import { requireBackendAvailable } from "$lib/server/guards";
+import { loadProtectedLayout } from "$lib/server/protected-layout";
 
 export const load: LayoutServerLoad = async ({ locals, fetch }) => {
-  requireBackendAvailable(locals);
-
-  let capabilities: Capabilities = {
-    twoFactor: false,
-    providers: [],
-    deleteAccount: false,
-    auditLog: false,
-    emailVerification: false,
-    signupApprovalRequired: false,
-    passwordBreachCheck: false,
-    magicLink: false,
-    emailOtp: false,
-    username: false,
-    multiSession: false,
-    phoneNumber: false,
-    apiKey: false,
-    passkey: false,
-    organization: false,
-    oidcProvider: false,
-    roles: ["admin", "user"],
-  };
-  try {
-    const res = await fetch("/api/account/capabilities");
-    if (res.ok) capabilities = (await res.json()) as Capabilities;
-  } catch {
-    /* keep defaults */
-  }
-
-  // Require-two-factor policy: a signed-in user who hasn't enrolled is sent to the
-  // enrolment page until they do (the API's TwoFactorRequiredGuard is the real
-  // boundary; this is the UX). /setup-2fa lives outside this layout, so no loop.
-  const user = locals.user as (App.Locals["user"] & { twoFactorEnabled?: boolean }) | null;
-  let mustEnrol = false;
-  if (user && !user.twoFactorEnabled) {
-    try {
-      const res = await fetch("/api/account/require-2fa");
-      mustEnrol = res.ok && ((await res.json()) as { require2fa?: boolean }).require2fa === true;
-    } catch {
-      /* don't block the app if the policy check fails */
-    }
-  }
-  if (mustEnrol) redirect(302, "/setup-2fa");
-
-  return { user: locals.user, impersonating: !!locals.session?.impersonatedBy, capabilities };
+  return loadProtectedLayout({ locals, fetch });
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/+page.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { page } from "$app/state";
+  import AccountMenu from "$lib/components/account-menu.svelte";
   import { Button } from "$lib/components/ui/button";
   import LanguageSwitch from "$lib/components/language-switch.svelte";
   import ThemeToggle from "$lib/components/theme-toggle.svelte";
@@ -6,12 +8,14 @@
   import { getI18n } from "$lib/i18n";
 
   const i18n = getI18n();
+  const user = $derived(page.data.user ?? null);
 </script>
 
 <div class="flex min-h-svh flex-col">
   <header class="flex items-center justify-end gap-2 p-4">
     <LanguageSwitch />
     <ThemeToggle />
+    <AccountMenu {user} />
   </header>
   <main class="flex flex-1 flex-col items-center justify-center gap-6 px-4 text-center">
     <div class="flex flex-col gap-3">

package/dist/templates/modules/admin-dashboard/files/tests/api/profile-image.api.spec.ts

@@ -0,0 +1,96 @@
+import { expect, test } from "@playwright/test";
+import { ADMIN } from "../helpers/accounts";
+
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+const PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAIAAAADAQMAAACDJEzCAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCSUTzXBDTwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozNzoxOSswMDowMOuehLIAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzc6MTkrMDA6MDCawzwOAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM3OjE5KzAwOjAwzdYd0QAAAAtJREFUCNdjYAABAAAGAAFm9MlsAAAAAElFTkSuQmCC",
+  "base64",
+);
+const TOO_WIDE_PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAACAEAAAABAQMAAACfGLePAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCScoTk3I6QAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozOTo0MCswMDowMCgv/7YAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzk6NDArMDA6MDBZckcKAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM5OjQwKzAwOjAwDmdm1QAAAAxJREFUGNNjYBjpAAABAgABRf+HpwAAAABJRU5ErkJggg==",
+  "base64",
+);
+
+async function adminContext(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+  const context = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await context.post("/api/auth/sign-in/email", {
+    data: { email: ADMIN.email, password: ADMIN.password },
+  });
+  return context;
+}
+
+test("profile image upload requires authentication", async ({ playwright }) => {
+  const anonymous = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const response = await anonymous.post("/api/account/profile-image", {
+    multipart: { file: { name: "avatar.png", mimeType: "image/png", buffer: PNG } },
+  });
+  expect(response.status()).toBe(401);
+  await anonymous.dispose();
+});
+
+test("profile image upload, replacement, public read, and removal", async ({ playwright }) => {
+  const admin = await adminContext(playwright);
+  await admin.delete("/api/account/profile-image");
+
+  const first = await admin.post("/api/account/profile-image", {
+    multipart: { file: { name: "avatar.png", mimeType: "image/png", buffer: PNG } },
+  });
+  expect(first.status()).toBe(201);
+  const firstBody = await first.json() as { image: string };
+  expect(firstBody.image).toMatch(/^\/api\/profile-images\/[0-9a-f-]+\.png$/);
+
+  const sessionAfterUpload = await (await admin.get("/api/auth/get-session")).json() as {
+    user: { image?: string | null };
+  };
+  expect(sessionAfterUpload.user.image).toBe(firstBody.image);
+  const firstImage = await admin.get(firstBody.image);
+  expect(firstImage.ok()).toBeTruthy();
+  expect(firstImage.headers()["content-type"]).toContain("image/png");
+  expect(firstImage.headers()["cache-control"]).toBe("public, max-age=31536000, immutable");
+
+  const replacement = await admin.post("/api/account/profile-image", {
+    multipart: { file: { name: "replacement.png", mimeType: "image/png", buffer: PNG } },
+  });
+  expect(replacement.status()).toBe(201);
+  const replacementBody = await replacement.json() as { image: string };
+  expect(replacementBody.image).not.toBe(firstBody.image);
+  expect((await admin.get(firstBody.image)).status()).toBe(404);
+
+  const removed = await admin.delete("/api/account/profile-image");
+  expect(await removed.json()).toEqual({ image: null });
+  expect((await admin.get(replacementBody.image)).status()).toBe(404);
+  const sessionAfterRemoval = await (await admin.get("/api/auth/get-session")).json() as {
+    user: { image?: string | null };
+  };
+  expect(sessionAfterRemoval.user.image).toBeNull();
+  await admin.dispose();
+});
+
+test("profile image upload returns stable validation errors", async ({ playwright }) => {
+  const admin = await adminContext(playwright);
+  const invalidType = await admin.post("/api/account/profile-image", {
+    multipart: { file: { name: "avatar.png", mimeType: "image/png", buffer: Buffer.from("not an image") } },
+  });
+  expect(invalidType.status()).toBe(400);
+  expect((await invalidType.json()).error.code).toBe("PROFILE_IMAGE_TYPE_INVALID");
+
+  const tooWide = await admin.post("/api/account/profile-image", {
+    multipart: { file: { name: "wide.png", mimeType: "image/png", buffer: TOO_WIDE_PNG } },
+  });
+  expect(tooWide.status()).toBe(400);
+  expect((await tooWide.json()).error.code).toBe("PROFILE_IMAGE_DIMENSIONS_INVALID");
+
+  const tooLarge = await admin.post("/api/account/profile-image", {
+    multipart: {
+      file: {
+        name: "large.png",
+        mimeType: "image/png",
+        buffer: Buffer.alloc(2 * 1024 * 1024 + 1),
+      },
+    },
+  });
+  expect(tooLarge.status()).toBe(413);
+  expect((await tooLarge.json()).error.code).toBe("PROFILE_IMAGE_TOO_LARGE");
+  await admin.dispose();
+});

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

@@ -2,6 +2,15 @@ import { expect, test } from "@playwright/test";
 import { ready } from "../helpers/hydration";
 import { ADMIN } from "../helpers/accounts";
 
+const PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAIAAAADAQMAAACDJEzCAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCSUTzXBDTwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozNzoxOSswMDowMOuehLIAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzc6MTkrMDA6MDCawzwOAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM3OjE5KzAwOjAwzdYd0QAAAAtJREFUCNdjYAABAAAGAAFm9MlsAAAAAElFTkSuQmCC",
+  "base64",
+);
+const TOO_WIDE_PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAACAEAAAABAQMAAACfGLePAAAAIGNIUk0AAHomAACAhAAA+gAAAIDoAAB1MAAA6mAAADqYAAAXcJy6UTwAAAAGUExURWYzmf///129H+IAAAABYktHRAH/Ai3eAAAAB3RJTUUH6gcVCScoTk3I6QAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyNi0wNy0yMVQwOTozOTo0MCswMDowMCgv/7YAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjYtMDctMjFUMDk6Mzk6NDArMDA6MDBZckcKAAAAKHRFWHRkYXRlOnRpbWVzdGFtcAAyMDI2LTA3LTIxVDA5OjM5OjQwKzAwOjAwDmdm1QAAAAxJREFUGNNjYBjpAAABAgABRf+HpwAAAABJRU5ErkJggg==",
+  "base64",
+);
+
 // admin storageState (project default)
 test("account opens on the profile section @smoke", async ({ page }) => {
   await ready(page, "/admin/account");
@@ -14,6 +23,60 @@ test("account opens on the profile section @smoke", async ({ page }) => {
   await expect(page.getByRole("button", { name: "Save changes" })).toBeEnabled();
 });
 
+test("protected app routes do not inherit the admin shell @smoke", async ({ page }) => {
+  await ready(page, "/accept-invitation/not-a-real-invitation");
+  await expect(page.getByText("Organization invitation", { exact: true })).toBeVisible();
+  await expect(page.getByTestId("sidebar-brand")).toHaveCount(0);
+
+  await ready(page, "/admin");
+  await expect(page.getByTestId("sidebar-brand")).toBeVisible();
+});
+
+test("account displays profile image limits and updates every avatar", async ({ page }) => {
+  await ready(page, "/account");
+  await page.request.delete("/api/account/profile-image");
+  await ready(page, "/account");
+  await expect(page.getByTestId("profile-image-hint")).toContainText(/PNG, JPEG, (?:or )?WebP/);
+  await expect(page.getByTestId("profile-image-hint")).toContainText(/2 ?MB/);
+  await expect(page.getByTestId("profile-image-hint")).toContainText(/2048 × 2048 ?px/);
+
+  await page.locator("#profile-image").setInputFiles({
+    name: "avatar.png",
+    mimeType: "image/png",
+    buffer: PNG,
+  });
+  await expect(page.getByText(/Profile image updated|프로필 이미지를 변경했습니다/)).toBeVisible();
+  await expect(page.getByTestId("profile-image-preview").locator("img")).toBeVisible();
+
+  await ready(page, "/");
+  await expect(page.getByTestId("account-menu").locator("img")).toBeVisible();
+  await ready(page, "/admin");
+  await expect(page.getByTestId("sidebar-user-menu").locator("img")).toBeVisible();
+
+  await ready(page, "/account");
+  await page.getByRole("button", { name: /Remove image|이미지 제거/ }).click();
+  await expect(page.getByText(/Profile image removed|프로필 이미지를 제거했습니다/)).toBeVisible();
+  await expect(page.getByTestId("profile-image-preview").locator("img")).toHaveCount(0);
+  await expect(page.getByRole("button", { name: /Upload image|이미지 업로드/ })).toBeVisible();
+});
+
+test("account rejects invalid profile images before upload", async ({ page }) => {
+  await ready(page, "/admin/account");
+  await page.locator("#profile-image").setInputFiles({
+    name: "avatar.txt",
+    mimeType: "text/plain",
+    buffer: Buffer.from("not an image"),
+  });
+  await expect(page.getByText(/Choose a valid PNG, JPEG, or WebP image|올바른 PNG, JPEG 또는 WebP 이미지를 선택해 주세요/)).toBeVisible();
+
+  await page.locator("#profile-image").setInputFiles({
+    name: "wide.png",
+    mimeType: "image/png",
+    buffer: TOO_WIDE_PNG,
+  });
+  await expect(page.getByText(/The image must not exceed 2048 × 2048 px|이미지는 2048 × 2048px를 초과할 수 없습니다/)).toBeVisible();
+});
+
 test("account exposes a change-email action when the address is edited", async ({ page }) => {
   await ready(page, "/admin/account");
   const email = page.getByLabel("Email");
@@ -106,7 +169,7 @@ test("account security and sessions sub-navigation", async ({ page }) => {
 
 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: "Profile", exact: true })).toBeVisible();
   await expect(page.getByRole("button", { name: "Security" })).toBeVisible();
   await expect(page.getByRole("button", { name: "Sessions" })).toBeVisible();
 });

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

@@ -10,6 +10,22 @@ test("overview shows the signed-in admin @smoke", async ({ page }) => {
   await expect(page.getByRole("main").getByText(ADMIN.email)).toBeVisible();
 });
 
+test("landing shows language, theme, and signed-in account actions", async ({ page }) => {
+  await ready(page, "/");
+  const language = page.getByRole("button", { name: /^(Language|언어)$/ });
+  const theme = page.getByRole("button", { name: /^(Toggle theme|테마 전환)$/ });
+  await expect(language).toBeVisible();
+  await expect(language.locator("svg")).toBeVisible();
+  await expect(theme).toBeVisible();
+  await expect(theme.locator("svg:visible")).toBeVisible();
+  await page.getByTestId("account-menu").click();
+  const label = page.getByRole("menu").locator('[data-slot="dropdown-menu-label"]');
+  await expect(label.getByText(ADMIN.name, { exact: true })).toBeVisible();
+  await expect(label.getByText(ADMIN.email, { exact: true })).toBeVisible();
+  await expect(page.getByRole("menuitem", { name: "Account" })).toBeVisible();
+  await expect(page.getByRole("menuitem", { name: "Sign out" })).toBeVisible();
+});
+
 test("sidebar navigates to sessions and account @smoke", async ({ page }) => {
   await ready(page, "/admin");
   await page.getByRole("link", { name: "Sessions" }).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/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- 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"
     },
     {
       "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

package/dist/update.d.ts

@@ -5,9 +5,11 @@ import { type Tier } from "./lockfile";
  * working copy, classifying each file. Applying the plan (writing files, 3-way
  * merging) is a later step (see ADR-0009).
  */
-export type Action = "update" | "merge" | "conflict" | "add" | "remove" | "skip" | "up-to-date";
+export type Action = "update" | "merge" | "conflict" | "add" | "move" | "remove" | "skip" | "up-to-date";
 export interface FileChange {
     path: string;
+    /** Previous path when this change is an update migration move. */
+    fromPath?: string;
     tier: Tier;
     action: Action;
     /** Why the action was chosen (for the report). */
@@ -33,6 +35,11 @@ export interface ApplyOptions {
 }
 export interface ApplyResult {
     written: string[];
+    /** Files relocated by module update migrations. */
+    moved: {
+        from: string;
+        to: string;
+    }[];
     removed: string[];
     /** Files 3-way merged cleanly. */
     merged: string[];