@tokenoftrust/cli 2.5.5 → 2.5.6

package/package.json

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

@@ -39,7 +39,7 @@ export const USAGE = `tot report go-live — the go-live readiness report for yo
 
 Save each page's JSON from the devkit page checks into <dir> first, e.g.
   validate-page.sh <base> / > <dir>/home.json
-  validate-page-browser.mjs <base> / --provider cloudflare > <dir>/home.browser.json
+  validate-page-browser.mjs <base> / --store . --provider cloudflare > <dir>/home.browser.json
 
 ${TEASER}`;
 
@@ -147,9 +147,9 @@ export function storeConfigCheck(lint) {
 /**
  * Everything the report needs, from a page-results directory. A site-wide run's summary is used as
  * is; otherwise the checks are derived here from the single-page results.
- * @param {{ pagesDir: string, stylePath?: string|null, lint?: any }} input
+ * @param {{ pagesDir: string, stylePath?: string|null, lint?: any, config?: Record<string, any>|null }} input the store checkout's lint and `.tot/config.json`
  */
-export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
+export function evidenceFromDir({ pagesDir, stylePath = null, lint = null, config = null }) {
   const summary = readJson(join(pagesDir, "site-summary.json"));
   const styleJson = readJson(stylePath ?? join(pagesDir, "style.json"));
   const browserDir = join(pagesDir, "browser");
@@ -177,6 +177,7 @@ export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
             aggregate: { ...summary, totals: { ...summary.totals, issues: summary.totals?.issues ?? { lowRiskOpen: 0 } } },
             styleJson: styleJson ?? (summary.style?.gates ? { gates: summary.style.gates } : null),
             args: { manifest: summary.manifest ?? "(none supplied to the style-concept audit)" },
+            config,
           }),
         ];
     return {
@@ -195,6 +196,7 @@ export function evidenceFromDir({ pagesDir, stylePath = null, lint = null }) {
       aggregate: { pages: results, totals: { issues: { lowRiskOpen: 0 } } },
       styleJson,
       args: { manifest: "(none supplied to the style-concept audit)" },
+      config,
     }).filter((c) => c.area !== "Low-risk fix loop"),
   ];
   const failing = results.filter((r) => Object.values(r.gates).some((v) => v === false)).length;
@@ -288,7 +290,8 @@ export function run(argv, ctx, io = {}) {
     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 });
