merged changes

Author: shafeeqd959

.cursor/rules/README.md

@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
+
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

.talismanrc

@@ -1,6 +1,34 @@
 fileignoreconfig:
   - filename: pnpm-lock.yaml
-    checksum: 0efb2a2f86f58006abbacf7de17e0d498824c046d1d3cb58c6a64b7364e93ff5
-  - filename: packages/contentstack-audit/src/modules/assets.ts
-    checksum: 968dde65ca1e6526d3a16766c86d4d9976752ba8589c27facbbb4df7a8f1f963
+    checksum: 11bf156488b12f529ab393fffa8e9d8741388ef2929263e89650eada87bfcf8a
+  - filename: packages/contentstack-branches/README.md
+    checksum: ad32bd365db7f085cc2ea133d69748954606131ec6157a272a3471aea60011c2
+  - filename: packages/contentstack-branches/src/branch/diff-handler.ts
+    checksum: 3cd4d26a2142cab7cbf2094c9251e028467d17d6a1ed6daf22f21975133805f1
+  - filename: packages/contentstack-branches/src/commands/cm/branches/merge-status.ts
+    checksum: 6e5b959ddcc5ff68e03c066ea185fcf6c6e57b1819069730340af35aad8a93a8
+  - filename: packages/contentstack-branches/src/utils/create-branch.ts
+    checksum: d0613295ee26f7a77d026e40db0a4ab726fabd0a74965f729f1a66d1ef14768f
+  - filename: packages/contentstack-branches/src/branch/merge-handler.ts
+    checksum: 4fd8dba9b723733530b9ba12e81e1d3e5d60b73ac4c082defb10593f257bb133
+  - filename: packages/contentstack-export/src/export/modules/environments.ts
+    checksum: a92c5de7ed8e80f08f911727973a66e0416b4a52265c275d1d25c3095f912811
+  - filename: packages/contentstack-import/src/utils/backup-handler.ts
+    checksum: 9a892b5c4b5aac230fb5969e7f34afdac0b6f96208e64bf9d1195468c935c66c
+  - filename: packages/contentstack-import/test/unit/utils/backup-handler.test.ts
+    checksum: 69860727e9b3099d8e1e95db2af17fc8b161684f675477981d27877cd8e1b3bb
+  - filename: pnpm-lock.yaml
+    checksum: 11bf156488b12f529ab393fffa8e9d8741388ef2929263e89650eada87bfcf8a
+  - filename: packages/contentstack-export/test/unit/export/modules/marketplace-apps.test.ts
+    checksum: 299b8f60cce1f64be7c20786d6a7c9c370474b97b06d1846114a76a70ec20cf7
+  - filename: packages/contentstack-export/test/unit/export/module-exporter.test.ts
+    checksum: 67b70c93ed679ccb2c61d0c277380676e33c91da8a423f948e81937e5d1d9479
+  - filename: packages/contentstack-asset-management/src/import/assets.ts
+    checksum: ed6af5d798282808c09643e1dcd1eaede89ce2b09bd0425998af64849b4f3f61
+  - filename: skills/code-review/SKILL.md
+    checksum: 29673e16f6b41fcec7fa236912e7f72b920ed4a3d9a66a89308b4a058b247f3e
+  - filename: skills/contentstack-cli/SKILL.md
+    checksum: 36762d43bbacedd0b344f9d4f1179a88e3dbc7e2467341ba42198dcd1bf9e40c
+  - filename: skills/testing/SKILL.md
+    checksum: ee1c82f1bb51860cb26fb9f112a53df0127e316fcb22a094034024741251fa3c
 version: '1.0'

AGENTS.md

