@podosoft/podokit 0.11.2 → 0.12.1

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

@@ -32,6 +32,18 @@ function targetManagedOverrides(projectRoot, templatesDir, modules, current = []
     }
     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).
@@ -49,6 +61,7 @@ function planUpdate(projectRoot, templatesDir) {
         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()) {
@@ -58,12 +71,15 @@ function planUpdate(projectRoot, templatesDir) {
         // 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"
-            : locked?.tier ??
-                (newText !== null
-                    ? (0, lockfile_1.classifyTier)(path, newText, manifest.ownedGlobs, managedOverrides)
-                    : "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;
@@ -108,6 +124,20 @@ function planUpdate(projectRoot, templatesDir) {
         changes,
     };
 }
+function assertPreviousExternalModulesInstalled(projectRoot, templatesDir, modules) {
+    const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
+    for (const module of modules) {
+        if (!module.packageName || !module.moduleVersion)
+            continue;
+        const resolved = (0, add_1.resolveModule)(module.packageName, modulesDir, projectRoot);
+        if (!resolved?.moduleVersion || resolved.moduleVersion === module.moduleVersion)
+            continue;
+        throw new Error(`Cannot use --from while external module "${module.packageName}" is installed at ` +
+            `${resolved.moduleVersion} but the project records ${module.moduleVersion}. Restore ` +
+            `${module.packageName}@${module.moduleVersion}, update PodoKit with --from, then upgrade ` +
+            "external modules separately.");
+    }
+}
 function writeFile(projectRoot, path, content) {
     const abs = (0, node_path_1.join)(projectRoot, path);
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(abs), { recursive: true });
@@ -171,7 +201,12 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         projectRoot,
     });
     const managedOverrides = targetManagedOverrides(projectRoot, templatesDir, modules, manifest.managedOverrides);
-    const oldTree = options.oldTemplatesDir
+    const ownedGlobs = targetOwnedGlobs(projectRoot, templatesDir, modules, manifest.ownedGlobs);
+    const needsMergeBase = plan.changes.some((change) => change.action === "conflict");
+    if (options.oldTemplatesDir && needsMergeBase) {
+        assertPreviousExternalModulesInstalled(projectRoot, templatesDir, modules);
+    }
+    const oldTree = options.oldTemplatesDir && needsMergeBase
         ? (0, assemble_1.assembleProject)({
             templatesDir: options.oldTemplatesDir,
             template: manifest.template,
@@ -210,7 +245,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, managedOverrides));
+    (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);
@@ -224,6 +259,7 @@ 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.2",
+  "version": "0.12.1",
   "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;