@podosoft/podokit 0.11.1 → 0.12.0

package/dist/templates/todo/apps/web/src/lib/i18n/locales/en.json

@@ -0,0 +1,6 @@
+{
+  "code": "en",
+  "name": "English",
+  "direction": "ltr",
+  "enabled": true
+}

package/dist/templates/todo/apps/web/src/lib/i18n/locales/ko.json

@@ -0,0 +1,6 @@
+{
+  "code": "ko",
+  "name": "한국어",
+  "direction": "ltr",
+  "enabled": true
+}

package/dist/templates/todo/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/todo/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/todo/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/todo/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/todo/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/todo/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/todo/dot-gitignore

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

package/dist/templates/todo/dot-podokit/dev.json

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

package/dist/templates/todo/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/update.js

@@ -20,6 +20,30 @@ function diskContent(projectRoot, path) {
     const abs = (0, node_path_1.join)(projectRoot, path);
     return (0, node_fs_1.existsSync)(abs) ? (0, node_fs_1.readFileSync)(abs) : null;
 }
+function targetManagedOverrides(projectRoot, templatesDir, modules, current = []) {
+    const overrides = new Set(current);
+    const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
+    for (const module of modules) {
+        const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
+        if (!resolved)
+            continue;
+        for (const glob of (0, add_1.readModuleManifest)(resolved.dir).managedOverrides ?? [])
+            overrides.add(glob);
+    }
+    return [...overrides];
+}
+function targetOwnedGlobs(projectRoot, templatesDir, modules, current) {
+    const owned = new Set([...lockfile_1.DEFAULT_OWNED_GLOBS, ...current]);
+    const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
+    for (const module of modules) {
+        const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
+        if (!resolved)
+            continue;
+        for (const glob of (0, add_1.readModuleManifest)(resolved.dir).ownedGlobs ?? [])
+            owned.add(glob);
+    }
+    return [...owned];
+}
 /**
  * Build the update plan. `templatesDir` is the installed CLI's template set (the
  * new version); the lock records what PodoKit last wrote (to detect user edits).
@@ -36,15 +60,26 @@ function planUpdate(projectRoot, templatesDir) {
         modules: manifest.modules,
         projectRoot,
     });
+    const managedOverrides = targetManagedOverrides(projectRoot, templatesDir, manifest.modules, manifest.managedOverrides);
+    const ownedGlobs = targetOwnedGlobs(projectRoot, templatesDir, manifest.modules, manifest.ownedGlobs);
     const changes = [];
     const paths = new Set([...newTree.keys(), ...Object.keys(lock.files)]);
     for (const path of [...paths].sort()) {
         const locked = lock.files[path];
         const newText = treeText(newTree, path);
         const disk = diskContent(projectRoot, path);
-        // tier: prefer the lock; else classify the new file.
-        const tier = locked?.tier ??
-            (newText !== null ? (0, lockfile_1.classifyTier)(path, newText, manifest.ownedGlobs) : "managed");
+        // A newer module can explicitly take responsibility for a path that older
+        // projects classified under a broad owned glob (notably generated skills).
+        const managedByTarget = managedOverrides.some((glob) => (0, lockfile_1.matchGlob)(path, glob));
+        const ownedByTarget = ownedGlobs.some((glob) => (0, lockfile_1.matchGlob)(path, glob));
+        const tier = managedByTarget
+            ? "managed"
+            : ownedByTarget
+                ? "owned"
+                : locked?.tier ??
+                    (newText !== null
+                        ? (0, lockfile_1.classifyTier)(path, newText, ownedGlobs, managedOverrides)
+                        : "managed");
         if (tier === "owned") {
             changes.push({ path, tier, action: "skip", note: "owned — never modified" });
             continue;
@@ -101,13 +136,15 @@ function writeFile(projectRoot, path, content) {
  * Files that are neither in the assembled tree nor explicitly owned stay out of
  * the lock instead of being accidentally adopted as managed files.
  */
