avo-cli 4.2.0.beta.5 → 4.3.0.beta.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 573e2761181c8f7805b67e3559693db7d95ae070b56e3dc430d1d8e8b5d15886
-  data.tar.gz: afbde3679980b2a958d903a76f40911d69c0e484a32bf3b65eb04cb52be51909
+  metadata.gz: e16520471450b18019b924ef115ead5d10506a57b20604bf6c5c2e001a86ce06
+  data.tar.gz: 1cefc1c773b788d3a82694971d5b045440c7887faf8149b3a3d248c44de343af
 SHA512:
-  metadata.gz: 992210ec32bc04da8d8d2d81efd26e5f5c16fe71469781ccd50ee71629d30fab56ec566be8bcd6da0b1f9d118ce6f3e6ff4ff2827caec75a8fbec7f6bea4bf94
-  data.tar.gz: d635d45e4f5540e324ed41e3bf8a2f392d6bc9163324db8343cbab7e92267755c8ca0de791311cb8bc1ecf00c27c4d9806b015d723f4f16d38a72e688ae16acb
+  metadata.gz: 58ea6fc978c6505b0812271ab03a937ad3145c15121314fa14c254e671b31fa1a7173e88842ae3b0bbdd82dbd5b185fd4b3dc5fd142c23fcf2fc7056b3604827
+  data.tar.gz: e649adb3ca3dc4c03c703172afe49ba56bde22d5e070ab1c9e5b4a944188a168db22a398a52ba1abcd4239fec5616e79fa29677694e0a5395f2166b1c8e97701

data/README.md

