cabloy 5.1.201 → 5.1.203

package/repo-agent-governance/tools/spec-charts/generate-implementation-charts.mjs

@@ -2,12 +2,20 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
 
-import { markdownLines, parseAtpIds, parseProgress, parseWbs } from './spec-parser.mjs';
+import {
+  isPlanningCompleteEligible,
+  isPrerequisiteSatisfied,
+  markdownLines,
+  parseAtpIds,
+  parseProgress,
+  parseWbs,
+} from './spec-parser.mjs';
 export { parseAtpIds, parseProgress, parseWbs } from './spec-parser.mjs';
 
 const STATUS_COLORS = {
   'not-started': 'var(--blue)',
   'in-progress': 'var(--orange)',
+  'planning-complete': 'var(--teal)',
   'implementation-complete': 'var(--violet)',
   'verified': 'var(--aqua)',
   'blocked': 'var(--red)',
@@ -47,6 +55,7 @@ const COPY = {
     statuses: {
       'not-started': 'Not started',
       'in-progress': 'In progress',
+      'planning-complete': 'Planning complete',
       'implementation-complete': 'Implementation complete',
       'verified': 'Verified',
       'blocked': 'Blocked',
@@ -104,6 +113,7 @@ const COPY = {
     statuses: {
       'not-started': '未开始',
       'in-progress': '进行中',
+      'planning-complete': '规划完成',
       'implementation-complete': '实施完成',
       'verified': '已核验',
       'blocked': '受阻',
@@ -248,6 +258,11 @@ export function createChartModel({ readme, wbs, progress, testPlan }) {
     }
     task.recordedStatus = task.status;
     task.status = progressStatus;
+    if (task.status === 'planning-complete' && !isPlanningCompleteEligible(task)) {
+      throw new Error(
+        `${task.id} has planning-complete status without Completion mode: planning-only.`,
+      );
+    }
     if (task.deferred && task.status !== 'deferred') {
       throw new Error(
         `${task.id} is marked deferred in pdp-wbs.md but has progress status ${task.status}.`,
@@ -274,10 +289,10 @@ export function createChartModel({ readme, wbs, progress, testPlan }) {
   };
 }
 
-function style() {
+function style(planningComplete) {
   return `<style>
-    :root { --surface:#fcfcfb;--page:#f9f9f7;--ink:#0b0b0b;--secondary:#52514e;--muted:#898781;--grid:#e1e0d9;--axis:#c3c2b7;--blue:#2a78d6;--orange:#eb6834;--aqua:#1baf7a;--violet:#4a3aa7;--red:#e34948;--yellow:#eda100;--blue-wash:#eaf3fd;--aqua-wash:#e7f7f0; }
-    @media (prefers-color-scheme:dark) { :root { --surface:#1a1a19;--page:#0d0d0d;--ink:#fff;--secondary:#c3c2b7;--muted:#a09f99;--grid:#2c2c2a;--axis:#383835;--blue:#3987e5;--orange:#d95926;--aqua:#199e70;--violet:#9085e9;--red:#e66767;--yellow:#c98500;--blue-wash:#172435;--aqua-wash:#122b23; } }
+    :root { --surface:#fcfcfb;--page:#f9f9f7;--ink:#0b0b0b;--secondary:#52514e;--muted:#898781;--grid:#e1e0d9;--axis:#c3c2b7;--blue:#2a78d6;--orange:#eb6834;${planningComplete ? '--teal:#087f83;' : ''}--aqua:#1baf7a;--violet:#4a3aa7;--red:#e34948;--yellow:#eda100;--blue-wash:#eaf3fd;--aqua-wash:#e7f7f0; }
+    @media (prefers-color-scheme:dark) { :root { --surface:#1a1a19;--page:#0d0d0d;--ink:#fff;--secondary:#c3c2b7;--muted:#a09f99;--grid:#2c2c2a;--axis:#383835;--blue:#3987e5;--orange:#d95926;${planningComplete ? '--teal:#29aeb0;' : ''}--aqua:#199e70;--violet:#9085e9;--red:#e66767;--yellow:#c98500;--blue-wash:#172435;--aqua-wash:#122b23; } }
     .canvas{fill:var(--page)}.card{fill:var(--surface);stroke:var(--grid);stroke-width:1}.title{fill:var(--ink);font-family:Arial,Helvetica,sans-serif;font-size:27px;font-weight:700}.subtitle{fill:var(--secondary);font-family:Arial,Helvetica,sans-serif;font-size:14px}.heading{fill:var(--ink);font-family:Arial,Helvetica,sans-serif;font-size:13px;font-weight:700}.phase{fill:var(--ink);font-family:Arial,Helvetica,sans-serif;font-size:10px;font-weight:700}.task{fill:var(--ink);font-family:Arial,Helvetica,sans-serif;font-size:10px}.small{fill:var(--muted);font-family:Arial,Helvetica,sans-serif;font-size:9px}.caption{fill:var(--secondary);font-family:Arial,Helvetica,sans-serif;font-size:11px}.num{fill:var(--ink);font-family:Arial,Helvetica,sans-serif;font-size:11px;font-weight:700;font-variant-numeric:tabular-nums}.grid{stroke:var(--grid);stroke-width:1;shape-rendering:crispEdges}.axis{stroke:var(--axis);stroke-width:1;shape-rendering:crispEdges}.row:focus{outline:2px solid var(--ink);outline-offset:2px}
   </style>`;
 }
@@ -302,13 +317,13 @@ function renderChartTextLines(className, x, y, lines, lineHeight) {
   return `<text class="${className}" x="${x}" y="${y}">${lines.map((line, lineIndex) => `<tspan x="${x}" dy="${lineIndex ? lineHeight : 0}">${escapeXml(line)}</tspan>`).join('')}</text>`;
 }
 
-function svgDocument(title, desc, body, height, metadata) {
+function svgDocument(title, desc, body, height, metadata, planningComplete = false) {
   return `<?xml version="1.0" encoding="UTF-8"?>
 <svg xmlns="http://www.w3.org/2000/svg" width="1600" height="${height}" viewBox="0 0 1600 ${height}" role="img" aria-labelledby="chart-title chart-desc">
   <title id="chart-title">${escapeXml(title)}</title>
   <desc id="chart-desc">${escapeXml(desc)}</desc>
   <metadata>${escapeXml(metadata)}</metadata>
-  ${style()}
+  ${style(planningComplete)}
   ${body}
 </svg>
 `;
@@ -392,9 +407,12 @@ export function renderGantt(model, suiteName) {
       },
     )
     .join('\n');
-  const completed = new Set(tasks.filter(task => task.status === 'verified').map(task => task.id));
+  const completed = new Set(
+    tasks.filter(task => isPrerequisiteSatisfied(task, task.status)).map(task => task.id),
+  );
   const nextTask = tasks.find(
     task =>
+      task.status !== 'planning-complete' &&
       task.status !== 'verified' &&
       task.status !== 'deferred' &&
       task.status !== 'waived' &&
@@ -418,6 +436,7 @@ export function renderGantt(model, suiteName) {
     body,
     height,
     t.metadata,
+    tasks.some(task => task.status === 'planning-complete'),
   );
 }
 

package/repo-agent-governance/tools/spec-charts/generate-implementation-charts.test.mjs

@@ -152,6 +152,88 @@ test('creates a mixed-status model with deferred scope separated', () => {
   assert.equal(model.activeTasks.length, 2);
   assert.equal(model.deferredTasks.length, 1);
   assert.equal(model.verified, 0);
+  assert.doesNotMatch(renderGantt(model, 'Demo'), /--teal:/);
+});
+
+test('planning completion requires an explicit task mode and preserves verified-only metrics', () => {
+  const wbs = files['pdp-wbs.md'].replace(
+    '#### WBS-10-01: Freeze the baseline',
+    '#### WBS-10-01: Freeze the baseline\n\nCompletion mode: planning-only.',
+  );
+  const progress = files['progress.md'].replace('`not-started`', '`planning-complete`');
+  assert.throws(
+    () =>
+      createChartModel({
+        readme: files['README.md'],
+        wbs: files['pdp-wbs.md'],
+        progress,
+        testPlan: files['test-plan.md'],
+      }),
+    /planning-complete status without Completion mode/,
+  );
+  const model = createChartModel({
+    readme: files['README.md'],
+    wbs,
+    progress,
+    testPlan: files['test-plan.md'],
+  });
+  assert.equal(model.tasks[0].completionMode, 'planning-only');
+  assert.equal(model.verified, 0);
+  const gantt = renderGantt(model, 'Demo');
+  assert.match(gantt, /Planning complete/);
+  assert.match(gantt, /--teal:#087f83/);
+  assert.doesNotMatch(renderBurndown(model, 'Demo'), /--teal:/);
+  assert.match(gantt, /class="caption" x="96" y="195">WBS-20-01: Deliver/);
+  assert.doesNotMatch(gantt, /class="caption" x="96" y="195">WBS-10-01/);
+  assert.match(renderBurndown(model, 'Demo'), />2 remaining · 0 verified</);
+  const blocked = createChartModel({
+    readme: files['README.md'],
+    wbs,
+    progress: progress.replace('`in-progress`', '`blocked`'),
+    testPlan: files['test-plan.md'],
+  });
+  assert.match(renderGantt(blocked, 'Demo'), /No dependency-ready WBS candidate is recorded/);
+  assert.equal(blocked.verified, 0);
+  const chinese = createChartModel({
+    readme: '# 中文规划\n\n完整中文记录。',
+    wbs,
+    progress,
+    testPlan: files['test-plan.md'],
+  });
+  assert.match(renderGantt(chinese, '示例'), /规划完成/);
+  assert.match(renderBurndown(chinese, '示例'), /2 剩余 · 0 已核验/);
+});
+
+test('completion mode must be unique, supported and task-local', () => {
+  const wbs = files['pdp-wbs.md'];
+  for (const value of ['unknown.', '', 'planning-only.\nCompletion mode: planning-only.']) {
+    assert.throws(
+      () => parseWbs(wbs.replace('Tasks:', `Completion mode: ${value}\n\nTasks:`)),
+      /Completion mode/,
+    );
+  }
+  assert.throws(
+    () =>
+      parseWbs(
+        wbs.replace('Dependencies: none.', 'Dependencies: none.\nCompletion mode: planning-only.'),
+      ),
+    /Completion mode must belong to a formal WBS task/,
+  );
+  assert.throws(
+    () => parseWbs(`Completion mode: planning-only.\n${wbs}`),
+    /Completion mode must belong to a formal WBS task/,
+  );
+  const progress = files['progress.md'].replace('`not-started`', '`planning-complete`');
+  assert.throws(
+    () =>
+      createChartModel({
+        readme: files['README.md'],
+        wbs: wbs.replace('Tasks:', 'Status: in-progress.\nCompletion mode: planning-only.\nTasks:'),
+        progress,
+        testPlan: files['test-plan.md'],
+      }),
+    /explicit.*Status in-progress.*planning-complete/,
+  );
 });
 
 test('selects the earliest dependency-ready WBS item', async t => {

package/repo-agent-governance/tools/spec-charts/spec-parser.mjs

@@ -2,6 +2,7 @@
 export const STATUS_ORDER = [
   'not-started',
   'in-progress',
+  'planning-complete',
   'implementation-complete',
   'verified',
   'blocked',
@@ -306,6 +307,16 @@ function normalizeStatus(value) {
   return normalized;
 }
 
+export function isPlanningCompleteEligible(task) {
+  return task.completionMode === 'planning-only';
+}
+
+export function isPrerequisiteSatisfied(task, status) {
+  return (
+    status === 'verified' || (status === 'planning-complete' && isPlanningCompleteEligible(task))
+  );
+}
+
 function reviewDateFromLine(line) {
   return (
     line.match(/(?:last reviewed|最后审查日期)\s*(?:[:：]\s*)?(\d{4}-\d{2}-\d{2})/i)?.[1] ?? null
@@ -360,7 +371,7 @@ export function parseProgress(markdown, { file } = {}) {
 }
 
 function labeledValue(record, labels) {
-  const match = record.text.trim().match(/^([A-Z]+)\s*:(.*)$/i);
+  const match = record.text.trim().match(/^([A-Z]+(?:\s+[A-Z]+)*)\s*:(.*)$/i);
   return match && labels.includes(match[1].toLowerCase()) ? match[2].trim() : null;
 }
 
@@ -502,6 +513,11 @@ export function parseWbs(markdown, { file } = {}) {
       task = null;
       inPhase = false;
     }
+    if (!task && labeledValue(record, ['completion mode']) !== null) {
+      throw new Error(
+        `Completion mode must belong to a formal WBS task at ${atLocation(record, file)}.`,
+      );
+    }
     if (!inPhase) continue;
     if (task) task.body.push(record);
     else if (!phase.tasks.length) phase.preamble.push(record);
@@ -519,6 +535,29 @@ export function parseWbs(markdown, { file } = {}) {
         ? { line: dependency.line, ...(file ? { file } : {}) }
         : undefined;
       task.phase = { number: phase.number, title: phase.title };
+      const modeRecords = task.body.filter(
+        record => labeledValue(record, ['completion mode']) !== null,
+      );
+      if (modeRecords.length > 1) {
+        throw new Error(
+          `Multiple ${task.id} Completion mode fields at ${atLocation(modeRecords[1], file)}.`,
+        );
+      }
+      const mode = modeRecords.length
+        ? labeledValue(modeRecords[0], ['completion mode'])
+            .replace(/`/g, '')
+            .replace(/\.$/, '')
+            .toLowerCase()
+        : undefined;
+      if (mode && mode !== 'planning-only') {
+        throw new Error(
+          `Unsupported ${task.id} Completion mode at ${atLocation(modeRecords[0], file)}.`,
+        );
+      }
+      if (modeRecords.length && !mode) {
+        throw new Error(`Empty ${task.id} Completion mode at ${atLocation(modeRecords[0], file)}.`);
+      }
+      task.completionMode = mode;
       const statusRecords = task.body.filter(record => labeledValue(record, ['status']) !== null);
       if (statusRecords.length > 1) {
         throw new Error(

package/repo-docs/ai/ai-spec-driven-development.md

@@ -53,6 +53,7 @@ For the detailed authority table, identifiers, and chart boundary, see [Generate
 
 **Evidence-gated delivery** means delivery status stays precise about what is known and what has been proven.
 
+- `planning-complete` means an explicitly `planning-only` WBS task's documentary checks have a named-reviewer, revision-scoped closure disposition and retained planning proof. It satisfies that task's prerequisite edge, not implementation, ATP, successor approval, or release.
 - `implementation-complete` means the source work is complete, while required ATP or release proof remains.
 - `verified` means all applicable WBS checks and ATPs have durable, linked, redacted observed evidence.
 

package/repo-docs/ai/playbook-spec-execution.md

@@ -109,11 +109,12 @@ Use the narrowest approved check first, then follow the linked ATP procedures an
 
 Use status precisely:
 
-- `in-progress` — approved implementation or verification has actually begun
+- `in-progress` — approved work or verification has actually begun
+- `planning-complete` — only an opted-in documentary/design WBS task with a named-reviewer, revision-scoped closure disposition and linked planning proof; no source or ATP closure
 - `implementation-complete` — source work is complete, but required ATP or release proof remains
 - `verified` — all applicable WBS checks and ATPs have durable, linked, redacted observed evidence
 
-A successful build, generation command, hook, manual walkthrough, screenshot, or unrelated test run is not by itself `verified` unless the authoritative test plan defines it as sufficient retained proof. Evidence is revision- and authority-scoped; mark old proof superseded or requiring rerun when relevant source or authority changes.
+`planning-complete` satisfies a predecessor dependency edge but does not unblock a task still recorded `blocked` or grant an execution dossier. Charts count only `verified` toward verified/remaining metrics. A successful build, generation command, hook, manual walkthrough, screenshot, or unrelated test run is not by itself `verified` unless the authoritative test plan defines it as sufficient retained proof. Evidence is revision- and authority-scoped; mark old proof superseded or requiring rerun when relevant source or authority changes.
 
 ## Refresh derived charts last
 

package/repo-docs/ai/playbook-spec-generation.md

@@ -115,7 +115,7 @@ PRD → SRS → WBS → ATP → Evidence
 
 A product or technical change belongs in its PRD, SRS, or accepted ADR before its WBS, acceptance, progress, evidence, and chart implications are updated. A progress entry or chart cannot introduce a requirement, resolve a contract conflict, or accept an ADR.
 
-Planning records and derived charts do not establish `implementation-complete` or `verified`. `verified` requires the applicable acceptance procedure and retained, redacted observed evidence. A generated plan, planned command, scaffold, screenshot, or unrelated check is not automatically sufficient proof.
+A WBS task may declare `Completion mode: planning-only.` only for documentary/design-only checks. It can reach `planning-complete` after an explicit named-reviewer, revision-scoped closure disposition and linked planning proof; this satisfies its dependency edge without executing source, passing future ATPs, unblocking a recorded `blocked` successor, or counting as `verified` in charts. Planning records and derived charts do not establish `implementation-complete` or `verified`. `verified` requires the applicable acceptance procedure and retained, redacted observed evidence. A generated plan, planned command, scaffold, screenshot, or unrelated check is not automatically sufficient proof.
 
 ## Check planning without claiming implementation
 

package/repo-docs/demo.md

@@ -10,3 +10,17 @@ Explore the Cabloy demonstration sites:
 | ---------- | ---------------------------------------------------------------- |
 | Web site   | [https://demo.cabloy.com/](https://demo.cabloy.com/)             |
 | Admin site | [https://demo.cabloy.com/admin/](https://demo.cabloy.com/admin/) |
+
+## Videos
+
+### 1. Can an Admin Site Use SSR? CabloyJS in Three Practical Demos (Duration: 1:16)
+
+[![CabloyJS Admin SSR video](./assets/img/cabloy-admin-ssr-cover-en.png)](https://youtu.be/786IQhRdr1I)
+
+### 2. A First: Second-Level Tabs for Admin Multitasking (Duration: 1:50)
+
+[![CabloyJS Admin Tabs video](./assets/img/cabloy-admin-tabs-cover-en.png)](https://youtu.be/L6DxD-JfztQ)
+
+### 3. AI Coding in Action: One Prompt for CRUD, SSR & Multitasking (Duration: 3:50)
+
+[![CabloyJS AI CRUD video](./assets/img/cabloy-ai-crud-cover-en.png)](https://youtu.be/PV9_By08hDM)

package/repo-docs/frontend/scripts.md

@@ -68,23 +68,16 @@ npm run deps:vona
 npm run test:e2e cabloy-basic home-user-account
 ```
 
-The managed clean command resets Vona-managed test data and the local Redis namespace, starts one development Vona worker, and runs the selected specs. Browser commands consume already-built artifacts; they do not rebuild them.
-
-The unified runner uses two commands:
-
-```text
-npm run test:e2e                 clean local run with database reset
-npm run test:e2e:fast            fast run without automatic reset
-```
+The sole managed `npm run test:e2e` command starts a fresh local Vona worker with `--workers=1 --flavor=normal --mode=test`, then runs the selected specs against Vona integrated SSR. Test-mode startup initializes test resources without a separate `db:reset`; browser commands consume already-built artifacts and do not rebuild them. Confirm exclusive ownership of the effective test database, `_local` Redis namespace, public/runtime paths, `APP_NAME`, API origin, and listener before startup; a free port alone is insufficient.
 
 Place flat spec basenames directly after the npm script name. Use npm's `--` delimiter before Playwright options. With no names, every spec in `repo-e2e/specs` runs. Native `--grep` and `--grep-invert` remain available, and repeatable `--tag` values require all listed tags:
 
 ```bash
 npm run test:e2e cabloy-basic home-user-account -- --grep @flow
-npm run test:e2e:fast a-commerce -- --tag @web --tag @smoke
+npm run test:e2e a-commerce -- --tag @web --tag @smoke
 ```
 
-For the complete tag vocabulary, managed-runner argument boundaries, and externally managed-target examples, see [Repo Scripts](/reference/repo-scripts#ssr-browser-checks). A separately managed target uses `E2E_BASE_URL` with `test:e2e:fast`; the caller owns external-target data, cache, and artifact freshness.
+For the complete Basic tag vocabulary and managed-runner argument boundaries, see [Repo Scripts](/reference/repo-scripts#ssr-browser-checks). `E2E_BASE_URL` must be unset: externally managed targets are unsupported.
 
 ## Cabloy Start root wrappers
 
@@ -102,7 +95,7 @@ Cabloy Start does not expose the Basic Commerce wrapper family.
 
 ## Start SSR browser acceptance
 
-The Start Web and Admin browser baseline also exercises Vona SSR dispatch at the effective local server port. Prepare current SSR and REST artifacts, then use the managed local command:
+The Start Web and Admin browser baseline exercises Vona integrated SSR dispatch at the effective local test-mode server port. Prepare current SSR and REST artifacts, then use the managed local command:
 
 ```bash
 npm run build:zova
@@ -110,23 +103,22 @@ npm run deps:vona
 npm run test:e2e
 ```
 
-Start uses the same unified E2E command pair as Basic:
+Start uses one E2E command and one fresh managed local test-mode lifecycle:
 
 ```text
-npm run test:e2e       managed clean local suite run
-npm run test:e2e:fast  fast rerun without an automatic reset
+npm run test:e2e       fresh managed local test-mode suite run
 ```
 
 Select flat spec basenames and filter scenarios or surfaces with runner tags and native Playwright arguments. Current Start scenarios use tags including `@web`, `@admin`, `@smoke`, `@layout`, `@cabloy-admin`, `@account`, `@ssr`, and `@flow`:
 
 ```bash
 npm run test:e2e cabloy-start
-npm run test:e2e:fast cabloy-start -- --tag @web
-npm run test:e2e:fast cabloy-admin -- --tag @admin --tag @cabloy-admin
-npm run test:e2e:fast cabloy-start -- --grep ATP-START-FLOW-01
+npm run test:e2e cabloy-start -- --tag @web
+npm run test:e2e cabloy-admin -- --tag @admin --tag @cabloy-admin
+npm run test:e2e cabloy-start -- --grep ATP-START-FLOW-01
 ```
 
-For a separately managed Start target, set `E2E_BASE_URL` and use `test:e2e:fast`. The target owner is responsible for data, cache, artifact freshness, and process lifecycle.
+Start does not support externally managed E2E targets: `E2E_BASE_URL` must be unset. The command requires the configured local port to be available and starts one Vona worker with `--flavor=normal --mode=test`; Playwright does not reuse an existing process. Test-mode startup initializes test state. Confirm exclusive ownership of the test database, Redis namespace, and public/runtime paths before running it. The command does not replace the paired build/dependency-sync prerequisite; do not change shared environment identity or ports to avoid a busy resource.
 
 ## Zova script model
 

package/repo-docs/fullstack/parallel-worktree-environment.md

@@ -77,12 +77,12 @@ For privacy, the skill writes only to absent or empty permitted broad local file
 
 Use commands from the active repository root.
 
-| Edition      | Marker             | Frontend command                                   | Managed clean E2E  |
+| Edition      | Marker             | Frontend command                                   | Managed E2E        |
 | ------------ | ------------------ | -------------------------------------------------- | ------------------ |
 | Cabloy Basic | `__CABLOY_BASIC__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e` |
 | Cabloy Start | `__CABLOY_START__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e` |
 
-Run one frontend command, not both, in each worktree. Both managed clean E2E workflows read Vona's effective local `SERVER_LISTEN_PORT`, then reset, start, and target that local runtime.
+Run one frontend command, not both, in each worktree. Both managed E2E workflows read Vona's effective local `SERVER_LISTEN_PORT` and start one fresh Vona test-mode worker; startup initializes test resources without a separate reset. Before either command, confirm exclusive ownership of the effective test database, `_local` Redis namespace, public/runtime paths, `APP_NAME`, API origin, and listener. A free port alone does not establish ownership. Do not change shared identity or ports to bypass a collision, and leave `E2E_BASE_URL` unset: externally managed targets are unsupported.
 
 ## What this isolates
 

package/repo-docs/index.md

@@ -32,9 +32,9 @@ features:
 
 ## Demonstrations(Videos)
 
-### 1. Can an Admin Site Use SSR? CabloyJS in Three Practical Demos (Duration: 1:16)
+### 1. AI Coding in Action: One Prompt for CRUD, SSR & Multitasking (Duration: 3:50)
 
-[![CabloyJS Admin SSR video](./assets/img/cabloy-admin-ssr-cover-en.png)](https://youtu.be/786IQhRdr1I)
+[![CabloyJS AI CRUD video](./assets/img/cabloy-ai-crud-cover-en.png)](https://youtu.be/PV9_By08hDM)
 
 ## Choose a reading path
 

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

@@ -40,9 +40,7 @@ Cabloy Basic exposes these shared root scripts:
 - `npm run start`
 - `npm run start:one`
 - `npm run test`
-- `npm run db:reset`
 - `npm run test:e2e`
-- `npm run test:e2e:fast`
 - `npm run tsc`
 - `npm run docs:dev`
 - `npm run docs:build`
@@ -117,7 +115,6 @@ Cabloy Start exposes the equivalent Start repository surface:
 - `npm run test`
 - `npm run db:reset`
 - `npm run test:e2e`
-- `npm run test:e2e:fast`
 - `npm run tsc`
 
 Cabloy Start does not expose Basic Commerce or root documentation wrappers.
@@ -138,7 +135,7 @@ repo-e2e/specs/home-user-account.spec.ts
 repo-e2e/specs/a-commerce.spec.ts
 ```
 
-It also reconciles the two framework E2E scripts and the `@playwright/test` development dependency. Keep additional project browser specs under other filenames in `repo-e2e/specs`; the upgrader updates only the listed framework files. The current fresh baseline is required and is not repaired for unsupported legacy project layouts.
+It reconciles the single framework-owned `test:e2e` script and the `@playwright/test` development dependency. The retired `test:e2e:fast` script is removed only if its value matches the known old framework command; a customized project alias is preserved. Keep additional project browser specs under other filenames in `repo-e2e/specs`; the upgrader updates only the listed framework files. The current fresh baseline is required and is not repaired for unsupported legacy project layouts.
 
 ### Cabloy Start repository
 
@@ -154,31 +151,28 @@ The public-package upgrade flow does not source or reconcile the Start-owned bas
 
 ## SSR browser checks
 
-The unified runner has two modes:
-
-- `npm run test:e2e`: clean local run; checks the managed Vona port, resets the database, starts one development Vona worker, and runs Playwright.
-- `npm run test:e2e:fast`: skips the reset for quick reruns and may target either the local managed Vona server or an externally managed `E2E_BASE_URL`.
+Cabloy Basic and Cabloy Start each use a single managed local `npm run test:e2e` command. In Basic, the runner checks the effective `normal/test/local` Vona listener port and starts one fresh `--workers=1 --flavor=normal --mode=test` worker. Test-mode startup initializes test resources; the runner does not invoke a separate `db:reset` or a development-mode server. Playwright does not reuse an existing process. Confirm exclusive ownership of the effective test database, `_local` Redis namespace, public/runtime paths, `APP_NAME`, API origin, and listener before starting it; port availability alone is insufficient.
 
-These browser checks target Vona integrated SSR. In the Cabloy Basic default environment, the Vona listener is `7102`; the Zova standalone SSR development server uses `9000` and is not an acceptance target.
+Both editions' browser checks target Vona integrated SSR. In the Cabloy Basic default environment, the Vona listener is `7102`; the Zova standalone SSR development server uses `9000` and is not an acceptance target.
 
 Place spec basenames directly after the npm script name; use npm's `--` delimiter only before Playwright options. Multiple spec names are allowed. With no names, every spec in `repo-e2e/specs` is discovered:
 
 ```bash
 npm run test:e2e cabloy-basic home-user-account
 npm run test:e2e a-commerce
-npm run test:e2e:fast home-user-account
-npm run test:e2e:fast a-commerce -- --grep ATP-SSR
-npm run test:e2e:fast a-commerce -- --grep-invert @admin
+npm run test:e2e home-user-account
+npm run test:e2e a-commerce -- --grep ATP-SSR
+npm run test:e2e a-commerce -- --grep-invert @admin
 ```
 
 Tags remain independent from filenames. Repeat `--tag` to require all tags, while native `--grep` and `--grep-invert` remain available:
 
 ```bash
-npm run test:e2e:fast a-commerce -- --tag @web --tag @smoke
-npm run test:e2e:fast home-user-account -- --grep @flow --tag @web
+npm run test:e2e a-commerce -- --tag @web --tag @smoke
+npm run test:e2e home-user-account -- --grep @flow --tag @web
 ```
 
-The existing tags include `@web`, `@admin`, `@smoke`, `@flow`, `@ssr`, `@theme`, and the business tags used by Commerce such as `@cart`, `@payment`, `@shipment`, and `@refund`. No suite tag is required. Clean runs are local-only and reject `E2E_BASE_URL`; fast runs against an external target do not reset, start, stop, or rebuild that target.
+The existing Basic tags include `@web`, `@admin`, `@smoke`, `@flow`, `@ssr`, `@theme`, and the business tags used by Commerce such as `@cart`, `@payment`, `@shipment`, and `@refund`. No suite tag is required. In Cabloy Basic, `E2E_BASE_URL` must be unset: external targets and a fast/no-reset mode are unsupported.
 
 ### Cabloy Basic and Commerce
 
@@ -198,15 +192,9 @@ npm run deps:vona
 npm run test:e2e a-commerce
 ```
 
-For a separately managed target, use the fast command:
-
-```bash
-E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:fast a-commerce -- --tag @smoke
-```
-
 ### Cabloy Start
 
-The Start suite exercises Web at `/` and Admin at `/admin` through Vona integrated SSR dispatch. Prepare current Start artifacts before a managed local run:
+The Start suite exercises Web at `/` and Admin at `/admin` through Vona integrated SSR dispatch. Prepare current Start artifacts before a managed local run. The runner uses the effective local `normal`-flavor, test-mode Vona listener, rather than assuming a fixed port:
 
 ```bash
 npm run build:zova
@@ -216,20 +204,16 @@ npm run test:e2e
 
 ```bash
 # Exact acceptance scenario
-npm run test:e2e:fast cabloy-start -- --grep ATP-START-FLOW-01
+npm run test:e2e cabloy-start -- --grep ATP-START-FLOW-01
 
 # Category or surface selection
-npm run test:e2e:fast cabloy-start -- --tag @smoke
-npm run test:e2e:fast cabloy-admin -- --tag @admin --tag @cabloy-admin
+npm run test:e2e cabloy-start -- --tag @smoke
+npm run test:e2e cabloy-admin -- --tag @admin --tag @cabloy-admin
 ```
 
-For an externally managed Start target, set `E2E_BASE_URL` and use `npm run test:e2e:fast`. The target owner is responsible for data, cache, artifact freshness, and process lifecycle:
+In Cabloy Start, the sole `npm run test:e2e` command checks the configured local port and starts a fresh runner-managed Vona target with `--workers=1 --flavor=normal --mode=test`. Playwright never reuses an existing server. Test-mode startup initializes test resources; the runner does not invoke a separate `db:reset`. Confirm ownership of the test database, Redis namespace, and public/runtime paths before running it; do not change shared environment identity or ports to bypass a busy resource.
 
-```bash
-E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:fast
-E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:fast cabloy-admin -- --tag @admin
-E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:fast cabloy-start -- --tag @web
-```
+`E2E_BASE_URL` is unsupported in Cabloy Start and must be unset, even for a local URL. Externally managed targets are not supported.
 
 Browser commands consume existing SSR and REST artifacts; they never rebuild them. Install Chromium once when needed with `npx playwright install chromium`.
 

package/repo-e2e/config/playwright.config.ts

@@ -2,9 +2,6 @@ import { defineConfig } from '@playwright/test';
 
 import { E2E_LOCAL_BASE_URL, E2E_ROOT_DIR } from '../scripts/e2e.ts';
 
-const externalBaseURL = process.env.E2E_BASE_URL;
-const baseURL = externalBaseURL || E2E_LOCAL_BASE_URL;
-
 export default defineConfig({
   testDir: `${E2E_ROOT_DIR}/repo-e2e/specs`,
   fullyParallel: false,
@@ -13,22 +10,20 @@ export default defineConfig({
   retries: process.env.CI ? 2 : 0,
   reporter: process.env.CI ? [['html', { open: 'never' }], ['list']] : 'list',
   use: {
-    baseURL,
+    baseURL: E2E_LOCAL_BASE_URL,
     trace: 'on-first-retry',
   },
-  webServer: externalBaseURL
-    ? undefined
-    : {
-        command: 'node repo-e2e/scripts/startE2eVona.ts',
-        cwd: E2E_ROOT_DIR,
-        url: `${baseURL}/health/ready`,
-        timeout: 180_000,
-        reuseExistingServer: false,
-        stdout: 'pipe',
-        stderr: 'pipe',
-        gracefulShutdown: {
-          signal: 'SIGINT',
-          timeout: 10_000,
-        },
-      },
+  webServer: {
+    command: 'node repo-e2e/scripts/startE2eVona.ts',
+    cwd: E2E_ROOT_DIR,
+    url: `${E2E_LOCAL_BASE_URL}/health/ready`,
+    timeout: 180_000,
+    reuseExistingServer: false,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    gracefulShutdown: {
+      signal: 'SIGINT',
+      timeout: 10_000,
+    },
+  },
 });

package/repo-e2e/scripts/e2e.test.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+test('rejects a defined E2E_BASE_URL before loading local configuration', () => {
+  const entrypoint = fileURLToPath(new URL('./e2e.ts', import.meta.url));
+  for (const value of ['', 'http://127.0.0.1:7102']) {
+    const result = spawnSync(process.execPath, [entrypoint], {
+      env: { ...process.env, E2E_BASE_URL: value },
+      encoding: 'utf8',
+    });
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /E2E_BASE_URL is unsupported/);
+    assert.doesNotMatch(result.stderr, /SERVER_LISTEN_PORT/);
+  }
+});

package/repo-e2e/scripts/e2e.ts

@@ -4,8 +4,12 @@ import { fileURLToPath } from 'node:url';
 
 export const E2E_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
+if (process.env.E2E_BASE_URL !== undefined) {
+  throw new Error('E2E_BASE_URL is unsupported; the E2E runner manages a local test-mode target.');
+}
+
 const vonaEnv = dotenv.loadEnvs(
-  { flavor: 'normal', mode: 'dev', local: 'local' },
+  { flavor: 'normal', mode: 'test', local: 'local' },
   resolve(E2E_ROOT_DIR, 'vona', 'env'),
   '.env',
 );