contentstack · harshitha-cstk · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026
@@ -1,37 +1,5 @@
-# Cursor Rules — `@contentstack/core`
+# Cursor (optional)
 
-Rules for **contentstack-js-core**: TypeScript foundation (HTTP, errors, retries) used by the Delivery SDK.
+**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) | Branch/PR expectations, build, lint, test, semver |
-| [`typescript.mdc`](typescript.mdc) | TypeScript style, `src/`, `config/`, `tools/` |
-| [`contentstack-js-core.mdc`](contentstack-js-core.mdc) | Axios client, errors, serializers, retry handlers |
-| [`testing.mdc`](testing.mdc) | Jest + ts-jest, specs, coverage thresholds |
-| [`code-review.mdc`](code-review.mdc) | PR checklist (**always applied**) |
-
-## Rule application
-
-| Context | Typical rules |
-|---------|----------------|
-| **Every session** | `code-review.mdc` |
-| **Most files** | `dev-workflow.md` |
-| **Implementation** | `typescript.mdc` + `contentstack-js-core.mdc` for `src/**/*.ts` |
-| **Build / tooling** | `typescript.mdc` for `config/**`, `tools/**` |
-| **Tests** | `testing.mdc` for `test/**` |
-
-## Quick reference
-
-| File | `alwaysApply` | Globs (summary) |
-|------|---------------|-----------------|
-| `dev-workflow.md` | no | `**/*.ts`, `**/*.js`, `**/*.json` |
-| `typescript.mdc` | no | `src/**/*.ts`, `config/**/*.ts`, `config/**/*.js`, `tools/**/*.js`, `*.ts` at root (jest, etc.) |
-| `contentstack-js-core.mdc` | no | `src/**/*.ts` |
-| `testing.mdc` | no | `test/**/*.ts` |
-| `code-review.mdc` | **yes** | — |
-
-## Skills & maintenance
-
-- [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.
@@ -1,55 +1,43 @@
-# AGENTS.md — AI / automation context
+# @contentstack/core – Agent guide
 
-## Project
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-| | |
-|---|---|
-| **Name** | **`@contentstack/core`** (npm) — **Contentstack JavaScript / TypeScript core library** |
-| **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. |
-| **Repository** | [contentstack/contentstack-js-core](https://github.com/contentstack/contentstack-js-core.git) |
+## What this repo is
 
-## Tech stack
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack-js-core](https://github.com/contentstack/contentstack-js-core) (`@contentstack/core`) |
+| **Purpose:** | TypeScript core library: HTTP client wiring, errors, serialization, retries—shared by Contentstack TS SDKs. |
+| **Out of scope:** | Not an end-user SDK; apps should use the Delivery SDK, which depends on this package. |
+
+## Tech stack (at a glance)
 
 | Area | Details |
 |------|---------|
-| **Language** | **TypeScript** in `src/` |
-| **HTTP** | **Axios** (`src/lib/contentstack-core.ts`), **qs** / custom **`param-serializer`**, **lodash** |
-| **Build** | **TypeScript** → **CJS** / **ESM** / **types** (`config/tsconfig.*.json`); **UMD** via **webpack** (`config/webpack.config.js`) |
-| **Lint** | **ESLint** (Airbnb TypeScript + Prettier; `.eslintrc.js` / `.eslintrc.json`) |
-| **Tests** | **Jest** + **ts-jest** (`jest.config.ts`, `test/**/*.spec.ts`); coverage thresholds in Jest config |
-
-## Source layout
-
-| Path | Role |
-|------|------|
-| `src/index.ts` | Public exports |
-| `src/lib/contentstack-core.ts` | **`httpClient`** factory, Axios config |
-| `src/lib/request.ts` / `param-serializer.ts` | Request wiring and query serialization |
-| `src/lib/contentstack-error.ts` / `api-error.ts` / `error-messages.ts` | Error types and messages |
-| `src/lib/retryPolicy/delivery-sdk-handlers.ts` | Retry interceptors for delivery SDK |
-| `src/lib/types.ts` | Shared TS types |
-| `config/` | TS compiler + webpack configs |
-| `tools/` | `cleanup`, `postbuild` |
-| `dist/` | Published artifacts (`package.json` `exports`) |
-
-## Common commands
-
-```bash
-npm install
-npm run build        # cjs + esm + umd + types
-npm run lint         # eslint . -c .eslintrc.js
-npm test             # jest ./test
-npm run clean        # node tools/cleanup
-```
-
-## Consumer relationship
-
-- **End users** should depend on **`@contentstack/delivery-sdk`**, not usually this package directly.
-- When changing public exports or behavior, consider impact on **contentstack-typescript** and semver for **`@contentstack/core`**.
-
-## Further guidance
-
-- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
-- **Skills:** [`skills/README.md`](skills/README.md)
-
-Official API context for consumers: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
+| Language | TypeScript (see `typescript` in `package.json`; `config/tsconfig.*.json`) |
+| Build | `tsc` (CJS/ESM/types) + Webpack UMD (`config/webpack.config.js`, `tools/`) |
+| Tests | Jest → `test/` (`npm test` → `jest ./test`) |
+| Lint / coverage | ESLint `.eslintrc.js` (`npm run lint`) |
+| CI | `.github/workflows/unit-test.yml`, `check-branch.yml`, `sca-scan.yml`, `policy-scan.yml`, `codeql-analysis.yml` |
+
+## Commands (quick reference)
+
+| Command type | Command |
+|--------------|---------|
+| Build | `npm run build` |
+| Test | `npm test` |
+| 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, CI, npm scripts, Husky, release notes |
+| **Contentstack core (package)** | [`skills/contentstack-core/SKILL.md`](skills/contentstack-core/SKILL.md) | `@contentstack/core` boundaries, public surface, dependency role |
+| **TypeScript & layout** | [`skills/typescript/SKILL.md`](skills/typescript/SKILL.md) | `src/`, `config/` tsconfigs, ESM/CJS/UMD outputs |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Jest layout, mocks, fixtures |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR expectations and 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.
@@ -1,20 +1,27 @@
 ---
 name: code-review
-description: PR review for @contentstack/core — public exports, delivery-sdk impact, errors, tests, coverage.
+description: Use when reviewing PRs or preparing changes for contentstack-js-core—API stability, tests, and consumer impact.
 ---
 
-# Code review — `@contentstack/core`
+# Code review – contentstack-js-core
 
-## Checklist
+## When to use
 
-- [ ] **Exports:** `src/index.ts` and `package.json` `exports` stay aligned; no accidental removal of symbols **delivery-sdk** uses.
-- [ ] **Semver:** Breaking type or runtime changes → **major**; additive → **minor** / **patch** as appropriate.
-- [ ] **HTTP / retry:** Behavior matches documented Axios options; 429 / retry paths still tested.
-- [ ] **Errors:** `ContentstackError` / `ApiError` patterns preserved; no token leakage in logs.
-- [ ] **Tests:** `npm test` passes; coverage thresholds in `jest.config.ts` satisfied.
-- [ ] **Lint:** `npm run lint` passes.
+- Authoring or reviewing a PR
+- Judging whether a change is safe for downstream SDKs
 
-## References
+## Instructions
 
-- `.cursor/rules/code-review.mdc`
-- `.cursor/rules/dev-workflow.md`
+### Checklist
+
+- **API / exports**: Any change to public exports or types that could break `@contentstack/delivery-sdk` or other consumers?
+- **Behavior**: Retries, errors, and serialization remain backward compatible unless semver major.
+- **Tests**: New logic covered; existing tests updated when semantics change.
+- **Build**: `npm run build` and `npm test` and `npm run lint` succeed.
+- **Security / deps**: Dependency bumps justified; no secrets in code or tests.
+
+### Severity hints
+
+- **Blocker**: Breaking change without major version or failing CI.
+- **Major**: Missing tests for risky HTTP/error changes.
+- **Minor**: Style, naming, or internal refactors with full green CI.
@@ -0,0 +1,28 @@
+---
+name: contentstack-core
+description: Use when working on @contentstack/core API surface, HTTP layer, errors, or how other SDKs consume this package.
+---
+
+# Contentstack core package – contentstack-js-core
+
+## When to use
+
+- Adding or changing modules under `src/`
+- Adjusting Axios usage, retries, error types, or serialization
+- Explaining how Delivery SDK pulls in this dependency
+
+## Instructions
+
+### Role of the package
+
+- Published as **`@contentstack/core`**; it is an **internal building block** for Contentstack TypeScript SDKs, not a standalone app SDK for stack users.
+- Entry points and exports are defined via `package.json` `exports` and build outputs under `dist/`.
+
+### Boundaries
+
+- Prefer stable, documented behavior for HTTP, errors, and request helpers—downstream SDKs rely on consistent error shapes and retry semantics.
+- Coordinate version bumps with consumers (e.g. `contentstack-typescript`) when changing public types or behavior.
+
+### Versioning
+
+- Follow semver for releases; breaking changes require a major bump and coordinated updates in dependent packages.
@@ -0,0 +1,31 @@
+---
+name: dev-workflow
+description: Use when changing branches, CI, npm scripts, Husky hooks, or release workflow in contentstack-js-core.
+---
+
+# Development workflow – contentstack-js-core
+
+## When to use
+
+- Planning a change that touches build, test, or CI
+- Onboarding to how PRs and checks run for this repo
+
+## Instructions
+
+### Branches and integration
+
+- Default branch is **`main`**; `development` also exists—match team practice for PR targets.
+- GitHub Actions under `.github/workflows/` run tests, branch checks, SCA, policy, and CodeQL—coordinate schema changes with those jobs.
+
+### Commands
+
+- Install: `npm ci` (or `npm install` for local dev).
+- Build: `npm run build` (CJS + ESM + UMD + types).
+- Test: `npm test`.
+- Lint: `npm run lint`.
+- `prepare` runs build and Husky setup—expect hooks after install.
+
+### PR expectations
+
+- Keep changes scoped; this package is consumed by other SDKs—avoid breaking exports without semver alignment.
+- Ensure `npm run build` and `npm test` pass locally before opening a PR.
@@ -1,28 +1,23 @@
 ---
 name: testing
-description: Run and extend Jest tests for @contentstack/core — ts-jest, coverage, mocks.
+description: Use when writing or fixing Jest tests, mocks, or test layout under test/ in contentstack-js-core.
 ---
 
-# Testing — `@contentstack/core`
+# Testing – contentstack-js-core
 
-## Commands
+## When to use
 
-| Goal | Command |
-|------|---------|
-| Unit tests | `npm test` → `jest ./test` |
-| Lint | `npm run lint` |
-| Build (before packaging) | `npm run build` |
+- Adding coverage for new `src/` behavior
+- Fixing flaky or outdated tests under `test/`
 
-## Config
+## Instructions
 
-- **`jest.config.ts`** — displayName, **ts-jest**, `tsconfig.spec.json`, **collectCoverageFrom** `src/**` (minus index if excluded), **coverageThreshold** (high bar).
-- Reporters: HTML under **`reports/contentstack-js-core/html`**, JUnit under **`reports/contentstack-js-core/junit`**.
+### Runner and layout
 
-## Patterns
+- **Jest** is configured for this repo; tests live under **`test/`** (`npm test` runs `jest ./test`).
+- Prefer focused unit tests near the behavior under test; use mocks for HTTP where `axios` or adapters are involved.
 
-- Use **axios-mock-adapter** or **`test/utils/mocks.ts`** for HTTP.
-- Name files **`*.spec.ts`** next to or under **`test/`** per existing layout.
+### Practice
 
-## References
-
-- `.cursor/rules/testing.mdc`
+- Run the full suite before merging: `npm test`.
+- Keep tests deterministic—no live network calls to Contentstack APIs in CI unless a dedicated integration job exists and secrets are available.
@@ -0,0 +1,24 @@
+---
+name: typescript
+description: Use for TypeScript layout, tsconfig variants, and build outputs (CJS/ESM/UMD/types) in contentstack-js-core.
+---
+
+# TypeScript & repo layout – contentstack-js-core
+
+## When to use
+
+- Editing `config/tsconfig.*.json` or build pipelines
+- Adding new source files under `src/`
+- Debugging dual CJS/ESM/UMD output issues
+
+## Instructions
+
+### Layout
+
+- Source lives under **`src/`**; compiled artifacts go to **`dist/`** via separate targets (`build:cjs`, `build:esm`, `build:umd`, `build:types`).
+- **`config/`** holds TypeScript and Webpack configs—keep them in sync when adding path aliases or new entry files.
+
+### Tooling
+
+- TypeScript version is pinned in `package.json`—upgrade deliberately with full `npm run build` and `npm test`.
+- ESLint uses `.eslintrc.js`; run `npm run lint` after structural refactors.