Skip to content

Commit 8fd26ad

Browse files
sunil-lakshmansunil-lakshman
authored
Merge pull request #69 from contentstack/enh/DX-5371
Enh: Added cursor rules and skills
2 parents cfc4b10 + 67638b7 commit 8fd26ad

File tree

9 files changed

+322
-0
lines changed

9 files changed

+322
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Cursor (optional)
2+
3+
**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool).
4+
5+
This folder only points contributors here so nothing editor-specific duplicates the canonical docs.

‎AGENTS.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Contentstack Utils Python – Agent guide
2+
3+
**Universal entry point** for anyone automating or assisting work in this repo—AI agents (Cursor, Copilot, CLI tools), reviewers, and contributors. Conventions and detailed guidance live in **`skills/*/SKILL.md`**, not in editor-specific config, so the same instructions apply whether or not you use Cursor.
4+
5+
## What this repo is
6+
7+
- **Name:** [contentstack-utils-python](https://github.com/contentstack/contentstack-utils-python) — **`contentstack_utils`** on 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+
- **Out of scope:** This package does **not** ship HTTP clients or stack credentials. Apps fetch content with the [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) / Python SDK, then pass field data into **`Utils`**.
10+
11+
## Tech stack (at a glance)
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+
## Commands (quick reference)
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+
## Where the real documentation lives: skills
51+
52+
Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review:
53+
54+
| Skill | Path | What it covers |
55+
|-------|------|----------------|
56+
| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, venv, **pytest**, ruff/black/flake8, PR expectations |
57+
| **Contentstack Utils (SDK)** | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | **`Utils`**, **`Options`**, RTE/embedded, **GQL**, editable tags, JS parity, semver |
58+
| **Python style & layout** | [`skills/python-style/SKILL.md`](skills/python-style/SKILL.md) | Package layout, typing, imports, **`lxml`**, **`setup.py`**, security |
59+
| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | **pytest** layout, coverage, **`tests/mocks/`**, hygiene |
60+
| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist (API, **`__all__`**, deps, tests, secrets) |
61+
| **Framework / integration** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | **`lxml`**, companion **Contentstack** Python SDK, dependency boundaries |
62+
63+
An index with short “when to use” hints is in [`skills/README.md`](skills/README.md).
64+
65+
## Using Cursor
66+
67+
If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same source of truth as everyone else; no separate `.mdc` rule files.

‎skills/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Skills – Contentstack Utils Python
2+
3+
**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, framework). Read **`AGENTS.md`** at the repo root for the index and quick commands; each skill is a folder with **`SKILL.md`** (YAML frontmatter: `name`, `description`).
4+
5+
## When to use which skill
6+
7+
| Skill folder | Use when |
8+
|--------------|----------|
9+
| **dev-workflow** | Branches, CI, venv, **`pip install -e .`**, **pytest**, ruff/black/flake8, PRs |
10+
| **contentstack-utils** | **`Utils`**, **`Options`**, RTE/embedded, **GQL**, editable tags, semver, README |
11+
| **python-style** | `contentstack_utils/` layout, typing, **`lxml`** usage, **`setup.py`** |
12+
| **testing** | **pytest**, coverage, **`tests/mocks/`**, HTML reports |
13+
| **code-review** | PR checklist, public API / **`__all__`**, dependencies, security |
14+
| **framework** | **`lxml`** integration, delivery SDK handoff, parsing impact |
15+
16+
## How to use these docs
17+
18+
- **Humans / any AI tool:** Start at **`AGENTS.md`**, then open the relevant **`skills/<name>/SKILL.md`**.
19+
- **Cursor users:** **`.cursor/rules/README.md`** only points to **`AGENTS.md`** so guidance stays universal—no duplicate `.mdc` rule sets.

‎skills/code-review/SKILL.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
name: code-review
3+
description: PR checklist—public API, __all__, semver, lxml/deps, pytest, secrets; aligns with JS utils where applicable.
4+
---
5+
6+
# Code review – Contentstack Utils Python
7+
8+
## When to use
9+
10+
- Reviewing a PR, self-review before submit, or automated review prompts.
11+
12+
## Instructions
13+
14+
Work through the checklist below. Optionally tag findings: **Blocker**, **Major**, **Minor**.
15+
16+
### Public API
17+
18+
- [ ] **`contentstack_utils/__init__.py`** **`__all__`** and exports match **README** examples and intended surface (**`Utils`**, **`Options`**, **`GQL`**, **`Automate`**, embed types, **`addEditableTags`** / **`addTags`** / **`getTag`**).
19+
- [ ] **JS parity** — where methods mirror the JS utils SDK, **parameter names** and behavior stay consistent unless a documented breaking change.
20+
21+
### Compatibility
22+
23+
- [ ] No breaking **`Utils`** / **`Options`** / tag helpers without a **semver** plan; **`setup.py` `version`** bumped for user-visible changes.
24+
25+
### Dependencies
26+
27+
- [ ] **`lxml`** usage stays bounded to parsing/rendering paths; new **`install_requires`** documented in **README** / changelog.
28+
29+
### Tests
30+
31+
- [ ] **`pytest`** passes; tests added or extended under **`tests/`** for new behavior and edge cases.
32+
33+
### Security
34+
35+
- [ ] No hardcoded tokens; no logging of secrets in new code.
36+
37+
### Severity (optional)
38+
39+
| Level | Examples |
40+
|-------|----------|
41+
| **Blocker** | Breaking public API without approval; security issue; no tests where practical |
42+
| **Major** | Inconsistent behavior vs documented API; README examples wrong |
43+
| **Minor** | Style; minor docs |
44+
45+
## References
46+
47+
- **`skills/testing/SKILL.md`**
48+
- **`skills/contentstack-utils/SKILL.md`**

