@tokenoftrust/cli 4.7.0 → 4.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "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("/");