123 lines
4.6 KiB
Markdown
123 lines
4.6 KiB
Markdown
---
|
|
name: upgrade-agent-native
|
|
description: >-
|
|
Bring an older Agent Native app or workspace current. Use when updating
|
|
@agent-native/core, fixing a broken upgrade, or when tempted to patch or
|
|
override core/dispatch packages to make an old branch run.
|
|
scope: dev
|
|
metadata:
|
|
internal: true
|
|
---
|
|
|
|
# Upgrade Agent Native
|
|
|
|
## Rule
|
|
|
|
When an older Agent Native app/branch needs to run on current packages, use
|
|
`agent-native upgrade`. Never "fix" upgrade breakage with
|
|
`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
|
|
edits under `node_modules/@agent-native/*` — especially not against
|
|
`@agent-native/core` or `@agent-native/dispatch`.
|
|
|
|
## Why
|
|
|
|
Agents often respond to a failed core bump by inventing framework patches and
|
|
dispatch behavior overrides. That hides the real app-level break, drifts from
|
|
upstream, and makes the next upgrade worse. The supported path is bump →
|
|
install → refresh scaffold skills → verify, then fix **app** code only.
|
|
|
|
## How
|
|
|
|
1. **Preview migration codemods first**
|
|
|
|
```bash
|
|
npx @agent-native/core@latest upgrade --codemods
|
|
```
|
|
|
|
Codemods are preview-by-default: read the diff before applying it. Do not
|
|
manually edit imports before running this command; the migration manifest is
|
|
the source of truth for renamed specifiers and symbols.
|
|
|
|
2. **Apply the reviewed codemods, then run the upgrade**
|
|
|
|
```bash
|
|
npx @agent-native/core@latest upgrade --codemods --yes
|
|
npx @agent-native/core@latest upgrade
|
|
```
|
|
|
|
Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
|
|
`agent-native upgrade`.
|
|
|
|
What it does:
|
|
|
|
- Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
|
|
- Rewrites non-local `@agent-native/*` dependency pins to `latest`
|
|
- Runs the package manager install
|
|
- Runs `skills update scaffold --project`
|
|
- Runs `typecheck` when the project has that script
|
|
|
|
3. **Pull upstream template changes (optional, separate from the bump)**
|
|
|
|
`agent-native upgrade` moves package versions. It never touches files that
|
|
were copied out of a template at scaffold time, so template fixes and
|
|
improvements do not arrive with a bump.
|
|
|
|
```bash
|
|
agent-native template status # recorded ref vs latest, drift counts
|
|
agent-native template diff # what upstream changed, read-only
|
|
agent-native template sync # 3-way merge it into the app
|
|
```
|
|
|
|
`sync` defaults to the ref matching the installed `@agent-native/core`, so
|
|
run it after `upgrade`. It merges per file against a pristine baseline
|
|
stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
|
|
did not touch are left alone, and real collisions get conflict markers.
|
|
After resolving markers, run `agent-native template accept` — the baseline
|
|
deliberately does not advance past an unresolved merge.
|
|
|
|
Apps scaffolded before provenance existed have no baseline. Create one
|
|
with `agent-native template baseline` before the first sync.
|
|
|
|
4. **If upgrade or typecheck fails**
|
|
|
|
- Read the concrete error
|
|
- Fix **app** source, actions, config, or env — not framework packages
|
|
- Re-run `agent-native upgrade` or `pnpm typecheck`
|
|
- Stop and ask the user if you cannot fix the app-level error
|
|
|
|
Intentional app-level UI customization is a separate workflow. Read
|
|
`customizing-agent-native` when the product needs to own a selectively
|
|
copied component; do not use that path to reproduce framework runtime
|
|
behavior or hide version skew.
|
|
|
|
5. **Dry-run / partial runs**
|
|
|
|
```bash
|
|
agent-native upgrade --dry-run
|
|
agent-native upgrade --skip-verify
|
|
agent-native upgrade --skip-install # package.json bumps only
|
|
agent-native doctor --only migration-manifest
|
|
```
|
|
|
|
`migration-manifest` has no opt-out. Run it in CI before upgrading to find
|
|
imports that will break, then use `npx @agent-native/core@latest upgrade --codemods`
|
|
to preview the supported rewrite.
|
|
|
|
## Don't
|
|
|
|
- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
|
|
`patchedDependencies` for any `@agent-native/*` package
|
|
- Don't edit `node_modules/@agent-native/core` or
|
|
`node_modules/@agent-native/dispatch`
|
|
- Don't invent local "dispatch behavior" shims to paper over version skew
|
|
- Don't keep iterating with more framework patches after a failed install
|
|
- Don't skip `skills update scaffold --project` after a core bump (the
|
|
upgrade command does this for you)
|
|
|
|
## Related Skills
|
|
|
|
- **self-modifying-code** — Tier 4: framework packages are off limits
|
|
- **agent-native-docs** — version-matched docs after the bump
|
|
- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches
|
|
- **portability** — keep app code provider-agnostic across upgrades
|