@tokenoftrust/storefront-runner 1.3.4-rc.3 → 1.4.0

package/apps/storefront/migrations-apps/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1784820107464,
+      "tag": "0000_fast_millenium_guard",
+      "breakpoints": true
+    }
+  ]
+}

package/apps/storefront/package.json

@@ -11,7 +11,7 @@
     "start": "astro dev",
     "prebuild": "node ../../scripts/build/copy-tenant-assets.mjs",
     "build": "astro build",
-    "preview": "wrangler dev ./dist/_worker.js/index.js",
+    "preview": "wrangler dev",
     "typecheck": "astro check && tsc --noEmit",
     "astro": "astro",
     "test": "NODE_OPTIONS=--experimental-sqlite vitest run"
@@ -19,8 +19,16 @@
   "dependencies": {
     "@astrojs/cloudflare": "^14.0.1",
     "@astrojs/preact": "^6.0.0",
+    "@fontsource/inter": "5.3.0",
+    "@fontsource/jetbrains-mono": "5.3.0",
+    "@fontsource/montserrat": "5.3.0",
+    "@fontsource/plus-jakarta-sans": "5.3.0",
+    "@fontsource/source-serif-4": "5.3.0",
+    "@fontsource/space-grotesk": "5.3.0",
+    "@fontsource/space-mono": "5.3.0",
     "@storyblok/astro": "^10.0.0",
     "@tailwindcss/vite": "^4.3.1",
+    "@tokenoftrust/private-apps-devkit": "*",
     "@tot/public-runtime": "*",
     "astro": "^7.0.3",
     "fuse.js": "^7.4.2",
@@ -31,9 +39,13 @@
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.4",
+    "@axe-core/playwright": "^4.12.1",
+    "@playwright/test": "^1.61.1",
+    "axe-core": "^4.12.1",
     "dependency-cruiser": "^18.0.0",
     "drizzle-kit": "^0.31.10",
     "drizzle-orm": "^0.45.2",
+    "tsx": "^4.22.4",
     "typescript": "^5.6.3",
     "vitest": "2.1.8",
     "wrangler": "^4.105.0"

package/apps/storefront/perf/README.md

@@ -0,0 +1,64 @@
+# Performance budgets & RUM (F14)
+
+The storefront's go-live framework enforces a performance gate. This directory
+is the **lab half** (a checked-in budget manifest + a CI-runnable assertion
+harness); the **field half** (Real User Monitoring) lives in
+`../src/lib/analytics/`.
+
+## The pieces
+
+| File | Role |
+|------|------|
+| `../src/lib/analytics/budgets.json` | **Source of truth.** Route budgets (LCP/INP/CLS p75 + JS/CSS/image/total KiB) + the third-party script allowlist. Edit here; everything derives from it. |
+| `../src/lib/analytics/perfBudgets.ts` | Typed lens + **pure** budget-assertion logic (`evaluateManifest`) + the Lighthouse-budgets exporter (`toLighthouseBudgets`). Unit-tested in `perfBudgets.test.ts`. |
+| `../src/lib/analytics/lighthouseReport.ts` | Pure adapter: a Lighthouse result (LHR JSON) → a `RouteMeasurement` the gate evaluates. Unit-tested in `lighthouseReport.test.ts`. |
+| `assert-budgets.ts` | Thin CLI: reads measurements / LHRs, runs the gate, exits non-zero on a violation. |
+| `../src/lib/analytics/webVitals.ts` | Field RUM beacon (LCP/INP/CLS from real visitors → the RUM sink). |
+| `../src/lib/analytics/rumAlert.ts` | Pure sink-side regression-alert contract; feeds F16's `core-web-vitals` monitor. Unit-tested in `rumAlert.test.ts`. |
+
+The budget numbers are enforced identically in three places, all reading the one
+manifest: the lab gate here, a Lighthouse `--budget-path` run (via
+`toLighthouseBudgets`), and the field RUM alert (`rumAlert.detectRegressions`).
+
+## Running the lab gate
+
+```bash
+# 1. emit a Lighthouse-native budgets file (feed to `lighthouse --budget-path`)
+pnpm --filter @tot/storefront perf:budgets:emit      # → perf/lighthouse-budgets.json
+
+# 2a. assert Lighthouse result JSON, one --lhr per route
+pnpm --filter @tot/storefront perf:budgets -- \
+  --lhr home=home.lhr.json --lhr pdp=pdp.lhr.json --require-all
+
+# 2b. …or assert a tool-neutral measurement report from any collector
+pnpm --filter @tot/storefront perf:budgets -- --measurements report.json
+```
+
+Exit `0` = within budget, `1` = a budget was violated (or, with `--require-all`,
+a budgeted route was never measured), `2` = bad usage.
+
+## Preview-validation seam (live lab run — follow-up)
+
+The pure logic (gate + LHR extraction) is **green in CI today** via the unit
+tests. Wiring an actual Lighthouse run against a live preview URL is the
+remaining step:
+
+1. `perf:budgets:emit` → `lighthouse-budgets.json`.
+2. For each route's `samplePath`, run Lighthouse against the preview URL with
+   `--budget-path=perf/lighthouse-budgets.json --output=json`, saving each LHR.
+3. `perf:budgets --lhr <route>=<lhr.json> … --require-all` — its exit code gates
+   the preview promotion.
+
+Add step 2's Lighthouse invocation to the preview-validation workflow (or LHCI)
+to make the gate enforce against real page loads. Until then the manifest,
+exporter, extractor, and gate are all covered by unit tests so the numbers can't
+silently drift.
+
+## Field RUM
+
+`startWebVitals()` (from `../src/lib/analytics/webVitals.ts`) is called from the
+client entry; it measures LCP/INP/CLS per real navigation, buckets each into the
+same budgeted route id the lab gate uses, and beacons finished samples to the RUM
+sink (`RUM_BEACON_PATH`). The sink rolls samples up per route/hour and calls
+`rumAlert.detectRegressions()`; any returned `RegressionAlert` trips F16's
+`core-web-vitals` monitor.

package/apps/storefront/perf/assert-budgets.ts

@@ -0,0 +1,159 @@
+/**
+ * F14 — Lab budget-assertion harness (the enforceable lab check).
+ *
+ * This is the thin CLI seam that preview validation calls to FAIL a build whose
+ * pages blow the performance budgets. All the decision logic lives in the pure,
+ * unit-tested modules under `src/lib/analytics/` — this file only does I/O:
+ * read a measurement report (or Lighthouse results), run the gate, print, exit.
+ *
+ *   exit 0 → every measured route is within budget
+ *   exit 1 → at least one budget violated (or, with --require-all, a route was
+ *            never measured)
+ *   exit 2 → bad usage / unreadable input
+ *
+ * Modes
+ * -----
+ *   Emit the Lighthouse budgets file (feed it to `lighthouse --budget-path` /
+ *   LHCI so Lighthouse enforces the same numbers directly):
+ *     tsx perf/assert-budgets.ts --emit-lighthouse-budgets perf/lighthouse-budgets.json
+ *
+ *   Assert a tool-neutral measurement report (array of RouteMeasurement, or
+ *   `{ "measurements": [...] }`), from any collector:
+ *     tsx perf/assert-budgets.ts --measurements report.json [--require-all]
+ *
+ *   Assert Lighthouse result JSON files, one per route (`--lhr <routeId>=<lhr.json>`,
+ *   repeatable):
+ *     tsx perf/assert-budgets.ts --lhr home=home.lhr.json --lhr pdp=pdp.lhr.json
+ *
+ * How preview validation wires this (documented seam — the live run is a
+ * follow-up; the LOGIC is green in CI via the unit tests):
+ *   1. `pnpm --filter @tot/storefront perf:budgets:emit`  → lighthouse-budgets.json
+ *   2. run Lighthouse against the preview URL per route with `--budget-path` +
+ *      `--output=json`, saving each LHR
+ *   3. `tsx perf/assert-budgets.ts --lhr home=... --lhr pdp=... --require-all`
+ *   Step 3's exit code gates the preview promotion.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import {
+  evaluateManifest,
+  formatBudgetReport,
+  toLighthouseBudgets,
+  ROUTE_IDS,
+  type RouteId,
+  type RouteMeasurement,
+} from "../src/lib/analytics/perfBudgets.js";
+import { lhrToMeasurement, type LighthouseResult } from "../src/lib/analytics/lighthouseReport.js";
+
+function die(msg: string, code = 2): never {
+  process.stderr.write(`assert-budgets: ${msg}\n`);
+  process.exit(code);
+}
+
+function readJson(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    return die(`cannot read/parse ${path}: ${(err as Error).message}`);
+  }
+}
+
+function isRouteId(v: string): v is RouteId {
+  return (ROUTE_IDS as readonly string[]).includes(v);
+}
+
+function parseArgs(argv: readonly string[]) {
+  const opts = {
+    emit: undefined as string | undefined,
+    measurements: undefined as string | undefined,
+    lhr: [] as Array<{ route: RouteId; path: string }>,
+    requireAll: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--emit-lighthouse-budgets":
+        opts.emit = argv[++i] ?? die("--emit-lighthouse-budgets needs a path");
+        break;
+      case "--measurements":
+        opts.measurements = argv[++i] ?? die("--measurements needs a path");
+        break;
+      case "--lhr": {
+        const spec = argv[++i] ?? die("--lhr needs <routeId>=<path>");
+        const eq = spec.indexOf("=");
+        if (eq < 0) die(`--lhr expects <routeId>=<path>, got "${spec}"`);
+        const route = spec.slice(0, eq);
+        if (!isRouteId(route)) die(`--lhr: "${route}" is not a known route id`);
+        opts.lhr.push({ route, path: spec.slice(eq + 1) });
+        break;
+      }
+      case "--require-all":
+        opts.requireAll = true;
+        break;
+      case "-h":
+      case "--help":
+        process.stdout.write(
+          "usage: assert-budgets.ts [--emit-lighthouse-budgets <path>] " +
+            "[--measurements <path>] [--lhr <routeId>=<path> ...] [--require-all]\n",
+        );
+        process.exit(0);
+      default:
+        die(`unknown argument "${a}"`);
+    }
+  }
+  return opts;
+}
+
+function collectMeasurements(opts: ReturnType<typeof parseArgs>): RouteMeasurement[] {
+  const measurements: RouteMeasurement[] = [];
+
+  if (opts.measurements) {
+    const raw = readJson(opts.measurements);
+    const arr = Array.isArray(raw)
+      ? raw
+      : raw && typeof raw === "object" && Array.isArray((raw as { measurements?: unknown }).measurements)
+        ? (raw as { measurements: unknown[] }).measurements
+        : die(`${opts.measurements}: expected an array or { "measurements": [...] }`);
+    for (const m of arr as RouteMeasurement[]) {
+      if (!m || typeof m !== "object" || !isRouteId((m as RouteMeasurement).routeId)) {
+        die(`${opts.measurements}: every entry needs a valid "routeId"`);
+      }
+      measurements.push(m as RouteMeasurement);
+    }
+  }
+
+  for (const { route, path } of opts.lhr) {
+    measurements.push(lhrToMeasurement(readJson(path) as LighthouseResult, route));
+  }
+
+  return measurements;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.emit) {
+    writeFileSync(opts.emit, JSON.stringify(toLighthouseBudgets(), null, 2) + "\n");
+    process.stdout.write(`assert-budgets: wrote Lighthouse budgets → ${opts.emit}\n`);
+    return;
+  }
+
+  const measurements = collectMeasurements(opts);
+  if (measurements.length === 0) {
+    die("no measurements: pass --measurements <path> and/or --lhr <routeId>=<path>");
+  }
+
+  const report = evaluateManifest(measurements);
+  process.stdout.write(formatBudgetReport(report) + "\n");
+
+  const missingFatal = opts.requireAll && report.missingRoutes.length > 0;
+  if (!report.passed || missingFatal) {
+    if (missingFatal) {
+      process.stderr.write(
+        `assert-budgets: --require-all set but no measurement for: ${report.missingRoutes.join(", ")}\n`,
+      );
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/apps/storefront/playwright.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig } from "@playwright/test";
+import { PARENT_PORT } from "./e2e/fixtures/ports.ts";
+
+/**
+ * PrivateApps epic, D5 Chunk F. The storefront has no prior Playwright setup
+ * (`packages/migration` depends on `playwright-core` for its own screenshot
+ * tooling, not a `@playwright/test` runner) — this is the first. Scoped to
+ * `e2e/` and, for now, the one widget-sandbox spec: see `e2e/fixtures/server.ts`
+ * for the "why a fixture server, not the full Cloudflare Worker" scope decision.
+ */
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: false,
+  reporter: "list",
+  use: {
+    baseURL: `http://127.0.0.1:${PARENT_PORT}`,
+  },
+  webServer: {
+    command: "npx tsx e2e/fixtures/server.ts",
+    url: `http://127.0.0.1:${PARENT_PORT}`,
+    timeout: 15_000,
+  },
+});

