@grafana/create-plugin 7.13.0 → 7.15.0

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

@@ -252,7 +252,7 @@ describe('experimental-app-sdk addition', () => {
       const result = appSdk(context);
 
       expect(result.getFile('docker-compose.yaml')).toContain(
-        'GF_FEATURE_TOGGLES_ENABLE: appplugins.loadAppManifest,appplugins.registerAPIServer'
+        'GF_FEATURE_TOGGLES_ENABLE: appplugins.loadAppManifest,appplugins.registerAPIServer,grafana.useRouterMiddleware'
       );
     });
 
@@ -274,6 +274,7 @@ describe('experimental-app-sdk addition', () => {
       expect(compose).toContain('someOtherToggle');
       expect(compose).toContain('appplugins.loadAppManifest');
       expect(compose).toContain('appplugins.registerAPIServer');
+      expect(compose).toContain('grafana.useRouterMiddleware');
     });
 
     it('does not duplicate the toggles when they are already set', () => {
@@ -284,7 +285,7 @@ describe('experimental-app-sdk addition', () => {
       file: .config/docker-compose-base.yaml
       service: grafana
     environment:
-      GF_FEATURE_TOGGLES_ENABLE: appplugins.loadAppManifest,appplugins.registerAPIServer
+      GF_FEATURE_TOGGLES_ENABLE: appplugins.loadAppManifest,appplugins.registerAPIServer,grafana.useRouterMiddleware
 `,
       });
 
@@ -321,7 +322,7 @@ describe('experimental-app-sdk addition', () => {
         `services:
   grafana:
     environment:
-      GF_FEATURE_TOGGLES_ENABLE: appplugins.loadAppManifest,appplugins.registerAPIServer
+      GF_FEATURE_TOGGLES_ENABLE: appplugins.loadAppManifest,appplugins.registerAPIServer,grafana.useRouterMiddleware
 `
       );
 

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

@@ -6,11 +6,16 @@ import type { TemplateData } from '../../../types.js';
 import { getBackendCmd } from '../../../commands/generate/print-success-message.js';
 import { output } from '../../../utils/utils.console.js';
 import { additionsDebug, getTemplateDataFromContext, renderTemplate } from '../../utils.js';
+import { AGENT_INSTRUCTIONS_PATH, appendToAgentInstructions } from '../../utils.agents.js';
 import { addRequireToGoMod } from '../../utils.goMod.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'];
+// these toggles are enabled. The router middleware lets the app's requests through the router.
+const APP_SDK_FEATURE_TOGGLES = [
+  'appplugins.loadAppManifest',
+  'appplugins.registerAPIServer',
+  'grafana.useRouterMiddleware',
+];
 
 // 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.
@@ -130,11 +135,8 @@ function renderAppSdkTemplate(file: string, data: TemplateData, includeWarning =
  * plugin's instructions has no idea kinds or generated code exist.
  */
 function referenceAgentInstructions(context: Context, data: TemplateData) {
-  const path = '.config/AGENTS/instructions.md';
-  const instructions = context.getFile(path);
-
-  if (!instructions) {
-    additionsDebug(`Could not find ${path}. Skipping the app-sdk reference.`);
+  if (!context.doesFileExist(AGENT_INSTRUCTIONS_PATH)) {
+    additionsDebug(`Could not find ${AGENT_INSTRUCTIONS_PATH}. Skipping the app-sdk reference.`);
     return;
   }
 
@@ -142,13 +144,11 @@ function referenceAgentInstructions(context: Context, data: TemplateData) {
     context.addFile(APP_SDK_MD, renderAppSdkTemplate(APP_SDK_MD, data));
   }
 
-  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`
+  appendToAgentInstructions(
+    context,
+    APP_SDK_MD,
+    `- 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`,
+    '\n'
   );
 }
 
@@ -257,7 +257,7 @@ function wireGoBackend(context: Context, data: TemplateData) {
 }
 
 // The go.mod version for grafana-app-sdk and its plugin/ submodule.
-const GRAFANA_APP_SDK_VERSION = 'v0.60.3';
+const GRAFANA_APP_SDK_VERSION = 'v0.60.16';
 
 /**
  * Adds github.com/grafana/grafana-app-sdk and its plugin/ submodule to go.mod. The generated Go kind

package/src/codemods/migrations/scripts/004-eslint9-flat-config.ts

@@ -159,9 +159,7 @@ function addConfigsToMigration(imports: Imports, config: Linter.ConfigOverride)
 function generateAST(
   value: Object
 ):
-  | recast.types.namedTypes.ObjectExpression
-  | recast.types.namedTypes.ArrayExpression
-  | recast.types.namedTypes.Literal {
+  recast.types.namedTypes.ObjectExpression | recast.types.namedTypes.ArrayExpression | recast.types.namedTypes.Literal {
   if (Array.isArray(value)) {
     return builders.arrayExpression(value.map((i) => generateAST(i)));
   }

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

@@ -0,0 +1,140 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Context } from './context.js';
+import {
+  AGENT_INSTRUCTIONS_PATH,
+  INSTRUCTIONS_POINTER,
+  appendToAgentInstructions,
+  ensureConfigAgentFiles,
+  ensureRootAgentFiles,
+} from './utils.agents.js';
+
+describe('utils.agents', () => {
+  describe('ensureRootAgentFiles', () => {
+    const templateDir = join(__dirname, '..', '..', 'templates', 'common');
+
+    it('creates the missing root agent files', () => {
+      const context = new Context('/virtual');
+      expect(ensureRootAgentFiles(context, templateDir)).toEqual([]);
+      for (const file of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
+        expect(context.getFile(file), file).toContain(AGENT_INSTRUCTIONS_PATH);
+      }
+    });
+
+    it('appends a pointer to an existing file that never reaches instructions.md', () => {
+      const context = new Context('/virtual');
+      context.addFile('CLAUDE.md', '# Mine\n');
+      expect(ensureRootAgentFiles(context, templateDir)).toEqual(['CLAUDE.md']);
+      expect(context.getFile('CLAUDE.md')).toContain(AGENT_INSTRUCTIONS_PATH);
+      expect(context.getFile('CLAUDE.md')).toContain('# Mine');
+    });
+
+    it('treats a file that imports a linked AGENTS.md as linked', () => {
+      const context = new Context('/virtual');
+      context.addFile('AGENTS.md', `Read @./${AGENT_INSTRUCTIONS_PATH}\n`);
+      context.addFile('CLAUDE.md', '@AGENTS.md\n');
+      expect(ensureRootAgentFiles(context, templateDir)).toEqual([]);
+      expect(context.getFile('CLAUDE.md')).toBe('@AGENTS.md\n');
+    });
+
+    it.each(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'])('uses the same pointer as the %s template', (file) => {
+      expect(readFileSync(join(templateDir, file), 'utf-8')).toContain(INSTRUCTIONS_POINTER);
+    });
+
+    it.each([
+      ['a plain mention of AGENTS.md', 'Codex reads AGENTS.md, this file is for Claude.\n'],
+      ['a markdown link to AGENTS.md', 'See [the guide](AGENTS.md).\n'],
+      ['a plain mention of the instructions', `Don't edit ${AGENT_INSTRUCTIONS_PATH} by hand.\n`],
+    ])('links a CLAUDE.md with only %s', (_, content) => {
+      const context = new Context('/virtual');
+      context.addFile('AGENTS.md', `Read @./${AGENT_INSTRUCTIONS_PATH}\n`);
+      context.addFile('CLAUDE.md', content);
+      expect(ensureRootAgentFiles(context, templateDir)).toEqual(['CLAUDE.md']);
+      expect(context.getFile('CLAUDE.md')).toBe(`${content}\n${INSTRUCTIONS_POINTER}`);
+    });
+
+    it('treats a plain mention of the instructions in AGENTS.md as linked', () => {
+      const context = new Context('/virtual');
+      context.addFile('AGENTS.md', `Read ${AGENT_INSTRUCTIONS_PATH} first.\n`);
+      expect(ensureRootAgentFiles(context, templateDir)).toEqual([]);
+    });
+
+    it('links existing files that never reach instructions.md', () => {
+      const context = new Context('/virtual');
+      context.addFile('AGENTS.md', '# Mine\n');
+      context.addFile('CLAUDE.md', '@AGENTS.md\n');
+      context.addFile('GEMINI.md', 'See docs/AGENTS.md\n');
+      // AGENTS.md gets the pointer first, so CLAUDE.md's @AGENTS.md then resolves without its own edit
+      expect(ensureRootAgentFiles(context, templateDir)).toEqual(['AGENTS.md', 'GEMINI.md']);
+      expect(context.getFile('AGENTS.md')).toContain(AGENT_INSTRUCTIONS_PATH);
+      expect(context.getFile('CLAUDE.md')).toBe('@AGENTS.md\n');
+      expect(context.getFile('GEMINI.md')).toContain(AGENT_INSTRUCTIONS_PATH);
+    });
+  });
+
+  describe('ensureConfigAgentFiles', () => {
+    const templateDir = join(__dirname, '..', '..', 'templates', 'common');
+
+    it('creates only the given files from the template dir and returns them', () => {
+      const context = new Context('/virtual');
+      const added = ensureConfigAgentFiles(context, templateDir, ['instructions.md', 'e2e-testing.md'], {
+        packageManagerName: 'npm',
+      });
+
+      expect(added.sort()).toEqual(['.config/AGENTS/e2e-testing.md', AGENT_INSTRUCTIONS_PATH]);
+    });
+
+    it('does nothing when instructions.md already exists', () => {
+      const context = new Context('/virtual');
+      context.addFile(AGENT_INSTRUCTIONS_PATH, '# Mine\n');
+      expect(
+        ensureConfigAgentFiles(context, templateDir, ['instructions.md', 'e2e-testing.md'], {
+          packageManagerName: 'npm',
+        })
+      ).toEqual([]);
+
+      expect(context.getFile(AGENT_INSTRUCTIONS_PATH)).toBe('# Mine\n');
+      expect(context.doesFileExist('.config/AGENTS/e2e-testing.md')).toBe(false);
+    });
+  });
+
+  describe('appendToAgentInstructions', () => {
+    it('writes just the text into an empty instructions file', () => {
+      const context = new Context('/virtual');
+      context.addFile(AGENT_INSTRUCTIONS_PATH, '\n');
+      appendToAgentInstructions(context, 'new.md', '## New\n');
+      expect(context.getFile(AGENT_INSTRUCTIONS_PATH)).toBe('## New\n');
+    });
+
+    it('appends after a blank line', () => {
+      const context = new Context('/virtual');
+      context.addFile(AGENT_INSTRUCTIONS_PATH, '# Mine\n');
+      appendToAgentInstructions(context, 'new.md', '## New\n');
+
+      expect(context.getFile(AGENT_INSTRUCTIONS_PATH)).toBe('# Mine\n\n## New\n');
+    });
+
+    it('uses the given separator', () => {
+      const context = new Context('/virtual');
+      context.addFile(AGENT_INSTRUCTIONS_PATH, '- one\n');
+      appendToAgentInstructions(context, 'new.md', '- two\n', '\n');
+
+      expect(context.getFile(AGENT_INSTRUCTIONS_PATH)).toBe('- one\n- two\n');
+    });
+
+    it('skips when the marker is already present', () => {
+      const context = new Context('/virtual');
+      context.addFile(AGENT_INSTRUCTIONS_PATH, 'See new.md\n');
+      appendToAgentInstructions(context, 'new.md', '## New\n');
+
+      expect(context.getFile(AGENT_INSTRUCTIONS_PATH)).toBe('See new.md\n');
+    });
+
+    it('skips when there is no instructions file', () => {
+      const context = new Context('/virtual');
+      appendToAgentInstructions(context, 'new.md', '## New\n');
+
+      expect(context.doesFileExist(AGENT_INSTRUCTIONS_PATH)).toBe(false);
+    });
+  });
+});

package/src/codemods/utils.agents.ts

@@ -0,0 +1,81 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Context } from './context.js';
+import { addTemplateFolder, codemodsDebug } from './utils.js';
+
+export const AGENT_INSTRUCTIONS_PATH = '.config/AGENTS/instructions.md';
+
+const ROOT_AGENT_FILES = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
+// matches the pointer line in templates/common/{AGENTS,CLAUDE,GEMINI}.md
+export const INSTRUCTIONS_POINTER = `## Project knowledge\nThis repository contains a **Grafana plugin**. You must Read @./${AGENT_INSTRUCTIONS_PATH} before doing changes.\n`;
+const IMPORTS_INSTRUCTIONS = /@(\.\/)?\.config\/AGENTS\/instructions\.md/;
+const IMPORTS_AGENTS_MD = /(^|\s)@(\.\/)?AGENTS\.md\b/m;
+
+/**
+ * Creates the missing root agent files. Appends a pointer to the instructions to any existing one that
+ * doesn't reach them, and returns those files.
+ */
+export function ensureRootAgentFiles(context: Context, templateDir: string): string[] {
+  const existing = ROOT_AGENT_FILES.filter((file) => context.doesFileExist(file));
+  for (const file of ROOT_AGENT_FILES) {
+    if (!existing.includes(file)) {
+      context.addFile(file, readFileSync(join(templateDir, file), 'utf-8'));
+    }
+  }
+
+  // Claude and Gemini only follow `@` imports, while Codex reads AGENTS.md as text, so a mention is enough there
+  const reachesInstructions = (file: string): boolean => {
+    const content = context.getFile(file) ?? '';
+    if (file === 'AGENTS.md') {
+      return content.includes(AGENT_INSTRUCTIONS_PATH);
+    }
+    return IMPORTS_INSTRUCTIONS.test(content) || (IMPORTS_AGENTS_MD.test(content) && reachesInstructions('AGENTS.md'));
+  };
+
+  const linked: string[] = [];
+  for (const file of existing) {
+    if (reachesInstructions(file)) {
+      continue;
+    }
+    const content = context.getFile(file) ?? '';
+    context.updateFile(file, `${content.trimEnd()}\n\n${INSTRUCTIONS_POINTER}`);
+    linked.push(file);
+  }
+  return linked;
+}
+
+/**
+ * Creates the given `.config/AGENTS/` files, only when `instructions.md` is missing. They import each
+ * other, so a plugin with its own instructions keeps what it has. Returns the paths it added.
+ */
+export function ensureConfigAgentFiles(
+  context: Context,
+  templateDir: string,
+  files: string[],
+  data: Record<string, unknown>
+): string[] {
+  if (context.doesFileExist(AGENT_INSTRUCTIONS_PATH)) {
+    return [];
+  }
+  return addTemplateFolder(context, {
+    folderPath: join(templateDir, '.config', 'AGENTS'),
+    targetPath: '.config/AGENTS',
+    data,
+    include: (file) => files.includes(file),
+  });
+}
+
+/** Appends `text` to the agent instructions, unless they're missing or already contain `marker`. */
+export function appendToAgentInstructions(context: Context, marker: string, text: string, separator = '\n\n') {
+  const existing = context.getFile(AGENT_INSTRUCTIONS_PATH);
+  if (existing === undefined) {
+    codemodsDebug(`Could not find ${AGENT_INSTRUCTIONS_PATH}, skipping`);
+    return;
+  }
+  if (existing.includes(marker)) {
+    codemodsDebug(`${AGENT_INSTRUCTIONS_PATH} already contains ${marker}, skipping`);
+    return;
+  }
+  const kept = existing.trimEnd();
+  context.updateFile(AGENT_INSTRUCTIONS_PATH, kept ? `${kept}${separator}${text}` : text);
+}

package/src/codemods/utils.test.ts

@@ -196,6 +196,12 @@ describe('utils', () => {
       const context = new Context(tmpDir);
       expect(() => readJsonFile(context, 'file.json')).toThrowError();
     });
+
+    it.each(['[]', 'null', '"text"'])('should throw when the file contains %s instead of an object', (content) => {
+      const context = new Context(tmpDir);
+      context.addFile('file.json', content);
+      expect(() => readJsonFile(context, 'file.json')).toThrowError('does not contain a JSON object');
+    });
   });
 
   describe('getTemplateDataFromContext', () => {
@@ -263,6 +269,23 @@ describe('utils', () => {
       expect(context.getFile('docs/nested/setup.md')).toBe('pnpm some-name\n');
     });
 
+    it('skips files that include rejects, matching on the output path relative to the target', () => {
+      const context = new Context(tmpDir);
+      const folderPath = templateFolder({ 'README.md': 'readme\n', 'nested/page.md.hbs': 'page\n', npmrc: 'x' });
+      const seen: string[] = [];
+      const added = addTemplateFolder(context, {
+        folderPath,
+        targetPath: 'docs',
+        data,
+        include: (file) => {
+          seen.push(file);
+          return file === 'README.md';
+        },
+      });
+      expect(seen.sort()).toEqual(['.npmrc', 'README.md', 'nested/page.md']);
+      expect(added).toEqual(['docs/README.md']);
+    });
+
     it('strips .hbs and maps config file names like generate does', () => {
       const context = new Context(tmpDir);
       const folderPath = templateFolder({ 'page.md.hbs': 'x', npmrc: 'y' });

package/src/codemods/utils.ts

@@ -1,4 +1,4 @@
-import { dirname, join } from 'node:path';
+import { dirname, join, posix } from 'node:path';
 import { createRequire } from 'node:module';
 import { Context } from './context.js';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -180,11 +180,16 @@ export function readJsonFile<T extends object = any>(context: Context, path: str
   if (!context.doesFileExist(path)) {
     throw new Error(`Cannot find ${path}`);
   }
+  let parsed: unknown;
   try {
-    return JSON.parse(context.getFile(path) || '');
+    parsed = JSON.parse(context.getFile(path) || '');
   } catch (e) {
     throw new Error(`Cannot parse ${path}: ${e}`);
   }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${path} does not contain a JSON object.`);
+  }
+  return parsed as T;
 }
 
 export function addDependenciesToPackageJson(
@@ -346,6 +351,8 @@ function sortObjectByKeys<T extends Record<string, any>>(obj: T): T {
 
 export const migrationsDebug = debug.extend('migrations');
 export const additionsDebug = debug.extend('additions');
+// for helpers that migrations and additions share
+export const codemodsDebug = debug.extend('codemods');
 
 export function renderTemplate(
   templatePath: string,
@@ -374,12 +381,23 @@ export function getTemplateDataFromContext(context: Context): TemplateData {
 
 /**
  * Renders every file under `folderPath` into `targetPath`, the way `generate` scaffolds a template folder:
- * `.hbs` is stripped and config file names are mapped. Files that already exist are left alone.
+ * `.hbs` is stripped and config file names are mapped. Files that already exist are left alone, and so are
+ * files `include` rejects, given each file's output path relative to `targetPath` with `/` separators.
  * Returns the paths it added.
  */
 export function addTemplateFolder(
   context: Context,
-  { folderPath, targetPath, data }: { folderPath: string; targetPath: string; data: Record<string, unknown> }
+  {
+    folderPath,
+    targetPath,
+    data,
+    include = () => true,
+  }: {
+    folderPath: string;
+    targetPath: string;
+    data: Record<string, unknown>;
+    include?: (relativeFile: string) => boolean;
+  }
 ): string[] {
   if (!existsSync(folderPath)) {
     throw new Error(
@@ -389,11 +407,15 @@ export function addTemplateFolder(
 
   const added: string[] = [];
   // relative to `cwd`, so glob characters in the install path (such as Windows backslashes) can't break the pattern
-  for (const relativeFile of glob.sync('**', { cwd: folderPath, dot: true, nodir: true })) {
+  for (const relativeFile of glob.sync('**', { cwd: folderPath, dot: true, nodir: true, posix: true })) {
     const file = join(folderPath, relativeFile);
-    const filePath = join(targetPath, dirname(relativeFile), getExportFileName(file));
+    const outputFile = posix.join(posix.dirname(relativeFile), getExportFileName(file));
+    if (!include(outputFile)) {
+      continue;
+    }
+    const filePath = join(targetPath, outputFile);
     if (context.doesFileExist(filePath)) {
-      additionsDebug(`${filePath} already exists, skipping`);
+      codemodsDebug(`${filePath} already exists, skipping`);
       continue;
     }
     context.addFile(filePath, renderHandlebarsTemplate(readFileSync(file, 'utf-8'), data));

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

@@ -0,0 +1,153 @@
+import { Context } from './context.js';
+import { bumpActionRefs } from './utils.workflows.js';
+
+const WORKFLOW = '.github/workflows/release.yml';
+const BUILD_PLUGIN = 'grafana/plugin-actions/build-plugin';
+const PACKAGE_PLUGIN = 'grafana/plugin-actions/package-plugin';
+const MINIMUMS = { [BUILD_PLUGIN]: 'build-plugin/v1.2.0', [PACKAGE_PLUGIN]: 'package-plugin/v1.3.3' };
+
+// a release workflow with one step per `uses` value
+function workflowWith(...uses: string[]): string {
+  return `name: Release\njobs:\n  release:\n    runs-on: ubuntu-latest\n    steps:\n${uses.map((u) => `      - uses: ${u}\n`).join('')}`;
+}
+
+function bump(workflow: string, minimums: Record<string, string> = MINIMUMS) {
+  const context = new Context('/virtual');
+  context.addFile(WORKFLOW, workflow);
+  const result = bumpActionRefs(context, WORKFLOW, minimums);
+  return { result, content: context.getFile(WORKFLOW) };
+}
+
+describe('bumpActionRefs', () => {
+  it.each([
+    ['a prefixed tag', 'build-plugin/v1.0.2'],
+    ['a bare tag', 'v1.0.0'],
+  ])('raises %s to the minimum', (_, ref) => {
+    const { content, result } = bump(workflowWith(`${BUILD_PLUGIN}@${ref}`));
+    expect(content).toBe(workflowWith(`${BUILD_PLUGIN}@build-plugin/v1.2.0`));
+    expect(result).toEqual({ found: [BUILD_PLUGIN], unrecognized: [] });
+  });
+
+  it.each([
+    ['a floating minor tag', 'build-plugin/v1.1', 'build-plugin/v1.2'],
+    ['a bare floating minor tag', 'v1.0', 'build-plugin/v1.2'],
+    ['a floating major tag', 'v0', 'build-plugin/v1'],
+  ])('raises %s and keeps it floating', (_, ref, raised) => {
+    const { content } = bump(workflowWith(`${BUILD_PLUGIN}@${ref}`));
+    expect(content).toBe(workflowWith(`${BUILD_PLUGIN}@${raised}`));
+  });
+
+  it.each(['build-plugin/v1.2.0', 'build-plugin/v2.0.0', 'build-plugin/v1.2', 'build-plugin/v1', 'v1', 'v2', 'main'])(
+    'leaves %s alone',
+    (ref) => {
+      const workflow = workflowWith(`${BUILD_PLUGIN}@${ref}`);
+      const { content, result } = bump(workflow);
+      expect(content).toBe(workflow);
+      expect(result).toEqual({ found: [BUILD_PLUGIN], unrecognized: [] });
+    }
+  );
+
+  it.each([
+    ['a branch', 'some-feature-branch'],
+    ['a commit SHA', 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'],
+    ["another action's tag", 'package-plugin/v1.0.0'],
+    ['a tag with a longer prefix', 'foo/build-plugin/v1.0.0'],
+  ])('leaves %s alone and reports it', (_, ref) => {
+    const workflow = workflowWith(`${BUILD_PLUGIN}@${ref}`);
+    const { content, result } = bump(workflow);
+    expect(content).toBe(workflow);
+    expect(result).toEqual({ found: [BUILD_PLUGIN], unrecognized: [BUILD_PLUGIN] });
+  });
+
+  it('bumps each use independently, to its own action minimum', () => {
+    const { content, result } = bump(
+      workflowWith(
+        `${BUILD_PLUGIN}@v1.0.0`,
+        `${BUILD_PLUGIN}@build-plugin/v2.0.0`,
+        `${PACKAGE_PLUGIN}@package-plugin/v1.3.2`
+      )
+    );
+    expect(content).toBe(
+      workflowWith(
+        `${BUILD_PLUGIN}@build-plugin/v1.2.0`,
+        `${BUILD_PLUGIN}@build-plugin/v2.0.0`,
+        `${PACKAGE_PLUGIN}@package-plugin/v1.3.3`
+      )
+    );
+    expect(result.found).toEqual([BUILD_PLUGIN, PACKAGE_PLUGIN]);
+  });
+
+  it('bumps a quoted ref and keeps the quotes and any trailing comment', () => {
+    const { content } = bump(workflowWith(`'${BUILD_PLUGIN}@v1.0.0' # pinned`));
+    expect(content).toBe(workflowWith(`'${BUILD_PLUGIN}@build-plugin/v1.2.0' # pinned`));
+  });
+
+  it('only bumps `uses` values, not incidental mentions', () => {
+    const mention = `# see ${BUILD_PLUGIN}@v1.0.0 for reference\nenv:\n  NOTE: ${BUILD_PLUGIN}@v1.0.0\n`;
+    const { content } = bump(`${mention}${workflowWith(`${BUILD_PLUGIN}@v1.0.0`)}`);
+    expect(content).toBe(`${mention}${workflowWith(`${BUILD_PLUGIN}@build-plugin/v1.2.0`)}`);
+  });
+
+  it('keeps comments, blank lines and the rest of the workflow unchanged', () => {
+    const before = [
+      '# release on tag',
+      'name: Release',
+      '',
+      'on:',
+      '  push:',
+      "    tags: ['v*']",
+      '',
+      'jobs:',
+      '  release:',
+      '    runs-on: ubuntu-latest',
+      '    steps:',
+      '      - uses: actions/checkout@v6 # keep me',
+      `      - uses: ${BUILD_PLUGIN}@v1.0.0`,
+      '        with:',
+      '          policy_token: ${{ secrets.TOKEN }}',
+      '',
+    ].join('\n');
+    const { content } = bump(before);
+    expect(content).toBe(before.replace(`${BUILD_PLUGIN}@v1.0.0`, `${BUILD_PLUGIN}@build-plugin/v1.2.0`));
+  });
+
+  it('leaves an indented commented-out block exactly as it was', () => {
+    const before = workflowWith(
+      `${BUILD_PLUGIN}@v1.0.0\n        #with:\n          # save the token in your repository secrets\n          #policy_token: \${{ secrets.TOKEN }}`
+    );
+    const { content } = bump(before);
+    expect(content).toBe(before.replace(`${BUILD_PLUGIN}@v1.0.0`, `${BUILD_PLUGIN}@build-plugin/v1.2.0`));
+  });
+
+  it('leaves a workflow it cannot parse alone', () => {
+    const workflow = `jobs: [\n  uses: ${BUILD_PLUGIN}@v1.0.0\n`;
+    const { content, result } = bump(workflow);
+    expect(content).toBe(workflow);
+    expect(result).toEqual({ found: [], unrecognized: [] });
+  });
+
+  it('does not match an action whose name only starts with the given one', () => {
+    const workflow = workflowWith(`${BUILD_PLUGIN}-extra@v1.0.0`);
+    const { content, result } = bump(workflow);
+    expect(content).toBe(workflow);
+    expect(result.found).toEqual([]);
+  });
+
+  it('reports nothing found when the workflow uses none of the actions', () => {
+    const { content, result } = bump('name: Release\n');
+    expect(content).toBe('name: Release\n');
+    expect(result).toEqual({ found: [], unrecognized: [] });
+  });
+
+  it('reports nothing found when the workflow does not exist', () => {
+    const context = new Context('/virtual');
+    expect(bumpActionRefs(context, WORKFLOW, MINIMUMS)).toEqual({ found: [], unrecognized: [] });
+    expect(context.doesFileExist(WORKFLOW)).toBe(false);
+  });
+
+  it('throws when a minimum is not a version tag', () => {
+    expect(() => bump(workflowWith(`${BUILD_PLUGIN}@v1.0.0`), { [BUILD_PLUGIN]: 'main' })).toThrow(
+      "The minimum ref 'main' for grafana/plugin-actions/build-plugin is not a version tag."
+    );
+  });
+});