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

package/apps/storefront/astro.config.mjs

@@ -64,6 +64,21 @@ import { tenantHotReload } from "./dev-plugins/tenant-hot-reload.mjs";
 // facets, search typeahead, mobile drawer) — near-zero JS everywhere else.
 export default defineConfig({
   output: "server",
+  // Prefetch (finding 5): every nav today is a cold MPA reload. Enable Astro's
+  // prefetch so key navigation + product-card links warm the next SSR response
+  // on intent. OPT-IN (prefetchAll:false) — only links carrying
+  // `data-astro-prefetch` prefetch (nav items, product/collection cards), so we
+  // don't blanket-fetch cart/auth/account/wishlist or over-fetch on load. The
+  // 'hover' default strategy fires on mouseenter/focus (intent-driven, cheap on
+  // bandwidth), degrading to tap on touch. Works on output:'server' with NO
+  // prerendered pages — prefetch just issues the same GET the click would.
+  // NOTE: this is prefetch WITHOUT View Transitions; no <ClientRouter> is added
+  // (see DECISIONS — it would need every once-run island/inline script rewired
+  // to astro:page-load and risks the CSP-nonce/age-gate paths).
+  prefetch: {
+    prefetchAll: false,
+    defaultStrategy: "hover",
+  },
   // Externalize all CSS (no auto-inlined <style>) so a strict CSP needs no
   // inline-style allowance for elements — every stylesheet is a 'self' <link>.
   // Small first-paint tradeoff, offset by cross-page caching (see LIMITATIONS).

package/apps/storefront/dev-plugins/dev-publish.mjs

@@ -0,0 +1,55 @@
+// @ts-check
+import { handlePublish } from "../../../scripts/dev/publish.mjs";
+
+// C5 · Publish in browser — server side. Dev-only (`apply: "serve"`), never
+// reaches the production Worker. Maps POST /__tot/publish {path} onto the
+// candidate_open flow in scripts/dev/publish.mjs — the local-loop counterpart
+// to the hosted cockpit's /api/dev/publish.ts (unit s6), reusing the SAME
+// per-actor deriveChangeId idempotency `tot submit` relies on so repeat
+// publishes update ONE PR instead of piling up duplicates.
+
+/** @param {any} req @returns {Promise<string>} */
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (/** @type {any} */ c) => {
+      data += c;
+      if (data.length > 4 * 1024 * 1024) req.destroy();
+    });
+    req.on("end", () => resolve(data));
+    req.on("error", () => resolve(data));
+  });
+}
+
+export function devPublish() {
+  /** @type {any} */
+  const plugin = {
+    name: "tot:dev-publish",
+    apply: "serve",
+    /** @param {any} server */
+    configureServer(server) {
+      server.middlewares.use(
+        async (/** @type {any} */ req, /** @type {any} */ res, /** @type {any} */ next) => {
+          if (req.method !== "POST" || !req.url || req.url.split("?")[0] !== "/__tot/publish") {
+            return next();
+          }
+          let body;
+          try {
+            body = JSON.parse((await readBody(req)) || "{}");
+          } catch {
+            res.statusCode = 400;
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify({ ok: false, status: "bad_json", message: "invalid JSON body" }));
+            return;
+          }
+          const out = await handlePublish(process.env, body);
+          res.statusCode = out.status;
+          res.setHeader("content-type", "application/json");
+          res.setHeader("cache-control", "no-store");
+          res.end(JSON.stringify(out.json));
+        },
+      );
+    },
+  };
+  return plugin;
+}

package/apps/storefront/dev-plugins/tenant-hot-reload.mjs

