feat: add asset management package for AM2.0 support

.talismanrc

@@ -1,8 +1,8 @@
 fileignoreconfig:
-  - filename: package-lock.json
-    checksum: 45100667793fc7dfaae3e24787871257e7f29e06df69ba10ec05b358d59ff15d
   - filename: pnpm-lock.yaml
-    checksum: 87d001c32b1d7f9df30a289c277e0ea13cfd8a0e2e5fa5118956ff4183683e5c
+    checksum: 69c9fefd1240e00e7efa17658a53292444de3eecc70fb93c719b3b92a8cac0f0
   - filename: .husky/pre-commit
     checksum: 7a12030ddfea18d6f85edc25f1721fb2009df00fdd42bab66b05de25ab3e32b2
+  - filename: packages/contentstack-migration/src/commands/cm/stacks/migration.ts
+    checksum: 8690833f285db085aa1431d4a708c243e2bf5b4ed366c5c15e2daf66eb24c19e
 version: '1.0'

package.json

@@ -10,16 +10,17 @@
   },
   "private": true,
   "scripts": {
-    "clean": "pnpm -r --filter './packages/*' run clean",
+    "clean:packages": "pnpm -r --filter './packages/*' run clean",
     "build": "pnpm -r --filter './packages/*' run build",
     "test": "pnpm -r --filter './packages/*' run test",
     "prepack": "pnpm -r --filter './packages/*' run prepack",
     "bootstrap": "pnpm install",
     "clean:modules": "rm -rf node_modules packages/**/node_modules",
     "clean:lock": "rm -f pnpm-lock.yaml",
-    "clean:all": "pnpm store prune && rm -rf node_modules && pnpm run clean",
+    "clean:all": "pnpm store prune && rm -rf node_modules && pnpm run clean:packages",
     "setup": "pnpm run clean:all && pnpm run bootstrap && pnpm run build",
-    "prepare": "npx husky && chmod +x .husky/pre-commit"
+    "prepare": "npx husky && chmod +x .husky/pre-commit",
+    "update:lockfile": "pnpm install --lockfile-only"
   },
   "license": "MIT",
   "packageManager": "pnpm@10.28.0",

packages/contentstack-asset-management/.eslintrc

@@ -0,0 +1,54 @@
+{
+    "env": {
+        "node": true
+    },
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "project": "tsconfig.json",
+        "sourceType": "module"
+    },
+    "extends": [
+        "oclif-typescript",
+        "plugin:@typescript-eslint/recommended"
+    ],
+    "rules": {
+        "@typescript-eslint/no-unused-vars": [
+            "error",
+            {
+                "args": "none"
+            }
+        ],
+        "@typescript-eslint/prefer-namespace-keyword": "error",
+        "@typescript-eslint/quotes": [
+            "error",
+            "single",
+            {
+                "avoidEscape": true,
+                "allowTemplateLiterals": true
+            }
+        ],
+        "semi": "off",
+        "@typescript-eslint/type-annotation-spacing": "error",
+        "@typescript-eslint/no-redeclare": "off",
+        "eqeqeq": [
+            "error",
+            "smart"
+        ],
+        "id-match": "error",
+        "no-eval": "error",
+        "no-var": "error",
+        "quotes": "off",
+        "indent": "off",
+        "camelcase": "off",
+        "comma-dangle": "off",
+        "arrow-parens": "off",
+        "operator-linebreak": "off",
+        "object-curly-spacing": "off",
+        "node/no-missing-import": "off",
+        "padding-line-between-statements": "off",
+        "@typescript-eslint/ban-ts-ignore": "off",
+        "unicorn/no-abusive-eslint-disable": "off",
+        "unicorn/consistent-function-scoping": "off",
+        "@typescript-eslint/no-use-before-define": "off"
+    }
+}

packages/contentstack-asset-management/.gitignore

