Merge pull request #13 from contentstack/feat/dx-5373-cursor-rules-skills

harshitha-cstk · web-flow · commit d3414f7ae532 · 2026-04-09T11:22:58.000+05:30
docs: add AGENTS.md, skills, and Cursor rules for contributors
diff --git a/.cursor/rules/README.md b/.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.
diff --git a/.github/workflows/check-branch.yml b/.github/workflows/check-branch.yml
@@ -8,13 +8,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Comment PR
-        if: github.base_ref == 'master' && github.head_ref != 'next'
+        if: github.base_ref == 'master' && github.head_ref != 'development'
         uses: thollander/actions-comment-pull-request@v2
         with:
           message: |
-            We regret to inform you that you are currently not able to merge your changes into the master branch due to restrictions applied by our SRE team. To proceed with merging your changes, we kindly request that you create a pull request from the next branch. Our team will then review the changes and work with you to ensure a successful merge into the master branch.
+            We regret to inform you that you are currently not able to merge your changes into the master branch due to restrictions applied by our SRE team. To proceed with merging your changes, we kindly request that you create a pull request from the development branch. Our team will then review the changes and work with you to ensure a successful merge into the master branch.
       - name: Check branch
-        if: github.base_ref == 'master' && github.head_ref != 'next'
+        if: github.base_ref == 'master' && github.head_ref != 'development'
         run: |
-          echo "ERROR: We regret to inform you that you are currently not able to merge your changes into the master branch due to restrictions applied by our SRE team. To proceed with merging your changes, we kindly request that you create a pull request from the next branch. Our team will then review the changes and work with you to ensure a successful merge into the master branch."
+          echo "ERROR: We regret to inform you that you are currently not able to merge your changes into the master branch due to restrictions applied by our SRE team. To proceed with merging your changes, we kindly request that you create a pull request from the development branch. Our team will then review the changes and work with you to ensure a successful merge into the master branch."
           exit 1
diff --git a/.github/workflows/issues-jira.yml b/.github/workflows/issues-jira.yml
@@ -0,0 +1,31 @@
+name: Create Jira Ticket for Github Issue
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  issue-jira:
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Login to Jira
+        uses: atlassian/gajira-login@master
+        env:
+          JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
+          JIRA_USER_EMAIL: ${{ secrets.JIRA_USER_EMAIL }}
+          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
+
+      - name: Create Jira Issue
+        id: create_jira
+        uses: atlassian/gajira-create@master
+        with:
+          project: ${{ secrets.JIRA_PROJECT }}
+          issuetype: ${{ secrets.JIRA_ISSUE_TYPE }}
+          summary: Github | Issue | ${{ github.event.repository.name }} | ${{ github.event.issue.title }}
+          description: |
+            *GitHub Issue:* ${{ github.event.issue.html_url }}
+            
+            *Description:*
+            ${{ github.event.issue.body }}
+          fields: "${{ secrets.ISSUES_JIRA_FIELDS }}"
diff --git a/.github/workflows/jira.yml b/.github/workflows/jira.yml
diff --git a/.github/workflows/policy-scan.yml b/.github/workflows/policy-scan.yml
@@ -0,0 +1,46 @@
+name: Checks the security policy and configurations
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  security-policy:
+    if: github.event.repository.visibility == 'public'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@master
+      - name: Checks for SECURITY.md policy file
+        run: |
+          if ! [[ -f "SECURITY.md" || -f ".github/SECURITY.md" ]]; then exit 1; fi
+  security-license:
+    if: github.event.repository.visibility == 'public'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@master
+      - name: Checks for License file
+        run: |
+          expected_license_files=("LICENSE" "LICENSE.txt" "LICENSE.md" "License.txt")
+          license_file_found=false
+          current_year=$(date +"%Y")
+
+          for license_file in "${expected_license_files[@]}"; do
+              if  [ -f "$license_file" ]; then
+                 license_file_found=true
+                 # check the license file for the current year, if not exists, exit with error
+                  if  ! grep -q "$current_year" "$license_file"; then
+                      echo "License file $license_file does not contain the current year."
+                      exit 2
+                  fi
+                  break
+              fi        
+          done
+
+          if [ "$license_file_found" = false ]; then
+              echo "No license file found. Please add a license file to the repository."
+              exit 1
+          fi
diff --git a/.github/workflows/sast-scan.yml b/.github/workflows/sast-scan.yml
diff --git a/.talismanrc b/.talismanrc
@@ -1,4 +1,7 @@
 fileignoreconfig:
