update

What this skill does

Bulk-update project dependencies safely: bump everything that's truly safe, hold back frameworks that need manual migration, hand off packages that ship their own upgrade CLI, and keep `@types/node` aligned with the user's actual Node runtime — not with whatever version the registry happens to publish next.

The reason these distinctions matter: a naïve `npm update --latest` will silently move frameworks (TypeScript, Next.js, React, etc.) across breaking versions, will fight with tools that have first-party upgrade scripts (Storybook, shadcn, Prisma), and will install `@types/node` versions that describe APIs the user's runtime doesn't have. Each of those is a separate failure mode, and each needs a different treatment.

## When this skill triggers

User says any of (non-exhaustive):
- "update all dependencies", "bump everything", "refresh packages"
- "what's outdated?", "run an upgrade pass", "update node modules"
- "sync @types/node to my node version"
- "smart update", "bulk dep update"

Also trigger when the user changes Node versions (via nvm/fnm/volta) and asks to bring types in line.

## Detection phase

### 1. Resolve the package manager from the lockfile

Check in this order — first match wins:

| Lockfile present                  | Package manager |
|-----------------------------------|------------------|
| `pnpm-lock.yaml`                  | `pnpm`           |
| `bun.lock` or `bun.lockb`         | `bun`            |
| `yarn.lock`                       | `yarn` (detect berry vs classic via `yarn --version`) |
| `package-lock.json`               | `npm`            |
| none                              | fall back to `npm`, warn the user |

Also read `package.json` `packageManager` field if present — it overrides lockfile detection.

### 2. Resolve the target Node major

The goal: find the highest Node major version the user has actually installed on this machine, and use that as the target for `@types/node`. Don't use the latest published Node — types should describe a runtime the user can run.

Probe in this order, collect all versions found, then take the max major:

```bash
# nvm (sourced into shell)
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && nvm ls --no-colors 2>/dev/null

# fnm
command -v fnm >/dev/null && fnm list 2>/dev/null

# volta
command -v volta >/dev/null && volta list node 2>/dev/null

# asdf
command -v asdf >/dev/null && asdf list nodejs 2>/dev/null

# system node (fallback)
command -v node >/dev/null && node --version
```

Parse out all `v<major>.<minor>.<patch>` strings, take `max(major)`. That major is the `@types/node` target.

If nothing is found, ask the user which Node major to target.

### 3. Collect outdated packages

```bash
<pm> outdated --json
```

Works on npm, pnpm, yarn (berry), and bun. Parse the JSON to get `{ package, current, wanted, latest, type }` per entry.

For older yarn classic, fall back to parsing `yarn outdated` table output.

## Classification

For each outdated package, classify into one of four buckets:

### Bucket A — `@types/node` (special-cased)

Target the latest version on the major matching the installed Node max-major. Example: installed majors `[18, 20, 22]` → install `@types/node@22` (resolves to latest 22.x). Don't follow `latest` from `outdated` here; it may be ahead of the runtime.

### Bucket B — Frameworks (skip auto-bump, surface to user)

Major bumps here usually require a migration guide. Skip silently for patches/minors? No — skip them entirely from the auto-update set, but list them in the report so the user knows they're outdated. Reason: even minor bumps of these can ship behavior changes the user wants to review.

Framework list (match by name or scope prefix):

- `typescript`
- `next`
- `react`, `react-dom`, `react-native`
- `vue`, `@vue/*`, `nuxt`, `@nuxt/*`
- `svelte`, `@sveltejs/*`
- `@angular/*`, `@angular-devkit/*`
- `@nestjs/*`
- `express`, `fastify`, `koa`, `hapi`
- `vite`
- `webpack`, `webpack-cli`
- `@remix-run/*`
- `gatsby`, `gatsby-*`
- `astro`, `@astrojs/*`
- `solid-js`, `@solidjs/*`
- `qwik`, `@builder.io/qwik*`

### Bucket C — Self-upgrading packages (skip auto-bump, surface CLI hint)

These ship their own upgrade tooling that does more than bump a version (codemods, config rewrites, schema sync). Bumping them via plain `<pm> update` skips the migration work.

| Match               | Recommended upgrade command                          |
|---------------------|------------------------------------------------------|
| `storybook`, `@storybook/*` | `npx storybook@latest upgrade`                       |
| `@shadcn/ui`, `shadcn-ui`, `shadcn` | `npx shadcn@latest add` (re-add components as needed) |
| `prisma`, `@prisma/*` | `pnpm add -D prisma@latest && npx prisma generate`  |
| `@cypress/*`, `cypress` | `npx cypress install` after bump                    |
| `tailwindcss` (major) | follow Tailwind v3→v4 guide; use `npx @tailwindcss/upgrade` for v4 |
| `@sentry/*` (major) | follow Sentry migration guide                        |
| `expo`              | `npx expo install --check` then `npx expo install --fix` |
| `@nx/*`, `nx`       | `npx nx migrate latest`                              |
| `@angular/cli` (major) | `ng update @angular/core @angular/cli`            |

For patches/minors of these, it's *usually* safe to bump normally — but err on the side of surfacing them so the user can decide.

### Bucket D — Everything else (safe-bump candidates)

Normal libraries: utility packages, eslint plugins (non-config-breaking), testing helpers, lint formatters, etc. Patches and minors get bumped without confirmation. Majors get listed for individual confirmation.

## Preview before applying

Always show the preview before running any install command. Group by bucket:

```
Package manager: pnpm
Target Node major (for @types/node): 22

@types/node alignment:
  @types/node  20.11.5 → 22.x (latest matching installed Node 22)

Safe bumps (patches + minors, will apply automatically):
  zod              3.22.4 → 3.22.7
  date-fns         2.30.0 → 2.30.4
  @types/react     18.2.45 → 18.2.79

Major bumps (need your confirmation, one by one):
  vitest           1.6.0 → 3.0.0
  zustand          4.5.0 → 5.0.0

Held back — frameworks (review the changelog yourself):
  typescript       5.3.3 → 5.6.2
  next             14.1.0 → 15.0.3
  react            18.2.0 → 19.0.0

Held back — self-upgrading (run the package's CLI):
  storybook        7.6.10 → 8.4.7   → npx storybook@latest upgrade
  prisma           5.8.1 → 5.22.0   → pnpm add -D prisma@latest && npx prisma generate
```

After the preview, ask: "Apply the safe bumps + @types/node now? Then I'll walk through the majors and ask about held-back packages individually."

After the safe bumps succeed, **proactively go through the Held-back list with AskUserQuestion** — one prompt per held-back package (or one batched multi-select for the framework list) — asking whether to also bump it. Don't just leave them in the report. The user explicitly said they want to be asked, not silently skipped.

## Update commands by package manager

### npm

```bash
npm install <pkg>@<version>      # explicit version
npm install <pkg>@latest         # major jump
```

### pnpm

```bash
pnpm update <pkg>                # within range (safe)
pnpm update --latest <pkg>       # cross-major
pnpm add -D <pkg>@latest         # for devDeps when promoting major
```

### yarn (berry)

```bash
yarn up <pkg>                    # within range
yarn up <pkg>@latest             # cross-major
```

### yarn (classic)

```bash
yarn upgrade <pkg> --latest
```

### bun

```bash
bun update <pkg>                 # respects range
bun add <pkg>@latest             # cross-major
```

Run multi-package bumps in a single command per package manager where possible — saves one full install cycle per package.

## @types/node alignment — the precise recipe

1. From the detection step you have `nodeMajor` (e.g. `22`).
2. Resolve the latest published `@types/node` on that major: