@uniformdev/transformer 1.1.30 → 1.1.32

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { Command as Command15 } from "commander";
+import { Command as Command16 } from "commander";
 
 // src/cli/commands/propagate-root-component-property.ts
 import { Command } from "commander";
@@ -346,18 +346,31 @@ var ComponentService = class {
     }
     return component;
   }
+  resolveRemoveIds(component, parameterId, options = {}) {
+    const param = this.findParameter(component, parameterId, options);
+    if (!param) return [];
+    if (!this.isGroupParameter(param)) {
+      return [param.id];
+    }
+    const ids = [param.id];
+    for (const childId of param.typeConfig?.childrenParams ?? []) {
+      ids.push(...this.resolveRemoveIds(component, childId, options));
+    }
+    return ids;
+  }
   removeParameter(component, parameterId, options = {}) {
     const { strict = false } = options;
     if (!component.parameters) {
       return component;
     }
+    const idsToRemove = this.resolveRemoveIds(component, parameterId, options);
     component.parameters = component.parameters.filter(
-      (p) => !this.compareIds(p.id, parameterId, strict)
+      (p) => !idsToRemove.some((id) => this.compareIds(p.id, id, strict))
     );
     for (const param of component.parameters) {
       if (this.isGroupParameter(param) && param.typeConfig?.childrenParams) {
         param.typeConfig.childrenParams = param.typeConfig.childrenParams.filter(
-          (id) => !this.compareIds(id, parameterId, strict)
+          (id) => !idsToRemove.some((removeId) => this.compareIds(id, removeId, strict))
         );
       }
     }
@@ -4520,11 +4533,20 @@ var ParameterRemoverService = class {
     if (!param) {
       throw new PropertyNotFoundError(parameterId, componentType);
     }
+    const allIdsToRemove = this.componentService.resolveRemoveIds(component, parameterId, findOptions);
+    const childIds = allIdsToRemove.filter((id) => !this.compareIds(id, parameterId, strict));
     this.logger.action(
       whatIf,
       "REMOVE",
       `Parameter "${parameterId}" from component/${this.fileSystem.getBasename(componentFilePath)}`
     );
+    if (childIds.length > 0) {
+      this.logger.action(
+        whatIf,
+        "REMOVE",
+        `Cascade-removing ${childIds.length} child parameter(s) [${childIds.join(", ")}] from component/${this.fileSystem.getBasename(componentFilePath)}`
+      );
+    }
     let modifiedComponent = this.componentService.removeParameter(component, parameterId, findOptions);
     const beforeGroupCount = modifiedComponent.parameters?.filter(
       (p) => this.componentService.isGroupParameter(p)
@@ -4547,7 +4569,7 @@ var ParameterRemoverService = class {
     const compositionsResult = await this.removeParameterInDirectory(
       fullCompositionsDir,
       componentType,
-      parameterId,
+      allIdsToRemove,
       whatIf,
       strict,
       "composition"
@@ -4555,7 +4577,7 @@ var ParameterRemoverService = class {
     const compositionPatternsResult = await this.removeParameterInDirectory(
       fullCompositionPatternsDir,
       componentType,
-      parameterId,
+      allIdsToRemove,
       whatIf,
       strict,
       "compositionPattern"
@@ -4563,7 +4585,7 @@ var ParameterRemoverService = class {
     const componentPatternsResult = await this.removeParameterInDirectory(
       fullComponentPatternsDir,
       componentType,
-      parameterId,
+      allIdsToRemove,
       whatIf,
       strict,
       "componentPattern"
@@ -4582,7 +4604,7 @@ var ParameterRemoverService = class {
       instancesUpdated: totalInstances
     };
   }
-  async removeParameterInDirectory(directory, componentType, parameterId, whatIf, strict, label) {
+  async removeParameterInDirectory(directory, componentType, parameterIds, whatIf, strict, label) {
     let files;
     try {
       files = await this.fileSystem.findFiles(directory, "**/*.{json,yaml,yml}");
@@ -4607,13 +4629,13 @@ var ParameterRemoverService = class {
       const count = this.removeParameterFromTree(
         composition.composition,
         componentType,
-        parameterId,
+        parameterIds,
         strict
       );
       const overridesCount = this.removeParameterFromOverrides(
         composition,
         componentType,
-        parameterId,
+        parameterIds,
         strict
       );
       const totalCount = count + overridesCount;
@@ -4633,11 +4655,11 @@ var ParameterRemoverService = class {
     }
     return { filesModified, instancesUpdated };
   }
-  removeParameterFromTree(node, componentType, parameterId, strict) {
+  removeParameterFromTree(node, componentType, parameterIds, strict) {
     let count = 0;
     if (this.compareIds(node.type, componentType, strict) && node.parameters) {
-      const removed = this.removeKeyFromMap(node.parameters, parameterId, strict);
-      if (removed) {
+      const removed = this.removeKeysFromMap(node.parameters, parameterIds, strict);
+      if (removed > 0) {
         count++;
       }
     }
@@ -4645,13 +4667,13 @@ var ParameterRemoverService = class {
       for (const slotInstances of Object.values(node.slots)) {
         if (!Array.isArray(slotInstances)) continue;
         for (const instance of slotInstances) {
-          count += this.removeParameterFromTree(instance, componentType, parameterId, strict);
+          count += this.removeParameterFromTree(instance, componentType, parameterIds, strict);
         }
       }
     }
     return count;
   }
-  removeParameterFromOverrides(composition, componentType, parameterId, strict) {
+  removeParameterFromOverrides(composition, componentType, parameterIds, strict) {
     if (!composition.composition._overrides) {
       return 0;
     }
@@ -4660,8 +4682,8 @@ var ParameterRemoverService = class {
       const rootId = composition.composition._id;
       const rootOverrides = composition.composition._overrides[rootId];
       if (rootOverrides?.parameters) {
-        const removed = this.removeKeyFromMap(rootOverrides.parameters, parameterId, strict);
-        if (removed) {
+        const removed = this.removeKeysFromMap(rootOverrides.parameters, parameterIds, strict);
+        if (removed > 0) {
           count++;
         }
       }
@@ -4671,14 +4693,14 @@ var ParameterRemoverService = class {
       composition.composition,
       composition.composition._overrides,
       componentType,
-      parameterId,
+      parameterIds,
       strict,
       counter
     );
     count += counter.count;
     return count;
   }
-  removeOverridesForMatchingInstances(node, overrides, componentType, parameterId, strict, counter) {
+  removeOverridesForMatchingInstances(node, overrides, componentType, parameterIds, strict, counter) {
     if (node.slots) {
       for (const slotInstances of Object.values(node.slots)) {
         if (!Array.isArray(slotInstances)) continue;
@@ -4686,8 +4708,8 @@ var ParameterRemoverService = class {
           if (this.compareIds(instance.type, componentType, strict) && instance._id) {
             const instanceOverrides = overrides[instance._id];
             if (instanceOverrides?.parameters) {
-              const removed = this.removeKeyFromMap(instanceOverrides.parameters, parameterId, strict);
-              if (removed) {
+              const removed = this.removeKeysFromMap(instanceOverrides.parameters, parameterIds, strict);
+              if (removed > 0) {
                 counter.count++;
               }
             }
@@ -4696,7 +4718,7 @@ var ParameterRemoverService = class {
             instance,
             overrides,
             componentType,
-            parameterId,
+            parameterIds,
             strict,
             counter
           );
@@ -4704,15 +4726,16 @@ var ParameterRemoverService = class {
       }
     }
   }
-  removeKeyFromMap(map, key, strict) {
-    const matchingKey = Object.keys(map).find(
-      (k) => this.compareIds(k, key, strict)
-    );
-    if (!matchingKey) {
-      return false;
+  removeKeysFromMap(map, keys, strict) {
+    let removed = 0;
+    for (const key of keys) {
+      const matchingKey = Object.keys(map).find((k) => this.compareIds(k, key, strict));
+      if (matchingKey) {
+        delete map[matchingKey];
+        removed++;
+      }
     }
-    delete map[matchingKey];
-    return true;
+    return removed;
   }
 };
 
@@ -4774,8 +4797,9 @@ import { Command as Command12 } from "commander";
 
 // src/core/services/field-remover.service.ts
 var FieldRemoverService = class {
-  constructor(fileSystem, logger) {
+  constructor(fileSystem, componentService, logger) {
     this.fileSystem = fileSystem;
+    this.componentService = componentService;
     this.logger = logger;
   }
   compareIds(id1, id2, strict) {
@@ -4787,6 +4811,7 @@ var FieldRemoverService = class {
   async remove(options) {
     const {
       rootDir,
+      componentsDir,
       compositionsDir,
       compositionPatternsDir,
       componentPatternsDir,
@@ -4795,14 +4820,29 @@ var FieldRemoverService = class {
       whatIf,
       strict
     } = options;
+    const findOptions = { strict };
+    const fullComponentsDir = this.fileSystem.resolvePath(rootDir, componentsDir);
     const fullCompositionsDir = this.fileSystem.resolvePath(rootDir, compositionsDir);
     const fullCompositionPatternsDir = this.fileSystem.resolvePath(rootDir, compositionPatternsDir);
     const fullComponentPatternsDir = this.fileSystem.resolvePath(rootDir, componentPatternsDir);
+    let allIdsToRemove = [parameterId];
+    try {
+      const { component } = await this.componentService.loadComponent(fullComponentsDir, componentType, findOptions);
+      const resolved = this.componentService.resolveRemoveIds(component, parameterId, findOptions);
+      if (resolved.length > 0) {
+        allIdsToRemove = resolved;
+      }
+    } catch {
+    }
+    const childIds = allIdsToRemove.filter((id) => id.toLowerCase() !== parameterId.toLowerCase());
+    if (childIds.length > 0) {
+      this.logger.info(`Cascade-removing ${childIds.length} child field(s) [${childIds.join(", ")}] along with "${parameterId}"`);
+    }
     this.logger.info(`Removing field "${parameterId}" from instances of ${componentType}`);
     const compositionsResult = await this.removeFieldInDirectory(
       fullCompositionsDir,
       componentType,
-      parameterId,
+      allIdsToRemove,
       whatIf,
       strict,
       "composition"
@@ -4810,7 +4850,7 @@ var FieldRemoverService = class {
     const compositionPatternsResult = await this.removeFieldInDirectory(
       fullCompositionPatternsDir,
       componentType,
-      parameterId,
+      allIdsToRemove,
       whatIf,
       strict,
       "compositionPattern"
@@ -4818,7 +4858,7 @@ var FieldRemoverService = class {
     const componentPatternsResult = await this.removeFieldInDirectory(
       fullComponentPatternsDir,
       componentType,
-      parameterId,
+      allIdsToRemove,
       whatIf,
       strict,
       "componentPattern"
@@ -4836,7 +4876,7 @@ var FieldRemoverService = class {
       instancesUpdated: totalInstances
     };
   }
-  async removeFieldInDirectory(directory, componentType, parameterId, whatIf, strict, label) {
+  async removeFieldInDirectory(directory, componentType, parameterIds, whatIf, strict, label) {
     let files;
     try {
       files = await this.fileSystem.findFiles(directory, "**/*.{json,yaml,yml}");
@@ -4861,13 +4901,13 @@ var FieldRemoverService = class {
       const treeCount = this.removeFieldFromTree(
         composition.composition,
         componentType,
-        parameterId,
+        parameterIds,
         strict
       );
       const overridesCount = this.removeFieldFromOverrides(
         composition,
         componentType,
-        parameterId,
+        parameterIds,
         strict
       );
       const totalCount = treeCount + overridesCount;
@@ -4887,11 +4927,11 @@ var FieldRemoverService = class {
     }
     return { filesModified, instancesUpdated };
   }
-  removeFieldFromTree(node, componentType, parameterId, strict) {
+  removeFieldFromTree(node, componentType, parameterIds, strict) {
     let count = 0;
     if (this.compareIds(node.type, componentType, strict) && node.parameters) {
-      const removed = this.removeKeyFromMap(node.parameters, parameterId, strict);
-      if (removed) {
+      const removed = this.removeKeysFromMap(node.parameters, parameterIds, strict);
+      if (removed > 0) {
         count++;
       }
     }
@@ -4899,13 +4939,13 @@ var FieldRemoverService = class {
       for (const slotInstances of Object.values(node.slots)) {
         if (!Array.isArray(slotInstances)) continue;
         for (const instance of slotInstances) {
-          count += this.removeFieldFromTree(instance, componentType, parameterId, strict);
+          count += this.removeFieldFromTree(instance, componentType, parameterIds, strict);
         }
       }
     }
     return count;
   }
-  removeFieldFromOverrides(composition, componentType, parameterId, strict) {
+  removeFieldFromOverrides(composition, componentType, parameterIds, strict) {
     if (!composition.composition._overrides) {
       return 0;
     }
@@ -4914,8 +4954,8 @@ var FieldRemoverService = class {
       const rootId = composition.composition._id;
       const rootOverrides = composition.composition._overrides[rootId];
       if (rootOverrides?.parameters) {
-        const removed = this.removeKeyFromMap(rootOverrides.parameters, parameterId, strict);
-        if (removed) {
+        const removed = this.removeKeysFromMap(rootOverrides.parameters, parameterIds, strict);
+        if (removed > 0) {
           count++;
         }
       }
@@ -4924,12 +4964,12 @@ var FieldRemoverService = class {
       composition.composition,
       composition.composition._overrides,
       componentType,
-      parameterId,
+      parameterIds,
       strict
     );
     return count;
   }
-  removeOverridesForMatchingInstances(node, overrides, componentType, parameterId, strict) {
+  removeOverridesForMatchingInstances(node, overrides, componentType, parameterIds, strict) {
     let count = 0;
     if (node.slots) {
       for (const slotInstances of Object.values(node.slots)) {
@@ -4938,8 +4978,8 @@ var FieldRemoverService = class {
           if (this.compareIds(instance.type, componentType, strict) && instance._id) {
             const instanceOverrides = overrides[instance._id];
             if (instanceOverrides?.parameters) {
-              const removed = this.removeKeyFromMap(instanceOverrides.parameters, parameterId, strict);
-              if (removed) {
+              const removed = this.removeKeysFromMap(instanceOverrides.parameters, parameterIds, strict);
+              if (removed > 0) {
                 count++;
               }
             }
@@ -4948,7 +4988,7 @@ var FieldRemoverService = class {
             instance,
             overrides,
             componentType,
-            parameterId,
+            parameterIds,
             strict
           );
         }
@@ -4956,15 +4996,16 @@ var FieldRemoverService = class {
     }
     return count;
   }
-  removeKeyFromMap(map, key, strict) {
-    const matchingKey = Object.keys(map).find(
-      (k) => this.compareIds(k, key, strict)
-    );
-    if (!matchingKey) {
-      return false;
+  removeKeysFromMap(map, keys, strict) {
+    let removed = 0;
+    for (const key of keys) {
+      const matchingKey = Object.keys(map).find((k) => this.compareIds(k, key, strict));
+      if (matchingKey) {
+        delete map[matchingKey];
+        removed++;
+      }
     }
-    delete map[matchingKey];
-    return true;
+    return removed;
   }
 };
 
@@ -4993,10 +5034,12 @@ function createRemoveFieldCommand() {
     };
     const logger = new Logger();
     const fileSystem = new FileSystemService();
-    const remover = new FieldRemoverService(fileSystem, logger);
+    const componentService = new ComponentService(fileSystem);
+    const remover = new FieldRemoverService(fileSystem, componentService, logger);
     try {
       const result = await remover.remove({
         rootDir: options.rootDir,
+        componentsDir: options.componentsDir,
         compositionsDir: options.compositionsDir,
         compositionPatternsDir: options.compositionPatternsDir,
         componentPatternsDir: options.componentPatternsDir,
@@ -5334,10 +5377,422 @@ function createAddContentTypeFieldCommand() {
   return command;
 }
 
+// src/cli/commands/flatten-block-field.ts
+import { Command as Command15 } from "commander";
+
+// src/core/services/block-field-flattener.service.ts
+var BlockFieldFlattenerService = class {
+  constructor(fileSystem, componentService, logger) {
+    this.fileSystem = fileSystem;
+    this.componentService = componentService;
+    this.logger = logger;
+  }
+  compareIds(id1, id2, strict) {
+    if (strict) return id1 === id2;
+    return id1.toLowerCase() === id2.toLowerCase();
+  }
+  async loadContentType(contentTypesDir, contentTypeId, strict) {
+    const jsonPath = this.fileSystem.joinPath(contentTypesDir, `${contentTypeId}.json`);
+    const yamlPath = this.fileSystem.joinPath(contentTypesDir, `${contentTypeId}.yaml`);
+    const ymlPath = this.fileSystem.joinPath(contentTypesDir, `${contentTypeId}.yml`);
+    if (await this.fileSystem.fileExists(jsonPath)) {
+      return { contentType: await this.fileSystem.readFile(jsonPath), filePath: jsonPath };
+    }
+    if (await this.fileSystem.fileExists(yamlPath)) {
+      return { contentType: await this.fileSystem.readFile(yamlPath), filePath: yamlPath };
+    }
+    if (await this.fileSystem.fileExists(ymlPath)) {
+      return { contentType: await this.fileSystem.readFile(ymlPath), filePath: ymlPath };
+    }
+    if (!strict) {
+      const files = await this.fileSystem.findFiles(contentTypesDir, "*.{json,yaml,yml}");
+      for (const filePath of files) {
+        const basename2 = this.fileSystem.getBasename(filePath);
+        const nameWithoutExt = basename2.replace(/\.(json|yaml|yml)$/i, "");
+        if (nameWithoutExt.toLowerCase() === contentTypeId.toLowerCase()) {
+          return { contentType: await this.fileSystem.readFile(filePath), filePath };
+        }
+      }
+    }
+    throw new TransformError(`Content type not found: ${contentTypeId} (searched: ${contentTypesDir})`);
+  }
+  async flatten(options) {
+    const {
+      rootDir,
+      componentsDir,
+      compositionsDir,
+      compositionPatternsDir,
+      componentPatternsDir,
+      contentTypesDir,
+      componentId,
+      parameterId,
+      whatIf,
+      strict,
+      excludeFields = []
+    } = options;
+    const findOptions = { strict };
+    const fullComponentsDir = this.fileSystem.resolvePath(rootDir, componentsDir);
+    const fullCompositionsDir = this.fileSystem.resolvePath(rootDir, compositionsDir);
+    const fullCompositionPatternsDir = this.fileSystem.resolvePath(rootDir, compositionPatternsDir);
+    const fullComponentPatternsDir = this.fileSystem.resolvePath(rootDir, componentPatternsDir);
+    const fullContentTypesDir = this.fileSystem.resolvePath(rootDir, contentTypesDir);
+    this.logger.info(`Loading component: ${componentId}`);
+    const { component, filePath: componentFilePath } = await this.componentService.loadComponent(fullComponentsDir, componentId, findOptions);
+    const blockParam = this.componentService.findParameter(component, parameterId, findOptions);
+    if (!blockParam) {
+      throw new PropertyNotFoundError(parameterId, componentId);
+    }
+    const allowedTypes = blockParam.typeConfig?.allowedTypes;
+    if (!allowedTypes || allowedTypes.length === 0) {
+      throw new TransformError(
+        `Parameter "${parameterId}" on component "${componentId}" has no allowedTypes in typeConfig`
+      );
+    }
+    if (allowedTypes.length > 1) {
+      throw new TransformError(
+        `Cannot flatten: parameter "${parameterId}" allows multiple block types: ${allowedTypes.join(", ")}`
+      );
+    }
+    const blockContentTypeId = allowedTypes[0];
+    this.logger.info(`Block content type: ${blockContentTypeId}`);
+    const { contentType: blockContentType } = await this.loadContentType(fullContentTypesDir, blockContentTypeId, strict);
+    const excludeSet = new Set(excludeFields.map((id) => id.toLowerCase()));
+    const blockFields = (blockContentType.fields ?? []).filter(
+      (f) => !excludeSet.has(f.id.toLowerCase())
+    );
+    const blockFieldIds = blockFields.map((f) => f.id);
+    this.logger.info(
+      `Block content type: ${blockContentTypeId} (${blockFields.length} field(s): ${blockFieldIds.join(", ")})`
+    );
+    for (const field of blockFields) {
+      const existingParam = this.componentService.findParameter(component, field.id, findOptions);
+      if (existingParam && !this.compareIds(existingParam.id, parameterId, strict)) {
+        throw new TransformError(
+          `Cannot flatten: field "${field.id}" from block type "${blockContentTypeId}" conflicts with existing parameter "${existingParam.id}" on component "${componentId}"`
+        );
+      }
+    }
+    this.logger.info("Validation pass: scanning compositions...");
+    await this.validateDirectory(fullCompositionsDir, componentId, parameterId, strict, "composition");
+    await this.validateDirectory(fullCompositionPatternsDir, componentId, parameterId, strict, "compositionPattern");
+    await this.validateDirectory(fullComponentPatternsDir, componentId, parameterId, strict, "componentPattern");
+    this.logger.action(
+      whatIf,
+      "REMOVE",
+      `parameter "${parameterId}" from component/${this.fileSystem.getBasename(componentFilePath)}`
+    );
+    this.logger.action(
+      whatIf,
+      "ADD",
+      `parameters "${blockFieldIds.join(", ")}" to component/${this.fileSystem.getBasename(componentFilePath)}`
+    );
+    let updatedComponent = this.componentService.removeParameter(component, parameterId, findOptions);
+    updatedComponent = this.componentService.removeEmptyGroups(updatedComponent);
+    for (const field of blockFields) {
+      updatedComponent = this.componentService.addParameterToComponent(
+        updatedComponent,
+        { id: field.id, name: field.name, type: field.type, ...field.typeConfig ? { typeConfig: field.typeConfig } : {}, ...this.extraFieldProps(field) },
+        findOptions
+      );
+    }
+    if (!whatIf) {
+      await this.componentService.saveComponent(componentFilePath, updatedComponent);
+    }
+    const compositionsResult = await this.flattenInDirectory(
+      fullCompositionsDir,
+      componentId,
+      parameterId,
+      whatIf,
+      strict,
+      "composition"
+    );
+    const compositionPatternsResult = await this.flattenInDirectory(
+      fullCompositionPatternsDir,
+      componentId,
+      parameterId,
+      whatIf,
+      strict,
+      "compositionPattern"
+    );
+    const componentPatternsResult = await this.flattenInDirectory(
+      fullComponentPatternsDir,
+      componentId,
+      parameterId,
+      whatIf,
+      strict,
+      "componentPattern"
+    );
+    const totalFiles = compositionsResult.filesModified + compositionPatternsResult.filesModified + componentPatternsResult.filesModified;
+    const totalInstances = compositionsResult.instancesUpdated + compositionPatternsResult.instancesUpdated + componentPatternsResult.instancesUpdated;
+    this.logger.info("");
+    this.logger.info(
+      `Summary: 1 component definition updated, ${totalFiles} file(s) (${totalInstances} instance(s)) updated.`
+    );
+    return {
+      componentDefinitionUpdated: true,
+      compositionsModified: compositionsResult.filesModified,
+      compositionPatternsModified: compositionPatternsResult.filesModified,
+      componentPatternsModified: componentPatternsResult.filesModified,
+      instancesUpdated: totalInstances
+    };
+  }
+  // Extract extra field props beyond id, name, type, typeConfig
+  extraFieldProps(field) {
+    const { id: _id, name: _name, type: _type, typeConfig: _tc, ...rest } = field;
+    return rest;
+  }
+  async validateDirectory(directory, componentId, parameterId, strict, label) {
+    let files;
+    try {
+      files = await this.fileSystem.findFiles(directory, "**/*.{json,yaml,yml}");
+    } catch {
+      return;
+    }
+    for (const filePath of files) {
+      let composition;
+      try {
+        composition = await this.fileSystem.readFile(filePath);
+      } catch {
+        continue;
+      }
+      if (!composition?.composition) continue;
+      this.validateBlocksInTree(composition.composition, componentId, parameterId, strict, filePath, label);
+      this.validateBlocksInOverrides(composition, componentId, parameterId, strict, filePath, label);
+    }
+  }
+  validateBlocksInTree(node, componentId, parameterId, strict, filePath, label) {
+    if (this.compareIds(node.type, componentId, strict) && node.parameters) {
+      const blockParamValue = this.findKeyInMap(node.parameters, parameterId, strict);
+      if (blockParamValue) {
+        const items = blockParamValue.value;
+        if (Array.isArray(items) && items.length > 1) {
+          throw new TransformError(
+            `Cannot flatten: more than one block item in parameter "${parameterId}" of "${componentId}" instance "${node._id ?? "(root)"}" in file "${label}/${this.fileSystem.getBasename(filePath)}"`
+          );
+        }
+      }
+    }
+    if (node.slots) {
+      for (const slotInstances of Object.values(node.slots)) {
+        if (!Array.isArray(slotInstances)) continue;
+        for (const instance of slotInstances) {
+          this.validateBlocksInTree(instance, componentId, parameterId, strict, filePath, label);
+        }
+      }
+    }
+  }
+  validateBlocksInOverrides(composition, componentId, parameterId, strict, filePath, label) {
+    if (!composition.composition._overrides) return;
+    for (const [overrideId, override] of Object.entries(composition.composition._overrides)) {
+      if (!override.parameters) continue;
+      const blockParamValue = this.findKeyInMap(override.parameters, parameterId, strict);
+      if (blockParamValue) {
+        const items = blockParamValue.value;
+        if (Array.isArray(items) && items.length > 1) {
+          throw new TransformError(
+            `Cannot flatten: more than one block item in _overrides["${overrideId}"] parameter "${parameterId}" in file "${label}/${this.fileSystem.getBasename(filePath)}"`
+          );
+        }
+      }
+    }
+  }
+  async flattenInDirectory(directory, componentId, parameterId, whatIf, strict, label) {
+    let files;
+    try {
+      files = await this.fileSystem.findFiles(directory, "**/*.{json,yaml,yml}");
+    } catch {
+      return { filesModified: 0, instancesUpdated: 0 };
+    }
+    if (files.length === 0) return { filesModified: 0, instancesUpdated: 0 };
+    let filesModified = 0;
+    let instancesUpdated = 0;
+    for (const filePath of files) {
+      let composition;
+      try {
+        composition = await this.fileSystem.readFile(filePath);
+      } catch {
+        continue;
+      }
+      if (!composition?.composition) continue;
+      const treeCount = this.flattenBlocksInTree(composition.composition, componentId, parameterId, strict);
+      const overridesCount = this.flattenBlocksInOverrides(composition, componentId, parameterId, strict);
+      const totalCount = treeCount + overridesCount;
+      if (totalCount > 0) {
+        const relativePath = filePath.replace(directory, "").replace(/^[/\\]/, "");
+        this.logger.action(
+          whatIf,
+          "UPDATE",
+          `${label}/${relativePath} (${totalCount} instance(s) of ${componentId})`
+        );
+        if (!whatIf) {
+          await this.fileSystem.writeFile(filePath, composition);
+        }
+        filesModified++;
+        instancesUpdated += totalCount;
+      }
+    }
+    return { filesModified, instancesUpdated };
+  }
+  flattenBlocksInTree(node, componentId, parameterId, strict) {
+    let count = 0;
+    if (this.compareIds(node.type, componentId, strict) && node.parameters) {
+      const matchingKey = this.findKeyName(node.parameters, parameterId, strict);
+      if (matchingKey !== void 0) {
+        const blockParamValue = node.parameters[matchingKey];
+        const items = blockParamValue.value;
+        if (Array.isArray(items) && items.length === 1) {
+          const blockItem = items[0];
+          for (const [fieldId, fieldValue] of Object.entries(blockItem.fields ?? {})) {
+            node.parameters[fieldId] = fieldValue;
+          }
+        }
+        delete node.parameters[matchingKey];
+        count++;
+      }
+    }
+    if (node.slots) {
+      for (const slotInstances of Object.values(node.slots)) {
+        if (!Array.isArray(slotInstances)) continue;
+        for (const instance of slotInstances) {
+          count += this.flattenBlocksInTree(instance, componentId, parameterId, strict);
+        }
+      }
+    }
+    return count;
+  }
+  flattenBlocksInOverrides(composition, componentId, parameterId, strict) {
+    if (!composition.composition._overrides) return 0;
+    let count = 0;
+    if (this.compareIds(composition.composition.type, componentId, strict)) {
+      count += this.flattenOverrideMap(composition.composition._overrides, parameterId, strict);
+    }
+    count += this.flattenOverridesForMatchingInstances(
+      composition.composition,
+      composition.composition._overrides,
+      componentId,
+      parameterId,
+      strict
+    );
+    return count;
+  }
+  flattenOverrideMap(overrides, parameterId, strict) {
+    let count = 0;
+    for (const override of Object.values(overrides)) {
+      if (!override.parameters) continue;
+      const matchingKey = this.findKeyName(override.parameters, parameterId, strict);
+      if (matchingKey === void 0) continue;
+      const blockParamValue = override.parameters[matchingKey];
+      const items = blockParamValue.value;
+      if (Array.isArray(items) && items.length === 1) {
+        const blockItem = items[0];
+        for (const [fieldId, fieldValue] of Object.entries(blockItem.fields ?? {})) {
+          override.parameters[fieldId] = fieldValue;
+        }
+      }
+      delete override.parameters[matchingKey];
+      count++;
+    }
+    return count;
+  }
+  flattenOverridesForMatchingInstances(node, overrides, componentId, parameterId, strict) {
+    let count = 0;
+    if (node.slots) {
+      for (const slotInstances of Object.values(node.slots)) {
+        if (!Array.isArray(slotInstances)) continue;
+        for (const instance of slotInstances) {
+          if (this.compareIds(instance.type, componentId, strict) && instance._id) {
+            const override = overrides[instance._id];
+            if (override?.parameters) {
+              const matchingKey = this.findKeyName(override.parameters, parameterId, strict);
+              if (matchingKey !== void 0) {
+                const blockParamValue = override.parameters[matchingKey];
+                const items = blockParamValue.value;
+                if (Array.isArray(items) && items.length === 1) {
+                  const blockItem = items[0];
+                  for (const [fieldId, fieldValue] of Object.entries(blockItem.fields ?? {})) {
+                    override.parameters[fieldId] = fieldValue;
+                  }
+                }
+                delete override.parameters[matchingKey];
+                count++;
+              }
+            }
+          }
+          count += this.flattenOverridesForMatchingInstances(instance, overrides, componentId, parameterId, strict);
+        }
+      }
+    }
+    return count;
+  }
+  findKeyName(map, key, strict) {
+    return Object.keys(map).find((k) => this.compareIds(k, key, strict));
+  }
+  findKeyInMap(map, key, strict) {
+    const k = this.findKeyName(map, key, strict);
+    return k !== void 0 ? map[k] : void 0;
+  }
+};
+
+// src/cli/commands/flatten-block-field.ts
+function createFlattenBlockFieldCommand() {
+  const command = new Command15("flatten-block-field");
+  command.description(
+    "Dissolves a $block parameter by lifting the block content type fields onto the component and extracting block item values into composition instances directly."
+  ).option("--componentId <id>", "The ID of the component that owns the block parameter").option("--parameterId <id>", "The ID of the $block parameter to flatten").option("--excludeFields <ids>", "Comma-separated list of block content type field IDs to skip when flattening").hook("preAction", (thisCommand) => {
+    const opts = thisCommand.opts();
+    const requiredOptions = [
+      { name: "componentId", flag: "--componentId" },
+      { name: "parameterId", flag: "--parameterId" }
+    ];
+    const missing = requiredOptions.filter((opt) => !opts[opt.name]).map((opt) => opt.flag);
+    if (missing.length > 0) {
+      console.error(`error: missing required options: ${missing.join(", ")}`);
+      process.exit(1);
+    }
+  }).action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const options = {
+      ...globalOpts,
+      componentId: opts.componentId,
+      parameterId: opts.parameterId,
+      excludeFields: opts.excludeFields
+    };
+    const logger = new Logger();
+    const fileSystem = new FileSystemService();
+    const componentService = new ComponentService(fileSystem);
+    const flattener = new BlockFieldFlattenerService(fileSystem, componentService, logger);
+    try {
+      const result = await flattener.flatten({
+        rootDir: options.rootDir,
+        componentsDir: options.componentsDir,
+        compositionsDir: options.compositionsDir,
+        compositionPatternsDir: options.compositionPatternsDir,
+        componentPatternsDir: options.componentPatternsDir,
+        contentTypesDir: options.contentTypesDir,
+        componentId: options.componentId,
+        parameterId: options.parameterId,
+        whatIf: options.whatIf ?? false,
+        strict: options.strict ?? false,
+        excludeFields: options.excludeFields ? options.excludeFields.split(",").map((s) => s.trim()) : []
+      });
+      logger.success(
+        `Flattened parameter "${options.parameterId}" on component "${options.componentId}": ${result.compositionsModified} composition(s), ${result.compositionPatternsModified} composition pattern(s), ${result.componentPatternsModified} component pattern(s) updated`
+      );
+    } catch (error) {
+      if (error instanceof TransformError) {
+        logger.error(error.message);
+        process.exit(1);
+      }
+      throw error;
+    }
+  });
+  return command;
+}
+
 // package.json
 var package_default = {
   name: "@uniformdev/transformer",
-  version: "1.1.30",
+  version: "1.1.32",
   description: "CLI tool for transforming Uniform.dev serialization files offline",
   type: "module",
   bin: {
@@ -5406,7 +5861,7 @@ var package_default = {
 };
 
 // src/cli/index.ts
-var program = new Command15();
+var program = new Command16();
 var appVersion = package_default.version;
 console.error(`uniform-transform v${appVersion}`);
 program.name("uniform-transform").description("CLI tool for transforming Uniform.dev serialization files offline").version(appVersion);
@@ -5433,5 +5888,6 @@ program.addCommand(createRemoveParameterCommand());
 program.addCommand(createRemoveFieldCommand());
 program.addCommand(createAddComponentParameterCommand());
 program.addCommand(createAddContentTypeFieldCommand());
+program.addCommand(createFlattenBlockFieldCommand());
 program.parse();
 //# sourceMappingURL=index.js.map