cabloy 5.1.59 → 5.1.61

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

@@ -0,0 +1,75 @@
+# 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`.
+
+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.
+
+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.61",
   "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",
@@ -32,11 +33,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 +71,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/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);
   }
 }

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": [