Skip to content

Commit fddda8e

Browse files
sunil-lakshmansunil-lakshman
committed
Enh: Added cursor rules and skills
1 parent 1a0d430 commit fddda8e

14 files changed

Lines changed: 1430 additions & 0 deletions

File tree

‎.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-management`
2+
3+
Rules for **contentstack-management-python**: Python **CMA** SDK (`contentstack_management`).
4+
5+
## Rules overview
6+
7+
| Rule | Role |
8+
|------|------|
9+
|[`dev-workflow.md`](dev-workflow.md)| Branch/PR, install, pytest (`unit` / `api` / `mock`), tooling |
10+
|[`python.mdc`](python.mdc)| Python conventions, `contentstack_management/`, `setup.py`|
11+
|[`contentstack-management-python.mdc`](contentstack-management-python.mdc)|**Client**, **Stack**, **`_APIClient`**, CMA modules |
12+
|[`testing.mdc`](testing.mdc)| pytest suites, **`tests/cred.py`**, env |
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 repo files**|`dev-workflow.md`|
21+
|**`contentstack_management/`**|`python.mdc` + `contentstack-management-python.mdc`|
22+
|**`tests/**`**|`testing.mdc`|
23+
|**Packaging / CI**|`python.mdc`|
24+
25+
## Quick reference
26+
27+
| File |`alwaysApply`| Globs (summary) |
28+
|------|---------------|-----------------|
29+
|`dev-workflow.md`| no |`**/*.py`, `setup.py`, `requirements.txt`, `.github/**/*.yml`|
30+
|`python.mdc`| no |`contentstack_management/**/*.py`, `setup.py`, `requirements.txt`|
31+
|`contentstack-management-python.mdc`| no |`contentstack_management/**/*.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-management — public API, Client, HTTP layer, tests"
3+
alwaysApply: true
4+
---
5+
6+
# Code review — `contentstack-management`
7+
8+
## Public API
9+
10+
- **Exported** **`Client`**, **`Region`**, stack and resource helpers match **README** and **`contentstack_management.__all__`** / **`__init__.py`**.
11+
- **Docstrings** on **`Client`** and changed public methods when behavior or parameters change.
12+
13+
## Compatibility
14+
15+
- Avoid breaking **`Client`** constructor or stack method chains without a semver strategy; document migration for breaking changes.
16+
17+
## HTTP / auth
18+
19+
- Changes to **`_APIClient`** or **OAuth** paths: verify retries, headers, and interceptor behavior with unit tests; no regressions for **authtoken** / **management_token** headers.
20+
21+
## Tests
22+
23+
- **Unit** coverage for new logic; **API** updates when live CMA request/response behavior changes; **mock** when contract-style tests are appropriate.
24+
25+
## Security
26+
27+
- No hardcoded tokens; no logging secrets in new code.

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
description: "CMA Management SDK — Client, Stack, _APIClient, resources, OAuth"
3+
globs:
4+
- "contentstack_management/**/*.py"
5+
alwaysApply: false
6+
---
7+
8+
# Contentstack Management Python SDK (`contentstack_management/`)
9+
10+
## Client entry
11+
12+
- **`Client`** in **`contentstack_management/contentstack.py`** builds **`endpoint`** from **host** / **region** / **scheme**, merges **headers** (**authtoken**, **management_token**, **early_access**), and constructs **`_APIClient`**. Optional **`oauth_config`** attaches **`OAuthHandler`**.
13+
14+
## Features
15+
16+
- **Stack** — **`contentstack_management/stack/stack.py`**: content types, entries, assets, branches, webhooks, etc.
17+
- **Org / user** — **`organizations/`**, **`users/`**, **`user_session/`** as applicable.
18+
- **OAuth** — **`oauth/oauth_handler.py`**, **`oauth/oauth_interceptor.py`**; keep aligned with **`_APIClient`** request path.
19+
20+
## HTTP layer
21+
22+
- **`_APIClient._call_request`** — central place for method, URL, JSON, files; respect **timeout** and **max_retries**.
23+
24+
## Docs
25+
26+
- [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/)

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
description: "Branches, install, and test layout for contentstack-management-python"
3+
globs:
4+
- "**/*.py"
5+
- "setup.py"
6+
- "requirements.txt"
7+
- ".github/**/*.yml"
8+
alwaysApply: false
9+
---
10+
11+
# Development workflow — `contentstack-management`
12+
13+
## Before a PR
14+
15+
1.**Install** — `pip install -e ".[dev]"` or install **`requirements.txt`** plus **pytest** / **pytest-cov** as needed.
16+
2.**`pytest tests/unit/`** — required baseline (matches CI **`coverage run -m pytest tests/unit/`**).
17+
3.**API tests** — `pytest tests/api/` when your change affects live CMA behavior; configure **`.env`** per **`tests/cred.py`**. Never commit tokens.
18+
4.**Mock tests** — `pytest tests/mock/` when extending mocked HTTP or fixtures.
19+
20+
## Packaging
21+
22+
- Bump **`contentstack_management/__init__.py`****`__version__`** and align **`setup.py`** versioning if release-facing.
23+
24+
## Tooling
25+
26+
-**pylint** is listed in **`requirements.txt`**; follow existing style in touched files.
27+
-**Husky / Talisman / Snyk** — see **README.md** for local hook setup.
28+
29+
## Links
30+
31+
-[`AGENTS.md`](../../AGENTS.md) · [`skills/contentstack-management-python/SKILL.md`](../../skills/contentstack-management-python/SKILL.md)

