@commercelayer/agent-cli 0.0.0-stage → 0.1.0

package/dist/api/stub/ucp.js

@@ -0,0 +1,350 @@
+// Everything a store host serves: the UCP profile and REST service, the OAuth
+// surface for identity linking, the permalink, the policy and continue pages,
+// and the published storefront. This is the spec of the Worker behind
+// *.sandbox.commercelayer.store.
+import crypto from 'node:crypto';
+import { agentProfile, AGENT_PROFILE_URL, capabilityEntry, EXTENSIONS, SANDBOX_HANDLER, SANDBOX_HANDLER_ID, SANDBOX_HANDLER_SCHEMA, SANDBOX_HANDLER_SPEC, SHOPPING_CAPABILITIES, UCP, UCP_VERSION } from '../../ucp/platform.js';
+import { contentDigest, signHeaders } from '../../ucp/signing.js';
+import { strip } from './db.js';
+import { json } from './http.js';
+import * as shop from './shopping.js';
+const SCOPES = ['dev.ucp.shopping.order:read', 'dev.ucp.shopping.order:manage'];
+const OUR_CAPABILITIES = [...SHOPPING_CAPABILITIES, 'dev.ucp.common.ask', ...Object.keys(EXTENSIONS), 'dev.ucp.common.identity_linking', 'dev.ucp.shopping.permalink'];
+// ---------- profile
+export function profile(r, origin) {
+    const service = (schema) => [{ version: UCP_VERSION, spec: `${UCP}/specification/overview`, transport: 'rest', schema: `${UCP}/services/${schema}/rest.openapi.json`, endpoint: `${origin}/ucp/v1` }];
+    const capabilities = {};
+    for (const name of OUR_CAPABILITIES) {
+        const extra = {};
+        if (name === 'dev.ucp.common.identity_linking')
+            extra.config = { scopes: Object.fromEntries(SCOPES.map((s) => [s, { description: { plain: s.endsWith(':read') ? 'View your orders and their status.' : 'Cancel or return your orders.' } }])) };
+        if (name === 'dev.ucp.shopping.permalink')
+            extra.config = { endpoint: `${origin}/buy` };
+        if (name === 'dev.ucp.shopping.fulfillment')
+            extra.config = { method_combinations: [['shipping']] };
+        capabilities[name] = [capabilityEntry(name, extra)];
+    }
+    return {
+        ucp: {
+            version: UCP_VERSION,
+            services: { 'dev.ucp.shopping': service('shopping'), 'dev.ucp.common': service('common') },
+            capabilities,
+            payment_handlers: {
+                [SANDBOX_HANDLER]: [{ id: SANDBOX_HANDLER_ID, version: UCP_VERSION, spec: SANDBOX_HANDLER_SPEC, schema: SANDBOX_HANDLER_SCHEMA, available_instruments: [{ type: 'card' }], config: { environment: 'sandbox' } }],
+            },
+        },
+        keys: [r.ucp.public_jwk],
+    };
+}
+// ---------- negotiation
+/** What the platform behind a UCP-Agent URL supports. The stub knows this CLI's profile; any other HTTPS platform is taken at face value. */
+function negotiate(platformUrl) {
+    let theirs = null;
+    if (platformUrl === AGENT_PROFILE_URL)
+        theirs = agentProfile();
+    const ours = new Set(OUR_CAPABILITIES);
+    if (!theirs)
+        return { shared: ours, webhookUrl: null };
+    const shared = new Set();
+    const caps = theirs.ucp.capabilities ?? {};
+    for (const name of ours)
+        if ((caps[name] ?? []).some((e) => e.version === UCP_VERSION))
+            shared.add(name);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [ext, parents] of Object.entries(EXTENSIONS)) {
+            if (shared.has(ext) && !parents.some((p) => shared.has(p))) {
+                shared.delete(ext);
+                changed = true;
+            }
+        }
+    }
+    const webhookUrl = caps['dev.ucp.shopping.order']?.[0]?.config?.webhook_url ?? null;
+    return { shared, webhookUrl };
+}
+// ---------- the REST service
+const protocolError = (status, code, content, headers = {}) => json(status, { code, content }, headers);
+function withUcpHeaders(r, res) {
+    const digest = contentDigest(res.body);
+    const values = { '@status': String(res.status), 'content-digest': digest, 'content-type': res.headers['content-type'] ?? 'application/json' };
+    const sig = signHeaders('sig1', values, { components: ['@status', 'content-digest', 'content-type'], keyid: r.ucp.kid, created: Math.floor(Date.now() / 1000) }, r.ucp.private_jwk);
+    return { ...res, headers: { ...res.headers, 'content-digest': digest, ...sig } };
+}
+function handleService(req, r, origin, path) {
+    // 1. Who is calling: UCP-Agent names the platform profile; Request-Id is required.
+    const agent = req.headers['ucp-agent']?.match(/profile="(https:\/\/[^"]+)"/);
+    if (!agent)
+        return protocolError(400, 'invalid_profile_url', 'UCP-Agent must be `profile="https://..."`, an HTTPS URL of the platform profile.');
+    if (!req.headers['request-id'])
+        return protocolError(400, 'missing_request_id', 'Request-Id is required on every request.');
+    const { shared, webhookUrl } = negotiate(agent[1]);
+    const ctx = { record: r, origin, platform: agent[1], shared, webhookUrl, bearer: bearerOf(req) };
+    // 2. Body integrity and idempotency.
+    const body = req.body ?? '';
+    if (req.headers['content-digest'] && req.headers['content-digest'] !== contentDigest(body))
+        return protocolError(400, 'digest_mismatch', 'Content-Digest does not match the body.');
+    let parsed = {};
+    if (body) {
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            return protocolError(400, 'invalid_json', 'The body is not valid JSON.');
+        }
+    }
+    const mutating = req.method !== 'GET' && !path.startsWith('/catalog/') && path !== '/ask';
+    const key = req.headers['idempotency-key'];
+    const digest = contentDigest(body);
+    if (mutating) {
+        if (!key)
+            return protocolError(400, 'missing_idempotency_key', 'Idempotency-Key is required on operations that change state.');
+        const seen = r.ucp.idempotency[`${req.method} ${path} ${key}`];
+        if (seen) {
+            if (seen.digest !== digest)
+                return protocolError(409, 'idempotency_key_reused', 'Idempotency-Key was already used with a different body.');
+            return { status: seen.status, headers: { ...seen.headers, 'idempotent-replayed': 'true' }, body: seen.body };
+        }
+    }
+    // 3. The operation.
+    const res = dispatch(ctx, req.method, path, parsed);
+    if (mutating && key)
+        r.ucp.idempotency[`${req.method} ${path} ${key}`] = { digest, status: res.status, headers: res.headers, body: res.body };
+    return res;
+}
+function dispatch(ctx, method, path, body) {
+    const r = ctx.record;
+    const out = (status, data) => withUcpHeaders(r, json(status, strip(data)));
+    const needs = (cap) => (ctx.shared.has(cap) ? null : out(200, shop.errorResponse(ctx, 'checkout', 'capabilities_incompatible', `${cap} is not shared with this platform.`)));
+    let m;
+    if (method === 'POST' && path === '/catalog/search')
+        return needs('dev.ucp.shopping.catalog.search') ?? out(200, shop.searchCatalog(ctx, body));
+    if (method === 'POST' && path === '/catalog/lookup')
+        return needs('dev.ucp.shopping.catalog.lookup') ?? out(200, shop.lookupCatalog(ctx, body));
+    if (method === 'POST' && path === '/catalog/product')
+        return needs('dev.ucp.shopping.catalog.lookup') ?? out(200, shop.getProduct(ctx, body));
+    if (method === 'POST' && path === '/carts') {
+        const blocked = needs('dev.ucp.shopping.cart');
+        if (blocked)
+            return blocked;
+        const created = shop.createCart(ctx, body);
+        return out(created.status, created.body);
+    }
+    if ((m = path.match(/^\/carts\/([^/]+)$/))) {
+        if (method === 'GET')
+            return needs('dev.ucp.shopping.cart') ?? out(200, shop.getCart(ctx, m[1]));
+        if (method === 'PUT')
+            return needs('dev.ucp.shopping.cart') ?? out(200, shop.updateCart(ctx, m[1], body));
+    }
+    if (method === 'POST' && (m = path.match(/^\/carts\/([^/]+)\/cancel$/)))
+        return needs('dev.ucp.shopping.cart') ?? out(200, shop.cancelCart(ctx, m[1]));
+    if (method === 'POST' && path === '/checkout-sessions') {
+        const blocked = needs('dev.ucp.shopping.checkout');
+        if (blocked)
+            return blocked;
+        const created = shop.createCheckout(ctx, body);
+        return out(created.status, created.body);
+    }
+    if ((m = path.match(/^\/checkout-sessions\/([^/]+)$/))) {
+        if (method === 'GET')
+            return needs('dev.ucp.shopping.checkout') ?? out(200, shop.getCheckout(ctx, m[1]));
+        if (method === 'PUT')
+            return needs('dev.ucp.shopping.checkout') ?? out(200, shop.updateCheckout(ctx, m[1], body));
+    }
+    if (method === 'POST' && (m = path.match(/^\/checkout-sessions\/([^/]+)\/complete$/)))
+        return needs('dev.ucp.shopping.checkout') ?? out(200, shop.completeCheckout(ctx, m[1], body));
+    if (method === 'POST' && (m = path.match(/^\/checkout-sessions\/([^/]+)\/cancel$/)))
+        return needs('dev.ucp.shopping.checkout') ?? out(200, shop.cancelCheckout(ctx, m[1]));
+    if (method === 'GET' && (m = path.match(/^\/orders\/([^/]+)$/))) {
+        const blocked = needs('dev.ucp.shopping.order');
+        if (blocked)
+            return blocked;
+        const order = shop.getOrder(ctx, m[1]);
+        if (!order)
+            return out(200, shop.errorResponse(ctx, 'order', 'not_found', `No order ${m[1]}.`));
+        const auth = authorize(ctx, order);
+        if (auth)
+            return auth;
+        return out(200, order);
+    }
+    if (method === 'POST' && path === '/ask')
+        return needs('dev.ucp.common.ask') ?? out(200, shop.ask(ctx, body));
+    return protocolError(404, 'not_found', `No operation ${method} ${path} in this service.`);
+}
+/** Orders are private: the platform that placed one, or a buyer token with the order scope, may read it. */
+function authorize(ctx, order) {
+    const r = ctx.record;
+    const issuer = ctx.origin;
+    const bearer = ctx.bearer;
+    if (bearer) {
+        const t = r.ucp.tokens[bearer];
+        if (!t || new Date(t.expires_at) < new Date()) {
+            return json(401, { ucp: shop.envelope(ctx, 'order', 'error'), messages: [{ type: 'error', code: 'identity_required', content: 'The token is invalid or expired.', severity: 'requires_buyer_review' }] }, { 'www-authenticate': `Bearer realm="${issuer}", error="invalid_token"` });
+        }
+        if (!t.scope.split(' ').some((s) => SCOPES.includes(s))) {
+            return json(403, { ucp: shop.envelope(ctx, 'order', 'error'), messages: [{ type: 'error', code: 'insufficient_scope', content: `Reading orders needs ${SCOPES[0]}.`, severity: 'requires_buyer_review' }] }, { 'www-authenticate': `Bearer realm="${issuer}", error="insufficient_scope", scope="${SCOPES[0]}"` });
+        }
+        return null;
+    }
+    if (order._platform === ctx.platform)
+        return null;
+    return json(401, { ucp: shop.envelope(ctx, 'order', 'error'), messages: [{ type: 'error', code: 'identity_required', content: 'Sign in to see this order.', severity: 'requires_buyer_review' }] }, { 'www-authenticate': `Bearer realm="${issuer}"` });
+}
+// ---------- OAuth 2.0 for identity linking (RFC 8414 metadata, PKCE, client credentials)
+function oauthMetadata(origin) {
+    return {
+        issuer: origin,
+        authorization_endpoint: `${origin}/oauth/authorize`,
+        token_endpoint: `${origin}/oauth/token`,
+        revocation_endpoint: `${origin}/oauth/revoke`,
+        jwks_uri: `${origin}/oauth/jwks`,
+        scopes_supported: SCOPES,
+        response_types_supported: ['code'],
+        grant_types_supported: ['authorization_code', 'refresh_token', 'client_credentials'],
+        code_challenge_methods_supported: ['S256'],
+        token_endpoint_auth_methods_supported: ['none', 'client_secret_basic'],
+        authorization_response_iss_parameter_supported: true,
+    };
+}
+function form(body) {
+    return Object.fromEntries(new URLSearchParams(body ?? ''));
+}
+function handleOauth(req, r, origin, path) {
+    const u = r.ucp;
+    const oauthError = (error, description, status = 400) => json(status, { error, error_description: description });
+    if (path === '/.well-known/oauth-authorization-server' && req.method === 'GET')
+        return json(200, oauthMetadata(origin), { 'cache-control': 'public, max-age=300' });
+    if (path === '/oauth/jwks' && req.method === 'GET')
+        return json(200, { keys: [u.public_jwk] });
+    if (path === '/oauth/authorize' && req.method === 'GET') {
+        const q = Object.fromEntries(req.url.searchParams);
+        if (q.response_type !== 'code' || !q.client_id || !q.redirect_uri || !q.code_challenge || q.code_challenge_method !== 'S256') {
+            return oauthError('invalid_request', 'response_type=code, client_id, redirect_uri, code_challenge and code_challenge_method=S256 are required.');
+        }
+        // A sandbox has no users: the buyer is signed in and consents at once.
+        const code = crypto.randomBytes(16).toString('hex');
+        u.codes[code] = { client_id: q.client_id, redirect_uri: q.redirect_uri, scope: q.scope ?? SCOPES[0], code_challenge: q.code_challenge, expires_at: new Date(Date.now() + 600_000).toISOString() };
+        const location = new URL(q.redirect_uri);
+        location.searchParams.set('code', code);
+        if (q.state)
+            location.searchParams.set('state', q.state);
+        location.searchParams.set('iss', origin);
+        return { status: 302, headers: { location: location.toString(), 'cache-control': 'no-store' }, body: '' };
+    }
+    if (path === '/oauth/token' && req.method === 'POST') {
+        const f = form(req.body);
+        let scope = f.scope ?? SCOPES[0];
+        let client = f.client_id ?? 'anonymous';
+        if (f.grant_type === 'authorization_code') {
+            const c = u.codes[f.code ?? ''];
+            if (!c || new Date(c.expires_at) < new Date())
+                return oauthError('invalid_grant', 'Unknown or expired code.');
+            if (c.redirect_uri !== f.redirect_uri || c.client_id !== f.client_id)
+                return oauthError('invalid_grant', 'redirect_uri or client_id do not match the authorization request.');
+            const challenge = crypto.createHash('sha256').update(f.code_verifier ?? '').digest('base64url');
+            if (challenge !== c.code_challenge)
+                return oauthError('invalid_grant', 'PKCE verification failed.');
+            delete u.codes[f.code];
+            scope = c.scope;
+            client = c.client_id;
+        }
+        else if (f.grant_type !== 'client_credentials')
+            return oauthError('unsupported_grant_type', 'Use authorization_code or client_credentials.');
+        const token = `at_${crypto.randomBytes(16).toString('hex')}`;
+        u.tokens[token] = { client_id: client, scope, expires_at: new Date(Date.now() + 3600_000).toISOString() };
+        return json(200, { access_token: token, token_type: 'Bearer', expires_in: 3600, scope }, { 'cache-control': 'no-store' });
+    }
+    if (path === '/oauth/revoke' && req.method === 'POST') {
+        delete u.tokens[form(req.body).token ?? ''];
+        return { status: 200, headers: {}, body: '' };
+    }
+    return null;
+}
+// ---------- permalink, pages, storefront
+const html = (status, title, body, headers = {}) => ({
+    status,
+    headers: { 'content-type': 'text/html; charset=utf-8', ...headers },
+    body: `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title></head><body><main><h1>${title}</h1>${body}</main></body></html>\n`,
+});
+function handlePermalink(req, r, origin, path) {
+    const safe = { 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' };
+    const items = path.replace(/^\/buy\/?/, '');
+    const lines = [];
+    if (items) {
+        if (!/^(?:[A-Za-z0-9._-]+|~[A-Za-z0-9_-]+):[1-9][0-9]*(?:,(?:[A-Za-z0-9._-]+|~[A-Za-z0-9_-]+):[1-9][0-9]*)*$/.test(items)) {
+            return { status: 303, headers: { location: `${origin}/`, ...safe }, body: '' };
+        }
+        for (const part of items.split(',')) {
+            const [token, qty] = part.split(':');
+            const itemId = token.startsWith('~') ? Buffer.from(token.slice(1), 'base64url').toString('utf8') : token;
+            lines.push({ item: { id: itemId }, quantity: Number(qty) });
+        }
+    }
+    const body = { line_items: lines };
+    for (const [k, v] of req.url.searchParams) {
+        if (k === 'continue_to')
+            continue;
+        const pointer = k.replace(/^\/+/, '').split('/');
+        if (pointer[0] === 'context' || pointer[0] === 'buyer')
+            (body[pointer[0]] ??= {})[pointer[1]] = v;
+        if (pointer[0] === 'discounts' && pointer[1] === 'codes')
+            ((body.discounts ??= {}).codes ??= []).push(v);
+    }
+    const ctx = { record: r, origin, platform: 'permalink', shared: new Set(OUR_CAPABILITIES) };
+    const created = lines.length ? shop.createCart(ctx, body) : null;
+    const cartId = created?.body?.id;
+    let target = `${origin}/`;
+    const cont = req.url.searchParams.get('continue_to');
+    if (cont && /^\/(?!\/)[^\s\\]*$/.test(cont))
+        target = new URL(cont, origin).toString();
+    else if (cartId)
+        target = `${origin}/carts/${cartId}`;
+    return { status: 303, headers: { location: target, ...safe }, body: '' };
+}
+const MIME = { html: 'text/html; charset=utf-8', css: 'text/css', js: 'text/javascript', mjs: 'text/javascript', json: 'application/json', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', ico: 'image/x-icon', txt: 'text/plain' };
+function serveStorefront(r, path) {
+    const files = r.ucp.files;
+    const candidates = [path.replace(/^\//, ''), `${path.replace(/^\/|\/$/g, '')}/index.html`.replace(/^\//, ''), ...(path === '/' ? ['index.html'] : [])];
+    for (const c of candidates) {
+        if (files[c] !== undefined) {
+            const ext = c.split('.').pop() ?? '';
+            return { status: 200, headers: { 'content-type': MIME[ext] ?? 'application/octet-stream' }, body: Buffer.from(files[c], 'base64').toString(ext in MIME && !MIME[ext].startsWith('image') ? 'utf8' : 'binary') };
+        }
+    }
+    if (Object.keys(files).length === 0)
+        return html(200, r.org, '<p>Nothing published yet. Run <code>c11r storefront publish</code>.</p>');
+    return html(404, 'Not found', `<p>No ${path} in this storefront.</p>`);
+}
+// ---------- the host
+export function handleUcp(req, r) {
+    const origin = `https://${req.url.hostname}`;
+    const path = req.url.pathname.replace(/\/+$/, '') || '/';
+    if (path === '/.well-known/ucp' && req.method === 'GET')
+        return json(200, profile(r, origin), { 'cache-control': 'public, max-age=300' });
+    const oauth = handleOauth(req, r, origin, path);
+    if (oauth)
+        return oauth;
+    if (path.startsWith('/ucp/v1/') || path === '/ucp/v1') {
+        const res = handleService({ ...req, headers: { ...req.headers } }, r, origin, path.slice('/ucp/v1'.length) || '/');
+        return res;
+    }
+    if (path === '/buy' || path.startsWith('/buy/'))
+        return handlePermalink(req, r, origin, path);
+    let m;
+    if ((m = path.match(/^\/policies\/(privacy|terms|returns)$/))) {
+        const titles = { privacy: 'Privacy policy', terms: 'Terms of service', returns: 'Returns' };
+        return html(200, titles[m[1]], `<p>Default sandbox ${titles[m[1]].toLowerCase()} for ${r.org}. Set <code>policies</code> in store.yml to use your own.</p>`);
+    }
+    if ((m = path.match(/^\/(carts|checkout-sessions|orders)\/([^/]+)$/))) {
+        const kind = m[1] === 'carts' ? 'cart' : m[1] === 'orders' ? 'order' : 'checkout';
+        const found = kind === 'cart' ? r.ucp.carts[m[2]] : kind === 'order' ? r.ucp.orders[m[2]] : r.ucp.checkouts[m[2]];
+        if (!found)
+            return html(404, 'Not found', `<p>No ${kind} ${m[2]}.</p>`);
+        return html(200, `${kind === 'order' ? `Order ${found.label}` : `Your ${kind}`}`, `<p>${kind === 'order' ? 'Thank you. ' : ''}${found.line_items.length} line item(s), ${found.currency} ${(found.totals.at(-1).amount / 100).toFixed(2)}.</p>`);
+    }
+    return serveStorefront(r, path);
+}
+/** Lets the service read the bearer token for order authorization. */
+export function bearerOf(req) {
+    return req.headers.authorization?.replace(/^Bearer /i, '');
+}

package/dist/api/stub.js

@@ -0,0 +1,112 @@
+// 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`.');
+}

package/dist/api/transport.js

@@ -0,0 +1,37 @@
+// One way to send HTTP requests, for both the management client and the UCP buyer:
+// over the network, or in-process to the stub when C11R_API_URL=stub.
+// When the API URL points at a local server, requests to other hosts (the store
+// hosts) are rewritten to that server's /-/<host>/ prefix, so one local process
+// stands in for the whole platform.
+import { fail } from '../output.js';
+import { handle } from './stub/index.js';
+export const DEFAULT_API_URL = 'https://api.commercelayer.ai';
+export const apiUrl = () => process.env.C11R_API_URL ?? DEFAULT_API_URL;
+export async function send(method, url, headers = {}, body) {
+    const base = apiUrl();
+    const lower = {};
+    for (const [k, v] of Object.entries(headers))
+        lower[k.toLowerCase()] = v;
+    if (body !== undefined && !lower['content-type'])
+        lower['content-type'] = 'application/json';
+    if (base === 'stub')
+        return handle({ method, url: new URL(url), headers: lower, body });
+    let target = url;
+    const baseUrl = new URL(base);
+    const targetUrl = new URL(url);
+    if (base !== DEFAULT_API_URL && targetUrl.host !== baseUrl.host && !url.startsWith(base)) {
+        target = `${base.replace(/\/$/, '')}/-/${targetUrl.host}${targetUrl.pathname}${targetUrl.search}`;
+    }
+    let res;
+    try {
+        // Never follow redirects: UCP forbids it for profiles, and the 302/303 of
+        // /oauth/authorize and the permalink are the answer, not a hop.
+        res = await fetch(target, { method, headers: lower, body, redirect: 'manual' });
+    }
+    catch (e) {
+        fail('api_unreachable', `Could not reach ${new URL(target).origin}: ${e.message}`, 'Check the network. If you are developing the CLI, run `npm run stub-api` and set C11R_API_URL=http://localhost:4747, or set it to "stub".');
+    }
+    const resHeaders = {};
+    res.headers.forEach((v, k) => (resHeaders[k] = v));
+    return { status: res.status, headers: resHeaders, body: await res.text() };
+}

package/dist/api/types.js

@@ -0,0 +1,4 @@
+// The contract between the CLI and api.commercelayer.ai (the management API).
+// The store hosts speak UCP, which has its own spec; src/ucp/ is the client side.
+// stub/ implements both locally until the real platform exists.
+export {};

package/dist/bin.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// c11r: the Commerce Layer CLI for coding agents (package @commercelayer/agent-cli).
+// Arguments are a command, optional subcommand, --flags and --option values.
+// 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 argv = process.argv.slice(2);
+const flags = new Set();
+const values = {};
+const args = [];
+for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) {
+        args.push(a);
+        continue;
+    }
+    const eq = a.indexOf('=');
+    if (eq > 0)
+        values[a.slice(2, eq)] = a.slice(eq + 1);
+    else if (VALUE_OPTIONS.has(a) && i + 1 < argv.length && !argv[i + 1].startsWith('--'))
+        values[a.slice(2)] = argv[++i];
+    else
+        flags.add(a);
+}
+const [name, sub] = args;
+async function run() {
+    if (flags.has('--version') || name === 'version')
+        return { version: cmd.VERSION };
+    switch (name) {
+        case undefined:
+        case 'help':
+            return cmd.help(args.slice(1).join(' ') || undefined);
+        case 'init':
+            return cmd.init();
+        case 'plan':
+            return cmd.plan();
+        case 'apply':
+            return cmd.apply(flags);
+        case 'status':
+            return cmd.status();
+        case 'claim':
+            return cmd.claim();
+        case 'storefront':
+            if (sub === 'init')
+                return cmd.storefrontInit(flags);
+            if (sub === 'publish')
+                return cmd.storefrontPublish();
+            throw new CliError('unknown_command', `There is no command "storefront ${sub ?? ''}".`, 'Use `c11r storefront init` or `c11r storefront publish`.');
+        case 'orders':
+            if (sub === 'test')
+                return cmd.ordersTest(flags, values);
+            if (sub === 'list')
+                return cmd.ordersList();
+            if (sub === 'show')
+                return cmd.ordersShow(args[2]);
+            throw new CliError('unknown_command', `There is no command "orders ${sub ?? ''}".`, 'Use `c11r orders test`, `orders list` or `orders show <id>`.');
+        case 'ucp':
+            if (sub === 'profile')
+                return cmd.ucpProfile(flags);
+            if (sub === 'check')
+                return cmd.ucpCheck();
+            throw new CliError('unknown_command', `There is no command "ucp ${sub ?? ''}".`, 'Use `c11r ucp profile` or `c11r ucp check`.');
+        default:
+            throw new CliError('unknown_command', `There is no command "${name}".`, `Run \`c11r help\`. Commands: ${Object.keys(cmd.HELP).join(', ')}.`);
+    }
+}
+run()
+    .then((result) => {
+    print(result);
+    if (result?.status === 'fail')
+        process.exit(1);
+})
+    .catch((e) => {
+    if (e instanceof CliError) {
+        print({ error: { code: e.code, message: e.message, hint: e.hint } });
+    }
+    else {
+        const message = e instanceof Error ? e.message : String(e);
+        print({ error: { code: 'internal', message, hint: 'This is a bug in the CLI. Report it at https://commercelayer.ai/support with this output.' } });
+    }
+    process.exit(1);
+});