diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md index eb55a55..f5c1f87 100644 --- a/.cursor/rules/README.md +++ b/.cursor/rules/README.md @@ -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. diff --git a/AGENTS.md b/AGENTS.md index 2085f30..3d608c6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 999d6b4..a4dbaa9 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -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. 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 index e9f6bc2..1b5d865 100644 --- a/skills/testing/SKILL.md +++ b/skills/testing/SKILL.md @@ -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. 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.