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

package/README.md

@@ -14,7 +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 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.
@@ -35,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
 

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,13 +131,12 @@ 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':
-            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()))
@@ -214,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/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 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.',
+        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,7 +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 } : {}),
-        ...(f.type === 'ref' && f.to === 'body' ? { clear: 'null, or an empty value, takes it off' } : {}),
+        ...(clearable(f) ? { clear: 'null, or an empty value, takes it off' } : {}),
         ...(f.filter ? { filter: f.filter.op } : {}),
         ...(f.description ? { description: f.description } : {}),
     };

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/package.json

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