@tokenoftrust/storefront-runner 3.1.2 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.1.2",
+  "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;