Skip to content

Commit 58ffeae

Browse files
cs-rajcs-raj
committed
update: added skill files
1 parent eea8699 commit 58ffeae

18 files changed

Lines changed: 776 additions & 0 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Cursor (optional)
2+
3+
**Cursor** users:
4+
5+
- Start at **[`AGENTS.md`](../../AGENTS.md)** — project entry point and commands.
6+
- Skills index and `references/` layout: **[`skills/README.md`](../../skills/README.md)**.
7+
8+
All conventions live in **`skills/*/SKILL.md`** and linked **`skills/*/references/*.md`**. This folder only points contributors to those paths so editor-specific config does not duplicate the canonical docs.

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,5 @@ api_referece/*
2828
*.html
2929
*.cobertura.xml
3030
integration-test-report_*.html
31+
*.zip
32+
.trx

‎AGENTS.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Contentstack Management .NET 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-management-dotnet](https://github.com/contentstack/contentstack-management-dotnet) |
10+
| **Purpose:** | .NET SDK for the [Content Management API (CMA)](https://www.contentstack.com/docs/developers/apis/content-management-api/)—manage stacks, content types, entries, assets, and related resources. |
11+
| **Out of scope (if any):** | Content **delivery** to end users should use the Content Delivery API and its SDKs, not this package. This repo does not implement the CDA. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
| ---- | ------- |
17+
| **Language** | C# 8.0, nullable reference types enabled (`LangVersion` in core project). |
18+
| **Build** | .NET SDK; main solution [`Contentstack.Management.Core.sln`](Contentstack.Management.Core.sln). Core library targets `netstandard2.0` (and `net471` / `net472` on Windows—see [`skills/framework/SKILL.md`](skills/framework/SKILL.md)). |
19+
| **Tests** | MSTest; test projects target `net7.0`. Unit tests: [`Contentstack.Management.Core.Unit.Tests/`](Contentstack.Management.Core.Unit.Tests/). Integration tests: [`Contentstack.Management.Core.Tests/`](Contentstack.Management.Core.Tests/) (includes `IntegrationTest/`). |
20+
| **Lint / coverage** | No repo-wide `dotnet format` / lint script at root. Rely on **.NET SDK analyzers** and IDE analysis. Tests use **coverlet** (`XPlat code coverage`) when run as in CI. |
21+
| **Other** | NuGet packages: `contentstack.management.csharp` (core), `contentstack.management.aspnetcore` (ASP.NET Core helpers). Assembly signing via `CSManagementSDK.snk`. |
22+
23+
## Commands (quick reference)
24+
25+
| Command type | Command |
26+
| ------------ | ------- |
27+
| **Build** | `dotnet build Contentstack.Management.Core.sln` |
28+
| **Test (CI-parity, unit)** | `sh ./Scripts/run-unit-test-case.sh` — runs `dotnet test` on [`Contentstack.Management.Core.Unit.Tests/Contentstack.Management.Core.Unit.Tests.csproj`](Contentstack.Management.Core.Unit.Tests/Contentstack.Management.Core.Unit.Tests.csproj) with TRX logger and coverlet. |
29+
| **Test (integration)** | `dotnet test Contentstack.Management.Core.Tests/Contentstack.Management.Core.Tests.csproj` — requires local `appsettings.json` with credentials (see [`skills/testing/SKILL.md`](skills/testing/SKILL.md)). |
30+
| **Pack (release)** | `dotnet pack -c Release -o out` (as in [`.github/workflows/nuget-publish.yml`](.github/workflows/nuget-publish.yml)). |
31+
32+
**CI:** [`.github/workflows/unit-test.yml`](.github/workflows/unit-test.yml) (unit tests on PR/push). **Branches:** PRs normally target **`development`**; **`main`** is for **hotfixes**. PRs **into `main`** must come from **`staging`** per [`.github/workflows/check-branch.yml`](.github/workflows/check-branch.yml).
33+
34+
## Where the documentation lives: skills
35+
36+
| Skill | Path | What it covers |
37+
| ----- | ---- | -------------- |
38+
| Dev workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, scripts, when to run which tests. |
39+
| SDK (CMA) | [`skills/contentstack-management-dotnet-sdk/SKILL.md`](skills/contentstack-management-dotnet-sdk/SKILL.md) | Public API, auth, package boundaries. |
40+
| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | MSTest layout, unit vs integration, credentials, coverage. |
41+
| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR expectations and checklist. |
42+
| Framework / platform | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | TFMs, signing, NuGet, HTTP pipeline overview. |
43+
| C# style | [`skills/csharp-style/SKILL.md`](skills/csharp-style/SKILL.md) | Language and layout conventions for this repo. |
44+
| HTTP pipeline (retries) | [`skills/http-pipeline/SKILL.md`](skills/http-pipeline/SKILL.md) | Handlers, retry policy, pipeline behavior. |
45+
| ASP.NET Core integration | [`skills/aspnetcore-integration/SKILL.md`](skills/aspnetcore-integration/SKILL.md) | `contentstack.management.aspnetcore` package and DI. |
46+
| Documentation (DocFX) | [`skills/documentation/SKILL.md`](skills/documentation/SKILL.md) | API docs under `docfx_project/`. |
47+
48+
An index with **when to use** hints is in [`skills/README.md`](skills/README.md).
49+
50+
## Using Cursor (optional)
51+
52+
If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) points to **`AGENTS.md`** and **`skills/`**—same docs as everyone else; no duplicated prose in `.cursor`.

‎skills/README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Skills – Contentstack Management .NET 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+
## Project context
6+
7+
| Area | This repo (CMA SDK) |
8+
| ---- | ------------------- |
9+
| **API** | [Content Management API (CMA)](https://www.contentstack.com/docs/developers/apis/content-management-api/) — not the Content Delivery API (CDA). |
10+
| **Packages** | `contentstack.management.csharp` (core), `contentstack.management.aspnetcore` (DI helpers). |
11+
| **HTTP** | `HttpClient` through [`ContentstackClient`](../Contentstack.Management.Core/ContentstackClient.cs) → runtime pipeline (`HttpHandler`, `RetryHandler`). |
12+
| **Language / tests** | C# 8, nullable enabled. **MSTest** on **net7.0**; unit tests use **Moq** and **AutoFixture** where existing tests do. |
13+
14+
## How to use these skills
15+
16+
- **In the repo:** open `skills/<folder>/SKILL.md` for the topic you need. Longer templates and checklists live under `skills/<folder>/references/*.md` where linked.
17+
- **In Cursor / other AI chats:** reference a skill by path, e.g. `skills/http-pipeline/SKILL.md` or `@skills/http-pipeline` if your tooling resolves that alias to this folder.
18+
19+
## Example prompts
20+
21+
- “Add a new CMA endpoint wrapper following `skills/contentstack-management-dotnet-sdk/SKILL.md` and `references/cma-architecture.md`.”
22+
- “Adjust retry behavior for 429 responses using `skills/http-pipeline/` and update unit tests under `Contentstack.Management.Core.Unit.Tests/Runtime/Pipeline/`.”
23+
- “Write a unit test with MSTest + Moq following `skills/testing/references/mstest-patterns.md`.”
24+
25+
## When to use which skill
26+
27+
| Skill folder | Use when |
28+
| ------------ | -------- |
29+
| [`dev-workflow/`](dev-workflow/) | Git branches, CI workflows, running build/test scripts, release/NuGet flow. |
30+
| [`contentstack-management-dotnet-sdk/`](contentstack-management-dotnet-sdk/) | `ContentstackClient`, options, authentication, public API and package boundaries. |
31+
| [`testing/`](testing/) | Writing or running unit/integration tests, MSTest, coverlet, local credentials. |
32+
| [`code-review/`](code-review/) | Preparing or reviewing a PR against this repository. |
33+
| [`framework/`](framework/) | Target frameworks, signing, NuGet packaging, OS-specific builds, high-level HTTP/runtime stack. |
34+
| [`csharp-style/`](csharp-style/) | C# language version, nullable usage, naming and folder layout consistent with the repo. |
35+
| [`http-pipeline/`](http-pipeline/) | Changing `HttpHandler`, `RetryHandler`, retry policy, or pipeline ordering. |
36+
| [`aspnetcore-integration/`](aspnetcore-integration/) | `Contentstack.Management.ASPNETCore` package, `IHttpClientFactory`, DI registration. |
37+
| [`documentation/`](documentation/) | Building or updating DocFX API documentation under `docfx_project/`. |
38+
39+
Each folder contains **`SKILL.md`** with YAML frontmatter (`name`, `description`). **Deep dives:** see the **Quick reference** line at the top of each `SKILL.md` for links to `references/`.

‎skills/aspnetcore-integration/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: aspnetcore-integration
3+
description: Use for the contentstack.management.aspnetcore package, HttpClient/DI registration with ASP.NET Core.
4+
---
5+
6+
# ASP.NET Core integration – Contentstack Management .NET SDK
7+
8+
## When to use
9+
10+
- Changing [`Contentstack.Management.ASPNETCore/`](../../Contentstack.Management.ASPNETCore/) or the NuGet package **`contentstack.management.aspnetcore`**.
11+
- Registering `ContentstackClient` with `IHttpClientFactory` / `IServiceCollection`.
12+
13+
## Instructions
14+
15+
### Package
16+
17+
- **Package ID:** `contentstack.management.aspnetcore`
18+
- **Target:** `netstandard2.1`
19+
- **Project:** [`contentstack.management.aspnetcore.csproj`](../../Contentstack.Management.ASPNETCore/contentstack.management.aspnetcore.csproj)
20+
21+
### Registration APIs
22+
23+
- [`ServiceCollectionExtensions`](../../Contentstack.Management.ASPNETCore/ServiceCollectionExtensions.cs) in namespace `Microsoft.Extensions.DependencyInjection`:
24+
- `AddContentstackClient(IServiceCollection, ContentstackClientOptions)` / `TryAddContentstackClient` — extend here when wiring options-based registration; keep behavior aligned with DI conventions.
25+
- `AddContentstackClient(IServiceCollection, Action<HttpClient>)` — registers `ContentstackClient` with **`AddHttpClient<ContentstackClient>`** for typed client configuration.
26+
27+
When extending DI support, align with Microsoft.Extensions.DependencyInjection and `Microsoft.Extensions.Http` patterns already referenced in the project file.
28+
29+
### Core dependency
30+
31+
- The ASP.NET Core project references the core management package; public types come from [`Contentstack.Management.Core`](../../Contentstack.Management.Core/).
32+
33+
## References
34+
35+
- [`../contentstack-management-dotnet-sdk/SKILL.md`](../contentstack-management-dotnet-sdk/SKILL.md) — core client and options.
36+
- [`../framework/SKILL.md`](../framework/SKILL.md) — NuGet and TFMs.

‎skills/code-review/SKILL.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: code-review
3+
description: Use when reviewing or preparing a pull request for contentstack-management-dotnet.
4+
---
5+
6+
# Code review – Contentstack Management .NET SDK
7+
8+
**Deep dive:** [`references/checklist.md`](references/checklist.md) (copy-paste PR checklist sections).
9+
10+
## When to use
11+
12+
- Before requesting review or merging a PR.
13+
- When auditing changes for API safety, tests, and repo policies.
14+
15+
## Instructions
16+
17+
### Branch and merge expectations
18+
19+
- **Typical PRs** should target **`development`**. Use **`main`** as the base branch only for **hotfixes**.
20+
- **When the base is `main`:** only PRs from **`staging`** are allowed (enforced by [`.github/workflows/check-branch.yml`](../../.github/workflows/check-branch.yml)). Confirm head/base match team intent before approving.
21+
22+
### Summary checklist
23+
24+
- **Purpose:** Change matches the ticket/PR description; no unrelated refactors.
25+
- **Tests:** Unit tests updated or added for behavior changes; run `sh ./Scripts/run-unit-test-case.sh` locally for core changes. Integration tests only when behavior depends on live API—coordinate credentials.
26+
- **API compatibility:** Public surface (`ContentstackClient`, options, models) changes are intentional and versioned appropriately; avoid breaking changes without major bump and changelog.
27+
- **Security:** No secrets, tokens, or keys in source or commits; `appsettings.json` with real data must not be committed.
28+
- **Signing:** If assembly signing is affected, confirm `CSManagementSDK.snk` usage matches [`../framework/SKILL.md`](../framework/SKILL.md).
29+
- **Style:** Follow [`../csharp-style/SKILL.md`](../csharp-style/SKILL.md); match surrounding code.
30+
- **Documentation:** User-visible behavior changes reflected in `README.md` or package release notes when needed.
31+
32+
For markdown blocks to paste into PRs, use [`references/checklist.md`](references/checklist.md).
33+
34+
### Severity (optional labels)
35+
36+
- **Blocker:** Build or CI broken; security issue; violates branch policy.
37+
- **Major:** Missing tests for risky logic; breaking API without process.
38+
- **Minor:** Naming nits, non-user-facing cleanup.
39+
40+
## References
41+
42+
- [`references/checklist.md`](references/checklist.md) — detailed PR checklist.
43+
- [`../dev-workflow/SKILL.md`](../dev-workflow/SKILL.md) — CI and branches.
44+
- [`../contentstack-management-dotnet-sdk/SKILL.md`](../contentstack-management-dotnet-sdk/SKILL.md) — API boundaries.

‎skills/code-review/references/checklist.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# PR review checklist (CMA Management SDK)
2+
3+
Copy sections into a PR comment when useful. This checklist is for **this** repo (`HttpClient` + pipeline + MSTest), **not** the Content Delivery .NET SDK.
4+
5+
## Branch policy
6+
7+
```markdown
8+
- [ ] **Default:** PR targets **`development`** unless this is a documented **hotfix** to **`main`**
9+
- [ ] If base is **`main`**: head branch is **`staging`** (see `.github/workflows/check-branch.yml`)
10+
```
11+
12+
## Breaking changes
13+
14+
```markdown
15+
- [ ] No public method/property removed or narrowed without deprecation / major version plan
16+
- [ ] `JsonProperty` / JSON names for API-facing models unchanged unless intentional and documented
17+
- [ ] New required `ContentstackClientOptions` fields have safe defaults or are optional
18+
- [ ] Strong naming: assembly signing still consistent if keys or `csproj` changed
19+
```
20+
21+
## HTTP and pipeline
22+
23+
```markdown
24+
- [ ] New or changed HTTP calls go through existing client/pipeline (`ContentstackClient` → `IContentstackService` → pipeline), not ad-hoc `HttpClient` usage inside services without justification
25+
- [ ] Retry-sensitive changes reviewed alongside `RetryHandler` / `DefaultRetryPolicy` and unit tests under `Contentstack.Management.Core.Unit.Tests/Runtime/Pipeline/`
26+
- [ ] Headers, query params, and path segments align with CMA docs; no hardcoded production URLs where options.Host should be used
27+
```
28+
29+
## Services and query API
30+
31+
```markdown
32+
- [ ] `IContentstackService` implementations set `ResourcePath`, `HttpMethod`, `Parameters` / `QueryResources` / `PathResources` / `Content` consistently with sibling services
33+
- [ ] New fluent `Query` methods only add to `ParameterCollection` with correct API parameter names
34+
```
35+
36+
## Tests
37+
38+
```markdown
39+
- [ ] Unit tests use MSTest; `sh ./Scripts/run-unit-test-case.sh` passes for core changes
40+
- [ ] Integration tests only when needed; no secrets committed (`appsettings.json` stays local)
41+
```
42+
43+
## Security and hygiene
44+
45+
```markdown
46+
- [ ] No API keys, tokens, or passwords in source or test data checked into git
47+
- [ ] OAuth / token handling does not log secrets
48+
```
49+
50+
## Documentation
51+
52+
```markdown
53+
- [ ] User-visible behavior reflected in `README.md` or release notes when appropriate
54+
- [ ] `skills/` or `references/` updated if agent/contributor workflow changed
55+
```

‎skills/contentstack-management-dotnet-sdk/SKILL.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
name: contentstack-management-dotnet-sdk
3+
description: Use when changing or using the CMA client API, authentication, or NuGet package surface for Contentstack.Management.Core.
4+
---
5+
6+
# Contentstack Management .NET SDK (CMA)
7+
8+
**Deep dive:** [`references/cma-architecture.md`](references/cma-architecture.md) (request flow, `IContentstackService`), [`references/query-and-parameters.md`](references/query-and-parameters.md) (fluent `Query`, `ParameterCollection`).
9+
10+
## When to use
11+
12+
- Adding or changing `ContentstackClient` behavior, options, or service entry points.
13+
- Documenting how consumers authenticate (management token, authtoken, login).
14+
- Reviewing breaking vs compatible changes for the NuGet package `contentstack.management.csharp`.
15+
16+
## Instructions
17+
18+
### Packages and entry points
19+
20+
| Package ID | Project | Role |
21+
| ---------- | ------- | ---- |
22+
| `contentstack.management.csharp` | [`Contentstack.Management.Core/`](../../Contentstack.Management.Core/) | Main SDK; `ContentstackClient`, models, services. |
23+
| `contentstack.management.aspnetcore` | [`Contentstack.Management.ASPNETCore/`](../../Contentstack.Management.ASPNETCore/) | ASP.NET Core registration helpers; see [`../aspnetcore-integration/SKILL.md`](../aspnetcore-integration/SKILL.md). |
24+
25+
- Primary type: [`ContentstackClient`](../../Contentstack.Management.Core/ContentstackClient.cs) (`IContentstackClient`).
26+
- Configuration: [`ContentstackClientOptions`](../../Contentstack.Management.Core/ContentstackClientOptions.cs) (and related options types).
27+
28+
### Authentication (high level)
29+
30+
- **Management token:** stack-scoped token; typical pattern `client.Stack(apiKey, managementToken)` per product docs.
31+
- **Authtoken:** user/session token on the client options.
32+
- **Login with credentials:** `ContentstackClient.Login` / `LoginAsync` with `NetworkCredential` (see root [`README.md`](../../README.md) examples).
33+
34+
OAuth-related code lives under [`Services/OAuth/`](../../Contentstack.Management.Core/Services/OAuth/), [`OAuthHandler.cs`](../../Contentstack.Management.Core/OAuthHandler.cs), and [`Utils/PkceHelper.cs`](../../Contentstack.Management.Core/Utils/PkceHelper.cs). Prefer small, testable changes; preserve existing public contracts unless doing a major version bump.
35+
36+
### Serialization and models
37+
38+
- JSON serialization and converters are configured in `ContentstackClient` (e.g. custom `JsonConverter` types for fields and nodes).
39+
- Domain models live under [`Models/`](../../Contentstack.Management.Core/Models/). Follow existing patterns when adding types.
40+
41+
### Errors
42+
43+
- Exceptions and error mapping: [`Exceptions/`](../../Contentstack.Management.Core/Exceptions/). Keep messages and HTTP status handling consistent with existing patterns.
44+
45+
### Integration boundaries
46+
47+
- The SDK talks to Contentstack **Management** HTTP APIs. Do not confuse with Delivery API clients.
48+
- HTTP behavior (retries, handlers) is documented under [`../framework/SKILL.md`](../framework/SKILL.md) and [`../http-pipeline/SKILL.md`](../http-pipeline/SKILL.md).
49+
50+
## References
51+
52+
- [`references/cma-architecture.md`](references/cma-architecture.md) — architecture and invocation flow.
53+
- [`references/query-and-parameters.md`](references/query-and-parameters.md) — fluent query API.
54+
- [`../framework/SKILL.md`](../framework/SKILL.md) — TFMs, NuGet, pipeline overview.
55+
- [`../http-pipeline/SKILL.md`](../http-pipeline/SKILL.md) — retries and handlers.
56+
- [`../csharp-style/SKILL.md`](../csharp-style/SKILL.md) — C# conventions.
57+
- [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/) (official docs).

0 commit comments

Comments
 (0)