Skip to content

Commit d114865

Browse files
harshitha-cstkharshitha-cstk
authored
Merge pull request #531 from contentstack/feat/dx-5378-skills-rules
docs(DX-5378): AGENTS.md, Cursor rules, and project skills
2 parents 75edb00 + 5e4ebbd commit d114865

File tree

12 files changed

+512
-0
lines changed

12 files changed

+512
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Cursor Rules Documentation
2+
3+
This directory contains **Cursor AI rules** that provide context-aware guidance for the **Contentstack Management JavaScript SDK** (`@contentstack/management`) — CMA client development, not a separate CLI repo.
4+
5+
## Rules overview
6+
7+
| Rule | Role |
8+
|------|------|
9+
| [`dev-workflow.md`](dev-workflow.md) | Branches, lint/tests before PR (unit + optional sanity), version bump guidance, links to skills |
10+
| [`javascript.mdc`](javascript.mdc) | JavaScript / TypeScript declaration style: `lib/`, `webpack/`, `types/`, root `*.mjs` |
11+
| [`contentstack-javascript-cma.mdc`](contentstack-javascript-cma.mdc) | CMA SDK patterns in `lib/`: client, stack, auth, host/region, HTTP/error handling |
12+
| [`testing.mdc`](testing.mdc) | Mocha unit suite, sanity/API tests, Jest + `test/typescript`; env and mocks |
13+
| [`code-review.mdc`](code-review.mdc) | PR checklist: JSDoc, compat, errors, SCA, unit + sanity tests, CMA semantics (**always applied**) |
14+
15+
## Rule application
16+
17+
Rules load from **globs** and **`alwaysApply`** in each file’s frontmatter (not every rule runs for every file).
18+
19+
| Context | Typical rules |
20+
|---------|----------------|
21+
| **Every chat / session** | [`code-review.mdc`](code-review.mdc) (`alwaysApply: true`) |
22+
| **Most project files** | [`dev-workflow.md`](dev-workflow.md) — `**/*.js`, `**/*.ts`, `**/*.json`, `**/*.mjs` |
23+
| **SDK implementation** | [`javascript.mdc`](javascript.mdc) + [`contentstack-javascript-cma.mdc`](contentstack-javascript-cma.mdc) for `lib/**/*.js` |
24+
| **Build config** | [`javascript.mdc`](javascript.mdc) for `webpack/**/*.js` |
25+
| **Public types** | [`javascript.mdc`](javascript.mdc) for `types/**` |
26+
| **Tests** | [`testing.mdc`](testing.mdc) for `test/unit/**`, `test/sanity-check/**`, `test/typescript/**`, `test/**/index.js` |
27+
28+
Overlaps are expected (e.g. editing `lib/foo.js` can match `dev-workflow`, `javascript`, and `contentstack-javascript-cma`).
29+
30+
## Usage
31+
32+
- Rules are **loaded automatically** when opened files match their globs (and `code-review` is always in context).
33+
- You can **@ mention** rule files in chat when your Cursor build supports file references, e.g. `@dev-workflow`, `@javascript`, `@contentstack-javascript-cma`, `@testing`, `@code-review` (exact names depend on how Cursor labels `.md` / `.mdc` rules in your project).
34+
35+
## Quick reference table
36+
37+
| File | `alwaysApply` | Globs (summary) |
38+
|------|---------------|-----------------|
39+
| `dev-workflow.md` | no | `**/*.js`, `**/*.ts`, `**/*.json`, `**/*.mjs` |
40+
| `javascript.mdc` | no | `lib/**/*.js`, `webpack/**/*.js`, `types/**/*.ts`, `types/**/*.d.ts`, `*.mjs` |
41+
| `contentstack-javascript-cma.mdc` | no | `lib/**/*.js` |
42+
| `testing.mdc` | no | `test/unit/**`, `test/sanity-check/**`, `test/typescript/**`, `test/**/index.js` |
43+
| `code-review.mdc` | **yes** | — |
44+
45+
## Skills & maintenance
46+
47+
- Deeper playbooks: [`skills/README.md`](../../skills/README.md).
48+
- Repo agent entry: [`AGENTS.md`](../../AGENTS.md).
49+
- When directories change, update **globs** in rule frontmatter; keep rules short and put detail in `skills/*/SKILL.md`.

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
description: "PR review themes — API docs, compatibility, errors, security, tests"
3+
alwaysApply: true
4+
---
5+
6+
# Code review checklist (CMA JavaScript SDK)
7+
8+
Apply when reviewing changes to `@contentstack/management`.
9+
10+
## Public API & documentation
11+
12+
- **JSDoc** updated for new or changed public methods/classes (params, return shape, examples), matching style in `lib/contentstack.js` / `lib/contentstackClient.js`.
13+
- **`types/**`** updated when TypeScript consumers would see different signatures or new exports.
14+
15+
## Backward compatibility
16+
17+
- Avoid breaking changes to exported function signatures, option objects, or default behavior without a major version rationale.
18+
- If behavior changes, ensure **callers inside `lib/`** and tests reflect the new contract.
19+
20+
## Errors & safety
21+
22+
- HTTP failures should flow through **`lib/core/contentstackError.js`** (or equivalent existing error path), preserving **status** and safe **request** metadata.
23+
- Do not log or stringify full **authtoken**, **authorization**, or **management_token** values; follow existing redaction patterns in `contentstackError.js`.
24+
- Respect **null/undefined** edge cases for optional API fields; avoid assuming nested objects always exist.
25+
26+
## Dependencies & supply chain
27+
28+
- New **dependencies** should be justified (size, maintenance, license); prefer existing `lodash` / `axios` patterns.
29+
- Lockfile and **`package.json`** version bumps should be minimal and reviewable.
30+
31+
## Tests
32+
33+
- **Unit tests** for new logic or regressions (`test/unit/`), with HTTP **mocked** (Nock, axios-mock-adapter, Sinon, etc.).
34+
- **Sanity / API tests** (`test/sanity-check/api/`) when change affects live CMA behavior, request shape, or end-to-end flows: add or update the relevant `*-test.js` suite and ensure **`sanity.js`** still wires it; run against **`dist/node/contentstack-management.js`** after **`npm run build`**. Do not commit secrets; env vars belong in `test/sanity-check/utility/testSetup.js` documentation only.
35+
- Document any new env requirements for sanity in **`test/sanity-check/utility/testSetup.js`** header comments.
36+
37+
## Security & privacy
38+
39+
- No hardcoded credentials; no accidental exposure of customer content in logs or error messages.