‎skills/contentstack-utils/SKILL.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
name: contentstack-utils
3+
description: Public API—Utils, Options, RTE/embedded, GQL, editable tags; JS parity; no bundled HTTP client.
4+
---
5+
6+
# Contentstack Utils – SDK skill
7+
8+
## When to use
9+
10+
- Implementing or changing RTE/HTML rendering, embedded resolution, **GQL**, or editable-tag behavior.
11+
- Updating **`README.md`** / **`changelog.rst`** / **`setup.py`** for user-visible behavior.
12+
- Assessing semver impact of **`__init__.py`** exports and public classes.
13+
14+
## Core entry points
15+
16+
- **`Utils`** — **`contentstack_utils.utils`**: **`render_content`**, **`render`**, embedded/RTE resolution; subclasses **`Automate`**.
17+
- **`Options`** — **`contentstack_utils.render.options`**: rendering configuration passed into **`Utils`** methods.
18+
- **Editable tags** — **`entry_editable`**: **`addEditableTags`**, **`addTags`**, **`getTag`**; also exposed as **`Utils.addEditableTags`** / **`Utils.addTags`** / **`Utils.getTag`** for parity.
19+
20+
## Features
21+
22+
- **Embedded / RTE** — JSON and HTML paths through **`Utils`** and **`Automate`**; **metadata** via **`Metadata`**.
23+
- **Styles** — **`convert_style`** and **embedded** **StyleType** / **ItemType** where applicable.
24+
- **GQL** — **`GQL`** in **`gql.py`** for GraphQL-oriented HTML/helpers.
25+
26+
## Public API and docs
27+
28+
- **`contentstack_utils/__init__.py`** **`__all__`** and exports must match **README** examples and intended surface (**`Utils`**, **`Options`**, **`GQL`**, **`Automate`**, embed types, tag helpers).
29+
- **JS parity** — where methods mirror the JS utils SDK, keep **parameter names** and behavior consistent unless a documented breaking change.
30+
31+
## Compatibility
32+
33+
- Avoid breaking **`Utils`** / **`Options`** / tag helpers without a **semver** plan; bump **`setup.py` `version`** for user-visible changes.
34+
35+
## Dependencies
36+
37+
- **`lxml`** usage stays bounded to parsing/rendering paths; note any new **`install_requires`** in **README** / changelog if added to **`setup.py`**.
38+
39+
## No network layer
40+
41+
- This package does **not** ship HTTP clients or tokens.
42+
- Consumers often use **`contentstack.Stack`** (**Contentstack** package) to fetch entries, then **`Utils.render`** / **`Utils.render_content`** — keep **README** examples accurate.
43+
44+
## References
45+
46+
- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
47+
- **`skills/python-style/SKILL.md`**, **`skills/framework/SKILL.md`**

‎skills/dev-workflow/SKILL.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: dev-workflow
3+
description: Branches, CI, venv, pytest, lint—standard workflow for Contentstack Utils Python.
4+
---
5+
6+
# Development workflow – Contentstack Utils Python
7+
8+
## When to use
9+
10+
- Setting up locally, opening a PR, or aligning with CI.
11+
- Answering “how do we run tests?” or “which branch targets `master`?”
12+
13+
## Before a PR
14+
15+
1. **Install** — `pip install -r requirements.txt` and `pip install -e .` in a virtual environment.
16+
2. **`pytest`** — full suite under **`tests/`** must pass.
17+
3. **Lint / format** — run **ruff**, **black**, **flake8**, **isort** as configured for the repo (see **`requirements.txt`**).
18+
4. **Version** — update **`setup.py` `version`** for releases per semver.
19+
20+
## Branching
21+
22+
- Follow org conventions: **`development`** / **`staging`** / **`master`**; PRs to **`master`** may be restricted (see **`.github/workflows/check-branch.yml`**). Confirm with your team before opening PRs to **`master`**.
23+
24+
## Links
25+
26+
- **`AGENTS.md`** — commands and layout overview.
27+
- **`skills/code-review/SKILL.md`** — pre-merge checklist.

