cabloy 5.1.60 → 5.1.62

package/cabloy-docs/fullstack/tutorial-4-custom-level-renderers.md

@@ -2,11 +2,21 @@
 
 <Badge type="info" text="Basic" />
 
-In this tutorial, one prompt lets AI upgrade the `level` field from built-in render resources to custom frontend renderers owned by the `demo-student` module.
+In this tutorial, one prompt lets the user express a simple product need: the `level` field in the Student experience should feel less generic and more like a real training-stage workflow.
+
+From that user need, AI can infer that the next step is no longer just relabeling the field. It now needs a more dedicated rendering experience owned by the `demo-student` module.
+
+This tutorial covers the **reverse chain** custom-resource handoff branch of the contract loop.
+
+> [!NOTE]
+> Like the earlier tutorials in this series, this page keeps using the standalone `demo-student` sandbox.
+> That keeps the custom-renderer experiment isolated from the repo's real suite-owned `a-training/training-student` implementation.
 
 ## Goal
 
-By the end of this tutorial, you will understand:
+By the end of this tutorial, you will understand how a user-facing request about a more business-specific `level` experience turns into a concrete custom-renderer implementation.
+
+In particular, you will understand:
 
 - when built-in render metadata is enough and when a custom renderer is worth adding
 - how a frontend table cell bean and a frontend form-field component can both serve the same backend field
@@ -17,17 +27,17 @@ By the end of this tutorial, you will understand:
 Give AI a prompt like this:
 
 ```text
-Please make the level UI more business-specific in the Student list page and form.
+For demo purposes, use custom renderer components to give the `level` field on the Student list page and form a more distinctive look and feel.
 ```
 
 ## Why this step matters
 
-This is the right follow-up step because built-in render resources are a good starting point, but some business fields eventually need module-specific behavior.
+This is the right follow-up step because built-in render resources are a good starting point, but some fields eventually need a more distinctive user experience to match the business workflow.
 
-The `level` field is a good teaching example because this step deepens the UI in two concrete ways:
+The `level` field is a good teaching example because users often expect two improvements once a training workflow becomes more realistic:
 
-- a custom table cell that renders a more business-specific badge style
-- a custom form field that adds helper text, readonly behavior, or module-specific select styling
+- the list should make each training stage easier to recognize at a glance
+- the form should guide the user more clearly when choosing a training stage
 
 This is where Cabloy’s contract model becomes more practical: the backend field still owns the business contract, while the frontend module progressively deepens the UI behavior behind that contract.
 
@@ -50,14 +60,15 @@ npm run zova :create:component formFieldLevel -- --module=demo-student
 
 Usage notes:
 
-- use `:create:bean` when you need a table-cell render resource under the bean scene
-- use `:create:component` when you need a custom frontend component/controller surface
+- use `:create:bean` when AI determines that the list needs a dedicated table-cell render resource under the bean scene
+- use `:create:component` when AI determines that the form needs a custom frontend component/controller surface
 - generation gives you the structural starting point, but this tutorial still expects manual refinement so the result matches the `demo-student` teaching implementation
 - after frontend resources exist, return to the backend entity and point `ZovaRender.field(...)` and `ZovaRender.cell(...)` at the custom module resources
+- once backend metadata starts consuming those new frontend resources, treat the next step as a reverse fullstack handoff rather than frontend-only cleanup: refresh generated output, rebuild the relevant flavor, and re-sync Vona dependencies
 
 ## Generated or affected files
 
-By the end of this tutorial, your module should provide these teaching anchors:
+To satisfy the user-facing need above, AI will usually converge on a small set of implementation anchors like these:
 
 - custom table cell bean:
   - `zova/src/module/demo-student/src/bean/tableCell.level.tsx`
@@ -68,50 +79,76 @@ By the end of this tutorial, your module should provide these teaching anchors:
 - backend field contract to update:
   - `vona/src/module/demo-student/src/entity/student.tsx`
 
