@grafana/create-plugin 6.2.0-canary.2233.19133609453.0 → 6.2.0-canary.2233.19368311379.0

package/src/codemods/runner.ts

@@ -0,0 +1,57 @@
+import { Context } from './context.js';
+import { formatFiles, flushChanges, installNPMDependencies, printChanges } from './utils.js';
+import { parseAndValidateOptions } from './schema-parser.js';
+import { output } from '../utils/utils.console.js';
+import { Codemod } from './types.js';
+
+/**
+ * Run a single codemod
+ *
+ * Steps:
+ * 1. Load codemod module from scriptPath
+ * 2. Parse and validate options from schema
+ * 3. Execute codemod transformation
+ * 4. Format files
+ * 5. Flush changes to disk
+ * 6. Print summary
+ * 7. Install dependencies if needed
+ */
+export async function runCodemod(codemod: Codemod, options?: Record<string, any>): Promise<Context> {
+  const codemodModule = await import(codemod.scriptPath);
+  if (!codemodModule.default || typeof codemodModule.default !== 'function') {
+    throw new Error(`Codemod ${codemod.name} must export a default function`);
+  }
+
+  let codemodOptions = {};
+
+  if (options && codemodModule.schema) {
+    codemodOptions = parseAndValidateOptions(options, codemodModule.schema);
+  }
+
+  const basePath = process.cwd();
+  const context = new Context(basePath);
+
+  try {
+    output.log({
+      title: `Running ${codemod.name}`,
+      body: [codemod.description],
+    });
+
+    const updatedContext = await codemodModule.default(context, codemodOptions);
+
+    // standard post-processing pipeline
+    await formatFiles(updatedContext);
+    flushChanges(updatedContext);
+    printChanges(updatedContext, codemod.name, codemod.description);
+    installNPMDependencies(updatedContext);
+
+    return updatedContext;
+  } catch (error) {
+    if (error instanceof Error) {
+      const newError = new Error(`Error running ${codemod.name}: ${error.message}`);
+      newError.cause = error;
+      throw newError;
+    }
+    throw error;
+  }
+}

package/src/codemods/schema-parser.ts

@@ -0,0 +1,27 @@
+import * as v from 'valibot';
+
+/**
+ * Parse and validate options using Valibot schema
+ * Valibot handles parsing, validation, type coercion, and defaults automatically
+ */
+export function parseAndValidateOptions<T extends v.BaseSchema<any, any, any>>(
+  options: Record<string, any>,
+  schema: T
+): v.InferOutput<T> {
+  try {
+    return v.parse(schema, options);
+  } catch (error) {
+    if (v.isValiError(error)) {
+      // format Valibot validation errors
+      const formattedErrors = error.issues
+        .map((issue) => {
+          const path = issue.path?.map((p) => p.key).join('.') || '';
+          return `  --${path}: ${issue.message}`;
+        })
+        .join('\n');
+
+      throw new Error(`Invalid flag(s) provided:\n\n${formattedErrors}`);
+    }
+    throw error;
+  }
+}

package/src/codemods/types.ts

@@ -1,21 +1,16 @@
 import type { Context } from './context.js';
+import type * as v from 'valibot';
 
