cabloy 5.1.108 → 5.1.110

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

@@ -0,0 +1,271 @@
+import type { Locator, Page } from '@playwright/test';
+
+import { expect, test } from '@playwright/test';
+
+const studentResourceUrl =
+  /\/admin\/rest\/resource\/training-student(?:%3A|:|%253A)student(?:[/?#]|$)/;
+
+interface IFieldGeometry {
+  container: {
+    display: string;
+    flexWrap: string;
+    left: number;
+    right: number;
+  };
+  field: {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+  };
+}
+
+function collectPageErrors(page: Page) {
+  const errors: Error[] = [];
+  page.on('pageerror', error => {
+    errors.push(error);
+  });
+  return errors;
+}
+
+async function loginAsAdmin(page: Page) {
+  await page.goto('/admin/', { waitUntil: 'load' });
+  if (page.url().includes('/admin/login')) {
+    await page.getByPlaceholder('Your Username').fill('admin');
+    await page.getByPlaceholder('Your Password').fill('123456');
+    await expect(page.getByPlaceholder('Please input captcha')).not.toHaveValue('');
+    await page.getByRole('button', { name: 'Login', exact: true }).click();
+    await expect(page).not.toHaveURL(/\/admin\/login(?:\?|$)/);
+  }
+
+  await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'admin');
+}
+
+function waitForStudentSelect(page: Page) {
+  return page.waitForResponse(response => {
+    const url = new URL(response.url());
+    return (
+      response.request().method() === 'GET' &&
+      response.ok() &&
+      url.pathname === '/api/training/student' &&
+      !response.request().headers()['x-vona-openapi-schema']
+    );
+  });
+}
+
+async function getFieldGeometry(locator: Locator): Promise<IFieldGeometry> {
+  return locator.evaluate(element => {
+    const field = element.closest('label')?.parentElement;
+    const container = field?.parentElement;
+    if (!field || !container) throw new Error('Could not resolve the filter field layout');
+
+    const fieldRect = field.getBoundingClientRect();
+    const containerRect = container.getBoundingClientRect();
+    const containerStyle = getComputedStyle(container);
+    return {
+      container: {
+        display: containerStyle.display,
+        flexWrap: containerStyle.flexWrap,
+        left: containerRect.left,
+        right: containerRect.right,
+      },
+      field: {
+        top: fieldRect.top,
+        left: fieldRect.left,
+        right: fieldRect.right,
+        bottom: fieldRect.bottom,
+      },
+    };
+  });
+}
+
+async function getFlowGeometry(name: Locator, level: Locator, createdAtStart: Locator) {
+  return Promise.all([
+    getFieldGeometry(name),
+    getFieldGeometry(level),
+    getFieldGeometry(createdAtStart),
+  ]);
+}
+
+function assertVisualOrder(geometry: IFieldGeometry[]) {
+  for (let index = 1; index < geometry.length; index++) {
+    const previous = geometry[index - 1].field;
+    const current = geometry[index].field;
+    expect(
+      current.top > previous.top + 2 ||
+        (Math.abs(current.top - previous.top) <= 2 && current.left > previous.left),
+    ).toBeTruthy();
+  }
+}
+
+test(
+  'ATP-BASIC-SSR-01: anonymous Web HTML hydrates through the default site',
+  { tag: ['@web', '@smoke'] },
+  async ({ page, request }) => {
+    const response = await request.get('/');
+    expect(response.ok()).toBeTruthy();
+    expect((await response.text()).toLowerCase()).not.toContain('data-zova-hydrated');
+
+    const pageErrors = collectPageErrors(page);
+    const documentResponse = await page.goto('/', { waitUntil: 'load' });
+    expect(documentResponse?.ok()).toBeTruthy();
+    await expect(page).toHaveURL(/\/$/);
+    await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'web');
+    await expect(page.getByText('Web: en-us')).toBeVisible();
+    await expect(page.getByText('Dashboard')).toHaveCount(0);
+    await expect(page.locator('body')).toBeVisible();
+    await expect(page).not.toHaveTitle(/error/i);
+    expect(pageErrors).toEqual([]);
+  },
+);
+
+test(
+  'ATP-BASIC-SSR-02: Admin waits for nested hydration before ready',
+  { tag: ['@admin', '@smoke'] },
+  async ({ page, request }) => {
+    const response = await request.get('/admin/', { maxRedirects: 0 });
+    expect(response.status()).toBe(302);
+    const loginPath = response.headers().location;
+    expect(loginPath).toMatch(/^\/admin\/login(?:\?|$)/);
+
+    const loginResponse = await request.get(loginPath!);
+    expect(loginResponse.ok()).toBeTruthy();
+    expect((await loginResponse.text()).toLowerCase()).not.toContain('data-zova-hydrated');
+
+    let releaseRequest: (() => void) | undefined;
+    const requestHeld = new Promise<void>(resolve => {
+      releaseRequest = resolve;
+    });
+    let firstRequest = true;
+    let requestObserved: () => void;
+    const requestBlocked = new Promise<void>(resolve => {
+      requestObserved = resolve;
+    });
+
+    await page.route(/\/admin\/assets\/a-form-[^/]+\.js(?:\?.*)?$/, async route => {
+      if (!firstRequest) {
+        await route.continue();
+        return;
+      }
+      firstRequest = false;
+      requestObserved();
+      await requestHeld;
+      await route.continue();
+    });
+
+    const pageErrors = collectPageErrors(page);
+    const navigation = page.goto('/admin/', { waitUntil: 'load' });
+    try {
+      await requestBlocked;
+      await expect(page).toHaveURL(/\/admin\/login(?:\?|$)/);
+      await expect(page.getByRole('heading', { name: 'Login' })).toBeVisible();
+      await expect(page.locator('html')).not.toHaveAttribute('data-zova-hydrated');
+    } finally {
+      releaseRequest?.();
+    }
+
+    const documentResponse = await navigation;
+    expect(documentResponse?.ok()).toBeTruthy();
+    await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'admin');
+    await expect(page.getByRole('heading', { name: 'Login' })).toBeVisible();
+    await expect(page.getByText('Dashboard')).toHaveCount(0);
+    await expect(page.locator('body')).toBeVisible();
+    expect(pageErrors).toEqual([]);
+    await page.unroute(/\/admin\/assets\/a-form-[^/]+\.js(?:\?.*)?$/);
+  },
+);
+
+test(
+  'ATP-BASIC-FLOW-01: Training Student flow filter wraps and submits queries',
+  { tag: ['@admin', '@flow'] },
+  async ({ page }) => {
+    await page.setViewportSize({ width: 1440, height: 900 });
+    const pageErrors = collectPageErrors(page);
+
+    await loginAsAdmin(page);
+
+    const initialSelect = waitForStudentSelect(page);
+    await page.getByRole('link', { name: 'Student', exact: true }).click();
+    await expect(page).toHaveURL(studentResourceUrl);
+    await initialSelect;
+
+    const name = page.getByLabel('Student Name');
+    const level = page.getByRole('combobox', { name: 'Training Stage' });
+    const createdAt = page.locator('label').filter({ hasText: /^Created At/ });
+    const dates = createdAt.locator('input[type="date"]');
+    const createdAtStart = dates.nth(0);
+    const createdAtEnd = dates.nth(1);
+    const search = page.getByRole('button', { name: 'Search', exact: true });
+    const reset = page.getByRole('button', { name: 'Reset', exact: true });
+
+    await expect(name).toBeVisible();
+    await expect(level).toBeVisible();
+    await expect(dates).toHaveCount(2);
+    await expect(search).toBeVisible();
+    await expect(reset).toBeVisible();
+
+    const wideGeometry = await getFlowGeometry(name, level, createdAtStart);
+    expect(wideGeometry[0].container.display).toBe('flex');
+    expect(wideGeometry[0].container.flexWrap).toBe('wrap');
+    expect(wideGeometry[1].container).toEqual(wideGeometry[0].container);
+    expect(wideGeometry[2].container).toEqual(wideGeometry[0].container);
+    expect(Math.abs(wideGeometry[0].field.top - wideGeometry[1].field.top)).toBeLessThanOrEqual(2);
+    expect(Math.abs(wideGeometry[1].field.top - wideGeometry[2].field.top)).toBeLessThanOrEqual(2);
+    assertVisualOrder(wideGeometry);
+    for (const geometry of wideGeometry) {
+      expect(geometry.field.right).toBeLessThanOrEqual(geometry.container.right + 1);
+    }
+
+    await page.setViewportSize({ width: 700, height: 900 });
+    await expect
+      .poll(
+        async () =>
+          new Set(
+            (await getFlowGeometry(name, level, createdAtStart)).map(item =>
+              Math.round(item.field.top),
+            ),
+          ).size,
+      )
+      .toBeGreaterThan(1);
+
+    const narrowGeometry = await getFlowGeometry(name, level, createdAtStart);
+    assertVisualOrder(narrowGeometry);
+    const viewport = page.viewportSize()!;
+    for (const geometry of narrowGeometry) {
+      expect(geometry.field.left).toBeGreaterThanOrEqual(-1);
+      expect(geometry.field.right).toBeLessThanOrEqual(viewport.width + 1);
+    }
+    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 page.setViewportSize({ width: 1440, height: 900 });
+    await name.fill('Flow E2E');
+    await level.selectOption('2');
+    await createdAtStart.fill('2026-01-10');
+    await createdAtEnd.fill('2026-01-20');
+
+    const searchResponse = waitForStudentSelect(page);
+    await search.click();
+    const searchUrl = new URL((await searchResponse).url());
+    expect(searchUrl.searchParams.get('name')).toBe('Flow E2E');
+    expect(searchUrl.searchParams.get('level')).toBe('2');
+    expect(searchUrl.searchParams.get('createdAt')).toBe('2026-01-10~2026-01-20');
+    await expect(name).toHaveValue('Flow E2E');
+    await expect(level).toHaveValue('2');
+
+    await reset.click();
+    await expect(name).toHaveValue('');
+    await expect(level).toHaveValue('');
+    await expect(createdAtStart).toHaveValue('');
+    await expect(createdAtEnd).toHaveValue('');
+    expect(pageErrors).toEqual([]);
+  },
+);

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

