1 | import { Dictionary, JsonMap, Nullable, Optional } from '@salesforce/ts-types';
|
2 | import { PackageDir, ProjectJson as ProjectJsonSchema, PackagePackageDir } from '@salesforce/schemas';
|
3 | import { ConfigFile } from './config/configFile';
|
4 | import { ConfigContents } from './config/configStackTypes';
|
5 | type NameAndFullPath = {
|
6 | /**
|
7 | * The [normalized](https://nodejs.org/api/path.html#path_path_normalize_path) path used as the package name.
|
8 | */
|
9 | name: string;
|
10 | /**
|
11 | * The absolute path of the package.
|
12 | */
|
13 | fullPath: string;
|
14 | };
|
15 | export type NamedPackagingDir = PackagePackageDir & NameAndFullPath;
|
16 | export type NamedPackageDir = PackageDir & NameAndFullPath;
|
17 | export type ProjectJson = ConfigContents & ProjectJsonSchema;
|
18 | /**
|
19 | * The sfdx-project.json config object. This file determines if a folder is a valid sfdx project.
|
20 | *
|
21 | * *Note:* Any non-standard (not owned by Salesforce) properties stored in sfdx-project.json should
|
22 | * be in a top level property that represents your project.
|
23 | * Plugins should store their configuration @see SfProject.getPluginConfiguration and @see SfProject.setPluginConfiguration
|
24 | *
|
25 | * @example reading a standard property
|
26 | * ```
|
27 | * const project = await SfProject.resolve();
|
28 | * const projectJson = await project.resolveProjectConfig();
|
29 | * const namespace = projectJson.get('namespace');
|
30 | * ```
|
31 | *
|
32 | * ```
|
33 | * @example writing
|
34 | * const project = await SfProject.resolve();
|
35 | * const projectJson = await project.resolveProjectConfig();
|
36 | * projectJson.set('namespace', 'new');
|
37 | * await projectJson.write();
|
38 | * ```
|
39 | *
|
40 | * **See** [force:project:create](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_create_new.htm)
|
41 | */
|
42 | export declare class SfProjectJson extends ConfigFile<ConfigFile.Options, ProjectJson> {
|
43 | /** json properties that are uppercase, or allow uppercase keys inside them */
|
44 | static BLOCKLIST: string[];
|
45 | static getFileName(): string;
|
46 | static getDefaultOptions(isGlobal?: boolean): ConfigFile.Options;
|
47 | read(): Promise<ProjectJson>;
|
48 | readSync(): ProjectJson;
|
49 | write(): Promise<ProjectJson>;
|
50 | writeSync(): ProjectJson;
|
51 | getDefaultOptions(options?: ConfigFile.Options): ConfigFile.Options;
|
52 | /**
|
53 | * Validates sfdx-project.json against the schema.
|
54 | *
|
55 | * Set the `SFDX_PROJECT_JSON_VALIDATION` environment variable to `true` to throw an error when schema validation fails.
|
56 | * A warning is logged by default when the file is invalid.
|
57 | *
|
58 | * ***See*** [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json)
|
59 | */
|
60 | schemaValidate(): Promise<void>;
|
61 | /**
|
62 | * Returns the `packageDirectories` within sfdx-project.json, first reading
|
63 | * and validating the file if necessary.
|
64 | */
|
65 | getPackageDirectories(): Promise<PackageDir[]>;
|
66 | /**
|
67 | * Validates sfdx-project.json against the schema.
|
68 | *
|
69 | * Set the `SFDX_PROJECT_JSON_VALIDATION` environment variable to `true` to throw an error when schema validation fails.
|
70 | * A warning is logged by default when the file is invalid.
|
71 | *
|
72 | * ***See*** [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json)
|
73 | */
|
74 | schemaValidateSync(): void;
|
75 | /**
|
76 | * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading
|
77 | * and validating the file if necessary. i.e. modifying this array will not affect the
|
78 | * sfdx-project.json file.
|
79 | */
|
80 | getPackageDirectoriesSync(): NamedPackageDir[];
|
81 | /**
|
82 | * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading
|
83 | * and validating the file if necessary. i.e. modifying this array will not affect the
|
84 | * sfdx-project.json file.
|
85 | *
|
86 | * There can be multiple packages in packageDirectories that point to the same directory.
|
87 | * This method only returns one packageDirectory entry per unique directory path. This is
|
88 | * useful when doing source operations based on directories but probably not as useful
|
89 | * for packaging operations that want to do something for each package entry.
|
90 | */
|
91 | getUniquePackageDirectories(): NamedPackageDir[];
|
92 | /**
|
93 | * Get a list of the unique package names from within sfdx-project.json. Use {@link SfProject.getUniquePackageDirectories}
|
94 | * for data other than the names.
|
95 | */
|
96 | getUniquePackageNames(): string[];
|
97 | /**
|
98 | * Has package directories defined in the project.
|
99 | */
|
100 | hasPackages(): boolean;
|
101 | /**
|
102 | * Has multiple package directories (MPD) defined in the project.
|
103 | */
|
104 | hasMultiplePackages(): boolean;
|
105 | /**
|
106 | * Has at least one package alias defined in the project.
|
107 | */
|
108 | hasPackageAliases(): Promise<boolean>;
|
109 | /**
|
110 | * Get package aliases defined in the project.
|
111 | */
|
112 | getPackageAliases(): Nullable<Dictionary<string>>;
|
113 | /**
|
114 | * Add a package alias to the project.
|
115 | * If the alias already exists, it will be overwritten.
|
116 | *
|
117 | * @param alias
|
118 | * @param id
|
119 | */
|
120 | addPackageAlias(alias: string, id: string): void;
|
121 | /**
|
122 | * Add a package directory to the project.
|
123 | * If the package directory already exists, the new directory
|
124 | * properties will be merged with the existing properties.
|
125 | *
|
126 | * @param packageDir
|
127 | */
|
128 | addPackageDirectory(packageDir: PackageDir): void;
|
129 | private doesPackageExist;
|
130 | private validateKeys;
|
131 | }
|
132 | /**
|
133 | * Represents an SFDX project directory. This directory contains a {@link SfProjectJson} config file as well as
|
134 | * a hidden .sfdx folder that contains all the other local project config files.
|
135 | *
|
136 | * ```
|
137 | * const project = await SfProject.resolve();
|
138 | * const projectJson = await project.resolveProjectConfig();
|
139 | * console.log(projectJson.sfdcLoginUrl);
|
140 | * ```
|
141 | */
|
142 | export declare class SfProject {
|
143 | private path;
|
144 | private static instances;
|
145 | private projectConfig;
|
146 | private sfProjectJson;
|
147 | private sfProjectJsonGlobal;
|
148 | private packageDirectories?;
|
149 | private activePackage;
|
150 | private packageAliases;
|
151 | /**
|
152 | * Do not directly construct instances of this class -- use {@link SfProject.resolve} instead.
|
153 | *
|
154 | * @ignore
|
155 | */
|
156 | protected constructor(path: string);
|
157 | /**
|
158 | * Get a Project from a given path or from the working directory.
|
159 | *
|
160 | * @param path The path of the project.
|
161 | *
|
162 | * **Throws** *{'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
SfError}{ name: |
163 | */
|
164 | static resolve(path?: string): Promise<SfProject>;
|
165 | /**
|
166 | * Get a Project from a given path or from the working directory.
|
167 | *
|
168 | * @param path The path of the project.
|
169 | *
|
170 | * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
|
171 | */
|
172 | static getInstance(path?: string): SfProject;
|
173 | /**
|
174 | * Performs an upward directory search for an sfdx project file. Returns the absolute path to the project.
|
175 | *
|
176 | * @param dir The directory path to start traversing from.
|
177 | *
|
178 | * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
|
179 | *
|
180 | * **See** {@link traverseForFile}
|
181 | *
|
182 | * **See** [process.cwd()](https://nodejs.org/api/process.html#process_process_cwd)
|
183 | */
|
184 | static resolveProjectPath(dir?: string): Promise<string>;
|
185 | /**
|
186 | * Performs a synchronous upward directory search for an sfdx project file. Returns the absolute path to the project.
|
187 | *
|
188 | * @param dir The directory path to start traversing from.
|
189 | *
|
190 | * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace.
|
191 | *
|
192 | * **See** {@link traverseForFileSync}
|
193 | *
|
194 | * **See** [process.cwd()](https://nodejs.org/api/process.html#process_process_cwd)
|
195 | */
|
196 | static resolveProjectPathSync(dir?: string): string;
|
197 | /** shared method for resolve and getInstance.
|
198 | * Cannot be a module-level function because instances is private */
|
199 | private static getMemoizedInstance;
|
200 | /**
|
201 | * Returns the project path.
|
202 | */
|
203 | getPath(): string;
|
204 | /**
|
205 | * Get the sfdx-project.json config. The global sfdx-project.json is used for user defaults
|
206 | * that are not checked in to the project specific file.
|
207 | *
|
208 | * *Note:* When reading values from {@link SfProjectJson}, it is recommended to use
|
209 | * {@link SfProject.resolveProjectConfig} instead.
|
210 | *
|
211 | * @param isGlobal True to get the global project file, otherwise the local project config.
|
212 | */
|
213 | retrieveSfProjectJson(isGlobal?: boolean): Promise<SfProjectJson>;
|
214 | /**
|
215 | * Get the sfdx-project.json config. The global sfdx-project.json is used for user defaults
|
216 | * that are not checked in to the project specific file.
|
217 | *
|
218 | * *Note:* When reading values from {@link SfProjectJson}, it is recommended to use
|
219 | * {@link SfProject.resolveProjectConfig} instead.
|
220 | *
|
221 | * This is the sync method of {@link SfProject.resolveSfProjectJson}
|
222 | *
|
223 | * @param isGlobal True to get the global project file, otherwise the local project config.
|
224 | */
|
225 | getSfProjectJson(isGlobal?: boolean): SfProjectJson;
|
226 | /**
|
227 | * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading
|
228 | * and validating the file if necessary. i.e. modifying this array will not affect the
|
229 | * sfdx-project.json file.
|
230 | */
|
231 | getPackageDirectories(): NamedPackageDir[];
|
232 | /**
|
233 | * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading
|
234 | * and validating the file if necessary. i.e. modifying this array will not affect the
|
235 | * sfdx-project.json file.
|
236 | *
|
237 | * There can be multiple packages in packageDirectories that point to the same directory.
|
238 | * This method only returns one packageDirectory entry per unique directory path. This is
|
239 | * useful when doing source operations based on directories but probably not as useful
|
240 | * for packaging operations that want to do something for each package entry.
|
241 | */
|
242 | getUniquePackageDirectories(): NamedPackageDir[];
|
243 | /**
|
244 | * Get a list of the unique package names from within sfdx-project.json. Use {@link SfProject.getUniquePackageDirectories}
|
245 | * for data other than the names.
|
246 | */
|
247 | getUniquePackageNames(): string[];
|
248 | /**
|
249 | * Returns the package from a file path.
|
250 | *
|
251 | * @param path A file path. E.g. /Users/jsmith/projects/ebikes-lwc/force-app/apex/my-cls.cls
|
252 | */
|
253 | getPackageFromPath(path: string): Optional<NamedPackageDir>;
|
254 | /**
|
255 | * Returns the package name, E.g. 'force-app', from a file path.
|
256 | *
|
257 | * @param path A file path. E.g. /Users/jsmith/projects/ebikes-lwc/force-app/apex/my-cls.cls
|
258 | */
|
259 | getPackageNameFromPath(path: string): Optional<string>;
|
260 | /**
|
261 | * Returns the package directory.
|
262 | *
|
263 | * @param packageName Name of the package directory. E.g., 'force-app'
|
264 | */
|
265 | getPackage(packageName: string): Optional<NamedPackageDir>;
|
266 | /**
|
267 | * Returns the package directory.
|
268 | *
|
269 | * @param packageName Name of the package directory. E.g., 'force-app'
|
270 | */
|
271 | findPackage(predicate: (packageDir: NamedPackageDir) => boolean): Optional<NamedPackageDir>;
|
272 | /**
|
273 | * Returns the absolute path of the package directory ending with the path separator.
|
274 | * E.g., /Users/jsmith/projects/ebikes-lwc/force-app/
|
275 | *
|
276 | * @param packageName Name of the package directory. E.g., 'force-app'
|
277 | */
|
278 | getPackagePath(packageName: string): Optional<string>;
|
279 | /**
|
280 | * Has package directories defined in the project.
|
281 | */
|
282 | hasPackages(): boolean;
|
283 | /**
|
284 | * Has multiple package directories (MPD) defined in the project.
|
285 | */
|
286 | hasMultiplePackages(): boolean;
|
287 | /**
|
288 | * Get the currently activated package on the project. This has no implication on sfdx-project.json
|
289 | * but is useful for keeping track of package and source specific options in a process.
|
290 | */
|
291 | getActivePackage(): Nullable<NamedPackageDir>;
|
292 | /**
|
293 | * Set the currently activated package on the project. This has no implication on sfdx-project.json
|
294 | * but is useful for keeping track of package and source specific options in a process.
|
295 | *
|
296 | * @param packageName The package name to activate. E.g. 'force-app'
|
297 | */
|
298 | setActivePackage(packageName: Nullable<string>): void;
|
299 | /**
|
300 | * Get the project's default package directory defined in sfdx-project.json using first 'default: true'
|
301 | * found. The first entry is returned if no default is specified.
|
302 | */
|
303 | getDefaultPackage(): NamedPackageDir;
|
304 | /**
|
305 | * The project config is resolved from local and global {@link SfProjectJson},
|
306 | * {@link ConfigAggregator}, and a set of defaults. It is recommended to use
|
307 | * this when reading values from SfProjectJson.
|
308 | *
|
309 | * The global {@link SfProjectJson} is used to allow the user to provide default values they
|
310 | * may not want checked into their project's source.
|
311 | *
|
312 | * @returns A resolved config object that contains a bunch of different
|
313 | * properties, including some 3rd party custom properties.
|
314 | */
|
315 | resolveProjectConfig(): Promise<JsonMap>;
|
316 | hasPackageAliases(): Promise<boolean>;
|
317 | /**
|
318 | * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading
|
319 | * and validating the file if necessary. i.e. modifying this array will not affect the
|
320 | * sfdx-project.json file.
|
321 | */
|
322 | getPackageAliases(): Nullable<Dictionary<string>>;
|
323 | getPackageIdFromAlias(alias: string): Optional<string>;
|
324 | getAliasesFromPackageId(id: string): string[];
|
325 | /**
|
326 | * retrieve the configuration for a named plugin from sfdx-project.json.plugins.pluginName
|
327 | *
|
328 | * @example
|
329 | * ```
|
330 | * const project = await SfProject.resolve();
|
331 | * const pluginConfig = await project.getPluginConfiguration('myPlugin');
|
332 | * ```
|
333 | *
|
334 | * optionally pass a type parameter for your plugin configuration's schema
|
335 | * */
|
336 | getPluginConfiguration<T extends Record<string, unknown>>(pluginName: string): Promise<Readonly<T>>;
|
337 | /**
|
338 | * set the configuration for a named plugin from sfdx-project.json.plugins.pluginName, overwriting existing configuration
|
339 | *
|
340 | * @example
|
341 | * ```
|
342 | * const project = await SfProject.resolve();
|
343 | * const pluginConfig = await project.setPluginConfiguration('myPlugin', {foo: 'bar', myLimit: 25});
|
344 | * ```
|
345 | *
|
346 | * optionally pass a type parameter for your plugin configuration's schema
|
347 | * */
|
348 | setPluginConfiguration<T extends Record<string, unknown>>(pluginName: string, config: T): Promise<void>;
|
349 | }
|
350 | /** 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 */
|
351 | export declare const isPackagingDirectory: (packageDir: PackageDir) => packageDir is PackagePackageDir;
|
352 | /** 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 */
|
353 | export declare const isNamedPackagingDirectory: (packageDir: NamedPackageDir) => packageDir is NamedPackagingDir;
|
354 | export {};
|