feat(drain): list the drains of every application and add-on

[KannarFr]

Closes #1118.

Why

clever drain always required a linked or targeted application:

[ERROR] There is no linked or targeted application. Use `--app` option or `clever link` command.

There was no way to get an overview of the drains one has set up.

What

clever drain now falls back to listing the drains of every resource of every organisation, the personal space included, grouped by organisation and naming the application or add-on each drain belongs to:

• Organisation 'LambdaDevs' (orga_5f42efc9-…) with 2 drains:
│ ID           │ Resource          │ Status     │ Execution status │ URL
│ 'drain_1111' │ 'biscuit-haskell' │ 'ENABLED'  │ 'RUNNING'        │ 'https://logs.example.com/in'
│ 'drain_2222' │ 'faas-test'       │ 'DISABLED' │ 'FAILED'         │ 'syslog+tcp://logs.example.com:514'

• --org (-o, --owner) restricts the listing to one organisation, and cannot be combined with --app, --alias or --addon
• targeting a resource is unchanged, and a linked application still takes precedence over the listing — since it can come from a parent directory, it is now named in the output
• --format json keeps printing a flat list of drains in both cases, each one carrying its ownerId/ownerName, so a script doesn't have to care how the command was targeted
• a drain that belongs to the organisation itself, audit logs for instance, has no resource: it is named after the organisation
• an organisation whose drains cannot be listed is reported on stderr without hiding the others, unless none can be listed at all
• resource names come from the /v2/summary call the listing already makes, so naming them costs no extra request

Also fixes clever drain --app <name> printing [object Object] instead of the application name when it has no drain.

API

The listing relies on GET /v4/drains/organisations/{ownerId}/drains, which is now live in production — it is served to OAuth1 callers since ovd!2147, and reading a drain asks for ADMIN, MANAGER or DEVELOPER in the organisation since ovd!2150. An organisation held with another role answers 403 and is reported as unreachable without hiding the others, which is what the per-organisation failure handling above is for. The roles are now documented in docs/services-logs-drains.md.

Side note, out of scope here: src/models/send-to-api.js maps any 401 to "You're not logged in, use clever login command". It is misleading whenever the API means "authenticated fine, not allowed here".

Testing

npm run validate passes.

Verified against production, no longer against stubs:

clever drain                                    # every organisation, grouped, resources named
clever drain --org "Clever Support"             # by name
clever drain --org orga_858600a8-…              # by id
clever drain --format json                      # flat list, every drain carrying ownerId/ownerName
clever drain --app app_5cd7548d-…               # single drain, detailed view
clever drain --app "test to delete"             # There are no drains for test to delete
clever drain --addon postgresql_66ab5c65-…      # add-on by real id
clever drain --addon addon_c743cde0-…           # add-on by add-on id

The add-on realId → name resolution is confirmed by the listing naming a PostgreSQL add-on next to its three drains, and the linked-application path by running from a directory whose .clever.json sits in a parent: ℹ Drains of the linked application 'billing-api' (app_5cd7548d-…), with --org still taking over when given.

The error paths behave as intended:

clever drain --org orga_11111111-1111-4111-8111-111111111111  # [ERROR] Organisation not found
clever drain --org definitely-not-an-org                      # [ERROR] Organisation not found
clever drain --org ""                                         # same as no --org
clever drain --org "Clever Cloud" --app foo                   # [ERROR] `--org` cannot be combined with …

[github-actions]

🔎 A preview has been automatically published!

If you created the alias to the preview script, you can run this command to download and install this preview:

clever-preview update feat-drain-list-all

You can also run it from your local repository:

./scripts/preview.js update feat-drain-list-all

OS	SHA256 checksum
🐧 linux	2a66a7904b84d223eaeac956567c6b55b82a8c287c0866e5255d9f1709a2b219
🍏 macos	1126ce07311aa89ccc43c1e32cced8961da799cfaf399e7e87be7bb70ca73f4d

This preview will be deleted once this PR is closed.

[KannarFr]

Tested, it works.