Merge branch 'sm/core-7-deprecations' into sm/no-mutate-params

.sfdevrc.json

@@ -8,6 +8,11 @@
       "files": ["src/**/*.ts", "tsconfig.json", "messages", "messageTransformer"],
       "output": ["lib/**", "*.tsbuildinfo"],
       "clean": "if-file-deleted"
+    },
+    "link-check": {
+      "command": "node -e \"process.exit(process.env.CI ? 0 : 1)\" || linkinator \"./*.md\" --skip \"examples/README.md|CHANGELOG.md|node_modules|test/|confluence.internal.salesforce.com|my.salesforce.com|%s\" --markdown --retry --directory-listing --verbosity error",
+      "files": ["./*.md", "./examples/**/*.md", "./messages/**/*.md", "./!(CHANGELOG).md"],
+      "output": []
     }
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core",
-  "version": "6.7.4",
+  "version": "6.7.6",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/index",
   "types": "lib/index.d.ts",
@@ -15,6 +15,7 @@
     "compile": "wireit",
     "docs": "sf-docs",
     "format": "wireit",
+    "link-check": "wireit",
     "lint": "wireit",
     "lint-fix": "yarn sf-lint --fix",
     "postcompile": "tsc -p typedocExamples",
@@ -39,9 +40,8 @@
   ],
   "dependencies": {
     "@salesforce/kit": "^3.1.0",
-    "@salesforce/schemas": "^1.6.1",
+    "@salesforce/schemas": "^1.7.0",
     "@salesforce/ts-types": "^2.0.9",
-    "@types/semver": "^7.5.8",
     "ajv": "^8.12.0",
     "change-case": "^4.1.2",
     "faye": "^1.4.0",
@@ -58,17 +58,18 @@
     "ts-retry-promise": "^0.7.1"
   },
   "devDependencies": {
-    "@salesforce/dev-scripts": "^7.1.1",
+    "@salesforce/dev-scripts": "^8.4.2",
     "@salesforce/ts-sinon": "^1.4.19",
     "@types/benchmark": "^2.1.5",
     "@types/chai-string": "^1.4.5",
     "@types/jsonwebtoken": "9.0.6",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/semver": "^7.5.8",
     "benchmark": "^2.1.4",
     "chai-string": "^1.5.0",
     "ts-node": "^10.9.2",
     "ts-patch": "^3.1.1",
-    "typescript": "^5.4.3"
+    "typescript": "^5.4.4"
   },
   "repository": {
     "type": "git",
@@ -146,8 +147,19 @@
     "test": {
       "dependencies": [
         "test:only",
-        "test:compile"
+        "test:compile",
+        "link-check"
       ]
+    },
+    "link-check": {
+      "command": "node -e \"process.exit(process.env.CI ? 0 : 1)\" || linkinator \"./*.md\" --skip \"examples/README.md|CHANGELOG.md|node_modules|test/|confluence.internal.salesforce.com|my.salesforce.com|%s\" --markdown --retry --directory-listing --verbosity error",
+      "files": [
+        "./*.md",
+        "./examples/**/*.md",
+        "./messages/**/*.md",
+        "./!(CHANGELOG).md"
+      ],
+      "output": []
     }
   }
 }

src/messageTransformer.ts

@@ -5,6 +5,7 @@
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
+// eslint-disable-next-line import/no-extraneous-dependencies
 import * as ts from 'typescript';
 import { Messages, StoredMessageMap } from './messages';
 

src/messages.ts

@@ -601,10 +601,10 @@ const resolvePackageName = (moduleMessagesDirPath: string): string => {
       ensureJsonMap(Messages.readFile(path.join(moduleMessagesDirPath, 'package.json'))).name
     );
     if (!resolvedPackageName) {
-      throw new SfError(errMessage, 'MissingPackageName');
+      throw SfError.create({ message: errMessage, name: 'MissingPackageName' });
     }
     return resolvedPackageName;
   } catch (err) {
-    throw new SfError('errMessage', 'MissingPackageName', undefined, err as Error);
+    throw SfError.create({ message: errMessage, name: 'MissingPackageName', cause: err });
   }
 };

src/org/authInfo.ts

