@commercelayer/agent-cli 0.1.5 → 0.1.8

package/README.md

@@ -9,14 +9,15 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 - **The repo is the store.** `.commercelayer/store.yml` holds the desired state (name, markets, storefront, policies, and the products of a small store) and is committed; a large catalog goes in `.commercelayer/products/` as `.yml` or `.csv` files. `plan` shows what `apply` would change; `apply` makes the store match the files.
 - **JSON only.** Every command prints one JSON object. A failure exits 1 with `{ "error": { "code", "message", "hint" } }`; the hint is the fix.
 - **Safe to re-run.** Every command is idempotent; a failed step can be fixed and run again.
-- **No secrets in git.** `init` writes the sandbox token to `.commercelayer/credentials` (`C11R_ORG`, `C11R_TOKEN`) and gitignores it.
+- **No secrets in git.** `init` writes the sandbox token to `.commercelayer/credentials` (`C11R_ORG`, `C11R_TOKEN`) and gitignores it. The keys of a catalog source go in the same file.
 ## Commands
 | Command | Does |
 | --- | --- |
 | `init [--name <business name>]` | Create a sandbox store, with no login. The name (the folder name when absent) names the organization; the org slug and store hostname derive from it, numbered when taken. Writes `store.yml` (a commented template) and `credentials`. Reuses the store if they exist. |
 | `plan` | Validate `store.yml` and the product files, and list what `apply` would create, update or delete: markets, products, and the store's name and policies. |
 | `apply [--allow-delete]` | Make the store match the files. Refuses deletes without the flag. |
