@commercelayer/agent-cli 0.8.0 → 1.0.0-dev.0

package/dist/config.js

@@ -0,0 +1,211 @@
+// 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.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fail, fixWith } from './errors.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();
+    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 function storedOrgs() {
+    return readCredentials().orgs;
+}
+export function storeOrg(slug, org) {
+    const c = readCredentials();
+    c.orgs[slug] = org;
+    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 (!entry)
+        return;
+    delete c.orgs[from];
+    c.orgs[to] = { ...entry, ...patch };
+    writeCredentials(c);
+}
+export function forgetOrg(slug) {
+    const c = readCredentials();
+    if (!c.orgs[slug])
+        return;
+    delete c.orgs[slug];
+    writeCredentials(c);
+}
+export function storedLogin() {
+    return readCredentials().login ?? null;
+}
+export function storeLogin(login) {
+    const c = readCredentials();
+    if (login)
+        c.login = login;
+    else
+        delete c.login;
+    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) {
+    return readCredentials().bookings?.[id] ?? null;
+}
+export function storeBooking(id, booking) {
+    const c = readCredentials();
+    const all = { ...(c.bookings ?? {}) };
+    if (booking)
+        all[id] = booking;
+    else
+        delete all[id];
+    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,173 @@
+// 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 { raiseProblem, resolveOrg } from './config.js';
+import { confirm } 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 { hasLogin, loginToken } from './login.js';
+import { resourceRequest } from './resources.js';
+import { describePlan, planSecret, 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);
+    check(schema, verb, parsed);
+    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 secretOf(r, run, secretPlan);
+}
+/** 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, 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}`;
+    if (verb.id && parsed.id === undefined) {
+        const accepts = schema.id?.accepts.length ? ` (or its ${schema.id.accepts.filter((a) => a !== 'id').join(' or ')})` : '';
+        fail('missing_id', `${cmd} needs the id${accepts} of one of the ${schema.noun}.`, { path: 'id', next_step: fixWith(`c11r ${schema.noun} list`) });
+    }
+    const keys = Object.keys(verb.flags);
+    for (const key of Object.keys(parsed.values)) {
+        if (!verb.flags[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];
+}

package/dist/help.js

@@ -0,0 +1,78 @@
+// Help, as JSON in the envelope like everything else. It follows the conversational rule: it says
+// what a command does and what it returns, never that a human should run something. The agent
+// reads it and offers to do the work.
+import { toFlag } from './argv.js';
+import { EXIT } from './errors.js';
+export const USAGE = 'c11r <noun> <verb> [id] [--field value ...]';
+export const GLOBAL_FLAG_HELP = {
+    '--json': 'Output as JSON. The default, and the only format: one object on stdout, { data, state, warnings, next } or { error, state }.',
+    '--dry-run': 'On a write, the API checks everything and says what would change, and changes nothing. Reads ignore it.',
+    '--yes': 'Confirms a destructive verb in advance. Without it a destructive verb asks in the terminal, or, with no terminal, stops with confirmation_required.',
+    '--org <slug>': 'The organization to act on, by its stored token. Without it: C11R_ORG, then the folder\'s .c11r.json, then the only stored organization.',
+    '--live': 'Acts on live data, on a claimed organization. Without it every command works in test mode.',
+    '--help': 'Describes the noun or verb it follows, from its schema.',
+};
+export const EXIT_CODE_HELP = {
+    [EXIT.ok]: 'done',
+    [EXIT.unexpected]: 'unexpected failure, a bug in c11r',
+    [EXIT.usage]: 'the command is not valid: unknown noun, verb or flag, a bad value, or no organization named',
+    [EXIT.confirmation]: 'a destructive verb needs confirmation (--yes)',
+    [EXIT.requirement]: 'the organization needs another state or plan, has expired, or reached a limit',
+    [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',
+};
+export function indexHelp(builtins, api) {
+    return {
+        usage: USAGE,
+        description: 'c11r is the Commerce Layer CLI for coding agents. Every answer, errors included, is one JSON object on stdout.',
+        nouns: [...builtins, ...(api ?? [])].sort((a, b) => (a.noun < b.noun ? -1 : 1)),
+        standard_verbs: 'list, get, create, update, delete. Nouns with a state machine add their own verbs.',
+        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01; in takes values separated by commas). A dotted flag sets part of an object (--customer.email). An array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
+        global_flags: GLOBAL_FLAG_HELP,
+        exit_codes: EXIT_CODE_HELP,
+        more: 'c11r <noun> --help describes a noun and its verbs; c11r <noun> <verb> --help a verb and its flags; c11r schema <noun> returns the full schema.',
+    };
+}
+export function nounHelp(s) {
+    return {
+        noun: s.noun,
+        description: s.description,
+        ...(s.skill ? { skill: s.skill } : {}),
+        ...(s.id?.accepts.length ? { id: `The id, or ${s.id.accepts.filter((a) => a !== 'id').join(' or ')}${s.id.example ? `, as in ${s.id.example}` : ''}.` } : {}),
+        verbs: Object.values(s.verbs).map((v) => ({ verb: v.name, usage: usageOf(s.noun, v), description: v.description, ...(v.destructive ? { destructive: true } : {}), ...(v.loopable ? { loopable: true } : {}), ...(v.refused ? { served: false, refused_by: v.refused.by } : {}) })),
+        ...(s.waiting ? { waiting: s.waiting } : {}),
+        ...(s.loop ? { loop: s.loop } : {}),
+    };
+}
+export function verbHelp(s, v) {
+    return {
+        usage: usageOf(s.noun, v),
+        description: v.description,
+        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.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)),
+    };
+}
+function flagHelp(key, f) {
+    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 ? { required: true } : {}),
+        ...(f.values ? { values: f.values } : {}),
+        ...(f.filter ? { filter: f.filter.op } : {}),
+        ...(f.description ? { description: f.description } : {}),
+    };
+}
+export function usageOf(noun, v) {
+    const required = Object.entries(v.flags)
+        .filter(([, f]) => f.required)
+        .map(([k, f]) => `${toFlag(k)} <${f.type === 'enum' ? f.values?.join('|') : f.type}>`);
+    const optional = Object.values(v.flags).some((f) => !f.required);
+    return [`c11r ${noun} ${v.name}`, v.id ? '<id>' : '', ...required, optional ? '[--field value ...]' : ''].filter(Boolean).join(' ');
+}