@nakedev/go-scaffold 0.1.2 → 0.1.3

package/templates/add/rbac/internal/shared/middleware/authz_test.go.hbs

@@ -0,0 +1,88 @@
+package middleware
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestAuthz_CachesWithinTTL(t *testing.T) {
+	var calls int32
+	a := NewAuthz(func(context.Context, string) (map[string]struct{}, error) {
+		atomic.AddInt32(&calls, 1)
+		return map[string]struct{}{"x": {}}, nil
+	}, time.Minute)
+
+	if _, err := a.permsOf(context.Background(), "staff"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, err := a.permsOf(context.Background(), "staff"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("want resolve called once for two calls within TTL (cache hit), got %d", got)
+	}
+}
+
+func TestAuthz_ReResolvesAfterTTLExpires(t *testing.T) {
+	var calls int32
+	a := NewAuthz(func(context.Context, string) (map[string]struct{}, error) {
+		atomic.AddInt32(&calls, 1)
+		return map[string]struct{}{"x": {}}, nil
+	}, 10*time.Millisecond)
+
+	if _, err := a.permsOf(context.Background(), "staff"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	time.Sleep(20 * time.Millisecond)
+	if _, err := a.permsOf(context.Background(), "staff"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := atomic.LoadInt32(&calls); got != 2 {
+		t.Fatalf("want resolve called again once the TTL expires, got %d calls", got)
+	}
+}
+
+func TestAuthz_Require_ForbidsMissingPermission(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	a := NewAuthz(func(context.Context, string) (map[string]struct{}, error) {
+		return map[string]struct{}{"other:perm": {}}, nil
+	}, time.Minute)
+
+	r := gin.New()
+	// Require only records a *apperror.AppError via c.Error — Error(true) is
+	// what actually translates that into the response status code, same as
+	// the real router (see cmd/api/main.go).
+	r.Use(Error(true))
+	r.GET("/x", func(c *gin.Context) { c.Set(RoleKey, "staff") }, a.Require("role:manage"), func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/x", nil))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("want 403 without the required permission, got %d", w.Code)
+	}
+}
+
+func TestAuthz_Require_AllowsGrantedPermission(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	a := NewAuthz(func(context.Context, string) (map[string]struct{}, error) {
+		return map[string]struct{}{"role:manage": {}}, nil
+	}, time.Minute)
+
+	r := gin.New()
+	r.Use(Error(true))
+	r.GET("/x", func(c *gin.Context) { c.Set(RoleKey, "admin") }, a.Require("role:manage"), func(c *gin.Context) {
+		c.Status(http.StatusOK)
+	})
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/x", nil))
+	if w.Code != http.StatusOK {
+		t.Fatalf("want 200 with the required permission granted, got %d", w.Code)
+	}
+}

package/templates/add/rbac/migrations/add_roles.down.sql.hbs

@@ -0,0 +1,15 @@
+-- if an admin created a custom role after this migration and it's still
+-- assigned to any user, dropping the roles table would orphan that value —
+-- raise a clear, actionable error instead of a raw FK-violation.
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM users WHERE role NOT IN ('staff', 'admin')) THEN
+        RAISE EXCEPTION 'cannot roll back add_roles: users still have a role other than staff/admin — reassign them to staff/admin first';
+    END IF;
+END $$;
+
+ALTER TABLE users DROP COLUMN role;
+
+DROP TABLE role_permissions;
+DROP TABLE permissions;
+DROP TABLE roles;

package/templates/add/rbac/migrations/add_roles.up.sql.hbs

@@ -0,0 +1,35 @@
+CREATE TABLE roles (
+    code       VARCHAR(20) PRIMARY KEY,
+    name       TEXT NOT NULL,
+    is_system  BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE permissions (
+    code        VARCHAR(50) PRIMARY KEY,
+    description TEXT NOT NULL
+);
+
+CREATE TABLE role_permissions (
+    role_code       VARCHAR(20) NOT NULL REFERENCES roles(code) ON DELETE CASCADE,
+    permission_code VARCHAR(50) NOT NULL REFERENCES permissions(code) ON DELETE CASCADE,
+    PRIMARY KEY (role_code, permission_code)
+);
+
+INSERT INTO roles (code, name, is_system) VALUES
+    ('staff', 'Staff', TRUE),
+    ('admin', 'Admin', TRUE);
+
+INSERT INTO permissions (code, description) VALUES
+    ('role:manage',       'Create roles and change their permissions'),
+    ('user:manage-role',  'Change a user''s assigned role'),
+    ('user:read',         'List and view other users');
+
+-- admin gets every permission that exists, staff gets none — no behavior
+-- change for existing users until an admin explicitly grants something.
+INSERT INTO role_permissions (role_code, permission_code)
+SELECT 'admin', code FROM permissions;
+
+ALTER TABLE users
+    ADD COLUMN role VARCHAR(20) NOT NULL DEFAULT 'staff' REFERENCES roles(code);

package/templates/add/worker/cmd/worker/main.go.hbs

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"{{goModule}}/internal/platform/mail"
+	"{{goModule}}/internal/platform/queue"
+	"{{goModule}}/internal/shared/config"
+	// go-scaffold:imports
+)
+
+func main() {
+	cfg := config.Load()
+
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: parseLevel(cfg.LogLevel)}))
+	slog.SetDefault(logger)
+
+	srv, err := queue.NewServer(cfg.RedisURL)
+	if err != nil {
+		logger.Error("new queue server", "error", err)
+		os.Exit(1)
+	}
+
+	srv.Handle(mail.TypeSendEmail, mail.HandleSendEmail(mail.Open(cfg)))
+	// go-scaffold:queue-handlers
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	go func() {
+		logger.Info("worker started")
+		if err := srv.Start(); err != nil && !errors.Is(err, context.Canceled) {
+			logger.Error("worker server", "error", err)
+			os.Exit(1)
+		}
+	}()
+
+	<-ctx.Done()
+	logger.Info("shutting down worker")
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	// asynq's Shutdown() blocks until in-flight tasks finish (or the process
+	// is killed) with no context/timeout parameter of its own — run it in a
+	// goroutine and race it against shutdownCtx so a stuck task can't hang
+	// the process forever.
+	done := make(chan struct{}, 1)
+	go func() {
+		srv.Shutdown()
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-shutdownCtx.Done():
+		logger.Warn("worker shutdown timed out")
+	}
+	logger.Info("worker stopped")
+}
+
+func parseLevel(s string) slog.Level {
+	switch s {
+	case "debug":
+		return slog.LevelDebug
+	case "warn":
+		return slog.LevelWarn
+	case "error":
+		return slog.LevelError
+	default:
+		return slog.LevelInfo
+	}
+}

