Add AGENTS.md, skills README, and individual skill guides. Update .g…

.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.

.gitignore

@@ -21,4 +21,9 @@ example/logs
 !.npmignore
 !dist/**
 !.talismanrc
-!SECURITY.md
+!SECURITY.md
+!AGENTS.md
+!.cursor
+!.cursor/**
+!skills
+!skills/**

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.

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`).

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.

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).

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.

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.

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.