@@ -0,0 +1,61 @@
+import { expect, test } from '@playwright/test';
+
+const privateMarkers = ['cart', 'address', 'order', 'coupon', 'payment'];
+
+function collectPageErrors(page) {
+  const errors: Error[] = [];
+  page.on('pageerror', error => {
+    errors.push(error);
+  });
+  return errors;
+}
+
+test(
+  'ATP-SSR-01: anonymous Commerce HTML is public and hydration completes',
+  { tag: ['@web', '@smoke'] },
+  async ({ page, request }) => {
+    const response = await request.get('/commerce');
+    expect(response.ok()).toBeTruthy();
+    const html = await response.text();
+    const normalizedHtml = html.toLowerCase();
+    expect(normalizedHtml).not.toContain('data-zova-hydrated');
+
+    for (const marker of privateMarkers) {
+      expect(normalizedHtml).not.toContain(`"${marker}"`);
+    }
+
+    const pageErrors = collectPageErrors(page);
+    const documentResponse = await page.goto('/commerce', { waitUntil: 'load' });
+    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.getByText('Dashboard')).toHaveCount(0);
+    await expect(page.locator('body')).toBeVisible();
+    await expect(page).not.toHaveTitle(/error/i);
+    expect(pageErrors).toEqual([]);
+  },
+);
+
+test(
+  'ATP-SSR-02: Commerce Admin is an independent SSR site',
+  { tag: ['@admin', '@smoke'] },
+  async ({ page, request }) => {
+    const response = await request.get('/commerce-admin/', { maxRedirects: 0 });
+    expect(response.status()).toBe(302);
+    const loginPath = response.headers().location;
+    expect(loginPath).toMatch(/^\/commerce-admin\/login(?:\?|$)/);
+
+    const loginResponse = await request.get(loginPath!);
+    expect(loginResponse.ok()).toBeTruthy();
+    expect((await loginResponse.text()).toLowerCase()).not.toContain('data-zova-hydrated');
+
+    const pageErrors = collectPageErrors(page);
+    const documentResponse = await page.goto('/commerce-admin/', { waitUntil: 'load' });
+    expect(documentResponse?.ok()).toBeTruthy();
+    await expect(page).toHaveURL(/\/commerce-admin\/login(?:\?|$)/);
+    await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'commerceAdmin');
+    await expect(page.locator('body')).toBeVisible();
+    expect(pageErrors).toEqual([]);
+  },
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.108",
+  "version": "5.1.110",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -28,16 +28,31 @@
     "vona": "node ./vona/packages-cli/cli/src/bin/vona.ts --projectPath=vona",
     "zova": "node ./zova/packages-cli/cli/src/bin/zova.ts --projectPath=zova",
     "dev": "cd vona && npm run dev",
