@tokenoftrust/cli 2.5.6 → 2.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.5.6",
+  "version": "2.5.7",
   "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

@@ -32,10 +32,21 @@ export function declarationFindings(
   current: Record<string, unknown> | null | undefined,
   previous: Record<string, unknown> | null | undefined,
 ): string[];
+export interface DeclaredObligation {
+  id: string;
+  surface: string;
+}
+export const COMPLIANCE_OBLIGATIONS: readonly Readonly<{ id: string; surface: string; keys: string[] }>[];
+export function declaredObligations(compliance: object | null | undefined): DeclaredObligation[];
 export function isRegulatedCompliance(compliance: object | null | undefined): boolean;
+export const COHERENCE_CHECK_IDS: readonly ("age_gate" | "excise" | "jurisdiction")[];
+export const OBLIGATION_EVIDENCE_CHECK: Readonly<Record<string, "age_gate" | "excise" | "jurisdiction" | null>>;
+export function isRegulatedObligationSet(obligations: readonly DeclaredObligation[]): boolean;
+export function coherenceChecksFor(obligations: readonly DeclaredObligation[]): ("age_gate" | "excise" | "jurisdiction")[];
 export function declaresJurisdictionNotice(compliance: object | null | undefined): boolean;
 export function complianceCoherenceFailures(
   compliance: object | null | undefined,
+  obligations?: readonly DeclaredObligation[],
 ): Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string; detail: string; hint: string }>>;
 export function complianceFindings(config: Record<string, unknown>, file?: string): DeclaredConfigFinding[];
 export function validateDeclaredConfig(config: Record<string, unknown>, file?: string): DeclaredConfigFinding[];

package/src/declared-config.mjs

@@ -189,6 +189,40 @@ const WARN = "warn";
 /** @type {(v: unknown) => v is Record<string, any>} */
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
+/**
+ * The platform's compliance obligations — the registry in
+ * packages/public-runtime/src/compliance-obligations.ts, mirrored here because this file
+ * is dependency-free: each duty's id, its compliance-authority surface, and the declared
+ * `compliance.*` keys that switch it on. packages/private-controlplane/tests/
+ * compliance-obligation-checks.test.ts pins this list to the registry, key for key.
+ */
+export const COMPLIANCE_OBLIGATIONS = Object.freeze([
+  { id: "age_gate", surface: "regulated", keys: ["minAge"] },
+  { id: "excise", surface: "regulated", keys: ["nicotineWarning", "exciseTax"] },
+  { id: "nicotine_warning", surface: "regulated", keys: ["nicotineWarning"] },
+  { id: "pact_act", surface: "regulated", keys: ["pactAct"] },
+  { id: "adult_signature", surface: "regulated", keys: ["adultSignature"] },
+  { id: "prop65", surface: "commerce", keys: ["prop65"] },
+  { id: "jurisdiction", surface: "commerce", keys: ["stateEligibility", "shippingRestriction"] },
+]);
+
+/**
+ * The obligations a declared compliance block switches on, as `resolveObligations` returns
+ * them (id + surface), in registry order.
+ * @param {Record<string, any> | null | undefined} compliance
+ * @returns {{ id: string, surface: string }[]}
+ */
+export function declaredObligations(compliance) {
+  return COMPLIANCE_OBLIGATIONS
+    .filter((o) => o.keys.some((key) => !!compliance?.[key]))
+    .map(({ id, surface }) => ({ id, surface }));
+}
+
+/** True when the declared block puts the store on the regulated surface. */
+export function isRegulatedCompliance(compliance) {
+  return isRegulatedObligationSet(declaredObligations(compliance));
+}
+
 /**
  * Compliance coherence — the declared-config half of the hosted preview's `age_gate`,
  * `excise` and `jurisdiction` evidence checks, so `tot validate` fails locally on
@@ -196,9 +230,42 @@ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
  * packages/public-runtime/src/compliance-coherence.mjs (the platform's single source);
  * test/declared-config-parity.test.mjs pins the two together.
  */
