create-standards 1.0.0

package/src/install.js

@@ -0,0 +1,77 @@
+const fs = require('fs');
+const path = require('path');
+
+// selectedIdeFolders empty = install every IDE pack for the stack
+function copyStandardsIntoProject({
+  stack,
+  selectedIdeFolders = [],
+  targetFolder,
+  force = false,
+  dryRun = false,
+  includeSharedReference = true,
+}) {
+  const target = path.resolve(targetFolder);
+
+  const idePacksToCopy =
+    selectedIdeFolders.length === 0
+      ? stack.idePacks
+      : stack.idePacks.filter((pack) => selectedIdeFolders.includes(pack.ideFolder));
+
+  if (
+    selectedIdeFolders.length > 0 &&
+    idePacksToCopy.length !== selectedIdeFolders.length
+  ) {
+    const found = new Set(idePacksToCopy.map((pack) => pack.ideFolder));
+    const missing = selectedIdeFolders.filter((name) => !found.has(name));
+    const availableFlags = stack.idePacks.flatMap((pack) =>
+      pack.flags.map((flag) => `--${flag}`)
+    );
+    throw new Error(
+      `IDE pack(s) not found for stack "${stack.shortName}": ${missing.join(', ')}.\n` +
+        `Available flags: ${availableFlags.length ? availableFlags.join(', ') : '(none)'}`
+    );
+  }
+
+  if (
+    idePacksToCopy.length === 0 &&
+    !(includeSharedReference && stack.hasSharedReference)
+  ) {
+    throw new Error(`Nothing to install for stack "${stack.shortName}".`);
+  }
+
+  const copyPlan = idePacksToCopy.map((pack) => ({
+    from: pack.sourcePath,
+    to: path.join(target, pack.installAs),
+  }));
+
+  if (includeSharedReference && stack.hasSharedReference && stack.sharedReferencePath) {
+    copyPlan.push({
+      from: stack.sharedReferencePath,
+      to: path.join(target, 'shared-reference'),
+    });
+  }
+
+  const alreadyExists = copyPlan.filter((item) => fs.existsSync(item.to));
+  if (alreadyExists.length > 0 && !force) {
+    const list = alreadyExists.map((item) => `  - ${item.to}`).join('\n');
+    throw new Error(
+      `Destination already exists (use --force to overwrite):\n${list}`
+    );
+  }
+
+  const createdPaths = [];
+
+  for (const item of copyPlan) {
+    if (dryRun) {
+      createdPaths.push(item.to);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(item.to), { recursive: true });
+    fs.cpSync(item.from, item.to, { recursive: true, force: true });
+    createdPaths.push(item.to);
+  }
+
+  return { copyPlan, createdPaths };
+}
+
+module.exports = { copyStandardsIntoProject };

package/standards/nodejs-express-standards/README.md

@@ -0,0 +1,59 @@
+# Node.js + Express Standards — Skills Pack
+
+Senior-architect-level standards for Node.js/Express backend work, packaged for three AI coding
+tools. Drop the relevant folder's contents into your project (paths already match what each tool
+expects), and the standards get applied automatically or on request — you don't have to retype
+them into every prompt.
+
+## What's inside
+
+- **`shared-reference/`** — the master content (8 topic files). This is the source of truth;
+  the other three folders are just this content repackaged into each tool's native format.
+- **`cursor/.cursor/rules/`** — Cursor `.mdc` rule files.
+- **`claude-code/.claude/skills/nodejs-express-standards/`** — a Claude Code Skill (`SKILL.md` +
+  `references/`).
+- **`antigravity/.agents/skills/nodejs-express-standards/`** — an Antigravity Skill, same
+  `SKILL.md` format as Claude Code (the format is now a shared open standard across tools).
+
+## How to install per tool
+
+### Cursor
+Copy the `cursor/.cursor/` folder into your project root, so you end up with
+`your-project/.cursor/rules/*.mdc`. Cursor loads these automatically:
+- `00-index.mdc`, `04-security.mdc`, `08-code-style.mdc` are **always applied**.
+- The rest **auto-attach** based on the file glob you're editing (e.g. editing anything in
+  `src/models/**` pulls in the database/model rules automatically).
+- `07-new-component-checklist.mdc` is manual-only — pull it in explicitly by typing
+  `@07-new-component-checklist` in chat before asking Cursor to scaffold something new.
+
+### Claude Code
+Copy the `claude-code/.claude/` folder into your project root (or into `~/.claude/` for a global,
+cross-project skill), so you end up with
+`your-project/.claude/skills/nodejs-express-standards/SKILL.md`. Claude Code discovers it
+automatically and loads it whenever a task involves Express routes, controllers, services,
+models, or migrations. You can also invoke it explicitly by name in a prompt, e.g. "follow the
+nodejs-express-standards skill."
+
+### Antigravity
+Copy the `antigravity/.agents/` folder into your project root (or into
+`~/.gemini/config/skills/` for a global skill), so you end up with
+`your-project/.agents/skills/nodejs-express-standards/SKILL.md`. Same format and behavior as the
+Claude Code skill above — Antigravity semantically triggers it when relevant, or you can ask
+for it by name / run `/skills` to confirm it's loaded.
+
+## Editing the standards
+
+Treat `shared-reference/` as the source of truth. If you update a rule there, copy the change into
+the corresponding `cursor/*.mdc` file and into both `references/` copies under `claude-code/` and
+`antigravity/` so all three tools stay in sync.
+
+## Topics covered
+
+1. Project structure & layered architecture
+2. REST API design (routing, status codes, response envelope, pagination)
+3. Error handling & request validation
+4. Security defaults (auth, secrets, rate limiting, sanitization)
+5. Database & model conventions (repository pattern, migrations, indexing)
+6. Testing standards (unit, integration, coverage gate)
+7. Checklist to run before scaffolding any new model/route/component
+8. General code style, linting, logging, and commit conventions