@@ -1,8 +1,10 @@
 // @ts-check
 import { fileURLToPath } from "node:url";
 import { readdirSync, existsSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { markSave, reportServerUp } from "./dev-loop-state.mjs";
+import { isTransientWatchFile } from "../../../scripts/dev/transient-files.mjs";
+import { readFile } from "node:fs/promises";
 
 // Repo-root tenants/ dir (colocated tenant layout) + the generated static dest
 // the predev copy step mirrors public/ into. This module lives at
@@ -11,11 +13,40 @@ import { markSave, reportServerUp } from "./dev-loop-state.mjs";
 const TENANTS_DIR = fileURLToPath(new URL("../../../tenants", import.meta.url)).replace(/\\/g, "/");
 const PUBLIC_TENANTS_DEST = fileURLToPath(new URL("../public/tenants", import.meta.url));
 
+/**
+ * Load a TS module's exports for Node-side (plugin) use, reusing Vite's own
+ * transform pipeline instead of a plain `import` (which can't parse `.ts`) or
+ * `ssrLoadModule` (which requires the 'ssr' environment to be Node-runnable —
+ * it isn't here, since the Cloudflare adapter's ssr environment runs in
+ * workerd). `src/themes/schema.ts` and `reference.ts` only ever import types
+ * (fully erased by the transform), so the transformed output has zero runtime
+ * imports left to resolve — safe to eval directly via a data: URL import.
+ * @param {any} server @param {string} url
+ */
+async function loadTsModule(server, url) {
+  const result = await server.transformRequest(url);
+  if (!result) throw new Error(`transformRequest returned nothing for ${url}`);
+  // Vite's dev transform prepends module-graph bookkeeping imports (e.g. a
+  // preact-debug preamble, HMR deps) that only resolve inside Vite's own
+  // module graph, not a bare data: URL import. schema.ts/reference.ts only
+  // ever import types (fully erased already), so stripping every top-level
+  // `import ...;` line leaves the real, self-contained function/const
+  // exports intact.
+  const code = result.code.replace(/^import\s.*;\s*$/gm, "");
+  const dataUrl = `data:text/javascript;base64,${Buffer.from(code, "utf8").toString("base64")}`;
+  return import(dataUrl);
+}
+
 /**
  * Classify a watched absolute path as a tenant file: → { id, rest } where `rest`
  * is tenant-relative posix ("content/home.html", "public/logo.png"), or null if
- * the path isn't under a tenant. Shared by handleHotUpdate (change) and the
- * add/unlink watcher handlers so both agree on the content/-vs-public/ split.
+ * the path isn't under a tenant OR is an editor/OS transient file (vim swap,
+ * emacs autosave, `.DS_Store`, a dotfile, …) — those are watcher noise, not real
+ * content, so neither reload logic nor the activity Monitor should ever see them
+ * (a vim `.home.html.swp` add/change/unlink was leaking into the developer's
+ * "Your activity" ledger before this check). Shared by handleHotUpdate (change)
+ * and the add/unlink watcher handlers so both agree on the content/-vs-public/
+ * split — and on what counts as noise.
  * @param {string} file
  * @returns {{ id: string, rest: string } | null}
  */
@@ -25,7 +56,9 @@ export function classifyTenantFile(file) {
   const rel = f.slice(TENANTS_DIR.length + 1); // "<id>/<...>"
   const slash = rel.indexOf("/");
   if (slash < 0) return null;
-  return { id: rel.slice(0, slash), rest: rel.slice(slash + 1) };
+  const rest = rel.slice(slash + 1);
+  if (isTransientWatchFile(basename(rest))) return null;
+  return { id: rel.slice(0, slash), rest };
 }
 
 /** True for the raw content HTML that's read fresh from disk per request. @param {string} rest */
@@ -33,6 +66,22 @@ export function isContentHtml(rest) {
   return rest.startsWith("content/") && rest.endsWith(".html");
 }
 
+/**
+ * Strip the documentation keys (`_vendor`, `_note`, `$schema`, …) a tenant's
+ * theme.json may carry, mirroring src/themes/tenants/index.ts's stripMeta
+ * exactly — both must agree on what counts as a real token vs. a comment key.
+ * @param {Record<string, unknown>} parsed
+ */
+export function stripThemeMeta(parsed) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [k, v] of Object.entries(parsed)) {
+    if (k.startsWith("_") || k.startsWith("$")) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
 /**
  * Is this tenant opted out of static-asset mirroring (R2-versioned)? Matches
  * scripts/build/copy-tenant-assets.mjs's isVersioned EXACTLY (both the marker
@@ -120,9 +169,12 @@ export function seedKnown(root, known) {
 //     rawHtmlResponse in src/lib/rawMarketingHtml.ts.)
 //   - public/**        — re-mirror the one changed asset into public/tenants/<id>/
 //     (skipping R2-versioned tenants, like copy-tenant-assets.mjs), then reload.
-// content/*.json, themes/*.json and theme.json are ordinary glob imports, so Vite
-// already invalidates + reloads them — left to default handling. Returning []
-// suppresses the pointless glob HMR that would otherwise fire for the raw files.
+// content/*.json and other themes/*.json globs are ordinary glob imports, so
+// Vite already invalidates + reloads them — left to default handling. A
+// tenant's own theme.json (D1) is the one exception: instead of the default
+// reload, handleHotUpdate below recomputes its CSS vars and patches them into
+// the open page in place. Returning [] suppresses the pointless glob HMR that
+// would otherwise fire for the raw files.
 //
 // RENAME/DELETE (C2): handleHotUpdate fires only on "change". Empirically, an
 // add/unlink of a content/*.html file already triggers a correct Vite full-reload
@@ -231,6 +283,33 @@ export function tenantHotReload() {
         return [];
       }
 
+      // theme.json (D1): the only thing a save actually changes is the CSS
+      // custom-property values themeToCssVars() already serializes per request
+      // — recompute them the SAME way the SSR path does (middleware/index.ts)
+      // and patch them into the open page in place instead of reloading it.
+      // mergeTheme/themeToCssVars live in src/themes/schema.ts, a TS module
+      // only reachable through Vite's own transform pipeline — a plain Node
+      // `import` from this .mjs file can't load it, and `ssrLoadModule`
+      // requires the 'ssr' environment to be Node-runnable, which it isn't
+      // under the Cloudflare adapter (that environment runs in workerd). So
+      // loadTsModule() reuses the transform pipeline directly instead.
+      if (rest === "theme.json") {
+        try {
+          const raw = await readFile(ctx.file, "utf8");
+          const override = stripThemeMeta(JSON.parse(raw));
+          const { mergeTheme, themeToCssVars } = await loadTsModule(ctx.server, "/src/themes/schema.ts");
+          const { referenceTheme } = await loadTsModule(ctx.server, "/src/themes/reference.ts");
+          const css = themeToCssVars(mergeTheme(referenceTheme, override));
+          ctx.server.ws.send({ type: "custom", event: "tot:theme-vars", data: { css } });
+          return [];
+        } catch {
+          // Malformed theme.json mid-edit, or the module graph failed to
+          // load — degrade to the default full-reload rather than leaving
+          // the page on stale CSS vars or hanging silently.
+          return undefined;
+        }
+      }
+
       return undefined;
     },
   };

package/apps/storefront/drizzle.config.apps.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "drizzle-kit";
+
+// Generate-only config for the STOREFRONT_APPS_DB lineage — sibling to
+// drizzle.config.ts (catalog). Same dialect/driver; diffs schema-apps.ts into
+// numbered SQL under migrations-apps/, which `wrangler d1 migrations apply
+// STOREFRONT_APPS_DB` runs. Kept as a separate config (not a second `schema`
+// entry on the catalog config) so each D1 gets its own independent migration
+// lineage/journal — the whole point of splitting the database.
+export default defineConfig({
+  dialect: "sqlite",
+  schema: "./src/lib/d1/schema-apps.ts",
+  out: "./migrations-apps",
+});

package/apps/storefront/env.d.ts

@@ -159,6 +159,16 @@ declare global {
       };
       /** Cloudflare runtime (env bindings) — provided by the adapter on Workers. */
       runtime?: { env: CloudflareEnv };
+      /**
+       * Every private-app widget placement actually rendered for this request
+       * (PrivateApps epic, D5). The middleware seeds this to `[]` before
+       * `next()`; each page/layout that renders a widget slot (`renderSlot.ts`)
+       * pushes its resolved placements onto it as the page renders, so the
+       * middleware can read the full per-request set back out AFTER `next()`
+       * to extend the CSP's `frame-src` (`appWidgetCspAdditions`) with exactly
+       * the origins that ended up on the page — never more.
+       */
+      activeWidgetPlacements?: { endpoint: string }[];
     }
   }
 }

