|
| 1 | +--- |
| 2 | +name: perps-core-sync |
| 3 | +description: Sync the perps controller from mobile to the core monorepo with change detection, automated validation, failure resolution, and post-sync commit guidance. Use after perps controller changes land in mobile. |
| 4 | +--- |
| 5 | + |
| 6 | +# Perps Core Sync |
| 7 | + |
| 8 | +## Purpose |
| 9 | + |
| 10 | +Use this skill to sync `app/controllers/perps/` from mobile to `packages/perps-controller/src/` in the core monorepo. The sync is driven by `scripts/perps/validate-core-sync.sh` — a 9-step pipeline (preflight, conflict check, copy, install, verify, eslint fix, build, lint, write sync state). |
| 11 | + |
| 12 | +Use when: |
| 13 | + |
| 14 | +- New commits touch `app/controllers/perps/` since the last sync |
| 15 | +- A perps PR is merged and needs to propagate to core |
| 16 | +- You need to verify mobile changes are core-compatible before pushing |
| 17 | + |
| 18 | +Do not use when: |
| 19 | + |
| 20 | +- Changes are UI-only (`app/components/UI/Perps/`) — these don't sync |
| 21 | +- Changes are test-only (`*.test.ts`) — tests are excluded from sync |
| 22 | +- The core repo is not checked out locally |
| 23 | + |
| 24 | +## Pre-Sync: Detect Changes |
| 25 | + |
| 26 | +Read the sync state from core to find what changed since the last sync: |
| 27 | + |
| 28 | +```bash |
| 29 | +cat <core-path>/packages/perps-controller/.sync-state.json |
| 30 | +``` |
| 31 | + |
| 32 | +Extract `lastSyncedMobileCommit` and run: |
| 33 | + |
| 34 | +```bash |
| 35 | +# Commits since last sync |
| 36 | +git log <lastSyncedMobileCommit>..HEAD --oneline -- app/controllers/perps/ |
| 37 | + |
| 38 | +# File-level summary (excluding tests) |
| 39 | +git diff <lastSyncedMobileCommit>..HEAD --stat -- app/controllers/perps/ ':!*.test.ts' |
| 40 | +``` |
| 41 | + |
| 42 | +Pay special attention to: |
| 43 | + |
| 44 | +- **New files** — need exports wired in core's `index.ts`, may need `tsconfig` references or new dependencies |
| 45 | +- **Deleted files** — rsync `--delete` handles removal, but verify no stale imports remain in core |
| 46 | +- **Changes to `PerpsPlatformDependencies`** — DI interface changes affect extension consumers |
| 47 | +- **Public API changes** — state shape, method signatures, event names affect all consumers |
| 48 | + |
| 49 | +## Execute Sync |
| 50 | + |
| 51 | +```bash |
| 52 | +bash scripts/perps/validate-core-sync.sh --core-path <core-path> |
| 53 | +``` |
| 54 | + |
| 55 | +Options: |
| 56 | + |
| 57 | +- `--skip-build` — skip the build step for faster iteration when debugging lint/copy issues |
| 58 | +- `--skip-test` — skip the test step for faster iteration |
| 59 | +- `--verbose` — show full output for every step (useful for debugging) |
| 60 | + |
| 61 | +The script runs these 12 steps in order: |
| 62 | + |
| 63 | +| Step | What it does | |
| 64 | +| ----------------------- | --------------------------------------------------------------------------------------- | |
| 65 | +| 1. Pre-flight checks | Confirms mobile source, core destination, required tools | |
| 66 | +| 2. Conflict check | Fetches origin/main, checks for upstream perps-controller changes, validates sync state | |
| 67 | +| 3. Copy source files | rsync `.ts` files (excluding tests, mocks, fixtures) | |
| 68 | +| 4. Install dependencies | `yarn install` in core | |
| 69 | +| 5. Verify build fixes | Checks for `__DEV__`, mobile imports, closure fixes | |
| 70 | +| 6. ESLint auto-fix | Runs `--fix`, `--suppress-all`, `--prune-suppressions`, checks suppression delta | |
| 71 | +| 7. Format fix (oxfmt) | Runs `yarn lint:misc --write` — core uses oxfmt, not prettier | |
| 72 | +| 8. Build | `yarn workspace @metamask/perps-controller build` | |
| 73 | +| 9. Lint | Final lint pass to confirm zero violations | |
| 74 | +| 10. Test | `yarn workspace @metamask/perps-controller test` — catches DI/fixture mismatches | |
| 75 | +| 11. Changelog check | Verifies `CHANGELOG.md` has been updated (core CI requirement) | |
| 76 | +| 12. Write sync state | Updates `.sync-state.json` with commit hashes and checksum | |
| 77 | + |
| 78 | +## Failure Resolution |
| 79 | + |
| 80 | +| Failure | Cause | Fix | |
| 81 | +| -------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 82 | +| `__DEV__` found | Mobile code uses `__DEV__` guard | Replace with `false` in the mobile source file, or route through `PerpsPlatformDependencies` for environment-aware behavior. Fix in mobile, then re-sync. | |
| 83 | +| Mobile imports (Engine, react-native, Sentry, DevLogger) | Direct platform import in controller | Route through `PerpsPlatformDependencies` (DI). All platform services must come through the `infrastructure` constructor param. Fix in mobile. | |
| 84 | +| Suppression delta increase | Sync introduces new ESLint violations | Fix violations in mobile first (e.g., `'x' in y` → `hasProperty(y, 'x')` from `@metamask/utils`). Re-run sync after fixing. | |
| 85 | +| Build failure | Missing tsconfig references, missing dependencies, type errors | Check `packages/perps-controller/tsconfig.json` references. Ensure new imports have corresponding `dependencies` in `package.json`. | |
| 86 | +| Lint failure after fix | Auto-fix didn't resolve all issues | Re-run the eslint fix step. If persistent, check for new rule violations that need manual fixes in mobile. | |
| 87 | +| Format fix failure | oxfmt can't auto-fix some files | Check for syntax errors that prevent parsing. Core uses `oxfmt` (not prettier) for TS formatting. | |
| 88 | +| Test failure | Test fixtures missing new DI dependencies | Add mocks for new `PerpsPlatformDependencies` fields (e.g., `diskCache`) in `tests/defer-eligibility.test.ts`. | |
| 89 | +| Changelog check failure | `CHANGELOG.md` not updated | Add entries under `## [Unreleased]` with `### Added`, `### Fixed`, `### Changed` sections linking to the PR. | |
| 90 | +| Conflict check: behind origin/main | Someone pushed perps-controller changes to main | `cd <core-path> && git merge origin/main` before re-running sync. | |
| 91 | +| Conflict check: checksum mismatch | Core source was hand-edited since last sync | Review the edits. Either port them back to mobile or discard and re-sync. | |
| 92 | + |
| 93 | +## Post-Sync |
| 94 | + |
| 95 | +After all 12 steps pass: |
| 96 | + |
| 97 | +1. **Review the diff in core:** |
| 98 | + |
| 99 | + ```bash |
| 100 | + cd <core-path> && git diff --stat |
| 101 | + ``` |
| 102 | + |
| 103 | +2. **Update `CHANGELOG.md`** before committing. Core CI requires entries under `## [Unreleased]`. Sections must follow [Keep a Changelog](https://keepachangelog.com/) order: |
| 104 | + |
| 105 | + ``` |
| 106 | + ### Added — new features, exports, files |
| 107 | + ### Changed — refactors, dependency bumps |
| 108 | + ### Deprecated — soon-to-be-removed features |
| 109 | + ### Removed — removed features |
| 110 | + ### Fixed — bug fixes |
| 111 | + ### Security — vulnerability fixes |
| 112 | + ``` |
| 113 | + |
| 114 | + Each entry must link to the PR: `([#NNNN](https://github.com/MetaMask/core/pull/NNNN))`. |
| 115 | + Validate locally: `yarn workspace @metamask/perps-controller changelog:validate` |
| 116 | + |
| 117 | +3. **Commit in core** with conventional format: |
| 118 | + |
| 119 | + ``` |
| 120 | + feat(perps): sync controller from mobile |
| 121 | +
|
| 122 | + Syncs app/controllers/perps/ from mobile commit <short-hash>. |
| 123 | +
|
| 124 | + Changes: |
| 125 | + - <summarize key changes from the pre-sync commit list> |
| 126 | + ``` |
| 127 | + |
| 128 | +4. **Verify `.sync-state.json` was updated** — it should contain the current mobile HEAD commit. |
| 129 | + |
| 130 | +5. **Check suppression count** — if non-zero, note it in the PR description. Target is zero suppressions. |
| 131 | + |
| 132 | +6. **Use `--verbose` when debugging** — without it, step output is captured to temp files and only shown on failure. With `--verbose`, all output streams to the terminal. |
| 133 | + |
| 134 | +## Portability Rules |
| 135 | + |
| 136 | +Reference: `docs/perps/perps-review-antipatterns.md` (Controller Portability section). |
| 137 | + |
| 138 | +- **No `__DEV__`** — must not appear in controller files. Core has no React Native dev mode. |
| 139 | +- **No mobile imports** — no `react-native`, `Engine`, `Sentry`, `DevLogger`. Everything through `PerpsPlatformDependencies` DI. |
| 140 | +- **No direct controller imports from app code** — app files must import from `@metamask/perps-controller`, not relative paths. |
| 141 | +- **Public API = publisher contract** — changing state shape, method signatures, or event names affects extension consumers. Coordinate breaking changes. |
| 142 | +- **New dependencies must be in DI interface** — controller code must not reach outside its boundary. |
0 commit comments