package/standards/nodejs-express-standards/antigravity/.agents/skills/nodejs-express-standards/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: nodejs-express-standards
+description: Senior-architect-level standards for Node.js + Express backend work — project structure, REST API design, error handling, security, database/model conventions, and testing. Use this skill whenever creating, editing, or reviewing any Express route, controller, service, repository, model, or migration, or before scaffolding any new backend component/endpoint, even if the user doesn't explicitly ask for "standards" or "best practices."
+---
+
+# Node.js + Express Standards
+
+Layered architecture is mandatory for this stack: `route -> validator -> controller -> service -> repository -> model`.
+Before writing or modifying backend code, apply the relevant reference file(s) below. Don't wait to be asked —
+if the task touches routes, controllers, services, models, or migrations, these standards apply by default.
+
+## When to consult which reference
+
+| Task involves...                          | Read                                          |
+|--------------------------------------------|------------------------------------------------|
+| New file/folder, overall app layout        | `references/01-project-structure.md`           |
+| Any route or controller                    | `references/02-api-design-standards.md`        |
+| Error handling, validation middleware      | `references/03-error-handling-validation.md`   |
+| Anything auth/security related            | `references/04-security-standards.md`          |
+| Models, repositories, migrations           | `references/05-database-model-standards.md`    |
+| Writing or reviewing tests                 | `references/06-testing-standards.md`           |
+| Scaffolding any new model/route/component  | `references/07-new-component-checklist.md`     |
+| Lint/format/logging/commit conventions     | `references/08-code-style-general.md`          |
+
+## Core non-negotiables (always apply)
+
+- No business logic in routes; controllers never query the DB directly.
+- Every request is validated at the boundary before it reaches the controller body.
+- Every error flows through the centralized error-handling middleware — no scattered bare `try/catch`.
+- Every new endpoint ships with an updated OpenAPI/Swagger doc and at least a happy-path + failure-path test.
+- Security defaults (helmet, rate limiting, input sanitization, no hardcoded secrets) apply to every service, not opt-in.
+
+## Workflow for a new feature
+
+1. Read `07-new-component-checklist.md` first — run through it before writing any code.
+2. Check `01-project-structure.md` to place the new files in the correct layer/folder.
+3. Design the endpoint per `02-api-design-standards.md` (path, verb, status codes, response envelope).
+4. Write the validation schema, then the controller/service/repository, applying `03`, `04`, and `05` as relevant.
+5. Write tests per `06-testing-standards.md`.
+6. Run lint/format per `08-code-style-general.md` before considering the task done.

package/standards/nodejs-express-standards/antigravity/.agents/skills/nodejs-express-standards/references/01-project-structure.md

@@ -0,0 +1,33 @@
+# Project Structure Standards (Node.js + Express)
+
+## Standard folder layout
+
+```
+src/
+  config/         # env loading + validation, db config, third-party config
+  routes/         # express.Router() definitions only — no logic
+  controllers/    # HTTP layer: parse req, call service, shape res
+  services/       # business logic, orchestration — framework-agnostic
+  repositories/    # data access layer (DB queries), one per model/table
+  models/         # ORM/schema definitions
+  validators/     # request schema validation (zod/joi/celebrate)
+  middlewares/    # auth, error handler, rate limit, logging
+  utils/          # pure helper functions
+  jobs/           # cron / queue workers
+  events/         # event emitters / pub-sub handlers
+  constants/       # enums, error codes, status strings
+app.js            # express app assembly (middleware + routes), NO app.listen()
+server.js         # imports app.js, calls app.listen(), handles graceful shutdown
+tests/
+  unit/
+  integration/
+```
+
+## Rules
+
+- **Layered architecture is mandatory**: `route → controller → service → repository → model`. A controller never talks to the DB directly, and a service never touches `req`/`res`.
+- Split `app.js` (the Express app object) from `server.js` (the process/listener) so the app can be imported into supertest without binding a port.
+- Config must be loaded and **validated at startup** (e.g. with `envalid`, `zod`, or `joi`) — fail fast if a required env var is missing, don't let it fail later at runtime.
+- No business logic in `routes/`. Routes only wire `path + method → middleware chain → controller`.
+- One repository per aggregate/model. Repositories are the only files allowed to import the ORM/query builder directly.
+- Barrel files (`index.js`) per folder are optional but if used, keep them to re-exports only — no logic.

package/standards/nodejs-express-standards/antigravity/.agents/skills/nodejs-express-standards/references/02-api-design-standards.md

@@ -0,0 +1,41 @@
+# REST API Design Standards
+
+## Resource naming & routing
+
+- Use plural nouns for resources: `/users`, `/orders`, not `/user` or `/getUsers`.
+- Nest resources only one level deep: `/orders/:orderId/items`, avoid deeper nesting.
+- Version the API from day one: `/api/v1/...`. Never ship an unversioned public API.
+- Use HTTP verbs correctly, never verbs in the path:
+
+| Verb   | Path              | Action                  |
+|--------|-------------------|-------------------------|
+| GET    | /users            | list                    |
+| GET    | /users/:id        | read one                |
+| POST   | /users            | create                  |
+| PUT    | /users/:id        | full replace            |
+| PATCH  | /users/:id        | partial update          |
+| DELETE | /users/:id        | delete                  |
+
+## Status codes
+
+- `200` OK (read/update), `201` Created (with `Location` header), `204` No Content (delete/no body).
+- `400` validation error, `401` unauthenticated, `403` unauthorized, `404` not found, `409` conflict, `422` semantically invalid, `429` rate-limited, `500` unhandled server error.
+- Never return `200` with an error payload — the HTTP status must reflect the outcome.
+
+## Response envelope (consistent across all endpoints)
+
+```json
+// success
+{ "success": true, "data": { }, "meta": { "page": 1, "totalPages": 4 } }
+
+// error
+{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "email is required", "details": [] } }
+```
+
+## Other requirements
+
+- **Pagination** is required on every list endpoint (`?page=&limit=` or cursor-based `?cursor=`) — never return an unbounded array.
+- **Filtering/sorting** via query params (`?status=active&sort=-createdAt`), validated against an allow-list of fields (never pass raw query straight into a DB `WHERE`/`ORDER BY`).
+- **Idempotency**: `PUT`/`DELETE` must be idempotent. For `POST` on payment/order-creation style endpoints, support an `Idempotency-Key` header.
+- **Document every endpoint** with OpenAPI/Swagger (`swagger-jsdoc` or a maintained `openapi.yaml`) — a new endpoint is not done until it's documented.
+- Never expose internal DB IDs/structure verbatim if it leaks implementation details; DTOs/serializers shape what the client sees.

package/standards/nodejs-express-standards/antigravity/.agents/skills/nodejs-express-standards/references/03-error-handling-validation.md

@@ -0,0 +1,27 @@
+# Error Handling & Validation Standards
+
+## Custom error class
+
+```js
+class AppError extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.isOperational = true; // distinguishes expected errors from bugs
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+```
+
+## Rules
+
+- **Never use raw `try/catch` scattered in controllers.** Wrap async route handlers with a `catchAsync`/`asyncHandler` utility that forwards rejected promises to `next(err)`.
+- **One centralized error-handling middleware**, registered last in `app.js`, that:
+  - Logs the error (with request id / correlation id).
+  - Returns the standard error envelope.
+  - Hides stack traces and internal messages in production (`isOperational === false` → generic "Something went wrong").
+- **Validate every request at the boundary**, before it reaches the controller body — use a schema library (`zod`, `joi`, or `celebrate`) as route middleware, not manual `if` checks sprinkled through the controller.
+- Validation errors return `400`/`422` with a `details` array listing each failing field.
+- Distinguish **operational errors** (bad input, not found, auth failure — expected, safe to show a message) from **programmer errors** (bugs — log, alert, return generic 500).
+- Async code must never produce an unhandled promise rejection — catch at the boundary, always.

package/standards/nodejs-express-standards/antigravity/.agents/skills/nodejs-express-standards/references/04-security-standards.md

@@ -0,0 +1,17 @@
+# Security Standards
+
+Apply all of these by default on every new Express service — don't wait to be asked:
+
+- **Helmet**: `app.use(helmet())` for secure headers (CSP, HSTS, X-Frame-Options, etc.) — configure CSP explicitly rather than leaving it wide open.
+- **CORS**: explicit origin allow-list via the `cors` package, never `origin: '*'` on an authenticated API.
+- **Rate limiting**: `express-rate-limit` (or a Redis-backed store in multi-instance deployments) on all public endpoints, stricter limits on auth endpoints (`/login`, `/register`, `/forgot-password`).
+- **Input sanitization**: strip/escape untrusted input against NoSQL/SQL injection and XSS (`express-mongo-sanitize`, parameterized queries/ORM query builders — never string-concatenate SQL).
+- **AuthN/AuthZ**:
+  - Short-lived JWT access tokens + refresh token rotation, or session cookies with `httpOnly`, `secure`, `sameSite`.
+  - Passwords hashed with `bcrypt`/`argon2`, never stored or logged in plaintext.
+  - Role/permission checks live in middleware, applied per-route, not scattered inside controller `if` statements.
+- **Secrets**: only via environment variables / a secrets manager. Never commit `.env`, never hardcode API keys or DB credentials.
+- **Request limits**: `express.json({ limit: '10kb' })` (or an appropriate cap) to prevent payload-based DoS.
+- **Dependency hygiene**: run `npm audit` (or Snyk/Dependabot) as part of CI; block merges on high/critical vulnerabilities.
+- **HTTPS only** in production; redirect HTTP → HTTPS at the load balancer/proxy layer.
+- Never leak stack traces, internal file paths, or library versions in API responses or headers.

package/standards/nodejs-express-standards/antigravity/.agents/skills/nodejs-express-standards/references/05-database-model-standards.md

@@ -0,0 +1,10 @@
+# Database & Model Standards
+
+- **Repository pattern**: all DB queries live in `repositories/`, never directly inside services or controllers. Services call repository methods; they don't know it's Postgres/Mongo/etc.
+- **Migrations are mandatory** for schema changes (e.g. `knex`, `sequelize-cli`, `prisma migrate`, `typeorm migration`). Never use `sync({ alter: true })` or manual schema edits against a shared/production DB.
+- Every table/collection gets `createdAt` and `updatedAt` timestamps by default.
+- Prefer **soft deletes** (`deletedAt` column + default query scope excluding it) over hard deletes for user-facing/business-critical records; hard-delete only where there's a clear compliance/retention reason.
+- Index every foreign key and every column used in a frequent `WHERE`/`sort` — check the query plan (`EXPLAIN`) for anything added to a hot path.
+- **Transactions** wrap any operation that writes to more than one table/collection, so a partial failure can't leave data inconsistent.
+- Naming: `snake_case` for DB columns/tables, `camelCase` in JS — handle the mapping in the ORM config, don't hand-convert per query.
+- Never return raw ORM model instances straight from a controller — map to a DTO/serializer so DB shape and API shape can evolve independently.

package/standards/nodejs-express-standards/antigravity/.agents/skills/nodejs-express-standards/references/06-testing-standards.md

@@ -0,0 +1,10 @@
+# Testing Standards
+
+- **Unit tests** (Jest/Vitest) for every service function — mock the repository layer, test business logic in isolation.
+- **Integration tests** (Supertest against the exported `app.js`, not a running server) for every route — exercise the real middleware chain, validation, and error handler.
+- Use a dedicated test database (or transactional rollback per test) — tests must never touch dev/prod data, and must be safely re-runnable/parallelizable.
+- Follow **Arrange–Act–Assert** structure in every test; one logical assertion focus per test case.
+- Mock external services/network calls (payment providers, email, third-party APIs) — tests must not depend on network access.
+- Minimum coverage threshold: **80%** on services and controllers, enforced in CI (fail the build below threshold).
+- Every new endpoint or model ships with at least: one happy-path integration test, one validation-failure test, one auth-failure test (if protected).
+- CI must run lint → unit → integration → coverage gate, in that order, before a PR can merge.

package/standards/nodejs-express-standards/antigravity/.agents/skills/nodejs-express-standards/references/07-new-component-checklist.md

@@ -0,0 +1,16 @@
+# Checklist: Before Creating Any New Model, Route, or Component
+
+Run through this before writing code for a new feature — this is what a senior architect reviews for in a PR:
+
+1. **Check for an existing pattern first.** Look at a similar existing model/route/service in the codebase and follow its shape — don't introduce a new pattern for something that already has one.
+2. **Confirm the layer boundaries**: route (wiring only) → validator (schema) → controller (HTTP glue) → service (logic) → repository (DB) → model. No shortcuts (e.g. controller querying the DB directly).
+3. **Write the validation schema** for every input (body/params/query) before writing the controller.
+4. **Define the DB migration** (not a live schema edit) if a new table/column is needed, with indexes on any FK/frequently-queried column.
+5. **Handle errors explicitly**: use `AppError`/`catchAsync`, no bare `try/catch` with silent `console.log`.
+6. **Add authorization checks** if the resource is user/role-scoped — don't rely on the client to hide UI for unauthorized actions.
+7. **Write tests**: at minimum one integration test (happy path) and one validation/error-path test.
+8. **Update API documentation** (OpenAPI/Swagger) for any new or changed endpoint.
+9. **Run lint + format** (ESLint + Prettier) — no new lint warnings introduced.
+10. **No secrets, no hardcoded config** — anything environment-specific goes through `config/`.
+11. **Consider pagination/rate-limits** if it's a list endpoint or public-facing.
+12. Keep the diff focused — one feature/concern per PR/commit.

package/standards/nodejs-express-standards/antigravity/.agents/skills/nodejs-express-standards/references/08-code-style-general.md

@@ -0,0 +1,9 @@
+# General Code Style Standards
+
+- ESLint (Airbnb-base or `eslint-config-standard`) + Prettier, enforced via a pre-commit hook (`husky` + `lint-staged`) and in CI — not just "run it locally sometimes."
+- `async/await` everywhere; no mixing with raw `.then()` chains or callback-style APIs in new code.
+- No `console.log` in committed code — use a structured logger (`pino` or `winston`) with log levels, and include a request/correlation id in every log line.
+- One export/responsibility per file; avoid god-files that mix routing, business logic, and DB access.
+- Environment-based configuration only (`dotenv` + a validated config schema) — never branch behavior on `NODE_ENV` scattered through business logic; centralize environment differences in `config/`.
+- Commit messages follow Conventional Commits (`feat:`, `fix:`, `refactor:`, `test:`, `chore:`) so history and changelogs stay meaningful.
+- Prefer explicit, readable code over clever one-liners — this codebase is read far more often than it's written.

package/standards/nodejs-express-standards/claude-code/.claude/skills/nodejs-express-standards/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: nodejs-express-standards
+description: Senior-architect-level standards for Node.js + Express backend work — project structure, REST API design, error handling, security, database/model conventions, and testing. Use this skill whenever creating, editing, or reviewing any Express route, controller, service, repository, model, or migration, or before scaffolding any new backend component/endpoint, even if the user doesn't explicitly ask for "standards" or "best practices."
+---
+
+# Node.js + Express Standards
+
+Layered architecture is mandatory for this stack: `route -> validator -> controller -> service -> repository -> model`.
+Before writing or modifying backend code, apply the relevant reference file(s) below. Don't wait to be asked —
+if the task touches routes, controllers, services, models, or migrations, these standards apply by default.
+
+## When to consult which reference
+
+| Task involves...                          | Read                                          |
+|--------------------------------------------|------------------------------------------------|
+| New file/folder, overall app layout        | `references/01-project-structure.md`           |
+| Any route or controller                    | `references/02-api-design-standards.md`        |
+| Error handling, validation middleware      | `references/03-error-handling-validation.md`   |
+| Anything auth/security related            | `references/04-security-standards.md`          |
+| Models, repositories, migrations           | `references/05-database-model-standards.md`    |
+| Writing or reviewing tests                 | `references/06-testing-standards.md`           |
+| Scaffolding any new model/route/component  | `references/07-new-component-checklist.md`     |
+| Lint/format/logging/commit conventions     | `references/08-code-style-general.md`          |
+
+## Core non-negotiables (always apply)
+
+- No business logic in routes; controllers never query the DB directly.
+- Every request is validated at the boundary before it reaches the controller body.
+- Every error flows through the centralized error-handling middleware — no scattered bare `try/catch`.
+- Every new endpoint ships with an updated OpenAPI/Swagger doc and at least a happy-path + failure-path test.
+- Security defaults (helmet, rate limiting, input sanitization, no hardcoded secrets) apply to every service, not opt-in.
+
+## Workflow for a new feature
+
+1. Read `07-new-component-checklist.md` first — run through it before writing any code.
+2. Check `01-project-structure.md` to place the new files in the correct layer/folder.
+3. Design the endpoint per `02-api-design-standards.md` (path, verb, status codes, response envelope).
+4. Write the validation schema, then the controller/service/repository, applying `03`, `04`, and `05` as relevant.
+5. Write tests per `06-testing-standards.md`.
+6. Run lint/format per `08-code-style-general.md` before considering the task done.

package/standards/nodejs-express-standards/claude-code/.claude/skills/nodejs-express-standards/references/01-project-structure.md

@@ -0,0 +1,33 @@
+# Project Structure Standards (Node.js + Express)
+
+## Standard folder layout
+
+```
+src/
+  config/         # env loading + validation, db config, third-party config
+  routes/         # express.Router() definitions only — no logic
+  controllers/    # HTTP layer: parse req, call service, shape res
+  services/       # business logic, orchestration — framework-agnostic
+  repositories/    # data access layer (DB queries), one per model/table
+  models/         # ORM/schema definitions
+  validators/     # request schema validation (zod/joi/celebrate)
+  middlewares/    # auth, error handler, rate limit, logging
+  utils/          # pure helper functions
+  jobs/           # cron / queue workers
+  events/         # event emitters / pub-sub handlers
+  constants/       # enums, error codes, status strings
+app.js            # express app assembly (middleware + routes), NO app.listen()
+server.js         # imports app.js, calls app.listen(), handles graceful shutdown
+tests/
+  unit/
+  integration/
+```
+
+## Rules
+
+- **Layered architecture is mandatory**: `route → controller → service → repository → model`. A controller never talks to the DB directly, and a service never touches `req`/`res`.
+- Split `app.js` (the Express app object) from `server.js` (the process/listener) so the app can be imported into supertest without binding a port.
+- Config must be loaded and **validated at startup** (e.g. with `envalid`, `zod`, or `joi`) — fail fast if a required env var is missing, don't let it fail later at runtime.
+- No business logic in `routes/`. Routes only wire `path + method → middleware chain → controller`.
+- One repository per aggregate/model. Repositories are the only files allowed to import the ORM/query builder directly.
+- Barrel files (`index.js`) per folder are optional but if used, keep them to re-exports only — no logic.

package/standards/nodejs-express-standards/claude-code/.claude/skills/nodejs-express-standards/references/02-api-design-standards.md

@@ -0,0 +1,41 @@
+# REST API Design Standards
+
+## Resource naming & routing
+
+- Use plural nouns for resources: `/users`, `/orders`, not `/user` or `/getUsers`.
+- Nest resources only one level deep: `/orders/:orderId/items`, avoid deeper nesting.
+- Version the API from day one: `/api/v1/...`. Never ship an unversioned public API.
+- Use HTTP verbs correctly, never verbs in the path:
+
+| Verb   | Path              | Action                  |
+|--------|-------------------|-------------------------|
+| GET    | /users            | list                    |
+| GET    | /users/:id        | read one                |
+| POST   | /users            | create                  |
+| PUT    | /users/:id        | full replace            |
+| PATCH  | /users/:id        | partial update          |
+| DELETE | /users/:id        | delete                  |
+
+## Status codes
+
+- `200` OK (read/update), `201` Created (with `Location` header), `204` No Content (delete/no body).
+- `400` validation error, `401` unauthenticated, `403` unauthorized, `404` not found, `409` conflict, `422` semantically invalid, `429` rate-limited, `500` unhandled server error.
+- Never return `200` with an error payload — the HTTP status must reflect the outcome.
+
+## Response envelope (consistent across all endpoints)
+
+```json
+// success
+{ "success": true, "data": { }, "meta": { "page": 1, "totalPages": 4 } }
+
+// error
+{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "email is required", "details": [] } }
+```
+
+## Other requirements
+
+- **Pagination** is required on every list endpoint (`?page=&limit=` or cursor-based `?cursor=`) — never return an unbounded array.
+- **Filtering/sorting** via query params (`?status=active&sort=-createdAt`), validated against an allow-list of fields (never pass raw query straight into a DB `WHERE`/`ORDER BY`).
+- **Idempotency**: `PUT`/`DELETE` must be idempotent. For `POST` on payment/order-creation style endpoints, support an `Idempotency-Key` header.
+- **Document every endpoint** with OpenAPI/Swagger (`swagger-jsdoc` or a maintained `openapi.yaml`) — a new endpoint is not done until it's documented.
+- Never expose internal DB IDs/structure verbatim if it leaks implementation details; DTOs/serializers shape what the client sees.

package/standards/nodejs-express-standards/claude-code/.claude/skills/nodejs-express-standards/references/03-error-handling-validation.md

@@ -0,0 +1,27 @@
+# Error Handling & Validation Standards
+
+## Custom error class
+
+```js
+class AppError extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.isOperational = true; // distinguishes expected errors from bugs
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+```
+
+## Rules
+
+- **Never use raw `try/catch` scattered in controllers.** Wrap async route handlers with a `catchAsync`/`asyncHandler` utility that forwards rejected promises to `next(err)`.
+- **One centralized error-handling middleware**, registered last in `app.js`, that:
+  - Logs the error (with request id / correlation id).
+  - Returns the standard error envelope.
+  - Hides stack traces and internal messages in production (`isOperational === false` → generic "Something went wrong").
+- **Validate every request at the boundary**, before it reaches the controller body — use a schema library (`zod`, `joi`, or `celebrate`) as route middleware, not manual `if` checks sprinkled through the controller.
+- Validation errors return `400`/`422` with a `details` array listing each failing field.
+- Distinguish **operational errors** (bad input, not found, auth failure — expected, safe to show a message) from **programmer errors** (bugs — log, alert, return generic 500).
+- Async code must never produce an unhandled promise rejection — catch at the boundary, always.

package/standards/nodejs-express-standards/claude-code/.claude/skills/nodejs-express-standards/references/04-security-standards.md

@@ -0,0 +1,17 @@
+# Security Standards
+
+Apply all of these by default on every new Express service — don't wait to be asked:
+
+- **Helmet**: `app.use(helmet())` for secure headers (CSP, HSTS, X-Frame-Options, etc.) — configure CSP explicitly rather than leaving it wide open.
+- **CORS**: explicit origin allow-list via the `cors` package, never `origin: '*'` on an authenticated API.
+- **Rate limiting**: `express-rate-limit` (or a Redis-backed store in multi-instance deployments) on all public endpoints, stricter limits on auth endpoints (`/login`, `/register`, `/forgot-password`).
+- **Input sanitization**: strip/escape untrusted input against NoSQL/SQL injection and XSS (`express-mongo-sanitize`, parameterized queries/ORM query builders — never string-concatenate SQL).
+- **AuthN/AuthZ**:
+  - Short-lived JWT access tokens + refresh token rotation, or session cookies with `httpOnly`, `secure`, `sameSite`.
+  - Passwords hashed with `bcrypt`/`argon2`, never stored or logged in plaintext.
+  - Role/permission checks live in middleware, applied per-route, not scattered inside controller `if` statements.
+- **Secrets**: only via environment variables / a secrets manager. Never commit `.env`, never hardcode API keys or DB credentials.
+- **Request limits**: `express.json({ limit: '10kb' })` (or an appropriate cap) to prevent payload-based DoS.
+- **Dependency hygiene**: run `npm audit` (or Snyk/Dependabot) as part of CI; block merges on high/critical vulnerabilities.
+- **HTTPS only** in production; redirect HTTP → HTTPS at the load balancer/proxy layer.
+- Never leak stack traces, internal file paths, or library versions in API responses or headers.

package/standards/nodejs-express-standards/claude-code/.claude/skills/nodejs-express-standards/references/05-database-model-standards.md

@@ -0,0 +1,10 @@
+# Database & Model Standards
+
+- **Repository pattern**: all DB queries live in `repositories/`, never directly inside services or controllers. Services call repository methods; they don't know it's Postgres/Mongo/etc.
+- **Migrations are mandatory** for schema changes (e.g. `knex`, `sequelize-cli`, `prisma migrate`, `typeorm migration`). Never use `sync({ alter: true })` or manual schema edits against a shared/production DB.
+- Every table/collection gets `createdAt` and `updatedAt` timestamps by default.
+- Prefer **soft deletes** (`deletedAt` column + default query scope excluding it) over hard deletes for user-facing/business-critical records; hard-delete only where there's a clear compliance/retention reason.
+- Index every foreign key and every column used in a frequent `WHERE`/`sort` — check the query plan (`EXPLAIN`) for anything added to a hot path.
+- **Transactions** wrap any operation that writes to more than one table/collection, so a partial failure can't leave data inconsistent.
+- Naming: `snake_case` for DB columns/tables, `camelCase` in JS — handle the mapping in the ORM config, don't hand-convert per query.
+- Never return raw ORM model instances straight from a controller — map to a DTO/serializer so DB shape and API shape can evolve independently.

package/standards/nodejs-express-standards/claude-code/.claude/skills/nodejs-express-standards/references/06-testing-standards.md

