cabloy 5.1.111 → 5.1.112

package/cabloy-docs/reference/repo-scripts.md

@@ -1,12 +1,14 @@
 # Repo Scripts
 
-Use this page when you need the compact lookup surface for the shared root scripts exposed by the Cabloy Basic monorepo.
+Use this page as the compact lookup surface for root scripts in Cabloy Basic and Cabloy Start.
 
 For the broader Reference landing page, see [Reference Introduction](/reference/introduction).
 
-The root `package.json` is the first reference point for shared monorepo workflows.
+Always start with the active repository's root `package.json`. Cabloy Basic is the public generated-project baseline; Cabloy Start is the licensed private repository and has its own root command surface.
 
-## Current shared entrypoints in Cabloy Basic
+## Cabloy Basic entrypoints
+
+Cabloy Basic exposes these shared root scripts:
 
 - `npm run init`
 - `npm run upgrade`
@@ -14,17 +16,23 @@ The root `package.json` is the first reference point for shared monorepo workflo
 - `npm run vona`
 - `npm run zova`
 - `npm run dev`
+- `npm run dev:one`
 - `npm run dev:zova:admin`
 - `npm run dev:zova:web`
 - `npm run dev:zova:commerce:web`
 - `npm run dev:zova:commerce:admin`
 - `npm run build`
 - `npm run build:zova`
+- `npm run build:zova:all`
+- `npm run build:zova:admin`
+- `npm run build:zova:web`
 - `npm run build:zova:commerce`
 - `npm run build:zova:commerce:web`
 - `npm run build:zova:commerce:admin`
 - `npm run start`
+- `npm run start:one`
 - `npm run test`
+- `npm run db:reset`
 - `npm run test:e2e:basic`
 - `npm run test:e2e:basic:web`
 - `npm run test:e2e:basic:admin`
@@ -38,21 +46,87 @@ The root `package.json` is the first reference point for shared monorepo workflo
 - `npm run docs:build`
 - `npm run docs:preview`
 
+`npm run init` prepares all Cabloy Basic SSR and REST artifacts with `npm run build:zova:all`, which sequentially builds the Basic and Commerce flavor batches before Vona initialization. Use `build:zova` or `build:zova:commerce` for focused artifact refreshes; use `build:zova:all` only when every shipped Basic flavor must be prepared.
+
+## Cabloy Start entrypoints
+
+Cabloy Start exposes the equivalent Start repository surface:
+
+- `npm run init`
+- `npm run upgrade`
+- `npm run upgrade:dry-run`
+- `npm run vona`
+- `npm run zova`
+- `npm run dev`
+- `npm run dev:one`
+- `npm run dev:zova:admin`
+- `npm run dev:zova:web`
+- `npm run build`
+- `npm run build:zova`
+- `npm run build:zova:admin`
+- `npm run build:zova:web`
+- `npm run start`
+- `npm run start:one`
+- `npm run test`
+- `npm run db:reset`
+- `npm run test:e2e:start`
+- `npm run test:e2e:start:web`
+- `npm run test:e2e:start:admin`
+- `npm run test:e2e:start:clean`
+- `npm run tsc`
+
+Cabloy Start does not expose Basic Commerce or root documentation wrappers.
+
 ## Upgrade
 
