Skip to content

Commit 85979d2

Browse files
reeshika-hreeshika-h
authored
Merge pull request #75 from contentstack/fix/DX-5362
Added cursor rules and skills
2 parents 6c74158 + 5767758 commit 85979d2

File tree

15 files changed

+490
-1
lines changed

15 files changed

+490
-1
lines changed

‎.cursor/rules/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Cursor Rules – Contentstack iOS CDA SDK
2+
3+
This directory contains Cursor AI rules that apply when working in this repository. Rules provide persistent context so the AI follows project conventions and Contentstack CDA patterns.
4+
5+
## How rules are applied
6+
7+
- **File-specific rules** use the `globs` frontmatter: they apply when you open or edit files matching that pattern.
8+
- **Always-on rules** use `alwaysApply: true`: they are included in every conversation in this project.
9+
10+
## Rule index
11+
12+
| File | Applies when | Purpose |
13+
|------|--------------|---------|
14+
| **dev-workflow.md** | (Reference only; no glob) | Development workflow: branches, running tests, PR expectations. Read for process guidance. |
15+
| **ios.mdc** | `Contentstack/`, `ContentstackInternal/`, `ThirdPartyExtension/` `*.h` / `*.m` | Objective-C standards: naming, module layout, headers vs implementation, nullability, consistency with existing SDK style. |
16+
| **contentstack-ios-cda.mdc** | `Contentstack/`, `ContentstackInternal/` `*.h` / `*.m` | CDA-specific patterns: Stack/Config, host/version/region/branch, HTTP entry points, retry behavior, blocks/callbacks, alignment with Content Delivery API. |
17+
| **testing.mdc** | `ContentstackTest/**/*.h`, `ContentstackTest/**/*.m` | XCTest patterns: test class naming, unit vs network/integration-style tests, fixtures (`config.json`), stability. |
18+
| **code-review.mdc** | Always | PR/review checklist: API stability, error handling, backward compatibility, dependencies and security (e.g. SCA). |
19+
20+
## Related
21+
22+
- **AGENTS.md** (repo root) – Main entry point for AI agents: project overview, entry points, commands, pointers to rules and skills.
23+
- **skills/** – Reusable skill docs (Contentstack iOS CDA, testing, code review, framework) for deeper guidance on specific tasks.

‎.cursor/rules/code-review.mdc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
description: PR and code review checklist – API stability, errors, compatibility, security, testing
3+
alwaysApply: true
4+
---
5+
6+
# Code Review Checklist – Contentstack iOS CDA SDK
7+
8+
Use this checklist when reviewing pull requests or before opening a PR.
9+
10+
## API design and stability
11+
12+
- [ ] **Public API:** New or changed public classes/methods/properties are necessary and documented (header comments / doc comments where the project documents API).
13+
- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly called out and justified (e.g. major semver bump per release policy).
14+
- [ ] **Naming:** Method and type names are consistent with existing SDK style (Objective-C / Swift import names) and CDA terminology.
15+
16+
## Error handling and robustness
17+
18+
- [ ] **Errors:** API failures surface through existing patterns (`NSError **` out-parameters, failure blocks, or delegate callbacks as used in the touched code).
19+
- [ ] **Nullability:** `NS_ASSUME_NONNULL` / `nullable` annotations stay accurate; no unintended force-unwraps or ignored errors in new paths.
20+
- [ ] **Memory / threading:** Blocks and delegates retain cycles are avoided; main-queue vs background behavior matches existing networking code.
21+
22+
## Dependencies and security
23+
24+
- [ ] **Dependencies:** No new third-party or vendored code without justification; version bumps are intentional and do not introduce known vulnerabilities.
25+
- [ ] **SCA:** Address any security findings (e.g. from Snyk or similar) in the scope of the PR or in a follow-up.
26+
27+
## Testing
28+
29+
- [ ] **Coverage:** New or modified behavior is covered by XCTest unit and/or integration-style tests as appropriate.
30+
- [ ] **Test quality:** Tests are readable, stable (no flakiness), and follow project conventions (see **testing.mdc**).
31+
32+
## Severity (optional)
33+
34+
- **Blocker:** Must fix before merge (e.g. breaking public API without approval, security issue, no tests for new code).
35+
- **Major:** Should fix (e.g. inconsistent error handling, missing documentation on new public API).
36+
- **Minor:** Nice to fix (e.g. style, minor docs).

‎.cursor/rules/contentstack-ios-cda.mdc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
description: Contentstack CDA patterns – Stack/Config, HTTP, retry, callbacks, Content Delivery API
3+
globs:
4+
- "Contentstack/**/*.{h,m}"
5+
- "ContentstackInternal/**/*.{h,m}"
6+
---
7+
8+
# Contentstack iOS CDA – SDK Rules
9+
10+
Apply when editing the SDK core (`Contentstack/`, `ContentstackInternal/`). Keep behavior aligned with the [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/).
11+
12+
## Stack and Config
13+
14+
- **Entry point:** `+[Contentstack stackWithAPIKey:accessToken:environmentName:]` and `stackWithAPIKey:accessToken:environmentName:config:` return a **`Stack`**. Use **`Config`** for optional settings (host, region, branch, delegate, early access).
15+
- **Defaults:** Follow existing **`Config`** initialization (host/version behavior as implemented in `Config` / stack setup).
16+
- **Region / branch:** Support regional endpoints and branch delivery via **`Config`** properties, consistent with CDA docs and current stack URL building (`CSIOAPIURLs`, etc.).
17+
18+
## HTTP layer
19+
20+
- **Requests** should flow through **`CSIOCoreHTTPNetworking`** and **`CSURLSessionManager`** (and related internal types). Do not bypass the shared session stack for CDA calls without a strong reason.
21+
- **Headers:** Preserve User-Agent, access token, environment, and other required CDA headers as built in existing request code (`CSIOConstants`, stack configuration).
22+
- **Errors:** Map API failures to existing patterns (`NSError`, failure blocks, or error callbacks) so app code receives consistent semantics.
23+
24+
## Retry and resilience
25+
26+
- Retry logic for transient failures lives in the networking layer (e.g. **`CSIOCoreHTTPNetworking`** handling of status / error codes). When changing retry behavior, keep defaults and caps consistent with CDA-friendly backoff and document any behavior change.
27+
- Unlike some other SDKs, retry is not always exposed as a separate public **`Config`** surface; prefer adjusting the internal implementation coherently.
28+
29+
## Callbacks and async
30+
31+
- Use **blocks**, delegates (`CSURLSessionDelegate`), and existing completion patterns already used on **`Stack`**, **`Entry`**, **`Query`**, **`Asset`**, **`SyncStack`**, etc.
32+
- Do not change public callback signatures without a compatibility plan (semver / migration note).
33+
34+
## CDA concepts
35+
36+
- **Entry, Query, Asset, Content Type, Sync, Taxonomy, AssetLibrary, Group, QueryResult** – follow existing class names and CDA semantics (query parameters, response parsing). When adding CDA features, align with the official Content Delivery API documentation and with other Contentstack CDA SDKs where practical.

