@tokenoftrust/cli 2.2.17 → 2.3.0

package/package.json

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

@@ -180,6 +180,8 @@ export function hotfixNextStep(reason) {
       return "re-run `tot hotfix` and confirm the plan";
     case "digest_mismatch":
       return "main moved under review — re-preview the hotfix against current main, then re-run `tot hotfix`";
+    case "provider_unsupported":
+      return "publish the fix through `tot ship` (Add to release, then Publish) instead";
     default:
       return "re-run `tot hotfix`";
   }

package/src/commands/preview-token.mjs

@@ -0,0 +1,148 @@
+/**
+ * `tot preview token` — mint a shared-preview `__preview` token for a store you have
+ * access to, for validation runs (`validate-site --preview-token`, `parity-check`,
+ * Lighthouse against the preview channel).
+ *
+ * AUTH — your own `tot login`. The CLI exchanges your MCP session for a storefront
+ * viewer session (`resolveViewerTransport`), then asks `POST /api/preview/token`,
+ * which mints only when that session may already view this store's preview. No
+ * operator secret, and no token for a store you cannot see.
+ *
+ * OUTPUT — the token alone on stdout, so `export PARITY_PREVIEW_TOKEN="$(tot preview
+ * token)"` works; its expiry and the commit the preview channel serves go to stderr.
+ * `--json` prints `{ token, exp, ttlSeconds, tenantId, previewVersion }` instead.
+ * Treat the token like a password: anyone holding it sees the unpublished site.
+ */
+import { resolveViewerTransport } from "../viewer-session.mjs";
+
+const MAX_TTL_SECONDS = 24 * 3600;
+
+/** Parse `tot preview token` argv. Pure — unit-tested. */
+export function parseTokenArgs(argv) {
+  const a = { tenant: null, ttl: null, url: null, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--ttl") a.ttl = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--json") a.json = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+export function renderUsage() {
+  return `tot preview token — mint a preview token for validation runs
+
+Usage:
+  tot preview token [--tenant <appDomain>] [--ttl <seconds>] [--json]
+
+Prints a signed token for the store's SHARED preview channel. Pass it to
+validate-site / parity-check as --preview-token (or PARITY_PREVIEW_TOKEN).
+Requires \`tot login\` and access to the store; the token is never longer-lived
+than you asked for (default 1h, max 24h).
+
+Options:
+  --tenant <appDomain>   Store to mint for. Defaults to the current checkout's store.
+  --ttl <seconds>        Token lifetime (default 3600, max ${MAX_TTL_SECONDS}).
+  --url <origin>         Storefront origin. Defaults to $TOT_STOREFRONT_URL or the
+                         hosted storefront.
+  --json                 Print { token, exp, ttlSeconds, tenantId, previewVersion }.
+  --help, -h             Show this help.
+
+Example:
+  node agency-kit/tools/validate-site.mjs ... --preview-token "$(tot preview token)"`;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx — detected CLI context (ctx.tenant when in a checkout)
+ * @param {{ resolveViewerTransport?: typeof resolveViewerTransport, fetchImpl?: typeof fetch,
+ *   env?: NodeJS.ProcessEnv, out?: (s: string) => void, err?: (s: string) => void }} [deps]
+ */
+export async function run(argv, ctx, deps = {}) {
+  const out = deps.out || ((s) => process.stdout.write(`${s}\n`));
+  const err = deps.err || ((s) => process.stderr.write(`${s}\n`));
+  const env = deps.env || process.env;
+  const fetchImpl = deps.fetchImpl || fetch;
+  const resolveViewer = deps.resolveViewerTransport || resolveViewerTransport;
+
+  const args = parseTokenArgs(argv);
+  if (args.help) {
+    out(renderUsage());
+    return 0;
+  }
+
+  const tenant = String(args.tenant || ctx?.tenant || "").trim().toLowerCase();
+  if (!tenant) {
+    err("✗ no store to mint for.\n\n  → next: pass --tenant <appDomain>, or run inside a store checkout.");
+    return 2;
+  }
+
+  let ttlSeconds;
+  if (args.ttl != null) {
+    ttlSeconds = Number(args.ttl);
+    if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > MAX_TTL_SECONDS) {
+      err(`✗ --ttl must be a whole number of seconds between 1 and ${MAX_TTL_SECONDS}.`);
+      return 2;
+    }
+  }
+
+  const storefrontUrl = args.url || env.TOT_STOREFRONT_URL || null;
+  const transport = await resolveViewer({ tenant, env, fetchImpl, storefrontUrl });
+  if (!transport.ok) {
+    err(`✗ ${transport.message}\n\n  → next: ${transport.hint}`);
+    return 1;
+  }
+
+  let res;
+  try {
+    res = await fetchImpl(`${transport.base}/api/preview/token`, {
+      method: "POST",
+      headers: { ...transport.authHeaders, "content-type": "application/json" },
+      body: JSON.stringify({ tenant, ...(ttlSeconds ? { ttlSeconds } : {}) }),
+    });
+  } catch (e) {
+    err(`✗ could not reach ${transport.base}: ${e?.message || e}\n\n  → next: check --url / your network.`);
+    return 1;
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    err(
+      `✗ your account can't view ${tenant}'s preview.\n\n` +
+        "  → next: ask the store owner for developer access (or check `tot whoami`), then re-run.",
+    );
+    return 1;
+  }
+  let data = null;
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON error body */
+  }
+  if (!res.ok || typeof data?.token !== "string") {
+    err(`✗ the store didn't mint a token (HTTP ${res.status}).\n\n  → next: retry shortly; if it persists, report it with \`tot feedback\`.`);
+    return 1;
+  }
+
+  if (args.json) {
+    out(JSON.stringify({
+      token: data.token,
+      exp: data.exp ?? null,
+      ttlSeconds: data.ttlSeconds ?? null,
+      tenantId: data.tenantId ?? tenant,
+      previewVersion: data.previewVersion ?? null,
+    }));
+    return 0;
+  }
+  out(data.token);
+  const expires = Number.isFinite(data.exp) ? new Date(data.exp * 1000).toISOString() : "in 1h";
+  err(`  ✓ preview token for ${data.tenantId ?? tenant} — expires ${expires}.`);
+  err(
+    data.previewVersion
+      ? `    the preview channel serves ${data.previewVersion} (pass it as --preview-version).`
+      : "    the preview channel has not reconciled a commit yet.",
+  );
+  err("    anyone holding this token sees the unpublished site — don't paste it into tickets.");
+  return 0;
+}

