cabloy 5.1.52 → 5.1.54

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

@@ -1,10 +1,16 @@
 # CLI Reference
 
-This page is the compact reference layer for the two main command entrypoints.
+This page is the fast orientation map for the two main Cabloy CLI entrypoints. Use it first when you need to answer three questions quickly:
 
-## Vona
+1. Should this workflow use Vona or Zova?
+2. Which command families already exist?
+3. Where is the authoritative command definition for a specific command?
 
-Entry from repo root:
+## Quick routing
+
+### Use Vona for backend workflows
+
+Run from the repo root:
 
 ```bash
 npm run vona :
@@ -12,38 +18,77 @@ npm run vona :create
 npm run vona :tools
 ```
 
-Primary command families:
-
-- `bin:*`
-- `create:*`
-- `init:*`
-- `tools:*`
+Choose Vona for backend-oriented work such as suites, modules, beans, metadata, runtime assets, tests, and backend build or dev tasks.
 
-## Zova
+### Use Zova for frontend workflows
 
-Entry from repo root:
+Run from the repo root:
 
 ```bash
 npm run zova :
 npm run zova :create
 npm run zova :refactor
+npm run zova :openapi
 ```
 
-Primary command families:
+Choose Zova for frontend-oriented work such as pages, components, frontend beans, refactors, generated frontend metadata, and OpenAPI-to-SDK generation.
+
+## Source of truth
+
+The shared root scripts live in `package.json`:
+
+- `npm run vona`
+- `npm run zova`
+
+Those scripts enter thin CLI launchers and then hand off to the real command catalogs:
+
+- Vona entrypoint: `vona/packages-cli/cli/src/bin/vona.ts`
+- Zova entrypoint: `zova/packages-cli/cli/src/bin/zova.ts`
+- Vona command registry: `vona/packages-cli/cli-set-api/src/lib/commands.ts`
+- Zova command registry: `zova/packages-cli/cli-set-front/src/lib/commands.ts`
+
+When you need the authoritative command-family map, inspect the two `commands.ts` files first.
+
+## Command families
 
-- `bin:*`
-- `create:*`
-- `init:*`
-- `refactor:*`
-- `tools:*`
-- `openapi:*`
+### Vona families
 
-## Workflow guidance for docs, skills, and rules
+- `bin:*` — backend runtime and build tasks
+- `create:*` — create suites, modules, beans, and tests
+- `init:*` — initialize backend source artifacts
+- `tools:*` — metadata, dependency, and CRUD-related tools
 
