@salesforce/plugin-deploy-retrieve 3.7.10 → 3.8.0

package/README.md

@@ -64,6 +64,7 @@ sf plugins
 
 - [`sf project convert mdapi`](#sf-project-convert-mdapi)
 - [`sf project convert source`](#sf-project-convert-source)
+- [`sf project convert source-behavior`](#sf-project-convert-source-behavior)
 - [`sf project delete source`](#sf-project-delete-source)
 - [`sf project delete tracking`](#sf-project-delete-tracking)
 - [`sf project deploy cancel`](#sf-project-deploy-cancel)
@@ -140,7 +141,7 @@ FLAG DESCRIPTIONS
     If you specify this parameter, don’t specify --metadata or --source-dir.
 ```
 
-_See code: [src/commands/project/convert/mdapi.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/convert/mdapi.ts)_
+_See code: [src/commands/project/convert/mdapi.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/convert/mdapi.ts)_
 
 ## `sf project convert source`
 
@@ -152,7 +153,7 @@ USAGE
     [-p <value> | -x <value> | -m <value>]
 
 FLAGS
-  -d, --output-dir=<value>     [default: metadataPackage_1716916326517] Output directory to store the Metadata
+  -d, --output-dir=<value>     [default: metadataPackage_1716992749510] Output directory to store the Metadata
                                API–formatted files in.
   -m, --metadata=<value>...    Metadata component names to convert.
   -n, --package-name=<value>   Name of the package to associate with the metadata-formatted files.
@@ -213,7 +214,64 @@ FLAG DESCRIPTIONS
     Override the api version used for api requests made by this command
 ```
 
-_See code: [src/commands/project/convert/source.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/convert/source.ts)_
+_See code: [src/commands/project/convert/source.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/convert/source.ts)_
+
+## `sf project convert source-behavior`
+
+Enable a behavior of your project source files, and then update your Salesforce DX project to implement the behavior.
+
+```
+USAGE
+  $ sf project convert source-behavior -b
+    decomposeCustomLabelsBeta|decomposePermissionSetBeta|decomposeSharingRulesBeta|decomposeWorkflowBeta [--json]
+    [--flags-dir <value>] [--dry-run] [--preserve-temp-dir] [-o <value>]
+
+FLAGS
+  -b, --behavior=<option>   (required) Behavior to enable; the values correspond to the possible values of the
+                            "sourceBehaviorOption" option in the "sfdx-project.json" file.
+                            <options: decomposeCustomLabelsBeta|decomposePermissionSetBeta|decomposeSharingRulesBeta|dec
+                            omposeWorkflowBeta>
+  -o, --target-org=<value>
+      --dry-run             Display what the command would do, but don't make any actual changes.
+      --preserve-temp-dir   Don't delete the metadata API format temporary directory that this command creates. Useful
+                            for debugging.
+
+GLOBAL FLAGS
+  --flags-dir=<value>  Import flag values from a directory.
+  --json               Format output as json.
+
+DESCRIPTION
+  Enable a behavior of your project source files, and then update your Salesforce DX project to implement the behavior.
+
+  Specifically, this command updates the "sourceBehaviorOption" option in the "sfdx-project.json" file and then converts
+  the associated local source files in your project as needed.
+
+  For example, run this command with the "--behavior decomposePermissionSetBeta" flag to start decomposing permission
+  sets when you deploy or retrieve them. Decomposing means breaking up the monolithic metadata API format XML file that
+  corresponds to a metadata component into smaller XML files and directories based on its subtypes. Permission sets are
+  not decomposed by default; you must opt-in to start decomposing them by using this command. When the command finishes,
+  your "sfdx-project.json" file is updated to always decompose permission sets, and the existing permission set files in
+  your local package directories are converted into the new decomposed format. You run this command only once for a
+  given behavior change.
+
+  For more information about the possible values for the --behavior flag, see the "sourceBehaviorOptions" section in the
+  https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_config.htm topic.
+
+EXAMPLES
+  Update your Salesforce DX project to decompose custom labels:
+
+    $ sf project convert source-behavior --behavior decomposeCustomLabelsBeta
+
+  Display what the command would do, but don't change any existing files:
+
+    $ sf project convert source-behavior --behavior decomposeCustomLabelsBeta --dry-run
+
+  Keep the temporary directory that contains the interim metadata API formatted files:
+
+    $ sf project convert source-behavior --behavior decomposeCustomLabelsBeta --dry-run --preserve-temp-dir
+```
+
+_See code: [src/commands/project/convert/source-behavior.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/convert/source-behavior.ts)_
 
 ## `sf project delete source`
 
@@ -353,7 +411,7 @@ FLAG DESCRIPTIONS
     - Separate the test names with spaces: --tests Test1 Test2 "Test With Space"
 ```
 
-_See code: [src/commands/project/delete/source.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/delete/source.ts)_
+_See code: [src/commands/project/delete/source.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/delete/source.ts)_
 
 ## `sf project delete tracking`
 
@@ -390,7 +448,7 @@ EXAMPLES
     $ sf project delete tracking --target-org my-scratch
 ```
 
-_See code: [src/commands/project/delete/tracking.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/delete/tracking.ts)_
+_See code: [src/commands/project/delete/tracking.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/delete/tracking.ts)_
 
 ## `sf project deploy cancel`
 
@@ -466,7 +524,7 @@ FLAG DESCRIPTIONS
     project deploy report".
 ```
 
-_See code: [src/commands/project/deploy/cancel.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/deploy/cancel.ts)_
+_See code: [src/commands/project/deploy/cancel.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/deploy/cancel.ts)_
 
 ## `sf project deploy preview`
 
@@ -552,7 +610,7 @@ FLAG DESCRIPTIONS
     All child components are included. If you specify this flag, don’t specify --metadata or --source-dir.
 ```
 
-_See code: [src/commands/project/deploy/preview.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/deploy/preview.ts)_
+_See code: [src/commands/project/deploy/preview.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/deploy/preview.ts)_
 
 ## `sf project deploy quick`
 
@@ -640,7 +698,7 @@ FLAG DESCRIPTIONS
     deploy report".
 ```
 
-_See code: [src/commands/project/deploy/quick.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/deploy/quick.ts)_
+_See code: [src/commands/project/deploy/quick.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/deploy/quick.ts)_
 
 ## `sf project deploy report`
 
@@ -736,7 +794,7 @@ FLAG DESCRIPTIONS
     --coverage-formatters lcov --coverage-formatters clover
 ```
 
-_See code: [src/commands/project/deploy/report.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/deploy/report.ts)_
+_See code: [src/commands/project/deploy/report.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/deploy/report.ts)_
 
 ## `sf project deploy resume`
 
@@ -821,7 +879,7 @@ FLAG DESCRIPTIONS
     --coverage-formatters lcov --coverage-formatters clover
 ```
 
-_See code: [src/commands/project/deploy/resume.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/deploy/resume.ts)_
+_See code: [src/commands/project/deploy/resume.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/deploy/resume.ts)_
 
 ## `sf project deploy start`
 
@@ -1042,7 +1100,7 @@ FLAG DESCRIPTIONS
     --coverage-formatters lcov --coverage-formatters clover
 ```
 
-_See code: [src/commands/project/deploy/start.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/deploy/start.ts)_
+_See code: [src/commands/project/deploy/start.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/deploy/start.ts)_
 
 ## `sf project deploy validate`
 
@@ -1217,7 +1275,7 @@ FLAG DESCRIPTIONS
     --coverage-formatters lcov --coverage-formatters clover
 ```
 
-_See code: [src/commands/project/deploy/validate.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/deploy/validate.ts)_
+_See code: [src/commands/project/deploy/validate.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/deploy/validate.ts)_
 
 ## `sf project generate manifest`
 
@@ -1294,7 +1352,7 @@ EXAMPLES
     $ sf project generate manifest --from-org test@myorg.com --include-packages unlocked
 ```
 
-_See code: [src/commands/project/generate/manifest.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/generate/manifest.ts)_
+_See code: [src/commands/project/generate/manifest.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/generate/manifest.ts)_
 
 ## `sf project list ignored`
 
@@ -1336,7 +1394,7 @@ EXAMPLES
     $ sf project list ignored --source-dir package.xml
 ```
 
-_See code: [src/commands/project/list/ignored.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/list/ignored.ts)_
+_See code: [src/commands/project/list/ignored.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/list/ignored.ts)_
 
 ## `sf project reset tracking`
 
@@ -1385,7 +1443,7 @@ EXAMPLES
     $ sf project reset tracking --revision 30
 ```
 
-_See code: [src/commands/project/reset/tracking.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/reset/tracking.ts)_
+_See code: [src/commands/project/reset/tracking.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/reset/tracking.ts)_
 
 ## `sf project retrieve preview`
 
@@ -1442,7 +1500,7 @@ FLAG DESCRIPTIONS
     Overrides your default org.
 ```
 
-_See code: [src/commands/project/retrieve/preview.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/retrieve/preview.ts)_
+_See code: [src/commands/project/retrieve/preview.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/retrieve/preview.ts)_
 
 ## `sf project retrieve start`
 
@@ -1593,6 +1651,6 @@ FLAG DESCRIPTIONS
     If you specify this parameter, don’t specify --metadata or --source-dir.
 ```
 
-_See code: [src/commands/project/retrieve/start.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.7.10/src/commands/project/retrieve/start.ts)_
+_See code: [src/commands/project/retrieve/start.ts](https://github.com/salesforcecli/plugin-deploy-retrieve/blob/3.8.0/src/commands/project/retrieve/start.ts)_
 
 <!-- commandsstop -->

package/lib/commands/project/convert/source-behavior.d.ts

@@ -0,0 +1,21 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { PRESETS_PROP } from '../../../utils/convertBehavior.js';
+export type SourceBehaviorResult = {
+    [PRESETS_PROP]: string[];
+    deletedFiles: string[];
+    createdFiles: string[];
+};
+export default class ConvertSourceBehavior extends SfCommand<SourceBehaviorResult> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly state = "beta";
+    static readonly requiresProject = true;
+    static readonly flags: {
+        behavior: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        'dry-run': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        'preserve-temp-dir': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        'target-org': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<import("@salesforce/core").Org, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    run(): Promise<SourceBehaviorResult>;
+}

package/lib/commands/project/convert/source-behavior.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2023, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import { rm, readFile, writeFile } from 'node:fs/promises';
+import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+import { getValidatedProjectJson, TMP_DIR, convertToMdapi, DRY_RUN_DIR, PRESETS_PROP, PRESET_CHOICES, getPackageDirectoriesForPreset, convertBackToSource, } from '../../../utils/convertBehavior.js';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@salesforce/plugin-deploy-retrieve', 'convert.source-behavior');
+export default class ConvertSourceBehavior extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    static state = 'beta';
+    static requiresProject = true;
+    static flags = {
+        behavior: Flags.option({
+            summary: messages.getMessage('flags.behavior.summary'),
+            char: 'b',
+            required: true,
+            options: PRESET_CHOICES,
+        })(),
+        'dry-run': Flags.boolean({
+            summary: messages.getMessage('flags.dry-run.summary'),
+        }),
+        'preserve-temp-dir': Flags.boolean({
+            summary: messages.getMessage('flags.preserve-temp-dir.summary'),
+        }),
+        'target-org': Flags.optionalOrg(),
+    };
+    async run() {
+        const { flags } = await this.parse(ConvertSourceBehavior);
+        if (await flags['target-org']?.supportsSourceTracking()) {
+            throw messages.createError('error.trackingNotSupported');
+        }
+        const projectJson = getValidatedProjectJson(flags.behavior, this.project);
+        const [backupPjsonContents, packageDirsWithDecomposable] = await Promise.all([
+            flags['dry-run'] ? readFile(projectJson.getPath()) : '',
+            getPackageDirectoriesForPreset(this.project, flags.behavior),
+        ]);
+        const filesToDelete = await convertToMdapi(packageDirsWithDecomposable);
+        // flip the preset in the sfdx-project.json, even for dry-run, since the registry will need for conversions
+        projectJson.set(PRESETS_PROP, [...(projectJson.get(PRESETS_PROP) ?? []), flags.behavior]);
+        await projectJson.write();
+        this.info(`sfdx-project.json ${PRESETS_PROP} is now [${projectJson.get(PRESETS_PROP).join(',')}]`);
+        // delete the “original” files that no longer work because of project update
+        await Promise.all(flags['dry-run'] ? [] : filesToDelete.map((f) => rm(f)));
+        const createdFiles = await convertBackToSource({
+            packageDirsWithPreset: packageDirsWithDecomposable,
+            projectDir: this.project.getPath(),
+            dryRun: flags['dry-run'],
+        });
+        if (!flags['preserve-temp-dir']) {
+            await rm(TMP_DIR, { recursive: true });
+        }
+        this.table(filesToDelete.map((f) => ({ value: f })), { value: { header: flags['dry-run'] ? 'Files that would have been deleted if not --dry-run' : 'Deleted Files' } });
+        this.log();
+        this.table(createdFiles.map((f) => ({ value: f })), { value: { header: 'Created Files' } });
+        if (flags['dry-run']) {
+            // put it back how it was
+            await writeFile(projectJson.getPath(), backupPjsonContents);
+            this.logSuccess(messages.getMessage('success.dryRun', [DRY_RUN_DIR]));
+        }
+        return {
+            createdFiles,
+            deletedFiles: filesToDelete,
+            sourceBehaviorOptions: projectJson.get(PRESETS_PROP),
+        };
+    }
+}
+//# sourceMappingURL=source-behavior.js.map

package/lib/commands/project/convert/source-behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-behavior.js","sourceRoot":"","sources":["../../../../src/commands/project/convert/source-behavior.ts"],"names":[],"mappings":"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"}

package/lib/utils/convertBehavior.d.ts

@@ -0,0 +1,24 @@
+import { SfProject, SfProjectJson } from '@salesforce/core';
+import { ComponentSet } from '@salesforce/source-deploy-retrieve';
+export type ComponentSetAndPackageDirPath = {
+    packageDirPath: string;
+    cs: ComponentSet;
+};
+export declare const PRESETS_PROP = "sourceBehaviorOptions";
+export declare const PRESET_CHOICES: string[];
+export declare const TMP_DIR: string;
+export declare const DRY_RUN_DIR = "DRY-RUN-RESULTS";
+/** returns packageDirectories and ComponentsSets where there is metadata of the type we'll change the behavior for */
+export declare const getPackageDirectoriesForPreset: (project: SfProject, preset: string) => Promise<ComponentSetAndPackageDirPath[]>;
+/** converts the composed metadata to mdapi format in a temp dir */
+export declare const convertToMdapi: (packageDirsWithDecomposable: ComponentSetAndPackageDirPath[]) => Promise<string[]>;
+/** get the LOCAL project json, throws if not present OR the preset already exists */
+export declare const getValidatedProjectJson: (preset: string, project: SfProject) => SfProjectJson;
+/** converts the temporary mdapi back to source, return a list of the created files */
+export declare const convertBackToSource: ({ packageDirsWithPreset, projectDir, dryRun, }: {
+    packageDirsWithPreset: ComponentSetAndPackageDirPath[];
+    projectDir: string;
+    /** if provided, will output the results into a separate directory outside the project's packageDirectories */
+    dryRun: boolean;
+}) => Promise<string[]>;
+export declare const getTypesFromPreset: (preset: string) => Promise<string[]>;

package/lib/utils/convertBehavior.js

@@ -0,0 +1,126 @@
+/*
+ * Copyright (c) 2023, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import { existsSync, readdirSync } from 'node:fs';
+// import { platform } from 'node:os';
+import { readFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SfError, Messages } from '@salesforce/core';
+import { ComponentSetBuilder, MetadataConverter, RegistryAccess, } from '@salesforce/source-deploy-retrieve';
+import { isString } from '@salesforce/ts-types';
+// TODO: there could be a cleaner way to read this
+const PRESET_DIR = fileURLToPath(join(import.meta.resolve('@salesforce/source-deploy-retrieve'), '..', 'registry', 'presets'));
+export const PRESETS_PROP = 'sourceBehaviorOptions';
+export const PRESET_CHOICES = (await readdir(PRESET_DIR)).map((f) => f.replace('.json', ''));
+export const TMP_DIR = process.env.SF_MDAPI_TEMP_DIR ?? 'decompositionConverterTempDir';
+export const DRY_RUN_DIR = 'DRY-RUN-RESULTS';
+/** returns packageDirectories and ComponentsSets where there is metadata of the type we'll change the behavior for */
+export const getPackageDirectoriesForPreset = async (project, preset) => {
+    const projectDir = project.getPath();
+    const output = (await Promise.all(project
+        .getPackageDirectories()
+        .map((pd) => pd.path)
+        .map(componentSetFromPackageDirectory(projectDir)(await getTypesFromPreset(preset)))))
+        .filter(componentSetIsNonEmpty)
+        // we do this after filtering componentSets to reduce false positives (ex: dir does not have main/default but also has nothing to decompose)
+        .map(validateMainDefault(projectDir));
+    if (output.length === 0) {
+        loadMessages().createError('error.noTargetTypes', [preset]);
+    }
+    return output;
+};
+/** converts the composed metadata to mdapi format in a temp dir */
+export const convertToMdapi = async (packageDirsWithDecomposable) => (await Promise.all(packageDirsWithDecomposable.map(async (pd) => {
+    // convert to the mdapi targetDir
+    await new MetadataConverter().convert(pd.cs, 'metadata', {
+        type: 'directory',
+        outputDirectory: join(TMP_DIR, pd.packageDirPath),
+        genUniqueDir: false,
+    });
+    return getComponentSetFiles(pd.cs);
+})))
+    .flat()
+    .map((f) => resolve(f));
+/** get the LOCAL project json, throws if not present OR the preset already exists */
+export const getValidatedProjectJson = (preset, project) => {
+    const projectJson = project.getSfProjectJson(false);
+    if (projectJson.get(PRESETS_PROP)?.includes(preset)) {
+        throw SfError.create({
+            name: 'sourceBehaviorOptionAlreadyExists',
+            message: `sourceBehaviorOption ${preset} already exists in sfdx-project.json`,
+        });
+    }
+    return projectJson;
+};
+/** converts the temporary mdapi back to source, return a list of the created files */
+export const convertBackToSource = async ({ packageDirsWithPreset, projectDir, dryRun, }) => [
+    ...new Set((await convertToSource({
+        packageDirsWithPreset,
+        projectDir,
+        dryRunDir: dryRun ? DRY_RUN_DIR : undefined,
+    }))
+        .flatMap((cr) => cr.converted ?? [])
+        // we can't use walkContent because there's a conditional inside it
+        .flatMap(getSourceComponentFiles)
+        .filter(isString)),
+];
+const getSourceComponentFiles = (c) => [c.xml, ...(c.content ? fullPathsFromDir(c.content) : [])].filter(isString);
+const fullPathsFromDir = (dir) => readdirSync(dir, { withFileTypes: true }).map((d) => join(d.path, d.name));
+/** build a component set from the original project for each pkgDir */
+const componentSetFromPackageDirectory = (projectDir) => (metadataEntries) => async (packageDir) => ({
+    packageDirPath: packageDir,
+    cs: await ComponentSetBuilder.build({
+        metadata: {
+            metadataEntries,
+            directoryPaths: [packageDir],
+        },
+        projectDir,
+    }),
+});
+const convertToSource = async ({ packageDirsWithPreset, projectDir, dryRunDir, }) => {
+    // mdapi=>source convert the target dir back to the project
+    // it's a new converter because the project has changed and it should reload the project's registry.
+    const converter = new MetadataConverter(new RegistryAccess(undefined, projectDir));
+    return Promise.all(packageDirsWithPreset.map(async (pd) => converter.convert(
+    // componentSet based on each mdapi folder
+    await ComponentSetBuilder.build({ sourcepath: [join(TMP_DIR, pd.packageDirPath)], projectDir }), 'source', dryRunDir
+        ? // dryRun outputs to a dir outside the real packageDirs folder to avoid changing real stuff
+            {
+                type: 'directory',
+                outputDirectory: join(projectDir, dryRunDir),
+                packageName: pd.packageDirPath,
+                genUniqueDir: false,
+            }
+        : {
+            type: 'merge',
+            mergeWith: (await ComponentSetBuilder.build({
+                sourcepath: [pd.packageDirPath],
+                projectDir,
+            })).getSourceComponents(),
+            defaultDirectory: join(projectDir, pd.packageDirPath),
+        })));
+};
+export const getTypesFromPreset = async (preset) => Object.values(JSON.parse(await readFile(join(PRESET_DIR, `${preset}.json`), 'utf-8')).types).map((t) => t.name);
+/** convert will put things in /main/default.  If the packageDirs aren't configured that way, we don't want to make a mess.
+ * See https://salesforce.quip.com/va5IAgXmTMWF for details on that issue */
+const validateMainDefault = (projectDir) => (i) => {
+    if (!existsSync(join(projectDir, i.packageDirPath, 'main', 'default'))) {
+        throw loadMessages().createError('error.packageDirectoryNeedsMainDefault', [i.packageDirPath], [i.packageDirPath]);
+    }
+    return i;
+};
+const getComponentSetFiles = (cs) => cs
+    .getSourceComponents()
+    .toArray()
+    .flatMap((c) => [c.xml, ...c.walkContent()])
+    .filter(isString);
+const loadMessages = () => {
+    Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+    return Messages.loadMessages('@salesforce/plugin-deploy-retrieve', 'convert.source-behavior');
+};
+const componentSetIsNonEmpty = (i) => i.cs.size > 0;
+//# sourceMappingURL=convertBehavior.js.map

package/lib/utils/convertBehavior.js.map

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

package/messages/convert.source-behavior.md

@@ -0,0 +1,70 @@
+# summary
+
+Enable a behavior of your project source files, and then update your Salesforce DX project to implement the behavior.
+
+# description
+
+Specifically, this command updates the "sourceBehaviorOption" option in the "sfdx-project.json" file and then converts the associated local source files in your project as needed.
+
+For example, run this command with the "--behavior decomposePermissionSetBeta" flag to start decomposing permission sets when you deploy or retrieve them. Decomposing means breaking up the monolithic metadata API format XML file that corresponds to a metadata component into smaller XML files and directories based on its subtypes. Permission sets are not decomposed by default; you must opt-in to start decomposing them by using this command. When the command finishes, your "sfdx-project.json" file is updated to always decompose permission sets, and the existing permission set files in your local package directories are converted into the new decomposed format. You run this command only once for a given behavior change.
+
+For more information about the possible values for the --behavior flag, see the "sourceBehaviorOptions" section in the https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_config.htm topic.
+
+# flags.behavior.summary
+
+Behavior to enable; the values correspond to the possible values of the "sourceBehaviorOption" option in the "sfdx-project.json" file.
+
+# examples
+
+- Update your Salesforce DX project to decompose custom labels:
+
+  <%= config.bin %> <%= command.id %> --behavior decomposeCustomLabelsBeta
+
+- Display what the command would do, but don't change any existing files:
+
+  <%= config.bin %> <%= command.id %> --behavior decomposeCustomLabelsBeta --dry-run
+
+- Keep the temporary directory that contains the interim metadata API formatted files:
+
+  <%= config.bin %> <%= command.id %> --behavior decomposeCustomLabelsBeta --dry-run --preserve-temp-dir
+
+# flags.dry-run.summary
+
+Display what the command would do, but don't make any actual changes.
+
+# flags.dry-run.description
+
+Doesn't modify the existing files in your project, including the "sfdx-project.json" file. Instead, the command lists the files that would be deleted, explains the modifications to the "sfdx-project.json" file, and outputs the resulting modifications to a new directory named `DRY-RUN-RESULTS` for review.
+
+# flags.preserve-temp-dir.summary
+
+Don't delete the metadata API format temporary directory that this command creates. Useful for debugging.
+
+# error.trackingNotSupported
+
+Your project has a default org (target-org) that uses source tracking. This operation will cause changes to the local project source files that can't be properly tracked.
+
+# error.trackingNotSupported.actions
+
+- Retrieve any changes or data you need from the org that you haven't already retrieved.
+- Delete the org ("sf org delete scratch" or "sf org delete sandbox").
+- Run this command again.
+- Create a new org ("sf org create scratch" or "sf org create sandbox") and deploy the modified source.
+
+# error.packageDirectoryNeedsMainDefault
+
+The package directory %s doesn't have a main/default structure.
+This command moves metadata into a main/default structure, but your package directories aren't ready for it.
+
+# error.packageDirectoryNeedsMainDefault.actions
+
+- Update %s to have all its metadata inside a main/default directory structure.
+- Run the command again.
+
+# success.dryRun
+
+Files were created in %s outside your package directories for you to inspect.
+
+# error.noTargetTypes
+
+The project doesn't contain any package directories with metadata that matches the specified behavior %s.