@commercelayer/agent-cli 0.5.0 → 0.5.1

package/README.md

@@ -10,6 +10,7 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 - **The website comes with the store.** Every store has a hosted theme at its preview URL, set by a few `theme:` settings and the product data: `apply` is all it takes. A custom storefront (your own web app) is opt-in: `storefront init`, `publish` and `check`.
 - **JSON only.** Every command prints one JSON object. A failure exits 1 with `{ "error": { "code", "message", "hint" } }`; the hint is the fix.
 - **Safe to re-run.** Every command is idempotent; a failed step can be fixed and run again.
+- **Always current.** Run it as `npx -y @commercelayer/agent-cli@latest`, even where a `c11r` binary is installed; the note `init` writes in `AGENTS.md` and `CLAUDE.md` says so. The CLI sends `User-Agent: c11r/<version> (node/<major>)`, and an outdated one gets a `cli_outdated` entry in `warnings`, with `current`, `latest` and a `hint`.
 - **No secrets in git.** `init` writes the sandbox token to `.commercelayer/credentials` (`C11R_ORG`, `C11R_TOKEN`) and gitignores it. The keys of a catalog source go in the same file.
 ## Commands
 | Command | Does |
@@ -40,9 +41,9 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | `ucp checkout show <id>` · `cancel <id>` · `complete <id> [--decline]` | Read, cancel, or pay a checkout with the sandbox handler (after the human said yes): `order` has `label` and `permalink_url`. |
 | `ucp order <id>` · `ucp ask "<question>"` | Read an order the CLI placed; ask the store a question. Every `ucp` buying command takes `--store <host>` to buy from any store that speaks UCP. |
 | `ucp check` | Walk every UCP capability the store advertises and report what passes. Places and pays one real test order on the way (the output says which). Exits 1 on a failed check. |
-| `status` | The sandbox, the sales channel client id, the published storefront, what is applied, the last import job (`apply`), the pending changes (exactly what `plan` lists; a store that does not load is pending too, with the error), orders, the UCP profile URL. |
+| `status` | The sandbox, the sales channel client id, the published storefront, what is applied, the last import job (`apply`), the pending changes (exactly what `plan` lists; a store that does not load is pending too, with the error), orders, the store's semantic search index (`search`: model, status, vectors, embedded, updated_at, error; null before its first run), the UCP profile URL. |
 | `claim` | Start the device flow that keeps the sandbox: a URL and a code for the human. |
-| `help [<command>]` | Describe the commands. `--version` prints the version. |
+| `help [<command>]` | Describe the commands. `--version` prints the version and `latest_hint`, how to always run the newest. |
 ## store.yml
 `init` writes a commented template. A filled-in store looks like this:
 ```yaml

package/dist/api/client.js

@@ -1,5 +1,6 @@
 // The client for the management API at api.commercelayer.ai.
-import { CliError, fail } from '../output.js';
+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(/\/$/, '');
@@ -20,6 +21,19 @@ export function createApi(auth) {
         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;

package/dist/api/stub/index.js

@@ -16,7 +16,7 @@ export function handle(req) {
         url = new URL(`https://${prefixed[1]}${prefixed[2] ?? '/'}${url.search}`);
     const org = orgOfHost(url.hostname);
     if (org === null)
-        return handleManagement({ ...req, url });
+        return outdated(req, handleManagement({ ...req, url }));
     const db = readDb();
     const store = db[org];
     if (!store)
@@ -25,3 +25,28 @@ export function handle(req) {
     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);
+    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/transport.js

@@ -5,6 +5,7 @@
 // stands in for the whole platform.
 import { fail } from '../output.js';
 import { handle } from './stub/index.js';
