Merge pull request #66 from contentstack/staging

DX | 06-04-2026 | Release

Author: harshitha-cstk

.cursor/rules/README.md

@@ -0,0 +1,25 @@
+# Cursor rules
+
+Rules give context-aware guidance for this **Contentstack query-export CLI plugin** (`@contentstack/cli-cm-export-query`).
+
+## Rules overview
+
+| File | Purpose |
+|------|---------|
+| `dev-workflow.md` | TDD, structure, validation commands (always applied) |
+| `typescript.mdc` | TypeScript style and naming |
+| `contentstack-cli.mdc` | Contentstack CLI utilities, export flow, API habits |
+| `testing.mdc` | Mocha/Chai/Sinon and coverage |
+| `oclif-commands.mdc` | Command flag and delegation patterns |
+
+## How they attach
+
+- **Always**: `dev-workflow.md`
+- **TypeScript**: `typescript.mdc`
+- **Commands** (`src/commands/**`): `oclif-commands.mdc` + `typescript.mdc`
+- **Core / utils** (`src/core/**`, `src/utils/**`, `src/types/**`): `contentstack-cli.mdc` + `typescript.mdc`
+- **Tests** (`test/**`): `testing.mdc` + domain rules as needed
+
+## Chat shortcuts
+
+You can `@`-mention rule topics (for example TypeScript or testing) depending on how your workspace maps rule names.

.cursor/rules/contentstack-cli.mdc

@@ -0,0 +1,39 @@
+---
+description: "Contentstack query-export plugin: CLI utilities, export flow, and API habits"
+globs:
+  - "**/core/**/*.ts"
+  - "**/utils/**/*.ts"
+  - "**/types/**/*.ts"
+  - "**/config/**/*.ts"
+alwaysApply: false
+---
+
+# Contentstack CLI — query export plugin
+
+This package is **`@contentstack/cli-cm-export-query`**. Business logic lives in **`src/core/`** and **`src/utils/`** (there is no `src/services/` layer).
+
+## Stack and auth
+
+- Use **`@contentstack/cli-utilities`**: `managementSDKClient`, `flags`, `log`, `handleAndLogError`, `sanitizePath`, etc.
+- Resolve management tokens and stack context the same way as **`src/commands/cm/stacks/export-query.ts`** (alias, `--stack-api-key`, config file).
+- **Never** log or write secrets (API keys, management tokens) to export artifacts or casual log lines.
+
+## Export orchestration
+
+- **`QueryExporter`** (`src/core/query-executor.ts`) drives the flow: parse query → export modules → resolve dependencies / references / assets per flags.
+- **`ModuleExporter`** (`src/core/module-exporter.ts`) handles module-level export alongside **`@contentstack/cli-cm-export`** behavior.
+- Prefer extending **utils** and **core** classes rather than putting heavy logic in the command’s `run()`.
+
+## Queries
+
+- Queries are JSON (string or path to a JSON file); see **`QueryParser`** (`src/utils/query-parser.ts`) and command examples in `export-query.ts`.
+- Respect flags: **`skip-references`**, **`skip-dependencies`**, **`secured-assets`**, branch / branch-alias.
+
+## API usage
+
+- Respect Contentstack **rate limits**; use backoff for **429** and transient failures when adding new API calls.
+- Mock **all** HTTP/SDK usage in tests (sinon); no live stack calls in unit tests.
+
+## Not in this plugin
+
+- Other CLI repos may use **`BaseBulkCommand`** or **`bulk-operation/*.json`** logs. This plugin uses **`Command`** from **`@contentstack/cli-command`** and the **`QueryExporter`** pipeline only.

.cursor/rules/dev-workflow.md

