cabloy 5.1.179 → 5.1.180

package/.cabloy-version

@@ -1 +1 @@
-5.1.179
+5.1.180

package/.claude/scheduled_tasks.lock

@@ -1 +1 @@
-{"sessionId":"6217847e-59ab-4e60-bb87-bbecdd19f760","pid":92862,"procStart":"Sat Sep 19 06:45:25 2026","acquiredAt":1789807599408}
+{"sessionId":"f94cb5dc-de70-445c-8874-218b19d56077","pid":47778,"procStart":"Sun Sep 20 12:39:48 2026","acquiredAt":1789961541374}

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 5.1.180
+
+### Features
+
+- Add support for `$pageHost?.active`.
+- Prepare CRUD resources for RBAC integration.
+- Add demonstration capabilities.
+- Update framework functionality.
+
+### Bug Fixes
+
+- Fix the RBAC adapter.
+
+### Improvements
+
+- Refactor the demo demonstration.
+- Update framework performance documentation.
+- Improve page metadata documentation.
+
 ## 5.1.179
 
 ### Improvements

package/package.json

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

package/repo-docs/.vitepress/config.mjs

@@ -308,6 +308,7 @@ export default defineConfig({
             { text: 'Auth Guide', link: '/backend/auth-guide' },
             { text: 'Captcha Guide', link: '/backend/captcha-guide' },
             { text: 'Rate Limit Guide', link: '/backend/rate-limit-guide' },
+            { text: 'Demonstration Mode Guide', link: '/backend/demonstration-mode-guide' },
             { text: 'User Access Guide', link: '/backend/user-access-guide' },
             { text: 'JWT Guide', link: '/backend/jwt-guide' },
             { text: 'Validation Guide', link: '/backend/validation-guide' },

package/repo-docs/backend/controller-aop-guide.md

@@ -81,7 +81,7 @@ The `@Core.gate(...)` shorthand still maps to `@Aspect.middlewareGlobal('a-core:
 
 ## Guard
 
-Guards are used for access control and execution preconditions.
+Guards are used for access control and execution preconditions. For a concrete global Guard that controls write admission in a shared demo deployment, see [Demonstration Mode Guide](/backend/demonstration-mode-guide).
 
 Typical jobs include:
 

package/repo-docs/backend/demonstration-mode-guide.md

@@ -0,0 +1,130 @@
+# Demonstration Mode Guide
+
+<Badge type="tip" text="Common" />
+
+Demonstration Mode is an application-wide write-admission policy for shared demonstration deployments. It is provided by the first-party `a-demo` suite and uses a global Vona Guard to prevent ordinary visitors from changing demo data.
+
+It is disabled by default. When enabled, it protects selected HTTP write methods while leaving the rest of the application's authentication and authorization policies in force.
+
+## What Demonstration Mode does—and does not do
+
+Demonstration Mode is a safety rail for demo data. It is **not** a replacement for:
+
+- Passport authentication
+- RBAC or domain-specific authorization
+- validation and business rules
+- WAF, reverse-proxy, or network controls
+- database and other data-access safeguards
+
+Approval by this Guard only lets the request continue to the normal request pipeline; it does not grant the caller any additional permission.
+
+The policy applies to HTTP requests only. It does not protect side-effecting `GET` handlers, background jobs, scheduled work, queues, CLI execution, or other non-HTTP code. Model state-changing HTTP APIs with the protected write methods and retain their ordinary authorization rules.
+
+## Enable Demonstration Mode
+
+Configure the backend environment and restart Vona:
+
+```dotenv
+DEMONSTRATION_ENABLED=true
+DEMONSTRATION_USERNAME_WHITELIST=admin,demo-editor
+```
+
+`DEMONSTRATION_ENABLED` enables the Guard only when its value is the exact lowercase string `true`. An unset value, an empty value, `TRUE`, `True`, and `1` all leave Demonstration Mode disabled.
+
+Use [Runtime and Flavors](/backend/runtime-and-flavors#env-file-resolution-and-precedence) to select the active environment files and understand precedence. In a local backend setup, an uncommitted `vona/env/.env.local` is a typical place for local overrides. Deployment-injected environment values may also take precedence. For the broader configuration model, see the [Config Guide](/backend/config-guide).
+
+Environment values are evaluated while the backend initializes. Restart Vona after changing either Demonstration Mode variable.
+
+## Configure exempt writers
+
+`DEMONSTRATION_USERNAME_WHITELIST` is a comma-separated list of usernames that may perform protected writes:
+
+```dotenv
+DEMONSTRATION_USERNAME_WHITELIST=admin, demo-editor, content-manager
+```
+
+The list is normalized as follows:
+
+- surrounding whitespace is removed from each entry
+- empty entries are discarded
+- repeated entries are deduplicated
+- usernames match entries exactly and case-sensitively
+
+Whitelist membership is necessary but not sufficient. A protected write is admitted only when the current user is all of the following:
+
+- authenticated
+- account-active
+- non-anonymous
+- present in the username whitelist
+
+If the whitelist is absent or empty while Demonstration Mode is enabled, no user qualifies for protected writes.
+
+## Request behavior
+
+The Guard protects these HTTP methods:
+
+- `POST`
+- `PATCH`
+- `DELETE`
+- `PUT`
+
+Other methods pass through this Guard unchanged. A protected request is allowed only for an eligible whitelisted user. All other protected requests are rejected with:
+
+| Field                  | Value                                             |
+| ---------------------- | ------------------------------------------------- |
+| HTTP status            | `403 Forbidden`                                   |
+| Application error code | `demo-demonstration:1001`                         |
+| Meaning                | The operation is forbidden in demonstration mode. |
+
+The Guard depends on Passport-resolved account state, so it makes this decision only after the current account information is available. Passing the Demonstration Mode check does not bypass later Passport, RBAC, or business-policy checks.
+
+## Exempt authentication routes
+
+Demonstration Mode deliberately does not apply to the standard authentication and OAuth routes below. This keeps sign-in, sign-out, registration, account association and migration, OAuth callbacks, and token flows available while the write policy is active.
+
+```text
+/home/user/passport/logout
+/home/user/passport/register
+/home/user/passport/login
+/home/user/passport/login/:module/:providerName/:clientName?
+/home/user/passport/associate/:module/:providerName/:clientName?
+/home/user/passport/migrate/:module/:providerName/:clientName?
+/home/user/passport/refreshAuthToken
+/home/user/passport/createPassportJwtFromOauthCode
+/home/user/passport/createTempAuthToken
+/auth/passport/callback
+```
+
+These are route templates used by the built-in authentication flows. They are not a general mechanism for bypassing Demonstration Mode on arbitrary URLs.
+
+## Deploy with the `a-demo` suite
+
+The `demo-demonstration` module is included in the current project's `a-demo` suite; no separate package installation is required.
+
+If an operator intentionally excludes the whole suite:
+
+```dotenv
+PROJECT_DISABLED_SUITES=a-demo
+```
+
+then `demo-demonstration` and its Guard are not loaded, regardless of `DEMONSTRATION_ENABLED` or the whitelist. This is expected when a deployment does not include demo capabilities.
+
+For ordinary policy changes, use `DEMONSTRATION_ENABLED` rather than disabling the suite. Reserve `PROJECT_DISABLED_SUITES=a-demo` for deployments that intentionally exclude all `a-demo` functionality.
+
+## Troubleshooting
+
+| Symptom                                | Check                                                                                                                                                               |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The policy appears inactive            | Confirm `DEMONSTRATION_ENABLED=true` uses exact lowercase spelling, then restart Vona and check active environment-file and deployment-variable precedence.         |
+| An intended demo editor receives `403` | Confirm that the user is authenticated, active, non-anonymous, and that their username exactly matches a whitelist entry, including case.                           |
+| A request is unexpectedly allowed      | Confirm whether it uses a method other than `POST`, `PATCH`, `DELETE`, or `PUT`, or whether it belongs to an exempt built-in authentication route.                  |
+| The policy never loads                 | Confirm that `a-demo` is not listed in `PROJECT_DISABLED_SUITES`.                                                                                                   |
+| A non-HTTP mutation still runs         | Demonstration Mode only guards applicable HTTP requests; add the appropriate authorization and execution controls to the relevant job, queue, CLI, or service path. |
+
+## Related guides
+
+- [Runtime and Flavors](/backend/runtime-and-flavors#env-file-resolution-and-precedence)
+- [Config Guide](/backend/config-guide)
+- [Controller AOP Guide](/backend/controller-aop-guide#guard)
+- [Auth Guide](/backend/auth-guide)
+- [User Access Guide](/backend/user-access-guide)

package/repo-docs/frontend/page-meta-guide.md

@@ -38,8 +38,8 @@ The shortest accurate model is:
 2. page code calls `$router.setPageMeta(this.$pageRoute, pageMeta)` when task-level presentation should change
 3. the shared router bean forwards that update to registered router-view hosts
 4. `routerViewTabs` delegates the update to `ModelTabs`
-5. `ModelTabs` stores the metadata on the current level-2 tab item
-6. the active layout reads that metadata to render task-level title and icon state
+5. `ModelTabs` stores the metadata on the level-2 work item matched by the route's `fullPath`
+6. the relevant layout reads that metadata to render task-level title and icon state
 
 That is why page metadata is not the same thing as route metadata.
 
@@ -57,13 +57,14 @@ The highest-value current Basic source path is:
 5. `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/component/routerViewTabs/controller.tsx` overrides `setPageMeta(...)` and delegates to `ModelTabs`
 6. `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/model/tabs.ts` stores and merges `pageMeta` on the routed work item
 7. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx` shows the clearest current authoring path
-8. `zova/src/suite/a-home/modules/home-layoutadmin/src/component/layoutAdmin/render.tabs.tsx` shows the clearest current visible shell consumer
+8. `zova/src/suite/a-home/modules/home-indexadmin/src/page/dashboard/controller.tsx` shows a current custom-render page-meta call site
+9. `zova/src/suite/a-home/modules/home-layoutadmin/src/component/layoutAdmin/render.tabs.tsx` shows the clearest current visible shell consumer
 
 A compact interpretation is:
 
 - page code emits page meta through `$router.setPageMeta(...)`
-- the router forwards it to the active routed host
-- the tabs host stores it on the routed work item
+- the router forwards it to all registered routed hosts
+- each host may handle the update or ignore it; the tabs host stores it on the work item matched by the route
 - the shell renders title, dirty, and form-scene signals from that stored metadata
 
 ## The public page-meta surface
@@ -81,9 +82,39 @@ export interface IPageMeta {
   pageTitle?: string;
   pageDirty?: boolean;
   formMeta?: IFormMeta;
+  onCustomRender?: (tabItem: IRouteViewRouteItem) => VNodeChild;
+  onCustomRenderIsolate?: (tabCurrent: IRouteViewTabCurrent) => VNodeChild;
 }
 ```
 
+The two render callbacks are optional shell-rendering hooks. They are useful when a page needs to replace the usual text-only task label with a small reactive presentation, such as a status badge or clock. They are not a replacement for the page's main `render()` output.
+
+### `onCustomRender`
+
+`onCustomRender` customizes the content of a non-anchor level-2 tab item. The callback receives the corresponding `IRouteViewRouteItem` and returns a Vue `VNodeChild`:
+
+```typescript
+this.$router.setPageMeta(this.$pageRoute, {
+  onCustomRender: tabItem => <span>{tabItem.pageMeta?.pageTitle || 'Working'}</span>,
+});
+```
+
+In the current Admin tabs renderer, this callback takes precedence over `pageTitle` for that tab item. The returned content is rendered inside the level-2 tab label. Use the callback argument for stable tab-item metadata; use the page/controller's reactive state when the label itself needs to update.
+
+### `onCustomRenderIsolate`
+
+`onCustomRenderIsolate` customizes the active anchor item's isolated level-2 presentation. The callback receives the current `IRouteViewTabCurrent` and returns a Vue `VNodeChild`:
+
+```typescript
+this.$router.setPageMeta(this.$pageRoute, {
+  onCustomRenderIsolate: () => <span class="badge">Online</span>,
+});
+```
+
+In the current Admin tabs renderer, this callback has precedence over the anchor's `pageTitle` and the ordinary level-2 tab list. It is therefore appropriate for a page-specific shell area that should be shown in place of the default current-item title. The current Basic dashboard uses this hook for its live time badge.
+
+These callbacks are currently consumed by the Admin layout's tabs renderer. Do not assume that every routed host or every edition renders them; verify the concrete host and layout before relying on custom shell output.
+
 ### `pageTitle`
 
 `pageTitle` is the task-level title for the current routed work item.
@@ -224,7 +255,7 @@ setPageMeta(route, pageMeta) {
 
 This means the router bean is not itself the state owner.
 
-It is the forwarding boundary between page code and routed hosts.
+It is the forwarding boundary between page code and routed hosts. The base router-view host provides a no-op `setPageMeta(...)`, so a host that does not override it can ignore the update without changing the page or route record.
 
 ### 3. `routerViewTabs` delegates to `ModelTabs`
 
@@ -241,7 +272,7 @@ public setPageMeta(route, pageMeta) {
 }
 ```
 
-Inside `ModelTabs`, the update is resolved by `route.fullPath`, then applied to the current tab item.
+Inside `ModelTabs`, the update is resolved by searching the tab items for the matching `route.fullPath`, then applied to that routed work item. The incoming object is shallow-merged with the existing `pageMeta`, so a later call can update one field without clearing the other fields already stored on that work item.
 
 This is the crucial source-level fact:
 
@@ -249,16 +280,29 @@ This is the crucial source-level fact:
 
 ### 4. The active layout consumes the stored page meta
 
-Representative Basic consumers:
+The clearest Basic page-meta consumer is the Admin layout:
 
 - `zova/src/suite/a-home/modules/home-layoutadmin/src/component/layoutAdmin/render.tabs.tsx`
+
+The Web layout has a related tabs presentation, but its current renderer does not read `pageMeta`:
+
 - `zova/src/suite/a-home/modules/home-layoutweb/src/component/layoutWeb/render.tabs.tsx`
 
-In the current Basic source, the layout can use page meta for:
+In the current Admin layout, the renderer can use page meta for:
 
 - task-level title rendering
 - dirty indicators
 - create/edit icon signals derived from `formMeta.formScene`
+- custom content for level-2 tab items through `onCustomRender`
+- isolated content for the active anchor item through `onCustomRenderIsolate`
+
+The current Admin tabs renderer applies custom content in this order:
+
+1. if the active anchor item has `onCustomRenderIsolate`, render that isolated result
+2. otherwise, if the anchor item has `pageTitle`, render that title
+3. otherwise, render the other level-2 items; each item uses `onCustomRender(tabItem)` when present, otherwise its `pageTitle`
+
+When tabs caching is enabled, this renderer wraps the custom shell output in `ClientOnly`. The current Web layout's tabs renderer does not read these page-meta callbacks, so do not assume that the same custom output appears in every layout or routed host.
 
 ## The most important authoring pattern
 
@@ -355,13 +399,47 @@ this.$router.setPageMeta(this.$pageRoute, {
 
 In the current Basic source, this lets the layout derive task-level icon treatment from `formMeta.formScene`.
 
-### Scenario 4: I only want to change browser document title
+### Scenario 4: I need a custom task-level shell presentation
+
+Use one of the custom render hooks when the normal title text is not enough:
+
+```typescript
+this.$router.setPageMeta(this.$pageRoute, {
+  onCustomRenderIsolate: () => (
+    <span class="badge badge-primary">{this.statusText}</span>
+  ),
+});
+```
+
+Use `onCustomRender` for a non-anchor level-2 item and `onCustomRenderIsolate` when the active anchor item's presentation should replace the ordinary level-2 item row. The callback may close over reactive controller state, as in the current dashboard clock example:
+
+- `zova/src/suite/a-home/modules/home-indexadmin/src/page/dashboard/controller.tsx`
+
+These are routed-shell presentation hooks, not browser document-title or SEO metadata APIs.
 
-Do not assume page meta is the right tool.
+### Scenario 5: I only want to change browser document title
+
+Use [`$useMeta(...)` in the SSR SEO Meta guide](/frontend/ssr-seo-meta#usemeta), not `$router.setPageMeta(...)`.
+
+`pageTitle` is a routed-shell task-title surface first. `$useMeta(...)` owns SSR-aware document-head metadata, including the browser title:
+
+```typescript
+this.$useMeta({
+  title: 'Product catalogue',
+});
+```
+
+When the title depends on reactive page state, pass a function so the client metadata surface updates with that state:
+
+```typescript
+this.$useMeta(() => ({
+  title: this.product?.name ?? 'Product',
+}));
+```
 
-`pageTitle` is a routed-shell task-title surface first.
+Use page meta as well only when the routed shell needs its task label to change independently. For example, a record editor may set `pageTitle` for its Admin tab and `$useMeta(...)` for the browser title; neither API automatically updates the other.
 
-If the requirement is only browser document-title behavior, verify the current document-title consumer path before reusing page meta for that purpose.
+For title templates, descriptions, other head tags, and the static-versus-reactive behavior of `$useMeta(...)`, continue with [SSR SEO Meta](/frontend/ssr-seo-meta).
 
 ## A compact helper pattern
 

package/repo-docs/frontend/router-view-hosts-guide.md

@@ -129,6 +129,43 @@ A compact interpretation is:
 
 This is the point where route state becomes host state.
 
+### Page activation state
+
+A routed page and its descendant Zova components can read the optional `$pageHost` shortcut:
+
+```ts
+this.$pageHost?.active;
+```
+
+`$pageHost.active` is a stable, reactive page-host context value. It describes whether this concrete page component instance is currently activated by its Vue host. It is initialized as `true` for SSR and the initial client render, becomes `false` when a cached page is deactivated, and becomes `true` again when that same page instance is reactivated. It becomes `false` before final unmount as a cleanup safeguard.
+
+Use it to pause work that does not need to continue while a cached page is inactive, for example timers, polling, subscriptions, media, or observers:
+
+```ts
+this.$watch(
+  () => this.$pageHost?.active,
+  active => {
+    if (active) this.startPolling();
+    else this.stopPolling();
+  },
+  { immediate: true },
+);
+```
+
+Keep the browser-only work behind the existing SSR and hydration boundary. An initial `active === true` value does not mean that `window`, `document`, or other browser APIs exist during server rendering.
+
+`$pageHost.active` is not:
+
+- the current route or navigation intent
+- membership in `keepAliveInclude`
+- the selected Tabs or Stack model item
+- browser visibility or window focus
+- data-loading readiness
+
+Therefore `active` and `keepAlive` answer different questions: `keepAlive` controls retention eligibility, while `$pageHost.active` reports the lifecycle state of the retained page instance. `__dispose__()` remains the final cleanup hook and is not called merely because a cached page is deactivated.
+
+This context is available through the page bean-host hierarchy, so Page Controllers, Render/Style companions, and descendant components can observe the same page-host object. Nested routed pages receive their own nearest page host.
+
 ## Host 1: `routerViewEmpty`
 
 The minimal host controller lives in:

package/repo-docs/fullstack/framework-performance.md

@@ -42,17 +42,17 @@ For the current public explanation of this backend capability, see [Cache Guide]
 
 This is the kind of result Cabloy is designed to support: a framework that stays operationally calm even when the system keeps running for long periods.
 
-One internally generated project was kept running continuously for **2 months**. At one representative PM2 snapshot, the process looked like this:
+One internally generated project was kept running continuously for **3 months**. At one representative PM2 snapshot, the process looked like this:
 
 ```text
 ┌────┬─────────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
 │ id │ name            │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
 ├────┼─────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
-│ 0  │ cabloy_***    │ default     │ N/A     │ cluster │ 226947   │ 2M    │ 17   │ online    │ 0%       │ 388.4mb  │ ubuntu   │ disabled │
+│ 0  │ cabloy_***    │ default     │ N/A     │ cluster │ 226947   │ 3M    │ 17   │ online    │ 0%       │ 381.4mb  │ ubuntu   │ disabled │
 └────┴─────────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘
 ```
 
-For this 2-month continuous run, the observed result was **0 memory leak**.
+For this 3-month continuous run, the observed result was **0 memory leak**.
 
 The value of this example is not that it is a synthetic micro-benchmark. The value is that it reflects a real long-running project process with a clear, inspectable runtime footprint.
 

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

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

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudBasic/boilerplate/src/controller/{{resourceName}}.ts_

@@ -27,42 +27,42 @@ export interface IControllerOptions<%=argv.resourceNameCapitalize%> extends IDec
 export class Controller<%=argv.resourceNameCapitalize%> extends BeanBase {
   @Web.post('', { summary: $locale('<%=argv.resourceNameCapitalize%>Create') })
   @Api.body(v.tableIdentity())
-  @Passport.systemAdmin()
+  @Passport.rbac()
   async create(@Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Create): Promise<TableIdentity> {
     return (await this.scope.service.<%=argv.resourceName%>.create(<%=argv.resourceName%>)).id;
   }
 
   @Web.get('', { summary: $locale('<%=argv.resourceNameCapitalize%>Select') })
   @Api.body(Dto<%=argv.resourceNameCapitalize%>SelectRes)
-  @Passport.systemAdmin()
+  @Passport.rbac()
   async select(@Arg.filter(Dto<%=argv.resourceNameCapitalize%>SelectReq) params: IQueryParams<Model<%=argv.resourceNameCapitalize%>>): Promise<Dto<%=argv.resourceNameCapitalize%>SelectRes> {
     return await this.scope.service.<%=argv.resourceName%>.select(params);
   }
 
   @Web.get(':id', { summary: $locale('<%=argv.resourceNameCapitalize%>View') })
   @Api.body(v.optional(), v.object(Dto<%=argv.resourceNameCapitalize%>View))
-  @Passport.systemAdmin()
+  @Passport.rbac()
   async view(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<Dto<%=argv.resourceNameCapitalize%>View | undefined> {
     return await this.scope.service.<%=argv.resourceName%>.view(id);
   }
 
   @Web.patch(':id', { summary: $locale('<%=argv.resourceNameCapitalize%>Update') })
   @Api.body(z.null())
-  @Passport.systemAdmin()
+  @Passport.rbac()
   async update(@Arg.param('id', v.tableIdentity()) id: TableIdentity, @Arg.body() <%=argv.resourceName%>: Dto<%=argv.resourceNameCapitalize%>Update): Promise<void> {
     await this.scope.service.<%=argv.resourceName%>.update(id, <%=argv.resourceName%>);
   }
 
   @Web.delete(':id', { summary: $locale('<%=argv.resourceNameCapitalize%>Delete') })
   @Api.body(z.null())
-  @Passport.systemAdmin()
+  @Passport.rbac()
   async delete(@Arg.param('id', v.tableIdentity()) id: TableIdentity): Promise<void> {
     await this.scope.service.<%=argv.resourceName%>.delete(id);
   }
 
-  @Web.post('bulk/delete', { summary: $locale('BulkDelete') })
+  @Web.post('bulk/delete', { summary: $locale('<%=argv.resourceNameCapitalize%>DeleteBulk') })
   @Api.body(z.null())
-  @Passport.systemAdmin()
+  @Passport.rbac({ actionInherit: 'delete' })
   async deleteBulk(@Arg.body() command: Dto<%=argv.resourceNameCapitalize%>DeleteBulk): Promise<void> {
     await this.scope.service.<%=argv.resourceName%>.deleteBulk(command.ids);
   }

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudBasic/boilerplate/test/{{resourceName}}.test.ts_

@@ -1,12 +1,74 @@
 import type { Dto<%=argv.resourceNameCapitalize%>Create, Dto<%=argv.resourceNameCapitalize%>SelectRes, Dto<%=argv.resourceNameCapitalize%>Update, Entity<%=argv.resourceNameCapitalize%> } from 'vona-module-<%=argv.moduleInfo.relativeName%>';
+
 import assert from 'node:assert';
 import { describe, it } from 'node:test';
+import { appMetadata } from 'vona';
 import { app } from 'vona-mock';
+import { SymbolOpenApiOptions } from 'vona-module-a-openapiutils';
+
+describe('<%=argv.resourceName%>.test.ts', { concurrency: false }, () => {
+  it('action:<%=argv.resourceName%>:openapiMetadata', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const controllerBeanFullName = '<%=argv.moduleInfo.relativeName%>.controller.<%=argv.resourceName%>';
+      const controller = app.bean.onion.controller
+        .getOnionsEnabledCached()
+        .find(item => item.beanOptions.beanFullName === controllerBeanFullName)
+        ?.beanOptions.beanClass;
+      if (!controller) throw new Error(`${controllerBeanFullName} not found`);
+
+      const controllerMetadata = appMetadata.getMetadata<any>(
+        SymbolOpenApiOptions,
+        controller,
+      );
+      assert.equal(
+        controllerMetadata?.summary?.toString(),
+        '<%=argv.moduleInfo.relativeName%>::<%=argv.resourceNameCapitalize%>Controller',
+      );
+
+      const expectedSummaries = {
+        create: ['post', '<%=argv.moduleActionPathRaw%>', 'Create <%=argv.resourceNameCapitalize%>'],
+        select: ['get', '<%=argv.moduleActionPathRaw%>', 'Query <%=argv.resourceNameCapitalize%> List'],
+        view: ['get', '<%=argv.moduleActionPathRaw%>/{id}', 'View <%=argv.resourceNameCapitalize%>'],
+        update: ['patch', '<%=argv.moduleActionPathRaw%>/{id}', 'Update <%=argv.resourceNameCapitalize%>'],
+        delete: ['delete', '<%=argv.moduleActionPathRaw%>/{id}', 'Delete <%=argv.resourceNameCapitalize%>'],
+        deleteBulk: ['post', '<%=argv.moduleActionPathRaw%>/bulk/delete', 'Bulk Delete <%=argv.resourceNameCapitalize%>'],
+      } as const;
+      for (const [action, [method, path, summary]] of Object.entries(expectedSummaries)) {
+        const apiJson = await app.bean.openapi.generateJsonOfControllerAction(
+          controller,
+          action,
+          'V31',
+        );
+        const operation = (apiJson.paths as any)?.[path]?.[method];
+        assert.ok(operation, `${action} operation is missing`);
+        assert.equal(operation.summary?.toJSON(), summary);
+      }
+    });
+  });
+
+  it('action:<%=argv.resourceName%>:rbacCatalog', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const controllerBeanFullName = '<%=argv.moduleInfo.relativeName%>.controller.<%=argv.resourceName%>';
+      const catalog = app.bean.rbacCatalog.getCatalog();
+      const expectedInherits = {
+        create: undefined,
+        select: undefined,
+        view: undefined,
+        update: undefined,
+        delete: undefined,
+        deleteBulk: `${controllerBeanFullName}#delete`,
+      } as const;
+      for (const [action, actionInheritKey] of Object.entries(expectedInherits)) {
+        const descriptor = catalog.get(`${controllerBeanFullName}#${action}`);
+        assert.ok(descriptor, `${action} RBAC action is missing`);
+        assert.equal(descriptor.actionInheritKey, actionInheritKey);
+        assert.equal(descriptor.options.dataScope, undefined);
+      }
+    });
+  });
 
-describe('<%=argv.resourceName%>.test.ts', () => {
   it('action:<%=argv.resourceName%>', async () => {
     await app.bean.executor.mockCtx(async () => {
-      // data
       const data: Dto<%=argv.resourceNameCapitalize%>Create = {
         name: '__Tom__',
         description: 'This is a test',
@@ -15,48 +77,40 @@ describe('<%=argv.resourceName%>.test.ts', () => {
         name: '__TomNew__',
         description: 'This is a test',
       };
-      // role-less authenticated users cannot access generated admin actions
+      let <%=argv.resourceName%>Id: Entity<%=argv.resourceNameCapitalize%>['id'] | undefined;
+      // sign in as an unrestricted test identity
       await app.bean.passport.signinMock();
       try {
-        app.bean.passport.current!.roles = [];
-        const actions = ['create', 'select', 'view', 'update', 'delete'];
-        const permissions = await Promise.all(
-          actions.map(action =>
-            app.bean.permission.retrievePermissionAction(
-              '<%=argv.moduleInfo.relativeName%>:<%=argv.resourceName%>',
-              action,
-            ),
-          ),
-        );
-        assert.deepEqual(permissions, actions.map(() => false));
+        // create
+        <%=argv.resourceName%>Id = await app.bean.executor.performAction('post', '<%=argv.moduleActionPathRaw%>', { body: data });
+        assert.equal(!!<%=argv.resourceName%>Id, true);
+        // findMany
+        const selectRes: Dto<%=argv.resourceNameCapitalize%>SelectRes = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>');
+        assert.equal(selectRes.list.findIndex(item => item.name === data.name) > -1, true);
+        // update
+        const updateRes = await app.bean.executor.performAction('patch', '<%=argv.moduleActionPathRaw%>/:id', {
+          params: { id: <%=argv.resourceName%>Id },
+          body: dataUpdate,
+        });
+        assert.equal(updateRes, null);
+        // findOne
+        let <%=argv.resourceName%>: Entity<%=argv.resourceNameCapitalize%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>Id } });
+        assert.equal(<%=argv.resourceName%>.name, dataUpdate.name);
+        // delete
+        const deleteRes = await app.bean.executor.performAction('delete', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
+        assert.equal(deleteRes, null);
+        // findOne
+        <%=argv.resourceName%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
+        assert.equal(<%=argv.resourceName%>, undefined);
       } finally {
+        if (<%=argv.resourceName%>Id) {
+          await app.scope('<%=argv.moduleInfo.relativeName%>').model.<%=argv.resourceName%>.deleteById(
+            <%=argv.resourceName%>Id,
+            { disableDeleted: true },
+          );
+        }
         await app.bean.passport.signout();
       }
-      // login as system admin
-      await app.bean.passport.signinMock();
-      // create
-      const <%=argv.resourceName%>Id = await app.bean.executor.performAction('post', '<%=argv.moduleActionPathRaw%>', { body: data });
-      assert.equal(!!<%=argv.resourceName%>Id, true);
-      // findMany
-      const selectRes: Dto<%=argv.resourceNameCapitalize%>SelectRes = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>');
-      assert.equal(selectRes.list.findIndex(item => item.name === data.name) > -1, true);
-      // update
-      const updateRes = await app.bean.executor.performAction('patch', '<%=argv.moduleActionPathRaw%>/:id', {
-        params: { id: <%=argv.resourceName%>Id },
-        body: dataUpdate,
-      });
-      assert.equal(updateRes, null);
-      // findOne
-      let <%=argv.resourceName%>: Entity<%=argv.resourceNameCapitalize%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>Id } });
-      assert.equal(<%=argv.resourceName%>.name, dataUpdate.name);
-      // delete
-      const deleteRes = await app.bean.executor.performAction('delete', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
-      assert.equal(deleteRes, null);
-      // findOne
-      <%=argv.resourceName%> = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/:id', { params: { id: <%=argv.resourceName%>.id } });
-      assert.equal(<%=argv.resourceName%>, undefined);
-      // logout
-      await app.bean.passport.signout();
     });
   });
 });