@commercelayer/agent-cli 1.0.0-dev.1 → 1.0.0-dev.3

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 dotted flag sets part of an object: `--customer.email ada@example.com`. An 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.
+- 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.
 - A document field the schema marks `file_input` (price rules, rule filters) also reads from a JSON file: `--file <file>`, or `--<field>-file` when a verb has more than one.
@@ -50,7 +50,7 @@ Never from a flag or the environment. c11r exchanges the pair for a two hour tok
 
 `organizations create` and `organizations connect <slug>` answer an organization token once: it is stored like a sandbox token. `connect --revoke-others` also ends every other token of that organization, and asks for confirmation. With a login and no organization token for the organization named, an organization noun stops with `no_credentials` and the next step `c11r organizations connect <slug>`. `members` and `roles` with an organization token and no login are sent with that token, and the API says what is needed: a claim for a sandbox, a login for a claimed organization. `organizations` with no login stops here with `login_required`.
 
-`credentials create` and `credentials token` answer a secret once. c11r writes it to a file with mode 600 and prints the file, the format and a hint, never the value: by default `~/.config/c11r/secrets/<org>/<name>.env` (`<id>-token.env` for a token), or `--out <path>`, as `KEY=value` lines or with `--format json` one JSON object. The file is checked before the request is sent; one there already is replaced only with `--yes`. A file inside a git repository that git does not ignore gets the warning `secret_not_ignored`. With `--dry-run` nothing is written and `secret_file` says where it would go. Each file records the record it belongs to. A `delete` of a record whose noun answers secrets (`credentials`, `webhooks`) removes the files c11r wrote for it in `~/.config/c11r/secrets/<org>/` (a credential's secret and tokens, a webhook's shared secret), found by the id, name or code given, and lists them in `removed_files`; `sandbox destroy` removes the whole folder of that organization and names it in `forgotten.secrets`. A file written with `--out` is not tracked and stays: the warning `out_files_not_tracked` says so, when a secret of that organization was written with `--out` on this machine, or when a delete found nothing to remove. A token file carries `CL_BASE_ENDPOINT` beside the token. `sales-calls book` answers a cancel token once: it is kept in `credentials.json` and `sales-calls cancel <booking>` sends it.
+`credentials create` and `credentials token` answer a secret once. c11r writes it to a file with mode 600 and prints the file, the format and a hint, never the value: by default `~/.config/c11r/secrets/<org>/<name>.env` (`<id>-token.env` for a token), or `--out <path>`, as `KEY=value` lines or with `--format json` one JSON object. The file is checked before the request is sent; one there already is replaced only with `--yes`. A file inside a git repository that git does not ignore gets the warning `secret_not_ignored`. With `--dry-run` nothing is written and `secret_file` says where it would go. Each file records the record it belongs to. A `delete` of a record whose noun answers secrets (`credentials`, `webhooks`) removes the files c11r wrote for it in `~/.config/c11r/secrets/<org>/` (a credential's secret and tokens, a webhook's shared secret), found by the id, name or code given, and lists them in `removed_files`; `sandbox destroy` removes the whole folder of that organization and names it in `forgotten.secrets`. A file written with `--out` is not tracked and stays: the warning `out_files_not_tracked` says so on the delete of the record whose secret went to `--out` on this machine, and on `sandbox destroy` of an organization that had one. Any other delete has no such warning. A token file carries `CL_BASE_ENDPOINT` beside the token. `sales-calls book` answers a cancel token once: it is kept in `credentials.json` and `sales-calls cancel <booking>` sends it.
 
 ## Global flags
 

package/dist/argv.js

@@ -104,7 +104,7 @@ export function parseFields(noun, verb, rest) {
             for (const k of sub.slice(0, -1))
                 target = (target[k] ??= {});
             const part = sub.join('.');
-            target[sub[sub.length - 1]] = part in (spec.properties ?? {}) ? coerce(key, { type: spec.properties[part] }, raw) : raw;
+            target[sub[sub.length - 1]] = part in (spec.properties ?? {}) ? coerce(key, spec.properties[part], raw) : raw;
             continue;
         }
         const value = coerce(key, spec, raw);
