# Dependency Policy

How this workspace keeps npm dependencies current, safe and reproducible.

## Principles

1. **Exact pins** – Every direct dependency in `package.json` is pinned to an
   exact version (`1.2.3`, never `^1.2.3`). `save-exact=true` is set in
   `.npmrc` so `pnpm add` follows this rule automatically.
2. **Committed lockfile** – `pnpm-lock.yaml` is committed. CI and the Docker
   build install with `--frozen-lockfile`, so builds are reproducible.
3. **Security gates** – CI runs `pnpm audit --prod` (fails on any finding) and
   `pnpm audit --audit-level high` (fails on high/critical). A non-zero exit
   blocks the release pipeline.
4. **Supply-chain protection** – `minimumReleaseAge: 1440` (1 day) in
   `pnpm-workspace.yaml` blocks freshly published versions. Do not lower or
   disable it; only allowlist trusted publishers via
   `minimumReleaseAgeExclude` for urgent security fixes.
5. **Pinned critical packages** – `react`, `react-dom` and `esbuild` are
   intentionally excluded from automated updates (see `renovate.json`). Bump
   them deliberately, one release at a time, with a test pass.

## Update cadence

| Frequency | Scope | Who |
|-----------|-------|-----|
| Weekly | Patch + minor (grouped by Renovate) | Renovate PR, human merge after green CI |
| Monthly | One major version at a time | Human, own commit + release tag |
| As needed | Security advisories | Immediate fix + patch release |
| Yearly | Infrastructure review (Node LTS, Postgres major, k3s) | Human |

## Rules

- **Patch/minor**: merge freely once CI (typecheck + build + audit) is green.
- **Major**: never bundle multiple majors into one release. One major per
  commit so regressions can be bisected to the responsible change.
- **"Safe intermediate"**: if a package has a newer major that is not yet
  absorbed, stay on the latest patch/minor of the *current* major line. The
  exact-pin guarantees we never float into a new major by accident.
- **Node/Infra**: Node base image and pnpm version in the `Dockerfile` are
  pinned exactly. Update them together with a build + live smoke test.
- **Postgres**: image tag is managed in the `admin/apps` repository
  (`apps/system/toolrate`). Major upgrades run through a backup/restore flow.

## Process for applying updates

1. `pnpm install` to refresh the lockfile.
2. Regenerate clients if the API changed: `pnpm --filter @workspace/api-spec run codegen`.
3. Run `pnpm run typecheck`, `pnpm run build` (with `PORT=8080 BASE_PATH=/`),
   and `pnpm audit`.
4. Fix any code that the new majors require (the common ones are
   `openid-client`, `recharts`, `react-day-picker`, `date-fns`,
   `@hookform/resolvers`, `react-resizable-panels`).
5. Commit, tag `vX.Y.Z`, push. CI builds, audits and deploys to k3s.