tablefacts 0.1.0

package/src/menu/cluvi/config.mjs

@@ -0,0 +1,33 @@
+// Everything restaurant-specific about the Cluvi import. Edit this file, not
+// source.mjs, when the menu is organised differently.
+export default {
+  // Any page of the restaurant's Cluvi menu. Only the first path segment is
+  // used (the supplier, here "cannario"). `tablefacts menu cluvi <url>`
+  // overrides it for one run.
+  url: "https://cannario.cluvi.co/cannario/maincategories",
+
+  // Cluvi groups products as main category > subcategory. The site groups them
+  // as category > section, with three categories by default (cocina, brunch,
+  // bar), so each main category is folded into one of these. `from` lists
+  // Cluvi main categories, ignoring case and accents. One that is listed
+  // nowhere becomes a category of its own (slug from its name); that works,
+  // but the slug then needs its keys in the dictionaries and in content/qr.ts.
+  // A category left with no products is not written.
+  categories: [
+    { slug: "cocina", name: "Comida", from: ["Entradas", "Fuertes", "Postres"] },
+    {
+      slug: "bar",
+      name: "Bebidas",
+      from: ["Cócteles Cannario", "Tardeo Cannario", "Vinos", "Licores", "Bebidas"],
+    },
+  ],
+
+  // Cluvi subcategory > section name, for the ones that should not just be
+  // the subcategory name in UPPERCASE. These two match keys of `menu.sections`
+  // in dictionary.ts, and the home page cocktail list reads signatureMenu
+  // ("COCTELES DE AUTOR") from content/site.ts.
+  sections: {
+    "Cócteles Autor Cannario": "COCTELES DE AUTOR",
+    Mocktails: "MOCKTAIL",
+  },
+};

package/src/menu/cluvi/extract.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Imports a restaurant's menu from Cluvi into the Supabase menu tables.
+// See src/menu/README.md. Run from the project's folder:
+//   tablefacts menu cluvi --dry-run
+import { runImport } from "../lib/run.mjs";
+import { fetchCluviMenu } from "./import.mjs";
+
+const usage = `Usage: tablefacts menu cluvi [menu-url] [options]
+
+Reads the menu of a restaurant on Cluvi and replaces it in Supabase.
+menu-url   any page of the restaurant's Cluvi menu (default: config.mjs)
+
+Cluvi options:
+  --service <name>   which Cluvi menu to read: on_table (default), delivery, take_away
+  --lang <code>      language of the Cluvi menu (default: es)`;
+
+await runImport({
+  usage,
+  options: {
+    service: { type: "string", default: "on_table" },
+    lang: { type: "string", default: "es" },
+  },
+  fetchMenu: ({ values, positionals }) => fetchCluviMenu({ url: positionals[0], service: values.service, lang: values.lang }),
+});

package/src/menu/cluvi/import.mjs

@@ -0,0 +1,30 @@
+// Cluvi as a library: read the menu of a restaurant and import it.
+import { TablefactsError } from "../../lib/errors.mjs";
+import { importMenu } from "../lib/import.mjs";
+import defaultConfig from "./config.mjs";
+import { fetchCluvi, normalizeCluvi } from "./source.mjs";
+
+/**
+ * Reads and normalizes the menu: `{ menu, notes, title }`, ready for importMenu.
+ * `config` is the restaurant-specific part (see config.mjs); the default is that file's.
+ */
+export async function fetchCluviMenu({ url, service, lang, config = defaultConfig } = {}) {
+  if (!(url ?? config.url)) throw new TablefactsError("No Cluvi menu URL: pass url, or set url in the cluvi config.", "ECONFIG");
+  const fetched = await fetchCluvi({ url: url ?? config.url, service, lang });
+  const { menu, notes, currency } = normalizeCluvi(fetched, config);
+  const { supplier } = fetched;
+  return {
+    menu,
+    notes,
+    title: `Cluvi: ${supplier.label} (id ${supplier.id}), ${fetched.service} menu in ${currency}`,
+  };
+}
+
+/**
+ * Reads the menu from Cluvi and imports it. Takes importMenu's options too.
+ * @param {import('../../lib/types.mjs').ImportCluviOptions} [options]
+ * @returns {Promise<import('../../lib/types.mjs').ImportResult>}
+ */
+export async function importCluvi({ url, service, lang, config, ...importOptions } = {}) {
+  return importMenu({ ...(await fetchCluviMenu({ url, service, lang, config })), ...importOptions });
+}

