feat: structured error classification for apply conflicts

- Add ErrorKind enum (VALIDATION, CONFLICT, APPLY_FAILED) with ApplyError struct
- Classify Kubernetes errors and return human-readable suggestions
- Conflict errors (409) now show 'Resource already exists — delete it first or use a different name'
- Validation errors (422) suggest using 'Retry with error context'
- Extract resource name from YAML for precise error reporting

Author: Aamod

internal/k8s/errors.go

@@ -0,0 +1,89 @@
+package k8s
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// ErrorKind categorizes the type of error returned by the apply pipeline.
+type ErrorKind string
+
+const (
+	// ErrValidation means the YAML is syntactically invalid or fails server-side dry-run.
+	ErrValidation ErrorKind = "VALIDATION"
+	// ErrConflict means the resource already exists or there is a version conflict.
+	ErrConflict ErrorKind = "CONFLICT"
+	// ErrApplyFailed means an unexpected server error occurred during apply.
+	ErrApplyFailed ErrorKind = "APPLY_FAILED"
+)
+
+// ApplyError is a structured error returned by the apply pipeline.
+type ApplyError struct {
+	Kind        ErrorKind `json:"kind"`
+	Resource    string    `json:"resource,omitempty"`
+	Message     string    `json:"message"`
+	Suggestion  string    `json:"suggestion,omitempty"`
+}
+
+func (e *ApplyError) Error() string {
+	return e.Message
+}
+
+// ClassifyError inspects a raw Kubernetes error message and returns a structured ApplyError.
+func ClassifyError(err error, resource string) *ApplyError {
+	if err == nil {
+		return nil
+	}
+
+	msg := err.Error()
+
+	// Conflict / already exists
+	if strings.Contains(msg, "already exists") {
+		return &ApplyError{
+			Kind:       ErrConflict,
+			Resource:   resource,
+			Message:    msg,
+			Suggestion: "Resource already exists. Delete it first with 'kubectl delete " + resource + "' or use a different name in your prompt.",
+		}
+	}
+
+	// Version conflict / modified
+	if strings.Contains(msg, "the object has been modified") {
+		return &ApplyError{
+			Kind:       ErrConflict,
+			Resource:   resource,
+			Message:    msg,
+			Suggestion: "The resource was modified concurrently. Try again.",
+		}
+	}
+
+	// Validation / dry-run failures
+	if strings.Contains(msg, "invalid") || strings.Contains(msg, "required field") ||
+		strings.Contains(msg, "unknown field") || strings.Contains(msg, "expected") ||
+		strings.Contains(msg, "DryRun") {
+		return &ApplyError{
+			Kind:       ErrValidation,
+			Resource:   resource,
+			Message:    msg,
+			Suggestion: "Fix the YAML and try again. Use 'Retry with error context' to let the LLM correct it.",
+		}
+	}
+
+	// Generic apply failure
+	return &ApplyError{
+		Kind:       ErrApplyFailed,
+		Resource:   resource,
+		Message:    msg,
+		Suggestion: "Check cluster connectivity and RBAC permissions.",
+	}
+}
+
+// MarshalJSON implements json.Marshaler for ApplyError to include the error kind in responses.
+func (e *ApplyError) MarshalJSON() ([]byte, error) {
+	return json.Marshal(map[string]any{
+		"kind":       e.Kind,
+		"resource":   e.Resource,
+		"message":    e.Message,
+		"suggestion": e.Suggestion,
+	})
+}

internal/server/apply.go

@@ -4,10 +4,12 @@ import (
 	"context"
 	"encoding/json"
 	"net/http"
+	"strings"
 	"time"
 
 	"github.com/gorilla/mux"
 	"go.uber.org/zap"
+	"github.com/aamod/llm-infra-assistant/internal/k8s"
 )
 
 type applyRequest struct {
@@ -28,7 +30,21 @@ func (s *Server) handleApply(w http.ResponseWriter, r *http.Request) {
 
 	res, err := s.clusterManager.Apply(r.Context(), req.YAML)
 	if err != nil {
-		http.Error(w, err.Error(), http.StatusInternalServerError)
+		// Extract resource name from error for better classification
+		resource := extractResourceFromError(req.YAML)
+		applyErr := k8s.ClassifyError(err, resource)
+
+		statusCode := http.StatusInternalServerError
+		switch applyErr.Kind {
+		case k8s.ErrConflict:
+			statusCode = http.StatusConflict
+		case k8s.ErrValidation:
+			statusCode = http.StatusUnprocessableEntity
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(statusCode)
+		json.NewEncoder(w).Encode(applyErr)
 		return
 	}
 
@@ -90,3 +106,22 @@ func (s *Server) handleRollback(w http.ResponseWriter, r *http.Request) {
 		"status": "ok",
 	})
 }
+
+// extractResourceFromError parses the YAML to find the resource name for error classification.
+func extractResourceFromError(yamlData string) string {
+	lines := strings.Split(yamlData, "\n")
+	var kind, name string
+	for _, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "kind:") {
+			kind = strings.TrimSpace(strings.TrimPrefix(trimmed, "kind:"))
+		}
+		if strings.HasPrefix(trimmed, "name:") && name == "" {
+			name = strings.TrimSpace(strings.TrimPrefix(trimmed, "name:"))
+		}
+	}
+	if kind != "" && name != "" {
+		return kind + "/" + name
+	}
+	return "unknown"
+}