feat: add skills in package

.cursor/rules/README.md

@@ -0,0 +1,16 @@
+# Cursor rules for `contentstack-cli-tsgen`
+
+This folder contains project-specific rules. Each `.mdc` file uses 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/**/*`, `tsconfig.json`, `jest.config.js`, `.eslintrc.js`, `AGENTS.md` | Workflow, CI, release, package scripts | [testing](../../skills/testing/SKILL.md), [code-review](../../skills/code-review/SKILL.md) |
+| [typescript.mdc](typescript.mdc) | No | `src/**/*.ts`, `tests/**/*.ts` | TypeScript and ESLint conventions | [typescript-cli-tsgen](../../skills/typescript-cli-tsgen/SKILL.md) |
+| [oclif-tsgen.mdc](oclif-tsgen.mdc) | No | `src/commands/**`, `src/lib/**` | OCLIF command, flags, delegation to `@contentstack/types-generator` | [typescript-cli-tsgen](../../skills/typescript-cli-tsgen/SKILL.md) |
+| [testing.mdc](testing.mdc) | No | `tests/**`, `jest.config.js` | Jest and integration tests with `csdx` | [testing](../../skills/testing/SKILL.md) |
+| [code-review.mdc](code-review.mdc) | **Yes** | — | Every change | [code-review](../../skills/code-review/SKILL.md) |
+
+## Referencing rules in Cursor
+
+- Use **@** in chat (e.g. `@oclif-tsgen`, `@dev-workflow`) to pull in rule context.
+- `code-review.mdc` applies automatically (`alwaysApply: true`); others match globs or manual @-mentions.

.cursor/rules/code-review.mdc

@@ -0,0 +1,28 @@
+---
+description: PR and change review checklist for contentstack-cli-tsgen
+alwaysApply: true
+---
+
+# Code review checklist
+
+## API and documentation
+
+- **CLI surface:** Flag names, examples, and help text stay accurate; **`oclif readme`** output remains consistent when commands change.
+- **Terminology:** **Delivery** token / **GraphQL** vs REST—do not describe this plugin as a **CMA**-first tool.
+
+## Compatibility
+
+- **Backward compatibility:** Avoid breaking changes to flags, exit behavior, or output file contract without semver intent.
+- **Errors:** Align with **`printFormattedError`** and **`FormattedError`** patterns in [`src/lib/helper.ts`](src/lib/helper.ts); preserve stable error codes where used.
+
+## Dependencies
+
+- **`@contentstack/types-generator`:** Pin/bump per semver; do not duplicate library logic in the CLI—delegate to the package ([npm](https://www.npmjs.com/package/@contentstack/types-generator), [repo](https://github.com/contentstack/types-generator)).
+
+## Security and supply chain
+
+- **SCA:** `.github/workflows/sca-scan.yml` runs Snyk on pull requests.
+
+## Tests
+
+- **Integration:** Changes to **`csdx tsgen`** should keep **`tests/integration/`** passing when **`TOKEN_ALIAS`** and stack secrets are available.

.cursor/rules/dev-workflow.mdc

@@ -0,0 +1,41 @@
+---
+description: Branches, prepack/test, PR and release workflow for contentstack-cli-tsgen
+alwaysApply: false
+globs:
+  - package.json
+  - package-lock.json
+  - .github/workflows/**/*
+  - tsconfig.json
+  - jest.config.js
+  - .eslintrc.js
+  - AGENTS.md
+---
+
+# Development workflow
+
+For detail on tests and env, see **[skills/testing](../../skills/testing/SKILL.md)**; for PR expectations, **[skills/code-review](../../skills/code-review/SKILL.md)**.
+
+## Branches
+
+- **CI (Node.js workflow)** runs on **push** and **pull_request** for **`master`**, **`development`**, and **`staging`** (see `.github/workflows/node.js.yml`).
+- **Release** runs on **push** to **`master`** (see `.github/workflows/release.yml`), Node **22.x**, artifact **`lib`**, npm publish + GitHub release.
+
+**Maintainer note:** Other Contentstack repos may use different default branches (`main` vs `master`). Align docs and protection rules when convenient—no git config changes implied here.
+
+## Build and compile
+
+- **`npm run prepack`**: removes **`lib/`**, runs **`tsc -b`**, **`oclif manifest`**, **`oclif readme`**. This is the canonical build before pack/publish.
+- CI runs **`npm run prepack`** after global **`csdx`** setup and **`plugins:link`**.
+
+## Tests and lint
+
+- **`npm test`**: Jest with `--testPathPattern=tests`.
+- **`posttest`** (after `npm test`): ESLint with `.eslintrc.js` and `--fix`.
+
+## Pull requests
+
+- Run **`npm run prepack`** and **`npm test`** (which triggers **`posttest`**) before merge when touching source or tests.
+
+## Releases
+
+- Version in **`package.json`** drives publishing; release workflow builds with **`prepack`** and publishes from **`master`**.

