cabloy 5.1.117 → 5.1.119

package/.cabloy-version

@@ -1 +1 @@
-5.1.117
+5.1.119

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

@@ -42,8 +42,8 @@ jobs:
           DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/orderSnapshot.test.ts --flavor=normal
           DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/reservationExpiry.test.ts --flavor=normal
         working-directory: vona
-      - name: run Commerce payment and shipment lifecycle gate
-        run: DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/paymentOutcome.test.ts commerce-trade/test/reservationExpiry.test.ts commerce-trade/test/shipment.test.ts --flavor=normal
+      - name: run Commerce payment, shipment, and refund lifecycle gate
+        run: DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/paymentOutcome.test.ts commerce-trade/test/reservationExpiry.test.ts commerce-trade/test/shipment.test.ts commerce-trade/test/refundLifecycle.test.ts commerce-trade/test/shipmentRefundRace.test.ts --flavor=normal
         working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=pg npm run test
         working-directory: vona

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

@@ -27,8 +27,8 @@ jobs:
           version: 11.5.2
       - name: init
         run: npm run init
-      - name: run Commerce payment and shipment lifecycle gate
-        run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- commerce-trade/test/paymentOutcome.test.ts commerce-trade/test/reservationExpiry.test.ts commerce-trade/test/shipment.test.ts --flavor=normal
+      - name: run Commerce payment, shipment, and refund lifecycle gate
+        run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- commerce-trade/test/paymentOutcome.test.ts commerce-trade/test/reservationExpiry.test.ts commerce-trade/test/shipment.test.ts commerce-trade/test/refundLifecycle.test.ts --flavor=normal
         working-directory: vona
       - run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run test
         working-directory: vona

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 5.1.119
+
+### Improvements
+
+- Update the upgrade script.
+
+## 5.1.118
+
+### Features
+
+- Complete refund lifecycle coverage for commerce workflows.
+- Add metrics support.
+- Update application functionality and dependencies.
+
+### Improvements
+
+- Extract the scene test lock into `vona-mock`.
+- Update the pnPM lockfile and environment configuration.
+
 ## 5.1.117
 
 ### Features

package/cabloy-docs/backend/metrics-guide.md

@@ -0,0 +1,75 @@
+# Metrics Guide
+
+Cabloy Metrics uses OpenTelemetry Metrics (OTLP/HTTP) and is disabled by default. It does not publish an application `/metrics` endpoint. A Vona application normally has several independent workers, so an in-memory Prometheus registry on the shared application port would expose only one worker per scrape.
+
+## Architecture
+
+```text
+Vona workers -> private OpenTelemetry Collector -> Prometheus exporter -> Prometheus
+```
+
+Each worker exports its own metric stream. Preserve `service.instance.id` during ingestion and aggregate workers in PromQL with `sum`, `rate`, and `histogram_quantile` as appropriate.
+
+Prometheus must scrape the Collector exporter on a private monitoring network. Do not route Collector OTLP or Prometheus exporter ports through Cloudflare or a public Nginx listener.
+
+## Enablement
+
+Inject configuration through the deployment platform. Do not commit credentials to environment files.
+
+```text
+METRICS_ENABLED=true
+METRICS_SERVICE_NAME=cabloy
+METRICS_OTLP_HTTP_URL=https://collector.internal/v1/metrics
+METRICS_OTLP_HTTP_HEADERS=Authorization=Bearer <secret>
+```
+
+Additional bounded settings are available:
+
+- `METRICS_EXPORT_INTERVAL_MS` — export cadence, default `15000`
+- `METRICS_EXPORT_TIMEOUT_MS` — one export timeout, default `10000`
+- `METRICS_RUNTIME_INTERVAL_MS` — process/runtime snapshot cadence, default `15000`
+- `METRICS_QUEUE_INTERVAL_MS` — reserved queue collection cadence, default `30000`
+- `METRICS_SNAPSHOT_CACHE_MS` — Admin snapshot cache lifetime, default `5000`
+- `METRICS_SHUTDOWN_TIMEOUT_MS` — bounded final flush time, default `4000`
+
+Invalid numeric values are clamped to safe ranges. Disabling Metrics creates no exporter or background sampler.
+
+## Initial metric families
+
+- HTTP request count, duration histogram, and active-request count
+- process uptime, RSS, heap, external memory, event-loop delay, and active Vona contexts
+- metrics observation failure counters
+
+HTTP labels are deliberately restricted to normalized method, route template, final status, and a bounded aborted marker. Literal URLs, query strings, hosts, tenant/instance names, users, request IDs, trace IDs, cookies, authorization values, Redis keys, queue job IDs, and job payloads are prohibited.
+
+HTTP duration buckets in seconds are fixed as:
+
+```text
+0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30
+```
+
+## Health probes
+
+Use these private infrastructure endpoints:
+
+| Endpoint              | Meaning                                                   |
+| --------------------- | --------------------------------------------------------- |
+| `GET /health/startup` | Vona startup completed                                    |
+| `GET /health/live`    | process is serving and not closing                        |
+| `GET /health/ready`   | startup complete plus bounded PostgreSQL and Redis checks |
+
+They return only a small status response. Collector and queue-observation failures never make the readiness probe fail.
+
+## Admin dashboard
+
+The Basic Admin **Metrics** page is available only to `systemAdmin`. It shows a redacted, short-lived runtime snapshot and clear `disabled`, `fresh`, `stale`, or `unavailable` states. It is not a Prometheus query UI and never sends browser traffic to OTLP, Collector, or probe endpoints.
+
+## Local example
+
+A loopback-only local stack is available under the repository's `observability/README.md`:
+
+```bash
+docker compose -f observability/docker-compose.metrics.yml up
+```
+
+Use it for local validation only. Production networking, TLS/mTLS, secret injection, retention, dashboards, and alert routing are operator-owned.

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

