Eng#2: Lock CI gates and publish QA (#5)

* docs(api): regenerate OpenAPI spec

* feat: make assets pipeline deterministic

* docs(qa): refresh QA.md with perf p50/p95, viewer budgets, and CI artifact links

Author: shayancoin

.github/workflows/perf-light.yml

@@ -0,0 +1,101 @@
+name: perf-light
+
+on:
+  pull_request: {}
+
+jobs:
+  k6:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    concurrency:
+      group: perf-${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install k6
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y k6
+
+      - name: Start stack
+        run: |
+          cd paform
+          docker compose --env-file .env.development -f docker-compose.dev.yml up -d --build
+
+      - name: Wait for API
+        run: |
+          cd paform
+          for i in {1..60}; do curl -sf http://localhost:8000/healthcheck && break || sleep 2; done
+
+      - name: Wait for Frontend
+        run: |
+          for i in {1..60}; do curl -sf http://localhost:3000/models/manifest.json && break || sleep 2; done
+
+      - name: Seed backend for perf
+        env:
+          BASE_URL: http://localhost:8000
+        run: |
+          cd paform
+          python - <<'PY'
+import json
+import os
+import urllib.error
+import urllib.request
+
+BASE_URL = os.environ.get("BASE_URL", "http://localhost:8000")
+
+def post(path: str, payload: dict) -> dict:
+    req = urllib.request.Request(
+        f"{BASE_URL}{path}",
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "ignore")
+        raise SystemExit(f"Seed request failed ({exc.code}): {detail}")
+
+material = post(
+    "/api/materials/",
+    {"name": "Walnut", "texture_url": None, "cost_per_sq_ft": 12.5},
+)
+material_id = material.get("id")
+if not material_id:
+    raise SystemExit("Material creation failed; missing id")
+
+post(
+    "/api/modules/",
+    {
+        "name": "Base600",
+        "width": 600.0,
+        "height": 720.0,
+        "depth": 580.0,
+        "base_price": 100.0,
+        "material_id": material_id,
+    },
+)
+PY
+
+      - name: Run k6 light profile
+        env:
+          BASE_URL: http://localhost:8000
+          FRONTEND_BASE_URL: http://localhost:3000
+        run: |
+          cd paform
+          k6 run --summary-export k6-summary.json tests/perf/k6-quote-cnc.js
+
+      - name: Upload k6 summary
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: k6-summary
+          path: paform/k6-summary.json
+
+      - name: Shutdown stack
+        if: always()
+        run: |
+          cd paform
+          docker compose --env-file .env.development -f docker-compose.dev.yml down

backend/tests/test_error_envelopes.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from api.main import app
+
+
+client = TestClient(app)
+
+
+def _is_error_shape(payload: dict) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    if payload.get('ok') is not False:
+        return False
+    error = payload.get('error')
+    return isinstance(error, dict) and 'code' in error and 'message' in error
+
+
+def test_quote_invalid_payload_envelope() -> None:
+    response = client.post(
+        '/api/quote/generate',
+        data='not-json',
+        headers={'Content-Type': 'application/json'},
+    )
+    assert response.status_code in (400, 422)
+    assert _is_error_shape(response.json())
+
+
+def test_cnc_invalid_payload_envelope() -> None:
+    response = client.post(
+        '/api/cnc/export',
+        data='not-json',
+        headers={'Content-Type': 'application/json'},
+    )
+    assert response.status_code in (400, 422)
+    assert _is_error_shape(response.json())

frontend/playwright.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  timeout: 30_000,
+  expect: { timeout: 15_000 },
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    headless: true,
+    trace: 'retain-on-failure',
+    launchOptions: {
+      args: [
+        '--ignore-gpu-blocklist',
+        '--use-gl=swiftshader',
+        '--enable-webgl',
+        '--disable-gpu-sandbox',
+        '--disable-web-security', // allow wasm decoders to initialise in CI
+      ],
+    },
+  },
+});

frontend/tests/e2e/cache.spec.ts

