Skip to content

Commit 3c20efb

Browse files
sunil-lakshmansunil-lakshman
authored
Merge pull request #210 from contentstack/enh/dx-5382
enh: Added skills and cursor rules
2 parents 3e40eeb + fefbab9 commit 3c20efb

13 files changed

Lines changed: 336 additions & 0 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Cursor Rules — `@contentstack/core`
2+
3+
Rules for **contentstack-js-core**: TypeScript foundation (HTTP, errors, retries) used by the Delivery SDK.
4+
5+
## Rules overview
6+
7+
| Rule | Role |
8+
|------|------|
9+
| [`dev-workflow.md`](dev-workflow.md) | Branch/PR expectations, build, lint, test, semver |
10+
| [`typescript.mdc`](typescript.mdc) | TypeScript style, `src/`, `config/`, `tools/` |
11+
| [`contentstack-js-core.mdc`](contentstack-js-core.mdc) | Axios client, errors, serializers, retry handlers |
12+
| [`testing.mdc`](testing.mdc) | Jest + ts-jest, specs, coverage thresholds |
13+
| [`code-review.mdc`](code-review.mdc) | PR checklist (**always applied**) |
14+
15+
## Rule application
16+
17+
| Context | Typical rules |
18+
|---------|----------------|
19+
| **Every session** | `code-review.mdc` |
20+
| **Most files** | `dev-workflow.md` |
21+
| **Implementation** | `typescript.mdc` + `contentstack-js-core.mdc` for `src/**/*.ts` |
22+
| **Build / tooling** | `typescript.mdc` for `config/**`, `tools/**` |
23+
| **Tests** | `testing.mdc` for `test/**` |
24+
25+
## Quick reference
26+
27+
| File | `alwaysApply` | Globs (summary) |
28+
|------|---------------|-----------------|
29+
| `dev-workflow.md` | no | `**/*.ts`, `**/*.js`, `**/*.json` |
30+
| `typescript.mdc` | no | `src/**/*.ts`, `config/**/*.ts`, `config/**/*.js`, `tools/**/*.js`, `*.ts` at root (jest, etc.) |
31+
| `contentstack-js-core.mdc` | no | `src/**/*.ts` |
32+
| `testing.mdc` | no | `test/**/*.ts` |
33+
| `code-review.mdc` | **yes** | — |
34+
35+
## Skills & maintenance
36+
37+
- [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
description: "PR checklist for @contentstack/core — exports, semver, errors, tests, consumers"
3+
alwaysApply: true
4+
---
5+
6+
# Code review — `@contentstack/core`
7+
8+
## Public API
9+
10+
- **`src/index.ts`** exports match intended **npm `exports`**; new surface is documented and versioned.
11+
- Changes that affect **`@contentstack/delivery-sdk`** require a coordinated plan (bump **core** + **SDK** as needed).
12+
13+
## Implementation
14+
15+
- Axios / retry / serializer changes remain **backward compatible** unless this is a **major** release.
16+
- Errors use existing **classes** and **messages**; do not leak secrets in **logs** or **errors**.
17+
18+
## Tests & quality
19+
20+
- New logic includes **`test/*.spec.ts`** (or extends existing specs); **coverage thresholds** must still pass.
21+
- **Lint** clean.
22+
23+
## Dependencies
24+
25+
- New dependencies need justification (bundle size, maintenance, license).

‎.cursor/rules/contentstack-js-core.mdc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
description: "@contentstack/core — Axios httpClient, errors, serialization, retry policies"
3+
globs: ["src/**/*.ts"]
4+
alwaysApply: false
5+
---
6+
7+
# `@contentstack/core` implementation
8+
9+
## HTTP
10+
11+
- **`httpClient(options)`** in **`src/lib/contentstack-core.ts`** builds the **Axios** instance: **baseURL**, headers (**api_key**, **access_token**), **timeout**, **retryCondition** (e.g. **429**), **logHandler**, **versioningStrategy**, etc.
12+
- **`src/lib/request.ts`** and **`param-serializer.ts`** implement delivery-oriented query/body serialization — keep behavior aligned with CDA query expectations.
13+
14+
## Errors
15+
16+
- Use **`ContentstackError`** / **`ApiError`** and **`error-messages.ts`** for consistent messaging; preserve **status** / response metadata where applicable.
17+
18+
## Retries
19+
20+
- **`src/lib/retryPolicy/delivery-sdk-handlers.ts`** provides Axios interceptors (**retryRequestHandler**, **retryResponseHandler**, **retryResponseErrorHandler**) — changes here affect all consumers (including **@contentstack/delivery-sdk**).
21+
22+
## Testing
23+
24+
- Prefer **axios-mock-adapter** or mocks in **`test/utils`**; keep **`*.spec.ts`** focused and deterministic.

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
description: "Branches, build, lint, and PR expectations for contentstack-js-core"
3+
globs: ["**/*.ts", "**/*.js", "**/*.json"]
4+
alwaysApply: false
5+
---
6+
7+
# Development workflow — `@contentstack/core`
8+
9+
## Before a PR
10+
11+
1. **`npm run lint`** — must pass.
12+
2. **`npm test`** — Jest + coverage thresholds in `jest.config.ts` must be satisfied.
13+
3. **`npm run build`** — CJS, ESM, UMD, and types must compile.
14+
15+
## API stability
16+
17+
- This package is a **dependency of `@contentstack/delivery-sdk`**. Avoid breaking changes to exported functions, option shapes, or error types without a **semver-major** bump and coordinated **delivery-sdk** upgrade.
18+
- Keep **`package.json` `exports`** in sync with `src/index.ts`.
19+
20+
## Versioning
21+
22+
- Bump **`package.json` `version`** for releases that change published behavior (patch/minor/major per semver).
23+
24+
## Links
25+
26+
- [`AGENTS.md`](../../AGENTS.md) · [`skills/contentstack-js-core/SKILL.md`](../../skills/contentstack-js-core/SKILL.md)

‎.cursor/rules/testing.mdc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
description: "Jest tests and coverage for @contentstack/core"
3+
globs: ["test/**/*.ts"]
4+
alwaysApply: false
5+
---
6+
7+
# Testing — contentstack-js-core
8+
9+
## Runner
10+
11+
- **Jest** + **ts-jest** — see **`jest.config.ts`** / **`jest.preset.js`** / **`tsconfig.spec.json`**.
12+
- **Coverage** is collected from **`src/**`** (with exclusions in config); **global thresholds** (branches/functions/lines/statements) apply — see `jest.config.ts`.
13+
14+
## Layout
15+
16+
- Specs: **`test/*.spec.ts`** (e.g. `request.spec.ts`, `contentstack-core.spec.ts`).
17+
- Shared mocks: **`test/utils/mocks.ts`**.
18+
19+
## Hygiene
20+
21+
- No **committed** `it.only` / `describe.only` meant for CI.
22+
- Avoid live network calls in unit tests unless explicitly an integration suite (this repo is primarily mocked unit tests).

‎.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 and repo conventions for @contentstack/core"
3+
globs:
4+
- "src/**/*.ts"
5+
- "config/**/*.ts"
6+
- "config/**/*.js"
7+
- "tools/**/*.js"
8+
- "jest.config.ts"
9+
- "jest.preset.js"
10+
alwaysApply: false
11+
---
12+
13+
# TypeScript — contentstack-js-core
14+
15+
## Layout
16+
17+
- **`src/lib/*.ts`** — implementation modules; **`src/index.ts`** re-exports the public surface.
18+
- **Configs** live under **`config/`** (multiple `tsconfig.*.json`, webpack).
19+
20+
## Style
21+
22+
- Follow **ESLint** (Airbnb TypeScript + Prettier) and existing patterns in `src/lib/`.
23+
- Prefer **explicit types** on public exports and Axios-related options.
24+
- Use **lodash** / **axios** patterns already present in `contentstack-core.ts` and `request.ts`.
25+
26+
## Security
27+
28+
- Do not log **api keys**, **access tokens**, or full auth headers in new code; align with existing **`logHandler`** usage.

‎.vscode/settings.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"snyk.advanced.autoSelectOrganization": true
3+
}