@@ -122,6 +122,10 @@ function secretAsValue(cmd, key) {
 /** A value as its flag's type says, or invalid_value with the reason. */
 export function coerce(key, spec, raw) {
     const invalid = (why) => fail('invalid_value', `${toFlag(key)} ${JSON.stringify(raw)} ${why}.`, { path: key, ...(spec.values ? { details: { values: spec.values } } : {}) });
+    // The schema's fault, not the command's: said so before any value is checked against nothing.
+    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' } });
+    }
     switch (spec.type) {
         case 'string':
         case 'ref':
@@ -156,7 +160,7 @@ export function coerce(key, spec, raw) {
             const v = raw.trim().startsWith('{') ? json(raw, invalid) : pairs(key, raw, spec.properties ?? {}, invalid);
             if (!v || typeof v !== 'object' || Array.isArray(v))
                 invalid('is not a JSON object');
-            return v;
+            return enumParts(key, spec.properties, v);
         }
         case 'array': {
             const item = spec.items ?? 'string';
@@ -164,11 +168,15 @@ export function coerce(key, spec, raw) {
                 const list = json(raw, invalid);
                 if (!Array.isArray(list))
                     invalid('is not a list');
-                return list.map((x) => (typeof x === 'string' && item !== 'string' ? coerce(key, { type: item, values: spec.values }, x) : x));
+                return list.map((x) => (typeof x === 'string' && item !== 'string' ? coerce(key, { type: item, values: spec.values }, x) : item === 'object' ? enumParts(key, spec.properties, x) : x));
             }
             // One object per flag (--items sku=A,quantity=2, repeated), or scalars separated by commas.
             if (item === 'object')
                 return [coerce(key, { type: 'object', properties: spec.properties }, raw)];
+            // An in filter on names or text takes the value whole: a name may have a comma ("UK VAT, manual").
+            // Several are the flag repeated, or a JSON array. Enums, numbers and dates still split on commas.
+            if (spec.filter?.op === 'in' && (item === 'string' || item === 'ref'))
+                return [raw];
             return raw
                 .split(',')
                 .map((s) => s.trim())
@@ -177,6 +185,17 @@ export function coerce(key, spec, raw) {
         }
     }
 }
+/** In JSON too, an enum part of an object is one of its values. */
+function enumParts(key, props, v) {
+    if (!v || typeof v !== 'object')
+        return v;
+    for (const [name, p] of Object.entries(props ?? {})) {
+        const part = v[name];
+        if (p.type === 'enum' && typeof part === 'string')
+            coerce(`${key}.${name}`, p, part);
+    }
+    return v;
+}
 function json(raw, invalid) {
     try {
         return JSON.parse(raw);
@@ -197,7 +216,7 @@ function pairs(key, raw, props, invalid) {
             invalid('is not JSON nor key=value pairs separated by commas');
         const name = part.slice(0, eq).trim();
         const value = part.slice(eq + 1).trim();
-        out[name] = props[name] ? coerce(`${key}.${name}`, { type: props[name] }, value) : value;
+        out[name] = props[name] ? coerce(`${key}.${name}`, props[name], value) : value;
     }
     return out;
 }

package/dist/builtins/sandbox.js

@@ -4,7 +4,7 @@
 // reset moves both to the new organization; destroy forgets them. The token is printed never,
 // not even by create: only its hint.
 import crypto from 'node:crypto';
-import { credentialsFile, defaultOrg, markOutWritten, outWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
+import { credentialsFile, defaultOrg, forgetOutWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
 import { CliError, fail } from '../errors.js';
 import { apiUrl, envelope, request } from '../http.js';
 import { parseSchema } from '../schema.js';
@@ -124,8 +124,7 @@ async function destroy(run) {
         // here. The sandbox is gone either way, so this machine forgets it too.
         if (!(e instanceof CliError && e.code === 'unauthorized') || run.globals.dryRun || !run.org.org)
             throw e;
-        const out = outWritten(run.org.org);
-        markOutWritten(run.org.org, false);
+        const out = forgetOutWritten(run.org.org);
         forgetOrg(run.org.org);
         const link = removeLink(run.org.org);
         const secrets = removeOrgSecrets(run.org.org);
@@ -136,8 +135,7 @@ async function destroy(run) {
     const org = r.data?.org ?? run.org.org;
     if (!org)
         return r;
-    const out = outWritten(org);
-    markOutWritten(org, false);
+    const out = forgetOutWritten(org);
     forgetOrg(org);
     const link = removeLink(org);
     const secrets = removeOrgSecrets(org);

package/dist/config.js

@@ -110,20 +110,37 @@ export function setDefaultOrg(org) {
         delete c.default_org;
     writeCredentials(c);
 }
-export function outWritten(org) {
-    return Boolean(readCredentials().out_written?.[org]);
+/** A record's secret went to an --out file: remembered so its delete can say that file stays. */
+export function markOutWritten(org, record) {
+    const keys = record.keys.filter(Boolean);
+    if (!keys.length)
+        return;
+    const c = readCredentials();
+    const all = { ...(c.out_written ?? {}) };
+    const list = (all[org] ?? []).filter((r) => !(r.noun === record.noun && r.keys.some((k) => keys.includes(k))));
+    all[org] = [...list, { noun: record.noun, keys }];
+    c.out_written = all;
+    writeCredentials(c);
 }
-export function markOutWritten(org, written) {
+/**
+ * After a delete: whether that record had a secret written with --out, which is then forgotten.
+ * With no record named, the organization goes (sandbox destroy).
+ */
+export function forgetOutWritten(org, record) {
     const c = readCredentials();
+    const list = c.out_written?.[org] ?? [];
+    const hit = (r) => !record || (r.noun === record.noun && r.keys.some((k) => record.keys.includes(k)));
+    if (!list.some(hit))
+        return false;
+    const rest = list.filter((r) => !hit(r));
     const all = { ...(c.out_written ?? {}) };
-    if (written === Boolean(all[org]))
-        return;
-    if (written)
-        all[org] = true;
+    if (rest.length)
+        all[org] = rest;
     else
         delete all[org];
     c.out_written = all;
     writeCredentials(c);
+    return true;
 }
 export function storedBooking(id) {
     const b = readCredentials().bookings?.[id];

package/dist/engine.js

@@ -4,7 +4,7 @@
 // destructive verb, then the request. A plain noun needs no code here: its schema says
 // everything. Every answer is the API's envelope, { data, state, warnings, next }.
 import { parseCommand, parseFields, toFlag } from './argv.js';
-import { outWritten, raiseProblem, resolveOrg } from './config.js';
+import { forgetOutWritten, raiseProblem, resolveOrg } from './config.js';
 import { confirm, terminal } from './confirm.js';
 import { CliError, closest, fail, fixWith } from './errors.js';
 import { indexHelp, nounHelp, verbHelp } from './help.js';
@@ -118,9 +118,9 @@ export async function execute(argv, opts = {}) {
     return filesGone(secretOf(r, run, secretPlan), run);
 }
 /**
- * A delete of a record whose verbs answer secrets (credentials, webhooks): the files c11r wrote
- * for it go with it, listed in removed_files. out_files_not_tracked only when it may apply:
- * nothing found here, or a secret of this organization written with --out on this machine.
+ * A delete on a noun that answers secrets: the files c11r wrote for that record in the secrets
+ * folder go with it, listed in removed_files. out_files_not_tracked only when that record's secret
+ * was written with --out on this machine: that file stays where it was written.
  */
 function filesGone(r, run) {
     if (run.verb.name !== 'delete' || run.globals.dryRun || !run.org.org)
@@ -128,8 +128,9 @@ function filesGone(r, run) {
     if (!Object.values(run.schema.verbs).some((v) => v.secret))
         return r;
     const data = (r.data && typeof r.data === 'object' ? r.data : {});
-    const removed = removeRecordFiles(run.org.org, run.schema.noun, [run.parsed.id, data.id, data.name, data.code]);
-    const warn = removed.length === 0 || outWritten(run.org.org);
+    const keys = [run.parsed.id, data.id, data.name, data.code].filter((k) => typeof k === 'string' && k !== '');
+    const removed = removeRecordFiles(run.org.org, run.schema.noun, keys);
+    const warn = forgetOutWritten(run.org.org, { noun: run.schema.noun, keys });
     return { ...r, data: { ...data, removed_files: removed }, warnings: [...r.warnings, ...(warn ? [OUT_NOT_TRACKED] : [])] };
 }
 /** A secret in the answer goes to its file; a dry run says where it would go. */

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 values separated by commas). A dotted flag sets part of an object (--customer.email). An 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 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.',
@@ -74,7 +74,7 @@ export function usageOf(noun, v) {
     const needed = (f) => f.required || (f.input?.kind === 'secret' && f.input.required);
     const required = Object.entries(v.flags)
         .filter(([, f]) => needed(f))
-        .map(([k, f]) => `${toFlag(k)} <${f.input ? 'file' : f.type === 'enum' ? f.values?.join('|') : f.type}>`);
+        .map(([k, f]) => `${toFlag(k)} <${f.input ? 'file' : f.type === 'enum' && f.values?.length ? f.values.join('|') : f.type}>`);
     const optional = Object.entries(v.flags).some(([k, f]) => !needed(f) && !v.idAlternative.includes(k));
     const id = v.id ? (v.idAlternative.length ? `<id | ${v.idAlternative.map((k) => `${toFlag(k)} <${v.flags[k].type}>`).join(' ')}>` : '<id>') : '';
     return [`c11r ${noun} ${v.name}`, id, ...required, optional ? '[--field value ...]' : ''].filter(Boolean).join(' ');

package/dist/resources.js

@@ -21,7 +21,7 @@ export function resourceRequest(noun, verb, id, values) {
         else if (flag.to === 'local')
             continue;
         else if (flag.to === 'filter')
-            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = text(value);
+            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = flag.filter.op === 'in' ? inList(value) : text(value);
         else
             query[key] = text(value);
     }
@@ -39,4 +39,7 @@ export function resourceRequest(noun, verb, id, values) {
         req.body = body;
     return req;
 }
+// An in list is joined by commas, or sent as a JSON array of strings when a value has a comma of its
+// own ("UK VAT, manual"), so the API keeps each value whole (contract 28.4).
+const inList = (v) => (Array.isArray(v) && v.some((x) => typeof x === 'string' && x.includes(',')) ? JSON.stringify(v.map(String)) : text(v));
 const text = (v) => (Array.isArray(v) ? v.join(',') : typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v));

package/dist/schema.js

@@ -145,7 +145,7 @@ function flag(f, to, required) {
         to,
         ...(f.values ? { values: f.values } : {}),
         ...(f.items ? { items: f.items } : {}),
-        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, p.type])) } : {}),
+        ...(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 } : {}),
         ...(required ? { required: true } : {}),
         ...(f.description ? { description: f.description } : {}),

package/dist/secrets.js

@@ -97,9 +97,9 @@ export function writeSecret(r, plan, ctx) {
         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.
+    // An --out file is not removed with its record: remember which record has one, for the warning.
     if (plan.fixed && ctx.org)
-        markOutWritten(ctx.org, true);
+        markOutWritten(ctx.org, { noun: ctx.noun, keys: [record.id, record.name, record.code, ctx.id].filter((k) => typeof k === 'string' && k !== '') });
     // 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))

package/package.json

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