Pickup-Config/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/ holds the React client: App.js bootstraps the main views (“Slots buchen”, Store-Watch) and composes feature-specific components (z. B. DashboardView, StoreWatchPage) plus hooks/utilities in neighboring folders.
• public/ contains the static shell served during development; only add files that must be copied verbatim into the build output.
• server.js is the Express backend that serves the built client, exposes the REST APIs used by the UI (e.g. /api/stores, /api/store-watch/*, /api/user/preferences/*, /api/location/nearest-store) und persistiert Daten über die Stores in config/.
• config/ stores generated runtime state (<profileId>-pickup-config.json, Admin-Settings, Preferences, Watcher etc.). Keep it writable but untracked so local credentials never leak.
• build/ is created by npm run build and shipped by the Express server or Docker image; never edit files here manually.
• docker-compose.yml, Dockerfile, and rebuildContainer.sh encapsulate deployment; update them when server ports, env vars, or base images change.

Build, Test, and Development Commands

• npm install – restore dependencies in package.json.
• npm start – launch the CRA dev server on port 3000 with live reload.
• npm run build – emit the production bundle into build/; run before node server.js or container builds.
• npm test – run React Testing Library suites in watch mode; append -- --watch=false in CI.
• npm run check:foodsharing-api – verify the Foodsharing endpoints used by the app against https://foodsharing.de/api/doc.
• node server.js – serve the prebuilt UI and REST API using values from .env (e.g., PICKUP_TOPIC, credentials, ports).
• docker-compose up --build – rebuild and start the containerized service, syncing the bundled UI and server.

Required Close-Out Steps

• After changes to server.js, services/, src/, Dockerfile, docker-compose.yml, or the Foodsharing API integration, always run this sequence completely:
• CI=true npm test -- --watch=false
• npm run build
• npm run check:foodsharing-api when Foodsharing endpoints, payloads, or response mappings are affected
• docker compose up -d --build
• curl http://localhost:3005/api/health and confirm the response contains "status":"ok"

Git & Deployment Workflow

• Before making any code, config, Docker, or documentation change, verify git status --short is clean. If it is not clean, stop and reconcile the current worktree first; the running Docker service on port 3005 is the relevant production reference when deciding which state to preserve.
• If the running Docker service contains changes that are not committed, compare its /app contents against the worktree, commit the Docker-live state, and push it before starting a new feature or fix.
• After every completed feature or fix, update .commitmessage, stage it with git add -f .commitmessage, create a conventional commit, and push main.
• Features and fixes must go live in Docker after the commit: run docker compose up -d --build and verify curl http://localhost:3005/api/health returns a JSON response containing "status":"ok".
• Keep config/, credentials, request logs, HAR captures, and other runtime state out of commits unless explicitly requested.

Coding Style & Naming Conventions

• Use 2-space indentation and Standard/Prettier-compatible formatting; rely on the CRA ESLint config (react-app, react-app/jest) for feedback.
• Favor functional React components with PascalCase filenames (PickupConfigEditor.js) and camelCase props/state keys.
• Keep config schema fields (e.g., desiredWeekday, onlyNotify) camelCase across client and API payloads.
• Prefer descriptive folder-local CSS files rather than global selectors; co-locate assets next to their component whenever possible.

Testing Guidelines

• React Testing Library + Jest underpin App.test.js; add <Component>.test.js files alongside components to exercise rendering and validation.
• Initialize helpers inside setupTests.js to keep suites lean.
• Aim for meaningful edge cases (blank config, duplicate IDs, toggling onlyNotify). Pull requests should demonstrate passing npm test output or CI logs.

Commit & Pull Request Guidelines

• Follow conventional commits (e.g., feat: add notification panel, fix: debounce config saves) and keep subjects ≤72 characters.
• After every change, refresh .commitmessage with the final commit text and ensure it is staged (e.g., git add -f .commitmessage) so tooling can reuse it automatically.
• Reference issues or API endpoints impacted inside the body, and describe user-visible changes plus verification steps.
• PRs must include: summary of API/UI changes, screenshots or JSON samples when modifying config shape, notes on new env vars, and confirmation that npm test and npm run build succeed.

Security & Configuration Tips

• Store secrets in .env, not in version control; provide .env.example updates when new variables (ports, credentials) are introduced.
• The server writes to config/pickup-config.json; ensure the directory exists and has the correct permissions before deploying or running containers.