@commercelayer/agent-cli 0.1.10 → 0.1.11

package/README.md

@@ -17,8 +17,8 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | `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] [--full]` | Make the store match the files. Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products Commerce Layer refused; While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--full` re-imports every product and price, after edits in the Commerce Layer dashboard. |
 | `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. |
+| `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, styled through theme tokens at the top of its `<style>` (`--paper`, `--ink`, `--muted`, `--line`, `--accent`, `--on-accent`, `--radius`, `--font`) that also restyle drop-in.js's prices, buttons and links, so a dark theme is a token change. Product images go in `storefront/img/` (`image_url: img/<file>`); products with no image get a neutral tile. 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, leaving out dotfiles. Lists products whose `image_url` points at a file that is not in the folder (`missing_images`). |
 | `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. |
 | `orders show <id or number>` | One order. |
@@ -70,7 +70,7 @@ COFFEE-ETH-250,"Ethiopia Yirgacheffe, 250 g","Washed, floral, bright.",Coffee >
 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`, `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.
+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 ` > `; an `image_url` is an `https://` URL or a path in the storefront folder such as `img/eth.jpg` (served from the store host, given to shopping agents as a full URL); 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

package/dist/api/stub/shopping.js

@@ -98,8 +98,9 @@ function variant(ctx, p, market) {
         // Inventory lives in Commerce Layer; the sandbox catalog has no stock, so everything is in stock.
         availability: { available: true, status: 'in_stock' },
     };
+    // A path in the storefront (img/eth.jpg) is served from the store host: shopping agents get the full URL.
     if (p.image_url)
