From 68134771099f98402b068e372c92a24ac6b5df3d Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Fri, 17 Apr 2026 12:37:35 +0530 Subject: [PATCH] docs(DX-6049): add AGENTS.md, skills, and Cursor rules entry --- .cursor/rules/README.md | 38 +------- .cursor/rules/code-review.mdc | 27 ------ .../contentstack-delivery-typescript.mdc | 33 ------- .cursor/rules/dev-workflow.md | 26 ------ .cursor/rules/testing.mdc | 37 -------- .cursor/rules/typescript.mdc | 34 ------- AGENTS.md | 92 ++++++++----------- skills/README.md | 10 -- skills/code-review/SKILL.md | 30 +++--- .../contentstack-delivery-typescript/SKILL.md | 35 +++---- skills/dev-workflow/SKILL.md | 30 ++++++ skills/framework/SKILL.md | 26 +++--- skills/testing/SKILL.md | 37 +++----- skills/typescript/SKILL.md | 22 +++++ 14 files changed, 155 insertions(+), 322 deletions(-) delete mode 100644 .cursor/rules/code-review.mdc delete mode 100644 .cursor/rules/contentstack-delivery-typescript.mdc delete mode 100644 .cursor/rules/dev-workflow.md delete mode 100644 .cursor/rules/testing.mdc delete mode 100644 .cursor/rules/typescript.mdc delete mode 100644 skills/README.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/typescript/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md index 763af30..f5c1f87 100644 --- a/.cursor/rules/README.md +++ b/.cursor/rules/README.md @@ -1,37 +1,5 @@ -# Cursor Rules — `@contentstack/delivery-sdk` +# Cursor (optional) -Rules for **contentstack-typescript**: TypeScript **CDA** SDK built on **`@contentstack/core`**. +**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, build, tests (`unit` / `api` / `browser`), e2e | -| [`typescript.mdc`](typescript.mdc) | TS conventions, `src/`, `config/` | -| [`contentstack-delivery-typescript.mdc`](contentstack-delivery-typescript.mdc) | **stack**, queries, cache, live preview, **core** integration | -| [`testing.mdc`](testing.mdc) | Jest suites, **jest.setup.ts**, env, Playwright | -| [`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` | -| **`src/`** | `typescript.mdc` + `contentstack-delivery-typescript.mdc` | -| **`test/**`** | `testing.mdc` | -| **Rollup / TS config** | `typescript.mdc` | - -## Quick reference - -| File | `alwaysApply` | Globs (summary) | -|------|---------------|-----------------| -| `dev-workflow.md` | no | `**/*.ts`, `**/*.mjs`, `**/*.json` | -| `typescript.mdc` | no | `src/**/*.ts`, `config/**/*.ts`, `jest.config.ts`, `jest.config.browser.ts`, `jest.setup.ts` | -| `contentstack-delivery-typescript.mdc` | no | `src/**/*.ts` | -| `testing.mdc` | no | `test/**/*.ts`, `playwright.config.ts` | -| `code-review.mdc` | **yes** | — | - -## Skills - -- [`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/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc deleted file mode 100644 index 96b501d..0000000 --- a/.cursor/rules/code-review.mdc +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "PR checklist for @contentstack/delivery-sdk — API, types, core bump, tests" -alwaysApply: true ---- - -# Code review — `@contentstack/delivery-sdk` - -## Public API - -- **Exported** `stack`, **Stack**, query/entry/asset types match **README** and **`.d.ts`** output in **`dist/modern/`**. -- **JSDoc** on **`stack()`** and key public methods when behavior or options change. - -## Compatibility - -- Avoid breaking **StackConfig** or method chains without semver strategy; document migration for breaking changes. - -## Core / deps - -- **`@contentstack/core`** version changes: verify interceptors, errors, and **httpClient** options in **`contentstack.ts`**. - -## Tests - -- **Unit** coverage for new logic; **API** updates when CDA request/response behavior changes; **browser** if bundling or globals affected. - -## Security - -- No hardcoded tokens; no logging secrets in new code. diff --git a/.cursor/rules/contentstack-delivery-typescript.mdc b/.cursor/rules/contentstack-delivery-typescript.mdc deleted file mode 100644 index 3273ead..0000000 --- a/.cursor/rules/contentstack-delivery-typescript.mdc +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: "CDA Delivery SDK — stack, queries, cache, live preview, @contentstack/core" -globs: ["src/**/*.ts"] -alwaysApply: false ---- - -# Contentstack TypeScript Delivery SDK (`src/`) - -## Stack entry - -- **`stack(config: StackConfig)`** in **`src/stack/contentstack.ts`** resolves **region → host** (`getHostforRegion`), merges **live_preview**, builds the Axios stack via **`httpClient`** + **`retryRequestHandler`** / **`retryResponseHandler`** / **`retryResponseErrorHandler`**, and returns **`Stack`**. - -## Features - -- **Queries** — **`src/query/*`**: base query, entry/asset/taxonomy/content-type/global-field queryables; chain methods match CDA query parameters. -- **Cache** — **`src/cache`** + **`Policy`** on **StackConfig**; persistence plugins may be documented as optional packages in JSDoc. -- **Sync** — **`src/sync/synchronization.ts`** for sync token workflows. - -## Live preview - -- **StackConfig.live_preview** — **enable**, **preview_token**, **host**, etc.; keep behavior aligned with tests under **`test/api/live-preview*.spec.ts`**. - -## Plugins - -- **ContentstackPlugin** interceptors should follow existing **preRequest**/**onData** patterns in **Stack** if extending. - -## Core alignment - -- HTTP defaults (**timeout**, retries, headers) must stay consistent with **`@contentstack/core`** capabilities; avoid duplicating retry logic that belongs in **core**. - -## Docs - -- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md deleted file mode 100644 index 95be5bf..0000000 --- a/.cursor/rules/dev-workflow.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: "Branches, build, and test matrix for contentstack-typescript" -globs: ["**/*.ts", "**/*.mjs", "**/*.json"] -alwaysApply: false ---- - -# Development workflow — `@contentstack/delivery-sdk` - -## Before a PR - -1. **`npm run build`** — Rollup + type declarations succeed. -2. **`npm run test:unit`** — required baseline. -3. **API tests** — `npm run test:api` when your change affects live CDA behavior; configure **`.env`** per **`test/utils/stack-instance.ts`**. Never commit tokens. -4. **Browser / e2e** — run when changing bundling, globals, or browser-specific code (`npm run test:browser`, `npm run test:e2e` as needed). - -## Dependency on core - -- Bumps to **`@contentstack/core`** may require alignment of **httpClient** options, interceptors, or error types. Verify **`stack/contentstack.ts`** and retry/plugin code after core upgrades. - -## Versioning - -- Update **`package.json` `version`** per semver for user-visible SDK changes. - -## Links - -- [`AGENTS.md`](../../AGENTS.md) · [`skills/contentstack-delivery-typescript/SKILL.md`](../../skills/contentstack-delivery-typescript/SKILL.md) diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc deleted file mode 100644 index ed3f073..0000000 --- a/.cursor/rules/testing.mdc +++ /dev/null @@ -1,37 +0,0 @@ ---- -description: "Jest unit/api/browser tests and Playwright e2e for delivery-sdk" -globs: - - "test/**/*.ts" - - "playwright.config.ts" -alwaysApply: false ---- - -# Testing — `@contentstack/delivery-sdk` - -## Jest - -| Suite | Path | Notes | -|-------|------|--------| -| **Unit** | `test/unit/**/*.spec.ts` | Mocked / fast; `npm run test:unit` | -| **API** | `test/api/**/*.spec.ts` | Real stack — **`.env`** via **`test/utils/stack-instance.ts`** | -| **Browser** | `test/browser/**/*.spec.ts` | `jest.config.browser.ts` | - -- **`jest.setup.ts`** — console capture, suppression of **expected** validation error noise; do not weaken checks for real failures. - -## Env (`test/api` and helpers) - -Required for **`stackInstance()`**: - -- **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`** - -Optional: - -- **`PREVIEW_TOKEN`**, **`LIVE_PREVIEW_HOST`** - -## E2E - -- **`npm run test:e2e`** — builds browser bundle then **Playwright** (`test/e2e`, `playwright.config.ts`). - -## Hygiene - -- No permanent **`test.only`** in CI paths; long-running API suites may use **`testTimeout`** in Jest config (`maxWorkers: 1` is intentional). diff --git a/.cursor/rules/typescript.mdc b/.cursor/rules/typescript.mdc deleted file mode 100644 index a60d0a0..0000000 --- a/.cursor/rules/typescript.mdc +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: "TypeScript conventions for the Delivery SDK src and tooling" -globs: - - "src/**/*.ts" - - "config/**/*.ts" - - "jest.config.ts" - - "jest.config.browser.ts" - - "jest.setup.ts" - - "jest.setup.browser.ts" - - "rollup.config.js" -alwaysApply: false ---- - -# TypeScript — `@contentstack/delivery-sdk` - -## Layout - -- **`src/stack/`** — **`stack()`** factory and **Stack** implementation. -- **`src/query/`**, **`src/entries/`**, **`src/assets/`**, **`src/sync/`**, **`src/cache/`** — feature modules. -- **`src/common/types.ts`** — **`StackConfig`**, **Region**, plugins, cache policies, etc. - -## Style - -- Follow **`.eslintrc.json`** and existing naming (including eslint disables only where already established, e.g. **stack** factory export). - -## Imports - -- **`@contentstack/core`** — **`httpClient`**, retry handlers. -- **`@contentstack/utils`** — re-exported from **`contentstack.ts`** where applicable. -- **`axios`** types for headers where needed. - -## Security - -- Do not log **delivery tokens**, **preview tokens**, or **api keys**; use existing error and debug patterns. diff --git a/AGENTS.md b/AGENTS.md index a1fe6f5..49e8146 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,59 +1,45 @@ -# AGENTS.md — AI / automation context +# Contentstack TypeScript Delivery SDK – Agent guide -## Project +**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**. -| | | -|---|---| -| **Name** | **`@contentstack/delivery-sdk`** (npm) — **Contentstack TypeScript Content Delivery SDK** | -| **Purpose** | TypeScript client for the **Content Delivery API (CDA)**: stacks, entries, assets, queries, sync, live preview, cache. Built on **`@contentstack/core`** (**Axios** HTTP + retry helpers) and **`@contentstack/utils`**. | -| **Repository** | [contentstack/contentstack-typescript](https://github.com/contentstack/contentstack-typescript.git) | +## What this repo is -## Tech stack +| Field | Detail | +|--------|--------| +| **Name:** | [contentstack-typescript](https://github.com/contentstack/contentstack-typescript) (`@contentstack/delivery-sdk`) | +| **Purpose:** | TypeScript/JavaScript Content Delivery SDK for fetching and working with stack content in Node and browsers. | +| **Out of scope:** | Not the Management API or CLI; use the appropriate Contentstack tools for non-delivery workflows. | + +## Tech stack (at a glance) | Area | Details | |------|---------| -| **Language** | **TypeScript**, **ES modules** (`"type": "module"`) | -| **Runtime** | Node **>= 18** (`package.json` `engines`) | -| **Build** | **Rollup** (`npm run build:rollup`) + **`tsc`** declarations (`config/tsconfig.decl-esm.json`) → **`dist/modern/`** | -| **Tests** | **Jest** + **ts-jest**: **`test/unit`**, **`test/api`**, **`test/browser`**; **Playwright** e2e (`test/e2e`, `npm run test:e2e`) | -| **Lint** | **ESLint** (`.eslintrc.json`) | - -## Source layout - -| Path | Role | -|------|------| -| `src/stack/contentstack.ts` | **`stack(config)`** factory — wires **`httpClient`** from **`@contentstack/core`**, region/host, live preview | -| `src/stack/stack.ts` | **Stack** class | -| `src/query/**` | Queries (entry, asset, taxonomy, content type, …) | -| `src/entries/**`, `src/assets/**`, `src/sync/**`, `src/cache/**` | Domain modules | -| `src/common/**` | Types, utils, errors, pagination | -| `src/index.ts` | Public package exports | -| `test/utils/stack-instance.ts` | **`stackInstance()`** — loads **dotenv**, **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`**, optional live-preview vars | - -## Common commands - -```bash -npm install -npm run build -npm run test:unit # jest ./test/unit -npm run test:api # live API — needs .env (see stack-instance) -npm run test:browser -npm run test:e2e # Playwright (builds browser bundle first) -npm run test:all # unit + browser + api -``` - -## Environment variables (API / integration tests) - -Loaded via **`dotenv`** in **`test/utils/stack-instance.ts`**: - -- **`HOST`**, **`API_KEY`**, **`DELIVERY_TOKEN`**, **`ENVIRONMENT`** — stack connection -- Optional: **`PREVIEW_TOKEN`**, **`LIVE_PREVIEW_HOST`** for live preview tests - -Do not commit secrets. - -## Further guidance - -- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md) -- **Skills:** [`skills/README.md`](skills/README.md) - -Product docs: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/). +| Language | TypeScript (`typescript` in `package.json`); Node **≥ 18** | +| Build | Rollup (`rollup -c`), declaration emit (`config/tsconfig.decl-esm.json`) → `dist/modern/` | +| Tests | Jest: `test/unit`, `test/api`, browser config; Playwright for e2e (`test/e2e`); bundler smoke tests under `test/bundlers/` | +| Lint / coverage | No root `lint` script—use `npm run validate:all` and `.github/workflows/coverage-check.yml` for quality gates | +| CI | `.github/workflows/coverage-check.yml`, `check-branch.yml`, `sca-scan.yml`, `policy-scan.yml`, `npm-publish.yml` | + +## Commands (quick reference) + +| Command type | Command | +|--------------|---------| +| Build | `npm run build` | +| Test (common) | `npm run test:unit` / `npm run test:api` / `npm run test:all` | +| Validate | `npm run validate:all` | +| Full CI-style suite | `npm run test:cicd` or `npm run test:cicd:no-browser` (see `package.json`) | + +## 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, prerelease | +| **Delivery SDK** | [`skills/contentstack-delivery-typescript/SKILL.md`](skills/contentstack-delivery-typescript/SKILL.md) | Public API, stack client, `@contentstack/core` usage | +| **TypeScript & layout** | [`skills/typescript/SKILL.md`](skills/typescript/SKILL.md) | `src/`, Rollup outputs, modern CJS/ESM | +| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Jest, API tests, Playwright, bundler matrix | +| **Build & platform** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | Rollup, browser safety, bundler validation | +| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist for SDK changes | + +## 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/README.md b/skills/README.md deleted file mode 100644 index 7e2aeb3..0000000 --- a/skills/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Project skills — `@contentstack/delivery-sdk` - -| Skill | When to use | -|-------|-------------| -| [`code-review/`](code-review/SKILL.md) | PR review, semver, core dependency bumps | -| [`testing/`](testing/SKILL.md) | Unit vs API vs browser vs Playwright | -| [`contentstack-delivery-typescript/`](contentstack-delivery-typescript/SKILL.md) | **stack**, Stack class, queries, sync, cache | -| [`framework/`](framework/SKILL.md) | **@contentstack/core** HTTP + retries on the stack | - -**Overview:** [`AGENTS.md`](../AGENTS.md) · **Rules:** [`.cursor/rules/README.md`](../.cursor/rules/README.md) diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 2cda34c..d48c852 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,19 +1,27 @@ --- name: code-review -description: PR review for @contentstack/delivery-sdk — public API, StackConfig, core alignment, tests. +description: Use when reviewing PRs for the TypeScript Delivery SDK—API, tests, bundler impact, semver. --- -# Code review — `@contentstack/delivery-sdk` +# Code review – contentstack-typescript -## Checklist +## When to use -- [ ] **API:** New or changed **`stack()`** / **Stack** / query methods documented; exports updated in **`src/index.ts`**. -- [ ] **Types:** **StackConfig** and public interfaces remain consistent with **`dist/modern/*.d.ts`** after build. -- [ ] **@contentstack/core:** Version or API changes validated in **`src/stack/contentstack.ts`** (interceptors, **httpClient** options). -- [ ] **Tests:** **`test:unit`** passes; add/extend **`test/api`** when integration behavior changes; browser/e2e if relevant. -- [ ] **Secrets:** No tokens in repo; **stack-instance** env vars only for local CI secrets store. +- Reviewing SDK features, fixes, or dependency upgrades +- Assessing risk of a change to browser/Node consumers -## References +## Instructions -- `.cursor/rules/code-review.mdc` -- `.cursor/rules/dev-workflow.md` +### Checklist + +- **Semver**: Public API or default behavior change flagged for major/minor/patch appropriately. +- **Core/utils**: Coordinated version bumps for `@contentstack/core` and `@contentstack/utils` when needed. +- **Tests**: Unit + relevant API/browser/bundler coverage for the change. +- **Build**: `npm run build` succeeds; consider `npm run validate:all` for packaging-sensitive edits. +- **Docs**: README or type docs updated for user-visible changes. + +### Severity hints + +- **Blocker**: Broken `exports`, failing CI, or security issues in dependencies. +- **Major**: Missing tests for cross-bundler or browser regressions. +- **Minor**: Internal refactors with full green matrix. diff --git a/skills/contentstack-delivery-typescript/SKILL.md b/skills/contentstack-delivery-typescript/SKILL.md index 03ad66c..1ce2fb0 100644 --- a/skills/contentstack-delivery-typescript/SKILL.md +++ b/skills/contentstack-delivery-typescript/SKILL.md @@ -1,35 +1,26 @@ --- name: contentstack-delivery-typescript -description: @contentstack/delivery-sdk — TypeScript CDA client, stack factory, queries, sync, cache, live preview. +description: Use for the public Delivery SDK API, stack initialization, and integration with @contentstack/core and utils. --- -# Contentstack TypeScript Delivery SDK skill +# Contentstack Delivery SDK – contentstack-typescript -## Entry +## When to use -- **`contentstack.stack(config)`** — **`src/stack/contentstack.ts`**: merges **StackConfig**, resolves **Region** → host, attaches **@contentstack/core** **`httpClient`** with retry handlers, returns **`Stack`**. +- Changing how consumers initialize the SDK or call stack APIs +- Updating dependencies on `@contentstack/core` or `@contentstack/utils` -## Structure +## Instructions -- **`Stack`** — **`src/stack/stack.ts`**: content types, entries, assets, sync, taxonomy helpers. -- **Queries** — **`src/query/`**: **BaseQuery**, **Query**, **AssetQuery**, **TaxonomyQuery**, **ContentTypeQuery**, **GlobalFieldQuery**, **EntryQueryable**, etc. -- **Sync** — **`src/sync/`** -- **Cache** — **`src/cache/`** + **Policy** enum in types. +### Package identity -## Extending +- Published as **`@contentstack/delivery-sdk`**; entry is built into **`dist/modern/`** with dual CJS/ESM typings (`package.json` `exports`). -- Add query methods on the appropriate class; keep param names aligned with **CDA** query docs. -- Prefer delegating transport concerns to **core** rather than duplicating Axios logic. +### Design constraints -## Consumer packages +- Preserve backward compatibility for public imports and options unless shipping a **semver major**. +- HTTP and low-level client behavior often delegate to **`@contentstack/core`**—avoid duplicating retry or error logic; extend in one place when possible. -- **`@contentstack/core`** — HTTP + retries -- **`@contentstack/utils`** — utilities; re-exported where documented. +### Documentation -## Docs - -- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) - -## Rule shortcut - -- `.cursor/rules/contentstack-delivery-typescript.mdc` +- User-facing behavior belongs in **`README.md`** and official Contentstack docs; keep code samples accurate when changing APIs. diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..7fc418b --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,30 @@ +--- +name: dev-workflow +description: Use for branches, CI, npm scripts, and release flow in contentstack-typescript. +--- + +# Development workflow – contentstack-typescript + +## When to use + +- Choosing which test target to run locally +- Aligning a PR with GitHub Actions (coverage, branch checks, publish) + +## Instructions + +### Branches + +- Default branch is **`main`**; feature work typically merges via PR with required checks. + +### Key commands + +- `npm run build` — produce `dist/modern/` artifacts. +- `npm run test:unit` — fast unit tests. +- `npm run test:api` — API-level Jest tests (may need env; see repo docs). +- `npm run test:all` — unit + browser + API (heavy). +- `npm run validate:all` — browser-safe + bundler validation before release-style work. +- `npm run prerelease` — `test:all` + `validate:all` per `package.json`. + +### CI + +- Workflows under `.github/workflows/` include coverage checks and policy/SCA—keep local runs close to what CI executes for risky changes. diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md index a0015d7..72f620d 100644 --- a/skills/framework/SKILL.md +++ b/skills/framework/SKILL.md @@ -1,23 +1,27 @@ --- name: framework -description: HTTP and retry integration — @contentstack/core with httpClient on the Delivery SDK stack. +description: Use for Rollup build, browser-safe validation, and bundler compatibility in contentstack-typescript. --- -# Framework skill — `@contentstack/core` + Delivery SDK +# Build & platform – contentstack-typescript -## Integration point +## When to use -- **`src/stack/contentstack.ts`** imports **`httpClient`**, **`retryRequestHandler`**, **`retryResponseErrorHandler`**, **`retryResponseHandler`** from **`@contentstack/core`** and composes them with stack-specific **headers**, **live_preview**, and **cache**-related request handling (**`handleRequest`**). +- Changing Rollup plugins, bundle splits, or `dist/` layout +- Debugging issues specific to browser, Next.js, Vite, or other bundlers -## When to change +## Instructions -- **Retry behavior** shared across Contentstack TS clients → prefer **`@contentstack/core`** (**contentstack-js-core** repo) if appropriate; otherwise document SDK-only overrides here. -- **Base URL / region** — **`getHostforRegion`** and **StackConfig.host** in **`src/common/utils.ts`** (verify imports from current **`contentstack.ts`**). +### Rollup -## Testing +- Production build: `npm run build:rollup` (high Node memory options may apply—see `package.json`). +- Declaration files: `npm run build:types` (`tsc` with `config/tsconfig.decl-esm.json`). -- **Unit** — mock HTTP layers; **API** — full stack via **`stackInstance()`**. +### Browser and bundlers -## Rule shortcut +- `npm run validate:browser` checks browser-safe assumptions. +- `test/bundlers/` validates multiple toolchains—run `./validate-all.sh` or `npm run validate:bundlers` after dependency or export map changes. -- `.cursor/rules/contentstack-delivery-typescript.mdc` +### Outputs + +- Consumers import from **`@contentstack/delivery-sdk`**—verify both `import` and `require` paths after changing `exports`. diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md index 38bbb18..4def5a7 100644 --- a/skills/testing/SKILL.md +++ b/skills/testing/SKILL.md @@ -1,34 +1,25 @@ --- name: testing -description: Jest unit/api/browser and Playwright e2e for @contentstack/delivery-sdk. +description: Use for Jest, Playwright e2e, API tests, and bundler smoke tests in contentstack-typescript. --- -# Testing — `@contentstack/delivery-sdk` +# Testing – contentstack-typescript -## Commands +## When to use -| Goal | Command | -|------|---------| -| Unit | `npm run test:unit` | -| API (live stack) | `npm run test:api` | -| Browser | `npm run test:browser` | -| All three | `npm run test:all` | -| E2E | `npm run test:e2e` | -| CI-style matrix | `npm run test:cicd` (includes reports + browser tests) | +- Adding or fixing tests under `test/unit`, `test/api`, or browser/e2e flows +- Investigating failures in `test/bundlers` or Playwright -## Environment +## Instructions -See **`test/utils/stack-instance.ts`**: +### Layers -- **Required:** `HOST`, `API_KEY`, `DELIVERY_TOKEN`, `ENVIRONMENT` -- **Optional:** `PREVIEW_TOKEN`, `LIVE_PREVIEW_HOST` +- **Unit**: `npm run test:unit` → `jest ./test/unit`. +- **API**: `npm run test:api` — may require stack credentials via env files (see project docs and `.gitignore`). +- **Browser**: `npm run test:browser` uses a dedicated Jest config. +- **E2E**: `npm run test:e2e` builds a browser bundle then runs Playwright—slower; run before large release changes. +- **Bundlers**: `test/bundlers/` exercises webpack/vite/rollup/next/esbuild—run `npm run validate:bundlers` when changing packaging. -Use a **`.env`** at repo root for local API runs. +### Hygiene -## Setup - -- **`jest.setup.ts`** — global hooks and expected-error suppression; read before changing console behavior. - -## References - -- `.cursor/rules/testing.mdc` +- Do not commit secrets or live tokens; use fixtures or CI secrets only where documented. diff --git a/skills/typescript/SKILL.md b/skills/typescript/SKILL.md new file mode 100644 index 0000000..ddacabc --- /dev/null +++ b/skills/typescript/SKILL.md @@ -0,0 +1,22 @@ +--- +name: typescript +description: Use for TypeScript source layout, Rollup build, and dist outputs in contentstack-typescript. +--- + +# TypeScript & layout – contentstack-typescript + +## When to use + +- Editing `src/` modules or `config/tsconfig.decl-esm.json` +- Debugging ESM vs CJS consumption issues + +## Instructions + +### Structure + +- Application source under **`src/`**; Rollup config at repo root (`rollup` `-c`). +- Types and JS emit land under **`dist/modern/`**—do not hand-edit generated files. + +### Node version + +- **`engines.node`** requires **≥ 18**—use the same for local development to avoid subtle test or tooling differences.