📝 Add README. Change name a little

Author: mcncl

README.md

@@ -1,61 +1,145 @@
-# Template Buildkite Plugin [![Build status](https://badge.buildkite.com/d673030645c7f3e7e397affddd97cfe9f93a40547ed17b6dc5.svg)](https://buildkite.com/buildkite/plugins-template)
+# Bazel BEP Annotate Buildkite Plugin
 
-A Buildkite plugin for something awesome
+A Buildkite plugin that creates rich annotations from Bazel Event Protocol (BEP) output files, providing at-a-glance build status, test results, and performance information.
 
-## Options
+![Build status](https://badge.buildkite.com/d673030645c7f3e7e397affddd97cfe9f93a40547ed17b6dc5.svg)
+
+## Features
+
+- 📊 Parses Bazel Event Protocol (BEP) output files
+- ✅ Displays build status with success/failure counts
+- ⏱️ Shows test durations and highlights slow tests
+- ❌ Provides detailed failure information with error logs
+- 🔄 Automatically detects BEP files based on Bazel commands
+- 💡 Includes random developer wisdom quotes for inspiration
 
-These are all the options available to configure this plugin's behaviour.
+## Prerequisites
 
-### Required
+This plugin requires:
+- Bash
+- jq (for JSON parsing)
+- bc (for floating point calculations)
+
+## Options
 
-#### `mandatory` (string)
+### `bep_file` (optional)
 
-A great description of what this is supposed to do.
+Path to the Bazel Event Protocol JSON file to parse. If not provided, the plugin will attempt to:
+1. Extract it from the `bazel_command` if provided
+2. Look for files at common locations (bazel-events.json, bazel-bep.json, bep.json)
 
-### Optional
+### `bazel_command` (optional)
 
-#### `optional` (string)
+The original Bazel command that was run. This is used for display purposes and can also be used to extract the BEP file path if it contains a `--build_event_json_file` flag.
 
-Describe how the plugin behaviour changes if this option is not specified, allowed values and its default.
+### `skip_if_no_bep` (optional, boolean)
+
+If set to `true`, the plugin will exit successfully if no BEP file is found, instead of failing the build.
+Default: `false`
 
 ## Examples
 
-Show how your plugin is to be used
+### Basic usage with explicit BEP file
 
 ```yaml
 steps:
-  - label: "🔨 Running plugin"
-    command: "echo template plugin"
+  - label: "🔨 Build with Bazel"
+    command: |
+      bazel build //... --build_event_json_file=bazel-events.json
     plugins:
-      - template#v1.0.0:
-          mandatory: "value"
+      - bazel-bep-annotate#v1.0.0:
+          bep_file: bazel-events.json
 ```
 
-## And with other options as well
+### Automatic BEP detection from Bazel command
 
-If you want to change the plugin behaviour:
+```yaml
+steps:
+  - label: "🔨 Build with Bazel"
+    command: |
+      bazel build //... --build_event_json_file=bazel-events.json
+    plugins:
+      - bazel-bep-annotate#v1.0.0:
+          bazel_command: "bazel build //... --build_event_json_file=bazel-events.json"
+```
+
+### Skip annotations if no BEP file found
 
 ```yaml
 steps:
-  - label: "🔨 Running plugin"
-    command: "echo template plugin with options"
+  - label: "🔨 Build with Bazel"
+    command: |
+      # Command might not produce a BEP file
+      bazel build //...
     plugins:
-      - template#v1.0.0:
-          mandatory: "value"
-          optional: "example"
+      - bazel-bep-annotate#v1.0.0:
+          skip_if_no_bep: true
+```
+
+## Common Use Cases
+
+### Running tests with annotations
+
+```yaml
+steps:
+  - label: "🧪 Run Bazel tests"
+    command: |
+      bazel test //... --build_event_json_file=bazel-test-events.json
+    plugins:
+      - bazel-bep-annotate#v1.0.0:
+          bep_file: bazel-test-events.json
+```
+
+### Running builds with annotations in a custom Bazel workspace
+
+```yaml
+steps:
+  - label: "🔨 Build with Bazel (custom workspace)"
+    command: |
+      cd my-workspace
+      bazel build //... --build_event_json_file=bazel-events.json
+    plugins:
+      - bazel-bep-annotate#v1.0.0:
+          bep_file: my-workspace/bazel-events.json
+```
+
+## How It Works
+
+1. After your Bazel command runs, the plugin looks for the BEP file
+2. It parses the BEP data to extract build status, test results, and performance metrics
+3. It creates a detailed Buildkite annotation with this information
+4. The annotation shows success/failure status, test performance, and detailed error logs
+
+## Troubleshooting
+
+### The plugin can't find the BEP file
+
+Make sure:
+1. The Bazel command has completed successfully
+2. You've specified the `--build_event_json_file` flag in your Bazel command
+3. The path to the BEP file is correct and accessible to the build agent
+
+### The annotation doesn't show all targets
+
+The BEP file might not contain complete information. Try running Bazel with additional flags:
+```
+--experimental_build_event_text_file_path_conversion=true
 ```
 
 ## ⚒ Developing
 
-You can use the [bk cli](https://github.com/buildkite/cli) to run the [pipeline](.buildkite/pipeline.yml) locally:
+You can use the [bk cli](https://github.com/buildkite/cli) to run the plugin locally:
 
 ```bash
 bk local run
 ```
 
 ## 👩‍💻 Contributing
 
-Your policy on how to contribute to the plugin!
+1. Fork the repository
+2. Create a feature branch
+3. Add your changes, including tests
+4. Submit a pull request
 
 ## 📜 License
 

lib/plugin.bash

@@ -1,7 +1,7 @@
 #!/bin/bash
 set -euo pipefail
 
-PLUGIN_PREFIX="BAZEL_BEP_ANNOTATOR"
+PLUGIN_PREFIX="BAZEL_BEP_ANNOTATE"
 
 # Reads either a value or a list from the given env prefix
 function prefix_read_list() {

plugin.yml

@@ -1,4 +1,4 @@
-name: Bazel BEP Annotator
+name: Bazel BEP Annotate
 description: Creates Buildkite annotations from Bazel Event Protocol output
 author: https://github.com/buildkite-plugins
 requirements:

tests/post-command.bats

@@ -8,7 +8,7 @@ setup() {
 
   # Setup environment
   export BUILDKITE=true
-  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATOR_SKIP_IF_NO_BEP=false
+  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATE_SKIP_IF_NO_BEP=false
 
   # Mock the process_bep function to avoid relying on external tools
   cat > "$TEMP_DIR/mock-bazel-bep.bash" << 'EOF'
@@ -134,7 +134,7 @@ teardown() {
 
 @test "Skip when no BEP file and skip option is enabled" {
   # No BEP file, but we'll enable skip option
-  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATOR_SKIP_IF_NO_BEP=true
+  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATE_SKIP_IF_NO_BEP=true
 
   # Ensure no common files exist
   rm -f "${BUILDKITE_BUILD_CHECKOUT_PATH:-$PWD}/bazel-events.json" || true
@@ -149,7 +149,7 @@ teardown() {
 
 @test "Fail when no BEP file and skip option is disabled" {
   # No BEP file, skip option disabled
-  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATOR_SKIP_IF_NO_BEP=false
+  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATE_SKIP_IF_NO_BEP=false
 
   # Ensure no common files exist
   rm -f "${BUILDKITE_BUILD_CHECKOUT_PATH:-$PWD}/bazel-events.json" || true
@@ -165,7 +165,7 @@ teardown() {
 @test "Process BEP file when explicitly provided" {
   # Create a sample BEP file
   touch "$TEMP_DIR/sample.bep"
-  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATOR_BEP_FILE="$TEMP_DIR/sample.bep"
+  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATE_BEP_FILE="$TEMP_DIR/sample.bep"
 
   run "$TEMP_DIR/hooks/post-command"
 
@@ -176,7 +176,7 @@ teardown() {
 @test "Detect BEP file from Bazel command" {
   # Create a sample BEP file
   touch "$TEMP_DIR/detected.bep"
-  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATOR_BAZEL_COMMAND="bazel build //... --build_event_json_file=$TEMP_DIR/detected.bep"
+  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATE_BAZEL_COMMAND="bazel build //... --build_event_json_file=$TEMP_DIR/detected.bep"
 
   run "$TEMP_DIR/hooks/post-command"
 
@@ -202,8 +202,8 @@ teardown() {
 
 @test "Skip when BEP file doesn't exist and skip is enabled" {
   # Reference a non-existent BEP file with skip enabled
-  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATOR_BEP_FILE="$TEMP_DIR/nonexistent.bep"
-  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATOR_SKIP_IF_NO_BEP=true
+  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATE_BEP_FILE="$TEMP_DIR/nonexistent.bep"
+  export BUILDKITE_PLUGIN_BAZEL_BEP_ANNOTATE_SKIP_IF_NO_BEP=true
 
   run "$TEMP_DIR/hooks/post-command"