Initial commit from agent-native create
This commit is contained in:
agent-native
@@ -0,0 +1,122 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user