Add vendor migrations to blocks

[nsams]

An alternative to #6390, solving the same problem with a smaller API.

A block's version is currently a single counter, so only one party can advance it. That works while an application owns all of a block's migrations, but not when the library providing the block ships migrations as well.

Examples where this is a problem:

• createTipTapRichTextBlock with migrateFromDraftJs (currently we workaround the limitation by letting the vendor use version 1 and application migrations must start at 2)
• future tiptap migrations (will be needed in Replace the TipTap block's paragraph/heading options with configurable textBlocks #6382) - while keeping the option for project migrations
• existing library blocks that have migrations: Youtube and ExternalLink currently can't have project migrations

Proposed solution

Add a second migrateVendor, a sibling of the migrate option the application fills. They count from 1 in $$vendorVersion, independently of the block's version, and run before the block's own migrations. migrate stays exactly as it is, and because the two options are separate, a library never merges its migrations into the application's object and neither side can overwrite the other's.

example (in real world this would be split in library and project):

createBlock(VideoBlockData, VideoBlockInput, {
    name: "Video",
    migrate: { //defined in project
        version: 1,
        migrations: typeSafeBlockMigrationPipe([ChangeTitleMigration]),
    },
    migrateVendor: { //defined in library
        version: 1,
        migrations: typeSafeBlockMigrationPipe([ChangeAspectRatioMigration]),
    },
});

naming

I decided to name the new counter "vendor", because it is a migration from a 3rd party vendor. Other option would be "library". A single vendor counter is enough, any other package providing blocks should also use vendor migrations.

Further information

Differences to #6390:

• There are exactly two chains instead of freely named scopes, and the library's chain is its own option rather than a nested scopes record inside the application's.
• The application-facing API is untouched: migrate keeps its shape, and $$version its meaning — only $$vendorVersion is added next to it.
• Vendor migrations run before the block's own migrations, instead of after.
• The migrations Dextinity ships actually move into the new chain, which is what frees the block's versions for applications. Their legacy counter is split before any migration runs, so a chain can't seed itself from a counter another chain has just advanced.

Note: extending eg. Youtube block is currently not possible because Data and Input classes are not exported.

Session: https://claude.ai/code/session_01ByXXwcnSeVYzQfLujMknXH

[nsams]

@greptileai

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with no outstanding correctness, security, or repository-rule findings.

Summary

This PR introduces an independent vendor migration chain for library-provided blocks.

• Adds migrateVendor and the $$vendorVersion counter, with vendor migrations running before application migrations.
• Splits legacy $$version values for migrations moved into the vendor chain.
• Preserves inherited vendor migrations and rejects conflicting vendor chains.
• Moves existing Dextinity migrations to the vendor chain and updates tests, documentation, and the demo.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Load raw block data] --> B{Legacy vendor migrations configured?}
    B -->|Yes and no vendor counter| C[Split legacy version into application and vendor counters]
    B -->|No| D[Use existing counters]
    C --> E[Run pending vendor migrations]
    D --> E
    E --> F[Run pending application migrations]
    F --> G[Create block data]
    G --> H[Save with current version counters]

Loading

_{Reviews (3) · Last reviewed commit: "cms-api: Take the migrations applyMigrat..."}

[nsams]

@greptileai review