Skip to content

Commit 2020416

Browse files
harshitha-cstkharshitha-cstk
committed
add cursor rules and skills
1 parent 80d35fe commit 2020416

11 files changed

Lines changed: 390 additions & 0 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Cursor rules — `@contentstack/datasync-mongodb-sdk`
2+
3+
This directory contains project-specific rules for AI assistants and developers. Rules use YAML frontmatter with `description`, and optionally `globs` and/or `alwaysApply`.
4+
5+
## How to use
6+
7+
- Rules with **`alwaysApply: true`** are intended to be loaded in relevant sessions automatically (depending on your Cursor settings).
8+
- Rules with **globs** apply when editing matching files.
9+
- For rules without `alwaysApply`, reference them explicitly when needed, e.g. **`@dev-workflow`**, **`@typescript`**, **`@datasync-mongodb`**, **`@testing`**, **`@code-review`** (use the file base name as shown in your Cursor UI).
10+
11+
## Rule index
12+
13+
| File | alwaysApply | Globs | When it applies |
14+
|------|-------------|-------|-----------------|
15+
| [dev-workflow.md](./dev-workflow.md) | No | *(none)* | Branching, scripts, PR/release expectations, security hooks |
16+
| [typescript.mdc](./typescript.mdc) | No | `src/**/*.ts`, `typings/**/*.ts` | TypeScript style, layout, TSLint alignment |
17+
| [datasync-mongodb.mdc](./datasync-mongodb.mdc) | No | `src/**/*.ts` | DataSync MongoDB SDK patterns (Stack, config, MongoDB — not CDA/CMA) |
18+
| [testing.mdc](./testing.mdc) | No | `test/**/*.ts`, `jest.config.js` | Jest tests, MongoDB integration tests, fixtures |
19+
| [code-review.mdc](./code-review.mdc) | **Yes** | *(global)* | PR checklist, terminology (DataSync vs CDA/CMA) |
20+
21+
## Related
22+
23+
- Root agent entry point: [../../AGENTS.md](../../AGENTS.md) (repository root)
24+
- Skills index: [../../skills/README.md](../../skills/README.md)

‎.cursor/rules/code-review.mdc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
description: PR review checklist for DataSync MongoDB SDK — API docs, compatibility, errors, tests, dependencies.
3+
alwaysApply: true
4+
---
5+
6+
# Code review checklist
7+
8+
## Product terminology
9+
10+
- This repo is the **DataSync MongoDB SDK** (local MongoDB over synced content). Do **not** describe changes as **CDA** (Delivery API) or **CMA** (Management API) unless the PR explicitly integrates separate HTTP clients — that is not the core of this package.
11+
12+
## Public API and docs
13+
14+
- New or changed **public** methods on `Contentstack` / `Stack` should have accurate **JSDoc** consistent with existing files.
15+
- README / example snippets should stay aligned with **`Stack.connect()`** and config shape in `src/config.ts`.
16+
17+
## Backward compatibility
18+
19+
- Avoid breaking changes to method names, config keys, and default behaviors without a semver-major plan.
20+
- Consider existing synced MongoDB document shapes and locale/collection naming.
21+
22+
## Errors and behavior
23+
24+
- Prefer consistent error messages via **`src/messages.ts`** where applicable.
25+
- Preserve null/undefined handling consistent with MongoDB driver and existing query chains.
26+
27+
## Dependencies and security
28+
29+
- New dependencies need justification (bundle size, maintenance, overlap with `lodash` / `mongodb` / `sift`).
30+
- Be mindful of **SCA** / supply-chain expectations (Snyk runs in husky pre-commit for many devs).
31+
32+
## Tests
33+
34+
- Meaningful **Jest** coverage for new branches; run **`npm test`** with MongoDB available.
35+
- Update or add fixtures under **`test/data/`** when adding query scenarios.
36+
37+
## Severity (optional)
38+
39+
- **Blocker:** Crashes, data corruption risk, security issues, broken public API contract.
40+
- **Major:** Incorrect results, missing tests for critical paths, breaking changes without version strategy.
41+
- **Minor:** Style, small refactors, doc typos.

