@grafana/create-plugin 7.12.3 → 7.14.0

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/migrations/scripts/017-jest-30.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import migrate from './017-jest-30.js';
+import { Context } from '../../context.js';
+import { output } from '../../../utils/utils.console.js';
+
+function setupContext(devDependencies: Record<string, string>) {
+  const context = new Context('/virtual');
+  context.addFile('package.json', JSON.stringify({ devDependencies }));
+  return context;
+}
+
+describe('017-jest-30', () => {
+  beforeEach(() => {
+    vi.spyOn(output, 'warning').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should bump jest, jest-environment-jsdom and @types/jest to v30', () => {
+    const result = migrate(
+      setupContext({ jest: '^29.7.0', 'jest-environment-jsdom': '^29.7.0', '@types/jest': '^29.5.0' })
+    );
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+
+    expect(packageJson.devDependencies).toEqual({
+      '@types/jest': '^30.0.0',
+      jest: '^30.5.0',
+      'jest-environment-jsdom': '^30.5.0',
+    });
+  });
+
+  it('should not add jest packages the plugin does not use', () => {
+    const result = migrate(setupContext({ jest: '^29.7.0' }));
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+
+    expect(packageJson.devDependencies).toEqual({ jest: '^30.5.0' });
+  });
+
+  it('should not downgrade newer versions', () => {
+    const result = migrate(setupContext({ jest: '^31.0.0' }));
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+
+    expect(packageJson.devDependencies).toEqual({ jest: '^31.0.0' });
+  });
+
+  it('should not modify anything when jest is not installed', () => {
+    const result = migrate(setupContext({ vitest: '^4.0.0' }));
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+
+    expect(packageJson.devDependencies).toEqual({ vitest: '^4.0.0' });
+  });
+
+  it('should warn about breaking changes when jest is bumped', () => {
+    migrate(setupContext({ jest: '^29.7.0' }));
+
+    expect(output.warning).toHaveBeenCalledWith(expect.objectContaining({ title: 'Jest was updated to v30' }));
+  });
+
+  it('should not warn when jest is already on v30', () => {
+    migrate(setupContext({ jest: '^30.5.0' }));
+
+    expect(output.warning).not.toHaveBeenCalled();
+  });
+
+  it('should be idempotent', async () => {
+    await expect(migrate).toBeIdempotent(
+      setupContext({ jest: '^29.7.0', 'jest-environment-jsdom': '^29.7.0', '@types/jest': '^29.5.0' })
+    );
+  });
+});

package/src/codemods/migrations/scripts/017-jest-30.ts

@@ -0,0 +1,39 @@
+import type { Context } from '../../context.js';
+import { addDependenciesToPackageJson, readJsonFile } from '../../utils.js';
+import { output } from '../../../utils/utils.console.js';
+
+const JEST_30_DEPENDENCIES: Record<string, string> = {
+  jest: '^30.5.0',
+  'jest-environment-jsdom': '^30.5.0',
+  '@types/jest': '^30.0.0',
+};
+
+// Jest 29 depends on micromatch, which pulls in braces. Jest 30 uses picomatch instead.
+export default function migrate(context: Context) {
+  if (!context.doesFileExist('package.json')) {
+    return context;
+  }
+
+  const packageJson = readJsonFile(context, 'package.json');
+  const installed = { ...packageJson.dependencies, ...packageJson.devDependencies };
+
+  // Only bump the jest packages the plugin already has.
+  const devDependencies = Object.fromEntries(
+    Object.entries(JEST_30_DEPENDENCIES).filter(([name]) => Boolean(installed[name]))
+  );
+
+  const before = context.getFile('package.json');
+  addDependenciesToPackageJson(context, {}, devDependencies);
+
+  if (context.getFile('package.json') !== before) {
+    output.warning({
+      title: 'Jest was updated to v30',
+      body: [
+        'Jest 30 is a major release, so existing tests may need small fixes (jsdom 26, removed matcher aliases like `toBeCalled`).',
+        'See https://jestjs.io/docs/upgrading-to-jest30 if `npm run test:ci` fails after the update.',
+      ],
+    });
+  }
+
+  return context;
+}

package/src/codemods/migrations/scripts/018-replace-eslint-webpack-plugin.test.ts

