Skip to content

Commit e4b2224

Browse files
naman-contentstacknaman-contentstack
authored
Merge pull request #289 from contentstack/feat/DX-5351
feat: add skills in package
2 parents 1de99e7 + 5269c7b commit e4b2224

File tree

12 files changed

+301
-0
lines changed

12 files changed

+301
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Cursor rules for `contentstack-cli-tsgen`
2+
3+
This folder contains project-specific rules. Each `.mdc` file uses YAML frontmatter (`description`, `globs`, `alwaysApply`).
4+
5+
| Rule file | `alwaysApply` | Globs | When it applies | Related skill |
6+
| --- | --- | --- | --- | --- |
7+
| [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) |
8+
| [typescript.mdc](typescript.mdc) | No | `src/**/*.ts`, `tests/**/*.ts` | TypeScript and ESLint conventions | [typescript-cli-tsgen](../../skills/typescript-cli-tsgen/SKILL.md) |
9+
| [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) |
10+
| [testing.mdc](testing.mdc) | No | `tests/**`, `jest.config.js` | Jest and integration tests with `csdx` | [testing](../../skills/testing/SKILL.md) |
11+
| [code-review.mdc](code-review.mdc) | **Yes** | — | Every change | [code-review](../../skills/code-review/SKILL.md) |
12+
13+
## Referencing rules in Cursor
14+
15+
- Use **@** in chat (e.g. `@oclif-tsgen`, `@dev-workflow`) to pull in rule context.
16+
- `code-review.mdc` applies automatically (`alwaysApply: true`); others match globs or manual @-mentions.

