Feature 12: Regular dinners and onboarding (#94)

Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com>

internal/server/aisettings_test.go

@@ -28,7 +28,7 @@ const (
 func newAIRouter(t *testing.T) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t),
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t),
 		newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/dinners.go

@@ -0,0 +1,251 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+)
+
+// maxDinnerBody bounds a POST or PATCH /dinners request body.
+const maxDinnerBody = 16 << 10
+
+// maxGroundBody bounds a POST /dinners/{id}/ground body, which may carry a
+// manual recipe of dinners.MaxManualLines lines of each kind.
+const maxGroundBody = 512 << 10
+
+// dinnerCreate is the POST /dinners body: a name, with or without a
+// recipe_url.
+type dinnerCreate struct {
+	Name      *string `json:"name"`
+	RecipeURL *string `json:"recipe_url"`
+}
+
+// dinnerPatch is the PATCH /dinners/{id} body. Every field is optional;
+// unknown fields and null values are refused.
+type dinnerPatch struct {
+	Name         *string `json:"name"`
+	Method       *string `json:"method"`
+	MinutesTotal *int    `json:"minutes_total"`
+	Difficulty   *string `json:"difficulty"`
+}
+
+type dinnerList struct {
+	Dinners []dinners.Dinner `json:"dinners"`
+}
+
+// dinnerGround is the POST /dinners/{id}/ground body: exactly one of
+// candidate_id, recipe_url and manual.
+type dinnerGround struct {
+	CandidateID *string             `json:"candidate_id"`
+	RecipeURL   *string             `json:"recipe_url"`
+	Manual      *dinnerManualRecipe `json:"manual"`
+}
+
+type dinnerManualRecipe struct {
+	Ingredients []string `json:"ingredients"`
+	Steps       []string `json:"steps"`
+	Minutes     *int     `json:"minutes"`
+	Method      *string  `json:"method"`
+}
+
+type candidateList struct {
+	Candidates []dinners.Candidate `json:"candidates"`
+}
+
+// getDinners answers GET /dinners?status=regular|quest_log.
+func getDinners(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		list, err := svc.List(r.Context(), r.URL.Query().Get("status"))
+		if err != nil {
+			writeDinnerError(w, r, logger, "list dinners", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, dinnerList{Dinners: list})
+	}
+}
+
+// postDinner adds a Regular, recording the session's actor as updated_by,
+// and answers 201 with it and its grounding_job_id without waiting for the
+// job. When the job cannot be enqueued it still answers 201, with the dinner
+// grounding_status failed and grounding_job_id null.
+func postDinner(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		body, err := decodePatch[dinnerCreate](http.MaxBytesReader(w, r.Body, maxDinnerBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		d, err := svc.CreateRegular(r.Context(), dinners.NewRegular(body), actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "create dinner", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusCreated, d)
+	}
+}
+
+// patchDinner edits a dinner, recording the session's actor as updated_by.
+func patchDinner(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		patch, err := decodePatch[dinnerPatch](http.MaxBytesReader(w, r.Body, maxDinnerBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		d, err := svc.Update(r.Context(), chi.URLParam(r, "id"), dinners.Patch(patch), actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "update dinner", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// getDinnerCandidates answers GET /dinners/{id}/recipe-candidates with up
+// to dinners.MaxCandidates recipe pages for the dinner's name.
+func getDinnerCandidates(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		list, err := svc.Candidates(r.Context(), chi.URLParam(r, "id"))
+		if err != nil {
+			writeDinnerError(w, r, logger, "list recipe candidates", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, candidateList{Candidates: list})
+	}
+}
+
+// postDinnerGround grounds a dinner by hand in a candidate, a pasted link
+// or a recipe typed in, recording the session's actor as updated_by.
+func postDinnerGround(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		body, err := decodePatch[dinnerGround](http.MaxBytesReader(w, r.Body, maxGroundBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		fix := dinners.Fix{CandidateID: body.CandidateID, RecipeURL: body.RecipeURL}
+		if body.Manual != nil {
+			m := dinners.ManualRecipe(*body.Manual)
+			fix.Manual = &m
+		}
+		d, err := svc.Ground(r.Context(), chi.URLParam(r, "id"), fix, actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "ground dinner", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// deleteDinner archives a dinner; the row is never deleted.
+func deleteDinner(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		d, err := svc.Archive(r.Context(), chi.URLParam(r, "id"), actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "archive dinner", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// postDinnerFavorite toggles a dinner's is_favorite.
+func postDinnerFavorite(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		d, err := svc.ToggleFavorite(r.Context(), chi.URLParam(r, "id"), actor.Subject)
+		if err != nil {
+			writeDinnerError(w, r, logger, "toggle dinner favorite", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// actorOrFail returns the session's actor, or answers 500 when the request
+// has none, which behind requireSession is a wiring bug.
+func actorOrFail(w http.ResponseWriter, r *http.Request, logger *slog.Logger) (auth.Actor, bool) {
+	actor, ok := auth.ActorFrom(r.Context())
+	if !ok {
+		logger.ErrorContext(r.Context(), r.Method+" "+r.URL.Path+" without a session")
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	}
+	return actor, ok
+}
+
+// writeDinnerError maps a dinners.Service error to its API error. A page
+// that cannot ground the dinner is 422 ungroundable; recipe search not set
+// up is 409 not_configured; a search or model failure is 502; grounding by
+// hand that runs past dinners.GroundTimeout is 504 ground_timeout; grounding
+// an archived dinner is 409 dinner_archived and one changed while grounding
+// 409 ground_conflict. Any other grounding failure, by candidate, link or
+// manual recipe, wraps dinners.ErrGroundFailed and is 500, logged by reason
+// and dinner id only.
+func writeDinnerError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, action string, err error) {
+	var invalid *dinners.ValidationError
+	var dup *dinners.DuplicateError
+	var ungroundable *recipes.ErrUngroundable
+	switch {
+	case errors.As(err, &ungroundable):
+		// The reasons quote dependency errors, so they are neither returned
+		// nor logged.
+		writeError(w, r, logger, http.StatusUnprocessableEntity, "ungroundable", "no usable recipe was found at that link")
+	case errors.Is(err, recipes.ErrSearchNotConfigured):
+		writeError(w, r, logger, http.StatusConflict, "not_configured", "recipe search is not configured")
+	case errors.Is(err, recipes.ErrSearchFailed):
+		// The error may quote the search provider's response, so only the
+		// reason is logged.
+		logger.WarnContext(r.Context(), action, "reason", "search_failed")
+		writeError(w, r, logger, http.StatusBadGateway, "search_failed", "recipe search failed")
+	case errors.Is(err, recipes.ErrNormalizeFailed):
+		logger.WarnContext(r.Context(), action, "reason", "normalize_recipe failed")
+		writeError(w, r, logger, http.StatusBadGateway, "ai_failed", "the AI provider failed to read the recipe")
+	case errors.Is(err, dinners.ErrGroundFailed):
+		// The error may quote the pasted link, which can carry a personal
+		// token, and dependency errors, so only the reason and dinner are
+		// logged.
+		logger.ErrorContext(r.Context(), action, "reason", "ground_failed", "dinner_id", chi.URLParam(r, "id"))
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	case errors.Is(err, dinners.ErrArchived):
+		writeError(w, r, logger, http.StatusConflict, "dinner_archived", "the dinner is archived")
+	case errors.Is(err, dinners.ErrGroundConflict):
+		writeError(w, r, logger, http.StatusConflict, "ground_conflict", "the dinner changed while its recipe was grounding; reload and try again")
+	case errors.Is(err, dinners.ErrGroundTimeout):
+		logger.WarnContext(r.Context(), action, "reason", "ground_timeout")
+		writeError(w, r, logger, http.StatusGatewayTimeout, "ground_timeout", "grounding the recipe took too long; try again")
+	case errors.As(err, &invalid):
+		writeError(w, r, logger, http.StatusBadRequest, "invalid_dinner", invalid.Error())
+	case errors.As(err, &dup):
+		writeError(w, r, logger, http.StatusConflict, "duplicate_dinner", dup.Error())
+	case errors.Is(err, dinners.ErrNotFound):
+		writeError(w, r, logger, http.StatusNotFound, "not_found", "dinner not found")
+	default:
+		logger.ErrorContext(r.Context(), action, "error", err)
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	}
+}

internal/server/dinners_test.go

@@ -0,0 +1,616 @@
+package server
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"testing/fstest"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+const dinnersPath = "/api/v1/dinners"
+
+// newDinnersRouter returns a router whose dinners service runs over the
+// returned store. Its job runner is not started, so grounding jobs stay
+// queued.
+func newDinnersRouter(t *testing.T) (http.Handler, *store.Store) {
+	t.Helper()
+	e := newDinnersEnv(t)
+	return e.h, e.st
+}
+
+// dinnersEnv is a router whose dinners service, job runner and grounder
+// share one store, grounding with fake search, pages, images and model.
+type dinnersEnv struct {
+	h      http.Handler
+	st     *store.Store
+	runner *jobs.Runner
+	search *recipestest.Search
+	pages  *recipestest.Pages
+	images *recipestest.Images
+	model  *llm.Fake
+	// logs holds everything the router and services log.
+	logs *logBuffer
+}
+
+// logBuffer is a bytes.Buffer safe for concurrent log writes.
+type logBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (b *logBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+func (b *logBuffer) String() string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.String()
+}
+
+func newDinnersEnv(t *testing.T) *dinnersEnv {
+	t.Helper()
+	st := newTestStore(t)
+	e := &dinnersEnv{
+		st:     st,
+		search: &recipestest.Search{Results: map[string][]recipes.Candidate{}},
+		pages:  &recipestest.Pages{Bodies: map[string][]byte{}},
+		images: &recipestest.Images{JPEGs: map[string][]byte{}},
+		model:  &llm.Fake{},
+		logs:   &logBuffer{},
+	}
+	logger := slog.New(slog.NewTextHandler(e.logs, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.runner = runner
+	g := recipestest.NewGrounder(t, st, t.TempDir(), e.search, e.pages, e.images, e.model)
+	svc, err := dinners.NewService(st, g, runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.h, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t),
+		svc, runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return e
+}
+
+// start starts the env's job runner, stopping it when the test ends.
+func (e *dinnersEnv) start(t *testing.T) {
+	t.Helper()
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := e.runner.Start(ctx); err != nil {
+		cancel()
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		cancel()
+		e.runner.Wait()
+	})
+}
+
+// callDinners sends a signed-in request with body (none when empty).
+func callDinners(t *testing.T, h http.Handler, method, target, body string) (*httptest.ResponseRecorder, map[string]any) {
+	t.Helper()
+	var r io.Reader
+	if body != "" {
+		r = strings.NewReader(body)
+	}
+	return serve(t, h, signedIn(method, target, r))
+}
+
+// createDinner adds a Regular and returns its id.
+func createDinner(t *testing.T, h http.Handler, body string) string {
+	t.Helper()
+	rec, got := callDinners(t, h, http.MethodPost, dinnersPath, body)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("POST %s = %d: %s", body, rec.Code, rec.Body)
+	}
+	return got["id"].(string)
+}
+
+// listNames returns the names GET /dinners?status=status lists, in order.
+func listNames(t *testing.T, h http.Handler, status string) []string {
+	t.Helper()
+	rec, body := callDinners(t, h, http.MethodGet, dinnersPath+"?status="+status, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET status=%s = %d: %s", status, rec.Code, rec.Body)
+	}
+	list, ok := body["dinners"].([]any)
+	if !ok {
+		t.Fatalf("GET status=%s has no dinners list: %v", status, body)
+	}
+	names := make([]string, len(list))
+	for i, d := range list {
+		names[i] = d.(map[string]any)["name"].(string)
+	}
+	return names
+}
+
+func TestCreateDinnerByName(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"  Chicken Tikka Masala "}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("status = %d, want 201: %s", rec.Code, rec.Body)
+	}
+	for k, v := range map[string]any{
+		"name":             "Chicken Tikka Masala",
+		"status":           "regular",
+		"origin":           "regular",
+		"grounding_status": "pending",
+		"is_favorite":      false,
+		"photo_url":        nil,
+		"method":           nil,
+		"minutes_total":    nil,
+		"difficulty":       nil,
+		"updated_by":       testSession.Subject,
+	} {
+		if got, ok := body[k]; !ok || got != v {
+			t.Errorf("%s = %#v (present %v), want %#v", k, got, ok, v)
+		}
+	}
+	if got, ok := body["recipe_url"]; ok {
+		t.Errorf("recipe_url = %#v, want no recipe_url in a dinner response", got)
+	}
+	var normalized, updatedBy string
+	if err := st.Reader.QueryRow(`SELECT normalized_name, updated_by FROM dinners WHERE id = ?`, body["id"]).Scan(&normalized, &updatedBy); err != nil {
+		t.Fatal(err)
+	}
+	if normalized != "chicken tikka masala" || updatedBy != testSession.Subject {
+		t.Errorf("stored normalized_name, updated_by = %q, %q", normalized, updatedBy)
+	}
+}
+
+func TestCreateDinnerByURL(t *testing.T) {
+	t.Parallel()
+	router, _ := newDinnersRouter(t)
+
+	link := "https://www.example.com/recipes/12345/beef-and-broccoli-stir-fry/"
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Stir fry night","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("status = %d, want 201: %s", rec.Code, rec.Body)
+	}
+	for k, v := range map[string]any{
+		"name":             "Stir fry night",
+		"status":           "regular",
+		"origin":           "regular",
+		"grounding_status": "pending",
+		"updated_by":       testSession.Subject,
+	} {
+		if body[k] != v {
+			t.Errorf("%s = %#v, want %#v", k, body[k], v)
+		}
+	}
+	// The link stays on the server for grounding; responses never carry it.
+	if got, ok := body["recipe_url"]; ok {
+		t.Errorf("recipe_url = %#v, want no recipe_url in a dinner response", got)
+	}
+
+	// The same link again is a duplicate even though its name would differ.
+	rec, body = callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Something else entirely"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("unrelated name = %d: %s", rec.Code, rec.Body)
+	}
+	rec, body = callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Beef and broccoli","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusConflict || errorCode(body) != "duplicate_dinner" {
+		t.Errorf("same link again = %d %v, want 409 duplicate_dinner", rec.Code, body)
+	}
+
+	for _, tc := range []struct{ name, body string }{
+		{"plain http", `{"name":"Chili","recipe_url":"http://example.com/recipes/chili"}`},
+		{"not a URL", `{"name":"Chili","recipe_url":"chili"}`},
+		{"credentials", `{"name":"Chili","recipe_url":"https://me:pw@example.com/recipes/chili"}`},
+		{"link without a name", `{"recipe_url":"https://example.com/recipes/chili"}`},
+		{"filler name with a link", `{"name":"The Best Easy Recipe","recipe_url":"https://example.com/recipes/chili"}`},
+		{"neither field", `{}`},
+	} {
+		rec, body := callDinners(t, router, http.MethodPost, dinnersPath, tc.body)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != "invalid_dinner" {
+			t.Errorf("%s: %d %v, want 400 invalid_dinner", tc.name, rec.Code, body)
+		}
+	}
+}
+
+// TestDinnerResponsesHideRecipeURL: a pasted link may carry a personal
+// token, so neither the create response nor a later list read shows any
+// part of it, while the stored link still awaits grounding.
+func TestDinnerResponsesHideRecipeURL(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+
+	const link = "https://c.example/recipes/stew?access_token=personal-token-abc123"
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Stew","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("status = %d, want 201: %s", rec.Code, rec.Body)
+	}
+	created := rec.Body.String()
+	rec, _ = callDinners(t, router, http.MethodGet, dinnersPath+"?status=regular", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET status=regular = %d: %s", rec.Code, rec.Body)
+	}
+	for _, resp := range []struct{ name, body string }{{"create", created}, {"list", rec.Body.String()}} {
+		for _, secret := range []string{link, "c.example", "access_token", "personal-token-abc123", "recipe_url"} {
+			if strings.Contains(resp.body, secret) {
+				t.Errorf("%s response contains %q: %s", resp.name, secret, resp.body)
+			}
+		}
+	}
+
+	var stored string
+	if err := st.Reader.QueryRow(`SELECT recipe_url FROM dinners WHERE id = ?`, body["id"]).Scan(&stored); err != nil {
+		t.Fatal(err)
+	}
+	if stored != link {
+		t.Errorf("stored recipe_url = %q, want %q kept for grounding", stored, link)
+	}
+}
+
+// TestDinnerResponsesHideTokenInLinkPath: a personal token can sit
+// anywhere in a link's path, even as plain letters, so a dinner added from
+// a link is named only by the household and neither the create response, a
+// later list read nor the duplicate error for the same link shows any of
+// the link.
+func TestDinnerResponsesHideTokenInLinkPath(t *testing.T) {
+	t.Parallel()
+	router, _ := newDinnersRouter(t)
+
+	const link = "https://c.example/recipes/stew-key-abcdefghijklmno"
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Sunday stew","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("status = %d, want 201: %s", rec.Code, rec.Body)
+	}
+	if body["name"] != "Sunday stew" {
+		t.Errorf("name = %v, want Sunday stew", body["name"])
+	}
+	created := rec.Body.String()
+	rec, _ = callDinners(t, router, http.MethodGet, dinnersPath+"?status=regular", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET status=regular = %d: %s", rec.Code, rec.Body)
+	}
+	listed := rec.Body.String()
+	rec, _ = callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Beef stew","recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusConflict {
+		t.Fatalf("same link again = %d, want 409: %s", rec.Code, rec.Body)
+	}
+	for _, resp := range []struct{ name, body string }{{"create", created}, {"list", listed}, {"duplicate", rec.Body.String()}} {
+		lower := strings.ToLower(resp.body)
+		for _, secret := range []string{"c.example", "recipes", "key", "abcdefghijklmno"} {
+			if strings.Contains(lower, secret) {
+				t.Errorf("%s response contains %q: %s", resp.name, secret, resp.body)
+			}
+		}
+	}
+}
+
+func TestCreateDinnerDuplicate(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	createDinner(t, router, `{"name":"Chicken Tikka Masala"}`)
+
+	for _, name := range []string{
+		"chicken tikka masala",
+		"Easy Chicken Tikka-Masala!",
+		"The Best Homemade Chicken Tikka Masala Recipe",
+	} {
+		rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"`+name+`"}`)
+		if rec.Code != http.StatusConflict || errorCode(body) != "duplicate_dinner" {
+			t.Errorf("%q: %d %v, want 409 duplicate_dinner", name, rec.Code, body)
+		}
+	}
+	// A name repeating the dish is a duplicate with a link too.
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath, `{"name":"Chicken tikka masala","recipe_url":"https://example.com/other-curry.html"}`)
+	if rec.Code != http.StatusConflict {
+		t.Errorf("named duplicate with a link = %d %v, want 409", rec.Code, body)
+	}
+
+	var n int
+	if err := st.Reader.QueryRow(`SELECT count(*) FROM dinners`).Scan(&n); err != nil {
+		t.Fatal(err)
+	}
+	if n != 1 {
+		t.Errorf("dinners rows = %d, want 1", n)
+	}
+
+	// A different dish sharing words is not a duplicate.
+	createDinner(t, router, `{"name":"Chicken Tikka Wraps"}`)
+}
+
+func TestCreateDinnerRejected(t *testing.T) {
+	t.Parallel()
+	router, _ := newDinnersRouter(t)
+	for _, tc := range []struct{ name, body, code string }{
+		{"empty name", `{"name":"   "}`, "invalid_dinner"},
+		{"filler only", `{"name":"The Best Easy Recipe"}`, "invalid_dinner"},
+		{"too long", `{"name":"` + strings.Repeat("x", dinners.MaxNameChars+1) + `"}`, "invalid_dinner"},
+		{"null name", `{"name":null}`, "invalid_request"},
+		{"unknown field", `{"name":"Chili","status":"quest_log"}`, "invalid_request"},
+		{"not an object", `"Chili"`, "invalid_request"},
+	} {
+		rec, body := callDinners(t, router, http.MethodPost, dinnersPath, tc.body)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != tc.code {
+			t.Errorf("%s: %d %v, want 400 %s", tc.name, rec.Code, body, tc.code)
+		}
+	}
+}
+
+func TestListDinnersFiltersByStatus(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	tacos := createDinner(t, router, `{"name":"Tacos"}`)
+	createDinner(t, router, `{"name":"Lasagna"}`)
+	pho := createDinner(t, router, `{"name":"Pho"}`)
+	gone := createDinner(t, router, `{"name":"Meatloaf"}`)
+
+	ctx := context.Background()
+	if _, err := st.Writer.ExecContext(ctx, `UPDATE dinners SET status = 'quest_log', origin = 'side_quest' WHERE id = ?`, pho); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := st.Writer.ExecContext(ctx,
+		`INSERT INTO photos (id, source_url, local_path, width, height, sha256, fetched_at, created_at, updated_at)
+		 VALUES ('photo1', 'https://example.com/tacos.jpg', 'media/photos/photo1', 1200, 800, 'abc', 't', 't', 't')`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := st.Writer.ExecContext(ctx, `UPDATE dinners SET photo_id = 'photo1', grounding_status = 'grounded' WHERE id = ?`, tacos); err != nil {
+		t.Fatal(err)
+	}
+	if rec, _ := callDinners(t, router, http.MethodDelete, dinnersPath+"/"+gone, ""); rec.Code != http.StatusOK {
+		t.Fatalf("DELETE = %d", rec.Code)
+	}
+
+	if got := strings.Join(listNames(t, router, "regular"), ","); got != "Lasagna,Tacos" {
+		t.Errorf("regular = %s, want Lasagna,Tacos", got)
+	}
+	if got := strings.Join(listNames(t, router, "quest_log"), ","); got != "Pho" {
+		t.Errorf("quest_log = %s, want Pho", got)
+	}
+
+	_, body := callDinners(t, router, http.MethodGet, dinnersPath+"?status=regular", "")
+	for _, d := range body["dinners"].([]any) {
+		d := d.(map[string]any)
+		switch d["name"] {
+		case "Tacos":
+			if d["photo_url"] != "/media/photos/photo1-400.jpg" || d["grounding_status"] != "grounded" {
+				t.Errorf("Tacos photo_url, grounding_status = %v, %v", d["photo_url"], d["grounding_status"])
+			}
+		case "Lasagna":
+			if d["photo_url"] != nil || d["grounding_status"] != "pending" {
+				t.Errorf("Lasagna photo_url, grounding_status = %v, %v", d["photo_url"], d["grounding_status"])
+			}
+		}
+	}
+
+	// An empty list is [] rather than null.
+	empty, _ := newDinnersRouter(t)
+	rec, _ := callDinners(t, empty, http.MethodGet, dinnersPath+"?status=regular", "")
+	if got := rec.Body.String(); got != `{"dinners":[]}` {
+		t.Errorf("empty list = %s", got)
+	}
+
+	for _, q := range []string{"", "?status=archived", "?status=suggested", "?status=bogus"} {
+		rec, body := callDinners(t, router, http.MethodGet, dinnersPath+q, "")
+		if rec.Code != http.StatusBadRequest || errorCode(body) != "invalid_dinner" {
+			t.Errorf("GET %q = %d %v, want 400 invalid_dinner", q, rec.Code, body)
+		}
+	}
+}
+
+func TestPatchDinner(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Chili"}`)
+	createDinner(t, router, `{"name":"Pot Roast"}`)
+	if _, err := st.Writer.Exec(`UPDATE dinners SET updated_by = 'someone-else' WHERE id = ?`, id); err != nil {
+		t.Fatal(err)
+	}
+
+	rec, body := callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id,
+		`{"name":"White Chicken Chili","method":"crockpot","minutes_total":480,"difficulty":"easy"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d: %s", rec.Code, rec.Body)
+	}
+	for k, v := range map[string]any{
+		"name":          "White Chicken Chili",
+		"method":        "crockpot",
+		"minutes_total": float64(480),
+		"difficulty":    "easy",
+		"status":        "regular",
+		"updated_by":    testSession.Subject,
+	} {
+		if body[k] != v {
+			t.Errorf("%s = %#v, want %#v", k, body[k], v)
+		}
+	}
+	var normalized string
+	if err := st.Reader.QueryRow(`SELECT normalized_name FROM dinners WHERE id = ?`, id).Scan(&normalized); err != nil {
+		t.Fatal(err)
+	}
+	if normalized != "white chicken chili" {
+		t.Errorf("normalized_name = %q", normalized)
+	}
+
+	// A partial patch leaves the other fields.
+	rec, body = callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id, `{"difficulty":"medium"}`)
+	if rec.Code != http.StatusOK || body["method"] != "crockpot" || body["difficulty"] != "medium" || body["name"] != "White Chicken Chili" {
+		t.Errorf("partial patch = %d %v", rec.Code, body)
+	}
+	// Renaming to its own name, respelled, is not a duplicate of itself.
+	if rec, body := callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id, `{"name":"Easy white chicken chili"}`); rec.Code != http.StatusOK {
+		t.Errorf("self rename = %d %v", rec.Code, body)
+	}
+	// Renaming onto another dinner is.
+	rec, body = callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id, `{"name":"The Best Pot Roast"}`)
+	if rec.Code != http.StatusConflict || errorCode(body) != "duplicate_dinner" {
+		t.Errorf("rename onto Pot Roast = %d %v, want 409", rec.Code, body)
+	}
+}
+
+func TestPatchDinnerValidation(t *testing.T) {
+	t.Parallel()
+	router, _ := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Chili"}`)
+
+	for _, tc := range []struct {
+		name, body, code, in string
+	}{
+		{"bad method", `{"method":"microwave"}`, "invalid_dinner", "method"},
+		{"crock pot spelling", `{"method":"crock pot"}`, "invalid_dinner", "method"},
+		{"bad difficulty", `{"difficulty":"expert"}`, "invalid_dinner", "difficulty"},
+		{"zero minutes", `{"minutes_total":0}`, "invalid_dinner", "minutes_total"},
+		{"negative minutes", `{"minutes_total":-5}`, "invalid_dinner", "minutes_total"},
+		{"too many minutes", `{"minutes_total":1441}`, "invalid_dinner", "minutes_total"},
+		{"empty name", `{"name":""}`, "invalid_dinner", "name"},
+		{"every problem", `{"method":"x","difficulty":"y","minutes_total":0}`, "invalid_dinner", "method: must be one of stovetop, oven, crockpot, grill, other; minutes_total"},
+		{"empty patch", `{}`, "invalid_dinner", "no fields"},
+		{"fractional minutes", `{"minutes_total":30.5}`, "invalid_request", "minutes_total"},
+		{"string minutes", `{"minutes_total":"30"}`, "invalid_request", "minutes_total"},
+		{"null method", `{"method":null}`, "invalid_request", "method"},
+		{"read-only field", `{"status":"archived"}`, "invalid_request", "status"},
+		{"favorite field", `{"is_favorite":true}`, "invalid_request", "is_favorite"},
+	} {
+		rec, body := callDinners(t, router, http.MethodPatch, dinnersPath+"/"+id, tc.body)
+		msg, _ := body["error"].(map[string]any)["message"].(string)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != tc.code || !strings.Contains(msg, tc.in) {
+			t.Errorf("%s: %d %v, want 400 %s containing %q", tc.name, rec.Code, body, tc.code, tc.in)
+		}
+	}
+
+	_, body := callDinners(t, router, http.MethodGet, dinnersPath+"?status=regular", "")
+	d := body["dinners"].([]any)[0].(map[string]any)
+	if d["method"] != nil || d["difficulty"] != nil || d["minutes_total"] != nil || d["name"] != "Chili" {
+		t.Errorf("a rejected patch changed the dinner: %v", d)
+	}
+
+	rec, body := callDinners(t, router, http.MethodPatch, dinnersPath+"/nope", `{"method":"oven"}`)
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown id = %d %v, want 404", rec.Code, body)
+	}
+}
+
+func TestDeleteDinnerArchives(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Shepherd's Pie"}`)
+	if _, err := st.Writer.Exec(`UPDATE dinners SET updated_by = 'someone-else' WHERE id = ?`, id); err != nil {
+		t.Fatal(err)
+	}
+
+	rec, body := callDinners(t, router, http.MethodDelete, dinnersPath+"/"+id, "")
+	if rec.Code != http.StatusOK || body["status"] != "archived" || body["updated_by"] != testSession.Subject {
+		t.Fatalf("DELETE = %d %v", rec.Code, body)
+	}
+	var status, name, updatedBy string
+	if err := st.Reader.QueryRow(`SELECT status, name, updated_by FROM dinners WHERE id = ?`, id).Scan(&status, &name, &updatedBy); err != nil {
+		t.Fatalf("archived row is gone: %v", err)
+	}
+	if status != "archived" || name != "Shepherd's Pie" || updatedBy != testSession.Subject {
+		t.Errorf("row = %s %q %s", status, name, updatedBy)
+	}
+	if got := listNames(t, router, "regular"); len(got) != 0 {
+		t.Errorf("regular after archive = %v", got)
+	}
+	// An archived name may be added again.
+	createDinner(t, router, `{"name":"Shepherds Pie"}`)
+
+	rec, body = callDinners(t, router, http.MethodDelete, dinnersPath+"/nope", "")
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown id = %d %v, want 404", rec.Code, body)
+	}
+}
+
+func TestFavoriteDinnerToggles(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Fish Tacos"}`)
+	if _, err := st.Writer.Exec(`UPDATE dinners SET updated_by = 'someone-else' WHERE id = ?`, id); err != nil {
+		t.Fatal(err)
+	}
+
+	for _, want := range []bool{true, false, true} {
+		rec, body := callDinners(t, router, http.MethodPost, dinnersPath+"/"+id+"/favorite", "")
+		if rec.Code != http.StatusOK || body["is_favorite"] != want || body["updated_by"] != testSession.Subject {
+			t.Fatalf("favorite = %d %v, want is_favorite %v", rec.Code, body, want)
+		}
+	}
+	var fav int
+	if err := st.Reader.QueryRow(`SELECT is_favorite FROM dinners WHERE id = ?`, id).Scan(&fav); err != nil {
+		t.Fatal(err)
+	}
+	if fav != 1 {
+		t.Errorf("stored is_favorite = %d, want 1", fav)
+	}
+
+	rec, body := callDinners(t, router, http.MethodPost, dinnersPath+"/nope/favorite", "")
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown id = %d %v, want 404", rec.Code, body)
+	}
+}
+
+// TestDinnerWritesRequireCSRF sends every dinners write without the CSRF
+// header and with a wrong one; each is refused and changes nothing.
+func TestDinnerWritesRequireCSRF(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	id := createDinner(t, router, `{"name":"Chili"}`)
+
+	var before string
+	snapshot := `SELECT group_concat(id || name || status || is_favorite || coalesce(method, '') || updated_at, '|') FROM dinners`
+	if err := st.Reader.QueryRow(snapshot).Scan(&before); err != nil {
+		t.Fatal(err)
+	}
+
+	writes := []struct{ method, target, body string }{
+		{http.MethodPost, dinnersPath, `{"name":"Lasagna"}`},
+		{http.MethodPatch, dinnersPath + "/" + id, `{"method":"oven"}`},
+		{http.MethodDelete, dinnersPath + "/" + id, ""},
+		{http.MethodPost, dinnersPath + "/" + id + "/favorite", ""},
+	}
+	for _, w := range writes {
+		for _, header := range []*string{nil, ptr("wrong-token")} {
+			req := httptest.NewRequest(w.method, w.target, strings.NewReader(w.body))
+			req.AddCookie(validSessionCookie)
+			if header != nil {
+				req.Header.Set(CSRFHeader, *header)
+			}
+			rec, body := serve(t, router, req)
+			if rec.Code != http.StatusForbidden || errorCode(body) != "csrf" {
+				t.Errorf("%s %s (header %v) = %d %v, want 403 csrf", w.method, w.target, header != nil, rec.Code, body)
+			}
+		}
+	}
+
+	var after string
+	if err := st.Reader.QueryRow(snapshot).Scan(&after); err != nil {
+		t.Fatal(err)
+	}
+	if after != before {
+		t.Errorf("refused writes changed dinners:\n before %s\n after  %s", before, after)
+	}
+
+	// Without a session, the list is 401 too.
+	req := httptest.NewRequest(http.MethodGet, dinnersPath+"?status=regular", nil)
+	if rec, body := serve(t, router, req); rec.Code != http.StatusUnauthorized || errorCode(body) != "unauthenticated" {
+		t.Errorf("GET without a session = %d %v, want 401", rec.Code, body)
+	}
+}
+
+func ptr[T any](v T) *T { return &v }

internal/server/grounding_test.go

@@ -0,0 +1,412 @@
+package server
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+)
+
+// Fixture pages: two curries found by searching "Chicken curry" and a stew
+// at a pasted link.
+const (
+	curryPage  = "https://a.example/chicken-curry"
+	curry2Page = "https://b.example/curry"
+	stewPage   = "https://c.example/recipes/beef-stew"
+)
+
+// withRecipes adds the fixture pages, their photos and the search for
+// "Chicken curry" to e.
+func (e *dinnersEnv) withRecipes(t *testing.T) *dinnersEnv {
+	t.Helper()
+	e.search.Results["Chicken curry"] = []recipes.Candidate{{URL: curryPage}, {URL: curry2Page}}
+	e.pages.Bodies[curryPage] = recipestest.RecipePage("Chicken Curry", "Curry House", "https://a.example/curry.jpg", 40)
+	e.pages.Bodies[curry2Page] = recipestest.RecipePage("Weeknight Curry", "B Kitchen", "https://b.example/curry.jpg", 25)
+	e.pages.Bodies[stewPage] = recipestest.RecipePage("Beef Stew", "Stew Co", "https://c.example/stew.jpg", 150)
+	e.images.JPEGs["https://a.example/curry.jpg"] = recipestest.JPEG(t, 400, 320, 1)
+	e.images.JPEGs["https://b.example/curry.jpg"] = recipestest.JPEG(t, 400, 320, 2)
+	e.images.JPEGs["https://c.example/stew.jpg"] = recipestest.JPEG(t, 400, 320, 3)
+	return e
+}
+
+// waitJob polls GET /jobs/{id} until the job ends and returns its body.
+func waitJob(t *testing.T, h http.Handler, id string) map[string]any {
+	t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for {
+		rec, body := callDinners(t, h, http.MethodGet, "/api/v1/jobs/"+id, "")
+		if rec.Code != http.StatusOK {
+			t.Fatalf("GET job = %d: %s", rec.Code, rec.Body)
+		}
+		if s := body["status"]; s == "succeeded" || s == "failed" {
+			return body
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job %s never finished; last %v", id, body)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
+// listedDinner returns dinner id as GET /dinners?status=regular lists it.
+func listedDinner(t *testing.T, h http.Handler, id string) map[string]any {
+	t.Helper()
+	rec, body := callDinners(t, h, http.MethodGet, dinnersPath+"?status=regular", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET dinners = %d: %s", rec.Code, rec.Body)
+	}
+	for _, d := range body["dinners"].([]any) {
+		if d := d.(map[string]any); d["id"] == id {
+			return d
+		}
+	}
+	t.Fatalf("dinner %s not listed", id)
+	return nil
+}
+
+func TestPostDinnerReturnsBeforeGroundingCompletes(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	e.search.Gate = make(chan struct{})
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	e.start(t)
+
+	rec, created := callDinners(t, e.h, http.MethodPost, dinnersPath, `{"name":"Chicken curry"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	jobID, _ := created["grounding_job_id"].(string)
+	if created["grounding_status"] != "pending" || created["grounding_error"] != nil || jobID == "" {
+		t.Fatalf("created = %v, want pending with a grounding_job_id", created)
+	}
+	// The search is held, so grounding cannot have completed.
+	_, job := callDinners(t, e.h, http.MethodGet, "/api/v1/jobs/"+jobID, "")
+	if s := job["status"]; s != "queued" && s != "running" {
+		t.Fatalf("job right after POST = %v, want queued or running", job)
+	}
+	if d := listedDinner(t, e.h, created["id"].(string)); d["grounding_status"] != "pending" {
+		t.Fatalf("dinner right after POST = %v, want pending", d)
+	}
+
+	close(e.search.Gate)
+	job = waitJob(t, e.h, jobID)
+	if job["status"] != "succeeded" || job["kind"] != "ground_dinner" {
+		t.Fatalf("job = %v, want ground_dinner succeeded", job)
+	}
+	d := listedDinner(t, e.h, created["id"].(string))
+	photo, _ := d["photo_url"].(string)
+	if d["grounding_status"] != "grounded" || d["recipe_id"] == nil || !strings.HasSuffix(photo, "-400.jpg") ||
+		d["method"] != "stovetop" || d["minutes_total"] != 40.0 || d["difficulty"] != "easy" || d["grounding_error"] != nil {
+		t.Errorf("dinner = %v, want grounded with recipe, photo, method, minutes and difficulty", d)
+	}
+}
+
+func TestPostDinnerGroundingFailure(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	e.start(t)
+
+	rec, created := callDinners(t, e.h, http.MethodPost, dinnersPath, `{"name":"Nothing matches this"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	job := waitJob(t, e.h, created["grounding_job_id"].(string))
+	if job["status"] != "failed" || job["error"] != "no_recipe_found" {
+		t.Errorf("job = %v, want failed with no_recipe_found", job)
+	}
+	d := listedDinner(t, e.h, created["id"].(string))
+	if d["grounding_status"] != "failed" || d["grounding_error"] != "no_recipe_found" || d["recipe_id"] != nil {
+		t.Errorf("dinner = %v, want failed with no_recipe_found", d)
+	}
+}
+
+func TestGetRecipeCandidates(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`) // runner not started: stays pending
+
+	rec, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET = %d: %s", rec.Code, rec.Body)
+	}
+	list, _ := body["candidates"].([]any)
+	if len(list) != 2 {
+		t.Fatalf("candidates = %v, want 2", body)
+	}
+	first := list[0].(map[string]any)
+	want := map[string]any{
+		"candidate_id": curryPage,
+		"title":        "Chicken Curry",
+		"site_name":    "Curry House",
+		"photo_url":    nil,
+		"minutes":      40.0,
+	}
+	if len(first) != len(want) {
+		t.Errorf("candidate keys = %v, want exactly %v", first, want)
+	}
+	for k, v := range want {
+		if got, ok := first[k]; !ok || got != v {
+			t.Errorf("%s = %#v (present %v), want %#v", k, got, ok, v)
+		}
+	}
+
+	rec, body = callDinners(t, e.h, http.MethodGet, dinnersPath+"/nope/recipe-candidates", "")
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown dinner = %d %v, want 404", rec.Code, body)
+	}
+}
+
+func TestGetRecipeCandidatesSearchFails(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	// The provider's text must reach neither the response nor the logs.
+	const leak = "provider-said-token-abc123"
+	e.search.Err = fmt.Errorf("%w: %s", recipes.ErrSearchRefused, leak)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`)
+	rec, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	if rec.Code != http.StatusBadGateway || errorCode(body) != "search_failed" {
+		t.Errorf("GET = %d %v, want 502 search_failed", rec.Code, body)
+	}
+	if strings.Contains(rec.Body.String(), leak) {
+		t.Errorf("response quotes the provider: %s", rec.Body)
+	}
+	logs := e.logs.String()
+	if strings.Contains(logs, leak) || !strings.Contains(logs, "reason=search_failed") {
+		t.Errorf("logs = %q, want reason=search_failed and no provider text", logs)
+	}
+}
+
+func TestPostGroundViaCandidate(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`)
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 25))
+
+	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"candidate_id":"`+curry2Page+`"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	photo, _ := d["photo_url"].(string)
+	if d["grounding_status"] != "grounded" || d["recipe_id"] == nil || photo == "" ||
+		d["method"] != "stovetop" || d["minutes_total"] != 25.0 || d["difficulty"] != "easy" || d["updated_by"] != testSession.Subject {
+		t.Errorf("dinner = %v", d)
+	}
+	// The candidate is now stored, so it is offered with its photo.
+	_, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	for _, c := range body["candidates"].([]any) {
+		if c := c.(map[string]any); c["candidate_id"] == curry2Page && c["photo_url"] != photo {
+			t.Errorf("grounded candidate photo_url = %v, want %s", c["photo_url"], photo)
+		}
+	}
+}
+
+func TestPostGroundViaRecipeURL(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Sunday stew"}`)
+	e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+
+	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"recipe_url":"`+stewPage+`"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	if d["grounding_status"] != "grounded" || d["photo_url"] == nil || d["method"] != "oven" || d["minutes_total"] != 150.0 {
+		t.Errorf("dinner = %v", d)
+	}
+
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"recipe_url":"https://gone.example/soup"}`)
+	if rec.Code != http.StatusUnprocessableEntity || errorCode(body) != "ungroundable" || strings.Contains(rec.Body.String(), "gone.example") {
+		t.Errorf("unusable link = %d %v, want 422 ungroundable", rec.Code, body)
+	}
+}
+
+// TestPostGroundViaRecipeURLStorageFailure: a pasted link that fails for a
+// reason other than its recipe is a 500 logged by reason and dinner id,
+// never with the link, which can carry a personal token, or the dependency
+// error.
+func TestPostGroundViaRecipeURLStorageFailure(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	const token = "personal-token-abc123"
+	link := stewPage + "?access_token=" + token
+	e.pages.Bodies[link] = e.pages.Bodies[stewPage]
+	id := createDinner(t, e.h, `{"name":"Sunday stew"}`)
+	e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+	if _, err := e.st.Writer.ExecContext(t.Context(),
+		`CREATE TRIGGER refuse_recipes BEFORE INSERT ON recipes BEGIN SELECT RAISE(ABORT, 'disk full'); END`); err != nil {
+		t.Fatal(err)
+	}
+
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"recipe_url":"`+link+`"}`)
+	if rec.Code != http.StatusInternalServerError || errorCode(body) != "internal" || strings.Contains(rec.Body.String(), token) {
+		t.Errorf("POST = %d %s, want 500 internal without the link", rec.Code, rec.Body)
+	}
+	logs := e.logs.String()
+	if strings.Contains(logs, token) || strings.Contains(logs, "c.example") || strings.Contains(logs, "disk full") ||
+		!strings.Contains(logs, "reason=ground_failed") || !strings.Contains(logs, "dinner_id="+id) {
+		t.Errorf("logs = %q, want reason=ground_failed and the dinner id, without the link or dependency error", logs)
+	}
+}
+
+// TestPostGroundViaRecipeURLDinnerWriteFailure: a pasted link whose recipe
+// is stored but whose dinner cannot be written is a 500 logged by reason
+// and dinner id, never with the dependency error.
+func TestPostGroundViaRecipeURLDinnerWriteFailure(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Sunday stew"}`)
+	e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+	if _, err := e.st.Writer.ExecContext(t.Context(),
+		`CREATE TRIGGER refuse_grounding BEFORE UPDATE OF recipe_id ON dinners WHEN NEW.recipe_id IS NOT NULL BEGIN SELECT RAISE(ABORT, 'disk full'); END`); err != nil {
+		t.Fatal(err)
+	}
+
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"recipe_url":"`+stewPage+`"}`)
+	if rec.Code != http.StatusInternalServerError || errorCode(body) != "internal" {
+		t.Errorf("POST = %d %s, want 500 internal", rec.Code, rec.Body)
+	}
+	var stored int
+	if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT COUNT(*) FROM recipes WHERE source_url = ?`, stewPage).Scan(&stored); err != nil || stored != 1 {
+		t.Fatalf("recipes stored for the link = %d (%v), want 1: the failure must be the dinner write", stored, err)
+	}
+	logs := e.logs.String()
+	if strings.Contains(logs, "disk full") || !strings.Contains(logs, "reason=ground_failed") || !strings.Contains(logs, "dinner_id="+id) {
+		t.Errorf("logs = %q, want reason=ground_failed and the dinner id, without the dependency error", logs)
+	}
+}
+
+// TestPostGroundUnexpectedFailures: grounding by hand that fails reading
+// the dinner, or storing a manual recipe, is a 500 logged by reason and
+// dinner id, never with the database error.
+func TestPostGroundUnexpectedFailures(t *testing.T) {
+	t.Parallel()
+	const (
+		// Renaming a column every dinner read selects fails the read.
+		breakRead = `ALTER TABLE dinners RENAME COLUMN cuisine TO cuisine_gone`
+		// The trigger's message stands in for the database error.
+		breakStore = `CREATE TRIGGER refuse_recipes BEFORE INSERT ON recipes BEGIN SELECT RAISE(ABORT, 'disk full'); END`
+		manual     = `{"manual":{"ingredients":["1 lb beef"],"steps":["Brown."],"minutes":240,"method":"crockpot"}}`
+	)
+	for _, tc := range []struct {
+		name, sabotage, fix, leak string
+	}{
+		{"link read", breakRead, `{"recipe_url":"` + stewPage + `"}`, "cuisine"},
+		{"manual read", breakRead, manual, "cuisine"},
+		{"manual store", breakStore, manual, "disk full"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			e := newDinnersEnv(t).withRecipes(t)
+			id := createDinner(t, e.h, `{"name":"Sunday stew"}`)
+			if _, err := e.st.Writer.ExecContext(t.Context(), tc.sabotage); err != nil {
+				t.Fatal(err)
+			}
+
+			rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", tc.fix)
+			if rec.Code != http.StatusInternalServerError || errorCode(body) != "internal" {
+				t.Errorf("POST = %d %s, want 500 internal", rec.Code, rec.Body)
+			}
+			logs := e.logs.String()
+			if strings.Contains(logs, tc.leak) || !strings.Contains(logs, "reason=ground_failed") || !strings.Contains(logs, "dinner_id="+id) {
+				t.Errorf("logs = %q, want reason=ground_failed and the dinner id, without the database error", logs)
+			}
+		})
+	}
+}
+
+// TestPostGroundArchived: grounding an archived dinner by hand is a 409.
+func TestPostGroundArchived(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	id := createDinner(t, e.h, `{"name":"Family chili"}`)
+	if rec, _ := callDinners(t, e.h, http.MethodDelete, dinnersPath+"/"+id, ""); rec.Code != http.StatusOK {
+		t.Fatalf("DELETE = %d: %s", rec.Code, rec.Body)
+	}
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground",
+		`{"manual":{"ingredients":["1 lb beef"],"minutes":240,"method":"crockpot"}}`)
+	if rec.Code != http.StatusConflict || errorCode(body) != "dinner_archived" {
+		t.Errorf("POST = %d %v, want 409 dinner_archived", rec.Code, body)
+	}
+}
+
+func TestPostGroundViaManual(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	id := createDinner(t, e.h, `{"name":"Family chili"}`)
+
+	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground",
+		`{"manual":{"ingredients":["1 lb beef","1 can beans"],"steps":["Brown.","Simmer."],"minutes":240,"method":"crockpot"}}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	if d["grounding_status"] != "manual" || d["recipe_id"] == nil || d["photo_url"] != nil ||
+		d["method"] != "crockpot" || d["minutes_total"] != 240.0 || d["grounding_error"] != nil {
+		t.Errorf("dinner = %v", d)
+	}
+	var lines int
+	if err := e.st.Reader.QueryRow(`SELECT count(*) FROM recipe_ingredients WHERE recipe_id = ?`, d["recipe_id"]).Scan(&lines); err != nil {
+		t.Fatal(err)
+	}
+	if lines != 2 {
+		t.Errorf("stored %d ingredient lines, want 2", lines)
+	}
+}
+
+func TestPostGroundRejects(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	id := createDinner(t, e.h, `{"name":"Pad thai"}`)
+	path := dinnersPath + "/" + id + "/ground"
+
+	for _, tc := range []struct{ name, body, code string }{
+		{"empty", `{}`, "invalid_dinner"},
+		{"two kinds", `{"candidate_id":"https://a.example/x","recipe_url":"https://a.example/x"}`, "invalid_dinner"},
+		{"candidate not a link", `{"candidate_id":"c1"}`, "invalid_dinner"},
+		{"http link", `{"recipe_url":"http://a.example/x"}`, "invalid_dinner"},
+		{"null", `{"recipe_url":null}`, "invalid_request"},
+		{"unknown field", `{"url":"https://a.example/x"}`, "invalid_request"},
+		{"unknown manual field", `{"manual":{"ingredients":["x"],"minutes":5,"method":"oven","serves":4}}`, "invalid_request"},
+		{"manual without method", `{"manual":{"ingredients":["x"],"minutes":5}}`, "invalid_dinner"},
+		{"manual without ingredients", `{"manual":{"ingredients":[],"minutes":5,"method":"oven"}}`, "invalid_dinner"},
+		{"manual minutes too many", `{"manual":{"ingredients":["x"],"minutes":5000,"method":"oven"}}`, "invalid_dinner"},
+		{"not an object", `[]`, "invalid_request"},
+	} {
+		rec, body := callDinners(t, e.h, http.MethodPost, path, tc.body)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != tc.code {
+			t.Errorf("%s: %d %v, want 400 %s", tc.name, rec.Code, body, tc.code)
+		}
+	}
+	if d := listedDinner(t, e.h, id); d["grounding_status"] != "pending" {
+		t.Errorf("dinner after rejected fixes = %v, want unchanged", d)
+	}
+
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/nope/ground",
+		`{"manual":{"ingredients":["x"],"minutes":5,"method":"oven"}}`)
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("unknown dinner = %d %v, want 404", rec.Code, body)
+	}
+}
+
+func TestPostDinnerEnqueueFailureAnswersFailedDinner(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	if _, err := e.st.Writer.ExecContext(t.Context(),
+		`CREATE TRIGGER refuse_jobs BEFORE INSERT ON jobs BEGIN SELECT RAISE(ABORT, 'no jobs'); END`); err != nil {
+		t.Fatal(err)
+	}
+	rec, created := callDinners(t, e.h, http.MethodPost, dinnersPath, `{"name":"Chicken curry"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	id, _ := created["id"].(string)
+	if id == "" || created["grounding_status"] != "failed" || created["grounding_error"] != "grounding_error" || created["grounding_job_id"] != nil {
+		t.Fatalf("created = %v, want its id, failed (grounding_error) and a null grounding_job_id", created)
+	}
+	if got := listedDinner(t, e.h, id); got["grounding_status"] != "failed" {
+		t.Errorf("listed = %v, want failed", got)
+	}
+}

internal/server/login_test.go

@@ -83,7 +83,7 @@ func newLoginRouter(t *testing.T, issuer string) http.Handler {
 		t.Fatal(err)
 	}
 	r, err := NewRouter(logger, "dev", trusted, flow, sessions, newTestSettings(t),
-		newTestSearch(t), newTestAI(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/media_test.go

@@ -51,7 +51,7 @@ func newMediaRouter(t *testing.T) (r http.Handler, id, orphan string) {
 		t.Fatal(err)
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestRunner(t),
+	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t),
 		photos, fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/origin_test.go

@@ -45,7 +45,7 @@ func newOriginRouter(t *testing.T, logs io.Writer) http.Handler {
 	}
 	logger := slog.New(forwarded.LogHandler(slog.NewJSONHandler(logs, nil)))
 	r, err := NewRouter(logger, "dev", trusted, probeAuth{}, stubSessions{}, newTestSettings(t),
-		newTestSearch(t), newTestAI(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/recipesearch_test.go

@@ -22,7 +22,7 @@ const (
 func newRecipeSearchRouter(t *testing.T, search *recipes.SearchSettingsService) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), search, newTestAI(t), newTestRunner(t),
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), search, newTestAI(t), newTestDinners(t), newTestRunner(t),
 		newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/server.go

@@ -11,6 +11,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/aisettings"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
@@ -34,12 +35,15 @@ type RouteMounter interface {
 // /media; settings serves /api/v1/settings/household; search serves
 // /api/v1/settings/recipe-search and its /test; ai serves
 // /api/v1/settings/ai, its /api-key, /verify, /models and /reset-prompt;
+// dinnerSvc serves GET and POST /api/v1/dinners, PATCH and DELETE
+// /api/v1/dinners/{id}, POST /api/v1/dinners/{id}/favorite, GET
+// /api/v1/dinners/{id}/recipe-candidates and POST /api/v1/dinners/{id}/ground;
 // runner serves
 // POST /api/v1/jobs and GET /api/v1/jobs/{id}; photos serves
 // GET /media/photos/{id}-{size}.jpg; assets is the web build
 // served for every other GET. /health, /auth and the web build are public.
 // Requests to /api/v1 other than GET also need the session's CSRF token in CSRFHeader.
-func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, auth RouteMounter, sessions SessionLookup, settings *household.SettingsService, search *recipes.SearchSettingsService, ai *aisettings.Service, runner *jobs.Runner, photos PhotoFiles, assets fs.FS) (http.Handler, error) {
+func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, auth RouteMounter, sessions SessionLookup, settings *household.SettingsService, search *recipes.SearchSettingsService, ai *aisettings.Service, dinnerSvc *dinners.Service, runner *jobs.Runner, photos PhotoFiles, assets fs.FS) (http.Handler, error) {
 	if settings == nil {
 		return nil, errors.New("server: nil household settings service")
 	}
@@ -49,6 +53,9 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	if ai == nil {
 		return nil, errors.New("server: nil AI settings service")
 	}
+	if dinnerSvc == nil {
+		return nil, errors.New("server: nil dinners service")
+	}
 	if runner == nil {
 		return nil, errors.New("server: nil job runner")
 	}
@@ -92,6 +99,13 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	apiV1.Post("/settings/ai/verify", postAIVerify(logger, ai))
 	apiV1.Get("/settings/ai/models", getAIModels(logger, ai))
 	apiV1.Post("/settings/ai/reset-prompt", postAIResetPrompt(logger, ai))
+	apiV1.Get("/dinners", getDinners(logger, dinnerSvc))
+	apiV1.Post("/dinners", postDinner(logger, dinnerSvc))
+	apiV1.Patch("/dinners/{id}", patchDinner(logger, dinnerSvc))
+	apiV1.Delete("/dinners/{id}", deleteDinner(logger, dinnerSvc))
+	apiV1.Post("/dinners/{id}/favorite", postDinnerFavorite(logger, dinnerSvc))
+	apiV1.Get("/dinners/{id}/recipe-candidates", getDinnerCandidates(logger, dinnerSvc))
+	apiV1.Post("/dinners/{id}/ground", postDinnerGround(logger, dinnerSvc))
 	apiV1.Post("/jobs", postJob(logger, runner))
 	apiV1.Get("/jobs/{id}", getJob(logger, runner))
 	media.Get("/photos/{name}", getPhoto(logger, photos))

internal/server/server_test.go

@@ -17,9 +17,12 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/aisettings"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
@@ -43,7 +46,7 @@ func newTestRouterWith(t *testing.T, version string, settings *household.Setting
 		"index.html":             {Data: []byte(fixtureIndex)},
 		"assets/index-AbC123.js": {Data: []byte(fixtureAsset)},
 	}
-	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, newTestSearch(t), newTestAI(t), runner, newTestPhotos(t), assets)
+	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, newTestSearch(t), newTestAI(t), newTestDinners(t), runner, newTestPhotos(t), assets)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -139,6 +142,24 @@ func newTestSearch(t *testing.T) *recipes.SearchSettingsService {
 	return search
 }
 
+// newTestDinners returns a dinners service over a migrated temp database,
+// with its own unstarted job runner and a grounder that finds nothing.
+func newTestDinners(t *testing.T) *dinners.Service {
+	t.Helper()
+	st := newTestStore(t)
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := recipestest.NewGrounder(t, st, t.TempDir(), &recipestest.Search{}, &recipestest.Pages{}, &recipestest.Images{}, &llm.Fake{})
+	svc, err := dinners.NewService(st, g, runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return svc
+}
+
 // newTestBox returns a secret box under a random key.
 func newTestBox(t *testing.T) *secretbox.Box {
 	t.Helper()
@@ -170,7 +191,7 @@ func TestNewRouterRequiresAISettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), nil, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), nil, newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil AI settings service")
 	}
 }
@@ -179,7 +200,7 @@ func TestNewRouterRequiresSearchSettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestAI(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil recipe search settings service")
 	}
 }
