clever-tools 4.10.0 → 4.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clever-tools",
-  "version": "4.10.0",
+  "version": "4.11.0",
   "description": "Command Line Interface for Clever Cloud.",
   "keywords": [
     "cli",

package/src/clever-client/drains.js

@@ -108,3 +108,20 @@ export function enableDrain(params) {
     // no body
   });
 }
+
+/**
+ * POST /v4/drains/organisations/{ownerId}/resources/{resourceId}/drains/{drainId}/check
+ * @param {Object} params
+ * @param {String} params.ownerId
+ * @param {String} params.resourceId
+ * @param {String} params.drainId
+ */
+export function checkDrain(params) {
+  // no multipath for /self or /organisations/{id}
+  return Promise.resolve({
+    method: 'post',
+    url: `/v4/drains/organisations/${params.ownerId}/resources/${params.resourceId}/drains/${params.drainId}/check`,
+    headers: { Accept: 'application/json' },
+    // no body
+  });
+}

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

@@ -1,5 +1,6 @@
 import { ApplicationAccessLogStream } from '@clevercloud/client/esm/streams/access-logs.js';
 import { formatTable } from '../../format-table.js';
+import { formatClf } from '../../lib/access-logs-clf.js';
 import { defineCommand } from '../../lib/define-command.js';
 import { styleText } from '../../lib/style-text.js';
 import { Logger } from '../../logger.js';
@@ -8,12 +9,12 @@ import { JsonArray } from '../../models/json-array.js';
 import { getHostAndTokens } from '../../models/send-to-api.js';
 import { truncateWithEllipsis } from '../../models/utils.js';
 import {
+  accessLogsFormatOption,
   addonIdOrRealIdOption,
   afterOption,
   aliasOption,
   appIdOrNameOption,
   beforeOption,
-  logsFormatOption,
 } from '../global.options.js';
 
 const THROTTLE_ELEMENTS = 2000;
