@grafana/create-plugin 7.13.0 → 7.15.0

package/dist/codemods/additions/scripts/docs.js

@@ -0,0 +1,468 @@
+import { join, basename } from 'node:path';
+import * as v from 'valibot';
+import { TEMPLATES_DIR, TEMPLATE_PATHS } from '../../../constants.js';
+import { output } from '../../../utils/utils.console.js';
+import { readJsonFile, getTemplateDataFromContext, addDependenciesToPackageJson, addTemplateFolder, renderTemplate, additionsDebug } from '../../utils.js';
+import { ensureRootAgentFiles, ensureConfigAgentFiles, appendToAgentInstructions, AGENT_INSTRUCTIONS_PATH } from '../../utils.agents.js';
+import { bumpActionRefs } from '../../utils.workflows.js';
+import { getPackageManagerExecCmd } from '../../../utils/utils.packageManager.js';
+import * as recast from 'recast';
+import * as babelTsParser from 'recast/parsers/babel-ts.js';
+
+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";
+function isValidDocsPath(value) {
+  return typeof value === "string" && DOCS_PATH_RE.test(value);
+}
+function assertValidDocsPath(value, command, nextStep) {
+  if (!isValidDocsPath(value)) {
+    throw new Error(
+      `src/plugin.json has docsPath set to '${value}', which create-plugin ${command} can't use.
+  Change it to ${DOCS_PATH_RULE}, then ${nextStep}.`
+    );
+  }
+}
+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.`
+      )
+    )
+  )
+});
+const PLUGIN_DOCS_CLI_VERSION = "^0.8.0";
+const SUPPORTED_PLUGIN_TYPES = ["panel", "datasource", "app"];
+function docs(context, options) {
+  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"),
+    featurePages: FEATURE_PAGES_BY_TYPE[pluginType],
+    pageStubs: pluginType === "app" ? getAppFeaturePageStubs : void 0
+  });
+}
+function setupDocsScaffolding(opts) {
+  const { context, templateDir, commonTemplateDir } = opts;
+  const pluginJson = readJsonFile(context, "src/plugin.json");
+  const existingDocsPath = pluginJson.docsPath;
+  if (existingDocsPath !== void 0) {
+    assertValidDocsPath(existingDocsPath, "add docs", "run this again");
+  }
+  if (opts.docsPath !== void 0 && existingDocsPath !== void 0 && existingDocsPath !== opts.docsPath) {
+    throw new Error(
+      `src/plugin.json already has docsPath set to '${existingDocsPath}'.
+  Re-run with the existing path:
+  create-plugin add docs --docsPath ${existingDocsPath}`
+    );
+  }
+  const docsPath = opts.docsPath ?? existingDocsPath ?? DEFAULT_DOCS_PATH;
+  if (existingDocsPath === void 0 && context.doesFileExistOnDisk(docsPath)) {
+    throw new Error(
+      `A directory already exists at '${docsPath}' but src/plugin.json has no docsPath.
+  Point the plugin at it by setting "docsPath": "${docsPath}" in src/plugin.json, or scaffold elsewhere:
+  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;
+  if (existingDocsPath !== docsPath) {
+    context.updateFile("src/plugin.json", JSON.stringify({ ...pluginJson, docsPath }, null, 2));
+  }
+  const templateData = getTemplateDataFromContext(context);
+  const featurePages = (opts.featurePages ?? []).map(({ page, templateFlag, hasFeature }) => ({
+    page,
+    templateFlag,
+    isEnabled: hasFeature(pluginJson, context)
+  }));
+  const featureFlags = Object.fromEntries(featurePages.map(({ templateFlag, isEnabled }) => [templateFlag, isEnabled]));
+  const pageStubs = opts.pageStubs?.(pluginJson, featureFlags) ?? { data: {}, stubs: [], skipped: [] };
+  const { packageManagerName, packageManagerVersion } = templateData;
+  const createPluginCmd = `${getPackageManagerExecCmd(packageManagerName, packageManagerVersion)}@latest`;
+  const data = {
+    ...templateData,
+    pluginId,
+    docsPath,
+    createPluginCmd,
+    lockFile: LOCK_FILES[packageManagerName],
+    ...featureFlags,
+    ...pageStubs.data
+  };
+  addDependenciesToPackageJson(context, {}, { "@grafana/plugin-docs-cli": PLUGIN_DOCS_CLI_VERSION });
+  addDocsScripts(context);
+  const hasPages = hasDocsPages(context, docsPath);
+  const disabledPageFiles = featurePages.filter(({ isEnabled }) => !isEnabled).map(({ page }) => `${page}.md`);
+  addTemplateFolder(context, {
+    folderPath: join(templateDir, "docs"),
+    targetPath: docsPath,
+    data,
+    include: (file) => SCAFFOLD_META_FILES.includes(file) || !hasPages && !disabledPageFiles.includes(file)
+  });
+  const report = {
+    missingPageStubs: scaffoldPageStubs({ context, docsPath, stubs: pageStubs.stubs, data, hasPages }),
+    // a feature turned on after the first scaffold gets no page, so point the author at it instead
+    missingFeaturePages: hasPages ? featurePages.filter(({ page, isEnabled }) => isEnabled && !pageExists(context, docsPath, [page])).map(({ page }) => `${page}.md`) : [],
+    // a re-run has no pages to compare against, so it only reports what the first scaffold left out
+    skippedPages: hasPages ? [] : pageStubs.skipped
+  };
+  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);
+  const linkedRootFiles = ensureRootAgentFiles(context, TEMPLATE_PATHS.common);
+  ensureConfigAgentFiles(context, TEMPLATE_PATHS.common, CONFIG_AGENT_FILES, data);
+  appendDocsPointerToInstructions(context, docsPath);
+  if (context.hasChanges() || report.missingFeaturePages.length > 0 || report.missingPageStubs.length > 0) {
+    context.setMessage(
+      buildNextStepsMessage({ docsPath, packageManagerName, createPluginCmd, pluginActions, linkedRootFiles, report })
+    );
+  }
+  return context;
+}
+function pageExists(context, docsPath, pageNames) {
+  return pageNames.some(
+    (name) => context.doesFileExist(`${docsPath}/${name}.md`) || context.doesFileExist(`${docsPath}/${name}`)
+  );
+}
+function scaffoldPageStubs(opts) {
+  const { context, docsPath, stubs, data, hasPages } = opts;
+  const missingPages = [];
+  const missingIndexes = [];
+  for (const stub of stubs) {
+    const filePath = `${docsPath}/${stub.file}`;
+    if (hasPages) {
+      if (stub.slug !== void 0) {
+        if (!pageExists(context, docsPath, [stub.slug, `features/${stub.slug}`])) {
+          missingPages.push(filePath);
+        }
+      } else if (!context.doesFileExist(filePath)) {
+        missingIndexes.push(filePath);
+      }
+    } else if (context.doesFileExist(filePath)) {
+      additionsDebug(`${filePath} already exists, skipping`);
+    } else {
+      context.addFile(filePath, renderTemplate(stub.templatePath, false, { ...data, ...stub.data }));
+    }
+  }
+  const missing = [...missingPages, ...missingIndexes];
+  return missing;
+}
+function buildNextStepsMessage(opts) {
+  const { docsPath, packageManagerName, createPluginCmd, pluginActions, linkedRootFiles } = opts;
+  const { missingFeaturePages, missingPageStubs, skippedPages } = opts.report;
+  const run = (script) => output.formatCode(`${packageManagerName} run ${script}`);
+  const steps = [
+    {
+      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 = [];
+  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 page of missingFeaturePages) {
+    warnings.push({
+      title: `src/plugin.json declares the feature ${docsPath}/${page} documents, but the page doesn't exist`,
+      detail: `If it needs docs, add the page as described under Optional pages in ${docsPath}/AGENTS.md. If you deleted it on purpose, ignore this.`
+    });
+  }
+  if (missingPageStubs.length > 0) {
+    warnings.push({
+      title: `src/plugin.json has pages with no docs page, such as ${missingPageStubs[0]}`,
+      detail: `If they need docs, add them as described under Optional pages in ${docsPath}/AGENTS.md. If you deleted them on purpose, ignore this.`
+    });
+  }
+  if (skippedPages.length > 0) {
+    warnings.push({
+      title: `Left out of the docs: ${skippedPages.join(", ")}`,
+      detail: `If they need docs, add them as described under Optional pages in ${docsPath}/AGENTS.md.`
+    });
+  }
+  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 };
+}
+function formatNextStep({ title, detail }, marker) {
+  const indent = " ".repeat(marker.length);
+  return [`${marker}${title}`, ...[detail ?? []].flat().map((line) => `${indent}${line}`)];
+}
+function assertSupportedPluginType(context, additionName = "docs") {
+  const { type } = readJsonFile(context, "src/plugin.json");
+  if (isSupportedPluginType(type)) {
+    return type;
+  }
+  const supported = SUPPORTED_PLUGIN_TYPES.join(", ");
+  throw new Error(
+    `create-plugin add ${additionName} needs a plugin type of ${supported} in src/plugin.json, but found '${type ?? "unset"}'.`
+  );
+}
+function isSupportedPluginType(type) {
+  return SUPPORTED_PLUGIN_TYPES.includes(type);
+}
+const CONFIG_AGENT_FILES = ["instructions.md", "e2e-testing.md"];
+const SCAFFOLD_META_FILES = ["README.md", "AGENTS.md", "CLAUDE.md"];
+const DASHBOARDS_PAGE = {
+  page: "dashboards",
+  templateFlag: "hasDashboards",
+  hasFeature: (p) => getIncludes(p).some((i) => i.type === "dashboard")
+};
+const FEATURE_PAGES_BY_TYPE = {
+  panel: [],
+  datasource: [
+    { page: "annotations", templateFlag: "hasAnnotations", hasFeature: (p) => p.annotations === true },
+    { page: "alerting", templateFlag: "hasAlerting", hasFeature: (p) => p.alerting === true },
+    DASHBOARDS_PAGE
+  ],
+  app: [
+    { page: "configure", templateFlag: "hasConfigPage", hasFeature: hasAppConfigPage },
+    DASHBOARDS_PAGE,
+    {
+      page: "permissions",
+      templateFlag: "hasPermissions",
+      hasFeature: (p) => p.roles !== void 0 || p.iam !== void 0 || getIncludes(p).some((i) => i.role !== void 0 && i.role !== "Viewer" || i.action !== void 0)
+    }
+  ]
+};
+function getIncludes(pluginJson) {
+  return Array.isArray(pluginJson.includes) ? pluginJson.includes.filter((i) => typeof i === "object" && i !== null) : [];
+}
+function isAppPath(path, pluginId, prefix) {
+  return [pluginId, "%PLUGIN_ID%"].some(
+    (id) => id && (path === `${prefix}${id}` || path?.startsWith(`${prefix}${id}/`))
+  );
+}
+const APP_MODULE_FILES = ["src/module.ts", "src/module.tsx", "src/module.js", "src/module.jsx"];
+function hasAppConfigPage(pluginJson, context) {
+  return APP_MODULE_FILES.some((file) => callsAddConfigPage(context.getFile(file))) || getIncludes(pluginJson).some((i) => i.type === "page" && isAppPath(i.path, pluginJson.id, "/plugins/"));
+}
+function callsAddConfigPage(source) {
+  if (!source) {
+    return false;
+  }
+  let ast;
+  try {
+    ast = recast.parse(source, { parser: babelTsParser });
+  } catch (error) {
+    additionsDebug(`Failed to parse the app module, so it can't tell whether it has a config page: ${error}`);
+    return false;
+  }
+  let isFound = false;
+  recast.visit(ast, {
+    visitCallExpression(path) {
+      const { callee } = path.node;
+      if (callee.type === "MemberExpression" && callee.property.type === "Identifier" && callee.property.name === "addConfigPage") {
+        isFound = true;
+        return false;
+      }
+      this.traverse(path);
+      return void 0;
+    }
+  });
+  return isFound;
+}
+const TEMPLATE_DEFAULT_PAGES = {
+  "Page One": "/one",
+  "Page Two": "/two",
+  "Page Three": "/three",
+  "Page Four": "/four"
+};
+const CONFIG_PAGE_SLUGS = ["configuration", "configure"];
+function getAppFeaturePages(pluginJson, hasConfigPage) {
+  const pages = [];
+  let configPage;
+  const skipped = [];
+  const appPages = getIncludes(pluginJson).filter((i) => i.type === "page" && typeof i.name === "string" && isAppPath(i.path, pluginJson.id, "/a/")).sort((a, b) => Number(b.defaultNav === true) - Number(a.defaultNav === true));
+  const takenSlugs = new Set(getReservedPageSlugs());
+  for (const include of appPages) {
+    const name = include.name;
+    const path = include.path.replaceAll("%PLUGIN_ID%", pluginJson.id ?? "");
+    const defaultPath = TEMPLATE_DEFAULT_PAGES[name];
+    if (defaultPath !== void 0 && path.endsWith(defaultPath)) {
+      additionsDebug(`${name} is an example page from the create-plugin app template, skipping`);
+      skipped.push(`${name} (${include.path}, an example page from the create-plugin app template)`);
+      continue;
+    }
+    const slug = slugify(name);
+    if (!slug) {
+      additionsDebug(`${name} has no letters or digits for a file name, skipping`);
+      skipped.push(`${name} (${include.path}, its name has no letters or digits for a file name)`);
+      continue;
+    }
+    const role = typeof include.role === "string" && include.role !== "Viewer" ? include.role : void 0;
+    if (!hasConfigPage && !configPage && CONFIG_PAGE_SLUGS.includes(slug)) {
+      configPage = { name, slug: "configure", path, role };
+      continue;
+    }
+    if (takenSlugs.has(slug)) {
+      additionsDebug(`${name} would be written to ${slug}.md, which another page uses, skipping`);
+      skipped.push(`${name} (${include.path}, its file name is used by another page)`);
+      continue;
+    }
+    takenSlugs.add(slug);
+    pages.push({ name, slug, path, role });
+  }
+  return { pages, configPage, skipped };
+}
+function slugify(name) {
+  return name.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+const MAX_FLAT_PAGES = 3;
+const FIRST_PAGE_POSITION = 3;
+const CONFIG_PAGE_POSITION = 2;
+const FIXED_PAGE_SLUGS = ["index", "configure", "dashboards", "permissions", "troubleshooting"];
+function getReservedPageSlugs() {
+  return [
+    ...FIXED_PAGE_SLUGS,
+    ...DOCS_CLI_META_FILES.map((file) => file.slice(0, -".MD".length).toLowerCase().replaceAll("_", "-"))
+  ];
+}
+function getAppFeaturePageStubs(pluginJson, featureFlags) {
+  const { pages, configPage, skipped } = getAppFeaturePages(pluginJson, featureFlags.hasConfigPage === true);
+  const templateDir = join(TEMPLATES_DIR, "docs", "app");
+  const pageTemplate = join(templateDir, "feature-page.md");
+  const stubs = [];
+  if (configPage) {
+    stubs.push({
+      templatePath: pageTemplate,
+      file: "configure.md",
+      slug: "configure",
+      data: { page: { ...configPage, position: CONFIG_PAGE_POSITION } }
+    });
+  }
+  const isInFolder = pages.length > MAX_FLAT_PAGES;
+  const folder = isInFolder ? "features/" : "";
+  if (isInFolder) {
+    stubs.push({
+      templatePath: join(templateDir, "features-index.md"),
+      file: "features/index.md",
+      data: { position: FIRST_PAGE_POSITION }
+    });
+  }
+  const firstPosition = isInFolder ? FIRST_PAGE_POSITION + 1 : FIRST_PAGE_POSITION;
+  pages.forEach((page, i) => {
+    stubs.push({
+      templatePath: pageTemplate,
+      file: `${folder}${page.slug}.md`,
+      slug: page.slug,
+      data: { page: { ...page, position: firstPosition + i } }
+    });
+  });
+  return {
+    data: {
+      ...configPage ? { hasConfigPage: true } : {},
+      ...pages.length > 0 ? { defaultFeaturePage: { ...pages[0], file: `${folder}${pages[0].slug}` } } : {}
+    },
+    stubs,
+    skipped
+  };
+}
+const DOCS_CLI_META_FILES = [
+  "README.MD",
+  "CONTRIBUTING.MD",
+  "LICENSE.MD",
+  "CODE_OF_CONDUCT.MD",
+  "SECURITY.MD",
+  "CHANGELOG.MD",
+  "AGENTS.MD",
+  "CLAUDE.MD"
+];
+function hasDocsPages(context, docsPath) {
+  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))
+  );
+}
+const SKIPPED_FOLDERS = ["node_modules", "dist"];
+function isInSkippedFolder(relativePath) {
+  return relativePath.split("/").some((segment) => SKIPPED_FOLDERS.includes(segment));
+}
+function listFiles(context, folder) {
+  return context.readDir(folder).flatMap((entry) => SKIPPED_FOLDERS.includes(basename(entry)) ? [] : [entry, ...listFiles(context, entry)]);
+}
+function appendDocsPointerToInstructions(context, docsPath) {
+  const agentsPath = `${docsPath}/AGENTS.md`;
+  const section = `## Plugin docs
+
+Whenever you add, remove or change a feature in the plugin, you must update the plugin documentation under \`${docsPath}/\`. Refer to [\`${agentsPath}\`](../../${agentsPath}) for instructions.
+`;
+  appendToAgentInstructions(context, agentsPath, section);
+}
+const LOCK_FILES = {
+  npm: "package-lock.json",
+  pnpm: "pnpm-lock.yaml",
+  yarn: "yarn.lock"
+};
+const RELEASE_WORKFLOW_PATH = ".github/workflows/release.yml";
+const REQUIRED_ACTION_REFS = {
+  "grafana/plugin-actions/build-plugin": "build-plugin/v1.2.0",
+  "grafana/plugin-actions/package-plugin": "package-plugin/v1.3.3"
+};
+const DOCS_SCRIPTS = {
+  "docs:serve": "plugin-docs-cli serve --port 3001 --reload",
+  "docs:validate": "plugin-docs-cli validate"
+};
+function addDocsScripts(context) {
+  const packageJson = readJsonFile(context, "package.json");
+  const scripts = packageJson["scripts"] ?? {};
+  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)
+    );
+  }
+}
+
+export { assertSupportedPluginType, assertValidDocsPath, docs as default, hasDocsPages, isValidDocsPath, schema, setupDocsScaffolding };

