@grafana/create-plugin 7.12.3 → 7.14.0

package/dist/codemods/agentic/runner.js

@@ -0,0 +1,79 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { parseHandoff } from './handoff.js';
+
+const DEFAULT_POLL_INTERVAL_MS = 500;
+const DEFAULT_KILL_GRACE_MS = 5e3;
+function runAgentSession(options) {
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+  return new Promise((resolve) => {
+    const child = spawn(options.binaryPath, options.args, {
+      stdio: "inherit",
+      cwd: options.cwd,
+      env: { ...process.env, ...options.env }
+    });
+    let settled = false;
+    let pendingHandoff;
+    let killTimer;
+    const pollTimer = setInterval(async () => {
+      const handoff = await readHandoff(options.handoffPath);
+      if (!handoff || settled || pendingHandoff) {
+        return;
+      }
+      pendingHandoff = handoff;
+      clearInterval(pollTimer);
+      child.kill("SIGINT");
+      killTimer = setTimeout(() => child.kill("SIGKILL"), killGraceMs);
+    }, pollIntervalMs);
+    function settle(result) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearInterval(pollTimer);
+      if (killTimer) {
+        clearTimeout(killTimer);
+      }
+      resetTerminal();
+      resolve(result);
+    }
+    child.on("error", () => {
+      settle({ outcome: "ambiguous-exit", exitCode: null, signal: null });
+    });
+    child.on("exit", async (exitCode, signal) => {
+      if (pendingHandoff) {
+        settle({ outcome: "handoff", handoff: pendingHandoff });
+        return;
+      }
+      const handoff = await readHandoff(options.handoffPath);
+      if (handoff) {
+        settle({ outcome: "handoff", handoff });
+        return;
+      }
+      if (isUserAbort(exitCode, signal)) {
+        settle({ outcome: "user-aborted" });
+        return;
+      }
+      settle({ outcome: "ambiguous-exit", exitCode, signal });
+    });
+  });
+}
+async function readHandoff(handoffPath) {
+  try {
+    const raw = await readFile(handoffPath, "utf-8");
+    return parseHandoff(raw);
+  } catch {
+    return void 0;
+  }
+}
+function isUserAbort(exitCode, signal) {
+  return exitCode === 130 || exitCode === 143 || signal === "SIGINT" || signal === "SIGTERM";
+}
+function resetTerminal() {
+  if (process.stdout.isTTY) {
+    process.stdout.write("\x1B[0m\n");
+  }
+}
+
+export { runAgentSession };

package/dist/codemods/agentic/verify.js