package/templates/add/worker/internal/platform/cache/redis.go.hbs

@@ -0,0 +1,18 @@
+package cache
+
+import (
+	"{{goModule}}/internal/shared/config"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// Open connects to Redis — it talks to a real external system, so it lives
+// in platform/, not shared/. Used for ephemeral, TTL-bound data and as the
+// backing store for the async task queue (platform/queue).
+func Open(cfg config.Config) (*redis.Client, error) {
+	opts, err := redis.ParseURL(cfg.RedisURL)
+	if err != nil {
+		return nil, err
+	}
+	return redis.NewClient(opts), nil
+}

package/templates/add/worker/internal/platform/mail/mail.go.hbs

@@ -0,0 +1,48 @@
+package mail
+
+import (
+	"fmt"
+	"log/slog"
+	"net/smtp"
+
+	"{{goModule}}/internal/shared/config"
+)
+
+// Client sends plain-text email over SMTP (net/smtp already handles STARTTLS
+// when the server offers it, which covers Gmail/SendGrid/Mailgun/SES/Resend
+// SMTP relays on port 587) — talks to a real external system, so it lives in
+// platform/, not shared/.
+type Client struct {
+	host, port, username, password, from string
+}
+
+func Open(cfg config.Config) *Client {
+	return &Client{
+		host:     cfg.SMTPHost,
+		port:     cfg.SMTPPort,
+		username: cfg.SMTPUsername,
+		password: cfg.SMTPPassword,
+		from:     cfg.SMTPFrom,
+	}
+}
+
+// Send delivers a plain-text email. If SMTP isn't configured (dev default —
+// SMTP_HOST unset), it logs the message instead of failing, so flows that
+// send email stay testable without a real mail server.
+func (c *Client) Send(to, subject, body string) error {
+	if c.host == "" {
+		// ponytail: no SMTP configured — log instead of failing. Upgrade path:
+		// set SMTP_HOST (+ USERNAME/PASSWORD/FROM) once a real environment needs it.
+		slog.Info("email not sent (SMTP not configured)", "to", to, "subject", subject, "body", body)
+		return nil
+	}
+	msg := fmt.Sprintf("To: %s\r\nFrom: %s\r\nSubject: %s\r\n\r\n%s\r\n", to, c.from, subject, body)
+	// nil Auth when no username is set — a relay/local catcher that doesn't
+	// require auth (or doesn't advertise AUTH at all) rejects a non-nil Auth
+	// outright, even with empty credentials.
+	var auth smtp.Auth
+	if c.username != "" {
+		auth = smtp.PlainAuth("", c.username, c.password, c.host)
+	}
+	return smtp.SendMail(c.host+":"+c.port, auth, c.from, []string{to}, []byte(msg))
+}

package/templates/add/worker/internal/platform/mail/task.go.hbs

@@ -0,0 +1,52 @@
+package mail
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/hibiken/asynq"
+)
+
+const TypeSendEmail = "email:send"
+
+type sendEmailPayload struct {
+	To      string
+	Subject string
+	Body    string
+}
+
+func NewSendEmailTask(p sendEmailPayload) *asynq.Task {
+	payload, _ := json.Marshal(p)
+	return asynq.NewTask(TypeSendEmail, payload)
+}
+
+func HandleSendEmail(client *Client) asynq.Handler {
+	return asynq.HandlerFunc(func(ctx context.Context, task *asynq.Task) error {
+		var p sendEmailPayload
+		if err := json.Unmarshal(task.Payload(), &p); err != nil {
+			return err
+		}
+		return client.Send(p.To, p.Subject, p.Body)
+	})
+}
+
+type AsyncClient struct {
+	q interface {
+		Enqueue(task *asynq.Task, opts ...asynq.Option) (string, error)
+	}
+}
+
+func NewAsyncClient(q interface {
+	Enqueue(task *asynq.Task, opts ...asynq.Option) (string, error)
+}) *AsyncClient {
+	return &AsyncClient{q: q}
+}
+
+// Send enqueues the email instead of sending it inline, so the caller (an
+// HTTP handler) returns in ~µs instead of blocking on SMTP. cmd/worker picks
+// it up and calls Client.Send.
+func (c *AsyncClient) Send(to, subject, body string) error {
+	task := NewSendEmailTask(sendEmailPayload{To: to, Subject: subject, Body: body})
+	_, err := c.q.Enqueue(task, asynq.MaxRetry(5))
+	return err
+}

