clever-tools 4.4.0 → 4.5.0

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

@@ -0,0 +1,236 @@
+import dedent from 'dedent';
+import { z } from 'zod';
+import { getOperator } from '../../clever-client/operators.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 Addon from '../../models/addon.js';
+import { completePlan, completeRegion, parseAddonOptions } from '../../models/addon.js';
+import * as AppConfig from '../../models/app_configuration.js';
+import { listAvailableAliases } from '../../models/application.js';
+import { conf } from '../../models/configuration.js';
+import * as Organisation from '../../models/organisation.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import * as User from '../../models/user.js';
+import { addonOptions } from '../../parsers.js';
+import { humanJsonOutputFormatOption, orgaIdOrNameOption } from '../global.options.js';
+import { addonNameArg, addonProviderArg } from './addon.args.js';
+
+const ADDON_PROVIDERS = {
+  keycloak: {
+    name: 'Keycloak',
+    isOperator: true,
+    postCreateInstructions: `Learn more about Keycloak on Clever Cloud: ${conf.DOC_URL}/addons/keycloak/`,
+  },
+  kv: {
+    name: 'Materia KV',
+    isOperator: false,
+    status: 'beta',
+    postCreateInstructions: (addonId) => dedent`
+      ${styleText('yellow', "You can easily use Materia KV with 'redis-cli', with such commands:")}
+      ${styleText('blue', `source <(clever addon env ${addonId} -F shell)`)}
+      ${styleText('blue', 'redis-cli -h $KV_HOST -p $KV_PORT --tls')}
+      Learn more about Materia KV on Clever Cloud: ${conf.DOC_URL}/addons/materia-kv/
+    `,
+  },
+  'addon-matomo': {
+    name: 'Matomo',
+    isOperator: true,
+    postCreateInstructions: `Learn more about Matomo on Clever Cloud: ${conf.DOC_URL}/addons/matomo/`,
+  },
+  metabase: {
+    name: 'Metabase',
+    isOperator: true,
+    postCreateInstructions: `Learn more about Metabase on Clever Cloud: ${conf.DOC_URL}/addons/metabase/`,
+  },
+  otoroshi: {
+    name: 'Otoroshi with LLM',
+    isOperator: true,
+    postCreateInstructions: `Learn more about Otoroshi with LLM on Clever Cloud: ${conf.DOC_URL}/addons/otoroshi/`,
+  },
+  'addon-pulsar': {
+    name: 'Pulsar',
+    isOperator: false,
+    postCreateInstructions: `Learn more about Pulsar on Clever Cloud: ${conf.DOC_URL}/addons/pulsar/`,
+  },
+};
+
+export const addonCreateCommand = defineCommand({
+  description: 'Create an add-on',
+  since: '0.2.3',
+  options: {
+    link: defineOption({
+      name: 'link',
+      schema: z.string().optional(),
+      description: 'Link the created add-on to the app with the specified alias',
+      aliases: ['l'],
+      placeholder: 'alias',
+      complete: listAvailableAliases,
+    }),
+    yes: defineOption({
+      name: 'yes',
+      schema: z.boolean().default(false),
+      description: 'Skip confirmation even if the add-on is not free',
+      aliases: ['y'],
+    }),
+    plan: defineOption({
+      name: 'plan',
+      schema: z.string().default(''),
+      description: 'Add-on plan, depends on the provider',
+      aliases: ['p'],
+      placeholder: 'plan',
+      complete: completePlan,
+    }),
+    region: defineOption({
+      name: 'region',
+      schema: z.string().default('par'),
+      description: 'Region to provision the add-on in, depends on the provider',
+      aliases: ['r'],
+      placeholder: 'region',
+      complete: completeRegion,
+    }),
+    version: defineOption({
+      name: 'addon-version',
+      schema: z.string().optional(),
+      description: 'The version to use for the add-on',
+      placeholder: 'addon-version',
+    }),
+    option: defineOption({
+      name: 'option',
+      schema: z.string().transform(addonOptions).optional(),
+      description:
+        'Option to enable for the add-on. Multiple --option argument can be passed to enable multiple options',
+      placeholder: 'option',
+    }),
+    org: orgaIdOrNameOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [addonProviderArg, addonNameArg],
+  async handler(options, providerName, name) {
+    const {
+      link: linkedAppAlias,
+      plan: planName,
+      region,
+      yes: skipConfirmation,
+      org: orgaIdOrName,
+      format,
+      version,
+      option: addonOptions,
+    } = options;
+
+    const addonToCreate = {
+      name,
+      providerName,
+      planName,
+      region,
+      skipConfirmation,
+      version: version,
+      addonOptions: parseAddonOptions(addonOptions),
+    };
+
+    const ownerId = orgaIdOrName != null ? await Organisation.getId(orgaIdOrName) : await User.getCurrentId();
+    if (linkedAppAlias != null) {
+      const linkedAppData = await AppConfig.getAppDetails({ alias: linkedAppAlias });
+      if (orgaIdOrName != null && linkedAppData.ownerId !== ownerId && format === 'human') {
+        Logger.warn(
+          'The specified application does not belong to the specified organisation. Ignoring the `--org` option',
+        );
+      }
+      addonToCreate.ownerId = linkedAppData.ownerId;
+    } else {
+      addonToCreate.ownerId = ownerId;
+    }
+
+    const newAddon = await Addon.create(addonToCreate);
+
+    if (linkedAppAlias != null) {
+      const linkedAppData = await AppConfig.getAppDetails({ alias: linkedAppAlias });
+      await Addon.link(linkedAppData.ownerId, linkedAppData.appId, { addon_id: newAddon.id });
+    }
+
+    const provider = ADDON_PROVIDERS[providerName];
+    let statusMessage = '';
+    if (provider?.status) {
+      statusMessage = `The ${provider.name} provider is in ${provider.status} testing phase`;
+      if (provider.status === 'alpha') {
+        statusMessage += ". Don't store sensitive or production grade data.";
+      }
+    }
+
+    // JSON format
+    if (format === 'json') {
+      const jsonAddon = {
+        id: newAddon.id,
+        realId: newAddon.realId,
+        name: newAddon.name,
+        env: newAddon.env,
+      };
+
+      if (provider?.status) {
+        jsonAddon.availability = provider.status;
+        jsonAddon.message = statusMessage;
+      }
+
+      Logger.printJson(jsonAddon);
+      return;
+    }
+
+    // Human format
+    if (linkedAppAlias != null) {
+      Logger.println(`Add-on created and linked to application ${linkedAppAlias} successfully!`);
+    } else {
+      Logger.println('Add-on created successfully!');
+    }
+
+    Logger.println(`ID: ${newAddon.id}`);
+    Logger.println(`Real ID: ${newAddon.realId}`);
+    Logger.println(`Name: ${newAddon.name}`);
+
+    const operator = ADDON_PROVIDERS[providerName]?.isOperator
+      ? await getOperator({ provider: providerName, realId: newAddon.realId }).then(sendToApi)
+      : null;
+
+    if (operator) {
+      if (operator.accessUrl) {
+        Logger.println();
+        Logger.println(`Your ${ADDON_PROVIDERS[providerName].name} is starting:`);
+        Logger.println(` - Access it: ${operator.accessUrl}`);
+        Logger.println(` - Manage it: ${conf.GOTO_URL}/${newAddon.id}`);
+      }
+
+      if (operator.initialCredentials) {
+        if (providerName === 'keycloak') {
+          Logger.println();
+          Logger.println(
+            "An initial account has been created, you'll be invited to change the password at first login:",
+          );
+          Logger.println(` - Admin user name: ${operator.initialCredentials.user}`);
+          Logger.println(` - Temporary password: ${operator.initialCredentials.password}`);
+        }
+        if (providerName === 'otoroshi') {
+          Logger.println();
+          Logger.println(
+            'An initial account has been created, change the password at first login (Security -> Administrators -> Edit user):',
+          );
+          Logger.println(` - Admin user name: ${operator.initialCredentials.user}`);
+          Logger.println(` - Password: ${operator.initialCredentials.password}`);
+        }
+      }
+    }
+
+    if (provider?.postCreateInstructions) {
+      Logger.println();
+
+      if (statusMessage !== '') {
+        Logger.println(styleText('yellow', `/!\\ ${statusMessage}`));
+      }
+
+      if (typeof provider.postCreateInstructions === 'function') {
+        Logger.println(provider.postCreateInstructions(newAddon.id));
+      } else {
+        Logger.println(provider.postCreateInstructions);
+      }
+    }
+  },
+});

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

@@ -0,0 +1,32 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import * as Addon from '../../models/addon.js';
+import * as Organisation from '../../models/organisation.js';
+import { addonIdOrNameArg } from '../global.args.js';
+import { confirmAddonDeletionOption, orgaIdOrNameOption } from '../global.options.js';
+
+export const addonDeleteCommand = defineCommand({
+  description: 'Delete an add-on',
+  since: '0.2.3',
+  options: {
+    org: orgaIdOrNameOption,
+    yes: confirmAddonDeletionOption,
+  },
+  args: [addonIdOrNameArg],
+  async handler(options, addon) {
+    const { yes: skipConfirmation, org: orgaIdOrName } = options;
+
+    let ownerId = await Organisation.getId(orgaIdOrName);
+    if (ownerId == null && addon.addon_id != null) {
+      ownerId = await Addon.findOwnerId(ownerId, addon.addon_id);
+    }
+    if (ownerId == null && addon.addon_name != null) {
+      const foundAddon = await Addon.findByName(addon.addon_name);
+      ownerId = foundAddon.orgaId;
+    }
+
+    await Addon.deleteAddon(ownerId, addon, skipConfirmation);
+
+    Logger.println(`Addon ${addon.addon_id || addon.addon_name} successfully deleted`);
+  },
+});

package/src/commands/addon/addon.docs.md

@@ -0,0 +1,156 @@
+# 📖 `clever addon` command reference
+
+## ➡️ `clever addon` <kbd>Since 0.2.3</kbd>
+
+Manage add-ons
+
+```bash
+clever addon [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|
+
+## ➡️ `clever addon create` <kbd>Since 0.2.3</kbd>
+
+Create an add-on
+
+```bash
+clever addon create <addon-provider> <addon-name> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-provider`|Add-on provider|
+|`addon-name`|Add-on name|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`--addon-version` `<addon-version>`|The version to use for the add-on|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+|`-l`, `--link` `<alias>`|Link the created add-on to the app with the specified alias|
+|`--option` `<option>`|Option to enable for the add-on. Multiple --option argument can be passed to enable multiple options|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|
+|`-p`, `--plan` `<plan>`|Add-on plan, depends on the provider|
+|`-r`, `--region` `<region>`|Region to provision the add-on in, depends on the provider (default: par)|
+|`-y`, `--yes`|Skip confirmation even if the add-on is not free|
+
+## ➡️ `clever addon delete` <kbd>Since 0.2.3</kbd>
+
+Delete an add-on
+
+```bash
+clever addon delete <addon-id|addon-name> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|
+|`-y`, `--yes`|Skip confirmation and delete the add-on directly|
+
+## ➡️ `clever addon env` <kbd>Since 2.11.0</kbd>
+
+List environment variables for an add-on
+
+```bash
+clever addon env <addon-id> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id`|Add-on ID or real ID|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json, shell) (default: human)|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|
+
+## ➡️ `clever addon list` <kbd>Since 0.2.3</kbd>
+
+List available add-ons
+
+```bash
+clever addon list [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|
+
+## ➡️ `clever addon providers` <kbd>Since 0.2.3</kbd>
+
+List available add-on providers
+
+```bash
+clever addon providers [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever addon providers show` <kbd>Since 0.2.3</kbd>
+
+Show information about an add-on provider
+
+```bash
+clever addon providers show <addon-provider> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-provider`|Add-on provider|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever addon rename` <kbd>Since 0.3.0</kbd>
+
+Rename an add-on
+
+```bash
+clever addon rename <addon-id|addon-name> <addon-name> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+|`addon-name`|Add-on name|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|

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

@@ -0,0 +1,50 @@
+import { getAllEnvVars } from '@clevercloud/client/esm/api/v2/addon.js';
+import { toNameEqualsValueString } from '@clevercloud/client/esm/utils/env-vars.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 { findOwnerId } from '../../models/addon.js';
+import { resolveAddonId } from '../../models/ids-resolver.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { envFormatOption, orgaIdOrNameOption } from '../global.options.js';
+
+export const addonEnvCommand = defineCommand({
+  description: 'List environment variables for an add-on',
+  since: '2.11.0',
+  options: {
+    org: orgaIdOrNameOption,
+    format: envFormatOption,
+  },
+  args: [
+    defineArgument({
+      schema: z.string(),
+      description: 'Add-on ID or real ID',
+      placeholder: 'addon-id',
+    }),
+  ],
+  async handler(options, addonIdOrRealId) {
+    const { org, format } = options;
+
+    const addonId = await resolveAddonId(addonIdOrRealId);
+    const ownerId = await findOwnerId(org, addonId);
+
+    const envFromAddon = await getAllEnvVars({ id: ownerId, addonId }).then(sendToApi);
+
+    switch (format) {
+      case 'json': {
+        const envFromAddonJson = Object.fromEntries(envFromAddon.map(({ name, value }) => [name, value]));
+        Logger.println(JSON.stringify(envFromAddonJson, null, 2));
+        break;
+      }
+
+      case 'shell':
+        Logger.println(toNameEqualsValueString(envFromAddon, { addExports: true }));
+        break;
+
+      case 'human':
+      default:
+        Logger.println(toNameEqualsValueString(envFromAddon, { addExports: false }));
+    }
+  },
+});

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

@@ -0,0 +1,55 @@
+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 Addon from '../../models/addon.js';
+import * as Organisation from '../../models/organisation.js';
+import { humanJsonOutputFormatOption, orgaIdOrNameOption } from '../global.options.js';
+
+export const addonListCommand = defineCommand({
+  description: 'List available add-ons',
+  since: '0.2.3',
+  options: {
+    org: orgaIdOrNameOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [],
+  async handler(options) {
+    const { org: orgaIdOrName, format } = options;
+
+    const ownerId = await Organisation.getId(orgaIdOrName);
+    const addons = await Addon.list(ownerId);
+
+    switch (format) {
+      case 'json': {
+        const formattedAddons = addons.map((addon) => {
+          return {
+            addonId: addon.id,
+            creationDate: addon.creationDate,
+            name: addon.name,
+            planName: addon.plan.name,
+            planSlug: addon.plan.slug,
+            providerId: addon.provider.id,
+            realId: addon.realId,
+            region: addon.region,
+            type: addon.provider.name,
+          };
+        });
+        Logger.printJson(formattedAddons);
+        break;
+      }
+      case 'human':
+      default: {
+        const formattedAddons = addons.map((addon) => {
+          return [
+            addon.plan.name + ' ' + addon.provider.name,
+            addon.region,
+            styleText(['bold', 'green'], addon.name),
+            addon.id,
+          ];
+        });
+        Logger.println(formatTable(formattedAddons));
+      }
+    }
+  },
+});

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

@@ -0,0 +1,45 @@
+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 Addon from '../../models/addon.js';
+import { humanJsonOutputFormatOption } from '../global.options.js';
+
+export const addonProvidersCommand = defineCommand({
+  description: 'List available add-on providers',
+  since: '0.2.3',
+  options: {
+    format: humanJsonOutputFormatOption,
+  },
+  args: [],
+  async handler(options) {
+    const { format } = options;
+
+    const providers = await Addon.listProviders();
+
+    switch (format) {
+      case 'json': {
+        const formattedProviders = providers.map((provider) => ({
+          id: provider.id,
+          name: provider.name,
+          shortDesc: provider.shortDesc,
+          regions: provider.regions,
+          plans: provider.plans.map((plan) => ({
+            id: plan.id,
+            name: plan.name,
+            slug: plan.slug,
+          })),
+        }));
+        Logger.printJson(formattedProviders);
+        break;
+      }
+      case 'human':
+      default: {
+        const formattedProviders = providers.map((provider) => {
+          return [styleText('bold', provider.id), provider.name, provider.shortDesc || ''];
+        });
+        Logger.println(formatTable(formattedProviders));
+      }
+    }
+  },
+});

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

@@ -0,0 +1,99 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import * as Addon from '../../models/addon.js';
+import { humanJsonOutputFormatOption } from '../global.options.js';
+import { addonProviderArg } from './addon.args.js';
+
+export const addonProvidersShowCommand = defineCommand({
+  description: 'Show information about an add-on provider',
+  since: '0.2.3',
+  options: {
+    format: humanJsonOutputFormatOption,
+  },
+  args: [addonProviderArg],
+  async handler(options, providerName) {
+    const { format } = options;
+
+    const provider = await Addon.getProvider(providerName);
+    const providerInfos = await Addon.getProviderInfos(providerName);
+
+    const formattedPlans = [...provider.plans]
+      .sort((a, b) => a.price - b.price)
+      .map((plan) => {
+        const formattedFeatures = plan.features
+          .map((feature) => ({
+            name: feature.name,
+            value: feature.value,
+          }))
+          .sort((a, b) => a.name.localeCompare(b.name));
+
+        const formattedPlan = {
+          id: plan.id,
+          name: plan.name,
+          slug: plan.slug,
+          features: formattedFeatures,
+        };
+
+        if (providerInfos != null) {
+          const planType = plan.features.find(({ name }) => name.toLowerCase() === 'type');
+          if (planType != null && planType.value.toLowerCase() === 'dedicated') {
+            const planVersions = Object.keys(providerInfos.dedicated);
+            formattedPlan.versions = planVersions.map((version) => {
+              return {
+                version,
+                isDefault: version === providerInfos.defaultDedicatedVersion,
+                features: providerInfos.dedicated[version].features.map((feature) => ({
+                  name: feature.name,
+                  enabledByDefault: feature.enabled,
+                })),
+              };
+            });
+          }
+        }
+
+        return formattedPlan;
+      });
+
+    const formattedProvider = {
+      id: provider.id,
+      name: provider.name,
+      shortDesc: provider.shortDesc,
+      regions: provider.regions,
+      plans: formattedPlans,
+    };
+
+    switch (format) {
+      case 'json': {
+        Logger.printJson(formattedProvider);
+        break;
+      }
+      case 'human':
+      default: {
+        Logger.println(styleText('bold', formattedProvider.id));
+        Logger.println(`${formattedProvider.name}: ${formattedProvider.shortDesc}`);
+        Logger.println();
+        Logger.println(`Available regions: ${formattedProvider.regions.join(', ')}`);
+        Logger.println();
+        Logger.println('Available plans');
+
+        formattedProvider.plans.forEach((plan) => {
+          Logger.println(`Plan ${styleText('bold', plan.slug)}`);
+          plan.features.forEach(({ name, value }) => Logger.println(`  ${name}: ${value}`));
+
+          if (plan.versions != null) {
+            Logger.println(
+              `  Available versions: ${plan.versions.map(({ version, isDefault }) => (isDefault ? `${version} (default)` : version)).join(', ')}`,
+            );
+            plan.versions.forEach(({ version, features }) => {
+              Logger.println(`  Options for version ${version}:`);
+              features.forEach(({ name, enabledByDefault }) => {
+                Logger.println(`    ${name}: default=${enabledByDefault}`);
+              });
+            });
+          }
+        });
+      }
+    }
+  },
+});

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

@@ -0,0 +1,24 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import * as Addon from '../../models/addon.js';
+import * as Organisation from '../../models/organisation.js';
+import { addonIdOrNameArg } from '../global.args.js';
+import { orgaIdOrNameOption } from '../global.options.js';
+import { addonNameArg } from './addon.args.js';
+
+export const addonRenameCommand = defineCommand({
+  description: 'Rename an add-on',
+  since: '0.3.0',
+  options: {
+    org: orgaIdOrNameOption,
+  },
+  args: [addonIdOrNameArg, addonNameArg],
+  async handler(options, addon, newName) {
+    const { org: orgaIdOrName } = options;
+
+    const ownerId = await Organisation.getId(orgaIdOrName);
+    await Addon.rename(ownerId, addon, newName);
+
+    Logger.println(`Addon ${addon.addon_id || addon.addon_name} successfully renamed to ${newName}`);
+  },
+});