@grafana/create-plugin 6.1.1 → 6.2.0-canary.2233.18644853669.0

package/dist/commands/add.command.js

@@ -0,0 +1,92 @@
+import { getAvailableAdditions, getAdditionByName, runAddition } from '../additions/manager.js';
+import { isGitDirectory, isGitDirectoryClean } from '../utils/utils.git.js';
+import { isPluginDirectory } from '../utils/utils.plugin.js';
+import { output } from '../utils/utils.console.js';
+import { promptI18nOptions } from './add/prompts.js';
+
+const add = async (argv) => {
+  const subCommand = argv._[1];
+  if (!subCommand) {
+    const availableAdditions = getAvailableAdditions();
+    const additionsList = Object.values(availableAdditions).map(
+      (addition2) => `${addition2.name} - ${addition2.description}`
+    );
+    output.error({
+      title: "No addition specified",
+      body: [
+        "Usage: npx @grafana/create-plugin add <addition-name>",
+        "",
+        "Available additions:",
+        ...output.bulletList(additionsList)
+      ]
+    });
+    process.exit(1);
+  }
+  await performPreAddChecks(argv);
+  const addition = getAdditionByName(subCommand);
+  if (!addition) {
+    const availableAdditions = getAvailableAdditions();
+    const additionsList = Object.values(availableAdditions).map((addition2) => addition2.name);
+    output.error({
+      title: `Unknown addition: ${subCommand}`,
+      body: ["Available additions:", ...output.bulletList(additionsList)]
+    });
+    process.exit(1);
+  }
+  try {
+    let options = {};
+    switch (addition.name) {
+      case "i18n":
+        options = await promptI18nOptions();
+        break;
+      default:
+        break;
+    }
+    const commitChanges = argv.commit;
+    await runAddition(addition, options, { commitChanges });
+  } catch (error) {
+    if (error instanceof Error) {
+      output.error({
+        title: "Addition failed",
+        body: [error.message]
+      });
+    }
+    process.exit(1);
+  }
+};
+async function performPreAddChecks(argv) {
+  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);
+  }
+}
+
+export { add };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/create-plugin",
-  "version": "6.1.1",
+  "version": "6.2.0-canary.2233.18644853669.0",
   "repository": {
     "directory": "packages/create-plugin",
     "url": "https://github.com/grafana/plugin-tools"
@@ -61,5 +61,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "6b891abe4df5c9c3c1e191b5286298182efa70a0"
+  "gitHead": "4eb067f4f28b42ef18426827a1443073a97c3efd"
 }

package/src/additions/additions.ts

@@ -0,0 +1,19 @@
+export type AdditionMeta = {
+  name: string;
+  description: string;
+  scriptPath: string;
+};
+
+type Additions = {
+  additions: Record<string, AdditionMeta>;
+};
+
+export default {
+  additions: {
+    i18n: {
+      name: 'i18n',
+      description: 'Add internationalization (i18n) support to your plugin',
+      scriptPath: './scripts/add-i18n.js',
+    },
+  },
+} as Additions;

package/src/additions/manager.ts

