@commercelayer/agent-cli 0.5.2 → 0.8.0

package/dist/files.js

@@ -53,12 +53,14 @@ export function requireCredentials() {
     return c;
 }
 /** Make sure .gitignore lists the credentials file. Returns true if it changed. */
-export function ignoreCredentials() {
+export const ignoreCredentials = () => ignorePath(paths.credentials);
+/** Add a path to .gitignore unless it is there; whether it was added. */
+export function ignorePath(file) {
     const existing = fs.existsSync('.gitignore') ? fs.readFileSync('.gitignore', 'utf8') : '';
-    if (existing.split('\n').includes(paths.credentials))
+    if (existing.split('\n').includes(file))
         return false;
     const sep = existing && !existing.endsWith('\n') ? '\n' : '';
-    fs.appendFileSync('.gitignore', `${sep}${paths.credentials}\n`);
+    fs.appendFileSync('.gitignore', `${sep}${file}\n`);
     return true;
 }
 /** The note that sends a future agent in this repo to the skills. No skill names: it never goes stale. */

package/dist/inbox/cursor.js

@@ -0,0 +1,11 @@
+// What the inbox commands remember between runs, in .commercelayer/inbox.json (gitignored):
+// when the inbox was last listed, and the messages already pulled, by Message-ID (or by id
+// when a message has none), so inbox list marks only the others as new.
+import path from 'node:path';
+import { jsonCursor, MAX_SEEN, strings } from '../cursor.js';
+import { paths } from '../files.js';
+const cursor = () => jsonCursor(path.join(paths.dir, 'inbox.json'), (c) => ({ last_check: typeof c?.last_check === 'string' ? c.last_check : null, seen: strings(c?.seen) }));
+export const readInboxCursor = () => cursor().read();
+export const writeInboxCursor = (c) => cursor().write({ last_check: c.last_check, seen: c.seen.slice(0, MAX_SEEN) });
+/** The key a message is remembered by. */
+export const seenKey = (m) => m.message_id ?? `id:${m.id}`;

package/dist/inbox/fake.js

@@ -0,0 +1,95 @@
+// A mailbox for tests (C11R_IMAP_FAKE=<dir>): the .eml files in the folder are the messages,
+// their id the file name's number (or the position), and flags.json keeps what IMAP would: seen,
+// labels, the folder a message was moved to. "gmail": true in flags.json makes labels Gmail
+// labels; "keywords": false makes a server with neither, which can only move.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fail } from '../output.js';
+import { keywordOk } from './mailbox.js';
+import { parseMessage } from './message.js';
+export function openFake(dir, folder) {
+    const stateFile = path.join(dir, 'flags.json');
+    const read = () => {
+        const s = fs.existsSync(stateFile) ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : {};
+        return { ...s, messages: s.messages ?? {} };
+    };
+    const save = (s) => fs.writeFileSync(stateFile, JSON.stringify(s, null, 2) + '\n');
+    const files = () => fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.eml'))
+        .sort()
+        .map((f, i) => ({ id: /^\d+\.eml$/.test(f) ? String(Number(f.slice(0, -4))) : String(i + 1), file: path.join(dir, f) }));
+    const here = (s) => files().filter((m) => (s.messages[m.id]?.folder ?? 'INBOX') === folder);
+    const one = (id) => {
+        const s = read();
+        const m = here(s).find((x) => x.id === id);
+        return { s, m, st: (s.messages[id] ??= { flags: [], labels: [] }) };
+    };
+    const labelsOf = (s, id) => (s.gmail ? (s.messages[id]?.labels ?? []) : (s.messages[id]?.flags ?? []).filter((f) => !f.startsWith('\\')));
+    return {
+        host: 'fake',
+        user: 'orders@example.com',
+        folder,
+        async check() {
+            const s = read();
+            const all = here(s);
+            return { exists: all.length, unseen: all.filter((m) => !s.messages[m.id]?.flags.includes('\\Seen')).length };
+        },
+        async list({ unseen, since, limit }) {
+            const s = read();
+            const out = [];
+            for (const m of here(s)) {
+                const seen = s.messages[m.id]?.flags.includes('\\Seen') ?? false;
+                if (unseen && seen)
+                    continue;
+                const p = await parseMessage(fs.readFileSync(m.file));
+                if (since && p.date && Date.parse(p.date) < since.getTime())
+                    continue;
+                out.push({ id: m.id, message_id: p.message_id, from: p.from, subject: p.subject, date: p.date, seen, labels: labelsOf(s, m.id), size: fs.statSync(m.file).size });
+            }
+            return out.sort((a, b) => Number(b.id) - Number(a.id)).slice(0, limit);
+        },
+        async fetch(id) {
+            const { s, m } = one(id);
+            return m ? { raw: fs.readFileSync(m.file), labels: labelsOf(s, id) } : null;
+        },
+        async tag(id, t) {
+            const { s, m, st } = one(id);
+            if (!m)
+                fail('not_found', `There is no message ${id} in ${folder}.`, 'Run `c11r inbox list` for the ids.');
+            const r = { id, labels_as: null, labeled: [], unlabeled: [], seen: false };
+            if (t.label.length || t.unlabel.length) {
+                if (s.gmail) {
+                    r.labels_as = 'gmail_label';
+                    st.labels = [...new Set([...st.labels, ...t.label])].filter((l) => !t.unlabel.includes(l));
+                }
+                else if (s.keywords !== false) {
+                    const bad = [...t.label, ...t.unlabel].find((l) => !keywordOk(l));
+                    if (bad)
+                        fail('invalid_argument', `${bad} cannot be a keyword on fake: no spaces, parentheses, quotes or backslashes.`, 'Use a one-word label (ordered, order-pending), or --move <folder>.');
+                    r.labels_as = 'keyword';
+                    st.flags = [...new Set([...st.flags, ...t.label])].filter((l) => !t.unlabel.includes(l));
+                }
+                else if (!t.move)
+                    fail('labels_unsupported', `fake keeps no labels or keyword flags in ${folder}.`, 'Move the email to a folder instead: c11r inbox tag <id> --move <folder> [--seen].');
+                else
+                    r.notes = [`fake keeps no labels or keywords: the email was moved to ${t.move} instead${t.unlabel.length ? ', and there was nothing to remove' : ''}.`];
+                if (r.labels_as) {
+                    r.labeled = t.label;
+                    r.unlabeled = t.unlabel;
+                }
+            }
+            if (t.seen) {
+                st.flags = [...new Set([...st.flags, '\\Seen'])];
+                r.seen = true;
+            }
+            if (t.move) {
+                st.folder = t.move;
+                r.moved_to = t.move;
+            }
+            save(s);
+            return r;
+        },
+        async close() { },
+    };
+}

package/dist/inbox/imap.js

@@ -0,0 +1,139 @@
+// The inbox over IMAP with imapflow, loaded only here: the other commands never pay for it.
+// Gmail keeps labels (X-GM-EXT-1); other servers keep keyword flags when the folder allows any
+// (\*); a server with neither can only move the message to a folder.
+import { fail } from '../output.js';
+import { keywordOk } from './mailbox.js';
+const who = (list) => {
+    const a = list?.[0];
+    if (!a?.address)
+        return null;
+    return a.name ? `${a.name} <${a.address}>` : a.address;
+};
+export async function openImap(s) {
+    const { ImapFlow } = await import('imapflow');
+    // What an error may say: never the password, even if a server echoes it.
+    const clean = (msg) => (s.password ? msg.split(s.password).join('***') : msg);
+    const unreachable = (e) => {
+        const err = e;
+        const reason = clean(err.responseText || err.message || String(e));
+        const auth = err.authenticationFailed || /auth|credentials|login/i.test(reason);
+        fail('inbox_unreachable', `Could not open ${s.folder} on ${s.host}:${s.port} as ${s.user}: ${reason}`, auth
+            ? 'Check C11R_IMAP_USER and C11R_IMAP_PASSWORD in .commercelayer/credentials with the human: Gmail needs IMAP on and an app password (https://myaccount.google.com/apppasswords), not the account password.'
+            : 'Check C11R_IMAP_HOST and C11R_IMAP_PORT (993) in .commercelayer/credentials, and that this machine is online.');
+    };
+    const client = new ImapFlow({ host: s.host, port: s.port, secure: s.port !== 143, auth: { user: s.user, pass: s.password }, logger: false });
+    // An error after connecting (a dropped socket) must not crash the process.
+    client.on('error', () => { });
+    try {
+        await client.connect();
+    }
+    catch (e) {
+        unreachable(e);
+    }
+    let lock;
+    try {
+        lock = await client.getMailboxLock(s.folder);
+    }
+    catch (e) {
+        await client.logout().catch(() => { });
+        fail('inbox_unreachable', `There is no folder ${s.folder} on ${s.host} for ${s.user}: ${clean(e.message)}`, 'Set C11R_IMAP_FOLDER in .commercelayer/credentials to an existing folder, or leave it out for INBOX.');
+    }
+    const gmail = client.capabilities.has('X-GM-EXT-1');
+    const mailbox = () => (client.mailbox ? client.mailbox : undefined);
+    const envelopeOf = (m) => ({
+        id: String(m.uid),
+        message_id: m.envelope?.messageId ?? null,
+        from: who(m.envelope?.from),
+        subject: m.envelope?.subject ?? null,
+        date: m.envelope?.date ? new Date(m.envelope.date).toISOString() : null,
+        seen: m.flags?.has('\\Seen') ?? false,
+        labels: gmail ? [...(m.labels ?? [])] : [...(m.flags ?? [])].filter((f) => !f.startsWith('\\') && !f.startsWith('$')),
+        ...(m.size ? { size: m.size } : {}),
+    });
+    const uidOf = (id) => {
+        if (!/^\d+$/.test(id))
+            fail('invalid_argument', `${id} is not a message id.`, 'Use the id inbox list prints (a number).');
+        return id;
+    };
+    return {
+        host: s.host,
+        user: s.user,
+        folder: s.folder,
+        async check() {
+            const st = await client.status(s.folder, { messages: true, unseen: true });
+            return { exists: st ? (st.messages ?? 0) : 0, unseen: st ? (st.unseen ?? 0) : 0 };
+        },
+        async list({ unseen, since, limit }) {
+            const query = unseen ? { seen: false } : { all: true };
+            if (since)
+                query.since = since;
+            const found = await client.search(query, { uid: true });
+            const uids = (Array.isArray(found) ? found : []).sort((a, b) => b - a).slice(0, limit);
+            if (!uids.length)
+                return [];
+            const out = [];
+            for await (const m of client.fetch(uids.join(','), { uid: true, envelope: true, flags: true, size: true, ...(gmail ? { labels: true } : {}) }, { uid: true }))
+                out.push(envelopeOf(m));
+            return out.sort((a, b) => Number(b.id) - Number(a.id));
+        },
+        async fetch(id) {
+            const m = await client.fetchOne(uidOf(id), { uid: true, source: true, flags: true, ...(gmail ? { labels: true } : {}) }, { uid: true });
+            if (!m || !m.source)
+                return null;
+            return { raw: m.source, labels: envelopeOf(m).labels };
+        },
+        async tag(id, t) {
+            const uid = uidOf(id);
+            if (!(await client.fetchOne(uid, { uid: true }, { uid: true })))
+                fail('not_found', `There is no message ${id} in ${s.folder}.`, 'Run `c11r inbox list` for the ids.');
+            const result = { id, labels_as: null, labeled: [], unlabeled: [], seen: false };
+            const notes = [];
+            if (t.label.length || t.unlabel.length) {
+                const keywords = mailbox()?.permanentFlags?.has('\\*') ?? false;
+                if (gmail) {
+                    result.labels_as = 'gmail_label';
+                    if (t.label.length)
+                        await client.messageFlagsAdd(uid, t.label, { uid: true, useLabels: true });
+                    if (t.unlabel.length)
+                        await client.messageFlagsRemove(uid, t.unlabel, { uid: true, useLabels: true });
+                }
+                else if (keywords) {
+                    const bad = [...t.label, ...t.unlabel].find((l) => !keywordOk(l));
+                    if (bad)
+                        fail('invalid_argument', `${bad} cannot be a keyword on ${s.host}: no spaces, parentheses, quotes or backslashes.`, 'Use a one-word label (ordered, order-pending), or --move <folder>.');
+                    result.labels_as = 'keyword';
+                    if (t.label.length)
+                        await client.messageFlagsAdd(uid, t.label, { uid: true });
+                    if (t.unlabel.length)
+                        await client.messageFlagsRemove(uid, t.unlabel, { uid: true });
+                }
+                else if (!t.move) {
+                    fail('labels_unsupported', `${s.host} keeps no labels or keyword flags in ${s.folder}.`, 'Move the email to a folder instead: c11r inbox tag <id> --move <folder> [--seen].');
+                }
+                else
+                    notes.push(`${s.host} keeps no labels or keywords: the email was moved to ${t.move} instead${t.unlabel.length ? ', and there was nothing to remove' : ''}.`);
+                if (result.labels_as) {
+                    result.labeled = t.label;
+                    result.unlabeled = t.unlabel;
+                }
+            }
+            if (t.seen) {
+                await client.messageFlagsAdd(uid, ['\\Seen'], { uid: true });
+                result.seen = true;
+            }
+            // Last: once moved, the message has another id in another folder.
+            if (t.move) {
+                if (!(await client.messageMove(uid, t.move, { uid: true })))
+                    fail('inbox_unreachable', `${s.host} did not move message ${id} to ${t.move}.`, 'Check that the folder exists (create it in the mail app), then try again.');
+                result.moved_to = t.move;
+            }
+            if (notes.length)
+                result.notes = notes;
+            return result;
+        },
+        async close() {
+            lock.release();
+            await client.logout().catch(() => { });
+        },
+    };
+}

package/dist/inbox/mailbox.js

@@ -0,0 +1,25 @@
+// The inbox the merchant receives orders in, over IMAP: what inbox check, list, pull and tag
+// work on. The connection details are in .commercelayer/credentials (gitignored) or the
+// environment; the password is never printed, not even in an error. C11R_IMAP_FAKE=<dir> reads
+// a folder of .eml files instead (tests).
+import { credential } from '../files.js';
+import { fail } from '../output.js';
+const CREDENTIALS_HINT = 'Ask the human to add them to .commercelayer/credentials (gitignored), one per line: C11R_IMAP_HOST=imap.gmail.com, C11R_IMAP_USER=<their address>, C11R_IMAP_PASSWORD=<an app password>, and optionally C11R_IMAP_PORT (993) and C11R_IMAP_FOLDER (INBOX). For Gmail: turn on 2-Step Verification, then create an app password at https://myaccount.google.com/apppasswords; never the account password. They write the password into the file themselves: never ask for it in the chat.';
+export function imapSettings() {
+    const missing = ['C11R_IMAP_HOST', 'C11R_IMAP_USER', 'C11R_IMAP_PASSWORD'].filter((k) => !credential(k));
+    if (missing.length)
+        fail('missing_credentials', `The inbox is not set up: ${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} missing.`, CREDENTIALS_HINT);
+    const rawPort = credential('C11R_IMAP_PORT') ?? '993';
+    const port = Number(rawPort);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        fail('invalid_credentials', `C11R_IMAP_PORT is ${rawPort}, not a port.`, 'Use 993 (IMAP over TLS), the usual one, or leave it out.');
+    return { host: credential('C11R_IMAP_HOST'), port, user: credential('C11R_IMAP_USER'), password: credential('C11R_IMAP_PASSWORD'), folder: credential('C11R_IMAP_FOLDER') ?? 'INBOX' };
+}
+export async function openMailbox() {
+    const fake = process.env.C11R_IMAP_FAKE;
+    if (fake)
+        return (await import('./fake.js')).openFake(fake, credential('C11R_IMAP_FOLDER') ?? 'INBOX');
+    return (await import('./imap.js')).openImap(imapSettings());
+}
+/** An IMAP keyword is one atom: no spaces, parentheses, quotes or backslashes. */
+export const keywordOk = (name) => /^[^\s(){}%*"\\\]]+$/.test(name);

package/dist/inbox/message.js

@@ -0,0 +1,88 @@
+// One email as the agent reads it: parsed with postal-mime (loaded only here, on first use) and
+// written to .commercelayer/inbox/<id>/: message.json (headers, text, the attachments' files),
+// body.txt (the text, or the HTML as text) and attachments/ with each file as it came. The
+// CLI does not read PDFs or sheets: the agent opens them with its own abilities.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ignorePath, paths } from '../files.js';
+export const MAX_ATTACHMENT = 25 * 1024 * 1024;
+export const inboxDir = () => path.join(paths.dir, 'inbox');
+const who = (a) => (a.group ? a.group.flatMap(who) : a.address ? [a.name ? `${a.name} <${a.address}>` : a.address] : []);
+/** The HTML of a message as plain text, for one with no text part. */
+export function htmlText(html) {
+    return html
+        .replace(/<(script|style|head)[^>]*>[\s\S]*?<\/\1>/gi, '')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/(p|div|tr|li|h[1-6]|table)>/gi, '\n')
+        .replace(/<(td|th)[^>]*>/gi, '\t')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&')
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export async function parseMessage(raw) {
+    const { default: PostalMime } = await import('postal-mime');
+    const m = await PostalMime.parse(raw, { attachmentEncoding: 'arraybuffer' });
+    const text = m.text?.trim() ? m.text : m.html ? htmlText(m.html) : '';
+    return {
+        message_id: m.messageId ?? null,
+        from: m.from ? (who(m.from)[0] ?? null) : null,
+        to: (m.to ?? []).flatMap((a) => who(a)),
+        subject: m.subject ?? null,
+        date: m.date ?? null,
+        text,
+        ...(m.html ? { html: m.html } : {}),
+        attachments: m.attachments.map((a) => ({
+            name: a.filename,
+            content_type: a.mimeType,
+            bytes: typeof a.content === 'string' ? new TextEncoder().encode(a.content) : new Uint8Array(a.content),
+            inline: a.related === true || (a.disposition === 'inline' && !!a.contentId && a.mimeType.startsWith('image/')),
+        })),
+    };
+}
+const EXT = { 'application/pdf': 'pdf', 'text/plain': 'txt', 'text/csv': 'csv', 'image/png': 'png', 'image/jpeg': 'jpg', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'xlsx', 'application/vnd.ms-excel': 'xls', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'docx', 'application/msword': 'doc' };
+/** A file name safe on every system: no folders, no control characters, never empty. */
+export function safeName(name, i, type) {
+    // Slashes become underscores: "PO 2026/114.pdf" keeps its whole name and stays in its folder.
+    const base = (name ?? '').replace(/[/\\\u0000-\u001f<>:"|?*]+/g, '_').replace(/^[._]+/, '').trim().slice(0, 120);
+    return base || `attachment-${i + 1}${EXT[type] ? `.${EXT[type]}` : ''}`;
+}
+/** Write a parsed message under .commercelayer/inbox/<id>/; the folder is gitignored on first use. */
+export function writeMessage(id, m, labels) {
+    const root = inboxDir();
+    if (!fs.existsSync(root))
+        ignorePath(`${root}/`);
+    const dir = path.join(root, id.replace(/[^A-Za-z0-9._-]+/g, '_'));
+    fs.mkdirSync(dir, { recursive: true });
+    const warnings = [];
+    const attachments = [];
+    const used = new Set();
+    m.attachments.forEach((a, i) => {
+        if (a.inline)
+            return;
+        if (a.bytes.length > MAX_ATTACHMENT) {
+            warnings.push(`${a.name ?? `attachment ${i + 1}`} is over 25 MB and was not saved: open the email in the mail app.`);
+            return;
+        }
+        let name = safeName(a.name, i, a.content_type);
+        for (let n = 2; used.has(name.toLowerCase()); n++)
+            name = name.replace(/(?: \(\d+\))?(\.[^.]*)?$/, ` (${n})$1`);
+        used.add(name.toLowerCase());
+        fs.mkdirSync(path.join(dir, 'attachments'), { recursive: true });
+        const file = path.join(dir, 'attachments', name);
+        fs.writeFileSync(file, a.bytes);
+        attachments.push({ file, name: a.name, content_type: a.content_type, size: a.bytes.length });
+    });
+    const body = path.join(dir, 'body.txt');
+    fs.writeFileSync(body, m.text.endsWith('\n') ? m.text : `${m.text}\n`);
+    const message = path.join(dir, 'message.json');
+    const json = { id, message_id: m.message_id, from: m.from, to: m.to, subject: m.subject, date: m.date, labels, text: m.text, ...(m.html ? { html: m.html } : {}), attachments: attachments.map(({ file, name, content_type, size }) => ({ file, name, content_type, size })) };
+    fs.writeFileSync(message, JSON.stringify(json, null, 2) + '\n');
+    return { id, dir, message, body, subject: m.subject, from: m.from, message_id: m.message_id, attachments, ...(warnings.length ? { warnings } : {}) };
+}

package/dist/inspect.js

@@ -0,0 +1,230 @@
+// c11r storefront inspect <url>: what a brand's website says about itself, for a demo store that
+// looks like it: title, languages, the logo, the colours, the currencies and countries it sells
+// in, the platform, and whether robots.txt lets catalog pull read its products. Read-only: it
+// writes no file and downloads nothing to keep; the logo is used by its URL (hot-linked).
+import { fail } from './output.js';
+import { absoluteUrl, BudgetExceeded, hreflangs, isType, jsonLd, metas, oneLine, platformOf, robotsAllows, siteOrigin, tags, unreachable, Web } from './web.js';
+const MAX_STYLESHEETS = 3;
+const MAX_LOGOS = 5;
+const MAX_COLORS = 5;
+const hex6 = (h) => {
+    const x = h.replace('#', '').toLowerCase();
+    return `#${x.length === 3 ? [...x].map((c) => c + c).join('') : x}`;
+};
+const rgbHex = (r, g, b) => `#${[r, g, b].map((n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, '0')).join('')}`;
+/** Greys, white and black: a page's text and background, rarely its brand colour. */
+const neutral = (hex) => {
+    const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+    return Math.max(r, g, b) - Math.min(r, g, b) < 16;
+};
+/** Every colour written in CSS: #rgb, #rrggbb and rgb()/rgba(), counted. */
+export function cssColors(css, into = new Map()) {
+    const add = (h) => into.set(h, (into.get(h) ?? 0) + 1);
+    for (const m of css.matchAll(/#([0-9a-f]{6}|[0-9a-f]{3})(?![0-9a-z_-])/gi))
+        add(hex6(m[1]));
+    for (const m of css.matchAll(/rgba?\(\s*(\d{1,3})[\s,]+(\d{1,3})[\s,]+(\d{1,3})(?:\s*[,/]\s*([\d.]+%?))?\s*\)/gi)) {
+        // A transparent colour is an overlay, not a colour of the brand.
+        if (m[4] !== undefined && parseFloat(m[4]) === 0)
+            continue;
+        add(rgbHex(Number(m[1]), Number(m[2]), Number(m[3])));
+    }
+    return into;
+}
+const num = (v) => {
+    const n = Number(String(v ?? '').replace(/px$/, ''));
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+};
+/** Where the header is: the <header> element, else the top of the body. */
+const headerOf = (html) => {
+    const h = html.match(/<header\b[\s\S]*?<\/header>/i)?.[0];
+    if (h)
+        return h;
+    const body = html.search(/<body\b/i);
+    return html.slice(Math.max(0, body), Math.max(0, body) + 20_000);
+};
+export function logoCandidates(html, base, siteTitle) {
+    const out = [];
+    for (const node of jsonLd(html)) {
+        if (!['Organization', 'Brand', 'OnlineStore', 'Store', 'Corporation', 'LocalBusiness', 'WebSite'].some((t) => isType(node, t)))
+            continue;
+        const l = Array.isArray(node.logo) ? node.logo[0] : node.logo;
+        const url = absoluteUrl(typeof l === 'string' ? l : (l?.url ?? l?.contentUrl), base);
+        if (url)
+            out.push({ url, source: 'json_ld', score: 4, ...(num(l?.width) ? { width: num(l.width) } : {}), ...(num(l?.height) ? { height: num(l.height) } : {}) });
+    }
+    const words = (siteTitle ?? '').toLowerCase();
+    const scan = (region, source, bonus) => {
+        for (const t of tags(region, 'img')) {
+            const a = t.attrs;
+            const src = a.src || a['data-src'] || (a.srcset ?? a['data-srcset'] ?? '').split(',')[0]?.trim().split(/\s+/)[0];
+            // Shopify themes leave {width} in lazy sources.
+            const url = absoluteUrl(src?.replace(/\{width\}/g, '600'), base);
+            if (!url)
+                continue;
+            const own = [a.class, a.id, a.alt, src].join(' ').toLowerCase();
+            // The element around it (a link or a wrapper named logo), not just anything near.
+            const parents = [...region.slice(Math.max(0, t.index - 600), t.index).matchAll(/<(?!img\b|\/)[a-z][^>]*>/gi)].slice(-2).map((m) => m[0]).join(' ').toLowerCase();
+            const alt = (a.alt ?? '').trim().toLowerCase();
+            const score = (own.includes('logo') ? 3 : 0) + (alt && words && (words.includes(alt) || alt.includes(words.split(/\s[|–—-]\s/)[0])) ? 2 : 0) + (parents.includes('logo') ? 1 : 0);
+            if (score === 0)
+                continue;
+            out.push({ url, source, score: score + bonus, ...(a.alt ? { alt: a.alt.trim() } : {}), ...(num(a.width) ? { width: num(a.width) } : {}), ...(num(a.height) ? { height: num(a.height) } : {}) });
+        }
+    };
+    const header = headerOf(html);
+    scan(header, 'header_img', 1);
+    scan(html, 'img', 0);
+    // An inline <svg> logo has no URL to link: say so, so the agent asks for a file or picks another.
+    for (const t of tags(header, 'svg')) {
+        const own = [t.attrs.class, t.attrs.id, t.attrs['aria-label']].join(' ').toLowerCase();
+        const titled = header.slice(t.index, t.index + 400).match(/<title>([^<]*)<\/title>/i)?.[1]?.toLowerCase();
+        if (!own.includes('logo') && !(titled && words && words.includes(titled.trim())))
+            continue;
+        out.push({ url: null, source: 'header_svg', score: 2, note: 'An inline SVG in the header: it has no URL to link. Use another candidate, or ask the human for the logo file (img/logo.svg).' });
+        break;
+    }
+    const seen = new Set();
+    return out
+        .sort((a, b) => b.score - a.score)
+        .filter((l) => {
+        const key = l.url ?? `svg:${l.source}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    })
+        .slice(0, MAX_LOGOS)
+        .map(({ score: _, ...l }) => l);
+}
+const ISO_CURRENCY = /^[A-Z]{3}$/;
+export function currenciesSeen(html, meta) {
+    const found = new Set();
+    const add = (c) => typeof c === 'string' && ISO_CURRENCY.test(c.trim().toUpperCase()) && found.add(c.trim().toUpperCase());
+    add(meta['og:price:currency']);
+    add(meta['product:price:currency']);
+    for (const m of html.matchAll(/Shopify\.currency\s*=\s*\{[^}]*"active"\s*:\s*"([A-Za-z]{3})"/g))
+        add(m[1]);
+    for (const m of html.matchAll(/"priceCurrency"\s*:\s*"([A-Za-z]{3})"/g))
+        add(m[1]);
+    for (const m of html.matchAll(/"currency_code"\s*:\s*"([A-Za-z]{3})"/g))
+        add(m[1]);
+    for (const m of html.matchAll(/data-currency(?:-code)?\s*=\s*["']([A-Za-z]{3})["']/g))
+        add(m[1]);
+    // A currency selector: <select name="currency"> with ISO codes as values.
+    for (const s of html.matchAll(/<select\b[^>]*name\s*=\s*["']?currency[^>]*>([\s\S]*?)<\/select>/gi))
+        for (const o of tags(s[1], 'option'))
+            add(o.attrs.value);
+    return [...found].sort();
+}
+export function countriesSeen(html, base) {
+    const found = new Set();
+    const add = (c) => typeof c === 'string' && /^[A-Z]{2}$/.test(c.trim()) && found.add(c.trim());
+    for (const h of hreflangs(html, base))
+        if (h.region && /^[A-Z]{2}$/.test(h.region))
+            found.add(h.region);
+    for (const m of html.matchAll(/Shopify\.country\s*=\s*"([A-Z]{2})"/g))
+        add(m[1]);
+    // A country selector: Shopify's localization form, or a <select name="country...">.
+    for (const f of html.matchAll(/<form\b[^>]*localization[^>]*>([\s\S]*?)<\/form>/gi))
+        for (const m of f[1].matchAll(/data-value\s*=\s*["']([A-Z]{2})["']/g))
+            add(m[1]);
+    for (const s of html.matchAll(/<select\b[^>]*name\s*=\s*["']?country[^>]*>([\s\S]*?)<\/select>/gi))
+        for (const o of tags(s[1], 'option'))
+            add(o.attrs.value);
+    return [...found].sort();
+}
+/** The paths catalog pull reads, by strategy: whether robots.txt lets c11r read them. */
+const PRODUCT_PATHS = { shopify: ['/products.json', '/collections/all/products.json'], woocommerce: ['/wp-json/wc/store/v1/products'], structured_data: ['/sitemap.xml'] };
+export async function inspect(raw) {
+    if (!raw)
+        fail('missing_argument', 'storefront inspect needs the website address.', 'Run c11r storefront inspect https://brand.example.');
+    const origin = siteOrigin(raw, 'The address');
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`;
+    const start = absoluteUrl(withScheme, origin) ?? `${origin}/`;
+    const web = new Web();
+    let page;
+    try {
+        page = await web.get(start);
+    }
+    catch (e) {
+        if (e instanceof BudgetExceeded)
+            fail('site_unreachable', `${start} did not answer in time.`, 'Try again later.');
+        unreachable(start, e);
+    }
+    if (page === null)
+        fail('robots_disallowed', `${start}'s robots.txt does not let c11r read that page.`, 'c11r does not go around robots.txt. Ask the human for the logo, colours and products instead (a feed or a sheet for catalog pull).');
+    if (page.status === 0)
+        fail('site_unreachable', `${start} did not answer within ${Math.round(web.timeout / 1000)} s.`, 'Check the address with the human (open it in a browser), and try again later.');
+    if (!page.ok)
+        fail('site_error', `${start} answered ${page.status}.`, 'Check the address with the human: open it in a browser.');
+    const html = page.text;
+    const base = page.url;
+    const finalOrigin = new URL(base).origin;
+    const meta = metas(html);
+    const title = oneLine(html.match(/<title\b[^>]*>([\s\S]*?)<\/title>/i)?.[1] ?? '') || null;
+    const siteName = meta['og:site_name'] || null;
+    const lang = html.match(/<html\b[^>]*\blang\s*=\s*["']?([A-Za-z]{2,3}(?:[-_][A-Za-z0-9]+)*)/)?.[1] ?? null;
+    const alternates = hreflangs(html, base);
+    const languages = [...new Set([lang?.slice(0, 2).toLowerCase(), ...alternates.map((h) => h.language)].filter((l) => !!l))];
+    const icons = tags(html, 'link')
+        .filter((t) => /\b(icon|apple-touch-icon|mask-icon)\b/i.test(t.attrs.rel ?? ''))
+        .map((t) => ({ url: absoluteUrl(t.attrs.href, base), rel: t.attrs.rel, ...(t.attrs.sizes ? { sizes: t.attrs.sizes } : {}), ...(t.attrs.type ? { type: t.attrs.type } : {}) }))
+        .filter((i) => i.url);
+    // Colours: theme-color first, then the CSS: inline <style>, style="" and the first linked stylesheets.
+    const counts = new Map();
+    for (const m of html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi))
+        cssColors(m[1], counts);
+    for (const m of html.matchAll(/\sstyle\s*=\s*"([^"]*)"/gi))
+        cssColors(m[1], counts);
+    const sheets = tags(html, 'link')
+        .filter((t) => /\bstylesheet\b/i.test(t.attrs.rel ?? '') && t.attrs.href)
+        .map((t) => absoluteUrl(t.attrs.href, base))
+        .filter((u) => !!u)
+        .slice(0, MAX_STYLESHEETS);
+    let stylesheetsRead = 0;
+    for (const url of sheets) {
+        try {
+            const css = await web.get(url, 'text/css,*/*;q=0.1');
+            if (css?.ok) {
+                cssColors(css.text, counts);
+                stylesheetsRead++;
+            }
+        }
+        catch (e) {
+            if (e instanceof BudgetExceeded)
+                break;
+        }
+    }
+    const themeColor = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(meta['theme-color'] ?? '') ? hex6(meta['theme-color']) : null;
+    const colors = [
+        ...(themeColor ? [{ hex: themeColor, source: 'theme_color', count: counts.get(themeColor) ?? 0, neutral: neutral(themeColor) }] : []),
+        ...[...counts.entries()]
+            .filter(([h]) => h !== themeColor)
+            .sort((a, b) => b[1] - a[1])
+            .map(([hex, count]) => ({ hex, source: 'css', count, neutral: neutral(hex) })),
+    ].slice(0, MAX_COLORS);
+    const robots = await web.robotsFor(finalOrigin).catch(() => ({ rules: [], sitemaps: [] }));
+    const paths = Object.fromEntries(Object.values(PRODUCT_PATHS).flat().map((p) => [p, robotsAllows(robots, p)]));
+    const platform = platformOf(html, page.headers);
+    const relevant = platform === 'unknown' ? Object.values(PRODUCT_PATHS).flat() : [...PRODUCT_PATHS[platform], ...PRODUCT_PATHS.structured_data];
+    return {
+        url: base,
+        title,
+        site_name: siteName,
+        description: meta.description || meta['og:description'] || null,
+        language: lang,
+        languages,
+        theme_color: themeColor,
+        icons,
+        og_image: absoluteUrl(meta['og:image:secure_url'] || meta['og:image'], base),
+        logo_candidates: logoCandidates(html, base, siteName ?? title),
+        colors,
+        currencies_seen: currenciesSeen(html, meta),
+        countries_seen: countriesSeen(html, base),
+        platform,
+        robots: { products_allowed: relevant.some((p) => paths[p]), paths },
+        stylesheets_read: stylesheetsRead,
+        requests: web.requests,
+        next: 'Pick theme.color from colors (the first one that is not neutral, usually) and theme.logo from logo_candidates (its url, hot-linked: nothing is copied), and show the human what you picked. Then catalog: { source: website, url: <this site> } in store.yml and c11r catalog pull.' + (relevant.some((p) => paths[p]) ? '' : ' robots.txt disallows the paths catalog pull reads: ask the human for a feed or a sheet instead.'),
+    };
+}