contentstack · reeshika-h · Apr 6, 2026 · Apr 6, 2026
@@ -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.
@@ -0,0 +1,53 @@
+# Contentstack Utils (Java) – 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-java](https://github.com/contentstack/contentstack-utils-java) — Maven `com.contentstack.sdk:utils` |
+| **Purpose:** | Library for rendering **Rich Text Editor (RTE)** content and **embedded items** from Contentstack entry JSON (REST/CDA-style with `_embedded_items`) and GraphQL-shaped responses. Consumed by the [Contentstack Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) and apps that already hold entry JSON. |
+| **Out of scope (if any):** | **No HTTP client** in this package: no stack API calls, tokens, or `includeEmbeddedItems()` — those belong to the Delivery SDK or your app. Optional **`sample/`** wires the SDK + Utils for manual testing only. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+|------|---------|
+| **Language** | Java **17** — `maven-compiler-plugin` `<release>17</release>` in root `pom.xml` (legacy `1.8` properties in `pom.xml` are not authoritative). |
+| **Build** | **Maven** — root `pom.xml`; optional module `sample/pom.xml`. |
+| **Tests** | **JUnit 4**, Maven **Surefire** (`src/test/java/com/contentstack/utils/**/*.java`). Surefire **`testFailureIgnore`** is `true` — check `target/surefire-reports/`. |
+| **Lint / coverage** | No Checkstyle/Spotless in repo — match existing style. **JaCoCo** (`target/site/jacoco/` after `mvn test`). |
+| **Other** | JSON: `org.json`, `json-simple` (provided). HTML: **Jsoup**. `spring-web` compile dependency — not a public REST client API for this module. **Snyk** on PRs (`.github/workflows/sca-scan.yml`). |
+
+## Commands (quick reference)
+
+| Command type | Command |
+|--------------|---------|
+| **Build** | `mvn clean compile` |
+| **Test** | `mvn clean test` |
+| **Lint** | *(none configured — rely on IDE and code review)* |
+
+| Optional | Command / location |
+|----------|---------------------|
+| Single test class | `mvn test -Dtest=UtilTests` |
+| Javadoc | `mvn javadoc:javadoc` |
+| Sample (after `mvn install` with skips if needed) | `mvn -f sample/pom.xml compile` |
+| **CI** | Java **17** publish: `.github/workflows/maven-publish.yml` · SCA: `.github/workflows/sca-scan.yml` · branch rules: `.github/workflows/check-branch.yml` |
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, build/test commands, PR expectations, optional TDD. |
+| **Java (language & layout)** | [`skills/java/SKILL.md`](skills/java/SKILL.md) | Java 17, `com.contentstack.utils` packages, naming, JSON/Jsoup, dependencies. |
+| **Contentstack Utils API** | [`skills/contentstack-utils-java/SKILL.md`](skills/contentstack-utils-java/SKILL.md) | Public API: `Utils`, `GQL`, `DefaultOption`, JSON contracts, RTE/embedded boundaries. |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | JUnit 4, fixtures, Surefire/JaCoCo, offline tests vs `sample/`. |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist, optional Blocker/Major/Minor. |
+| **Framework (build & tooling)** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | Maven plugins, publishing, GPG, Central, `sample/` dependency hygiene. |
+
+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.
@@ -0,0 +1,16 @@
+# Skills – Contentstack Utils (Java)
+
+Source of truth for detailed guidance. Read **`AGENTS.md`** first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+|--------------|----------|
+| **dev-workflow** | Branches, CI, how to run build/test, PR expectations, optional TDD. |
+| **java** | Java 17 conventions, package layout under `com.contentstack.utils`, JSON/Jsoup, Javadoc, dependency discipline. |
+| **contentstack-utils-java** | Changing `Utils`, `GQL`, `DefaultOption`, callbacks, embedded/RTE behavior or JSON contracts. |
+| **testing** | Writing or refactoring tests, fixtures, Surefire/JaCoCo, offline tests. |
+| **code-review** | Reviewing a PR or self-review before merge. |
+| **framework** | Editing `pom.xml`, plugins, release signing, Maven Central, or `sample/` dependency versions. |
+
+Each folder contains **`SKILL.md`** with YAML frontmatter (`name`, `description`).
@@ -0,0 +1,49 @@
+---
+name: code-review
+description: PR checklist and optional Blocker/Major/Minor — use when reviewing or before submitting a PR
+---
+
+# Code review – Contentstack Utils (Java)
+
+## When to use
+
+- Reviewing another contributor’s pull request.
+- Self-review before merge.
+- Auditing API, security, or test coverage for a change set.
+
+## Instructions
+
+### API design and stability
+
+- [ ] **Public API:** New or changed methods on `Utils`, `GQL`, `DefaultOption`, or `interfaces` are necessary, Javadoc’d, and safe for `com.contentstack.sdk:utils` consumers.
+- [ ] **Backward compatibility:** Breaking changes only with major version / **`Changelog.md`** plan.
+- [ ] **Naming:** Consistent with existing Utils and RTE/embedded terminology.
+
+### Error handling and robustness
+
+- [ ] **JSON:** Missing keys / `_embedded_items` behave predictably; no accidental NPEs or silent semantic changes.
+- [ ] **Null safety:** `JSONObject` / `JSONArray` access follows existing `opt*` / `has` patterns.
+
+### Dependencies and security
+
+- [ ] **Dependencies:** `pom.xml` changes are justified; consider downstream Java SDK consumers.
+- [ ] **SCA:** Snyk / team process (`.github/workflows/sca-scan.yml`) — address or defer with a ticket.
+
+### Testing
+
+- [ ] **Coverage:** New behavior has tests and fixtures under `src/test/java` / `src/test/resources` as needed.
+- [ ] **Surefire:** With `testFailureIgnore`, verify **`target/surefire-reports/`**, not only exit code.
+
+### Severity (optional)
+
+| Level | Examples |
+|-------|----------|
+| **Blocker** | Unapproved breaking public API; critical CVE; no tests for new behavior. |
+| **Major** | Undocumented HTML/JSON behavior change; missing Javadoc on new public API; risky dependency bump. |
+| **Minor** | Style, typos, internal refactor with equivalent coverage. |
+
+## References
+
+- **`skills/testing/SKILL.md`** — test conventions and Surefire.
+- **`skills/contentstack-utils-java/SKILL.md`** — API boundaries.
+- **`AGENTS.md`** — stack and commands.
@@ -0,0 +1,44 @@
+---
+name: contentstack-utils-java
+description: Public API — Utils, GQL, DefaultOption, RTE/embedded JSON; use when changing SDK behavior or contracts
+---
+
+# Contentstack Utils API – Contentstack Utils (Java)
+
+## When to use
+
+- Changing **`Utils`**, **`GQL`**, **`DefaultOption`**, **`Option`**, callbacks, or embedded/RTE logic.
+- Reviewing JSON shape assumptions for CDA or GraphQL responses.
+
+## Instructions
+
+### Scope
+
+- Artifact **`com.contentstack.sdk:utils`** only **transforms** JSON that apps or the [Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) already fetched.
+- **Authentication, API keys, delivery tokens, and `includeEmbeddedItems()`** are out of scope here — handled by the SDK or app code.
+
+### Entry points
+
+- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `renderContents`, `jsonToHTML` for REST/CDA-style JSON with `_embedded_items`; dot-paths into entries (e.g. `group.field`). Variant-related helpers as documented in `Utils`.
+- **`com.contentstack.utils.GQL`** — `jsonToHTML` for GraphQL-shaped entries (`embedded_itemsConnection`, `edges`, `node`, JSON RTE under `json`). Do not instantiate `GQL` (private constructor).
+
+### Rendering and options
+
+- Implement **`com.contentstack.utils.interfaces.Option`** or extend **`com.contentstack.utils.render.DefaultOption`** for custom embedded HTML, marks, and nodes.
+- Use **`com.contentstack.utils.interfaces.NodeCallback`** and **`com.contentstack.utils.helper.Metadata`** with **`embedded.StyleType`** / **`embedded.ItemType`** as in existing code.
+
+### Data flow and compatibility
+
+- Shared traversal: **`AutomateCommon`**; JSON RTE trees: **`NodeToHTML`**.
+- Preserve keys and HTML class names (`_embedded_items`, `embedded-entry`, etc.) unless shipping a **breaking** version with changelog.
+- Prefer null-safe **`opt*`** / **`has`** on `JSONObject` / `JSONArray`.
+
+### Alignment with Contentstack
+
+- Entry JSON shapes align with the [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) as consumed by the Java SDK; root **`README.md`** shows `Contentstack.stack`, `Entry`, `Query` usage **outside** this JAR.
+
+## References
+
+- **`skills/java/SKILL.md`** — language and package conventions.
+- **`skills/testing/SKILL.md`** — tests for API changes.
+- Root **`README.md`** — Maven coordinates and embedded-items examples.
@@ -0,0 +1,52 @@
+---
+name: dev-workflow
+description: Branches, CI, build and test commands, PR expectations, optional TDD — use when onboarding or before a PR
+---
+
+# Development workflow – Contentstack Utils (Java)
+
+## When to use
+
+- Starting work in this repository or onboarding.
+- Before opening or updating a pull request.
+- You need the canonical commands for build, test, sample, and CI pointers.
+
+## Instructions
+
+### Branches
+
+- Default integration for PRs is often **`staging`**; merging into **`master`** may be restricted (see `.github/workflows/check-branch.yml`).
+- Feature/fix branches often use ticket-style names (e.g. `fix/DX-5734`).
+
+### Running tests and builds
+
+- **All tests:** `mvn test`
+- **Compile only:** `mvn clean compile`
+- **Full check before PR:** `mvn clean test` (and `mvn -f sample/pom.xml compile` if you changed `sample/` — install parent first; see `skills/framework/SKILL.md`).
+- Review **`target/surefire-reports/`** when debugging: **`testFailureIgnore`** is `true` in `pom.xml` (see `skills/testing/SKILL.md`).
+
+### Pull requests
+
+- Describe the change; link issues/tickets when applicable.
+- Keep public API backward-compatible unless releasing a breaking version; update **`Changelog.md`** for user-visible behavior.
+- Use **`skills/code-review/SKILL.md`** as the review checklist.
+
+### Optional: TDD
+
+- If the team uses TDD: RED → GREEN → REFACTOR. Structure and Surefire behavior are in **`skills/testing/SKILL.md`**.
+
+### CI and security
+
+- **Java 17** in `.github/workflows/maven-publish.yml`.
+- **Snyk** Maven scan on PRs: `.github/workflows/sca-scan.yml`.
+- **Javadoc:** optional locally `mvn javadoc:javadoc`; attach phase uses `-Xdoclint:none` per `pom.xml`.
+
+### Lint / format
+
+- No repo-wide Checkstyle/Spotless — match existing style (`skills/java/SKILL.md`).
+
+## References
+
+- **`skills/testing/SKILL.md`** — Surefire, JaCoCo, fixtures.
+- **`skills/framework/SKILL.md`** — Maven install skips, publishing, `sample/pom.xml`.
+- **`AGENTS.md`** — commands quick reference.
@@ -0,0 +1,64 @@
+---
+name: framework
+description: Maven, plugins, Java 17, publishing, sample module deps — use when editing pom.xml or release tooling
+---
+
+# Framework (build & tooling) – Contentstack Utils (Java)
+
+## When to use
+
+- Editing root **`pom.xml`** or **`sample/pom.xml`**.
+- Changing release/publish flow, signing, or CI-related Maven settings.
+- Aligning **`sample/`** `contentstack.utils.version` with a new library release.
+
+## Instructions
+
+### Build commands
+
+```bash
+mvn clean compile
+mvn test
+mvn package
+```
+
+Local install without GPG/Javadoc (common for dev before `sample/`):
+
+```bash
+mvn install -DskipTests -Dmaven.javadoc.skip=true -Dgpg.skip=true
+```
+
+### Java version
+
+- **`maven-compiler-plugin`** — **`<release>17</release>`**. Match **Java 17** locally and in `.github/workflows/maven-publish.yml`.
+
+### Key plugins (root `pom.xml`)
+
+| Plugin | Role |
+|--------|------|
+| `maven-surefire-plugin` | Runs JUnit; note `testFailureIgnore` |
+| `jacoco-maven-plugin` | Coverage → `target/site/jacoco/` |
+| `maven-javadoc-plugin` | Javadoc JAR; `-Xdoclint:none` in execution |
+| `central-publishing-maven-plugin` | Maven Central publishing |
+| `maven-gpg-plugin` | Signs artifacts on release |
+
+### Coordinates
+
+- **groupId:** `com.contentstack.sdk`
+- **artifactId:** `utils`
+- **version:** root `pom.xml` `<version>`
+
+### Dependency hygiene
+
+- Keep the dependency set small; this JAR is pulled in by the Contentstack Java SDK.
+- **Snyk** on PRs: `.github/workflows/sca-scan.yml`.
+- **`sample/pom.xml`:** Keep **`contentstack.utils.version`** in sync when bumping the root version; use **`dependencyManagement`** for transitive CVE overrides when needed.
+
+### Formatting
+
+- No Checkstyle/Spotless — match surrounding code (`skills/java/SKILL.md`).
+
+## References
+
+- **`skills/dev-workflow/SKILL.md`** — when to run full build/test.
+- **`skills/testing/SKILL.md`** — Surefire/JaCoCo behavior.
+- **`AGENTS.md`** — CI file pointers.
@@ -0,0 +1,54 @@
+---
+name: java
+description: Java 17, package layout, naming, JSON/Jsoup, Javadoc — use when editing any production or test Java in this repo
+---
+
+# Java – Contentstack Utils (Java)
+
+## When to use
+
+- Editing any `.java` file under this repository.
+- Adding dependencies or debating style vs other Contentstack SDKs.
+
+## Instructions
+
+### Language and runtime
+
+- **Java 17** via `maven-compiler-plugin` `<release>17</release>` in `pom.xml`. Ignore legacy `maven.compiler.source/target` `1.8` — the compiler plugin wins.
+- Avoid raw types; use generics where applicable.
+
+### Package and layout
+
+- Production code lives under **`com.contentstack.utils`** and subpackages: `render`, `node`, `embedded`, `helper`, `interfaces`.
+- Do not add new top-level packages without team alignment.
+
+### Naming
+
+- **Classes:** PascalCase (`Utils`, `DefaultOption`, `AutomateCommon`).
+- **Methods / variables:** camelCase.
+- **Tests:** Mixed conventions already in use — see **`skills/testing/SKILL.md`**.
+
+### JSON and HTML
+
+- Prefer **`org.json`** (`JSONObject`, `JSONArray`) for APIs and internals used by `Utils` and `GQL`.
+- Use **Jsoup** for RTE HTML; follow patterns in `AutomateCommon` and `Utils`.
+
+### Validation and utility types
+
+- `javax.validation.constraints` (e.g. `@NotNull`) on some public methods — keep Javadoc aligned with null behavior.
+- Private constructors for non-instantiable types where the codebase already does (`GQL`, `AutomateCommon`).
+
+### Dependencies
+
+- Small JAR consumed by the Contentstack Java SDK — prefer minimal dependencies; justify additions in `pom.xml`.
+- **No Lombok** in this repo unless explicitly adopted by the team.
+
+### Documentation
+
+- Javadoc on public API; examples must match real entry points (`Utils.render`, `GQL.jsonToHTML`, `DefaultOption`).
+
+## References
+
+- **`skills/contentstack-utils-java/SKILL.md`** — RTE, embedded, GraphQL shapes.
+- **`skills/testing/SKILL.md`** — test naming and layout.
+- **`AGENTS.md`** — tech stack summary.
@@ -0,0 +1,47 @@
+---
+name: testing
+description: JUnit 4, Surefire, JaCoCo, fixtures, offline policy — use when adding or changing tests
+---
+
+# Testing – Contentstack Utils (Java)
+
+## When to use
+
+- Creating or editing tests under `src/test/java/com/contentstack/utils/`.
+- Adding JSON under `src/test/resources/`.
+- Investigating CI failures or coverage gaps.
+
+## Instructions
+
+### Framework
+
+- **JUnit 4** (`junit:junit`, test scope in `pom.xml`).
+- **Maven Surefire** runs classes from `src/test/java`.
+
+### Surefire caveat
+
+- **`testFailureIgnore`** is **`true`** in `pom.xml`. Always inspect **`target/surefire-reports/`** — a successful Maven exit code does not guarantee all tests passed.
+
+### Naming and layout
+
+- Mirror package **`com.contentstack.utils`**.
+- Existing patterns: `UtilTests`, `DefaultOptionTests`, `AssetLinkTest`, `TestRte`, `TestMetadata`, `Test*`, `*Test`, `*Tests`.
+- No separate `*IT` Maven profile in this repo; optional **`sample/`** uses the Delivery SDK with env vars (see `sample/README.md`).
+
+### Fixtures
+
+- JSON and assets under **`src/test/resources/`** (e.g. `multiple_rich_text_content.json`, `reports/`). Loading patterns: `ReadResource`, `UtilTests` `@BeforeClass`.
+
+### Helpers
+
+- `ReadResource`, `DefaultOptionClass`, and similar helpers — keep tests **deterministic** and **offline** (no live API for default unit tests).
+
+### Coverage
+
+- **JaCoCo** on `mvn test`; HTML report **`target/site/jacoco/index.html`**.
+
+## References
+
+- **`skills/dev-workflow/SKILL.md`** — when to run tests before PRs.
+- **`skills/framework/SKILL.md`** — Maven/Surefire configuration.
+- **`skills/code-review/SKILL.md`** — test expectations for reviews.