clever-tools 4.4.0 → 4.5.0

package/src/commands/keycloak/keycloak.docs.md

@@ -0,0 +1,197 @@
+# 📖 `clever keycloak` command reference
+
+> [!NOTE]
+> 🧪 **Experimental**: This command may change or be removed in future versions.
+> Enable with: `clever features enable operators`
+
+## ➡️ `clever keycloak` <kbd>Since 3.13.0</kbd>
+
+Manage Clever Cloud Keycloak services
+
+```bash
+clever keycloak [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever keycloak disable-ng` <kbd>Since 3.13.0</kbd>
+
+Unlink Keycloak from its Network Group
+
+```bash
+clever keycloak disable-ng <addon-id|addon-name>
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+## ➡️ `clever keycloak enable-ng` <kbd>Since 3.13.0</kbd>
+
+Link Keycloak to a Network Group, used for multi-instances secure communication
+
+```bash
+clever keycloak enable-ng <addon-id|addon-name>
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+## ➡️ `clever keycloak get` <kbd>Since 3.13.0</kbd>
+
+Get information about a deployed Keycloak
+
+```bash
+clever keycloak get <addon-id|addon-name> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever keycloak open` <kbd>Since 3.13.0</kbd>
+
+Open the Keycloak dashboard in Clever Cloud Console
+
+```bash
+clever keycloak open <addon-id|addon-name>
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+## ➡️ `clever keycloak open logs` <kbd>Since 3.13.0</kbd>
+
+Open the Keycloak application logs in Clever Cloud Console
+
+```bash
+clever keycloak open logs <addon-id|addon-name>
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+## ➡️ `clever keycloak open webui` <kbd>Since 3.13.0</kbd>
+
+Open the Keycloak admin console in your browser
+
+```bash
+clever keycloak open webui <addon-id|addon-name>
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+## ➡️ `clever keycloak rebuild` <kbd>Since 3.13.0</kbd>
+
+Rebuild Keycloak
+
+```bash
+clever keycloak rebuild <addon-id|addon-name>
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+## ➡️ `clever keycloak restart` <kbd>Since 3.13.0</kbd>
+
+Restart Keycloak
+
+```bash
+clever keycloak restart <addon-id|addon-name>
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+## ➡️ `clever keycloak version` <kbd>Since 3.13.0</kbd>
+
+Check Keycloak deployed version
+
+```bash
+clever keycloak version <addon-id|addon-name> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever keycloak version check` <kbd>Since 3.13.0</kbd>
+
+Check Keycloak deployed version
+
+```bash
+clever keycloak version check <addon-id|addon-name> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever keycloak version update` <kbd>Since 3.13.0</kbd>
+
+Update Keycloak deployed version
+
+```bash
+clever keycloak version update <addon-id|addon-name> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`addon-id|addon-name`|Add-on ID (or name, if unambiguous)|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`--target` `<version>`|Target version to upgrade to (e.g.: 24, 2.4, 2.4.1)|

package/src/commands/keycloak/keycloak.enable-ng.command.js

@@ -0,0 +1,13 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorNgEnable } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+
+export const keycloakEnableNgCommand = defineCommand({
+  description: 'Link Keycloak to a Network Group, used for multi-instances secure communication',
+  since: '3.13.0',
+  options: {},
+  args: [addonIdOrNameArg],
+  async handler(_options, addonIdOrName) {
+    await operatorNgEnable('keycloak', addonIdOrName);
+  },
+});

package/src/commands/keycloak/keycloak.get.command.js

@@ -0,0 +1,17 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorPrint } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+import { humanJsonOutputFormatOption } from '../global.options.js';
+
+export const keycloakGetCommand = defineCommand({
+  description: 'Get information about a deployed Keycloak',
+  since: '3.13.0',
+  options: {
+    format: humanJsonOutputFormatOption,
+  },
+  args: [addonIdOrNameArg],
+  async handler(options, addonIdOrName) {
+    const { format } = options;
+    await operatorPrint('keycloak', addonIdOrName, format);
+  },
+});

package/src/commands/keycloak/keycloak.open.command.js

@@ -0,0 +1,13 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorOpen } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+
+export const keycloakOpenCommand = defineCommand({
+  description: 'Open the Keycloak dashboard in Clever Cloud Console',
+  since: '3.13.0',
+  options: {},
+  args: [addonIdOrNameArg],
+  async handler(_options, addonIdOrName) {
+    await operatorOpen('keycloak', addonIdOrName);
+  },
+});

