sf-decomposer 6.11.0 → 6.13.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@
 
 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.13.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.12.0...v6.13.0) (2026-04-30)
+
+
+### Features
+
+* **decompose:** add per-component overrides ([#415](https://github.com/mcarvin8/sf-decomposer/issues/415)) ([47d7c79](https://github.com/mcarvin8/sf-decomposer/commit/47d7c794db17ccc59e832309a0a4980d736ab89c))
+* **deps:** bump dependabot/fetch-metadata from 2 to 3 ([#412](https://github.com/mcarvin8/sf-decomposer/issues/412)) ([6b0a24b](https://github.com/mcarvin8/sf-decomposer/commit/6b0a24b9c83dfb6fb9ef1d8dc8e2dfbec23200bf))
+* **metadata:** bump @salesforce/source-deploy-retrieve ([#413](https://github.com/mcarvin8/sf-decomposer/issues/413)) ([e261049](https://github.com/mcarvin8/sf-decomposer/commit/e261049cc07a94642c1e80cf29dbd1e96a7183bd))
+
+## [6.12.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.11.0...v6.12.0) (2026-04-27)
+
+
+### Features
+
+* add per-metadata-type overrides for decompose ([#407](https://github.com/mcarvin8/sf-decomposer/issues/407)) ([43be31d](https://github.com/mcarvin8/sf-decomposer/commit/43be31d6190e095a0dbc5b763e2439582c5b4214))
+
 ## [6.11.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.10.0...v6.11.0) (2026-04-24)
 
 

package/README.md

@@ -26,6 +26,7 @@ A Salesforce CLI plugin that **decomposes** large metadata XML files into smalle
   - [Exceptions](#exceptions)
 - [Troubleshooting](#troubleshooting)
 - [Hooks](#hooks)
+- [Per-Type & Per-Component Overrides](#per-type--per-component-overrides)
 - [Ignore Files](#ignore-files)
   - [.forceignore](#forceignore)
   - [.sfdecomposerignore](#sfdecomposerignore)
@@ -78,7 +79,7 @@ A Salesforce CLI plugin that **decomposes** large metadata XML files into smalle
 
 ## Requirements
 
-The [xml-disassembler](https://github.com/mcarvin8/xml-disassembler) NodeJS dependency, which depends on a Rust crate, ships with native binaries for these platforms:
+The [config-disassembler-node](https://github.com/mcarvin8/config-disassembler-node) package, which depends on a Rust crate, ships with native binaries for these platforms:
 
 | Platform    | Architectures                      |
 | ----------- | ---------------------------------- |
@@ -86,7 +87,7 @@ The [xml-disassembler](https://github.com/mcarvin8/xml-disassembler) NodeJS depe
 | **Linux**   | x64, arm64, ia32                   |
 | **Windows** | x64                                |
 
-If other platforms or architectures require support, please open an issue in the [Rust repository](https://github.com/mcarvin8/xml-disassembler-rust).
+If other platforms or architectures require support, please open an issue in [config-disassembler-node](https://github.com/mcarvin8/config-disassembler-node/issues).
 
 ---
 
@@ -123,7 +124,7 @@ Decomposes metadata in all local package directories (from `sfdx-project.json`)
 
 ```
 USAGE
-  $ sf decomposer decompose [-m <value>] [-x <value>] [-f <value>] [-i <value>] [-s <value>] [--prepurge --postpurge -p --json]
+  $ sf decomposer decompose [-m <value>] [-x <value>] [-f <value>] [-i <value>] [-s <value>] [--prepurge --postpurge -p -c --json]
 
 FLAGS
   -m, --metadata-type=<value>             Metadata suffix to process (e.g. flow, labels). Repeatable. Optional when --manifest is provided.
@@ -134,6 +135,7 @@ FLAGS
   --prepurge                              Remove existing decomposed files before decomposing [default: false]
   --postpurge                             Remove original metadata files after decomposing [default: false]
   -p, --decompose-nested-permissions      With grouped-by-tag, further decompose permission set and muting permission set object/field permissions
+  -c, --config                            Load per-type and per-component overrides from .sfdecomposer.config.json in the repo root. Only the "overrides" array is consumed. See Per-Type & Per-Component Overrides. [default: false]
 
 GLOBAL FLAGS
   --json  Output as JSON.
@@ -230,7 +232,7 @@ sf project deploy start -x "manifest/package.xml"
 
 ## Decompose Strategies
 
-> **Important:** Use one strategy per metadata type. To switch from `unique-id` to `grouped-by-tag`, run decompose with `--prepurge` and `-s "grouped-by-tag"` to regenerate.
+> **Tip:** A single decompose run can mix strategies and formats across metadata types — and even across components within the same type — through the `overrides` array (see [Per-Type & Per-Component Overrides](#per-type--per-component-overrides)). Recompose is deterministic from the on-disk sidecar, so any combination round-trips. When switching strategies for an existing component, pass `--prepurge` (or set `prePurge: true`) so leftover files from the previous strategy are removed before the new ones are written.
 
 - **unique-id** (default): Each nested element goes to its own file, named by unique-id fields or content hash. Leaf elements stay in a file named like the original XML.
 - **grouped-by-tag**: All elements with the same tag (e.g. `<fieldPermissions>`) go into one file named after the tag (e.g. `fieldPermissions.xml`). Leaf elements are still grouped in the original-named file.
@@ -332,14 +334,14 @@ For example, if you attempt to decompose Custom Labels but none of your package
 
 ### XML disassemble output (Rust crate)
 
-The xml-disassembler Node plugin uses a **Rust crate** for XML decomposing and recomposing. Disassemble errors and messages are shown in the terminal.
+The config-disassembler Node plugin uses a **Rust crate** for XML decomposing and recomposing. Disassemble errors and messages are shown in the terminal.
 
 Control verbosity with the `RUST_LOG` environment variable (e.g. `RUST_LOG=debug` for detailed output).
 
 Example output in the terminal (Rust log format):
 
 ```
-[2026-02-11T22:52:32Z ERROR xml_disassembler::builders::build_disassembled_files] The XML file C:\Users\matthew.carvin\Documents\sf-decomposer\fixtures\package-dir-1\permissionsets\only_leafs.permissionset-meta.xml only has leaf elements. This file will not be disassembled.
+[2026-04-30T12:34:38Z ERROR config_disassembler::xml::builders::build_disassembled_files] The XML file C:\Users\matthew.carvin\Documents\sf-decomposer\fixtures\package-dir-1\permissionsets\only_leafs.permissionset-meta.xml only has leaf elements. This file will not be disassembled.
 ```
 
 ### Files with only leaf elements
@@ -357,18 +359,101 @@ Put **.sfdecomposer.config.json** in the project root to run:
 - **After** `sf project retrieve start`: decompose.
 - **Before** `sf project deploy start` / `sf project deploy validate`: recompose.
 
-Copy and customize the [sample config](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/examples/.sfdecomposer.config.json).
+Copy and customize the [sample config](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/examples/.sfdecomposer.config.json), or the [sample config with overrides](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/examples/.sfdecomposer.config.overrides.json) to vary format/strategy/etc. by metadata type or by individual component.
 
-| Option                       | Required    | Description                                                                                                                                                       |
-| ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `metadataSuffixes`           | Conditional | Comma-separated metadata suffixes to decompose/recompose. Required unless `manifest` is set; when both are set, the run is scoped to the intersection.            |
-| `manifest`                   | Conditional | Path (relative to the project root) to a `package.xml` manifest. When set, only the components listed in the manifest are decomposed/recomposed. See `-x` above. |
-| `ignorePackageDirectories`   | No          | Comma-separated package directories to skip.                                                                                                                      |
-| `prePurge`                   | No          | Remove existing decomposed files before decomposing (default: false).                                                                                             |
-| `postPurge`                  | No          | After decompose: remove originals; after recompose: remove decomposed files (default: false).                                                                     |
-| `decomposedFormat`           | No          | xml, json, json5, or yaml (default: xml).                                                                                                                         |
-| `strategy`                   | No          | `unique-id` \| `grouped-by-tag` (default: unique-id).                                                                                                             |
-| `decomposeNestedPermissions` | No          | With grouped-by-tag, set true to further decompose permission set and muting permission set object/field permissions.                                             |
+| Option                       | Required    | Description                                                                                                                                                                                                                   |
+| ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `metadataSuffixes`           | Conditional | Comma-separated metadata suffixes to decompose/recompose. Required unless `manifest` is set; when both are set, the run is scoped to the intersection.                                                                        |
+| `manifest`                   | Conditional | Path (relative to the project root) to a `package.xml` manifest. When set, only the components listed in the manifest are decomposed/recomposed. See `-x` above.                                                              |
+| `ignorePackageDirectories`   | No          | Comma-separated package directories to skip.                                                                                                                                                                                  |
+| `prePurge`                   | No          | Remove existing decomposed files before decomposing (default: false).                                                                                                                                                         |
+| `postPurge`                  | No          | After decompose: remove originals; after recompose: remove decomposed files (default: false).                                                                                                                                 |
+| `decomposedFormat`           | No          | xml, json, json5, or yaml (default: xml).                                                                                                                                                                                     |
+| `strategy`                   | No          | `unique-id` \| `grouped-by-tag` (default: unique-id).                                                                                                                                                                         |
+| `decomposeNestedPermissions` | No          | With grouped-by-tag, set true to further decompose permission set and muting permission set object/field permissions.                                                                                                         |
+| `overrides`                  | No          | Array of per-type and/or per-component overrides for `decomposedFormat`, `strategy`, `decomposeNestedPermissions`, `prePurge`, and `postPurge`. See [Per-Type & Per-Component Overrides](#per-type--per-component-overrides). |
+
+---
+
+## Per-Type & Per-Component Overrides
+
+Overrides apply to **decompose only**. Recompose is a deterministic round-trip — it auto-detects format from the on-disk files and does not depend on strategy — so it ignores the `overrides` array.
+
+By default, a single decompose run uses one format and one strategy across every metadata type. The optional `overrides` array in `.sfdecomposer.config.json` lets you vary a small set of options per metadata suffix (**type-scope**) or per individual SDR component (**component-scope**) without splitting the run into multiple invocations.
+
+```json
+{
+  "metadataSuffixes": "labels,workflow,profile,flow,permissionset",
+  "ignorePackageDirectories": "force-app,examples",
+  "prePurge": true,
+  "postPurge": true,
+  "decomposedFormat": "xml",
+  "strategy": "unique-id",
+  "overrides": [
+    { "metadataTypes": ["flow"], "decomposedFormat": "yaml" },
+    {
+      "metadataTypes": ["permissionset", "mutingpermissionset"],
+      "strategy": "grouped-by-tag",
+      "decomposeNestedPermissions": true
+    },
+    {
+      "components": ["permissionset:HR_Admin", "permissionset:Big_PermSet"],
+      "strategy": "grouped-by-tag",
+      "decomposeNestedPermissions": true
+    }
+  ]
+}
+```
+
+### What can be overridden
+
+| Field                        | Notes                                                                                                                                                                                                          |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `metadataTypes`              | Optional (required if `components` is omitted). Array of metadata suffixes (same vocabulary as `--metadata-type` / `metadataSuffixes`). Each suffix may appear in at most one override.                        |
+| `components`                 | Optional (required if `metadataTypes` is omitted). Array of `<metadataSuffix>:<fullName>` keys (e.g. `permissionset:HR_Admin`, `report:MyFolder/MyReport`). Each component may appear in at most one override. |
+| `decomposedFormat`           | `xml` \| `json` \| `json5` \| `yaml`.                                                                                                                                                                          |
+| `strategy`                   | `unique-id` \| `grouped-by-tag`. Hard rules still win — `labels` and `loyaltyProgramSetup` are always treated as `unique-id`.                                                                                  |
+| `decomposeNestedPermissions` | Only applies to `permissionset` / `mutingpermissionset` with `grouped-by-tag`.                                                                                                                                 |
+| `prePurge`                   | Per-scope prePurge (decompose). Component-scope `prePurge` only purges the named component's decomposed directory.                                                                                             |
+| `postPurge`                  | Per-scope postPurge (decompose: remove originals after decomposing).                                                                                                                                           |
+
+Run-scope options (`metadataSuffixes`, `manifest`, `ignorePackageDirectories`) are **not** valid inside an override; the plugin will throw if they are present.
+
+#### Component key conventions
+
+The `<fullName>` part of a component key is the SDR fullName for the component, matching the basename of the decomposed directory:
+
+- **Plain types** (e.g. `permissionset`, `flow`, `profile`, `workflow`): use the file stem, e.g. `permissionset:HR_Admin` for `permissionsets/HR_Admin.permissionset-meta.xml`.
+- **Strict-directory types** (e.g. `bot`): use the bot directory name, e.g. `bot:My_Bot` for `bots/My_Bot/My_Bot.bot-meta.xml`.
+- **Folder-typed metadata** (e.g. `report`, `dashboard`, `email`, `document`): the unit of decomposition is the folder; use the folder name, e.g. `report:MyFolder` to scope every report inside `reports/MyFolder/`.
+- **`labels`**: there is exactly one labels file per labels directory, so component-scope keys are not meaningful — use the type-scope `metadataTypes: ["labels"]` instead.
+
+Component overrides are not a filter. If `--metadata` / `metadataSuffixes` includes `permissionset`, every permission set is still decomposed; the override only changes how the named ones are decomposed. Use `--manifest` / the hook's `manifest` field if you want to scope the run itself to a subset of components.
+
+### Precedence
+
+For each component, each option is resolved independently in this order (highest first):
+
+1. The component-scope override value (matching `<suffix>:<fullName>` in `components`), if set.
+2. The type-scope override value (matching `<suffix>` in `metadataTypes`), if set.
+3. The run-wide value (CLI flag, hook config top-level field, or built-in default).
+4. Hard plugin rules (e.g. `labels` and `loyaltyProgramSetup` forced to `unique-id`) override all of the above.
+
+### Opting in from the CLI
+
+CLI users can opt into overrides on `decompose` with the boolean `--config` (`-c`) flag. When set, the plugin reads `.sfdecomposer.config.json` from the repo root (the nearest ancestor directory that contains `sfdx-project.json`):
+
+```bash
+sf decomposer decompose -m "flow" -m "permissionset" -c
+```
+
+When `--config` is set, **only** the `overrides` array is consumed from the file. Top-level fields like `decomposedFormat`, `strategy`, `metadataSuffixes`, etc. are ignored — the CLI flags remain the source of truth for run-wide values. This keeps direct CLI behavior predictable and lets you reuse the same config file as the post-retrieve hook without any surprises.
+
+If `--config` is set but `.sfdecomposer.config.json` is missing from the repo root, the command fails with a clear error.
+
+`recompose` does not accept `--config` because it does not need the override information — format is auto-detected from the decomposed files on disk and recompose does not depend on strategy.
+
+The post-retrieve hook automatically picks up `overrides` from `.sfdecomposer.config.json` — no extra setup required. Existing config files without an `overrides` field continue to behave exactly as before.
 
 ---
 
@@ -396,8 +481,7 @@ Bugs and feature requests: [open an issue](https://github.com/mcarvin8/sf-decomp
 
 ## Built With
 
-- [xml-disassembler](https://github.com/mcarvin8/xml-disassembler) – Disassemble XML into smaller, manageable files and reassemble when needed. Node.js + Rust (Neon). Includes prebuilt binaries for macOS (x64, arm64), Linux (x64, arm64, ia32), and Windows (x64).
-- [fs-extra](https://github.com/jprichardson/node-fs-extra) – Node.js: extra methods for the `fs` object like copy(), remove(), mkdirs().
+- [config-disassembler-node](https://github.com/mcarvin8/config-disassembler-node) – Disassemble XML (and other config formats) into smaller, manageable files and reassemble when needed. Node.js + Rust (Neon). See [Requirements](#requirements).
 - [@salesforce/source-deploy-retrieve](https://github.com/forcedotcom/source-deploy-retrieve) – JavaScript toolkit for working with Salesforce metadata.
 
 ---
@@ -408,4 +492,4 @@ Contributions are welcome. See [CONTRIBUTING.md](https://github.com/mcarvin8/sf-
 
 ## License
 
-MIT. See [LICENSE](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/LICENSE.md).
+[MIT](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/LICENSE.md)

package/lib/commands/decomposer/decompose.d.ts

@@ -13,6 +13,7 @@ export default class DecomposerDecompose extends SfCommand<DecomposerResult> {
         'ignore-package-directory': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         strategy: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'decompose-nested-permissions': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        config: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<DecomposerResult>;
 }

package/lib/commands/decomposer/decompose.js

@@ -3,6 +3,7 @@ import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
 import { Messages } from '@salesforce/core';
 import { DECOMPOSED_FILE_TYPES, DECOMPOSED_STRATEGIES } from '../../helpers/constants.js';
 import { decomposeMetadataTypes } from '../../core/decomposeMetadataTypes.js';
+import { loadOverridesFromConfig, resolveDefaultConfigPath } from '../../helpers/configOverrides.js';
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('sf-decomposer', 'decomposer.decompose');
 export default class DecomposerDecompose extends SfCommand {
@@ -60,12 +61,19 @@ export default class DecomposerDecompose extends SfCommand {
             required: false,
             default: false,
         }),
+        config: Flags.boolean({
+            summary: messages.getMessage('flags.config.summary'),
+            char: 'c',
+            required: false,
+            default: false,
+        }),
     };
     async run() {
         const { flags } = await this.parse(DecomposerDecompose);
         if (!flags['metadata-type'] && !flags['manifest']) {
             throw messages.createError('error.missingMetadataOrManifest');
         }
+        const overrides = flags['config'] ? await loadOverridesFromConfig(await resolveDefaultConfigPath()) : undefined;
         return decomposeMetadataTypes({
             metadataTypes: flags['metadata-type'],
             prepurge: flags['prepurge'],
@@ -75,6 +83,7 @@ export default class DecomposerDecompose extends SfCommand {
             strategy: flags['strategy'],
             decomposeNestedPerms: flags['decompose-nested-permissions'],
             manifest: flags['manifest'],
+            overrides,
             log: this.log.bind(this),
         });
     }

package/lib/commands/decomposer/decompose.js.map

@@ -1 +1 @@
-{"version":3,"file":"decompose.js","sourceRoot":"","sources":["../../../src/commands/decomposer/decompose.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decompose.js","sourceRoot":"","sources":["../../../src/commands/decomposer/decompose.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAC1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAGrG,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC;AAEhF,MAAM,CAAC,OAAO,OAAO,mBAAoB,SAAQ,SAA2B;IACnE,MAAM,CAAmB,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAClE,MAAM,CAAmB,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IAC1E,MAAM,CAAmB,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAErE,MAAM,CAAmB,KAAK,GAAG;QACtC,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC;YAC5B,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,6BAA6B,CAAC;YAC3D,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,KAAK;SAChB,CAAC;QACF,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC;YACnB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,wBAAwB,CAAC;YACtD,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,IAAI;SACb,CAAC;QACF,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC;YACtB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,wBAAwB,CAAC;YACtD,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;SACf,CAAC;QACF,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;YACvB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,yBAAyB,CAAC;YACvD,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;SACf,CAAC;QACF,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;YACnB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,sBAAsB,CAAC;YACpD,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,qBAAqB;SAC/B,CAAC;QACF,0BAA0B,EAAE,KAAK,CAAC,SAAS,CAAC;YAC1C,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,wCAAwC,CAAC;YACtE,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,KAAK;YACf,QAAQ,EAAE,IAAI;SACf,CAAC;QACF,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC;YACrB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,wBAAwB,CAAC;YACtD,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,WAAW;YACpB,OAAO,EAAE,qBAAqB;SAC/B,CAAC;QACF,8BAA8B,EAAE,KAAK,CAAC,OAAO,CAAC;YAC5C,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,4CAA4C,CAAC;YAC1E,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;SACf,CAAC;QACF,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC;YACpB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,sBAAsB,CAAC;YACpD,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;SACf,CAAC;KACH,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAExD,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;YAClD,MAAM,QAAQ,CAAC,WAAW,CAAC,iCAAiC,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,uBAAuB,CAAC,MAAM,wBAAwB,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEhH,OAAO,sBAAsB,CAAC;YAC5B,aAAa,EAAE,KAAK,CAAC,eAAe,CAAC;YACrC,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC;YAC3B,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC;YAC7B,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC;YACvB,UAAU,EAAE,KAAK,CAAC,0BAA0B,CAAC;YAC7C,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC;YAC3B,oBAAoB,EAAE,KAAK,CAAC,8BAA8B,CAAC;YAC3D,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC;YAC3B,SAAS;YACT,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;SACzB,CAAC,CAAC;IACL,CAAC"}

package/lib/core/decomposeMetadataTypes.js

@@ -4,8 +4,9 @@ import { getRegistryValuesBySuffix } from '../metadata/getRegistryValuesBySuffix
 import { parseManifest } from '../metadata/parseManifest.js';
 import { decomposeFileHandler } from '../service/decompose/decomposeFileHandler.js';
 import { CONCURRENCY_LIMITS } from '../helpers/constants.js';
+import { resolveDecomposeOptionsForType } from '../helpers/configOverrides.js';
 export async function decomposeMetadataTypes(options) {
-    const { metadataTypes, prepurge, postpurge, format, ignoreDirs, strategy, decomposeNestedPerms, manifest, log } = options;
+    const { metadataTypes, prepurge, postpurge, format, ignoreDirs, strategy, decomposeNestedPerms, manifest, overrides, log, } = options;
     let manifestFilter;
     let effectiveTypes;
     if (manifest) {
@@ -47,14 +48,12 @@ export async function decomposeMetadataTypes(options) {
             log(`Skipping ${metadataType}: ${message}`);
             return;
         }
-        let effectiveStrategy = strategy;
-        if (metadataType === 'labels' && strategy === 'grouped-by-tag') {
-            effectiveStrategy = 'unique-id';
-        }
-        if (metadataType === 'loyaltyProgramSetup' && strategy === 'grouped-by-tag') {
-            effectiveStrategy = 'unique-id';
-        }
-        await decomposeFileHandler(metaAttributes, prepurge, postpurge, format, ignorePath, effectiveStrategy, decomposeNestedPerms, manifestXmlPaths);
+        // Type-scope resolved options serve as the base for component-scope resolution further
+        // down the call stack. Hard strategy rules (labels / loyaltyProgramSetup) are applied per
+        // file inside the disassembler so they remain in force even when a component-scope override
+        // tries to flip the strategy.
+        const typeResolved = resolveDecomposeOptionsForType(metadataType, { format, strategy, decomposeNestedPerms, prepurge, postpurge }, overrides);
+        await decomposeFileHandler(metaAttributes, typeResolved, ignorePath, overrides, manifestXmlPaths);
         processed.push(metadataType);
         log(`All metadata files have been decomposed for the metadata type: ${metadataType}`);
     }));

package/lib/core/decomposeMetadataTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"decomposeMetadataTypes.js","sourceRoot":"","sources":["../../src/core/decomposeMetadataTypes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decomposeMetadataTypes.js","sourceRoot":"","sources":["../../src/core/decomposeMetadataTypes.ts"],"names":[],"mappings":"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"}

package/lib/helpers/configOverrides.d.ts

@@ -0,0 +1,62 @@
+import { DecomposerOverride } from './types.js';
+/**
+ * Resolve the absolute path of the default `.sfdecomposer.config.json`, located in the
+ * repo root (the nearest ancestor directory that contains `sfdx-project.json`). Throws
+ * a clear error when the repo root cannot be located or the config file does not exist.
+ */
+export declare function resolveDefaultConfigPath(): Promise<string>;
+export type ResolvedDecomposeTypeOptions = {
+    format: string;
+    strategy: string;
+    decomposeNestedPerms: boolean;
+    prepurge: boolean;
+    postpurge: boolean;
+};
+/**
+ * Load and validate the `overrides` array from a `.sfdecomposer.config.json` file.
+ * Returns an empty array if the file is missing, unreadable, or contains no overrides.
+ */
+export declare function loadOverridesFromConfig(configPath: string): Promise<DecomposerOverride[]>;
+/**
+ * Validate that the overrides array is well-formed. Throws on any structural problem.
+ * Unknown override keys are tolerated (ignored), but forbidden run-scope keys throw.
+ */
+export declare function validateOverrides(overrides: DecomposerOverride[]): void;
+/**
+ * Parse a component override key of the form `<metadataSuffix>:<fullName>`. Returns `undefined`
+ * when the key is malformed. Only the first colon is treated as the delimiter so fullNames that
+ * contain `/` (folder-typed metadata such as `report:MyFolder/MyReport`) are preserved verbatim.
+ */
+export declare function parseComponentKey(key: string): {
+    metadataType: string;
+    fullName: string;
+} | undefined;
+/**
+ * Find the override (if any) that targets a specific metadata suffix.
+ */
+export declare function getOverrideForType(metadataType: string, overrides?: DecomposerOverride[]): DecomposerOverride | undefined;
+/**
+ * Find the override (if any) that targets a specific component, identified by its metadata
+ * suffix and SDR fullName.
+ */
+export declare function getOverrideForComponent(metadataType: string, fullName: string, overrides?: DecomposerOverride[]): DecomposerOverride | undefined;
+/**
+ * Returns true when at least one override targets a component of the given metadata type.
+ * Used by the decompose handler to decide whether per-component enumeration is required.
+ */
+export declare function hasComponentOverridesForType(metadataType: string, overrides?: DecomposerOverride[]): boolean;
+/**
+ * Resolve the effective decompose options for a single metadata type. The base values are
+ * the run-wide options (CLI flags or defaults); per-type override values, when present, win.
+ */
+export declare function resolveDecomposeOptionsForType(metadataType: string, base: ResolvedDecomposeTypeOptions, overrides?: DecomposerOverride[]): ResolvedDecomposeTypeOptions;
+/**
+ * Resolve the effective decompose options for a single component. Precedence (highest first):
+ * component-scoped override fields (via `components`), then type-scoped resolved values
+ * (already applied by `resolveDecomposeOptionsForType`), then run-wide base values (passed
+ * through as the typeResolved fallback).
+ *
+ * Hard plugin rules (e.g. labels and loyaltyProgramSetup forced to `unique-id`) are applied
+ * separately by callers, not here, so this function stays pure.
+ */
+export declare function resolveDecomposeOptionsForComponent(metadataType: string, fullName: string, typeResolved: ResolvedDecomposeTypeOptions, overrides?: DecomposerOverride[]): ResolvedDecomposeTypeOptions;

package/lib/helpers/configOverrides.js

@@ -0,0 +1,219 @@
+'use strict';
+import { access, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { getRepoRoot } from '../service/core/getRepoRoot.js';
+import { DECOMPOSED_FILE_TYPES, DECOMPOSED_STRATEGIES, HOOK_CONFIG_JSON } from './constants.js';
+/**
+ * Resolve the absolute path of the default `.sfdecomposer.config.json`, located in the
+ * repo root (the nearest ancestor directory that contains `sfdx-project.json`). Throws
+ * a clear error when the repo root cannot be located or the config file does not exist.
+ */
+export async function resolveDefaultConfigPath() {
+    const { repoRoot } = await getRepoRoot();
+    /* istanbul ignore if -- @preserve: getRepoRoot throws when no sfdx-project.json ancestor exists, so repoRoot is always defined here. */
+    if (!repoRoot) {
+        throw new Error(`Cannot locate ${HOOK_CONFIG_JSON}: repo root not found.`);
+    }
+    const configPath = resolve(repoRoot, HOOK_CONFIG_JSON);
+    try {
+        await access(configPath);
+    }
+    catch {
+        throw new Error(`--config was provided but ${HOOK_CONFIG_JSON} was not found at ${configPath}. ` +
+            'Create the file in the repo root or omit --config.');
+    }
+    return configPath;
+}
+// Run-scope keys that must never appear inside an override entry. Any other key is treated
+// as either a recognized override field (validated below) or as a forward-compatible unknown
+// key (silently ignored).
+const FORBIDDEN_OVERRIDE_KEYS = new Set(['manifest', 'metadataSuffixes', 'ignorePackageDirectories']);
+/**
+ * Load and validate the `overrides` array from a `.sfdecomposer.config.json` file.
+ * Returns an empty array if the file is missing, unreadable, or contains no overrides.
+ */
+export async function loadOverridesFromConfig(configPath) {
+    let raw;
+    try {
+        raw = await readFile(configPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        /* istanbul ignore next -- @preserve: JSON.parse always throws SyntaxError instances. */
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse ${configPath}: ${message}`);
+    }
+    const overrides = parsed.overrides;
+    if (!overrides)
+        return [];
+    if (!Array.isArray(overrides)) {
+        throw new Error(`"overrides" in ${configPath} must be an array.`);
+    }
+    validateOverrides(overrides);
+    return overrides;
+}
+/**
+ * Validate that the overrides array is well-formed. Throws on any structural problem.
+ * Unknown override keys are tolerated (ignored), but forbidden run-scope keys throw.
+ */
+export function validateOverrides(overrides) {
+    const seenTypes = new Set();
+    const seenComponents = new Set();
+    for (let i = 0; i < overrides.length; i++) {
+        validateOverride(overrides[i], i, seenTypes, seenComponents);
+    }
+}
+function validateOverride(override, i, seenTypes, seenComponents) {
+    if (!override || typeof override !== 'object') {
+        throw new Error(`Override at index ${i} must be an object.`);
+    }
+    if (override.metadataTypes !== undefined && !Array.isArray(override.metadataTypes)) {
+        throw new Error(`Override at index ${i} has a non-array "metadataTypes".`);
+    }
+    if (override.components !== undefined && !Array.isArray(override.components)) {
+        throw new Error(`Override at index ${i} has a non-array "components".`);
+    }
+    const hasMetadataTypes = Array.isArray(override.metadataTypes) && override.metadataTypes.length > 0;
+    const hasComponents = Array.isArray(override.components) && override.components.length > 0;
+    if (!hasMetadataTypes && !hasComponents) {
+        throw new Error(`Override at index ${i} must include a non-empty "metadataTypes" or "components" array.`);
+    }
+    validateForbiddenKeys(override, i);
+    validateOverrideValues(override, i);
+    if (hasMetadataTypes) {
+        validateMetadataTypeEntries(override.metadataTypes, i, seenTypes);
+    }
+    if (hasComponents) {
+        validateComponentEntries(override.components, i, seenComponents);
+    }
+}
+function validateForbiddenKeys(override, i) {
+    for (const key of Object.keys(override)) {
+        if (FORBIDDEN_OVERRIDE_KEYS.has(key)) {
+            throw new Error(`Override at index ${i} contains "${key}", which is a run-scope option and cannot be set per metadata type.`);
+        }
+    }
+}
+function validateOverrideValues(override, i) {
+    if (override.decomposedFormat !== undefined && !DECOMPOSED_FILE_TYPES.includes(override.decomposedFormat)) {
+        throw new Error(`Override at index ${i} has invalid "decomposedFormat": "${override.decomposedFormat}". ` +
+            `Allowed values: ${DECOMPOSED_FILE_TYPES.join(', ')}.`);
+    }
+    if (override.strategy !== undefined && !DECOMPOSED_STRATEGIES.includes(override.strategy)) {
+        throw new Error(`Override at index ${i} has invalid "strategy": "${override.strategy}". ` +
+            `Allowed values: ${DECOMPOSED_STRATEGIES.join(', ')}.`);
+    }
+}
+function validateMetadataTypeEntries(metadataTypes, i, seenTypes) {
+    for (const metadataType of metadataTypes) {
+        if (typeof metadataType !== 'string' || metadataType.trim() === '') {
+            throw new Error(`Override at index ${i} contains an empty or non-string metadata type.`);
+        }
+        if (seenTypes.has(metadataType)) {
+            throw new Error(`Metadata type "${metadataType}" appears in more than one override. Each type may appear at most once.`);
+        }
+        seenTypes.add(metadataType);
+    }
+}
+function validateComponentEntries(components, i, seenComponents) {
+    for (const component of components) {
+        if (typeof component !== 'string' || component.trim() === '') {
+            throw new Error(`Override at index ${i} contains an empty or non-string component.`);
+        }
+        if (!parseComponentKey(component)) {
+            throw new Error(`Override at index ${i} has invalid component key "${component}". ` +
+                'Expected format: "<metadataSuffix>:<fullName>" (e.g. "permissionset:HR_Admin").');
+        }
+        if (seenComponents.has(component)) {
+            throw new Error(`Component "${component}" appears in more than one override. Each component may appear at most once.`);
+        }
+        seenComponents.add(component);
+    }
+}
+/**
+ * Parse a component override key of the form `<metadataSuffix>:<fullName>`. Returns `undefined`
+ * when the key is malformed. Only the first colon is treated as the delimiter so fullNames that
+ * contain `/` (folder-typed metadata such as `report:MyFolder/MyReport`) are preserved verbatim.
+ */
+export function parseComponentKey(key) {
+    const colonIdx = key.indexOf(':');
+    if (colonIdx <= 0 || colonIdx === key.length - 1)
+        return undefined;
+    const metadataType = key.slice(0, colonIdx).trim();
+    const fullName = key.slice(colonIdx + 1).trim();
+    if (!metadataType || !fullName)
+        return undefined;
+    return { metadataType, fullName };
+}
+/**
+ * Find the override (if any) that targets a specific metadata suffix.
+ */
+export function getOverrideForType(metadataType, overrides) {
+    if (!overrides || overrides.length === 0)
+        return undefined;
+    return overrides.find((override) => override.metadataTypes?.includes(metadataType));
+}
+/**
+ * Find the override (if any) that targets a specific component, identified by its metadata
+ * suffix and SDR fullName.
+ */
+export function getOverrideForComponent(metadataType, fullName, overrides) {
+    if (!overrides || overrides.length === 0)
+        return undefined;
+    const key = `${metadataType}:${fullName}`;
+    return overrides.find((override) => override.components?.includes(key));
+}
+/**
+ * Returns true when at least one override targets a component of the given metadata type.
+ * Used by the decompose handler to decide whether per-component enumeration is required.
+ */
+export function hasComponentOverridesForType(metadataType, overrides) {
+    if (!overrides || overrides.length === 0)
+        return false;
+    const prefix = `${metadataType}:`;
+    return overrides.some((override) => override.components?.some((component) => component.startsWith(prefix)));
+}
+/**
+ * Resolve the effective decompose options for a single metadata type. The base values are
+ * the run-wide options (CLI flags or defaults); per-type override values, when present, win.
+ */
+export function resolveDecomposeOptionsForType(metadataType, base, overrides) {
+    const override = getOverrideForType(metadataType, overrides);
+    if (!override)
+        return base;
+    return {
+        format: override.decomposedFormat ?? base.format,
+        strategy: override.strategy ?? base.strategy,
+        decomposeNestedPerms: override.decomposeNestedPermissions ?? base.decomposeNestedPerms,
+        prepurge: override.prePurge ?? base.prepurge,
+        postpurge: override.postPurge ?? base.postpurge,
+    };
+}
+/**
+ * Resolve the effective decompose options for a single component. Precedence (highest first):
+ * component-scoped override fields (via `components`), then type-scoped resolved values
+ * (already applied by `resolveDecomposeOptionsForType`), then run-wide base values (passed
+ * through as the typeResolved fallback).
+ *
+ * Hard plugin rules (e.g. labels and loyaltyProgramSetup forced to `unique-id`) are applied
+ * separately by callers, not here, so this function stays pure.
+ */
+export function resolveDecomposeOptionsForComponent(metadataType, fullName, typeResolved, overrides) {
+    const componentOverride = getOverrideForComponent(metadataType, fullName, overrides);
+    if (!componentOverride)
+        return typeResolved;
+    return {
+        format: componentOverride.decomposedFormat ?? typeResolved.format,
+        strategy: componentOverride.strategy ?? typeResolved.strategy,
+        decomposeNestedPerms: componentOverride.decomposeNestedPermissions ?? typeResolved.decomposeNestedPerms,
+        prepurge: componentOverride.prePurge ?? typeResolved.prepurge,
+        postpurge: componentOverride.postPurge ?? typeResolved.postpurge,
+    };
+}
+//# sourceMappingURL=configOverrides.js.map