fix: support new package version retrieve error messages (@W-23089623@)

Author: ravipanguluri

messages/package.md

@@ -38,6 +38,14 @@ Can't retrieve package version metadata. The specified directory must be relativ
 
 Can't retrieve package metadata. To use this feature, you must first assign yourself the DownloadPackageVersionZips user permission. Then retry retrieving your package metadata.
 
+# packageVersionNotFound
+
+Can't retrieve package metadata. We can't find the package version %s. Verify that the 04t ID is correct and that the package version exists.
+
+# packageVersionNotInDevHub
+
+Can't retrieve package metadata. Package version %s isn't accessible from this Dev Hub org. You can only retrieve package metadata from the Dev Hub that created the package version. Verify that you specified the correct target Dev Hub.
+
 # downloadDeveloperPackageZipHasNoDataNative2GP
 
 Can't retrieve package metadata. The developer package zip for this native 2GP package version is unretrievable. To resolve, create a new package version with the --generate-pkg-zip flag. Then retry retrieving your package metadata.

src/package/packageVersionRetrieve.ts

@@ -23,7 +23,7 @@ import { PackageVersionMetadataDownloadOptions, PackageVersionMetadataDownloadRe
 import { generatePackageAliasEntry, isPackageDirectoryEffectivelyEmpty } from '../utils/packageUtils';
 import { createPackageDirEntry } from './packageCreate';
 import { Package } from './package';
-import { PackageVersion } from './packageVersion';
+import { PackageVersion, Package2VersionFieldTypes } from './packageVersion';
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/packaging', 'package');
@@ -60,31 +60,52 @@ export async function retrievePackageVersionMetadata(
   const subscriberPackageVersionId =
     project.getPackageIdFromAlias(options.subscriberPackageVersionId) ?? options.subscriberPackageVersionId;
 
-  // Query Package2Version to get the record by SubscriberPackageVersionId
+  // Query Package2Version to confirm the row exists in the running user's Dev Hub. We select
+  // only the minimal columns this flow actually reads (Package2Id for the project.json update,
+  // ConvertedFromVersionId for the "no data" message variant). We deliberately do NOT select
+  // DeveloperUsePkgZip here: it is gated by the DownloadPackageVersionZips user permission and
+  // is invisible to SOQL for users without it, so selecting it would throw "No such column" at
+  // parse time before we could distinguish "not found" from "wrong Dev Hub" from "missing
+  // permission". The download URL is fetched separately, only when we're about to download
+  // (see getDeveloperUsePkgZipUrl below). This mirrors the strip already done in getData().
   const queryOptions = {
     whereClause: `WHERE SubscriberPackageVersionId = '${subscriberPackageVersionId}'`,
+    fields: ['Package2Id', 'ConvertedFromVersionId'] as Package2VersionFieldTypes,
   };
   let versionInfo;
   try {
     [versionInfo] = await PackageVersion.queryPackage2Version(connection, queryOptions);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    if (msg.includes("No such column 'DeveloperUsePkgZip' on entity 'Package2Version'")) {
-      throw messages.createError('developerUsePkgZipFieldUnavailable');
-    }
     if (msg.includes("sObject type 'Package2Version' is not supported.")) {
       throw messages.createError('packagingNotEnabledOnOrg');
     }
     throw e;
   }
 
-  if (!versionInfo?.DeveloperUsePkgZip) {
+  // No Package2Version row visible for this 04t in the running user's Dev Hub.
+  // Distinguish "doesn't exist anywhere" from "exists but not in this Dev Hub"
+  // using SubscriberPackageVersion, which any authenticated user can query by ID.
+  if (!versionInfo) {
+    const exists = await subscriberPackageVersionExists(connection, subscriberPackageVersionId);
+    throw messages.createError(exists ? 'packageVersionNotInDevHub' : 'packageVersionNotFound', [
+      subscriberPackageVersionId,
+    ]);
+  }
+
+  // The row exists. Now fetch the FLS-gated download URL on its own. If the user lacks the
+  // DownloadPackageVersionZips permission (or the field isn't available on this API version),
+  // this returns nothing and we surface the actionable "assign the permission" message.
+  const developerUsePkgZipUrl = await getDeveloperUsePkgZipUrl(connection, subscriberPackageVersionId);
+  if (!developerUsePkgZipUrl) {
     throw messages.createError('developerUsePkgZipFieldUnavailable');
   }
 
-  const responseBase64 = await connection.tooling.request<string>(versionInfo.DeveloperUsePkgZip, {
-    encoding: 'base64',
-  });
+  const responseBase64 = await downloadDeveloperPackageZip(
+    connection,
+    developerUsePkgZipUrl,
+    subscriberPackageVersionId
+  );
   const buffer = Buffer.from(responseBase64, 'base64');
 
   let tree;
@@ -232,3 +253,78 @@ async function attemptToUpdateProjectJson(
     );
   }
 }
+
+/**
+ * Download the developer package zip from the DeveloperUsePkgZip URL, mapping late-stage
+ * access failures to actionable errors. The download servlet performs its own independent
+ * access check, so a valid-looking URL can still be rejected at fetch time.
+ */
+async function downloadDeveloperPackageZip(
+  connection: Connection,
+  developerUsePkgZipUrl: string,
+  subscriberPackageVersionId: string
+): Promise<string> {
+  try {
+    return await connection.tooling.request<string>(developerUsePkgZipUrl, { encoding: 'base64' });
+  } catch (e) {
+    const name = e instanceof Error ? e.name : '';
+    if (name === 'NOT_FOUND') {
+      throw messages.createError('packageVersionNotFound', [subscriberPackageVersionId]);
+    }
+    if (name === 'INSUFFICIENT_ACCESS' || name === 'INSUFFICIENT_ACCESS_OR_READONLY') {
+      throw messages.createError('packageVersionNotInDevHub', [subscriberPackageVersionId]);
+    }
+    throw e;
+  }
+}
+
+/**
+ * Fetch the FLS-gated DeveloperUsePkgZip download URL for a Package2Version, given that the
+ * row is already known to exist. DeveloperUsePkgZip is gated by the DownloadPackageVersionZips
+ * user permission: for a user without it, the column is invisible to SOQL and selecting it
+ * throws "No such column" (at API versions where the field exists). We isolate that select
+ * here so the caller can treat both "no such column" and an empty value as the same signal —
+ * the running user cannot access the download URL — without masking the not-found / wrong-hub
+ * disambiguation done by the caller's existence query.
+ *
+ * @returns the DeveloperUsePkgZip URL, or undefined if the user cannot access it.
+ */
+async function getDeveloperUsePkgZipUrl(
+  connection: Connection,
+  subscriberPackageVersionId: string
+): Promise<string | undefined> {
+  try {
+    const [record] = await PackageVersion.queryPackage2Version(connection, {
+      whereClause: `WHERE SubscriberPackageVersionId = '${subscriberPackageVersionId}'`,
+      fields: ['DeveloperUsePkgZip'] as Package2VersionFieldTypes,
+    });
+    return record?.DeveloperUsePkgZip ?? undefined;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (msg.includes("No such column 'DeveloperUsePkgZip' on entity 'Package2Version'")) {
+      return undefined;
+    }
+    throw e;
+  }
+}
+
+/**
+ * Returns true if a SubscriberPackageVersion with the given 04t ID exists in the system.
+ * SubscriberPackageVersion is a global, non-org-scoped view queryable by any authenticated
+ * user (orgAccess="always", userAccess="isAuthenticatedUser"), so this lets us tell
+ * "package version not found" apart from "exists but not in the targeted Dev Hub".
+ */
+async function subscriberPackageVersionExists(
+  connection: Connection,
+  subscriberPackageVersionId: string
+): Promise<boolean> {
+  try {
+    const result = await connection.tooling.query<{ Id: string }>(
+      `SELECT Id FROM SubscriberPackageVersion WHERE Id = '${subscriberPackageVersionId}' LIMIT 1`
+    );
+    return (result.records?.length ?? 0) > 0;
+  } catch {
+    // If even the existence probe fails (malformed ID, etc.), fall back to "not found".
+    return false;
+  }
+}