Merge branch 'v2-dev' into feat/DX-5418

Author: naman-contentstack

.cursor/commands/code-review.md

@@ -0,0 +1,122 @@
+---
+name: code-review
+description: Automated PR review using comprehensive checklist tailored for Contentstack CLI plugins
+---
+
+# Code Review Command
+
+## Usage Patterns
+
+### Scope-Based Reviews
+- `/code-review` - Review all current changes with full checklist
+- `/code-review --scope typescript` - Focus on TypeScript configuration and patterns
+- `/code-review --scope testing` - Focus on Mocha/Chai/Sinon test patterns
+- `/code-review --scope contentstack` - Focus on API integration and CLI patterns
+- `/code-review --scope oclif` - Focus on command structure and OCLIF patterns
+
+### Severity Filtering
+- `/code-review --severity critical` - Show only critical issues (security, breaking changes)
+- `/code-review --severity high` - Show high and critical issues
+- `/code-review --severity all` - Show all issues including suggestions
+
+### Package-Aware Reviews
+- `/code-review --package contentstack-import` - Review changes in specific package
+- `/code-review --package-type plugin` - Review plugin packages only
+- `/code-review --package-type library` - Review library packages (e.g., variants)
+
+### File Type Focus
+- `/code-review --files commands` - Review command files only
+- `/code-review --files tests` - Review test files only
+- `/code-review --files modules` - Review import/export modules
+
+## Comprehensive Review Checklist
+
+### Monorepo Structure Compliance
+- **Package organization**: Proper placement in `packages/` structure
+- **pnpm workspace**: Correct `package.json` workspace configuration
+- **Build artifacts**: No `lib/` directories committed to version control
+- **Dependencies**: Proper use of shared utilities (`@contentstack/cli-command`, `@contentstack/cli-utilities`)
+
+### TypeScript Standards (Repository-Specific)
+- **Configuration compliance**: Follows package-specific TypeScript config
+- **Naming conventions**: kebab-case files, PascalCase classes, camelCase functions
+- **Type safety**: Appropriate use of strict mode vs relaxed settings per package
+- **Import patterns**: ES modules with proper default/named exports
+- **Migration strategy**: Proper use of `@ts-ignore` during gradual migration
+
+### OCLIF Command Patterns (Actual Implementation)
+- **Base class usage**: Extends `@contentstack/cli-command` (not `@oclif/core`)
+- **Command structure**: Proper `static description`, `examples`, `flags`
+- **Topic organization**: Uses `cm` topic structure (`cm:stacks:import`)
+- **Error handling**: Uses `handleAndLogError` from utilities
+- **Validation**: Early flag validation and user-friendly error messages
+- **Service delegation**: Commands orchestrate, services implement business logic
+
+### Testing Excellence (Mocha/Chai/Sinon Stack)
+- **Framework compliance**: Uses Mocha + Chai + Sinon (not Jest)
+- **File patterns**: Follows `*.test.ts` naming (or `*.test.js` for bootstrap)
+- **Directory structure**: Proper placement in `test/unit/`, `test/lib/`, etc.
+- **Mock patterns**: Proper Sinon stubbing of SDK methods
+- **Coverage configuration**: Correct nyc setup (watch for `inlcude` typo)
+- **Test isolation**: Proper `beforeEach`/`afterEach` with `sinon.restore()`
+- **No real API calls**: All external dependencies properly mocked
+
+### Contentstack API Integration (Real Patterns)
+- **SDK usage**: Proper `managementSDKClient` and fluent API chaining
+- **Authentication**: Correct `configHandler` and token alias handling
+- **Rate limiting compliance**: 
+  - Batch spacing (minimum 1 second between batches)
+  - 429 retry handling with exponential backoff
+  - Pagination throttling for variants
+- **Error handling**: Proper `handleAndLogError` usage and user-friendly messages
+- **Configuration**: Proper regional endpoint and management token handling
+
+### Import/Export Module Architecture
+- **BaseClass extension**: Proper inheritance from import/export BaseClass
+- **Batch processing**: Correct use of `makeConcurrentCall` and `logMsgAndWaitIfRequired`
+- **Module organization**: Proper entity-specific module structure
+- **Configuration handling**: Proper `ModuleClassParams` usage
+- **Progress feedback**: Appropriate user feedback during long operations
+
+### Security and Best Practices
+- **Token security**: No API keys or tokens logged or committed
+- **Input validation**: Proper validation of user inputs and flags
+- **Error exposure**: No sensitive information in error messages
+- **File permissions**: Proper handling of file system operations
+- **Process management**: Appropriate use of `process.exit(1)` for critical failures
+
+### Performance Considerations
+- **Concurrent processing**: Proper use of `Promise.allSettled` for batch operations
+- **Memory management**: Appropriate handling of large datasets
+- **Rate limiting**: Compliance with Contentstack API limits (10 req/sec)
+- **Batch sizing**: Appropriate batch sizes for different operations
+- **Progress tracking**: Efficient progress reporting without performance impact
+
+### Package-Specific Patterns
+- **Plugin vs Library**: Correct `oclif.commands` configuration for plugin packages
+- **Command compilation**: Proper build pipeline (`tsc` → `lib/commands` → `oclif manifest`)
+- **Dependency management**: Correct use of shared vs package-specific dependencies
+- **Test variations**: Handles different test patterns per package (JS vs TS, different structures)
+
+## Review Execution
+
+### Automated Checks
+1. **Lint compliance**: ESLint and TypeScript compiler checks
+2. **Test coverage**: nyc coverage thresholds (where enforced)
+3. **Build verification**: Successful compilation to `lib/` directories
+4. **Dependency audit**: No security vulnerabilities in dependencies
+
+### Manual Review Focus Areas
+1. **API integration patterns**: Verify proper SDK usage and error handling
+2. **Rate limiting implementation**: Check for proper throttling mechanisms
+3. **Test quality**: Verify comprehensive mocking and error scenario coverage
+4. **Command usability**: Ensure clear help text and examples
+5. **Monorepo consistency**: Check for consistent patterns across packages
+
+### Common Issues to Flag
+- **Coverage config typos**: `"inlcude"` instead of `"include"` in `.nycrc.json`
+- **Inconsistent TypeScript**: Mixed strict mode usage without migration plan
+- **Real API calls in tests**: Any unmocked external dependencies
+- **Missing rate limiting**: API calls without proper throttling
+- **Build artifacts committed**: Any `lib/` directories in version control
+- **Inconsistent error handling**: Not using utilities error handling patterns

