DX | 10-08-2026 | Release

.cursor/rules/README.md

@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
+
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

.github/workflows/back-merge-pr.yml

@@ -0,0 +1,56 @@
+# Opens a PR from main → development after changes land on main (back-merge).
+
+name: Back-merge main to development
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  open-back-merge-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Open back-merge PR if needed
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          git fetch origin development main
+
+          MAIN_SHA=$(git rev-parse origin/main)
+          DEV_SHA=$(git rev-parse origin/development)
+
+          if [ "$MAIN_SHA" = "$DEV_SHA" ]; then
+            echo "main and development are at the same commit; nothing to back-merge."
+            exit 0
+          fi
+
+          EXISTING=$(gh pr list --repo "${{ github.repository }}" \
+            --base development \
+            --head main \
+            --state open \
+            --json number \
+            --jq 'length')
+
+          if [ "$EXISTING" -gt 0 ]; then
+            echo "An open PR from main to development already exists; skipping."
+            exit 0
+          fi
+
+          gh pr create --repo "${{ github.repository }}" \
+            --base development \
+            --head main \
+            --title "chore: back-merge main into development" \
+            --body "Automated back-merge after changes landed on \`main\`. Review and merge to keep \`development\` in sync."
+
+          echo "Created back-merge PR main → development."

.github/workflows/check-version-bump.yml

