From 68b21a1690c11d71a064ff2444fe0a498d3a194d Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Fri, 10 Apr 2026 11:56:34 +0530 Subject: [PATCH] Add AGENTS.md, skills README, and individual skill guides. Update .gitignore to include new files. --- .cursor/rules/README.md | 5 ++++ .gitignore | 7 ++++- AGENTS.md | 47 ++++++++++++++++++++++++++++++++ skills/README.md | 15 ++++++++++ skills/code-review/SKILL.md | 31 +++++++++++++++++++++ skills/dev-workflow/SKILL.md | 39 ++++++++++++++++++++++++++ skills/testing/SKILL.md | 31 +++++++++++++++++++++ skills/typescript-style/SKILL.md | 32 ++++++++++++++++++++++ skills/webhook-listener/SKILL.md | 39 ++++++++++++++++++++++++++ 9 files changed, 245 insertions(+), 1 deletion(-) 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/dev-workflow/SKILL.md create mode 100644 skills/testing/SKILL.md create mode 100644 skills/typescript-style/SKILL.md create mode 100644 skills/webhook-listener/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..d107daa --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,5 @@ +# 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. diff --git a/.gitignore b/.gitignore index 0b8f77d..5d87ceb 100755 --- a/.gitignore +++ b/.gitignore @@ -21,4 +21,9 @@ example/logs !.npmignore !dist/** !.talismanrc -!SECURITY.md \ No newline at end of file +!SECURITY.md +!AGENTS.md +!.cursor +!.cursor/** +!skills +!skills/** \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d2cc00f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# Contentstack Webhook Listener – 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/webhook-listener](https://github.com/contentstack/webhook-listener) — npm `@contentstack/webhook-listener` | +| **Purpose:** | TypeScript/Node HTTP server library that receives Contentstack webhooks and invokes a registered callback; part of Contentstack DataSync. | +| **Out of scope (if any):** | Does not implement DataSync Manager, content/asset stores, or CMS configuration—only the webhook HTTP listener surface. | + +## Tech stack (at a glance) + +| Area | Details | +| --- | --- | +| Language | TypeScript (see `tsconfig.json`); Node.js **20+** (see README). | +| Build | `tsc` → output in `dist/`; `package.json` `main` is `./dist`. | +| Tests | Jest, `test/unit/*.test.js`; `npm test` runs with coverage (`jest.config.js`). | +| Lint / coverage | No ESLint/Prettier in repo; coverage via Jest (`coverage/`). | +| Other | Types under `typings/`; runnable example under `example/`. | + +## Commands (quick reference) + +| Command type | Command | +| --- | --- | +| Build | `npm run build-ts` (clean + `tsc`) or `npm run compile` (`tsc` only) | +| Test | `npm test` (runs `pretest` → compile, then Jest with coverage) | +| Lint | Not configured | + +CI / automation: [.github/workflows/check-version-bump.yml](.github/workflows/check-version-bump.yml), [sca-scan.yml](.github/workflows/sca-scan.yml), [policy-scan.yml](.github/workflows/policy-scan.yml), [codeql-analysis.yml](.github/workflows/codeql-analysis.yml), [github-release.yml](.github/workflows/github-release.yml), [issues-jira.yml](.github/workflows/issues-jira.yml). + +## Where the documentation lives: skills + +| Skill | Path | What it covers | +| --- | --- | --- | +| Dev workflow & CI | `skills/dev-workflow/SKILL.md` | Branches, npm scripts, Husky, GitHub Actions, version bumps | +| TypeScript style | `skills/typescript-style/SKILL.md` | `tsconfig`, `src/` vs `example/`, typings, module conventions | +| Package API | `skills/webhook-listener/SKILL.md` | Public exports, config, integration with DataSync | +| Testing | `skills/testing/SKILL.md` | Jest layout, compiled output, coverage | +| Code review | `skills/code-review/SKILL.md` | PR expectations and checklist | + +An index with “when to use” hints is in `skills/README.md`. + +## Using Cursor (optional) + +If you use **Cursor**, `.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..ded2b09 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,15 @@ +# Skills – Contentstack Webhook Listener + +Source of truth for detailed guidance: read **AGENTS.md** at the repo root, then open the skill that matches your task. + +## When to use which skill + +| Skill folder | Use when | +| --- | --- | +| `dev-workflow/` | Building, scripts, CI, releases, Husky hooks | +| `typescript-style/` | TypeScript/`tsconfig`, typings, layout of `src/` vs `example/` | +| `webhook-listener/` | Public API, configuration, how the listener fits DataSync | +| `testing/` | Writing or running Jest tests, coverage | +| `code-review/` | Preparing or reviewing a PR | + +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..e8a5f75 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,31 @@ +--- +name: code-review +description: PR checklist and review expectations for this repository +--- + +# Code review – Contentstack Webhook Listener + +## When to use + +- Opening a PR or reviewing someone else’s changes + +## Instructions + +### Before requesting review + +- **`npm test`** passes (includes compile + Jest coverage). +- **User-visible behavior** changes are reflected in **README** or typings if needed. +- **Release-affecting** changes: **`package.json` version** bumped appropriately; GitHub **version-bump** workflow expectations are met (see [dev-workflow](../dev-workflow/SKILL.md)). + +### Review focus + +- **Correctness**: webhook handling, auth, error paths, and shutdown/reconnect behavior in `src/`. +- **Compatibility**: public exports and config shape for `@contentstack/webhook-listener` consumers. +- **Tests**: new behavior covered under `test/unit/` when it reduces regression risk. +- **Security**: no secrets in code; dependencies align with org policy (SCA/policy workflows). + +### Severity (optional labels) + +- **Blocker**: breaks consumers, security issue, or CI consistently red. +- **Major**: wrong behavior or missing tests for important paths. +- **Minor**: style, docs nits, non-critical refactors. diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..a7e5b77 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,39 @@ +--- +name: dev-workflow +description: Branches, npm scripts, Husky, GitHub Actions, and version/release expectations for this repo +--- + +# Dev workflow – Contentstack Webhook Listener + +## When to use + +- Changing build/test commands or CI +- Cutting releases or bumping `package.json` version +- Working with Git hooks + +## Instructions + +### Scripts (`package.json`) + +- **`npm run build-ts`**: `rimraf dist` then full TypeScript compile (artifact: `dist/`). +- **`npm run compile` / `npm run watch-ts`**: `tsc` with or without watch; no clean in `compile`. +- **`npm test`**: `pretest` runs `compile`; then `jest --coverage`. +- **`npm start`**: runs `node example/` for a local demo. + +### Source layout + +- Implement in **`src/`**; published entry is **`dist/`** (from `"main": "./dist"`). +- Do not edit **`dist/`** by hand—regenerate via compile. + +### Git hooks (Husky) + +- **`npm run pre-commit`**: installs Husky and ensures `.husky/pre-commit` is executable—see repo for current hook behavior. + +### CI (`.github/workflows`) + +- **Version bump** ([check-version-bump.yml](../../.github/workflows/check-version-bump.yml)): on PRs, may require `package.json` version to increase vs latest git tag when certain paths change—confirm patterns match this repo’s layout (`src/`, `test/`, etc.) when troubleshooting. +- **SCA / policy / CodeQL / release / Jira**: see workflow files for triggers and purposes. + +### PR expectations + +- Release-affecting changes typically need a **version bump** in `package.json` per org process; align with the version-bump workflow and [code-review](../code-review/SKILL.md). diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..93f9b4a --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,31 @@ +--- +name: testing +description: Jest tests, layout, coverage, and how they relate to the TypeScript build +--- + +# Testing – Contentstack Webhook Listener + +## When to use + +- Adding or changing unit/integration tests +- Debugging `npm test` or coverage output + +## Instructions + +### Runner and config + +- **Jest** is configured in **`jest.config.js`**: Node environment, `testRegex: "./test/.*.js$"`, coverage under **`coverage/`** (json + html reporters). +- **`npm test`** runs **`pretest`** → `npm run compile` (runs `tsc`), then **`jest --coverage`**. Ensure **`dist/`** is up to date when tests import compiled code. + +### Layout + +- Tests live under **`test/unit/`** (e.g. `*.test.js`). **`test/unit/dummy/`** is ignored by Jest (`testPathIgnorePatterns`). + +### Style and scope + +- Tests are **JavaScript** (`.js`) against the compiled module graph; follow existing files (`index.test.js`, `core.test.js`, `logger.test.js`) for patterns. +- Use **supertest** (devDependency) for HTTP-level assertions where applicable. + +### Credentials and secrets + +- Do not commit real webhook secrets or Basic Auth credentials; use test doubles or env only as needed in CI-safe ways. diff --git a/skills/typescript-style/SKILL.md b/skills/typescript-style/SKILL.md new file mode 100644 index 0000000..b4ddbf2 --- /dev/null +++ b/skills/typescript-style/SKILL.md @@ -0,0 +1,32 @@ +--- +name: typescript-style +description: TypeScript and Node coding conventions for this repo—tsconfig, modules, typings +--- + +# TypeScript style – Contentstack Webhook Listener + +## When to use + +- Editing or adding `.ts` under `src/` or `example/` +- Adjusting compiler options or public type surface (`typings/`) + +## Instructions + +### Compiler (`tsconfig.json`) + +- **`include`**: `src/**/*` only—library code lives under **`src/`**. **`example/`** is not in that include; demos use checked-in **`example/index.js`** with `npm start` (`node example/`). If you change **`example/index.ts`**, update the corresponding JS (or add a dedicated compile step—there is none in `package.json` today). +- **Output**: CommonJS (`"module": "commonjs"`), **`outDir`: `dist`**, **`baseUrl`: `./src`**, **`sourceMap`: true**. +- **`paths`**: resolves `*` via `node_modules/*` and `src/types/*`—follow that layout for new type-only modules. + +### Source style + +- Files use **`'use strict';`** and the existing import style (`import` / `export`); match surrounding modules when adding code. +- Prefer explicit, conservative typing for **public** APIs; internal code may use `any` where the codebase already does—avoid widening surface area without need. + +### Types shipped to consumers + +- Package types are exposed via **`typings/`** (`package.json` `"types": "./typings"`). When you change exported symbols in **`src/`**, update typings (or generated hand-maintained defs) so they stay aligned. + +### Build commands + +- Compile and clean steps are in **[dev-workflow](../dev-workflow/SKILL.md)**—this skill does not repeat them. diff --git a/skills/webhook-listener/SKILL.md b/skills/webhook-listener/SKILL.md new file mode 100644 index 0000000..8aedb9b --- /dev/null +++ b/skills/webhook-listener/SKILL.md @@ -0,0 +1,39 @@ +--- +name: webhook-listener +description: Public API, configuration, and boundaries of the @contentstack/webhook-listener package +--- + +# Webhook listener package – Contentstack Webhook Listener + +## When to use + +- Integrating or extending the HTTP webhook server +- Changing defaults, messages, logging, or webhook routing behavior +- Documenting behavior for DataSync consumers + +## Instructions + +### Entry points + +- **`src/index.ts`** (compiled to `dist/`): primary module consumers import from `@contentstack/webhook-listener`. +- **Public exports** include: `register`, `start`, `shutdown`, `getEventEmitter`, `setConfig`, `getConfig`, `setLogger` (re-exported from logger). Consumers must call **`register(callback)`** before **`start(config, customLogger?)`** or `start` rejects. + +### Core behavior + +- **`src/core.ts`**: creates the HTTP listener (body parsing, basic auth if configured, webhook payload handling). +- **`src/defaults.ts`**: default `listener.port`, `listener.endpoint`, allowed webhook **actions**, and **reconnection** defaults. +- **`src/logger.ts`**: pluggable logger; optional **`customLogger`** passed to `start` must expose `info`, `debug`, `error`, `warn` (see `start` implementation). + +### Configuration + +- User config is merged with defaults (Lodash `merge`). Important keys under `listener`: `port`, `endpoint`, `basic_auth`, `actions`, `reconnection`—see **`src/defaults.ts`** and root **README** table for the subset documented for users. +- **`PORT`** env var overrides `listener.port` when starting the server. + +### Boundaries + +- This package **notifies** a registered function when a valid webhook is received; it does **not** persist content or run DataSync Manager—that lives in other DataSync modules. +- Broader product context: [Contentstack DataSync](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync). + +### Types + +- **`typings/`** and `"types": "./typings"` in `package.json`—keep public types consistent with `src/` exports.