112 lines
5.4 KiB
Markdown
112 lines
5.4 KiB
Markdown
# AGENTS.md - Fiddy
|
||
|
||
## Authority
|
||
- Source of truth: `PROJECT_INSTRUCTIONS.md` in the repo root.
|
||
- Bugfix protocol: `DEBUGGING_INSTRUCTIONS.md`.
|
||
- Current-stack mapping: `docs/AGENTIC_CONTRACT_MAP.md`.
|
||
- If files conflict, follow `PROJECT_INSTRUCTIONS.md`.
|
||
|
||
## Project Overview
|
||
- Full-stack grocery list app with household/group behavior, RBAC, image support, and Postgres persistence.
|
||
- Backend: Express 5 CommonJS API in `backend/`.
|
||
- Frontend: React 19 + Vite SPA in `frontend/`, with partial TypeScript.
|
||
- Database: external on-prem Postgres. Do not add or assume a DB container.
|
||
- Canonical migrations live in `packages/db/migrations`.
|
||
|
||
## Important Directories
|
||
- `backend/routes`, `backend/controllers`: route registration and request/response handling.
|
||
- `backend/models`, `backend/services`, `backend/middleware`, `backend/db`: DB access, domain logic, auth, RBAC, request IDs, image handling.
|
||
- `frontend/src/api`: client API wrappers using the shared Axios instance.
|
||
- `frontend/src/context`, `frontend/src/hooks`, `frontend/src/components`, `frontend/src/pages`: UI state and screens.
|
||
- `frontend/tests`: Playwright e2e tests.
|
||
- `backend/tests`: Jest/Supertest backend tests.
|
||
- `scripts`: DB migration helpers.
|
||
- `docs`: practical maps, runbooks, architecture notes, and archived implementation history.
|
||
|
||
## Setup
|
||
- Install root tools: `npm ci`
|
||
- Install backend tools: `npm --prefix backend ci`
|
||
- Install frontend tools: `npm --prefix frontend ci`
|
||
- Use Node.js 20.19+ or 22.12+ for frontend/Vite commands.
|
||
- Configure backend env from `backend/.env.example`; never commit real `.env` values.
|
||
- For migration scripts, set `DATABASE_URL` in the shell before running root DB commands.
|
||
|
||
## Run Commands
|
||
- Dev with Docker: `docker compose -f docker-compose.dev.yml up`
|
||
- Backend only: `npm run dev:backend`
|
||
- Frontend only: `npm run dev:frontend`
|
||
- Backend default port: `5000`
|
||
- Frontend Docker-mapped port: `3010`; Vite direct default is `5173` unless overridden.
|
||
|
||
## Verification Commands
|
||
- Backend unit/API tests: `npm test`
|
||
- Frontend lint: `npm run lint`
|
||
- Frontend typecheck: `npm run typecheck`
|
||
- Vulnerability audit: `npm run audit`
|
||
- Backend build: `npm run build:backend`
|
||
- Frontend build: `npm run build:frontend`
|
||
- Full build: `npm run build`
|
||
- E2E tests: `npm run test:e2e`
|
||
- Migration status: `npm run db:migrate:status`
|
||
- Migration verification: `npm run db:migrate:verify`
|
||
|
||
## Environment Notes
|
||
- `backend/.env` is used by the backend and Docker dev service.
|
||
- `frontend/.env` may define `VITE_API_URL` and `VITE_ALLOWED_HOSTS`.
|
||
- Do not print, log, or commit secrets, tokens, cookies, DB URLs, receipt bytes, or full invite codes.
|
||
- Logs/audit entries for invite codes may include last4 only.
|
||
|
||
## Coding Conventions
|
||
- Preserve the current stack; do not migrate to Next.js or another framework.
|
||
- Keep Express routes/controllers thin; put DB-heavy work in models/services and authz in backend layers.
|
||
- Keep frontend network calls in `frontend/src/api` wrappers and UI state in context/hooks.
|
||
- Always send credentials through the shared Axios client when touching authenticated frontend API calls.
|
||
- Enforce RBAC server-side; client guards are UX only.
|
||
- Frontend DB-mutating actions must show toast/bubble outcome notifications.
|
||
- Progress notifications must reuse `UploadQueueContext` and `UploadToaster`.
|
||
- Keep encoding clean; do not introduce mojibake.
|
||
|
||
## Dependency Rules
|
||
- npm is the package manager; do not introduce pnpm, yarn, bun, or another build tool.
|
||
- Do not add production dependencies unless the task clearly requires it and the repo has no practical existing option.
|
||
- Do not add cron, workers, polling daemons, or background job frameworks.
|
||
|
||
## Testing Expectations
|
||
- Add or update tests when API behavior changes.
|
||
- Include negative cases for authz, membership, and invalid input where applicable.
|
||
- For UI behavior changes, prefer focused Playwright tests.
|
||
- Run the narrowest relevant checks first, then broader checks when risk warrants it.
|
||
|
||
## Done Means
|
||
- Behavior is preserved unless the task explicitly requires a change.
|
||
- Relevant tests/lint/typecheck/build commands were run or the reason they could not run is documented.
|
||
- Touched files have no known TS/lint errors.
|
||
- Migrations are in `packages/db/migrations` when schema changes are required.
|
||
- Documentation is updated for changed commands, contracts, or workflows.
|
||
|
||
## Codex Must Not
|
||
- Do not read or expose real `.env` values; inspect variable names only when needed.
|
||
- Do not touch production data or run DB migrations without explicit operator intent.
|
||
- Do not log secrets, receipt bytes, or full invite codes.
|
||
- Do not delete user work or generated artifacts unless explicitly asked.
|
||
- Do not make broad refactors, file moves, or framework changes for cleanup alone.
|
||
|
||
## Deeper Docs
|
||
- `docs/PROJECT_MAP.md`: quick repo orientation.
|
||
- `docs/DEVELOPMENT.md`: setup, run, verify, and troubleshooting.
|
||
- `docs/DB_MIGRATION_WORKFLOW.md`: migration runbook.
|
||
- `docs/PLANS.md`: template for multi-step work.
|
||
- `.agents/skills/fiddy-verify/SKILL.md`: repo-specific verification workflow for Codex.
|
||
|
||
## Response Icon Legend
|
||
- `🔄` in progress
|
||
- `✅` completed
|
||
- `🧪` verification/test result
|
||
- `📄` documentation update
|
||
- `🗄️` database or migration change
|
||
- `🚀` deploy/release step
|
||
- `⚠️` risk, blocker, or manual operator action needed
|
||
- `❌` failed command or unsuccessful attempt
|
||
- `ℹ️` informational context
|
||
- `🧭` recommendation or next-step option
|