fix: provide better errors when deleting sandboxes

Author: shetzel

messages/delete_sandbox.md

@@ -6,6 +6,7 @@ Delete a sandbox.
 
 Salesforce CLI marks the org for deletion in the production org that contains the sandbox licenses and then deletes all local references to the org from your computer.
 Specify a sandbox with either the username you used when you logged into it, or the alias you gave the sandbox when you created it. Run "<%= config.bin %> org list" to view all your orgs, including sandboxes, and their aliases.
+Both the sandbox and the associated production org must already be authenticated with the CLI to successfully delete the sandbox.
 
 # examples
 
@@ -17,7 +18,7 @@ Specify a sandbox with either the username you used when you logged into it, or
 
   <%= config.bin %> <%= command.id %> --target-org [email protected]
 
-- Delete the sandbox without prompting to confirm :
+- Delete the sandbox without prompting to confirm:
 
   <%= config.bin %> <%= command.id %> --target-org my-sandbox --no-prompt
 
@@ -41,6 +42,11 @@ Successfully marked sandbox %s for deletion.
 
 There is no sandbox with the username %s.
 
-# error.isNotSandbox
+# error.unknownSandbox
 
-The target org, %s, is not a sandbox.
+The org with username: %s is not known by the CLI to be a sandbox
+
+# error.unknownSandbox.actions
+
+Re-authenticate the sandbox with the CLI and try again.
+Ensure the CLI has authenticated with the sandbox's production org.

src/commands/org/delete/sandbox.ts

@@ -4,7 +4,7 @@
  * 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 { AuthInfo, AuthRemover, Messages, Org, StateAggregator } from '@salesforce/core';
+import { AuthInfo, AuthRemover, Messages, Org, SfError, StateAggregator } from '@salesforce/core';
 import { Flags, SfCommand } from '@salesforce/sf-plugins-core';
 import { orgThatMightBeDeleted } from '../../../shared/flags';
 
@@ -16,7 +16,7 @@ export interface SandboxDeleteResponse {
   username: string;
 }
 
