# Gotchas Things that turned out differently than expected, so the same wrong assumption isn't made twice. Collected during the rewrite (September 2026); the progress log in [rewrite-plan.md](rewrite-plan.md) has the context for each. ## The API - **PUT replaces the whole event.** Missing fields fall back to `status: 'PUBLIC'` and `repeatFrequency: ''`. Always send the full `EventPayload`, even to change one field. - **"0 rows were updated" comes back as HTTP 200.** `api.updateEvent` turns that body into an error. - **The API returns raw DB values.** `wholeDay` is `0`/`1` (observed), and a deleted event's latest version is a row with every field `null` except `status: 'DELETED'`. `parseApiEvent` handles both. - **`GET /admin/me` answers 200 for accounts without the calendar permission.** Only `apps` says so. - **The admin feed ignores `includes_calendars`**; the public/iCal feeds follow it. So an event can appear in a calendar's subscription although it belongs to another calendar. - **`PRIVATE` is in the status enum but nothing uses it.** The app shows it read-only and keeps it. - **The iCal times depend on the API process's time zone** (formatted with local `getHours()`, labelled Europe/Berlin). Inferred from the code; not checked on the server. - **Only the admin DB pool reads `DB_PORT`.** A local calendar test database has to listen on 3306. ## Time - **Historical DST.** Until 1995 German summer time ended in September, so `1994-10-02T22:00Z` is 23:00 on 2 October in Berlin, not midnight on the 3rd. The date code gets it right; hand-written test data easily doesn't. - **DST edges in forms.** A nonexistent spring time (02:30) becomes 03:30 CEST; an ambiguous autumn time resolves to the second occurrence (CET). Pinned in `lib/dates.test.ts`. ## Next.js / hosting - **Standalone output doesn't serve `.next/static` by itself.** Without the copy, CSS and JS are 404s. The `postbuild` script copies it into `.next/standalone/.next/static`; there is no `public/` folder to copy (the favicon lives in `app/`). Verified by running `.next/standalone/server.js`. - **`NEXT_PUBLIC_*` values are inlined at build time.** They must be set when `npm run build` runs, not only when the server starts; `lib/env.ts` fails the build if they're missing. - **The build prerenders `/` by calling the API.** If the build machine can't reach it, the build still succeeds and the events section appears after the first revalidation (≤ 5 min). - **With `revalidate`, a short API outage doesn't blank the landing page's events** in a running server - Next keeps serving the cached fetch. - **The dev server must run on port 4200.** That's the origin the API and the admin app trust; another port breaks sign-out and the return redirect. - **Dev runs React strict mode**, so every calendar is fetched twice on load in development. - **A leftover Angular `node_modules`** makes `npm install` fail on a vite peer conflict. - **npm 11 blocks install scripts by default** (`sharp`, `unrs-resolver` didn't run theirs). Lint and build work without them; the app doesn't use `next/image`. - **Vitest 5 needs `@types/node` ≥ 22**; the config is `vitest.config.mts` because `package.json` has no `"type": "module"`. ## Deploy (Gitea Actions) - **`~` in an rsync `-e` string is not your `$HOME`.** rsync passes it to ssh without a shell, and ssh expands `~` from the passwd entry. In a job container those can differ, so a key written to `$HOME/.ssh` isn't found and `known_hosts` is read from somewhere else. The workflow uses absolute paths (`SSH_DIR`) and `UserKnownHostsFile`. Found in a local dry run. - **The deploy target is Plesk's own subdomain folder** (`calendar.nachklang.art/`), so rsync `--delete` must exclude what Plesk or Passenger keep there (`tmp/`, `.well-known/`). The first deploy replaces the Angular build - back it up first, and switch Plesk to the Node app right after the run, because the folder no longer works as a static site. - **Plesk's chrooted SSH shell is broken on this server**: `bash` segfaults in the chroot copy under `/var/www/vhosts/nachklang.art`, so sessions close right after login (and the command of an `ssh host 'cmd'` never runs, exit 255). The deploy user uses plain `/bin/bash` instead. - **SSH is on port 42069**, not 22 (22 is closed); the deploy user is `plesk-nachklang`, not `nachklang`. - **Jenkins deployed as root.** Files it copied into an app folder belong to `root:root`, so the first Gitea deploy (as `plesk-nachklang`) fails with rsync "Operation not permitted" / "Permission denied". Before switching an app, run `find . ! -user plesk-nachklang` in its folder and `chown -R plesk-nachklang:psacln` what it lists (hit on the API, 2026-11-08; the calendar folder only held files directly in a folder the user owned, so deleting them worked). - **Every Gitea Actions job starts in a fresh container.** Splitting test and deploy into two jobs repeats checkout, Node setup and `npm ci` (and here the build); one job with the deploy steps conditioned on push-to-master is faster. Spell the condition out on each step instead of comparing an env flag to `'true'` - a mismatch there skips the deploy silently and the run stays green. - **Disable the Jenkins job before merging to master**, or it runs `ng build` on the next push. ## shadcn / Base UI - **`npx shadcn add` imports `cn` from the npm package `cn`** and adds it (plus `next-themes` for the toaster). This repo uses `@/lib/utils` like feedback, and toasts are light-only - fix both after every `shadcn add`. - **Generated components have English labels** ("Close"); translated to "Schließen" in `dialog.tsx` and `sheet.tsx`. - **Base UI, not Radix:** toggles expose `aria-pressed` (not `data-state=on`), triggers take a `render` prop (not `asChild`), menu radio items stay open unless `closeOnClick` is set. - **A link that looks like a button is a plain ``**, not `