@contentstack/cli-cm-export-query 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Contentstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# Contentstack CLI Query Export Plugin
+
+A powerful CLI plugin for Contentstack that enables query-based content export with intelligent dependency resolution and asset reference detection.
+
+## Overview
+
+This plugin extends the Contentstack CLI to export content based on custom queries, automatically resolving dependencies between content types, global fields, extensions, and taxonomies. It intelligently detects and exports referenced assets to ensure complete content portability.
+
+## Features
+
+- 🔍 **Query-based Export**: Export content using custom queries instead of entire content types
+- 🔗 **Dependency Resolution**: Automatically resolve and export dependencies (global fields, extensions, taxonomies)
+- 🖼️ **Asset Reference Detection**: Intelligent detection of asset references in various formats
+- 📁 **Organized Output**: Well-structured export with separate folders for each module
+- ⚙️ **Configurable**: Support for external config files and flexible options
+- 🌐 **Multi-locale Support**: Export content across different locales
+- 📊 **Export Metadata**: Comprehensive metadata tracking for export operations
+
+## Installation
+
+```bash
+# Install as a Contentstack CLI plugin
+npm install -g @contentstack/cli-cm-export-query
+
+# Or install locally
+npm install @contentstack/cli-cm-export-query
+```
+
+## Usage
+
+### Basic Export
+
+```bash
+# Export using management token alias
+csdx cm:stacks:export-query -a <alias> -q "{'title': {'$exists': true}}"
+
+# Export using API key and management token
+csdx cm:stacks:export-query --stack-api-key <api-key> -A <management-token> -q "{'title': {'$exists': true}}"
+```
+
+### Command Options
+
+| Flag | Description | Required |
+|------|-------------|----------|
+| `-a, --alias` | Management token alias | Yes (or use -A) |
+| `-A, --management-token` | Management token | Yes (or use -a) |
+| `--stack-api-key` | Stack API key | Yes |
+| `-q, --query` | Query for content export | Yes |
+| `-d, --data-dir` | Export directory path | No |
+| `--branch` | Branch name | No |
+| `--skip-references` | Skip reference resolution | No |
+| `--skip-dependencies` | Skip dependency export | No |
+| `--secured-assets` | Include secured assets | No |
+| `--config` | External config file path | No |
+
+### Query Examples
+
+**Basic Content Query:**
+```bash
+csdx cm:stacks:export-query -a prod -q "{'title': {'$regex': 'blog'}}"
+```
+
+**Date Range Query:**
+```bash
+csdx cm:stacks:export-query -a prod -q "{'updated_at': {'$gte': '2024-01-01'}}"
+```
+
+**Complex Query:**
+```bash
+csdx cm:stacks:export-query -a prod -q "{'$and': [{'title': {'$exists': true}}, {'tags': {'$in': ['featured']}}]}"
+```
+
+## Configuration
+
+### Default Configuration
+
+The plugin includes a default configuration file at `src/config/export-defaults.json`:
+
+```json
+{
+  "skipReferences": false,
+  "skipDependencies": false,
+  "securedAssets": false,
+  "includeGlobalFieldSchema": true,
+  "includePublishDetails": true,
+  "includeDimension": false,
+  "fetchConcurrency": 5,
+  "writeConcurrency": 5,
+  "batchSize": 100
+}
+```
+
+### External Configuration
+
+Create a custom config file and pass it using the `--config` flag:
+
+```json
+{
+  "skipReferences": true,
+  "batchSize": 50,
+  "fetchConcurrency": 3,
+  "securedAssets": true
+}
+```
+
+```bash
+csdx cm:stacks:export-query -a prod -q "{'title': {'$exists': true}}" --config ./my-config.json
+```

package/lib/commands/cm/stacks/export-query.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@contentstack/cli-command';
+import { FlagInput } from '@contentstack/cli-utilities';
+export default class ExportQueryCommand extends Command {
+    static description: string;
+    private exportDir;
+    static examples: string[];
+    static usage: string;
+    static flags: FlagInput;
+    static aliases: string[];
+    run(): Promise<void>;
+}