-export default class EnvDeleteSandbox extends SfCommand<SandboxDeleteResponse> {
+export default class DeleteSandbox extends SfCommand<SandboxDeleteResponse> {
   public static readonly summary = messages.getMessage('summary');
   public static readonly description = messages.getMessage('description');
   public static readonly examples = messages.getMessages('examples');
@@ -34,14 +34,30 @@ export default class EnvDeleteSandbox extends SfCommand<SandboxDeleteResponse> {
   };
 
   public async run(): Promise<SandboxDeleteResponse> {
-    const flags = (await this.parse(EnvDeleteSandbox)).flags;
+    const flags = (await this.parse(DeleteSandbox)).flags;
     const username = flags['target-org'];
+    let orgId: string;
 
-    const orgId = (await AuthInfo.create({ username })).getFields().orgId as string;
-    const isSandbox = await (await StateAggregator.getInstance()).sandboxes.hasFile(orgId);
+    try {
+      const sbxAuthFields = (await AuthInfo.create({ username })).getFields();
+      orgId = sbxAuthFields.orgId as string;
+    } catch (error) {
+      if (error instanceof SfError && error.name === 'NamedOrgNotFoundError') {
+        error.actions = [
+          `Ensure the alias or username for the ${username} org is correct.`,
+          `Ensure the ${username} org has been authenticated with the CLI.`,
+        ];
+      }
+      throw error;
+    }
+
+    // The StateAggregator identifies sandbox auth files with a pattern of
+    // <sandbox_ID>.sandbox.json.  E.g., 00DZ0000009T3VZMA0.sandbox.json
+    const stateAggregator = await StateAggregator.getInstance();
+    const cliCreatedSandbox = await stateAggregator.sandboxes.hasFile(orgId);
 
-    if (!isSandbox) {
-      throw messages.createError('error.isNotSandbox', [username]);
+    if (!cliCreatedSandbox) {
+      throw messages.createError('error.unknownSandbox', [username]);
     }
 
     if (flags['no-prompt'] || (await this.confirm(messages.getMessage('prompt.confirm', [username])))) {

src/commands/org/delete/scratch.ts

@@ -17,7 +17,7 @@ export interface ScratchDeleteResponse {
   username: string;
 }
 
-export default class EnvDeleteScratch extends SfCommand<ScratchDeleteResponse> {
+export default class DeleteScratch extends SfCommand<ScratchDeleteResponse> {
   public static readonly summary = messages.getMessage('summary');
   public static readonly description = messages.getMessage('description');
   public static readonly examples = messages.getMessages('examples');
@@ -35,7 +35,7 @@ export default class EnvDeleteScratch extends SfCommand<ScratchDeleteResponse> {
   };
 
   public async run(): Promise<ScratchDeleteResponse> {
-    const flags = (await this.parse(EnvDeleteScratch)).flags;
+    const flags = (await this.parse(DeleteScratch)).flags;
     const resolvedUsername = flags['target-org'];
     const orgId = (await AuthInfo.create({ username: resolvedUsername })).getFields().orgId as string;
 

test/nut/scratchDelete.nut.ts

@@ -11,7 +11,7 @@ import { execCmd, TestSession } from '@salesforce/cli-plugins-testkit';
 import { assert, expect } from 'chai';
 import { ScratchDeleteResponse } from '../../src/commands/org/delete/scratch';
 
-describe('env:delete:scratch NUTs', () => {
+describe('org:delete:scratch NUTs', () => {
   const scratchOrgAlias = 'scratch-org';
   const scratchOrgAlias2 = 'scratch-org-2';
   const scratchOrgAlias3 = 'scratch-org-3';

test/unit/force/org/clone.test.ts

@@ -16,7 +16,7 @@ import * as requestFunctions from '../../../../src/shared/sandboxRequest';
 
 config.truncateThreshold = 0;
 
-describe('org:clone', () => {
+describe('[DEPRECATED] force:org:clone', () => {
   const $$ = new TestContext();
 
   beforeEach(async () => {

test/unit/force/org/delete.test.ts

@@ -10,14 +10,14 @@ import { MockTestOrgData, TestContext } from '@salesforce/core/lib/testSetup';
 import { config, expect } from 'chai';
 import { stubPrompter, stubSfCommandUx } from '@salesforce/sf-plugins-core';
 import { SandboxAccessor } from '@salesforce/core/lib/stateAggregator/accessors/sandboxAccessor';
-import { Delete } from '../../../../src/commands/force/org/delete';
+import { Delete as LegacyDelete } from '../../../../src/commands/force/org/delete';
 
 config.truncateThreshold = 0;
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/plugin-org', 'delete');
 
-describe('org:delete', () => {
+describe('[DEPRECATED] force:org:delete', () => {
   const $$ = new TestContext();
   const testOrg = new MockTestOrgData();
   const testHub = new MockTestOrgData();
@@ -35,7 +35,7 @@ describe('org:delete', () => {
   it('will throw an error when no default set', async () => {
     await $$.stubConfig({});
     try {
-      await Delete.run();
+      await LegacyDelete.run();
       expect.fail('should have thrown an error');
     } catch (e) {
       const err = e as SfError;
@@ -46,7 +46,7 @@ describe('org:delete', () => {
 
   it('will prompt before attempting to delete', async () => {
     await $$.stubConfig({ 'target-org': testOrg.username });
-    const res = await Delete.run([]);
+    const res = await LegacyDelete.run([]);
     expect(prompterStubs.confirm.calledOnce).to.equal(true);
     expect(prompterStubs.confirm.firstCall.args[0]).to.equal(
       messages.getMessage('confirmDelete', ['scratch', testOrg.username])
@@ -57,7 +57,7 @@ describe('org:delete', () => {
   it('will resolve a default alias', async () => {
     await $$.stubConfig({ 'target-org': 'myAlias' });
     $$.stubAliases({ myAlias: testOrg.username });
-    const res = await Delete.run([]);
+    const res = await LegacyDelete.run([]);
     expect(prompterStubs.confirm.calledOnce).to.equal(true);
     expect(prompterStubs.confirm.firstCall.args[0]).to.equal(
       messages.getMessage('confirmDelete', ['scratch', testOrg.username])
@@ -67,7 +67,7 @@ describe('org:delete', () => {
 
   it('will determine sandbox vs scratch org and delete sandbox', async () => {
     $$.SANDBOX.stub(SandboxAccessor.prototype, 'hasFile').resolves(true);
-    const res = await Delete.run(['--target-org', testOrg.username]);
+    const res = await LegacyDelete.run(['--target-org', testOrg.username]);
     expect(prompterStubs.confirm.calledOnce).to.equal(true);
     expect(prompterStubs.confirm.firstCall.args[0]).to.equal(
       messages.getMessage('confirmDelete', ['sandbox', testOrg.username])
@@ -78,7 +78,7 @@ describe('org:delete', () => {
   it('will NOT prompt before deleting scratch org when flag is provided', async () => {
     $$.SANDBOX.stub(Org.prototype, 'isSandbox').resolves(false);
     $$.SANDBOX.stub(Org.prototype, 'delete').resolves();
-    const res = await Delete.run(['--noprompt', '--target-org', testOrg.username]);
+    const res = await LegacyDelete.run(['--noprompt', '--target-org', testOrg.username]);
     expect(prompterStubs.confirm.calledOnce).to.equal(false);
     expect(sfCommandUxStubs.log.callCount).to.equal(1);
     expect(sfCommandUxStubs.log.getCalls().flatMap((call) => call.args)).to.deep.include(
@@ -90,7 +90,7 @@ describe('org:delete', () => {
   it('will NOT prompt before deleting sandbox when flag is provided', async () => {
     $$.SANDBOX.stub(SandboxAccessor.prototype, 'hasFile').resolves(true);
     $$.SANDBOX.stub(Org.prototype, 'delete').resolves();
-    const res = await Delete.run(['--noprompt', '--target-org', testOrg.username]);
+    const res = await LegacyDelete.run(['--noprompt', '--target-org', testOrg.username]);
     expect(prompterStubs.confirm.calledOnce).to.equal(false);
     expect(sfCommandUxStubs.log.callCount).to.equal(1);
     expect(sfCommandUxStubs.log.getCalls().flatMap((call) => call.args)).to.deep.include(
@@ -102,7 +102,7 @@ describe('org:delete', () => {
   it('will catch the ScratchOrgNotFound and wrap correctly', async () => {
     $$.SANDBOX.stub(Org.prototype, 'isSandbox').resolves(false);
     $$.SANDBOX.stub(Org.prototype, 'delete').throws(new SfError('bah!', 'ScratchOrgNotFound'));
-    const res = await Delete.run(['--noprompt', '--target-org', testOrg.username]);
+    const res = await LegacyDelete.run(['--noprompt', '--target-org', testOrg.username]);
     expect(prompterStubs.confirm.calledOnce).to.equal(false);
     expect(res).to.deep.equal({ orgId: testOrg.orgId, username: testOrg.username });
     expect(sfCommandUxStubs.log.getCalls().flatMap((call) => call.args)).to.deep.include(
@@ -113,7 +113,7 @@ describe('org:delete', () => {
   it('will catch the SandboxNotFound and wrap correctly', async () => {
     $$.SANDBOX.stub(SandboxAccessor.prototype, 'hasFile').resolves(true);
     $$.SANDBOX.stub(Org.prototype, 'delete').throws(new SfError('bah!', 'SandboxNotFound'));
-    const res = await Delete.run(['--noprompt', '--target-org', testOrg.username]);
+    const res = await LegacyDelete.run(['--noprompt', '--target-org', testOrg.username]);
     expect(prompterStubs.confirm.called).to.equal(false);
     expect(res).to.deep.equal({ orgId: testOrg.orgId, username: testOrg.username });
     expect(

test/unit/force/org/sandboxCreate.test.ts

@@ -29,7 +29,7 @@ config.truncateThreshold = 0;
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/plugin-org', 'create');
 
-describe('org:create (sandbox paths)', () => {
+describe('[DEPRECATED] force:org:create (sandbox paths)', () => {
   const $$ = new TestContext();
   const testOrg = new MockTestOrgData();
   // stubs

test/unit/force/org/scratchOrgCreate.test.ts

@@ -34,7 +34,7 @@ const CREATE_RESULT = {
   warnings: [],
 };
 
-describe('org:create', () => {
+describe('[DEPRECATED] force:org:create', () => {
   const $$ = new TestContext();
   const testHub = new MockTestOrgData();
   testHub.isDevHub = true;