@@ -0,0 +1,77 @@
+import { additionsDebug, flushChanges, formatFiles, installNPMDependencies, printChanges } from './utils.js';
+import defaultAdditions, { AdditionMeta } from './additions.js';
+
+import { Context } from '../migrations/context.js';
+import { gitCommitNoVerify } from '../utils/utils.git.js';
+import { output } from '../utils/utils.console.js';
+
+export type AdditionFn = (context: Context, options?: AdditionOptions) => Context | Promise<Context>;
+
+export type AdditionOptions = Record<string, any>;
+
+type RunAdditionOptions = {
+  commitChanges?: boolean;
+};
+
+export function getAvailableAdditions(
+  additions: Record<string, AdditionMeta> = defaultAdditions.additions
+): Record<string, AdditionMeta> {
+  return additions;
+}
+
+export function getAdditionByName(
+  name: string,
+  additions: Record<string, AdditionMeta> = defaultAdditions.additions
+): AdditionMeta | undefined {
+  return additions[name];
+}
+
+export async function runAddition(
+  addition: AdditionMeta,
+  additionOptions: AdditionOptions = {},
+  runOptions: RunAdditionOptions = {}
+): Promise<void> {
+  const basePath = process.cwd();
+
+  output.log({
+    title: `Running addition: ${addition.name}`,
+    body: [addition.description],
+  });
+
+  try {
+    const context = new Context(basePath);
+    const updatedContext = await executeAddition(addition, context, additionOptions);
+    const shouldCommit = runOptions.commitChanges && updatedContext.hasChanges();
+
+    additionsDebug(`context for "${addition.name} (${addition.scriptPath})":`);
+    additionsDebug('%O', updatedContext.listChanges());
+
+    await formatFiles(updatedContext);
+    flushChanges(updatedContext);
+    printChanges(updatedContext, addition.name, addition);
+
+    installNPMDependencies(updatedContext);
+
+    if (shouldCommit) {
+      await gitCommitNoVerify(`chore: add ${addition.name} support via create-plugin`);
+    }
+
+    output.success({
+      title: `Successfully added ${addition.name} to your plugin.`,
+    });
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Error running addition "${addition.name} (${addition.scriptPath})": ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+export async function executeAddition(
+  addition: AdditionMeta,
+  context: Context,
+  options: AdditionOptions = {}
+): Promise<Context> {
+  const module: { default: AdditionFn } = await import(addition.scriptPath);
+  return module.default(context, options);
+}

package/src/additions/scripts/add-i18n.test.ts

@@ -0,0 +1,347 @@
+import { describe, expect, it } from 'vitest';
+
+import { Context } from '../../migrations/context.js';
+import migrate from './add-i18n.js';
+
+describe('add-i18n', () => {
+  it('should be idempotent', async () => {
+    const context = new Context('/virtual');
+
+    // Set up a minimal plugin structure
+    context.addFile(
+      'src/plugin.json',
+      JSON.stringify({
+        id: 'test-plugin',
+        type: 'panel',
+        name: 'Test Plugin',
+        dependencies: {
+          grafanaDependency: '>=11.0.0',
+        },
+      })
+    );
+    context.addFile('docker-compose.yaml', 'services:\n  grafana:\n    environment:\n      FOO: bar');
+    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {} }));
+    context.addFile(
+      'eslint.config.mjs',
+      'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
+    );
+    context.addFile(
+      'src/module.ts',
+      'import { PanelPlugin } from "@grafana/data";\nexport const plugin = new PanelPlugin();'
+    );
+
+    const migrateWithOptions = (ctx: Context) => migrate(ctx, { locales: ['en-US'] });
+    await expect(migrateWithOptions).toBeIdempotent(context);
+  });
+
+  it('should add i18n support with a single locale (backward compatibility for Grafana < 12.1.0)', () => {
+    const context = new Context('/virtual');
+
+    // Set up a minimal plugin structure with Grafana 11.0.0 (needs backward compatibility)
+    context.addFile(
+      'src/plugin.json',
+      JSON.stringify({
+        id: 'test-plugin',
+        type: 'panel',
+        name: 'Test Plugin',
+        dependencies: {
+          grafanaDependency: '>=11.0.0',
+        },
+      })
+    );
+    context.addFile(
+      'docker-compose.yaml',
+      `services:
+  grafana:
+    environment:
+      FOO: bar`
+    );
+    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {}, scripts: {} }));
+    context.addFile(
+      'eslint.config.mjs',
+      'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
+    );
+    context.addFile(
+      'src/module.ts',
+      'import { PanelPlugin } from "@grafana/data";\nexport const plugin = new PanelPlugin();'
+    );
+
+    const result = migrate(context, { locales: ['en-US'] });
+
+    // Check plugin.json was updated
+    const pluginJson = JSON.parse(result.getFile('src/plugin.json') || '{}');
+    expect(pluginJson.languages).toEqual(['en-US']);
+    // Should stay at 11.0.0 for backward compatibility
+    expect(pluginJson.dependencies.grafanaDependency).toBe('>=11.0.0');
+
+    // Check locale file was created with example translations
+    expect(result.doesFileExist('src/locales/en-US/test-plugin.json')).toBe(true);
+    const localeContent = result.getFile('src/locales/en-US/test-plugin.json');
+    const localeData = JSON.parse(localeContent || '{}');
+    expect(localeData).toHaveProperty('components');
+    expect(localeData).toHaveProperty('config');
+
+    // Check package.json was updated with dependencies
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+    expect(packageJson.dependencies['@grafana/i18n']).toBe('12.2.2');
+    expect(packageJson.dependencies['semver']).toBe('^7.6.0');
+    expect(packageJson.devDependencies['@types/semver']).toBe('^7.5.0');
+    expect(packageJson.devDependencies['i18next-cli']).toBeDefined();
+    expect(packageJson.scripts['i18n-extract']).toBe('i18next-cli extract --sync-primary');
+
+    // Check docker-compose.yaml was NOT updated (backward compat doesn't add feature toggle)
+    const dockerCompose = result.getFile('docker-compose.yaml');
+    expect(dockerCompose).not.toContain('localizationForPlugins');
+
+    // Check module.ts was updated with backward compatibility code
+    const moduleTs = result.getFile('src/module.ts');
+    expect(moduleTs).toContain('initPluginTranslations');
+    expect(moduleTs).toContain('semver');
+    expect(moduleTs).toContain('loadResources');
+
+    // Check loadResources.ts was created for backward compatibility
+    expect(result.doesFileExist('src/loadResources.ts')).toBe(true);
+    const loadResources = result.getFile('src/loadResources.ts');
+    expect(loadResources).toContain('ResourceLoader');
+
+    // Check i18next.config.ts was created
+    expect(result.doesFileExist('i18next.config.ts')).toBe(true);
+    const i18nextConfig = result.getFile('i18next.config.ts');
+    expect(i18nextConfig).toContain('defineConfig');
+    expect(i18nextConfig).toContain('pluginJson.id');
+  });
+
+  it('should add i18n support with multiple locales', () => {
+    const context = new Context('/virtual');
+
+    context.addFile(
+      'src/plugin.json',
+      JSON.stringify({
+        id: 'test-plugin',
+        type: 'panel',
+        name: 'Test Plugin',
+        dependencies: {
+          grafanaDependency: '>=11.0.0',
+        },
+      })
+    );
+    context.addFile(
+      'docker-compose.yaml',
+      `services:
+  grafana:
+    environment:
+      FOO: bar`
+    );
+    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {}, scripts: {} }));
+    context.addFile(
+      'eslint.config.mjs',
+      'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
+    );
+    context.addFile(
+      'src/module.ts',
+      'import { PanelPlugin } from "@grafana/data";\nexport const plugin = new PanelPlugin();'
+    );
+
+    const result = migrate(context, { locales: ['en-US', 'es-ES', 'sv-SE'] });
+
+    // Check plugin.json has all locales
+    const pluginJson = JSON.parse(result.getFile('src/plugin.json') || '{}');
+    expect(pluginJson.languages).toEqual(['en-US', 'es-ES', 'sv-SE']);
+
+    // Check all locale files were created
+    expect(result.doesFileExist('src/locales/en-US/test-plugin.json')).toBe(true);
+    expect(result.doesFileExist('src/locales/es-ES/test-plugin.json')).toBe(true);
+    expect(result.doesFileExist('src/locales/sv-SE/test-plugin.json')).toBe(true);
+  });
+
+  it('should skip if i18n is already configured', () => {
+    const context = new Context('/virtual');
+
+    // Set up a plugin with i18n already configured
+    context.addFile(
+      'src/plugin.json',
+      JSON.stringify({
+        id: 'test-plugin',
+        type: 'panel',
+        name: 'Test Plugin',
+        languages: ['en-US'], // Already configured
+        dependencies: {
+          grafanaDependency: '>=12.1.0',
+        },
+      })
+    );
+    context.addFile(
+      'docker-compose.yaml',
+      `services:
+  grafana:
+    environment:
+      FOO: bar`
+    );
+    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {}, scripts: {} }));
+    context.addFile(
+      'eslint.config.mjs',
+      'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
+    );
+    context.addFile(
+      'src/module.ts',
+      'import { PanelPlugin } from "@grafana/data";\nimport { i18n } from "@grafana/i18n";\nexport const plugin = new PanelPlugin();'
+    );
+
+    // Flush the context to simulate these files existing on "disk"
+    const initialChanges = Object.keys(context.listChanges()).length;
+
+    const result = migrate(context, { locales: ['es-ES'] });
+
+    // Should not add any NEW changes beyond the initial setup
+    const finalChanges = Object.keys(result.listChanges()).length;
+    expect(finalChanges).toBe(initialChanges);
+  });
+
+  it('should handle existing feature toggles in docker-compose.yaml (Grafana >= 12.1.0)', () => {
+    const context = new Context('/virtual');
+
+    context.addFile(
+      'src/plugin.json',
+      JSON.stringify({
+        id: 'test-plugin',
+        type: 'panel',
+        name: 'Test Plugin',
+        dependencies: {
+          grafanaDependency: '>=12.1.0',
+        },
+      })
+    );
+    context.addFile(
+      'docker-compose.yaml',
+      `services:
+  grafana:
+    environment:
+      GF_FEATURE_TOGGLES_ENABLE: someOtherFeature`
+    );
+    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {}, scripts: {} }));
+    context.addFile(
+      'eslint.config.mjs',
+      'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
+    );
+    context.addFile(
+      'src/module.ts',
+      'import { PanelPlugin } from "@grafana/data";\nexport const plugin = new PanelPlugin();'
+    );
+
+    const result = migrate(context, { locales: ['en-US'] });
+
+    const dockerCompose = result.getFile('docker-compose.yaml');
+    expect(dockerCompose).toContain('someOtherFeature,localizationForPlugins');
+  });
+
+  it('should work with module.tsx instead of module.ts', () => {
+    const context = new Context('/virtual');
+
+    context.addFile(
+      'src/plugin.json',
+      JSON.stringify({
+        id: 'test-plugin',
+        type: 'panel',
+        name: 'Test Plugin',
+        dependencies: {
+          grafanaDependency: '>=11.0.0',
+        },
+      })
+    );
+    context.addFile(
+      'docker-compose.yaml',
+      `services:
+  grafana:
+    environment:
+      FOO: bar`
+    );
+    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {}, scripts: {} }));
+    context.addFile(
+      'eslint.config.mjs',
+      'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
+    );
+    context.addFile(
+      'src/module.tsx',
+      'import { PanelPlugin } from "@grafana/data";\nexport const plugin = new PanelPlugin();'
+    );
+
+    const result = migrate(context, { locales: ['en-US'] });
+
+    const moduleTsx = result.getFile('src/module.tsx');
+    expect(moduleTsx).toContain('@grafana/i18n');
+  });
+
+  it('should not update grafanaDependency if it is already >= 12.1.0', () => {
+    const context = new Context('/virtual');
+
+    context.addFile(
+      'src/plugin.json',
+      JSON.stringify({
+        id: 'test-plugin',
+        type: 'panel',
+        name: 'Test Plugin',
+        dependencies: {
+          grafanaDependency: '>=13.0.0',
+        },
+      })
+    );
+    context.addFile(
+      'docker-compose.yaml',
+      `services:
+  grafana:
+    environment:
+      FOO: bar`
+    );
+    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {}, scripts: {} }));
+    context.addFile(
+      'eslint.config.mjs',
+      'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
+    );
+    context.addFile(
+      'src/module.ts',
+      'import { PanelPlugin } from "@grafana/data";\nexport const plugin = new PanelPlugin();'
+    );
+
+    const result = migrate(context, { locales: ['en-US'] });
+
+    const pluginJson = JSON.parse(result.getFile('src/plugin.json') || '{}');
+    expect(pluginJson.dependencies.grafanaDependency).toBe('>=13.0.0');
+  });
+
+  it('should handle plugins without existing scripts in package.json', () => {
+    const context = new Context('/virtual');
+
+    context.addFile(
+      'src/plugin.json',
+      JSON.stringify({
+        id: 'test-plugin',
+        type: 'panel',
+        name: 'Test Plugin',
+        dependencies: {
+          grafanaDependency: '>=11.0.0',
+        },
+      })
+    );
+    context.addFile(
+      'docker-compose.yaml',
+      `services:
+  grafana:
+    environment:
+      FOO: bar`
+    );
+    context.addFile('package.json', JSON.stringify({ dependencies: {}, devDependencies: {} })); // No scripts field
+    context.addFile(
+      'eslint.config.mjs',
+      'import { defineConfig } from "eslint/config";\nexport default defineConfig([]);'
+    );
+    context.addFile(
+      'src/module.ts',
+      'import { PanelPlugin } from "@grafana/data";\nexport const plugin = new PanelPlugin();'
+    );
+
+    const result = migrate(context, { locales: ['en-US'] });
+
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+    expect(packageJson.scripts['i18n-extract']).toBe('i18next-cli extract --sync-primary');
+  });
+});