From 1eca092d2ceaf4d44202a42aac041be2111f657a Mon Sep 17 00:00:00 2001 From: raj pandey Date: Sun, 19 Apr 2026 05:34:52 +0530 Subject: [PATCH] update: removed rules and moved everything to agents.md --- .cursor/rules/README.md | 17 ++------ .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 | 16 +++++-- AGENTS.md | 65 +++++++++++++++------------- skills/README.md | 19 +++++--- skills/code-review/SKILL.md | 4 +- skills/dev-workflow/SKILL.md | 36 +++++++++++++++ skills/typescript-cli-tsgen/SKILL.md | 9 ++++ 12 files changed, 108 insertions(+), 188 deletions(-) delete mode 100644 .cursor/rules/code-review.mdc delete mode 100644 .cursor/rules/dev-workflow.mdc delete mode 100644 .cursor/rules/oclif-tsgen.mdc delete mode 100644 .cursor/rules/testing.mdc delete mode 100644 .cursor/rules/typescript.mdc create mode 100644 skills/dev-workflow/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md index bc9ca78..f5c1f87 100644 --- a/.cursor/rules/README.md +++ b/.cursor/rules/README.md @@ -1,16 +1,5 @@ -# Cursor rules for `contentstack-cli-tsgen` +# Cursor (optional) -This folder contains project-specific rules. Each `.mdc` file uses YAML frontmatter (`description`, `globs`, `alwaysApply`). +**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**. -| 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. +This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs. diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc deleted file mode 100644 index ac75b45..0000000 --- a/.cursor/rules/code-review.mdc +++ /dev/null @@ -1,28 +0,0 @@ ---- -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 deleted file mode 100644 index 6b2981b..0000000 --- a/.cursor/rules/dev-workflow.mdc +++ /dev/null @@ -1,41 +0,0 @@ ---- -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 deleted file mode 100644 index 80d4f20..0000000 --- a/.cursor/rules/oclif-tsgen.mdc +++ /dev/null @@ -1,33 +0,0 @@ ---- -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 deleted file mode 100644 index fba350f..0000000 --- a/.cursor/rules/testing.mdc +++ /dev/null @@ -1,15 +0,0 @@ ---- -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 deleted file mode 100644 index 222177d..0000000 --- a/.cursor/rules/typescript.mdc +++ /dev/null @@ -1,13 +0,0 @@ ---- -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 a718b70..8ee405a 100644 --- a/.talismanrc +++ b/.talismanrc @@ -3,9 +3,17 @@ fileignoreconfig: ignore_detectors: - filecontent - filename: package-lock.json - checksum: 9cf2ec1b73a078e9f3c974f1a9b7f70864f0307115d1f965b57752ba5a9dcdf2 - - filename: .cursor/rules/oclif-tsgen.mdc - checksum: 83d43465e1b0d7d8c4fd3a13ca4cde13fc5ea2b578186891e3b268ede0e7d97c + checksum: 40cf1a77a8277c0236bdb74dee168a8ca9e0d4fc56706e0006b7ce69743319d7 - filename: AGENTS.md - checksum: 7cce7645c9ebd051f971ea157fc85b691b23c963211debf31729d9ee607c081f + checksum: e442f35176d7263bc2ea3e7f5e112bfb4cbf6aad30f1a768d9695578b1b19636 + - filename: skills/dev-workflow/SKILL.md + checksum: 036381e0d336cec14d0f83ba784f101a12ceaa9b86e486bc049e3aef0594c95b + - filename: skills/README.md + checksum: 6a74a10445c50ddebe3fae7737c04f2bc49c776ffdc8973711463c4d878e6041 + - filename: skills/code-review/SKILL.md + checksum: 3cff88deeefd1fadf5714adf5657effdf5ce839a368dc71e4cb7f88db2cd7ddc + - filename: skills/typescript-cli-tsgen/SKILL.md + checksum: abbe95d052464f5d3434dd36caa7aab62cf6931f223aed70b698dc8f1aff5c28 + - filename: skills/testing/SKILL.md + checksum: 6dbbb85e8eb83ebf0dda715fcd8f9c2704495ed6598a67b7222010d4c91366a5 version: "1.0" diff --git a/AGENTS.md b/AGENTS.md index 728e3bb..b0611d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,51 +1,54 @@ -# `contentstack-cli-tsgen` +# contentstack-cli-tsgen – Agent guide -**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). +**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**. -- **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) +## What this repo is -**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. +| Field | Detail | +| --- | --- | +| **Name:** | [Contentstack-Solutions/contentstack-cli-tsgen](https://github.com/Contentstack-Solutions/contentstack-cli-tsgen) | +| **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. | +| **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. | -## Tech stack +## Tech stack (at a glance) | 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) | +| **Language** | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) | +| **Build** | **`tsc -b`** → **`lib/`**; **`npm run prepack`** runs compile, **`oclif manifest`**, **`oclif readme`** | +| **Tests** | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)); integration tests under `tests/integration/` | +| **Lint / coverage** | ESLint in **`posttest`** after **`npm test`** ([package.json](package.json)) | +| **Other** | OCLIF, Node (CI **18.x** / **20.x**; release **22.x**) | **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 +## Commands (quick reference) -| Command | Purpose | +| Command type | Command | | --- | --- | -| `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 | +| **Build** | `npm run prepack` (canonical compile; no separate `build` script) | +| **Test** | `npm test` (then **`posttest`** → ESLint) | +| **Lint** | via **`posttest`** after tests | -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). +**Integration tests:** `npm run test:integration` — Jest for `tests/integration` only. + +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). ## 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)). +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`**. + +## Where the documentation lives: skills -CI uses GitHub secrets such as **`REGION`**, **`TOKEN_ALIAS`**, **`APIKEY`**, **`DELIVERYKEY`**, **`ENVIRONMENT`** (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)). +| Skill | Path | What it covers | +| --- | --- | --- | +| Development workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, CI, prepack, PRs, releases | +| TypeScript CLI tsgen | [skills/typescript-cli-tsgen/SKILL.md](skills/typescript-cli-tsgen/SKILL.md) | OCLIF command, flags, delegation to the library | +| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Jest, ESLint posttest, integration env | +| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist, terminology, semver | ---- +An index with “when to use” hints is in [skills/README.md](skills/README.md). -## AI guidance index +## Using Cursor (optional) -- [Cursor rules (overview)](.cursor/rules/README.md) -- [Skills index](skills/README.md) +If you use **Cursor**, [.cursor/rules/README.md](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else. diff --git a/skills/README.md b/skills/README.md index 52afd06..2741638 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,11 +1,16 @@ -# Skills for `contentstack-cli-tsgen` +# Skills – contentstack-cli-tsgen -Use with [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md). +Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task. -| Skill | When to use | +## When to use which skill + +| Skill folder | Use when | | --- | --- | -| [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 | +| [dev-workflow](dev-workflow/SKILL.md) | Branches, CI, prepack, PR and release process | +| [typescript-cli-tsgen](typescript-cli-tsgen/SKILL.md) | OCLIF `tsgen` command, flags, helpers vs library behavior | +| [testing](testing/SKILL.md) | Jest, posttest ESLint, integration tests, `TOKEN_ALIAS`, CI secrets | +| [code-review](code-review/SKILL.md) | PR checklist: CLI UX, errors, Delivery vs CMA wording, types-generator dependency | + +HTTP and generation internals live in **`@contentstack/types-generator`** ([npm](https://www.npmjs.com/package/@contentstack/types-generator)); do not assume a sibling checkout. -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. +Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`). diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 51186de..0bf41b6 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -5,8 +5,6 @@ description: PR review checklist for contentstack-cli-tsgen (CLI, errors, Delive # 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. @@ -27,6 +25,8 @@ Aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.m ## Tests and CI - Integration tests depend on **`csdx`** and **`TOKEN_ALIAS`**; document env needs when adding cases. +- **Backward compatibility:** Avoid breaking changes to flags, exit behavior, or output file contract without semver intent. +- **Supply chain:** `.github/workflows/sca-scan.yml` runs Snyk on pull requests. ## Optional severity diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..b1fb32e --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,36 @@ +--- +name: dev-workflow +description: Branches, prepack, CI, PR and release workflow for contentstack-cli-tsgen. +--- + +# Development workflow – contentstack-cli-tsgen + +## When to use + +- Running the canonical build before pack or publish +- Understanding which branches run CI and how releases work + +## Branches and CI + +- **Node.js workflow** (`.github/workflows/node.js.yml`) runs on **push** and **pull_request** for **`master`**, **`development`**, and **`staging`**. +- **Release** (`.github/workflows/release.yml`) runs on **push** to **`master`** (Node **22.x**), publishes npm artifact from **`lib`**, creates GitHub release. + +Other Contentstack repos may use **`main`** instead of **`master`**; align with team branch protection when contributing. + +## Build + +- **`npm run prepack`**: removes **`lib/`**, runs **`tsc -b`**, **`oclif manifest`**, **`oclif readme`**. This is the canonical compile before pack/publish. +- CI runs **`prepack`** after global **`csdx`** setup and **`plugins:link`** where applicable. + +## 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 runs **`posttest`**) when changing source or tests. + +## Releases + +- Version in **`package.json`** drives publishing; release workflow builds with **`prepack`** from **`master`**. diff --git a/skills/typescript-cli-tsgen/SKILL.md b/skills/typescript-cli-tsgen/SKILL.md index b6e82de..eb7a1dc 100644 --- a/skills/typescript-cli-tsgen/SKILL.md +++ b/skills/typescript-cli-tsgen/SKILL.md @@ -25,3 +25,12 @@ description: Mental model for the contentstack-cli-tsgen OCLIF plugin and tsgen ## OCLIF - Commands compile to **`lib/commands`**; **`prepack`** refreshes **`oclif.manifest.json`** and README. + +### Command shape (`tsgen`) + +- Extends **`Command`** from **`@contentstack/cli-command`** ([`src/commands/tsgen.ts`](../../src/commands/tsgen.ts)). +- **Flags** include **`token-alias`** (`-a`, required), **`output`** (`-o`), **`prefix`**, **`doc`**, **`branch`**, **`include-system-fields`**, **`include-editable-tags`**, **`include-referenced-entry`**, **`api-type`** (`rest` \| `graphql`), **`namespace`** (GraphQL). +- Resolve token via **`this.getToken(flags["token-alias"])`**; warn if **`token.type !== "delivery"`** (management token can break Delivery/GraphQL flows). +- Build **`StackConnectionConfig`**: **`apiKey`**, **`token`**, **`region`**, **`environment`**, **`branch`**, **`host`** as in existing code. +- **`api-type === "graphql"`** → **`graphqlTS(...)`** with delivery token; **REST** → **`generateTS`** with **`tokenType: "delivery"`**; write output with **`fs.writeFileSync`** to the resolved path. +- Use **`printFormattedError`** from [`src/lib/helper.ts`](../../src/lib/helper.ts) for consistent CLI messaging.