tablefacts 0.1.0

package/src/lib/edge.mjs

@@ -0,0 +1,49 @@
+// Attaches to the user's own Edge window over the DevTools protocol, starting it when needed.
+// Shared by the tools that drive a real browser (photos instagram, photos tripadvisor).
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+export const DEFAULT_CDP = 'http://localhost:9222'
+export const DEFAULT_EDGE_DIR = 'C:\\ig-edge'
+
+const EDGE_PATHS = [
+  'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+  'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+]
+
+/**
+ * Whether a browser answers on the DevTools address.
+ * @param {string} cdp e.g. http://localhost:9222
+ * @returns {Promise<boolean>}
+ */
+export async function cdpUp(cdp) {
+  try {
+    return (await fetch(new URL('/json/version', cdp), { signal: AbortSignal.timeout(2000) })).ok
+  } catch {
+    return false
+  }
+}
+
+// Starts Edge with remote debugging when nothing answers on the `cdp` address (local only).
+// It is detached, so it stays open after the run and keeps its logins for the next one.
+/**
+ * @param {string} cdp DevTools address; only localhost can be started
+ * @param {string} [edgeDir] Edge profile folder. Default C:\ig-edge
+ * @returns {Promise<void>}
+ */
+export async function ensureEdge(cdp, edgeDir) {
+  if (await cdpUp(cdp)) return
+  const url = new URL(cdp)
+  if (!['localhost', '127.0.0.1'].includes(url.hostname)) throw new Error(`no browser answers at ${cdp}`)
+  const exe = EDGE_PATHS.find((path) => existsSync(path))
+  if (!exe) throw new Error('Edge was not found in its usual folder; start it yourself with --remote-debugging-port')
+  const dir = resolve(edgeDir ?? DEFAULT_EDGE_DIR)
+  console.log(`Starting Edge on port ${url.port} (profile ${dir})`)
+  spawn(exe, [`--remote-debugging-port=${url.port}`, `--user-data-dir=${dir}`], { detached: true, stdio: 'ignore' }).unref()
+  for (let i = 0; i < 30; i++) {
+    await new Promise((done) => setTimeout(done, 1000))
+    if (await cdpUp(cdp)) return
+  }
+  throw new Error('Edge did not open its debugging port; close the Edge window that uses that profile and run again')
+}

package/src/lib/env.mjs

