From 5269c7b1c310a5d9d100c6f6ef659364fe86399c Mon Sep 17 00:00:00 2001 From: naman-contentstack Date: Wed, 25 Mar 2026 21:33:47 +0530 Subject: [PATCH] feat: add skills in package --- .cursor/rules/README.md | 16 +++++++++ .cursor/rules/code-review.mdc | 28 +++++++++++++++ .cursor/rules/dev-workflow.mdc | 41 ++++++++++++++++++++++ .cursor/rules/oclif-tsgen.mdc | 33 ++++++++++++++++++ .cursor/rules/testing.mdc | 15 ++++++++ .cursor/rules/typescript.mdc | 13 +++++++ .talismanrc | 4 +++ AGENTS.md | 51 ++++++++++++++++++++++++++++ skills/README.md | 11 ++++++ skills/code-review/SKILL.md | 35 +++++++++++++++++++ skills/testing/SKILL.md | 27 +++++++++++++++ skills/typescript-cli-tsgen/SKILL.md | 27 +++++++++++++++ 12 files changed, 301 insertions(+) create mode 100644 .cursor/rules/README.md create mode 100644 .cursor/rules/code-review.mdc create mode 100644 .cursor/rules/dev-workflow.mdc create mode 100644 .cursor/rules/oclif-tsgen.mdc create mode 100644 .cursor/rules/testing.mdc create mode 100644 .cursor/rules/typescript.mdc create mode 100644 AGENTS.md create mode 100644 skills/README.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/testing/SKILL.md create mode 100644 skills/typescript-cli-tsgen/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..bc9ca78 --- /dev/null +++ b/.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. diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc new file mode 100644 index 0000000..ac75b45 --- /dev/null +++ b/.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. diff --git a/.cursor/rules/dev-workflow.mdc b/.cursor/rules/dev-workflow.mdc new file mode 100644 index 0000000..6b2981b --- /dev/null +++ b/.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`**. diff --git a/.cursor/rules/oclif-tsgen.mdc b/.cursor/rules/oclif-tsgen.mdc new file mode 100644 index 0000000..80d4f20 --- /dev/null +++ b/.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. diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc new file mode 100644 index 0000000..fba350f --- /dev/null +++ b/.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). diff --git a/.cursor/rules/typescript.mdc b/.cursor/rules/typescript.mdc new file mode 100644 index 0000000..222177d --- /dev/null +++ b/.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. diff --git a/.talismanrc b/.talismanrc index f83dbcb..5df2e33 100644 --- a/.talismanrc +++ b/.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" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..728e3bb --- /dev/null +++ b/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) diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..52afd06 --- /dev/null +++ b/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. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..51186de --- /dev/null +++ b/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. diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..ded6b93 --- /dev/null +++ b/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. diff --git a/skills/typescript-cli-tsgen/SKILL.md b/skills/typescript-cli-tsgen/SKILL.md new file mode 100644 index 0000000..b6e82de --- /dev/null +++ b/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.