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

import { Dictionary, JsonMap, Nullable, Optional } from '@salesforce/ts-types';
import { PackageDir, ProjectJson as ProjectJsonSchema, PackagePackageDir } from '@salesforce/schemas';
import { ConfigFile } from './config/configFile';
import { ConfigContents } from './config/configStackTypes';
type NameAndFullPath = {
    /**
     * 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 type NamedPackagingDir = PackagePackageDir & NameAndFullPath;
export type NamedPackageDir = PackageDir & NameAndFullPath;
export type ProjectJson = ConfigContents & ProjectJsonSchema;
/**
 * 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.
 * Plugins should store their configuration @see SfProject.getPluginConfiguration and @see SfProject.setPluginConfiguration
 *
 * @example reading a standard property
 * ```
 * const project = await SfProject.resolve();
 * const projectJson = await project.resolveProjectConfig();
 * const namespace = projectJson.get('namespace');
 * ```
 *
 * ```
 * @example writing
 * const project = await SfProject.resolve();
 * const projectJson = await project.resolveProjectConfig();
 * projectJson.set('namespace', 'new');
 * 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<ConfigFile.Options, ProjectJson> {
    /** json properties that are uppercase, or allow uppercase keys inside them */
    static BLOCKLIST: string[];
    static getFileName(): string;
    static getDefaultOptions(isGlobal?: boolean): ConfigFile.Options;
    read(): Promise<ProjectJson>;
    /** force a reread of the project contents if you know they may have been modified */
    refreshSync(): SfProjectJson;
    readSync(): ProjectJson;
    write(): Promise<ProjectJson>;
    writeSync(): 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;
    /**
     * Has at least one package alias defined in the project.
     */
    hasPackageAliases(): Promise<boolean>;
    /**
     * Get package aliases defined in the project.
     */
    getPackageAliases(): Nullable<Dictionary<string>>;
    /**
     * Add a package alias to the project.
     * If the alias already exists, it will be overwritten.
     *
     * @param alias
     * @param id
     */
    addPackageAlias(alias: string, id: string): void;
    /**
     * Add a package directory to the project.
     * If the package directory already exists, the new directory
     * properties will be merged with the existing properties.
     *
     * @param packageDir
     */
    addPackageDirectory(packageDir: PackageDir): void;
    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;
    private packageAliases;
    /**
     * Do not directly construct instances of this class -- use {@link SfProject.resolve} instead.
     *
     * @ignore
     */
    protected constructor(path: string);
    /**
     * Clear the cache to force reading from disk.
     *
     * *NOTE: Only call this method if you must and you know what you are doing.*
     */
    static clearInstances(): void;
    /**
     * 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;
    /** shared method for resolve and getInstance.
     * Cannot be a module-level function because instances is private */
    private static getMemoizedInstance;
    /**
     * 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 package directory.
     *
     * @param packageName Name of the package directory.  E.g., 'force-app'
     */
    findPackage(predicate: (packageDir: NamedPackageDir) => boolean): 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 packageName 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>;
    hasPackageAliases(): Promise<boolean>;
    /**
     * 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.
     */
    getPackageAliases(): Nullable<Dictionary<string>>;
    getPackageIdFromAlias(alias: string): Optional<string>;
    getAliasesFromPackageId(id: string): string[];
    /**
     * retrieve the configuration for a named plugin from sfdx-project.json.plugins.pluginName
     *
     * @example
     * ```
     * const project = await SfProject.resolve();
     * const pluginConfig = await project.getPluginConfiguration('myPlugin');
     * ```
     *
     * optionally pass a type parameter for your plugin configuration's schema
     * */
    getPluginConfiguration<T extends Record<string, unknown>>(pluginName: string): Promise<Readonly<T>>;
    /**
     * set the configuration for a named plugin from sfdx-project.json.plugins.pluginName, overwriting existing configuration
     *
     * @example
     * ```
     * const project = await SfProject.resolve();
     * const pluginConfig = await project.setPluginConfiguration('myPlugin', {foo: 'bar', myLimit: 25});
     * ```
     *
     * optionally pass a type parameter for your plugin configuration's schema
     * */
    setPluginConfiguration<T extends Record<string, unknown>>(pluginName: string, config: T): Promise<void>;
}
/** differentiate between the Base PackageDir (path, maybe default) and the Packaging version (package and maybe a LOT of other fields) by whether is has the `package` property */
export declare const isPackagingDirectory: (packageDir: PackageDir) => packageDir is PackagePackageDir;
/** differentiate between the Base PackageDir (path, maybe default) and the Packaging version (package and maybe a LOT of other fields) by whether is has the `package` property */
export declare const isNamedPackagingDirectory: (packageDir: NamedPackageDir) => packageDir is NamedPackagingDir;
export {};