@grafana/create-plugin 5.17.0 → 5.18.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+# v5.18.0 (Wed Feb 19 2025)
+
+#### 🚀 Enhancement
+
+- Feat: Create Plugin updates as migrations [#1479](https://github.com/grafana/plugin-tools/pull/1479) ([@jackw](https://github.com/jackw) [@leventebalogh](https://github.com/leventebalogh))
+
+#### 🐛 Bug Fix
+
+- chore(deps): update grafana patch dependencies to v11.5.2 [#1549](https://github.com/grafana/plugin-tools/pull/1549) ([@renovate[bot]](https://github.com/renovate[bot]))
+
+#### Authors: 3
+
+- [@renovate[bot]](https://github.com/renovate[bot])
+- Jack Westbrook ([@jackw](https://github.com/jackw))
+- Levente Balogh ([@leventebalogh](https://github.com/leventebalogh))
+
+---
+
 # v5.17.0 (Fri Feb 14 2025)
 
 #### 🚀 Enhancement

package/CONTRIBUTING.md

@@ -33,7 +33,8 @@ npm install
 ├── src // Executable code
 │   ├── bin // the entrypoint file
 │   ├── commands // Code that runs commands
-│   └── utils // Utilities used by commands
+│   ├── utils // Utilities used by commands
+│   └── migrations // Migrations for updating create-plugins
 └── templates // Handlebars templates
     ├── _partials // Composable parts of a template
     ├── app // Templates specific to scaffolding an app plugin
@@ -81,3 +82,118 @@ _Work in progress._
 The templates are used by Handlebars to scaffold Grafana plugins. Whilst they appear to be the intended filetype they are infact treated as markdown by Handlebars when it runs. As such we need to be mindful of syntax and to [escape particular characters](https://handlebarsjs.com/guide/expressions.html#whitespace-control) where necessary. The [github/ci.yml](./templates/github/ci/.github/workflows/ci.yml) file is a good example of this.
 
 Note that certain files are intentionally named differently (e.g. npmrc, package.json). This is done due to other tooling preventing the files from being packaged for NPM or breaking other tools during local development.
+
+### Migrations
+
+> **Note:** Migrations are currently behind the `--experimental-updates` flag and are not enabled by default.
+
+Migrations are scripts that update a particular aspect of a project created with create-plugin. When users run `@grafana/create-plugin@latest update`, the command compares their project's version against the running package version and executes any necessary migrations to bring their project up to date.
+
+```js
+└── src/
+    ├── migrations/
+    │   └── scripts/ // The directory where migration scripts live
+    │       ├── add-webpack-profile.test.ts // migration script tests
+    │       └── add-webpack-profile.ts // migration script
+    ├── context.ts // The context object that is passed to the migration scripts
+    ├── manager.ts // The manager object that is used to run the migration scripts
+    ├── migrations.ts // The configuration that registers the migration scripts
+    └── utils.ts // The utilities used by the migration scripts
+```
+
+#### How do migrations run?
+
+The update command follows these steps:
+
+1. Checks the current project version (`projectCpVersion`) and package version (`packageCpVersion`).
+2. If the project version is greater than or equal to the package version, exits early.
+3. Identifies all migrations needed between the project version and package version.
+4. Executes migrations sequentially.
+5. If the `--commit` flag is passed, it will commit changes after each migration.
+
+#### How to add a migration?
+
+1. Create a new migration script file with a descriptive name (e.g. `add-webpack-profile.ts`)
+2. Register your migration in `migrations.ts`:
+
+   ```typescript
+   migrations: {
+      'add-webpack-profile': {
+         version: '5.13.0',
+         description: 'Update build command to use webpack profile flag.',
+         migrationScript: './scripts/add-webpack-profile.js',
+      },
+   },
+   ```
+
+3. Write your migration script:
+
+   The migration script makes changes to files in a Grafana plugin to bring updates or improvements to the project. It should be isolated to a single task (e.g. add profile flag to webpack builds) rather than update the entire .config directory and all the projects dependencies.
+
+   > **Note:** The migration script must use the context to access the file system and return the updated context.
+
+   ```typescript
+   import { Context } from '../context.js';
+
+   export default async function (context: Context): Promise<Context> {
+     // Your migration logic here. for example:
+     // update files, delete files, add files, rename files, etc.
+     // Once done, return the updated context.
+     return context;
+   }
+   ```
+
+#### How to test a migration?
+
+Migrations should be thoroughly tested using the provided testing utilities. Create a test file alongside your migration script (e.g., `add-webpack-profile.test.ts`).
+
+```typescript
+import migrate from './add-webpack-profile.js';
+import { createDefaultContext } from '../test-utils.js';
+
+describe('Migration - append profile to webpack', () => {
+  test('should update the package.json', async () => {
+    // 1. Set up a test context with some default files.
+    const context = await createDefaultContext();
+
+    // 2. Create some file state to test against.
+    await context.updateFile(
+      './package.json',
+      JSON.stringify({
+        scripts: {
+          build: 'webpack -c ./.config/webpack/webpack.config.ts --env production',
+        },
+      })
+    );
+
+    // 3. Run the migration function and get the updated context.
+    const updatedContext = await migrate(context);
+
+    // 4. Assert expected changes
+    expect(await updatedContext.getFile('./package.json')).toMatch(
+      'webpack -c ./.config/webpack/webpack.config.ts --profile --env production'
+    );
+  });
+});
+```
+
+It is important that migration scripts can run multiple times without making additional changes to files. To make it easy to test this you can make use of the `.toBeIdempotent()` test matcher.
+
+```typescript
+describe('Migration - append profile to webpack', () => {
+  it('should not make additional changes when run multiple times', async () => {
+    const context = await createDefaultContext();
+
+    await context.updateFile(
+      './package.json',
+      JSON.stringify({
+        scripts: {
+          build: 'webpack -c ./.config/webpack/webpack.config.ts --env production',
+        },
+      })
+    );
+
+    await expect(migrate).toBeIdempotent(context);
+  });
+});
+```

package/dist/commands/update.command.js

@@ -1,78 +1,38 @@
-import chalk from 'chalk';
-import { UDPATE_CONFIG } from '../constants.js';
-import { printBlueBox, printRedBox } from '../utils/utils.console.js';
-import { getOnlyExistingInCwd, removeFilesInCwd } from '../utils/utils.files.js';
+import { standardUpdate } from './update.standard.command.js';
+import { migrationUpdate } from './update.migrate.command.js';
 import { isGitDirectory, isGitDirectoryClean } from '../utils/utils.git.js';
-import { updateGoSdkAndModules } from '../utils/utils.goSdk.js';
-import { updateNpmScripts, updatePackageJson } from '../utils/utils.npm.js';
-import { getPackageManagerFromUserAgent } from '../utils/utils.packageManager.js';
-import { isPluginDirectory, updateDotConfigFolder } from '../utils/utils.plugin.js';
-import { getGrafanaRuntimeVersion, getVersion } from '../utils/utils.version.js';
+import { printRedBox } from '../utils/utils.console.js';
+import chalk from 'chalk';
+import { isPluginDirectory } from '../utils/utils.plugin.js';
 export const update = async (argv) => {
-    const { packageManagerName } = getPackageManagerFromUserAgent();
-    try {
-        if (!(await isGitDirectory()) && !argv.force) {
-            printRedBox({
-                title: 'You are not inside a git directory',
-                content: `In order to proceed please run "git init" in the root of your project and commit your changes.\n
+    if (!(await isGitDirectory()) && !argv.force) {
+        printRedBox({
+            title: 'You are not inside a git directory',
+            content: `In order to proceed please run "git init" in the root of your project and commit your changes.\n
 (This check is necessary to make sure that the updates are easy to revert and don't mess with any changes you currently have.
 In case you want to proceed as is please use the ${chalk.bold('--force')} flag.)`,
-            });
-            process.exit(1);
-        }
-        if (!(await isGitDirectoryClean()) && !argv.force) {
-            printRedBox({
-                title: 'Please clean your repository working tree before updating.',
-                subtitle: '(Commit your changes or stash them.)',
-                content: `(This check is necessary to make sure that the updates are easy to revert and don't mess with any changes you currently have.
+        });
+        process.exit(1);
+    }
+    if (!(await isGitDirectoryClean()) && !argv.force) {
+        printRedBox({
+            title: 'Please clean your repository working tree before updating.',
+            subtitle: '(Commit your changes or stash them.)',
+            content: `(This check is necessary to make sure that the updates are easy to revert and don't mess with any changes you currently have.
 In case you want to proceed as is please use the ${chalk.bold('--force')} flag.)`,
-            });
-            process.exit(1);
-        }
-        if (!isPluginDirectory() && !argv.force) {
-            printRedBox({
-                title: 'Are you inside a plugin directory?',
-                subtitle: 'We couldn\'t find a "src/plugin.json" file under your current directory.',
-                content: `(Please make sure to run this command from the root of your plugin folder. In case you want to proceed as is please use the ${chalk.bold('--force')} flag.)`,
-            });
-            process.exit(1);
-        }
-        await updateDotConfigFolder();
-        updateNpmScripts();
-        updatePackageJson({
-            onlyOutdated: true,
-            ignoreGrafanaDependencies: false,
         });
-        await updateGoSdkAndModules(process.cwd());
-        const filesToRemove = getOnlyExistingInCwd(UDPATE_CONFIG.filesToRemove);
-        if (filesToRemove.length) {
-            removeFilesInCwd(filesToRemove);
-        }
-        printBlueBox({
-            title: 'Update successful ✔',
-            content: `${chalk.bold('@grafana/* package version:')} ${getGrafanaRuntimeVersion()}
-${chalk.bold('@grafana/create-plugin version:')} ${getVersion()}
-
-${chalk.bold.underline('Next steps:')}
-- 1. Run ${chalk.bold(`${packageManagerName} install`)} to install the package updates
-- 2. Check if you encounter any breaking changes
-  (refer to our migration guide: https://grafana.com/developers/plugin-tools/migration-guides/update-from-grafana-versions/)
-${chalk.bold('Do you have questions?')}
-Please don't hesitate to reach out in one of the following ways:
-- Open an issue in https://github.com/grafana/plugin-tools
-- Ask a question in the community forum at https://community.grafana.com/c/plugin-development/30
-- Join our community slack channel at https://slack.grafana.com/`,
+        process.exit(1);
+    }
+    if (!isPluginDirectory() && !argv.force) {
+        printRedBox({
+            title: 'Are you inside a plugin directory?',
+            subtitle: 'We couldn\'t find a "src/plugin.json" file under your current directory.',
+            content: `(Please make sure to run this command from the root of your plugin folder. In case you want to proceed as is please use the ${chalk.bold('--force')} flag.)`,
         });
+        process.exit(1);
     }
-    catch (error) {
-        if (error instanceof Error) {
-            printRedBox({
-                title: 'Something went wrong while updating your plugin.',
-                content: error.message,
-            });
-        }
-        else {
-            console.error(error);
-        }
+    if (argv.experimentalUpdates) {
+        return await migrationUpdate(argv);
     }
+    return await standardUpdate();
 };

package/dist/commands/update.migrate.command.js

@@ -0,0 +1,27 @@
+import { gte } from 'semver';
+import { getMigrationsToRun, runMigrations } from '../migrations/manager.js';
+import { getConfig } from '../utils/utils.config.js';
+import { getVersion } from '../utils/utils.version.js';
+import { printHeader } from '../utils/utils.console.js';
+export const migrationUpdate = async (argv) => {
+    try {
+        const projectCpVersion = getConfig().version;
+        const packageCpVersion = getVersion();
+        if (gte(projectCpVersion, packageCpVersion)) {
+            console.warn('Nothing to update, exiting.');
+            process.exit(0);
+        }
+        console.log(`Running migrations from ${projectCpVersion} to ${packageCpVersion}.`);
+        const commitEachMigration = argv.commit;
+        const migrations = getMigrationsToRun(projectCpVersion, packageCpVersion);
+        await runMigrations(migrations, { commitEachMigration });
+        printHeader('the update command completed successfully.');
+        console.log('');
+    }
+    catch (error) {
+        printHeader('the update command encountered an error.');
+        console.log('');
+        console.error(error);
+        process.exit(1);
+    }
+};

package/dist/commands/update.standard.command.js

@@ -0,0 +1,51 @@
+import chalk from 'chalk';
+import { UDPATE_CONFIG } from '../constants.js';
+import { printBlueBox, printRedBox } from '../utils/utils.console.js';
+import { getOnlyExistingInCwd, removeFilesInCwd } from '../utils/utils.files.js';
+import { updateGoSdkAndModules } from '../utils/utils.goSdk.js';
+import { updateNpmScripts, updatePackageJson } from '../utils/utils.npm.js';
+import { getPackageManagerFromUserAgent } from '../utils/utils.packageManager.js';
+import { updateDotConfigFolder } from '../utils/utils.plugin.js';
+import { getGrafanaRuntimeVersion, getVersion } from '../utils/utils.version.js';
+export const standardUpdate = async () => {
+    const { packageManagerName } = getPackageManagerFromUserAgent();
+    try {
+        await updateDotConfigFolder();
+        updateNpmScripts();
+        updatePackageJson({
+            onlyOutdated: true,
+            ignoreGrafanaDependencies: false,
+        });
+        await updateGoSdkAndModules(process.cwd());
+        const filesToRemove = getOnlyExistingInCwd(UDPATE_CONFIG.filesToRemove);
+        if (filesToRemove.length) {
+            removeFilesInCwd(filesToRemove);
+        }
+        printBlueBox({
+            title: 'Update successful ✔',
+            content: `${chalk.bold('@grafana/* package version:')} ${getGrafanaRuntimeVersion()}
+${chalk.bold('@grafana/create-plugin version:')} ${getVersion()}
+
+${chalk.bold.underline('Next steps:')}
+- 1. Run ${chalk.bold(`${packageManagerName} install`)} to install the package updates
+- 2. Check if you encounter any breaking changes
+  (refer to our migration guide: https://grafana.com/developers/plugin-tools/migration-guides/update-from-grafana-versions/)
+${chalk.bold('Do you have questions?')}
+Please don't hesitate to reach out in one of the following ways:
+- Open an issue in https://github.com/grafana/plugin-tools
+- Ask a question in the community forum at https://community.grafana.com/c/plugin-development/30
+- Join our community slack channel at https://slack.grafana.com/`,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            printRedBox({
+                title: 'Something went wrong while updating your plugin.',
+                content: error.message,
+            });
+        }
+        else {
+            console.error(error);
+        }
+    }
+};

package/dist/migrations/context.js

@@ -0,0 +1,118 @@
+import { constants, accessSync, readFileSync, readdirSync } from 'node:fs';
+import { relative, normalize, join, dirname } from 'node:path';
+import { migrationsDebug } from './utils.js';
+export class Context {
+    files = {};
+    basePath;
+    constructor(basePath) {
+        this.basePath = basePath || process.cwd();
+    }
+    addFile(filePath, content) {
+        const path = this.normalisePath(filePath);
+        if (!this.doesFileExist(path)) {
+            this.files[path] = { content, changeType: 'add' };
+        }
+        else {
+            throw new Error(`File ${path} already exists`);
+        }
+    }
+    deleteFile(filePath) {
+        const path = this.normalisePath(filePath);
+        if (this.files[path] && this.files[path].changeType === 'add') {
+            delete this.files[path];
+            return;
+        }
+        else if (this.doesFileExistOnDisk(path)) {
+            this.files[path] = { ...this.files[path], changeType: 'delete' };
+        }
+        else if (this.files[path] && this.files[path].changeType === 'update') {
+            throw new Error(`File ${path} was marked as updated already`);
+        }
+        else {
+            throw new Error(`File ${path} does not exist`);
+        }
+    }
+    updateFile(filePath, content) {
+        const path = this.normalisePath(filePath);
+        const originalContent = this.getFile(path);
+        if (originalContent === undefined) {
+            throw new Error(`File ${path} does not exist`);
+        }
+        if (originalContent !== content) {
+            this.files[path] = { content, changeType: 'update' };
+        }
+        else {
+            migrationsDebug(`Context.updateFile() - no updates for ${filePath}`);
+        }
+    }
+    doesFileExist(filePath) {
+        const path = this.normalisePath(filePath);
+        if (this.files[path] && this.files[path].changeType !== 'delete') {
+            return true;
+        }
+        return this.doesFileExistOnDisk(path);
+    }
+    doesFileExistOnDisk(filePath) {
+        const path = join(this.basePath, this.normalisePath(filePath));
+        try {
+            accessSync(path, constants.R_OK | constants.W_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    getFile(filePath) {
+        const path = this.normalisePath(filePath);
+        if (this.files[path] && this.files[path].changeType === 'delete') {
+            return undefined;
+        }
+        if (this.files[path]) {
+            return this.files[path].content;
+        }
+        if (this.doesFileExistOnDisk(path)) {
+            return readFileSync(join(this.basePath, path), 'utf-8');
+        }
+        return undefined;
+    }
+    listChanges() {
+        return this.files;
+    }
+    hasChanges() {
+        return Object.keys(this.files).length > 0;
+    }
+    renameFile(from, to) {
+        const normalisedTo = this.normalisePath(to);
+        const contents = this.getFile(from);
+        if (contents === undefined) {
+            throw new Error(`File ${from} does not exist`);
+        }
+        else if (this.files[normalisedTo]) {
+            throw new Error(`File ${to} already exists`);
+        }
+        else {
+            this.deleteFile(from);
+            this.addFile(to, contents);
+        }
+    }
+    readDir(folderPath) {
+        const path = this.normalisePath(folderPath);
+        const childrenOnDisk = this.readDirFromDisk(folderPath)
+            .map((child) => join(path, child))
+            .filter((child) => !this.files[child] || this.files[child].changeType !== 'delete');
+        const childrenAddedInContext = Object.keys(this.files).filter((p) => dirname(p) === path && this.files[p].changeType === 'add');
+        return [...childrenOnDisk, ...childrenAddedInContext];
+    }
+    readDirFromDisk(folderPath) {
+        const path = this.normalisePath(folderPath);
+        try {
+            return readdirSync(join(this.basePath, path));
+        }
+        catch (error) {
+            return [];
+        }
+    }
+    normalisePath(filePath) {
+        return normalize(relative(this.basePath, join(this.basePath, filePath)));
+    }
+}

package/dist/migrations/context.test.js

@@ -0,0 +1,122 @@
+import { Context } from './context.js';
+describe('Context', () => {
+    describe('getFile', () => {
+        it('should read a file from the file system', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            const content = context.getFile('foo/bar.ts');
+            expect(content).toEqual("console.log('foo/bar.ts');\n");
+        });
+        it('should get a file that was just added to the context', () => {
+            const context = new Context();
+            context.addFile('file.txt', 'content');
+            const content = context.getFile('file.txt');
+            expect(content).toEqual('content');
+        });
+        it('should get a file that was updated in the current context', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            context.updateFile('foo/bar.ts', 'content');
+            const content = context.getFile('foo/bar.ts');
+            expect(content).toEqual('content');
+        });
+        it('should not return a file that was marked for deletion', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            context.deleteFile('foo/bar.ts');
+            const content = context.getFile('foo/bar.ts');
+            expect(content).toEqual(undefined);
+        });
+    });
+    describe('addFile', () => {
+        it('should add a file to the context', () => {
+            const context = new Context();
+            context.addFile('file.txt', 'content');
+            expect(context.listChanges()).toEqual({ 'file.txt': { content: 'content', changeType: 'add' } });
+        });
+        it('should not add a file if it already exists', () => {
+            const context = new Context();
+            context.addFile('file.txt', 'content');
+            expect(() => context.addFile('file.txt', 'new content')).toThrowError('File file.txt already exists');
+        });
+    });
+    describe('deleteFile', () => {
+        it('should delete a file from the context', () => {
+            const context = new Context();
+            context.addFile('file.txt', 'content');
+            context.deleteFile('file.txt');
+            expect(context.listChanges()).toEqual({});
+        });
+        it('should not delete a file if it does not exist', () => {
+            const context = new Context();
+            expect(() => context.deleteFile('file.txt')).toThrowError('File file.txt does not exist');
+        });
+    });
+    describe('updateFile', () => {
+        it('should update a file in the context', () => {
+            const context = new Context();
+            context.addFile('file.txt', 'content');
+            context.updateFile('file.txt', 'new content');
+            expect(context.listChanges()).toEqual({ 'file.txt': { content: 'new content', changeType: 'update' } });
+        });
+        it('should not update a file if it does not exist', () => {
+            const context = new Context();
+            expect(() => context.updateFile('file.txt', 'new content')).toThrowError('File file.txt does not exist');
+        });
+    });
+    describe('renameFile', () => {
+        it('should rename a file', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            context.renameFile('foo/bar.ts', 'new-file.txt');
+            expect(context.listChanges()).toEqual({
+                'new-file.txt': { content: "console.log('foo/bar.ts');\n", changeType: 'add' },
+                'foo/bar.ts': { changeType: 'delete' },
+            });
+        });
+        it('should not rename a file if it does not exist', () => {
+            const context = new Context();
+            expect(() => context.renameFile('file.txt', 'new-file.txt')).toThrowError('File file.txt does not exist');
+        });
+        it('should not rename a file if the new name already exists', () => {
+            const context = new Context();
+            context.addFile('file.txt', 'content');
+            context.addFile('new-file.txt', 'content');
+            expect(() => context.renameFile('file.txt', 'new-file.txt')).toThrowError('File new-file.txt already exists');
+        });
+    });
+    describe('readDir', () => {
+        it('should read the directory', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            const files = context.readDir('foo');
+            expect(files).toEqual(['foo/bar.ts', 'foo/baz.ts']);
+        });
+        it('should filter out deleted files', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            context.deleteFile('foo/bar.ts');
+            const files = context.readDir('foo');
+            expect(files).toEqual(['foo/baz.ts']);
+        });
+        it('should include files that are only added to the context', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            context.addFile('foo/foo.txt', '');
+            const files = context.readDir('foo');
+            expect(files).toEqual(['foo/bar.ts', 'foo/baz.ts', 'foo/foo.txt']);
+        });
+    });
+    describe('normalisePath', () => {
+        it('should normalise the path', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            expect(context.normalisePath('foo/bar.ts')).toEqual('foo/bar.ts');
+            expect(context.normalisePath('./foo/bar.ts')).toEqual('foo/bar.ts');
+            expect(context.normalisePath('/foo/bar.ts')).toEqual('foo/bar.ts');
+        });
+    });
+    describe('hasChanges', () => {
+        it('should return FALSE if the context has no changes', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            expect(context.hasChanges()).toEqual(false);
+        });
+        it('should return TRUE if the context has changes', () => {
+            const context = new Context(`${__dirname}/fixtures`);
+            context.addFile('foo.ts', '');
+            expect(context.hasChanges()).toEqual(true);
+        });
+    });
+});

package/dist/migrations/fixtures/foo/bar.js

@@ -0,0 +1,2 @@
+console.log('foo/bar.ts');
+export {};

package/dist/migrations/fixtures/foo/baz.js

@@ -0,0 +1 @@
+export {};

package/dist/migrations/fixtures/migrations.js

@@ -0,0 +1,19 @@
+export default {
+    migrations: {
+        'migration-key1': {
+            version: '5.0.0',
+            description: 'Update project to use new cache directory',
+            migrationScript: './5-0-0-cache-directory.js',
+        },
+        'migration-key2': {
+            version: '5.4.0',
+            description: 'Update project to use new cache directory',
+            migrationScript: './5-4-0-cache-directory.js',
+        },
+        'migration-key3': {
+            version: '6.0.0',
+            description: 'Update project to use new cache directory',
+            migrationScript: './5-4-0-cache-directory.js',
+        },
+    },
+};

package/dist/migrations/manager.js

@@ -0,0 +1,50 @@
+import { satisfies, gte } from 'semver';
+import { Context } from './context.js';
+import defaultMigrations from './migrations.js';
+import { flushChanges, printChanges, migrationsDebug } from './utils.js';
+import { gitCommitNoVerify } from '../utils/utils.git.js';
+import { setRootConfig } from '../utils/utils.config.js';
+export function getMigrationsToRun(fromVersion, toVersion, migrations = defaultMigrations.migrations) {
+    const semverRange = `${fromVersion} - ${toVersion}`;
+    const migrationsToRun = Object.entries(migrations)
+        .sort((a, b) => {
+        return gte(a[1].version, b[1].version) ? 1 : -1;
+    })
+        .reduce((acc, [key, meta]) => {
+        if (satisfies(meta.version, semverRange)) {
+            acc[key] = meta;
+        }
+        return acc;
+    }, {});
+    return migrationsToRun;
+}
+export async function runMigrations(migrations, options = {}) {
+    const basePath = process.cwd();
+    console.log('');
+    console.log('Running the following migrations:');
+    Object.entries(migrations).map(([key, migrationMeta]) => console.log(`- ${key} (${migrationMeta.description})`));
+    console.log('');
+    for (const [key, migration] of Object.entries(migrations)) {
+        try {
+            const context = await runMigration(migration, new Context(basePath));
+            const shouldCommit = options.commitEachMigration && context.hasChanges();
+            migrationsDebug(`context for "${key} (${migration.migrationScript})":`);
+            migrationsDebug('%O', context.listChanges());
+            flushChanges(context);
+            printChanges(context, key, migration);
+            if (shouldCommit) {
+                await gitCommitNoVerify(`chore: run create-plugin migration - ${key} (${migration.migrationScript})`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Error running migration "${key} (${migration.migrationScript})": ${error.message}`);
+            }
+        }
+    }
+    setRootConfig({ version: Object.values(migrations).at(-1).version });
+}
+export async function runMigration(migration, context) {
+    const module = await import(migration.migrationScript);
+    return module.default(context);
+}