package/dist/codemods/additions/scripts/experimental-app-sdk.js

@@ -4,9 +4,14 @@ import { parseDocument, YAMLMap, Scalar, stringify } from 'yaml';
 import { getBackendCmd } from '../../../commands/generate/print-success-message.js';
 import { output } from '../../../utils/utils.console.js';
 import { getTemplateDataFromContext, additionsDebug, renderTemplate } from '../../utils.js';
+import { AGENT_INSTRUCTIONS_PATH, appendToAgentInstructions } from '../../utils.agents.js';
 import { addRequireToGoMod } from '../../utils.goMod.js';
 
-const APP_SDK_FEATURE_TOGGLES = ["appplugins.loadAppManifest", "appplugins.registerAPIServer"];
+const APP_SDK_FEATURE_TOGGLES = [
+  "appplugins.loadAppManifest",
+  "appplugins.registerAPIServer",
+  "grafana.useRouterMiddleware"
+];
 const TEMPLATE_FILES = [
   [".config/app-sdk/generate-kinds.mjs", true],
   [".config/app-sdk/README.md", false],
@@ -78,23 +83,19 @@ function renderAppSdkTemplate(file, data, includeWarning = false) {
   return renderTemplate(templatePath(file), includeWarning, data);
 }
 function referenceAgentInstructions(context, data) {
-  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;
   }
   if (!context.doesFileExist(APP_SDK_MD)) {
     context.addFile(APP_SDK_MD, renderAppSdkTemplate(APP_SDK_MD, data));
   }
-  if (instructions.includes(APP_SDK_MD)) {
-    return;
-  }
-  context.updateFile(
-    path,
-    `${instructions.trimEnd()}
-- 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.**
-`
+  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"
   );
 }
 function addGenerateScript(context) {
@@ -164,7 +165,7 @@ function wireGoBackend(context, data) {
   wireMainGo(context);
   addGoModDependency(context);
 }
-const GRAFANA_APP_SDK_VERSION = "v0.60.3";
+const GRAFANA_APP_SDK_VERSION = "v0.60.16";
 function addGoModDependency(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);

package/dist/codemods/utils.agents.js

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { addTemplateFolder, codemodsDebug } from './utils.js';
+
+const AGENT_INSTRUCTIONS_PATH = ".config/AGENTS/instructions.md";
+const ROOT_AGENT_FILES = ["AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+const INSTRUCTIONS_POINTER = `## Project knowledge
+This repository contains a **Grafana plugin**. You must Read @./${AGENT_INSTRUCTIONS_PATH} before doing changes.
+`;
+const IMPORTS_INSTRUCTIONS = /@(\.\/)?\.config\/AGENTS\/instructions\.md/;
+const IMPORTS_AGENTS_MD = /(^|\s)@(\.\/)?AGENTS\.md\b/m;
+function ensureRootAgentFiles(context, templateDir) {
+  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"));
+    }
+  }
+  const reachesInstructions = (file) => {
+    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 = [];
+  for (const file of existing) {
+    if (reachesInstructions(file)) {
+      continue;
+    }
+    const content = context.getFile(file) ?? "";
+    context.updateFile(file, `${content.trimEnd()}
+
+${INSTRUCTIONS_POINTER}`);
+    linked.push(file);
+  }
+  return linked;
+}
+function ensureConfigAgentFiles(context, templateDir, files, data) {
+  if (context.doesFileExist(AGENT_INSTRUCTIONS_PATH)) {
+    return [];
+  }
+  return addTemplateFolder(context, {
+    folderPath: join(templateDir, ".config", "AGENTS"),
+    targetPath: ".config/AGENTS",
+    data,
+    include: (file) => files.includes(file)
+  });
+}
+function appendToAgentInstructions(context, marker, text, separator = "\n\n") {
+  const existing = context.getFile(AGENT_INSTRUCTIONS_PATH);
+  if (existing === void 0) {
+    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);
+}
+
+export { AGENT_INSTRUCTIONS_PATH, INSTRUCTIONS_POINTER, appendToAgentInstructions, ensureConfigAgentFiles, ensureRootAgentFiles };

package/dist/codemods/utils.js

@@ -1,7 +1,7 @@
-import { join, dirname } from 'node:path';
+import { join, dirname, posix } from 'node:path';
 import { createRequire } from 'node:module';
-import { mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
-import 'glob';
+import { mkdirSync, writeFileSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { glob } from 'glob';
 import { styleText } from 'node:util';
 import { output } from '../utils/utils.console.js';
 import { getPackageManagerWithFallback, getPackageManagerSilentInstallCmd } from '../utils/utils.packageManager.js';
@@ -12,8 +12,7 @@ import { debug } from '../utils/utils.cli.js';
 import { renderHandlebarsTemplate } from '../utils/utils.handlebars.js';
 import { buildTemplateData, getTemplateData } from '../utils/utils.templates.js';
 import { getConfig } from '../utils/utils.config.js';
-import '../constants.js';
-import 'fs/promises';
+import { getExportFileName } from '../utils/utils.files.js';
 
 function printChanges(context, key, description) {
   const changes = context.listChanges();
@@ -135,11 +134,16 @@ function readJsonFile(context, path) {
   if (!context.doesFileExist(path)) {
     throw new Error(`Cannot find ${path}`);
   }
+  let parsed;
   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;
 }
 function addDependenciesToPackageJson(context, dependencies, devDependencies = {}, packageJsonPath = "package.json") {
   const currentPackageJson = readJsonFile(context, packageJsonPath);
@@ -236,6 +240,7 @@ function sortObjectByKeys(obj) {
 }
 const migrationsDebug = debug.extend("migrations");
 const additionsDebug = debug.extend("additions");
+const codemodsDebug = debug.extend("codemods");
 function renderTemplate(templatePath, includeWarning = false, data = getTemplateData()) {
   let rendered = renderHandlebarsTemplate(readFileSync(templatePath, "utf-8"), data);
   const regex = /DO NOT EDIT THIS FILE DIRECTLY\./g;
@@ -253,9 +258,37 @@ function getTemplateDataFromContext(context) {
     features: getConfig(context.basePath).features
   });
 }
+function addTemplateFolder(context, {
+  folderPath,
+  targetPath,
+  data,
+  include = () => true
+}) {
+  if (!existsSync(folderPath)) {
+    throw new Error(
+      `Cannot find templates at ${folderPath}. This is a bug in @grafana/create-plugin - please report it.`
+    );
+  }
+  const added = [];
+  for (const relativeFile of glob.sync("**", { cwd: folderPath, dot: true, nodir: true, posix: true })) {
+    const file = join(folderPath, relativeFile);
+    const outputFile = posix.join(posix.dirname(relativeFile), getExportFileName(file));
+    if (!include(outputFile)) {
+      continue;
+    }
+    const filePath = join(targetPath, outputFile);
+    if (context.doesFileExist(filePath)) {
+      codemodsDebug(`${filePath} already exists, skipping`);
+      continue;
+    }
+    context.addFile(filePath, renderHandlebarsTemplate(readFileSync(file, "utf-8"), data));
+    added.push(filePath);
+  }
+  return added;
+}
 const warningComment = `/*
  * \u26A0\uFE0F\u26A0\uFE0F\u26A0\uFE0F THIS FILE WAS SCAFFOLDED BY \`@grafana/create-plugin\`. DO NOT EDIT THIS FILE DIRECTLY. \u26A0\uFE0F\u26A0\uFE0F\u26A0\uFE0F
  *
  */`;
 
-export { addDependenciesToPackageJson, additionsDebug, flushChanges, formatFiles, getTemplateDataFromContext, installNPMDependencies, isVersionGreater, migrationsDebug, printChanges, readJsonFile, removeDependenciesFromPackageJson, renderTemplate, runGoModTidy };
+export { addDependenciesToPackageJson, addTemplateFolder, additionsDebug, codemodsDebug, flushChanges, formatFiles, getTemplateDataFromContext, installNPMDependencies, isVersionGreater, migrationsDebug, printChanges, readJsonFile, removeDependenciesFromPackageJson, renderTemplate, runGoModTidy };