feat(global-fields): switch to per-file export/import format

Replaces the bulk-array globalfields.json export with individual {uid}.json
files per global field, consistent with how content types are handled.

Export writes each global field to global_fields/{uid}.json instead of
collecting all into a single array file. Import and content-types modules
now use readGlobalFieldSchemas to scan the directory and read all per-file
schemas. The audit base command is updated to use the same function when
loading global field schemas for cross-reference validation.

The globalfields.json fileName config values are retained for type
compatibility but are no longer read or written at runtime.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: cs-raj

packages/contentstack-audit/src/audit-base-command.ts

@@ -14,9 +14,10 @@ import {
   CLIProgressManager,
   clearProgressModuleSetting,
   readContentTypeSchemas,
+  readGlobalFieldSchemas,
   generateUid
 } from '@contentstack/cli-utilities';
-import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
+import { createWriteStream, existsSync, mkdirSync, writeFileSync, rmSync } from 'fs';
 import config from './config';
 import { print } from './util/log';
 import { auditMsg } from './messages';
@@ -491,13 +492,9 @@ export abstract class AuditBaseCommand extends BaseCommand<typeof AuditBaseComma
    */
   getCtAndGfSchema() {
     const ctDirPath = join(this.sharedConfig.basePath, this.sharedConfig.moduleConfig['content-types'].dirName);
-    const gfPath = join(
-      this.sharedConfig.basePath,
-      this.sharedConfig.moduleConfig['global-fields'].dirName,
-      this.sharedConfig.moduleConfig['global-fields'].fileName,
-    );
+    const gfDirPath = join(this.sharedConfig.basePath, this.sharedConfig.moduleConfig['global-fields'].dirName);
 
-    const gfSchema = existsSync(gfPath) ? (JSON.parse(readFileSync(gfPath, 'utf8')) as ContentTypeStruct[]) : [];
+    const gfSchema = (readGlobalFieldSchemas(gfDirPath) || []) as ContentTypeStruct[];
     const ctSchema = (readContentTypeSchemas(ctDirPath) || []) as ContentTypeStruct[];
 
     return { ctSchema, gfSchema };

packages/contentstack-audit/src/config/index.ts

@@ -24,7 +24,7 @@ const config = {
     'global-fields': {
       name: 'global field',
       dirName: 'global_fields',
-      fileName: 'globalfields.json',
+      fileName: 'globalfields.json', // Not used - reads from individual files via readGlobalFieldSchemas
     },
     entries: {
       name: 'entries',

packages/contentstack-export/src/config/index.ts

@@ -98,7 +98,7 @@ const config: DefaultConfig = {
     },
     'global-fields': {
       dirName: 'global_fields',
-      fileName: 'globalfields.json',
+      fileName: 'globalfields.json', // Not used - writes individual {uid}.json files
       validKeys: ['title', 'uid', 'schema', 'options', 'singleton', 'description'],
     },
     assets: {

packages/contentstack-export/src/export/modules/global-fields.ts

@@ -17,14 +17,12 @@ export default class GlobalFieldsExport extends BaseClass {
   };
   private globalFieldsConfig: {
     dirName?: string;
-    fileName?: string;
     validKeys?: string[];
     fetchConcurrency?: number;
     writeConcurrency?: number;
     limit?: number;
   };
   private globalFieldsDirPath: string;
-  private globalFields: Record<string, unknown>[];
 
   constructor({ exportConfig, stackAPIClient }: ModuleClassParams) {
     super({ exportConfig, stackAPIClient });
@@ -41,7 +39,6 @@ export default class GlobalFieldsExport extends BaseClass {
       sanitizePath(getExportBasePath(exportConfig)),
       sanitizePath(this.globalFieldsConfig.dirName),
     );
-    this.globalFields = [];
     this.applyQueryFilters(this.qs, 'global-fields');
     this.exportConfig.context.module = MODULE_CONTEXTS.GLOBAL_FIELDS;
     this.currentModuleName = MODULE_NAMES[MODULE_CONTEXTS.GLOBAL_FIELDS];
@@ -66,20 +63,13 @@ export default class GlobalFieldsExport extends BaseClass {
 
       if (totalCount === 0) {
         log.info(messageHandler.parse('GLOBAL_FIELDS_NOT_FOUND'), this.exportConfig.context);
-        const globalFieldsFilePath = path.join(this.globalFieldsDirPath, this.globalFieldsConfig.fileName);
-        log.debug(`Writing global fields to: ${globalFieldsFilePath}`, this.exportConfig.context);
-        fsUtil.writeFile(globalFieldsFilePath, this.globalFields);
         this.completeProgress(true);
         return;
       }
 
       progress.updateStatus('Fetching global fields...');
       await this.getGlobalFields();
 
-      const globalFieldsFilePath = path.join(this.globalFieldsDirPath, this.globalFieldsConfig.fileName);
-      log.debug(`Writing global fields to: ${globalFieldsFilePath}`, this.exportConfig.context);
-      fsUtil.writeFile(globalFieldsFilePath, this.globalFields);
-
 
 
       this.completeProgressWithMessage();
@@ -133,14 +123,15 @@ export default class GlobalFieldsExport extends BaseClass {
           delete globalField[key];
         }
       }
-      this.globalFields.push(globalField);
+      const filePath = path.join(this.globalFieldsDirPath, `${globalField.uid}.json`);
+      fsUtil.writeFile(filePath, globalField);
 
       // Track progress for each global field
       this.progressManager?.tick(true, `global-field: ${globalField.uid}`);
     });
 
     log.debug(
-      `Sanitization complete. Total global fields processed: ${this.globalFields.length}`,
+      `Sanitization complete. Total global fields processed: ${globalFields.length}`,
       this.exportConfig.context,
     );
   }

packages/contentstack-import-setup/src/config/index.ts

@@ -87,7 +87,7 @@ const config: DefaultConfig = {
     },
     'global-fields': {
       dirName: 'global_fields',
-      fileName: 'globalfields.json',
+      fileName: 'globalfields.json', // Not used - reads individual {uid}.json files
       dependencies: ['extensions', 'marketplace-apps'],
     },
     'marketplace-apps': {

packages/contentstack-import/src/config/index.ts

@@ -177,7 +177,7 @@ const config: DefaultConfig = {
     },
     'global-fields': {
       dirName: 'global_fields',
-      fileName: 'globalfields.json',
+      fileName: 'globalfields.json', // Not used - reads individual {uid}.json files
       validKeys: ['title', 'uid', 'schema', 'options', 'singleton', 'description'],
       limit: 100,
     },

packages/contentstack-import/src/import/modules/content-types.ts

@@ -6,7 +6,7 @@
  */
 import * as path from 'path';
 import { find, cloneDeep, map } from 'lodash';
-import { sanitizePath, log, handleAndLogError, readContentTypeSchemas } from '@contentstack/cli-utilities';
+import { sanitizePath, log, handleAndLogError, readContentTypeSchemas, readGlobalFieldSchemas } from '@contentstack/cli-utilities';
 import { PATH_CONSTANTS } from '../../constants';
 import { ImportConfig, ModuleClassParams } from '../../types';
 import BaseClass, { ApiOptions } from './base-class';
@@ -50,7 +50,6 @@ export default class ContentTypesImport extends BaseClass {
   };
   private gFsConfig: {
     dirName: string;
-    fileName: string;
     validKeys: string[];
     limit: number;
     writeConcurrency?: number;
@@ -105,6 +104,7 @@ export default class ContentTypesImport extends BaseClass {
       ['__master.json', 'true'],
       ['__priority.json', 'true'],
       [PATH_CONSTANTS.FILES.SCHEMA, 'true'],
+      ['globalfields.json', 'true'],
       ['.DS_Store', 'true'],
     ]);
 
@@ -499,7 +499,7 @@ export default class ContentTypesImport extends BaseClass {
       'CONTENT TYPES: Analyzing import data...',
       async () => {
         const cts = readContentTypeSchemas(this.cTsFolderPath);
-        const gfs = fsUtil.readFile(path.resolve(this.gFsFolderPath, this.gFsConfig.fileName));
+        const gfs = readGlobalFieldSchemas(this.gFsFolderPath);
         const pendingGfs = fsUtil.readFile(this.gFsPendingPath);
         const pendingExt = fsUtil.readFile(this.extPendingPath);
         return [cts, gfs, pendingGfs, pendingExt];

packages/contentstack-import/src/import/modules/global-fields.ts

@@ -7,7 +7,7 @@
 
 import * as path from 'path';
 import { isEmpty, cloneDeep } from 'lodash';
-import { sanitizePath, log, handleAndLogError, GlobalFieldData, GlobalField } from '@contentstack/cli-utilities';
+import { sanitizePath, log, handleAndLogError, GlobalFieldData, GlobalField, readGlobalFieldSchemas } from '@contentstack/cli-utilities';
 import { PATH_CONSTANTS } from '../../constants';
 import {   fsUtil,
   fileHelper,
@@ -41,7 +41,6 @@ export default class ImportGlobalFields extends BaseClass {
   private existingGFs: Record<string, any>[];
   private gFsConfig: {
     dirName: string;
-    fileName: string;
     validKeys: string[];
     limit: number;
     writeConcurrency?: number;
@@ -430,12 +429,9 @@ export default class ImportGlobalFields extends BaseClass {
       }
 
       log.debug(`Found global fields folder: ${this.gFsFolderPath}`, this.importConfig.context);
-      this.gFs = fsUtil.readFile(path.join(this.gFsFolderPath, this.gFsConfig.fileName)) as Record<string, unknown>[];
+      this.gFs = readGlobalFieldSchemas(this.gFsFolderPath) as Record<string, unknown>[];
       if (!this.gFs || isEmpty(this.gFs)) {
-        log.info(
-          `No global fields found in file - '${path.join(this.gFsFolderPath, this.gFsConfig.fileName)}'`,
-          this.importConfig.context,
-        );
+        log.info(`No global fields found in directory - '${this.gFsFolderPath}'`, this.importConfig.context);
         return [0];
       }