@commercelayer/agent-cli 1.0.0-dev.10 → 1.0.0-dev.12

package/README.md

@@ -18,7 +18,8 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 - 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.
+- A field with documented values the API does not enforce (`known`: webhook topics) takes any value. One outside them is sent anyway, with the warning `unknown_value` and `did_you_mean`. Help lists up to 20 of them, and past that says how many and that `c11r schema <noun>` has them all.
+- 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. Where the verb takes `--format csv` (`imports create`), the file goes as CSV text with `--format csv`, or when its name ends in `.csv` and no format is given; otherwise it is JSON.
 - A verb whose schema lists `id_alternative` takes the id or those flags in its place: `c11r prices get pr_1`, or `c11r prices get --sku BEANS-1KG --price-list eur`. Both at once, or half the flags, stop before sending.
 
 ## Built-in nouns
@@ -64,7 +65,7 @@ Never from a flag or the environment. c11r exchanges the pair for a two hour tok
 | `--live` | Live data, on a claimed organization: `?mode=live` on every request. Without it, test mode. |
 | `--help` | Describes the noun or verb it follows, from its schema. |
 
-Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sandbox reset` and `destroy`), and any verb the schema marks `confirm`, ask for confirmation in a terminal, then send `confirm=true`. With no terminal, as when an agent or a schedule runs the CLI, they never wait: without `--yes` they stop at once with `confirmation_required` and exit code 3.
+Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sandbox reset` and `destroy`), and any verb the schema marks `confirm`, ask for confirmation in a terminal, then send `confirm=true`. With no terminal, as when an agent or a schedule runs the CLI, they never wait: without `--yes` they stop at once with `confirmation_required` and exit code 3. Its `next_step.command` is the same command without `--yes`: the agent asks the human first, and only on their yes runs it again with `--yes`. The API's own `confirmation_required` works the same way.
 
 ## Which organization
 
@@ -76,12 +77,14 @@ Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sand
 
 ## The store's setup in files
 
-`c11r config export` writes the organization's setup into the project folder: `store.yml` (the Configure nouns, refs by key, no ids, no secrets; its first key, `meta`, names the organization and the time) and `price_lists/<code>.csv`. It records what it wrote in `.c11r/export.json`, and never overwrites a file changed since the last export (or one no export wrote) without `--yes`: the answer lists them. A price list file the organization no longer has, unchanged since, goes. `c11r config plan` sends the files and answers what `config apply` would change; `apply` makes the organization match them, and with `--prune` (confirmed) also deletes what the files lack. While imports run, `apply` answers `status: running` with each noun's state and `retry_after`; `--wait` applies again until done or failed.
+`c11r config export` writes the organization's setup into the project folder: `store.yml` (the Configure nouns, refs by key, no ids, no secrets; its first key, `meta`, names the organization and the time) and `price_lists/<code>.csv` (in a row, an empty `compare_at_amount` means equal to `amount`, and one below `amount` is refused). It records what it wrote in `.c11r/export.json`, and never overwrites a file changed since the last export (or one no export wrote) without `--yes`: the answer lists them. A price list file the organization no longer has, unchanged since, goes. `c11r config plan` sends the files and answers what `config apply` would change; `apply` makes the organization match them, and with `--prune` (confirmed) also deletes what the files lack. While imports run, `apply` answers `status: running` with each noun's state, `retry_after` and the run's token, `run`; `--wait` applies again with that token and the same files until done or failed, and the done answer counts everything the run wrote. The `next` an unfinished apply suggests carries `--run <token> --wait`. `plan` lists in `needs` the new records the files can't make alone (a webhook without its `callback_url`); `apply` skips them and warns `needs_input` with the command that creates each.
 
 Records that share a key (two shipping methods with the same name in one market, say) can't be matched to the files. `export` and `plan` list them in `ambiguous` (an empty list when there are none), each with the command that makes its key differ, and `export` puts the first one at the top of `next`. `apply` refuses with `conflict` and the same list in `error.details.ambiguous`, before it writes anything.
 
 After a Configure write that went through (create, update, delete or a domain verb), in a folder whose `store.yml` names the same organization, the answer warns `config_drift` and `.c11r/drift` notes the write; `config plan` repeats the warning, and `config export` clears it.
 
+`c11r scaffold drop-in --out <file>` writes the drop-in.js snippet as one HTML file: the part for the page's `<head>`, then the part for its `<body>`, each under a comment saying where it goes. It never replaces a different file without `--yes`. Without `--out`, the snippet stays in the JSON answer.
+
 `c11r exports get <id> --out <file>` downloads a completed export while its link lasts (5 minutes), unzipped unless the name ends in `.gz`; `--wait` reads the job again until it completes.
 
 ## Output, errors and exit codes

package/dist/builtins/extensions.js