‎.cursor/rules/dev-workflow.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Development Workflow – Contentstack iOS CDA SDK
2+
3+
Use this as the standard workflow when contributing to the iOS CDA SDK.
4+
5+
## Branches
6+
7+
- Use feature branches for changes (e.g. `feat/...`, `fix/...`).
8+
- Base work off the appropriate long-lived branch (e.g. `staging`, `development`) per team norms.
9+
10+
## Running tests
11+
12+
- **From Xcode:** Select scheme **Contentstack**, then **Product → Test** (`⌘U`).
13+
- **Command line:**
14+
`xcodebuild -project Contentstack.xcodeproj -scheme Contentstack -destination 'platform=iOS Simulator,name=<Device>' test`
15+
Replace `<Device>` with an installed simulator (list with `xcrun simctl list devices available`).
16+
17+
Run tests before opening a PR. Tests that call the live CDA may require **`ContentstackTest/config.json`** (API key, delivery token, environment, host, etc.)—keep secrets out of git; follow existing test setup patterns.
18+
19+
## Pull requests
20+
21+
- Ensure the project builds and tests pass locally.
22+
- Follow the **code-review** rule (see `.cursor/rules/code-review.mdc`) for the PR checklist.
23+
- Keep changes backward-compatible for public API; call out any breaking changes clearly in the PR description.
24+
25+
## Optional: TDD
26+
27+
If the team uses TDD, follow RED–GREEN–REFACTOR when adding behavior: write a failing test first, then implement to pass, then refactor. The **testing** rule and **skills/testing** skill describe test structure and naming.

