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

package/dist/argv.js

@@ -0,0 +1,214 @@
+// c11r <noun> <verb> [id] [--field value ...], in two passes. The first takes the global flags
+// out, wherever they are, and finds the noun and the verb. The second reads the rest against the
+// verb's flags, which say whether a flag takes a value, what type it is and where it goes.
+import fs from 'node:fs';
+import { closest, fail, fixWith } from './errors.js';
+const BOOLEAN_GLOBALS = {
+    '--json': 'json',
+    '--dry-run': 'dryRun',
+    '--yes': 'yes',
+    '-y': 'yes',
+    '--live': 'live',
+    '--help': 'help',
+    '-h': 'help',
+    '--version': 'version',
+};
+export function parseCommand(argv) {
+    const globals = { json: true, dryRun: false, yes: false, live: false, help: false, version: false };
+    const bare = [];
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const [flag, inline] = splitInline(a);
+        if (BOOLEAN_GLOBALS[flag] && inline === undefined) {
+            globals[BOOLEAN_GLOBALS[flag]] = true;
+        }
+        else if (flag === '--org') {
+            const value = inline ?? argv[++i];
+            if (value === undefined || value.startsWith('--'))
+                fail('missing_value', '--org needs an organization slug.', { path: 'org' });
+            globals.org = value;
+        }
+        else if (bare.length < 2 && !a.startsWith('-') && rest.length === 0) {
+            bare.push(a);
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    return { globals, noun: bare[0], verb: bare[1], rest };
+}
+function splitInline(a) {
+    if (!a.startsWith('--'))
+        return [a, undefined];
+    const eq = a.indexOf('=');
+    return eq === -1 ? [a, undefined] : [a.slice(0, eq), a.slice(eq + 1)];
+}
+/** --price-list and --price_list are the same flag: the schema's names are snake_case. */
+const toKey = (flag) => flag.replace(/^--/, '').replace(/-/g, '_');
+export const toFlag = (key) => `--${key.replace(/_/g, '-')}`;
+/** The rest of the command, read against the verb: its id, then its flags. */
+export function parseFields(noun, verb, rest) {
+    const values = {};
+    let id;
+    const keys = Object.keys(verb.flags);
+    const cmd = `c11r ${noun} ${verb.name}`;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (!a.startsWith('--')) {
+            if (verb.id && id === undefined) {
+                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`) });
+        }
+        const [flag, inline] = splitInline(a);
+        const key = toKey(flag);
+        if (key === 'data') {
+            Object.assign(values, readData(inline ?? rest[++i]));
+            continue;
+        }
+        // A key of its own (a filter operator: created_at.gte), else part of an object (checkout.url).
+        const [top, ...sub] = verb.flags[key] ? [key] : key.split('.');
+        const spec = verb.flags[top];
+        if (!spec) {
+            fail('unknown_field', `${cmd} has no flag ${toFlag(key)}.`, {
+                path: key,
+                did_you_mean: closest(top, keys).map(toFlag),
+                details: { flags: keys.map(toFlag) },
+                next_step: fixWith(`${cmd} --help`),
+            });
+        }
+        let raw = inline;
+        if (raw === undefined) {
+            const next = rest[i + 1];
+            if (spec.type === 'boolean' && !sub.length) {
+                raw = next === 'true' || next === 'false' ? rest[++i] : 'true';
+            }
+            else {
+                if (next === undefined || /^--[a-z]/i.test(next))
+                    fail('missing_value', `${toFlag(key)} needs a value.`, { path: key });
+                raw = rest[++i];
+            }
+        }
+        if (sub.length) {
+            if (spec.type !== 'object')
+                fail('invalid_value', `${toFlag(top)} is ${spec.type}: it has no part ${sub.join('.')}.`, { path: key });
+            let target = (values[top] ??= {});
+            for (const k of sub.slice(0, -1))
+                target = (target[k] ??= {});
+            const part = sub.join('.');
+            target[sub[sub.length - 1]] = part in (spec.properties ?? {}) ? coerce(key, { type: spec.properties[part] }, raw) : raw;
+            continue;
+        }
+        const value = coerce(key, spec, raw);
+        values[top] = spec.type === 'array' ? [...(values[top] ?? []), ...value] : value;
+    }
+    return { id, values };
+}
+/** A value as its flag's type says, or invalid_value with the reason. */
+export function coerce(key, spec, raw) {
+    const invalid = (why) => fail('invalid_value', `${toFlag(key)} ${JSON.stringify(raw)} ${why}.`, { path: key, ...(spec.values ? { details: { values: spec.values } } : {}) });
+    switch (spec.type) {
+        case 'string':
+        case 'ref':
+            return raw;
+        case 'integer':
+            if (!/^-?\d+$/.test(raw.trim()))
+                invalid('is not a whole number');
+            return Number(raw);
+        case 'number':
+        case 'money':
+            // Money is in major units: 12.50.
+            if (raw.trim() === '' || !Number.isFinite(Number(raw)))
+                invalid(spec.type === 'money' ? 'is not an amount, as in 12.50' : 'is not a number');
+            return Number(raw);
+        case 'boolean':
+            if (raw !== 'true' && raw !== 'false')
+                invalid('is not true or false');
+            return raw === 'true';
+        case 'date':
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(raw) || Number.isNaN(Date.parse(raw)))
+                invalid('is not a date, as in 2026-11-30');
+            return raw;
+        case 'datetime':
+            if (Number.isNaN(Date.parse(raw)))
+                invalid('is not a date and time, as in 2026-11-30T09:00:00Z');
+            return raw;
+        case 'enum':
+            if (!spec.values?.includes(raw))
+                invalid(`is not one of ${spec.values?.join(', ')}`);
+            return raw;
+        case 'object': {
+            const v = raw.trim().startsWith('{') ? json(raw, invalid) : pairs(key, raw, spec.properties ?? {}, invalid);
+            if (!v || typeof v !== 'object' || Array.isArray(v))
+                invalid('is not a JSON object');
+            return v;
+        }
+        case 'array': {
+            const item = spec.items ?? 'string';
+            if (raw.trim().startsWith('[')) {
+                const list = json(raw, invalid);
+                if (!Array.isArray(list))
+                    invalid('is not a list');
+                return list.map((x) => (typeof x === 'string' && item !== 'string' ? coerce(key, { type: item, values: spec.values }, x) : x));
+            }
+            // One object per flag (--items sku=A,quantity=2, repeated), or scalars separated by commas.
+            if (item === 'object')
+                return [coerce(key, { type: 'object', properties: spec.properties }, raw)];
+            return raw
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean)
+                .map((x) => coerce(key, { type: item, values: spec.values }, x));
+        }
+    }
+}
+function json(raw, invalid) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return invalid('is not valid JSON');
+    }
+}
+/**
+ * sku=A,quantity=2 as { sku: 'A', quantity: 2 }, each part typed by the schema's properties.
+ * A part the schema does not type stays text: a postal code or a phone is never made a number.
+ */
+function pairs(key, raw, props, invalid) {
+    const out = {};
+    for (const part of raw.split(',')) {
+        const eq = part.indexOf('=');
+        if (eq < 1)
+            invalid('is not JSON nor key=value pairs separated by commas');
+        const name = part.slice(0, eq).trim();
+        const value = part.slice(eq + 1).trim();
+        out[name] = props[name] ? coerce(`${key}.${name}`, { type: props[name] }, value) : value;
+    }
+    return out;
+}
+/** --data '{"name": ...}' or --data @file.json: the values as one JSON object. */
+function readData(raw) {
+    if (raw === undefined)
+        fail('missing_value', '--data needs a JSON object, or @ and a file name.', { path: 'data' });
+    let text = raw;
+    if (raw.startsWith('@')) {
+        try {
+            text = fs.readFileSync(raw.slice(1), 'utf8');
+        }
+        catch (e) {
+            fail('invalid_value', `--data ${raw}: ${e.message}.`, { path: 'data' });
+        }
+    }
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        fail('invalid_value', '--data is not valid JSON.', { path: 'data' });
+    }
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        fail('invalid_value', '--data is not a JSON object.', { path: 'data' });
+    return v;
+}

package/dist/bin.js

@@ -1,182 +1,19 @@
 #!/usr/bin/env node
-// c11r: the Commerce Layer CLI for coding agents (package @commercelayer/agent-cli).
-// Arguments are a command, optional subcommand, --flags and --option values.
-// Output is always JSON; exit code 1 on an error or a failed check.
-import * as cmd from './commands.js';
-import { CliError, print } from './output.js';
-import { LATEST_HINT, NPX } from './version.js';
-const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code', '--file', '--store', '--item', '--email', '--first-name', '--last-name', '--phone', '--street', '--city', '--postal-code', '--region', '--shipping', '--category', '--min-price', '--max-price', '--status', '--payment', '--fulfillment', '--limit', '--archived', '--amount', '--carrier', '--tracking', '--tracking-url', '--since', '--until', '--by', '--company', '--line-2', '--query', '--reference', '--notes', '--language', '--source', '--channel', '--label', '--unlabel', '--move', '--currency']);
-const argv = process.argv.slice(2);
-const flags = new Set();
-const values = {};
-/** Every value of an option given more than once (--item, --code, --category), in order; values keeps the last. */
-const lists = {};
-const set = (k, v) => {
-    values[k] = v;
-    (lists[k] ??= []).push(v);
-};
-const args = [];
-for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '-f' && i + 1 < argv.length) {
-        values.file = argv[++i];
-        continue;
+// c11r: one JSON object on stdout per command, { data, state, warnings, next } or
+// { error, state }, and a stable exit code (src/errors.ts, EXIT). Retry notices go to stderr.
+import { builtins, extensions } from './builtins/index.js';
+import { execute } from './engine.js';
+import { asCliError, EXIT } from './errors.js';
+async function main() {
+    try {
+        const out = await execute(process.argv.slice(2), { builtins, extensions });
+        process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+        process.exitCode = EXIT.ok;
     }
-    if (!a.startsWith('--')) {
-        args.push(a);
-        continue;
+    catch (e) {
+        const err = asCliError(e);
+        process.stdout.write(JSON.stringify({ error: err.body, state: err.state ?? null }, null, 2) + '\n');
+        process.exitCode = err.exitCode;
     }
-    const eq = a.indexOf('=');
-    if (eq > 0)
-        set(a.slice(2, eq), a.slice(eq + 1));
-    else if (VALUE_OPTIONS.has(a) && i + 1 < argv.length && !argv[i + 1].startsWith('--'))
-        set(a.slice(2), argv[++i]);
-    else
-        flags.add(a);
 }
-const [name, sub] = args;
-async function run() {
-    if (flags.has('--version') || name === 'version')
-        return { version: cmd.VERSION, latest_hint: LATEST_HINT };
-    switch (name) {
-        case undefined:
-        case 'help':
-            return cmd.help(args.slice(1).join(' ') || undefined);
-        case 'init':
-            return cmd.init(values);
-        case 'plan':
-            return cmd.plan();
-        case 'apply':
-            return cmd.apply(flags);
-        case 'status':
-            return cmd.status();
-        case 'claim':
-            return cmd.claim();
-        case 'catalog':
-            if (sub === 'pull')
-                return cmd.catalogPull(values);
-            throw new CliError('unknown_command', `There is no command "catalog ${sub ?? ''}".`, 'Use `c11r catalog pull`.');
-        case 'storefront':
-            if (sub === 'init')
-                return cmd.storefrontInit(flags);
-            if (sub === 'publish')
-                return cmd.storefrontPublish();
-            if (sub === 'check')
-                return cmd.storefrontCheckCmd();
-            if (sub === 'inspect')
-                return cmd.storefrontInspect(args[2]);
-            throw new CliError('unknown_command', `There is no command "storefront ${sub ?? ''}".`, 'Use `c11r storefront init`, `storefront publish`, `storefront check` or `storefront inspect <url>`.');
-        case 'promotions':
-            if (sub === 'list')
-                return cmd.promotionsList();
-            if (sub === 'show')
-                return cmd.promotionsShow(args[2]);
-            if (sub === 'create')
-                return cmd.promotionsCreate(values);
-            if (sub === 'update')
-                return cmd.promotionsUpdate(args[2], values);
-            if (sub === 'enable' || sub === 'disable')
-                return cmd.promotionsEnable(args[2], sub === 'enable');
-            if (sub === 'delete')
-                return cmd.promotionsDelete(args[2]);
-            throw new CliError('unknown_command', `There is no command "promotions ${sub ?? ''}".`, 'Use `c11r promotions list`, `show <id>`, `create`, `update <id>`, `enable <id>`, `disable <id>` or `delete <id>`.');
-        case 'links':
-            if (sub === 'list')
-                return cmd.linksList();
-            if (sub === 'show')
-                return cmd.linksShow(args[2]);
-            if (sub === 'create')
-                return cmd.linksCreate(values);
-            if (sub === 'enable' || sub === 'disable')
-                return cmd.linksEnable(args[2], sub === 'enable');
-            if (sub === 'delete')
-                return cmd.linksDelete(args[2]);
-            throw new CliError('unknown_command', `There is no command "links ${sub ?? ''}".`, 'Use `c11r links list`, `show <id>`, `create`, `enable <id>`, `disable <id>` or `delete <id>`.');
-        case 'orders':
-            if (sub === 'test')
-                return cmd.ordersTest(flags, values);
-            if (sub === 'create')
-                return cmd.ordersCreate(values, lists, flags);
-            if (sub === 'list')
-                return cmd.ordersList(values, flags);
-            if (sub === 'show')
-                return cmd.ordersShow(args[2]);
-            if (sub === 'place' || sub === 'approve' || sub === 'capture' || sub === 'cancel' || sub === 'refund' || sub === 'archive' || sub === 'unarchive')
-                return cmd.ordersAct(sub, args[2], values, flags);
-            throw new CliError('unknown_command', `There is no command "orders ${sub ?? ''}".`, 'Use `c11r orders list`, `show <number>`, `create`, `place <number>`, `approve <number> [--capture]`, `capture`, `cancel`, `refund <number> [--amount <n>]`, `archive`, `unarchive`, or `orders test`.');
-        case 'fulfillment':
-            if (sub === 'list')
-                return cmd.fulfillmentList(values);
-            if (sub === 'show')
-                return cmd.fulfillmentShow(args[2]);
-            if (sub === 'hold' || sub === 'pick' || sub === 'pack' || sub === 'ready' || sub === 'ship' || sub === 'deliver')
-                return cmd.fulfillmentAct(sub, args[2], values);
-            throw new CliError('unknown_command', `There is no command "fulfillment ${sub ?? ''}".`, 'Use `c11r fulfillment list`, `show <shipment>`, `hold`, `pick`, `pack`, `ready`, `ship <shipment> [--carrier --tracking --tracking-url]` or `deliver`.');
-        case 'ops':
-            if (sub === 'check')
-                return cmd.opsCheck(values);
-            if (sub === 'run')
-                return cmd.opsRun(flags);
-            if (sub === 'digest')
-                return cmd.opsDigest(values);
-            throw new CliError('unknown_command', `There is no command "ops ${sub ?? ''}".`, 'Use `c11r ops check`, `ops run [--dry-run]` or `ops digest [--since 24h]`.');
-        case 'insights':
-            return cmd.insights(values);
-        case 'inbox':
-            if (sub === 'check')
-                return cmd.inboxCheck();
-            if (sub === 'list')
-                return cmd.inboxList(values, flags);
-            if (sub === 'pull')
-                return cmd.inboxPull(args[2], values, flags);
-            if (sub === 'tag')
-                return cmd.inboxTag(args[2], lists, values, flags);
-            throw new CliError('unknown_command', `There is no command "inbox ${sub ?? ''}".`, sub === 'reply' ? 'The CLI does not send email: replies stay with the human or their mail app.' : 'Use `c11r inbox check`, `list [--unseen] [--since 24h] [--limit 20]`, `pull <id> | --unseen` or `tag <id> --label <name> | --unlabel <name> | --move <folder> | --seen`.');
-        case 'ucp':
-            if (sub === 'profile')
-                return cmd.ucpProfile(flags);
-            if (sub === 'check')
-                return cmd.ucpCheck();
-            if (sub === 'search')
-                return cmd.ucpSearch(args.slice(2).join(' '), values, lists, flags);
-            if (sub === 'product')
-                return cmd.ucpProduct(args[2], values, flags);
-            if (sub === 'order')
-                return cmd.ucpOrder(args[2], values);
-            if (sub === 'ask')
-                return cmd.ucpAsk(args.slice(2).join(' '), values);
-            if (sub === 'checkout') {
-                const [, , action, id] = args;
-                if (action === 'create')
-                    return cmd.ucpCheckoutCreate(values, lists);
-                if (action === 'update')
-                    return cmd.ucpCheckoutUpdate(id, values, lists);
-                if (action === 'show')
-                    return cmd.ucpCheckoutShow(id, values);
-                if (action === 'cancel')
-                    return cmd.ucpCheckoutCancel(id, values);
-                if (action === 'complete')
-                    return cmd.ucpCheckoutComplete(id, values, flags);
-                throw new CliError('unknown_command', `There is no command "ucp checkout ${action ?? ''}".`, 'Use `c11r ucp checkout create`, `update <id>`, `show <id>`, `cancel <id>` or `complete <id>`.');
-            }
-            throw new CliError('unknown_command', `There is no command "ucp ${sub ?? ''}".`, 'Use `c11r ucp search`, `product`, `checkout`, `order`, `ask`, `profile` or `check`.');
-        default:
-            throw new CliError('unknown_command', `There is no command "${name}".`, `Run \`c11r help\`. Commands: ${Object.keys(cmd.HELP).join(', ')}.`);
-    }
-}
-run()
-    .then((result) => {
-    print(result);
-    if (result?.status === 'fail')
-        process.exit(1);
-})
-    .catch((e) => {
-    if (e instanceof CliError) {
-        print({ error: { code: e.code, message: e.message, hint: e.hint, ...(e.path ? { path: e.path } : {}) } });
-    }
-    else {
-        const message = e instanceof Error ? e.message : String(e);
-        print({ error: { code: 'internal', message, hint: `This is a bug in the CLI. Tell the human, with this output, and try again with ${NPX} in case it is already fixed.` } });
-    }
-    process.exit(1);
-});
+void main();

package/dist/builtins/auth.js

@@ -0,0 +1,169 @@
+// c11r auth login, logout, switch (contract section 18): the human's own Commerce Layer
+// login, for the nouns a claimed organization needs (organizations, members, roles, credentials).
+//
+// login reads the client id and secret of the human's Provisioning API application: from a
+// terminal, the secret typed without echo; with no terminal, from a file the human saved
+// (--secret-file, or ~/.config/c11r/provisioning.secret by default), only if no other user can
+// read it. Never from a flag or the environment. It mints a token at Commerce Layer, checks it
+// with GET /v1/auth, keeps both values in credentials.json (mode 600) and deletes the file.
+// With no terminal and no file it stops at once, makes the empty file (mode 600) for the human
+// to complete, and answers secret_required with next_step human_step. The stored login shows in
+// c11r status, never its secret.
+import fs from 'node:fs';
+import { credentialsFile, readLink, setDefaultOrg, storedLogin, storedOrgs, storeLogin, writeLink } from '../config.js';
+import { terminal } from '../confirm.js';
+import { closest, errorBody, CliError, fail } from '../errors.js';
+import { envelope, request } from '../http.js';
+import { loginToken, mint, PROVISIONING_URL, readSecretFile, secretFileDefault, writeSecretTemplate } from '../login.js';
+import { parseSchema } from '../schema.js';
+export const auth = {
+    schema: parseSchema({
+        noun: 'auth',
+        group: 'setup',
+        skill: 'setup-auth',
+        kind: 'task',
+        description: 'The human\'s own Commerce Layer login, from their Provisioning API application: for organizations, members, roles and the credentials of a claimed organization. The secret stays on this machine and is never printed.',
+        verbs: [
+            {
+                verb: 'login',
+                method: 'POST',
+                path: '/v1/auth/login',
+                state: 'none',
+                credential: 'none',
+                body: [
+                    { name: 'client_id', type: 'string', description: 'The client id of the Provisioning API application. Not a secret. Also read from the secret file.' },
+                    { name: 'secret_file', type: 'string', description: `A file with the client secret, alone or as client_secret=..., readable only by its owner (mode 600). By default ${'~/.config/c11r/provisioning.secret'} when there is no terminal.` },
+                    { name: 'keep_file', type: 'boolean', description: 'Leaves the secret file where it is; by default it is deleted once read.' },
+                ],
+                effect: 'Logs in with the human\'s Provisioning API application: mints a token at Commerce Layer, checks it with the API, keeps the client id and secret in credentials.json (mode 600). The API receives only the token.',
+            },
+            { verb: 'logout', method: 'POST', path: '/v1/auth/logout', state: 'none', credential: 'none', effect: 'Forgets the stored login on this machine. Its last token ends by itself within two hours. Organization tokens stay.' },
+            {
+                verb: 'switch',
+                method: 'POST',
+                path: '/v1/auth/switch/{slug}',
+                state: 'none',
+                credential: 'none',
+                body: [{ name: 'global', type: 'boolean', description: 'Sets the default for this machine, used when no --org, C11R_ORG or .c11r.json names one; without it, links this project folder.' }],
+                effect: 'Picks the organization commands act on: links this project folder to it (.c11r.json), or with --global sets the default for this machine.',
+            },
+        ],
+    }),
+    async run(run) {
+        switch (run.verb.name) {
+            case 'login':
+                return login(run);
+            case 'logout':
+                return logout();
+            case 'switch':
+                return switchOrg(run);
+        }
+        return undefined;
+    },
+};
+async function login(run) {
+    const v = run.parsed.values;
+    const prompter = run.prompter ?? terminal;
+    let clientId = v.client_id;
+    let secret;
+    let file = v.secret_file;
+    const fallback = secretFileDefault();
+    if (!file && !prompter.interactive && fs.existsSync(fallback))
+        file = fallback;
+    if (file) {
+        const read = readSecretFile(file);
+        clientId = clientId ?? read.client_id;
+        secret = read.client_secret;
+        if (!secret || !clientId) {
+            fail('secret_required', `${file} is not complete: ${!secret && !clientId ? 'client_id and client_secret have' : !secret ? 'client_secret has' : 'client_id has'} no value. Ask the human to complete the two lines client_id= and client_secret= in it with the values of their Provisioning API application, from the dashboard (next_step.url). Then c11r auth login reads it. Do not open or print that file.`, {
+                path: !secret ? 'client_secret' : 'client_id',
+                next_step: { action: 'human_step', command: 'c11r auth login', url: PROVISIONING_URL },
+                details: { secret_file: file },
+            });
+        }
+    }
+    else if (prompter.interactive && prompter.askSecret) {
+        clientId = clientId ?? (await prompter.ask('Client id of your Provisioning API application: ')).trim();
+        secret = (await prompter.askSecret('Client secret (not shown): ')).trim();
+        if (!clientId || !secret)
+            fail('secret_required', 'Nothing was typed: no login was stored.', { path: !clientId ? 'client_id' : 'client_secret' });
+    }
+    else {
+        // No terminal and no file: the human saves the values in a file the CLI made for it.
+        const created = writeSecretTemplate(fallback);
+        throw new CliError(errorBody('secret_required', `There is no terminal to type the secret in. Ask the human to open the Provisioning API page of the dashboard (next_step.url), create an application if there is none, and complete the two lines client_id= and client_secret= in ${fallback}, which ${created ? 'c11r has just made' : 'is there already'}, readable only by them. Then c11r auth login reads it. Do not open or print that file.`, { path: 'secret_file', next_step: { action: 'human_step', command: 'c11r auth login', url: PROVISIONING_URL }, details: { secret_file: fallback, created } }));
+    }
+    const minted = await mint(clientId, secret);
+    const who = await request({ method: 'GET', path: '/auth', query: { limit: '100' } }, { live: false, token: minted.token });
+    const orgs = who.data?.organizations;
+    const items = Array.isArray(orgs) ? orgs : Array.isArray(orgs?.items) ? orgs.items : [];
+    const previous = storedLogin();
+    if (!run.globals.dryRun) {
+        storeLogin({
+            client_id: clientId,
+            client_secret: secret,
+            token: minted.token,
+            expires_at: minted.expires_at,
+            user: who.data?.user ?? null,
+            organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null, ...(o.claimed_with_c11r !== undefined ? { claimed_with_c11r: o.claimed_with_c11r } : {}) })),
+            created_at: new Date().toISOString(),
+        });
+    }
+    let removed = false;
+    if (file && !v.keep_file && !run.globals.dryRun) {
+        fs.rmSync(file, { force: true });
+        removed = true;
+    }
+    const warnings = [...who.warnings];
+    if (previous && previous.client_id !== clientId)
+        warnings.push({ code: 'login_replaced', message: `The login with client id ${previous.client_id} was replaced.` });
+    return {
+        ...who,
+        data: {
+            ...(run.globals.dryRun ? { dry_run: true } : {}),
+            user: who.data?.user ?? null,
+            organizations: orgs ?? null,
+            client_id: clientId,
+            token_expires_at: minted.expires_at,
+            credentials: run.globals.dryRun ? null : credentialsFile(),
+            secret_file: file ? { file, removed } : null,
+        },
+        warnings,
+        next: who.next?.length ? who.next : [{ command: 'c11r organizations list', why: 'The organizations this login reaches.' }],
+    };
+}
+function logout() {
+    const l = storedLogin();
+    if (!l)
+        return envelope({ forgotten: false, login: null });
+    storeLogin(null);
+    return envelope({ forgotten: true, client_id: l.client_id, token_ends_by: l.expires_at }, { warnings: [{ code: 'token_still_valid', message: `The last token of this login ends by itself${l.expires_at ? ` at ${l.expires_at}` : ''}, within two hours; it is not revoked. Organization tokens on this machine stay.` }] });
+}
+async function switchOrg(run) {
+    const slug = run.parsed.id;
+    const tokens = storedOrgs();
+    let reached = storedLogin()?.organizations.map((o) => o.slug) ?? [];
+    if (!tokens[slug] && !reached.includes(slug) && storedLogin()) {
+        // The list may be older than the organization: read it again.
+        const who = await request({ method: 'GET', path: '/auth', query: { limit: '100' } }, { live: false, token: await loginToken() });
+        const items = who.data?.organizations?.items ?? who.data?.organizations ?? [];
+        reached = items.map((o) => o.slug);
+        const l = storedLogin();
+        if (l)
+            storeLogin({ ...l, organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null })) });
+    }
+    if (!tokens[slug] && !reached.includes(slug)) {
+        const known = [...new Set([...Object.keys(tokens), ...reached])];
+        fail('not_found', `${slug} is neither an organization with a token on this machine nor one the login reaches.`, { path: 'slug', did_you_mean: closest(slug, known), details: { orgs: known }, next_step: { action: 'fix_request', command: 'c11r organizations list' } });
+    }
+    const next = tokens[slug] ? [] : [{ command: `c11r organizations connect ${slug}`, why: 'This machine has no organization token for it yet: the organization nouns need one.' }];
+    if (run.parsed.values.global) {
+        if (!run.globals.dryRun)
+            setDefaultOrg(slug);
+        return envelope({ org: slug, default: true, token: tokens[slug] ? 'stored' : 'none', ...(run.globals.dryRun ? { dry_run: true } : {}) }, { next });
+    }
+    if (run.globals.dryRun)
+        return envelope({ org: slug, dry_run: true, link: readLink()?.file ?? null, token: tokens[slug] ? 'stored' : 'none' }, { next });
+    const link = writeLink(slug);
+    return envelope({ org: slug, linked: link.file, previous: link.previous, token: tokens[slug] ? 'stored' : 'none' }, { next });
+}