@@ -76,7 +77,7 @@ export const accesslogsCommand = defineCommand({
   options: {
     alias: aliasOption,
     app: appIdOrNameOption,
-    format: logsFormatOption,
+    format: accessLogsFormatOption,
     before: beforeOption,
     after: afterOption,
     addon: addonIdOrRealIdOption,
@@ -132,6 +133,14 @@ export const accesslogsCommand = defineCommand({
           case 'json-stream':
             Logger.printJson(log);
             break;
+          case 'clf':
+            // when the connection is cut too early, or for TCP redirections, we don't have HTTP section
+            if (log.http == null) {
+              break;
+            }
+
+            Logger.println(formatClf(log));
+            break;
           case 'human':
           default:
             // when the connection is cut too early, or for TCP redirections, we don't have HTTP section

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

@@ -17,4 +17,4 @@ clever accesslogs [options]
 |`-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)|
+|`-F`, `--format` `<format>`|Output format (human, json, json-stream, clf) (default: human)|

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

@@ -9,6 +9,7 @@ import { Logger } from '../../logger.js';
 import * as AppConfig from '../../models/app_configuration.js';
 import * as Application from '../../models/application.js';
 import { AVAILABLE_ZONES, listAvailableTypes, listAvailableZones } from '../../models/application.js';
+import { LinkedWorktreeNotSupportedError } from '../../models/git-isomorphic.js';
 import { Git } from '../../models/git.js';
 import { aliasCreationOption, humanJsonOutputFormatOption, orgaIdOrNameOption } from '../global.options.js';
 
@@ -54,7 +55,13 @@ async function displayAppCreation(app, alias, github, taskCommand) {
       Logger.println(`    ${shellCommand('git commit -m "Initial commit"')}`);
       Logger.println();
     } else {
-      const isClean = await git.isGitWorkingDirectoryClean();
+      // Best-effort hint: if we can't tell because of a linked worktree on the JS backend, don't nag
+      const isClean = await git.isGitWorkingDirectoryClean().catch((error) => {
+        if (error instanceof LinkedWorktreeNotSupportedError) {
+          return true;
+        }
+        throw error;
+      });
       if (!isClean) {
         Logger.println(`  ${styleText('yellow', '!')} Commit your changes first:`);
         Logger.println(`    ${shellCommand('git add .')}`);

package/src/commands/deploy/deploy.docs.md

@@ -28,6 +28,7 @@ Clever Tools uses a current JS implementation for git operations. This works wit
 * **HTTP-only**: cannot use SSH-based git protocols
 * **Slow performance** on repositories with rewritten history (rebases, squashes)
 * **Connection timeouts** on large repositories or when pushing big files, due to HTTP-based transfers
+* **No git worktree support**: deploying from a linked git worktree (`git worktree add`) fails with `Could not find HEAD`. The system git backend deploys from worktrees just like from the main working tree
 
 If you experience any of these issues, you can enable the **system git backend** which uses the `git` command installed on your system (it must be in your `PATH` environment variable).
 

package/src/commands/drain/drain.check.command.js

@@ -0,0 +1,43 @@
+import { checkDrain } from '../../clever-client/drains.js';
+import { defineCommand } from '../../lib/define-command.js';
+import { styleText } from '../../lib/style-text.js';
+import { Logger } from '../../logger.js';
+import { resolveDrainResource } from '../../models/drain.js';
+import { sendToApi } from '../../models/send-to-api.js';
+import {
+  addonIdOrRealIdOption,
+  aliasOption,
+  appIdOrNameOption,
+  humanJsonOutputFormatOption,
+} from '../global.options.js';
+import { drainIdArg } from './drain.args.js';
+
+export const drainCheckCommand = defineCommand({
+  description: "Check that a drain's recipient is reachable and accepts deliveries",
+  since: '4.11.0',
+  options: {
+    alias: aliasOption,
+    appIdOrName: appIdOrNameOption,
+    addonIdOrRealId: addonIdOrRealIdOption,
+    format: humanJsonOutputFormatOption,
+  },
+  args: [drainIdArg],
+  async handler(options, drainId) {
+    const { alias, appIdOrName, addonIdOrRealId, format } = options;
+    const { ownerId, resourceId } = await resolveDrainResource(alias, appIdOrName, addonIdOrRealId);
+
+    const probe = await checkDrain({ ownerId, resourceId, drainId }).then(sendToApi);
+    switch (format) {
+      case 'json': {
+        Logger.printJson({ ok: probe.ok, message: probe.message });
+        break;
+      }
+      case 'human':
+      default: {
+        const status = probe.ok ? styleText(['bold', 'green'], 'OK') : styleText(['bold', 'red'], 'FAILED');
+        Logger.println(`Probe: ${status}`);
+        Logger.println(probe.message);
+      }
+    }
+  },
+});

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

@@ -34,6 +34,13 @@ export const drainCreateCommand = defineCommand({
       aliases: ['k'],
       placeholder: 'api-key',
     }),
+    sourceToken: defineOption({
+      name: 'source-token',
+      schema: z.string().optional(),
+      description: 'Source token (for betterstack)',
+      aliases: ['t'],
+      placeholder: 'source-token',
+    }),
     indexPrefix: defineOption({
       name: 'index-prefix',
       schema: z.string().optional(),
@@ -66,7 +73,7 @@ export const drainCreateCommand = defineCommand({
   ],
   async handler(options, drainTypeCliCode, url) {
     const { alias, appIdOrName, addonIdOrRealId } = options;
-    const { username, password, apiKey, indexPrefix, rfc5424StructuredDataParameters } = options;
+    const { username, password, apiKey, sourceToken, indexPrefix, rfc5424StructuredDataParameters } = options;
 
     const drainType = Object.values(DRAIN_TYPES).find((drainType) => drainType.cliCode === drainTypeCliCode);
 
@@ -108,6 +115,13 @@ export const drainCreateCommand = defineCommand({
       body.recipient.apiKey = apiKey;
     }
 
+    if (drainTypeCliCode === DRAIN_TYPES.BETTERSTACK.cliCode) {
+      if (!sourceToken) {
+        throw new Error(`${DRAIN_TYPES.BETTERSTACK.cliCode} drains require a source token (--source-token) to be set`);
+      }
+      body.recipient.sourceToken = sourceToken;
+    }
+
     if (
       drainTypeCliCode === DRAIN_TYPES.OVH_TCP.cliCode ||
       drainTypeCliCode === DRAIN_TYPES.SYSLOG_TCP.cliCode ||

package/src/commands/drain/drain.docs.md

@@ -17,6 +17,29 @@ clever drain [options]
 |`--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 drain check` <kbd>Since 4.11.0</kbd>
+
+Check that a drain's recipient is reachable and accepts deliveries
+
+```bash
+clever drain check <drain-id> [options]
+```
+
+### 📥 Arguments
+
+|Name|Description|
+|---|---|
+|`drain-id`|Drain ID|
+
+### ⚙️ Options
+
+|Name|Description|
+|---|---|
+|`--addon` `<addon-id>`|Add-on ID or real ID|
+|`-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 drain create` <kbd>Since 0.9.0</kbd>
 
 Create a drain
@@ -29,7 +52,7 @@ clever drain create <drain-type> <drain-url> [options]
 
 |Name|Description|
 |---|---|
-|`drain-type`|Drain type (datadog, elasticsearch, newrelic, ovh-tcp, raw-http, syslog-tcp, syslog-udp)|
+|`drain-type`|Drain type (betterstack, datadog, elasticsearch, newrelic, ovh-tcp, raw-http, syslog-tcp, syslog-udp)|
 |`drain-url`|Drain URL|
 
 ### ⚙️ Options
@@ -43,6 +66,7 @@ clever drain create <drain-type> <drain-url> [options]
 |`-i`, `--index-prefix` `<index-prefix>`|Optional index prefix (for elasticsearch), `logstash` value is used if not set|
 |`-p`, `--password` `<password>`|Basic auth password (for elasticsearch or raw-http)|
 |`-s`, `--sd-params` `<sd-params>`|RFC5424 structured data parameters (for ovh-tcp), e.g.: `X-OVH-TOKEN=\"REDACTED\"`|
+|`-t`, `--source-token` `<source-token>`|Source token (for betterstack)|
 |`-u`, `--username` `<username>`|Basic auth username (for elasticsearch or raw-http)|
 
 ## ➡️ `clever drain disable` <kbd>Since 0.9.0</kbd>

package/src/commands/global.commands.js

@@ -39,6 +39,7 @@ import { domainFavouriteSetCommand } from './domain/domain.favourite.set.command
 import { domainFavouriteUnsetCommand } from './domain/domain.favourite.unset.command.js';
 import { domainOverviewCommand } from './domain/domain.overview.command.js';
 import { domainRmCommand } from './domain/domain.rm.command.js';
+import { drainCheckCommand } from './drain/drain.check.command.js';
 import { drainCommand } from './drain/drain.command.js';
 import { drainCreateCommand } from './drain/drain.create.command.js';
 import { drainDisableCommand } from './drain/drain.disable.command.js';
@@ -268,6 +269,7 @@ export const globalCommands = {
   drain: [
     drainCommand,
     {
+      check: drainCheckCommand,
       create: drainCreateCommand,
       disable: drainDisableCommand,
       enable: drainEnableCommand,

package/src/commands/global.options.js

@@ -28,6 +28,14 @@ export const logsFormatOption = defineOption({
   placeholder: 'format',
 });
 
+export const accessLogsFormatOption = defineOption({
+  name: 'format',
+  schema: z.enum(['human', 'json', 'json-stream', 'clf']).default('human'),
+  description: 'Output format',
+  aliases: ['F'],
+  placeholder: 'format',
+});
+
 export const beforeOption = defineOption({
   name: 'before',
   schema: z.string().transform(date).optional(),

package/src/commands/profile/profile.switch.command.js

@@ -75,6 +75,10 @@ async function resolveTargetProfile(profiles, requestedAlias) {
     name: formatProfile(profile),
     value: profile.alias,
   }));
-  const selectedAlias = await selectAnswer('Select a profile:', choices);
+  const selectedAlias = await selectAnswer(
+    'Select a profile:',
+    choices,
+    'Use --alias <name> to select a profile directly.',
+  );
   return profiles.find((profile) => profile.alias === selectedAlias);
 }

package/src/commands/ssh/ssh.command.js

@@ -45,7 +45,7 @@ export const sshCommand = defineCommand({
     let sshTarget;
     if (instances.length === 1) {
       sshTarget = instances[0].id;
-    } else if (process.stdout.isTTY) {
+    } else if (process.stdin.isTTY) {
       const choices = instances
         .sort((a, b) => a.instanceNumber - b.instanceNumber)
         .map((inst) => ({

package/src/lib/access-logs-clf.js

@@ -0,0 +1,52 @@
+const CLF_MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/**
+ * Format a `Date` as a Common Log Format timestamp in UTC, e.g. `10/Oct/2000:13:55:36 +0000`.
+ * @param {Date} date
+ * @returns {string}
+ */
+function formatClfDate(date) {
+  const pad = (n) => String(n).padStart(2, '0');
+  const day = pad(date.getUTCDate());
+  const month = CLF_MONTHS[date.getUTCMonth()];
+  const year = date.getUTCFullYear();
+  const hours = pad(date.getUTCHours());
+  const minutes = pad(date.getUTCMinutes());
+  const seconds = pad(date.getUTCSeconds());
+  return `${day}/${month}/${year}:${hours}:${minutes}:${seconds} +0000`;
+}
+
+/**
+ * Escape a value so it can be safely embedded inside a double-quoted CLF field.
+ * Backslashes are escaped first, then double-quotes, otherwise a `"` would be escaped
+ * twice. Without this, a `"` in the value would close the quoted field early and shift
+ * every subsequent column.
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeClfQuoted(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Format an HTTP access log as a Common Log Format line.
+ *
+ * The HTTP protocol version is absent from the v4 access log payload, so the request line is
+ * limited to `method path` (no `HTTP/x.y` token). The protocol token is optional in CLF parsers
+ * (grok, GoAccess), and emitting a `-` placeholder would actually break their structured parsing.
+ *
+ * @see https://en.wikipedia.org/wiki/Common_Log_Format
+ * @param {object} log an HTTP access log (the `http` section must be present)
+ * @returns {string}
+ */
+export function formatClf(log) {
+  const host = log.source.ip;
+  const ident = '-';
+  const authuser = '-';
+  const date = formatClfDate(log.date);
+  const request = `${log.http.request.method} ${escapeClfQuoted(log.http.request.path)}`;
+  const status = log.http.response.statusCode;
+  const bytes = log.bytesOut;
+
+  return `${host} ${ident} ${authuser} [${date}] "${request}" ${status} ${bytes}`;
+}

package/src/lib/cliparse-patched.js

@@ -1,4 +1,5 @@
 import cliparseOriginal from 'cliparse';
+import cliparseArgumentModule from 'cliparse/src/argument.js';
 import cliparseCommandModule from 'cliparse/src/command.js';
 import semver from 'semver';
 import pkg from '../../package.json' with { type: 'json' };
@@ -33,6 +34,23 @@ cliparseOriginal.command = function (name, options, commandFunction) {
   return command;
 };
 
+// Patch cliparse.argument.parseList to drop the parse results that succeeded
+// from its error payload. When several positional args are given and only one
+// fails its parser, parseList returns the *whole* result list (successes
+// included) as the error. Downstream, displayErrors prints the valid siblings
+// as `<arg-name>: undefined` (they carry an `.argument` but no `.error`).
+// We keep only the entries that actually failed, fixing the issue at its root.
+// The success path is untouched (we only rewrite the error array), and
+// missing-value errors carry an `.error` ("missing value") so they are kept.
+const originalParseList = cliparseArgumentModule.parseList;
+cliparseArgumentModule.parseList = function (args, providedArguments) {
+  const result = originalParseList(args, providedArguments);
+  if (Array.isArray(result.error)) {
+    return cliparseOriginal.parsers.error(result.error.filter((entry) => entry.error != null));
+  }
+  return result;
+};
+
 /**
  * Map options from cliparse format (using option.name) to the original definition keys.
  * For example, { theOptionName: defineOption({ name: 'the-option-name', ... }) },

package/src/lib/define-command.types.d.ts

@@ -41,8 +41,13 @@ export interface CommandDefinition<
    */
   featureFlag?: string;
 
-  /** Version when this command was introduced (semver format, e.g., '2.1.0'). */
-  since?: `${number}.${number}.${number}`;
+  /**
+   * Version when this command was introduced (semver format, e.g., '2.1.0').
+   * Use `null` for a command not yet released: the release workflow resolves it
+   * to the upcoming version (see `scripts/resolve-since.js`). Required on purpose,
+   * so a missing value is a type error rather than a silent omission.
+   */
+  since: `${number}.${number}.${number}` | null;
 
   /** Options (named options like --type, --region, --format). */
   options?: O;

package/src/lib/k8s.js

@@ -503,6 +503,7 @@ export async function k8sUpdateVersion(orgIdOrName, clusterIdOrName, askedVersio
     (await selectAnswer(
       `Which version do you want to update ${styleText('blue', name)} to, current is ${styleText('blue', versions.installed)}?`,
       [...versions.available].reverse(),
+      'Use --target <version> to update directly.',
     ));
 
   if (!versions.available.includes(targetVersion)) {

package/src/lib/operator-commands.js

@@ -77,6 +77,7 @@ export async function operatorUpdateVersion(provider, askedVersion, addonIdOrNam
     (await selectAnswer(
       `Which version do you want to update ${styleText('blue', name)} to, current is ${styleText('blue', versions.installed)}?`,
       versions.available.reverse(),
+      'Use --target <version> to update directly.',
     ));
 
   if (!versions.available.includes(targetVersion)) {

package/src/lib/profile.js

@@ -59,7 +59,14 @@ export async function getProfileDetails({ profile, isActive }) {
   const [user, token] = await Promise.all([
     getUser({}).then(sendWithCredentials),
     getCurrentTokenInfo().then(sendWithCredentials),
-  ]).catch(() => [null, null]);
+  ]).catch((error) => {
+    // An expired/invalid token surfaces as a 401: degrade gracefully so the command can report it.
+    // Any other failure (TLS, network…) must bubble up instead of being masked as "token invalid".
+    if (error?.cause?.response?.status === 401) {
+      return [null, null];
+    }
+    throw error;
+  });
 
   return {
     id: user?.id ?? profile.userId,

package/src/lib/prompts.js

@@ -25,11 +25,23 @@ export async function confirmAnswer(message, rejectionMessage, expectedAnswer) {
   }
 }
 
-export function selectAnswer(message, choices) {
+/**
+ * @param {string} message
+ * @param {Array<unknown>} choices
+ * @param {string} [nonInteractiveHint] How to achieve the same result without a prompt (e.g. an option to use)
+ */
+export function selectAnswer(message, choices, nonInteractiveHint) {
+  assertInteractiveTerminal(nonInteractiveHint);
   return select({ message, choices }).catch(exitOnPromptError);
 }
 
-export function promptCheckbox(message, choices) {
+/**
+ * @param {string} message
+ * @param {Array<unknown>} choices
+ * @param {string} [nonInteractiveHint] How to achieve the same result without a prompt (e.g. an option to use)
+ */
+export function promptCheckbox(message, choices, nonInteractiveHint) {
+  assertInteractiveTerminal(nonInteractiveHint);
   return checkbox({ message, choices }).catch(exitOnPromptError);
 }
 
@@ -50,6 +62,22 @@ export function promptTextOption(option, defaultValue) {
   return input({ message, default: defaultValue, validate }).catch(exitOnPromptError);
 }
 
+/**
+ * Throw an explicit error when no interactive terminal is available.
+ *
+ * Raw-mode prompts (select, checkbox) need a TTY on stdin. Without one (CI, scripts,
+ * pipes, `< /dev/null`), Inquirer reads EOF and throws ExitPromptError, which
+ * exitOnPromptError turns into a silent `process.exit(1)` — indistinguishable from a
+ * user pressing Ctrl+C. Guarding up front lets us surface a clear message instead.
+ * @param {string} [hint] How to achieve the same result without a prompt (e.g. an option to use)
+ */
+function assertInteractiveTerminal(hint) {
+  if (!process.stdin.isTTY) {
+    const suffix = hint != null ? ` ${hint}` : '';
+    throw new Error(`This command requires an interactive terminal.${suffix}`);
+  }
+}
+
 function exitOnPromptError(error) {
   if (error instanceof Error && error.name === 'ExitPromptError') {
     process.exit(1);

package/src/models/drain.js

@@ -16,6 +16,7 @@ export async function resolveDrainResource(alias, appIdOrName, addonIdOrRealId)
 }
 
 export const DRAIN_TYPES = {
+  BETTERSTACK: { apiCode: 'BETTERSTACK', cliCode: 'betterstack', label: 'Better Stack' },
   DATADOG: { apiCode: 'DATADOG', cliCode: 'datadog', label: 'Datadog' },
   ELASTICSEARCH: { apiCode: 'ELASTICSEARCH', cliCode: 'elasticsearch', label: 'Elasticsearch' },
   NEWRELIC: { apiCode: 'NEWRELIC', cliCode: 'newrelic', label: 'New Relic' },

package/src/models/git-isomorphic.js

@@ -13,6 +13,9 @@ export class GitIsomorphic extends Git {
 
   async #getRepo() {
     const dir = await this._getRepoDir();
+    if (await this._isLinkedWorktree(dir)) {
+      throw new LinkedWorktreeNotSupportedError();
+    }
     return { fs, dir, http };
   }
 
@@ -128,7 +131,8 @@ export class GitIsomorphic extends Git {
    */
   async isInsideGitRepo() {
     this._debug('isInsideGitRepo');
-    return this.#getRepo()
+    // Don't go through #getRepo: it rejects linked worktrees, which are still git repos
+    return this._getRepoDir()
       .then(() => true)
       .catch(() => false);
   }
@@ -151,3 +155,14 @@ export class GitIsomorphic extends Git {
     return isStatusEmpty;
   }
 }
+
+export class LinkedWorktreeNotSupportedError extends Error {
+  constructor() {
+    super(
+      "Linked git worktrees aren't supported by the default JS git backend.\n" +
+        'Enable the system git backend (it uses your installed git):\n' +
+        '    clever features enable system-git',
+    );
+    this.name = 'LinkedWorktreeNotSupportedError';
+  }
+}

package/src/models/git.js

@@ -66,6 +66,24 @@ export class Git {
     }
   }
 
+  /**
+   * Check if the repository is a linked git worktree.
+   * In a linked worktree (created with `git worktree add`), the top-level `.git`
+   * is a file holding a `gitdir:` pointer instead of a directory.
+   * @protected
+   * @param {string} [dir] - Repository directory (resolved automatically when omitted)
+   * @returns {Promise<boolean>}
+   */
+  async _isLinkedWorktree(dir) {
+    const repoDir = dir ?? (await this._getRepoDir());
+    try {
+      const stats = await fs.promises.stat(path.join(repoDir, '.git'));
+      return stats.isFile();
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Add a remote to the repository
    * @param {string} remoteName

package/src/models/oauth-consumer.js

@@ -47,7 +47,7 @@ export async function promptRights(existingRights) {
     checked: existingRights?.[apiName] ?? false,
   }));
 
-  const selected = await promptCheckbox('Select rights', choices);
+  const selected = await promptCheckbox('Select rights', choices, 'Use --rights <list> to set rights directly.');
 
   return rightsFromList(selected);
 }

package/src/models/send-to-api.js

@@ -75,6 +75,15 @@ async function executeRequest(requestParams, customConfig = {}) {
     .catch(processError);
 }
 
+// OpenSSL error codes raised when the server certificate chain isn't trusted
+// (corporate TLS-intercepting proxy, private or self-signed CA…).
+const TLS_ERROR_CODES = [
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+];
+
 export function processError(error) {
   const code = error.code ?? error?.cause?.code;
   if (code === 'EAI_AGAIN') {
@@ -89,6 +98,12 @@ export function processError(error) {
       { cause: error },
     );
   }
+  if (TLS_ERROR_CODES.includes(code)) {
+    throw new Error(
+      `TLS certificate verification failed (${code}). If you're behind a corporate proxy or using a private/self-signed Certificate Authority, trust your CA and follow the "TLS certificates" section of the documentation.`,
+      { cause: error },
+    );
+  }
   throw error;
 }