+- filename: .github/workflows/secrets-scan.yml
+  ignore_detectors:
+    - filecontent
 - filename: composer.lock
   checksum: 3e19a34da8e50af426a1b648f3fb067592c3df08274fa553b7204fd4d326e1df
 - filename: README.md
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,48 @@
+# Contentstack Utils PHP – 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/utils](https://packagist.org/packages/contentstack/utils) · [GitHub](https://github.com/contentstack/contentstack-utils-php) |
+| **Purpose:** | PHP library for rendering Contentstack Rich Text (RTE) content and GraphQL-shaped JSON to HTML, including embedded entries and custom render options. |
+| **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. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | PHP `>=7.2` (Composer); CI runs on PHP 8.3. `declare(strict_types=1);` in source files. |
+| Build | [Composer](https://getcomposer.org/) — `composer.json`, `composer.lock`. No compile step; autoload PSR-4 `Contentstack\Utils\` → `src/`. |
+| Tests | PHPUnit 9.x via `composer test` / `phpunit`; suite in `tests/`, config `phpunit.xml`. |
+| Lint / coverage | PHP_CodeSniffer (PSR-2 ruleset) — `composer check-style` / `composer fix-style`; config `phpcs.xml.dist`. Coverage/logging paths under `build/` when generated. |
+| Other | Dev dependency `marc-mabe/php-enum` for enums. |
+
+## Commands (quick reference)
+
+| Command type | Command |
+| --- | --- |
+| Install deps | `composer install` |
+| Test | `composer test` |
+| Lint | `composer check-style` |
+| Format (fix) | `composer fix-style` |
+
+**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`.
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Dev workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, Composer scripts, PR expectations |
+| Contentstack Utils API | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | Public API, namespaces, extension points (`Option`, `RenderableInterface`) |
+| PHP style & layout | [`skills/php-style/SKILL.md`](skills/php-style/SKILL.md) | PSR-2, PHPCS, file layout under `src/` |
+| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | PHPUnit layout, mocks, coverage output |
+| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist aligned with this repo |
+
+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.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -1 +1,9 @@
-* @contentstack/security-admin
+* @contentstack/devex-pr-reviewers
+
+.github/workflows/sca-scan.yml @contentstack/security-admin
+
+**/.snyk @contentstack/security-admin
+
+.github/workflows/policy-scan.yml @contentstack/security-admin
+
+.github/workflows/issues-jira.yml @contentstack/security-admin
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
 
-Copyright (c) 2016-2024 Contentstack
+Copyright (c) 2016-2026 Contentstack
 
 > Permission is hereby granted, free of charge, to any person obtaining a copy
 > of this software and associated documentation files (the "Software"), to deal
diff --git a/skills/README.md b/skills/README.md
@@ -0,0 +1,15 @@
+# Skills – Contentstack Utils PHP
+
+Source of truth for detailed guidance. Read [`AGENTS.md`](../AGENTS.md) first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+| --- | --- |
+| [`dev-workflow`](dev-workflow/SKILL.md) | Running installs/tests, understanding CI, branch rules for PRs to `master` |
+| [`contentstack-utils`](contentstack-utils/SKILL.md) | Changing public APIs, `Utils` / `GQL`, parsers, models, or embed rendering |
+| [`php-style`](php-style/SKILL.md) | Code style, PHPCS/PSR-2, namespaces, or `src/` layout |
+| [`testing`](testing/SKILL.md) | Adding or changing PHPUnit tests, mocks, or coverage |
+| [`code-review`](code-review/SKILL.md) | Preparing or reviewing a PR for this repository |
+
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: code-review
+description: Use when reviewing or preparing a PR — tests, style, SemVer, docs, and branch rules for this repository.
+---
+
+# Code review – Contentstack Utils PHP
+
+## When to use
+
+- Authoring a pull request into this repo
+- Reviewing someone else’s PR for completeness and repo policy
+
+## Instructions
+
+### Checklist
+
+- **Tests:** New or changed behavior has PHPUnit coverage; `composer test` passes.
+- **Style:** `composer check-style` passes (PSR-2 via PHPCS).
+- **Docs:** User-visible behavior changes reflected in [`README.md`](../../README.md) or other maintainer-facing docs as appropriate.
+- **API / SemVer:** Public signatures and documented behavior follow semantic versioning expectations per [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+- **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.
+- **Commits:** Prefer coherent history; squash noisy WIP commits when requested.
+
+### Severity (optional labels)
+
+- **Blocker:** Breaks tests, CI, or documented security/policy requirements.
+- **Major:** Missing tests for non-trivial logic, public API breakage without version strategy, or policy violations (e.g. wrong base branch).
+- **Minor:** Style nits, naming, or internal refactors with no contract change.
+
+## References
+
+- [`CONTRIBUTING.md`](../../CONTRIBUTING.md)
+- [`PULL_REQUEST_TEMPLATE.md`](../../PULL_REQUEST_TEMPLATE.md)
+- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)
diff --git a/skills/contentstack-utils/SKILL.md b/skills/contentstack-utils/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: contentstack-utils
+description: Use when changing Utils, GQL, BaseParser, models, enums, or embed/render behavior — the library’s public surface and integration boundaries.
+---
+
+# Contentstack Utils API – Contentstack Utils PHP
+
+## When to use
+
+- Adding or changing HTML/RTE rendering or GraphQL JSON → HTML conversion
+- Extending or implementing render callbacks (`Option`, `RenderableInterface`)
+- Working with metadata, embedded items, or enum-backed node/mark types
+
+## Instructions
+
+### Package identity
+
+- Composer package: `contentstack/utils` ([Packagist](https://packagist.org/packages/contentstack/utils)); PSR-4 root namespace `Contentstack\Utils\` maps to `src/`.
+
+### Main entry points (illustrative)
+
+- **`Contentstack\Utils\Utils`** ([`src/Utils.php`](../../src/Utils.php)) — static helpers such as `renderContent` / `jsonToHtml` for RTE strings and JSON payloads; extends `BaseParser`.
+- **`Contentstack\Utils\GQL`** ([`src/GQL.php`](../../src/GQL.php)) — `jsonToHtml` and related parsing for GraphQL-shaped content; extends `BaseParser`.
+- **`Contentstack\Utils\BaseParser`** ([`src/BaseParser.php`](../../src/BaseParser.php)) — shared parsing and embedded-object resolution logic.
+
+### Extension / integration
+
+- **`Contentstack\Utils\Model\Option`** — configure rendering; subclasses override `renderMark`, `renderNode`, `renderOptions`, etc.
+- **`Contentstack\Utils\Resource\RenderableInterface`** — contract for types that participate in rendering.
+- **`Contentstack\Utils\Model\Metadata`** — embed metadata (e.g. style type, attributes).
+- **Enums** under `Contentstack\Utils\Enum\` (`NodeType`, `MarkType`, `StyleType`, `EmbedItemType`) use `marc-mabe/php-enum`.
+
+### Boundaries
+
+- 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`.
+- Prefer backward-compatible changes to public method signatures; follow SemVer.
+
+## References
+
+- [`testing/SKILL.md`](../testing/SKILL.md)
+- [`php-style/SKILL.md`](../php-style/SKILL.md)
+- [Product README — usage](../../README.md)
diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md
@@ -0,0 +1,44 @@
+---
+name: dev-workflow
+description: Use when running Composer, CI, or PRs to master/next — installs, tests, and branch policy for this repo.
+---
+
+# Dev workflow – Contentstack Utils PHP
+
+## When to use
+
+- Installing dependencies or running the test suite locally
+- Understanding what GitHub Actions run on push/PR
+- Opening or reviewing a PR and matching branch expectations
+
+## Instructions
+
+### Local setup
+
+- 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`).
+- Run tests: `composer test` (runs PHPUnit as defined in `composer.json`).
+
+### Lint
+
+- Check: `composer check-style` (PHPCS on `src` and `tests`).
+- Autofix where supported: `composer fix-style` (PHPCBF).
+
+### CI
+
+- [`ci.yml`](../../.github/workflows/ci.yml): `composer validate`, cache + `composer install`, then `composer run-script test`.
+- Lint is not currently enforced in that workflow; still run `check-style` before pushing.
+
+### Branch / PR policy
+
+- [`check-branch.yml`](../../.github/workflows/check-branch.yml): PRs **into `master`** must use branch **`next`** as the head branch (automation comments and fails otherwise).
+- Prefer feature branches (not your fork’s default branch name as the only source) per [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+
+### Releases / versioning
+
+- Project follows SemVer per [`CONTRIBUTING.md`](../../CONTRIBUTING.md); public API changes belong in changelog/release notes as the maintainers require.
+
+## References
+
+- [`AGENTS.md`](../../AGENTS.md)
+- [`testing/SKILL.md`](../testing/SKILL.md)
+- [`php-style/SKILL.md`](../php-style/SKILL.md)
diff --git a/skills/php-style/SKILL.md b/skills/php-style/SKILL.md
diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md
