contentstack · shafeeqd959 · Mar 25, 2026
@@ -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
@@ -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
@@ -0,0 +1,107 @@
+# Cursor Rules
+
+Context-aware rules that load automatically based on the files you're editing, optimized for this Contentstack CLI plugins monorepo.
+
+## Rule Files
+
+| File | Scope | Always Applied | Purpose |
+|------|-------|----------------|---------|
+| `dev-workflow.md` | `**/*.ts`, `**/*.js`, `**/*.json` | Yes | Monorepo TDD workflow, pnpm workspace patterns |
+| `typescript.mdc` | `**/*.ts`, `**/*.tsx` | No | TypeScript config variations, naming conventions |
+| `testing.mdc` | `**/test/**/*.ts`, `**/test/**/*.js`, `**/*.test.ts`, `**/*.spec.ts` | Yes | Mocha, Chai, Sinon patterns, nyc coverage |
+| `oclif-commands.mdc` | `**/commands/**/*.ts` | No | OCLIF patterns, BaseCommand classes, CLI validation |
+| `contentstack-cli.mdc` | `**/import/**/*.ts`, `**/export/**/*.ts`, `**/modules/**/*.ts`, `**/services/**/*.ts`, `**/utils/**/*.ts` | No | API integration, rate limiting, batch processing |
+
+## Commands
+
+| File | Trigger | Purpose |
+|------|---------|---------|
+| `execute-tests.md` | `/execute-tests` | Run tests by scope, package, or module with monorepo awareness |
+| `code-review.md` | `/code-review` | Automated PR review with Contentstack CLI specific checklist |
+
+## Loading Behaviour
+
+### File Type Mapping
+- **TypeScript files** → `typescript.mdc` + `dev-workflow.md`
+- **Command files** (`packages/*/src/commands/**/*.ts`) → `oclif-commands.mdc` + `typescript.mdc` + `dev-workflow.md`
+- **Import/Export modules** (`packages/*/src/{import,export,modules}/**/*.ts`) → `contentstack-cli.mdc` + `typescript.mdc` + `dev-workflow.md`
+- **Service files** (`packages/*/src/services/**/*.ts`) → `contentstack-cli.mdc` + `typescript.mdc` + `dev-workflow.md`
+- **Test files** (`packages/*/test/**/*.{ts,js}`) → `testing.mdc` + relevant domain rules + `dev-workflow.md`
+- **Utility files** (`packages/*/src/utils/**/*.ts`) → `contentstack-cli.mdc` + `typescript.mdc` + `dev-workflow.md`
+
+### Package-Specific Loading
+- **Plugin packages** (with `oclif.commands`) → Full command and API rules
+- **Library packages** (e.g., variants) → TypeScript and utility rules only
+- **Bootstrap package** (JavaScript tests) → Adjusted testing rules
+
+## Repository-Specific Features
+
+### Monorepo Awareness
+- **11 plugin packages** under `packages/`
+- **pnpm workspaces** configuration
+- **Shared utilities**: `@contentstack/cli-command`, `@contentstack/cli-utilities`
+- **Build artifacts**: `lib/` directories (excluded from rules)
+
+### Actual Patterns Detected
+- **Testing**: Mocha + Chai + Sinon (not Jest)
+- **TypeScript**: Mixed strict mode adoption
+- **Commands**: Extend `@contentstack/cli-command` (not `@oclif/core`)
+- **Rate limiting**: Multiple mechanisms (batch spacing, 429 retry, pagination throttle)
+- **Coverage**: nyc with inconsistent enforcement
+
+## Performance Benefits
+
+- **75-85% token reduction** vs monolithic `.cursorrules`
+- **Context-aware loading** - only relevant rules activate based on actual file patterns
+- **Precise glob patterns** - avoid loading rules for build artifacts or irrelevant files
+- **Skills integration** - rules provide quick context, skills provide comprehensive patterns
+
+## Design Principles
+
+### Validated Against Codebase
+- Rules reflect **actual patterns** found in repository analysis
+- Glob patterns match **real file structure** (not theoretical)
+- Examples use **actual dependencies** and APIs
+- Coverage targets reflect **current enforcement** (aspirational vs actual)
+
+### Lightweight and Focused
+- Each rule has **single responsibility**
+- Detailed patterns referenced via **skills system**
+- `alwaysApply: true` only for truly universal patterns
+- Package-specific variations acknowledged
+
+## Validation Checklist
+
+### Rule Loading Tests (Repository-Specific)
+- ✅ **Command files** (`packages/*/src/commands/**/*.ts`) → `oclif-commands.mdc` + `typescript.mdc` + `dev-workflow.md`
+- ✅ **Import modules** (`packages/contentstack-import/src/import/**/*.ts`) → `contentstack-cli.mdc` + `typescript.mdc` + `dev-workflow.md`
+- ✅ **Export modules** (`packages/contentstack-export/src/export/**/*.ts`) → `contentstack-cli.mdc` + `typescript.mdc` + `dev-workflow.md`
+- ✅ **Test files** (`packages/*/test/unit/**/*.test.ts`) → `testing.mdc` + `dev-workflow.md`
+- ✅ **Bootstrap tests** (`packages/contentstack-bootstrap/test/**/*.test.js`) → `testing.mdc` (JS-aware) + `dev-workflow.md`
+- ✅ **Service files** (`packages/*/src/services/**/*.ts`) → `contentstack-cli.mdc` + `typescript.mdc` + `dev-workflow.md`
+
+### Manual Verification
+1. Open files from different packages in Cursor
+2. Check active rules shown in chat interface
+3. Verify correct rule combinations load based on file location
+4. Test manual rule invocation: `@contentstack-cli show me rate limiting patterns`
+5. Confirm no rules load for `lib/` build artifacts
+
+### Performance Monitoring
+- **Before**: Monolithic rules loaded for all files
+- **After**: Context-specific rules based on actual file patterns
+- **Expected reduction**: 75-85% in token usage
+- **Validation**: Rules load only when relevant to current file context
+
+## Maintenance Notes
+
+### Regular Updates Needed
+- **Glob patterns** - Update when package structure changes
+- **TypeScript config** - Align with actual tsconfig.json variations
+- **Coverage targets** - Sync with actual nyc configuration
+- **Dependencies** - Update when shared utilities change
+
+### Known Issues to Monitor
+- **Coverage typo**: Several `.nycrc.json` files have `"inlcude"` instead of `"include"`
+- **Strict mode inconsistency**: Packages have different TypeScript strictness levels
+- **Test patterns**: Bootstrap uses `.test.js` while others use `.test.ts`