@@ -761,8 +761,7 @@ export class AuthInfo extends AsyncOptionalCreatable<AuthInfo.Options> {
    * @param alias alias to set
    */
   public async setAlias(alias: string): Promise<void> {
-    this.stateAggregator.aliases.set(alias, this.getUsername());
-    await this.stateAggregator.aliases.write();
+    return this.stateAggregator.aliases.setAndSave(alias, this.getUsername());
   }
 
   /**

src/org/authRemover.ts

@@ -182,7 +182,9 @@ export class AuthRemover extends AsyncOptionalCreatable {
     if (existingAliases.length === 0) return;
 
     this.logger.debug(`Found these aliases to remove: ${existingAliases.join(',')}`);
-    existingAliases.forEach((alias) => this.stateAggregator.aliases.unset(alias));
-    await this.stateAggregator.aliases.write();
+    for (const alias of existingAliases) {
+      // eslint-disable-next-line no-await-in-loop
+      await this.stateAggregator.aliases.unsetAndSave(alias);
+    }
   }
 }

src/org/connection.ts

@@ -359,7 +359,7 @@ export class Connection<S extends Schema = Schema> extends JSForceConnection<S>
     const config: ConfigAggregator = await ConfigAggregator.create();
     // take the limit from the calling function, then the config, then default 10,000
     const maxFetch: number =
-      ((config.getInfo(OrgConfigProperties.ORG_MAX_QUERY_LIMIT).value as number) || queryOptions.maxFetch) ?? 10000;
+      ((config.getInfo(OrgConfigProperties.ORG_MAX_QUERY_LIMIT).value as number) || queryOptions.maxFetch) ?? 10_000;
 
     const { tooling, ...queryOptionsWithoutTooling } = queryOptions;
 

src/org/org.ts

@@ -607,7 +607,7 @@ export class Org extends AsyncOptionalCreatable<Org.Options> {
     await stateAgg.aliases.unsetValuesAndSave(existingAliases);
 
     // unset any configs referencing this org
-    [...existingAliases, username].flatMap((name) => this.configAggregator.unsetByValue(name));
+    await Promise.all([...existingAliases, username].flatMap((name) => this.configAggregator.unsetByValue(name)));
 
     if (await this.isSandbox()) {
       await this.deleteSandbox();

src/sfError.ts

@@ -12,7 +12,8 @@ export type SfErrorOptions<T extends ErrorDataProperties = ErrorDataProperties>
   exitCode?: number;
   name?: string;
   data?: T;
-  cause?: Error;
+  /** pass an Error.  For convenience in catch blocks, code will check that it is, in fact, an Error */
+  cause?: unknown;
   context?: string;
   actions?: string[];
 };
@@ -74,12 +75,14 @@ export class SfError<T extends ErrorDataProperties = ErrorDataProperties> extend
     name = 'SfError',
     actions?: string[],
     exitCodeOrCause?: number | Error,
-    cause?: Error
+    cause?: unknown
   ) {
-    const derivedCause = exitCodeOrCause instanceof Error ? exitCodeOrCause : cause;
+    if (typeof cause !== 'undefined' && !(cause instanceof Error)) {
+      throw new TypeError(`The cause, if provided, must be an instance of Error. Received: ${typeof cause}`);
+    }
     super(message);
     this.name = name;
-    this.cause = derivedCause;
+    this.cause = exitCodeOrCause instanceof Error ? exitCodeOrCause : cause;
     this.actions = actions;
     if (typeof exitCodeOrCause === 'number') {
       this.exitCode = exitCodeOrCause;
@@ -88,12 +91,7 @@ export class SfError<T extends ErrorDataProperties = ErrorDataProperties> extend
     }
   }
 
-  public get fullStack(): string | undefined {
-    return recursiveStack(this).join('\nCaused by: ');
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  public get code(): any {
+  public get code(): string {
     return this.#code ?? this.name;
   }
 
@@ -125,9 +123,15 @@ export class SfError<T extends ErrorDataProperties = ErrorDataProperties> extend
     const sfError =
       err instanceof Error
         ? // a basic error with message and name.  We make it the cause to preserve any other properties
-          new SfError<T>(err.message, err.name, undefined, err)
+          SfError.create<T>({
+            message: err.message,
+            name: err.name,
+            cause: err,
+          })
         : // ok, something was throws that wasn't error or string.  Convert it to an Error that preserves the information as the cause and wrap that.
-          SfError.wrap<T>(new TypeError('An unexpected error occurred', { cause: err }));
+          SfError.wrap<T>(
+            new Error(`SfError.wrap received type ${typeof err} but expects type Error or string`, { cause: err })
+          );
 
     // If the original error has a code, use that instead of name.
     if (hasString(err, 'code')) {
@@ -171,6 +175,3 @@ export class SfError<T extends ErrorDataProperties = ErrorDataProperties> extend
     };
   }
 }
-
-const recursiveStack = (err: Error): string[] =>
-  (err.cause && err.cause instanceof Error ? [err.stack, ...recursiveStack(err.cause)] : [err.stack]).filter(isString);

src/sfProject.ts

