@commercelayer/agent-cli 0.1.0 → 0.1.2

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,37 +1,16 @@
 # @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
 ```
-
-## The four repos of commercelayer.ai
-
-commercelayer.ai lets a coding agent build and run a store on Commerce Layer. A human pastes one prompt, the agent reads `start.md`, runs the CLI, and the human ends up with a store in a sandbox that both people and shopping agents can buy from. It is four repos, siblings in the same workspace:
-
-| Repo | What it is | Where it runs |
-| --- | --- | --- |
-| `commercelayer-ai-site` | the website and the agent-facing docs: `start.md`, `skills.md`, `skills/*.md`, plus the CLI's UCP platform profile and the sandbox payment-handler schema | commercelayer.ai, Cloudflare Pages |
-| `commercelayer-ai-cli` | `@commercelayer/agent-cli`, the CLI the agent runs as `c11r`: `init`, `plan`, `apply`, `storefront`, `orders test`, `ucp check`, `claim`. Prints JSON only. | npm, in the agent's repo |
-| `commercelayer-ai-api` | the management API the CLI talks to: sandboxes and their life cycle, `apply`, storefront uploads, orders, claims | api.commercelayer.ai, Cloudflare Worker |
-| `commercelayer-ai-store` | the store host: every store's website and its [UCP](https://ucp.dev) merchant endpoints (release 2026-08-25) | `<org>.sandbox.commercelayer.store` and, once live, `<org>.commercelayer.store`, Cloudflare Worker |
-
-**This repo is the CLI.** It owns everything the agent runs: the commands and their JSON, the store files in the agent's repo (`.commercelayer/store.yml` and `.commercelayer/products/`), the drop-in.js storefront scaffold, the UCP buyer and conformance check, and the stub of the whole platform in `src/api/stub/`, which is the reference the API and the store host are ported from. It depends on the API for the management contract in `src/api/types.ts`, on the store host for the UCP surface, and on the site for the platform profile and handler schema it names in `src/ucp/platform.ts`; a change to the stub is mirrored in the API and the store host, and a change to the management contract is mirrored in the API. The site depends on it: every command, flag, file and JSON field the skills describe must exist here, so a change to the commands or the store files is mirrored on the site.
-
 ## 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. |
@@ -47,14 +26,10 @@ commercelayer.ai lets a coding agent build and run a store on Commerce Layer. A
 | `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".
@@ -67,7 +42,6 @@ markets:
     name: United States
     countries: [US]
     currency: USD
-
 products:
   # sku is unique and stays the same when you rename a product.
   - sku: COFFEE-ETH-250
@@ -75,11 +49,9 @@ products:
     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>.
@@ -87,30 +59,20 @@ policies:
   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[]`) |
@@ -121,40 +83,17 @@ Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (liv
 | 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
 
-## The management API
-
-The CLI keeps no state of its own: the store lives behind `api.commercelayer.ai` (the `commercelayer-ai-api` Worker) and the store hosts (the `commercelayer-ai-store` Worker). This repo ships a stub of the whole platform with the same routes, which both Workers are ported from and tested against. `src/api/types.ts` is the management contract; `src/api/stub/management.ts` is the reference for the API, and `src/api/stub/ucp.ts` and `shopping.ts` are the reference for the store host. A change to the stub is mirrored in the Worker it belongs to.
-
-| Route | Auth | Does |
-| --- | --- | --- |
-| `POST /sandboxes` `{ name }` | none | Create a sandbox with one sales channel and one signing key. Returns `org`, `token`, `claim_url`, `expires_at`, `preview_url`, `sales_channel_client_id`. |
-| `GET /stores/:org` | bearer | The store: `applied`, `applied_hash`, `orders` (UCP entities, newest first), `storefront`, `sales_channel_client_id`, `claimed`, `expires_at`, `preview_url`, `claim_url`. |
-| `PUT /stores/:org/resources` `{ applied, hash, name, policies }` | bearer | Make the store match the resources (markets by code, products by sku). `hash` digests every store file on disk; `status` compares it to report pending changes. Market scopes are `market:code:<code>`. |
-| `PUT /stores/:org/storefront` `{ path, files: [{ path, content_base64 }] }` | bearer | Replace the static files served at the store host. `422 no_storefront` without an `index.html`. Returns `{ path, files, published_at }`. (The real API should take a `tar.gz` body with a size cap; base64 JSON is fine for the sandbox.) |
-| `GET /stores/:org/orders` | bearer | The orders, newest first. |
-| `GET /stores/:org/orders/:id` | bearer | One order, by id or label number, or `404 not_found`. |
-| `POST /stores/:org/claim` | bearer | Start the device flow: `verification_url`, `user_code`. |
-
-Errors come back as `{ "error": { "code", "message", "hint" } }` with 4xx/5xx and are printed as they are.
+Node 20 or later. One runtime dependency (`yaml`).
 
-`C11R_API_URL` picks the platform:
+## Links and license
 
-- unset: `https://api.commercelayer.ai` and the real store hosts
-- `stub`: the stub in-process, state in `~/.local/state/c11r/stub-api.json` (or `$C11R_STUB_DB`). No server to run; what agent tests use.
-- `http://localhost:4747`: the stub over HTTP (`npm run stub-api`), to exercise the real client. Store hosts are reached as `http://localhost:4747/-/<org>.sandbox.commercelayer.store/...` or with a `Host` header.
-
-## Development
-
-```
-npm install
-npm run dev -- help              # run from source
-npm test                         # build, then end-to-end tests against the in-process stub
-npm run stub-api                 # serve the stub platform on :4747
-```
+- [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.
 
-Node 20 or later, one runtime dependency (`yaml`). Source in `src/`: `bin.ts` parses arguments, `commands.ts` has one function per command, `store.ts` validates and diffs the store, `products.ts` reads the product files (YAML and CSV), `files.ts` handles the files in the repo, `storefront.ts` is the drop-in.js scaffold; `api/` is the management client, its contract, the transport and the stub (`stub/management.ts`, `stub/ucp.ts`, `stub/shopping.ts`); `ucp/` is the UCP side: `platform.ts` (this CLI's profile and shared constants), `client.ts` (discovery and the REST calls), `signing.ts` (RFC 9421/9530), `buy.ts` (the buyer flow), `check.ts` (the conformance walk).
+MIT. Copyright Commerce Layer.

package/dist/commands.js

@@ -1,6 +1,7 @@
 // One function per command. Each returns the object the CLI prints, or throws a
 // CliError. Every command is safe to re-run.
 import fs from 'node:fs';
+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';
@@ -11,7 +12,8 @@ import { buy } from './ucp/buy.js';
 import { check } from './ucp/check.js';
 import { discover } from './ucp/client.js';
 import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
-export const VERSION = '0.1.0';
+/** The package version, read from package.json so a release bumps it in one place. */
+export const VERSION = createRequire(import.meta.url)('../package.json').version;
 export const HELP = {
     init: 'Create a sandbox store for this repo, with no login. Writes .commercelayer/store.yml and .commercelayer/credentials. Reuses the store if store.yml already exists.',
     plan: 'Show what apply would create, update or delete, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',

package/package.json

@@ -1,14 +1,23 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": [
+    "commercelayer",
+    "commerce",
+    "cli",
+    "agent",
+    "ucp",
+    "sandbox"
+  ],
   "license": "MIT",
   "type": "module",
   "engines": {
     "node": ">=20"
   },
   "bin": {
-    "c11r": "./dist/bin.js"
+    "c11r": "dist/bin.js"
   },
   "files": [
     "dist",

package/dist/api/stub.js

@@ -1,112 +0,0 @@
-// A stand-in for api.commercelayer.ai: the same routes, answered from a JSON file.
-// server.ts serves it over HTTP; client.ts can also call handle() in-process when
-// COMMERCELAYER_AI_API_URL=stub, so agent tests need no server running.
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-const dbFile = process.env.COMMERCELAYER_AI_STUB_DB
-    ?? path.join(process.env.XDG_STATE_HOME ?? path.join(os.homedir(), '.local', 'state'), 'commercelayer-ai', 'stub-api.json');
-function readDb() {
-    return fs.existsSync(dbFile) ? JSON.parse(fs.readFileSync(dbFile, 'utf8')) : {};
-}
-function writeDb(db) {
-    fs.mkdirSync(path.dirname(dbFile), { recursive: true });
-    fs.writeFileSync(dbFile, JSON.stringify(db, null, 2) + '\n');
-}
-function error(status, code, message, hint) {
-    return { status, body: { error: { code, message, hint } } };
-}
-function publicState(r) {
-    const { token: _token, ...state } = r;
-    return state;
-}
-export function handle(req) {
-    const db = readDb();
-    if (req.method === 'POST' && req.path === '/sandboxes') {
-        const name = String(req.body?.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 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.commercelayer.store`,
-            sales_channel_client_id: `sc_${crypto.randomBytes(12).toString('hex')}`,
-            storefront: null,
-            applied: null,
-            applied_hash: null,
-            orders: [],
-        };
-        db[slug] = record;
-        writeDb(db);
-        const { org, token, claim_url, expires_at, preview_url, sales_channel_client_id } = record;
-        return { status: 201, body: { org, token, claim_url, expires_at, preview_url, sales_channel_client_id } };
-    }
-    const m = req.path.match(/^\/stores\/([^/]+)(\/.*)?$/);
-    if (!m)
-        return error(404, 'not_found', `No route ${req.method} ${req.path}.`, 'Check the command; run `commercelayer-ai help`.');
-    const [, org, rest = ''] = m;
-    const record = db[org];
-    if (!record || record.token !== req.token) {
-        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 `commercelayer-ai 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 `commercelayer-ai init` to create a new sandbox; store.yml is kept.');
-    }
-    if (req.method === 'GET' && rest === '')
-        return { status: 200, body: publicState(record) };
-    if (req.method === 'PUT' && rest === '/resources') {
-        const { applied, hash } = req.body;
-        record.applied = applied;
-        record.applied_hash = hash;
-        writeDb(db);
-        return { status: 200, body: publicState(record) };
-    }
-    if (req.method === 'PUT' && rest === '/storefront') {
-        const { path: dir, files } = req.body;
-        if (!files?.some((f) => f.path === 'index.html')) {
-            return error(422, 'no_storefront', 'The upload has no index.html.', 'Run `commercelayer-ai storefront init` to create one, or set storefront.path in store.yml to the folder that has index.html.');
-        }
-        // The real API serves these files at preview_url; the stub only remembers them.
-        record.storefront = { path: dir, files: files.length, published_at: new Date().toISOString() };
-        writeDb(db);
-        return { status: 200, body: record.storefront };
-    }
-    if (req.method === 'GET' && rest === '/orders')
-        return { status: 200, body: [...record.orders].reverse() };
-    const order = rest.match(/^\/orders\/(\d+)$/);
-    if (req.method === 'GET' && order) {
-        const found = record.orders.find((o) => String(o.number) === order[1]);
-        if (!found)
-            return error(404, 'not_found', `There is no order ${order[1]}.`, 'Run `commercelayer-ai orders list` to see the order numbers.');
-        return { status: 200, body: found };
-    }
-    if (req.method === 'POST' && rest === '/orders/test') {
-        if (!record.applied)
-            return error(409, 'not_applied', 'The store has nothing applied yet.', 'Run `commercelayer-ai apply` first.');
-        const market = Object.values(record.applied.markets)[0];
-        const product = Object.values(record.applied.products)[0];
-        const order = {
-            number: 1001 + record.orders.length,
-            status: 'paid',
-            market: market.code,
-            currency: market.currency,
-            total: product.prices[market.currency],
-            items: [{ sku: product.sku, quantity: 1 }],
-            payment_gateway: 'sandbox',
-            payment: 'captured',
-        };
-        record.orders.push(order);
-        writeDb(db);
-        return { status: 201, body: order };
-    }
-    if (req.method === 'POST' && rest === '/claim') {
-        return { status: 200, body: { verification_url: 'https://commercelayer.ai/device', user_code: 'BXQT-4KMF' } };
-    }
-    return error(404, 'not_found', `No route ${req.method} ${req.path}.`, 'Check the command; run `commercelayer-ai help`.');
-}