@salesforce/core/lib/sfProject.d.ts

Core libraries to interact with SFDX projects, orgs, and APIs.

import { JsonMap, Nullable, Optional } from '@salesforce/ts-types';
import { ConfigFile } from './config/configFile';
import { ConfigContents } from './config/configStore';
export declare type PackageDirDependency = {
    [k: string]: unknown;
    package: string;
    versionNumber?: string;
};
export declare type PackageDir = {
    ancestorId?: string;
    ancestorVersion?: string;
    default?: boolean;
    definitionFile?: string;
    dependencies?: PackageDirDependency[];
    includeProfileUserLicenses?: boolean;
    package?: string;
    path: string;
    postInstallScript?: string;
    postInstallUrl?: string;
    releaseNotesUrl?: string;
    uninstallScript?: string;
    versionDescription?: string;
    versionName?: string;
    versionNumber?: string;
};
export declare type NamedPackageDir = PackageDir & {
    /**
     * The [normalized](https://nodejs.org/api/path.html#path_path_normalize_path) path used as the package name.
     */
    name: string;
    /**
     * The absolute path of the package.
     */
    fullPath: string;
};
export declare type ProjectJson = ConfigContents & {
    packageDirectories: PackageDir[];
    namespace?: string;
    sourceApiVersion?: string;
    sfdcLoginUrl?: string;
    signupTargetLoginUrl?: string;
    oauthLocalPort?: number;
    plugins?: {
        [k: string]: unknown;
    };
    packageAliases?: {
        [k: string]: string;
    };
};
/**
 * The sfdx-project.json config object. This file determines if a folder is a valid sfdx project.
 *
 * *Note:* Any non-standard (not owned by Salesforce) properties stored in sfdx-project.json should
 * be in a top level property that represents your project or plugin.
 *
 * ```
 * const project = await SfProject.resolve();
 * const projectJson = await project.resolveProjectConfig();
 * const myPluginProperties = projectJson.get('myplugin') || {};
 * myPluginProperties.myprop = 'someValue';
 * projectJson.set('myplugin', myPluginProperties);
 * await projectJson.write();
 * ```
 *
 * **See** [force:project:create](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_create_new.htm)
 */
export declare class SfProjectJson extends ConfigFile {
    static BLOCKLIST: string[];
    static getFileName(): string;
    static getDefaultOptions(isGlobal?: boolean): ConfigFile.Options;
    read(): Promise<ConfigContents>;
    readSync(): ConfigContents;
    write(newContents?: ConfigContents): Promise<ConfigContents>;
    writeSync(newContents?: ConfigContents): ConfigContents;
    getContents(): ProjectJson;
    getDefaultOptions(options?: ConfigFile.Options): ConfigFile.Options;
    /**
     * Validates sfdx-project.json against the schema.
     *
     * Set the `SFDX_PROJECT_JSON_VALIDATION` environment variable to `true` to throw an error when schema validation fails.
     * A warning is logged by default when the file is invalid.
     *
     * ***See*** [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json)
     */
    schemaValidate(): Promise<void>;
    /**
     * Returns the `packageDirectories` within sfdx-project.json, first reading
     * and validating the file if necessary.
     */
    getPackageDirectories(): Promise<PackageDir[]>;
    /**
     * Validates sfdx-project.json against the schema.
     *
     * Set the `SFDX_PROJECT_JSON_VALIDATION` environment variable to `true` to throw an error when schema validation fails.
     * A warning is logged by default when the file is invalid.
     *
     * ***See*** [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json)
     */
    schemaValidateSync(): void;
    /**
     * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading
     * and validating the file if necessary. i.e. modifying this array will not affect the
     * sfdx-project.json file.
     */
    getPackageDirectoriesSync(): NamedPackageDir[];
    /**
     * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading
     * and validating the file if necessary. i.e. modifying this array will not affect the
     * sfdx-project.json file.
     *
     * There can be multiple packages in packageDirectories that point to the same directory.
     * This method only returns one packageDirectory entry per unique directory path. This is
     * useful when doing source operations based on directories but probably not as useful
     * for packaging operations that want to do something for each package entry.
     */
    getUniquePackageDirectories(): NamedPackageDir[];
    /**
     * Get a list of the unique package names from within sfdx-project.json. Use {@link SfProject.getUniquePackageDirectories}
     * for data other than the names.
     */
    getUniquePackageNames(): string[];
    /**
     * Has package directories defined in the project.
     */
    hasPackages(): boolean;
    /**
     * Has multiple package directories (MPD) defined in the project.
     */
    hasMultiplePackages(): boolean;
    private doesPackageExist;
    private validateKeys;
}
/**
 * Represents an SFDX project directory. This directory contains a {@link SfProjectJson} config file as well as
 * a hidden .sfdx folder that contains all the other local project config files.
 *
 * ```
 * const project = await SfProject.resolve();
 * const projectJson = await project.resolveProjectConfig();
 * console.log(projectJson.sfdcLoginUrl);
 * ```
 */
