@grafana/create-plugin 7.10.1 → 7.12.0

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

@@ -0,0 +1,86 @@
+import { Context } from './context.js';
+import { addRequireToGoMod } from './utils.goMod.js';
+
+const GO_MOD = `module github.com/my-org/my-plugin
+
+go 1.26.3
+
+require github.com/grafana/grafana-plugin-sdk-go v0.285.0
+
+require (
+	github.com/BurntSushi/toml v1.5.0 // indirect
+)
+`;
+
+describe('addRequireToGoMod', () => {
+  it('inserts a new require line after the last existing one', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', GO_MOD);
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    const goMod = context.getFile('go.mod') ?? '';
+    expect(goMod).toContain('require github.com/grafana/grafana-app-sdk v0.59.1');
+    // The existing require survives, and the new one is inserted right after it.
+    expect(goMod).toContain(
+      'require github.com/grafana/grafana-plugin-sdk-go v0.285.0\nrequire github.com/grafana/grafana-app-sdk v0.59.1'
+    );
+    // The grouped require (...) block is left untouched.
+    expect(goMod).toContain('require (\n\tgithub.com/BurntSushi/toml v1.5.0 // indirect\n)');
+  });
+
+  it('inserts after the go directive when there is no existing require line', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', 'module github.com/my-org/my-plugin\n\ngo 1.26.3\n');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    const goMod = context.getFile('go.mod') ?? '';
+    expect(goMod).toBe(
+      'module github.com/my-org/my-plugin\n\ngo 1.26.3\nrequire github.com/grafana/grafana-app-sdk v0.59.1\n'
+    );
+  });
+
+  it('does not duplicate an already-present dependency at the same version', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', GO_MOD);
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+    const afterFirst = context.getFile('go.mod');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    expect(context.getFile('go.mod')).toBe(afterFirst);
+  });
+
+  it('bumps the version when a greater one is requested', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', GO_MOD);
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.60.0');
+
+    const goMod = context.getFile('go.mod') ?? '';
+    expect(goMod).toContain('require github.com/grafana/grafana-app-sdk v0.60.0');
+    expect(goMod).not.toContain('v0.59.1');
+  });
+
+  it('does not downgrade when a lesser version is requested', () => {
+    const context = new Context('/virtual');
+    context.addFile('go.mod', GO_MOD);
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.60.0');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    const goMod = context.getFile('go.mod') ?? '';
+    expect(goMod).toContain('require github.com/grafana/grafana-app-sdk v0.60.0');
+    expect(goMod).not.toContain('v0.59.1');
+  });
+
+  it('does nothing when go.mod does not exist', () => {
+    const context = new Context('/virtual');
+
+    addRequireToGoMod(context, 'github.com/grafana/grafana-app-sdk', 'v0.59.1');
+
+    expect(context.doesFileExist('go.mod')).toBe(false);
+  });
+});

package/src/codemods/utils.goMod.ts

