@commercelayer/agent-cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Commerce Layer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @commercelayer/agent-cli
+`c11r`, the Commerce Layer CLI for coding agents. An agent reads [commercelayer.ai/start.md](https://commercelayer.ai/start.md), runs this CLI, and the human ends up with a working store in a sandbox: products, prices, a market, a storefront at `<org>.sandbox.commercelayer.store`, and a paid test order. No account needed until they decide to keep it.
+Every store speaks the [Universal Commerce Protocol](https://ucp.dev) on its own hostname, so shopping agents can discover it, browse it and buy from it. The CLI itself buys through UCP (`orders test`) and checks the store against the spec (`ucp check`), so what it verifies is what any agent would get.
+It is a separate tool from [`@commercelayer/cli`](https://www.npmjs.com/package/@commercelayer/cli), the CLI for humans. The package is `@commercelayer/agent-cli`; the command is `c11r` (c, eleven letters, r), short and unmistakable in an agent's transcript.
+```
+npx -y @commercelayer/agent-cli@latest init   # runs c11r init
+```
+## How it works
+- **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.
+## Commands
+| Command | Does |
+| --- | --- |
+| `init` | Create a sandbox store, with no login. 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. |
+| `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 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. |
+| `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. Exits 1 on a failed check. |
+| `status` | The sandbox, the sales channel client id, the published storefront, what is applied, pending changes, 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
+`init` writes a commented template. A filled-in store looks like this:
+```yaml
+name: Beans
+markets:
+  # One market per region you sell in. countries are ISO 3166 codes.
+  # shipping is optional: without it orders ship free as "Standard".
+  - code: eu
+    name: Europe
+    countries: [IT, FR, DE, ES]
+    currency: EUR
+    shipping: { method: Standard, price: 4.90, days: 3-5 }
+  - code: us
+    name: United States
+    countries: [US]
+    currency: USD
+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.
+    image_url: https://example.com/eth.jpg
+    prices: { EUR: 14.50, USD: 16.00 }
+storefront:
+  # The web app in this repo that sells the products, relative to the repo root.
+  path: storefront
+policies:
+  # Pages shopping agents show buyers before they pay. Without them the store
+  # serves default sandbox pages at <preview_url>/policies/<name>.
+  privacy_policy: https://example.com/privacy
+  terms_of_service: https://example.com/terms
+  returns: https://example.com/returns
+```
+### 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.
+```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
+```
+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.
+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:
+| What | Where |
+| --- | --- |
+| Business profile | `GET /.well-known/ucp` (`Cache-Control: public, max-age=300`, ES256 public key in `keys[]`) |
+| Shopping service `dev.ucp.shopping` | `/ucp/v1`: `POST /catalog/search`, `POST /catalog/lookup`, `POST /catalog/product`, `POST /carts`, `GET/PUT /carts/{id}`, `POST /carts/{id}/cancel`, `POST /checkout-sessions`, `GET/PUT /checkout-sessions/{id}`, `POST /checkout-sessions/{id}/complete`, `POST /checkout-sessions/{id}/cancel`, `GET /orders/{id}` |
+| Common service `dev.ucp.common` | `/ucp/v1`: `POST /ask` |
+| Extensions | `dev.ucp.shopping.fulfillment` (one shipping method per market, from `shipping` in `store.yml`), `dev.ucp.shopping.discount` (the sandbox accepts code `SANDBOX10`, 10% off the items), `dev.ucp.shopping.buyer_consent`, `dev.ucp.shopping.policy.return` (30-day returns) |
+| Identity linking `dev.ucp.common.identity_linking` | `GET /.well-known/oauth-authorization-server`, `GET /oauth/authorize` (PKCE S256; the sandbox approves at once), `POST /oauth/token` (`authorization_code`, `client_credentials`), `POST /oauth/revoke`, `GET /oauth/jwks`. Scopes `dev.ucp.shopping.order:read`, `dev.ucp.shopping.order:manage`. |
+| Permalink `dev.ucp.shopping.permalink` | `GET /buy/{sku}:{qty}[,...]?context/postal_code=…&discounts/codes/0=…` → `303` to the cart |
+| Payment handler `ai.commercelayer.sandbox` | id `cl_sandbox`, `card` instruments, credential `{ "type": "sandbox_token", "token": "sbx_tok_success" \| "sbx_tok_declined", "expiry": … }`. No money moves. |
+| Pages | `/policies/{privacy,terms,returns}` (defaults when `store.yml` has no `policies`), `/carts/{id}`, `/checkout-sessions/{id}` (`continue_url`), `/orders/{id}` (`permalink_url`), and the published storefront at `/`. |
+Transport rules the store enforces: `UCP-Agent` (an HTTPS platform profile URL) and `Request-Id` on every request; `Idempotency-Key` on every state change, replayed when the body matches and `409` when it does not; `Content-Digest` verified when present. Every service response carries `Content-Digest`, `Signature-Input` and `Signature` (ES256 over `@status`, `content-digest`, `content-type`, key `kid` from the profile). Orders are private: readable by the platform that placed them or with a buyer token carrying an order scope; anything else gets `401` with `WWW-Authenticate: Bearer`. Catalog ids are the skus (`product.id` is `prod_<sku>`, `variant.id` is the sku); amounts are integers in minor units.
+The CLI is a UCP **platform**: its profile is served at `https://commercelayer.ai/ucp/agent-cli/profile.json` (`ucp profile --agent` prints it) and goes in `UCP-Agent` on every call. The store negotiates the capability intersection with it. `orders test` is the buyer; `ucp check` runs 30-odd checks across profile, transport rules, catalog, cart, discount, checkout, fulfillment, consent, payment, signatures, idempotency, order, identity linking, ask and permalink.
+## Requirements
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node 20 or later. One runtime dependency (`yaml`).
+
+## Links and license
+
+- [commercelayer.ai/start.md](https://commercelayer.ai/start.md): the entry point an agent reads.
+- [Universal Commerce Protocol](https://ucp.dev): the protocol every store speaks.
+- [`@commercelayer/cli`](https://www.npmjs.com/package/@commercelayer/cli): the Commerce Layer CLI for humans.
+- [Commerce Layer](https://commercelayer.io): the commerce API behind the stores.
+
+MIT. Copyright Commerce Layer.

package/dist/api/client.js

@@ -0,0 +1,39 @@
+// The client for the management API at api.commercelayer.ai.
+import { fail } from '../output.js';
+import { apiUrl, DEFAULT_API_URL, send } from './transport.js';
+export function createApi(auth) {
+    const base = apiUrl() === 'stub' ? DEFAULT_API_URL : apiUrl().replace(/\/$/, '');
+    const org = () => {
+        if (!auth)
+            fail('no_store', 'There is no store in this repo.', 'Run `c11r init` in the repo root first.');
+        return `/stores/${auth.org}`;
+    };
+    const request = async (method, path, body) => {
+        const headers = { accept: 'application/json' };
+        if (auth)
+            headers.authorization = `Bearer ${auth.token}`;
+        const res = await send(method, base + path, headers, body === undefined ? undefined : JSON.stringify(body));
+        let data;
+        try {
+            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`.');
+        }
+        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`.');
+    };
+    return {
+        createSandbox: (name) => request('POST', '/sandboxes', { name }),
+        getStore: () => request('GET', org()),
+        applyStore: (body) => request('PUT', `${org()}/resources`, body),
+        publishStorefront: (path, files) => request('PUT', `${org()}/storefront`, { path, files }),
+        listOrders: () => request('GET', `${org()}/orders`),
+        getOrder: (id) => request('GET', `${org()}/orders/${encodeURIComponent(id)}`),
+        startClaim: () => request('POST', `${org()}/claim`),
+    };
+}

package/dist/api/server.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Serve the stub platform over HTTP, so the CLI's real HTTP client can be exercised:
+//   npm run stub-api                       (port 4747)
+//   C11R_API_URL=http://localhost:4747 c11r init
+// Store hosts are reached as http://localhost:4747/-/<org>.sandbox.commercelayer.store/...
+// or with a real Host header.
+import http from 'node:http';
+import { handle } from './stub/index.js';
+const port = Number(process.env.PORT ?? 4747);
+http
+    .createServer((req, res) => {
+    let raw = '';
+    req.on('data', (chunk) => (raw += chunk));
+    req.on('end', () => {
+        const headers = {};
+        for (const [k, v] of Object.entries(req.headers))
+            if (typeof v === 'string')
+                headers[k.toLowerCase()] = v;
+        const host = headers.host ?? `localhost:${port}`;
+        const url = new URL(req.url ?? '/', `http://${host}`);
+        const { status, headers: resHeaders, body } = handle({ method: req.method ?? 'GET', url, headers, body: raw || undefined });
+        res.writeHead(status, resHeaders);
+        res.end(body);
+    });
+})
+    .listen(port, () => console.log(`stub platform on http://localhost:${port}`));

package/dist/api/stub/db.js

@@ -0,0 +1,37 @@
+// The stub's state: one JSON file, one record per sandbox. The real platform keeps
+// the same data behind api.commercelayer.ai and the store hosts.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const dbFile = process.env.C11R_STUB_DB
+    ?? path.join(process.env.XDG_STATE_HOME ?? path.join(os.homedir(), '.local', 'state'), 'c11r', 'stub-api.json');
+export function readDb() {
+    return fs.existsSync(dbFile) ? JSON.parse(fs.readFileSync(dbFile, 'utf8')) : {};
+}
+export function writeDb(db) {
+    fs.mkdirSync(path.dirname(dbFile), { recursive: true });
+    fs.writeFileSync(dbFile, JSON.stringify(db, null, 2) + '\n');
+}
+export const SANDBOX_DOMAIN = 'sandbox.commercelayer.store';
+/** The org a store hostname belongs to, or null if it is not a store host. */
+export function orgOfHost(hostname) {
+    const m = hostname.match(/^([a-z0-9-]+)\.sandbox\.commercelayer\.store$/);
+    return m ? m[1] : null;
+}
+/** Orders of a store, newest first, without private members. */
+export function publicOrders(r) {
+    return Object.values(r.ucp.orders).map((o) => strip(o)).reverse();
+}
+/** A deep copy without the members whose name starts with _. */
+export function strip(value) {
+    if (Array.isArray(value))
+        return value.map(strip);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            if (!k.startsWith('_'))
+                out[k] = strip(v);
+        return out;
+    }
+    return value;
+}

package/dist/api/stub/http.js

@@ -0,0 +1,18 @@
+// The HTTP shapes the stub works with: what a Cloudflare Worker would see. Keeping
+// the stub HTTP-shaped lets UCP headers (UCP-Agent, Idempotency-Key, signatures)
+// be modelled the way the real API will have to handle them.
+export function json(status, body, headers = {}) {
+    return { status, headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(body) };
+}
+/** The management API's error shape, the same the CLI prints. */
+export function error(status, code, message, hint) {
+    return json(status, { error: { code, message, hint } });
+}
+export function readJson(req) {
+    if (!req.body)
+        return undefined;
+    return JSON.parse(req.body);
+}
+export function bearer(req) {
+    return req.headers.authorization?.replace(/^Bearer /i, '');
+}

package/dist/api/stub/index.js

@@ -0,0 +1,27 @@
+// A stand-in for the whole platform: api.commercelayer.ai (management) and
+// <org>.sandbox.commercelayer.store (the store: UCP, OAuth, the storefront).
+// server.ts serves it over HTTP; transport.ts calls handle() in-process when
+// C11R_API_URL=stub, so agent tests need no server running.
+//
+// Routing is by hostname. Over local HTTP, where subdomains do not resolve, the
+// path prefix /-/<host>/... stands in for the hostname.
+import { orgOfHost, readDb, writeDb } from './db.js';
+import { json } from './http.js';
+import { handleManagement } from './management.js';
+import { handleUcp } from './ucp.js';
+export function handle(req) {
+    let url = req.url;
+    const prefixed = url.pathname.match(/^\/-\/([^/]+)(\/.*)?$/);
+    if (prefixed)
+        url = new URL(`https://${prefixed[1]}${prefixed[2] ?? '/'}${url.search}`);
+    const org = orgOfHost(url.hostname);
+    if (org === null)
+        return handleManagement({ ...req, url });
+    const db = readDb();
+    const store = db[org];
+    if (!store)
+        return json(404, { error: { code: 'not_found', message: `There is no store at ${url.hostname}.`, hint: 'The sandbox may have expired.' } });
+    const res = handleUcp({ ...req, url }, store);
+    writeDb(db);
+    return res;
+}

package/dist/api/stub/management.js

@@ -0,0 +1,86 @@
+// 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 { 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, name: _name, policies: _policies, ...state } = r;
+    return { ...state, orders: publicOrders(r) };
+}
+export function handleManagement(req) {
+    const db = readDb();
+    const path = req.url.pathname;
+    if (req.method === 'POST' && path === '/sandboxes') {
+        const name = String(readJson(req)?.name ?? 'store');
+        const slug = `${name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'store'}-${crypto.randomBytes(2).toString('hex')}`;
+        const expires = new Date(Date.now() + 7 * 24 * 3600 * 1000);
+        expires.setUTCHours(0, 0, 0, 0);
+        const kid = `${slug}-${new Date().toISOString().slice(0, 7)}`;
+        const { privateJwk, publicJwk } = generateKey(kid);
+        const record = {
+            org: slug,
+            token: `sbx_${crypto.randomBytes(16).toString('hex')}`,
+            sandbox: true,
+            claimed: false,
+            claim_url: `https://commercelayer.ai/claim/${crypto.randomBytes(6).toString('hex')}`,
+            expires_at: expires.toISOString(),
+            preview_url: `https://${slug}.${SANDBOX_DOMAIN}`,
+            sales_channel_client_id: `sc_${crypto.randomBytes(12).toString('hex')}`,
+            storefront: null,
+            applied: null,
+            applied_hash: null,
+            ucp: { kid, private_jwk: privateJwk, public_jwk: publicJwk, carts: {}, checkouts: {}, orders: {}, idempotency: {}, webhooks: [], tokens: {}, codes: {}, files: {} },
+        };
+        db[slug] = record;
+        writeDb(db);
+        const { org, token, claim_url, expires_at, preview_url, sales_channel_client_id } = record;
+        return json(201, { org, token, claim_url, expires_at, preview_url, sales_channel_client_id });
+    }
+    const m = path.match(/^\/stores\/([^/]+)(\/.*)?$/);
+    if (!m)
+        return error(404, 'not_found', `No route ${req.method} ${path}.`, 'Check the command; run `c11r help`.');
+    const [, org, rest = ''] = m;
+    const record = db[org];
+    if (!record || record.token !== bearer(req)) {
+        return error(401, 'unauthorized', `No sandbox ${org} for this token.`, 'The sandbox may have expired or the credentials file may be stale. Remove .commercelayer/credentials and run `c11r init` again.');
+    }
+    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 === '')
+        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;
+        record.name = name;
+        record.policies = policies ?? {};
+        writeDb(db);
+        return json(200, publicState(record));
+    }
+    if (req.method === 'PUT' && rest === '/storefront') {
+        const { path: dir, files } = readJson(req);
+        if (!files?.some((f) => f.path === 'index.html')) {
+            return error(422, 'no_storefront', 'The upload has no index.html.', 'Run `c11r storefront init` to create one, or set storefront.path in store.yml to the folder that has index.html.');
+        }
+        record.ucp.files = Object.fromEntries(files.map((f) => [f.path, f.content_base64]));
+        record.storefront = { path: dir, files: files.length, published_at: new Date().toISOString() };
+        writeDb(db);
+        return json(200, record.storefront);
+    }
+    if (req.method === 'GET' && rest === '/orders')
+        return json(200, publicOrders(record));
+    const one = rest.match(/^\/orders\/([^/]+)$/);
+    if (req.method === 'GET' && one) {
+        const wanted = decodeURIComponent(one[1]);
+        const found = publicOrders(record).find((o) => o.id === wanted || o.label === wanted || o.label === `#${wanted}`);
+        if (!found)
+            return error(404, 'not_found', `There is no order ${wanted}.`, 'Run `c11r orders list` to see the orders.');
+        return json(200, found);
+    }
+    if (req.method === 'POST' && rest === '/claim') {
+        return json(200, { verification_url: 'https://commercelayer.ai/device', user_code: 'BXQT-4KMF' });
+    }
+    return error(404, 'not_found', `No route ${req.method} ${path}.`, 'Check the command; run `c11r help`.');
+}