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

package/dist/builtins/skills.js

@@ -0,0 +1,349 @@
+// c11r skills sync: local copies of the skills, from the index the site publishes (start.md), so
+// any coding agent in the project finds them. State none: no token, no organization, no call to
+// the API; only commercelayer.ai.
+//
+//   <project>/.claude/skills/<name>/SKILL.md   one per skill, as the site serves it
+//   <project>/.claude/skills/.c11r-skills.json  the manifest: what sync wrote, by version and hash
+//   <project>/AGENTS.md                         a marked block listing them, for other agents
+//
+// Only what the index version changed is fetched, with the index itself a conditional GET. A copy
+// whose bytes are not what sync wrote is the person's edit: it is never replaced or deleted
+// without --yes. Folders sync did not write are never touched.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { findUp, LINK_FILE } from '../config.js';
+import { CliError, fail } from '../errors.js';
+import { envelope } from '../http.js';
+import { parseSchema } from '../schema.js';
+import { USER_AGENT } from '../version.js';
+const INDEX_URL = 'https://commercelayer.ai/start.md';
+const SKILLS_DIR = path.join('.claude', 'skills');
+const MANIFEST = '.c11r-skills.json';
+const AGENTS_FILE = 'AGENTS.md';
+const START = '<!-- c11r skills: start -->';
+const END = '<!-- c11r skills: end -->';
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+const TIMEOUT_MS = 30_000;
+export const skills = {
+    schema: parseSchema({
+        noun: 'skills',
+        group: 'setup',
+        skill: 'start',
+        kind: 'task',
+        description: 'The local copies of the Commerce Layer skills, in the project folder, where coding agents load them: .claude/skills/<name>/SKILL.md, and a list of them in AGENTS.md.',
+        verbs: [
+            {
+                verb: 'sync',
+                method: 'POST',
+                path: '/skills/sync',
+                state: 'none',
+                live: false,
+                body: [
+                    { name: 'except', type: 'array', items: 'string', description: 'A skill not to keep a copy of, repeated. Remembered: later syncs leave it out too.' },
+                    { name: 'include', type: 'array', items: 'string', description: 'A skill left out with --except to keep a copy of again, repeated.' },
+                ],
+                effect: 'Brings the copies up to date with the index at commercelayer.ai: fetches only the skills whose version changed, adds new ones, removes the ones the index dropped, and keeps the list in AGENTS.md (creating the file when there is none). A copy edited on this machine is kept as it is; replacing or removing it needs the human\'s yes. Answers added, updated, removed, edited and how many are unchanged. With --dry-run it reads only the index and writes nothing.',
+            },
+        ],
+    }),
+    defaultVerb: 'sync',
+    async run(run) {
+        return sync(run);
+    },
+};
+// ---------- the site
+function indexUrl() {
+    const given = process.env.C11R_SKILLS_URL;
+    if (!given)
+        return INDEX_URL;
+    let u;
+    try {
+        u = new URL(given);
+    }
+    catch {
+        fail('invalid_config', `C11R_SKILLS_URL ${given} is not a URL.`);
+    }
+    if (!['localhost', '127.0.0.1'].includes(u.hostname))
+        fail('invalid_config', `C11R_SKILLS_URL is for a test site on localhost only, not ${u.host}.`);
+    return u.toString();
+}
+const unavailable = (message) => new CliError({ code: 'site_unavailable', message, required_state: null, required_plan: null, missing: null, path: null, next_step: { action: 'retry_later', command: null, url: null } }, 'unavailable');
+async function get(url, etag) {
+    let res;
+    try {
+        res = await fetch(url, { headers: { 'user-agent': USER_AGENT, accept: 'text/markdown', ...(etag ? { 'if-none-match': etag } : {}) }, signal: AbortSignal.timeout(TIMEOUT_MS) });
+    }
+    catch (e) {
+        throw unavailable(`${new URL(url).host} could not be reached: ${e.message}. The local copies are unchanged and still usable.`);
+    }
+    if (res.status !== 200 && res.status !== 304)
+        throw unavailable(`${url} answered ${res.status}. The local copies are unchanged and still usable.`);
+    return { status: res.status, etag: res.headers.get('etag'), text: res.status === 200 ? await res.text() : '' };
+}
+/** The index lines: - [name](url) VERSION, state ..., plan ...[, requires ...]: description. */
+function parseIndex(text, from) {
+    const origin = new URL(from).origin;
+    const entries = [];
+    const skipped = [];
+    for (const line of text.split('\n')) {
+        const m = line.match(/^- \[([^\]]+)\]\((\S+)\) (\d+\.\d+\.\d+\S*?),[^:]*: (.*)$/);
+        if (!m)
+            continue;
+        const [, name, link, version, description] = m;
+        let u = null;
+        try {
+            u = new URL(link, from);
+        }
+        catch {
+            u = null;
+        }
+        if (!NAME.test(name) || !u || u.origin !== origin || !u.pathname.startsWith('/skills/')) {
+            skipped.push(name);
+            continue;
+        }
+        if (!entries.some((e) => e.name === name))
+            entries.push({ name, version, url: u.toString(), description: description.trim() });
+    }
+    return { entries, version: frontmatter(text).version ?? null, skipped };
+}
+function frontmatter(text) {
+    const m = text.match(/^---\n([\s\S]*?)\n---/);
+    const out = {};
+    for (const line of m?.[1].split('\n') ?? []) {
+        const kv = line.match(/^([a-z_]+):\s*(.*)$/);
+        if (kv)
+            out[kv[1]] = kv[2].replace(/^"(.*)"$/, '$1').trim();
+    }
+    return out;
+}
+// ---------- this machine
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+const readOr = (file) => {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+function readManifest(file) {
+    const raw = readOr(file);
+    if (raw === null)
+        return null;
+    try {
+        const m = JSON.parse(raw);
+        return { index: { url: m.index?.url ?? INDEX_URL, version: m.index?.version ?? null, etag: m.index?.etag ?? null, entries: m.index?.entries ?? [] }, skills: m.skills ?? {}, except: m.except ?? [] };
+    }
+    catch {
+        fail('invalid_config', `${file} is not JSON: c11r skills sync writes it, and it was changed by hand.`);
+    }
+}
+function writeAtomic(file, text) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, text);
+    fs.renameSync(tmp, file);
+}
+const firstSentence = (d) => {
+    const i = d.indexOf('. ');
+    return i === -1 ? d : d.slice(0, i + 1);
+};
+function agentsBlock(entries, rel) {
+    const link = (n) => `${rel}/${n}/SKILL.md`;
+    const start = entries.find((e) => e.name === 'start');
+    const lines = [
+        START,
+        '## Commerce Layer skills',
+        '',
+        `Local copies of the Commerce Layer skills, kept up to date by \`c11r skills sync\`.${start ? ` Load [start](${link('start')}) first: it routes to the others.` : ''}`,
+        '',
+        ...entries.map((e) => `- [${e.name}](${link(e.name)}): ${firstSentence(e.description)}`),
+        END,
+    ];
+    return lines.join('\n');
+}
+/** AGENTS.md with the block put in or replaced; nothing outside the markers changes. */
+function withBlock(current, block) {
+    if (current === null)
+        return `${block}\n`;
+    const a = current.indexOf(START);
+    const b = current.indexOf(END);
+    if (a !== -1 && b > a)
+        return current.slice(0, a) + block + current.slice(b + END.length);
+    return `${current.replace(/\n*$/, '')}\n\n${block}\n`;
+}
+// ---------- sync
+async function sync(run) {
+    const v = run.parsed.values;
+    const dryRun = run.globals.dryRun;
+    // The project root: where the copies already are, the folder's link or store files, a git
+    // repository's root, else here.
+    const root = findUp([path.join(SKILLS_DIR, MANIFEST)]) ?? findUp([LINK_FILE]) ?? findUp(['store.yml', 'loops.yml']) ?? findUp(['.git']) ?? process.cwd();
+    const dir = path.join(root, SKILLS_DIR);
+    const manifestFile = path.join(dir, MANIFEST);
+    const from = indexUrl();
+    const before = readManifest(manifestFile);
+    const manifest = before ?? { index: { url: from, version: null, etag: null, entries: [] }, skills: {}, except: [] };
+    const warnings = [];
+    const except = v.except ?? [];
+    const include = v.include ?? [];
+    for (const n of [...except, ...include])
+        if (!NAME.test(n))
+            fail('invalid_value', `${n} is not a skill name: lowercase letters, digits and dashes, as in manage-orders.`, { path: except.includes(n) ? 'except' : 'include' });
+    const excluded = new Set([...manifest.except.filter((n) => !include.includes(n)), ...except]);
+    // The index: a 304 means the one sync last read, whose entries the manifest keeps.
+    const sameUrl = manifest.index.url === from;
+    const idx = await get(from, sameUrl && manifest.index.entries.length ? manifest.index.etag : null);
+    let entries;
+    let indexVersion;
+    if (idx.status === 304) {
+        entries = manifest.index.entries;
+        indexVersion = manifest.index.version;
+    }
+    else {
+        const parsed = parseIndex(idx.text, from);
+        if (!parsed.entries.length)
+            throw unavailable(`${from} lists no skills: it may be mid-deploy. The local copies are unchanged.`);
+        entries = parsed.entries;
+        indexVersion = parsed.version;
+        for (const n of parsed.skipped)
+            warnings.push({ code: 'skill_skipped', message: `${n} links outside ${new URL(from).origin}/skills/ in the index: not copied.` });
+    }
+    for (const n of include)
+        if (!entries.some((e) => e.name === n))
+            warnings.push({ code: 'unknown_skill', message: `${n} is not in the index.` });
+    for (const n of except)
+        if (!entries.some((e) => e.name === n) && !manifest.skills[n])
+            warnings.push({ code: 'unknown_skill', message: `${n} is not in the index.` });
+    const wanted = entries.filter((e) => !excluded.has(e.name));
+    const fileOf = (n) => path.join(dir, n, 'SKILL.md');
+    const editedNow = (n) => {
+        const kept = manifest.skills[n];
+        const text = readOr(fileOf(n));
+        return Boolean(kept && text !== null && sha(text) !== kept.sha256);
+    };
+    const added = [];
+    const updated = [];
+    const removed = [];
+    const edited = [];
+    let unchanged = 0;
+    const toFetch = [];
+    for (const e of wanted) {
+        const kept = manifest.skills[e.name];
+        const present = readOr(fileOf(e.name)) !== null;
+        if (kept && present && kept.version === e.version) {
+            // Same version: still checked, since an edit there is not what the index says either.
+            if (editedNow(e.name))
+                edited.push({ name: e.name, local: kept.version, latest: e.version });
+            else
+                unchanged++;
+            continue;
+        }
+        if (kept && present && editedNow(e.name)) {
+            edited.push({ name: e.name, local: kept.version, latest: e.version });
+            continue;
+        }
+        // A file there that sync never wrote is the person's: kept, as an edit.
+        if (!kept && present) {
+            edited.push({ name: e.name, local: frontmatter(readOr(fileOf(e.name))).version ?? 'unknown', latest: e.version });
+            continue;
+        }
+        toFetch.push(e);
+    }
+    const gone = Object.values(manifest.skills).filter((k) => !wanted.some((e) => e.name === k.name));
+    const toRemove = [];
+    for (const k of gone) {
+        if (readOr(fileOf(k.name)) === null)
+            continue;
+        if (editedNow(k.name))
+            edited.push({ name: k.name, local: k.version, latest: null });
+        else
+            toRemove.push(k);
+    }
+    // Edits are replaced or removed only on the human's yes.
+    const replaceEdits = edited.length > 0 && !dryRun && run.globals.yes;
+    if (dryRun) {
+        for (const e of toFetch)
+            (manifest.skills[e.name] && readOr(fileOf(e.name)) !== null ? updated.push({ name: e.name, from: manifest.skills[e.name].version, to: e.version }) : added.push({ name: e.name, version: e.version }));
+        for (const k of toRemove)
+            removed.push({ name: k.name, version: k.version });
+        const agentsNow = readOr(path.join(root, AGENTS_FILE));
+        const agentsNext = withBlock(agentsNow, agentsBlock(wanted, SKILLS_DIR.split(path.sep).join('/')));
+        return answer({ dry_run: true, dir, index: { url: from, version: indexVersion }, added, updated, removed, edited, unchanged, agents_md: agentsNow === null ? 'created' : agentsNow === agentsNext ? 'unchanged' : 'updated' }, warnings, edited, replaceEdits);
+    }
+    // Fetch first, write after: a cut-off sync writes nothing.
+    if (replaceEdits)
+        for (const e of edited)
+            if (e.latest)
+                toFetch.push(wanted.find((w) => w.name === e.name));
+    const bodies = new Map();
+    for (const e of toFetch) {
+        const r = await get(e.url);
+        const fm = frontmatter(r.text);
+        if (fm.name !== e.name || fm.version !== e.version) {
+            warnings.push({ code: 'skill_invalid', message: `${e.url} is ${fm.name ?? 'no skill'} ${fm.version ?? ''}, not ${e.name} ${e.version} as the index says: the local copy is unchanged.`.replace('  ', ' ') });
+            continue;
+        }
+        bodies.set(e.name, r.text);
+    }
+    for (const e of toFetch) {
+        const text = bodies.get(e.name);
+        if (text === undefined)
+            continue;
+        const kept = manifest.skills[e.name];
+        const had = readOr(fileOf(e.name)) !== null;
+        writeAtomic(fileOf(e.name), text);
+        if (kept && had)
+            updated.push({ name: e.name, from: kept.version, to: e.version });
+        else
+            added.push({ name: e.name, version: e.version });
+        manifest.skills[e.name] = { ...e, sha256: sha(text) };
+    }
+    const removeOne = (name, version) => {
+        fs.rmSync(fileOf(name), { force: true });
+        try {
+            fs.rmdirSync(path.join(dir, name));
+        }
+        catch {
+            // The folder holds something of the person's: it stays.
+        }
+        removed.push({ name, version });
+        delete manifest.skills[name];
+    };
+    for (const k of toRemove)
+        removeOne(k.name, k.version);
+    for (const k of gone)
+        if (readOr(fileOf(k.name)) === null && manifest.skills[k.name])
+            delete manifest.skills[k.name];
+    if (replaceEdits)
+        for (const e of edited)
+            if (!e.latest)
+                removeOne(e.name, e.local);
+    // Unchanged entries take the index's description, which AGENTS.md lists.
+    for (const e of wanted)
+        if (manifest.skills[e.name] && manifest.skills[e.name].version === e.version)
+            manifest.skills[e.name] = { ...manifest.skills[e.name], url: e.url, description: e.description };
+    manifest.index = { url: from, version: indexVersion, etag: idx.status === 304 ? manifest.index.etag : idx.etag, entries };
+    manifest.except = [...excluded].sort();
+    writeAtomic(manifestFile, JSON.stringify(manifest, null, 2) + '\n');
+    const listed = wanted.filter((e) => manifest.skills[e.name] || readOr(fileOf(e.name)) !== null);
+    const agentsFile = path.join(root, AGENTS_FILE);
+    const agentsNow = readOr(agentsFile);
+    const agentsNext = withBlock(agentsNow, agentsBlock(listed, SKILLS_DIR.split(path.sep).join('/')));
+    const agents_md = agentsNow === null ? 'created' : agentsNow === agentsNext ? 'unchanged' : 'updated';
+    if (agents_md !== 'unchanged')
+        writeAtomic(agentsFile, agentsNext);
+    const stillEdited = replaceEdits ? [] : edited;
+    return answer({ dir, index: { url: from, version: indexVersion }, added, updated, removed, edited: stillEdited, unchanged, agents_md }, warnings, stillEdited, replaceEdits);
+}
+function answer(data, warnings, edited, replaced) {
+    if (!replaced) {
+        for (const e of edited) {
+            warnings.push({ code: 'skill_edited', message: `${e.name} was edited on this machine: kept as it is${e.latest ? `, while the index has ${e.latest}` : ', though the index dropped it'}. Replacing it loses those edits: ask the human first, and on their yes run the sync again with --yes.` });
+        }
+    }
+    if (data.agents_md === 'created')
+        warnings.push({ code: 'agents_md_created', message: 'AGENTS.md was created, holding only the list of skills: tell the human in one line.' });
+    return envelope(data, { warnings, next: [] });
+}