.cursor/commands/execute-tests.md

@@ -0,0 +1,107 @@
+---
+name: execute-tests
+description: Run tests by scope, file, or module with intelligent filtering for this pnpm monorepo
+---
+
+# Execute Tests Command
+
+## Usage Patterns
+
+### Monorepo-Wide Testing
+- `/execute-tests` - Run all tests across all packages
+- `/execute-tests --coverage` - Run all tests with nyc coverage report
+- `/execute-tests --parallel` - Run package tests in parallel using pnpm
+
+### Package-Specific Testing
+- `/execute-tests packages/contentstack-audit/` - Run tests for specific package
+- `/execute-tests packages/contentstack-import/` - Run import package tests
+- `/execute-tests packages/contentstack-export/` - Run export package tests
+- `/execute-tests contentstack-migration` - Run tests by package name (shorthand)
+
+### Scope-Based Testing
+- `/execute-tests unit` - Run unit tests only (`test/unit/**/*.test.ts`)
+- `/execute-tests commands` - Run command tests (`test/commands/**/*.test.ts`)
+- `/execute-tests services` - Run service layer tests
+- `/execute-tests modules` - Run import/export module tests
+
+### File Pattern Testing
+- `/execute-tests *.test.ts` - Run all TypeScript tests
+- `/execute-tests *.test.js` - Run JavaScript tests (bootstrap package)
+- `/execute-tests test/unit/services/` - Run tests for specific directory
+
+### Watch and Development
+- `/execute-tests --watch` - Run tests in watch mode with file monitoring
+- `/execute-tests --debug` - Run tests with debug output enabled
+- `/execute-tests --bail` - Stop on first test failure
+
+## Intelligent Filtering
+
+### Repository-Aware Detection
+- **Test patterns**: Primarily `*.test.ts`, some `*.test.js` (bootstrap), rare `*.spec.ts`
+- **Directory structures**: `test/unit/`, `test/lib/`, `test/seed/`, `test/commands/`
+- **Package variations**: Different test layouts per package
+- **Build exclusion**: Ignores `lib/` directories (compiled artifacts)
+
+### Monorepo Integration
+- **pnpm workspace support**: Uses `pnpm -r --filter` for package targeting
+- **Dependency awareness**: Understands package interdependencies
+- **Parallel execution**: Leverages pnpm's parallel capabilities
+- **Selective testing**: Can target specific packages or file patterns
+
+### Framework Detection
+- **Mocha configuration**: Respects `.mocharc.json` files per package
+- **TypeScript compilation**: Handles `pretest: tsc -p test` scripts
+- **Coverage integration**: Works with nyc configuration (`.nycrc.json`)
+- **Test helpers**: Detects and includes test initialization files
+
+## Execution Examples
+
+### Common Workflows
+```bash
+# Run all tests with coverage
+/execute-tests --coverage
+
+# Test specific package during development
+/execute-tests packages/contentstack-import/ --watch
+
+# Run only unit tests across all packages
+/execute-tests unit
+
+# Test import/export modules specifically
+/execute-tests modules --coverage
+
+# Debug failing tests in audit package
+/execute-tests packages/contentstack-audit/ --debug --bail
+```
+
+### Package-Specific Commands Generated
+```bash
+# For contentstack-import package
+cd packages/contentstack-import && pnpm test
+
+# For all packages with coverage
+pnpm -r --filter './packages/*' run test:coverage
+
+# For specific test file
+cd packages/contentstack-export && npx mocha test/unit/export/modules/stack.test.ts
+```
+
+## Configuration Awareness
+
+### Mocha Integration
+- Respects individual package `.mocharc.json` configurations
+- Handles TypeScript compilation via `ts-node/register`
+- Supports test helpers and initialization files
+- Manages timeout settings per package
+
+### Coverage Integration
+- Uses nyc for coverage reporting
+- Respects `.nycrc.json` configurations (with typo detection)
+- Generates HTML, text, and lcov reports
+- Handles TypeScript source mapping
+
+### pnpm Workspace Features
+- Leverages workspace dependency resolution
+- Supports filtered execution by package patterns
+- Enables parallel test execution across packages
+- Respects package-specific scripts and configurations

