cabloy 5.1.112 → 5.1.113

package/.cabloy-version

@@ -1 +1 @@
-5.1.112
+5.1.113

package/.claude/skills/cabloy-backend-scaffold/SKILL.md

@@ -172,6 +172,8 @@ For the canonical distinction, read [Backend Foundation](../../../cabloy-docs/ba
 
 ### Verification
 
+For persisted test data, classify each record as a durable module seed or a test-local fixture. Durable seed data belongs in the owning module's `meta.version.ts` `seed()` hook, runs from a newly recreated managed database, and is read-only to tests; test-local resources must be tracked and deleted in `finally` in reverse dependency order.
+
 Check whether the feature needs:
 
 - unit tests

package/.claude/skills/cabloy-backend-scaffold/references/follow-up-checklist.md

@@ -35,6 +35,15 @@ After generating or extending a backend thread, check which follow-up layers app
 - add a warm-query → mutate-source → repeat-query regression test for each new dependency path; read [Vona Cross-Model Query-Cache Dependencies](../../../../.docs-internal/architecture/vona-cross-model-query-cache-dependencies.md) for the source-backed decision rules
 - transaction behavior
 
+## Test resource lifecycle follow-up
+
+- classify persisted test data as either an owning-module durable seed or a test-local fixture
+- create durable test or local-development baseline data in the owning module's `meta.version.ts` `seed()` hook; this managed path starts from a newly recreated database
+- treat durable seed data as read-only in tests; create an independent fixture when a scenario needs mutation
+- retain exact IDs or entities for every test-local persisted resource and delete them from `finally`
+- delete joins, children, derived records, and other dependents before their owners, in the same active tenant/instance scope
+- do not use unscoped, timestamp-, prefix-, or broad business-condition deletion when an exact test-owned identity is available
+
 ## Module composition and dependency intent
 
 - target module is already composed into the application when code uses cross-module scope lookup

package/.github/workflows/playwright-e2e.yml

@@ -4,7 +4,7 @@ on:
     branches:
       - main
 jobs:
-  test:
+  basic-e2e:
     runs-on: ubuntu-latest
     env:
       DATABASE_DEFAULT_CLIENT: sqlite3
@@ -28,6 +28,38 @@ jobs:
         run: npx playwright install --with-deps chromium
       - name: run Basic E2E baseline
         run: npm run test:e2e:basic:clean
+      - name: upload Playwright artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts-basic
+          path: |
+            playwright-report/
+            test-results/
+          if-no-files-found: ignore
+
+  commerce-e2e:
+    runs-on: ubuntu-latest
+    env:
+      DATABASE_DEFAULT_CLIENT: sqlite3
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
+    services:
+      redis:
+        image: redis:latest
+        ports:
+          - 6379:6379
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+      - uses: pnpm/action-setup@v5
+        with:
+          version: 11.5.2
+      - name: init
+        run: npm run init
+      - name: install Chromium
+        run: npx playwright install --with-deps chromium
       - name: build Commerce Zova artifacts
         run: npm run build:zova:commerce
       - name: synchronize Vona dependencies
@@ -38,7 +70,7 @@ jobs:
         if: failure()
         uses: actions/upload-artifact@v4
         with:
-          name: playwright-artifacts
+          name: playwright-artifacts-commerce
           path: |
             playwright-report/
             test-results/

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

@@ -34,6 +34,14 @@ jobs:
           version: 11.5.2
       - name: init
         run: npm run init
+      - name: run Commerce stock contention gate
+        run: >-
+          TEST_CONCURRENCY=false DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test --
+          commerce-trade/test/stockBalance.test.ts
+          commerce-trade/test/stockReservation.test.ts
+          commerce-trade/test/stockAudit.test.ts
+          --flavor=normal
+        working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=pg npm run test
         working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=pg npm run build -- --flavor=ci

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 5.1.113
+
+### Features
+
+- Update application capabilities and workflows.
+
+### Improvements
+
+- Rename the version test lifecycle to the seed lifecycle.
+- Run Commerce end-to-end tests independently in CI.
+- Strengthen Commerce catalog, stock balance, and stock reservation test coverage.
+- Record Commerce stock verification and Phase 20 CI evidence.
+
 ## 5.1.112
 
 ### Features

package/CLAUDE.md

@@ -72,6 +72,8 @@ Before inventing a custom implementation path:
 - In Vona, a tenant corresponds to an instance. Ordinary resource-model CRUD is automatically scoped to the active instance; treat records absent from that scope as absent, and do not use raw cross-instance probes merely to choose between `403` and not-found behavior. Model future multi-merchant boundaries explicitly inside an instance.
 - Model cross-Model query-cache dependencies as one directed, acyclic `modelsClear` / `modelsClearedBy` graph, and verify source mutations refresh warmed dependent queries; read `.docs-internal/architecture/vona-cross-model-query-cache-dependencies.md` before designing a nontrivial graph.
 - For `@Api.field(...)` and related schemaLike composition, framework guards now preserve previously attached OpenAPI metadata across schema rebuilds, but structure-shaping schemaLike is still order-sensitive. Treat `v.object(...)`, `v.array(...)`, `v.optional()`, `v.nullable()`, `v.default(...)`, and preprocess/transform wrappers as structure-shaping; keep the final structure-defining schemaLike last and verify emitted schema/OpenAPI output after such edits.
+- Unit tests must delete every test-owned persisted resource in `finally`, using precise owned identities and reverse dependency order.
+- Shared durable test or local-development fixtures must be created through the owning module's `meta.version.ts` `seed()` hook and treated as read-only by tests; the managed seed path starts from a newly recreated database rather than repeating against one database.
 
 ## Verification expectations
 

package/cabloy-docs/backend/migration-and-changes.md

@@ -73,19 +73,19 @@ Three migration scenarios are defined:
 | -------- | ------------------------------------------------ |
 | `update` | schema evolution such as tables and fields       |
 | `init`   | instance- or tenant-specific initialization data |
-| `test`   | test-only data for the test environment          |
+| `seed`   | shared baseline data for the test environment    |
 
 This split is one of the most important Vona migration ideas because it separates:
 
 - structural change
 - initialization logic
-- test data setup
+- shared baseline data setup
 
 A practical generated-thread interpretation is:
 
 - `update` follows schema and entity/model evolution
 - `init` follows instance-aware initialization needs introduced by the backend feature
-- `test` keeps the generated or refined contract easy to verify under the test lifecycle
+- `seed` provides shared baseline data while the application starts in test mode
 
 ## Update: schema migration
 
@@ -128,23 +128,27 @@ export class MetaVersion extends BeanBase implements IMetaVersionInit {
 
 The important point is that initialization can run per instance or tenant, which keeps tenant data isolated.
 
-## Test: test-only data
+## Seed: test-environment baseline data
 
 Representative pattern:
 
 ```typescript
 @Meta()
-export class MetaVersion extends BeanBase implements IMetaVersionTest {
-  async test() {
+export class MetaVersion extends BeanBase implements IMetaVersionSeed {
+  async seed() {
     await this.scope.model.student.insert({
       name: 'Jimmy',
-      description: 'Only used in unit test',
+      description: 'Shared test-environment baseline data',
     });
   }
 }
 ```
 
-This is valuable because test data becomes part of the structured migration lifecycle instead of being scattered across unrelated setup code.
+This is valuable because shared baseline data becomes part of the structured version lifecycle instead of being scattered across unrelated setup code.
+
+Vona invokes `seed()` while the application starts in test mode. Use it for durable baseline fixtures shared by multiple tests, E2E tests, or the managed local-development test-data workflow. The seed path starts from a newly recreated managed database; it is not a repeatable, same-database data-import mechanism.
+
+Treat shared `seed()` records as read-only in ordinary tests. A scenario that needs different state must create independent, test-owned data and clean it up in `finally`; it must not mutate or delete the shared baseline. `seed()` remains distinct from `init()`: use `init()` for instance-aware initialization data and reserve `seed()` for shared test-environment baseline data.
 
 ## Version changes across the generated backend thread
 
@@ -185,7 +189,7 @@ When changing backend schema or module initialization behavior, do not only edit
 Also ask:
 
 1. does this change require a `fileVersion` increment?
-2. does `meta.version` need an `update`, `init`, or `test` branch?
+2. does `meta.version` need an `update`, `init`, or `seed` branch?
 3. should the local verification path include `test` or `db:reset`?
 4. does the change affect the CRUD-generated thread or frontend-facing API contract as well?
 

package/cabloy-docs/backend/unit-testing.md

@@ -86,6 +86,31 @@ await app.bean.executor.mockCtx(async () => {
 
 Locale-sensitive variants and additional request-context helpers are also available.
 
+## Persisted fixture lifecycle
+
+Classify persisted test data before creating it:
+
+- use a **test-local fixture** for a single test or scenario;
+- use an owning module's `meta.version.ts` `seed()` hook only for stable baseline data shared across tests or intentionally used by the local-development test-data workflow.
+
+A test owns every persisted resource it creates. Keep the returned entity or exact ID and delete owned records from `finally`, including when an assertion or action fails. Delete dependents before their owners and use the same active tenant/instance context that created them. Do not discover cleanup targets through broad table queries, time-based prefixes, or business conditions when the test already knows the exact identity.
+
+```typescript
+let parentId: number | undefined;
+let childId: number | undefined;
+try {
+  parentId = await createParent();
+  childId = await createChild(parentId);
+
+  // exercise and assert the behavior under test
+} finally {
+  if (childId) await deleteChild(childId);
+  if (parentId) await deleteParent(parentId);
+}
+```
+
+Treat shared `seed()` records as read-only. If a scenario needs to change a record, create a separate test-local fixture instead and clean it up. See [Migration and Changes](/backend/migration-and-changes#seed-test-environment-baseline-data) for the durable seed lifecycle.
+
 ## Working with module scope in tests
 
 Representative pattern:

package/e2e/scripts/startE2eVona.ts

@@ -8,31 +8,69 @@ const child = spawn('npm', ['run', 'dev:one'], {
   stdio: 'inherit',
 });
 
+const gracefulShutdownTimeout = 7000;
+
 let stopping = false;
+let forced = false;
+let shutdownTimer: NodeJS.Timeout | undefined;
 
-function stop() {
-  if (stopping) return;
-  stopping = true;
-  if (process.platform === 'win32') {
-    child.kill('SIGINT');
-  } else if (child.pid) {
-    try {
-      process.kill(-child.pid, 'SIGINT');
-    } catch (error: any) {
-      if (error.code !== 'ESRCH') throw error;
+function finish(code: number) {
+  if (shutdownTimer) {
+    clearTimeout(shutdownTimer);
+    shutdownTimer = undefined;
+  }
+  process.exit(code);
+}
+
+function signalChild(signal: NodeJS.Signals) {
+  if (!child.pid) return;
+  try {
+    if (process.platform === 'win32') {
+      child.kill(signal);
+    } else {
+      process.kill(-child.pid, signal);
+    }
+  } catch (error: any) {
+    if (error.code !== 'ESRCH') {
+      // eslint-disable-next-line
+      console.error(error);
     }
   }
 }
 
+function forceStop() {
+  if (forced) return;
+  forced = true;
+  // eslint-disable-next-line
+  console.error(
+    `E2E Vona process group did not stop within ${gracefulShutdownTimeout}ms; forcing termination: ${child.pid}`,
+  );
+  signalChild('SIGKILL');
+  finish(1);
+}
+
+function stop() {
+  if (stopping) {
+    forceStop();
+    return;
+  }
+  stopping = true;
+  // Vona handles SIGINT, not SIGTERM. Keep this deadline below Playwright's 10-second timeout.
+  signalChild('SIGINT');
+  shutdownTimer = setTimeout(forceStop, gracefulShutdownTimeout);
+  shutdownTimer.unref();
+}
+
 process.on('SIGINT', stop);
 process.on('SIGTERM', stop);
 
 child.on('error', error => {
   // eslint-disable-next-line
   console.error(error);
-  process.exitCode = 1;
+  finish(1);
 });
 
-child.on('exit', code => {
-  process.exitCode = code ?? 1;
+child.on('exit', (code, signal) => {
+  // Playwright waits for this wrapper to exit, not only for Vona's workers to stop.
+  finish(code ?? (signal ? 1 : 0));
 });

package/e2e/specs/a-commerce/commerce.spec.ts

@@ -111,6 +111,7 @@ test(
     const documentResponse = await page.goto(productPath, { waitUntil: 'load' });
     expect(documentResponse?.ok()).toBeTruthy();
     await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'commerce');
+    await expect(page).toHaveURL(productPath);
     await expect(page.getByRole('heading', { name: 'Wireless Headphones' })).toBeVisible();
 
     const cartLink = page.locator('a[href="/commerce/cart"]');

package/e2e/specs/cabloy-basic/basic.spec.ts

@@ -98,6 +98,14 @@ function assertVisualOrder(geometry: IFieldGeometry[]) {
   }
 }
 
+async function getDocumentHorizontalOverflow(page: Page) {
+  return page.evaluate(() => {
+    return (
+      Math.max(document.documentElement.scrollWidth, document.body.scrollWidth) - window.innerWidth
+    );
+  });
+}
+
 test(
   'ATP-BASIC-SSR-01: anonymous Web HTML hydrates through the default site',
   { tag: ['@web', '@smoke'] },
@@ -217,6 +225,8 @@ test(
     }
 
     await page.setViewportSize({ width: 700, height: 900 });
+    const drawer = page.locator('.drawer').first();
+    await expect(drawer).not.toHaveClass(/\bdrawer-open\b/);
     await expect
       .poll(
         async () =>
@@ -238,15 +248,10 @@ test(
     const createdAtEndBox = await createdAtEnd.boundingBox();
     expect(createdAtEndBox).not.toBeNull();
     expect(createdAtEndBox!.x + createdAtEndBox!.width).toBeLessThanOrEqual(viewport.width + 1);
-    await expect
-      .poll(() =>
-        page.evaluate(
-          () => document.documentElement.scrollWidth - document.documentElement.clientWidth,
-        ),
-      )
-      .toBeLessThanOrEqual(1);
+    await expect.poll(() => getDocumentHorizontalOverflow(page)).toBeLessThanOrEqual(1);
 
     await page.setViewportSize({ width: 1440, height: 900 });
+    await expect(drawer).toHaveClass(/\bdrawer-open\b/);
     await name.fill('Flow E2E');
     await level.selectOption('2');
     await createdAtStart.fill('2026-01-10');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.112",
+  "version": "5.1.113",
   "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.130",
+  "version": "1.1.131",
   "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.128",
+  "version": "1.1.129",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

package/vona/packages-cli/cli-set-api/src/lib/bean/cli.bin.test.ts

@@ -77,15 +77,12 @@ export class CliBinTest extends BeanCliBase {
       patterns.join(','),
     ]);
     // args = args.concat(['--experimental-transform-types', getImportEsm(), testFile, projectPath, (!!argv.coverage).toString(), patterns.join(',')]);
-    // ignore error special in windows
-    await catchError(() => {
-      return this.helper.spawnExe({
-        cmd: 'node',
-        args,
-        options: {
-          cwd: projectPath,
-        },
-      });
+    await this.helper.spawnExe({
+      cmd: 'node',
+      args,
+      options: {
+        cwd: projectPath,
+      },
     });
   }
 

package/vona/packages-cli/cli-set-api/toolsIsolate/test.ts

@@ -63,9 +63,27 @@ async function testRun(projectPath: string, coverage: boolean, patterns: string[
   ];
   // app
   const app: VonaApplication = await createGeneralApp(projectPath);
-  // concurrency
-  const concurrency = await prepareConcurrency(app);
-  return new Promise(resolve => {
+  let testError: unknown;
+  let closeError: unknown;
+  let closePromise: Promise<void> | undefined;
+  const closeApplication = async () => {
+    const [_, error] = await catchError(() => app.close());
+    closeError = error;
+    // handles
+    if (process.env.TEST_WHYISNODERUNNING === 'true') {
+      await sleep(2000);
+      const handles = (process as any)._getActiveHandles();
+      if (handles.length > 3) {
+        whyIsNodeRunning();
+      }
+    }
+  };
+  const closeApplicationOnce = () => {
+    return (closePromise ??= closeApplication());
+  };
+  try {
+    // concurrency
+    const concurrency = await prepareConcurrency(app);
     const testStream = run({
       isolation: 'none',
       concurrency,
@@ -80,27 +98,12 @@ async function testRun(projectPath: string, coverage: boolean, patterns: string[
       .on('test:coverage', data => {
         outputCoverageReport(data.summary.totals);
       })
-      .on('test:summary', async () => {
-        resolve(undefined);
-      })
-      .on('test:pass', async t => {
+      .on('test:pass', t => {
         if (t.name === '---done---') {
-          const [_, err] = await catchError(() => {
-            return app.close();
-          });
-          if (err) {
-            console.error(err);
-          }
-          // handles
-          if (process.env.TEST_WHYISNODERUNNING === 'true') {
-            await sleep(2000);
-            const handles = (process as any)._getActiveHandles();
-            if (handles.length > 3) {
-              whyIsNodeRunning();
-            }
-          }
+          void closeApplicationOnce();
         }
       });
+    const summaryPromise = waitForTestSummary(testStream);
     if (coverage) {
       const reporterDir = path.join(projectPath, 'coverage');
       fse.ensureDirSync(reporterDir);
@@ -109,6 +112,32 @@ async function testRun(projectPath: string, coverage: boolean, patterns: string[
     } else {
       testStream.compose(spec).pipe(process.stdout);
     }
+
+    const summarySuccess = await summaryPromise;
+    if (!summarySuccess) {
+      throw new Error('node:test reported failed tests');
+    }
+  } catch (error) {
+    testError = error;
+  } finally {
+    await closeApplicationOnce();
+  }
+  if (testError) {
+    if (closeError) console.error(closeError);
+    throw toError(testError);
+  }
+  if (closeError) {
+    throw toError(closeError);
+  }
+}
+
+function toError(error: unknown) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function waitForTestSummary(testStream: ReturnType<typeof run>) {
+  return new Promise<boolean>((resolve, reject) => {
+    testStream.once('test:summary', summary => resolve(summary.success)).once('error', reject);
   });
 }
 

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

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