orionplace-react 0.5.0 → 0.6.1

package/runtime/marketplace.mjs

@@ -1,5 +1,5 @@
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { chown, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
 import {
   getDefaultAutoSelectFamilyAttemptTimeout,
   isIP,
@@ -81,8 +81,20 @@ export async function readMarketplace(request, configuration = {}) {
   if (!domain) {
     throw new Error('Invalid storefront domain');
   }
+  return readMarketplaceDomain(domain);
+}
 
-  const directory = environment.SITEMAPS_DIR || resolve('sitemaps');
+/**
+ * The marketplace of one storefront domain: its `sitemaps/<domain>.cfg` in
+ * the project (`root`, the working directory by default).
+ * @param {string} name @param {{root?: string}} options
+ */
+export async function readMarketplaceDomain(name, options = {}) {
+  const domain    = normalizeFrontDomain(name);
+  if (!domain) {
+    throw new Error('Invalid storefront domain');
+  }
+  const directory = marketplaceConfigDirectory(options.root);
   const source    = await readFile(resolve(directory, `${domain}.cfg`), 'utf8');
   const lines     = source
     .split(/\r?\n/)
@@ -111,6 +123,13 @@ export async function readMarketplace(request, configuration = {}) {
   return { domain, api };
 }
 
+/** The folder of the domain files (`SITEMAPS_DIR`, or `sitemaps`). */
+export function marketplaceConfigDirectory(root = process.cwd()) {
+  return environment.SITEMAPS_DIR
+    ? resolve(root, environment.SITEMAPS_DIR)
+    : resolve(root, 'sitemaps');
+}
+
 /** @param {number} status @param {string} message */
 function failure(status, message) {
   return Response.json(
@@ -297,3 +316,500 @@ export async function forwardMarketplace(request, configuration = {}) {
     headers: responseHeaders,
   });
 }
+
+// ---------------------------------------------------------------------------
+// robots.txt and sitemap.xml
+//
+// The sitemap lists the storefront's public pages in every language the
+// marketplace offers (`?locale=<code>` links, with hreflang alternates): the
+// home, catalog and directory pages, the journal and its publications when
+// the blog is on, the subscription plans when there are any, every public
+// category and every product on sale. It is built from the backend's public
+// API and kept for an hour per storefront domain in
+// node_modules/.cache/orionplace/sitemaps/<domain>.json (ORIONPLACE_CACHE_DIR
+// moves it). "orionplace-<framework> sitemap rebuild" rebuilds that file at
+// once; the running storefront serves the new file without a restart.
+// Paths in ORIONPLACE_NOINDEX_PATHS are left out when the sitemap is served.
+
+export const SITEMAP_LIFETIME = 60 * 60 * 1000;
+const sitemapPageSize = 100;
+const sitemapMaxPages = 500;
+const sitemapMaxUrls  = 50_000;
+const sitemapVersion  = 1;
+/** Built sitemaps of this process, for when the cache folder is read-only. */
+const sitemapMemory   = new Map();
+/** @type {Map<string, Promise<object>>} */
+const sitemapBuilds   = new Map();
+
+/** The public origin a crawler used: the storefront host, or a local one. */
+export function marketplacePublicOrigin(request, tenantDomain = '') {
+  const url  = new URL(request.url);
+  const host = normalizeFrontDomain(
+    request.headers.get('x-forwarded-host') ?? request.headers.get('host') ?? '',
+  );
+  if (host) {
+    return `https://${host}`;
+  }
+  const local = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])$/.test(url.hostname);
+  return local || !tenantDomain ? url.origin : `https://${tenantDomain}`;
+}
+
+/**
+ * Pages kept out of search engines: ORIONPLACE_NOINDEX_PATHS lists path
+ * prefixes separated by spaces or commas, for example "/catalog /category
+ * /product" on a demo or staging storefront. Those pages answer with
+ * `X-Robots-Tag: noindex, follow` and the sitemap leaves them out. Empty
+ * (the default) keeps every public page indexable.
+ */
+export function noindexPathPrefixes(value = environment.ORIONPLACE_NOINDEX_PATHS) {
+  return String(value ?? '')
+    .split(/[\s,]+/)
+    .map((item) => item.trim().replace(/\/+$/, ''))
+    .filter((item) => /^\/[A-Za-z0-9._~\/-]+$/.test(item));
+}
+
+/** Whether a page path is kept out of search engines (see noindexPathPrefixes). */
+export function marketplaceNoindexPath(pathname, value = environment.ORIONPLACE_NOINDEX_PATHS) {
+  const path = String(pathname ?? '');
+  return noindexPathPrefixes(value)
+    .some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+
+/** The sitemap pages search engines may index. */
+export function sitemapIndexedPages(pages, value = environment.ORIONPLACE_NOINDEX_PATHS) {
+  return noindexPathPrefixes(value).length
+    ? pages.filter((page) => !marketplaceNoindexPath(page.path, value))
+    : pages;
+}
+
+/** @param {string} origin */
+export function marketplaceRobots(origin) {
+  return `User-agent: *\nDisallow: /api/\nAllow: /\n\nSitemap: ${origin}/sitemap.xml\n`;
+}
+
+/** @param {Request} request @param {{mimicFrontDomain?: string}} configuration */
+export async function marketplaceRobotsResponse(request, configuration = {}) {
+  let domain = '';
+  try {
+    domain = (await readMarketplace(request, configuration)).domain;
+  } catch {
+    domain = '';
+  }
+  return new Response(
+    marketplaceRobots(marketplacePublicOrigin(request, domain)),
+    {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Cache-Control': 'public, max-age=3600',
+        'Vary': 'Host, X-Forwarded-Host, X-Front-Domain',
+      },
+    },
+  );
+}
+
+/** @param {string} value */
+function escapeXml(value) {
+  return value.replace(/[<>&"']/g, (character) => ({
+    '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;',
+  })[character]);
+}
+
+/** @param {unknown} value */
+function publicId(value) {
+  const id = Number(value);
+  return Number.isSafeInteger(id) && id > 0 ? id : null;
+}
+
+/** The marketplace's languages from /appload `init.locale`. */
+export function sitemapLocales(locales) {
+  const codes = Object.entries(locales && typeof locales === 'object' ? locales : {})
+    .map(([key, item]) => String(item?.code || key).trim().toLowerCase())
+    .filter((code) => /^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$/.test(code));
+  return [...new Set(codes)].sort();
+}
+
+/** A product edit time (ISO 8601) or a blog post day ({date: 'DD.MM.YYYY'}). */
+export function sitemapLastmod(value, now = Date.now()) {
+  if (typeof value === 'string' && value) {
+    const time = Date.parse(value);
+    return Number.isFinite(time) && time <= now + 60_000
+      ? new Date(time).toISOString().replace(/\.\d{3}Z$/, 'Z')
+      : null;
+  }
+  const match = /^(\d{2})\.(\d{2})\.(\d{4})$/.exec(value?.date ?? '');
+  if (!match) {
+    return null;
+  }
+  const [, day, month, year] = match;
+  const time  = Date.UTC(Number(year), Number(month) - 1, Number(day));
+  const date  = new Date(time);
+  return date.getUTCDate() === Number(day) &&
+    date.getUTCMonth() === Number(month) - 1 &&
+    time <= now + 24 * 60 * 60 * 1000
+    ? `${year}-${month}-${day}`
+    : null;
+}
+
+/** The API path (under /api) of a route named in /appload `unauth.paths`. */
+export function sitemapApiPath(paths, name) {
+  for (const group of Object.values(paths ?? {})) {
+    for (const route of Object.values(group ?? {})) {
+      if (route?.url_name === name) {
+        const target = String(route.target ?? '').split('/{')[0].replace(/^\/+/, '');
+        return target.startsWith('api/') ? `/${target}` : null;
+      }
+    }
+  }
+  return null;
+}
+
+/** Public categories, parents before children. */
+export function sitemapCategoryIds(categories) {
+  const ids   = [];
+  const visit = (category) => {
+    const id = publicId(category?.id);
+    if (id && category?.is_public) {
+      ids.push(id);
+    }
+    (category?.childs ?? []).forEach(visit);
+  };
+  (Array.isArray(categories) ? categories : []).forEach(visit);
+  return [...new Set(ids)];
+}
+
+/**
+ * One <url> per page and language, each with alternates for its languages.
+ * A page with its own `locales` (a publication written in some languages
+ * only) is listed in those of the marketplace's languages.
+ * @param {string} origin
+ * @param {{path: string, lastmod?: string | null, locales?: string[]}[]} pages
+ * @param {string[]} locales
+ */
+export function marketplaceSitemapXml(origin, pages, locales) {
+  const href  = (path, code) => {
+    const url = new URL(path, `${origin}/`);
+    if (code) {
+      url.searchParams.set('locale', code);
+    }
+    return escapeXml(url.toString());
+  };
+  const urls  = [];
+  for (const page of pages) {
+    const own        = page.locales
+      ? locales.filter((code) => page.locales.includes(code))
+      : locales;
+    if (page.locales && !own.length) {
+      continue;
+    }
+    const codes      = own.length ? own : [''];
+    const alternates = own.length > 1
+      ? own.map((code) =>
+        `    <xhtml:link rel="alternate" hreflang="${escapeXml(code)}" href="${href(page.path, code)}" />\n`).join('')
+      : '';
+    const lastmod    = page.lastmod ? `    <lastmod>${escapeXml(page.lastmod)}</lastmod>\n` : '';
+    for (const code of codes) {
+      if (urls.length >= sitemapMaxUrls) {
+        break;
+      }
+      urls.push(`  <url>\n    <loc>${href(page.path, code)}</loc>\n${lastmod}${alternates}  </url>\n`);
+    }
+  }
+  return '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">\n' +
+    urls.join('') +
+    '</urlset>\n';
+}
+
+/** @param {{domain: string, api: URL}} tenant @param {string} path @param {unknown} body */
+async function sitemapRequest(tenant, path, body) {
+  const response = await fetch(new URL(path, tenant.api.origin), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      'X-Front-Domain': tenant.domain,
+    },
+    body: JSON.stringify(body),
+    cache: 'no-store',
+    signal: AbortSignal.timeout(requestTimeout),
+  });
+  if (!response.ok) {
+    throw new Error(`${path} answered ${response.status}`);
+  }
+  return response.json();
+}
+
+/** Every record of a paginated list (`page_data[key].data` + `rpag`). */
+async function sitemapList(tenant, path, key, filters = {}) {
+  const records = new Map();
+  let page      = 1;
+  for (let count = 0; count < sitemapMaxPages; count++) {
+    const payload = await sitemapRequest(tenant, path, {
+      filters,
+      paginate: { page, pp_items: sitemapPageSize },
+    });
+    const list    = payload?.page_data?.[key];
+    if (!Array.isArray(list?.data)) {
+      throw new Error(`${path} returned no ${key} list`);
+    }
+    for (const record of list.data) {
+      const id = publicId(record?.id);
+      if (id) {
+        records.set(id, record);
+      }
+    }
+    const next    = Number(list.rpag?.next_page_number);
+    if (!list.rpag?.has_next || !Number.isSafeInteger(next) || next <= page) {
+      return [...records.values()];
+    }
+    page          = next;
+  }
+  throw new Error(`${path} has more than ${sitemapMaxPages} pages`);
+}
+
+/** Products on sale and in stock states a shopper can open. */
+function productOnSale(product) {
+  const status = Number(product?.status?.status ?? product?.status);
+  return [2, -2, -3].includes(status);
+}
+
+/** Blog publications that are published. */
+function postPublished(post) {
+  const state = post?.publishing_state?.int ?? post?.publishing_state;
+  return state === undefined || state === null || Number(state) === 1;
+}
+
+/** The languages a publication is written in (it has a title there). */
+function postLocales(post) {
+  return Object.entries(post?.locale && typeof post.locale === 'object' ? post.locale : {})
+    .filter(([, text]) => typeof text?.post_title === 'string' && text.post_title.trim())
+    .map(([code]) => code.toLowerCase());
+}
+
+/** @param {{domain: string, api: URL}} tenant */
+async function buildMarketplaceSitemap(tenant) {
+  const appload    = await sitemapRequest(tenant, '/api/appload', {
+    detalize_mode: 'light',
+    ignore_cache: false,
+  });
+  const init       = appload?.page_data?.init;
+  const paths      = appload?.page_data?.unauth?.paths;
+  if (!init || !Array.isArray(init.catalog)) {
+    throw new Error('appload returned no catalog');
+  }
+  const locales    = sitemapLocales(init.locale);
+  const categories = sitemapCategoryIds(init.catalog);
+  const blogPath   = sitemapApiPath(paths, 'blog_posts_get');
+  const searchPath = sitemapApiPath(paths, 'products_search');
+  const [products, posts] = await Promise.all([
+    searchPath && categories.length
+      ? sitemapList(tenant, searchPath, 'products', { categories })
+      : [],
+    blogPath ? sitemapList(tenant, blogPath, 'posts') : [],
+  ]);
+  const postPages  = posts
+    .filter(postPublished)
+    .sort((left, right) => left.id - right.id)
+    .map((post) => ({
+      path: `/journal/${post.id}`,
+      lastmod: sitemapLastmod(post.date_updated),
+      locales: postLocales(post),
+    }));
+  const newestPost = postPages.map((page) => page.lastmod).filter(Boolean).sort().at(-1) ?? null;
+  const pages      = [
+    { path: '/' },
+    { path: '/catalog' },
+    ...(blogPath ? [{ path: '/journal', lastmod: newestPost }] : []),
+    ...(init.tariffs?.data?.length ? [{ path: '/tariffs' }] : []),
+    { path: '/manufacturers' },
+    ...(init.visual_settings?.single_seller_mode ? [] : [{ path: '/sellers' }]),
+    { path: '/stores' },
+    { path: '/contact' },
+    { path: '/privacy' },
+    ...categories.map((id) => ({ path: `/category/${id}` })),
+    ...products
+      .filter(productOnSale)
+      .map((product) => ({
+        path: `/product/${product.id}`,
+        lastmod: sitemapLastmod(product.date_updated),
+      })),
+    ...postPages,
+  ];
+  return {
+    version: sitemapVersion,
+    domain: tenant.domain,
+    built: new Date().toISOString(),
+    locales,
+    pages,
+  };
+}
+
+/** How many <url> entries a built sitemap has. */
+export function sitemapUrlCount(sitemap) {
+  let count = 0;
+  for (const page of sitemapIndexedPages(sitemap.pages)) {
+    const own = page.locales
+      ? sitemap.locales.filter((code) => page.locales.includes(code))
+      : sitemap.locales;
+    count    += page.locales ? own.length : Math.max(own.length, 1);
+  }
+  return Math.min(count, sitemapMaxUrls);
+}
+
+/** The cache folder of built sitemaps. */
+export function sitemapCacheDirectory(root = process.cwd()) {
+  return environment.ORIONPLACE_CACHE_DIR
+    ? resolve(root, environment.ORIONPLACE_CACHE_DIR, 'sitemaps')
+    : resolve(root, 'node_modules', '.cache', 'orionplace', 'sitemaps');
+}
+
+/** @param {string} domain @param {string} root */
+function sitemapCachePath(domain, root) {
+  return resolve(sitemapCacheDirectory(root), `${domain}.json`);
+}
+
+/** A cached sitemap of the domain, or null. @param {string} domain */
+export async function readSitemapCache(domain, root = process.cwd()) {
+  let sitemap;
+  try {
+    sitemap = JSON.parse(await readFile(sitemapCachePath(domain, root), 'utf8'));
+  } catch {
+    return null;
+  }
+  return sitemap?.version === sitemapVersion &&
+    sitemap.domain === domain &&
+    Number.isFinite(Date.parse(sitemap.built)) &&
+    Array.isArray(sitemap.locales) &&
+    Array.isArray(sitemap.pages)
+    ? sitemap
+    : null;
+}
+
+/**
+ * Write the cache file. When root writes it (sudo), the folders it creates
+ * and the file go to the project owner, so the storefront service can
+ * replace them later.
+ */
+async function writeSitemapCache(sitemap, root) {
+  const path      = sitemapCachePath(sitemap.domain, root);
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await mkdir(dirname(path), { recursive: true });
+  try {
+    await writeFile(temporary, JSON.stringify(sitemap), { mode: 0o644 });
+    await rename(temporary, path);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+  if (process.getuid?.() === 0) {
+    const owner = await stat(root);
+    if (owner.uid !== 0) {
+      let cursor = path;
+      while (cursor !== root && !relative(root, cursor).startsWith('..')) {
+        const info = await stat(cursor);
+        if (info.uid === 0) {
+          await chown(cursor, owner.uid, owner.gid);
+        }
+        cursor = dirname(cursor);
+      }
+    }
+  }
+  return path;
+}
+
+/** @param {{domain: string, api: URL}} tenant @param {string} root */
+function buildOnce(tenant, root) {
+  let build = sitemapBuilds.get(tenant.domain);
+  if (!build) {
+    build = buildMarketplaceSitemap(tenant)
+      .then(async (sitemap) => {
+        sitemapMemory.set(tenant.domain, sitemap);
+        try {
+          await writeSitemapCache(sitemap, root);
+        } catch (error) {
+          console.error(`[orionplace] Sitemap cache not written: ${error?.code ?? error?.message ?? error}`);
+        }
+        return sitemap;
+      })
+      .finally(() => sitemapBuilds.delete(tenant.domain));
+    sitemapBuilds.set(tenant.domain, build);
+  }
+  return build;
+}
+
+/**
+ * Rebuild the sitemap of one storefront domain now and store it where the
+ * running storefront reads it (the "sitemap rebuild" command).
+ * @param {string} domain @param {{root?: string}} options
+ */
+export async function rebuildMarketplaceSitemap(domain, options = {}) {
+  const root    = resolve(options.root ?? process.cwd());
+  const tenant  = await readMarketplaceDomain(domain, { root });
+  const sitemap = await buildMarketplaceSitemap(tenant);
+  const path    = await writeSitemapCache(sitemap, root);
+  return {
+    domain: tenant.domain,
+    path,
+    built: sitemap.built,
+    urls: sitemapUrlCount(sitemap),
+    pages: sitemap.pages.length,
+    publications: sitemap.pages.filter((page) => page.path.startsWith('/journal/')).length,
+  };
+}
+
+/** The storefront domains of the project (its `sitemaps/*.cfg` files). */
+export async function marketplaceDomains(root = process.cwd()) {
+  let names;
+  try {
+    names = await readdir(marketplaceConfigDirectory(root));
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+  return names
+    .filter((name) => name.endsWith('.cfg'))
+    .map((name) => normalizeFrontDomain(name.slice(0, -4)))
+    .filter(Boolean)
+    .sort();
+}
+
+/** @param {Request} request @param {{mimicFrontDomain?: string}} configuration */
+export async function marketplaceSitemapResponse(request, configuration = {}) {
+  let tenant;
+  try {
+    tenant = await readMarketplace(request, configuration);
+  } catch {
+    return failure(503, 'Storefront domain configuration is missing or invalid');
+  }
+  const root    = process.cwd();
+  const fresh   = (sitemap) =>
+    sitemap && Date.now() - Date.parse(sitemap.built) < SITEMAP_LIFETIME;
+  // The file wins when it is newer: a "sitemap rebuild" replaced it.
+  const file    = await readSitemapCache(tenant.domain, root);
+  const memory  = sitemapMemory.get(tenant.domain);
+  const newest  = [file, memory]
+    .filter(Boolean)
+    .sort((left, right) => Date.parse(right.built) - Date.parse(left.built))[0];
+  let sitemap   = fresh(newest) ? newest : null;
+  if (!sitemap) {
+    try {
+      sitemap = await buildOnce(tenant, root);
+    } catch (error) {
+      console.error(`[orionplace] Sitemap build failed: ${error?.message ?? error}`);
+      if (!newest) {
+        return failure(502, 'Marketplace backend is unavailable');
+      }
+      sitemap = newest;
+    }
+  }
+  const origin  = marketplacePublicOrigin(request, tenant.domain);
+  return new Response(marketplaceSitemapXml(origin, sitemapIndexedPages(sitemap.pages), sitemap.locales), {
+    headers: {
+      'Content-Type': 'application/xml; charset=utf-8',
+      'Cache-Control': 'public, max-age=3600',
+      'Vary': 'Host, X-Forwarded-Host, X-Front-Domain',
+    },
+  });
+}

package/src/project-readme.mjs

@@ -89,6 +89,7 @@ and Next.js configuration are preserved.
 | \`../${base}app/_storefront/\` | Route controllers that connect components, navigation and API actions. |
 | \`../${base}app/api/[...orionplace]/route.ts\` | The route handler serving \`/api/...\` from your project. |
 | \`../${base}app/ps3/blog/[...orionplace]/route.ts\` | The route handler serving guarded blog images and videos under \`/ps3/blog/...\`. |
+| \`../${base}app/robots.txt/route.ts\`, \`../${base}app/sitemap.xml/route.ts\` | \`/robots.txt\` and the storefront sitemap. |
 | \`../${base}proxy.ts\` | Marks personalized pages private and answers HTTP 503 when Application Load fails. |
 | \`../sitemaps/${frontend}.cfg\` | The backend URL used for this frontend domain. |
 | \`../.env\` | Local MIMIC setting; keep secrets out of version control. |
@@ -389,8 +390,28 @@ location / {
 
 Here localhost is your frontend process on your VPS. That process selects the
 remote personal API from the domain file. The proxy must overwrite those headers.
-An unknown domain never falls back to another tenant. This setup does not generate
-sitemap XML or add analytics.
+An unknown domain never falls back to another tenant. \`/robots.txt\` points
+crawlers to \`/sitemap.xml\`, which lists the public pages, categories, products
+on sale and journal publications in every storefront language (each publication
+only in the languages it is written in). The sitemap is built from the backend
+and kept for an hour in \`node_modules/.cache/orionplace/sitemaps/\`
+(\`ORIONPLACE_CACHE_DIR\` moves it). After you publish or change content, rebuild
+it at once from the project folder; the running storefront serves the new
+sitemap without a restart:
+
+\`\`\`bash
+npm run orionplace:sitemap                          # every frontend domain
+npx orionplace-react sitemap rebuild shop.example.com  # one domain
+npx orionplace-react sitemap status                  # when each was built
+\`\`\`
+
+To keep a demo or staging storefront's shop pages out of search engines, set
+\`ORIONPLACE_NOINDEX_PATHS\` in \`.env\` to path prefixes separated by spaces,
+for example \`ORIONPLACE_NOINDEX_PATHS="/catalog /category /product"\`. Those
+pages answer with \`X-Robots-Tag: noindex, follow\` and the sitemap leaves them
+out; the journal and other pages stay indexable. Leave it empty on a live shop.
+
+This setup does not add analytics.
 
 ## Android app
 

package/src/setup.mjs

@@ -187,6 +187,7 @@ export async function setupProject({ cwd = process.cwd(), action = 'set', field,
   pkg.scripts['orionplace:remove-frontend'] ||= 'orionplace-react remove frontend';
   pkg.scripts['orionplace:mimic']           ||= 'orionplace-react set mimic';
   pkg.scripts['orionplace:help']            ||= 'orionplace-react help';
+  pkg.scripts['orionplace:sitemap']         ||= 'orionplace-react sitemap rebuild';
   pkg.scripts['orionplace:update']          ||= 'orionplace-react update';
   pkg.dependencies                          ||= {};
   pkg.dependencies.zustand                  ||= dependencies.zustand || '^5.0.15';

package/src/sitemap.mjs

@@ -0,0 +1,93 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const metadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+const cli      = metadata.name;
+
+/**
+ * The project's own gateway runtime (orionplace/runtime/marketplace.mjs): the
+ * sitemap is built with the code the running storefront uses.
+ */
+async function projectRuntime(root) {
+  const path    = resolve(root, 'orionplace/runtime/marketplace.mjs');
+  if (!existsSync(path)) {
+    throw new Error(`No orionplace/runtime/marketplace.mjs in ${root}. Run this in the storefront project (or pass --cwd).`);
+  }
+  const runtime = await import(pathToFileURL(path).href);
+  if (typeof runtime.rebuildMarketplaceSitemap !== 'function') {
+    throw new Error(`This project's runtime has no sitemap support. Run npx ${cli} update first.`);
+  }
+  return runtime;
+}
+
+/**
+ * The storefront reads SITEMAPS_DIR and ORIONPLACE_CACHE_DIR from the
+ * project's .env; the command uses the same folders. Variables already set
+ * in the shell win.
+ */
+async function projectEnvironment(root) {
+  let source = '';
+  try { source = await readFile(resolve(root, '.env'), 'utf8'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  for (const line of source.split(/\r?\n/)) {
+    const match = /^\s*(?:export\s+)?(SITEMAPS_DIR|ORIONPLACE_CACHE_DIR)\s*=\s*(.*?)\s*$/.exec(line);
+    if (!match || process.env[match[1]] !== undefined) continue;
+    const value = match[2].replace(/^(['"])(.*)\1$/, '$2');
+    if (value) process.env[match[1]] = resolve(root, value);
+  }
+}
+
+async function domainsFor(runtime, root, domain) {
+  if (domain) {
+    const normalized = runtime.normalizeFrontDomain(domain);
+    if (!normalized) throw new Error(`Invalid frontend domain: ${domain}`);
+    return [normalized];
+  }
+  const domains = await runtime.marketplaceDomains(root);
+  if (!domains.length) throw new Error(`No frontend domains yet. Add one: npx ${cli} add frontend <shop.example.com>`);
+  return domains;
+}
+
+function age(built, now = Date.now()) {
+  const minutes = Math.max(0, Math.round((now - Date.parse(built)) / 60_000));
+  return minutes < 60 ? `${minutes} min ago` : `${Math.floor(minutes / 60)} h ${minutes % 60} min ago`;
+}
+
+/**
+ * `sitemap rebuild [domain]`: build the sitemap of every frontend domain (or
+ * one) now. `sitemap status [domain]`: show when each was built.
+ * @param {{cwd: string, action: string, domain?: string, log?: (line: string) => void}} options
+ * @returns {Promise<number>} exit code
+ */
+export async function sitemapCommand({ cwd, action, domain, log = console.log }) {
+  if (!['rebuild', 'status'].includes(action)) {
+    throw new Error(`Use: npx ${cli} sitemap rebuild [domain] | sitemap status [domain]`);
+  }
+  const root    = resolve(cwd);
+  await projectEnvironment(root);
+  const runtime = await projectRuntime(root);
+  const domains = await domainsFor(runtime, root, domain);
+  let failed    = 0;
+  for (const name of domains) {
+    if (action === 'status') {
+      const sitemap = await runtime.readSitemapCache(name, root);
+      const stale   = sitemap && Date.now() - Date.parse(sitemap.built) >= runtime.SITEMAP_LIFETIME;
+      log(sitemap
+        ? `${name}: built ${sitemap.built} (${age(sitemap.built)}), ${runtime.sitemapUrlCount(sitemap)} URLs${stale ? '; rebuilt at the next crawl' : ''}`
+        : `${name}: not built yet; built at the first /sitemap.xml request or with: npx ${cli} sitemap rebuild`);
+      continue;
+    }
+    const started = Date.now();
+    try {
+      const done = await runtime.rebuildMarketplaceSitemap(name, { root });
+      log(`${name}: ${done.urls} URLs (${done.pages} pages, ${done.publications} journal publications) in ${((Date.now() - started) / 1000).toFixed(1)} s`);
+      log(`  saved ${relative(root, done.path)}; the running storefront serves it now at https://${name}/sitemap.xml`);
+    } catch (error) {
+      failed++;
+      log(`${name}: not rebuilt: ${error?.message ?? error}`);
+    }
+  }
+  return failed ? 1 : 0;
+}