feat: add decomposition preset for external service registration

package.json

@@ -25,8 +25,8 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@salesforce/core": "^8.8.0",
-    "@salesforce/kit": "^3.2.2",
+    "@salesforce/core": "^8.8.2",
+    "@salesforce/kit": "^3.2.3",
     "@salesforce/ts-types": "^2.0.12",
     "fast-levenshtein": "^3.0.0",
     "fast-xml-parser": "^4.5.1",
@@ -37,7 +37,8 @@
     "jszip": "^3.10.1",
     "mime": "2.6.0",
     "minimatch": "^9.0.5",
-    "proxy-agent": "^6.4.0"
+    "proxy-agent": "^6.4.0",
+    "yaml": "^2.6.1"
   },
   "devDependencies": {
     "@jsforce/jsforce-node": "^3.6.3",

src/convert/convertContext/convertContext.ts

@@ -11,6 +11,7 @@ import { DecompositionFinalizer } from './decompositionFinalizer';
 import { ConvertTransactionFinalizer } from './transactionFinalizer';
 import { DecomposedLabelsFinalizer } from './decomposedLabelsFinalizer';
 import { DecomposedPermissionSetFinalizer } from './decomposedPermissionSetFinalizer';
+import { DecomposedExternalServiceRegistrationFinalizer } from './decomposedExternalServiceRegistrationFinalizer';
 /**
  * A state manager over the course of a single metadata conversion call.
  */
@@ -20,6 +21,7 @@ export class ConvertContext {
   public readonly nonDecomposition = new NonDecompositionFinalizer();
   public readonly decomposedLabels = new DecomposedLabelsFinalizer();
   public readonly decomposedPermissionSet = new DecomposedPermissionSetFinalizer();
+  public readonly decomposedExternalServiceRegistration = new DecomposedExternalServiceRegistrationFinalizer();
 
   // eslint-disable-next-line @typescript-eslint/require-await
   public async *executeFinalizers(defaultDirectory?: string): AsyncIterable<WriterFormat[]> {

src/convert/convertContext/decomposedExternalServiceRegistrationFinalizer.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2025, 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 { join } from 'node:path';
+import type { ExternalServiceRegistration } from '@jsforce/jsforce-node/lib/api/metadata/schema';
+import { ensure, ensureString } from '@salesforce/ts-types';
+import { WriterFormat } from '../types';
+import { MetadataType } from '../../registry';
+import { JsToXml } from '../streams';
+import { ConvertTransactionFinalizer } from './transactionFinalizer';
+
+type ExternalServiceRegistrationState = {
+  esrRecords: Map<string, ExternalServiceRegistration>;
+};
+
+export class DecomposedExternalServiceRegistrationFinalizer extends ConvertTransactionFinalizer<ExternalServiceRegistrationState> {
+  /** to support custom presets (the only way this code should get hit at all pass in the type from a transformer that has registry access */
+  public externalServiceRegistration?: MetadataType;
+  public transactionState: ExternalServiceRegistrationState = {
+    esrRecords: new Map<string, ExternalServiceRegistration>(),
+  };
+  // eslint-disable-next-line class-methods-use-this
+  public defaultDir: string | undefined;
+
+  public finalize(defaultDirectory: string | undefined): Promise<WriterFormat[]> {
+    this.defaultDir = defaultDirectory;
+    const writerFormats: WriterFormat[] = [];
+    this.transactionState.esrRecords.forEach((esrRecord, parent) =>
+      writerFormats.push({
+        component: {
+          type: ensure(this.externalServiceRegistration, 'DecomposedESRFinalizer should have set .ESR'),
+          fullName: ensureString(parent),
+        },
+        writeInfos: [
+          {
+            output: join(
+              ensure(this.externalServiceRegistration?.directoryName, 'directory name missing'),
+              `${parent}.externalServiceRegistration`
+            ),
+            source: new JsToXml({ ExternalServiceRegistration: { ...esrRecord } }),
+          },
+        ],
+      })
+    );
+    return Promise.resolve(writerFormats);
+  }
+}

src/convert/transformers/baseMetadataTransformer.ts

@@ -6,8 +6,8 @@
  */
 import { MetadataTransformer, WriteInfo } from '../types';
 import { ConvertContext } from '../convertContext/convertContext';
-import { SourceComponent } from '../../resolve/sourceComponent';
-import { RegistryAccess } from '../../registry/registryAccess';
+import { SourceComponent } from '../../resolve';
+import { RegistryAccess } from '../../registry';
 
 export abstract class BaseMetadataTransformer implements MetadataTransformer {
   public readonly context: ConvertContext;

src/convert/transformers/decomposeExternalServiceRegistrationTransformer.ts

@@ -0,0 +1,119 @@
+/*
+ * 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 * as path from 'node:path';
+import { Readable } from 'node:stream';
+import * as yaml from 'yaml';
+import { XMLBuilder } from 'fast-xml-parser';
+import type { ExternalServiceRegistration } from '@jsforce/jsforce-node/lib/api/metadata/schema';
+import { WriteInfo } from '../types';
+import { SourceComponent } from '../../resolve';
+import { DEFAULT_PACKAGE_ROOT_SFDX, META_XML_SUFFIX, XML_DECL, XML_NS_KEY } from '../../common';
+import { BaseMetadataTransformer } from './baseMetadataTransformer';
+
+type SchemaType = 'json' | 'yaml';
+
+type ESR = {
+  ExternalServiceRegistration: ExternalServiceRegistration & { schemaUploadFileExtension: SchemaType };
+};
+
+const xmlDeclaration = '<?xml version="1.0" encoding="UTF-8"?>\n';
+
+export class DecomposeExternalServiceRegistrationTransformer extends BaseMetadataTransformer {
+  public async toSourceFormat(input: {
+    component: SourceComponent;
+    mergeWith?: SourceComponent | undefined;
+  }): Promise<WriteInfo[]> {
+    this.context.decomposedExternalServiceRegistration.externalServiceRegistration ??=
+      this.registry.getTypeByName('ExternalServiceRegistration');
+    const writeInfos: WriteInfo[] = [];
+    const { component } = input;
+    const outputDir = path.join(
+      this.getOutputFolder('source', component),
+      this.context.decomposedExternalServiceRegistration.externalServiceRegistration.directoryName
+    );
+    const xmlContent = { ...(await component.parseXml<ESR>()).ExternalServiceRegistration };
+
+    // Extract schema content
+    const schemaContent: string = xmlContent.schema ?? '';
+    const schemaType = xmlContent.schemaUploadFileExtension ?? this.getSchemaType(schemaContent);
+    const asYaml = schemaType === 'yaml' ? schemaContent : yaml.stringify(JSON.parse(schemaContent));
+    const schemaFileName = `${component.fullName}.yaml`;
+    const schemaFilePath = path.join(path.dirname(outputDir), schemaFileName);
+
+    // make sure the schema type is set
+    xmlContent.schemaUploadFileExtension = schemaType;
+
+    // Write schema content to file
+    writeInfos.push({
+      source: Readable.from(asYaml),
+      output: schemaFilePath,
+    });
+
+    // Remove schema content from ESR content
+    delete xmlContent.schema;
+
+    // Write remaining ESR content to file
+    const esrFileName = `${component.fullName}.externalServiceRegistration`;
+    const esrFilePath = path.join(path.dirname(outputDir), `${esrFileName}${META_XML_SUFFIX}`);
+    const xmlBuilder = new XMLBuilder({
+      format: true,
+      ignoreAttributes: false,
+      suppressUnpairedNode: true,
+      processEntities: true,
+      indentBy: '    ',
+    });
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const source = xmlBuilder.build({ ExternalServiceRegistration: xmlContent });
+    writeInfos.push({
+      source: Readable.from(Buffer.from(xmlDeclaration + source)),
+      output: esrFilePath,
+    });
+
+    return writeInfos;
+  }
+
+  public async toMetadataFormat(component: SourceComponent): Promise<WriteInfo[]> {
+    // only need to do this once
+    this.context.decomposedExternalServiceRegistration.externalServiceRegistration ??=
+      this.registry.getTypeByName('ExternalServiceRegistration');
+    const esrFilePath = component.xml;
+    const esrContent = { ...(await component.parseXml<ESR>()).ExternalServiceRegistration };
+
+    // Read schema content from file
+    const schemaFileName = `${component.fullName}.yaml`; // or .json based on your logic
+    const schemaFilePath = path.join(path.dirname(esrFilePath ?? ''), schemaFileName);
+    // load the schema content from the file
+    const schemaContent = (await component.tree.readFile(schemaFilePath)).toString();
+    // Add schema content back to ESR content in its original format
+    // if the original format was JSON, then convert the yaml to json otherwise leave as is
+    esrContent.schema =
+      esrContent.schemaUploadFileExtension === 'json'
+        ? JSON.stringify(yaml.parse(schemaContent), undefined, 2)
+        : schemaContent;
+
+    // Write combined content back to md format
+    this.context.decomposedExternalServiceRegistration.transactionState.esrRecords.set(component.fullName, {
+      // @ts-expect-error Object literal may only specify known properties
+      [XML_NS_KEY]: XML_DECL,
+      ...esrContent,
+    });
+
+    return [];
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  private getOutputFolder(format: string, component: SourceComponent, mergeWith?: SourceComponent): string {
+    const base = format === 'source' ? DEFAULT_PACKAGE_ROOT_SFDX : '';
+    const { type } = mergeWith ?? component;
+    return path.join(base, type.directoryName);
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  private getSchemaType(content: string): SchemaType {
+    return content.trim().startsWith('{') ? 'json' : 'yaml';
+  }
+}

src/convert/transformers/decomposedPermissionSetTransformer.ts

@@ -68,7 +68,7 @@ export class DecomposedPermissionSetTransformer extends BaseMetadataTransformer
   }
 
   /**
-   * will decomopse a .permissionset into a directory containing files, and an 'objectSettings' folder for object-specific settings
+   * will decompose a .permissionset into a directory containing files, and an 'objectSettings' folder for object-specific settings
    *
    * @param {SourceComponent} component A SourceComponent representing a metadata-formatted permission set
    * @param {SourceComponent | undefined} mergeWith any existing source-formatted permission sets to be merged with, think existing source merging with new information from a retrieve

src/convert/transformers/metadataTransformerFactory.ts

@@ -6,24 +6,22 @@
  */
 import { Messages } from '@salesforce/core';
 import { MetadataTransformer } from '../types';
-import { SourceComponent } from '../../resolve/sourceComponent';
+import { SourceComponent } from '../../resolve';
 import { ConvertContext } from '../convertContext/convertContext';
-import { RegistryAccess } from '../../registry/registryAccess';
+import { RegistryAccess } from '../../registry';
 import { DefaultMetadataTransformer } from './defaultMetadataTransformer';
 import { DecomposedMetadataTransformer } from './decomposedMetadataTransformer';
 import { StaticResourceMetadataTransformer } from './staticResourceMetadataTransformer';
 import { NonDecomposedMetadataTransformer } from './nonDecomposedMetadataTransformer';
 import { LabelMetadataTransformer, LabelsMetadataTransformer } from './decomposeLabelsTransformer';
 import { DecomposedPermissionSetTransformer } from './decomposedPermissionSetTransformer';
+import { DecomposeExternalServiceRegistrationTransformer } from './decomposeExternalServiceRegistrationTransformer';
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/source-deploy-retrieve', 'sdr');
 
 export class MetadataTransformerFactory {
-  private registry: RegistryAccess;
-  private context: ConvertContext;
-
-  public constructor(registry: RegistryAccess, context = new ConvertContext()) {
+  public constructor(private readonly registry: RegistryAccess, private readonly context = new ConvertContext()) {
     this.registry = registry;
     this.context = context;
   }
@@ -48,6 +46,8 @@ export class MetadataTransformerFactory {
         return component.type.name === 'CustomLabels'
           ? new LabelsMetadataTransformer(this.registry, this.context)
           : new LabelMetadataTransformer(this.registry, this.context);
+      case 'decomposeExternalServiceRegistration':
+        return new DecomposeExternalServiceRegistrationTransformer(this.registry, this.context);
       default:
         throw messages.createError('error_missing_transformer', [type.name, transformerId]);
     }

src/registry/presets/decomposeExternalServiceRegistrationBeta.json

@@ -0,0 +1,43 @@
+{
+  "types": {
+    "externalserviceregistration": {
+      "children": {
+        "types": {
+          "yaml": {
+            "strategies": {
+              "adapter": "partiallyDecomposed"
+            },
+            "directoryName": "externalServiceRegistrations",
+            "id": "yaml",
+            "isAddressable": false,
+            "name": "OAS Yaml Schema",
+            "suffix": "yaml",
+            "xmlElementName": "schema"
+          }
+        },
+        "suffixes": {
+          "yaml": "yaml"
+        }
+      },
+      "directoryName": "externalServiceRegistrations",
+      "id": "externalserviceregistration",
+      "ignoreParsedFullName": false,
+      "name": "ExternalServiceRegistration",
+      "strategies": {
+        "adapter": "partiallyDecomposed",
+        "decomposition": "topLevel",
+        "transformer": "decomposeExternalServiceRegistration"
+      },
+      "suffix": "externalServiceRegistration",
+      "supportsPartialDelete": false
+    }
+  },
+  "suffixes": {
+    "yaml": "yaml",
+    "externalServiceRegistration": "externalserviceregistration"
+  },
+  "strictDirectoryNames": {},
+  "childTypes": {
+    "yaml": "externalserviceregistration"
+  }
+}

src/registry/presets/presetMap.ts

@@ -14,6 +14,7 @@ import * as decomposePermissionSetBeta from './decomposePermissionSetBeta.json';
 import * as decomposePermissionSetBeta2 from './decomposePermissionSetBeta2.json';
 import * as decomposeSharingRulesBeta from './decomposeSharingRulesBeta.json';
 import * as decomposeWorkflowBeta from './decomposeWorkflowBeta.json';
+import * as decomposeExternalServiceRegistrationBeta from './decomposeExternalServiceRegistrationBeta.json';
 
 export const presetMap = new Map<string, MetadataRegistry>([
   ['decomposeCustomLabelsBeta2', decomposeCustomLabelsBeta2 as MetadataRegistry],
@@ -22,4 +23,5 @@ export const presetMap = new Map<string, MetadataRegistry>([
   ['decomposePermissionSetBeta2', decomposePermissionSetBeta2 as MetadataRegistry],
   ['decomposeSharingRulesBeta', decomposeSharingRulesBeta as MetadataRegistry],
   ['decomposeWorkflowBeta', decomposeWorkflowBeta as MetadataRegistry],
+  ['decomposeExternalServiceRegistrationBeta', decomposeExternalServiceRegistrationBeta as MetadataRegistry],
 ]);

src/registry/types.ts

@@ -139,14 +139,22 @@ export type MetadataType = {
    * Configuration for resolving and converting components of the type.
    */
   strategies?: {
-    adapter: 'mixedContent' | 'matchingContentFile' | 'decomposed' | 'digitalExperience' | 'bundle' | 'default';
+    adapter:
+      | 'mixedContent'
+      | 'matchingContentFile'
+      | 'decomposed'
+      | 'digitalExperience'
+      | 'bundle'
+      | 'default'
+      | 'partiallyDecomposed';
     transformer?:
       | 'decomposed'
       | 'staticResource'
       | 'nonDecomposed'
       | 'standard'
       | 'decomposedLabels'
-      | 'decomposedPermissionSet';
+      | 'decomposedPermissionSet'
+      | 'decomposeExternalServiceRegistration';
     decomposition?: 'topLevel' | 'folderPerType';
     recomposition?: 'startEmpty';
   };