clever-tools 4.4.1 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clever-tools",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "description": "Command Line Interface for Clever Cloud.",
   "keywords": [
     "cli",
@@ -37,54 +37,62 @@
     "scripts/*.sh"
   ],
   "scripts": {
-    "fix-all": "npm run lint:fix && npm run format",
+    "docs": "node scripts/generate-docs.js",
+    "docs:check": "node scripts/generate-docs.js --check",
+    "fix-all": "npm run lint:fix && npm run docs && npm run format",
     "format": "prettier . --write",
     "format:check": "prettier . --check",
     "install-local:cliparse": "(cd ../cliparse-node && npm pack) && mv ../cliparse-node/cliparse-*.tgz . && npm i -f ./cliparse-*.tgz",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
-    "validate": "npm run lint && npm run format:check && npm run typecheck",
+    "validate": "npm run lint && npm run format:check && npm run typecheck && npm run docs:check",
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@clevercloud/client": "11.2.0",
+    "@babel/traverse": "7.28.5",
+    "@clevercloud/client": "11.3.0",
     "@inquirer/prompts": "7.8.4",
     "char-regex": "2.0.2",
     "cliparse": "0.5.0",
-    "dedent": "1.6.0",
-    "eventsource": "4.0.0",
-    "ioredis": "5.7.0",
-    "iso8601-duration": "2.1.2",
-    "isomorphic-git": "1.33.1",
+    "dedent": "1.7.0",
+    "eventsource": "4.1.0",
+    "ioredis": "5.8.2",
+    "iso8601-duration": "2.1.3",
+    "isomorphic-git": "1.35.1",
     "linux-release-info": "3.0.0",
     "lodash": "4.17.21",
     "open": "10.2.0",
-    "semver": "7.7.2",
+    "semver": "7.7.3",
     "slugify": "1.6.6",
-    "tldts": "7.0.12",
+    "tldts": "7.0.19",
     "update-notifier": "7.3.1",
-    "xdg": "0.1.1"
+    "xdg": "0.1.1",
+    "zod": "4.1.13"
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.876.0",
-    "@clevercloud/eslint-config": "1.0.1",
+    "@aws-sdk/client-s3": "3.940.0",
+    "@clevercloud/eslint-config": "1.1.0",
     "@commitlint/cli": "19.8.1",
     "@commitlint/config-conventional": "19.8.1",
     "@eslint/compat": "1.3.2",
     "@rollup/plugin-commonjs": "28.0.6",
     "@rollup/plugin-json": "6.1.0",
-    "@rollup/plugin-node-resolve": "16.0.1",
+    "@rollup/plugin-node-resolve": "16.0.3",
     "@types/mime-types": "3.0.1",
-    "@yao-pkg/pkg": "6.6.0",
-    "eslint": "9.34.0",
-    "globals": "16.3.0",
-    "mime-types": "3.0.1",
-    "prettier": "3.6.2",
-    "prettier-plugin-organize-imports": "4.2.0",
-    "rollup": "4.49.0",
-    "simple-git": "3.28.0",
-    "tinyglobby": "0.2.14",
-    "typescript": "5.9.2"
+    "@types/picomatch": "4.0.2",
+    "@yao-pkg/pkg": "6.10.1",
+    "eslint": "9.39.1",
+    "globals": "16.5.0",
+    "mime-types": "3.0.2",
+    "prettier": "3.7.3",
+    "prettier-plugin-organize-imports": "4.3.0",
+    "remark-parse": "11.0.0",
+    "remark-stringify": "11.0.0",
+    "rollup": "4.53.3",
+    "simple-git": "3.30.0",
+    "tinyglobby": "0.2.15",
+    "typescript": "5.9.3",
+    "unified": "11.0.5"
   },
   "engines": {
     "node": ">=22"

package/src/commands/README.md

@@ -0,0 +1,65 @@
+# clever-tools reference
+
+This directory contains the documentation for all `clever` CLI commands.
+
+## ⚙️ Global options
+
+These options are available for all commands:
+
+|Name|Description|
+|---|---|
+|`--color`|Choose whether to print colors or not. You can also use --no-color|
+|`-v`, `--verbose`|Verbose output|
+|`--update-notifier`|Choose whether to use update notifier or not. You can also use --no-update-notifier|
+
+## ➡️ Commands
+
+|Command|Description|
+|---|---|
+|[`clever accesslogs`](./accesslogs/accesslogs.docs.md)|Fetch access logs|
+|[`clever activity`](./activity/activity.docs.md)|Show last deployments of an application|
+|[`clever addon`](./addon/addon.docs.md)|Manage add-ons|
+|[`clever applications`](./applications/applications.docs.md)|List linked applications|
+|[`clever cancel-deploy`](./cancel-deploy/cancel-deploy.docs.md)|Cancel an ongoing deployment|
+|[`clever config`](./config/config.docs.md)|Display or edit the configuration of your application|
+|[`clever console`](./console/console.docs.md)|Open an application in the Console|
+|[`clever create`](./create/create.docs.md)|Create an application|
+|[`clever curl`](./curl/curl.docs.md)|Query Clever Cloud's API using Clever Tools credentials|
+|[`clever database`](./database/database.docs.md)|Manage databases and backups|
+|[`clever delete`](./delete/delete.docs.md)|Delete an application|
+|[`clever deploy`](./deploy/deploy.docs.md)|Deploy an application|
+|[`clever diag`](./diag/diag.docs.md)|Diagnose the current installation (prints various informations for support)|
+|[`clever domain`](./domain/domain.docs.md)|Manage domain names for an application|
+|[`clever drain`](./drain/drain.docs.md)|Manage drains|
+|[`clever emails`](./emails/emails.docs.md)|Manage email addresses of the current user|
+|[`clever env`](./env/env.docs.md)|Manage environment variables of an application|
+|[`clever features`](./features/features.docs.md)|Manage Clever Tools experimental features|
+|[`clever help`](./help/help.docs.md)|Display help about the Clever Cloud CLI|
+|[`clever k8s`](./k8s/k8s.docs.md)|Manage Kubernetes clusters|
+|[`clever keycloak`](./keycloak/keycloak.docs.md)|Manage Clever Cloud Keycloak services|
+|[`clever kv`](./kv/kv.docs.md)|Send a raw command to a Materia KV or Redis® add-on|
+|[`clever link`](./link/link.docs.md)|Link this repo to an existing application|
+|[`clever login`](./login/login.docs.md)|Login to Clever Cloud|
+|[`clever logout`](./logout/logout.docs.md)|Logout from Clever Cloud|
+|[`clever logs`](./logs/logs.docs.md)|Fetch application logs, continuously|
+|[`clever make-default`](./make-default/make-default.docs.md)|Make a linked application the default one|
+|[`clever matomo`](./matomo/matomo.docs.md)|Manage Clever Cloud Matomo services|
+|[`clever metabase`](./metabase/metabase.docs.md)|Manage Clever Cloud Metabase services|
+|[`clever ng`](./ng/ng.docs.md)|List Network Groups|
+|[`clever notify-email`](./notify-email/notify-email.docs.md)|Manage email notifications|
+|[`clever open`](./open/open.docs.md)|Open an application in the Console|
+|[`clever otoroshi`](./otoroshi/otoroshi.docs.md)|Manage Clever Cloud Otoroshi services|
+|[`clever profile`](./profile/profile.docs.md)|Display the profile of the current user|
+|[`clever published-config`](./published-config/published-config.docs.md)|Manage the configuration made available to other applications by this application|
+|[`clever restart`](./restart/restart.docs.md)|Start or restart an application|
+|[`clever scale`](./scale/scale.docs.md)|Change scalability of an application|
+|[`clever service`](./service/service.docs.md)|Manage service dependencies|
+|[`clever ssh`](./ssh/ssh.docs.md)|Connect to running instances through SSH|
+|[`clever ssh-keys`](./ssh-keys/ssh-keys.docs.md)|Manage SSH keys of the current user|
+|[`clever status`](./status/status.docs.md)|See the status of an application|
+|[`clever stop`](./stop/stop.docs.md)|Stop a running application|
+|[`clever tcp-redirs`](./tcp-redirs/tcp-redirs.docs.md)|Control the TCP redirections from reverse proxies to your application|
+|[`clever tokens`](./tokens/tokens.docs.md)|Manage API tokens to query Clever Cloud API from https://api-bridge.clever-cloud.com|
+|[`clever unlink`](./unlink/unlink.docs.md)|Unlink this repo from an existing application|
+|[`clever version`](./version/version.docs.md)|Display the clever-tools version|
+|[`clever webhooks`](./webhooks/webhooks.docs.md)|Manage webhooks|

package/src/commands/accesslogs/accesslogs.command.js

@@ -0,0 +1,158 @@
+import { ApplicationAccessLogStream } from '@clevercloud/client/esm/streams/access-logs.js';
+import { formatTable } from '../../format-table.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import * as Application from '../../models/application.js';
+import { JsonArray } from '../../models/json-array.js';
+import { getHostAndTokens } from '../../models/send-to-api.js';
+import { truncateWithEllipsis } from '../../models/utils.js';
+import {
+  addonIdOption,
+  afterOption,
+  aliasOption,
+  appIdOrNameOption,
+  beforeOption,
+  logsFormatOption,
+} from '../global.options.js';
+
+const THROTTLE_ELEMENTS = 2000;
+
+const THROTTLE_PER_IN_MILLISECONDS = 100;
+
+const CITY_MAX_LENGTH = 20;
+
+function formatHuman(log) {
+  const { date, http, source } = log;
+  const country = source.countryCode ?? '(unknown)';
+  const hasSourceCity = source.city ?? '';
+
+  return formatTable(
+    [
+      [
+        styleText('grey', date.toISOString(date)),
+        source.ip,
+        `${country}${hasSourceCity ? '/' + truncateWithEllipsis(CITY_MAX_LENGTH, source.city) : ''}`,
+        colorStatusCode(http.response.statusCode),
+        http.request.method.toString().padEnd(4, ' ') + ' ' + http.request.path,
+      ],
+    ],
+
+    ACCESSLOG_COLUMN_WIDTHS,
+  );
+}
+
+const ACCESSLOG_COLUMN_WIDTHS = [
+  '2024-06-24T08:05:43.880Z',
+  '255.255.255.255',
+  // country / city
+  2 + 1 + CITY_MAX_LENGTH,
+  'XXX',
+  // longest method name
+  'OPTIONS',
+  // path
+];
+
+function colorStatusCode(code) {
+  const codeString = code.toString();
+  if (code >= 500) {
+    return styleText('red', codeString);
+  }
+  if (code >= 400) {
+    return styleText('yellow', codeString);
+  }
+  if (code >= 300) {
+    return styleText('blue', codeString);
+  }
+  if (code >= 200) {
+    return styleText('green', codeString);
+  }
+  return codeString;
+}
+
+export const accesslogsCommand = defineCommand({
+  description: 'Fetch access logs',
+  since: '2.1.0',
+  options: {
+    alias: aliasOption,
+    app: appIdOrNameOption,
+    format: logsFormatOption,
+    before: beforeOption,
+    after: afterOption,
+    addon: addonIdOption,
+  },
+  args: [],
+  async handler(options) {
+    // TODO: drop when add-ons are supported in API
+    if (options.addon) {
+      throw new Error('Access Logs are not available for add-ons yet');
+    }
+
+    const { apiHost, tokens } = await getHostAndTokens();
+    const { alias, app: appIdOrName, format, before: until, after: since } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+
+    const stream = new ApplicationAccessLogStream({
+      apiHost,
+      tokens,
+      ownerId,
+      appId,
+      since,
+      until,
+      throttleElements: THROTTLE_ELEMENTS,
+      throttlePerInMilliseconds: THROTTLE_PER_IN_MILLISECONDS,
+    });
+
+    if (format === 'human') {
+      Logger.println(styleText('yellow', '/!\\ This feature is in Beta testing phase'));
+    }
+
+    if (format === 'json' && !until) {
+      throw new Error('JSON format only works with a limiting parameter such as `before`');
+    }
+
+    // used for 'json' format
+    const jsonArray = new JsonArray();
+
+    stream
+      .on('open', () => {
+        Logger.debug(styleText('blue', `Logs stream (open) ${JSON.stringify({ appId })}`));
+        if (format === 'json') {
+          jsonArray.open();
+        }
+      })
+      .on('error', (event) => {
+        Logger.debug(styleText('red', `Logs stream (error) ${event.error.message}`));
+      })
+      .onLog((log) => {
+        switch (format) {
+          case 'json':
+            jsonArray.push(log);
+            break;
+          case 'json-stream':
+            Logger.printJson(log);
+            break;
+          case 'human':
+          default:
+            // when the connection is cut too early, or for TCP redirections, we don't have HTTP section
+            if (log.http == null) {
+              break;
+            }
+
+            Logger.println(formatHuman(log));
+            break;
+        }
+      });
+
+    // Properly close the stream
+    process.once('SIGINT', (signal) => stream.close(signal));
+
+    const closeReason = await stream.start();
+
+    if (format === 'json') {
+      jsonArray.close();
+    }
+
+    Logger.debug(`stream closed: ${closeReason?.type}`);
+  },
+});

package/src/commands/accesslogs/accesslogs.docs.md

@@ -0,0 +1,20 @@
+# 📖 `clever accesslogs` command reference
+
+## ➡️ `clever accesslogs` <kbd>Since 2.1.0</kbd>
+
+Fetch access logs
+
+```bash
+clever accesslogs [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`--addon` `<addon-id>`|Add-on ID|
+|`--after`, `--since` `<after>`|Fetch logs after this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h)|
+|`-a`, `--alias` `<alias>`|Short name for the application|
+|`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`--before`, `--until` `<before>`|Fetch logs before this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h)|
+|`-F`, `--format` `<format>`|Output format (human, json, json-stream) (default: human)|