@@ -0,0 +1,35 @@
+// Reads KEY=value env files into an env object (process.env by default) without overriding what is already set.
+import { existsSync, readFileSync } from 'node:fs'
+import { envFiles } from './project.mjs'
+
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/
+
+/** `env` when given, else process.env. */
+export const resolveEnv = (env) => env ?? process.env
+
+/** Loads `files` (default: the project's .env files) into `env`. The first file that sets a variable wins. Returns the files it read. */
+export function loadEnvFiles(files = envFiles(), env = process.env) {
+  const target = resolveEnv(env)
+  const read = []
+  for (const file of files) {
+    if (!existsSync(file)) continue
+    read.push(file)
+    for (const line of readFileSync(file, 'utf8').replace(/^/, '').split(/\r?\n/)) {
+      const m = line.match(LINE)
+      if (!m || line.trim().startsWith('#') || m[1] in target) continue
+      target[m[1]] = m[2].replace(/^(['"])(.*)\1$/, '$2')
+    }
+  }
+  return read
+}
+
+/**
+ * Loads the project's env files (`projectDir`, else TABLEFACTS_PROJECT or the current folder) or
+ * exactly `files` into `env` (default process.env). Never overrides a variable that is already set.
+ * Returns the files it read.
+ * @param {import('./types.mjs').LoadEnvOptions} [options]
+ * @returns {string[]}
+ */
+export function loadEnv({ projectDir, files, env = process.env } = {}) {
+  return loadEnvFiles(files ?? envFiles(projectDir), env)
+}

package/src/lib/errors.mjs

@@ -0,0 +1,39 @@
+// The one error type the library throws on purpose, so callers can tell what went wrong from `code`:
+//   EUSAGE      bad or missing arguments (the CLI exits with 2)
+//   ECONFIG     missing key, database URL, unknown provider, no config url
+//   EDEPENDENCY an optional dependency (such as playwright) is not installed
+//   EFAILED     a source failed or was blocked, fetched data did not validate, an unsafe import was refused
+
+export class TablefactsError extends Error {
+  /**
+   * @param {string} message
+   * @param {import('./types.mjs').TablefactsErrorCode} code
+   * @param {{ cause?: unknown, option?: string }} [options] `option` names the library option the message is about.
+   */
+  constructor(message, code, options) {
+    super(message, options?.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'TablefactsError'
+    /** @type {import('./types.mjs').TablefactsErrorCode} */
+    this.code = code
+    if (options?.option !== undefined) {
+      /** The library option the error is about, when it is about one. @type {string=} */
+      this.option = options.option
+    }
+  }
+}
+
+/** Bad or missing arguments: the CLIs exit with 2. */
+export const usageError = (message) => new TablefactsError(message, 'EUSAGE')
+
+/** The exit code a CLI uses for an error it reports: 2 for bad arguments (EUSAGE), 1 for anything else. */
+export const exitCodeFor = (err) => (err?.code === 'EUSAGE' ? 2 : 1)
+
+/** "fooBar" -> "foo-bar". */
+export const kebab = (name) => String(name).replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+
+/** An error about a library option. Write the option in backticks in the message, e.g. "`out` is required". */
+export const optionError = (option, message, code = 'EUSAGE') => new TablefactsError(message, code, { option })
+
+/** The message with `option` tokens replaced by CLI flag text from `flags` ({ out: '--out <folder>' }). */
+export const cliMessage = (err, flags = {}) =>
+  String(err?.message ?? err).replace(/`([^`]+)`/g, (token, name) => (Object.hasOwn(flags, name) ? flags[name] : token))

package/src/lib/files.mjs

@@ -0,0 +1,10 @@
+import { access } from 'node:fs/promises'
+
+export async function exists(path) {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/lib/images.mjs

@@ -0,0 +1,20 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { TablefactsError } from './errors.mjs'
+
+/** Throws EFAILED unless the response is a good image: ok, an image/* content type and at least `minBytes` bytes. */
+export function assertImageResponse({ ok, status, contentType, bytes, minBytes = 0, label } = {}) {
+  const fail = (text) => {
+    throw new TablefactsError(label ? `${label}: ${text}` : text, 'EFAILED')
+  }
+  if (!ok) fail(`HTTP ${status}`)
+  const type = contentType ?? ''
+  if (!type.startsWith('image/')) fail(type ? `not an image (${type})` : 'not an image')
+  if (minBytes > 0 && (bytes?.length ?? 0) < minBytes) fail('too small')
+}
+
+/** Writes the bytes to `file`, creating its folder first. */
+export async function writeImage(file, bytes) {
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, bytes)
+}

package/src/lib/log.mjs

@@ -0,0 +1,17 @@
+// One logger contract for every tool: log(message, level = 'info'), level is 'info' | 'warn' | 'error'.
+
+export const noopLog = () => {}
+
+/** For CLIs: info goes to stdout, warn and error to stderr. */
+export const consoleLog = (message, level = 'info') => {
+  if (level === 'info') console.log(message)
+  else console.error(message)
+}
+
+/** Always returns a function that is called as log(message, level); tolerates a missing log or one that takes one argument. */
+export function normalizeLog(log) {
+  if (typeof log !== 'function') return noopLog
+  return (message, level = 'info') => {
+    log(message, level)
+  }
+}

package/src/lib/photos.mjs

@@ -0,0 +1,42 @@
+// Scaffolding shared by the photo tools (Instagram, TripAdvisor).
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { exists } from './files.mjs'
+import { resolveIn } from './project.mjs'
+
+export const DELAY_MS = 2500
+
+/** { saved, skipped, failed: [{ item, reason }], found? } where `found` ([{ name, url }]) exists only in a dry run. */
+export function newSummary({ dryRun = false } = {}) {
+  const summary = { saved: 0, skipped: 0, failed: [] }
+  if (dryRun) summary.found = []
+  return summary
+}
+
+/** Resolves the output folder and creates it (not in a dry run), plus <out>/_debug when `debug`. */
+export async function prepareOut({ out, dryRun = false, debug = false, projectDir } = {}) {
+  const outDir = resolveIn(projectDir, out)
+  if (!dryRun) await mkdir(outDir, { recursive: true })
+  const debugDir = debug ? join(outDir, '_debug') : null
+  if (debugDir) await mkdir(debugDir, { recursive: true })
+  return { outDir, debugDir }
+}
+
+/**
+ * Dry run: records { name, url } in summary.found. File already there: counts it as skipped.
+ * Otherwise awaits `save({ file, name, url })` and counts it as saved. A save error is not caught.
+ */
+export async function storeFile({ outDir, name, url, dryRun, summary, log, save }) {
+  const file = join(outDir, name)
+  if (dryRun) {
+    summary.found.push({ name, url })
+    log(`  ${name} <- ${url}`)
+  } else if (await exists(file)) {
+    summary.skipped++
+    log(`  ${name} already there`)
+  } else {
+    await save({ file, name, url })
+    summary.saved++
+    log(`  ${name} saved`)
+  }
+}

package/src/lib/playwright.mjs

@@ -0,0 +1,13 @@
+// Playwright is an optional peer dependency: only the browser tools need it, so it loads on use.
+import { TablefactsError } from './errors.mjs'
+
+export async function loadPlaywright() {
+  try {
+    return await import('playwright')
+  } catch (error) {
+    if (error?.code === 'ERR_MODULE_NOT_FOUND' && /playwright/.test(error.message ?? '')) {
+      throw new TablefactsError('playwright is not installed. The browser tools need it. Install it with: npm install playwright', 'EDEPENDENCY', { cause: error })
+    }
+    throw error
+  }
+}

package/src/lib/project.mjs

@@ -0,0 +1,42 @@
+// Where a tool looks for the project it works on and where it keeps its own files.
+// The project is the folder the command is run in (or TABLEFACTS_PROJECT), never the folder this
+// library is installed in, so one copy of tablefacts serves every template. A library caller can
+// pass a `projectDir` instead.
+import { isAbsolute, join, resolve } from 'node:path'
+
+/**
+ * `dir` when given, else TABLEFACTS_PROJECT, else the current folder.
+ * @param {string} [dir]
+ * @returns {string}
+ */
+export const projectRoot = (dir) => resolve(dir ?? process.env.TABLEFACTS_PROJECT ?? process.cwd())
+
+/**
+ * A path under <root>/.tablefacts, where output, caches and browser profiles go (git-ignore it).
+ * @param {string | undefined} root project folder (see projectRoot)
+ * @param {...string} parts
+ * @returns {string}
+ */
+export const workDirIn = (root, ...parts) => join(projectRoot(root), '.tablefacts', ...parts)
+
+/**
+ * A path under <project>/.tablefacts for the project in TABLEFACTS_PROJECT or the current folder.
+ * @param {...string} parts
+ * @returns {string}
+ */
+export const workDir = (...parts) => workDirIn(undefined, ...parts)
+
+/**
+ * The env files read, first one wins: <root>/.env, then <root>/data/.env (older templates).
+ * @param {string} [root] project folder (see projectRoot)
+ * @returns {string[]}
+ */
+export const envFiles = (root) => [join(projectRoot(root), '.env'), join(projectRoot(root), 'data', '.env')]
+
+/**
+ * An absolute path: relative paths resolve against the project (`projectDir`) when given, else the current folder.
+ * @param {string | undefined} projectDir
+ * @param {string} path
+ * @returns {string}
+ */
+export const resolveIn = (projectDir, path) => (isAbsolute(path) ? path : resolve(projectDir ? projectRoot(projectDir) : process.cwd(), path))

package/src/lib/text.mjs

@@ -0,0 +1,7 @@
+// Text helpers shared by the research and menu tools.
+
+/** Lowercase and accent-free, to compare names typed by different people. */
+export const fold = (s) => String(s ?? "").normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase();
+
+/** "Café Ñandú & Co." to "cafe-nandu-co" (empty when nothing letter-like is left). */
+export const slugify = (s) => fold(s).replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");

package/src/lib/types.mjs

@@ -0,0 +1,247 @@
+// Shared type definitions of the public API. This module exports nothing at runtime; it exists so
+// the generated declarations (types/lib/types.d.ts) hold the option and result shapes.
+
+/**
+ * Progress callback. `level` is 'info' by default; 'warn' for problems the run goes on from,
+ * 'error' for failures. Every tool is silent unless given one.
+ * @typedef {(message: string, level?: 'info' | 'warn' | 'error') => void} Log
+ */
+
+/**
+ * An environment object such as process.env.
+ * @typedef {Record<string, string | undefined>} Env
+ */
+
+/**
+ * @typedef {object} ResearchOptions
+ * @property {string} name Restaurant name. Required.
+ * @property {string} [location] "City, Country".
+ * @property {string} [country] ISO country code, narrows the search (CO, MX, US...).
+ * @property {string} [website]
+ * @property {string} [instagram] Handle or URL.
+ * @property {string} [tripadvisor] TripAdvisor page URL.
+ * @property {string} [linktree] Linktree or other link-in-bio page.
+ * @property {number} [photos] Also download up to n Google and n website photos (reference only).
+ * @property {boolean} [render] Render the website with Playwright (sites built in JavaScript).
+ * @property {boolean} [google] Set false to skip Google even if a key is available. Default true.
+ * @property {string} [googleKey] Default: env.GOOGLE_PLACES_API_KEY.
+ * @property {Env} [env] Environment the keys are read from. Default process.env.
+ * @property {string} [out] Output folder; relative paths resolve against projectDir. Default <project>/.tablefacts/research/<slug>.
+ * @property {string} [projectDir] Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+ * @property {Log} [log]
+ */
+
+/**
+ * @typedef {object} ResearchPhoto
+ * @property {string} file File name inside <outDir>/photos.
+ * @property {string} source Where it was downloaded from.
+ * @property {string} [alt]
+ */
+
+/**
+ * @typedef {object} ResearchProfile
+ * @property {Record<string, any>} fields Each field carries value, source and confidence.
+ * @property {string[]} [warnings]
+ */
+
+/**
+ * @typedef {object} ResearchResult
+ * @property {ResearchProfile} profile The merged profile.
+ * @property {string[]} notes What each source found or failed to find.
+ * @property {ResearchPhoto[]} photos
+ * @property {string} outDir Absolute output folder.
+ * @property {{ profile: string, report: string, setupAnswers: string }} files Absolute paths of the written files.
+ */
+
+/**
+ * @typedef {object} PhotoFailure
+ * @property {string} item The post, profile or page that failed.
+ * @property {string} reason
+ */
+
+/**
+ * @typedef {object} PhotoSummary
+ * @property {number} saved
+ * @property {number} skipped Files that were already there.
+ * @property {PhotoFailure[]} failed
+ * @property {{ name: string, url: string }[]} [found] Only present when dryRun is true.
+ */
+
+/**
+ * At least one of `links`, `file` or `profile` is required.
+ * @typedef {object} InstagramOptions
+ * @property {string[]} [links] Post links.
+ * @property {string} [file] Text file with one link per line (resolved against projectDir).
+ * @property {string} out Folder the images are saved to (resolved against projectDir). Required.
+ * @property {string} [profile] Profile link or handle (with or without the at sign): download a whole profile (videos skipped).
+ * @property {number | 'all'} [pages] With `profile`, batches of posts to load. Default 1.
+ * @property {string} [cdp] Edge debugging address, e.g. http://localhost:9222. Started if nothing listens.
+ * @property {string} [edgeDir] Profile folder for the Edge that is started.
+ * @property {boolean} [viaGoogle] Reach toolzu through a Google search (CLI: --google). Default false.
+ * @property {string} [browser] Installed browser channel: 'msedge' or 'chrome'.
+ * @property {string} [userDataDir] Persistent browser profile (resolved against projectDir).
+ * @property {string} [projectDir] Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+ * @property {boolean} [headed] Show the browser window.
+ * @property {boolean} [dryRun] List what would be saved without saving.
+ * @property {boolean} [debug] Keep screenshots in <out>/_debug.
+ * @property {Log} [log]
+ */
+
+/**
+ * @typedef {object} TripadvisorOptions
+ * @property {string[]} links Restaurant page links. At least one valid link is required.
+ * @property {string} out Folder the images are saved to (resolved against projectDir). Required.
+ * @property {string} [cdp] Edge debugging address. Default http://localhost:9222.
+ * @property {string} [edgeDir] Profile folder for the Edge that is started.
+ * @property {number} [max] Stop after n photos per restaurant.
+ * @property {string} [projectDir] Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+ * @property {boolean} [dryRun]
+ * @property {boolean} [debug]
+ * @property {Log} [log]
+ */
+
+/**
+ * @typedef {object} MenuProduct
+ * @property {string} name
+ * @property {string | null} [description]
+ * @property {number} price Finite and not negative.
+ * @property {string} currency ISO 4217 code, e.g. COP.
+ * @property {string | null} [image_url] An https URL.
+ * @property {boolean} [recommended]
+ */
+
+/**
+ * @typedef {object} MenuSection
+ * @property {string} name
+ * @property {MenuProduct[]} products
+ */
+
+/**
+ * @typedef {object} MenuCategory
+ * @property {string} slug The key the site's dictionaries use.
+ * @property {string} name
+ * @property {MenuSection[]} sections
+ */
+
+/** @typedef {MenuCategory[]} Menu */
+
+/**
+ * @typedef {object} MenuTotals
+ * @property {number} categories
+ * @property {number} sections
+ * @property {number} products
+ * @property {number} withImage
+ */
+
+/**
+ * @typedef {object} ImportOptions
+ * @property {boolean} [dryRun] Check and report, write nothing.
+ * @property {string} [json] Also save the extracted menu as JSON at this path (resolved against projectDir).
+ * @property {boolean} [replaceAll] Replace the whole menu, not only the categories in this import.
+ * @property {boolean} [force] Write even if the import has far fewer products than it replaces.
+ * @property {string} [databaseUrl] Default: env.SUPABASE_DB_URL.
+ * @property {Env} [env] Environment the database URL and keys are read from. Default process.env.
+ * @property {string} [projectDir] Project folder. Default: TABLEFACTS_PROJECT or the current folder.
+ * @property {Log} [log]
+ */
+
+/**
+ * @typedef {object} ImportResult
+ * @property {MenuTotals} totals
+ * @property {string[]} notes
+ * @property {boolean} written
+ * @property {boolean} dryRun
+ * @property {{ label: string, current: { categories: number, products: number, kept: string[] } } | null} database Null when the database was not reached.
+ */
+
+/**
+ * @typedef {ImportOptions & { menu: Menu, notes?: string[], title?: string }} ImportMenuOptions
+ */
+
+/**
+ * Restaurant-specific part of the Cluvi source (src/menu/cluvi/config.mjs).
+ * @typedef {object} CluviConfig
+ * @property {string} [url] Any page of the restaurant's Cluvi menu.
+ * @property {{ slug: string, name: string, from: string[] }[]} [categories] Cluvi main categories folded into each site category.
+ * @property {Record<string, string>} [sections] Cluvi subcategory to section name.
+ */
+
+/**
+ * Restaurant-specific part of the picture-menu source (src/menu/raw/config.mjs).
+ * @typedef {object} RawConfig
+ * @property {string} [url] Page with the menu pictures, or a direct image URL.
+ * @property {string} currency ISO code of the prices.
+ * @property {string} [thousands] Thousands separator the menu prints. Default ".".
+ * @property {string} [decimal] Decimal separator the menu prints. Default ",".
+ * @property {number} [scale] Multiplies every price. Default 1.
+ * @property {{ slug: string, name: string, groups?: ('food' | 'drink')[] }[]} [categories] Category that lists each group.
+ * @property {Record<string, string>} [placeIn] Section title to category slug.
+ * @property {Record<string, string>} [sections] Section title to the name stored.
+ * @property {string[]} [skipSections] Section titles to leave out.
+ */
+
+/** @typedef {CluviConfig | RawConfig} MenuSourceConfig */
+
+/**
+ * @typedef {object} CluviMenuOptions
+ * @property {string} [url] Default: the config's.
+ * @property {'on_table' | 'delivery' | 'take_away'} [service]
+ * @property {string} [lang]
+ * @property {CluviConfig} [config] Default: the cluvi config.mjs.
+ */
+
+/** @typedef {ImportOptions & CluviMenuOptions} ImportCluviOptions */
+
+/**
+ * @typedef {object} ImageMenuReadOptions
+ * @property {string[]} [urls] Pages or image URLs. Default: the config's url.
+ * @property {string | number[]} [only] Pages to read, e.g. '1,3-5' or [1, 3, 4, 5].
+ * @property {string} [provider] Vision provider, see `providers`. Default MENU_VISION_PROVIDER or `defaultProvider`.
+ * @property {string} [model]
+ * @property {number} [minWidth] Ignore images declaring a smaller width. Default 500.
+ * @property {string} [apiKey] Default: the provider's key in env.
+ * @property {boolean} [refresh] Read the pages again instead of using the saved transcriptions.
+ * @property {RawConfig} [config] Default: the raw config.mjs.
+ */
+
+/** @typedef {ImportOptions & ImageMenuReadOptions} ImportImageMenuOptions */
+
+/**
+ * @typedef {object} ListMenuImagesOptions
+ * @property {string[]} [urls]
+ * @property {string | number[]} [only]
+ * @property {number} [minWidth]
+ * @property {RawConfig} [config]
+ */
+
+/**
+ * @typedef {object} MenuImage
+ * @property {number} number Position as the CLI's --list numbers it.
+ * @property {string} url
+ * @property {string} alt
+ */
+
+/**
+ * @typedef {object} PriceFormat
+ * @property {string} [thousands] Default ".".
+ * @property {string} [decimal] Default ",".
+ * @property {number} [scale] Default 1.
+ */
+
+/**
+ * @typedef {object} VisionProvider
+ * @property {string} label
+ * @property {string} keyName Environment variable holding the API key.
+ * @property {string} defaultModel
+ */
+
+/**
+ * @typedef {object} LoadEnvOptions
+ * @property {string} [projectDir] Project folder whose .env files are read.
+ * @property {string[]} [files] Exactly these files instead of the project's.
+ * @property {Env} [env] Object the variables are set on. Default process.env.
+ */
+
+/** @typedef {'EUSAGE' | 'ECONFIG' | 'EDEPENDENCY' | 'EFAILED'} TablefactsErrorCode */
+
+export {}

package/src/menu/README.md

@@ -0,0 +1,97 @@
+# Menu import
+
+Scripts that read a restaurant's menu from the website that hosts it and write it into the Supabase menu tables the site reads (`menu_categories`, `menu_sections`, `menu_products`; the Cannario templates ship them as `supabase/migrations/0001_menu.sql`, and the columns written are listed in the [main README](../../README.md#supabase-tables)). One folder per source:
+
+| Source | Folder | Status |
+| --- | --- | --- |
+| Cluvi (`<restaurant>.cluvi.co`) | `cluvi/` | working |
+| Menu that is only pictures (one image per page) | `raw/` | working, API calls untested |
+
+The same code is available as functions: `importCluvi`, `importImageMenu`, `listMenuImages` and `importMenu` (see the [main README](../../README.md#use-it-as-a-library)). Each source's `config.mjs` can be replaced with the `config` option, so a script can import a menu without editing the package:
+
+```js
+import { importCluvi, listMenuImages } from 'tablefacts'
+
+await importCluvi({
+  url: 'https://gaucho.cluvi.co/gaucho/maincategories',
+  config: { categories: [{ slug: 'cocina', name: 'Comida', from: ['Entradas', 'Fuertes'] }], sections: {} },
+  env: { SUPABASE_DB_URL: process.env.MY_DB_URL },   // keys are read from `env` (default process.env)
+  dryRun: true,
+  log: (message, level) => console.log(level ?? 'info', message),
+})
+const pictures = await listMenuImages({ urls: ['https://example.com/carta'], config: { currency: 'COP' } })
+```
+
+- **Cluvi `config`**: `{ url?, categories: [{ slug, name, from[] }], sections: { 'Cluvi subcategory': 'SECTION NAME' } }`.
+- **Picture `config`**: `{ url?, currency, thousands, decimal, scale, categories: [{ slug, name, groups: ['food' | 'drink'] }], placeIn, sections, skipSections }`. `currency` is required.
+- **Options every import takes**: `dryRun`, `json` (relative paths resolve against `projectDir`), `replaceAll`, `force`, `databaseUrl` (default `env.SUPABASE_DB_URL`), `env`, `projectDir` and `log(message, level)` (`'info'`, `'warn'` for notes, `'error'`).
+- **Result**: `{ totals, notes, written, dryRun, database }`; `database` is `{ label, current: { categories, products, kept } }` once the database was inspected, and `null` when it was not reached (a dry run without a URL).
+- **Errors** are `TablefactsError`: `ECONFIG` (no URL, unknown provider, no key, bad currency), `EFAILED` (invalid menu, no products, import refused without `force`), `EUSAGE` (bad `only`). `err.option` names the option; the CLI shows the flag (`--force`, `--only`) and exits `2` for `EUSAGE`, `1` otherwise.
+
+## Setup
+
+1. Install the package in the project (`npm install --save-dev tablefacts`); it brings `pg`. Run the commands from the project's folder.
+2. Apply the migration to your Supabase project.
+3. `cp .env.example .env` and set `SUPABASE_DB_URL` to the pooler URL from the Supabase dashboard (Connect > Transaction pooler), with the real password.
+
+`SUPABASE_DB_URL` bypasses row level security. It stays in `.env` (git-ignored). Never copy it into a browser-exposed variable (such as `NEXT_PUBLIC_*`): the site only uses the publishable key.
+
+## Run (Cluvi)
+
+```bash
+tablefacts menu cluvi --dry-run        # extract and check, show what would change, write nothing
+tablefacts menu cluvi                     # replace the menu in Supabase
+tablefacts menu cluvi <menu-url>       # another restaurant
+tablefacts menu cluvi --help
+```
+
+Edit `cluvi/config.mjs` first: the menu URL, how Cluvi's main categories fold into the site's categories, and section renames. The run prints what the site still needs (dictionary keys, `content/qr.ts`).
+
+## Run (menu that is only pictures)
+
+For a restaurant whose site shows the menu as a gallery of page images, such as <https://www.mombasa.co/carta-restaurante-espanol/>. Each page is transcribed by a vision model from one of three providers, so it needs that provider's key in `.env`:
+
+| `--provider` | Key in `.env` | Default `--model` |
+| --- | --- | --- |
+| `anthropic` (default) | `ANTHROPIC_API_KEY` | `claude-sonnet-5-5` |
+| `gemini` | `GEMINI_API_KEY` | `gemini-3.8-flash` |
+| `groq` | `GROQ_API_KEY` | `qwen/qwen3.8-27b` |
+
+Choose the provider per run with `--provider`, or once for every run with `MENU_VISION_PROVIDER` in `.env`.
+
+```bash
+tablefacts menu raw --list                 # show the pictures found; no key needed, nothing read or written
+tablefacts menu raw --dry-run              # read the pages, show the menu and the checks, write nothing
+tablefacts menu raw --only 3,9 --dry-run   # try two pages first
+tablefacts menu raw --provider gemini --dry-run   # the same, read by Gemini
+tablefacts menu raw                           # replace the menu in Supabase
+tablefacts menu raw <page-or-image-url>... # another restaurant
+```
+
+Edit `raw/config.mjs` first: the URL, the currency, how the menu prints prices (`$95.000` is `thousands: "."`, `decimal: ","`) and which category each section goes to.
+
+- `raw/source.mjs` takes the large JPG/PNG/WebP images of the page in document order (full size, not the thumbnails; logos and icons are skipped by width) and downloads them. A site that builds its gallery with JavaScript shows up as "no images": pass the image URLs instead.
+- `raw/vision.mjs` has the model transcribe each page into sections and dishes with one request: a forced tool call for Anthropic, JSON held to the same schema for Gemini (`generateContent`) and Groq (strict structured output), so every provider hands back the same shape. Prices come back as printed text and `raw/normalize.mjs` parses them, so a thousands separator is never guessed by the model. Adding a provider is one more entry in `providers` there.
+- Groq serves a single vision model, `qwen/qwen3.8-27b`, and it is a preview one: if Groq retires it, pass its successor with `--model`.
+- Rate limits (HTTP 429) are retried after the wait the service asks for, up to a minute; for a longer wait the run stops with the service's message. Pages already read are saved (below), so run it again later.
+- The model tags each section food, drink or other; `config.categories` maps those to the site's categories. A section with no heading continues the one before it, even across pages. A dish with several price columns (bottle and glass) becomes one product per column, "Name (Botella)".
+- Each page's transcription is saved in `<project>/.tablefacts/cache/<host>/<id>.json` (git-ignored) and reused on the next run, so re-running costs nothing. Edit a file there to fix a misread page; `--refresh` reads everything again. The saved pages are shared by all providers, so after switching provider or model, add `--refresh` or the pages already read are reused.
+- **Read the dry run against the pictures before writing.** The model can misread small print, and a wrong price is worse than a missing dish. Pages it was unsure of are listed in the notes. There are no dish photos, so `image_url` is empty.
+
+## What it does (Cluvi)
+
+- Cluvi main category > site category, subcategory > section (name in UPPERCASE), product > product. Products keep the order Cluvi shows (its `order` field). Cluvi's "important" flag is `recommended`. Descriptions are converted from HTML to text.
+- The write is one transaction. By default only the categories in the import are replaced (their sections and products with them), so re-running never duplicates. `--replace-all` replaces the whole menu, which also removes the template's sample categories.
+- It refuses an import with no products, or with under half the products it replaces (`--force` overrides), so a broken extraction cannot empty the menu.
+- Photos stay on Cluvi's CDN: `image_url` holds the Cluvi URL, and your site must allow `images.cluvi.com` and `images-mini.cluvi.com` as image hosts (a template with `menuImageHosts` in `frontend/src/content/site.ts` gets a warning from the run when they are missing). If the restaurant leaves Cluvi, the photos must be re-hosted (Supabase Storage needs a different credential than the DB URL).
+
+## Known limits
+
+- Cluvi has no public API. `cluvi/source.mjs` calls the two JSON endpoints its web app calls; if they change, that file is the one to fix.
+- Products with options (add-ons, sizes) import their base price only. Products Cluvi hides the price of (price 0) import as 0 and the site shows 0.
+- The Supabase pooler's certificate is not trusted by Node, so the connection is encrypted but the certificate is not verified unless `sslmode` is in the URL.
+- Dish names and descriptions are not translated, as elsewhere in the site.
+
+## Adding a source
+
+Create `src/menu/<source>/` with a script that calls `runImport` from `lib/run.mjs` and returns the menu in the shape described in `lib/menu.mjs`. The flags, checks and the database write are shared. If the source's photos stay on its own CDN, allow that host in your site's image settings.