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

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';
@@ -12,11 +12,37 @@ import { envelope, request } from './http.js';
 import { readInputs } from './inputs.js';
 import { hasLogin, loginToken } from './login.js';
 import { resourceRequest } from './resources.js';
+import { markDrift } from './project.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)
@@ -28,7 +54,10 @@ export async function execute(argv, opts = {}) {
     const schema = builtins[cmd.noun]?.schema ?? (await apiSchema(cmd.noun, Object.keys(builtins)));
     if (cmd.globals.help && !cmd.verb && !builtins[cmd.noun]?.defaultVerb)
         return envelope(nounHelp(schema));
-    const verb = verbOf(schema, cmd.verb ?? builtins[cmd.noun]?.defaultVerb);
+    const ext = opts.extensions?.[schema.noun];
+    const found = verbOf(schema, cmd.verb ?? builtins[cmd.noun]?.defaultVerb);
+    const local = ext?.flags?.[found.name];
+    const verb = local ? { ...found, flags: { ...found.flags, ...local } } : found;
     if (cmd.globals.help)
         return envelope(verbHelp(schema, verb));
     // A verb the schema lists as refused: no request, no confirmation for something that cannot happen.
@@ -36,7 +65,6 @@ export async function execute(argv, opts = {}) {
         const by = verb.refused.by === 'commercelayer' ? 'Commerce Layer' : verb.refused.by;
         fail('not_supported', `c11r ${schema.noun} ${verb.name} is refused by ${by}: ${verb.description || 'it cannot be done through the API.'}`, { details: { refused_by: verb.refused.by }, next_step: { action: 'none' } });
     }
-    const ext = opts.extensions?.[schema.noun];
     const positional = ext?.positional?.[verb.name];
     const rest = positional && !verb.id && cmd.rest[0] !== undefined && !cmd.rest[0].startsWith('-') ? [`--${positional}`, ...cmd.rest] : cmd.rest;
     const parsed = parseFields(schema.noun, verb, rest);
@@ -73,13 +101,13 @@ export async function execute(argv, opts = {}) {
     }
     let confirmed = false;
     const confirmFlags = verb.confirmIf.filter((k) => parsed.values[k] !== undefined && parsed.values[k] !== false);
-    if ((verb.destructive || confirmFlags.length) && !cmd.globals.dryRun) {
+    if ((verb.destructive || verb.confirm || confirmFlags.length) && !cmd.globals.dryRun) {
         const what = `${verb.name} ${schema.noun}${parsed.id ? ` ${parsed.id}` : ''}${confirmFlags.length ? ` with ${confirmFlags.map(toFlag).join(' ')}` : ''}`;
         await confirm(what.charAt(0).toUpperCase() + what.slice(1), line, { yes: cmd.globals.yes, prompter: opts.prompter });
         confirmed = true;
     }
     // Where a secret goes, checked before the request makes one.
-    const secretPlan = verb.secret ? planSecret({ org: org.org, verb: verb.name, id: parsed.id, values: parsed.values, yes: cmd.globals.yes }) : null;
+    const secretPlan = verb.secret ? planSecret({ org: org.org, noun: schema.noun, verb: verb.name, id: parsed.id, values: parsed.values, yes: cmd.globals.yes }) : null;
     const ctx = { live: cmd.globals.live, token: bearer === 'login' ? await loginToken() : org.token };
     const orgQuery = bearer === 'login' && loginOrg && schema.noun !== 'organizations' && schema.noun !== 'auth' ? { org: loginOrg } : {};
     const sendOnce = (req) => request({ ...req, query: { ...(req.query ?? {}), ...orgQuery }, dryRun: req.dryRun ?? cmd.globals.dryRun, confirm: confirmed || req.confirm }, ctx);
@@ -115,12 +143,26 @@ export async function execute(argv, opts = {}) {
     };
     const own = (await builtins[schema.noun]?.run?.(run)) ?? (await ext?.run?.(run));
     const r = own ?? (await run.send(resourceRequest(schema.noun, verb, parsed.id, parsed.values)));
-    return filesGone(secretOf(r, run, secretPlan), run);
+    return drifted(filesGone(secretOf(r, run, secretPlan), run), run);
+}
+/**
+ * A Configure write that went through, in a folder whose store.yml names this organization: the
+ * file is now behind it. Noted in .c11r/drift, with the warning config_drift.
+ */
+function drifted(r, run) {
+    if (run.globals.dryRun || !run.org.org || run.verb.method === 'GET')
+        return r;
+    if (run.schema.doc?.group !== 'configure')
+        return r;
+    const data = (r.data && typeof r.data === 'object' ? r.data : {});
+    const id = [run.parsed.id, data.code, data.name, data.id].find((k) => typeof k === 'string' && k !== '');
+    const warning = markDrift(run.org.org, { noun: run.schema.noun, verb: run.verb.name, id: id ?? null });
+    return warning ? { ...r, warnings: [...r.warnings, warning] } : r;
 }
 /**
- * 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 +170,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. */
@@ -138,7 +181,7 @@ function secretOf(r, run, plan) {
     const secret = data && typeof data === 'object' ? data.secret : undefined;
     if (secret && typeof secret === 'object' && 'value' in secret) {
         // A verb the schema did not mark: still never printed.
-        const p = plan ?? planSecret({ org: run.org.org, verb: run.verb.name, id: run.parsed.id, values: run.parsed.values, yes: true });
+        const p = plan ?? planSecret({ org: run.org.org, noun: run.schema.noun, verb: run.verb.name, id: run.parsed.id, values: run.parsed.values, yes: true });
         return writeSecret(r, p, { org: run.org.org, noun: run.schema.noun, verb: run.verb.name, id: run.parsed.id });
     }
     if (plan && run.globals.dryRun)

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 }.',
@@ -21,7 +22,7 @@ export const EXIT_CODE_HELP = {
     [EXIT.not_found]: 'no such resource',
     [EXIT.rejected]: 'the API or Commerce Layer refused the request as it is',
     [EXIT.unavailable]: 'the API did not answer, is busy, or answered with an error of its own',
-    [EXIT.auth]: 'a wrong or revoked token, or no token stored for the organization named',
+    [EXIT.auth]: 'a wrong or revoked token, no token stored for the organization named, or no login (login_required)',
 };
 export function indexHelp(builtins, api) {
     return {
@@ -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 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 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.',
@@ -53,7 +54,8 @@ export function verbHelp(s, v) {
         state: v.state,
         ...(v.plan ? { plan: v.plan } : {}),
         ...(v.refused ? { served: false, refused_by: v.refused.by } : {}),
-        ...(v.destructive ? { destructive: true, confirmation: 'Asks for confirmation unless --yes; with no terminal and no --yes it stops with confirmation_required.' } : {}),
+        ...(v.destructive ? { destructive: true } : {}),
+        ...(v.confirm ? { confirmation: 'Asks for confirmation unless --yes; with no terminal and no --yes it stops with confirmation_required.' } : {}),
         ...(v.loopable ? { loopable: 'A loop policy may allow this verb.' } : {}),
         ...(v.live ? {} : { live: 'Not in live mode.' }),
         flags: Object.entries(v.flags).map(([key, f]) => flagHelp(key, f)),
@@ -66,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 } : {}),
     };
@@ -74,7 +77,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/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/inputs.js

@@ -4,6 +4,8 @@
 // KEY=value lines, from a plain file only its owner can read; or, in a terminal, typed without
 // echo. Never from a flag value or --data, never printed: an error names the file, not the value.
 // A document field (file_input: price rules, rule filters) is also read from a JSON file, --file.
+// Where the verb takes --format csv (imports), the file is sent as CSV text with --format csv, or
+// when it ends in .csv and no format is given; JSON otherwise.
 import fs from 'node:fs';
 import { toFlag } from './argv.js';
 import { fail } from './errors.js';
@@ -29,7 +31,12 @@ export async function readInputs(noun, verb, parsed, prompter) {
                 continue;
             if (parsed.values[input.target] !== undefined)
                 fail('invalid_value', `${cmd} takes ${input.target} from ${toFlag(input.target)} or from ${toFlag(key)}, not both.`, { path: key });
-            parsed.values[input.target] = documentOf(file, key, spec);
+            if (isCsv(verb, parsed, file)) {
+                parsed.values.format ??= 'csv';
+                parsed.values[input.target] = csvOf(file, key);
+            }
+            else
+                parsed.values[input.target] = documentOf(file, key, spec);
             continue;
         }
         if (file !== undefined) {
@@ -51,6 +58,19 @@ export async function readInputs(noun, verb, parsed, prompter) {
         });
     }
 }