package/src/commands/keycloak/keycloak.open.logs.command.js

@@ -0,0 +1,13 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorOpenLogs } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+
+export const keycloakOpenLogsCommand = defineCommand({
+  description: 'Open the Keycloak application logs in Clever Cloud Console',
+  since: '3.13.0',
+  options: {},
+  args: [addonIdOrNameArg],
+  async handler(_options, addonIdOrName) {
+    await operatorOpenLogs('keycloak', addonIdOrName);
+  },
+});

package/src/commands/keycloak/keycloak.open.webui.command.js

@@ -0,0 +1,13 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorOpenWebUi } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+
+export const keycloakOpenWebuiCommand = defineCommand({
+  description: 'Open the Keycloak admin console in your browser',
+  since: '3.13.0',
+  options: {},
+  args: [addonIdOrNameArg],
+  async handler(_options, addonIdOrName) {
+    await operatorOpenWebUi('keycloak', addonIdOrName);
+  },
+});

package/src/commands/keycloak/keycloak.rebuild.command.js

@@ -0,0 +1,13 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorRebuild } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+
+export const keycloakRebuildCommand = defineCommand({
+  description: 'Rebuild Keycloak',
+  since: '3.13.0',
+  options: {},
+  args: [addonIdOrNameArg],
+  async handler(_options, addonIdOrName) {
+    await operatorRebuild('keycloak', addonIdOrName);
+  },
+});

package/src/commands/keycloak/keycloak.restart.command.js

@@ -0,0 +1,13 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorReboot } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+
+export const keycloakRestartCommand = defineCommand({
+  description: 'Restart Keycloak',
+  since: '3.13.0',
+  options: {},
+  args: [addonIdOrNameArg],
+  async handler(_options, addonIdOrName) {
+    await operatorReboot('keycloak', addonIdOrName);
+  },
+});

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

@@ -0,0 +1,17 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorCheckVersion } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+import { humanJsonOutputFormatOption } from '../global.options.js';
+
+export const keycloakVersionCheckCommand = defineCommand({
+  description: 'Check Keycloak deployed version',
+  since: '3.13.0',
+  options: {
+    format: humanJsonOutputFormatOption,
+  },
+  args: [addonIdOrNameArg],
+  async handler(options, addonIdOrName) {
+    const { format } = options;
+    await operatorCheckVersion('keycloak', addonIdOrName, format);
+  },
+});

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

@@ -0,0 +1,17 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorCheckVersion } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+import { humanJsonOutputFormatOption } from '../global.options.js';
+
+export const keycloakVersionCommand = defineCommand({
+  description: 'Check Keycloak deployed version',
+  since: '3.13.0',
+  options: {
+    format: humanJsonOutputFormatOption,
+  },
+  args: [addonIdOrNameArg],
+  async handler(options, addonIdOrName) {
+    const { format } = options;
+    await operatorCheckVersion('keycloak', addonIdOrName, format);
+  },
+});

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

@@ -0,0 +1,17 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { operatorUpdateVersion } from '../../lib/operator-commands.js';
+import { addonIdOrNameArg } from '../global.args.js';
+import { targetVersionOption } from '../global.options.js';
+
+export const keycloakVersionUpdateCommand = defineCommand({
+  description: 'Update Keycloak deployed version',
+  since: '3.13.0',
+  options: {
+    target: targetVersionOption,
+  },
+  args: [addonIdOrNameArg],
+  async handler(options, addonIdOrName) {
+    const { target } = options;
+    await operatorUpdateVersion('keycloak', target, addonIdOrName);
+  },
+});

package/src/commands/kv/kv.command.js