‎.cursor/rules/contentstack-javascript-cma.mdc‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
description: "Contentstack CMA SDK patterns for lib/ (Management API client)"
3+
globs: ["lib/**/*.js"]
4+
alwaysApply: false
5+
---
6+
# Contentstack CMA SDK (`lib/`)
7+
8+
This package implements the **Content Management API (CMA)** client, not the read-only Content Delivery API.
9+
10+
## Client
11+
12+
- Entry: **`contentstack.client(params)`** in `lib/contentstack.js` — wires HTTP client, region/host/endpoint, **timeout**, **retryOnError**, **retryLimit**, **retryDelay**, **maxRequests**, **early_access**, optional **proxy**, **plugins**, etc.
13+
- Endpoint resolution uses **`getContentstackEndpoint`** from `@contentstack/utils` where applicable (see `contentstack.js`).
14+
15+
## Authentication & stack scoping
16+
17+
- **User/session**: `authtoken` or `authorization` header patterns set on the axios instance after `login` (`lib/contentstackClient.js`).
18+
- **Stack**: `client.stack({ api_key, management_token, ... })` — management token is stack-scoped.
19+
- **Organization**: `client.organization()` for org-level operations.
20+
- **Branch**: pass branch options where the Stack/entity factory methods accept them (match existing callers in `lib/stack/`).
21+
22+
## HTTP & errors
23+
24+
- All requests go through the **axios** instance created in **`lib/core/contentstackHTTPClient.js`** (concurrency queue, interceptors, retries on e.g. **429** per `retryCondition`).
25+
- Failures should continue to use **`lib/core/contentstackError.js`** in promise rejection chains (e.g. `.then(success, error)`), producing errors with **status**, **request** metadata, and **`error_message` / `error_code`** from CMA JSON when present.
26+
27+
## Resource modules
28+
29+
- **Entity** helpers and collection patterns: `lib/entity.js`, `lib/contentstackCollection.js`, `lib/query/index.js`.
30+
- New resources should follow existing **constructor(http, data)** + **`urlPath`** + **`stackHeaders`** patterns in sibling modules under `lib/stack/`.
31+
32+
## Callbacks vs async
33+
34+
- Prefer **Promises** (`async`/`await` or `.then`) consistent with surrounding code; avoid introducing callback-style APIs unless matching an existing public surface.
35+
36+
## CMA concepts
37+
38+
This SDK targets the **Content Management API (CMA)**, not the Content Delivery API.
39+
40+
- **Entry, Query, Asset, Content type, Taxonomy (terms, etc.), Stack, Branch, Locale, Webhooks,** and related resources — follow existing **class/module names and method names** in `lib/stack/` (and siblings) and **Management API** semantics (paths, query/body shapes, response parsing). When adding or changing CMA features, align with the official [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/) documentation.

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
description: "Branches, tests, and PR expectations for contentstack-management-javascript"
3+
globs: ["**/*.js", "**/*.ts", "**/*.json", "**/*.mjs"]
4+
alwaysApply: false
5+
---
6+
7+
# Development workflow - Contentstack javascript CMA SDK
8+
9+
## Branches
10+
11+
- Follow team Git conventions (e.g. feature branches off `development` / default integration branch as used in this repo).
12+
- Keep commits focused; do not commit with `test.only`, `it.only`, `describe.only`, or skipped tests meant to be permanent.
13+
14+
## Before opening a PR
15+
16+
1. **`npm run lint`** — ESLint must pass on `lib` and `test`.
17+
2. **Unit tests** — `npm run test:unit` (default `npm test` also invokes `test:api` first — ensure that script exists in `package.json` on your branch).
18+
3. **Sanity / API tests** — only when explicitly validating against live CMA: run `npm run test:sanity-nocov` or `test:sanity-test` after **`npm run build`**, with env vars documented in `test/sanity-check/utility/testSetup.js` (`EMAIL`, `PASSWORD`, `HOST`, `ORGANIZATION`, etc.). Never commit secrets.
19+
4. **Version bump** — When the PR introduces **user-visible or release-worthy** `lib/` behavior (new API, bug fix shipped to npm, or a **breaking** change), update **`version`** in `package.json` per **semver**: **patch** (fixes, internal-compatible tweaks), **minor** (backward-compatible features or additive API), **major** (breaking public contract). Docs-only, tests-only, or chore-only changes often **omit** a bump if your team bumps only at release; follow team practice (some repos bump only on `main`/`release`). If unsure, ask the reviewer or match sibling PRs.
20+
21+
## PR expectations (summary)
22+
23+
- **User-facing changes** — JSDoc on public methods; update `types/**` when the public surface changes.
24+
- **Behavior** — Preserve backward compatibility unless the change is explicitly breaking and documented.
25+
- **Errors** — Route HTTP failures through existing patterns (`lib/core/contentstackError.js`-style handling); avoid leaking full tokens in logs (existing code redacts authtoken/authorization in error paths).
26+
- **Tests** — Add or adjust unit tests under `test/unit/` for new behavior; use mocks (Sinon / Nock / axios-mock-adapter) rather than live API in unit tests.
27+
28+
## Quick links
29+
30+
- Agent overview: repo root `AGENTS.md`
31+
- CMA SDK patterns: `skills/contentstack-javascript-cma/SKILL.md`
32+
- HTTP / retry layer: `skills/framework/SKILL.md`