package/apps/storefront/public/js/dashboard-apps.js

@@ -0,0 +1,173 @@
+/**
+ * Client behavior for /dashboard/<appDomain>/apps (PrivateApps epic, D8 Chunk C).
+ *
+ * Served as a STATIC same-origin file (public/) and referenced via
+ * <script src="/js/dashboard-apps.js">, so the strict production CSP allows it via
+ * `script-src 'self'` — no nonce, no per-build hash. Mirrors dashboard-team.js exactly.
+ *
+ * The tenant appDomain and the manage-capability are read from the #apps
+ * container's `data-tenant`/`data-can-manage` attributes (server-resolved from
+ * the SAME `MANAGE_ROLES` set the admin routes gate on) — no server-injected
+ * values beyond those two, so this file is fully static.
+ */
+(function () {
+  const $ = (id) => document.getElementById(id);
+  const container = $("apps");
+  if (!container) return;
+  const tenant = container.dataset.tenant;
+  const canManage = container.dataset.canManage === "true";
+
+  function fmtDuration(ms) {
+    if (ms == null) return "—";
+    return ms >= 1000 ? (ms / 1000).toFixed(1) + "s" : ms + "ms";
+  }
+
+  function badge(text, cls) {
+    const span = document.createElement("span");
+    span.className = "badge " + cls;
+    span.textContent = text;
+    return span;
+  }
+
+  function renderApp(app) {
+    const card = document.createElement("div");
+    card.className = "card";
+
+    const top = document.createElement("div");
+    top.className = "top";
+    const name = document.createElement("span");
+    name.className = "name";
+    name.textContent = app.appId;
+    top.appendChild(name);
+    const badges = document.createElement("div");
+    badges.appendChild(badge(app.status, "status-" + app.status));
+    badges.appendChild(badge(app.health.status, "health-" + app.health.status));
+    badges.appendChild(badge(app.egressStatus, "egress-" + app.egressStatus));
+    top.appendChild(badges);
+    card.appendChild(top);
+
+    const dl = document.createElement("dl");
+    dl.className = "meta";
+    function row(term, value) {
+      const dt = document.createElement("dt");
+      dt.textContent = term;
+      const dd = document.createElement("dd");
+      dd.textContent = value;
+      dl.appendChild(dt);
+      dl.appendChild(dd);
+    }
+    row("Env", app.env);
+    row("Scopes", (app.scopes || []).join(", ") || "none");
+    row("Webhook", app.hasWebhookEndpoint ? "configured" : "not configured");
+    row("p95 delivery", fmtDuration(app.health.p95DeliveryMs));
+    row("Failure streak", String(app.health.failureStreak));
+    row("Dead-lettered", String(app.health.dlqCount));
+    if (app.health.lastSuccessAt) row("Last success", app.health.lastSuccessAt);
+    card.appendChild(dl);
+
+    if (app.health.recentTraceIds && app.health.recentTraceIds.length) {
+      const traces = document.createElement("p");
+      traces.className = "traces";
+      traces.textContent = "Recent traces: " + app.health.recentTraceIds.join(", ");
+      card.appendChild(traces);
+    }
+
+    if (canManage) {
+      const actions = document.createElement("div");
+      actions.className = "actions";
+
+      if (app.status === "active") {
+        actions.appendChild(actionBtn("Suspend", "suspend", app.id, card, false));
+      } else if (app.status === "suspended") {
+        actions.appendChild(actionBtn("Resume", "resume", app.id, card, false));
+      }
+      if (app.status !== "uninstalled") {
+        actions.appendChild(actionBtn("Rotate credentials", "credentials/rotate", app.id, card, false));
+        actions.appendChild(actionBtn("Uninstall", "uninstall", app.id, card, true));
+      }
+      card.appendChild(actions);
+
+      const msg = document.createElement("div");
+      msg.className = "msg";
+      card.appendChild(msg);
+    }
+
+    return card;
+  }
+
+  function actionBtn(label, action, installId, card, danger) {
+    const btn = document.createElement("button");
+    btn.type = "button";
+    btn.className = "rowbtn" + (danger ? " danger" : "");
+    btn.textContent = label;
+    btn.addEventListener("click", () => runAction(action, installId, card, btn));
+    return btn;
+  }
+
+  async function runAction(action, installId, card, btn) {
+    const msg = card.querySelector(".msg");
+    btn.disabled = true;
+    if (msg) { msg.className = "msg"; msg.textContent = ""; }
+    try {
+      const res = await fetch("/api/apps/admin/" + action + "?tenant=" + encodeURIComponent(tenant), {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({ installId }),
+      });
+      const body = await res.json().catch(() => ({}));
+      if (res.ok) {
+        loadApps();
+      } else if (msg) {
+        msg.className = "msg err";
+        msg.textContent = body.error || ("Couldn't " + action + " (HTTP " + res.status + ").");
+        btn.disabled = false;
+      }
+    } catch (e) {
+      if (msg) {
+        msg.className = "msg err";
+        msg.textContent = "Couldn't " + action + ": " + (e && e.message ? e.message : e);
+      }
+      btn.disabled = false;
+    }
+  }
+
+  function renderApps(apps) {
+    container.replaceChildren();
+    if (!apps || !apps.length) {
+      const p = document.createElement("p");
+      p.className = "muted";
+      p.textContent = "No apps installed yet.";
+      container.appendChild(p);
+      return;
+    }
+    for (const app of apps) container.appendChild(renderApp(app));
+  }
+
+  function renderError(text) {
+    container.replaceChildren();
+    const p = document.createElement("p");
+    p.className = "muted";
+    p.textContent = text;
+    container.appendChild(p);
+  }
+
+  async function loadApps() {
+    try {
+      const res = await fetch("/api/apps/admin/health?tenant=" + encodeURIComponent(tenant), {
+        headers: { accept: "application/json" },
+      });
+      const body = await res.json().catch(() => ({}));
+      if (res.ok) {
+        renderApps(body.apps);
+      } else if (res.status === 403) {
+        renderError("You don't have access to this vendor's apps.");
+      } else {
+        renderError(body.error || ("Couldn't load apps (HTTP " + res.status + ")."));
+      }
+    } catch (e) {
+      renderError("Couldn't load apps: " + (e && e.message ? e.message : e));
+    }
+  }
+
+  loadApps();
+})();