Skip to content

Commit ee09d2d

Browse files
reeshika-hreeshika-h
authored
Merge pull request #238 from contentstack/DX-5379-cursor
Add agent guide and skills documentation
2 parents 1cf3783 + a4cbc18 commit ee09d2d

File tree

10 files changed

+311
-5
lines changed

10 files changed

+311
-5
lines changed

‎.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: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Contentstack Management Java SDK – 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-management-java](https://github.com/contentstack/contentstack-management-java) |
10+
| *Purpose:* | Java client library for the Contentstack Content Management API (CMA): create, update, delete, and fetch account content and configuration from JVM applications. |
11+
| *Out of scope (if any):* | Content Delivery API (CDA) and delivery-only use cases belong in the Delivery SDK, not this package. This SDK is read/write against CMA; do not treat it as the primary way to serve content to end users. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
| --- | --- |
17+
| Language | Java 8 (source/target in `pom.xml`); README suggests Java 8+ for consumers. |
18+
| Build | Apache Maven; `pom.xml` at repo root. |
19+
| Tests | JUnit 5 / Vintage, Mockito, OkHttp MockWebServer; tests under `src/test/java/com/contentstack/cms/`. |
20+
| Lint / coverage | Compiler: `-Xlint:all` (see `maven-compiler-plugin`). Coverage: JaCoCo (`jacoco-maven-plugin`); HTML report under `target/site/jacoco` after tests + `jacoco:report`. No separate Checkstyle/SpotBugs in this `pom.xml`. |
21+
| Other | HTTP: Retrofit 3, OkHttp 5, Gson; RxJava 3; Lombok for generated code. |
22+
23+
## Commands (quick reference)
24+
25+
| Command type | Command |
26+
| --- | --- |
27+
| Build | `mvn clean compile` |
28+
| Test | `mvn clean test -DskipTests=false` |
29+
| Lint | `mvn compile` (compiler warnings; see Tech stack) |
30+
| Coverage | `mvn clean test -DskipTests=false jacoco:report` (open `target/site/jacoco/index.html`) |
31+
32+
**Note:** `maven-surefire-plugin` sets `skipTests` to `true` by default in this repo, so you must pass `-DskipTests=false` (or override in your IDE) to run unit tests locally.
33+
34+
**CI:** [.github/workflows/coverage.yml](.github/workflows/coverage.yml) runs `mvn clean package` and JaCoCo steps on push. Other workflows under [.github/workflows/](.github/workflows/) handle publish, scans, and branch checks.
35+
36+
## Where the documentation lives: skills
37+
38+
| Skill | Path | What it covers |
39+
| --- | --- | --- |
40+
| Dev workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, Maven lifecycle, CI expectations, PR flow. |
41+
| Contentstack Java CMA SDK | [skills/contentstack-java-cma-sdk/SKILL.md](skills/contentstack-java-cma-sdk/SKILL.md) | Public API, `Contentstack` entry point, auth, versioning boundaries. |
42+
| Java (repo conventions) | [skills/java/SKILL.md](skills/java/SKILL.md) | Package layout, language conventions, Lombok usage. |
43+
| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Test layout, naming, skipping policy, credentials. |
44+
| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist and severity guidance. |
45+
| HTTP client stack | [skills/http-client-stack/SKILL.md](skills/http-client-stack/SKILL.md) | Retrofit, OkHttp, retries, logging—what this repo actually wires. |
46+
47+
An index with “when to use” hints is in [skills/README.md](skills/README.md).
48+
49+
## Using Cursor (optional)
50+
51+
If you use *Cursor*, [.cursor/rules/README.md](.cursor/rules/README.md) only points to *AGENTS.md*—same docs as everyone else.

‎pom.xml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@
9393
<converter-gson-version>3.0.0</converter-gson-version>
9494
<okhttp.version>5.3.2</okhttp.version>
9595
<jococo-plugin.version>0.8.13</jococo-plugin.version>
96-
<lombok-source.version>1.18.42</lombok-source.version>
96+
<lombok-source.version>1.18.44</lombok-source.version>
9797
<junit-jupiter.version>5.11.4</junit-jupiter.version>
9898
<junit-jupiter-engine.version>5.10.1</junit-jupiter-engine.version>
9999
<gson.version>2.13.2</gson.version>
@@ -148,7 +148,7 @@
148148
<dependency>
149149
<groupId>org.jetbrains</groupId>
150150
<artifactId>annotations</artifactId>
151-
<version>26.0.2</version>
151+
<version>26.1.0</version>
152152
<scope>provided</scope>
153153
</dependency>
154154
<dependency>
@@ -214,12 +214,12 @@
214214
<dependency>
215215
<groupId>org.jsoup</groupId>
216216
<artifactId>jsoup</artifactId>
217-
<version>1.21.2</version>
217+
<version>1.22.1</version>
218218
</dependency>
219219
<dependency>
220220
<groupId>org.jetbrains.kotlin</groupId>
221221
<artifactId>kotlin-stdlib</artifactId>
222-
<version>2.2.21</version>
222+
<version>2.3.20</version>
223223
</dependency>
224224
<dependency>
225225
<groupId>com.warrenstrange</groupId>
@@ -254,7 +254,7 @@
254254
</includes>
255255
<reportsDirectory>${project.build.directory}/surefire-reports</reportsDirectory>
256256
<!-- Skip during default lifecycle (e.g. publish); run tests locally with: mvn test -DskipTests=false -->
257-
<skipTests>true</skipTests>
257+
<!-- <skipTests>true</skipTests> -->
258258
<testFailureIgnore>true</testFailureIgnore>
259259
</configuration>
260260
</plugin>

‎skills/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Skills – Contentstack Management Java SDK
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) | Branching against `master`/`staging`, running Maven/CI commands, release or publish touchpoints. |
10+
| [contentstack-java-cma-sdk](contentstack-java-cma-sdk/SKILL.md) | Changing public API, `Contentstack` / `Stack` flows, auth tokens, or SDK surface exposed to integrators. |
11+
| [java](java/SKILL.md) | Package structure under `com.contentstack.cms`, Java 8 compatibility, Lombok, imports, and code style in this repo. |
12+
| [testing](testing/SKILL.md) | Adding or fixing tests, Surefire `skipTests` behavior, MockWebServer or live API tests, env/credentials. |
13+
| [code-review](code-review/SKILL.md) | Preparing or reviewing a PR: scope, tests, API compatibility, and security around tokens. |
14+
| [http-client-stack](http-client-stack/SKILL.md) | Retrofit services, OkHttp client/interceptors, retries, proxies, or HTTP logging. |
15+
16+
Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

