@tokenoftrust/cli 4.5.0 → 4.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "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/sku.mjs

@@ -0,0 +1,146 @@
+/**
+ * The SKU contract: one rule for every reader and writer of a merchant's SKU.
+ *
+ * A SKU is merchant data, kept exactly as the merchant wrote it. The only rewrite is trimming
+ * leading and trailing whitespace on the way in. A SKU is refused only when it is empty, carries a
+ * control character, or is longer than {@link SKU_MAX_LENGTH} characters. Anything else, a space
+ * included, is a valid SKU; a space is a lint warning, never an error.
+ *
+ * Two SKUs are the same SKU when their {@link skuKey} is equal: trimmed, NBSP read as a space, and
+ * case-folded. The key is for comparison only and is never stored.
+ *
+ * A SKU is never used raw where a boundary needs a safe token (a path, a file name, a URL segment,
+ * a checkout product code). {@link skuToken} is the one encoding for those boundaries: reversible,
+ * injective, and the identity for a SKU of letters, digits, `.`, `_` and `-`.
+ *
+ * Pure: no filesystem, no network, no dependencies. `packages/cli/src/sku.mjs` is a byte-identical
+ * copy (the CLI installs without the kit), pinned by `packages/cli/test/sku-copy.test.mjs`.
+ */
+
+/** Longest SKU accepted, in characters (code points). */
+export const SKU_MAX_LENGTH = 250;
+/** The checkout provider's product-code limit; a longer {@link skuToken} is a lint warning. */
+export const CHECKOUT_CODE_MAX_LENGTH = 200;
+/** Longest {@link skuToken} any SKU can produce (four UTF-8 bytes, three characters each). */
+export const SKU_TOKEN_MAX_LENGTH = SKU_MAX_LENGTH * 12;
+
+const CONTROL = /\p{Cc}/u;
+const WHITESPACE = /\s/u;
+const TOKEN_SAFE = /^[A-Za-z0-9._-]$/;
+const TOKEN = /^(?:[A-Za-z0-9._-]|%[0-9A-F]{2})+$/;
+
+/**
+ * Read a SKU as it arrives from a merchant, a file or an import.
+ *
+ * @param {unknown} value
+ * @returns {{ ok: true, sku: string } | { ok: false, reason: "not-string" | "empty" | "control-character" | "too-long" }}
+ */
+export function parseSku(value) {
+  if (typeof value !== "string") return { ok: false, reason: "not-string" };
+  const sku = value.trim();
+  if (sku === "") return { ok: false, reason: "empty" };
+  if (CONTROL.test(sku)) return { ok: false, reason: "control-character" };
+  if ([...sku].length > SKU_MAX_LENGTH) return { ok: false, reason: "too-long" };
+  return { ok: true, sku };
+}
+
+/** True when `value` is a SKU in its stored form: valid and already trimmed. */
+export function isStoredSku(value) {
+  const parsed = parseSku(value);
+  return parsed.ok && parsed.sku === value;
+}
+
+/** The comparison key two SKUs share when they are the same SKU. Never stored. */
+export function skuKey(sku) {
+  return String(sku).replace(/ /g, " ").trim().toLowerCase();
+}
+
+/**
+ * The SKU as a token safe in a path, file name, URL segment or checkout product code. Letters,
+ * digits, `.`, `_` and `-` pass through; every other character is its UTF-8 bytes as `%XX`.
+ */
+export function skuToken(sku) {
+  let out = "";
+  for (const char of String(sku)) {
+    if (TOKEN_SAFE.test(char)) {
+      out += char;
+      continue;
+    }
+    for (const byte of new TextEncoder().encode(char)) out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+  }
+  return out;
+}
+
+/** The stored SKU a {@link skuToken} encodes, or null when `token` is not one. */
+export function skuFromToken(token) {
+  if (typeof token !== "string" || token.length > SKU_TOKEN_MAX_LENGTH || !TOKEN.test(token)) return null;
+  const bytes = [];
+  for (let i = 0; i < token.length; i += 1) {
+    if (token[i] === "%") {
+      bytes.push(Number.parseInt(token.slice(i + 1, i + 3), 16));
+      i += 2;
+    } else {
+      bytes.push(token.charCodeAt(i));
+    }
+  }
+  // Bytes that are not UTF-8 decode to U+FFFD, whose token differs, so the round trip refuses them.
+  const sku = new TextDecoder().decode(new Uint8Array(bytes));
+  return isStoredSku(sku) && skuToken(sku) === token ? sku : null;
+}
+
+const REASONS = {
+  "not-string": "a SKU must be text",
+  empty: "a SKU cannot be empty",
+  "control-character": "a SKU cannot contain a control character (tab, newline, ...)",
+  "too-long": `a SKU is at most ${SKU_MAX_LENGTH} characters`,
+};
+
+/**
+ * Lint findings for one SKU. `error` means the SKU is refused; `warning` means it works.
+ *
+ * @param {unknown} value
+ * @returns {Array<{ level: "error" | "warning", code: string, message: string }>}
+ */
+export function skuFindings(value) {
+  const parsed = parseSku(value);
+  if (!parsed.ok) return [{ level: "error", code: `sku-${parsed.reason}`, message: REASONS[parsed.reason] }];
+  /** @type {Array<{ level: "error" | "warning", code: string, message: string }>} */
+  const findings = [];
+  if (parsed.sku !== value) {
+    findings.push({ level: "warning", code: "sku-untrimmed", message: "leading or trailing whitespace is trimmed when the SKU is read" });
+  }
+  if (WHITESPACE.test(parsed.sku)) {
+    findings.push({
+      level: "warning",
+      code: "sku-whitespace",
+      message: "works, but we recommend against spaces in a SKU: spreadsheets, scanners and other systems often trim or split on them",
+    });
+  }
+  if (skuToken(parsed.sku).length > CHECKOUT_CODE_MAX_LENGTH) {
+    findings.push({
+      level: "warning",
+      code: "sku-checkout-code-long",
+      message: `its checkout product code is longer than ${CHECKOUT_CODE_MAX_LENGTH} characters, which the checkout provider may refuse`,
+    });
+  }
+  return findings;
+}
+
+/**
+ * SKUs that are the same SKU under {@link skuKey}. Each group lists every entry that shares a key.
+ *
+ * @template {{ sku: string }} T
+ * @param {Iterable<T>} entries
+ * @returns {Array<{ key: string, entries: T[] }>}
+ */
+export function skuCollisions(entries) {
+  /** @type {Map<string, T[]>} */
+  const groups = new Map();
+  for (const entry of entries) {
+    const key = skuKey(entry.sku);
+    const group = groups.get(key);
+    if (group) group.push(entry);
+    else groups.set(key, [entry]);
+  }
+  return [...groups].filter(([, group]) => group.length > 1).map(([key, group]) => ({ key, entries: group }));
+}

