clever-tools 4.4.0 → 4.5.0

package/src/commands/diag/diag.command.js

@@ -0,0 +1,136 @@
+import { releaseInfo as getLinuxInfos } from 'linux-release-info';
+import os from 'node:os';
+import pkg from '../../../package.json' with { type: 'json' };
+import { defineCommand } from '../../lib/define-command.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import { conf, loadOAuthConf } from '../../models/configuration.js';
+import * as User from '../../models/user.js';
+import { humanJsonOutputFormatOption } from '../global.options.js';
+
+function getShell() {
+  const platform = os.platform();
+
+  if (platform === 'win32') {
+    if (process.env.PSModulePath) {
+      if (process.env.WT_SESSION) {
+        return 'PowerShell (Windows Terminal)';
+      }
+      if (process.env.PSVersionTable || process.env.POWERSHELL_DISTRIBUTION_CHANNEL) {
+        return 'PowerShell Core';
+      }
+      return 'Windows PowerShell';
+    }
+    if (process.env.WT_SESSION) {
+      return 'Windows Terminal (cmd)';
+    }
+    return process.env.ComSpec || 'cmd.exe';
+  }
+
+  return process.env.SHELL || 'unknown';
+}
+
+function getTerminal() {
+  if (process.env.WT_SESSION) {
+    return 'Windows Terminal';
+  }
+  return process.env.TERM_PROGRAM || process.env.TERMINAL_EMULATOR || process.env.TERM;
+}
+
+export const diagCommand = defineCommand({
+  description: 'Diagnose the current installation (prints various informations for support)',
+  since: '1.6.0',
+  options: {
+    format: humanJsonOutputFormatOption,
+  },
+  args: [],
+  async handler(options) {
+    const { format } = options;
+
+    /** @type {string} */
+    const userId = await User.getCurrentId().catch(() => null);
+    const authDetails = await loadOAuthConf();
+
+    function getAuthState() {
+      if (authDetails.token == null) {
+        return 'not connected';
+      }
+      if (userId == null) {
+        return 'authentication failed';
+      }
+      return 'authenticated';
+    }
+
+    const formattedDiag = {
+      version: pkg.version,
+      commitId: pkg.commitId,
+      nodeVersion: process.version,
+      platform: os.platform(),
+      release: os.release(),
+      arch: process.arch,
+      shell: getShell(),
+      terminal: getTerminal(),
+      isPackaged: process.pkg != null,
+      execPath: process.execPath,
+      configFile: conf.CONFIGURATION_FILE,
+      authSource: authDetails.source,
+      oAuthToken: authDetails.token,
+      authState: getAuthState(),
+      userId,
+    };
+
+    const linuxInfos = await getLinuxInfos()
+      .then(({ pretty_name, name, id }) => pretty_name || name || id)
+      .catch(() => null);
+    if (linuxInfos != null) {
+      formattedDiag.linuxInfos = linuxInfos;
+    }
+
+    switch (format) {
+      case 'json': {
+        Logger.printJson(formattedDiag);
+        break;
+      }
+      case 'human':
+      default: {
+        Logger.println('clever-tools  ' + styleText('green', formattedDiag.version));
+        // Only available in built binaries
+        if (formattedDiag.commitId) {
+          Logger.println('Commit        ' + styleText('green', formattedDiag.commitId));
+        }
+        Logger.println('Node.js       ' + styleText('green', formattedDiag.nodeVersion));
+        Logger.println('Platform      ' + styleText('green', formattedDiag.platform));
+        Logger.println('Release       ' + styleText('green', formattedDiag.release));
+        Logger.println('Architecture  ' + styleText('green', formattedDiag.arch));
+        if (formattedDiag.linuxInfos != null) {
+          Logger.println('Linux         ' + styleText('green', formattedDiag.linuxInfos));
+        }
+        Logger.println('Shell         ' + styleText('green', formattedDiag.shell));
+        Logger.println('Terminal      ' + styleText('green', formattedDiag.terminal));
+        Logger.println('Packaged      ' + styleText('green', formattedDiag.isPackaged));
+        Logger.println('Exec path     ' + styleText('green', formattedDiag.execPath));
+        Logger.println('Config file   ' + styleText('green', formattedDiag.configFile));
+
+        Logger.println('Auth source   ' + styleText('green', formattedDiag.authSource));
+
+        const token =
+          formattedDiag.oAuthToken == null ? styleText('red', '(none)') : styleText('green', formattedDiag.oAuthToken);
+        Logger.println('oAuth token   ' + token);
+
+        switch (formattedDiag.authState) {
+          case 'authenticated': {
+            Logger.println('User ID       ' + styleText('green', formattedDiag.userId));
+            break;
+          }
+          case 'authentication failed': {
+            Logger.println('User ID       ' + styleText('red', 'Authentication failed'));
+            break;
+          }
+          case 'not connected': {
+            Logger.println('User ID       ' + styleText('red', 'Not connected'));
+          }
+        }
+      }
+    }
+  },
+});

