@grafana/create-plugin 7.10.1 → 7.11.0

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/templates/app-sdk/.config/AGENTS/app-sdk.md

@@ -0,0 +1,87 @@
+---
+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.
+- **This plugin generates no Go code.** `kinds/config.cue` sets `codegen: goEnabled: false`, so
+  generation emits only TypeScript and the JSON definitions. Do not 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.
+
+## 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.
+
+This plugin has no Go backend, and does not need one for storage or CRUD. Admission (validation and
+mutation), conversion between versions, and custom routes would require adding one.

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

@@ -0,0 +1,60 @@
+# 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.

package/templates/app-sdk/.config/app-sdk/generate-kinds.mjs

@@ -0,0 +1,138 @@
+// Runs grafana-app-sdk kind code generation from the CUE kinds in ./kinds.
+//
+// Always runs the CLI at the version pinned in VERSION below, resolved as:
+//   1. a previously obtained copy in node_modules/.cache/grafana-app-sdk/<version>/
+//   2. a fresh copy, downloaded from the official release and verified against its checksum
+//
+// A `grafana-app-sdk` on your PATH is deliberately ignored: generated code has to match the library
+// version it is compiled against, and silently generating with whatever happens to be installed makes
+// that mismatch invisible. To use your own build, set GRAFANA_APP_SDK_BIN to the binary — an explicit,
+// per-invocation override for local development.
+//
+// Downloading the CLI needs no Go toolchain. Generation itself only needs Go when codegen.goEnabled
+// is set in kinds/config.cue: the generator formats Go output with golang.org/x/tools, which shells
+// out to `go`.
+//
+// Output paths are configured in kinds/config.cue. Generated code is intended to be committed.
+
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { arch, platform, tmpdir } from 'node:os';
+
+const VERSION = 'v0.60.0';
+const REPO = 'grafana/grafana-app-sdk';
+const BIN = 'grafana-app-sdk';
+
+// Escape hatch for developing against a local CLI build, e.g. one you are changing yourself. Unlike a
+// binary that merely happens to be on PATH, setting this is a deliberate act, so it is honoured.
+const BIN_OVERRIDE = 'GRAFANA_APP_SDK_BIN';
+
+// node_modules is already gitignored, so nothing extra needs ignoring for this cache.
+const CACHE_DIR = resolve('node_modules', '.cache', 'grafana-app-sdk', VERSION);
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, { stdio: 'inherit', ...options });
+}
+
+const EXE = platform() === 'win32' ? '.exe' : '';
+
+/** Returns the release asset's platform pair, or exits if this platform has no published build. */
+function target() {
+  const goos = { linux: 'linux', darwin: 'darwin', win32: 'windows' }[platform()];
+  const goarch = { x64: 'amd64', arm64: 'arm64' }[arch()];
+
+  if (!goos || !goarch) {
+    console.error(
+      `No grafana-app-sdk release build for ${platform()}/${arch()}.\n` +
+        `Install the CLI yourself and re-run: https://github.com/${REPO}/releases`
+    );
+    process.exit(1);
+  }
+
+  return { goos, goarch };
+}
+
+async function fetchOrDie(url, what) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    console.error(`Failed to download ${what} (${response.status} ${response.statusText})\n  ${url}`);
+    process.exit(1);
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/** Downloads the release archive, verifies it against checksums.txt, and unpacks it into CACHE_DIR. */
+async function download({ goos, goarch }) {
+  // Release assets drop the leading "v" from the tag.
+  const archive = `${BIN}_${VERSION.replace(/^v/, '')}_${goos}_${goarch}.tar.gz`;
+  const base = `https://github.com/${REPO}/releases/download/${VERSION}`;
+
+  console.log(`Downloading ${BIN} ${VERSION} for ${goos}/${goarch}...`);
+  const [tarball, checksums] = await Promise.all([
+    fetchOrDie(`${base}/${archive}`, archive),
+    fetchOrDie(`${base}/checksums.txt`, 'checksums.txt'),
+  ]);
+
+  const expected = checksums
+    .toString('utf8')
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/))
+    .find(([, name]) => name === archive)?.[0];
+
+  if (!expected) {
+    console.error(`${archive} is not listed in checksums.txt; refusing to run an unverified binary.`);
+    process.exit(1);
+  }
+
+  const actual = createHash('sha256').update(tarball).digest('hex');
+  if (actual !== expected) {
+    console.error(`Checksum mismatch for ${archive}.\n  expected ${expected}\n  actual   ${actual}`);
+    process.exit(1);
+  }
+
+  // Unpack via tar(1): available on macOS/Linux and shipped with Windows 10+. The archive lays the
+  // binary flat at its root (alongside LICENSE and README.md), so extract straight into CACHE_DIR.
+  const tarPath = join(tmpdir(), `${archive}-${process.pid}`);
+  writeFileSync(tarPath, tarball);
+  mkdirSync(CACHE_DIR, { recursive: true });
+
+  const untar = run('tar', ['-xzf', tarPath, '-C', CACHE_DIR, `${BIN}${EXE}`]);
+  rmSync(tarPath, { force: true });
+  if (untar.status !== 0) {
+    console.error(`Could not unpack ${archive}. Is tar available on your PATH?`);
+    process.exit(1);
+  }
+
+  const binary = join(CACHE_DIR, `${BIN}${EXE}`);
+  chmodSync(binary, 0o755);
+
+  return binary;
+}
+
+async function resolveBinary() {
+  const override = process.env[BIN_OVERRIDE];
+  if (override) {
+    // Exit rather than falling back to the pinned version: you asked for a specific binary, so
+    // silently generating with a different one is the surprise worth avoiding.
+    if (!existsSync(override)) {
+      console.error(`${BIN_OVERRIDE} is set to ${override}, but no such file exists.`);
+      process.exit(1);
+    }
+
+    console.log(`Using ${BIN} from ${BIN_OVERRIDE}: ${override}`);
+    return resolve(override);
+  }
+
+  const cached = join(CACHE_DIR, `${BIN}${EXE}`);
+  if (existsSync(cached)) {
+    return cached;
+  }
+
+  return download(target());
+}
+
+const binary = await resolveBinary();
+const result = run(binary, ['generate', '--source', 'kinds']);
+process.exit(result.status ?? 1);

