@commercelayer/agent-cli 0.1.9 → 0.1.10

package/README.md

@@ -15,7 +15,7 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | --- | --- |
 | `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] [--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; `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. |
+| `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. |

package/dist/api/stub/management.js

@@ -11,6 +11,8 @@ function publicState(r) {
 }
 /** Like Commerce Layer refusing a sku in an import. Only the stub does this, so tests can exercise apply_failed. */
 const REFUSED = /^REFUSED-/;
+/** C11R_STUB_BUSY_READS=n: the first n reads of a running import answer 503 commercelayer_busy, as when Commerce Layer rate-limits. Per process. */
+let busyReads = Number(process.env.C11R_STUB_BUSY_READS) || 0;
 /** Items an import gets through per read: small, so the CLI polls a few times. */
 const ITEMS_PER_READ = 2;
 /**
@@ -83,6 +85,10 @@ export function handleManagement(req) {
         return error(410, 'expired', `Sandbox ${org} expired on ${record.expires_at}.`, 'Remove .commercelayer/credentials and run `c11r init` to create a new sandbox; store.yml is kept.');
     }
     if (req.method === 'GET' && rest === '') {
+        if (record.apply?.status === 'in_progress' && busyReads > 0) {
+            busyReads--;
+            return error(503, 'commercelayer_busy', 'Commerce Layer is rate-limiting this organization.', 'Wait a minute and try again; never edit store.yml for this.');
+        }
         advance(record);
         writeDb(db);
         return json(200, publicState(record));

package/dist/commands.js

@@ -18,7 +18,7 @@ export const VERSION = createRequire(import.meta.url)('../package.json').version
 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. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. An apply still running is finished first. --full re-imports every product and price, after edits in the Commerce Layer dashboard.',
+    apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/. Refuses deletes unless --allow-delete is given. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. While Commerce Layer is busy or unavailable it keeps reading, with a retrying line. An apply still running is finished first. --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 (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.',
@@ -29,9 +29,15 @@ export const HELP = {
     'ucp check': 'Walk every UCP capability the store advertises and report what passes. Places and pays one real test order on the way. Exits 1 when a check fails.',
     status: 'Show the sandbox, what is applied, and whether the store files have changes not yet applied (the same changes plan lists).',
     claim: 'Start keeping this sandbox store: returns a URL and a code for the human to approve in the browser.',
-    help: 'Describe the commands. `c11r help <command>` for one command.',
+    help: 'Describe the commands. `c11r help <command>` for one command, `c11r help <group>` (catalog, orders, storefront, ucp) for a group.',
 };
 export function help(name) {
+    if (name && !HELP[name]) {
+        // A group (catalog, orders, storefront, ucp): its commands.
+        const group = Object.entries(HELP).filter(([k]) => k.startsWith(`${name} `));
+        if (group.length)
+            return { group: name, commands: Object.fromEntries(group) };
+    }
     if (name) {
         if (!HELP[name])
             fail('unknown_command', `There is no command "${name}".`, `Commands: ${Object.keys(HELP).join(', ')}.`);
@@ -80,12 +86,17 @@ export async function plan() {
 /** How often apply reads a running import, and when it stops waiting. Env overrides are for tests. */
 const POLL_MS = Number(process.env.C11R_APPLY_POLL_MS) || 2000;
 const WAIT_MS = Number(process.env.C11R_APPLY_WAIT_MS) || 10 * 60 * 1000;
+/** Errors that say nothing about the import itself: apply keeps polling through them. */
+const TRANSIENT = new Set(['commercelayer_busy', 'commercelayer_unavailable', 'api_error', 'api_unreachable']);
+/** The longest wait between reads while Commerce Layer answers busy (429). */
+const MAX_BACKOFF_MS = 30_000;
 const jobSummary = (j) => ({ id: j.id, status: j.status, step: j.step, processed: j.processed, total: j.total });
 /** Read the store until its apply job is no longer in progress, with a progress line per change. */
 async function follow(api, state) {
     const until = Date.now() + WAIT_MS;
     let s = state;
     let last = '';
+    let wait = POLL_MS;
     while (s.apply?.status === 'in_progress') {
         const line = JSON.stringify(jobSummary(s.apply));
         if (line !== last)
@@ -95,8 +106,18 @@ async function follow(api, state) {
             const j = s.apply;
             fail('apply_pending', `The apply is still running: ${j.processed} of ${j.total} items done (step ${j.step}).`, 'The apply keeps going; run `c11r status` to follow it.');
         }
-        await new Promise((r) => setTimeout(r, POLL_MS));
-        s = await api.getStore();
+        await new Promise((r) => setTimeout(r, Math.min(wait, Math.max(0, until - Date.now()))));
+        try {
+            s = await api.getStore();
+            wait = POLL_MS;
+        }
+        catch (e) {
+            // The import runs on regardless: report the error and read again, backing off while Commerce Layer is busy.
+            if (!(e instanceof CliError) || !TRANSIENT.has(e.code))
+                throw e;
+            wait = e.code === 'commercelayer_busy' ? Math.min(MAX_BACKOFF_MS, wait * 2) : POLL_MS;
+            progress({ retrying: { code: e.code, message: e.message, next_read_ms: wait } });
+        }
     }
     return s;
 }

package/package.json

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