‎.cursor/rules/ios.mdc‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
description: Objective-C standards and Contentstack iOS SDK layout for CDA sources
3+
globs:
4+
- "Contentstack/**/*.{h,m}"
5+
- "ContentstackInternal/**/*.{h,m}"
6+
- "ThirdPartyExtension/**/*.{h,m}"
7+
---
8+
9+
# iOS SDK Standards – Contentstack iOS CDA SDK
10+
11+
Apply these conventions when editing Objective-C code in the SDK (not test targets).
12+
13+
## Language and runtime
14+
15+
- **Objective-C** with Apple’s modern conventions: use `NS_ASSUME_NONNULL_BEGIN` / `END` (or explicit `nullable` / `nonnull`) on public headers where the project already does.
16+
- **Swift consumers** import the module; avoid breaking Swift names without good reason (Objective-C names map to Swift automatically).
17+
18+
## Layout and modules
19+
20+
- **Public API** lives under **`Contentstack/`** (headers shipped via `public_header_files` in the podspec).
21+
- **Internal implementation** lives under **`ContentstackInternal/`** (HTTP, URLs, constants, extensions). Do not expose internal headers as public API without an explicit decision.
22+
- **Vendored / shared code** under **`ThirdPartyExtension/`** (e.g. `CSURLSessionManager`, markdown, ISO8601). Keep changes minimal and consistent with upstream vendoring policy.
23+
24+
## Naming
25+
26+
- **Classes:** Prefix or unprefixed names as established in this SDK (`Stack`, `Config`, `CSIOCoreHTTPNetworking`, etc.); do not introduce conflicting generic names.
27+
- **Methods:** Objective-C style, descriptive selectors; match existing patterns for “fetch”, “callback”, “withConfig:”, etc.
28+
- **Categories:** Use project prefixes on category methods to avoid collisions (`cs_` or existing project convention).
29+
- **Test classes:** See **testing.mdc** (`*Test` XCTest case naming).
30+
31+
## Headers
32+
33+
- Public declarations belong in **`Contentstack/*.h`**; import umbrella patterns consistent with **`Contentstack.h`**.
34+
- Use forward declarations (`@class`) in headers when possible to reduce compile coupling.
35+
36+
## Documentation
37+
38+
- Public API should retain or extend the existing block-comment style in headers (parameters, return value, Obj-C / Swift snippets where already used).
39+
40+
## General
41+
42+
- Prefer explicit error handling over silent failure when adding new async or network paths.
43+
- Match existing memory management (ARC); avoid introducing non-ARC patterns.

‎.cursor/rules/testing.mdc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
description: XCTest patterns, unit vs integration-style tests, fixtures, stability
3+
globs:
4+
- "ContentstackTest/**/*.{h,m}"
5+
---
6+
7+
# Testing Rules – Contentstack iOS CDA SDK
8+
9+
Apply when writing or editing tests in the **ContentstackTest** target.
10+
11+
## Test naming and layout
12+
13+
- **XCTest** case classes: suffix **`Test`** (e.g. `ContentstackMainTest`, `QueryResultTest`, `SyncTest`) matching existing files under **`ContentstackTest/`**.
14+
- **Test methods:** `- (void)test...` with descriptive names; group related tests with `#pragma mark` sections where the file already uses that style.
15+
16+
## Unit vs integration-style
17+
18+
- **Unit-style:** Mock or avoid network where possible; assert parsing, model behavior, and edge cases quickly.
19+
- **Integration-style:** Tests that call the live CDA require valid credentials—typically via **`config.json`** in the test bundle (see `ContentstackMainTest` and similar). Do not commit real tokens; document required keys for local/CI runs.
20+
21+
## XCTest usage
22+
23+
- Use **`XCTAssert*`** macros; use **`XCTestExpectation`** / **`waitForExpectationsWithTimeout:`** for async flows.
24+
- Use **`setUp`** / **`tearDown`** for fixtures; load JSON or plist resources from **`[NSBundle bundleForClass:[self class]]`** when the project uses bundle resources.
25+
26+
## Stability
27+
28+
- Avoid time-dependent assertions unless necessary; prefer reasonable timeouts for network tests.
29+
- Do not introduce flaky ordering assumptions or shared mutable global state across tests without synchronization.
30+
31+
## Coverage
32+
33+
- The **Contentstack** scheme enables code coverage for the **Contentstack** framework target. Add or extend tests when changing production behavior; do not drop coverage for critical paths without replacement tests.

‎.vscode/settings.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"snyk.advanced.organization": "18cb8ddb-8261-46fc-85fd-8b7025684b29",
3+
"snyk.advanced.autoSelectOrganization": true
4+
}

