Skip to content

Commit 9689c9b

Browse files
harshithad0703harshithad0703
authored
Merge pull request #220 from contentstack/fix/dx-6051-update-cursor-rules-skills
docs(DX-6051): add AGENTS.md, skills, and Cursor rules entry
2 parents eafc583 + 8ac250d commit 9689c9b

7 files changed

Lines changed: 154 additions & 113 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 3 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,5 @@
1-
# Cursor Rules — `@contentstack/core`
1+
# Cursor (optional)
22

3-
Rules for **contentstack-js-core**: TypeScript foundation (HTTP, errors, retries) used by the Delivery SDK.
3+
**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
44

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)
5+
This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

‎AGENTS.md‎

Lines changed: 37 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,43 @@
1-
# AGENTS.md — AI / automation context
1+
# @contentstack/core – Agent guide
22

3-
## Project
3+
**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
44

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) |
5+
## What this repo is
106

11-
## Tech stack
7+
| Field | Detail |
8+
|--------|--------|
9+
| **Name:** | [contentstack-js-core](https://github.com/contentstack/contentstack-js-core) (`@contentstack/core`) |
10+
| **Purpose:** | TypeScript core library: HTTP client wiring, errors, serialization, retries—shared by Contentstack TS SDKs. |
11+
| **Out of scope:** | Not an end-user SDK; apps should use the Delivery SDK, which depends on this package. |
12+
13+
## Tech stack (at a glance)
1214

1315
| Area | Details |
1416
|------|---------|
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/).
17+
| Language | TypeScript (see `typescript` in `package.json`; `config/tsconfig.*.json`) |
18+
| Build | `tsc` (CJS/ESM/types) + Webpack UMD (`config/webpack.config.js`, `tools/`) |
19+
| Tests | Jest → `test/` (`npm test` → `jest ./test`) |
20+
| Lint / coverage | ESLint `.eslintrc.js` (`npm run lint`) |
21+
| CI | `.github/workflows/unit-test.yml`, `check-branch.yml`, `sca-scan.yml`, `policy-scan.yml`, `codeql-analysis.yml` |
22+
23+
## Commands (quick reference)
24+
25+
| Command type | Command |
26+
|--------------|---------|
27+
| Build | `npm run build` |
28+
| Test | `npm test` |
29+
| Lint | `npm run lint` |
30+
31+
## Where the documentation lives: skills
32+
33+
| Skill | Path | What it covers |
34+
|-------|------|----------------|
35+
| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, npm scripts, Husky, release notes |
36+
| **Contentstack core (package)** | [`skills/contentstack-core/SKILL.md`](skills/contentstack-core/SKILL.md) | `@contentstack/core` boundaries, public surface, dependency role |
37+
| **TypeScript & layout** | [`skills/typescript/SKILL.md`](skills/typescript/SKILL.md) | `src/`, `config/` tsconfigs, ESM/CJS/UMD outputs |
38+
| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Jest layout, mocks, fixtures |
39+
| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR expectations and checklist |
40+
41+
## Using Cursor (optional)
42+
43+
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‎

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,27 @@
11
---
22
name: code-review
3-
description: PR review for @contentstack/core — public exports, delivery-sdk impact, errors, tests, coverage.
3+
description: Use when reviewing PRs or preparing changes for contentstack-js-core—API stability, tests, and consumer impact.
44
---
55

6-
# Code review — `@contentstack/core`
6+
# Code review – contentstack-js-core
77

8-
## Checklist
8+
## When to use
99

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.
10+
- Authoring or reviewing a PR
11+
- Judging whether a change is safe for downstream SDKs
1612

17-
## References
13+
## Instructions
1814

19-
- `.cursor/rules/code-review.mdc`
20-
- `.cursor/rules/dev-workflow.md`
15+
### Checklist
16+
17+
- **API / exports**: Any change to public exports or types that could break `@contentstack/delivery-sdk` or other consumers?
18+
- **Behavior**: Retries, errors, and serialization remain backward compatible unless semver major.
19+
- **Tests**: New logic covered; existing tests updated when semantics change.
20+
- **Build**: `npm run build` and `npm test` and `npm run lint` succeed.
21+
- **Security / deps**: Dependency bumps justified; no secrets in code or tests.
22+
23+
### Severity hints
24+
25+
- **Blocker**: Breaking change without major version or failing CI.
26+
- **Major**: Missing tests for risky HTTP/error changes.
27+
- **Minor**: Style, naming, or internal refactors with full green CI.

