From ebbf66e76e82e37bc3e9b0266c5c260abb5e9bea Mon Sep 17 00:00:00 2001
From: marcusDenslow <marcus.allen.denslow@gmail.com>
Date: Sun, 14 Jun 2026 20:15:21 +0200
Subject: [PATCH] docs(docs): update docs to get rid of gopls warnings. update
 some code to newer standards

---
 .gitignore                 |  1 +
 api/doc.go                 |  3 +++
 api/handlers/doc.go        |  3 +++
 api/middleware/doc.go      |  4 ++++
 api/routes/doc.go          |  3 +++
 cmd/reconcile-cards/doc.go |  3 +++
 pkg/api/doc.go             |  3 +++
 pkg/auth/doc.go            |  3 +++
 pkg/bring/doc.go           |  3 +++
 pkg/config/doc.go          |  3 +++
 pkg/database/doc.go        |  3 +++
 pkg/models/doc.go          |  3 +++
 pkg/observability/doc.go   |  3 +++
 pkg/shipping/doc.go        |  3 +++
 pkg/shippo/doc.go          |  2 ++
 pkg/stripeclient/doc.go    |  3 +++
 pkg/tui/doc.go             |  3 +++
 pkg/tui/payment_form.go    |  8 +++-----
 pkg/tui/qrfefe/doc.go      |  3 +++
 pkg/tui/shop.go            | 13 ++++---------
 pkg/tui/theme/doc.go       |  3 +++
 pkg/utils/doc.go           |  3 +++
 pkg/validate/doc.go        |  3 +++
 23 files changed, 68 insertions(+), 14 deletions(-)
 create mode 100644 api/doc.go
 create mode 100644 api/handlers/doc.go
 create mode 100644 api/middleware/doc.go
 create mode 100644 api/routes/doc.go
 create mode 100644 cmd/reconcile-cards/doc.go
 create mode 100644 pkg/api/doc.go
 create mode 100644 pkg/auth/doc.go
 create mode 100644 pkg/bring/doc.go
 create mode 100644 pkg/config/doc.go
 create mode 100644 pkg/database/doc.go
 create mode 100644 pkg/models/doc.go
 create mode 100644 pkg/observability/doc.go
 create mode 100644 pkg/shipping/doc.go
 create mode 100644 pkg/shippo/doc.go
 create mode 100644 pkg/stripeclient/doc.go
 create mode 100644 pkg/tui/doc.go
 create mode 100644 pkg/tui/qrfefe/doc.go
 create mode 100644 pkg/tui/theme/doc.go
 create mode 100644 pkg/utils/doc.go
 create mode 100644 pkg/validate/doc.go

diff --git a/.gitignore b/.gitignore
index 7023db7..ae7d82a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@
 
 docs/sca-psd2-compliance.md
 accept-a-payment/
+codemap/
 
 
 FULFILLMENT.md
