Skip to content

Commit 30afae3

Browse files
harshitha-cstkharshitha-cstk
committed
docs: add AGENTS.md, Cursor rules, and agent skills
Extend .talismanrc to skip false-positive secret scans on markdown guidance files. Made-with: Cursor
1 parent f4bde4b commit 30afae3

File tree

12 files changed

+400
-0
lines changed

12 files changed

+400
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Cursor rules — `@contentstack/utils`
2+
3+
This folder holds project-specific rules for AI assistants working in **contentstack-utils-javascript**. For the full project overview, see **[`AGENTS.md`](../../AGENTS.md)** at the repository root.
4+
5+
## How rules are picked up
6+
7+
Each rule is a `.md`/`.mdc` file. Files with YAML frontmatter can set `description`, `globs`, and `alwaysApply`. Cursor uses these to decide when a rule is included in context.
8+
9+
### Referencing rules in chat
10+
11+
In Cursor, you can **`@`-mention** a rule file (e.g. type `@` and choose the rule from the list) to force its guidance into the conversation. The file name (without extension) is the usual handle, e.g. **`typescript`**, **`testing`**, **`code-review`**.
12+
13+
## Rule index
14+
15+
| File | `alwaysApply` | Globs | When it applies |
16+
|------|----------------|-------|------------------|
17+
| [`dev-workflow.md`](dev-workflow.md) | no | *(none)* | Branching, CI alignment, commits, releases, and day-to-day commands for this repo. |
18+
| [`typescript.mdc`](typescript.mdc) | no | `src/**/*.ts`, `__test__/**/*.ts` | TypeScript version, layout, ESLint/Prettier, strictness, imports. |
19+
| [`typescript-contentstack-utils.mdc`](typescript-contentstack-utils.mdc) | no | `src/**/*.ts` | Delivery-oriented utils only: RTE rendering, GQL helpers, endpoints JSON, Live Preview tags—**not** full CDA/CMA SDK surface. |
20+
| [`testing.mdc`](testing.mdc) | no | `__test__/**/*.ts` | Jest, jsdom, mocks, coverage output paths, no live-test env. |
21+
| [`code-review.mdc`](code-review.mdc) | **yes** | *(global)* | PR checklist: public API docs, compatibility, errors, dependencies, terminology (utils + delivery context). |
22+
23+
## Related
24+
25+
- **[`AGENTS.md`](../../AGENTS.md)** — Single entry point (package purpose, stack, commands).
26+
- **[`skills/README.md`](../../skills/README.md)** — Longer-form skill docs for the same themes.

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

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
description: PR review checklist for @contentstack/utils — API docs, compatibility, security, testing
3+
alwaysApply: true
4+
---
5+
6+
# Code review checklist — `@contentstack/utils`
7+
8+
Use severity labels (**Blocker / Major / Minor**) when triaging findings.
9+
10+
## Public API and documentation
11+
12+
- **Blocker/Major:** New or changed **exports** from `src/index.ts` need accurate **JSDoc** (or clear type names) matching runtime behavior.
13+
- **Major:** README / CHANGELOG updates when behavior is user-visible or migration is needed.
14+
15+
## Backward compatibility
16+
17+
- **Blocker:** Unplanned breaking changes to **function signatures** or **default behavior** consumed by Delivery SDK integrations or documented `renderOption` contracts.
18+
- **Major:** Stricter throwing on inputs that previously passed (especially `getContentstackEndpoint`, RTE traversals).
19+
20+
## Errors
21+
22+
- This package uses **plain `Error`** (e.g. `endpoints.ts`); new code should keep messages actionable. **Major:** Silent failures where callers need to detect bad input.
23+
24+
## Null safety and RTE edge cases
25+
26+
- **Major:** Missing guards on **null/undefined** node or entry fragments (historically sensitive in `entry-editable` / RTE paths).
27+
- **Minor:** Align with **`strictNullChecks: false`** legacy but avoid widening undefined leaks into public types.
28+
29+
## Dependencies and SCA
30+
31+
- **Major:** New runtime deps are rare—justify any addition; **`prepublishOnly`** and hooks assume **`npm test`** and Snyk-friendly trees.
32+
- Use **`npm audit` / Snyk** expectations per org policy.
33+
34+
## Tests
35+
36+
- **Blocker:** Behavioral fixes or new branches without **`__test__`** coverage when risk is high (RTE nesting, GQL URL rewriting, endpoint resolution).
37+
- **Minor:** Snapshot-only tests where a small assertion would be clearer.
38+
39+
## Terminology
40+
41+
- **Major:** Docs/comments must describe this as **utils** alongside **CDA / Delivery / JSON RTE / GraphQL**, not as **CMA** unless the change is explicitly management-related.

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
description: Branching, CI, local commands, commit hooks, and release flow for contentstack-utils-javascript
3+
alwaysApply: false
4+
---
5+
6+
# Dev workflow — `@contentstack/utils`
7+
8+
## Branches and PRs
9+
10+
- **CI** (`Unit-Test-CI`) runs on **push/PR** to `development`, `staging`, and `master` (see `.github/workflows/ci.yml`).
11+
- **Branch protection:** A workflow fails PRs that target **`staging`** when the head branch is **not** `development` (see `.github/workflows/check-branch.yml`). Prefer **`development`** as the integration branch when contributing upstream.
12+
- Target the branch your team uses for integration; align with maintainers if unsure.
13+
14+
## Local development
15+
16+
| Task | Command / note |
17+
|------|----------------|
18+
| Build | `npm run build` (runs `prebuild`: clean `dist`, `download-regions`, then `tsc` + Rollup) |
19+
| Test | `npm test` (includes `pretest` → build; Jest + coverage; `reports/`) |
20+
| Format | `npm run format` (Prettier: `src/**/*.ts`) |
21+
| ESLint | No `lint` script in `package.json`; run e.g. `npx eslint src __test__` using `eslint.config.js` |
22+
23+
## Git hooks (Husky)
24+
25+
- **`commit-msg`:** [Conventional Commits](https://www.conventionalcommits.org/) via **`commitlint`** (`.commitlintrc.json`).
26+
- **`pre-commit`:** Requires **Snyk** (`snyk test --all-projects`) and **Talisman** installed locally. Set `SKIP_HOOK=1` to bypass (documented in the hook).
27+
28+
## PR expectations
29+
30+
- **`npm test`** passes (build + unit tests).
31+
- **CHANGELOG.md** updated for user-visible changes when maintainers expect it.
32+
- **Dependencies:** Be mindful of Snyk/SCA workflows; security-relevant bumps should be justified.
33+
34+
## Releases and versioning
35+
36+
- **Package version** lives in **`package.json`** (also reflected in **`CHANGELOG.md`**).
37+
- **`prepublishOnly`** runs **`npm test`** before publish.
38+
- **NPM / GitHub Packages:** Publishing is driven by **GitHub release `created`** (`.github/workflows/npm-publish.yml`); requires maintainer secrets (`NPM_TOKEN`, `GIT_TOKEN`). Bump version and changelog in the same change set as the release your team uses.

‎.cursor/rules/testing.mdc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
description: Jest tests, mocks, reports, and environments for @contentstack/utils
3+
globs:
4+
- __test__/**/*.ts
5+
alwaysApply: false
6+
---
7+
8+
# Testing — `@contentstack/utils`
9+
10+
## Framework
11+
12+
- **Jest 29** with **`ts-jest`** preset (`jest.config.ts`).
13+
- **Environment:** **`jsdom`** (suitable for HTML string assertions and DOM-related behavior).
14+
15+
## Discovery and naming
16+
17+
- **Pattern:** `**/__test__/**/?(*.)+(spec|test).[jt]s?(x)` — this repo uses `*.test.ts` under **`__test__/`**.
18+
- **Mocks / fixtures:** `__test__/mock/*.ts` — follow existing mock naming (`*-mock.ts`).
19+
20+
## Coverage and reports
21+
22+
- **Coverage** is collected from `src/**` excluding `src/index.ts` (`collectCoverageFrom`).
23+
- Outputs: **`reports/coverage/`**, **`reports/html/`** (jest-html-reporters), **`reports/junit/`** (jest-junit), **`reports/report.json`** (from `npm test` script).
24+
25+
## Running tests
26+
27+
| Command | Behavior |
28+
|---------|----------|
29+
| `npm test` | Runs **`pretest` → build** then Jest (CI-aligned). |
30+
| `npm run test:debug` | Watch mode, `--runInBand`. |
31+
32+
## Integration / live tests
33+
34+
- **None** in this repo. No `.env` or stack credentials required for **`npm test`**.
35+
36+
## Build dependency
37+
38+
- **`npm test` always builds first** (`pretest`). Ensure **`src/assets/regions.json`** exists or can be downloaded so `endpoints` tests pass.

‎.cursor/rules/typescript-contentstack-utils.mdc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
description: Contentstack utils package patterns — RTE, embedded items, GQL, endpoints (delivery-oriented companion, not CDA/CMA SDK)
3+
globs:
4+
- src/**/*.ts
5+
alwaysApply: false
6+
---
7+
8+
# `@contentstack/utils` — domain patterns
9+
10+
This repository implements **companion utilities** for Contentstack **content consumption** scenarios (typically with the **Delivery SDK** and **CDA / GraphQL** responses). It does **not** implement stack configuration, delivery tokens, or HTTP clients—callers fetch entry JSON elsewhere and pass it into these helpers.
11+
12+
## Mental model
13+
14+
| Area | Source anchors | Notes |
15+
|------|----------------|-------|
16+
| Render options / callbacks | `src/options/`, `src/render-embedded-objects.ts` | `RenderOption`-style maps: node types, marks, `block` / `inline` embeds, `reference`, `display`, `default`. |
17+
| JSON RTE → HTML | `src/json-to-html.ts`, `src/nodes/*`, `src/helper/*` | Supercharged RTE path uses `paths` arrays for nested fields (see `README.md`). |
18+
| Embedded object types | `src/Models/embedded-object.ts`, `src/Models/json-rte-model.ts` | Align typings with shapes coming from **delivery** entry JSON, not management APIs. |
19+
| GraphQL | `src/gql.ts`, `src/updateAssetURLForGQL.ts` | Docs/comments describe use **after** GraphQL fetches; asset URL rewriting is response-shape specific. |
20+
| Live Preview / CSLP tags | `src/entry-editable.ts` | `addTags` / exported `addEditableTags` — preserve existing attribute and locale behavior when changing tag generation. |
21+
| Region endpoints | `src/endpoints.ts` | **`getContentstackEndpoint(region, service?, omitHttps?)`** reads **`src/assets/regions.json`**; throws plain `Error` with human-readable messages on bad region/service. |
22+
23+
## Terminology
24+
25+
- Prefer **CDA / Delivery / JSON RTE / GraphQL** vocabulary when describing behavior—**not** CMA unless you are explicitly discussing something management-only (rare here).
26+
- **“SDK”** in docs often means **this utils package** or the **Delivery SDK** together—disambiguate in user-facing text.
27+
28+
## Concurrency / IO
29+
30+
- Pure synchronous transforms dominate; no retry or rate-limit layer. Do not add HTTP clients without an explicit product requirement.
31+
32+
## Official docs alignment
33+
34+
- Behavior should stay consistent with current **Content Delivery** / **Live Preview** / **JSON RTE** documentation. When in doubt, cite the relevant Contentstack doc set in PR descriptions rather than guessing CMS semantics.

‎.cursor/rules/typescript.mdc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
description: TypeScript conventions for @contentstack/utils (src and tests)
3+
globs:
4+
- src/**/*.ts
5+
- __test__/**/*.ts
6+
alwaysApply: false
7+
---
8+
9+
# TypeScript — `@contentstack/utils`
10+
11+
## Tooling
12+
13+
- **TypeScript ~4.9** (`package.json`, `tsconfig.json`).
14+
- **Bundler output:** `tsc` emits to `dist/lib` with declarations in `dist/types`; **Rollup** produces `dist/index.es.js` (`rollup.config.js`).
15+
- **Strict mode** is on with **`strictNullChecks: false`** — new code should still minimize unnecessary null/undefined gaps when touching APIs.
16+
17+
## Layout
18+
19+
- **Library code:** `src/**/*.ts` only (`tsconfig.json` `include`); **tests** are under `__test__/` (excluded from `tsc` program but type-checked via Jest/tsconfig paths).
20+
- **Public exports:** Maintain **`src/index.ts`** as the single export surface unless intentionally adding secondary entry points.
21+
22+
## Style and lint
23+
24+
- Match existing naming (PascalCase types, camelCase functions, existing file layout under `Models/`, `nodes/`, `helper/`, `options/`).
25+
- **ESLint** flat config: `eslint.config.js` — `@typescript-eslint` recommended for `__test__`; source files use `js.configs.recommended` baseline.
26+
- **Prettier:** `npm run format` scopes `src/**/*.ts`; keep formatting consistent when editing tests too.
27+
28+
## JSON / assets
29+
30+
- **`src/assets/regions.json`:** Consumed by `src/endpoints.ts`; populated by **`npm run download-regions`** during `prebuild`. Do not assume the file is committed (see root `.gitignore`).
31+
32+
## Logging
33+
34+
- No shared logger dependency; avoid introducing `console` noise in library paths unless consistent with nearby code.

‎.talismanrc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,9 @@ fileignoreconfig:
2626
checksum: a843710fc9f54bf4c7996f39561dc66491d62a9d9eeca50fa2c7c37bd6141f53
2727
- filename: src/render-embedded-objects.ts
2828
checksum: 35d56d4f7b625611fef18414fccdbff014c1d90d02e17eb0efa4d6166b73e23b
29+
- filename: .cursor/rules/code-review.mdc
30+
checksum: 43d4fddb706e5ad6c92fe0af30bd5f44eec9b83c31dc93d3d4cc5e6208d351cc
31+
- filename: .cursor/rules/dev-workflow.md
32+
checksum: b9a4d68439ce9564730506ab6c4712f5034a645858bdb78ac57e43ba183cb981
33+
- filename: skills/code-review/SKILL.md
34+
checksum: 4ec638a87a795e5cc0b0e66b569e04749cb27f9d3be29d4ea69f56b48225c943

‎AGENTS.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Agent guidance — `@contentstack/utils`
2+
3+
## What this package is
4+
5+
**[@contentstack/utils](https://www.npmjs.com/package/@contentstack/utils)** (`contentstack-utils-javascript`) is a **JavaScript/TypeScript utilities library** for Contentstack. It is **not** the Content Delivery API (CDA) SDK or the Content Management API (CMA) SDK. It focuses on **JSON RTE / Supercharged RTE** rendering (`jsonToHTML`), **embedded entry and asset** rendering (`render`, `renderContent`), **GraphQL-oriented helpers** (`GQL`, `updateAssetURLForGQL`), **Live Preview–style editable tags** (`addEditableTags` / `addTags`), and **region endpoint lookup** (`getContentstackEndpoint`). Typical usage is **alongside** the Delivery SDK (see repository `README.md` examples with `@contentstack/delivery-sdk`).
6+
7+
- **Repository:** [github.com/contentstack/contentstack-utils-javascript](https://github.com/contentstack/contentstack-utils-javascript)
8+
9+
## Tech stack
10+
11+
| Area | Details |
12+
|------|---------|
13+
| Language | TypeScript **4.9** (`tsconfig.json`, `strict: true`, `strictNullChecks: false`) |
14+
| Build | **TypeScript** (`tsc`) → `dist/lib`; **Rollup** (`rollup -c`) → `dist/index.es.js`; types in `dist/types/` |
15+
| Test | **Jest 29** + **ts-jest**, **jsdom** environment (`jest.config.ts`) |
16+
| Lint / format | **ESLint 9** flat config (`eslint.config.js`); **Prettier 3** (`npm run format`) — there is **no** `lint` npm script; use `npx eslint` as needed |
17+
| Runtime HTTP / JSON for API calls | **None** in library code; `regions.json` is a **build-time** asset (see below) |
18+
19+
## Source layout and public API
20+
21+
| Role | Path |
22+
|------|------|
23+
| Public entry (sources) | `src/index.ts` |
24+
| Options / render types | `src/options/` |
25+
| RTE / node model | `src/Models/`, `src/nodes/` |
26+
| Helpers | `src/helper/` |
27+
| GQL + asset URL rewrite | `src/gql.ts`, `src/updateAssetURLForGQL.ts` |
28+
| Endpoints helper | `src/endpoints.ts` + `src/assets/regions.json` (generated; see build) |
29+
| Published bundle | `dist/` (per `package.json` `main` / `types`) |
30+
31+
## Common commands
32+
33+
| Command | Purpose |
34+
|---------|---------|
35+
| `npm run build` | Cleans `dist`, ensures `src/assets/regions.json` (download or warning), runs `tsc` + Rollup |
36+
| `npm test` | Runs `pretest` → **build**, then Jest with coverage; outputs under `reports/` |
37+
| `npm run test:debug` | Jest watch, in-band |
38+
| `npm run format` | Prettier on `src/**/*.ts` |
39+
| `npm run download-regions` | Fetches `regions.json` only (used by `prebuild`) |
40+
41+
**Tests:** Unit tests only, under `__test__/**/*.test.ts`, with mocks in `__test__/mock/`. There are **no** live/integration tests requiring stack credentials in this repository.
42+
43+
## Credentials / environment
44+
45+
- **Unit tests:** No API keys or `.env` required.
46+
- **Build:** `download-regions` calls a public URL (`artifacts.contentstack.com`); offline builds may warn and rely on an existing `src/assets/regions.json`. Note `regions.json` is listed in `.gitignore`; clones may need a successful `npm run build` (or manual file) before tests pass.
47+
- **Publish:** GitHub release workflow uses `NPM_TOKEN` / `GIT_TOKEN` secrets (maintainers only).
48+
49+
## More detail for AI / IDE rules
50+
51+
- [`.cursor/rules/README.md`](.cursor/rules/README.md) — Cursor rules index (`alwaysApply`, globs, when to use).
52+
- [`skills/README.md`](skills/README.md) — Topic skills (testing, code review, package mental model).

‎skills/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Skills — `@contentstack/utils`
2+
3+
Short-form guides for humans and agents. Root context: **[`AGENTS.md`](../AGENTS.md)**. Cursor rule index: **[`.cursor/rules/README.md`](../.cursor/rules/README.md)**.
4+
5+
| Skill | When to use |
6+
|-------|--------------|
7+
| [`code-review/`](code-review/SKILL.md) | Before opening or approving a PR; expanded checklist (API docs, compatibility, errors, tests, terminology). |
8+
| [`testing/`](testing/SKILL.md) | Running Jest, understanding `pretest`/build, mocks, reports, and why no live API tests exist here. |
9+
| [`typescript-contentstack-utils/`](typescript-contentstack-utils/SKILL.md) | Mental map of RTE/embed/GQL/endpoints/Live Preview code paths and where to change behavior safely. |
10+
11+
There is **no** separate `framework` skill: this repo has **no** shared HTTP client or retry layer.

‎skills/code-review/SKILL.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Skill: Code review — `@contentstack/utils`
2+
3+
## When to use
4+
5+
Final pass before merge, or when authoring a PR to self-check against team expectations.
6+
7+
## Checklist (expanded)
8+
9+
### Public API and docs
10+
11+
- Exported symbols from **`src/index.ts`** stay coherent: names match behavior, types match real JSON RTE / entry shapes from **delivery** content.
12+
- **JSDoc** on public functions (`getContentstackEndpoint`, `jsonToHTML`, `render`, GQL helpers, etc.) matches parameters, throws, and return shapes.
13+
- **README.md** examples remain valid for **`@contentstack/delivery-sdk`** + **`Contentstack.Utils`** style usage when touching those flows.
14+
15+
### Backward compatibility
16+
17+
- Avoid breaking **`RenderOption`** callback contracts or default HTML output without a major version plan and **CHANGELOG** entry.
18+
- Changes to **`regions.json`** / endpoint keys must stay aligned with upstream region definitions.
19+
20+
### Errors
21+
22+
- Prefer clear **`Error`** messages for invalid regions, missing services, or malformed internal state—callers often log these verbatim.
23+
24+
### Security and dependencies
25+
26+
- New **npm dependencies** need justification (`package.json` is dev-heavy already).
27+
- No secrets or tokens in code; **Talisman** pre-commit enforces secret scanning locally for contributors with hooks installed.
28+
29+
### Tests
30+
31+
- **`npm test`** must pass (includes full **build**).
32+
- Add or update **`__test__`** cases for RTE edge cases, GQL URL rewriting, and endpoint error paths when logic changes.
33+
34+
### Severity rubric (optional)
35+
36+
| Level | Examples |
37+
|-------|-----------|
38+
| **Blocker** | Breaks published API, break consumers without semver major, removes tests on critical path |
39+
| **Major** | Missing docs for new export, behavior change without tests, confusing error surfaces |
40+
| **Minor** | Naming nits, internal refactors with equivalent coverage |
41+
42+
### Terminology
43+
44+
- Use **delivery / CDA / JSON RTE / GraphQL / Live Preview** context—not **CMA**—unless the work truly relates to management APIs.

0 commit comments

Comments
 (0)