‎.cursor/rules/datasync-mongodb.mdc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
description: DataSync MongoDB SDK — Stack API, MongoDB connection, config, and query patterns (not CDA/CMA HTTP APIs).
3+
globs:
4+
- src/**/*.ts
5+
alwaysApply: false
6+
---
7+
8+
# DataSync MongoDB SDK core
9+
10+
This package **queries MongoDB** that holds Contentstack **DataSync**-synced content. It does **not** call Contentstack **Delivery** or **Management** REST APIs.
11+
12+
## Mental model
13+
14+
- **`Contentstack.Stack(config, existingDb?)`** (`src/index.ts`) returns **`Stack`** (`src/stack.ts`).
15+
- Call **`Stack.connect()`** before queries (see README).
16+
- Config merges with defaults in **`src/config.ts`**: `contentStore.url`, `dbName`, collection names (`collection.asset` / `entry` / `schema`), `locale`, `limit`, `skip`, `referenceDepth`, `projections`, `options` (MongoClient options), indexes, etc.
17+
- Optional second constructor argument: an **existing MongoDB connection** for advanced hosting scenarios.
18+
19+
## Patterns in code
20+
21+
- Uses **`mongodb`** driver (`MongoClient`, `Db`, collections).
22+
- Uses **`sift`** for filter matching where applicable.
23+
- **Locales** and **content type** UIDs drive collection naming and queries; respect `validateConfig` / URI validation in **`src/util.ts`**.
24+
- Errors and user-facing strings live in **`src/messages.ts`**.
25+
26+
## Documentation alignment
27+
28+
- Product docs: [Contentstack DataSync](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync) and related DataSync / content-store-mongodb material — **not** CDA/CMA API reference docs for HTTP JSON payloads.
29+
30+
## Out of scope for this SDK
31+
32+
- Do not model this package as an HTTP SDK or assume `fetch`/axios patterns for Contentstack cloud APIs here.

‎.cursor/rules/dev-workflow.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
description: Branch workflow, npm scripts, PR expectations, version bumps, and local security hooks for this repo.
3+
---
4+
5+
# Development workflow
6+
7+
## Branches
8+
9+
Use your team’s Git conventions (feature branches off the main integration branch, PR-based merge). No branch naming scheme is enforced in this repository’s config files.
10+
11+
## Lint and tests
12+
13+
- **Compile:** `npm run compile` or `npm run build-ts` (clean + build).
14+
- **Tests:** `npm test` (Jest). Requires a **running MongoDB** reachable at the URL in stack config (defaults to `mongodb://localhost:27017`).
15+
- **Lint:** `npm run tslint` (TSLint on `src/**/*.ts`).
16+
17+
## Pre-commit (local)
18+
19+
`.husky/pre-commit` runs **Snyk** (`snyk test --all-projects`) and **Talisman** secret scanning. Both tools must be installed on the developer machine unless commits are skipped with `SKIP_HOOK=1` (documented in the hook). This is separate from `npm test` / `tslint`.
20+
21+
## Pull requests
22+
23+
- Prefer green **Jest** runs for changes that touch query or connection behavior.
24+
- Repository automation may include **SCA**, **policy**, and **CodeQL** workflows under `.github/workflows/` — follow failing checks before merge.
25+
- **Version bump:** `.github/workflows/check-version-bump.yml` enforces `package.json` version bumps for certain change sets. *Note:* That workflow’s path filters appear tailored to a different layout in places; if your PR changes `src/` or `test/` and CI expects a version bump, confirm behavior against the latest workflow definition.
26+
27+
## Releases
28+
29+
Package version is **`package.json` → `version`**. Publishing uses `publishConfig.access: public`. Bump the version when releasing; align with maintainers on semver for breaking Stack API or config shape changes.