package/lib/commands/cm/stacks/export-query.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_command_1 = require("@contentstack/cli-command");
+const cli_utilities_1 = require("@contentstack/cli-utilities");
+const query_executor_1 = require("../../../core/query-executor");
+const utils_1 = require("../../../utils");
+class ExportQueryCommand extends cli_command_1.Command {
+    async run() {
+        try {
+            const { flags } = await this.parse(ExportQueryCommand);
+            // Setup export configuration
+            const exportQueryConfig = await (0, utils_1.setupQueryExportConfig)(flags);
+            exportQueryConfig.host = this.cmaHost;
+            exportQueryConfig.region = this.region;
+            if (this.developerHubUrl) {
+                exportQueryConfig.developerHubBaseUrl = this.developerHubUrl;
+            }
+            this.exportDir = (0, cli_utilities_1.sanitizePath)(exportQueryConfig.exportDir);
+            // Initialize and run query export
+            const managementAPIClient = await (0, cli_utilities_1.managementSDKClient)(exportQueryConfig);
+            const queryExporter = new query_executor_1.QueryExporter(managementAPIClient, exportQueryConfig);
+            await queryExporter.execute();
+            (0, utils_1.log)(exportQueryConfig, 'Query-based export completed successfully!', 'success');
+            (0, utils_1.log)(exportQueryConfig, `Export files saved to: ${this.exportDir}`, 'info');
+        }
+        catch (error) {
+            (0, utils_1.log)({ exportDir: this.exportDir }, `Export failed: ${(0, cli_utilities_1.formatError)(error)}`, 'error');
+            throw error;
+        }
+    }
+}
+exports.default = ExportQueryCommand;
+ExportQueryCommand.description = 'Export content from a stack using query-based filtering';
+ExportQueryCommand.examples = [
+    'csdx cm:stacks:export-query --query \'{"modules":{"content-types":{"title":{"$in":["Blog","Author"]}}}}\'',
+    'csdx cm:stacks:export-query --query ./ct-query.json --skip-references',
+    'csdx cm:stacks:export-query --alias <alias> --query \'{"modules":{"entries":{"content_type_uid":"blog"}}}\'',
+    'csdx cm:stacks:export-query --query \'{"modules":{"assets":{"title":{"$regex":"image"}}}}\'',
+];
+ExportQueryCommand.usage = 'cm:stacks:export-query --query <value> [options]';
+ExportQueryCommand.flags = {
+    config: cli_utilities_1.flags.string({
+        char: 'c',
+        description: 'Path to the configuration file',
+    }),
+    'stack-api-key': cli_utilities_1.flags.string({
+        char: 'k',
+        description: 'Stack API key',
+    }),
+    'data-dir': cli_utilities_1.flags.string({
+        char: 'd',
+        description: 'Path to store exported content',
+    }),
+    alias: cli_utilities_1.flags.string({
+        char: 'a',
+        description: 'Management token alias',
+    }),
+    branch: cli_utilities_1.flags.string({
+        description: 'Branch name to export from',
+    }),
+    query: cli_utilities_1.flags.string({
+        required: true,
+        description: 'Query as JSON string or file path',
+    }),
+    'skip-references': cli_utilities_1.flags.boolean({
+        description: 'Skip referenced content types',
+    }),
+    'skip-dependencies': cli_utilities_1.flags.boolean({
+        description: 'Skip dependent modules (global-fields, extensions, taxonomies)',
+    }),
+    'secured-assets': cli_utilities_1.flags.boolean({
+        description: 'Export secured assets',
+    }),
+    yes: cli_utilities_1.flags.boolean({
+        char: 'y',
+        description: 'Skip confirmation prompts',
+    }),
+};
+ExportQueryCommand.aliases = ['cm:export-query'];

package/lib/config/export-config.json

@@ -0,0 +1 @@
+{ "skipDependencies": true, "skipStackSettings": false, "personalizationEnabled": true }