-Run `npm run upgrade:dry-run` before `npm run upgrade` to inspect the framework files and root manifest entries that an upgrade would synchronize. In Cabloy Basic, the upgrade owns `e2e/config/`, `e2e/scripts/`, `e2e/specs/a-basic/`, and `e2e/specs/a-commerce/`, together with the framework `test:e2e:*` scripts and `@playwright/test` development dependency. Keep project browser tests outside those reserved paths; see [Fullstack Quickstart](/fullstack/quickstart) for the upgrade bootstrap behavior.
+Run `npm run upgrade:dry-run` before `npm run upgrade` to inspect framework files and root manifest entries that an upgrade would synchronize.
+
+### Cabloy Basic public projects
+
+Basic upgrade owns these browser baseline paths:
+
+```text
+e2e/config/
+e2e/scripts/
+e2e/specs/cabloy-basic/
+e2e/specs/a-commerce/
+```
+
+It also reconciles the framework Basic and Commerce `test:e2e:*` scripts and `@playwright/test` development dependency. Keep project browser tests outside those reserved paths. The upgrader merges framework baseline directories without deleting project-owned paths and can repair an incomplete Basic E2E baseline even when the framework version marker is already current.
+
+### Cabloy Start private repository
+
+The Start E2E baseline is maintained in the private repository:
+
+```text
+e2e/config/
+e2e/scripts/
+e2e/specs/cabloy-start/
+```
+
+The public-package upgrade flow does not source or reconcile the Start baseline, its `test:e2e:start*` scripts, or `@playwright/test`. Keep project browser tests outside the baseline paths, for example under `e2e/specs/my-project/`.
 
 ## SSR browser checks
 
-Both E2E families use the same command structure:
+The suites use this command family:
 
 - `test:e2e:<suite>` runs every browser scenario in the suite.
-- `test:e2e:<suite>:web` and `test:e2e:<suite>:admin` are durable surface shortcuts that select `@web` and `@admin` tests.
-- `test:e2e:<suite>:clean` resets managed local test state, starts one development Vona worker, then runs the suite or a Playwright-filtered subset.
+- `test:e2e:<suite>:web` and `test:e2e:<suite>:admin` select `@web` and `@admin` scenarios.
+- `test:e2e:<suite>:clean` resets managed local state, starts one development Vona worker, then runs the suite or a Playwright-filtered subset.
+
+The managed `:clean` runner requires port `7102` to be available. It owns the suite config and local lifecycle: it resets the database, and Playwright starts and stops `npm run dev:one`. It accepts normal Playwright selection and reporting options, but rejects external base URLs, `--config`, and positional spec paths. Use `--grep` or `--grep-invert` to narrow the run.
+
+Pass Playwright options after npm's `--` delimiter. `@web` and `@admin` are stable surface tags. Purpose tags depend on the suite: current scenarios use `@smoke`, while the Basic suite also uses `@flow`. ATP IDs remain in titles for exact evidence and failure reruns.
 
-Use native Playwright tags for scenario categories rather than adding a root script for each feature. Every framework scenario uses one surface tag (`@web` or `@admin`) and one purpose tag when applicable (`@smoke` or `@flow`). ATP IDs remain in titles for exact evidence and failure reruns.
+### Cabloy Basic and Commerce
 
-Pass Playwright options after npm's `--` delimiter:
+The Basic suite exercises Web at `/` and Admin at `/admin` through Vona's SSR dispatcher. Prepare fresh SSR and REST artifacts explicitly when frontend output has changed:
+
+```bash
+npm run build:zova
+npm run deps:vona
+npm run test:e2e:basic:clean
+```
 
 ```bash
 # Exact acceptance scenario
@@ -66,16 +140,6 @@ npm run test:e2e:basic:clean -- --grep @admin
 npm run test:e2e:basic:clean -- --grep '(?=.*@admin)(?=.*@flow)'
 ```
 
-The managed `:clean` runner owns its suite config and local lifecycle. It accepts normal Playwright selection and reporting options, but does not accept `--config` or positional spec paths. Use `--grep` or `--grep-invert` to narrow the run. It rejects an external base URL rather than resetting or starting an externally managed target.
-
-The Basic suite exercises Web at `/` and Admin at `/admin` through Vona's SSR dispatcher. Prepare fresh Basic SSR artifacts explicitly when frontend SSR output has changed:
-
-```bash
-npm run build:zova
-npm run deps:vona
-npm run test:e2e:basic:clean
-```
-
 For an externally managed Basic target, set `BASIC_E2E_BASE_URL` and use aggregate, surface, or forwarded-tag commands. These commands do not reset, start, stop, or rebuild the target:
 
 ```bash
@@ -100,13 +164,34 @@ COMMERCE_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:commerce:web
 COMMERCE_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:commerce -- --grep @smoke
 ```
 