+    "dev:one": "cd vona && npm run dev:one",
     "dev:zova:admin": "cd zova && npm run dev:ssr:cabloyBasicAdmin",
     "dev:zova:web": "cd zova && npm run dev:ssr:cabloyBasicWeb",
+    "dev:zova:commerce:web": "cd zova && npm run dev:ssr:cabloyCommerce",
+    "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": "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",
+    "build:zova:commerce": "pnpm --dir zova run build:ssr:cabloyCommerceBatch",
+    "build:zova:commerce:web": "pnpm --dir zova run build:ssr:cabloyCommerce && pnpm --dir zova run build:rest:cabloyCommerce",
+    "build:zova:commerce:admin": "pnpm --dir zova run build:ssr:cabloyCommerceAdmin && pnpm --dir zova run build:rest:cabloyCommerceAdmin",
+    "test:e2e:basic": "playwright test --config e2e/config/playwright.basic.config.ts",
+    "test:e2e:basic:web": "playwright test --config e2e/config/playwright.basic.config.ts --grep @web",
+    "test:e2e:basic:admin": "playwright test --config e2e/config/playwright.basic.config.ts --grep @admin",
+    "test:e2e:basic:clean": "node e2e/scripts/testE2eClean.ts basic",
+    "test:e2e:commerce": "playwright test --config e2e/config/playwright.commerce.config.ts",
+    "test:e2e:commerce:web": "playwright test --config e2e/config/playwright.commerce.config.ts --grep @web",
+    "test:e2e:commerce:admin": "playwright test --config e2e/config/playwright.commerce.config.ts --grep @admin",
+    "test:e2e:commerce:clean": "node e2e/scripts/testE2eClean.ts commerce",
     "start": "cd vona && npm run start",
     "start:one": "cd vona && npm run start:one",
     "test": "cd vona && npm run test",
