@commercelayer/agent-cli 0.1.2 → 0.1.4

package/README.md

@@ -3,7 +3,7 @@
 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
+npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # 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.
@@ -13,8 +13,8 @@ npx -y @commercelayer/agent-cli@latest init   # runs c11r init
 ## 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. |
+| `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. |
 | `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. |
@@ -22,8 +22,8 @@ npx -y @commercelayer/agent-cli@latest init   # runs c11r init
 | `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. |
+| `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. |
 | `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

package/dist/api/stub/management.js

@@ -5,15 +5,20 @@ 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) };
+    const { token: _token, ucp: _ucp, ...state } = r;
+    return { ...state, name: r.name ?? null, policies: r.policies ?? null, orders: publicOrders(r) };
 }
 export function handleManagement(req) {
     const db = readDb();
     const path = req.url.pathname;
     if (req.method === 'POST' && path === '/sandboxes') {
+        // Like Commerce Layer: the organization is named `name`, and its slug is derived
+        // from it, suffixed -2, -3, ... when taken. The slug is the org and the store host.
         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 base = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'store';
+        let slug = base;
+        for (let n = 2; db[slug]; n++)
+            slug = `${base}-${n}`;
         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)}`;

package/dist/bin.js

@@ -4,7 +4,7 @@
 // Output is always JSON; exit code 1 on an error or a failed check.
 import * as cmd from './commands.js';
 import { CliError, print } from './output.js';
-const VALUE_OPTIONS = new Set(['--sku', '--quantity', '--country', '--code']);
+const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code']);
 const argv = process.argv.slice(2);
 const flags = new Set();
 const values = {};