@@ -169,14 +169,18 @@ export const config = {
             };
         }
         if (name === 'plan' || name === 'apply') {
-            const req = resourceRequest('config', run.verb, undefined, run.parsed.values);
-            let r = await run.send(req);
+            const values = run.parsed.values;
+            let r = await run.send(resourceRequest('config', run.verb, undefined, values));
             const started = Date.now();
-            while (name === 'apply' && run.parsed.values.wait && r.data?.status === 'running' && Date.now() - started < WAIT_MAX_MS) {
+            while (name === 'apply' && values.wait && r.data?.status === 'running' && Date.now() - started < WAIT_MAX_MS) {
                 const ms = waitMs(r.data);
                 process.stderr.write(JSON.stringify({ running: { nouns: states(r.data), next_in_ms: ms } }) + '\n');
                 await sleep(ms);
-                r = await run.send(req);
+                // The same run carries on (45.9): its token goes back with the same files, so done counts
+                // everything the run wrote.
+                if (typeof r.data?.run === 'string')
+                    values.run = r.data.run;
+                r = await run.send(resourceRequest('config', run.verb, undefined, values));
             }
             const warnings = [...r.warnings];
             const here = storeFileOrg();
@@ -192,12 +196,25 @@ export const config = {
                 ...r,
                 data: running ? { ...data, retry_after: waitMs(data) / 1000, states: states(data) } : data,
                 warnings,
-                next: running && !run.parsed.values.wait ? [{ command: `${run.line} --wait`, why: 'carry on, and wait until every noun is done or failed' }, ...r.next] : r.next,
+                next: running ? [{ command: carryOn(run.line, run.verb.flags.run ? data.run : undefined), why: 'carry on with the same files, and wait until every noun is done or failed' }, ...r.next] : r.next,
             };
         }
         return undefined;
     },
 };
+/**
+ * The apply that carries this run on: the same line with its --run token and --wait. Without --yes:
+ * a yes covers the run the human saw, so carrying on a prune is confirmed again.
+ */
+function carryOn(line, token) {
+    let out = line
+        .replace(/\s--run(=|\s+)("[^"]*"|'[^']*'|\S+)/g, '')
+        .replace(/\s--wait\b/g, '')
+        .replace(/\s(--yes|-y)(?=\s|$)/g, '');
+    if (typeof token === 'string' && token)
+        out += ` --run ${/^[\w.~:+\/=-]+$/.test(token) ? token : `'${token.replace(/'/g, `'\\''`)}'`}`;
+    return `${out} --wait`;
+}
 /** Each noun's state while apply runs: done, running (with its import), waiting, failed or unchanged. */
 function states(data) {
     const out = {};
@@ -255,4 +272,44 @@ export const exports = {
         return { ...r, data: { ...rest, file, bytes: bytes.length, unzipped: zipped && !file.endsWith('.gz') } };
     },
 };