@@ -0,0 +1,70 @@
+---
+description: "Core development workflow and TDD patterns - always applied"
+globs: ["**/*.ts", "**/*.js", "**/*.json"]
+alwaysApply: true
+---
+
+# Development Workflow
+
+## Quick Reference
+
+For detailed patterns, see project skills:
+
+- `@skills/testing` — Testing and TDD
+- `@skills/contentstack-cli` — Export command, utilities, and API usage
+- `@skills/framework` — Config, logging, and shared patterns
+- `@skills/code-review` — PR review checklist
+
+## TDD workflow (recommended)
+
+For **new behavior or bug fixes**, prefer working in three steps:
+
+1. **RED** → Write a failing test (or extend an existing one)
+2. **GREEN** → Minimal code to pass
+3. **REFACTOR** → Clean up while tests stay green
+
+**Exceptions (no new test required when behavior is unchanged):** pure refactors, documentation-only edits, comments/config-only tweaks, trivial typos.
+
+## Guidelines
+
+- **Coverage:** aim high; **~80%** (lines/branches/functions) is an **aspirational target**, not a CI gate in this repo
+- **TypeScript** — explicit return types where practical; avoid `any`
+- **NO test.skip or .only** in commits
+
+## File structure (this repo)
+
+- **Command**: `src/commands/cm/stacks/export-query.ts`
+- **Core**: `src/core/` — `QueryExporter`, `ModuleExporter`
+- **Utils**: `src/utils/` — query parsing, config, dependencies, assets, branches, file helpers
+- **Types**: `src/types/index.ts`
+- **Config**: `src/config/` (copied to `lib/` on build)
+- **Messages**: `messages/index.json`
+- **Tests**: `test/unit/*.test.ts` (grouped by module under test)
+
+## Naming conventions
+
+- Files: `kebab-case.ts` / `kebab-case.test.ts`
+- Classes: `PascalCase`
+- Functions: `camelCase`
+- Tests: `should [behavior] when [condition]`
+
+## Before coding
+
+1. Read relevant `@skills/*` references
+2. For behavior changes: prefer a failing test first, then implement
+3. Refactor and run tests
+
+## Validation commands
+
+- `npm run lint` — ESLint on `src/**/*.ts`
+- `npm run test` — All tests with nyc
+- `npm run test:report` — LCOV coverage report
+- `npm run test:unit` — Unit tests only
+- `npm run format` — ESLint `--fix`
+
+## Commit suggestions
+
+- Conventional commits are helpful but optional: `feat(scope): description`
+- Tests passing before merge
+- No lint errors
+- No stray `console.log` / `debugger`

.cursor/rules/oclif-commands.mdc

@@ -0,0 +1,45 @@
+---
+description: "OCLIF / Contentstack command patterns for this plugin"
+globs: ["**/commands/**/*.ts"]
+alwaysApply: false
+---
+
+# Command standards (`export-query`)
+
+This plugin uses **`Command`** from **`@contentstack/cli-command`** and **`flags` / `FlagInput`** from **`@contentstack/cli-utilities`** (not `@oclif/core` `Flags` directly). Follow **`src/commands/cm/stacks/export-query.ts`** as the source of truth.
+
+## Structure
+
+```typescript
+import { Command } from '@contentstack/cli-command';
+import { flags, FlagInput, managementSDKClient, log, handleAndLogError } from '@contentstack/cli-utilities';
+import { QueryExporter } from '../../../core/query-executor';
+
+export default class ExportQueryCommand extends Command {
+  static description = 'Export content from a stack using query-based filtering';
+  static examples = ['csdx cm:stacks:export-query --query \'{"modules":{...}}\''];
+
+  static flags: FlagInput = {
+    query: flags.string({ required: true, description: 'Query as JSON string or file path' }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(ExportQueryCommand);
+    // Build config via src/utils (e.g. setupQueryExportConfig), then:
+    const exporter = new QueryExporter(client, exportQueryConfig);
+    await exporter.execute();
+  }
+}
+```
+
+## Practices
+
+- **Validate early**: required `query`; ensure stack auth is present before calling the API.
+- **Delegate**: keep parsing, paths, and SDK wiring out of `QueryExporter` where helpers already exist under **`src/utils/`**.
+- **User feedback**: prefer **`log`** from **`@contentstack/cli-utilities`** with export context.
+- **Errors**: use **`handleAndLogError`** and/or command error UX consistent with other Contentstack CLI plugins.
+
+## Flags
+
+- Define flags with **`flags.string`**, **`flags.boolean`**, etc., and **`FlagInput`** typing for the static `flags` object.
+- Use **`exclusive`** on mutually exclusive options (see branch vs branch-alias in `export-query.ts`).

.cursor/rules/testing.mdc

@@ -0,0 +1,66 @@
+---
+description: "Testing patterns and TDD workflow"
+globs: ["**/__tests__/**/*.ts", "**/*.spec.ts", "**/*.test.ts"]
+alwaysApply: true
+---
+
+# Testing Standards
+
+## TDD workflow
+1. For behavior changes, prefer a failing test first
+2. Minimal code to pass
+3. Refactor while keeping tests green
+
+Pure refactors and docs-only changes may skip new tests when behavior is unchanged.
+
+## Coverage
+- **~80%** (lines, branches, functions) is an **aspirational** goal, not enforced as a hard gate here
+- Test both success and failure paths
+- Mock all external dependencies
+
+## Test Patterns
+```typescript
+// ✅ GOOD - Simple test structure
+describe('[ComponentName]', () => {
+  beforeEach(() => {
+    // Setup mocks and test data
+    sinon.stub(ExternalService.prototype, 'method').resolves(mockData);
+  });
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  it('should [expected behavior] when [condition]', () => {
+    // Arrange
+    const input = { /* test data */ };
+    
+    // Act
+    const result = component.method(input);
+    
+    // Assert
+    expect(result).to.equal(expectedOutput);
+  });
+});
+```
+
+## Mocking Standards
+- Use sinon for API response mocking
+- Never make real API calls in tests
+- Mock at module boundaries (SDK clients, `fsUtil`, etc.), not irrelevant internals
+
+## Layout
+
+- Unit tests live under **`test/unit/**/*.test.ts`** (Mocha).
+
+## Common mock patterns
+```typescript
+// Mock external API
+sinon.stub(HttpClient.prototype, 'request').resolves(mockResponse);
+
+// Mock file operations
+sinon.stub(fs, 'readFile').resolves(mockFileContent);
+
+// Mock rate limiter
+sinon.stub(RateLimiter.prototype, 'wait').resolves();
+```