‎.cursor/rules/code-review.mdc‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
description: PR and change review checklist for contentstack-cli-tsgen
3+
alwaysApply: true
4+
---
5+
6+
# Code review checklist
7+
8+
## API and documentation
9+
10+
- **CLI surface:** Flag names, examples, and help text stay accurate; **`oclif readme`** output remains consistent when commands change.
11+
- **Terminology:** **Delivery** token / **GraphQL** vs REST—do not describe this plugin as a **CMA**-first tool.
12+
13+
## Compatibility
14+
15+
- **Backward compatibility:** Avoid breaking changes to flags, exit behavior, or output file contract without semver intent.
16+
- **Errors:** Align with **`printFormattedError`** and **`FormattedError`** patterns in [`src/lib/helper.ts`](src/lib/helper.ts); preserve stable error codes where used.
17+
18+
## Dependencies
19+
20+
- **`@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)).
21+
22+
## Security and supply chain
23+
24+
- **SCA:** `.github/workflows/sca-scan.yml` runs Snyk on pull requests.
25+
26+
## Tests
27+
28+
- **Integration:** Changes to **`csdx tsgen`** should keep **`tests/integration/`** passing when **`TOKEN_ALIAS`** and stack secrets are available.

‎.cursor/rules/dev-workflow.mdc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
description: Branches, prepack/test, PR and release workflow for contentstack-cli-tsgen
3+
alwaysApply: false
4+
globs:
5+
- package.json
6+
- package-lock.json
7+
- .github/workflows/**/*
8+
- tsconfig.json
9+
- jest.config.js
10+
- .eslintrc.js
11+
- AGENTS.md
12+
---
13+
14+
# Development workflow
15+
16+
For detail on tests and env, see **[skills/testing](../../skills/testing/SKILL.md)**; for PR expectations, **[skills/code-review](../../skills/code-review/SKILL.md)**.
17+
18+
## Branches
19+
20+
- **CI (Node.js workflow)** runs on **push** and **pull_request** for **`master`**, **`development`**, and **`staging`** (see `.github/workflows/node.js.yml`).
21+
- **Release** runs on **push** to **`master`** (see `.github/workflows/release.yml`), Node **22.x**, artifact **`lib`**, npm publish + GitHub release.
22+
23+
**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.
24+
25+
## Build and compile
26+
27+
- **`npm run prepack`**: removes **`lib/`**, runs **`tsc -b`**, **`oclif manifest`**, **`oclif readme`**. This is the canonical build before pack/publish.
28+
- CI runs **`npm run prepack`** after global **`csdx`** setup and **`plugins:link`**.
29+
30+
## Tests and lint
31+
32+
- **`npm test`**: Jest with `--testPathPattern=tests`.
33+
- **`posttest`** (after `npm test`): ESLint with `.eslintrc.js` and `--fix`.
34+
35+
## Pull requests
36+
37+
- Run **`npm run prepack`** and **`npm test`** (which triggers **`posttest`**) before merge when touching source or tests.
38+
39+
## Releases
40+
41+
- Version in **`package.json`** drives publishing; release workflow builds with **`prepack`** and publishes from **`master`**.

‎.cursor/rules/oclif-tsgen.mdc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
description: OCLIF tsgen command, flags, and delegation to @contentstack/types-generator
3+
alwaysApply: false
4+
globs:
5+
- src/commands/**
6+
- src/lib/**
7+
---
8+
9+
# OCLIF `tsgen` command
10+
11+
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.
12+
13+
## Command shape
14+
15+
- Extends **`Command`** from **`@contentstack/cli-command`** ([`src/commands/tsgen.ts`](src/commands/tsgen.ts)).
16+
- **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).
17+
- Use **`this.parse`**, **`this.error`**, **`this.log`** / **`cliux`** / **`log`** from **`@contentstack/cli-utilities`** per existing patterns.
18+
19+
## Auth and stack config
20+
21+
- Resolve token via **`this.getToken(flags["token-alias"])`**. Warn if **`token.type !== "delivery"`** (management token may break Delivery/GraphQL flows).
22+
- Build **`StackConnectionConfig`**: **`apiKey`**, **`token`**, **`region`**, **`environment`**, **`branch`**, **`host`** (CDA host from command context).
23+
24+
## Generation paths
25+
26+
- **`api-type === "graphql"`** → **`graphqlTS(...)`** with delivery token required; pass **`logger: log`** where applicable.
27+
- **REST (default)** → **`generateTS({ ...config, tokenType: "delivery", ... })`**.
28+
- Write result with **`fs.writeFileSync`** to the resolved output path.
29+
30+
## Errors
31+
32+
- 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.
33+
- **Terminology:** **Delivery** and **GraphQL** as documented in flags—not **CMA** as the primary path.

‎.cursor/rules/testing.mdc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
description: Jest tests and integration env for contentstack-cli-tsgen
3+
alwaysApply: false
4+
globs:
5+
- tests/**
6+
- jest.config.js
7+
---
8+
9+
# Testing (`contentstack-cli-tsgen`)
10+
11+
- **Runner:** **Jest** with **ts-jest** preset **`node`** ([jest.config.js](jest.config.js)).
12+
- **Match:** `**/tests/**/*.+(ts|tsx)` and standard test patterns.
13+
- **Current layout:** Integration tests under **`tests/integration/`** (e.g. **`spawnSync`** invoking **`csdx tsgen`**).
14+
- **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.
15+
- **Commands:** `npm test` (all tests under `tests`), `npm run test:integration` (integration path only).

‎.cursor/rules/typescript.mdc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
description: TypeScript and ESLint conventions for contentstack-cli-tsgen
3+
alwaysApply: false
4+
globs:
5+
- src/**/*.ts
6+
- tests/**/*.ts
7+
---
8+
9+
# TypeScript (`contentstack-cli-tsgen`)
10+
11+
- **Compiler:** TypeScript **5.9**, **`strict: true`** ([tsconfig.json](tsconfig.json)); output **`lib/`** from **`src/`** via **`tsc -b`**.
12+
- **Layout:** **`src/commands/`** (OCLIF commands), **`src/lib/`** (helpers such as path sanitization and **`printFormattedError`**), **`src/types/`**.
13+
- **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‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,8 @@ fileignoreconfig:
44
- filecontent
55
- filename: package-lock.json
66
checksum: fadad20d6e5ea2efd20595a8262b5f18ab59db802c18f4b1c1faec0c325ab2ac
7+
- filename: .cursor/rules/oclif-tsgen.mdc
8+
checksum: 83d43465e1b0d7d8c4fd3a13ca4cde13fc5ea2b578186891e3b268ede0e7d97c
9+
- filename: AGENTS.md
10+
checksum: 7cce7645c9ebd051f971ea157fc85b691b23c963211debf31729d9ee607c081f
711
version: "1.0"

‎AGENTS.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# `contentstack-cli-tsgen`
2+
3+
**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).
4+
5+
- **Repository:** [github.com/Contentstack-Solutions/contentstack-cli-tsgen](https://github.com/Contentstack-Solutions/contentstack-cli-tsgen)
6+
- **Homepage:** [https://github.com/Contentstack-Solutions/contentstack-cli-tsgen](https://github.com/Contentstack-Solutions/contentstack-cli-tsgen)
7+
8+
**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.
9+
10+
## Tech stack
11+
12+
| Area | Details |
13+
| --- | --- |
14+
| Language | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) |
15+
| Runtime | Node (CI **18.x** / **20.x**; release **22.x**) |
16+
| Build | **`tsc -b`** → **`lib/`**; **`npm run prepack`** runs `tsc -b`, **`oclif manifest`**, **`oclif readme`** |
17+
| CLI | **OCLIF** — commands compiled to **`lib/commands`** (see `oclif.commands` in [package.json](package.json)) |
18+
| Tests | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)) |
19+
| Lint | **ESLint** runs in **`posttest`** after tests ([package.json](package.json) scripts) |
20+
21+
**Main dependencies:** `@contentstack/cli-command`, `@contentstack/cli-utilities`, `@contentstack/types-generator`, `dotenv`.
22+
23+
## Source layout
24+
25+
- **Commands:** [src/commands/](src/commands/) (e.g. `tsgen.ts`)
26+
- **Helpers / errors:** [src/lib/](src/lib/)
27+
- **Types:** [src/types/](src/types/)
28+
- **Build output:** **`lib/`** (not committed as source of truth; produced by `prepack`)
29+
30+
## Common commands
31+
32+
| Command | Purpose |
33+
| --- | --- |
34+
| `npm run prepack` | Clean `lib/`, compile TypeScript, generate OCLIF manifest and README |
35+
| `npm test` | Jest (`--testPathPattern=tests`); then **`posttest`** runs ESLint with fix |
36+
| `npm run test:integration` | Jest for `tests/integration` only |
37+
38+
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).
39+
40+
## Credentials and integration tests
41+
42+
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)).
43+
44+
CI uses GitHub secrets such as **`REGION`**, **`TOKEN_ALIAS`**, **`APIKEY`**, **`DELIVERYKEY`**, **`ENVIRONMENT`** (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)).
45+
46+
---
47+
48+
## AI guidance index
49+
50+
- [Cursor rules (overview)](.cursor/rules/README.md)
51+
- [Skills index](skills/README.md)

‎skills/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Skills for `contentstack-cli-tsgen`
2+
3+
Use with [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md).
4+
5+
| Skill | When to use |
6+
| --- | --- |
7+
| [code-review](code-review/SKILL.md) | PR checklist: CLI UX, errors, Delivery vs CMA wording, dependency on `@contentstack/types-generator` |
8+
| [testing](testing/SKILL.md) | Jest, `posttest` ESLint, integration tests, `TOKEN_ALIAS`, CI secrets |
9+
| [typescript-cli-tsgen](typescript-cli-tsgen/SKILL.md) | OCLIF command flow, helpers, where to change flags vs library behavior |
10+
11+
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‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: code-review
3+
description: PR review checklist for contentstack-cli-tsgen (CLI, errors, Delivery/GraphQL, types-generator dependency).
4+
---
5+
6+
# Code review skill (`contentstack-cli-tsgen`)
7+
8+
Aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc).
9+
10+
## CLI and docs
11+
12+
- Help text, **`static examples`**, and README/oclif-generated docs stay in sync when flags or behavior change.
13+
- Short command name **`tsgen`** / **`TSGEN`** comes from **`csdxConfig`** in [package.json](../../package.json).
14+
15+
## Product language
16+
17+
- Prefer **Delivery** token flows; **GraphQL** requires delivery token in code paths—reviewers should catch **CMA**-centric wording that misleads users.
18+
19+
## Errors
20+
21+
- **`printFormattedError`** in [`src/lib/helper.ts`](../../src/lib/helper.ts) maps **`error_code`** to user-facing messages; extend switches carefully for backward compatibility.
22+
23+
## Dependency on the library
24+
25+
- 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.
26+
27+
## Tests and CI
28+
29+
- Integration tests depend on **`csdx`** and **`TOKEN_ALIAS`**; document env needs when adding cases.
30+
31+
## Optional severity
32+
33+
- **Blocker:** Wrong token type handling, broken `csdx` contract, security issues.
34+
- **Major:** Missing integration coverage for new flags, unclear errors.
35+
- **Minor:** Copy, non-breaking refactors.

0 commit comments

Comments
 (0)