@tokenoftrust/storefront-runner 3.1.1 → 3.2.0

package/agency-kit/tools/lib/public-binaries.mjs

@@ -9,11 +9,11 @@
  *
  *   - one per entry of {@link FORBIDDEN_PUBLIC_DIRS}: any file under a directory a media download
  *     writes (`public/catalog-images/` is `catalog-images-in-repo`, `public/blog/wp-content/uploads/`
- *     is `blog-media-in-repo`). Decided from paths alone, so a caller without sizes still refuses
- *     it. This list is the one source the validators and the reconcile read; the Gitea
- *     pre-receive size guard names the same directories.
+ *     is `blog-media-in-repo`), each with its own remedy. Decided from paths alone, so a caller
+ *     without sizes still refuses it. This list is the one source the validators and the reconcile
+ *     read; the Gitea pre-receive size guard names the same directories.
  *   - `public-binary-oversized` — one raster or media file over {@link PUBLIC_BINARY_LIMITS}
- *     `maxFileBytes`.
+ *     `maxFileBytes`. An image's remedy is {@link IMAGE_ADD_COMMAND}.
  *   - `public-tree-over-budget` — the whole `public/` tree over `maxTotalBytes`.
  *
  * The size findings need `bytes`; an entry without it is judged by path only.
@@ -31,14 +31,24 @@ export const PUBLIC_BINARY_LIMITS = Object.freeze({
   maxTotalBytes: 32 * 1024 * 1024,
 });
 
+/** The kit command that moves downloaded catalog images and blog media back to their source URLs. */
+export const UNHOST_IMAGES_COMMAND = "node agency-kit/tools/import-catalog.mjs --store <checkout> --unhost-images --write";
+
+/** The command that puts an image the author holds into the platform pool and prints its `/_a/` URL. */
+export const IMAGE_ADD_COMMAND = "tot image add <file>";
+
 /**
  * The directories under `public/` a media download writes. No file under one may be committed.
+ * `remedy` is the fix for files of that kind.
  *
- * @type {ReadonlyArray<Readonly<{ dir: string, code: string, noun: string }>>}
+ * @type {ReadonlyArray<Readonly<{ dir: string, code: string, noun: string, remedy: string }>>}
  */
 export const FORBIDDEN_PUBLIC_DIRS = Object.freeze([
-  Object.freeze({ dir: "catalog-images/", code: "catalog-images-in-repo", noun: "catalog image" }),
-  Object.freeze({ dir: "blog/wp-content/uploads/", code: "blog-media-in-repo", noun: "blog media" }),
+  Object.freeze({ dir: "catalog-images/", code: "catalog-images-in-repo", noun: "catalog image", remedy: UNHOST_IMAGES_COMMAND }),
+  Object.freeze({
+    dir: "blog/wp-content/uploads/", code: "blog-media-in-repo", noun: "blog media",
+    remedy: `a new post image: ${IMAGE_ADD_COMMAND}, then reference the /_a/ URL it prints; media a migration downloaded: ${UNHOST_IMAGES_COMMAND}`,
+  }),
 ]);
 
 /** The finding codes decided from paths alone. */
@@ -49,11 +59,11 @@ export function isForbiddenPublicPath(rel) {
   return FORBIDDEN_PUBLIC_DIRS.some((d) => rel.startsWith(d.dir));
 }
 
-/** The kit command that moves downloaded catalog images and blog media back to their source URLs. */
-export const UNHOST_IMAGES_COMMAND = "node agency-kit/tools/import-catalog.mjs --store <checkout> --unhost-images --write";
-
 const RASTER_OR_MEDIA = /\.(?:jpe?g|png|gif|webp|avif|bmp|tiff?|heic|heif|ico|jxl|mp4|m4v|mov|webm|mkv|avi|mpe?g|mp3|wav|ogg|oga|m4a|aac|flac|opus)$/i;
 
