@tokenoftrust/cli 4.7.3 → 4.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "4.7.3",
+  "version": "4.7.4",
   "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/publication-spaces.mjs

@@ -17,6 +17,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { parseSitemapChildPathV1 } from "./sitemap-index.mjs";
 
 /** Where `tot clone` puts each mounted space, relative to the root checkout: `spaces/<spaceId>/`. */
 export const SPACES_DIR = "spaces";
@@ -26,7 +27,9 @@ export const TOPOLOGY_VERSION = 1;
 
 /**
  * Platform-owned paths no space serves (packages/public-runtime PUBLICATION_SPACE_RESERVED_MOUNTS;
- * the ownership parity test holds the two equal).
+ * the ownership parity test holds the two equal). Child sitemaps (`/sitemap-<group>-<page>.xml`) are
+ * platform-owned too, recognized by `parseSitemapChildPathV1` (a byte-identical copy of
+ * packages/public-runtime/src/sitemap-index.mjs, pinned by test/sitemap-index-copy.test.mjs).
  */
 export const PLATFORM_PATHS = Object.freeze([
   "/.well-known", "/__evidence", "/__preview", "/_a", "/_astro", "/_style-guide", "/admin", "/api",
@@ -167,7 +170,9 @@ export function owningSpace(topology, urlPath) {
   const path = normalizeRequestPath(urlPath);
   if (path === null) return null;
   const folded = path.toLowerCase();
-  if (PLATFORM_PATHS.some((reserved) => mountMatchesPath(reserved, folded))) return { space: null, via: "platform" };
+  if (PLATFORM_PATHS.some((reserved) => mountMatchesPath(reserved, folded)) || parseSitemapChildPathV1(folded) !== null) {
+    return { space: null, via: "platform" };
+  }
   /** @type {{ space: TopologySpace, via: "mount"|"alias", mount: string } | null} */
   let best = null;
   for (const space of topology.spaces) {

package/src/sitemap-index.mjs

@@ -0,0 +1,157 @@
+// @ts-check
+/**
+ * The tenant sitemap contract, shared by the Worker that renders it and the publish tooling
+ * that materializes and validates it on both serving substrates.
+ *
+ * `/sitemap.xml` is a `<sitemapindex>`. Its entries are typed, paged child sitemaps at
+ * `/sitemap-<group>-<page>.xml`, each a `<urlset>` of at most {@link SITEMAP_MAX_URLS_PER_CHILD_V1}
+ * URLs. A child path ends in `.xml`, so S3/CloudFront and the Cloudflare static bundle both serve
+ * it as a plain file with no rewrite, and the materializer writes it at the same bundle path.
+ *
+ * Pure: no I/O, no platform imports.
+ */
+
+/** @typedef {{loc: string, lastmod?: string}} SitemapUrl */
+
+/** The one discovery entry point robots.txt advertises. */
+export const SITEMAP_INDEX_PATH_V1 = "/sitemap.xml";
+
+/**
+ * URLs per child sitemap. The protocol allows 50,000; 5,000 keeps each child a small, fast,
+ * individually cacheable document and matches the paging large commerce platforms use.
+ */
+export const SITEMAP_MAX_URLS_PER_CHILD_V1 = 5000;
+
+/** Child sitemap groups, in the order the index lists them. */
+export const SITEMAP_GROUPS_V1 = Object.freeze(["pages", "collections", "products", "blogs", "build", "spaces"]);
+
+const CHILD_PATH = /^\/sitemap-([a-z]+)-([1-9][0-9]{0,5})\.xml$/;
+
+/**
+ * `/sitemap-<group>-<page>.xml` for a declared group and a 1-based page.
+ * @param {string} group @param {number} page @returns {string}
+ */
+export function sitemapChildPathV1(group, page) {
+  if (!SITEMAP_GROUPS_V1.includes(group)) throw new Error(`unknown sitemap group ${JSON.stringify(group)}`);
+  if (!Number.isInteger(page) || page < 1) throw new Error(`sitemap page must be a positive integer, got ${page}`);
+  return `/sitemap-${group}-${page}.xml`;
+}
+
+/**
+ * The group and page a child sitemap path names, or null when it names none.
+ * @param {unknown} path @returns {{group: string, page: number} | null}
+ */
+export function parseSitemapChildPathV1(path) {
+  if (typeof path !== "string") return null;
+  const match = CHILD_PATH.exec(path);
+  const group = match?.[1];
+  if (!match || group === undefined || !SITEMAP_GROUPS_V1.includes(group)) return null;
+  return { group, page: Number(match[2]) };
+}
+
+/** True for `/sitemap.xml` and for every well-formed child sitemap path. @param {string} path */
+export function isSitemapDocumentPathV1(path) {
+  return path === SITEMAP_INDEX_PATH_V1 || parseSitemapChildPathV1(path) !== null;
+}
+
+/**
+ * Page each group into children of at most {@link SITEMAP_MAX_URLS_PER_CHILD_V1} URLs, in
+ * {@link SITEMAP_GROUPS_V1} order. An empty group yields no child.
+ * @param {ReadonlyArray<{group: string, urls: readonly SitemapUrl[]}>} groups
+ * @param {number} [maxPerChild]
+ * @returns {{group: string, page: number, path: string, urls: SitemapUrl[]}[]}
+ */
+export function chunkSitemapGroupsV1(groups, maxPerChild = SITEMAP_MAX_URLS_PER_CHILD_V1) {
+  /** @type {Map<string, SitemapUrl[]>} */
+  const byGroup = new Map();
+  for (const { group, urls } of groups) {
+    if (!SITEMAP_GROUPS_V1.includes(group)) throw new Error(`unknown sitemap group ${JSON.stringify(group)}`);
+    byGroup.set(group, [...(byGroup.get(group) ?? []), ...urls]);
+  }
+  /** @type {{group: string, page: number, path: string, urls: SitemapUrl[]}[]} */
+  const children = [];
+  for (const group of SITEMAP_GROUPS_V1) {
+    const urls = byGroup.get(group) ?? [];
+    for (let start = 0, page = 1; start < urls.length; start += maxPerChild, page += 1) {
+      children.push({ group, page, path: sitemapChildPathV1(group, page), urls: urls.slice(start, start + maxPerChild) });
+    }
+  }
+  return children;
+}
+
+/** @param {string} value */
+function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * The newest `lastmod` among `urls`, spelled as its source spelled it; undefined when none parses.
+ * @param {readonly SitemapUrl[]} urls @returns {string | undefined}
+ */
+export function newestLastmodV1(urls) {
+  /** @type {string | undefined} */
+  let newest;
+  let newestTime = -Infinity;
+  for (const { lastmod } of urls) {
+    const time = lastmod ? Date.parse(lastmod) : NaN;
+    if (Number.isFinite(time) && time > newestTime) {
+      newest = lastmod;
+      newestTime = time;
+    }
+  }
+  return newest;
+}
+
+/** A `<urlset>` document. Locs are written exactly as given. @param {readonly SitemapUrl[]} urls */
+export function renderSitemapUrlsetV1(urls) {
+  const rows = urls.map((u) =>
+    `  <url>\n    <loc>${escapeXml(u.loc)}</loc>${u.lastmod ? `\n    <lastmod>${escapeXml(u.lastmod)}</lastmod>` : ""}\n  </url>`);
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${rows.join("\n")}\n</urlset>\n`;
+}
+
+/**
+ * A `<sitemapindex>` naming each child at `base` + its path. `base` is the tenant's canonical
+ * base without a trailing slash, path prefix included, so every loc keeps the prefix the page
+ * locs carry. Each entry's lastmod is the newest lastmod inside that child, when it has one.
+ * @param {string} base @param {readonly {path: string, urls: readonly SitemapUrl[]}[]} children
+ */
+export function renderSitemapIndexV1(base, children) {
+  const root = base.replace(/\/+$/, "");
+  const rows = children.map((child) => {
+    const lastmod = newestLastmodV1(child.urls);
+    return `  <sitemap>\n    <loc>${escapeXml(`${root}${child.path}`)}</loc>${lastmod ? `\n    <lastmod>${escapeXml(lastmod)}</lastmod>` : ""}\n  </sitemap>`;
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${rows.join("\n")}\n</sitemapindex>\n`;
+}
+
+/** True when `xml` is a `<sitemapindex>` rather than a `<urlset>`. @param {string} xml */
+export function isSitemapIndexXmlV1(xml) {
+  return /<sitemapindex[\s>]/.test(xml);
+}
+
+/**
+ * The child sitemap locs a `<sitemapindex>` names, exactly as spelled; empty for a `<urlset>`.
+ * @param {string} xml @returns {string[]}
+ */
+export function sitemapIndexLocsV1(xml) {
+  if (!isSitemapIndexXmlV1(xml)) return [];
+  return [...xml.matchAll(/<sitemap>\s*<loc>([^<]*)<\/loc>/g)].map((match) => (match[1] ?? "").trim());
+}
+
+/**
+ * Page URLs a sitemap lists, following an index to its children. `readChild` returns a child's
+ * body, or null when it cannot be read (which contributes nothing).
+ * @param {string} xml @param {(loc: string) => Promise<string | null>} readChild @returns {Promise<number>}
+ */
+export async function countSitemapUrlsV1(xml, readChild) {
+  /** @param {string} body */
+  const urls = (body) => (body.match(/<url>/g) ?? []).length;
+  if (!isSitemapIndexXmlV1(xml)) return urls(xml);
+  const bodies = await Promise.all(sitemapIndexLocsV1(xml).map(readChild));
+  return bodies.reduce((count, body) => count + urls(body ?? ""), 0);
+}