@@ -0,0 +1,174 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import migrate from './018-replace-eslint-webpack-plugin.js';
+import { Context } from '../../context.js';
+import { output } from '../../../utils/utils.console.js';
+
+const WEBPACK_CONFIG_PATH = '.config/webpack/webpack.config.ts';
+const RSPACK_CONFIG_PATH = '.config/rspack/rspack.config.ts';
+
+const WEBPACK_CONFIG = `import ESLintPlugin from 'eslint-webpack-plugin';
+import ForkTsCheckerWebpackPlugin from 'fork-ts-checker-webpack-plugin';
+import { type Configuration } from 'webpack';
+import LiveReloadPlugin from 'webpack-livereload-plugin';
+
+const config = async (env: Record<string, unknown>): Promise<Configuration> => ({
+  plugins: [
+    ...(env.development ? [
+      new LiveReloadPlugin(),
+      new ForkTsCheckerWebpackPlugin({
+        async: Boolean(env.development),
+      }),
+      new ESLintPlugin({
+        extensions: ['.ts', '.tsx'],
+        lintDirtyModulesOnly: Boolean(env.development), // don't lint on start, only lint changed files
+        failOnError: Boolean(env.production),
+      }),
+    ] : []),
+  ],
+});
+
+export default config;
+`;
+
+const RSPACK_CONFIG = `import rspack, { type Configuration } from '@rspack/core';
+import ESLintPlugin from 'eslint-webpack-plugin';
+import { TsCheckerRspackPlugin } from 'ts-checker-rspack-plugin';
+
+const config = async (env: Record<string, unknown>): Promise<Configuration> => ({
+  plugins: [
+    ...(env.development
+      ? [
+          new TsCheckerRspackPlugin({
+            async: Boolean(env.development),
+          }),
+          new ESLintPlugin({
+            extensions: ['.ts', '.tsx'],
+            lintDirtyModulesOnly: Boolean(env.development), // don't lint on start, only lint changed files
+          }),
+        ]
+      : []),
+  ],
+});
+
+export default config;
+`;
+
+function setupContext(files: Record<string, string> = { [WEBPACK_CONFIG_PATH]: WEBPACK_CONFIG }) {
+  const context = new Context('/virtual');
+  context.addFile(
+    'package.json',
+    JSON.stringify({ devDependencies: { 'eslint-webpack-plugin': '^5.0.0', webpack: '^5.101.0' } })
+  );
+  for (const [path, content] of Object.entries(files)) {
+    context.addFile(path, content);
+  }
+  return context;
+}
+
+describe('018-replace-eslint-webpack-plugin', () => {
+  beforeEach(() => {
+    vi.spyOn(output, 'warning').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should replace the plugin in the webpack config', () => {
+    const result = migrate(setupContext());
+    const expected = WEBPACK_CONFIG.replace(
+      "import ESLintPlugin from 'eslint-webpack-plugin';",
+      "import DiagnosticsPlugin from 'diagnostics-webpack-plugin';"
+    ).replace(
+      /new ESLintPlugin\(\{\n(?:.*\n){3} {6}\}\)/,
+      `new DiagnosticsPlugin({
+        lintOnStart: false, // don't lint on start, only lint changed files
+        checks: [{ use: 'eslint', extensions: ['ts', 'tsx'] }],
+      })`
+    );
+
+    expect(result.getFile(WEBPACK_CONFIG_PATH)).toBe(expected);
+  });
+
+  it('should swap the dependency and bump webpack in package.json', () => {
+    const result = migrate(setupContext());
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+
+    expect(packageJson.devDependencies).toEqual({ 'diagnostics-webpack-plugin': '^1.0.1', webpack: '^5.106.0' });
+  });
+
+  it('should replace the plugin when it shares a line with other plugins', () => {
+    const result = migrate(
+      setupContext({
+        [WEBPACK_CONFIG_PATH]: `import ESLintPlugin from 'eslint-webpack-plugin';\nimport LiveReloadPlugin from 'webpack-livereload-plugin';\n\nexport default { plugins: [new LiveReloadPlugin(), new ESLintPlugin({ extensions: ['.ts', '.tsx'], lintDirtyModulesOnly: Boolean(env.development) })] };\n`,
+      })
+    );
+    const config = result.getFile(WEBPACK_CONFIG_PATH) || '';
+
+    expect(config).not.toContain('ESLintPlugin');
+    expect(config).toContain('[new LiveReloadPlugin(), new DiagnosticsPlugin({');
+  });
+
+  it('should replace the plugin when it has the older scaffolded options', () => {
+    const result = migrate(setupContext({ [WEBPACK_CONFIG_PATH]: WEBPACK_CONFIG.replace(/\n.*failOnError.*/, '') }));
+
+    expect(result.getFile(WEBPACK_CONFIG_PATH)).not.toContain('ESLintPlugin');
+    expect(output.warning).not.toHaveBeenCalled();
+  });
+
+  it('should skip the replacement and warn when the options were customised', () => {
+    const customConfig = WEBPACK_CONFIG.replace("extensions: ['.ts', '.tsx'],", "extensions: ['.ts', '.tsx', '.js'],");
+    const result = migrate(setupContext({ [WEBPACK_CONFIG_PATH]: customConfig }));
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+
+    expect(result.getFile(WEBPACK_CONFIG_PATH)).toBe(customConfig);
+    expect(packageJson.devDependencies).toEqual({ 'eslint-webpack-plugin': '^5.0.0', webpack: '^5.101.0' });
+    expect(output.warning).toHaveBeenCalledWith(
+      expect.objectContaining({ title: expect.stringContaining('Skipping the eslint-webpack-plugin replacement') })
+    );
+  });
+
+  it('should skip the replacement when the plugin is called without options', () => {
+    const config = `import ESLintPlugin from 'eslint-webpack-plugin';\n\nexport default { plugins: [new ESLintPlugin()] };\n`;
+    const result = migrate(setupContext({ [WEBPACK_CONFIG_PATH]: config }));
+
+    expect(result.getFile(WEBPACK_CONFIG_PATH)).toBe(config);
+  });
+
+  it('should leave the rspack config alone', () => {
+    const result = migrate(setupContext({ [RSPACK_CONFIG_PATH]: RSPACK_CONFIG }));
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+
+    expect(result.getFile(RSPACK_CONFIG_PATH)).toBe(RSPACK_CONFIG);
+    expect(packageJson.devDependencies).toEqual({ 'eslint-webpack-plugin': '^5.0.0', webpack: '^5.101.0' });
+  });
+
+  it('should keep the old dependency when an extended config still imports it', () => {
+    const result = migrate(
+      setupContext({
+        [WEBPACK_CONFIG_PATH]: WEBPACK_CONFIG,
+        'webpack.config.ts': `import ESLintPlugin from 'eslint-webpack-plugin';\n`,
+      })
+    );
+    const packageJson = JSON.parse(result.getFile('package.json') || '{}');
+
+    expect(result.getFile(WEBPACK_CONFIG_PATH)).not.toContain('ESLintPlugin');
+    expect(packageJson.devDependencies['eslint-webpack-plugin']).toBe('^5.0.0');
+    expect(packageJson.devDependencies['diagnostics-webpack-plugin']).toBe('^1.0.1');
+  });
+
+  it('should not modify configs that do not use the plugin', () => {
+    const context = new Context('/virtual');
+    context.addFile(WEBPACK_CONFIG_PATH, `export default {};\n`);
+
+    const result = migrate(context);
+
+    expect(result.getFile(WEBPACK_CONFIG_PATH)).toBe(`export default {};\n`);
+  });
+
+  it('should be idempotent', async () => {
+    await expect(migrate).toBeIdempotent(
+      setupContext({ [WEBPACK_CONFIG_PATH]: WEBPACK_CONFIG, [RSPACK_CONFIG_PATH]: RSPACK_CONFIG })
+    );
+  });
+});