+/** The formats {@link IMAGE_ADD_COMMAND} accepts. */
+const UPLOADABLE_IMAGE = /\.(?:jpe?g|png|gif|webp|avif)$/i;
+
 const mb = (bytes) => `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 
 /**
@@ -66,7 +76,7 @@ export function publicBinaryFindings(entries, limits = {}) {
   const maxFileBytes = limits.maxFileBytes ?? PUBLIC_BINARY_LIMITS.maxFileBytes;
   const maxTotalBytes = limits.maxTotalBytes ?? PUBLIC_BINARY_LIMITS.maxTotalBytes;
   const findings = [];
-  for (const { dir, code, noun } of FORBIDDEN_PUBLIC_DIRS) {
+  for (const { dir, code, noun, remedy } of FORBIDDEN_PUBLIC_DIRS) {
     const files = entries.filter((e) => e.rel.startsWith(dir));
     if (files.length === 0) continue;
     const bytes = files.reduce((n, e) => n + (e.bytes ?? 0), 0);
@@ -74,8 +84,8 @@ export function publicBinaryFindings(entries, limits = {}) {
       code,
       path: `public/${dir}`,
       message: `${files.length} ${noun} file(s)${bytes ? ` (${mb(bytes)})` : ""} are committed to the store repo; ` +
-        "images belong in the platform pool, not the repo; until platform capture owns them, keep each image at its source URL",
-      remedy: UNHOST_IMAGES_COMMAND,
+        "images belong in the platform pool, not the repo",
+      remedy,
     });
   }
   for (const e of entries) {
@@ -86,7 +96,9 @@ export function publicBinaryFindings(entries, limits = {}) {
         path: `public/${e.rel}`,
         message: `${mb(e.bytes)} raster/media file exceeds the ${mb(maxFileBytes)} per-file limit for the store repo; ` +
           "images and media belong in the platform pool",
-        remedy: "reference the file by its source URL, or compress it under the limit",
+        remedy: UPLOADABLE_IMAGE.test(e.rel)
+          ? `${IMAGE_ADD_COMMAND}, then reference the /_a/ URL it prints instead of the file`
+          : "reference the file by its source URL, or compress it under the limit",
       });
     }
   }
@@ -98,7 +110,8 @@ export function publicBinaryFindings(entries, limits = {}) {
         path: "public/",
         message: `public/ holds ${mb(total)} across ${entries.length} file(s), over the ${mb(maxTotalBytes)} store-repo budget; ` +
           "images and media belong in the platform pool",
-        remedy: "reference large or bulk assets by their source URL instead of committing them",
+        remedy: `upload images with ${IMAGE_ADD_COMMAND} and reference the /_a/ URLs it prints; ` +
+          "reference other large assets by their source URL",
       });
     }
   }

package/apps/storefront/src/lib/assets/captured-original-serve.ts

@@ -44,7 +44,7 @@ export type ManifestEntry = {
   address: string;
   byteLength: number;
   mediaType: string;
-  provenance?: { kind: "local" | "remote"; locator: string };
+  provenance?: { kind: "local" | "remote" | "upload"; locator: string };
 };
 
 function objectKey(tenantId: string, address: string): string {

package/apps/storefront/test/pipeline/pool-config.cjs

@@ -11,6 +11,10 @@
 const { defineWorkersConfig } = require("@cloudflare/vitest-pool-workers/config");
 const esbuild = require("esbuild");
 const path = require("node:path");
+// The check step's CPU budget sizes the worker pool (scripts/lib/step-cpus.cjs). Concurrent cells
+// are not held to it: they interleave on the one workerd isolate thread and wait on alarms, so 24
+// at once keep under one CPU busy (measured 2026-10-22: 11.5 CPU-s over 16.8s at 24; 87s at 3).
+const { stepWorkers } = require("../../../../scripts/lib/step-cpus.cjs");
 
 const compatibilityDate = "2024-11-01";
 const compatibilityFlags = ["nodejs_compat"];
@@ -20,6 +24,7 @@ const HOST = "pipeline-host";
  * @param {{ root: string; name: string; include: string[]; maxConcurrency?: number; testTimeout?: number }} options
  */
 function pipelinePoolConfig({ root, name, include, maxConcurrency, testTimeout = 60_000 }) {
+  const workers = stepWorkers();
   const hostModule = esbuild.buildSync({
     entryPoints: [path.join(root, "test/pipeline/pipeline-host.ts")],
     bundle: true,
@@ -42,6 +47,8 @@ function pipelinePoolConfig({ root, name, include, maxConcurrency, testTimeout =
       testTimeout,
       hookTimeout: 60_000,
       ...(maxConcurrency ? { maxConcurrency } : {}),
+      maxWorkers: workers.maxWorkers,
+      minWorkers: workers.minWorkers,
       poolOptions: {
         workers: {
           isolatedStorage: false,

package/apps/storefront/vitest.config.cts

@@ -3,8 +3,12 @@
 // node_modules/.vite/vitest.
 process.env.VITE_CJS_IGNORE_WARNING = "1";
 const { defineConfig } = require("vitest/config");
+// The check step's CPU budget sizes the worker pool (scripts/lib/step-cpus.cjs).
+const { stepWorkers } = require("../../scripts/lib/step-cpus.cjs");
 const path = require("node:path");
 
+const workers = stepWorkers();
+
 // Storefront unit tests — pure TS logic (tenant routing, search, query engine,
 // image-attr resolution, edge cache, etc.). We deliberately do NOT render .astro
 // components here: the Astro Container API needs Astro's Vite pipeline, whose
@@ -34,5 +38,7 @@ module.exports = defineConfig({
     // Folds and CI run many suites at once; a fixture-heavy test that takes 2s alone can pass 5s
     // under that load. A genuinely hung test still fails, only later.
     testTimeout: 30_000,
+    maxWorkers: workers.maxWorkers,
+    minWorkers: workers.minWorkers,
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/capture-rewrites.ts

@@ -28,7 +28,7 @@ export type CaptureRewrite = {
 /** A sealed capture-manifest entry, as `original-image-capture.ts` writes it. */
 export interface CapturedManifestEntry {
   /** Remote `locator` is query-stripped for display; remote entries are matched by `locatorDigest`. */
-  provenance: { kind: "local" | "remote"; locator: string };
+  provenance: { kind: "local" | "remote" | "upload"; locator: string };
   address: string;
   mediaType: string;
   /** Remote entries: digest of the exact fetched locator, query included (`captureLocatorDigest`). */

package/packages/public-runtime/src/image-finding-acceptance.ts

@@ -141,7 +141,7 @@ export async function digestCaptureManifest(manifest: {
   version: 1;
   revisionId: string;
   entries: ReadonlyArray<{
-    provenance: { kind: "local" | "remote"; locator: string };
+    provenance: { kind: "local" | "remote" | "upload"; locator: string };
     address: string;
     byteLength: number;
     mediaType: string;

package/packages/public-runtime/vitest.config.cts

@@ -3,6 +3,10 @@
 // node_modules/.vite/vitest.
 process.env.VITE_CJS_IGNORE_WARNING = "1";
 const { defineConfig } = require("vitest/config");
+// The check step's CPU budget sizes the worker pool (scripts/lib/step-cpus.cjs).
+const { stepWorkers } = require("../../scripts/lib/step-cpus.cjs");
+
+const workers = stepWorkers();
 
 module.exports = defineConfig({
   test: {
@@ -12,5 +16,7 @@ module.exports = defineConfig({
     // Folds and CI run many suites at once; a fixture-heavy test that takes 0.5s alone can pass 5s
     // under that load. A genuinely hung test still fails, only later.
     testTimeout: 30_000,
+    maxWorkers: workers.maxWorkers,
+    minWorkers: workers.minWorkers,
   },
 });

package/scripts/lib/step-cpus.cjs

@@ -0,0 +1,48 @@
+// The CPU budget of the check step this process runs in. The check runner
+// (scripts/lib/check-runner.mjs) reserves slots for each step and exports the count as
+// TOT_STEP_CPUS; every pool a step starts (vitest workers, `node --test`
+// files, `pnpm -r` packages) sizes itself from it, so a step never uses more CPUs than it reserved.
+// With TOT_STEP_CPUS unset (a suite run by hand) every pool keeps its own default.
+//
+// CommonJS so the in-memory `.cts` vitest configs can require it as well as ESM can import it.
+"use strict";
+
+const STEP_CPUS_ENV = "TOT_STEP_CPUS";
+
+/**
+ * The step's CPU budget, or null outside a budgeted step.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number | null}
+ */
+function stepCpus(env = process.env) {
+  const raw = env[STEP_CPUS_ENV];
+  if (raw === undefined || raw === "") return null;
+  const cpus = Number(raw);
+  if (!Number.isInteger(cpus) || cpus < 1) throw new Error(`${STEP_CPUS_ENV} must be a positive integer, got "${raw}"`);
+  return cpus;
+}
+
+/**
+ * vitest's worker pool for this step: at most the budget. Both are undefined outside a budgeted
+ * step, which leaves vitest's defaults.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ maxWorkers: number | undefined, minWorkers: number | undefined }}
+ */
+function stepWorkers(env = process.env) {
+  const cpus = stepCpus(env);
+  return { maxWorkers: cpus ?? undefined, minWorkers: cpus === null ? undefined : 1 };
+}
+
+/**
+ * `node --test` flags with the run's file concurrency held to the budget. A flag list that already
+ * sets --test-concurrency keeps it.
+ * @param {string[]} flags
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+function nodeTestFlags(flags, env = process.env) {
+  const cpus = stepCpus(env);
+  if (cpus === null || flags.some((flag) => flag.startsWith("--test-concurrency"))) return flags;
+  return [...flags, `--test-concurrency=${cpus}`];
+}
+
+module.exports = { STEP_CPUS_ENV, stepCpus, stepWorkers, nodeTestFlags };