Skip to content

Commit 37981cf

Browse files
reeshika-hreeshika-h
authored
Merge pull request #137 from contentstack/DX-5368-cursor
Added cursor rules and skills
2 parents 3b63ad5 + 8ed862a commit 37981cf

9 files changed

Lines changed: 384 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: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Contentstack Utils (Java) – 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-java](https://github.com/contentstack/contentstack-utils-java) — Maven `com.contentstack.sdk:utils` |
10+
| **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. |
11+
| **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. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
|------|---------|
17+
| **Language** | Java **17** — `maven-compiler-plugin` `<release>17</release>` in root `pom.xml` (legacy `1.8` properties in `pom.xml` are not authoritative). |
18+
| **Build** | **Maven** — root `pom.xml`; optional module `sample/pom.xml`. |
19+
| **Tests** | **JUnit 4**, Maven **Surefire** (`src/test/java/com/contentstack/utils/**/*.java`). Surefire **`testFailureIgnore`** is `true` — check `target/surefire-reports/`. |
20+
| **Lint / coverage** | No Checkstyle/Spotless in repo — match existing style. **JaCoCo** (`target/site/jacoco/` after `mvn test`). |
21+
| **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`). |
22+
23+
## Commands (quick reference)
24+
25+
| Command type | Command |
26+
|--------------|---------|
27+
| **Build** | `mvn clean compile` |
28+
| **Test** | `mvn clean test` |
29+
| **Lint** | *(none configured — rely on IDE and code review)* |
30+
31+
| Optional | Command / location |
32+
|----------|---------------------|
33+
| Single test class | `mvn test -Dtest=UtilTests` |
34+
| Javadoc | `mvn javadoc:javadoc` |
35+
| Sample (after `mvn install` with skips if needed) | `mvn -f sample/pom.xml compile` |
36+
| **CI** | Java **17** publish: `.github/workflows/maven-publish.yml` · SCA: `.github/workflows/sca-scan.yml` · branch rules: `.github/workflows/check-branch.yml` |
37+
38+
## Where the documentation lives: skills
39+
40+
| Skill | Path | What it covers |
41+
|-------|------|----------------|
42+
| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, build/test commands, PR expectations, optional TDD. |
43+
| **Java (language & layout)** | [`skills/java/SKILL.md`](skills/java/SKILL.md) | Java 17, `com.contentstack.utils` packages, naming, JSON/Jsoup, dependencies. |
44+
| **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. |
45+
| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | JUnit 4, fixtures, Surefire/JaCoCo, offline tests vs `sample/`. |
46+
| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist, optional Blocker/Major/Minor. |
47+
| **Framework (build & tooling)** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | Maven plugins, publishing, GPG, Central, `sample/` dependency hygiene. |
48+
49+
An index with **when to use** hints is in [`skills/README.md`](skills/README.md).
50+
51+
## Using Cursor (optional)
52+
53+
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: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Skills – Contentstack Utils (Java)
2+
3+
Source of truth for detailed guidance. Read **`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** | Branches, CI, how to run build/test, PR expectations, optional TDD. |
10+
| **java** | Java 17 conventions, package layout under `com.contentstack.utils`, JSON/Jsoup, Javadoc, dependency discipline. |
11+
| **contentstack-utils-java** | Changing `Utils`, `GQL`, `DefaultOption`, callbacks, embedded/RTE behavior or JSON contracts. |
12+
| **testing** | Writing or refactoring tests, fixtures, Surefire/JaCoCo, offline tests. |
13+
| **code-review** | Reviewing a PR or self-review before merge. |
14+
| **framework** | Editing `pom.xml`, plugins, release signing, Maven Central, or `sample/` dependency versions. |
15+
16+
Each folder contains **`SKILL.md`** with YAML frontmatter (`name`, `description`).

‎skills/code-review/SKILL.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
name: code-review
3+
description: PR checklist and optional Blocker/Major/Minor — use when reviewing or before submitting a PR
4+
---
5+
6+
# Code review – Contentstack Utils (Java)
7+
8+
## When to use
9+
10+
- Reviewing another contributor’s pull request.
11+
- Self-review before merge.
12+
- Auditing API, security, or test coverage for a change set.
13+
14+
## Instructions
15+
16+
### API design and stability
17+
18+
- [ ] **Public API:** New or changed methods on `Utils`, `GQL`, `DefaultOption`, or `interfaces` are necessary, Javadoc’d, and safe for `com.contentstack.sdk:utils` consumers.
19+
- [ ] **Backward compatibility:** Breaking changes only with major version / **`Changelog.md`** plan.
20+
- [ ] **Naming:** Consistent with existing Utils and RTE/embedded terminology.
21+
22+
### Error handling and robustness
23+
24+
- [ ] **JSON:** Missing keys / `_embedded_items` behave predictably; no accidental NPEs or silent semantic changes.
25+
- [ ] **Null safety:** `JSONObject` / `JSONArray` access follows existing `opt*` / `has` patterns.
26+
27+
### Dependencies and security
28+
29+
- [ ] **Dependencies:** `pom.xml` changes are justified; consider downstream Java SDK consumers.
30+
- [ ] **SCA:** Snyk / team process (`.github/workflows/sca-scan.yml`) — address or defer with a ticket.
31+
32+
### Testing
33+
34+
- [ ] **Coverage:** New behavior has tests and fixtures under `src/test/java` / `src/test/resources` as needed.
35+
- [ ] **Surefire:** With `testFailureIgnore`, verify **`target/surefire-reports/`**, not only exit code.
36+
37+
### Severity (optional)
38+
39+
| Level | Examples |
40+
|-------|----------|
41+
| **Blocker** | Unapproved breaking public API; critical CVE; no tests for new behavior. |
42+
| **Major** | Undocumented HTML/JSON behavior change; missing Javadoc on new public API; risky dependency bump. |
43+
| **Minor** | Style, typos, internal refactor with equivalent coverage. |
44+
45+
## References
46+
47+
- **`skills/testing/SKILL.md`** — test conventions and Surefire.
48+
- **`skills/contentstack-utils-java/SKILL.md`** — API boundaries.
49+
- **`AGENTS.md`** — stack and commands.

‎skills/contentstack-utils-java/SKILL.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: contentstack-utils-java
3+
description: Public API — Utils, GQL, DefaultOption, RTE/embedded JSON; use when changing SDK behavior or contracts
4+
---
5+
6+
# Contentstack Utils API – Contentstack Utils (Java)
7+
8+
## When to use
9+
10+
- Changing **`Utils`**, **`GQL`**, **`DefaultOption`**, **`Option`**, callbacks, or embedded/RTE logic.
11+
- Reviewing JSON shape assumptions for CDA or GraphQL responses.
12+
13+
## Instructions
14+
15+
### Scope
16+
17+
- 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.
18+
- **Authentication, API keys, delivery tokens, and `includeEmbeddedItems()`** are out of scope here — handled by the SDK or app code.
19+
20+
### Entry points
21+
22+
- **`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`.
23+
- **`com.contentstack.utils.GQL`** — `jsonToHTML` for GraphQL-shaped entries (`embedded_itemsConnection`, `edges`, `node`, JSON RTE under `json`). Do not instantiate `GQL` (private constructor).
24+
25+
### Rendering and options
26+
27+
- Implement **`com.contentstack.utils.interfaces.Option`** or extend **`com.contentstack.utils.render.DefaultOption`** for custom embedded HTML, marks, and nodes.
28+
- Use **`com.contentstack.utils.interfaces.NodeCallback`** and **`com.contentstack.utils.helper.Metadata`** with **`embedded.StyleType`** / **`embedded.ItemType`** as in existing code.
29+
30+
### Data flow and compatibility
31+
32+
- Shared traversal: **`AutomateCommon`**; JSON RTE trees: **`NodeToHTML`**.
33+
- Preserve keys and HTML class names (`_embedded_items`, `embedded-entry`, etc.) unless shipping a **breaking** version with changelog.
34+
- Prefer null-safe **`opt*`** / **`has`** on `JSONObject` / `JSONArray`.
35+
36+
### Alignment with Contentstack
37+
38+
- 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.
39+
40+
## References
41+
42+
- **`skills/java/SKILL.md`** — language and package conventions.
43+
- **`skills/testing/SKILL.md`** — tests for API changes.
44+
- Root **`README.md`** — Maven coordinates and embedded-items examples.

‎skills/dev-workflow/SKILL.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: dev-workflow
3+
description: Branches, CI, build and test commands, PR expectations, optional TDD — use when onboarding or before a PR
4+
---
5+
6+
# Development workflow – Contentstack Utils (Java)
7+
8+
## When to use
9+
10+
- Starting work in this repository or onboarding.
11+
- Before opening or updating a pull request.
12+
- You need the canonical commands for build, test, sample, and CI pointers.
13+
14+
## Instructions
15+
16+
### Branches
17+
18+
- Default integration for PRs is often **`staging`**; merging into **`master`** may be restricted (see `.github/workflows/check-branch.yml`).
19+
- Feature/fix branches often use ticket-style names (e.g. `fix/DX-5734`).
20+
21+
### Running tests and builds
22+
23+
- **All tests:** `mvn test`
24+
- **Compile only:** `mvn clean compile`
25+
- **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`).
26+
- Review **`target/surefire-reports/`** when debugging: **`testFailureIgnore`** is `true` in `pom.xml` (see `skills/testing/SKILL.md`).
27+
28+
### Pull requests
29+
30+
- Describe the change; link issues/tickets when applicable.
31+
- Keep public API backward-compatible unless releasing a breaking version; update **`Changelog.md`** for user-visible behavior.
32+
- Use **`skills/code-review/SKILL.md`** as the review checklist.
33+
34+
### Optional: TDD
35+
36+
- If the team uses TDD: RED → GREEN → REFACTOR. Structure and Surefire behavior are in **`skills/testing/SKILL.md`**.
37+
38+
### CI and security
39+
40+
- **Java 17** in `.github/workflows/maven-publish.yml`.
41+
- **Snyk** Maven scan on PRs: `.github/workflows/sca-scan.yml`.
42+
- **Javadoc:** optional locally `mvn javadoc:javadoc`; attach phase uses `-Xdoclint:none` per `pom.xml`.
43+
44+
### Lint / format
45+
46+
- No repo-wide Checkstyle/Spotless — match existing style (`skills/java/SKILL.md`).
47+
48+
## References
49+
50+
- **`skills/testing/SKILL.md`** — Surefire, JaCoCo, fixtures.
51+
- **`skills/framework/SKILL.md`** — Maven install skips, publishing, `sample/pom.xml`.
52+
- **`AGENTS.md`** — commands quick reference.

‎skills/framework/SKILL.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
name: framework
3+
description: Maven, plugins, Java 17, publishing, sample module deps — use when editing pom.xml or release tooling
4+
---
5+
6+
# Framework (build & tooling) – Contentstack Utils (Java)
7+
8+
## When to use
9+
10+
- Editing root **`pom.xml`** or **`sample/pom.xml`**.
11+
- Changing release/publish flow, signing, or CI-related Maven settings.
12+
- Aligning **`sample/`** `contentstack.utils.version` with a new library release.
13+
14+
## Instructions
15+
16+
### Build commands
17+
18+
```bash
19+
mvn clean compile
20+
mvn test
21+
mvn package
22+
```
23+
24+
Local install without GPG/Javadoc (common for dev before `sample/`):
25+
26+
```bash
27+
mvn install -DskipTests -Dmaven.javadoc.skip=true -Dgpg.skip=true
28+
```
29+
30+
### Java version
31+
32+
- **`maven-compiler-plugin`** — **`<release>17</release>`**. Match **Java 17** locally and in `.github/workflows/maven-publish.yml`.
33+
34+
### Key plugins (root `pom.xml`)
35+
36+
| Plugin | Role |
37+
|--------|------|
38+
| `maven-surefire-plugin` | Runs JUnit; note `testFailureIgnore` |
39+
| `jacoco-maven-plugin` | Coverage → `target/site/jacoco/` |
40+
| `maven-javadoc-plugin` | Javadoc JAR; `-Xdoclint:none` in execution |
41+
| `central-publishing-maven-plugin` | Maven Central publishing |
42+
| `maven-gpg-plugin` | Signs artifacts on release |
43+
44+
### Coordinates
45+
46+
- **groupId:** `com.contentstack.sdk`
47+
- **artifactId:** `utils`
48+
- **version:** root `pom.xml` `<version>`
49+
50+
### Dependency hygiene
51+
52+
- Keep the dependency set small; this JAR is pulled in by the Contentstack Java SDK.
53+
- **Snyk** on PRs: `.github/workflows/sca-scan.yml`.
54+
- **`sample/pom.xml`:** Keep **`contentstack.utils.version`** in sync when bumping the root version; use **`dependencyManagement`** for transitive CVE overrides when needed.
55+
56+
### Formatting
57+
58+
- No Checkstyle/Spotless — match surrounding code (`skills/java/SKILL.md`).
59+
60+
## References
61+
62+
- **`skills/dev-workflow/SKILL.md`** — when to run full build/test.
63+
- **`skills/testing/SKILL.md`** — Surefire/JaCoCo behavior.
64+
- **`AGENTS.md`** — CI file pointers.

‎skills/java/SKILL.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
name: java
3+
description: Java 17, package layout, naming, JSON/Jsoup, Javadoc — use when editing any production or test Java in this repo
4+
---
5+
6+
# Java – Contentstack Utils (Java)
7+
8+
## When to use
9+
10+
- Editing any `.java` file under this repository.
11+
- Adding dependencies or debating style vs other Contentstack SDKs.
12+
13+
## Instructions
14+
15+
### Language and runtime
16+
17+
- **Java 17** via `maven-compiler-plugin` `<release>17</release>` in `pom.xml`. Ignore legacy `maven.compiler.source/target` `1.8` — the compiler plugin wins.
18+
- Avoid raw types; use generics where applicable.
19+
20+
### Package and layout
21+
22+
- Production code lives under **`com.contentstack.utils`** and subpackages: `render`, `node`, `embedded`, `helper`, `interfaces`.
23+
- Do not add new top-level packages without team alignment.
24+
25+
### Naming
26+
27+
- **Classes:** PascalCase (`Utils`, `DefaultOption`, `AutomateCommon`).
28+
- **Methods / variables:** camelCase.
29+
- **Tests:** Mixed conventions already in use — see **`skills/testing/SKILL.md`**.
30+
31+
### JSON and HTML
32+
33+
- Prefer **`org.json`** (`JSONObject`, `JSONArray`) for APIs and internals used by `Utils` and `GQL`.
34+
- Use **Jsoup** for RTE HTML; follow patterns in `AutomateCommon` and `Utils`.
35+
36+
### Validation and utility types
37+
38+
- `javax.validation.constraints` (e.g. `@NotNull`) on some public methods — keep Javadoc aligned with null behavior.
39+
- Private constructors for non-instantiable types where the codebase already does (`GQL`, `AutomateCommon`).
40+
41+
### Dependencies
42+
43+
- Small JAR consumed by the Contentstack Java SDK — prefer minimal dependencies; justify additions in `pom.xml`.
44+
- **No Lombok** in this repo unless explicitly adopted by the team.
45+
46+
### Documentation
47+
48+
- Javadoc on public API; examples must match real entry points (`Utils.render`, `GQL.jsonToHTML`, `DefaultOption`).
49+
50+
## References
51+
52+
- **`skills/contentstack-utils-java/SKILL.md`** — RTE, embedded, GraphQL shapes.
53+
- **`skills/testing/SKILL.md`** — test naming and layout.
54+
- **`AGENTS.md`** — tech stack summary.

‎skills/testing/SKILL.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
name: testing
3+
description: JUnit 4, Surefire, JaCoCo, fixtures, offline policy — use when adding or changing tests
4+
---
5+
6+
# Testing – Contentstack Utils (Java)
7+
8+
## When to use
9+
10+
- Creating or editing tests under `src/test/java/com/contentstack/utils/`.
11+
- Adding JSON under `src/test/resources/`.
12+
- Investigating CI failures or coverage gaps.
13+
14+
## Instructions
15+
16+
### Framework
17+
18+
- **JUnit 4** (`junit:junit`, test scope in `pom.xml`).
19+
- **Maven Surefire** runs classes from `src/test/java`.
20+
21+
### Surefire caveat
22+
23+
- **`testFailureIgnore`** is **`true`** in `pom.xml`. Always inspect **`target/surefire-reports/`** — a successful Maven exit code does not guarantee all tests passed.
24+
25+
### Naming and layout
26+
27+
- Mirror package **`com.contentstack.utils`**.
28+
- Existing patterns: `UtilTests`, `DefaultOptionTests`, `AssetLinkTest`, `TestRte`, `TestMetadata`, `Test*`, `*Test`, `*Tests`.
29+
- No separate `*IT` Maven profile in this repo; optional **`sample/`** uses the Delivery SDK with env vars (see `sample/README.md`).
30+
31+
### Fixtures
32+
33+
- JSON and assets under **`src/test/resources/`** (e.g. `multiple_rich_text_content.json`, `reports/`). Loading patterns: `ReadResource`, `UtilTests` `@BeforeClass`.
34+
35+
### Helpers
36+
37+
- `ReadResource`, `DefaultOptionClass`, and similar helpers — keep tests **deterministic** and **offline** (no live API for default unit tests).
38+
39+
### Coverage
40+
41+
- **JaCoCo** on `mvn test`; HTML report **`target/site/jacoco/index.html`**.
42+
43+
## References
44+
45+
- **`skills/dev-workflow/SKILL.md`** — when to run tests before PRs.
46+
- **`skills/framework/SKILL.md`** — Maven/Surefire configuration.
47+
- **`skills/code-review/SKILL.md`** — test expectations for reviews.

0 commit comments

Comments
 (0)