cabloy 5.1.150 → 5.1.151

package/repo-docs/backend/resource-field-update.md

@@ -0,0 +1,156 @@
+# Existing Resource Field Update
+
+<Badge type="tip" text="Common" />
+
+Use this workflow when changing a field on an existing Vona resource. It covers a new persisted field, validation or metadata refinement, enum-like constraints, and the optional renderer follow-up that connects backend `ZovaRender.*(...)` metadata to Zova resources.
+
+This is a field-update workflow, not a substitute for initial module or CRUD scaffolding. For a new backend thread, start from [CRUD Workflow](/backend/crud-workflow). For an already stale generated consumer, start from the [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## When to use this workflow
+
+Use it when you need to:
+
+- add a stored field to an existing resource;
+- refine validation, titles, OpenAPI metadata, or `ZovaRender.field(...)` / `ZovaRender.cell(...)` metadata for an existing field;
+- add enum-like field constraints;
+- decide whether a persisted field change increments `vonaModule.fileVersion`;
+- add a custom form-field or table-cell renderer because shared renderer options are insufficient.
+
+Before changing anything, detect the active edition from the root marker. Explain the common backend workflow once, then resolve renderer keys, frontend flavors, build commands, and generated-output paths from the active edition.
+
+## Persisted field or metadata-only change
+
+Classify the work before editing migration code.
+
+### New persisted field
+
+Examples include a new `level: number`, `status: string`, or stored relation key. This changes storage shape and requires an explicit `fileVersion` decision.
+
+### Metadata-only or validation/rendering refinement
+
+Examples include:
+
+- enum validation for a field that already exists in storage;
+- a new field or table rendering hint;
+- locale-label changes;
+- stricter validation that does not change storage shape.
+
+This usually does not require a `fileVersion` increment. Confirm the current schema first instead of assuming the field already exists.
+
+## Decide whether to increment fileVersion
+
+For a new persisted field, decide with the user **before** editing `meta.version.ts`, a versioned schema path, or the module `package.json`.
+
+### Increment fileVersion
+
+When the change needs a new sequential migration:
+
+1. increment `vonaModule.fileVersion`;
+2. add a new `meta.version.ts` migration branch;
+3. preserve older branches as historical snapshots;
+4. introduce the field only in the new version branch.
+
+Do not add the same column to an older create path and again to a later migration branch. A fresh installation can apply the branches sequentially and fail on a duplicate column.
+
+### Keep the current fileVersion
+
+When the user decides not to create new migration history:
+
+1. keep the current `fileVersion`;
+2. fold the schema change into the current version path;
+3. do not create a new migration branch.
+
+For the complete migration lifecycle and test requirement, see [Migration and Changes](/backend/migration-and-changes#decide-whether-to-increment-fileversion).
+
+## Inspect the existing resource thread
+
+Read the current implementation before proposing changes:
+
+- entity and model;
+- DTOs, controller, and service;
+- `meta.version.ts` and module `package.json`;
+- locale files;
+- resource tests;
+- root `package.json`, `npm run vona`, and `npm run zova`.
+
+Use source patterns to determine whether DTOs are inferred. Do not hand-edit generated consumers or duplicate existing schema metadata.
+
+## Update entity truth first
+
+Treat the entity as the primary field-definition surface. Typical changes begin with `@Api.field(...)`, validation helpers, titles, and `ZovaRender.*(...)` metadata.
+
+For enum-like values, prefer a constrained schema that expresses the allowed values explicitly, for example `z.union([z.literal(1), z.literal(2), z.literal(3)])`.
+
+Structure-shaping schema helpers remain order-sensitive. When a field uses `v.object(...)`, `v.array(...)`, `v.optional()`, `v.nullable()`, `v.default(...)`, preprocess/transform wrappers, or an explicit zod schema, keep the final structure-defining schema-like argument last. Then verify emitted schema/OpenAPI output rather than assuming argument reordering is safe.
+
+For the underlying contract surface, see [Entity Guide](/backend/entity-guide#api-field-as-the-shared-contract-surface).
+
+## Preserve the inferred DTO flow
+
+When DTOs use `$Dto.create(...)`, `$Dto.update(...)`, `$Dto.get(...)`, or another inferred projection, let the entity change propagate. Add hand-authored field lists only when the current source demonstrates an intentional business projection or a separate contract-only field.
+
+For projected fields, use `$makeMetadata(...)` for metadata-only refinement and `$makeSchema(...)` for schema or validation refinement. Use a class-body `@Api.field(...)` member only for a genuinely new declared field.
+
+Read [DTO Infer and Generation](/backend/dto-infer-generation) when inference cannot express the intended contract. If serialization metadata controls the returned value, also confirm that the target controller action opts into `@Core.serializer()`.
+
+## Choose the renderer branch
+
+Prefer the smallest rendering change that expresses the requirement:
+
+1. reuse an existing shared renderer;
+2. configure it with field-level options;
+3. create a custom module-local renderer only when the shared surface cannot express the needed behavior.
+
+For a field-rendering select, provide a visible placeholder unless the UX genuinely requires a preselected value.
+
+### Shared renderer reuse
+
+Resolve renderer keys and component behavior in the active edition. Cabloy Basic and Cabloy Start can differ in select wrappers, placeholder behavior, UI library, flavors, and generated outputs. Do not copy a Basic renderer key or empty-item convention into Start without inspecting the Start baseline.
+
+### Custom renderer follow-up
+
+A custom backend-rendered field normally needs both sides of the frontend pair:
+
+- a module-local FormField component;
+- a registered module-local `@TableCell(...)` bean when backend `ZovaRender.cell(...)` references a table cell.
+
+A plain frontend component is not sufficient for backend table-cell metadata. Reuse the closest shared renderer’s option/data flow and keep the customization focused.
+
+For public implementation patterns, see [Form Guide](/frontend/form-guide), [TableCell Cookbook](/frontend/table-cell-cookbook#pattern-7-backend-contract-to-frontend-cell-handoff), and the Basic-only [Custom Form/Table Renderers tutorial](/fullstack/tutorial-4-custom-level-renderers).
+
+## Follow the contract loop
+
+A field change commonly has two possible handoffs:
+
+- a persisted entity/DTO/OpenAPI change begins with the **forward chain**: update backend truth, verify emitted contract output, regenerate frontend consumers, then make thin follow-up changes;
+- a new frontend-owned FormField or TableCell resource begins the **reverse chain**: update frontend source, regenerate metadata when needed, run the active edition’s complete frontend build, then run `npm run deps:vona`.
+
+Do not treat `build:rest:*` alone as sufficient for reverse-chain work. The SSR bundle and REST output must move together. If generated `.zova-rest` output already contains the expected keys but Vona still sees stale types after the normal build and dependency sync, treat the issue as local dependency drift and repair the local installation state before hand-patching generated links.
+
+Use the [Contract Loop Playbook](/fullstack/contract-loop-playbook) for edition-aware commands and recovery details.
+
+## Update locale and tests
+
+Update locale files when users can see field titles, enum labels, placeholders, or renderer helper text.
+
+Minimum backend coverage generally includes:
+
+- create with the field;
+- select/list behavior;
+- update persistence;
+- get-by-id or view response;
+- delete behavior when it is relevant.
+
+For constrained enum-like values, add a negative test that proves an invalid value is rejected. Test-local persisted resources must be deleted in `finally` using precise owned identities and reverse dependency order.
+
+## Verification checklist
+
+Choose checks that match the layers changed:
+
+- inspect generated schema/OpenAPI after structure-shaping field changes;
+- run the narrow resource test and relevant typecheck;
+- run `npm run test` for any `meta.version.ts` change so the test database is recreated and migration consistency is exercised;
+- run the relevant frontend metadata/build/dependency synchronization when custom renderer resources are involved;
+- verify action-level serializer behavior with an API test when `v.serializer*` metadata changes returned fields.
+
+Finish by confirming the backend contract, frontend resources, generated handoff, and user-visible locale labels all describe the same field behavior.

package/repo-docs/frontend/router-tabs-introduction.md

@@ -110,15 +110,13 @@ Recommended order:
 
 1. [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
 2. [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison)
-3. `repo-docs-internal/architecture/router-tabs-design-boundaries.md`
+3. inspect the current implementation and public comparison guidance for refactor boundaries
 
 ## Scope boundary
 
 The public router-tabs docs explain the shared frontend mechanism and how to use it.
 
-For internal design boundaries, maintenance invariants, and refactor safety rules, see:
-
-- `repo-docs-internal/architecture/router-tabs-design-boundaries.md`
+For maintainer-only design boundaries, maintenance invariants, and refactor safety rules, consult an established internal-documentation home when the active repository provides one. The public mechanism, layout, route-meta, and Admin/Web comparison guides remain the shared implementation baseline.
 
 ## See also
 

package/repo-docs/fullstack/a-pay-payment-suite.md

@@ -265,7 +265,7 @@ The Commerce payment route requires authentication and uses the session SSR prof
 
 The invariant is more important than a particular visual shell: server HTML and the hydration-time initial render must agree about private payment/order data. Do not render customer-owned payment state on the server when the request cannot authorize it, and do not let the provider return itself settle Commerce.
 
-For the deeper SSR return and Passport recovery rationale, maintainers can consult the internal architecture note. The public rule remains: settle on verified server facts; recover private browser state only after hydration and authorization.
+When the active repository provides the corresponding internal architecture note, maintainers can consult it for deeper SSR return and Passport recovery rationale. The public rule remains: settle on verified server facts; recover private browser state only after hydration and authorization.
 
 ## Reliability and security invariants
 

package/repo-docs/fullstack/contract-loop-playbook.md

@@ -113,6 +113,9 @@ Examples:
 - controller request or response changed
 - validation changed
 - OpenAPI metadata changed
+- an existing resource field changed
+
+For an existing resource-field change, first use [Existing Resource Field Update](/backend/resource-field-update) to make the persistence, DTO, locale, renderer, and migration decision explicit. Then continue with the applicable contract-loop branch.
 
 Then use the **forward chain**:
 
@@ -357,6 +360,7 @@ Use the tutorial series as examples of the two chains:
 
 - [Fullstack Introduction](/fullstack/introduction)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Existing Resource Field Update](/backend/resource-field-update)
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
 - [Vona + Zova Integration](/fullstack/vona-zova-integration)
 - [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)

package/repo-docs/fullstack/one-to-one-companion-resource-guide.md

@@ -295,7 +295,7 @@ The dependency should be directional:
 companion mutation → parent query cache invalidation
 ```
 
-Keep the cache graph acyclic and avoid duplicate or reverse edges. Cache invalidation is not a lock, a uniqueness constraint, or a transaction. Continue to use normal Model mutation APIs so the framework’s cache behavior remains active. Read [Cache Guide](/backend/cache-guide) for general cache rules.
+Keep the cache graph acyclic and avoid duplicate or reverse edges. Cache invalidation is not a lock, a uniqueness constraint, or a transaction. Continue to use normal Model mutation APIs so the framework’s cache behavior remains active. Read [Cross-model query-cache dependencies](/backend/cache-guide#cross-model-query-cache-dependencies) for the graph rules.
 
 ## DTO and contract design
 

package/repo-docs/reference/package-map.md

@@ -6,7 +6,7 @@ This monorepo is organized around a small set of stable top-level areas.
 
 - `package.json` — shared scripts and release entrypoints
 - `lerna.json` — package topology
-- `repo-docs-internal/` — internal engineering docs
+- an established internal-documentation home, when present — edition-local maintainer notes and ADRs
 - `.claude/` — Claude commands, skills, and local settings
 - `repo-docs/` — unified public docs
 

package/scripts/release.ts

@@ -88,10 +88,55 @@ function readJson(filePath: string): Record<string, any> {
   return JSON.parse(readFileSync(filePath, 'utf-8'));
 }
 
+type CabloyEdition = 'basic' | 'start';
+
+function resolveEdition(): CabloyEdition {
+  const hasBasic = existsSync(resolve(ROOT_DIR, '__CABLOY_BASIC__'));
+  const hasStart = existsSync(resolve(ROOT_DIR, '__CABLOY_START__'));
+  if (hasBasic === hasStart) {
+    throw new Error(
+      hasBasic
+        ? 'Ambiguous Cabloy edition: both __CABLOY_BASIC__ and __CABLOY_START__ markers are present'
+        : 'Not a Cabloy project: no __CABLOY_BASIC__ or __CABLOY_START__ marker found',
+    );
+  }
+  return hasBasic ? 'basic' : 'start';
+}
+
 function readPackageJson(): Record<string, any> {
   return readJson(PACKAGE_JSON_PATH);
 }
 
+function assertPublicBasicReleaseSurface(): void {
+  const edition = resolveEdition();
+  if (edition !== 'basic') {
+    throw new Error(
+      'The public Cabloy release workflow is available only in Cabloy Basic. Use an explicitly configured Cabloy Start release workflow instead.',
+    );
+  }
+
+  const pkg = readPackageJson();
+  const requiredScripts: Record<string, string> = {
+    'release-patch': 'node scripts/release.ts patch',
+    'release-minor': 'node scripts/release.ts minor',
+    'release-major': 'node scripts/release.ts major',
+    'release': 'node scripts/release.ts',
+    'release:dry-run': 'node scripts/release.ts --dry-run',
+    'release:changelog': 'node scripts/release.ts --changelog-only',
+    'release:publish': 'node scripts/release.ts --publish-only',
+    'release:github': 'node scripts/release.ts --release-only',
+  };
+  if (
+    pkg.name !== 'cabloy' ||
+    !isValidVersion(pkg.version) ||
+    Object.entries(requiredScripts).some(([name, command]) => pkg.scripts?.[name] !== command)
+  ) {
+    throw new Error(
+      'The active package.json does not expose the Cabloy Basic public release surface required by scripts/release.ts.',
+    );
+  }
+}
+
 function writePackageJson(pkg: Record<string, any>): void {
   writeFileSync(PACKAGE_JSON_PATH, `${JSON.stringify(pkg, null, 2)}\n`);
 }
@@ -274,7 +319,7 @@ function refreshZovaDependencyGraph(): void {
   execInherited('pnpm install', false, { cwd: ZOVA_DIR });
   execInherited('npm run zova :tools:deps', false, { cwd: ZOVA_DIR });
   execInherited('npm run build:zova:admin');
-  if (existsSync(resolve(ROOT_DIR, '__CABLOY_BASIC__'))) {
+  if (resolveEdition() === 'basic') {
     execInherited('npm run build:zova:web');
   }
 }
@@ -882,6 +927,8 @@ async function release(options: ReleaseOptions): Promise<void> {
   // eslint-disable-next-line
   console.log('🔧 Cabloy Release\n');
 
+  assertPublicBasicReleaseSurface();
+
   // Pre-flight checks
   try {
     execSync('git rev-parse --is-inside-work-tree', {

package/scripts/upgrade.ts

@@ -152,8 +152,21 @@ function copyDirectory(src: string, dest: string): void {
   cpSync(src, dest, { recursive: true, filter: shouldCopyPath });
 }
 
+function resolveEdition(): 'basic' | 'start' {
+  const hasBasic = existsSync(resolve(ROOT_DIR, '__CABLOY_BASIC__'));
+  const hasStart = existsSync(resolve(ROOT_DIR, '__CABLOY_START__'));
+  if (hasBasic === hasStart) {
+    throw new Error(
+      hasBasic
+        ? 'Ambiguous Cabloy edition: both __CABLOY_BASIC__ and __CABLOY_START__ markers are present'
+        : 'Not a Cabloy project: no __CABLOY_BASIC__ or __CABLOY_START__ marker found',
+    );
+  }
+  return hasBasic ? 'basic' : 'start';
+}
+
 function isCabloyBasic(): boolean {
-  return existsSync(resolve(ROOT_DIR, '__CABLOY_BASIC__'));
+  return resolveEdition() === 'basic';
 }
 
 function readPackageJson(filePath: string): PackageJson {
@@ -337,12 +350,10 @@ function reconcileFrameworkE2ePackageJson(dryRun?: boolean): void {
 // --- Step 1: Pre-flight ---
 
 function preflight(): void {
-  const markers = ['__CABLOY_BASIC__', '__CABLOY_START__'];
-  const found = markers.find(m => existsSync(resolve(ROOT_DIR, m)));
-  if (!found) {
-    console.error(
-      'Error: Not a cabloy project (no __CABLOY_BASIC__ or __CABLOY_START__ marker found)',
-    );
+  try {
+    resolveEdition();
+  } catch (error) {
+    console.error(`Error: ${(error as Error).message}`);
     process.exit(1);
   }
 }

package/zova/pnpm-lock.yaml

@@ -870,7 +870,7 @@ importers:
         specifier: ^5.1.88
         version: link:../zova-core
       zova-suite-a-zova:
-        specifier: ^5.1.153
+        specifier: ^5.1.154
         version: link:../../src/suite-vendor/a-zova
     devDependencies:
       clean-package:
@@ -977,7 +977,7 @@ importers:
         specifier: ^5.0.1
         version: link:modules/a-rbac
       zova-module-rest-resource:
-        specifier: ^5.1.46
+        specifier: ^5.1.47
         version: link:modules/rest-resource
 
   src/suite-vendor/a-cabloy/modules/a-rbac:
@@ -1076,7 +1076,7 @@ importers:
         specifier: ^5.1.25
         version: link:modules/a-fetch
       zova-module-a-form:
-        specifier: ^5.1.49
+        specifier: ^5.1.50
         version: link:modules/a-form
       zova-module-a-icon:
         specifier: ^5.1.27
@@ -1091,10 +1091,10 @@ importers:
         specifier: ^5.1.22
         version: link:modules/a-meta
       zova-module-a-model:
-        specifier: ^5.1.35
+        specifier: ^5.1.36
         version: link:modules/a-model
       zova-module-a-openapi:
-        specifier: ^5.1.50
+        specifier: ^5.1.51
         version: link:modules/a-openapi
       zova-module-a-router:
         specifier: ^5.1.34