-        v.media = [{ type: 'image', url: p.image_url }];
+        v.media = [{ type: 'image', url: new URL(p.image_url, `${ctx.origin}/`).href }];
     if (ctx.shared.has('dev.ucp.shopping.fulfillment')) {
         const o = shippingOption(market);
         v.fulfillment = { methods: [{ type: 'shipping', description: { plain: `Ships to ${market.countries.join(', ')}` }, availability: v.availability, options: [{ id: o.id, title: o.title, description: o.description }] }] };

package/dist/commands.js

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { createApi } from './api/client.js';
 import { ignoreCredentials, paths, readCredentials, requireCredentials, writeCredentials } from './files.js';
 import { CliError, fail, progress } from './output.js';
-import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from './store.js';
+import { diff, hashStore, isLocalImage, loadStore, storefrontPath, template, toApplied } from './store.js';
 import { storefrontHtml } from './storefront.js';
 import { pull } from './catalog.js';
 import { buy } from './ucp/buy.js';
@@ -167,12 +167,17 @@ export async function storefrontInit(flags) {
     fs.mkdirSync(dir, { recursive: true });
     const file = path.join(dir, 'index.html');
     fs.writeFileSync(file, storefrontHtml(desired, state.sales_channel_client_id));
+    // img/ is where product images go (image_url: img/<file>); .gitkeep keeps the empty folder in git, and publish skips dotfiles.
+    const keep = path.join(dir, 'img', '.gitkeep');
+    fs.mkdirSync(path.dirname(keep), { recursive: true });
+    if (!fs.existsSync(keep))
+        fs.writeFileSync(keep, '');
     return {
         status: 'created',
-        files: [file],
+        files: [file, keep],
         markets: desired.markets.map((m) => m.code),
         products: desired.products.length,
-        next: `Set storefront.path: ${dir} in ${paths.store}, make the page the human's, then run c11r storefront publish.`,
+        next: `Set storefront.path: ${dir} in ${paths.store}, make the page the human's (restyle it through the theme tokens at the top of its <style>; product images go in ${dir}/img/ with image_url: img/<file>), then run c11r storefront publish.`,
     };
 }
 export async function storefrontPublish() {
@@ -181,16 +186,36 @@ export async function storefrontPublish() {
     if (!fs.existsSync(path.join(dir, 'index.html'))) {
         fail('no_storefront', `There is no ${path.join(dir, 'index.html')}.`, 'Run `c11r storefront init` to create one, or set storefront.path in store.yml to the folder that has index.html.');
     }
+    // Dotfiles (.gitkeep, .DS_Store, .env) and dot folders stay on this machine.
     const files = fs
         .readdirSync(dir, { recursive: true, withFileTypes: true })
         .filter((e) => e.isFile())
-        .map((e) => {
-        const full = path.join(e.parentPath, e.name);
-        return { path: path.relative(dir, full).split(path.sep).join('/'), content_base64: fs.readFileSync(full).toString('base64') };
-    });
+        .map((e) => path.relative(dir, path.join(e.parentPath, e.name)).split(path.sep).join('/'))
+        .filter((rel) => !rel.split('/').some((part) => part.startsWith('.')))
+        .map((rel) => ({ path: rel, content_base64: fs.readFileSync(path.join(dir, rel)).toString('base64') }));
+    // Products whose image_url is a path in the storefront that is not there.
+    let missingImages = [];
+    try {
+        const uploaded = new Set(files.map((f) => f.path));
+        missingImages = loadStore()
+            .products.filter((p) => p.image_url && isLocalImage(p.image_url) && !uploaded.has(p.image_url.replace(/^\.?\//, '')))
+            .map((p) => `${p.sku}: ${p.image_url}`);
+    }
+    catch (e) {
+        if (!(e instanceof CliError))
+            throw e;
+    }
     const published = await api.publishStorefront(dir, files);
     const state = await api.getStore();
-    return { status: 'published', preview_url: state.preview_url, path: dir, files: published.files, published_at: published.published_at };
+    return {
+        status: 'published',
+        preview_url: state.preview_url,
+        path: dir,
+        files: published.files,
+        published_at: published.published_at,
+        missing_images: missingImages.length ? missingImages : undefined,
+        next: missingImages.length ? `Add the missing images under ${dir}/ (image_url is relative to it), or fix image_url, then publish again.` : undefined,
+    };
 }
 /** The store's origin on the web: where it speaks UCP. */
 async function storeOrigin() {

package/dist/store.js

@@ -153,6 +153,12 @@ export function checkProducts(sourced, currencies) {
             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.image_url !== undefined) {
+            const url = String(p.image_url);
+            const ok = isLocalImage(url) ? !url.split('/').includes('..') && url.trim() === url && url !== '' : /^https?:\/\/\S+$/.test(url);
+            if (!ok)
+                fail('invalid_product', `Product ${p.sku} in ${source} has image_url "${url}".`, 'Use a full https:// URL, or a path in the storefront folder such as img/eth.jpg (no "..").');
+        }
         if (p.category !== undefined) {
             const parts = typeof p.category === 'string' ? p.category.split('>').map((c) => c.trim()) : [''];
             if (parts.some((c) => !c))
@@ -169,6 +175,8 @@ export function checkProducts(sourced, currencies) {
     }
     return products;
 }
+/** An image_url that is a path in the storefront (img/eth.jpg), not a URL. */
+export const isLocalImage = (url) => !/^[a-z][a-z0-9+.-]*:/i.test(url) && !url.startsWith('//');
 export function toApplied(store) {
     return {
         markets: Object.fromEntries(store.markets.map((m) => [m.code, m])),

package/dist/storefront.js

@@ -5,7 +5,8 @@ const esc = (t) => String(t ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<
 export function storefrontHtml(store, clientId) {
     const name = esc(store.name);
     const card = (p, h) => `      <article class="product">
-${p.image_url ? `        <img src="${esc(p.image_url)}" alt="">\n` : ''}        <${h}>${esc(p.name)}</${h}>
+${p.image_url ? `        <img src="${esc(p.image_url)}" alt="">` : '        <div class="placeholder" aria-hidden="true"></div>'}
+        <${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>
@@ -45,7 +46,8 @@ ${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-pric
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${name}</title>
-  <!-- Commerce Layer drop-in.js: prices, availability, add to cart, the minicart (a slide-in panel, styled by minicart.css) and links to the hosted cart and checkout. -->
+  <!-- Commerce Layer drop-in.js: prices, availability, add to cart, the minicart (a slide-in panel, styled by minicart.css) and links to the hosted cart and checkout.
+       Product images: put them in img/ next to this page and set image_url: img/<file> in the catalog. -->
   <link href="https://cdn.jsdelivr.net/npm/@commercelayer/drop-in.js@2/dist/drop-in/drop-in.css" rel="stylesheet">
   <link href="https://cdn.jsdelivr.net/npm/@commercelayer/drop-in.js@2/dist/drop-in/minicart.css" rel="stylesheet">
   <script>
@@ -59,38 +61,69 @@ ${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-pric
   </script>
   <script type="module" src="https://cdn.jsdelivr.net/npm/@commercelayer/drop-in.js@2/dist/drop-in/drop-in.esm.js"></script>
   <style>
-    :root { color-scheme: light; --ink: #16181d; --muted: #5d6572; --line: #e3e6ea; --accent: #1f5eff; }
-    body { margin: 0; font-family: system-ui, sans-serif; color: var(--ink); background: #fff; }
-    header { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 20px 24px; border-bottom: 1px solid var(--line); }
+    /* Theme: restyle the page by changing these tokens; a dark theme is color-scheme: dark with paper and ink swapped.
+       Keep this <style> after the drop-in.js stylesheets: its rules use the same selectors as drop-in.css, so they win by coming later. */
+    :root {
+      color-scheme: light;
+      --paper: #ffffff;     /* page background */
+      --ink: #16181d;       /* text and prices */
+      --muted: #5d6572;     /* secondary text, compare-at prices, availability */
+      --line: #e3e6ea;      /* borders, disabled buttons */
+      --accent: #1f5eff;    /* buttons, link hover */
+      --on-accent: #ffffff; /* text on the accent */
+      --radius: 8px;
+      --font: system-ui, sans-serif;
+      /* drop-in.css's own defaults (add to cart, cart count) read these. */
+      --cl-color-primary: var(--accent);
+      --cl-color-white: var(--on-accent);
+    }
+    body { margin: 0; font-family: var(--font); color: var(--ink); background: var(--paper); }
+    a { color: inherit; }
+    header { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 10px 16px; padding: 16px 24px; border-bottom: 1px solid var(--line); }
     header h1 { margin: 0; font-size: 20px; }
-    header nav { display: flex; align-items: center; gap: 16px; }
+    /* The nav never wraps inside: on a narrow screen it moves under the store name as a whole. */
+    header nav { display: flex; align-items: center; gap: 16px; margin-left: auto; white-space: nowrap; }
+    header select { font: inherit; color: inherit; background: var(--paper); border: 1px solid var(--line); border-radius: calc(var(--radius) / 2); padding: 4px 6px; }
     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 { 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 { display: flex; flex-direction: column; gap: 8px; padding: 20px; border: 1px solid var(--line); border-radius: var(--radius); }
+    .product img, .product .placeholder { width: 100%; aspect-ratio: 1; object-fit: cover; border-radius: calc(var(--radius) - 2px); }
+    /* No image: a plain tile a shade off the page, in any theme. */
+    .product .placeholder { background: color-mix(in srgb, var(--ink) 6%, var(--paper)); }
     .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; }
+    /* drop-in.css colours cl-price-amount itself (#101111), so inheriting is not enough: set it here. */
+    cl-price-amount { color: var(--ink); font-weight: 600; }
+    cl-price-amount[type="compare-at"] { color: var(--muted); font-weight: 400; }
     cl-availability { font-size: 13px; color: var(--muted); }
-    cl-add-to-cart { margin-top: auto; }
+    /* cl-add-to-cart is the button itself (it has no ::part); drop-in.css colours it with these same selectors. */
+    cl-add-to-cart { margin-top: auto; align-self: flex-start; padding: 10px 16px; border-radius: calc(var(--radius) - 2px); font: inherit; font-weight: 600; background-color: var(--line); color: var(--muted); }
+    cl-add-to-cart:not([aria-disabled=true]) { background-color: var(--accent); color: var(--on-accent); }
+    /* cl-checkout-link renders a plain <a> (no shadow DOM); without an order it is aria-disabled. */
+    cl-checkout-link a { display: inline-block; padding: 8px 14px; border-radius: calc(var(--radius) - 2px); background: var(--accent); color: var(--on-accent); font-weight: 600; text-decoration: none; }
+    cl-checkout-link[aria-disabled="true"] a { background: var(--line); color: var(--muted); }
     /* 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; }
+    @media (max-width: 480px) {
+      header, nav.categories { padding-left: 16px; padding-right: 16px; }
+      header nav { gap: 12px; }
+      .market-label { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+      main { padding: 24px 16px; }
+    }
   </style>
 </head>
 <body>
   <header>
     <h1>${name}</h1>
     <nav>
-      <label>Market
+      <label><span class="market-label">Market</span>
         <select onchange="location.search = '?market=' + this.value">
 ${options}
         </select>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "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": [