-When creating docs, skills, or rules, use the CLI family names as the public mental model first. Only drop to file-level implementation details when the command surface is insufficient.
+### Zova families
+
+- `bin:*` — frontend build tasks
+- `create:*` — create suites, modules, pages, components, mocks, and beans
+- `init:*` — initialize frontend source artifacts
+- `refactor:*` — frontend refactor workflows
+- `tools:*` — metadata and dependency tools
+- `openapi:*` — OpenAPI config and SDK generation workflows
+
+## Fast path to a specific command
+
+For a specific command, use this navigation path:
+
+1. choose `npm run vona` or `npm run zova`
+2. inspect the relevant `commands.ts` registry
+3. open the matching command module in `src/lib/command/`
+4. read `info.title`, `info.usage`, and `options`
+
+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`
+
+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
 
 Use this page together with:
 
 - [Backend Quickstart](/backend/quickstart)
 - [Frontend (Zova)](/frontend/introduction)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+If the public CLI surface is enough, prefer it over file-level implementation details. Drop to the source files only when you need the authoritative registry or per-command metadata.

package/cabloy-docs/reference/frontend-directory-structure.md

@@ -0,0 +1,125 @@
+# Frontend Directory Structure
+
+This page gives a compact reference view of the frontend tree under `zova/`.
+
+## Why this page exists
+
+The package map explains the architectural meaning of package, module, and suite boundaries.
+
+This page complements that by showing the practical frontend tree layout used in the Cabloy repository.
+
+## Simplified frontend tree
+
+Representative frontend structure:
+
+```text
+zova/
+├── packages-cli/
+├── packages-utils/
+├── packages-zova/
+├── env/
+├── public/
+├── src-ssr/
+└── src/
+   ├── boot/
+   ├── css/
+   ├── front/
+   │  ├── config/
+   │  └── typing/
+   ├── module/
+   ├── module-vendor/
+   ├── suite/
+   └── suite-vendor/
+```
+
+## Meaning of the main directories
+
+| Path                      | Meaning                                        |
+| ------------------------- | ---------------------------------------------- |
+| `zova/packages-cli/`      | Zova CLI entrypoints and command sets          |
+| `zova/packages-utils/`    | shared frontend-side utilities                 |
+| `zova/packages-zova/`     | framework packages                             |
+| `zova/env/`               | frontend env files and runtime/build inputs    |
+| `zova/public/`            | public static assets                           |
+| `zova/src-ssr/`           | SSR entrypoints and SSR-related project source |
+| `zova/src/boot/`          | app bootstrapping and startup registration     |
+| `zova/src/css/`           | project-level CSS and theme entry assets       |
+| `zova/src/front/config/`  | project-level frontend config overrides        |
+| `zova/src/front/typing/`  | project-level frontend type definitions        |
+| `zova/src/module/`        | first-party standalone frontend modules        |
+| `zova/src/module-vendor/` | vendor-provided standalone frontend modules    |
+| `zova/src/suite/`         | first-party frontend suites and their modules  |
+| `zova/src/suite-vendor/`  | vendor-provided frontend suites and modules    |
+
+## Project-level frontend areas
+
+Within the frontend application layer, contributors should also know these practical areas:
+
+| Path                     | Meaning                                            |
+| ------------------------ | -------------------------------------------------- |
+| `zova/env/`              | frontend env files and runtime/build inputs        |
+| `zova/public/`           | project-level public static assets                 |
+| `zova/src-ssr/`          | project-level SSR entry and SSR middleware wiring  |
+| `zova/src/boot/`         | project-level boot registration and startup hooks  |
+| `zova/src/css/`          | project-level CSS, theme, and style entry assets   |
+| `zova/src/front/config/` | project-level frontend config and override surface |
+| `zova/src/front/typing/` | project-level frontend typing definitions          |
+
+## Edition note
+
+The high-level Zova tree above is intentionally stable across Cabloy Basic and Cabloy Start.
+
+A practical rule is:
+
+- use the shared tree as the structural reference
+- treat suite names and UI-layer examples as edition-sensitive details
+- in Cabloy Basic, public examples may include suites such as `cabloy-basic` and `a-devui`
+- in Cabloy Start, examples may include suites such as `cabloy-start` and `a-vuetify`
+
+Cabloy Start is a sibling repository, not a subdirectory of this monorepo.
+
+## Practical development reading of the tree
+
+A useful rule is:
+
+- start in `zova/src/module/` when the work belongs to a standalone frontend module
+- start in `zova/src/suite/` when the work belongs to a suite-composed business area
+- inspect `zova/packages-cli/` when the task is about command discovery, generation behavior, or refactor behavior
+- inspect `zova/src/front/config/` when the task is about project-level frontend config overrides rather than module-local defaults
+- inspect `zova/src/boot/` or `zova/src-ssr/` when the task is about startup flow or SSR behavior
+- inspect `zova/src/css/` and `zova/public/` when the task is about project-level styling or static assets
+
+A practical generator-oriented reading is:
+
+- `create:*` commands choose the structural target before placing frontend resources
+- `init:*` commands create project-level or module-level support assets
+- `refactor:*` commands reshape existing frontend patterns without requiring manual rework from scratch
+- `openapi:*` commands affect generated SDK-related frontend surfaces
+
+## Relationship to other reference pages
+
+Read this page together with:
+
+- [Package Map](/reference/package-map)
+- [Frontend (Zova)](/frontend/introduction)
+- [Modules and Suites](/frontend/modules-and-suites)
+- [Environment and Config Guide](/frontend/environment-config-guide)
+- [App Startup Guide](/frontend/app-startup-guide)
+- [System Startup Guide](/frontend/system-startup-guide)
+- [Frontend CLI](/frontend/cli)
+
+A practical split is:
+
+- [Frontend (Zova)](/frontend/introduction) is the broader frontend hub
+- [Package Map](/reference/package-map) explains architecture boundaries and package metadata
+- this page explains the practical directory tree contributors navigate
+
+## Implementation checks for frontend file-location changes
+
+When changing frontend code, ask:
+
+1. does this change belong to a standalone module, a suite-contained module, or a project-level frontend area?
+2. is the task about generation behavior under `packages-cli/`, startup behavior under `src/boot` or `src-ssr`, or feature code under `src/`?
+3. should the example use a shared structural path, a Cabloy Basic example, or a public Cabloy Start example note?
+
+That helps keep frontend file references aligned with the actual monorepo layout.

package/cabloy-docs/reference/introduction.md

@@ -0,0 +1,47 @@
+# Reference
+
+This page is the reference hub for shared monorepo commands, package lookup, directory lookup, and shared terminology.
+
+## What Reference is responsible for
+
+- shared monorepo command entrypoints
+- CLI lookup and command-surface discovery
+- package lookup across the repository
+- backend and frontend directory lookup
+- shared terminology and glossary support
+
+## How to approach reference work
+
+For contributor and automation workflows in this repository, prefer this order:
+
+1. inspect the root `package.json` when you need the shared workflow entrypoints
+2. inspect the CLI reference before inferring command families from memory
+3. use package and directory lookup pages when the task is about locating code, modules, or shared terms
+4. pair Reference pages with Backend, Frontend, or Fullstack guides when lookup alone is not enough
+
+## Reference reading paths
+
+Use Reference as the lookup area for shared commands, package discovery, directory lookup, and shared terminology.
+
+### Workflow entry path
+
+Start here when you first need the shared monorepo command surface:
+
+- [Repo Scripts](/reference/repo-scripts)
+- [CLI Reference](/reference/cli-reference)
+- [Fullstack CLI](/fullstack/cli)
+
+### Structure and lookup path
+
+Use this path when you need to find where packages, backend directories, frontend directories, or shared terms live:
+
+- [Package Map](/reference/package-map)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+- [Frontend Directory Structure](/reference/frontend-directory-structure)
+- [Glossary](/reference/glossary)
+
+## Edition impact
+
+Cabloy Start keeps the same high-level workflow pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own SSR site baselines and project assets in the licensed private repository.
+
+When documenting or automating flavor-specific commands, always confirm the active repo first.

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

@@ -96,6 +96,8 @@ For the broader backend entry path, also see [Backend (Vona)](/backend/introduct
 
 For the frontend architectural meaning of modules, suites, scope-driven resources, and runtime/startup structure, see `/frontend/modules-and-suites`, `/frontend/module-scope`, `/frontend/ioc-and-beans`, `/frontend/environment-config-guide`, `/frontend/app-startup-guide`, and `/frontend/system-startup-guide`.
 
+For the practical frontend directory tree contributors navigate, also see [Frontend Directory Structure](/reference/frontend-directory-structure).
+
 ## Sibling edition
 
 - `cabloy-start` is a separate sibling repository, not a subdirectory of this monorepo.

package/cabloy-docs/reference/repo-scripts.md

@@ -1,5 +1,9 @@
 # Repo Scripts
 
+Use this page when you need the compact lookup surface for the shared root scripts exposed by the Cabloy Basic monorepo.
+
+For the broader Reference landing page, see [Reference Introduction](/reference/introduction).
+
 The root `package.json` is the first reference point for shared monorepo workflows.
 
 ## Current shared entrypoints in Cabloy Basic
@@ -21,9 +25,7 @@ The root `package.json` is the first reference point for shared monorepo workflo
 
 ## Edition-sensitive note
 
-Cabloy Start keeps the same high-level pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own Start-specific suites, SSR site baselines, and project assets in the licensed private repository.
-
-### Documentation and automation guidance
+Cabloy Start keeps the same high-level pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own SSR site baselines and project assets in the licensed private repository.
 
 When documenting or automating flavor-specific commands, always confirm the active repo first.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.52",
+  "version": "5.1.54",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -21,7 +21,7 @@
   },
   "type": "module",
   "scripts": {
-    "init": "pnpm install --no-frozen-lockfile && node scripts/init.ts",
+    "init": "node scripts/init.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",
@@ -77,5 +77,5 @@
   "engines": {
     "node": ">=24.4.0"
   },
-  "packageManager": "pnpm@10.19.0"
+  "packageManager": "pnpm@11.5.2"
 }

package/scripts/init.ts

@@ -18,6 +18,7 @@ const ROOT_DIR = resolve(__dirname, '..');
 const VONA_DIR = resolve(ROOT_DIR, 'vona');
 const ZOVA_DIR = resolve(ROOT_DIR, 'zova');
 const CABLOY_DOCS_DIR = resolve(ROOT_DIR, 'cabloy-docs');
+const PNPM_VERSION = '11.5.2';
 
 // --- Helpers ---
 
@@ -39,6 +40,21 @@ function exec(cmd: string, cwd = ROOT_DIR): void {
   execSync(cmd, { stdio: 'inherit', cwd });
 }
 
+function execQuiet(cmd: string, cwd = ROOT_DIR): string {
+  return execSync(cmd, { stdio: 'pipe', cwd }).toString();
+}
+
+function checkPnpm(): void {
+  const version = execQuiet('pnpm --version').trimEnd();
+  const [major, minor, patch] = version.split('.').map(item => Number.parseInt(item, 10) || 0);
+  const lowerMajor = major < 11;
+  const lowerMinor = major === 11 && minor < 5;
+  const lowerPatch = major === 11 && minor === 5 && patch < 2;
+  if (lowerMajor || lowerMinor || lowerPatch) {
+    throw new Error(`pnpm should >= ${PNPM_VERSION}, current: ${version}`);
+  }
+}
+
 function deleteGitkeepFiles(dir: string): void {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const fullPath = resolve(dir, entry.name);
@@ -215,6 +231,8 @@ function initCabloyDocs(): void {
 
 // --- Main ---
 
+checkPnpm();
+exec('pnpm install --no-frozen-lockfile');
 setAppName();
 generateEnvProdLocal();
 generateEnvProdDockerLocal();

package/vona/README.md

@@ -52,11 +52,11 @@ The Web and Admin of Cabloy Store are built by one codebase
 
 ### General
 
-| Name       | Version   |
-| ---------- | --------- |
-| pnpm       | >=10.19.0 |
-| Nodejs     | >=24.8.0  |
-| Typescript | >=5.9.3   |
+| Name       | Version  |
+| ---------- | -------- |
+| pnpm       | >=11.5.2 |
+| Nodejs     | >=24.8.0 |
+| Typescript | >=5.9.3  |
 
 ### Backend(Vona)
 

package/vona/README.zh-CN.md

@@ -52,11 +52,11 @@ Vona 采用前后端分离的架构。前端使用 Zova 框架，将构建生成
 
 ### 通用
 
-| 名称       | 版本      |
-| ---------- | --------- |
-| pnpm       | >=10.19.0 |
-| Nodejs     | >=24.8.0  |
-| Typescript | >=5.9.3   |
+| 名称       | 版本     |
+| ---------- | -------- |
+| pnpm       | >=11.5.2 |
+| Nodejs     | >=24.8.0 |
+| Typescript | >=5.9.3  |
 
 ### 后端(Vona)
 

package/vona/package.original.json

@@ -2,7 +2,7 @@
   "name": "vona",
   "private": true,
   "type": "module",
-  "packageManager": "pnpm@10.19.0",
+  "packageManager": "pnpm@11.5.2",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "repository": {
     "type": "git",
@@ -50,10 +50,5 @@
     "textlint-rule-period-in-list-item": "^1.0.1",
     "oxfmt": "^0.45.0",
     "oxlint": "^1.65.0"
-  },
-  "pnpm": {
-    "overrides": {
-      "zod": "npm:@cabloy/zod@4.3.6"
-    }
   }
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@cabloy/cli",
-  "version": "3.1.14",
+  "version": "3.1.17",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "@cabloy/cli",
   "keywords": [
@@ -29,7 +29,7 @@
   },
   "scripts": {
     "clean": "rimraf dist tsconfig.tsbuildinfo",
-    "tsc:publish": "npm run clean && vona :bin:buildGeneral && tsc",
+    "tsc:publish": "npm run clean && node ../cli/src/bin/vona.ts :bin:buildGeneral && tsc",
     "prepublishOnly": "npm run tsc:publish",
     "prepack": "clean-package",
     "postpack": "clean-package restore"

package/vona/packages-cli/cli/README.md

@@ -1 +1,57 @@
 # vona-cli
+
+This package is the thin Vona CLI entrypoint.
+
+## Purpose
+
+From the monorepo root, `npm run vona` resolves to this package and launches the backend-oriented CLI flow.
+
+Primary entrypoint:
+
+- `src/bin/vona.ts`
+
+This entrypoint stays intentionally small. It handles top-level argument parsing, the special `play` dispatch path, and handoff to the Vona command runtime.
+
+## Source of truth
+
+Do not treat this package as the full command catalog. The authoritative Vona command-family registry lives in:
+
+- `../../packages-cli/cli-set-api/src/lib/commands.ts`
+
+Inspect that file first when you need to know:
+
+- which command families exist
+- which command names are registered
+- which command module implements each entry
+
+Current top-level families include:
+
+- `bin`
+- `create`
+- `init`
+- `tools`
+
+## Where command details live
+
+Each command module in `../../packages-cli/cli-set-api/src/lib/command/` provides the main CLI-facing metadata, including:
+
+- `info.title`
+- `info.usage`
+- `options`
+
+Representative example:
+
+- `../../packages-cli/cli-set-api/src/lib/command/bin.play.ts`
+
+## Recommended navigation path
+
+1. start from `npm run vona`
+2. inspect `src/bin/vona.ts` only for top-level dispatch behavior
+3. inspect `cli-set-api/src/lib/commands.ts` for the authoritative catalog
+4. inspect the specific command module for usage and options
+
+## Canonical public reference
+
+For the compact top-level overview shared across Vona and Zova, start with:
+
+- `../../../cabloy-docs/reference/cli-reference.md`

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

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

package/vona/packages-cli/cli/src/bin/vona.ts

@@ -1,36 +1,13 @@
 #!/usr/bin/env node
 
 import { parseProjectPath } from '@cabloy/cli';
-import { ProcessHelper } from '@cabloy/process-helper';
 import mri from 'mri';
-import semver from 'semver';
 
 import { playAttach } from '../play.ts';
 import { VonaCommand } from '../start.ts';
 
-const pnpm_version = '10.19.0';
-
-const processHelper = new ProcessHelper(process.cwd());
-
 main();
 
-async function checkPnpm() {
-  const res = await processHelper.spawnCmd({
-    cmd: 'pnpm',
-    args: ['--version'],
-    options: {
-      stdio: 'pipe',
-      shell: true,
-      dummy: true,
-    },
-  });
-  const version = res.trimEnd();
-  const lt = semver.lt(version, pnpm_version);
-  if (lt) {
-    throw new Error(`pnpm should >= ${pnpm_version}, current: ${version}`);
-  }
-}
-
 async function main() {
   const rawArgv = process.argv.slice(2);
   const _args = mri(rawArgv, {
@@ -58,9 +35,6 @@ async function main() {
   if (isPlayAttach) {
     await playAttach(projectPath, args);
   } else {
-    if (!isPlay) {
-      await checkPnpm();
-    }
     new VonaCommand(args).start();
   }
 }

package/vona/packages-cli/cli-set-api/README.md

@@ -1 +1,49 @@
 # vona-cli-set-api
+
+This package contains the authoritative Vona command catalog for backend-oriented CLI workflows.
+
+## Source of truth
+
+The top-level command-family registry lives in:
+
+- `src/lib/commands.ts`
+
+Inspect this file first when you need to answer:
+
+- which Vona command families exist
+- which command names are registered
+- which command module implements each entry
+
+Current families include:
+
+- `default`
+- `bin`
+- `create`
+- `init`
+- `tools`
+
+## Command metadata surface
+
+Each command module under `src/lib/command/` provides the main CLI-facing metadata for that command, typically including:
+
+- `bean`
+- `info.title`
+- `info.usage`
+- `options`
+
+Representative example:
+
+- `src/lib/command/bin.play.ts`
+
+## Recommended navigation path
+
+1. run `npm run vona`
+2. inspect `../cli/src/bin/vona.ts` for entry dispatch only
+3. inspect `src/lib/commands.ts` for the authoritative family map
+4. inspect the specific command module for usage and options
+
+## Public reference
+
+For the compact top-level overview shared across Vona and Zova, see:
+
+- `../../../cabloy-docs/reference/cli-reference.md`

package/vona/packages-cli/cli-set-api/cli/templates/create/module/boilerplate/_package.json

@@ -22,7 +22,7 @@
   "files": ["assets", "dist", "src"],
   "scripts": {
     "clean": "rimraf dist tsconfig.build.tsbuildinfo",
-    "tsc:publish": "npm run clean && vona :bin:buildModule --sourcemap && tsc -p tsconfig.build.json",
+    "tsc:publish": "npm run clean && node <%=argv.suite?'../../../../../':'../../../'%>packages-cli/cli/src/bin/vona.ts :bin:buildModule --sourcemap && tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run tsc:publish",
     "prepack": "clean-package",
     "postpack": "clean-package restore && npm run clean"

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.103",
+  "version": "1.1.106",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [
@@ -33,7 +33,7 @@
   },
   "scripts": {
     "clean": "rimraf dist dist-cli dist-toolsIsolate tsconfig.build.tsbuildinfo tsconfig.cli.tsbuildinfo tsconfig.isolate.tsbuildinfo",
-    "tsc:publish": "npm run clean && vona :bin:buildGeneral && tsc -p tsconfig.build.json && tsc -p tsconfig.cli.json && tsc -p tsconfig.isolate.json",
+    "tsc:publish": "npm run clean && node ../cli/src/bin/vona.ts :bin:buildGeneral && tsc -p tsconfig.build.json && tsc -p tsconfig.cli.json && tsc -p tsconfig.isolate.json",
     "prepublishOnly": "npm run tsc:publish",
     "prepack": "clean-package",
     "postpack": "clean-package restore && npm run clean"