Skip to content

Commit 5275504

Browse files
reeshika-hreeshika-h
authored
Merge pull request #51 from contentstack/DX-5384-cursor
Add agent guide and skills documentation
2 parents f04e0d8 + 9b7fecd commit 5275504

File tree

11 files changed

+314
-6
lines changed

11 files changed

+314
-6
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: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Contentstack Marketplace 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/contentstack-marketplace-java](https://github.com/contentstack/contentstack-marketplace-java) |
10+
| *Purpose:* | Java SDK for the Contentstack Marketplace API: apps, authorizations, installations, and related resources (Retrofit-based HTTP client). |
11+
| *Out of scope (if any):* | Not a general Contentstack Delivery or Management SDK; Marketplace API only. No Kotlin-first API surface (Kotlin stdlib is a transitive dependency). |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
| --- | --- |
17+
| Language | Java 8 (compiler `source`/`target` in `pom.xml`; CI uses JDK 11). Lombok for generated code. |
18+
| Build | Maven — `pom.xml`; artifact `com.contentstack.sdk:marketplace`. |
19+
| Tests | JUnit 5 (and Vintage for legacy tests) — `src/test/java/**`. |
20+
| Lint / coverage | Compiler warnings (`-Xlint` in `maven-compiler-plugin`); JaCoCo (`target/site/jacoco/index.html` after tests). Optional JetBrains Qodana JVM — `qodana.yaml`. |
21+
| Other | HTTP: Retrofit 2, OkHttp, Gson. `README.md` for end-user install and usage. |
22+
23+
## Commands (quick reference)
24+
25+
| Command Type | Command |
26+
| --- | --- |
27+
| Build | `mvn -B package --file pom.xml` |
28+
| Test | `mvn test` |
29+
| Lint | No separate CLI lint target; use compiler warnings during `mvn compile` / `mvn package`, JaCoCo report after `mvn test`, or Qodana locally/CI per `qodana.yaml`. |
30+
31+
CI: GitHub Actions — `.github/workflows/maven.yml` (`mvn -B package --file pom.xml` on push/PR to `main`).
32+
33+
## Where the documentation lives: skills
34+
35+
| Skill | Path | What it covers |
36+
| --- | --- | --- |
37+
| Dev workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, CI, build/test, release notes |
38+
| Marketplace SDK API | [skills/contentstack-marketplace-sdk/SKILL.md](skills/contentstack-marketplace-sdk/SKILL.md) | Public API, `Marketplace` builder, domains (apps, auths, installations) |
39+
| Java layout & conventions | [skills/java/SKILL.md](skills/java/SKILL.md) | Package layout, Java/Lombok usage in this repo |
40+
| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Test layout, `TestClient`, env / credentials |
41+
| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist for this SDK |
42+
| Framework & HTTP | [skills/framework-and-http/SKILL.md](skills/framework-and-http/SKILL.md) | Retrofit `Client`, Gson, base URLs, extension points |
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.

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2012 - 2025 Contentstack
3+
Copyright (c) 2012 - 2026 Contentstack
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎pom.xml‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,10 @@
2020
<maven-javadoc-plugin.version>3.4.1</maven-javadoc-plugin.version>
2121
<dotenv-source.version>5.2.2</dotenv-source.version>
2222
<rxjava-source.version>3.1.6</rxjava-source.version>
23-
<retrofit-source.version>2.10.0</retrofit-source.version>
24-
<converter-gson-version>2.10.0</converter-gson-version>
25-
<okhttp.version>4.12.0</okhttp.version>
26-
<okio.version>3.4.0</okio.version>
23+
<retrofit-source.version>3.0.0</retrofit-source.version>
24+
<converter-gson-version>3.0.0</converter-gson-version>
25+
<okhttp.version>5.1.0</okhttp.version>
26+
<okio.version>3.9.1</okio.version>
2727
<logging.version>4.10.0</logging.version>
2828
<jococo-plugin.version>0.8.7</jococo-plugin.version>
2929
<lombok-source.version>1.18.36</lombok-source.version>
@@ -125,6 +125,12 @@
125125
<artifactId>okhttp</artifactId>
126126
<version>${okhttp.version}</version>
127127
</dependency>
128+
<!-- OkHttp 5+: the okhttp artifact is a stub on Maven; JVM classes ship in okhttp-jvm -->
129+
<dependency>
130+
<groupId>com.squareup.okhttp3</groupId>
131+
<artifactId>okhttp-jvm</artifactId>
132+
<version>${okhttp.version}</version>
133+
</dependency>
128134
<dependency>
129135
<groupId>com.squareup.okio</groupId>
130136
<artifactId>okio</artifactId>
@@ -169,7 +175,7 @@
169175
<dependency>
170176
<groupId>org.jetbrains.kotlin</groupId>
171177
<artifactId>kotlin-stdlib</artifactId>
172-
<version>2.1.0</version>
178+
<version>2.2.0</version>
173179
</dependency>
174180
</dependencies>
175181

@@ -225,6 +231,7 @@
225231
<plugin>
226232
<groupId>org.apache.maven.plugins</groupId>
227233
<artifactId>maven-javadoc-plugin</artifactId>
234+
<version>${maven-javadoc-plugin.version}</version>
228235
<configuration>
229236
<source>8</source>
230237
</configuration>

‎skills/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Skills – Contentstack Marketplace 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/) | Branching, CI, local build/test commands, releases |
10+
| [contentstack-marketplace-sdk](contentstack-marketplace-sdk/) | `Marketplace` API surface, apps/auths/installations, versioning |
11+
| [java](java/) | Package structure, Java 8/Lombok patterns in this codebase |
12+
| [testing](testing/) | Writing or running tests, fixtures, `.env` / secrets |
13+
| [code-review](code-review/) | Reviewing or preparing PRs for this repository |
14+
| [framework-and-http](framework-and-http/) | Retrofit, OkHttp, Gson, `Client` and HTTP boundaries |
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 pull requests or preparing changes for review in this SDK repository.
4+
---
5+
6+
# Code review – Contentstack Marketplace Java SDK
7+
8+
## When to use
9+
10+
- Reviewing a PR for correctness, API safety, and consistency
11+
- Self-review before requesting reviewers
12+
13+
## Instructions
14+
15+
### Blocker
16+
17+
- Breaking changes to public **`Marketplace`** or domain types without version/changelog strategy and maintainer agreement.
18+
- Committed secrets, real org tokens, or `.env` files with live credentials.
19+
- New HTTP clients that bypass **`com.contentstack.sdk.Client`** without rationale (duplicated base URLs, converters).
20+
21+
### Major
22+
23+
- Missing or misleading Javadoc on new public methods/classes.
24+
- Tests absent for non-trivial new behavior (happy path at minimum).
25+
- Null/empty handling inconsistent with existing `Builder` and service patterns.
26+
- Compiler warnings introduced without justification.
27+
28+
### Minor
29+
30+
- Naming or package placement inconsistent with `com.contentstack.sdk.marketplace` structure.
31+
- Typos in user-facing Javadoc or `README.md` when behavior changes.
32+
33+
### Quick checklist
34+
35+
- [ ] `mvn -B package` succeeds locally.
36+
- [ ] Public API changes reflected in `README.md` or Javadoc where users look first.
37+
- [ ] Tests updated; integration tests respect env-based credentials ([../testing/SKILL.md](../testing/SKILL.md)).
38+
39+
## References
40+
41+
- [../contentstack-marketplace-sdk/SKILL.md](../contentstack-marketplace-sdk/SKILL.md)
42+
- [../testing/SKILL.md](../testing/SKILL.md)