‎AGENTS.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Contentstack iOS CDA SDK – Agent Guide
2+
3+
This document is the main entry point for AI agents working in this repository.
4+
5+
## Project
6+
7+
- **Name:** Contentstack iOS CDA SDK (contentstack-ios)
8+
- **Purpose:** iOS client for the Contentstack **Content Delivery API (CDA)**. It fetches content (entries, assets, content types, sync, taxonomy) from Contentstack for iOS apps (Objective-C primary API; Swift-compatible headers).
9+
- **Repo:** [contentstack-ios](https://github.com/contentstack/contentstack-ios)
10+
11+
## Tech stack
12+
13+
- **Languages:** Objective-C (public SDK surface), with Swift-callable APIs via generated/bridged headers
14+
- **IDE / build:** Xcode, `Contentstack.xcodeproj`
15+
- **Distribution:** CocoaPods (`Contentstack.podspec`); no Swift Package Manager manifest in-repo today
16+
- **HTTP:** `NSURLSession` via `CSURLSessionManager` and `CSIOCoreHTTPNetworking` (internal)
17+
- **Testing:** XCTest, target **ContentstackTest** (`ContentstackTest.xctest`), scheme **Contentstack** (tests enabled; code coverage for **Contentstack** framework)
18+
19+
## Main entry points
20+
21+
- **`Contentstack`** – Factory: `+[Contentstack stackWithAPIKey:accessToken:environmentName:]` and `stackWithAPIKey:accessToken:environmentName:config:` return a **`Stack`**.
22+
- **`Stack`** – Main API surface: content types, entries, queries, assets, asset library, sync, taxonomy, etc.
23+
- **`Config`** – Optional settings: host, region, version (read-only where applicable), branch, URL session delegate, early access headers.
24+
- **Paths (source):** `Contentstack/` (public headers + implementation), `ContentstackInternal/` (HTTP, URLs, constants, internal helpers), `ThirdPartyExtension/` (networking session layer, markdown, ISO8601).
25+
- **Paths (tests):** `ContentstackTest/`
26+
27+
## Commands
28+
29+
- **Build framework:**
30+
`xcodebuild -project Contentstack.xcodeproj -scheme Contentstack -destination 'generic/platform=iOS' -configuration Debug build`
31+
- **Run tests:**
32+
`xcodebuild -project Contentstack.xcodeproj -scheme Contentstack -destination 'platform=iOS Simulator,name=<Device>' test`
33+
Pick a simulator you have installed (e.g. **iPhone 16**). Tests may require **`ContentstackTest/config.json`** (or equivalent) with stack credentials for integration-style cases—do not commit secrets.
34+
- **CocoaPods lint (maintainers):**
35+
`pod lib lint Contentstack.podspec`
36+
37+
Use **Product → Test** in Xcode as an alternative to `xcodebuild test`.
38+
39+
## Rules and skills
40+
41+
- **`.cursor/rules/`** – Cursor rules for this repo:
42+
- **README.md** – Index of all rules and when each applies.
43+
- **dev-workflow.md** – Branches, tests, PR expectations.
44+
- **ios.mdc** – Applies to SDK Objective-C sources: style, structure, naming.
45+
- **contentstack-ios-cda.mdc** – Applies to SDK core: CDA patterns, Stack/Config, HTTP/retry, callbacks, CDA alignment.
46+
- **testing.mdc** – Applies to **ContentstackTest**: XCTest naming, unit vs integration-style tests.
47+
- **code-review.mdc** – Always applied: PR/review checklist (aligned with other Contentstack CDA SDKs).
48+
- **`skills/`** – Reusable skill docs:
49+
- **contentstack-ios-cda** – CDA implementation and SDK core behavior.
50+
- **testing** – Adding or refactoring tests.
51+
- **code-review** – PR review or pre-submit checklist.
52+
- **framework** – Config, HTTP session layer, retry behavior, and networking internals.
53+
54+
Refer to `.cursor/rules/README.md` for the rule index and to `skills/README.md` for when to use each skill.
55+
56+
For cross-SDK alignment, see the Java CDA SDK’s **AGENTS.md** and `.cursor/rules/` in [contentstack-java](https://github.com/contentstack/contentstack-java) (patterns are analogous; APIs and build tools differ).

‎ContentstackInternal/NSObject+Extensions.m‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,7 @@ - (NSArray *)arrayFromJSONData:(NSData *)data {
294294
- (NSString *)jsonStringFromArray:(NSArray*)array {
295295
if (array == nil) { return nil; }
296296
NSData *JSONData = [NSJSONSerialization dataWithJSONObject:array options:0 error:NULL];
297+
if (JSONData == nil) { return nil; }
297298
return [[NSString alloc] initWithData:JSONData encoding:NSUTF8StringEncoding];
298299
}
299300

‎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

0 commit comments

Comments
 (0)