@pintawebware/strapi-sync 1.0.4

package/lib/schema-writer.js

@@ -0,0 +1,356 @@
+const path = require('path');
+const fs = require('fs');
+const { parseComponentType, parseRelationType, parseDynamicZoneType, isLocalizedSnapshotBlock, expandRelationTarget } = require('./snapshot-utils');
+
+function simpleTypeToStrapiAttr(simpleType) {
+  if (Array.isArray(simpleType)) return { type: 'dynamiczone', components: simpleType };
+  if (!simpleType || typeof simpleType !== 'string') return { type: 'json' };
+  const parsed = parseComponentType(simpleType);
+  if (parsed) return { type: 'component', component: parsed.uid, repeatable: parsed.repeatable };
+  const relation = parseRelationType(simpleType);
+  if (relation) return { type: 'relation', relation: relation.relType, target: expandRelationTarget(relation.target) };
+  const t = simpleType;
+  if (t === 'string') return { type: 'text' };
+  if (t === 'number') return { type: 'integer' };
+  if (t === 'boolean') return { type: 'boolean' };
+  if (t === 'date') return { type: 'datetime' };
+  if (t === 'media') return { type: 'media' };
+  if (t === 'media[]') return { type: 'media', multiple: true };
+  return { type: 'json' };
+}
+
+function pluralize(word) {
+  const w = word.toLowerCase();
+  if (/\w[^aeiou]y$/.test(w)) return w.slice(0, -1) + 'ies';
+  if (/[sxz]$|ch$|sh$/.test(w)) return w + 'es';
+  return w + 's';
+}
+
+function setLocalizationPluginOptions(pluginOptions, enable) {
+  const next = { ...(pluginOptions || {}) };
+  if (enable) {
+    next.i18n = { localized: true };
+    return next;
+  }
+  delete next.i18n;
+  return next;
+}
+
+function applyLocalizationToSchema(rawSchema, enable) {
+  const attrs = {};
+  for (const [k, v] of Object.entries(rawSchema.attributes ?? {})) {
+    const attr = { ...v };
+    const nextPluginOptions = setLocalizationPluginOptions(attr.pluginOptions, enable);
+    if (Object.keys(nextPluginOptions).length > 0) attr.pluginOptions = nextPluginOptions;
+    else delete attr.pluginOptions;
+    attrs[k] = attr;
+  }
+
+  const info = rawSchema.info ?? {
+    singularName: rawSchema.singularName,
+    pluralName: rawSchema.pluralName,
+    displayName: rawSchema.displayName,
+    ...(rawSchema.description != null ? { description: rawSchema.description } : {})
+  };
+  const options = rawSchema.options ?? {
+    draftAndPublish: rawSchema.draftAndPublish
+  };
+  const nextPluginOptions = setLocalizationPluginOptions(rawSchema.pluginOptions, enable);
+
+  const result = {
+    kind: rawSchema.kind,
+    collectionName: rawSchema.collectionName,
+    info,
+    options,
+    pluginOptions: nextPluginOptions,
+    attributes: attrs
+  };
+
+  if (rawSchema.visible !== undefined) result.visible = rawSchema.visible;
+  if (rawSchema.restrictRelationsTo !== undefined) result.restrictRelationsTo = rawSchema.restrictRelationsTo;
+
+  return result;
+}
+
+function buildStrapiSchema(contentType, snapshotBlock) {
+  const { singleType = false, attributes = {} } = snapshotBlock;
+  const localized = isLocalizedSnapshotBlock(snapshotBlock);
+  const kind = singleType ? 'singleType' : 'collectionType';
+  const singularName = contentType;
+  const displayName = contentType.charAt(0).toUpperCase() + contentType.slice(1).toLowerCase();
+  const collectionName = pluralize(contentType);
+  const pluralName = collectionName;
+  const i18nPluginOptions = { i18n: { localized: true } };
+  const attrs = {};
+  for (const [k, v] of Object.entries(attributes)) {
+    if (k === 'id') continue;
+    const attr = simpleTypeToStrapiAttr(v);
+    if (localized) attr.pluginOptions = i18nPluginOptions;
+    attrs[k] = attr;
+  }
+  return {
+    kind,
+    collectionName,
+    info: {
+      singularName,
+      pluralName,
+      displayName
+    },
+    options: { draftAndPublish: false },
+    pluginOptions: localized ? i18nPluginOptions : {},
+    attributes: attrs
+  };
+}
+
+function componentUidToPath(componentUid) {
+  const parts = componentUid.split('.');
+  const name = parts[parts.length - 1];
+  const category = parts.slice(0, -1).join('/');
+  return path.join('src', 'components', category, `${name}.json`);
+}
+
+function buildStrapiComponentSchema(componentUid, snapshotBlock) {
+  const { attributes = {} } = snapshotBlock;
+  const parts = componentUid.split('.');
+  const name = parts[parts.length - 1] || 'component';
+  const displayName = name.charAt(0).toUpperCase() + name.slice(1).replace(/-/g, ' ');
+  const collectionName = componentUid.replace(/\./g, '_');
+  const attrs = {};
+  for (const [k, v] of Object.entries(attributes)) {
+    if (k === 'id') continue;
+    attrs[k] = simpleTypeToStrapiAttr(v);
+  }
+  return {
+    collectionName,
+    info: { displayName },
+    attributes: attrs
+  };
+}
+
+function schemaPath(basePath, contentType) {
+  return path.join(basePath, 'src', 'api', contentType, 'content-types', contentType, 'schema.json');
+}
+
+function componentSchemaPath(basePath, componentUid) {
+  return path.join(basePath, componentUidToPath(componentUid));
+}
+
+function apiDir(basePath, contentType) {
+  return path.join(basePath, 'src', 'api', contentType);
+}
+
+function componentFile(basePath, componentUid) {
+  return path.join(basePath, componentUidToPath(componentUid));
+}
+
+const CORE_TEMPLATES = {
+  routes: (uid) => `'use strict';\n\nmodule.exports = require('@strapi/strapi').factories.createCoreRouter('${uid}');\n`,
+  controllers: (uid) => `'use strict';\n\nmodule.exports = require('@strapi/strapi').factories.createCoreController('${uid}');\n`,
+  services: (uid) => `'use strict';\n\nmodule.exports = require('@strapi/strapi').factories.createCoreService('${uid}');\n`
+};
+
+function writeCoreFilesLocal(base, contentType) {
+  const uid = `api::${contentType}.${contentType}`;
+  const apiPath = apiDir(base, contentType);
+  const routesDir = path.join(apiPath, 'routes');
+  const controllersDir = path.join(apiPath, 'controllers');
+  const servicesDir = path.join(apiPath, 'services');
+  [routesDir, controllersDir, servicesDir].forEach((dir) => {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  });
+  fs.writeFileSync(path.join(routesDir, `${contentType}.js`), CORE_TEMPLATES.routes(uid), 'utf8');
+  fs.writeFileSync(path.join(controllersDir, `${contentType}.js`), CORE_TEMPLATES.controllers(uid), 'utf8');
+  fs.writeFileSync(path.join(servicesDir, `${contentType}.js`), CORE_TEMPLATES.services(uid), 'utf8');
+}
+
+function createLocalUpdater(strapiProjectPath, projectPath) {
+  const base = path.isAbsolute(strapiProjectPath)
+    ? strapiProjectPath
+    : path.resolve(projectPath || process.cwd(), strapiProjectPath);
+  return {
+    async writeSchema(contentType, schemaObj) {
+      const schemaFilePath = schemaPath(base, contentType);
+      const dir = path.dirname(schemaFilePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(schemaFilePath, JSON.stringify(schemaObj, null, 2), 'utf8');
+    },
+    async writeCoreFiles(contentType) {
+      writeCoreFilesLocal(base, contentType);
+    },
+    async deleteContentType(contentType) {
+      const dir = apiDir(base, contentType);
+      if (fs.existsSync(dir)) {
+        fs.rmSync(dir, { recursive: true });
+      }
+    },
+    async listContentTypes() {
+      const apiPath = path.join(base, 'src', 'api');
+      if (!fs.existsSync(apiPath)) return [];
+      return fs.readdirSync(apiPath).filter((name) => {
+        const ctPath = path.join(apiPath, name, 'content-types', name);
+        return fs.existsSync(ctPath);
+      });
+    },
+    async writeComponent(componentUid, schemaObj) {
+      const filePath = componentFile(base, componentUid);
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(filePath, JSON.stringify(schemaObj, null, 2), 'utf8');
+    },
+    async listComponents() {
+      const componentsPath = path.join(base, 'src', 'components');
+      if (!fs.existsSync(componentsPath)) return [];
+      const uids = [];
+      const categories = fs.readdirSync(componentsPath);
+      for (const cat of categories) {
+        const catPath = path.join(componentsPath, cat);
+        if (!fs.statSync(catPath).isDirectory()) continue;
+        for (const file of fs.readdirSync(catPath)) {
+          if (file.endsWith('.json')) uids.push(`${cat}.${path.basename(file, '.json')}`);
+        }
+      }
+      return uids;
+    },
+    async deleteComponent(componentUid) {
+      const filePath = componentFile(base, componentUid);
+      if (fs.existsSync(filePath)) fs.rmSync(filePath);
+    }
+  };
+}
+
+function createSSHUpdater(remote, options) {
+  let Client;
+  try {
+    Client = require('ssh2').Client;
+  } catch (e) {
+    throw new Error('SSH schema update requires ssh2: npm install ssh2');
+  }
+  const conn = new Client();
+  const buildConnectionError = (error, config) => {
+    const parts = [];
+    if (config.username) parts.push(`user=${config.username}`);
+    if (config.host) parts.push(`host=${config.host}`);
+    if (config.port != null) parts.push(`port=${config.port}`);
+    if (config.password) parts.push('auth=password');
+    else if (config.privateKey) parts.push('auth=privateKey');
+    else parts.push('auth=default');
+    const message = `SSH connection failed (${parts.join(', ')}): ${error.message}`;
+    const wrapped = new Error(message);
+    wrapped.code = error.code;
+    wrapped.level = error.level;
+    wrapped.description = error.description;
+    wrapped.host = config.host;
+    wrapped.port = config.port;
+    wrapped.username = config.username;
+    wrapped.cause = error;
+    return wrapped;
+  };
+  const connect = () => new Promise((resolve, reject) => {
+    const config = {
+      host: remote.host,
+      username: options.strapiSSHUser || 'root',
+      port: options.strapiSSHPort || 22
+    };
+    if (options.strapiSSHPassword) {
+      config.password = options.strapiSSHPassword;
+    } else if (options.strapiSSHPrivateKeyPath) {
+      config.privateKey = fs.readFileSync(options.strapiSSHPrivateKeyPath, 'utf8');
+    }
+    conn.on('ready', () => resolve()).on('error', (error) => reject(buildConnectionError(error, config))).connect(config);
+  });
+  const exec = (cmd) => new Promise((resolve, reject) => {
+    conn.exec(cmd, (err, stream) => {
+      if (err) return reject(err);
+      let out = '';
+      stream.on('data', (d) => { out += d.toString(); }).on('close', (code) => resolve({ code, out }));
+    });
+  });
+  const base = remote.path;
+  const uid = (ct) => `api::${ct}.${ct}`;
+  const writeRemoteFile = async (filePath, content) => {
+    const b64 = Buffer.from(content, 'utf8').toString('base64');
+    const r = await exec(`mkdir -p $(dirname '${filePath}') && echo '${b64}' | base64 -d > '${filePath}'`);
+    if (r.code !== 0) throw new Error(r.out || `SSH exit ${r.code}`);
+  };
+  return {
+    async writeSchema(contentType, schemaObj) {
+      await connect();
+      const schemaFilePath = `${base}/src/api/${contentType}/content-types/${contentType}/schema.json`;
+      const dir = `${base}/src/api/${contentType}/content-types/${contentType}`;
+      const json = JSON.stringify(schemaObj, null, 2);
+      const b64 = Buffer.from(json, 'utf8').toString('base64');
+      const r = await exec(`mkdir -p '${dir}' && echo '${b64}' | base64 -d > '${schemaFilePath}'`);
+      if (r.code !== 0) {
+        conn.end();
+        throw new Error(r.out || `SSH exit ${r.code}`);
+      }
+      conn.end();
+    },
+    async writeCoreFiles(contentType) {
+      await connect();
+      const u = uid(contentType);
+      await writeRemoteFile(`${base}/src/api/${contentType}/routes/${contentType}.js`, CORE_TEMPLATES.routes(u));
+      await writeRemoteFile(`${base}/src/api/${contentType}/controllers/${contentType}.js`, CORE_TEMPLATES.controllers(u));
+      await writeRemoteFile(`${base}/src/api/${contentType}/services/${contentType}.js`, CORE_TEMPLATES.services(u));
+      conn.end();
+    },
+    async deleteContentType(contentType) {
+      await connect();
+      const dir = `${base}/src/api/${contentType}`;
+      const r = await exec(`rm -rf '${dir}'`);
+      conn.end();
+      if (r.code !== 0) throw new Error(r.out || `SSH exit ${r.code}`);
+    },
+    async listContentTypes() {
+      await connect();
+      const apiPath = `${base}/src/api`;
+      const r = await exec(`ls -1 '${apiPath}' 2>/dev/null || true`);
+      conn.end();
+      if (r.code !== 0) return [];
+      return r.out.trim().split('\n').filter(Boolean);
+    },
+    async writeComponent(componentUid, schemaObj) {
+      await connect();
+      const filePath = `${base}/${componentUidToPath(componentUid)}`.replace(/\\/g, '/');
+      const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+      const json = JSON.stringify(schemaObj, null, 2);
+      const b64 = Buffer.from(json, 'utf8').toString('base64');
+      const r = await exec(`mkdir -p '${dir}' && echo '${b64}' | base64 -d > '${filePath}'`);
+      conn.end();
+      if (r.code !== 0) throw new Error(r.out || `SSH exit ${r.code}`);
+    },
+    async listComponents() {
+      await connect();
+      const compPath = `${base}/src/components`;
+      const r = await exec(`find '${compPath}' -name '*.json' 2>/dev/null | sed 's|.*/src/components/||;s|\\.json||;s|/|\\.|g'` + " || true");
+      conn.end();
+      if (r.code !== 0 || !r.out) return [];
+      return r.out.trim().split('\n').filter(Boolean);
+    },
+    async deleteComponent(componentUid) {
+      await connect();
+      const filePath = `${base}/${componentUidToPath(componentUid)}`.replace(/\\/g, '/');
+      const r = await exec(`rm -f '${filePath}'`);
+      conn.end();
+      if (r.code !== 0) throw new Error(r.out || `SSH exit ${r.code}`);
+    }
+  };
+}
+
+function getSchemaUpdater(options) {
+  const raw = options.strapiProjectPath;
+  if (!raw || typeof raw !== 'string') return null;
+  if (options.strapiSSHHost) {
+    return createSSHUpdater({ host: options.strapiSSHHost, path: raw.trim() }, options);
+  }
+  return createLocalUpdater(raw, options.projectPath);
+}
+
+module.exports = {
+  buildStrapiSchema,
+  buildStrapiComponentSchema,
+  applyLocalizationToSchema,
+  getSchemaUpdater
+};

package/lib/snapshot-io.js

@@ -0,0 +1,343 @@
+const fs = require('fs');
+const { SNAPSHOT_VERSION } = require('./constants');
+const { mapWithConcurrency } = require('./async');
+const {
+  simplifyAttributeType,
+  entryToSnapshot,
+  buildSampleFromSimpleAttributes,
+  normalizeSimpleAttributeType,
+  validateSimpleAttributeType,
+  isPlainObject,
+  isSingleTypeLocaleMap
+} = require('./snapshot-utils');
+
+function getPluralNameFromSchema(type, schema, contentType) {
+  const ct = schema?.data?.contentType || schema?.contentType || schema?.data;
+  const p = ct?.pluralName ?? ct?.info?.pluralName ?? schema?.data?.contentType?.pluralName;
+  const plural = (p && String(p).toLowerCase()) || (contentType.endsWith('s') ? contentType : `${contentType}s`);
+  return plural;
+}
+
+function simplifyComponentAttributes(rawAttrs) {
+  if (!rawAttrs || typeof rawAttrs !== 'object') return {};
+  return Object.fromEntries(
+    Object.entries(rawAttrs).map(([k, v]) => [k, simplifyAttributeType(v)])
+  );
+}
+
+function normalizeAttributes(attributes) {
+  if (!attributes || typeof attributes !== 'object' || Array.isArray(attributes)) return {};
+  return Object.fromEntries(
+    Object.entries(attributes).map(([key, value]) => [key, normalizeSimpleAttributeType(value)])
+  );
+}
+
+function validateEntryList(entries, fieldPath, errors) {
+  if (!Array.isArray(entries)) {
+    errors.push(`${fieldPath} must be an array`);
+    return;
+  }
+  entries.forEach((entry, index) => {
+    if (!isPlainObject(entry)) {
+      errors.push(`${fieldPath}[${index}] must be an object`);
+    }
+  });
+}
+
+function validateAttributes(attributes, fieldPath, errors) {
+  if (!isPlainObject(attributes)) {
+    errors.push(`${fieldPath} must be an object`);
+    return;
+  }
+
+  for (const [name, type] of Object.entries(attributes)) {
+    if (!name || typeof name !== 'string') {
+      errors.push(`${fieldPath} contains an invalid attribute name`);
+      continue;
+    }
+    errors.push(...validateSimpleAttributeType(type, `${fieldPath}.${name}`));
+  }
+}
+
+function isSingleTypeEntryObject(entries, attributes) {
+  if (!isPlainObject(entries)) return false;
+  const entryKeys = Object.keys(entries);
+  const attributeKeys = Object.keys(attributes || {});
+  const systemKeys = new Set(['id', 'documentId', 'locale']);
+  return entryKeys.some((key) => attributeKeys.includes(key) || systemKeys.has(key));
+}
+
+function validateSnapshotBlock(block, fieldPath, errors, { requireSingleType }) {
+  if (!isPlainObject(block)) {
+    errors.push(`${fieldPath} must be an object`);
+    return;
+  }
+
+  if (requireSingleType) {
+    if (typeof block.singleType !== 'boolean') {
+      errors.push(`${fieldPath}.singleType must be a boolean`);
+    }
+  } else if ('singleType' in block && typeof block.singleType !== 'boolean') {
+    errors.push(`${fieldPath}.singleType must be a boolean`);
+  }
+
+  if ('attributes' in block) {
+    validateAttributes(block.attributes, `${fieldPath}.attributes`, errors);
+  } else if (requireSingleType) {
+    errors.push(`${fieldPath}.attributes is required`);
+  }
+
+  if (!('entries' in block)) return;
+
+  if (block.singleType === true) {
+    if (!isPlainObject(block.entries)) {
+      errors.push(`${fieldPath}.entries must be an object for singleType`);
+      return;
+    }
+    if (isSingleTypeEntryObject(block.entries, block.attributes)) {
+      return;
+    }
+    const entryPairs = Object.entries(block.entries);
+    const localePairs = entryPairs.filter(([key]) => /^[a-z]{2}(?:-[A-Z]{2})?$/.test(key));
+    if (localePairs.length > 0) {
+      if (localePairs.length !== entryPairs.length) {
+        errors.push(`${fieldPath}.entries must be either a single object or a locale-to-object map for singleType`);
+        return;
+      }
+      for (const [locale, entry] of localePairs) {
+        if (!locale.trim()) errors.push(`${fieldPath}.entries has an empty locale key`);
+        if (!isPlainObject(entry)) {
+          errors.push(`${fieldPath}.entries.${locale} must be an object for localized singleType`);
+        }
+      }
+      return;
+    }
+    return;
+  }
+
+  if (Array.isArray(block.entries)) {
+    validateEntryList(block.entries, `${fieldPath}.entries`, errors);
+    return;
+  }
+
+  if (!isPlainObject(block.entries)) {
+    errors.push(`${fieldPath}.entries must be an array or a locale map`);
+    return;
+  }
+
+  const localePairs = Object.entries(block.entries).filter(([key]) => /^[a-z]{2}(?:-[A-Z]{2})?$/.test(key));
+  if (localePairs.length === 0 || localePairs.length !== Object.keys(block.entries).length) {
+    errors.push(`${fieldPath}.entries must be an array or an object with locale keys`);
+    return;
+  }
+
+  for (const [locale, list] of Object.entries(block.entries)) {
+    if (!locale.trim()) {
+      errors.push(`${fieldPath}.entries has an empty locale key`);
+    }
+    validateEntryList(list, `${fieldPath}.entries.${locale}`, errors);
+  }
+}
+
+function validateSnapshotSyntax(snapshot) {
+  const errors = [];
+
+  if (!isPlainObject(snapshot)) {
+    errors.push('Snapshot root must be an object');
+    return errors;
+  }
+
+  if (!isPlainObject(snapshot.contentTypes)) {
+    errors.push('contentTypes must be an object');
+  } else {
+    for (const [contentType, block] of Object.entries(snapshot.contentTypes)) {
+      if (!contentType.trim()) {
+        errors.push('contentTypes contains an empty content type key');
+        continue;
+      }
+      validateSnapshotBlock(block, `contentTypes.${contentType}`, errors, { requireSingleType: true });
+    }
+  }
+
+  if ('components' in snapshot) {
+    if (!isPlainObject(snapshot.components)) {
+      errors.push('components must be an object');
+    } else {
+      for (const [uid, block] of Object.entries(snapshot.components)) {
+        if (!uid.trim()) {
+          errors.push('components contains an empty component UID');
+          continue;
+        }
+        validateSnapshotBlock(block, `components.${uid}`, errors, { requireSingleType: false });
+      }
+    }
+  }
+
+  return errors;
+}
+
+async function exportSnapshot(client, outputPath) {
+  const apiTypes = await client.getAllContentTypes();
+  const apiComponents = await client.getAllComponents();
+  const contentTypes = {};
+  const components = {};
+  for (const comp of apiComponents) {
+    const rawAttrs = comp.schema?.attributes ?? comp.attributes ?? {};
+    components[comp.uid] = { attributes: simplifyComponentAttributes(rawAttrs) };
+  }
+
+  const exportedTypes = await mapWithConcurrency(apiTypes, 4, async (type) => {
+    const contentType = type.uid?.includes('.') ? type.uid.split('.')[1] : (type.apiID || type.name);
+    const schema = await client.getContentTypeSchema(contentType);
+    const kind = type.kind ?? schema?.data?.contentType?.kind ?? schema?.data?.kind;
+    const singleType = kind === 'singleType';
+    const localized = !!(
+      type.schema?.pluginOptions?.i18n?.localized ??
+      (schema?.data?.contentType ?? schema?.contentType ?? schema?.data)?.pluginOptions?.i18n?.localized
+    );
+    const apiId = type.pluralName ?? getPluralNameFromSchema(type, schema, contentType);
+
+    const ct = schema?.data?.contentType || schema?.contentType || schema?.data;
+    const rawAttrs =
+      schema?.data?.contentType?.attributes ??
+      schema?.data?.schema?.attributes ??
+      schema?.attributes ??
+      ct?.attributes ??
+      {};
+    const attributes = normalizeAttributes(
+      Object.fromEntries(Object.entries(rawAttrs).map(([k, v]) => [k, simplifyAttributeType(v)]))
+    );
+    let entries = singleType ? {} : [];
+    try {
+      const withLocale = await client.getEntries(contentType, {}, {
+        singleType,
+        pageSize: singleType ? undefined : 500,
+        apiId,
+        locale: 'all',
+        localized
+      });
+      const hasLocale = Array.isArray(withLocale) && withLocale.length > 0 &&
+        withLocale.some((e) => e?.locale ?? e?.localization);
+      const locKey = (e) => e?.locale ?? e?.localization?.locale ?? 'en';
+
+      if (singleType && hasLocale) {
+        entries = {};
+        for (const entry of withLocale) {
+          const locale = locKey(entry);
+          entries[locale] = entryToSnapshot(entry, attributes);
+        }
+      } else if (singleType) {
+        entries = withLocale[0] ? entryToSnapshot(withLocale[0], attributes) : {};
+      } else if (hasLocale) {
+        const byLocale = {};
+        for (const e of withLocale) {
+          const loc = locKey(e);
+          if (!byLocale[loc]) byLocale[loc] = [];
+          byLocale[loc].push(entryToSnapshot(e, attributes));
+        }
+        entries = Object.keys(byLocale).length > 0 ? byLocale : withLocale.map((e) => entryToSnapshot(e, attributes));
+      } else {
+        entries = withLocale.map((e) => entryToSnapshot(e, attributes));
+      }
+    } catch (err) {
+      console.warn(`⚠️  Could not fetch entries for "${contentType}":`, err.message);
+    }
+
+    return [contentType, { singleType, attributes, entries }];
+  });
+
+  exportedTypes.forEach(([contentType, block]) => {
+    contentTypes[contentType] = block;
+  });
+
+  const snapshot = { version: SNAPSHOT_VERSION, contentTypes, components };
+  fs.writeFileSync(outputPath, JSON.stringify(snapshot, null, 2), 'utf8');
+}
+
+function normalizeSnapshotEntries(block) {
+  const { singleType = true, attributes = {}, entries = singleType ? {} : [], schema = null } = block;
+  const normalizedAttributes = normalizeAttributes(attributes);
+  let rawEntries = [];
+
+  if (singleType && isPlainObject(entries)) {
+    if (isSingleTypeLocaleMap(entries)) {
+      for (const [locale, entry] of Object.entries(entries)) {
+        rawEntries.push({ data: entry, locale });
+      }
+    } else if (Object.keys(entries).length > 0) {
+      rawEntries.push({ data: entries, source: 'snapshot' });
+    }
+  } else if (entries && typeof entries === 'object' && !Array.isArray(entries)) {
+    for (const [locale, list] of Object.entries(entries)) {
+      if (Array.isArray(list)) list.forEach((e) => rawEntries.push({ data: e, locale }));
+    }
+  } else if (Array.isArray(entries)) {
+    rawEntries = (entries || []).map((e) => ({ data: e, source: 'snapshot' }));
+  }
+
+  let objects = rawEntries.length > 0
+    ? rawEntries.map((o) =>
+        o.locale != null ? { data: o.data, locale: o.locale, source: 'snapshot' } : { data: o.data, source: 'snapshot' }
+      )
+    : (Array.isArray(entries) ? (entries || []).map((e) => ({ data: e, source: 'snapshot' })) : []);
+
+  if (objects.length === 0) {
+    const attrs =
+      Object.keys(attributes).length > 0
+        ? normalizedAttributes
+        : schema?.data?.contentType?.attributes ?? schema?.data?.schema?.attributes ?? schema?.attributes;
+    const simpleAttrs =
+      attrs && typeof attrs === 'object' && !Array.isArray(attrs)
+        ? Object.fromEntries(
+            Object.entries(attrs).map(([k, v]) => [k, typeof v === 'string' ? v : simplifyAttributeType(v)])
+          )
+        : {};
+    if (Object.keys(simpleAttrs).length > 0) {
+      objects = [{ data: buildSampleFromSimpleAttributes(simpleAttrs), source: 'schema-only' }];
+    }
+  }
+
+  return objects.map((o) => ({ ...o, singleType }));
+}
+
+function loadSnapshotFile(snapshotPath) {
+  const content = fs.readFileSync(snapshotPath, 'utf8');
+  const snap = JSON.parse(content);
+  const validationErrors = validateSnapshotSyntax(snap);
+  if (validationErrors.length > 0) {
+    throw new Error(`Invalid snapshot syntax:\n- ${validationErrors.join('\n- ')}`);
+  }
+
+  const groupedObjects = {};
+  const snapshotContentTypes = {};
+  for (const [contentType, block] of Object.entries(snap.contentTypes)) {
+    snapshotContentTypes[contentType] = {
+      ...block,
+      attributes: normalizeAttributes(block.attributes ?? {})
+    };
+    const objects = normalizeSnapshotEntries(block);
+    if (objects.length > 0) groupedObjects[contentType] = objects;
+  }
+
+  const snapshotComponents = Object.fromEntries(
+    Object.entries(snap.components || {}).map(([uid, block]) => [
+      uid,
+      {
+        ...block,
+        attributes: normalizeAttributes(block.attributes ?? {})
+      }
+    ])
+  );
+
+  return {
+    groupedObjects,
+    snapshotContentTypes,
+    snapshotComponents
+  };
+}
+
+module.exports = {
+  exportSnapshot,
+  loadSnapshotFile,
+  validateSnapshotSyntax
+};