package/src/commands/preview.mjs

@@ -75,6 +75,13 @@ export async function run(argv, ctx, { alias = null } = {}) {
     return runRetryEvidence(argv.slice(1), ctx);
   }
 
+  // `tot preview token` mints a shared-preview token for validation runs, from the
+  // developer's own login — dispatched before the submit-flow arg parse, like `build`.
+  if (!alias && argv[0] === "token") {
+    const { run: runToken } = await import("./preview-token.mjs");
+    return runToken(argv.slice(1), ctx);
+  }
+
   const verb = alias || "preview";
   const args = parseArgs(argv);
 

package/src/declared-config.d.mts

@@ -0,0 +1,65 @@
+/** 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 isRegulatedCompliance(compliance: object | null | undefined): boolean;
+export function declaresJurisdictionNotice(compliance: object | null | undefined): boolean;
+export function complianceCoherenceFailures(
+  compliance: object | null | undefined,
+): 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[];
+
+export interface NicotineWarningPresentation {
+  background: string;
+  text: string;
+  border: string;
+  textTransform: "uppercase" | "none";
+  fontWeight: number;
+  fontSizePx: number;
+}
+export interface ResolvedNicotineWarning {
+  enabled: boolean;
+  presentation: NicotineWarningPresentation;
+  preset: string | null;
+  custom: boolean;
+  problems: string[];
+}
+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_STYLE_KEYS: readonly string[];
+export function contrastRatio(a: string, b: string): number;
+export function conspicuityProblems(p: NicotineWarningPresentation): string[];
+export function resolveNicotineWarning(declaration: unknown): ResolvedNicotineWarning;
+export function describeNicotineWarningPresentation(p: NicotineWarningPresentation): string;
+export function unreviewedNicotineWarningPresentation(
+  current: Record<string, unknown> | null | undefined,
+  previous: Record<string, unknown> | null | undefined,
+): string | null;
+export function nicotineWarningHtml(declaration: unknown, variant: "bar" | "block"): string;
+export function nicotineWarningStyle(p: NicotineWarningPresentation, variant: "bar" | "block"): string;

package/src/declared-config.mjs

@@ -1,17 +1,23 @@
 /**
- * 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 = [
   "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "siteType", "compliance", "capabilities", "features", "embeds",
+  "displayName", "siteType", "compliance", "capabilities", "features", "embeds",
 ];
 // Keys other tooling has written that the platform does NOT read, with the key it does.
 const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
@@ -24,53 +30,330 @@ 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);
 
+/**
+ * Compliance coherence — the declared-config half of the hosted preview's `age_gate`,
+ * `excise` and `jurisdiction` evidence checks, so `tot validate` fails locally on
+ * exactly what the reconcile fails. Mirrors
+ * 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 function declaresJurisdictionNotice(compliance) {
+  const text = compliance?.shippingRestriction;
+  return compliance?.pactAct === true || (typeof text === "string" && text.trim().length > 0);
+}
+
+/**
+ * @param {Record<string, any> | null | undefined} compliance
+ * @returns {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>}
+ */
+export function complianceCoherenceFailures(compliance) {
+  /** @type {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>} */
+  const out = {};
+  if (!isRegulatedCompliance(compliance)) return out;
+  const minAge = typeof compliance?.minAge === "number" ? compliance.minAge : null;
+  if (minAge == null || minAge < 18) {
+    out.age_gate = {
+      field: "compliance.minAge",
+      detail: "Age-restricted/nicotine products require `compliance.minAge` (18 or higher) — none is set.",
+      hint: "Set `compliance.minAge` (18+) in .tot/config.json.",
+    };
+  }
+  if (compliance?.nicotineWarning && (minAge == null || minAge < 21)) {
+    out.excise = {
+      field: "compliance.minAge",
+      detail: "Nicotine products (`compliance.nicotineWarning`) require `compliance.minAge` of 21 or higher.",
+      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.",
+    };
+  }
+  return out;
+}
+
+/**
+ * The compliance findings `tot validate` reports for a declared block: an ERROR per
+ * coherence failure the hosted preview would fail (`evidence-<check>`), and a WARNING
+ * when a regulated store declares no `ruleProfile` — its preview renders, but going
+ * live refuses because no checkout rules resolve.
+ * @param {Record<string, any>} config
+ * @param {string} file
+ * @returns {Finding[]}
+ */
+export function complianceFindings(config, file = ".tot/config.json") {
+  const compliance = isObject(config?.compliance) ? config.compliance : null;
+  const out = [];
+  for (const [check, failure] of Object.entries(complianceCoherenceFailures(compliance))) {
+    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) {
+    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) {
+    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.",
+      "Remove `capabilities.exciseTax.enabled: false` from .tot/config.json."));
+  }
+  if (isRegulatedCompliance(compliance) && !compliance?.ruleProfile) {
+    out.push(mk(WARN, "compliance-rule-profile", `${file} compliance`,
+      "This store is regulated (`compliance.minAge`/`compliance.nicotineWarning`) 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.'));
+  }
+  return out;
+}
+
 /** @typedef {{level:string, rule:string, file:string, message:string, fix?:string}} Finding */
 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 FDA nicotine warning presentation this revision would put live that the live site does
+ * not already show: a custom (non-preset) presentation whose resolved values differ from the
+ * live revision's. Null when the warning is off, invalid, a validated preset, or unchanged.
+ * @param {Record<string, any> | null | undefined} current
+ * @param {Record<string, any> | null | undefined} previous
+ * @returns {string | null} the exact presentation, as describeNicotineWarningPresentation states it
+ */
+export function unreviewedNicotineWarningPresentation(current, previous) {
+  const now = resolveNicotineWarning(isObject(current?.compliance) ? current.compliance.nicotineWarning : undefined);
+  if (!now.enabled || !now.custom) return null;
+  const before = resolveNicotineWarning(isObject(previous?.compliance) ? previous.compliance.nicotineWarning : undefined);
+  const spec = describeNicotineWarningPresentation(now.presentation);
+  return before.enabled && before.custom && describeNicotineWarningPresentation(before.presentation) === spec ? null : spec;
+}
+
+/**
+ * The publication validator's findings for a revision's declaration: an owner-approvable
+ * `CONFIG:` finding per unknown key or invalid nicotine-warning presentation, a `COMPLIANCE:`
+ * finding per mandated notice the live site shows and this revision drops, and a
+ * `COMPLIANCE:` finding for a custom nicotine-warning presentation the live site does not
+ * already show. All are QUALITY findings (scripts/publish/lib/finding-severity.mjs):
+ * publication halts until the owner accepts them through "Accept issue & continue", which
+ * records who accepted these exact findings, when, and why.
+ * @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)}`);
+    const warning = resolveNicotineWarning(isObject(current.compliance) ? current.compliance.nicotineWarning : undefined);
+    if (warning.enabled && warning.problems.length > 0) {
+      out.push(`CONFIG: ${nicotineWarningProblemMessage(warning.problems)}`);
+    }
+  }
+  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.`,
+    );
+  }
+  const custom = unreviewedNicotineWarningPresentation(current, previous);
+  if (custom) {
+    out.push(
+      `COMPLIANCE: the FDA nicotine warning uses a custom presentation outside the validated presets — ${custom}. ` +
+        `Approving records that you reviewed exactly these values; changing any of them asks again.`,
+    );
+  }
+  return out;
+}
+
+/** The owner-facing sentence for an invalid `compliance.nicotineWarning`. */
+function nicotineWarningProblemMessage(problems) {
+  return `\`compliance.nicotineWarning\` is not a valid presentation (${problems.join("; ")}). ` +
+    `The warning renders in the default "dark" preset instead.`;
+}
+
+/**
+ * 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.displayName !== undefined && !(typeof config.displayName === "string" && config.displayName.trim())) {
+    out.push(mk(ERROR, "config-display-name", file,
+      "`displayName` must be a non-empty string — the store's name as visitors read it (page titles, og:site_name, the copyright line)"));
   }
   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(", ")}`));
-      }
     }
   }
+  out.push(...complianceFindings(config, file));
+  const warning = resolveNicotineWarning(isObject(config.compliance) ? config.compliance.nicotineWarning : undefined);
+  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'));
+  } else if (warning.custom) {
+    out.push(mk(WARN, "config-nicotine-warning-custom", `${file} compliance`,
+      `\`compliance.nicotineWarning\` uses a custom presentation outside the validated presets — ` +
+        `${describeNicotineWarningPresentation(warning.presentation)}. It renders in preview; it goes live only ` +
+        `after you approve it in the go-live compliance review.`,
+      'use a preset (`"dark"`, `"light"`) to skip the review, or keep it and approve it when you publish'));
+  }
   if (config.capabilities !== undefined && !isObject(config.capabilities)) {
     out.push(mk(ERROR, "config-capabilities", file, "`capabilities` must be an object"));
   }
@@ -80,3 +363,254 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
   }
   return out;
 }
+
+// ── The FDA nicotine warning (21 CFR 1143.3): what compliance.nicotineWarning may declare ──
+//
+// The wording is fixed by law and is not configurable. The presentation is one of the
+// validated presets, or a custom style built on one:
+//
+//   "nicotineWarning": true                                   → the "dark" preset
+//   "nicotineWarning": { "preset": "light" }                  → a validated preset
+//   "nicotineWarning": { "preset": "light", "style": {...} }  → a custom presentation
+//
+// 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:
+// declarationFindings raises it as a COMPLIANCE finding that spells out every resolved style
+// value, and the owner's "Accept issue & continue" records who approved exactly those values,
+// when, and why. Any change to the styling produces a different finding, so it is reviewed again.
+//
+// The style keys are a closed set of colours, case, weight and size. Nothing here can position,
+// hide, shrink below the floor, or dismiss the warning, and a declaration that is invalid renders
+// the default preset rather than nothing. The hosted renderer (NicotineWarning.astro and the
+// raw-HTML path) renders through nicotineWarningHtml, so every surface presents it identically.
+
+export const NICOTINE_WARNING_TEXT =
+  "WARNING: This product contains nicotine. Nicotine is an addictive chemical.";
+
+/** The floor every presentation clears: WCAG AAA text contrast, a 12px minimum, semibold or heavier. */
+export const CONSPICUITY_FLOOR = Object.freeze({ contrast: 7, fontSizePx: 12, fontWeight: 600 });
+
+/** Bounds on the size a custom style may declare, so the bar cannot swallow the header. */
+const MAX_FONT_SIZE_PX = 24;
+
+export const DEFAULT_NICOTINE_WARNING_PRESET = "dark";
+
+/**
+ * The validated presets. `dark` is the platform default; `light` matches a light bar with a
+ * dark border and bold normal-case text.
+ * @type {Readonly<Record<string, Readonly<NicotineWarningPresentation>>>}
+ */
+export const NICOTINE_WARNING_PRESETS = Object.freeze({
+  dark: Object.freeze({
+    background: "#111111",
+    text: "#ffffff",
+    border: "#111111",
+    textTransform: "uppercase",
+    fontWeight: 600,
+    fontSizePx: 12,
+  }),
+  light: Object.freeze({
+    background: "#e6e6e6",
+    text: "#000000",
+    border: "#000000",
+    textTransform: "none",
+    fontWeight: 700,
+    fontSizePx: 14,
+  }),
+});
+
+/**
+ * @typedef {{
+ *   background: string,
+ *   text: string,
+ *   border: string,
+ *   textTransform: "uppercase" | "none",
+ *   fontWeight: number,
+ *   fontSizePx: number,
+ * }} NicotineWarningPresentation
+ */
+
+export const NICOTINE_WARNING_STYLE_KEYS = Object.freeze([
+  "background", "text", "border", "textTransform", "fontWeight", "fontSizePx",
+]);
+const TEXT_TRANSFORMS = ["uppercase", "none"];
+const FONT_WEIGHTS = [600, 700, 800, 900];
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/** `#abc` / `#AABBCC` → `#aabbcc`. */
+function normalizeHex(value) {
+  const hex = value.slice(1).toLowerCase();
+  return `#${hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex}`;
+}
+
+function luminance(hex) {
+  const n = normalizeHex(hex);
+  const [r, g, b] = [1, 3, 5].map((i) => {
+    const c = parseInt(n.slice(i, i + 2), 16) / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG 2 contrast ratio between two hex colours. */
+export function contrastRatio(a, b) {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Why a presentation is not conspicuous enough — empty when it clears the floor.
+ * @param {NicotineWarningPresentation} p
+ * @returns {string[]}
+ */
+export function conspicuityProblems(p) {
+  const out = [];
+  const ratio = contrastRatio(p.text, p.background);
+  if (ratio < CONSPICUITY_FLOOR.contrast) {
+    out.push(`text ${p.text} on background ${p.background} has contrast ${ratio.toFixed(2)}:1 — the floor is ${CONSPICUITY_FLOOR.contrast}:1`);
+  }
+  if (p.fontSizePx < CONSPICUITY_FLOOR.fontSizePx) {
+    out.push(`font size ${p.fontSizePx}px is below the ${CONSPICUITY_FLOOR.fontSizePx}px floor`);
+  }
+  if (p.fontWeight < CONSPICUITY_FLOOR.fontWeight) {
+    out.push(`font weight ${p.fontWeight} is below the ${CONSPICUITY_FLOOR.fontWeight} floor`);
+  }
+  return out;
+}
+
+/** Why one declared style value is not usable, or null. */
+function styleValueProblem(key, value) {
+  switch (key) {
+    case "background":
+    case "text":
+    case "border":
+      return typeof value === "string" && HEX.test(value) ? null : `\`${key}\` must be a hex colour like "#e6e6e6"`;
+    case "textTransform":
+      return TEXT_TRANSFORMS.includes(value) ? null : `\`textTransform\` must be one of ${TEXT_TRANSFORMS.map((t) => `"${t}"`).join(", ")}`;
+    case "fontWeight":
+      return FONT_WEIGHTS.includes(value) ? null : `\`fontWeight\` must be one of ${FONT_WEIGHTS.join(", ")}`;
+    case "fontSizePx":
+      return typeof value === "number" && Number.isFinite(value) && value >= CONSPICUITY_FLOOR.fontSizePx && value <= MAX_FONT_SIZE_PX
+        ? null
+        : `\`fontSizePx\` must be a number from ${CONSPICUITY_FLOOR.fontSizePx} to ${MAX_FONT_SIZE_PX}`;
+    default:
+      return `\`${key}\` is not a nicotine-warning style key (allowed: ${NICOTINE_WARNING_STYLE_KEYS.join(", ")})`;
+  }
+}
+
+function samePresentation(a, b) {
+  return NICOTINE_WARNING_STYLE_KEYS.every((k) => a[k] === b[k]);
+}
+
+/**
+ * @typedef {{
+ *   enabled: boolean,
+ *   presentation: NicotineWarningPresentation,
+ *   preset: string | null,
+ *   custom: boolean,
+ *   problems: string[],
+ * }} ResolvedNicotineWarning
+ */
+
+/**
+ * Resolve a `compliance.nicotineWarning` declaration to what renders.
+ *
+ * `preset` names the preset the presentation equals (null for a custom one); `custom` is
+ * true when the owner must review it; `problems` lists why the declaration is invalid, in
+ * which case the default preset renders. A disabled declaration (absent, `false`) resolves
+ * `enabled: false`.
+ * @param {unknown} declaration
+ * @returns {ResolvedNicotineWarning}
+ */
+export function resolveNicotineWarning(declaration) {
+  const fallback = NICOTINE_WARNING_PRESETS[DEFAULT_NICOTINE_WARNING_PRESET];
+  const resolved = (/** @type {Partial<ResolvedNicotineWarning>} */ fields) => ({
+    enabled: true,
+    presentation: { ...fallback },
+    preset: DEFAULT_NICOTINE_WARNING_PRESET,
+    custom: false,
+    problems: [],
+    ...fields,
+  });
+  if (!declaration) return resolved({ enabled: false });
+  if (declaration === true) return resolved({});
+  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 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(", ")}`);
+  }
+  if (style !== undefined && !isObject(style)) problems.push("`style` must be an object");
+  const declaredStyle = isObject(style) ? /** @type {Record<string, unknown>} */ (style) : {};
+  for (const [key, value] of Object.entries(declaredStyle)) {
+    const problem = styleValueProblem(key, value);
+    if (problem) problems.push(problem);
+  }
+  if (problems.length > 0 || !base) return resolved({ problems });
+
+  /** @type {NicotineWarningPresentation} */
+  const presentation = { ...base };
+  for (const [key, value] of Object.entries(declaredStyle)) {
+    presentation[/** @type {keyof NicotineWarningPresentation} */ (key)] =
+      /** @type {never} */ (typeof value === "string" && HEX.test(value) ? normalizeHex(value) : value);
+  }
+  const conspicuity = conspicuityProblems(presentation);
+  if (conspicuity.length > 0) return resolved({ problems: conspicuity });
+  const matching = Object.keys(NICOTINE_WARNING_PRESETS).find((name) => samePresentation(NICOTINE_WARNING_PRESETS[name], presentation));
+  return resolved({ presentation, preset: matching ?? null, custom: !matching });
+}
+
+/**
+ * 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
+ * differently.
+ * @param {NicotineWarningPresentation} p
+ */
+export function describeNicotineWarningPresentation(p) {
+  return `background ${p.background}, text ${p.text}, border ${p.border}, ` +
+    `${p.textTransform === "uppercase" ? "uppercase" : "normal case"}, weight ${p.fontWeight}, ${p.fontSizePx}px`;
+}
+
+/**
+ * The warning's markup — the one rendering shared by NicotineWarning.astro and the raw-HTML
+ * serve path, so both present the same declaration identically. "bar" is the strip at the top
+ * of every page; "block" is the reinforced box on the product page. Every interpolated value
+ * is a validated hex colour, enum or number. Styling is inline (no utility classes), so the
+ * markup renders the same wherever it is served, whatever stylesheet the page carries.
+ * @param {unknown} declaration the tenant's `compliance.nicotineWarning`
+ * @param {"bar" | "block"} variant
+ */
+export function nicotineWarningHtml(declaration, variant) {
+  const { presentation, preset } = resolveNicotineWarning(declaration);
+  const attrs = `style="${nicotineWarningStyle(presentation, variant)}" role="note" aria-label="Health warning" ` +
+    `data-compliance="nicotine-warning" data-nicotine-warning-preset="${preset ?? "custom"}"`;
+  return variant === "bar"
+    ? `<div ${attrs}><p class="container-prose" style="margin-block:0;padding-block:0.5rem;text-align:center">${NICOTINE_WARNING_TEXT}</p></div>`
+    : `<div ${attrs}><p style="margin:0">${NICOTINE_WARNING_TEXT}</p></div>`;
+}
+
+/**
+ * Inline CSS for a presentation. `variant` "block" (the product page) never renders smaller
+ * than 14px.
+ * @param {NicotineWarningPresentation} p
+ * @param {"bar" | "block"} variant
+ */
+export function nicotineWarningStyle(p, variant) {
+  const size = variant === "block" ? Math.max(p.fontSizePx, 14) : p.fontSizePx;
+  const frame = variant === "bar"
+    ? [`border-bottom:2px solid ${p.border}`]
+    : [`border:2px solid ${p.border}`, "border-radius:var(--radius-md)", "padding:0.75rem 1rem"];
+  return [
+    ...frame,
+    `background-color:${p.background}`,
+    `color:${p.text}`,
+    `text-transform:${p.textTransform}`,
+    `letter-spacing:${p.textTransform === "uppercase" ? "0.06em" : "normal"}`,
+    `font-weight:${p.fontWeight}`,
+    `font-size:${size}px`,
+    "line-height:1.4",
+  ].join(";");
+}

package/src/mcp.mjs

@@ -205,8 +205,15 @@ export function createMcpClient(baseUrl, opts = {}) {
     try {
       text = await res.text();
     } catch (cause) {
-      throw diagnosticError(`${method} failed: response body was unreadable`, {
-        operation: method, category: "malformed_response", httpStatus: res.status,
+      // The request timeout covers the body read (MCP streams over SSE, so the
+      // headers arrive first): our own timeout firing mid-body is a timeout, and a
+      // stream that ends early is a network failure — neither is a malformed body.
+      const category = signal.aborted ? "timeout" : "network";
+      const message = signal.aborted
+        ? `${method} timed out after ${timeoutMs}ms while reading the response`
+        : `${method} failed: the response stream ended early: ${sanitizeDiagnosticText(cause?.message || cause, MAX_SERVER_MESSAGE)}`;
+      throw diagnosticError(message, {
+        operation: method, category, message, httpStatus: res.status,
         statusText: res.statusText, traceId: responseTraceId, requestId: headerRequestId,
         contentType: ct,
       }, cause);

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;
@@ -352,6 +353,31 @@ function validateScriptsDoc(doc, file, config) {
   return out;
 }
 
+// Standalone published-CLI mirror of extension-contract-values.mjs
+// (THEME_HEADING_LEVELS / isThemeCssSize); packages/cli/test/validate.test.mjs pins it.
+export const THEME_HEADING_LEVELS = Object.freeze(["hero", "h1", "h2", "h3"]);
+export function isThemeCssSize(value) {
+  return typeof value === "string" && value.length <= 120 && /^[0-9a-z.%(),+\-*/ ]*[0-9a-z%)]$/i.test(value.trim());
+}
+
+/** theme.json `type.headings`: fixed heading sizes the renderer emits as --heading-<level>. */
+function validateThemeHeadings(theme, file) {
+  const out = [];
+  const headings = theme?.type?.headings;
+  if (headings === undefined) return out;
+  if (headings == null || typeof headings !== "object" || Array.isArray(headings)) {
+    return [mk(ERROR, "theme-token", file, "type.headings must be an object of hero/h1/h2/h3 sizes")];
+  }
+  for (const [level, size] of Object.entries(headings)) {
+    if (!THEME_HEADING_LEVELS.includes(level)) {
+      out.push(mk(ERROR, "theme-token", file, `type.headings.${level} is not a heading level (use ${THEME_HEADING_LEVELS.join(", ")})`));
+    } else if (!isThemeCssSize(size)) {
+      out.push(mk(ERROR, "theme-token", file, `type.headings.${level} must be a CSS length such as "28px", "1.75rem" or "clamp(1.5rem, 4vw, 2rem)"`));
+    }
+  }
+  return out;
+}
+
 // Standalone published-CLI mirror. packages/cli/test/validate.test.mjs pins it
 // to extension-contract-values.mjs, the repository/runtime authority.
 export const BLOCK_PALETTE_SUPPORTED_CONTRACTS = Object.freeze([
@@ -361,6 +387,7 @@ export const BLOCK_PALETTE_SUPPORTED_CONTRACTS = Object.freeze([
   "block-palette@4",
   "block-palette@5",
   "block-palette@6",
+  "block-palette@7",
 ]);
 export const FEATURED_PRODUCT_PRESENTATIONS = Object.freeze(["grid", "carousel"]);
 const SUPPORTED_BLOCK_CONTRACTS = new Set(BLOCK_PALETTE_SUPPORTED_CONTRACTS);
@@ -645,6 +672,9 @@ function validateHomeDoc(doc, file, tenantId) {
       validateVisualAsset(block.image, file, `${at}.image`, out, tenantId);
     }
     if (component === "hero" && block.slides !== undefined) validateHeroSlides(block.slides, file, at, out, tenantId);
+    if (component === "hero" && block.notice !== undefined && (typeof block.notice !== "string" || !block.notice.trim())) {
+      out.push(mk(ERROR, "block-prop", file, `${at}.notice must be a non-empty plain-text string`));
+    }
     if (component === "editorial" && block.image !== undefined) {
       validateVisualAsset(block.image, file, `${at}.image`, out, tenantId);
       if (typeof block.imageAlt !== "string") {
@@ -723,6 +753,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?",
@@ -1128,12 +1173,14 @@ export function validateTenant(tenantDir, opts = {}) {
   // 2. theme.json — parse (a malformed one is a WHOLE-APP BUILD FAILURE)
   const themePath = located("theme.json");
   if (existsSync(themePath)) {
-    const { error } = readJsonSafe(themePath);
+    const { value: theme, error } = readJsonSafe(themePath);
     if (error) {
       findings.push(
         mk(ERROR, "theme-parse", rel(themePath),
           `invalid JSON: ${error}`, "theme.json is loaded by an eager Vite glob — a parse error fails the entire storefront build"),
       );
+    } else {
+      findings.push(...validateThemeHeadings(theme, rel(themePath)));
     }
   }