avo-cli 0.0.3 → 4.2.0.beta.1

data/payload/dist/client.js

@@ -0,0 +1,77 @@
+import { failedRequest, failedResponse } from './errors.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+// All the CLI knows about avo-api: the URL shape `/api/resources/<version>/<path>` (the default mount), a Bearer
+// token, and JSON both ways.
+export class Client {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get(path, query) {
+        return this.request('GET', path, { query });
+    }
+    async request(method, path, { body, query } = {}) {
+        const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const url = this.url(path, query);
+        const headers = {
+            Accept: 'application/json',
+            Authorization: `Bearer ${this.options.token}`,
+        };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        this.options.log?.(`> ${method} ${url}`);
+        const started = performance.now();
+        let response;
+        let raw;
+        try {
+            response = await fetch(url, {
+                body: body === undefined ? undefined : JSON.stringify(body),
+                headers,
+                method,
+                // fetch drops the token when it follows a redirect to another origin, so a 3xx is reported, not followed.
+                redirect: 'manual',
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            // Inside the same `try`: the timeout aborts the body stream too, so an app that stalls after its headers fails here.
+            raw = await response.text();
+        }
+        catch (error) {
+            throw failedRequest(error, url, timeoutMs);
+        }
+        const elapsed = Math.round(performance.now() - started);
+        this.options.log?.(`< ${response.status} ${response.statusText} (${Buffer.byteLength(raw)} bytes, ${elapsed} ms)`);
+        const result = {
+            body: parseJson(raw, response.headers),
+            headers: response.headers,
+            raw,
+            status: response.status,
+            url,
+        };
+        if (!response.ok)
+            throw failedResponse(result, method);
+        return result;
+    }
+    url(path, query) {
+        const segments = path.map((segment) => encodeURIComponent(segment)).join('/');
+        const url = new URL(`${this.options.host}/api/resources/${this.options.apiVersion}/${segments}`);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        return url.toString();
+    }
+}
+// Parsed only when the server said it is JSON, so an HTML error page from the wrong app is `undefined`, which the
+// caller reads as "not an avo-api answer", rather than a SyntaxError.
+function parseJson(raw, headers) {
+    if (raw === '')
+        return undefined;
+    if (!headers.get('content-type')?.includes('json'))
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}

data/payload/dist/commands/create.js

@@ -0,0 +1,26 @@
+import { readData } from '../data.js';
+import { RecordCommand } from '../record-command.js';
+import { WriteCommand } from '../write-command.js';
+export default class Create extends WriteCommand {
+    static args = {
+        resource: RecordCommand.resourceArg,
+    };
+    static description = 'Create a record from one JSON object of fields';
+    static examples = [
+        `<%= config.bin %> create users --data '{"name": "Ada Lovelace", "email": "ada@example.com"}'`,
+        `<%= config.bin %> create users --data '{"name": "Ada", "active": true, "roles": ["editor", "reviewer"]}'`,
+        `<%= config.bin %> create comments --data '{"body": "Hi", "commentable_type": "Post", "commentable_id": 7}'`,
+        '<%= config.bin %> create users --data @user.json',
+        '<%= config.bin %> create users --data - < user.json',
+        `<%= config.bin %> create users --data '{"name": "Ada"}' --format json`,
+    ];
+    static hiddenAliases = ['c'];
+    async run() {
+        const { args, flags } = await this.parse(Create);
+        // The client first, so `--data -` does not wait on stdin for a line with no host. Neither step sends anything.
+        const client = this.client(flags);
+        const data = await readData(flags.data);
+        const response = await this.sendFields(client, { method: 'POST', view: 'create' }, [args.resource], data);
+        this.printRecord(response, flags);
+    }
+}

data/payload/dist/commands/delete.js

@@ -0,0 +1,22 @@
+import { RecordCommand } from '../record-command.js';
+export default class Delete extends RecordCommand {
+    static args = {
+        resource: RecordCommand.resourceArg,
+        id: RecordCommand.idArg,
+    };
+    static description = 'Delete a record';
+    static examples = ['<%= config.bin %> delete users 5', '<%= config.bin %> delete users 5 --format json'];
+    static hiddenAliases = ['d'];
+    // No confirmation: an agent or a CI job has no terminal to answer a prompt on, and a `--yes` typed on every line
+    // guards nothing. The line names the record; that is the intent.
+    async run() {
+        const { args, flags } = await this.parse(Delete);
+        const client = this.client(flags);
+        // No body, so no view to read first: one request.
+        const response = await client.request('DELETE', [args.resource, args.id]);
+        if (this.printedJson(flags, response))
+            return;
+        const { message } = (response.body ?? {});
+        this.log(message ?? `Deleted ${args.resource} ${args.id}.`);
+    }
+}

data/payload/dist/commands/get.js

@@ -0,0 +1,19 @@
+import { RecordCommand } from '../record-command.js';
+export default class Get extends RecordCommand {
+    static args = {
+        resource: RecordCommand.resourceArg,
+        id: RecordCommand.idArg,
+    };
+    static description = 'Show one record';
+    static examples = [
+        '<%= config.bin %> get users 5',
+        '<%= config.bin %> get users 5 --fields name,email',
+        '<%= config.bin %> get users 5 --format json',
+    ];
+    static flags = { fields: RecordCommand.fieldsFlag };
+    static hiddenAliases = ['g'];
+    async run() {
+        const { args, flags } = await this.parse(Get);
+        this.printRecord(await this.client(flags).get([args.resource, args.id]), flags);
+    }
+}

data/payload/dist/commands/list.js

@@ -0,0 +1,47 @@
+import { Flags } from '@oclif/core';
+import { wrongShape } from '../errors.js';
+import { RecordCommand } from '../record-command.js';
+import { renderTable } from '../table.js';
+export default class List extends RecordCommand {
+    static args = { resource: RecordCommand.resourceArg };
+    static description = 'List the records of a resource, one page at a time';
+    static examples = [
+        '<%= config.bin %> list users',
+        '<%= config.bin %> list users --page 2 --per-page 10',
+        '<%= config.bin %> list users --sort name --dir desc',
+        '<%= config.bin %> list users --fields id,name,email',
+        '<%= config.bin %> list users --format json',
+    ];
+    static flags = {
+        dir: Flags.string({ dependsOn: ['sort'], description: 'Sort direction: asc or desc' }),
+        fields: RecordCommand.fieldsFlag,
+        page: Flags.integer({ description: 'Page number, starting at 1' }),
+        'per-page': Flags.integer({ description: "Records per page (default: the app's Avo setting)" }),
+        sort: Flags.string({ description: 'Field to sort by' }),
+    };
+    static hiddenAliases = ['l'];
+    async run() {
+        const { args, flags } = await this.parse(List);
+        const client = this.client(flags);
+        const response = await client.get([args.resource], {
+            page: flags.page,
+            per_page: flags['per-page'],
+            sort_by: flags.sort,
+            sort_direction: flags.dir,
+        });
+        // Before `parseRecords`: `--format json` must relay a body this command could not table.
+        if (this.printedJson(flags, response))
+            return;
+        const { pagination, records } = parseRecords(response);
+        this.log(records.length === 0 ? `No ${args.resource} records.` : renderTable(records, flags.fields));
+        if (typeof pagination?.page === 'number') {
+            this.log(`Page ${pagination.page} of ${pagination.total_pages} (${pagination.total_count} records)`);
+        }
+    }
+}
+function parseRecords(response) {
+    const body = response.body;
+    if (!Array.isArray(body?.records))
+        throw wrongShape(response.url, 'records');
+    return { pagination: body.pagination, records: body.records };
+}

data/payload/dist/commands/login.js

@@ -0,0 +1,93 @@
+import input from '@inquirer/input';
+import password from '@inquirer/password';
+import { ConnectionCommand } from '../base-command.js';
+import { checkToken, DEFAULT_API_VERSION, normalizeHost, resolveConfig } from '../config.js';
+import { CliError } from '../errors.js';
+import { loadSchema } from '../schema.js';
+import { fileIn, save } from '../store.js';
+export default class Login extends ConnectionCommand {
+    static description = 'Save a host, an API token and the API version, so later commands need none of them';
+    static examples = [
+        '<%= config.bin %> login',
+        '<%= config.bin %> login --host http://localhost:3000',
+        '<%= config.bin %> login --host http://localhost:3000 --token avo_...',
+        '<%= config.bin %> login --api-version v2',
+    ];
+    // On stderr, like any prompt: `avo login > log` still shows the questions, and the log gets only the result.
+    static prompts = {
+        input: (config) => input(config, { output: process.stderr }),
+        isTTY: () => Boolean(process.stdin.isTTY),
+        password: (config) => password(config, { output: process.stderr }),
+    };
+    async run() {
+        const { flags } = await this.parse(Login);
+        const connection = resolveConfig(await this.collect(flags));
+        // Through the same client every other command uses, so nothing is saved that the next `avo list` could not use.
+        await loadSchema(this.clientFor(connection, flags.verbose));
+        this.log(`Checking ${connection.host} (API ${connection.apiVersion}) ... ok.`);
+        const file = fileIn(this.config.configDir);
+        const replaced = save(this.config.configDir, connection);
+        this.log(`Saved to ${file}${replaced ? ' (replaced the previous one).' : '.'}`);
+    }
+    async askHost() {
+        this.requireTerminal('host', '--host', 'AVO_API_HOST');
+        // Normalized with the rest in `resolveConfig`; the prompt has already accepted it.
+        return Login.prompts.input({
+            message: 'Host (e.g. http://localhost:3000):',
+            validate: problemWith(normalizeHost),
+        });
+    }
+    async askToken() {
+        this.requireTerminal('token', '--token', 'AVO_API_TOKEN');
+        return Login.prompts.password({
+            mask: true,
+            message: 'API token:',
+            validate: (value) => (value.length > 0 ? problemWith(checkToken)(value) : 'The token cannot be empty.'),
+        });
+    }
+    // The version has a default, so without a terminal it is taken rather than refused: CI gives host and token only.
+    async askVersion() {
+        if (!Login.prompts.isTTY())
+            return DEFAULT_API_VERSION;
+        return Login.prompts.input({
+            default: DEFAULT_API_VERSION,
+            message: 'API version:',
+        });
+    }
+    // A value given by flag or env is an answer already, so only the rest is asked for. The answers are raw, for
+    // `resolveConfig`; a bad `--host` is checked here only so it fails before the token is asked for.
+    async collect(flags) {
+        try {
+            if (flags.host)
+                normalizeHost(flags.host);
+            const host = flags.host || (await this.askHost());
+            const token = flags.token || (await this.askToken());
+            const apiVersion = flags['api-version'] || (await this.askVersion());
+            return { 'api-version': apiVersion, host, token };
+        }
+        catch (error) {
+            // Ctrl-C is a decision not to log in, not a failure to report back. 130 is the shell's code for it.
+            if (error.name === 'ExitPromptError')
+                this.exit(130);
+            throw error;
+        }
+    }
+    requireTerminal(what, flag, env) {
+        if (Login.prompts.isTTY())
+            return;
+        throw CliError.usage(`No ${what}. \`avo login\` cannot ask without a terminal; pass ${flag} or set ${env}.`);
+    }
+}
+// Turns the check `resolveConfig` runs into a prompt's own, so a bad answer is asked again with the reason rather
+// than failing only after every question.
+function problemWith(check) {
+    return (value) => {
+        try {
+            check(value);
+            return true;
+        }
+        catch (error) {
+            return error.message;
+        }
+    };
+}

data/payload/dist/commands/logout.js

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+import { fileIn, remove } from '../store.js';
+// Not a `BaseCommand`: it makes no request, so the connection flags would be on `--help` doing nothing.
+export default class Logout extends Command {
+    static description = 'Delete the saved host and token. AVO_API_HOST and AVO_API_TOKEN set in the environment are not affected';
+    static examples = ['<%= config.bin %> logout'];
+    async run() {
+        // Nothing to read from it: parsing is what refuses a flag this command does not have, instead of ignoring it.
+        await this.parse(Logout);
+        const { configDir } = this.config;
+        this.log(remove(configDir) ? `Deleted ${fileIn(configDir)}.` : 'Nothing to delete: no host and token were saved.');
+    }
+}

data/payload/dist/commands/schema.js

@@ -0,0 +1,58 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../base-command.js';
+import { CliError } from '../errors.js';
+import { DEFAULT_VIEW, fetchResourceSchema, loadSchema } from '../schema.js';
+import { renderTable } from '../table.js';
+// One verb, two answers: with no resource, the resources the API serves and
+// how far the token reaches on each; with one, its fields on one view.
+export default class Schema extends BaseCommand {
+    static args = {
+        resource: Args.string({
+            description: 'A resource by its route key; with none, the resources the API serves are listed',
+        }),
+    };
+    static description = 'List the resources the API serves, or the fields of one resource on one view';
+    static examples = [
+        '<%= config.bin %> schema',
+        '<%= config.bin %> schema --format json',
+        '<%= config.bin %> schema users',
+        '<%= config.bin %> schema users --view show',
+        '<%= config.bin %> schema --host http://localhost:3000 --token avo_...',
+    ];
+    static flags = {
+        // No `options`: the view names are the API's to know, not this flag's.
+        view: Flags.string({
+            description: `Which view's fields: create/update list what a write may send, with required; index/show what a record reads back (default: ${DEFAULT_VIEW})`,
+        }),
+    };
+    static hiddenAliases = ['s'];
+    async run() {
+        const { args, flags } = await this.parse(Schema);
+        const { resource } = args;
+        // A usage error, so it comes before the host and token are looked for.
+        if (resource === undefined && flags.view) {
+            throw CliError.usage('--view needs a resource: `schema users --view show`.');
+        }
+        const client = this.client(flags);
+        if (resource === undefined) {
+            await this.listResources(client, flags);
+            return;
+        }
+        const asked = flags.view ?? DEFAULT_VIEW;
+        const { response, schema } = await fetchResourceSchema(client, resource, asked);
+        if (this.printedJson(flags, response))
+            return;
+        const { fields } = schema;
+        this.log(fields.length === 0 ? `No fields on the ${asked} view of ${resource}.` : renderTable(fields));
+    }
+    async listResources(client, flags) {
+        const { response, schema } = await loadSchema(client);
+        if (this.printedJson(flags, response))
+            return;
+        if (schema.resources.length === 0) {
+            this.log(`No resources: nothing API ${schema.api_version} serves is within this token's entitlements.`);
+            return;
+        }
+        this.log(renderTable(schema.resources, ['route_key', 'name', 'entitlements', 'avo_actions']));
+    }
+}

data/payload/dist/commands/update.js

@@ -0,0 +1,27 @@
+import { readData } from '../data.js';
+import { RecordCommand } from '../record-command.js';
+import { WriteCommand } from '../write-command.js';
+export default class Update extends WriteCommand {
+    static args = {
+        resource: RecordCommand.resourceArg,
+        id: RecordCommand.idArg,
+    };
+    static description = 'Update a record from one JSON object of fields; every field not given is left as it is';
+    static examples = [
+        `<%= config.bin %> update users 5 --data '{"name": "Ada King"}'`,
+        `<%= config.bin %> update users 5 --data '{"active": false, "age": 36}'`,
+        `<%= config.bin %> update users 5 --data '{"bio": null, "roles": []}'`,
+        '<%= config.bin %> update users 5 --data @user.json',
+        '<%= config.bin %> update users 5 --data - < user.json',
+        `<%= config.bin %> update users 5 --data '{"name": "Ada"}' --format json`,
+    ];
+    static hiddenAliases = ['u'];
+    async run() {
+        const { args, flags } = await this.parse(Update);
+        // The client first, so `--data -` does not wait on stdin for a line with no host. Neither step sends anything.
+        const client = this.client(flags);
+        const data = await readData(flags.data);
+        const response = await this.sendFields(client, { method: 'PATCH', view: 'update' }, [args.resource, args.id], data);
+        this.printRecord(response, flags);
+    }
+}

data/payload/dist/config.js

@@ -0,0 +1,57 @@
+import { CliError } from './errors.js';
+import { exists, read } from './store.js';
+export const DEFAULT_API_VERSION = 'v1';
+// Fails fast on the two values that have no default. A saved login (`configDir`) is used all or nothing: a flag naming
+// either value skips the file, so a saved token never reaches another host and a broken file cannot fail the command.
+export function resolveConfig(flags, configDir) {
+    const given = Boolean(flags.host || flags.token);
+    const saved = (given || !configDir ? undefined : read(configDir)) ?? {};
+    const host = flags.host || saved.host;
+    const token = flags.token || saved.token;
+    // Asked only on failure, so the error names the ignored file rather than sending the customer back to `avo login`.
+    const ignoredSaved = () => given && configDir !== undefined && exists(configDir);
+    if (!host) {
+        throw CliError.usage(ignoredSaved()
+            ? 'No host. The saved login was ignored because a token was given without a host. Pass --host or set ' +
+                'AVO_API_HOST too, or drop --token and unset AVO_API_TOKEN to use the saved login.'
+            : 'No host. Pass --host (e.g. http://localhost:3000), set AVO_API_HOST, or run `avo login`.');
+    }
+    if (!token) {
+        throw CliError.usage(ignoredSaved()
+            ? 'No token. The saved login was ignored because a host was given without a token. Pass --token or set ' +
+                'AVO_API_TOKEN too, or drop --host and unset AVO_API_HOST to use the saved login.'
+            : 'No token. Pass --token, set AVO_API_TOKEN to an API token secret, or run `avo login`.');
+    }
+    checkToken(token);
+    return {
+        // `||`, not `??`: `--api-version "$VER"` with the variable unset arrives empty, and an empty URL segment 404s.
+        apiVersion: flags['api-version'] || saved.apiVersion || DEFAULT_API_VERSION,
+        host: normalizeHost(host),
+        token,
+    };
+}
+// fetch quotes a header value it refuses in its error, so a token it cannot send is refused here, unquoted.
+export function checkToken(token) {
+    if (/[^\u0020-\u007E]/.test(token)) {
+        throw CliError.usage('The token has a character that cannot be sent in a header, such as a newline.');
+    }
+}
+// A scheme is required rather than assumed: `localhost:3000` parses as a URL with protocol `localhost:`, and guessing
+// http would hide the mistake until the request failed. A trailing slash is dropped so the path appends cleanly.
+export function normalizeHost(host) {
+    let url;
+    try {
+        url = new URL(host);
+    }
+    catch {
+        throw CliError.usage(`Host must be a URL, e.g. http://localhost:3000 (got "${host}")`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw CliError.usage(`Host must start with http:// or https:// (got "${host}")`);
+    }
+    // `origin` would drop them in silence, and the 401 that follows would blame the token. Not quoted: it is a secret.
+    if (url.username || url.password) {
+        throw CliError.usage('Host cannot carry a username and password: basic auth in the URL is not supported.');
+    }
+    return url.origin + url.pathname.replace(/\/+$/, '');
+}

data/payload/dist/data.js

@@ -0,0 +1,33 @@
+import { readFile } from 'node:fs/promises';
+import { text } from 'node:stream/consumers';
+import { CliError } from './errors.js';
+// Only the outer shape is checked: it parsed, and it is one object. An empty object goes out like any other, since
+// what sets nothing is the API's to refuse. A list would be a batch, which does not exist yet.
+export async function readData(given, stdin = process.stdin) {
+    const data = parse(await read(given, stdin));
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        throw CliError.usage('--data takes one JSON object, such as {"name": "Ada"}.');
+    }
+    return data;
+}
+async function read(given, stdin) {
+    if (given === '-')
+        return text(stdin);
+    if (!given.startsWith('@'))
+        return given;
+    const path = given.slice(1);
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw CliError.usage(`--data could not read the file ${path}: ${error.message}`);
+    }
+}
+function parse(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch (error) {
+        throw CliError.usage(`--data is not valid JSON: ${error.message}. For quoting trouble, use --data @file.json.`);
+    }
+}

data/payload/dist/errors.js

@@ -0,0 +1,93 @@
+import { Errors } from '@oclif/core';
+// oclif prints it and exits with the code it carries: 1 when the request failed, 2 when the caller got the invocation
+// wrong. 130 is not raised through here: `login` exits with it directly on Ctrl-C at a prompt.
+export class CliError extends Errors.CLIError {
+    constructor(message, exitCode = 1) {
+        super(message, { exit: exitCode });
+    }
+    static usage(message) {
+        return new CliError(message, 2);
+    }
+}
+// `status` and `reason` are the contract; a server `message` is used wherever one is sent. A 404 is always worded
+// here, since no 404 body names its cause.
+export function failedResponse(response, method) {
+    const { status, url } = response;
+    const body = (typeof response.body === 'object' && response.body !== null ? response.body : {});
+    const { origin, pathname } = new URL(url);
+    if (status >= 300 && status < 400)
+        return new CliError(redirected(response, origin));
+    if (status === 401)
+        return new CliError(unauthorized(body.message, origin));
+    if (status === 403)
+        return new CliError(forbidden(body, `${method} ${pathname}`));
+    if (status === 404)
+        return new CliError(notFound(response, origin));
+    if (status === 422)
+        return new CliError(validationFailed(body));
+    if (status >= 500)
+        return new CliError(withDetail(`Server error ${status} from ${url}.`, body));
+    return new CliError(withDetail(`HTTP ${status} from ${url}.`, body));
+}
+// A success whose body is not the shape the endpoint promises, typically a different app on the port.
+export function wrongShape(source, expected) {
+    return new CliError(`${source} did not answer with ${expected}. Is this an app running avo-api?`);
+}
+// `fetch` wraps the network error as the `cause` of a bare "fetch failed", so the useful part is one level down.
+export function failedRequest(error, url, timeoutMs) {
+    const { hostname, origin } = new URL(url);
+    const { cause, name } = error;
+    if (name === 'TimeoutError' || name === 'AbortError') {
+        return new CliError(`Timed out after ${timeoutMs / 1000}s waiting for ${url}.`);
+    }
+    if (cause?.code === 'ECONNREFUSED') {
+        return new CliError(`Connection refused by ${origin}. Is the app running there?`);
+    }
+    if (cause?.code === 'ENOTFOUND' || cause?.code === 'EAI_AGAIN') {
+        return new CliError(`Unknown host ${hostname}. Check --host, AVO_API_HOST, or the host \`avo login\` saved.`);
+    }
+    const detail = cause?.message ?? error.message;
+    return new CliError(`Request to ${url} failed: ${detail}`);
+}
+// Typically `force_ssl` answering an http host. Following it would send the request on without the token.
+function redirected(response, origin) {
+    const location = response.headers.get('location');
+    return `${origin} redirected${location ? ` to ${location}` : ''}. Use the address it points to as the host.`;
+}
+// The server cannot know where the token came from, so the hint follows whichever side worded the sentence.
+function unauthorized(message, origin) {
+    return `${message ?? `Unauthorized: ${origin} rejected the token.`} Check --token, AVO_API_TOKEN, or run \`avo login\` again.`;
+}
+// `reason` is relayed as it came: only the server knows whether to widen the token or the policy. Not `withDetail`:
+// it falls back to `error`, which on this status is the word "Forbidden" again.
+function forbidden(body, request) {
+    const reason = body.reason ? ` (reason: ${body.reason})` : '';
+    return [`Forbidden: ${request} was refused${reason}.`, body.message].filter(Boolean).join(' ');
+}
+// A wrong resource name, a wrong API version, an unmounted and an unlicensed app all answer 404, so the message lists
+// all four; a missing record does too, and only the URL line covers it. A non-JSON body hints at the wrong app.
+function notFound(response, origin) {
+    const lines = [
+        `Not found: ${response.url}.`,
+        'Check the resource name and the API version, and that the app has avo-api mounted and licensed.',
+    ];
+    if (response.body === undefined) {
+        const type = response.headers.get('content-type') ?? 'no content type';
+        lines.push(`The response was ${type}, not JSON: is ${origin} the right app?`);
+    }
+    return lines.join('\n');
+}
+// `errors` is Rails' `record.errors` as JSON: a message list per attribute.
+function validationFailed(body) {
+    const lines = [body.message ?? 'Validation failed.'];
+    for (const [field, messages] of Object.entries(body.errors ?? {})) {
+        lines.push(`  ${field}: ${[messages].flat().join(', ')}`);
+    }
+    return lines.join('\n');
+}
+// Each part is optional, so `views` is relayed even without a sentence.
+function withDetail(message, body) {
+    const detail = body.message ?? body.error;
+    const known = body.views?.length ? `(known views: ${body.views.join(', ')})` : '';
+    return [message, detail, known].filter(Boolean).join(' ');
+}

data/payload/dist/hooks/command-not-found.js

@@ -0,0 +1,22 @@
+import { CliError } from '../errors.js';
+import { suggest } from '../suggest.js';
+// oclif collates every word up to the first flag into the id (`users:lst`), so the id read back with spaces is the
+// line as typed. It has to throw: oclif counts any return from this hook, undefined included, as the command run.
+const hook = async function ({ id }) {
+    const words = id.split(':');
+    const nearest = nearestCommand(words, this.config);
+    const lines = [`command ${words.join(' ')} not found`];
+    if (nearest)
+        lines.push(`Did you mean: ${this.config.bin} ${nearest}?`);
+    lines.push(`Usage: ${this.config.bin} <verb> <resource> [id] [flags]`);
+    throw CliError.usage(lines.join('\n'));
+};
+// A hidden shortcut is never a candidate. Only the first word is compared, since every command is one word, so the
+// resource and id on the line do not count as edits. A first word that already is a command is no correction.
+function nearestCommand(words, config) {
+    const ids = config.commands.filter((command) => !command.hidden).map((command) => command.id);
+    const [typed] = words;
+    const nearest = suggest(typed, ids);
+    return nearest && nearest !== typed ? nearest : undefined;
+}
+export default hook;

data/payload/dist/index.js

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

data/payload/dist/list.js

@@ -0,0 +1,7 @@
+// One rule for every comma-separated word the CLI reads. An empty item is dropped, so `--fields name,` is one column.
+export function splitList(value) {
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}

data/payload/dist/payload.js

@@ -0,0 +1,35 @@
+import { CliError } from './errors.js';
+// A value is sent as given and the server validates it: a second copy of the API's rules here would refuse a write a
+// newer server accepts. The schema is read only for a file, and for a value whose wire form differs from its JSON.
+export function buildPayload(data, fields) {
+    const payload = {};
+    const byId = new Map(fields.map((field) => [field.id, field]));
+    for (const [id, value] of Object.entries(data)) {
+        payload[id] = onTheWire(byId.get(id), value);
+    }
+    return payload;
+}
+// `key_value` and `code` take their JSON as a string and parse it themselves; sent as an object, a `key_value` column
+// is wiped.
+const JSON_AS_STRING = new Set(['code', 'key_value']);
+// null clears any field, but strong params silently drop a bare null in place of a list or a hash, so there it becomes
+// what does clear: the empty list, or every key null (both held by avo-api's `field_types_update_test.rb`).
+function onTheWire(field, value) {
+    if (!field)
+        return value;
+    const { id, keys = [], shape, type } = field;
+    // Whatever its shape, a file is bytes the JSON body cannot carry.
+    if (type === 'file' || type === 'files') {
+        throw CliError.usage(`${id} is a ${type} field, and a file needs a multipart upload the CLI does not send.`);
+    }
+    if (value === null) {
+        if (shape === 'array')
+            return [];
+        if (shape === 'hash')
+            return Object.fromEntries(keys.map((key) => [key, null]));
+        return value;
+    }
+    if (typeof value === 'object' && JSON_AS_STRING.has(type))
+        return JSON.stringify(value);
+    return value;
+}