feat: Package Push Upgrade List command

command-snapshot.json

@@ -179,6 +179,13 @@
     "flags": ["api-version", "flags-dir", "json", "loglevel", "target-dev-hub", "verbose"],
     "plugin": "@salesforce/plugin-packaging"
   },
+  {
+    "alias": ["force:package:pushupgrade:list"],
+    "command": "package:pushupgrade:list",
+    "flagAliases": ["apiversion", "scheduledlastdays", "target-hub-org", "targetdevhubusername"],
+    "flagChars": ["l", "p", "s", "v"],
+    "flags": ["api-version", "flags-dir", "json", "packageid", "scheduled-last-days", "status", "target-dev-hub"],
+  },
   {
     "alias": ["force:package:pushupgrade:report"],
     "command": "package:pushupgrade:report",

messages/package_pushupgrade_list.md

@@ -0,0 +1,57 @@
+# 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-id.summary
+
+Specify the package ID (starts with 033) of the package that you want push upgrade information for.
+
+# flags.scheduled-last-days.summary
+
+Filter the list output to only display push upgrades scheduled in the last few days. For example, if this flag is set to 30, only push upgrade requests scheduled for the last 30 days are listed in the output.
+
+# flags.status.summary
+
+Filter the list output by one of the following statuses: Created, Canceled, Pending, In Progress, Failed, or Succeeded
+
+# flags.verbose.summary
+
+Displays additional information such as number of orgs scheduled for push upgrade, orgs successfully upgraded, etc.
+
+# examples
+
+- List all package push upgrade requests in the specified Dev Hub org:
+
+  sf package pushupgrade list --package 033xyz --target-dev-hub myHub
+
+- List all package push upgrade requests in the specified Dev Hub org scheduled in the last 30 days:
+
+  sf package pushupgrade list --package 033xyz --scheduled-last-days 30 --target-dev-hub myHub
+
+- List all package push upgrade with a status Succeeded:
+
+  sf package pushupgrade list --package 033xyz –-Status=Succeeded
+
+# id
+
+ID
+
+# status
+
+Status
+
+# package-id
+
+Package Id
+
+# packageVersionId
+
+Package Version Id

schemas/package-pushupgrade-list.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/PackagePushRequestListResultArr",
+  "definitions": {
+    "PackagePushRequestListResultArr": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/PackagePushRequestListResult"
+      }
+    },
+    "PackagePushRequestListResult": {
+      "type": "object",
+      "properties": {
+        "Id": {
+          "type": "string"
+        },
+        "PackageVersionId": {
+          "type": "string"
+        },
+        "PackageVersion": {
+          "type": "object",
+          "properties": {
+            "Name": {
+              "type": "string"
+            },
+            "MajorVersion": {
+              "type": "string"
+            },
+            "MinorVersion": {
+              "type": "string"
+            }
+          },
+          "required": ["Name", "MajorVersion", "MinorVersion"],
+          "additionalProperties": false
+        },
+        "Status": {
+          "type": "string"
+        },
+        "ScheduledStartTime": {
+          "type": "string"
+        },
+        "StartTime": {
+          "type": "string"
+        },
+        "EndTime": {
+          "type": "string"
+        },
+        "OrgsScheduled": {
+          "type": "number"
+        },
+        "OrgsUpgradeSucceeded": {
+          "type": "number"
+        },
+        "OrgsUpgradeFailed": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "Id",
+        "PackageVersionId",
+        "PackageVersion",
+        "Status",
+        "ScheduledStartTime",
+        "StartTime",
+        "EndTime",
+        "OrgsScheduled",
+        "OrgsUpgradeSucceeded",
+        "OrgsUpgradeFailed"
+      ],
+      "additionalProperties": false
+    }
+  }
+}

src/commands/package/pushupgrade/list.ts