.cursor/rules/typescript.mdc

@@ -0,0 +1,49 @@
+---
+description: "TypeScript strict mode standards and naming conventions"
+globs: ["**/*.ts", "**/*.tsx"]
+alwaysApply: false
+---
+
+# TypeScript Standards
+
+## Strict Mode Requirements
+- Explicit return types for all functions
+- No `any` type usage
+- Strict null checks enabled
+- No unused variables or imports
+
+## Naming Conventions
+- **Files**: kebab-case.ts
+- **Classes**: PascalCase
+- **Functions/Variables**: camelCase
+- **Constants**: SCREAMING_SNAKE_CASE
+- **Interfaces**: PascalCase (no I prefix)
+- **Types**: PascalCase
+
+## Code Examples
+```typescript
+// ✅ GOOD - Explicit types and proper naming
+export class UserService {
+  async fetchUser(userId: string): Promise<User> {
+    const user = await this.client.getUser(userId);
+    return user;
+  }
+}
+
+// ❌ BAD - Implicit any, poor naming
+export class userservice {
+  async fetchUser(id) {
+    return await this.client.getUser(id);
+  }
+}
+```
+
+## Import Organization
+1. Node.js built-ins
+2. External libraries
+3. Internal modules (relative imports last)
+
+## Error Handling
+- Use custom error classes
+- Include error context and cause
+- Never swallow errors silently

.cursor/skills/SKILL.md

@@ -0,0 +1,5 @@
+# Project skills
+
+Agent-oriented skills for **cli-query-export** (`@contentstack/cli-cm-export-query`) live under **[`skills/`](../../skills/)**.
+
+Reference in chat with `@skills/<name>` (for example `@skills/contentstack-cli`, `@skills/testing`).

.gitignore

@@ -17,3 +17,4 @@ contents/
 logs/
 oclif.manifest.json
 talisman_output.log
+snyk_output.log

.nycrc.json

@@ -1,5 +1,5 @@
 {
-    "inlcude": [
+    "include": [
         "lib/**/*.js"
     ]
 }

.talismanrc

@@ -1,10 +1,14 @@
 fileignoreconfig:
-  - filename: src/core/query-executor.ts
-    checksum: 3d0b5cf07f5a87256f132f85a5556d193ce5a1fa6d92df2c7c50514071d592b7
+  - filename: skills/code-review/SKILL.md
+    checksum: 8c0c5c1a18ba08aa0c048d261f1ca81c152def23745fd74b531b75a23a5ac969
+  - filename: skills/framework/SKILL.md
+    checksum: 5674849276e2087f6361decb2c7e427f451ec7799538fa2eb697b0a8b7b92f44
+  - filename: .cursor/rules/contentstack-cli.mdc
+    checksum: 11bf8883f584b900ce1cde336057391717b47eb5a304cb46c5660bb3185cef2f
+  - filename: skills/code-review/references/code-review-checklist.md
+    checksum: 6e65ad06469083ed0196edaf8bd2d4478800493b32535be7c98e436082fba44a
+  - filename: skills/framework/references/framework-patterns.md
+    checksum: cae3858eea36c1f716ebe4a9679fc3d4eee628cb244cf4fc0a6eccbd8cecb36d
   - filename: package-lock.json
-    checksum: 216c297102d8f30ebed4a942e24d27f94f714ef9e32a932474e85127fb7cc435
-  - filename: src/types/index.ts
-    checksum: 8d3021c2690dbceeb5a97e449262834b8177f2a4a674fe13ac33d71b890ab8fd
-  - filename: src/utils/logger.ts
-    checksum: c5baa97b996aaeaa0eb2c4d40d71bd67047fc85281449278f3d9058433dcb4ab
+    checksum: 9b73c1e977f09964843bd5f7529ca8decb7e8b5ab462a4e9ab167ff2a05df53f
 version: '1.0'