package/lib/config/index.d.ts

@@ -0,0 +1,3 @@
+import { DefaultConfig } from '../types';
+declare const config: DefaultConfig;
+export default config;

package/lib/config/index.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config = {
+    contentVersion: 2,
+    host: 'https://api.contentstack.io/v3',
+    // Query-based export module configuration
+    modules: {
+        // Always export - general modules
+        general: ['stack', 'locales', 'environments'],
+        // Query target modules
+        queryable: ['content-types'],
+        dependent: ['global-fields', 'extensions', 'marketplace-apps', 'taxonomies', 'personalize'],
+        // Content modules
+        content: ['entries', 'assets'],
+        // Export order based on dependencies
+        exportOrder: [
+            'stack',
+            'locales',
+            'environments',
+            'content-types',
+            'global-fields',
+            'extensions',
+            'taxonomies',
+            'entries',
+            'assets',
+        ],
+    },
+    // Query-specific settings
+    queryConfig: {
+        maxRecursionDepth: 10,
+        batchSize: 100,
+        metadataFileName: '_query-meta.json',
+        validation: {
+            maxQueryDepth: 5,
+            maxArraySize: 1000,
+            allowedDateFormats: ['ISO8601', 'YYYY-MM-DD', 'MM/DD/YYYY'],
+        },
+    },
+    // API endpoints
+    apis: {
+        stacks: '/stacks/',
+        locales: '/locales/',
+        environments: '/environments/',
+        content_types: '/content_types/',
+        global_fields: '/global_fields/',
+        extensions: '/extensions/',
+        taxonomies: '/taxonomies/',
+        entries: '/entries/',
+        assets: '/assets/',
+    },
+    // Performance settings
+    fetchConcurrency: 5,
+    writeConcurrency: 5,
+    maxCTReferenceDepth: 20,
+    // Optional settings
+};
+exports.default = config;

package/lib/config/index.ts

@@ -0,0 +1,59 @@
+import { DefaultConfig } from '../types';
+
+const config: DefaultConfig = {
+  contentVersion: 2,
+  host: 'https://api.contentstack.io/v3',
+
+  // Query-based export module configuration
+  modules: {
+    // Always export - general modules
+    general: ['stack', 'locales', 'environments'],
+    // Query target modules
+    queryable: ['content-types'],
+    dependent: ['global-fields', 'extensions', 'marketplace-apps', 'taxonomies', 'personalize'],
+    // Content modules
+    content: ['entries', 'assets'],
+    // Export order based on dependencies
+    exportOrder: [
+      'stack',
+      'locales',
+      'environments',
+      'content-types',
+      'global-fields',
+      'extensions',
+      'taxonomies',
+      'entries',
+      'assets',
+    ],
+  },
+  // Query-specific settings
+  queryConfig: {
+    maxRecursionDepth: 10,
+    batchSize: 100,
+    metadataFileName: '_query-meta.json',
+    validation: {
+      maxQueryDepth: 5,
+      maxArraySize: 1000,
+      allowedDateFormats: ['ISO8601', 'YYYY-MM-DD', 'MM/DD/YYYY'],
+    },
+  },
+  // API endpoints
+  apis: {
+    stacks: '/stacks/',
+    locales: '/locales/',
+    environments: '/environments/',
+    content_types: '/content_types/',
+    global_fields: '/global_fields/',
+    extensions: '/extensions/',
+    taxonomies: '/taxonomies/',
+    entries: '/entries/',
+    assets: '/assets/',
+  },
+  // Performance settings
+  fetchConcurrency: 5,
+  writeConcurrency: 5,
+  maxCTReferenceDepth: 20,
+  // Optional settings
+};
+
+export default config;

package/lib/core/module-exporter.d.ts

