Skip to content

Commit b64f295

Browse files
sunil-lakshmansunil-lakshman
committed
Enh: Added cursor rules and skills
1 parent 03f2118 commit b64f295

File tree

12 files changed

+345
-0
lines changed

12 files changed

+345
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Cursor Rules — `contentstack_utils`
2+
3+
Rules for **contentstack-utils-python**: Python **utils** package for **RTE / embedded** rendering, **GQL**, and **editable tags** (companion to the Contentstack Python SDK).
4+
5+
## Rules overview
6+
7+
| Rule | Role |
8+
|------|------|
9+
| [`dev-workflow.md`](dev-workflow.md) | Branch/PR, venv, **pytest**, lint (**ruff** / **black** / **flake8**) |
10+
| [`python.mdc`](python.mdc) | Python layout, `contentstack_utils/`, `setup.py` |
11+
| [`contentstack-utils-python.mdc`](contentstack-utils-python.mdc) | **Utils**, **Options**, RTE/embedded, **GQL**, **entry_editable** |
12+
| [`testing.mdc`](testing.mdc) | **pytest** under **`tests/`** |
13+
| [`code-review.mdc`](code-review.mdc) | PR checklist (**always applied**) |
14+
15+
## Rule application
16+
17+
| Context | Typical rules |
18+
|---------|----------------|
19+
| **Every session** | `code-review.mdc` |
20+
| **Most files** | `dev-workflow.md` |
21+
| **`contentstack_utils/`** | `python.mdc` + `contentstack-utils-python.mdc` |
22+
| **`tests/**`** | `testing.mdc` |
23+
| **`setup.py` / packaging** | `python.mdc` |
24+
25+
## Quick reference
26+
27+
| File | `alwaysApply` | Globs (summary) |
28+
|------|---------------|-----------------|
29+
| `dev-workflow.md` | no | `**/*.py`, `requirements.txt`, `setup.py` |
30+
| `python.mdc` | no | `contentstack_utils/**/*.py`, `setup.py` |
31+
| `contentstack-utils-python.mdc` | no | `contentstack_utils/**/*.py` |
32+
| `testing.mdc` | no | `tests/**/*.py` |
33+
| `code-review.mdc` | **yes** | — |
34+
35+
## Skills
36+
37+
- [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
description: "PR checklist for contentstack_utils — public API, semver, tests, secrets"
3+
alwaysApply: true
4+
---
5+
6+
# Code review — `contentstack_utils`
7+
8+
## Public API
9+
10+
- **`contentstack_utils/__init__.py`** **`__all__`** and exports match **README** examples and intended surface (**`Utils`**, **`Options`**, **`GQL`**, **`Automate`**, embed types, **`addEditableTags`** / **`addTags`** / **`getTag`**).
11+
- **JS parity** — where methods mirror the JS utils SDK, keep **parameter names** and behavior consistent unless a documented breaking change.
12+
13+
## Compatibility
14+
15+
- Avoid breaking **`Utils`** / **`Options`** / tag helpers without a **semver** plan; bump **`setup.py` `version`** for user-visible changes.
16+
17+
## Dependencies
18+
19+
- **`lxml`** usage stays bounded to parsing/rendering paths; note any new **install_requires** in **README** / changelog if added to **`setup.py`**.
20+
21+
## Tests
22+
23+
- **`pytest`** passes for changed behavior; add or extend tests under **`tests/`** for new branches and edge cases.
24+
25+
## Security
26+
27+
- No hardcoded tokens; no logging of secrets in new code.

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
description: "Contentstack Python Utils — Utils, Options, RTE/embedded, GQL, editable tags"
3+
globs: ["contentstack_utils/**/*.py"]
4+
alwaysApply: false
5+
---
6+
7+
# Contentstack Python Utils (`contentstack_utils/`)
8+
9+
## Core entry points
10+
11+
- **`Utils`** — **`contentstack_utils.utils`**: **`render_content`**, **`render`**, embedded/RTE resolution; subclasses **`Automate`**.
12+
- **`Options`** — **`contentstack_utils.render.options`**: rendering configuration passed into **`Utils`** methods.
13+
- **Editable tags** — **`entry_editable`**: **`addEditableTags`**, **`addTags`**, **`getTag`**; also exposed as **`Utils.addEditableTags`** / **`Utils.addTags`** / **`Utils.getTag`** for parity.
14+
15+
## Features
16+
17+
- **Embedded / RTE** — JSON and HTML paths through **`Utils`** and **`Automate`**; **metadata** via **`Metadata`**.
18+
- **Styles** — **`convert_style`** and **embedded** **StyleType** / **ItemType** where applicable.
19+
- **GQL** — **`GQL`** in **`gql.py`** for GraphQL-oriented HTML/helpers.
20+
21+
## Companion SDK
22+
23+
- Consumers often use **`contentstack.Stack`** ( **`Contentstack`** package) to fetch entries, then **`Utils.render`** / **`Utils.render_content`** on field data — keep examples in **README** accurate.
24+
25+
## Docs
26+
27+
- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
description: "Branches, venv, pytest, and lint for contentstack-utils-python"
3+
globs: ["**/*.py", "requirements.txt", "setup.py"]
4+
alwaysApply: false
5+
---
6+
7+
# Development workflow — `contentstack_utils`
8+
9+
## Before a PR
10+
11+
1. **Install** — `pip install -r requirements.txt` and `pip install -e .` in a virtual environment.
12+
2. **`pytest`** — full suite under **`tests/`** must pass.
13+
3. **Lint / format** — run **ruff**, **black**, **flake8**, **isort** as configured for the repo (see **`requirements.txt`**).
14+
4. **Version** — update **`setup.py` `version`** for releases per semver.
15+
16+
## Branching
17+
18+
- Follow org conventions: **`development`** / **`staging`** / **`master`**; PRs to **`master`** may be restricted (see **`.github/workflows/check-branch.yml`**).
19+
20+
## Links
21+
22+
- [`AGENTS.md`](../../AGENTS.md) · [`skills/contentstack-utils-python/SKILL.md`](../../skills/contentstack-utils-python/SKILL.md)

‎.cursor/rules/python.mdc‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
description: "Python conventions for contentstack_utils package and setup"
3+
globs:
4+
- "contentstack_utils/**/*.py"
5+
- "setup.py"
6+
alwaysApply: false
7+
---
8+
9+
# Python — `contentstack_utils`
10+
11+
## Layout
12+
13+
- **`contentstack_utils/utils.py`** — **`Utils`** class (rendering, embedded items); delegates **editable tag** static methods to **`entry_editable`**.
14+
- **`contentstack_utils/render/`** — **`Options`** and render-related code.
15+
- **`contentstack_utils/helper/`** — **Metadata**, **NodeToHtml**, **converter**.
16+
- **`contentstack_utils/embedded/`** — **ItemType**, **StyleType**.
17+
- **`contentstack_utils/gql.py`**, **`automate.py`**, **`entry_editable.py`** — feature modules.
18+
19+
## Style
20+
21+
- Match existing patterns: **typing** hints where already used; **pylint** pragmas only where established.
22+
- Prefer **small, focused** changes; avoid drive-by refactors unrelated to the task.
23+
24+
## Imports
25+
26+
- **`lxml.etree`** — HTML/XML parsing in **`utils`** and helpers; keep usage consistent with existing error handling.
27+
28+
## Packaging
29+
30+
- **`setup.py`** — **`name`**, **`version`**, **`packages=find_packages()`**; keep **`install_requires`** accurate if dependencies change.
31+
32+
## Security
33+
34+
- Do not log **delivery tokens**, **API keys**, or stack secrets.

‎.cursor/rules/testing.mdc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
description: "pytest for contentstack-utils-python"
3+
globs:
4+
- "tests/**/*.py"
5+
alwaysApply: false
6+
---
7+
8+
# Testing — `contentstack_utils`
9+
10+
## pytest
11+
12+
- Tests live in **`tests/`** as **`test_*.py`** modules.
13+
- Run: **`pytest`** from the repo root (with venv and **`requirements.txt`** installed).
14+
- Optional HTML report: **`pytest --html=tests/test-report/test-report.html --self-contained-html`** (path may vary; align with local **pytest-html** output).
15+
16+
## Coverage
17+
18+
- **`coverage run -m pytest`** then **`coverage report -m`** (or **`coverage html`**) for coverage review.
19+
20+
## Mocks
21+
22+
- Shared mock data under **`tests/mocks/`** (e.g. **supercharged** fixtures) — reuse for new cases instead of duplicating large JSON.
23+
24+
## Hygiene
25+
26+
- No committed **`pytest.mark.skip`** or **`xfail`** without justification; no **`breakpoint()`** left in CI paths.

‎AGENTS.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# AGENTS.md — AI / automation context
2+
3+
## Project
4+
5+
| | |
6+
|---|---|
7+
| **Name** | **`contentstack_utils`** (PyPI) — **Contentstack Python Utils SDK** |
8+
| **Purpose** | Utilities for **Contentstack** headless CMS: **RTE / embedded** rendering (`Utils`, `Options`), **GQL** helpers, **editable tags** on entries, HTML/metadata helpers. Often used alongside the **`Contentstack`** Python delivery package. |
9+
| **Repository** | [contentstack/contentstack-utils-python](https://github.com/contentstack/contentstack-utils-python.git) |
10+
11+
## Tech stack
12+
13+
| Area | Details |
14+
|------|---------|
15+
| **Language** | **Python** (`python_requires` in `setup.py`; classifiers list 3.6–3.9; dev tooling in `requirements.txt` may need a newer interpreter) |
16+
| **Package** | **`setuptools`** — `find_packages()`, `contentstack_utils/` |
17+
| **Runtime deps** | **`lxml`** (XML/HTML parsing in `utils.py` and helpers) |
18+
| **Tests** | **pytest** + **pytest-cov**, **pytest-html** (optional HTML report) |
19+
| **Lint / format** | **ruff**, **black**, **flake8**, **isort** (see `requirements.txt`) |
20+
21+
## Source layout
22+
23+
| Path | Role |
24+
|------|------|
25+
| `contentstack_utils/utils.py` | **`Utils`** — `render_content`, embedded/RTE flows; extends **`Automate`** |
26+
| `contentstack_utils/render/options.py` | **`Options`** for rendering |
27+
| `contentstack_utils/helper/` | **Metadata**, **NodeToHtml**, **converter** (e.g. `convert_style`) |
28+
| `contentstack_utils/embedded/` | **ItemType**, **StyleType** |
29+
| `contentstack_utils/gql.py` | **GQL** helpers |
30+
| `contentstack_utils/automate.py` | **`Automate`** base for automation-style rendering |
31+
| `contentstack_utils/entry_editable.py` | **`addEditableTags`**, **`addTags`**, **`getTag`**; re-exported via **`Utils`** static methods and package **`__init__`** |
32+
| `contentstack_utils/__init__.py` | Public exports — keep **`__all__`** aligned with documented API |
33+
| `tests/` | pytest modules (`test_*.py`), mocks under `tests/mocks/` |
34+
35+
## Common commands
36+
37+
```bash
38+
python -m venv .venv && source .venv/bin/activate # or equivalent on Windows
39+
pip install -r requirements.txt
40+
pip install -e .
41+
pytest
42+
pytest --html=tests/test-report/test-report.html --self-contained-html
43+
coverage run -m pytest && coverage report -m
44+
```
45+
46+
## Security
47+
48+
- Do not commit **API keys**, **delivery tokens**, or other secrets. Examples in **`README.md`** use placeholders only.
49+
50+
## Further guidance
51+
52+
- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
53+
- **Skills:** [`skills/README.md`](skills/README.md)
54+
55+
Product docs: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).

‎skills/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Project skills — `contentstack_utils`
2+
3+
| Skill | When to use |
4+
|-------|-------------|
5+
| [`code-review/`](code-review/SKILL.md) | PR review, semver, public **`__all__`**, dependency changes |
6+
| [`testing/`](testing/SKILL.md) | **pytest**, coverage, **`tests/mocks`** |
7+
| [`contentstack-utils-python/`](contentstack-utils-python/SKILL.md) | **`Utils`**, **`Options`**, RTE/embedded, **GQL**, editable tags |
8+
| [`framework/`](framework/SKILL.md) | **`lxml`**, companion **`Contentstack`** Python SDK usage |
9+
10+
**Overview:** [`AGENTS.md`](../AGENTS.md) · **Rules:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)