-export function isRegulatedCompliance(compliance) {
-  const minAge = compliance?.minAge;
-  return (typeof minAge === "number" && minAge > 0) || !!compliance?.nicotineWarning;
+export const COHERENCE_CHECK_IDS = Object.freeze(/** @type {const} */ (["age_gate", "excise", "jurisdiction"]));
+
+export const OBLIGATION_EVIDENCE_CHECK = Object.freeze({
+  age_gate: "age_gate",
+  excise: "excise",
+  nicotine_warning: "excise",
+  pact_act: "jurisdiction",
+  adult_signature: "jurisdiction",
+  jurisdiction: "jurisdiction",
+  prop65: null,
+});
+
+/** @param {readonly { id: string, surface: string }[]} obligations */
+export function isRegulatedObligationSet(obligations) {
+  return obligations.some((o) => o.surface === "regulated");
+}
+
+/**
+ * @param {readonly { id: string, surface: string }[]} obligations
+ * @returns {("age_gate" | "excise" | "jurisdiction")[]}
+ */
+export function coherenceChecksFor(obligations) {
+  const out = new Set();
+  if (isRegulatedObligationSet(obligations)) {
+    out.add("age_gate");
+    out.add("jurisdiction");
+  }
+  for (const { id } of obligations) {
+    if (!Object.hasOwn(OBLIGATION_EVIDENCE_CHECK, id)) {
+      for (const check of COHERENCE_CHECK_IDS) out.add(check);
+      continue;
+    }
+    const check = OBLIGATION_EVIDENCE_CHECK[/** @type {keyof typeof OBLIGATION_EVIDENCE_CHECK} */ (id)];
+    if (check) out.add(check);
+  }
+  return COHERENCE_CHECK_IDS.filter((c) => out.has(c));
 }
 
 export function declaresJurisdictionNotice(compliance) {
@@ -206,19 +273,48 @@ export function declaresJurisdictionNotice(compliance) {
   return compliance?.pactAct === true || (typeof text === "string" && text.trim().length > 0);
 }
 
+/** @param {unknown} declaration */
+function stateEligibilityHasContent(declaration) {
+  if (declaration === null || typeof declaration !== "object" || Array.isArray(declaration)) return false;
+  const d = /** @type {Record<string, unknown>} */ (declaration);
+  const listed = (v) => Array.isArray(v) && v.some((s) => typeof s === "string" && s.trim().length > 0);
+  return listed(d.restrictedStates) || listed(d.eligibleStates) || (typeof d.note === "string" && d.note.trim().length > 0);
+}
+
+const REGULATED_KEY_FOR = Object.freeze({
+  age_gate: "minAge",
+  excise: "exciseTax",
+  nicotine_warning: "nicotineWarning",
+  pact_act: "pactAct",
+  adult_signature: "adultSignature",
+});
+
+function regulatedBy(compliance, obligations) {
+  const keys = new Set();
+  for (const o of obligations) {
+    if (o.surface !== "regulated") continue;
+    const key = REGULATED_KEY_FOR[/** @type {keyof typeof REGULATED_KEY_FOR} */ (o.id)];
+    if (o.id === "excise" && !compliance?.exciseTax) continue;
+    if (key) keys.add(key);
+  }
+  return [...keys].map((k) => `\`compliance.${k}\``).join(", ") || "a regulated obligation";
+}
+
 /**
  * @param {Record<string, any> | null | undefined} compliance
+ * @param {readonly { id: string, surface: string }[]} [obligations] defaults to what the block declares
  * @returns {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>}
  */
-export function complianceCoherenceFailures(compliance) {
+export function complianceCoherenceFailures(compliance, obligations = declaredObligations(compliance)) {
   /** @type {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>} */
   const out = {};
-  if (!isRegulatedCompliance(compliance)) return out;
+  const checks = coherenceChecksFor(obligations);
+  const regulated = isRegulatedObligationSet(obligations);
   const minAge = typeof compliance?.minAge === "number" ? compliance.minAge : null;
-  if (minAge == null || minAge < 18) {
+  if (checks.includes("age_gate") && regulated && (minAge == null || minAge < 18)) {
     out.age_gate = {
       field: "compliance.minAge",
-      detail: "Age-restricted/nicotine products require `compliance.minAge` (18 or higher) — none is set.",
+      detail: `Age-restricted products (${regulatedBy(compliance, obligations)}) require \`compliance.minAge\` (18 or higher) — none is set.`,
       hint: "Set `compliance.minAge` (18+) in .tot/config.json.",
     };
   }
@@ -229,16 +325,29 @@ export function complianceCoherenceFailures(compliance) {
       hint: "Set `compliance.minAge` to 21 in .tot/config.json (nicotine requires 21+, not just 18+).",
     };
   }
-  if (!declaresJurisdictionNotice(compliance)) {
-    out.jurisdiction = {
-      field: "compliance.pactAct",
-      detail:
-        "Regulated products require a shipping/jurisdiction notice: set `compliance.pactAct: true` " +
-        "or `compliance.shippingRestriction` — neither is set.",
-      hint:
-        "Set `compliance.pactAct: true` for the platform's PACT Act notice, or " +
-        "`compliance.shippingRestriction` to your own restriction text, in .tot/config.json.",
-    };
+  if (checks.includes("jurisdiction")) {
+    if (regulated && !declaresJurisdictionNotice(compliance)) {
+      out.jurisdiction = {
+        field: "compliance.pactAct",
+        detail:
+          `Regulated products (${regulatedBy(compliance, obligations)}) require a shipping/jurisdiction notice: ` +
+          "set `compliance.pactAct: true` or `compliance.shippingRestriction` — neither is set.",
+        hint:
+          "Set `compliance.pactAct: true` for the platform's PACT Act notice, or " +
+          "`compliance.shippingRestriction` to your own restriction text, in .tot/config.json.",
+      };
+    } else if (!regulated && !declaresJurisdictionNotice(compliance)
+      && !stateEligibilityHasContent(compliance?.stateEligibility)) {
+      const field = compliance?.stateEligibility ? "compliance.stateEligibility" : "compliance.shippingRestriction";
+      out.jurisdiction = {
+        field,
+        detail:
+          `\`${field}\` is declared but gives its shipping/jurisdiction notice nothing to say, so no notice renders.`,
+        hint:
+          "Set `compliance.shippingRestriction` to your restriction text, or give `compliance.stateEligibility` " +
+          "`restrictedStates`, `eligibleStates` or a `note`, in .tot/config.json.",
+      };
+    }
   }
   return out;
 }
@@ -254,27 +363,29 @@ export function complianceCoherenceFailures(compliance) {
  */
 export function complianceFindings(config, file = ".tot/config.json") {
   const compliance = isObject(config?.compliance) ? config.compliance : null;
+  const obligations = declaredObligations(compliance);
+  const owed = new Set(obligations.map((o) => o.id));
   const out = [];
-  for (const [check, failure] of Object.entries(complianceCoherenceFailures(compliance))) {
+  for (const [check, failure] of Object.entries(complianceCoherenceFailures(compliance, obligations))) {
     out.push(mk(ERROR, `compliance-${check.replace("_", "-")}`, `${file} compliance`,
       `${failure.detail} The hosted preview fails its \`${check}\` check on this.`, failure.hint));
   }
   // The hosted reconcile refuses a declaration whose `capabilities` switch off the
   // compliance floor (packages/public-runtime/src/capabilities.ts capabilityFloorViolations).
   const capabilities = isObject(config?.capabilities) ? config.capabilities : {};
-  if (compliance?.minAge && capabilities.ageVerification?.enabled === false) {
+  if (owed.has("age_gate") && capabilities.ageVerification?.enabled === false) {
     out.push(mk(ERROR, "capability-compliance-floor", `${file} capabilities`,
       "`capabilities.ageVerification` cannot be disabled for a store with `compliance.minAge` — the hosted preview refuses this revision.",
       "Remove `capabilities.ageVerification.enabled: false` from .tot/config.json."));
   }
-  if (compliance?.nicotineWarning && capabilities.exciseTax?.enabled === false) {
+  if (owed.has("excise") && capabilities.exciseTax?.enabled === false) {
     out.push(mk(ERROR, "capability-compliance-floor", `${file} capabilities`,
-      "`capabilities.exciseTax` cannot be disabled for a store with `compliance.nicotineWarning` — the hosted preview refuses this revision.",
+      "`capabilities.exciseTax` cannot be disabled for a store with `compliance.nicotineWarning` or `compliance.exciseTax` — the hosted preview refuses this revision.",
       "Remove `capabilities.exciseTax.enabled: false` from .tot/config.json."));
   }
-  if (isRegulatedCompliance(compliance) && !compliance?.ruleProfile) {
+  if (isRegulatedObligationSet(obligations) && !compliance?.ruleProfile) {
     out.push(mk(WARN, "compliance-rule-profile", `${file} compliance`,
-      "This store is regulated (`compliance.minAge`/`compliance.nicotineWarning`) but declares no " +
+      `This store is regulated (${regulatedBy(compliance, obligations)}) but declares no ` +
         "`compliance.ruleProfile`, so no checkout rules resolve: the preview renders, but checkout blocks " +
         "and going live refuses.",
       'Declare `compliance.ruleProfile` (e.g. "vape-nicotine-us") in .tot/config.json.'));

package/src/validate.mjs

@@ -17,7 +17,7 @@
  */
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
-import { validateDeclaredConfig } from "./declared-config.mjs";
+import { declaredObligations, isRegulatedCompliance, validateDeclaredConfig } from "./declared-config.mjs";
 import {
   foreignTenantSegments,
   parseMappingTarget,
@@ -291,18 +291,17 @@ function validateEmbedsDoc(doc, file) {
   return out;
 }
 
+// What the obligation registry says this store owes (declared-config.mjs mirrors it).
 function complianceObligations(config) {
-  const compliance = config?.compliance || {};
+  const owed = new Set(declaredObligations(config?.compliance).map((o) => o.id));
   return {
-    ageVerification: !!compliance.minAge,
-    exciseTax: !!compliance.nicotineWarning,
+    ageVerification: owed.has("age_gate"),
+    exciseTax: owed.has("excise"),
   };
 }
 
 function rawHtmlAllowed(config) {
-  const obligations = complianceObligations(config);
-  const regulated = obligations.ageVerification || obligations.exciseTax;
-  return !regulated;
+  return !isRegulatedCompliance(config?.compliance);
 }
 
 function validateCapabilitiesDoc(doc, file, config) {
@@ -325,7 +324,7 @@ function validateCapabilitiesDoc(doc, file, config) {
     out.push(mk(ERROR, "capability-compliance-floor", file, "ageVerification cannot be disabled for a tenant with compliance.minAge"));
   }
   if (obligations.exciseTax && doc.exciseTax?.enabled === false) {
-    out.push(mk(ERROR, "capability-compliance-floor", file, "exciseTax cannot be disabled for a tenant with compliance.nicotineWarning"));
+    out.push(mk(ERROR, "capability-compliance-floor", file, "exciseTax cannot be disabled for a tenant with compliance.nicotineWarning or compliance.exciseTax"));
   }
   return out;
 }