+const isCsv = (verb, parsed, file) => Boolean(verb.flags.format?.values?.includes('csv')) && (parsed.values.format === 'csv' || (parsed.values.format === undefined && /\.csv$/i.test(file)));
+function csvOf(file, key) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        fail('invalid_value', `${toFlag(key)} ${file}: ${e.code === 'ENOENT' ? 'no such file' : e.message}.`, { path: key });
+    }
+    if (!text.trim())
+        fail('invalid_value', `${file} is empty: a CSV file starts with its header row.`, { path: key });
+    return text;
+}
 function documentOf(file, key, spec) {
     let text;
     try {

package/dist/project.js

@@ -0,0 +1,175 @@
+// The project folder's configuration files (contract section 45.2): store.yml and
+// price_lists/<code>.csv, written by config export and read by config plan and apply, and the
+// CLI's own notes about them in .c11r/:
+//
+//   .c11r/export.json  what the last export wrote: the organization, when, and each file's hash,
+//                      so the next export never overwrites a file changed since without --yes.
+//   .c11r/drift        the Configure writes made since, in a folder whose store.yml names the
+//                      same organization: config plan mentions them, config export clears them.
+//
+// store.yml carries the export's meta ({ org, exported_at }) as its first key; the CLI takes it
+// off before it sends the file, so the API sees { <noun>: [records] } only.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { projectDir } from './config.js';
+import { fail } from './errors.js';
+export const STORE_FILE = 'store.yml';
+export const PRICE_LISTS_DIR = 'price_lists';
+const NOTES_DIR = '.c11r';
+const EXPORT_FILE = 'export.json';
+const DRIFT_FILE = 'drift';
+const hashOf = (text) => `sha256-${crypto.createHash('sha256').update(text).digest('hex')}`;
+const notes = (dir) => path.join(dir, NOTES_DIR);
+/** store.yml and the price list CSVs of the project folder, or store_not_found. */
+export function readStoreFiles(dir = projectDir()) {
+    const file = path.join(dir, STORE_FILE);
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        fail('not_found', `There is no ${STORE_FILE} in ${dir}. c11r config export writes one from the organization.`, { path: 'store', next_step: { action: 'fix_request', command: 'c11r config export' } });
+    }
+    let doc;
+    try {
+        doc = YAML.parse(text) ?? {};
+    }
+    catch (e) {
+        fail('invalid_config', `${file} is not YAML: ${e.message}`, { path: 'store' });
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        fail('invalid_config', `${file} holds no nouns: it is { <noun>: [records] }.`, { path: 'store' });
+    const { meta, ...store } = doc;
+    const org = meta && typeof meta === 'object' && typeof meta.org === 'string' ? meta.org : null;
+    const price_lists = {};
+    const csvDir = path.join(dir, PRICE_LISTS_DIR);
+    let names = [];
+    try {
+        names = fs.readdirSync(csvDir);
+    }
+    catch {
+        // No price lists: fine.
+    }
+    for (const n of names.sort())
+        if (n.endsWith('.csv'))
+            price_lists[n.slice(0, -4)] = fs.readFileSync(path.join(csvDir, n), 'utf8');
+    return { store, price_lists, org };
+}
+/** The organization the folder's store.yml names, or null without one. */
+export function storeFileOrg(dir = projectDir()) {
+    try {
+        const doc = YAML.parse(fs.readFileSync(path.join(dir, STORE_FILE), 'utf8'));
+        return typeof doc?.meta?.org === 'string' ? doc.meta.org : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Writes an export: store.yml (meta first) and price_lists/<code>.csv. A file there that differs
+ * from what the last export wrote (or that no export wrote) is the user's: without overwrite,
+ * nothing is written and the answer lists them. Price list files the last export wrote, unchanged
+ * since, and no longer in the organization, go.
+ */
+export function writeStoreFiles(data, opts) {
+    const dir = opts.dir ?? projectDir();
+    const last = readRecord(dir);
+    const meta = { org: data.meta?.org ?? null, exported_at: data.meta?.exported_at ?? new Date().toISOString() };
+    const yaml = `# The organization's setup, written by c11r config export. Edit it, then c11r config plan and c11r config apply.\n${YAML.stringify({ meta, ...data.store }, { lineWidth: 0 })}`;
+    const files = { [STORE_FILE]: yaml };
+    for (const [code, csv] of Object.entries(data.price_lists ?? {}))
+        files[path.join(PRICE_LISTS_DIR, `${safeName(code)}.csv`)] = csv;
+    const changed = (rel) => {
+        const abs = path.join(dir, rel);
+        if (!fs.existsSync(abs))
+            return false;
+        const now = hashOf(fs.readFileSync(abs, 'utf8'));
+        return last.files[rel] !== now;
+    };
+    const stale = Object.keys(last.files).filter((rel) => rel.startsWith(`${PRICE_LISTS_DIR}${path.sep}`) && !(rel in files) && fs.existsSync(path.join(dir, rel)));
+    const mine = [...Object.keys(files).filter((rel) => files[rel] !== readOr(path.join(dir, rel))), ...stale].filter(changed);
+    if (mine.length && !opts.overwrite) {
+        fail('conflict', `${mine.join(', ')} changed since the last export${last.exported_at ? ` (${last.exported_at})` : ''}, or no export wrote ${mine.length === 1 ? 'it' : 'them'}. c11r replaces ${mine.length === 1 ? 'it' : 'them'} only with --yes; c11r config plan shows what the files would change in the organization.`, {
+            path: 'store',
+            details: { files: mine.map((rel) => path.join(dir, rel)) },
+            next_step: { action: 'fix_request', command: 'c11r config plan' },
+        }, 'rejected');
+    }
+    const written = [];
+    for (const [rel, text] of Object.entries(files)) {
+        const abs = path.join(dir, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        if (readOr(abs) !== text)
+            fs.writeFileSync(abs, text);
+        written.push(abs);
+    }
+    const removed = [];
+    for (const rel of stale) {
+        fs.rmSync(path.join(dir, rel), { force: true });
+        removed.push(path.join(dir, rel));
+    }
+    writeRecord(dir, { org: meta.org, exported_at: meta.exported_at, files: Object.fromEntries(Object.entries(files).map(([rel, text]) => [rel, hashOf(text)])) });
+    clearDrift(dir);
+    return { written, removed, dir };
+}
+/**
+ * After a Configure write: in a folder whose store.yml names this organization, notes it in
+ * .c11r/drift and answers the warning. Elsewhere, nothing.
+ */
+export function markDrift(org, entry, dir = projectDir()) {
+    if (storeFileOrg(dir) !== org)
+        return null;
+    const list = readDrift(dir);
+    list.push({ ...entry, at: new Date().toISOString() });
+    fs.mkdirSync(notes(dir), { recursive: true });
+    // The first ones say since when; the last 50 say what.
+    const kept = list.length > 50 ? [list[0], ...list.slice(-49)] : list;
+    fs.writeFileSync(path.join(notes(dir), DRIFT_FILE), JSON.stringify(kept, null, 2) + '\n');
+    return driftWarning(kept);
+}
+/** The writes noted since the last export, oldest first. */
+export function readDrift(dir = projectDir()) {
+    try {
+        const v = JSON.parse(fs.readFileSync(path.join(notes(dir), DRIFT_FILE), 'utf8'));
+        return Array.isArray(v) ? v : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function clearDrift(dir = projectDir()) {
+    fs.rmSync(path.join(notes(dir), DRIFT_FILE), { force: true });
+}
+export function driftWarning(list) {
+    const first = list[0];
+    const what = (e) => `${e.noun} ${e.verb}${e.id ? ` ${e.id}` : ''}`;
+    return {
+        code: 'config_drift',
+        message: `store.yml is now behind the organization, since ${first.at} (${what(first)}${list.length > 1 ? ` and ${list.length - 1} more` : ''}): c11r config export refreshes it.`,
+    };
+}
+function readRecord(dir) {
+    try {
+        const v = JSON.parse(fs.readFileSync(path.join(notes(dir), EXPORT_FILE), 'utf8'));
+        return { org: v.org ?? null, exported_at: v.exported_at ?? null, files: v.files && typeof v.files === 'object' ? v.files : {} };
+    }
+    catch {
+        return { org: null, exported_at: null, files: {} };
+    }
+}
+function writeRecord(dir, r) {
+    fs.mkdirSync(notes(dir), { recursive: true });
+    fs.writeFileSync(path.join(notes(dir), EXPORT_FILE), JSON.stringify(r, null, 2) + '\n');
+}
+function readOr(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** A price list code as a file name: letters, digits, dot, dash and underscore. */
+const safeName = (code) => code.replace(/[^A-Za-z0-9._-]+/g, '-');

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

@@ -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';
@@ -53,6 +53,7 @@ export function parseSchema(raw, expected) {
             method,
             id: v.path ? /\{[^}]+\}/.test(v.path) : !['list', 'create'].includes(name),
             destructive,
+            confirm: destructive || v.confirm === true,
             // A policy never deletes nor returns money, whatever else the document says.
             loopable: Boolean(v.loopable) && !v.deletes && !v.returns_money && name !== 'delete',
             live: v.live !== false,
@@ -102,7 +103,9 @@ function fileInputs(flags, fields, body) {
             type: 'string',
             to: 'local',
             input: { kind: 'document', target: k, required: Boolean(flags[k].required), target_type: flags[k].type },
-            description: `A JSON file with ${k}, in place of ${toFlag(k)}.`,
+            description: flags.format?.values?.includes('csv')
+                ? `A file with ${k}, in place of ${toFlag(k)}: JSON, or CSV with --format csv or a name ending in .csv.`
+                : `A JSON file with ${k}, in place of ${toFlag(k)}.`,
         };
     }
 }
@@ -145,8 +148,9 @@ 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 } : {}),
+        ...(f.nullable !== undefined ? { nullable: f.nullable } : {}),
         ...(required ? { required: true } : {}),
         ...(f.description ? { description: f.description } : {}),
     };
@@ -180,3 +184,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.