@@ -0,0 +1,55 @@
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function runVerifyScripts(options) {
+  const { scripts, cwd, packageManagerName, runScript = runPackageScript } = options;
+  const availableScripts = readPackageScripts(cwd);
+  const results = [];
+  for (const script of scripts) {
+    if (!availableScripts.has(script)) {
+      results.push({ script, outcome: "missing" });
+      continue;
+    }
+    const hasPassed = runScript(packageManagerName, script, cwd);
+    results.push({ script, outcome: hasPassed ? "passed" : "failed" });
+  }
+  return results;
+}
+function buildVerifyWarning(additionName, packageManagerName, results) {
+  const failedResults = results.filter((result) => result.outcome !== "passed");
+  if (failedResults.length === 0) {
+    return void 0;
+  }
+  const failedCount = failedResults.filter((result) => result.outcome === "failed").length;
+  const title = failedCount > 0 ? `${additionName} was applied, but ${failedCount} of its checks failed.` : `${additionName} was applied, but some of its checks could not run.`;
+  return {
+    title,
+    body: [
+      ...failedResults.map(
+        ({ script, outcome }) => outcome === "failed" ? `${packageManagerName} run ${script}  failed` : `${packageManagerName} run ${script}  skipped: package.json has no "${script}" script`
+      ),
+      "Nothing was committed. Review the changes with git diff before you commit them."
+    ]
+  };
+}
+function readPackageScripts(cwd) {
+  try {
+    const packageJson = JSON.parse(
+      readFileSync(join(cwd, "package.json"), "utf-8")
+    );
+    return new Set(Object.keys(packageJson.scripts ?? {}));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function runPackageScript(packageManagerName, script, cwd) {
+  try {
+    execSync(`${packageManagerName} run ${script}`, { cwd, stdio: "inherit" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export { buildVerifyWarning, runVerifyScripts };

package/dist/codemods/migrations/migrations.js

@@ -96,6 +96,18 @@ var defaultMigrations = [
     version: "7.12.2",
     description: "Fix @grafana/ui Combobox dropdown crashing in Jest: add an IntersectionObserver polyfill stub so ScrollIndicators (mounted when the dropdown opens) no longer throws ReferenceError in jsdom.",
     scriptPath: import.meta.resolve("./scripts/016-jest-intersection-observer.js")
+  },
+  {
+    name: "017-jest-30",
+    version: "7.13.0",
+    description: "Update Jest to v30, which replaces micromatch with picomatch and drops the braces dependency flagged by vulnerability scanners.",
+    scriptPath: import.meta.resolve("./scripts/017-jest-30.js")
+  },
+  {
+    name: "018-replace-eslint-webpack-plugin",
+    version: "7.13.0",
+    description: "Replace eslint-webpack-plugin with diagnostics-webpack-plugin in the webpack config. eslint-webpack-plugin depends on micromatch, which pulls in the braces dependency flagged by vulnerability scanners.",
+    scriptPath: import.meta.resolve("./scripts/018-replace-eslint-webpack-plugin.js")
   }
   // Do not use LEGACY_UPDATE_CUTOFF_VERSION for new migrations. It is only used above to force migrations to run
   // for those written before the switch to updates as migrations.

package/dist/codemods/migrations/scripts/017-jest-30.js

@@ -0,0 +1,32 @@
+import { readJsonFile, addDependenciesToPackageJson } from '../../utils.js';
+import { output } from '../../../utils/utils.console.js';
+
+const JEST_30_DEPENDENCIES = {
+  jest: "^30.5.0",
+  "jest-environment-jsdom": "^30.5.0",
+  "@types/jest": "^30.0.0"
+};
+function migrate(context) {
+  if (!context.doesFileExist("package.json")) {
+    return context;
+  }
+  const packageJson = readJsonFile(context, "package.json");
+  const installed = { ...packageJson.dependencies, ...packageJson.devDependencies };
+  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;
+}
+
+export { migrate as default };

package/dist/codemods/migrations/scripts/018-replace-eslint-webpack-plugin.js

@@ -0,0 +1,115 @@
+import { join } from 'node:path';
+import * as recast from 'recast';
+import { addDependenciesToPackageJson, removeDependenciesFromPackageJson, migrationsDebug } 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");
+const CONFIG_PATHS = [
+  WEBPACK_CONFIG_PATH,
+  join(".config", "rspack", "rspack.config.ts"),
+  "webpack.config.ts",
+  "rspack.config.ts"
+];
+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'] }],
+})`;
+function migrate(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) {
+  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;
+  }
+  const lineOffsets = [0];
+  for (const line of source.split("\n")) {
+    lineOffsets.push(lineOffsets[lineOffsets.length - 1] + line.length + 1);
+  }
+  const toOffset = ({ line, column }) => lineOffsets[line - 1] + column;
+  const localNames = /* @__PURE__ */ new Set();
+  const replacements = [];
+  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", `
+${indent}`) + updated.slice(toOffset(end));
+  }
+  context.updateFile(WEBPACK_CONFIG_PATH, updated);
+  return true;
+}
+
+export { migrate as default };

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,6 +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 { 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';
@@ -9,7 +10,9 @@ import which from 'which';
 import { gte, gt, clean, coerce } from 'semver';
 import { debug } from '../utils/utils.cli.js';
 import { renderHandlebarsTemplate } from '../utils/utils.handlebars.js';
-import { getTemplateData } from '../utils/utils.templates.js';
+import { buildTemplateData, getTemplateData } from '../utils/utils.templates.js';
+import { getConfig } from '../utils/utils.config.js';
+import { getExportFileName } from '../utils/utils.files.js';
 
 function printChanges(context, key, description) {
   const changes = context.listChanges();
@@ -131,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);
@@ -232,9 +240,9 @@ function sortObjectByKeys(obj) {
 }
 const migrationsDebug = debug.extend("migrations");
 const additionsDebug = debug.extend("additions");
-function renderTemplate(templatePath, includeWarning = false) {
-  const templateData = getTemplateData();
-  let rendered = renderHandlebarsTemplate(readFileSync(templatePath, "utf-8"), templateData);
+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;
   if (includeWarning && !regex.test(rendered)) {
     rendered = `${warningComment}
@@ -243,9 +251,44 @@ ${rendered}`;
   }
   return rendered;
 }
+function getTemplateDataFromContext(context) {
+  return buildTemplateData({
+    pluginJson: readJsonFile(context, "src/plugin.json"),
+    packageManager: getPackageManagerWithFallback(),
+    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, installNPMDependencies, isVersionGreater, migrationsDebug, printChanges, readJsonFile, removeDependenciesFromPackageJson, renderTemplate, runGoModTidy };
+export { addDependenciesToPackageJson, addTemplateFolder, additionsDebug, codemodsDebug, flushChanges, formatFiles, getTemplateDataFromContext, installNPMDependencies, isVersionGreater, migrationsDebug, printChanges, readJsonFile, removeDependenciesFromPackageJson, renderTemplate, runGoModTidy };

package/dist/codemods/utils.workflows.js

@@ -0,0 +1,94 @@
+import { parseDocument, visit, isScalar } from 'yaml';
+import { codemodsDebug } from './utils.js';
+
+function bumpActionRefs(context, workflowPath, minimumRefs) {
+  const minimums = new Map(
+    Object.entries(minimumRefs).map(([action, minimumRef]) => {
+      const minimum = parseTag(action, minimumRef);
+      if (!minimum) {
+        throw new Error(`The minimum ref '${minimumRef}' for ${action} is not a version tag.`);
+      }
+      return [action, minimum];
+    })
+  );
+  const content = context.getFile(workflowPath);
+  if (!content) {
+    codemodsDebug(`Could not find ${workflowPath}. Skipping action bumps.`);
+    return { found: [], unrecognized: [] };
+  }
+  const doc = parseDocument(content);
+  if (doc.errors.length > 0) {
+    codemodsDebug(`Failed to parse ${workflowPath}: ${doc.errors[0].message}. Skipping action bumps.`);
+    return { found: [], unrecognized: [] };
+  }
+  const found = /* @__PURE__ */ new Set();
+  const unrecognized = /* @__PURE__ */ new Set();
+  const edits = [];
+  visit(doc, {
+    Pair: (_, pair) => {
+      if (!isScalar(pair.key) || pair.key.value !== "uses" || !isScalar(pair.value)) {
+        return;
+      }
+      const uses = pair.value;
+      if (typeof uses.value !== "string" || !uses.value.includes("@")) {
+        return;
+      }
+      const separator = uses.value.lastIndexOf("@");
+      const action = uses.value.slice(0, separator);
+      const ref = uses.value.slice(separator + 1);
+      const minimum = minimums.get(action);
+      if (!minimum) {
+        return;
+      }
+      found.add(action);
+      if (ref === "main") {
+        return;
+      }
+      const tag = parseTag(action, ref);
+      if (!tag) {
+        codemodsDebug(`${workflowPath} pins ${action}@${ref}, which is not a version tag. Leaving it as-is.`);
+        unrecognized.add(action);
+        return;
+      }
+      if (meetsMinimum(tag.version, minimum.version)) {
+        codemodsDebug(`${workflowPath} already pins ${action}@${ref}. Skipping.`);
+        return;
+      }
+      if (!uses.range) {
+        return;
+      }
+      const [start, end] = uses.range;
+      edits.push({ start, end, text: content.slice(start, end).replace(`@${ref}`, `@${raisedRef(tag, minimum)}`) });
+    }
+  });
+  if (edits.length > 0) {
+    const updated = edits.sort((a, b) => b.start - a.start).reduce((acc, { start, end, text }) => `${acc.slice(0, start)}${text}${acc.slice(end)}`, content);
+    context.updateFile(workflowPath, updated);
+  }
+  return { found: [...found], unrecognized: [...unrecognized] };
+}
+function parseTag(action, ref) {
+  const match = /^(?:([^/]+)\/)?v(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(ref);
+  if (!match || match[1] !== void 0 && match[1] !== action.split("/").at(-1)) {
+    return void 0;
+  }
+  return {
+    prefix: match[1] === void 0 ? "" : `${match[1]}/`,
+    version: match.slice(2).filter((part) => part !== void 0).map(Number)
+  };
+}
+function meetsMinimum(version, minimum) {
+  for (const [i, part] of version.entries()) {
+    const minimumPart = minimum[i] ?? 0;
+    if (part !== minimumPart) {
+      return part > minimumPart;
+    }
+  }
+  return true;
+}
+function raisedRef(tag, minimum) {
+  const version = Array.from({ length: tag.version.length }, (_, i) => minimum.version[i] ?? 0);
+  return `${minimum.prefix}v${version.join(".")}`;
+}
+
+export { bumpActionRefs };

package/dist/commands/add.command.js

@@ -1,9 +1,14 @@
-import defaultAdditions from '../codemods/additions/additions.js';
+import additions, { isScriptAddition, hasPromptStep } from '../codemods/additions/additions.js';
+import { prepareAgenticAddition, runAgenticStep, buildAdditionTodosWarning } from '../codemods/agentic/index.js';
+import { getPromptPath, buildDirectiveBlock, buildNextStepsLine } from '../codemods/agentic/prompts.js';
+import { buildVerifyWarning, runVerifyScripts } from '../codemods/agentic/verify.js';
 import { runCodemod } from '../codemods/runner.js';
-import { getPackageManagerFromUserAgent, getPackageManagerExecCmd } from '../utils/utils.packageManager.js';
+import { getPackageManagerWithFallback, getPackageManagerFromUserAgent, getPackageManagerExecCmd } from '../utils/utils.packageManager.js';
 import { performPreCodemodChecks } from '../utils/utils.checks.js';
+import { isGitDirectoryClean, findAdditionTodos } from '../utils/utils.git.js';
 import { output } from '../utils/utils.console.js';
 
+const ADD_FEATURES_DOCS_URL = "https://grafana.com/developers/plugin-tools/how-to-guides/add-features-to-a-plugin";
 const add = async (argv) => {
   const subCommand = argv._[1];
   if (!subCommand) {
@@ -12,23 +17,78 @@ const add = async (argv) => {
   }
   await performPreCodemodChecks(argv);
   try {
-    const addition = defaultAdditions.find((addition2) => addition2.name === subCommand);
+    const addition = additions.find((addition2) => addition2.name === subCommand);
     if (!addition) {
-      const additionsList = defaultAdditions.map((addition2) => addition2.name);
+      const additionsList = additions.map((addition2) => addition2.name);
       throw new Error(`Unknown addition: ${subCommand}
 
 Available additions: ${additionsList.join(", ")}`);
     }
-    const { _, $0, ...codemodOptions } = argv;
-    const context = await runCodemod(addition, codemodOptions);
-    const message = context.getMessage();
+    const { _, $0, agent: agentFlag, ...codemodOptions } = argv;
+    const resolution = await prepareAgenticAddition(addition, agentFlag);
+    const treeWasDirty = resolution?.mode === "enabled" ? !await isGitDirectoryClean() : false;
+    let context;
+    if (isScriptAddition(addition)) {
+      context = await runCodemod(addition, codemodOptions);
+    }
+    const message = context?.getMessage();
     if (message) {
       output[message.level]({ title: message.title, body: message.body });
-    } else {
-      output.success({
-        title: `Successfully added ${addition.name} to your plugin.`
+    }
+    if (!resolution || !hasPromptStep(addition)) {
+      if (!message) {
+        output.success({
+          title: `Successfully added ${addition.name} to your plugin.`
+        });
+      }
+      return;
+    }
+    if (resolution.mode === "enabled") {
+      const result = await runAgenticStep({
+        addition,
+        agent: resolution.agent,
+        context,
+        basePath: process.cwd(),
+        treeWasDirty
       });
+      const summaryBody = result.kind === "applied" ? [result.summary] : [];
+      const { packageManagerName } = getPackageManagerWithFallback();
+      const verifyWarning = buildVerifyWarning(
+        addition.name,
+        packageManagerName,
+        runVerifyScripts({ scripts: addition.verify ?? [], cwd: process.cwd(), packageManagerName })
+      );
+      if (verifyWarning) {
+        output.warning({ title: verifyWarning.title, body: [...summaryBody, ...verifyWarning.body] });
+      } else {
+        output.success({
+          title: `Successfully added ${addition.name} to your plugin.`,
+          body: summaryBody.length > 0 ? summaryBody : void 0
+        });
+      }
+      const todosWarning = buildAdditionTodosWarning(
+        addition.name,
+        await findAdditionTodos(addition.name, process.cwd())
+      );
+      if (todosWarning) {
+        output.warning(todosWarning);
+      }
+      return;
     }
+    const deferredAddition = {
+      name: addition.name,
+      description: addition.description,
+      instructionsPath: getPromptPath(addition.prompt),
+      verifyScripts: addition.verify ?? []
+    };
+    if (resolution.mode === "inside-agent") {
+      output.logSingleLine(buildDirectiveBlock(deferredAddition));
+      return;
+    }
+    output.warning({
+      title: `${addition.name} includes AI-agent instructions that were not applied.`,
+      body: [buildNextStepsLine(deferredAddition)]
+    });
   } catch (error) {
     if (error instanceof Error) {
       output.error({
@@ -40,7 +100,7 @@ Available additions: ${additionsList.join(", ")}`);
   }
 };
 async function showAdditionsHelp() {
-  const additionsList = defaultAdditions.map((addition) => addition.name);
+  const additionsList = additions.map((addition) => addition.name);
   const { packageManagerName, packageManagerVersion } = getPackageManagerFromUserAgent();
   output.error({
     title: "No addition specified",
@@ -48,7 +108,9 @@ async function showAdditionsHelp() {
       `Usage: ${getPackageManagerExecCmd(packageManagerName, packageManagerVersion)} add <addition-name> [options]`,
       "",
       "Available additions:",
-      ...output.bulletList(additionsList)
+      ...output.bulletList(additionsList),
+      "",
+      `Learn more: ${output.formatUrl(ADD_FEATURES_DOCS_URL)}`
     ]
   });
 }