From fe1f35e7a73d6d3ea9d53a6a3903ddf0ac2e7afb Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Fri, 17 Apr 2026 12:37:35 +0530 Subject: [PATCH] docs(DX-6051): add AGENTS.md, skills, and Cursor rules entry --- .cursor/rules/README.md | 5 ++++ AGENTS.md | 43 +++++++++++++++++++++++++++++++ skills/code-review/SKILL.md | 27 +++++++++++++++++++ skills/contentstack-core/SKILL.md | 28 ++++++++++++++++++++ skills/dev-workflow/SKILL.md | 31 ++++++++++++++++++++++ skills/testing/SKILL.md | 23 +++++++++++++++++ skills/typescript/SKILL.md | 24 +++++++++++++++++ 7 files changed, 181 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-core/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/testing/SKILL.md create mode 100644 skills/typescript/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..f5c1f87 --- /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 0000000..3d608c6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,43 @@ +# @contentstack/core – 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-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 (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. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..a4dbaa9 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,27 @@ +--- +name: code-review +description: Use when reviewing PRs or preparing changes for contentstack-js-core—API stability, tests, and consumer impact. +--- + +# Code review – contentstack-js-core + +## When to use + +- Authoring or reviewing a PR +- Judging whether a change is safe for downstream SDKs + +## Instructions + +### 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. diff --git a/skills/contentstack-core/SKILL.md b/skills/contentstack-core/SKILL.md new file mode 100644 index 0000000..1d07a9d --- /dev/null +++ b/skills/contentstack-core/SKILL.md @@ -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. diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..2bc47c9 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -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. diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..1b5d865 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,23 @@ +--- +name: testing +description: Use when writing or fixing Jest tests, mocks, or test layout under test/ in contentstack-js-core. +--- + +# Testing – contentstack-js-core + +## When to use + +- Adding coverage for new `src/` behavior +- Fixing flaky or outdated tests under `test/` + +## Instructions + +### Runner and layout + +- **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. + +### Practice + +- 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. diff --git a/skills/typescript/SKILL.md b/skills/typescript/SKILL.md new file mode 100644 index 0000000..86eedba --- /dev/null +++ b/skills/typescript/SKILL.md @@ -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.