‎.cursor/rules/testing.mdc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
description: Jest tests, MongoDB integration requirements, and test data layout for datasync-mongodb-sdk.
3+
globs:
4+
- test/**/*.ts
5+
- jest.config.js
6+
alwaysApply: false
7+
---
8+
9+
# Testing
10+
11+
## Runner and config
12+
13+
- **Jest** with **`ts-jest`** preset (`jest.config.js`).
14+
- **Environment:** `node`.
15+
- **Match:** `**/test/**/*.ts` (and `.js` if present).
16+
- **Coverage:** collected to `coverage/` (JSON + HTML reporters). `test/data/*` paths are ignored per `testPathIgnorePatterns`.
17+
18+
## Integration vs unit
19+
20+
- Tests are largely **integration**: they connect to a **real MongoDB** via `Stack.connect()`, insert fixtures, assert query results, then tear down collections / close the client.
21+
- There is no separate `test/integration` folder; behavior is split by topic files (e.g. `core.ts`, `queries.ts`, `references.ts`).
22+
23+
## Fixtures
24+
25+
- Shared sample documents: `test/data/*.ts` (e.g. `blog.ts`, `author.ts`, `content_types.ts`).
26+
- Stack config for tests: **`test/config.ts`** (e.g. `dbName: 'sync-test'`).
27+
28+
## Environment
29+
30+
- Default Mongo URL comes from merged **`src/config.ts`** (`contentStore.url`) unless tests override `contentStore` in the config object passed to `Contentstack.Stack(...)`.
31+
- No standard **`env` file** is defined in-repo for tests; use local MongoDB or explicitly pass `contentStore.url` in test configs.
32+
33+
## Naming
34+
35+
- Test files use descriptive topic names (`comparison-operators.ts`, `skip-limit.ts`, etc.), not `*.test.ts` — Jest picks them up via `testMatch`.

‎.cursor/rules/typescript.mdc‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
description: TypeScript conventions for this repo — compiler settings, TSLint, and src/ layout.
3+
globs:
4+
- src/**/*.ts
5+
- typings/**/*.ts
6+
alwaysApply: false
7+
---
8+
9+
# TypeScript — datasync-mongodb-sdk
10+
11+
## Toolchain
12+
13+
- **TypeScript** ~4.9 (`package.json` / `tsconfig.json`).
14+
- **Module:** CommonJS, `target` ES6, `moduleResolution` node. Declarations emit to `typings/`, JS to `dist/`.
15+
- **Strictness:** `alwaysStrict`, `noImplicitReturns`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`.
16+
17+
## Style (TSLint)
18+
19+
Align with `tslint.json`: **2-space** indent, **single quotes**, **no semicolons** (`semicolon: never`), **max line length 120**, `only-arrow-functions`, `ordered-imports`, `interface-name` with `I` prefix where used, `no-default-export` (prefer named exports from modules — entry re-exports via `src/index.ts`).
20+
21+
## Layout
22+
23+
- Keep new logic in `src/`; avoid expanding `example/` for core behavior.
24+
- Match existing patterns: JSDoc blocks on public classes/methods where the file already uses them.
25+
26+
## Logging
27+
28+
- Avoid adding `console.log` / noisy logging in library paths; TSLint warns on several `console` methods.

‎AGENTS.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Agent guidance — `@contentstack/datasync-mongodb-sdk`
2+
3+
## What this package is
4+
5+
**Contentstack DataSync MongoDB SDK** — a TypeScript/JavaScript library that **queries content already synced into MongoDB** (via Contentstack DataSync and stores such as `@contentstack/content-store-mongodb`). It is **not** a Content Delivery API (CDA) or Content Management API (CMA) HTTP client; it wraps the **MongoDB Node.js driver**, uses **sift** for predicate matching, and exposes a **Stack**-style query API over local collections.
6+
7+
## Repository
8+
9+
- **GitHub:** https://github.com/contentstack/datasync-mongodb-sdk
10+
11+
## Tech stack
12+
13+
| Area | Details |
14+
|------|---------|
15+
| Language | TypeScript **4.9.x** (compiles to `dist/`, declarations in `typings/`) |
16+
| Runtime | Node.js **≥ 8** (`package.json` engines); README suggests Node **20+** for local dev |
17+
| Build | `tsc` — `npm run compile` / `npm run build-ts` (with clean) |
18+
| Tests | **Jest 29** + **ts-jest**, Node test environment |
19+
| Data access | **mongodb** ^6.x, **lodash**, **sift** |
20+
| Lint | **TSLint** (`npm run tslint`) — repo does not use ESLint |
21+
| Docs | JSDoc → `npm run build-doc` (outputs under `docs/`) |
22+
23+
## Main entry points and layout
24+
25+
- **Published entry:** `main` → `dist/index.js` (build from `src/index.ts`).
26+
- **Public API:** `Contentstack.Stack(config, db?)` → `Stack` instance (`src/index.ts`, `src/stack.ts`).
27+
- **Config defaults:** `src/config.ts`; messages: `src/messages.ts`; helpers: `src/util.ts`.
28+
- **Type declarations:** `typings/*.d.ts` (generated/committed alongside build).
29+
- **Example:** `example/index.js` (not part of the core SDK package surface for agent edits).
30+
31+
## Common commands
32+
33+
| Command | Purpose |
34+
|---------|---------|
35+
| `npm run compile` | TypeScript compile to `dist/` |
36+
| `npm run build-ts` | `clean` + full `tsc` |
37+
| `npm run clean` | Remove `dist/`, `typings/`, `coverage/` |
38+
| `npm test` | Run Jest (see `jest.config.js`) |
39+
| `npm run tslint` | Lint `src/**/*.ts` |
40+
| `npm run build-doc` | Build TS then JSDoc site |
41+
42+
## Tests and credentials
43+
44+
Tests under `test/` are **integration-style**: they call `Stack.connect()` and use a real MongoDB instance (default **`mongodb://localhost:27017`** from `src/config.ts` unless overridden in config). There is **no** separate `.env` contract in this repo for tests; ensure MongoDB is running locally (database name in tests is typically `sync-test` per `test/config.ts`). Fixture data lives under `test/data/` (ignored as tests by Jest patterns where configured).
45+
46+
## Further reading for agents
47+
48+
- **Cursor rules (when to apply, globs, @-references):** [.cursor/rules/README.md](.cursor/rules/README.md)
49+
- **Skills (expanded checklists and workflows):** [skills/README.md](skills/README.md)