@@ -0,0 +1,110 @@
+# Release-affecting changes under contentstack_management/ or setup.py require
+# __version__ + CHANGELOG.md updates aligned with the latest tag.
+
+name: Check Version Bump
+
+on:
+  pull_request:
+
+jobs:
+  version-bump:
+    name: Version & changelog bump
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed files
+        id: detect
+        run: |
+          FILES=$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}")
+          echo "Changed files:"
+          echo "$FILES"
+
+          CODE_CHANGED=false
+          while IFS= read -r f; do
+            [ -z "$f" ] && continue
+            if [[ "$f" == contentstack_management/* ]] || [[ "$f" == "setup.py" ]]; then
+              CODE_CHANGED=true
+              break
+            fi
+          done <<< "$FILES"
+
+          INIT_CHANGED=false
+          CHANGELOG_CHANGED=false
+          echo "$FILES" | grep -qx 'contentstack_management/__init__.py' && INIT_CHANGED=true
+          echo "$FILES" | grep -qx 'CHANGELOG.md' && CHANGELOG_CHANGED=true
+
+          VERSION_FILES_OK=false
+          if [ "$INIT_CHANGED" = true ] && [ "$CHANGELOG_CHANGED" = true ]; then
+            VERSION_FILES_OK=true
+          fi
+
+          echo "code_changed=$CODE_CHANGED" >> "$GITHUB_OUTPUT"
+          echo "version_files_ok=$VERSION_FILES_OK" >> "$GITHUB_OUTPUT"
+
+      - name: Skip when no release-affecting code changed
+        if: steps.detect.outputs.code_changed != 'true'
+        run: |
+          echo "No contentstack_management or setup.py changes. Skipping version-bump check."
+          exit 0
+
+      - name: Fail when version files were not both updated
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_ok != 'true'
+        run: |
+          echo "::error::Bump __version__ in contentstack_management/__init__.py and add a ## vX.Y.Z section in CHANGELOG.md."
+          exit 1
+
+      - name: Validate version vs latest tag and changelog header
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_ok == 'true'
+        run: |
+          set -euo pipefail
+          PKG_VERSION=$(python3 <<'PY'
+          import re
+          text = open("contentstack_management/__init__.py").read()
+          m = re.search(r"^__version__\s*=\s*['\"]([^'\"]+)['\"]", text, re.MULTILINE)
+          if not m:
+              raise SystemExit("Could not read __version__ from contentstack_management/__init__.py")
+          print(m.group(1).strip())
+          PY
+          )
+
+          git fetch --tags --force 2>/dev/null || true
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "No existing tags found. Skipping semver vs tag check."
+            CHANGELOG_HEAD=$(sed -nE 's/^## v?([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' CHANGELOG.md | head -1)
+            if [ -z "$CHANGELOG_HEAD" ]; then
+              echo "::error::Could not find a ## vX.Y.Z entry at the top of CHANGELOG.md."
+              exit 1
+            fi
+            if [ "$CHANGELOG_HEAD" != "$PKG_VERSION" ]; then
+              echo "::error::CHANGELOG top version ($CHANGELOG_HEAD) does not match __version__ ($PKG_VERSION)."
+              exit 1
+            fi
+            exit 0
+          fi
+
+          LATEST_VERSION="${LATEST_TAG#v}"
+          LATEST_VERSION="${LATEST_VERSION%%-*}"
+          if [ "$(printf '%s\n' "$LATEST_VERSION" "$PKG_VERSION" | sort -V | tail -1)" != "$PKG_VERSION" ]; then
+            echo "::error::__version__ ($PKG_VERSION) must be greater than latest tag ($LATEST_TAG)."
+            exit 1
+          fi
+          if [ "$PKG_VERSION" = "$LATEST_VERSION" ]; then
+            echo "::error::__version__ ($PKG_VERSION) must be strictly greater than latest tag version ($LATEST_VERSION)."
+            exit 1
+          fi
+
+          CHANGELOG_HEAD=$(sed -nE 's/^## v?([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' CHANGELOG.md | head -1)
+          if [ -z "$CHANGELOG_HEAD" ]; then
+            echo "::error::Could not find a ## vX.Y.Z entry at the top of CHANGELOG.md."
+            exit 1
+          fi
+          if [ "$CHANGELOG_HEAD" != "$PKG_VERSION" ]; then
+            echo "::error::CHANGELOG top version ($CHANGELOG_HEAD) does not match __version__ ($PKG_VERSION)."
+            exit 1
+          fi
+          echo "Version bump check passed: __version__ and CHANGELOG at $PKG_VERSION (latest tag: $LATEST_TAG)."

.github/workflows/sca-scan.yml

@@ -5,14 +5,17 @@ on:
 jobs:
   security-sca:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
       - uses: actions/checkout@master
       - name: Run Snyk to check for vulnerabilities
         uses: snyk/actions/python@master
         env:
           SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
         with:
-          args: --fail-on=all --all-projects --skip-unresolved
+          args: --fail-on=all --all-projects
           json: true
         continue-on-error: true
       - uses: contentstack/sca-policy@main

.github/workflows/unit-test.yml

@@ -19,7 +19,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt  # If you have a requirements file
-          pip install coverage pytest coverage-badge
+          pip install coverage pytest coverage-badge "setuptools<81"
 
 
       - name: Run tests and coverage

.gitignore

@@ -133,8 +133,17 @@ tests/config/default.yml
 .vscode/settings.json
 run.py
 tests/resources/.DS_Store
-.talismanrc
 tests/.DS_Store
-tests/resources/.DS_Store
 .DS_Store
-.talismanrc
+*/data/regions.json
+# Local backup of legacy tests (do not commit)
+
+# --- CMA integration suite: do not track ---
+docs/
+tests_backup_legacy/
+tests/integration/report/
+tests/integration/.env
+tests/integration/.env.example
+# Timestamped reports written at repo root
+cma-python-report-*.html
+api-requests-*.txt

.talismanrc

@@ -406,3 +406,7 @@ fileignoreconfig:
 - filename: tests/mock/assets/test_assets_mock.py
   checksum: 12c9091bb88c0c12712f046b29fb4a9dce3b95ecc45f4ea46bbc3fd4529742a0
 version: "1.0"
+fileignoreconfig:
+- filename: tests/integration/framework/capture.py
+  checksum: c9680c4ee3e1def0765fd89767fa1383aee5d195222fa021a19618607373047c
+version: "1.0"

AGENTS.md

@@ -0,0 +1,86 @@
+# Contentstack Management Python – Agent guide
+
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
+
+## What this repo is
+
+| Field | Detail |
+|--------|--------|
+| **Name:** | **`contentstack-management`** (PyPI) — [contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python) |
+| **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`**. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+|------|---------|
+| Language | Python ≥ 3.9 (`setup.py` `python_requires`) |
+| Build | `setuptools` / `setup.py`; package `contentstack_management` |
+| HTTP | `requests`, `requests-toolbelt`, `urllib3` |
+| Tests | `pytest` — `tests/integration` (live e2e / sanity, dynamic stack), `tests/unit`, `tests/mock`, `tests/api` (legacy, superseded by `tests/integration`) |
+| Lint / coverage | `pylint`, `coverage` (see `requirements-dev.txt`) |
+| Secrets / hooks | Talisman, Snyk (see `README.md` development setup) |
+
+## Source layout
+
+| Path | Role |
+|------|------|
+| `contentstack_management/contentstack.py` | **`Client`**, **`Region`**, endpoint construction, **`user_agents`**, optional **OAuth** wiring |
+| `contentstack_management/_api_client.py` | **`_APIClient`** — HTTP calls, retries, optional **OAuth** interceptor |
+| `contentstack_management/stack/stack.py` | **Stack**-scoped CMA operations |
+| `contentstack_management/*/` | Domain modules (entries, assets, webhooks, taxonomies, …) |
+| `contentstack_management/__init__.py` | Public exports |
+| `tests/integration/` | **Live e2e / sanity suite** (pytest). Self-contained: creates a fresh stack per run, exercises every SDK method (positive/negative/edge), tears it down. Own `framework/` + `data/`; config in `tests/integration/.env`. |
+| `tests/cred.py` | **`get_credentials()`** — **dotenv** + env vars for the legacy `tests/api` / `tests/mock` suites |
+
+## Commands (quick reference)
+
+| Command Type | Command |
+|---|---|
+| Install | `pip install -e ".[dev]"` |
+| **Sanity / e2e (live)** | `pytest tests/integration` — dynamically creates a stack, runs the full suite, tears it down. Needs `tests/integration/.env` (`EMAIL`, `PASSWORD`, `HOST`, `ORGANIZATION`). Writes a timestamped HTML report + cURL log to the repo root. |
+| Sanity, keep stack | `DELETE_DYNAMIC_RESOURCES=false pytest tests/integration` (preserve the created stack for debugging) |
+| Sanity, one resource | `pytest tests/integration/api/test_12_content_type.py` |
+| Test (unit) | `pytest tests/unit/ -v` |
+| Test (mock) | `pytest tests/mock/ -v` |
+| Test (legacy API, live) | `pytest tests/api/ -v` (needs `.env` — see `tests/cred.py`) |
+| Coverage (CI) | `coverage run -m pytest tests/unit/` |
+| Lint | `pylint contentstack_management/` |
+
+> **CI note:** `.github/workflows/unit-test.yml` runs **only `tests/unit/`** (no credentials). The `tests/integration` sanity suite is run manually (or via a credential-gated job) because it provisions real stacks.
+
+## Environment variables
+
+**Sanity / e2e suite** (`tests/integration`) — configured via **`tests/integration/.env`** (gitignored). No pre-existing stack/UIDs needed; the suite creates everything at runtime.
+
+| Var | Required | Purpose |
+|-----|----------|---------|
+| `EMAIL`, `PASSWORD` | ✅ | Login for the run (a **non-2FA** account) |
+| `HOST` | ✅ | API host (e.g. `api.contentstack.io`) |
+| `ORGANIZATION` | ✅ | Org the dynamic test stack is created in |
+| `MFA_SECRET` | — | TOTP secret (for the OAuth/2FA account, not the primary login) |
+| `DELETE_DYNAMIC_RESOURCES` | — | `false` keeps the created stack for debugging (default deletes) |
+| `CLIENT_ID`, `APP_ID`, `REDIRECT_URI` | — | OAuth tests |
+| `PERSONALIZE_HOST` | — | Personalize project for variant tests |
+
+**Legacy `tests/api` / `tests/mock`** — loaded via **`tests/cred.py`** (`load_dotenv()`): `HOST`, `APIKEY`, `AUTHTOKEN`, `MANAGEMENT_TOKEN`, `ORG_UID`, and resource UIDs. See that file for the full list.
+
+Do not commit secrets. `tests/integration/.env`, `docs/`, and the repo-root `cma-python-report-*.html` / `api-requests-*.txt` are gitignored.
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Install, pytest suites, packaging version, pylint, hooks, PR baseline |
+| **Contentstack Management (SDK)** | [`skills/contentstack-management/SKILL.md`](skills/contentstack-management/SKILL.md) | **`Client`**, **`Stack`**, **`_APIClient`**, CMA resources, OAuth, CMA docs |
+| **Python style & repo layout** | [`skills/python-style/SKILL.md`](skills/python-style/SKILL.md) | Package layout, naming, imports via **`_APIClient`**, secrets in logs |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | pytest unit / API / mock, **`tests/cred.py`**, env hygiene |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist—public API, HTTP/auth, tests, security |
+| **Framework / HTTP** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | **`requests`**, retries, OAuth interceptor, where to change transport |
+
+An index with “when to use” hints is in [`skills/README.md`](skills/README.md).
+
+## Using Cursor (optional)
+
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.
+
+Product docs: [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/).