Skip to content

AGENTS.md

Latest commit

 

History

History
116 lines (80 loc) · 5.73 KB

AGENTS.md

File metadata and controls

116 lines (80 loc) · 5.73 KB
Raw

AGENTS.md

PII Policy

Never include anyone's real name, email address, phone number, or other personally identifiable information (PII) in GitHub issues, tasks, or PR descriptions. Use placeholders like "[Name]", "[Email]", or generic descriptions instead.

Setup

Source env before running commands:

source .env   # or use direnv: create .envrc containing `dotenv`

Required vars: POSTGRESQL_HOST, POSTGRESQL_PORT, POSTGRESQL_DATABASE, POSTGRESQL_DATABASE_TEST, POSTGRESQL_USER, POSTGRESQL_PASSWORD, SSO_URL, PROJECT, ENVIRONMENT, BUILD_TARGET, API_PORT

Database

Database is already populated with data. Use connection settings from .env:

  • POSTGRESQL_HOST, POSTGRESQL_PORT, POSTGRESQL_DATABASE, POSTGRESQL_USER, POSTGRESQL_PASSWORD

Do NOT run migrations or seeds unless explicitly asked — they may overwrite existing data.

Developer Commands

Task Command
Dev server (local) npm run dev (nodemon + babel-node, debug on :9229)
Build npm run build (gulp: babel transpile src/ + scripts/ → build/, copies config/templates)
Start (production) npm start → runs build/src/server.js
Lint npm run test:lint (eslint + prettier, scans src __tests__ __testHelpers__ __mocks__)
DB migrate N/A — knex removed, DB schema frozen
DB seed N/A — knex removed, seed data managed via scripts
Full init npm run initialize_docker (build + migrate + seed + import)

Docker Workflow

Two separate docker-compose projects coexist (dev = default, test = myra-project):

Task Command
Dev setup make local-setup (build + seed)
Dev run make run-local
Test setup make local-test-setup
Test run make local-test (uses test.docker-compose.yml -p myra-test)
DB shell make database (dev) or make database-test (test)
Container shell make workspace

Test DB container also starts minio and minio-nginx (required for some features).

Architecture

  • Entry: src/server.js → src/index.js
  • Routes: src/router/
  • Business logic: src/services/, src/libs/
  • DB layer: src/libs/db2/ (pg + kysely), no migration system (schema frozen)
  • Scripts: scripts/ (import, data generation, maintenance) — transpiled to build/scripts/
  • Build output: build/ (gitignored, generated by gulp)
  • Frontend: range-web sibling directory

Toolchain Quirks

  • Node version: engines says ~6.11.0, babel targets Node 8.9, CI runs 10.x — legacy codebase, all modern syntax transpiled
  • Knex removal: knex was removed — all runtime queries use kysely, raw SQL falls back to pg.Pool
  • npm run initialize has a typo: npm rum build — use initialize_docker instead
  • Pre-commit: husky v9 + lint-staged runs eslint --fix and prettier --write on staged .js files

Database Access

Quick query command:

source .env && PGPASSWORD=$POSTGRESQL_PASSWORD psql -h $POSTGRESQL_HOST -p $POSTGRESQL_PORT -U $POSTGRESQL_USER -d $POSTGRESQL_DATABASE -c "SQL_QUERY"

Key tables:

  • plan — extension_status, extension_required_votes, extension_received_votes
  • plan_extension_requests — plan_id, client_id, user_id, requested_extension
  • user_account — id, email
  • user_client_link — user_id, client_id
  • client_agreement — client_id, agreement_id

Frontend Code

Location: /Users/bamin/range/range-web (sibling directory)

Key file for plan extension UI: src/components/selectRangeUsePlanPage/ExtensionColumn.js — renders Thumbs up/down buttons when extensionStatus === 1 (AWAITING_VOTES)

Running Scripts

Use Node 25 via nvm for compatibility:

source ~/.nvm/nvm.sh && nvm use 25 && node build/scripts/plan_extension_exemption.js

Bug Workflow

When user reports a bug, follow this exact sequence:

  1. Create GitHub issue on correct repo (range-web for frontend, range-api for backend) with title, description, root cause, and impact
  2. Assign to the user (brijesh-amin)
  3. Implement fix on dev branch
  4. Add/update tests to prevent regression (existing test patterns in __tests__/)
  5. Commit using commit style #issue-number - description
  6. Push to origin:dev
  7. Close the issue with a comment pointing to the commit

Gotchas

  • POSTGRESQL_DATABASE_TEST defaults to myra_test — must exist for tests
  • build/ must exist and be populated before npm start or npm run initialize_docker will work
  • Never run npm test directly — it connects to the .env database ($POSTGRESQL_DATABASE, not the test database) and will clear local data. Always use make local-test (Docker) for integration tests; it uses $POSTGRESQL_DATABASE_TEST. Unit tests that don't touch the DB are fine.
  • Always use $POSTGRESQL_DATABASE_TEST for test-related database queries — never $POSTGRESQL_DATABASE. The local dev database has real data.