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

package/README.md

@@ -18,6 +18,7 @@ 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 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.
 
@@ -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
 
@@ -82,6 +83,8 @@ Records that share a key (two shipping methods with the same name in one market,
 
 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

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

@@ -118,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 } };
         }
@@ -147,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.11",
+  "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": [