@tokenoftrust/cli 2.4.12 → 2.4.13

package/package.json

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

@@ -11,6 +11,13 @@ export const TOT_CONFIG_KEYS: string[];
 export const COMPLIANCE_KEYS: string[];
 export const FEATURE_KEYS: string[];
 export const SITE_TYPES: string[];
+export const SEO_KEYS: readonly string[];
+export const STRUCTURED_DATA_KEYS: readonly string[];
+export const STRUCTURED_DATA_PAGE_TYPES: readonly string[];
+export const STRUCTURED_DATA_NODE_TOKENS: readonly string[];
+export const STRUCTURED_DATA_NAMED_TYPES: readonly string[];
+export const STRUCTURED_DATA_NAME_SOURCES: readonly string[];
+export function seoDeclarationProblems(seo: unknown): string[];
 export const COMPLIANCE_NOTICES: Record<string, string>;
 export const MANDATED_NOTICE_KEYS: string[];
 export function nearestKey(key: string, known: readonly string[]): string | null;

package/src/declared-config.mjs

@@ -17,7 +17,7 @@
 
 export const TOT_CONFIG_KEYS = [
   "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "displayName", "siteType", "compliance", "capabilities", "features", "embeds",
+  "displayName", "siteType", "compliance", "capabilities", "features", "embeds", "seo",
 ];
 // Keys other tooling has written that the platform does NOT read, with the key it does.
 const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
@@ -30,6 +30,115 @@ export const FEATURE_KEYS = [
 ];
 export const SITE_TYPES = ["commerce", "marketing"];
 
