cabloy 5.1.53 → 5.1.54

package/.github/workflows/docs-pages.yml

@@ -25,7 +25,7 @@ jobs:
       - uses: actions/checkout@v6
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - uses: actions/setup-node@v6
         with:
           node-version: 24

package/.github/workflows/vona-cov-pg.yml

@@ -29,7 +29,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - name: cov

package/.github/workflows/vona-test-crud.yml

@@ -22,7 +22,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - run: npm run vona :create:module demo-student -- --suite --ci

package/.github/workflows/vona-test-mysql.yml

@@ -29,7 +29,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - run: DATABASE_DEFAULT_CLIENT=mysql DATABASE_CLIENT_MYSQL_HOST=127.0.0.1 DATABASE_CLIENT_MYSQL_PASSWORD=root npm run test

package/.github/workflows/vona-test-pg.yml

@@ -29,7 +29,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - run: DATABASE_DEFAULT_CLIENT=pg npm run test

package/.github/workflows/vona-test-sqlite3.yml

@@ -22,7 +22,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run test

package/.github/workflows/vona-tsc.yml

@@ -17,7 +17,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - name: tsc

package/.github/workflows/zova-ui.yml

@@ -17,7 +17,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - uses: pnpm/action-setup@v5
         with:
-          version: 10.19.0
+          version: 11.5.2
       - name: init
         run: npm run init
       - name: suite

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 5.1.54
+
+### Features
+
+- Add a set of incremental feature updates across the codebase to expand supported functionality and behavior.
+
+### Bug Fixes
+
+- Support `src/module` test targets.
+- Support module-relative test targets.
+
+### Improvements
+
+- Clarify ORM omit semantics in tests and documentation.
+- Refine query and model-related internals, including updates to post handling, `where` building, and model cache behavior.
+
 ## 5.1.53
 
 ### Features

package/README.md

@@ -20,14 +20,14 @@ With Vona, Zova, suite-based modules, and CLI-first workflows, Cabloy turns comm
 
 Before creating a new Cabloy project, make sure your environment has:
 
-| Name       | Version     |
-| ---------- | ----------- |
-| pnpm       | `>=10.19.0` |
-| Node.js    | `>=24.4.0`  |
-| Redis      | `>=7.2.6`   |
-| SQLite3    | `Built-in`  |
-| MySQL      | `>=8`       |
-| PostgreSQL | `>=16`      |
+| Name       | Version    |
+| ---------- | ---------- |
+| pnpm       | `>=11.5.2` |
+| Node.js    | `>=24.4.0` |
+| Redis      | `>=7.2.6`  |
+| SQLite3    | `Built-in` |
+| MySQL      | `>=8`      |
+| PostgreSQL | `>=16`     |
 
 - `Redis`: powers queue, schedule, startup, broadcast, caching, two-layer cache, and redlock
 - `SQLite3`: if you use `better-sqlite3`, set up `node-gyp` before installing dependencies

package/cabloy-docs/backend/model-guide.md

@@ -105,6 +105,13 @@ return await this.scope.model.student.deleteById(id);
 
 These methods are also part of the generated CRUD thread; see [CRUD Workflow](/backend/crud-workflow).
 
+When using magic methods, keep one semantic detail in mind:
+
+- default `eq` methods can treat an omitted argument as `null`
+- non-`eq` methods require an explicit argument
+
+For omission inside structured `where` objects, prefer `Op.omit`; for SQL null checks, use `null`.
+
 ## Query-builder support
 
 Vona models are built on Knex, so the model layer also supports lower-level query builder access when needed.

package/cabloy-docs/backend/orm-mutation-guide.md

@@ -180,6 +180,16 @@ The important rule is:
 - the underlying write semantics still come from the standard ORM mutation surface
 - custom model methods take precedence when business-specific behavior is needed
 
