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

package/README.md

@@ -34,7 +34,7 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 | `c11r auth login [--client-id] [--secret-file] [--keep-file]` | The human's own Commerce Layer login, from their Provisioning API application. See below. |
 | `c11r auth logout`, `auth switch <slug> [--global]` | Forgetting the login; the organization commands act on. |
 
-A loop policy allows verbs: a bare verb is the skill's own noun (`approve`), `<noun>.<verb>` another Manage noun's verb on the same item (`payments.capture`). Verbs that delete or return money are never open to a policy.
+A loop runs a skill a Manage noun's schema names in `loop.skill` (`manage-orders`, `manage-payments`, `playbook-mail-to-order` for carts); create and update refuse any other skill, and any verb that loop does not list, with the allowed values. A loop policy allows verbs: a bare verb is the skill's own noun (`approve`), `<noun>.<verb>` another Manage noun's verb on the same item (`payments.capture`). Verbs that delete or return money are never open to a policy.
 
 ## Login, organization tokens and secrets
 
@@ -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/builtins/loops.js

@@ -4,8 +4,9 @@
 // schedules the agent repeats it every `every`.
 //
 // A policy allows verbs: a bare verb is the skill's own noun (approve), <noun>.<verb> another
-// Manage noun's verb on the same item (payments.capture). Each must be in the noun's schema
-// loop.verbs; the API checks again on every pass.
+// Manage noun's verb on the same item (payments.capture). The skill must be one a Manage noun's
+// schema names in loop.skill (a noun's own skill is not always its loop's: carts loops run
+// playbook-mail-to-order), and each verb in that loop.verbs; the API checks again on every pass.
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
@@ -13,11 +14,11 @@ import { projectDir } from '../config.js';
 import { CliError, closest, fail, fixWith } from '../errors.js';
 import { envelope } from '../http.js';
 import { parseSchema } from '../schema.js';
-import { apiSchema } from '../schemas.js';
+import { apiNouns, apiSchema } from '../schemas.js';
 const NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
 const EVERY = /^[1-9]\d*(m|h|d)$/;
 const policyFlags = (required) => [
-    { name: 'skill', type: 'string', required, description: 'The Manage skill or playbook the loop runs, as in manage-orders.' },
+    { 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: '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.' },
@@ -166,24 +167,45 @@ function maxTotal(items) {
         return [ccy, amount(n)];
     }));
 }
-/** The policy's verbs against the skill noun's schema; a playbook is checked by the API at the first pass. */
+/**
+ * The skill and the policy's verbs against the same source loops run uses: each noun schema's loop,
+ * { skill, verbs }. A skill no schema's loop names is refused with the ones that are, and so is a
+ * 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' });
-    if (!def.skill.startsWith('manage-'))
-        return [{ code: 'policy_unchecked', message: `${def.skill} is not a Manage skill: the API checks its policy at the first pass.` }];
-    const noun = def.skill.slice('manage-'.length);
-    const schema = await apiSchema(noun, []);
-    const allowed = schema.loop?.verbs ?? [];
-    if (!allowed.length)
-        fail('policy_forbidden', `No loop acts on ${noun}: its schema has no loop.`, { path: 'skill' });
+    const skills = await loopSkills();
+    const allowed = skills.get(def.skill);
+    if (!allowed) {
+        const names = [...skills.keys()].sort();
+        fail('invalid_value', `--skill ${def.skill} runs no loop. A loop runs ${names.length ? names.join(', ') : 'no skill yet'}.`, {
+            path: 'skill',
+            did_you_mean: closest(def.skill, names),
+            details: { values: names },
+            next_step: fixWith('c11r loops create --help'),
+        });
+    }
     for (const verb of def.policy.allow) {
-        if (!allowed.includes(verb)) {
-            fail('policy_forbidden', `A ${def.skill} loop may not allow ${verb}. It may allow ${allowed.join(', ')}.`, { path: 'allow', did_you_mean: closest(verb, allowed), details: { loopable: allowed }, next_step: fixWith(`c11r schema ${noun}`) });
+        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}`) });
         }
     }
     return [];
 }
+/** The skills a loop can run, from the schemas of the nouns that have a loop: skill to its noun and verbs. */
+async function loopSkills() {
+    const nouns = (await apiNouns()).filter((n) => n.group === 'manage' && n.served !== false);
+    const schemas = await Promise.all(nouns.map((n) => apiSchema(n.noun, []).catch(() => null)));
+    const out = new Map();
+    for (const s of schemas) {
+        if (!s?.loop?.skill)
+            continue;
+        const seen = out.get(s.loop.skill);
+        out.set(s.loop.skill, { noun: seen?.noun ?? s.noun, verbs: [...new Set([...(seen?.verbs ?? []), ...s.loop.verbs])] });
+    }
+    return out;
+}
 async function remove(run, name, file) {
     one(file, name);
     if (run.globals.dryRun)

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';
@@ -28,7 +28,7 @@ export const sandbox = {
                 live: false,
                 body: [
                     { name: 'name', type: 'string', description: 'The organization name; without it, an invented one. A name starting zztest marks a test organization.' },
-                    { name: 'seed', type: 'boolean', description: 'Loads the demo dataset: two markets, six products, shipping and a test payment method, enough to place a test order at once.' },
+                    { name: 'seed', type: 'boolean', description: 'Loads the demo dataset: two markets, six products, shipping and a manual payment setting (Wire transfer), enough to place a test order at once.' },
                 ],
                 effect: 'Creates a sandbox, stores its token on this machine (never printed) and links this folder to it with .c11r.json. With --seed it answers once the seed is applied, in about 20 seconds.',
             },
@@ -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/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.2",
+  "version": "1.0.0-dev.4",
   "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": [