package/apps/storefront/migrations/README.md

@@ -1,14 +1,19 @@
 # D1 provision migrations (Drizzle Kit)
 
-The catalog + customization D1 schema as numbered migrations, applied by `provision.sh`
-(the **provision** lifecycle phase — never `deploy`, never runtime). Generated by
-**Drizzle Kit** (ADR-0002), applied by `wrangler d1 migrations apply`.
+The catalog + customization D1 (`CATALOG_DB`) schema as numbered migrations, applied by
+`provision.sh` (the **provision** lifecycle phase — never `deploy`, never runtime). Generated
+by **Drizzle Kit** (ADR-0002), applied by `wrangler d1 migrations apply`.
+
+> The storefront-apps registry/webhooks/orders tables have their OWN D1
+> (`STOREFRONT_APPS_DB`) + config (`drizzle.config.apps.ts`) + lineage
+> (`../migrations-apps/`) — this directory holds ONLY catalog + customization.
 
 ## Source of truth
 
-- **`src/lib/d1/schema.ts`** (Drizzle schema) is the source of truth for migration
-  *generation*. `drizzle-kit generate` diffs it into numbered `migrations/*.sql`
-  (+ `meta/` journal) and owns the SQLite table-rebuild logic for `ALTER`s.
+- **`src/lib/d1/schema.ts`** (Drizzle schema, catalog + customization ONLY) is the
+  source of truth for migration *generation*. `drizzle-kit generate` diffs it into
+  numbered `migrations/*.sql` (+ `meta/` journal) and owns the SQLite table-rebuild
+  logic for `ALTER`s.
 - **`products_fts`** (FTS5 virtual table) can't be modelled by Drizzle — it's a custom
   migration (`0001_products_fts.sql`), hand-maintained.
 - The raw-SQL read model + ETL still consume `CATALOG_D1_SCHEMA`/`CUSTOMIZATION_D1_SCHEMA`
