Merge pull request #968 from salesforcecli/packagingDistribution/pushUpgradeCLI

@W-17683677@ Integrate push upgrade/migration CLI work into main branch on packaging and plugin-packaging repos.

Author: WillieRuemmele

command-snapshot.json

@@ -64,11 +64,11 @@
       "definitionfile",
       "installationkey",
       "installationkeybypass",
+      "patchversion",
       "target-hub-org",
-      "targetdevhubusername",
-      "patchversion"
+      "targetdevhubusername"
     ],
-    "flagChars": ["f", "k", "m", "p", "s", "v", "w", "x", "a"],
+    "flagChars": ["a", "f", "k", "m", "p", "s", "v", "w", "x"],
     "flags": [
       "api-version",
       "build-instance",
@@ -79,11 +79,11 @@
       "json",
       "loglevel",
       "package",
+      "patch-version",
       "seed-metadata",
       "target-dev-hub",
       "verbose",
-      "wait",
-      "patch-version"
+      "wait"
     ],
     "plugin": "@salesforce/plugin-packaging"
   },
@@ -181,6 +181,57 @@
     "flags": ["api-version", "flags-dir", "json", "loglevel", "target-dev-hub", "verbose"],
     "plugin": "@salesforce/plugin-packaging"
   },
+  {
+    "alias": [],
+    "command": "package:push-upgrade:abort",
+    "flagAliases": [],
+    "flagChars": ["i", "v"],
+    "flags": ["api-version", "flags-dir", "json", "push-request-id", "target-dev-hub"],
+    "plugin": "@salesforce/plugin-packaging"
+  },
+  {
+    "alias": ["force:package:push-upgrade:list"],
+    "command": "package:push-upgrade:list",
+    "flagAliases": ["apiversion", "scheduledlastdays", "target-hub-org", "targetdevhubusername"],
+    "flagChars": ["l", "p", "s", "v"],
+    "flags": [
+      "api-version",
+      "flags-dir",
+      "json",
+      "package",
+      "scheduled-last-days",
+      "show-push-migrations-only",
+      "status",
+      "target-dev-hub"
+    ],
+    "plugin": "@salesforce/plugin-packaging"
+  },
+  {
+    "alias": ["force:package:push-upgrade:report"],
+    "command": "package:push-upgrade:report",
+    "flagAliases": ["apiversion", "pushrequestid", "target-hub-org", "targetdevhubusername"],
+    "flagChars": ["i", "v"],
+    "flags": ["api-version", "flags-dir", "json", "loglevel", "push-request-id", "target-dev-hub"],
+    "plugin": "@salesforce/plugin-packaging"
+  },
+  {
+    "alias": [],
+    "command": "package:push-upgrade:schedule",
+    "flagAliases": ["apiversion"],
+    "flagChars": ["f", "l", "p", "t", "v"],
+    "flags": [
+      "api-version",
+      "flags-dir",
+      "json",
+      "migrate-to-2gp",
+      "org-file",
+      "org-list",
+      "package",
+      "start-time",
+      "target-dev-hub"
+    ],
+    "plugin": "@salesforce/plugin-packaging"
+  },
   {
     "alias": ["force:package:uninstall"],
     "command": "package:uninstall",
@@ -231,7 +282,6 @@
       "releasenotesurl",
       "skipancestorcheck",
       "skipvalidation",
-      "asyncvalidation",
       "target-hub-org",
       "targetdevhubusername",
       "uninstallscript",
@@ -243,6 +293,7 @@
     "flagChars": ["a", "b", "c", "d", "e", "f", "j", "k", "n", "p", "r", "s", "t", "v", "w", "x"],
     "flags": [
       "api-version",
+      "async-validation",
       "branch",
       "build-instance",
       "code-coverage",
@@ -261,7 +312,6 @@
       "releasenotes-url",
       "skip-ancestor-check",
       "skip-validation",
-      "async-validation",
       "tag",
       "target-dev-hub",
       "uninstall-script",

messages/package_pushupgrade_abort.md

@@ -0,0 +1,51 @@
+# summary
+
+Abort a package push upgrade that has been scheduled. Only push upgrade requests with a status of Created or Pending can be aborted.
+
+# description
+
+Specify the request ID for which you want abort the request. If applicable, the command displays errors related to the request.
+
+To show all requests in the org, run "<%= config.bin %> package pushupgrade list --package 033...".
+
+# examples
+
+- Cancel the specified package push upgrade request with the specified ID; uses your default Dev Hub org:
+
+  <%= config.bin %> <%= command.id %> --push-request-id 0DV...
+
+- Cancel the specified package push upgrade request in the Dev Hub org with username devhub@example.com:
+
+  <%= config.bin %> <%= command.id %> --push-request-id 0DV... --target-dev-hub devhub@example.com
+
+# flags.push-request-id.summary
+
+ID of the package push request (starts with 0DV). This ID is returned after the package push-upgrade schedule command completes successfully.
+
+# flags.target-dev-hub.summary
+
+Username or alias of the Dev Hub org.
+
+# flags.target-dev-hub.description
+
+Overrides the value of the target-dev-hub configuration variable, if set.
+
+# error.invalid-push-request-id-owner
+
+Can’t abort package push upgrade request. The specified push upgrade ID is associated with a package in a different Dev Hub org. Retry this command in the context of the Dev Hub org that owns the package.
+
+# error.invalid-push-request-id
+
+Can’t abort package push upgrade request. The specified push upgrade ID isn’t valid. Check the ID (starts with 0DV) and retry the command.
+
+# error.invalid-push-request-status
+
+Can’t abort package push upgrade request with status '${pushRequest.Status}'. Only push upgrade requests with a status of 'Created' or 'Pending' can be cancelled.
+
+# status
+
+Status
+
+# output
+
+Scheduled push upgrade ID [%s] was cancelled.

messages/package_pushupgrade_list.md

@@ -0,0 +1,61 @@
+# summary
+
+Lists the status of push upgrade requests for a given package.
+
+# description
+
+Shows the details of each request to create a push upgrade in the Dev Hub org.
+
+All filter parameters are applied using the AND logical operator (not OR).
+
+To get information about a specific request, run "sf package pushupgrade report" and supply the request ID.
+
+# flags.package.summary
+
+Package ID (starts with 033) of the package that you want push upgrade information for.
+
+# flags.scheduled-last-days.summary
+
+Number of days in the past for which to display the list of push upgrade requests that were scheduled. Used to filter the list output to only recently scheduled push upgrades.
+
+# flags.status.summary
+
+Status used to filter the list output Valid values are: Created, Canceled, Pending, In Progress, Failed, or Succeeded
+
+# flags.show-push-migrations-only.summary
+
+Display only push upgrade requests for package migrations.
+
+# examples
+
+- List all package push upgrade requests in the specified Dev Hub org:
+
+  <%= config.bin %> <%= command.id %> --package 033xyz --target-dev-hub myHub
+
+- List all package push upgrade requests in the specified Dev Hub org scheduled in the last 30 days:
+
+  <%= config.bin %> <%= command.id %> --package 033xyz --scheduled-last-days 30 --target-dev-hub myHub
+
+- List all package push upgrade with a status Succeeded:
+
+  <%= config.bin %> <%= command.id %> --package 033xyz –-status Succeeded
+
+- List all package push upgrade with a status Failed:
+
+  <%= config.bin %> <%= command.id %> --package 033xyz –-status Failed
+
+# id
+
+ID
+
+# status
+
+Status
+
+# package-id
+
+Package Id
+
+# packageVersionId
+
+Package Version Id

messages/package_pushupgrade_report.md

@@ -0,0 +1,27 @@
+# summary
+
+Retrieve the status of a package push upgrade.
+
+# description
+
+Specify the request ID for which you want to view details. If applicable, the command displays errors related to the request.
+
+To show all requests in the org, run "<%= config.bin %> package pushupgrade list".
+
+# examples
+
+- Retrieve details about the package push upgrade with the specified ID; uses your default Dev Hub org:
+
+  <%= config.bin %> <%= command.id %> --push-request-id 0DV...
+
+- Retrieve details about the specified package push request in the Dev Hub org with username devhub@example.com:
+
+  <%= config.bin %> <%= command.id %> --push-request-id 0DV... --target-dev-hub devhub@example.com
+
+# flags.push-request-id.summary
+
+ID of the package push request (starts with 0DV). This ID is returned after the package push-upgrade schedule command completes successfully.
+
+# truncatedErrors
+
+To see all errors, run: %s data query -q "SELECT ErrorMessage FROM PackagePushError WHERE PackagePushJob.PackagePushRequestId='%s'"

messages/package_pushupgrade_schedule.md

@@ -0,0 +1,109 @@
+# summary
+
+Schedule a package push upgrade.
+
+# description
+
+Represents a push upgrade request for upgrading a package in one or many orgs from one version to another version.
+To initiate a push upgrade for an unlocked or second-generation managed package, the Create and Update Second-Generation Packages user permission is required.
+For second-generation managed packages, the push upgrade feature is available only for packages that have passed AppExchange security review. To enable push upgrades for your managed package, log a support case in the Salesforce Partner Community.
+For unlocked packages, push upgrades are enabled by default.
+
+Use the -–migrate-to-2GP flag to indicate you’re installing a converted second-generation managed package into an org that has the first-generation managed package version of that package installed.
+
+# flags.target-dev-hub.summary
+
+Username or alias of the Dev Hub org.
+
+# flags.target-dev-hub.description
+
+Overrides the value of the target-dev-hub configuration variable, if set.
+
+# flags.package.summary
+
+ID (starts with 04t) of the package version that the package is being upgraded to. The package version must be an active, non-beta package version.
+
+# flags.start-time.summary
+
+Date and time (UTC) when the push upgrade is processed. Set to the earliest time that you want Salesforce to attempt to start the upgrade.
+
+# flags.start-time.description
+
+Scheduled push upgrades begin as soon as resources are available on the Salesforce instance, which is either at or after the start time you specify. In certain scenarios, the push upgrade starts a few hours after the scheduled start time.
+
+As a best practice, schedule push upgrades at off-peak hours like 1:00 AM Saturday.  
+If you don't specify this flag, the push upgrade is scheduled to run as soon as resources are available on the Salesforce instance.
+
+# flags.org-file.summary
+
+Filename of the CSV file that contains the list of orgs that need the package upgrade.
+
+# flags.org-file.description
+
+The file must contain one org per line. The org ID must be the only value in each row. 
+All listed orgs must have a package version installed in their org that is lower than the package version you specified for the --package-version flag.
+
+# flags.org-list.summary
+
+Comma-separated list of subscriber org IDs that need the package upgrade.
+
+# flags.migrate-to-2gp.summary
+
+Upgrade from a first-generation managed package (1GP) to a second-generation managed package (2GP). Required when you’re pushing a 2GP package to orgs with the 1GP version installed.
+
+# error.invalid-package-version
+
+Invalid package version.
+
+# error.empty-org-list
+
+Can’t schedule the package push upgrade. The
+org file you specified is empty. Review the file you specified, and retry this command.
+
+# error.empty-org-input
+
+There are no org Ids.
+
+# error.invalid-org-file
+
+Can’t schedule the package push upgrade. The org file you specified is invalid. The org file must be a CSV file, and each row can contain only one org ID. Review and update your org file and retry this command.
+
+# error.invalid-org-input
+
+Can’t schedule the package push upgrade. One or more of the orgs IDs you specified in the org list is an invalid org ID. Review the list of orgs you specified, and retry this command
+
+# error.no-org-file-or-org-list-input
+
+Can’t schedule the package push upgrade. You must specify either a list of orgs, or a file containing the list of orgs to be upgraded. Retry this command using either --org-list or --org-file flag and include the required details.
+
+# examples
+
+- Schedule a push upgrade that initiates at a specified time:
+  <%= config.bin %> <%= command.id %> --package 04txyz --start-time "2024-12-06T21:00:00" --org-file upgrade-orgs.csv
+
+- Schedule a push upgrade that initiates as soon as possible:
+  <%= config.bin %> <%= command.id %> --package 04txyz --org-file upgrade-orgs.csv
+
+- Schedule a push migration from a 1GP package to a 2GP package:
+  <%= config.bin %> <%= command.id %> --migrate-to-2gp --package 04txyz --start-time "2024-12-06T21:00:00" --org-file upgrade-orgs.csv --target-dev-hub myHub
+
+# id
+
+ID
+
+# status
+
+Status
+
+# package-id
+
+Package Id
+
+# packageVersionId
+
+Package Version Id
+
+# output
+
+Push upgrade has been scheduled. To check the status of this push upgrade, use push upgrade request ID [%s] with either "package push-upgrade list" or "package push-upgrade report".
+Orgs scheduled for push upgrade: {%s}

package.json

@@ -8,7 +8,7 @@
     "@oclif/core": "^4",
     "@salesforce/core": "^8.11.1",
     "@salesforce/kit": "^3.2.3",
-    "@salesforce/packaging": "^4.5.0",
+    "@salesforce/packaging": "^4.6.0",
     "@salesforce/sf-plugins-core": "^12.2.2",
     "chalk": "^5.4.1"
   },

schemas/package-push__upgrade-abort.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/PackagePushUpgradeAbortResult",
+  "definitions": {
+    "PackagePushUpgradeAbortResult": {
+      "type": "object",
+      "properties": {
+        "success": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "success"
+      ],
+      "additionalProperties": false
+    }
+  }
+}