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

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, or one the schema marks `nullable`, given `null` or an empty value sends `null` and takes it off: `c11r customers update ada@example.com --customer-group null` sends `customer_group: null`, `c11r orders update 1001 --coupon-code null` sends `coupon_code: null`. A ref the schema marks `nullable: false`, and any other field, sends the text.
 - 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.
@@ -34,7 +35,7 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 | `c11r auth login [--client-id] [--secret-file] [--keep-file]` | The human's own Commerce Layer login, from their Provisioning API application. See below. |
 | `c11r auth logout`, `auth switch <slug> [--global]` | Forgetting the login; the organization commands act on. |
 
-A loop runs a skill a Manage noun's schema names in `loop.skill` (`manage-orders`, `manage-payments`, `playbook-mail-to-order` for carts); create and update refuse any other skill, and any verb that loop does not list, with the allowed values. A loop policy allows verbs: a bare verb is the skill's own noun (`approve`), `<noun>.<verb>` another Manage noun's verb on the same item (`payments.capture`). Verbs that delete or return money are never open to a policy.
+A loop runs a skill a Manage noun's schema names in `loop.skill` (`manage-orders`, `manage-payments`, `manage-stock`, ...); create and update refuse any other skill, and any verb that loop does not list, with the allowed values. A loop policy allows verbs: a bare verb is the skill's own noun (`approve`), `<noun>.<verb>` another Manage noun's verb on the same item (`payments.capture`). Verbs that delete or return money are never open to a policy.
 
 ## Login, organization tokens and secrets
 
@@ -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

@@ -3,6 +3,7 @@
 // verb's flags, which say whether a flag takes a value, what type it is and where it goes.
 import fs from 'node:fs';
 import { closest, fail, fixWith } from './errors.js';
+import { clearable } from './schema.js';
 const BOOLEAN_GLOBALS = {
     '--json': 'json',
     '--dry-run': 'dryRun',
@@ -130,6 +131,9 @@ export function coerce(key, spec, raw) {
     if ((spec.type === 'enum' || (spec.type === 'array' && spec.items === 'enum')) && !spec.values?.length) {
         fail('invalid_response', `The API's schema gives ${toFlag(key)} as an enum with no values, so c11r cannot check ${JSON.stringify(raw)}. It was not sent.`, { path: key, next_step: { action: 'none' } });
     }
+    // null, or an empty value, clears what the schema lets null clear (--customer-group null, --coupon-code "").
+    if (clearable(spec) && (raw === 'null' || raw.trim() === ''))
+        return null;
     switch (spec.type) {
         case 'string':
         case 'ref':
@@ -210,7 +214,7 @@ function json(raw, invalid) {
 }
 /**
  * sku=A,quantity=2 as { sku: 'A', quantity: 2 }, each part typed by the schema's properties.
- * A part the schema does not type stays text: a postal code or a phone is never made a number.
+ * A part the schema does not type stays text: a zip code or a phone is never made a number.
  */
 function pairs(key, raw, props, invalid) {
     const out = {};

package/dist/builtins/loops.js

@@ -5,8 +5,7 @@
 //
 // A policy allows verbs: a bare verb is the skill's own noun (approve), <noun>.<verb> another
 // Manage noun's verb on the same item (payments.capture). The skill must be one a Manage noun's
-// schema names in loop.skill (a noun's own skill is not always its loop's: carts loops run
-// playbook-mail-to-order), and each verb in that loop.verbs; the API checks again on every pass.
+// schema names in loop.skill, and each verb in that loop.verbs; the API checks again on every pass.
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
@@ -18,7 +17,7 @@ import { apiNouns, apiSchema } from '../schemas.js';
 const NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
 const EVERY = /^[1-9]\d*(m|h|d)$/;
 const policyFlags = (required) => [
-    { name: 'skill', type: 'string', required, description: 'The skill or playbook the loop runs, as in manage-orders or playbook-mail-to-order: one a noun\'s schema names in loop.skill.' },
+    { name: 'skill', type: 'string', required, description: 'The skill the loop runs, as in manage-orders: one a noun\'s schema names in loop.skill.' },
     { name: 'every', type: 'string', required, description: 'How often a pass should run, as in 15m, 2h or 1d. The scheduler reads it; the CLI does not wait.' },
     { name: 'allow', type: 'array', description: 'A verb the policy allows, repeated: approve, payments.capture. Only verbs the noun\'s schema lists in loop.verbs. Without it the loop only reports what is waiting.' },
     { name: 'max_total', type: 'array', description: 'The largest order total acted on, in major units: 500 for every currency, or EUR=500, repeated per currency. Above it, the item waits for the human.' },

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

@@ -3,6 +3,7 @@
 // reads it and offers to do the work.
 import { toFlag } from './argv.js';
 import { EXIT } from './errors.js';
+import { clearable } from './schema.js';
 export const USAGE = 'c11r <noun> <verb> [id] [--field value ...]';
 export const GLOBAL_FLAG_HELP = {
     '--json': 'Output as JSON. The default, and the only format: one object on stdout, { data, state, warnings, next } or { error, state }.',
@@ -29,7 +30,7 @@ export function indexHelp(builtins, api) {
         description: 'c11r is the Commerce Layer CLI for coding agents. Every answer, errors included, is one JSON object on stdout.',
         nouns: [...builtins, ...(api ?? [])].sort((a, b) => (a.noun < b.noun ? -1 : 1)),
         standard_verbs: 'list, get, create, update, delete. Nouns with a state machine add their own verbs.',
-        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01). in takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it, and a list that has one is sent as a JSON array. A dotted flag sets part of an object (--customer.email). Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
+        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01). in takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it, and a list that has one is sent as a JSON array. A ref flag, or a flag the schema marks nullable, given null or an empty value sends null and takes it off (--customer-group null, --coupon-code null). A dotted flag sets part of an object (--customer.email). Any other array takes 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 +68,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 } : {}),
+        ...(clearable(f) ? { 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/schema.js

@@ -1,6 +1,6 @@
 // The schema of a noun, as the contract's schema document has it (section 5.1), and what the
 // engine makes of it: for every verb, the flags it takes and where each one goes (body, query or
-// filter). A plain noun (markets, orders, carts, about 60 of them) has no code in the CLI: its
+// filter). A plain noun (markets, orders, payments, about 60 of them) has no code in the CLI: its
 // schema is read from GET /v1/schema/<noun>. Built-in nouns (sandbox, loops, report) write theirs
 // in the same document format, so one reader serves both.
 import { closest, fail, fixWith } from './errors.js';
@@ -148,6 +148,7 @@ function flag(f, to, required) {
         ...(f.items ? { items: f.items } : {}),
         ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, { type: p.type, ...(p.values ? { values: p.values } : {}) }])) } : {}),
         ...(f.noun ? { noun: f.noun } : {}),
+        ...(f.nullable !== undefined ? { nullable: f.nullable } : {}),
         ...(required ? { required: true } : {}),
         ...(f.description ? { description: f.description } : {}),
     };
@@ -181,3 +182,7 @@ export function verbOf(schema, verb) {
     }
     return v;
 }
+/** A body flag that null clears: a field marked nullable, or a ref unless marked nullable: false. */
+export function clearable(f) {
+    return f.to === 'body' && (f.nullable === true || (f.type === 'ref' && f.nullable !== false));
+}

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.7",
   "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": [