package/src/commands/{activity.js → activity/activity.command.js}

@@ -1,12 +1,15 @@
-import { styleText } from '../lib/style-text.js';
-
 import { EventsStream } from '@clevercloud/client/esm/streams/events.js';
-import { formatTable } from '../format-table.js';
-import { Logger } from '../logger.js';
-import * as Activity from '../models/activity.js';
-import * as Application from '../models/application.js';
-import { getHostAndTokens } from '../models/send-to-api.js';
-import { Deferred } from '../models/utils.js';
+import { z } from 'zod';
+import { formatTable } from '../../format-table.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { defineOption } from '../../lib/define-option.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import * as Activity from '../../models/activity.js';
+import * as Application from '../../models/application.js';
+import { getHostAndTokens } from '../../models/send-to-api.js';
+import { Deferred } from '../../models/utils.js';
+import { aliasOption, appIdOrNameOption } from '../global.options.js';
 
 const dtf = new Intl.DateTimeFormat('en', {
   year: 'numeric',
@@ -41,7 +44,6 @@ function getColoredState(state, isLast) {
   return 'UNKNOWN';
 }
 
-// We use examples of maximum width text to have a clean display
 const ACTIVITY_TABLE_COLUMN_WIDTHS = [
   formatDate(Date.now()),
   47,
@@ -75,6 +77,7 @@ function formatActivityLine(event) {
         event.cause,
       ],
     ],
+
     ACTIVITY_TABLE_COLUMN_WIDTHS,
   );
 }