@@ -0,0 +1,99 @@
+import { getAllEnvVars } from '@clevercloud/client/esm/api/v2/addon.js';
+import Redis from 'ioredis';
+import { z } from 'zod';
+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 { findAddonsByNameOrId } from '../../models/ids-resolver.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { humanJsonOutputFormatOption, orgaIdOrNameOption } from '../global.options.js';
+
+const URL_ENV_KEY = 'REDIS_URL';
+
+const MAX_RETRIES_PER_REQUEST = 1;
+
+async function getAddonUrl(ownerId, addonId) {
+  const envVars = await getAllEnvVars({ id: ownerId, addonId }).then(sendToApi);
+  const redisUrl = envVars.find((env) => env.name === URL_ENV_KEY)?.value;
+
+  if (!redisUrl) {
+    throw new Error(
+      `Environment variable ${styleText('red', URL_ENV_KEY)} not found, is it a Materia KV or Redis® add-on?`,
+    );
+  }
+
+  return redisUrl;
+}
+
+async function sendCommand(url, command) {
+  Logger.debug(`Sending command '${command.join(' ')}' to ${url}`);
+  const client = new Redis(url, { maxRetriesPerRequest: MAX_RETRIES_PER_REQUEST });
+  try {
+    const result = await client.call(...command);
+    Logger.debug(`Command result: ${result}`);
+    return result;
+  } finally {
+    await client.disconnect();
+    Logger.debug('Disconnected from server');
+  }
+}
+
+export const kvCommand = defineCommand({
+  description: 'Send a raw command to a Materia KV or Redis® add-on',
+  since: '3.11.0',
+  isExperimental: true,
+  featureFlag: 'kv',
+  options: {
+    org: orgaIdOrNameOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [
+    defineArgument({
+      schema: z.string(),
+      description: 'Add-on/Real ID (or name, if unambiguous) of a Materia KV or Redis® add-on',
+      placeholder: 'kv-id|addon-id|addon-name',
+    }),
+    defineArgument({
+      schema: z.string(),
+      description: 'The raw command to send to the Materia KV or Redis® add-on',
+      placeholder: 'command',
+    }),
+  ],
+  async handler(options, addonIdOrRealIdOrName, ...restArgs) {
+    const { org, format } = options;
+
+    const addons = await findAddonsByNameOrId(addonIdOrRealIdOrName, org);
+
+    if (addons.length === 0) {
+      throw new Error(`Add-on ${addonIdOrRealIdOrName} not found`);
+    }
+
+    if (addons.length > 1) {
+      const formattedAddons = addons
+        .map(({ addonId, ownerId }) => `\n${styleText('grey', `- ${addonId} (${ownerId})`)}`)
+        .join('');
+      throw new Error(`Several add-ons found for '${addonIdOrRealIdOrName}', use ID instead:${formattedAddons}`);
+    }
+
+    const { addonId, ownerId } = addons[0];
+
+    const url = await getAddonUrl(ownerId, addonId);
+
+    Logger.debug(`Extracted command: ${restArgs.join(' ')}`);
+    const command = restArgs;
+
+    const result = await sendCommand(url, command);
+
+    switch (format) {
+      case 'json': {
+        Logger.printJson(result);
+        break;
+      }
+      case 'human':
+      default: {
+        Logger.println(result);
+      }
+    }
+  },
+});

package/src/commands/kv/kv.docs.md

@@ -0,0 +1,27 @@
+# 📖 `clever kv` command reference
+
+> [!NOTE]
+> 🧪 **Experimental**: This command may change or be removed in future versions.
+> Enable with: `clever features enable kv`
+
+## ➡️ `clever kv` <kbd>Since 3.11.0</kbd>
+
+Send a raw command to a Materia KV or Redis® add-on
+
+```bash
+clever kv <kv-id|addon-id|addon-name> <command> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`kv-id|addon-id|addon-name`|Add-on/Real ID (or name, if unambiguous) of a Materia KV or Redis® add-on|
+|`command`|The raw command to send to the Materia KV or Redis® add-on|
+
+### ⚙️ 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)|

package/src/commands/link/link.command.js

@@ -0,0 +1,31 @@
+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 { appIdOrNameArg } from '../global.args.js';
+import { aliasCreationOption, orgaIdOrNameOption } from '../global.options.js';
+
+export const linkCommand = defineCommand({
+  description: 'Link this repo to an existing application',
+  since: '0.2.0',
+  options: {
+    alias: aliasCreationOption,
+    org: orgaIdOrNameOption,
+  },
+  args: [appIdOrNameArg],
+  async handler(options, app) {
+    const { org: orgaIdOrName, alias } = options;
+
+    let appConfigEntry;
+    if (app.app_id != null && orgaIdOrName != null) {
+      Logger.warn("You've specified a unique application ID, organisation option will be ignored");
+      appConfigEntry = await Application.linkRepo(app, null, alias);
+    } else {
+      appConfigEntry = await Application.linkRepo(app, orgaIdOrName, alias);
+    }
+
+    Logger.printSuccess(
+      `Application ${styleText('green', appConfigEntry.app_id)} has been successfully linked to local alias ${styleText('green', appConfigEntry.alias)}!`,
+    );
+  },
+});

package/src/commands/link/link.docs.md

@@ -0,0 +1,22 @@
+# 📖 `clever link` command reference
+
+## ➡️ `clever link` <kbd>Since 0.2.0</kbd>
+
+Link this repo to an existing application
+
+```bash
+clever link <app-id|app-name> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`app-id|app-name`|Application ID (or name, if unambiguous)|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-a`, `--alias` `<alias>`|Short name for the application|
+|`-o`, `--org`, `--owner` `<org-id\|org-name>`|Organisation to target by its ID (or name, if unambiguous)|

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

@@ -1,18 +1,21 @@
 import crypto from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
 import open from 'open';
-import pkg from '../../package.json' with { type: 'json' };
-import { styleText } from '../lib/style-text.js';
-import { Logger } from '../logger.js';
-import { conf, writeOAuthConf } from '../models/configuration.js';
-import * as User from '../models/user.js';
+import { z } from 'zod';
+import pkg from '../../../package.json' with { type: 'json' };
+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 { conf, writeOAuthConf } from '../../models/configuration.js';
+import * as User from '../../models/user.js';
 
-// 20 random bytes as Base64URL
 function randomToken() {
   return crypto.randomBytes(20).toString('base64').replace(/\//g, '-').replace(/\+/g, '_').replace(/=/g, '');
 }
 
 const POLLING_INTERVAL = 2000;
+
 const POLLING_MAX_TRY_COUNT = 60;
 
 function pollOauthData(url, tryCount = 0) {
@@ -55,22 +58,41 @@ async function loginViaConsole() {
   return pollOauthData(cliPollUrl.toString());
 }
 
-export async function login(params) {
-  const { token, secret } = params.options;
-  const isLoginWithArgs = token != null && secret != null;
-  const isInteractiveLogin = token == null && secret == null;
+export const loginCommand = defineCommand({
+  description: 'Login to Clever Cloud',
+  since: '0.2.0',
+  options: {
+    token: defineOption({
+      name: 'token',
+      schema: z.string().optional(),
+      description: 'Directly give an existing token',
+      placeholder: 'token',
+    }),
+    secret: defineOption({
+      name: 'secret',
+      schema: z.string().optional(),
+      description: 'Directly give an existing secret',
+      placeholder: 'secret',
+    }),
+  },
+  args: [],
+  async handler(options) {
+    const { token, secret } = options;
+    const isLoginWithArgs = token != null && secret != null;
+    const isInteractiveLogin = token == null && secret == null;
 
-  if (isLoginWithArgs) {
-    return writeOAuthConf({ token, secret });
-  }
+    if (isLoginWithArgs) {
+      return writeOAuthConf({ token, secret });
+    }
 
-  if (isInteractiveLogin) {
-    const oauthData = await loginViaConsole();
-    await writeOAuthConf(oauthData);
-    const { name, email } = await User.getCurrent();
-    const formattedName = name || styleText(['red', 'bold'], '[unspecified name]');
-    return Logger.println(`Login successful as ${formattedName} <${email}>`);
-  }
+    if (isInteractiveLogin) {
+      const oauthData = await loginViaConsole();
+      await writeOAuthConf(oauthData);
+      const { name, email } = await User.getCurrent();
+      const formattedName = name || styleText(['red', 'bold'], '[unspecified name]');
+      return Logger.println(`Login successful as ${formattedName} <${email}>`);
+    }
 
-  throw new Error('Both `--token` and `--secret` have to be defined');
-}
+    throw new Error('Both `--token` and `--secret` have to be defined');
+  },
+});

package/src/commands/login/login.docs.md

@@ -0,0 +1,16 @@
+# 📖 `clever login` command reference
+
+## ➡️ `clever login` <kbd>Since 0.2.0</kbd>
+
+Login to Clever Cloud
+
+```bash
+clever login [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`--secret` `<secret>`|Directly give an existing secret|
+|`--token` `<token>`|Directly give an existing token|

package/src/commands/logout/logout.command.js

@@ -0,0 +1,15 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import { conf, writeOAuthConf } from '../../models/configuration.js';
+
+export const logoutCommand = defineCommand({
+  description: 'Logout from Clever Cloud',
+  since: '1.0.0',
+  options: {},
+  args: [],
+  async handler() {
+    // write empty object
+    await writeOAuthConf({});
+    Logger.println(`${conf.CONFIGURATION_FILE} has been updated.`);
+  },
+});

package/src/commands/logout/logout.docs.md

@@ -0,0 +1,9 @@
+# 📖 `clever logout` command reference
+
+## ➡️ `clever logout` <kbd>Since 1.0.0</kbd>
+
+Logout from Clever Cloud
+
+```bash
+clever logout
+```