From 47a51005e1e143fdd6007abd23b8056f2ea50682 Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Tue, 7 Apr 2026 12:41:32 +0530 Subject: [PATCH 1/2] Add agent guide and skills documentation --- .cursor/rules/README.md | 5 +++ AGENTS.md | 51 +++++++++++++++++++++++ skills/README.md | 16 +++++++ skills/code-review/SKILL.md | 42 +++++++++++++++++++ skills/contentstack-java-cma-sdk/SKILL.md | 35 ++++++++++++++++ skills/dev-workflow/SKILL.md | 41 ++++++++++++++++++ skills/http-client-stack/SKILL.md | 42 +++++++++++++++++++ skills/java/SKILL.md | 37 ++++++++++++++++ skills/testing/SKILL.md | 37 ++++++++++++++++ 9 files changed, 306 insertions(+) create mode 100644 .cursor/rules/README.md create mode 100644 AGENTS.md create mode 100644 skills/README.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/contentstack-java-cma-sdk/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/http-client-stack/SKILL.md create mode 100644 skills/java/SKILL.md create mode 100644 skills/testing/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..d8f3545 --- /dev/null +++ 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/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d4a23ae --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,51 @@ +# Contentstack Management Java SDK – 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-management-java](https://github.com/contentstack/contentstack-management-java) | +| *Purpose:* | Java client library for the Contentstack Content Management API (CMA): create, update, delete, and fetch account content and configuration from JVM applications. | +| *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. | + +## Tech stack (at a glance) + +| Area | Details | +| --- | --- | +| Language | Java 8 (source/target in `pom.xml`); README suggests Java 8+ for consumers. | +| Build | Apache Maven; `pom.xml` at repo root. | +| Tests | JUnit 5 / Vintage, Mockito, OkHttp MockWebServer; tests under `src/test/java/com/contentstack/cms/`. | +| 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`. | +| Other | HTTP: Retrofit 3, OkHttp 5, Gson; RxJava 3; Lombok for generated code. | + +## Commands (quick reference) + +| Command type | Command | +| --- | --- | +| Build | `mvn clean compile` | +| Test | `mvn clean test -DskipTests=false` | +| Lint | `mvn compile` (compiler warnings; see Tech stack) | +| Coverage | `mvn clean test -DskipTests=false jacoco:report` (open `target/site/jacoco/index.html`) | + +**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. + +**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. + +## Where the documentation lives: skills + +| Skill | Path | What it covers | +| --- | --- | --- | +| Dev workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, Maven lifecycle, CI expectations, PR flow. | +| 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. | +| Java (repo conventions) | [skills/java/SKILL.md](skills/java/SKILL.md) | Package layout, language conventions, Lombok usage. | +| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Test layout, naming, skipping policy, credentials. | +| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist and severity guidance. | +| HTTP client stack | [skills/http-client-stack/SKILL.md](skills/http-client-stack/SKILL.md) | Retrofit, OkHttp, retries, logging—what this repo actually wires. | + +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/skills/README.md b/skills/README.md new file mode 100644 index 0000000..5d34656 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,16 @@ +# Skills – Contentstack Management Java SDK + +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) | Branching against `master`/`staging`, running Maven/CI commands, release or publish touchpoints. | +| [contentstack-java-cma-sdk](contentstack-java-cma-sdk/SKILL.md) | Changing public API, `Contentstack` / `Stack` flows, auth tokens, or SDK surface exposed to integrators. | +| [java](java/SKILL.md) | Package structure under `com.contentstack.cms`, Java 8 compatibility, Lombok, imports, and code style in this repo. | +| [testing](testing/SKILL.md) | Adding or fixing tests, Surefire `skipTests` behavior, MockWebServer or live API tests, env/credentials. | +| [code-review](code-review/SKILL.md) | Preparing or reviewing a PR: scope, tests, API compatibility, and security around tokens. | +| [http-client-stack](http-client-stack/SKILL.md) | Retrofit services, OkHttp client/interceptors, retries, proxies, or HTTP logging. | + +Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`). diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..906a50f --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,42 @@ +--- +name: code-review +description: Use when reviewing or preparing a PR—API safety, tests, auth handling, and compatibility checklist. +--- + +# Code review – Contentstack Management Java SDK + +## When to use + +- You are reviewing a pull request or self-reviewing before request. +- You need a quick severity rubric (blocker / major / minor) aligned with this SDK. + +## Instructions + +### Blocker + +- Real credentials, tokens, or stack keys committed in source or fixtures. +- Breaking public API changes without version strategy or without team agreement. +- New network behavior that bypasses existing interceptors, retry policy, or auth without explicit design. + +### Major + +- Missing or insufficient tests for new CMA behavior or error paths. +- Behavior change for `Contentstack` / `Stack` builders or defaults without README or Javadoc updates where integrators would notice. +- Regressions for Java 8 compatibility or new compiler warnings left unaddressed. + +### Minor + +- Style inconsistencies fixable in follow-up, or internal refactors with no API impact. +- Javadoc typos or non-user-facing comment cleanup. + +### PR checklist (short) + +- [ ] `mvn clean test -DskipTests=false` passes locally. +- [ ] Public changes documented (Javadoc / README / changelog per team process). +- [ ] No secrets in repo; test config uses env or mocks. +- [ ] HTTP changes reviewed against [http-client-stack/SKILL.md](../http-client-stack/SKILL.md). + +## References + +- [dev-workflow/SKILL.md](../dev-workflow/SKILL.md) +- [contentstack-java-cma-sdk/SKILL.md](../contentstack-java-cma-sdk/SKILL.md) diff --git a/skills/contentstack-java-cma-sdk/SKILL.md b/skills/contentstack-java-cma-sdk/SKILL.md new file mode 100644 index 0000000..15501d4 --- /dev/null +++ b/skills/contentstack-java-cma-sdk/SKILL.md @@ -0,0 +1,35 @@ +--- +name: contentstack-java-cma-sdk +description: Use when changing the Management SDK surface—Contentstack entry, Stack, auth, or CMA integration boundaries. +--- + +# Contentstack Java CMA SDK – Contentstack Management Java SDK + +## When to use + +- You add or change public methods on `Contentstack`, `Stack`, organization, user, or other API-facing types under `com.contentstack.cms`. +- You need to document how integrators authenticate (authtoken, management token, OAuth, login). +- You are deciding what belongs in this SDK vs the Delivery API or other Contentstack clients. + +## Instructions + +### Purpose and boundaries + +- 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. +- 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. + +### Public API and compatibility + +- Treat additions to public classes as **semver-sensitive**: new optional builder methods are easier to ship than breaking signature changes. +- Errors and responses should stay consistent with existing patterns (`retrofit2.Response`, model types under `com.contentstack.cms.models`, etc.). +- Document behavior in Javadoc where integrators rely on contracts (auth order, token precedence, branch/early-access headers). + +### Versioning + +- Artifact coordinates: `com.contentstack.sdk:cms` — version in root [`pom.xml`](../../pom.xml). Follow org release process for bumping version and tagging. + +## References + +- [java/SKILL.md](../java/SKILL.md) +- [http-client-stack/SKILL.md](../http-client-stack/SKILL.md) +- [Content Management API – Authentication](https://www.contentstack.com/docs/developers/apis/content-management-api/#authentication) (official) diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..3bfe3cc --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,41 @@ +--- +name: dev-workflow +description: Use when branching, building with Maven, CI, or release/publish workflows for this repo. +--- + +# Dev workflow – Contentstack Management Java SDK + +## When to use + +- You need the canonical build/test commands or CI expectations. +- You are opening a PR and need branch rules (`master` vs `staging`). +- You are changing `pom.xml`, plugins, or publishing configuration. + +## Instructions + +### Repository and branches + +- 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. + +### Maven + +- **Compile:** `mvn clean compile` +- **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.) +- **Package:** `mvn clean package` — note tests may be skipped unless you add `-DskipTests=false`. +- **Coverage report:** after tests with skip disabled, `mvn jacoco:report` and open `target/site/jacoco/index.html`. + +### CI + +- 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. +- Publishing and security scans live under [.github/workflows/](../../.github/workflows/); read the relevant workflow before changing release or scan behavior. + +### PR expectations + +- Run tests locally with `-DskipTests=false` before pushing. +- Update [changelog.md](../../changelog.md) or version metadata when your team’s release process requires it. + +## References + +- [AGENTS.md](../../AGENTS.md) +- [testing/SKILL.md](../testing/SKILL.md) +- [code-review/SKILL.md](../code-review/SKILL.md) diff --git a/skills/http-client-stack/SKILL.md b/skills/http-client-stack/SKILL.md new file mode 100644 index 0000000..db8717b --- /dev/null +++ b/skills/http-client-stack/SKILL.md @@ -0,0 +1,42 @@ +--- +name: http-client-stack +description: Use when changing Retrofit, OkHttp, interceptors, retries, proxies, or HTTP logging in this SDK. +--- + +# HTTP client stack – Contentstack Management Java SDK + +## When to use + +- You modify [`Contentstack`](../../src/main/java/com/contentstack/cms/Contentstack.java) or related code that builds `Retrofit`, `OkHttpClient`, or interceptors. +- You touch `AuthInterceptor`, OAuth interceptors, logging, connection pool, timeouts, or `RetryConfig` / retry utilities under `com.contentstack.cms.core`. + +## Instructions + +### Stack in this repo + +- **Retrofit 3** + **Gson** converter for API interfaces and JSON binding. +- **OkHttp 5** for transport; **logging-interceptor** for debug logging when enabled. +- **RxJava 3** is a dependency for async patterns where used; keep consistency with existing call patterns. + +### Auth and headers + +- `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`). + +### Retries and resilience + +- Retry behavior is configurable via `RetryConfig` and related utilities (`core/Retry*.java`). Preserve backward-compatible defaults when adjusting retry conditions or backoff. + +### Proxies and TLS + +- `Contentstack` supports `Proxy` configuration; verify behavior if you change client building or connection pool settings. + +### Testing + +- Prefer **MockWebServer** for deterministic HTTP tests; see existing stack and core tests for patterns. + +## References + +- [contentstack-java-cma-sdk/SKILL.md](../contentstack-java-cma-sdk/SKILL.md) +- [testing/SKILL.md](../testing/SKILL.md) +- [Retrofit](https://square.github.io/retrofit/) (official) +- [OkHttp](https://square.github.io/okhttp/) (official) diff --git a/skills/java/SKILL.md b/skills/java/SKILL.md new file mode 100644 index 0000000..59dfab0 --- /dev/null +++ b/skills/java/SKILL.md @@ -0,0 +1,37 @@ +--- +name: java +description: Use for Java package layout, Java 8 constraints, Lombok, and coding conventions in this repository. +--- + +# Java – Contentstack Management Java SDK + +## When to use + +- You add new types under `com.contentstack.cms` or reorganize packages. +- You need to stay compatible with Java 8 (`maven.compiler.source` / `target` = 1.8). +- You use or configure Lombok and need to match existing patterns. + +## Instructions + +### Layout + +- **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/`. +- **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). + +### Language level + +- 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 `` in [`pom.xml`](../../pom.xml)). + +### Lombok and tooling + +- Lombok is on the annotation processor path; prefer the same style as neighboring classes (`@Getter`, `@Builder`, etc.) instead of mixing hand-written boilerplate inconsistently. +- JetBrains `@NotNull` / nullable annotations appear in places like [`Contentstack`](../../src/main/java/com/contentstack/cms/Contentstack.java); follow existing nullability hints for new APIs. + +### Compiler + +- The compiler enables broad `-Xlint` checks; fix new warnings rather than suppressing without cause. + +## References + +- [contentstack-java-cma-sdk/SKILL.md](../contentstack-java-cma-sdk/SKILL.md) +- [testing/SKILL.md](../testing/SKILL.md) diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..d345a1f --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,37 @@ +--- +name: testing +description: Use when writing or running tests—Surefire skip flag, test naming, mocks, MockWebServer, and secrets policy. +--- + +# Testing – Contentstack Management Java SDK + +## When to use + +- You add or change unit or integration tests under `src/test/java`. +- Tests “do not run” locally or in CI — usually `skipTests`. +- You need to mock HTTP or use OkHttp `MockWebServer` like existing tests. + +## Instructions + +### Running tests + +- **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 `true` by default. + +### Layout and naming + +- Tests live under `src/test/java/com/contentstack/cms/` with class names matching Surefire includes (`*Test`, `*Tests`, `Test*`, suites like `UnitTestSuite`). +- 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. + +### HTTP and API tests + +- **MockWebServer** is available for stubbing HTTP; align with tests in `core/` and `stack/` packages. +- 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. + +### Coverage + +- JaCoCo attaches via `prepare-agent`; generate HTML with `mvn jacoco:report` after a test run with skips disabled. + +## References + +- [dev-workflow/SKILL.md](../dev-workflow/SKILL.md) +- [http-client-stack/SKILL.md](../http-client-stack/SKILL.md) From a4cbc18e29ac058067394e88fa6617419672119a Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Tue, 7 Apr 2026 12:52:55 +0530 Subject: [PATCH 2/2] snyk fixes --- pom.xml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pom.xml b/pom.xml index 2feb459..c227e9b 100644 --- a/pom.xml +++ b/pom.xml @@ -93,7 +93,7 @@ 3.0.0 5.3.2 0.8.13 - 1.18.42 + 1.18.44 5.11.4 5.10.1 2.13.2 @@ -148,7 +148,7 @@ org.jetbrains annotations - 26.0.2 + 26.1.0 provided @@ -214,12 +214,12 @@ org.jsoup jsoup - 1.21.2 + 1.22.1 org.jetbrains.kotlin kotlin-stdlib - 2.2.21 + 2.3.20 com.warrenstrange @@ -254,7 +254,7 @@ ${project.build.directory}/surefire-reports - true + true