package/templates/app-sdk/.github/workflows/generate-kinds-drift.yml

@@ -0,0 +1,84 @@
+name: Kinds drift check
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - 'kinds/**'
+      - 'pkg/generated/**'
+      - 'src/generated/**'
+      - 'src/app-sdk-manifest.json'
+      - '.github/workflows/generate-kinds-drift.yml'
+  pull_request:
+    branches:
+      - master
+      - main
+    paths:
+      - 'kinds/**'
+      - 'pkg/generated/**'
+      - 'src/generated/**'
+      - 'src/app-sdk-manifest.json'
+      - '.github/workflows/generate-kinds-drift.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  check-drift:
+    name: Check generated kinds are up to date
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+{{#if_eq packageManagerName "pnpm"}}
+      # pnpm action uses the packageManager field in package.json to
+      # understand which version to install.
+      - uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+{{/if_eq}}
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: '{{ packageManagerName }}'
+
+      - name: Check for backend
+        id: check-for-backend
+        run: |
+          if [ -f "Magefile.go" ]
+          then
+            echo "has-backend=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Setup Go environment
+        if: steps.check-for-backend.outputs.has-backend == 'true'
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Install dependencies
+        run: {{ packageManagerInstallCmd }}
+
+      - name: Cache grafana-app-sdk CLI
+        uses: actions/cache@v4
+        with:
+          path: node_modules/.cache/grafana-app-sdk
+          key: grafana-app-sdk-cli-${{ '{{' }} hashFiles('.config/app-sdk/generate-kinds.mjs') {{ '}}' }}
+
+      - name: Generate kinds
+        run: {{ packageManagerName }} run generate:kinds
+
+      - name: Fail if generated code is out of date
+        run: |
+          # Scoped to kinds/ and the generated output: installing dependencies above can itself touch
+          # files (e.g. package-lock.json, if CI's Node version differs from the one used to generate
+          # the committed lockfile), which is not kind drift and shouldn't fail this check.
+          paths="kinds src/generated pkg/generated src/app-sdk-manifest.json"
+          if [ -n "$(git status --porcelain -- $paths)" ]; then
+            echo "::error::Generated code is out of date. Run '{{ packageManagerName }} run generate:kinds' and commit the result."
+            git status --porcelain -- $paths
+            git diff --stat -- $paths
+            exit 1
+          fi

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

@@ -0,0 +1,3 @@
+# Kinds (grafana-app-sdk)
+
+See [`.config/app-sdk/README.md`](../.config/app-sdk/README.md) for the full workflow.

package/templates/app-sdk/kinds/config.cue

@@ -0,0 +1,39 @@
+package kinds
+
+// config holds the grafana-app-sdk code generation settings, and is read by
+// `grafana-app-sdk generate` (via the default `-c config` selector) when you run
+// `{{ packageManagerName }} run generate:kinds`.
+//
+// Paths are relative to the plugin root and match the layout scaffolded by @grafana/create-plugin:
+// the frontend lives in src/.
+config: {
+	definitions: {
+		manifestVersion:  "v1alpha2"
+
+		// Do not edit this section; the generated manifest must be named exactly as below.
+		// The manifest tells Grafana which kinds and capabilities your app serves. Write it
+		// straight into src/ so the frontend build picks it up as-is.
+		manifestSchemas:  true
+		path:             "src"
+		manifestFileName: "app-sdk-manifest.json"
+		encoding:         "json"
+		// Do not generate separate files per-CRD, they are not used.
+		genCRDs: false
+	}
+
+	codegen: {
+{{#if hasBackend}}
+		// Generated Go types land alongside the plugin backend.
+		goEnabled: true
+		goGenPath: "pkg/generated/"
+{{else}}
+		// This plugin has no Go backend, so skip Go code generation entirely: only TypeScript and
+		// the definitions below are emitted, and no Go toolchain is needed to generate them.
+		goEnabled: false
+{{/if}}
+		// Generated TypeScript types land in the frontend source dir.
+		tsGenPath:                      "src/generated/"
+		enableK8sPostProcessing:        false
+		enableOperatorStatusGeneration: false
+	}
+}

package/templates/app-sdk/kinds/cue.mod/module.cue

@@ -0,0 +1,4 @@
+module: "github.com/{{ kebabCase orgName }}/{{ kebabCase pluginName }}/kinds"
+language: {
+	version: "v0.11.0"
+}

package/templates/app-sdk/kinds/example.cue

@@ -0,0 +1,29 @@
+package kinds
+
+// exampleKind holds the information about the Example kind that does not change between versions.
+// Rename this kind (and its file) to model your own resource.
+exampleKind: {
+	kind:       "Example"
+	pluralName: "Examples"
+	// Namespaced resources are created per-tenant. Use "Cluster" for global resources.
+	scope: "Namespaced"
+	codegen: {
+		ts: {
+			enabled: true
+		}
+		go: {
+			enabled: true
+		}
+	}
+}
+
+// examplev1alpha1 is the v1alpha1 version of the Example kind: the common kind information plus
+// this version's schema. Edit the spec to model your resource, then re-run code generation.
+examplev1alpha1: exampleKind & {
+	schema: {
+		spec: {
+			title:       string
+			description: string
+		}
+	}
+}

package/templates/app-sdk/kinds/manifest.cue

@@ -0,0 +1,29 @@
+package kinds
+
+manifest: {
+	// appName is the unique name of your app. It is used to reference the app from other config
+	// objects, and to derive the API group your app serves (by default,
+	// LOWER(strip dashes)+".ext.grafana.app"). Set `groupOverride` if you need to pin a shorter or
+	// different group.
+	appName: "{{ pluginId }}"
+
+	// versions maps each version your app serves to the kinds it exposes. Version names follow the
+	// format "v<integer>" or "v<integer>(alpha|beta)<integer>".
+	versions: {
+		"v1alpha1": v1alpha1
+	}
+
+	// extraPermissions declares any additional permissions your app needs, e.g. access to kinds
+	// owned by other apps.
+	extraPermissions: {
+		accessKinds: []
+	}
+}
+
+// v1alpha1 is the v1alpha1 version of the app's API.
+v1alpha1: {
+	// kinds lists the version-specific kind values served by this version.
+	kinds: [examplev1alpha1]
+	// served indicates whether this version is served by the API server. Defaults to true.
+	served: true
+}

package/templates/app-sdk/pkg/generated/example/v1alpha1/doc.go

@@ -0,0 +1,11 @@
+// Package v1alpha1 is a stub that exists purely so `go mod tidy` resolves its dependencies before
+// code generation has run. `generate:kinds` fills this package with its own generated files, without
+// removing this one — it's left behind, harmless, since it exports nothing.
+package v1alpha1
+
+import (
+	_ "k8s.io/apimachinery/pkg/apis/meta/v1"
+	_ "k8s.io/apimachinery/pkg/runtime"
+	_ "k8s.io/apimachinery/pkg/runtime/schema"
+	_ "k8s.io/apimachinery/pkg/types"
+)

package/templates/app-sdk/pkg/generated/manifestdata/doc.go

@@ -0,0 +1,12 @@
+// Package manifestdata is a stub that exists purely so `go mod tidy` resolves its dependencies before
+// code generation has run. `generate:kinds` fills this package with its own generated files, without
+// removing this one — it's left behind, harmless, since it exports nothing.
+package manifestdata
+
+import (
+	_ "github.com/grafana/grafana-app-sdk/app"
+	_ "github.com/grafana/grafana-app-sdk/resource"
+	_ "k8s.io/apimachinery/pkg/runtime"
+	_ "k8s.io/kube-openapi/pkg/spec3"
+	_ "k8s.io/kube-openapi/pkg/validation/spec"
+)