package/src/codemods/migrations/scripts/018-replace-eslint-webpack-plugin.ts

@@ -0,0 +1,141 @@
+import { join } from 'node:path';
+import * as recast from 'recast';
+import type { Context } from '../../context.js';
+import { addDependenciesToPackageJson, migrationsDebug, removeDependenciesFromPackageJson } from '../../utils.js';
+import { parseAsTypescript } from '../../utils.ast.js';
+import { output } from '../../../utils/utils.console.js';
+
+const OLD_PACKAGE_NAME = 'eslint-webpack-plugin';
+const NEW_PACKAGE_NAME = 'diagnostics-webpack-plugin';
+
+const WEBPACK_CONFIG_PATH = join('.config', 'webpack', 'webpack.config.ts');
+
+// The rspack config keeps eslint-webpack-plugin, diagnostics-webpack-plugin relies on webpack-only compiler hooks.
+const CONFIG_PATHS = [
+  WEBPACK_CONFIG_PATH,
+  join('.config', 'rspack', 'rspack.config.ts'),
+  'webpack.config.ts',
+  'rspack.config.ts',
+];
+
+// Options the template has scaffolded over time, with whitespace, comments and trailing commas stripped.
+const SCAFFOLDED_OPTIONS = [
+  "{extensions:['.ts','.tsx'],lintDirtyModulesOnly:Boolean(env.development)}",
+  "{extensions:['.ts','.tsx'],lintDirtyModulesOnly:Boolean(env.development),failOnError:Boolean(env.production)}",
+];
+
+const NEW_IMPORT = `import DiagnosticsPlugin from '${NEW_PACKAGE_NAME}';`;
+const NEW_PLUGIN = `new DiagnosticsPlugin({
+  lintOnStart: false, // don't lint on start, only lint changed files
+  checks: [{ use: 'eslint', extensions: ['ts', 'tsx'] }],
+})`;
+
+// eslint-webpack-plugin depends on micromatch, which pulls in braces. diagnostics-webpack-plugin uses picomatch
+// instead and needs webpack 5.106 or newer.
+export default function migrate(context: Context) {
+  if (!replaceESLintPlugin(context)) {
+    return context;
+  }
+
+  if (context.doesFileExist('package.json')) {
+    addDependenciesToPackageJson(context, {}, { [NEW_PACKAGE_NAME]: '^1.0.1', webpack: '^5.106.0' });
+
+    const isStillUsed = CONFIG_PATHS.some(
+      (path) => context.doesFileExist(path) && (context.getFile(path) ?? '').includes(OLD_PACKAGE_NAME)
+    );
+    if (!isStillUsed) {
+      removeDependenciesFromPackageJson(context, [OLD_PACKAGE_NAME], [OLD_PACKAGE_NAME]);
+    }
+  }
+
+  return context;
+}
+
+function replaceESLintPlugin(context: Context): boolean {
+  if (!context.doesFileExist(WEBPACK_CONFIG_PATH)) {
+    return false;
+  }
+
+  const source = context.getFile(WEBPACK_CONFIG_PATH);
+  if (!source || !source.includes(OLD_PACKAGE_NAME)) {
+    return false;
+  }
+
+  const parsed = parseAsTypescript(source);
+  if (!parsed.success) {
+    migrationsDebug(`Failed to parse ${WEBPACK_CONFIG_PATH}. Error: ${parsed.error.message}`);
+    return false;
+  }
+
+  // Splice the source text rather than reprinting the AST, which would reformat the surrounding plugins array.
+  const lineOffsets = [0];
+  for (const line of source.split('\n')) {
+    lineOffsets.push(lineOffsets[lineOffsets.length - 1] + line.length + 1);
+  }
+  const toOffset = ({ line, column }: { line: number; column: number }) => lineOffsets[line - 1] + column;
+
+  const localNames = new Set<string>();
+  const replacements: Array<{ node: recast.types.namedTypes.Node; text: string }> = [];
+  let hasCustomOptions = false;
+
+  recast.visit(parsed.ast, {
+    visitImportDeclaration(path) {
+      if (path.node.source.value === OLD_PACKAGE_NAME) {
+        for (const specifier of path.node.specifiers ?? []) {
+          if (specifier.local?.name) {
+            localNames.add(String(specifier.local.name));
+          }
+        }
+        replacements.push({ node: path.node, text: NEW_IMPORT });
+        return false;
+      }
+      return this.traverse(path);
+    },
+  });
+
+  recast.visit(parsed.ast, {
+    visitNewExpression(path) {
+      const { node } = path;
+      if (node.callee.type === 'Identifier' && localNames.has(node.callee.name)) {
+        const [options] = node.arguments;
+        const optionsText = options?.loc ? source.slice(toOffset(options.loc.start), toOffset(options.loc.end)) : '';
+        const normalized = optionsText
+          .replace(/\/\/.*$/gm, '')
+          .replace(/\s+/g, '')
+          .replace(/,}/g, '}');
+        if (node.arguments.length !== 1 || !SCAFFOLDED_OPTIONS.includes(normalized)) {
+          hasCustomOptions = true;
+        }
+        replacements.push({ node, text: NEW_PLUGIN });
+        return false;
+      }
+      return this.traverse(path);
+    },
+  });
+
+  if (hasCustomOptions) {
+    output.warning({
+      title: `Skipping the ${OLD_PACKAGE_NAME} replacement in ${WEBPACK_CONFIG_PATH}`,
+      body: [
+        `The ${OLD_PACKAGE_NAME} options differ from the scaffolded defaults, so the config was left as is.`,
+        `${OLD_PACKAGE_NAME} depends on micromatch, which pulls in braces. To drop it, switch to ${NEW_PACKAGE_NAME} by hand.`,
+      ],
+    });
+    return false;
+  }
+
+  let updated = source;
+  const sorted = replacements
+    .filter(({ node }) => node.loc)
+    .sort(
+      (a, b) => b.node.loc!.start.line - a.node.loc!.start.line || b.node.loc!.start.column - a.node.loc!.start.column
+    );
+  for (const { node, text } of sorted) {
+    const { start, end } = node.loc!;
+    const indent = ' '.repeat(start.column);
+    updated = updated.slice(0, toOffset(start)) + text.replaceAll('\n', `\n${indent}`) + updated.slice(toOffset(end));
+  }
+
+  context.updateFile(WEBPACK_CONFIG_PATH, updated);
+  return true;
+}

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);
+}