‎skills/framework/SKILL.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: framework
3+
description: lxml parsing layers, setup.py install_requires, companion Contentstack Python SDK handoff.
4+
---
5+
6+
# Framework / integration – Contentstack Utils Python
7+
8+
## When to use
9+
10+
- Changing HTML/XML parsing behavior or **`lxml`** touchpoints.
11+
- Adding runtime dependencies or documenting **`install_requires`**.
12+
13+
## Integration points
14+
15+
- **`lxml.etree`** — parsing and tree operations in **`utils.py`** and related helpers; errors should remain predictable for malformed HTML/XML inputs.
16+
- **Contentstack delivery SDK** — consumers fetch **`entry`** data with **`contentstack.Stack`**, then pass fields into **`Utils.render`** / **`Utils.render_content`** with **`Options`**.
17+
18+
## When to change
19+
20+
- **Parsing behavior** — verify impact on **RTE** output and existing **`tests/`** fixtures.
21+
- **New dependencies** — add to **`setup.py` `install_requires`** and document; prefer stdlib or existing stack (**`lxml`** already required).
22+
23+
## Testing
24+
25+
- **Unit** — **`tests/test_*.py`** with mocks under **`tests/mocks/`** where applicable.
26+
27+
## References
28+
29+
- **`skills/python-style/SKILL.md`**
30+
- **`skills/dev-workflow/SKILL.md`**

‎skills/python-style/SKILL.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: python-style
3+
description: Python layout for contentstack_utils, typing, lxml usage, setup.py, packaging.
4+
---
5+
6+
# Python style and repo layout – Contentstack Utils Python
7+
8+
## When to use
9+
10+
- Editing any Python under **`contentstack_utils/`** or **`setup.py`**.
11+
- Adding modules or changing how **`lxml`** is used.
12+
13+
## Layout
14+
15+
- **`contentstack_utils/utils.py`** — **`Utils`** class (rendering, embedded items); delegates **editable tag** static methods to **`entry_editable`**.
16+
- **`contentstack_utils/render/`** — **`Options`** and render-related code.
17+
- **`contentstack_utils/helper/`** — **Metadata**, **NodeToHtml**, **converter**.
18+
- **`contentstack_utils/embedded/`** — **ItemType**, **StyleType**.
19+
- **`contentstack_utils/gql.py`**, **`automate.py`**, **`entry_editable.py`** — feature modules.
20+
21+
## Style
22+
23+
- Match existing patterns: **typing** hints where already used; **pylint** pragmas only where established.
24+
- Prefer **small, focused** changes; avoid drive-by refactors unrelated to the task.
25+
26+
## Imports
27+
28+
- **`lxml.etree`** — HTML/XML parsing in **`utils`** and helpers; keep usage consistent with existing error handling.
29+
30+
## Packaging
31+
32+
- **`setup.py`** — **`name`**, **`version`**, **`packages=find_packages()`**; keep **`install_requires`** accurate if dependencies change.
33+
34+
## Security
35+
36+
- Do not log **delivery tokens**, **API keys**, or stack secrets.
37+
38+
## References
39+
40+
- **`skills/contentstack-utils/SKILL.md`** — public API and features.
41+
- **`skills/framework/SKILL.md`** — **`lxml`** and SDK integration.

‎skills/testing/SKILL.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
name: testing
3+
description: pytest—layout, coverage, tests/mocks, HTML reports; offline fixtures.
4+
---
5+
6+
# Testing – Contentstack Utils Python
7+
8+
## When to use
9+
10+
- Adding or changing tests under **`tests/`**.
11+
- Debugging flaky tests; improving mocks or fixtures.
12+
13+
## Commands
14+
15+
| Goal | Command |
16+
|------|---------|
17+
| Full suite | `pytest` |
18+
| HTML report | `pytest --html=tests/test-report/test-report.html --self-contained-html` |
19+
| Coverage (example) | `coverage run -m pytest && coverage report -m` |
20+
21+
## Layout
22+
23+
- **`tests/test_*.py`** — feature-focused modules (**utils**, **GQL**, **metadata**, **editable tags**, etc.).
24+
- **`tests/mocks/`** — shared fixture-style data; extend for new scenarios instead of duplicating large JSON.
25+
26+
## Setup
27+
28+
- Install **`requirements.txt`** in a venv; **`pip install -e .`** for editable package tests.
29+
30+
## Hygiene
31+
32+
- No committed **`pytest.mark.skip`** or **`xfail`** without justification; no **`breakpoint()`** left in CI paths.
33+
- No API keys or real tokens in tests.
34+
35+
## References
36+
37+
- **`skills/dev-workflow/SKILL.md`**
38+
- **`skills/code-review/SKILL.md`**

0 commit comments

Comments
 (0)