@commercelayer/agent-cli 1.0.0-dev.12 → 1.0.0-dev.14

package/README.md

@@ -15,7 +15,7 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 - Flags are the schema's fields, in kebab or snake case: `--price-list` and `--price_list` are the same.
 - On `list`, `--<field> <value>` filters by equality and `--<field>.<op> <value>` by another operator: `--placed-at.gte 2026-11-01`, `--status.in placed,approved`. `--waiting` lists what needs a decision now.
 - A ref flag, or one the schema marks `nullable`, given `null` or an empty value sends `null` and takes it off: `c11r customers update ada@example.com --customer-group null` sends `customer_group: null`, `c11r orders update 1001 --coupon-code null` sends `coupon_code: null`. A ref the schema marks `nullable: false`, and any other field, sends the text.
-- A dotted flag sets part of an object: `--customer.email ada@example.com`. An `in` filter takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it (`--tax-calculator.in "UK VAT, manual"`), and a list that has one is sent as a JSON array. Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2`. `--data` takes the fields as one JSON object, or `@` and a file name.
+- A dotted flag sets part of an object: `--customer.email ada@example.com`. An `in` filter takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it (`--tax-calculator.in "UK VAT, manual"`), and a list that has one is sent as a JSON array. Any other array takes the flag repeated or a JSON array, and the same rule holds: enums, numbers and dates also separated by commas, a name or text one value per flag (`--payment-settings "Invoice, 60 days"`); an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2`. `--data` takes the fields as one JSON object, or `@` and a file name.
 - Amounts are in major units: `--amount 12.50`.
 - A secret field the schema marks `secret_input` (provider credentials) has no flag of its own: `--credentials-file <file>` reads it, as JSON or `KEY=value` lines, from a plain file only its owner can read (mode 600). Without the file, a terminal asks for it without echo; with neither, the command stops with `secret_required`. It is refused as a flag value or in `--data`, and never printed.
 - A field with documented values the API does not enforce (`known`: webhook topics) takes any value. One outside them is sent anyway, with the warning `unknown_value` and `did_you_mean`. Help lists up to 20 of them, and past that says how many and that `c11r schema <noun>` has them all.
@@ -35,6 +35,9 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 | `c11r report sales [--from] [--to] [--by] [--interval] [--market] [--top]` | Sales in a window, from the Metrics API. A plain noun: its flags come from the API's schema. |
 | `c11r auth login [--client-id] [--secret-file] [--keep-file]` | The human's own Commerce Layer login, from their Provisioning API application. See below. |
 | `c11r auth logout`, `auth switch <slug> [--global]` | Forgetting the login; the organization commands act on. |
+| `c11r shop profile\|search\|get\|ask <store>` | Reading a store that speaks UCP, as a shopping agent: what it offers, its catalog, a variant, a question. No organization. See below. |
+| `c11r skills sync` | Local copies of the Commerce Layer skills in `.claude/skills`, from the index at commercelayer.ai, listed in `AGENTS.md`. No organization. See below. |
+| `c11r shop checkout <store> [<checkout>]`, `shop order <store> <checkout>` | Buying there for the human: their details after their yes on what is shared, then the payment after their yes on the total, with the sandbox test handler only. |
 
 A loop runs a skill a Manage or Report noun's schema names in `loop.skill`, or in `loop.skills` for a noun with several (`manage-orders`, `manage-stock`, `report-sales`, `report-pending`, ...); a report loop allows no verb and only reports. create and update refuse any other skill, and any verb that loop does not list, with the allowed values. A loop policy allows verbs: a bare verb is the skill's own noun (`approve`), `<noun>.<verb>` another Manage noun's verb on the same item (`payments.capture`). Verbs that delete or return money are never open to a policy.
 