-function updatedFilesLock(projectRoot, newTree, previous, ownedGlobs) {
-    const next = (0, lockfile_1.computeFilesLock)(projectRoot, ownedGlobs);
+function updatedFilesLock(projectRoot, newTree, previous, ownedGlobs, managedOverrides) {
+    const next = (0, lockfile_1.computeFilesLock)(projectRoot, ownedGlobs, managedOverrides);
     for (const [path, entry] of Object.entries(next.files)) {
         const newText = treeText(newTree, path);
         if (newText !== null) {
             if (entry.tier !== "owned") {
-                entry.tier = previous.files[path]?.tier ?? entry.tier;
+                if (!managedOverrides.some((glob) => (0, lockfile_1.matchGlob)(path, glob))) {
+                    entry.tier = previous.files[path]?.tier ?? entry.tier;
+                }
                 entry.outHash = (0, podokit_template_engine_1.hashContent)(newText);
             }
             continue;
@@ -149,6 +186,8 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         modules,
         projectRoot,
     });
+    const managedOverrides = targetManagedOverrides(projectRoot, templatesDir, modules, manifest.managedOverrides);
+    const ownedGlobs = targetOwnedGlobs(projectRoot, templatesDir, modules, manifest.ownedGlobs);
     const oldTree = options.oldTemplatesDir
         ? (0, assemble_1.assembleProject)({
             templatesDir: options.oldTemplatesDir,
@@ -188,7 +227,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     // Keep the assembled target as the managed baseline. A merged working file
     // intentionally remains drifted so a future update performs another 3-way
     // merge instead of treating the user's lines as clean generated output.
-    (0, lockfile_1.writeFilesLock)(projectRoot, updatedFilesLock(projectRoot, newTree, previousLock, manifest.ownedGlobs));
+    (0, lockfile_1.writeFilesLock)(projectRoot, updatedFilesLock(projectRoot, newTree, previousLock, ownedGlobs, managedOverrides));
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
     const refreshedModules = manifest.modules.map((module) => {
         const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
@@ -202,6 +241,8 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     });
     (0, lockfile_1.writeManifest)(projectRoot, {
         ...manifest,
+        ownedGlobs,
+        managedOverrides,
         modules: refreshedModules,
         podokitVersion: (0, lockfile_1.podokitVersion)(),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/i18n/en.ts

@@ -1,10 +0,0 @@
-import type { BaseTranslation } from "typesafe-i18n";
-
-// Base locale. Run `npx typesafe-i18n` to generate the typed runtime,
-// then access strings as `$LL.appTitle()` in components.
-const en = {
-  appTitle: "{{projectName}}",
-  checkHealth: "Check API health",
-} satisfies BaseTranslation;
-
-export default en;

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/i18n/ko.ts

@@ -1,11 +0,0 @@
-import type { BaseTranslation } from "typesafe-i18n";
-
-// Uses BaseTranslation until you generate typed runtimes with `npx typesafe-i18n`.
-// After generating, switch to `import type { Translation } from "../i18n-types"`
-// so this locale is checked against the base locale's keys.
-const ko = {
-  appTitle: "{{projectName}}",
-  checkHealth: "API 상태 확인",
-} satisfies BaseTranslation;
-
-export default ko;

package/dist/templates/todo/apps/web/src/lib/i18n/en.ts

@@ -1,10 +0,0 @@
-import type { BaseTranslation } from "typesafe-i18n";
-
-// Base locale. Run `npx typesafe-i18n` to generate the typed runtime,
-// then access strings as `$LL.appTitle()` in components.
-const en = {
-  appTitle: "{{projectName}}",
-  checkHealth: "Check API health",
-} satisfies BaseTranslation;
-
-export default en;

package/dist/templates/todo/apps/web/src/lib/i18n/ko.ts

@@ -1,11 +0,0 @@
-import type { BaseTranslation } from "typesafe-i18n";
-
-// Uses BaseTranslation until you generate typed runtimes with `npx typesafe-i18n`.
-// After generating, switch to `import type { Translation } from "../i18n-types"`
-// so this locale is checked against the base locale's keys.
-const ko = {
-  appTitle: "{{projectName}}",
-  checkHealth: "API 상태 확인",
-} satisfies BaseTranslation;
-
-export default ko;