@@ -61,6 +61,18 @@ avo delete users 5                      # no confirmation
 Field formats, errors and exit codes are in the
 [docs](https://docs.avohq.io/4.0/cli.html#send-the-right-value-for-a-field).
 
+To describe the API to another tool, export what the token may call as an
+OpenAPI 3.1 document and import the file into Swagger UI, Postman, Redocly or
+a client generator:
+
+```sh
+avo schema --format openapi > openapi.json
+```
+
+The document is built for the token that asked: a read-only token gets one
+with no create, update or delete operations. See
+[OpenAPI document](https://docs.avohq.io/4.0/rest-api.html#openapi-document).
+
 <!-- commands -->
 * [`avo create RESOURCE`](#avo-create-resource)
 * [`avo delete RESOURCE ID`](#avo-delete-resource-id)
@@ -284,15 +296,14 @@ EXAMPLES
 
 ## `avo logout`
 
-Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION exported in the environment keep working
+Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION set in the environment keep working
 
 ```
 USAGE
   $ avo logout
 
 DESCRIPTION
-  Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION exported in the environment keep
-  working
+  Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION set in the environment keep working
 
 EXAMPLES
   $ avo logout
@@ -305,7 +316,7 @@ List the resources the API serves, or the fields of one resource on one view
 ```
 USAGE
   $ avo schema [RESOURCE] [--api-version <value>] [--host <value>] [--token <value>] [--verbose] [--format
-    table|json] [--view <value>]
+    table|json|openapi] [--view <value>]
 
 ARGUMENTS
   [RESOURCE]  A resource by its route key; with none, the resources the API serves are listed
@@ -322,8 +333,8 @@ CONNECTION FLAGS
 
 OUTPUT FLAGS
   --format=<option>  [default: table] Output format; `json` prints the body exactly as the server sent it, indented on a
-                     terminal
-                     <options: table|json>
+                     terminal; `openapi` prints the OpenAPI document of what the token may call
+                     <options: table|json|openapi>
   --verbose          Log each request and response line to stderr
 
 DESCRIPTION
@@ -334,6 +345,8 @@ EXAMPLES
 
   $ avo schema --format json
 
+  $ avo schema --format openapi > openapi.json
+
   $ avo schema users
 
   $ avo schema users --view show

data/lib/avo/cli/version.rb

@@ -2,6 +2,6 @@
 
 module Avo
   module Cli
-    VERSION = "4.2.0.beta.5"
+    VERSION = "4.3.0.beta.5"
   end
 end

data/payload/README.md

@@ -61,6 +61,18 @@ avo delete users 5                      # no confirmation
 Field formats, errors and exit codes are in the
 [docs](https://docs.avohq.io/4.0/cli.html#send-the-right-value-for-a-field).
 
+To describe the API to another tool, export what the token may call as an
+OpenAPI 3.1 document and import the file into Swagger UI, Postman, Redocly or
+a client generator:
+
+```sh
+avo schema --format openapi > openapi.json
+```
+
+The document is built for the token that asked: a read-only token gets one
+with no create, update or delete operations. See
+[OpenAPI document](https://docs.avohq.io/4.0/rest-api.html#openapi-document).
+
 <!-- commands -->
 * [`avo create RESOURCE`](#avo-create-resource)
 * [`avo delete RESOURCE ID`](#avo-delete-resource-id)
@@ -284,15 +296,14 @@ EXAMPLES
 
 ## `avo logout`
 
-Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION exported in the environment keep working
+Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION set in the environment keep working
 
 ```
 USAGE
   $ avo logout
 
 DESCRIPTION
-  Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION exported in the environment keep
-  working
+  Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION set in the environment keep working
 
 EXAMPLES
   $ avo logout
@@ -305,7 +316,7 @@ List the resources the API serves, or the fields of one resource on one view
 ```
 USAGE
   $ avo schema [RESOURCE] [--api-version <value>] [--host <value>] [--token <value>] [--verbose] [--format
-    table|json] [--view <value>]
+    table|json|openapi] [--view <value>]
 
 ARGUMENTS
   [RESOURCE]  A resource by its route key; with none, the resources the API serves are listed
@@ -322,8 +333,8 @@ CONNECTION FLAGS
 
 OUTPUT FLAGS
   --format=<option>  [default: table] Output format; `json` prints the body exactly as the server sent it, indented on a
-                     terminal
-                     <options: table|json>
+                     terminal; `openapi` prints the OpenAPI document of what the token may call
+                     <options: table|json|openapi>
   --verbose          Log each request and response line to stderr
 
 DESCRIPTION
@@ -334,6 +345,8 @@ EXAMPLES
 
   $ avo schema --format json
 
+  $ avo schema --format openapi > openapi.json
+
   $ avo schema users
 
   $ avo schema users --view show

data/payload/dist/base-command.js

@@ -47,16 +47,20 @@ export class BaseCommand extends ConnectionCommand {
             options: ['table', 'json'],
         }),
     };
-    // Answers whether it printed. The record commands call it ahead of their shape check, so json relays a body they
-    // could not table; `schema` cannot, since its loaders check the shape as they fetch.
-    printedJson(flags, response) {
-        if (flags.format !== 'json')
-            return false;
+    // The body as the server sent it, whatever the flag that asked for it.
+    printBody(response) {
         const body = terminal().tty && response.body !== undefined ? indented(response.body) : response.raw;
         // `this.log` always appends a newline, which would double the one a body ends with.
         process.stdout.write(body);
         if (!body.endsWith('\n'))
             process.stdout.write('\n');
+    }
+    // Answers whether it printed. The record commands call it ahead of their shape check, so json relays a body they
+    // could not table; `schema` cannot, since its loaders check the shape as they fetch.
+    printedJson(flags, response) {
+        if (flags.format !== 'json')
+            return false;
+        this.printBody(response);
         return true;
     }
 }

data/payload/dist/commands/list.js

@@ -34,7 +34,7 @@ export default class List extends RecordCommand {
         if (this.printedJson(flags, response))
             return;
         const { pagination, records } = parseRecords(response);
-        const layout = records.length === 0 ? undefined : await layoutTable(records, { columns: flags.fields });
+        const layout = records.length === 0 ? undefined : await layoutTable(records, { columns: flags.fields, overflow: 'wrap' });
         this.log(layout?.text ?? `No ${args.resource}.`);
         if (typeof pagination?.page !== 'number')
             return;

data/payload/dist/commands/logout.js

@@ -2,7 +2,7 @@ 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, AVO_API_TOKEN and AVO_API_VERSION exported in the environment keep working';
+    static description = 'Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION set in the environment keep working';
     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.

data/payload/dist/commands/schema.js

@@ -1,17 +1,9 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
-import { CliError } from '../errors.js';
+import { CliError, wrongShape } from '../errors.js';
 import { DEFAULT_VIEW, fetchResourceSchema, loadSchema } from '../schema.js';
 import { hiddenColumnsNote, layoutTable } from '../table.js';
-// `required: false` is what most fields carry, so printing it on every row buries the few that are `true`. A `null`
-// (the server could not tell) stays, and a row left with nothing prints `-` rather than `{}`. `--format json` keeps all.
-function shownOptions(options) {
-    if (options?.required !== false)
-        return options;
-    const rest = { ...options };
-    delete rest.required;
-    return Object.keys(rest).length === 0 ? undefined : rest;
-}
+import { paint, terminal } from '../terminal.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 {
@@ -24,11 +16,18 @@ export default class Schema extends BaseCommand {
     static examples = [
         '<%= config.bin %> schema',
         '<%= config.bin %> schema --format json',
+        '<%= config.bin %> schema --format openapi > openapi.json',
         '<%= config.bin %> schema users',
         '<%= config.bin %> schema users --view show',
         '<%= config.bin %> schema --host http://localhost:3000/api --token avo_...',
     ];
     static flags = {
+        // `openapi` is this verb's alone: the document describes the whole API, so no record command could print it.
+        format: {
+            ...BaseCommand.baseFlags.format,
+            description: `${BaseCommand.baseFlags.format.description}; \`openapi\` prints the OpenAPI document of what the token may call`,
+            options: ['table', 'json', 'openapi'],
+        },
         // 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 their field_options; index/show what a record reads back (default: ${DEFAULT_VIEW})`,
@@ -38,11 +37,23 @@ export default class Schema extends BaseCommand {
     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.
+        // Usage errors, so they come before the host and token are looked for.
+        if (flags.format === 'openapi' && (resource !== undefined || flags.view)) {
+            throw CliError.usage('--format openapi takes no resource and no --view: the document is the whole API.');
+        }
         if (resource === undefined && flags.view) {
             throw CliError.usage('--view needs a resource: `schema users --view show`.');
         }
         const client = this.client(flags);
+        if (flags.format === 'openapi') {
+            const response = await client.get(['_openapi']);
+            // A wrong host can answer 200 with a web page, which `> openapi.json` would save as the document.
+            if (response.body?.openapi === undefined) {
+                throw wrongShape(response.url, 'an OpenAPI document');
+            }
+            this.printBody(response);
+            return;
+        }
         if (resource === undefined) {
             await this.listResources(client, flags);
             return;
@@ -52,18 +63,21 @@ export default class Schema extends BaseCommand {
         if (this.printedJson(flags, response))
             return;
         const { fields } = schema;
+        const view = schema.view ?? asked;
         if (fields.length === 0) {
-            this.log(`No fields on the ${asked} view of ${resource}.`);
+            this.log(`No fields on the ${view} view of ${resource}.`);
             return;
         }
         // Headed `field id`, `field type`, `field options`, as a person reads them; `--format json` keeps the keys.
         // Wrapped, never cut: the CLI checks nothing against the view (decisions.md), so a truncated cell is the only
         // place a reader could have seen the `options` before sending.
-        const rows = fields.map((field) => {
-            const shown = 'field_options' in field ? { ...field, field_options: shownOptions(field.field_options) } : field;
-            return Object.fromEntries(Object.entries(shown).map(([key, value]) => [key.replaceAll('_', ' '), value]));
-        });
+        const rows = fields.map((field) => Object.fromEntries(Object.entries(field).map(([key, value]) => [key.replaceAll('_', ' '), value])));
+        const term = terminal();
+        // Writes point at what a record reads back, reads at what a write may send: the view a reader most likely wants next.
+        const next = view === 'create' || view === 'update' ? 'show' : 'create';
+        this.log(`${paint(term, 'bold', resource)} ${paint(term, 'cyan', `${view} view`)}`);
         await this.printTable(rows, { overflow: 'wrap' });
+        this.log(paint(term, 'dim', `Try: ${this.config.bin} schema ${resource} --view ${next}`));
     }
     async listResources(client, flags) {
         const { response, schema } = await loadSchema(client);

data/payload/dist/schema.js

@@ -1,6 +1,6 @@
 import { wrongShape } from './errors.js';
 // The one view name held here; every other is the server's to know, and a list would refuse a view a newer API serves.
-// It is sent explicitly because the answer does not echo the view, so the output names the view that was asked for.
+// It is sent explicitly, so what comes back is never the server's default under another name.
 export const DEFAULT_VIEW = 'create';
 // `source` names where the payload came from, so a shape error can say what did not answer.
 function parseSchema(payload, source) {

data/payload/dist/table.js

@@ -54,7 +54,8 @@ export function formatCell(value) {
     }
     if (typeof value === 'object')
         return JSON.stringify(value);
-    return String(value).replaceAll(/\s*\n\s*/g, ' ');
+    // A terminal draws a tab out to the next stop and acts on an ESC, so either one moves every border after the cell.
+    return String(value).replaceAll(/\s*\p{Cc}[\s\p{Cc}]*/gu, ' ').trim() || '-';
 }
 // Colour only where it carries something: a name is what the eye looks for, a boolean is scanned down a column, and
 // an empty cell should fade behind real data. Read off the value, not the cell, so a string `"true"` stays plain.

data/payload/oclif.manifest.json

@@ -548,7 +548,7 @@
     "logout": {
       "aliases": [],
       "args": {},
-      "description": "Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION exported in the environment keep working",
+      "description": "Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION set in the environment keep working",
       "examples": [
         "<%= config.bin %> logout"
       ],
@@ -580,6 +580,7 @@
       "examples": [
         "<%= config.bin %> schema",
         "<%= config.bin %> schema --format json",
+        "<%= config.bin %> schema --format openapi > openapi.json",
         "<%= config.bin %> schema users",
         "<%= config.bin %> schema users --view show",
         "<%= config.bin %> schema --host http://localhost:3000/api --token avo_..."
@@ -620,7 +621,7 @@
           "type": "boolean"
         },
         "format": {
-          "description": "Output format; `json` prints the body exactly as the server sent it, indented on a terminal",
+          "description": "Output format; `json` prints the body exactly as the server sent it, indented on a terminal; `openapi` prints the OpenAPI document of what the token may call",
           "helpGroup": "OUTPUT",
           "name": "format",
           "default": "table",
@@ -628,7 +629,8 @@
           "multiple": false,
           "options": [
             "table",
-            "json"
+            "json",
+            "openapi"
           ],
           "type": "option"
         },
@@ -786,5 +788,5 @@
       ]
     }
   },
-  "version": "4.2.0.beta.5"
+  "version": "4.3.0.beta.5"
 }

data/payload/package.json

@@ -1,7 +1,7 @@
 {
   "name": "avo-cli",
   "description": "Command line client for the Avo REST API",
-  "version": "4.2.0.beta.5",
+  "version": "4.3.0.beta.5",
   "author": "Avo",
   "bin": {
     "avo": "./bin/run.js"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: avo-cli
 version: !ruby/object:Gem::Version
-  version: 4.2.0.beta.5
+  version: 4.3.0.beta.5
 platform: ruby
 authors:
 - Avo