‎AGENTS.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# AGENTS.md — AI / automation context
2+
3+
## Project
4+
5+
| | |
6+
|---|---|
7+
| **Name** | **`@contentstack/core`** (npm) — **Contentstack JavaScript / TypeScript core library** |
8+
| **Purpose** | Foundational HTTP client, errors, serialization, and retry helpers consumed by **Contentstack TypeScript Delivery SDK** (`@contentstack/delivery-sdk`) and related packages. **Not** an app-facing CDA client by itself. |
9+
| **Repository** | [contentstack/contentstack-js-core](https://github.com/contentstack/contentstack-js-core.git) |
10+
11+
## Tech stack
12+
13+
| Area | Details |
14+
|------|---------|
15+
| **Language** | **TypeScript** in `src/` |
16+
| **HTTP** | **Axios** (`src/lib/contentstack-core.ts`), **qs** / custom **`param-serializer`**, **lodash** |
17+
| **Build** | **TypeScript** → **CJS** / **ESM** / **types** (`config/tsconfig.*.json`); **UMD** via **webpack** (`config/webpack.config.js`) |
18+
| **Lint** | **ESLint** (Airbnb TypeScript + Prettier; `.eslintrc.js` / `.eslintrc.json`) |
19+
| **Tests** | **Jest** + **ts-jest** (`jest.config.ts`, `test/**/*.spec.ts`); coverage thresholds in Jest config |
20+
21+
## Source layout
22+
23+
| Path | Role |
24+
|------|------|
25+
| `src/index.ts` | Public exports |
26+
| `src/lib/contentstack-core.ts` | **`httpClient`** factory, Axios config |
27+
| `src/lib/request.ts` / `param-serializer.ts` | Request wiring and query serialization |
28+
| `src/lib/contentstack-error.ts` / `api-error.ts` / `error-messages.ts` | Error types and messages |
29+
| `src/lib/retryPolicy/delivery-sdk-handlers.ts` | Retry interceptors for delivery SDK |
30+
| `src/lib/types.ts` | Shared TS types |
31+
| `config/` | TS compiler + webpack configs |
32+
| `tools/` | `cleanup`, `postbuild` |
33+
| `dist/` | Published artifacts (`package.json` `exports`) |
34+
35+
## Common commands
36+
37+
```bash
38+
npm install
39+
npm run build # cjs + esm + umd + types
40+
npm run lint # eslint . -c .eslintrc.js
41+
npm test # jest ./test
42+
npm run clean # node tools/cleanup
43+
```
44+
45+
## Consumer relationship
46+
47+
- **End users** should depend on **`@contentstack/delivery-sdk`**, not usually this package directly.
48+
- When changing public exports or behavior, consider impact on **contentstack-typescript** and semver for **`@contentstack/core`**.
49+
50+
## Further guidance
51+
52+
- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
53+
- **Skills:** [`skills/README.md`](skills/README.md)
54+
55+
Official API context for consumers: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).

