contentstack · naman-contentstack · Mar 24, 2026 · Mar 23, 2026
@@ -0,0 +1,19 @@
+# Cursor rules for `@contentstack/types-generator`
+
+This folder contains project-specific rules for AI assistants and developers. Each file lists its scope in YAML frontmatter (`description`, `globs`, `alwaysApply`).
+
+
+| Rule file                                                      | `alwaysApply` | Globs                                                   | When it applies                                                   | Related skill                                                                  |
+| -------------------------------------------------------------- | ------------- | ------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| [dev-workflow.mdc](dev-workflow.mdc)                           | No            | `package.json`, `package-lock.json`, `.github/workflows/**/*`, `jest.config.js`, `tsup.config.ts`, `AGENTS.md` | Branch strategy, build/test commands, PR and release expectations | [testing](../../skills/testing/SKILL.md), [code-review](../../skills/code-review/SKILL.md) |
+| [typescript.mdc](typescript.mdc)                               | No            | `src/**/*.ts`, `tests/**/*.ts`                          | Editing or adding TypeScript in this package                      | [typescript-types-generator](../../skills/typescript-types-generator/SKILL.md) |
+| [contentstack-delivery-cda.mdc](contentstack-delivery-cda.mdc) | No            | `src/sdk/**`, `src/generateTS/**`, `src/graphqlTS/**`   | Delivery SDK, regions, stack config, GraphQL introspection/axios  | [typescript-types-generator](../../skills/typescript-types-generator/SKILL.md) |
+| [testing.mdc](testing.mdc)                                     | No            | `tests/**`, `jest.config.js`                            | Writing or running Jest tests, env for live tests                 | [testing](../../skills/testing/SKILL.md)                                       |
+| [code-review.mdc](code-review.mdc)                             | **Yes**       | —                                                       | Every change: API docs, compatibility, errors, security, tests    | [code-review](../../skills/code-review/SKILL.md)                               |
+
+
+## Referencing rules in Cursor
+
+- Use **@** in chat and pick a rule file (e.g. `@contentstack-delivery-cda`, `@dev-workflow`) to focus the model on Delivery/GraphQL or workflow context.
+- Rules with `alwaysApply: true` are included automatically; others apply when matching files are in context or when @-mentioned.
+
@@ -0,0 +1,29 @@
+---
+description: PR and change review checklist for types-generator
+alwaysApply: true
+---
+
+# Code review checklist
+
+Use this for every change. Severity labels are optional (**Blocker** / **Major** / **Minor**).
+
+## API and documentation
+
+- **Public API:** New or changed exports need **JSDoc** (or equivalent) where the package documents behavior; keep examples accurate.
+- **Terminology:** Use **CDA / Delivery** and **GraphQL** as in this codebase. **Do not** describe this library as CMA or Management-API–centric.
+
+## Compatibility
+
+- **Backward compatibility:** Avoid breaking changes to function signatures, error shapes, and generated output format unless versioned or documented.
+- **Errors:** Align with existing patterns: **`type: "validation"`** and related helpers in `generateTS` / `graphqlTS`; do not silently swallow SDK or network errors.
+
+## Correctness and safety
+
+- **Null safety:** Respect **`strictNullChecks`**; guard optional stack config (`host`, `branch`, etc.).
+- **Dependencies:** New dependencies need justification; watch license and footprint. **SCA:** `.github/workflows/sca-scan.yml` runs Snyk and `contentstack/sca-policy` on PRs.
+
+## Tests
+
+- **Unit:** Add or update tests under **`tests/unit/`** for logic changes.
+- **Integration / sanity:** Touch **`tests/integration/`** when behavior depends on live APIs; document required env vars.
+- **Coverage:** CI uses **`test:unit:report:json`**; keep meaningful coverage for new code paths.
@@ -0,0 +1,25 @@
+---
+description: Contentstack Delivery (CDA) SDK and GraphQL usage in types-generator
+globs:
+  - src/sdk/**
+  - src/generateTS/**
+  - src/graphqlTS/**
+---
+
+# Contentstack Delivery and GraphQL (this repo)
+
+Scope: **SDK-facing library code only** (no separate `samples/` tree). This package is **not** a CMA (Management) client.
+
+## Delivery / CDA
+
+- **Token type:** Only **`TOKEN_TYPE.DELIVERY`** is defined ([`src/constants/index.ts`](src/constants/index.ts)). `generateTS` validates `tokenType` and uses the **Delivery SDK** for content types and global fields.
+- **SDK entry:** [`initializeContentstackSdk`](src/sdk/utils.ts) wraps **`@contentstack/delivery-sdk`** (`Contentstack.stack` with `deliveryToken`, `environment`, `region` or `host`, optional `branch`).
+- **Regions:** Map string constants in **`REGIONS`** to **`Region`** enum; **custom** regions require **`host`** (see `isCustomRegion` branch in [`src/sdk/utils.ts`](src/sdk/utils.ts)).
+- **Errors:** Validation failures often use **`{ type: "validation", error_message: string }`** or helpers from [`generateTS/shared/utils`](src/generateTS/shared/utils.ts). Preserve stable `type` / message shapes for callers.
+
+## GraphQL
+
+- **Transport:** **`graphqlTS`** uses **`axios`** POST to region-specific GraphQL URLs or to **`https://${host}/...`** when `host` is set ([`src/graphqlTS/index.ts`](src/graphqlTS/index.ts)).
+- **Schema:** Introspection query + **`@gql2ts/from-schema`** (`schemaToInterfaces`, `generateNamespace`). Align URL and headers (`access_token`, `branch`) with Contentstack GraphQL documentation for the target region.
+
+When unsure, prefer official **Content Delivery API** / **GraphQL** docs—not Management API patterns.
@@ -0,0 +1,38 @@
+---
+description: Branches, build/test commands, PR and release workflow for types-generator
+alwaysApply: false
+globs:
+  - package.json
+  - package-lock.json
+  - .github/workflows/**/*
+  - jest.config.js
+  - tsup.config.ts
+  - AGENTS.md
+---
+
+# Development workflow
+
+For deeper detail, see **[skills/testing](../../skills/testing/SKILL.md)** (commands, env, fixtures) and **[skills/code-review](../../skills/code-review/SKILL.md)** (PR expectations). In chat you can also @-mention those skill folders if your workspace exposes them.
+
+## Branches
+
+- **CI (Node.js workflow)** runs on **push** and **pull_request** for branches **`master`** and **`development`** (see `.github/workflows/node.js.yml`).
+- **Release / publish** runs on **push** to **`main`** (see `.github/workflows/release.yml`), using Node **22.x**, autotag, npm publish, and GitHub release.
+
+**Maintainer note:** Default branch naming differs between CI (`master`/`development`) and release (`main`). Align branch protection and contributor docs when convenient—no change required for local development if your fork uses the upstream defaults.
+
+## Local commands
+
+- **Build:** `npm run build` (tsup; `prepare` also runs build).
+- **Test (all under `tests/`):** `npm test` (sets `NODE_OPTIONS=--experimental-vm-modules`).
+- **Unit tests + coverage (CI):** `npm run test:unit:report:json` (targets `tests/unit`, coverage and JSON artifacts).
+
+## Pull requests
+
+- Ensure **`npm run build`** and **`npm test`** pass before requesting review.
+- CI runs **`test:unit:report:json`** with secrets for integration-related env vars; PRs from forks may not have secrets—coordinate with maintainers if integration jobs fail only on secrets.
+
+## Releases
+
+- Version in **`package.json`** is the source of truth for the published package.
+- Publishing is automated from **`main`** via the release workflow (tag prefix `v`, npm publish, GitHub release). Bump version on the branch that merges to `main` per team process.
@@ -0,0 +1,18 @@
+---
+description: Jest tests, layout, and env for types-generator
+globs:
+  - tests/**
+  - jest.config.js
+---
+
+# Testing (`@contentstack/types-generator`)
+
+- **Runner:** **Jest** with **ts-jest** ([jest.config.js](jest.config.js)). **`setupFiles: ["dotenv/config"]`** loads environment variables for tests.
+- **Match:** `**/?(*.)+(spec|test).+(ts|tsx)` and `test/**/*.test.ts`.
+- **Layout:**
+  - **`tests/unit/`** — fast, isolated tests (including `tests/unit/tsgen/` with **`.ct.js`** content-type fixtures paired with **`.test.ts`** files).
+  - **`tests/integration/`** — live stack / API tests (e.g. `generateTS`, `graphqlTS`); require real credentials.
+- **Commands:**
+  - `npm test` — all tests under `tests` (via `--testPathPattern=tests`).
+  - `npm run test:unit:report:json` — unit coverage + reports for CI.
+- **Integration env:** Typically **`TOKEN`**, **`APIKEY`**, **`ENVIRONMENT`**, **`REGION`**, **`TOKENTYPE`**, **`BRANCH`**. Integration tests may load **`.env`** from the package root path (see test files). CI sets additional secrets such as **`TOKEN_WITH_NO_CT`** / **`APIKEY_WITH_NO_CT`** where needed.
@@ -0,0 +1,14 @@
+---
+description: TypeScript layout, strict mode, and logging for types-generator
+globs:
+  - src/**/*.ts
+  - tests/**/*.ts
+---
+
+# TypeScript conventions (`@contentstack/types-generator`)
+
+- **Compiler:** TypeScript **5.9** with **`strict`**, **`noImplicitAny`**, **`strictNullChecks`** ([tsconfig.json](tsconfig.json)). Prefer explicit types at public boundaries.
+- **Layout:** Source lives under **`src/`** — `generateTS/`, `graphqlTS/`, `sdk/`, `types/`, `format/`, `logger/`, `constants/`. Tests mirror under **`tests/unit/`** and **`tests/integration/`**.
+- **Logging:** Use **`createLogger`** from [`src/logger`](src/logger/index.ts); pass optional logger instances into `generateTS` / `graphqlTS` where supported.
+- **Formatting output:** **`prettier`** is a **runtime** dependency used to format generated TypeScript strings—not only dev formatting.
+- **Linting:** This package does **not** ship an ESLint config or `lint` script; do not assume ESLint fixes are available in CI.
@@ -4,4 +4,14 @@ fileignoreconfig:
       - filecontent
   - filename: package-lock.json
     checksum: d392a5bf70cad2cb90afaf284410f580e359afe4f1a0a970a6f6061aee7c821c
+  - filename: .cursor/rules/testing.mdc
+    checksum: a3768ed70d1fa61e73d1838efbc3066859dd5dfce3fbefe40fb6c23800679a43
+  - filename: skills/README.md
+    checksum: ae09bf77a43f81f76a06f23ae2b2cbb1e81c490a66cf1b4e7df4e7142e22b5f5
+  - filename: AGENTS.md
+    checksum: 6ff4b2c6957f75f85f6afd188cc09af21ac9c90f05f87e4198674302b74bb021
+  - filename: skills/testing/SKILL.md
+    checksum: 858b4a830e74a0e90fe2f1097b4480a5eed513cdd88ba2646087399423ddee00
+  - filename: skills/typescript-types-generator/SKILL.md
+    checksum: aaa97f6eb31a66221ceedc7e5e965a9b13d33358a350dbfb3034014ece0c3e6c
 version: "1.0"
@@ -0,0 +1,49 @@
+# `@contentstack/types-generator`
+
+**Purpose:** Library for generating TypeScript type definitions from Contentstack stack content types (via the Delivery SDK) and from GraphQL schema (introspection over the Contentstack GraphQL endpoint).
+
+- **Repository:** [github.com/contentstack/types-generator](https://github.com/contentstack/types-generator)
+- **Homepage:** [https://github.com/contentstack/types-generator](https://github.com/contentstack/types-generator)
+
+## Tech stack
+
+| Area | Details |
+| --- | --- |
+| Language | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) |
+| Runtime | Node (CI on **18.x** and **20.x**; release workflow uses **22.x**) |
+| Build | **tsup** → `dist/` ([tsup.config.ts](tsup.config.ts)): entries `index` ([src/index.ts](src/index.ts)), `web` ([src/web.ts](src/web.ts)) |
+| Tests | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)); `dotenv/config` in setup |
+| Main dependencies | `@contentstack/delivery-sdk`, `axios`, `@gql2ts/from-schema`, `lodash`, `async`, `prettier` |
+
+This package targets **Content Delivery (CDA)** and **GraphQL** only—not the Management API (CMA).
+
+## Public API and source layout
+
+- **Package entry:** `main` / `module` / `types` point to `./dist/*` (see [package.json](package.json)).
+- **Exports:** `generateTS`, `graphqlTS`, and related symbols from [src/index.ts](src/index.ts) (re-exports from [src/generateTS/](src/generateTS/) and [src/graphqlTS/](src/graphqlTS/)).
+- **Key paths:** [src/sdk/](src/sdk/) (Delivery SDK wiring), [src/types/](src/types/), [src/format/](src/format/), [src/logger/](src/logger/), [src/constants/](src/constants/).
+
+## Common commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm run build` | Run `tsup` (also runs on `npm run prepare`) |
+| `npm test` | Jest with `--testPathPattern=tests` and `NODE_OPTIONS=--experimental-vm-modules` |
+| `npm run test:unit:report:json` | Unit tests under `tests/unit` with coverage and JSON reports (used in CI) |
+
+There is **no ESLint** script in this package; rely on TypeScript strictness and project conventions.
+
+## Credentials and integration tests
+
+Integration tests need a live stack. Set a **`.env`** at the repo root (see integration tests under `tests/integration/`) or export variables in your shell. Typical names:
+
+`TOKEN`, `APIKEY`, `ENVIRONMENT`, `REGION`, `TOKENTYPE`, `BRANCH`
+
+CI injects these from GitHub Actions secrets (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)), including `TOKEN_WITH_NO_CT` and `APIKEY_WITH_NO_CT` where tests require them.
+
+---
+
+## AI guidance index
+
+- [Cursor rules (overview)](.cursor/rules/README.md) — when each rule applies and how to reference it.
+- [Skills index](skills/README.md) — deeper checklists and package mental model.
@@ -0,0 +1,11 @@
+# Skills for `@contentstack/types-generator`
+
+Short index of deeper guidance (use alongside [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md)).
+
+| Skill | When to use |
+| --- | --- |
+| [code-review](code-review/SKILL.md) | Preparing or reviewing a PR: API docs, compatibility, errors, security, tests, Delivery vs Management terminology. |
+| [testing](testing/SKILL.md) | Running Jest, unit vs integration layout, `.env` and CI secrets, content-type fixtures. |
+| [typescript-types-generator](typescript-types-generator/SKILL.md) | Understanding `generateTS` vs `graphqlTS`, main modules, and where to change behavior. |
+
+There is no separate **framework** skill: HTTP/GraphQL details are covered in [contentstack-delivery-cda.mdc](../.cursor/rules/contentstack-delivery-cda.mdc) and the typescript skill.
@@ -0,0 +1,47 @@
+---
+name: code-review
+description: PR review checklist for @contentstack/types-generator (API docs, compatibility, errors, tests, CDA/GraphQL terminology).
+---
+
+# Code review skill (`@contentstack/types-generator`)
+
+Expanded checklist aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc).
+
+## Documentation and API surface
+
+- Public exports from [`src/index.ts`](../../src/index.ts) should stay coherent and documented (JSDoc on exported functions where the package documents behavior).
+- **`generateTS`** / **`graphqlTS`** options and error behavior should match README and real usage.
+
+## Product terminology
+
+- This library is **Delivery (CDA)** + **GraphQL** only. Do not label features or errors as **CMA** or Management API unless you are explicitly comparing upstream docs—and even then, keep user-facing text accurate to this package.
+
+## Backward compatibility
+
+- Generated TypeScript shape changes can break consumers; treat output as a semver-sensitive API.
+- Error objects with **`type`** and **`error_message`** should remain predictable; document intentional changes.
+
+## Error handling
+
+- Prefer existing helpers (**`createValidationError`**, **`createErrorDetails`**) and patterns in [`src/generateTS`](../../src/generateTS) / [`src/graphqlTS`](../../src/graphqlTS).
+- SDK initialization errors in [`src/sdk/utils.ts`](../../src/sdk/utils.ts) use **`type: "validation"`**; keep consistency.
+
+## Null and config safety
+
+- Optional **`host`**, **`branch`**, logger instances, and stack parameters must be guarded per **`strictNullChecks`**.
+
+## Dependencies and security
+
+- Justify new runtime dependencies (bundle size, maintenance).
+- CI runs SCA (Snyk + policy) on pull requests—consider supply-chain impact of new packages.
+
+## Tests
+
+- **Unit:** [`tests/unit/`](../../tests/unit/) for deterministic logic; use **`.ct.js`** fixtures with matching **`.test.ts`** where applicable.
+- **Integration:** [`tests/integration/`](../../tests/integration/) for live stack tests; require documented env vars.
+
+## Optional severity tags
+
+- **Blocker:** breaks consumers, security issue, or wrong API family (e.g. CMA-only assumption).
+- **Major:** missing tests for new behavior, unclear errors, semver risk.
+- **Minor:** style, small doc gaps, non-user-facing refactors.
@@ -0,0 +1,38 @@
+---
+name: testing
+description: How to run and write tests for @contentstack/types-generator (Jest, unit vs integration, env, fixtures).
+---
+
+# Testing skill (`@contentstack/types-generator`)
+
+## Commands
+
+| Command | What it runs |
+| --- | --- |
+| `npm test` | Jest with `--testPathPattern=tests` and `NODE_OPTIONS=--experimental-vm-modules` ([`package.json`](../../package.json)). |
+| `npm run test:unit:report:json` | Unit tests only (`tests/unit`), coverage (clover + json), `test-results.json` — mirrors CI. |
+| `npm run build` | Build first if imports from `dist/` matter (normally tests import `src/`). |
+
+[`jest.config.js`](../../jest.config.js) sets **`setupFiles: ["dotenv/config"]`** so `.env` keys load when present.
+
+## Layout
+
+- **`tests/unit/`** — Fast tests; **`tests/unit/tsgen/`** pairs **`.ct.js`** content-type fixtures with **`.test.ts`** files.
+- **`tests/integration/`** — Live API tests (e.g. `generateTS`, `graphqlTS`); need credentials.
+
+## Environment variables (integration)
+
+Common variables read in integration tests:
+
+- **`TOKEN`**, **`APIKEY`**, **`ENVIRONMENT`**, **`REGION`**, **`TOKENTYPE`**, **`BRANCH`**
+
+Some tests use **`TOKEN_WITH_NO_CT`** / **`APIKEY_WITH_NO_CT`** (see CI env in [`.github/workflows/node.js.yml`](../../.github/workflows/node.js.yml)). Integration specs may load **`.env`** from the package root via `dotenv` paths—check the specific test file.
+
+## Mocks
+
+- **`axios-mock-adapter`** and **`nock`** are devDependencies for HTTP mocking when adding unit tests around network code.
+
+## Timeouts and coverage
+
+- Use reasonable async timeouts for integration tests hitting real endpoints.
+- CI publishes coverage from **`test:unit:report:json`**; keep new unit code covered when practical.