Skip to content

Commit 8db46c0

Browse files
naman-contentstacknaman-contentstack
authored
Merge pull request #473 from contentstack/feat/DX-5350
feat: add skills in the package
2 parents 08a7fbe + 6f730aa commit 8db46c0

File tree

12 files changed

+306
-0
lines changed

12 files changed

+306
-0
lines changed

‎.cursor/commands/code-review.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
name: code-review
3+
description: PR-style review checklist for this CLI (tests, oclif, security, mocks)
4+
---
5+
6+
# Code review
7+
8+
Use this checklist against the current diff or branch.
9+
10+
## Correctness and UX
11+
12+
- [ ] Command behavior matches flags and prompts; edge cases handled
13+
- [ ] User-facing strings use `messages` / `$t` where appropriate
14+
- [ ] Logging uses project logger / `this.log` patterns, not ad hoc `console` unless intentional
15+
16+
## Tests
17+
18+
- [ ] New or changed behavior covered (success and failure where relevant)
19+
- [ ] No committed `describe.only` / `it.only` / `test.skip` (`--forbid-only`)
20+
- [ ] External I/O mocked (sinon + nock); no real API calls
21+
- [ ] `nock.cleanAll()` and sandbox `restore()` in `afterEach` where used
22+
23+
## TypeScript and style
24+
25+
- [ ] Avoid unnecessary `any`; align with strict TS
26+
- [ ] Follow existing naming (kebab-case files, PascalCase classes)
27+
28+
## Security
29+
30+
- [ ] No secrets, tokens, or internal URLs committed
31+
- [ ] Auth continues to flow through `configHandler` / stubs in tests
32+
33+
## Optional deep dives
34+
35+
- `@skills/testing` — mock patterns
36+
- `@skills/apps-cli-framework` — command structure
37+
- `@skills/contentstack-apps` — API and manifest changes

‎.cursor/commands/execute-tests.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
name: execute-tests
3+
description: Run tests by scope using this package's npm scripts and Mocha paths
4+
---
5+
6+
# Execute tests
7+
8+
- **All tests** — `npm test` (Mocha: `test/**/*.test.ts`, `--forbid-only`)
9+
- **Unit tests with coverage** — `npm run test:unit:report`
10+
- **Unit JSON report** — `npm run test:unit:report:json`
11+
- **Single file** — `npx mocha --forbid-only "test/unit/commands/app/delete.test.ts"` (adjust path)
12+
- **Directory** — `npx mocha --forbid-only "test/unit/commands/app/**/*.test.ts"`
13+
14+
After changes, run `npm run lint` if needed (`posttest` runs lint after `npm test`).

‎.cursor/rules/README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Cursor rules for contentstack-apps-cli
2+
3+
Rules in this directory load based on file context. Skills hold the long-form guidance.
4+
5+
## Files
6+
7+
| Rule | When it applies |
8+
|------|-----------------|
9+
| `dev-workflow.md` | Always (lightweight workflow + TDD) |
10+
| `typescript.mdc` | TypeScript / TSX sources |
11+
| `testing.mdc` | Test files under `test/**/*.test.ts` |
12+
| `oclif-commands.mdc` | CLI commands and base command classes |
13+
| `contentstack-apps.mdc` | Utils, factories, strategies, GraphQL, config, types, messages |
14+
15+
## Expected combinations (examples)
16+
17+
- Editing `src/commands/app/*.ts` — typically `dev-workflow`, `typescript`, `oclif-commands`
18+
- Editing `test/unit/.../*.test.ts` — `dev-workflow`, `typescript`, `testing`
19+
- Editing `src/util/*.ts` or `src/graphql/*.ts` — `dev-workflow`, `typescript`, `contentstack-apps`
20+
21+
## Skills
22+
23+
Project skills live in `.cursor/skills/<name>/SKILL.md`. Reference them in chat, for example:
24+
25+
- `@skills/testing`
26+
- `@skills/apps-cli-framework`
27+
- `@skills/contentstack-apps`
28+
29+
## Optional commands
30+
31+
Slash-style workflows (if enabled in your Cursor setup) live in `.cursor/commands/`.

