From 125f18f1f9e6932059ecb3bab5d7bc15676c10c6 Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Fri, 10 Apr 2026 12:55:51 +0530 Subject: [PATCH] Add AGENTS.md, skills README, and individual skill guides. --- .cursor/rules/README.md | 5 +++ AGENTS.md | 49 ++++++++++++++++++++++++++++ skills/README.md | 13 ++++++++ skills/code-review/SKILL.md | 18 ++++++++++ skills/datasync-boilerplate/SKILL.md | 19 +++++++++++ skills/dev-workflow/SKILL.md | 18 ++++++++++ skills/javascript-node/SKILL.md | 17 ++++++++++ skills/testing/SKILL.md | 18 ++++++++++ 8 files changed, 157 insertions(+) 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/datasync-boilerplate/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/javascript-node/SKILL.md create mode 100644 skills/testing/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..f5c1f87 --- /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/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..294040a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,49 @@ +# Contentstack DataSync Boilerplate – 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/datasync-boilerplate](https://github.com/contentstack/datasync-boilerplate) | +| **Purpose:** | Skeleton app to run Contentstack DataSync: webhook listener, asset/content stores (filesystem or MongoDB), and `@contentstack/datasync-manager` wiring. | +| **Out of scope (if any):** | Not a published npm library; product behavior lives in Contentstack DataSync packages (`package.json` dependencies). | + +## Tech stack (at a glance) + +| Area | Details | +|------|---------| +| Language | JavaScript (CommonJS), Node.js **20+** | +| Build | npm; entry `index.js`; config under `config/` | +| Tests | No automated test runner or `test` script in this repo | +| Lint / coverage | ESLint (`.eslintrc.js`); no coverage tooling configured | +| Runtime | Long-running DataSync process; `NODE_ENV` selects `config/.js` when present | + +## Commands (quick reference) + +| Command type | Command | +|--------------|---------| +| Install | `npm install` | +| Run (clean + start) | `npm start` | +| Run without clean | `npm run continue` | +| Clean synced output | `npm run clean` | +| Lint | `npx eslint .` | + +**CI:** [`.github/workflows/sca-scan.yml`](.github/workflows/sca-scan.yml) (Snyk), [`.github/workflows/policy-scan.yml`](.github/workflows/policy-scan.yml), [`.github/workflows/codeql-analysis.yml`](.github/workflows/codeql-analysis.yml), [`.github/workflows/issues-jira.yml`](.github/workflows/issues-jira.yml). + +## Where the documentation lives: skills + +| Skill | Path | What it covers | +|-------|------|----------------| +| Dev workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI touchpoints, npm scripts | +| DataSync app | [`skills/datasync-boilerplate/SKILL.md`](skills/datasync-boilerplate/SKILL.md) | Entry flow, config, DataSync modules | +| JavaScript / Node | [`skills/javascript-node/SKILL.md`](skills/javascript-node/SKILL.md) | Linting and code style for this repo | +| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | How verification works here (no test suite) | +| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR expectations | + +An index with “when to use” hints is in [`skills/README.md`](skills/README.md). + +## Using Cursor (optional) + +If you use **Cursor**, [`.cursor/rules/README.md`](.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..357c845 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,13 @@ +# Skills – Contentstack DataSync Boilerplate + +Source of truth for detailed guidance. Read [`AGENTS.md`](../AGENTS.md) first, then open the skill that matches your task. + +| Skill folder | Use when | +|--------------|----------| +| [`dev-workflow`](dev-workflow/SKILL.md) | CI, npm scripts, or repo workflow | +| [`datasync-boilerplate`](datasync-boilerplate/SKILL.md) | `index.js`, `config/`, DataSync or Contentstack integration | +| [`javascript-node`](javascript-node/SKILL.md) | ESLint, formatting, or JS/Node conventions | +| [`testing`](testing/SKILL.md) | Verification, credentials, or adding tests | +| [`code-review`](code-review/SKILL.md) | Opening 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..653ea8e --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,18 @@ +--- +name: code-review +description: Use when authoring or reviewing pull requests for this repository. +--- + +# Code review – Contentstack DataSync Boilerplate + +## When to use + +- Preparing a PR or reviewing someone else’s changes +- Ensuring security and operational expectations are met + +## Instructions + +- **Scope**: Keep changes focused; this repo is a thin composition layer over Contentstack DataSync packages—avoid unrelated refactors. +- **Quality**: Run `npx eslint .`; ensure config edits don’t encourage committing secrets; document user-visible behavior changes in the PR description. +- **CI**: PRs trigger Snyk, policy, CodeQL, and related workflows—fix or explain new findings. +- **Severity (optional)**: **Blocker** — broken startup, leaked credentials, unsafe defaults; **Major** — incorrect DataSync wiring or config contract; **Minor** — style, comments, non-user-facing cleanup. diff --git a/skills/datasync-boilerplate/SKILL.md b/skills/datasync-boilerplate/SKILL.md new file mode 100644 index 0000000..c618917 --- /dev/null +++ b/skills/datasync-boilerplate/SKILL.md @@ -0,0 +1,19 @@ +--- +name: datasync-boilerplate +description: Use for DataSync wiring—index.js, config, listener, asset/content stores, and Contentstack settings. +--- + +# DataSync boilerplate app – Contentstack DataSync Boilerplate + +## When to use + +- Editing startup, checkpoint, or plugin behavior +- Choosing or configuring content store, asset store, or listener modules +- Documenting or fixing integration with Contentstack delivery API / webhooks + +## Instructions + +- **Entry point**: `index.js` loads `config/all.js`, merges `config/.js` when that file exists (else `config/development.js`), optionally reads a checkpoint file for `sync_token`, then wires `datasyncManager` with listener, asset store, and content store from **module paths in config** (`listenerModule`, `assetStoreModule`, `contentStoreModule`). +- **Configuration**: Put stack credentials and module names in `config/`—see product docs in root [`README.md`](../../README.md) for `apiKey`, delivery token, `host`, and webhook setup (ngrok, `/notify`, publish actions). +- **Published packages**: Behavior is implemented in `@contentstack/datasync-manager`, `@contentstack/webhook-listener`, and the filesystem/MongoDB store packages listed in `package.json`; this repo only composes them. +- **Plugins**: Custom plugins live under `plugins/` per patterns already described in `config/all.js`. diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..e29f7e6 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,18 @@ +--- +name: dev-workflow +description: Use for npm scripts, GitHub Actions, branching, and day-to-day repo workflow. +--- + +# Dev workflow – Contentstack DataSync Boilerplate + +## When to use + +- Changing or documenting how the app is run or cleaned +- Touching CI or security scanning behavior +- Aligning with how PRs are validated in this repository + +## Instructions + +- **Scripts** (from `package.json`): `npm start` runs `clean` then `node index.js`; `npm run continue` runs `index.js` without cleaning; `npm run clean` runs `clean.js`. +- **CI** (`.github/workflows/`): SCA via Snyk on PRs; policy checks (e.g. `SECURITY.md`, license) for public repos; CodeQL on PRs; Jira integration for issues. No dedicated workflow runs `npm test` (there is no test script). +- **Dependencies**: Managed with npm; `overrides` in `package.json` pins `lodash` for supply-chain consistency—coordinate changes with security tooling expectations. diff --git a/skills/javascript-node/SKILL.md b/skills/javascript-node/SKILL.md new file mode 100644 index 0000000..dc35410 --- /dev/null +++ b/skills/javascript-node/SKILL.md @@ -0,0 +1,17 @@ +--- +name: javascript-node +description: Use for ESLint, formatting, and JavaScript/Node conventions in this repository. +--- + +# JavaScript / Node – Contentstack DataSync Boilerplate + +## When to use + +- Editing `.eslintrc.js` or fixing lint findings +- Keeping new files consistent with existing CommonJS style + +## Instructions + +- **Lint**: Run `npx eslint .` from the repo root (no `lint` npm script). Config is [`.eslintrc.js`](../../.eslintrc.js): `eslint:recommended` plus indent, linebreak, quotes, and `semi` rules—match ESLint output and the style of files you edit. +- **Modules**: Use CommonJS (`require` / `module.exports`) to match `index.js`, `config/`, and dependencies. +- **Environment**: Target Node; match `ecmaVersion` / parser options to `.eslintrc.js` when changing tooling. diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..cebd328 --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,18 @@ +--- +name: testing +description: Use for verification strategy, secrets handling, and any future automated tests. +--- + +# Testing – Contentstack DataSync Boilerplate + +## When to use + +- Checking changes before merge without a dedicated test suite +- Deciding how to handle API tokens, webhooks, or local tunnels + +## Instructions + +- **Current state**: There is no `npm test` script or standard test directory. Rely on `npx eslint .`, manual runs (`npm start` / `npm run continue`) against non-production stacks, and CI security scans on PRs. +- **Secrets**: Never commit real `apiKey`, delivery tokens, or checkpoint files with live tokens. Use environment-appropriate `config/*.js` or secure injection per team practice. +- **Local integration**: Webhooks require a public URL (e.g. ngrok) and Contentstack webhook configuration—see root [`README.md`](../../README.md) prerequisites. +- **Adding tests**: If introducing a runner, add scripts to `package.json` and document them in [`AGENTS.md`](../../AGENTS.md) and [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md).