‎skills/code-review/SKILL.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: code-review
3+
description: PR review for contentstack_utils — public API, __all__, lxml/deps, pytest.
4+
---
5+
6+
# Code review — `contentstack_utils`
7+
8+
## Checklist
9+
10+
- [ ] **API:** New or changed **`Utils`** / **`Options`** / tag helpers reflected in **`contentstack_utils/__init__.py`** **`__all__`** and **README** if user-facing.
11+
- [ ] **Version:** **`setup.py` `version`** bumped when releasing behavioral or API changes (semver).
12+
- [ ] **Dependencies:** Any new **`install_requires`** entry documented; **`lxml`** usage stays appropriate for parsing/rendering.
13+
- [ ] **Tests:** **`pytest`** passes; add tests under **`tests/`** for new behavior.
14+
- [ ] **Secrets:** No tokens in repo; examples use placeholders only.
15+
16+
## References
17+
18+
- `.cursor/rules/code-review.mdc`
19+
- `.cursor/rules/dev-workflow.md`

‎skills/contentstack-utils-python/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: contentstack-utils-python
3+
description: contentstack_utils — Python RTE/embedded rendering, Options, GQL, editable tags.
4+
---
5+
6+
# Contentstack Python Utils skill
7+
8+
## Entry
9+
10+
- **`Utils`** — **`contentstack_utils.utils`**: **`render_content`**, **`render`**, embedded item automation via **`Automate`**.
11+
- **`Options`** — configure rendering behavior for **`Utils`** calls.
12+
13+
## Structure
14+
15+
- **`Automate`** — **`automate.py`**: shared automation/rendering flow used by **`Utils`**.
16+
- **Helpers** — **`helper/metadata.py`**, **`helper/node_to_html.py`**, **`helper/converter.py`**.
17+
- **Embedded** — **`embedded/item_type.py`**, **`embedded/styletype.py`**.
18+
- **GQL** — **`gql.py`**.
19+
- **Live preview / tags** — **`entry_editable.py`**; static wrappers on **`Utils`** keep JS-style parameter names where needed.
20+
21+
## Extending
22+
23+
- Prefer matching **JS contentstack-utils** behavior when the feature exists there; document intentional divergences.
24+
- Keep **`lxml`** usage in parsing/rendering layers; avoid broad new runtime deps without packaging updates.
25+
26+
## Companion package
27+
28+
- **`Contentstack`** (delivery SDK) fetches entries; this package renders RTE/embedded fields — see **README** examples.
29+
30+
## Docs
31+
32+
- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
33+
34+
## Rule shortcut
35+
36+
- `.cursor/rules/contentstack-utils-python.mdc`

0 commit comments

Comments
 (0)