@podosoft/podokit 0.11.1 → 0.12.0

package/dist/templates/fullstack-nest-svelte/apps/web/vite.config.ts

@@ -2,15 +2,10 @@ import { sveltekit } from "@sveltejs/kit/vite";
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
 
-// Inside the dev container (compose.dev.yaml sets VITE_DOCKER=1): bind to all
-// interfaces, allow the Traefik hostname, and route HMR's WebSocket back through
-// Traefik. The browser reaches the app at Traefik's published host port, so the
-// HMR client must target that same port — otherwise the ws connects to :80,
-// fails, and Vite silently falls back to a full page reload on every change
-// (which wipes in-progress form input). compose.dev.yaml injects
-// VITE_HMR_CLIENT_PORT to match the published Traefik port (default 80).
+// Inside the dev container, bind to all interfaces and accept local gateway or
+// HTTPS tunnel hostnames. Vite derives HMR's protocol, host, and port from the
+// browser origin so the same configuration works for both entry points.
 const inDocker = process.env.VITE_DOCKER === "1";
-const hmrClientPort = Number(process.env.VITE_HMR_CLIENT_PORT) || 80;
 
 export default defineConfig({
   plugins: [tailwindcss(), sveltekit()],
@@ -19,7 +14,6 @@ export default defineConfig({
         host: true,
         port: 5001,
         allowedHosts: true,
-        hmr: { clientPort: hmrClientPort },
       }
     : undefined,
 });

package/dist/templates/fullstack-nest-svelte/compose.dev.yaml

@@ -1,13 +1,11 @@
 # Containerized development environment.
 #
-#   docker compose -f compose.dev.yaml watch                       # core stack
-#   docker compose -f compose.dev.yaml --profile cache \
-#     --profile storage --profile queue watch                     # with modules
+#   podo dev watch                                                # core stack
+#   podo dev watch --profile cache --profile storage \
+#     --profile queue                                             # with modules
 #
-# Only Traefik binds a host port (default 80). The app is at http://app.localhost.
-# Set TRAEFIK_PORT to publish on another port (e.g. TRAEFIK_PORT=8001) so several
-# containerized stacks can run at once without colliding — the web container reads
-# the same value as VITE_HMR_CLIENT_PORT so Vite HMR follows automatically.
+# A user-level PodoKit gateway owns loopback :80 and routes each *.localhost host
+# to this stack. The legacy per-project Traefik service is opt-in only.
 # api/postgres/redis/minio have NO published ports — they talk by service name
 # on the internal network, so this stack never collides with other projects.
 #
@@ -24,6 +22,7 @@ name: {{projectName}}-dev
 
 services:
   traefik:
+    profiles: [podokit-legacy-proxy]
     image: traefik:v3.5
     command:
       - --providers.file.filename=/etc/traefik/dynamic.yml
@@ -52,10 +51,6 @@ services:
       # getClientAddress() tied to the visitor instead of the proxy container.
       - ADDRESS_HEADER=x-forwarded-for
       - XFF_DEPTH=1
-      # Match Traefik's published port so HMR's WebSocket targets the right port
-      # (default 80). Without this, HMR connects to :80 and a non-80 stack falls
-      # back to a full page reload on every edit.
-      - VITE_HMR_CLIENT_PORT=${TRAEFIK_PORT:-80}
     depends_on: [api]
     networks: [podokit]
     develop:
@@ -83,6 +78,7 @@ services:
         # sync+restart is the stable, recommended approach; the web keeps instant
         # HMR via plain sync.
         - { action: sync+restart, path: ./apps/api/src, target: /app/apps/api/src }
+        - { action: sync, path: ./apps/api/scripts, target: /app/apps/api/scripts }
         - { action: rebuild, path: ./apps/api/package.json }
 
   worker:
@@ -105,6 +101,7 @@ services:
         # sync+restart is the stable, recommended approach; the web keeps instant
         # HMR via plain sync.
         - { action: sync+restart, path: ./apps/api/src, target: /app/apps/api/src }
+        - { action: sync, path: ./apps/api/scripts, target: /app/apps/api/scripts }
         - { action: rebuild, path: ./apps/api/package.json }
 
   postgres:

package/dist/templates/fullstack-nest-svelte/dot-claude/skills/podokit-add-locale/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: podokit-add-locale
+description: Add, translate, validate, activate, or troubleshoot a JSON locale in a PodoKit-generated SvelteKit app. Use when a user asks to add a language, split or edit locale JSON, check translation coverage or placeholders, configure fallback behavior, or verify locale changes through Vite HMR.
+---
+
+# PodoKit Add Locale
+
+Add languages through the PodoKit locale commands and the app-owned JSON catalog. Keep module catalogs managed so `podo update` can continue to update them.
+
+## Workflow
+
+1. Inspect the existing locale state.
+
+   ```sh
+   podo locale list
+   ```
+
+2. Add a canonical BCP 47 language tag. Set `--direction rtl` only for right-to-left languages.
+
+   ```sh
+   podo locale add pt-BR --name "Português (Brasil)"
+   ```
+
+3. Read [references/catalog-format.md](references/catalog-format.md), then translate the new app-owned file at `apps/web/src/lib/i18n/catalogs/app/<locale>.json`.
+
+4. Validate key coverage, JSON value types, and interpolation placeholders.
+
+   ```sh
+   podo locale validate pt-BR
+   ```
+
+5. Activate the locale. Partial catalogs are permitted because runtime fallback fills missing keys, but report the coverage percentage to the user.
+
+   ```sh
+   podo locale activate pt-BR
+   ```
+
+6. Run the app with its documented container-based development command. Verify the language switch, one complete key, one fallback key, and locale persistence. Editing an existing JSON file must update through Vite HMR without restarting the container. Adding a new locale file may trigger an automatic full-page reload.
+
+## Rules
+
+- Treat `en` as the stable final fallback and never deactivate it.
+- Preserve placeholders exactly. For example, translate `Hello {name}` without renaming or removing `{name}`.
+- Put product-specific copy only in `catalogs/app/`. Do not edit `catalogs/admin-dashboard/` or other module catalogs directly.
+- Keep locale definition filenames identical to their canonical codes, including case such as `pt-BR.json`.
+- Do not activate a locale definition before its JSON parses and `podo locale validate` succeeds.
+- Do not use the UI message catalogs for user-authored records. Dynamic content needs locale-aware records and a separate publication/fallback policy.
+- When deactivating a locale, preserve its files so it can be reactivated without losing translations.
+
+## Fallback And Site Default
+
+The message runtime resolves missing keys in this order: selected locale, configured site default, then English. The site default is an administrator choice, not a build-time constant. Changing it must not delete or rewrite catalogs.
+
+If a requested language is unsupported or inactive, resolve it to the configured site default. Keep localized URL and SEO behavior in the consuming app; the catalogs provide translated strings but do not define routing policy.
+
+## Completion Checklist
+
+- `podo locale validate` succeeds for every active locale.
+- The new locale definition is active and has the intended display name and direction.
+- App-owned JSON contains the new product copy; managed module catalogs remain untouched.
+- Development edits update without a container restart.
+- Automated tests cover selection, fallback, placeholders, and at least one incomplete catalog.
+- User-facing locale setup or routing documentation is updated when behavior changes.

package/dist/templates/fullstack-nest-svelte/dot-claude/skills/podokit-add-locale/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PodoKit Locale Setup"
+  short_description: "Add and validate JSON locale catalogs safely"
+  default_prompt: "Use $podokit-add-locale to add, validate, activate, and test a new JSON locale in this PodoKit app."

package/dist/templates/fullstack-nest-svelte/dot-claude/skills/podokit-add-locale/references/catalog-format.md

@@ -0,0 +1,49 @@
+# JSON Catalog Format
+
+## Directory Layout
+
+```text
+apps/web/src/lib/i18n/
+├── locales/
+│   ├── en.json
+│   ├── ko.json
+│   └── pt-BR.json
+└── catalogs/
+    ├── admin-dashboard/  # PodoKit-managed module messages
+    ├── blog/             # module-managed messages when installed
+    └── app/              # app-owned product messages and overrides
+```
+
+Each locale definition has this shape:
+
+```json
+{
+  "code": "pt-BR",
+  "name": "Português (Brasil)",
+  "direction": "ltr",
+  "enabled": false
+}
+```
+
+`code` must be a canonical BCP 47 tag and must match the filename. `direction` is `ltr` or `rtl`. Newly added locales stay inactive until explicitly activated.
+
+## Catalog Composition
+
+Catalogs are nested JSON objects with strings at their leaves:
+
+```json
+{
+  "common": {
+    "save": "Save",
+    "welcome": "Welcome, {name}"
+  }
+}
+```
+
+The runtime lazily loads every `catalogs/*/<locale>.json` file. Module catalogs are merged first in stable name order; the `app` catalog is merged last, so the consuming app may intentionally override module copy without modifying managed files.
+
+English defines the complete key and value-type contract. Other locales may omit keys, but translated values must retain the English type and all `{placeholder}` names. JSON objects and arrays are supported; executable expressions are not.
+
+## Development Reloading
+
+Catalog imports use Vite's `import.meta.glob`. Changes to an existing JSON dependency participate in Vite HMR and must appear without restarting the development container. A new file changes the glob membership and may cause Vite to reload the page automatically. If neither occurs, confirm that the app source directory, including `apps/web/src`, is mounted or synced by the development compose configuration.

package/dist/templates/fullstack-nest-svelte/dot-env.docker

@@ -6,11 +6,11 @@ POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 BACKEND_INTERNAL_URL=http://api:5002
-CORS_ORIGIN=http://app.localhost
+CORS_ORIGIN=http://{{projectName}}.localhost,http://localhost
 REDIS_HOST=redis
 REDIS_PORT=6379
 BETTER_AUTH_SECRET=change-me-in-container-min-32-characters
-BETTER_AUTH_URL=http://app.localhost
+BETTER_AUTH_URL=http://{{projectName}}.localhost
 ADMIN_EMAILS=admin@example.com
 AUDIT_LOG_ENABLED=true
 RATE_LIMIT_TTL=60

package/dist/templates/fullstack-nest-svelte/dot-gitignore

@@ -18,3 +18,6 @@ test-results/
 
 # local performance reports
 output/lighthouse/
+
+# podo dev generated compose overlay
+.podokit/runtime/

package/dist/templates/fullstack-nest-svelte/dot-podokit/dev.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "hostname": "{{projectName}}.localhost"
+}