@@ -83,7 +86,7 @@ Records that share a key (two shipping methods with the same name in one market,
 
 After a Configure write that went through (create, update, delete or a domain verb), in a folder whose `store.yml` names the same organization, the answer warns `config_drift` and `.c11r/drift` notes the write; `config plan` repeats the warning, and `config export` clears it.
 
-`c11r scaffold drop-in --out <file>` writes the drop-in.js snippet as one HTML file: the part for the page's `<head>`, then the part for its `<body>`, each under a comment saying where it goes. It never replaces a different file without `--yes`. Without `--out`, the snippet stays in the JSON answer.
+`c11r scaffold drop-in --out <file>` writes the drop-in.js snippet as one HTML file: the part for the page's `<head>`, then the part for its `<body>`, each under a comment saying where it goes. The file must be inside the project folder: a path that leads out of it, by `..`, an absolute path or a symlink, is refused with `invalid_value` on `out` before anything is sent. It never replaces a different file without `--yes`. Without `--out`, the snippet stays in the JSON answer.
 
 `c11r exports get <id> --out <file>` downloads a completed export while its link lasts (5 minutes), unzipped unless the name ends in `.gz`; `--wait` reads the job again until it completes.
 
@@ -128,6 +131,27 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 
 `rate_limited` is retried twice with a short backoff, for reads and writes: nothing was processed. `commercelayer_busy` and `commercelayer_unavailable` are retried for reads only; a write that may have reached Commerce Layer fails with its next step. The one exception is `sandbox create`: it sends a fresh `Idempotency-Key`, and after a 5xx or a lost connection it repeats the create with the same key, so the API answers the sandbox it made and its token is stored. Each retry waits as long as the API says (`retry_after` seconds in the error, or the `Retry-After` header), at most 30 seconds; without it, 1 then 3 seconds. When the API asks for longer than 30 seconds, the CLI does not wait: the error goes to the agent, with `retry_after`, to plan around. Each retry writes a line to stderr.
 
+## Shop
+
+`c11r shop` buys for the human from any store that speaks UCP. The CLI talks to the store directly, with no organization and no call to the API. `<store>` is the store's host (`shop.example.com`) or an https URL on it.
+
+- Every call carries `UCP-Agent: profile="https://commercelayer.ai/ucp/agent-cli/profile.json"`, a `Request-Id`, a `Content-Digest` with a body, and an `Idempotency-Key` on a write. The CLI holds no keys and signs no request. The store's answers are checked against the keys its `/.well-known/ucp` publishes: a digest that does not match, or a signature that does not verify, is `invalid_response` and the answer is not used. An unsigned answer warns `answer_unsigned`. A store that wants signed requests is `not_supported`.
+- `profile`, `search`, `get` and `ask` only read. `get` and `ask` take the variant or the question as the bare value after the store.
+- `checkout` opens a checkout with `--item ID=QTY` (repeated) and the buyer's `--email`, `--first-name`, `--last-name`, `--phone` and `--address.street`, `--address.line-2`, `--address.locality`, `--address.postal-code`, `--address.region`, `--address.country`, all but the line 2 and the region required. Each is the human's, never invented: a missing one is `missing_value` with a human step. Before any of them is sent, `confirmation_required` shows every value and the host (`Sharing with shop.example.com: Ada Lovelace, ada@example.com, ...`); the agent asks the human and, on their yes, runs it again with `--yes`. `checkout <store> <checkout>` changes one (items, the buyer, the address, `--shipping <option>`), or with nothing to change reads it again. The answer has the totals with shipping and, when it is ready, `next` is the order.
+- `order <store> <checkout>` shows the total and asks the same way, then pays with the sandbox test handler (`ai.commercelayer.sandbox`), where no money moves, and answers the order. On a checkout already paid it answers the order and pays nothing. A checkout that is not ready is `invalid_transition`: when the store's messages name the fields it still needs, `next_step` is the command with their flags (`--phone PHONE`), and when they do not, it is a human step at the store's checkout page; a declined payment is `store_refused` with the store's words.
+- The CLI has no flag for card data. A store without the sandbox handler is `payment_handler_unsupported` before anything of the human's is sent, with the store's URL for the human to buy there in person.
+- With `--dry-run`, checkout answers what it would send and order the total it would pay: nothing is sent.
+
+## Skills
+
+`c11r skills sync` keeps copies of the skills in the project folder, where coding agents load them: `.claude/skills/<name>/SKILL.md`, one per skill as https://commercelayer.ai serves it, and in `AGENTS.md` a block between `<!-- c11r skills: start -->` and `<!-- c11r skills: end -->` listing them, for agents that read that file. Nothing outside the markers changes; without an `AGENTS.md`, sync creates one holding only the block, and says so with `agents_md: "created"`. The project folder is the one already holding the copies, else the one with `.c11r.json`, `store.yml` or `loops.yml`, else the git repository's root, else the current folder. It needs no organization and calls only commercelayer.ai, not the API.
+
+- It reads the index (`start.md`) with the ETag of the last sync, and fetches only the skills whose version changed. A skill the index dropped is removed. `.claude/skills/.c11r-skills.json` records what sync wrote, with each file's sha256; a folder sync did not write is never touched.
+- Every copy's sha256 is checked on each run, also when nothing new is in the index. A copy that is not what sync wrote is an edit: it is kept, neither replaced nor removed, and listed in `edited` with a `skill_edited` warning. `--yes`, on the human's yes, replaces or removes it.
+- `--except <skill>` (repeated) leaves a skill out, and later syncs remember it; `--include <skill>` takes it back.
+- A file whose name or version is not what the index says is not used (`skill_invalid`); a link off `commercelayer.ai/skills/` is skipped (`skill_skipped`).
+- The answer has `added`, `updated` (from and to), `removed`, `edited` and how many are `unchanged`. With `--dry-run` it reads only the index and writes nothing. When the site cannot be reached it is `site_unavailable` (exit 7), and the copies stay as they are.
+
 ## Environment
 
 | Variable | What it does |
@@ -139,5 +163,6 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 | `C11R_AUTH_URL` | Commerce Layer's token endpoint, `https://auth.commercelayer.io/oauth/token` by default: for tests. |
 | `C11R_TEST` | `1` marks a sandbox as a test organization, like a name starting `zztest`. |
 | `C11R_SCHEMA_CACHE` | `0` turns off the 10 minute schema cache in `~/.cache/c11r`. The cache records the `C11R-Schema` hash it was read under; an answer with another hash drops it, and a command the API refused on the old schema runs once more on the fresh one (without the header, after `confirmation_required`, `unknown_field` or `unknown_verb`). The second run asks what the fresh schema asks: it never adds `confirm=true` by itself. |
+| `C11R_SKILLS_URL` | The skills index, for a test site on localhost only: `https://commercelayer.ai/start.md` otherwise. |
 | `C11R_RETRY_CAP_S` | The longest the CLI waits before one retry, 30 by default. |
 | `C11R_TIMEOUT_MS` | How long a request may take, 30000 by default (sandbox create waits longer). |

package/dist/argv.js

@@ -181,9 +181,10 @@ export function coerce(key, spec, raw) {
             // One object per flag (--items sku=A,quantity=2, repeated), or scalars separated by commas.
             if (item === 'object')
                 return [coerce(key, { type: 'object', properties: spec.properties }, raw)];
-            // An in filter on names or text takes the value whole: a name may have a comma ("UK VAT, manual").
-            // Several are the flag repeated, or a JSON array. Enums, numbers and dates still split on commas.
-            if (spec.filter?.op === 'in' && (item === 'string' || item === 'ref'))
+            // A name or text is one value per flag, in a filter or not: a name may have a comma
+            // ("Invoice, 60 days"). Several are the flag repeated, or a JSON array. Enums, numbers and
+            // dates still split on commas.
+            if (item === 'string' || item === 'ref')
                 return [raw];
             return raw
                 .split(',')

package/dist/builtins/extensions.js

@@ -11,7 +11,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import zlib from 'node:zlib';
-import { credentialsFile, hintOf, readLink, storeBooking, storedBooking, storeOrg, writeLink } from '../config.js';
+import { credentialsFile, hintOf, projectDir, readLink, storeBooking, storedBooking, storeOrg, writeLink } from '../config.js';
 import { confirm, terminal } from '../confirm.js';
 import { fail } from '../errors.js';
 import { apiUrl } from '../http.js';
@@ -272,19 +272,49 @@ export const exports = {
         return { ...r, data: { ...rest, file, bytes: bytes.length, unzipped: zipped && !file.endsWith('.gz') } };
     },
 };
+/** Where a path really lands: symlinks followed, dangling ones too, and the missing rest as written. */
+function realPath(p, hops = 0) {
+    let st = null;
+    try {
+        st = fs.lstatSync(p);
+    }
+    catch {
+        st = null;
+    }
+    if (st?.isSymbolicLink() && hops < 40)
+        return realPath(path.resolve(realPath(path.dirname(p), hops + 1), fs.readlinkSync(p)), hops + 1);
+    if (st)
+        return fs.realpathSync(p);
+    const parent = path.dirname(p);
+    return parent === p ? p : path.join(realPath(parent, hops), path.basename(p));
+}
+/**
+ * --out resolved from here, refused (invalid_value on out) when it lands outside the project folder:
+ * by .., by an absolute path, or by a symlink on the way (the file itself or a folder above it).
+ */
+function insideProject(out) {
+    const file = path.resolve(out);
+    const root = fs.realpathSync(projectDir());
+    const target = realPath(file);
+    const rel = path.relative(root, target);
+    if (rel === '' || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        fail('invalid_value', `--out ${out} is outside the project folder ${root}: c11r writes only inside it.`, { path: 'out', details: { project: root, resolved: target } });
+    }
+    return file;
+}
 // scaffold (46): drop-in --out writes the snippet as one HTML file, its head part and its body part
 // each under a comment saying where it goes. It never replaces a different file without --yes.
 export const scaffold = {
     flags: {
         'drop-in': {
-            out: { type: 'string', to: 'local', description: 'Write the snippet to this HTML file: the part for the page\'s <head>, then the part for its <body>, each under a comment saying where it goes. A different file there is replaced only with --yes.' },
+            out: { type: 'string', to: 'local', description: 'Write the snippet to this HTML file: the part for the page\'s <head>, then the part for its <body>, each under a comment saying where it goes. It must be inside the project folder. A different file there is replaced only with --yes.' },
         },
     },
     async run(run) {
         const out = run.parsed.values.out;
         if (run.verb.name !== 'drop-in' || !out)
             return undefined;
-        const file = path.resolve(out);
+        const file = insideProject(out);
         // Before anything is sent: a different file there stays without --yes.
         const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
         const r = await run.send(resourceRequest('scaffold', run.verb, undefined, run.parsed.values));

package/dist/builtins/index.js

@@ -1,8 +1,10 @@
 // The nouns with code of their own. Each brings a schema document in the API's format, so help,
 // validation and confirmation are the engine's. report is a plain noun: the API's schema drives
-// it. skills (c11r skills sync) comes with deliverable 4.
+// it.
 import { auth } from './auth.js';
 import { loops } from './loops.js';
 import { sandbox, status } from './sandbox.js';
-export const builtins = { sandbox, status, loops, auth };
+import { shop } from './shop.js';
+import { skills } from './skills.js';
+export const builtins = { sandbox, status, loops, auth, shop, skills };
 export { extensions } from './extensions.js';

package/dist/builtins/loops.js

@@ -21,7 +21,7 @@ const policyFlags = (required) => [
     { name: 'skill', type: 'string', required, description: 'The skill the loop runs, as in manage-orders or report-sales: one a noun\'s schema names in loop.skill or loop.skills.' },
     { name: 'every', type: 'string', required, description: 'How often a pass should run, as in 15m, 2h or 1d. The scheduler reads it; the CLI does not wait.' },
     { name: 'allow', type: 'array', description: 'A verb the policy allows, repeated: approve, payments.capture. Only verbs the noun\'s schema lists in loop.verbs. Without it the loop only reports what is waiting.' },
-    { name: 'max_total', type: 'array', description: 'The largest order total acted on, in major units: 500 for every currency, or EUR=500, repeated per currency. Above it, the item waits for the human.' },
+    { name: 'max_total', type: 'array', description: 'The largest order total acted on, in major units: 500 for every currency, or EUR=500 per currency, the flag repeated or separated by commas. Above it, the item waits for the human.' },
     { name: 'market', type: 'array', description: 'A market code the loop acts in, repeated. Items in other markets wait. Without it, every market.' },
 ];
 export const loops = {
@@ -147,7 +147,9 @@ async function write(run, name, file) {
     });
 }
 /** 500, or EUR=500 per currency. */
-function maxTotal(items) {
+function maxTotal(given) {
+    // Amounts and currency codes hold no comma: EUR=500,USD=550 is two, as is the flag repeated.
+    const items = given.flatMap((i) => i.split(',')).map((i) => i.trim()).filter(Boolean);
     const plain = items.filter((i) => !i.includes('='));
     if (plain.length && plain.length !== items.length)
         fail('invalid_value', '--max-total takes one amount, or one CURRENCY=amount per currency, not both.', { path: 'max_total' });