@@ -525,6 +525,117 @@ test(
   },
 );
 
+test(
+  'Phase 60: customer requests and operator executes a whole-order refund',
+  { tag: ['@web', '@admin', '@flow', '@payment', '@refund'] },
+  async ({ browser, request }, testInfo) => {
+    test.setTimeout(120_000);
+    const { context, fixture, page, pageErrors } = await createAddressThroughCustomerPage(
+      browser,
+      request,
+      testInfo,
+    );
+    try {
+      await page.goto('/commerce', { waitUntil: 'load' });
+      await expect(page.locator('html')).toHaveAttribute('data-zova-hydrated', 'commerce');
+      await expect(page.getByRole('heading', { name: 'Commerce catalogue' })).toBeVisible();
+      const productLink = page.getByRole('link', { name: 'Pour-Over Coffee Set', exact: true });
+      await expect(productLink).toBeVisible();
+      await productLink.click();
+      await expect(page).toHaveURL(/\/commerce\/product\/\d+(?:\/|$)/);
+      await expect(page.getByRole('heading', { name: 'Pour-Over Coffee Set' })).toBeVisible();
+      await expect(page.getByText('COF-SET-01')).toBeVisible();
+      await expect(page.getByText('$45.99')).toBeVisible();
+      const addResponse = waitForApiResponse(page, 'POST', '/api/commerce/trade/cart/items');
+      await page.getByRole('button', { name: 'Add to cart', exact: true }).click();
+      await addResponse;
+      await page.getByRole('link', { name: /^Cart/ }).click();
+      await expect(page).toHaveURL(/\/commerce\/cart(?:\/|$)/);
+      await page.getByRole('link', { name: 'Checkout', exact: true }).click();
+      await expect(page).toHaveURL(/\/commerce\/checkout(?:\/|$)/);
+      const addressChoice = page.getByRole('radio', { name: new RegExp(fixture.recipientName) });
+      await addressChoice.check();
+      await page.getByRole('radio', { name: 'No coupon', exact: true }).check();
+      const checkoutResponse = waitForApiResponse(page, 'POST', '/api/commerce/trade/checkout');
+      await page.getByRole('button', { name: 'Create order', exact: true }).click();
+      const checkout = (await (await checkoutResponse).json()).data;
+      const paymentResponse = waitForApiResponse(
+        page,
+        'POST',
+        new RegExp(`/api/commerce/trade/payment/${checkout.paymentAttemptId}/outcome$`),
+      );
+      await page.getByRole('button', { name: 'Payment succeeded', exact: true }).click();
+      expect((await paymentResponse).ok()).toBeTruthy();
+      await expect(page.getByText('paid · $45.99')).toBeVisible();
+
+      const requestResponse = waitForApiResponse(
+        page,
+        'POST',
+        `/api/commerce/trade/order/${checkout.orderId}/requestRefund`,
+      );
+      await page.getByPlaceholder('Reason for refund').fill('E2E refund request');
+      await page.getByRole('button', { name: 'Request refund', exact: true }).click();
+      expect((await requestResponse).ok()).toBeTruthy();
+      await expect(page.getByText('refund_requested · $45.99')).toBeVisible();
+
+      const adminContext = await browser.newContext();
+      const adminPage = await adminContext.newPage();
+      const adminPageErrors = collectPageErrors(adminPage);
+      try {
+        await adminPage.setViewportSize({ width: 1440, height: 900 });
+        await login(adminPage, '/commerce-admin/', 'admin', '123456', 'commerceAdmin');
+        await adminPage.goto('/commerce-admin/rest/resource/commerce-trade%3Aorder', {
+          waitUntil: 'load',
+        });
+        await expect(adminPage.locator('html')).toHaveAttribute(
+          'data-zova-hydrated',
+          'commerceAdmin',
+        );
+        const orderRow = adminPage
+          .getByRole('cell', { name: String(checkout.orderId), exact: true })
+          .locator('..');
+        await expect(orderRow).toBeVisible();
+        await orderRow.getByPlaceholder('Decision reason').fill('E2E approval');
+        await orderRow.getByRole('checkbox').check();
+        const approveResponse = waitForApiResponse(
+          adminPage,
+          'POST',
+          `/api/commerce/trade/order/${checkout.orderId}/approveRefund`,
+        );
+        await orderRow.getByRole('button', { name: 'Approve refund', exact: true }).click();
+        expect((await approveResponse).ok()).toBeTruthy();
+        await expect(orderRow).toContainText('refund_approved');
+        const executeResponse = waitForApiResponse(
+          adminPage,
+          'POST',
+          `/api/commerce/trade/order/${checkout.orderId}/refundOutcome`,
+        );
+        await orderRow.getByRole('button', { name: 'Execute refund', exact: true }).click();
+        expect((await executeResponse).ok()).toBeTruthy();
+        await expect(orderRow).toContainText('refunded');
+        expect(adminPageErrors).toEqual([]);
+      } finally {
+        await adminContext.close().catch(() => {});
+      }
+
+      const refundedDetailResponse = waitForApiResponse(
+        page,
+        'GET',
+        new RegExp(`/api/commerce/trade/order/viewMine/${checkout.orderId}$`),
+      );
+      await page.reload({ waitUntil: 'load' });
+      await refundedDetailResponse;
+      await expect(page.getByText('refunded · $45.99')).toBeVisible();
+      await expect(page.getByText('1 × $45.99 = $45.99')).toBeVisible();
+      await expect(page.getByRole('heading', { name: 'Shipment' })).toHaveCount(0);
+      await expect(page.getByRole('alert')).toHaveCount(0);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await context.close().catch(() => {});
+    }
+  },
+);
+
 test(
   'ATP-ADDR-01: systemAdmin inspects Address Resource without mutation controls',
   { tag: ['@admin', '@flow', '@address'] },

package/observability/README.md

@@ -0,0 +1,18 @@
+# Local Metrics Stack
+
+Start the local OpenTelemetry Collector, Prometheus, and Grafana stack:
+
+```bash
+docker compose -f observability/docker-compose.metrics.yml up
+```
+
+Enable the application metric exporter only for local development:
+
+```text
+METRICS_ENABLED=true
+METRICS_OTLP_HTTP_URL=http://127.0.0.1:4318/v1/metrics
+```
+
+Prometheus scrapes the Collector at its private exporter endpoint. Cabloy deliberately does not expose an application `/metrics` endpoint: Vona workers export independently, and the Collector preserves each worker stream before PromQL aggregates them.
+
+The published ports bind to loopback for development. Production must keep the Collector OTLP receiver and Prometheus exporter on a private workload/monitoring network, inject any OTLP credentials from the deployment secret store, and never proxy those paths through Cloudflare or the public Nginx listener.

package/observability/collector/otel-collector.yaml

@@ -0,0 +1,34 @@
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 256
+  batch:
+    timeout: 5s
+  transform/metrics_allowlist:
+    error_mode: ignore
+    metric_statements:
+      - context: datapoint
+        statements:
+          - delete_key(attributes, "http.target") where attributes["http.target"] != nil
+          - delete_key(attributes, "url.full") where attributes["url.full"] != nil
+          - delete_key(attributes, "user.id") where attributes["user.id"] != nil
+          - delete_key(attributes, "enduser.id") where attributes["enduser.id"] != nil
+
+exporters:
+  prometheus:
+    endpoint: 0.0.0.0:9464
+    resource_to_telemetry_conversion:
+      enabled: true
+
+service:
+  pipelines:
+    metrics:
+      receivers: [otlp]
+      processors: [memory_limiter, transform/metrics_allowlist, batch]
+      exporters: [prometheus]

package/observability/docker-compose.metrics.yml

@@ -0,0 +1,25 @@
+services:
+  collector:
+    image: otel/opentelemetry-collector-contrib:0.134.1
+    command: [--config=/etc/otelcol-contrib/config.yaml]
+    ports:
+      - '127.0.0.1:4318:4318'
+      - '127.0.0.1:9464:9464'
+    volumes:
+      - ./collector/otel-collector.yaml:/etc/otelcol-contrib/config.yaml:ro
+
+  prometheus:
+    image: prom/prometheus:v3.5.0
+    depends_on: [collector]
+    ports:
+      - '127.0.0.1:9090:9090'
+    volumes:
+      - ./prometheus/prometheus.yaml:/etc/prometheus/prometheus.yml:ro
+
+  grafana:
+    image: grafana/grafana:12.1.0
+    depends_on: [prometheus]
+    ports:
+      - '127.0.0.1:3000:3000'
+    volumes:
+      - ./grafana/provisioning:/etc/grafana/provisioning:ro

package/observability/grafana/provisioning/datasources/prometheus.yaml

@@ -0,0 +1,8 @@
+apiVersion: 1
+
+datasources:
+  - name: Prometheus
+    type: prometheus
+    access: proxy
+    url: http://prometheus:9090
+    isDefault: true

package/observability/prometheus/prometheus.yaml

@@ -0,0 +1,7 @@
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: cabloy-collector
+    static_configs:
+      - targets: [collector:9464]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.117",
+  "version": "5.1.119",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/scripts/upgrade.ts

@@ -29,6 +29,7 @@ const OVERWRITE_DIRS: string[] = [
   'scripts',
   '.husky',
   'cabloy-docs',
+  'observability',
   // vona
   'vona/packages-vona',
   'vona/packages-cli',

package/vona/env/.env

@@ -34,6 +34,12 @@ LOGGER_ROTATE_DATEPATTERN = YYYY-MM-DD
 LOGGER_ROTATE_MAXSIZE = 20m
 LOGGER_ROTATE_MAXFILES = 7d
 
+# telemetry
+TELEMETRY_ENABLED = false
+
+# metrics
+METRICS_ENABLED = true
+
 # build
 
 BUILD_OUTDIR =

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.133",
+  "version": "1.1.134",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.131",
+  "version": "1.1.132",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-core",
-  "version": "5.1.34",
+  "version": "5.1.35",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona",
   "keywords": [

package/vona/packages-vona/vona-core/src/lib/framework/processWorker.ts

@@ -21,7 +21,7 @@ async function _closeInner() {
 }
 
 export function handleProcessWork() {
-  ['SIGINT', 'SIGUSR2'].forEach(signal => {
+  ['SIGINT', 'SIGTERM', 'SIGUSR2'].forEach(signal => {
     process.on(signal, async () => {
       if (__closing) return;
       __closing = true;

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-mock",
-  "version": "6.1.34",
+  "version": "6.1.35",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona mock",
   "keywords": [

package/vona/packages-vona/vona-mock/src/index.ts

@@ -4,6 +4,8 @@ import type { VonaApplication } from 'vona-core';
 import { parseModuleInfo, ParseModuleNameLevelInit } from '@cabloy/module-info-pro';
 import { useApp } from 'vona-core';
 
+export { acquireTestLock } from './lib/testLock.ts';
+
 const ParseModuleNameLevel = ParseModuleNameLevelInit + 2;
 
 export const app: VonaApplication = useApp();

package/vona/packages-vona/vona-mock/src/lib/testLock.ts

@@ -0,0 +1,21 @@
+const pendingScenes = new Map<string, Promise<void>>();
+
+export async function acquireTestLock(scene: string): Promise<() => void> {
+  const previous = pendingScenes.get(scene) ?? Promise.resolve();
+  let resolve: () => void;
+  const pending = new Promise<void>(pendingResolve => {
+    resolve = pendingResolve;
+  });
+  pendingScenes.set(scene, pending);
+  await previous;
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    resolve!();
+    if (pendingScenes.get(scene) === pending) {
+      pendingScenes.delete(scene);
+    }
+  };
+}