package/dist/templates/fullstack-nest-svelte/tests/README.md

@@ -9,7 +9,13 @@ npm run test:e2e:ui      # pages (chromium)
 npm run test:e2e:report  # open the HTML report
 ```
 
-The suite runs against a live stack (web on `E2E_BASE_URL`, default
-`http://localhost:5001`, proxying `/api/*` to the API). Start PostgreSQL, run the
-auth migration, and start the API + web first. Files ending in `*.api.spec.ts` run
-in the request-only `api` project; `*.ui.spec.ts` run in the chromium `ui` project.
+The suite runs against a live stack (web on `E2E_BASE_URL`, proxying `/api/*` to
+the API). With the recommended containerized loop, start `podo dev watch` and run:
+
+```bash
+E2E_BASE_URL=http://{{projectName}}.localhost npm run test:e2e
+```
+
+The default `http://localhost:5001` is for the alternative `npm run dev`
+host-process loop. Files ending in `*.api.spec.ts` run in the request-only `api`
+project; `*.ui.spec.ts` run in the chromium `ui` project.

package/dist/templates/modules/admin-dashboard/files/apps/api/scripts/bootstrap-admin.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "node:url";
+
+const args = process.argv.slice(2);
+
+function has(flag) {
+  return args.includes(flag);
+}
+
+function required(name, value) {
+  if (!value?.trim()) throw new Error(`${name} is required.`);
+  return value.trim();
+}
+
+function usage() {
+  console.log(`Create or verify the initial PodoKit administrator.
+
+Usage:
+  npm run admin:bootstrap -w <app>-api
+  npm run admin:bootstrap -w <app>-api -- --dry-run
+  npm run admin:bootstrap -w <app>-api -- --check-only
+
+Required environment:
+  ADMIN_EMAILS               Allowed administrator emails (comma-separated)
+  ADMIN_BOOTSTRAP_EMAIL      Initial administrator email
+  ADMIN_BOOTSTRAP_PASSWORD   Initial administrator password
+
+Optional environment:
+  ADMIN_BOOTSTRAP_NAME       Display name (default: Administrator)
+
+AUTH_SETUP_ADMIN_EMAIL and AUTH_SETUP_ADMIN_PASSWORD work as fallbacks so the
+same ephemeral credentials can be reused by auth:configure.
+
+Options:
+  --dry-run                  Validate and print a redacted plan without writing
+  --check-only               Verify an existing administrator without creating
+`);
+}
+
+export function resolveBootstrapInput(env = process.env) {
+  const email = required(
+    "ADMIN_BOOTSTRAP_EMAIL",
+    env.ADMIN_BOOTSTRAP_EMAIL ?? env.AUTH_SETUP_ADMIN_EMAIL,
+  ).toLowerCase();
+  const password = required(
+    "ADMIN_BOOTSTRAP_PASSWORD",
+    env.ADMIN_BOOTSTRAP_PASSWORD ?? env.AUTH_SETUP_ADMIN_PASSWORD,
+  );
+  const name = required("ADMIN_BOOTSTRAP_NAME", env.ADMIN_BOOTSTRAP_NAME ?? "Administrator");
+  const adminEmails = new Set(
+    required("ADMIN_EMAILS", env.ADMIN_EMAILS)
+      .split(",")
+      .map((value) => value.trim().toLowerCase())
+      .filter(Boolean),
+  );
+
+  if (!adminEmails.has(email)) {
+    throw new Error("ADMIN_BOOTSTRAP_EMAIL must be listed in ADMIN_EMAILS.");
+  }
+  if (password.length < 8 || password.length > 128) {
+    throw new Error("ADMIN_BOOTSTRAP_PASSWORD must be between 8 and 128 characters.");
+  }
+
+  return { email, password, name };
+}
+
+function roles(value) {
+  return (value ?? "")
+    .split(",")
+    .map((role) => role.trim())
+    .filter(Boolean);
+}
+
+async function verifyExisting(dependencies, input, user) {
+  if (!roles(user.role).includes("admin")) {
+    throw new Error("The administrator email already exists without the admin role; no changes were made.");
+  }
+  if (user.signupApproved !== true) {
+    throw new Error("The administrator account is not approved; no changes were made.");
+  }
+  if (user.emailVerified !== true) {
+    throw new Error("The administrator email is not verified; no changes were made.");
+  }
+  if (!user.passwordHash || !(await dependencies.verifyPassword(user.passwordHash, input.password))) {
+    throw new Error("The administrator account already exists but the supplied password does not match; no changes were made.");
+  }
+}
+
+export async function bootstrapAdmin(dependencies, input, options = {}) {
+  const existing = await dependencies.findUser(input.email);
+
+  if (options.dryRun) {
+    return {
+      status: "planned",
+      action: existing ? "verify" : "create",
+      email: input.email,
+      name: input.name,
+      password: "<redacted>",
+    };
+  }
+
+  if (existing) {
+    await verifyExisting(dependencies, input, existing);
+    return { status: "existing", email: input.email };
+  }
+
+  if (options.checkOnly) {
+    throw new Error("The administrator account does not exist; no changes were made.");
+  }
+
+  await dependencies.createUser({
+    email: input.email,
+    password: input.password,
+    name: input.name,
+    role: "admin",
+    data: { emailVerified: true, signupApproved: true },
+  });
+
+  const created = await dependencies.findUser(input.email);
+  if (!created) throw new Error("The administrator account was not found after creation.");
+  await verifyExisting(dependencies, input, created);
+  return { status: "created", email: input.email };
+}
+
+async function main() {
+  if (has("--help") || has("-h")) {
+    usage();
+    return;
+  }
+
+  const input = resolveBootstrapInput();
+  // Load the auth graph before importing one of its dependencies directly.
+  // Concurrent ESM imports can ask Node to link the same Better Auth submodule
+  // through two graph roots and fail before the command reaches the database.
+  const { auth } = await import("../dist/auth/auth.js");
+  const { pool } = await import("../dist/auth/db.js");
+  const { verifyPassword } = await import("better-auth/crypto");
+
+  try {
+    const result = await bootstrapAdmin(
+      {
+        findUser: async (email) => {
+          const query = await pool.query(
+            `SELECT u.id,
+                    u.email,
+                    u.role,
+                    u."emailVerified" AS "emailVerified",
+                    u."signupApproved" AS "signupApproved",
+                    a.password AS "passwordHash"
+               FROM "user" AS u
+          LEFT JOIN "account" AS a
+                 ON a."userId" = u.id
+                AND a."providerId" = 'credential'
+              WHERE lower(u.email) = lower($1)
+              LIMIT 1`,
+            [email],
+          );
+          return query.rows[0] ?? null;
+        },
+        createUser: async (user) => auth.api.createUser({ body: user }),
+        verifyPassword: async (hash, password) => verifyPassword({ hash, password }),
+      },
+      input,
+      { dryRun: has("--dry-run"), checkOnly: has("--check-only") },
+    );
+
+    if (result.status === "planned") {
+      console.log("Validated administrator bootstrap plan.");
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.status === "created") {
+      console.log(`Created and verified administrator account ${result.email}.`);
+    } else {
+      console.log(`Verified existing administrator account ${result.email}.`);
+    }
+  } finally {
+    await pool.end();
+  }
+}
+
+const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (invokedPath === import.meta.url) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-settings/site-settings.controller.ts