@@ -32,7 +32,7 @@ async function run() {
         case 'help':
             return cmd.help(args.slice(1).join(' ') || undefined);
         case 'init':
-            return cmd.init();
+            return cmd.init(values);
         case 'plan':
             return cmd.plan();
         case 'apply':

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 { fail } from './output.js';
+import { CliError, fail } from './output.js';
 import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from './store.js';
 import { storefrontHtml } from './storefront.js';
 import { buy } from './ucp/buy.js';
@@ -15,8 +15,8 @@ import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
 /** 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).',
+    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.',
     'storefront init': 'Write storefront/index.html: a static page on drop-in.js listing the products in store.yml, with 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.',
@@ -24,8 +24,8 @@ export const HELP = {
     'orders list': 'List the orders placed in the store, newest first, as UCP order entities.',
     'orders show': 'Show one order: c11r orders show <id or number>.',
     'ucp profile': 'Show the store\'s UCP business profile (/.well-known/ucp). With --agent, this CLI\'s own platform profile instead.',
-    'ucp check': 'Walk every UCP capability the store advertises and report what passes. Exits 1 when a check fails.',
-    status: 'Show the sandbox, what is applied, and whether store.yml has changes not yet applied.',
+    '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.',
 };
@@ -38,13 +38,17 @@ export function help(name) {
     }
     return { version: VERSION, commands: HELP, note: 'Every command prints JSON. The store format is documented in the comments of .commercelayer/store.yml; large catalogs go in .commercelayer/products/ as .yml or .csv files.' };
 }
-export async function init() {
+export async function init(values) {
     const existing = readCredentials();
     if (existing && fs.existsSync(paths.store)) {
         const s = await createApi(existing).getStore();
         return { status: 'reused', org: s.org, claim_url: s.claim_url, expires_at: s.expires_at, preview_url: s.preview_url };
     }
-    const name = path.basename(process.cwd());
+    // The business name becomes the organization's name; the platform derives the
+    // org slug (and so the store hostname) from it. The folder name is the fallback.
+    if (values.name !== undefined && !values.name.trim())
+        fail('invalid_argument', '--name needs the business name.', 'Example: c11r init --name "The Blue Brand". Leave it out to use the folder name.');
+    const name = values.name?.trim() || path.basename(process.cwd());
     const sandbox = await createApi(null).createSandbox(name);
     fs.mkdirSync(paths.dir, { recursive: true });
     if (!fs.existsSync(paths.store))
@@ -56,6 +60,7 @@ export async function init() {
     return {
         status: 'created',
         org: sandbox.org,
+        name,
         claim_url: sandbox.claim_url,
         expires_at: sandbox.expires_at,
         preview_url: sandbox.preview_url,
@@ -67,14 +72,14 @@ export async function plan() {
     const api = createApi(requireCredentials());
     const desired = loadStore();
     const state = await api.getStore();
-    const changes = diff(state.applied, desired);
+    const changes = diff(state, desired);
     return { status: changes.length ? 'changes' : 'up_to_date', changes, deletes: changes.filter((c) => c.action === 'delete').length };
 }
 export async function apply(flags) {
     const api = createApi(requireCredentials());
     const desired = loadStore();
     const state = await api.getStore();
-    const changes = diff(state.applied, desired);
+    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`.');
@@ -168,11 +173,27 @@ export async function ucpProfile(flags) {
 export async function ucpCheck() {
     const origin = await storeOrigin();
     const report = await check(origin);
-    return { ...report, next: report.status === 'pass' ? 'Any shopping agent can buy from this store.' : 'Fix the failed checks and run `c11r ucp check` again.' };
+    return {
+        ...report,
+        note: report.order ? `The checkout checks placed and paid a real test order (${report.order.label ?? report.order.id}) with the sandbox handler; it appears in \`c11r orders list\` like one from \`orders test\`.` : undefined,
+        next: report.status === 'pass' ? 'Any shopping agent can buy from this store.' : 'Fix the failed checks and run `c11r ucp check` again.',
+    };
 }
 export async function status() {
     const api = createApi(requireCredentials());
     const s = await api.getStore();
+    // Pending means exactly what plan would list, so the two never disagree. If
+    // the store files do not even load, that is pending too, with the error.
+    let pending = [];
+    let storeError;
+    try {
+        pending = diff(s, loadStore());
+    }
+    catch (e) {
+        if (!(e instanceof CliError))
+            throw e;
+        storeError = { code: e.code, message: e.message, hint: e.hint };
+    }
     return {
         org: s.org,
         sandbox: s.sandbox,
@@ -182,11 +203,14 @@ export async function status() {
         sales_channel_client_id: s.sales_channel_client_id,
         storefront: s.storefront,
         applied: Boolean(s.applied),
-        pending_changes: s.applied_hash !== hashStore(),
+        pending_changes: pending.length > 0 || storeError !== undefined,
+        pending: pending.length ? pending : undefined,
+        store_error: storeError,
         markets: s.applied ? Object.keys(s.applied.markets) : [],
         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,
     };
 }
 export async function claim() {

package/dist/store.js

@@ -152,8 +152,17 @@ export function toApplied(store) {
         products: Object.fromEntries(store.products.map((p) => [p.sku, p])),
     };
 }
-export function diff(applied, desired) {
+const canonical = (v) => JSON.stringify(v ?? {}, (_k, x) => (x === undefined ? undefined : x));
+/** The one definition of "pending changes": what apply would do. plan and status both use it. */
+export function diff(state, desired) {
     const changes = [];
+    const { applied } = state;
+    if (applied) {
+        if (state.name !== undefined && state.name !== null && state.name !== desired.name)
+            changes.push({ action: 'update', type: 'store', id: 'name' });
+        if (state.policies !== undefined && canonical(state.policies) !== canonical(desired.policies))
+            changes.push({ action: 'update', type: 'store', id: 'policies' });
+    }
     const after = toApplied(desired);
     for (const kind of ['markets', 'products']) {
         const type = kind.slice(0, -1);

package/dist/ucp/check.js

@@ -235,6 +235,7 @@ export async function check(origin) {
         return 'payment_failed';
     });
     let completeCall = null;
+    let placed;
     let orderId = null;
     const key = crypto.randomUUID();
     const completeBody = { payment: { instruments: [sandboxInstrument()] }, signals: { 'dev.ucp.buyer_ip': '203.0.113.1', 'dev.ucp.user_agent': 'c11r' } };
@@ -246,6 +247,7 @@ export async function check(origin) {
         must(done.continue_url === undefined && done.expires_at === undefined, 'completed checkouts should omit continue_url and expires_at');
         must(JSON.stringify(done.payment ?? {}).includes('"token"') === false, 'the credential token must not be echoed');
         orderId = done.order.id;
+        placed = { id: done.order.id, label: done.order.label };
         return `order ${done.order.id} ${done.order.label ?? ''}`;
     });
     await run('signatures', 'the completion response is signed and verifies', async () => {
@@ -347,9 +349,12 @@ export async function check(origin) {
             return `303 → ${res.headers.location}`;
         });
     }
-    return finish(origin, checks);
+    return finish(origin, checks, placed);
 }
-function finish(origin, checks) {
+function finish(origin, checks, order) {
     const failed = checks.filter((c) => !c.pass).length;
-    return { status: failed ? 'fail' : 'pass', store: origin, version: UCP_VERSION, passed: checks.length - failed, failed, checks };
+    const report = { status: failed ? 'fail' : 'pass', store: origin, version: UCP_VERSION, passed: checks.length - failed, failed, checks };
+    if (order)
+        report.order = order;
+    return report;
 }

package/package.json

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