‎skills/contentstack-marketplace-sdk/SKILL.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
name: contentstack-marketplace-sdk
3+
description: Use when changing or documenting the public Marketplace SDK API, entry points, or domain modules.
4+
---
5+
6+
# Marketplace SDK API – Contentstack Marketplace Java SDK
7+
8+
## When to use
9+
10+
- Adding or changing `com.contentstack.sdk.marketplace.*` public types
11+
- Documenting how consumers construct `Marketplace` and access apps, auths, installations, requests
12+
- Deciding what belongs in this library vs. other Contentstack Java SDKs
13+
14+
## Instructions
15+
16+
### Entry point
17+
18+
- **`com.contentstack.sdk.marketplace.Marketplace`** — constructed via **`Marketplace.Builder`**, which requires a non-null, non-empty organization UID (`Constants.ERROR_NO_ORGANIZATION_UID` on violation).
19+
- Optional builder knobs: `host`, `region` (`com.contentstack.sdk.Region`), `authtoken`, and login-related methods where implemented.
20+
- Host resolution: if `region` is set, the client prefixes the region to the host segment (see `Marketplace` constructor); empty host falls back to `Constants.DEFAULT_HOST`.
21+
22+
### Domain surfaces (high level)
23+
24+
- **`App`** / `AppService` — marketplace apps (including hosting, OAuth subpackages).
25+
- **`Auth`** — authorizations.
26+
- **`Installation`** — installations (including `location`, `webhook` subpackages).
27+
- **`AppRequest`** — app request flows via `RequestService`.
28+
29+
### Integration boundaries
30+
31+
- Shared HTTP/Retrofit wiring lives in **`com.contentstack.sdk.Client`**; do not duplicate base URL or converter setup on each feature without a design reason.
32+
- JSON: Gson via Retrofit; `org.json.simple` appears where legacy JSON types are needed — keep new code consistent with existing patterns in the same module.
33+
34+
### Versioning
35+
36+
- Library version is the Maven **`artifactId` `marketplace`** version in `pom.xml`; align changelog and consumer docs (`README.md`) when bumping.
37+
38+
## References
39+
40+
- [../framework-and-http/SKILL.md](../framework-and-http/SKILL.md) — Retrofit client and HTTP stack
41+
- [../java/SKILL.md](../java/SKILL.md) — packages and Lombok
42+
- End-user overview: repository root `README.md`