‎skills/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Project skills — `@contentstack/core`
2+
3+
| Skill | When to use |
4+
|-------|-------------|
5+
| [`code-review/`](code-review/SKILL.md) | PR readiness, semver, consumer impact |
6+
| [`testing/`](testing/SKILL.md) | Jest, coverage thresholds, mocks |
7+
| [`contentstack-js-core/`](contentstack-js-core/SKILL.md) | httpClient, request, errors, retry handlers |
8+
| [`framework/`](framework/SKILL.md) | Axios pipeline, interceptors, serializers |
9+
10+
**Overview:** [`AGENTS.md`](../AGENTS.md) · **Rules:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)

‎skills/code-review/SKILL.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
name: code-review
3+
description: PR review for @contentstack/core — public exports, delivery-sdk impact, errors, tests, coverage.
4+
---
5+
6+
# Code review — `@contentstack/core`
7+
8+
## Checklist
9+
10+
- [ ] **Exports:** `src/index.ts` and `package.json` `exports` stay aligned; no accidental removal of symbols **delivery-sdk** uses.
11+
- [ ] **Semver:** Breaking type or runtime changes → **major**; additive → **minor** / **patch** as appropriate.
12+
- [ ] **HTTP / retry:** Behavior matches documented Axios options; 429 / retry paths still tested.
13+
- [ ] **Errors:** `ContentstackError` / `ApiError` patterns preserved; no token leakage in logs.
14+
- [ ] **Tests:** `npm test` passes; coverage thresholds in `jest.config.ts` satisfied.
15+
- [ ] **Lint:** `npm run lint` passes.
16+
17+
## References
18+
19+
- `.cursor/rules/code-review.mdc`
20+
- `.cursor/rules/dev-workflow.md`

0 commit comments

Comments
 (0)