@tokenoftrust/cli 3.0.3 → 3.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "3.0.3",
+  "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/declared-config.d.mts

@@ -22,6 +22,9 @@ export const DEFAULT_CURRENCY: "USD";
 export const CURRENCY_CODES: readonly string[];
 export function resolveStoreCurrency(declared: unknown): string;
 export function currencyDeclarationProblems(currency: unknown): string[];
+export const SHIPPING_KEYS: readonly string[];
+export const MAX_SHIPPING_AMOUNT: number;
+export function shippingDeclarationProblems(shipping: unknown): string[];
 export const COMPLIANCE_NOTICES: Record<string, string>;
 export const MANDATED_NOTICE_KEYS: string[];
 export function nearestKey(key: string, known: readonly string[]): string | null;

package/src/declared-config.mjs

@@ -19,7 +19,7 @@
 
 export const TOT_CONFIG_KEYS = [
   "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "displayName", "siteType", "compliance", "capabilities", "features", "embeds", "seo", "currency",
+  "displayName", "siteType", "compliance", "capabilities", "features", "embeds", "seo", "currency", "shipping",
 ];
 // Keys other tooling has written that the platform does NOT read, with the key it does.
 const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
@@ -196,6 +196,46 @@ export function seoDeclarationProblems(seo) {
   return problems;
 }
 
+/** Every `shipping` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
+export const SHIPPING_KEYS = Object.freeze(["flatRate", "freeAtOrAbove"]);
+
+/** Largest shipping amount a declaration may state, in the cart's currency. */
+export const MAX_SHIPPING_AMOUNT = 100000;
+
+/** @param {unknown} value */
+const isShippingAmount = (value) =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= MAX_SHIPPING_AMOUNT
+  && Math.abs(value * 100 - Math.round(value * 100)) < 1e-6;
+
+/**
+ * What is wrong with a declared `shipping` value, one sentence per problem; `[]` when it is
+ * valid. A policy with any problem is refused whole, so checkout never charges half of one.
+ *
+ * @param {unknown} shipping
+ * @returns {string[]}
+ */
+export function shippingDeclarationProblems(shipping) {
+  if (!isPlainObject(shipping)) return ["`shipping` must be an object"];
+  const problems = [];
+  const source = /** @type {Record<string, unknown>} */ (shipping);
+  for (const key of Object.keys(source)) {
+    if (!SHIPPING_KEYS.includes(key)) problems.push(`\`shipping.${key}\` is not a shipping key (${SHIPPING_KEYS.join(", ")})`);
+  }
+  if (!isShippingAmount(source.flatRate)) {
+    problems.push(`\`shipping.flatRate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+  }
+  if (source.freeAtOrAbove !== undefined && !(isShippingAmount(source.freeAtOrAbove) && /** @type {number} */ (source.freeAtOrAbove) > 0)) {
+    problems.push(`\`shipping.freeAtOrAbove\` must be an amount above 0 and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+  }
+  return problems;
+}
+
+/** The owner-facing sentence for an invalid `shipping` declaration. */
+function shippingProblemMessage(problems) {
+  return `\`shipping\` is not a valid shipping policy (${problems.join("; ")}). ` +
+    "Checkout charges no shipping until it is fixed.";
+}
+
 
 /** What each compliance key puts on the page — the thing that is missing when it is. */
 export const COMPLIANCE_NOTICES = {
@@ -568,6 +608,8 @@ export function declarationFindings(current, previous) {
     if (warning.enabled && warning.problems.length > 0) {
       out.push(`CONFIG: ${nicotineWarningProblemMessage(warning.problems)}`);
     }
+    const shipping = current.shipping === undefined ? [] : shippingDeclarationProblems(current.shipping);
+    if (shipping.length > 0) out.push(`CONFIG: ${shippingProblemMessage(shipping)}`);
   }
   for (const { key, notice } of droppedMandatedNotices(previous, current)) {
     out.push(
@@ -656,6 +698,13 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
       out.push(mk(ERROR, "config-seo", `${file} seo`, `${problem} — the whole \`seo\` declaration is ignored until it is fixed`));
     }
   }
+  if (config.shipping !== undefined) {
+    const problems = shippingDeclarationProblems(config.shipping);
+    if (problems.length > 0) {
+      out.push(mk(ERROR, "config-shipping", `${file} shipping`, shippingProblemMessage(problems),
+        'declare e.g. `"shipping": { "flatRate": 5.99, "freeAtOrAbove": 100 }`, or remove `shipping` to charge none'));
+    }
+  }
   return out;
 }
 

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`));