@commercelayer/agent-cli 1.0.0-dev.4 → 1.0.0-dev.5

package/README.md

@@ -28,7 +28,7 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 | `c11r schema <noun>` | The noun's schema document: fields, filters, verbs, which verbs are destructive and which a loop may automate. |
 | `c11r sandbox create [--name] [--seed]` | An anonymous sandbox. Its token is stored on this machine and never printed; the folder is linked to it. |
 | `c11r sandbox get`, `reset`, `claim`, `destroy` | The sandbox's details; a fresh organization behind the same token; a claim URL for the human; the end of the sandbox. |
-| `c11r loops create <name> --skill --every --allow [--max-total] [--market]` | A loop in `loops.yml`: a skill, a policy and a cadence. Also `list`, `get`, `update`, `delete`. |
+| `c11r loops create <name> --skill --every [--allow] [--max-total] [--market]` | A loop in `loops.yml`: a skill, a policy and a cadence; with no `--allow` it only reports what is waiting. Also `list`, `get`, `update`, `delete`. |
 | `c11r loops run <name>` | One pass of a loop. The CLI is not a daemon: a scheduler repeats the pass. |
 | `c11r report sales [--from] [--to] [--by] [--interval] [--market] [--top]` | Sales in a window, from the Metrics API. A plain noun: its flags come from the API's schema. |
 | `c11r auth login [--client-id] [--secret-file] [--keep-file]` | The human's own Commerce Layer login, from their Provisioning API application. See below. |
@@ -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 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.
+`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; a record with no name, such as a gift card, `gift-card-<id>.env` after the id it is given), 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
 
@@ -63,7 +63,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`) 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.
 
 ## Which organization
 

package/dist/argv.js

@@ -60,7 +60,11 @@ export function parseFields(noun, verb, rest) {
                 id = a;
                 continue;
             }
-            fail('unexpected_argument', `${cmd} does not take ${a}${verb.id ? `: it already has the id ${id}` : ''}. A value goes after its flag.`, { next_step: fixWith(`${cmd} --help`) });
+            // A verb with no id (stock set): say which flags it does take, as --sku for the sku.
+            const sent = Object.entries(verb.flags).filter(([, f]) => f.to !== 'local');
+            const required = sent.filter(([, f]) => f.required);
+            const takes = (required.length ? required : sent).map(([k]) => toFlag(k));
+            fail('unexpected_argument', `${cmd} does not take ${a}${verb.id ? `: it already has the id ${id}` : takes.length ? `: it takes no id, only flags (${takes.join(', ')})` : ': it takes no id, only flags'}. A value goes after its flag.`, { next_step: fixWith(`${cmd} --help`) });
         }
         const [flag, inline] = splitInline(a);
         const key = toKey(flag);

package/dist/builtins/loops.js

@@ -20,7 +20,7 @@ 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: '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', required, description: 'A verb the policy allows, repeated: approve, payments.capture. Only verbs the noun\'s schema lists in loop.verbs.' },
+    { 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.' },
     { name: 'market', type: 'array', description: 'A market code the loop acts in, repeated. Items in other markets wait. Without it, every market.' },
 ];
@@ -78,9 +78,11 @@ export function readLoops(file) {
     const out = {};
     for (const [name, d] of Object.entries(raw.loops ?? {})) {
         const def = d;
-        if (!def || typeof def.skill !== 'string' || !Array.isArray(def.policy?.allow))
-            fail('invalid_config', `${file}: loop ${name} needs a skill and a policy with allow.`, { path: `loops.${name}` });
-        out[name] = def;
+        // allow may be left out, or empty: the loop only reports.
+        const allow = def?.policy?.allow ?? [];
+        if (!def || typeof def.skill !== 'string' || !Array.isArray(allow))
+            fail('invalid_config', `${file}: loop ${name} needs a skill, and its policy.allow is a list of verbs.`, { path: `loops.${name}` });
+        out[name] = { ...def, policy: { ...(def.policy ?? {}), allow } };
     }
     return out;
 }
