@tokenoftrust/cli 2.2.16 → 2.2.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.2.16",
+  "version": "2.2.18",
   "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/commands/dev.mjs

@@ -286,9 +286,12 @@ function runMonorepo(ctx, argv) {
  */
 export class NativeArtifactUnavailableError extends Error {}
 
-/** Same URL shape buildContainerPlan uses — factored out so native + Docker agree. */
+/**
+ * The local landing URL, shared by the native and Docker paths. The store's path is its canonical
+ * id, the config's `tenant` — the same id `tot dev` grafts the checkout under.
+ */
 export function deriveUrl(cfg, port) {
-  const domain = typeof cfg.scope === "string" && cfg.scope.includes(".") ? cfg.scope : null;
+  const domain = typeof cfg.tenant === "string" && cfg.tenant.includes(".") ? cfg.tenant : null;
   return { domain, url: `http://localhost:${port}/${domain ? `${domain}/` : ""}` };
 }
 
@@ -1835,8 +1838,7 @@ export function buildContainerPlan(workspace, args, _ctx) {
 
   const image = resolveDevImage(args);
   const port = String(args.port || "4321");
-  const domain = typeof cfg.scope === "string" && cfg.scope.includes(".") ? cfg.scope : null;
-  const url = `http://localhost:${port}/${domain ? `${domain}/` : ""}`;
+  const { domain, url } = deriveUrl(cfg, port);
 
   // docker run equivalent of scripts/dev/docker-compose.pull.yml: bind-mount the
   // checkout, map the port, force polling (reliable HMR across the mount), pull

package/src/commands/report.mjs

@@ -233,10 +233,14 @@ function resolveStore(args, ctx) {
   return null;
 }
 
-/** @param {string} dir */
+/**
+ * The store's id from its `.tot/config.json` — the id its `/tenants/<id>/` assets bind to. Never the
+ * directory's name.
+ * @param {string} dir
+ */
 function storeTenant(dir) {
   const config = readJson(join(dir, ".tot", "config.json"));
-  return typeof config?.tenant === "string" && config.tenant ? config.tenant : basename(dir);
+  return typeof config?.tenant === "string" && config.tenant ? config.tenant : null;
 }
 
 /**
@@ -272,7 +276,14 @@ export function run(argv, ctx, io = {}) {
     return 2;
   }
   const storeExists = existsSync(store);
-  const tenant = args.tenant ?? (storeExists ? storeTenant(store) : basename(store));
+  const tenant = args.tenant ?? (storeExists ? storeTenant(store) : null);
+  if (!tenant) {
+    err(`${fail(
+      `${store} names no store id`,
+      "set \"tenant\" in .tot/config.json to your store's id (the one `tot whoami` lists), or pass --tenant <id>",
+    )}\n`);
+    return 2;
+  }
   const lint = storeExists ? validateTenant(store, { tenantId: tenant, mode: args.workspace ? "workspace" : "monorepo" }) : null;
   const evidence = evidenceFromDir({ pagesDir, stylePath: args.style ? resolve(args.style) : null, lint });
   if (!evidence.measured) {

package/src/declared-config.d.mts

@@ -0,0 +1,28 @@
+/** Types for the dependency-free declared-config module (declared-config.mjs). */
+export interface DeclaredConfigFinding {
+  level: string;
+  rule: string;
+  file: string;
+  message: string;
+  fix?: string;
+}
+
+export const TOT_CONFIG_KEYS: string[];
+export const COMPLIANCE_KEYS: string[];
+export const FEATURE_KEYS: string[];
+export const SITE_TYPES: string[];
+export const COMPLIANCE_NOTICES: Record<string, string>;
+export const MANDATED_NOTICE_KEYS: string[];
+export function nearestKey(key: string, known: readonly string[]): string | null;
+export function unknownConfigKeys(
+  config: Record<string, unknown>,
+): { path: string; suggestion: string | null; consequence: string }[];
+export function droppedMandatedNotices(
+  previous: Record<string, unknown> | null | undefined,
+  current: Record<string, unknown> | null | undefined,
+): { key: string; notice: string }[];
+export function declarationFindings(
+  current: Record<string, unknown> | null | undefined,
+  previous: Record<string, unknown> | null | undefined,
+): string[];
+export function validateDeclaredConfig(config: Record<string, unknown>, file?: string): DeclaredConfigFinding[];

package/src/declared-config.mjs

@@ -1,12 +1,18 @@
 /**
- * The `.tot/config.json` keys the platform reads, and the refusal of everything
- * else. Shared by `tot validate` (src/validate.mjs) and the monorepo/dev-loop
- * validator (scripts/tenant/validate.mjs), so both refuse the same keys.
+ * The `.tot/config.json` keys the platform reads, and what happens to everything else.
+ * Shared by `tot validate` (src/validate.mjs), the monorepo/dev-loop validator
+ * (scripts/tenant/validate.mjs), the hosted reconcile, and the publication validator
+ * (scripts/publish/validate-bundle.mjs), so every surface says the same thing.
+ *
+ * An unknown key is the store owner's to decide about: it is reported as a WARNING the
+ * owner must approve before publication, naming the nearest key the platform does read
+ * and what will not render because of it. A wrong-shaped value of a known key (a
+ * `siteType` that is not a site type, a `compliance` that is not an object) stays an
+ * error: there is no reading of it the platform could act on.
  *
  * Mirrors packages/public-runtime/src/declared-tenant-config.mjs (this package ships
- * to npm on its own); test/declared-config-parity.test.mjs pins the two together, so
- * a field the platform honors can never be refused here, and a key no surface reads
- * can never pass. Dependency-free: the storefront runner copies this file as-is.
+ * to npm on its own); test/declared-config-parity.test.mjs pins the two together.
+ * Dependency-free: the storefront runner copies this file as-is.
  */
 
 export const TOT_CONFIG_KEYS = [
@@ -24,7 +30,33 @@ export const FEATURE_KEYS = [
 ];
 export const SITE_TYPES = ["commerce", "marketing"];
 
+/** What each compliance key puts on the page — the thing that is missing when it is. */
+export const COMPLIANCE_NOTICES = {
+  ruleProfile: "checkout compliance rules",
+  minAge: "age gate",
+  nicotineWarning: "FDA nicotine warning",
+  shippingRestriction: "shipping-restriction notice",
+  pactAct: "PACT Act notice",
+  adultSignature: "adult-signature notice",
+  prop65: "California Prop 65 warning",
+  purchaseLimit: "purchase-limit notice",
+  stateEligibility: "state-eligibility notice",
+  exciseTax: "excise-tax notice",
+};
+
+/**
+ * The compliance keys that each turn on a mandated duty in the platform's obligation
+ * model (packages/public-runtime/src/compliance-obligations.ts). Dropping one between
+ * the live revision and the one being published removes a mandated notice from the
+ * site — a decision the owner must make explicitly.
+ */
+export const MANDATED_NOTICE_KEYS = [
+  "minAge", "nicotineWarning", "pactAct", "adultSignature", "prop65",
+  "stateEligibility", "shippingRestriction", "exciseTax",
+];
+
 const ERROR = "error";
+const WARN = "warn";
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
 /** @typedef {{level:string, rule:string, file:string, message:string, fix?:string}} Finding */
@@ -32,43 +64,150 @@ function mk(level, rule, file, message, fix) {
   return { level, rule, file, message, fix };
 }
 
+/** Case-insensitive edit distance. */
+function distance(a, b) {
+  const s = a.toLowerCase();
+  const t = b.toLowerCase();
+  const row = Array.from({ length: t.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= s.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= t.length; j++) {
+      const cur = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (s[i - 1] === t[j - 1] ? 0 : 1));
+      prev = cur;
+    }
+  }
+  return row[t.length];
+}
+
 /**
- * Refuse what the platform would silently ignore: an unknown top-level key, an
- * unknown `compliance`/`features` key, or a declared field of the wrong shape. Each
- * one passes JSON parsing and renders nothing — on a regulated store that is a
- * mandated notice that never appears.
+ * The known key an unknown one most plausibly meant, or null when none is close.
+ * @param {string} key
+ * @param {readonly string[]} known
+ * @returns {string | null}
+ */
+export function nearestKey(key, known) {
+  let best = null;
+  let bestDistance = Infinity;
+  for (const candidate of known) {
+    const d = distance(key, candidate);
+    if (d < bestDistance) {
+      best = candidate;
+      bestDistance = d;
+    }
+  }
+  const lower = key.toLowerCase();
+  const near = best !== null && (bestDistance <= Math.max(2, Math.floor(best.length / 3)) ||
+    best.toLowerCase().startsWith(lower) || lower.startsWith(best.toLowerCase()));
+  return near ? best : null;
+}
+
+/**
+ * Every key in a `.tot/config.json` the platform does not read, with the key it most
+ * plausibly meant and the consequence. `path` is dotted (`compliance.nicotineWarnings`).
+ * @param {Record<string, any>} config
+ * @returns {{ path: string, suggestion: string | null, consequence: string }[]}
+ */
+export function unknownConfigKeys(config) {
+  const out = [];
+  for (const key of Object.keys(config)) {
+    if (TOT_CONFIG_KEYS.includes(key)) continue;
+    const suggestion = RENAMED_CONFIG_KEYS[/** @type {keyof typeof RENAMED_CONFIG_KEYS} */ (key)] ??
+      nearestKey(key, TOT_CONFIG_KEYS);
+    out.push({ path: key, suggestion, consequence: "the platform never reads it" });
+  }
+  /** @type {Array<[string, string[]]>} */
+  const objectFields = [["compliance", COMPLIANCE_KEYS], ["features", FEATURE_KEYS]];
+  for (const [field, known] of objectFields) {
+    const value = config[field];
+    if (!isObject(value)) continue;
+    for (const key of Object.keys(value)) {
+      if (known.includes(key)) continue;
+      const suggestion = nearestKey(key, known);
+      const notice = field === "compliance" && suggestion && !(suggestion in value)
+        ? COMPLIANCE_NOTICES[/** @type {keyof typeof COMPLIANCE_NOTICES} */ (suggestion)]
+        : null;
+      out.push({
+        path: `${field}.${key}`,
+        suggestion: suggestion ? `${field}.${suggestion}` : null,
+        consequence: notice
+          ? `this setting does nothing — your ${notice} will NOT render`
+          : "this setting does nothing",
+      });
+    }
+  }
+  return out;
+}
+
+/** The one-line, owner-facing sentence for an unknown key. */
+function unknownKeyMessage({ path, suggestion, consequence }) {
+  return `\`${path}\` is not a .tot/config.json key${suggestion ? ` — did you mean \`${suggestion}\`?` : ""} ` +
+    `${consequence.charAt(0).toUpperCase()}${consequence.slice(1)}.`;
+}
+
+/**
+ * The mandated notices the live revision declared that this one no longer does.
+ * @param {Record<string, any> | null | undefined} previous the live revision's `.tot/config.json`
+ * @param {Record<string, any> | null | undefined} current this revision's `.tot/config.json`
+ * @returns {{ key: string, notice: string }[]}
+ */
+export function droppedMandatedNotices(previous, current) {
+  const before = isObject(previous?.compliance) ? previous.compliance : {};
+  const now = isObject(current?.compliance) ? current.compliance : {};
+  return MANDATED_NOTICE_KEYS
+    .filter((key) => Boolean(before[key]) && !now[key])
+    .map((key) => ({ key, notice: COMPLIANCE_NOTICES[/** @type {keyof typeof COMPLIANCE_NOTICES} */ (key)] }));
+}
+
+/**
+ * The publication validator's findings for a revision's declaration: an owner-approvable
+ * `CONFIG:` finding per unknown key and a `COMPLIANCE:` finding per mandated notice the
+ * live site shows and this revision drops. Both are QUALITY findings
+ * (scripts/publish/lib/finding-severity.mjs): publication halts until the owner accepts
+ * them through "Accept issue & continue".
+ * @param {Record<string, any> | null | undefined} current
+ * @param {Record<string, any> | null | undefined} previous
+ * @returns {string[]}
+ */
+export function declarationFindings(current, previous) {
+  const out = [];
+  if (isObject(current)) {
+    for (const unknown of unknownConfigKeys(current)) out.push(`CONFIG: ${unknownKeyMessage(unknown)}`);
+  }
+  for (const { key, notice } of droppedMandatedNotices(previous, current)) {
+    out.push(
+      `COMPLIANCE: the live site shows the ${notice} (\`compliance.${key}\`) and this revision no longer ` +
+        `declares it — publishing removes a mandated notice from the store.`,
+    );
+  }
+  return out;
+}
+
+/**
+ * The validator's report on a `.tot/config.json`: a WARNING per unknown key (owner-approved
+ * before publication), an error per wrong-shaped value of a known key.
  * @param {Record<string, any>} config parsed `.tot/config.json` (an object)
  * @param {string} [file]
  * @returns {Finding[]}
  */
 export function validateDeclaredConfig(config, file = ".tot/config.json") {
   const out = [];
-  for (const key of Object.keys(config)) {
-    if (!TOT_CONFIG_KEYS.includes(key)) {
-      const renamed = RENAMED_CONFIG_KEYS[/** @type {keyof typeof RENAMED_CONFIG_KEYS} */ (key)];
-      out.push(mk(ERROR, "config-unknown-key", file,
-        `\`${key}\` is not a .tot/config.json key — the platform never reads it`,
-        renamed ? `use \`${renamed}\`` : `known keys: ${TOT_CONFIG_KEYS.join(", ")}`));
-    }
+  for (const unknown of unknownConfigKeys(config)) {
+    const nested = unknown.path.includes(".");
+    out.push(mk(WARN, nested ? `config-${unknown.path.split(".")[0]}-unknown-key` : "config-unknown-key",
+      nested ? `${file} ${unknown.path.split(".")[0]}` : file,
+      unknownKeyMessage(unknown),
+      unknown.suggestion
+        ? `rename it to \`${unknown.suggestion}\`, or keep it and approve the warning when you publish`
+        : "remove it, or keep it and approve the warning when you publish"));
   }
   if (config.siteType !== undefined && !SITE_TYPES.includes(config.siteType)) {
     out.push(mk(ERROR, "config-site-type", file, `\`siteType\` is "${config.siteType}" — must be one of ${SITE_TYPES.join(", ")}`));
   }
-  /** @type {Array<[string, string[]]>} */
-  const objectFields = [["compliance", COMPLIANCE_KEYS], ["features", FEATURE_KEYS]];
-  for (const [field, known] of objectFields) {
-    const value = config[field];
-    if (value === undefined) continue;
-    if (!isObject(value)) {
+  for (const field of ["compliance", "features"]) {
+    if (config[field] !== undefined && !isObject(config[field])) {
       out.push(mk(ERROR, `config-${field}`, file, `\`${field}\` must be an object`));
-      continue;
-    }
-    for (const key of Object.keys(value)) {
-      if (!known.includes(key)) {
-        out.push(mk(ERROR, `config-${field}-unknown-key`, `${file} ${field}`,
-          `\`${field}.${key}\` is not a ${field} key — nothing renders from it`,
-          `known keys: ${known.join(", ")}`));
-      }
     }
   }
   if (config.capabilities !== undefined && !isObject(config.capabilities)) {

package/src/validate.mjs

@@ -311,6 +311,7 @@ function validateCapabilitiesDoc(doc, file, config) {
     return [mk(ERROR, "capabilities-root", file, "capabilities must be a JSON object")];
   }
   for (const [key, value] of Object.entries(doc)) {
+    if (key === "$schema") continue; // an editor's schema hint, which the devkit tells stores to add
     if (!CAPABILITY_KEYS.has(key)) {
       out.push(mk(ERROR, "capability-unknown", file, `unknown capability "${key}"`));
       continue;
@@ -723,6 +724,21 @@ export const LARGE_PUBLIC_ASSET_FIX =
  * above); `printLoudAdvisories` is the shared renderer.
  */
 export const LOUD_ADVISORY_RULES = [
+  [
+    "config-compliance-unknown-key",
+    "a compliance setting the platform does not read — a mandated notice may be missing",
+    "The store builds and every other check passes, but the notice this key was meant to turn on does not render. Publishing halts until the owner approves it.",
+  ],
+  [
+    "config-unknown-key",
+    "a .tot/config.json key the platform does not read",
+    "It does nothing. Publishing halts until the owner approves it.",
+  ],
+  [
+    "config-features-unknown-key",
+    "a features flag the platform does not read",
+    "The feature it names keeps its default. Publishing halts until the owner approves it.",
+  ],
   [
     "git-conflict-markers",
     "git conflict markers in submitted content — an unfinished merge/rebase?",

package/src/visual-parity.mjs

@@ -1,11 +1,13 @@
 /**
  * Read-only closure checks for the optional visual-parity migration module.
- * The tenant checkout remains portable: this reads only content/, public/, and
- * .tot/visual-parity.json, never a preview host or a delivery provider.
+ * The tenant checkout remains portable: this reads only content/, public/ and theme.json (where
+ * `.tot/config.json` maps them) and .tot/visual-parity.json, never a preview host or a delivery
+ * provider.
  */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { extname, join, relative } from "node:path";
+import { workspacePathForTenantRelative } from "./tot-repo-mappings.mjs";
 
 const ERROR = "error";
 // Public routes implemented by the renderer. Authentication and cart URLs are
@@ -59,10 +61,10 @@ function parseConfig(tenantDir) {
   }
 }
 
-function tenantFromConfig(tenantDir) {
+/** The checkout's `.tot/config.json`, or null when absent or unreadable. */
+function readTotConfig(tenantDir) {
   try {
-    const value = JSON.parse(readFileSync(join(tenantDir, ".tot", "config.json"), "utf8"));
-    return typeof value?.tenant === "string" ? value.tenant : null;
+    return JSON.parse(readFileSync(join(tenantDir, ".tot", "config.json"), "utf8"));
   } catch { return null; }
 }
 
@@ -278,7 +280,11 @@ export function validateVisualParityClosure(tenantDir, options = {}) {
   const findings = [];
   const { value: config, findings: configFindings } = parseConfig(tenantDir);
   findings.push(...configFindings);
-  const pagesDir = join(tenantDir, "content", "pages");
+  // Files are found where the checkout's `.tot/config.json` mappings declare them, as `tot validate`
+  // and the hosted reconcile find them.
+  const totConfig = readTotConfig(tenantDir);
+  const located = (rel) => join(tenantDir, workspacePathForTenantRelative(totConfig, rel));
+  const pagesDir = located("content/pages");
   const files = walk(pagesDir).filter((file) => file.endsWith(".json")).sort();
   if (files.length === 0) findings.push(finding("parity-pages-missing", "content/pages/", "no page JSON files define the visual-parity route scope", "add the paired authored page records under content/pages/ before closing parity"));
   const pages = [];
@@ -297,17 +303,17 @@ export function validateVisualParityClosure(tenantDir, options = {}) {
   const routes = new Set(["/"]);
   for (const page of pages) routes.add(normalizeRoute(page.value.slug));
   /** @type {{findings:ParityFinding[], tenantId:string|null, publicDir:string, routes:Set<string>, allowlist:string[], decodeAssets:DecodeAsset[]}} */
-  const context = { findings, tenantId: tenantId ?? tenantFromConfig(tenantDir), publicDir: join(tenantDir, "public"), routes, allowlist: Array.isArray(config.externalNavigationAllowlist) ? config.externalNavigationAllowlist : [], decodeAssets: [] };
+  const context = { findings, tenantId: tenantId ?? (typeof totConfig?.tenant === "string" ? totConfig.tenant : null), publicDir: located("public"), routes, allowlist: Array.isArray(config.externalNavigationAllowlist) ? config.externalNavigationAllowlist : [], decodeAssets: [] };
   if (!context.tenantId) findings.push(finding("parity-tenant-id", ".tot/config.json", "tenant id is required to verify /tenants/<tenant>/ assets", "set tenant in .tot/config.json or pass a resolved tenant id"));
   for (const page of pages) inspectValue(page.value, page.file, [], context);
   for (const name of ["home.json", "chrome.json"]) {
-    const path = join(tenantDir, "content", name);
+    const path = located(`content/${name}`);
     if (existsSync(path)) {
       const value = readStructured(path, `content/${name}`, findings);
       if (value != null) inspectValue(value, `content/${name}`, [], context);
     }
   }
-  const themePath = join(tenantDir, "theme.json");
+  const themePath = located("theme.json");
   if (existsSync(themePath)) {
     const value = readStructured(themePath, "theme.json", findings);
     if (value != null) inspectValue(value, "theme.json", [], context);