Create Plugin: Support new add cmd

[sunker]

What this PR does / why we need it:

This PR adds support for a new create-plugin add cmd that lets users add optional features not enabled by default when scaffolding new plugins.

add Command

Users can now add features to their existing plugins:

npx @grafana/create-plugin add <addition-name> [options]

Additions are codemods that modify the plugin codebase. Each addition can accept validated options through Valibot schemas, providing full type safety and automatic validation.

Example:

npx @grafana/create-plugin add i18n --locales=sv-SE,fr-FR --grafana11Support=true

Migrations vs Additions

Both migrations and additions are codemods that share the same execution pipeline and can be used interchangeably. The key difference is their purpose and when they run:

• Migrations: Automatically run during create-plugin update to keep plugins compatible with newer versions of the tooling. They are forced upon developers to ensure compatibility and are versioned based on the create-plugin version.

• Additions: Optional features that developers choose to add via create-plugin add. They are not versioned and can be run at any time to enhance a plugin with new capabilities.

The distinction between the two is purely semantic based on their use case.

To support additions and simplify the codebase, migrations and additions goes through a shared codemod architecture. A single runner handles execution for both type of codemods, with common steps like formatting, flushing changes and dependency installation. The migrations manager is thin and responsible for version filtering, sequential execution and git commits. The add command directly invokes the runner directly.

Schema-Based Validation with Valibot

Codemods can optionally define options using Valibot schemas, providing automatic ts type inference, runtime validation with clear error messages and a single source of truth for both validation rules and types. Valibot is lightweight (~1kb) and tree-shakeable.

Example:

export const schema = v.object({
  grafana11Support: v.optional(v.boolean(), true),
  locales: v.optional(v.array(v.string())),
  featureName: v.pipe(
    v.string(),
    v.minLength(3, 'Feature name must be at least 3 characters'),
    v.maxLength(50, 'Feature name must be at most 50 characters')
  ),
});

type ExampleOptions = v.InferOutput<typeof schema>;

export default function exampleAddition(context: Context, options: ExampleOptions): Context {
  // Fully typed 
  const { featureName, enabled, port } = options;
}

Which issue(s) this PR fixes:

Fixes #2193

Special notes for your reviewer:

Once this PR is getting closer to a mergeable state, I should add:

• Docs
• CI steps for verifying additions work as expected(?)

📦 Published PR as canary version: Canary Versions

✨ Test out this PR locally via:

npm install [email protected]
npm install @grafana/[email protected]
npm install @grafana/[email protected]
npm install @grafana/[email protected]
# or 
yarn add [email protected]
yarn add @grafana/[email protected]
yarn add @grafana/[email protected]
yarn add @grafana/[email protected]

[github-actions]

Hello! 👋 This repository uses Auto for releasing packages using PR labels.

✨ This PR can be merged and will trigger a new minor release.
NOTE: When merging a PR with the release label please avoid merging another PR. For further information see here.

[sunker]

After async discussions with @jackw, these are the next steps to be taken:

• When an addition has completed, it should update the .config/cprs.json and set features[featureName] to enabled. The featureName should be defined in the addtionMeta type.
• Replace the prompts with command line args. e.g create-plugin add i18n --locales=en-US, se-SV
• Instead of passing the addition name to runAddition, pass the prompt itself so the user can choose which addition to execute.
• Move the i18n script to a separate, follow-up pr

Next steps (after this PR has been merged):

• Write a migration that moves the root cprc.json to .config/cprc.json and deletes the root config
• Create additions scripts for the existing feature flags (bundleGrafanaUI, useReactRouterV6 & useExperimentalRspack)

[sunker]

Planning to iterate a bit more on this PR so moving it to draft state.

[sunker]

will remove this before merging to main

[sunker]

scripts are now imported from the shared codemod runner, so paths must be resolved relative to this registry file's location to ensure correct resolution at runtime