diff --git a/api/doc.go b/api/doc.go
new file mode 100644
index 0000000..1959c95
--- /dev/null
+++ b/api/doc.go
@@ -0,0 +1,3 @@
+// Command api is the HTTP backend: it boots the router, bolts on all the
+// middleware, and answers the requests the TUI throws at it.
+package main
diff --git a/api/handlers/doc.go b/api/handlers/doc.go
new file mode 100644
index 0000000..d483528
--- /dev/null
+++ b/api/handlers/doc.go
@@ -0,0 +1,3 @@
+// Package handlers is where the real work happens, one function per endpoint:
+// carts, orders, products, addresses, cards, webhooks, and the rest.
+package handlers
diff --git a/api/middleware/doc.go b/api/middleware/doc.go
new file mode 100644
index 0000000..f803c51
--- /dev/null
+++ b/api/middleware/doc.go
@@ -0,0 +1,4 @@
+// Package middleware holds the stuff that runs on every request before a
+// handler ever sees it: auth, CORS, logging, rate limiting, metrics, and a
+// recovery net for panics.
+package middleware
diff --git a/api/routes/doc.go b/api/routes/doc.go
new file mode 100644
index 0000000..3581ed1
--- /dev/null
+++ b/api/routes/doc.go
@@ -0,0 +1,3 @@
+// Package routes is the switchboard: it maps every URL to the handler that
+// knows what to do with it.
+package routes
diff --git a/cmd/reconcile-cards/doc.go b/cmd/reconcile-cards/doc.go
new file mode 100644
index 0000000..781e4e2
--- /dev/null
+++ b/cmd/reconcile-cards/doc.go
@@ -0,0 +1,3 @@
+// Command reconcile-cards hunts down saved cards that Stripe no longer knows
+// about and detaches them. Run it with -dry-run first if you're nervous.
+package main
diff --git a/pkg/api/doc.go b/pkg/api/doc.go
new file mode 100644
index 0000000..a10a3ca
--- /dev/null
+++ b/pkg/api/doc.go
@@ -0,0 +1,3 @@
+// Package api is the client side of the house: it talks to our HTTP backend
+// so other Go code doesn't have to hand-roll requests.
+package api
diff --git a/pkg/auth/doc.go b/pkg/auth/doc.go
new file mode 100644
index 0000000..7d1c9b5
--- /dev/null
+++ b/pkg/auth/doc.go
@@ -0,0 +1,3 @@
+// Package auth sorts out who you are: logging in with an SSH key and minting
+// the JWT you carry around afterwards.
+package auth
diff --git a/pkg/bring/doc.go b/pkg/bring/doc.go
new file mode 100644
index 0000000..f190adb
--- /dev/null
+++ b/pkg/bring/doc.go
@@ -0,0 +1,3 @@
+// Package bring talks to Bring, the Norwegian postal service, for booking
+// shipments and printing labels.
+package bring
diff --git a/pkg/config/doc.go b/pkg/config/doc.go
new file mode 100644
index 0000000..ae39698
--- /dev/null
+++ b/pkg/config/doc.go
@@ -0,0 +1,3 @@
+// Package config reads everything out of the environment so secrets and
+// settings stay out of the source code.
+package config
diff --git a/pkg/database/doc.go b/pkg/database/doc.go
new file mode 100644
index 0000000..dfce962
--- /dev/null
+++ b/pkg/database/doc.go
@@ -0,0 +1,3 @@
+// Package database opens the SQLite connection, runs the migrations, and
+// drops in some seed data so the shop isn't empty on a fresh boot.
+package database
diff --git a/pkg/models/doc.go b/pkg/models/doc.go
new file mode 100644
index 0000000..8fc016b
--- /dev/null
+++ b/pkg/models/doc.go
@@ -0,0 +1,3 @@
+// Package models is the shared vocabulary of the app: coffee, carts, orders,
+// addresses, cards, users, and the other nouns everything passes around.
+package models
diff --git a/pkg/observability/doc.go b/pkg/observability/doc.go
new file mode 100644
index 0000000..c572220
--- /dev/null
+++ b/pkg/observability/doc.go
@@ -0,0 +1,3 @@
+// Package observability sets up tracing and structured logs so that when
+// something breaks at 3am you stand a chance of figuring out why.
+package observability
diff --git a/pkg/shipping/doc.go b/pkg/shipping/doc.go
new file mode 100644
index 0000000..37b890d
--- /dev/null
+++ b/pkg/shipping/doc.go
@@ -0,0 +1,3 @@
+// Package shipping holds the plain shipping types that the rest of the app
+// passes back and forth.
+package shipping
diff --git a/pkg/shippo/doc.go b/pkg/shippo/doc.go
new file mode 100644
index 0000000..bf1fca9
--- /dev/null
+++ b/pkg/shippo/doc.go
@@ -0,0 +1,2 @@
+// Package shippo talks to the Shippo API for shipping rates and labels.
+package shippo
diff --git a/pkg/stripeclient/doc.go b/pkg/stripeclient/doc.go
new file mode 100644
index 0000000..203a491
--- /dev/null
+++ b/pkg/stripeclient/doc.go
@@ -0,0 +1,3 @@
+// Package stripeclient wires up the Stripe SDK once at startup (with tracing
+// baked in) so everyone else can just make calls.
+package stripeclient
diff --git a/pkg/tui/doc.go b/pkg/tui/doc.go
new file mode 100644
index 0000000..9ad4369
--- /dev/null
+++ b/pkg/tui/doc.go
@@ -0,0 +1,3 @@
+// Package tui is the terminal UI you see over SSH: the shop, the cart, your
+// account, and the checkout flow, all drawn with Bubbletea.
+package tui
diff --git a/pkg/tui/payment_form.go b/pkg/tui/payment_form.go
index a237965..07a81f4 100644
--- a/pkg/tui/payment_form.go
+++ b/pkg/tui/payment_form.go
@@ -276,9 +276,7 @@ func (m Model) updatePaymentViewport() Model {
 	breadH := lipgloss.Height(m.BuildBreadcrumbs())
 	footerH := lipgloss.Height(m.BuildFooter())
 	availH := m.heightContainer - headerH - footerH - breadH
-	if availH < 1 {
-		availH = 1
-	}
+	availH = max(availH, 1)
 	if !m.payment.viewportReady {
 		m.payment.viewport = viewport.New(viewport.WithWidth(m.widthContent), viewport.WithHeight(availH))
 		m.payment.viewport.KeyMap = viewport.KeyMap{}
@@ -303,7 +301,7 @@ func (m Model) PaymentPageView() string {
 			m.widthContainer,
 			m.payment.viewport.Height(),
 			lipgloss.Center, lipgloss.Center,
-			m.renderPaymentHttpsView(),
+			m.renderPaymentHTTPSView(),
 		)
 	} else if m.payment.view == 0 && m.payment.form == nil {
 		content = m.RenderCardList()
@@ -374,7 +372,7 @@ func (m Model) RenderCardList() string {
 	return lipgloss.JoinVertical(lipgloss.Left, parts...)
 }
 
-func (m Model) renderPaymentHttpsView() string {
+func (m Model) renderPaymentHTTPSView() string {
 	baseStyle := m.theme.TextLabel()
 	accentStyle := m.theme.TextHighlight()
 
diff --git a/pkg/tui/qrfefe/doc.go b/pkg/tui/qrfefe/doc.go
new file mode 100644
index 0000000..61e5848
--- /dev/null
+++ b/pkg/tui/qrfefe/doc.go
@@ -0,0 +1,3 @@
+// Package qrfefe turns text into a QR code drawn with terminal block
+// characters, handy for showing links you can scan right off the screen.
+package qrfefe
diff --git a/pkg/tui/shop.go b/pkg/tui/shop.go
index a556bba..0117dac 100644
--- a/pkg/tui/shop.go
+++ b/pkg/tui/shop.go
@@ -24,9 +24,7 @@ const (
 // menu(menuW+4) + gap(1) + detail(detailW+4) = contentW = wideW + 4.
 func (m Model) shopLayout() (contentW, menuW, detailW, wideW int) {
 	contentW = m.widthContent
-	if contentW > 74 {
-		contentW = 74
-	}
+	contentW = min(contentW, 74)
 	wideW = contentW - 4
 	if m.size < large {
 		// Stacked layout: both panels span the full content width.
@@ -66,6 +64,7 @@ func clampLines(s string, n int) string {
 
 // roastMeter renders the strength dots, e.g. ● ● ● ○ ○
 func roastMeter(n int) string {
+	n = max(0, min(n, 5))
 	on := lipgloss.NewStyle().Foreground(cGold).Render(strings.Repeat("● ", n))
 	off := pDim.Render(strings.Repeat("○ ", 5-n))
 	return strings.TrimRight(on+off, " ")
@@ -218,12 +217,8 @@ func (m Model) shopMoveSelected(previous bool) Model {
 	} else {
 		next++
 	}
-	if next < 0 {
-		next = 0
-	}
-	if next >= len(m.Coffees) {
-		next = len(m.Coffees) - 1
-	}
+	next = max(next, 0)
+	next = min(next, len(m.Coffees)-1)
 	m.shop.selected = next
 	return m
 }
diff --git a/pkg/tui/theme/doc.go b/pkg/tui/theme/doc.go
new file mode 100644
index 0000000..7e65fe9
--- /dev/null
+++ b/pkg/tui/theme/doc.go
@@ -0,0 +1,3 @@
+// Package theme keeps the colors and styles in one spot so the whole UI
+// looks like it was built by the same person.
+package theme
diff --git a/pkg/utils/doc.go b/pkg/utils/doc.go
new file mode 100644
index 0000000..a80fa88
--- /dev/null
+++ b/pkg/utils/doc.go
@@ -0,0 +1,3 @@
+// Package utils is the catch-all drawer for tiny HTTP helpers that didn't
+// earn a package of their own.
+package utils
diff --git a/pkg/validate/doc.go b/pkg/validate/doc.go
new file mode 100644
index 0000000..0590882
--- /dev/null
+++ b/pkg/validate/doc.go
@@ -0,0 +1,3 @@
+// Package validate gives user input a once-over before the rest of the app
+// trusts it.
+package validate