@@ -188,7 +209,7 @@ func TestNewRouterRequiresPhotoFiles(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted nil photo files")
 	}
 }
@@ -197,16 +218,25 @@ func TestNewRouterRequiresSettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestAI(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil settings service")
 	}
 }
 
+func TestNewRouterRequiresDinners(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), nil, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil dinners service")
+	}
+}
+
 func TestNewRouterRequiresJobRunner(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil job runner")
 	}
 }

internal/server/settings.go

@@ -37,6 +37,9 @@ type settingsPatch struct {
 	SuggestionsTime  *string `json:"suggestions_time"`
 	ChatAutosendDow  *int    `json:"chat_autosend_dow"`
 	ChatAutosendTime *string `json:"chat_autosend_time"`
+	// OnboardingCompleted true sets onboarding_completed_at, which is
+	// itself read-only.
+	OnboardingCompleted *bool `json:"onboarding_completed"`
 }
 
 func getHouseholdSettings(logger *slog.Logger, svc *household.SettingsService) http.HandlerFunc {
@@ -110,7 +113,7 @@ func decodePatch[T any](body io.Reader) (T, error) {
 		if errors.As(err, &typeErr) {
 			return patch, fmt.Errorf("%s: want a JSON %s", typeErr.Field, typeErr.Type)
 		}
-		return patch, fmt.Errorf("invalid settings: %v", err)
+		return patch, fmt.Errorf("invalid request body: %v", err)
 	}
 	return patch, nil
 }