-Representative custom metadata targets are:
+Representative metadata targets after AI makes that implementation decision are:
 
 ```typescript
 ZovaRender.field('demo-student:formFieldLevel', {
   items: levelItems,
   helper: $locale('LevelPlaceholder'),
-})
+});
 ```
 
 and:
 
 ```typescript
-ZovaRender.cell('demo-student:level', { items: levelItems })
+ZovaRender.cell('demo-student:level', { items: levelItems });
 ```
 
-## What those files mean in the business thread
+This is the point where a user request about “better list presentation” and “better form guidance” starts turning into explicit renderer resources and backend metadata links.
+
+## How those files support the user experience
 
-This tutorial makes the split of responsibilities explicit:
+These files work together to deliver the richer `level` experience:
 
-- `tableCell.level.tsx` owns the custom table-cell rendering behavior for `level`
-- `component/formFieldLevel/controller.tsx` owns the custom form-field behavior for `level`
+- `tableCell.level.tsx` makes the training stage easier to recognize in the list
+- `component/formFieldLevel/controller.tsx` makes the form interaction more guided and business-specific
 - `.metadata/component/formFieldLevel.ts` exposes that component through the module registration surface
 - `entity/student.tsx` remains the backend-owned business contract that chooses which frontend resources should render the field
 
-That means the backend still defines the business field, validation, and metadata entry point, while the frontend module owns the implementation details of the richer UI behavior.
+That means the backend still defines the business field, validation, and metadata entry point, while the frontend module owns the implementation details that make the experience feel more tailored to the Student Training Center workflow.
 
 ## Verification
 
-1. make sure the local dev workflow is running:
+These checks are the reverse-chain synchronization steps AI must complete so the user-facing renderer change is actually available to backend consumers and the running app.
+
+1. refresh the generated handoff surfaces before checking backend consumers:
+
+```bash
+npm run zova :tools:metadata demo-student
+npm run build:zova:admin
+npm run deps:vona
+```
+
+If the same renderer path must also be available for Web, also run:
+
+```bash
+npm run build:zova:web
+npm run deps:vona
+```
+
+If backend-side type consumers still cannot see the new shared renderer types even though generated `.zova-rest` output is already correct, rebuild `vona/node_modules` and reinstall dependencies:
+
+```bash
+cd vona && rm -rf node_modules && pnpm install
+```
+
+2. make sure the local dev workflow is running:
 
 ```bash
 npm run dev
 ```
 
-2. open `http://localhost:7102/admin/`
-3. enter the **Student** list page and verify that the `level` column now uses the custom table-cell presentation
-4. open a Student create, update, or view form and verify that the `level` field now uses the custom form-field behavior
-5. inspect `vona/src/module/demo-student/src/entity/student.tsx` and confirm that the backend metadata now points to `demo-student:formFieldLevel` and `demo-student:level`
+3. open `http://localhost:7102/admin/`
+4. enter the **Student** list page and verify that the `level` column now uses the custom table-cell presentation
+5. open a Student create, update, or view form and verify that the `level` field now uses the custom form-field behavior
+6. inspect `vona/src/module/demo-student/src/entity/student.tsx` and confirm that the backend metadata now points to `demo-student:formFieldLevel` and `demo-student:level`
 
 ## Read more
 
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
 - [Frontend CLI](/frontend/cli)
 - [Component Guide](/frontend/component-guide)