@@ -31,6 +31,7 @@ const ICON_TYPES = new Set(["image/svg+xml", "image/png", "image/x-icon", "image
 // preset a slug, and overrides a JSON map of hex colors under known token keys.
 const HEX = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
 const PRESET = /^[a-z0-9-]{1,32}$/;
+const LOCALE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
 const THEME_TOKEN_KEYS = new Set([
   "background",
   "card",
@@ -46,6 +47,14 @@ const THEME_TOKEN_KEYS = new Set([
 /** Validate/normalize a single theme setting value. Empty string clears it. */
 function validateThemeValue(key: string, value: string): string {
   if (value === "") return "";
+  if (key === "locale") {
+    if (!LOCALE.test(value)) throw new BadRequestException("locale must be a valid BCP 47 language tag");
+    try {
+      return Intl.getCanonicalLocales(value)[0] ?? value;
+    } catch {
+      throw new BadRequestException("locale must be a valid BCP 47 language tag");
+    }
+  }
   if (key === "brandColor") {
     if (!HEX.test(value)) throw new BadRequestException("brandColor must be a hex color");
     return value;

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.ts

@@ -35,7 +35,11 @@ export const handle: Handle = async ({ event, resolve }) => {
     event.locals.session = null;
   }
   const response = await resolve(event, {
-    transformPageChunk: ({ html }) => html.replace('lang="en"', `lang="${event.locals.locale}"`),
+    transformPageChunk: ({ html }) =>
+      html.replace(
+        /(<html\b[^>]*?\slang=)(["'])[^"']*\2/i,
+        `$1"${event.locals.locale}"`,
+      ),
   });
   return applySearchIndexingHeaders(response, event.url.pathname);
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/auth-errors.ts

@@ -0,0 +1,3 @@
+/** Stable registration-policy errors used by Better Auth callbacks before the
+ *  shared API client is necessarily upgraded in an existing generated app. */
+export const PUBLIC_SIGNUP_DISABLED = "PUBLIC_SIGNUP_DISABLED" as const;

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/auth-redirect.ts

@@ -0,0 +1,27 @@
+const AUTH_PATHS = new Set(["/login", "/signup", "/forgot-password", "/reset-password"]);
+
+/** Accept only same-site absolute paths and keep authentication redirects from
+ *  becoming open redirects or loops back into an auth screen. */
+export function safeAuthRedirect(value: string | null | undefined, fallback = "/"): string {
+  if (!value || !value.startsWith("/") || value.startsWith("//") || value.includes("\\")) {
+    return fallback;
+  }
+  try {
+    const parsed = new URL(value, "http://podokit.local");
+    if (parsed.origin !== "http://podokit.local" || AUTH_PATHS.has(parsed.pathname)) return fallback;
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  } catch {
+    return fallback;
+  }
+}
+
+/** Current same-site path, suitable for a login return target. */
+export function currentPath(url: URL): string {
+  return safeAuthRedirect(`${url.pathname}${url.search}${url.hash}`);
+}
+
+/** Add a validated return target to an authentication-page link. */
+export function withAuthRedirect(authPath: "/login" | "/signup", target: string): string {
+  const params = new URLSearchParams({ redirect: safeAuthRedirect(target) });
+  return `${authPath}?${params.toString()}`;
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/account-menu.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
   import { goto } from "$app/navigation";
+  import { page } from "$app/state";
+  import { currentPath, withAuthRedirect } from "$lib/auth-redirect";
   import { Button } from "$lib/components/ui/button";
   import * as DropdownMenu from "$lib/components/ui/dropdown-menu";
   import LayoutDashboardIcon from "@lucide/svelte/icons/layout-dashboard";
@@ -12,16 +14,19 @@
 
   let { user }: { user: SessionUser | null } = $props();
   const i18n = getI18n();
+  const loginHref = $derived(withAuthRedirect("/login", currentPath(page.url)));
 
   async function signOut(): Promise<void> {
+    const returnTo = currentPath(page.url);
     await api.auth.signOut();
-    await goto("/login", { invalidateAll: true });
+    await goto(returnTo, { invalidateAll: true });
   }
 </script>
 
 {#if user}
   <DropdownMenu.Root>
     <DropdownMenu.Trigger
+      data-testid="account-menu"
       class="hover:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 inline-flex size-8 items-center justify-center rounded-full outline-none focus-visible:ring-3"
       aria-label={i18n.t.nav.account}
     >
@@ -38,9 +43,9 @@
         <DropdownMenu.Item onSelect={() => goto("/admin")}><LayoutDashboardIcon class="mr-2 size-4" /> {i18n.t.common.appName}</DropdownMenu.Item>
       {/if}
       <DropdownMenu.Separator />
-      <DropdownMenu.Item onSelect={signOut}><LogOutIcon class="mr-2 size-4" /> {i18n.t.nav.signOut}</DropdownMenu.Item>
+      <DropdownMenu.Item data-testid="sign-out" onSelect={signOut}><LogOutIcon class="mr-2 size-4" /> {i18n.t.nav.signOut}</DropdownMenu.Item>
     </DropdownMenu.Content>
   </DropdownMenu.Root>
 {:else}
-  <Button href="/login" variant="ghost">{i18n.t.auth.signIn}</Button>
+  <Button data-testid="sign-in-link" href={loginHref} variant="ghost">{i18n.t.auth.signIn}</Button>
 {/if}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/sidebar-user-menu.svelte

@@ -15,7 +15,7 @@
 
   async function signOut(): Promise<void> {
     await api.auth.signOut();
-    await goto("/login", { invalidateAll: true });
+    await goto("/", { invalidateAll: true });
   }
 </script>