@grafana/create-plugin 7.13.0 → 7.14.0

package/src/codemods/additions/scripts/docs.ts

@@ -0,0 +1,353 @@
+import { basename, join } from 'node:path';
+import * as v from 'valibot';
+import type { Context, ContextMessage } from '../../context.js';
+import { TEMPLATE_PATHS, TEMPLATES_DIR } from '../../../constants.js';
+import { output } from '../../../utils/utils.console.js';
+import {
+  additionsDebug,
+  addDependenciesToPackageJson,
+  addTemplateFolder,
+  getTemplateDataFromContext,
+  readJsonFile,
+  renderTemplate,
+} from '../../utils.js';
+import {
+  AGENT_INSTRUCTIONS_PATH,
+  appendToAgentInstructions,
+  ensureConfigAgentFiles,
+  ensureRootAgentFiles,
+} from '../../utils.agents.js';
+import { type BumpActionRefsResult, bumpActionRefs } from '../../utils.workflows.js';
+import { getPackageManagerExecCmd } from '../../../utils/utils.packageManager.js';
+
+// an allowlist, because the value becomes a path on disk and is embedded unescaped in a YAML workflow
+const DOCS_PATH_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9_-]|\/[a-zA-Z0-9_-])*$/;
+const DOCS_PATH_RULE =
+  'a relative path of letters, digits, hyphens, underscores and single "/" separators (for example "catalog-docs" or "docs/plugin")';
+const DEFAULT_DOCS_PATH = 'catalog-docs';
+
+export function isValidDocsPath(value: unknown): value is string {
+  return typeof value === 'string' && DOCS_PATH_RE.test(value);
+}
+
+export function assertValidDocsPath(value: unknown, command: string, nextStep: string): asserts value is string {
+  if (!isValidDocsPath(value)) {
+    throw new Error(
+      `src/plugin.json has docsPath set to '${value}', which create-plugin ${command} can't use.\n  Change it to ${DOCS_PATH_RULE}, then ${nextStep}.`
+    );
+  }
+}
+
+export const schema = v.object({
+  docsPath: v.optional(
+    v.pipe(
+      v.string(),
+      v.minLength(1, 'docsPath must not be empty.'),
+      v.regex(
+        DOCS_PATH_RE,
+        `docsPath must be ${DOCS_PATH_RULE}, with no leading "/", "./", trailing "/", ".." segment, backslash or quote character.`
+      )
+    )
+  ),
+});
+
+type Options = v.InferOutput<typeof schema>;
+
+// kept current by a Renovate custom manager in .github/renovate.json, which matches this exact line
+const PLUGIN_DOCS_CLI_VERSION = '^0.8.0';
+
+// each type needs a template set under `templates/docs/<type>/`
+const SUPPORTED_PLUGIN_TYPES = ['panel'] as const;
+type SupportedPluginType = (typeof SUPPORTED_PLUGIN_TYPES)[number];
+
+export default function docs(context: Context, options: Options): Context {
+  const pluginType = assertSupportedPluginType(context);
+  return setupDocsScaffolding({
+    context,
+    docsPath: options.docsPath,
+    // `templates/docs` is left out of TEMPLATE_PATHS so `generate` ignores it
+    templateDir: join(TEMPLATES_DIR, 'docs', pluginType),
+    commonTemplateDir: join(TEMPLATES_DIR, 'docs', 'common'),
+  });
+}
+
+interface PluginJson {
+  type?: string;
+  name?: string;
+  id?: string;
+  docsPath?: string;
+  [key: string]: unknown;
+}
+
+export interface DocsSetupOptions {
+  context: Context;
+  /** Falls back to the docsPath in `src/plugin.json`, then to `catalog-docs`. */
+  docsPath?: string;
+  /** Templates specific to this plugin type, under `templates/docs/<type>/`. */
+  templateDir: string;
+  /** Templates shared by every plugin type, under `templates/docs/common/`. */
+  commonTemplateDir: string;
+}
+
+export function setupDocsScaffolding(opts: DocsSetupOptions): Context {
+  const { context, templateDir, commonTemplateDir } = opts;
+
+  const pluginJson = readJsonFile<PluginJson>(context, 'src/plugin.json');
+  const existingDocsPath = pluginJson.docsPath;
+
+  if (existingDocsPath !== undefined) {
+    assertValidDocsPath(existingDocsPath, 'add docs', 'run this again');
+  }
+
+  if (opts.docsPath !== undefined && existingDocsPath !== undefined && existingDocsPath !== opts.docsPath) {
+    throw new Error(
+      `src/plugin.json already has docsPath set to '${existingDocsPath}'.\n  Re-run with the existing path:\n  create-plugin add docs --docsPath ${existingDocsPath}`
+    );
+  }
+
+  const docsPath = opts.docsPath ?? existingDocsPath ?? DEFAULT_DOCS_PATH;
+
+  // a folder plugin.json doesn't declare isn't ours. doesFileExistOnDisk also catches an empty directory
+  if (existingDocsPath === undefined && context.doesFileExistOnDisk(docsPath)) {
+    throw new Error(
+      `A directory already exists at '${docsPath}' but src/plugin.json has no docsPath.\n  Point the plugin at it by setting "docsPath": "${docsPath}" in src/plugin.json, or scaffold elsewhere:\n  create-plugin add docs --docsPath <alternative-path>`
+    );
+  }
+
+  if (!pluginJson.name) {
+    throw new Error('src/plugin.json has no "name". Add one - it is used as the title throughout the docs.');
+  }
+  if (!pluginJson.id) {
+    throw new Error('src/plugin.json has no "id". Add one - it is used in the catalog links throughout the docs.');
+  }
+  const pluginId = pluginJson.id;
+
+  // only rewritten when docsPath changes, so re-runs don't reformat plugin.json
+  if (existingDocsPath !== docsPath) {
+    context.updateFile('src/plugin.json', JSON.stringify({ ...pluginJson, docsPath }, null, 2));
+  }
+
+  const templateData = getTemplateDataFromContext(context);
+  const { packageManagerName, packageManagerVersion } = templateData;
+  const createPluginCmd = `${getPackageManagerExecCmd(packageManagerName, packageManagerVersion)}@latest`;
+  const data = {
+    ...templateData,
+    pluginId,
+    docsPath,
+    createPluginCmd,
+    lockFile: LOCK_FILES[packageManagerName],
+  };
+
+  addDependenciesToPackageJson(context, {}, { '@grafana/plugin-docs-cli': PLUGIN_DOCS_CLI_VERSION });
+
+  addDocsScripts(context);
+
+  // pages are only rendered into a folder without any, so pages the author deleted stay deleted
+  const hasPages = hasDocsPages(context, docsPath);
+  addTemplateFolder(context, {
+    folderPath: join(templateDir, 'docs'),
+    targetPath: docsPath,
+    data,
+    include: (file) => !hasPages || SCAFFOLD_META_FILES.includes(file),
+  });
+
+  // left alone when it exists, since the author may have customized it
+  const workflowPath = '.github/workflows/validate-docs.yml';
+  if (!context.doesFileExist(workflowPath)) {
+    context.addFile(workflowPath, renderTemplate(join(commonTemplateDir, 'workflows/validate-docs.yml'), false, data));
+  } else {
+    additionsDebug(`${workflowPath} already exists, skipping`);
+  }
+
+  const pluginActions = bumpActionRefs(context, RELEASE_WORKFLOW_PATH, REQUIRED_ACTION_REFS);
+
+  // a plugin that predates the root and .config/AGENTS files gets them here
+  const linkedRootFiles = ensureRootAgentFiles(context, TEMPLATE_PATHS.common);
+  ensureConfigAgentFiles(context, TEMPLATE_PATHS.common, CONFIG_AGENT_FILES, data);
+  appendDocsPointerToInstructions(context, docsPath);
+
+  // deferred so it prints after the runner's change list, and only when something changed
+  if (context.hasChanges()) {
+    context.setMessage(
+      buildNextStepsMessage({ docsPath, packageManagerName, createPluginCmd, pluginActions, linkedRootFiles })
+    );
+  }
+
+  return context;
+}
+
+function buildNextStepsMessage(opts: {
+  docsPath: string;
+  packageManagerName: string;
+  createPluginCmd: string;
+  pluginActions: BumpActionRefsResult;
+  linkedRootFiles: string[];
+}): ContextMessage {
+  const { docsPath, packageManagerName, createPluginCmd, pluginActions, linkedRootFiles } = opts;
+  const run = (script: string) => output.formatCode(`${packageManagerName} run ${script}`);
+
+  const steps: NextStep[] = [
+    {
+      title: `Read ${docsPath}/README.md`,
+      detail: 'It has the commands and a link to the plugin docs guide.',
+    },
+    {
+      title: 'Write the pages, yourself or with an AI agent',
+      detail: [
+        `Fill in or review the pages under ${docsPath}/ by hand.`,
+        'Or commit these changes, then have an agent draft them from your source code and README:',
+        output.formatCode(`${createPluginCmd} add docs-content`),
+        'Review its work either way.',
+      ],
+    },
+    {
+      title: 'Preview the pages',
+      detail: `Run ${run('docs:serve')}, which also lists every section left to fill.`,
+    },
+  ];
+
+  const warnings: NextStep[] = [];
+  if (pluginActions.found.length === 0) {
+    warnings.push({
+      title: `No build-plugin or package-plugin step found in ${RELEASE_WORKFLOW_PATH}`,
+      detail: `Make sure your release pipeline builds ${docsPath}/ into the plugin archive, or the docs won't publish.`,
+    });
+  }
+  for (const action of pluginActions.unrecognized) {
+    warnings.push({
+      title: `${RELEASE_WORKFLOW_PATH} pins ${action} to a branch or commit, so it was left as is`,
+      detail: `Docs need ${REQUIRED_ACTION_REFS[action]} or later.`,
+    });
+  }
+  for (const file of linkedRootFiles) {
+    warnings.push({
+      title: `Added a pointer to ${AGENT_INSTRUCTIONS_PATH} at the end of ${file}`,
+      detail: 'Agents that read it now also load the plugin instructions. Check it fits with the rest of the file.',
+    });
+  }
+
+  const body = steps.flatMap((step, i) => formatNextStep(step, ` ${i + 1}. `));
+  if (warnings.length > 0) {
+    body.push('', 'Needs your attention:', ...warnings.flatMap((warning) => formatNextStep(warning, ' ! ')));
+  }
+  return { level: 'log', title: 'Next steps', body };
+}
+
+interface NextStep {
+  title: string;
+  detail?: string | string[];
+}
+
+function formatNextStep({ title, detail }: NextStep, marker: string): string[] {
+  const indent = ' '.repeat(marker.length);
+  return [`${marker}${title}`, ...[detail ?? []].flat().map((line) => `${indent}${line}`)];
+}
+
+export function assertSupportedPluginType(context: Context, additionName = 'docs'): SupportedPluginType {
+  const { type } = readJsonFile<PluginJson>(context, 'src/plugin.json');
+
+  if (isSupportedPluginType(type)) {
+    return type;
+  }
+
+  const supported = SUPPORTED_PLUGIN_TYPES.join(', ');
+  if (type === 'app' || type === 'datasource') {
+    throw new Error(
+      `create-plugin add ${additionName} does not support '${type}' plugins yet. Supported so far: ${supported}.`
+    );
+  }
+  throw new Error(
+    `create-plugin add ${additionName} needs a plugin type of ${supported} in src/plugin.json, but found '${type ?? 'unset'}'.`
+  );
+}
+
+function isSupportedPluginType(type: string | undefined): type is SupportedPluginType {
+  return SUPPORTED_PLUGIN_TYPES.includes(type as SupportedPluginType);
+}
+
+// instructions.md imports e2e-testing.md, so the two are created together
+const CONFIG_AGENT_FILES = ['instructions.md', 'e2e-testing.md'];
+// the scaffold's files that aren't pages, so they're added on every run
+const SCAFFOLD_META_FILES = ['README.md', 'AGENTS.md', 'CLAUDE.md'];
+// mirrors isMetaFile in @grafana/plugin-docs-cli, so both tools agree on what counts as a page
+const DOCS_CLI_META_FILES = [
+  'README.MD',
+  'CONTRIBUTING.MD',
+  'LICENSE.MD',
+  'CODE_OF_CONDUCT.MD',
+  'SECURITY.MD',
+  'CHANGELOG.MD',
+  'AGENTS.MD',
+  'CLAUDE.MD',
+];
+
+export function hasDocsPages(context: Context, docsPath: string): boolean {
+  const addedInContext = Object.entries(context.listChanges())
+    .filter(([path, change]) => change.changeType === 'add' && path.startsWith(`${docsPath}/`))
+    .map(([path]) => path);
+  return [...listFiles(context, docsPath), ...addedInContext].some(
+    (file) =>
+      file.endsWith('.md') &&
+      !DOCS_CLI_META_FILES.includes(basename(file).toUpperCase()) &&
+      !isInSkippedFolder(file.slice(docsPath.length + 1))
+  );
+}
+
+// plugin-docs-cli skips these too, and walking node_modules would be slow
+const SKIPPED_FOLDERS = ['node_modules', 'dist'];
+
+function isInSkippedFolder(relativePath: string): boolean {
+  return relativePath.split('/').some((segment) => SKIPPED_FOLDERS.includes(segment));
+}
+
+// readDir gives nothing for a file, so this walks into every entry
+function listFiles(context: Context, folder: string): string[] {
+  return context
+    .readDir(folder)
+    .flatMap((entry) => (SKIPPED_FOLDERS.includes(basename(entry)) ? [] : [entry, ...listFiles(context, entry)]));
+}
+
+function appendDocsPointerToInstructions(context: Context, docsPath: string): void {
+  const agentsPath = `${docsPath}/AGENTS.md`;
+  // a link rather than an @-import, so the docs guidance only loads when an agent works in the docs folder
+  const section = `## Plugin docs\n\nWhenever you add, remove or change a feature in the plugin, you must update the plugin documentation under \`${docsPath}/\`. Refer to [\`${agentsPath}\`](../../${agentsPath}) for instructions.\n`;
+  appendToAgentInstructions(context, agentsPath, section);
+}
+
+// so the docs workflow also runs when the docs CLI is bumped
+const LOCK_FILES: Record<string, string> = {
+  npm: 'package-lock.json',
+  pnpm: 'pnpm-lock.yaml',
+  yarn: 'yarn.lock',
+};
+
+const RELEASE_WORKFLOW_PATH = '.github/workflows/release.yml';
+// the oldest release of each action that builds docs into the plugin archive
+const REQUIRED_ACTION_REFS: Record<string, string> = {
+  'grafana/plugin-actions/build-plugin': 'build-plugin/v1.2.0',
+  'grafana/plugin-actions/package-plugin': 'package-plugin/v1.3.3',
+};
+
+const DOCS_SCRIPTS: Record<string, string> = {
+  'docs:serve': 'plugin-docs-cli serve --port 3001 --reload',
+  'docs:validate': 'plugin-docs-cli validate',
+};
+
+function addDocsScripts(context: Context): void {
+  const packageJson = readJsonFile<Record<string, unknown>>(context, 'package.json');
+  const scripts = (packageJson['scripts'] ?? {}) as Record<string, string>;
+  const missing = Object.entries(DOCS_SCRIPTS).filter(([name]) => {
+    if (scripts[name]) {
+      additionsDebug(`${name} already exists in package.json scripts, skipping`);
+      return false;
+    }
+    return true;
+  });
+
+  if (missing.length > 0) {
+    context.updateFile(
+      'package.json',
+      JSON.stringify({ ...packageJson, scripts: { ...scripts, ...Object.fromEntries(missing) } }, null, 2)
+    );
+  }
+}

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