@@ -0,0 +1,45 @@
+# Contentstack CLI plugins – Agent guide
+
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
+
+## What this repo is
+
+| Field | Detail |
+| --- | --- |
+| **Name:** | Contentstack CLI plugins (pnpm monorepo; root package name `csdx`) |
+| **Purpose:** | OCLIF plugins that extend the Contentstack CLI (import/export, clone, migration, seed, audit, variants, etc.). |
+| **Out of scope (if any):** | The **core** CLI aggregation lives in the separate `cli` monorepo; this repo ships plugin packages only. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| **Language** | TypeScript / JavaScript, Node **>= 18** (`engines` in root `package.json`) |
+| **Build** | pnpm workspaces (`packages/*`); per package: `tsc`, OCLIF manifest/readme where applicable → `lib/` |
+| **Tests** | Mocha + Chai; layouts under `packages/*/test/` (see [skills/testing/SKILL.md](skills/testing/SKILL.md)) |
+| **Lint / coverage** | ESLint in packages that define `lint` scripts; nyc where configured |
+| **Other** | OCLIF v4, Husky |
+
+## Commands (quick reference)
+
+| Command type | Command |
+| --- | --- |
+| **Build** | `pnpm build` |
+| **Test** | `pnpm test` |
+| **Lint** | `pnpm run lint` in a package that defines `lint` (no root aggregate lint script) |
+
+CI: [.github/workflows/unit-test.yml](.github/workflows/unit-test.yml) and other workflows under [.github/workflows/](.github/workflows/).
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Development workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | pnpm commands, CI, TDD expectations, PR checklist |
+| Contentstack CLI | [skills/contentstack-cli/SKILL.md](skills/contentstack-cli/SKILL.md) | Plugin commands, OCLIF, Contentstack APIs |
+| Framework | [skills/framework/SKILL.md](skills/framework/SKILL.md) | Utilities, config, logging, errors |
+| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Mocha/Chai, coverage, mocks |
+| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR review for this monorepo |
+
+## Using Cursor (optional)
+
+If you use **Cursor**, [.cursor/rules/README.md](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

packages/contentstack-asset-management/src/export/asset-types.ts

@@ -13,15 +13,17 @@ export default class ExportAssetTypes extends AssetManagementExportAdapter {
 
   async start(spaceUid: string): Promise<void> {
     await this.init();
+
+    log.debug('Starting shared asset types export process...', this.exportContext.context);
+
     const assetTypesData = await this.getWorkspaceAssetTypes(spaceUid);
     const items = getArrayFromResponse(assetTypesData, 'asset_types');
     const dir = this.getAssetTypesDir();
-    log.debug(
-      items.length === 0
-        ? 'No asset types, wrote empty asset-types'
-        : `Writing ${items.length} shared asset types`,
-      this.exportContext.context,
-    );
+    if (items.length === 0) {
+      log.info('No asset types to export, writing empty asset-types', this.exportContext.context);
+    } else {
+      log.debug(`Writing ${items.length} shared asset types`, this.exportContext.context);
+    }
     await this.writeItemsToChunkedJson(dir, 'asset-types.json', 'asset_types', ['uid', 'title', 'category', 'file_extension'], items);
     this.tick(true, PROCESS_NAMES.AM_ASSET_TYPES, null);
   }

packages/contentstack-asset-management/src/export/assets.ts

@@ -7,6 +7,7 @@ import type { AssetManagementAPIConfig, LinkedWorkspace } from '../types/asset-m
 import type { ExportContext } from '../types/export-types';
 import { AssetManagementExportAdapter } from './base';
 import { getAssetItems, writeStreamToFile } from '../utils/export-helpers';
+import { runInBatches } from '../utils/concurrent-batch';
 import { PROCESS_NAMES, PROCESS_STATUS } from '../constants/index';
 
 export default class ExportAssets extends AssetManagementExportAdapter {
@@ -16,8 +17,14 @@ export default class ExportAssets extends AssetManagementExportAdapter {
 
   async start(workspace: LinkedWorkspace, spaceDir: string): Promise<void> {
     await this.init();
+
+    log.debug(`Starting assets export for space ${workspace.space_uid}`, this.exportContext.context);
+    log.info(`Exporting asset folders, metadata, and files for space ${workspace.space_uid}`, this.exportContext.context);
+
     const assetsDir = pResolve(spaceDir, 'assets');
     await mkdir(assetsDir, { recursive: true });
+    log.debug(`Assets directory ready: ${assetsDir}`, this.exportContext.context);
+
     log.debug(`Fetching folders and assets for space ${workspace.space_uid}`, this.exportContext.context);
 
     const [folders, assetsData] = await Promise.all([
@@ -43,37 +50,61 @@ export default class ExportAssets extends AssetManagementExportAdapter {
       ['uid', 'url', 'filename', 'file_name', 'parent_uid'],
       assetItems,
     );
+    log.debug(
+      `Finished writing chunked assets metadata (${assetItems.length} item(s)) under ${assetsDir}`,
+      this.exportContext.context,
+    );
+    log.info(
+      assetItems.length === 0
+        ? `Wrote empty asset metadata for space ${workspace.space_uid}`
+        : `Wrote ${assetItems.length} asset metadata record(s) for space ${workspace.space_uid}`,
+      this.exportContext.context,
+    );
     this.tick(true, `assets: ${workspace.space_uid} (${assetItems.length})`, null);
 
+    log.debug(`Starting binary downloads for space ${workspace.space_uid}`, this.exportContext.context);
     await this.downloadWorkspaceAssets(assetsData, assetsDir, workspace.space_uid);
   }
 
-  private async downloadWorkspaceAssets(
-    assetsData: unknown,
-    assetsDir: string,
-    spaceUid: string,
-  ): Promise<void> {
+  private async downloadWorkspaceAssets(assetsData: unknown, assetsDir: string, spaceUid: string): Promise<void> {
     const items = getAssetItems(assetsData);
     if (items.length === 0) {
+      log.info(`No asset files to download for space ${spaceUid}`, this.exportContext.context);
       log.debug('No assets to download', this.exportContext.context);
       return;
     }
 
     this.updateStatus(PROCESS_STATUS[PROCESS_NAMES.AM_DOWNLOADS].DOWNLOADING);
+    log.info(`Downloading asset files for space ${spaceUid} (${items.length} in metadata)`, this.exportContext.context);
     log.debug(`Downloading ${items.length} asset file(s) for space ${spaceUid}...`, this.exportContext.context);
     const filesDir = pResolve(assetsDir, 'files');
     await mkdir(filesDir, { recursive: true });
+    log.debug(`Asset files directory ready: ${filesDir}`, this.exportContext.context);
 
     const securedAssets = this.exportContext.securedAssets ?? false;
     const authtoken = securedAssets ? configHandler.get('authtoken') : null;
+    log.debug(
+      `Asset downloads: securedAssets=${securedAssets}, concurrency=${this.downloadAssetsBatchConcurrency}`,
+      this.exportContext.context,
+    );
     let lastError: string | null = null;
     let allSuccess = true;
+    let downloadOk = 0;
+    let downloadFail = 0;
 
-    for (const asset of items) {
+    const validItems = items.filter((asset) => Boolean(asset.url && (asset.uid ?? asset._uid)));
+    const skipped = items.length - validItems.length;
+    if (skipped > 0) {
+      log.debug(
+        `Skipping ${skipped} asset row(s) without url or uid (${validItems.length} file download(s) scheduled)`,
+        this.exportContext.context,
+      );
+    }
+    await runInBatches(validItems, this.downloadAssetsBatchConcurrency, async (asset) => {
       const uid = asset.uid ?? asset._uid;
       const url = asset.url;
       const filename = asset.filename ?? asset.file_name ?? 'asset';
-      if (!url || !uid) continue;
+      if (!url || !uid) return;
       try {
         const separator = url.includes('?') ? '&' : '?';
         const downloadUrl = securedAssets && authtoken ? `${url}${separator}authtoken=${authtoken}` : url;
@@ -86,15 +117,26 @@ export default class ExportAssets extends AssetManagementExportAdapter {
         await mkdir(assetFolderPath, { recursive: true });
         const filePath = pResolve(assetFolderPath, filename);
         await writeStreamToFile(nodeStream, filePath);
-        log.debug(`Downloaded asset ${uid}`, this.exportContext.context);
+        downloadOk += 1;
+        log.debug(`Downloaded asset ${uid} → ${filePath}`, this.exportContext.context);
       } catch (e) {
         allSuccess = false;
+        downloadFail += 1;
         lastError = (e as Error)?.message ?? PROCESS_STATUS[PROCESS_NAMES.AM_DOWNLOADS].FAILED;
         log.debug(`Failed to download asset ${uid}: ${e}`, this.exportContext.context);
       }
-    }
+    });
 
     this.tick(allSuccess, `downloads: ${spaceUid}`, lastError);
-    log.debug('Asset downloads completed', this.exportContext.context);
+    log.info(
+      allSuccess
+        ? `Finished downloading ${downloadOk} asset file(s) for space ${spaceUid}`
+        : `Asset downloads for space ${spaceUid} completed with errors: ${downloadOk} succeeded, ${downloadFail} failed`,
+      this.exportContext.context,
+    );
+    log.debug(
+      `Asset downloads finished for space ${spaceUid}: ok=${downloadOk}, failed=${downloadFail}, allSuccess=${allSuccess}`,
+      this.exportContext.context,
+    );
   }
 }

packages/contentstack-asset-management/src/export/base.ts

@@ -5,7 +5,7 @@ import { FsUtility, log, CLIProgressManager, configHandler } from '@contentstack
 import type { AssetManagementAPIConfig } from '../types/asset-management-api';
 import type { ExportContext } from '../types/export-types';
 import { AssetManagementAdapter } from '../utils/asset-management-api-adapter';
-import { AM_MAIN_PROCESS_NAME, FALLBACK_AM_CHUNK_FILE_SIZE_MB } from '../constants/index';
+import { AM_MAIN_PROCESS_NAME, FALLBACK_AM_API_CONCURRENCY, FALLBACK_AM_CHUNK_FILE_SIZE_MB } from '../constants/index';
 
 export type { ExportContext };
 
@@ -63,6 +63,16 @@ export class AssetManagementExportAdapter extends AssetManagementAdapter {
     return this.exportContext.spacesRootPath;
   }
 
+  /** Parallel AM export limit for bootstrap and default batch operations. */
+  protected get apiConcurrency(): number {
+    return this.exportContext.apiConcurrency ?? FALLBACK_AM_API_CONCURRENCY;
+  }
+
+  /** Asset download batch size; falls back to {@link apiConcurrency}. */
+  protected get downloadAssetsBatchConcurrency(): number {
+    return this.exportContext.downloadAssetsConcurrency ?? this.apiConcurrency;
+  }
+
   protected getAssetTypesDir(): string {
     return pResolve(this.exportContext.spacesRootPath, 'asset_types');
   }

packages/contentstack-asset-management/src/export/fields.ts

@@ -13,13 +13,17 @@ export default class ExportFields extends AssetManagementExportAdapter {
 
   async start(spaceUid: string): Promise<void> {
     await this.init();
+
+    log.debug('Starting shared fields export process...', this.exportContext.context);
+
     const fieldsData = await this.getWorkspaceFields(spaceUid);
     const items = getArrayFromResponse(fieldsData, 'fields');
     const dir = this.getFieldsDir();
-    log.debug(
-      items.length === 0 ? 'No field items, wrote empty fields' : `Writing ${items.length} shared fields`,
-      this.exportContext.context,
-    );
+    if (items.length === 0) {
+      log.info('No field items to export, writing empty fields', this.exportContext.context);
+    } else {
+      log.debug(`Writing ${items.length} shared fields`, this.exportContext.context);
+    }
     await this.writeItemsToChunkedJson(dir, 'fields.json', 'fields', ['uid', 'title', 'display_type'], items);
     this.tick(true, PROCESS_NAMES.AM_FIELDS, null);
   }

packages/contentstack-asset-management/src/export/spaces.ts

@@ -1,6 +1,6 @@
 import { resolve as pResolve } from 'node:path';
 import { mkdir } from 'node:fs/promises';
-import { log, CLIProgressManager, configHandler } from '@contentstack/cli-utilities';
+import { log, CLIProgressManager, configHandler, handleAndLogError } from '@contentstack/cli-utilities';
 
 import type { AssetManagementExportOptions, AssetManagementAPIConfig } from '../types/asset-management-api';
 import type { ExportContext } from '../types/export-types';
@@ -46,6 +46,8 @@ export class ExportSpaces {
       return;
     }
 
+    log.debug('Starting Asset Management export process...', context);
+    log.info('Started Asset Management export', context);
     log.debug(`Exporting Asset Management 2.0 (${linkedWorkspaces.length} space(s))`, context);
     log.debug(`Spaces: ${linkedWorkspaces.map((ws) => ws.space_uid).join(', ')}`, context);
 
@@ -70,6 +72,8 @@ export class ExportSpaces {
       context,
       securedAssets,
       chunkFileSizeMb,
+      apiConcurrency: this.options.apiConcurrency,
+      downloadAssetsConcurrency: this.options.downloadAssetsConcurrency,
     };
 
     const sharedFieldsDir = pResolve(spacesRootPath, 'fields');
@@ -81,11 +85,9 @@ export class ExportSpaces {
     try {
       const exportAssetTypes = new ExportAssetTypes(apiConfig, exportContext);
       exportAssetTypes.setParentProgressManager(progress);
-      await exportAssetTypes.start(firstSpaceUid);
-
       const exportFields = new ExportFields(apiConfig, exportContext);
       exportFields.setParentProgressManager(progress);
-      await exportFields.start(firstSpaceUid);
+      await Promise.all([exportAssetTypes.start(firstSpaceUid), exportFields.start(firstSpaceUid)]);
 
       for (const ws of linkedWorkspaces) {
         progress.updateStatus(`Exporting space: ${ws.space_uid}...`, AM_MAIN_PROCESS_NAME);
@@ -109,9 +111,11 @@ export class ExportSpaces {
       }
 
       progress.completeProcess(AM_MAIN_PROCESS_NAME, true);
+      log.info('Asset Management export completed successfully', context);
       log.debug('Asset Management 2.0 export completed', context);
     } catch (err) {
       progress.completeProcess(AM_MAIN_PROCESS_NAME, false);
+      handleAndLogError(err, { ...(context as Record<string, unknown>) }, 'Asset Management export failed');
       throw err;
     }
   }

packages/contentstack-asset-management/src/export/workspaces.ts

@@ -15,6 +15,9 @@ export default class ExportWorkspace extends AssetManagementExportAdapter {
 
   async start(workspace: LinkedWorkspace, spaceDir: string, branchName: string): Promise<void> {
     await this.init();
+
+    log.debug(`Starting export for AM space ${workspace.space_uid}`, this.exportContext.context);
+
     const spaceResponse = await this.getSpace(workspace.space_uid);
     const space = spaceResponse.space;
     await mkdir(spaceDir, { recursive: true });
@@ -25,7 +28,13 @@ export default class ExportWorkspace extends AssetManagementExportAdapter {
       is_default: workspace.is_default,
       branch: branchName || 'main',
     };
-    await writeFile(pResolve(spaceDir, 'metadata.json'), JSON.stringify(metadata, null, 2));
+    const metadataPath = pResolve(spaceDir, 'metadata.json');
+    try {
+      await writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    } catch (e) {
+      log.warn(`Could not write ${metadataPath}: ${e}`, this.exportContext.context);
+      throw e;
+    }
     this.tick(true, `space: ${workspace.space_uid}`, null);
     log.debug(`Space metadata written for ${workspace.space_uid}`, this.exportContext.context);