clever-tools 4.4.1 → 4.5.0

package/src/commands/stop/stop.command.js

@@ -0,0 +1,23 @@
+import { undeploy as stopApplication } from '@clevercloud/client/esm/api/v2/application.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import * as Application from '../../models/application.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { aliasOption, appIdOrNameOption } from '../global.options.js';
+
+export const stopCommand = defineCommand({
+  description: 'Stop a running application',
+  since: '0.2.0',
+  options: {
+    alias: aliasOption,
+    app: appIdOrNameOption,
+  },
+  args: [],
+  async handler(options) {
+    const { alias, app: appIdOrName } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+
+    await stopApplication({ id: ownerId, appId }).then(sendToApi);
+    Logger.printSuccess('Application successfully stopped!');
+  },
+});

package/src/commands/stop/stop.docs.md

@@ -0,0 +1,16 @@
+# 📖 `clever stop` command reference
+
+## ➡️ `clever stop` <kbd>Since 0.2.0</kbd>
+
+Stop a running application
+
+```bash
+clever stop [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)|

package/src/commands/tcp-redirs/tcp-redirs.add.command.js

@@ -0,0 +1,24 @@
+import { addTcpRedir } from '@clevercloud/client/esm/api/v2/application.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import * as Application from '../../models/application.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { aliasOption, appIdOrNameOption } from '../global.options.js';
+import { namespaceOption } from './tcp-redirs.options.js';
+
+export const tcpRedirsAddCommand = defineCommand({
+  description: 'Add a new TCP redirection to the application',
+  since: '2.3.0',
+  options: {
+    namespace: namespaceOption,
+    alias: aliasOption,
+    app: appIdOrNameOption,
+  },
+  args: [],
+  async handler(options) {
+    const { alias, app: appIdOrName, namespace } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+    const { port } = await addTcpRedir({ id: ownerId, appId }, { namespace }).then(sendToApi);
+    Logger.println('Successfully added tcp redirection on port: ' + port);
+  },
+});

package/src/commands/tcp-redirs/tcp-redirs.command.js

@@ -0,0 +1,41 @@
+import { getTcpRedirs } from '@clevercloud/client/esm/api/v2/application.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import * as Application from '../../models/application.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { aliasOption, appIdOrNameOption, humanJsonOutputFormatOption } from '../global.options.js';
+
+export const tcpRedirsCommand = defineCommand({
+  description: 'Control the TCP redirections from reverse proxies to your application',
+  since: '2.3.0',
+  options: {
+    alias: aliasOption,
+    app: appIdOrNameOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [],
+  async handler(options) {
+    const { alias, app: appIdOrName, format } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+
+    const redirs = await getTcpRedirs({ id: ownerId, appId }).then(sendToApi);
+
+    switch (format) {
+      case 'json': {
+        Logger.printJson(redirs);
+        break;
+      }
+      case 'human':
+      default: {
+        if (redirs.length === 0) {
+          Logger.println('No active TCP redirection for this application');
+        } else {
+          Logger.println('Enabled TCP redirections:');
+          for (const { namespace, port } of redirs) {
+            Logger.println(port + ' on ' + namespace);
+          }
+        }
+      }
+    }
+  },
+});

package/src/commands/tcp-redirs/tcp-redirs.docs.md

@@ -0,0 +1,71 @@
+# 📖 `clever tcp-redirs` command reference
+
+## ➡️ `clever tcp-redirs` <kbd>Since 2.3.0</kbd>
+
+Control the TCP redirections from reverse proxies to your application
+
+```bash
+clever tcp-redirs [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`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever tcp-redirs add` <kbd>Since 2.3.0</kbd>
+
+Add a new TCP redirection to the application
+
+```bash
+clever tcp-redirs add --namespace <namespace> [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`--namespace` `<namespace>`|Namespace in which the TCP redirection should be **(required)**|
+|`-a`, `--alias` `<alias>`|Short name for the application|
+|`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|
+
+## ➡️ `clever tcp-redirs list-namespaces` <kbd>Since 2.3.0</kbd>
+
+List the namespaces in which you can create new TCP redirections
+
+```bash
+clever tcp-redirs list-namespaces [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`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever tcp-redirs remove` <kbd>Since 2.3.0</kbd>
+
+Remove a TCP redirection from the application
+
+```bash
+clever tcp-redirs remove --namespace <namespace> <port> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`port`|port identifying the TCP redirection|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`--namespace` `<namespace>`|Namespace in which the TCP redirection should be **(required)**|
+|`-a`, `--alias` `<alias>`|Short name for the application|
+|`--app` `<app-id\|app-name>`|Application to manage by its ID (or name, if unambiguous)|

package/src/commands/tcp-redirs/tcp-redirs.list-namespaces.command.js

@@ -0,0 +1,48 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import * as Application from '../../models/application.js';
+import * as Namespaces from '../../models/namespaces.js';
+import { aliasOption, appIdOrNameOption, humanJsonOutputFormatOption } from '../global.options.js';
+
+export const tcpRedirsListNamespacesCommand = defineCommand({
+  description: 'List the namespaces in which you can create new TCP redirections',
+  since: '2.3.0',
+  options: {
+    alias: aliasOption,
+    app: appIdOrNameOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [],
+  async handler(options) {
+    const { alias, app: appIdOrName, format } = options;
+    const { ownerId } = await Application.resolveId(appIdOrName, alias);
+
+    const namespaces = await Namespaces.getNamespaces(ownerId);
+
+    namespaces.sort((a, b) => a.namespace.localeCompare(b.namespace));
+
+    switch (format) {
+      case 'json': {
+        Logger.printJson(namespaces);
+        break;
+      }
+      case 'human':
+      default: {
+        Logger.println('Available namespaces:');
+        namespaces.forEach(({ namespace }) => {
+          switch (namespace) {
+            case 'cleverapps':
+              Logger.println(`- ${namespace}: for redirections used with 'cleverapps.io' domain`);
+              break;
+            case 'default':
+              Logger.println(`- ${namespace}: for redirections used with custom domains`);
+              break;
+            default:
+              Logger.println(`- ${namespace}`);
+          }
+        });
+        break;
+      }
+    }
+  },
+});

package/src/commands/tcp-redirs/tcp-redirs.options.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { defineOption } from '../../lib/define-option.js';
+import { completeNamespaces } from '../../models/namespaces.js';
+
+export const namespaceOption = defineOption({
+  name: 'namespace',
+  schema: z.string(),
+  description: 'Namespace in which the TCP redirection should be',
+  placeholder: 'namespace',
+  complete: completeNamespaces,
+});

package/src/commands/tcp-redirs/tcp-redirs.remove.command.js

@@ -0,0 +1,34 @@
+import { removeTcpRedir } from '@clevercloud/client/esm/api/v2/application.js';
+import { z } from 'zod';
+import { defineArgument } from '../../lib/define-argument.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import * as Application from '../../models/application.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { aliasOption, appIdOrNameOption } from '../global.options.js';
+import { namespaceOption } from './tcp-redirs.options.js';
+
+export const tcpRedirsRemoveCommand = defineCommand({
+  description: 'Remove a TCP redirection from the application',
+  since: '2.3.0',
+  options: {
+    namespace: namespaceOption,
+    alias: aliasOption,
+    app: appIdOrNameOption,
+  },
+  args: [
+    defineArgument({
+      schema: z.coerce.number().int().min(1025, 65535),
+      description: 'port identifying the TCP redirection',
+      placeholder: 'port',
+    }),
+  ],
+  async handler(options, port) {
+    const { alias, app: appIdOrName, namespace } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+
+    await removeTcpRedir({ id: ownerId, appId, sourcePort: port, namespace }).then(sendToApi);
+
+    Logger.println('Successfully removed tcp redirection.');
+  },
+});

package/src/commands/tokens/tokens.command.js

@@ -0,0 +1,43 @@
+import { listApiTokens } from '../../clever-client/auth-bridge.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { formatDate } from '../../lib/format-date.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import { conf } from '../../models/configuration.js';
+import { sendToAuthBridge } from '../../models/send-to-api.js';
+import { humanJsonOutputFormatOption } from '../global.options.js';
+
+export const tokensCommand = defineCommand({
+  description: `Manage API tokens to query Clever Cloud API from ${conf.AUTH_BRIDGE_HOST}`,
+  since: '3.12.0',
+  options: {
+    format: humanJsonOutputFormatOption,
+  },
+  args: [],
+  async handler(options) {
+    const { format } = options;
+
+    const tokens = await listApiTokens().then(sendToAuthBridge);
+
+    if (format === 'json') {
+      Logger.printJson(tokens);
+    } else {
+      if (tokens.length === 0) {
+        Logger.println(`ℹ️  No API token found, create one with ${styleText('blue', 'clever tokens create')} command`);
+      } else {
+        console.table(
+          tokens.map((token) => {
+            return {
+              'API token ID': token.apiTokenId,
+              Name: token.name,
+              'Creation IP address': token.ip,
+              Creation: formatDate(token.creationDate),
+              Expiration: formatDate(token.expirationDate),
+              State: token.state,
+            };
+          }),
+        );
+      }
+    }
+  },
+});

package/src/commands/tokens/tokens.create.command.js

@@ -0,0 +1,108 @@
+import dedent from 'dedent';
+import { z } from 'zod';
+import { createApiToken } from '../../clever-client/auth-bridge.js';
+import { defineArgument } from '../../lib/define-argument.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { defineOption } from '../../lib/define-option.js';
+import { formatDate } from '../../lib/format-date.js';
+import { promptSecret } from '../../lib/prompts.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import { conf } from '../../models/configuration.js';
+import { sendToAuthBridge } from '../../models/send-to-api.js';
+import { getCurrent as getCurrentUser } from '../../models/user.js';
+import { futureDateOrDuration } from '../../parsers.js';
+import { humanJsonOutputFormatOption } from '../global.options.js';
+
+export const tokensCreateCommand = defineCommand({
+  description: 'Create an API token',
+  since: '3.12.0',
+  options: {
+    expiration: defineOption({
+      name: 'expiration',
+      schema: z.string().default('1y').transform(futureDateOrDuration),
+      description: 'Duration until API token expiration (e.g.: 1h, 4d, 2w, 6M)',
+      aliases: ['e'],
+      placeholder: 'expiration',
+    }),
+    format: humanJsonOutputFormatOption,
+  },
+  args: [
+    defineArgument({
+      schema: z.string(),
+      description: 'API token name',
+      placeholder: 'api-token-name',
+    }),
+  ],
+  async handler(options, apiTokenName) {
+    const { expiration, format } = options;
+    const user = await getCurrentUser();
+
+    if (!user.hasPassword) {
+      const apiTokenListHref = new URL('/users/me/api-tokens', conf.CONSOLE_URL).href;
+      throw new Error(dedent`
+          ${styleText('yellow', '!')} Your Clever Cloud account is linked via GitHub and has no password. Setting one is required to create API tokens.
+          ${styleText('blue', '→')} To do so, go to the following URL: ${styleText('blue', apiTokenListHref)}
+        `);
+    }
+
+    // Max expiration is 1 year from now
+    const maxExpirationDate = new Date();
+    maxExpirationDate.setFullYear(maxExpirationDate.getFullYear() + 1);
+
+    if (expiration > maxExpirationDate) {
+      throw new Error('You cannot set an expiration date greater than 1 year');
+    }
+    const expirationDate = expiration;
+
+    const password = await promptSecret('Enter your password:');
+
+    let mfaCode;
+    if (user.preferredMFA === 'TOTP') {
+      mfaCode = await promptSecret('Enter your 2FA code:');
+    }
+
+    const tokenData = {
+      email: user.email,
+      password,
+      mfaCode,
+      name: apiTokenName,
+      expirationDate: expirationDate.toISOString(),
+    };
+    const createdToken = await createApiToken(tokenData)
+      .then(sendToAuthBridge)
+      .catch((error) => {
+        const errorCode = error?.cause?.responseBody?.code;
+        if (errorCode === 'invalid-credential') {
+          throw new Error('Invalid credentials, check your password');
+        }
+        if (errorCode === 'invalid-mfa-code') {
+          throw new Error('Invalid credentials, check your 2FA code');
+        }
+        throw error;
+      });
+
+    switch (format) {
+      case 'json':
+        Logger.printJson(createdToken);
+        break;
+      case 'human':
+      default:
+        Logger.println(dedent`
+            ${styleText('green', '✔')} API token successfully created! Store it securely, you won't able to print it again.
+    
+              - API token ID : ${styleText('grey', createdToken.apiTokenId)}
+              - API token    : ${styleText('grey', createdToken.apiToken)}
+              - Expiration   : ${styleText('grey', formatDate(createdToken.expirationDate))}
+    
+            Export this token and use it to make authenticated requests to the Clever Cloud API through the Auth Bridge:
+    
+            export CC_API_TOKEN=${createdToken.apiToken}
+            curl -H "Authorization: Bearer $CC_API_TOKEN" ${conf.AUTH_BRIDGE_HOST}/v2/self
+    
+            Then, to revoke this token, run:
+            clever tokens revoke ${createdToken.apiTokenId}
+          `);
+    }
+  },
+});

package/src/commands/tokens/tokens.docs.md

@@ -0,0 +1,50 @@
+# 📖 `clever tokens` command reference
+
+## ➡️ `clever tokens` <kbd>Since 3.12.0</kbd>
+
+Manage API tokens to query Clever Cloud API from https://api-bridge.clever-cloud.com
+
+```bash
+clever tokens [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever tokens create` <kbd>Since 3.12.0</kbd>
+
+Create an API token
+
+```bash
+clever tokens create <api-token-name> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`api-token-name`|API token name|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-e`, `--expiration` `<expiration>`|Duration until API token expiration (e.g.: 1h, 4d, 2w, 6M) (default: 1y)|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever tokens revoke` <kbd>Since 3.12.0</kbd>
+
+Revoke an API token
+
+```bash
+clever tokens revoke <api-token-id>
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`api-token-id`|API token ID|

package/src/commands/tokens/tokens.revoke.command.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { deleteApiToken } from '../../clever-client/auth-bridge.js';
+import { defineArgument } from '../../lib/define-argument.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import { sendToAuthBridge } from '../../models/send-to-api.js';
+
+export const tokensRevokeCommand = defineCommand({
+  description: 'Revoke an API token',
+  since: '3.12.0',
+  options: {},
+  args: [
+    defineArgument({
+      schema: z.string(),
+      description: 'API token ID',
+      placeholder: 'api-token-id',
+    }),
+  ],
+  async handler(_options, apiTokenId) {
+    await deleteApiToken(apiTokenId).then(sendToAuthBridge);
+
+    Logger.println(styleText('green', '✔'), 'API token successfully revoked!');
+  },
+});

package/src/commands/unlink/unlink.command.js

@@ -0,0 +1,21 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import * as AppConfig from '../../models/app_configuration.js';
+import * as Application from '../../models/application.js';
+import { aliasArg } from '../global.args.js';
+
+export const unlinkCommand = defineCommand({
+  description: 'Unlink this repo from an existing application',
+  since: '0.2.0',
+  options: {},
+  args: [aliasArg],
+  async handler(_options, alias) {
+    const app = await AppConfig.getAppDetails({ alias });
+
+    await Application.unlinkRepo(app.alias);
+    Logger.printSuccess(
+      `Application ${styleText('green', app.appId)} has been successfully unlinked from local alias ${styleText('green', app.alias)}!`,
+    );
+  },
+});

package/src/commands/unlink/unlink.docs.md

@@ -0,0 +1,15 @@
+# 📖 `clever unlink` command reference
+
+## ➡️ `clever unlink` <kbd>Since 0.2.0</kbd>
+
+Unlink this repo from an existing application
+
+```bash
+clever unlink <app-alias>
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`app-alias`|Application alias|

package/src/commands/version/version.command.js

@@ -0,0 +1,13 @@
+import pkg from '../../../package.json' with { type: 'json' };
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+
+export const versionCommand = defineCommand({
+  description: 'Display the clever-tools version',
+  since: '1.0.0',
+  options: {},
+  args: [],
+  async handler() {
+    Logger.println(pkg.version);
+  },
+});

package/src/commands/version/version.docs.md

@@ -0,0 +1,9 @@
+# 📖 `clever version` command reference
+
+## ➡️ `clever version` <kbd>Since 1.0.0</kbd>
+
+Display the clever-tools version
+
+```bash
+clever version
+```

package/src/commands/webhooks/webhooks.add.command.js

@@ -0,0 +1,51 @@
+import { createWebhook } from '@clevercloud/client/esm/api/v2/notification.js';
+import { z } from 'zod';
+import { defineArgument } from '../../lib/define-argument.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { defineOption } from '../../lib/define-option.js';
+import { Logger } from '../../logger.js';
+import { getOwnerAndApp } from '../../models/notification.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { notificationNameArg } from '../global.args.js';
+import { notificationEventTypeOption, notificationScopeOption, orgaIdOrNameOption } from '../global.options.js';
+
+export const webhooksAddCommand = defineCommand({
+  description: 'Register webhook to be called when events happen',
+  since: '0.6.0',
+  options: {
+    format: defineOption({
+      name: 'format',
+      schema: z.string().default('raw'),
+      description: "Format of the body sent to the webhook ('raw', 'slack', 'gitter', or 'flowdock')",
+      placeholder: 'format',
+    }),
+    org: orgaIdOrNameOption,
+    event: notificationEventTypeOption,
+    service: notificationScopeOption,
+  },
+  args: [
+    notificationNameArg,
+    defineArgument({
+      schema: z.string(),
+      description: 'Webhook URL',
+      placeholder: 'url',
+    }),
+  ],
+  async handler(options, name, hookUrl) {
+    const { org, format, event: events, service } = options;
+
+    // TODO: fix alias option
+    const { ownerId, appId } = await getOwnerAndApp(null, org, !org && !service);
+
+    const body = {
+      name,
+      urls: [{ format, url: hookUrl }],
+      scope: appId != null && service == null ? [appId] : service,
+      events,
+    };
+
+    await createWebhook({ ownerId }, body).then(sendToApi);
+
+    Logger.println('The webhook has been added');
+  },
+});

package/src/commands/webhooks/webhooks.command.js

@@ -0,0 +1,57 @@
+import { getWebhooks } from '@clevercloud/client/esm/api/v2/notification.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import { getOwnerAndApp } from '../../models/notification.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { humanJsonOutputFormatOption, listAllNotificationsOption, orgaIdOrNameOption } from '../global.options.js';
+
+export const webhooksCommand = defineCommand({
+  description: 'Manage webhooks',
+  since: '0.6.0',
+  options: {
+    org: orgaIdOrNameOption,
+    listAll: listAllNotificationsOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [],
+  async handler(options) {
+    const { org, listAll, format } = options;
+
+    // TODO: fix alias option
+    const { ownerId, appId } = await getOwnerAndApp(null, org, !listAll);
+    const hooks = await getWebhooks({ ownerId }).then(sendToApi);
+
+    const formattedHooks = hooks
+      .filter((hook) => {
+        const emptyScope = !hook.scope || hook.scope.length === 0;
+        return !appId || emptyScope || hook.scope.includes(appId);
+      })
+      .map((hook) => ({
+        id: hook.id,
+        name: hook.name,
+        ownerId: hook.ownerId,
+        services: hook.scope ?? [hook.ownerId],
+        events: hook.events ?? ['ALL'],
+        urls: hook.urls,
+      }));
+
+    switch (format) {
+      case 'json': {
+        Logger.printJson(formattedHooks);
+        break;
+      }
+      case 'human':
+      default: {
+        formattedHooks.forEach((hook) => {
+          Logger.println(hook.name ? styleText('bold', hook.name) : hook.id);
+          Logger.println(`  id: ${hook.id}`);
+          Logger.println(`  services: ${hook.services.join(', ')}`);
+          Logger.println(`  events: ${hook.events.join(', ')}`);
+          Logger.println('  hooks:');
+          hook.urls.forEach((url) => Logger.println(`    ${url.url} (${url.format})`));
+        });
+      }
+    }
+  },
+});