@grafana/create-plugin 5.17.0 → 5.18.0

package/src/commands/update.command.ts

@@ -1,91 +1,49 @@
-import chalk from 'chalk';
 import minimist from 'minimist';
-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: minimist.ParsedArgs) => {
-  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);
-    }
+    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.
+  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);
-    }
+    process.exit(1);
+  }
 
-    // Updating the plugin (.config/, NPM package dependencies, package.json scripts)
-    // (More info on the why: https://docs.google.com/document/d/15dm4WV9v7Ga9Z_Hp3CJMf2D3meuTyEWqBc3omqiOksQ)
-    // -------------------
-    await updateDotConfigFolder();
-    updateNpmScripts();
-    updatePackageJson({
-      onlyOutdated: true,
-      ignoreGrafanaDependencies: false,
+  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.)`,
     });
-    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()}
+    process.exit(1);
+  }
 
-${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);
-    }
+  if (argv.experimentalUpdates) {
+    return await migrationUpdate(argv);
   }
+
+  return await standardUpdate();
 };

package/src/commands/update.migrate.command.ts

@@ -0,0 +1,31 @@
+import minimist from 'minimist';
+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: minimist.ParsedArgs) => {
+  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/src/commands/update.standard.command.ts

@@ -0,0 +1,55 @@
+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 {
+    // Updating the plugin (.config/, NPM package dependencies, package.json scripts)
+    // (More info on the why: https://docs.google.com/document/d/15dm4WV9v7Ga9Z_Hp3CJMf2D3meuTyEWqBc3omqiOksQ)
+    // -------------------
+    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/src/migrations/context.test.ts

@@ -0,0 +1,148 @@
+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/src/migrations/context.ts

@@ -0,0 +1,155 @@
+import { constants, accessSync, readFileSync, readdirSync } from 'node:fs';
+import { relative, normalize, join, dirname } from 'node:path';
+import { migrationsDebug } from './utils.js';
+
+export type ContextFile = Record<
+  string,
+  {
+    content?: string;
+    changeType: 'add' | 'delete' | 'update';
+  }
+>;
+
+export class Context {
+  private files: ContextFile = {};
+  basePath: string;
+
+  constructor(basePath?: string) {
+    this.basePath = basePath || process.cwd();
+  }
+
+  addFile(filePath: string, content: string) {
+    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: string) {
+    const path = this.normalisePath(filePath);
+
+    // Delete a file that was added to the current context
+    if (this.files[path] && this.files[path].changeType === 'add') {
+      delete this.files[path];
+      return;
+    }
+    // Delete a file from the disk
+    else if (this.doesFileExistOnDisk(path)) {
+      this.files[path] = { ...this.files[path], changeType: 'delete' };
+    }
+    // Delete a file that was updated in the current context
+    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: string, content: string) {
+    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: string) {
+    const path = this.normalisePath(filePath);
+
+    // Added / updated in this context
+    if (this.files[path] && this.files[path].changeType !== 'delete') {
+      return true;
+    }
+
+    return this.doesFileExistOnDisk(path);
+  }
+
+  doesFileExistOnDisk(filePath: string) {
+    const path = join(this.basePath, this.normalisePath(filePath));
+
+    try {
+      accessSync(path, constants.R_OK | constants.W_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  getFile(filePath: string) {
+    const path = this.normalisePath(filePath);
+
+    // Deleted in this context
+    if (this.files[path] && this.files[path].changeType === 'delete') {
+      return undefined;
+    }
+
+    // Added / updated in this context
+    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: string, to: string) {
+    const normalisedTo = this.normalisePath(to);
+    const contents = this.getFile(from);
+
+    if (contents === undefined) {
+      throw new Error(`File ${from} does not exist`);
+    }
+    // File was already touched in this context
+    else if (this.files[normalisedTo]) {
+      throw new Error(`File ${to} already exists`);
+    } else {
+      this.deleteFile(from);
+      this.addFile(to, contents);
+    }
+  }
+
+  readDir(folderPath: string): string[] {
+    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: string): string[] {
+    const path = this.normalisePath(folderPath);
+
+    try {
+      return readdirSync(join(this.basePath, path));
+    } catch (error) {
+      return [];
+    }
+  }
+
+  normalisePath(filePath: string) {
+    return normalize(relative(this.basePath, join(this.basePath, filePath)));
+  }
+}

package/src/migrations/fixtures/foo/bar.ts

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

package/src/migrations/fixtures/migrations.ts

@@ -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',
+    },
+  },
+};