refactor(R2d.158): carve internal/api/aivehpaint subpackage

Move the vehicle paint preview AI handler into the aivehpaint API subpackage and rename its exported handler type and constructor for package-local clarity.

Wire router.go to construct the carved handler through aivehpaint.NewHandler while preserving the existing router variable and AIHandlers field names.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: atulmgupta

internal/api/aivehpaint/doc.go

@@ -0,0 +1,6 @@
+// Package aivehpaint serves the LLM-backed vehicle paint-preview draft route
+// at POST /api/v1/ai/vehicles/{vehicleID}/paint-preview/draft. It proposes
+// review-only paint preview prompts without persisting vehicle configuration.
+//
+// Layer: handler
+package aivehpaint

…/api/ai_vehicle_paint_preview_handler.go internal/api/aivehpaint/handler.gointernal/api/ai_vehicle_paint_preview_handler.go renamed to internal/api/aivehpaint/handler.go internal/api/ai_vehicle_paint_preview_handler.go renamed to internal/api/aivehpaint/handler.go

@@ -1,9 +1,9 @@
-package api
+package aivehpaint
 
 // Phase-50 / 0061 — GEN2 Vehicle paint preview.
 //
-// ai_vehicle_paint_preview_handler.go implements the LLM-backed
-// handler at POST /api/v1/ai/vehicles/{vehicleID}/paint-preview/draft.
+// handler.go implements the LLM-backed handler at
+// POST /api/v1/ai/vehicles/{vehicleID}/paint-preview/draft.
 // The flow mirrors auto-trip-naming / route-efficiency-
 // suggestions / drive-coaching narration handlers — same
 // dispatch+stream loop, no persistence (one-shot proposal; no
@@ -47,6 +47,7 @@ package api
 //     is added or modified by this slice.
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -63,49 +64,50 @@ import (
 	"github.com/ev-dev-labs/teslasync/internal/ai/strategy"
 	"github.com/ev-dev-labs/teslasync/internal/ai/stream"
 	"github.com/ev-dev-labs/teslasync/internal/ai/tools"
+	"github.com/ev-dev-labs/teslasync/internal/api/httpx"
 	tsauth "github.com/ev-dev-labs/teslasync/internal/auth"
 )
 
-// aiVehiclePaintPreviewMaxIterations bounds the dispatcher's
+// maxIterations bounds the dispatcher's
 // tool-loop. The strategy is at most draft-then-answer (with
 // optional retries on validator rejection) — a hard ceiling of 6 is
 // generous and matches the aiAutoTripNamingMaxIterations precedent.
-const aiVehiclePaintPreviewMaxIterations = 6
+const maxIterations = 6
 
-// aiVehiclePaintPreviewMaxBodyBytes is the hard cap on the request
+// maxBodyBytes is the hard cap on the request
 // body. 16 KiB is generous for an optional {style_hint} envelope
 // and defends against amplification or accidental payload bombs.
-const aiVehiclePaintPreviewMaxBodyBytes = 16 * 1024
+const maxBodyBytes = 16 * 1024
 
-// aiVehiclePaintPreviewMaxStyleHintLen mirrors the tool's
+// maxStyleHintLen mirrors the tool's
 // paintPreviewMaxStyleHintLen so a body that would be rejected by
 // the tool is rejected by the handler first (faster failure mode +
 // no SSE stream opened for a doomed request).
-const aiVehiclePaintPreviewMaxStyleHintLen = 80
+const maxStyleHintLen = 80
 
-// aiVehiclePaintPreviewRequest is the JSON body shape the handler
+// request is the JSON body shape the handler
 // accepts. Body is optional (empty body is accepted). StyleHint is
 // optional free-text the LLM may quote when seeding the
 // draft_paint_preview_prompt tool.