+- [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
 - [Bean Scene Boilerplate Variants](/reference/bean-scene-boilerplates)
 
 ## Next step

package/cabloy-docs/fullstack/tutorial-5-backend-contract-sharing.md

@@ -2,20 +2,25 @@
 
 <Badge type="info" text="Basic" />
 
-In this tutorial, one prompt lets AI show the forward direction of Cabloy’s fullstack contract loop: backend API contracts that generate and refresh the frontend consumption surface.
+In this tutorial, one prompt lets AI show the **forward chain** of Cabloy’s fullstack contract loop: backend API contracts that generate and refresh the frontend consumption surface.
 
 The teaching thread in this page is the pair of Student actions:
 
 - `summary/:id`
 - `deleteForce/:id`
 
+> [!NOTE]
+> This tutorial still runs inside the standalone `demo-student` sandbox from the earlier pages.
+> Use that sandbox for OpenAPI regeneration experiments so you do not interfere with the repo's real suite-owned `a-training/training-student` implementation.
+
 ## Goal
 
 By the end of this tutorial, you will understand:
 
 - how a backend controller and DTO change becomes frontend generated API output
 - how backend row-action metadata can drive frontend table actions
-- how generated API, frontend model helpers, and row-action beans fit into one contract-sharing workflow
+- how generated API, thin frontend model helpers, and row-action beans fit into one forward-chain workflow
+- why custom resource endpoints that still belong to the same resource should reuse the existing resource-owner instead of creating a competing cache owner
 
 ## AI Prompt
 
@@ -26,8 +31,6 @@ Please add two custom actions to the Student list:
 
 - Summary: return or display a student summary for the selected row
 - Force Delete: permanently delete the selected student through a dedicated row action
-
-Make both actions work end to end, from the backend contract to the Student list page.
 ```
 
 ## Why this step matters
@@ -60,6 +63,8 @@ Usage notes:
 - use the backend controller and DTOs as the starting point
 - inspect the module OpenAPI config before generation
 - prefer regeneration over hand-written duplicate API layers when the module already owns an OpenAPI contract surface
+- keep frontend follow-up thin: treat the module model as a semantic facade over generated API consumers rather than a second contract-definition layer
+- if the custom endpoint still belongs to the existing resource, reuse the existing resource-owner for server-state ownership
 
 ## Generated or affected files
 
@@ -105,10 +110,11 @@ This tutorial is easiest to understand as one contract chain:
 3. `dto/studentSelectResItem.tsx` defines the row-action metadata that exposes those actions in the Student list page
 4. `cli/openapi.config.ts` tells the frontend module which backend operations it owns
 5. `src/api/demoStudent.ts` is the generated typed API surface created from that backend contract
-6. `src/model/student.ts` wraps the generated API in frontend business-facing helper methods
-7. `tableCell.actionSummary.tsx` and `tableCell.actionDeleteForce.tsx` turn those model methods into visible row actions
+6. `src/model/student.ts` wraps the generated API in a thin frontend semantic facade
+7. the model should reuse the existing resource-owner for server-state ownership when the new API still belongs to the Student resource
+8. `tableCell.actionSummary.tsx` and `tableCell.actionDeleteForce.tsx` turn those model methods into visible row actions
 
-That is the practical contract-sharing loop: backend controller and DTO truth flows into generated frontend API output, then into frontend model helpers, and finally into visible table actions.
+That is the practical forward chain: backend controller and DTO truth flows into generated frontend API output, then into thin frontend model helpers, and finally into visible table actions.
 
 ## Verification
 
@@ -133,6 +139,7 @@ npm run dev
 
 ## Read more
 
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - [OpenAPI Guide](/backend/openapi-guide)
 - [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)

package/cabloy-docs/fullstack/tutorial-6-one-contract-four-uses.md

@@ -4,8 +4,14 @@
 
 In this tutorial, one prompt lets AI close the series by showing Cabloy’s core fullstack idea: one field-oriented contract surface can drive several behaviors across backend and frontend.
 
+This capstone sits on top of both the forward chain and the reverse chain rather than replacing either one.
+
 This time the main teaching field is `mobile`, while `level` stays as the supporting example for table and form rendering.
 
+> [!NOTE]
+> This capstone still uses the standalone `demo-student` sandbox carried through the tutorial series.
+> That keeps the final experiment path isolated while preserving a clean comparison against the repo's real suite-owned `a-training/training-student` implementation.
+
 ## Goal
 
 By the end of this tutorial, you will understand how one business field thread can participate in:

package/cabloy-docs/fullstack/tutorials-overview.md

@@ -36,7 +36,7 @@ Why these fields?
 
 This keeps the storyline small enough for beginners while still showing Cabloy’s fullstack contract model.
 
-At the beginning of the series, the `demo-student` module does not exist yet. The tutorials build it step by step.
+At the beginning of the series, the `demo-student` module does not exist yet. The tutorials build it step by step. This standalone tutorial track is intentional: it gives readers a safe experiment surface that does not collide with the repo's real `a-training/training-student` implementation and also makes side-by-side comparison easier.
 
 ## What you should prepare first
 
@@ -61,16 +61,29 @@ Those pages explain the repo entrypoints and the CLI-first workflow model that t
 - [Tutorial 1: Create Your First Module](/fullstack/tutorial-1-first-module)
 - [Tutorial 2: Create Your First CRUD](/fullstack/tutorial-2-first-crud)
 
-### Phase 2: Share frontend rendering metadata through the backend contract
+### Phase 2: Reverse chain — share frontend rendering metadata through the backend contract
 
 - [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing)
 - [Tutorial 4: Custom Form/Table Renderers for Level](/fullstack/tutorial-4-custom-level-renderers)
 
-### Phase 3: Share backend contracts forward into frontend consumption
+Important handoff note for this phase:
+
+- this phase teaches the **reverse chain** of the Cabloy contract loop
+- Tutorial 3 uses the built-in metadata branch
+- Tutorial 4 uses the custom resource handoff branch
+- once a frontend resource created in these tutorials is later consumed by backend metadata, do not stop at frontend source edits alone
+- refresh the generated frontend output, run the relevant flavor build, then run `npm run deps:vona`
+- if backend-side shared types still look stale after that normal sync flow, rebuild `vona/node_modules` and reinstall dependencies
+
+See [Contract Loop Playbook](/fullstack/contract-loop-playbook) and [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend) for the full reverse-chain explanation.
+
+### Phase 3: Forward chain — share backend contracts into frontend consumption
 
 - [Tutorial 5: Backend Contract Sharing](/fullstack/tutorial-5-backend-contract-sharing)
 
-### Phase 4: Understand one contract surface through one field story
+This phase teaches the **forward chain** of the contract loop: backend contract truth changes first, generated frontend consumers are refreshed second, and frontend follow-up stays thin and resource-owner-aware.
+
+### Phase 4: One field story across multiple contract surfaces
 
 - [Tutorial 6: One Contract Surface, Four Uses](/fullstack/tutorial-6-one-contract-four-uses)
 

package/cabloy-docs/reference/bean-scene-boilerplates.md

@@ -28,15 +28,15 @@ A practical contributor rule is:
 
 ### Current built-in scenes with variants
 
-| Scene          | Default metadata key | Named variant keys  | Example command                                                                               | Source module          |
-| -------------- | -------------------- | ------------------- | --------------------------------------------------------------------------------------------- | ---------------------- |
-| `filter`       | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean filter log -- --module=demo-student --boilerplate=global`          | `vona-module-a-aspect` |
-| `pipe`         | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean pipe log -- --module=demo-student --boilerplate=global`            | `vona-module-a-aspect` |
-| `interceptor`  | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean interceptor log -- --module=demo-student --boilerplate=global`     | `vona-module-a-aspect` |
-| `guard`        | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean guard auth -- --module=demo-student --boilerplate=global`          | `vona-module-a-aspect` |
-| `middleware`   | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean middleware trace -- --module=demo-student --boilerplate=global`    | `vona-module-a-aspect` |
-| `ssrMenu`      | `boilerplate`        | `boilerplateWeb`    | `npm run vona :create:bean ssrMenu menuTest -- --module=demo-student --boilerplate=web`       | `vona-module-a-ssr`    |
-| `ssrMenuGroup` | `boilerplate`        | `boilerplateWeb`    | `npm run vona :create:bean ssrMenuGroup groupTest -- --module=demo-student --boilerplate=web` | `vona-module-a-ssr`    |
+| Scene          | Default metadata key | Named variant keys  | Example command                                                                                   | Source module          |
+| -------------- | -------------------- | ------------------- | ------------------------------------------------------------------------------------------------- | ---------------------- |
+| `filter`       | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean filter log -- --module=training-student --boilerplate=global`          | `vona-module-a-aspect` |
+| `pipe`         | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean pipe log -- --module=training-student --boilerplate=global`            | `vona-module-a-aspect` |
+| `interceptor`  | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean interceptor log -- --module=training-student --boilerplate=global`     | `vona-module-a-aspect` |
+| `guard`        | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean guard auth -- --module=training-student --boilerplate=global`          | `vona-module-a-aspect` |
+| `middleware`   | `boilerplate`        | `boilerplateGlobal` | `npm run vona :create:bean middleware trace -- --module=training-student --boilerplate=global`    | `vona-module-a-aspect` |
+| `ssrMenu`      | `boilerplate`        | `boilerplateWeb`    | `npm run vona :create:bean ssrMenu menuTest -- --module=training-student --boilerplate=web`       | `vona-module-a-ssr`    |
+| `ssrMenuGroup` | `boilerplate`        | `boilerplateWeb`    | `npm run vona :create:bean ssrMenuGroup groupTest -- --module=training-student --boilerplate=web` | `vona-module-a-ssr`    |
 
 These backend entries come from the current `vonaModule.onions` metadata in `a-aspect` and `a-ssr`.
 
@@ -44,13 +44,15 @@ These backend entries come from the current `vonaModule.onions` metadata in `a-a
 
 ### Current built-in scenes with variants
 
-| Scene       | Default metadata key | Named variant keys                                | Example command pattern                                                                          | Source module           |
-| ----------- | -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------- |
-| `command`   | `boilerplate`        | `boilerplateCommandBulk`, `boilerplateCommandRow` | `npm run zova :create:bean command test -- --module=demo-student --boilerplate=commandRow`       | `zova-module-a-command` |
-| `tableCell` | `boilerplate`        | `boilerplateTableActionRow`                       | `npm run zova :create:bean tableCell test -- --module=demo-student --boilerplate=tableActionRow` | `zova-module-a-table`   |
+| Scene       | Default metadata key | Named variant keys                                | Example command pattern                                                                              | Source module           |
+| ----------- | -------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------- |
+| `command`   | `boilerplate`        | `boilerplateCommandBulk`, `boilerplateCommandRow` | `npm run zova :create:bean command test -- --module=training-student --boilerplate=commandRow`       | `zova-module-a-command` |
+| `tableCell` | `boilerplate`        | `boilerplateTableActionRow`                       | `npm run zova :create:bean tableCell test -- --module=training-student --boilerplate=tableActionRow` | `zova-module-a-table`   |
 
 These frontend entries come from the current `zovaModule.onions` metadata in `a-command` and `a-table`.
 
+For the built-in command scene’s runtime model and helper-base patterns, see [Command Scene Authoring](/frontend/command-scene-authoring).
+
 ## Guidance for AI-assisted development
 
 Do not assume every bean scene supports named variants.

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

@@ -32,10 +32,10 @@ Representative package metadata in the current repo shows the distinction clearl
 
 ### Module package
 
-Example: `vona/src/module/demo-student/package.json`
+Example: `vona/src/suite/a-training/modules/training-student/package.json`
 
-- package name: `vona-module-demo-student`
-- title: `demo-student`
+- package name: `vona-module-training-student`
+- title: `training-student`
 - `vonaModule.dependencies` records module-level framework dependencies
 
 ### Suite package
@@ -74,6 +74,7 @@ A practical comparison is:
 
 Use this package map together with:
 
+- [Suites and Modules](/fullstack/suites-and-modules)
 - [Backend Essentials](/backend/backend-essentials)
 - [Backend Foundation](/backend/foundation)
 - [Backend CLI](/backend/cli)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.60",
+  "version": "5.1.62",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -22,6 +22,7 @@
   "type": "module",
   "scripts": {
     "init": "node scripts/init.ts",
+    "init:test-data": "node scripts/initTestData.ts",
     "upgrade": "node scripts/upgrade.ts",
     "upgrade:dry-run": "node scripts/upgrade.ts --dry-run",
     "vona": "node ./vona/packages-cli/cli/src/bin/vona.ts --projectPath=vona",

package/scripts/init.ts

@@ -247,22 +247,7 @@ function buildSsrCabloyBasicStartBatch(): void {
   }
 }
 
-// --- Step F: initTestData ---
-
-function initTestData(): void {
-  // eslint-disable-next-line
-  console.log('[init] Initializing test data via npm run test...');
-  try {
-    exec('npm run test');
-  } catch {
-    // eslint-disable-next-line
-    console.warn(
-      '[init] npm run test failed after init completed; Redis may be unavailable, skipping test data initialization',
-    );
-  }
-}
-
-// --- Step G: cleanupWorkspaceYaml ---
+// --- Step F: cleanupWorkspaceYaml ---
 
 function cleanupWorkspaceYaml(): void {
   const subProjects = ['vona', 'zova'];
@@ -283,7 +268,7 @@ function cleanupWorkspaceYaml(): void {
   }
 }
 
-// --- Step H: init:cabloy-docs ---
+// --- Step G: init:cabloy-docs ---
 
 function initCabloyDocs(): void {
   const pkgPath = resolve(CABLOY_DOCS_DIR, 'package.json');
@@ -306,6 +291,5 @@ initZova();
 initCabloyDocs();
 buildSsrCabloyBasicStartBatch();
 writeVersionMarker();
-initTestData();
 // eslint-disable-next-line
 console.log('[init] Done!');

package/scripts/initTestData.ts

@@ -0,0 +1,25 @@
+import { execSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = resolve(__dirname, '..');
+
+function exec(cmd: string): void {
+  execSync(cmd, { stdio: 'inherit', cwd: ROOT_DIR });
+}
+
+function initTestData(): void {
+  // eslint-disable-next-line no-console
+  console.log('[init:test-data] Initializing test data via npm run test...');
+  try {
+    exec('npm run test');
+  } catch {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[init:test-data] npm run test failed after init completed; Redis may be unavailable, skipping test data initialization',
+    );
+  }
+}
+
+initTestData();

package/scripts/upgrade.ts

@@ -300,7 +300,17 @@ function runInit(dryRun: boolean, version: string): void {
   exec('npm run init', { CABLOY_VERSION: version } as any);
 }
 
-// --- Step 5: Cleanup ---
+// --- Step 5: Run init:test-data ---
+
+function runInitTestData(dryRun: boolean): void {
+  if (dryRun) {
+    log('  [dry-run] Run: npm run init:test-data');
+    return;
+  }
+  exec('npm run init:test-data');
+}
+
+// --- Step 6: Cleanup ---
 
 function cleanup(dryRun?: boolean): void {
   if (dryRun) {
@@ -366,6 +376,11 @@ async function main(): Promise<void> {
     runInit(dryRun, latestPackageInfo.version);
     log('');
 
+    // 5. Run init:test-data
+    log('Running npm run init:test-data...');
+    runInitTestData(dryRun);
+    log('');
+
     if (dryRun) {
       log(`[dry-run] Current Cabloy version would become: ${latestPackageInfo.version}`);
     } else {
@@ -374,7 +389,7 @@ async function main(): Promise<void> {
 
     log('Upgrade complete!');
   } finally {
-    // 5. Cleanup
+    // 6. Cleanup
     cleanup(dryRun);
   }
 }