Meal-Planner/Review/sprint5-verification.md

Sprint 5 — Deploy & smoke-check (F5 + F2)

Goal: verify the URL week selector (F5) and keyboard shortcuts (F2) work end-to-end on http://100.108.208.56:8082/.

Commits:

• d78bd18 — F5 URL week selector + 0015 migration cast fix
• f740f40 — F2 keyboard shortcuts

Sprint scope: F5 (URL week selector) + F2 (keyboard shortcuts) + 0015 cast fix Backend changes: meals.py (week_start param), shopping_list.py (week_start param), 0015_normalize_pantry_aisles.py (cast fix) Frontend changes: App.tsx, lib/utils.ts, api/index.ts, pages/Dashboard.tsx, pages/ShoppingList.tsx, pages/Pantry.tsx, pages/Recipes.tsx; new hooks/useKeyboardShortcuts.ts, hooks/useFocusSearch.ts, components/ShortcutHelpBanner.tsx

1. Deploy

This sprint includes a backend migration and a frontend bundle change.

# On deployment host (100.108.224.12)
cd /path/to/MealPlanner
git pull

# 1. Persistent backup of aisle values BEFORE the migration (recommended)
docker compose exec -T db psql -U mealplanner -d mealplanner \
  -f /dev/stdin < backend/scripts/persist_aisle_backup.sql

# 2. Apply the migration (now includes the cast fix from Sprint 5)
docker compose exec backend alembic upgrade head
# Expected: "Running upgrade 0014 -> 0015, Normalize ingredient.aisle and grocery_item.aisle..."

# 3. Rebuild & restart both backend and frontend
docker compose -f docker-compose.yml up -d --build backend frontend

CRITICAL: the migration fix in d78bd18 is what makes the Sprint 2 migration actually runnable. The deployment host will hit the same text = boolean error without it.

2. Build verification (already green locally)

$ cd frontend && npm run build
> tsc && vite build
✓ 1894 modules transformed.
dist/index.html                   0.54 kB │ gzip:   0.32 kB
dist/assets/index-BeQbgL42.css   37.83 kB │ gzip:   6.79 kB
dist/assets/index-6M0ldwxq.js   474.37 kB │ gzip: 146.54 kB
✓ built in 6.71s

tsc 0 errors, vite 0 errors.

3. Smoke checks

S5.A — F5 backend: ?week_start= is honoured

# 1. Without param — should return the latest plan
curl -s "http://100.108.208.56:8082/api/meals" | python3 -c "import sys,json; d=json.load(sys.stdin); print('week_start_date:', d.get('week_start_date') if d else 'NULL')"

# 2. With a known plan's week — should return that plan
curl -s "http://100.108.208.56:8082/api/meals?week_start=2026-05-15" | python3 -c "import sys,json; d=json.load(sys.stdin); print('week_start_date:', d.get('week_start_date') if d else 'NULL', 'items:', len(d.get('items',[])) if d else 0)"

# 3. With a week that has no plan — should return null
curl -s "http://100.108.208.56:8082/api/meals?week_start=2099-01-01"
# Expected: null (or a JSON "null")

# 4. Same for shopping-list
curl -s "http://100.108.208.56:8082/api/shopping-list?week_start=2026-05-15" | python3 -c "import sys,json; d=json.load(sys.stdin); print('week_start_date:', d.get('week_start_date'), 'items:', len(d.get('items',[])))"

The local dev DB returns week_start_date: 2026-05-15 items: 4 for the known plan and null for 2099-01-01. The deployment host should match (modulo different seed data).

S5.B — F5 frontend: URL week navigation on Dashboard