‎skills/code-review/SKILL.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
name: code-review
3+
description: Use when reviewing or preparing a PR—API safety, tests, auth handling, and compatibility checklist.
4+
---
5+
6+
# Code review – Contentstack Management Java SDK
7+
8+
## When to use
9+
10+
- You are reviewing a pull request or self-reviewing before request.
11+
- You need a quick severity rubric (blocker / major / minor) aligned with this SDK.
12+
13+
## Instructions
14+
15+
### Blocker
16+
17+
- Real credentials, tokens, or stack keys committed in source or fixtures.
18+
- Breaking public API changes without version strategy or without team agreement.
19+
- New network behavior that bypasses existing interceptors, retry policy, or auth without explicit design.
20+
21+
### Major
22+
23+
- Missing or insufficient tests for new CMA behavior or error paths.
24+
- Behavior change for `Contentstack` / `Stack` builders or defaults without README or Javadoc updates where integrators would notice.
25+
- Regressions for Java 8 compatibility or new compiler warnings left unaddressed.
26+
27+
### Minor
28+
29+
- Style inconsistencies fixable in follow-up, or internal refactors with no API impact.
30+
- Javadoc typos or non-user-facing comment cleanup.
31+
32+
### PR checklist (short)
33+
34+
- [ ] `mvn clean test -DskipTests=false` passes locally.
35+
- [ ] Public changes documented (Javadoc / README / changelog per team process).
36+
- [ ] No secrets in repo; test config uses env or mocks.
37+
- [ ] HTTP changes reviewed against [http-client-stack/SKILL.md](../http-client-stack/SKILL.md).
38+
39+
## References
40+
41+
- [dev-workflow/SKILL.md](../dev-workflow/SKILL.md)
42+
- [contentstack-java-cma-sdk/SKILL.md](../contentstack-java-cma-sdk/SKILL.md)

