feat(cli): preserve structured Brev HTTP error codes

pkg/cmd/start/start.go

@@ -3,6 +3,7 @@ package start
 
 import (
 	"fmt"
+	"net/http"
 	"net/url"
 	"os"
 	"path/filepath"
@@ -331,6 +332,7 @@ func createEmptyWorkspace(user *entity.User, apiKeyAuth bool, t *terminal.Termin
 	s := t.NewSpinner()
 	s.Suffix = " Creating your instance. Hang tight 🤙"
 	s.Start()
+	defer s.Stop()
 	w, err := startStore.CreateWorkspace(orgID, cwOptions)
 	if err != nil {
 		return breverrors.WrapAndTrace(err)
@@ -678,7 +680,7 @@ func runSingleStart(t *terminal.Terminal, names []string, name, setupScript, set
 		InstanceType:         gpu,
 	}, startStore)
 	if err != nil {
-		if strings.Contains(err.Error(), "duplicate instance with name") {
+		if store.IsHTTPErrorCode(err, http.StatusBadRequest, "WORKSPACE_ALREADY_EXISTS") {
 			t.Vprint(t.Yellow("try running:"))
 			t.Vprint(t.Yellow("\tbrev start --name [different name] [repo] # or"))
 			t.Vprint(t.Yellow("\tbrev delete [name]"))

pkg/cmd/start/start_test.go

@@ -1,14 +1,92 @@
 package start
 
 import (
+	"bytes"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
 	"testing"
 
 	"github.com/brevdev/brev-cli/pkg/entity"
 	"github.com/brevdev/brev-cli/pkg/store"
 	"github.com/brevdev/brev-cli/pkg/terminal"
+	resty "github.com/go-resty/resty/v2"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
+type failingCreateStartStore struct {
+	StartStore
+	createErr error
+}
+
+func (s failingCreateStartStore) GetAuthTokens() (*entity.AuthTokens, error) {
+	return nil, nil
+}
+
+func (s failingCreateStartStore) GetCurrentUser() (*entity.User, error) {
+	return &entity.User{ID: "user-1"}, nil
+}
+
+func (s failingCreateStartStore) GetActiveOrganizationOrDefault() (*entity.Organization, error) {
+	return &entity.Organization{ID: "org-1"}, nil
+}
+
+func (s failingCreateStartStore) CreateWorkspace(_ string, _ *store.CreateWorkspacesOptions) (*entity.Workspace, error) {
+	return nil, s.createErr
+}
+
+func startHTTPError(t *testing.T, status int, body string) error {
+	t.Helper()
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(status)
+		_, _ = w.Write([]byte(body))
+	}))
+	t.Cleanup(server.Close)
+	response, err := resty.New().R().Post(server.URL)
+	require.NoError(t, err)
+	return fmt.Errorf("create failed: %w", store.NewHTTPResponseError(response))
+}
+
+func TestRunSingleStartDuplicateGuidanceUsesWorkspaceCode(t *testing.T) {
+	cases := []struct {
+		name         string
+		status       int
+		body         string
+		wantGuidance bool
+	}{
+		{"coded duplicate", http.StatusBadRequest, `{"errors":[{"type":"BadRequestError","code":"WORKSPACE_ALREADY_EXISTS","message":"Bad Request"}]}`, true},
+		{"generic bad request", http.StatusBadRequest, `{"errors":[{"type":"BadRequestError","message":"Bad Request"}]}`, false},
+		{"unrelated error with duplicate words", http.StatusBadRequest, `{"errors":[{"type":"BadRequestError","code":"OTHER","message":"duplicate instance with name"}]}`, false},
+		{"wrong status", http.StatusInternalServerError, `{"errors":[{"type":"InternalServerError","code":"WORKSPACE_ALREADY_EXISTS","message":"Internal Server Error"}]}`, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			createErr := startHTTPError(t, tc.status, tc.body)
+			read, write, err := os.Pipe()
+			require.NoError(t, err)
+			original := os.Stdout
+			os.Stdout = write
+			t.Cleanup(func() {
+				os.Stdout = original
+				_ = read.Close()
+				_ = write.Close()
+			})
+			term := terminal.New()
+			runErr := runSingleStart(term, nil, "existing-name", "", "", "", "", "", true, false, failingCreateStartStore{createErr: createErr})
+			require.Error(t, runErr)
+			require.ErrorContains(t, runErr, "create failed")
+			require.NoError(t, write.Close())
+			var output bytes.Buffer
+			_, err = output.ReadFrom(read)
+			require.NoError(t, err)
+			assert.Equal(t, tc.wantGuidance, strings.Contains(output.String(), "brev delete [name]"), output.String())
+		})
+	}
+}
+
 func TestMakeNewWorkspaceFromURL(t *testing.T) {
 	gitTruth := "github.com:brevdev/brev-cli.git"
 	nameTruth := "brev-cli"

pkg/store/http.go

@@ -2,6 +2,7 @@ package store
 
 import (
 	"encoding/json"
+	stderrors "errors"
 	"fmt"
 	"log"
 	"net/http"
@@ -311,9 +312,33 @@ type BrevDeployErrorList struct {
 
 type BrevDeployError struct {
 	Kind    string `json:"type"`
+	Code    string `json:"code"`
 	Message string `json:"message"`
 }
 
+// IsHTTPErrorCode matches a Brev error envelope through ordinary error wrapping.
+// Callers supply the exact status and Brev-owned code they handle; malformed,
+// unstructured, and unrelated errors keep their normal failure path.
+func IsHTTPErrorCode(err error, status int, code string) bool {
+	if code == "" {
+		return false
+	}
+	var responseErr *HTTPResponseError
+	if !stderrors.As(err, &responseErr) || responseErr.Response == nil || responseErr.Response.StatusCode() != status {
+		return false
+	}
+	var envelope BrevDeployErrorList
+	if json.Unmarshal(responseErr.Response.Body(), &envelope) != nil {
+		return false
+	}
+	for _, item := range envelope.Errors {
+		if item.Code == code {
+			return true
+		}
+	}
+	return false
+}
+
 type HTTPResponseError struct {
 	Response *resty.Response
 }

pkg/store/http_response_error_test.go

@@ -1,6 +1,7 @@
 package store
 
 import (
+	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -11,6 +12,28 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+func TestIsHTTPErrorCode(t *testing.T) {
+	cases := []struct {
+		name   string
+		status int
+		body   string
+		code   string
+		want   bool
+	}{
+		{"matching Brev code", http.StatusBadRequest, `{"errors":[{"type":"BadRequestError","code":"WORKSPACE_ALREADY_EXISTS","message":"Request could not be completed"}]}`, "WORKSPACE_ALREADY_EXISTS", true},
+		{"other code", http.StatusBadRequest, `{"errors":[{"type":"BadRequestError","code":"OTHER","message":"Request could not be completed"}]}`, "WORKSPACE_ALREADY_EXISTS", false},
+		{"wrong status", http.StatusInternalServerError, `{"errors":[{"type":"InternalServerError","code":"WORKSPACE_ALREADY_EXISTS","message":"Request could not be completed"}]}`, "WORKSPACE_ALREADY_EXISTS", false},
+		{"unstructured body", http.StatusBadRequest, `{"message":"WORKSPACE_ALREADY_EXISTS"}`, "WORKSPACE_ALREADY_EXISTS", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := fmt.Errorf("create workspace: %w", doRequestWithToken(t, tc.status, tc.body, ""))
+			assert.Equal(t, tc.want, IsHTTPErrorCode(err, http.StatusBadRequest, tc.code))
+		})
+	}
+	assert.False(t, IsHTTPErrorCode(fmt.Errorf("WORKSPACE_ALREADY_EXISTS"), http.StatusBadRequest, "WORKSPACE_ALREADY_EXISTS"))
+}
+
 const unauthorizedBody = `{"errors":[{"type":"UnauthorizedError"}]}`
 
 func doRequestWithToken(t *testing.T, status int, body, token string) *HTTPResponseError {