@shopify/cli-kit 4.8.4 → 4.9.0

package/dist/public/node/error/index.js

@@ -0,0 +1,266 @@
+import { normalizePath } from '../path.js';
+import { flushStdout, stringifyMessage, TokenizedString } from '../output.js';
+import { tokenItemToString } from '../../../private/node/ui/components/token-item.js';
+import { hasRateLimitCode } from '../../../private/node/analytics/graphql-error-codes.js';
+import { isGatewayErrorStatus } from '../../../private/node/api/status-checks.js';
+import { Errors } from '@oclif/core';
+export var FatalErrorType;
+(function (FatalErrorType) {
+    // These values are also read from errors created by other cli-kit copies. Do not renumber them.
+    FatalErrorType[FatalErrorType["Abort"] = 0] = "Abort";
+    FatalErrorType[FatalErrorType["AbortSilent"] = 1] = "AbortSilent";
+    FatalErrorType[FatalErrorType["Bug"] = 2] = "Bug";
+})(FatalErrorType || (FatalErrorType = {}));
+export class CancelExecution extends Error {
+}
+/**
+ * A fatal error represents an error shouldn't be rescued and that causes the execution to terminate.
+ * There shouldn't be code that catches fatal errors.
+ */
+export class FatalError extends Error {
+    tryMessage;
+    type;
+    nextSteps;
+    formattedMessage;
+    customSections;
+    /** A stable code for JSON consumers to identify this error, included only when known. */
+    code;
+    /** Selected JSON-serializable data to include in JSON errors. Never attach the raw error or request. */
+    details;
+    skipOclifErrorHandling;
+    /**
+     * Creates a new FatalError error.
+     *
+     * @param message - The error message.
+     * @param type - The type of fatal error.
+     * @param tryMessage - The message that recommends next steps to the user.
+     * You can pass a string a {@link TokenizedString} or a {@link TokenItem}
+     * if you need to style the message inside the error Banner component.
+     * @param nextSteps - Message to show as "next steps" with suggestions to solve the issue.
+     * @param customSections - Custom sections to show in the error banner. To be used if nextSteps is not enough.
+     */
+    constructor(message, type, tryMessage = null, nextSteps, customSections) {
+        const messageIsOutputMessage = typeof message === 'string' || 'value' in message;
+        super(messageIsOutputMessage ? stringifyMessage(message) : tokenItemToString(message));
+        if (tryMessage) {
+            if (tryMessage instanceof TokenizedString) {
+                this.tryMessage = stringifyMessage(tryMessage);
+            }
+            else {
+                this.tryMessage = tryMessage;
+            }
+        }
+        else {
+            this.tryMessage = null;
+        }
+        this.type = type;
+        this.nextSteps = nextSteps;
+        this.customSections = customSections;
+        this.skipOclifErrorHandling = true;
+        if (!messageIsOutputMessage) {
+            this.formattedMessage = message;
+        }
+    }
+}
+/**
+ * An abort error is a fatal error that shouldn't be reported as a bug.
+ * Those usually represent unexpected scenarios that we can't handle and that usually require some action from the developer.
+ */
+export class AbortError extends FatalError {
+    constructor(message, tryMessage = null, nextSteps, customSections) {
+        super(message, FatalErrorType.Abort, tryMessage, nextSteps, customSections);
+    }
+}
+/**
+ * An external error is similar to Abort but has extra command and args attributes.
+ * This is useful to represent errors coming from external commands, usually executed by execa.
+ */
+export class ExternalError extends FatalError {
+    command;
+    args;
+    constructor(message, command, args, tryMessage = null) {
+        super(message, FatalErrorType.Abort, tryMessage);
+        this.command = command;
+        this.args = args;
+    }
+}
+export class AbortSilentError extends FatalError {
+    constructor() {
+        super('', FatalErrorType.AbortSilent);
+    }
+}
+/**
+ * A bug error is an error that represents a bug and therefore should be reported.
+ */
+export class BugError extends FatalError {
+    constructor(message, tryMessage = null) {
+        super(message, FatalErrorType.Bug, tryMessage);
+    }
+}
+/**
+ * A function that handles errors that blow up in the CLI.
+ *
+ * @param error - Error to be handled.
+ * @returns A promise that resolves with the error passed.
+ */
+export async function handler(error) {
+    let fatal;
+    if (isFatal(error)) {
+        fatal = error;
+    }
+    else if (typeof error === 'string') {
+        fatal = new BugError(error);
+    }
+    else if (error instanceof Error) {
+        fatal = new BugError(error.message);
+        fatal.stack = error.stack;
+    }
+    else {
+        // errors can come in all shapes and sizes...
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const maybeError = error;
+        fatal = new BugError(maybeError?.message ?? 'Unknown error');
+        if (maybeError?.stack) {
+            fatal.stack = maybeError?.stack;
+        }
+    }
+    const { jsonOutputEnabled } = await import('../environment.js');
+    if (jsonOutputEnabled()) {
+        const { renderFatalErrorAsJson } = await import('../../../private/node/json-error.js');
+        renderFatalErrorAsJson(fatal);
+        await flushStdout();
+        return error;
+    }
+    const { renderFatalError } = await import('../ui.js');
+    renderFatalError(fatal);
+    return Promise.resolve(error);
+}
+/**
+ * A function that maps an error to an Abort with the stack trace when coming from the CLI.
+ *
+ * @param error - Error to be mapped.
+ * @returns A promise that resolves with the new error object.
+ */
+export function errorMapper(error) {
+    if (error instanceof Errors.CLIError) {
+        const mappedError = new AbortError(error.message);
+        mappedError.stack = error.stack;
+        return Promise.resolve(mappedError);
+    }
+    else {
+        return Promise.resolve(error);
+    }
+}
+/**
+ * A function that checks if an error is a fatal one.
+ *
+ * @param error - Error to be checked.
+ * @returns A boolean indicating if the error is a fatal one.
+ */
+function isFatal(error) {
+    try {
+        return Object.prototype.hasOwnProperty.call(error, 'type');
+        // eslint-disable-next-line no-catch-all/no-catch-all
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A function that checks if an error should be reported as unexpected.
+ *
+ * @param error - Error to be checked.
+ * @returns A boolean indicating if the error should be reported as unexpected.
+ */
+export function shouldReportErrorAsUnexpected(error) {
+    if (!isFatal(error)) {
+        // this means its not one of the CLI wrapped errors
+        if (error instanceof Error) {
+            // Raw API errors that slip through unwrapped (e.g. the handleErrors:false path) are expected
+            // environmental conditions, not CLI bugs. Treat them as expected so they don't pollute crash
+            // reporting.
+            if (isExpectedApiError(error)) {
+                return false;
+            }
+            const message = error.message;
+            return !errorMessageImpliesEnvironmentIssue(message);
+        }
+        return true;
+    }
+    if (error.type === FatalErrorType.Bug) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Detects raw graphql-request `ClientError`s that are expected environmental conditions rather than
+ * CLI bugs. These reach the reporter as plain `Error`s (not `FatalError`s) and would otherwise be
+ * reported as unexpected.
+ *
+ * HTTP 401 (unauthenticated) is not "transient" in the retry sense — it means the user's session
+ * token is expired or invalid, a credential/environment condition (see issue #7891). Rate limiting
+ * (HTTP 429, or a `THROTTLED`/`429` GraphQL code on any error in the response) matches the shape
+ * detected by `errorsIncludeStatus429` in `private/node/api.ts`. Gateway errors (502/503/504) are
+ * also expected infrastructure failures.
+ *
+ * Scoped to the external `ClientError` shape only — importing the cli-kit `GraphQLClientError`
+ * wrapper here would create an `error.ts → headers.ts → error.ts` import cycle.
+ *
+ * Matched structurally rather than with `instanceof ClientError`, because importing the class
+ * pulls `graphql-request` — and through it `graphql`, `tr46` and `whatwg-url` — into the module
+ * graph of every command, for one type check on an error path. `ClientError` is the only error
+ * reaching here that carries both `response` and `request`; the cli-kit wrapper carries
+ * `statusCode` instead (see `private/node/api/headers.ts`).
+ *
+ * @param error - Error to be checked.
+ * @returns A boolean indicating if the error is a known expected API error.
+ */
+function isExpectedApiError(error) {
+    const candidate = error;
+    if (typeof candidate.response !== 'object' || candidate.response === null || candidate.request === undefined) {
+        return false;
+    }
+    const status = candidate.response.status;
+    if (status === 401 || status === 429 || isGatewayErrorStatus(status)) {
+        return true;
+    }
+    return hasRateLimitCode(candidate.response.errors);
+}
+/**
+ * Stack traces usually have file:// - we strip that and also remove the Windows drive designation.
+ *
+ * @param filePath - Path to be cleaned.
+ * @returns The cleaned path.
+ */
+export function cleanSingleStackTracePath(filePath) {
+    return normalizePath(filePath)
+        .replace('file:/', '/')
+        .replace(/^\/?[A-Z]:/, '');
+}
+/**
+ * There are certain errors that we know are not due to a CLI bug, but are environmental/user error.
+ *
+ * @param message - The error message to check.
+ * @returns A boolean indicating if the error message implies an environment issue.
+ */
+function errorMessageImpliesEnvironmentIssue(message) {
+    const environmentIssueMessages = [
+        'EPERM: operation not permitted, scandir',
+        'EPERM: operation not permitted, rename',
+        'EACCES: permission denied',
+        'EPERM: operation not permitted, symlink',
+        'This version of npm supports the following node versions',
+        'EBUSY: resource busy or locked',
+        'ENOTEMPTY: directory not empty',
+        'getaddrinfo ENOTFOUND',
+        'Client network socket disconnected before secure TLS connection was established',
+        'spawn EPERM',
+        'socket hang up',
+        'The user aborted a request.',
+        'write EPIPE',
+        'Unsupported platform',
+    ];
+    const anyMatches = environmentIssueMessages.some((issueMessage) => message.includes(issueMessage));
+    return anyMatches;
+}
+//# sourceMappingURL=index.js.map

package/dist/public/node/error/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/public/node/error/index.ts"],"names":[],"mappings":"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","sourcesContent":["import {normalizePath} from '../path.js'\nimport {flushStdout, OutputMessage, stringifyMessage, TokenizedString} from '../output.js'\nimport {tokenItemToString, type InlineToken, type TokenItem} from '../../../private/node/ui/components/token-item.js'\nimport {hasRateLimitCode} from '../../../private/node/analytics/graphql-error-codes.js'\nimport {isGatewayErrorStatus} from '../../../private/node/api/status-checks.js'\n\nimport {Errors} from '@oclif/core'\n\nimport type {AlertCustomSection} from '../ui.js'\n\nexport enum FatalErrorType {\n  // These values are also read from errors created by other cli-kit copies. Do not renumber them.\n  Abort = 0,\n  AbortSilent = 1,\n  Bug = 2,\n}\n\nexport class CancelExecution extends Error {}\n\n/**\n * A fatal error represents an error shouldn't be rescued and that causes the execution to terminate.\n * There shouldn't be code that catches fatal errors.\n */\nexport abstract class FatalError extends Error {\n  tryMessage: TokenItem | null\n  type: FatalErrorType\n  nextSteps?: TokenItem<InlineToken>[]\n  formattedMessage?: TokenItem\n  customSections?: AlertCustomSection[]\n  /** A stable code for JSON consumers to identify this error, included only when known. */\n  code?: string\n  /** Selected JSON-serializable data to include in JSON errors. Never attach the raw error or request. */\n  details?: unknown\n  skipOclifErrorHandling: boolean\n  /**\n   * Creates a new FatalError error.\n   *\n   * @param message - The error message.\n   * @param type - The type of fatal error.\n   * @param tryMessage - The message that recommends next steps to the user.\n   * You can pass a string a {@link TokenizedString} or a {@link TokenItem}\n   * if you need to style the message inside the error Banner component.\n   * @param nextSteps - Message to show as \"next steps\" with suggestions to solve the issue.\n   * @param customSections - Custom sections to show in the error banner. To be used if nextSteps is not enough.\n   */\n  constructor(\n    message: TokenItem | OutputMessage,\n    type: FatalErrorType,\n    tryMessage: TokenItem | OutputMessage | null = null,\n    nextSteps?: TokenItem<InlineToken>[],\n    customSections?: AlertCustomSection[],\n  ) {\n    const messageIsOutputMessage = typeof message === 'string' || 'value' in message\n    super(messageIsOutputMessage ? stringifyMessage(message) : tokenItemToString(message))\n\n    if (tryMessage) {\n      if (tryMessage instanceof TokenizedString) {\n        this.tryMessage = stringifyMessage(tryMessage)\n      } else {\n        this.tryMessage = tryMessage\n      }\n    } else {\n      this.tryMessage = null\n    }\n\n    this.type = type\n    this.nextSteps = nextSteps\n    this.customSections = customSections\n    this.skipOclifErrorHandling = true\n\n    if (!messageIsOutputMessage) {\n      this.formattedMessage = message\n    }\n  }\n}\n\n/**\n * An abort error is a fatal error that shouldn't be reported as a bug.\n * Those usually represent unexpected scenarios that we can't handle and that usually require some action from the developer.\n */\nexport class AbortError extends FatalError {\n  constructor(\n    message: TokenItem | OutputMessage,\n    tryMessage: TokenItem | OutputMessage | null = null,\n    nextSteps?: TokenItem<InlineToken>[],\n    customSections?: AlertCustomSection[],\n  ) {\n    super(message, FatalErrorType.Abort, tryMessage, nextSteps, customSections)\n  }\n}\n\n/**\n * An external error is similar to Abort but has extra command and args attributes.\n * This is useful to represent errors coming from external commands, usually executed by execa.\n */\nexport class ExternalError extends FatalError {\n  command: string\n  args: string[]\n\n  constructor(\n    message: OutputMessage,\n    command: string,\n    args: string[],\n    tryMessage: TokenItem | OutputMessage | null = null,\n  ) {\n    super(message, FatalErrorType.Abort, tryMessage)\n    this.command = command\n    this.args = args\n  }\n}\n\nexport class AbortSilentError extends FatalError {\n  constructor() {\n    super('', FatalErrorType.AbortSilent)\n  }\n}\n\n/**\n * A bug error is an error that represents a bug and therefore should be reported.\n */\nexport class BugError extends FatalError {\n  constructor(message: TokenItem | OutputMessage, tryMessage: TokenItem | OutputMessage | null = null) {\n    super(message, FatalErrorType.Bug, tryMessage)\n  }\n}\n\n/**\n * A function that handles errors that blow up in the CLI.\n *\n * @param error - Error to be handled.\n * @returns A promise that resolves with the error passed.\n */\nexport async function handler(error: unknown): Promise<unknown> {\n  let fatal: FatalError\n  if (isFatal(error)) {\n    fatal = error\n  } else if (typeof error === 'string') {\n    fatal = new BugError(error)\n  } else if (error instanceof Error) {\n    fatal = new BugError(error.message)\n    fatal.stack = error.stack\n  } else {\n    // errors can come in all shapes and sizes...\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const maybeError = error as any\n    fatal = new BugError(maybeError?.message ?? 'Unknown error')\n    if (maybeError?.stack) {\n      fatal.stack = maybeError?.stack\n    }\n  }\n\n  const {jsonOutputEnabled} = await import('../environment.js')\n  if (jsonOutputEnabled()) {\n    const {renderFatalErrorAsJson} = await import('../../../private/node/json-error.js')\n    renderFatalErrorAsJson(fatal)\n    await flushStdout()\n    return error\n  }\n\n  const {renderFatalError} = await import('../ui.js')\n  renderFatalError(fatal)\n  return Promise.resolve(error)\n}\n\n/**\n * A function that maps an error to an Abort with the stack trace when coming from the CLI.\n *\n * @param error - Error to be mapped.\n * @returns A promise that resolves with the new error object.\n */\nexport function errorMapper(error: unknown): Promise<unknown> {\n  if (error instanceof Errors.CLIError) {\n    const mappedError = new AbortError(error.message)\n    mappedError.stack = error.stack\n    return Promise.resolve(mappedError)\n  } else {\n    return Promise.resolve(error)\n  }\n}\n\n/**\n * A function that checks if an error is a fatal one.\n *\n * @param error - Error to be checked.\n * @returns A boolean indicating if the error is a fatal one.\n */\nfunction isFatal(error: unknown): error is FatalError {\n  try {\n    return Object.prototype.hasOwnProperty.call(error, 'type')\n    // eslint-disable-next-line no-catch-all/no-catch-all\n  } catch {\n    return false\n  }\n}\n\n/**\n * A function that checks if an error should be reported as unexpected.\n *\n * @param error - Error to be checked.\n * @returns A boolean indicating if the error should be reported as unexpected.\n */\nexport function shouldReportErrorAsUnexpected(error: unknown): boolean {\n  if (!isFatal(error)) {\n    // this means its not one of the CLI wrapped errors\n    if (error instanceof Error) {\n      // Raw API errors that slip through unwrapped (e.g. the handleErrors:false path) are expected\n      // environmental conditions, not CLI bugs. Treat them as expected so they don't pollute crash\n      // reporting.\n      if (isExpectedApiError(error)) {\n        return false\n      }\n      const message = error.message\n      return !errorMessageImpliesEnvironmentIssue(message)\n    }\n    return true\n  }\n  if (error.type === FatalErrorType.Bug) {\n    return true\n  }\n  return false\n}\n\n/**\n * Detects raw graphql-request `ClientError`s that are expected environmental conditions rather than\n * CLI bugs. These reach the reporter as plain `Error`s (not `FatalError`s) and would otherwise be\n * reported as unexpected.\n *\n * HTTP 401 (unauthenticated) is not \"transient\" in the retry sense — it means the user's session\n * token is expired or invalid, a credential/environment condition (see issue #7891). Rate limiting\n * (HTTP 429, or a `THROTTLED`/`429` GraphQL code on any error in the response) matches the shape\n * detected by `errorsIncludeStatus429` in `private/node/api.ts`. Gateway errors (502/503/504) are\n * also expected infrastructure failures.\n *\n * Scoped to the external `ClientError` shape only — importing the cli-kit `GraphQLClientError`\n * wrapper here would create an `error.ts → headers.ts → error.ts` import cycle.\n *\n * Matched structurally rather than with `instanceof ClientError`, because importing the class\n * pulls `graphql-request` — and through it `graphql`, `tr46` and `whatwg-url` — into the module\n * graph of every command, for one type check on an error path. `ClientError` is the only error\n * reaching here that carries both `response` and `request`; the cli-kit wrapper carries\n * `statusCode` instead (see `private/node/api/headers.ts`).\n *\n * @param error - Error to be checked.\n * @returns A boolean indicating if the error is a known expected API error.\n */\nfunction isExpectedApiError(error: Error): boolean {\n  const candidate = error as Error & {\n    response?: {status?: number; errors?: unknown}\n    request?: unknown\n  }\n  if (typeof candidate.response !== 'object' || candidate.response === null || candidate.request === undefined) {\n    return false\n  }\n  const status = candidate.response.status\n  if (status === 401 || status === 429 || isGatewayErrorStatus(status)) {\n    return true\n  }\n  return hasRateLimitCode(candidate.response.errors)\n}\n\n/**\n * Stack traces usually have file:// - we strip that and also remove the Windows drive designation.\n *\n * @param filePath - Path to be cleaned.\n * @returns The cleaned path.\n */\nexport function cleanSingleStackTracePath(filePath: string): string {\n  return normalizePath(filePath)\n    .replace('file:/', '/')\n    .replace(/^\\/?[A-Z]:/, '')\n}\n\n/**\n * There are certain errors that we know are not due to a CLI bug, but are environmental/user error.\n *\n * @param message - The error message to check.\n * @returns A boolean indicating if the error message implies an environment issue.\n */\nfunction errorMessageImpliesEnvironmentIssue(message: string): boolean {\n  const environmentIssueMessages = [\n    'EPERM: operation not permitted, scandir',\n    'EPERM: operation not permitted, rename',\n    'EACCES: permission denied',\n    'EPERM: operation not permitted, symlink',\n    'This version of npm supports the following node versions',\n    'EBUSY: resource busy or locked',\n    'ENOTEMPTY: directory not empty',\n    'getaddrinfo ENOTFOUND',\n    'Client network socket disconnected before secure TLS connection was established',\n    'spawn EPERM',\n    'socket hang up',\n    'The user aborted a request.',\n    'write EPIPE',\n    'Unsupported platform',\n  ]\n  const anyMatches = environmentIssueMessages.some((issueMessage) => message.includes(issueMessage))\n  return anyMatches\n}\n"]}