@@ -153,43 +156,70 @@ function getEventHandler(format, follow) {
   }
 }
 
-export async function activity(params) {
-  const { alias, app: appIdOrName, 'show-all': showAll, follow, format } = params.options;
-  const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
-  const events = await Activity.list(ownerId, appId, showAll);
-  const reversedArrayWithIndex = events.reverse().map((event, index, all) => {
-    const isLast = index === all.length - 1;
-    return { ...event, isLast };
-  });
-
-  const handler = getEventHandler(format, follow);
-
-  let lastEvent = reversedArrayWithIndex.reduce(
-    (previousEvent, newEvent) => handleEvent(previousEvent, newEvent, handler),
-    {},
-  );
-
-  if (!follow) {
-    handler.end();
-    return lastEvent;
-  }
+export const activityCommand = defineCommand({
+  description: 'Show last deployments of an application',
+  since: '0.2.3',
+  options: {
+    follow: defineOption({
+      name: 'follow',
+      schema: z.boolean().default(false),
+      description: 'Track new deployments in activity list',
+      aliases: ['f'],
+    }),
+    showAll: defineOption({
+      name: 'show-all',
+      schema: z.boolean().default(false),
+      description: 'Show all activity',
+    }),
+    format: defineOption({
+      name: 'format',
+      schema: z.enum(['human', 'json', 'json-stream']).default('human'),
+      description: 'Output format (human, json, json-stream)',
+      aliases: ['F'],
+      placeholder: 'format',
+    }),
+    alias: aliasOption,
+    app: appIdOrNameOption,
+  },
+  args: [],
+  async handler(options) {
+    const { alias, app: appIdOrName, showAll, follow, format } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+    const events = await Activity.list(ownerId, appId, showAll);
+    const reversedArrayWithIndex = events.reverse().map((event, index, all) => {
+      const isLast = index === all.length - 1;
+      return { ...event, isLast };
+    });
+
+    const handler = getEventHandler(format, follow);
+
+    let lastEvent = reversedArrayWithIndex.reduce(
+      (previousEvent, newEvent) => handleEvent(previousEvent, newEvent, handler),
+      {},
+    );
+
+    if (!follow) {
+      handler.end();
+      return lastEvent;
+    }
 
-  const { apiHost, tokens } = await getHostAndTokens();
-  const eventsStream = new EventsStream({ apiHost, tokens, appId });
+    const { apiHost, tokens } = await getHostAndTokens();
+    const eventsStream = new EventsStream({ apiHost, tokens, appId });
 
-  const deferred = new Deferred();
+    const deferred = new Deferred();
 
-  eventsStream
-    .on('open', () => Logger.debug('WS for events (open) ' + JSON.stringify({ appId })))
-    .on('event', (event) => {
-      lastEvent = onEvent(lastEvent, event, handler);
-      return lastEvent;
-    })
-    .on('ping', () => Logger.debug('WS for events (ping)'))
-    .on('close', ({ reason }) => Logger.debug('WS for events (close) ' + reason))
-    .on('error', deferred.reject);
+    eventsStream
+      .on('open', () => Logger.debug('WS for events (open) ' + JSON.stringify({ appId })))
+      .on('event', (event) => {
+        lastEvent = onEvent(lastEvent, event, handler);
+        return lastEvent;
+      })
+      .on('ping', () => Logger.debug('WS for events (ping)'))
+      .on('close', ({ reason }) => Logger.debug('WS for events (close) ' + reason))
+      .on('error', deferred.reject);
 
-  eventsStream.open({ autoRetry: true, maxRetryCount: 6 });
+    eventsStream.open({ autoRetry: true, maxRetryCount: 6 });
 
-  return deferred.promise;
-}
+    return deferred.promise;
+  },
+});

package/src/commands/activity/activity.docs.md

@@ -0,0 +1,19 @@
+# 📖 `clever activity` command reference
+
+## ➡️ `clever activity` <kbd>Since 0.2.3</kbd>
+
+Show last deployments of an application
+
+```bash
+clever activity [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-a`, `--alias` `<alias>`|Short name for the application|
+|`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+|`-f`, `--follow`|Track new deployments in activity list|
+|`-F`, `--format` `<format>`|Output format (human, json, json-stream) (default: human)|
+|`--show-all`|Show all activity|

package/src/commands/addon/addon.args.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { defineArgument } from '../../lib/define-argument.js';
+
+export const addonProviderArg = defineArgument({
+  schema: z.string(),
+  description: 'Add-on provider',
+  placeholder: 'addon-provider',
+});
+
+export const addonNameArg = defineArgument({
+  schema: z.string(),
+  description: 'Add-on name',
+  placeholder: 'addon-name',
+});

package/src/commands/addon/addon.command.js

@@ -0,0 +1,7 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { addonListCommand } from './addon.list.command.js';
+
+export const addonCommand = defineCommand({
+  ...addonListCommand,
+  description: 'Manage add-ons',
+});