@grafana/create-plugin 7.10.1 → 7.11.0

package/src/codemods/additions/scripts/experimental-app-sdk.ts

@@ -0,0 +1,431 @@
+import { fileURLToPath } from 'node:url';
+import { styleText } from 'node:util';
+import { parseDocument, stringify, YAMLMap, Scalar } from 'yaml';
+import type { Context, ContextMessage } from '../../context.js';
+import { getBackendCmd } from '../../../commands/generate/print-success-message.js';
+import { output } from '../../../utils/utils.console.js';
+import { additionsDebug, renderTemplate } from '../../utils.js';
+import { addRequireToGoMod } from '../../utils.goMod.js';
+import { getTemplateData } from '../../../utils/utils.templates.js';
+
+// Grafana reads an app-sdk manifest from the plugin bundle, and registers its API server, only when
+// these toggles are enabled.
+const APP_SDK_FEATURE_TOGGLES = ['appplugins.loadAppManifest', 'appplugins.registerAPIServer'];
+
+// Files copied verbatim from templates/app-sdk, and whether they get the "scaffolded by create-plugin,
+// don't edit" header. Paths are relative to both the template folder and the plugin root.
+//
+// The CUE kinds and the drift-check workflow are meant to be edited (declaring your own kinds is the
+// point, and users may want to tweak the workflow's triggers), so they're excluded. generate-kinds.mjs
+// is a tool, not something devs hand-edit, so it gets the header.
+const TEMPLATE_FILES: Array<[path: string, includeWarning: boolean]> = [
+  ['.config/app-sdk/generate-kinds.mjs', true],
+  ['.config/app-sdk/README.md', false],
+  ['.github/workflows/generate-kinds-drift.yml', false],
+  ['kinds/config.cue', false],
+  ['kinds/manifest.cue', false],
+  ['kinds/example.cue', false],
+  ['kinds/cue.mod/module.cue', false],
+  ['kinds/README.md', false],
+];
+
+// Points agents at the app-sdk guidance. Only added alongside an existing instructions.md.
+const APP_SDK_MD = '.config/AGENTS/app-sdk.md';
+
+/**
+ * Adds grafana-app-sdk CUE kind code generation to an existing app plugin.
+ *
+ * Every step is guarded so re-running is a no-op, and user edits to the scaffolded CUE are never
+ * overwritten.
+ */
+export default function appSdk(context: Context): Context {
+  if (!isAppPlugin(context)) {
+    return context;
+  }
+
+  const changesBefore = Object.keys(context.listChanges()).length;
+
+  addTemplateFiles(context);
+  referenceAgentInstructions(context);
+  addGenerateScript(context);
+  addFeatureToggle(context);
+  wireGoBackend(context);
+
+  // Only guide the user when we actually scaffolded something; a re-run should stay quiet.
+  if (Object.keys(context.listChanges()).length > changesBefore) {
+    context.setMessage(buildNextStepsMessage(hasGoBackend(context)));
+  }
+
+  return context;
+}
+
+/**
+ * Kinds are served per app, so codegen only applies to app plugins. A Go backend is not required:
+ * Grafana can serve kinds from the bundled manifest alone.
+ */
+function isAppPlugin(context: Context): boolean {
+  const pluginJsonContent = context.getFile('src/plugin.json');
+
+  if (!pluginJsonContent) {
+    skip('Could not find src/plugin.json.', ['Run this from the root of your plugin.']);
+    return false;
+  }
+
+  let pluginJson;
+  try {
+    pluginJson = JSON.parse(pluginJsonContent);
+  } catch (error) {
+    additionsDebug(`Failed to parse src/plugin.json: ${error}`);
+    skip('Could not parse src/plugin.json.');
+    return false;
+  }
+
+  if (pluginJson.type !== 'app') {
+    skip(`grafana-app-sdk codegen needs an app plugin, but this is a ${pluginJson.type} plugin.`, [
+      'The app-sdk serves Kubernetes-style resources from an app plugin.',
+    ]);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Explains why nothing happened. The runner reports success for a no-op codemod, so without this the
+ * user is left guessing.
+ */
+function skip(title: string, body: string[] = []) {
+  output.warning({ title: `Skipping app-sdk: ${title}`, body });
+}
+
+function addTemplateFiles(context: Context) {
+  for (const [file, includeWarning] of TEMPLATE_FILES) {
+    if (context.doesFileExist(file)) {
+      additionsDebug(`${file} already exists. Skipping.`);
+      continue;
+    }
+
+    context.addFile(file, renderTemplate(templatePath(file), includeWarning));
+  }
+}
+
+function templatePath(file: string): string {
+  return fileURLToPath(new URL(`../../../../templates/app-sdk/${file}`, import.meta.url));
+}
+
+/**
+ * Points the plugin's agent instructions at the app-sdk ones.
+ *
+ * On a fresh scaffold this line is rendered into instructions.md by the template. Retrofitted plugins
+ * have an instructions.md that predates the flag, so add it here — without it, an agent reading the
+ * plugin's instructions has no idea kinds or generated code exist.
+ */
+function referenceAgentInstructions(context: Context) {
+  const path = '.config/AGENTS/instructions.md';
+  const instructions = context.getFile(path);
+
+  if (!instructions) {
+    additionsDebug(`Could not find ${path}. Skipping the app-sdk reference.`);
+    return;
+  }
+
+  if (!context.doesFileExist(APP_SDK_MD)) {
+    context.addFile(APP_SDK_MD, renderTemplate(templatePath(APP_SDK_MD), false));
+  }
+
+  if (instructions.includes(APP_SDK_MD)) {
+    return;
+  }
+
+  context.updateFile(
+    path,
+    `${instructions.trimEnd()}\n- This plugin defines its API resources as **CUE kinds** under \`kinds/\`, with TypeScript and Go types generated from them. Read @./${APP_SDK_MD} before changing anything under \`kinds/\` or any generated directory. **Never hand-edit generated code.**\n`
+  );
+}
+
+/** Adds the `generate:kinds` npm script that runs code generation. */
+function addGenerateScript(context: Context) {
+  const raw = context.getFile('package.json');
+
+  if (!raw) {
+    additionsDebug('Could not find package.json. Skipping the generate:kinds script.');
+    return;
+  }
+
+  let packageJson;
+  try {
+    packageJson = JSON.parse(raw);
+  } catch (error) {
+    additionsDebug(`Failed to parse package.json: ${error}`);
+    return;
+  }
+
+  if (packageJson.scripts?.['generate:kinds']) {
+    additionsDebug('A generate:kinds script already exists. Skipping.');
+    return;
+  }
+
+  packageJson.scripts = { ...packageJson.scripts, 'generate:kinds': 'node ./.config/app-sdk/generate-kinds.mjs' };
+  context.updateFile('package.json', JSON.stringify(packageJson, null, 2));
+}
+
+/**
+ * Enables the app-sdk manifest feature toggle on the dev server.
+ *
+ * The toggle goes in the root docker-compose.yaml rather than .config/docker-compose-base.yaml,
+ * because the root file is the one users own.
+ */
+function addFeatureToggle(context: Context) {
+  const composePath = 'docker-compose.yaml';
+  const composeContent = context.getFile(composePath);
+
+  if (!composeContent) {
+    additionsDebug(`Could not find ${composePath}. Skipping the feature toggle.`);
+    return;
+  }
+
+  // Already set in the base config, so adding it to the root file would be redundant. Note compose
+  // replaces (rather than merges) a scalar value across `extends`, so a root value would also mask
+  // any other toggles the base file sets.
+  const baseComposeContent = context.getFile('.config/docker-compose-base.yaml');
+  if (APP_SDK_FEATURE_TOGGLES.every((toggle) => baseComposeContent?.includes(toggle))) {
+    additionsDebug(`${APP_SDK_FEATURE_TOGGLES.join(', ')} are already enabled in the base compose file. Skipping.`);
+    return;
+  }
+
+  const composeData = parseDocument(composeContent);
+  const environment = composeData.getIn(['services', 'grafana', 'environment']);
+
+  if (environment !== undefined && !(environment instanceof YAMLMap)) {
+    additionsDebug(
+      `services.grafana.environment in ${composePath} is not a mapping. Add ${APP_SDK_FEATURE_TOGGLES.join(', ')} to GF_FEATURE_TOGGLES_ENABLE manually.`
+    );
+    return;
+  }
+
+  const grafanaService = composeData.getIn(['services', 'grafana']);
+  if (!(grafanaService instanceof YAMLMap)) {
+    additionsDebug(`Could not find the grafana service in ${composePath}. Skipping the feature toggle.`);
+    return;
+  }
+
+  const existing = composeData.getIn(['services', 'grafana', 'environment', 'GF_FEATURE_TOGGLES_ENABLE'], true);
+  const existingValue = existing instanceof Scalar ? String(existing.value) : undefined;
+  const toggles = existingValue
+    ? existingValue
+        .split(',')
+        .map((toggle) => toggle.trim())
+        .filter(Boolean)
+    : [];
+
+  const missingToggles = APP_SDK_FEATURE_TOGGLES.filter((toggle) => !toggles.includes(toggle));
+
+  if (missingToggles.length === 0) {
+    additionsDebug(`${APP_SDK_FEATURE_TOGGLES.join(', ')} are already enabled. Skipping.`);
+    return;
+  }
+
+  toggles.push(...missingToggles);
+  composeData.setIn(['services', 'grafana', 'environment', 'GF_FEATURE_TOGGLES_ENABLE'], toggles.join(','));
+
+  context.updateFile(composePath, stringify(composeData, { lineWidth: 120, singleQuote: true }));
+}
+
+/**
+ * Wires the generated kinds into the Go backend, for app plugins that have one. Go code generation
+ * itself is enabled when kinds/config.cue is first scaffolded, in addTemplateFiles.
+ */
+function wireGoBackend(context: Context) {
+  if (!hasGoBackend(context)) {
+    additionsDebug('No Go backend found. Skipping main.go wiring.');
+    return;
+  }
+
+  addAppProvider(context);
+  addGeneratedStubs(context);
+  wireMainGo(context);
+  addGoModDependency(context);
+}
+
+// The go.mod version for grafana-app-sdk and its plugin/ submodule.
+const GRAFANA_APP_SDK_VERSION = 'v0.60.0';
+
+/**
+ * Adds github.com/grafana/grafana-app-sdk and its plugin/ submodule to go.mod. The generated Go kind
+ * types, provider.go, and main.go all import them, but the scaffolded backend's go.mod has no reason
+ * to know about either until app-sdk is added.
+ *
+ * Only adds the require lines — go.sum entries and any transitive requirements (k8s.io/apimachinery,
+ * k8s.io/kube-openapi, ...) still need `go mod tidy`. This doesn't run it itself; the codemod runner
+ * does, once every change (including the pkg/generated/ stubs below) has been flushed to disk.
+ */
+function addGoModDependency(context: Context) {
+  addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', GRAFANA_APP_SDK_VERSION);
+  addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk/plugin', GRAFANA_APP_SDK_VERSION);
+}
+
+/**
+ * Scaffolds pkg/provider/provider.go: the app.Provider/app.App wiring that plugin.Run needs, built
+ * from the generated manifest and the example kind. Named "provider", not "app", so it doesn't
+ * collide with the app-sdk's own `app` package and force an import alias everywhere it's used.
+ *
+ * Not overwritten on a re-run — like kinds/*.cue, it's meant to be edited as the plugin adds
+ * validators, mutators, or more kinds.
+ */
+function addAppProvider(context: Context) {
+  const path = 'pkg/provider/provider.go';
+
+  if (context.doesFileExist(path)) {
+    additionsDebug(`${path} already exists. Skipping.`);
+    return;
+  }
+
+  context.addFile(path, renderTemplate(templatePath(path), false));
+}
+
+// Stub doc.go files under pkg/generated/. Both are real packages `generate:kinds` fills in; they
+// exist solely so the `go mod tidy` the codemod runner runs automatically (see runGoModTidy in
+// ../../utils.js) succeeds before code generation has ever run, since it otherwise can't resolve the
+// packages pkg/provider/provider.go imports. `generate:kinds` writes its own, differently-named files
+// into these directories rather than overwriting doc.go, so it's left behind afterwards — but an
+// unused doc.go with no exported symbols compiles fine alongside the generated code.
+const GENERATED_STUB_PATHS = ['pkg/generated/example/v1alpha1/doc.go', 'pkg/generated/manifestdata/doc.go'];
+
+/**
+ * Scaffolds stub packages under pkg/generated/, so provider.go's imports resolve for `go mod tidy`
+ * before `generate:kinds` has run for the first time.
+ */
+function addGeneratedStubs(context: Context) {
+  for (const path of GENERATED_STUB_PATHS) {
+    if (context.doesFileExist(path)) {
+      additionsDebug(`${path} already exists. Skipping.`);
+      continue;
+    }
+
+    context.addFile(path, renderTemplate(templatePath(path), false));
+  }
+}
+
+/** A Go backend is declared by `backend: true` in src/plugin.json, same as the rest of create-plugin. */
+function hasGoBackend(context: Context): boolean {
+  const pluginJsonContent = context.getFile('src/plugin.json');
+
+  if (!pluginJsonContent) {
+    return false;
+  }
+
+  try {
+    return JSON.parse(pluginJsonContent).backend === true;
+  } catch (error) {
+    additionsDebug(`Failed to parse src/plugin.json: ${error}`);
+    return false;
+  }
+}
+
+// Matches the backend-app template's `if err := app.Manage(...); err != nil { ... }` statement,
+// capturing the plugin ID, app factory, and error-handling body so they can be preserved verbatim.
+const APP_MANAGE_STATEMENT_REGEX =
+  /if err := app\.Manage\((".*?"), (\S+), app\.ManageOpts\{\}\); err != nil \{\n(\t+[\s\S]*?\n)\t\}/;
+
+/**
+ * Wires the app-sdk's plugin.Run helper into main.go, replacing the plain app.Manage call, using the
+ * app.Provider scaffolded into pkg/provider by addAppProvider.
+ *
+ * Bails out rather than guessing if main.go has already diverged from the scaffolded shape this
+ * transform expects.
+ */
+function wireMainGo(context: Context) {
+  const path = 'pkg/main.go';
+  const content = context.getFile(path);
+
+  if (!content) {
+    additionsDebug(`Could not find ${path}. Skipping the app-sdk backend wiring.`);
+    return;
+  }
+
+  if (content.includes('grafana-app-sdk/plugin"')) {
+    additionsDebug(`${path} already wires plugin.Run. Skipping.`);
+    return;
+  }
+
+  const match = content.match(APP_MANAGE_STATEMENT_REGEX);
+
+  if (!match) {
+    skip(`${path} does not match the expected app.Manage(...) call.`, [
+      'Wire the grafana-app-sdk plugin.Run helper into main.go yourself:',
+      'https://github.com/grafana/grafana-app-sdk/blob/main/plugin/run.go',
+    ]);
+    return;
+  }
+
+  const [fullStatement, pluginId, appFactory, errorBody] = match;
+  const moduleMatch = content.match(/"(github\.com\/[^/]+\/[^/]+)\/pkg\/plugin"/);
+  const providerImportPath = moduleMatch ? `${moduleMatch[1]}/pkg/provider` : undefined;
+
+  if (!providerImportPath) {
+    skip(`${path} does not import its own pkg/plugin package under a recognisable module path.`, [
+      'Wire the grafana-app-sdk plugin.Run helper into main.go yourself:',
+      'https://github.com/grafana/grafana-app-sdk/blob/main/plugin/run.go',
+    ]);
+    return;
+  }
+
+  const appImport = '\t"github.com/grafana/grafana-plugin-sdk-go/backend/app"';
+  const pluginImport = `"${moduleMatch![1]}/pkg/plugin"`;
+
+  if (!content.includes(appImport) || !content.includes(pluginImport)) {
+    skip(`${path} does not match the expected import shape.`, [
+      'Wire the grafana-app-sdk plugin.Run helper into main.go yourself:',
+      'https://github.com/grafana/grafana-app-sdk/blob/main/plugin/run.go',
+    ]);
+    return;
+  }
+
+  const updated = content
+    .replace(appImport, '\tsdkplugin "github.com/grafana/grafana-app-sdk/plugin"')
+    .replace(pluginImport, `${pluginImport}\n\t"${providerImportPath}"`)
+    .replace(
+      fullStatement,
+      `if err := sdkplugin.Run(
+		provider.New(),
+		sdkplugin.WithPluginID(${pluginId}),
+		sdkplugin.WithAppFunc(${appFactory}),
+	); err != nil {
+${errorBody}\t}`
+    );
+
+  context.updateFile(path, updated);
+}
+
+/** Builds the message telling the user what to run next. */
+function buildNextStepsMessage(hasGoBackend: boolean): ContextMessage {
+  const { packageManagerName } = getTemplateData();
+  const versionBadge = styleText(['reset', 'inverse', 'bold', 'cyan'], ` grafana-app-sdk@${GRAFANA_APP_SDK_VERSION} `);
+
+  const commands = output.bulletList([
+    `${output.formatCode(`${packageManagerName} run generate:kinds`)} ${styleText(['dim'], 'to generate code from the definitions in kinds/')}`,
+    ...(hasGoBackend
+      ? [
+          // The generated Go code under pkg/generated/ only takes effect once it's compiled into the
+          // backend binary.
+          `${getBackendCmd()} ${styleText(['dim'], 'to rebuild the plugin backend with the generated code')}`,
+        ]
+      : []),
+    // Grafana reads the app manifest from the bundle at startup, so a manifest change (any change to
+    // the kinds) isn't picked up by an already-running Grafana instance until it's restarted.
+    `${output.formatCode('docker compose restart grafana')} ${styleText(['dim'], 'to pick up changes to kinds/')}`,
+  ]);
+
+  return {
+    level: 'success',
+    title: 'Successfully added grafana-app-sdk code generation to your plugin.',
+    body: [
+      `${versionBadge} ${styleText(['cyan', 'bold'], 'Next steps:')}`,
+      '',
+      'Run the following commands to get started:',
+      ...commands,
+      '',
+      `See ${output.formatCode('./.config/app-sdk/README.md')} for the full workflow.`,
+    ],
+  };
+}

package/src/codemods/context.test.ts

@@ -62,10 +62,16 @@ describe('Context', () => {
 
   describe('updateFile', () => {
     it('should update a file in the context', () => {
+      const context = new Context(`${__dirname}/migrations/fixtures`);
+      context.updateFile('foo/bar.ts', 'new content');
+      expect(context.listChanges()).toEqual({ 'foo/bar.ts': { content: 'new content', changeType: 'update' } });
+    });
+
+    it("should preserve the 'add' changeType when updating a file that was added in the current 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' } });
+      expect(context.listChanges()).toEqual({ 'file.txt': { content: 'new content', changeType: 'add' } });
     });
 
     it('should not update a file if it does not exist', () => {

package/src/codemods/context.ts

@@ -12,14 +12,33 @@ export type ContextFile = Record<
   }
 >;
 
+export interface ContextMessage {
+  level: 'error' | 'success' | 'warning' | 'log';
+  title: string;
+  body?: string[];
+}
+
 export class Context {
   private files: ContextFile = {};
+  private message?: ContextMessage;
   basePath: string;
 
   constructor(basePath?: string) {
     this.basePath = basePath || process.cwd();
   }
 
+  /**
+   * Lets a codemod defer printing a message until after the caller has reported success, instead
+   * of printing immediately during the codemod's own execution.
+   */
+  setMessage(message: ContextMessage) {
+    this.message = message;
+  }
+
+  getMessage() {
+    return this.message;
+  }
+
   addFile(filePath: string, content: string) {
     const path = this.normalisePath(filePath);
     if (!this.doesFileExist(path)) {
@@ -58,7 +77,10 @@ export class Context {
     }
 
     if (originalContent !== content) {
-      this.files[path] = { content, changeType: 'update' };
+      // Preserve 'add' so a file added earlier in this same context (its directory may not exist on
+      // disk yet) doesn't get downgraded to 'update' and fail to write.
+      const changeType = this.files[path]?.changeType === 'add' ? 'add' : 'update';
+      this.files[path] = { content, changeType };
     } else {
       codemodsDebug(`Context.updateFile() - no updates for ${filePath}`);
     }

package/src/codemods/runner.ts

@@ -1,5 +1,5 @@
 import { Context } from './context.js';
-import { formatFiles, flushChanges, installNPMDependencies, printChanges } from './utils.js';
+import { formatFiles, flushChanges, installNPMDependencies, printChanges, runGoModTidy } from './utils.js';
 import { parseAndValidateOptions } from './schema-parser.js';
 import { Codemod } from './types.js';
 
@@ -14,6 +14,7 @@ import { Codemod } from './types.js';
  * 5. Flush changes to disk
  * 6. Print summary
  * 7. Install dependencies if needed
+ * 8. Run `go mod tidy` if go.mod changed
  */
 export async function runCodemod(codemod: Codemod, options?: Record<string, any>): Promise<Context> {
   const codemodModule = await import(codemod.scriptPath);
@@ -38,6 +39,7 @@ export async function runCodemod(codemod: Codemod, options?: Record<string, any>
     flushChanges(updatedContext);
     printChanges(updatedContext, codemod.name, codemod.description);
     installNPMDependencies(updatedContext);
+    runGoModTidy(updatedContext);
 
     return updatedContext;
   } catch (error) {

package/src/codemods/utils.goMod.test.ts

@@ -0,0 +1,86 @@
+import { Context } from './context.js';
+import { addRequireToGoMod } from './utils.goMod.js';
+
+const GO_MOD = `module github.com/my-org/my-plugin
+
+go 1.26.3
+
+require github.com/grafana/grafana-plugin-sdk-go v0.285.0
+
+require (
+	github.com/BurntSushi/toml v1.5.0 // indirect
+)
+`;
+
+describe('addRequireToGoMod', () => {
+  it('inserts a new require line after the last existing one', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', GO_MOD);
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    const goMod = context.getFile('go.mod') ?? '';
+    expect(goMod).toContain('require github.com/grafana/grafana-app-sdk v0.59.1');
+    // The existing require survives, and the new one is inserted right after it.
+    expect(goMod).toContain(
+      'require github.com/grafana/grafana-plugin-sdk-go v0.285.0\nrequire github.com/grafana/grafana-app-sdk v0.59.1'
+    );
+    // The grouped require (...) block is left untouched.
+    expect(goMod).toContain('require (\n\tgithub.com/BurntSushi/toml v1.5.0 // indirect\n)');
+  });
+
+  it('inserts after the go directive when there is no existing require line', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', 'module github.com/my-org/my-plugin\n\ngo 1.26.3\n');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    const goMod = context.getFile('go.mod') ?? '';
+    expect(goMod).toBe(
+      'module github.com/my-org/my-plugin\n\ngo 1.26.3\nrequire github.com/grafana/grafana-app-sdk v0.59.1\n'
+    );
+  });
+
+  it('does not duplicate an already-present dependency at the same version', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', GO_MOD);
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+    const afterFirst = context.getFile('go.mod');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    expect(context.getFile('go.mod')).toBe(afterFirst);
+  });
+
+  it('bumps the version when a greater one is requested', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', GO_MOD);
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.60.0');
+
+    const goMod = context.getFile('go.mod') ?? '';
+    expect(goMod).toContain('require github.com/grafana/grafana-app-sdk v0.60.0');
+    expect(goMod).not.toContain('v0.59.1');
+  });
+
+  it('does not downgrade when a lesser version is requested', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', GO_MOD);
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.60.0');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    const goMod = context.getFile('go.mod') ?? '';
+    expect(goMod).toContain('require github.com/grafana/grafana-app-sdk v0.60.0');
+    expect(goMod).not.toContain('v0.59.1');
+  });
+
+  it('does nothing when go.mod does not exist', () => {
+    const context = new Context('/virtual');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    expect(context.doesFileExist('go.mod')).toBe(false);
+  });
+});

package/src/codemods/utils.goMod.ts

@@ -0,0 +1,70 @@
+import type { Context } from './context.js';
+import { isVersionGreater, migrationsDebug } from './utils.js';
+
+// Matches a single-line `require <module> <version>` statement (with an optional trailing
+// `// indirect` comment), the shape every codemod-scaffolded backend's go.mod uses.
+function singleLineRequireRegex(modulePath: string): RegExp {
+  const escapedModulePath = modulePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^require ${escapedModulePath} (\\S+)(.*)$`, 'm');
+}
+
+/**
+ * Adds a `require <modulePath> <version>` line to go.mod, or bumps its version if it's already
+ * present with a lower one (using the same version-comparison logic as addDependenciesToPackageJson).
+ *
+ * Only understands the single-line `require <module> <version>` form that create-plugin's own
+ * templates use — it does not parse grouped `require (...)` blocks, `replace`/`exclude` directives,
+ * or anything else that would need a real go.mod grammar. A codemod that needs that should shell out
+ * to `go mod edit` against the real file on disk instead (see utils.goSdk.ts), outside of Context.
+ */
+export function addRequireToGoMod(context: Context, modulePath: string, version: string, goModPath = 'go.mod') {
+  const content = context.getFile(goModPath);
+
+  if (!content) {
+    migrationsDebug(`Could not find ${goModPath}. Skipping the ${modulePath} dependency.`);
+    return;
+  }
+
+  const requireRegex = singleLineRequireRegex(modulePath);
+  const match = content.match(requireRegex);
+
+  if (match) {
+    const [, existingVersion] = match;
+    if (!isVersionGreater(version, existingVersion, false)) {
+      migrationsDebug(`${goModPath} already requires ${modulePath} at ${existingVersion}. Skipping.`);
+      return;
+    }
+
+    const updated = content.replace(requireRegex, `require ${modulePath} ${version}$2`);
+    context.updateFile(goModPath, updated);
+    return;
+  }
+
+  const insertAt = findRequireInsertionPoint(content);
+  const newRequireLine = `require ${modulePath} ${version}\n`;
+
+  context.updateFile(goModPath, `${content.slice(0, insertAt)}${newRequireLine}${content.slice(insertAt)}`);
+}
+
+/**
+ * Finds where to insert a new top-level `require ...` line: right after the last existing one, else
+ * right after the `go 1.x` directive, else at the end of the file.
+ */
+function findRequireInsertionPoint(content: string): number {
+  const requireLines = [...content.matchAll(/^require \S+ \S+.*$/gm)];
+  const lastRequireLine = requireLines[requireLines.length - 1];
+
+  if (lastRequireLine) {
+    const lineEnd = content.indexOf('\n', lastRequireLine.index! + lastRequireLine[0].length);
+    return lineEnd === -1 ? content.length : lineEnd + 1;
+  }
+
+  const goDirective = content.match(/^go \d+\.\d+(\.\d+)?.*$/m);
+
+  if (goDirective) {
+    const lineEnd = content.indexOf('\n', goDirective.index! + goDirective[0].length);
+    return lineEnd === -1 ? content.length : lineEnd + 1;
+  }
+
+  return content.length;
+}