@tokenoftrust/cli 4.7.0 → 4.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "4.7.0",
+  "version": "4.7.2",
   "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/page-slugs.mjs

@@ -0,0 +1,113 @@
+// @ts-check
+/**
+ * Which editorial page slugs the hosted storefront router can serve.
+ *
+ * A page under `content/pages/<file>.json` is served at `/<slug>/`, where `<slug>` is the page's
+ * own JSON `slug` (never the file name), and a raw page `content/pages-html/<path>.html` is served
+ * at `/<path>/`. Both reach the platform's catch-all route, which every first-class platform route
+ * outranks. So a slug is servable only when:
+ *
+ *   - it is a string of one or more `/`-separated segments, each starting with a letter or digit
+ *     and holding only letters, digits, `-` and `_` (no leading/trailing or doubled slash, no `.`:
+ *     both CDNs treat a dotted last segment as a file, never a page);
+ *   - its first segment is not a route root the platform owns (`products`, `collections`, `blog`,
+ *     `api`, …) — the platform route answers first and the page is never reached;
+ *   - no other page, JSON or raw, claims the same slug — the router serves one of them.
+ *
+ * Pure: callers pass what they read, so the kit validator and `tot validate` apply one rule.
+ * `packages/cli/src/page-slugs.mjs` is a byte-identical copy (a test pins it).
+ */
+
+/**
+ * First path segments the platform's own routes answer before the editorial catch-all.
+ * Pinned against the storefront's route tree by scripts/lib/page-slug-reserved.test.mjs.
+ */
+export const RESERVED_PAGE_ROOTS = Object.freeze([
+  "_sitemap",
+  "account",
+  "admin",
+  "api",
+  "auth",
+  "blog",
+  "capabilities",
+  "cart",
+  "cockpit",
+  "collections",
+  "dashboard",
+  "diag",
+  "preview",
+  "products",
+  "saved",
+  "search",
+  "shared",
+  "style-guide",
+  "tenants",
+  "the-build",
+]);
+
+const SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+/**
+ * Why `slug` cannot be served by the hosted router, or null when it can.
+ * @param {unknown} slug
+ * @returns {string | null}
+ */
+export function unservableSlugReason(slug) {
+  if (typeof slug !== "string" || slug.length === 0) return "has no string `slug`";
+  const segments = slug.split("/");
+  if (segments.some((segment) => !SEGMENT_RE.test(segment))) {
+    return `slug "${slug}" is not a page path: each "/"-separated segment must start with a letter or digit and hold only letters, digits, "-" and "_" (no leading, trailing or doubled "/", no ".")`;
+  }
+  const root = /** @type {string} */ (segments[0]);
+  if (RESERVED_PAGE_ROOTS.includes(root)) {
+    return `slug "${slug}" starts with "${root}/", a route the platform serves itself — the page is never reached`;
+  }
+  return null;
+}
+
+/**
+ * @typedef {Object} PageSlugFinding
+ * @property {string} code     `page-slug-unservable` | `page-slug-duplicate`
+ * @property {string} path     the declaring file, store-relative
+ * @property {string} message
+ * @property {string} remedy
+ */
+
+/**
+ * Every slug the hosted router cannot serve, across a store's JSON and raw pages.
+ * @param {{ pages?: ReadonlyArray<{ path: string, slug: unknown }>, rawPages?: ReadonlyArray<{ path: string, slug: string }> }} input
+ *   `pages`: each `content/pages/*.json` with its parsed `slug`; `rawPages`: each
+ *   `content/pages-html/**.html` with the slug its path encodes.
+ * @returns {PageSlugFinding[]}
+ */
+export function pageSlugFindings({ pages = [], rawPages = [] }) {
+  /** @type {PageSlugFinding[]} */
+  const findings = [];
+  /** @type {Map<string, string>} */
+  const claimed = new Map();
+  for (const { path, slug } of [...pages, ...rawPages]) {
+    const reason = unservableSlugReason(slug);
+    if (reason) {
+      findings.push({
+        code: "page-slug-unservable",
+        path,
+        message: `${reason}, so the hosted store answers 404 for it`,
+        remedy: "give the page a slug of plain path segments outside the platform's routes, and add a content/redirects.json entry from any old URL",
+      });
+      continue;
+    }
+    const key = /** @type {string} */ (slug);
+    const first = claimed.get(key);
+    if (first !== undefined) {
+      findings.push({
+        code: "page-slug-duplicate",
+        path,
+        message: `slug "${slug}" is also claimed by ${first} — the hosted store serves only one of them`,
+        remedy: "give each page its own slug",
+      });
+      continue;
+    }
+    claimed.set(key, path);
+  }
+  return findings;
+}

