Enh: Added cursor rules and skills

.cursor/rules/README.md

@@ -0,0 +1,16 @@
+# Cursor Rules — Contentstack Python CDA SDK
+
+This repository keeps **project guidance in [skills](../../skills/)** (one folder per topic, each with **`SKILL.md`**), not as separate rule files under `.cursor/rules/`.
+
+## Where to look
+
+| Topic | Skill |
+|-------|--------|
+| PR checklist, public API, semver | [`skills/code-review/SKILL.md`](../../skills/code-review/SKILL.md) |
+| Branch, install, tests, versioning | [`skills/dev-workflow/SKILL.md`](../../skills/dev-workflow/SKILL.md) |
+| **Stack**, queries, CDA features | [`skills/contentstack-utils/SKILL.md`](../../skills/contentstack-utils/SKILL.md) |
+| **requests**, retries, **HTTPSConnection** | [`skills/framework/SKILL.md`](../../skills/framework/SKILL.md) |
+| Python layout and package conventions | [`skills/python-style/SKILL.md`](../../skills/python-style/SKILL.md) |
+| **pytest**, **`tests/`**, **`config.py`** | [`skills/testing/SKILL.md`](../../skills/testing/SKILL.md) |
+
+**Index:** [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.md)

AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md — AI / automation context
+
+## Project
+
+| | |
+|---|---|
+| **Name** | **Contentstack** (PyPI) — **Python Content Delivery SDK** |
+| **Purpose** | Python client for the **Content Delivery API (CDA)**: **Stack**, content types, entries, assets, queries, live preview, taxonomy, variants. Uses **`requests`** + **`urllib3.Retry`** via **`HTTPSConnection`**. |
+| **Repository** | [contentstack/contentstack-python](https://github.com/contentstack/contentstack-python.git) |
+
+## Tech stack
+
+| Area | Details |
+|------|---------|
+| **Language** | **Python** (see **`setup.py`** `python_requires`, classifiers) |
+| **HTTP** | **`requests`**, **`urllib3`** |
+| **Tests** | **pytest** + **`unittest.TestCase`** under **`tests/`** |
+| **Packaging** | **`setuptools`** / **`setup.py`**, package **`contentstack`** |
+
+## Source layout
+
+| Path | Role |
+|------|------|
+| `contentstack/stack.py` | **`Stack`**, **`ContentstackRegion`**, endpoint and **HTTPSConnection** wiring |
+| `contentstack/https_connection.py`, `contentstack/controller.py` | Session, retries, **`get_request`** |
+| `contentstack/query.py`, `contentstack/basequery.py` | Queries |
+| `contentstack/entry.py`, `asset.py`, `contenttype.py`, … | Domain modules |
+| `contentstack/__init__.py` | Public exports (**`Stack`**, **`Entry`**, **`Asset`**, …), **`__version__`** |
+| `config.py` (repo root) | Test credentials and UIDs — **must not commit secrets** |
+| `tests/*.py` | Integration-style tests importing **`config`** |
+
+## Common commands
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+pytest tests/
+```
+
+## Environment / test configuration
+
+Tests load stack settings from root **`config.py`** (e.g. **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**). Use a local, gitignored file or sanitized values for CI. Do not commit secrets.
+
+## Further guidance
+
+- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
+- **Skills:** [`skills/README.md`](skills/README.md)
+
+Product docs: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).

skills/README.md

@@ -0,0 +1,12 @@
+# Project skills — Contentstack Python CDA SDK
+
+| Skill | When to use |
+|-------|-------------|
+| [`code-review/`](code-review/SKILL.md) | PR review, semver, public API on **Stack** |
+| [`contentstack-utils/`](contentstack-utils/SKILL.md) | **Stack**, queries, entries, assets, live preview, CDA behavior |
+| [`dev-workflow/`](dev-workflow/SKILL.md) | Branch/PR, install, tests, **config.py**, versioning |
+| [`framework/`](framework/SKILL.md) | **requests**, **HTTPSConnection**, retries |
+| [`python-style/`](python-style/SKILL.md) | **`contentstack/`** layout, **setup.py**, Python conventions |
+| [`testing/`](testing/SKILL.md) | **pytest** + **`tests/`** + **`config.py`** |
+
+**Overview:** [`AGENTS.md`](../AGENTS.md) · **Cursor rules index:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)

skills/code-review/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: code-review
+description: PR review for Contentstack Python CDA SDK — public API, Stack, HTTP layer, tests.
+---
+
+# Code review — Contentstack Python CDA SDK
+
+## Checklist
+
+- [ ] **API:** New or changed **`Stack`** / content-type / query / entry methods documented; **`contentstack/__init__.py`** exports updated if needed.
+- [ ] **Version:** **`__version__`** in **`contentstack/__init__.py`** aligned with release strategy for breaking changes.
+- [ ] **HTTP:** **`https_connection.py`** / **`controller.py`** changes keep retry and timeout behavior predictable.
+- [ ] **Tests:** **`pytest tests/`** passes; extend **`tests/`** when CDA behavior changes.
+- [ ] **Secrets:** No tokens in repo; **`config.py`** remains local-only when it holds real credentials.
+
+## Public API
+
+- **Exported** **`Stack`**, **ContentType**, **Query**, asset/entry helpers match **README** and consumer expectations; **`contentstack/__init__.py`** **`__all__`** stays accurate when exports change.
+- **Docstrings** on **`Stack`** and key public methods when behavior or options change.
+
+## Compatibility
+
+- Avoid breaking **`Stack.__init__`** signatures or method chains without a semver strategy; document migration for breaking changes (**`setup.py`** / **`__version__`**).
+
+## HTTP / dependencies
+
+- Changes to **`requests`**, **retry** behavior, or **`HTTPSConnection`** should stay consistent with **`contentstack/controller.py`** and **`urllib3`** **`Retry`** usage in **`stack.py`**.
+
+## Tests
+
+- **Tests** hit the live CDA when using **`config`** credentials; extend **`tests/`** when request/response behavior changes. Do not commit new secrets.
+
+## Security
+
+- No hardcoded tokens in source or docs; no logging of **api keys**, **delivery tokens**, **preview**, or **management** tokens.
+
+## References
+
+- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)
+- [`python-style/SKILL.md`](../python-style/SKILL.md)

skills/contentstack-utils/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: contentstack-utils
+description: Contentstack Python CDA SDK — Stack, queries, entries, assets, live preview, taxonomy, HTTP session.
+---
+
+# Contentstack Python Delivery SDK (`contentstack/`)
+
+## Stack entry
+
+- **`Stack`** in **`contentstack/stack.py`**: validates **api_key**, **delivery_token**, **environment**; resolves **region → host** via **`ContentstackRegion`**; builds **`endpoint`**; wires **`HTTPSConnection`** with **headers**, **timeout**, **`urllib3.Retry`**, and optional **`live_preview`** / **`branch`** / **`early_access`**.
+
+## Features
+
+- **Content types & entries** — **`contenttype.py`**, **`entry.py`**, **`entryqueryable.py`**.
+- **Queries** — **`basequery.py`**, **`query.py`**; chain methods align with CDA query parameters.
+- **Assets** — **`asset.py`**, **`assetquery.py`**.
+- **Taxonomy, global fields, variants, image transform** — **`taxonomy.py`**, **`globalfields.py`**, **`variants.py`**, **`image_transform.py`**.
+- **Sync** — **`Stack.sync_init`**, **`pagination`**, **`sync_token`** → **`/stacks/sync`** via **`__sync_request`**.
+
+## Live preview
+
+- **`live_preview`** dict (**enable**, **host**, **authorization**, etc.) merged in **`deep_merge_lp.py`** / stack setup; keep behavior aligned with **`tests/test_live_preview.py`**.
+
+## HTTP layer
+
+- **`https_connection.py`** — **`requests.Session`**, **`HTTPAdapter`**, **`get_request`** from **`controller.py`**; user-agent uses **`contentstack.__title__`** / **`__version__`**.
+
+## Extending
+
+- Add query or stack methods consistent with [CDA query parameters](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
+- Keep transport logic in **`HTTPSConnection`** / **`controller`** rather than duplicating **`requests`** setup.
+
+## Dependencies
+
+- **`requests`**, **`urllib3`** (**Retry**), **`python-dateutil`**
+
+## Related skills
+
+- [`framework/SKILL.md`](../framework/SKILL.md) — retries, **`HTTPAdapter`**, timeouts
+
+## Docs
+
+- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)

skills/dev-workflow/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: dev-workflow
+description: Branches, install, tests, and versioning for contentstack-python.
+---
+
+# Development workflow — Contentstack Python CDA SDK
+
+## Before a PR
+
+1. **Install** — `pip install -r requirements.txt` and editable package as needed: `pip install -e .`
+2. **Tests** — `pytest tests/` (or `python -m pytest tests/`) from the repo root; **`tests/pytest.ini`** applies.
+3. **Integration tests** use **`config.py`** at repo root for **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**, etc. Use local credentials only; **never commit** real tokens—prefer a gitignored local **`config.py`** or environment-based loading if you refactor tests.
+
+## Versioning
+
+- Bump **`contentstack/__init__.py`** **`__version__`** and **`setup.py`**-driven releases per semver for user-visible SDK changes.
+
+## References
+
+- [`AGENTS.md`](../../AGENTS.md) · [`contentstack-utils/SKILL.md`](../contentstack-utils/SKILL.md)

skills/framework/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: framework
+description: HTTP layer for the Python CDA SDK — requests Session, urllib3 retries, HTTPSConnection.
+---
+
+# Framework skill — requests + Contentstack Python SDK
+
+## Integration point
+
+- **`contentstack/stack.py`** constructs **`HTTPSConnection`** with **endpoint**, **headers**, **timeout**, **`retry_strategy`** (**`urllib3.Retry`**), and **live_preview**.
+- **`contentstack/https_connection.py`** mounts **`HTTPAdapter(max_retries=...)`** and calls **`get_request`** from **`contentstack/controller.py`**.
+
+## When to change
+
+- **Retry / timeout** behavior: align **`Stack`** defaults with **`HTTPSConnection`** and **`HTTPAdapter`** usage; avoid breaking existing **`Retry`** constructor expectations.
+- **Headers / user-agent** — **`user_agents()`** in **`https_connection.py`** uses **`contentstack.__title__`** and **`__version__`**.
+
+## Testing
+
+- **Integration** — full stack via **`tests/`** and **`config`**; **unit-style** assertions on URL building and headers where tests exist.
+
+## Related skills
+
+- [`contentstack-utils/SKILL.md`](../contentstack-utils/SKILL.md)

skills/python-style/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: python-style
+description: Python layout, packaging, and conventions for the Contentstack CDA SDK package.
+---
+
+# Python style — Contentstack CDA SDK
+
+## Layout
+
+- **`contentstack/stack.py`** — **`Stack`**, **`ContentstackRegion`**.
+- **`contentstack/query.py`**, **`basequery.py`** — query building.
+- **`contentstack/entry.py`**, **`asset.py`**, **`contenttype.py`**, **`taxonomy.py`**, **`globalfields.py`** — domain objects.
+- **`contentstack/https_connection.py`**, **`controller.py`** — HTTP.
+- **`contentstack/error_messages.py`**, **`utility.py`** — shared helpers.
+
+## Style
+
+- Match existing patterns (typing on **`Stack`**, **unittest**-style tests in **`tests/`**).
+- Prefer clear public APIs over internal churn; keep module boundaries similar to neighboring files.
+
+## Dependencies
+
+- **`requests`**, **`python-dateutil`**, **`urllib3`** (Retry) — see **`setup.py`** **`install_requires`**.
+
+## Security
+
+- Do not log **delivery tokens**, **preview tokens**, **api keys**, or **management** tokens; follow existing logging on **`Stack`**.

skills/testing/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: testing
+description: pytest and unittest tests for contentstack-python — tests/ and config.py.
+---
+
+# Testing — Contentstack Python CDA SDK
+
+## Commands
+
+| Goal | Command |
+|------|---------|
+| Full test tree | `pytest tests/` |
+| Single file | `pytest tests/test_stack.py` |
+
+## Environment
+
+- Root **`config.py`**: **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**, optional **PREVIEW_TOKEN**, content UIDs for specific suites.
+- Use a **local** **`config.py`** or sanitized values; never commit live secrets.
+
+## Conventions
+
+- Tests subclass **`unittest.TestCase`**; **`tests/pytest.ini`** applies warning filters.
+
+## Scope by module
+
+| Area | Example tests |
+|------|----------------|
+| Stack / region | **`tests/test_stack.py`** |
+| Queries | **`tests/test_query.py`**, **`tests/test_basequery.py`** |
+| Entries / assets | **`tests/test_entry.py`**, **`tests/test_assets.py`** |
+| Taxonomy / global fields / live preview | **`tests/test_taxonomies.py`**, **`tests/test_global_fields.py`**, **`tests/test_live_preview.py`** |
+| Early access | **`tests/test_early_find.py`**, **`tests/test_early_fetch.py`** |
+
+## Hygiene
+
+- No committed **`pytest.mark.skip`** without reason; avoid **`@unittest.skip`** unless environment is genuinely unavailable in CI.
+
+## References
+
+- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)