-Browser commands consume existing SSR and REST artifacts; they never rebuild them. Install Chromium once when needed with `npx playwright install chromium`.
+### Cabloy Start
 
-## Edition-sensitive note
+The Start suite exercises Web at `/` and Admin at `/admin` through Vona's SSR dispatcher. Prepare current Start artifacts before a managed local run:
 
-Cabloy Start keeps the same high-level pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own SSR site baselines and project assets in the licensed private repository.
+```bash
+npm run build:zova
+npm run deps:vona
+npm run test:e2e:start:clean
+```
 
-When documenting or automating flavor-specific commands, always confirm the active repo first.
+```bash
+# Exact acceptance scenario
+npm run test:e2e:start -- --grep ATP-START-FLOW-01
+
+# Category or surface selection
+npm run test:e2e:start:clean -- --grep @smoke
+npm run test:e2e:start:clean -- --grep @admin
+```
+
+For an externally managed Start target, set `START_E2E_BASE_URL` and use matching aggregate, surface, or forwarded-tag commands. The target owner is responsible for data, cache, and artifact freshness:
+
+```bash
+START_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:start
+START_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:start:admin
+START_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:start -- --grep @web
+```
+
+Browser commands consume existing SSR and REST artifacts; they never rebuild them. Install Chromium once when needed with `npx playwright install chromium`.
 
 ## Read together with
 

package/e2e/scripts/e2e.ts

