From 563d9531d27c7946bc9f69191fd18f09ad5799f4 Mon Sep 17 00:00:00 2001 From: sunil-lakshman <104969541+sunil-lakshman@users.noreply.github.com> Date: Tue, 7 Apr 2026 15:38:29 +0530 Subject: [PATCH] Added cursor rules and skill files --- .cursor/rules/README.md | 5 +++ AGENTS.md | 49 ++++++++++++++++++++++++++ skills/README.md | 19 ++++++++++ skills/code-review/SKILL.md | 56 ++++++++++++++++++++++++++++++ skills/contentstack-utils/SKILL.md | 47 +++++++++++++++++++++++++ skills/dev-workflow/SKILL.md | 39 +++++++++++++++++++++ skills/framework/SKILL.md | 35 +++++++++++++++++++ skills/php-style/SKILL.md | 42 ++++++++++++++++++++++ skills/testing/SKILL.md | 38 ++++++++++++++++++++ 9 files changed, 330 insertions(+) create mode 100644 .cursor/rules/README.md create mode 100644 AGENTS.md create mode 100644 skills/README.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/contentstack-utils/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/framework/SKILL.md create mode 100644 skills/php-style/SKILL.md create mode 100644 skills/testing/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 00000000..0c75565b --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,5 @@ +# Cursor (optional) + +**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool). + +This folder only points contributors here so nothing editor-specific duplicates the canonical docs. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..b1a6e272 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,49 @@ +# Contentstack PHP SDK – Agent guide + +**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. + +## What this repo is + +- **Name:** [contentstack-php](https://github.com/contentstack/contentstack-php) +- **Purpose:** PHP library for the Contentstack **Delivery API**—stack initialization, content types, entries, assets, queries, sync, live preview config, and RTE rendering via the optional **`contentstack/utils`** package. +- **Out of scope:** This package is not the Management API client; it focuses on read/delivery patterns documented in the SDK README. + +## Tech stack (at a glance) + +| Area | Details | +|------|---------| +| Language | PHP (see `composer.json` `require.php`; supports legacy 5.5+ per package) | +| Layout | PSR-4 `Contentstack\` → `src/`; helper `src/Support/helper.php` | +| Tests | PHPUnit 10 → `test/` (`phpunit.xml`) | +| Docs | Doctum → `composer run generate:docs` (`config.php`) | +| Dependency | `contentstack/utils` for `Utils`, `Option`, RTE rendering helpers | + +## Commands (quick reference) + +```bash +composer install +composer test +# or: vendor/bin/phpunit +composer run generate:docs +``` + +Coverage and reports (when configured in `phpunit.xml`) write under `./tmp/`. + +## Where the real documentation lives: skills + +Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review: + +| Skill | Path | What it covers | +|-------|------|----------------| +| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI expectations, Composer test/docs, PR notes | +| **Contentstack PHP SDK / Utils** | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | `Contentstack::Stack`, `Stack`, queries, entries, assets, regions, `contentstack/utils`, semver | +| **PHP style & repo layout** | [`skills/php-style/SKILL.md`](skills/php-style/SKILL.md) | PSR-4, namespaces, docblocks, `src/` layout, PHP version constraints | +| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | PHPUnit, `test/` layout, constants/helpers, credentials hygiene | +| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist (API, errors, deps/SCA, tests), Blocker/Major/Minor | +| **Framework / build** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | `composer.json`, autoload, Doctum, optional CI workflows | + +An index with short “when to use” hints is in [`skills/README.md`](skills/README.md). + +## Using Cursor + +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. diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 00000000..d8f3bdc9 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,19 @@ +# Skills – Contentstack PHP SDK + +**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, build). 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`). + +## When to use which skill + +| Skill folder | Use when | +|--------------|----------| +| **dev-workflow** | Branches, `composer test` / docs, GitHub workflows, PR expectations | +| **contentstack-utils** | `Contentstack`, `Stack`, queries, entries, assets, sync, Composer `contentstack/utils` | +| **php-style** | PSR-4, namespaces, docblocks, `src/` structure, PHP compatibility | +| **testing** | PHPUnit, `test/` helpers, offline vs live tests, secrets | +| **code-review** | PR checklist, Blocker/Major/Minor, API and dependency gates | +| **framework** | `composer.json`, autoload, Doctum, dev dependencies | + +## How to use these docs + +- **Humans / any AI tool:** Start at **`AGENTS.md`**, then open the relevant **`skills//SKILL.md`**. +- **Cursor users:** **`.cursor/rules/README.md`** only points to **`AGENTS.md`** so guidance stays universal—no duplicate `.mdc` rule sets. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 00000000..5030c9c2 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,56 @@ +--- +name: code-review +description: PR checklist—API stability, docs, errors, compatibility, dependencies/SCA, tests; Blocker/Major/Minor. +--- + +# Code review – Contentstack PHP SDK + +## When to use + +- Reviewing a PR, self-review before submit, or automated review prompts. + +## Instructions + +Work through the checklist below. Optionally tag findings: **Blocker**, **Major**, **Minor**. + +### API design and stability + +- [ ] **Public API:** New or changed public methods/classes under `src/` are necessary, semver-conscious, and documented (`README.md` / `CHANGELOG.md` when user-visible). +- [ ] **Backward compatibility:** No breaking changes unless explicitly justified (e.g. major version). Prefer additive options and default config shapes. +- [ ] **Naming:** Matches existing SDK terminology (`Stack`, `ContentType`, `Query`, `Entry`, regions, etc.). + +### Error handling and robustness + +- [ ] **Errors:** New failure paths use or extend `CSException` / domain messages where appropriate; callers get actionable context. +- [ ] **Input:** Validate or document preconditions for public parameters; avoid silent failures on malformed API responses where the SDK should surface errors. +- [ ] **HTTP / JSON:** Parsing stays tolerant of documented Delivery API shapes; regressions for edge payloads are called out. + +### Dependencies and security + +- [ ] **Dependencies:** `composer.json` changes are justified; versions do not introduce known vulnerabilities. +- [ ] **SCA:** Address security findings (e.g. Snyk, org scanners) in the PR or via an agreed follow-up. + +### Testing + +- [ ] **Coverage:** New or modified behavior in `src/` has tests under `test/` when feasible. +- [ ] **Quality:** Tests are readable, deterministic, and follow existing helper/constants patterns. + +### Severity (optional) + +| Level | Examples | +|-------|----------| +| **Blocker** | Breaking public API without approval; security issue; no tests for new code where tests are practical | +| **Major** | Inconsistent errors; README examples that do not match real APIs | +| **Minor** | Style; minor docs | + +### Detailed review themes + +- **API:** Breaking public signatures without semver / CHANGELOG alignment. +- **Errors:** Exception changes that confuse callers without a version strategy. +- **README:** Examples must match real `Contentstack::Stack` and query APIs. +- **Dependencies:** New packages need justification and license awareness. + +## References + +- `skills/testing/SKILL.md` +- `skills/contentstack-utils/SKILL.md` diff --git a/skills/contentstack-utils/SKILL.md b/skills/contentstack-utils/SKILL.md new file mode 100644 index 00000000..194ff54a --- /dev/null +++ b/skills/contentstack-utils/SKILL.md @@ -0,0 +1,47 @@ +--- +name: contentstack-utils +description: PHP Delivery SDK API—Contentstack::Stack, queries, entries, assets, regions, sync; RTE via Composer package contentstack/utils. +--- + +# Contentstack PHP SDK (and Utils integration) + +## When to use + +- Implementing or changing Delivery API behavior, query builders, entries, assets, or sync. +- Updating `README.md` / `CHANGELOG.md` for user-visible behavior. +- Assessing semver impact of public API changes or **`contentstack/utils`** usage. + +## Main entry (consumer API) + +- Consumers use **`Contentstack\Contentstack::Stack(...)`** to obtain a **`Contentstack\Stack\Stack`** instance (API key, delivery token, environment, optional region / branch / live preview config). +- Query and fetch patterns flow through **content types**, **queries**, **entries**, and **assets** under `src/Stack/`. +- **RTE / JSON rendering:** `Contentstack::renderContent` and related helpers delegate to the **`contentstack/utils`** Composer package (`Contentstack\Utils\*`, `Option`). Do not reimplement utils behavior inside this SDK without strong reason. + +## Customization and options + +- Stack **config** array supports region, branch, live preview host/enable flags—preserve backward compatibility when extending keys. +- **ContentstackRegion** (or string region values per existing API) must stay consistent with documented Contentstack regions. + +## Data and HTTP + +- The SDK builds requests to Contentstack Delivery endpoints; keep URL construction, headers, and query parameters aligned with product documentation. +- **Result** parsing should match documented JSON shapes; guard against missing keys where the API allows omission. + +## Errors + +- Use **`Contentstack\Error\CSException`** and **`ErrorMessages`** patterns for domain failures. +- Avoid suppressing errors on public code paths without documentation. + +## Related package + +- **`contentstack/utils`** is a required dependency for RTE features shipped through this repo’s public surface; version ranges in `composer.json` should stay coherent with utils releases. + +## Docs and versioning + +- Follow **semver** for public API changes; update **CHANGELOG** and tag/release process per team norms. + +## References + +- [Contentstack](https://www.contentstack.com/) +- [PHP Delivery SDK docs](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/php) +- `skills/php-style/SKILL.md`, `skills/framework/SKILL.md` diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 00000000..136ebda7 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,39 @@ +--- +name: dev-workflow +description: Branches, CI expectations, Composer test/docs, PR hygiene for Contentstack PHP SDK. +--- + +# Development workflow – Contentstack PHP SDK + +## When to use + +- Setting up locally, opening a PR, or aligning with repository automation. +- Answering “how do we run tests?” or “why did the branch check fail?” + +## Branches + +- Use feature branches (e.g. `feat/...`, `fix/...`, ticket branches). +- **`.github/workflows/check-branch.yml`** blocks pull requests into **`master`** unless the head branch is **`staging`** (SRE policy). Prefer PRs to **`staging`** when targeting a master release train. +- **Policy / SCA** workflows may run on PRs (see `.github/workflows/policy-scan.yml`, `sca-scan.yml`). + +## Running tests and build + +- **Install:** `composer install` +- **Tests:** `composer test` or `vendor/bin/phpunit` (config: `phpunit.xml`, suite under `test/`). +- Tests may require Contentstack credentials or mocks as documented in `test/README.md`—do not commit secrets. + +## Documentation generation + +- **Doctum:** `composer run generate:docs` (see `config.php`, output per Doctum defaults). + +## Pull requests + +- Build/tests pass locally where applicable (`composer test`). +- Follow the **code-review** skill (`skills/code-review/SKILL.md`) before merge. +- Prefer backward-compatible public API; call out breaking changes and semver. +- Update **`CHANGELOG.md`** when behavior visible to integrators changes. + +## References + +- `skills/testing/SKILL.md` +- `skills/code-review/SKILL.md` diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md new file mode 100644 index 00000000..501b3247 --- /dev/null +++ b/skills/framework/SKILL.md @@ -0,0 +1,35 @@ +--- +name: framework +description: Composer package, PSR-4 autoload, Doctum docs, PHP version constraints, dev dependencies. +--- + +# Framework / build – Contentstack PHP SDK + +## When to use + +- Editing `composer.json`, autoload blocks, or scripts. +- Changing minimum PHP version or required packages (e.g. `contentstack/utils`, PHPUnit). +- Updating documentation generation (`config.php`, Doctum). + +## Composer + +- **Package name:** `contentstack/contentstack` (see `composer.json`). +- **Autoload:** PSR-4 `Contentstack\` → `src/` plus `files` entry for `src/Support/helper.php`—keep in sync when moving classes. +- **Scripts:** `test` → PHPUnit; `generate:docs` → Doctum. + +## PHP version + +- `require.php` sets minimum language level; raising it is a **compatibility decision**—document in CHANGELOG and coordinate releases. + +## Documentation + +- **Doctum** scans `./src` per `config.php`; adjust only when layout changes. + +## CI / automation + +- This repo may not define a dedicated PHPUnit workflow file; still run **`composer test`** before merge. Branch and policy workflows live under `.github/workflows/`. + +## References + +- `skills/php-style/SKILL.md` +- `skills/dev-workflow/SKILL.md` diff --git a/skills/php-style/SKILL.md b/skills/php-style/SKILL.md new file mode 100644 index 00000000..92f89db6 --- /dev/null +++ b/skills/php-style/SKILL.md @@ -0,0 +1,42 @@ +--- +name: php-style +description: PSR-4 layout, namespaces, docblocks, PHP compatibility, src/ structure for this SDK. +--- + +# PHP style and repo layout – Contentstack PHP SDK + +## When to use + +- Editing any PHP under `src/` or `test/`. +- Adding classes or changing namespace boundaries. + +## Layout + +- **Library code:** `src/` with namespace **`Contentstack\...`** matching PSR-4 paths. +- **Stack / Delivery:** `src/Stack/` (e.g. `Stack.php`, `ContentType/`, `Assets.php`, `BaseQuery.php`). +- **Config / errors / support:** `src/Config/`, `src/Error/`, `src/Support/`. +- **Entry point:** `src/Contentstack.php` exposes static factory and utils-facing helpers. + +## PHP language + +- Honor **minimum PHP** from `composer.json`; avoid syntax and standard-library features unavailable on that floor unless the constraint is explicitly raised. +- **`#[\AllowDynamicProperties]`** and legacy patterns may exist for backward compatibility—do not remove without a semver plan. + +## Documentation blocks + +- Existing files use **PHPDoc** (`@param`, `@return`, `@package`, etc.); new public APIs should include equivalent documentation for IDEs and Doctum. + +## Naming + +- **Classes:** `PascalCase` matching file names under PSR-4. +- **Methods:** `camelCase` consistent with surrounding code. +- Preserve established **public** names even when imperfect unless doing a **semver-major** cleanup with maintainer agreement. + +## Imports and visibility + +- Prefer `use` statements for classes in other namespaces; keep **public** surface explicit (public methods on classes intended for consumers). + +## References + +- `skills/framework/SKILL.md` (Composer, autoload) +- `skills/testing/SKILL.md` diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 00000000..097e2aa8 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,38 @@ +--- +name: testing +description: PHPUnit—test/ layout, helpers, constants, coverage output, secrets hygiene. +--- + +# Testing – Contentstack PHP SDK + +## When to use + +- Adding or changing tests under `test/`. +- Debugging failing tests or coverage gaps. + +## Runner and config + +- **PHPUnit 10** via `vendor/bin/phpunit` or `composer test`. +- Configuration: **`phpunit.xml`**—suite directory `test/`, source coverage for `src/`, reports under `./tmp/` when generated. + +## Layout and naming + +- Tests live as `*Test.php` (e.g. `EntriesTest.php`, `AssetsTest.php`, `SyncTest.php`) alongside helpers such as `constants.php`, `utility.php`, `REST.php`. +- Reuse existing helpers before introducing parallel fixtures. + +## Integration vs unit + +- Some tests may exercise HTTP against Contentstack (see `test/README.md` **Prerequisite**); treat credentials as **local-only** or CI secrets—never commit API keys or tokens. + +## Coverage + +- Clover/HTML/text reports are configured in `phpunit.xml`; ensure `tmp/` (or chosen output dirs) stays out of version control if generated locally (see `.gitignore`). + +## Secrets + +- Tests must not embed real **delivery tokens** or **API keys** in the repository. + +## References + +- `skills/dev-workflow/SKILL.md` +- `skills/code-review/SKILL.md`