‎.cursor/rules/contentstack-apps.mdc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
description: "Contentstack Apps CLI domain patterns and API integration"
3+
globs:
4+
- "src/util/**/*.ts"
5+
- "src/factories/**/*.ts"
6+
- "src/strategies/**/*.ts"
7+
- "src/graphql/**/*.ts"
8+
- "src/config/**/*.ts"
9+
- "src/types/**/*.ts"
10+
- "src/messages/**/*.ts"
11+
alwaysApply: false
12+
---
13+
14+
# Contentstack Apps / Developer Hub standards
15+
16+
- Prefer existing utilities (`api-request-handler`, config, `getDeveloperHubUrl`) over ad hoc clients
17+
- Respect region and auth expectations; tests must stub auth — never rely on real tokens in automated tests
18+
- GraphQL queries live under `src/graphql/`; keep shapes aligned with Developer Hub usage in commands
19+
- Handle transient failures thoughtfully where the codebase already uses retries or clear errors
20+
21+
Domain detail: `@skills/contentstack-apps`.

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
description: "Core development workflow and TDD patterns - always applied"
3+
globs: ["**/*.ts", "**/*.js", "**/*.json"]
4+
alwaysApply: true
5+
---
6+
7+
# Development Workflow
8+
9+
## Quick reference
10+
11+
For detailed patterns, use project skills (invoke in chat when relevant):
12+
13+
- `@skills/testing` — Testing, TDD, Mocha, sinon, nock, `@oclif/test`
14+
- `@skills/apps-cli-framework` — Base commands, oclif, `@contentstack/cli-utilities`
15+
- `@skills/contentstack-apps` — Developer Hub, manifest, GraphQL, API utilities
16+
17+
## TDD workflow — mandatory
18+
19+
1. **RED** — Write one failing test
20+
2. **GREEN** — Write minimal code to pass
21+
3. **REFACTOR** — Improve code quality
22+
23+
## Critical rules
24+
25+
- No implementation before tests for new behavior
26+
- Target high coverage; run `npm run test:unit:report` to measure (aim for ~80% on touched areas)
27+
- TypeScript strict mode is enabled in `tsconfig.json`
28+
- Do not commit `test.skip`, `describe.skip`, or `.only` (Mocha runs with `--forbid-only`)

‎.cursor/rules/oclif-commands.mdc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
description: "OCLIF command development patterns and CLI best practices"
3+
globs: ["src/commands/**/*.ts", "src/base-command.ts", "src/app-cli-base-command.ts"]
4+
alwaysApply: false
5+
---
6+
7+
# OCLIF command standards
8+
9+
- Extend `BaseCommand` / `AppCLIBaseCommand` for shared init, flags, SDKs, and logging
10+
- Validate early: parse flags and check required inputs before heavy work
11+
- Keep commands thin: orchestration and UX in the command; logic in utilities, factories, or strategies
12+
- User feedback: use `this.log` / logger patterns from the base command stack; user-facing failures via `this.error` where appropriate
13+
- Reuse `messages` / `$t` for consistent copy
14+
15+
Details: `@skills/apps-cli-framework`.

‎.cursor/rules/testing.mdc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
description: "Testing patterns and TDD workflow"
3+
globs: ["test/**/*.test.ts", "**/*.spec.ts"]
4+
alwaysApply: false
5+
---
6+
7+
# Testing standards
8+
9+
- Exercise success and failure paths
10+
- Mock external I/O: use **sinon** for modules and collaborators; use **nock** for HTTP — no real API calls in unit tests
11+
- Stub at boundaries (`cliux`, `configHandler`, `fs`, SDK entry points) as existing tests do
12+
- Prefer shared helpers in `test/unit/helpers/` (e.g. authentication stubs) over duplicating setup
13+
- Do not commit `.only` or skips; full suite uses `mocha --forbid-only`
14+
15+
Deep patterns: `@skills/testing`.

