update-deps

# Audit JS Dependencies Use this skill to handle repo-wide JS dependency audits without double-auditing workspace members or blindly applying major upgrades. ## Audit Scope Audit these install roots: - `.` for the npm workspace root and all workspace members under `packages/authgear-core`, `packages/authgear-web`, `packages/authgear-react-native`, and `packages/authgear-capacitor` - `example/reactweb` - `example/reactnative` - `example/capacitor` - `website` Do not run `npm audit` separately inside `packages/authgear-core`, `packages/authgear-web`, `packages/authgear-react-native`, or `packages/authgear-capacitor`. Those packages are installed and resolved by the repo root workspace and root `package-lock.json`. Use these package managers: - `.`: `npm` - `example/reactweb`: `npm` - `example/reactnative`: `npm` - `example/capacitor`: `npm` - `website`: `npm` `example/reactnative` migrated from Yarn to npm (it now has a `package-lock.json`, no `yarn.lock`, and no `yarnauditfix` script). Confirm the lockfile in use before auditing in case this changes again. ## Workflow 1. Audit each install root with its existing package manager. 2. Apply only fixes that stay within the current major line unless the user explicitly asks for breaking upgrades. 3. Re-run audits after each change. 4. Run lightweight verification for each touched project. 5. If a fix requires a major bump, stop and report it instead of applying it. ## Audit Commands Use these commands: ```bash npm audit --json npm outdated --json ``` If a root's package manager has changed since this skill was last updated, use that manager's audit/outdated equivalent instead (e.g. `yarn audit --json` / `yarn outdated --json`). If dependencies are missing, install them with the package manager already used by that directory before auditing. Keep lockfiles aligned with the existing manager. ## Decide Whether A Fix Is Non-Breaking Treat a fix as non-breaking only when at least one of these is true: - `npm audit fix` or the package-manager equivalent resolves the issue without changing declared major versions - The minimal fixed version stays in the same major line as the current declared dependency - The package is transitive and can be fixed by a lockfile update or override/resolution that does not widen a package to a new major Use registry metadata to verify the target version before changing manifests: ```bash npm view <package> version versions --json ``` Check the current declared range in `package.json`, the vulnerable installed version from the audit report, and the minimum patched version. If the patched version requires a new major, do not apply it automatically. Before adding any `overrides` or `resolutions`, check whether the existing declared range already allows a patched version. If it does, prefer a lockfile-only update via `npm audit fix`, the package-manager equivalent, or a non-breaking reinstall over changing `package.json`. When an override or resolution is genuinely required, keep its scope as narrow as possible: - For npm, use `npm explain <package>` to identify the exact parent chain and scope the override to the nested dependency path instead of the package globally. - If a root still uses Yarn, use `yarn why <package>` and prefer the most specific resolution pattern that matches the vulnerable path. - If the vulnerable package can be updated through the existing semver range after a lockfile refresh, remove the temporary override or resolution instead of leaving it behind. - As part of the final pass, review any existing or newly added `overrides` and `resolutions` touched by the audit and remove entries that are now outdated, redundant, or no longer needed. - If an override or resolution crosses a major version line for a transitive dependency, only do it when you have primary-source evidence that the major change is compatible in this context, and note that evidence alongside the manifest change before verification. For this repo, also account for these specifics: - Keep local file references such as `../../packages/authgear-web` and `../../packages/authgear-react-native` untouched - Preserve root `overrides` or per-project `resolutions` unless the fix requires adjusting them ## Apply Safe Fixes Prefer the smallest change that clears the audit: 1. Run `npm audit fix` in npm projects when it does not propose breaking upgrades. 2. Re-check whether the vulnerability is already fixed by the refreshed lockfile before editing manifests. 3. If a targeted package still needs a patch, install the minimal fixed version explicitly. 4. Only add a narrowly scoped override or resolution when the existing declared range cannot otherwise land on the patched version. 5. Update the lockfile with the same package manager that owns the directory. 6. Re-run the audit immediately after each root is updated. When explicit targeted updates are needed, use commands in this shape: ```bash npm install <package>@<fixed-version> ``` If a root still uses Yarn, use `yarn add <package>@<fixed-version>` instead. Avoid opportunistic upgrades. The goal is to remove vulnerable dependencies with the narrowest safe diff. ## Tool Path Setup Check `which npm yarn` first. In some sandboxed/cloud environments `npm` and `yarn` are not on the default shell PATH and must be located manually; on a local machine using a version manager (e.g. asdf) they are typically already resolvable and no extra setup is needed. If they are missing, locate them in the Nix store before running any commands: ```bash NPM=$(find /nix/store -maxdepth 3 -name "npm" -path "*/nodejs-24*/bin/npm" 2>/dev/null | head -1) YARN=$(find /nix/store -maxdepth 3 -name "yarn" -path "*/yarn-*/bin/yarn" 2>/dev/null | head -1) export PATH="$(dirname $NPM):$(dirname $YARN):$PATH" ``` Use this PATH prefix for every `npm` and `yarn` command in this skill. No install root in this repo currently uses Yarn (see Audit Scope), so `YARN`/`yarn` lookups are usually unnecessary — only resolve `yarn` if a root's package manager has changed back. ## Verify After Changes Re-run the audit for every root you touched. Then run the most relevant lightweight verification for each affected project: - Repo root: `npm test` and `npm run typecheck` - `example/reactweb`: `npm run build` - `example/reactnative`: `npm test` and `npm run typecheck` - `example/capacitor`: `npm run build` - `website`: `npm run build` If a dependency update affects native mobile tooling, note any heavier validation you did not run, such as Capacitor or React Native platform builds. ## Run Local CI Checks Before Completing After all audits and per-project verifications pass, run the full local CI suite from the repo root before declaring the task done. These mirror the `test` job in `.github/workflows/ci.yaml`. Run each command individually and capture its exit code explicitly. **Never pipe a CI command through `tail`, `grep`, or any filter** — doing so returns the filter's exit code, not the command's, silently hiding failures. ```bash npm audit --audit-level=critical; echo "exit: $?" cd website && npm audit --audit-level=critical; echo "exit: $?"; cd .. npm run check-tidy; echo "exit: $?" npm run format; echo "exit: $?" npm run lint; echo "exit: $?" npm run typecheck; echo "exit: $?" npm run test; echo "exit: $?" npm run verify; echo "exit: $?" npm run build; echo "exit: $?" ``` All nine commands must print `exit: 0`. If any print a non-zero exit, fix the issue before completing. Do not skip this step. ## Report Breaking Changes Instead Of Applying Them If the audit can only be fixed through a major-version change, stop and notify the user with a concise summary: - Affected project root - Package name - Current declared range - Minimum fixed version - Why it is breaking - Whether a lockfile-only mitigation or override was available - The verification work that would be needed after a major upgrade