-| `storefront init [--force]` | Write `storefront/index.html`: a static page on [drop-in.js](https://commercelayer.github.io/drop-in.js/) listing the products in `store.yml`, with a minicart that slides in on add to cart, and the hosted cart and checkout, wired to the sandbox's sales channel. Refuses to overwrite without the flag. |
+| `catalog pull` | Read the products from the catalog source in `store.yml` (a Supabase table, a Google Sheet or a Google Merchant Center feed) into `.commercelayer/products/catalog.csv`. Then `plan` and `apply` as usual. |
+| `storefront init [--force]` | Write `storefront/index.html`: a static page on [drop-in.js](https://commercelayer.github.io/drop-in.js/) listing the products in `store.yml`, grouped by top-level category with a navigation, with a minicart that slides in on add to cart, and the hosted cart and checkout, wired to the sandbox's sales channel. Refuses to overwrite without the flag. |
 | `storefront publish` | Upload the folder at `storefront.path` (default `storefront`) to the store host. |
 | `orders test [--sku <id>] [--quantity <n>] [--country <CC>] [--code <discount>] [--via-cart] [--decline]` | Buy from the store over UCP as a shopping agent would: discover, search, (cart,) checkout, address, pay with the sandbox handler, read the order back. Prints the order and every step. |
 | `orders list` | The orders placed in the store, newest first, as UCP order entities. |
@@ -62,14 +63,27 @@ policies:
 ### The products folder
 Beyond a handful of products, put the catalog in `.commercelayer/products/` and leave `products` out of `store.yml`. Every file in the folder is merged into the catalog by sku, in file-name order:
 - `<name>.yml`: a list of products in the shape above (one file per collection, or one per product, as you like).
-- `<name>.csv`: one product per row. The first line names the columns: `sku`, `name`, `description`, `image_url`, and one column per currency, named by its ISO 4217 code, holding the price. Quoted cells and CRLF are fine; empty cells are left out.
+- `<name>.csv`: one product per row. The first line names the columns: `sku`, `name`, `description`, `image_url`, `category`, and one column per currency, named by its ISO 4217 code, holding the price. Quoted cells and CRLF are fine; empty cells are left out.
 ```csv
-sku,name,description,EUR,USD
-COFFEE-ETH-250,"Ethiopia Yirgacheffe, 250 g","Washed, floral, bright.",14.50,16.00
-COFFEE-COL-250,"Colombia Huila, 250 g",,12.00,13.50
+sku,name,description,category,EUR,USD
+COFFEE-ETH-250,"Ethiopia Yirgacheffe, 250 g","Washed, floral, bright.",Coffee > Single origin,14.50,16.00
+COFFEE-COL-250,"Colombia Huila, 250 g",,Coffee > Single origin,12.00,13.50
 ```
 Errors name the file (and line, for CSV) and the sku, so one product file can be fixed without reading the rest. Moving a product between `store.yml` and a file is not a change to the store: `plan` keys everything by sku. The catalog has no stock: inventory is tracked live in Commerce Layer, and the sandbox treats every product as in stock. Prices in these files are what the store charges; a published storefront reads prices and availability live from Commerce Layer.
-Rules `plan` and `apply` enforce: a name, at least one market and one product; every market has `code`, `name`, `countries` and an ISO 4217 `currency`; codes and skus are unique across all files; a product has only `sku`, `name`, `description`, `image_url` and `prices`; every product has a price in the currency of every market; `shipping`, if present, has `method` and a non-negative `price`; policy entries are URLs. Currency, languages and tax follow from the countries.
+Rules `plan` and `apply` enforce: a name, at least one market and one product; every market has `code`, `name`, `countries` and an ISO 4217 `currency`; codes and skus are unique across all files; a product has only `sku`, `name`, `description`, `image_url`, `category` and `prices`; a `category` is a path of names from the top level, separated by ` > `; every product has a price in the currency of every market; `shipping`, if present, has `method` and a non-negative `price`; policy entries are URLs. Currency, languages and tax follow from the countries.
+### A catalog the human edits
+When the products live in a tool the human edits too, `store.yml` names it and `c11r catalog pull` copies it into `.commercelayer/products/catalog.csv`, sorted by sku: same source, same file. Pull applies the product rules above before it writes, with errors naming the row in the source, and reports the skus added, changed and removed. Removed products leave the store only through `apply --allow-delete`. Every source has the same columns: `sku`, `name`, `description`, `image_url`, `category`, and one price column per market currency, named by its ISO 4217 code in lowercase (`eur`, `usd`).
+```yaml
+catalog:
+  source: sheets     # sheets | supabase | merchant
+  url: https://docs.google.com/spreadsheets/d/e/2PACX-.../pub?output=csv
+  # table: products  # supabase only
+```
+- `sheets`: a Google Sheet, by its CSV link (File > Share > Publish to web > Comma-separated values) or by its own link when anyone with the link can view it. No key.
+- `supabase`: a table (default `products`), read over the REST API with the project's anon key: `C11R_SUPABASE_URL=https://<project>.supabase.co` and `C11R_SUPABASE_KEY=<anon key>` in `.commercelayer/credentials`, or the environment. The key needs a row level security policy that allows select. Never use the `service_role` key. Columns `id`, `created_at` and `updated_at` are skipped.
+- `merchant`: a Google Merchant Center product feed URL, RSS 2.0 (XML, `g:` namespace) or TSV. `id` is the sku, `title` the name, `description`, `image_link` the image, `price` (`14.50 EUR`) the price in its currency, `product_type` the category. An id listed once per currency is one product with several prices. Other attributes, `sale_price` included, are ignored.
+Error codes: `no_catalog_source`, `invalid_catalog`, `missing_credentials`, `catalog_unreachable`, `catalog_unauthorized`, `catalog_not_found`, `catalog_not_csv`, `catalog_error`, `empty_catalog`, plus `invalid_product` and `missing_price`.
+
 Error codes: `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `storefront_exists`, `no_storefront`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
 ## The store speaks UCP
 Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (live stores: `<slug>.commercelayer.store`), implementing release **2026-08-25** over REST:

package/dist/api/client.js

@@ -18,14 +18,14 @@ export function createApi(auth) {
             data = res.body ? JSON.parse(res.body) : null;
         }
         catch {
-            fail('api_error', `${base} answered ${res.status} with something that is not JSON.`, 'Try again. If it keeps happening, report it at https://commercelayer.ai/support with the output of `c11r status`.');
+            fail('api_error', `${base} answered ${res.status} with something that is not JSON.`, 'Try again. If it keeps happening, tell the human, with the output of `c11r status`.');
         }
         if (res.status < 400)
             return data;
         const err = data?.error;
         if (err)
             fail(err.code, err.message, err.hint);
-        fail('api_error', `The API answered ${res.status}.`, 'Try again. If it keeps happening, report it at https://commercelayer.ai/support with the output of `c11r status`.');
+        fail('api_error', `The API answered ${res.status}.`, 'Try again. If it keeps happening, tell the human, with the output of `c11r status`.');
     };
     return {
         createSandbox: (name) => request('POST', '/sandboxes', { name }),

package/dist/bin.js

@@ -41,6 +41,10 @@ async function run() {
             return cmd.status();
         case 'claim':
             return cmd.claim();
+        case 'catalog':
+            if (sub === 'pull')
+                return cmd.catalogPull();
+            throw new CliError('unknown_command', `There is no command "catalog ${sub ?? ''}".`, 'Use `c11r catalog pull`.');
         case 'storefront':
             if (sub === 'init')
                 return cmd.storefrontInit(flags);
@@ -77,7 +81,7 @@ run()
     }
     else {
         const message = e instanceof Error ? e.message : String(e);
-        print({ error: { code: 'internal', message, hint: 'This is a bug in the CLI. Report it at https://commercelayer.ai/support with this output.' } });
+        print({ error: { code: 'internal', message, hint: 'This is a bug in the CLI. Tell the human, with this output, and try again with npx -y @commercelayer/agent-cli@latest in case it is already fixed.' } });
     }
     process.exit(1);
 });

package/dist/catalog.js

@@ -0,0 +1,288 @@
+// c11r catalog pull: the products live in a tool the human edits too (a Supabase
+// table, a Google Sheet, a Google Merchant Center feed). Pull reads them and
+// writes .commercelayer/products/catalog.csv, so plan and apply work as always.
+// Every source maps onto the same fixed schema: sku, name, description,
+// image_url, category and one price column per currency.
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { credential, paths } from './files.js';
+import { CliError, fail } from './output.js';
+import { parseCsv, readProductFile, toCsv } from './products.js';
+import { canonical, checkProducts, readStoreFile } from './store.js';
+export const SOURCES = ['supabase', 'sheets', 'merchant'];
+export const catalogFile = path.join(paths.products, 'catalog.csv');
+const FIELDS = ['sku', 'name', 'description', 'image_url', 'category'];
+/** Columns tools add on their own (Supabase's defaults): pull skips them. */
+const IGNORED = ['id', 'created_at', 'updated_at'];
+/** Supabase rows per request; pull pages until a page comes back empty. */
+const PAGE = 1000;
+const EXAMPLE = 'For example `catalog: { source: sheets, url: <the sheet\'s CSV link> }`. Sources are supabase, sheets and merchant; see the comments in store.yml.';
+function readConfig(doc) {
+    const c = doc.catalog;
+    if (!c || typeof c !== 'object')
+        fail('no_catalog_source', 'store.yml has no catalog source.', `Add a \`catalog:\` entry to ${paths.store}. ${EXAMPLE}`);
+    if (!SOURCES.includes(c.source))
+        fail('invalid_catalog', `catalog.source in store.yml is "${c.source ?? ''}".`, `Use supabase, sheets or merchant. ${EXAMPLE}`);
+    const table = String(c.table ?? 'products');
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table))
+        fail('invalid_catalog', `catalog.table in store.yml is "${table}".`, 'Use the name of the Supabase table, such as products.');
+    const url = String(c.url ?? '');
+    if (c.source !== 'supabase' && !/^https?:\/\//.test(url)) {
+        fail('invalid_catalog', url ? `catalog.url in store.yml is "${url}", not a URL.` : 'catalog.url is missing in store.yml.', c.source === 'sheets'
+            ? 'Set url to the Google Sheet\'s CSV link (File > Share > Publish to web > Comma-separated values), or to the sheet\'s own link if it is shared with anyone who has the link.'
+            : 'Set url to the Merchant Center product feed (RSS/XML or TSV), as Merchant Center fetches it.');
+    }
+    return { source: c.source, url, table };
+}
+async function get(url, what, headers = {}) {
+    try {
+        return await fetch(url, { headers });
+    }
+    catch (e) {
+        const cause = e.cause?.message;
+        fail('catalog_unreachable', `Could not reach ${what}: ${cause ?? e.message}.`, 'Check the catalog entry in store.yml and the network, then try again.');
+    }
+}
+/** Rows with a header, from a sheet or a table: the fixed fields and one column per currency. */
+function fromTable(header, rows, where, label, currencies) {
+    const prices = currencies.map((c) => c.toLowerCase()).join(', ') || 'eur, usd, ...';
+    const columns = header.map((h) => {
+        const key = h.trim().toLowerCase();
+        if (FIELDS.includes(key))
+            return { field: key };
+        if (key === '' || IGNORED.includes(key))
+            return null;
+        const code = /^[a-z]{3}$/.test(key);
+        if (code && (currencies.length === 0 || currencies.includes(key.toUpperCase())))
+            return { currency: key.toUpperCase() };
+        const why = key === 'stock' ? 'Stock is not part of the catalog: inventory is tracked live in Commerce Layer. ' : code ? `${key.toUpperCase()} is not the currency of a market in store.yml. ` : '';
+        fail('invalid_product', `${where} has a column "${h}" that is not a product field.`, `${why}The catalog columns are ${FIELDS.join(', ')} and one price column per market currency, named by its ISO 4217 code in lowercase (${prices}). Ask the human to rename or remove the column.`);
+    });
+    if (!columns.some((c) => c && 'field' in c && c.field === 'sku'))
+        fail('invalid_product', `${where} has no sku column.`, `The catalog columns are ${FIELDS.join(', ')} and one price column per market currency (${prices}).`);
+    const out = [];
+    rows.forEach((cells, i) => {
+        if (cells.every((v) => v === null || v === undefined || String(v).trim() === ''))
+            return;
+        const product = { sku: '', name: '', prices: {} };
+        columns.forEach((col, j) => {
+            const v = cells[j];
+            if (!col || v === null || v === undefined || String(v).trim() === '')
+                return;
+            if ('currency' in col) {
+                const price = typeof v === 'number' ? v : Number(String(v).trim());
+                if (!Number.isFinite(price))
+                    fail('invalid_product', `${label(i)}: ${col.currency} price "${v}" is not a number.`, 'Write prices as plain decimals, such as 14.50, with no currency sign or thousands separator.');
+                product.prices[col.currency] = price;
+            }
+            else
+                product[col.field] = String(v).trim();
+        });
+        out.push({ product, source: label(i) });
+    });
+    return out;
+}
+async function fromSupabase(c, currencies) {
+    const base = credential('C11R_SUPABASE_URL');
+    const key = credential('C11R_SUPABASE_KEY');
+    const missing = [!base && 'C11R_SUPABASE_URL', !key && 'C11R_SUPABASE_KEY'].filter(Boolean);
+    if (missing.length || !base || !key) {
+        fail('missing_credentials', `The Supabase catalog needs ${missing.join(' and ')}.`, `Ask the human for the Supabase project URL and its anon (public) key, and for a policy that lets it select from the ${c.table} table. Add them to ${paths.credentials} as C11R_SUPABASE_URL=https://<project>.supabase.co and C11R_SUPABASE_KEY=<anon key>. Never use the service_role key.`);
+    }
+    const where = `Supabase table ${c.table}`;
+    const records = [];
+    for (;;) {
+        const url = `${base.replace(/\/+$/, '')}/rest/v1/${c.table}?select=*&order=sku.asc&limit=${PAGE}&offset=${records.length}`;
+        const res = await get(url, where, { apikey: key, Authorization: `Bearer ${key}`, Accept: 'application/json' });
+        const body = (await res.json().catch(() => null));
+        if (!res.ok) {
+            const detail = body?.message ? `: ${body.message}` : '';
+            if (res.status === 401 || res.status === 403)
+                fail('catalog_unauthorized', `Supabase refused the key${detail}.`, `Check that C11R_SUPABASE_KEY in ${paths.credentials} is the anon key of the project at C11R_SUPABASE_URL.`);
+            if (body?.code === '42703')
+                fail('invalid_product', `${where} has no sku column${detail}.`, `The catalog columns are ${FIELDS.join(', ')} and one price column per market currency, in lowercase.`);
+            if (res.status === 404 || body?.code === 'PGRST205' || body?.code === '42P01')
+                fail('catalog_not_found', `There is no ${where} at C11R_SUPABASE_URL${detail}.`, 'Check catalog.table in store.yml and C11R_SUPABASE_URL, or ask the human to create the table.');
+            fail('catalog_error', `${where} answered ${res.status}${detail}.`, 'Try again. If it keeps happening, tell the human, with this output.');
+        }
+        if (!Array.isArray(body))
+            fail('catalog_error', `${where} did not answer with rows.`, 'Check that C11R_SUPABASE_URL is the project URL, such as https://<project>.supabase.co.');
+        if (body.length === 0)
+            break;
+        records.push(...body);
+    }
+    if (records.length === 0)
+        return [];
+    const header = [...new Set(records.flatMap((r) => Object.keys(r)))];
+    return fromTable(header, records.map((r) => header.map((h) => r[h])), where, (i) => `${where}, row ${i + 1}`, currencies);
+}
+/** The CSV link of a Google Sheet, from the link the human has. */
+export function sheetCsvUrl(url) {
+    const u = new URL(url);
+    if (u.hostname !== 'docs.google.com')
+        return url;
+    const gid = u.searchParams.get('gid') ?? u.hash.match(/gid=(\d+)/)?.[1];
+    const published = u.pathname.match(/^\/spreadsheets\/d\/e\/([^/]+)\/pub(html)?$/);
+    if (published)
+        return `https://docs.google.com/spreadsheets/d/e/${published[1]}/pub?output=csv${gid ? `&gid=${gid}` : ''}`;
+    const shared = u.pathname.match(/^\/spreadsheets\/d\/([^/]+)/);
+    if (shared && shared[1] !== 'e')
+        return `https://docs.google.com/spreadsheets/d/${shared[1]}/export?format=csv${gid ? `&gid=${gid}` : ''}`;
+    return url;
+}
+async function fromSheet(c, currencies) {
+    const where = 'The Google Sheet';
+    const res = await get(sheetCsvUrl(c.url), 'the Google Sheet');
+    const help = 'In the sheet, use File > Share > Publish to web, pick the sheet and "Comma-separated values (.csv)", and put that link in catalog.url. Sharing the sheet with "Anyone with the link" works too.';
+    if (!res.ok)
+        fail('catalog_error', `${where} answered ${res.status}.`, help);
+    if ((res.headers.get('content-type') ?? '').includes('text/html'))
+        fail('catalog_not_csv', `${where} answered with a web page, not CSV: it is not published or shared.`, help);
+    const rows = parseCsv((await res.text()).replace(/^\uFEFF/, ''));
+    if (rows.length === 0)
+        return [];
+    return fromTable(rows[0], rows.slice(1), where, (i) => `the Google Sheet, row ${i + 2}`, currencies);
+}
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+function xmlText(raw) {
+    const cdata = raw.match(/^\s*<!\[CDATA\[([\s\S]*?)\]\]>\s*$/);
+    if (cdata)
+        return cdata[1].trim();
+    return raw
+        .replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (m, e) => (e[0] === '#' ? String.fromCodePoint(e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1))) : (ENTITIES[e] ?? m)))
+        .trim();
+}
+/** The top-level tags of each <item> (RSS 2.0) or <entry> (Atom), by name; g:title wins over title. */
+export function feedItems(xml) {
+    return [...xml.matchAll(/<(item|entry)\b[^>]*>([\s\S]*?)<\/\1>/g)].map(([, , body]) => {
+        const plain = {};
+        const google = {};
+        for (const [, tag, inner] of body.matchAll(/<([\w-]+(?::[\w-]+)?)\b[^>]*?(?:\/>|>([\s\S]*?)<\/\1>)/g)) {
+            if (inner === undefined)
+                continue;
+            const [prefix, name] = tag.includes(':') ? tag.toLowerCase().split(':') : ['', tag.toLowerCase()];
+            const into = prefix === 'g' ? google : prefix === '' ? plain : null;
+            if (into && !(name in into))
+                into[name] = xmlText(inner);
+        }
+        return { ...plain, ...google };
+    });
+}
+function feedRows(text) {
+    if (text.trimStart().startsWith('<'))
+        return { items: feedItems(text), label: (i) => `the Merchant feed, item ${i + 1}` };
+    const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/);
+    const header = lines[0].split('\t').map((h) => h.trim().replace(/^"|"$/g, '').replace(/^g:/i, '').toLowerCase());
+    const items = [];
+    const lineOf = [];
+    lines.slice(1).forEach((line, i) => {
+        if (!line.trim())
+            return;
+        const cells = line.split('\t');
+        const item = {};
+        header.forEach((h, j) => {
+            const v = (cells[j] ?? '').trim().replace(/^"(.*)"$/, '$1');
+            if (h && v && !(h in item))
+                item[h] = v;
+        });
+        items.push(item);
+        lineOf.push(i + 2);
+    });
+    return { items, label: (i) => `the Merchant feed, line ${lineOf[i]}` };
+}
+/** "14.50 EUR" (the Merchant format), or "EUR 14.50". */
+function feedPrice(value, label) {
+    const v = value.trim();
+    const after = v.match(/^([0-9][0-9.,]*)\s*([A-Za-z]{3})$/);
+    const before = v.match(/^([A-Za-z]{3})\s*([0-9][0-9.,]*)$/);
+    const amount = Number((after?.[1] ?? before?.[2] ?? '').replace(/,/g, '') || NaN);
+    const currency = after?.[2] ?? before?.[1];
+    if (!currency || !Number.isFinite(amount))
+        fail('invalid_product', `${label}: price "${value}" is not an amount and a currency.`, 'Merchant feed prices are written like "14.50 EUR".');
+    return [currency.toUpperCase(), amount];
+}
+async function fromMerchant(c) {
+    const res = await get(c.url, 'the Merchant feed');
+    if (!res.ok)
+        fail('catalog_error', `The Merchant feed answered ${res.status}.`, 'Check catalog.url in store.yml: it is the feed URL Merchant Center fetches.');
+    const { items, label } = feedRows(await res.text());
+    const bySku = new Map();
+    const out = [];
+    items.forEach((item, i) => {
+        if (!item.id)
+            fail('invalid_product', `${label(i)} has no id.`, 'Every feed item needs id (the sku), title and price.');
+        const product = { sku: item.id, name: item.title ?? '', prices: {} };
+        if (item.description)
+            product.description = item.description;
+        if (item.image_link)
+            product.image_url = item.image_link;
+        if (item.product_type)
+            product.category = item.product_type;
+        if (item.price) {
+            const [currency, amount] = feedPrice(item.price, label(i));
+            product.prices[currency] = amount;
+            // The same id once per country feed: one product, a price per currency.
+            const seen = bySku.get(item.id);
+            if (seen && seen.product.prices[currency] === undefined) {
+                seen.product.prices[currency] = amount;
+                return;
+            }
+        }
+        const sourced = { product, source: label(i) };
+        bySku.set(item.id, sourced);
+        out.push(sourced);
+    });
+    return out;
+}
+export async function pull() {
+    if (!fs.existsSync(paths.store))
+        fail('no_store', 'There is no store in this repo.', 'Run `c11r init` in the repo root first.');
+    let doc;
+    try {
+        doc = YAML.parse(readStoreFile()) ?? {};
+    }
+    catch (e) {
+        const reason = e.message.split('\n')[0];
+        fail('invalid_yaml', `store.yml is not valid YAML: ${reason}`, `Fix the YAML syntax in ${paths.store} and run the command again.`);
+    }
+    const config = readConfig(doc);
+    const markets = Array.isArray(doc.markets) ? doc.markets : [];
+    const currencies = [...new Set(markets.map((m) => m?.currency).filter(Boolean).map(String))];
+    const sourced = config.source === 'supabase' ? await fromSupabase(config, currencies) : config.source === 'sheets' ? await fromSheet(config, currencies) : await fromMerchant(config);
+    if (sourced.length === 0) {
+        const rls = config.source === 'supabase' ? ' If the table has rows, row level security hides them from the anon key: ask the human to add a policy that allows select.' : '';
+        fail('empty_catalog', `The ${config.source} catalog has no products.`, `Ask the human to add products to it, then pull again.${rls}`);
+    }
+    const products = checkProducts(sourced, currencies);
+    let before = new Map();
+    if (fs.existsSync(catalogFile)) {
+        try {
+            before = new Map(readProductFile(catalogFile).map((s) => [String(s.product.sku), s.product]));
+        }
+        catch (e) {
+            if (!(e instanceof CliError))
+                throw e;
+        }
+    }
+    const after = new Map(products.map((p) => [p.sku, p]));
+    const csv = toCsv(products);
+    const changed = !fs.existsSync(catalogFile) || fs.readFileSync(catalogFile, 'utf8') !== csv;
+    if (changed) {
+        fs.mkdirSync(paths.products, { recursive: true });
+        fs.writeFileSync(catalogFile, csv);
+    }
+    const removed = [...before.keys()].filter((sku) => !after.has(sku));
+    return {
+        status: changed ? 'pulled' : 'up_to_date',
+        source: config.source,
+        file: catalogFile,
+        products: products.length,
+        added: [...after.keys()].filter((sku) => !before.has(sku)),
+        changed: [...after.keys()].filter((sku) => before.has(sku) && canonical(before.get(sku)) !== canonical(after.get(sku))),
+        removed,
+        next: changed
+            ? `Run c11r plan to see what apply will change in the store.${removed.length ? ' Removed products are deleted from the store only by c11r apply --allow-delete, once the human agrees.' : ''} ${catalogFile} is rewritten by every pull: change products in the ${config.source} source, not in the file.`
+            : `${catalogFile} already matches the ${config.source} source.`,
+    };
+}

