Preflight specific exit codes (#732)

* Return dedicated preflight exit codes

This introduces `cmd/preflight.Result` to classify the final preflight `build.State` and return typed CLI errors instead of a generic `fmt.Errorf` for every non-passing result.

Previously `bk preflight` ended by returning plain string errors such as `preflight build failed`. `internal/errors/handler.go` treated those the same as any other generic failure, so scripts could not distinguish a completed failed build from an active failure, an incomplete build, or an unknown result.

With this change, `Result.Error()` maps preflight outcomes onto dedicated error categories and `internal/errors/handler.go` assigns stable exit codes for each one:

| `build.State` | Exit code | Meaning |
| --- | ---: | --- |
| `passed` | `0` | Successful preflight |
| `failed` | `9` | Terminal preflight failure |
| `canceled` | `9` | Terminal preflight failure |
| `skipped` | `9` | Terminal preflight failure |
| `not_run` | `9` | Terminal preflight failure |
| `failing` | `10` | Active preflight failure |
| `scheduled` | `11` | Incomplete preflight |
| `running` | `11` | Incomplete preflight |
| `blocked` | `11` | Incomplete preflight |
| `canceling` | `11` | Incomplete preflight |
| any other state | `12` | Unknown preflight result |

This keeps `bk preflight` on the shared CLI error-handling path while giving preflight-specific prefixes, messages, and automation-friendly exit codes.

Amp-Thread-ID: https://ampcode.com/threads/T-019d3d79-37bd-700b-8052-34e00ab1e618
Co-authored-by: Amp <amp@ampcode.com>

* Restore rendering the summary of failures at the end of preflight

* Add result kind for unknown kind error

* Add additional line to preflight output

To seperate cleanup from results

* Show preflight build failed.

* Update tests for Preflight build failed.

---------

Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Ben McNicholl <ben.mcnicholl@buildkite.com>

Author: 3 people

cmd/preflight/preflight.go

@@ -15,6 +15,7 @@ import (
 	"github.com/google/uuid"
 	"github.com/mattn/go-isatty"
 
+	buildstate "github.com/buildkite/cli/v3/internal/build/state"
 	"github.com/buildkite/cli/v3/internal/build/watch"
 	"github.com/buildkite/cli/v3/internal/cli"
 	bkErrors "github.com/buildkite/cli/v3/internal/errors"
@@ -35,6 +36,8 @@ type renderStatusError struct {
 	err error
 }
 
+var notifyContext = signal.NotifyContext
+
 func (e renderStatusError) Error() string {
 	return e.err.Error()
 }
@@ -81,7 +84,7 @@ func (c *PreflightCmd) Run(kongCtx *kong.Context, globals cli.GlobalFlags) error
 		return bkErrors.NewValidationError(fmt.Errorf("interval must be greater than 0"), "invalid polling interval")
 	}
 	// Resolve the pipeline to create a build against.
-	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	ctx, stop := notifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 	resolvers := resolver.NewAggregateResolver(
 		resolver.ResolveFromFlag(c.Pipeline, f.Config),
@@ -97,26 +100,23 @@ func (c *PreflightCmd) Run(kongCtx *kong.Context, globals cli.GlobalFlags) error
 	}
 
 	tty := isatty.IsTerminal(os.Stdout.Fd()) || isatty.IsCygwinTerminal(os.Stdout.Fd())
-	renderer := newRenderer(os.Stdout, tty, resolvedPipeline.Name)
+	snapshotOutput := []string{"Creating snapshot of working tree..."}
 
 	var opts []preflight.SnapshotOption
 	if globals.EnableDebug() {
 		opts = append(opts, preflight.WithDebug())
 	}
 
-	renderer.appendSnapshotLine("Creating snapshot of working tree...")
 	result, err := preflight.Snapshot(wt.Filesystem.Root(), preflightID, opts...)
 	if err != nil {
 		return bkErrors.NewSnapshotError(err, "failed to create preflight snapshot",
 			"Ensure you have uncommitted or committed changes to snapshot",
 			"Ensure you have push access to the remote repository",
 		)
 	}
-
-	renderer.setSnapshot(result)
-
-	renderer.appendSnapshotLine("")
-	renderer.appendSnapshotLine(fmt.Sprintf("Creating build on %s/%s...", resolvedPipeline.Org, resolvedPipeline.Name))
+	snapshotOutput = append(snapshotOutput, snapshotLines(result)...)
+	snapshotOutput = append(snapshotOutput, "")
+	snapshotOutput = append(snapshotOutput, fmt.Sprintf("Creating build on %s/%s...", resolvedPipeline.Org, resolvedPipeline.Name))
 	build, _, err := f.RestAPIClient.Builds.Create(ctx, resolvedPipeline.Org, resolvedPipeline.Name, buildkite.CreateBuild{
 		Message: fmt.Sprintf("Preflight %s", preflightID),
 		Commit:  result.Commit,
@@ -129,6 +129,10 @@ func (c *PreflightCmd) Run(kongCtx *kong.Context, globals cli.GlobalFlags) error
 		return bkErrors.WrapAPIError(err, "creating preflight build")
 	}
 
+	renderer := newRenderer(os.Stdout, tty, resolvedPipeline.Name, build.Number)
+	for _, line := range snapshotOutput {
+		renderer.appendSnapshotLine(line)
+	}
 	renderer.appendSnapshotLine(fmt.Sprintf("Build:  %s", build.WebURL))
 
 	if !c.Watch {
@@ -139,7 +143,7 @@ func (c *PreflightCmd) Run(kongCtx *kong.Context, globals cli.GlobalFlags) error
 	tracker := watch.NewJobTracker()
 
 	finalBuild, err := watch.WatchBuild(ctx, f.RestAPIClient, resolvedPipeline.Org, resolvedPipeline.Name, build.Number, interval, func(b buildkite.Build) error {
-		if err := renderer.renderStatus(tracker.Update(b), b); err != nil {
+		if err := renderer.renderStatus(tracker.Update(b), b.State); err != nil {
 			return renderStatusError{err: err}
 		}
 		return nil
@@ -151,6 +155,14 @@ func (c *PreflightCmd) Run(kongCtx *kong.Context, globals cli.GlobalFlags) error
 		}
 	}
 
+	// Flush the screen so final output is not overwritten.
+	renderer.flush()
+
+	buildResult := NewResult(finalBuild)
+	failedJobs := tracker.FailedJobs()
+	finalErr := buildResult.Error()
+	renderer.renderFinalFailures(buildResult, failedJobs)
+
 	if !c.NoCleanup {
 		fmt.Fprintf(os.Stderr, "Cleaning up remote branch %s...\n", result.Branch)
 		if cleanupErr := preflight.Cleanup(wt.Filesystem.Root(), result.Ref, globals.EnableDebug()); cleanupErr != nil {
@@ -161,7 +173,7 @@ func (c *PreflightCmd) Run(kongCtx *kong.Context, globals cli.GlobalFlags) error
 	}
 
 	if errors.Is(err, context.Canceled) {
-		if finalBuild.FinishedAt == nil && !watch.IsTerminalBuildState(finalBuild.State) {
+		if finalBuild.FinishedAt == nil && !buildstate.IsTerminal(buildstate.State(finalBuild.State)) {
 			cancelCtx, cancelStop := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancelStop()
 			if _, cancelErr := f.RestAPIClient.Builds.Cancel(cancelCtx, resolvedPipeline.Org, resolvedPipeline.Name, strconv.Itoa(build.Number)); cancelErr != nil {
@@ -177,7 +189,7 @@ func (c *PreflightCmd) Run(kongCtx *kong.Context, globals cli.GlobalFlags) error
 				fmt.Fprintf(os.Stderr, "Cancelled build #%d\n", build.Number)
 			}
 		}
-		return nil
+		return bkErrors.NewUserAbortedError(context.Canceled, "preflight canceled by user")
 	}
 	if err != nil {
 		return bkErrors.NewInternalError(err, "watching build failed",
@@ -186,14 +198,5 @@ func (c *PreflightCmd) Run(kongCtx *kong.Context, globals cli.GlobalFlags) error
 		)
 	}
 
-	// Flush the screen so final output is not overwritten.
-	renderer.flush()
-
-	renderer.renderFinalFailures(tracker.AllFailed())
-
-	renderer.setResult(finalBuild.State)
-	if finalBuild.State == "passed" {
-		return nil
-	}
-	return fmt.Errorf("preflight build %s", finalBuild.State)
+	return finalErr
 }

cmd/preflight/preflight_test.go

@@ -1,6 +1,7 @@
 package preflight
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"net/http"
@@ -9,6 +10,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"strings"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -259,8 +261,72 @@ func TestPreflightCmd_Run(t *testing.T) {
 		if err == nil {
 			t.Fatal("expected error, got nil")
 		}
-		if !strings.Contains(err.Error(), "preflight build failed") {
-			t.Errorf("expected 'preflight build failed', got: %v", err)
+		if !strings.Contains(err.Error(), "preflight completed with failure: build is failed") {
+			t.Errorf("expected completed failure error, got: %v", err)
+		}
+	})
+
+	t.Run("returns user aborted error when interrupted while watching", func(t *testing.T) {
+		t.Setenv("BUILDKITE_EXPERIMENTS", "preflight")
+
+		originalNotifyContext := notifyContext
+		t.Cleanup(func() { notifyContext = originalNotifyContext })
+
+		watchCtx, cancelWatch := context.WithCancel(context.Background())
+		notifyContext = func(context.Context, ...os.Signal) (context.Context, context.CancelFunc) {
+			return watchCtx, cancelWatch
+		}
+
+		var buildCancelRequests atomic.Int32
+		var pollCount atomic.Int32
+		s := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			switch {
+			case r.Method == "PUT" && strings.Contains(r.URL.Path, "/builds/1/cancel"):
+				buildCancelRequests.Add(1)
+				json.NewEncoder(w).Encode(buildkite.Build{Number: 1, State: "canceling"})
+				return
+			case r.Method == "POST" && strings.Contains(r.URL.Path, "/builds"):
+				json.NewEncoder(w).Encode(buildkite.Build{
+					Number: 1,
+					State:  "scheduled",
+					WebURL: "https://buildkite.com/test-org/test-pipeline/builds/1",
+				})
+				return
+			case r.Method == "GET" && strings.Contains(r.URL.Path, "/builds/1"):
+				if pollCount.Add(1) == 1 {
+					cancelWatch()
+				}
+				json.NewEncoder(w).Encode(buildkite.Build{Number: 1, State: "running"})
+				return
+			}
+			http.NotFound(w, r)
+		}))
+		defer s.Close()
+		t.Setenv("BUILDKITE_REST_API_ENDPOINT", s.URL)
+
+		worktree := initTestRepo(t)
+		t.Chdir(worktree)
+		if err := os.WriteFile(filepath.Join(worktree, "new.txt"), []byte("hello\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+
+		cmd := &PreflightCmd{Pipeline: "test-org/test-pipeline", Watch: true, Interval: 0.01}
+		err := cmd.Run(nil, stubGlobals{})
+		if err == nil {
+			t.Fatal("expected error, got nil")
+		}
+		if !bkErrors.IsUserAborted(err) {
+			t.Fatalf("expected user aborted error, got %T: %v", err, err)
+		}
+		if code := bkErrors.GetExitCodeForError(err); code != bkErrors.ExitCodeUserAbortedError {
+			t.Fatalf("expected exit code %d, got %d", bkErrors.ExitCodeUserAbortedError, code)
+		}
+		if pollCount.Load() == 0 {
+			t.Fatal("expected at least one build poll before interrupt")
+		}
+		if buildCancelRequests.Load() != 1 {
+			t.Fatalf("expected one build cancel request, got %d", buildCancelRequests.Load())
 		}
 	})
 

cmd/preflight/render.go

@@ -9,25 +9,23 @@ import (
 
 	"github.com/buildkite/cli/v3/internal/build/watch"
 	internalpreflight "github.com/buildkite/cli/v3/internal/preflight"
-	buildkite "github.com/buildkite/go-buildkite/v4"
 )
 
 const maxTTYRunningJobs = 10
 
 type renderer interface {
 	appendSnapshotLine(string)
 	setSnapshot(*internalpreflight.SnapshotResult)
-	renderStatus(watch.BuildStatus, buildkite.Build) error
+	renderStatus(watch.BuildStatus, string) error
 	flush()
-	renderFinalFailures([]buildkite.Job)
-	setResult(string)
+	renderFinalFailures(Result, watch.FailedJobs)
 }
 
-func newRenderer(stdout *os.File, tty bool, pipeline string) renderer {
+func newRenderer(stdout *os.File, tty bool, pipeline string, buildNumber int) renderer {
 	if tty {
-		return newTTYRenderer(stdout, pipeline)
+		return newTTYRenderer(stdout, pipeline, buildNumber)
 	}
-	return newPlainRenderer(stdout, pipeline)
+	return newPlainRenderer(stdout, pipeline, buildNumber)
 }
 
 type ttyRenderer struct {
@@ -41,10 +39,11 @@ type ttyRenderer struct {
 	resultRegion   *internalpreflight.Region
 }
 
-func newTTYRenderer(stdout *os.File, pipeline string) *ttyRenderer {
+func newTTYRenderer(stdout *os.File, pipeline string, buildNumber int) *ttyRenderer {
 	screen := internalpreflight.NewScreen(stdout)
 	return &ttyRenderer{
 		pipeline:       pipeline,
+		buildNumber:    buildNumber,
 		screen:         screen,
 		snapshotRegion: screen.AddRegion("snapshot"),
 		titleRegion:    screen.AddRegion("title"),
@@ -62,12 +61,15 @@ func (r *ttyRenderer) setSnapshot(result *internalpreflight.SnapshotResult) {
 	r.snapshotRegion.SetLines(snapshotLines(result))
 }
 
-func (r *ttyRenderer) renderStatus(status watch.BuildStatus, b buildkite.Build) error {
-	r.buildNumber = b.Number
+func (r *ttyRenderer) renderStatus(status watch.BuildStatus, buildState string) error {
 	var presenter jobPresenter = ttyJobPresenter{pipeline: r.pipeline, buildNumber: r.buildNumber}
+	title := fmt.Sprintf("  %s Watching build #%d…", spinner(), r.buildNumber)
+	if buildState != "" {
+		title += " (" + buildState + ")"
+	}
 	r.titleRegion.SetLines([]string{
 		"",
-		fmt.Sprintf("  %s Watching build #%d…", spinner(), b.Number),
+		title,
 		"",
 	})
 	for _, failed := range status.NewlyFailed {
@@ -94,14 +96,9 @@ func (r *ttyRenderer) flush() {
 	r.screen.Flush()
 }
 
-func (r *ttyRenderer) renderFinalFailures(_ []buildkite.Job) {}
-
-func (r *ttyRenderer) setResult(state string) {
-	if state == "passed" {
-		r.resultRegion.SetLines([]string{"", "✅ Preflight passed!"})
-		return
-	}
-	r.resultRegion.SetLines([]string{"", fmt.Sprintf("❌ Preflight %s", state)})
+func (r *ttyRenderer) renderFinalFailures(result Result, failedJobs watch.FailedJobs) {
+	var presenter jobPresenter = ttyJobPresenter{pipeline: r.pipeline, buildNumber: r.buildNumber}
+	r.resultRegion.SetLines(finalResultLines(result, failedJobs, presenter))
 }
 
 type plainRenderer struct {
@@ -111,8 +108,8 @@ type plainRenderer struct {
 	lastLine    string
 }
 
-func newPlainRenderer(stdout io.Writer, pipeline string) *plainRenderer {
-	return &plainRenderer{stdout: stdout, pipeline: pipeline}
+func newPlainRenderer(stdout io.Writer, pipeline string, buildNumber int) *plainRenderer {
+	return &plainRenderer{stdout: stdout, pipeline: pipeline, buildNumber: buildNumber}
 }
 
 func (r *plainRenderer) appendSnapshotLine(line string) {
@@ -125,16 +122,15 @@ func (r *plainRenderer) setSnapshot(result *internalpreflight.SnapshotResult) {
 	}
 }
 
-func (r *plainRenderer) renderStatus(status watch.BuildStatus, b buildkite.Build) error {
-	r.buildNumber = b.Number
+func (r *plainRenderer) renderStatus(status watch.BuildStatus, buildState string) error {
 	var presenter jobPresenter = plainJobPresenter{pipeline: r.pipeline, buildNumber: r.buildNumber}
 	for _, failed := range status.NewlyFailed {
 		if _, err := fmt.Fprintf(r.stdout, "%s\n", presenter.Line(failed)); err != nil {
 			return err
 		}
 	}
 
-	line := fmt.Sprintf("Build #%d %s", b.Number, b.State)
+	line := fmt.Sprintf("Build #%d %s", r.buildNumber, buildState)
 	if summary := status.Summary.String(); summary != "" {
 		line += " — " + summary
 	}
@@ -149,41 +145,40 @@ func (r *plainRenderer) renderStatus(status watch.BuildStatus, b buildkite.Build
 
 func (r *plainRenderer) flush() {}
 
-func (r *plainRenderer) renderFinalFailures(allFailed []buildkite.Job) {
-	var hardFailed, softFailed []buildkite.Job
+func (r *plainRenderer) renderFinalFailures(result Result, failedJobs watch.FailedJobs) {
 	var presenter jobPresenter = plainJobPresenter{pipeline: r.pipeline, buildNumber: r.buildNumber, final: true}
-	for _, rawJob := range allFailed {
-		job := watch.NewFormattedJob(rawJob)
-		if job.IsSoftFailed() {
-			softFailed = append(softFailed, rawJob)
-		} else {
-			hardFailed = append(hardFailed, rawJob)
-		}
+	for _, line := range finalResultLines(result, failedJobs, presenter) {
+		fmt.Fprintln(r.stdout, line)
 	}
+}
+
+func finalResultLines(result Result, failedJobs watch.FailedJobs, presenter jobPresenter) []string {
+	lines := []string{"", resultStatusLine(result)}
 
-	if len(hardFailed) > 0 {
-		fmt.Fprintln(r.stdout)
-		fmt.Fprintf(r.stdout, "Failed jobs (%d):\n", len(hardFailed))
-		for _, rawJob := range hardFailed {
-			fmt.Fprintf(r.stdout, "%s\n", presenter.Line(rawJob))
+	if len(failedJobs.Hard) > 0 {
+		lines = append(lines, "", fmt.Sprintf("Failed jobs (%d):", len(failedJobs.Hard)))
+		for _, rawJob := range failedJobs.Hard {
+			lines = append(lines, presenter.Line(rawJob))
 		}
 	}
 
-	if len(softFailed) > 0 {
-		fmt.Fprintln(r.stdout)
-		fmt.Fprintf(r.stdout, "Soft failed jobs (%d):\n", len(softFailed))
-		for _, rawJob := range softFailed {
-			fmt.Fprintf(r.stdout, "%s\n", presenter.Line(rawJob))
+	if len(failedJobs.Soft) > 0 {
+		lines = append(lines, "", fmt.Sprintf("Soft failed jobs (%d):", len(failedJobs.Soft)))
+		for _, rawJob := range failedJobs.Soft {
+			lines = append(lines, presenter.Line(rawJob))
 		}
 	}
+
+	lines = append(lines, "")
+
+	return lines
 }
 
-func (r *plainRenderer) setResult(state string) {
-	if state == "passed" {
-		fmt.Fprintln(r.stdout, "✅ Preflight passed!")
-		return
+func resultStatusLine(result Result) string {
+	if result.kind == resultCompletedPass {
+		return "✅ Preflight build passed."
 	}
-	fmt.Fprintf(r.stdout, "❌ Preflight %s\n", state)
+	return fmt.Sprintf("❌ Preflight build %s.", result.buildState)
 }
 
 func snapshotLines(result *internalpreflight.SnapshotResult) []string {