Merge pull request #383 from contentstack/fix/dx-6049-update-cursor-rules-skills

docs: add AGENTS.md, skills, and Cursor rules entry

Author: harshitha-cstk

.cursor/rules/README.md

@@ -1,49 +1,5 @@
-# Cursor Rules Documentation
+# Cursor (optional)
 
-This directory contains **Cursor AI rules** for the **Contentstack JavaScript Content Delivery SDK** (`contentstack` on npm) — CDA client development in this repository.
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
 
-## Rules overview
-
-| Rule | Role |
-|------|------|
-| [`dev-workflow.md`](dev-workflow.md) | Branches, lint/tests before PR, build + version bump guidance, links to skills |
-| [`javascript.mdc`](javascript.mdc) | JavaScript / TypeScript declaration style: `src/`, `webpack/`, root `index.d.ts` |
-| [`contentstack-javascript-cda.mdc`](contentstack-javascript-cda.mdc) | CDA SDK patterns: `Stack`, delivery token, host/region, request/cache/live preview |
-| [`testing.mdc`](testing.mdc) | Jest e2e (`test/**/*.js`) and TypeScript tests; `test/config.js` env |
-| [`code-review.mdc`](code-review.mdc) | PR checklist: JSDoc, `index.d.ts`, compat, errors, tests, CDA semantics (**always applied**) |
-
-## Rule application
-
-Rules load from **globs** and **`alwaysApply`** in each file’s frontmatter.
-
-| Context | Typical rules |
-|---------|----------------|
-| **Every chat / session** | [`code-review.mdc`](code-review.mdc) (`alwaysApply: true`) |
-| **Most project files** | [`dev-workflow.md`](dev-workflow.md) — `**/*.js`, `**/*.ts`, `**/*.json` |
-| **SDK implementation** | [`javascript.mdc`](javascript.mdc) + [`contentstack-javascript-cda.mdc`](contentstack-javascript-cda.mdc) for `src/**/*.js` |
-| **Build config** | [`javascript.mdc`](javascript.mdc) for `webpack/**/*.js` |
-| **Public types** | [`javascript.mdc`](javascript.mdc) for `index.d.ts` |
-| **Tests** | [`testing.mdc`](testing.mdc) for `test/**/*.js`, `test/**/*.ts` |
-
-Overlaps are expected (e.g. editing `src/core/stack.js` can match `dev-workflow`, `javascript`, and `contentstack-javascript-cda`).
-
-## Usage
-
-- Rules load automatically when opened files match their globs (`code-review` is always in context).
-- You can **@ mention** rule files in chat when supported.
-
-## Quick reference table
-
-| File | `alwaysApply` | Globs (summary) |
-|------|---------------|-----------------|
-| `dev-workflow.md` | no | `**/*.js`, `**/*.ts`, `**/*.json` |
-| `javascript.mdc` | no | `src/**/*.js`, `webpack/**/*.js`, `index.d.ts` |
-| `contentstack-javascript-cda.mdc` | no | `src/**/*.js` |
-| `testing.mdc` | no | `test/**/*.js`, `test/**/*.ts` |
-| `code-review.mdc` | **yes** | — |
-
-## Skills & maintenance
-
-- Deeper playbooks: [`skills/README.md`](../../skills/README.md).
-- Repo agent entry: [`AGENTS.md`](../../AGENTS.md).
-- When directories change, update **globs** in rule frontmatter; keep rules short and put detail in `skills/*/SKILL.md`.
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

AGENTS.md

@@ -1,61 +1,43 @@
-# AGENTS.md — AI / automation context
+# Contentstack JavaScript Delivery SDK – Agent guide
 