package/src/menu/cluvi/source.mjs

@@ -0,0 +1,156 @@
+// Reads a restaurant's menu from Cluvi (cluvi.com), which serves digital menus
+// as a single-page app at <restaurant>.cluvi.co. The page has no menu markup
+// and Cluvi publishes no API, so this calls the two JSON endpoints the app
+// itself calls. They are not a documented interface and may change: if the
+// import breaks, check these URLs against the network tab of the menu page.
+//
+//   supplier  https://exp2.cluvi.com/api/suppliers/<slug>.json        id, currency
+//   menu      https://services.cluvi.com/v1/menu/<id>/<service>.json  categories + products
+import { cleanText, htmlToText, isCurrency, matchKey, sectionName, slugify } from "../lib/menu.mjs";
+import { TablefactsError } from "../../lib/errors.mjs";
+
+const SUPPLIER_URL = "https://exp2.cluvi.com/api/suppliers";
+const MENU_URL = "https://services.cluvi.com/v1/menu";
+const headers = { accept: "application/json", "user-agent": "cannario-menu-sync/1.0 (restaurant menu importer)" };
+
+async function getJson(url) {
+  let failure;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      const res = await fetch(url, { headers, signal: AbortSignal.timeout(30_000) });
+      if (res.ok) return await res.json();
+      failure = Object.assign(new TablefactsError(`HTTP ${res.status} from ${url}`, "EFAILED"), { status: res.status });
+      if (res.status < 500) break; // a client error will not fix itself
+    } catch (error) {
+      failure = error; // network error, timeout or a body that is not JSON
+    }
+    await new Promise((resolve) => setTimeout(resolve, attempt * 1000));
+  }
+  throw failure;
+}
+
+/** https://<restaurant>.cluvi.co/<supplier>/maincategories gives "<supplier>". */
+export function supplierSlug(menuUrl) {
+  let slug;
+  try {
+    slug = new URL(menuUrl).pathname.split("/").filter(Boolean)[0];
+  } catch {
+    throw new TablefactsError(`"${menuUrl}" is not a URL.`, "EUSAGE");
+  }
+  if (!slug) {
+    throw new TablefactsError(`"${menuUrl}" has no supplier in its path. Use a menu page such as https://<restaurant>.cluvi.co/<supplier>/maincategories.`, "EUSAGE");
+  }
+  return slug;
+}
+
+/**
+ * `service` picks which of the restaurant's menus to read. `on_table` is the
+ * digital menu guests open from the table QR code and is the complete one:
+ * `delivery` and `take_away` only list what the restaurant sells that way.
+ */
+export async function fetchCluvi({ url, service = "on_table", lang = "es" }) {
+  const slug = supplierSlug(url);
+  const unknown = new TablefactsError(`Cluvi has no restaurant "${slug}". Check the first path segment of the menu URL.`, "EFAILED");
+  let supplier;
+  try {
+    supplier = await getJson(`${SUPPLIER_URL}/${slug}.json`);
+  } catch (error) {
+    throw error.status === 404 ? unknown : error;
+  }
+  if (!supplier?.id) throw unknown; // an unknown slug is answered with 200 and {}
+  const raw = await getJson(`${MENU_URL}/${supplier.id}/${encodeURIComponent(service)}.json?lang=${encodeURIComponent(lang)}`);
+  return { supplier, raw, service };
+}
+
+// Photos come as the same file at several widths. The largest is the best
+// source for next/image, which resizes it again.
+const imageWidths = ["w_1200", "w_992", "w_768", "w_576", "blog", "thumb"];
+
+function imageUrl(image) {
+  if (typeof image === "string") return image.startsWith("https://") ? image : null;
+  return imageWidths.map((width) => image?.[width]).find((url) => typeof url === "string" && url.startsWith("https://")) ?? null;
+}
+
+const byOrder = (a, b) => (Number(a.order) || 0) - (Number(b.order) || 0);
+const leaves = (category) => (category.subcategories?.length ? category.subcategories.flatMap(leaves) : [category]);
+const listNames = (names) => names.slice(0, 8).join(", ") + (names.length > 8 ? `, and ${names.length - 8} more` : "");
+
+/**
+ * Cluvi's response to the shape lib/menu.mjs describes. Main categories are
+ * folded into the categories of `config.categories`, subcategories become
+ * sections, and products keep the order Cluvi shows them in (their `order`
+ * field, not their position in the subcategory's product_ids).
+ */
+export function normalizeCluvi({ supplier, raw }, config) {
+  const { categories, products } = raw?.menu ?? {};
+  if (!Array.isArray(categories) || !Array.isArray(products)) {
+    throw new TablefactsError("Cluvi returned a menu in an unexpected shape (no menu.categories or menu.products). Its API may have changed: see src/menu/cluvi/source.mjs.", "EFAILED");
+  }
+  const currency = [supplier.currency, raw.customer?.currency].map((code) => String(code ?? "").toUpperCase()).find(isCurrency);
+  if (!currency) throw new TablefactsError("Cluvi did not say which currency this menu uses.", "EFAILED");
+
+  const notes = [];
+  const byId = new Map(products.map((product) => [product.id, product]));
+  const renames = new Map(Object.entries(config.sections ?? {}).map(([from, to]) => [matchKey(from), to]));
+  const groups = (config.categories ?? []).map((c) => ({ slug: c.slug, name: c.name, from: new Set(c.from.map(matchKey)), sections: new Map() }));
+  const own = new Map(); // main categories that config.categories does not list
+  const placed = new Set();
+  const unpriced = [];
+  const withOptions = [];
+  let soldOut = 0;
+
+  const ownCategory = (main) => {
+    const slug = slugify(main.label) || `category-${main.id}`;
+    if (!own.has(slug)) {
+      own.set(slug, { slug, name: cleanText(main.label), sections: new Map() });
+      notes.push(`Cluvi category "${cleanText(main.label)}" is not in config.categories: imported as its own category "${slug}".`);
+    }
+    return own.get(slug);
+  };
+
+  function convert(product) {
+    const name = cleanText(product.label);
+    if (!name) return null;
+    const price = Number(product.price);
+    if (!(price > 0)) unpriced.push(name);
+    if (product.configs?.length) withOptions.push(name);
+    if (product.out_of_stock) soldOut++;
+    return {
+      name,
+      description: htmlToText(product.description),
+      price: price > 0 ? Math.round(price * 100) / 100 : 0,
+      currency,
+      image_url: imageUrl(product.image),
+      recommended: product.important === true,
+    };
+  }
+
+  for (const main of [...categories].sort(byOrder)) {
+    const category = groups.find((group) => group.from.has(matchKey(main.label))) ?? ownCategory(main);
+    for (const sub of leaves(main).sort(byOrder)) {
+      const name = renames.get(matchKey(sub.label)) ?? sectionName(sub.label || main.label);
+      if (!category.sections.has(name)) category.sections.set(name, []);
+      const items = (sub.product_ids ?? []).map((id, index) => ({ product: byId.get(id), index }));
+      for (const { product } of items.filter((item) => item.product).sort((a, b) => byOrder(a.product, b.product) || a.index - b.index)) {
+        placed.add(product.id);
+        const converted = convert(product);
+        if (converted) category.sections.get(name).push(converted);
+      }
+    }
+  }
+
+  const unplaced = products.filter((product) => !placed.has(product.id));
+  if (unplaced.length) notes.push(`${unplaced.length} products are in no category and were skipped: ${listNames(unplaced.map((p) => cleanText(p.label)))}.`);
+  if (unpriced.length) notes.push(`${unpriced.length} products have no price in Cluvi, which hides a price of 0. They are imported with price 0 and the site will show 0: ${listNames(unpriced)}.`);
+  if (withOptions.length) notes.push(`${withOptions.length} products have options in Cluvi (add-ons, sizes) that the menu tables cannot hold, so only their base price is imported.`);
+  if (soldOut) notes.push(`${soldOut} products are marked sold out in Cluvi and were imported anyway.`);
+
+  const menu = [...groups, ...own.values()]
+    .map((c) => ({
+      slug: c.slug,
+      name: c.name,
+      sections: [...c.sections].filter(([, list]) => list.length).map(([name, list]) => ({ name, products: list })),
+    }))
+    .filter((c) => c.sections.length);
+  return { menu, notes, currency };
+}