‎skills/contentstack-core/SKILL.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
name: contentstack-core
3+
description: Use when working on @contentstack/core API surface, HTTP layer, errors, or how other SDKs consume this package.
4+
---
5+
6+
# Contentstack core package – contentstack-js-core
7+
8+
## When to use
9+
10+
- Adding or changing modules under `src/`
11+
- Adjusting Axios usage, retries, error types, or serialization
12+
- Explaining how Delivery SDK pulls in this dependency
13+
14+
## Instructions
15+
16+
### Role of the package
17+
18+
- Published as **`@contentstack/core`**; it is an **internal building block** for Contentstack TypeScript SDKs, not a standalone app SDK for stack users.
19+
- Entry points and exports are defined via `package.json` `exports` and build outputs under `dist/`.
20+
21+
### Boundaries
22+
23+
- Prefer stable, documented behavior for HTTP, errors, and request helpers—downstream SDKs rely on consistent error shapes and retry semantics.
24+
- Coordinate version bumps with consumers (e.g. `contentstack-typescript`) when changing public types or behavior.
25+
26+
### Versioning
27+
28+
- Follow semver for releases; breaking changes require a major bump and coordinated updates in dependent packages.

‎skills/dev-workflow/SKILL.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: dev-workflow
3+
description: Use when changing branches, CI, npm scripts, Husky hooks, or release workflow in contentstack-js-core.
4+
---
5+
6+
# Development workflow – contentstack-js-core
7+
8+
## When to use
9+
10+
- Planning a change that touches build, test, or CI
11+
- Onboarding to how PRs and checks run for this repo
12+
13+
## Instructions
14+
15+
### Branches and integration
16+
17+
- Default branch is **`main`**; `development` also exists—match team practice for PR targets.
18+
- GitHub Actions under `.github/workflows/` run tests, branch checks, SCA, policy, and CodeQL—coordinate schema changes with those jobs.
19+
20+
### Commands
21+
22+
- Install: `npm ci` (or `npm install` for local dev).
23+
- Build: `npm run build` (CJS + ESM + UMD + types).
24+
- Test: `npm test`.
25+
- Lint: `npm run lint`.
26+
- `prepare` runs build and Husky setup—expect hooks after install.
27+
28+
### PR expectations
29+
30+
- Keep changes scoped; this package is consumed by other SDKs—avoid breaking exports without semver alignment.
31+
- Ensure `npm run build` and `npm test` pass locally before opening a PR.

‎skills/testing/SKILL.md‎

Lines changed: 12 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,23 @@
11
---
22
name: testing
3-
description: Run and extend Jest tests for @contentstack/core — ts-jest, coverage, mocks.
3+
description: Use when writing or fixing Jest tests, mocks, or test layout under test/ in contentstack-js-core.
44
---
55

6-
# Testing — `@contentstack/core`
6+
# Testing – contentstack-js-core
77

8-
## Commands
8+
## When to use
99

10-
| Goal | Command |
11-
|------|---------|
12-
| Unit tests | `npm test` → `jest ./test` |
13-
| Lint | `npm run lint` |
14-
| Build (before packaging) | `npm run build` |
10+
- Adding coverage for new `src/` behavior
11+
- Fixing flaky or outdated tests under `test/`
1512

16-
## Config
13+
## Instructions
1714

18-
- **`jest.config.ts`** — displayName, **ts-jest**, `tsconfig.spec.json`, **collectCoverageFrom** `src/**` (minus index if excluded), **coverageThreshold** (high bar).
19-
- Reporters: HTML under **`reports/contentstack-js-core/html`**, JUnit under **`reports/contentstack-js-core/junit`**.
15+
### Runner and layout
2016

21-
## Patterns
17+
- **Jest** is configured for this repo; tests live under **`test/`** (`npm test` runs `jest ./test`).
18+
- Prefer focused unit tests near the behavior under test; use mocks for HTTP where `axios` or adapters are involved.
2219

23-
- Use **axios-mock-adapter** or **`test/utils/mocks.ts`** for HTTP.
24-
- Name files **`*.spec.ts`** next to or under **`test/`** per existing layout.
20+
### Practice
2521

26-
## References
27-
28-
- `.cursor/rules/testing.mdc`
22+
- Run the full suite before merging: `npm test`.
23+
- Keep tests deterministic—no live network calls to Contentstack APIs in CI unless a dedicated integration job exists and secrets are available.

‎skills/typescript/SKILL.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
name: typescript
3+
description: Use for TypeScript layout, tsconfig variants, and build outputs (CJS/ESM/UMD/types) in contentstack-js-core.
4+
---
5+
6+
# TypeScript & repo layout – contentstack-js-core
7+
8+
## When to use
9+
10+
- Editing `config/tsconfig.*.json` or build pipelines
11+
- Adding new source files under `src/`
12+
- Debugging dual CJS/ESM/UMD output issues
13+
14+
## Instructions
15+
16+
### Layout
17+
18+
- Source lives under **`src/`**; compiled artifacts go to **`dist/`** via separate targets (`build:cjs`, `build:esm`, `build:umd`, `build:types`).
19+
- **`config/`** holds TypeScript and Webpack configs—keep them in sync when adding path aliases or new entry files.
20+
21+
### Tooling
22+
23+
- TypeScript version is pinned in `package.json`—upgrade deliberately with full `npm run build` and `npm test`.
24+
- ESLint uses `.eslintrc.js`; run `npm run lint` after structural refactors.

0 commit comments

Comments
 (0)