internal/server/settings_test.go

@@ -3,6 +3,7 @@ package server
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"io"
 	"log/slog"
 	"net/http"
@@ -13,6 +14,7 @@ import (
 	"time"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/auth"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
@@ -115,6 +117,63 @@ func TestPatchHouseholdSettings(t *testing.T) {
 	}
 }
 
+// newOnboardingRouter returns a router whose settings store holds regulars
+// Regulars.
+func newOnboardingRouter(t *testing.T, regulars int) http.Handler {
+	t.Helper()
+	st := newTestStore(t)
+	if err := household.SeedSettings(context.Background(), st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
+	for i := range regulars {
+		now := store.Now().String()
+		if _, err := db.New(st.Writer).CreateDinner(context.Background(), db.CreateDinnerParams{
+			ID: store.NewID(), Name: fmt.Sprintf("Dinner %d", i), NormalizedName: fmt.Sprintf("dinner %d", i),
+			Status: "regular", Origin: "regular", GroundingStatus: "pending", CreatedAt: now, UpdatedAt: now,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return newTestRouterWith(t, "dev", household.NewSettingsService(st), newTestRunner(t))
+}
+
+func TestPatchHouseholdSettingsCompletesOnboarding(t *testing.T) {
+	t.Parallel()
+
+	rec, body := serve(t, newOnboardingRouter(t, household.MinRegulars), signedIn(http.MethodPatch, settingsPath,
+		strings.NewReader(`{"onboarding_completed":true}`)))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", rec.Code, rec.Body)
+	}
+	if at, ok := body["onboarding_completed_at"].(string); !ok || at != body["updated_at"] {
+		t.Errorf("onboarding_completed_at = %#v, want the update time %#v", body["onboarding_completed_at"], body["updated_at"])
+	}
+}
+
+// TestPatchHouseholdSettingsOnboardingNeedsRegulars: completing onboarding
+// with fewer than three Regulars is refused and leaves it incomplete.
+func TestPatchHouseholdSettingsOnboardingNeedsRegulars(t *testing.T) {
+	t.Parallel()
+
+	for regulars := range household.MinRegulars {
+		t.Run(fmt.Sprintf("%d Regulars", regulars), func(t *testing.T) {
+			t.Parallel()
+			router := newOnboardingRouter(t, regulars)
+			rec, _ := serve(t, router, signedIn(http.MethodPatch, settingsPath,
+				strings.NewReader(`{"onboarding_completed":true}`)))
+			if rec.Code != http.StatusBadRequest ||
+				!strings.Contains(rec.Body.String(), `"code":"invalid_settings"`) ||
+				!strings.Contains(rec.Body.String(), "onboarding_completed: add at least 3 Regulars first") {
+				t.Fatalf("PATCH = %d %s, want 400 invalid_settings on onboarding_completed", rec.Code, rec.Body)
+			}
+			_, body := serve(t, router, signedIn(http.MethodGet, settingsPath, nil))
+			if body["onboarding_completed_at"] != nil {
+				t.Errorf("onboarding_completed_at = %#v after a refused completion, want null", body["onboarding_completed_at"])
+			}
+		})
+	}
+}
+
 func TestPatchHouseholdSettingsRejected(t *testing.T) {
 	t.Parallel()
 
@@ -136,6 +195,8 @@ func TestPatchHouseholdSettingsRejected(t *testing.T) {
 		{"null value", `{"timezone":null}`, "invalid_request", "timezone"},
 		{"unknown field", `{"dinner":"17:30"}`, "invalid_request", "dinner"},
 		{"read-only field", `{"updated_by":"someone"}`, "invalid_request", "updated_by"},
+		{"read-only onboarding time", `{"onboarding_completed_at":"2026-10-06T12:00:00.000Z"}`, "invalid_request", "onboarding_completed_at"},
+		{"onboarding undone", `{"onboarding_completed":false}`, "invalid_settings", "onboarding_completed"},
 		{"not an object", `["timezone"]`, "invalid_request", "JSON object"},
 		{"null body", `null`, "invalid_request", "JSON object"},
 		{"trailing data", `{"dinner_time":"18:00"} {}`, "invalid_request", "JSON object"},
@@ -216,7 +277,7 @@ func TestHouseholdSettingsWithRealSession(t *testing.T) {
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
 	router, err := NewRouter(logger, "dev", nil, stubAuth{}, sessions, household.NewSettingsService(st),
-		newTestSearch(t), newTestAI(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}