sf-decomposer 5.3.12 → 5.3.13

package/CHANGELOG.md

@@ -5,6 +5,14 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [5.3.13](https://github.com/mcarvin8/sf-decomposer/compare/v5.3.12...v5.3.13) (2025-03-05)
+
+
+### Bug Fixes
+
+* **deps:** bump @salesforce/source-deploy-retrieve ([2146e58](https://github.com/mcarvin8/sf-decomposer/commit/2146e5881e0307d44c092a942c3380d7c441ecd4))
+* **deps:** bump the xml-disassemblers group with 3 updates ([3b5c37f](https://github.com/mcarvin8/sf-decomposer/commit/3b5c37f6cceaedd913df75351b25d05e633b8e5d))
+
 ## [5.3.12](https://github.com/mcarvin8/sf-decomposer/compare/v5.3.11...v5.3.12) (2025-02-27)
 
 

package/README.md

@@ -6,7 +6,7 @@
 <details>
   <summary>Table of Contents</summary>
 
-- [Install](#install)
+- [Quick Start](#quick-start)
 - [Why SF Decomposer](#why-sf-decomposer)
 - [Commands](#commands)
   - [`sf decomposer decompose`](#sf-decomposer-decompose)
@@ -14,34 +14,60 @@
 - [Decompose Structure](#decompose-structure)
 - [Supported Metadata](#supported-metadata)
   - [Metadata Exceptions](#metadata-exceptions)
-- [Debugging](#debugging)
+- [Troubleshooting](#troubleshooting)
 - [Hooks](#hooks)
 - [Ignore Files](#ignore-files)
   - [`.forceignore`](#.forceignore)
   - [`.sfdecomposerignore`](#.sfdecomposerignore)
   - [`.gitignore`](#.gitignore)
-- [Contributing](#contributing)
 - [Issues](#issues)
+- [Contributing](#contributing)
 - [License](#license)
 </details>
 
-A Salesforce CLI plugin to break down large metadata files into smaller, more manageable files for version control and then recreate deployment-compatible files.
+Break down large Salesforce metadata files into smaller, more manageable files for version control and then recreate deployment-compatible files.
 
-## Install
+## Quick Start
+1. Install plugin using `sf`
 
 ```bash
 sf plugins install sf-decomposer@x.y.z
 ```
 
+2. Decompose the metadata type(s) in your Salesforce DX project
+
+```bash
+sf decomposer decompose -m "flow" -m "labels"
+```
+
+3. Add decomposed files to `.forceignore`
+
+> This is **REQUIRED** to avoid errors when running `sf`commands. See [Ignore Files](#ignore-files) section.
+
+4. Stage files in version control
+
+5. Recompose the metadata type(s)
+
+```bash
+sf decomposer recompose -m "flow" -m "labels"
+```
+
+6. Deploy recomposed metadata
+
 ## Why SF Decomposer
 
 Why should you consider using `sf-decomposer` over Salesforce's decomposition?
 
-- Salesforce's decomposition betas are evaluated for each metadata type before they are considered. `sf-decomposer` supports the vast majority of Salesforce metadata types available from the Metadata API.
-- Salesforce's decomposition is all or nothing for each metadata type. Meaning, if you want to decompose workflows, all of your workflows will need to be decomposed to work with Salesforce's approach. `sf-decomposer` allows you to selectively decompose for each metadata type.
+- **Broad Metadata Support**: Unlike Salesforce's decomposition, `sf-decomposer` supports most metadata types available in the Metadata API.  
+- **Selective Decomposition**: `sf-decomposer` allows you to decompose only the metadata you need instead of Salesforce's all-or-nothing approach.
   - See [.sfdecomposerignore](#.sfdecomposerignore)
-- Some metadata types may only be partially decomposed by Salesforce such as permission sets based on what designs are picked. `sf-decomposer` will allow for total decomposition. So if a user wants to fully decompose permission sets, they can use this plugin.
-- When `sf-decomposer` recomposes the decomposed files, it will sort the elements consistently compared to native Salesforce files.
+- **Complete Decomposition**: Partially decomposed metadata types (e.g., Salesforce's `decomposePermissionSetBeta2`) can be fully decomposed by `sf-decomposer`.  
+- **Consistent Sorting**: `sf-decomposer` recomposition ensures elements are always sorted consistently for better version control.
+
+In general, `sf-decomposer` helps Salesforce Admins do a few things with their source deployments:
+
+- Enhance peer reviews of large metadata in CI/CD platforms like GitHub, i.e. easier-to-review diffs in pull requests
+- Make deployments safer by ensuring only the intended changes are deployed, improving the overall version control process
 
 ## Commands
 
@@ -167,7 +193,7 @@ When custom labels are decomposed, each custom label will have its own file in t
 
 ## Supported Metadata
 
-All metadata types imported from this plugin's version of `@salesforce/source-deploy-retrieve` (SDR) toolkit are supported except for certain types.
+All parent metadata types imported from this plugin's version of `@salesforce/source-deploy-retrieve` (SDR) toolkit are supported except for certain types.
 
 The `--metadata-type`/`-m` flag should be the metadata's `suffix` value as listed in the [metadataRegistry.json](https://github.com/forcedotcom/source-deploy-retrieve/blob/main/src/registry/metadataRegistry.json).
 
@@ -189,7 +215,7 @@ Here are some examples:
   ```
   Error (1): `botVersion` suffix should not be used. Please use `bot` to decompose/recompose bot and bot version files.
   ```
-- Custom Objects are not supported by this plugin.
+- Custom Objects are not supported by this plugin as they already are decomposed by default.
   ```
   Error (1): Custom Objects are not supported by this plugin.
   ```
@@ -202,7 +228,7 @@ Here are some examples:
   Error (1): Metadata type not found for the given suffix: field.
   ```
 
-## Debugging
+## Troubleshooting
 
 `sf-decomposer` searches the current working directory for the `sfdx-project.json`, and if it's not found in the current working directory, it will search upwards for it until it hits your root drive. If the `sfdx-project.json` file isn't found, the plugin will fail with:
 
@@ -226,11 +252,9 @@ Recommend adding the `disassemble.log` to your `.gitignore` file if you are usin
 
 ## Hooks
 
-> **NOTE:** In order to avoid errors during the retrieval, you must configure your `.forceignore` file to have the Salesforce CLI ignore the decomposed files. See [Ignore Files](#ignore-files) section.
+> **NOTE:** In order to avoid errors when running `sf` commands, you must configure your `.forceignore` file to have the Salesforce CLI ignore the decomposed files. See [Ignore Files](#ignore-files) section.
 
-A post-retrieve hook (for the decompose command) and a pre-run hook (for the recompose command) have been configured if you elect to use them. The post-retrieve hook will automatically decompose the desired metadata types after every Salesforce CLI retrieval (`sf project retrieve start` command). The pre-run hook will automatically recompose the desired metadata types before every Salesforce CLI deployment/validation (`sf project deploy start` and `sf project deploy validate` commands).
-
-Both hooks require you to create this file in the root of your repo: `.sfdecomposer.config.json`. You can use the sample [.sfdecomposer.config.json](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/samples/.sfdecomposer.config.json) provided. Update the file as such:
+To automate decomposing and recomposing, create `.sfdecomposer.config.json` in the root of your Salesforce DX project. You can copy and update the sample [.sfdecomposer.config.json](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/samples/.sfdecomposer.config.json) provided.
 
 - `metadataSuffixes` is required and should be a comma-separated string of metadata suffixes to decompose automatically after retrievals.
 - `ignorePackageDirectories` is optional and should be a comma-separated string of package directories to ignore.
@@ -238,7 +262,12 @@ Both hooks require you to create this file in the root of your repo: `.sfdecompo
 - `postPurge` is optional and should be a boolean. If true, this will delete the retrieval file after decomposing it or delete the decomposed files after recomposing them. If you do not provide this, the default will be `false`.
 - `decomposedFormat` is optional and should be either `xml`, `json`, or `yaml`, depending on what file format you want the decomposed files created as. If you do not provide this, the default will be `xml`.
 
-If the `.sfdecomposer.config.json` file isn't found, the hooks will be skipped.
+If `.sfdecomposer.config.json` is found, the hooks will fire:
+
+- the decompose command after a `sf project retrieve start` command completes successfully (post-run)
+- the recompose command before a `sf project deploy start` or `sf project deploy validate` command starts (pre-run)
+
+If `.sfdecomposer.config.json` isn't found, the hooks will be skipped.
 
 ## Ignore Files
 
@@ -250,7 +279,7 @@ You can use the sample [.forceignore](https://raw.githubusercontent.com/mcarvin8
 
 ### `.sfdecomposerignore`
 
-If you wish, you can create a `.sfdecomposerignore` file in the root of your repository to ignore specific XMLs when running the decompose command. The `.sfdecomposerignore` file should follow [.gitignore spec 2.22.1](https://git-scm.com/docs/gitignore).
+If you wish, you can create a `.sfdecomposerignore` file in the root of your Salesforce DX project to ignore specific XMLs when running the decompose command. The `.sfdecomposerignore` file should follow [.gitignore spec 2.22.1](https://git-scm.com/docs/gitignore).
 
 When the decompose command is ran with the `--debug` flag and it processes a file that matches an entry in `.sfdecomposerignore`, a warning will be printed to the `disassemble.log`:
 
@@ -262,18 +291,18 @@ When the decompose command is ran with the `--debug` flag and it processes a fil
 
 ### `.gitignore`
 
-Optionally, Git (or whatever version control system you are using) can ignore the recomposed files so you don't stage those in your repositories. You can also have git ignore the `disassemble.log` created by the `xml-disassembler` package.
+Optionally, git can ignore the recomposed files so you don't stage those in your repositories. You can also have git ignore the `disassemble.log` created by the `xml-disassembler` package.
 
 You can use the sample [.gitignore](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/samples/.gitignore) provided.
 
-## Contributing
-
-Contributions are welcome! See [Contributing](https://github.com/mcarvin8/sf-decomposer/blob/main/CONTRIBUTING.md).
-
 ## Issues
 
 If you encounter any bugs or would like to request features, please create an [issue](https://github.com/mcarvin8/sf-decomposer/issues).
 
+## Contributing
+
+Contributions are welcome! See [Contributing](https://github.com/mcarvin8/sf-decomposer/blob/main/CONTRIBUTING.md).
+
 ## License
 
 This project is licensed under the MIT license. Please see the [LICENSE](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/LICENSE.md) file for details.

package/oclif.lock

@@ -1596,17 +1596,17 @@
     string-width "^7.2.0"
     terminal-link "^3.0.0"
 
-"@salesforce/source-deploy-retrieve@^12.16.0":
-  version "12.16.0"
-  resolved "https://registry.yarnpkg.com/@salesforce/source-deploy-retrieve/-/source-deploy-retrieve-12.16.0.tgz#6c0338a5cd83b87161414ae4a326669d81884f60"
-  integrity sha512-vKBoefk1bHzs945e7PFhBJd21jLYJY2QrrNCwQpmHf6C3Lbu9+kzOnZVLPuDM4lGxXyhhQ89Nx3TtPCyndhmfg==
+"@salesforce/source-deploy-retrieve@^12.16.3":
+  version "12.16.3"
+  resolved "https://registry.yarnpkg.com/@salesforce/source-deploy-retrieve/-/source-deploy-retrieve-12.16.3.tgz#a299d85b29715303764cafda2ff743a2acb8d3b6"
+  integrity sha512-xGZd45VSEE72AP/5Zl1g6gm2w2ITz2zWDmcyq16PsBPbQv7fOB44BF8wH41zUqww0d1KWOdQLZ/du+I/Ew5Lmg==
   dependencies:
     "@salesforce/core" "^8.8.3"
     "@salesforce/kit" "^3.2.3"
     "@salesforce/ts-types" "^2.0.12"
     "@salesforce/types" "^1.3.0"
     fast-levenshtein "^3.0.0"
-    fast-xml-parser "^4.5.1"
+    fast-xml-parser "^4.5.3"
     got "^11.8.6"
     graceful-fs "^4.2.11"
     ignore "^5.3.2"
@@ -4111,19 +4111,19 @@ fast-xml-parser@4.2.5:
   dependencies:
     strnum "^1.0.5"
 
-fast-xml-parser@^4.5.1:
-  version "4.5.1"
-  resolved "https://registry.yarnpkg.com/fast-xml-parser/-/fast-xml-parser-4.5.1.tgz#a7e665ff79b7919100a5202f23984b6150f9b31e"
-  integrity sha512-y655CeyUQ+jj7KBbYMc4FG01V8ZQqjN+gDYGJ50RtfsUB8iG9AmwmwoAgeKLJdmueKKMrH1RJ7yXHTSoczdv5w==
+fast-xml-parser@^4.5.3:
+  version "4.5.3"
+  resolved "https://registry.yarnpkg.com/fast-xml-parser/-/fast-xml-parser-4.5.3.tgz#c54d6b35aa0f23dc1ea60b6c884340c006dc6efb"
+  integrity sha512-RKihhV+SHsIUGXObeVy9AXiBbFwkVk7Syp8XgwN5U3JV416+Gwp/GO9i0JYKmikykgz/UHRrrV4ROuZEo/T0ig==
   dependencies:
-    strnum "^1.0.5"
+    strnum "^1.1.1"
 
-fast-xml-parser@^5.0.6:
-  version "5.0.6"
-  resolved "https://registry.yarnpkg.com/fast-xml-parser/-/fast-xml-parser-5.0.6.tgz#3531c630ea334bd67b91f236117fbf439a19b21f"
-  integrity sha512-5zIl0jWsewL5LdneswG6aJXx1YH1FXQ02UVIe/CZI3wXhI3SqP62bjcIYRNOgU43/MnN1t/MCpH6UoOtBrDNug==
+fast-xml-parser@^5.0.8:
+  version "5.0.8"
+  resolved "https://registry.yarnpkg.com/fast-xml-parser/-/fast-xml-parser-5.0.8.tgz#cb84ca077c0c5c45906051c13c4075ed44d3f271"
+  integrity sha512-qY8NiI5L8ff00F2giyICiJxSSKHO52tC36LJqx2JtvGyAd5ZfehC/l4iUVVHpmpIa6sM9N5mneSLHQG2INGoHA==
   dependencies:
-    strnum "^2.0.4"
+    strnum "^2.0.5"
 
 fastest-levenshtein@^1.0.7:
   version "1.0.16"
@@ -7236,10 +7236,15 @@ strnum@^1.0.5:
   resolved "https://registry.npmjs.org/strnum/-/strnum-1.0.5.tgz"
   integrity sha512-J8bbNyKKXl5qYcR36TIO8W3mVGVHrmmxsd5PAItGkmyzwJvybiw2IVq5nqd0i4LSNSkB/sx9VHllbfFdr9k1JA==
 
-strnum@^2.0.4:
-  version "2.0.4"
-  resolved "https://registry.yarnpkg.com/strnum/-/strnum-2.0.4.tgz#7b2ace8a55d8c92a41c2d339ddb1bc306f337820"
-  integrity sha512-qrXhLMohxtEPKMlajtNaOp5zvAQUo6L3fNcdiJKzWH98kGfklqGwmxhFjM7DzxsuoVM7rJeiYr+lEcu4Jlu9UQ==
+strnum@^1.1.1:
+  version "1.1.2"
+  resolved "https://registry.yarnpkg.com/strnum/-/strnum-1.1.2.tgz#57bca4fbaa6f271081715dbc9ed7cee5493e28e4"
+  integrity sha512-vrN+B7DBIoTTZjnPNewwhx6cBA/H+IS7rfW68n7XxC1y7uoiGQBxaKzqucGUgavX15dJgiGztLJ8vxuEzwqBdA==
+
+strnum@^2.0.5:
+  version "2.0.5"
+  resolved "https://registry.yarnpkg.com/strnum/-/strnum-2.0.5.tgz#40700b1b5bf956acdc755e98e90005d7657aaaea"
+  integrity sha512-YAT3K/sgpCUxhxNMrrdhtod3jckkpYwH6JAuwmUdXZsmzH1wUyzTMrrK2wYCEEqlKwrWDd35NeuUkbBy/1iK+Q==
 
 supports-color@^5.3.0:
   version "5.5.0"
@@ -7809,12 +7814,12 @@ write-file-atomic@^3.0.0:
     signal-exit "^3.0.2"
     typedarray-to-buffer "^3.1.5"
 
-xml-disassembler@^1.3.12:
-  version "1.3.12"
-  resolved "https://registry.yarnpkg.com/xml-disassembler/-/xml-disassembler-1.3.12.tgz#f3fa2ea6573e815c20e6ca2e7a758dfe68a7b807"
-  integrity sha512-P/aApcGRfq568GHwNBQDqdsKq686rwX03ZusyDugbokxd7CDPB5AXBP79bdrJWdKV4k6l/dHBfRwMzJ/kgcNbg==
+xml-disassembler@^1.3.13:
+  version "1.3.13"
+  resolved "https://registry.yarnpkg.com/xml-disassembler/-/xml-disassembler-1.3.13.tgz#fade68d62add9992340b94b6e4537bc040333c87"
+  integrity sha512-qjfNcTNSAXbLDErLw6hlckpm9ARQDQDJ+CMDFPV2LrheMUhlDF3Z4vZKSNBWyTrb+4PgUOTpGXnXRpgFPtcO9Q==
   dependencies:
-    fast-xml-parser "^5.0.6"
+    fast-xml-parser "^5.0.8"
     ignore "^5.3.1"
     log4js "^6.9.1"
     tslib "^2.6.2"
@@ -7827,21 +7832,21 @@ xml2js@^0.6.2:
     sax ">=0.6.0"
     xmlbuilder "~11.0.0"
 
-xml2json-disassembler@^1.1.12:
-  version "1.1.12"
-  resolved "https://registry.yarnpkg.com/xml2json-disassembler/-/xml2json-disassembler-1.1.12.tgz#b7feba01bd575f9d68e1fc0341ab0b3f5d09b4fc"
-  integrity sha512-YQJd7XPdq8pxLZK++Ld6GGOowQalZsarg3UXh2GA4RwM6yPL4vpKPW6kFE3aa9llsHDgpBVZH3TYoirtfAWvUA==
+xml2json-disassembler@^1.1.13:
+  version "1.1.13"
+  resolved "https://registry.yarnpkg.com/xml2json-disassembler/-/xml2json-disassembler-1.1.13.tgz#04f8577fda4bbcbf5c167d5320b6ed88e46f75c7"
+  integrity sha512-YWIybFAJ59yiuUbQ+DgeJ/aOd5ACfVquCmZNbMlqJGlqVhON3IUCJ8SPyhfRJwuuJScAbBBbi+kXrhI8KMRz7w==
   dependencies:
     tslib "^2.6.2"
-    xml-disassembler "^1.3.12"
+    xml-disassembler "^1.3.13"
 
-xml2yaml-disassembler@^1.1.12:
-  version "1.1.12"
-  resolved "https://registry.yarnpkg.com/xml2yaml-disassembler/-/xml2yaml-disassembler-1.1.12.tgz#3f933b33a4f6a30b19e43277890be7914fa6b096"
-  integrity sha512-BpTbiJsECMWxDme/ZwkVsDkDQuGXb14YswViajIWkNOMnzH6/8ITUqLMUsL0GGajufhM9a3+xNiZF0k/9Kzk5A==
+xml2yaml-disassembler@^1.1.13:
+  version "1.1.13"
+  resolved "https://registry.yarnpkg.com/xml2yaml-disassembler/-/xml2yaml-disassembler-1.1.13.tgz#8c524cacce2f6741691e2958c3fab25fa4479195"
+  integrity sha512-itP9OrE77LRNqWbsU0Fs6rJJT59R1k0lqY6+ycm4IZKITMSvnCVFznbCaZ6EUv+GvDZd73+hreO4so6vcqDRDw==
   dependencies:
     tslib "^2.6.2"
-    xml-disassembler "^1.3.12"
+    xml-disassembler "^1.3.13"
     yaml "^2.7.0"
 
 xmlbuilder@~11.0.0:

package/oclif.manifest.json

@@ -198,5 +198,5 @@
       ]
     }
   },
-  "version": "5.3.12"
+  "version": "5.3.13"
 }

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "sf-decomposer",
   "description": "Break down large Salesforce metadata files into smaller, more manageable files for version control and then recreate deployment-compatible files.",
-  "version": "5.3.12",
+  "version": "5.3.13",
   "dependencies": {
     "@oclif/core": "^4",
     "@salesforce/core": "^8.2.1",
     "@salesforce/sf-plugins-core": "^11.2.1",
-    "@salesforce/source-deploy-retrieve": "^12.16.0",
+    "@salesforce/source-deploy-retrieve": "^12.16.3",
     "fs-extra": "^11.2.0",
-    "xml-disassembler": "^1.3.12",
-    "xml2json-disassembler": "^1.1.12",
-    "xml2yaml-disassembler": "^1.1.12"
+    "xml-disassembler": "^1.3.13",
+    "xml2json-disassembler": "^1.1.13",
+    "xml2yaml-disassembler": "^1.1.13"
   },
   "devDependencies": {
     "@commitlint/cli": "^18.6.1",