cabloy 5.1.240 → 5.1.241

package/.cabloy-version

@@ -1 +1 @@
-5.1.240
+5.1.241

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 5.1.241
+
+### Features
+
+- Display the user's display name.
+- Add MCP permission support.
+- Add guard-only permission checks.
+
+### Improvements
+
+- Update the OpenAPI guide.
+
 ## 5.1.240
 
 ### Improvements

package/package.json

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

package/repo-docs/backend/openapi-guide.md

@@ -48,6 +48,24 @@ Representative capabilities include generating JSON for:
 
 This is important because OpenAPI is treated as a first-class framework service, not as an external afterthought.
 
+## MCP mapping and normal ingress admission
+
+In Cabloy Basic, method/class `@mcp.tool()` metadata opts registered Controller Actions into MCP mapping using their existing request/response contracts. It is independent of ordinary OpenAPI publication: `@Api.exclude()` is not an MCP authorization boundary, and publishing an HTTP action does not opt it into MCP. Decorator opt-in alone does **not** expose an action on normal `/mcp`.
+
+Normal shared ingress is owned by `cabloy-mcp` and accepts recognized dev/test/prod modes through the same OAuth and business-authorization boundary. Production is not rejected solely by mode; unknown modes, not-ready, closing, disabled or invalid required authority configuration still fail closed. Dedicated protected audit, audit-delivery gating and deployment-wide fine-grained quotas are deferred for this two-read MVP, not delivered capabilities or production prerequisites. Enabled-by-default behavior is unchanged: only literal `CABLOY_MCP_ENABLED=false` disables it. Construction admission permits exactly `training-student.controller.student` actions `lookup` and `summary`, for both listing and known-name direct calls. Optional training absent means an empty catalog, without fallback. The three synthetic catalog tools and anonymous standalone entry belong only to the `mcp-test` launcher, not shared `/mcp`.
+
+OAuth scope does not grant business authority. Lookup and summary retain independent student select/view permissions, current-instance reads and minimized output; summary's six-field projection does not change its HTTP DTO. Calls retain ordinary Action guards with `innerAccess: false`.
+
+Repository-relative source pointers:
+
+- Opt-in metadata: `vona/src/suite-vendor/a-vona/modules/a-openapiutils/src/lib/decorator/mcp.ts`
+- Contract mapper: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/lib/controllerTools.ts`
+- Normal ingress middleware: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/bean/middlewareSystem.mcp.ts`
+- Ingress checks: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/lib/mcpTransport.ts`
+- Authenticated exchange and settlement: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/lib/businessTransport.ts`
+- Exact admission and discovery: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/lib/sharedBusinessTools.ts`
+- Application-close drain: `vona/src/suite/cabloy-mcp/modules/cabloy-mcp/src/monkey.ts`
+
 ## Validation and OpenAPI are linked
 
 A major theme is that the same validation-oriented declaration surface also drives OpenAPI metadata generation.

package/repo-e2e/specs/home-user-account.spec.ts

@@ -383,7 +383,7 @@ test(
 );
 
 test(
-  'ATP-ACCOUNT-WEB-01: signed-in Web menu refreshes after profile save and keeps drafts isolated',
+  'ATP-ACCOUNT-WEB-01: display name refreshes the Web menu without changing the login username',
   { tag: ['@account', '@web', '@flow'] },
   async ({ page, request }, testInfo) => {
     let account: RegisteredAccount | undefined;
@@ -424,14 +424,27 @@ test(
         .poll(() => avatarPreview.evaluate(image => (image as HTMLImageElement).naturalWidth))
         .toBeGreaterThan(0);
 
-      const profileName = `e2e-fixture-home-account-profile-${testInfo.workerIndex}-${crypto.randomUUID()}`;
-      await page
+      const username = page.getByRole('textbox', { name: 'User name', exact: true });
+      await expect(username).toHaveValue(account.username);
+      await expect(username).toHaveAttribute('readonly', '');
+      const displayName = page
         .getByRole('group', { name: 'Display name', exact: true })
-        .getByRole('textbox')
-        .fill(profileName);
+        .getByRole('textbox');
+      await expect(displayName).toHaveValue('');
+      const profileName = `e2e-fixture-home-account-profile-${testInfo.workerIndex}-${crypto.randomUUID()}`;
+      await displayName.fill(`  ${profileName}  `);
       const timezone = page
         .getByRole('group', { name: 'Time zone', exact: true })
         .getByRole('textbox');
+      const inputWidths = await Promise.all(
+        [username, displayName, timezone].map(input =>
+          input.evaluate(element => element.getBoundingClientRect().width),
+        ),
+      );
+      expect(inputWidths[0]).toBeGreaterThan(0);
+      for (const width of inputWidths.slice(1)) {
+        expect(width).toBeCloseTo(inputWidths[0], 0);
+      }
       const browserTimezone = await page.evaluate(
         () => Intl.DateTimeFormat().resolvedOptions().timeZone,
       );
@@ -447,9 +460,21 @@ test(
       const profileResponse = waitForApiResponse(page, 'PATCH', accountProfileApiPath);
       const refreshedPassportResponse = waitForApiResponse(page, 'GET', passportCurrentApiPath);
       await page.getByRole('button', { name: 'Save profile', exact: true }).click();
-      expect((await profileResponse).ok()).toBeTruthy();
-      account.username = profileName;
-      expect((await refreshedPassportResponse).ok()).toBeTruthy();
+      const savedProfileResponse = await profileResponse;
+      expect(savedProfileResponse.ok()).toBeTruthy();
+      expect((await savedProfileResponse.json()).data).toMatchObject({
+        name: account.username,
+        displayName: profileName,
+      });
+      expect(savedProfileResponse.request().postDataJSON()).not.toHaveProperty('name');
+      const savedPassportResponse = await refreshedPassportResponse;
+      expect(savedPassportResponse.ok()).toBeTruthy();
+      expect((await savedPassportResponse.json()).data.user).toMatchObject({
+        name: account.username,
+        displayName: profileName,
+      });
+      await expect(username).toHaveValue(account.username);
+      await expect(displayName).toHaveValue(profileName);
       await expect(page.getByText('Profile saved.', { exact: true })).toBeVisible();
       await expect
         .poll(() =>
@@ -473,6 +498,26 @@ test(
       await expect(page).toHaveURL(accountPath);
       await expect(page.getByRole('heading', { name: 'Account Settings' })).toBeVisible();
       await expect(userMenu).not.toHaveAttribute('open', '');
+      await expect(username).toHaveValue(account.username);
+      await expect(displayName).toHaveValue(profileName);
+      const originalLogin = await loginAsAccount(request, account.username, account.password);
+      expect(String(originalLogin.id)).toBe(String(account.id));
+
+      await displayName.fill('   ');
+      const clearedProfileResponse = waitForApiResponse(page, 'PATCH', accountProfileApiPath);
+      const clearedPassportResponse = waitForApiResponse(page, 'GET', passportCurrentApiPath);
+      await page.getByRole('button', { name: 'Save profile', exact: true }).click();
+      const clearedProfile = await clearedProfileResponse;
+      expect(clearedProfile.ok()).toBeTruthy();
+      expect(clearedProfile.request().postDataJSON()).toMatchObject({ displayName: null });
+      const clearedProfileBody = (await clearedProfile.json()).data;
+      expect(clearedProfileBody.name).toBe(account.username);
+      expect(clearedProfileBody.displayName).toBeFalsy();
+      expect((await clearedPassportResponse).ok()).toBeTruthy();
+      await expect(displayName).toHaveValue('');
+      await expect(username).toHaveValue(account.username);
+      await expect(userMenu.locator('summary')).toContainText(account.username);
+      await expect(userMenu.locator('summary')).not.toContainText(profileName);
       expect(pageErrors).toEqual([]);
       expect(consoleErrors).toEqual([]);
     } finally {

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

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

package/vona/pnpm-lock.yaml

@@ -995,11 +995,11 @@ importers:
         specifier: npm:@cabloy/zod@4.3.8
         version: '@cabloy/zod@4.3.8'
       zova:
-        specifier: ^5.1.176
-        version: 5.1.176(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: ^5.1.177
+        version: 5.1.177(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
       zova-jsx:
-        specifier: ^1.1.94
-        version: 1.1.94(typescript@5.9.3)
+        specifier: ^1.1.95
+        version: 1.1.95(typescript@5.9.3)
       zova-module-a-api:
         specifier: ^5.1.23
         version: 5.1.23
@@ -1061,8 +1061,8 @@ importers:
         specifier: ^5.1.36
         version: 5.1.36
       zova-module-a-ssr:
-        specifier: ^5.1.41
-        version: 5.1.41
+        specifier: ^5.1.42
+        version: 5.1.42
       zova-module-a-ssrhmr:
         specifier: ^5.1.24
         version: 5.1.24
@@ -1079,8 +1079,8 @@ importers:
         specifier: ^5.1.39
         version: 5.1.39
       zova-module-a-zova:
-        specifier: ^5.1.113
-        version: 5.1.113(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: ^5.1.114
+        version: 5.1.114(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
       zova-module-pay-mock:
         specifier: ^5.0.6
         version: 5.0.6
@@ -1124,11 +1124,11 @@ importers:
         specifier: npm:@cabloy/zod@4.3.8
         version: '@cabloy/zod@4.3.8'
       zova:
-        specifier: ^5.1.176
-        version: 5.1.176(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: ^5.1.177
+        version: 5.1.177(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
       zova-jsx:
-        specifier: ^1.1.94
-        version: 1.1.94(typescript@5.9.3)
+        specifier: ^1.1.95
+        version: 1.1.95(typescript@5.9.3)
       zova-module-a-api:
         specifier: ^5.1.23
         version: 5.1.23
@@ -1190,8 +1190,8 @@ importers:
         specifier: ^5.1.36
         version: 5.1.36
       zova-module-a-ssr:
-        specifier: ^5.1.41
-        version: 5.1.41
+        specifier: ^5.1.42
+        version: 5.1.42
       zova-module-a-ssrhmr:
         specifier: ^5.1.24
         version: 5.1.24
@@ -1208,8 +1208,8 @@ importers:
         specifier: ^5.1.39
         version: 5.1.39
       zova-module-a-zova:
-        specifier: ^5.1.113
-        version: 5.1.113(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
+        specifier: ^5.1.114
+        version: 5.1.114(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
       zova-module-pay-mock:
         specifier: ^5.0.6
         version: 5.0.6
@@ -9412,15 +9412,9 @@ packages:
     resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
     engines: {node: '>=10'}
 
-  zova-core@5.1.94:
-    resolution: {integrity: sha512-puo3pqa4/ngwZj//Md457XMloZ4FRaoJlmwf+zyPyxKL7GoV81BaJeUPi9szzY8aM9EkoWXBhSVA0cp6mTXBhw==}
-
   zova-core@5.1.95:
     resolution: {integrity: sha512-nvBb3zVdJEQ9SWi+cl5j2PLs/T0FRRIULfHqU3SBFUn3jFSZFizniRlak+qoSq3mzj+LGD61BfnFJQb2JJ8+Zg==}
 
-  zova-jsx@1.1.94:
-    resolution: {integrity: sha512-4QGgNE5J32PXYCgHBt8JBrTRp8CXADgZzIBUsovQmKfIwtMY6DK5+zPQeWBVqHoV5vK95RKhRPwdAKFGOLupeg==}
-
   zova-jsx@1.1.95:
     resolution: {integrity: sha512-gzmR01Qt4oBrMCejH4W0fqfFx62L+XQOfOROs6mBVdFYGmbyXzy/lDXtTH4v4WjlrmVbuoAyZE/BrYmNxn2swA==}
 
@@ -9484,9 +9478,6 @@ packages:
   zova-module-a-routertabs@5.1.36:
     resolution: {integrity: sha512-QYkeK7ql0B2AdFcCj9a+oIyqZi7oW/Ay/YHMFSseRgoRU/dTQnK79/v/DWB8+JluxY0tWMakLDcSq7bIolRdgg==}
 
-  zova-module-a-ssr@5.1.41:
-    resolution: {integrity: sha512-2p19mMzc9MjvYDdEbV6qjOngxuM7vdzwA1+Z4+/81pOfptU7nBobqDaDUNZxblHEoiIHrDM8NCeghPBO6Fz2sg==}
-
   zova-module-a-ssr@5.1.42:
     resolution: {integrity: sha512-XaZcUHwDxwyQi4VNLK6CxkdG4lV5aUNgPNkiLjN3LWh9l2yS0u8CQqGV8+gEKcpOOj7XhZIubu4gb4GUNNQoGw==}
 
@@ -9505,9 +9496,6 @@ packages:
   zova-module-a-zod@5.1.39:
     resolution: {integrity: sha512-nyVgDGt7Xly/8ccGau/ZRck3PJfo+9WFMR4EudXo2YBFMahNeXUegTyUPeSV6DfJDUjCqpy2V060PipBVJ5QzQ==}
 
-  zova-module-a-zova@5.1.113:
-    resolution: {integrity: sha512-PuasOjYgRz8F94oVPSjQepwVxL+LySauwJQKNzly+yD7YCbQJcHy6tw7IejwcaSTjlBe3M1Iy6IWX7IwrOrfyw==}
-
   zova-module-a-zova@5.1.114:
     resolution: {integrity: sha512-H16jQ2YRw3Q9KSO7RDKMl+QRFZSZ7J/AkUUD71BTQA1oDLY+zBLuKTABwicEgS3S44R4qJC79rR/yuTXLlZnkw==}
 
@@ -9523,15 +9511,9 @@ packages:
   zova-module-rest-resource@5.1.57:
     resolution: {integrity: sha512-xpx42J+ZCx3KGzFZPQBHfUUDxgYTPlQGrUTrN0/SCY8PD/qYu77kqQ29+B5B9WcUeSnSAzUtbZx0UzzFia1slQ==}
 
-  zova-suite-a-zova@5.1.175:
-    resolution: {integrity: sha512-cjN97iaDZ3WhvOtu27YnqfZpEnnKptLGqqpllIhAtOFaTXtuMGiGVTmH7Q1tc/k9OPEHzvvCThsYKRxzYbR5DQ==}
-
   zova-suite-a-zova@5.1.176:
     resolution: {integrity: sha512-w7JQ0cutO3zaZosxfsSLn9/mcY5deftZWTGkiPJTTG6I6eGGZlFJRDCQpu+dBd8eYI66xe4kstdH3KGhLSt74A==}
 
-  zova@5.1.176:
-    resolution: {integrity: sha512-7E/Kc9QkuB6ckDX2ual9DFmiVrcPy/umDVlC+QlRFy5A30L8D5/WNKzWxmBubXYsXWmsAd/VZQUQPwditMmNkA==}
-
   zova@5.1.177:
     resolution: {integrity: sha512-35jZVs08Qn4cybwNqu1/PE3qz1J7Vi64y7AgTD98rVv5uOnDPkuwIIIVgMYZllV/C3kCsWPBLoC3tz/UG4SEcA==}
 
@@ -15880,37 +15862,6 @@ snapshots:
 
   yocto-queue@0.1.0: {}
 
-  zova-core@5.1.94(typescript@5.9.3):
-    dependencies:
-      '@cabloy/compose': link:packages-utils/compose
-      '@cabloy/extend': link:packages-utils/extend
-      '@cabloy/json5': link:packages-utils/json5
-      '@cabloy/localeutil': link:packages-utils/localeutil
-      '@cabloy/logger': 1.1.25
-      '@cabloy/module-info': 2.0.3
-      '@cabloy/utils': link:packages-utils/utils
-      '@cabloy/vue-compiler-sfc': 3.5.14
-      '@cabloy/vue-reactivity': 3.5.16
-      '@cabloy/vue-router': 4.4.18(vue@3.5.43(typescript@5.9.3))
-      '@cabloy/vue-runtime-core': 3.5.57
-      '@cabloy/vue-runtime-dom': 3.5.13
-      '@cabloy/vue-server-renderer': 3.5.18(vue@3.5.43(typescript@5.9.3))
-      '@cabloy/word-utils': 2.1.14
-      '@cabloy/zod-errors-custom': link:packages-utils/zod-errors-custom
-      '@cabloy/zod-openapi': link:packages-utils/zod-openapi
-      '@cabloy/zod-query': link:packages-utils/zod-query
-      '@types/js-cookie': 3.0.6
-      '@types/ms': 2.1.0
-      '@vue/shared': 3.5.36
-      deep-equal: 2.2.3
-      ms: 2.1.3
-      reflect-metadata: 0.2.2
-      vue: 3.5.43(typescript@5.9.3)
-      vue-plugin-render-freeze: 2.0.4(vue@3.5.43(typescript@5.9.3))
-      zod: '@cabloy/zod@4.3.8'
-    transitivePeerDependencies:
-      - typescript
-
   zova-core@5.1.95(patch_hash=44197c3f359a73a1a5bb3dc0a8a97e705a55b30f9a434717aa24d75a96f2c6b6)(typescript@5.9.3):
     dependencies:
       '@cabloy/compose': link:packages-utils/compose
@@ -15942,17 +15893,6 @@ snapshots:
     transitivePeerDependencies:
       - typescript
 
-  zova-jsx@1.1.94(typescript@5.9.3):
-    dependencies:
-      '@cabloy/compose': link:packages-utils/compose
-      '@cabloy/utils': link:packages-utils/utils
-      '@cabloy/word-utils': 2.1.14
-      typestyle: 2.4.0
-      vue: 3.5.43(typescript@5.9.3)
-      zova-core: 5.1.94(typescript@5.9.3)
-    transitivePeerDependencies:
-      - typescript
-
   zova-jsx@1.1.95(typescript@5.9.3):
     dependencies:
       '@cabloy/compose': link:packages-utils/compose
@@ -16033,11 +15973,6 @@ snapshots:
 
   zova-module-a-routertabs@5.1.36: {}
 
-  zova-module-a-ssr@5.1.41:
-    dependencies:
-      devalue: 5.9.4
-      ms: 2.1.3
-
   zova-module-a-ssr@5.1.42:
     dependencies:
       devalue: 5.9.4
@@ -16071,22 +16006,6 @@ snapshots:
       '@cabloy/zod-query': link:packages-utils/zod-query
       zod: '@cabloy/zod@4.3.8'
 
-  zova-module-a-zova@5.1.113(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
-    dependencies:
-      '@cabloy/compose': link:packages-utils/compose
-      '@cabloy/deps': link:packages-utils/deps
-      '@cabloy/json5': link:packages-utils/json5
-      '@cabloy/module-info': 2.0.3
-      '@cabloy/utils': link:packages-utils/utils
-      '@cabloy/vue-router': 4.4.18(vue@3.5.43(typescript@5.9.3))
-      '@cabloy/word-utils': 2.1.14
-      defu: 6.1.7
-      luxon: 3.7.2
-      zova-jsx: 1.1.94(typescript@5.9.3)
-    transitivePeerDependencies:
-      - typescript
-      - vue
-
   zova-module-a-zova@5.1.114(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       '@cabloy/compose': link:packages-utils/compose
@@ -16111,39 +16030,6 @@ snapshots:
 
   zova-module-rest-resource@5.1.57: {}
 
-  zova-suite-a-zova@5.1.175(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
-    dependencies:
-      zova-module-a-api: 5.1.23
-      zova-module-a-app: 5.1.27
-      zova-module-a-bean: 5.1.37
-      zova-module-a-behavior: 5.1.28
-      zova-module-a-behaviors: 5.1.23
-      zova-module-a-command: 5.1.36
-      zova-module-a-fetch: 5.1.26(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)
-      zova-module-a-form: 5.1.55(vue@3.5.43(typescript@5.9.3))
-      zova-module-a-icon: 5.1.28
-      zova-module-a-interceptor: 5.1.32
-      zova-module-a-logger: 5.1.29
-      zova-module-a-meta: 5.1.23
-      zova-module-a-model: 5.1.39(vue@3.5.43(typescript@5.9.3))
-      zova-module-a-openapi: 5.1.59
-      zova-module-a-router: 5.1.43
-      zova-module-a-routerstack: 5.1.30
-      zova-module-a-routertabs: 5.1.36
-      zova-module-a-ssr: 5.1.41
-      zova-module-a-ssrhmr: 5.1.24
-      zova-module-a-ssrserver: 5.1.27
-      zova-module-a-style: 5.1.36
-      zova-module-a-table: 5.1.45(vue@3.5.43(typescript@5.9.3))
-      zova-module-a-zod: 5.1.39
-      zova-module-a-zova: 5.1.113(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
-    transitivePeerDependencies:
-      - '@vue/composition-api'
-      - debug
-      - supports-color
-      - typescript
-      - vue
-
   zova-suite-a-zova@5.1.176(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       zova-module-a-api: 5.1.23
@@ -16177,17 +16063,6 @@ snapshots:
       - typescript
       - vue
 
-  zova@5.1.176(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
-    dependencies:
-      zova-core: 5.1.94(typescript@5.9.3)
-      zova-suite-a-zova: 5.1.175(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3))
-    transitivePeerDependencies:
-      - '@vue/composition-api'
-      - debug
-      - supports-color
-      - typescript
-      - vue
-
   zova@5.1.177(debug@4.4.3(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       zova-core: 5.1.95(patch_hash=44197c3f359a73a1a5bb3dc0a8a97e705a55b30f9a434717aa24d75a96f2c6b6)(typescript@5.9.3)

package/vona/src/suite/a-commerce/modules/commerce-siteadmin/src/dto/operatorContext.ts

@@ -1,6 +1,6 @@
 import type { IDecoratorDtoOptions } from 'vona-module-a-web';
 
-import { Api } from 'vona-module-a-openapiutils';
+import { Api, v } from 'vona-module-a-openapiutils';
 import { Dto } from 'vona-module-a-web';
 
 export interface IDtoOptionsOperatorContext extends IDecoratorDtoOptions {}
@@ -18,4 +18,7 @@ export class DtoOperatorContext {
 
   @Api.field()
   userName: string;
+
+  @Api.field(v.optional())
+  displayName?: string;
 }

package/vona/src/suite/a-commerce/modules/commerce-siteadmin/src/service/operator.ts

@@ -13,6 +13,7 @@ export class ServiceOperator extends BeanBase {
       instanceName: instanceName ?? '',
       userId: user.id.toString(),
       userName: user.name,
+      displayName: user.displayName,
     };
   }
 }

package/vona/src/suite/a-commerce/modules/commerce-siteadmin/test/operatorAccess.test.ts

@@ -47,6 +47,7 @@ describe('operatorAccess.test.ts', () => {
         assert.equal(result.instanceName, app.ctx.instanceName);
         assert.equal(result.userId, app.bean.passport.current!.user!.id.toString());
         assert.equal(result.userName, app.bean.passport.current!.user!.name);
+        assert.equal(result.displayName, app.bean.passport.current!.user!.displayName);
       } finally {
         await app.bean.passport.signout();
       }

package/vona/src/suite/a-home/modules/home-user/src/bean/meta.version.ts

@@ -32,6 +32,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionUpdate, IMetaVe
         table.comment(entityUser.$comment.$table);
         table.basicFields();
         table.string(entityUser.name, 255).comment(entityUser.$comment.name);
+        table.string(entityUser.displayName, 100).comment(entityUser.$comment.displayName);
         table.string(entityUser.avatar, 255).comment(entityUser.$comment.avatar);
         table.string(entityUser.email, 255).comment(entityUser.$comment.email);
         table.string(entityUser.mobile, 255).comment(entityUser.$comment.mobile);

package/vona/src/suite/a-home/modules/home-user/src/controller/passport.ts

@@ -157,6 +157,7 @@ export class ControllerPassport extends BeanBase {
       user: {
         id: user.id,
         name: user.name,
+        displayName: user.displayName,
         avatar: user.avatar,
         email: user.email,
         mobile: user.mobile,

package/vona/src/suite/a-home/modules/home-user/src/dto/accountCurrent.ts

@@ -11,6 +11,9 @@ export class DtoAccountCurrent {
   @Api.field()
   name: string;
 
+  @Api.field(v.optional())
+  displayName?: string;
+
   @Api.field(v.optional())
   avatar?: string;
 

package/vona/src/suite/a-home/modules/home-user/src/dto/accountProfileUpdate.ts

@@ -29,8 +29,15 @@ const avatarSchema = avatar.openapi({
 
 @Dto<IDtoOptionsAccountProfileUpdate>()
 export class DtoAccountProfileUpdate {
-  @Api.field(v.title($locale('AccountDisplayName')), v.min(1), v.max(100), v.trim())
-  name: string;
+  @Api.field(
+    v.title($locale('AccountDisplayName')),
+    z.preprocess(
+      // Preserve an explicit clear before optional-string coercion treats '' as omitted.
+      value => (value === '' ? null : value),
+      z.string().trim().max(100).nullable().optional(),
+    ),
+  )
+  displayName?: string | null;
 
   @Api.field(v.title($locale('AccountAvatar')), v.optional(), v.nullable(), avatarSchema)
   avatar?: string | null;

package/vona/src/suite/a-home/modules/home-user/src/dto/passportUser.ts

@@ -17,6 +17,9 @@ export class DtoPassportUser {
   @Api.field()
   name: string;
 
+  @Api.field(v.optional())
+  displayName?: string;
+
   @Api.field(v.optional())
   avatar?: string;
 

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

@@ -15,6 +15,9 @@ export class EntityUser extends EntityBase implements IUser {
   @Api.field(v.title($locale('UserName')))
   name: string;
 
+  @Api.field(v.title($locale('AccountDisplayName')), z.string().trim().max(100).optional())
+  displayName?: string;
+
   @Api.field(v.title($locale('UserAvatar')), v.optional())
   avatar?: string;
 

package/vona/src/suite/a-home/modules/home-user/src/service/account.ts

@@ -63,7 +63,10 @@ export class ServiceAccount extends BeanBase {
     const locale = this._resolveLocale(command.locale, user.locale);
     const tz = this._resolveTimezone(command.tz, user.tz);
     await this.scope.model.user.updateById(user.id, {
-      name: command.name,
+      displayName:
+        command.displayName === undefined
+          ? user.displayName
+          : command.displayName?.trim() || undefined,
       avatar,
       locale,
       tz,
@@ -218,12 +221,12 @@ export class ServiceAccount extends BeanBase {
       await this.bean.mail.send({
         to: currentUser.email,
         subject: replaceTemplate(this.scope.locale.ActivationEmailSubject(), {
-          userName: currentUser.name,
+          userName: currentUser.displayName || currentUser.name,
           link,
           siteName: this.ctx.instance.title || this.app.meta.env.APP_TITLE,
         }),
         text: replaceTemplate(this.scope.locale.ActivationEmailBody(), {
-          userName: currentUser.name,
+          userName: currentUser.displayName || currentUser.name,
           link,
           siteName: this.ctx.instance.title || this.app.meta.env.APP_TITLE,
         }),
@@ -521,6 +524,7 @@ export class ServiceAccount extends BeanBase {
     const eligibleEmail = user.email?.trim() || undefined;
     return {
       name: user.name,
+      displayName: user.displayName,
       avatar: user.avatar,
       locale: user.locale,
       tz: user.tz,

package/vona/src/suite/a-home/modules/home-user/src/service/userAdapter.ts

@@ -13,6 +13,7 @@ export class ServiceUserAdapter extends BeanBase implements IUserAdapter {
   async userOfProfile(profile: IAuthUserProfile): Promise<Partial<IUser>> {
     return {
       name: profile.username!,
+      displayName: profile.displayName?.trim() || undefined,
       email: profile.emails?.[0].value,
       avatar: profile.photos?.[0].value,
       locale: profile.locale || this.ctx.locale,