@commercelayer/agent-cli 1.0.0-dev.5 → 1.0.0-dev.6

package/README.md

@@ -14,6 +14,7 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 - A plain noun has no code in the CLI. Its fields, filters and verbs come from the API's schema, and `c11r schema <noun>` returns that schema.
 - Flags are the schema's fields, in kebab or snake case: `--price-list` and `--price_list` are the same.
 - On `list`, `--<field> <value>` filters by equality and `--<field>.<op> <value>` by another operator: `--placed-at.gte 2026-11-01`, `--status.in placed,approved`. `--waiting` lists what needs a decision now.
+- A ref flag given `null`, or an empty value, takes the relationship off: `c11r customers update ada@example.com --customer-group null` sends `customer_group: null`.
 - A dotted flag sets part of an object: `--customer.email ada@example.com`. An `in` filter takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it (`--tax-calculator.in "UK VAT, manual"`), and a list that has one is sent as a JSON array. Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2`. `--data` takes the fields as one JSON object, or `@` and a file name.
 - Amounts are in major units: `--amount 12.50`.
 - A secret field the schema marks `secret_input` (provider credentials) has no flag of its own: `--credentials-file <file>` reads it, as JSON or `KEY=value` lines, from a plain file only its owner can read (mode 600). Without the file, a terminal asks for it without echo; with neither, the command stops with `secret_required`. It is refused as a flag value or in `--data`, and never printed.
@@ -124,6 +125,6 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 | `C11R_PROVISIONING_TOKEN` | A ready login token, used as is: for CI. Never a client secret. |
 | `C11R_AUTH_URL` | Commerce Layer's token endpoint, `https://auth.commercelayer.io/oauth/token` by default: for tests. |
 | `C11R_TEST` | `1` marks a sandbox as a test organization, like a name starting `zztest`. |
-| `C11R_SCHEMA_CACHE` | `0` turns off the 10 minute schema cache in `~/.cache/c11r`. |
+| `C11R_SCHEMA_CACHE` | `0` turns off the 10 minute schema cache in `~/.cache/c11r`. The cache records the `C11R-Schema` hash it was read under; an answer with another hash drops it, and a command the API refused on the old schema runs once more on the fresh one (without the header, after `confirmation_required`, `unknown_field` or `unknown_verb`). The second run asks what the fresh schema asks: it never adds `confirm=true` by itself. |
 | `C11R_RETRY_CAP_S` | The longest the CLI waits before one retry, 30 by default. |
 | `C11R_TIMEOUT_MS` | How long a request may take, 30000 by default (sandbox create waits longer). |

package/dist/argv.js