@@ -0,0 +1,109 @@
+/*
+ * Copyright (c) 2024, 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
+ */
+
+import { Flags, SfCommand, orgApiVersionFlagWithDeprecations } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+import { PackagePushRequestListResult, PackagePushUpgrade } from '@salesforce/packaging';
+import chalk from 'chalk';
+import { requiredHubFlag } from '../../../utils/hubFlag.js';
+
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@salesforce/plugin-packaging', 'package_pushupgrade_list');
+
+type Status = 'Created' | 'Cancelled' | 'Pending' | 'In Progress' | 'Failed' | 'Succeeded';
+
+export type PackagePushRequestListResultArr = PackagePushRequestListResult[];
+
+export class PackagePushRequestListCommand extends SfCommand<PackagePushRequestListResultArr> {
+  public static readonly summary = messages.getMessage('summary');
+  public static readonly description = messages.getMessage('description');
+  public static readonly examples = messages.getMessages('examples');
+  public static readonly hidden = true;
+  public static state = 'beta';
+  public static readonly aliases = ['force:package:pushupgrade:list'];
+  public static readonly flags = {
+    'target-dev-hub': requiredHubFlag,
+    'api-version': orgApiVersionFlagWithDeprecations,
+    packageid: Flags.string({
+      char: 'p',
+      summary: messages.getMessage('flags.package-id.summary'),
+      required: true,
+    }),
+    'scheduled-last-days': Flags.integer({
+      char: 'l',
+      deprecateAliases: true,
+      aliases: ['scheduledlastdays'],
+      summary: messages.getMessage('flags.scheduled-last-days.summary'),
+    }),
+    status: Flags.custom<Status>({
+      options: ['Created', 'Cancelled', 'Pending', 'In Progress', 'Failed', 'Succeeded'],
+    })({
+      char: 's',
+      summary: messages.getMessage('flags.status.summary'),
+    }),
+  };
+
+  public async run(): Promise<PackagePushRequestListResultArr> {
+    const { flags } = await this.parse(PackagePushRequestListCommand);
+    const connection = flags['target-dev-hub'].getConnection(flags['api-version']);
+    const scheduledLastDays = flags['scheduled-last-days'];
+
+    // Check if scheduledLastDays is valid
+    if (flags['scheduled-last-days'] !== undefined) {
+      if (isNaN(scheduledLastDays!) || scheduledLastDays! <= 0) {
+        throw new Error('Invalid value for --scheduled-last-days. It must be a positive integer.');
+      }
+    }
+
+    // Get results of query here
+    // Use const since we will add verbose later
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment
+    const results: PackagePushRequestListResult[] = await PackagePushUpgrade.list(connection, {
+      packageId: flags.packageid,
+      status: flags.status,
+      scheduledLastDays,
+    });
+
+    if (results.length === 0) {
+      this.warn('No results found');
+    } else {
+      const data = await Promise.all(
+        results.map(async (record: PackagePushRequestListResult) => {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+          const packagePushRequestOptions = { packagePushRequestId: record?.Id };
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+          const totalNumOrgs = await PackagePushUpgrade.getTotalJobs(connection, packagePushRequestOptions);
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+          const numOrgsUpgradedFail = await PackagePushUpgrade.getFailedJobs(connection, packagePushRequestOptions);
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+          const numOrgsUpgradedSuccess = await PackagePushUpgrade.getSucceededJobs(
+            connection,
+            packagePushRequestOptions
+          );
+
+          return {
+            Id: record?.Id,
+            PackageVersionId: record?.PackageVersionId,
+            PackageVersionName: record?.PackageVersion?.Name,
+            PackageVersionNumber: record?.PackageVersion?.MajorVersion + '.' + record?.PackageVersion?.MinorVersion,
+            Status: record?.Status,
+            ScheduledStartTime: record?.ScheduledStartTime,
+            StartTime: record?.StartTime,
+            EndTime: record?.EndTime,
+            NumOrgsScheduled: totalNumOrgs,
+            NumOrgsUpgradedFail: numOrgsUpgradedFail,
+            NumOrgsUpgradedSuccess: numOrgsUpgradedSuccess,
+          };
+        })
+      );
+
+      this.table({ data, overflow: 'wrap', title: chalk.blue(`Push Upgrade Request List:  [${results.length}]`) });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return results;
+  }
+}

test/commands/package/packagePushUpgradeList.test.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2024, 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
+ */
+import { MockTestOrgData, TestContext } from '@salesforce/core/testSetup';
+import { Config } from '@oclif/core';
+import { expect } from 'chai';
+import { PackagePushRequestListResult, PackagePushUpgrade } from '@salesforce/packaging';
+import { env } from '@salesforce/kit';
+import { PackagePushRequestListCommand } from '../../../src/commands/package/pushupgrade/list.js';
+
+const pushUpgradeListSuccess: PackagePushRequestListResult[] = [
+  {
+    Id: '0Af0M000000AxuqSAC',
+    PackageVersionId: '04t0M000000AxuqSAC',
+    PackageVersion: {
+      Name: 'VersionName',
+      MajorVersion: '1',
+      MinorVersion: '1',
+    },
+    Status: 'Success',
+    ScheduledStartTime: '2024-01-02T00:00:00.000Z',
+    StartTime: '2024-01-02T00:01:00.000Z',
+    EndTime: '2024-01-02T00:10:00.000Z',
+    OrgsScheduled: 2,
+    OrgsUpgradeFailed: 0,
+    OrgsUpgradeSucceeded: 2,
+  },
+];
+
+describe('package:pushupgrade:list - tests', () => {
+  const $$ = new TestContext();
+  const testOrg = new MockTestOrgData();
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+  const createStub = $$.SANDBOX.stub(PackagePushUpgrade, 'list');
+  const config = new Config({ root: import.meta.url });
+
+  const stubSpinner = (cmd: PackagePushRequestListCommand) => {
+    $$.SANDBOX.stub(cmd.spinner, 'start');
+    $$.SANDBOX.stub(cmd.spinner, 'stop');
+  };
+
+  before(async () => {
+    await $$.stubAuths(testOrg);
+    await config.load();
+  });
+
+  afterEach(() => {
+    $$.restore();
+  });
+
+  it('should list push upgrade requests', async () => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+    createStub.resolves(pushUpgradeListSuccess);
+    const envSpy = $$.SANDBOX.spy(env, 'setBoolean').withArgs('SF_APPLY_REPLACEMENTS_ON_CONVERT', true);
+
+    const cmd = new PackagePushRequestListCommand(['-p', '033xi000000Gmj6XXX', '-v', '[email protected]'], config);
+    stubSpinner(cmd);
+    const res = await cmd.run();
+    expect(envSpy.calledOnce).to.equal(false);
+    expect(res).to.eql(pushUpgradeListSuccess);
+  });
+
+  it('should fail to list push upgrade requests', async () => {
+    createStub.rejects(new Error('Failed to list push upgrade requests'));
+    const envSpy = $$.SANDBOX.spy(env, 'setBoolean').withArgs('SF_APPLY_REPLACEMENTS_ON_CONVERT', true);
+
+    const cmd = new PackagePushRequestListCommand(['-p', '033xi000000Gmj6XXX', '-v', '[email protected]'], config);
+    stubSpinner(cmd);
+
+    try {
+      await cmd.run();
+      throw new Error('Failed to list push upgrade requests');
+    } catch (error) {
+      expect((error as Error).message).to.equal('Failed to list push upgrade requests');
+      expect(envSpy.calledOnce).to.equal(false);
+    }
+  });
+});