sf-decomposer-edit-metadata
Use when the user asks to read, compare, audit, or change large Salesforce metadata XML files in a Salesforce DX project, such as permission sets, profiles, custom labels, workflows, flows, sharing rules, or bots. Examples include "give the Sales Ops permission set read access to Account.Industry", "which permission sets can edit Opportunity.Amount", "remove every reference to the oldns package from our profiles", "compare these two permission sets", or "rename this custom label". Splits each file into small per-element files with sf-decomposer, works on those, then rebuilds the original file so only the intended change remains. Needs Node.js 22.19+, no Salesforce CLI.
mcarvin8 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mcarvin8/sf-decomposer --skill sf-decomposer-edit-metadata技能说明
name: sf-decomposer-edit-metadata description: Use when the user asks to read, compare, audit, or change large Salesforce metadata XML files in a Salesforce DX project, such as permission sets, profiles, custom labels, workflows, flows, sharing rules, or bots. Examples include "give the Sales Ops permission set read access to Account.Industry", "which permission sets can edit Opportunity.Amount", "remove every reference to the oldns package from our profiles", "compare these two permission sets", or "rename this custom label". Splits each file into small per-element files with sf-decomposer, works on those, then rebuilds the original file so only the intended change remains. Needs Node.js 22.19+, no Salesforce CLI. license: MIT
Edit Salesforce metadata with sf-decomposer
Large metadata files (permission sets, profiles, labels, workflows) are thousands of lines of repetitive XML. Editing them in place is error-prone and reading them whole wastes context. sf-decomposer splits each file into one small file per element (for example one file per field permission), so you can find, read, add, change, or delete exactly the element you need, then rebuild the original file.
All commands below run npx -y sf-decomposer-core@7, which needs Node.js 22.19
or newer and nothing else. Never install the Salesforce CLI or the sf plugin
for this.
Step 1: Check the project
- Find
sfdx-project.jsonin the working directory or a parent. If there is none, stop: sf-decomposer only works in a Salesforce DX project. Run every command below from the folder that holds it. - Confirm
node --versionis 22.19 or newer. - Find the metadata type suffix from the file name,
<Name>.<suffix>-meta.xml(for examplepermissionset,profile,labels,workflow,flow). Custom objects (object) and types stored as bundles or with content files (Apex classes, LWC, Aura, static resources, Experience sites) are not supported. Edit those directly. - Check
sfdx-project.jsonforsourceBehaviorOptions(for exampledecomposePermissionSetBeta2,decomposeCustomLabelsBeta2,decomposeWorkflowBeta,decomposeSharingRulesBeta). If the type you need is listed, Salesforce's own decomposition already splits it. Don't run sf-decomposer on that type; edit the files Salesforce created directly.
Step 2: Choose the mode
Check whether the project already uses sf-decomposer: a
.sfdecomposer.config.json in the project root, or .key_order.json files in
folders next to the metadata files.
- Already decomposed: the small files exist and are what the team edits and commits. Use Mode A.
- Not decomposed: the project keeps only the original XML files. Use Mode B. It decomposes only the components you need, then restores the original layout, so the only change left is the one the user asked for.
Mode A: project already uses sf-decomposer
- Read, edit, add, or delete the small files directly (see Working with the small files).
- If the original root files are tracked in git (
git ls-fileslists files likepermissionsets/Sales_Ops.permissionset-meta.xml), rebuild them so they match:npx -y sf-decomposer-core@7 recompose -c -m <suffix>. If only the small files are tracked, skip this; the team's hooks or CI rebuild them. - Don't change
.sfdecomposer.config.json,.forceignore, or the decompose strategy or format unless the user asks.
Mode B: temporary decomposition
-
Check that the target files have no uncommitted changes (
git status --porcelain -- <paths>). If they do, tell the user and ask before continuing, so their edits and yours stay distinguishable. -
Write a
package.xmloutside the repository (in a fresh temporary folder) that lists only the components you need, using the Metadata API type names:<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>Sales_Ops</members> <members>Support_Agent</members> <name>PermissionSet</name> </types> <version>62.0</version> </Package><members>*</members>covers every component of that type, which suits repo-wide questions such as "which permission sets grant X". For the type names, seereferences/metadata-types.md. -
Check the round trip is safe before touching anything:
npx -y sf-decomposer-core@7 verify -x <manifest> --json- Non-empty
drift: stop and tell the user. Rebuilding would change those files beyond your edit. - Non-empty
reordered: rebuilding would reorder elements in those files (Salesforce ignores the order, but the diff will show it). Tell the user and ask whether to continue.
- Non-empty
-
Decompose with the defaults (one file per element, XML):
npx -y sf-decomposer-core@7 decompose -x <manifest>Never pass
--postpurge,--update-forceignore,--update-gitattributes, or-cin this mode. Those change the project's layout or config. -
Do the work in the small files (see below).
-
Rebuild the original files and remove the small ones:
npx -y sf-decomposer-core@7 recompose -x <manifest> --postpurgeRun every command from the project root, and never
cdinto a component folder. On Windows, a shell whose working directory is inside a folder locks it, so--postpurgestops partway through and still exits 0. -
Run
git statusandgit diffon the changed files. For a read-only task, the diff should be empty. If a component folder is still there after step 6, the purge stopped partway and some small files are already gone:- Never run recompose again. It would rebuild the original from the files that are left and silently drop the elements that were purged.
- The original was rebuilt