‎.cursor/rules/python.mdc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: "Python conventions for the Management SDK package and packaging files"
3+
globs:
4+
- "contentstack_management/**/*.py"
5+
- "setup.py"
6+
- "requirements.txt"
7+
alwaysApply: false
8+
---
9+
10+
# Python — `contentstack-management`
11+
12+
## Layout
13+
14+
- **`contentstack_management/contentstack.py`** — **`Client`**, **`Region`**, **`user_agents`**, OAuth wiring.
15+
- **`contentstack_management/_api_client.py`** — **`_APIClient`** (HTTP, retries).
16+
- **`contentstack_management/stack/`** — stack-scoped API surface.
17+
- **Domain modules** — **`entries/`**, **`assets/`**, **`webhooks/`**, **`oauth/`**, etc.
18+
19+
## Style
20+
21+
- Match existing modules: naming, docstrings, and patterns already used in the same directory.
22+
- Prefer small, focused changes; keep **`__init__.py`** exports consistent with public API intent.
23+
24+
## Imports
25+
26+
- Use **`requests`** (and **`requests-toolbelt`** where already used) through **`_APIClient`** patterns rather than ad-hoc clients in domain modules unless justified.
27+
28+
## Security
29+
30+
- Do not log **authtokens**, **management tokens**, **passwords**, or **API keys**; preserve existing header handling in **`Client`**.

‎.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 unit, api, and mock tests for contentstack-management-python"
3+
globs:
4+
- "tests/**/*.py"
5+
alwaysApply: false
6+
---
7+
8+
# Testing — `contentstack-management`
9+
10+
## pytest
11+
12+
| Suite | Path | Notes |
13+
|-------|------|--------|
14+
| **Unit** | `tests/unit/**` | Fast, isolated; primary CI target (`pytest tests/unit/`) |
15+
| **API** | `tests/api/**` | Live CMA — **`.env`** via **`tests/cred.py`** |
16+
| **Mock** | `tests/mock/**` | Mocked HTTP / contracts |
17+
18+
## Env (`tests/cred.py`)
19+
20+
- **`get_credentials()`** loads **dotenv** and returns host, tokens, and resource UIDs.
21+
- Required for real API runs typically include **`HOST`**, **`APIKEY`**, and either **`AUTHTOKEN`** or stack **`MANAGEMENT_TOKEN`** context as tests expect; see **`tests/cred.py`** and individual tests.
22+
23+
## Hygiene
24+
25+
- No committed secrets; use placeholders or env-only values for CI.
26+
- Avoid leaving **`pytest.skip`** or focused-only tests enabled in paths meant for full suite runs unless intentional.