1. Open http://100.108.208.56:8082/.
2. Confirm the header shows the current week ("This week" button is highlighted, primary-50 background).
3. Click the left chevron — title should change to the previous week. URL should update to ?week=YYYY-MM-DD (Monday's date).
4. Click the left chevron again — should be 2 weeks back. URL still has ?week=....
5. Click the "This week" / "Current" button — URL should drop ?week=..., title should be the current week.
6. Click the right chevron — title should be next week. (If no plan for that week, you should see the "No meal plan yet" empty state.)
7. Manually type http://100.108.208.56:8082/?week=2026-05-15 in the URL bar. Page should load with that week's plan.

S5.C — F5 frontend: URL week navigation on Shopping List

Same as S5.B but on /shopping-list. The empty state should say "No plan for that week" (not "No shopping list yet") when ?week= is set to a week that has no plan.

S5.D — F5 frontend: query-key isolation

1. Open http://100.108.208.56:8082/?week=2026-05-15.
2. Open DevTools → Network tab.
3. Drag a meal to a different slot. The Network tab should show:
   • PUT /api/meals/items/{id}/move?new_day_of_week=...&new_meal_type=...
   • GET /api/meals?week_start=2026-05-15 (the refetch, not /api/meals without the param)
4. Verify the change persists on refresh.

S5.E — F2 keyboard shortcuts

Open http://100.108.208.56:8082/ in a fresh tab (so no input is focused).

Action	Expected
Press ?	Help banner appears under the nav; auto-dismisses after 6s
Press ? then Escape	Banner appears then immediately closes
Press g then d	Navigate to / (Dashboard)
Press g then r	Navigate to /recipes
Press g then p	Navigate to /pantry
Press g then s	Navigate to /shopping-list
On Pantry, press /	Search input gains focus, text is selected
On Recipes, press /	Search input gains focus, text is selected
On Pantry, focus the search, type g d	"g d" is typed in the search box; no navigation
Press g and wait 2 seconds	Nothing happens (sequence timeout)

S5.F — Migration 0015 cast fix verification

After alembic upgrade head returns successfully:

# Pick a sample of rows to see they normalized correctly
docker compose exec -T db psql -U mealplanner -d mealplanner -c "
  SELECT aisle, COUNT(*) AS n
  FROM ingredient
  GROUP BY aisle
  ORDER BY n DESC
  LIMIT 20;
"
# Expected: aisle values are sentence-case canonical labels only:
# 'Pantry', 'Produce', 'Meat & Seafood', 'Dairy & Eggs', 'Frozen',
# 'Bakery', 'Beverages', 'Spices', 'Other', or NULL.
# If you see 'pantry', 'meat_seafood', 'canned_goods' etc., the
# migration did NOT run correctly — re-check the cast fix.

S5.G — Regression check: Sprints 1-4 still work

• /recommended redirects to /recipes/recommended (Sprint 1 B4)
• /this-does-not-exist renders the NotFound page (Sprint 1 B4)
• Recipe detail shows ingredients with proper spacing (Sprint 1 B1)
• Meal detail shows $X.XX per serving (Sprint 1 B3)
• Pantry aisle <select> has all 9 canonical options (Sprint 2 B8)
• Pantry aisles are sentence-case canonical (Sprint 5 / 0015 fix)
• Shopping list section headers are sentence-case (Sprint 2 B9)
• Recipes filter panel has Apply/Reset and active count badge (Sprint 2 B11)
• Dashboard mobile viewport (390 px) shows empty meal slots (Sprint 1 B5)
• Dashboard delete shows the Undo toast (Sprint 3 B12)
• Failed mutations show a toast with the FastAPI detail (Sprint 4 F7)
• Plan-status Badge announces correctly (Sprint 4 F6)

4. Acceptance criteria

Sprint 5 is done when:

• git pull + migration + container rebuild on the deployment host succeeds
• Migration 0015 completes with the cast fix
• All S5.A curl tests return the expected results
• All S5.B / S5.C / S5.D / S5.E interactions behave as described
• S5.F sample query shows only canonical aisle labels
• No regression in S5.G

5. Rollback

If something goes wrong:

# Revert the cast fix in 0015
# (only needed if the cast fix makes the migration worse — it shouldn't)
# Just revert the code commit; the migration file change alone won't re-run.

# Revert the URL week selector
git revert f740f40 d78bd18
docker compose -f docker-compose.yml up -d --build backend frontend

# For the aisle data: if 0015 ran but produced wrong results,
# restore from the persist_aisle_backup tables:
docker compose exec -T db psql -U mealplanner -d mealplanner -c "
  UPDATE ingredient i SET aisle = b.aisle
  FROM public.ingredient_aisle_backup_0015 b
  WHERE i.id = b.id;
  UPDATE grocery_item g SET aisle = b.aisle
  FROM public.grocery_item_aisle_backup_0015 b
  WHERE g.id = b.id;
"

# Note: 0015 itself has no down-migration (raises NotImplementedError).
# A full rollback requires a DB snapshot taken before the migration ran.

No data loss if you ran persist_aisle_backup.sql first.