‎.cursor/rules/javascript.mdc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
description: "JavaScript/TypeScript conventions for lib, types, and webpack"
3+
globs:
4+
- "lib/**/*.js"
5+
- "webpack/**/*.js"
6+
- "types/**/*.ts"
7+
- "types/**/*.d.ts"
8+
- "*.mjs"
9+
alwaysApply: false
10+
---
11+
12+
# JavaScript & types (this repo)
13+
14+
## Runtime & modules
15+
16+
- **Source** is **ES modules** under `lib/` (`import` / `export`). Builds target Node and browsers via Babel + Webpack (see `package.json` scripts).
17+
- **`types/`** holds public TypeScript declarations consumed from npm; keep them aligned with `lib/` JSDoc and exports.
18+
19+
## Style & tooling
20+
21+
- **ESLint** uses **`eslint-config-standard`** and **`@babel/eslint-parser`**; match existing **semicolon-free** standard style and two-space indentation seen in `lib/`.
22+
- **Environment**: ESLint `es2020`; tests may relax rules via `overrides` in `.eslintrc.js` for `test/**/*.js`.
23+
24+
## Patterns
25+
26+
- Prefer **named exports** from feature modules where the codebase already does; default exports are used for factory-style modules (e.g. `contentstackClient`, HTTP client factory).
27+
- Use **JSDoc** (`@memberof`, `@func`, `@param`, `@returns`, `@example`) on **public** package API consistent with `lib/contentstack.js` and `lib/contentstackClient.js`.
28+
- **Dependencies**: `lodash` (e.g. `cloneDeep`), `axios`, `qs`, `@contentstack/utils` — follow existing import paths (`.js` suffixes in imports where used).
29+
30+
## Logging
31+
32+
- Do not add noisy `console.log` in library code except where aligned with existing `logHandler` / error reporting in `lib/core/contentstackHTTPClient.js`.
33+
- Never log full **authtoken**, **management tokens**, or raw **passwords**.

