@commercelayer/agent-cli 0.8.0 → 1.0.0-dev.0

package/dist/secrets.js

@@ -0,0 +1,189 @@
+// Secrets in answers (contract section 22). credentials create and credentials token answer a
+// secret once, in data.secret: the CLI writes it to a file with mode 600 and prints the file, the
+// format and a hint, never the value. The file is checked before the request is sent, so a create
+// does not make a secret that then has nowhere to go.
+//
+// Default file: ~/.config/c11r/secrets/<org>/<credential name>.env (or <id>-token.env for a token),
+// outside the project so it cannot be committed. --out picks another; --format env|json. A file
+// there already is replaced only with --yes. A file inside a git repository that git does not
+// ignore gets the warning secret_not_ignored.
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { markOutWritten } from './config.js';
+import { fail } from './errors.js';
+export function secretsDir() {
+    const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    return path.join(base, 'c11r', 'secrets');
+}
+const safe = (s) => s.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'credential';
+/** Where the secret will go, checked now: writable, not a link, not there already unless --yes. */
+export function planSecret(opts) {
+    const out = opts.values.out;
+    const format = opts.values.format ?? null;
+    const base = opts.verb === 'token' ? `${safe(opts.id ?? 'credential')}-token` : safe(String(opts.values.name ?? opts.id ?? 'credential'));
+    const file = out ? path.resolve(out) : path.join(secretsDir(), safe(opts.org ?? 'default'), base);
+    const plan = { file: out || !format ? file : `${file}.${format}`, format, fixed: Boolean(out), overwrite: opts.yes };
+    const candidates = plan.fixed || format ? [plan.file] : [`${file}.env`, `${file}.json`];
+    for (const c of candidates) {
+        let st = null;
+        try {
+            st = fs.lstatSync(c);
+        }
+        catch {
+            // Not there: fine.
+        }
+        if (st?.isSymbolicLink())
+            fail('insecure_file', `${c} is a symbolic link. c11r writes a secret only to a plain file.`, { path: 'out' });
+        if (st && !st.isFile())
+            fail('invalid_value', `${c} is not a file.`, { path: 'out' });
+        if (st && !opts.yes) {
+            fail('conflict', `${c} exists. c11r replaces it only with --yes, or writes the secret elsewhere with --out.`, { path: 'out', next_step: { action: 'fix_request', command: null }, details: { file: c } }, 'rejected');
+        }
+    }
+    const dir = path.dirname(candidates[0]);
+    const existing = nearestExisting(dir);
+    try {
+        fs.accessSync(existing, fs.constants.W_OK);
+    }
+    catch {
+        fail('invalid_value', `${dir} cannot be written by this user, so the secret would have nowhere to go.`, { path: 'out' });
+    }
+    return plan;
+}
+function nearestExisting(dir) {
+    let d = dir;
+    while (!fs.existsSync(d)) {
+        const up = path.dirname(d);
+        if (up === d)
+            break;
+        d = up;
+    }
+    return d;
+}
+/** Writes data.secret to its file and answers the envelope without the value. */
+export function writeSecret(r, plan, ctx) {
+    const data = (r.data ?? {});
+    const secret = data.secret;
+    const credentialId = data.credential?.id ?? data.id ?? ctx.id;
+    const format = plan.format ?? (secret.format === 'json' ? 'json' : 'env');
+    const file = plan.fixed || plan.format ? plan.file : `${plan.file}.${format}`;
+    const env = secret.env && Object.keys(secret.env).length ? { ...secret.env } : { [`CL_${(secret.kind ?? 'secret').toUpperCase()}`]: String(secret.value ?? '') };
+    // The endpoint goes with every secret, so the file is enough to call Commerce Layer.
+    if (!env.CL_BASE_ENDPOINT && typeof data.base_endpoint === 'string')
+        env.CL_BASE_ENDPOINT = data.base_endpoint;
+    const written = new Date().toISOString();
+    const content = format === 'json'
+        ? JSON.stringify({ org: ctx.org, credential_id: credentialId ?? null, kind: secret.kind ?? null, value: secret.value ?? null, expires_at: secret.expires_at ?? null, env, written_at: written }, null, 2) + '\n'
+        : [`# ${secret.kind ?? 'secret'} of credential ${credentialId ?? '?'} in ${ctx.org ?? '?'}, written by c11r at ${written}.`, '# Keep it out of git.', ...Object.entries(env).map(([k, v]) => `${k}=${v}`), ''].join('\n');
+    try {
+        atomicWrite(file, content, plan.overwrite);
+    }
+    catch (e) {
+        const id = credentialId ?? '<id>';
+        const created = ctx.verb === 'create';
+        fail('secret_not_written', `The API answered the ${secret.kind ?? 'secret'} of credential ${id} once, and c11r could not write it to ${file}: ${e.message}. It was not printed, and the API cannot show it again. ${created ? `c11r credentials token ${id} gives a working token now; for a new secret, create another credential and delete ${id}.` : `c11r credentials token ${id} gives another token.`}`, { path: 'out', next_step: { action: 'fix_request', command: `c11r credentials token ${id}` }, details: { credential_id: credentialId ?? null, file } });
+    }
+    // An --out file is not removed with its credential: remember that one exists, for the warning.
+    if (plan.fixed && ctx.org)
+        markOutWritten(ctx.org, true);
+    // The API says the secret is shown once: c11r kept it in the file, and printed none of it.
+    const warnings = r.warnings.filter((w) => w.code !== 'secret_shown_once' && w.code !== 'token_shown_once');
+    if (!ignoredByGit(file))
+        warnings.push({ code: 'secret_not_ignored', message: `${file} is inside a git repository and git does not ignore it: add it to .gitignore before any commit.`, path: 'out' });
+    const { value: _value, env: _env, ...rest } = secret;
+    return {
+        ...r,
+        data: { ...data, secret: { kind: rest.kind ?? null, file, format, hint: rest.hint ?? null, mode: '600', expires_at: rest.expires_at ?? null } },
+        warnings,
+    };
+}
+/** What a dry run says about the file: where it would go and whether one is there. */
+export function describePlan(plan) {
+    const files = plan.fixed || plan.format ? [plan.file] : [`${plan.file}.env`, `${plan.file}.json`];
+    return { file: files[0], format: plan.format ?? 'env', would_overwrite: files.some((f) => fs.existsSync(f)), writable: true };
+}
+function atomicWrite(file, content, overwrite) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    if (!overwrite && fs.existsSync(file))
+        throw new Error('the file appeared meanwhile');
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+    fs.writeFileSync(tmp, content, { mode: 0o600, flag: 'wx' });
+    try {
+        fs.chmodSync(tmp, 0o600);
+        fs.renameSync(tmp, file);
+    }
+    catch (e) {
+        fs.rmSync(tmp, { force: true });
+        throw e;
+    }
+}
+/** True unless the file is inside a git repository that does not ignore it. */
+function ignoredByGit(file) {
+    const r = spawnSync('git', ['check-ignore', '-q', path.basename(file)], { cwd: path.dirname(file), stdio: 'ignore' });
+    // 0 ignored, 1 not ignored, 128 not a repository (or no git).
+    return r.status !== 1;
+}
+/** The folder of an organization's secret files. */
+export const orgSecretsDir = (org) => path.join(secretsDir(), safe(org));
+/**
+ * After credentials delete: the files c11r wrote in the organization's secrets folder for that
+ * credential (its secret and its tokens), found by the credential id each file records. Files
+ * written with --out elsewhere are not tracked.
+ */
+export function removeCredentialFiles(org, credentialId) {
+    const dir = orgSecretsDir(org);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const removed = [];
+    for (const n of names) {
+        const file = path.join(dir, n);
+        let text;
+        try {
+            if (!fs.lstatSync(file).isFile())
+                continue;
+            text = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let mine = text.startsWith('#') && new RegExp(`^# \\S+ of credential ${credentialId.replace(/[^\w-]/g, '')} in `).test(text);
+        if (!mine) {
+            try {
+                mine = JSON.parse(text).credential_id === credentialId;
+            }
+            catch {
+                // Not JSON, not ours.
+            }
+        }
+        if (mine) {
+            fs.rmSync(file);
+            removed.push(file);
+        }
+    }
+    if (removed.length) {
+        try {
+            fs.rmdirSync(dir);
+        }
+        catch {
+            // Not empty: other credentials' files stay.
+        }
+    }
+    return removed;
+}
+/** After sandbox destroy: the organization's whole secrets folder. Null if there was none. */
+export function removeOrgSecrets(org) {
+    const dir = orgSecretsDir(org);
+    if (!fs.existsSync(dir))
+        return null;
+    fs.rmSync(dir, { recursive: true, force: true });
+    return dir;
+}
+export const OUT_NOT_TRACKED = { code: 'out_files_not_tracked', message: 'Only files in c11r\'s secrets folder (~/.config/c11r/secrets/<org>/) are removed with what they belong to. A file written with --out is not tracked: delete it where it was written.' };

package/dist/version.js

@@ -1,9 +1,5 @@
-// The CLI's version and how it names itself on the wire.
+// The CLI's version, from package.json, and the User-Agent every request carries.
 import { createRequire } from 'node:module';
-/** 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;
-/** The User-Agent of every request: the API answers cli_outdated when a newer CLI exists. */
-export const USER_AGENT = `c11r/${VERSION} (node/${process.versions.node.split('.')[0]})`;
-/** The one way to run the CLI that is always current, whatever is installed. */
-export const NPX = 'npx -y @commercelayer/agent-cli@latest';
-export const LATEST_HINT = `${NPX} always runs the newest version, even where a c11r binary is installed.`;
+const pkg = createRequire(import.meta.url)('../package.json');
+export const VERSION = pkg.version;
+export const USER_AGENT = `c11r/${VERSION} (node ${process.versions.node}; ${process.platform})`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.8.0",
-  "description": "c11r: the Commerce Layer CLI for coding agents. Builds a sandbox store that people and shopping agents can buy from.",
+  "version": "1.0.0-dev.0",
+  "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": [
     "commercelayer",
@@ -24,20 +24,15 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist.next && tsc -p tsconfig.json --outDir dist.next && chmod +x dist.next/bin.js dist.next/api/server.js && rm -rf dist.old && { mv dist dist.old 2>/dev/null; mv dist.next dist; } && rm -rf dist.old",
+    "build": "rm -rf dist.next && tsc -p tsconfig.json --outDir dist.next && chmod +x dist.next/bin.js && rm -rf dist.old && { mv dist dist.old 2>/dev/null; mv dist.next dist; } && rm -rf dist.old",
     "dev": "tsx src/bin.ts",
-    "stub-api": "tsx src/api/server.ts",
-    "test": "npm run build && vitest run",
-    "prepublishOnly": "npm run build"
+    "test": "npm run build && vitest run"
   },
   "dependencies": {
-    "imapflow": "^2.10.2",
-    "postal-mime": "^4.2.0",
     "yaml": "^2.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "happy-dom": "^21.0.4",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"

package/dist/api/client.js

@@ -1,190 +0,0 @@
-// The client for the management API at api.commercelayer.ai.
-import { CliError, fail, notice } from '../output.js';
-import { NPX } from '../version.js';
-import { apiUrl, DEFAULT_API_URL, send } from './transport.js';
-export function createApi(auth) {
-    const base = apiUrl() === 'stub' ? DEFAULT_API_URL : apiUrl().replace(/\/$/, '');
-    const org = () => {
-        if (!auth)
-            fail('no_store', 'There is no store in this repo.', 'Run `c11r init` in the repo root first.');
-        return `/stores/${auth.org}`;
-    };
-    const request = async (method, path, body) => {
-        const headers = { accept: 'application/json' };
-        if (auth)
-            headers.authorization = `Bearer ${auth.token}`;
-        const res = await send(method, base + path, headers, body === undefined ? undefined : JSON.stringify(body));
-        let data;
-        try {
-            data = res.body ? JSON.parse(res.body) : null;
-        }
-        catch {
-            fail('api_error', `${base} answered ${res.status} with something that is not JSON.`, 'Try again. If it keeps happening, tell the human, with the output of `c11r status`.');
-        }
-        // The API flags an outdated CLI (from the User-Agent) in warnings, on any answer, errors included.
-        const warnings = data && typeof data === 'object' && !Array.isArray(data) ? data.warnings : undefined;
-        if (Array.isArray(warnings)) {
-            const isOutdated = (w) => !!w && typeof w === 'object' && w.code === 'cli_outdated';
-            for (const n of warnings.filter(isOutdated))
-                notice({ ...n, hint: n.hint ?? `Run the commands with ${NPX}. If c11r is installed globally, tell the human it is on ${n.current} and ${n.latest} exists.` });
-            // Printed once, at the top of the output, not inside the order or store it came with.
-            const rest = warnings.filter((w) => !isOutdated(w));
-            if (rest.length)
-                data.warnings = rest;
-            else
-                delete data.warnings;
-        }
-        if (res.status < 400)
-            return data;
-        const err = data?.error;
-        if (err)
-            fail(err.code, err.message, err.hint, err.path);
-        fail('api_error', `The API answered ${res.status}.`, 'Try again. If it keeps happening, tell the human, with the output of `c11r status`.');
-    };
-    // Promotions and links: on an API older than them, the collection route is an unknown route (404 not_found).
-    const collection = (kind) => `${org()}/${kind}`;
-    const one = (kind, id) => `${collection(kind)}/${encodeURIComponent(id)}`;
-    const unsupported = async (kind, call) => {
-        try {
-            return await call;
-        }
-        catch (e) {
-            if (e instanceof CliError && (e.code === 'not_found' || (e.code === 'api_error' && /\b404\b/.test(e.message))))
-                fail(`${kind}_unsupported`, `This API does not manage ${kind} yet.`, 'Try again later; tell the human if it persists.');
-            throw e;
-        }
-    };
-    const found = async (kind, id, call) => {
-        try {
-            return await call;
-        }
-        catch (e) {
-            if (e instanceof CliError && e.code === 'not_found')
-                fail('not_found', `There is no ${kind.slice(0, -1)} ${id}.`, `Run \`c11r ${kind} list\` for the ids, or \`c11r ${kind} create\` to make it.`);
-            throw e;
-        }
-    };
-    // Orders and shipments for the merchant: an API older than them answers the UCP array on GET
-    // /orders?view=merchant and not_found on the routes it lacks. A not_found on one order or
-    // shipment is checked against the list, so a missing order is still not_found.
-    const qs = (query) => {
-        const p = new URLSearchParams(Object.entries(query).filter(([, v]) => v !== undefined && v !== ''));
-        return p.toString() ? `&${p}` : '';
-    };
-    const ordersUnsupported = () => fail('orders_unsupported', 'This API does not manage orders for the merchant yet.', 'Try again later; tell the human if it persists. c11r orders test still places test orders.');
-    const shipmentsUnsupported = () => fail('fulfillment_unsupported', 'This API does not manage shipments yet.', 'Try again later; tell the human if it persists.');
-    const listMerchantOrders = async (query) => {
-        const r = (await request('GET', `${org()}/orders?view=merchant${qs(query)}`));
-        if (Array.isArray(r) || !Array.isArray(r.orders))
-            ordersUnsupported();
-        return r;
-    };
-    const listShipments = async (query) => {
-        try {
-            const p = new URLSearchParams(Object.entries(query).filter(([, v]) => v !== undefined && v !== ''));
-            return (await request('GET', `${org()}/shipments${p.toString() ? `?${p}` : ''}`));
-        }
-        catch (e) {
-            if (e instanceof CliError && e.code === 'not_found')
-                shipmentsUnsupported();
-            throw e;
-        }
-    };
-    const orderCall = async (call) => {
-        try {
-            return await call();
-        }
-        catch (e) {
-            if (e instanceof CliError && e.code === 'not_found')
-                await listMerchantOrders({ limit: '1' });
-            throw e;
-        }
-    };
-    const shipmentCall = async (call) => {
-        try {
-            return await call();
-        }
-        catch (e) {
-            if (e instanceof CliError && e.code === 'not_found')
-                await listShipments({ limit: '1' });
-            throw e;
-        }
-    };
-    const orderPath = (id) => `${org()}/orders/${encodeURIComponent(id)}`;
-    const shipmentPath = (id) => `${org()}/shipments/${encodeURIComponent(id)}`;
-    return {
-        listMerchantOrders,
-        getMerchantOrder: (id) => orderCall(async () => {
-            const o = (await request('GET', `${orderPath(id)}?view=merchant`));
-            if (o && o.payment_status === undefined)
-                ordersUnsupported();
-            return o;
-        }),
-        createOrder: async (body) => {
-            try {
-                return (await request('POST', `${org()}/orders`, body));
-            }
-            catch (e) {
-                // An API before orders from messages has no POST /orders.
-                if (e instanceof CliError && e.code === 'not_found')
-                    fail('orders_unsupported', 'This API cannot create orders from messages yet.', 'Try again later; tell the human if it persists.');
-                throw e;
-            }
-        },
-        orderAction: (id, action, body) => orderCall(() => request('POST', `${orderPath(id)}/${action}`, body ?? {})),
-        listShipments,
-        // An API before the snapshot answers not_found: ops_unsupported, and the CLI reads the lists instead.
-        getOps: async (query) => {
-            try {
-                const r = (await request('GET', `${org()}/ops${qs(query).replace(/^&/, '?')}`));
-                if (!r || typeof r !== 'object' || !r.orders || !r.shipments)
-                    fail('ops_unsupported', 'This API has no operations snapshot yet.', 'The CLI reads the order and shipment lists instead.');
-                return r;
-            }
-            catch (e) {
-                if (e instanceof CliError && e.code === 'not_found')
-                    fail('ops_unsupported', 'This API has no operations snapshot yet.', 'The CLI reads the order and shipment lists instead.');
-                throw e;
-            }
-        },
-        insights: async (query) => {
-            try {
-                const r = (await request('GET', `${org()}/insights${qs(query).replace(/^&/, '?')}`));
-                if (!r || typeof r !== 'object' || !('totals' in r))
-                    fail('insights_unsupported', 'This API does not report insights yet.', 'Try again later; tell the human if it persists.');
-                return r;
-            }
-            catch (e) {
-                if (e instanceof CliError && e.code === 'not_found')
-                    fail('insights_unsupported', 'This API does not report insights yet.', 'Try again later; tell the human if it persists.');
-                throw e;
-            }
-        },
-        getShipment: (id) => shipmentCall(() => request('GET', shipmentPath(id))),
-        shipmentAction: (id, action, body) => shipmentCall(() => request('POST', `${shipmentPath(id)}/${action}`, body ?? {})),
-        listPromotions: () => unsupported('promotions', request('GET', collection('promotions'))),
-        createPromotion: (spec) => unsupported('promotions', request('POST', collection('promotions'), spec)),
-        getPromotion: (id) => found('promotions', id, request('GET', one('promotions', id))),
-        updatePromotion: (id, spec) => found('promotions', id, request('PUT', one('promotions', id), spec)),
-        setPromotionEnabled: (id, enabled) => found('promotions', id, request('POST', `${one('promotions', id)}/${enabled ? 'enable' : 'disable'}`)),
-        deletePromotion: async (id) => {
-            await found('promotions', id, request('DELETE', one('promotions', id)));
-        },
-        listLinks: () => unsupported('links', request('GET', collection('links'))),
-        createLink: (spec) => unsupported('links', request('POST', collection('links'), spec)),
-        getLink: (id) => found('links', id, request('GET', one('links', id))),
-        setLinkEnabled: (id, enabled) => found('links', id, request('POST', `${one('links', id)}/${enabled ? 'enable' : 'disable'}`)),
-        deleteLink: async (id) => {
-            await found('links', id, request('DELETE', one('links', id)));
-        },
-        // C11R_TEST=1 (our own test runs) asks the API to tag the organization as a test.
-        createSandbox: (name) => request('POST', '/sandboxes', process.env.C11R_TEST === '1' ? { name, test: true } : { name }),
-        getStore: () => request('GET', org()),
-        applyStore: (body) => request('PUT', `${org()}/resources`, body),
-        uploadAssets: (files) => request('PUT', `${org()}/assets`, { files }),
-        publishStorefront: (path, files) => request('PUT', `${org()}/storefront`, { path, files }),
-        listOrders: () => request('GET', `${org()}/orders`),
-        getOrder: (id) => request('GET', `${org()}/orders/${encodeURIComponent(id)}`),
-        startClaim: () => request('POST', `${org()}/claim`),
-    };
-}

package/dist/api/server.js

@@ -1,26 +0,0 @@
-#!/usr/bin/env node
-// Serve the stub platform over HTTP, so the CLI's real HTTP client can be exercised:
-//   npm run stub-api                       (port 4747)
-//   C11R_API_URL=http://localhost:4747 c11r init
-// Store hosts are reached as http://localhost:4747/-/<org>.sandbox.commercelayer.store/...
-// or with a real Host header.
-import http from 'node:http';
-import { handle } from './stub/index.js';
-const port = Number(process.env.PORT ?? 4747);
-http
-    .createServer((req, res) => {
-    let raw = '';
-    req.on('data', (chunk) => (raw += chunk));
-    req.on('end', () => {
-        const headers = {};
-        for (const [k, v] of Object.entries(req.headers))
-            if (typeof v === 'string')
-                headers[k.toLowerCase()] = v;
-        const host = headers.host ?? `localhost:${port}`;
-        const url = new URL(req.url ?? '/', `http://${host}`);
-        const { status, headers: resHeaders, body } = handle({ method: req.method ?? 'GET', url, headers, body: raw || undefined });
-        res.writeHead(status, resHeaders);
-        res.end(body);
-    });
-})
-    .listen(port, () => console.log(`stub platform on http://localhost:${port}`));

package/dist/api/stub/db.js

@@ -1,37 +0,0 @@
-// The stub's state: one JSON file, one record per sandbox. The real platform keeps
-// the same data behind api.commercelayer.ai and the store hosts.
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-const dbFile = process.env.C11R_STUB_DB
-    ?? path.join(process.env.XDG_STATE_HOME ?? path.join(os.homedir(), '.local', 'state'), 'c11r', 'stub-api.json');
-export function readDb() {
-    return fs.existsSync(dbFile) ? JSON.parse(fs.readFileSync(dbFile, 'utf8')) : {};
-}
-export function writeDb(db) {
-    fs.mkdirSync(path.dirname(dbFile), { recursive: true });
-    fs.writeFileSync(dbFile, JSON.stringify(db, null, 2) + '\n');
-}
-export const SANDBOX_DOMAIN = 'sandbox.commercelayer.store';
-/** The org a store hostname belongs to, or null if it is not a store host. */
-export function orgOfHost(hostname) {
-    const m = hostname.match(/^([a-z0-9-]+)\.sandbox\.commercelayer\.store$/);
-    return m ? m[1] : null;
-}
-/** Orders of a store, newest first, without private members. */
-export function publicOrders(r) {
-    return Object.values(r.ucp.orders).map((o) => strip(o)).reverse();
-}
-/** A deep copy without the members whose name starts with _. */
-export function strip(value) {
-    if (Array.isArray(value))
-        return value.map(strip);
-    if (value && typeof value === 'object') {
-        const out = {};
-        for (const [k, v] of Object.entries(value))
-            if (!k.startsWith('_'))
-                out[k] = strip(v);
-        return out;
-    }
-    return value;
-}

package/dist/api/stub/http.js

@@ -1,18 +0,0 @@
-// The HTTP shapes the stub works with: what a Cloudflare Worker would see. Keeping
-// the stub HTTP-shaped lets UCP headers (UCP-Agent, Idempotency-Key, signatures)
-// be modelled the way the real API will have to handle them.
-export function json(status, body, headers = {}) {
-    return { status, headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(body) };
-}
-/** The management API's error shape, the same the CLI prints. */
-export function error(status, code, message, hint, path) {
-    return json(status, { error: { code, message, hint, ...(path ? { path } : {}) } });
-}
-export function readJson(req) {
-    if (!req.body)
-        return undefined;
-    return JSON.parse(req.body);
-}
-export function bearer(req) {
-    return req.headers.authorization?.replace(/^Bearer /i, '');
-}

package/dist/api/stub/index.js

@@ -1,52 +0,0 @@
-// A stand-in for the whole platform: api.commercelayer.ai (management) and
-// <org>.sandbox.commercelayer.store (the store: UCP, OAuth, the storefront).
-// server.ts serves it over HTTP; transport.ts calls handle() in-process when
-// C11R_API_URL=stub, so agent tests need no server running.
-//
-// Routing is by hostname. Over local HTTP, where subdomains do not resolve, the
-// path prefix /-/<host>/... stands in for the hostname.
-import { orgOfHost, readDb, writeDb } from './db.js';
-import { json } from './http.js';
-import { handleManagement } from './management.js';
-import { handleUcp } from './ucp.js';
-export function handle(req) {
-    let url = req.url;
-    const prefixed = url.pathname.match(/^\/-\/([^/]+)(\/.*)?$/);
-    if (prefixed)
-        url = new URL(`https://${prefixed[1]}${prefixed[2] ?? '/'}${url.search}`);
-    const org = orgOfHost(url.hostname);
-    if (org === null)
-        return outdated(req, handleManagement({ ...req, url }));
-    const db = readDb();
-    const store = db[org];
-    if (!store)
-        return json(404, { error: { code: 'not_found', message: `There is no store at ${url.hostname}.`, hint: 'The sandbox may have expired.' } });
-    const res = handleUcp({ ...req, url }, store);
-    writeDb(db);
-    return res;
-}
-/** "0.5.1" → [0, 5, 1], for comparing versions. */
-const parts = (v) => v.split('.').map((n) => Number.parseInt(n, 10) || 0);
-const older = (a, b) => {
-    const [x, y] = [parts(a), parts(b)];
-    for (let i = 0; i < 3; i++)
-        if ((x[i] ?? 0) !== (y[i] ?? 0))
-            return (x[i] ?? 0) < (y[i] ?? 0);
-    return false;
-};
-/**
- * Like the API: a CLI whose User-Agent (c11r/<version>) is older than the latest gets a
- * cli_outdated warning on every JSON object it is answered. The stub's latest is
- * C11R_STUB_LATEST_CLI; unset, every CLI is current.
- */
-function outdated(req, res) {
-    const latest = process.env.C11R_STUB_LATEST_CLI;
-    const current = req.headers['user-agent']?.match(/^c11r\/(\d+\.\d+\.\d+)/)?.[1];
-    if (!latest || !current || !older(current, latest) || !res.body)
-        return res;
-    const body = JSON.parse(res.body.toString());
-    if (!body || typeof body !== 'object' || Array.isArray(body))
-        return res;
-    const warning = { code: 'cli_outdated', current, latest, hint: `Run the commands with npx -y @commercelayer/agent-cli@latest. If c11r is installed globally, tell the human it is on ${current} and ${latest} exists.` };
-    return { ...res, body: JSON.stringify({ ...body, warnings: [...(Array.isArray(body.warnings) ? body.warnings : []), warning] }) };
-}

package/dist/api/stub/locale.js

@@ -1,52 +0,0 @@
-// Locales on the store host, as the store Worker does them: one per country, from the
-// `locales` the API derives on apply (the stub keeps them on the record). The texts come
-// from applied.products[sku].translations[ll], falling back to the base language.
-export const COOKIE = 'c11r_locale';
-export const baseLanguage = (r) => r.applied?.language ?? 'en';
-/** The languages the store has: the base one, then every language a product is translated into. */
-export function languagesOf(r) {
-    const out = new Set([baseLanguage(r)]);
-    for (const p of Object.values(r.applied?.products ?? {}))
-        for (const ll of Object.keys(p.translations ?? {}))
-            out.add(ll);
-    return out;
-}
-/** A product's name, description and category in a language, falling back to the base one. */
-export function texts(p, ll) {
-    const t = p.translations?.[ll] ?? {};
-    return { name: t.name ?? p.name, description: t.description ?? p.description, category: t.category ?? p.category };
-}
-/** The store's locales; none before an apply that derived them (the site stays as it was). */
-export const localesOf = (r) => r.locales ?? [];
-/** The locale at /<path>/, by its country: a known country with the wrong language still matches. */
-export const localeOfCountry = (r, country) => localesOf(r).find((l) => l.country === country.toUpperCase());
-/** The locale a cookie names, if it is one of the store's. */
-export function cookieLocale(r, cookie) {
-    const m = cookie?.match(new RegExp(`(?:^|;\\s*)${COOKIE}=([a-z]{2}-[a-z]{2})`));
-    return m ? localesOf(r).find((l) => l.path === m[1]) : undefined;
-}
-/** The locale of a product URL for a market: the buyer's country when it is in the market, else the market's first. */
-export function marketLocale(r, market, country) {
-    const ls = localesOf(r).filter((l) => l.market === market);
-    return ls.find((l) => country && l.country === country.toUpperCase()) ?? ls[0];
-}
-/**
- * The language of a UCP catalog answer: context.language (primary subtag), else the first
- * Accept-Language the store has, else the language of the buyer's country's locale, else the base.
- */
-export function ucpLanguage(r, context, acceptLanguage) {
-    const has = languagesOf(r);
-    const primary = (tag) => tag.trim().split(/[-_;]/)[0].toLowerCase();
-    const asked = typeof context?.language === 'string' ? primary(context.language) : '';
-    if (has.has(asked))
-        return asked;
-    for (const part of (acceptLanguage ?? '').split(',')) {
-        const ll = primary(part);
-        if (ll && has.has(ll))
-            return ll;
-    }
-    const country = typeof context?.address_country === 'string' ? localeOfCountry(r, context.address_country) : undefined;
-    if (country && has.has(country.language))
-        return country.language;
-    return baseLanguage(r);
-}