+import { USER_AGENT } from '../version.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) {
@@ -12,6 +13,8 @@ export async function send(method, url, headers = {}, body) {
     const lower = {};
     for (const [k, v] of Object.entries(headers))
         lower[k.toLowerCase()] = v;
+    // On every request, to the API and to stores: the API tells an outdated CLI so (cli_outdated).
+    lower['user-agent'] ??= USER_AGENT;
     if (body !== undefined && !lower['content-type'])
         lower['content-type'] = 'application/json';
     if (base === 'stub')

package/dist/bin.js

@@ -4,6 +4,7 @@
 // Output is always JSON; exit code 1 on an error or a failed check.
 import * as cmd from './commands.js';
 import { CliError, print } from './output.js';
+import { LATEST_HINT, NPX } from './version.js';
 const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code', '--file', '--store', '--item', '--email', '--first-name', '--last-name', '--phone', '--street', '--city', '--postal-code', '--region', '--shipping', '--category', '--min-price', '--max-price', '--status', '--payment', '--fulfillment', '--limit', '--archived', '--amount', '--carrier', '--tracking', '--tracking-url']);
 const argv = process.argv.slice(2);
 const flags = new Set();
@@ -36,7 +37,7 @@ for (let i = 0; i < argv.length; i++) {
 const [name, sub] = args;
 async function run() {
     if (flags.has('--version') || name === 'version')
-        return { version: cmd.VERSION };
+        return { version: cmd.VERSION, latest_hint: LATEST_HINT };
     switch (name) {
         case undefined:
         case 'help':
@@ -151,7 +152,7 @@ run()
     }
     else {
         const message = e instanceof Error ? e.message : String(e);
-        print({ error: { code: 'internal', message, hint: 'This is a bug in the CLI. Tell the human, with this output, and try again with npx -y @commercelayer/agent-cli@latest in case it is already fixed.' } });
+        print({ error: { code: 'internal', message, hint: `This is a bug in the CLI. Tell the human, with this output, and try again with ${NPX} in case it is already fixed.` } });
     }
     process.exit(1);
 });

package/dist/commands.js

@@ -1,7 +1,6 @@
 // One function per command. Each returns the object the CLI prints, or throws a
 // CliError. Every command is safe to re-run.
 import fs from 'node:fs';
-import { createRequire } from 'node:module';
 import path from 'node:path';
 import { createApi } from './api/client.js';
 import { ignoreCredentials, paths, readCredentials, requireCredentials, writeAgentNotes, writeCredentials } from './files.js';
@@ -19,8 +18,8 @@ import { check } from './ucp/check.js';
 import { discover } from './ucp/client.js';
 import * as shop from './ucp/shop.js';
 import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
-/** The package version, read from package.json so a release bumps it in one place. */
-export const VERSION = createRequire(import.meta.url)('../package.json').version;
+import { LATEST_HINT, VERSION } from './version.js';
+export { VERSION } from './version.js';
 export const HELP = {
     init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials, and a section in AGENTS.md and CLAUDE.md (created, or appended once) that points later agents in this repo to the skills: commit them. Reuses the store if store.yml already exists.',
     plan: 'Show what apply would create, update or delete: markets, products, images, and the store\'s name, language, policies and theme; missing_images lists references with no file in .commercelayer/img/ (apply refuses them), unused_images files nothing references, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku). Products may carry other languages: name, description and category as { <ll>: text } maps (the base language, store.yml language:, default en, among them), or name_<ll>, description_<ll>, category_<ll> CSV columns; at most 6 languages. warnings lists a language no country of the store speaks.',
@@ -70,7 +69,7 @@ export const HELP = {
     'ucp checkout complete': "Buy for the human, step 4, only after the human said yes to the total: pay the checkout. c11r ucp checkout complete <id> [--decline] [--store <host>]. Pays with the ai.commercelayer.sandbox test handler (no money moves): only stores that advertise it can be paid; --decline uses the declined test card. Returns the checkout with status completed and order: { id, label, permalink_url }, plus payment_handler. Tell the human the order label and give them permalink_url. A store without that handler (any store taking real payments) answers payment_handler_unsupported: give the human continue_url to pay there. A declined payment leaves status ready_for_complete with a payment_failed message.",
     'ucp order': 'Read an order this CLI placed: c11r ucp order <id> [--store <host>]. Returns { id, label, permalink_url, store, checkout_id, currency, line_items: [{ item_id, title, quantity, status, total }], fulfillment: [{ method, destination, description }], events, totals, signature }.',
     'ucp ask': 'Ask a store a question in plain language over UCP (shipping, returns, what it sells): c11r ucp ask "<question>" [--store <host>]. Returns { store, question, answer, links, messages, signature }. The answer is the store\'s: quote it, do not embellish it. Ask only answers; buy with ucp checkout.',
-    status: 'Show the sandbox, what is applied, and whether the store files have changes not yet applied (the same changes plan lists).',
+    status: 'Show the sandbox, what is applied, and whether the store files have changes not yet applied (the same changes plan lists). search is the store\'s semantic search index: { model, status: indexing|ready|failed|too_large, vectors, embedded, updated_at, error }, or null before it first runs; until it is ready the store\'s search matches words only.',
     claim: 'Start keeping this sandbox store: returns a URL and a code for the human to approve in the browser.',
     help: 'Describe the commands. `c11r help <command>` for one command, `c11r help <group>` (catalog, fulfillment, links, orders, promotions, storefront, ucp) for a group.',
 };
@@ -87,7 +86,7 @@ export function help(name) {
         const showsFormat = name === 'apply' || name === 'plan';
         return { command: name, description: HELP[name], store_format: showsFormat ? template('<name>') : undefined };
     }
-    return { version: VERSION, commands: HELP, note: 'Every command prints JSON. The store format is documented in the comments of .commercelayer/store.yml; large catalogs go in .commercelayer/products/ as .yml or .csv files.' };
+    return { version: VERSION, latest_hint: LATEST_HINT, commands: HELP, note: 'Every command prints JSON. The store format is documented in the comments of .commercelayer/store.yml; large catalogs go in .commercelayer/products/ as .yml or .csv files.' };
 }
 export async function init(values) {
     const existing = readCredentials();
@@ -462,6 +461,8 @@ export async function status() {
         markets: s.applied ? Object.keys(s.applied.markets) : [],
         products: s.applied ? Object.keys(s.applied.products).length : 0,
         orders: s.orders.map((o) => ({ id: o.id, label: o.label })),
+        // Semantic search: until it is ready, the store's search matches words only.
+        search: s.search ? { model: s.search.model, status: s.search.status, vectors: s.search.vectors, embedded: s.search.embedded, updated_at: s.search.updated_at, error: s.search.error } : null,
         ucp_profile: `${s.preview_url}/.well-known/ucp`,
         next: s.apply?.status === 'in_progress' ? 'An apply is running: run `c11r status` again to follow it, or `c11r apply` to wait for it.' : storeError ? 'Fix the store files (see store_error), then run `c11r plan`.' : pending.length ? 'Run `c11r plan` to see the changes, then `c11r apply`.' : undefined,
     };

package/dist/files.js

@@ -63,18 +63,30 @@ export function ignoreCredentials() {
 }
 /** The note that sends a future agent in this repo to the skills. No skill names: it never goes stale. */
 const AGENT_NOTE_HEADING = '# Store on Commerce Layer';
+const SKILLS = 'Before any task about the store (products, prices, markets, storefront, orders, promotions, agents), fetch `https://commercelayer.ai/skills.md` with `curl -fsSL` and load the skill for the task from `skills/<name>.md`; follow it rather than calling the Commerce Layer API directly. If `.commercelayer/store.yml` is missing, start from `https://commercelayer.ai/start.md`.';
 export const AGENT_NOTE = `${AGENT_NOTE_HEADING}
-This store is managed with \`c11r\` (\`npx @commercelayer/agent-cli\`), configured in \`.commercelayer/store.yml\`. Before any task about the store (products, prices, markets, storefront, orders, promotions, agents), fetch \`https://commercelayer.ai/skills.md\` with \`curl -fsSL\` and load the skill for the task from \`skills/<name>.md\`; follow it rather than calling the Commerce Layer API directly. If \`.commercelayer/store.yml\` is missing, start from \`https://commercelayer.ai/start.md\`.
+This store is managed with \`c11r\`, run as \`npx -y @commercelayer/agent-cli@latest\`, configured in \`.commercelayer/store.yml\`. Always use that form, even if a \`c11r\` binary is installed: it stays on the current version. ${SKILLS}
+`;
+/** The note CLIs before 0.5.1 wrote: replaced by the current one when a file has it word for word. */
+const OLD_AGENT_NOTE = `${AGENT_NOTE_HEADING}
+This store is managed with \`c11r\` (\`npx @commercelayer/agent-cli\`), configured in \`.commercelayer/store.yml\`. ${SKILLS}
 `;
 /**
  * Write the note to AGENTS.md and CLAUDE.md (Claude Code reads that name) in the repo root:
  * created when absent, appended as a section when the file has other content, left alone
- * when the section is already there. Returns the files written.
+ * when the section is already there (replaced when it is an older CLI's, word for word).
+ * Returns the files written.
  */
 export function writeAgentNotes() {
     const written = [];
     for (const file of ['AGENTS.md', 'CLAUDE.md']) {
         const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+        // A note an older CLI wrote, untouched since: bring it up to date. An edited one stays as it is.
+        if (before.includes(OLD_AGENT_NOTE)) {
+            fs.writeFileSync(file, before.replace(OLD_AGENT_NOTE, AGENT_NOTE));
+            written.push(file);
+            continue;
+        }
         if (before.split('\n').some((line) => line.trim() === AGENT_NOTE_HEADING))
             continue;
         fs.writeFileSync(file, before.trim() ? `${before.replace(/\s*$/, '')}\n\n${AGENT_NOTE}` : AGENT_NOTE);

package/dist/output.js

@@ -2,6 +2,7 @@
 // A failure is { error: { code, message, hint } } with exit code 1. The hint is
 // the fix: an agent reads it and acts on it before trying anything else.
 // A command that waits (apply) writes progress to stderr, one JSON object per line.
+// Warnings the API sends about the CLI itself (cli_outdated) go into whatever is printed.
 export class CliError extends Error {
     code;
     hint;
@@ -17,6 +18,18 @@ export function fail(code, message, hint) {
 export function progress(data) {
     process.stderr.write(JSON.stringify(data) + '\n');
 }
+const notices = [];
+/** Keep a warning to print with the result, once per code. */
+export function notice(n) {
+    if (!notices.some((x) => x.code === n.code))
+        notices.push(n);
+}
 export function print(data) {
-    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    let out = data;
+    if (notices.length && data && typeof data === 'object' && !Array.isArray(data)) {
+        const own = data.warnings;
+        // A command's own warnings are strings or objects; the API's are added after them.
+        out = { ...data, warnings: [...(Array.isArray(own) ? own : own === undefined ? [] : [own]), ...notices] };
+    }
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
 }

package/dist/version.js

@@ -0,0 +1,9 @@
+// The CLI's version and how it names itself on the wire.
+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.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "c11r: the Commerce Layer CLI for coding agents. Builds a sandbox store that people and shopping agents can buy from.",
   "homepage": "https://commercelayer.ai",
   "keywords": [