.cursor/rules/oclif-tsgen.mdc

@@ -0,0 +1,33 @@
+---
+description: OCLIF tsgen command, flags, and delegation to @contentstack/types-generator
+alwaysApply: false
+globs:
+  - src/commands/**
+  - src/lib/**
+---
+
+# OCLIF `tsgen` command
+
+Scope: **CLI only**. Type generation internals live in the **`@contentstack/types-generator`** package ([npm](https://www.npmjs.com/package/@contentstack/types-generator), [repository](https://github.com/contentstack/types-generator))—do not invent library APIs here.
+
+## Command shape
+
+- Extends **`Command`** from **`@contentstack/cli-command`** ([`src/commands/tsgen.ts`](src/commands/tsgen.ts)).
+- **Flags:** e.g. **`token-alias`** (`-a`, required), **`output`** (`-o`), **`prefix`**, **`doc`**, **`branch`**, **`include-system-fields`**, **`include-editable-tags`**, **`include-referenced-entry`**, **`api-type`** (`rest` \| `graphql`), **`namespace`** (GraphQL).
+- Use **`this.parse`**, **`this.error`**, **`this.log`** / **`cliux`** / **`log`** from **`@contentstack/cli-utilities`** per existing patterns.
+
+## Auth and stack config
+
+- Resolve token via **`this.getToken(flags["token-alias"])`**. Warn if **`token.type !== "delivery"`** (management token may break Delivery/GraphQL flows).
+- Build **`StackConnectionConfig`**: **`apiKey`**, **`token`**, **`region`**, **`environment`**, **`branch`**, **`host`** (CDA host from command context).
+
+## Generation paths
+
+- **`api-type === "graphql"`** → **`graphqlTS(...)`** with delivery token required; pass **`logger: log`** where applicable.
+- **REST (default)** → **`generateTS({ ...config, tokenType: "delivery", ... })`**.
+- Write result with **`fs.writeFileSync`** to the resolved output path.
+
+## Errors
+
+- Use **`printFormattedError`** from [`src/lib/helper.ts`](src/lib/helper.ts) for consistent CLI messaging; **`process.exit(1)`** on failure paths as in the command today.
+- **Terminology:** **Delivery** and **GraphQL** as documented in flags—not **CMA** as the primary path.

.cursor/rules/testing.mdc

@@ -0,0 +1,15 @@
+---
+description: Jest tests and integration env for contentstack-cli-tsgen
+alwaysApply: false
+globs:
+  - tests/**
+  - jest.config.js
+---
+
+# Testing (`contentstack-cli-tsgen`)
+
+- **Runner:** **Jest** with **ts-jest** preset **`node`** ([jest.config.js](jest.config.js)).
+- **Match:** `**/tests/**/*.+(ts|tsx)` and standard test patterns.
+- **Current layout:** Integration tests under **`tests/integration/`** (e.g. **`spawnSync`** invoking **`csdx tsgen`**).
+- **Env:** **`TOKEN_ALIAS`** must be set for integration tests (see **`tests/integration/tsgen.integration.test.ts`**); **`.env`** at package root is loaded via `dotenv` in that file.
+- **Commands:** `npm test` (all tests under `tests`), `npm run test:integration` (integration path only).

.cursor/rules/typescript.mdc

@@ -0,0 +1,13 @@
+---
+description: TypeScript and ESLint conventions for contentstack-cli-tsgen
+alwaysApply: false
+globs:
+  - src/**/*.ts
+  - tests/**/*.ts
+---
+
+# TypeScript (`contentstack-cli-tsgen`)
+
+- **Compiler:** TypeScript **5.9**, **`strict: true`** ([tsconfig.json](tsconfig.json)); output **`lib/`** from **`src/`** via **`tsc -b`**.
+- **Layout:** **`src/commands/`** (OCLIF commands), **`src/lib/`** (helpers such as path sanitization and **`printFormattedError`**), **`src/types/`**.
+- **Linting:** **ESLint** with **`eslint-config-oclif`** / **`eslint-config-oclif-typescript`** (see **`.eslintrc.js`**). **`posttest`** runs `eslint . --ext .ts --config .eslintrc.js --fix` after Jest.

.talismanrc

@@ -4,4 +4,8 @@ fileignoreconfig:
       - filecontent
   - filename: package-lock.json
     checksum: fadad20d6e5ea2efd20595a8262b5f18ab59db802c18f4b1c1faec0c325ab2ac
+  - filename: .cursor/rules/oclif-tsgen.mdc
+    checksum: 83d43465e1b0d7d8c4fd3a13ca4cde13fc5ea2b578186891e3b268ede0e7d97c
+  - filename: AGENTS.md
+    checksum: 7cce7645c9ebd051f971ea157fc85b691b23c963211debf31729d9ee607c081f
 version: "1.0"

AGENTS.md

@@ -0,0 +1,51 @@
+# `contentstack-cli-tsgen`
+
+**Purpose:** Contentstack CLI (**OCLIF**) plugin that adds **`csdx tsgen`** to generate TypeScript typings from a stack. Generation is delegated to the **`@contentstack/types-generator`** npm package (`generateTS` / `graphqlTS`); this repo owns the command surface (flags, auth alias, file output, CLI error formatting).
+
+- **Repository:** [github.com/Contentstack-Solutions/contentstack-cli-tsgen](https://github.com/Contentstack-Solutions/contentstack-cli-tsgen)
+- **Homepage:** [https://github.com/Contentstack-Solutions/contentstack-cli-tsgen](https://github.com/Contentstack-Solutions/contentstack-cli-tsgen)
+
+**Library dependency (separate repo):** [`@contentstack/types-generator`](https://www.npmjs.com/package/@contentstack/types-generator) (see version in [package.json](package.json)). Source for the generator itself: [github.com/contentstack/types-generator](https://github.com/contentstack/types-generator). Do not assume a local sibling folder; treat it as an npm dependency only.
+
+## Tech stack
+
+| Area | Details |
+| --- | --- |
+| Language | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) |
+| Runtime | Node (CI **18.x** / **20.x**; release **22.x**) |
+| Build | **`tsc -b`** → **`lib/`**; **`npm run prepack`** runs `tsc -b`, **`oclif manifest`**, **`oclif readme`** |
+| CLI | **OCLIF** — commands compiled to **`lib/commands`** (see `oclif.commands` in [package.json](package.json)) |
+| Tests | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)) |
+| Lint | **ESLint** runs in **`posttest`** after tests ([package.json](package.json) scripts) |
+
+**Main dependencies:** `@contentstack/cli-command`, `@contentstack/cli-utilities`, `@contentstack/types-generator`, `dotenv`.
+
+## Source layout
+
+- **Commands:** [src/commands/](src/commands/) (e.g. `tsgen.ts`)
+- **Helpers / errors:** [src/lib/](src/lib/)
+- **Types:** [src/types/](src/types/)
+- **Build output:** **`lib/`** (not committed as source of truth; produced by `prepack`)
+
+## Common commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm run prepack` | Clean `lib/`, compile TypeScript, generate OCLIF manifest and README |
+| `npm test` | Jest (`--testPathPattern=tests`); then **`posttest`** runs ESLint with fix |
+| `npm run test:integration` | Jest for `tests/integration` only |
+
+There is no dedicated `build` script; **`prepack`** is the canonical compile path. CI may run `npm run build --if-present` (no-op here if no `build` script).
+
+## Credentials and integration tests
+
+Integration tests spawn **`csdx tsgen`** and require a configured **delivery token alias**. Set **`TOKEN_ALIAS`** (e.g. in **`.env`** at the package root; see [tests/integration/tsgen.integration.test.ts](tests/integration/tsgen.integration.test.ts)).
+
+CI uses GitHub secrets such as **`REGION`**, **`TOKEN_ALIAS`**, **`APIKEY`**, **`DELIVERYKEY`**, **`ENVIRONMENT`** (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)).
+
+---
+
+## AI guidance index
+
+- [Cursor rules (overview)](.cursor/rules/README.md)
+- [Skills index](skills/README.md)

