Skip to content

Commit e297e79

Browse files
cs-rajcs-raj
authored
Merge pull request #300 from contentstack/update/DX-6055
update: removed rules and moved everything to agents.md
2 parents 8884b4a + 1eca092 commit e297e79

12 files changed

Lines changed: 108 additions & 188 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 3 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,5 @@
1-
# Cursor rules for `contentstack-cli-tsgen`
1+
# Cursor (optional)
22

3-
This folder contains project-specific rules. Each `.mdc` file uses YAML frontmatter (`description`, `globs`, `alwaysApply`).
3+
**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
44

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.
5+
This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

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

Lines changed: 0 additions & 28 deletions
This file was deleted.

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

Lines changed: 0 additions & 41 deletions
This file was deleted.

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

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎.cursor/rules/testing.mdc‎

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎.cursor/rules/typescript.mdc‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎.talismanrc‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,17 @@ fileignoreconfig:
33
ignore_detectors:
44
- filecontent
55
- filename: package-lock.json
6-
checksum: 9cf2ec1b73a078e9f3c974f1a9b7f70864f0307115d1f965b57752ba5a9dcdf2
7-
- filename: .cursor/rules/oclif-tsgen.mdc
8-
checksum: 83d43465e1b0d7d8c4fd3a13ca4cde13fc5ea2b578186891e3b268ede0e7d97c
6+
checksum: 40cf1a77a8277c0236bdb74dee168a8ca9e0d4fc56706e0006b7ce69743319d7
97
- filename: AGENTS.md
10-
checksum: 7cce7645c9ebd051f971ea157fc85b691b23c963211debf31729d9ee607c081f
8+
checksum: e442f35176d7263bc2ea3e7f5e112bfb4cbf6aad30f1a768d9695578b1b19636
9+
- filename: skills/dev-workflow/SKILL.md
10+
checksum: 036381e0d336cec14d0f83ba784f101a12ceaa9b86e486bc049e3aef0594c95b
11+
- filename: skills/README.md
12+
checksum: 6a74a10445c50ddebe3fae7737c04f2bc49c776ffdc8973711463c4d878e6041
13+
- filename: skills/code-review/SKILL.md
14+
checksum: 3cff88deeefd1fadf5714adf5657effdf5ce839a368dc71e4cb7f88db2cd7ddc
15+
- filename: skills/typescript-cli-tsgen/SKILL.md
16+
checksum: abbe95d052464f5d3434dd36caa7aab62cf6931f223aed70b698dc8f1aff5c28
17+
- filename: skills/testing/SKILL.md
18+
checksum: 6dbbb85e8eb83ebf0dda715fcd8f9c2704495ed6598a67b7222010d4c91366a5
1119
version: "1.0"

‎AGENTS.md‎

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,54 @@
1-
# `contentstack-cli-tsgen`
1+
# contentstack-cli-tsgen – Agent guide
22

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).
3+
**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
44

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)
5+
## What this repo is
76

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.
7+
| Field | Detail |
8+
| --- | --- |
9+
| **Name:** | [Contentstack-Solutions/contentstack-cli-tsgen](https://github.com/Contentstack-Solutions/contentstack-cli-tsgen) |
10+
| **Purpose:** | OCLIF plugin that adds **`csdx tsgen`** to generate TypeScript typings from a stack. Generation is delegated to **`@contentstack/types-generator`** (`generateTS` / `graphqlTS`); this repo owns flags, auth alias, file output, and CLI error formatting. |
11+
| **Out of scope (if any):** | Core type-generation logic belongs in **`@contentstack/types-generator`** ([npm](https://www.npmjs.com/package/@contentstack/types-generator)), not reimplemented here. |
912

10-
## Tech stack
13+
## Tech stack (at a glance)
1114

1215
| Area | Details |
1316
| --- | --- |
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) |
17+
| **Language** | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) |
18+
| **Build** | **`tsc -b`** → **`lib/`**; **`npm run prepack`** runs compile, **`oclif manifest`**, **`oclif readme`** |
19+
| **Tests** | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)); integration tests under `tests/integration/` |
20+
| **Lint / coverage** | ESLint in **`posttest`** after **`npm test`** ([package.json](package.json)) |
21+
| **Other** | OCLIF, Node (CI **18.x** / **20.x**; release **22.x**) |
2022

