continente-mcp 3.1.0

package/.env.example

@@ -0,0 +1,19 @@
+# continente-mcp environment variables
+# Copy this to .env or set in your shell / launchd / systemd unit.
+
+# Path where cookies are stored (default: ~/.continente/cookies.json)
+# CONTINENTE_COOKIES_PATH=~/.continente/cookies.json
+
+# If you run the MCP server on a second machine and sync cookies via a shared
+# folder (e.g. Obsidian vault, Syncthing, Dropbox), set this to the shared path
+# on the machine that runs the cookie reader. The reader will write cookies to
+# both the default path and this one whenever it runs.
+# CONTINENTE_VAULT_COOKIE_PATH=/path/to/shared/folder/cookies.json
+
+# Override the state directory (preferences, fingerprint, backups)
+# CONTINENTE_STATE_DIR=~/.continente
+
+# Webhook URL to notify when the website structure changes (check-change.js).
+# Supports anything that accepts a POST with { "text": "..." } — Slack, Discord,
+# n8n, Make, etc. If not set, changes are logged to stdout only.
+# CONTINENTE_ALERT_WEBHOOK=https://hooks.slack.com/services/...

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Marques
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# continente-mcp
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for [Continente.pt](https://www.continente.pt) — Portugal's largest supermarket chain.
+
+Lets your AI assistant search products, manage your shopping cart, and browse order history using your real Continente account.
+
+> **⚠️ Stability note:** This server works by automating a real browser session against Continente's website using CSS selectors. If Continente updates their site structure, some tools may break. See [Detecting changes](#detecting-changes).
+
+---
+
+## What it can do
+
+| Tool | Description |
+|------|-------------|
+| `search_products` | Search the catalogue — results ranked by your favourites |
+| `get_favorites` | List your saved favourite products |
+| `refresh_favorites` | Re-sync favourites from the website |
+| `get_cart` | View your current basket |
+| `add_to_cart` | Add a product by ID |
+| `get_order_history` | Recent orders with product lines |
+| `get_most_bought` | Products you order most often (scans all orders — slow) |
+| `close_session` | Close the browser and free memory |
+
+---
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) 18 or later
+- [Python](https://www.python.org/) 3.10+ (for the cookie export script)
+- A Continente.pt account, logged in on one of the [supported browsers](#supported-browsers)
+
+---
+
+## Setup
+
+### 1. Clone and install
+
+The setup requires the repository — the Python cookie scripts live here and are needed before the server can authenticate.
+
+```bash
+git clone https://github.com/davidmarqu3s/continente-mcp
+cd continente-mcp
+npm install
+```
+
+Install the Chromium browser that Playwright uses internally:
+
+```bash
+npm run setup
+# or: npx playwright install chromium --with-deps
+```
+
+> **Linux note:** `--with-deps` installs OS-level dependencies via apt. On macOS and Windows this flag is a no-op — `npx playwright install chromium` is sufficient.
+
+Once set up, you can run the server either via the local clone or via `npx continente-mcp` — both work in your MCP client config (see [step 3](#3-configure-your-mcp-client)).
+
+### 2. Export your cookies
+
+The server authenticates using cookies from your existing browser session — no password handling, no OAuth flow. You need to be **logged into Continente.pt** in your browser first.
+
+Install the cookie reader dependencies:
+
+```bash
+python3 -m pip install browser-cookie3 requests   # macOS / Linux
+python  -m pip install browser-cookie3 requests   # Windows
+```
+
+Export your cookies:
+
+```bash
+python3 continente-cookie-reader.py   # macOS / Linux
+python  continente-cookie-reader.py   # Windows
+# Auto-detecting browser with Continente cookies...
+# Found 20 cookies in chrome.
+# Saved 20 cookies → ~/.continente/cookies.json  (browser: chrome)
+# On Windows: %USERPROFILE%\.continente\cookies.json
+```
+
+To specify a browser explicitly:
+
+```bash
+python3 continente-cookie-reader.py --browser firefox
+python3 continente-cookie-reader.py --list-browsers   # see all supported browsers
+```
+
+Cookies are saved to `~/.continente/cookies.json` (`%USERPROFILE%\.continente\cookies.json` on Windows) with owner-only read permissions.
+
+### 3. Configure your MCP client
+
+This server works with any [MCP-compatible client](https://modelcontextprotocol.io/clients). The config format is the same across most of them — add an entry under `mcpServers` pointing to the server command.
+
+**Via npx (no local install needed):**
+
+```json
+{
+  "mcpServers": {
+    "continente": {
+      "command": "npx",
+      "args": ["continente-mcp"]
+    }
+  }
+}
+```
+
+**Via local clone:**
+
+```json
+{
+  "mcpServers": {
+    "continente": {
+      "command": "node",
+      "args": ["/path/to/continente-mcp/src/index.js"]
+    }
+  }
+}
+```
+
+Where to put this config:
+
+| Client | Config file |
+|--------|-------------|
+| Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor (Mac/Linux) | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally |
+| Cursor (Windows) | `.cursor\mcp.json` in your project, or `%USERPROFILE%\.cursor\mcp.json` globally |
+| Windsurf (Mac/Linux) | `~/.codeium/windsurf/mcp_config.json` |
+| Windsurf (Windows) | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
+| Other clients | See your client's MCP documentation |
+
+---
+
+## Keeping the session alive
+
+Continente sessions expire after a period of inactivity. Run the keepalive script on a schedule to prevent this:
+
+**macOS (launchd), every 20 minutes:**
+
+Create `~/Library/LaunchAgents/com.continente.keepalive.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.continente.keepalive</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/bin/python3</string>
+    <string>/path/to/continente-keepalive.py</string>
+  </array>
+  <key>StartInterval</key>
+  <integer>1200</integer>
+  <key>StandardOutPath</key>
+  <string>/tmp/continente-keepalive.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/continente-keepalive.log</string>
+</dict>
+</plist>
+```
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.continente.keepalive.plist
+```
+
+**Linux / WSL (cron):**
+
+```bash
+crontab -e
+# Add:
+*/20 * * * * python3 /path/to/continente-keepalive.py >> ~/.continente/keepalive.log 2>&1
+```
+
+**Windows (Task Scheduler):**
+
+```powershell
+schtasks /create /tn "ContinenteKeepalive" /tr "python C:\path\to\continente-keepalive.py" /sc minute /mo 20 /f
+```
+
+Or open Task Scheduler and create a task that runs `python C:\path\to\continente-keepalive.py` every 20 minutes.
+
+If the session expires, the keepalive script will automatically re-read cookies from your browser.
+
+---
+
+## Security
+
+- **Cookies give full account access** — they can view your address, manage your cart, and see your order history. Treat them like a password.
+- **macOS / Linux:** Cookies are stored at `~/.continente/cookies.json` with owner-only read permissions (`chmod 600`).
+- **Windows:** Cookies are stored at `%USERPROFILE%\.continente\cookies.json`. To restrict access: `icacls "%USERPROFILE%\.continente\cookies.json" /inheritance:r /grant:r "%USERNAME%:R"`
+- This path is excluded from git via `.gitignore`. Never commit it.
+- Cookies expire roughly every 30 days. Re-run `continente-cookie-reader.py` to refresh them.
+
+---
+
+## Detecting changes
+
+Run `check-change.js` on a schedule to get notified if Continente updates their site structure in a way that might break scraping:
+
+```bash
+# First run saves a structural fingerprint
+node check-change.js
+```
+
+**Linux / WSL (cron):**
+```bash
+# Daily at 9am
+0 9 * * * node /path/to/check-change.js >> ~/.continente/change-detector.log 2>&1
+```
+
+**macOS (launchd):** Add a plist similar to the keepalive one above, with `StartInterval` set to `86400`.
+
+**Windows (Task Scheduler):**
+```powershell
+schtasks /create /tn "ContinenteChangeDetector" /tr "node C:\path\to\check-change.js" /sc daily /st 09:00 /f
+```
+
+To receive a webhook notification (Slack, Discord, n8n, etc.) on change, set `CONTINENTE_ALERT_WEBHOOK` in your environment or MCP client config:
+
+```bash
+# macOS / Linux
+export CONTINENTE_ALERT_WEBHOOK=https://hooks.slack.com/services/...
+
+# Windows cmd
+set CONTINENTE_ALERT_WEBHOOK=https://hooks.slack.com/services/...
+
+# Windows PowerShell
+$env:CONTINENTE_ALERT_WEBHOOK = "https://hooks.slack.com/services/..."
+```
+
+Or add it to your MCP client config under `env` (platform-neutral):
+
+```json
+{
+  "mcpServers": {
+    "continente": {
+      "command": "npx",
+      "args": ["continente-mcp"],
+      "env": {
+        "CONTINENTE_ALERT_WEBHOOK": "https://hooks.slack.com/services/..."
+      }
+    }
+  }
+}
+```
+
+---
+
+## Utilities
+
+**Back up order history** (incremental — only fetches new orders):
+
+```bash
+node continente-backup.js
+# → ~/.continente/orders-backup.json
+# → %USERPROFILE%\.continente\orders-backup.json  (Windows)
+```
+
+---
+
+## Supported browsers
+
+`continente-cookie-reader.py` can read cookies from:
+
+| Browser | macOS | Windows | Linux |
+|---------|-------|---------|-------|
+| Chrome | ✓ | ✓ | ✓ |
+| Edge | ✓ | ✓ | ✓ |
+| Brave | ✓ | ✓ | ✓ |
+| Firefox | ✓ | ✓ | ✓ |
+| Arc | ✓ | — | — |
+| Chromium | ✓ | ✓ | ✓ |
+| Vivaldi | ✓ | ✓ | ✓ |
+| Opera | ✓ | ✓ | ✓ |
+| Safari | ✓ | — | — |
+
+Powered by [browser-cookie3](https://github.com/borisbabic/browser_cookie3).
+
+---
+
+## Environment variables
+
+See [`.env.example`](./.env.example) for all options. The main ones:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTINENTE_COOKIES_PATH` | `~/.continente/cookies.json` | Where cookies are read/written |
+| `CONTINENTE_STATE_DIR` | `~/.continente` | Directory for preferences, fingerprint, backups |
+| `CONTINENTE_ALERT_WEBHOOK` | — | Webhook URL for change detection alerts |
+| `CONTINENTE_VAULT_COOKIE_PATH` | — | Optional secondary path to also write cookies to (for multi-machine sync) |
+
+> **Windows:** Replace `~` with `%USERPROFILE%` (cmd) or `$env:USERPROFILE` (PowerShell). Node.js accepts both `/` and `\` as path separators.
+
+---
+
+## Skills
+
+The [`skills/`](./skills/) directory contains ready-made agent skills for clients that support them (e.g. Claude Code).
+
+### groceries
+
+Adds items to the basket by name. Matches against your favourites and order history to pick the right product variant automatically.
+
+Install it in Claude Code:
+
+```bash
+# From the repo root
+claude skill install skills/groceries
+```
+
+Then use it:
+
+```
+/groceries queijo flamengo, leite mimosa, ovos
+```
+
+Or naturally: *"add some manteiga and pão de forma to my Continente cart"*
+
+See [`skills/groceries/SKILL.md`](./skills/groceries/SKILL.md) for full details.
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/check-change.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Continente Change Detector
+ *
+ * Checks whether the website structure has changed in a way that might break
+ * the MCP server's scrapers. Run daily via cron.
+ *
+ * Usage:
+ *   node check-change.js
+ *
+ * On first run it saves a baseline fingerprint. Subsequent runs compare against
+ * it and log a warning if the structure changed significantly.
+ *
+ * To receive a webhook notification on change, set:
+ *   CONTINENTE_ALERT_WEBHOOK=https://hooks.slack.com/...
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { chromium } from 'playwright';
+import * as cheerio from 'cheerio';
+import os from 'os';
+
+const CONTINENTE_SEARCH  = 'https://www.continente.pt/pesquisa/?q=leite';
+const STATE_DIR          = `${os.homedir()}/.continente`;
+const FINGERPRINT_FILE   = `${STATE_DIR}/fingerprint.json`;
+const LAST_ALERT_FILE    = `${STATE_DIR}/last_change_alert.txt`;
+const COOKIE_FILE        = `${STATE_DIR}/cookies.json`;
+const WEBHOOK_URL        = process.env.CONTINENTE_ALERT_WEBHOOK || null;
+
+function getPlatformUserAgent() {
+  if (process.platform === 'win32') {
+    return 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36';
+  } else if (process.platform === 'linux') {
+    return 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36';
+  }
+  return 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36';
+}
+
+function extractFingerprint(html) {
+  const $ = cheerio.load(html);
+  $('script, style, noscript, iframe, svg').remove();
+
+  const counts = {
+    produtoLinks:  $('a[href*="/produto/"]').length,
+    priceElements: $('[class*="price"]').filter((i, el) => $(el).text().includes('€')).length,
+    forms:         $('form').length,
+    buttons:       $('button').length,
+    productCards:  $('[class*="product"], [class*="card"]').filter(
+      (i, el) => $(el).find('a[href*="/produto/"]').length > 0
+    ).length,
+  };
+
+  return {
+    ...counts,
+    hash:      createHash('sha256').update(JSON.stringify(counts)).digest('hex').substring(0, 12),
+    timestamp: new Date().toISOString(),
+  };
+}
+
+async function fetchHtml() {
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({ userAgent: getPlatformUserAgent() });
+
+  if (existsSync(COOKIE_FILE)) {
+    try {
+      const cookies = JSON.parse(readFileSync(COOKIE_FILE, 'utf8'));
+      if (cookies.length > 0) await context.addCookies(cookies);
+    } catch {}
+  }
+
+  const page = await context.newPage();
+  await page.goto(CONTINENTE_SEARCH, { waitUntil: 'domcontentloaded', timeout: 20000 });
+  await page.waitForTimeout(3000);
+
+  const html = await page.content();
+  await browser.close();
+  return html;
+}
+
+async function sendAlert(message) {
+  if (WEBHOOK_URL) {
+    // POST to webhook (works with Slack, Discord, n8n, etc.)
+    try {
+      const res = await fetch(WEBHOOK_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text: message }),
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      console.error('[ChangeDetector] Webhook notified.');
+    } catch (e) {
+      console.error(`[ChangeDetector] Webhook failed: ${e.message}`);
+    }
+  } else {
+    // No webhook configured — log prominently to stdout so cron picks it up
+    console.log('\n' + '='.repeat(60));
+    console.log('CONTINENTE STRUCTURE CHANGE DETECTED');
+    console.log('='.repeat(60));
+    console.log(message);
+    console.log('='.repeat(60) + '\n');
+  }
+}
+
+async function main() {
+  mkdirSync(STATE_DIR, { recursive: true });
+
+  console.error(`[ChangeDetector] Checking ${CONTINENTE_SEARCH}`);
+  const html    = await fetchHtml();
+  const current = extractFingerprint(html);
+
+  if (!existsSync(FINGERPRINT_FILE)) {
+    writeFileSync(FINGERPRINT_FILE, JSON.stringify({ baseline: current, savedAt: current.timestamp }, null, 2));
+    console.error(`[ChangeDetector] Baseline saved (${current.hash}). Run again tomorrow to start detecting changes.`);
+    return;
+  }
+
+  const { baseline } = JSON.parse(readFileSync(FINGERPRINT_FILE, 'utf8'));
+
+  if (baseline.hash === current.hash) {
+    console.error(`[ChangeDetector] Unchanged (${current.hash}). All good.`);
+    return;
+  }
+
+  const diffs = {};
+  for (const key of Object.keys(baseline)) {
+    if (key === 'hash' || key === 'timestamp') continue;
+    if (JSON.stringify(baseline[key]) !== JSON.stringify(current[key])) {
+      diffs[key] = { before: baseline[key], after: current[key] };
+    }
+  }
+
+  const diffSummary = Object.entries(diffs).map(([k, v]) => `${k}: ${v.before} → ${v.after}`).join(', ');
+  console.error(`[ChangeDetector] CHANGE DETECTED: ${diffSummary}`);
+
+  // Rate-limit: only alert once per 24 h
+  if (existsSync(LAST_ALERT_FILE)) {
+    const lastAlert = readFileSync(LAST_ALERT_FILE, 'utf8').trim();
+    const hoursSince = (Date.now() - new Date(lastAlert).getTime()) / 3_600_000;
+    if (hoursSince < 24) {
+      console.error(`[ChangeDetector] Alert suppressed (last sent ${hoursSince.toFixed(1)}h ago).`);
+      return;
+    }
+  }
+
+  const alertMsg =
+    `⚠️ Continente website structure changed — the MCP scraper may need updating.\n\n` +
+    `Baseline: ${baseline.hash}\n` +
+    `Current:  ${current.hash}\n` +
+    `Changes:  ${diffSummary}\n\n` +
+    `Check https://github.com/davidmarqu3s/continente-mcp for updates.`;
+
+  await sendAlert(alertMsg);
+  writeFileSync(LAST_ALERT_FILE, new Date().toISOString());
+}
+
+main().catch(e => { console.error('[ChangeDetector] Fatal:', e.message); process.exit(1); });

package/continente-backup.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * Continente Order Backup — incremental
+ *
+ * Checks for orders not yet in the backup, fetches their details,
+ * and appends them. Run daily via cron.
+ *
+ * Usage:
+ *   node continente-backup.js
+ *
+ * Output:
+ *   ~/.continente/orders-backup.json
+ */
+import { chromium } from 'playwright';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { normalizeCookies } from './src/utils.js';
+import os from 'os';
+
+const CONTINENTE_BASE = 'https://www.continente.pt';
+const STATE_DIR       = `${os.homedir()}/.continente`;
+const BACKUP_FILE     = `${STATE_DIR}/orders-backup.json`;
+const COOKIE_FILE     = `${STATE_DIR}/cookies.json`;
+
+const log = (...args) => console.error('[backup]', ...args);
+
+// ─── Cookie helpers ───────────────────────────────────────────────────────────
+
+function loadCookies() {
+  if (!existsSync(COOKIE_FILE)) {
+    log(`No cookies found at ${COOKIE_FILE}`);
+    log('Run: python3 continente-cookie-reader.py');
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(COOKIE_FILE, 'utf8'));
+  } catch (e) {
+    log('Failed to parse cookies:', e.message);
+    return null;
+  }
+}
+
+// ─── Scraping helpers ─────────────────────────────────────────────────────────
+
+async function getOrderLinks(page) {
+  await page.goto(`${CONTINENTE_BASE}/conta/encomendas/`, { waitUntil: 'networkidle', timeout: 30000 });
+  await page.waitForTimeout(3000);
+
+  if (page.url().includes('/login')) throw new Error('Not authenticated — cookies may have expired');
+
+  return page.evaluate(() => {
+    const seen = new Set();
+    return Array.from(document.querySelectorAll('a[href*="detalhe-encomenda"]'))
+      .map(a => a.href)
+      .filter(h => { if (seen.has(h)) return false; seen.add(h); return true; });
+  });
+}
+
+async function getOrderDetail(page, url) {
+  await page.goto(url, { waitUntil: 'networkidle', timeout: 20000 });
+  await page.waitForTimeout(2000);
+
+  return page.evaluate(() => {
+    const bodyText = document.body.innerText;
+    const orderNumMatch = bodyText.match(/Encomenda (\d{9}_\d{3})/);
+    const totalMatch    = bodyText.match(/Total Encomendado\s+([\d,.]+€)/);
+    const slotMatch     = bodyText.match(/(\d{1,2}:\d{2} - \d{1,2}:\d{2})/);
+    const dateMatch     = bodyText.match(/(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+\d{1,2},\s+\d{4}/i);
+
+    const products = [];
+    document.querySelectorAll('[class*="product-line"]').forEach(el => {
+      const qtyEl = el.querySelector('[class*="qty"], [class*="quantity"], [class*="amount"]');
+      if (!qtyEl) return;
+      const nameEl  = el.querySelector('[class*="product-name"], [class*="name"], a[href*="produto"]');
+      const rawName = (nameEl || el).textContent.trim();
+      const name    = rawName.split('\n')[0].trim();
+      const qtyMatch = qtyEl.textContent.trim().match(/^(\d+)/);
+      const qty     = qtyMatch ? parseInt(qtyMatch[1], 10) : 1;
+      const priceEl = el.querySelector('[class*="price"]');
+      const price   = priceEl ? priceEl.textContent.trim().split('\n')[0].trim() : null;
+      if (name && name.length > 3) products.push({ name, qty, price });
+    });
+
+    return {
+      orderNumber:  orderNumMatch ? orderNumMatch[1] : null,
+      date:         dateMatch     ? dateMatch[0]     : null,
+      total:        totalMatch    ? totalMatch[1]    : null,
+      deliverySlot: slotMatch     ? slotMatch[1]     : null,
+      productCount: products.length,
+      products,
+    };
+  });
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const cookies = loadCookies();
+  if (!cookies) process.exit(1);
+
+  // Load existing backup
+  let backup = { backedUpAt: null, orderCount: 0, orders: [] };
+  if (existsSync(BACKUP_FILE)) {
+    try { backup = JSON.parse(readFileSync(BACKUP_FILE, 'utf8')); } catch {}
+  }
+  const knownUrls = new Set(backup.orders.map(o => o.url).filter(Boolean));
+
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    userAgent: getPlatformUserAgent(),
+    locale: 'pt-PT',
+  });
+  await context.addCookies(normalizeCookies(cookies));
+  const page = await context.newPage();
+
+  let orderLinks;
+  try {
+    orderLinks = await getOrderLinks(page);
+  } catch (e) {
+    log('Failed to load orders page:', e.message);
+    await browser.close();
+    process.exit(1);
+  }
+
+  const newLinks = orderLinks.filter(l => !knownUrls.has(l));
+  log(`${orderLinks.length} orders on site, ${knownUrls.size} already backed up, ${newLinks.length} new`);
+
+  if (newLinks.length === 0) {
+    log('Nothing new to backup.');
+    await browser.close();
+    return;
+  }
+
+  const newOrders = [];
+  for (let i = 0; i < newLinks.length; i++) {
+    try {
+      const detail = await getOrderDetail(page, newLinks[i]);
+      detail.url = newLinks[i];
+      newOrders.push(detail);
+      log(`${i + 1}/${newLinks.length} — ${detail.orderNumber || '?'} (${detail.productCount} products)`);
+    } catch (e) {
+      log(`${i + 1}/${newLinks.length} FAILED: ${e.message}`);
+      newOrders.push({ url: newLinks[i], error: e.message });
+    }
+  }
+
+  backup.orders    = [...newOrders, ...backup.orders];
+  backup.orderCount = backup.orders.filter(o => !o.error).length;
+  backup.backedUpAt = new Date().toISOString();
+
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(BACKUP_FILE, JSON.stringify(backup, null, 2));
+  log(`Done — added ${newOrders.length} orders. Total: ${backup.orderCount} → ${BACKUP_FILE}`);
+
+  await browser.close();
+}
+
+function getPlatformUserAgent() {
+  if (process.platform === 'win32') {
+    return 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36';
+  } else if (process.platform === 'linux') {
+    return 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36';
+  }
+  return 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36';
+}
+
+main().catch(e => { log('Fatal:', e.message); process.exit(1); });