storyblok 4.20.0-alpha.0 → 4.20.0

package/dist/index.mjs

@@ -698,6 +698,8 @@ const API_ACTIONS = {
   pull_component_internal_tags: "Failed to pull component internal tags",
   push_component: "Failed to push component",
   push_component_group: "Failed to push component group",
+  push_component_folder: "Failed to create component folder",
+  delete_component_folder: "Failed to delete component folder",
   push_component_preset: "Failed to push component preset",
   push_component_internal_tag: "Failed to push component internal tag",
   update_component: "Failed to update component",
@@ -806,7 +808,11 @@ class APIError extends Error {
     if (this.code === 422) {
       const responseData = this.response?.data;
       if (responseData?.name?.[0] === "has already been taken") {
-        this.message = "A component with this name already exists";
+        if (action === "push_component_folder") {
+          this.message = "A component folder with this name already exists";
+        } else if (action === "push_component" || action === "update_component") {
+          this.message = "A component with this name already exists";
+        }
       }
       Object.entries(responseData || {}).forEach(([key, errors]) => {
         if (Array.isArray(errors)) {
@@ -5826,10 +5832,8 @@ const getPropertyTypeAnnotation = (property, prefix, suffix) => {
     return { type: property.type };
   }
   let type = "unknown";
-  const options = property.options && property.options.length > 0 ? property.options.map((item) => item.value) : [];
-  if (options.length > 0 && property.exclude_empty_option !== true) {
-    options.unshift("");
-  }
+  const optionValues = property.options && property.options.length > 0 ? property.options.map((item) => item.value).filter((value) => value !== "") : [];
+  const options = optionValues.length > 0 && !property.required ? ["", ...optionValues] : optionValues;
   if (property.source === "internal_stories") {
     if (property.filter_content_type) {
       return {
@@ -6182,11 +6186,18 @@ const generateStoryblokTypes = async (options = {}) => {
 const pushDatasource = async (spaceId, datasource) => {
   try {
     const client = getMapiClient();
+    const { dimensions, ...datasourceFields } = datasource;
+    const dimensionsAttributes = (dimensions ?? []).filter((dimension) => dimension.entry_value).map((dimension) => ({ name: dimension.name ?? dimension.entry_value ?? "", entry_value: dimension.entry_value ?? "" }));
     const { data } = await client.datasources.create({
       path: {
         space_id: Number(spaceId)
       },
-      body: { datasource },
+      body: {
+        datasource: {
+          ...datasourceFields,
+          ...dimensionsAttributes.length > 0 && { dimensions_attributes: dimensionsAttributes }
+        }
+      },
       throwOnError: true
     });
     return data.datasource;
@@ -6221,13 +6232,14 @@ const upsertDatasource = async (space, datasource, existingId) => {
 const pushDatasourceEntry = async (spaceId, datasourceId, entry, position) => {
   try {
     const client = getMapiClient();
+    const { dimension_values, ...entryFields } = entry;
     const { data } = await client.datasourceEntries.create({
       path: {
         space_id: Number(spaceId)
       },
       body: {
         datasource_entry: {
-          ...entry,
+          ...entryFields,
           value: entry.value ?? "",
           datasource_id: datasourceId,
           ...position != null && { position }
@@ -6243,13 +6255,14 @@ const pushDatasourceEntry = async (spaceId, datasourceId, entry, position) => {
 const updateDatasourceEntry = async (spaceId, entryId, entry, position) => {
   try {
     const client = getMapiClient();
+    const { dimension_values, ...entryFields } = entry;
     await client.datasourceEntries.update(entryId, {
       path: {
         space_id: Number(spaceId)
       },
       body: {
         datasource_entry: {
-          ...entry,
+          ...entryFields,
           ...position != null && { position }
         }
       },
@@ -6259,6 +6272,27 @@ const updateDatasourceEntry = async (spaceId, entryId, entry, position) => {
     handleAPIError("update_datasource", error, `Failed to update datasource entry ${entry.name}`);
   }
 };
+const updateDatasourceEntryDimension = async (spaceId, entryId, entry, dimensionId, dimensionValue) => {
+  try {
+    const client = getMapiClient();
+    await client.datasourceEntries.update(entryId, {
+      path: {
+        space_id: Number(spaceId)
+      },
+      query: { dimension_id: dimensionId },
+      body: {
+        datasource_entry: {
+          name: entry.name,
+          value: entry.value ?? "",
+          dimension_value: dimensionValue
+        }
+      },
+      throwOnError: true
+    });
+  } catch (error) {
+    handleAPIError("update_datasource", error, `Failed to update datasource entry ${entry.name} for dimension ${dimensionId}`);
+  }
+};
 const upsertDatasourceEntry = async (space, datasourceId, entry, existingId, position) => {
   if (existingId) {
     await updateDatasourceEntry(space, existingId, entry, position);
@@ -6418,7 +6452,7 @@ const datasourcesCommand = program$7.command(commands.DATASOURCES).alias("ds").d
 
 const DEFAULT_DATASOURCES_FILENAME = "datasources";
 
-const fetchDatasourceEntries = async (spaceId, datasourceId) => {
+const fetchDatasourceEntries = async (spaceId, datasourceId, dimensionId) => {
   try {
     const client = getMapiClient();
     return await fetchAllPages(
@@ -6428,7 +6462,9 @@ const fetchDatasourceEntries = async (spaceId, datasourceId) => {
         },
         query: {
           datasource_id: datasourceId,
-          page
+          page,
+          // MAPI matches `dimension` against the numeric dimension id.
+          ...dimensionId != null && { dimension: dimensionId }
         },
         throwOnError: true
       }),
@@ -6438,6 +6474,34 @@ const fetchDatasourceEntries = async (spaceId, datasourceId) => {
     handleAPIError("pull_datasources", error);
   }
 };
+const fetchDatasourceEntriesWithDimensions = async (spaceId, datasource) => {
+  const defaultEntries = await fetchDatasourceEntries(spaceId, datasource.id) ?? [];
+  const entries = defaultEntries.map(({ dimension_value, ...rest }) => rest);
+  const dimensions = datasource.dimensions ?? [];
+  if (!dimensions.length) {
+    return entries;
+  }
+  const entriesById = new Map(entries.map((entry) => [entry.id, entry]));
+  for (const dimension of dimensions) {
+    if (dimension.id == null || !dimension.entry_value) {
+      continue;
+    }
+    const dimensionEntries = await fetchDatasourceEntries(spaceId, datasource.id, dimension.id) ?? [];
+    for (const dimensionEntry of dimensionEntries) {
+      const value = dimensionEntry.dimension_value;
+      if (!value) {
+        continue;
+      }
+      const entry = entriesById.get(dimensionEntry.id);
+      if (!entry) {
+        continue;
+      }
+      entry.dimension_values ??= {};
+      entry.dimension_values[dimension.entry_value] = value;
+    }
+  }
+  return entries;
+};
 const fetchDatasources = async (spaceId) => {
   try {
     const client = getMapiClient();
@@ -6458,7 +6522,7 @@ const fetchDatasources = async (spaceId) => {
         if (!ds.id) {
           return { ...ds, entries: [] };
         }
-        const entries = await fetchDatasourceEntries(spaceId, ds.id);
+        const entries = await fetchDatasourceEntriesWithDimensions(spaceId, ds);
         return { ...ds, entries };
       })
     );
@@ -6487,8 +6551,8 @@ const fetchDatasource = async (spaceId, datasourceName) => {
     if (!found) {
       return void 0;
     }
-    const entries = await fetchDatasourceEntries(spaceId, found.id);
-    return { ...found, entries: entries || [] };
+    const entries = await fetchDatasourceEntriesWithDimensions(spaceId, found);
+    return { ...found, entries };
   } catch (error) {
     handleAPIError("pull_datasources", error, `Failed to fetch datasource ${datasourceName}`);
   }
@@ -6586,6 +6650,14 @@ pullCmd$2.action(async (datasourceName, options, command) => {
   }
 });
 
+function dimensionValuesEqual(a, b) {
+  const aKeys = Object.keys(a ?? {});
+  const bKeys = Object.keys(b ?? {});
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+  return aKeys.every((key) => a?.[key] === b?.[key]);
+}
 const pushCmd$2 = datasourcesCommand.command("push [datasourceName]").description(`Push your space's datasources schema as json`).option("-f, --from <from>", "source space id").option("--fi, --filter <filter>", "glob filter to apply to the datasources before pushing").option("--sf, --separate-files", "Read from separate files instead of consolidated files").option("--su, --suffix <suffix>", "Load only files matching *.<suffix>.json (e.g. datasources.dev.json)").option("-s, --space <space>", "space ID");
 pushCmd$2.action(async (datasourceName, options, command) => {
   konsola.title(`${commands.DATASOURCES}`, colorPalette.DATASOURCES, datasourceName ? `Pushing datasource ${datasourceName}...` : "Pushing datasources...");
@@ -6657,19 +6729,39 @@ pushCmd$2.action(async (datasourceName, options, command) => {
         results.successful.push(datasource.name);
         const localEntries = entries ?? [];
         const existingEntries = existingDatasource?.entries ?? [];
+        const dimensionWarnings = [];
         const existingEntryMap = new Map(existingEntries.map((e, idx) => [e.name, { entry: e, position: idx + 1 }]));
         for (let i = 0; i < localEntries.length; i++) {
           const entry = localEntries[i];
           const existing = existingEntryMap.get(entry.name);
           const existingEntryId = existing?.entry.id;
           const targetPosition = i + 1;
-          if (existing && existing.entry.value === entry.value && existing.entry.dimension_value === entry.dimension_value && existing.position === targetPosition) {
+          if (existing && existing.entry.value === entry.value && dimensionValuesEqual(existing.entry.dimension_values, entry.dimension_values) && existing.position === targetPosition) {
             logger.info("Skipped datasource entry (unchanged)", { datasource: datasource.name, entry: entry.name, position: targetPosition });
             continue;
           }
           try {
-            await upsertDatasourceEntry(space, result.id, entry, existingEntryId, i + 1);
+            const upserted = await upsertDatasourceEntry(space, result.id, entry, existingEntryId, i + 1);
+            const entryId = existingEntryId ?? upserted?.id;
             logger.info(existingEntryId ? "Updated datasource entry" : "Created datasource entry", { datasource: datasource.name, entry: entry.name, position: i + 1 });
+            if (entryId != null && entry.dimension_values !== void 0) {
+              const localDimensionValues = entry.dimension_values;
+              const targetDimensionValues = existing?.entry.dimension_values ?? {};
+              const dimensionCodes = /* @__PURE__ */ new Set([...Object.keys(localDimensionValues), ...Object.keys(targetDimensionValues)]);
+              for (const code of dimensionCodes) {
+                const localValue = localDimensionValues[code] ?? "";
+                const targetValue = targetDimensionValues[code] ?? "";
+                if (localValue === targetValue) {
+                  continue;
+                }
+                const dimension = result.dimensions?.find((d) => d.entry_value === code);
+                if (!dimension?.id) {
+                  dimensionWarnings.push(`Skipping dimension "${code}" for entry "${entry.name}": no matching dimension in target space ${space}`);
+                  continue;
+                }
+                await updateDatasourceEntryDimension(space, entryId, entry, dimension.id, localValue);
+              }
+            }
           } catch (entryError) {
             results.failed.push({ name: datasource.name, error: entryError });
             spinner.failed(`${chalk.hex(colorPalette.DATASOURCES)(datasource.name)} - Failed in ${spinner.elapsedTime.toFixed(2)}ms`);
@@ -6687,6 +6779,7 @@ pushCmd$2.action(async (datasourceName, options, command) => {
           }
         }
         spinner.succeed(`${chalk.hex(colorPalette.DATASOURCES)(datasource.name)} - Completed in ${spinner.elapsedTime.toFixed(2)}ms`);
+        dimensionWarnings.forEach((warning) => konsola.warn(warning));
       } else {
         results.failed.push({ name: datasource.name, error: result });
         spinner.failed(`${chalk.hex(colorPalette.DATASOURCES)(datasource.name)} - Failed in ${spinner.elapsedTime.toFixed(2)}ms`);
@@ -7820,7 +7913,7 @@ const extractAssetSizeFromFilename = (filename) => {
   }
   try {
     const segments = new URL(filename).pathname.split("/");
-    return segments.find((segment) => /^\d+x\d+$/.test(segment));
+    return segments.find((segment) => /^\d+x\d+$/i.test(segment));
   } catch {
     return void 0;
   }
@@ -10698,6 +10791,11 @@ function applyDefaults(entity, defaults) {
   return result;
 }
 const INDENT = "  ";
+class RawCode {
+  constructor(code) {
+    this.code = code;
+  }
+}
 function quoteString(value) {
   const escaped = JSON.stringify(value).slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'");
   return `'${escaped}'`;
@@ -10708,6 +10806,9 @@ function formatValue(value, depth) {
   if (value === null || value === void 0) {
     return String(value);
   }
+  if (value instanceof RawCode) {
+    return value.code;
+  }
   if (typeof value === "string") {
     return quoteString(value);
   }
@@ -10753,10 +10854,69 @@ function stripKeys(obj, keysToStrip) {
   return result;
 }
 
+function buildGroupPathByUuid(folders) {
+  const byUuid = new Map(folders.map((folder) => [folder.uuid, folder]));
+  const cache = /* @__PURE__ */ new Map();
+  function pathFor(uuid, visited) {
+    if (!uuid) {
+      return [];
+    }
+    const cached = cache.get(uuid);
+    if (cached) {
+      return cached;
+    }
+    const folder = byUuid.get(uuid);
+    if (!folder) {
+      return [];
+    }
+    if (visited.has(uuid)) {
+      return [];
+    }
+    visited.add(uuid);
+    const path = [...pathFor(folder.parent_uuid, visited), slugify(folder.name)];
+    cache.set(uuid, path);
+    return path;
+  }
+  for (const folder of folders) {
+    pathFor(folder.uuid, /* @__PURE__ */ new Set());
+  }
+  return cache;
+}
+function slugifyPath(displayPath) {
+  return displayPath.split("/").map((segment) => slugify(segment)).filter(Boolean).join("/");
+}
+function expandFolderPath(displayPath) {
+  const segments = displayPath.split("/").map((segment) => ({ name: segment, slug: slugify(segment) })).filter((segment) => segment.slug !== "");
+  const result = [];
+  let parentPath = null;
+  for (const { name, slug } of segments) {
+    const path = parentPath ? `${parentPath}/${slug}` : slug;
+    result.push({ name, path, parentPath });
+    parentPath = path;
+  }
+  return result;
+}
+
 function mapFieldToWire(field) {
   const { name, allow, datasource, ...rest } = field;
   const value = { ...rest };
-  if (allow !== void 0) {
+  if (allow !== void 0 && Array.isArray(allow)) {
+    const folderPaths = allow.filter((entry) => isRecord(entry) && typeof entry.folder === "string").map((entry) => slugifyPath(entry.folder));
+    const blockNames = allow.filter((entry) => typeof entry === "string");
+    if (folderPaths.length > 0) {
+      value.component_group_whitelist = folderPaths;
+      if (rest.type === "bloks" || rest.type === "richtext") {
+        value.restrict_components = true;
+        value.restrict_type = "groups";
+      }
+    } else {
+      value.component_whitelist = blockNames;
+      if (rest.type === "bloks") {
+        value.restrict_components = true;
+        value.restrict_type = "";
+      }
+    }
+  } else if (allow !== void 0) {
     value.component_whitelist = allow;
     if (rest.type === "bloks") {
       value.restrict_components = true;
@@ -10769,7 +10929,7 @@ function mapFieldToWire(field) {
   return { name: typeof name === "string" ? name : "", value };
 }
 function mapBlockToWire(block) {
-  const { fields, ...rest } = block;
+  const { fields, folder, ...rest } = block;
   const schema = {};
   if (Array.isArray(fields)) {
     for (const field of fields) {
@@ -10782,7 +10942,11 @@ function mapBlockToWire(block) {
       }
     }
   }
-  return { ...rest, schema };
+  return {
+    ...rest,
+    ...folder !== void 0 && { folder: typeof folder === "string" ? slugifyPath(folder) : null },
+    schema
+  };
 }
 function mapDatasourceToWire(datasource) {
   return datasource;
@@ -10794,23 +10958,88 @@ function isComponent(value) {
 function isDatasource(value) {
   return isRecord(value) && typeof value.name === "string" && typeof value.slug === "string" && !Array.isArray(value.fields);
 }
+function isFolder(value) {
+  return isRecord(value) && typeof value.name === "string" && typeof value.path === "string" && !Array.isArray(value.fields) && !("slug" in value);
+}
+function buildLocalFolders(registered, derived) {
+  const byPath = /* @__PURE__ */ new Map();
+  const add = (displayPath, registeredLeaf) => {
+    const expanded = expandFolderPath(displayPath);
+    expanded.forEach((entry, i) => {
+      const isLeaf = i === expanded.length - 1;
+      const isRegisteredEntry = registeredLeaf && isLeaf;
+      const existing = byPath.get(entry.path);
+      if (!existing) {
+        byPath.set(entry.path, { folder: entry, isRegistered: isRegisteredEntry });
+        return;
+      }
+      if (isRegisteredEntry && existing.isRegistered && existing.folder.name !== entry.name) {
+        throw new CommandError(`Conflicting folder names for path "${entry.path}": "${existing.folder.name}" vs "${entry.name}"`);
+      }
+      if (isRegisteredEntry && !existing.isRegistered) {
+        byPath.set(entry.path, { folder: entry, isRegistered: true });
+      }
+    });
+  };
+  for (const path of registered) {
+    add(path, true);
+  }
+  for (const path of derived) {
+    add(path, false);
+  }
+  const folders = [...byPath.values()].map((v) => v.folder).sort((a, b) => a.path.split("/").length - b.path.split("/").length || a.path.localeCompare(b.path));
+  const leafToPath = /* @__PURE__ */ new Map();
+  for (const folder of folders) {
+    const leaf = folder.path.split("/").pop() ?? folder.path;
+    const existing = leafToPath.get(leaf);
+    if (existing !== void 0 && existing !== folder.path) {
+      throw new CommandError(
+        `Duplicate folder name "${leaf}" (folders "${existing}" and "${folder.path}"): Storyblok group names must be unique per space, even under different parents.`
+      );
+    }
+    leafToPath.set(leaf, folder.path);
+  }
+  return folders;
+}
 function isSchemaObject(value) {
-  return isRecord(value) && ("blocks" in value || "datasources" in value);
+  return isRecord(value) && ("blocks" in value || "datasources" in value || "folders" in value);
 }
 function emptySchemaData() {
-  return { components: [], datasources: [] };
+  return { components: [], folders: [], datasources: [] };
 }
 function classifyExports(moduleExports) {
   const data = emptySchemaData();
   const seenComponents = /* @__PURE__ */ new Set();
   const seenDatasources = /* @__PURE__ */ new Set();
+  const registered = [];
+  const derived = [];
+  function harvestComponentPaths(value) {
+    if (typeof value.folder === "string") {
+      derived.push(value.folder);
+    }
+    if (Array.isArray(value.fields)) {
+      for (const field of value.fields) {
+        if (!isRecord(field) || !Array.isArray(field.allow)) {
+          continue;
+        }
+        for (const entry of field.allow) {
+          if (isRecord(entry) && typeof entry.folder === "string") {
+            derived.push(entry.folder);
+          }
+        }
+      }
+    }
+  }
   function collect(value) {
     if (isComponent(value)) {
+      harvestComponentPaths(value);
       if (seenComponents.has(value.name)) {
         return;
       }
       seenComponents.add(value.name);
       data.components.push(mapBlockToWire(value));
+    } else if (isFolder(value)) {
+      registered.push(value.path);
     } else if (isDatasource(value)) {
       if (seenDatasources.has(value.name)) {
         return;
@@ -10832,6 +11061,7 @@ function classifyExports(moduleExports) {
       collect(value);
     }
   }
+  data.folders = buildLocalFolders(registered, derived);
   return data;
 }
 async function loadSchema(entryPath) {
@@ -10859,6 +11089,7 @@ function sortSchemaByPos$1(schema) {
     })
   );
 }
+const FOLDER_UNGROUPED = "__FOLDER_UNGROUPED__";
 function serializeComponent(component, options = {}) {
   const stripSet = options.includeGroupUuid ? new Set([...COMPONENT_STRIP_KEYS].filter((key) => key !== "component_group_uuid")) : COMPONENT_STRIP_KEYS;
   const clean = stripKeys(component, stripSet);
@@ -10878,7 +11109,10 @@ function serializeComponent(component, options = {}) {
   if (clean.is_nestable !== void 0) {
     ordered.is_nestable = clean.is_nestable;
   }
-  const handled = /* @__PURE__ */ new Set(["name", "display_name", "is_root", "is_nestable", "schema"]);
+  if ("folder" in component) {
+    ordered.folder = component.folder === null ? FOLDER_UNGROUPED : component.folder;
+  }
+  const handled = /* @__PURE__ */ new Set(["name", "display_name", "is_root", "is_nestable", "folder", "schema"]);
   for (const [key, value] of Object.entries(clean).sort(([a], [b]) => a.localeCompare(b))) {
     if (!handled.has(key)) {
       ordered[key] = value;
@@ -10887,7 +11121,7 @@ function serializeComponent(component, options = {}) {
   if (clean.schema !== void 0) {
     ordered.schema = clean.schema;
   }
-  return `defineBlock(${formatValue(ordered, 0)})`;
+  return `defineBlock(${formatValue(ordered, 0)})`.replace(`folder: '${FOLDER_UNGROUPED}'`, "folder: null");
 }
 function serializeDatasource(datasource) {
   const clean = stripKeys(datasource, DATASOURCE_STRIP_KEYS);
@@ -10912,6 +11146,23 @@ function serializeDatasource(datasource) {
   return `defineDatasource(${formatValue(ordered, 0)})`;
 }
 
+function translateGroupWhitelist(schema, uuidToPath) {
+  if (!isRecord(schema)) {
+    return schema;
+  }
+  const result = {};
+  for (const [fieldName, field] of Object.entries(schema)) {
+    if (isRecord(field) && Array.isArray(field.component_group_whitelist)) {
+      result[fieldName] = {
+        ...field,
+        component_group_whitelist: field.component_group_whitelist.map((entry) => typeof entry === "string" ? uuidToPath.get(entry) ?? entry : entry)
+      };
+    } else {
+      result[fieldName] = field;
+    }
+  }
+  return result;
+}
 function diffEntity(type, name, localSerialized, remoteSerialized) {
   if (!remoteSerialized && localSerialized) {
     return { type, name, action: "create", diff: null, local: null, remote: null };
@@ -10934,13 +11185,46 @@ function diffEntity(type, name, localSerialized, remoteSerialized) {
 }
 function diffSchema(local, remote) {
   const diffs = [];
+  const groupPathByUuid = buildGroupPathByUuid([...remote.componentFolders.values()]);
+  const uuidToPath = /* @__PURE__ */ new Map();
+  for (const [uuid, segments] of groupPathByUuid) {
+    uuidToPath.set(uuid, segments.join("/"));
+  }
+  const remoteFolderPaths = new Set(uuidToPath.values());
+  const localFolderPaths = new Set(local.folders.map((f) => f.path));
+  for (const folder of local.folders) {
+    const action = remoteFolderPaths.has(folder.path) ? "unchanged" : "create";
+    diffs.push({ type: "folder", name: folder.path, action, diff: null, local: null, remote: null });
+  }
+  for (const path of remoteFolderPaths) {
+    if (!localFolderPaths.has(path)) {
+      diffs.push({ type: "folder", name: path, action: "stale", diff: null, local: null, remote: null });
+    }
+  }
   const processedComponentNames = /* @__PURE__ */ new Set();
   for (const comp of local.components) {
     processedComponentNames.add(comp.name);
     const remoteComp = remote.components.get(comp.name);
     const includeGroupUuid = typeof comp.component_group_uuid === "string";
-    const localSerialized = serializeComponent(applyDefaults(comp, COMPONENT_DEFAULTS), { includeGroupUuid });
-    const remoteSerialized = remoteComp ? serializeComponent(applyDefaults(remoteComp, COMPONENT_DEFAULTS), { includeGroupUuid }) : null;
+    const localForDiff = { ...comp };
+    const remoteForDiff = remoteComp ? { ...remoteComp } : void 0;
+    if ("folder" in comp) {
+      if (remoteForDiff) {
+        const uuid = remoteForDiff.component_group_uuid;
+        remoteForDiff.folder = typeof uuid === "string" && uuid ? uuidToPath.get(uuid) ?? null : null;
+      }
+    } else {
+      delete localForDiff.folder;
+      if (remoteForDiff) {
+        delete remoteForDiff.folder;
+      }
+    }
+    localForDiff.schema = translateGroupWhitelist(localForDiff.schema, uuidToPath);
+    if (remoteForDiff) {
+      remoteForDiff.schema = translateGroupWhitelist(remoteForDiff.schema, uuidToPath);
+    }
+    const localSerialized = serializeComponent(applyDefaults(localForDiff, COMPONENT_DEFAULTS), { includeGroupUuid });
+    const remoteSerialized = remoteForDiff ? serializeComponent(applyDefaults(remoteForDiff, COMPONENT_DEFAULTS), { includeGroupUuid }) : null;
     diffs.push(diffEntity("component", comp.name, localSerialized, remoteSerialized));
   }
   for (const [name] of remote.components) {
@@ -11023,7 +11307,10 @@ function buildComponentPayload(input) {
     ...isRecord(input.schema) && { schema: toSchemaRecord(input.schema) },
     ...typeof input.is_root === "boolean" && { is_root: input.is_root },
     ...typeof input.is_nestable === "boolean" && { is_nestable: input.is_nestable },
-    ...typeof input.component_group_uuid === "string" && { component_group_uuid: input.component_group_uuid }
+    // Forward the group membership only when the key is present on input: a
+    // string sets the group, an explicit `null` clears it. Unmanaged components
+    // (key absent) omit it so their remote group is left untouched.
+    ..."component_group_uuid" in input && (typeof input.component_group_uuid === "string" || input.component_group_uuid === null) && { component_group_uuid: input.component_group_uuid }
   };
 }
 function toComponentCreate(input) {
@@ -11066,11 +11353,54 @@ function toDatasourceUpdate(input, remote) {
   return base;
 }
 
+function resolveGroupRefs(comp, groupByPath) {
+  const { folder, ...rest } = comp;
+  const resolved = { ...rest };
+  if (typeof folder === "string") {
+    const group = groupByPath.get(folder);
+    if (!group) {
+      throw new CommandError(
+        `Unknown folder path "${folder}" for component "${comp.name}": no matching component group exists. Folder creation runs before component push, so this indicates an internal inconsistency.`
+      );
+    }
+    resolved.component_group_uuid = group.uuid;
+  } else if (folder === null) {
+    resolved.component_group_uuid = null;
+  }
+  if (isRecord(resolved.schema)) {
+    const schema = {};
+    for (const [key, field] of Object.entries(resolved.schema)) {
+      if (isRecord(field) && Array.isArray(field.component_group_whitelist)) {
+        schema[key] = {
+          ...field,
+          component_group_whitelist: field.component_group_whitelist.map((path) => typeof path === "string" ? groupByPath.get(path)?.uuid ?? path : path)
+        };
+      } else {
+        schema[key] = field;
+      }
+    }
+    resolved.schema = schema;
+  }
+  return resolved;
+}
+function buildGroupByPath(remote) {
+  const remoteFolders = [...remote.componentFolders.values()];
+  const groupPathByUuid = buildGroupPathByUuid(remoteFolders);
+  const groupByPath = /* @__PURE__ */ new Map();
+  for (const folder of remoteFolders) {
+    const segments = groupPathByUuid.get(folder.uuid);
+    if (segments?.length) {
+      groupByPath.set(segments.join("/"), { id: folder.id, uuid: folder.uuid });
+    }
+  }
+  return groupByPath;
+}
 function formatDiffOutput(result, options) {
   const lines = [];
   const byType = {
     component: [],
-    datasource: []
+    datasource: [],
+    folder: []
   };
   for (const diff of result.diffs) {
     byType[diff.type].push(diff);
@@ -11083,6 +11413,7 @@ function formatDiffOutput(result, options) {
     stale: chalk.red("-")
   };
   const sections = [
+    ["Folders", byType.folder],
     ["Components", byType.component],
     ["Datasources", byType.datasource]
   ];
@@ -11123,24 +11454,62 @@ async function executePush(spaceId, local, remote, diffResult, options) {
   let created = 0;
   let updated = 0;
   let deleted = 0;
+  const groupByPath = buildGroupByPath(remote);
+  const foldersByPath = new Map(local.folders.map((f) => [f.path, f]));
+  const folderCreates = diffResult.diffs.filter((d) => d.type === "folder" && d.action === "create").sort((a, b) => a.name.split("/").length - b.name.split("/").length);
+  for (const diff of folderCreates) {
+    const localFolder = foldersByPath.get(diff.name);
+    if (!localFolder) {
+      continue;
+    }
+    const parent = localFolder.parentPath ? groupByPath.get(localFolder.parentPath) : void 0;
+    let createdGroup;
+    try {
+      const res = await client.componentFolders.create({
+        path: { space_id: spaceIdNum },
+        body: { component_group: { name: localFolder.name, parent_id: parent?.id ?? null } },
+        throwOnError: true
+      });
+      createdGroup = res.data?.component_group;
+    } catch (error) {
+      handleAPIError("push_component_folder", error, `Failed to create folder ${localFolder.name}`);
+    }
+    if (createdGroup?.id == null || !createdGroup.uuid) {
+      throw new CommandError(
+        `Folder "${localFolder.name}" was created but the Management API response did not include an id and uuid; blocks that reference this folder cannot be resolved.`
+      );
+    }
+    groupByPath.set(localFolder.path, { id: createdGroup.id, uuid: createdGroup.uuid });
+    created++;
+  }
   const componentDiffs = diffResult.diffs.filter((d) => d.type === "component");
+  const resolvedComponents = /* @__PURE__ */ new Map();
+  for (const diff of componentDiffs) {
+    if (diff.action !== "create" && diff.action !== "update") {
+      continue;
+    }
+    const localComp = local.components.find((c) => c.name === diff.name);
+    if (localComp) {
+      resolvedComponents.set(diff.name, resolveGroupRefs(localComp, groupByPath));
+    }
+  }
   const componentResults = await Promise.allSettled(
     componentDiffs.map(async (diff) => {
-      const localComp = local.components.find((c) => c.name === diff.name);
-      if (diff.action === "create" && localComp) {
+      const resolvedComp = resolvedComponents.get(diff.name);
+      if (diff.action === "create" && resolvedComp) {
         await client.components.create({
           path: { space_id: spaceIdNum },
-          body: { component: toComponentCreate(localComp) },
+          body: { component: toComponentCreate(resolvedComp) },
           throwOnError: true
         });
         return "created";
       }
-      if (diff.action === "update" && localComp) {
+      if (diff.action === "update" && resolvedComp) {
         const existing = remote.components.get(diff.name);
         if (existing?.id) {
           await client.components.update(existing.id, {
             path: { space_id: spaceIdNum },
-            body: { component: toComponentUpdate(localComp) },
+            body: { component: toComponentUpdate(resolvedComp) },
             throwOnError: true
           });
           return "updated";
@@ -11202,6 +11571,7 @@ async function executePush(spaceId, local, remote, diffResult, options) {
     }
   }
   if (options.delete) {
+    const deleteErrors = [];
     const staleComponents = diffResult.diffs.filter((d) => d.type === "component" && d.action === "stale");
     const deleteComponentResults = await Promise.allSettled(
       staleComponents.map(async (diff) => {
@@ -11222,7 +11592,7 @@ async function executePush(spaceId, local, remote, diffResult, options) {
           deleted++;
         }
       } else {
-        handleAPIError("delete_component", result.reason, `Failed to delete component ${staleComponents[i].name}`);
+        deleteErrors.push({ action: "delete_component", reason: result.reason, message: `Failed to delete component ${staleComponents[i].name}` });
       }
     }
     const staleDatasources = diffResult.diffs.filter((d) => d.type === "datasource" && d.action === "stale");
@@ -11245,14 +11615,49 @@ async function executePush(spaceId, local, remote, diffResult, options) {
           deleted++;
         }
       } else {
-        handleAPIError("delete_datasource", result.reason, `Failed to delete datasource ${staleDatasources[i].name}`);
+        deleteErrors.push({ action: "delete_datasource", reason: result.reason, message: `Failed to delete datasource ${staleDatasources[i].name}` });
       }
     }
+    const staleFolders = diffResult.diffs.filter((d) => d.type === "folder" && d.action === "stale").sort((a, b) => b.name.split("/").length - a.name.split("/").length);
+    for (const diff of staleFolders) {
+      const group = groupByPath.get(diff.name);
+      if (!group) {
+        deleteErrors.push({
+          action: "delete_component_folder",
+          reason: new Error(`No component group resolved for stale folder path "${diff.name}".`),
+          message: `Failed to delete folder ${diff.name}`
+        });
+        continue;
+      }
+      try {
+        await client.componentFolders.delete(group.id, {
+          path: { space_id: spaceIdNum },
+          throwOnError: true
+        });
+        deleted++;
+      } catch (error) {
+        deleteErrors.push({ action: "delete_component_folder", reason: error, message: `Failed to delete folder ${diff.name}` });
+      }
+    }
+    if (deleteErrors.length > 0) {
+      const first = deleteErrors[0];
+      const suffix = deleteErrors.length > 1 ? ` (and ${deleteErrors.length - 1} more delete error(s))` : "";
+      handleAPIError(first.action, first.reason, `${first.message}${suffix}`);
+    }
   }
   return { created, updated, deleted };
 }
 function buildChangesetEntries(diffResult, local, remote, options) {
   const changes = [];
+  const remoteFolders = [...remote.componentFolders.values()];
+  const folderPathByUuid = buildGroupPathByUuid(remoteFolders);
+  const remoteFolderByPath = /* @__PURE__ */ new Map();
+  for (const folder of remoteFolders) {
+    const segments = folderPathByUuid.get(folder.uuid);
+    if (segments?.length) {
+      remoteFolderByPath.set(segments.join("/"), folder);
+    }
+  }
   for (const diff of diffResult.diffs) {
     if (diff.action === "unchanged") {
       continue;
@@ -11269,6 +11674,9 @@ function buildChangesetEntries(diffResult, local, remote, options) {
     } else if (diff.type === "datasource") {
       remoteSrc = remote.datasources.get(diff.name);
       localSrc = local.datasources.find((d) => d.name === diff.name);
+    } else if (diff.type === "folder") {
+      remoteSrc = remoteFolderByPath.get(diff.name);
+      localSrc = local.folders.find((f) => f.path === diff.name);
     }
     changes.push({
       type: diff.type,
@@ -11552,6 +11960,25 @@ async function writeMigrationFile(options) {
 
 const DEFAULT_GROUPS_FILENAME = "groups.json";
 const CONSOLIDATED_COMPONENTS_FILENAME = "components.json";
+function sanitizeForLocalWrite(component) {
+  const { folder, ...rest } = component;
+  if (isRecord(rest.schema)) {
+    const schema = {};
+    for (const [key, field] of Object.entries(rest.schema)) {
+      if (isRecord(field) && "component_group_whitelist" in field) {
+        const { component_group_whitelist, restrict_components, ...fieldRest } = field;
+        if (fieldRest.restrict_type === "groups") {
+          delete fieldRest.restrict_type;
+        }
+        schema[key] = fieldRest;
+      } else {
+        schema[key] = field;
+      }
+    }
+    rest.schema = schema;
+  }
+  return rest;
+}
 async function writeLocalComponents({
   space,
   basePath,
@@ -11570,7 +11997,7 @@ async function writeLocalComponents({
   }
   for (const component of resolved.components) {
     const filePath = join(componentsDir, `${sanitizeFilename(component.name || "")}.json`);
-    await saveToFile(filePath, JSON.stringify(component, null, 2));
+    await saveToFile(filePath, JSON.stringify(sanitizeForLocalWrite(component), null, 2));
   }
   const groupsPath = join(componentsDir, DEFAULT_GROUPS_FILENAME);
   if (await fileExists(groupsPath)) {
@@ -11631,10 +12058,10 @@ schemaCommand.command("push <entry-file>").description("Push local TypeScript sc
       handleError(toError(maybeError), verbose);
       return;
     }
-    loadSpinner.succeed(`Found: ${local.components.length} components, ${local.datasources.length} datasources`);
-    const totalLocal = local.components.length + local.datasources.length;
+    loadSpinner.succeed(`Found: ${local.components.length} components, ${local.folders.length} folders, ${local.datasources.length} datasources`);
+    const totalLocal = local.components.length + local.datasources.length + local.folders.length;
     if (totalLocal === 0) {
-      ui.warn("No components or datasources found in the entry file. Verify the file exports schema definitions.");
+      ui.warn("No components, folders, or datasources found in the entry file. Verify the file exports schema definitions.");
       return;
     }
     const remoteSpinner = ui.createSpinner(`Fetching remote state from space ${space}...`);
@@ -11720,6 +12147,26 @@ schemaCommand.command("push <entry-file>").description("Push local TypeScript sc
       for (const comp of deletedComponents) {
         ui.warn(`Component '${comp.name}' will be deleted. Stories using it will have out-of-schema content.`);
       }
+      const staleFolders = diffResult.diffs.filter((d) => d.type === "folder" && d.action === "stale");
+      if (staleFolders.length > 0) {
+        const uuidByPath = /* @__PURE__ */ new Map();
+        for (const [uuid, segments] of buildGroupPathByUuid([...remote.componentFolders.values()])) {
+          uuidByPath.set(segments.join("/"), uuid);
+        }
+        const staleComponentNames = new Set(
+          diffResult.diffs.filter((d) => d.type === "component" && d.action === "stale").map((d) => d.name)
+        );
+        for (const folder of staleFolders) {
+          const uuid = uuidByPath.get(folder.name);
+          if (!uuid) {
+            continue;
+          }
+          const count = [...remote.components.values()].filter((c) => c.component_group_uuid === uuid && !staleComponentNames.has(c.name)).length;
+          if (count > 0) {
+            ui.warn(`Folder '${folder.name}' will be deleted; ${count} component(s) inside will be ungrouped.`);
+          }
+        }
+      }
     }
     if (diffResult.stale > 0 && !options.delete) {
       ui.warn(`${diffResult.stale} stale entity(s) exist remotely but not in schema. Use --delete to remove.`);
@@ -11780,35 +12227,6 @@ schemaCommand.command("push <entry-file>").description("Push local TypeScript sc
   }
 });
 
-function buildGroupPathByUuid(folders) {
-  const byUuid = new Map(folders.map((folder) => [folder.uuid, folder]));
-  const cache = /* @__PURE__ */ new Map();
-  function pathFor(uuid, visited) {
-    if (!uuid) {
-      return [];
-    }
-    const cached = cache.get(uuid);
-    if (cached) {
-      return cached;
-    }
-    const folder = byUuid.get(uuid);
-    if (!folder) {
-      return [];
-    }
-    if (visited.has(uuid)) {
-      return [];
-    }
-    visited.add(uuid);
-    const path = [...pathFor(folder.parent_uuid, visited), slugify(folder.name)];
-    cache.set(uuid, path);
-    return path;
-  }
-  for (const folder of folders) {
-    pathFor(folder.uuid, /* @__PURE__ */ new Set());
-  }
-  return cache;
-}
-
 const FIELD_STRIP_KEYS = /* @__PURE__ */ new Set(["id", "pos"]);
 function toCamelCaseIdentifier(str) {
   const camel = slugify(str).replace(/^[_-]+/, "").replace(/[_-]+(.)/g, (_, char) => char.toUpperCase());
@@ -11826,6 +12244,9 @@ function componentVarName(name) {
 function datasourceVarName(name) {
   return `${toCamelCaseIdentifier(name)}Datasource`;
 }
+function folderVarName(name) {
+  return `${toCamelCaseIdentifier(name)}Folder`;
+}
 function resolveVarNames(rawNames, baseVarName) {
   const used = /* @__PURE__ */ new Set();
   return rawNames.map((raw) => {
@@ -11885,12 +12306,37 @@ function resolveDatasources(datasources) {
     fileName: fileNames[i]
   }));
 }
-function toDslField(field) {
-  const { component_whitelist, datasource_slug, restrict_components, restrict_type, ...rest } = field;
+function resolveFolders(folders) {
+  const pathByUuid = buildGroupPathByUuid(folders);
+  const ordered = [...folders].sort((a, b) => (pathByUuid.get(a.uuid)?.length ?? 0) - (pathByUuid.get(b.uuid)?.length ?? 0));
+  const varNames = resolveVarNames(ordered.map((f) => f.name), folderVarName);
+  return ordered.map((folder, i) => ({
+    folder,
+    varName: varNames[i],
+    segments: pathByUuid.get(folder.uuid) ?? []
+  }));
+}
+function resolveGroupWhitelistRefs(whitelist, folderVarByUuid) {
+  if (!folderVarByUuid || !Array.isArray(whitelist) || whitelist.length === 0) {
+    return void 0;
+  }
+  const vars = whitelist.map((uuid) => typeof uuid === "string" ? folderVarByUuid.get(uuid) : void 0);
+  if (!vars.every((v) => typeof v === "string")) {
+    return void 0;
+  }
+  return vars.map((v) => new RawCode(v));
+}
+function toDslField(field, folderVarByUuid) {
+  const { component_whitelist, component_group_whitelist, datasource_slug, restrict_components, restrict_type, ...rest } = field;
   const out = { ...rest };
-  if (component_whitelist !== void 0) {
+  const groupRefs = resolveGroupWhitelistRefs(component_group_whitelist, folderVarByUuid);
+  const hasBlockNames = Array.isArray(component_whitelist) && component_whitelist.length > 0;
+  if (hasBlockNames) {
     out.allow = component_whitelist;
-  } else {
+  } else if (groupRefs) {
+    out.allow = groupRefs;
+  } else if (component_group_whitelist !== void 0) {
+    out.component_group_whitelist = component_group_whitelist;
     if (restrict_components !== void 0) {
       out.restrict_components = restrict_components;
     }
@@ -11903,10 +12349,33 @@ function toDslField(field) {
   }
   return out;
 }
-function generateFieldCode(fieldName, fieldData, depth) {
-  const clean = toDslField(stripKeys(fieldData, FIELD_STRIP_KEYS));
+function omitEmptyArrays(obj) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (Array.isArray(value) && value.length === 0) {
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+function generateFieldCode(fieldName, fieldData, depth, folderVarByUuid) {
+  const clean = omitEmptyArrays(toDslField(stripKeys(fieldData, FIELD_STRIP_KEYS), folderVarByUuid));
   return `defineField(${quoteString(fieldName)}, ${formatValue(clean, depth)})`;
 }
+function collectWhitelistFolderVars(schema, folderVarByUuid) {
+  const vars = /* @__PURE__ */ new Set();
+  for (const field of Object.values(schema)) {
+    if (!isRecord(field)) {
+      continue;
+    }
+    const refs = resolveGroupWhitelistRefs(field.component_group_whitelist, folderVarByUuid);
+    if (refs) {
+      refs.forEach((ref) => vars.add(ref.code));
+    }
+  }
+  return [...vars].sort();
+}
 function sortSchemaByPos(schema) {
   return Object.entries(schema).filter(([key]) => key !== "_uid" && key !== "component").sort(([, a], [, b]) => {
     const posA = typeof a.pos === "number" ? a.pos : Infinity;
@@ -11914,16 +12383,42 @@ function sortSchemaByPos(schema) {
     return posA - posB;
   });
 }
-function generateComponentFile(component, varName) {
+function generateFoldersFile(resolved) {
+  const varByUuid = new Map(resolved.map((r) => [r.folder.uuid, r.varName]));
+  const lines = ["import { defineFolder } from '@storyblok/schema';", ""];
+  for (const { folder, varName } of resolved) {
+    const parentVar = folder.parent_uuid ? varByUuid.get(folder.parent_uuid) : void 0;
+    lines.push(`export const ${varName} = defineFolder({`);
+    lines.push(`${INDENT}name: ${quoteString(folder.name)},`);
+    if (parentVar) {
+      lines.push(`${INDENT}parent: ${parentVar},`);
+    }
+    lines.push("});");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function generateComponentFile(component, varName, folderRef, folderVarByUuid) {
   const lines = [];
   lines.push("import {");
   lines.push("  defineBlock,");
   lines.push("  defineField,");
   lines.push("} from '@storyblok/schema';");
   lines.push("");
+  const blockDepth = folderRef?.segments.length ?? 0;
+  const schema = isRecord(component.schema) ? component.schema : {};
+  const folderVars = [.../* @__PURE__ */ new Set([
+    ...folderRef ? [folderRef.varName] : [],
+    ...collectWhitelistFolderVars(schema, folderVarByUuid)
+  ])].sort();
+  if (folderVars.length > 0) {
+    const rel = "../".repeat(blockDepth + 1);
+    lines.push(`import { ${folderVars.join(", ")} } from '${rel}folders';`);
+    lines.push("");
+  }
   const resolvedVarName = varName ?? componentVarName(component.name);
   lines.push(`export const ${resolvedVarName} = defineBlock({`);
-  const clean = stripKeys(component, COMPONENT_STRIP_KEYS);
+  const clean = omitEmptyArrays(stripKeys(component, COMPONENT_STRIP_KEYS));
   delete clean.component_group_uuid;
   const orderedKeys = [];
   if (clean.name !== void 0) {
@@ -11938,22 +12433,29 @@ function generateComponentFile(component, varName) {
   if (clean.is_nestable !== void 0) {
     orderedKeys.push("is_nestable");
   }
+  const prefixKeyCount = orderedKeys.length;
   const handled = /* @__PURE__ */ new Set(["name", "display_name", "is_root", "is_nestable", "schema"]);
   for (const key of Object.keys(clean).sort()) {
     if (!handled.has(key)) {
       orderedKeys.push(key);
     }
   }
-  for (const key of orderedKeys) {
+  orderedKeys.forEach((key, i) => {
     lines.push(`${INDENT}${key}: ${formatValue(clean[key], 1)},`);
+    if (folderRef && i === prefixKeyCount - 1) {
+      lines.push(`${INDENT}folder: ${folderRef.varName},`);
+    }
+  });
+  if (folderRef && prefixKeyCount === 0) {
+    lines.push(`${INDENT}folder: ${folderRef.varName},`);
   }
   if (clean.schema && typeof clean.schema === "object") {
-    const schema = clean.schema;
-    const sortedFields = sortSchemaByPos(schema);
+    const schema2 = clean.schema;
+    const sortedFields = sortSchemaByPos(schema2);
     if (sortedFields.length > 0) {
       lines.push(`${INDENT}fields: [`);
       for (const [fieldName, fieldData] of sortedFields) {
-        const fieldCode = generateFieldCode(fieldName, fieldData, 2);
+        const fieldCode = generateFieldCode(fieldName, fieldData, 2, folderVarByUuid);
         lines.push(`${INDENT}${INDENT}${fieldCode},`);
       }
       lines.push(`${INDENT}],`);
@@ -11971,7 +12473,7 @@ function generateDatasourceFile(datasource, varName) {
   lines.push("");
   const resolvedVarName = varName ?? datasourceVarName(datasource.name);
   lines.push(`export const ${resolvedVarName} = defineDatasource({`);
-  const clean = stripKeys(datasource, DATASOURCE_STRIP_KEYS);
+  const clean = omitEmptyArrays(stripKeys(datasource, DATASOURCE_STRIP_KEYS));
   if (clean.name !== void 0) {
     lines.push(`${INDENT}name: ${formatValue(clean.name, 1)},`);
   }
@@ -11988,7 +12490,7 @@ function generateDatasourceFile(datasource, varName) {
   lines.push("");
   return lines.join("\n");
 }
-function generateSchemaFile(components, datasources) {
+function generateSchemaFile(components, datasources, folders = []) {
   const lines = [];
   lines.push("import { defineSchema } from '@storyblok/schema';");
   lines.push("import type { Schema as InferSchema, Story as InferStory } from '@storyblok/schema';");
@@ -12001,6 +12503,9 @@ function generateSchemaFile(components, datasources) {
   for (const { varName, fileName } of datasources) {
     lines.push(`import { ${varName} } from './datasources/${fileName}';`);
   }
+  if (folders.length > 0) {
+    lines.push(`import { ${folders.map((f) => f.varName).join(", ")} } from './folders';`);
+  }
   lines.push("");
   lines.push("export const schema = defineSchema({");
   if (components.length > 0) {
@@ -12017,6 +12522,13 @@ function generateSchemaFile(components, datasources) {
     }
     lines.push("  },");
   }
+  if (folders.length > 0) {
+    lines.push("  folders: {");
+    for (const { varName } of folders) {
+      lines.push(`    ${varName},`);
+    }
+    lines.push("  },");
+  }
   lines.push("});");
   lines.push("");
   lines.push("export type Schema = InferSchema<typeof schema>;");
@@ -12040,9 +12552,14 @@ async function writeSchemaFiles(targetPath, components, componentFolders, dataso
   );
   const resolvedComponents = resolveComponents(components, componentSegments);
   const resolvedDatasources = resolveDatasources(datasources);
+  const resolvedFolders = resolveFolders(componentFolders);
+  const folderByUuid = new Map(resolvedFolders.map((r) => [r.folder.uuid, r]));
+  const folderVarByUuid = new Map([...folderByUuid].map(([uuid, r]) => [uuid, r.varName]));
   for (const { component, varName, fileName, segments } of resolvedComponents) {
     const filePath = join(targetPath, "blocks", ...segments, `${fileName}.ts`);
-    await writeFileWithDirs(filePath, generateComponentFile(component, varName));
+    const folder = component.component_group_uuid ? folderByUuid.get(component.component_group_uuid) : void 0;
+    const folderRef = folder && { varName: folder.varName, segments };
+    await writeFileWithDirs(filePath, generateComponentFile(component, varName, folderRef, folderVarByUuid));
     writtenFiles.push(filePath);
   }
   for (const { datasource, varName, fileName } of resolvedDatasources) {
@@ -12050,8 +12567,13 @@ async function writeSchemaFiles(targetPath, components, componentFolders, dataso
     await writeFileWithDirs(filePath, generateDatasourceFile(datasource, varName));
     writtenFiles.push(filePath);
   }
+  if (resolvedFolders.length > 0) {
+    const foldersPath = join(targetPath, "folders.ts");
+    await writeFileWithDirs(foldersPath, generateFoldersFile(resolvedFolders));
+    writtenFiles.push(foldersPath);
+  }
   const schemaPath = join(targetPath, "schema.ts");
-  await writeFileWithDirs(schemaPath, generateSchemaFile(resolvedComponents, resolvedDatasources));
+  await writeFileWithDirs(schemaPath, generateSchemaFile(resolvedComponents, resolvedDatasources, resolvedFolders));
   writtenFiles.push(schemaPath);
   return writtenFiles;
 }
@@ -12181,6 +12703,7 @@ function rollbackAction(original) {
 }
 function formatRollbackOutput(changes) {
   const byType = {
+    folder: [],
     component: [],
     datasource: []
   };
@@ -12194,6 +12717,7 @@ function formatRollbackOutput(changes) {
   };
   const lines = [];
   const sections = [
+    ["Folders", byType.folder],
     ["Components", byType.component],
     ["Datasources", byType.datasource]
   ];
@@ -12213,9 +12737,11 @@ function formatRollbackOutput(changes) {
         if (entry.type === "component") {
           fromStr = serializeComponent(applyDefaults(entry.after, COMPONENT_DEFAULTS));
           toStr = serializeComponent(applyDefaults(entry.before, COMPONENT_DEFAULTS));
-        } else {
+        } else if (entry.type === "datasource") {
           fromStr = serializeDatasource(entry.after);
           toStr = serializeDatasource(entry.before);
+        } else {
+          continue;
         }
         if (fromStr !== toStr) {
           const patch = createTwoFilesPatch(
@@ -12240,6 +12766,46 @@ function formatRollbackOutput(changes) {
   }
   return lines.join("\n").trimEnd();
 }
+function buildGroupRefByPath(remote) {
+  const folders = [...remote.componentFolders.values()];
+  const pathByUuid = buildGroupPathByUuid(folders);
+  const byPath = /* @__PURE__ */ new Map();
+  for (const folder of folders) {
+    const segments = pathByUuid.get(folder.uuid);
+    if (segments?.length) {
+      byPath.set(segments.join("/"), { id: folder.id, uuid: folder.uuid });
+    }
+  }
+  return byPath;
+}
+function parentPathOf(path) {
+  const segments = path.split("/");
+  return segments.length > 1 ? segments.slice(0, -1).join("/") : null;
+}
+function remapGroupUuids(payload, uuidMap) {
+  if (uuidMap.size === 0) {
+    return payload;
+  }
+  const result = { ...payload };
+  if (typeof result.component_group_uuid === "string") {
+    result.component_group_uuid = uuidMap.get(result.component_group_uuid) ?? result.component_group_uuid;
+  }
+  if (isRecord(result.schema)) {
+    const schema = {};
+    for (const [key, field] of Object.entries(result.schema)) {
+      if (isRecord(field) && Array.isArray(field.component_group_whitelist)) {
+        schema[key] = {
+          ...field,
+          component_group_whitelist: field.component_group_whitelist.map((uuid) => typeof uuid === "string" ? uuidMap.get(uuid) ?? uuid : uuid)
+        };
+      } else {
+        schema[key] = field;
+      }
+    }
+    result.schema = schema;
+  }
+  return result;
+}
 async function executeRollback(spaceId, ops, remote) {
   const client = getMapiClient();
   const spaceIdNum = Number(spaceId);
@@ -12248,9 +12814,43 @@ async function executeRollback(spaceId, ops, remote) {
   let deleted = 0;
   const componentOps = ops.filter((op) => op.type === "component");
   const datasourceOps = ops.filter((op) => op.type === "datasource");
+  const folderOps = ops.filter((op) => op.type === "folder");
+  const groupRefByPath = buildGroupRefByPath(remote);
+  const groupUuidMap = /* @__PURE__ */ new Map();
+  const folderCreates = folderOps.filter((o) => o.action === "create").sort((a, b) => a.name.split("/").length - b.name.split("/").length);
+  for (const op of folderCreates) {
+    const existing = groupRefByPath.get(op.name);
+    const oldUuid = typeof op.payload.uuid === "string" ? op.payload.uuid : void 0;
+    if (existing) {
+      if (oldUuid) {
+        groupUuidMap.set(oldUuid, existing.uuid);
+      }
+      continue;
+    }
+    const parentPath = parentPathOf(op.name);
+    const parentId = parentPath ? groupRefByPath.get(parentPath)?.id ?? null : null;
+    const name = typeof op.payload.name === "string" ? op.payload.name : op.name.split("/").pop() ?? op.name;
+    try {
+      const res = await client.componentFolders.create({
+        path: { space_id: spaceIdNum },
+        body: { component_group: { name, parent_id: parentId } },
+        throwOnError: true
+      });
+      const group = res.data?.component_group;
+      if (group?.id != null && group.uuid) {
+        groupRefByPath.set(op.name, { id: group.id, uuid: group.uuid });
+        if (oldUuid) {
+          groupUuidMap.set(oldUuid, group.uuid);
+        }
+        created++;
+      }
+    } catch (error) {
+      handleAPIError("push_component_folder", error, `Failed to recreate folder ${op.name}`);
+    }
+  }
   for (const op of componentOps.filter((o) => o.action !== "delete")) {
     if (op.action === "create") {
-      const payload = toComponentCreate(stripApiFields(op.payload));
+      const payload = toComponentCreate(remapGroupUuids(stripApiFields(op.payload), groupUuidMap));
       try {
         await client.components.create({
           path: { space_id: spaceIdNum },
@@ -12264,7 +12864,7 @@ async function executeRollback(spaceId, ops, remote) {
     } else if (op.action === "update") {
       const existing = remote.components.get(op.name);
       if (existing?.id) {
-        const payload = toComponentUpdate(stripApiFields(op.payload));
+        const payload = toComponentUpdate(remapGroupUuids(stripApiFields(op.payload), groupUuidMap));
         try {
           await client.components.update(existing.id, {
             path: { space_id: spaceIdNum },
@@ -12336,6 +12936,22 @@ async function executeRollback(spaceId, ops, remote) {
       }
     }
   }
+  const folderDeletes = folderOps.filter((o) => o.action === "delete").sort((a, b) => b.name.split("/").length - a.name.split("/").length);
+  for (const op of folderDeletes) {
+    const ref = groupRefByPath.get(op.name);
+    if (!ref) {
+      continue;
+    }
+    try {
+      await client.componentFolders.delete(ref.id, {
+        path: { space_id: spaceIdNum },
+        throwOnError: true
+      });
+      deleted++;
+    } catch (error) {
+      handleAPIError("delete_component_folder", error, `Failed to delete folder ${op.name}`);
+    }
+  }
   return { created, updated, deleted };
 }