@salesforce/packaging 0.0.2 → 0.0.3

package/lib/utils/packageUtils.js

@@ -0,0 +1,786 @@
+"use strict";
+/*
+ * Copyright (c) 2022, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDate = exports.getSoqlWhereClauseMaxLength = exports.pollForStatusWithInterval = exports._getPackageVersionCreateRequestApi = exports.findOrCreatePackage2 = exports.getPackageAliasesFromId = exports.convertCamelCaseStringToSentence = exports.getPackageIdFromAlias = exports.getConfigPackageDirectory = exports.getConfigPackageDirectories = exports.getPackage2VersionNumber = exports.concatVersion = exports.getAncestorIdHighestRelease = exports.validateAncestorId = exports.getAncestorId = exports.getInClauseItemsCount = exports.queryWithInConditionChunking = exports.getPackageVersionStrings = exports.getHasMetadataRemoved = exports.getContainerOptions = exports.getSubscriberPackageVersionId = exports.getPackage2TypeBy04t = exports.getPackage2Type = exports.getPackageVersionId = exports.applyErrorAction = exports.massageErrorMessage = exports.isErrorPackageNotAvailable = exports.isErrorFromSPVQueryRestriction = exports.validUrl = exports.validatePatchVersion = exports.validateVersionNumber = exports.validateIdNoThrow = exports.validateId = exports.BY_LABEL = exports.BY_PREFIX = exports.DEFAULT_PACKAGE_DIR = exports.POLL_INTERVAL_SECONDS = exports.SOQL_WHERE_CLAUSE_MAX_LENGTH = exports.INSTALL_URL_BASE = exports.VERSION_NUMBER_SEP = void 0;
+const core_1 = require("@salesforce/core");
+const kit_1 = require("@salesforce/kit");
+const interfaces_1 = require("../interfaces");
+const packageVersionCreateRequestApi_1 = require("../package/packageVersionCreateRequestApi");
+const versionNumber_1 = require("./versionNumber");
+var Package2VersionStatus = interfaces_1.PackagingSObjects.Package2VersionStatus;
+core_1.Messages.importMessagesDirectory(__dirname);
+const messages = core_1.Messages.loadMessages('@salesforce/packaging', 'messages');
+exports.VERSION_NUMBER_SEP = '.';
+const INVALID_TYPE_REGEX = /[\w]*(sObject type '[A-Za-z]*Package[2]?[A-Za-z]*' is not supported)[\w]*/im;
+const ID_REGISTRY = [
+    {
+        prefix: '0Ho',
+        label: 'Package Id',
+    },
+    {
+        prefix: '05i',
+        label: 'Package Version Id',
+    },
+    {
+        prefix: '08c',
+        label: 'Package Version Create Request Id',
+    },
+    {
+        prefix: '04t',
+        label: 'Subscriber Package Version Id',
+    },
+];
+exports.INSTALL_URL_BASE = 'https://login.salesforce.com/packaging/installPackage.apexp?p0=';
+// https://developer.salesforce.com/docs/atlas.en-us.salesforce_app_limits_cheatsheet.meta/salesforce_app_limits_cheatsheet/salesforce_app_limits_platform_soslsoql.htm
+exports.SOQL_WHERE_CLAUSE_MAX_LENGTH = 4000;
+exports.POLL_INTERVAL_SECONDS = 30;
+exports.DEFAULT_PACKAGE_DIR = {
+    path: '',
+    package: '',
+    versionName: 'ver 0.1',
+    versionNumber: '0.1.0.NEXT',
+    default: true,
+};
+const logger = core_1.Logger.childFromRoot('packageUtils');
+exports.BY_PREFIX = (() => {
+    return Object.fromEntries(ID_REGISTRY.map((id) => [id.prefix, { prefix: id.prefix, label: id.label }]));
+})();
+exports.BY_LABEL = (() => {
+    return Object.fromEntries(ID_REGISTRY.map((id) => [id.label.replace(/ /g, '_').toUpperCase(), { prefix: id.prefix, label: id.label }]));
+})();
+function validateId(idObj, value) {
+    if (!validateIdNoThrow(idObj, value)) {
+        throw messages.createError('invalidIdOrAlias', [
+            Array.isArray(idObj) ? idObj.map((e) => e.label).join(' or ') : idObj.label,
+            value,
+            Array.isArray(idObj) ? idObj.map((e) => e.prefix).join(' or ') : idObj.prefix,
+        ]);
+    }
+}
+exports.validateId = validateId;
+function validateIdNoThrow(idObj, value) {
+    if (!value || (value.length !== 15 && value.length !== 18)) {
+        return false;
+    }
+    return Array.isArray(idObj) ? idObj.some((e) => value.startsWith(e.prefix)) : value.startsWith(idObj.prefix);
+}
+exports.validateIdNoThrow = validateIdNoThrow;
+function validateVersionNumber(versionNumberString, supportedBuildNumberToken, supportedBuildNumberToken2) {
+    const versionNumber = versionNumber_1.VersionNumber.from('1.1.0.NEXT');
+    // build number can be a number or valid token
+    if (Number.isNaN(parseInt(versionNumber.build, 10)) &&
+        versionNumber.build !== supportedBuildNumberToken &&
+        versionNumber.build !== supportedBuildNumberToken2) {
+        if (supportedBuildNumberToken2) {
+            throw messages.createError('errorInvalidBuildNumberForKeywords', [
+                versionNumberString,
+                supportedBuildNumberToken,
+                supportedBuildNumberToken2,
+            ]);
+        }
+        else {
+            throw messages.createError('errorInvalidBuildNumber', [versionNumberString, supportedBuildNumberToken]);
+        }
+    }
+    return versionNumberString;
+}
+exports.validateVersionNumber = validateVersionNumber;
+async function validatePatchVersion(connection, versionNumberString, packageId) {
+    const query = `SELECT ContainerOptions FROM Package2 WHERE id ='${packageId}'`;
+    const queryResult = await connection.tooling.query(query);
+    if (queryResult.records === null || queryResult.records.length === 0) {
+        throw messages.createError('errorInvalidPackageId', [packageId]);
+    }
+    // Enforce a patch version of zero (0) for Locked packages only
+    if (queryResult.records[0].ContainerOptions === 'Locked') {
+        const versionNumber = versionNumber_1.VersionNumber.from(versionNumberString);
+        if (versionNumber.patch !== '0') {
+            throw messages.createError('errorInvalidPatchNumber', [versionNumberString]);
+        }
+    }
+}
+exports.validatePatchVersion = validatePatchVersion;
+// TODO: let's get rid of this in favor of SfdcUrl.isValidUrl()
+// check that the provided url has a valid format
+function validUrl(url) {
+    return core_1.SfdcUrl.isValidUrl(url);
+}
+exports.validUrl = validUrl;
+// determines if error is from malformed SubscriberPackageVersion query
+// this is in place to allow cli to run against app version 214, where SPV queries
+// do not require installation key
+function isErrorFromSPVQueryRestriction(err) {
+    return (err.name === 'MALFORMED_QUERY' &&
+        err.message.includes('Implementation restriction: You can only perform queries of the form Id'));
+}
+exports.isErrorFromSPVQueryRestriction = isErrorFromSPVQueryRestriction;
+function isErrorPackageNotAvailable(err) {
+    return err.name === 'UNKNOWN_EXCEPTION' || err.name === 'PACKAGE_UNAVAILABLE';
+}
+exports.isErrorPackageNotAvailable = isErrorPackageNotAvailable;
+// overwrites error message under certain conditions
+function massageErrorMessage(err) {
+    if (err.name === 'INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST') {
+        err['message'] = messages.getMessage('invalidPackageTypeMessage');
+    }
+    if (err.name === 'MALFORMED_ID' &&
+        (err.message.includes('Version ID') || err.message.includes('Version Definition ID'))) {
+        err['message'] = messages.getMessage('malformedPackageVersionIdMessage');
+    }
+    if (err.name === 'MALFORMED_ID' && err.message.includes('Package2 ID')) {
+        err['message'] = messages.getMessage('malformedPackageIdMessage');
+    }
+    // remove references to Second Generation
+    if (err.message.includes('Second Generation ')) {
+        err['message'] = err.message.replace('Second Generation ', '');
+    }
+    return err;
+}
+exports.massageErrorMessage = massageErrorMessage;
+// applies actions to common package errors
+// eslint-disable-next-line complexity
+function applyErrorAction(err) {
+    // append when actions already exist
+    const actions = [];
+    // include existing actions
+    if (err['action']) {
+        actions.push(err['action']);
+    }
+    // TODO: (need to get with packaging team on this)
+    // until next generation packaging is GA, wrap perm-based errors w/
+    // 'contact sfdc' action (REMOVE once GA'd)
+    if ((err.name === 'INVALID_TYPE' && INVALID_TYPE_REGEX.test(err.message)) ||
+        (err.name === 'NOT_FOUND' && err.message === messages.getMessage('notFoundMessage'))) {
+        // contact sfdc customer service
+        actions.push(messages.getMessage('packageNotEnabledAction'));
+    }
+    if (err.name === 'INVALID_FIELD' && err.message.includes('Instance')) {
+        actions.push(messages.getMessage('packageInstanceNotEnabled'));
+    }
+    if (err.name === 'INVALID_FIELD' && err.message.includes('SourceOrg')) {
+        actions.push(messages.getMessage('packageSourceOrgNotEnabled'));
+    }
+    if (err.name === 'INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST') {
+        actions.push(messages.getMessage('invalidPackageTypeAction'));
+    }
+    if (err.name === 'MALFORMED_ID' && err.message === messages.getMessage('malformedPackageIdMessage')) {
+        actions.push(messages.getMessage('malformedPackageIdAction'));
+    }
+    if (err.name === 'MALFORMED_ID' && err.message === messages.getMessage('malformedPackageVersionIdMessage')) {
+        actions.push(messages.getMessage('malformedPackageVersionIdAction'));
+    }
+    if ((err.message.includes(exports.BY_LABEL.SUBSCRIBER_PACKAGE_VERSION_ID.label) && err.message.includes('is invalid')) ||
+        err.name === 'INVALID_ID_FIELD' ||
+        (err.name === 'INVALID_INPUT' && err.message.includes('Verify you entered the correct ID')) ||
+        err.name === 'MALFORMED_ID') {
+        actions.push(messages.getMessage('idNotFoundAction'));
+    }
+    if (actions.length > 0) {
+        err['action'] = actions.join('\n');
+    }
+    return err;
+}
+exports.applyErrorAction = applyErrorAction;
+/**
+ * Given a subscriber package version ID (04t) or package version ID (05i), return the package version ID (05i)
+ *
+ * @param versionId The subscriber package version ID
+ * @param connection For tooling query
+ */
+async function getPackageVersionId(versionId, connection) {
+    // if it's already a 05i return it, otherwise query for it
+    if (versionId === null || versionId === void 0 ? void 0 : versionId.startsWith(exports.BY_LABEL.PACKAGE_VERSION_ID.prefix)) {
+        return versionId;
+    }
+    const query = `SELECT Id FROM Package2Version WHERE SubscriberPackageVersionId = '${versionId}'`;
+    return connection.tooling.query(query).then((queryResult) => {
+        if (!queryResult || !queryResult.totalSize) {
+            throw messages.createError('errorInvalidIdNoMatchingVersionId', [
+                exports.BY_LABEL.SUBSCRIBER_PACKAGE_VERSION_ID.label,
+                versionId,
+                exports.BY_LABEL.PACKAGE_VERSION_ID.label,
+            ]);
+        }
+        return queryResult.records[0].Id;
+    });
+}
+exports.getPackageVersionId = getPackageVersionId;
+/**
+ * Given 0Ho the package type type (Managed, Unlocked, Locked(deprecated?))
+ *
+ * @param package2Id the 0Ho
+ * @param connection For tooling query
+ * @throws Error with message when package2 cannot be found
+ */
+async function getPackage2Type(package2Id, connection) {
+    const query = `SELECT ContainerOptions FROM Package2 WHERE id ='${package2Id}'`;
+    const queryResult = await connection.tooling.query(query);
+    if (!queryResult || queryResult.records === null || queryResult.records.length === 0) {
+        throw messages.createError('errorInvalidPackageId', [package2Id]);
+    }
+    return queryResult.records[0].ContainerOptions;
+}
+exports.getPackage2Type = getPackage2Type;
+/**
+ * Given 04t the package type type (Managed, Unlocked, Locked(deprecated?))
+ *
+ * @param package2VersionId the 04t
+ * @param connection For tooling query
+ * @param installKey For tooling query, if an installation key is applicable to the package version it must be passed in the queries
+ * @throws Error with message when package2 cannot be found
+ */
+async function getPackage2TypeBy04t(package2VersionId, connection, installKey) {
+    let query = `SELECT Package2ContainerOptions FROM SubscriberPackageVersion WHERE id ='${package2VersionId}'`;
+    if (installKey) {
+        const escapedInstallationKey = installKey.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+        query += ` AND InstallationKey ='${escapedInstallationKey}'`;
+    }
+    const queryResult = await connection.tooling.query(query);
+    if (!queryResult || queryResult.records === null || queryResult.records.length === 0) {
+        throw messages.createError('errorInvalidPackageId', [package2VersionId]);
+    }
+    return queryResult.records[0].Package2ContainerOptions;
+}
+exports.getPackage2TypeBy04t = getPackage2TypeBy04t;
+/**
+ * Given a package version ID (05i) or subscriber package version ID (04t), return the subscriber package version ID (04t)
+ *
+ * @param versionId The suscriber package version ID
+ * @param connection For tooling query
+ */
+async function getSubscriberPackageVersionId(versionId, connection) {
+    // if it's already a 04t return it, otherwise query for it
+    if (!versionId || versionId.startsWith(exports.BY_LABEL.SUBSCRIBER_PACKAGE_VERSION_ID.prefix)) {
+        return versionId;
+    }
+    const query = `SELECT SubscriberPackageVersionId FROM Package2Version WHERE Id = '${versionId}'`;
+    const queryResult = await connection.tooling.query(query);
+    if (!queryResult || !queryResult.totalSize) {
+        throw messages.createError('errorInvalidIdNoMatchingVersionId', [
+            exports.BY_LABEL.PACKAGE_VERSION_ID.label,
+            versionId,
+            exports.BY_LABEL.SUBSCRIBER_PACKAGE_VERSION_ID.label,
+        ]);
+    }
+    return queryResult.records[0].SubscriberPackageVersionId;
+}
+exports.getSubscriberPackageVersionId = getSubscriberPackageVersionId;
+/**
+ * Get the ContainerOptions for the specified Package2 (0Ho) IDs.
+ *
+ * @return Map of 0Ho id to container option api value
+ * @param package2Ids The list of package IDs
+ * @param connection For tooling query
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+async function getContainerOptions(package2Ids, connection) {
+    if (!package2Ids || package2Ids.length === 0) {
+        return new Map();
+    }
+    const query = 'SELECT Id, ContainerOptions FROM Package2 WHERE Id IN (%IDS%)';
+    const records = await queryWithInConditionChunking(query, package2Ids, '%IDS%', connection);
+    if (records && records.length > 0) {
+        return new Map(records.map((record) => [record.Id, record.ContainerOptions]));
+    }
+    return new Map();
+}
+exports.getContainerOptions = getContainerOptions;
+/**
+ * Return the Package2Version.HasMetadataRemoved field value for the given Id (05i)
+ *
+ * @param packageVersionId package version ID (05i)
+ * @param connection For tooling query
+ */
+async function getHasMetadataRemoved(packageVersionId, connection) {
+    const query = `SELECT HasMetadataRemoved FROM Package2Version WHERE Id = '${packageVersionId}'`;
+    const queryResult = await connection.tooling.query(query);
+    if (!queryResult || queryResult.records === null || queryResult.records.length === 0) {
+        throw messages.createError('errorInvalidIdNoMatchingVersionId', [
+            exports.BY_LABEL.PACKAGE_VERSION_ID.label,
+            packageVersionId,
+            exports.BY_LABEL.PACKAGE_VERSION_ID.label,
+        ]);
+    }
+    return queryResult.records[0].HasMetadataRemoved;
+}
+exports.getHasMetadataRemoved = getHasMetadataRemoved;
+/**
+ * Given a list of subscriber package version IDs (04t), return the associated version strings (e.g., Major.Minor.Patch.Build)
+ *
+ * @return Map of subscriberPackageVersionId to versionString
+ * @param subscriberPackageVersionIds
+ * @param connection For tooling query
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+async function getPackageVersionStrings(subscriberPackageVersionIds, connection) {
+    let results = new Map();
+    if (!subscriberPackageVersionIds || subscriberPackageVersionIds.length === 0) {
+        return results;
+    }
+    // remove any duplicate Ids
+    const ids = [...new Set(subscriberPackageVersionIds)];
+    const query = 'SELECT SubscriberPackageVersionId, MajorVersion, MinorVersion, PatchVersion, BuildNumber FROM Package2Version WHERE SubscriberPackageVersionId IN (%IDS%)';
+    const records = await queryWithInConditionChunking(query, ids, '%IDS%', connection);
+    if (records && records.length > 0) {
+        results = new Map(records.map((record) => {
+            const version = concatVersion(record.MajorVersion, record.MinorVersion, record.PatchVersion, record.BuildNumber);
+            return [record.SubscriberPackageVersionId, version];
+        }));
+    }
+    return results;
+}
+exports.getPackageVersionStrings = getPackageVersionStrings;
+/**
+ * For queries with an IN condition, determine if the WHERE clause will exceed
+ * SOQL's 4000 character limit.  Perform multiple queries as needed to stay below the limit.
+ *
+ * @return concatenated array of records returned from the resulting query(ies)
+ * @param query The full query to execute containing the replaceToken param in its IN clause
+ * @param items The IN clause items.  A length-appropriate single-quoted comma-separated string chunk will be made from the items.
+ * @param replaceToken A placeholder in the query's IN condition that will be replaced with the chunked items
+ * @param connection For tooling query
+ */
+async function queryWithInConditionChunking(query, items, replaceToken, connection) {
+    let records = [];
+    if (!query || !items || !replaceToken) {
+        return records;
+    }
+    const whereClause = query.substring(query.toLowerCase().indexOf('where'), query.length);
+    const inClauseItemsMaxLength = exports.SOQL_WHERE_CLAUSE_MAX_LENGTH - whereClause.length - replaceToken.length;
+    let itemsQueried = 0;
+    while (itemsQueried < items.length) {
+        const chunkCount = getInClauseItemsCount(items, itemsQueried, inClauseItemsMaxLength);
+        if (chunkCount === 0) {
+            throw messages.createError('itemDoesNotFitWithinMaxLength', [
+                query,
+                items[itemsQueried].slice(0, 20),
+                items[itemsQueried].length,
+                inClauseItemsMaxLength,
+            ]);
+        }
+        const itemsStr = `${items.slice(itemsQueried, itemsQueried + chunkCount).join("','")}`;
+        const queryChunk = query.replace(replaceToken, itemsStr);
+        const result = await connection.tooling.query(queryChunk);
+        if (result && result.records.length > 0) {
+            records = records.concat(result.records);
+        }
+        itemsQueried += chunkCount;
+    }
+    return records;
+}
+exports.queryWithInConditionChunking = queryWithInConditionChunking;
+/**
+ *   Returns the number of items that can be included in a quoted comma-separated string (e.g., "'item1','item2'") not exceeding maxLength
+ */
+// TODO: this function cannot handle a single item that is longer than maxLength - what to do, since this could be the root cause of an infinite loop?
+function getInClauseItemsCount(items, startIndex, maxLength) {
+    let resultLength = 0;
+    let includedCount = 0;
+    while (startIndex + includedCount < items.length) {
+        let itemLength = 0;
+        if (items[startIndex + includedCount]) {
+            itemLength = items[startIndex + includedCount].length + 3; // 3 = length of "'',"
+            if (resultLength + itemLength > maxLength) {
+                // the limit has been exceeded, return the current count
+                return includedCount;
+            }
+            includedCount++;
+            resultLength += itemLength;
+        }
+    }
+    return includedCount;
+}
+exports.getInClauseItemsCount = getInClauseItemsCount;
+/**
+ * Given a package descriptor, return the ancestor ID. This code was duplicated to scratchOrgInfoGenerator.getAncestorIds,
+ * changes here may need to be duplicated there until that code, and/or this code is moved to a separate plugin.
+ *
+ * @param packageDescriptorJson JSON for packageDirectories element in sfdx-project.json
+ * @param connection For tooling query
+ * @param project The project to use for looking up the ancestor ID
+ * @param versionNumberString The version number string to use for looking up the ancestor ID
+ * @param skipAncestorCheck If true, skip the check for the ancestor ID
+ */
+async function getAncestorId(packageDescriptorJson, connection, project, versionNumberString, skipAncestorCheck) {
+    // eslint-disable-next-line complexity
+    return Promise.resolve().then(async () => {
+        var _a;
+        // If an id property is present, use it.  Otherwise, look up the package id from the package property.
+        const packageId = (_a = packageDescriptorJson['id']) !== null && _a !== void 0 ? _a : getPackageIdFromAlias(packageDescriptorJson.package, project);
+        // No need to proceed if Unlocked
+        const packageType = await getPackage2Type(packageId, connection);
+        if (packageType === 'Unlocked') {
+            return '';
+        }
+        let ancestorId = '';
+        // ancestorID can be alias, 05i, or 04t;
+        // validate and convert to 05i, as needed
+        const versionNumber = versionNumberString.split(exports.VERSION_NUMBER_SEP);
+        const isPatch = versionNumber[2] !== '0';
+        let origSpecifiedAncestor = packageDescriptorJson.ancestorId;
+        let highestReleasedVersion = null;
+        const explicitUseHighestRelease = packageDescriptorJson.ancestorId === versionNumber_1.BuildNumberToken.HIGHEST_VERSION_NUMBER_TOKEN ||
+            packageDescriptorJson.ancestorVersion === versionNumber_1.BuildNumberToken.HIGHEST_VERSION_NUMBER_TOKEN;
+        const explicitUseNoAncestor = packageDescriptorJson.ancestorId === versionNumber_1.BuildNumberToken.NONE_VERSION_NUMBER_TOKEN ||
+            packageDescriptorJson.ancestorVersion === versionNumber_1.BuildNumberToken.NONE_VERSION_NUMBER_TOKEN;
+        if ((explicitUseHighestRelease || explicitUseNoAncestor) &&
+            packageDescriptorJson.ancestorId &&
+            packageDescriptorJson.ancestorVersion) {
+            if (packageDescriptorJson.ancestorId !== packageDescriptorJson.ancestorVersion) {
+                // both ancestorId and ancestorVersion specified, HIGHEST and/or NONE are used, the values disagree
+                throw messages.createError('errorAncestorIdVersionHighestOrNoneMismatch', [
+                    packageDescriptorJson.ancestorId,
+                    packageDescriptorJson.ancestorVersion,
+                ]);
+            }
+        }
+        if (explicitUseNoAncestor && skipAncestorCheck) {
+            return '';
+        }
+        else {
+            const result = await getAncestorIdHighestRelease(connection, packageId, versionNumberString, explicitUseHighestRelease, skipAncestorCheck);
+            if (result.finalAncestorId) {
+                return result.finalAncestorId;
+            }
+            highestReleasedVersion = result.highestReleasedVersion;
+        }
+        // at this point if explicitUseHighestRelease=true, we have returned the ancestorId or thrown an error
+        // highestReleasedVersion should be null only if skipAncestorCheck or if there is no existing released package version
+        if (!explicitUseNoAncestor && packageDescriptorJson.ancestorId) {
+            ancestorId = getPackageIdFromAlias(packageDescriptorJson.ancestorId, project);
+            validateId([exports.BY_LABEL.SUBSCRIBER_PACKAGE_VERSION_ID, exports.BY_LABEL.PACKAGE_VERSION_ID], ancestorId);
+            ancestorId = await getPackageVersionId(ancestorId, connection);
+        }
+        if (!explicitUseNoAncestor && packageDescriptorJson.ancestorVersion) {
+            const regNumbers = new RegExp('^[0-9]+$');
+            const versionNumber = packageDescriptorJson.ancestorVersion.split(exports.VERSION_NUMBER_SEP);
+            if (versionNumber.length < 3 ||
+                versionNumber.length > 4 ||
+                !versionNumber[0].match(regNumbers) ||
+                !versionNumber[1].match(regNumbers) ||
+                !versionNumber[2].match(regNumbers)) {
+                throw messages.createError('errorInvalidAncestorVersionFormat', [packageDescriptorJson.ancestorVersion]);
+            }
+            const query = 'SELECT Id, IsReleased FROM Package2Version ' +
+                `WHERE Package2Id = '${packageId}' AND MajorVersion = ${versionNumber[0]} AND MinorVersion = ${versionNumber[1]} AND PatchVersion = ${versionNumber[2]}`;
+            let queriedAncestorId;
+            const ancestorVersionResult = await connection.tooling.query(query);
+            if (!ancestorVersionResult || !ancestorVersionResult.totalSize) {
+                throw messages.createError('errorNoMatchingAncestor', [packageDescriptorJson.ancestorVersion, packageId]);
+            }
+            else {
+                const releasedAncestor = ancestorVersionResult.records.find((rec) => rec.IsReleased === true);
+                if (!releasedAncestor) {
+                    throw messages.createError('errorAncestorNotReleased', [packageDescriptorJson.ancestorVersion]);
+                }
+                else {
+                    queriedAncestorId = releasedAncestor.Id;
+                }
+            }
+            // check for discrepancy between queried ancestorId and descriptor's ancestorId
+            if (Object.prototype.hasOwnProperty.call(packageDescriptorJson, 'ancestorId') &&
+                ancestorId !== queriedAncestorId) {
+                throw messages.createError('errorAncestorIdVersionMismatch', [
+                    packageDescriptorJson.ancestorVersion,
+                    packageDescriptorJson.ancestorId,
+                ]);
+            }
+            ancestorId = queriedAncestorId;
+            origSpecifiedAncestor = packageDescriptorJson.ancestorVersion;
+        }
+        return validateAncestorId(ancestorId, highestReleasedVersion, explicitUseNoAncestor, isPatch, skipAncestorCheck, origSpecifiedAncestor);
+    });
+}
+exports.getAncestorId = getAncestorId;
+function validateAncestorId(ancestorId, highestReleasedVersion, explicitUseNoAncestor, isPatch, skipAncestorCheck, origSpecifiedAncestor) {
+    if (explicitUseNoAncestor) {
+        if (!highestReleasedVersion) {
+            return '';
+        }
+        else {
+            // the explicitUseNoAncestor && skipAncestorCheck case is handled above
+            throw messages.createError('errorAncestorNoneNotAllowed', [getPackage2VersionNumber(highestReleasedVersion)]);
+        }
+    }
+    if (!isPatch && !skipAncestorCheck) {
+        if (highestReleasedVersion) {
+            if (highestReleasedVersion.Id !== ancestorId) {
+                throw messages.createError('errorAncestorNotHighest', [
+                    origSpecifiedAncestor,
+                    getPackage2VersionNumber(highestReleasedVersion),
+                ]);
+            }
+        }
+        else {
+            // looks like the initial version:create - allow
+            ancestorId = '';
+        }
+    }
+    return ancestorId;
+}
+exports.validateAncestorId = validateAncestorId;
+async function getAncestorIdHighestRelease(connection, packageId, versionNumberString, explicitUseHighestRelease, skipAncestorCheck) {
+    const versionNumber = versionNumberString.split(exports.VERSION_NUMBER_SEP);
+    const isPatch = versionNumber[2] !== '0';
+    const result = { finalAncestorId: null, highestReleasedVersion: null };
+    if (isPatch && explicitUseHighestRelease) {
+        // based on server-side validation, whatever ancestor is specified for a patch is
+        // tightly controlled; therefore we only need concern ourselves if explicitUseHighestRelease == true;
+        // equally applies when skipAncestorCheck == true
+        // gather appropriate matching major.minor.0
+        const query = `SELECT Id FROM Package2Version WHERE Package2Id = '${packageId}' ` +
+            'AND IsReleased = True AND IsDeprecated = False AND PatchVersion = 0 ' +
+            `AND MajorVersion = ${versionNumber[0]} AND MinorVersion = ${versionNumber[1]} ` +
+            'ORDER BY MajorVersion Desc, MinorVersion Desc, PatchVersion Desc, BuildNumber Desc LIMIT 1';
+        const majorMinorVersionResult = await connection.tooling.query(query);
+        const majorMinorVersionRecords = majorMinorVersionResult.records;
+        if (majorMinorVersionRecords && (majorMinorVersionRecords === null || majorMinorVersionRecords === void 0 ? void 0 : majorMinorVersionRecords.length) === 1 && majorMinorVersionRecords[0]) {
+            result.finalAncestorId = majorMinorVersionRecords[0].Id;
+        }
+        else {
+            const majorMinorNotFound = `${versionNumber[0]}.${versionNumber[1]}.0`;
+            throw messages.createError('errorNoMatchingMajorMinorForPatch', [majorMinorNotFound]);
+        }
+    }
+    else if (!isPatch && (explicitUseHighestRelease || !skipAncestorCheck)) {
+        // ancestor must be set to latest released major.minor version
+        const query = 'SELECT Id, SubscriberPackageVersionId, MajorVersion, MinorVersion, PatchVersion FROM Package2Version ' +
+            `WHERE Package2Id = '${packageId}' AND IsReleased = True AND IsDeprecated = False AND PatchVersion = 0 ` +
+            'ORDER BY MajorVersion Desc, MinorVersion Desc, PatchVersion Desc, BuildNumber Desc LIMIT 1';
+        const highestVersionResult = await connection.tooling.query(query);
+        const highestVersionRecords = highestVersionResult.records;
+        if (highestVersionRecords && highestVersionRecords[0]) {
+            result.highestReleasedVersion = highestVersionRecords[0];
+            if (explicitUseHighestRelease) {
+                result.finalAncestorId = result.highestReleasedVersion.Id;
+            }
+        }
+        else if (explicitUseHighestRelease) {
+            // there is no eligible ancestor version
+            throw new Error(messages.getMessage('errorNoMatchingAncestor', [versionNumberString, packageId]));
+        }
+    }
+    return result;
+}
+exports.getAncestorIdHighestRelease = getAncestorIdHighestRelease;
+/**
+ * Return a version string in Major.Minor.Patch.Build format, using 0 for any empty part
+ */
+function concatVersion(major, minor, patch, build) {
+    return [major, minor, patch, build].map((part) => (part ? `${part}` : '0')).join('.');
+}
+exports.concatVersion = concatVersion;
+function getPackage2VersionNumber(package2VersionObj) {
+    const version = concatVersion(package2VersionObj.MajorVersion, package2VersionObj.MinorVersion, package2VersionObj.PatchVersion, undefined);
+    return version.slice(0, version.lastIndexOf('.'));
+}
+exports.getPackage2VersionNumber = getPackage2VersionNumber;
+// TODO: get rid of this function if possible.
+function getConfigPackageDirectories(project) {
+    return project.getPackageDirectories();
+}
+exports.getConfigPackageDirectories = getConfigPackageDirectories;
+function getConfigPackageDirectory(packageDirs, lookupProperty, lookupValue) {
+    return packageDirs === null || packageDirs === void 0 ? void 0 : packageDirs.find((pkgDir) => pkgDir[lookupProperty] === lookupValue);
+}
+exports.getConfigPackageDirectory = getConfigPackageDirectory;
+/**
+ * Given a packageAlias, attempt to return the associated id from the config
+ *
+ * @param packageAlias string representing a package alias
+ * @param project for obtaining the project config
+ * @returns the associated id or the arg given.
+ */
+function getPackageIdFromAlias(packageAlias, project) {
+    const packageAliases = project.getSfProjectJson().getContents().packageAliases || {};
+    // return alias if it exists, otherwise return what was passed in
+    return packageAliases[packageAlias] || packageAlias;
+}
+exports.getPackageIdFromAlias = getPackageIdFromAlias;
+/**
+ * @param stringIn pascal or camel case string
+ * @returns space delimited and lower-cased (except for 1st char) string (e.g. in "AbcdEfghIj" => "Abcd efgh ij")
+ */
+function convertCamelCaseStringToSentence(stringIn) {
+    return (0, kit_1.camelCaseToTitleCase)(stringIn);
+}
+exports.convertCamelCaseStringToSentence = convertCamelCaseStringToSentence;
+/**
+ * Given a package id, attempt to return the associated aliases from the config
+ *
+ * @param packageId string representing a package id
+ * @param project for obtaining the project config
+ * @returns an array of alias for the given id.
+ */
+function getPackageAliasesFromId(packageId, project) {
+    const packageAliases = project.getSfProjectJson().getContents().packageAliases || {};
+    // check for a matching alias
+    return Object.entries(packageAliases)
+        .filter((alias) => alias[1] === packageId)
+        .map((alias) => alias[0]);
+}
+exports.getPackageAliasesFromId = getPackageAliasesFromId;
+async function findOrCreatePackage2(seedPackage, connection) {
+    const query = `SELECT Id FROM Package2 WHERE ConvertedFromPackageId = '${seedPackage}'`;
+    const queryResult = await connection.tooling.query(query);
+    const records = queryResult.records;
+    if (records && records.length > 1) {
+        const ids = records.map((r) => r.Id);
+        throw new Error(messages.getMessage('errorMoreThanOnePackage2WithSeed', [ids.join(', ')]));
+    }
+    if (records && records.length === 1) {
+        // return the package2 object
+        return records[0].Id;
+    }
+    // Need to create a new Package2
+    const subQuery = `SELECT Name, Description, NamespacePrefix FROM SubscriberPackage WHERE Id = '${seedPackage}'`;
+    const subscriberResult = await connection.tooling.query(subQuery);
+    const subscriberRecords = subscriberResult.records;
+    if (!subscriberRecords || subscriberRecords.length <= 0) {
+        throw new Error(messages.getMessage('errorNoSubscriberPackageRecord', [seedPackage]));
+    }
+    const request = {
+        Name: subscriberRecords[0].Name,
+        Description: subscriberRecords[0].Description,
+        NamespacePrefix: subscriberRecords[0].NamespacePrefix,
+        ContainerOptions: 'Managed',
+        ConvertedFromPackageId: seedPackage,
+    };
+    const createResult = await connection.tooling.create('Package2', request);
+    if (!createResult.success) {
+        throw new Error(createResult.errors.map((e) => e.message).join('\n'));
+    }
+    return createResult.id;
+}
+exports.findOrCreatePackage2 = findOrCreatePackage2;
+function _getPackageVersionCreateRequestApi(connection) {
+    return new packageVersionCreateRequestApi_1.PackageVersionCreateRequestApi({ connection });
+}
+exports._getPackageVersionCreateRequestApi = _getPackageVersionCreateRequestApi;
+async function pollForStatusWithInterval(context, id, retries, packageId, branch, withProject, connection, interval) {
+    let remainingRetries = retries;
+    const pollingClient = await core_1.PollingClient.create({
+        poll: async () => {
+            var _a;
+            const pvcrApi = new packageVersionCreateRequestApi_1.PackageVersionCreateRequestApi({ connection });
+            const results = await pvcrApi.byId(id);
+            if (_isStatusEqualTo(results, [Package2VersionStatus.success, Package2VersionStatus.error])) {
+                // complete
+                if (_isStatusEqualTo(results, [Package2VersionStatus.success])) {
+                    // update sfdx-project.json
+                    let projectUpdated = false;
+                    if (withProject && !process.env.SFDX_PROJECT_AUTOUPDATE_DISABLE_FOR_PACKAGE_VERSION_CREATE) {
+                        projectUpdated = true;
+                        const query = `SELECT MajorVersion, MinorVersion, PatchVersion, BuildNumber FROM Package2Version WHERE Id = '${results[0].Package2VersionId}'`;
+                        const package2VersionVersionString = await connection.tooling
+                            .query(query)
+                            .then((pkgQueryResult) => {
+                            const record = pkgQueryResult.records[0];
+                            return `${record.MajorVersion}.${record.MinorVersion}.${record.PatchVersion}-${record.BuildNumber}`;
+                        });
+                        const newConfig = await _generatePackageAliasEntry(connection, withProject, results[0].SubscriberPackageVersionId, package2VersionVersionString, branch, packageId);
+                        withProject.getSfProjectJson().set('packageAliases', newConfig);
+                        await withProject.getSfProjectJson().write();
+                    }
+                    core_1.Lifecycle.getInstance().emit(Package2VersionStatus.success, {
+                        id,
+                        package2VersionCreateRequestResult: results[0],
+                        projectUpdated,
+                    });
+                    return { completed: true, payload: results[0] };
+                }
+                else {
+                    let status = 'Unknown Error';
+                    if ((results === null || results === void 0 ? void 0 : results.length) > 0 && results[0].Error.length > 0) {
+                        const errors = [];
+                        // for multiple errors, display one per line prefixed with (x)
+                        if (results[0].Error.length > 1) {
+                            results[0].Error.forEach((error) => {
+                                errors.push(`(${errors.length + 1}) ${error}`);
+                            });
+                            errors.unshift(messages.getMessage('versionCreateFailedWithMultipleErrors'));
+                        }
+                        status = errors.length !== 0 ? errors.join('\n') : results[0].Error.join('\n');
+                    }
+                    core_1.Lifecycle.getInstance().emit(Package2VersionStatus.error, { id, status });
+                    throw new core_1.SfError(status);
+                }
+            }
+            else {
+                const remainingTime = kit_1.Duration.milliseconds(interval.milliseconds * remainingRetries);
+                core_1.Lifecycle.getInstance().emit(Package2VersionStatus.inProgress, {
+                    id,
+                    package2VersionCreateRequestResult: results[0],
+                    message: '',
+                    remainingTime,
+                });
+                logger.info(`Request in progress. Sleeping ${interval} seconds. Will wait a total of ${remainingTime.seconds} more seconds before timing out. Current Status='${convertCamelCaseStringToSentence((_a = results[0]) === null || _a === void 0 ? void 0 : _a.Status)}'`);
+                remainingRetries--;
+                return { completed: false, payload: results[0] };
+            }
+        },
+        frequency: kit_1.Duration.milliseconds(interval.milliseconds * 1000),
+        timeout: kit_1.Duration.milliseconds(interval.milliseconds * retries * 1000),
+    });
+    return pollingClient.subscribe();
+}
+exports.pollForStatusWithInterval = pollForStatusWithInterval;
+/**
+ * Generate package alias json entry for this package version that can be written to sfdx-project.json
+ *
+ * @param connection
+ * @param project SfProject instance for the project
+ * @param packageVersionId 04t id of the package to create the alias entry for
+ * @param packageVersionNumber that will be appended to the package name to form the alias
+ * @param branch
+ * @param packageId the 0Ho id
+ * @private
+ */
+async function _generatePackageAliasEntry(connection, project, packageVersionId, packageVersionNumber, branch, packageId) {
+    const configContent = project.getSfProjectJson().getContents();
+    const packageAliases = configContent.packageAliases || {};
+    const aliasForPackageId = getPackageAliasesFromId(packageId, project);
+    let packageName;
+    if (!aliasForPackageId || aliasForPackageId.length === 0) {
+        const query = `SELECT Name FROM Package2 WHERE Id = '${packageId}'`;
+        packageName = await connection.tooling
+            .query(query)
+            .then((pkgQueryResult) => { var _a; return (_a = pkgQueryResult.records[0]) === null || _a === void 0 ? void 0 : _a.Name; });
+    }
+    else {
+        packageName = aliasForPackageId[0];
+    }
+    const packageAlias = branch
+        ? `${packageName}@${packageVersionNumber}-${branch}`
+        : `${packageName}@${packageVersionNumber}`;
+    packageAliases[packageAlias] = packageVersionId;
+    return { packageAliases };
+}
+/**
+ * Return true if the queryResult.records[0].Status is equal to one of the values in statuses.
+ *
+ * @param results to examine
+ * @param statuses array of statuses to look for
+ * @returns {boolean} if one of the values in status is found.
+ */
+function _isStatusEqualTo(results, statuses) {
+    return (results === null || results === void 0 ? void 0 : results.length) <= 0 ? false : statuses === null || statuses === void 0 ? void 0 : statuses.some((status) => results[0].Status === status);
+}
+// added for unit testing
+function getSoqlWhereClauseMaxLength() {
+    return exports.SOQL_WHERE_CLAUSE_MAX_LENGTH;
+}
+exports.getSoqlWhereClauseMaxLength = getSoqlWhereClauseMaxLength;
+function formatDate(date) {
+    const pad = (num) => {
+        return num < 10 ? `0${num}` : num;
+    };
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+exports.formatDate = formatDate;
+//# sourceMappingURL=packageUtils.js.map