Rewrite Agent Rules

These rules apply when implementing the Next.js rewrite on the rewrite/next branch.

Checklist Tracking

CHECKLIST.md uses three checkbox states:

Rules:

The ✅ column is yours; the ✔️ column belongs to the review agent.
After completing each numbered item, mark its ✅ box by changing [ ] to [x].
If you complete an optional item ([~]), change it to [x]. If you skip it, leave it as [~].
Before starting any item in a new phase, read CHECKLIST.md and confirm that every required ([ ]/[x]) item in all preceding phases has [x] in both ✅ and ✔️. Items marked [~] in both columns do not need to be completed first.
If any required box in a previous phase is unchecked, stop and report which items are blocking progress instead of proceeding.

REWRITE_PLAN.md is the guiding plan for the migration from the current CRA + Express app to a Next.js App Router + TypeScript app.
When working on the rewrite, follow the migration phases in REWRITE_PLAN.md unless the user explicitly asks for a different order.
Treat each numbered migration item as a checkpoint: implement it, update its ✅ box in CHECKLIST.md, add or update tests, run the relevant verification, then continue.
Prefer building the new Next.js structure in parallel until feature parity is proven. Do not delete server/, oebb-planner-app/, or oebb-planner.jsx before equivalent Next.js behavior is implemented, tested, and the user has clearly asked for cleanup.
Preserve existing API contracts and user-visible behavior during migration unless the rewrite plan or user request explicitly changes them.
Use npm consistently because the existing project uses package-lock.json.

Start by reading the relevant files and identifying the smallest safe next step.
State the plan before making non-trivial changes.
Implement one coherent change at a time.
After each step, review the diff and check whether it still matches the intended behavior.
Do not move on to the next step while the current step has unresolved compile errors, failing tests, or obvious regressions.
Prefer small, targeted edits over broad rewrites.
Preserve existing behavior unless the user explicitly asks to change it.
When a task spans multiple rewrite phases, complete one vertical slice at a time where practical: type or library code, route or hook, UI integration, tests, then verification.
Keep reusable logic in src/lib, side effects in hooks or route handlers, and shared contracts in src/types.

Add or update tests for every new feature, bug fix, and behavior change.
Put tests near the code they cover and follow the existing test style.
Cover the main success path, important edge cases, and failure behavior.
Do not remove or weaken tests just to make the suite pass.
If a change cannot reasonably be tested, explain why and add the closest practical verification.
For the Next.js rewrite, prefer unit tests for src/lib, route tests for src/app/api, and component smoke or behavior tests for UI components.
Mock external services in automated tests, including ÖBB HAFAS, Nominatim, OSRM, geolocation, time, and calendar downloads. Do not make tests depend on live network availability.
Test TypeScript data shapes and boundary parsing where API responses are transformed into app types.

cd server
npm test

cd oebb-planner-app
CI=true npm test -- --watchAll=false
npm run build

For the Next.js rewrite, once the root Next.js project exists, run the relevant root checks instead:

npm test
npm run build

npm run typecheck
npm run lint

If a change touches both server and app behavior, run both sets of checks.
If a command fails, stop, inspect the failure, fix the cause, and rerun the command.
Do not claim the work is complete until the relevant checks pass, or until the remaining blocker is clearly reported.

Make sure additions do not introduce compile errors, lint errors, runtime crashes, or broken imports.
Check that public APIs, endpoint contracts, props, and data shapes remain compatible with existing callers.
Keep error handling explicit and user-facing failures understandable.
Avoid hidden global state, timing assumptions, and network-dependent tests unless the project already uses that pattern.
Keep dependencies unchanged unless they are necessary for the task and justified.
Do not commit generated artifacts, caches, logs, or local environment files.
Keep TypeScript strictness intact once introduced. Do not use any as a shortcut around unclear domain types.
Keep server-only code out of client components. Route handlers and src/lib clients that use secrets, privileged headers, or upstream service details must not be imported into browser-only code.
Respect Nominatim usage requirements when implementing geocoding: configurable base URL, clear user agent, rate-limit-aware caching, and no direct browser calls to the public service.
Keep OSRM and HAFAS clients behind API routes or server-side utilities so failures can be normalized and tested.
For UI work, preserve accessibility basics: semantic buttons and links, labels for inputs, keyboard-operable controls, visible loading and error states.

Before finishing a step, confirm:

The requested behavior is implemented.
The ✅ box for the corresponding item in CHECKLIST.md is checked.
The change matches the relevant phase or numbered item in REWRITE_PLAN.md, when applicable.
Tests were added or updated where appropriate.
Relevant tests and build checks pass.
The change is scoped to the request.
No unrelated user changes were overwritten.
Old implementation files were not removed unless parity is tested and cleanup was requested.
Any limitations or skipped checks are reported clearly.