@@ -39,6 +39,10 @@ export type PackageDir = {
   dependencies?: PackageDirDependency[];
   includeProfileUserLicenses?: boolean;
   package?: string;
+  packageMetadataAccess?: {
+    permissionSets: string | string[];
+    permissionSetLicenses: string | string[];
+  };
   path: string;
   postInstallScript?: string;
   postInstallUrl?: string;

src/stateAggregator/accessors/aliasAccessor.ts

@@ -8,8 +8,7 @@
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { writeFileSync, readFileSync } from 'node:fs';
-import { lock, unlock, lockSync, unlockSync } from 'proper-lockfile';
+import { lock, unlock } from 'proper-lockfile';
 
 import { AsyncOptionalCreatable, ensureArray } from '@salesforce/kit';
 
@@ -18,7 +17,7 @@ import { Global } from '../../global';
 import { AuthFields } from '../../org/authInfo';
 import { ConfigContents } from '../../config/configStackTypes';
 import { SfError } from '../../sfError';
-import { lockRetryOptions, lockOptions } from '../../util/lockRetryOptions';
+import { lockRetryOptions } from '../../util/lockRetryOptions';
 
 export type Aliasable = string | Partial<AuthFields>;
 export const DEFAULT_GROUP = 'orgs';
@@ -109,20 +108,6 @@ export class AliasAccessor extends AsyncOptionalCreatable {
     return Array.from(this.aliasStore.entries()).find(([, value]) => value === usernameOrAlias)?.[0];
   }
 
-  /**
-   * Set an alias for the given aliasable entity.  Writes to the file
-   *
-   * @deprecated use setAndSave
-   * @param alias the alias you want to set
-   * @param entity the aliasable entity that's being aliased
-   */
-  public set(alias: string, entity: Aliasable): void {
-    // get a very fresh copy to merge with to avoid conflicts
-    this.readFileToAliasStoreSync();
-    this.aliasStore.set(alias, getNameOf(entity));
-    this.saveAliasStoreToFileSync();
-  }
-
   /**
    * Set an alias for the given aliasable entity.  Writes to the file
    *
@@ -136,18 +121,6 @@ export class AliasAccessor extends AsyncOptionalCreatable {
     return this.saveAliasStoreToFile();
   }
 
-  /**
-   * Unset the given alias.  Writes to the file
-   *
-   * @deprecated use unsetAndSave
-   *
-   */
-  public unset(alias: string): void {
-    this.readFileToAliasStoreSync();
-    this.aliasStore.delete(alias);
-    this.saveAliasStoreToFileSync();
-  }
-
   /**
    * Unset the given alias(es).  Writes to the file
    *
@@ -158,20 +131,6 @@ export class AliasAccessor extends AsyncOptionalCreatable {
     return this.saveAliasStoreToFile();
   }
 
-  /**
-   * Unsets all the aliases for the given entity.
-   *
-   * @deprecated use unsetValuesAndSave
-   *
-   * @param entity the aliasable entity for which you want to unset all aliases
-   */
-  public unsetAll(entity: Aliasable): void {
-    this.readFileToAliasStoreSync();
-    const aliases = this.getAll(entity);
-    aliases.forEach((a) => this.aliasStore.delete(a));
-    this.saveAliasStoreToFileSync();
-  }
-
   /**
    * Unset all the aliases for the given array of entity.
    *
@@ -185,13 +144,6 @@ export class AliasAccessor extends AsyncOptionalCreatable {
     return this.saveAliasStoreToFile();
   }
 
-  /**
-   * @deprecated the set/unset methods now write to the file when called.  Use (un)setAndSave instead of calling (un)set and then calling write()
-   */
-  public async write(): Promise<ConfigContents<string>> {
-    return Promise.resolve(this.getAll());
-  }
-
   /**
    * Returns true if the provided alias exists
    *
@@ -232,30 +184,6 @@ export class AliasAccessor extends AsyncOptionalCreatable {
     await writeFile(this.fileLocation, aliasStoreToRawFileContents(this.aliasStore));
     return unlockIfLocked(this.fileLocation);
   }
-
-  /**
-   * @deprecated use the async version of this method instead
-   * provided for the legacy sync set/unset methods. */
-  private readFileToAliasStoreSync(): void {
-    // the file is guaranteed to exist because this init method ensures it
-    // put a lock in place.  This method is only used by legacy set/unset methods.
-    lockSync(this.fileLocation, lockOptions);
-    this.aliasStore = fileContentsRawToAliasStore(readFileSync(this.fileLocation, 'utf-8'));
-  }
-
-  /**
-   * @deprecated use the async version of this method instead
-   * provided for the legacy sync set/unset methods */
-  private saveAliasStoreToFileSync(): void {
-    writeFileSync(this.fileLocation, aliasStoreToRawFileContents(this.aliasStore));
-    try {
-      unlockSync(this.fileLocation);
-    } catch (e) {
-      // ignore the error.  If it wasn't locked, that's what we wanted
-      if (errorIsNotAcquired(e)) return;
-      throw e;
-    }
-  }
 }
 
 /**