Skip to content

Commit 1b018fc

Browse files
sunil-lakshmansunil-lakshman
authored
Merge pull request #145 from contentstack/enh/DX-5381
Enh: Added cursor rules and skills
2 parents 1a0d430 + 9fa7935 commit 1b018fc

File tree

9 files changed

+340
-0
lines changed

9 files changed

+340
-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: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Contentstack Management 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+
| | |
8+
|---|---|
9+
| **Name** | **`contentstack-management`** (PyPI) — **Contentstack Management Python SDK** |
10+
| **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`**. |
11+
| **Repository** | [contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python.git) |
12+
13+
## Tech stack
14+
15+
| Area | Details |
16+
|------|---------|
17+
| **Language** | **Python** ≥ 3.9 (`setup.py` `python_requires`) |
18+
| **HTTP** | **`requests`**, **`requests-toolbelt`**, **`urllib3`** |
19+
| **Tests** | **pytest** — **`tests/unit`**, **`tests/api`**, **`tests/mock`** |
20+
| **Lint** | **pylint** (see `requirements.txt`) |
21+
| **Secrets / hooks** | **Talisman**, **Snyk** (see **README.md** development setup) |
22+
23+
## Source layout
24+
25+
| Path | Role |
26+
|------|------|
27+
| `contentstack_management/contentstack.py` | **`Client`**, **`Region`**, endpoint construction, **`user_agents`**, optional **OAuth** wiring |
28+
| `contentstack_management/_api_client.py` | **`_APIClient`** — HTTP calls, retries, optional **OAuth** interceptor |
29+
| `contentstack_management/stack/stack.py` | **Stack**-scoped CMA operations |
30+
| `contentstack_management/*/` | Domain modules (entries, assets, webhooks, taxonomies, …) |
31+
| `contentstack_management/__init__.py` | Public exports |
32+
| `tests/cred.py` | **`get_credentials()`** — **dotenv** + env vars for API/mock tests |
33+
34+
## Commands (quick reference)
35+
36+
```bash
37+
pip install -e ".[dev]"
38+
# or: pip install -r requirements.txt && pip install pytest pytest-cov
39+
40+
pytest tests/unit/ -v
41+
pytest tests/api/ -v # live CMA — needs .env (see tests/cred.py)
42+
pytest tests/mock/ -v
43+
pytest tests/ -v
44+
coverage run -m pytest tests/unit/
45+
```
46+
47+
## Environment variables (API / integration tests)
48+
49+
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.
50+
51+
Do not commit secrets.
52+
53+
## Where the real documentation lives: skills
54+
55+
Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review:
56+
57+
| Skill | Path | What it covers |
58+
|-------|------|----------------|
59+
| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Install, pytest suites, packaging version, pylint, hooks, PR baseline |
60+
| **Contentstack Management (SDK)** | [`skills/contentstack-management/SKILL.md`](skills/contentstack-management/SKILL.md) | **`Client`**, **`Stack`**, **`_APIClient`**, CMA resources, OAuth, CMA docs |
61+
| **Python style & repo layout** | [`skills/python-style/SKILL.md`](skills/python-style/SKILL.md) | Package layout, naming, imports via **`_APIClient`**, secrets in logs |
62+
| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | pytest unit / API / mock, **`tests/cred.py`**, env hygiene |
63+
| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist—public API, HTTP/auth, tests, security |
64+
| **Framework / HTTP** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | **`requests`**, retries, OAuth interceptor, where to change transport |
65+
66+
An index with short “when to use” hints is in [`skills/README.md`](skills/README.md).
67+
68+
## Using Cursor
69+
70+
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.
71+
72+
Product docs: [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/).

‎skills/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Skills — Contentstack Management Python
2+
3+
**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, HTTP layer). 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** | Install, **`pytest`** (unit / API / mock), **`__version__`**, pylint, Talisman/Snyk, before PR |
10+
| **contentstack-management** | **`Client`**, **`Stack`**, **`_APIClient`**, domain modules, OAuth, CMA paths and payloads |
11+
| **python-style** | Editing **`contentstack_management/`** or **`setup.py`** / **`requirements.txt`**—layout, style, imports |
12+
| **testing** | Adding or changing tests under **`tests/`**, **`tests/cred.py`**, env for API runs |
13+
| **code-review** | PR checklist, API semver, HTTP regressions, secrets |
14+
| **framework** | Changing **`_APIClient`**, retries, **`requests`** usage, OAuth interceptor wiring |
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: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
name: code-review
3+
description: PR checklist—public API, Client/Stack, _APIClient/OAuth, tests, secrets; align with README and exports.
4+
---
5+
6+
# Code review — Contentstack Management 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+
- [ ] **Exported** **`Client`**, **`Region`**, stack and resource helpers match **README** and **`contentstack_management.__all__`** / **`__init__.py`**.
19+
- [ ] **Docstrings** on **`Client`** and changed public methods when behavior or parameters change.
20+
21+
### Compatibility
22+
23+
- [ ] Avoid breaking **`Client`** constructor or stack method chains without a semver strategy; document migration for breaking changes.
24+
25+
### HTTP / auth
26+
27+
- [ ] Changes to **`_APIClient`** or **OAuth** paths: verify retries, headers, and interceptor behavior with unit tests; no regressions for **authtoken** / **management_token** headers.
28+
29+
### Testing
30+
31+
- [ ] **Unit** coverage for new logic; **API** updates when live CMA request/response behavior changes; **mock** when contract-style tests are appropriate.
32+
- [ ] **`pytest tests/unit/`** passes.
33+
34+
### Security
35+
36+
- [ ] No hardcoded tokens; no logging secrets in new code.
37+
38+
### Severity (optional)
39+
40+
| Level | Examples |
41+
|-------|----------|
42+
| **Blocker** | Breaking public API without approval; security issue; no tests for new logic where tests are practical |
43+
| **Major** | Inconsistent HTTP/auth behavior; README examples that do not match code |
44+
| **Minor** | Style; minor docs |
45+
46+
## References
47+
48+
- **`skills/testing/SKILL.md`**
49+
- **`skills/contentstack-management/SKILL.md`**
50+
- **`skills/dev-workflow/SKILL.md`**

‎skills/contentstack-management/SKILL.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: contentstack-management
3+
description: Public CMA surface—Client, Stack, _APIClient, domain resources, OAuth; align with CMA docs and semver.
4+
---
5+
6+
# Contentstack Management — SDK skill
7+
8+
## When to use
9+
10+
- Implementing or changing **`Client`**, **Stack**, or resource modules (entries, assets, webhooks, …).
11+
- Updating **`README.md`** or public exports for user-visible behavior.
12+
- Assessing semver impact of constructor, method, or export changes.
13+
14+
## Main entry (consumer API)
15+
16+
- **`contentstack_management.Client`** in **`contentstack.py`**: builds CMA **endpoint** from **region** / **host** / **scheme**, merges **headers** (**authtoken**, **management_token**, **early_access**), constructs **`_APIClient`**, optional **`oauth_config`** with **`OAuthHandler`**.
17+
18+
## Structure
19+
20+
- **`Stack`** — **`contentstack_management/stack/stack.py`**: stack-scoped resources (content types, entries, assets, branches, webhooks, …).
21+
- **Org / user** — **`organizations/`**, **`users/`**, **`user_session/`** as applicable.
22+
- **Resources** — packages under **`contentstack_management/`** following existing patterns.
23+
- **OAuth** — **`oauth/oauth_handler.py`**, **`oauth/oauth_interceptor.py`**; keep aligned with **`_APIClient`** request path.
24+
25+
## HTTP layer
26+
27+
- **`_APIClient._call_request`** — central place for method, URL, JSON, files; respect **timeout** and **max_retries**.
28+
29+
## Extending
30+
31+
- Add methods on the appropriate resource class; align path and payload shapes with **CMA** docs.
32+
- Prefer routing HTTP through **`_APIClient`** for consistent retries and OAuth handling.
33+
34+
## Docs and versioning
35+
36+
- Exported **`Client`**, **`Region`**, and stack helpers should match **README** and **`contentstack_management.__init__.py`**.
37+
- Document migration for intentional breaking changes.
38+
39+
## References
40+
41+
- [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/)
42+
- **`skills/framework/SKILL.md`**
43+
- **`skills/python-style/SKILL.md`**

‎skills/dev-workflow/SKILL.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
name: dev-workflow
3+
description: Install, pytest unit/API/mock, versioning, pylint, hooks—standard workflow for this SDK repo.
4+
---
5+
6+
# Development workflow — Contentstack Management Python
7+
8+
## When to use
9+
10+
- Setting up locally, opening a PR, or matching CI expectations.
11+
- Answering “how do we run tests?” or “what runs in CI?”
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+
## Pull requests
30+
31+
- Build passes: **`pytest tests/unit/`** at minimum; run **API** / **mock** when your change touches those layers.
32+
- Follow **`skills/code-review/SKILL.md`** before merge.
33+
- Prefer backward-compatible public API; call out breaking changes and semver.
34+
35+
## References
36+
37+
- **`AGENTS.md`**
38+
- **`skills/contentstack-management/SKILL.md`**
39+
- **`skills/testing/SKILL.md`**

‎skills/framework/SKILL.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: framework
3+
description: requests-based _APIClient, retries, timeout, OAuth interceptor—central HTTP for the Management SDK.
4+
---
5+
6+
# Framework / HTTP — Contentstack Management Python
7+
8+
## When to use
9+
10+
- Editing **`contentstack_management/_api_client.py`** or OAuth interceptor/handler wiring.
11+
- Changing retry policy, timeouts, or how **`requests`** is invoked.
12+
13+
## Integration point
14+
15+
- **`_APIClient`** uses **`requests`** in **`_call_request`**, honors **timeout** and **max_retries**, and delegates to **`oauth_interceptor`** when configured.
16+
17+
## When to change
18+
19+
- **Retry or transport behavior** — keep logic centralized in **`_APIClient`** unless a resource truly needs a documented exception.
20+
- **Auth headers** — prefer extending **`Client`** / **`user_agents`** patterns rather than scattering header merges.
21+
22+
## Testing
23+
24+
- **Unit** — mock **`requests`** or **`_APIClient`** at the boundary used by existing tests.
25+
- **API** — full stack via credentials from **`tests/cred.py`**.
26+
27+
## References
28+
29+
- **`skills/contentstack-management/SKILL.md`**
30+
- **`skills/dev-workflow/SKILL.md`**
31+
- **`skills/testing/SKILL.md`**

‎skills/python-style/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: python-style
3+
description: Package layout under contentstack_management/, setup.py, pylint-friendly style, imports, no secret logging.
4+
---
5+
6+
# Python style and repo layout — Contentstack Management Python
7+
8+
## When to use
9+
10+
- Editing any Python under **`contentstack_management/`**, **`setup.py`**, or **`requirements.txt`**.
11+
- Adding modules or changing how the public package surface is exported.
12+
13+
## Layout
14+
15+
- **`contentstack_management/contentstack.py`** — **`Client`**, **`Region`**, **`user_agents`**, OAuth wiring.
16+
- **`contentstack_management/_api_client.py`** — **`_APIClient`** (HTTP, retries).
17+
- **`contentstack_management/stack/`** — stack-scoped API surface.
18+
- **Domain modules** — **`entries/`**, **`assets/`**, **`webhooks/`**, **`oauth/`**, etc.
19+
20+
## Style
21+
22+
- Match existing modules: naming, docstrings, and patterns already used in the same directory.
23+
- Prefer small, focused changes; keep **`__init__.py`** exports consistent with public API intent (**`README`**, **`contentstack_management.__all__`**).
24+
25+
## Imports
26+
27+
- Use **`requests`** (and **`requests-toolbelt`** where already used) through **`_APIClient`** patterns rather than ad-hoc clients in domain modules unless justified.
28+
29+
## Security
30+
31+
- Do not log **authtokens**, **management tokens**, **passwords**, or **API keys**; preserve existing header handling in **`Client`**.
32+
33+
## References
34+
35+
- **`skills/framework/SKILL.md`**
36+
- **`skills/contentstack-management/SKILL.md`**
37+
- **`skills/testing/SKILL.md`**

‎skills/testing/SKILL.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: testing
3+
description: pytest—unit, API, mock; tests/cred.py and .env; no committed secrets.
4+
---
5+
6+
# Testing — Contentstack Management Python
7+
8+
## When to use
9+
10+
- Adding or changing tests under **`tests/`**.
11+
- Debugging API vs mock failures; improving **`tests/cred.py`** usage.
12+
13+
## Runner and tooling
14+
15+
| Suite | Path | Notes |
16+
|-------|------|--------|
17+
| **Unit** | `tests/unit/**` | Fast, isolated; primary CI target |
18+
| **API** | `tests/api/**` | Live CMA — **`.env`** via **`tests/cred.py`** |
19+
| **Mock** | `tests/mock/**` | Mocked HTTP / contracts |
20+
21+
### Commands
22+
23+
| Goal | Command |
24+
|------|---------|
25+
| Unit (CI-style) | `pytest tests/unit/ -v` or `coverage run -m pytest tests/unit/` |
26+
| API (live CMA) | `pytest tests/api/ -v` |
27+
| Mock | `pytest tests/mock/ -v` |
28+
| Full tree | `pytest tests/ -v` |
29+
30+
## Environment (`tests/cred.py`)
31+
32+
- **`get_credentials()`** loads **dotenv** and returns host, tokens, and resource UIDs.
33+
- Common vars: **`HOST`**, **`APIKEY`**, **`AUTHTOKEN`**, **`MANAGEMENT_TOKEN`**, **`ORG_UID`**, plus resource UIDs as tests require.
34+
- Use a **`.env`** at repo root for local API runs; never commit secrets.
35+
36+
## Hygiene
37+
38+
- No committed secrets; use placeholders or env-only values for CI.
39+
- Avoid leaving **`pytest.skip`** or focused-only tests enabled in paths meant for full suite runs unless intentional.
40+
41+
## References
42+
43+
- **`skills/dev-workflow/SKILL.md`**
44+
- **`skills/code-review/SKILL.md`**

0 commit comments

Comments
 (0)