Skip to content

Commit 6c268c5

Browse files
harshitha-cstkharshitha-cstk
committed
Add agent guide, skills overview, and development workflow instructions.
1 parent 1ea51d7 commit 6c268c5

8 files changed

Lines changed: 265 additions & 0 deletions

File tree

‎.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 **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
4+
5+
This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

‎AGENTS.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Contentstack Utils PHP – Agent guide
2+
3+
**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
4+
5+
## What this repo is
6+
7+
| Field | Detail |
8+
| --- | --- |
9+
| **Name:** | [contentstack/utils](https://packagist.org/packages/contentstack/utils) · [GitHub](https://github.com/contentstack/contentstack-utils-php) |
10+
| **Purpose:** | PHP library for rendering Contentstack Rich Text (RTE) content and GraphQL-shaped JSON to HTML, including embedded entries and custom render options. |
11+
| **Out of scope (if any):** | Not an HTTP client or full Contentstack Delivery SDK; it focuses on parsing/rendering utilities used alongside other Contentstack PHP packages. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
| --- | --- |
17+
| Language | PHP `>=7.2` (Composer); CI runs on PHP 8.3. `declare(strict_types=1);` in source files. |
18+
| Build | [Composer](https://getcomposer.org/) — `composer.json`, `composer.lock`. No compile step; autoload PSR-4 `Contentstack\Utils\` → `src/`. |
19+
| Tests | PHPUnit 9.x via `composer test` / `phpunit`; suite in `tests/`, config `phpunit.xml`. |
20+
| Lint / coverage | PHP_CodeSniffer (PSR-2 ruleset) — `composer check-style` / `composer fix-style`; config `phpcs.xml.dist`. Coverage/logging paths under `build/` when generated. |
21+
| Other | Dev dependency `marc-mabe/php-enum` for enums. |
22+
23+
## Commands (quick reference)
24+
25+
| Command type | Command |
26+
| --- | --- |
27+
| Install deps | `composer install` |
28+
| Test | `composer test` |
29+
| Lint | `composer check-style` |
30+
| Format (fix) | `composer fix-style` |
31+
32+
**CI:** [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — validates `composer.json` / lockfile, installs dependencies, runs `composer run-script test`. Other workflows: `sca-scan.yml`, `policy-scan.yml`, `issues-jira.yml`, `check-branch.yml`.
33+
34+
## Where the documentation lives: skills
35+
36+
| Skill | Path | What it covers |
37+
| --- | --- | --- |
38+
| Dev workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, Composer scripts, PR expectations |
39+
| Contentstack Utils API | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | Public API, namespaces, extension points (`Option`, `RenderableInterface`) |
40+
| PHP style & layout | [`skills/php-style/SKILL.md`](skills/php-style/SKILL.md) | PSR-2, PHPCS, file layout under `src/` |
41+
| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | PHPUnit layout, mocks, coverage output |
42+
| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist aligned with this repo |
43+
44+
An index with “when to use” hints is in [`skills/README.md`](skills/README.md).
45+
46+
## Using Cursor (optional)
47+
48+
If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

‎skills/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Skills – Contentstack Utils PHP
2+
3+
Source of truth for detailed guidance. Read [`AGENTS.md`](../AGENTS.md) first, then open the skill that matches your task.
4+
5+
## When to use which skill
6+
7+
| Skill folder | Use when |
8+
| --- | --- |
9+
| [`dev-workflow`](dev-workflow/SKILL.md) | Running installs/tests, understanding CI, branch rules for PRs to `master` |
10+
| [`contentstack-utils`](contentstack-utils/SKILL.md) | Changing public APIs, `Utils` / `GQL`, parsers, models, or embed rendering |
11+
| [`php-style`](php-style/SKILL.md) | Code style, PHPCS/PSR-2, namespaces, or `src/` layout |
12+
| [`testing`](testing/SKILL.md) | Adding or changing PHPUnit tests, mocks, or coverage |
13+
| [`code-review`](code-review/SKILL.md) | Preparing or reviewing a PR for this repository |
14+
15+
Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

‎skills/code-review/SKILL.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: code-review
3+
description: Use when reviewing or preparing a PR — tests, style, SemVer, docs, and branch rules for this repository.
4+
---
5+
6+
# Code review – Contentstack Utils PHP
7+
8+
## When to use
9+
10+
- Authoring a pull request into this repo
11+
- Reviewing someone else’s PR for completeness and repo policy
12+
13+
## Instructions
14+
15+
### Checklist
16+
17+
- **Tests:** New or changed behavior has PHPUnit coverage; `composer test` passes.
18+
- **Style:** `composer check-style` passes (PSR-2 via PHPCS).
19+
- **Docs:** User-visible behavior changes reflected in [`README.md`](../../README.md) or other maintainer-facing docs as appropriate.
20+
- **API / SemVer:** Public signatures and documented behavior follow semantic versioning expectations per [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
21+
- **Branch policy:** PRs targeting **`master`** must come from the **`next`** branch per [`.github/workflows/check-branch.yml`](../../.github/workflows/check-branch.yml); confirm with the team if process changes.
22+
- **Commits:** Prefer coherent history; squash noisy WIP commits when requested.
23+
24+
### Severity (optional labels)
25+
26+
- **Blocker:** Breaks tests, CI, or documented security/policy requirements.
27+
- **Major:** Missing tests for non-trivial logic, public API breakage without version strategy, or policy violations (e.g. wrong base branch).
28+
- **Minor:** Style nits, naming, or internal refactors with no contract change.
29+
30+
## References
31+
32+
- [`CONTRIBUTING.md`](../../CONTRIBUTING.md)
33+
- [`PULL_REQUEST_TEMPLATE.md`](../../PULL_REQUEST_TEMPLATE.md)
34+
- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)

‎skills/contentstack-utils/SKILL.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
name: contentstack-utils
3+
description: Use when changing Utils, GQL, BaseParser, models, enums, or embed/render behavior — the library’s public surface and integration boundaries.
4+
---
5+
6+
# Contentstack Utils API – Contentstack Utils PHP
7+
8+
## When to use
9+
10+
- Adding or changing HTML/RTE rendering or GraphQL JSON → HTML conversion
11+
- Extending or implementing render callbacks (`Option`, `RenderableInterface`)
12+
- Working with metadata, embedded items, or enum-backed node/mark types
13+
14+
## Instructions
15+
16+
### Package identity
17+
18+
- Composer package: `contentstack/utils` ([Packagist](https://packagist.org/packages/contentstack/utils)); PSR-4 root namespace `Contentstack\Utils\` maps to `src/`.
19+
20+
### Main entry points (illustrative)
21+
22+
- **`Contentstack\Utils\Utils`** ([`src/Utils.php`](../../src/Utils.php)) — static helpers such as `renderContent` / `jsonToHtml` for RTE strings and JSON payloads; extends `BaseParser`.
23+
- **`Contentstack\Utils\GQL`** ([`src/GQL.php`](../../src/GQL.php)) — `jsonToHtml` and related parsing for GraphQL-shaped content; extends `BaseParser`.
24+
- **`Contentstack\Utils\BaseParser`** ([`src/BaseParser.php`](../../src/BaseParser.php)) — shared parsing and embedded-object resolution logic.
25+
26+
### Extension / integration
27+
28+
- **`Contentstack\Utils\Model\Option`** — configure rendering; subclasses override `renderMark`, `renderNode`, `renderOptions`, etc.
29+
- **`Contentstack\Utils\Resource\RenderableInterface`** — contract for types that participate in rendering.
30+
- **`Contentstack\Utils\Model\Metadata`** — embed metadata (e.g. style type, attributes).
31+
- **Enums** under `Contentstack\Utils\Enum\` (`NodeType`, `MarkType`, `StyleType`, `EmbedItemType`) use `marc-mabe/php-enum`.
32+
33+
### Boundaries
34+
35+
- This package does not ship HTTP calls; consumers fetch data with the Contentstack PHP SDK or other clients and pass strings/objects into `Utils` / `GQL`.
36+
- Prefer backward-compatible changes to public method signatures; follow SemVer.
37+
38+
## References
39+
40+
- [`testing/SKILL.md`](../testing/SKILL.md)
41+
- [`php-style/SKILL.md`](../php-style/SKILL.md)
42+
- [Product README — usage](../../README.md)

‎skills/dev-workflow/SKILL.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: dev-workflow
3+
description: Use when running Composer, CI, or PRs to master/next — installs, tests, and branch policy for this repo.
4+
---
5+
6+
# Dev workflow – Contentstack Utils PHP
7+
8+
## When to use
9+
10+
- Installing dependencies or running the test suite locally
11+
- Understanding what GitHub Actions run on push/PR
12+
- Opening or reviewing a PR and matching branch expectations
13+
14+
## Instructions
15+
16+
### Local setup
17+
18+
- From the repo root: `composer install` (use `composer install --ignore-platform-reqs` only if you must match CI’s relaxed install; see `.github/workflows/ci.yml`).
19+
- Run tests: `composer test` (runs PHPUnit as defined in `composer.json`).
20+
21+
### Lint
22+
23+
- Check: `composer check-style` (PHPCS on `src` and `tests`).
24+
- Autofix where supported: `composer fix-style` (PHPCBF).
25+
26+
### CI
27+
28+
- [`ci.yml`](../../.github/workflows/ci.yml): `composer validate`, cache + `composer install`, then `composer run-script test`.
29+
- Lint is not currently enforced in that workflow; still run `check-style` before pushing.
30+
31+
### Branch / PR policy
32+
33+
- [`check-branch.yml`](../../.github/workflows/check-branch.yml): PRs **into `master`** must use branch **`next`** as the head branch (automation comments and fails otherwise).
34+
- Prefer feature branches (not your fork’s default branch name as the only source) per [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
35+
36+
### Releases / versioning
37+
38+
- Project follows SemVer per [`CONTRIBUTING.md`](../../CONTRIBUTING.md); public API changes belong in changelog/release notes as the maintainers require.
39+
40+
## References
41+
42+
- [`AGENTS.md`](../../AGENTS.md)
43+
- [`testing/SKILL.md`](../testing/SKILL.md)
44+
- [`php-style/SKILL.md`](../php-style/SKILL.md)

‎skills/php-style/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: php-style
3+
description: Use when applying PSR-2, running PHPCS, or matching src/tests layout and strict_types in this repo.
4+
---
5+
6+
# PHP style & layout – Contentstack Utils PHP
7+
8+
## When to use
9+
10+
- Fixing or avoiding PHPCS violations
11+
- Adding new classes under `src/` or tests under `tests/`
12+
- Aligning with existing `declare(strict_types=1);` usage
13+
14+
## Instructions
15+
16+
### Coding standard
17+
18+
- **PHPCS** ruleset: [`phpcs.xml.dist`](../../phpcs.xml.dist) extends **PSR-2** (`<rule ref="PSR2" />`).
19+
- Check: `composer check-style`; fix: `composer fix-style` (both target `src` and `tests` per `composer.json` scripts).
20+
21+
### File layout
22+
23+
- **Source:** `src/` — namespaces mirror directories (e.g. `Contentstack\Utils\Model\Option` → `src/Model/Option.php`).
24+
- **Tests:** `tests/` — namespace `Contentstack\Tests\Utils\` per `composer.json` `autoload-dev`.
25+
26+
### PHP version
27+
28+
- `composer.json` requires `php: >=7.2`; avoid language features that require newer versions unless the project explicitly raises the minimum.
29+
30+
### Strict typing
31+
32+
- New PHP files in `src/` should use `declare(strict_types=1);` consistently with existing classes.
33+
34+
## References
35+
36+
- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)
37+
- [PSR-2 coding style guide](https://www.php-fig.org/psr/psr-2/)

‎skills/testing/SKILL.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: testing
3+
description: Use when writing PHPUnit tests, mocks under tests/Mock, or coverage/output under build/ for this package.
4+
---
5+
6+
# Testing – Contentstack Utils PHP
7+
8+
## When to use
9+
10+
- Adding or updating unit tests for `Utils`, `GQL`, models, or helpers
11+
- Extending mocks/fixtures under `tests/Mock` or `tests/Helpers`
12+
- Interpreting PHPUnit config, coverage, or CI test runs
13+
14+
## Instructions
15+
16+
### Runner and config
17+
18+
- **Command:** `composer test` → PHPUnit (`phpunit/phpunit` ^9.3).
19+
- **Config:** [`phpunit.xml`](../../phpunit.xml) — bootstrap `vendor/autoload.php`, suite directory `tests/`, whitelist coverage on `src/`.
20+
21+
### Layout
22+
23+
- Test classes live directly under `tests/` (e.g. `UtilsTest.php`, `GQLTest.php`, `MetadataTest.php`) plus **`tests/Mock/`** (`JsonMock.php`, `EmbedObjectMock.php`, etc.) and **`tests/Helpers/`** (`Utility.php`).
24+
25+
### Coverage and reports
26+
27+
- `phpunit.xml` logs JUnit, coverage (HTML, text, Clover), and testdox output under **`build/`** (e.g. `build/coverage/`, `build/logs/`). Add `build/` to `.gitignore` if generating locally; do not commit generated artifacts unless the project asks for them.
28+
29+
### Expectations for contributions
30+
31+
- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) requires tests for changes; new behavior should include PHPUnit coverage in the same PR where feasible.
32+
33+
### Credentials
34+
35+
- Tests use mocks and fixtures; do not add real API keys or stack secrets to the repo.
36+
37+
## References
38+
39+
- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)
40+
- [`contentstack-utils/SKILL.md`](../contentstack-utils/SKILL.md)

0 commit comments

Comments
 (0)