Skip to content

Commit 8ad7a1f

Browse files
sunil-lakshmansunil-lakshman
committed
Added cursor rules and skill files
1 parent 87f735f commit 8ad7a1f

File tree

8 files changed

+278
-0
lines changed

8 files changed

+278
-0
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 Ruby 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-ruby](https://github.com/contentstack/contentstack-ruby) (Ruby gem `contentstack`) |
10+
| **Purpose:** | Ruby client for the Contentstack Content Delivery API (CDA): stack client, content types, entries, assets, queries, sync, and live preview. |
11+
| **Out of scope (if any):** | Management / write APIs and app-specific business logic live outside this gem. Rich-text rendering delegates to the `contentstack_utils` gem. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
| --- | --- |
17+
| Language | Ruby **≥ 3.3** (see `contentstack.gemspec` and `.ruby-version`; team uses **3.3.x** locally). |
18+
| Build | **Bundler** + **`contentstack.gemspec`**; `Gemfile` pulls the gemspec. |
19+
| Tests | **RSpec 3** under `spec/**/*_spec.rb`; **`spec/spec_helper.rb`** loads WebMock and SimpleCov. |
20+
| Lint / coverage | **SimpleCov** (via `spec_helper.rb`); HTML under `coverage/`. No RuboCop in this repo. **YARD** for API docs (see `rakefile.rb`, `.yardopts`). |
21+
| Runtime deps | `activesupport`, `contentstack_utils` (~> 1.2); `Gemfile` pins **nokogiri** for security alignment. |
22+
23+
## Commands (quick reference)
24+
25+
| Command type | Command |
26+
| --- | --- |
27+
| Install deps | `bundle install` |
28+
| Build gem | `gem build contentstack.gemspec` |
29+
| Test | `bundle exec rspec` |
30+
| Single file | `bundle exec rspec spec/path/to_spec.rb` |
31+
| Lint / format | No RuboCop or formatter in-repo; match existing `lib/` and `spec/` style. |
32+
| Docs (YARD) | `bundle exec rake yard` |
33+
34+
**CI / automation:** `.github/workflows/check-branch.yml` (PR branch rules toward `master`), `.github/workflows/release-gem.yml` (publish on release), plus `codeql-analysis.yml`, `sca-scan.yml`, `policy-scan.yml`, `issues-jira.yml`. There is no dedicated “run RSpec on every PR” workflow in-repo—run tests locally before opening a PR.
35+
36+
## Where the documentation lives: skills
37+
38+
| Skill | Path | What it covers |
39+
| --- | --- | --- |
40+
| Dev workflow | `skills/dev-workflow/SKILL.md` | Branches, bundler, commands, release notes alignment. |
41+
| Ruby SDK (CDA) | `skills/contentstack-ruby-sdk/SKILL.md` | Public API, modules, errors, versioning, integration with `contentstack_utils`. |
42+
| Ruby style & layout | `skills/ruby-style/SKILL.md` | File layout, idioms, and conventions for this codebase. |
43+
| Testing | `skills/testing/SKILL.md` | RSpec, WebMock, fixtures, env vars, coverage. |
44+
| Code review | `skills/code-review/SKILL.md` | PR checklist and review expectations. |
45+
| Framework & packaging | `skills/framework/SKILL.md` | Bundler/gem packaging, HTTP stack (`Net::HTTP`), retries, optional proxy. |
46+
47+
An index with “when to use” hints is in `skills/README.md`.
48+
49+
## Using Cursor (optional)
50+
51+
If you use **Cursor**, `.cursor/rules/README.md` only points to **`AGENTS.md`**—same docs as everyone else.

‎skills/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Skills – Contentstack Ruby SDK
2+
3+
Source of truth for detailed guidance. Read **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` | Setting up the repo, running build/test/docs, branching, or preparing a release-oriented change. |
10+
| `contentstack-ruby-sdk` | Changing or extending the public CDA client API, errors, or how the gem integrates with Contentstack and `contentstack_utils`. |
11+
| `ruby-style` | Naming, file layout, Ruby idioms, and keeping changes consistent with existing `lib/` and `spec/` code. |
12+
| `testing` | Adding or changing specs, fixtures, WebMock stubs, SimpleCov, or test-only helpers. |
13+
| `code-review` | Reviewing or authoring a PR; scope, docs, and risk checklist. |
14+
| `framework` | Dependencies, gemspec, HTTP/retry/proxy behavior, or gem build/install mechanics. |
15+
16+
Each folder contains **SKILL.md** with YAML frontmatter (`name`, `description`).

‎skills/code-review/SKILL.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: code-review
3+
description: Use when authoring or reviewing a pull request for contentstack-ruby—scope, tests, API stability, and documentation.
4+
---
5+
6+
# Code review – Contentstack Ruby SDK
7+
8+
## When to use
9+
10+
- Opening a PR against **`development`** (or the team’s active integration branch)
11+
- Reviewing a colleague’s change for risk, API impact, or test gaps
12+
- Deciding whether a change needs **CHANGELOG** / version bump / **README** updates
13+
14+
## Instructions
15+
16+
### Blocker (must fix before merge)
17+
18+
- **Tests:** New or changed behavior lacks **`spec`** coverage where feasible, or **`bundle exec rspec`** would fail.
19+
- **Security / secrets:** No real API keys, tokens, or stack data committed; tests use fixtures and WebMock.
20+
- **Breaking changes:** Public method signatures or documented behavior changed without version strategy and **CHANGELOG** / **README** updates as appropriate.
21+
22+
### Major (strongly prefer fixing)
23+
24+
- **WebMock:** New HTTP paths or hosts not stubbed in **`spec/spec_helper.rb`**, causing flaky or network-dependent specs.
25+
- **Error handling:** New failure modes do not use **`Contentstack::Error`** / **`ErrorMessages`** consistently with the rest of the client.
26+
- **Dependencies:** **`contentstack.gemspec`** or **`Gemfile`** changes without a clear reason (security pins are documented in comments—preserve that intent).
27+
28+
### Minor (nice to have)
29+
30+
- YARD or **README** examples for new public options
31+
- Clear commit messages and PR description linking to internal tickets if applicable
32+
33+
### Process notes
34+
35+
- **`master`** is protected by **`.github/workflows/check-branch.yml`**; follow team flow (**`staging`** → **`master`**) for production promotion.
36+
- Run **`bundle exec rspec`** locally; CI may not run the full suite on every PR in this repository.
37+
38+
## References
39+
40+
- `skills/dev-workflow/SKILL.md` — branches and commands
41+
- `skills/testing/SKILL.md` — fixtures and stubs
42+
- `skills/contentstack-ruby-sdk/SKILL.md` — API surface
43+
- [Reference PR pattern (Cursor rules + skills)](https://github.com/contentstack/contentstack-utils-swift/pull/36)

‎skills/dev-workflow/SKILL.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: dev-workflow
3+
description: Use when setting up the repo, running tests or docs, choosing branches, or aligning with release and CI expectations for contentstack-ruby.
4+
---
5+
6+
# Dev workflow – Contentstack Ruby SDK
7+
8+
## When to use
9+
10+
- First-time setup or refreshing dependencies
11+
- Running the test suite or generating YARD docs before a PR
12+
- Choosing a base branch or understanding merge restrictions
13+
- Bumping version or coordinating with gem release (see also `skills/framework/SKILL.md`)
14+
15+
## Instructions
16+
17+
### Environment
18+
19+
- Use Ruby **≥ 3.3**; match **`.ruby-version`** when using rbenv/asdf/chruby.
20+
- From the repo root: `bundle install` (respects `Gemfile` + `contentstack.gemspec`).
21+
22+
### Everyday commands
23+
24+
- Full test suite: `bundle exec rspec`
25+
- One file: `bundle exec rspec spec/<name>_spec.rb`
26+
- API docs: `bundle exec rake yard` (task defined in `rakefile.rb`; options in `.yardopts`)
27+
- Build the gem locally: `gem build contentstack.gemspec`
28+
29+
### Branches and PRs
30+
31+
- Default integration branch is typically **`development`** (confirm on GitHub). **`master`** merges are restricted: `.github/workflows/check-branch.yml` blocks PRs into `master` unless the head branch is **`staging`**—follow org process for promotion.
32+
- Keep PRs focused; mention breaking API or Ruby version requirement changes in the description.
33+
34+
### Before you push
35+
36+
- Run **`bundle exec rspec`**; ensure new behavior has specs and existing stubs in `spec/spec_helper.rb` stay consistent with CDN host patterns you use.
37+
38+
## References
39+
40+
- `AGENTS.md` — stack summary and command table
41+
- `skills/testing/SKILL.md` — RSpec and fixtures
42+
- `skills/framework/SKILL.md` — gemspec, Bundler, HTTP concerns
43+
- [contentstack/contentstack-ruby](https://github.com/contentstack/contentstack-ruby)

‎skills/framework/SKILL.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: framework
3+
description: Use when changing Bundler setup, gemspec, gem build/release, or HTTP/retry/proxy behavior in the CDA client.
4+
---
5+
6+
# Framework & packaging – Contentstack Ruby SDK
7+
8+
## When to use
9+
10+
- Editing **`Gemfile`**, **`contentstack.gemspec`**, or **`Gemfile.lock`** (via `bundle install`)
11+
- Changing **`Contentstack::API`** request sending, timeouts, retries, or proxy support
12+
- Preparing **`gem build`** / release alignment with **`.github/workflows/release-gem.yml`**
13+
14+
## Instructions
15+
16+
### Bundler and gemspec
17+
18+
- **`contentstack.gemspec`**: declares **`required_ruby_version >= 3.3`**, runtime deps **`activesupport`**, **`contentstack_utils`** (~> 1.2), and dev deps **rspec**, **webmock**, **simplecov**, **yard**.
19+
- **`Gemfile`**: `gemspec` plus **nokogiri** pin for transitive security alignment (see comment in file)—do not remove without verifying **`contentstack_utils`** / **nokogiri** constraints.
20+
21+
### HTTP stack
22+
23+
- CDA calls are implemented in **`lib/contentstack/api.rb`** using **`Net::HTTP`**, **`URI`**, **ActiveSupport JSON**, with retry logic in **`fetch_retry`** and configurable **`timeout`**, **`retryDelay`**, **`retryLimit`**, **`errorRetry`** from **`Contentstack::Client`** options.
24+
- **Live preview** and **proxy** paths are configured on the client and passed into **`API.init_api`**—keep option keys backward compatible.
25+
26+
### Release automation
27+
28+
- **`.github/workflows/release-gem.yml`** runs on **GitHub release created**; it uses **`ruby/setup-ruby`** (workflow currently pins Ruby **2.7** for publish—aligning that pin with **`required_ruby_version`** is an org/infrastructure concern; do not change release secrets from the skill docs).
29+
30+
### Local validation
31+
32+
- **`gem build contentstack.gemspec`** should succeed after dependency and require-path changes.
33+
- After changing **`lib/`** load order or new files, run **`bundle exec rspec`** and smoke-require in **`irb -r contentstack`** if needed.
34+
35+
## References
36+
37+
- `skills/contentstack-ruby-sdk/SKILL.md` — client options and public API
38+
- `skills/dev-workflow/SKILL.md` — everyday commands
39+
- `skills/testing/SKILL.md` — stubbing HTTP for tests
40+
- [RubyGems guides](https://guides.rubygems.org/)

‎skills/ruby-style/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: ruby-style
3+
description: Use when editing Ruby in lib/ or spec/ and you need layout, naming, and idioms consistent with this gem.
4+
---
5+
6+
# Ruby style & layout – Contentstack Ruby SDK
7+
8+
## When to use
9+
10+
- Adding new files under **`lib/contentstack/`** or **`spec/`**
11+
- Refactoring while keeping style aligned with existing code
12+
- Choosing where to place helpers (e.g. `lib/util.rb` vs. domain classes)
13+
14+
## Instructions
15+
16+
### Layout
17+
18+
- **`lib/contentstack.rb`**: top-level module, YARD overview, delegates to **`contentstack_utils`** for render helpers.
19+
- **`lib/contentstack/*.rb`**: one main concept per file (`client`, `api`, `query`, etc.).
20+
- **`lib/util.rb`**: refinements / utilities consumed via `using Utility` where already established—follow existing patterns before introducing new global monkey patches.
21+
- **`spec/*_spec.rb`**: mirror behavior under test; shared setup belongs in **`spec/spec_helper.rb`** only when it is truly global (WebMock, SimpleCov, default stubs).
22+
23+
### Conventions observed in this repo
24+
25+
- Prefer explicit validation in **`Contentstack::Client#initialize`** with **`Contentstack::Error`** for invalid configuration.
26+
- Use **`ActiveSupport`** patterns (e.g. `present?`) where already used in **`Contentstack::API`** and client code—stay consistent within a file.
27+
- Keep public method names stable; breaking renames require a major version strategy and **README** / **CHANGELOG** updates.
28+
29+
### Naming
30+
31+
- Match existing spellings in public APIs (e.g. `retryDelay`, `retryLimit`) for backward compatibility even if Ruby style guides suggest snake_case for new APIs—when adding **new** options, prefer **snake_case** unless extending an existing options hash that is documented with camelCase keys.
32+
33+
## References
34+
35+
- `skills/contentstack-ruby-sdk/SKILL.md` — public API boundaries
36+
- `skills/testing/SKILL.md` — spec patterns
37+
- `CHANGELOG.md` — record user-visible behavior changes

‎skills/testing/SKILL.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: testing
3+
description: Use when writing or fixing RSpec examples, WebMock stubs, JSON fixtures, SimpleCov, or env-based test helpers.
4+
---
5+
6+
# Testing – Contentstack Ruby SDK
7+
8+
## When to use
9+
10+
- Adding specs under **`spec/`**
11+
- Changing CDN hosts, paths, or headers used in **`Contentstack::API`**
12+
- Updating global **`WebMock`** stubs in **`spec/spec_helper.rb`**
13+
- Interpreting **SimpleCov** output under **`coverage/`**
14+
15+
## Instructions
16+
17+
### Runner and config
18+
19+
- Run **`bundle exec rspec`** from the repo root.
20+
- **`spec/spec_helper.rb`** requires **WebMock/RSpec**, disables real network (`WebMock.disable_net_connect!(allow_localhost: true)`), starts **SimpleCov**, and requires **`contentstack`**.
21+
22+
### Stubbing HTTP
23+
24+
- Default stubs live in **`config.before(:each)`** in **`spec/spec_helper.rb`** for hosts such as **`cdn.contentstack.io`**, **`eu-cdn.contentstack.com`**, **`custom-cdn.contentstack.com`**, and **`preview.contentstack.io`**.
25+
- When adding endpoints or hosts, add matching **`stub_request`** entries and JSON fixtures under **`spec/fixtures/`** (reuse shape of real CDA responses where possible).
26+
27+
### Fixtures
28+
29+
- Store static JSON under **`spec/fixtures/*.json`**; load with **`File.read`** relative to **`__dir__`** or **`File.dirname(__FILE__)`** as existing specs do.
30+
31+
### Helpers
32+
33+
- **`create_client`** and **`create_preview_client`** in **`spec_helper`** build clients using **`ENV['API_KEY']`**, **`ENV['DELIVERY_TOKEN']`**, **`ENV['ENVIRONMENT']`** — tests should not rely on real credentials; stubs supply responses.
34+
35+
### Coverage
36+
37+
- **SimpleCov** runs on every **`rspec`** invocation; review **`coverage/index.html`** after substantive **`lib/`** changes.
38+
39+
## References
40+
41+
- `skills/contentstack-ruby-sdk/SKILL.md` — which classes own behavior under test
42+
- `skills/dev-workflow/SKILL.md` — commands
43+
- [RSpec](https://rspec.info/), [WebMock](https://github.com/bblimke/webmock)

0 commit comments

Comments
 (0)