‎skills/contentstack-java-cma-sdk/SKILL.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: contentstack-java-cma-sdk
3+
description: Use when changing the Management SDK surface—Contentstack entry, Stack, auth, or CMA integration boundaries.
4+
---
5+
6+
# Contentstack Java CMA SDK – Contentstack Management Java SDK
7+
8+
## When to use
9+
10+
- You add or change public methods on `Contentstack`, `Stack`, organization, user, or other API-facing types under `com.contentstack.cms`.
11+
- You need to document how integrators authenticate (authtoken, management token, OAuth, login).
12+
- You are deciding what belongs in this SDK vs the Delivery API or other Contentstack clients.
13+
14+
## Instructions
15+
16+
### Purpose and boundaries
17+
18+
- This library targets the [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/) (CMA). It is **not** the recommended way to deliver content to websites or apps at scale; the README directs readers to the [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) for that.
19+
- The main entry point is [`Contentstack`](../../src/main/java/com/contentstack/cms/Contentstack.java): builders set host, tokens, timeouts, proxy, OAuth, and retry behavior before obtaining `Stack`, `User`, `Organization`, etc.
20+
21+
### Public API and compatibility
22+
23+
- Treat additions to public classes as **semver-sensitive**: new optional builder methods are easier to ship than breaking signature changes.
24+
- Errors and responses should stay consistent with existing patterns (`retrofit2.Response`, model types under `com.contentstack.cms.models`, etc.).
25+
- Document behavior in Javadoc where integrators rely on contracts (auth order, token precedence, branch/early-access headers).
26+
27+
### Versioning
28+
29+
- Artifact coordinates: `com.contentstack.sdk:cms` — version in root [`pom.xml`](../../pom.xml). Follow org release process for bumping version and tagging.
30+
31+
## References
32+
33+
- [java/SKILL.md](../java/SKILL.md)
34+
- [http-client-stack/SKILL.md](../http-client-stack/SKILL.md)
35+
- [Content Management API – Authentication](https://www.contentstack.com/docs/developers/apis/content-management-api/#authentication) (official)

‎skills/dev-workflow/SKILL.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: dev-workflow
3+
description: Use when branching, building with Maven, CI, or release/publish workflows for this repo.
4+
---
5+
6+
# Dev workflow – Contentstack Management Java SDK
7+
8+
## When to use
9+
10+
- You need the canonical build/test commands or CI expectations.
11+
- You are opening a PR and need branch rules (`master` vs `staging`).
12+
- You are changing `pom.xml`, plugins, or publishing configuration.
13+
14+
## Instructions
15+
16+
### Repository and branches
17+
18+
- Default collaboration flow is documented in [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml): PRs targeting `master` from branches other than `staging` may be blocked; prefer the documented Contentstack branching policy for your team.
19+
20+
### Maven
21+
22+
- **Compile:** `mvn clean compile`
23+
- **Tests:** `mvn clean test -DskipTests=false` (Surefire is configured with `skipTests` true by default in [`pom.xml`](../../pom.xml); always pass `-DskipTests=false` for real test runs unless you intentionally skip.)
24+
- **Package:** `mvn clean package` — note tests may be skipped unless you add `-DskipTests=false`.
25+
- **Coverage report:** after tests with skip disabled, `mvn jacoco:report` and open `target/site/jacoco/index.html`.
26+
27+
### CI
28+
29+
- On push, [.github/workflows/coverage.yml](../../.github/workflows/coverage.yml) uses Java 11 on Ubuntu and runs Maven + JaCoCo. Align local verification with those steps when debugging CI-only failures.
30+
- Publishing and security scans live under [.github/workflows/](../../.github/workflows/); read the relevant workflow before changing release or scan behavior.
31+
32+
### PR expectations
33+
34+
- Run tests locally with `-DskipTests=false` before pushing.
35+
- Update [changelog.md](../../changelog.md) or version metadata when your team’s release process requires it.
36+
37+
## References
38+
39+
- [AGENTS.md](../../AGENTS.md)
40+
- [testing/SKILL.md](../testing/SKILL.md)
41+
- [code-review/SKILL.md](../code-review/SKILL.md)

‎skills/http-client-stack/SKILL.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
name: http-client-stack
3+
description: Use when changing Retrofit, OkHttp, interceptors, retries, proxies, or HTTP logging in this SDK.
4+
---
5+
6+
# HTTP client stack – Contentstack Management Java SDK
7+
8+
## When to use
9+
10+
- You modify [`Contentstack`](../../src/main/java/com/contentstack/cms/Contentstack.java) or related code that builds `Retrofit`, `OkHttpClient`, or interceptors.
11+
- You touch `AuthInterceptor`, OAuth interceptors, logging, connection pool, timeouts, or `RetryConfig` / retry utilities under `com.contentstack.cms.core`.
12+
13+
## Instructions
14+
15+
### Stack in this repo
16+
17+
- **Retrofit 3** + **Gson** converter for API interfaces and JSON binding.
18+
- **OkHttp 5** for transport; **logging-interceptor** for debug logging when enabled.
19+
- **RxJava 3** is a dependency for async patterns where used; keep consistency with existing call patterns.
20+
21+
### Auth and headers
22+
23+
- `AuthInterceptor` and OAuth-related types attach tokens and headers expected by CMA. Changes here affect every call—coordinate with tests in `core/` (e.g. `AuthInterceptorTest`).
24+
25+
### Retries and resilience
26+
27+
- Retry behavior is configurable via `RetryConfig` and related utilities (`core/Retry*.java`). Preserve backward-compatible defaults when adjusting retry conditions or backoff.
28+
29+
### Proxies and TLS
30+
31+
- `Contentstack` supports `Proxy` configuration; verify behavior if you change client building or connection pool settings.
32+
33+
### Testing
34+
35+
- Prefer **MockWebServer** for deterministic HTTP tests; see existing stack and core tests for patterns.
36+
37+
## References
38+
39+
- [contentstack-java-cma-sdk/SKILL.md](../contentstack-java-cma-sdk/SKILL.md)
40+
- [testing/SKILL.md](../testing/SKILL.md)
41+
- [Retrofit](https://square.github.io/retrofit/) (official)
42+
- [OkHttp](https://square.github.io/okhttp/) (official)

‎skills/java/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: java
3+
description: Use for Java package layout, Java 8 constraints, Lombok, and coding conventions in this repository.
4+
---
5+
6+
# Java – Contentstack Management Java SDK
7+
8+
## When to use
9+
10+
- You add new types under `com.contentstack.cms` or reorganize packages.
11+
- You need to stay compatible with Java 8 (`maven.compiler.source` / `target` = 1.8).
12+
- You use or configure Lombok and need to match existing patterns.
13+
14+
## Instructions
15+
16+
### Layout
17+
18+
- **Main code:** `src/main/java/com/contentstack/cms/` — core client in `Contentstack`, stack features under `stack/`, HTTP helpers in `core/`, OAuth under `oauth/`, models under `models/`.
19+
- **Tests:** mirror packages under `src/test/java/com/contentstack/cms/`; Surefire includes `**/Test*.java`, `**/*Test.java`, `**/*Tests.java`, and related patterns per [`pom.xml`](../../pom.xml).
20+
21+
### Language level
22+
23+
- Do not use language or library features that require a JVM newer than 8 for **source** compatibility unless the project explicitly upgrades (check `maven-compiler-plugin` and `<maven.compiler.source>` in [`pom.xml`](../../pom.xml)).
24+
25+
### Lombok and tooling
26+
27+
- Lombok is on the annotation processor path; prefer the same style as neighboring classes (`@Getter`, `@Builder`, etc.) instead of mixing hand-written boilerplate inconsistently.
28+
- JetBrains `@NotNull` / nullable annotations appear in places like [`Contentstack`](../../src/main/java/com/contentstack/cms/Contentstack.java); follow existing nullability hints for new APIs.
29+
30+
### Compiler
31+
32+
- The compiler enables broad `-Xlint` checks; fix new warnings rather than suppressing without cause.
33+
34+
## References
35+
36+
- [contentstack-java-cma-sdk/SKILL.md](../contentstack-java-cma-sdk/SKILL.md)
37+
- [testing/SKILL.md](../testing/SKILL.md)

‎skills/testing/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: testing
3+
description: Use when writing or running tests—Surefire skip flag, test naming, mocks, MockWebServer, and secrets policy.
4+
---
5+
6+
# Testing – Contentstack Management Java SDK
7+
8+
## When to use
9+
10+
- You add or change unit or integration tests under `src/test/java`.
11+
- Tests “do not run” locally or in CI — usually `skipTests`.
12+
- You need to mock HTTP or use OkHttp `MockWebServer` like existing tests.
13+
14+
## Instructions
15+
16+
### Running tests
17+
18+
- **Always** use `mvn test -DskipTests=false` (or `mvn clean test -DskipTests=false`) unless you are only compiling. The Surefire plugin in [`pom.xml`](../../pom.xml) sets `<skipTests>true</skipTests>` by default.
19+
20+
### Layout and naming
21+
22+
- Tests live under `src/test/java/com/contentstack/cms/` with class names matching Surefire includes (`*Test`, `*Tests`, `Test*`, suites like `UnitTestSuite`).
23+
- Reuse helpers such as [`TestClient`](../../src/test/java/com/contentstack/cms/TestClient.java), [`TestUtils`](../../src/test/java/com/contentstack/cms/core/TestUtils.java), or patterns in existing `*APITest` classes when appropriate.
24+
25+
### HTTP and API tests
26+
27+
- **MockWebServer** is available for stubbing HTTP; align with tests in `core/` and `stack/` packages.
28+
- Tests that hit real APIs may require environment variables or `.env` (see `java-dotenv` test dependency in [`pom.xml`](../../pom.xml)). **Never commit** real API keys, management tokens, or passwords; use CI secrets or local env only.
29+
30+
### Coverage
31+
32+
- JaCoCo attaches via `prepare-agent`; generate HTML with `mvn jacoco:report` after a test run with skips disabled.
33+
34+
## References
35+
36+
- [dev-workflow/SKILL.md](../dev-workflow/SKILL.md)
37+
- [http-client-stack/SKILL.md](../http-client-stack/SKILL.md)

0 commit comments

Comments
 (0)