skills/README.md

@@ -0,0 +1,11 @@
+# Skills for `contentstack-cli-tsgen`
+
+Use with [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md).
+
+| Skill | When to use |
+| --- | --- |
+| [code-review](code-review/SKILL.md) | PR checklist: CLI UX, errors, Delivery vs CMA wording, dependency on `@contentstack/types-generator` |
+| [testing](testing/SKILL.md) | Jest, `posttest` ESLint, integration tests, `TOKEN_ALIAS`, CI secrets |
+| [typescript-cli-tsgen](typescript-cli-tsgen/SKILL.md) | OCLIF command flow, helpers, where to change flags vs library behavior |
+
+There is no separate **framework** skill: HTTP and generation details belong in **`@contentstack/types-generator`** (see npm / [github.com/contentstack/types-generator](https://github.com/contentstack/types-generator)), not relative paths to another checkout.

skills/code-review/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: code-review
+description: PR review checklist for contentstack-cli-tsgen (CLI, errors, Delivery/GraphQL, types-generator dependency).
+---
+
+# Code review skill (`contentstack-cli-tsgen`)
+
+Aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc).
+
+## CLI and docs
+
+- Help text, **`static examples`**, and README/oclif-generated docs stay in sync when flags or behavior change.
+- Short command name **`tsgen`** / **`TSGEN`** comes from **`csdxConfig`** in [package.json](../../package.json).
+
+## Product language
+
+- Prefer **Delivery** token flows; **GraphQL** requires delivery token in code paths—reviewers should catch **CMA**-centric wording that misleads users.
+
+## Errors
+
+- **`printFormattedError`** in [`src/lib/helper.ts`](../../src/lib/helper.ts) maps **`error_code`** to user-facing messages; extend switches carefully for backward compatibility.
+
+## Dependency on the library
+
+- Business logic for **`generateTS`** / **`graphqlTS`** belongs in **`@contentstack/types-generator`** ([npm](https://www.npmjs.com/package/@contentstack/types-generator), [GitHub](https://github.com/contentstack/types-generator)). CLI changes should orchestrate and format, not reimplement generation.
+
+## Tests and CI
+
+- Integration tests depend on **`csdx`** and **`TOKEN_ALIAS`**; document env needs when adding cases.
+
+## Optional severity
+
+- **Blocker:** Wrong token type handling, broken `csdx` contract, security issues.
+- **Major:** Missing integration coverage for new flags, unclear errors.
+- **Minor:** Copy, non-breaking refactors.

skills/testing/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: testing
+description: How to run tests and use env for contentstack-cli-tsgen (Jest, ESLint posttest, integration).
+---
+
+# Testing skill (`contentstack-cli-tsgen`)
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `npm test` | Jest with `--testPathPattern=tests`; then **`posttest`** runs ESLint ([package.json](../../package.json)) |
+| `npm run test:integration` | Jest only for `tests/integration` |
+| `npm run prepack` | Build `lib/` (required before local `csdx plugins:link` style workflows) |
+
+## Config
+
+- [`jest.config.js`](../../jest.config.js): **ts-jest**, **`testEnvironment: node`**.
+
+## Integration tests
+
+- **[tests/integration/tsgen.integration.test.ts](../../tests/integration/tsgen.integration.test.ts)** spawns **`csdx tsgen`** with **`TOKEN_ALIAS`**.
+- Loads **`.env`** from package root via **`dotenv`** (`path` relative to test file). **`TOKEN_ALIAS`** must be defined or the suite throws at load time.
+
+## CI
+
+- [.github/workflows/node.js.yml](../../.github/workflows/node.js.yml): `npm ci`, optional `npm run build --if-present`, global **`@contentstack/cli`**, **`csdx config:set:region`**, **`csdx auth:tokens:add`** (delivery), **`npm run prepack`**, **`csdx plugins:link`**, **`npm test`** with **`TOKEN_ALIAS`** secret.

skills/typescript-cli-tsgen/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: typescript-cli-tsgen
+description: Mental model for the contentstack-cli-tsgen OCLIF plugin and tsgen command.
+---
+
+# TypeScript CLI tsgen skill
+
+## Role of this repo
+
+- **Plugin** for **`csdx`**: implements **`TypeScriptCodeGeneratorCommand`** in [`src/commands/tsgen.ts`](../../src/commands/tsgen.ts).
+- **Generation** is delegated to **`@contentstack/types-generator`** ([npm](https://www.npmjs.com/package/@contentstack/types-generator), [GitHub](https://github.com/contentstack/types-generator))—version **^3.9.3** in [package.json](../../package.json). Do not assume a local clone; use npm and published source only.
+
+## Change here vs change in the library
+
+| Concern | Where |
+| --- | --- |
+| New flags, output path, `csdx` UX, **`printFormattedError`** | This repo (`src/commands/`, `src/lib/`) |
+| Schema mapping, Delivery SDK calls, GraphQL introspection | **`@contentstack/types-generator`** |
+
+## Helpers
+
+- [`src/lib/helper.ts`](../../src/lib/helper.ts): **`sanitizePath`**, **`printFormattedError`** (`FormattedError`, **`error_code`** switch).
+- [`src/types/index.ts`](../../src/types/index.ts): **`StackConnectionConfig`** and related CLI types.
+
+## OCLIF
+
+- Commands compile to **`lib/commands`**; **`prepack`** refreshes **`oclif.manifest.json`** and README.