From 1bfc1aa92663c618272842b3182293866481aa3e Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Wed, 8 Apr 2026 12:06:13 +0530 Subject: [PATCH 1/3] Added skill and agent files --- .cursor/rules/README.md | 7 ++++ AGENTS.md | 50 +++++++++++++++++++++++++++ skills/README.md | 16 +++++++++ skills/code-review/SKILL.md | 36 +++++++++++++++++++ skills/contentstack-dart-sdk/SKILL.md | 38 ++++++++++++++++++++ skills/dart-style/SKILL.md | 35 +++++++++++++++++++ skills/dev-workflow/SKILL.md | 42 ++++++++++++++++++++++ skills/runtime-and-http/SKILL.md | 42 ++++++++++++++++++++++ skills/testing/SKILL.md | 35 +++++++++++++++++++ 9 files changed, 301 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-dart-sdk/SKILL.md create mode 100644 skills/dart-style/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/runtime-and-http/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..78817b6 --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,7 @@ +# 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. + +Path to AGENTS.md: from `.cursor/rules/README.md` use `../../AGENTS.md`. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a9cb93f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,50 @@ +# Contentstack Dart 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/contentstack-dart](https://github.com/contentstack/contentstack-dart) | +| *Purpose:* | Official Dart package for Contentstack’s **Content Delivery API (CDA)**—fetch and query published content (entries, assets, content types), live preview, sync, and image transforms. | +| *Out of scope (if any):* | Not the Management API, not a Flutter UI kit, and not a standalone HTTP server—this is a client library built on the `http` package. | + +## Tech stack (at a glance) + +| Area | Details | +| --- | --- | +| Language | Dart SDK `>=2.12.0 <4.0.0` (`environment` in `pubspec.yaml`) | +| Build | `dart pub get`; JSON models use `json_serializable`—regenerate with `dart run build_runner build --delete-conflicting-outputs` when `*.dart` parts change (`pubspec.yaml`, `analysis_options.yaml` excludes `*.g.dart`) | +| Tests | `package:test`; tests under `test/*.dart` (see `test/run_test.sh` for optional coverage steps) | +| Lint / coverage | Analyzer + linter rules in `analysis_options.yaml` (`flutter_lints`-aligned custom rule set); coverage via `dart test --coverage=./coverage` and tooling described in `test/run_test.sh` | +| Other | Runtime deps: `http`, `json_annotation`, `logger`, `path`, `dotenv`, `file`; API docs generated with `dartdoc` (dev dependency) | + +## Commands (quick reference) + +| Command Type | Command | +| --- | --- | +| Build | `dart pub get` | +| Codegen (when models / `part` files change) | `dart run build_runner build --delete-conflicting-outputs` | +| Test | `dart test` | +| Lint | `dart analyze` | +| Format (optional) | `dart format .` | + +**CI / automation:** workflows under [.github/workflows/](.github/workflows/) (e.g. branch checks, publish to pub.dev on version tags, policy scan, Jira integration). + +## Where the documentation lives: skills + +| Skill | Path | What it covers | +| --- | --- | --- | +| Dev workflow | [skills/dev-workflow/SKILL.md](skills/dev-workflow/SKILL.md) | Branches, PR expectations, local commands, optional codegen | +| Contentstack Dart SDK (API) | [skills/contentstack-dart-sdk/SKILL.md](skills/contentstack-dart-sdk/SKILL.md) | Public surface, `Stack`/queries, errors, integration boundaries | +| Dart style & layout | [skills/dart-style/SKILL.md](skills/dart-style/SKILL.md) | Package layout, imports, analyzer conventions | +| Testing | [skills/testing/SKILL.md](skills/testing/SKILL.md) | Test layout, env/credentials, coverage notes | +| Code review | [skills/code-review/SKILL.md](skills/code-review/SKILL.md) | PR checklist and severity hints | +| Runtime & HTTP | [skills/runtime-and-http/SKILL.md](skills/runtime-and-http/SKILL.md) | HTTP client usage, env config, logging, packaging | + +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..265e80c --- /dev/null +++ b/skills/README.md @@ -0,0 +1,16 @@ +# Skills – Contentstack Dart 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/) | Branching, CI expectations, day-to-day build/test/lint/codegen | +| [contentstack-dart-sdk](contentstack-dart-sdk/) | Changing public API, `Stack`, queries, errors, or CDA behavior | +| [dart-style](dart-style/) | Imports, library structure, analyzer/linter alignment | +| [testing](testing/) | Writing or running tests, fixtures, coverage, credentials | +| [code-review](code-review/) | Preparing or reviewing a PR | +| [runtime-and-http](runtime-and-http/) | HTTP usage, retries/env, dependencies, or packaging concerns | + +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..f22a1c9 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,36 @@ +--- +name: code-review +description: Use when preparing a pull request or reviewing changes for this SDK repository. +--- +# Code review – Contentstack Dart SDK + +## When to use + +- Before requesting review or approving a PR +- When triaging risk (API breaks, security, test gaps) + +## Instructions + +### Checklist + +- **Behavior:** Change matches CDA semantics; no accidental Management API assumptions +- **API:** Public exports updated deliberately in `lib/contentstack.dart`; breaking changes documented and versioned +- **Quality:** `dart analyze` clean; `dart test` passes; codegen committed if `*.g.dart` changed +- **Security:** No API keys, tokens, or `.env` with secrets in the diff +- **Style:** Matches `analysis_options.yaml` and project patterns ([../dart-style/SKILL.md](../dart-style/SKILL.md)) + +### Severity (optional) + +- **Blocker:** Breaks consumers, leaks credentials, or ships broken analyze/tests +- **Major:** Incorrect API usage, missing tests for risky logic, undocumented breaking change +- **Minor:** Naming, small refactors, doc nits + +### Process + +- Respect branch rules in [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml) for target branches + +## References + +- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) +- [../testing/SKILL.md](../testing/SKILL.md) +- [AGENTS.md](../../AGENTS.md) diff --git a/skills/contentstack-dart-sdk/SKILL.md b/skills/contentstack-dart-sdk/SKILL.md new file mode 100644 index 0000000..18cf7ee --- /dev/null +++ b/skills/contentstack-dart-sdk/SKILL.md @@ -0,0 +1,38 @@ +--- +name: contentstack-dart-sdk +description: Use when changing the public API, Stack, queries, CDA calls, errors, or SDK boundaries. +--- +# Contentstack Dart SDK (API) – Contentstack Dart SDK + +## When to use + +- Adding or changing exported types in `lib/contentstack.dart` +- Working on `Stack`, content types, entries, queries, assets, image transforms, sync, or live preview +- Defining or handling SDK errors and response models + +## Instructions + +### Entry points + +- Main library: [`lib/contentstack.dart`](../../lib/contentstack.dart) re-exports `src/` modules—prefer exporting new public types from there +- Core client: [`lib/src/stack.dart`](../../lib/src/stack.dart) and related `entry.dart`, `query.dart`, `contenttype.dart`, `asset.dart`, `image_transform.dart` + +### API boundaries + +- This package targets **Content Delivery API** usage (read/query published content), not Management API operations +- HTTP is performed via the `http` package; see [../runtime-and-http/SKILL.md](../runtime-and-http/SKILL.md) + +### Models and errors + +- JSON models use `json_annotation` + generated `*.g.dart` parts—regenerate after schema changes (see [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md)) +- Errors live under [`lib/src/error/`](../../lib/src/error/); keep messages and types consistent with CDA behavior + +### Versioning + +- Package version and changelog: follow semver in `pubspec.yaml` and `CHANGELOG.md` when releasing + +## References + +- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) +- [../dart-style/SKILL.md](../dart-style/SKILL.md) — imports and docs +- [../testing/SKILL.md](../testing/SKILL.md) — integration-style tests diff --git a/skills/dart-style/SKILL.md b/skills/dart-style/SKILL.md new file mode 100644 index 0000000..ab44fa5 --- /dev/null +++ b/skills/dart-style/SKILL.md @@ -0,0 +1,35 @@ +--- +name: dart-style +description: Use for package layout, imports, naming, and analyzer/linter alignment in this Dart repo. +--- +# Dart style & layout – Contentstack Dart SDK + +## When to use + +- Adding new files under `lib/` or `test/` +- Fixing analyzer or lint findings +- Choosing import style (`package:` vs relative) consistent with this repo + +## Instructions + +### Layout + +- Public API: `lib/contentstack.dart` and `lib/src/` +- Tests: `test/*.dart` alongside optional scripts like `test/run_test.sh` +- Analyzer config: root [`analysis_options.yaml`](../../analysis_options.yaml) + +### Conventions reflected in `analysis_options.yaml` + +- Prefer `package:` imports for public code; `avoid_relative_lib_imports` is enabled +- `directives_ordering`, `package_api_docs` (document public APIs), `always_declare_return_types`, strong null-safety practices +- Generated `*.g.dart` files are excluded from analysis—do not hand-edit them + +### Naming + +- Follow `file_names`, `camel_case_types`, `non_constant_identifier_names` as enforced by the configured lints + +## References + +- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — `dart analyze` / format +- [Effective Dart](https://dart.dev/effective-dart) +- [Analyzer options](https://dart.dev/tools/analysis) diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..f820082 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,42 @@ +--- +name: dev-workflow +description: Use for branches, CI, local build/test/lint, codegen, and PR workflow for this repo. +--- +# Dev workflow – Contentstack Dart SDK + +## When to use + +- Starting work in this repository or onboarding +- Before opening a PR (verify analyze, tests, format) +- After editing JSON-serializable models or `part` files + +## Instructions + +### Dependencies and codegen + +- Install deps: `dart pub get` +- If you change files that use `json_serializable` / `part '*.g.dart'`, run: + `dart run build_runner build --delete-conflicting-outputs` + Generated files are excluded from manual lint in `analysis_options.yaml` + +### Quality gates + +- Static analysis: `dart analyze` (rules in `analysis_options.yaml`) +- Tests: `dart test` +- Optional format check: `dart format .` + +### Branches and automation + +- Pull requests run [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml) (e.g. restrictions when targeting `master`) +- Publishing: [.github/workflows/publish.yml](../../.github/workflows/publish.yml) on semver tags; dry-run uses `dart pub publish --dry-run` + +### Package docs + +- HTML API docs: `dartdoc` is listed in `pubspec.yaml`; generate when documenting public API changes + +## References + +- [../contentstack-dart-sdk/SKILL.md](../contentstack-dart-sdk/SKILL.md) — API surface +- [../testing/SKILL.md](../testing/SKILL.md) — tests and coverage +- [../dart-style/SKILL.md](../dart-style/SKILL.md) — layout and analyzer +- [Dart SDK environment](https://dart.dev/tools/pub/pubspec#sdk) diff --git a/skills/runtime-and-http/SKILL.md b/skills/runtime-and-http/SKILL.md new file mode 100644 index 0000000..f18557b --- /dev/null +++ b/skills/runtime-and-http/SKILL.md @@ -0,0 +1,42 @@ +--- +name: runtime-and-http +description: Use for HTTP client usage, env configuration, logging, retries, and dependency packaging for this SDK. +--- +# Runtime & HTTP – Contentstack Dart SDK + +## When to use + +- Changing how requests are built or executed +- Working with `http`, headers, hosts/regions, or error mapping from responses +- Adjusting runtime dependencies (`pubspec.yaml`) or environment loading (`dotenv`) + +## Instructions + +### HTTP stack + +- HTTP calls use the [`http`](https://pub.dev/packages/http) package—keep usage consistent with Dart async/await patterns elsewhere in `lib/src/` +- Do not introduce an alternate HTTP client for the same code paths without team agreement + +### Configuration + +- `dotenv` is used in tests and may be used for local/dev configuration—never commit real credentials ([../testing/SKILL.md](../testing/SKILL.md)) +- `path` and `file` support path handling where needed; keep imports minimal + +### Logging + +- `logger` is a dependency; avoid logging sensitive tokens or full auth headers + +### Packaging + +- Keep `pubspec.yaml` constraints coherent with Dart SDK bounds (`>=2.12.0 <4.0.0`) +- Publishing flow: see [.github/workflows/publish.yml](../../.github/workflows/publish.yml) + +### Retries and resilience + +- If adding retries, backoff, or timeouts, document behavior in public API or internal modules and add tests where feasible + +## References + +- [../contentstack-dart-sdk/SKILL.md](../contentstack-dart-sdk/SKILL.md) +- [http package](https://pub.dev/packages/http) +- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..da69258 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,35 @@ +--- +name: testing +description: Use for test layout, running tests, coverage, fixtures, and credential handling in this repo. +--- +# Testing – Contentstack Dart SDK + +## When to use + +- Adding or changing tests under `test/` +- Running the suite locally or generating coverage +- Dealing with API keys and environment variables for integration-style tests + +## Instructions + +### Layout and runner + +- Tests live in `test/` (e.g. `stack_test.dart`, `query_test.dart`, `entry_test.dart`) +- Run all: `dart test` +- Optional coverage workflow and LCOV steps are documented in [`test/run_test.sh`](../../test/run_test.sh) (`dart test --coverage=./coverage`, `coverage:format_coverage`, etc.) + +### Credentials policy + +- Tests such as [`test/stack_test.dart`](../../test/stack_test.dart) load credentials via `dotenv` (`apiKey`, `deliveryToken`, `environment`, optional `host`) +- **Do not commit secrets**—use local `.env` or CI secrets only as your team documents; never paste real tokens into the repo or PR descriptions + +### Scope + +- Prefer unit tests for pure logic; use guarded integration tests only when stack credentials are available +- After codegen changes, ensure tests still pass and coverage excludes generated files if you use the scripts in `test/run_test.sh` + +## References + +- [../dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — `dart test` in CI workflow +- [../contentstack-dart-sdk/SKILL.md](../contentstack-dart-sdk/SKILL.md) — behavior under test +- [package:test](https://pub.dev/packages/test) From ef7b40f23c7d598e2c545ed1b1fa9ccf6a5ae2bc Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Thu, 9 Apr 2026 16:11:46 +0530 Subject: [PATCH 2/3] Update documentation to reflect deprecation of the Contentstack Dart SDK and provide migration guidance to the Content Delivery API. Added deprecation notice in CHANGELOG and README. --- CHANGELOG.md | 6 ++++++ DEPRECATION.md | 25 +++++++++++++++++++++++++ README.md | 6 ++++++ 3 files changed, 37 insertions(+) create mode 100644 DEPRECATION.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 98bb409..be5c42b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # CHANGELOG +### **APR-09-2026** + +#### Documentation + +- Add deprecation notice and migration guidance to the Content Delivery API. See [DEPRECATION.md](DEPRECATION.md). + ### **JAN-12-2026** #### v1.0.2 - Improved Error messages diff --git a/DEPRECATION.md b/DEPRECATION.md new file mode 100644 index 0000000..0bef329 --- /dev/null +++ b/DEPRECATION.md @@ -0,0 +1,25 @@ +# Deprecation notice: Contentstack Dart SDK (pub.dev) + +This page is for **developers using the Contentstack Dart SDK** published on **pub.dev** as [`contentstack`](https://pub.dev/packages/contentstack). + +## What this means for you + +**We are deprecating this SDK as the recommended path for new Dart and Flutter work.** If you are **starting a new project**, use our **[Content Delivery API (CDA)](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)** directly with your preferred HTTP client (for example `package:http` or your app’s existing networking stack). + +**If you already ship an app** that depends on `contentstack`, you can **keep using it**. Your integration continues to work. Plan a move to direct CDA usage when it fits your release schedule—you do not have to change immediately. + +## What to use for new projects + +| | Link | +|---|------| +| **Content Delivery API** | [Content Delivery API documentation](https://www.contentstack.com/docs/developers/apis/content-delivery-api/) | + +## Why we are making this change + +We are focusing investment on **direct API usage** and **documented integration patterns** for Dart and Flutter. This repository will remain in **maintenance**: we may address critical or security issues where we can, but **we do not plan new features** in the Dart SDK. + +## Support for this SDK going forward + +This repository will stay in **maintenance** as described above. Feature work and new capabilities should be built against the **Content Delivery API** and your application code. + +If you need help choosing a migration path or timing, contact **[Contentstack support](https://www.contentstack.com/)** or your account team. diff --git a/README.md b/README.md index 7d783ec..7b70c4b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,11 @@ # ![Contentstack](https://www.contentstack.com/docs/static/images/contentstack.png) +## Important: Dart SDK and pub.dev + +**We are deprecating** the **Contentstack** Dart SDK on pub.dev as the supported path for **new** development. **New Dart or Flutter projects should use the [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)** directly with the HTTP client of your choice. + +**Already using this SDK?** You can keep shipping with your current dependencies and migrate when it makes sense for your app. More detail: **[DEPRECATION.md](DEPRECATION.md)**. + ## Dart SDK for Contentstack ![version](https://img.shields.io/github/v/release/contentstack/contentstack-dart) From 7344b47eda31be4bd0dc1c2e6743a82a279f98cd Mon Sep 17 00:00:00 2001 From: naman-contentstack Date: Mon, 20 Apr 2026 15:03:55 +0530 Subject: [PATCH 3/3] chore: version bump --- pubspec.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pubspec.yaml b/pubspec.yaml index 894775d..8870745 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,6 @@ name: contentstack description: Contentstack is a headless CMS with an API-first approach that puts content at the centre. -version: 1.0.2 +version: 1.0.3 homepage: https://www.contentstack.com documentation: https://www.contentstack.com/docs/developers/apis/content-delivery-api @@ -24,4 +24,3 @@ dev_dependencies: build_web_compilers: ^4.0.11 json_serializable: ^6.9.0 test: ^1.20.1 -