@@ -0,0 +1,70 @@
+import type { Context } from './context.js';
+import { isVersionGreater, migrationsDebug } from './utils.js';
+
+// Matches a single-line `require <module> <version>` statement (with an optional trailing
+// `// indirect` comment), the shape every codemod-scaffolded backend's go.mod uses.
+function singleLineRequireRegex(modulePath: string): RegExp {
+  const escapedModulePath = modulePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^require ${escapedModulePath} (\\S+)(.*)$`, 'm');
+}
+
+/**
+ * Adds a `require <modulePath> <version>` line to go.mod, or bumps its version if it's already
+ * present with a lower one (using the same version-comparison logic as addDependenciesToPackageJson).
+ *
+ * Only understands the single-line `require <module> <version>` form that create-plugin's own
+ * templates use — it does not parse grouped `require (...)` blocks, `replace`/`exclude` directives,
+ * or anything else that would need a real go.mod grammar. A codemod that needs that should shell out
+ * to `go mod edit` against the real file on disk instead (see utils.goSdk.ts), outside of Context.
+ */
+export function addRequireToGoMod(context: Context, modulePath: string, version: string, goModPath = 'go.mod') {
+  const content = context.getFile(goModPath);
+
+  if (!content) {
+    migrationsDebug(`Could not find ${goModPath}. Skipping the ${modulePath} dependency.`);
+    return;
+  }
+
+  const requireRegex = singleLineRequireRegex(modulePath);
+  const match = content.match(requireRegex);
+
+  if (match) {
+    const [, existingVersion] = match;
+    if (!isVersionGreater(version, existingVersion, false)) {
+      migrationsDebug(`${goModPath} already requires ${modulePath} at ${existingVersion}. Skipping.`);
+      return;
+    }
+
+    const updated = content.replace(requireRegex, `require ${modulePath} ${version}$2`);
+    context.updateFile(goModPath, updated);
+    return;
+  }
+
+  const insertAt = findRequireInsertionPoint(content);
+  const newRequireLine = `require ${modulePath} ${version}\n`;
+
+  context.updateFile(goModPath, `${content.slice(0, insertAt)}${newRequireLine}${content.slice(insertAt)}`);
+}
+
+/**
+ * Finds where to insert a new top-level `require ...` line: right after the last existing one, else
+ * right after the `go 1.x` directive, else at the end of the file.
+ */
+function findRequireInsertionPoint(content: string): number {
+  const requireLines = [...content.matchAll(/^require \S+ \S+.*$/gm)];
+  const lastRequireLine = requireLines[requireLines.length - 1];
+
+  if (lastRequireLine) {
+    const lineEnd = content.indexOf('\n', lastRequireLine.index! + lastRequireLine[0].length);
+    return lineEnd === -1 ? content.length : lineEnd + 1;
+  }
+
+  const goDirective = content.match(/^go \d+\.\d+(\.\d+)?.*$/m);
+
+  if (goDirective) {
+    const lineEnd = content.indexOf('\n', goDirective.index! + goDirective[0].length);
+    return lineEnd === -1 ? content.length : lineEnd + 1;
+  }
+
+  return content.length;
+}

package/src/codemods/utils.test.ts

@@ -8,13 +8,25 @@ import {
   readJsonFile,
   isVersionGreater,
   printChanges,
+  runGoModTidy,
 } from './utils.js';
 import { join } from 'node:path';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import which from 'which';
 import { output } from '../utils/utils.console.js';
 import { vi } from 'vitest';
 
+vi.mock(import('node:child_process'), async (importOriginal) => ({
+  ...(await importOriginal()),
+  execSync: vi.fn(),
+}));
+
+vi.mock('which', () => ({
+  default: { sync: vi.fn() },
+}));
+
 describe('utils', () => {
   const tmpObj = dirSync({ unsafeCleanup: true });
   const tmpDir = join(tmpObj.name, 'cp-test-migration');
@@ -121,6 +133,43 @@ describe('utils', () => {
     });
   });
 
+  describe('runGoModTidy', () => {
+    beforeEach(() => {
+      vi.mocked(execSync).mockClear();
+      vi.mocked(which.sync).mockReset().mockReturnValue('/usr/local/bin/go');
+    });
+
+    it('runs `go mod tidy` when go.mod was updated', async () => {
+      await writeFile(join(tmpDir, 'go.mod'), 'module example.com/foo\n');
+      const context = new Context(tmpDir);
+      context.updateFile('go.mod', 'module example.com/foo\n\nrequire example.com/bar v1.0.0\n');
+
+      runGoModTidy(context);
+
+      expect(execSync).toHaveBeenCalledWith('go mod tidy', { cwd: tmpDir, stdio: 'inherit' });
+    });
+
+    it('does nothing when go.mod was not changed', () => {
+      const context = new Context(tmpDir);
+      context.addFile('other.txt', 'content');
+
+      runGoModTidy(context);
+
+      expect(execSync).not.toHaveBeenCalled();
+    });
+
+    it('does nothing when there is no `go` binary on PATH', async () => {
+      vi.mocked(which.sync).mockReturnValue(null as unknown as string);
+      await writeFile(join(tmpDir, 'go.mod'), 'module example.com/foo\n');
+      const context = new Context(tmpDir);
+      context.updateFile('go.mod', 'module example.com/foo\n\nrequire example.com/baz v2.0.0\n');
+
+      runGoModTidy(context);
+
+      expect(execSync).not.toHaveBeenCalled();
+    });
+  });
+
   describe('readJsonFile', () => {
     it('should read a json file', () => {
       const context = new Context(tmpDir);

package/src/codemods/utils.ts

@@ -6,6 +6,7 @@ import { styleText } from 'node:util';
 import { output } from '../utils/utils.console.js';
 import { getPackageManagerSilentInstallCmd, getPackageManagerWithFallback } from '../utils/utils.packageManager.js';
 import { execSync } from 'node:child_process';
+import which from 'which';
 import { clean, coerce, gt, gte } from 'semver';
 import { debug } from '../utils/utils.cli.js';
 import { renderHandlebarsTemplate } from '../utils/utils.handlebars.js';
@@ -133,6 +134,44 @@ export function installNPMDependencies(context: Context) {
   }
 }
 
+// Cache the go.mod contents to avoid re-running `go mod tidy` if go.mod hasn't changed
+// (This runs for each codemod used in an update)
+let goModTidyCache: string;
+
+/**
+ * Runs `go mod tidy` when a codemod has updated go.mod, mirroring installNPMDependencies. Skipped
+ * when there is no `go` binary on PATH, since a Go backend is optional for plugins that use this repo's
+ * tooling from a machine without a Go toolchain.
+ */
+export function runGoModTidy(context: Context) {
+  const hasGoModChanges = Object.entries(context.listChanges()).some(
+    ([filePath, { changeType }]) => filePath === 'go.mod' && changeType === 'update'
+  );
+
+  if (!hasGoModChanges) {
+    return;
+  }
+
+  const goModContents = context.getFile('go.mod');
+
+  if (!goModContents) {
+    return;
+  }
+
+  if (goModContents === goModTidyCache) {
+    return;
+  }
+
+  if (!which.sync('go', { nothrow: true })) {
+    additionsDebug('No `go` binary found on PATH. Skipping `go mod tidy`.');
+    return;
+  }
+
+  goModTidyCache = goModContents;
+  output.logSingleLine('Running `go mod tidy`...');
+  execSync('go mod tidy', { cwd: context.basePath, stdio: 'inherit' });
+}
+
 export function readJsonFile<T extends object = any>(context: Context, path: string): T {
   if (!context.doesFileExist(path)) {
     throw new Error(`Cannot find ${path}`);

package/src/commands/add.command.ts

@@ -24,11 +24,16 @@ export const add = async (argv: minimist.ParsedArgs) => {
 
     // filter out minimist internal properties (_ and $0) before passing to codemod
     const { _, $0, ...codemodOptions } = argv;
-    await runCodemod(addition, codemodOptions);
-
-    output.success({
-      title: `Successfully added ${addition.name} to your plugin.`,
-    });
+    const 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.`,
+      });
+    }
   } catch (error) {
     if (error instanceof Error) {
       output.error({

package/src/commands/generate/print-success-message.ts

@@ -39,7 +39,7 @@ export function printGenerateSuccessMessage(answers: TemplateData) {
   });
 }
 
-function getBackendCmd() {
+export function getBackendCmd() {
   const platform = machine();
   if (platform === 'arm64') {
     return output.formatCode('mage -v build:linuxARM64');

package/src/utils/utils.templates.ts

@@ -121,7 +121,7 @@ export function getTemplateData(cliArgs?: GenerateCliArgs): TemplateData {
       isNPM: isNPM(packageManagerName),
       version: currentVersion,
       bundleGrafanaUI,
-      scenesVersion: '^7.0.0',
+      scenesVersion: '^8.17.0',
       useExperimentalRspack: Boolean(features.useExperimentalRspack),
       frontendBundler,
     };
@@ -145,7 +145,7 @@ export function getTemplateData(cliArgs?: GenerateCliArgs): TemplateData {
       isNPM: isNPM(packageManagerName),
       version: currentVersion,
       bundleGrafanaUI,
-      scenesVersion: '^7.0.0',
+      scenesVersion: '^8.17.0',
       pluginExecutable: pluginJson.executable,
       useExperimentalRspack: Boolean(features.useExperimentalRspack),
       frontendBundler,

package/templates/app/src/plugin.json

@@ -58,7 +58,7 @@
     }
   ],
   "dependencies": {
-    "grafanaDependency": ">=12.3.0",
+    "grafanaDependency": ">=13.2.0",
     "plugins": []
   }
 }

package/templates/app-sdk/.config/AGENTS/app-sdk.md

@@ -0,0 +1,99 @@
+---
+name: grafana-app-sdk kind instructions for a grafana plugin
+description: Guides how to work with CUE kinds and generated code in a plugin that uses the grafana-app-sdk
+---
+
+# grafana-app-sdk kinds
+
+This plugin defines its own API resources ("kinds") as [CUE](https://cuelang.org/) schemas using the
+[grafana-app-sdk](https://github.com/grafana/grafana-app-sdk). Code generation turns those schemas into
+TypeScript types and an app manifest that Grafana reads from the plugin bundle.
+
+## Critical rules
+
+- **`kinds/*.cue` is the source of truth for the API.** To change a resource's shape, edit the CUE and
+  regenerate. Never work the other way around.
+- **Never hand-edit generated code.** Everything under the generated directories listed below is
+  overwritten on the next run, so edits there are silently lost. They carry a
+  `Code generated - EDITING IS FUTILE. DO NOT EDIT.` header.
+- **Regenerate after every change under `kinds/`:**
+  ```bash
+  {{ packageManagerName }} run generate:kinds
+  ```
+- **Generated code is committed.** Commit the regenerated files alongside the CUE change so schema
+  changes are reviewable and a fresh clone builds without running code generation.
+- **Go code generation follows `kinds/config.cue`'s `codegen.goEnabled` setting.** If it's `false`,
+  generation emits only TypeScript and the JSON definitions — don't add Go output paths or a Go
+  backend to work around a generation problem.
+- **Do not set `GRAFANA_APP_SDK_BIN`.** It overrides the pinned CLI with a local build, and is meant
+  for people working on the app-sdk itself. Code generated with it can differ from what `VERSION` in
+  `.config/app-sdk/generate-kinds.mjs` produces, so committing it would put the repository out of step. Run
+  `generate:kinds` without it.
+- **Do not add code generation to the build.** It is a schema-change-time step, not a build step. The
+  frontend build must keep working without a Go toolchain.
+- **Never write authorization/permission checks in app code.** Access is declared in the manifest and
+  enforced by Grafana's API server, not by this plugin.
+- **A `Namespaced` kind is folder-scoped by default:** callers need the Stack Role *and* folder access,
+  and every write must set the `grafana.app/folder` annotation to a real folder the caller can access —
+  this applies to anything your backend writes on a user's behalf too. Set `folderScoped: false` on the
+  kind if it shouldn't be gated by folders (writes then skip the annotation).
+- **Every role needs a `roleBindings` entry to be granted to anyone.** Defining a role in
+  `kinds/manifest.cue` without binding it to a basic role (`viewer`/`editor`/`admin`) leaves it unused.
+- **Set `appDisplayName` in `kinds/manifest.cue`** so the app's roles show a readable name in Grafana's
+  role picker, instead of the raw `appName`.
+- **`admin` currently grants the same actions as `editor`.** Don't design a feature assuming admin has
+  extra permissions today.
+
+## Layout
+
+| Path | What it is |
+| ---- | ---------- |
+| `kinds/manifest.cue` | The app manifest: app name, and the versions and kinds your app serves. |
+| `kinds/*.cue` | One file per kind. Edit these to change a resource's schema. |
+| `kinds/config.cue` | Code generation settings (output paths). Rarely needs changing. |
+| `src/generated/` | Generated TypeScript types. **Do not edit.** Import from here in frontend code. |
+| `src/app-sdk-manifest.json` | Generated app manifest JSON. **Do not edit.** The frontend build's existing JSON copy pattern carries it into the plugin bundle. |
+
+## Changing a schema
+
+1. Edit the relevant kind in `kinds/`. Add a new kind by creating a file and listing it in the version's
+   `kinds` array in `kinds/manifest.cue`.
+2. Run `{{ packageManagerName }} run generate:kinds`.
+3. Update the frontend to match. Because the TypeScript types are generated from the CUE, a schema
+   change surfaces as a type error wherever the code is now wrong — fix those rather than casting.
+4. Commit the CUE and the regenerated files together.
+
+Common CUE constructs, for reference:
+
+```cue
+spec: {
+    title:       string                          // required
+    owner?:      string                          // optional
+    tier:        *"gold" | "silver" | "bronze"   // enum, defaults to "gold"
+    labels: [string]: string                     // map
+    tags: [...string]                            // list
+}
+```
+
+For anything beyond this — subtypes, time types, constraints, multiple versions — consult the app-sdk's
+kind authoring reference at
+https://github.com/grafana/grafana-app-sdk/blob/main/docs/custom-kinds/writing-kinds.md rather than
+guessing at CUE syntax.
+
+## Serving the kinds
+
+Grafana serves storage and CRUD for the kinds from the manifest bundled in the plugin, behind the
+`appplugins.loadAppManifest` and `appplugins.registerAPIServer` feature toggles. The development server
+enables both. Grafana only reads plugin manifests at startup, so restart it after rebuilding.
+
+Resources are served under a Kubernetes-style path:
+
+```
+/apis/<group>/<version>/namespaces/<namespace>/<plural>
+```
+
+The namespace is deployment-dependent — `default` on single-tenant Grafana, `stacks-<id>` on Grafana
+Cloud. Read it from `config.namespace` in `@grafana/runtime`; never hardcode it.
+
+No backend is needed for storage or CRUD — that comes from the manifest alone. Admission (validation
+and mutation), conversion between versions, and custom routes require a backend.

package/templates/app-sdk/.config/app-sdk/README.md

@@ -0,0 +1,126 @@
+# Kinds (grafana-app-sdk)
+
+The [kinds/](../../kinds) directory declares your app's API as [CUE](https://cuelang.org/) "kinds", which
+[grafana-app-sdk](https://github.com/grafana/grafana-app-sdk) turns into TypeScript types and an app
+manifest.
+
+| File | Purpose |
+| ---- | ------- |
+| `manifest.cue` | The app manifest: app name, and the versions/kinds your app serves. |
+| `example.cue` | An example kind. Rename it and edit its `spec` to model your own resource. |
+| `config.cue` | Code generation settings (output paths). You rarely need to change this. |
+| `cue.mod/module.cue` | The CUE module definition. |
+
+## Generating code
+
+After every change under this directory:
+
+```bash
+{{ packageManagerName }} run generate:kinds
+```
+
+That script always runs the `grafana-app-sdk` version set as `VERSION` at the top of
+`.config/app-sdk/generate-kinds.mjs`, reusing a copy in `node_modules/.cache/` or downloading and checksum-verifying one for
+your platform. A `grafana-app-sdk` on your `PATH` is ignored, so everyone on the project generates with
+the same version. To run a local build instead, set `GRAFANA_APP_SDK_BIN` to its path. It writes:
+
+| Output | Path |
+| ------ | ---- |
+| TypeScript types | `src/generated/<kind>/<version>/` |
+| App manifest (JSON) | `src/app-sdk-manifest.json` |
+| Go types (backend only) | `pkg/generated/` |
+
+Generated code is meant to be committed, so schema changes show up in review and a fresh clone builds
+without running code generation.
+
+> **Note:** No Go toolchain is needed to run generate:kinds unless generating Go code.** 
+
+## How the manifest reaches Grafana
+
+The generator writes the manifest straight into `src/app-sdk-manifest.json`, so the frontend build's
+existing `**/*.json` copy pattern (`.config/bundler/copyFiles.ts`) carries it into the plugin bundle as
+`dist/app-sdk-manifest.json` with no dedicated copy step. Grafana reads it when the
+`appplugins.loadAppManifest` and `appplugins.registerAPIServer` feature toggles are enabled — the Docker
+dev server in this repo enables both for you. Note the toggles are experimental and off by default in
+Grafana.
+
+With the manifest in place, Grafana serves storage and CRUD for your kinds through its aggregated API
+server, and users can also manage the objects with `kubectl`.
+
+## Adding a backend
+
+Storage and CRUD come from the manifest alone, so a plugin with no backend still gets them. A backend will
+be required for:
+
+- Admission logic (i.e. validation/mutation)
+- Conversion logic (i.e. between API versions)
+- Custom routes and subresource routes
+- Controller logic (informers, watchers, or any other background work)
+
+If this plugin has a backend, `pkg/provider/provider.go` is where you wire those up as your app grows.
+
+## Authorization & RBAC
+
+You don't write permission checks in code. You declare roles and scoping in the manifest, and Grafana's
+aggregated API server enforces them for every caller (kubectl, Terraform, generated clients, your
+frontend). This only applies to requests from users (UI, Service Account tokens) — requests from a
+Service Identity (another internal operator) are less strict.
+
+### Folder scoping
+
+Namespaced kinds (set in `kinds/*.cue`, see `example.cue`) are **folder-scoped by default**. Access
+requires *both* the right Stack Role (see below) *and* folder access on the resource's
+`grafana.app/folder`. If your kind's data doesn't belong in folders, opt out with
+`folderScoped: false` — access then comes down to the Stack Role alone, and adding a folder annotation
+to a request is rejected.
+
+```cue
+examplev1alpha1: exampleKind & {
+    // Opt this kind out of folder-scoped access.
+    folderScoped: false
+    schema: {
+        spec: {
+            title:       string
+            description: string
+        }
+    }
+}
+```
+
+### Roles and role bindings
+
+Declare custom roles in `kinds/manifest.cue`. A role name follows `<app>:<role>` and grants one of three
+tiers — `viewer` (read), `editor` (read + write), or `admin` (currently identical to `editor` — don't
+design around admin having extra powers yet). Role bindings attach your app's roles to Grafana's basic
+roles (`viewer`, `editor`, `admin`), so every Grafana user inherits the matching app role automatically.
+Set `appDisplayName` so your app shows up with a readable name in the Grafana UI's role picker, instead
+of the raw `appName`.
+
+```cue
+manifest: {
+    appName: "{{ pluginId }}"
+    appDisplayName: "{{ pluginId }}"
+    versions: {
+        "v1alpha1": v1alpha1
+    }
+    extraPermissions: {
+        accessKinds: []
+    }
+    // roles your app grants, and which Grafana basic role gets each one by default.
+    roles: [
+        {
+            name: "{{ pluginId }}:editor"
+            permissionSet: "editor"
+        },
+    ]
+    roleBindings: [
+        {
+            roleName: "{{ pluginId }}:editor"
+            basicRole: "editor"
+        },
+    ]
+}
+```
+
+Without a `roleBindings` entry, a role you define is never granted to anyone — add one for every role you
+want users to actually have.