Merge pull request #870 from salesforcecli/t/packaging-distribution/W-17409066/pushUpgrade-abort

feat: adds pushupgrade abort command support

Author: mradulsf

command-snapshot.json

@@ -210,6 +210,14 @@
       "target-dev-hub"
     ],
     "plugin": "@salesforce/plugin-packaging"
+  }
+  {
+    "alias": ["force:package:pushupgrade:abort"],
+    "command": "package:pushupgrade:abort",
+    "flagAliases": [],
+    "flagChars": ["i", "v"],
+    "flags": ["api-version", "flags-dir", "json", "push-request-id", "target-dev-hub"],
+    "plugin": "@salesforce/plugin-packaging"
   },
   {
     "alias": ["force:package:uninstall"],

messages/package_pushupgrade_abort.md

@@ -0,0 +1,51 @@
+# summary
+
+Aborts 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. Only package push requests in Created or Pending statuses can be aborted.
+
+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
+
+The ID of the package push request (starts with 0DV). This ID is returned after the package pushupgrade schedule command is run.
+
+# 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
+
+--push-request-id 0DV... is not owned by the org from where the CLI command is run.
+
+# error.invalid-push-request-id
+
+Package push upgrade request id is invalid. Please use valid ID (starts with 0DV).
+
+# error.invalid-push-request-status
+
+The status of the push request is one of the following: In Progress, Succeeded, Failed, Canceled. Only push requests in Created or Pending statuses can be aborted.
+
+# status
+
+Status
+
+# output
+
+Scheduled push upgrade ID [%s] was cancelled.

schemas/package-pushupgrade-abort.json

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

src/commands/package/pushupgrade/abort.ts

@@ -0,0 +1,48 @@
+/*
+ * 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 } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+import { PackagePushUpgrade } from '@salesforce/packaging';
+
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@salesforce/plugin-packaging', 'package_pushupgrade_abort');
+
+export class PackagePushUpgradeAbortCommand extends SfCommand<boolean> {
+  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 flags = {
+    'target-dev-hub': Flags.requiredHub(),
+    'api-version': Flags.orgApiVersion(),
+    // eslint-disable-next-line sf-plugin/id-flag-suggestions
+    'push-request-id': Flags.salesforceId({
+      length: 'both',
+      char: 'i',
+      summary: messages.getMessage('flags.push-request-id.summary'),
+      required: true,
+      startsWith: '0DV',
+    }),
+  };
+
+  public async run(): Promise<boolean> {
+    const { flags } = await this.parse(PackagePushUpgradeAbortCommand);
+    const connection = flags['target-dev-hub'].getConnection(flags['api-version']);
+
+    const packagePushRequestOptions = { packagePushRequestId: flags['push-request-id'] };
+
+    // Schedule the push upgrade
+    const result = await PackagePushUpgrade.abort(connection, packagePushRequestOptions);
+
+    if (result) {
+      this.log(messages.getMessage('output', [flags['push-request-id']]));
+    }
+
+    return result;
+  }
+}

test/commands/package/packagePushUpgradeAbort.test.ts

@@ -0,0 +1,85 @@
+/*
+ * 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 { SfCommand } from '@salesforce/sf-plugins-core';
+import { Config } from '@oclif/core';
+import { expect } from 'chai';
+import sinon from 'sinon';
+import { PackagePushUpgrade } from '@salesforce/packaging';
+import { PackagePushUpgradeAbortCommand } from '../../../src/commands/package/pushupgrade/abort.js';
+
+describe('PackagePushUpgradeAbortCommand', () => {
+  const $$ = new TestContext();
+  const testOrg = new MockTestOrgData();
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+  const abortStub = $$.SANDBOX.stub(PackagePushUpgrade, 'abort');
+  const config = new Config({ root: import.meta.url });
+
+  // stubs
+  let logStub: sinon.SinonStub;
+
+  const stubSpinner = (cmd: PackagePushUpgradeAbortCommand) => {
+    $$.SANDBOX.stub(cmd.spinner, 'start');
+    $$.SANDBOX.stub(cmd.spinner, 'stop');
+  };
+
+  before(async () => {
+    await $$.stubAuths(testOrg);
+    await config.load();
+  });
+
+  beforeEach(async () => {
+    logStub = $$.SANDBOX.stub(SfCommand.prototype, 'log');
+  });
+
+  afterEach(() => {
+    $$.restore();
+  });
+
+  it('should successfully abort a push request', async () => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+    const cmd = new PackagePushUpgradeAbortCommand(['-i', '0DVxx0000004CCG', '-v', 'test@hub.org'], config);
+    stubSpinner(cmd);
+    const res = await cmd.run();
+
+    expect(res).to.be.true;
+    expect(abortStub.calledOnce).to.be.true;
+    expect(logStub.callCount).to.equal(1);
+    expect(logStub.args[0]).to.deep.equal(['Scheduled push upgrade ID 0DVxx0000004CCG was canceled.']);
+  });
+
+  it('should throw an error if push-request-id is missing', async () => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+    const cmd = new PackagePushUpgradeAbortCommand(['-v', 'test@hub.org'], config);
+    stubSpinner(cmd);
+
+    try {
+      await cmd.run();
+    } catch (err) {
+      const error = err as Error;
+      expect(error.name).to.equal('Error');
+      expect(error.message).to.include('Missing required flag push-request-id');
+    }
+  });
+
+  it('should throw an error if push-request status is not "Created" or "Pending" or  is missing', async () => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+    abortStub.rejects(new Error('Abortion is only allowed for "Created" or "Pending" statuses.'));
+    const cmd = new PackagePushUpgradeAbortCommand(['-i', '0DVxx0000004CCG', '-v', 'test@hub.org'], config);
+    stubSpinner(cmd);
+
+    try {
+      await cmd.run();
+    } catch (err) {
+      const error = err as Error;
+      const msg = 'Abortion is only allowed for "Created" or "Pending" statuses.';
+      expect(error.name).to.equal('Error');
+      expect(error.message).to.include(msg);
+    }
+  });
+});