.cursor/rules/contentstack-cli.mdc

@@ -0,0 +1,165 @@
+---
+description: 'Contentstack CLI specific patterns and API integration'
+globs: ['**/import/**/*.ts', '**/export/**/*.ts', '**/modules/**/*.ts', '**/services/**/*.ts', '**/utils/**/*.ts']
+alwaysApply: false
+---
+
+# Contentstack CLI Standards
+
+## API Integration
+
+- Use `@contentstack/cli-utilities` for SDK factory: `managementSDKClient(config)`
+- Stack-scoped API access: `stackAPIClient.asset()`, `stackAPIClient.extension()`
+- Fluent SDK chaining: `stack.contentType().entry().query().find()`
+- Custom HTTP for variants: `apiClient.put/get` with path strings
+
+## Authentication
+
+- Use `@contentstack/cli-utilities` for token management
+- Management token alias: `configHandler.get('tokens.<alias>')`
+- OAuth context: `configHandler.get('userUid'|'email'|'oauthOrgUid')`
+- Authentication check: `isAuthenticated()` before operations
+- Never log API keys or tokens in console or files
+
+## Rate Limiting - Multiple Mechanisms
+
+### Batch Spacing (Import/Export)
+```typescript
+// ✅ GOOD - Ensure minimum 1 second between batches
+async logMsgAndWaitIfRequired(processName: string, start: number): Promise<void> {
+  const end = Date.now();
+  const exeTime = end - start;
+  if (exeTime < 1000) await this.delay(1000 - exeTime);
+}
+```
+
+### 429 Retry (Branches)
+```typescript
+// ✅ GOOD - Handle 429 with retry
+export async function handleErrorMsg(err, retryCallback?: () => Promise<any>) {
+  if (err?.status === 429 || err?.response?.status === 429) {
+    await new Promise((resolve) => setTimeout(resolve, 1000)); // 1 sec delay
+    if (retryCallback) {
+      return retryCallback(); // Retry the request
+    }
+  }
+}
+```
+
+### Variant Pagination Throttle
+```typescript
+// ✅ GOOD - Throttle variant API requests
+if (requestTime < 1000) {
+  await delay(1000 - requestTime);
+}
+```
+
+## Error Handling
+
+### Standard Pattern
+```typescript
+// ✅ GOOD - Use handleAndLogError from utilities
+try {
+  const result = await this.stack.contentType().entry().fetch();
+} catch (error) {
+  handleAndLogError(error);
+  this.logAndPrintErrorDetails(error, config);
+}
+```
+
+### User-Friendly Errors
+```typescript
+// ✅ GOOD - User-facing error display
+cliux.print(errorMessage, { color: 'red' });
+// For critical failures
+process.exit(1);
+```
+
+## Module Architecture (Import/Export)
+
+### BaseClass Pattern
+```typescript
+// ✅ GOOD - Extend BaseClass for entity modules
+export class ContentTypes extends BaseClass {
+  constructor(params: ModuleClassParams) {
+    super(params);
+    // Entity-specific initialization
+  }
+
+  async import(): Promise<void> {
+    // Use this.makeConcurrentCall for batching
+    // Use this.logMsgAndWaitIfRequired for rate limiting
+  }
+}
+```
+
+### Batch Processing
+```typescript
+// ✅ GOOD - Concurrent batch processing
+const batches = chunk(apiContent, batchSize);
+for (const batch of batches) {
+  const start = Date.now();
+  await this.makeConcurrentCall(batch, this.processItem.bind(this));
+  await this.logMsgAndWaitIfRequired('Processing', start, batches.length, batchIndex);
+}
+```
+
+## Configuration Patterns
+
+### Import/Export Config
+```typescript
+// ✅ GOOD - Use configHandler for management tokens
+const config = {
+  host: configHandler.get('region.cma'),
+  managementTokenAlias: flags.alias,
+  stackApiKey: flags['stack-api-key'],
+  rateLimit: 5, // Default rate limit
+};
+```
+
+### Regional Configuration
+```typescript
+// ✅ GOOD - Handle regional endpoints
+const defaultConfig = {
+  host: 'https://api.contentstack.io',
+  cdn: 'https://cdn.contentstack.io',
+  // Regional developer hub URLs
+};
+```
+
+## Testing Patterns
+
+### SDK Mocking
+```typescript
+// ✅ GOOD - Mock stack client methods
+const mockStackClient = {
+  fetch: sinon.stub().resolves({ name: 'Test Stack', uid: 'stack-uid' }),
+  locale: sinon.stub().returns({
+    query: sinon.stub().returns({
+      find: sinon.stub().resolves({ items: [], count: 0 }),
+    }),
+  }),
+};
+```
+
+### Error Simulation
+```typescript
+// ✅ GOOD - Test error handling
+it('should handle 429 rate limit', async () => {
+  const error = { status: 429 };
+  mockClient.fetch.rejects(error);
+  // Test retry logic
+});
+```
+
+## Package-Specific Patterns
+
+### Plugin vs Library
+- **Plugin packages**: Have `oclif.commands` in package.json
+- **Library packages** (e.g., variants): No OCLIF commands, consumed by other packages
+
+### Monorepo Structure
+- Commands: `packages/*/src/commands/cm/**/*.ts`
+- Modules: `packages/*/src/{import,export,modules}/**/*.ts`
+- Utilities: `packages/*/src/utils/**/*.ts`
+- Built artifacts: `packages/*/lib/**` (not source)