package/templates/add/worker/internal/platform/queue/client.go.hbs

@@ -0,0 +1,31 @@
+package queue
+
+import (
+	"github.com/hibiken/asynq"
+)
+
+// Client enqueues tasks to Redis. Created by cmd/api; each domain or platform
+// package defines its own task types and calls Client.Enqueue.
+type Client struct {
+	inner *asynq.Client
+}
+
+func NewClient(redisURL string) (*Client, error) {
+	opt, err := asynq.ParseRedisURI(redisURL)
+	if err != nil {
+		return nil, err
+	}
+	return &Client{inner: asynq.NewClient(opt)}, nil
+}
+
+func (c *Client) Enqueue(task *asynq.Task, opts ...asynq.Option) (string, error) {
+	info, err := c.inner.Enqueue(task, opts...)
+	if err != nil {
+		return "", err
+	}
+	return info.ID, nil
+}
+
+func (c *Client) Close() error {
+	return c.inner.Close()
+}

package/templates/add/worker/internal/platform/queue/server.go.hbs

@@ -0,0 +1,68 @@
+package queue
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+
+	"github.com/hibiken/asynq"
+)
+
+// Server runs the background worker. Created by cmd/worker; handlers register
+// their task types on the mux before Start is called.
+type Server struct {
+	inner *asynq.Server
+	mux   *asynq.ServeMux
+}
+
+// slogAdapter wraps *slog.Logger to implement asynq.Logger. Asynq calls these
+// like the stdlib `log` package (a plain message, sometimes several args
+// meant to be concatenated) — fmt.Sprint joins them into one message string
+// rather than passing them as slog key-value pairs, which would otherwise
+// misinterpret a lone message argument as a key with no value.
+type slogAdapter struct {
+	inner *slog.Logger
+}
+
+func (a *slogAdapter) Debug(args ...interface{}) { a.inner.Debug(fmt.Sprint(args...)) }
+func (a *slogAdapter) Info(args ...interface{})  { a.inner.Info(fmt.Sprint(args...)) }
+func (a *slogAdapter) Warn(args ...interface{})  { a.inner.Warn(fmt.Sprint(args...)) }
+func (a *slogAdapter) Error(args ...interface{}) { a.inner.Error(fmt.Sprint(args...)) }
+func (a *slogAdapter) Fatal(args ...interface{}) { a.inner.Error(fmt.Sprint(args...)) }
+
+func NewServer(redisURL string) (*Server, error) {
+	opt, err := asynq.ParseRedisURI(redisURL)
+	if err != nil {
+		return nil, err
+	}
+	srv := &Server{
+		inner: asynq.NewServer(opt, asynq.Config{
+			Concurrency: 10,
+			Logger:      &slogAdapter{inner: slog.Default()},
+		}),
+		mux: asynq.NewServeMux(),
+	}
+	// Global error handler for tasks that panic or return a non-Retryable error.
+	srv.mux.Use(func(next asynq.Handler) asynq.Handler {
+		return asynq.HandlerFunc(func(ctx context.Context, task *asynq.Task) error {
+			err := next.ProcessTask(ctx, task)
+			if err != nil {
+				slog.Error("task failed", "type", task.Type(), "error", err)
+			}
+			return err
+		})
+	})
+	return srv, nil
+}
+
+func (s *Server) Handle(pattern string, handler asynq.Handler) {
+	s.mux.Handle(pattern, handler)
+}
+
+func (s *Server) Start() error {
+	return s.inner.Start(s.mux)
+}
+
+func (s *Server) Shutdown() {
+	s.inner.Shutdown()
+}