+/** Every `seo` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
+export const SEO_KEYS = Object.freeze(["trailingSlash", "structuredData"]);
+
+/** Every `seo.structuredData` key. */
+export const STRUCTURED_DATA_KEYS = Object.freeze(["graphs", "names", "reviews"]);
+
+/**
+ * The page types a structured-data profile declares a graph for. `productGroup` is a product
+ * with more than one variant; without its own graph it renders the `product` graph.
+ * `collection` covers every archive: a catalog collection, the collections index, and the
+ * blog index and its category/tag/author archives.
+ */
+export const STRUCTURED_DATA_PAGE_TYPES = Object.freeze([
+  "home", "product", "productGroup", "collection", "post", "page",
+]);
+
+/**
+ * The JSON-LD nodes a profile may list, as the `@type` each emits (a multi-type node joins its
+ * sorted types with `+`, the key a parity snapshot records). `Person:author` is the page's
+ * author; every other Organization/Person token is the site entity.
+ */
+export const STRUCTURED_DATA_NODE_TOKENS = Object.freeze([
+  "Organization", "Person", "Organization+Person",
+  "WebSite", "ImageObject",
+  "WebPage", "ItemPage", "CollectionPage", "AboutPage", "ContactPage",
+  "Person:author",
+  "Article", "BlogPosting",
+  "Product", "ProductGroup",
+  "FAQPage", "BreadcrumbList", "ItemList",
+]);
+
+/** Node types whose `name` a profile may source, and the sources. */
+export const STRUCTURED_DATA_NAMED_TYPES = Object.freeze(["Product", "ProductGroup", "Article", "BlogPosting"]);
+export const STRUCTURED_DATA_NAME_SOURCES = Object.freeze(["documentTitle", "title"]);
+
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * What is wrong with a declared `seo` value, one sentence per problem; `[]` when it is valid.
+ * A profile that names a node or page type the renderer does not build is refused whole: a
+ * partly-applied profile emits a graph nobody declared.
+ *
+ * @param {unknown} seo
+ * @returns {string[]}
+ */
+export function seoDeclarationProblems(seo) {
+  if (!isPlainObject(seo)) return ["`seo` must be an object"];
+  const problems = [];
+  const source = /** @type {Record<string, unknown>} */ (seo);
+  for (const key of Object.keys(source)) {
+    if (!SEO_KEYS.includes(key)) problems.push(`\`seo.${key}\` is not a seo key (${SEO_KEYS.join(", ")})`);
+  }
+  if (source.trailingSlash !== undefined && typeof source.trailingSlash !== "boolean") {
+    problems.push("`seo.trailingSlash` must be true or false");
+  }
+  const sd = source.structuredData;
+  if (sd === undefined) return problems;
+  if (!isPlainObject(sd)) return [...problems, "`seo.structuredData` must be an object"];
+  const data = /** @type {Record<string, unknown>} */ (sd);
+  for (const key of Object.keys(data)) {
+    if (!STRUCTURED_DATA_KEYS.includes(key)) {
+      problems.push(`\`seo.structuredData.${key}\` is not a structuredData key (${STRUCTURED_DATA_KEYS.join(", ")})`);
+    }
+  }
+  if (!isPlainObject(data.graphs) || Object.keys(/** @type {object} */ (data.graphs)).length === 0) {
+    problems.push("`seo.structuredData.graphs` must map at least one page type to its node list");
+  } else {
+    for (const [pageType, tokens] of Object.entries(/** @type {Record<string, unknown>} */ (data.graphs))) {
+      const at = `seo.structuredData.graphs.${pageType}`;
+      if (!STRUCTURED_DATA_PAGE_TYPES.includes(pageType)) {
+        problems.push(`\`${at}\`: unknown page type (${STRUCTURED_DATA_PAGE_TYPES.join(", ")})`);
+        continue;
+      }
+      if (!Array.isArray(tokens) || tokens.length === 0) {
+        problems.push(`\`${at}\` must be a non-empty array of node types`);
+        continue;
+      }
+      const seen = new Set();
+      for (const token of tokens) {
+        if (typeof token !== "string" || !STRUCTURED_DATA_NODE_TOKENS.includes(token)) {
+          problems.push(`\`${at}\`: ${JSON.stringify(token)} is not a node type the renderer builds (${STRUCTURED_DATA_NODE_TOKENS.join(", ")})`);
+        } else if (seen.has(token)) {
+          problems.push(`\`${at}\` lists ${token} twice`);
+        }
+        seen.add(token);
+      }
+    }
+  }
+  if (data.names !== undefined) {
+    if (!isPlainObject(data.names)) {
+      problems.push("`seo.structuredData.names` must map a node type to documentTitle or title");
+    } else {
+      for (const [type, from] of Object.entries(/** @type {Record<string, unknown>} */ (data.names))) {
+        if (!STRUCTURED_DATA_NAMED_TYPES.includes(type)) {
+          problems.push(`\`seo.structuredData.names.${type}\`: only ${STRUCTURED_DATA_NAMED_TYPES.join(", ")} take a declared name`);
+        } else if (typeof from !== "string" || !STRUCTURED_DATA_NAME_SOURCES.includes(from)) {
+          problems.push(`\`seo.structuredData.names.${type}\` must be one of ${STRUCTURED_DATA_NAME_SOURCES.join(", ")}`);
+        }
+      }
+    }
+  }
+  if (data.reviews !== undefined && typeof data.reviews !== "boolean") {
+    problems.push("`seo.structuredData.reviews` must be true or false");
+  }
+  return problems;
+}
+
+
 /** What each compliance key puts on the page — the thing that is missing when it is. */
 export const COMPLIANCE_NOTICES = {
   ruleProfile: "checkout compliance rules",
@@ -361,6 +470,11 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     && !(Array.isArray(config.embeds) && config.embeds.every((/** @type {unknown} */ s) => typeof s === "string"))) {
     out.push(mk(ERROR, "config-embeds", file, '`embeds` must be an array of embed slugs, e.g. ["youtube"]'));
   }
+  if (config.seo !== undefined) {
+    for (const problem of seoDeclarationProblems(config.seo)) {
+      out.push(mk(ERROR, "config-seo", `${file} seo`, `${problem} — the whole \`seo\` declaration is ignored until it is fixed`));
+    }
+  }
   return out;
 }