package/src/validate.mjs

@@ -24,6 +24,7 @@ import {
   workspacePathForTenantRelative,
 } from "./tot-repo-mappings.mjs";
 import { isForbiddenPublicPath, publicBinaryFindings } from "./public-binaries.mjs";
+import { parseSku, skuCollisions, skuFindings } from "./sku.mjs";
 
 export {
   TOT_CONFIG_KEYS,
@@ -74,6 +75,57 @@ export function detectConflictMarkers(content) {
 const CONFLICT_SCAN_EXT = new Set([".html", ".htm", ".json", ".md", ".txt", ".css", ".js", ".mjs", ".svg", ".xml"]);
 const hasScanExt = (p) => CONFLICT_SCAN_EXT.has((p.match(/\.[^./\\]+$/) || [""])[0].toLowerCase());
 
+// --- catalog SKUs ---------------------------------------------------------------
+// The SKU contract (sku.mjs, a copy of the kit's catalog-model/sku.mjs). A refused SKU is an
+// error (the catalog reader refuses its file); a space is a warning ("works, but recommend
+// against"); two SKUs that are the same SKU ignoring case and edge whitespace are an error.
+
+/**
+ * SKU findings for a store's product records. Pure — exported for focused testing.
+ * @param {Array<{ file: string, record: unknown }>} products
+ * @returns {Finding[]}
+ */
+export function catalogSkuFindings(products) {
+  /** @type {Finding[]} */
+  const out = [];
+  /** @type {Array<{ sku: string, file: string }>} */
+  const skued = [];
+  for (const { file, record } of products) {
+    const doc = /** @type {any} */ (record);
+    const variants = doc && typeof doc === "object" && Array.isArray(doc.variants) ? doc.variants : [];
+    variants.forEach((variant, index) => {
+      if (!variant || typeof variant !== "object" || variant.sku === undefined) return;
+      for (const f of skuFindings(variant.sku)) {
+        if (f.code === "sku-empty") continue; // a blank SKU is no SKU
+        out.push(mk(f.level === "error" ? ERROR : WARN, f.code, file, `variants[${index}].sku ${JSON.stringify(variant.sku)}: ${f.message}`));
+      }
+      const parsed = parseSku(variant.sku);
+      if (parsed.ok) skued.push({ sku: parsed.sku, file });
+    });
+  }
+  for (const collision of skuCollisions(skued)) {
+    const names = collision.entries.map((e) => `${JSON.stringify(e.sku)} (${e.file})`).join(", ");
+    out.push(mk(ERROR, "sku-duplicate", collision.entries[0].file, `the same SKU, ignoring case and edge whitespace, is used ${collision.entries.length} times: ${names}`,
+      "give each variant its own SKU"));
+  }
+  return out;
+}
+
+function validateCatalogSkus(contentDir, rel) {
+  const dir = join(contentDir, "catalog", "products");
+  if (!existsSync(dir)) return [];
+  /** @type {Finding[]} */
+  const parseErrors = [];
+  const products = [];
+  for (const name of readdirSync(dir).filter((n) => n.endsWith(".json")).sort()) {
+    const path = join(dir, name);
+    const { value, error } = readJsonSafe(path);
+    if (error) parseErrors.push(mk(ERROR, "catalog-parse", rel(path), `invalid JSON: ${error}`));
+    else products.push({ file: rel(path), record: value });
+  }
+  return [...parseErrors, ...catalogSkuFindings(products)];
+}
+
 // --- canonical `.tot/config.json` shape (the #24/#25 regression guard) --------
 const KNOWN_KINDS = new Set(["file", "tree"]);
 const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
@@ -1247,6 +1299,8 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  findings.push(...validateCatalogSkus(contentDir, rel));
+
   const capabilitiesPath = located("capabilities.json");
   if (existsSync(capabilitiesPath)) {
     const { value, error } = readJsonSafe(capabilitiesPath);