From d2680627dabbef96d91f5cd461e45f46abf2f0b2 Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Fri, 17 Apr 2026 12:37:36 +0530 Subject: [PATCH] docs: add AGENTS.md, skills, and Cursor rules entry --- .cursor/rules/README.md | 5 +++ AGENTS.md | 43 +++++++++++++++++++++ skills/code-review/SKILL.md | 27 +++++++++++++ skills/contentstack-javascript-sdk/SKILL.md | 26 +++++++++++++ skills/dev-workflow/SKILL.md | 32 +++++++++++++++ skills/javascript/SKILL.md | 25 ++++++++++++ skills/testing/SKILL.md | 26 +++++++++++++ 7 files changed, 184 insertions(+) create mode 100644 .cursor/rules/README.md create mode 100644 AGENTS.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/contentstack-javascript-sdk/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/javascript/SKILL.md create mode 100644 skills/testing/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 00000000..f5c1f870 --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,5 @@ +# Cursor (optional) + +**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**. + +This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..4db6094f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,43 @@ +# Contentstack JavaScript Delivery SDK – Agent guide + +**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**. + +## What this repo is + +| 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 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. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 00000000..6b31d3ae --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,27 @@ +--- +name: code-review +description: Use when reviewing PRs for contentstack-javascript—API compatibility, bundles, Jest, and npm/CDN impact. +--- + +# Code review – contentstack-javascript + +## When to use + +- Reviewing SDK or Webpack changes +- Assessing dependency bumps (`@contentstack/utils`, Babel, Webpack, Jest) + +## Instructions + +### Checklist + +- **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. + +### Severity hints + +- **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. diff --git a/skills/contentstack-javascript-sdk/SKILL.md b/skills/contentstack-javascript-sdk/SKILL.md new file mode 100644 index 00000000..c8dcdf55 --- /dev/null +++ b/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. diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 00000000..c187fd96 --- /dev/null +++ b/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. diff --git a/skills/javascript/SKILL.md b/skills/javascript/SKILL.md new file mode 100644 index 00000000..cd288ab3 --- /dev/null +++ b/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. diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 00000000..00623f86 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,26 @@ +--- +name: testing +description: Use for Jest e2e and TypeScript test suites, jest configs, and test layout in contentstack-javascript. +--- + +# Testing – contentstack-javascript + +## When to use + +- Adding tests under **`test/`** or adjusting **`jest.js.config.js`** / **`jest.config.js`** +- Debugging failures that only appear after **`pretest` / build** + +## Instructions + +### Suites + +- **`npm run test:e2e`** — Jest with **`jest.js.config.js`**. +- **`npm run test:typescript`** — Jest with **`jest.config.js`**, limited to **`test/typescript`** paths. + +### Order + +- Full **`npm test`** runs e2e then TypeScript tests; both assume a fresh **`build`** (via **`pretest`**). + +### Hygiene + +- Do not commit stack secrets; use fixtures or env patterns documented for this repo.