azure-pipelines-tool-lib/tool.d.ts

Azure Pipelines Tool Installer Lib for CI/CD Tasks

import * as ifm from 'typed-rest-client/Interfaces';
export declare function debug(message: string): void;
export declare function prependPath(toolPath: string): void;
/**
 * Checks if a version spec is an explicit version (e.g. 1.0.1 or v1.0.1)
 * As opposed to a version spec like 1.x
 *
 * @param versionSpec
 */
export declare function isExplicitVersion(versionSpec: string): boolean;
/**
 * Returns cleaned (removed leading/trailing whitespace, remove '=v' prefix)
 * and parsed version, or null if version is invalid.
 */
export declare function cleanVersion(version: string): string;
/**
 * evaluates a list of versions and returns the latest version matching the version spec
 *
 * @param versions      an array of versions to evaluate
 * @param versionSpec   a version spec (e.g. 1.x)
 */
export declare function evaluateVersions(versions: string[], versionSpec: string): string;
/**
 * finds the path to a tool in the local installed tool cache
 *
 * @param toolName      name of the tool
 * @param versionSpec   version of the tool
 * @param arch          optional arch.  defaults to arch of computer
 */
export declare function findLocalTool(toolName: string, versionSpec: string, arch?: string): string;
/**
 * Retrieves the versions of a tool that is intalled in the local tool cache
 *
 * @param toolName  name of the tool
 * @param arch      optional arch.  defaults to arch of computer
 */
export declare function findLocalToolVersions(toolName: string, arch?: string): string[];
/**
 * Download a tool from an url and stream it into a file
 *
 * @param url                url of tool to download
 * @param fileName           optional fileName.  Should typically not use (will be a guid for reliability). Can pass fileName with an absolute path.
 * @param handlers           optional handlers array.  Auth handlers to pass to the HttpClient for the tool download.
 * @param additionalHeaders  optional custom HTTP headers.  This is passed to the REST client that downloads the tool.
 */
export declare function downloadTool(url: string, fileName?: string, handlers?: ifm.IRequestHandler[], additionalHeaders?: ifm.IHeaders): Promise<string>;
export declare function downloadToolWithRetries(url: string, fileName?: string, handlers?: ifm.IRequestHandler[], additionalHeaders?: ifm.IHeaders, maxAttempts?: number, retryInterval?: number): Promise<string>;
/**
 * Caches a directory and installs it into the tool cacheDir
 *
 * @param sourceDir    the directory to cache into tools
 * @param tool          tool name
 * @param version       version of the tool.  semver format
 * @param arch          architecture of the tool.  Optional.  Defaults to machine architecture
 */
export declare function cacheDir(sourceDir: string, tool: string, version: string, arch?: string): Promise<string>;
/**
 * Caches a downloaded file (GUID) and installs it
 * into the tool cache with a given targetName
 *
 * @param sourceFile    the file to cache into tools.  Typically a result of downloadTool which is a guid.
 * @param targetFile    the name of the file name in the tools directory
 * @param tool          tool name
 * @param version       version of the tool.  semver format
 * @param arch          architecture of the tool.  Optional.  Defaults to machine architecture
 */
export declare function cacheFile(sourceFile: string, targetFile: string, tool: string, version: string, arch?: string): Promise<string>;
/**
 * Extract a .7z file
 *
 * @param file     path to the .7z file
 * @param dest     destination directory. Optional.
 * @param _7zPath  path to 7zr.exe. Optional, for long path support. Most .7z archives do not have this
 * problem. If your .7z archive contains very long paths, you can pass the path to 7zr.exe which will
 * gracefully handle long paths. By default 7z.exe is used because it is a very small program and is
 * bundled with the tool lib. However it does not support long paths. 7z.exe is the reduced command line
 * interface, it is smaller than the full command line interface, and it does support long paths. At the
 * time of this writing, it is freely available from the LZMA SDK that is available on the 7zip website.
 * Be sure to check the current license agreement. If 7z.exe is bundled with your task, then the path
 * to 7z.exe can be pass to this function.
 * @param overwriteDest Overwrite files in destination catalog. Optional.
 * @returns        path to the destination directory
 */
export declare function extract7z(file: string, dest?: string, _7zPath?: string, overwriteDest?: boolean): Promise<string>;
/**
 * installs a tool from a tar by extracting the tar and installing it into the tool cache
 *
 * @param file      file path of the tar
 * @param tool      name of tool in the tool cache
 * @param version   version of the tool
 * @param arch      arch of the tool.  optional.  defaults to the arch of the machine
 * @param options   IExtractOptions
 * @param destination   destination directory. optional.
 */
export declare function extractTar(file: string, destination?: string): Promise<string>;
export declare function extractZip(file: string, destination?: string): Promise<string>;
/**
 * Scrape a web page for versions by regex
 *
 * @param url       url to scrape
 * @param regex     regex to use for version matches
 * @param handlers  optional handlers array.  Auth handlers to pass to the HttpClient for the tool download.
 */
export declare function scrape(url: string, regex: RegExp, handlers?: ifm.IRequestHandler[]): Promise<string[]>;