2123
**Main dependencies:** `@contentstack/cli-command`, `@contentstack/cli-utilities`, `@contentstack/types-generator`, `dotenv`.
2224

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
25+
## Commands (quick reference)
3126

32-
| Command | Purpose |
27+
| Command type | Command |
3328
| --- | --- |
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 |
29+
| **Build** | `npm run prepack` (canonical compile; no separate `build` script) |
30+
| **Test** | `npm test` (then **`posttest`** → ESLint) |
31+
| **Lint** | via **`posttest`** after tests |
3732

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).
33+
**Integration tests:** `npm run test:integration` — Jest for `tests/integration` only.
34+
35+
CI: [.github/workflows/node.js.yml](.github/workflows/node.js.yml); release: [.github/workflows/release.yml](.github/workflows/release.yml); SCA: [.github/workflows/sca-scan.yml](.github/workflows/sca-scan.yml).
3936

4037
## Credentials and integration tests
4138

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)).
39+
Integration tests spawn **`csdx tsgen`** and require a **delivery token alias**. Set **`TOKEN_ALIAS`** (e.g. **`.env`** at package root; see [tests/integration/tsgen.integration.test.ts](tests/integration/tsgen.integration.test.ts)). CI uses secrets such as **`REGION`**, **`TOKEN_ALIAS`**, **`APIKEY`**, **`DELIVERYKEY`**, **`ENVIRONMENT`**.
40+
41+
## Where the documentation lives: skills
4342

44-
CI uses GitHub secrets such as **`REGION`**, **`TOKEN_ALIAS`**, **`APIKEY`**, **`DELIVERYKEY`**, **`ENVIRONMENT`** (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)).
43+
| Skill | Path | What it covers |
44+
| --- | --- | --- |
45+
| Development workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, CI, prepack, PRs, releases |
46+
| TypeScript CLI tsgen | [skills/typescript-cli-tsgen/SKILL.md](skills/typescript-cli-tsgen/SKILL.md) | OCLIF command, flags, delegation to the library |
47+
| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Jest, ESLint posttest, integration env |
48+
| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist, terminology, semver |
4549

46-
---
50+
An index with “when to use” hints is in [skills/README.md](skills/README.md).
4751

48-
## AI guidance index
52+
## Using Cursor (optional)
4953

50-
- [Cursor rules (overview)](.cursor/rules/README.md)
51-
- [Skills index](skills/README.md)
54+
If you use **Cursor**, [.cursor/rules/README.md](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

‎skills/README.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,16 @@
1-
# Skills for `contentstack-cli-tsgen`
1+
# Skills – contentstack-cli-tsgen
22

3-
Use with [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md).
3+
Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task.
44

5-
| Skill | When to use |
5+
## When to use which skill
6+
7+
| Skill folder | Use when |
68
| --- | --- |
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 |
9+
| [dev-workflow](dev-workflow/SKILL.md) | Branches, CI, prepack, PR and release process |
10+
| [typescript-cli-tsgen](typescript-cli-tsgen/SKILL.md) | OCLIF `tsgen` command, flags, helpers vs library behavior |
11+
| [testing](testing/SKILL.md) | Jest, posttest ESLint, integration tests, `TOKEN_ALIAS`, CI secrets |
12+
| [code-review](code-review/SKILL.md) | PR checklist: CLI UX, errors, Delivery vs CMA wording, types-generator dependency |
13+
14+
HTTP and generation internals live in **`@contentstack/types-generator`** ([npm](https://www.npmjs.com/package/@contentstack/types-generator)); do not assume a sibling checkout.
1015

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.
16+
Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

‎skills/code-review/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,6 @@ description: PR review checklist for contentstack-cli-tsgen (CLI, errors, Delive
55

66
# Code review skill (`contentstack-cli-tsgen`)
77

8-
Aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc).
9-
108
## CLI and docs
119

1210
- Help text, **`static examples`**, and README/oclif-generated docs stay in sync when flags or behavior change.
@@ -27,6 +25,8 @@ Aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.m
2725
## Tests and CI
2826

2927
- Integration tests depend on **`csdx`** and **`TOKEN_ALIAS`**; document env needs when adding cases.
28+
- **Backward compatibility:** Avoid breaking changes to flags, exit behavior, or output file contract without semver intent.
29+
- **Supply chain:** `.github/workflows/sca-scan.yml` runs Snyk on pull requests.
3030

3131
## Optional severity
3232

0 commit comments

Comments
 (0)