@@ -119,7 +121,7 @@ async function write(run, name, file) {
         skill: v.skill ?? existing.skill,
         every: v.every ?? existing.every,
         policy: {
-            allow: v.allow ?? existing.policy.allow,
+            allow: v.allow ?? existing?.policy.allow ?? [],
             ...(v.max_total !== undefined ? { max_total: maxTotal(v.max_total) } : existing?.policy.max_total !== undefined ? { max_total: existing.policy.max_total } : {}),
             ...(v.market !== undefined ? { markets: v.market } : existing?.policy.markets ? { markets: existing.policy.markets } : {}),
         },
@@ -173,8 +175,6 @@ function maxTotal(items) {
  * verb its loop does not list.
  */
 async function checkPolicy(def) {
-    if (!def.policy.allow.length)
-        fail('missing_argument', 'A loop needs at least one --allow.', { path: 'allow' });
     const skills = await loopSkills();
     const allowed = skills.get(def.skill);
     if (!allowed) {
@@ -188,7 +188,7 @@ async function checkPolicy(def) {
     }
     for (const verb of def.policy.allow) {
         if (!allowed.verbs.includes(verb)) {
-            fail('policy_forbidden', `A ${def.skill} loop may not allow ${verb}. It may allow ${allowed.verbs.join(', ')}.`, { path: 'allow', did_you_mean: closest(verb, allowed.verbs), details: { loopable: allowed.verbs }, next_step: fixWith(`c11r schema ${allowed.noun}`) });
+            fail('policy_forbidden', `A ${def.skill} loop may not allow ${verb}. ${allowed.verbs.length ? `It may allow ${allowed.verbs.join(', ')}.` : 'It allows no verb: it only reports what is waiting, so it takes no --allow.'}`, { path: 'allow', did_you_mean: closest(verb, allowed.verbs), details: { loopable: allowed.verbs }, next_step: fixWith(`c11r schema ${allowed.noun}`) });
         }
     }
     return [];

package/dist/engine.js

@@ -73,13 +73,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);
@@ -139,7 +139,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

@@ -21,7 +21,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 {
@@ -53,7 +53,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)),

package/dist/schema.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,

package/dist/secrets.js

@@ -14,6 +14,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { markOutWritten } from './config.js';
 import { fail } from './errors.js';
+/** Where the record's id goes in a file named after it, once the answer gives the id. */
+const ID_SLOT = '<id>';
 export function secretsDir() {
     const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
     return path.join(base, 'c11r', 'secrets');
@@ -23,10 +25,14 @@ const safe = (s) => s.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|
 export function planSecret(opts) {
     const out = opts.values.out;
     const format = opts.values.format ?? null;
-    const base = opts.verb === 'token' ? `${safe(opts.id ?? 'credential')}-token` : safe(String(opts.values.name ?? opts.id ?? 'credential'));
+    // By the name given, else the id given; a record with neither (a gift card) by the id it is
+    // given, so each has a file of its own: gift-card-<id>.env.
+    const named = opts.values.name ?? opts.id;
+    const byRecord = !out && opts.verb !== 'token' && (named === undefined || named === null || named === '');
+    const base = opts.verb === 'token' ? `${safe(opts.id ?? 'credential')}-token` : byRecord ? `${safe(opts.noun.replace(/s$/, ''))}-${ID_SLOT}` : safe(String(named));
     const file = out ? path.resolve(out) : path.join(secretsDir(), safe(opts.org ?? 'default'), base);
-    const plan = { file: out || !format ? file : `${file}.${format}`, format, fixed: Boolean(out), overwrite: opts.yes };
-    const candidates = plan.fixed || format ? [plan.file] : [`${file}.env`, `${file}.json`];
+    const plan = { file: out || !format ? file : `${file}.${format}`, format, fixed: Boolean(out), overwrite: opts.yes, byRecord };
+    const candidates = byRecord ? [] : plan.fixed || format ? [plan.file] : [`${file}.env`, `${file}.json`];
     for (const c of candidates) {
         let st = null;
         try {
@@ -43,7 +49,7 @@ export function planSecret(opts) {
             fail('conflict', `${c} exists. c11r replaces it only with --yes, or writes the secret elsewhere with --out.`, { path: 'out', next_step: { action: 'fix_request', command: null }, details: { file: c } }, 'rejected');
         }
     }
-    const dir = path.dirname(candidates[0]);
+    const dir = path.dirname(plan.file);
     const existing = nearestExisting(dir);
     try {
         fs.accessSync(existing, fs.constants.W_OK);
@@ -74,7 +80,7 @@ export function writeSecret(r, plan, ctx) {
     const credentialId = str(rec.id) ?? ctx.id;
     const record = { noun: ctx.noun, id: credentialId ?? null, name: str(rec.name), code: str(rec.code) };
     const format = plan.format ?? (secret.format === 'json' ? 'json' : 'env');
-    const file = plan.fixed || plan.format ? plan.file : `${plan.file}.${format}`;
+    const file = byRecordFile(plan.fixed || plan.format ? plan.file : `${plan.file}.${format}`, plan, credentialId);
     const env = secret.env && Object.keys(secret.env).length ? { ...secret.env } : { [`CL_${(secret.kind ?? 'secret').toUpperCase()}`]: String(secret.value ?? '') };
     // The endpoint goes with every secret, so the file is enough to call Commerce Layer.
     if (!env.CL_BASE_ENDPOINT && typeof data.base_endpoint === 'string')
@@ -111,6 +117,18 @@ export function writeSecret(r, plan, ctx) {
         warnings,
     };
 }
+/** A file named after its record: the id in its slot, and a file there already left alone. */
+function byRecordFile(file, plan, id) {
+    if (!plan.byRecord)
+        return file;
+    // The id as the API gives it, case kept: ids are case-sensitive (lqgwUkXlBw).
+    const slot = (id ?? crypto.randomBytes(4).toString('hex')).replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+/, '') || crypto.randomBytes(4).toString('hex');
+    const named = file.replace(ID_SLOT, slot);
+    if (plan.overwrite || !fs.existsSync(named))
+        return named;
+    const ext = path.extname(named);
+    return `${named.slice(0, -ext.length || undefined)}-${crypto.randomBytes(3).toString('hex')}${ext}`;
+}
 /** What a dry run says about the file: where it would go and whether one is there. */
 export function describePlan(plan) {
     const files = plan.fixed || plan.format ? [plan.file] : [`${plan.file}.env`, `${plan.file}.json`];

package/package.json

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