@tokenoftrust/cli 3.0.4 → 3.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/public-binaries.mjs

@@ -0,0 +1,95 @@
+/**
+ * Tenant binaries never live in the tenant repo. The platform's content-addressed `/_a/<sha256>`
+ * pool owns them and the store's repo holds references only. Platform capture of catalog images
+ * is pending: until it owns them, an image stays at its source URL, go-live requires 0 uncaptured
+ * catalog images, and the source store is never shut down before that check passes. This decides,
+ * from a listing of the store's `public/` tree, whether the repo is carrying binaries it must not.
+ *
+ * Three findings, each naming its remedy:
+ *
+ *   - `catalog-images-in-repo` — any file under `public/catalog-images/`, the directory a catalog
+ *     image download writes. Decided from paths alone, so a caller without sizes still refuses it.
+ *   - `public-binary-oversized` — one raster or media file over {@link PUBLIC_BINARY_LIMITS}
+ *     `maxFileBytes`.
+ *   - `public-tree-over-budget` — the whole `public/` tree over `maxTotalBytes`.
+ *
+ * The size findings need `bytes`; an entry without it is judged by path only.
+ *
+ * Budget basis (measured 2026-10-20 on three live store repos' `preview` branches): public/ held
+ * 17.2 MB (384 files, largest 0.9 MB), 16.5 MB (largest 0.4 MB) and 0.2 MB outside
+ * catalog-images/. No legitimate file exceeded 1 MB.
+ *
+ * Pure: no filesystem, no network, no imports, so it runs in Node and in the Worker.
+ */
+
+/** @type {{ maxFileBytes: number, maxTotalBytes: number }} */
+export const PUBLIC_BINARY_LIMITS = Object.freeze({
+  maxFileBytes: 1024 * 1024,
+  maxTotalBytes: 32 * 1024 * 1024,
+});
+
+/** The directory under `public/` a catalog image download writes. */
+export const CATALOG_IMAGES_DIR = "catalog-images/";
+
+/** The finding code for files under {@link CATALOG_IMAGES_DIR}. */
+export const CATALOG_IMAGES_FINDING_CODE = "catalog-images-in-repo";
+
+/** The kit command that moves rehosted catalog image references 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;
+
+const mb = (bytes) => `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+
+/**
+ * @param {ReadonlyArray<{ rel: string, bytes?: number }>} entries  files under `public/`, `rel`
+ *   relative to it (`catalog-images/ab.jpg`)
+ * @param {{ maxFileBytes?: number, maxTotalBytes?: number }} [limits]
+ * @returns {Array<{ code: string, path: string, message: string, remedy: string }>}
+ */
+export function publicBinaryFindings(entries, limits = {}) {
+  const maxFileBytes = limits.maxFileBytes ?? PUBLIC_BINARY_LIMITS.maxFileBytes;
+  const maxTotalBytes = limits.maxTotalBytes ?? PUBLIC_BINARY_LIMITS.maxTotalBytes;
+  const findings = [];
+  const catalogImages = entries.filter((e) => e.rel.startsWith(CATALOG_IMAGES_DIR));
+  if (catalogImages.length > 0) {
+    const bytes = catalogImages.reduce((n, e) => n + (e.bytes ?? 0), 0);
+    findings.push({
+      code: CATALOG_IMAGES_FINDING_CODE,
+      path: `public/${CATALOG_IMAGES_DIR}`,
+      message: `${catalogImages.length} catalog image 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,
+    });
+  }
+  for (const e of entries) {
+    if (e.rel.startsWith(CATALOG_IMAGES_DIR) || e.bytes === undefined) continue;
+    if (e.bytes > maxFileBytes && RASTER_OR_MEDIA.test(e.rel)) {
+      findings.push({
+        code: "public-binary-oversized",
+        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",
+      });
+    }
+  }
+  if (entries.every((e) => e.bytes !== undefined)) {
+    const total = entries.reduce((n, e) => n + /** @type {number} */ (e.bytes), 0);
+    if (total > maxTotalBytes) {
+      findings.push({
+        code: "public-tree-over-budget",
+        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",
+      });
+    }
+  }
+  return findings;
+}
+
+/** One line per finding, remedy included: `<path>: [<code>] <message> — fix: <remedy>`. */
+export function describePublicBinaryFindings(findings) {
+  return findings.map((f) => `${f.path}: [${f.code}] ${f.message} — fix: ${f.remedy}`);
+}

package/src/validate.mjs

@@ -23,6 +23,7 @@ import {
   parseMappingTarget,
   workspacePathForTenantRelative,
 } from "./tot-repo-mappings.mjs";
+import { CATALOG_IMAGES_DIR, publicBinaryFindings } from "./public-binaries.mjs";
 
 export {
   TOT_CONFIG_KEYS,
@@ -1350,6 +1351,13 @@ export function validateTenant(tenantDir, opts = {}) {
   // large public assets — advisory (never blocks); see LARGE_PUBLIC_ASSET_FIX.
   findings.push(...findLargePublicAssets(publicDir, rel));
 
+  // Tenant binaries never live in the tenant repo — the same rule the hosted reconcile refuses.
+  const publicEntries = walk(publicDir, () => true)
+    .map((p) => ({ rel: relative(publicDir, p).split("\\").join("/"), bytes: statSync(p).size }));
+  for (const f of publicBinaryFindings(publicEntries)) {
+    findings.push(mk(ERROR, f.code, `${rel(publicDir)}/${f.path.slice("public/".length)}`, f.message, f.remedy));
+  }
+
   const ok = !findings.some((f) => f.level === ERROR);
   return { ok, findings };
 }
@@ -1426,6 +1434,8 @@ function checkAsset(src, file, publicDir, tenantId) {
 function findLargePublicAssets(publicDir, rel) {
   const out = [];
   for (const p of walk(publicDir, () => true)) {
+    // public/catalog-images/ is already an error (catalog-images-in-repo); one line, not thousands.
+    if (relative(publicDir, p).split("\\").join("/").startsWith(CATALOG_IMAGES_DIR)) continue;
     const size = statSync(p).size;
     if (size >= LARGE_PUBLIC_ASSET_BYTES) {
       out.push(mk(WARN, "large-public-asset", rel(p), `${(size / 1024).toFixed(0)}KB`));