‎skills/dev-workflow/SKILL.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
name: dev-workflow
3+
description: Use when branching, running CI locally, building, testing, or releasing this Maven project.
4+
---
5+
6+
# Dev workflow – Contentstack Marketplace Java SDK
7+
8+
## When to use
9+
10+
- Setting up the repo locally or onboarding
11+
- Matching what CI runs before opening a PR
12+
- Cutting releases or understanding deploy steps in `pom.xml`
13+
14+
## Instructions
15+
16+
### Repository and default branch
17+
18+
- Remote: `https://github.com/contentstack/contentstack-marketplace-java` (see `pom.xml` `<scm>`).
19+
- CI in `.github/workflows/maven.yml` runs on pushes and pull requests targeting `main`: checkout, JDK 11 (Temurin), `mvn -B package --file pom.xml`.
20+
21+
### Local commands
22+
23+
- Full package (compile, test, package): `mvn -B package --file pom.xml` — aligns with CI.
24+
- Tests only: `mvn test`.
25+
- Coverage HTML after tests: `target/site/jacoco/index.html` (JaCoCo is bound to the `test` phase).
26+
27+
### Maven release / publishing
28+
29+
- `pom.xml` documents release flow (e.g. `mvn clean deploy`, Central Publishing plugin, GPG signing in `verify`). Coordinate with maintainers before changing version or release profiles.
30+
31+
### PR expectations
32+
33+
- Ensure `mvn -B package` passes; note that Surefire may be configured with `testFailureIgnore` — still fix failing tests before merging when possible.
34+
35+
## References
36+
37+
- [../testing/SKILL.md](../testing/SKILL.md) — test env and credentials
38+
- [../java/SKILL.md](../java/SKILL.md) — compiler and layout
39+
- Official: [Maven](https://maven.apache.org/guides/), [GitHub Actions Java + Maven](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-maven)

‎skills/framework-and-http/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: framework-and-http
3+
description: Use when changing Retrofit/OkHttp setup, Gson serialization, or HTTP behavior for the Marketplace client.
4+
---
5+
6+
# Framework and HTTP – Contentstack Marketplace Java SDK
7+
8+
## When to use
9+
10+
- Editing **`com.contentstack.sdk.Client`** or how `Marketplace` obtains **`Retrofit`**
11+
- Adding interceptors, converters, or base URL behavior
12+
- Debugging API calls built with **Retrofit** + **Gson**
13+
14+
## Instructions
15+
16+
### Retrofit singleton
17+
18+
- **`Client.getInstance(String host)`** lazily creates one **`Retrofit`** per JVM: the **first** `host` wins; later calls pass the parameter but do not recreate the client. Multiple `Marketplace` instances with different hosts in one process can mis-route requests unless this is addressed in `Client`.
19+
20+
### Base URL and transport
21+
22+
- **`createRetrofitInstance`** builds **`https://{host}/`** and attaches **`GsonConverterFactory.create()`** — new endpoints should use Retrofit interfaces consistent with existing `*Service` classes under `marketplace`.
23+
- **OkHttp** is a direct dependency (version in `pom.xml`) — configure timeouts, interceptors, or auth headers in one place when extending the stack.
24+
25+
### JSON
26+
27+
- Gson is the Retrofit converter; **`org.json.simple`** is used where historical code requires it — follow the dominant pattern in the package you touch.
28+
29+
### Errors and responses
30+
31+
- Services typically use **`retrofit2.Call`** / **`Response`** — preserve existing error-handling conventions when adding calls (see `Marketplace` and service classes for patterns).
32+
33+
## References
34+
35+
- [../contentstack-marketplace-sdk/SKILL.md](../contentstack-marketplace-sdk/SKILL.md) — domain entry points
36+
- [Retrofit](https://square.github.io/retrofit/), [OkHttp](https://square.github.io/okhttp/)

‎skills/java/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: java
3+
description: Use when navigating Java package layout, compiler settings, or Lombok usage in this repository.
4+
---
5+
6+
# Java layout and conventions – Contentstack Marketplace Java SDK
7+
8+
## When to use
9+
10+
- Adding new classes under `src/main/java`
11+
- Aligning with Java 8 language level and Maven compiler settings
12+
- Using Lombok consistently with existing types
13+
14+
## Instructions
15+
16+
### Layout
17+
18+
- Root packages: **`com.contentstack.sdk`** (`Region`, `Client`, `BaseImplementation`) and **`com.contentstack.sdk.marketplace`** (Marketplace API and subpackages: `apps`, `auths`, `installations`, `login`, `request`).
19+
- Tests mirror main packages under `src/test/java/com/contentstack/sdk/...`.
20+
- `package-info.java` exists in several packages for Javadoc cohesion — add or update when expanding a package’s public story.
21+
22+
### Compiler and language level
23+
24+
- **`maven-compiler-plugin`** sets `source`/`target` **8** with Lombok on the annotation processor path; `-Xlint` style args are configured — fix new warnings when practical.
25+
- `pom.xml` also declares `maven.compiler.source/target` properties (9) while the plugin overrides to 8 — treat **the plugin’s Java 8** as authoritative for emitted bytecode unless maintainers unify properties.
26+
27+
### Lombok and dependencies
28+
29+
- **Lombok** is `provided` — use for DTOs/services only where the rest of the module already does; avoid mixing styles in one feature area.
30+
- **JetBrains annotations** (`@NotNull`, etc.) appear on public APIs — keep null contracts explicit for new parameters.
31+
32+
## References
33+
34+
- [../contentstack-marketplace-sdk/SKILL.md](../contentstack-marketplace-sdk/SKILL.md) — public API map
35+
- [../testing/SKILL.md](../testing/SKILL.md) — test code layout
36+
- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — `mvn` commands

0 commit comments

Comments
 (0)