‎AGENTS.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# AGENTS.md — AI / automation context
2+
3+
## Project
4+
5+
|||
6+
|---|---|
7+
|**Name**|**`contentstack-management`** (PyPI) — **Contentstack Management Python SDK**|
8+
|**Purpose**| Python client for the **Content Management API (CMA)**: organizations, stacks, content types, entries, assets, webhooks, workflows, OAuth, and related resources. Uses **`requests`** via **`_APIClient`**. |
9+
|**Repository**|[contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python.git)|
10+
11+
## Tech stack
12+
13+
| Area | Details |
14+
|------|---------|
15+
|**Language**|**Python** ≥ 3.9 (`setup.py``python_requires`) |
16+
|**HTTP**|**`requests`**, **`requests-toolbelt`**, **`urllib3`**|
17+
|**Tests**|**pytest** — **`tests/unit`**, **`tests/api`**, **`tests/mock`**|
18+
|**Lint**|**pylint** (see `requirements.txt`) |
19+
|**Secrets / hooks**|**Talisman**, **Snyk** (see **README.md** development setup) |
20+
21+
## Source layout
22+
23+
| Path | Role |
24+
|------|------|
25+
|`contentstack_management/contentstack.py`|**`Client`**, **`Region`**, endpoint construction, **`user_agents`**, optional **OAuth** wiring |
26+
|`contentstack_management/_api_client.py`|**`_APIClient`** — HTTP calls, retries, optional **OAuth** interceptor |
27+
|`contentstack_management/stack/stack.py`|**Stack**-scoped CMA operations |
28+
|`contentstack_management/*/`| Domain modules (entries, assets, webhooks, taxonomies, …) |
29+
|`contentstack_management/__init__.py`| Public exports |
30+
|`tests/cred.py`|**`get_credentials()`** — **dotenv** + env vars for API/mock tests |
31+
32+
## Common commands
33+
34+
```bash
35+
pip install -e ".[dev]"
36+
# or: pip install -r requirements.txt && pip install pytest pytest-cov
37+
38+
pytest tests/unit/ -v
39+
pytest tests/api/ -v # live CMA — needs .env (see tests/cred.py)
40+
pytest tests/mock/ -v
41+
pytest tests/ -v
42+
coverage run -m pytest tests/unit/
43+
```
44+
45+
## Environment variables (API / integration tests)
46+
47+
Loaded via **`tests/cred.py`** (`load_dotenv()`). Examples include **`HOST`**, **`APIKEY`**, **`AUTHTOKEN`**, **`MANAGEMENT_TOKEN`**, **`ORG_UID`**, and resource UIDs (**`CONTENT_TYPE_UID`**, **`ENTRY_UID`**, …). See that file for the full list.
48+
49+
Do not commit secrets.
50+
51+
## Further guidance
52+
53+
-**Cursor rules:**[`.cursor/rules/README.md`](.cursor/rules/README.md)
54+
-**Skills:**[`skills/README.md`](skills/README.md)
55+
56+
Product docs: [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-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-management`
2+
3+
| Skill | When to use |
4+
|-------|-------------|
5+
|[`code-review/`](code-review/SKILL.md)| PR review, semver, Client / HTTP changes |
6+
|[`testing/`](testing/SKILL.md)| Unit vs API vs mock pytest |
7+
|[`contentstack-management-python/`](contentstack-management-python/SKILL.md)|**Client**, **Stack**, **`_APIClient`**, CMA modules |
8+
|[`framework/`](framework/SKILL.md)|**`requests`** + **`_APIClient`** + OAuth interceptor |
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-management — public API, Client, _APIClient, OAuth, tests.
4+
---
5+
6+
# Code review — `contentstack-management`
7+
8+
## Checklist
9+
10+
-[ ]**API:** New or changed **`Client`** / **Stack** / resource methods documented; **`contentstack_management/__init__.py`** exports updated if public surface changes.
11+
-[ ]**Version:****`__version__`** in **`contentstack_management/__init__.py`** aligned with release strategy when user-visible behavior changes.
12+
-[ ]**HTTP:****`_APIClient`** or OAuth changes covered by unit tests; retries and headers remain consistent.
13+
-[ ]**Tests:****`pytest tests/unit/`** passes; extend **`tests/api`** or **`tests/mock`** when integration or contract behavior changes.
14+
-[ ]**Secrets:** No tokens in repo; use **`tests/cred.py`** / env for local API runs.
15+
16+
## References
17+
18+
-`.cursor/rules/code-review.mdc`
19+
-`.cursor/rules/dev-workflow.md`

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
name: contentstack-management-python
3+
description: contentstack-management — Python CMA client, Client, Stack, _APIClient, OAuth.
4+
---
5+
6+
# Contentstack Management Python SDK skill
7+
8+
## Entry
9+
10+
-**`contentstack_management.Client`** — **`contentstack_management/contentstack.py`**: builds CMA **endpoint** from **region** / **host**, sets **headers** (**authtoken**, **management_token**), creates **`_APIClient`**, optional **OAuth**.
11+
12+
## Structure
13+
14+
-**`Stack`** — **`contentstack_management/stack/stack.py`**: stack-scoped resources (content types, entries, assets, …).
15+
-**Resources** — packages under **`contentstack_management/`** (e.g. **`entries/`**, **`assets/`**, **`webhooks/`**).
16+
-**OAuth** — **`oauth/oauth_handler.py`**, **`oauth/oauth_interceptor.py`**.
17+
18+
## Extending
19+
20+
- Add methods on the appropriate resource class; align path and payload shapes with **CMA** docs.
21+
- Prefer routing HTTP through **`_APIClient`** for consistent retries and OAuth handling.
22+
23+
## Docs
24+
25+
-[Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/)
26+
27+
## Rule shortcut
28+
29+
-`.cursor/rules/contentstack-management-python.mdc`

0 commit comments

Comments
 (0)