cabloy 5.1.156 → 5.1.158

package/.cabloy-version

@@ -1 +1 @@
-5.1.156
+5.1.158

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 5.1.158
+
+### Improvements
+
+- Add licensing documentation.
+- Add contribution guidelines.
+
+## 5.1.157
+
+### Features
+
+- Add `coerceColumn` support.
+
 ## 5.1.156
 
 ### Features

package/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to Cabloy Basic
+
+Contributions to Cabloy Basic source, tests, tooling, and documentation are welcome. Cabloy Basic is the public Cabloy framework/reference edition, with Vona backend and Zova frontend layers.
+
+## Before you begin
+
+- Use [GitHub Issues](https://github.com/cabloy/cabloy/issues) for reproducible bugs, public questions, and feature proposals. Search for an existing issue first.
+- Use [pull requests](https://github.com/cabloy/cabloy/pulls) for focused, reviewable changes.
+- For a bug report, include the expected and actual behavior, a minimal reproduction or sufficient setup details, and relevant Cabloy, Node.js, pnpm, database, and browser/runtime versions.
+- Remove credentials, tokens, personal data, and sensitive system information from issues, logs, screenshots, and pull requests.
+
+## Set up a development checkout
+
+You need Git, Node.js `>=24.4.0`, pnpm `>=11.5.2`, Redis `>=7.2.6`, and one documented development database baseline: SQLite, MySQL `>=8`, or PostgreSQL `>=16`. SQLite setups using `better-sqlite3` may also require a native build toolchain for `node-gyp`.
+
+```bash
+git clone https://github.com/cabloy/cabloy.git
+cd cabloy
+npm run init
+```
+
+`npm run init` is more than a package install: it installs multiple workspaces, prepares generated local configuration, initializes and synchronizes Vona and Zova, and generates required frontend and backend artifacts. Run it intentionally rather than as a retry for an unrelated narrow change.
+
+Current CI workflows run on Ubuntu with Node.js 24 after pushes to `main`; do not assume that every pull request is automatically validated. For maintained onboarding guidance, see [Cabloy Basic](https://cabloy.com/editions/cabloy-basic).
+
+## Develop and validate
+
+Start with the narrowest meaningful check, then broaden validation when a change crosses a shared boundary.
+
+| Purpose                                  | Command                    |
+| ---------------------------------------- | -------------------------- |
+| Start Vona development                   | `npm run dev`              |
+| Start one Vona development process       | `npm run dev:one`          |
+| Start Basic Admin SSR development        | `npm run dev:zova:admin`   |
+| Start Basic Web SSR development          | `npm run dev:zova:web`     |
+| Check formatting                         | `npm run format`           |
+| Lint                                     | `npm run lint`             |
+| Type-check Vona and Zova                 | `npm run tsc`              |
+| Run backend tests                        | `npm run test`             |
+| Run the full E2E suite                   | `npm run test:e2e`         |
+| Rerun E2E tests without reset            | `npm run test:e2e:fast`    |
+| Build required Basic artifacts           | `npm run build`            |
+| Build Basic Admin SSR and REST artifacts | `npm run build:zova:admin` |
+| Build Basic Web SSR and REST artifacts   | `npm run build:zova:web`   |
+| Synchronize Zova dependencies into Vona  | `npm run deps:vona`        |
+| Build the public documentation site      | `npm run docs:build`       |
+
+The tracked pre-commit hook runs `lint-staged`. It may format staged Markdown and configuration files, and may lint-fix and format staged source files. Review the resulting staged changes and run the relevant explicit checks before submitting.
+
+## Generated code and Vona–Zova integration
+
+Use Vona backend contracts, DTOs, OpenAPI metadata, and schema metadata as contract truth. Regenerate consumers rather than hand-editing generated frontend artifacts.
+
+For frontend metadata or dependency changes that Vona consumes, build every affected Basic flavor before synchronizing dependencies:
+
+```bash
+npm run build:zova:admin
+# Also run npm run build:zova:web when Web is affected.
+npm run deps:vona
+```
+
+Keep SSR and REST outputs aligned; a REST-only build is not sufficient. See the canonical [Contract Loop Playbook](https://cabloy.com/fullstack/contract-loop-playbook), [Vona + Zova Integration](https://cabloy.com/fullstack/vona-zova-integration), and [repository scripts reference](https://cabloy.com/reference/repo-scripts).
+
+## Pull requests
+
+Keep each pull request focused and describe its user-visible and technical effects. Include:
+
+- the related issue when one exists;
+- tests added or updated for behavioral changes;
+- the exact validation commands run and their results;
+- any regenerated contract artifacts and the build/synchronization steps used; and
+- documentation updates, or why no documentation update is needed.
+
+Do not include unrelated generated output, build artifacts, environment files, credentials, or cache files.
+
+## Documentation
+
+Canonical public Cabloy documentation is maintained in this repository's `repo-docs/` tree and published at [cabloy.com](https://cabloy.com). Discuss and submit proposed public-documentation changes in an issue or pull request; do not treat copies outside this repository as independent canonical sources.
+
+## License and contribution rights
+
+Cabloy Basic project-owned content is licensed under the root [MIT License](./LICENSE).
+
+Submit only material that you have the right to contribute. Preserve required copyright, license, attribution, and third-party notices for any included code, media, fonts, generated material, or copied snippets.

package/LICENSES.md

@@ -0,0 +1,5 @@
+# License Scope
+
+Unless a file or directory includes its own complete license or third-party notice, Cabloy Basic project-owned source, documentation, and assets inherit the root [MIT License](./LICENSE).
+
+Third-party material remains subject to the license and notice provided with that material or otherwise required by its upstream terms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.156",
+  "version": "5.1.158",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.142",
+  "version": "1.1.143",
   "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.140",
+  "version": "1.1.141",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

package/vona/packages-utils/cascade-extend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cascade-extend",
-  "version": "2.2.8",
+  "version": "2.2.9",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "cascade-extend",
   "keywords": [

package/vona/packages-utils/dotenv/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabloy/dotenv",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "cabloy dotenv",
   "keywords": [

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

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

package/vona/src/suite/a-home/modules/home-user/test/role.test.ts

@@ -45,11 +45,13 @@ describe('role.test.ts', { concurrency: false }, () => {
   it('bean:role emits only actual membership changes', async () => {
     let userId: string | undefined;
     let roleId: string | undefined;
-    const events: unknown[] = [];
+    const events: Array<{ userIds: unknown[]; roleIds: unknown[] }> = [];
     const event = app.scope('a-user').event.roleMembershipChanged;
     const originalEmit = event.emit.bind(event);
     const emitMock = mock.method(event, 'emit', async data => {
-      events.push(data);
+      if (data.userIds.some(item => String(item) === userId)) {
+        events.push(data);
+      }
       return await originalEmit(data);
     });
     try {
@@ -143,11 +145,13 @@ describe('role.test.ts', { concurrency: false }, () => {
   it('bean:role replaces a membership set with one change event', async () => {
     let userId: string | undefined;
     const roleIds: string[] = [];
-    const events: unknown[] = [];
+    const events: Array<{ userIds: unknown[]; roleIds: unknown[] }> = [];
     const event = app.scope('a-user').event.roleMembershipChanged;
     const originalEmit = event.emit.bind(event);
     const emitMock = mock.method(event, 'emit', async data => {
-      events.push(data);
+      if (data.userIds.some(item => String(item) === userId)) {
+        events.push(data);
+      }
       return await originalEmit(data);
     });
     try {
@@ -175,7 +179,9 @@ describe('role.test.ts', { concurrency: false }, () => {
 
         const result = await app.bean.role.replaceUserRoleIds(user.id, [roles[1].id, roles[2].id]);
         assert.deepEqual(result, { addedRoleIds: [roles[2].id], removedRoleIds: [roles[0].id] });
-        assert.deepEqual(events, [{ userIds: [user.id], roleIds: [roles[0].id, roles[2].id] }]);
+        assert.equal(events.length, 1);
+        assert.deepEqual(events[0]?.userIds, [user.id]);
+        assert.deepEqual(events[0]?.roleIds.toSorted(), [roles[0].id, roles[2].id].toSorted());
 
         const memberships = await homeUser.model.roleUser.select({ where: { userId: user.id } });
         assert.deepEqual(

package/vona/src/suite-vendor/a-cabloy/modules/a-rbac/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-rbac",
-  "version": "5.0.3",
+  "version": "5.0.4",
   "description": "",
   "keywords": [
     "Vona Module"

package/vona/src/suite-vendor/a-cabloy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-suite-a-cabloy",
-  "version": "5.1.49",
+  "version": "5.1.50",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "",
   "author": "",
@@ -9,7 +9,7 @@
   "dependencies": {
     "vona-module-a-cabloy": "workspace:^",
     "vona-module-a-markdown": "^5.0.3",
-    "vona-module-a-rbac": "^5.0.3",
+    "vona-module-a-rbac": "^5.0.4",
     "vona-module-a-socket": "workspace:^",
     "vona-module-a-ssr": "workspace:^",
     "vona-module-a-ssrhmr": "workspace:^"

package/vona/src/suite-vendor/a-vona/modules/a-orm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-orm",
-  "version": "5.1.30",
+  "version": "5.1.31",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "db",
   "keywords": [

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/service/databaseDialectBase_.ts

@@ -15,17 +15,17 @@ import type {
 } from '../types/dialect.ts';
 
 const BOOLEAN_COLUMN_TYPES = ['bit', 'bool', 'boolean'];
-const NUMBER_COLUMN_TYPES = ['int'];
-const TIMESTAMP_COLUMN_TYPE_PREFIXES = ['timestamp'];
-const FLOAT_COLUMN_TYPE_PREFIXES = ['float', 'double'];
-const INTEGER_COLUMN_TYPE_PREFIXES = [
-  'tinyint',
-  'smallint',
-  'mediumint',
-  'bigint',
-  'numeric',
-  'integer',
-];
+const INTEGER_COLUMN_TYPES = ['tinyint', 'smallint', 'mediumint', 'int', 'integer'];
+const FLOAT_COLUMN_TYPES = ['float', 'double'];
+const GENERATED_DEFAULT_PATTERN =
+  /^(?:current_timestamp\b(?:\s*\(\s*\d*\s*\))?|current_date\b|current_time\b(?:\s*\(\s*\d*\s*\))?|now\s*\(\s*\)|nextval\s*\()/i;
+const NUMBER_LITERAL_PATTERN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
+const QUOTED_LITERAL_PATTERN = /^'((?:''|[^'])*)'$/;
+
+type ColumnDefaultLiteral =
+  | { kind: 'string'; value: string }
+  | { kind: 'boolean'; value: boolean }
+  | { kind: 'number'; value: string };
 
 @Service()
 @Virtual()
@@ -96,13 +96,13 @@ export class ServiceDatabaseDialectBase extends BeanBase {
 
   coerceColumn(column: Knex.ColumnInfo): ITableColumn {
     const result = { type: column.type } as ITableColumn;
-    result.default = this._coerceColumnValue(column.type, column.defaultValue);
     const columnType = (column as Knex.ColumnInfo & { columnType?: string }).columnType;
     if (columnType) result.columnType = columnType;
+    result.default = this._coerceColumnValue(result, column.defaultValue);
     return result;
   }
 
-  protected _isMysqlBooleanColumn(column: ITableColumn) {
+  protected _isMysqlBooleanColumn(column: Pick<ITableColumn, 'columnType'>) {
     return column.columnType?.trim().toLowerCase() === 'tinyint(1)';
   }
 
@@ -191,34 +191,105 @@ export class ServiceDatabaseDialectBase extends BeanBase {
     return [items.map(item => item.id), builder];
   }
 
-  protected _coerceColumnValue(type: string, value) {
+  protected _coerceColumnValue(column: Pick<ITableColumn, 'type' | 'columnType'>, value: unknown) {
     if (isNil(value)) return undefined;
-    if (BOOLEAN_COLUMN_TYPES.includes(type)) return safeBoolean(value);
-    if (NUMBER_COLUMN_TYPES.includes(type)) return this._safeNumber(value);
-    if (
-      this._columnTypePrefixes(type, TIMESTAMP_COLUMN_TYPE_PREFIXES) &&
-      value === 'CURRENT_TIMESTAMP'
-    ) {
-      return undefined; // new Date();
+    if (typeof value !== 'string') {
+      return this._isBooleanColumn(column) ? safeBoolean(value as any) : value;
     }
-    if (this._columnTypePrefixes(type, FLOAT_COLUMN_TYPE_PREFIXES)) {
-      return this._safeNumber(value);
+
+    const literal = this._coerceColumnLiteral(value);
+    if (literal === undefined) return undefined;
+    if (this._isBooleanColumn(column)) return safeBoolean(literal.value);
+    if (literal.kind === 'boolean') return literal.value;
+
+    const type = this._columnTypeName(column.type);
+    if (literal.kind === 'string') return literal.value;
+    if (INTEGER_COLUMN_TYPES.includes(type)) return this._safeInteger(literal.value);
+    if (FLOAT_COLUMN_TYPES.includes(type)) return this._safeNumber(literal.value);
+    return literal.value;
+  }
+
+  protected _isBooleanColumn(column: Pick<ITableColumn, 'type' | 'columnType'>) {
+    return (
+      this._isMysqlBooleanColumn(column) ||
+      BOOLEAN_COLUMN_TYPES.includes(this._columnTypeName(column.type))
+    );
+  }
+
+  protected _columnTypeName(type: string) {
+    return type.trim().toLowerCase().match(/^\w+/)?.[0] ?? '';
+  }
+
+  protected _coerceColumnLiteral(value: string): ColumnDefaultLiteral | undefined {
+    const literal = this._unwrapColumnDefault(value);
+    if (literal === '') return undefined;
+    const literalLower = literal.toLowerCase();
+    if (literalLower === 'null' || GENERATED_DEFAULT_PATTERN.test(literal)) return undefined;
+    const quoted = literal.match(QUOTED_LITERAL_PATTERN);
+    if (quoted) return { kind: 'string', value: quoted[1].replaceAll("''", "'") };
+    if (literalLower === 'true' || literalLower === 't') return { kind: 'boolean', value: true };
+    if (literalLower === 'false' || literalLower === 'f') return { kind: 'boolean', value: false };
+    if (NUMBER_LITERAL_PATTERN.test(literal)) return { kind: 'number', value: literal };
+    if (this._isExpressionColumnDefault(literal)) return undefined;
+    return { kind: 'string', value: literal };
+  }
+
+  protected _unwrapColumnDefault(value: string) {
+    let literal = value.trim();
+    while (literal.startsWith('(') && literal.endsWith(')')) {
+      const inner = literal.slice(1, -1).trim();
+      if (!inner || !this._isColumnDefaultBalanced(inner)) break;
+      literal = inner;
     }
-    if (this._columnTypePrefixes(type, INTEGER_COLUMN_TYPE_PREFIXES)) {
-      return this._safeNumber(value);
+    const castIndex = literal.indexOf('::');
+    if (castIndex > 0 && this._isScalarColumnDefault(literal.slice(0, castIndex).trim())) {
+      literal = literal.slice(0, castIndex).trim();
     }
-    // pg: NULL::character varying
-    if (value.indexOf('NULL::') === 0) return undefined;
-    return value;
+    return literal;
   }
 
-  // pg: nextval
-  protected _safeNumber(value) {
+  protected _isScalarColumnDefault(value: string) {
+    return (
+      value.toLowerCase() === 'null' ||
+      QUOTED_LITERAL_PATTERN.test(value) ||
+      value.toLowerCase() === 'true' ||
+      value.toLowerCase() === 'false' ||
+      NUMBER_LITERAL_PATTERN.test(value)
+    );
+  }
+
+  protected _isColumnDefaultBalanced(value: string) {
+    let depth = 0;
+    let quoted = false;
+    for (let index = 0; index < value.length; index++) {
+      const char = value[index];
+      if (char === "'") {
+        if (quoted && value[index + 1] === "'") {
+          index++;
+        } else {
+          quoted = !quoted;
+        }
+      } else if (!quoted && char === '(') {
+        depth++;
+      } else if (!quoted && char === ')') {
+        if (depth === 0) return false;
+        depth--;
+      }
+    }
+    return !quoted && depth === 0;
+  }
+
+  protected _isExpressionColumnDefault(value: string) {
+    return /[()*/+\-\s]/.test(value);
+  }
+
+  protected _safeInteger(value: string) {
     const num = Number(value);
-    return Number.isNaN(num) ? undefined : num;
+    return Number.isSafeInteger(num) ? num : value;
   }
 
-  protected _columnTypePrefixes(type: string, prefixes: string[]) {
-    return prefixes.some(prefix => type.includes(prefix));
+  protected _safeNumber(value: string) {
+    const num = Number(value);
+    return Number.isFinite(num) ? num : undefined;
   }
 }

package/vona/src/suite-vendor/a-vona/modules/a-permission/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-permission",
-  "version": "5.1.19",
+  "version": "5.1.20",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "",
   "keywords": [

package/vona/src/suite-vendor/a-vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-suite-a-vona",
-  "version": "5.1.83",
+  "version": "5.1.84",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "",
   "author": "",

package/zova/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-cli",
-  "version": "1.2.104",
+  "version": "1.2.105",
   "gitHead": "6f675a8cc46d596142c591c28a40cc4d82fcc6cc",
   "description": "zova cli",
   "keywords": [
@@ -44,7 +44,7 @@
     "@cabloy/process-helper": "^3.1.8",
     "fs-extra": "^11.3.5",
     "semver": "^7.6.2",
-    "zova-cli-set-front": "^1.2.102"
+    "zova-cli-set-front": "^1.2.103"
   },
   "devDependencies": {
     "clean-package": "^2.2.0",

package/zova/packages-cli/cli-set-front/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-cli-set-front",
-  "version": "1.2.102",
+  "version": "1.2.103",
   "gitHead": "6f675a8cc46d596142c591c28a40cc4d82fcc6cc",
   "description": "zova cli-set-front",
   "keywords": [
@@ -70,7 +70,7 @@
     "vite": "^8.0.14",
     "yaml": "^2.8.3",
     "zova-openapi": "^1.1.17",
-    "zova-vite": "^1.1.44"
+    "zova-vite": "^1.1.45"
   },
   "devDependencies": {
     "clean-package": "^2.2.0",

package/zova/packages-utils/zova-vite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-vite",
-  "version": "1.1.44",
+  "version": "1.1.45",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "zova vite",
   "keywords": [
@@ -40,7 +40,7 @@
     "@babel/plugin-proposal-decorators": "^7.29.0",
     "@babel/plugin-transform-class-properties": "^7.28.6",
     "@babel/plugin-transform-typescript": "^7.28.6",
-    "@cabloy/dotenv": "^1.2.8",
+    "@cabloy/dotenv": "^1.2.9",
     "@cabloy/extend": "^3.2.8",
     "@cabloy/module-glob": "^5.3.18",
     "@cabloy/module-info": "^2.0.3",

package/.claude/scheduled_tasks.lock

@@ -1 +0,0 @@
-{"sessionId":"834e10b3-c7de-4e46-8255-347f58ac99c9","pid":21283,"procStart":"Tue Sep  1 21:20:05 2026","acquiredAt":1788301241462}

package/vona/packages-utils/cascade-extend/LICENSE

@@ -1,3 +0,0 @@
-MIT License
-
-Copyright (c) 2016-present CabloyJS