@terreno/agent-plugin 0.0.0-stage → 58.0.0-beta.2

package/skills/upgrading-terreno/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: upgrading-terreno
+description: >-
+  Upgrade Terreno lockstep @terreno/* packages. Trigger with "upgrade Terreno",
+  "bump @terreno packages", "update to the latest Terreno", or "upgrade terreno version".
+targets: ['*']
+---
+
+# Upgrade Terreno
+
+Perform a lockstep `@terreno/*` upgrade. Human-facing twin: `docs/how-to/upgrade-terreno.md`. Ordering detail: [references/ordering.md](references/ordering.md).
+
+Do **not** duplicate Expo SDK steps. At step 6 invoke the `upgrading-expo` skill by name.
+
+## Preconditions (refuse, do not warn)
+
+Stop immediately and do not mutate the tree if any of these fail:
+
+1. `git status --short` is **not empty** — refuse. Ask the user to commit or stash. A dirty tree has no safe rollback.
+2. The current branch is the default branch (`master` or `main`) — refuse. Create or switch to a feature branch first.
+3. Tests on this HEAD have not been shown passing — refuse. Run the app’s usual test command once so later failures are attributable to the upgrade.
+
+## Determine versions
+
+1. Prefer MCP `application_info` from `terreno-mcp-local`.
+2. Else read every `package.json` that lists `@terreno/*`.
+3. `fromVersion` = lowest installed `@terreno/*` semver. `toVersion` = user target or latest GitHub release.
+
+## Fetch notes
+
+Call hosted MCP `terreno_get_upgrade_guide` with `fromVersion` and `toVersion`. Read every concatenated note. A “no bundled notes” line means **unknown**, not no-op.
+
+## Syncdb / RTK platform migration
+
+If `toVersion` is `58.0.0` or later and the app still imports `@terreno/rtk`, `@reduxjs/toolkit`,
+`react-redux`, `redux-persist`, or `@rtk-query/codegen-openapi`, **stop**. Terreno 58 deletes
+`@terreno/rtk` and Redux; this is a platform migration, not a routine bump.
+
+Offer exactly two options; do not automate the data-layer migration inside this flow:
+
+1. Bump to the last 57.x release only (stays on `@terreno/rtk`).
+2. Migrate first with `docs/how-to/migrate-rtk-to-syncdb.md` (every removed export → its
+   replacement) and the 58.0.0 upgrade note, then return to this flow.
+
+Wait for the user to pick.
+
+If `fromVersion` is before `56.0.0-beta.2` and `toVersion` is below 58, the range crosses the
+syncdb introduction; offer the same two options (routine bump, or migrate collection CRUD to
+syncdb with the same guide).
+
+## Plan and confirm (no mutations yet)
+
+Print, then **stop until the user confirms**:
+
+- `fromVersion` and `toVersion`
+- Notes returned (or the gap warning)
+- Packages affected
+- Ordered steps 1–10 below
+
+Do not install, edit lockfiles, or regenerate the client before confirmation.
+
+If the caller is an unattended agent whose **invoking task already names** `fromVersion`, `toVersion`, and authorizes the bump (for example Pick Task 5.1), print the same plan into the transcript and treat that task as confirmation. Do not skip the printed plan. Do not skip the stop when a human is in the loop.
+
+## Ordered steps (verification gate after each phase)
+
+Match `docs/how-to/upgrade-terreno.md`. After each phase, run its gate. **If compile or tests fail, stop. Do not continue.**
+
+Compile means a **typecheck** (`tsc --noEmit` or `bun run compile` when that script typechecks). `bun build` / bundlers that ignore TypeScript errors are not a passing gate.
+
+1. Clean git tree + branch (already enforced).
+2. Record current `@terreno/*` versions (`application_info` / `package.json`).
+3. `terreno_get_upgrade_guide` for the range (already fetched). Apply note migrations that are code edits **after** confirmation, in this same order.
+4. Bump **backend** packages: `@terreno/api`, `@terreno/test`, `@terreno/admin-backend`, `@terreno/blocks` (when the app lists it; `ai` and `ui` depend on it), `@terreno/ai`, `@terreno/api-health`, `@terreno/comms`, `@terreno/feature-flags`, `@terreno/mcp`. `bun install`.
+5. Backend `bun run compile` and backend tests. Gate: both pass.
+6. Expo SDK — invoke **`upgrading-expo`**. Skip only when Terreno majors do not require a new Expo (same Expo line). Gate: `npx expo-doctor` / install --fix as that skill requires; native rebuild if peers moved.
+7. Bump **frontend** packages: `@terreno/ui`, `@terreno/syncdb`, `@terreno/admin-frontend`, `@terreno/admin-spa`. `bun install`. (`@terreno/rtk` stops at 57.x; on 58+ remove it.)
+8. Start the **upgraded** backend. Regenerate the typed client (`bun run sdk`, and `bun run sync-sdk` when the app has synced collections).
+9. `bun run compile`, `bun run lint`, and the app tests. Gate: all pass.
+10. Run the app, log in, exercise changed screens.
+
+## Failure handling
+
+Report all three:
+
+1. What succeeded (last passing step number).
+2. What failed (command and first error line).
+3. Rollback: `git reset --hard` on this branch, or `git checkout <pre-upgrade-sha> -- package.json bun.lock && bun install`.
+
+On a **multi-version** jump failure: retry **version by version** (`from` → next recorded note version → …) to isolate the breaking version. Keep the failing consumer file. The first version whose typecheck fails is the isolate. Do not continue past a failed compile or test run.
+
+## Final report
+
+Print `fromVersion` → `toVersion`, notes applied, packages bumped, gates that passed, and remaining human follow-ups (native store binaries, the 58 RTK-to-syncdb migration if deferred).

package/skills/upgrading-terreno/references/ordering.md

@@ -0,0 +1,40 @@
+# Upgrade ordering
+
+Why the `upgrading-terreno` skill bumps packages in a fixed order. Packages below are every published job in `.github/workflows/publish-on-tag.yml`.
+
+## Package classes
+
+| Class | Packages (`publish-on-tag.yml` job) |
+| --- | --- |
+| Backend | `api`, `test`, `admin-backend`, `blocks`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp` |
+| Frontend | `ui`, `syncdb`, `admin-frontend`, `admin-spa` |
+
+`blocks` holds contracts that both `ai` and `ui` depend on, so it moves with the backend step.
+
+`demo` and the example apps are not published. `rtk` was published through 57.x and removed in 58.
+
+## Backend before frontend
+
+The OpenAPI document from the running backend is the contract `bun run sdk` consumes. Regenerating the client against an **un-upgraded** backend produces hooks for the old surface: new routes and fields are missing, and consumer screens fail at **compile** (`Property X does not exist on type …` or a missing generated hook).
+
+Bump and compile backend packages first, then start that backend, then regenerate.
+
+## Typed client only after the new backend is up
+
+`example-frontend` codegen reads `http://localhost:4000/openapi.json` (or `OPENAPI_URL`). If the process is still the old binary, `store/apiSdk.ts` (and `store/syncDbSdk.ts`) are silently stale. Symptom: runtime 404 on new paths or TypeScript errors after you edit screens to call new endpoints that the SDK never emitted.
+
+## Expo before `@terreno/ui`
+
+`ui/package.json` `peerDependencies` pin `react-native` to the Expo line (for example `~0.86.0` on Terreno 57). Installing `@terreno/ui@57` while the app is still on Expo 54 / RN 0.81 fails peer resolution or breaks at Metro/native build. Symptom: `ERESOLVE` / unmet peer, or a native module ABI mismatch after `expo start`.
+
+Run `upgrading-expo` (skill name) before bumping Terreno frontend packages when the Terreno major tracks a new Expo SDK.
+
+## Violation symptoms
+
+| If you… | What breaks |
+| --- | --- |
+| Bump `@terreno/ui` before Expo | Unmet `react-native` peers; native rebuild required anyway |
+| Run `bun run sdk` before upgrading/starting the backend | Generated client missing new operations; compile errors in screens |
+| Bump frontend `@terreno/*` before backend compile | Client types and server handlers disagree; 4xx/5xx on new fields |
+| Mix `@terreno/api@57` with `@terreno/ui@0.31` | Unsupported; lockstep publish tags one version for every package |
+| Continue after a failed `compile` | Half-upgraded lockfile; rollback is unclear |