‎skills/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Agent skills — `@contentstack/datasync-mongodb-sdk`
2+
3+
Short index of per-topic folders containing **SKILL.md** files. Use them for deeper context than the Cursor rules alone.
4+
5+
| Skill folder | When to use it |
6+
|--------------|----------------|
7+
| [code-review](./code-review/SKILL.md) | PR preparation, review criteria, severity labels, terminology (DataSync vs CDA/CMA). |
8+
| [testing](./testing/SKILL.md) | Running Jest, MongoDB prerequisites, fixtures, test naming. |
9+
| [contentstack-typescript-datasync-mongodb](./contentstack-typescript-datasync-mongodb/SKILL.md) | SDK mental model (`Stack`, config, MongoDB), where to change query or connection behavior. |
10+
11+
## Related
12+
13+
- [AGENTS.md](../AGENTS.md) — single entry point for tools, paths, and commands.
14+
- [.cursor/rules/README.md](../.cursor/rules/README.md) — rule index and globs.

‎skills/code-review/SKILL.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: code-review
3+
description: PR review checklist for the Contentstack DataSync MongoDB SDK — JSDoc, compatibility, errors, tests, dependencies, and DataSync-vs-CDA/CMA terminology.
4+
---
5+
6+
# Skill: Code review (datasync-mongodb-sdk)
7+
8+
Use this skill when preparing or reviewing pull requests for **@contentstack/datasync-mongodb-sdk**.
9+
10+
## Scope reminder
11+
12+
This package implements **DataSync** queries against **MongoDB** (synced content). It is **not** the Contentstack **Delivery API (CDA)** or **Management API (CMA)** HTTP SDK. Reviews should use **DataSync** / **MongoDB Stack** terminology unless the change explicitly touches another system.
13+
14+
## Checklist
15+
16+
### Public API and documentation
17+
18+
- New or changed public surface on `Contentstack` / `Stack` has accurate **JSDoc** and matches behavior in `src/stack.ts`.
19+
- README or `example/` updates reflect required **`Stack.connect()`** usage and realistic `contentStore` config.
20+
21+
### Backward compatibility
22+
23+
- Avoid breaking changes to exported names, config keys, default limits/skip/locale behavior, or query result shapes without a major version plan.
24+
- Call out any change that affects **collection naming**, **locale** handling, or **reference depth** behavior for consumers.
25+
26+
### Errors and robustness
27+
28+
- Errors should flow through established patterns; prefer centralized copy in **`src/messages.ts`** where the codebase already does.
29+
- Avoid leaking internal MongoDB details in thrown messages unless intentional.
30+
31+
### Dependencies and security
32+
33+
- Justify new packages; prefer existing **lodash**, **mongodb**, **sift** usage patterns.
34+
- Consider **Snyk**/SCA impact and supply-chain expectations.
35+
36+
### Tests
37+
38+
- Add or update **Jest** tests with **MongoDB** running locally (default URL from config).
39+
- Use **`test/data/`** fixtures for new document shapes; keep `test/config.ts` consistent with inserted collections.
40+
41+
### Optional severity
42+
43+
| Level | Examples |
44+
|-------|----------|
45+
| Blocker | Data loss, security issue, broken connect/query for supported config |
46+
| Major | Wrong query results, missing tests for new feature, accidental breaking change |
47+
| Minor | Typos, non-functional cleanup, comment-only |
48+
49+
## Related
50+
51+
- Cursor rule: [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc)
52+
- Entry point: [`AGENTS.md`](../../AGENTS.md)

