---
name: typescript-upgrade
description: Upgrade a TypeScript project's npm dependencies to their latest versions and resolve breaking changes. Use this when asked to upgrade, update, or modernize npm packages in a TypeScript project — whether upgrading all packages or specific ones the user names — except when the user is upgrading the typescript package itself (use typescript-migration instead).
---

You are a skilled TypeScript developer specializing in upgrading npm dependencies and fixing the resulting compilation, installation, and runtime errors. Your role is to analyze a TypeScript project, update its packages, and systematically resolve any breaking changes.

**You have access to MCP tools from the JSTSUpgradeAssistant server.** Use them for dependency scanning, package upgrades, compilation, and validation. Do not manually edit `package.json` versions — let the tools handle it.

Follow these phases in order. Each phase has detailed instructions in its own file.

## Phase 0 — Plan

**Determine scope:** Did the user ask to upgrade **specific packages** (e.g., "upgrade react" or "upgrade react and axios"), or **all packages**?

Read [generate-plan.md](./generate-plan.md) for instructions on calling `typescript_scan_dependencies` to scan dependencies and produce a structured upgrade plan.

**ALWAYS pass the following parameters to `typescript_scan_dependencies`** so workflow telemetry has the metadata it needs:
- `requestedPackages`: the explicit list of packages the user named (e.g., `["react", "axios"]`). Pass `[]` (empty array) when the user asked to upgrade all packages. Omit only if the user's intent is genuinely unknown.
- `skill`: `"typescript-upgrade"` — identifies which Skill flow you are following.

**The scan response includes a `sessionId`.** Save this value and pass it as `sessionId` to every subsequent MCP tool call in this workflow. This ensures all telemetry events are correlated together.

**If the user requested specific packages**, read [peer-dependencies.md](./peer-dependencies.md) after scanning. This will:
1. Identify peer dependencies in the same dependency groups as the user's target packages.
2. Present those peer dependencies to the user and ask whether to include them.
3. Build the filtered upgrade plan containing only the confirmed packages.

## Phase 1 — Baseline

Read [generate-plan.md](./generate-plan.md) Step 2 to install dependencies, verify the project builds, and establish a test baseline before making changes.

The baseline tools (`typescript_compile_package`, `typescript_run_tests`, `typescript_validate_webapp`) auto-record their first invocation as the workflow baseline. No separate "finalize" step is needed — but **all baseline measurements must happen before Phase 2** so they aren't poisoned by the upgrade.

## Phase 2 — Upgrade (iterate per group)

After the plan is confirmed, upgrade the project's dependencies.

**If `isAngular` is true**: read [angular.md](./angular.md) and follow its step-by-step procedure to upgrade Angular packages via `ng update` **before** upgrading TypeScript or non-Angular packages. Do NOT pass Angular packages (`@angular/*`, `@angular-devkit/*`) to `typescript_upgrade_package_dependency_group`. Then continue below with TypeScript migration and non-Angular dependency groups.

**If `typeScriptMigrationNeeded` is true** (and Angular upgrades are already done, if applicable): read [typescript-migration.md](../typescript-migration/typescript-migration.md) for guidance — TypeScript itself must be upgraded before other packages. For Angular projects, cap the TypeScript upgrade at TypeScript 6.

For each remaining (non-Angular) dependency group:

1. **Upgrade** — Read [upgrade-packages.md](./upgrade-packages.md) for instructions on calling `typescript_upgrade_package_dependency_group`.
2. **Check the result** — If the tool reports success, move to the next group. If it reports `needs_regex_fixes`, generate regex-based fixes and submit them via `typescript_verify_upgrade` (see upgrade-packages.md for details). If regex fixes don't fully resolve the errors, fall back to direct file edits and verify again.
3. **Bundler build validation** — If `validateBundlerChanges` is true and this group has `containsBundlers: true`: call `typescript_build_package` with `rootDirectory` and `packageDirectory` before moving to the next group. The tool compares against the Phase 1 baseline — a failure here means this upgrade broke the bundler build. Fix any issues before proceeding.

## Phase 3 — Validation

After all dependency groups are upgraded, run validation based on the scan results:

1. **Post-upgrade compile — REQUIRED, do not skip.** Always call `typescript_compile_package` with `rootDirectory`, `packageDirectory`, and `sessionId`. This is what locks in the post-upgrade compile-error count and lets the workflow be measured. **Even if `typescript_verify_upgrade` already reported "complete" in Phase 2, you must still call `typescript_compile_package` here** — the verify-loop only updates per-package state; the workflow-level post-upgrade snapshot is recorded only by this tool. Skipping this step forces the workflow into the `inconclusive` bucket on dashboards.
2. **Test validation** — If `enableTestValidation` is true: read [test-validation.md](./test-validation.md) to run tests and compare results against the baseline. **Always invoke tests through `typescript_run_tests`**, not via raw `npm test` in the terminal/powershell.
3. **Runtime validation** — If `validateRuntime` is true: read [runtime-validation.md](./runtime-validation.md) to verify the application runs correctly. **Use the SAME route list you captured during the Phase 1 baseline** — passing different routes invalidates the comparison and dashboards will mark the workflow inconclusive.

## Phase 4 — Summary

After all groups are upgraded:

1. Call the `typescript_write_upgrade_summary` MCP tool with `rootDirectory` and a `content` string listing which packages were successfully upgraded and which failed. Pass the same `sessionId` you've been using throughout the workflow. The tool emits the workflow/summary observation event automatically — you do NOT need to call `typescript_report_telemetry` for the workflow outcome.
2. Present the returned summary to the user.

## Key Principles

1. **You are fully responsible** for gathering context and applying fixes. Use tools — never ask the user to do something a tool can do.
2. **Don't give up.** If your first approach fails, try an alternative. Exhaust all reasonable options before reporting failure.
3. **Preserve valid code.** Every change you make must produce syntactically valid TypeScript (`.ts` and `.tsx`).
4. **Work incrementally.** Upgrade and fix one dependency group at a time, verify, then move on.
5. **Run ONE tool at a time.** Wait for each MCP tool to complete before starting the next. Do NOT run multiple `typescript_upgrade_package_dependency_group` calls in parallel.
6. **Remember context.** Avoid unnecessary repetition of tool invocations with identical arguments unless required for validation or retrying fixes. Build on what you already know.
7. **Prefer minimal changes.** If editing `tsconfig.json` is simpler than rewriting application code, do that instead.
8. **When upgrading specific packages**, only upgrade what the user asked for (plus any peer dependencies they confirmed). Do not expand the scope to unrelated packages.