package/templates/create/base/.env.example.hbs

@@ -1,3 +1,8 @@
+# development | production — the one gate for prod behavior (config.IsProd):
+# hides error `details` from responses. Any other value makes the app refuse
+# to boot (so a typo can't silently downgrade prod).
+APP_ENV=development                 # prod: production
+
 PORT=8080
 DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable
 LOG_LEVEL=info
@@ -5,3 +10,18 @@ AUTO_MIGRATE=true
 DB_MAX_OPEN_CONNS=10
 DB_MAX_IDLE_CONNS=10
 DB_CONN_MAX_LIFETIME_MIN=5
+
+# read only by `go test`, never by cmd/api — a separate database on purpose: the
+# integration-test harness does DropTable+AutoMigrate on every run, which would
+# otherwise wipe the schema `make migrate-up` built in DB_DSN above.
+# Create it once: make db-create DB_NAME={{dbName}}_test
+TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable
+
+# comma-separated frontend origins allowed to call this API with credentials (cookies)
+CORS_ALLOWED_ORIGINS=http://localhost:3000
+{{#if observability}}
+
+# OTLP/HTTP endpoint for trace export (e.g. localhost:4318) — empty disables
+# tracing entirely: no exporter is created, no network calls are made
+OTEL_EXPORTER_OTLP_ENDPOINT=
+{{/if}}

package/templates/create/base/.github/workflows/ci.yml.hbs

@@ -14,7 +14,9 @@ jobs:
         env:
           POSTGRES_USER: postgres
           POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: {{dbName}}
+          # the test database, not the app's — CI only runs tests, and the
+          # integration harness drops/recreates its tables on every run
+          POSTGRES_DB: {{dbName}}_test
         ports:
           - 5432:5432
         options: >-
@@ -42,5 +44,5 @@ jobs:
           version: latest
 
       # TEST_DB_DSN not set: the default in handler_test.go already points at
-      # localhost:5432/{{dbName}} with postgres/postgres, matching the service above
+      # localhost:5432/{{dbName}}_test with postgres/postgres, matching the service above
       - run: go test ./...

package/templates/create/base/.gitignore.hbs

@@ -1,5 +1,7 @@
 app.db
 *.db
 .env
+.env.*
+!.env.example
 bin/
 docs/openapi.bundled.yaml

package/templates/create/base/Makefile.hbs

@@ -4,16 +4,32 @@ DB_USER ?= postgres
 DB_NAME ?= {{dbName}}
 PGPASSWORD ?= postgres
 
-.PHONY: run build test fmt vet lint tidy db-create db-drop migrate-up migrate-down{{#if openapiDocs}} openapi-bundle{{/if}}{{#if docker}} docker-up docker-down{{/if}}
+# which env file to load — defaults to .env (your local override, gitignored).
+# override to run against another file, e.g. copy .env.example to .env.production,
+# fill it in, then `make run ENV_FILE=.env.production`.
+#
+# Every target that needs config loads it the same way: drop whole-line comments
+# (^#) AND trailing ` # ...` comments — the sed only strips a `#` preceded by
+# whitespace, so a `#` inside a value (password, DSN) is kept. Without the sed,
+# `xargs` hands the comment's words to `export` too: `PORT=8080 # prod: PORT=80`
+# would export PORT twice and the comment's value would win. (Can't factor this
+# into a make variable: a `#` in a variable value starts a make comment; in a
+# recipe line it's passed to the shell untouched.)
+ENV_FILE ?= .env
+
+.PHONY: run build test fmt vet lint tidy db-create db-drop migrate-up migrate-down migrate-verify{{#if openapiDocs}} openapi-bundle{{/if}}{{#if docker}} docker-up docker-down{{/if}}
 
 run:
-	@[ -f .env ] && export $$(grep -v '^#' .env | xargs); go run ./cmd/api
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); go run ./cmd/api
 
 build:
 	go build -o bin/api ./cmd/api
 
+# loads ENV_FILE like every other target, so TEST_DB_DSN set there reaches the
+# integration tests. A bare `go test ./...` still works, but falls back to
+# whatever defaults the test files carry.
 test:
-	go test ./...
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); go test ./...
 
 fmt:
 	gofmt -w .
@@ -69,10 +85,19 @@ db-drop:
 	fi
 
 migrate-up:
-	migrate -path migrations -database "$$DB_DSN" up
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); migrate -path migrations -database "$$DB_DSN" up
 
 migrate-down:
-	migrate -path migrations -database "$$DB_DSN" down 1
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); migrate -path migrations -database "$$DB_DSN" down 1
+
+# runs up -> down-to-zero -> up against $DB_DSN to catch a bit-rotted down.sql
+# (one that no longer reverses cleanly) before you actually need a rollback.
+# point DB_DSN at a throwaway/test database first — this drops every table.
+migrate-verify:
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); \
+	migrate -path migrations -database "$$DB_DSN" up && \
+	migrate -path migrations -database "$$DB_DSN" down -all && \
+	migrate -path migrations -database "$$DB_DSN" up
 {{#if openapiDocs}}
 
 # docs/openapi.yaml is hand-written and split across sibling files via relative

package/templates/create/base/README.md.hbs

@@ -40,9 +40,13 @@ go mod tidy
 make run                           # AUTO_MIGRATE=true creates the schema automatically in dev
 ```
 
-`make run` loads `.env` if present (copy `.env.example` to `.env` to override
-defaults — the app itself just reads `os.Getenv`, no `.env` parsing at
-runtime).
+`make run`/`make test`/`make migrate-up`/`make migrate-down` load `.env` if
+present (copy `.env.example` to `.env` to override defaults — the app itself
+just reads `os.Getenv`, no `.env` parsing at runtime). Point them at another
+file with `ENV_FILE`: copy `.env.example` to `.env.production`, fill it in,
+then `make run ENV_FILE=.env.production`. Trailing `# ...` comments in the env
+file are stripped before loading, so a `# prod: ...` note next to a value is
+safe; a `#` inside a value (password, DSN) is kept.
 
 `make db-create` connects to Postgres at `DB_HOST`/`DB_PORT`/`DB_USER` (default:
 `localhost`/`5432`/`postgres`, matching `.env.example`) using the `psql`
@@ -68,15 +72,20 @@ make lint           # golangci-lint run (see .golangci.yml)
 make tidy           # go mod tidy
 make db-create       # create the database itself (safe to re-run)
 make db-drop         # drop the database
-make migrate-up      # apply migrations (needs $DB_DSN)
+make migrate-up      # apply migrations (reads DB_DSN from ENV_FILE)
 make migrate-down     # roll back one migration
+make migrate-verify   # up -> down-to-zero -> up, catches a broken down.sql (point DB_DSN at a throwaway DB)
 {{#if docker}}make docker-up       # docker compose up -d
 make docker-down     # docker compose down
 {{/if}}```
 
 ## Migrations
 
-Schema is managed with [golang-migrate](https://github.com/golang-migrate/migrate), files live in `migrations/`.
+Schema is managed with [golang-migrate](https://github.com/golang-migrate/migrate), files live in `migrations/`, named `<version>_<name>.{up,down}.sql`. `version` is a 14-digit UTC timestamp, not an incrementing counter — two people adding a migration off the same base branch get different filenames instead of both claiming the same number and colliding on merge. (`generate module` names its own migration the same way; existing sequential `0000NN_*` files from before this convention sort fine alongside timestamped ones either way.)
+
+```bash
+go-scaffold generate migration add_status_to_orders   # reserves migrations/<version>_add_status_to_orders.{up,down}.sql, TODO-stubbed — you write the SQL
+```
 
 ```bash
 brew install golang-migrate
@@ -84,16 +93,31 @@ brew install golang-migrate
 
 migrate -path migrations -database "$DB_DSN" up
 migrate -path migrations -database "$DB_DSN" down 1
-migrate create -ext sql -dir migrations -seq add_something
+migrate create -ext sql -dir migrations -seq=false add_something   # same as `go-scaffold generate migration`, if you'd rather not use the CLI
 ```
 
 **dev:** leave `AUTO_MIGRATE=true` (default) so GORM's AutoMigrate creates the schema quickly.
 **prod:** set `AUTO_MIGRATE=false` and run `migrate up` as a separate deploy step — versioned, has rollback (`down`), doesn't lock the table the way AutoMigrate does once there's real data.
 
+With `AUTO_MIGRATE=false`, the app checks the DB's applied migration version
+against the migration files baked into the binary (embedded at build time)
+before it starts serving traffic — a stale or half-applied schema fails fast
+at boot with a clear message, instead of failing later on whatever query
+happens to hit the missing column first:
+
+```text
+DB schema is at migration 3, this binary expects 5 — run `make migrate-up`
+```
+
+```bash
+make migrate-verify   # up -> down-to-zero -> up, catches a broken down.sql before you actually need a rollback (point DB_DSN at a throwaway DB first — this drops every table)
+```
+
 ## Env vars
 
 | var | default | notes |
 |---|---|---|
+| `APP_ENV` | `development` | `development` or `production` — **the prod gate**: hides error `details` from responses. App refuses to boot on any other value |
 | `PORT` | `8080` | |
 | `DB_DSN` | `postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable` | used by both GORM and the `migrate` CLI |
 | `LOG_LEVEL` | `info` | debug/info/warn/error |
@@ -101,17 +125,21 @@ migrate create -ext sql -dir migrations -seq add_something
 | `DB_MAX_OPEN_CONNS` | `10` | |
 | `DB_MAX_IDLE_CONNS` | `10` | |
 | `DB_CONN_MAX_LIFETIME_MIN` | `5` | minutes |
+| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000` | comma-separated frontend origins allowed to call this API with credentials (cookies) |
 
 ## Tests
 
 Integration tests (handler-level) run against a **real Postgres** instance (same engine as prod), each test in a transaction that's rolled back — no leftover rows. If the DB isn't reachable those tests **skip** (unit tests using a fake repo always run).
 
+They use a **separate `{{dbName}}_test` database**, not the one `DB_DSN` points at. That's deliberate: the harness runs `DropTable` + `AutoMigrate` on every real run, so pointing it at your dev database would wipe whatever `make migrate-up` built there — FK constraints and seed data included. Create it once:
+
 ```bash
 {{#if docker}}
 make docker-up      # local postgres first
 {{/if}}
+make db-create DB_NAME={{dbName}}_test
 make test
-# point at a different test DB: TEST_DB_DSN=postgres://... go test ./...
+# point somewhere else entirely: TEST_DB_DSN=postgres://... go test ./...
 ```
 
 ## Error payload
@@ -120,7 +148,7 @@ make test
 {"error":{"code":"VALIDATION_ERROR","message":"invalid input","details":{"email":"email"},"request_id":"a1b2..."}}
 ```
 
-`code` is machine-readable, `details` names the field that failed, `request_id` correlates with server logs (header `X-Request-ID`).
+`code` is machine-readable, `details` names the field that failed, `request_id` correlates with server logs (header `X-Request-ID`). `details` is **only returned outside production** (`APP_ENV` != `production`) — in prod it's stripped from every error so a direct caller can't learn the API's shape; the server log still has the full detail keyed by `request_id`.
 {{#if openapiDocs}}
 
 ## API spec