package/src/validate.mjs

@@ -24,6 +24,7 @@ import {
   workspacePathForTenantRelative,
 } from "./tot-repo-mappings.mjs";
 import { isForbiddenPublicPath, publicBinaryFindings } from "./public-binaries.mjs";
+import { pageSlugFindings } from "./page-slugs.mjs";
 import { parseSku, skuCollisions, skuFindings } from "./sku.mjs";
 
 export {
@@ -1349,6 +1350,9 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  // 3b. editorial page slugs — every page must be reachable at its slug on the hosted router.
+  findings.push(...editorialSlugFindings(contentDir, pagesDir, rel));
+
   // 4. raw HTML documents — validate + portability + resolution
   const hasChrome = providesChrome(contentDir);
   const htmlFiles = walk(contentDir, (p) => p.endsWith(".html"));
@@ -1479,6 +1483,23 @@ export function validateTenant(tenantDir, opts = {}) {
   return { ok, findings };
 }
 
+/**
+ * `page-slug-*` findings for a store's `content/pages/*.json` and `content/pages-html/**.html`
+ * (see ./page-slugs.mjs). An unparseable page has no slug, so it is unservable.
+ * @param {string} contentDir @param {string} pagesDir @param {(p: string) => string} rel
+ * @returns {Finding[]}
+ */
+function editorialSlugFindings(contentDir, pagesDir, rel) {
+  const pages = walk(join(contentDir, "pages"), (x) => x.endsWith(".json")).sort().map((p) => {
+    const { value, error } = readJsonSafe(p);
+    return { path: rel(p), slug: error ? undefined : value?.slug };
+  });
+  const rawPages = walk(pagesDir, (x) => x.endsWith(".html")).sort()
+    .map((p) => ({ path: rel(p), slug: relative(pagesDir, p).split("\\").join("/").replace(/\.html$/, "") }));
+  return pageSlugFindings({ pages, rawPages })
+    .map((f) => mk(ERROR, f.code, f.path, f.message, f.remedy));
+}
+
 function buildPageTargetSet(contentDir, pagesDir) {
   const set = new Set(["/", ""]);
   if (existsSync(join(contentDir, "home.html"))) set.add("/");

package/src/visual-parity.mjs

@@ -255,8 +255,9 @@ function pageShape(value, file) {
       case "definitions": if (!Array.isArray(section.items) || !section.items.length || section.items.some((item) => !item || !string(item.term) || !rich(item.description))) findings.push(finding("parity-section-shape", at, "definitions require string terms and RichText descriptions", "supply valid definition items")); break;
       case "callout": if (!rich(section.body) || !["info", "warning", "legal", "success"].includes(section.tone) || section.title !== undefined && !string(section.title)) findings.push(finding("parity-section-shape", at, "callout requires supported tone, RichText body, and optional string title", "supply a valid callout")); break;
       case "contact": if (section.heading !== undefined && !string(section.heading) || section.email !== undefined && !string(section.email) || section.phone !== undefined && !string(section.phone) || section.address !== undefined && (!Array.isArray(section.address) || section.address.some((line) => !string(line))) || !string(section.email) && !string(section.phone) && !(Array.isArray(section.address) && section.address.length)) findings.push(finding("parity-section-shape", at, "contact requires string members and email, phone, or address", "supply valid contact details")); break;
+      case "contact_form": if (["heading", "messageLabel", "submitLabel", "successMessage"].some((key) => section[key] !== undefined && !string(section[key])) || section.fields !== undefined && (!Array.isArray(section.fields) || section.fields.some((field) => field !== "name" && field !== "phone"))) findings.push(finding("parity-section-shape", at, "contact_form requires optional string copy and fields limited to name or phone", "supply a valid contact_form section")); break;
       case "needs_review": if (!string(section.reason) || section.severity !== undefined && !["blocker", "note"].includes(section.severity) || section.owner !== undefined && !string(section.owner) || section.href !== undefined && !string(section.href)) findings.push(finding("parity-section-shape", at, "needs_review requires reason and valid optional severity/owner/href", "supply a valid needs_review section")); break;
-      default: findings.push(finding("parity-section-kind", `${at}/kind`, "section kind is not supported by the renderer", "use heading, paragraph, list, definitions, callout, contact, or needs_review"));
+      default: findings.push(finding("parity-section-kind", `${at}/kind`, "section kind is not supported by the renderer", "use heading, paragraph, list, definitions, callout, contact, contact_form, or needs_review"));
     }
   });
   const bodyHtml = typeof value.body_html === "string" && value.body_html.trim() !== "";