+There is also a useful argument-handling rule to remember:
+
+- default `eq` magic methods such as `getByName()` or `selectByName()` treat an omitted argument as `null`
+- non-`eq` magic methods such as `getByNameEqI()` require an explicit value and throw if the argument is omitted
+
+This aligns magic-method behavior with the current ORM `where` semantics:
+
+- `Op.omit` means omit a condition explicitly
+- `null` means SQL `IS NULL`
+
 That means mutation should stay conceptually grounded in the standard model methods even when convenience wrappers are present.
 
 ## Implementation checks for ORM mutation changes

package/cabloy-docs/backend/orm-select-guide.md

@@ -110,7 +110,6 @@ The operator model is broad and includes examples like:
 - `_includes_`
 - case-insensitive variants
 - `_ref_`
-- `_skip_`
 
 That operator vocabulary is part of the Cabloy data language and should be reused consistently.
 
@@ -121,15 +120,17 @@ A practical operator-family reading is:
 - null checks: `_is_`, `_isNot_`
 - string matching: `_startsWith_`, `_endsWith_`, `_includes_`, and case-insensitive variants
 - composition/subquery: `_and_`, `_or_`, `_not_`, `_exists_`, `_notExists_`
-- identifier or composition helpers: `_ref_`, `_skip_`
+- identifier helper: `_ref_`
 
-### `_skip_`
+### Omitting a condition with `Op.omit`
 
-`_skip_` is especially useful when building query objects compositionally.
+Use `Op.omit` when you want to express omission explicitly at the call site. `Op.omit` is defined as `undefined`, but using the named constant makes the business meaning of the query object clearer.
 
 Representative pattern:
 
 ```typescript
+import { Op } from 'vona-module-a-orm';
+
 const where = {
   title: { _includes_: 'ai' },
   stars: { _gt_: 20 },
@@ -138,12 +139,12 @@ const where = {
 await this.scope.model.post.select({
   where: {
     ...where,
-    stars: '_skip_' as const,
+    stars: Op.omit,
   },
 });
 ```
 
-This lets a query builder remove one condition cleanly without rebuilding the whole `where` object by hand.
+This lets a query builder remove one condition cleanly without rebuilding the whole `where` object by hand, while `null` remains available for SQL `IS NULL` semantics.
 
 ## Joint operators and subqueries
 

package/cabloy-docs/backend/quickstart.md

@@ -16,14 +16,14 @@ Use this page when you are contributing backend work in the framework repository
 
 ## Prerequisites
 
-| Name       | Version   |
-| ---------- | --------- |
-| pnpm       | >=10.19.0 |
-| Node.js    | >=24.8.0  |
-| Redis      | >=7.2.6   |
-| Sqlite3    | Built-in  |
-| MySQL      | >=8       |
-| Postgresql | >=16      |
+| Name       | Version  |
+| ---------- | -------- |
+| pnpm       | >=11.5.2 |
+| Node.js    | >=24.8.0 |
+| Redis      | >=7.2.6  |
+| Sqlite3    | Built-in |
+| MySQL      | >=8      |
+| Postgresql | >=16     |
 
 Notes:
 

package/cabloy-docs/fullstack/quickstart.md

@@ -6,14 +6,14 @@ This guide explains the fastest way to start a Cabloy fullstack project.
 
 Before creating a new Cabloy project, make sure your environment has:
 
-| Name         | Version     |
-| ------------ | ----------- |
-| `pnpm`       | `>=10.19.0` |
-| `Node.js`    | `>=24.4.0`  |
-| `Redis`      | `>=7.2.6`   |
-| `SQLite3`    | `Built-in`  |
-| `MySQL`      | `>=8`       |
-| `PostgreSQL` | `>=16`      |
+| Name         | Version    |
+| ------------ | ---------- |
+| `pnpm`       | `>=11.5.2` |
+| `Node.js`    | `>=24.4.0` |
+| `Redis`      | `>=7.2.6`  |
+| `SQLite3`    | `Built-in` |
+| `MySQL`      | `>=8`      |
+| `PostgreSQL` | `>=16`     |
 
 - `Redis`: powers queue, schedule, startup, broadcast, caching, two-layer cache, and redlock
 - `SQLite3`: if you use `better-sqlite3`, set up `node-gyp` before installing dependencies

package/cabloy-docs/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: true

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.53",
+  "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();
   }
 }