Files
Calendar_Frontend/docs/gotchas.md
T
PaddyandClaude Opus 5.5 b22e89001a
Test and deploy / test-and-deploy (pull_request) Successful in 2m25s
Run tests and deploy in one Gitea Actions job
Two jobs meant checking out, setting up Node and running npm ci (and in the
frontend the build) twice, about two minutes each, because every job starts
in a fresh container. Now one job tests and, for pushes to master only,
deploys. The push-to-master condition is spelled out on every deploy step
instead of an env flag compared to 'true', which would skip the deploy
silently and stay green if the boolean were rendered differently. A failed
test still stops the deploy (an if: without a status function implies
success()).

Docs: the one-job layout, and that Jenkins deployed as root - files it left
in an app folder must be chowned to the subscription user before the first
Gitea deploy (hit on the API).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-08 22:51:26 +01:00

102 lines
6.9 KiB
Markdown

# 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 `<a className={buttonVariants(…)}>`**, not
`<Button render={<a …/>}>`. Through Base UI's Button it warns in dev ("expected a native
<button>", shown as Next's "2 issues" badge) and, with `nativeButton={false}`, gets
`role="button"` - screen readers then announce a link as a button.
- **Base UI Select ignores synthetic `click()`s**; automated tests need real pointer or keyboard input.
- **Closed dialogs stay in the DOM** with `data-closed` until their exit animation ends - in a hidden
tab that never happens. Query `[data-open]` when checking what's open.
- **In a hidden tab `matchMedia` `change` events don't fire either**, so a resize there doesn't switch
the sheet between bottom and side. It works in a visible window.
## CSS
- **Responsive rules inside a capped panel need container queries**, not viewport breakpoints (the
edit sheet's footer labels use `@container` / `@md:`).
- **An implicit grid column grows to its longest unbreakable content** (a URL) and defeats
`truncate`; use `grid-cols-[minmax(0,1fr)]`.
- **`break-all` splits ordinary words mid-word** ("App-s"); only use it on text without spaces.