avo-cli 0.0.3 → 4.2.0.beta.2

data/payload/README.md

@@ -0,0 +1,612 @@
+# avo-cli
+
+Command line client for the [Avo REST API](https://docs.avohq.io/4.0/rest-api.html).
+It talks to any Rails app running `avo-api`; nothing is installed in the app.
+
+Status: every command works against any app running `avo-api`, and the docs
+site describes them. It ships as a Ruby gem that runs the built client on the
+machine's Node ([docs/install.md](docs/install.md)); the gem builds and installs
+locally and has not been released yet. What is left is in
+[docs/plans/v1-todo.md](docs/plans/v1-todo.md).
+
+## Requirements
+
+- Running the CLI: Node 18.12.1 or newer. 18.0 fails at startup on a missing
+  `node:fs/promises` export. The installed gem also needs Ruby 3.0 or newer,
+  for the `avo` executable that finds Node and hands the line over.
+- Developing it: Node 22.13 or newer (`.node-version` pins it). The lint toolchain
+  (`@typescript-eslint` → `eslint-visitor-keys@5`) refuses anything older.
+- yarn
+
+## Install (development)
+
+```sh
+cd gems/avo-cli
+yarn install
+./bin/dev.js --version
+```
+
+`./bin/dev.js` runs the TypeScript sources directly through tsx.
+`./bin/run.js` runs the compiled `dist/` after `yarn build`. The installed gem's
+`avo` runs that same `run.js`, from the `payload/` the gem carries. To build the
+gem and install it locally, see [docs/distribution.md](docs/distribution.md) §6.
+
+## Configuration
+
+Log in once and every later command knows the app:
+
+```sh
+avo login     # asks for the host, the token and the API version (Enter for v1), checks them, saves them
+avo schema    # works in any terminal from here on
+avo logout    # deletes what was saved
+```
+
+`avo login` saves to `~/.config/avo/config.json` (`$XDG_CONFIG_HOME/avo` when
+set, `%LOCALAPPDATA%\avo` on Windows), readable by your user only. The token is
+stored as plain text, like `~/.bundle/config`, so use a token you can revoke.
+
+The host is the API base URL: the address `avo-api` answers on, mount path
+included, exactly what you would paste into Postman before `/resources/...`.
+An app that mounts it the usual way is `http://localhost:3000/api`; one that
+mounts it elsewhere, say `mount_avo_api at: "avo"`, is
+`http://localhost:3000/avo`. The CLI appends only `/resources/<version>/<path>`
+and guesses no mount, so the address that works in a browser works here.
+
+For CI and scripts, skip `login` and set the variables. A flag wins over its
+variable, and either wins over what was saved. The saved host and token are
+used only together: name a host or a token yourself and the saved pair is left
+out, so a saved token never reaches another host. The saved API version goes
+with them: `avo login --api-version v2` once, and later commands use `v2`.
+
+| Variable          | Flag            | Default | Purpose                                                             |
+| ----------------- | --------------- | ------- | ------------------------------------------------------------------- |
+| `AVO_API_HOST`    | `--host`        | none    | API base URL, mount path included, e.g. `http://localhost:3000/api` |
+| `AVO_API_TOKEN`   | `--token`       | none    | API token secret, sent as `Authorization: Bearer`                   |
+| `AVO_API_VERSION` | `--api-version` | `v1`    | API version segment of the URL, saved by `login`                    |
+
+## Commands
+
+The gem is not released yet, so there is no `avo` on anyone's PATH: every
+example here runs the source through `./bin/dev.js`. The generated reference
+further down prints `avo`, the released name. These examples are swept to it
+when the gem ships.
+
+```sh
+./bin/dev.js schema                              # what the token may reach, as a table
+./bin/dev.js schema --format json                # the _schema body, byte for byte
+./bin/dev.js schema users                        # the fields a create sends, with required
+./bin/dev.js schema users --view show            # the fields a record reads back
+./bin/dev.js list users                          # first page, one row per record
+./bin/dev.js list users --page 2 --per-page 10   # paging
+./bin/dev.js list users --sort name --dir desc   # sorting, server side
+./bin/dev.js list users --fields id,name,email   # pick the columns
+./bin/dev.js get users 5                         # one record, field by field
+./bin/dev.js get users 5 --format json           # the body, byte for byte
+./bin/dev.js get users 5 --verbose               # request and response lines on stderr
+./bin/dev.js create users --data '{"name": "Ada", "email": "ada@example.com"}'
+./bin/dev.js update users 5 --data '{"name": "Ada King", "bio": null}'  # null clears
+./bin/dev.js create users --data @user.json      # the object from a file
+./bin/dev.js update users 5 --data - < user.json # the object from stdin
+./bin/dev.js delete users 5                      # no confirmation, see below
+./bin/dev.js login                               # save the host, token and API version
+./bin/dev.js logout                              # delete what login saved
+```
+
+### Grammar
+
+Every line has the same shape:
+
+```
+./bin/dev.js <verb> <resource> [id] [flags]
+```
+
+There are six verbs: `schema`, `list`, `get`, `create`, `update` and `delete`.
+The resource is always an argument, never a command, because route keys come
+from the app being talked to and only after an HTTP call. `login` and `logout`
+are the two commands outside the grammar: they take no resource
+([Configuration](#configuration)).
+
+`./bin/dev.js --help` lists the six verbs, with `login`, `logout` and `help`
+beside them, and `./bin/dev.js get --help` shows one. A line that names no
+command prints the usage above, with a did-you-mean when the typo is close to
+something real.
+
+Each verb has a one-letter shortcut — `s l g c u d`, in the order listed above
+— in the same slot, so `./bin/dev.js l users` is `list users`. They are hidden
+aliases: help, the reference below and the error messages all keep to the full
+spelling, and nothing else about the grammar bends. `./bin/dev.js users l` is
+refused like any other line that puts the resource first.
+
+### Output
+
+A table is plain text, two spaces between columns. `--fields` picks the
+columns and lays a table out in the flag's order; a single `get` reads down
+the page in the record's own order. A cell is one line: `-` for null and
+empty, a list joined with `, `, an object — an association included — as its
+JSON, and anything past 40 characters cut with `…`.
+
+`--format json` prints the body exactly as the server sent it and ignores
+`--fields`; `table` is the default. `--verbose` logs each request and
+response line to stderr, so `--format json --verbose | jq` still works.
+
+### Writing fields
+
+Fields are one JSON object, given through `--data` (`-d`): the JSON itself,
+`@path` to read it from a file, or `-` to read stdin. Every key is a field as
+`schema <resource>` lists them. JSON carries its own types, so nothing is
+converted — a value is sent as written. Before sending, the CLI reads the
+resource's form view: for the key the body nests under, for the `file` refusal
+below, and for the two values the wire wants in another form. What each field
+takes:
+
+| The view says                                     | You write                                       | Sent                                    |
+| ------------------------------------------------- | ----------------------------------------------- | --------------------------------------- |
+| `shape: array`                                    | `"roles": ["editor", "reviewer"]`               | as written; `null` sends `[]`           |
+| `shape: hash`, `keys: [latitude, longitude]`      | `"coordinates": {"latitude": 44.4, …}`          | as written; `null` sends every key null |
+| polymorphic `belongs_to`, two scalars             | `"reactable_type": "Post", "reactable_id": 7`   | as written                              |
+| `type: key_value` or `type: code`                 | `"settings": {"theme": "dark"}`                 | the object as a JSON string             |
+| `type: tags`                                      | `"skills": "ruby,rails"`                        | the string; the field splits it         |
+| anything else                                     | `"active": false`, `"birth_date": "1985-03-04"` | as written; the app casts               |
+
+Refused with exit `2`, before any request: `--data` that is not valid JSON or
+not one object, and an `@path` that cannot be read. Refused once the view is
+read, before the write: a `file` or `files` field, which needs a multipart
+upload the CLI does not send. Nothing else is checked against the view: the API
+validates a write, so an empty object, a field the view does not list or a
+value outside a field's `options` goes out as written and the server answers.
+An empty object is a `400`. A value outside a field's `options` is written as
+given, or a `500` where a Rails enum raises on it, and a misspelled field name
+or a value of the wrong shape is mostly dropped by the app's strong params
+without a word — the write exits `0` with that field unchanged — until
+[AVO-1804](https://linear.app/avo-hq/issue/AVO-1804) makes the API answer those
+too. Read the record back when it matters.
+[docs/field-types.md](docs/field-types.md) is the full table, type by type.
+
+Quote the object in single quotes: the shell reads the line first, and an
+unquoted `{"a":1,"b":2}` is a brace expansion that silently splits in two.
+When the quoting gets in the way — a value holding a quote, or an object too
+long for one line — write the JSON to a file and pass `--data @user.json`, or
+pipe it in with `--data -`.
+
+A `code` field takes its JSON as a string. Whether the field parses that string
+on the way in is a write transform the view does not publish — it describes the
+value a write sends, not what the field does with it afterwards — so over a
+JSON column the string lands double-encoded unless the resource declares
+`pretty_generated: true`. Setting such a field replaces the whole column;
+nothing is merged.
+
+`schema users` lists the fields a create may send, each with every key the
+view publishes for it: its `type`, whether it is `required`, its `shape`, and
+`options` or `keys` where it has them. `--view update` does the same for an
+update, and `--view index` or `--view show` list what a record comes back
+with, as `id` and `type`. The views are named by the API action they describe,
+the same words `schema` shows under `entitlements`. The answer is always for
+one view, never a merge of several, and each view needs the entitlement of the
+request it describes: a read-only token gets `index` and `show`, and on
+`create` and `update` a `403` the CLI relays like any other. A view the API
+does not serve is refused by the API, which names the ones it has. A
+`belongs_to` is listed by the key the body sets it through, `team_id`.
+
+`delete` has no body, so it reads no view and sends straight away. The server
+answers every request, and a refusal comes back as a `403` whose `reason` says
+which side to widen, `token_entitlement` or `policy`. The CLI names the request
+it made and relays the reason as it came:
+
+```
+ ›   Error: Forbidden: DELETE /api/resources/v1/users/5 was refused (reason: token_entitlement).
+```
+
+`delete` asks for no confirmation: an agent or a CI job has no terminal to
+answer a prompt on, and the line already names the record. A confirmation
+step is parked for after v1.
+
+### Errors
+
+Every error is one sentence naming what to change, on stderr. A `404` is the
+one message whatever the cause — a mistyped resource, a missing id, an app
+without `avo-api` mounted or licensed — because the API does not yet say which,
+and the CLI does not guess. `schema` lists the names this token may reach:
+
+```
+ ›   Error: Not found: http://localhost:3030/api/resources/v1/user.
+ ›   Check the resource name and the API version, and that the app has avo-api mounted and licensed.
+```
+
+A line that names no command is answered with the one grammar there is, and a
+correction above it when the typo is close to something real:
+
+```
+ ›   Error: command lst users not found
+ ›   Did you mean: avo list?
+ ›   Usage: avo <verb> <resource> [id] [flags]
+```
+
+A `422` lists what the app refused, one line per field:
+
+```
+ ›   Error: Failed to create User
+ ›     name: can't be blank
+ ›     email: has already been taken
+```
+
+A wrong secret, an expired token and a revoked one all read the same
+`Unauthorized`: the server does not say which, since saying would confirm a
+guessed secret.
+
+A redirect is reported and never followed, since the token would not survive
+it. It is usually `http://` on an app that forces `https://`:
+
+```
+ ›   Error: http://app.example.com redirected to https://app.example.com/api/resources/v1/_schema. Use the address it points to as the host.
+```
+
+### Exit codes
+
+| Code  | Meaning                                                                                      |
+| ----- | -------------------------------------------------------------------------------------------- |
+| `0`   | Success                                                                                      |
+| `1`   | The request failed: refused (400, 401, 403, 404, 422, 5xx), redirected, unreachable, timeout |
+| `2`   | Usage: the line or the setup was wrong, and nothing was written                              |
+| `130` | Interrupted: Ctrl-C at an `avo login` prompt, with nothing saved                             |
+
+Exit `1` also covers an answer that is not avo-api's: a `200` without the
+`records`, `record` or schema the endpoint promises. Exit `2` is an unknown
+command, a bad flag, `--view` with no resource, an empty id, a missing host or
+token, a host without `http://` or `https://` or with a username and password
+in it, a token holding a character a header cannot carry, `--data` that is not
+one JSON object or names a file that cannot be read, and a `file` field. It is
+also a saved login that cannot be read, written or parsed, `avo login` with a
+value left to ask for and no terminal to ask on, and the installed gem finding
+no Node, or one older than 18.12.1.
+
+<!-- commands -->
+* [`avo create RESOURCE`](#avo-create-resource)
+* [`avo delete RESOURCE ID`](#avo-delete-resource-id)
+* [`avo get RESOURCE ID`](#avo-get-resource-id)
+* [`avo help [COMMAND]`](#avo-help-command)
+* [`avo list RESOURCE`](#avo-list-resource)
+* [`avo login`](#avo-login)
+* [`avo logout`](#avo-logout)
+* [`avo schema [RESOURCE]`](#avo-schema-resource)
+* [`avo update RESOURCE ID`](#avo-update-resource-id)
+
+## `avo create RESOURCE`
+
+Create a record from one JSON object of fields
+
+```
+USAGE
+  $ avo create RESOURCE -d json|@path|- [--api-version <value>] [--host <value>] [--token <value>]
+    [--verbose] [--format table|json] [--fields field,field]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+
+FLAGS
+  -d, --data=json|@path|-  (required) Fields to write, as one JSON object; @path reads it from a file, - from stdin
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] API base URL, including the mount path, e.g. http://localhost:3000/api
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --fields=field,field  Columns to show, comma-separated, e.g. id,name,email
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it
+                        <options: table|json>
+  --verbose             Log each request and response line to stderr
+
+DESCRIPTION
+  Create a record from one JSON object of fields
+
+EXAMPLES
+  $ avo create users --data '{"name": "Ada Lovelace", "email": "ada@example.com"}'
+
+  $ avo create users --data '{"name": "Ada", "active": true, "roles": ["editor", "reviewer"]}'
+
+  $ avo create comments --data '{"body": "Hi", "commentable_type": "Post", "commentable_id": 7}'
+
+  $ avo create users --data @user.json
+
+  $ avo create users --data - < user.json
+
+  $ avo create users --data '{"name": "Ada"}' --format json
+```
+
+## `avo delete RESOURCE ID`
+
+Delete a record
+
+```
+USAGE
+  $ avo delete RESOURCE ID [--api-version <value>] [--host <value>] [--token <value>] [--verbose] [--format
+    table|json]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+  ID        Record id
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] API base URL, including the mount path, e.g. http://localhost:3000/api
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --format=<option>  [default: table] Output format; `json` prints the body exactly as the server sent it
+                     <options: table|json>
+  --verbose          Log each request and response line to stderr
+
+DESCRIPTION
+  Delete a record
+
+EXAMPLES
+  $ avo delete users 5
+
+  $ avo delete users 5 --format json
+```
+
+## `avo get RESOURCE ID`
+
+Show one record
+
+```
+USAGE
+  $ avo get RESOURCE ID [--api-version <value>] [--host <value>] [--token <value>] [--verbose] [--format
+    table|json] [--fields field,field]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+  ID        Record id
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] API base URL, including the mount path, e.g. http://localhost:3000/api
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --fields=field,field  Columns to show, comma-separated, e.g. id,name,email
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it
+                        <options: table|json>
+  --verbose             Log each request and response line to stderr
+
+DESCRIPTION
+  Show one record
+
+EXAMPLES
+  $ avo get users 5
+
+  $ avo get users 5 --fields name,email
+
+  $ avo get users 5 --format json
+```
+
+## `avo help [COMMAND]`
+
+Display help for avo.
+
+```
+USAGE
+  $ avo help [COMMAND...] [-n]
+
+ARGUMENTS
+  [COMMAND...]  Command to show help for.
+
+FLAGS
+  -n, --nested-commands  Include all nested commands in the output.
+
+DESCRIPTION
+  Display help for avo.
+```
+
+## `avo list RESOURCE`
+
+List the records of a resource, one page at a time
+
+```
+USAGE
+  $ avo list RESOURCE [--api-version <value>] [--host <value>] [--token <value>] [--verbose] [--format
+    table|json] [--dir <value> --sort <value>] [--fields field,field] [--page <value>] [--per-page <value>]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+
+FLAGS
+  --dir=<value>       Sort direction: asc or desc
+  --page=<value>      Page number, starting at 1
+  --per-page=<value>  Records per page (default: the app's Avo setting)
+  --sort=<value>      Field to sort by
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] API base URL, including the mount path, e.g. http://localhost:3000/api
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --fields=field,field  Columns to show, comma-separated, e.g. id,name,email
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it
+                        <options: table|json>
+  --verbose             Log each request and response line to stderr
+
+DESCRIPTION
+  List the records of a resource, one page at a time
+
+EXAMPLES
+  $ avo list users
+
+  $ avo list users --page 2 --per-page 10
+
+  $ avo list users --sort name --dir desc
+
+  $ avo list users --fields id,name,email
+
+  $ avo list users --format json
+```
+
+## `avo login`
+
+Save a host, an API token and the API version, so later commands need none of them
+
+```
+USAGE
+  $ avo login [--api-version <value>] [--host <value>] [--token <value>] [--verbose]
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] API base URL, including the mount path, e.g. http://localhost:3000/api
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --verbose  Log each request and response line to stderr
+
+DESCRIPTION
+  Save a host, an API token and the API version, so later commands need none of them
+
+EXAMPLES
+  $ avo login
+
+  $ avo login --host http://localhost:3000/api
+
+  $ avo login --host http://localhost:3000/api --token avo_...
+
+  $ avo login --api-version v2
+```
+
+## `avo logout`
+
+Delete the saved host and token. AVO_API_HOST and AVO_API_TOKEN set in the environment are not affected
+
+```
+USAGE
+  $ avo logout
+
+DESCRIPTION
+  Delete the saved host and token. AVO_API_HOST and AVO_API_TOKEN set in the environment are not affected
+
+EXAMPLES
+  $ avo logout
+```
+
+## `avo schema [RESOURCE]`
+
+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>]
+
+ARGUMENTS
+  [RESOURCE]  A resource by its route key; with none, the resources the API serves are listed
+
+FLAGS
+  --view=<value>  Which view's fields: create/update list what a write may send, with required; index/show what a record
+                  reads back (default: create)
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] API base URL, including the mount path, e.g. http://localhost:3000/api
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --format=<option>  [default: table] Output format; `json` prints the body exactly as the server sent it
+                     <options: table|json>
+  --verbose          Log each request and response line to stderr
+
+DESCRIPTION
+  List the resources the API serves, or the fields of one resource on one view
+
+EXAMPLES
+  $ avo schema
+
+  $ avo schema --format json
+
+  $ avo schema users
+
+  $ avo schema users --view show
+
+  $ avo schema --host http://localhost:3000/api --token avo_...
+```
+
+## `avo update RESOURCE ID`
+
+Update a record from one JSON object of fields; every field not given is left as it is
+
+```
+USAGE
+  $ avo update RESOURCE ID -d json|@path|- [--api-version <value>] [--host <value>] [--token <value>]
+    [--verbose] [--format table|json] [--fields field,field]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+  ID        Record id
+
+FLAGS
+  -d, --data=json|@path|-  (required) Fields to write, as one JSON object; @path reads it from a file, - from stdin
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] API base URL, including the mount path, e.g. http://localhost:3000/api
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --fields=field,field  Columns to show, comma-separated, e.g. id,name,email
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it
+                        <options: table|json>
+  --verbose             Log each request and response line to stderr
+
+DESCRIPTION
+  Update a record from one JSON object of fields; every field not given is left as it is
+
+EXAMPLES
+  $ avo update users 5 --data '{"name": "Ada King"}'
+
+  $ avo update users 5 --data '{"active": false, "age": 36}'
+
+  $ avo update users 5 --data '{"bio": null, "roles": []}'
+
+  $ avo update users 5 --data @user.json
+
+  $ avo update users 5 --data - < user.json
+
+  $ avo update users 5 --data '{"name": "Ada"}' --format json
+```
+<!-- commandsstop -->
+
+## Development
+
+```sh
+cd gems/avo-cli
+node --version   # 22.13 or newer, per `.node-version`
+
+yarn build       # compile src/ to dist/
+yarn test        # mocha, then typecheck and eslint (posttest)
+yarn typecheck   # tsc over src/ and test/, writing nothing
+yarn lint
+```
+
+Narrower runs, when the whole suite is more than you need:
+
+```sh
+yarn mocha test/commands/list.test.ts          # one file
+yarn mocha "test/**/*.test.ts" --grep "404"    # every test whose name matches
+```
+
+Tests never reach the network: HTTP is stubbed with undici's `MockAgent`,
+which Node's built-in `fetch` honours (see `test/http.test.ts`).
+
+The command reference above is generated by `oclif readme` and regenerated on
+`yarn version` and on pack. After changing a command's description, flags or
+examples, run `yarn build && yarn oclif readme --no-source-links` and commit
+the result. The flag matters: without it the reference links into the private
+workspace repository, which `test/readme.test.ts` refuses.
+
+To run the CLI against a real app, command by command, with the expected
+output and every way a line can fail, follow
+[docs/manual-testing.md](docs/manual-testing.md).

data/payload/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

data/payload/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+
+await execute({dir: import.meta.url})

data/payload/dist/base-command.js

@@ -0,0 +1,60 @@
+import { Command, Flags } from '@oclif/core';
+import { Client } from './client.js';
+import { DEFAULT_API_VERSION, resolveConfig } from './config.js';
+// The connection flags every command shares, plus a client built from them. Flag > env is oclif's job; the saved
+// file and the defaults come after, in `resolveConfig`. `login` stops here: it prints no table and no JSON.
+export class ConnectionCommand extends Command {
+    static baseFlags = {
+        // No oclif `default`: it would fill the flag before the saved version is read, and always win over it.
+        // `resolveConfig` applies the default instead, after both.
+        'api-version': Flags.string({
+            description: `API version segment of the URL; defaults to the one \`avo login\` saved, then ${DEFAULT_API_VERSION}`,
+            env: 'AVO_API_VERSION',
+            helpGroup: 'CONNECTION',
+        }),
+        host: Flags.string({
+            description: 'API base URL, including the mount path, e.g. http://localhost:3000/api',
+            env: 'AVO_API_HOST',
+            helpGroup: 'CONNECTION',
+        }),
+        token: Flags.string({
+            description: 'API token secret, sent as a Bearer token',
+            env: 'AVO_API_TOKEN',
+            helpGroup: 'CONNECTION',
+        }),
+        verbose: Flags.boolean({
+            description: 'Log each request and response line to stderr',
+            helpGroup: 'OUTPUT',
+        }),
+    };
+    client(flags) {
+        return this.clientFor(resolveConfig(flags, this.config.configDir), flags.verbose);
+    }
+    // For a caller that already holds the resolved connection. `--verbose` lines go to stderr.
+    clientFor(connection, verbose) {
+        return new Client({ ...connection, log: verbose ? (line) => this.logToStderr(line) : undefined });
+    }
+}
+// Every command that prints a response, which adds `--format` to the connection flags.
+export class BaseCommand extends ConnectionCommand {
+    static baseFlags = {
+        ...ConnectionCommand.baseFlags,
+        format: Flags.string({
+            default: 'table',
+            description: 'Output format; `json` prints the body exactly as the server sent it',
+            helpGroup: 'OUTPUT',
+            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;
+        // `this.log` always appends a newline, which would double the one a body ends with.
+        process.stdout.write(response.raw);
+        if (!response.raw.endsWith('\n'))
+            process.stdout.write('\n');
+        return true;
+    }
+}