‎.cursor/rules/testing.mdc‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
description: "Mocha, Jest, and sanity-check tests for this SDK"
3+
globs:
4+
- "test/unit/**/*.js"
5+
- "test/sanity-check/**/*.js"
6+
- "test/typescript/**/*.ts"
7+
- "test/**/index.js"
8+
alwaysApply: false
9+
---
10+
11+
# Testing — `@contentstack/management`
12+
13+
## Frameworks
14+
15+
| Suite | Runner | Assertion / mocks | Notes |
16+
|-------|--------|-------------------|--------|
17+
| **Unit** | **Mocha** + `@babel/register` | **Chai**, **Sinon**, **Nock**, **axios-mock-adapter** | Entry: `test/unit/index.js`; **30s** timeout in npm script |
18+
| **Sanity / API** | Mocha | Chai; **live HTTP** | Entry: `test/sanity-check/sanity.js`; imports **`dist/node/contentstack-management.js`** — run **`npm run build`** first |
19+
| **TypeScript** | **Jest** + **ts-jest** | Jest mocks | `jest.config.js`; `npm run test:typescript` |
20+
21+
## Naming & layout
22+
23+
- **Unit**: `test/unit/*-test.js` (required from `test/unit/index.js`).
24+
- **Sanity**: `test/sanity-check/api/*-test.js` (orchestrated via `sanity.js`); shared setup in `test/sanity-check/utility/testSetup.js` and helpers.
25+
- **TS**: `test/typescript/**/*.test.ts` per Jest config.
26+
27+
## Credentials & env (sanity only)
28+
29+
- Canonical env documentation: **`test/sanity-check/utility/testSetup.js`** (see also `sanity.js`).
30+
- **Required for setup:** `EMAIL`, `PASSWORD`, `HOST`, `ORGANIZATION`.
31+
- **Suite-specific (tests skip when unset):** OAuth — `CLIENT_ID`, `APP_ID`, `REDIRECT_URI`; 2FA — `TFA_EMAIL`, `TFA_PASSWORD`; MFA — `MFA_SECRET`; team/stack share — `MEMBER_EMAIL`; DAM 2.0 — `DAM_2_0_ENABLED=true`.
32+
- **Optional / defaults:** `PERSONALIZE_HOST`, `DELETE_DYNAMIC_RESOURCES`. Use `HOST` for the target CMA API host / region.
33+
- Setup **writes** `API_KEY`, `AUTHTOKEN`, `MANAGEMENT_TOKEN`, `PERSONALIZE_PROJECT_UID` at runtime — never commit those.
34+
- Unit tests must **not** rely on real API keys; mock HTTP.
35+
36+
## Coverage
37+
38+
- **nyc** is used with `npm run test:unit` / `test:sanity-test`; exclusions are configured under `package.json` → `nyc`.
39+
40+
## Hygiene
41+
42+
- No committed **`only`** / **`skip`** for tests that should run in CI.
43+
- Prefer existing **`test/unit/mock/`** and sanity **`mock/`** patterns for fixtures.