@@ -132,7 +132,11 @@ export function coerce(key, spec, raw) {
     }
     switch (spec.type) {
         case 'string':
+            return raw;
         case 'ref':
+            // In a body, null or "" takes the relationship off (customers update --customer-group null).
+            if (spec.to === 'body' && (raw === 'null' || raw.trim() === ''))
+                return null;
             return raw;
         case 'integer':
             if (!/^-?\d+$/.test(raw.trim()))

package/dist/engine.js

@@ -14,9 +14,34 @@ import { hasLogin, loginToken } from './login.js';
 import { resourceRequest } from './resources.js';
 import { describePlan, OUT_NOT_TRACKED, planSecret, removeRecordFiles, writeSecret } from './secrets.js';
 import { verbOf } from './schema.js';
-import { apiNouns, apiSchema } from './schemas.js';
+import { apiNouns, apiSchema, refreshSchemas, refusedBySchema } from './schemas.js';
 import { VERSION } from './version.js';
+/**
+ * One command. When it was read against a cached schema the API has since changed (a deploy), and
+ * the refusal is one that explains (refusedBySchema), it runs once more on fresh schemas. The API
+ * refused, so nothing happened; the second run asks again what the fresh schema asks, and never
+ * adds confirm=true on its own.
+ */
 export async function execute(argv, opts = {}) {
+    try {
+        return await executeOnce(argv, opts);
+    }
+    catch (e) {
+        if (!(e instanceof CliError) || !refusedBySchema(e.code) || !refusedBeforeEffect(e))
+            throw e;
+        refreshSchemas();
+        process.stderr.write(JSON.stringify({ retrying: { code: e.code, why: 'the schema changed on the API: read again' } }) + '\n');
+        return executeOnce(argv, opts);
+    }
+}
+/** A refusal the API answered (4xx), or a flag or verb the cached schema did not know: nothing was done. */
+function refusedBeforeEffect(e) {
+    const status = e.body.details?.status;
+    if (typeof status === 'number')
+        return status >= 400 && status < 500;
+    return e.code === 'unknown_field' || e.code === 'unknown_verb';
+}
+async function executeOnce(argv, opts) {
     const cmd = parseCommand(argv);
     const builtins = opts.builtins ?? {};
     if (cmd.globals.version && !cmd.noun)

package/dist/help.js

@@ -29,7 +29,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 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 given null, or an empty value, takes the relationship off (--customer-group 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.',
         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.',
@@ -67,6 +67,7 @@ function flagHelp(key, f) {
         ...(f.required || (f.input?.kind === 'secret' && f.input.required) ? { required: true } : {}),
         ...(f.input ? { reads: f.input.kind === 'secret' ? `${f.input.target}, a secret: never a flag value, never printed` : `${f.input.target}, a JSON document` } : {}),
         ...(f.values ? { values: f.values } : {}),
+        ...(f.type === 'ref' && f.to === 'body' ? { clear: 'null, or an empty value, takes it off' } : {}),
         ...(f.filter ? { filter: f.filter.op } : {}),
         ...(f.description ? { description: f.description } : {}),
     };

package/dist/http.js

@@ -33,6 +33,13 @@ export function urlOf(req, ctx) {
     const qs = q.toString();
     return `${apiUrl()}${req.path}${qs ? `?${qs}` : ''}`;
 }
+/** The header with the hash of the schemas the API serves: it changes with a deploy that changes them. */
+export const SCHEMA_HEADER = 'c11r-schema';
+let schemaWatcher = null;
+/** Called with the header's value on every answer that has it (the schema cache listens). */
+export function watchSchemaHeader(fn) {
+    schemaWatcher = fn;
+}
 /** Sends the request: the envelope, or the API's error as a CliError. */
 export async function request(req, ctx) {
     for (let attempt = 1;; attempt++) {
@@ -76,6 +83,9 @@ async function once(req, ctx) {
             next_step: req.method === 'GET' ? { action: 'retry_later' } : { action: 'none' },
         });
     }
+    const version = res.headers.get(SCHEMA_HEADER);
+    if (version && schemaWatcher)
+        schemaWatcher(version);
     const text = await res.text();
     let data;
     try {

package/dist/schemas.js

@@ -2,28 +2,91 @@
 // one (contract section 5), cached on disk for a few minutes so a command costs one request, not
 // two. Schemas are the same at every state, so no token is sent. C11R_SCHEMA_CACHE=0 turns the
 // cache off.
+//
+// A deploy can change a schema inside those minutes. Every answer carries C11R-Schema, the hash of
+// the schemas served: an entry records the one it was loaded with, and an answer with another
+// drops the cache. The engine then runs the command once more on fresh schemas when the API
+// refused it (refusedBySchema). Without the header, a refusal that a stale schema explains
+// (confirmation_required, unknown_field, unknown_verb) does the same.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { CliError, closest, fail, fixWith } from './errors.js';
-import { apiUrl, request } from './http.js';
+import { apiUrl, request, watchSchemaHeader } from './http.js';
 import { parseSchema } from './schema.js';
 import { VERSION } from './version.js';
 const TTL_MS = 10 * 60_000;
-function cacheFile(key) {
+function cacheDir() {
     if (process.env.C11R_SCHEMA_CACHE === '0')
         return null;
     const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
     const host = crypto.createHash('sha256').update(apiUrl()).digest('hex').slice(0, 12);
-    return path.join(base, 'c11r', `schema-${VERSION}-${host}`, `${key}.json`);
+    return path.join(base, 'c11r', `schema-${VERSION}-${host}`);
+}
+/** This process: the header last seen, the versions of the cache entries used, and whether to skip the cache. */
+const seen = { header: null, used: new Set(), fromCache: false, stale: false, fresh: false, written: null };
+/** The hash the cache on disk was written under, in its own file: any answer can check it, whatever the command read. */
+const HASH_FILE = '_hash';
+watchSchemaHeader((version) => {
+    seen.header = version;
+    // Schemas this command read from the cache, under another hash: the refusal may be theirs.
+    if (seen.fromCache && [...seen.used].some((v) => v !== version))
+        seen.stale = true;
+    // The cache on disk, under another hash (or none recorded): gone, whatever this command read.
+    const dir = cacheDir();
+    if (!dir || seen.written === version)
+        return;
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const hash = names.includes(HASH_FILE) ? fs.readFileSync(path.join(dir, HASH_FILE), 'utf8').trim() : null;
+    if (hash !== version && names.some((n) => n.endsWith('.json')))
+        dropSchemaCache();
+});
+/** Every cached schema of this API, gone: the next command loads them again. */
+export function dropSchemaCache() {
+    const dir = cacheDir();
+    if (dir)
+        fs.rmSync(dir, { recursive: true, force: true });
+}
+/**
+ * Whether a refusal may come from a schema older than the API's: one was served from the cache,
+ * and the API's header says the schemas changed, or, with no header, the refusal is one a stale
+ * schema explains. The caller then refreshes (refreshSchemas) and runs the command once more.
+ */
+export function refusedBySchema(code) {
+    if (!seen.fromCache || seen.fresh)
+        return false;
+    if (seen.stale)
+        return true;
+    return seen.header === null && STALE_CODES.has(code);
+}
+const STALE_CODES = new Set(['confirmation_required', 'unknown_field', 'unknown_verb']);
+/** From now on, in this process, schemas come from the API, and the cache is rewritten. */
+export function refreshSchemas() {
+    dropSchemaCache();
+    seen.fresh = true;
+    seen.fromCache = false;
+    seen.used.clear();
 }
 async function cached(key, load) {
-    const file = cacheFile(key);
-    if (file) {
+    const dir = cacheDir();
+    const file = dir ? path.join(dir, `${key}.json`) : null;
+    if (file && !seen.fresh) {
         try {
-            if (Date.now() - fs.statSync(file).mtimeMs < TTL_MS)
-                return JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (Date.now() - fs.statSync(file).mtimeMs < TTL_MS) {
+                const entry = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (entry && typeof entry === 'object' && 'value' in entry) {
+                    seen.fromCache = true;
+                    seen.used.add(entry.version ?? null);
+                    return entry.value;
+                }
+            }
         }
         catch {
             // Not cached, or unreadable: load it.
@@ -33,7 +96,18 @@ async function cached(key, load) {
     if (file) {
         try {
             fs.mkdirSync(path.dirname(file), { recursive: true });
-            fs.writeFileSync(file, JSON.stringify(value));
+            // Written under another hash than the files there: those go first, so the cache is one hash.
+            if (seen.header && seen.written !== seen.header) {
+                const hashFile = path.join(path.dirname(file), HASH_FILE);
+                const hash = fs.existsSync(hashFile) ? fs.readFileSync(hashFile, 'utf8').trim() : null;
+                if (hash !== seen.header) {
+                    dropSchemaCache();
+                    fs.mkdirSync(path.dirname(file), { recursive: true });
+                    fs.writeFileSync(hashFile, seen.header);
+                }
+                seen.written = seen.header;
+            }
+            fs.writeFileSync(file, JSON.stringify({ version: seen.header, value }));
         }
         catch {
             // A read-only home is fine: no cache.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "1.0.0-dev.5",
+  "version": "1.0.0-dev.6",
   "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": [