-## Project
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-| | |
-|---|---|
-| **Name** | **`contentstack`** (npm) — **Contentstack JavaScript Content Delivery SDK** |
-| **Purpose** | Client for the **Content Delivery API (CDA)**: read published content, assets, taxonomies, sync, and live preview from a stack. *(This is not the Content Management API / CMA client — see `@contentstack/management`.)* |
-| **Repository** | [contentstack/contentstack-javascript](https://github.com/contentstack/contentstack-javascript.git) |
+## What this repo is
 
-## Tech stack
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack-javascript](https://github.com/contentstack/contentstack-javascript) (npm package **`contentstack`**) |
+| **Purpose:** | Legacy **JavaScript** Content Delivery SDK for browsers, Node.js, React Native, and NativeScript—stack initialization, queries, entries, assets. |
+| **Out of scope:** | Not the TypeScript-first **`@contentstack/delivery-sdk`** (`contentstack-typescript`); new TypeScript projects should prefer that package when appropriate. |
+
+## Tech stack (at a glance)
 
 | Area | Details |
 |------|---------|
-| **Language** | JavaScript **ES modules** in `src/core/` and `src/runtime/`; public types in root **`index.d.ts`** |
-| **Runtime** | Node `>= 10.14.2` per `package.json` `engines` |
-| **Build** | **Webpack** bundles for `node`, `web`, `react-native`, `nativescript` → `dist/` (`npm run build`) |
-| **Lint / style** | **ESLint** with `eslint-config-standard`, **`@babel/eslint-parser`**; **semicolons required** (see `.eslintrc.js`) |
-| **Tests** | **Jest**: JS e2e-style suite (`jest.js.config.js`, `test/**/*.js`) and **TypeScript** tests (`jest.config.js`, `test/typescript/**/*.test.ts`) |
-| **HTTP** | Platform **`fetch`** via webpack alias `runtime/http.js` and `runtime/localstorage.js` (Node / web / React Native / NativeScript) |
-| **Helpers** | **`@contentstack/utils`** re-exported on the `Contentstack` instance |
-
-## Source layout & public entrypoints
-
-| Path | Role |
-|------|------|
-| `src/core/contentstack.js` | Package facade: `Stack()`, `CachePolicy`, `Region`, `Utils` |
-| `src/core/stack.js` | `Stack` class: delivery config, queries, sync, plugins, `fetchOptions` |
-| `src/core/lib/request.js` | CDA requests: query serialization, retries, plugins `onRequest` / `onResponse` |
-| `src/core/lib/utils.js` | Shared helpers |
-| `src/core/modules/*` | Entry, Query, Assets, Taxonomy, Result, etc. |
-| `src/core/cache*.js`, `src/core/cache-provider/` | Cache policies and providers |
-| `src/runtime/**` | Per-platform `http` and `localstorage` implementations |
-| `config.js` | Default CDN host, API version, URL paths (imported by `stack.js`) |
-| `webpack/` | Build configs per target |
-| `dist/**` | Built artifacts (`package.json` `main` / `browser` / `react-native`) |
-
-## Common commands
-
-```bash
-npm install
-npm run build          # all webpack targets (also runs on prepare / pretest)
-npm run lint           # eslint src test
-npm run format         # eslint src test --fix
-npm run test           # test:e2e + test:typescript (pretest runs build)
-npm run test:e2e       # Jest JS tests under test/ (see jest.js.config.js)
-npm run test:typescript # Jest + ts-jest for test/typescript
-npm run generate-docs  # JSDoc (docs-config.json)
-```
-
-**Live API tests**
-
-- **`test/config.js`** loads **`.env`** and **requires** `HOST`, `API_KEY`, `DELIVERY_TOKEN`, `ENVIRONMENT`. Without them, importing `test/config.js` throws.
-- Jest e2e tests use **`dist/node/contentstack.js`** (built output). Run **`npm run build`** (or `npm test`, which runs `pretest`) before relying on fresh `src/` changes.
-
-## Further guidance
-
-- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
-- **Deeper playbooks:** [`skills/README.md`](skills/README.md)
-
-When unsure about API behavior, prefer the official [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) documentation and existing JSDoc in `src/core/`.
+| Language | JavaScript in **`src/`**; TypeScript tests via Jest (`test/typescript`) |
+| Build | Webpack configs under **`webpack/`**; outputs under **`dist/`** per target (`npm run build`) |
+| Tests | Jest: **`test:e2e`** (`jest.js.config.js`) and **`test:typescript`** (`jest.config.js`); **`pretest`** runs **`build`** first |
+| Lint / coverage | ESLint on `src` and `test` (`npm run lint`) |
+| CI | `.github/workflows/check-branch.yml`, `npm-publish.yml`, `sca-scan.yml`, `policy-scan.yml`, `codeql-analysis.yml`, `link-check.yml`, `issues-jira.yml` |
+
+## Commands (quick reference)
+
+| Command type | Command |
+|--------------|---------|
+| Build | `npm run build` |
+| Test | `npm test` (build via `pretest`, then e2e + TypeScript Jest suites) |
+| Lint | `npm run lint` |
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, npm scripts, Husky, CI |
+| **JavaScript SDK** | [`skills/contentstack-javascript-sdk/SKILL.md`](skills/contentstack-javascript-sdk/SKILL.md) | Public API (`Stack`, regions), `@contentstack/utils` |
+| **JavaScript tooling** | [`skills/javascript/SKILL.md`](skills/javascript/SKILL.md) | Webpack targets, `dist/` layout, Babel |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Jest configs, e2e vs TypeScript tests |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist |
+
+## Using Cursor (optional)
+
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

skills/code-review/SKILL.md

@@ -1,62 +1,27 @@
 ---
 name: code-review
-description: Use when reviewing PRs or before opening a PR — API design, errors, backward compatibility, dependencies, security, and test quality for the CDA SDK.
+description: Use when reviewing PRs for contentstack-javascript—API compatibility, bundles, Jest, and npm/CDN impact.
 ---
 
-# Code review — Contentstack JavaScript CDA SDK
-
-Use this skill for pull request review or self-review of the **`contentstack`** package (**Content Delivery API** client — not `@contentstack/management` / CMA).
+# Code review – contentstack-javascript
 
 ## When to use
 
-- Reviewing someone else’s PR.
-- Self-reviewing before submission.
-- Checking API, error, compatibility, tests, and security expectations.
+- Reviewing SDK or Webpack changes
+- Assessing dependency bumps (`@contentstack/utils`, Babel, Webpack, Jest)
 
 ## Instructions
 
-Work through the checklist. Optionally tag severity: **Blocker**, **Major**, **Minor**.
-
-### 1. API design and stability
-
-- [ ] **Public API:** New or changed exports are documented with **JSDoc**, consistent with `src/core/contentstack.js` and `src/core/stack.js`.
-- [ ] **TypeScript surface:** **`index.d.ts`** updated when consumers would see new or changed signatures.
-- [ ] **Backward compatibility:** No breaking changes to public signatures, option objects, or defaults without an agreed major bump.
-- [ ] **Naming:** Consistent with **CDA** concepts (stack, entry, query, asset, taxonomy, sync, environment).
-
-**Severity:** Breaking public API without approval = **Blocker**. Missing JSDoc or types on new public API = **Major**.
-
-### 2. Error handling and robustness
-
-- [ ] **Errors:** Rejections align with **`src/core/lib/request.js`** patterns (`error_message`, `error_code`, `errors`, `status`, `statusText` when JSON is available).
-- [ ] **Null safety:** Guard optional nested fields from API responses.
-- [ ] **Secrets:** No logging of full **delivery_token**, **preview_token**, **management_token**, or **api_key**.
-
-**Severity:** Missing or inconsistent error handling on new paths = **Major**.
-
-### 3. Dependencies and security
-
-- [ ] **Dependencies:** New or upgraded packages are justified; lockfile changes are intentional.
-- [ ] **SCA:** Address or explicitly track security findings from org tooling (Snyk, Dependabot, etc.).
-
-**Severity:** Unaddressed critical/high issues in scope = **Blocker**.
-
-### 4. Testing
-
-- [ ] **Jest:** New or changed behavior has coverage under **`test/`** (JS and/or **`test/typescript/`**).
-- [ ] **Live tests:** If tests hit the network, they respect **`test/config.js`** (`HOST`, `API_KEY`, `DELIVERY_TOKEN`, `ENVIRONMENT`); no committed secrets.
-- [ ] **Build:** Fresh `src/` changes are validated against **`dist/node/contentstack.js`** after **`npm run build`** when tests import dist.
-
-**Severity:** No tests for new behavior = **Blocker** (unless truly docs-only). Flaky tests = **Major**.
-
-### 5. Optional severity summary
+### Checklist
 
-- **Blocker:** Must fix before merge.
-- **Major:** Should fix before or soon after merge.
-- **Minor:** Nice to fix.
+- **Semver**: Breaking changes for npm and **jsDelivr** consumers called out with major bump and release notes.
+- **Bundles**: Each target still builds; `package.json` entry points remain valid.
+- **Tests**: `npm test` and `npm run lint` succeed for the change set.
+- **Docs**: README or JSDoc updated for user-visible behavior.
+- **Security**: No API keys in tests or docs.
 
-## References
+### Severity hints
 
-- `.cursor/rules/code-review.mdc`
-- `.cursor/rules/dev-workflow.md`
-- `skills/testing/SKILL.md`
+- **Blocker**: Broken `dist/` layout, failing CI, or regression in core `Stack` flow.
+- **Major**: Missing tests for new API surface or cross-environment behavior.
+- **Minor**: Internal refactors with full green tests.

skills/contentstack-javascript-sdk/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: contentstack-javascript-sdk
+description: Use for the contentstack npm package API—Stack, regions, queries, and @contentstack/utils usage.
+---
+
+# JavaScript Delivery SDK – contentstack-javascript
+
+## When to use
+
+- Changing how consumers call **`Contentstack.Stack(...)`** or Delivery API wrappers
+- Updating **`@contentstack/utils`** or cross-runtime behavior (browser vs Node vs RN)
+
+## Instructions
+
+### Package surface
+
+- Published as **`contentstack`** on npm; entry fields in **`package.json`** point to **`dist/node`**, **`dist/web`**, **`dist/react-native`**, etc.
+
+### API stability
+
+- This SDK has a long-lived **3.x** line—treat breaking changes as **semver major** and document migration for CDN and npm users.
+
+### Boundaries
+
+- Keep browser bundles free of Node-only APIs; keep Node builds free of DOM assumptions unless guarded.
+- Align behavior with other CDA SDKs where features overlap (regions, preview, sync) and update **`README.md`** examples when user-facing options change.

skills/dev-workflow/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: dev-workflow
+description: Use for npm scripts, Husky, CI, and branch workflow in contentstack-javascript.
+---
+
+# Development workflow – contentstack-javascript
+
+## When to use
+
+- Running builds or tests before a PR
+- Aligning with GitHub Actions (branch checks, publish, SCA)
+
+## Instructions
+
+### Branches
+
+- Default branch is **`master`** (`origin/HEAD`); **`development`** and **`next`** also exist—confirm PR target with the team.
+
+### Commands
+
+- **`npm run build`** — all Webpack targets (node, web, react-native, native-script).
+- **`npm test`** — runs **`pretest`** (which builds) then **`test:e2e`** and **`test:typescript`**.
+- **`npm run lint`** — ESLint on `src` and `test`.
+
+### Hooks
+
+- **`prepare`** runs **`build`** on install—expect compile time after dependency changes.
+- **`husky-check`** script wires Husky for pre-commit hooks when used.
+
+### CI
+
+- Workflows under **`.github/workflows/`** include npm publish, CodeQL, SCA, policy scans, and link checks.

skills/javascript/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: javascript
+description: Use for Webpack configs, multi-target dist outputs, and Babel/loader setup in contentstack-javascript.
+---
+
+# JavaScript tooling – contentstack-javascript
+
+## When to use
+
+- Editing **`webpack/*.js`** or changing how `src` is bundled per platform
+- Debugging path or env differences between **node**, **web**, **react-native**, and **nativescript** builds
+
+## Instructions
+
+### Webpack
+
+- Each target has its own config (`webpack.node.js`, `webpack.web.js`, etc.)—keep shared options consistent via **`webpack-merge`** where the repo already does.
+
+### Outputs
+
+- Artifacts land under **`dist/`**—verify **`package.json`** `main` / `browser` / `react-native` fields after changing filenames or folders.
+
+### Types
+
+- **`index.d.ts`** ships typings—update when public JS exports or options change.

skills/testing/SKILL.md

@@ -1,49 +1,26 @@
 ---
 name: testing
-description: How to run and extend tests — Jest e2e (test/*.js), TypeScript tests, test/config.js env, dist build.
+description: Use for Jest e2e and TypeScript test suites, jest configs, and test layout in contentstack-javascript.
 ---
 
-# Testing skill — `contentstack` (CDA)
+# Testing – contentstack-javascript
 
-## Commands (from `package.json`)
+## When to use
 
-| Goal | Command |
-|------|---------|
-| Lint | `npm run lint` |
-| Full test (includes build) | `npm test` — runs **`pretest`** → **`npm run build`**, then **`test:e2e`** + **`test:typescript`** |
-| JS Jest suite only | `npm run test:e2e` — config: **`jest.js.config.js`** |
-| TypeScript / Jest | `npm run test:typescript` — config: **`jest.config.js`** |
-| Build | `npm run build` — required before trusting **`dist/`** against updated `src/` |
+- Adding tests under **`test/`** or adjusting **`jest.js.config.js`** / **`jest.config.js`**
+- Debugging failures that only appear after **`pretest` / build**
 
-## JS tests (`test/**/*.js`)
+## Instructions
 
-- Wired from **`test/index.js`** via `require(...)`.
-- **`jest.js.config.js`** sets `testEnvironment: node`, HTML reporters, and **ignore patterns** for `test/index.js`, `test/config.js`, `test/sync_config.js`, and certain `utils.js` paths — check the config when adding files.
+### Suites
 
-## Environment variables (live stack)
+- **`npm run test:e2e`** — Jest with **`jest.js.config.js`**.
+- **`npm run test:typescript`** — Jest with **`jest.config.js`**, limited to **`test/typescript`** paths.
 
-**Authoritative validation:** **`test/config.js`** (uses **dotenv**).
+### Order
 
-**Required** when importing `test/config.js` (used by tests that need stack credentials):
+- Full **`npm test`** runs e2e then TypeScript tests; both assume a fresh **`build`** (via **`pretest`**).
 
-- **`HOST`** — delivery API host for your region/stack
-- **`API_KEY`**
-- **`DELIVERY_TOKEN`**
-- **`ENVIRONMENT`**
+### Hygiene
 
-If any are missing, the process throws on import. Use a local **`.env`**; never commit real tokens.
-
-## TypeScript tests (`test/typescript/`)
-
-- **`jest.config.js`**: **ts-jest**, transforms for TS/JS; HTML report under **`typescript-html-report/`** per config.
-- Use for type-level and behavioral checks against the public SDK shape; keep assertions aligned with **`index.d.ts`**.
-
-## Hygiene
-
-- No committed **`only`** / **`skip`** for CI-mandatory tests.
-- Prefer stable ordering and avoid time-dependent assertions unless unavoidable.
-
-## References
-
-- `.cursor/rules/testing.mdc`
-- `test/README.md`
+- Do not commit stack secrets; use fixtures or env patterns documented for this repo.