mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-09 13:01:00 +00:00
Marc-André BombeckandClaude Opus 4.7
0783261b44
Full audit of every overlapping claim across the five top-level docs
against the v1.3.2 codebase. Fixes structural drift accumulated since
v1.2:
- README: API envelope was documented as `{ data, error, meta }` but the
actual helpers return `{ data, error }`. Architecture tree was missing
6 src/app/, 4 components/, 8 lib/ subdirectories that landed in
1.2/1.3 (auth, mood, charts, targets, notifications, bugreport,
gamification, settings, ai, feedback, insights, logging, moodlog,
monitoring, …). API Reference grew 4 new sections (Personalization,
Feedback + Tokens, Notifications, Admin) covering ~25 previously
undocumented endpoints. Route count `~60` → `100+`. Achievement count
`30+` → `38+`. i18n keys `1000+` → `1500+` with note about the new
integrity test.
- AGENTS.md: Status `v1.2.0` → `v1.3.2` with the body-composition / SSRF
/ GHCR / pg-boss-drain / blocking-CI / locale-integrity highlights.
Prisma `7.4` → `7.8`. Migrations `0001–0018` → `0001–0022`. Settings
page `13 sections / ~2100 lines` → `8 top-level sections / ~3150
lines` with the actual section IDs. Insights page line estimate
trimmed to `~1750`, section ID `medications` → `meds`.
NotificationChannel / EventType correctly described as `String`
fields (not Prisma enums) sourced from
`src/lib/notifications/types.ts`.
- CONTRIBUTING.md: UI-language statement was inverted ("UI text in
German" → English-default with German user-selectable, plus the
i18n integrity test). Dark-mode-only claim corrected — light/system
toggle exists in the topbar. Node `22+` → `20+` to match the README.
openssl recipe split: POSTGRES_PASSWORD uses base64 24, the three
hex secrets use hex 32. CI check list expanded to the 5-step
pipeline (typecheck, lint, test, format:check, build).
- CLAUDE.md: vitest config path `vitest.config.ts` → `vitest.config.mts`.
Bearer-token hashing labelled `HMAC-SHA256` (keyed by
`API_TOKEN_HMAC_KEY`) instead of plain SHA-256. Removed the
reference to a non-existent `docs/STATUS.md` and the overstated
`docs/{architecture,security,ops,API,ADRs}` directory list — the
long-form end-user docs live at docs.healthlog.dev, only audit notes
are local.
- SECURITY.md: pin example bumped from `:1.2.0` to `:1.3.2`.
Verified against code: 23 Prisma models, all listed endpoints exist,
all package.json versions match, every CHANGELOG v1.3.x claim
(SSRF guard, Withings 77/88 mapping, pg-boss SIGTERM drain, WCAG
44×44 touch targets, rate-limited threshold writes, N+1 fix in
/api/insights/comprehensive) traced to the actual implementation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
108 lines
3.4 KiB
Markdown
108 lines
3.4 KiB
Markdown
# Contributing to HealthLog
|
|
|
|
Contributions are welcome. This guide covers how to set up the project and submit changes.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 20+
|
|
- pnpm
|
|
- PostgreSQL 16+ (or Docker)
|
|
- Git
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
git clone https://github.com/MBombeck/HealthLog.git
|
|
cd HealthLog
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` and configure at minimum:
|
|
|
|
```
|
|
POSTGRES_PASSWORD=<base64, 24 bytes>
|
|
DATABASE_URL="postgresql://healthlog:${POSTGRES_PASSWORD}@db:5432/healthlog"
|
|
SESSION_SECRET=<64-char hex>
|
|
ENCRYPTION_KEY=<64-char hex>
|
|
API_TOKEN_HMAC_KEY=<64-char hex>
|
|
```
|
|
|
|
Generate the four secrets:
|
|
|
|
```bash
|
|
echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)" >> .env
|
|
echo "SESSION_SECRET=$(openssl rand -hex 32)" >> .env
|
|
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env
|
|
echo "API_TOKEN_HMAC_KEY=$(openssl rand -hex 32)" >> .env
|
|
```
|
|
|
|
### With Docker (database only)
|
|
|
|
```bash
|
|
docker compose up -d db
|
|
pnpm install
|
|
pnpm db:generate
|
|
pnpm db:migrate
|
|
pnpm dev
|
|
```
|
|
|
|
### Full Docker
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
```bash
|
|
pnpm dev # Start dev server (http://localhost:3000)
|
|
pnpm lint # ESLint
|
|
pnpm format:check # Prettier (check)
|
|
pnpm typecheck # TypeScript strict mode
|
|
pnpm test # Vitest
|
|
pnpm build # Next.js production build
|
|
```
|
|
|
|
All five checks must pass before submitting a PR. The full one-liner that mirrors CI:
|
|
|
|
```bash
|
|
pnpm typecheck && pnpm lint && pnpm test && pnpm format:check && pnpm build
|
|
```
|
|
|
|
## Code Conventions
|
|
|
|
- **TypeScript strict mode** -- avoid `any`. Where it's truly unavoidable (e.g. variadic Next.js handler signatures in `src/lib/api-handler.ts`), document the reason inline.
|
|
- **English-default UI** -- the default locale is English. German is user-selectable. Code, comments, commit messages, and docs are English. All user-facing strings go through `t("key")` with translations in both `messages/en.json` and `messages/de.json`. The `i18n-locale-integrity.test.ts` suite blocks merges if keys drift between locales or duplicate at any nesting depth.
|
|
- **API responses** follow the `{ data, error }` envelope via `apiSuccess()` / `apiError()` in `src/lib/api-response.ts`. Wrap every route handler in `apiHandler()` (`src/lib/api-handler.ts`) for error handling, structured Wide-Event logging, and `x-request-id` propagation.
|
|
- **Zod v4** (`import { ... } from "zod/v4"`) for input validation in API routes and forms.
|
|
- **shadcn/ui** components (new-york style) for UI primitives.
|
|
- **Dracula theme** -- dark mode is the default; a `light`/`system` toggle is exposed in the topbar. Chart and accent colors use the `--dracula-*` CSS tokens so both themes stay coherent.
|
|
|
|
See `CLAUDE.md` for detailed architecture and patterns.
|
|
|
|
## Database Changes
|
|
|
|
```bash
|
|
# After modifying prisma/schema.prisma:
|
|
pnpm db:migrate # Creates a new migration
|
|
pnpm db:generate # Regenerates Prisma client
|
|
```
|
|
|
|
Always include the migration file in your PR.
|
|
|
|
## Pull Requests
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/your-feature`)
|
|
3. Make your changes
|
|
4. Ensure all checks pass (`pnpm typecheck && pnpm lint && pnpm test && pnpm format:check && pnpm build`)
|
|
5. Submit a PR with a clear description of the changes
|
|
|
|
## Security
|
|
|
|
If you find a security vulnerability, **do not open a public issue**. See [SECURITY.md](SECURITY.md) for responsible disclosure instructions.
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the [AGPL-3.0](LICENSE) license.
|