@commercelayer/agent-cli 0.1.8 → 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]` | Make the store match the files. Refuses deletes without the flag. |
+| `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. |
@@ -24,7 +24,7 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | `orders show <id or number>` | One order. |
 | `ucp profile [--agent]` | The store's UCP business profile (`/.well-known/ucp`); with `--agent`, this CLI's own platform profile. |
 | `ucp check` | Walk every UCP capability the store advertises and report what passes. Places and pays one real test order on the way (the output says which). Exits 1 on a failed check. |
-| `status` | The sandbox, the sales channel client id, the published storefront, what is applied, the pending changes (exactly what `plan` lists; a store that does not load is pending too, with the error), orders, the UCP profile URL. |
+| `status` | The sandbox, the sales channel client id, the published storefront, what is applied, the last import job (`apply`), the pending changes (exactly what `plan` lists; a store that does not load is pending too, with the error), orders, the UCP profile URL. |
 | `claim` | Start the device flow that keeps the sandbox: a URL and a code for the human. |
 | `help [<command>]` | Describe the commands. `--version` prints the version. |
 ## store.yml
@@ -84,7 +84,7 @@ catalog:
 - `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`.
+Error codes: `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `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:
 | What | Where |

package/dist/api/stub/management.js

@@ -1,12 +1,43 @@
 // The management API at api.commercelayer.ai: sandboxes, resources, storefront
 // uploads, orders, claims. The CLI's only private API; the store hosts speak UCP.
 import crypto from 'node:crypto';