-type aiVehiclePaintPreviewRequest struct {
+type request struct {
 	StyleHint string `json:"style_hint,omitempty"`
 }
 
-// AIVehiclePaintPreviewHandler is the HTTP handler for
+// Handler is the HTTP handler for
 // POST /api/v1/ai/vehicles/{vehicleID}/paint-preview/draft.
 //
 // Stateless beyond its constructor inputs; safe for concurrent use
 // across requests. Construction is in router.go so the dispatcher's
 // tool registry + provider registry are wired once at boot.
-type AIVehiclePaintPreviewHandler struct {
+type Handler struct {
 	registry   *provider.Registry
 	tools      *tools.Registry
 	strategy   strategy.Strategy
 	headerName string
 	maxIters   int
 }
 
-// NewAIVehiclePaintPreviewHandler constructs the handler. All
+// NewHandler constructs the handler. All
 // non-pointer arguments are required; the constructor panics on a
 // nil so the wiring bug surfaces at boot, not at first request.
 //
@@ -117,80 +119,84 @@ type AIVehiclePaintPreviewHandler struct {
 //
 // strat:      the vehicle-paint-preview Strategy (one per process).
 // headerName: forward-auth header name; used to extract subject for audit.
-func NewAIVehiclePaintPreviewHandler(
+func NewHandler(
 	registry *provider.Registry,
 	toolReg *tools.Registry,
 	strat strategy.Strategy,
 	headerName string,
-) *AIVehiclePaintPreviewHandler {
+) *Handler {
 	switch {
 	case registry == nil:
-		panic("api: NewAIVehiclePaintPreviewHandler: nil provider.Registry")
+		panic("aivehpaint: NewHandler: nil provider.Registry")
 	case toolReg == nil:
-		panic("api: NewAIVehiclePaintPreviewHandler: nil tools.Registry")
+		panic("aivehpaint: NewHandler: nil tools.Registry")
 	case strat == nil:
-		panic("api: NewAIVehiclePaintPreviewHandler: nil strategy.Strategy")
+		panic("aivehpaint: NewHandler: nil strategy.Strategy")
 	}
-	return &AIVehiclePaintPreviewHandler{
+	return &Handler{
 		registry:   registry,
 		tools:      toolReg,
 		strategy:   strat,
 		headerName: headerName,
-		maxIters:   aiVehiclePaintPreviewMaxIterations,
+		maxIters:   maxIterations,
 	}
 }
 
-// parseAIVehiclePaintPreviewURL extracts and validates the
+func denyAllConfirm(_ context.Context, _ dispatch.ConfirmRequest) (dispatch.ConfirmDecision, error) {
+	return dispatch.ConfirmDenied, nil
+}
+
+// parseURL extracts and validates the
 // vehicleID URL parameter. Pulled out so the unit tests can
 // exercise the parser without constructing a full handler.
 //
 // vehicleID MUST be a positive integer; zero or negative values are
 // rejected with a 400.
-func parseAIVehiclePaintPreviewURL(w http.ResponseWriter, r *http.Request) (int64, bool) {
+func parseURL(w http.ResponseWriter, r *http.Request) (int64, bool) {
 	raw := chi.URLParam(r, "vehicleID")
 	if raw == "" {
-		writeError(w, http.StatusBadRequest, "vehicleID URL parameter is required")
+		httpx.WriteError(w, http.StatusBadRequest, "vehicleID URL parameter is required")
 		return 0, false
 	}
 	id, err := strconv.ParseInt(raw, 10, 64)
 	if err != nil {
-		writeError(w, http.StatusBadRequest, fmt.Sprintf("vehicleID must be a positive integer (got %q)", raw))
+		httpx.WriteError(w, http.StatusBadRequest, fmt.Sprintf("vehicleID must be a positive integer (got %q)", raw))
 		return 0, false
 	}
 	if id <= 0 {
-		writeError(w, http.StatusBadRequest, "vehicleID must be > 0")
+		httpx.WriteError(w, http.StatusBadRequest, "vehicleID must be > 0")
 		return 0, false
 	}
 	return id, true
 }
 
-// parseAIVehiclePaintPreviewBody extracts and validates the
+// parseBody extracts and validates the
 // optional request JSON body. Empty body is accepted (returns the
 // zero request). On parse failure writes a 4xx and returns false.
-func parseAIVehiclePaintPreviewBody(w http.ResponseWriter, r *http.Request) (aiVehiclePaintPreviewRequest, bool) {
-	var req aiVehiclePaintPreviewRequest
+func parseBody(w http.ResponseWriter, r *http.Request) (request, bool) {
+	var req request
 	if r.Body == nil {
 		return req, true
 	}
-	limited := io.LimitReader(r.Body, aiVehiclePaintPreviewMaxBodyBytes+1)
+	limited := io.LimitReader(r.Body, maxBodyBytes+1)
 	body, err := io.ReadAll(limited)
 	if err != nil {
-		writeError(w, http.StatusBadRequest, fmt.Sprintf("failed to read request body: %v", err))
+		httpx.WriteError(w, http.StatusBadRequest, fmt.Sprintf("failed to read request body: %v", err))
 		return req, false
 	}
-	if int64(len(body)) > aiVehiclePaintPreviewMaxBodyBytes {
-		writeError(w, http.StatusRequestEntityTooLarge, fmt.Sprintf("request body exceeds %d byte cap", aiVehiclePaintPreviewMaxBodyBytes))
+	if int64(len(body)) > maxBodyBytes {
+		httpx.WriteError(w, http.StatusRequestEntityTooLarge, fmt.Sprintf("request body exceeds %d byte cap", maxBodyBytes))
 		return req, false
 	}
 	if len(body) == 0 {
 		return req, true
 	}
 	if err := json.Unmarshal(body, &req); err != nil {
-		writeError(w, http.StatusBadRequest, fmt.Sprintf("invalid JSON body: %v", err))
+		httpx.WriteError(w, http.StatusBadRequest, fmt.Sprintf("invalid JSON body: %v", err))
 		return req, false
 	}
-	if len([]rune(req.StyleHint)) > aiVehiclePaintPreviewMaxStyleHintLen {
-		writeError(w, http.StatusBadRequest, fmt.Sprintf("style_hint must be at most %d characters", aiVehiclePaintPreviewMaxStyleHintLen))
+	if len([]rune(req.StyleHint)) > maxStyleHintLen {
+		httpx.WriteError(w, http.StatusBadRequest, fmt.Sprintf("style_hint must be at most %d characters", maxStyleHintLen))
 		return req, false
 	}
 	return req, true
@@ -202,13 +208,13 @@ func parseAIVehiclePaintPreviewBody(w http.ResponseWriter, r *http.Request) (aiV
 // WriteDone. Every error path either writes a structured frame
 // onto the SSE stream (when the writer has been opened) or a plain
 // JSON 4xx/5xx (before it has).
-func (h *AIVehiclePaintPreviewHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	// 1) Parse + validate URL parameters and optional body.
-	vehicleID, ok := parseAIVehiclePaintPreviewURL(w, r)
+	vehicleID, ok := parseURL(w, r)
 	if !ok {
 		return
 	}
-	req, ok := parseAIVehiclePaintPreviewBody(w, r)
+	req, ok := parseBody(w, r)
 	if !ok {
 		return
 	}
@@ -220,7 +226,7 @@ func (h *AIVehiclePaintPreviewHandler) ServeHTTP(w http.ResponseWriter, r *http.
 	// gracefully.
 	if _, err := h.registry.For(r.Context(), vehiclepaintpreview.FeatureID); err != nil {
 		log.Error().Err(err).Msg("ai vehicle-paint-preview: provider.For failed")
-		writeError(w, http.StatusBadGateway, "ai provider unavailable")
+		httpx.WriteError(w, http.StatusBadGateway, "ai provider unavailable")
 		return
 	}
 
@@ -233,7 +239,7 @@ func (h *AIVehiclePaintPreviewHandler) ServeHTTP(w http.ResponseWriter, r *http.
 	sseW, ctx, err := stream.New(ctx, w, stream.WithFeatureID(vehiclepaintpreview.FeatureID))
 	if err != nil {
 		log.Error().Err(err).Msg("ai vehicle-paint-preview: stream.New failed (non-flushable writer)")
-		writeError(w, http.StatusInternalServerError, "streaming not supported")
+		httpx.WriteError(w, http.StatusInternalServerError, "streaming not supported")
 		return
 	}
 
@@ -290,6 +296,6 @@ func (h *AIVehiclePaintPreviewHandler) ServeHTTP(w http.ResponseWriter, r *http.
 	}
 }
 
-// Compile-time assertion: AIVehiclePaintPreviewHandler satisfies
+// Compile-time assertion: Handler satisfies
 // http.Handler.
-var _ http.Handler = (*AIVehiclePaintPreviewHandler)(nil)
+var _ http.Handler = (*Handler)(nil)

…ai_vehicle_paint_preview_handler_test.go internal/api/aivehpaint/handler_test.gointernal/api/ai_vehicle_paint_preview_handler_test.go renamed to internal/api/aivehpaint/handler_test.go internal/api/ai_vehicle_paint_preview_handler_test.go renamed to internal/api/aivehpaint/handler_test.go

@@ -15,10 +15,11 @@
 // vehicle-paint-preview`); duplicating that here would require a
 // live vehicles fixture.
 
-package api
+package aivehpaint
 
 import (
 	"bytes"
+	"context"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -29,6 +30,24 @@ import (
 	"github.com/ev-dev-labs/teslasync/internal/ai/guard"
 )
 
+// stubGuardSettings is a minimal in-memory guard.Settings used to
+// drive the off-mode contract test without a real DB.
+type stubGuardSettings struct {
+	mode string
+	on   map[string]bool
+}
+
+func (s *stubGuardSettings) AIMode(_ context.Context) (string, error) {
+	if s.mode == "" {
+		return "off", nil
+	}
+	return s.mode, nil
+}
+
+func (s *stubGuardSettings) AIFeatureEnabled(_ context.Context, id string) (bool, error) {
+	return s.on[id], nil
+}
+
 // TestVehiclePaintPreviewAIOffHidesPreviewTool is the load-bearing
 // off-mode contract proof for slice 0061. It mounts the AI
 // vehicle-paint-preview route through the guard with ai_mode='off'
@@ -147,43 +166,43 @@ func TestVehiclePaintPreviewAIOffHidesPreviewTool(t *testing.T) {
 	}
 }
 
-// TestAIVehiclePaintPreviewHandler_PanicsOnNilWiring asserts the
+// TestHandler_PanicsOnNilWiring asserts the
 // handler constructor refuses zero-valued dependencies. A wiring
 // bug at boot must surface as a panic, not as a nil-deref on first
 // request.
-func TestAIVehiclePaintPreviewHandler_PanicsOnNilWiring(t *testing.T) {
+func TestHandler_PanicsOnNilWiring(t *testing.T) {
 	t.Parallel()
 	cases := []struct {
 		name string
 		fn   func()
 	}{
-		{"all nil", func() { NewAIVehiclePaintPreviewHandler(nil, nil, nil, "") }},
+		{"all nil", func() { NewHandler(nil, nil, nil, "") }},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			defer func() {
 				if r := recover(); r == nil {
-					t.Fatalf("NewAIVehiclePaintPreviewHandler(%s) did not panic", tc.name)
+					t.Fatalf("NewHandler(%s) did not panic", tc.name)
 				}
 			}()
 			tc.fn()
 		})
 	}
 }
 
-// TestAIVehiclePaintPreviewHandler_RejectsBadVehicleID asserts the
+// TestHandler_RejectsBadVehicleID asserts the
 // URL parser refuses non-positive / non-numeric vehicleID values
 // BEFORE opening the SSE stream — a malformed URL must surface as
 // a JSON 400, not a half-opened stream that confuses the frontend.
-func TestAIVehiclePaintPreviewHandler_RejectsBadVehicleID(t *testing.T) {
+func TestHandler_RejectsBadVehicleID(t *testing.T) {
 	t.Parallel()
 
 	router := chi.NewRouter()
 	// Mount the URL parser through a minimal handler so chi's
-	// URLParam plumbing is in scope (parseAIVehiclePaintPreviewURL
+	// URLParam plumbing is in scope (parseURL
 	// calls chi.URLParam, which requires the route to be mounted).
 	router.Post("/api/v1/ai/vehicles/{vehicleID}/paint-preview/draft", func(w http.ResponseWriter, r *http.Request) {
-		_, _ = parseAIVehiclePaintPreviewURL(w, r)
+		_, _ = parseURL(w, r)
 	})
 
 	cases := []struct {
@@ -210,11 +229,11 @@ func TestAIVehiclePaintPreviewHandler_RejectsBadVehicleID(t *testing.T) {
 	}
 }
 
-// TestAIVehiclePaintPreviewHandler_RejectsBadBody asserts the body
+// TestHandler_RejectsBadBody asserts the body
 // parser validates the optional body BEFORE opening the SSE stream.
 // Empty body is allowed; malformed JSON or oversized style_hint
 // surfaces as a JSON 4xx.
-func TestAIVehiclePaintPreviewHandler_RejectsBadBody(t *testing.T) {
+func TestHandler_RejectsBadBody(t *testing.T) {
 	t.Parallel()
 
 	cases := []struct {
@@ -236,7 +255,7 @@ func TestAIVehiclePaintPreviewHandler_RejectsBadBody(t *testing.T) {
 			req := httptest.NewRequest(http.MethodPost, "/api/v1/ai/vehicles/7/paint-preview/draft", strings.NewReader(tc.body))
 			req.Header.Set("Content-Type", "application/json")
 
-			_, ok := parseAIVehiclePaintPreviewBody(rec, req)
+			_, ok := parseBody(rec, req)
 			if ok != tc.wantOK {
 				t.Errorf("ok = %v, want %v (body=%q, status=%d, response=%q)", ok, tc.wantOK, tc.body, rec.Code, rec.Body.String())
 			}
@@ -247,18 +266,18 @@ func TestAIVehiclePaintPreviewHandler_RejectsBadBody(t *testing.T) {
 	}
 }
 
-// TestAIVehiclePaintPreviewHandler_RejectsOversizedBody asserts the
+// TestHandler_RejectsOversizedBody asserts the
 // 16 KiB body cap is enforced before any further parsing. A request
 // body that exceeds the cap surfaces as 413.
-func TestAIVehiclePaintPreviewHandler_RejectsOversizedBody(t *testing.T) {
+func TestHandler_RejectsOversizedBody(t *testing.T) {
 	t.Parallel()
 
-	huge := `{"style_hint":"` + strings.Repeat("X", aiVehiclePaintPreviewMaxBodyBytes+128) + `"}`
+	huge := `{"style_hint":"` + strings.Repeat("X", maxBodyBytes+128) + `"}`
 	rec := httptest.NewRecorder()
 	req := httptest.NewRequest(http.MethodPost, "/api/v1/ai/vehicles/7/paint-preview/draft", strings.NewReader(huge))
 	req.Header.Set("Content-Type", "application/json")
 
-	_, ok := parseAIVehiclePaintPreviewBody(rec, req)
+	_, ok := parseBody(rec, req)
 	if ok {
 		t.Fatal("ok = true; want false for oversized body")
 	}

internal/api/router.go

@@ -40,6 +40,7 @@ import (
 	aitirepress "github.com/ev-dev-labs/teslasync/internal/api/aitirepress"
 	aitripplanllm "github.com/ev-dev-labs/teslasync/internal/api/aitripplanllm"
 	aivampire "github.com/ev-dev-labs/teslasync/internal/api/aivampire"
+	"github.com/ev-dev-labs/teslasync/internal/api/aivehpaint"
 	aiyir "github.com/ev-dev-labs/teslasync/internal/api/aiyir"
 	apialertmsg "github.com/ev-dev-labs/teslasync/internal/api/alertmsg"
 	apialerts "github.com/ev-dev-labs/teslasync/internal/api/alerts"
@@ -2726,7 +2727,7 @@ func NewRouter(db *database.DB, teslaClient *tesla.Client, mqttClient *mqtt.Clie
 	// beyond constructor inputs. Must be constructed AFTER the
 	// tool registration above so the dispatcher can resolve the
 	// strategy's allowedTools at boot.
-	aiVehiclePaintPreviewHandler := NewAIVehiclePaintPreviewHandler(
+	aiVehiclePaintPreviewHandler := aivehpaint.NewHandler(
 		aiRegistry,
 		aiToolRegistry,
 		vehiclepaintpreview.New(),