@grafana/create-plugin 7.10.0 → 7.11.0

package/src/codemods/runner.ts

@@ -1,5 +1,5 @@
 import { Context } from './context.js';
-import { formatFiles, flushChanges, installNPMDependencies, printChanges } from './utils.js';
+import { formatFiles, flushChanges, installNPMDependencies, printChanges, runGoModTidy } from './utils.js';
 import { parseAndValidateOptions } from './schema-parser.js';
 import { Codemod } from './types.js';
 
@@ -14,6 +14,7 @@ import { Codemod } from './types.js';
  * 5. Flush changes to disk
  * 6. Print summary
  * 7. Install dependencies if needed
+ * 8. Run `go mod tidy` if go.mod changed
  */
 export async function runCodemod(codemod: Codemod, options?: Record<string, any>): Promise<Context> {
   const codemodModule = await import(codemod.scriptPath);
@@ -38,6 +39,7 @@ export async function runCodemod(codemod: Codemod, options?: Record<string, any>
     flushChanges(updatedContext);
     printChanges(updatedContext, codemod.name, codemod.description);
     installNPMDependencies(updatedContext);
+    runGoModTidy(updatedContext);
 
     return updatedContext;
   } catch (error) {

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/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);