diff --git a/packages/create-plugin/templates/common/.claude/skills/build-plugin/SKILL.md b/packages/create-plugin/templates/common/.claude/skills/build-plugin/SKILL.md new file mode 100644 index 0000000000..97f2d191a3 --- /dev/null +++ b/packages/create-plugin/templates/common/.claude/skills/build-plugin/SKILL.md @@ -0,0 +1 @@ +@../../../../.config/AGENTS/skills/build-plugin.md diff --git a/packages/create-plugin/templates/common/.claude/skills/validate-plugin/SKILL.md b/packages/create-plugin/templates/common/.claude/skills/validate-plugin/SKILL.md new file mode 100644 index 0000000000..14685c2c33 --- /dev/null +++ b/packages/create-plugin/templates/common/.claude/skills/validate-plugin/SKILL.md @@ -0,0 +1 @@ +@../../../../.config/AGENTS/skills/validate-plugin.md diff --git a/packages/create-plugin/templates/common/.codex/skills/build-plugin/SKILL.md b/packages/create-plugin/templates/common/.codex/skills/build-plugin/SKILL.md new file mode 100644 index 0000000000..c49a091550 --- /dev/null +++ b/packages/create-plugin/templates/common/.codex/skills/build-plugin/SKILL.md @@ -0,0 +1,6 @@ +--- +name: build-plugin +description: build a Grafana plugin using the standard build process (frontend and backend if applicable) +--- + +@../../../../.config/AGENTS/skills/build-plugin.md diff --git a/packages/create-plugin/templates/common/.codex/skills/validate-plugin/SKILL.md b/packages/create-plugin/templates/common/.codex/skills/validate-plugin/SKILL.md new file mode 100644 index 0000000000..f265c46ed2 --- /dev/null +++ b/packages/create-plugin/templates/common/.codex/skills/validate-plugin/SKILL.md @@ -0,0 +1,6 @@ +--- +name: validate-plugin +description: validate a Grafana plugin using the official Grafana plugin validator +--- + +@../../../../.config/AGENTS/skills/validate-plugin.md diff --git a/packages/create-plugin/templates/common/.config/AGENTS/skills/build-plugin.md b/packages/create-plugin/templates/common/.config/AGENTS/skills/build-plugin.md new file mode 100644 index 0000000000..dcad7b6674 --- /dev/null +++ b/packages/create-plugin/templates/common/.config/AGENTS/skills/build-plugin.md @@ -0,0 +1,49 @@ +# Build Grafana Plugin + +## Usage + +``` +/build-plugin +``` + +Run this from the root of your plugin directory. + +## Steps + +1. Detect the package manager. Check the `packageManager` field in `package.json` first, then fall back to lock file detection: + ```bash + PKG_MANAGER=$( + if grep -q '"packageManager"' package.json 2>/dev/null; then + grep '"packageManager"' package.json | sed -E 's/.*"packageManager" *: *"([^@]+).*/\1/' + elif [ -f "pnpm-lock.yaml" ]; then + echo "pnpm" + elif [ -f "yarn.lock" ]; then + echo "yarn" + else + echo "npm" + fi + ) + ``` + +2. Check if the plugin has a backend: + ```bash + HAS_BACKEND=$(grep -c '"backend" *: *true' src/plugin.json || true) + ``` + +3. Build the frontend following the build instructions in `.config/AGENTS/instructions.md`. For detailed packaging steps refer to the packaging documentation linked there: + ```bash + ${PKG_MANAGER} run build + ``` + If the build fails, stop and report the error to the user. + +4. If `HAS_BACKEND` is non-zero (backend plugin detected), build the backend following the build instructions and packaging documentation linked in `.config/AGENTS/instructions.md`: + - The backend must be built using `mage` with the build targets provided by the Grafana plugin Go SDK: + ```bash + mage -v + ``` + - If `mage` is not installed, stop and tell the user: "mage is required to build the backend. Install it from https://magefile.org or run: go install github.com/magefile/mage@latest" + - If the build fails, stop and report the error to the user. + - After a successful backend build, ensure all backend binaries in `dist/` have execute permissions: + ```bash + chmod 0755 dist/gpx_* + ``` diff --git a/packages/create-plugin/templates/common/.config/AGENTS/skills/validate-plugin.md b/packages/create-plugin/templates/common/.config/AGENTS/skills/validate-plugin.md new file mode 100644 index 0000000000..096f69002f --- /dev/null +++ b/packages/create-plugin/templates/common/.config/AGENTS/skills/validate-plugin.md @@ -0,0 +1,57 @@ +# Validate Grafana Plugin + +## Important + +Always use the bash commands below directly. + +## Usage + +``` +/validate-plugin +``` + +Run this from the root of your plugin directory. + +## Steps + +1. Check if `npx` or `docker` is available. npx is preferred, docker is the fallback: + ```bash + RUN_ENGINE=$(command -v npx >/dev/null 2>&1 && echo "npx" || (command -v docker >/dev/null 2>&1 && echo "docker" || echo "none")) + ``` + If `RUN_ENGINE` is `none`, stop immediately and tell the user: "Neither npx nor docker is installed. Please install Node.js (for npx) or Docker to run the plugin validator." + +2. Extract the plugin ID from `src/plugin.json` (or `plugin.json`). Sanitize `PLUGIN_ID` to only allow characters valid in a Grafana plugin ID: + ```bash + PLUGIN_ID=$(grep '"id"' < src/plugin.json | sed -E 's/.*"id" *: *"(.*)".*/\1/' | tr -cd 'a-zA-Z0-9._-') + ``` + +3. Run the `build-plugin` skill to build the plugin (frontend and backend if applicable). + +4. Build the plugin zip archive for validation with a timestamp: + ```bash + TIMESTAMP=$(date +%Y%m%d-%H%M%S) + ZIP_NAME="${PLUGIN_ID}-${TIMESTAMP}.zip" + cp -r dist "${PLUGIN_ID}" + zip -qr "${ZIP_NAME}" "${PLUGIN_ID}" + rm -rf "${PLUGIN_ID}" + ``` + +5. Run the validator with JSON output using `$RUN_ENGINE` from step 1 and `$ZIP_NAME` from step 4: + If `$RUN_ENGINE` is `npx`: + ```bash + npx --cache .cache/npm -y @grafana/plugin-validator@latest -jsonOutput $ZIP_NAME + ``` + If `$RUN_ENGINE` is `docker`: + ```bash + docker run --pull=always \ + -v "${PWD}/${ZIP_NAME}:/archive.zip:ro" \ + grafana/plugin-validator-cli -jsonOutput /archive.zip + ``` + +6. Read and interpret the JSON output. Summarize: + - Total errors, warnings, and passed checks + - List each error with its title and detail + - List each warning with its title and detail + - Provide actionable suggestions to fix each issue + +7. Inform the user that a zip file was created (include the filename) and suggest they remove it manually when done. Do NOT run `rm` to delete the zip — this tool does not have permission to remove files.