+    "db:reset": "cd vona && npm run db:reset",
     "tsc": "npm run tsc:zova && pnpm --dir vona run tsc",
     "tsc:zova": "pnpm --dir zova run tsc",
     "deps:vona": "pnpm --dir vona run vona :tools:deps",
@@ -63,6 +78,7 @@
   "devDependencies": {
     "@cabloy/lint": "^5.1.27",
     "@cabloy/process-helper": "^3.1.3",
+    "@playwright/test": "^1.61.1",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^22.19.17",
     "husky": "^9.1.7",

package/scripts/upgrade.ts

@@ -6,6 +6,7 @@ import {
   mkdirSync,
   readFileSync,
   rmSync,
+  writeFileSync,
   unlinkSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -55,6 +56,31 @@ const OVERWRITE_DIRS_CABLOY_BASIC: string[] = [
   'zova/src/suite/a-devui',
 ];
 
+const FRAMEWORK_E2E_DIRS_CABLOY_BASIC: string[] = [
+  'e2e/config',
+  'e2e/scripts',
+  'e2e/specs/a-basic',
+  'e2e/specs/a-commerce',
+];
+
+const FRAMEWORK_E2E_SCRIPT_NAMES_CABLOY_BASIC: string[] = [
+  'test:e2e:basic',
+  'test:e2e:basic:web',
+  'test:e2e:basic:admin',
+  'test:e2e:basic:clean',
+  'test:e2e:commerce',
+  'test:e2e:commerce:web',
+  'test:e2e:commerce:admin',
+  'test:e2e:commerce:clean',
+];
+
+const FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC = '@playwright/test';
+
+const OBSOLETE_FRAMEWORK_E2E_SCRIPTS_CABLOY_BASIC: Record<string, string> = {
+  'test:e2e:basic:flow':
+    'playwright test --config e2e/config/playwright.basic.config.ts --grep ATP-BASIC-FLOW-01',
+};
+
 const MERGE_DIRS: string[] = [
   // Claude project assets
   '.claude/commands',
@@ -109,6 +135,12 @@ type LatestPackageInfo = {
   tarballUrl: string;
 };
 
+type PackageJson = {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  scripts?: Record<string, string>;
+};
+
 // --- Helpers ---
 
 // oxlint-disable no-console
@@ -130,6 +162,14 @@ function copyDirectory(src: string, dest: string): void {
   cpSync(src, dest, { recursive: true, filter: shouldCopyPath });
 }
 
+function isCabloyBasic(): boolean {
+  return existsSync(resolve(ROOT_DIR, '__CABLOY_BASIC__'));
+}
+
+function readPackageJson(filePath: string): PackageJson {
+  return JSON.parse(readFileSync(filePath, 'utf-8')) as PackageJson;
+}
+
 function isValidVersion(version: string): boolean {
   return /^\d+\.\d+\.\d+$/.test(version);
 }
@@ -188,6 +228,125 @@ async function extractTarball(tarballPath: string, targetDir: string): Promise<v
   }
 }
 
+function needsBasicE2eReconciliation(): boolean {
+  if (!isCabloyBasic()) return false;
+
+  for (const dir of FRAMEWORK_E2E_DIRS_CABLOY_BASIC) {
+    if (!existsSync(resolve(ROOT_DIR, dir))) return true;
+  }
+
+  const packageJson = readPackageJson(resolve(ROOT_DIR, 'package.json'));
+  for (const name of FRAMEWORK_E2E_SCRIPT_NAMES_CABLOY_BASIC) {
+    const script = packageJson.scripts?.[name];
+    if (!script?.includes('e2e/')) return true;
+  }
+  for (const [name, value] of Object.entries(OBSOLETE_FRAMEWORK_E2E_SCRIPTS_CABLOY_BASIC)) {
+    if (packageJson.scripts?.[name] === value) return true;
+  }
+  return !packageJson.devDependencies?.[FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC];
+}
+
+function mergeFrameworkE2eAssets(dryRun?: boolean): void {
+  if (!isCabloyBasic()) return;
+
+  for (const dir of FRAMEWORK_E2E_DIRS_CABLOY_BASIC) {
+    const src = resolve(TEMP_DIR, dir);
+    const dest = resolve(ROOT_DIR, dir);
+    if (!existsSync(src)) {
+      throw new Error(`Expected framework E2E directory in package: ${dir}`);
+    }
+    if (dryRun) {
+      log(`  [dry-run] Merge framework E2E directory: ${dir}`);
+      continue;
+    }
+    copyDirectory(src, dest);
+  }
+}
+
+function reconcileFrameworkE2ePackageJson(dryRun?: boolean): void {
+  if (!isCabloyBasic()) return;
+
+  const projectPackagePath = resolve(ROOT_DIR, 'package.json');
+  const sourcePackagePath = resolve(TEMP_DIR, 'package.json');
+  const projectPackage = readPackageJson(projectPackagePath);
+  const sourcePackage = readPackageJson(sourcePackagePath);
+  const sourcePlaywrightVersion =
+    sourcePackage.devDependencies?.[FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC];
+  if (!sourcePlaywrightVersion) {
+    throw new Error(
+      `Expected ${FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC} in framework package devDependencies`,
+    );
+  }
+
+  let changed = false;
+  for (const name of FRAMEWORK_E2E_SCRIPT_NAMES_CABLOY_BASIC) {
+    const sourceValue = sourcePackage.scripts?.[name];
+    if (!sourceValue) {
+      throw new Error(`Expected framework E2E script in package.json: ${name}`);
+    }
+    if (projectPackage.scripts?.[name] === sourceValue) continue;
+    changed = true;
+    if (dryRun) {
+      log(`  [dry-run] Set package.json scripts.${name}`);
+    } else {
+      projectPackage.scripts ??= {};
+      projectPackage.scripts[name] = sourceValue;
+    }
+  }
+
+  if (
+    projectPackage.devDependencies?.[FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC] !==
+    sourcePlaywrightVersion
+  ) {
+    changed = true;
+    if (dryRun) {
+      log(
+        `  [dry-run] Set package.json devDependencies.${FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC} = ${sourcePlaywrightVersion}`,
+      );
+    } else {
+      projectPackage.devDependencies ??= {};
+      projectPackage.devDependencies[FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC] =
+        sourcePlaywrightVersion;
+    }
+  }
+
+  if (projectPackage.dependencies?.[FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC]) {
+    changed = true;
+    if (dryRun) {
+      log(
+        `  [dry-run] Remove package.json dependencies.${FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC}`,
+      );
+    } else {
+      delete projectPackage.dependencies[FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC];
+    }
+  }
+
+  for (const [name, value] of Object.entries(OBSOLETE_FRAMEWORK_E2E_SCRIPTS_CABLOY_BASIC)) {
+    const currentValue = projectPackage.scripts?.[name];
+    if (!currentValue) continue;
+    if (currentValue !== value) {
+      log(
+        `  Retain customized obsolete framework E2E script package.json scripts.${name}; remove it manually if no longer needed.`,
+      );
+      continue;
+    }
+    changed = true;
+    if (dryRun) {
+      log(`  [dry-run] Remove obsolete framework E2E script package.json scripts.${name}`);
+    } else {
+      delete projectPackage.scripts?.[name];
+    }
+  }
+
+  if (!changed) {
+    if (dryRun) log('  [dry-run] Framework E2E package entries already match');
+    return;
+  }
+  if (!dryRun) {
+    writeFileSync(projectPackagePath, `${JSON.stringify(projectPackage, null, 2)}\n`);
+  }
+}
+
 // --- Step 1: Pre-flight ---
 
 function preflight(): void {
@@ -250,7 +409,7 @@ async function downloadAndExtract(tarballUrl: string): Promise<void> {
 // --- Step 3: Selective overwrite ---
 
 function selectiveOverwrite(dryRun?: boolean): void {
-  const overwriteDirs = existsSync(resolve(ROOT_DIR, '__CABLOY_BASIC__'))
+  const overwriteDirs = isCabloyBasic()
     ? [...OVERWRITE_DIRS, ...OVERWRITE_DIRS_CABLOY_BASIC]
     : OVERWRITE_DIRS;
 
@@ -292,6 +451,9 @@ function selectiveOverwrite(dryRun?: boolean): void {
     rmSync(dest, { recursive: true, force: true });
   }
 
+  // Merge Cabloy Basic framework E2E directories without deleting project-owned paths.
+  mergeFrameworkE2eAssets(dryRun);
+
   // Overwrite files
   for (const file of WHITELIST_FILES) {
     const src = resolve(TEMP_DIR, file);
@@ -348,6 +510,7 @@ async function main(): Promise<void> {
 
   const latestPackageInfo = await fetchLatestPackageInfo();
   const currentVersion = readVersionMarker();
+  const basicE2eIncomplete = needsBasicE2eReconciliation();
 
   if (currentVersion) {
     log(`Current project Cabloy version: ${currentVersion}`);
@@ -361,13 +524,18 @@ async function main(): Promise<void> {
   if (currentVersion) {
     const comparison = compareVersions(currentVersion, latestPackageInfo.version);
     if (comparison === 0) {
-      if (!dryRun) {
+      if (basicE2eIncomplete) {
+        log(
+          `Cabloy is already up to date (current: ${currentVersion}), but the Cabloy Basic E2E baseline is incomplete. Repairing it in this upgrade; no additional upgrade command is required.\n`,
+        );
+      } else if (!dryRun) {
         log(`Cabloy is already up to date (current: ${currentVersion}). Skipping upgrade.`);
         return;
+      } else {
+        log(
+          `Cabloy is already up to date (current: ${currentVersion}). Continuing dry-run to show overwrite plan.\n`,
+        );
       }
-      log(
-        `Cabloy is already up to date (current: ${currentVersion}). Continuing dry-run to show overwrite plan.\n`,
-      );
     } else if (comparison > 0) {
       throw new Error(
         `Project Cabloy version ${currentVersion} is newer than npm latest ${latestPackageInfo.version}. Aborting upgrade.`,
@@ -390,12 +558,19 @@ async function main(): Promise<void> {
     selectiveOverwrite(dryRun);
     log('');
 
-    // 4. Run init
+    // 4. Reconcile Cabloy Basic framework E2E manifest entries
+    if (isCabloyBasic()) {
+      log('Reconciling framework-owned E2E package entries...');
+      reconcileFrameworkE2ePackageJson(dryRun);
+      log('');
+    }
+
+    // 5. Run init
     log('Running npm run init...');
     runInit(dryRun, latestPackageInfo.version);
     log('');
 
-    // 5. Run init:test-data
+    // 6. Run init:test-data
     log('Running npm run init:test-data...');
     runInitTestData(dryRun);
     log('');

package/test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "passed",
+  "failedTests": []
+}

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

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