package/dist/config.js

@@ -161,7 +161,7 @@ export function storeBooking(id, booking) {
 /** The last four characters, as the API shows them. */
 export const hintOf = (token) => `${token.slice(0, 4)}...${token.slice(-4)}`;
 /** The nearest folder, from the current one up, that holds one of the files. */
-function findUp(names, from = process.cwd()) {
+export function findUp(names, from = process.cwd()) {
     let dir = path.resolve(from);
     for (;;) {
         if (names.some((n) => fs.existsSync(path.join(dir, n))))

package/dist/confirm.js

@@ -40,18 +40,25 @@ export const terminal = {
         });
     },
 };
+/**
+ * action names what needs a yes ("Destroy sandbox"). sentence, when given, is what the human is
+ * shown instead, whole ("Sharing with shop.example.com: Ada Lovelace, ..."), and details go with
+ * the error, so the agent can show the human the same.
+ */
 export async function confirm(action, command, opts) {
     if (opts.yes)
         return;
     const p = opts.prompter ?? terminal;
+    const said = opts.sentence ? `${opts.sentence.replace(/\.?$/, '.')} This` : action;
     if (!p.interactive) {
         // The agent asks the human; on a yes it repeats the command with --yes. next never carries the
         // --yes itself: only the human's answer adds it.
-        fail('confirmation_required', `${action} needs confirmation, and there is no terminal to ask in. Ask the human first; on their yes, run it again with --yes.`, {
+        fail('confirmation_required', `${said} needs confirmation, and there is no terminal to ask in. Ask the human first; on their yes, run it again with --yes.`, {
             next_step: { action: 'fix_request', command },
+            ...(opts.details ? { details: opts.details } : {}),
         });
     }
-    const answer = (await p.ask(`${action}. Go ahead? [y/N] `)).trim().toLowerCase();
+    const answer = (await p.ask(opts.sentence ? `${opts.sentence.replace(/\.?$/, '.')} Go ahead? [y/N] ` : `${action}. Go ahead? [y/N] `)).trim().toLowerCase();
     if (answer !== 'y' && answer !== 'yes')
-        fail('confirmation_declined', `${action}: not confirmed, nothing was changed.`);
+        fail('confirmation_declined', opts.sentence ? `${opts.sentence.replace(/\.?$/, '')}: not confirmed, nothing was sent.` : `${action}: not confirmed, nothing was changed.`);
 }

package/dist/engine.js

@@ -65,8 +65,11 @@ async function executeOnce(argv, opts) {
         const by = verb.refused.by === 'commercelayer' ? 'Commerce Layer' : verb.refused.by;
         fail('not_supported', `c11r ${schema.noun} ${verb.name} is refused by ${by}: ${verb.description || 'it cannot be done through the API.'}`, { details: { refused_by: verb.refused.by }, next_step: { action: 'none' } });
     }
-    const positional = ext?.positional?.[verb.name];
-    const rest = positional && !verb.id && cmd.rest[0] !== undefined && !cmd.rest[0].startsWith('-') ? [`--${positional}`, ...cmd.rest] : cmd.rest;
+    // A bare value that is a flag's: the first for a verb with no id (sales-calls book <slot>), the
+    // second, after the id, for one with (shop order <store> <checkout>).
+    const positional = (builtins[schema.noun]?.positional ?? ext?.positional)?.[verb.name];
+    const bare = (i) => cmd.rest[i] !== undefined && !cmd.rest[i].startsWith('-');
+    const rest = !positional ? cmd.rest : !verb.id && bare(0) ? [`--${positional}`, ...cmd.rest] : verb.id && bare(0) && bare(1) ? [cmd.rest[0], `--${positional}`, ...cmd.rest.slice(1)] : cmd.rest;
     const parsed = parseFields(schema.noun, verb, rest);
     ext?.prepare?.(verb, parsed);
     // Files first, so a required document given with --file counts; a secret is typed only once

package/dist/errors.js

@@ -62,6 +62,12 @@ const KIND = {
     no_credentials: 'auth',
     forbidden: 'rejected',
     claim_not_found: 'not_found',
+    // A store spoken to over UCP (c11r shop).
+    store_unavailable: 'unavailable',
+    store_refused: 'rejected',
+    payment_handler_unsupported: 'rejected',
+    // The site that publishes the skills (c11r skills sync).
+    site_unavailable: 'unavailable',
 };
 /** For an API error whose code the CLI does not know: from the HTTP status. */
 export function kindOfStatus(status) {

package/dist/help.js

@@ -30,7 +30,7 @@ export function indexHelp(builtins, api) {
         description: 'c11r is the Commerce Layer CLI for coding agents. Every answer, errors included, is one JSON object on stdout.',
         nouns: [...builtins, ...(api ?? [])].sort((a, b) => (a.noun < b.noun ? -1 : 1)),
         standard_verbs: 'list, get, create, update, delete. Nouns with a state machine add their own verbs.',
-        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01). in 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, and a list that has one is sent as a JSON array. A ref flag, or a flag the schema marks nullable, given null or an empty value sends null and takes it off (--customer-group null, --coupon-code null). A dotted flag sets part of an object (--customer.email). Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
+        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01). in 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, and a list that has one is sent as a JSON array. A ref flag, or a flag the schema marks nullable, given null or an empty value sends null and takes it off (--customer-group null, --coupon-code null). A dotted flag sets part of an object (--customer.email). 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 (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
         global_flags: GLOBAL_FLAG_HELP,
         exit_codes: EXIT_CODE_HELP,
         more: 'c11r <noun> --help describes a noun and its verbs; c11r <noun> <verb> --help a verb and its flags; c11r schema <noun> returns the full schema.',

package/dist/ucp.js

@@ -0,0 +1,207 @@
+// A UCP platform client: what any shopping agent does to buy from a store that speaks UCP.
+// The CLI talks to the store directly, as the agent CLI platform: its profile is the static
+// https://commercelayer.ai/ucp/agent-cli/profile.json, it holds no keys, and stores verify no
+// request signature. Every call carries UCP-Agent and Request-Id, a Content-Digest with a body,
+// and an Idempotency-Key on writes. The store signs its answers (RFC 9421, ES256 over @status,
+// content-digest and content-type): the CLI checks them against keys[] of its /.well-known/ucp.
+import crypto from 'node:crypto';
+import { CliError, fail } from './errors.js';
+import { USER_AGENT } from './version.js';
+export const UCP_VERSION = '2026-08-25';
+export const AGENT_PROFILE_URL = 'https://commercelayer.ai/ucp/agent-cli/profile.json';
+/** The sandbox payment handler: no money moves. The only one this CLI pays with. */
+export const SANDBOX_HANDLER = 'ai.commercelayer.sandbox';
+const SANDBOX_HANDLER_ID = 'cl_sandbox';
+const SANDBOX_CREDENTIAL_TYPE = 'sandbox_token';
+const SANDBOX_TOKEN_SUCCESS = 'sbx_tok_success';
+const TIMEOUT_MS = 30_000;
+/** A store from a host or a URL on it: https only (http for localhost, in tests). */
+export function originOf(given) {
+    let url = null;
+    try {
+        url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(given) ? given : `https://${given}`);
+    }
+    catch {
+        url = null;
+    }
+    if (!url || !url.hostname)
+        fail('invalid_value', `${given} is not a store: give its host, as in shop.example.com, or an https URL on it.`, { path: 'id' });
+    const local = ['localhost', '127.0.0.1'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local))
+        fail('invalid_value', `${given} is not https: UCP stores are served over https.`, { path: 'id' });
+    return url.origin;
+}
+/** GET /.well-known/ucp: what the store offers this CLI. */
+export async function discover(origin) {
+    const res = await http('GET', `${origin}/.well-known/ucp`, { accept: 'application/json' });
+    const host = new URL(origin).host;
+    if (res.status === 404)
+        fail('not_found', `${host} serves no UCP profile (/.well-known/ucp answered 404): it does not sell to agents.`, { path: 'id', next_step: { action: 'human_step', url: origin } });
+    if (res.status !== 200)
+        fail('store_unavailable', `${host}/.well-known/ucp answered ${res.status}.`, { details: { status: res.status }, next_step: { action: 'retry_later' } });
+    const profile = parse(res.body);
+    if (!profile || typeof profile.ucp !== 'object')
+        fail('invalid_response', `${host}/.well-known/ucp is not a UCP profile.`, { next_step: { action: 'none' } });
+    const ucp = profile.ucp;
+    if (ucp.version !== UCP_VERSION)
+        fail('not_supported', `${host} speaks UCP ${ucp.version ?? '(no version)'}; this CLI speaks ${UCP_VERSION}.`, { details: { store_version: ucp.version ?? null, cli_version: UCP_VERSION }, next_step: { action: 'none' } });
+    const rest = (name) => (ucp.services?.[name] ?? []).find((s) => s.transport === 'rest')?.endpoint ?? null;
+    const endpoint = rest('dev.ucp.shopping');
+    if (!endpoint)
+        fail('not_supported', `${host}'s profile has no REST dev.ucp.shopping service.`, { next_step: { action: 'none' } });
+    const capabilities = new Set();
+    for (const [name, entries] of Object.entries((ucp.capabilities ?? {})))
+        if (Array.isArray(entries) && entries.some((e) => e.version === UCP_VERSION))
+            capabilities.add(name);
+    return { origin, host, profile, endpoint, commonEndpoint: rest('dev.ucp.common'), capabilities, keys: Array.isArray(profile.keys) ? profile.keys : [] };
+}
+/** The payment handlers the store offers, by name, and whether this CLI can pay there. */
+export function handlersOf(store) {
+    const handlers = Object.keys(store.profile.ucp?.payment_handlers ?? {});
+    return { handlers, can_pay: handlers.includes(SANDBOX_HANDLER) && store.capabilities.has('dev.ucp.shopping.checkout') };
+}
+/** Before anything of the human's is sent: a store this CLI cannot pay at is refused. */
+export function mustPay(store, extra = {}) {
+    if (!store.capabilities.has('dev.ucp.shopping.checkout')) {
+        fail('not_supported', `${store.host} offers no UCP checkout: an agent can browse it, not buy there.`, { next_step: { action: 'human_step', url: store.origin } });
+    }
+    const { handlers } = handlersOf(store);
+    if (!handlers.includes(SANDBOX_HANDLER)) {
+        fail('payment_handler_unsupported', `${store.host} takes ${handlers.length ? handlers.join(', ') : 'no payment handler'}; this CLI pays only with the ${SANDBOX_HANDLER} test handler, where no money moves. The human buys there in person.`, { details: { handlers }, next_step: { action: 'human_step', url: extra.continue_url ?? store.origin } }, 'rejected');
+    }
+}
+export const sandboxPayment = () => ({ payment: { instruments: [{ id: 'pi_1', handler_id: SANDBOX_HANDLER_ID, type: 'card', selected: true, credential: { type: SANDBOX_CREDENTIAL_TYPE, token: SANDBOX_TOKEN_SUCCESS } }] } });
+/** A UCP call. The answer's digest and signature are checked; an error is a CliError. */
+export async function call(store, method, url, body, what = 'the store') {
+    const raw = body === undefined ? undefined : JSON.stringify(body);
+    const headers = { accept: 'application/json', 'ucp-agent': `profile="${AGENT_PROFILE_URL}"`, 'request-id': crypto.randomUUID() };
+    if (raw !== undefined) {
+        headers['content-type'] = 'application/json';
+        headers['content-digest'] = contentDigest(raw);
+    }
+    if (method !== 'GET' && !/\/catalog\/|\/ask$/.test(url))
+        headers['idempotency-key'] = crypto.randomUUID();
+    const res = await http(method, url, headers, raw);
+    const signature = checkAnswer(store, res);
+    const parsed = parse(res.body);
+    if (res.status >= 400 || parsed?.ucp?.status === 'error')
+        refused(store, res.status, parsed, what);
+    if (!parsed || typeof parsed !== 'object')
+        fail('invalid_response', `${store.host} answered ${what} with no JSON.`, { details: { status: res.status }, next_step: { action: 'retry_later' } });
+    return { status: res.status, body: parsed, signature };
+}
+/** The store's own words, as an error the agent can show the human. */
+function refused(store, status, body, what) {
+    const messages = Array.isArray(body?.messages) ? body.messages : [];
+    const first = messages.find((m) => m.type === 'error') ?? messages[0];
+    const code = body?.code ?? first?.code;
+    const said = body?.content ?? first?.content ?? `it answered ${status}`;
+    const details = { status, store_code: code ?? null, messages: messages.length ? messages : undefined };
+    if (status === 404 || code === 'not_found')
+        fail('not_found', `${store.host} does not know ${what}: ${said}`, { details, next_step: { action: 'none' } });
+    if (status === 401 && /signature/i.test(`${code} ${said}`)) {
+        fail('not_supported', `${store.host} wants a signed request, and this CLI signs none: ${said}`, { details, next_step: { action: 'human_step', url: store.origin } });
+    }
+    if (status === 401 || code === 'identity_required')
+        fail('forbidden', `${store.host} refused ${what}: ${said} This CLI reads only orders it placed.`, { details, next_step: { action: 'none' } });
+    if (status === 429 || status >= 500)
+        fail('store_unavailable', `${store.host} could not answer ${what}: ${said}`, { details, next_step: { action: 'retry_later' } });
+    fail('store_refused', `${store.host} refused ${what}: ${said}`, { details, next_step: { action: 'human_step' } }, 'rejected');
+}
+async function http(method, url, headers, body) {
+    let res;
+    try {
+        res = await fetch(url, { method, headers: { 'user-agent': USER_AGENT, ...headers }, body, redirect: 'follow', signal: AbortSignal.timeout(TIMEOUT_MS) });
+    }
+    catch (e) {
+        const host = (() => {
+            try {
+                return new URL(url).host;
+            }
+            catch {
+                return url;
+            }
+        })();
+        throw new CliError({ code: 'store_unavailable', message: `${host} could not be reached: ${e.message}.`, required_state: null, required_plan: null, missing: null, path: null, next_step: { action: 'retry_later', command: null, url: null } }, 'unavailable');
+    }
+    const out = {};
+    res.headers.forEach((v, k) => (out[k.toLowerCase()] = v));
+    return { status: res.status, headers: out, body: await res.text() };
+}
+function parse(text) {
+    if (!text)
+        return null;
+    try {
+        const v = JSON.parse(text);
+        return v && typeof v === 'object' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------- digests and signatures (RFC 9530, RFC 9421)
+export function contentDigest(body) {
+    return `sha-256=:${crypto.createHash('sha256').update(body).digest('base64')}:`;
+}
+function serializeParams(p) {
+    let s = `(${p.components.map((c) => `"${c}"`).join(' ')})`;
+    if (p.created !== undefined)
+        s += `;created=${p.created}`;
+    return `${s};keyid="${p.keyid}"`;
+}
+export function signatureBase(values, p) {
+    return [...p.components.map((c) => `"${c}": ${values[c] ?? ''}`), `"@signature-params": ${serializeParams(p)}`].join('\n');
+}
+function parseSignature(input, signature) {
+    if (!input || !signature)
+        return null;
+    const m = input.match(/^\s*([a-z0-9_-]+)=\(([^)]*)\)((?:;[a-z]+=[^;]*)*)\s*$/i);
+    if (!m)
+        return null;
+    const [, label, list, rest] = m;
+    const params = { components: [...list.matchAll(/"([^"]+)"/g)].map((x) => x[1]), keyid: '' };
+    for (const [, k, v] of rest.matchAll(/;([a-z]+)=("[^"]*"|[^;]*)/g)) {
+        if (k === 'keyid')
+            params.keyid = v.replace(/^"|"$/g, '');
+        if (k === 'created')
+            params.created = Number(v);
+    }
+    const sig = signature.match(new RegExp(`${label}=:([A-Za-z0-9+/=]+):`));
+    return sig ? { params, signature: sig[1] } : null;
+}
+function verify(base, signature, jwk) {
+    try {
+        const { kid: _k, use: _u, alg: _a, key_ops: _o, ...key } = jwk;
+        return crypto.verify('sha256', Buffer.from(base), { key: crypto.createPublicKey({ key: key, format: 'jwk' }), dsaEncoding: 'ieee-p1363' }, Buffer.from(signature, 'base64'));
+    }
+    catch {
+        return false;
+    }
+}
+/** A digest that does not match, or a signature that does not verify: the answer is not trusted. */
+function checkAnswer(store, res) {
+    const digest = res.headers['content-digest'];
+    if (digest && digest !== contentDigest(res.body))
+        fail('invalid_response', `${store.host}'s answer does not match its Content-Digest: it was changed on the way, and is not used.`, { next_step: { action: 'retry_later' } });
+    const sig = parseSignature(res.headers['signature-input'], res.headers.signature);
+    if (!sig)
+        return 'unsigned';
+    const key = store.keys.find((k) => k.kid === sig.params.keyid);
+    const values = { '@status': String(res.status), 'content-digest': digest ?? '', 'content-type': res.headers['content-type'] ?? '' };
+    if (!key || !verify(signatureBase(values, sig.params), sig.signature, key)) {
+        fail('invalid_response', `${store.host}'s answer is signed with ${key ? 'a signature that does not verify' : `a key its profile does not publish (${sig.params.keyid})`}: it is not used.`, { next_step: { action: 'none' } });
+    }
+    return 'verified';
+}
+export function money(amount, currency) {
+    let digits = 2;
+    try {
+        digits = new Intl.NumberFormat('en', { style: 'currency', currency }).resolvedOptions().maximumFractionDigits ?? 2;
+    }
+    catch {
+        digits = 2;
+    }
+    const major = amount / 10 ** digits;
+    return { amount, currency, display: `${amount < 0 ? '-' : ''}${currency} ${Math.abs(major).toFixed(digits)}` };
+}
+export const minorOf = (major, currency) => Math.round(major * 10 ** (money(0, currency).display.split('.')[1]?.length ?? 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "1.0.0-dev.12",
+  "version": "1.0.0-dev.14",
   "description": "c11r: the Commerce Layer CLI for coding agents. One grammar, c11r <noun> <verb>, from a sandbox to a running organization.",
   "homepage": "https://commercelayer.ai",
   "keywords": [