agentleFS
LedgerHQLedgerHQ/ledger-live/.agents/skills/legacy-migration/SKILL.md

legacy-migration

Skill627 starsChanged 10 days agoMITView on GitHub

Move code out of `libs/` or `apps/*/src` into the layers (`shared/`, `domain/`, `features/`) in three steps, addition, deprecation and deletion, and give a new-architecture package what only legacy code provides through injection (ports, thunk `extraArgument`) instead of an import. Use when moving, extracting or porting code out of `libs/` or `apps/*/src`, replacing a legacy module with a new package, deprecating or deleting legacy code, or when a new package seems to need a `libs/` import.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Only apps/ imports both sides.

    line 17
  2. Distinctive:

    Never re-export a legacy type from a new-architecture barrel.

    line 24
  3. Very specific:

    Delete once nothing imports the legacy code: search the import path and every exported name separately (static imports, require, jest.mock …

    line 65
  4. Distinctive:

    Delete the module, its tests, the app bridges that adapted it, and the restricted-import entries that named its paths.

    line 69

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Legacy migration

Code leaves libs/ and apps/*/src in three steps: addition, deprecation, deletion. Each step is its own PR and leaves develop working. structure-flow decides which layer receives the code; this skill covers how it gets there. The layer model and the status of each libs/ area live in the architecture guide.

Boundary rules this relies on

  • shared/, domain/ and features/ never import a libs/ package (scope:libs tag), neither as a declared dependency nor as a source import.
  • Only apps/ imports both sides. Legacy code may consume new code as migration glue, never the reverse.
  • No new exception. BOUNDARY_EXCEPTIONS in constraints.js lists the existing allowances for a new package to depend on a legacy one, each kept only until that legacy package leaves the repo. When a new package needs legacy code, inject it (below); never add an entry.
  • Never re-export a legacy type from a new-architecture barrel.

pnpm lint:boundaries enforces the import rules: it checks the Nx graph against the layer constraints, scans source imports under shared/, domain/ and features/ for legacy packages, and rejects manifests that declare a banned package. Run it before every migration commit.

1. Addition

Build the replacement in the lowest valid layer, with its tests, while the legacy code keeps working. Keep the public names when the new package is a drop-in replacement: callers then switch by changing an import path.

Example: #17239 added @features/platform-feature-flags as a Redux-backed drop-in replacement for the Context-based hooks of @ledgerhq/live-common/featureFlags (useFeature, useFeatureFlags, FeatureToggle), reading the slice that @shared/feature-flags owns. No caller moved in that PR.

2. Deprecation

Point every caller at the replacement and stop new ones from appearing:

  • Mark each legacy export @deprecated, naming the replacement package and export.
  • Migrate the callers. Legacy code that stays may import the new package.
  • Ban the old import in the apps with an eslint/no-restricted-imports pattern in their .oxlintrc.json, with importNamePattern and a message naming the new package. This ban is the only real guard: @deprecated alone blocks nothing. Both desktop and mobile set typescript/no-deprecated to error, but it is a type-aware rule and their lint scripts (oxlint src ... in each package.json) never pass --type-aware, so it reports nothing.
  • Notify open PRs still using the old path: impacting-prs.

Example: #20261 moved the currency accessors to @domain/entity-currency-crypto and @domain/entity-currency-fiat. Both apps' .oxlintrc.json reject findCryptoCurrencyById and its siblings from @ledgerhq/live-common/currencies with a message naming the domain packages. For the JSDoc form, see libs/types-live/src/feature.ts: "@deprecated Moved to @shared/feature-flags".

3. Deletion

Delete once nothing imports the legacy code: search the import path and every exported name separately (static imports, require, jest.mock factories, string literals). Where the package runs knip, let it confirm the exports are unused.

  • Delete the module, its tests, the app bridges that adapted it, and the restricted-import entries that named its paths.
  • A whole package that must stay published but that no workspace package may depend on goes into BANNED_DEPENDENCIES in constraints.js first; delete the package in a later PR.
  • Removing a public export from a package that stays needs a changeset on that package: create-changeset. A deleted package cannot appear in a changeset, since the changeset check rejects packages that are not in the workspace: the changeset names the packages that dropped it, and pending changesets that list it lose that entry (details).

Example: once both apps used @features/platform-feature-flags, #18237 deleted the live-common featureFlags module and the app feature-flag bridges. @ledgerhq/errors followed the package route: banned in BANNED_DEPENDENCIES by #20280, then dropped from libs/ by #20278.

Crossing the frontier with injection

A new package that needs behavior only legacy code has declares the contract itself and receives the implementation. The app, the only place allowed to import both sides, builds the implementation from legacy code and hands it over at the composition root.

Port: a type in the new package, implemented by the app and passed in.

// features/flow/flow-contacts-add-address/src/state/ports.ts
export type ContactsCurrencySelectionPort = Readonly<{
  selectCurrency(networkIds: readonly CryptoCurrency["id"][]): Promise<AddAddressCurrencySelection | null>;
}>;

Desktop implements it in useContactsCurrencySelectionAdapter.ts on top of the live-common modular drawer, and the Contacts screen view model hands it to the flow. The flow package never sees @ledgerhq/live-common.

Thunk extraArgument: for thunks and RTK Query endpoints, the contract is a typed slice of the store's extraArgument, built by an xxxExtra() function the package exports.

// apps/ledger-live-desktop/src/state-manager/configureStore.ts
thunk: {
  extraArgument: {
    ...accountDataExtra(accountDataSources(getState, dispatch)),
  },
},

@domain/api-account-data declares AccountDataSource; live-common implements it with createFullSyncSource, and each app's account-data-setup.ts (desktop, mobile) feeds it the legacy accounts and bridge cache. The domain package reads its router from extraArgument and stays legacy-free.

More patterns and their trade-offs: references/injection.md.

Checklist

  • The target layer follows structure-flow.
  • Addition, deprecation and deletion land as separate PRs.
  • No new package imports or declares a libs/ package; BOUNDARY_EXCEPTIONS is unchanged.
  • Legacy behavior reaches new code through a port or extraArgument wired in apps/.
  • pnpm lint:boundaries passes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.