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

package/dist/config.js

@@ -0,0 +1,238 @@
+// What the CLI keeps on the machine, and which organization a command acts on.
+//
+// Tokens live only in ~/.config/c11r/credentials.json (XDG_CONFIG_HOME respected), mode 600,
+// keyed by organization slug. A token is printed never: only its hint.
+//
+// A project folder links to its organization with .c11r.json, { "org": "<slug>" }: no secret,
+// safe to commit, found by walking up from the current folder like .git. The project folder is
+// the one with .c11r.json, else the nearest with store.yml or loops.yml, else the current one.
+//
+// The organization: --org, then C11R_ORG, then .c11r.json, then the stored one when exactly one
+// is stored. With several stored and nothing naming one, the command stops and names them.
+// C11R_TOKEN, for CI, is used as is, whatever is stored.
+//
+// Every stored token records the host that issued it: an organization token and a cancel token
+// the API base (api_url), the login the auth endpoint (auth_url). An entry is used, listed and
+// forgotten only while that base is the one in effect, so a token never goes to a host it was not
+// issued by. An entry that records no host is not used, and goes at the next write.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fail, fixWith } from './errors.js';
+import { apiUrl } from './http.js';
+export const LINK_FILE = '.c11r.json';
+export function credentialsFile() {
+    const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    return path.join(base, 'c11r', 'credentials.json');
+}
+function readCredentials() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(credentialsFile(), 'utf8'));
+        return { ...raw, orgs: raw.orgs && typeof raw.orgs === 'object' ? raw.orgs : {} };
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { orgs: {} };
+        fail('invalid_config', `${credentialsFile()} cannot be read: ${e.message}.`);
+    }
+}
+function writeCredentials(c) {
+    const file = credentialsFile();
+    // An entry that records no issuing host is never used: it is not kept either.
+    c.orgs = Object.fromEntries(Object.entries(c.orgs).filter(([, o]) => o?.api_url));
+    if (c.login && !c.login.auth_url)
+        delete c.login;
+    if (c.bookings)
+        c.bookings = Object.fromEntries(Object.entries(c.bookings).filter(([, b]) => b?.api_url));
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    // Written aside then renamed, so a crash never leaves half a file; 600 from the start.
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(c, null, 2) + '\n', { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, file);
+}
+export const DEFAULT_AUTH_URL = 'https://auth.commercelayer.io/oauth/token';
+export const authUrl = () => process.env.C11R_AUTH_URL || DEFAULT_AUTH_URL;
+const norm = (u) => u.replace(/\/+$/, '');
+/** True when an entry was issued by the API base in effect; one that records none never is. */
+const fromApi = (e) => !!e?.api_url && norm(e.api_url) === norm(apiUrl());
+const fromAuth = (e) => !!e?.auth_url && norm(e.auth_url) === norm(authUrl());
+/** The organization tokens issued by the API in effect. */
+export function storedOrgs() {
+    return Object.fromEntries(Object.entries(readCredentials().orgs).filter(([, o]) => fromApi(o)));
+}
+export function storeOrg(slug, org) {
+    const c = readCredentials();
+    c.orgs[slug] = { ...org, api_url: apiUrl() };
+    writeCredentials(c);
+}
+/** After a reset: the same token, a new organization. */
+export function renameOrg(from, to, patch = {}) {
+    const c = readCredentials();
+    const entry = c.orgs[from];
+    if (!fromApi(entry))
+        return;
+    delete c.orgs[from];
+    c.orgs[to] = { ...entry, ...patch };
+    writeCredentials(c);
+}
+export function forgetOrg(slug) {
+    const c = readCredentials();
+    if (!fromApi(c.orgs[slug]))
+        return;
+    delete c.orgs[slug];
+    writeCredentials(c);
+}
+/** The login minted by the auth endpoint in effect. */
+export function storedLogin() {
+    const l = readCredentials().login;
+    return l && fromAuth(l) ? l : null;
+}
+/** Stores the login for the auth endpoint in effect; null forgets it, only if it is that one's. */
+export function storeLogin(login) {
+    const c = readCredentials();
+    if (login)
+        c.login = { ...login, auth_url: authUrl() };
+    else if (fromAuth(c.login))
+        delete c.login;
+    else
+        return;
+    writeCredentials(c);
+}
+export function defaultOrg() {
+    return readCredentials().default_org ?? null;
+}
+export function setDefaultOrg(org) {
+    const c = readCredentials();
+    if (org)
+        c.default_org = org;
+    else
+        delete c.default_org;
+    writeCredentials(c);
+}
+export function outWritten(org) {
+    return Boolean(readCredentials().out_written?.[org]);
+}
+export function markOutWritten(org, written) {
+    const c = readCredentials();
+    const all = { ...(c.out_written ?? {}) };
+    if (written === Boolean(all[org]))
+        return;
+    if (written)
+        all[org] = true;
+    else
+        delete all[org];
+    c.out_written = all;
+    writeCredentials(c);
+}
+export function storedBooking(id) {
+    const b = readCredentials().bookings?.[id];
+    return b && fromApi(b) ? b : null;
+}
+export function storeBooking(id, booking) {
+    const c = readCredentials();
+    const all = { ...(c.bookings ?? {}) };
+    if (booking)
+        all[id] = { ...booking, api_url: apiUrl() };
+    else if (fromApi(all[id]))
+        delete all[id];
+    else
+        return;
+    c.bookings = all;
+    writeCredentials(c);
+}
+/** The last four characters, as the API shows them. */
+export const hintOf = (token) => `${token.slice(0, 4)}...${token.slice(-4)}`;
+/** The nearest folder, from the current one up, that holds one of the files. */
+function findUp(names, from = process.cwd()) {
+    let dir = path.resolve(from);
+    for (;;) {
+        if (names.some((n) => fs.existsSync(path.join(dir, n))))
+            return dir;
+        const up = path.dirname(dir);
+        if (up === dir)
+            return null;
+        dir = up;
+    }
+}
+/** The project folder: where .c11r.json, store.yml and loops.yml go. */
+export function projectDir() {
+    return findUp([LINK_FILE]) ?? findUp(['store.yml', 'loops.yml']) ?? process.cwd();
+}
+export function readLink() {
+    const dir = findUp([LINK_FILE]);
+    if (!dir)
+        return null;
+    const file = path.join(dir, LINK_FILE);
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        fail('invalid_config', `${file} is not valid JSON: ${e.message}.`, { path: LINK_FILE });
+    }
+    const org = raw?.org;
+    if (typeof org !== 'string' || !org)
+        fail('invalid_config', `${file} has no org.`, { path: `${LINK_FILE}.org` });
+    return { file, org };
+}
+/** Links the project folder to the organization; returns the file and the org it linked before. */
+export function writeLink(org) {
+    const existing = readLink();
+    const file = existing?.file ?? path.join(process.cwd(), LINK_FILE);
+    fs.writeFileSync(file, JSON.stringify({ org }, null, 2) + '\n');
+    return { file, previous: existing && existing.org !== org ? existing.org : null };
+}
+/** Removes the link, only when it names this organization. */
+export function removeLink(org) {
+    const link = readLink();
+    if (!link || link.org !== org)
+        return null;
+    fs.rmSync(link.file);
+    return link.file;
+}
+/** Which organization, and which token. Never throws: callers decide what a problem means. */
+export function resolveOrg(flag) {
+    if (process.env.C11R_TOKEN)
+        return { org: flag ?? (process.env.C11R_ORG || null), source: 'token_env', token: process.env.C11R_TOKEN, problem: null };
+    const orgs = storedOrgs();
+    const named = [
+        [flag, 'flag'],
+        [process.env.C11R_ORG || undefined, 'env'],
+    ];
+    let link = null;
+    try {
+        link = readLink();
+    }
+    catch (e) {
+        return { org: null, source: null, token: null, problem: { code: 'invalid_config', message: e.message } };
+    }
+    named.push([link?.org, 'link']);
+    named.push([defaultOrg() ?? undefined, 'default']);
+    for (const [org, source] of named) {
+        if (!org)
+            continue;
+        const stored = orgs[org];
+        if (stored)
+            return { org, source, token: stored.token, problem: null };
+        const where = source === 'flag' ? '--org' : source === 'env' ? 'C11R_ORG' : source === 'default' ? 'The default organization (c11r auth switch --global)' : link.file;
+        return { org, source, token: null, problem: { code: 'no_credentials', message: `${where} names ${org}, and this machine has no token for it.`, orgs: Object.keys(orgs) } };
+    }
+    const slugs = Object.keys(orgs);
+    if (slugs.length === 1)
+        return { org: slugs[0], source: 'only_stored', token: orgs[slugs[0]].token, problem: null };
+    if (slugs.length > 1)
+        return { org: null, source: null, token: null, problem: { code: 'org_required', message: `This machine has tokens for ${slugs.length} organizations (${slugs.join(', ')}), and nothing names one: no --org, no C11R_ORG, no ${LINK_FILE}.`, orgs: slugs } };
+    return { org: null, source: null, token: null, problem: null };
+}
+/** The token for a command that needs an organization; a problem becomes its error. */
+export function raiseProblem(r, line) {
+    if (!r.problem)
+        return;
+    const { code, message, orgs } = r.problem;
+    if (code === 'org_required')
+        fail('org_required', message, { path: 'org', next_step: fixWith(`${line} --org ${orgs[0]}`), details: { orgs } }, 'usage');
+    if (code === 'no_credentials')
+        fail('no_credentials', message, { path: 'org', next_step: { action: 'none' }, details: { stored: orgs } }, 'auth');
+    fail(code, message);
+}

package/dist/confirm.js

@@ -0,0 +1,56 @@
+// Confirmation for destructive verbs. --yes skips it. With a terminal, it asks on stderr and
+// reads one line. With no terminal (an agent, a pipe, a schedule) it never waits: it fails with
+// confirmation_required, and the agent asks the human, then repeats the command with --yes.
+import readline from 'node:readline';
+import { fail } from './errors.js';
+export const terminal = {
+    get interactive() {
+        return Boolean(process.stdin.isTTY && process.stderr.isTTY) && process.env.C11R_NO_PROMPT !== '1';
+    },
+    ask(question) {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        return new Promise((resolve) => {
+            // Resolve before close(): close emits at once, and its handler would answer '' first.
+            rl.question(question, (answer) => {
+                resolve(answer);
+                rl.close();
+            });
+            // Ctrl-D or a closed stdin is a no.
+            rl.on('close', () => resolve(''));
+        });
+    },
+    askSecret(question) {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        // Nothing typed is echoed: only the question is written.
+        const out = rl;
+        let asked = false;
+        out._writeToOutput = (s) => {
+            if (!asked) {
+                process.stderr.write(s);
+                asked = true;
+            }
+        };
+        return new Promise((resolve) => {
+            rl.question(question, (answer) => {
+                process.stderr.write('\n');
+                resolve(answer);
+                rl.close();
+            });
+            rl.on('close', () => resolve(''));
+        });
+    },
+};
+export async function confirm(action, command, opts) {
+    if (opts.yes)
+        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` },
+        });
+    }
+    const answer = (await p.ask(`${action}. Go ahead? [y/N] `)).trim().toLowerCase();
+    if (answer !== 'y' && answer !== 'yes')
+        fail('confirmation_declined', `${action}: not confirmed, nothing was changed.`);
+}

package/dist/engine.js

@@ -0,0 +1,205 @@
+// The grammar engine. c11r <noun> <verb> [id] [--field value ...] becomes, in order: the noun's
+// schema (built in, or from the API), the verb, the id and the typed values, the checks the CLI
+// can make before sending (required flags, an organization to act on), confirmation for a
+// 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 { confirm, terminal } from './confirm.js';
+import { CliError, closest, fail, fixWith } from './errors.js';
+import { indexHelp, nounHelp, verbHelp } from './help.js';
+import { envelope, request } from './http.js';
+import { readInputs } from './inputs.js';
+import { hasLogin, loginToken } from './login.js';
+import { resourceRequest } from './resources.js';
+import { describePlan, OUT_NOT_TRACKED, planSecret, removeRecordFiles, writeSecret } from './secrets.js';
+import { verbOf } from './schema.js';
+import { apiNouns, apiSchema } from './schemas.js';
+import { VERSION } from './version.js';
+export async function execute(argv, opts = {}) {
+    const cmd = parseCommand(argv);
+    const builtins = opts.builtins ?? {};
+    if (cmd.globals.version && !cmd.noun)
+        return envelope({ version: VERSION });
+    if (!cmd.noun || cmd.noun === 'help')
+        return help(cmd, opts);
+    if (cmd.noun === 'schema')
+        return schemaOf(cmd, builtins);
+    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);
+    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.
+    if (verb.refused) {
+        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);
+    ext?.prepare?.(verb, parsed);
+    // Files first, so a required document given with --file counts; a secret is typed only once
+    // the command is otherwise complete.
+    await readInputs(schema.noun, verb, parsed, null);
+    check(schema, verb, parsed);
+    await readInputs(schema.noun, verb, parsed, opts.prompter ?? terminal);
+    const line = ['c11r', ...argv.filter((a) => a !== '--yes' && a !== '-y')].map(quote).join(' ');
+    const org = resolveOrg(cmd.globals.org);
+    const login = hasLogin();
+    // The bearer, from the schema (contract section 23). An organization token for the organization
+    // nouns, the login for the Provisioning ones; credentials take the login when there is one and
+    // the organization token is not a sandbox's.
+    let bearer = verb.credential === 'login' ? 'login' : verb.credential === 'organization|login' ? (login && !org.token?.startsWith('sbx_') ? 'login' : 'organization') : verb.credential === 'none' ? 'none' : 'organization';
+    // members and roles with an organization token and no login: the API says what is needed (a
+    // claim for a sandbox, a login for a claimed organization). organizations and auth stop here.
+    if (bearer === 'login' && !login && org.token && schema.noun !== 'organizations' && schema.noun !== 'auth')
+        bearer = 'organization';
+    // A verb that needs an organization token: say which is missing before the API does.
+    if (bearer === 'organization' && verb.state !== 'none' && !org.token) {
+        if (org.problem?.code === 'no_credentials' && login && org.org) {
+            fail('no_credentials', `${org.problem.message} The login can make one: c11r organizations connect ${org.org}.`, { path: 'org', next_step: { action: 'fix_request', command: `c11r organizations connect ${org.org}` } }, 'auth');
+        }
+        raiseProblem(org, line);
+        fail('state_required', `c11r ${schema.noun} ${verb.name} needs a sandbox, and this machine has none.`, { required_state: 'sandbox', next_step: { action: 'create_sandbox', command: 'c11r sandbox create' } });
+    }
+    // The login names its organization with ?org=, from --org, C11R_ORG, .c11r.json or the default:
+    // never a guess from the only token stored, which may be a sandbox the login does not reach.
+    const loginOrg = org.source && org.source !== 'only_stored' ? org.org : null;
+    if (cmd.globals.live && !verb.live) {
+        fail('state_required', `c11r ${schema.noun} ${verb.name} does not run in live mode.`, { required_state: 'claimed', path: 'live', next_step: fixWith(line.replace(/\s--live\b/, '')) });
+    }
+    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) {
+        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 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);
+    const run = {
+        globals: cmd.globals,
+        schema,
+        verb,
+        parsed,
+        line,
+        org,
+        ctx,
+        bearer,
+        prompter: opts.prompter,
+        async send(req) {
+            try {
+                return await sendOnce(req);
+            }
+            catch (e) {
+                // A login token Commerce Layer no longer takes: mint a new one, once.
+                if (!(e instanceof CliError && e.code === 'login_required') || !login)
+                    throw e;
+                if (bearer === 'login' && process.env.C11R_PROVISIONING_TOKEN)
+                    throw e;
+                if (bearer === 'organization' && verb.credential !== 'organization|login')
+                    throw e;
+                ctx.token = await loginToken({ fresh: bearer === 'login' });
+                run.bearer = 'login';
+                if (loginOrg && schema.noun !== 'organizations')
+                    Object.assign(orgQuery, { org: loginOrg });
+                return sendOnce(req);
+            }
+        },
+    };
+    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);
+}
+/**
+ * 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.
+ */
+function filesGone(r, run) {
+    if (run.verb.name !== 'delete' || run.globals.dryRun || !run.org.org)
+        return r;
+    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);
+    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. */
+function secretOf(r, run, plan) {
+    const data = r.data;
+    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 });
+        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)
+        return { ...r, data: { ...(data && typeof data === 'object' ? data : { result: data }), secret_file: describePlan(plan) } };
+    return r;
+}
+/** What the command needs before anything is sent: the id, the required flags, known --data keys. */
+function check(schema, verb, parsed) {
+    const cmd = `c11r ${schema.noun} ${verb.name}`;
+    const alt = verb.idAlternative;
+    const altGiven = alt.filter((k) => parsed.values[k] !== undefined);
+    if (alt.length && parsed.id !== undefined && altGiven.length) {
+        fail('invalid_value', `${cmd} takes the id or ${alt.map(toFlag).join(' with ')}, not both.`, { path: altGiven[0], next_step: fixWith(`${cmd} --help`) });
+    }
+    if (verb.id && parsed.id === undefined && altGiven.length < Math.max(alt.length, 1)) {
+        const accepts = schema.id?.accepts.length ? ` (or its ${schema.id.accepts.filter((a) => a !== 'id').join(' or ')})` : '';
+        const instead = alt.length ? `, or ${alt.map(toFlag).join(' with ')}` : '';
+        const missing = alt.filter((k) => parsed.values[k] === undefined);
+        fail('missing_id', `${cmd} needs the id${accepts} of one of the ${schema.noun}${instead}.`, {
+            path: altGiven.length ? missing[0] : 'id',
+            ...(alt.length ? { details: { id_alternative: alt.map(toFlag) } } : {}),
+            next_step: fixWith(`c11r ${schema.noun} list`),
+        });
+    }
+    const keys = Object.keys(verb.flags);
+    const fromFiles = new Set(Object.values(verb.flags).flatMap((f) => (f.input ? [f.input.target] : [])));
+    for (const key of Object.keys(parsed.values)) {
+        if (!verb.flags[key] && !fromFiles.has(key))
+            fail('unknown_field', `${cmd} has no field ${key}.`, { path: key, did_you_mean: closest(key, keys), details: { flags: keys.map(toFlag) } });
+    }
+    const missing = Object.entries(verb.flags)
+        .filter(([k, f]) => f.required && parsed.values[k] === undefined)
+        .map(([k]) => k);
+    if (missing.length)
+        fail('missing_argument', `${cmd} needs ${missing.map(toFlag).join(', ')}.`, { path: missing[0], details: { missing: missing.map(toFlag) }, next_step: fixWith(`${cmd} --help`) });
+    if (verb.name === 'update' && !Object.keys(parsed.values).length)
+        fail('no_fields', `${cmd} needs at least one field to change.`, { details: { flags: keys.map(toFlag) }, next_step: fixWith(`${cmd} --help`) });
+}
+async function help(cmd, opts) {
+    const builtins = opts.builtins ?? {};
+    // c11r help <noun> [verb] is c11r <noun> [verb] --help.
+    if (cmd.noun === 'help' && cmd.verb)
+        return execute([cmd.verb, ...cmd.rest.filter((a) => !a.startsWith('-')).slice(0, 1), '--help'], opts);
+    const own = [
+        ...Object.values(builtins).map((b) => ({ noun: b.schema.noun, description: b.schema.description, ...(b.schema.doc.group ? { group: b.schema.doc.group } : {}), ...(b.schema.skill ? { skill: b.schema.skill } : {}) })),
+        { noun: 'schema', description: 'c11r schema <noun> returns a noun\'s fields, filters and verbs, and what a loop policy may automate.' },
+        { noun: 'help', description: 'c11r help [noun [verb]] describes the CLI, a noun or a verb.' },
+    ];
+    try {
+        const api = (await apiNouns()).filter((n) => !builtins[n.noun]);
+        return envelope(indexHelp(own, api));
+    }
+    catch (e) {
+        return envelope(indexHelp(own, null), { warnings: [{ code: 'nouns_incomplete', message: `Only the built-in nouns are listed: ${e.message}` }] });
+    }
+}
+async function schemaOf(cmd, builtins) {
+    if (!cmd.verb)
+        fail('missing_argument', 'c11r schema needs a noun, as in c11r schema markets.', { next_step: fixWith('c11r help') });
+    if (cmd.rest.length)
+        fail('unexpected_argument', `c11r schema takes one noun, not ${cmd.rest.join(' ')}.`);
+    return envelope((builtins[cmd.verb]?.schema ?? (await apiSchema(cmd.verb, Object.keys(builtins)))).doc);
+}
+const quote = (a) => (/^[\w@%+=:,./#-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`);

