sf-decomposer 6.33.1 → 6.34.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@
 
 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.
 
+## [6.34.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.33.2...v6.34.0) (2026-06-30)
+
+
+### Features
+
+* add sidecar elements support for XML decompose/recompose ([#507](https://github.com/mcarvin8/sf-decomposer/issues/507)) ([76fb5a8](https://github.com/mcarvin8/sf-decomposer/commit/76fb5a8ca1293ed1d32213682342af6c52d4599c))
+
+## [6.33.2](https://github.com/mcarvin8/sf-decomposer/compare/v6.33.1...v6.33.2) (2026-06-29)
+
+
+### Bug Fixes
+
+* **deps:** bump all deps, drop Node 20 support ([#505](https://github.com/mcarvin8/sf-decomposer/issues/505)) ([7425c87](https://github.com/mcarvin8/sf-decomposer/commit/7425c87c24721ab8e41938ed6fb85792ef56dff4))
+
 ## [6.33.1](https://github.com/mcarvin8/sf-decomposer/compare/v6.33.0...v6.33.1) (2026-06-25)
 
 
@@ -335,8 +349,8 @@ All notable changes to this project will be documented in this file. See [standa
 
 ### ⚠ BREAKING CHANGES
 
-* Remove --debug flag and disassemble.log file 
-* Remove INI and TOML formats from decompose 
+* Remove --debug flag and disassemble.log file
+* Remove INI and TOML formats from decompose
 * Re-decompose files to include updated key config JSONs from rust crate
 
 ### Features

package/HANDBOOK.md

@@ -12,6 +12,7 @@ If you want the underlying option grammar instead of recipes, see the [main READ
 
 - [Choosing a strategy](#choosing-a-strategy)
 - [Common pitfalls](#common-pitfalls)
+- [ExternalServiceRegistration (ESR / OpenAPI schema)](#externalserviceregistration-esr--openapi-schema)
 - [Bots (Agentforce and Einstein)](#bots-agentforce-and-einstein)
 - [Flexipages (Lightning App / Record / Home pages)](#flexipages-lightning-app--record--home-pages)
 - [Layouts (page layouts)](#layouts-page-layouts)
@@ -23,7 +24,7 @@ If you want the underlying option grammar instead of recipes, see the [main READ
 Three knobs cover almost every case:
 
 | Symptom of the source XML                                                                     | Reach for                                                                                          |
-| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+|-----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
 | One repeating section at the top level (e.g. `<labels>` of a custom-labels file).             | `strategy: unique-id` (default).                                                                   |
 | Lots of small repeatable tags, you want one file per tag-name, not per-instance.              | `strategy: grouped-by-tag`.                                                                        |
 | `grouped-by-tag`, but a few specific tags (e.g. `objectPermissions`) need finer-grained diff. | Add `splitTags`.                                                                                   |
@@ -31,12 +32,13 @@ Three knobs cover almost every case:
 
 Hard rules the plugin always enforces (so you don't have to):
 
-- `labels` and `loyaltyProgramSetup` are always treated as `unique-id` regardless of any override.
+- `labels`, `loyaltyProgramSetup`, and `externalServiceRegistration` are always treated as `unique-id` regardless of any override.
+- `externalServiceRegistration` always applies sidecar extraction for the `<schema>` element (written to `<componentName>.yaml`). No config needed.
 
 Built-in `multiLevel` defaults — applied automatically when `strategy` is `unique-id` and you do not supply your own `multiLevel` for that type. You can replace any of them by setting an explicit `multiLevel` on the override.
 
 | Metadata type         | Built-in `multiLevel`                                               |
-| --------------------- | ------------------------------------------------------------------- |
+|-----------------------|---------------------------------------------------------------------|
 | `bot`                 | `["botDialogs:botDialogs:developerName", "botSteps:botSteps:type"]` |
 | `loyaltyProgramSetup` | `"programProcesses:programProcesses:parameterName,ruleName"`        |
 
@@ -64,6 +66,48 @@ There are two distinct causes; run the decompose under `RUST_LOG=warn` to tell t
 - **No `WARN` line.** Your `unique_id_elements` (or the rule's third part) didn't resolve to a non-empty value on those items. Check the source XML for the elements you listed — names are case-sensitive and live at the immediate child level of each repeating item. The plugin only walks one level deep when picking a UID.
 - **A `WARN` line of the form `uniqueIdElements collision: <parentTag> id "X" matched N sibling elements`.** The configured key is too narrow — multiple siblings legitimately share the same value, so the collision detector falls back to per-element SHA-256 hashes for that group rather than overwrite. Add a tiebreaker to `unique_id_elements` (e.g. a compound like `name+recordType`) and re-decompose with `prePurge: true`.
 
+## ExternalServiceRegistration (ESR / OpenAPI schema)
+
+**Why this is hard.** An `ExternalServiceRegistration` embeds its full OpenAPI (or other) schema document as raw text inside a `<schema>` XML element. This block can be hundreds of lines of YAML or JSON. Storing it inline in the `.externalServiceRegistration-meta.xml` file produces large, noisy diffs whenever the schema changes.
+
+**What the plugin does automatically.** No config is needed. The plugin applies these rules to every ESR component:
+
+- **Forced `unique-id` strategy** — grouped-by-tag is a no-op for singleton-per-component types and is silently upgraded.
+- **Sidecar extraction** — the `<schema>` element's text content is extracted to `<componentName>.yaml` alongside the decomposed XML shards, and a `.sidecars.json` manifest is written to record the extraction.
+- **Auto-detect on recompose** — recompose reads `.sidecars.json` and reinserts the schema content into `<schema>` before writing the final XML. No recompose flag is needed.
+
+**On-disk layout** for `DropboxFileManagerHandler.externalServiceRegistration-meta.xml`:
+
+```
+externalServiceRegistrations/
+└── DropboxFileManagerHandler/
+    ├── DropboxFileManagerHandler.yaml        ← extracted <schema> content
+    ├── .sidecars.json                        ← sidecar manifest; do not hand-edit
+    └── DropboxFileManagerHandler/            ← unique-id decomposed XML shards
+        ├── description.externalServiceRegistration-meta.xml
+        ├── label.externalServiceRegistration-meta.xml
+        ├── schema.externalServiceRegistration-meta.xml  ← placeholder (empty text)
+        ├── status.externalServiceRegistration-meta.xml
+        ├── operations/
+        │   └── uploadFile.operations-meta.xml
+        └── ...
+```
+
+**Override example.** Only needed if you want a different extension for the schema file (e.g. `json`):
+
+```json
+{
+  "overrides": [
+    {
+      "metadataTypes": ["externalServiceRegistration"],
+      "sidecarElements": "schema:json"
+    }
+  ]
+}
+```
+
+> **Conflict with Salesforce native decomposition.** Salesforce CLI also decomposes `ExternalServiceRegistration` natively. Never use both on the same type in the same project. See [METADATA_SUPPORT.md](./METADATA_SUPPORT.md) for guidance.
+
 ## Bots (Agentforce and Einstein)
 
 **Why this is hard.** Agentforce and Einstein bots both ship as `.bot-meta.xml`, but their internals diverge:
@@ -264,13 +308,14 @@ layouts/
 
 These follow the same pattern; pick the rules that match your repo's data. None of these are decomposed natively by Salesforce.
 
-| Metadata type                              | Suggested override                                                                                 |
-| ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
-| `flow`                                     | `multiLevel: ["actionCalls:actionCalls:name", "decisions:decisions:name", "rules:rules:name"]`     |
-| `globalValueSet`                           | `multiLevel: ["customValue:customValue:fullName"]` — handy when value sets have hundreds of picks. |
-| `marketingappextension`                    | `multiLevel: ["activityDefinitions:activityDefinitions:apiName"]`                                  |
-| `cmsDeliveryChannel` (and other CMS types) | `strategy: grouped-by-tag` plus `splitTags` for any wide repeatable tag.                           |
-| `dashboard`                                | `multiLevel: ["components:components:title"]` — one file per dashboard widget.                     |
+| Metadata type                              | Suggested override                                                                                                                                                                                                                                        |
+|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `flow`                                     | `multiLevel: ["actionCalls:actionCalls:name", "decisions:decisions:name", "rules:rules:name"]`                                                                                                                                                            |
+| `globalValueSet`                           | `multiLevel: ["customValue:customValue:fullName"]` — handy when value sets have hundreds of picks.                                                                                                                                                        |
+| `field` (CustomField)                      | `multiLevel: "valueSet:valueSetDefinition:fullName"` — splits each picklist value into its own file. Only effective on fields that define picklist values inline; fields referencing a global value set or non-picklist fields are leaf-only and skipped. |
+| `marketingappextension`                    | `multiLevel: ["activityDefinitions:activityDefinitions:apiName"]`                                                                                                                                                                                         |
+| `cmsDeliveryChannel` (and other CMS types) | `strategy: grouped-by-tag` plus `splitTags` for any wide repeatable tag.                                                                                                                                                                                  |
+| `dashboard`                                | `multiLevel: ["components:components:title"]` — one file per dashboard widget.                                                                                                                                                                            |
 
 If a metadata type has a single deeply-nested repeatable block, a one-rule `multiLevel` is enough. Reach for the array form only when you have **two or more** distinct nested sections you want addressable on disk.