@@ -12,7 +12,7 @@ const e2eSuites = {
   basic: {
     externalBaseUrlEnv: 'BASIC_E2E_BASE_URL',
     configFile: resolve(E2E_CONFIG_DIR, 'playwright.basic.config.ts'),
-    testDir: resolve(E2E_SPECS_DIR, 'a-basic'),
+    testDir: resolve(E2E_SPECS_DIR, 'cabloy-basic'),
     readinessPath: '/',
   },
   commerce: {

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

@@ -29,7 +29,7 @@ test(
     expect(documentResponse?.ok()).toBeTruthy();
     await expect(page).toHaveURL(/\/commerce(?:\/|$)/);
     await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'commerce');
-    await expect(page.getByText('Web: en-us')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Commerce catalogue' })).toBeVisible();
     await expect(page.getByText('Dashboard')).toHaveCount(0);
     await expect(page.locator('body')).toBeVisible();
     await expect(page).not.toHaveTitle(/error/i);
@@ -37,6 +37,129 @@ test(
   },
 );
 
+test(
+  'Commerce catalogue: public sellable inventory renders after hydration',
+  { tag: ['@web', '@flow'] },
+  async ({ page }) => {
+    const pageErrors = collectPageErrors(page);
+    const response = await page.goto('/commerce', { waitUntil: 'load' });
+    expect(response?.ok()).toBeTruthy();
+    await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'commerce');
+    await expect(page.getByRole('heading', { name: 'Commerce catalogue' })).toBeVisible();
+    await expect(page.getByRole('link', { name: 'Wireless Headphones' })).toBeVisible();
+    await expect(page.getByText('24 available')).toBeVisible();
+    await page.getByRole('link', { name: 'Wireless Headphones' }).click();
+    await expect(page).toHaveURL(/\/commerce\/product\/\d+(?:\/|$)/);
+    await expect(page.getByRole('heading', { name: 'Wireless Headphones' })).toBeVisible();
+    await expect(page.getByText('HPH-BLK')).toBeVisible();
+    expect(pageErrors).toEqual([]);
+  },
+);
+
+test(
+  'Commerce catalogue: localized Product navigation preserves locale',
+  { tag: ['@web', '@flow'] },
+  async ({ page, request }) => {
+    const localizedPath = '/commerce/zh-cn';
+    const response = await request.get(localizedPath);
+    expect(response.ok()).toBeTruthy();
+    const html = await response.text();
+    expect(html.toLowerCase()).not.toContain('data-zova-hydrated');
+    expect(html).toContain('商品目录');
+    expect(html).toContain('当前价格和库存以结算时确认为准。');
+
+    const pageErrors = collectPageErrors(page);
+    const documentResponse = await page.goto(localizedPath, { waitUntil: 'load' });
+    expect(documentResponse?.ok()).toBeTruthy();
+    await expect(page).toHaveURL(/\/commerce\/zh-cn(?:\/|$)/);
+    await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'commerce');
+    await expect(page.getByRole('heading', { name: '商品目录' })).toBeVisible();
+    await expect(page.getByText('当前价格和库存以结算时确认为准。')).toBeVisible();
+    await expect(page.getByText('库存 24 件')).toBeVisible();
+
+    const productLink = page.getByRole('link', { name: 'Wireless Headphones' });
+    await expect(productLink).toHaveAttribute('href', /\/commerce\/zh-cn\/product\/\d+$/);
+    const productPath = await productLink.getAttribute('href');
+    const productResponse = await request.get(productPath!);
+    expect(productResponse.ok()).toBeTruthy();
+    expect((await productResponse.text()).toLowerCase()).not.toContain('data-zova-hydrated');
+    await productLink.click();
+    await expect(page).toHaveURL(/\/commerce\/zh-cn\/product\/\d+(?:\/|$)/);
+    await expect(page.getByRole('heading', { name: 'Wireless Headphones' })).toBeVisible();
+    await expect(page.getByText('HPH-BLK')).toBeVisible();
+    await expect(page.getByText('库存 24 件')).toBeVisible();
+    await expect(page.getByRole('link', { name: '购物车' })).toHaveAttribute(
+      'href',
+      '/commerce/zh-cn/cart',
+    );
+    expect(pageErrors).toEqual([]);
+  },
+);
+
+test(
+  'Commerce Product: Cart badge keeps SSR initial render neutral',
+  { tag: ['@web', '@cart'] },
+  async ({ page, request }) => {
+    const productPath = '/commerce/product/1';
+    const productResponse = await request.get(productPath);
+    expect(productResponse.ok()).toBeTruthy();
+    const productHtml = await productResponse.text();
+    expect(productHtml.toLowerCase()).not.toContain('data-zova-hydrated');
+    expect(productHtml).toContain('>Cart<!----></a>');
+
+    const pageErrors = collectPageErrors(page);
+    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.getByRole('heading', { name: 'Wireless Headphones' })).toBeVisible();
+
+    const cartLink = page.locator('a[href="/commerce/cart"]');
+    await expect(cartLink).toHaveCount(1);
+    await expect(cartLink.locator('.badge')).toHaveCount(0);
+    expect(pageErrors).toEqual([]);
+  },
+);
+
+test(
+  'Commerce Address: cookie-disabled SSR renders a neutral protected entry',
+  { tag: ['@web', '@cart'] },
+  async ({ page, request }) => {
+    const path = '/commerce/address';
+    const routePath = '/address';
+    const response = await request.get(path, { maxRedirects: 0 });
+    expect(response.status()).toBe(200);
+    expect(response.headers().location).toBeUndefined();
+    expect((await response.text()).toLowerCase()).not.toContain('data-zova-hydrated');
+
+    const pageErrors = collectPageErrors(page);
+    const documentResponse = await page.goto(path, { waitUntil: 'load' });
+    expect(documentResponse?.ok()).toBeTruthy();
+    await expect(page).toHaveURL(/\/commerce\/login\?(?:.*&)?returnTo=/);
+    const loginUrl = new URL(page.url());
+    expect(loginUrl.searchParams.getAll('returnTo')).toEqual([routePath]);
+    await expect(page.getByRole('heading', { name: 'Login' })).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Addresses' })).toHaveCount(0);
+    expect(pageErrors).toEqual([]);
+  },
+);
+
+test(
+  'Commerce Cart: anonymous browser is redirected to login',
+  { tag: ['@web', '@cart'] },
+  async ({ page, request }) => {
+    const path = '/commerce/cart';
+    const response = await request.get(path);
+    expect(response.ok()).toBeTruthy();
+    expect((await response.text()).toLowerCase()).not.toContain('data-zova-hydrated');
+
+    const pageErrors = collectPageErrors(page);
+    const documentResponse = await page.goto(path, { waitUntil: 'load' });
+    expect(documentResponse?.ok()).toBeTruthy();
+    await expect(page).toHaveURL(/\/commerce\/login\?(?:.*&)?returnTo=/);
+    expect(pageErrors).toEqual([]);
+  },
+);
+
 test(
   'ATP-SSR-02: Commerce Admin is an independent SSR site',
   { tag: ['@admin', '@smoke'] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.111",
+  "version": "5.1.112",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -35,6 +35,7 @@
     "dev:zova:commerce:admin": "cd zova && npm run dev:ssr:cabloyCommerceAdmin",
     "build": "npm run build:zova && pnpm --dir vona run build",
     "build:docker": "npm run build:zova && pnpm --dir vona run build:docker",
+    "build:zova:all": "npm run build:zova && npm run build:zova:commerce",
     "build:zova": "pnpm --dir zova run build:ssr:cabloyBasicBatch",
     "build:zova:admin": "pnpm --dir zova run build:ssr:cabloyBasicAdmin && pnpm --dir zova run build:rest:cabloyBasicAdmin",
     "build:zova:web": "pnpm --dir zova run build:ssr:cabloyBasicWeb && pnpm --dir zova run build:rest:cabloyBasicWeb",

package/scripts/init.ts

@@ -260,18 +260,12 @@ function initZova(): void {
   exec('npm run zova :tools:deps');
 }
 
-// --- Step E: buildSsrCabloyBasicStartBatch ---
+// --- Step E: buildSsrZovaAll ---
 
-function buildSsrCabloyBasicStartBatch(): void {
-  if (existsSync(resolve(ROOT_DIR, '__CABLOY_BASIC__'))) {
-    // eslint-disable-next-line
-    console.log('[init] Building zova SSR cabloyBasicBatch...');
-    exec('pnpm run build:ssr:cabloyBasicBatch', ZOVA_DIR);
-  } else if (existsSync(resolve(ROOT_DIR, '__CABLOY_START__'))) {
-    // eslint-disable-next-line
-    console.log('[init] Building zova SSR cabloyStartBatch...');
-    exec('pnpm run build:ssr:cabloyStartBatch', ZOVA_DIR);
-  }
+function buildSsrZovaAll(): void {
+  // eslint-disable-next-line
+  console.log('[init] Building all zova SSR flavors...');
+  exec('npm run build:zova:all');
 }
 
 // --- Step F: cleanupWorkspaceYaml ---
@@ -314,7 +308,7 @@ generateEnvProdLocal();
 generateEnvProdDockerLocal();
 cleanupWorkspaceYaml();
 initZova();
-buildSsrCabloyBasicStartBatch();
+buildSsrZovaAll();
 initVona();
 initCabloyDocs();
 writeVersionMarker();

package/scripts/upgrade.ts

@@ -51,15 +51,17 @@ const OVERWRITE_DIRS: string[] = [
 const OVERWRITE_DIRS_CABLOY_BASIC: string[] = [
   'vona/src/suite/cabloy-basic',
   'vona/src/suite/a-training',
+  'vona/src/suite/a-commerce',
   'zova/src/suite/cabloy-basic',
   'zova/src/suite/a-training',
+  'zova/src/suite/a-commerce',
   'zova/src/suite/a-devui',
 ];
 
 const FRAMEWORK_E2E_DIRS_CABLOY_BASIC: string[] = [
   'e2e/config',
   'e2e/scripts',
-  'e2e/specs/a-basic',
+  'e2e/specs/cabloy-basic',
   'e2e/specs/a-commerce',
 ];
 

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

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