package/dist/errors.js

@@ -0,0 +1,146 @@
+// Every failure is one JSON object on stdout, { error, state }, in the API contract's shape
+// (section 3), whether the API or the CLI raised it, and a stable exit code. The code is the
+// contract with the agent: it never changes meaning. next_step says what would make the command
+// work, for the agent to propose to the human; the agent does not retry the failed call.
+/**
+ * Exit codes. Stable: an agent or a script can branch on them.
+ * 0 success, 1 unexpected, 2 usage, 3 confirmation needed, 4 state or plan needed,
+ * 5 not found, 6 refused by the API, 7 API unreachable or failing, 8 authentication.
+ */
+export const EXIT = {
+    ok: 0,
+    unexpected: 1,
+    usage: 2,
+    confirmation: 3,
+    requirement: 4,
+    not_found: 5,
+    rejected: 6,
+    unavailable: 7,
+    auth: 8,
+};
+/** The exit kind of every code the CLI raises, and of the contract's codes (section 3). */
+const KIND = {
+    // The CLI's own, before anything is sent.
+    unknown_noun: 'usage',
+    unknown_verb: 'usage',
+    unknown_field: 'usage',
+    invalid_value: 'usage',
+    missing_value: 'usage',
+    missing_argument: 'usage',
+    missing_id: 'usage',
+    unexpected_argument: 'usage',
+    no_fields: 'usage',
+    confirmation_declined: 'confirmation',
+    invalid_response: 'unavailable',
+    schema_unavailable: 'unavailable',
+    api_unreachable: 'unavailable',
+    invalid_config: 'usage',
+    secret_required: 'usage',
+    insecure_file: 'usage',
+    // A secret the API answered once and the disk refused: nothing else to do but say so.
+    secret_not_written: 'unexpected',
+    // The contract's.
+    confirmation_required: 'confirmation',
+    state_required: 'requirement',
+    plan_required: 'requirement',
+    expired: 'requirement',
+    limit_reached: 'requirement',
+    not_found: 'not_found',
+    invalid_argument: 'rejected',
+    invalid_transition: 'rejected',
+    conflict: 'rejected',
+    dependency_missing: 'rejected',
+    commercelayer_refused: 'rejected',
+    policy_forbidden: 'rejected',
+    not_supported: 'rejected',
+    rate_limited: 'unavailable',
+    commercelayer_busy: 'unavailable',
+    commercelayer_unavailable: 'unavailable',
+    api_error: 'unavailable',
+    unauthorized: 'auth',
+    login_required: 'auth',
+    no_credentials: 'auth',
+    forbidden: 'rejected',
+    claim_not_found: 'not_found',
+};
+/** For an API error whose code the CLI does not know: from the HTTP status. */
+export function kindOfStatus(status) {
+    if (status === 401)
+        return 'auth';
+    if (status === 403 || status === 410)
+        return 'requirement';
+    if (status === 404)
+        return 'not_found';
+    if (status === 428)
+        return 'confirmation';
+    if (status === 429 || status >= 500)
+        return 'unavailable';
+    if (status >= 400)
+        return 'rejected';
+    return 'unexpected';
+}
+export class CliError extends Error {
+    body;
+    kind;
+    /** The API's state envelope, when the error came from the API. */
+    state;
+    constructor(body, kind, state = null) {
+        super(body.message);
+        this.body = body;
+        this.kind = kind ?? KIND[body.code] ?? 'unexpected';
+        this.state = state;
+    }
+    get code() {
+        return this.body.code;
+    }
+    get exitCode() {
+        return EXIT[this.kind];
+    }
+}
+export function errorBody(code, message, extra = {}) {
+    const { next_step, required_state = null, required_plan = null, missing = null, path = null, ...rest } = extra;
+    return {
+        code,
+        message,
+        required_state,
+        required_plan,
+        missing,
+        path,
+        next_step: next_step ? { action: next_step.action, command: next_step.command ?? null, url: next_step.url ?? null } : null,
+        ...rest,
+    };
+}
+export function fail(code, message, extra = {}, kind) {
+    throw new CliError(errorBody(code, message, extra), kind);
+}
+/** A next step that fixes the command: the command to look at, or to run instead. */
+export const fixWith = (command) => ({ action: 'fix_request', command });
+/** Any thrown value as a CliError: unexpected ones keep their message. */
+export function asCliError(e) {
+    if (e instanceof CliError)
+        return e;
+    return new CliError(errorBody('unexpected', `c11r failed unexpectedly: ${e instanceof Error ? e.message : String(e)}. This is a bug in c11r.`), 'unexpected');
+}
+/** Close matches by edit distance, for did_you_mean. */
+export function closest(word, candidates, max = 3) {
+    const scored = [...candidates].map((c) => ({ c, d: distance(word.toLowerCase(), c.toLowerCase()) }));
+    const limit = Math.max(2, Math.floor(word.length / 3));
+    return scored
+        .filter((s) => s.d <= limit || s.c.startsWith(word) || word.startsWith(s.c))
+        .sort((a, b) => a.d - b.d || (a.c < b.c ? -1 : 1))
+        .slice(0, max)
+        .map((s) => s.c);
+}
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = tmp;
+        }
+    }
+    return row[b.length];
+}