@@ -0,0 +1,3 @@
+lib/
+node_modules/
+*.tsbuildinfo

packages/contentstack-asset-management/README.md

@@ -0,0 +1,49 @@
+# @contentstack/cli-asset-management
+
+Asset Management 2.0 API adapter for Contentstack CLI export and import. Used by the export and import plugins when Asset Management (AM 2.0) is enabled. To learn how to export and import content in Contentstack, refer to the [Migration guide](https://www.contentstack.com/docs/developers/cli/migration/).
+
+[![License](https://img.shields.io/npm/l/@contentstack/cli)](https://github.com/contentstack/cli/blob/main/LICENSE)
+
+<!-- toc -->
+* [@contentstack/cli-asset-management](#contentstackcli-asset-management)
+* [Overview](#overview)
+* [Usage](#usage)
+* [Exports](#exports)
+<!-- tocstop -->
+
+# Overview
+
+This package provides:
+
+- **AssetManagementAdapter** – HTTP client for the Asset Management API (spaces, assets, folders, fields, asset types).
+- **exportSpaceStructure** – Exports space metadata and full workspace structure (metadata, folders, assets, fields, asset types) for linked workspaces.
+- **Types** – `AssetManagementExportOptions`, `LinkedWorkspace`, `IAssetManagementAdapter`, and related types for export/import integration.
+
+# Usage
+
+This package is consumed by the export and import plugins. When using the export CLI with the `--asset-management` flag (or when the host app enables AM 2.0), the export plugin calls `exportSpaceStructure` with linked workspaces and options:
+
+```ts
+import { exportSpaceStructure } from '@contentstack/cli-asset-management';
+
+await exportSpaceStructure({
+  linkedWorkspaces,
+  exportDir,
+  branchName: 'main',
+  assetManagementUrl,
+  org_uid,
+  context,
+  progressManager,
+  progressProcessName,
+  updateStatus,
+  downloadAsset, // optional
+});
+```
+
+# Exports
+
+| Export | Description |
+|--------|-------------|
+| `exportSpaceStructure` | Async function to export space structure for given linked workspaces. |
+| `AssetManagementAdapter` | Class to call the Asset Management API (getSpace, getWorkspaceFields, getWorkspaceAssets, etc.). |
+| Types from `./types` | `AssetManagementExportOptions`, `ExportSpaceOptions`, `ChunkedJsonWriteOptions`, `LinkedWorkspace`, `SpaceResponse`, `FieldsResponse`, `AssetTypesResponse`, and related API types. |

packages/contentstack-asset-management/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@contentstack/cli-asset-management",
+  "version": "1.0.0",
+  "description": "Asset Management 2.0 API adapter for export and import",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "oclif.manifest.json"
+  ],
+  "scripts": {
+    "build": "pnpm compile",
+    "clean": "rm -rf ./lib ./node_modules tsconfig.build.tsbuildinfo",
+    "compile": "tsc -b tsconfig.json",
+    "postpack": "rm -f oclif.manifest.json",
+    "prepack": "pnpm compile && oclif manifest && oclif readme",
+    "version": "oclif readme && git add README.md",
+    "lint": "eslint src/**/*.ts",
+    "format": "eslint src/**/*.ts --fix",
+    "test": "nyc --extension .ts mocha --require ts-node/register --forbid-only \"test/**/*.test.ts\"",
+    "posttest": "npm run lint",
+    "test:unit": "mocha --require ts-node/register --forbid-only \"test/unit/**/*.test.ts\"",
+    "test:unit:report": "nyc --extension .ts mocha --require ts-node/register --forbid-only \"test/unit/**/*.test.ts\""
+  },
+  "keywords": [
+    "contentstack",
+    "asset-management",
+    "cli"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@contentstack/cli-utilities": "~2.0.0-beta"
+  },
+  "oclif": {
+    "commands": "./lib/commands",
+    "bin": "csdx",
+    "devPlugins": [
+      "@oclif/plugin-help"
+    ],
+    "repositoryPrefix": "<%- repo %>/blob/main/packages/contentstack-asset-management/<%- commandPath %>"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.11",
+    "@types/mocha": "^10.0.6",
+    "@types/node": "^20.17.50",
+    "@types/sinon": "^17.0.2",
+    "chai": "^4.4.1",
+    "eslint": "^8.57.1",
+    "eslint-config-oclif": "^6.0.68",
+    "mocha": "^10.8.2",
+    "nyc": "^15.1.0",
+    "oclif": "^4.17.46",
+    "sinon": "^17.0.1",
+    "source-map-support": "^0.5.21",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3"
+  }
+}

packages/contentstack-asset-management/src/constants/index.ts

@@ -0,0 +1,50 @@
+export const BATCH_SIZE = 50;
+export const CHUNK_FILE_SIZE_MB = 1;
+
+/**
+ * Main process name for Asset Management 2.0 export (single progress bar).
+ * Use this when adding/starting the process and for all ticks.
+ */
+export const AM_MAIN_PROCESS_NAME = 'Asset Management 2.0';
+
+/**
+ * Process names for Asset Management 2.0 export progress (for tick labels).
+ */
+export const PROCESS_NAMES = {
+  AM_SPACE_METADATA: 'Space metadata',
+  AM_FOLDERS: 'Folders',
+  AM_ASSETS: 'Assets',
+  AM_FIELDS: 'Fields',
+  AM_ASSET_TYPES: 'Asset types',
+  AM_DOWNLOADS: 'Asset downloads',
+} as const;
+
+/**
+ * Status messages for each process (exporting, fetching, failed).
+ */
+export const PROCESS_STATUS = {
+  [PROCESS_NAMES.AM_SPACE_METADATA]: {
+    EXPORTING: 'Exporting space metadata...',
+    FAILED: 'Failed to export space metadata.',
+  },
+  [PROCESS_NAMES.AM_FOLDERS]: {
+    FETCHING: 'Fetching folders...',
+    FAILED: 'Failed to fetch folders.',
+  },
+  [PROCESS_NAMES.AM_ASSETS]: {
+    FETCHING: 'Fetching assets...',
+    FAILED: 'Failed to fetch assets.',
+  },
+  [PROCESS_NAMES.AM_FIELDS]: {
+    FETCHING: 'Fetching fields...',
+    FAILED: 'Failed to fetch fields.',
+  },
+  [PROCESS_NAMES.AM_ASSET_TYPES]: {
+    FETCHING: 'Fetching asset types...',
+    FAILED: 'Failed to fetch asset types.',
+  },
+  [PROCESS_NAMES.AM_DOWNLOADS]: {
+    DOWNLOADING: 'Downloading asset files...',
+    FAILED: 'Failed to download assets.',
+  },
+} as const;

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

@@ -0,0 +1,28 @@
+import { log } from '@contentstack/cli-utilities';
+
+import type { AssetManagementAPIConfig } from '../types/asset-management-api';
+import type { ExportContext } from '../types/export-types';
+import { AssetManagementExportAdapter } from './base';
+import { getArrayFromResponse } from '../utils/export-helpers';
+import { PROCESS_NAMES } from '../constants/index';
+
+export default class ExportAssetTypes extends AssetManagementExportAdapter {
+  constructor(apiConfig: AssetManagementAPIConfig, exportContext: ExportContext) {
+    super(apiConfig, exportContext);
+  }
+
+  async start(spaceUid: string): Promise<void> {
+    await this.init();
+    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,
+    );
+    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

@@ -0,0 +1,100 @@
+import { resolve as pResolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { configHandler, log } from '@contentstack/cli-utilities';
+
+import type { AssetManagementAPIConfig, LinkedWorkspace } from '../types/asset-management-api';
+import type { ExportContext } from '../types/export-types';
+import { AssetManagementExportAdapter } from './base';
+import { getAssetItems, writeStreamToFile } from '../utils/export-helpers';
+import { PROCESS_NAMES, PROCESS_STATUS } from '../constants/index';
+
+export default class ExportAssets extends AssetManagementExportAdapter {
+  constructor(apiConfig: AssetManagementAPIConfig, exportContext: ExportContext) {
+    super(apiConfig, exportContext);
+  }
+
+  async start(workspace: LinkedWorkspace, spaceDir: string): Promise<void> {
+    await this.init();
+    const assetsDir = pResolve(spaceDir, 'assets');
+    await mkdir(assetsDir, { recursive: true });
+    log.debug(`Fetching folders and assets for space ${workspace.space_uid}`, this.exportContext.context);
+
+    const [folders, assetsData] = await Promise.all([
+      this.getWorkspaceFolders(workspace.space_uid),
+      this.getWorkspaceAssets(workspace.space_uid),
+    ]);
+
+    await writeFile(pResolve(assetsDir, 'folders.json'), JSON.stringify(folders, null, 2));
+    this.tick(true, `folders: ${workspace.space_uid}`, null);
+    log.debug(`Wrote folders.json for space ${workspace.space_uid}`, this.exportContext.context);
+
+    const assetItems = getAssetItems(assetsData);
+    log.debug(
+      assetItems.length === 0
+        ? `No assets for space ${workspace.space_uid}, wrote empty assets.json`
+        : `Writing ${assetItems.length} assets metadata for space ${workspace.space_uid}`,
+      this.exportContext.context,
+    );
+    await this.writeItemsToChunkedJson(
+      assetsDir,
+      'assets.json',
+      'assets',
+      ['uid', 'url', 'filename', 'file_name', 'parent_uid'],
+      assetItems,
+    );
+    this.tick(true, `assets: ${workspace.space_uid} (${assetItems.length})`, null);
+
+    await this.downloadWorkspaceAssets(assetsData, assetsDir, workspace.space_uid);
+  }
+
+  private async downloadWorkspaceAssets(
+    assetsData: unknown,
+    assetsDir: string,
+    spaceUid: string,
+  ): Promise<void> {
+    const items = getAssetItems(assetsData);
+    if (items.length === 0) {
+      log.debug('No assets to download', this.exportContext.context);
+      return;
+    }
+
+    this.updateStatus(PROCESS_STATUS[PROCESS_NAMES.AM_DOWNLOADS].DOWNLOADING);
+    log.debug(`Downloading ${items.length} asset file(s) for space ${spaceUid}...`, this.exportContext.context);
+    const filesDir = pResolve(assetsDir, 'files');
+    await mkdir(filesDir, { recursive: true });
+
+    const securedAssets = this.exportContext.securedAssets ?? false;
+    const authtoken = securedAssets ? configHandler.get('authtoken') : null;
+    let lastError: string | null = null;
+    let allSuccess = true;
+
+    for (const asset of items) {
+      const uid = asset.uid ?? asset._uid;
+      const url = asset.url;
+      const filename = asset.filename ?? asset.file_name ?? 'asset';
+      if (!url || !uid) continue;
+      try {
+        const separator = url.includes('?') ? '&' : '?';
+        const downloadUrl = securedAssets && authtoken ? `${url}${separator}authtoken=${authtoken}` : url;
+        const response = await fetch(downloadUrl);
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const body = response.body;
+        if (!body) throw new Error('No response body');
+        const nodeStream = Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]);
+        const assetFolderPath = pResolve(filesDir, uid);
+        await mkdir(assetFolderPath, { recursive: true });
+        const filePath = pResolve(assetFolderPath, filename);
+        await writeStreamToFile(nodeStream, filePath);
+        log.debug(`Downloaded asset ${uid}`, this.exportContext.context);
+      } catch (e) {
+        allSuccess = false;
+        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);
+  }
+}