cabloy 5.1.59 → 5.1.60

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

@@ -0,0 +1,179 @@
+# Fullstack Quick Start Tutorials
+
+<Badge type="info" text="Basic" />
+
+This six-part tutorial series gives you one connected, AI-guided path into Cabloy fullstack development.
+
+## Why this series exists
+
+Cabloy already has strong reference guides for CRUD, OpenAPI, DTO and entity contracts, schema-driven frontend rendering, and serialization. This series packages those capabilities into one simple workflow: each page gives you one focused prompt, AI completes the next increment, and you use the result to understand the framework model behind it.
+
+The core rhythm is:
+
+1. each page provides one focused prompt
+2. AI completes the tutorial-sized increment
+3. the generated or affected files become the next teaching surface
+4. the result is verified in the running app or generated contract output
+5. deeper reference docs remain available when more background is needed
+
+That makes the series practical as a guided, interactive workflow: each tutorial reduces the user action to one prompt, while the generated result becomes the teaching material for the next step.
+
+## The business scenario
+
+Throughout the series, you will build and refine a small **Student Training Center** example.
+
+The main business object is `student`, and the teaching fields are:
+
+- `name`
+- `description`
+- `level`
+- `mobile`
+
+Why these fields?
+
+- `level` is a good field for schema-driven form and table rendering
+- `mobile` is a good field for validation, OpenAPI output, and serialization or masking
+
+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.
+
+## What you should prepare first
+
+Before starting this tutorial series, make sure you already know:
+
+- how to bootstrap a Cabloy Basic project
+- how to run the repo from the root
+- how to discover command families through `npm run vona` and `npm run zova`
+
+Read these pages first:
+
+- [Fullstack Quickstart](/fullstack/quickstart)
+- [Fullstack CLI](/fullstack/cli)
+- [CLI Reference](/reference/cli-reference)
+
+Those pages explain the repo entrypoints and the CLI-first workflow model that the tutorial prompts will reuse throughout this series.
+
+## The learning path
+
+### Phase 1: Create the module and CRUD thread
+
+- [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
+
+- [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
+
+- [Tutorial 5: Backend Contract Sharing](/fullstack/tutorial-5-backend-contract-sharing)
+
+### Phase 4: Understand one contract surface through one field story
+
+- [Tutorial 6: One Contract Surface, Four Uses](/fullstack/tutorial-6-one-contract-four-uses)
+
+## The standard tutorial structure
+
+All six tutorials in this series follow the same learning structure:
+
+1. `Goal`
+2. `AI Prompt`
+3. `Why this step matters`
+4. `CLI commands to inspect/use`
+5. `Generated or affected files`
+6. `What those files mean in the business thread`
+7. `Verification`
+8. `Read more`
+9. `Next step`
+
+This makes the series easier to execute one page at a time: each page gives AI one clear increment, and the resulting output teaches why that step fits the Cabloy architecture.
+
+## How to use this series with AI
+
+Keep this series simple.
+
+In each tutorial, your main job is to copy the prompt from the page and give it to AI.
+
+That prompt already tells AI how to work in the Cabloy way, including things like:
+
+- inspect the CLI first
+- perform only the current tutorial increment
+- explain the commands it used
+- explain the business meaning of the generated or changed files
+- tell you what to verify next
+
+So for the user, the workflow is intentionally lightweight:
+
+1. open the current tutorial
+2. copy the prompt
+3. send it to AI
+4. review the result and continue to the next tutorial when ready
+
+## CLI-first rule
+
+This series assumes that AI should follow Cabloy’s CLI-first workflow before attempting manual scaffolding.
+
+In practice, the tutorial prompt should push AI to follow this rule:
+
+1. inspect the existing CLI family
+2. run the matching generator or tooling command
+3. inspect the generated result
+4. make only the minimal manual follow-up changes that the business case still needs
+
+Shared discovery commands from the repo root:
+
+```bash
+npm run vona :
+npm run vona :create
+npm run vona :tools
+
+npm run zova :
+npm run zova :create
+npm run zova :openapi
+```
+
+This is one of the most important Cabloy rules for AI-driven development in this series.
+
+## Suggested reading rhythm
+
+This series is designed to progress one prompt at a time.
+
+Each tutorial assumes that the previous result remains in place, so the workflow should stay incremental:
+
+1. complete the current tutorial prompt
+2. keep the generated result
+3. continue to the next tutorial on top of that result
+
+If a tutorial creates a new module, the local dev workflow may need `npm run dev` again so the new module is picked up before the next step.
+
+Do not jump directly to SDK generation or custom renderers before the module and CRUD thread are in place.
+
+## What you will understand by the end
+
+After the six tutorials, the completed workflow should make these Cabloy ideas clear:
+
+- when to use Vona and when to use Zova
+- why CRUD generation usually comes before hand-written backend boilerplate
+- how backend field metadata can reuse frontend render resources
+- how to evolve from built-in renderers to custom renderers
+- how backend OpenAPI contracts regenerate frontend SDKs and model helpers
+- how validation, rendering, OpenAPI, and serialization fit into one field-oriented contract model
+
+## Read together with
+
+The deeper reference guides behind this workflow include:
+
+- [CRUD Workflow](/backend/crud-workflow)
+- [Entity Guide](/backend/entity-guide)
+- [DTO Guide](/backend/dto-guide)
+- [Validation Guide](/backend/validation-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Serialization Guide](/backend/serialization-guide)
+
+This series is not meant to replace those guides. It is meant to help you move through them in one practical, task-driven order.

package/cabloy-docs/index.md

@@ -51,9 +51,10 @@ Start here to learn the shared Cabloy architecture, see how Vona and Zova fit to
 ### For getting started
 
 1. [Fullstack Quickstart](/fullstack/quickstart)
-2. [Editions Overview](/editions/overview)
-3. [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start)
-4. [Fullstack Introduction](/fullstack/introduction)
+2. [Fullstack Quick Start Tutorials](/fullstack/tutorials-overview)
+3. [Editions Overview](/editions/overview)
+4. [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start)
+5. [Fullstack Introduction](/fullstack/introduction)
 
 ### For contributors and AI vibe coding workflows
 

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

@@ -0,0 +1,73 @@
+# Bean Scene Boilerplate Variants
+
+This page is the fast lookup surface for backend Vona and frontend Zova bean scenes that expose more than one CLI scaffold template.
+
+Use it when you need to answer questions such as:
+
+- does this bean scene support `--boilerplate=...`
+- which variant names are currently defined
+- where is the source module metadata for that scene
+
+## Shared rule
+
+Vona and Zova follow the same practical lookup rule for bean-scene boilerplate variants:
+
+- `boilerplate` provides the default template
+- `--boilerplate=web` maps to `boilerplateWeb`
+- more generally, `--boilerplate=name` maps to `boilerplateName`
+
+That means the available variants are scene-defined metadata, not a universal list shared by every scene.
+
+A practical contributor rule is:
+
+1. use the default template unless you know the scene exposes a named variant
+2. check this page first for current built-in examples
+3. if needed, verify the owning module `package.json` metadata before assuming a variant exists
+
+## Backend Vona
+
+### 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`    |
+
+These backend entries come from the current `vonaModule.onions` metadata in `a-aspect` and `a-ssr`.
+
+## Frontend Zova
+
+### 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`   |
+
+These frontend entries come from the current `zovaModule.onions` metadata in `a-command` and `a-table`.
+
+## Guidance for AI-assisted development
+
+Do not assume every bean scene supports named variants.
+
+For reliable AI-assisted workflow selection:
+
+1. choose `npm run vona` for backend bean scenes and `npm run zova` for frontend bean scenes
+2. check whether the current scene is listed on this page
+3. if it is not listed, verify the owning module metadata before recommending `--boilerplate=...`
+4. treat this page as a current built-in lookup surface, not as a promise that all future scenes will follow the same naming set
+
+## Related guides
+
+Use this page together with:
+
+- [Backend CLI](/backend/cli)
+- [Frontend CLI](/frontend/cli)
+- [Backend Bean Scene Authoring](/backend/bean-scene-authoring)
+- [Frontend Bean Scene Authoring](/frontend/bean-scene-authoring)
+- [CLI Reference](/reference/cli-reference)

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

@@ -81,6 +81,8 @@ Representative command modules:
 - `vona/packages-cli/cli-set-api/src/lib/command/bin.play.ts`
 - `zova/packages-cli/cli-set-front/src/lib/command/tools.metadata.ts`
 
+When a `:create:bean` workflow depends on scene-specific boilerplate variants, also see [Bean Scene Boilerplate Variants](/reference/bean-scene-boilerplates).
+
 This is the preferred path for both humans and AI agents because it follows the real registration flow instead of relying on scattered examples.
 
 ## Related guides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.59",
+  "version": "5.1.60",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -32,11 +32,15 @@
     "build": "npm run build:zova && pnpm --dir vona run build",
     "build:docker": "npm run build:zova && pnpm --dir vona run build:docker",
     "build:zova": "pnpm --dir zova run build:ssr:cabloyBasicBatch",
+    "build:zova:admin": "pnpm --dir zova run build:ssr:cabloyBasicAdmin && pnpm --dir zova run build:rest:cabloyBasicAdmin",
+    "build:zova:web": "pnpm --dir zova run build:ssr:cabloyBasicWeb && pnpm --dir zova run build:rest:cabloyBasicWeb",
     "start": "cd vona && npm run start",
     "start:one": "cd vona && npm run start:one",
     "test": "cd vona && npm run test",
     "tsc": "npm run tsc:zova && pnpm --dir vona run tsc",
     "tsc:zova": "pnpm --dir zova run tsc",
+    "deps:vona": "pnpm --dir vona run vona :tools:deps",
+    "deps:zova": "pnpm --dir zova run zova :tools:deps",
     "format": "oxfmt --check",
     "format:fix": "oxfmt --write",
     "lint": "oxlint",
@@ -66,7 +70,7 @@
     "minimist": "^1.2.8",
     "oxfmt": "^0.45.0",
     "oxlint": "^1.65.0",
-    "tar": "^7.5.11",
+    "tar": "^7.5.16",
     "textlint": "^15.7.0",
     "textlint-rule-en-no-mixed-period": "^3.0.2",
     "textlint-rule-ja-no-mixed-period": "^3.0.2",

package/scripts/init.ts

@@ -247,7 +247,22 @@ function buildSsrCabloyBasicStartBatch(): void {
   }
 }
 
-// --- Step F: cleanupWorkspaceYaml ---
+// --- 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 ---
 
 function cleanupWorkspaceYaml(): void {
   const subProjects = ['vona', 'zova'];
@@ -268,7 +283,7 @@ function cleanupWorkspaceYaml(): void {
   }
 }
 
-// --- Step G: init:cabloy-docs ---
+// --- Step H: init:cabloy-docs ---
 
 function initCabloyDocs(): void {
   const pkgPath = resolve(CABLOY_DOCS_DIR, 'package.json');
@@ -291,5 +306,6 @@ initZova();
 initCabloyDocs();
 buildSsrCabloyBasicStartBatch();
 writeVersionMarker();
+initTestData();
 // eslint-disable-next-line
 console.log('[init] Done!');

package/vona/packages-cli/cabloy-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabloy/cli",
-  "version": "3.1.17",
+  "version": "3.1.18",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "@cabloy/cli",
   "keywords": [
@@ -55,7 +55,7 @@
     "is-type-of": "^2.2.0",
     "istextorbinary": "^3.3.0",
     "semver": "^7.7.4",
-    "tmp": "^0.2.5",
+    "tmp": "^0.2.7",
     "urllib": "^4.9.0"
   },
   "devDependencies": {

package/vona/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.111",
+  "version": "1.1.112",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.109",
+  "version": "1.1.110",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

package/vona/packages-cli/cli-set-api/src/lib/bean/cli.create.module.ts

@@ -81,5 +81,9 @@ export class CliCreateModule extends BeanCliBase {
     if (!argv.vscode && !argv.ci) {
       await this.helper.pnpmInstall();
     }
+    // tools.metadata
+    if (!argv.nometadata) {
+      await this.helper.invokeCli([':tools:metadata', moduleName], { cwd: argv.projectPath });
+    }
   }
 }

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.47",
+  "version": "5.1.48",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [