From 6f622f9b1eb77b4280ecd05512fa46962bf7b482 Mon Sep 17 00:00:00 2001 From: Peter Dave Hello Date: Fri, 3 Oct 2025 03:26:50 +0800 Subject: [PATCH] Add AGENTS.md (comprehensive agent guide) Mainly generated by codex-cli v0.42.0, with gpt-5-codex high, and this AGENTS.md construction prompt: - https://gist.github.com/PeterDaveHello/f30c38a156982a35683edfd5ece2d474 This guide captures the repository structure, tooling, and safety checks, enabling contributors and coding agents to quickly grasp the project architecture, stay aligned, and deliver efficient, well-vetted changes with confidence. Reference: - https://agents.md/ Signed-off-by: Peter Dave Hello --- AGENTS.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..10578f1ab --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,49 @@ +# Repository Guidelines + +## Dos and Don'ts + +- Do run `nvm use` (reads the version pinned in `.nvmrc`) before `npm ci`; don't rely on ad-hoc Node versions. +- Do lint (`npm run lint -- lib/...`) and run focused tests; don't commit artifacts from `public/build/`. +- Do sign commits with `git commit -s`; don't rewrite reviewed history. +- Do update `public/docs/release-notes.md` and `package.json` on `release/*`; CI verifies both. + +## Project Structure & Module Organization + +- `app.js` boots Express, Socket.IO, metrics, and pulls settings from `lib/**` modules. +- Scripts and utilities live in `bin/` and `utils/`; base config defaults reside in `config.json.example`. +- Front-end assets/locales live in `public/` and `locales/`; docs live in `public/docs/`. +- Tests mirror runtime folders under `test/` with shared fakes in `test/testDoubles/`, and CI workflows live in `.github/workflows/`. + +## Build, Test, and Development Commands + +- Install once per checkout: `nvm use` (uses `.nvmrc`) then `npm ci` (mirrors `.github/workflows/build.yml`). +- `npm run dev` watches webpack; `npm run build` emits production bundles to `public/build/`. +- `npm start` runs `sequelize db:migrate` before serving. +- Lint via `npm run lint -- lib/realtime/realtime.js`; validate JSON with `npm run jsonlint`. +- Targeted tests: `npx mocha --require intelli-espower-loader --exit test/realtime/connection.test.js`; use `npm run test:ci` or `npm run coverage` for the full suite. + +## Coding Style & Naming Conventions + +- StandardJS and `.editorconfig` enforce two-space indents, no semicolons, and single quotes. +- Keep filenames lowercase/camelCase in `lib/`, kebab-case for web assets, and reuse `test/testDoubles/` helpers for specs. + +## Testing Guidelines + +- Mocha + Power Assert run through `npm run mocha`; `nyc` covers `app.js` and `lib/**`. +- Place specs beside their domain (`test/realtime/*.test.js`, `test/auth/*.test.js`) and keep them deterministic via shared fakes. + +## Commit & Pull Request Guidelines + +- Keep commits atomic, DCO-signed, and in `type: summary` form (for example `fix: empty exported notes in the archive`). +- Reference issues, document config/schema changes, attach `npm run test:ci` output or UI evidence when relevant, ensure `release/*` PRs update `public/docs/release-notes.md` and `package.json`, and gather sign-off from two other developers per `CONTRIBUTING.md`. + +## Safety & Permissions + +- Safe: read/list files, adjust docs, run scoped lint/test commands. +- Ask first: new dependencies, renames/deletions, build or CI edits, Docker publish flows, or other large refactors. +- Never force-push shared branches, wipe data stores, or leak secrets. + +## Security & Configuration Tips + +- Seed new configs from `config.json.example` and inject secrets via environment variables. +- Security headers default in `lib/config/default.js` (override via `config.json`), with CSP logic in `lib/csp.js`; image upload adapters under `lib/imageRouter/` (for example `lib/imageRouter/s3.js`) need local S3/MinIO verification and documented port/TLS expectations.