‎.cursor/rules/typescript.mdc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
description: "TypeScript strict mode standards and naming conventions"
3+
globs: ["**/*.ts", "**/*.tsx"]
4+
alwaysApply: false
5+
---
6+
7+
# TypeScript standards
8+
9+
- Prefer explicit return types on exported and public functions
10+
- Avoid `any`; use narrow types, generics, or `unknown` with guards
11+
- Strict null checks are enabled project-wide (`tsconfig.json`)
12+
- Files: kebab-case (e.g. `app-cli-base-command.ts`)
13+
- Classes: PascalCase
14+
- Functions and methods: camelCase
15+
- Constants: `SCREAMING_SNAKE_CASE` when truly immutable module-level constants
16+
17+
For CLI and command typing patterns, see `@skills/apps-cli-framework`.

‎.cursor/skills/apps-cli-framework/SKILL.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: apps-cli-framework
3+
description: >-
4+
Oclif command structure for Contentstack Apps CLI using BaseCommand,
5+
AppCLIBaseCommand, @contentstack/cli-command, and @contentstack/cli-utilities.
6+
Use when adding flags, init/SDK setup, logging, or organizing command code.
7+
---
8+
9+
# Apps CLI framework
10+
11+
## Class hierarchy
12+
13+
- **`BaseCommand`** (`src/base-command.ts`) — Extends `@contentstack/cli-command` `Command`. Centralizes `init`, `parse`, shared **flags** (`org`, `yes`), logger, `managementSdk` / `marketplaceAppSdk`, region/auth validation, and `messages` / `$t`.
14+
- **`AppCLIBaseCommand`** (`src/app-cli-base-command.ts`) — For app-manifest workflows: loads `manifestData` from the default app JSON path after `super.init()`.
15+
16+
New app-facing commands should extend the appropriate base and call `await super.init()` first.
17+
18+
## Command responsibilities
19+
20+
- **CLI layer**: flag definitions, prompts via `cliux`, progress via `this.log` / logger, user errors via `this.error` / framework patterns.
21+
- **Business logic**: prefer `src/util/`, `src/factories/`, `src/strategies/` over large `run()` methods.
22+
23+
## Flags and parse
24+
25+
- Add static `flags` on the command class; inherit `baseFlags` from `BaseCommand` where org/skip-confirmation apply.
26+
- Parse runs in `BaseCommand.init`; use `this.flags` / `this.args` after `init`.
27+
28+
## Copy and i18n
29+
30+
- Use **`messages`** and **`$t`** from `src/messages` for user-visible strings consistent with the rest of the CLI.
31+
32+
## Errors
33+
34+
- `BaseCommand.catch` handles some framework errors; prefer consistent, actionable messages for users.

‎.cursor/skills/contentstack-apps/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: contentstack-apps
3+
description: >-
4+
Contentstack Developer Hub apps, manifests, GraphQL, and HTTP helpers for this
5+
CLI. Use when changing API calls, manifest handling, regions, or shared app
6+
types.
7+
---
8+
9+
# Contentstack Apps domain
10+
11+
## Configuration
12+
13+
- **`src/config/index.ts`** — Default filenames, Developer Hub base URL defaults, and related constants consumed by commands and `BaseCommand`.
14+
15+
## Manifest and app data
16+
17+
- App manifest shape and typings live under **`src/types/`** (e.g. `AppManifest`).
18+
- Commands that need on-disk manifest use **`AppCLIBaseCommand`** and `config.defaultAppFileName`.
19+
20+
## HTTP and APIs
21+
22+
- **`src/util/api-request-handler.ts`** — Shared request/error handling patterns; prefer extending these utilities over raw `fetch` scattered in commands.
23+
- **`src/util/inquirer.ts`** — `getDeveloperHubUrl()` and related helpers; tests often nock against the derived host.
24+
25+
## GraphQL
26+
27+
- Queries and fragments belong in **`src/graphql/queries.ts`** (or sibling files if the folder grows). Keep query strings aligned with Developer Hub expectations used by install/deploy/update flows.
28+
29+
## Auth and region in tests
30+
31+
- Production code expects region and auth from `@contentstack/cli-utilities` `configHandler`.
32+
- Unit tests must stub these (see `stubAuthentication` in `test/unit/helpers/auth-stub-helper.ts`); never require real credentials.
33+
34+
## Rate limits and retries
35+
36+
- If adding new network calls, follow existing patterns for errors and retries in utilities rather than blocking the CLI without feedback.

0 commit comments

Comments
 (0)