@@ -0,0 +1,11 @@
+import { QueryExportConfig, Modules, ExportOptions } from '../types';
+export declare class ModuleExporter {
+    private exportQueryConfig;
+    private exportedModules;
+    constructor(exportQueryConfig: QueryExportConfig);
+    exportModule(moduleName: Modules, options?: ExportOptions): Promise<void>;
+    /**
+     * Build export command arguments based on module and options
+     */
+    private buildExportCommand;
+}

package/lib/core/module-exporter.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModuleExporter = void 0;
+const tslib_1 = require("tslib");
+const cli_utilities_1 = require("@contentstack/cli-utilities");
+const cli_cm_export_1 = tslib_1.__importDefault(require("@contentstack/cli-cm-export"));
+const logger_1 = require("../utils/logger");
+class ModuleExporter {
+    constructor(exportQueryConfig) {
+        this.exportedModules = [];
+        this.exportQueryConfig = exportQueryConfig;
+    }
+    async exportModule(moduleName, options = {}) {
+        try {
+            (0, logger_1.log)(this.exportQueryConfig, `Exporting module: ${moduleName}`, 'info');
+            // Build command arguments
+            const cmd = this.buildExportCommand(moduleName, options);
+            (0, logger_1.log)(this.exportQueryConfig, `Running export command: ${cmd.join(' ')}`, 'debug');
+            // Configurable delay
+            const delay = this.exportQueryConfig.exportDelayMs || 2000;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            // Create export command instance
+            await cli_cm_export_1.default.run(cmd);
+            // Read the exported data
+            // const data = await this.readExportedData(moduleName, options);
+            if (!this.exportedModules.includes(moduleName)) {
+                this.exportedModules.push(moduleName);
+            }
+            // success message
+            (0, logger_1.log)(this.exportQueryConfig, `Successfully exported ${moduleName}`, 'success');
+        }
+        catch (error) {
+            (0, logger_1.log)(this.exportQueryConfig, `Failed to export ${moduleName}: ${(0, cli_utilities_1.formatError)(error)}`, 'error');
+            throw error;
+        }
+    }
+    /**
+     * Build export command arguments based on module and options
+     */
+    buildExportCommand(moduleName, options) {
+        const cmd = [];
+        // Stack API key (required)
+        cmd.push('-k', this.exportQueryConfig.stackApiKey);
+        // Directory
+        const directory = options.directory || this.exportQueryConfig.exportDir;
+        cmd.push('-d', directory);
+        // Module
+        cmd.push('--module', moduleName);
+        // Alias (management token)
+        if (options.alias) {
+            cmd.push('-a', options.alias);
+        }
+        // Branch
+        if (options.branch || this.exportQueryConfig.branchName) {
+            cmd.push('--branch', options.branch || this.exportQueryConfig.branchName);
+        }
+        // Query (if provided)
+        if (options.query) {
+            cmd.push('--query', JSON.stringify(options.query));
+        }
+        // Secured assets
+        if (options.securedAssets || this.exportQueryConfig.securedAssets) {
+            cmd.push('--secured-assets');
+        }
+        // External config file
+        const externalConfigPath = options.configPath || this.exportQueryConfig.externalConfigPath;
+        if (externalConfigPath) {
+            cmd.push('--config', externalConfigPath);
+        }
+        // Auto confirm
+        cmd.push('-y');
+        return cmd;
+    }
+}
+exports.ModuleExporter = ModuleExporter;

package/lib/core/query-executor.d.ts

@@ -0,0 +1,17 @@
+import { ContentstackClient } from '@contentstack/cli-utilities';
+import { QueryExportConfig } from '../types';
+export declare class QueryExporter {
+    private stackAPIClient;
+    private exportQueryConfig;
+    private queryParser;
+    private moduleExporter;
+    constructor(managementAPIClient: ContentstackClient, exportQueryConfig: QueryExportConfig);
+    execute(): Promise<void>;
+    private exportGeneralModules;
+    private exportQueriedModule;
+    private exportReferencedContentTypes;
+    private exportDependentModules;
+    private exportContentModules;
+    private exportEntries;
+    private exportReferencedAssets;
+}