platform-destructive-deploy

Handling Destructive Changes

Coordinate metadata deletion against a Salesforce org via the destructiveChanges manifest. Runs in three phases: scope → validate → execute, with stricter guardrails for production.

Phase 1 — Scope the deletion

Step 1a — Gather the components to remove

Ask the user (or infer from context) which components to delete. For each, capture:

• Metadata type (e.g. CustomObject, CustomField, ApexClass, Flow, PermissionSet)
• API name (e.g. Project__c, Account.Status__c, MyController)

Step 1b — Local dependency scan (best-effort)

Before generating the manifest, scan the local project for references to each component. Use Grep over force-app/:

grep -rn "<componentApiName>" force-app/ --include='*.cls' --include='*.trigger' --include='*.xml' --include='*.js' --include='*.html'

If references are found:

• List them to the user
• Recommend either updating those references first OR removing them in the same destructive deploy
• Do NOT proceed silently — surface the dependency risk

Step 1c — Generate destructiveChanges.xml

Write to manifest/destructiveChangesPre.xml (for pre-deploy deletion) or manifest/destructiveChangesPost.xml (for post-deploy deletion). Use the standard Salesforce metadata format:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Project__c</members>
        <members>OldThing__c</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>Account.Status__c</members>
        <name>CustomField</name>
    </types>
    <version>62.0</version>
</Package>

Use the API version from sfdx-project.json's sourceApiVersion.

Group components by metadata type (one <types> block per type). For namespaced fields, use Object.Field notation.

Phase 2 — Validate

ALWAYS validate before executing a destructive deploy:

sf project deploy validate \
  --pre-destructive-changes manifest/destructiveChangesPre.xml \
  --manifest manifest/package.xml \
  --target-org <alias> \
  --test-level RunLocalTests \
  --json