@@ -51,4 +56,5 @@ wrangler d1 migrations apply CATALOG_DB --env <env> [--remote|--local]
 ```
 
 > Catalog + customization tables share the **one** `CATALOG_DB` binding (one edge DB),
-> per `src/lib/customization/d1Store.ts`.
+> per `src/lib/customization/d1Store.ts`. The storefront-apps tables are a SEPARATE D1
+> (`STOREFRONT_APPS_DB`) applied the same way, from `../migrations-apps/`.

package/apps/storefront/migrations-apps/0000_fast_millenium_guard.sql

@@ -0,0 +1,129 @@
+CREATE TABLE `app_attributions` (
+	`install_id` text NOT NULL,
+	`attribution_id` text NOT NULL,
+	`tenant_id` text NOT NULL,
+	`order_id` text NOT NULL,
+	`campaign` text,
+	`referral_code` text,
+	`commission_amount` real,
+	`commission_currency` text,
+	`customer_hash` text,
+	`recorded_at` text NOT NULL,
+	PRIMARY KEY(`install_id`, `attribution_id`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_app_attributions_tenant_order` ON `app_attributions` (`tenant_id`,`order_id`);--> statement-breakpoint
+CREATE TABLE `app_audit_log` (
+	`id` text PRIMARY KEY NOT NULL,
+	`install_id` text NOT NULL,
+	`tenant_id` text NOT NULL,
+	`event` text NOT NULL,
+	`actor` text NOT NULL,
+	`trace_id` text,
+	`detail` text DEFAULT '{}' NOT NULL,
+	`at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx_app_audit_install` ON `app_audit_log` (`install_id`);--> statement-breakpoint
+CREATE TABLE `app_credentials` (
+	`install_id` text PRIMARY KEY NOT NULL,
+	`client_id` text NOT NULL,
+	`secret_hash` text NOT NULL,
+	`secret_created_at` text NOT NULL,
+	`rotated_at` text,
+	`jwks_kid` text NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `app_credentials_client_id_unique` ON `app_credentials` (`client_id`);--> statement-breakpoint
+CREATE TABLE `app_installs` (
+	`install_id` text PRIMARY KEY NOT NULL,
+	`app_id` text NOT NULL,
+	`app_version` text NOT NULL,
+	`tenant_id` text NOT NULL,
+	`env` text NOT NULL,
+	`status` text DEFAULT 'active' NOT NULL,
+	`scopes` text DEFAULT '[]' NOT NULL,
+	`manifest` text NOT NULL,
+	`webhook_endpoint` text,
+	`widget_placements` text DEFAULT '[]' NOT NULL,
+	`install_actor` text NOT NULL,
+	`created_at` text NOT NULL,
+	`updated_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `uq_app_installs_app_tenant_env` ON `app_installs` (`app_id`,`tenant_id`,`env`);--> statement-breakpoint
+CREATE INDEX `idx_app_installs_tenant` ON `app_installs` (`tenant_id`);--> statement-breakpoint
+CREATE TABLE `idempotency_keys` (
+	`install_id` text NOT NULL,
+	`idempotency_key` text NOT NULL,
+	`body_hash` text NOT NULL,
+	`response_body` text NOT NULL,
+	`created_at` text NOT NULL,
+	PRIMARY KEY(`install_id`, `idempotency_key`)
+);
+--> statement-breakpoint
+CREATE TABLE `orders` (
+	`tenant_id` text NOT NULL,
+	`external_order_id` text NOT NULL,
+	`env` text NOT NULL,
+	`status` text NOT NULL,
+	`currency` text NOT NULL,
+	`total` real DEFAULT 0 NOT NULL,
+	`subtotal` real,
+	`customer_hash` text,
+	`line_items` text DEFAULT '[]' NOT NULL,
+	`created_at` text NOT NULL,
+	`updated_at` text NOT NULL,
+	PRIMARY KEY(`tenant_id`, `external_order_id`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_orders_tenant` ON `orders` (`tenant_id`);--> statement-breakpoint
+CREATE TABLE `webhook_deliveries` (
+	`delivery_id` text PRIMARY KEY NOT NULL,
+	`event_id` text NOT NULL,
+	`install_id` text NOT NULL,
+	`tenant_id` text NOT NULL,
+	`topic` text NOT NULL,
+	`state` text DEFAULT 'pending' NOT NULL,
+	`attempts` integer DEFAULT 0 NOT NULL,
+	`last_status` integer,
+	`last_error_class` text,
+	`last_trace_id` text,
+	`next_attempt_at` text,
+	`created_at` text NOT NULL,
+	`updated_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx_webhook_deliveries_install` ON `webhook_deliveries` (`install_id`);--> statement-breakpoint
+CREATE INDEX `idx_webhook_deliveries_due` ON `webhook_deliveries` (`state`,`next_attempt_at`);--> statement-breakpoint
+CREATE TABLE `webhook_delivery_attempts` (
+	`id` text PRIMARY KEY NOT NULL,
+	`delivery_id` text NOT NULL,
+	`attempt_no` integer NOT NULL,
+	`started_at` text NOT NULL,
+	`duration_ms` integer,
+	`http_status` integer,
+	`error_class` text,
+	`trace_id` text
+);
+--> statement-breakpoint
+CREATE INDEX `idx_webhook_delivery_attempts_delivery` ON `webhook_delivery_attempts` (`delivery_id`);--> statement-breakpoint
+CREATE TABLE `webhook_events` (
+	`id` text PRIMARY KEY NOT NULL,
+	`tenant_id` text NOT NULL,
+	`topic` text NOT NULL,
+	`dataschema_version` text NOT NULL,
+	`payload` text NOT NULL,
+	`created_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `webhook_install_health` (
+	`install_id` text PRIMARY KEY NOT NULL,
+	`last_success_at` text,
+	`failure_streak` integer DEFAULT 0 NOT NULL,
+	`dlq_count` integer DEFAULT 0 NOT NULL,
+	`last_status` integer,
+	`last_error_class` text,
+	`recent_trace_ids` text DEFAULT '[]' NOT NULL,
+	`updated_at` text NOT NULL
+);