+  const config = storeExists ? readJson(join(store, ".tot", "config.json")) : null;
+  const evidence = evidenceFromDir({ pagesDir, stylePath: args.style ? resolve(args.style) : null, lint, config });
   if (!evidence.measured) {
     err(`${fail(
       `no page-check results under ${pagesDir}`,

package/src/declared-config.d.mts

@@ -59,7 +59,10 @@ export const NICOTINE_WARNING_TEXT: string;
 export const CONSPICUITY_FLOOR: Readonly<{ contrast: number; fontSizePx: number; fontWeight: number }>;
 export const DEFAULT_NICOTINE_WARNING_PRESET: string;
 export const NICOTINE_WARNING_PRESETS: Readonly<Record<string, Readonly<NicotineWarningPresentation>>>;
+export const NICOTINE_WARNING_KEYS: readonly string[];
 export const NICOTINE_WARNING_STYLE_KEYS: readonly string[];
+export const NICOTINE_WARNING_CHECK_WIDTH_BOUNDS: Readonly<{ min: number; max: number }>;
+export function nicotineWarningCheckWidths(declaration: unknown): { widths: number[]; problems: string[] };
 export function contrastRatio(a: string, b: string): number;
 export function conspicuityProblems(p: NicotineWarningPresentation): string[];
 export function resolveNicotineWarning(declaration: unknown): ResolvedNicotineWarning;

package/src/declared-config.mjs

@@ -12,7 +12,9 @@
  *
  * 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.
- * Dependency-free: the storefront runner copies this file as-is.
+ * Dependency-free: the storefront runner copies this file as-is, and the devkit page checks carry
+ * a byte-identical copy (docs/devkit-staging/tools/lib/declared-config.mjs, pinned by
+ * test/declared-config-devkit-copy.test.mjs) so their gates read a store's declaration the same way.
  */
 
 export const TOT_CONFIG_KEYS = [
@@ -184,6 +186,7 @@ export const MANDATED_NOTICE_KEYS = [
 
 const ERROR = "error";
 const WARN = "warn";
+/** @type {(v: unknown) => v is Record<string, any>} */
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
 /**
@@ -470,7 +473,13 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     }
   }
   out.push(...complianceFindings(config, file));
-  const warning = resolveNicotineWarning(isObject(config.compliance) ? config.compliance.nicotineWarning : undefined);
+  const declaration = isObject(config.compliance) ? config.compliance.nicotineWarning : undefined;
+  for (const problem of nicotineWarningCheckWidths(declaration).problems) {
+    out.push(mk(ERROR, "config-nicotine-warning-check-widths", `${file} compliance`,
+      `\`compliance.nicotineWarning\`: ${problem}. The page browser gate cannot check the warning at the widths you meant.`,
+      "list the widths where your layout changes (e.g. where your header becomes fixed), or remove `checkWidthsPx`"));
+  }
+  const warning = resolveNicotineWarning(declaration);
   if (warning.enabled && warning.problems.length > 0) {
     out.push(mk(ERROR, "config-nicotine-warning", `${file} compliance`, nicotineWarningProblemMessage(warning.problems),
       'use `true`, `{ "preset": "dark" }` or `{ "preset": "light" }`, or fix the style values named above'));
@@ -504,6 +513,7 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
 //   "nicotineWarning": true                                   → the "dark" preset
 //   "nicotineWarning": { "preset": "light" }                  → a validated preset
 //   "nicotineWarning": { "preset": "light", "style": {...} }  → a custom presentation
+//   "nicotineWarning": { "checkWidthsPx": [800] }             → also checked seen at 800px wide
 //
 // Every presentation — preset or custom — must clear CONSPICUITY_FLOOR. A preset needs no
 // review. A custom presentation is a deviation the owner approves at go-live:
@@ -562,6 +572,9 @@ export const NICOTINE_WARNING_PRESETS = Object.freeze({
  * }} NicotineWarningPresentation
  */
 
+/** Every key a `compliance.nicotineWarning` object may declare. */
+export const NICOTINE_WARNING_KEYS = Object.freeze(["preset", "style", "checkWidthsPx"]);
+
 export const NICOTINE_WARNING_STYLE_KEYS = Object.freeze([
   "background", "text", "border", "textTransform", "fontWeight", "fontSizePx",
 ]);
@@ -669,8 +682,9 @@ export function resolveNicotineWarning(declaration) {
   if (!isObject(declaration)) {
     return resolved({ problems: ["must be `true` or an object like { \"preset\": \"light\" }"] });
   }
-  const { preset: presetName = DEFAULT_NICOTINE_WARNING_PRESET, style, ...rest } = /** @type {Record<string, unknown>} */ (declaration);
-  const problems = Object.keys(rest).map((k) => `\`${k}\` is not a nicotineWarning key (allowed: preset, style)`);
+  const { preset: presetName = DEFAULT_NICOTINE_WARNING_PRESET, style, checkWidthsPx: _checkWidths, ...rest } =
+    /** @type {Record<string, unknown>} */ (declaration);
+  const problems = Object.keys(rest).map((k) => `\`${k}\` is not a nicotineWarning key (allowed: ${NICOTINE_WARNING_KEYS.join(", ")})`);
   const base = typeof presetName === "string" ? NICOTINE_WARNING_PRESETS[presetName] : undefined;
   if (!base) {
     problems.push(`\`preset\` must be one of ${Object.keys(NICOTINE_WARNING_PRESETS).map((p) => `"${p}"`).join(", ")}`);
@@ -695,6 +709,35 @@ export function resolveNicotineWarning(declaration) {
   return resolved({ presentation, preset: matching ?? null, custom: !matching });
 }
 
+/** The viewport widths a store may add to the page browser gate's nicotine-warning check. */
+export const NICOTINE_WARNING_CHECK_WIDTH_BOUNDS = Object.freeze({ min: 320, max: 3840 });
+
+/**
+ * The extra viewport widths at which the page browser gate checks the nicotine warning is seen.
+ *
+ * The gate always checks its own phone, tablet, laptop and desktop widths; `checkWidthsPx` adds
+ * the store's own breakpoints (e.g. the width where its header becomes fixed) and never removes
+ * a default. A store that does not declare the warning has no widths; `true` and an object
+ * without `checkWidthsPx` add none.
+ *
+ *   "nicotineWarning": { "preset": "dark", "checkWidthsPx": [800, 1180] }
+ *
+ * `problems` lists why a declared value is unusable, in which case no extra width is used.
+ * @param {unknown} declaration the store's `compliance.nicotineWarning`
+ * @returns {{ widths: number[], problems: string[] }}
+ */
+export function nicotineWarningCheckWidths(declaration) {
+  if (!isObject(declaration)) return { widths: [], problems: [] };
+  const value = /** @type {Record<string, unknown>} */ (declaration).checkWidthsPx;
+  if (value === undefined) return { widths: [], problems: [] };
+  const { min, max } = NICOTINE_WARNING_CHECK_WIDTH_BOUNDS;
+  const usable = (/** @type {unknown} */ w) => Number.isInteger(w) && /** @type {number} */ (w) >= min && /** @type {number} */ (w) <= max;
+  if (!Array.isArray(value) || value.length === 0 || !value.every(usable)) {
+    return { widths: [], problems: [`\`checkWidthsPx\` must be a non-empty array of whole pixel widths from ${min} to ${max}, e.g. [800]`] };
+  }
+  return { widths: [...new Set(/** @type {number[]} */ (value))].sort((a, b) => a - b), problems: [] };
+}
+
 /**
  * The exact, human-readable statement of a custom presentation — what the owner approves.
  * Every resolved value is in it, so two presentations that differ in any value describe
@@ -720,7 +763,8 @@ export function describeNicotineWarningPresentation(p) {
  * fixed or sticky header pinned to the top of the viewport). Raising the warning above page
  * chrome would paint it over the tenant's own open menus and drawers, so occlusion is measured
  * instead: the page browser gate (`validate-page-browser.mjs`, `nicotineWarning`) fails a page
- * whose warning is covered at a phone, tablet or desktop width and names the covering element.
+ * whose warning is covered at a phone, tablet or desktop width, or at a width the store declares
+ * in `checkWidthsPx`, and names the covering element.
  * @param {unknown} declaration the tenant's `compliance.nicotineWarning`
  * @param {"bar" | "block"} variant
  */

package/src/readiness-checks.mjs

@@ -178,8 +178,38 @@ export function ecommerceStyleGuideCheck(styleJson) {
   };
 }
 
-export function buildReadinessChecks({ aggregate, styleJson, args }) {
+/**
+ * The store's declared compliance notices, judged on every page. Only a notice the store declares
+ * is a row, and a page that did not judge it fails: a declared legal notice nobody has seen on the
+ * page is not ready, whatever the page check reported.
+ * @param {{ gates?: Record<string, boolean | null> }[]} results
+ * @param {Record<string, any> | null | undefined} config the store's `.tot/config.json`
+ */
+export function complianceNoticesCheck(results, config) {
+  if (!config?.compliance?.nicotineWarning) return null;
+  const counts = countGate(results, "nicotineWarning");
+  const problem = counts.total === 0
+    ? "No pages were discovered for validation."
+    : counts.fail > 0 || counts.unknown > 0
+      ? `The store declares the FDA nicotine warning: ${counts.fail}/${counts.total} page(s) fail the visibility gate` +
+        `${counts.unknown > 0 ? ` and ${counts.unknown}/${counts.total} were not judged against the declaration` : ""}.`
+      : `The FDA nicotine warning is seen on all ${counts.total} page(s) at every checked width.`;
+  return {
+    area: "Compliance notices",
+    status: counts.total > 0 && counts.fail === 0 && counts.unknown === 0 ? "PASS" : "FAIL",
+    why: "A store that declares the FDA nicotine warning must show it, conspicuously and uncovered, on every page (21 CFR 1143.3).",
+    problem,
+    fix: "Run the browser page checks with --store <your checkout> on every page, then offset any fixed or sticky header the gate names; never restyle or move the warning.",
+  };
+}
+
+/**
+ * @param {{ aggregate: any, styleJson: any, args: { manifest: string }, config?: Record<string, any> | null }} input
+ *   `config` is the store's `.tot/config.json`, which decides the compliance notices row.
+ */
+export function buildReadinessChecks({ aggregate, styleJson, args, config = null }) {
   const results = aggregate.pages;
+  const compliance = complianceNoticesCheck(results, config);
   const render = countGate(results, "render");
   const boundary = countGate(results, "boundary");
   const seo = combineCounts(countGate(results, "seo"), countGate(results, "sitemap"));
@@ -191,6 +221,7 @@ export function buildReadinessChecks({ aggregate, styleJson, args }) {
   const lowRisk = aggregate.totals.issues.lowRiskOpen ?? 0;
 
   return [
+    ...(compliance ? [compliance] : []),
     styleGuideCheck(styleJson, args.manifest),
     ecommerceStyleGuideCheck(styleJson),
     styleQualityCheck(styleJson),