-export interface CodemodModule {
-  default: (context: Context) => Context | Promise<Context>;
+// used as a generic constraint for codemod schemas. accepts any input, output and error types
+type AnySchema = v.BaseSchema<any, any, any>;
+
+export interface CodemodModule<TSchema extends AnySchema = AnySchema> {
+  default: (context: Context, options: v.InferOutput<TSchema>) => Context | Promise<Context>;
+  schema?: TSchema;
 }
 
-export interface FlagDefinition {
+export interface Codemod {
   name: string;
   description: string;
-  required: boolean;
-}
-
-export interface AdditionModule<TOptions = any> extends CodemodModule {
-  default: (context: Context, options?: TOptions) => Context | Promise<Context>;
-  flags?: FlagDefinition[];
-  parseFlags?: (argv: any) => TOptions;
-}
-
-export interface MigrationModule extends CodemodModule {
-  default: (context: Context) => Context | Promise<Context>;
+  scriptPath: string;
 }

package/src/codemods/{migrations/utils.test.ts → utils.test.ts}

@@ -1,5 +1,5 @@
 import { dirSync } from 'tmp';
-import { Context } from '../context.js';
+import { Context } from './context.js';
 import {
   addDependenciesToPackageJson,
   removeDependenciesFromPackageJson,
@@ -7,12 +7,13 @@ import {
   formatFiles,
   readJsonFile,
   isVersionGreater,
-} from '../utils.js';
-import { printChanges } from './utils.js';
+  printChanges,
+} from './utils.js';
 import { join } from 'node:path';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
-import { output } from '../../utils/utils.console.js';
+import { output } from '../utils/utils.console.js';
+import { vi } from 'vitest';
 
 describe('utils', () => {
   const tmpObj = dirSync({ unsafeCleanup: true });
@@ -80,7 +81,7 @@ describe('utils', () => {
       context.updateFile('baz.ts', 'new content');
       context.deleteFile('bar.ts');
 
-      printChanges(context, 'key', { migrationScript: 'test', description: 'test', version: '1.0.0' });
+      printChanges(context, 'key', 'test');
 
       expect(outputMock.addHorizontalLine).toHaveBeenCalledWith('gray');
       expect(outputMock.logSingleLine).toHaveBeenCalledWith('key (test)');
@@ -102,7 +103,7 @@ describe('utils', () => {
     it('should print no changes', async () => {
       const context = new Context(tmpDir);
 
-      printChanges(context, 'key', { migrationScript: 'test', description: 'test', version: '1.0.0' });
+      printChanges(context, 'key', 'test');
 
       expect(outputMock.logSingleLine).toHaveBeenCalledWith('No changes were made');
     });
@@ -271,7 +272,7 @@ describe('utils', () => {
     });
   });
 
-  describe('isIncomingVersionGreater', () => {
+  describe('isVersionGreater', () => {
     describe('dist tag comparison', () => {
       it('should return false when incoming is "latest" and existing is "next"', () => {
         expect(isVersionGreater('latest', 'next')).toBe(false);

package/src/codemods/utils.ts

@@ -1,9 +1,4 @@
-/**
- * Shared utilities for codemods (migrations and additions).
- * These functions work with the Context class to modify plugin codebases.
- */
-
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { Context } from './context.js';
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
@@ -11,20 +6,10 @@ import chalk from 'chalk';
 import { output } from '../utils/utils.console.js';
 import { getPackageManagerSilentInstallCmd, getPackageManagerWithFallback } from '../utils/utils.packageManager.js';
 import { execSync } from 'node:child_process';
-import { clean, coerce, gt } from 'semver';
-
-/**
- * Generic metadata type for printChanges
- */
-type ChangeMetadata = {
-  description: string;
-};
+import { clean, coerce, gt, gte } from 'semver';
+import { fileURLToPath } from 'node:url';
 
-/**
- * Prints changes made to the context in a formatted way.
- * Works with both migrations and additions.
- */
-export function printChanges(context: Context, key: string, meta: ChangeMetadata) {
+export function printChanges(context: Context, key: string, description: string) {
   const changes = context.listChanges();
   const lines = [];
 
@@ -39,7 +24,7 @@ export function printChanges(context: Context, key: string, meta: ChangeMetadata
   }
 
   output.addHorizontalLine('gray');
-  output.logSingleLine(`${key} (${meta.description})`);
+  output.logSingleLine(`${key} (${description})`);
 
   if (lines.length === 0) {
     output.logSingleLine('No changes were made');
@@ -48,9 +33,6 @@ export function printChanges(context: Context, key: string, meta: ChangeMetadata
   }
 }
 
-/**
- * Writes all changes from the context to the filesystem.
- */
 export function flushChanges(context: Context) {
   const basePath = context.basePath;
   const changes = context.listChanges();
@@ -122,9 +104,6 @@ export async function formatFiles(context: Context) {
 // (This runs for each codemod used in an update)
 let packageJsonInstallCache: string;
 
-/**
- * Installs NPM dependencies if package.json has changed.
- */
 export function installNPMDependencies(context: Context) {
   const hasPackageJsonChanges = Object.entries(context.listChanges()).some(
     ([filePath, { changeType }]) => filePath === 'package.json' && changeType === 'update'
@@ -152,9 +131,6 @@ export function installNPMDependencies(context: Context) {
   }
 }
 
-/**
- * Reads and parses a JSON file from the context.
- */
 export function readJsonFile<T extends object = any>(context: Context, path: string): T {
   if (!context.doesFileExist(path)) {
     throw new Error(`Cannot find ${path}`);
@@ -166,9 +142,6 @@ export function readJsonFile<T extends object = any>(context: Context, path: str
   }
 }
 
-/**
- * Adds or updates dependencies in package.json, preventing downgrades.
- */
 export function addDependenciesToPackageJson(
   context: Context,
   dependencies: Record<string, string>,
@@ -233,9 +206,6 @@ export function addDependenciesToPackageJson(
   context.updateFile(packageJsonPath, JSON.stringify(updatedPackageJson, null, 2));
 }
 
-/**
- * Removes dependencies from package.json.
- */
 export function removeDependenciesFromPackageJson(
   context: Context,
   dependencies: string[],
@@ -276,8 +246,13 @@ const DIST_TAGS = {
 
 /**
  * Compares two version strings to determine if the incoming version is greater
+ *
+ * @param incomingVersion - The incoming version to compare.
+ * @param existingVersion - The existing version to compare.
+ * @param orEqualTo - Whether to check for greater than or equal to (>=) instead of just greater than (>).
+ *
  */
-export function isVersionGreater(incomingVersion: string, existingVersion: string): boolean {
+export function isVersionGreater(incomingVersion: string, existingVersion: string, orEqualTo = false) {
   const incomingIsDistTag = incomingVersion in DIST_TAGS;
   const existingIsDistTag = existingVersion in DIST_TAGS;
 
@@ -301,6 +276,10 @@ export function isVersionGreater(incomingVersion: string, existingVersion: strin
     return true;
   }
 
+  if (orEqualTo) {
+    return gte(incomingSemver, existingSemver);
+  }
+
   return gt(incomingSemver, existingSemver);
 }
 
@@ -319,3 +298,16 @@ function sortObjectByKeys<T extends Record<string, any>>(obj: T): T {
     .sort()
     .reduce((acc, key) => ({ ...acc, [key]: obj[key] }), {} as T);
 }
+
+/**
+ * Resolves a script path relative to the caller's file location.
+ *
+ * @param callerUrl - The import.meta.url from the calling file
+ * @param relativePath - The relative path to resolve (e.g., './scripts/example.js')
+ * @returns The absolute resolved path
+ */
+export function resolveScriptPath(callerUrl: string, relativePath: string): string {
+  const __filename = fileURLToPath(callerUrl);
+  const __dirname = dirname(__filename);
+  return resolve(__dirname, relativePath);
+}

package/src/commands/add.command.ts

@@ -1,7 +1,7 @@
-import { getAdditionFlags, getAvailableAdditions, runAdditionByName } from '../codemods/additions/manager.js';
-import { isGitDirectory, isGitDirectoryClean } from '../utils/utils.git.js';
-
-import { isPluginDirectory } from '../utils/utils.plugin.js';
+import defaultAdditions from '../codemods/additions/additions.js';
+import { runCodemod } from '../codemods/runner.js';
+import { getPackageManagerExecCmd, getPackageManagerFromUserAgent } from '../utils/utils.packageManager.js';
+import { performPreCodemodChecks } from '../utils/utils.checks.js';
 import minimist from 'minimist';
 import { output } from '../utils/utils.console.js';
 
@@ -13,10 +13,27 @@ export const add = async (argv: minimist.ParsedArgs) => {
     process.exit(1);
   }
 
-  await performPreAddChecks(argv);
+  await performPreCodemodChecks(argv);
 
   try {
-    await runAdditionByName(subCommand, argv);
+    const addition = defaultAdditions.find((addition) => addition.name === subCommand);
+    if (!addition) {
+      const additionsList = defaultAdditions.map((addition) => addition.name);
+      throw new Error(`Unknown addition: ${subCommand}\n\nAvailable additions: ${additionsList.join(', ')}`);
+    }
+
+    output.log({
+      title: `Running addition: ${addition.name}`,
+      body: [addition.description],
+    });
+
+    // filter out minimist internal properties (_ and $0) before passing to codemod
+    const { _, $0, ...codemodOptions } = argv;
+    await runCodemod(addition, codemodOptions);
+
+    output.success({
+      title: `Successfully added ${addition.name} to your plugin.`,
+    });
   } catch (error) {
     if (error instanceof Error) {
       output.error({
@@ -29,69 +46,16 @@ export const add = async (argv: minimist.ParsedArgs) => {
 };
 
 async function showAdditionsHelp() {
-  const availableAdditions = getAvailableAdditions();
-  const additionsList = await Promise.all(
-    Object.values(availableAdditions).map(async (addition) => {
-      let info = `${addition.name} - ${addition.description}`;
-      const flags = await getAdditionFlags(addition);
-      if (flags.length > 0) {
-        const flagDocs = flags.map((flag) => {
-          const req = flag.required ? ' (required)' : ' (optional)';
-          return `  --${flag.name}: ${flag.description}${req}`;
-        });
-        info += '\n' + flagDocs.join('\n');
-      }
-      return info;
-    })
-  );
+  const additionsList = defaultAdditions.map((addition) => addition.name);
+  const { packageManagerName, packageManagerVersion } = getPackageManagerFromUserAgent();
 
   output.error({
     title: 'No addition specified',
     body: [
-      'Usage: npx @grafana/create-plugin add <addition-name> [options]',
+      `Usage: ${getPackageManagerExecCmd(packageManagerName, packageManagerVersion)} add <addition-name> [options]`,
       '',
       'Available additions:',
       ...output.bulletList(additionsList),
     ],
   });
 }
-
-async function performPreAddChecks(argv: minimist.ParsedArgs) {
-  if (!(await isGitDirectory()) && !argv.force) {
-    output.error({
-      title: 'You are not inside a git directory',
-      body: [
-        `In order to proceed please run ${output.formatCode('git init')} in the root of your project and commit your changes.`,
-        `(This check is necessary to make sure that the changes are easy to revert and don't interfere with any changes you currently have.`,
-        `In case you want to proceed as is please use the ${output.formatCode('--force')} flag.)`,
-      ],
-    });
-
-    process.exit(1);
-  }
-
-  if (!(await isGitDirectoryClean()) && !argv.force) {
-    output.error({
-      title: 'Please clean your repository working tree before adding features.',
-      body: [
-        'Commit your changes or stash them.',
-        `(This check is necessary to make sure that the changes 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 ${output.formatCode('--force')} flag.)`,
-      ],
-    });
-
-    process.exit(1);
-  }
-
-  if (!isPluginDirectory() && !argv.force) {
-    output.error({
-      title: 'Are you inside a plugin directory?',
-      body: [
-        `We couldn't find a "src/plugin.json" file under your current directory.`,
-        `(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 ${output.formatCode('--force')} flag.)`,
-      ],
-    });
-
-    process.exit(1);
-  }
-}

package/src/commands/update.command.ts

@@ -5,18 +5,17 @@ import {
   getPackageManagerWithFallback,
 } from '../utils/utils.packageManager.js';
 import { gte, lt } from 'semver';
-import { isGitDirectory, isGitDirectoryClean } from '../utils/utils.git.js';
+import { performPreCodemodChecks } from '../utils/utils.checks.js';
 
 import { CURRENT_APP_VERSION } from '../utils/utils.version.js';
 import { LEGACY_UPDATE_CUTOFF_VERSION } from '../constants.js';
 import { getConfig } from '../utils/utils.config.js';
-import { isPluginDirectory } from '../utils/utils.plugin.js';
 import minimist from 'minimist';
 import { output } from '../utils/utils.console.js';
 import { spawnSync } from 'node:child_process';
 
 export const update = async (argv: minimist.ParsedArgs) => {
-  await performPreUpdateChecks(argv);
+  await performPreCodemodChecks(argv);
   const { version } = getConfig();
 
   if (lt(version, LEGACY_UPDATE_CUTOFF_VERSION)) {
@@ -32,9 +31,13 @@ export const update = async (argv: minimist.ParsedArgs) => {
       process.exit(0);
     }
 
-    const commitEachMigration = argv.commit;
     const migrations = getMigrationsToRun(version, CURRENT_APP_VERSION);
-    await runMigrations(migrations, { commitEachMigration });
+    // filter out minimist internal properties (_ and $0) before passing to codemod
+    const { _, $0, ...codemodOptions } = argv;
+    await runMigrations(migrations, {
+      commitEachMigration: !!argv.commit,
+      codemodOptions,
+    });
     output.success({
       title: `Successfully updated create-plugin from ${version} to ${CURRENT_APP_VERSION}.`,
     });
@@ -49,48 +52,6 @@ export const update = async (argv: minimist.ParsedArgs) => {
   }
 };
 
-async function performPreUpdateChecks(argv: minimist.ParsedArgs) {
-  if (!(await isGitDirectory()) && !argv.force) {
-    output.error({
-      title: 'You are not inside a git directory',
-      body: [
-        `In order to proceed please run ${output.formatCode('git init')} in the root of your project and commit your changes.`,
-        `(This check is necessary to make sure that the updates are easy to revert and don't interfere with any changes you currently have.`,
-        `In case you want to proceed as is please use the ${output.formatCode('--force')} flag.)`,
-      ],
-    });
-
-    process.exit(1);
-  }
-
-  if (!(await isGitDirectoryClean()) && !argv.force) {
-    output.error({
-      title: 'Please clean your repository working tree before updating.',
-      body: [
-        'Commit your changes or stash them.',
-        `(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 ${output.formatCode('--force')} flag.)`,
-      ],
-    });
-
-    process.exit(1);
-  }
-
-  if (!isPluginDirectory() && !argv.force) {
-    output.error({
-      title: 'Are you inside a plugin directory?',
-      body: [
-        `We couldn't find a "src/plugin.json" file under your current directory.`,
-        `(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 ${output.formatCode(
-          '--force'
-        )} flag.)`,
-      ],
-    });
-
-    process.exit(1);
-  }
-}
-
 /**
  * Prepares a plugin for migrations by running the legacy update command and installing dependencies.
  * This is a one time operation that ensures the plugin configs are "as expected" by the new migration system.

package/src/migrations/migrations.ts

@@ -0,0 +1,44 @@
+import { LEGACY_UPDATE_CUTOFF_VERSION } from '../constants.js';
+
+export type MigrationMeta = {
+  version: string;
+  description: string;
+  migrationScript: string;
+};
+
+type Migrations = {
+  migrations: Record<string, MigrationMeta>;
+};
+
+// Do not use LEGACY_UPDATE_CUTOFF_VERSION for new migrations. It was used to force migrations to run
+// for those written before the switch to updates as migrations.
+export default {
+  migrations: {
+    '001-update-grafana-compose-extend': {
+      version: LEGACY_UPDATE_CUTOFF_VERSION,
+      description: 'Update ./docker-compose.yaml to extend from ./.config/docker-compose-base.yaml.',
+      migrationScript: './scripts/001-update-grafana-compose-extend.js',
+    },
+    '002-update-is-compatible-workflow': {
+      version: LEGACY_UPDATE_CUTOFF_VERSION,
+      description:
+        'Update ./.github/workflows/is-compatible.yml to use is-compatible github action instead of calling levitate directly',
+      migrationScript: './scripts/002-update-is-compatible-workflow.js',
+    },
+    '003-update-eslint-deprecation-rule': {
+      version: LEGACY_UPDATE_CUTOFF_VERSION,
+      description: 'Replace deprecated eslint-plugin-deprecation with @typescript-eslint/no-deprecated rule.',
+      migrationScript: './scripts/003-update-eslint-deprecation-rule.js',
+    },
+    '004-eslint9-flat-config': {
+      version: LEGACY_UPDATE_CUTOFF_VERSION,
+      description: 'Migrate eslint config to flat config format and update devDependencies to latest versions.',
+      migrationScript: './scripts/004-eslint9-flat-config.js',
+    },
+    '005-react-18-3': {
+      version: '6.1.9',
+      description: 'Update React and ReactDOM 18.x versions to ^18.3.0 to surface React 19 compatibility issues.',
+      migrationScript: './scripts/005-react-18-3.js',
+    },
+  },
+} as Migrations;

package/src/utils/utils.checks.ts

@@ -0,0 +1,47 @@
+import minimist from 'minimist';
+import { isGitDirectory, isGitDirectoryClean } from './utils.git.js';
+import { isPluginDirectory } from './utils.plugin.js';
+import { output } from './utils.console.js';
+
+/**
+ * Ensures git directory exists, is clean, and we're in a plugin directory
+ */
+export async function performPreCodemodChecks(argv: minimist.ParsedArgs): Promise<void> {
+  if (!(await isGitDirectory()) && !argv.force) {
+    output.error({
+      title: 'You are not inside a git directory',
+      body: [
+        `In order to proceed please run ${output.formatCode('git init')} in the root of your project and commit your changes.`,
+        `(This check is necessary to make sure that changes are easy to revert and don't interfere with any changes you currently have.`,
+        `In case you want to proceed as is please use the ${output.formatCode('--force')} flag.)`,
+      ],
+    });
+
+    process.exit(1);
+  }
+
+  if (!(await isGitDirectoryClean()) && !argv.force) {
+    output.error({
+      title: 'Please clean your repository working tree before making changes.',
+      body: [
+        'Commit your changes or stash them.',
+        `(This check is necessary to make sure that changes 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 ${output.formatCode('--force')} flag.)`,
+      ],
+    });
+
+    process.exit(1);
+  }
+
+  if (!isPluginDirectory() && !argv.force) {
+    output.error({
+      title: 'Are you inside a plugin directory?',
+      body: [
+        `We couldn't find a "src/plugin.json" file under your current directory.`,
+        `(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 ${output.formatCode('--force')} flag.)`,
+      ],
+    });
+
+    process.exit(1);
+  }
+}

package/src/utils/utils.config.ts

@@ -1,6 +1,4 @@
 import { argv, commandName } from './utils.cli.js';
-
-import type { AdditionFeatureName } from '../codemods/additions/additions.js';
 import { CURRENT_APP_VERSION } from './utils.version.js';
 import { DEFAULT_FEATURE_FLAGS } from '../constants.js';
 import fs from 'node:fs';
@@ -10,7 +8,7 @@ import path from 'node:path';
 import { writeFile } from 'node:fs/promises';
 import { EOL } from 'node:os';
 
-type CoreFeatureFlags = {
+type FeatureFlags = {
   bundleGrafanaUI?: boolean;
 
   // If set to true, the plugin will be scaffolded with React Router v6. Defaults to true.
@@ -21,16 +19,6 @@ type CoreFeatureFlags = {
   useExperimentalUpdates?: boolean;
 };
 
-type AdditionFeatureFlags = {
-  [K in AdditionFeatureName]?: boolean;
-};
-
-export type FeatureFlags = CoreFeatureFlags & AdditionFeatureFlags;
-
-export function isFeatureEnabled(features: FeatureFlags, featureName: AdditionFeatureName): boolean {
-  return features[featureName] === true;
-}
-
 export type CreatePluginConfig = UserConfig & {
   version: string;
 };
@@ -144,18 +132,3 @@ export async function setRootConfig(configOverride: Partial<CreatePluginConfig>
 
   return updatedConfig;
 }
-
-export async function setFeatureFlag(featureName: string, enabled = true): Promise<void> {
-  const userConfig = getUserConfig() || { features: {} };
-  const userConfigPath = path.resolve(process.cwd(), '.cprc.json');
-
-  const updatedConfig = {
-    ...userConfig,
-    features: {
-      ...userConfig.features,
-      [featureName]: enabled,
-    },
-  };
-
-  await writeFile(userConfigPath, JSON.stringify(updatedConfig, null, 2) + EOL);
-}