package/dist/commands.js

@@ -8,6 +8,7 @@ import { ignoreCredentials, paths, readCredentials, requireCredentials, writeCre
 import { CliError, fail } from './output.js';
 import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from './store.js';
 import { storefrontHtml } from './storefront.js';
+import { pull } from './catalog.js';
 import { buy } from './ucp/buy.js';
 import { check } from './ucp/check.js';
 import { discover } from './ucp/client.js';
@@ -18,6 +19,7 @@ export const HELP = {
     init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials. Reuses the store if store.yml already exists.',
     plan: 'Show what apply would create, update or delete: markets, products and the store\'s name and policies, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',
     apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/. Refuses deletes unless --allow-delete is given.',
+    'catalog pull': 'Read the products from the catalog source in store.yml (catalog: { source: supabase | sheets | merchant, url, table }) and write them to .commercelayer/products/catalog.csv; then plan and apply as usual. Columns: sku, name, description, image_url, category and one price column per market currency, in lowercase (eur, usd). Supabase reads C11R_SUPABASE_URL and C11R_SUPABASE_KEY (the anon key) from .commercelayer/credentials or the environment; a Google Sheet needs its CSV link or a link anyone can open; a Merchant Center feed is RSS/XML or TSV.',
     'storefront init': 'Write storefront/index.html: a static page on drop-in.js listing the products in store.yml, with a minicart that opens on add to cart, and the hosted cart and checkout. Refuses to overwrite unless --force is given.',
     'storefront publish': 'Upload the storefront folder (store.yml storefront.path, default storefront) to the sandbox preview URL.',
     'orders test': 'Buy from the store over UCP as a shopping agent would, paying with the sandbox handler: discover, search, checkout, address, pay, read the order. Options: --sku <id> --quantity <n> --country <CC> --code <discount> --via-cart --decline.',
@@ -94,6 +96,9 @@ export async function apply(flags) {
         payment_gateway: 'sandbox (test payments only)',
     };
 }
+export async function catalogPull() {
+    return pull();
+}
 export async function storefrontInit(flags) {
     const api = createApi(requireCredentials());
     const desired = loadStore();

package/dist/files.js

@@ -1,6 +1,6 @@
 // The files the CLI keeps in the repo: .commercelayer/store.yml and the product
 // files under .commercelayer/products/ (committed), and .commercelayer/credentials
-// (gitignored: the sandbox token).
+// (gitignored: the sandbox token, and the keys of a catalog source).
 import fs from 'node:fs';
 import path from 'node:path';
 import { fail } from './output.js';
@@ -11,22 +11,38 @@ export const paths = {
     products: path.join(dir, 'products'),
     credentials: path.join(dir, 'credentials'),
 };
-export function readCredentials() {
-    if (!fs.existsSync(paths.credentials))
-        return null;
+/** Every KEY=value line of the credentials file; quotes around a value are dropped. */
+function credentialVars() {
     const vars = {};
+    if (!fs.existsSync(paths.credentials))
+        return vars;
     for (const line of fs.readFileSync(paths.credentials, 'utf8').split('\n')) {
-        const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+        const m = line.trim().match(/^([A-Z0-9_]+)=(.*)$/);
         if (m)
-            vars[m[1]] = m[2];
+            vars[m[1]] = m[2].trim().replace(/^(["'])(.*)\1$/, '$2');
     }
+    return vars;
+}
+/** A secret the CLI needs besides the store's own token: the environment wins over the credentials file. */
+export function credential(key) {
+    return process.env[key] || credentialVars()[key] || undefined;
+}
+export function readCredentials() {
+    if (!fs.existsSync(paths.credentials))
+        return null;
+    const vars = credentialVars();
     if (!vars.C11R_ORG || !vars.C11R_TOKEN)
         return null;
     return { org: vars.C11R_ORG, token: vars.C11R_TOKEN };
 }
 export function writeCredentials(c) {
     fs.mkdirSync(paths.dir, { recursive: true });
-    fs.writeFileSync(paths.credentials, `C11R_ORG=${c.org}\nC11R_TOKEN=${c.token}\n`, { mode: 0o600 });
+    // Keep any other keys already in the file (C11R_SUPABASE_*, ...).
+    const others = Object.entries(credentialVars())
+        .filter(([k]) => k !== 'C11R_ORG' && k !== 'C11R_TOKEN')
+        .map(([k, v]) => `${k}=${v}\n`)
+        .join('');
+    fs.writeFileSync(paths.credentials, `C11R_ORG=${c.org}\nC11R_TOKEN=${c.token}\n${others}`, { mode: 0o600 });
 }
 /** The store and its credentials, or a failure telling the agent to run init. */
 export function requireCredentials() {

package/dist/products.js

@@ -8,7 +8,7 @@ import YAML from 'yaml';
 import { paths } from './files.js';
 import { fail } from './output.js';
 /** The fixed CSV columns; any other column named by an ISO 4217 code is a price. */
-export const CSV_COLUMNS = ['sku', 'name', 'description', 'image_url'];
+export const CSV_COLUMNS = ['sku', 'name', 'description', 'image_url', 'category'];
 /** The product files, in a stable order. */
 export function productFiles() {
     if (!fs.existsSync(paths.products))
@@ -126,3 +126,16 @@ function fromCsv(file, text) {
     });
     return products;
 }
+const csvCell = (v) => {
+    const t = v === undefined ? '' : String(v);
+    return /[",\r\n]/.test(t) ? `"${t.replace(/"/g, '""')}"` : t;
+};
+/** Products as CSV in the shape fromCsv reads: the fixed columns, then one per currency, rows by sku. Same products, same bytes. */
+export function toCsv(products) {
+    const currencies = [...new Set(products.flatMap((p) => Object.keys(p.prices ?? {})))].sort();
+    const rows = [...products].sort((a, b) => (a.sku < b.sku ? -1 : a.sku > b.sku ? 1 : 0));
+    const lines = [[...CSV_COLUMNS, ...currencies].join(',')];
+    for (const p of rows)
+        lines.push([...CSV_COLUMNS.map((c) => csvCell(p[c])), ...currencies.map((c) => csvCell(p.prices?.[c]))].join(','));
+    return lines.join('\n') + '\n';
+}

package/dist/store.js

@@ -9,7 +9,7 @@ import { fail } from './output.js';
 import { paths } from './files.js';
 import { productFiles, readProductFile } from './products.js';
 /** The keys a product may have. Stock is not one: inventory lives in Commerce Layer. */
-export const PRODUCT_KEYS = ['sku', 'name', 'description', 'image_url', 'prices'];
+export const PRODUCT_KEYS = ['sku', 'name', 'description', 'image_url', 'category', 'prices'];
 export const template = (name) => `# Commerce Layer store. This file is the store: edit it, then run
 #   c11r plan    to see what will change
 #   c11r apply   to make the change
@@ -30,15 +30,27 @@ products:
   # Products go here, or in files under .commercelayer/products/, merged by sku:
   #   <name>.yml   a list of products in this same shape
   #   <name>.csv   one product per row, columns: sku, name, description, image_url,
-  #                and one column per currency (EUR, USD, ...) with the price
+  #                category, and one column per currency (EUR, USD, ...) with the price
+  # category is optional, a path from the top level: Coffee > Single origin.
   # Use the folder for anything beyond a handful of products.
   # sku is unique and stays the same when you rename a product.
   # - sku: COFFEE-ETH-250
   #   name: Ethiopia Yirgacheffe, 250 g
   #   description: Washed, floral, bright.
+  #   category: Coffee > Single origin
   #   prices: { EUR: 14.50 }
   # Stock is not part of the catalog: inventory is tracked live in Commerce Layer.
 
+catalog:
+  # Where \`c11r catalog pull\` reads the products from, if they live in a tool the
+  # human edits. Pull writes them to .commercelayer/products/catalog.csv.
+  # source: sheets     # a Google Sheet published as CSV: url is its CSV link
+  # source: supabase   # a Supabase table: table is its name (default products);
+  #                    # C11R_SUPABASE_URL and C11R_SUPABASE_KEY in .commercelayer/credentials
+  # source: merchant   # a Google Merchant Center feed, RSS (XML) or TSV: url is the feed
+  # url: https://...
+  # table: products
+
 storefront:
   # The web app in this repo that sells the products, relative to the repo root.
   # path: storefront
@@ -119,6 +131,11 @@ export function loadStore() {
             fail('invalid_store', `policies.${key} is not a URL.`, 'Policy entries are full URLs starting with https://, or left out to use the default sandbox pages.');
     }
     const currencies = [...new Set(markets.map((m) => m.currency))];
+    const products = checkProducts(sourced, currencies);
+    return { name: doc.name, markets, products, storefront: doc.storefront, policies };
+}
+/** The product rules, shared by loadStore and catalog pull: errors name each product's source. */
+export function checkProducts(sourced, currencies) {
     const skus = new Map();
     const products = [];
     for (const { product: p, source } of sourced) {
@@ -136,15 +153,21 @@ export function loadStore() {
             const why = unknown.includes('stock') ? 'Stock is not part of the catalog: inventory is tracked live in Commerce Layer. ' : '';
             fail('invalid_product', `Product ${p.sku} in ${source} has ${unknown.length === 1 ? 'a field' : 'fields'} not in the catalog: ${unknown.join(', ')}.`, `${why}A product has ${PRODUCT_KEYS.join(', ')}. Remove the other fields.`);
         }
+        if (p.category !== undefined) {
+            const parts = typeof p.category === 'string' ? p.category.split('>').map((c) => c.trim()) : [''];
+            if (parts.some((c) => !c))
+                fail('invalid_product', `Product ${p.sku} in ${source} has category "${p.category}".`, 'A category is a path of names from the top level, separated by " > ", such as "Coffee > Single origin". Leave it out for no category.');
+            p.category = parts.join(' > ');
+        }
         for (const c of currencies) {
             const price = p.prices?.[c];
             if (typeof price !== 'number' || price < 0) {
-                fail('missing_price', `Product ${p.sku} in ${source} has no price in ${c}.`, `Add the ${c} price to the product (\`${c}: <amount>\` under prices in YAML, a ${c} column in CSV); every product needs a price in each market's currency (${currencies.join(', ')}).`);
+                fail('missing_price', `Product ${p.sku} in ${source} has no price in ${c}.`, `Add the ${c} price to the product (\`${c}: <amount>\` under prices in YAML, a ${c} column in CSV or in the catalog source); every product needs a price in each market's currency (${currencies.join(', ')}).`);
             }
         }
         products.push(p);
     }
-    return { name: doc.name, markets, products, storefront: doc.storefront, policies };
+    return products;
 }
 export function toApplied(store) {
     return {
@@ -152,7 +175,8 @@ export function toApplied(store) {
         products: Object.fromEntries(store.products.map((p) => [p.sku, p])),
     };
 }
-const canonical = (v) => JSON.stringify(v ?? {}, (_k, x) => (x === undefined ? undefined : x));
+/** JSON with sorted keys and no undefined values, so key order never reads as a change. */
+export const canonical = (v) => JSON.stringify(v ?? {}, (_k, x) => (x && typeof x === 'object' && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : x));
 /** The one definition of "pending changes": what apply would do. plan and status both use it. */
 export function diff(state, desired) {
     const changes = [];
@@ -170,7 +194,7 @@ export function diff(state, desired) {
         for (const id of Object.keys(after[kind])) {
             if (!(id in before))
                 changes.push({ action: 'create', type, id });
-            else if (JSON.stringify(before[id]) !== JSON.stringify(after[kind][id]))
+            else if (canonical(before[id]) !== canonical(after[kind][id]))
                 changes.push({ action: 'update', type, id });
         }
         for (const id of Object.keys(before))

package/dist/storefront.js

@@ -1,16 +1,43 @@
 // The storefront scaffold: one static page on drop-in.js listing the products in
-// store.yml, with the minicart, the hosted cart and checkout. The agent then makes it the human's.
+// store.yml, grouped by top-level category, with the minicart, the hosted cart and
+// checkout. The agent then makes it the human's.
 const esc = (t) => String(t ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 export function storefrontHtml(store, clientId) {
     const name = esc(store.name);
-    const cards = store.products
-        .map((p) => `      <article class="product">
-${p.image_url ? `        <img src="${esc(p.image_url)}" alt="">\n` : ''}        <h2>${esc(p.name)}</h2>
+    const card = (p, h) => `      <article class="product">
+${p.image_url ? `        <img src="${esc(p.image_url)}" alt="">\n` : ''}        <${h}>${esc(p.name)}</${h}>
 ${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-price code="${esc(p.sku)}"><cl-price-amount type="compare-at"></cl-price-amount> <cl-price-amount type="price"></cl-price-amount></cl-price>
         <cl-availability code="${esc(p.sku)}"><cl-availability-status type="available">In stock</cl-availability-status><cl-availability-status type="unavailable">Sold out</cl-availability-status></cl-availability>
         <cl-add-to-cart code="${esc(p.sku)}">Add to cart</cl-add-to-cart>
-      </article>`)
-        .join('\n');
+      </article>`;
+    // Products are grouped by the top level of their category, in order of first appearance;
+    // products with no category come last, under "Other". No categories: one grid.
+    const groups = new Map();
+    for (const p of store.products) {
+        const top = p.category?.split(' > ')[0] ?? '';
+        groups.set(top, [...(groups.get(top) ?? []), p]);
+    }
+    const categorized = [...groups.keys()].some((k) => k);
+    let body;
+    let categoryNav = '';
+    if (!categorized)
+        body = `    <div class="grid">\n${store.products.map((p) => card(p, 'h2')).join('\n')}\n    </div>`;
+    else {
+        const ordered = [...groups.keys()].filter((k) => k).concat(groups.has('') ? [''] : []);
+        const used = new Set();
+        const ids = ordered.map((k) => {
+            const base = `category-${(k || 'other').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'other'}`;
+            let id = base;
+            for (let n = 2; used.has(id); n++)
+                id = `${base}-${n}`;
+            used.add(id);
+            return id;
+        });
+        categoryNav = `  <nav class="categories">\n${ordered.map((k, i) => `    <a href="#${ids[i]}">${esc(k || 'Other')}</a>`).join('\n')}\n  </nav>\n`;
+        body = ordered
+            .map((k, i) => `    <section id="${ids[i]}">\n      <h2>${esc(k || 'Other')}</h2>\n      <div class="grid">\n${groups.get(k).map((p) => card(p, 'h3')).join('\n')}\n      </div>\n    </section>`)
+            .join('\n');
+    }
     const options = store.markets.map((m) => `          <option value="${esc(m.code)}">${esc(m.name)} (${esc(m.currency)})</option>`).join('\n');
     return `<!doctype html>
 <html lang="en">
@@ -37,15 +64,24 @@ ${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-pric
     header { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 20px 24px; border-bottom: 1px solid var(--line); }
     header h1 { margin: 0; font-size: 20px; }
     header nav { display: flex; align-items: center; gap: 16px; }
-    main { max-width: 1100px; margin: 0 auto; padding: 32px 24px; display: grid; gap: 24px; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); }
+    nav.categories { display: flex; flex-wrap: wrap; gap: 8px 20px; padding: 14px 24px; border-bottom: 1px solid var(--line); }
+    nav.categories a { color: var(--ink); text-decoration: none; font-size: 15px; }
+    nav.categories a:hover { color: var(--accent); }
+    main { max-width: 1100px; margin: 0 auto; padding: 32px 24px; }
+    main section { scroll-margin-top: 16px; }
+    main section + section { margin-top: 40px; }
+    main section > h2 { margin: 0 0 16px; font-size: 22px; }
+    .grid { display: grid; gap: 24px; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); }
     .product { display: flex; flex-direction: column; gap: 8px; padding: 20px; border: 1px solid var(--line); border-radius: 8px; }
     .product img { width: 100%; aspect-ratio: 1; object-fit: cover; border-radius: 6px; }
-    .product h2 { margin: 0; font-size: 17px; }
+    .product h2, .product h3 { margin: 0; font-size: 17px; }
     .product p { margin: 0; color: var(--muted); font-size: 14px; line-height: 1.5; }
     cl-price { font-weight: 600; }
     cl-price-amount[type="compare-at"] { color: var(--muted); font-weight: 400; text-decoration: line-through; }
     cl-availability { font-size: 13px; color: var(--muted); }
     cl-add-to-cart { margin-top: auto; }
+    /* drop-in.css styles the count as a badge beside a cart icon (absolute, pushed right). The link is text here, so render it inline: "Cart (3)". */
+    cl-cart-link cl-cart-count { position: static; transform: none; display: inline; min-width: 0; height: auto; padding: 0; border-radius: 0; background: none; color: inherit; font-size: inherit; }
     cl-add-to-cart::part(button), cl-checkout-link::part(a) { display: inline-block; padding: 10px 16px; border-radius: 6px; background: var(--accent); color: #fff; font: inherit; border: 0; cursor: pointer; text-decoration: none; }
     footer { padding: 24px; border-top: 1px solid var(--line); color: var(--muted); font-size: 13px; }
   </style>
@@ -63,8 +99,8 @@ ${options}
       <cl-checkout-link>Checkout</cl-checkout-link>
     </nav>
   </header>
-  <main>
-${cards}
+${categoryNav}  <main>
+${body}
   </main>
   <footer>Sandbox store: test payments only.</footer>
   <script>document.querySelector('header select').value = market;</script>

package/dist/ucp/client.js

@@ -65,7 +65,7 @@ export async function discover(origin) {
         profile = JSON.parse(res.body);
     }
     catch {
-        fail('ucp_profile_malformed', `${origin}/.well-known/ucp is not JSON.`, 'Report it at https://commercelayer.ai/support with the output of `c11r status`.');
+        fail('ucp_profile_malformed', `${origin}/.well-known/ucp is not JSON.`, 'The store host answered badly. Try again; if it keeps happening, tell the human, with the output of `c11r status`.');
     }
     const ucp = profile.ucp ?? {};
     if (ucp.version !== UCP_VERSION) {
@@ -74,7 +74,7 @@ export async function discover(origin) {
     const rest = (name) => (ucp.services?.[name] ?? []).find((s) => s.transport === 'rest')?.endpoint ?? null;
     const endpoint = rest('dev.ucp.shopping');
     if (!endpoint)
-        fail('ucp_no_rest_service', 'The store profile has no REST dev.ucp.shopping service.', 'Report it at https://commercelayer.ai/support.');
+        fail('ucp_no_rest_service', 'The store profile has no REST dev.ucp.shopping service.', 'The store host serves a profile this CLI cannot use. Tell the human, with the output of `c11r ucp profile`.');
     const capabilities = new Set();
     for (const [name, entries] of Object.entries(ucp.capabilities ?? {})) {
         if (entries.some((e) => e.version === UCP_VERSION))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "c11r: the Commerce Layer CLI for coding agents. Builds a sandbox store that people and shopping agents can buy from.",
   "homepage": "https://commercelayer.ai",
   "keywords": [