cabloy 5.1.227 → 5.1.228

package/repo-agent-governance/tools/evidence-paths/sanitize.mjs

@@ -9,14 +9,15 @@ export const LINE_LIMIT = 1024 * 1024;
 export const FILE_LIMIT = 8 * 1024 * 1024;
 
 class SafeError extends Error {
-  constructor(code) {
+  constructor(code, details) {
     super(code);
     this.code = code;
+    this.details = details;
   }
 }
 
-function fail(code) {
-  throw new SafeError(code);
+function fail(code, details) {
+  throw new SafeError(code, details);
 }
 
 function rootInfo(value) {
@@ -247,6 +248,7 @@ export async function sanitizeStream(input, output, { matcher = createMatcher()
   output.on('error', onError);
   let parts = [];
   let length = 0;
+  let lineNumber = 1;
   try {
     for await (const chunk of input) {
       if (outputFailed) fail('OUTPUT_ERROR');
@@ -262,9 +264,10 @@ export async function sanitizeStream(input, output, { matcher = createMatcher()
         parts.push(bytes.subarray(start, end));
         if (newline < 0) break;
         const line = Buffer.concat(parts, length);
-        if (binary(line)) fail('BINARY');
+        rejectBinary(line, lineNumber);
         const text = decode(line);
         await write(output, `${matcher.sanitize(text)}\n`);
+        lineNumber++;
         parts = [];
         length = 0;
         start = newline + 1;
@@ -272,7 +275,7 @@ export async function sanitizeStream(input, output, { matcher = createMatcher()
     }
     if (length) {
       const line = Buffer.concat(parts, length);
-      if (binary(line)) fail('BINARY');
+      rejectBinary(line, lineNumber);
       await write(output, matcher.sanitize(decode(line)));
     }
     if (outputFailed) fail('OUTPUT_ERROR');
@@ -293,12 +296,21 @@ function safeFilename(value, matcher) {
     );
 }
 
-function binary(bytes) {
-  return bytes.some(
+function binaryIndex(bytes) {
+  return bytes.findIndex(
     byte => byte === 0 || byte === 127 || (byte < 32 && ![9, 10, 12, 13].includes(byte)),
   );
 }
 
+function binary(bytes) {
+  return binaryIndex(bytes) >= 0;
+}
+
+function rejectBinary(bytes, line) {
+  const index = binaryIndex(bytes);
+  if (index >= 0) fail('BINARY', { byte: bytes[index], line, bytePosition: index + 1 });
+}
+
 async function ancestorExclusion(path) {
   const root = parse(path).root;
   let current = root;
@@ -465,6 +477,9 @@ paths and unknown absolute roots are left unchanged: this is NOT a universal sec
 scanner. Use explicit maps for other local roots; inspect output before publication.
 UTF-8 decoding is fatal, with a 1 MiB byte limit per line (including CR, excluding LF).
 NUL, DEL and non-text C0 controls are rejected; tab, LF, form feed and CR are allowed.
+sanitize BINARY diagnostics report only the first rejected decimal byte, 1-based input
+line and byte-position within that original UTF-8 line. LF advances the line; CR counts
+as a byte, not a line boundary. No text from the rejected line is reported.
 Only complete validated lines are emitted; earlier sanitized lines may survive failure.
 check limits each file to 8 MiB, treats NUL/non-text controls as binary, and reports only
 scope-N/relative-filename:line CODE, never source lines or absolute scan roots.
@@ -530,8 +545,23 @@ export async function runCli(
     return result.status;
   } catch (caught) {
     const code = caught instanceof SafeError ? caught.code : 'INTERNAL_ERROR';
+    let diagnostic = code;
+    if (caught instanceof SafeError && code === 'BINARY') {
+      const { byte, line, bytePosition } = caught.details ?? {};
+      if (
+        Number.isInteger(byte) &&
+        byte >= 0 &&
+        byte <= 255 &&
+        Number.isSafeInteger(line) &&
+        line > 0 &&
+        Number.isSafeInteger(bytePosition) &&
+        bytePosition > 0
+      ) {
+        diagnostic += ` byte=${byte} line=${line} byte-position=${bytePosition}`;
+      }
+    }
     try {
-      await write(error, `evidence-paths: ${code}\n`);
+      await write(error, `evidence-paths: ${diagnostic}\n`);
     } catch {
       /* no unsafe fallback */
     }

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

@@ -71,7 +71,9 @@ When the change belongs in the current version path rather than new migration hi
 2. fold the schema change into the current version path;
 3. do not create a new migration branch.
 
-Ask before choosing this strategy; do not infer migration history from the field change alone. Any change to `meta.version.ts` requires `npm run test` so the test database is recreated and schema/data consistency is exercised.
+Ask before choosing this strategy; do not infer migration history from the field change alone. Normal startup does not replay an already-applied positive-numbered migration branch. Editing that branch affects fresh installations and isolated test preparation, not a development database that has already applied it. A no-bump decision is not authorization to reset development data; if existing data must be preserved, agree on a new incremental migration instead.
+
+Verify changes to migration, initialization, or seed behavior through managed isolated tests covering the affected behavior, preferably focused. A `meta.version.ts` edit alone does not require the full suite. See [Local development workflow](#local-development-workflow) for the separate verification and development-database decisions.
 
 ## `meta.version`
 
@@ -186,29 +188,33 @@ A practical sequence is:
 1. decide whether to increment `fileVersion`
 2. add or adjust entity/model structure
 3. update the current or new `meta.version` path to match that decision
-4. rerun migration locally
-5. verify the contract through tests and controller actions
+4. verify migration and resource behavior through managed isolated tests
+5. separately decide whether and how to update the development database
 
 This keeps schema change, backend contract change, and verification tightly connected.
 
 ## Local development workflow
 
-One important distinction for local development is:
+Keep two questions separate: **how to verify the change** and **how to update development data**. Isolated tests do not update development databases, and a development reset is not a substitute for tests.
 
-- when iterating locally, you often want to recreate the database and re-run migration logic without bumping `fileVersion`
+| Need                                                                                   | Path                                             | Boundary                                                                                                 |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| Verify migration, initialization, seed, and affected resource behavior                 | Managed isolated tests, preferably focused       | Even a focused run prepares a fresh test database; it does not change dev data.                          |
+| Apply a new module or pending versioned migration to an existing prepared dev database | Normal application startup                       | Applies pending versions without resetting existing data; ordinary dev startup does not repeat `seed()`. |
+| Replay an edited, already-applied positive-numbered branch on disposable dev data      | Separately approved `npm run db:reset`           | Destructive recreation; a no-bump decision does not authorize reset.                                     |
+| Update an existing database while preserving business data                             | A new incremental migration, then normal startup | Do not rely on editing an already-applied branch or use reset.                                           |
 
-Representative commands:
+For example, from the repository root:
 
 ```bash
-npm run test
-npm run db:reset
+npm run test -- 'src/module/<module-name>/test/**/*.ts'
 ```
 
-A practical decision rule is:
+Resolve the actual path for suite-owned modules. Select tests that cover the affected migration and contract behavior; expand coverage according to actual impact, not merely the presence of a `meta.version.ts` edit. Fresh-database preparation proves the fresh-install path, not every existing-data upgrade; verify upgrade behavior when the change requires it. See [Unit Testing](/backend/unit-testing#execute-tests).
+
+The replay rule above concerns positive-numbered migration branches. The special version `0` and `fileVersion: -1` lifecycle paths retain their always-run semantics; they are not a reason to move a versioned schema change into an always-run branch.
 
-- use `db:reset` to recreate the disposable **dev-mode** databases, rerun migrations and instance initialization, and then invoke module `seed()` hooks; it deletes existing matching development databases, so do not run it against data you need to keep
-- `db:reset` requires `database.testDatabase: true` in dev config and a connection outside the disposable database; it refuses to reset a configured non-disposable database
-- use `test` when you need **test-mode** verification of migration, controller behavior, and the broader generated contract thread; E2E also remains test-mode
+`db:reset` requires explicit approval, `database.testDatabase: true` in dev config, and a connection outside the disposable database. It refuses to reset a configured non-disposable database. Follow the lifecycle and concurrency precautions below before an approved reset.
 
 ### Managed development database preparation
 
@@ -239,7 +245,8 @@ Also ask:
 
 1. does this change require a `fileVersion` increment?
 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?
+3. which managed focused tests verify the affected migration and resource behavior, and does the actual impact require broader coverage?
+4. does the development database need pending migrations through startup, a separately approved disposable reset, or a new data-preserving migration?
+5. does the change affect the CRUD-generated thread or frontend-facing API contract as well?
 
 That prevents schema changes from being documented in code but never integrated into the module lifecycle.

package/repo-docs/backend/quickstart.md

@@ -19,7 +19,7 @@ Use this page when you are contributing backend work in the framework repository
 | Name       | Version   |
 | ---------- | --------- |
 | pnpm       | >=12.14.0 |
-| Node.js    | >=24.8.0  |
+| Node.js    | >=24.11.0 |
 | Redis      | >=7.2.6   |
 | Sqlite3    | Built-in  |
 | MySQL      | >=8       |

package/repo-docs/backend/resource-field-update.md

@@ -61,7 +61,7 @@ When the user decides not to create new migration history:
 2. fold the schema change into the current version path;
 3. do not create a new migration branch.
 
-For the complete migration lifecycle and test requirement, see [Migration and Changes](/backend/migration-and-changes#decide-whether-to-increment-fileversion).
+Normal startup does not replay an already-applied positive-numbered migration branch. Managed focused tests exercise the edited path on an isolated test database, not the development database. A no-bump decision does not authorize a destructive dev reset; use a new incremental migration when existing data must be preserved. See [Migration and Changes](/backend/migration-and-changes#local-development-workflow) for the verification and development-database decision paths.
 
 ## Inspect the existing resource thread
 
@@ -195,7 +195,8 @@ Choose checks that match the layers changed:
 
 - inspect generated schema/OpenAPI after structure-shaping field changes;
 - run the narrow resource test and relevant typecheck;
-- run `npm run test` for any `meta.version.ts` change so the test database is recreated and migration consistency is exercised;
+- verify affected migration, initialization, or seed behavior through managed isolated tests, preferably focused; focused runs still prepare a fresh test database, so a `meta.version.ts` edit alone does not require the full suite;
+- decide development-database updates separately: tests do not update dev data, pending migrations apply through normal startup, and replaying an already-applied positive-numbered branch on disposable dev data requires explicit reset approval;
 - run the relevant frontend metadata/build/dependency synchronization when custom renderer resources are involved;
 - verify action-level serializer behavior with an API test when `v.serializer*` metadata changes returned fields;
 - for join-backed filters and sorting, inspect transformed `where`, `orders`, and `joins`, then exercise the resource endpoint so metadata-only success cannot hide incorrect query behavior.

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

@@ -8,7 +8,7 @@ Keep testing proportional to the backend change: cover critical business behavio
 
 Test-driven development and targeted unit or framework tests remain useful when they clarify and directly prove new or changed behavior. Exhaustive upfront mock/fake matrices and bespoke harnesses are not a delivery prerequisite.
 
-Preserve applicable authentication/authorization, tenant-isolation, transaction, concurrency, idempotency, migration, and acceptance checks without turning them into an unrelated mandatory matrix. The context, fixture, and resource-isolation rules below still apply, including the required `npm run test` after `meta.version.ts` changes. Missing runtime access must be reported, not worked around with unauthorized resets or substitute test machinery.
+Preserve applicable authentication/authorization, tenant-isolation, transaction, concurrency, idempotency, migration, and acceptance checks without turning them into an unrelated mandatory matrix. The context, fixture, and resource-isolation rules below still apply. Verify changes to migration, initialization, or seed behavior through managed isolated tests covering the affected behavior, preferably focused; a `meta.version.ts` edit alone does not require the full suite. Missing runtime access must be reported, not worked around with unauthorized resets or substitute test machinery.
 
 Vona’s testing story is valuable because it is closely integrated with:
 
@@ -42,7 +42,13 @@ npm run vona :create:test student -- --module=training-student
 
 ## Execute tests
 
-From the root repository:
+From the repository root, prefer a focused run for a bounded module change:
+
+```bash
+npm run test -- 'src/module/<module-name>/test/**/*.ts'
+```
+
+Resolve the actual test path for suite-owned modules. Positional patterns select test files, not a reduced database-preparation lifecycle. Focused managed tests still exercise fresh migration, initialization, and seeds; assert the affected resource behavior and cover existing-data upgrades when applicable. Expand to the full suite according to actual impact:
 
 ```bash
 npm run test
@@ -57,7 +63,7 @@ A typical Vona test flow includes:
 5. run the test files
 6. close the shared application after the test run
 
-In Cabloy Basic and Cabloy Start, root `npm run test` delegates to `vona/`'s `npm run test`; both allocate an isolated test identity, database and Redis namespace, Vona generated/runtime/public paths, and loopback listener. They can run in the same checkout as an ordinary development server without resetting or mutating that server's business data. Even a targeted run performs the test-mode setup. The Vona `npm run cov` script uses the same isolation; raw `:bin:test` commands do not. Shared build/dependency preparation may still write to shared artifacts, and custom external resources need separate isolation. See [Repo Scripts](/reference/repo-scripts#test-isolation-and-development-data).
+In Cabloy Basic and Cabloy Start, root `npm run test` delegates to `vona/`'s `npm run test`; both allocate an isolated test identity, database and Redis namespace, Vona generated/runtime/public paths, and loopback listener. They can run in the same checkout as an ordinary development server without resetting or mutating that server's business data. Even a targeted run performs the test-mode setup. Passing tests do not update the development database; choose its migration or explicitly approved reset path separately using [Migration and Changes](/backend/migration-and-changes#local-development-workflow). The Vona `npm run cov` script uses the same isolation; raw `:bin:test` commands do not. Shared build/dependency preparation may still write to shared artifacts, and custom external resources need separate isolation. See [Repo Scripts](/reference/repo-scripts#test-isolation-and-development-data).
 
 The runner owns this application lifecycle. Test files import the shared app from `vona-mock` and must not create or close it themselves:
 

package/repo-docs/frontend/table-cell-cookbook.md

@@ -343,6 +343,38 @@ A practical rule is:
 - let the cell resource own the render interaction
 - let the command bean or model layer own the actual action semantics
 
+### Collect input for a business row action in a dialog
+
+When a row action needs additional business input, such as shipment details or a stock-adjustment reason, prefer a compact button in the cell and collect the input in a focused dialog. Keep deliberate inline-editing workflows inline; this is not a requirement to put every table action in a dialog.
+
+Use the following interaction boundaries:
+
+1. **Open from the target row.** Keep the cell responsible for the trigger and row context. For caller-owned content, use the ordinary `this.$appModal.dialog(...)` with `slotDefault` and `slotActions`; use a routed dialog only when the workflow needs routed pages. See [Routed Dialog Guide](/frontend/routed-dialog-guide#choose-the-right-primitive).
+2. **Collect operation-specific input.** Prefer the operation's generated `$apiSchema` or the owning `ModelResource` schema with automatic `ZForm` rendering when the contract already describes the fields. Keep localized schema access reactive, and do not copy backend field metadata into the controller. Use manual or mixed fields only for a concrete interaction need, such as UI-only confirmation. See [API Schema Guide](/frontend/api-schema-guide#direct-schema-driven-form-pattern) and [Form Guide](/frontend/form-guide#preserve-the-automatic-custom-rendering-boundary).
+3. **Submit through the existing action owner.** Keep the draft local to the interaction, but reuse the existing command or semantic model facade for business execution. For an action on the same resource, retain its existing `ModelResource` mutation and cache owner rather than adding dialog-local fetch/cache state or manual list refreshes. See [Resource Model Cookbook](/frontend/model-resource-cookbook#recipe-4-inside-that-facade-add-a-row-level-custom-mutation).
+4. **Keep one complete submission lifecycle.** Validate and normalize input as required by the operation, and prevent duplicate submission at the boundary that owns all submit paths. Return or await the whole action through `ZButton.onPerform` for a button-only action; use form submission state and error handling when `ZForm` owns submission. Reflect broader mutation pending state only when it is needed beyond that button's own lifecycle. Choose one error presentation owner, not competing alerts. See [Behavior Guide](/frontend/behavior-guide#perform-a-standalone-asynchronous-button-action).
+5. **Close only after success.** Await the mutation before calling the dialog's `close()`. On failure, keep the dialog and entered values available for correction or retry; do not close in `finally`. Cancel or dismissal must not initiate a mutation, but closing the dialog does not cancel an already submitted request. Choose confirmation, draft reset/recovery, and dismissal behavior from the business workflow rather than copying one example's checkbox, width, or reset policy.
+
+For a schema-driven form, keep its submit controls in `ZForm.slotFooter` when appropriate so that validation and native-form submission remain one path. The dialog's `slotActions` is not a reason to introduce a second submission owner.
+
+Apply these schema-driven form details where they fit the operation:
+
+- **Submit same-shaped data directly.** When the validated form data has the same shape as the operation's request DTO, pass `data.value` directly to the existing mutation, for example `await mutation.mutateAsync(data.value)`. Build a separate payload only when the operation needs a real projection, conversion, or removal of UI-only fields. Do not enumerate fields or duplicate normalization merely to reconstruct the same request; when the backend already owns normalization, leave it there. Schema validation does not imply that every operation trims its input.
+- **Await business confirmation inside `onSubmitData`.** If the operation requires a confirmation prompt, await it after form validation and before the mutation in the same returned or awaited submit handler. Button submission and Enter then share validation, confirmation, pending state, and error handling. A declined confirmation should return without mutating or closing the form, preserving the draft. Do not put confirmation only in the submit button's click handler or introduce a confirmation checkbox unless the business workflow calls for one.
+- **Prepare lazy schemas at the opening boundary when appropriate.** For a low-frequency dialog, opening can await `$QueryEnsureLoaded(() => this.apiSchemasShip.sdk)` before rendering the form. Resolve `apiSchemasShip` through a getter for the current runtime and derive `requestBody` reactively, such as with `$computed`. Ensure the current locale's SDK on every opening, even if the reactive derivation was installed earlier; do not retain a facade or schema snapshot from a previous locale. If preparation is extracted into a helper, await SDK readiness on every call and use `if (!this.schema)` only to create the computed derivation once. Do not place `if (this.schema) return` before the SDK check: an existing computed does not prove that the current locale's SDK is loaded. Extracting a helper is optional; the important boundary is repeated readiness checks versus one-time derivation setup. This is an optional loading boundary, not a requirement to defer every form's schema until interaction.
+
+The Cabloy Basic shipment example is `zova/src/suite/a-commerce/modules/commerce-trade/src/component/tableCellActionShip/controller.tsx`: `_openDialog()` calls `_ensureSchema()` to prepare the current schema, `ZForm` renders the contract fields automatically, and `_submit()` awaits confirmation and `mutateAsync(data.value)` before closing. Its dialog width, draft-reset policy, and backend normalization are operation-specific choices, not additional form rules.
+
+Extend an existing critical-flow E2E scenario rather than creating a separate harness:
+
+- locate the trigger within the intended order or resource row, then locate fields and submit controls within the opened dialog
+- check that the cell no longer exposes the dialog's input fields, and that invalid input cannot submit
+- check cancellation and the chosen reopen/draft policy
+- check successful submission, dialog closure, and the refreshed resource state
+- when covering a submission failure, assert that the dialog retains the draft, presents the intended error, and allows retry after pending state clears
+
+In Cabloy Basic, the ordinary dialog can be located with `getByRole('dialog')`; assert its visible heading rather than assuming the title also supplies its accessible name. Verify the active edition's modal adapter before reusing UI-specific selectors.
+
 ## Pattern 5: Row-action composition with `tableActionRow`
 
 Use this pattern when one cell should show several row actions together.

package/repo-docs/fullstack/quickstart.md

@@ -9,7 +9,7 @@ Before creating a new Cabloy project, make sure your environment has:
 | Name         | Version     |
 | ------------ | ----------- |
 | `pnpm`       | `>=12.14.0` |
-| `Node.js`    | `>=24.4.0`  |
+| `Node.js`    | `>=24.11.0` |
 | `Redis`      | `>=7.2.6`   |
 | `SQLite3`    | `Built-in`  |
 | `MySQL`      | `>=8`       |

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

@@ -74,7 +74,7 @@ Root `npm run tsc` runs `tsc:zova`, then `tsc:vona`; these are the only root `ts
 
 In both nested workspaces, `npm run tsc` delegates to `npm run tsc:native`. Native and legacy checks first run `npm run prerun`, then invoke the selected compiler with incremental caching disabled. Root workspace aliases delegate to these scripts too, so dependency and generated metadata preparation is not bypassed. Each workspace's `prerun` runs only its `:tools:deps` command; it does not call `tsc`, avoiding recursive script execution. Preparation may refresh generated metadata or dependency manifests and install changed dependencies, while the compiler step itself emits no declarations or build-info files.
 
-Zova development and build entrypoints call `npm run prerun` before Quasar or REST emission to prepare dependencies and generated metadata without automatically running a typecheck. Run `npm run tsc`, `npm run tsc:native`, or `npm run tsc:legacy` explicitly inside the Zova workspace when source typechecking is needed. The former multi-project Vona CLI command `:bin:tsc` has been removed; use the project checking scripts instead. Module publication configurations and REST emitters are unchanged. Classic TypeScript remains installed for compiler-JavaScript-API consumers, including SWC configuration loading, Rollup integration, and OpenAPI generation; the REST emitter retains the `@typescript/native-preview` dependency name as an npm alias for stable `typescript@7.0.2`, preserving its declaration plugin's compiler lookup.
+Zova development and build entrypoints call `npm run prerun` before Quasar or REST emission to prepare dependencies and generated metadata without automatically running a typecheck. Run `npm run tsc`, `npm run tsc:native`, or `npm run tsc:legacy` explicitly inside the Zova workspace when source typechecking is needed. The former multi-project Vona CLI command `:bin:tsc` has been removed; use the project checking scripts instead. Module publication configurations retain their existing compiler selection. REST emission uses tsdown 0.23.1 with an explicit JavaScript-only pass (`dts: false`) followed by a declaration-only pass (`dts.generator: 'tsgo'`). The frontend CLI and fullstack workflows require Node.js `>=24.11.0`. Classic TypeScript remains installed for compiler-JavaScript-API consumers, including SWC configuration loading, Rollup integration, and OpenAPI generation; the REST emitter retains the `@typescript/native-preview` dependency name as an npm alias for stable `typescript@7.0.2`, preserving its declaration plugin's compiler lookup.
 
 The native alias is installed at the repository root, not in either nested workspace. Run `pnpm install` at the root after updating the checkout; a missing alias fails with an installation diagnostic rather than silently selecting the legacy compiler. Do not use a bare root `tsc`/`pnpm exec tsc` to choose a compiler, because both packages declare the same binary name.
 
@@ -208,7 +208,7 @@ Combine producer stdout/stderr **before** sanitization, never `tee` or spool raw
 
 ### Windows and PowerShell
 
-The tool uses Node's native filesystem APIs on Windows, Linux and macOS; it requires the repository's Node.js version (`>=24.4.0`). Path-text recognition is cross-platform independently of the host OS. Native filesystem behavior is checked by the `evidence-platforms` CI matrix on Ubuntu, Windows and macOS. A configured matrix is not a successful run: inspect the actual job results before claiming all three platforms are verified.
+The tool uses Node's native filesystem APIs on Windows, Linux and macOS; use a Node.js version supported by the repository's root `engines.node` declaration. Path-text recognition is cross-platform independently of the host OS. Native filesystem behavior is checked by the `evidence-platforms` CI matrix on Ubuntu, Windows and macOS. A configured matrix is not a successful run: inspect the actual job results before claiming all three platforms are verified.
 
 From the repository root, PowerShell can invoke the CLI directly:
 

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

@@ -936,22 +936,96 @@ test(
         await expect(adminPage.getByRole('button', { name: 'Submit', exact: true })).toHaveCount(0);
         await adminPage.getByRole('button', { name: 'Back', exact: true }).click();
         await expect(orderRow).toBeVisible();
-        const carrierInput = orderRow.getByPlaceholder('Carrier');
-        const trackingNumberInput = orderRow.getByPlaceholder('Tracking number');
-        const confirmationCheckbox = orderRow.getByRole('checkbox');
+        const openShipmentButton = orderRow.getByRole('button', {
+          name: 'Ship order',
+          exact: true,
+        });
+        await expect(openShipmentButton).toHaveCount(1);
+        await expect(orderRow.locator('input')).toHaveCount(0);
+        await openShipmentButton.click();
+        const shipmentDialog = adminPage.getByRole('dialog').filter({
+          has: adminPage.getByRole('heading', { name: 'Ship order', exact: true }),
+        });
+        const shipmentConfirmation = adminPage.getByRole('dialog').filter({
+          hasText: 'Ship this order with the entered shipment details?',
+        });
+        await expect(shipmentDialog).toBeVisible();
+        const carrierField = shipmentDialog.locator('fieldset').filter({
+          has: adminPage.locator('legend').filter({ hasText: /^Carrier$/ }),
+        });
+        const trackingNumberField = shipmentDialog.locator('fieldset').filter({
+          has: adminPage.locator('legend').filter({ hasText: /^Tracking number$/ }),
+        });
+        const carrierInput = carrierField.getByRole('textbox');
+        const trackingNumberInput = trackingNumberField.getByRole('textbox');
+        await expect(shipmentDialog.getByRole('checkbox')).toHaveCount(0);
+        const submitShipmentButton = shipmentDialog.getByRole('button', {
+          name: 'Ship order',
+          exact: true,
+        });
+        let shipmentRequestCount = 0;
+        adminPage.on('request', request => {
+          if (
+            request.method() === 'POST' &&
+            new URL(request.url()).pathname === `/api/commerce/trade/order/${checkout.orderId}/ship`
+          ) {
+            shipmentRequestCount++;
+          }
+        });
         await carrierInput.fill(shipmentCarrier);
         await trackingNumberInput.fill(shipmentTrackingNumber);
-        await confirmationCheckbox.check();
-        await expect(carrierInput).toHaveValue(shipmentCarrier);
-        await expect(trackingNumberInput).toHaveValue(shipmentTrackingNumber);
-        await expect(confirmationCheckbox).toBeChecked();
+        await shipmentDialog.getByRole('button', { name: 'Cancel', exact: true }).click();
+        await expect(shipmentDialog).toHaveCount(0);
+        await expect(orderRow).toContainText('Paid');
+        await openShipmentButton.click();
+        await expect(carrierInput).toHaveValue('');
+        await expect(trackingNumberInput).toHaveValue('');
+        await submitShipmentButton.click();
+        await expect(carrierField.locator('.text-error')).toBeVisible();
+        await expect(trackingNumberField.locator('.text-error')).toBeVisible();
+        await expect(shipmentConfirmation).toHaveCount(0);
+        await carrierInput.fill('   ');
+        await trackingNumberInput.fill(shipmentTrackingNumber);
+        await submitShipmentButton.click();
+        await expect(carrierField.locator('.text-error')).toBeVisible();
+        await expect(shipmentConfirmation).toHaveCount(0);
+        await carrierInput.fill('x'.repeat(101));
+        await submitShipmentButton.click();
+        await expect(carrierField.locator('.text-error')).toBeVisible();
+        await expect(shipmentConfirmation).toHaveCount(0);
+        await carrierInput.fill(`  ${shipmentCarrier}  `);
+        await trackingNumberInput.fill('x'.repeat(101));
+        await submitShipmentButton.click();
+        await expect(trackingNumberField.locator('.text-error')).toBeVisible();
+        await expect(shipmentConfirmation).toHaveCount(0);
+        await trackingNumberInput.fill(`  ${shipmentTrackingNumber}  `);
+        await submitShipmentButton.click();
+        await expect(shipmentConfirmation).toBeVisible();
+        await expect(submitShipmentButton).toBeDisabled();
+        expect(shipmentRequestCount).toBe(0);
+        await shipmentConfirmation.getByRole('button', { name: 'No', exact: true }).click();
+        await expect(shipmentConfirmation).toHaveCount(0);
+        await expect(carrierInput).toHaveValue(`  ${shipmentCarrier}  `);
+        await expect(trackingNumberInput).toHaveValue(`  ${shipmentTrackingNumber}  `);
+        await expect(orderRow).toContainText('Paid');
+        expect(shipmentRequestCount).toBe(0);
+        await expect(submitShipmentButton).toBeEnabled();
+        await trackingNumberInput.press('Enter');
+        await expect(shipmentConfirmation).toBeVisible();
         const shipmentResponse = waitForApiResponse(
           adminPage,
           'POST',
           `/api/commerce/trade/order/${checkout.orderId}/ship`,
         );
-        await orderRow.getByRole('button', { name: 'Ship order', exact: true }).click();
-        expect((await shipmentResponse).ok()).toBeTruthy();
+        await shipmentConfirmation.getByRole('button', { name: 'Yes', exact: true }).click();
+        const shipmentResult = await shipmentResponse;
+        expect(shipmentResult.ok()).toBeTruthy();
+        expect(shipmentResult.request().postDataJSON()).toEqual({
+          carrier: `  ${shipmentCarrier}  `,
+          trackingNumber: `  ${shipmentTrackingNumber}  `,
+        });
+        expect(shipmentRequestCount).toBe(1);
+        await expect(shipmentDialog).toHaveCount(0);
         await expect(orderRow).toContainText('Shipped');
         expect(adminPageErrors).toEqual([]);
       } finally {

package/scripts/init.ts

@@ -19,6 +19,7 @@ const ROOT_DIR = resolve(__dirname, '..');
 const VONA_DIR = resolve(ROOT_DIR, 'vona');
 const ZOVA_DIR = resolve(ROOT_DIR, 'zova');
 const REPO_DOCS_DIR = resolve(ROOT_DIR, 'repo-docs');
+const NODE_VERSION = '24.11.0';
 const PNPM_VERSION = '12.14.0';
 const VERSION_MARKER_FILE = '.cabloy-version';
 
@@ -50,6 +51,18 @@ function pnpmInstall(cwd = ROOT_DIR): void {
   exec('pnpm install --config.confirmModulesPurge=false --no-frozen-lockfile', cwd);
 }
 
+function checkNode(): void {
+  const version = process.versions.node;
+  const current = version.split('.').map(Number);
+  const minimum = NODE_VERSION.split('.').map(Number);
+  for (let i = 0; i < minimum.length; i++) {
+    if (current[i] > minimum[i]) return;
+    if (current[i] < minimum[i]) {
+      throw new Error(`Node.js should >= ${NODE_VERSION}, current: ${version}`);
+    }
+  }
+}
+
 function checkPnpm(): void {
   const version = execQuiet('pnpm --version').trimEnd();
   const [major, minor] = version.split('.').map(item => Number.parseInt(item, 10) || 0);
@@ -295,6 +308,7 @@ function initRepoDocs(): void {
 
 // --- Main ---
 
+checkNode();
 checkPnpm();
 exec('node scripts/bootstrapAgentGovernance.mjs');
 pnpmInstall();