@@ -0,0 +1,10 @@
+# Testing Standards
+
+- **Unit tests** (Jest/Vitest) for every service function — mock the repository layer, test business logic in isolation.
+- **Integration tests** (Supertest against the exported `app.js`, not a running server) for every route — exercise the real middleware chain, validation, and error handler.
+- Use a dedicated test database (or transactional rollback per test) — tests must never touch dev/prod data, and must be safely re-runnable/parallelizable.
+- Follow **Arrange–Act–Assert** structure in every test; one logical assertion focus per test case.
+- Mock external services/network calls (payment providers, email, third-party APIs) — tests must not depend on network access.
+- Minimum coverage threshold: **80%** on services and controllers, enforced in CI (fail the build below threshold).
+- Every new endpoint or model ships with at least: one happy-path integration test, one validation-failure test, one auth-failure test (if protected).
+- CI must run lint → unit → integration → coverage gate, in that order, before a PR can merge.

package/standards/nodejs-express-standards/claude-code/.claude/skills/nodejs-express-standards/references/07-new-component-checklist.md

@@ -0,0 +1,16 @@
+# Checklist: Before Creating Any New Model, Route, or Component
+
+Run through this before writing code for a new feature — this is what a senior architect reviews for in a PR:
+
+1. **Check for an existing pattern first.** Look at a similar existing model/route/service in the codebase and follow its shape — don't introduce a new pattern for something that already has one.
+2. **Confirm the layer boundaries**: route (wiring only) → validator (schema) → controller (HTTP glue) → service (logic) → repository (DB) → model. No shortcuts (e.g. controller querying the DB directly).
+3. **Write the validation schema** for every input (body/params/query) before writing the controller.
+4. **Define the DB migration** (not a live schema edit) if a new table/column is needed, with indexes on any FK/frequently-queried column.
+5. **Handle errors explicitly**: use `AppError`/`catchAsync`, no bare `try/catch` with silent `console.log`.
+6. **Add authorization checks** if the resource is user/role-scoped — don't rely on the client to hide UI for unauthorized actions.
+7. **Write tests**: at minimum one integration test (happy path) and one validation/error-path test.
+8. **Update API documentation** (OpenAPI/Swagger) for any new or changed endpoint.
+9. **Run lint + format** (ESLint + Prettier) — no new lint warnings introduced.
+10. **No secrets, no hardcoded config** — anything environment-specific goes through `config/`.
+11. **Consider pagination/rate-limits** if it's a list endpoint or public-facing.
+12. Keep the diff focused — one feature/concern per PR/commit.

package/standards/nodejs-express-standards/claude-code/.claude/skills/nodejs-express-standards/references/08-code-style-general.md

@@ -0,0 +1,9 @@
+# General Code Style Standards
+
+- ESLint (Airbnb-base or `eslint-config-standard`) + Prettier, enforced via a pre-commit hook (`husky` + `lint-staged`) and in CI — not just "run it locally sometimes."
+- `async/await` everywhere; no mixing with raw `.then()` chains or callback-style APIs in new code.
+- No `console.log` in committed code — use a structured logger (`pino` or `winston`) with log levels, and include a request/correlation id in every log line.
+- One export/responsibility per file; avoid god-files that mix routing, business logic, and DB access.
+- Environment-based configuration only (`dotenv` + a validated config schema) — never branch behavior on `NODE_ENV` scattered through business logic; centralize environment differences in `config/`.
+- Commit messages follow Conventional Commits (`feat:`, `fix:`, `refactor:`, `test:`, `chore:`) so history and changelogs stay meaningful.
+- Prefer explicit, readable code over clever one-liners — this codebase is read far more often than it's written.

package/standards/nodejs-express-standards/cursor/.cursor/rules/00-index.mdc

@@ -0,0 +1,25 @@
+---
+description: Node.js + Express senior-architect standards — always apply as the baseline for this project
+globs:
+alwaysApply: true
+---
+
+# Node.js + Express Standards (index)
+
+This project follows layered architecture: `route -> validator -> controller -> service -> repository -> model`.
+Before creating or editing any model, route, controller, or service, also consult the more specific rules in this
+folder — they auto-attach based on the file you're touching:
+
+- `01-project-structure.mdc` — folder layout & layering rules
+- `02-api-design.mdc` — REST conventions, status codes, response shape
+- `03-error-handling-validation.mdc` — error classes, validation middleware
+- `04-security.mdc` — security defaults (helmet, rate limiting, auth, secrets)
+- `05-database-models.mdc` — repository pattern, migrations, indexing
+- `06-testing.mdc` — unit/integration test requirements
+- `07-new-component-checklist.mdc` — run this checklist before scaffolding anything new
+- `08-code-style.mdc` — lint/format/logging/commit conventions
+
+Core non-negotiables:
+- No business logic in routes or controllers talking directly to the DB.
+- Every new input is validated at the boundary; every error goes through the centralized error handler.
+- Every new endpoint ships with tests and updated API docs.