# AGENTS.md

Repository-specific instructions for Codex sessions in this repository.

These instructions apply to all work in `nowdatabase_react` unless the user gives a more specific direct instruction for the current task.

## Source Policy Files

Codex must follow the repository policies described in:

- `documentation/codex_planning_prompt.md`
- `documentation/coding_prompt_template_fullstack.md`

Treat those files as the canonical planning and coding policy for this repository.

## How To Handle User Requests In VS Code

- The user may describe tasks in plain language in the Codex chat panel.
- Do not require the user to provide JSON task payloads.
- Translate the user’s plain-language request into the same planning and implementation discipline described in the two policy files above.
- If the request is ambiguous in a way that could cause incorrect implementation, ask a short clarifying question. Otherwise make reasonable assumptions and proceed.

## Default Workflow

For any non-trivial feature, bug fix, refactor, or test change:

1. Read the relevant code before changing anything.
2. Create a short internal plan that follows `documentation/codex_planning_prompt.md`.
3. Implement the task using the coding standards from `documentation/coding_prompt_template_fullstack.md`.
4. Run the relevant validation commands.
5. Summarize what changed, what was verified, and any remaining risks.

For very small requests, Codex may skip writing out a formal plan, but it must still follow the same policy.

## Frontend Test Policy

When changing frontend code or frontend tests, Codex must proactively apply these rules:

- Prefer narrow fixes over broad Jest configuration workarounds.
- Before changing Jest config, check whether the real issue is missing runtime context in tests.
- Wrap Redux-dependent components in `Provider`.
- Wrap router-dependent components in the correct router harness:
  - `MemoryRouter` for simple router hooks
  - `createMemoryRouter` + `RouterProvider` when data-router behavior or `useBlocker` is involved
- Provide required app contexts such as page/detail/notification providers when components depend on them.
- Mock unrelated heavy subtrees when they are not part of the behavior under test.
- Treat these as known Jest risk areas and handle them with focused fixes:
  - `import.meta.env`
  - ESM-only dependencies
  - asset imports
  - RTK Query `fetchBaseQuery`
  - timers and open handles
- Use `act(...)` for programmatic router navigation or other async state transitions when needed.
- Ensure select fields use valid empty values such as `''` rather than `undefined`.
- Avoid introducing runtime circular imports between Redux API modules, reducers, and store setup.
- Keep React hooks lint-safe at all times: do not call hooks conditionally in production components or test-support code.
- Do not attach promise-returning functions directly to DOM event props when a void callback is expected; wrap them in a lint-safe handler.
- Treat `src/tests/setup.ts` and `src/tests/mocks/*` as strict frontend code, not throwaway helpers: they must satisfy ESLint, Prettier, and TypeScript rules too.

## Backend API Test Policy

When changing backend code or backend API tests, Codex must proactively apply these rules:

- Prefer fixing the real backend cause over rewriting many tests, but verify whether a failure is actually caused by stale fixtures, environment dependence, or overly strict assertions before changing production code.
- Treat API tests as strict code too: helper files, mocks, and test-only fetch/database shims must satisfy ESLint, Prettier, and TypeScript rules.
- Do not make API tests depend on live external services. Mock outbound calls such as Geonames requests so CI is deterministic and offline-safe.
- Avoid depending on unstable seeded data details unless the test explicitly verifies them. If a test needs seeded fixtures, use values that are present in the checked-in test SQL and keep related tests aligned to the same seeded ids.
- For update tests, build payloads from known-valid fixture shapes when the endpoint validates broad entity state, but avoid blindly merging fetched server objects if that reintroduces legacy fields that fail current validation.
- When a test only cares about one behavior, keep the payload narrow enough to avoid replaying unrelated edits on subsequent requests.
- Avoid brittle assertions on total log-row counts when broader valid payloads can legitimately produce more audit rows. Assert the required rows and the key audit linkage instead.
- Watch for write-layer helper fields leaking into generic persistence code, especially metadata such as `comment`, `references`, computed helper objects, or UI-only fields. Strip those before calling shared DB writers.
- Be careful with generated ids in MariaDB-backed tests. Prefer deterministic id handling that works with the actual driver behavior instead of assuming `RETURNING` semantics.
- When debugging backend test failures, capture the real exception if possible before applying another speculative fix.

## Cypress / E2E Test Policy

When changing Cypress support code or E2E specs, Codex must proactively apply these rules:

- Prefer fixing the shared Cypress harness first when multiple specs fail in similar ways. Check `cypress/support/commands.js`, `cypress.config.js`, shared fixtures, and common login/reset helpers before patching many individual specs.
- Use deterministic database setup. Prefer a single shared `cy.resetDatabase()` helper over raw reset requests scattered through specs, and use `beforeEach` isolation when tests mutate shared seeded state.
- Treat Cypress support files as strict code too: custom commands, TS declaration files, fixtures used as typed metadata, and support helpers must satisfy ESLint, Prettier, and TypeScript rules.
- Be careful with Material UI wrappers and hidden inputs. Target the actual interactive element (for example the nested `input` inside a `TextField` wrapper) rather than wrapper divs or hidden native select inputs.
- Do not rely on live external services in E2E tests. Stub third-party requests such as Geonames lookups with `cy.intercept(...)` when the behavior under test is not the external service itself.
- Prefer stable post-action assertions over brittle transient UI text. If a save/create flow is asynchronous, verify the actual network response or returned id/slug and then navigate/assert from the durable saved state instead of depending only on an immediate toast or header text.
- Avoid over-asserting read-mode text for fields whose display formatting can legitimately differ from edit-mode values. For selectors such as time-unit sequences, assert against the stable UI state that the current component actually exposes.
- When a Cypress failure shows an application-side unhandled rejection, check whether the real fix belongs in production code, especially around RTK Query `unwrap()` calls, delete flows, or mutation side effects leaking rejected promises.
- Keep hard-coded seeded ids in E2E specs aligned with the current checked-in seed data. If API and E2E tests both exercise the same entity, prefer the same known-good ids.

## Validation Expectations

Before finishing, Codex should run the narrowest useful checks for the task, and run broader checks when the scope justifies it.

Typical commands from the repository root:

- `npm run lint`
- `npm run tsc`
- `npm run test`
- `npm run lint:frontend`
- `npm run tsc:frontend`
- `npm run lint:cypress`

Backend-focused checks are also expected when relevant:

- `cd backend && npm run lint`
- `cd backend && npm run build`
- `cd backend && npm run test:api:local -- --runTestsByPath <path>`

If only a small area changed, targeted test runs are acceptable during iteration, but the final state should reflect the validation standard from the two policy files.

## Scope Control

- Implement only the requested task and directly necessary fixes.
- Do not add unrelated cleanup unless it is required to make the task correct or keep CI green.
- Do not add temporary test hacks without checking whether a production or harness-level fix is the better solution.

## Priority Order For Decisions

When tradeoffs appear, prefer:

1. Correctness
2. Keeping existing tests and CI stable
3. Narrow, local fixes
4. Consistency with existing repository patterns
5. Speed

## Output Expectations

- Be concise and practical.
- Mention files changed, validation performed, and any unresolved risk.
- If a task was only partially verifiable locally, say so clearly.

## Database Safety (Mandatory)

- Never run database reset or restore commands against the **development** database unless the user explicitly asks for it.
- Treat `/test/reset-test-database` and any SQL in `test_data/sqlfiles/` as **test-only** fixtures. Do not point dev services at those databases.
- Before running any DB reset/restore, confirm which **DB host, port, and database names** the backend is using and whether they are isolated from dev data.
- If test and dev share the same database container or port, stop and ask the user to separate them before proceeding.