@@ -0,0 +1,21 @@
+import { test, expect } from '@playwright/test';
+
+test('static asset cache headers from manifest', async ({ request }) => {
+  const manifestResponse = await request.get('/models/manifest.json');
+  expect(manifestResponse.ok()).toBeTruthy();
+  const data = await manifestResponse.json();
+  const first = (data?.models || [])[0];
+  expect(first?.file).toBeTruthy();
+
+  const filePath = first.file as string;
+  const assetResponse = await request.get(filePath);
+  expect(assetResponse.status()).toBe(200);
+  const cacheControl = assetResponse.headers()['cache-control'] || '';
+  expect(cacheControl).toMatch(/immutable/);
+
+  const etag = assetResponse.headers()['etag'];
+  if (etag) {
+    const cached = await request.get(filePath, { headers: { 'If-None-Match': etag } });
+    expect([200, 304]).toContain(cached.status());
+  }
+});

tests/perf/k6-quote-cnc.js

@@ -0,0 +1,128 @@
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  vus: 5,
+  duration: '30s',
+  thresholds: {
+    http_req_failed: ['rate<0.01'],
+    http_req_duration: ['p(95)<150'],
+  },
+};
+
+const baseUrl = __ENV.BASE_URL || 'http://localhost:8000';
+const feBase = __ENV.FRONTEND_BASE_URL || '';
+
+function createMaterialAndModule() {
+  const suffix = `${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+  const headers = { 'Content-Type': 'application/json' };
+  const materialRes = http.post(
+    `${baseUrl}/api/materials/`,
+    JSON.stringify({
+      name: `Walnut-${suffix}`,
+      texture_url: null,
+      cost_per_sq_ft: 12.5,
+    }),
+    { headers }
+  );
+  check(materialRes, { 'material created': (r) => r.status === 200 });
+  const materialId = materialRes.json('id');
+
+  const moduleRes = http.post(
+    `${baseUrl}/api/modules/`,
+    JSON.stringify({
+      name: `Base600-${suffix}`,
+      width: 600.0,
+      height: 720.0,
+      depth: 580.0,
+      base_price: 100.0,
+      material_id: materialId,
+    }),
+    { headers }
+  );
+  check(moduleRes, { 'module created': (r) => r.status === 200 });
+  const moduleId = moduleRes.json('id');
+
+  return { materialId, moduleId };
+}
+
+export function setup() {
+  return createMaterialAndModule();
+}
+
+function buildPayload(moduleId) {
+  const configuration = {
+    room: {
+      length_mm: 4200,
+      width_mm: 3200,
+      height_mm: 2700,
+      bulkheads: [],
+      openings: [],
+    },
+    placements: [
+      {
+        placement_id: 'p1',
+        module_id: moduleId,
+        quantity: 1,
+        wall: 'north',
+        position_mm: 100,
+        elevation_mm: 0,
+        rotation_deg: 0,
+      },
+    ],
+  };
+
+  return {
+    quote: JSON.stringify({ configuration }),
+    cnc: JSON.stringify({
+      configuration_id: 'cfg-1',
+      configuration,
+      include_csv: true,
+    }),
+  };
+}
+
+export default function (data) {
+  const headers = { 'Content-Type': 'application/json' };
+  const moduleId = data?.moduleId || createMaterialAndModule().moduleId;
+  const payloads = buildPayload(moduleId);
+
+  const quoteResponse = http.post(`${baseUrl}/api/quote/generate`, payloads.quote, {
+    headers,
+  });
+  check(quoteResponse, { 'quote 200': (r) => r.status === 200 });
+
+  const cncResponse = http.post(`${baseUrl}/api/cnc/export`, payloads.cnc, {
+    headers,
+  });
+  check(cncResponse, {
+    'cnc 200 + csv': (r) => r.status === 200 && r.json('csv'),
+  });
+
+  if (feBase) {
+    const manifestResponse = http.get(`${feBase}/models/manifest.json`);
+    check(manifestResponse, { 'manifest 200': (r) => r.status === 200 });
+    try {
+      const manifest = manifestResponse.json();
+      const file = manifest?.models?.[0]?.file;
+      if (file) {
+        const asset = http.get(`${feBase}${file}`);
+        check(asset, {
+          'model 200 + immutable': (r) => {
+            const header = r.headers['Cache-Control'] || r.headers['cache-control'] || '';
+            return r.status === 200 && String(header).includes('immutable');
+          },
+        });
+        const etag = asset.headers['Etag'] || asset.headers['ETag'];
+        if (etag) {
+          const cached = http.get(`${feBase}${file}`, { headers: { 'If-None-Match': etag } });
+          check(cached, { 'model cache 200/304': (r) => r.status === 304 || r.status === 200 });
+        }
+      }
+    } catch (err) {
+      // Ignore JSON parsing issues so perf run can continue.
+    }
+  }
+
+  sleep(0.5);
+}