package/src/menu/index.mjs

@@ -0,0 +1,9 @@
+// The menu importer as a library. Silent unless given a `log` function; it
+// never reads process.argv, loads .env or sets an exit code. Importing it runs
+// nothing (pg loads only when a database is reached).
+export { importMenu } from "./lib/import.mjs";
+export { importCluvi } from "./cluvi/import.mjs";
+export { importImageMenu, listMenuImages } from "./raw/import.mjs";
+export { cleanText, countMenu, sectionName, slugify, validateMenu } from "./lib/menu.mjs";
+export { normalizePages, parsePrice } from "./raw/normalize.mjs";
+export { defaultProvider, providers } from "./raw/vision.mjs";

package/src/menu/lib/db.mjs

@@ -0,0 +1,119 @@
+// Writes a menu (see lib/menu.mjs) into the Supabase tables of
+// supabase/migrations/0001_menu.sql over a direct Postgres connection.
+//
+// The connection string (SUPABASE_DB_URL) is a privileged credential: it
+// bypasses row level security, which only allows public reads. It lives in
+// .env, which is git-ignored, and is never read by the site: do not copy
+// it into frontend/.env or into a NEXT_PUBLIC_ variable.
+import { randomUUID } from "node:crypto";
+import { resolveEnv } from "../../lib/env.mjs";
+import { TablefactsError } from "../../lib/errors.mjs";
+
+/** Opens the connection. `label` names the target without the credentials. */
+export async function connect(url, { env } = {}) {
+  url ??= resolveEnv(env).SUPABASE_DB_URL;
+  if (!/^postgres(ql)?:\/\//i.test(url ?? "")) {
+    throw new TablefactsError(
+      "SUPABASE_DB_URL is not set to a postgres:// connection string.\n" +
+        "Copy .env.example to .env and paste the pooler URL from the Supabase dashboard (Connect > Transaction pooler).",
+      "ECONFIG",
+    );
+  }
+  if (url.includes("[YOUR-PASSWORD]")) {
+    throw new TablefactsError("SUPABASE_DB_URL still contains [YOUR-PASSWORD]: replace it with the database password.", "ECONFIG");
+  }
+  let target;
+  try {
+    target = new URL(url);
+  } catch {
+    throw new TablefactsError("SUPABASE_DB_URL is not a valid connection string (special characters in the password must be URL-encoded).", "ECONFIG");
+  }
+
+  const { default: pg } = await import("pg");
+  const client = new pg.Client({
+    connectionString: url,
+    // Supabase's pooler certificate chains to Supabase's own root CA, which Node
+    // does not trust, so verification fails by default. The connection is still
+    // encrypted. Put `sslmode` in the URL to choose something else.
+    ssl: target.searchParams.has("sslmode") ? undefined : { rejectUnauthorized: false },
+  });
+  await client.connect();
+  return { client, label: `${target.hostname}:${target.port || 5432}${target.pathname}` };
+}
+
+/** Says what is wrong when the migration has not been applied to this database. */
+function explain(error) {
+  if (error.code === "42P01") {
+    error.message = "The menu tables do not exist. Apply supabase/migrations/0001_menu.sql to this database first.";
+  }
+  return error;
+}
+
+/** What an import would replace: the categories it writes, or the whole menu. */
+export async function inspect(client, menu, { replaceAll = false } = {}) {
+  const slugs = replaceAll ? null : menu.map((category) => category.slug);
+  try {
+    const { rows } = await client.query(
+      `select count(distinct c.id)::int as categories, count(p.id)::int as products
+         from public.menu_categories c
+         left join public.menu_sections s on s.category_id = c.id
+         left join public.menu_products p on p.section_id = s.id
+        where $1::text[] is null or c.slug = any($1)`,
+      [slugs],
+    );
+    const kept = slugs
+      ? (await client.query("select slug from public.menu_categories where slug <> all($1) order by sort_order", [slugs])).rows.map((row) => row.slug)
+      : [];
+    return { ...rows[0], kept };
+  } catch (error) {
+    throw explain(error);
+  }
+}
+
+/**
+ * Replaces the menu in one transaction, so readers see the old menu or the new
+ * one and a failure changes nothing. By default only the categories in `menu`
+ * are replaced (deleting a category cascades to its sections and products);
+ * `replaceAll` empties the menu first. Ids are generated here so the rows can
+ * be inserted in bulk, a column at a time.
+ */
+export async function replaceMenu(client, menu, { replaceAll = false } = {}) {
+  const categories = menu.map((c, i) => ({ id: randomUUID(), slug: c.slug, name: c.name, sort_order: i + 1 }));
+  const sections = menu.flatMap((c, ci) =>
+    c.sections.map((s, si) => ({ id: randomUUID(), category_id: categories[ci].id, name: s.name, sort_order: si + 1, products: s.products })),
+  );
+  // `recommended` is NOT NULL DEFAULT false, but inserting through unnest sends an explicit null, which skips the default.
+  const products = sections.flatMap((s) => s.products.map((p, i) => ({ ...p, recommended: p.recommended === true, section_id: s.id, sort_order: i + 1 })));
+  const column = (rows, key) => rows.map((row) => row[key] ?? null);
+
+  try {
+    await client.query("begin");
+    if (replaceAll) await client.query("delete from public.menu_categories");
+    else await client.query("delete from public.menu_categories where slug = any($1::text[])", [column(categories, "slug")]);
+
+    const inserted = [
+      await client.query(
+        "insert into public.menu_categories (id, slug, name, sort_order) select * from unnest($1::uuid[], $2::text[], $3::text[], $4::int[])",
+        ["id", "slug", "name", "sort_order"].map((key) => column(categories, key)),
+      ),
+      await client.query(
+        "insert into public.menu_sections (id, category_id, name, sort_order) select * from unnest($1::uuid[], $2::uuid[], $3::text[], $4::int[])",
+        ["id", "category_id", "name", "sort_order"].map((key) => column(sections, key)),
+      ),
+      await client.query(
+        `insert into public.menu_products (section_id, name, description, price, currency, image_url, recommended, sort_order)
+         select * from unnest($1::uuid[], $2::text[], $3::text[], $4::numeric[], $5::text[], $6::text[], $7::boolean[], $8::int[])`,
+        ["section_id", "name", "description", "price", "currency", "image_url", "recommended", "sort_order"].map((key) => column(products, key)),
+      ),
+    ];
+    const expected = [categories.length, sections.length, products.length];
+    if (inserted.some((result, i) => result.rowCount !== expected[i])) {
+      throw new Error("The database did not insert every row; nothing was changed.");
+    }
+    await client.query("commit");
+    return { categories: categories.length, sections: sections.length, products: products.length };
+  } catch (error) {
+    await client.query("rollback").catch(() => {});
+    throw explain(error);
+  }
+}

