# Upgrade Lambda Node Modules

Upgrade all npm/yarn dependencies for a lambda, prune stale resolutions, fix tooling config, and verify the build. Follow these steps exactly:

## 1. Create a branch

```
git checkout master && git checkout -b MAINT-bump-<lambda-name>-modules
```

## 2. Set up environment

Run both of these:
```
awsume prod && nvm use
```

## 3. Upgrade all dependencies

```
yarn upgrade --latest
```

## 4. Prune stale resolutions

```
check-resolutions --fix
```

> **Note:** `check-resolutions` is a custom global script. If the command is not found, ask the repo owner for installation instructions — it is currently being published via [this PR](https://github.com/theorchard/collab/pull/2389#pullrequestreview-4007039847) and this link should be updated once merged.

Note which resolutions were removed ("CAN REMOVE") and which are still needed ("STILL NEEDED").

## 5. Clean up dependencies

Read `package.json` and do the following:

- **Removed resolutions**: Any package that `check-resolutions --fix` removed that also appears in `dependencies` — remove it from `dependencies`. It was only there because yarn upgrade incorrectly added it.
- **Still-needed resolutions**: Any package in the `resolutions` section that also appears in `dependencies` — update the resolution version to match the version now in `dependencies`, then remove it from `dependencies`. There is no reason for a package to be in both `resolutions` and `dependencies`.
- **Sort resolutions**: Sort the `resolutions` keys in ascending alphabetical order (purely stylistic — consistent with how yarn orders dependencies).
- **Resolution versions**: Prefer caret ranges (e.g. `^4.0.5`) over exact versions unless the resolution is specifically pinning to a known-safe exact version (e.g. `brace-expansion: 2.0.2`).

After all edits to `package.json`, check the original indentation style with:
```
git show HEAD:<path-to-package.json> | head -3 | cat -v
```
Then rewrite the file using that exact indentation (tabs or 2-space) so the diff only shows meaningful changes.

## 6. Migrate to biome (if not already using biome)

Check whether the lambda has `eslint.config.mts` (or similar eslint config). If so, it hasn't been migrated to biome yet — do this before proceeding:

1. **Create `biome.json`** at the lambda root by copying from `~/.claude/commands/references/biome.json`. Update the `files.includes` ignores if the lambda has different fixture/script paths.

2. **Update Dockerfiles** — in both `Dockerfile` and `Dockerfile.tests`, find the `COPY` line that copies config files. If it includes `eslint.config.mts`, replace that with `biome.json`. If it doesn't mention eslint at all, just add `biome.json` to the existing `COPY` line.

3. **Delete `eslint.config.mts`** (if it exists).

4. **Update `package.json`**:
   - Remove `"prettier": "@theorchard/prettier-config"` top-level field (if present)
   - Remove `"eslintConfig"` section (if present)
   - Update scripts:
     - `lint:js` → `biome lint --write ./src`
     - `format` → `biome format --write .`
     - `format:check` → `biome check .`
   - Remove from `devDependencies`: `@theorchard/eslint-config`, `@theorchard/eslint-config-ts-prettier`, `@theorchard/prettier-config`, `prettier`, `jiti` (and any other eslint/prettier-only packages)
   - Run `yarn add --dev @biomejs/biome@latest` to install biome
   - Update `lint-staged`: change `"prettier --write"` → `"biome lint --write"`

## 7. Update biome config (if biome was already a dependency)

Check if `@biomejs/biome` was upgraded. If so, run:
```
yarn exec biome migrate --write
```

If that doesn't write the file (check the schema version in `biome.json` to confirm), apply the migration manually by reading the diff output and editing `biome.json` directly.

## 8. Handle TypeScript version

Pin typescript to `^5.9.3` in `package.json` (v6 has compatibility issues). Then run:
```
yarn install
```

## 8. Add skipLibCheck

Add `"skipLibCheck": true` to `compilerOptions` in `tsconfig.json` to prevent type errors from third-party packages (e.g. `@types/glob` vs `minimatch` incompatibilities).

## 9. Verify

Run these in order and fix any issues before proceeding to the next:

```
yarn format
yarn lint
yarn exec biome check ./src ./tests
yarn test:unit
yarn dev:docker:build
```

> **Note:** `yarn exec biome check` (without `--write`) is needed to catch `assist/organizeImports` violations — biome v2 does not auto-apply assist actions via `--write`. Fix any import ordering issues manually.

## 10. Commit and PR

Stage all changed files, commit with a message like `MAINT: bump <lambda-name> modules`, push the branch, and open a PR.