Skip to content

Commit d268062

Browse files
harshitha-cstkharshitha-cstk
committed
docs: add AGENTS.md, skills, and Cursor rules entry
1 parent 1143032 commit d268062

File tree

7 files changed

+184
-0
lines changed

7 files changed

+184
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Cursor (optional)
2+
3+
**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
4+
5+
This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

‎AGENTS.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Contentstack JavaScript Delivery SDK – Agent guide
2+
3+
**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
4+
5+
## What this repo is
6+
7+
| Field | Detail |
8+
|--------|--------|
9+
| **Name:** | [contentstack-javascript](https://github.com/contentstack/contentstack-javascript) (npm package **`contentstack`**) |
10+
| **Purpose:** | Legacy **JavaScript** Content Delivery SDK for browsers, Node.js, React Native, and NativeScript—stack initialization, queries, entries, assets. |
11+
| **Out of scope:** | Not the TypeScript-first **`@contentstack/delivery-sdk`** (`contentstack-typescript`); new TypeScript projects should prefer that package when appropriate. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
|------|---------|
17+
| Language | JavaScript in **`src/`**; TypeScript tests via Jest (`test/typescript`) |
18+
| Build | Webpack configs under **`webpack/`**; outputs under **`dist/`** per target (`npm run build`) |
19+
| Tests | Jest: **`test:e2e`** (`jest.js.config.js`) and **`test:typescript`** (`jest.config.js`); **`pretest`** runs **`build`** first |
20+
| Lint / coverage | ESLint on `src` and `test` (`npm run lint`) |
21+
| CI | `.github/workflows/check-branch.yml`, `npm-publish.yml`, `sca-scan.yml`, `policy-scan.yml`, `codeql-analysis.yml`, `link-check.yml`, `issues-jira.yml` |
22+
23+
## Commands (quick reference)
24+
25+
| Command type | Command |
26+
|--------------|---------|
27+
| Build | `npm run build` |
28+
| Test | `npm test` (build via `pretest`, then e2e + TypeScript Jest suites) |
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, npm scripts, Husky, CI |
36+
| **JavaScript SDK** | [`skills/contentstack-javascript-sdk/SKILL.md`](skills/contentstack-javascript-sdk/SKILL.md) | Public API (`Stack`, regions), `@contentstack/utils` |
37+
| **JavaScript tooling** | [`skills/javascript/SKILL.md`](skills/javascript/SKILL.md) | Webpack targets, `dist/` layout, Babel |
38+
| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Jest configs, e2e vs TypeScript tests |
39+
| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR 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: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: code-review
3+
description: Use when reviewing PRs for contentstack-javascript—API compatibility, bundles, Jest, and npm/CDN impact.
4+
---
5+
6+
# Code review – contentstack-javascript
7+
8+
## When to use
9+
10+
- Reviewing SDK or Webpack changes
11+
- Assessing dependency bumps (`@contentstack/utils`, Babel, Webpack, Jest)
12+
13+
## Instructions
14+
15+
### Checklist
16+
17+
- **Semver**: Breaking changes for npm and **jsDelivr** consumers called out with major bump and release notes.
18+
- **Bundles**: Each target still builds; `package.json` entry points remain valid.
19+
- **Tests**: `npm test` and `npm run lint` succeed for the change set.
20+
- **Docs**: README or JSDoc updated for user-visible behavior.
21+
- **Security**: No API keys in tests or docs.
22+
23+
### Severity hints
24+
25+
- **Blocker**: Broken `dist/` layout, failing CI, or regression in core `Stack` flow.
26+
- **Major**: Missing tests for new API surface or cross-environment behavior.
27+
- **Minor**: Internal refactors with full green tests.

‎skills/contentstack-javascript-sdk/SKILL.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: contentstack-javascript-sdk
3+
description: Use for the contentstack npm package API—Stack, regions, queries, and @contentstack/utils usage.
4+
---
5+
6+
# JavaScript Delivery SDK – contentstack-javascript
7+
8+
## When to use
9+
10+
- Changing how consumers call **`Contentstack.Stack(...)`** or Delivery API wrappers
11+
- Updating **`@contentstack/utils`** or cross-runtime behavior (browser vs Node vs RN)
12+
13+
## Instructions
14+
15+
### Package surface
16+
17+
- Published as **`contentstack`** on npm; entry fields in **`package.json`** point to **`dist/node`**, **`dist/web`**, **`dist/react-native`**, etc.
18+
19+
### API stability
20+
21+
- This SDK has a long-lived **3.x** line—treat breaking changes as **semver major** and document migration for CDN and npm users.
22+
23+
### Boundaries
24+
25+
- Keep browser bundles free of Node-only APIs; keep Node builds free of DOM assumptions unless guarded.
26+
- 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‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: dev-workflow
3+
description: Use for npm scripts, Husky, CI, and branch workflow in contentstack-javascript.
4+
---
5+
6+
# Development workflow – contentstack-javascript
7+
8+
## When to use
9+
10+
- Running builds or tests before a PR
11+
- Aligning with GitHub Actions (branch checks, publish, SCA)
12+
13+
## Instructions
14+
15+
### Branches
16+
17+
- Default branch is **`master`** (`origin/HEAD`); **`development`** and **`next`** also exist—confirm PR target with the team.
18+
19+
### Commands
20+
21+
- **`npm run build`** — all Webpack targets (node, web, react-native, native-script).
22+
- **`npm test`** — runs **`pretest`** (which builds) then **`test:e2e`** and **`test:typescript`**.
23+
- **`npm run lint`** — ESLint on `src` and `test`.
24+
25+
### Hooks
26+
27+
- **`prepare`** runs **`build`** on install—expect compile time after dependency changes.
28+
- **`husky-check`** script wires Husky for pre-commit hooks when used.
29+
30+
### CI
31+
32+
- Workflows under **`.github/workflows/`** include npm publish, CodeQL, SCA, policy scans, and link checks.

‎skills/javascript/SKILL.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
name: javascript
3+
description: Use for Webpack configs, multi-target dist outputs, and Babel/loader setup in contentstack-javascript.
4+
---
5+
6+
# JavaScript tooling – contentstack-javascript
7+
8+
## When to use
9+
10+
- Editing **`webpack/*.js`** or changing how `src` is bundled per platform
11+
- Debugging path or env differences between **node**, **web**, **react-native**, and **nativescript** builds
12+
13+
## Instructions
14+
15+
### Webpack
16+
17+
- 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.
18+
19+
### Outputs
20+
21+
- Artifacts land under **`dist/`**—verify **`package.json`** `main` / `browser` / `react-native` fields after changing filenames or folders.
22+
23+
### Types
24+
25+
- **`index.d.ts`** ships typings—update when public JS exports or options change.

‎skills/testing/SKILL.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: testing
3+
description: Use for Jest e2e and TypeScript test suites, jest configs, and test layout in contentstack-javascript.
4+
---
5+
6+
# Testing – contentstack-javascript
7+
8+
## When to use
9+
10+
- Adding tests under **`test/`** or adjusting **`jest.js.config.js`** / **`jest.config.js`**
11+
- Debugging failures that only appear after **`pretest` / build**
12+
13+
## Instructions
14+
15+
### Suites
16+
17+
- **`npm run test:e2e`** — Jest with **`jest.js.config.js`**.
18+
- **`npm run test:typescript`** — Jest with **`jest.config.js`**, limited to **`test/typescript`** paths.
19+
20+
### Order
21+
22+
- Full **`npm test`** runs e2e then TypeScript tests; both assume a fresh **`build`** (via **`pretest`**).
23+
24+
### Hygiene
25+
26+
- Do not commit stack secrets; use fixtures or env patterns documented for this repo.

0 commit comments

Comments
 (0)