package/src/commands/diag/diag.docs.md

@@ -0,0 +1,15 @@
+# 📖 `clever diag` command reference
+
+## ➡️ `clever diag` <kbd>Since 1.6.0</kbd>
+
+Diagnose the current installation (prints various informations for support)
+
+```bash
+clever diag [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|

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

@@ -0,0 +1,25 @@
+import { addDomain } 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 { fqdnArg } from './domain.args.js';
+
+export const domainAddCommand = defineCommand({
+  description: 'Add a domain name to an application',
+  since: '0.2.0',
+  options: {
+    alias: aliasOption,
+    app: appIdOrNameOption,
+  },
+  args: [fqdnArg],
+  async handler(options, fqdn) {
+    const { alias, app: appIdOrName } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+    const encodedFqdn = encodeURIComponent(fqdn);
+
+    await addDomain({ id: ownerId, appId, domain: encodedFqdn }).then(sendToApi);
+    Logger.println('Your domain has been successfully saved');
+  },
+});

package/src/commands/domain/domain.args.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { defineArgument } from '../../lib/define-argument.js';
+
+export const fqdnArg = defineArgument({
+  schema: z.string(),
+  description: 'Domain name of the application',
+  placeholder: 'fqdn',
+});

package/src/commands/domain/domain.command.js

@@ -0,0 +1,38 @@
+import { get as getApp } 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 { getDomainObject, getFavouriteDomain } from '../../models/domain.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { aliasOption, appIdOrNameOption, humanJsonOutputFormatOption } from '../global.options.js';
+
+export const domainCommand = defineCommand({
+  description: 'Manage domain names for an application',
+  since: '0.2.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 app = await getApp({ id: ownerId, appId }).then(sendToApi);
+    const favouriteDomain = await getFavouriteDomain({ ownerId, appId });
+
+    const domains = app.vhosts.map((vhost) => getDomainObject(vhost.fqdn, favouriteDomain));
+
+    switch (format) {
+      case 'json':
+        Logger.printJson(domains);
+        break;
+      default:
+        domains.forEach((domain) => {
+          Logger.println(`${domain.isFavourite ? '* ' : '  '}${domain.domainWithPathPrefix}`);
+        });
+        break;
+    }
+  },
+});

package/src/commands/domain/domain.diag.command.js

@@ -0,0 +1,204 @@
+import { get as getApp } from '@clevercloud/client/esm/api/v2/application.js';
+import { getDefaultLoadBalancersDnsInfo } from '@clevercloud/client/esm/api/v4/load-balancers.js';
+import { diagDomainConfig } from '@clevercloud/client/esm/utils/diag-domain-config.js';
+import { sortDomains } from '@clevercloud/client/esm/utils/domains.js';
+import { parse as parseDomain } from 'tldts';
+import { z } from 'zod';
+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 Application from '../../models/application.js';
+import { DnsResolver } from '../../models/node-dns-resolver.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import { aliasOption, appIdOrNameOption, humanJsonOutputFormatOption } from '../global.options.js';
+
+function reportDomainDiagnostics({ hostname, pathPrefix, resolvedDnsConfig, diagDetails, diagSummary }) {
+  const validDiags = diagDetails.filter((diag) => diag.code === 'valid-a');
+  const unknownDiags = diagDetails.filter((diag) => diag.code === 'unknown-a');
+  const missingDiags = diagDetails.filter((diag) => diag.code === 'missing-a');
+  const suggestedCname = diagDetails.find((diag) => diag.code === 'suggested-cname');
+  const missingCname = diagDetails.find((diag) => diag.code === 'missing-cname');
+  const unknownCname = diagDetails.find((diag) => diag.code === 'unknown-cname');
+
+  const hasARecords = resolvedDnsConfig.aRecords.length > 0;
+  const hasCnameRecord = resolvedDnsConfig.cnameRecords.length > 0;
+
+  Logger.println('\n' + styleText('blue', hostname) + styleText('yellow', pathPrefix) + '\n');
+
+  switch (diagSummary) {
+    case 'managed':
+      Logger.printlnWithIndent(styleText('green', '✔ Managed by Clever Cloud'), 2);
+      Logger.printlnWithIndent('ⓘ cleverapps.io domains should only be used for testing purposes', 2);
+      break;
+    case 'no-config':
+      Logger.printlnWithIndent(styleText('red', '✘ No DNS configuration found'), 2);
+      break;
+    case 'valid':
+      Logger.printlnWithIndent(styleText('green', '✔ Your configuration is valid'), 2);
+      break;
+    case 'invalid':
+      Logger.printlnWithIndent(styleText('red', '✘ Something is wrong with your configuration'), 2);
+      break;
+    case 'incomplete':
+      Logger.printlnWithIndent(styleText('yellow', '⚠ Your configuration is incomplete'), 2);
+      break;
+  }
+
+  // Valid records
+  if (validDiags.length > 0) {
+    Logger.println('');
+    validDiags.forEach((diag) => {
+      const source = hasCnameRecord ? `(from CNAME ${resolvedDnsConfig.cnameRecords[0]}.)` : '';
+      Logger.printlnWithIndent(`${diag.record.value} ${styleText('green', '✔ A Record OK')} ${source}`, 2);
+    });
+  }
+
+  // Replace A with CNAME
+  if (diagSummary === 'valid' && suggestedCname != null) {
+    Logger.println('');
+    Logger.printlnWithIndent('ⓘ You can replace your A records with this CNAME:', 2);
+    Logger.printlnWithIndent(suggestedCname.record.value, 6);
+  }
+
+  // Replace A Records with CNAME
+  if (missingCname != null && unknownCname == null && (diagSummary === 'invalid' || diagSummary === 'incomplete')) {
+    const cnameToUse = suggestedCname != null ? suggestedCname.record.value : missingCname.record.value;
+
+    Logger.println('');
+    Logger.printlnWithIndent('⇄ Replace your A records with this CNAME:', 2);
+    Logger.printlnWithIndent(cnameToUse, 6);
+    Logger.println('');
+    Logger.printlnWithIndent('or:', 2);
+  }
+
+  // Replace unknown CNAME with missing CNAME
+  if (diagSummary === 'invalid' && missingCname != null && unknownCname != null) {
+    Logger.println('');
+    Logger.printlnWithIndent('➖Remove this CNAME record:', 2);
+    Logger.printlnWithIndent(unknownCname.record.value + '. ', 6);
+    Logger.println('');
+    Logger.printlnWithIndent('➕Add this CNAME record instead:', 2);
+    Logger.printlnWithIndent(missingCname.record.value, 6);
+
+    if (hasARecords) {
+      Logger.println('');
+      Logger.printlnWithIndent('or:', 2);
+    }
+  }
+
+  // Add CNAME
+  if (diagSummary === 'no-config' && missingCname != null) {
+    Logger.println('');
+    Logger.printlnWithIndent('➕Add this CNAME record:', 2);
+    Logger.printlnWithIndent(missingCname.record.value, 6);
+  }
+
+  // Remove Unknown records
+  if (unknownDiags.length > 0) {
+    Logger.println('');
+    Logger.printlnWithIndent('➖Remove these A records:', 2);
+
+    unknownDiags.forEach((diag) => {
+      const source = hasCnameRecord ? `(from CNAME ${resolvedDnsConfig.cnameRecords[0]}.)` : '';
+      Logger.printlnWithIndent(`${diag.record.value} ${source}`, 6);
+    });
+  }
+
+  // Add missing A records
+  if (missingDiags.length > 0) {
+    Logger.println('');
+    Logger.printlnWithIndent('➕Add these A records:', 2);
+
+    missingDiags.forEach((missingDiag) => Logger.printlnWithIndent(missingDiag.record.value, 6));
+  }
+}
+
+function getParsedDomains(vhosts) {
+  return vhosts.map(({ fqdn }) => {
+    const { hostname, pathname } = new URL('https://' + fqdn);
+    const { subdomain } = parseDomain(fqdn);
+
+    return { hostname, pathPrefix: pathname, isApex: subdomain === '' };
+  });
+}
+
+export const domainDiagCommand = defineCommand({
+  description: 'Check if domains associated to a specific app are properly configured',
+  since: '3.9.0',
+  options: {
+    filter: defineOption({
+      name: 'filter',
+      schema: z.string().default(''),
+      description: 'Check only domains containing the provided text',
+      placeholder: 'text',
+    }),
+    alias: aliasOption,
+    app: appIdOrNameOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [],
+  async handler(options) {
+    const dnsResolver = new DnsResolver();
+    const allDomainDiagnostics = [];
+    const { alias, app: appIdOrName, format, filter } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+    const hasDomainFilter = filter.length > 0;
+    let hasError = false;
+
+    const app = await getApp({ id: ownerId, appId }).then(sendToApi);
+    const expectedDnsForPublicLoadBalancer = await getDefaultLoadBalancersDnsInfo({ ownerId, appId }).then(sendToApi);
+
+    const loadBalancerDnsConfig = {
+      aRecords: expectedDnsForPublicLoadBalancer[0].dns.a,
+      cnameRecord: expectedDnsForPublicLoadBalancer[0].dns.cname,
+    };
+
+    const filteredDomains = app.vhosts.filter(({ fqdn }) => fqdn.includes(filter));
+    const domains = getParsedDomains(filteredDomains);
+    const sortedDomains = domains.sort(sortDomains);
+
+    for (const { hostname, pathPrefix, isApex } of sortedDomains) {
+      const resolvedDnsConfig = {
+        aRecords: await dnsResolver.resolveA(hostname),
+        cnameRecords: (await dnsResolver.resolveCname(hostname)) ?? [],
+      };
+
+      const diagnosticResults = diagDomainConfig(
+        {
+          hostname,
+          pathPrefix,
+          isApex,
+        },
+        resolvedDnsConfig,
+        loadBalancerDnsConfig,
+      );
+      allDomainDiagnostics.push({ ...diagnosticResults, resolvedDnsConfig });
+
+      if (diagnosticResults.diagSummary === 'invalid' || diagnosticResults.diagSummary === 'no-config') {
+        hasError = true;
+      }
+    }
+
+    switch (format) {
+      case 'json':
+        Logger.printJson(allDomainDiagnostics);
+        break;
+      default: {
+        allDomainDiagnostics.forEach((diag) => reportDomainDiagnostics(diag));
+
+        if (allDomainDiagnostics.length === 0 && !hasDomainFilter) {
+          Logger.println(`\nNo domain associated to the app "${app.name}" (${app.id})`);
+        }
+
+        if (allDomainDiagnostics.length === 0 && hasDomainFilter) {
+          Logger.println(`\nNo domain matches "${filter}" for the app "${app.name}" (${app.id})`);
+        }
+      }
+    }
+
+    if (hasError) {
+      throw new Error('At least one of the domains is misconfigured');
+    }
+  },
+});

package/src/commands/domain/domain.docs.md

@@ -0,0 +1,143 @@
+# 📖 `clever domain` command reference
+
+## ➡️ `clever domain` <kbd>Since 0.2.0</kbd>
+
+Manage domain names for an application
+
+```bash
+clever domain [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 domain add` <kbd>Since 0.2.0</kbd>
+
+Add a domain name to an application
+
+```bash
+clever domain add <fqdn> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`fqdn`|Domain name of the application|
+
+### ⚙️ 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)|
+
+## ➡️ `clever domain diag` <kbd>Since 3.9.0</kbd>
+
+Check if domains associated to a specific app are properly configured
+
+```bash
+clever domain diag [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)|
+|`--filter` `<text>`|Check only domains containing the provided text|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever domain favourite` <kbd>Since 2.7.0</kbd>
+
+Manage the favourite domain name for an application
+
+```bash
+clever domain favourite [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 domain favourite set` <kbd>Since 2.7.0</kbd>
+
+Set the favourite domain for an application
+
+```bash
+clever domain favourite set <fqdn> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`fqdn`|Domain name of the application|
+
+### ⚙️ 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)|
+
+## ➡️ `clever domain favourite unset` <kbd>Since 2.7.0</kbd>
+
+Unset the favourite domain for an application
+
+```bash
+clever domain favourite unset [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)|
+
+## ➡️ `clever domain overview` <kbd>Since 3.9.0</kbd>
+
+Get an overview of all your domains (all orgas, all apps)
+
+```bash
+clever domain overview [options]
+```
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`--filter` `<text>`|Get only domains containing the provided text|
+|`-F`, `--format` `<format>`|Output format (human, json) (default: human)|
+
+## ➡️ `clever domain rm` <kbd>Since 0.2.0</kbd>
+
+Remove a domain name from an application
+
+```bash
+clever domain rm <fqdn> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`fqdn`|Domain name of the application|
+
+### ⚙️ 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/domain/domain.favourite.command.js

@@ -0,0 +1,35 @@
+import { defineCommand } from '../../lib/define-command.js';
+import { Logger } from '../../logger.js';
+import * as Application from '../../models/application.js';
+import { getDomainObject, getFavouriteDomain } from '../../models/domain.js';
+import { aliasOption, appIdOrNameOption, humanJsonOutputFormatOption } from '../global.options.js';
+
+export const domainFavouriteCommand = defineCommand({
+  description: 'Manage the favourite domain name for an application',
+  since: '2.7.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 favouriteDomain = await getFavouriteDomain({ ownerId, appId });
+
+    switch (format) {
+      case 'json':
+        const domain = getDomainObject(favouriteDomain, favouriteDomain);
+        Logger.printJson(domain);
+        break;
+      default:
+        if (favouriteDomain == null) {
+          return Logger.println('No favourite domain set');
+        }
+        Logger.println(favouriteDomain);
+        break;
+    }
+  },
+});

package/src/commands/domain/domain.favourite.set.command.js

@@ -0,0 +1,24 @@
+import { markFavouriteDomain } 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 { fqdnArg } from './domain.args.js';
+
+export const domainFavouriteSetCommand = defineCommand({
+  description: 'Set the favourite domain for an application',
+  since: '2.7.0',
+  options: {
+    alias: aliasOption,
+    app: appIdOrNameOption,
+  },
+  args: [fqdnArg],
+  async handler(options, fqdn) {
+    const { alias, app: appIdOrName } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+
+    await markFavouriteDomain({ id: ownerId, appId }, { fqdn }).then(sendToApi);
+    Logger.println('Your favourite domain has been successfully set');
+  },
+});

package/src/commands/domain/domain.favourite.unset.command.js

@@ -0,0 +1,23 @@
+import { unmarkFavouriteDomain } 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 domainFavouriteUnsetCommand = defineCommand({
+  description: 'Unset the favourite domain for an application',
+  since: '2.7.0',
+  options: {
+    alias: aliasOption,
+    app: appIdOrNameOption,
+  },
+  args: [],
+  async handler(options) {
+    const { alias, app: appIdOrName } = options;
+    const { ownerId, appId } = await Application.resolveId(appIdOrName, alias);
+
+    await unmarkFavouriteDomain({ id: ownerId, appId }).then(sendToApi);
+    Logger.println('Favourite domain has been successfully unset');
+  },
+});