‎skills/contentstack-typescript-datasync-mongodb/SKILL.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
name: contentstack-typescript-datasync-mongodb
3+
description: Mental model and file map for the TypeScript DataSync MongoDB SDK — Stack, config, MongoDB driver usage (not CDA/CMA).
4+
---
5+
6+
# Skill: Contentstack TypeScript — DataSync MongoDB SDK
7+
8+
Use this skill when changing **query behavior**, **connection lifecycle**, or **configuration defaults** for **`@contentstack/datasync-mongodb-sdk`**.
9+
10+
## What this SDK is
11+
12+
- **DataSync MongoDB SDK:** queries **local/synced** MongoDB collections populated by Contentstack **DataSync** (e.g. via content-store-mongodb). **Not** a REST client for **Delivery** or **Management** APIs.
13+
14+
## Entry and flow
15+
16+
1. **`Contentstack.Stack(config, existingDb?)`** — `src/index.ts` → constructs **`Stack`**.
17+
2. **`Stack.connect()`** — establishes MongoDB client / DB (see `src/stack.ts`).
18+
3. Fluent API — **`contentType()`**, **`entries()`**, **`assets()`**, filters, **`language()`**, **`includeReferences()`**, etc., ending in **`find()`** / similar per implementation.
19+
20+
## Where to change things
21+
22+
| Concern | Primary location |
23+
|---------|------------------|
24+
| Defaults and mergeable config | `src/config.ts` |
25+
| Connection, queries, cursor logic | `src/stack.ts` |
26+
| Validation helpers (URI, config) | `src/util.ts` |
27+
| User-facing error/warning strings | `src/messages.ts` |
28+
| Package export surface | `src/index.ts` |
29+
30+
## Dependencies (facts from package.json)
31+
32+
- **`mongodb`** — database access.
33+
- **`lodash`** — merging and data manipulation.
34+
- **`sift`** — matching filters.
35+
36+
## Config concepts
37+
38+
- **`contentStore`:** `url`, `dbName`, **`collection`** (asset/entry/schema names), `locale`, `limit`, `skip`, `projections`, `options` (MongoClient), `referenceDepth`, `indexes`, internal type keys, etc.
39+
- **Locales** can influence collection naming in advanced setups (see tests that prefix collection names with locale segments).
40+
41+
## Related
42+
43+
- Cursor rule: [`.cursor/rules/datasync-mongodb.mdc`](../../.cursor/rules/datasync-mongodb.mdc)
44+
- Cursor rule: [`.cursor/rules/typescript.mdc`](../../.cursor/rules/typescript.mdc)
45+
- Entry point: [`AGENTS.md`](../../AGENTS.md)

0 commit comments

Comments
 (0)