package/template/sample-store/content/chrome.html

@@ -28,7 +28,7 @@
     <ul>
       <li><a href="/blogs/news">News</a></li>
       <li><a href="/pages/about-us">About</a></li>
-      <li><a href="/pages/contact-us">Contact</a></li>
+      <li><a href="/contact-us">Contact</a></li>
     </ul>
     <div class="utility-nav__right">
       <span class="sel">English</span>
@@ -98,7 +98,7 @@
         <ul>
           <li><a href="/search">Search</a></li>
           <li><a href="/pages/about-us">About Us</a></li>
-          <li><a href="/pages/contact-us">Contact Us</a></li>
+          <li><a href="/contact-us">Contact Us</a></li>
           <li><a href="/blogs/news">Blog</a></li>
         </ul>
       </div>

package/template/sample-store/content/pages/contact-us.json

@@ -0,0 +1,22 @@
+{
+  "slug": "contact-us",
+  "title": "Contact Sample Vapor Co.",
+  "seoTitle": "Contact | Sample Vapor Co.",
+  "seoDescription": "Sample contact page for the fictional Sample Vapor Co. demo store.",
+  "eyebrow": "Sample content",
+  "intro": "This is a placeholder contact page for a fictional demo store.",
+  "isPolicy": false,
+  "sections": [
+    { "kind": "heading", "text": "Support hours" },
+    { "kind": "paragraph", "text": "Sample copy: set your real support hours here." },
+    { "kind": "heading", "text": "Customer support" },
+    { "kind": "paragraph", "text": "Sample copy: describe how customers reach you." },
+    {
+      "kind": "contact_form",
+      "heading": "Send us a message",
+      "fields": ["name", "phone"],
+      "messageLabel": "How can we help?",
+      "submitLabel": "Send message"
+    }
+  ]
+}

package/template/sample-store/content/pages-html/pages/contact-us.html

@@ -1,48 +0,0 @@
-<head>
-<title>Contact | Sample Vapor Co.</title>
-<meta name="description" content="Sample contact page for the fictional Sample Vapor Co. demo store.">
-<link rel="canonical" href="https://sample-store.example/pages/contact-us">
-<meta name="robots" content="noindex,nofollow">
-<link rel="stylesheet" href="/tenants/sample-store.example/pages/page.css">
-</head>
-<main id="main">
-
-  <section class="page-hero page-hero--center section--tight">
-    <div class="container">
-      <nav class="crumbs" aria-label="Breadcrumb"><a href="/">Home</a> / Contact Us</nav>
-      <h1>Contact Sample Vapor Co.</h1>
-      <p>This is a placeholder contact page for a fictional demo store. Nothing here submits anywhere.</p>
-    </div>
-  </section>
-
-  <section class="section" aria-labelledby="contact-h">
-    <h2 id="contact-h" class="sr-only">Get in touch</h2>
-    <div class="container">
-      <div class="contact-grid">
-        <div class="contact-card">
-          <h3>Support hours</h3>
-          <p>Sample copy — set your real support hours here.</p>
-        </div>
-        <div class="contact-card">
-          <h3>Customer support</h3>
-          <p>Sample copy — describe how customers reach you.</p>
-        </div>
-        <div class="contact-card">
-          <h3>Track your order</h3>
-          <p>Sample copy — link your order-tracking flow here.</p>
-        </div>
-      </div>
-
-      <form class="contact-form" action="/api/contact" method="post">
-        <div class="row2">
-          <input type="text" name="name" aria-label="Name" placeholder="Name" required>
-          <input type="email" name="email" aria-label="Email" placeholder="Email" required>
-        </div>
-        <input type="text" name="order" aria-label="Order number (optional)" placeholder="Order number (optional)">
-        <textarea name="comment" aria-label="How can we help?" placeholder="How can we help?"></textarea>
-        <button type="submit" class="btn btn-primary">Send Message</button>
-      </form>
-    </div>
-  </section>
-
-</main>