+import { canonical } from '../../store.js';
 import { generateKey } from '../../ucp/signing.js';
 import { publicOrders, readDb, SANDBOX_DOMAIN, writeDb } from './db.js';
 import { bearer, error, json, readJson } from './http.js';
 function publicState(r) {
-    const { token: _token, ucp: _ucp, ...state } = r;
-    return { ...state, name: r.name ?? null, policies: r.policies ?? null, orders: publicOrders(r) };
+    const { token: _token, ucp: _ucp, pending: _pending, ...state } = r;
+    return { ...state, name: r.name ?? null, policies: r.policies ?? null, apply: r.apply ?? null, orders: publicOrders(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;
+/**
+ * Move a running apply job forward, as the API does on every read: nothing runs in
+ * the background. When it ends, the pending resources are installed, or refused.
+ */
+function advance(r) {
+    const job = r.apply;
+    if (!job || job.status !== 'in_progress' || !r.pending)
+        return;
+    job.processed = Math.min(job.total, job.processed + ITEMS_PER_READ);
+    if (job.processed < job.total)
+        return;
+    job.step = 'done';
+    job.finished_at = new Date().toISOString();
+    if (r.pending.refused.length) {
+        job.status = 'failed';
+        job.errors = r.pending.refused.slice(0, 50).map((sku) => ({ sku, message: 'code is invalid' }));
+    }
+    else {
+        job.status = 'completed';
+        r.applied = r.pending.applied;
+        r.applied_hash = job.hash;
+    }
+    delete r.pending;
 }
 export function handleManagement(req) {
     const db = readDb();
@@ -53,16 +84,50 @@ export function handleManagement(req) {
     if (new Date(record.expires_at) < new Date() && !record.claimed) {
         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 (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));
+    }
     if (req.method === 'PUT' && rest === '/resources') {
-        const { applied, hash, name, policies } = readJson(req);
-        record.applied = applied;
-        record.applied_hash = hash;
+        advance(record);
+        writeDb(db);
+        if (record.apply?.status === 'in_progress')
+            return error(409, 'apply_in_progress', 'Another apply is still running.', 'Run `c11r status` to follow it, then apply again.');
+        const { applied, hash, name, policies, allow_delete, full } = readJson(req);
+        const before = record.applied?.products ?? {};
+        const removed = Object.keys(before).filter((sku) => !(sku in applied.products));
+        if (removed.length && !allow_delete)
+            return error(409, 'deletes_need_approval', `Apply would delete product ${removed.join(', ')}.`, 'Ask the human whether to delete these. If they agree, run `c11r apply --allow-delete`.');
+        // The name, policies and markets apply in the request; products go through an
+        // import job (SKUs, prices, then cleanups for removals) when any changed.
         record.name = name;
         record.policies = policies ?? {};
+        const changed = Object.keys(applied.products).filter((sku) => full || !(sku in before) || canonical(before[sku]) !== canonical(applied.products[sku]));
+        if (changed.length === 0 && removed.length === 0) {
+            record.applied = applied;
+            record.applied_hash = hash;
+            writeDb(db);
+            return json(200, publicState(record));
+        }
+        record.apply = {
+            id: `apply_${crypto.randomBytes(6).toString('hex')}`,
+            status: 'in_progress',
+            step: 'skus',
+            hash,
+            processed: 0,
+            total: changed.length + removed.length,
+            started_at: new Date().toISOString(),
+            finished_at: null,
+            errors: [],
+        };
+        record.pending = { applied, refused: changed.filter((sku) => REFUSED.test(sku)) };
         writeDb(db);
-        return json(200, publicState(record));
+        return json(202, publicState(record));
     }
     if (req.method === 'PUT' && rest === '/storefront') {
         const { path: dir, files } = readJson(req);

package/dist/commands.js

@@ -5,7 +5,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { createApi } from './api/client.js';
 import { ignoreCredentials, paths, readCredentials, requireCredentials, writeCredentials } from './files.js';
-import { CliError, fail } from './output.js';
+import { CliError, fail, progress } from './output.js';
 import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from './store.js';
 import { storefrontHtml } from './storefront.js';
 import { pull } from './catalog.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.',
+    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(', ')}.`);
@@ -77,23 +83,74 @@ export async function plan() {
     const changes = diff(state, desired);
     return { status: changes.length ? 'changes' : 'up_to_date', changes, deletes: changes.filter((c) => c.action === 'delete').length };
 }
+/** 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)
+            progress({ apply: jobSummary(s.apply) });
+        last = line;
+        if (Date.now() >= until) {
+            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, 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;
+}
 export async function apply(flags) {
     const api = createApi(requireCredentials());
     const desired = loadStore();
-    const state = await api.getStore();
+    // An apply still running is finished first, so the changes are counted from what it installs.
+    let state = await api.getStore();
+    if (state.apply?.status === 'in_progress')
+        state = await follow(api, state);
     const changes = diff(state, desired);
     const deletes = changes.filter((c) => c.action === 'delete');
     if (deletes.length && !flags.has('--allow-delete')) {
         fail('deletes_need_approval', `Apply would delete ${deletes.map((d) => `${d.type} ${d.id}`).join(', ')}.`, 'Ask the human whether to delete these. If they agree, run `c11r apply --allow-delete`.');
     }
-    const applied = await api.applyStore({ applied: toApplied(desired), hash: hashStore(), name: desired.name, policies: desired.policies });
+    const body = { applied: toApplied(desired), hash: hashStore(), name: desired.name, policies: desired.policies, ...(flags.has('--allow-delete') && { allow_delete: true }), ...(flags.has('--full') && { full: true }) };
+    const started = await api.applyStore(body);
+    const job = started.apply?.status === 'in_progress' ? started.apply : null;
+    const done = job ? await follow(api, started) : started;
+    if (job && done.apply?.id === job.id && done.apply.status === 'failed') {
+        const errors = done.apply.errors;
+        const list = errors.map((e) => (e.sku ? `${e.sku}: ${e.message}` : e.message)).join('; ');
+        const what = errors.length === 1 ? '1 product was refused' : `${errors.length} products were refused`;
+        fail('apply_failed', errors.length ? `${what}: ${list}` : 'The apply failed in Commerce Layer.', 'Fix those products in store.yml or the catalog source and run `c11r apply` again; the rest of the store is unchanged.');
+    }
     return {
         status: 'applied',
         changes,
-        preview_url: applied.preview_url,
+        preview_url: done.preview_url,
         markets: desired.markets.length,
         products: desired.products.length,
         payment_gateway: 'sandbox (test payments only)',
+        apply: job && done.apply ? jobSummary(done.apply) : undefined,
     };
 }
 export async function catalogPull() {
@@ -208,6 +265,7 @@ export async function status() {
         sales_channel_client_id: s.sales_channel_client_id,
         storefront: s.storefront,
         applied: Boolean(s.applied),
+        apply: s.apply ?? undefined,
         pending_changes: pending.length > 0 || storeError !== undefined,
         pending: pending.length ? pending : undefined,
         store_error: storeError,
@@ -215,7 +273,7 @@ export async function status() {
         products: s.applied ? Object.keys(s.applied.products).length : 0,
         orders: s.orders.map((o) => ({ id: o.id, label: o.label })),
         ucp_profile: `${s.preview_url}/.well-known/ucp`,
-        next: storeError ? 'Fix the store files (see store_error), then run `c11r plan`.' : pending.length ? 'Run `c11r plan` to see the changes, then `c11r apply`.' : undefined,
+        next: s.apply?.status === 'in_progress' ? 'An apply is running: run `c11r status` again to follow it, or `c11r apply` to wait for it.' : storeError ? 'Fix the store files (see store_error), then run `c11r plan`.' : pending.length ? 'Run `c11r plan` to see the changes, then `c11r apply`.' : undefined,
     };
 }
 export async function claim() {

package/dist/output.js

@@ -1,6 +1,7 @@
 // Everything the CLI says is JSON on stdout: one object per run, pretty-printed.
 // A failure is { error: { code, message, hint } } with exit code 1. The hint is
 // the fix: an agent reads it and acts on it before trying anything else.
+// A command that waits (apply) writes progress to stderr, one JSON object per line.
 export class CliError extends Error {
     code;
     hint;
@@ -13,6 +14,9 @@ export class CliError extends Error {
 export function fail(code, message, hint) {
     throw new CliError(code, message, hint);
 }
+export function progress(data) {
+    process.stderr.write(JSON.stringify(data) + '\n');
+}
 export function print(data) {
     process.stdout.write(JSON.stringify(data, null, 2) + '\n');
 }

package/package.json

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