@sentry/cli 2.58.2 → 2.58.3-alpha0

package/js/index.d.ts

@@ -1,248 +1,73 @@
+export = SentryCli;
 /**
- * Typings for @sentry/cli
+ * @typedef {import('./types').SentryCliOptions} SentryCliOptions
+ * @typedef {import('./types').SentryCliUploadSourceMapsOptions} SentryCliUploadSourceMapsOptions
+ * @typedef {import('./types').SourceMapsPathDescriptor} SourceMapsPathDescriptor
+ * @typedef {import('./types').SentryCliNewDeployOptions} SentryCliNewDeployOptions
+ * @typedef {import('./types').SentryCliCommitsOptions} SentryCliCommitsOptions
+ * @typedef {import('./types').SentryCliReleases} SentryCliReleases
  */
-declare module '@sentry/cli' {
-  export interface SentryCliOptions {
-    /**
-     * The URL of the Sentry instance you are connecting to. Defaults to https://sentry.io/.
-     * This value will update `SENTRY_URL env variable.
-     */
-    url?: string;
-    /**
-     * Authentication token for HTTP requests to Sentry.
-     * This value will update `SENTRY_AUTH_TOKEN` env variable.
-     */
-    authToken?: string;
-    /**
-     * API key to authenticate any HTTP requests to Sentry (legacy authentication method).
-     * This value will update `SENTRY_API_KEY` env variable.
-     * @deprecated Use auth-token-based authentication via `authToken` instead.
-     *    This option is scheduled for removal in the next major release.
-     */
-    apiKey?: string;
-    /**
-     * Sentry DSN.
-     * This value will update `SENTRY_DSN` env variable.
-     */
-    dsn?: string;
-    /**
-     * Organization slug.
-     * This value will update `SENTRY_ORG` env variable.
-     */
-    org?: string;
-    /**
-     * Project Project slug.
-     * This value will update `SENTRY_PROJECT` env variable.
-     */
-    project?: string;
-    /**
-     * Version control system remote name.
-     * This value will update `SENTRY_VCS_REMOTE` env variable.
-     */
-    vcsRemote?: string;
-    /**
-     * If true, all logs are suppressed.
-     */
-    silent?: boolean;
-    /**
-     * A header added to every outgoing network request.
-     * This value will update `CUSTOM_HEADER` env variable.
-     */
-    customHeader?: string;
-    /**
-     * Headers added to every outgoing network request.
-     * This value does not set any env variable, and is overridden by `customHeader`.
-     */
-    headers?: Record<string, string>;
-  }
-
-  /**
-   * Custom upload-sourcemaps options for a particular `include` path. In this
-   * case `paths` takes the place of `include` in the options so as to make it
-   * clear that this is not recursive.
-   */
-  export type SourceMapsPathDescriptor = Omit<SentryCliUploadSourceMapsOptions, 'include'> & {
-    paths: string[];
-  };
-
-  export interface SentryCliUploadSourceMapsOptions {
-    /**
-     * One or more paths that Sentry CLI should scan recursively for sources.
-     * It will upload all .map files and match associated .js files.
-     */
-    include: Array<string | SourceMapsPathDescriptor>;
-    /**
-     * One or more paths to ignore during upload. Overrides entries in ignoreFile file.
-     */
-    ignore?: string[];
-    /**
-     * Path to a file containing list of files/directories to ignore.
-     * Can point to .gitignore or anything with same format.
-     */
-    ignoreFile?: string | null;
-    /**
-     * Enables rewriting of matching sourcemaps so that indexed maps are flattened
-     * and missing sources are inlined if possible. Defaults to `true`.
-     */
-    rewrite?: boolean;
-    /**
-     * This prevents the automatic detection of sourcemap references.
-     */
-    sourceMapReference?: boolean;
-    /**
-     * Enables files gzip decompression prior to uploading. Defaults to `false`.
-     */
-    decompress?: boolean;
-    /**
-     * Enable artifacts deduplication prior to uploading. This will skip uploading
-     * any artifacts that are already present on the server. Defaults to `true`.
-     */
-    dedupe?: boolean;
-    /**
-     * When paired with the rewrite option this will remove a prefix from uploaded files.
-     * For instance you can use this to remove a path that is build machine specific.
-     */
-    stripPrefix?: string[];
-    /**
-     * When paired with the rewrite option this will add ~ to the stripPrefix array.
-     */
-    stripCommonPrefix?: boolean;
-    /**
-     * The projects to upload the sourcemaps to. If not provided, the sourcemaps will be uploaded to the default project.
-     */
-    projects?: string[];
-    /**
-     * This attempts sourcemap validation before upload when rewriting is not enabled.
-     * It will spot a variety of issues with source maps and cancel the upload if any are found.
-     * This is not enabled by default as this can cause false positives.
-     */
-    validate?: boolean;
-    /**
-     * This sets an URL prefix at the beginning of all files.
-     * This defaults to `~/` but you might want to set this to the full URL.
-     * This is also useful if your files are stored in a sub folder. eg: url-prefix `~/static/js`.
-     */
-    urlPrefix?: string;
-    /**
-     * This sets an URL suffix at the end of all files.
-     * Useful for appending query parameters.
-     */
-    urlSuffix?: string;
+/**
+ * Interface to and wrapper around the `sentry-cli` executable.
+ *
+ * Commands are grouped into namespaces. See the respective namespaces for more
+ * documentation. To use this wrapper, simply create an instance and call methods:
+ *
+ * @example
+ * const cli = new SentryCli();
+ * console.log(SentryCli.getVersion());
+ *
+ * @example
+ * const cli = new SentryCli('path/to/custom/sentry.properties');
+ * const release = await cli.releases.proposeVersion());
+ * console.log(release);
+ */
+declare class SentryCli {
     /**
-     * This sets the file extensions to be considered.
-     * By default the following file extensions are processed: js, map, jsbundle and bundle.
+     * Returns the version of the installed `sentry-cli` binary.
+     * @returns {string}
      */
-    ext?: string[];
+    static getVersion(): string;
     /**
-     * Unique identifier for the distribution, used to further segment your release.
-     * Usually your build number.
+     * Returns an absolute path to the `sentry-cli` binary.
+     * @returns {string}
      */
-    dist?: string;
+    static getPath(): string;
     /**
-     * Force use of new Artifact Bundles upload, that enables use of Debug ID for Source Maps discovery,
-     * even when the Sentry server does not declare support for it.
+     * Creates a new `SentryCli` instance.
      *
-     * @deprecated This option is deprecated and will be removed in the next major version. Sentry CLI
-     *     should always respect what the server says it supports.
-     */
-    useArtifactBundle?: boolean;
-  }
-
-  export interface SentryCliNewDeployOptions {
-    /**
-     * Environment for this release. Values that make sense here would be `production` or `staging`.
-     */
-    env: string;
-    /**
-     * Deployment start time in Unix timestamp (in seconds) or ISO 8601 format.
-     */
-    started?: number | string;
-    /**
-     * Deployment finish time in Unix timestamp (in seconds) or ISO 8601 format.
-     */
-    finished?: number | string;
-    /**
-     * Deployment duration (in seconds). Can be used instead of started and finished.
-     */
-    time?: number;
-    /**
-     * Human readable name for the deployment.
-     */
-    name?: string;
-    /**
-     * URL that points to the deployment.
-     */
-    url?: string;
-  }
-
-  export interface SentryCliCommitsOptions {
-    /**
-     * Automatically choose the associated commit (uses the current commit). Overrides other setCommit options.
-     */
-    auto?: boolean;
-    /**
-     * The full repo name as defined in Sentry. Required if auto option is not true.
-     */
-    repo?: string;
-    /**
-     * The current (last) commit in the release. Required if auto option is not true.
-     */
-    commit?: string;
-    /**
-     * The commit before the beginning of this release (in other words, the last commit of the previous release).
-     * If omitted, this will default to the last commit of the previous release in Sentry.
-     * If there was no previous release, the last 10 commits will be used.
-     */
-    previousCommit?: string;
-    /**
-     * When the flag is set and the previous release commit was not found in the repository, will create a release
-     * with the default commits count(or the one specified with `--initial-depth`) instead of failing the command.
-     */
-    ignoreMissing?: boolean;
-    /**
-     * When the flag is set, command will not fail and just exit silently if no new commits for a given release have been found.
-     */
-    ignoreEmpty?: boolean;
-  }
-
-  export interface SentryCliReleases {
-    ['new'](release: string, options?: { projects: string[] } | string[]): Promise<string>;
-
-    setCommits(release: string, options: SentryCliCommitsOptions): Promise<string>;
-
-    finalize(release: string): Promise<string>;
-
-    proposeVersion(): Promise<string>;
-
-    uploadSourceMaps(
-      release: string,
-      options: SentryCliUploadSourceMapsOptions & { live?: boolean | 'rejectOnError' }
-    ): Promise<string>;
-
-    listDeploys(release: string): Promise<string>;
-
-    newDeploy(release: string, options: SentryCliNewDeployOptions): Promise<string>;
-
-    execute(args: string[], live: boolean | 'rejectOnError'): Promise<string>;
-  }
-
-  export default class SentryCli {
-    /**
-     * Creates a new instance of SentryCli class
+     * If the `configFile` parameter is specified, configuration located in the default
+     * location and the value specified in the `SENTRY_PROPERTIES` environment variable is
+     * overridden.
      *
-     * @param configFile Path to Sentry CLI config properties, as described in https://docs.sentry.io/learn/cli/configuration/#properties-files.
+     * @param {string | null} [configFile] - Path to Sentry CLI config properties, as described in https://docs.sentry.io/learn/cli/configuration/#properties-files.
      * By default, the config file is looked for upwards from the current path and defaults from ~/.sentryclirc are always loaded.
      * This value will update `SENTRY_PROPERTIES` env variable.
-     * @param options {@link SentryCliOptions}
+     * @param {SentryCliOptions} [options] - More options to pass to the CLI
      */
     constructor(configFile?: string | null, options?: SentryCliOptions);
-
-    public configFile?: string;
-    public options?: SentryCliOptions;
-    public releases: SentryCliReleases;
-
-    public static getVersion(): string;
-    public static getPath(): string;
-    public execute(args: string[], live: boolean | 'rejectOnError'): Promise<string>;
-  }
+    configFile: string;
+    options: import("./types").SentryCliOptions;
+    releases: Releases;
+    /**
+     * See {helper.execute} docs.
+     * @param {string[]} args Command line arguments passed to `sentry-cli`.
+     * @param {boolean | 'rejectOnError'} live can be set to:
+     *  - `true` to inherit stdio to display `sentry-cli` output directly.
+     *  - `false` to not inherit stdio and return the output as a string.
+     *  - `'rejectOnError'` to inherit stdio and reject the promise if the command
+     *    exits with a non-zero exit code.
+     * @returns {Promise<string>} A promise that resolves to the standard output.
+     */
+    execute(args: string[], live: boolean | "rejectOnError"): Promise<string>;
+}
+declare namespace SentryCli {
+    export { SentryCliOptions, SentryCliUploadSourceMapsOptions, SourceMapsPathDescriptor, SentryCliNewDeployOptions, SentryCliCommitsOptions, SentryCliReleases };
 }
+import Releases = require("./releases");
+type SentryCliOptions = import("./types").SentryCliOptions;
+type SentryCliUploadSourceMapsOptions = import("./types").SentryCliUploadSourceMapsOptions;
+type SourceMapsPathDescriptor = import("./types").SourceMapsPathDescriptor;
+type SentryCliNewDeployOptions = import("./types").SentryCliNewDeployOptions;
+type SentryCliCommitsOptions = import("./types").SentryCliCommitsOptions;
+type SentryCliReleases = import("./types").SentryCliReleases;

package/js/index.js

@@ -1,9 +1,15 @@
 'use strict';
-
 const pkgInfo = require('../package.json');
 const helper = require('./helper');
 const Releases = require('./releases');
-
+/**
+ * @typedef {import('./types').SentryCliOptions} SentryCliOptions
+ * @typedef {import('./types').SentryCliUploadSourceMapsOptions} SentryCliUploadSourceMapsOptions
+ * @typedef {import('./types').SourceMapsPathDescriptor} SourceMapsPathDescriptor
+ * @typedef {import('./types').SentryCliNewDeployOptions} SentryCliNewDeployOptions
+ * @typedef {import('./types').SentryCliCommitsOptions} SentryCliCommitsOptions
+ * @typedef {import('./types').SentryCliReleases} SentryCliReleases
+ */
 /**
  * Interface to and wrapper around the `sentry-cli` executable.
  *
@@ -20,53 +26,51 @@ const Releases = require('./releases');
  * console.log(release);
  */
 class SentryCli {
-  /**
-   * Creates a new `SentryCli` instance.
-   *
-   * If the `configFile` parameter is specified, configuration located in the default
-   * location and the value specified in the `SENTRY_PROPERTIES` environment variable is
-   * overridden.
-   *
-   * @param {string} [configFile] Relative or absolute path to the configuration file.
-   * @param {Object} [options] More options to pass to the CLI
-   */
-  constructor(configFile, options) {
-    if (typeof configFile === 'string') {
-      this.configFile = configFile;
+    /**
+     * Creates a new `SentryCli` instance.
+     *
+     * If the `configFile` parameter is specified, configuration located in the default
+     * location and the value specified in the `SENTRY_PROPERTIES` environment variable is
+     * overridden.
+     *
+     * @param {string | null} [configFile] - Path to Sentry CLI config properties, as described in https://docs.sentry.io/learn/cli/configuration/#properties-files.
+     * By default, the config file is looked for upwards from the current path and defaults from ~/.sentryclirc are always loaded.
+     * This value will update `SENTRY_PROPERTIES` env variable.
+     * @param {SentryCliOptions} [options] - More options to pass to the CLI
+     */
+    constructor(configFile, options) {
+        if (typeof configFile === 'string') {
+            this.configFile = configFile;
+        }
+        this.options = options || { silent: false };
+        this.releases = new Releases(Object.assign(Object.assign({}, this.options), { configFile }));
+    }
+    /**
+     * Returns the version of the installed `sentry-cli` binary.
+     * @returns {string}
+     */
+    static getVersion() {
+        return pkgInfo.version;
+    }
+    /**
+     * Returns an absolute path to the `sentry-cli` binary.
+     * @returns {string}
+     */
+    static getPath() {
+        return helper.getPath();
+    }
+    /**
+     * See {helper.execute} docs.
+     * @param {string[]} args Command line arguments passed to `sentry-cli`.
+     * @param {boolean | 'rejectOnError'} live can be set to:
+     *  - `true` to inherit stdio to display `sentry-cli` output directly.
+     *  - `false` to not inherit stdio and return the output as a string.
+     *  - `'rejectOnError'` to inherit stdio and reject the promise if the command
+     *    exits with a non-zero exit code.
+     * @returns {Promise<string>} A promise that resolves to the standard output.
+     */
+    execute(args, live) {
+        return helper.execute(args, live, this.options.silent, this.configFile, this.options);
     }
-    this.options = options || { silent: false };
-    this.releases = new Releases({ ...this.options, configFile });
-  }
-
-  /**
-   * Returns the version of the installed `sentry-cli` binary.
-   * @returns {string}
-   */
-  static getVersion() {
-    return pkgInfo.version;
-  }
-
-  /**
-   * Returns an absolute path to the `sentry-cli` binary.
-   * @returns {string}
-   */
-  static getPath() {
-    return helper.getPath();
-  }
-
-  /**
-   * See {helper.execute} docs.
-   * @param {string[]} args Command line arguments passed to `sentry-cli`.
-   * @param {boolean | 'rejectOnError'} live can be set to:
-   *  - `true` to inherit stdio to display `sentry-cli` output directly.
-   *  - `false` to not inherit stdio and return the output as a string.
-   *  - `'rejectOnError'` to inherit stdio and reject the promise if the command
-   *    exits with a non-zero exit code.
-   * @returns {Promise.<string>} A promise that resolves to the standard output.
-   */
-  execute(args, live) {
-    return helper.execute(args, live, this.options.silent, this.configFile, this.options);
-  }
 }
-
 module.exports = SentryCli;

package/js/logger.d.ts

@@ -0,0 +1,6 @@
+export = Logger;
+declare class Logger {
+    constructor(stream: any);
+    stream: any;
+    log(...args: any[]): void;
+}

package/js/logger.js

@@ -1,14 +1,11 @@
 'use strict';
-
 const format = require('util').format;
-
 module.exports = class Logger {
-  constructor(stream) {
-    this.stream = stream;
-  }
-
-  log() {
-    const message = format(...arguments);
-    this.stream.write(`[sentry-cli] ${message}\n`);
-  }
+    constructor(stream) {
+        this.stream = stream;
+    }
+    log() {
+        const message = format(...arguments);
+        this.stream.write(`[sentry-cli] ${message}\n`);
+    }
 };

package/js/releases/index.d.ts

@@ -0,0 +1,148 @@
+export = Releases;
+/**
+ * @typedef {import('../types').SentryCliUploadSourceMapsOptions} SentryCliUploadSourceMapsOptions
+ * @typedef {import('../types').SourceMapsPathDescriptor} SourceMapsPathDescriptor
+ * @typedef {import('../types').SentryCliNewDeployOptions} SentryCliNewDeployOptions
+ * @typedef {import('../types').SentryCliCommitsOptions} SentryCliCommitsOptions
+ */
+/**
+ * Manages releases and release artifacts on Sentry.
+ * @namespace SentryReleases
+ */
+declare class Releases {
+    /**
+     * Creates a new `Releases` instance.
+     *
+     * @param {Object} [options] More options to pass to the CLI
+     */
+    constructor(options?: any);
+    options: any;
+    configFile: any;
+    /**
+     * Registers a new release with sentry.
+     *
+     * The given release name should be unique and deterministic. It can later be used to
+     * upload artifacts, such as source maps.
+     *
+     * @param {string} release Unique name of the new release.
+     * @param {{projects?: string[]}} [options] The list of project slugs for a release.
+     * @returns {Promise<string>} A promise that resolves when the release has been created.
+     * @memberof SentryReleases
+     */
+    "new"(release: string, options?: {
+        projects?: string[];
+    }): Promise<string>;
+    /**
+     * Specifies the set of commits covered in this release.
+     *
+     * @param {string} release Unique name of the release
+     * @param {SentryCliCommitsOptions} options A set of options to configure the commits to include
+     * @returns {Promise<string>} A promise that resolves when the commits have been associated
+     * @memberof SentryReleases
+     */
+    setCommits(release: string, options: SentryCliCommitsOptions): Promise<string>;
+    /**
+     * Marks this release as complete. This should be called once all artifacts has been
+     * uploaded.
+     *
+     * @param {string} release Unique name of the release.
+     * @returns {Promise<string>} A promise that resolves when the release has been finalized.
+     * @memberof SentryReleases
+     */
+    finalize(release: string): Promise<string>;
+    /**
+     * Creates a unique, deterministic version identifier based on the project type and
+     * source files. This identifier can be used as release name.
+     *
+     * @returns {Promise<string>} A promise that resolves to the version string.
+     * @memberof SentryReleases
+     */
+    proposeVersion(): Promise<string>;
+    /**
+     * Scans the given include folders for JavaScript source maps and uploads them to the
+     * specified release for processing.
+     *
+     * The options require an `include` array, which is a list of directories to scan.
+     * Additionally, it supports to ignore certain files, validate and preprocess source
+     * maps and define a URL prefix.
+     *
+     * @example
+     * await cli.releases.uploadSourceMaps(cli.releases.proposeVersion(), {
+     *   // required options:
+     *   include: ['build'],
+     *
+     *   // default options:
+     *   ignore: ['node_modules'],  // globs for files to ignore
+     *   ignoreFile: null,          // path to a file with ignore rules
+     *   rewrite: false,            // preprocess sourcemaps before uploading
+     *   sourceMapReference: true,  // add a source map reference to source files
+     *   dedupe: true,              // deduplicate already uploaded files
+     *   stripPrefix: [],           // remove certain prefixes from filenames
+     *   stripCommonPrefix: false,  // guess common prefixes to remove from filenames
+     *   validate: false,           // validate source maps and cancel the upload on error
+     *   urlPrefix: '',             // add a prefix source map urls after stripping them
+     *   urlSuffix: '',             // add a suffix source map urls after stripping them
+     *   ext: ['js', 'map', 'jsbundle', 'bundle'],  // override file extensions to scan for
+     *   projects: ['node'],        // provide a list of projects
+     *   decompress: false          // decompress gzip files before uploading
+     *   live: true                 // whether to inherit stdio to display `sentry-cli` output directly.
+     * });
+     *
+     * @param {string} release Unique name of the release.
+     * @param {SentryCliUploadSourceMapsOptions & {live?: boolean | 'rejectOnError'}} options Options to configure the source map upload.
+     * @returns {Promise<string[]>} A promise that resolves when the upload has completed successfully.
+     * @memberof SentryReleases
+     */
+    uploadSourceMaps(release: string, options: SentryCliUploadSourceMapsOptions & {
+        live?: boolean | "rejectOnError";
+    }): Promise<string[]>;
+    /**
+     * List all deploys for a given release.
+     *
+     * @param {string} release Unique name of the release.
+     * @returns {Promise<string>} A promise that resolves when the list comes back from the server.
+     * @memberof SentryReleases
+     */
+    listDeploys(release: string): Promise<string>;
+    /**
+     * Creates a new release deployment. This should be called after the release has been
+     * finalized, while deploying on a given environment.
+     *
+     * @example
+     * await cli.releases.newDeploy(cli.releases.proposeVersion(), {
+     *   // required options:
+     *   env: 'production',          // environment for this release. Values that make sense here would be 'production' or 'staging'
+     *
+     *   // optional options:
+     *   started: 42,                // unix timestamp when the deployment started
+     *   finished: 1337,             // unix timestamp when the deployment finished
+     *   time: 1295,                 // deployment duration in seconds. This can be specified alternatively to `started` and `finished`
+     *   name: 'PickleRick',         // human readable name for this deployment
+     *   url: 'https://example.com', // URL that points to the deployment
+     * });
+     *
+     * @param {string} release Unique name of the release.
+     * @param {SentryCliNewDeployOptions} options Options to configure the new release deploy.
+     * @returns {Promise<string>} A promise that resolves when the deploy has been created.
+     * @memberof SentryReleases
+     */
+    newDeploy(release: string, options: SentryCliNewDeployOptions): Promise<string>;
+    /**
+     * See {helper.execute} docs.
+     * @param {string[]} args Command line arguments passed to `sentry-cli`.
+     * @param {boolean | 'rejectOnError'} live can be set to:
+     *  - `true` to inherit stdio to display `sentry-cli` output directly.
+     *  - `false` to not inherit stdio and return the output as a string.
+     *  - `'rejectOnError'` to inherit stdio and reject the promise if the command
+     *    exits with a non-zero exit code.
+     * @returns {Promise<string>} A promise that resolves to the standard output.
+     */
+    execute(args: string[], live: boolean | "rejectOnError"): Promise<string>;
+}
+declare namespace Releases {
+    export { SentryCliUploadSourceMapsOptions, SourceMapsPathDescriptor, SentryCliNewDeployOptions, SentryCliCommitsOptions };
+}
+type SentryCliUploadSourceMapsOptions = import("../types").SentryCliUploadSourceMapsOptions;
+type SourceMapsPathDescriptor = import("../types").SourceMapsPathDescriptor;
+type SentryCliNewDeployOptions = import("../types").SentryCliNewDeployOptions;
+type SentryCliCommitsOptions = import("../types").SentryCliCommitsOptions;