Skip to content

Commit fddda8e

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

File tree

14 files changed

+1430
-0
lines changed

14 files changed

+1430
-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-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)