From b0b730f58a4cbe80403fdbde7fdf57fc0d14bbfa Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Fri, 10 Apr 2026 12:59:02 +0530 Subject: [PATCH] Add AGENTS.md, skills README, and individual skill guides. --- .cursor/rules/README.md | 5 ++++ AGENTS.md | 48 ++++++++++++++++++++++++++++++++ skills/README.md | 13 +++++++++ skills/code-review/SKILL.md | 19 +++++++++++++ skills/datasync-website/SKILL.md | 22 +++++++++++++++ skills/dev-workflow/SKILL.md | 20 +++++++++++++ skills/javascript-style/SKILL.md | 18 ++++++++++++ skills/testing/SKILL.md | 18 ++++++++++++ 8 files changed, 163 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-website/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/javascript-style/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..2dafdca --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# Contentstack DataSync Node.js Website 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-nodejs-website-boilerplate](https://github.com/contentstack/datasync-nodejs-website-boilerplate) | +| **Purpose:** | Express app that serves a site from Contentstack DataSync–backed content (filesystem or MongoDB SDK), with Nunjucks views and synced data under the configured content store. | +| **Out of scope (if any):** | Not the DataSync sync pipeline itself (webhook listener, manager); this repo is the website layer on top of synced data. | + +## Tech stack (at a glance) + +| Area | Details | +|------|---------| +| Language | JavaScript (Node.js), CommonJS. Conventions: `skills/javascript-style/SKILL.md`. | +| Build | No compile step; run from source. Install dependencies with npm. | +| Tests | No automated test script in `package.json` today. | +| Lint / coverage | ESLint 5 with `.eslintrc.js` (strict rule set). No coverage tool configured. | +| Other | Express 5, Nunjucks, `@contentstack/datasync-filesystem-sdk` / `@contentstack/datasync-mongodb-sdk`, `contentstack` npm package. Optional: Husky hooks (Snyk, Talisman). | + +## Commands (quick reference) + +| Command type | Command | +|--------------|---------| +| Install deps | `npm install` | +| Run locally | `npm start` (uses `bin/www`; `NODE_ENV` selects `config/.js`, default `development`) | +| Lint | `npx eslint .` | +| Husky setup | `npm run pre-commit` | + +CI and automation: [.github/workflows/check-version-bump.yml](.github/workflows/check-version-bump.yml), [.github/workflows/sca-scan.yml](.github/workflows/sca-scan.yml), [.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 | +|-------|------|----------------| +| Development workflow | `skills/dev-workflow/SKILL.md` | Install, run, hooks, CI expectations, version bumps on PRs | +| JavaScript style | `skills/javascript-style/SKILL.md` | CommonJS patterns, ESLint, matching existing file style | +| DataSync website app | `skills/datasync-website/SKILL.md` | Express entry points, Stack/content store, config and routes | +| Testing | `skills/testing/SKILL.md` | Current test posture; adding tests safely | +| Code review | `skills/code-review/SKILL.md` | PR checklist aligned with this repo | + +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..44cb854 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,13 @@ +# Skills – Contentstack DataSync Node.js Website Boilerplate + +Source of truth for detailed guidance. Read `AGENTS.md` first, then open the skill that matches your task. + +| Skill folder | Use when | +|--------------|----------| +| `dev-workflow` | Local setup, scripts, Husky/Snyk/Talisman, CI and version-bump rules | +| `javascript-style` | CommonJS, ESLint, and staying consistent with nearby code | +| `datasync-website` | Express app structure, DataSync Stack, config, routes, views, synced content paths | +| `testing` | Adding or running automated tests; credentials and fixtures | +| `code-review` | Preparing or reviewing PRs for this repository | + +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..a240aa0 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,19 @@ +--- +name: code-review +description: PR checklist for this boilerplate—version bumps, security hooks, and consistency with Express/DataSync patterns. +--- + +# Code review – Contentstack DataSync Node.js Website Boilerplate + +## When to use + +- Authoring or reviewing a pull request +- Verifying release readiness for a change that touches app code + +## Instructions + +- **Version bump:** If the PR changes release-affecting files (paths are defined in `.github/workflows/check-version-bump.yml`), `package.json` version must increase and exceed the latest tag. +- **Security / hooks:** Contributors with Husky enabled should pass Snyk and Talisman locally unless bypass is justified; align dependency changes with `.github/workflows/sca-scan.yml` expectations where relevant. +- **Code quality:** ESLint should pass on touched files; new code should match existing patterns in the same directory (CommonJS, existing error handling). +- **Product behavior:** DataSync connection and routes should remain coherent—config changes should be documented for operators (ports, `contentStore`, locales). +- **Ownership:** See `CODEOWNERS` for required reviewers. diff --git a/skills/datasync-website/SKILL.md b/skills/datasync-website/SKILL.md new file mode 100644 index 0000000..4ef3968 --- /dev/null +++ b/skills/datasync-website/SKILL.md @@ -0,0 +1,22 @@ +--- +name: datasync-website +description: Express entry points, Contentstack DataSync Stack, environment config, routes, and where synced content lives in this boilerplate. +--- + +# DataSync website app – Contentstack DataSync Node.js Website Boilerplate + +## When to use + +- Adding or changing pages, routes, middleware, or views +- Connecting or switching DataSync content stores (filesystem vs MongoDB SDK) +- Locating API keys, tokens, ports, or locale settings + +## Instructions + +- **HTTP entry:** `bin/www` creates the server from `app.js` (`module.exports = app`). `app.js` registers Nunjucks (`views/`), static assets under `/static` from `public/`, rate limiting, JSON/urlencoded parsers, and `./routes`. +- **Contentstack Stack:** `models/contentstack.js` uses `require(config.sdk)` to load `Contentstack`, then `Contentstack.Stack(config)` and `Stack.connect(config.contentStore)`. The `sdk` string in `config/.js` must match an installed module name. Export is the connected `Stack` for use in routes. +- **Environment config:** Edit `config/development.js`, `config/staging.js`, or `config/production.js` for `contentstack.apikey`, `deliveryToken`, `contentStore` (e.g. `baseDir: './_contents'` for filesystem), `locales`, and `port`. Do not commit real secrets; use local overrides or secret injection patterns your team agrees on. +- **Routing:** `routes/index.js` mounts `middlewares` and `routes/home.js`. Locale and partials live under `middlewares/` (`locales.js`, `partials.js`). +- **Synced content:** Default filesystem layout uses `_contents` under the project (see `contentStore.baseDir` in config). `schemaNentries/` holds schema-related assets for the sample—treat as part of release-affecting paths when the version-bump workflow applies. +- **Dependencies:** See `package.json` for `@contentstack/datasync-filesystem-sdk`, `@contentstack/datasync-mongodb-sdk`, `contentstack`, `express`, `nunjucks`, etc. +- **Product docs:** [Contentstack DataSync](https://www.contentstack.com/docs/guide/synchronization/contentstack-datasync). diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..a07b4d8 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,20 @@ +--- +name: dev-workflow +description: Local setup, npm scripts, Husky and security hooks, CI expectations, and PR version-bump rules for this boilerplate. +--- + +# Development workflow – Contentstack DataSync Node.js Website Boilerplate + +## When to use + +- Setting up the project or onboarding someone new +- Changing how commits or CI behave +- Opening a PR that touches application code (version bump may be required) + +## Instructions + +- **Dependencies:** Run `npm install` at the repo root. There is no separate build or bundle step. +- **Run the server:** `npm start` executes `node ./bin/www`. Port and stack config come from `config/.js` (default `development` if `NODE_ENV` is unset). +- **Lint:** `npx eslint .` uses `.eslintrc.js`. There is no `lint` npm script; invoke ESLint directly. +- **Husky:** `npm run pre-commit` installs Husky and marks `.husky/pre-commit` executable. The pre-commit hook runs **Snyk** (`snyk test --all-projects`) and **Talisman**; both CLIs must be installed locally. Set `SKIP_HOOK=1` to bypass (document why if you use this in automation). +- **PR version bump:** [.github/workflows/check-version-bump.yml](../../.github/workflows/check-version-bump.yml) requires `package.json` to change when certain paths change (e.g. `app.js`, `bin/`, `config/`, `middlewares/`, `models/`, `public/`, `routes/`, `views/`, `schemaNentries/`) and the new version must be greater than the latest git tag. Doc-only or `.github`-only changes skip the check per that workflow. diff --git a/skills/javascript-style/SKILL.md b/skills/javascript-style/SKILL.md new file mode 100644 index 0000000..e24dc5f --- /dev/null +++ b/skills/javascript-style/SKILL.md @@ -0,0 +1,18 @@ +--- +name: javascript-style +description: JavaScript and CommonJS conventions, ESLint usage, and matching existing file style in this Node.js boilerplate. +--- + +# JavaScript style – Contentstack DataSync Node.js Website Boilerplate + +## When to use + +- Writing or editing `.js` files under `app.js`, `bin/`, `config/`, `middlewares/`, `models/`, `routes/`, or `public/js/` +- Choosing `var` vs `const`/`let` or module layout in a file that mixes styles + +## Instructions + +- **Modules:** Use CommonJS (`require`, `module.exports`) consistently with the file you are editing. New code in files that already use `const`/`let` should use the same; older files under `config/` and `models/` often use `var`—do not rewrite wholesale for style alone. +- **Lint:** Run `npx eslint .`; rules live in `.eslintrc.js` (extends `eslint:recommended` with many explicit rules, including single quotes and JSDoc-related rules where enabled). +- **Paths:** Prefer `path.join(__dirname, ...)` for filesystem paths when the surrounding code does. +- **Formatting:** `.jsbeautifyrc` applies to JS/HTML formatting where your editor uses it; keep line length and indentation consistent with existing files. diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..d33986d --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,18 @@ +--- +name: testing +description: Automated testing posture for this repo (currently minimal) and how to add tests without leaking credentials. +--- + +# Testing – Contentstack DataSync Node.js Website Boilerplate + +## When to use + +- Adding unit, integration, or E2E tests +- Deciding where test files live and how CI should run them +- Handling API keys and tokens in test fixtures + +## Instructions + +- **Today:** `package.json` has no `test` script and the repository does not ship a standard `test/` tree. Validate changes by running the app (`npm start`) and ESLint (`npx eslint .`) as appropriate. +- **Adding a runner:** Prefer adding a `test` script (e.g. Node’s built-in runner, or Mocha/Jest if the team standardizes) and document the command in `AGENTS.md` when it lands. Keep test-only changes in paths that your CI treats as non–release-affecting where applicable (see version-bump workflow). +- **Credentials:** Never commit real Contentstack keys or tokens. Use environment variables or ignored local config for integration tests; mirror patterns from `config/*.js` with placeholders only in committed files.