-export const extensions = { organizations, 'sales-calls': salesCalls, config, exports };
+// scaffold (46): drop-in --out writes the snippet as one HTML file, its head part and its body part
+// each under a comment saying where it goes. It never replaces a different file without --yes.
+export const scaffold = {
+    flags: {
+        'drop-in': {
+            out: { type: 'string', to: 'local', description: 'Write the snippet to this HTML file: the part for the page\'s <head>, then the part for its <body>, each under a comment saying where it goes. A different file there is replaced only with --yes.' },
+        },
+    },
+    async run(run) {
+        const out = run.parsed.values.out;
+        if (run.verb.name !== 'drop-in' || !out)
+            return undefined;
+        const file = path.resolve(out);
+        // Before anything is sent: a different file there stays without --yes.
+        const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+        const r = await run.send(resourceRequest('scaffold', run.verb, undefined, run.parsed.values));
+        if (run.globals.dryRun)
+            return r;
+        const data = r.data ?? {};
+        const snippet = data.snippet;
+        if (!snippet || typeof snippet.head !== 'string' || typeof snippet.body !== 'string')
+            fail('invalid_response', 'scaffold drop-in answered without snippet.head and snippet.body.', { next_step: { action: 'none' } });
+        const html = [
+            `<!-- c11r scaffold drop-in${run.org.org ? ` (${run.org.org})` : ''}: this part goes in the page's <head>. -->`,
+            snippet.head.trimEnd(),
+            '',
+            `<!-- This part goes in the page's <body>, where the products show. -->`,
+            snippet.body.trimEnd(),
+            '',
+        ].join('\n');
+        if (before !== null && before !== html && !run.globals.yes) {
+            fail('conflict', `${file} is there already, and differs from this snippet. c11r replaces it only with --yes.`, { path: 'out', details: { files: [file] }, next_step: { action: 'fix_request', command: null } }, 'rejected');
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        if (before !== html)
+            fs.writeFileSync(file, html);
+        const { snippet: _snippet, ...rest } = data;
+        return { ...r, data: { ...rest, file, replaced: before !== null && before !== html } };
+    },
+};
+export const extensions = { organizations, 'sales-calls': salesCalls, config, exports, scaffold };

package/dist/confirm.js

@@ -45,9 +45,10 @@ export async function confirm(action, command, opts) {
         return;
     const p = opts.prompter ?? terminal;
     if (!p.interactive) {
-        // The agent asks the human; on a yes it repeats the command with --yes.
-        fail('confirmation_required', `${action} needs confirmation, and there is no terminal to ask in. Ask the human whether to go ahead.`, {
-            next_step: { action: 'fix_request', command: `${command} --yes` },
+        // The agent asks the human; on a yes it repeats the command with --yes. next never carries the
+        // --yes itself: only the human's answer adds it.
+        fail('confirmation_required', `${action} needs confirmation, and there is no terminal to ask in. Ask the human first; on their yes, run it again with --yes.`, {
+            next_step: { action: 'fix_request', command },
         });
     }
     const answer = (await p.ask(`${action}. Go ahead? [y/N] `)).trim().toLowerCase();

package/dist/engine.js

@@ -74,6 +74,7 @@ async function executeOnce(argv, opts) {
     await readInputs(schema.noun, verb, parsed, null);
     check(schema, verb, parsed);
     await readInputs(schema.noun, verb, parsed, opts.prompter ?? terminal);
+    const unknown = unknownValues(verb, parsed.values);
     const line = ['c11r', ...argv.filter((a) => a !== '--yes' && a !== '-y')].map(quote).join(' ');
     const org = resolveOrg(cmd.globals.org);
     const login = hasLogin();
@@ -143,7 +144,32 @@ async function executeOnce(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 drifted(filesGone(secretOf(r, run, secretPlan), run), run);
+    const out = drifted(filesGone(secretOf(r, run, secretPlan), run), run);
+    return unknown.length ? { ...out, warnings: [...unknown, ...out.warnings] } : out;
+}
+/**
+ * A value outside a flag's documented values (known: webhook topics): not enforced, so it is sent,
+ * with a warning and the closest documented ones.
+ */
+function unknownValues(verb, values) {
+    const out = [];
+    for (const [key, f] of Object.entries(verb.flags)) {
+        const v = values[key];
+        if (!f.known || v === undefined || v === null)
+            continue;
+        for (const x of (Array.isArray(v) ? v : [v]).filter((x) => typeof x === 'string' && x !== '')) {
+            if (f.known.includes(x))
+                continue;
+            const near = closest(x, f.known);
+            out.push({
+                code: 'unknown_value',
+                message: `${x} is not one of the documented values of ${toFlag(key)}${near.length ? ` (closest: ${near.join(', ')})` : ''}; it was sent anyway.`,
+                path: key,
+                ...(near.length ? { did_you_mean: near } : {}),
+            });
+        }
+    }
+    return out;
 }
 /**
  * A Configure write that went through, in a folder whose store.yml names this organization: the

package/dist/help.js

@@ -58,16 +58,19 @@ export function verbHelp(s, v) {
         ...(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)),
+        flags: Object.entries(v.flags).map(([key, f]) => flagHelp(key, f, s.noun)),
     };
 }
-function flagHelp(key, f) {
+/** Up to this many documented values are listed in help; past it, help says where they are. */
+const KNOWN_IN_FULL = 20;
+function flagHelp(key, f, noun) {
     return {
         flag: toFlag(key),
         type: f.type === 'array' ? `array of ${f.items ?? 'string'}` : f.type === 'ref' ? `${f.noun ?? 'resource'} id` : f.type === 'money' ? 'amount in major units' : f.type,
         ...(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.known ? { known: f.known.length <= KNOWN_IN_FULL ? f.known : `one of ${f.known.length} documented values: c11r schema ${noun}` } : {}),
         ...(clearable(f) ? { clear: 'null, or an empty value, takes it off' } : {}),
         ...(f.filter ? { filter: f.filter.op } : {}),
         ...(f.description ? { description: f.description } : {}),

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/schema.js

@@ -103,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)}.`,
         };
     }
 }
@@ -116,7 +118,7 @@ function listFlags(flags, fields, doc) {
             if (op === 'in')
                 flags[key] = { ...base, type: 'array', items: f.type === 'array' ? f.items : f.type, filter: { field: f.name, op } };
             else if (op === 'null')
-                flags[key] = { ...base, type: 'boolean', values: undefined, filter: { field: f.name, op } };
+                flags[key] = { ...base, type: 'boolean', values: undefined, known: undefined, filter: { field: f.name, op } };
             else
                 flags[key] = { ...base, filter: { field: f.name, op } };
         }
@@ -145,6 +147,7 @@ function flag(f, to, required) {
         type: f.type,
         to,
         ...(f.values ? { values: f.values } : {}),
+        ...(Array.isArray(f.known) && f.known.length ? { known: f.known } : {}),
         ...(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 } : {}),

package/package.json

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