package/src/menu/lib/import.mjs

@@ -0,0 +1,126 @@
+// The import itself, with no command line in it: check a menu, optionally save
+// it as JSON, compare it with the database and replace it. Silent unless given
+// a `log`; failures are thrown, never turned into an exit code.
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveEnv } from "../../lib/env.mjs";
+import { optionError, TablefactsError } from "../../lib/errors.mjs";
+import { normalizeLog } from "../../lib/log.mjs";
+import { projectRoot, resolveIn } from "../../lib/project.mjs";
+import { connect, inspect, replaceMenu } from "./db.mjs";
+import { countMenu, validateMenu } from "./menu.mjs";
+
+/** Things the site needs that this menu does not give it, read from the template's own files. */
+export async function templateHints(menu, { projectDir } = {}) {
+  const hints = [];
+  const content = join(projectRoot(projectDir), "frontend/src/content");
+  // A file that is missing means the template was reorganised: skip its hint rather than guess.
+  const read = (file) => readFile(join(content, file), "utf8").catch(() => null);
+  const [siteTs, qrTs, dictionary] = await Promise.all([read("site.ts"), read("qr.ts"), read("dictionary.ts")]);
+
+  const signatureBlock = siteTs?.match(/signatureMenu\s*=\s*\{([^}]*)\}/)?.[1] ?? "";
+  const signatureCategory = signatureBlock.match(/category:\s*"([^"]+)"/)?.[1];
+  const signature = signatureBlock.match(/section:\s*"([^"]+)"/)?.[1];
+  if (signature && !menu.find((c) => c.slug === signatureCategory)?.sections.some((s) => s.name === signature)) {
+    hints.push(`The home page cocktail list reads the "${signature}" section of the "${signatureCategory}" category (signatureMenu in content/site.ts). This menu has none, so that list will be empty.`);
+  }
+
+  if (siteTs) {
+    const allowed = new Set([...(siteTs.match(/menuImageHosts[^=]*=\s*\[([^\]]*)\]/)?.[1] ?? "").matchAll(/"([^"]+)"/g)].map((m) => m[1]));
+    const hosts = new Set();
+    for (const c of menu) for (const s of c.sections) for (const p of s.products ?? []) {
+      try { if (p.image_url) hosts.add(new URL(p.image_url).hostname); } catch { /* reported by the import checks */ }
+    }
+    const missing = [...hosts].filter((host) => !allowed.has(host) && !host.endsWith(".supabase.co"));
+    if (missing.length) hints.push(`Photos load from ${missing.join(", ")}, which is not in menuImageHosts (content/site.ts): next/image will refuse them until it is.`);
+  }
+
+  if (qrTs) {
+    const known = new Set([...qrTs.matchAll(/^\s*id:\s*"([^"]+)"/gm)].map((m) => m[1]));
+    const missing = menu.map((c) => c.slug).filter((slug) => !known.has(slug));
+    if (missing.length) hints.push(`Categories not in qrCategories (content/qr.ts): ${missing.join(", ")}. They render, but are not prerendered or in the sitemap and have no index photo; their names and blurbs also need keys in both dictionaries (menu.categories, qr.categoryBlurbs).`);
+  }
+
+  const blocks = [...(dictionary ?? "").matchAll(/^\s*sections:\s*\{([^}]*)\}/gm)].map((m) => m[1]);
+  if (blocks.length) {
+    const keysOf = (block) => new Set([...block.matchAll(/^\s*(?:"([^"]+)"|([A-Za-z_$][\w$]*))\s*:/gm)].map((m) => m[1] ?? m[2]));
+    const mapped = blocks.map(keysOf);
+    const unmapped = [...new Set(menu.flatMap((c) => c.sections.map((s) => s.name)))].filter((name) => mapped.some((keys) => !keys.has(name)));
+    if (unmapped.length) hints.push(`${unmapped.length} sections have no display name in both languages (menu.sections in dictionary.ts) and will show as stored, in capitals: ${unmapped.join(", ")}.`);
+  }
+  return hints;
+}
+
+/**
+ * Checks `menu` (the shape of lib/menu.mjs) and writes it to the database.
+ * `notes` are what the source wants the user to know; `title` heads the log.
+ * Resolves to `{ totals, notes, written, dryRun, database }`, `database` being
+ * `{ label, current }` once it was inspected and null when it was not reached.
+ * @param {import('../../lib/types.mjs').ImportMenuOptions} options
+ * @returns {Promise<import('../../lib/types.mjs').ImportResult>}
+ */
+export async function importMenu({
+  menu,
+  notes = [],
+  title = "",
+  dryRun = false,
+  json,
+  replaceAll = false,
+  force = false,
+  databaseUrl,
+  env,
+  projectDir,
+  log: logOption,
+} = {}) {
+  const log = normalizeLog(logOption);
+  databaseUrl ??= resolveEnv(env).SUPABASE_DB_URL;
+  let client;
+  try {
+    validateMenu(menu);
+    const totals = countMenu(menu);
+
+    log(`${title}\n`);
+    for (const category of menu) {
+      const n = countMenu([category]);
+      log(`  ${category.name} (${category.slug}): ${n.sections} sections, ${n.products} products`);
+    }
+    log(`  Total: ${totals.categories} categories, ${totals.sections} sections, ${totals.products} products (${totals.withImage} with a photo)`);
+    if (json) {
+      await writeFile(resolveIn(projectDir, json), JSON.stringify(menu, null, 2) + "\n");
+      log(`\nSaved ${json}`);
+    }
+    const allNotes = [...notes, ...(await templateHints(menu, { projectDir }))];
+    for (const line of allNotes) log(`\n- ${line}`, "warn");
+
+    const result = { totals, notes: allNotes, written: false, dryRun: !!dryRun, database: null };
+    if (!totals.products) throw new TablefactsError("The source returned no products, so there is nothing to import.", "EFAILED");
+    if (dryRun && !databaseUrl) {
+      log("\nDry run: SUPABASE_DB_URL is not set, so the database was not checked. Nothing was written.", "warn");
+      return result;
+    }
+
+    const scope = { replaceAll: !!replaceAll };
+    let label;
+    ({ client, label } = await connect(databaseUrl, { env }));
+    const current = await inspect(client, menu, scope);
+    result.database = { label, current };
+    log(`\nDatabase ${label}`);
+    log(`  ${scope.replaceAll ? "Replaces the whole menu" : `Replaces the categories this import writes`}: ${current.categories} categories and ${current.products} products now, ${totals.categories} and ${totals.products} after.`);
+    if (current.kept.length) log(`  Left untouched (not part of this import): ${current.kept.join(", ")}. Use \`replaceAll\` to remove them.`, "warn");
+
+    if (current.products > 0 && totals.products < current.products / 2 && !force) {
+      throw optionError("force", `This import has ${totals.products} products and would replace ${current.products}. That looks like a broken extraction, so nothing was written. Use \`force\` if it is intended.`, "EFAILED");
+    }
+    if (dryRun) {
+      log("\nDry run: nothing was written.");
+      return result;
+    }
+    const done = await replaceMenu(client, menu, scope);
+    result.written = true;
+    log(`\nDone: wrote ${done.categories} categories, ${done.sections} sections and ${done.products} products.`);
+    log("The site shows them within the hour (the menu pages revalidate hourly).");
+    return result;
+  } finally {
+    await client?.end().catch(() => {});
+  }
+}

package/src/menu/lib/menu.mjs

@@ -0,0 +1,95 @@
+// What every menu source (src/menu/<source>/) produces, and the helpers they
+// share. A source turns a restaurant's menu on some website into this shape;
+// lib/run.mjs then checks it and writes it to Supabase.
+//
+//   [{ slug, name, sections: [{ name, products: [
+//        { name, description, price, currency, image_url, recommended } ] }] }]
+//
+// Array order is display order (it becomes sort_order). The conventions are
+// the ones in frontend/src/content/menu.ts: a category's `slug` is the key the
+// dictionaries use, and section names are UPPERCASE strings that
+// `menu.sections` in dictionary.ts maps to display names.
+import { TablefactsError } from "../../lib/errors.mjs";
+import { fold, slugify as slug } from "../../lib/text.mjs";
+
+const squash = (text) => String(text ?? "").replace(/\s+/g, " ").trim();
+
+/** Collapses runs of whitespace (Cluvi labels carry stray spaces). */
+export const cleanText = squash;
+
+/** Lowercase, accent-free key, to compare labels typed by different people. */
+export const matchKey = (text) => fold(squash(text));
+
+export const slugify = (text) => slug(squash(text));
+
+export const sectionName = (text) => squash(text).toLocaleUpperCase("es");
+
+const entities = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+
+function decodeEntity(match, body) {
+  if (body[0] !== "#") return entities[body.toLowerCase()] ?? match;
+  const code = body[1].toLowerCase() === "x" ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+  return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match;
+}
+
+/** Rich-text descriptions (<p>, <br>, <span style>) to plain text, one line per paragraph. */
+export function htmlToText(html) {
+  if (!html) return null;
+  const text = String(html)
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/(p|div|li|h[1-6])\s*>/gi, "\n")
+    .replace(/<[^>]*>/g, "")
+    .replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, decodeEntity)
+    .split("\n")
+    .map(squash)
+    .filter(Boolean)
+    .join("\n");
+  return text || null;
+}
+
+const currencies = new Set(Intl.supportedValuesOf("currency"));
+
+/** An invalid code would make Intl.NumberFormat throw in the site's formatPrice. */
+export const isCurrency = (code) => currencies.has(String(code ?? "").toUpperCase());
+
+/**
+ * Totals of a menu.
+ * @param {import('../../lib/types.mjs').Menu} menu
+ * @returns {import('../../lib/types.mjs').MenuTotals}
+ */
+export function countMenu(menu) {
+  const sections = menu.flatMap((c) => c.sections);
+  const products = sections.flatMap((s) => s.products);
+  return {
+    categories: menu.length,
+    sections: sections.length,
+    products: products.length,
+    withImage: products.filter((p) => p.image_url).length,
+  };
+}
+
+/**
+ * Throws a TablefactsError (EFAILED) on anything the database or the site could not take, naming the culprit.
+ * @param {import('../../lib/types.mjs').Menu} menu
+ * @returns {void}
+ */
+export function validateMenu(menu) {
+  const problems = [];
+  const slugs = new Set();
+  for (const category of menu) {
+    if (!category.slug || !category.name) problems.push(`a category has no slug or name (${JSON.stringify(category.name)})`);
+    if (slugs.has(category.slug)) problems.push(`category slug "${category.slug}" appears twice`);
+    slugs.add(category.slug);
+    for (const section of category.sections) {
+      if (!section.name) problems.push(`a section of "${category.slug}" has no name`);
+      for (const product of section.products) {
+        const where = `"${product.name}" in ${category.slug} / ${section.name}`;
+        if (!product.name) problems.push(`a product of ${category.slug} / ${section.name} has no name`);
+        if (!Number.isFinite(product.price) || product.price < 0) problems.push(`${where}: invalid price ${product.price}`);
+        if (!isCurrency(product.currency)) problems.push(`${where}: invalid currency "${product.currency}"`);
+        if (product.image_url && !/^https:\/\//.test(product.image_url)) problems.push(`${where}: image_url is not an https URL`);
+      }
+    }
+  }
+  if (problems.length) throw new TablefactsError(`The extracted menu is not valid:\n  - ${problems.slice(0, 10).join("\n  - ")}`, "EFAILED");
+}