‎AGENTS.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# AGENTS.md — AI / automation context
2+
3+
## Project
4+
5+
| | |
6+
|---|---|
7+
| **Name** | `@contentstack/management` (npm) — **Contentstack Management JavaScript SDK** |
8+
| **Purpose** | Client for the **Content Management API (CMA)**: create, update, delete, and fetch content and stack configuration in a Contentstack account. *(This is not the Content Delivery API / read-only delivery client.)* |
9+
| **Repository** | [contentstack/contentstack-management-javascript](https://github.com/contentstack/contentstack-management-javascript.git) |
10+
11+
## Tech stack
12+
13+
| Area | Details |
14+
|------|---------|
15+
| **Language** | JavaScript (ES modules in `lib/`); TypeScript declarations under `types/`; small Jest suite under `test/typescript/` |
16+
| **Runtime** | Node `>=8` per `package.json` `engines`; README suggests Node 10+ for typical development |
17+
| **Build** | Babel (`lib/` → `dist/es5`, `dist/es-modules`); Webpack bundles for `node`, `web`, `react-native`, `nativescript` |
18+
| **Lint / style** | ESLint with `standard` config (`eslint-config-standard`), `@babel/eslint-parser`, `es2020` env |
19+
| **Unit / API tests** | Mocha + Chai + `@babel/register` + `nyc`; Sinon / Nock / `axios-mock-adapter` where used |
20+
| **TypeScript tests** | Jest + `ts-jest` (`jest.config.js`, `npm run test:typescript`) |
21+
| **HTTP / JSON** | **Axios** (`axios`); query serialization via **qs**; helpers from **`@contentstack/utils`** (e.g. `getContentstackEndpoint`) |
22+
23+
## Source layout & public entrypoints
24+
25+
| Path | Role |
26+
|------|------|
27+
| `lib/contentstack.js` | Package entry: `contentstack.client()`, re-exports |
28+
| `lib/contentstackClient.js` | High-level client: `login`, `stack`, `organization`, etc. |
29+
| `lib/core/contentstackHTTPClient.js` | Axios instance, retries, concurrency, interceptors |
30+
| `lib/core/contentstackError.js` | Maps failed HTTP responses to thrown errors |
31+
| `lib/stack/**`, `lib/organization/**`, `lib/user/**`, `lib/query/**` | Resource modules |
32+
| `types/**` | Public `.d.ts` (and some `.ts`) for consumers |
33+
| `dist/**` | Built artifacts (`package.json` `main` / `browser`) |
34+
35+
## Common commands
36+
37+
```bash
38+
npm install
39+
npm run build # clean + babel + webpack targets
40+
npm run lint # eslint lib test
41+
npm run test # package.json chains test:api + test:unit (verify test:api exists in scripts)
42+
npm run test:unit # Mocha unit suite + nyc
43+
npm run test:sanity-test # integration-style suite (needs env + network)
44+
npm run test:sanity-nocov # same without nyc
45+
npm run test:typescript # Jest for test/typescript
46+
npm run generate:docs # JSDoc
47+
```
48+
49+
**Unit vs integration**
50+
51+
- **Unit**: `test/unit/index.js` wires Mocha files; mocked HTTP, no live CMA.
52+
- **Sanity / API**: `test/sanity-check/sanity.js` runs against a real stack; imports **`dist/node/contentstack-management.js`** (built output). **Requires credentials and env** (see `test/sanity-check/utility/testSetup.js`: `EMAIL`, `PASSWORD`, `HOST`, `ORGANIZATION`, optional OAuth / Personalize vars).
53+
54+
## Further guidance
55+
56+
- **Cursor rules (globs, always-apply):** [`.cursor/rules/README.md`](.cursor/rules/README.md)
57+
- **Deeper playbooks:** [`skills/README.md`](skills/README.md)
58+
59+
When unsure about API behavior, prefer the official [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/) docs and existing JSDoc in `lib/`.

‎skills/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Project skills
2+
3+
Short playbooks for agents and maintainers. Prefer these when you need depth beyond `.cursor/rules/*.mdc`.
4+
5+
| Skill | When to use |
6+
|-------|-------------|
7+
| [`code-review/`](code-review/SKILL.md) | Structured PR review, release readiness, API/doc alignment |
8+
| [`testing/`](testing/SKILL.md) | Mocha unit vs sanity runs, env vars, mocks, Jest TS tests |
9+
| [`contentstack-javascript-cma/`](contentstack-javascript-cma/SKILL.md) | CMA client usage: `client`, `stack`, auth, regions, entities |
10+
| [`framework/`](framework/SKILL.md) | Axios HTTP layer: retries, concurrency queue, interceptors, plugins, errors |
11+
12+
**Repo overview:** see root [`AGENTS.md`](../AGENTS.md). **Rule index:** [`.cursor/rules/README.md`](../.cursor/rules/README.md).
13+
14+
In Cursor, reference a skill in chat when supported (e.g. instructions that point at `@skills/testing` may map to these paths depending on your setup).

0 commit comments

Comments
 (0)