export declare class SfProject {
    private path;
    private static instances;
    private projectConfig;
    private sfProjectJson;
    private sfProjectJsonGlobal;
    private packageDirectories?;
    private activePackage;
    /**
     * Do not directly construct instances of this class -- use {@link SfProject.resolve} instead.
     *
     * @ignore
     */
    protected constructor(path: string);
    /**
     * Get a Project from a given path or from the working directory.
     *
     * @param path The path of the project.
     *
     * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
     */
    static resolve(path?: string): Promise<SfProject>;
    /**
     * Get a Project from a given path or from the working directory.
     *
     * @param path The path of the project.
     *
     * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
     */
    static getInstance(path?: string): SfProject;
    /**
     * Performs an upward directory search for an sfdx project file. Returns the absolute path to the project.
     *
     * @param dir The directory path to start traversing from.
     *
     * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
     *
     * **See** {@link traverseForFile}
     *
     * **See** [process.cwd()](https://nodejs.org/api/process.html#process_process_cwd)
     */
    static resolveProjectPath(dir?: string): Promise<string>;
    /**
     * Performs a synchronous upward directory search for an sfdx project file. Returns the absolute path to the project.
     *
     * @param dir The directory path to start traversing from.
     *
     * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
     *
     * **See** {@link traverseForFileSync}
     *
     * **See** [process.cwd()](https://nodejs.org/api/process.html#process_process_cwd)
     */
    static resolveProjectPathSync(dir?: string): string;
    /**
     * Returns the project path.
     */
    getPath(): string;
    /**
     * Get the sfdx-project.json config. The global sfdx-project.json is used for user defaults
     * that are not checked in to the project specific file.
     *
     * *Note:* When reading values from {@link SfProjectJson}, it is recommended to use
     * {@link SfProject.resolveProjectConfig} instead.
     *
     * @param isGlobal True to get the global project file, otherwise the local project config.
     */
    retrieveSfProjectJson(isGlobal?: boolean): Promise<SfProjectJson>;
    /**
     * Get the sfdx-project.json config. The global sfdx-project.json is used for user defaults
     * that are not checked in to the project specific file.
     *
     * *Note:* When reading values from {@link SfProjectJson}, it is recommended to use
     * {@link SfProject.resolveProjectConfig} instead.
     *
     * This is the sync method of {@link SfProject.resolveSfProjectJson}
     *
     * @param isGlobal True to get the global project file, otherwise the local project config.
     */
    getSfProjectJson(isGlobal?: boolean): SfProjectJson;
    /**
     * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading
     * and validating the file if necessary. i.e. modifying this array will not affect the
     * sfdx-project.json file.
     */
    getPackageDirectories(): NamedPackageDir[];
    /**
     * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading
     * and validating the file if necessary. i.e. modifying this array will not affect the
     * sfdx-project.json file.
     *
     * There can be multiple packages in packageDirectories that point to the same directory.
     * This method only returns one packageDirectory entry per unique directory path. This is
     * useful when doing source operations based on directories but probably not as useful
     * for packaging operations that want to do something for each package entry.
     */
    getUniquePackageDirectories(): NamedPackageDir[];
    /**
     * Get a list of the unique package names from within sfdx-project.json. Use {@link SfProject.getUniquePackageDirectories}
     * for data other than the names.
     */
    getUniquePackageNames(): string[];
    /**
     * Returns the package from a file path.
     *
     * @param path A file path. E.g. /Users/jsmith/projects/ebikes-lwc/force-app/apex/my-cls.cls
     */
    getPackageFromPath(path: string): Optional<NamedPackageDir>;
    /**
     * Returns the package name, E.g. 'force-app', from a file path.
     *
     * @param path A file path. E.g. /Users/jsmith/projects/ebikes-lwc/force-app/apex/my-cls.cls
     */
    getPackageNameFromPath(path: string): Optional<string>;
    /**
     * Returns the package directory.
     *
     * @param packageName Name of the package directory.  E.g., 'force-app'
     */
    getPackage(packageName: string): Optional<NamedPackageDir>;
    /**
     * Returns the absolute path of the package directory ending with the path separator.
     * E.g., /Users/jsmith/projects/ebikes-lwc/force-app/
     *
     * @param packageName Name of the package directory.  E.g., 'force-app'
     */
    getPackagePath(packageName: string): Optional<string>;
    /**
     * Has package directories defined in the project.
     */
    hasPackages(): boolean;
    /**
     * Has multiple package directories (MPD) defined in the project.
     */
    hasMultiplePackages(): boolean;
    /**
     * Get the currently activated package on the project. This has no implication on sfdx-project.json
     * but is useful for keeping track of package and source specific options in a process.
     */
    getActivePackage(): Nullable<NamedPackageDir>;
    /**
     * Set the currently activated package on the project. This has no implication on sfdx-project.json
     * but is useful for keeping track of package and source specific options in a process.
     *
     * @param pkgName The package name to activate. E.g. 'force-app'
     */
    setActivePackage(packageName: Nullable<string>): void;
    /**
     * Get the project's default package directory defined in sfdx-project.json using first 'default: true'
     * found. The first entry is returned if no default is specified.
     */
    getDefaultPackage(): NamedPackageDir;
    /**
     * The project config is resolved from local and global {@link SfProjectJson},
     * {@link ConfigAggregator}, and a set of defaults. It is recommended to use
     * this when reading values from SfProjectJson.
     *
     * The global {@link SfProjectJson} is used to allow the user to provide default values they
     * may not want checked into their project's source.
     *
     * @returns A resolved config object that contains a bunch of different
     * properties, including some 3rd party custom properties.
     */
    resolveProjectConfig(): Promise<JsonMap>;
}
/**
 * @deprecated use SfProject instead
 */
export declare class SfdxProject extends SfProject {
}
/**
 * @deprecated use SfProjectJson instead
 */
export declare class SfdxProjectJson extends SfProjectJson {
}