@nakedev/go-scaffold 0.1.4 → 0.3.0

package/templates/create/base/.golangci.yml.hbs

@@ -5,12 +5,39 @@ version: "2"
 
 linters:
   enable:
+    - depguard
     - errcheck
     - govet
     - ineffassign
     - staticcheck
     - unused
   settings:
+    depguard:
+      # What keeps this a modular monolith rather than a pile of folders: a
+      # domain may not reach into another domain's package. It declares a
+      # narrow interface for what it needs and cmd/api/wiring.go supplies the
+      # concrete service — see docs/architect/patterns.md "Calling Another
+      # Domain's Logic". Without this, the first shortcut someone takes stays
+      # invisible until the coupling is everywhere.
+      #
+      # One rule per domain, written by `go-scaffold generate module`: depguard
+      # matches import paths as static prefixes and has no notion of "the
+      # domain this file belongs to", so denying internal/app wholesale would
+      # also reject a domain importing its own model/ subpackage. Each rule
+      # scopes itself with `files:` and allows exactly its own path.
+      #
+      # This only sees Go imports. A raw SQL JOIN into another domain's table
+      # couples just as hard and no linter can see it — that boundary comes
+      # from giving each domain its own schema.
+      rules:
+        wiring-flows-inward:
+          list-mode: lax
+          files:
+            - "**/internal/app/**"
+          deny:
+            - pkg: "{{goModule}}/cmd"
+              desc: a domain must not import cmd/ — wiring flows the other way
+        # go-scaffold:depguard-rules
     errcheck:
       exclude-functions:
         # gin.Context.Error()'s return value is intentionally never checked —

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

@@ -46,7 +46,7 @@ hand-rolling anything that looks like scaffolding.
 ## Command quick reference
 
 - `go-scaffold generate module <name>` — safe minimal model + errors +
-  repository + service/handler plumbing, wired into `cmd/api/main.go` and
+  repository + service/handler plumbing, wired into `cmd/api/wiring.go` and
   appended to `migrations/`. Add endpoints one at a time with `generate
   method`, or pass `--full` to opt into a CRUD skeleton with TODO DTO fields
 - `go-scaffold generate method <module> <name> --type <get|post|put|patch|delete> [--get-mode all|one] [--field <name>]` —
@@ -55,9 +55,13 @@ hand-rolling anything that looks like scaffolding.
   with the same name — pick a different one if it collides. With OpenAPI
   enabled it also writes a valid TODO path document and wires the index;
   replace placeholder schemas while implementing the method
-- `go-scaffold remove module <name>` — deletes the package and un-wires
-  main.go/OpenAPI while preserving immutable migrations and table data. Use
-  `generate migration drop_<table>` for an explicit reviewed data removal
+- `go-scaffold undo module <name>` — takes back a `generate module` that
+  shouldn't have happened (typo'd name, domain decided against): deletes the
+  package, un-wires main.go/OpenAPI, and deletes the module's migration files.
+  It refuses if those migrations are committed to git or already applied to
+  your database, since then they may exist somewhere this can't reach. Not for
+  retiring a domain that has shipped — that's `generate migration drop_<table>`
+  plus a reviewed data removal; the table is never dropped either way
 - Every route in this project is grouped under{{#if apiPrefix}} `/{{apiPrefix}}`{{else}} no prefix{{/if}}
   (set once at `create` time via `--api-prefix`) — there is no per-domain
   versioning; a breaking API change gets a new domain package or a new DTO

package/templates/create/base/Dockerfile.hbs

@@ -0,0 +1,42 @@
+# Build both binaries in one image, ship each from a separate stage — cmd/api
+# and cmd/worker are deployed as two processes, and neither needs the other's.
+#
+#   docker build --target api    -t {{projectName}}-api .
+#   docker build --target worker -t {{projectName}}-worker .
+#
+# The worker target only builds once `go-scaffold add worker` has created
+# cmd/worker; until then `--target api` is the only one that resolves.
+FROM golang:1.25-alpine AS build
+WORKDIR /src
+
+# Dependencies first: this layer is cached until go.mod/go.sum change, so an
+# ordinary code edit doesn't re-download the module graph.
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+# CGO off so the result runs on a distroless/scratch base with no libc.
+# -trimpath keeps build-machine paths out of panics; -s -w drops the symbol
+# table and DWARF, which is most of the binary size and nothing you can use in
+# production anyway.
+ENV CGO_ENABLED=0
+RUN go build -trimpath -ldflags="-s -w" -o /out/api ./cmd/api
+RUN if [ -d ./cmd/worker ]; then go build -trimpath -ldflags="-s -w" -o /out/worker ./cmd/worker; fi
+
+# nonroot, and no shell: there is nothing in this image to exec into if
+# something gets in. Debug with `docker run --entrypoint` against the build
+# stage instead.
+FROM gcr.io/distroless/static-debian12:nonroot AS api
+WORKDIR /app
+COPY --from=build /out/api /app/api
+# migrations/ is embedded in the binary (migrations/embed.go), so nothing to
+# copy for CheckMigrationVersion. docs/ is only served outside production.
+USER nonroot:nonroot
+EXPOSE 8080
+ENTRYPOINT ["/app/api"]
+
+FROM gcr.io/distroless/static-debian12:nonroot AS worker
+WORKDIR /app
+COPY --from=build /out/worker /app/worker
+USER nonroot:nonroot
+ENTRYPOINT ["/app/worker"]

package/templates/create/base/Makefile.hbs

@@ -1,3 +1,15 @@
+# Pinned dev-tool versions — one place, used by `make tools` and by CI, so a
+# lint rule or migration runner never behaves differently on someone's laptop
+# than it does on a pull request.
+#
+# ponytail: installed with `go install`, not tracked as a go.mod `tool`
+# directive — golang-migrate's CLI pulls a driver for every database it
+# supports and golangci-lint pulls its whole linter tree, which between them
+# turned this project's go.sum from 117 lines into 2,700. Tool pinning is not
+# worth that in a scaffold whose point is a clean starting project.
+MIGRATE_VERSION       ?= v4.19.1
+GOLANGCI_LINT_VERSION ?= v2.12.2
+
 DB_HOST ?= localhost
 DB_PORT ?= 5432
 DB_USER ?= postgres
@@ -9,19 +21,26 @@ POSTGRES_CONTAINER ?=
 # 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.)
+# Every target that needs config loads it the same way: `set -a` marks whatever
+# follows for export, the file is sourced, `set +a` stops.
+#
+# Sourcing rather than piping through xargs, which is what this used to do. The
+# shell already understands the format: `PORT=8080 # prod: 80` keeps 8080,
+# blank lines are nothing, and — the reason it changed — a quoted value with a
+# space in it survives. xargs word-split `SMTP_PASSWORD="two words"` into two
+# arguments and exported the wrong thing, silently.
+#
+# It does mean .env is executed, so `$(...)` in a value runs. That file is your
+# own gitignored config, and the alternative could not read half of it.
+#
+# (Can't factor this into a make variable: a `#` in a variable value starts a
+# make comment; in a recipe line it is 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}}
+.PHONY: tools run build test fmt vet lint tidy db-create db-drop migrate-up migrate-up-test migrate-down migrate-verify{{#if openapiDocs}} openapi-bundle{{/if}}{{#if docker}} docker-up docker-down{{/if}}
 
 run:
-	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); go run ./cmd/api
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; go run ./cmd/api
 
 build:
 	go build -o bin/api ./cmd/api
@@ -30,7 +49,7 @@ build:
 # integration tests. A bare `go test ./...` still works, but falls back to
 # whatever defaults the test files carry.
 test:
-	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); go test ./...
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; go test ./...
 
 fmt:
 	gofmt -w .
@@ -41,6 +60,11 @@ vet:
 lint:
 	golangci-lint run
 
+# install the pinned dev tools into $(go env GOPATH)/bin
+tools:
+	go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@$(MIGRATE_VERSION)
+	go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION)
+
 tidy:
 	go mod tidy
 
@@ -91,16 +115,22 @@ db-drop:
 	fi
 
 migrate-up:
-	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); migrate -path migrations -database "$$DB_DSN" up
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; migrate -path migrations -database "$$DB_DSN" up
+
+# same migration files, applied to TEST_DB_DSN instead of DB_DSN — run this
+# once after `make db-create DB_NAME=..._test` so repository_test.go files
+# see real tables instead of skipping (or failing, if REQUIRE_TEST_DB=true).
+migrate-up-test:
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; migrate -path migrations -database "$$TEST_DB_DSN" up
 
 migrate-down:
-	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); migrate -path migrations -database "$$DB_DSN" down 1
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; 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); \
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; \
 	migrate -path migrations -database "$$DB_DSN" up && \
 	migrate -path migrations -database "$$DB_DSN" down -all && \
 	migrate -path migrations -database "$$DB_DSN" up

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

@@ -27,8 +27,10 @@ internal/
 │   ├── apperror/               # central error type (status + payload)
 │   ├── dberr/                 # maps DB errors to constraint kind (IsDuplicate, IsForeignKey) — shared by every domain
 │   ├── httpx/                 # HTTP helpers shared by every domain (ParseID, BindErr)
-│   ├── middleware/            # RequestID, Logger (slog), Error
-│   └── pagination/             # parses ?limit=&offset=, response envelope
+│   ├── id/                    # UUID v7 generation (id.New) — app-side, not a DB default
+│   ├── middleware/            # RequestID, Logger (slog), Error, CORS
+│   ├── pagination/             # parses ?limit=&offset=, response envelope
+│   └── tx/                    # carries a transaction on the ctx (tx.Do / tx.From) so two repositories commit together
 └── app/                       # domain packages — empty until you `generate module`
 ```
 
@@ -53,13 +55,14 @@ 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`
-client — works the same whether Postgres came from `make docker-up` or an
-existing instance you already have running. Override any of
+client — works the same whether Postgres came from
+{{#if docker}}`make docker-up`{{else}}a container{{/if}} or an existing instance you already have
+running. Override any of
 `DB_HOST`/`DB_PORT`/`DB_USER`/`DB_NAME`/`PGPASSWORD` to point at a different
 server. If `psql` isn't installed locally and `DB_HOST` is `localhost`, it
 falls back to `docker exec` into whichever container is publishing
-`DB_PORT` — this project's own Postgres (`make docker-up` first) or any
-other Postgres container you already have running.
+`DB_PORT` — {{#if docker}}this project's own Postgres (`make docker-up` first) or any
+other Postgres container{{else}}any Postgres container{{/if}} you already have running.
 
 Server listens on `:8080` (override with `PORT`). Ctrl+C = graceful shutdown.
 
@@ -76,6 +79,7 @@ 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 (reads DB_DSN from ENV_FILE)
+make migrate-up-test  # same migrations, applied to TEST_DB_DSN instead — see Tests
 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
@@ -147,7 +151,7 @@ becoming a false-green skip. Use a separate `{{dbName}}_test` database:
 make docker-up      # local postgres first
 {{/if}}
 make db-create DB_NAME={{dbName}}_test
-DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable make migrate-up
+make migrate-up-test
 TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable REQUIRE_TEST_DB=true go test ./...
 ```
 
@@ -180,6 +184,39 @@ go-scaffold generate module orders
 ```
 
 Scaffolds the safe minimal `internal/app/order/` module, wires its empty route
-group/model into `cmd/api/main.go`, and appends a migration file. Add endpoints
+group/model into `cmd/api/wiring.go`, and appends a migration file. Add endpoints
 with `generate method`; use `--full` only when a CRUD skeleton is intentional.
 See `docs/architect/patterns.md` for the module shape and foreign-key rules.
+
+## Deploying
+
+Two processes, one image, one target each:
+
+```bash
+docker build --target api    -t {{projectName}}-api .
+docker build --target worker -t {{projectName}}-worker .    # once `add worker` exists
+```
+
+Both stages are distroless and run as `nonroot`, so there is no shell in either
+image. Debug against the `build` stage instead:
+`docker run --rm -it --entrypoint sh $(docker build -q --target build .)`.
+
+`cmd/api` serves HTTP. `cmd/worker` consumes the queue and is a separate
+deployment with **no port and no health endpoint** — scale it independently,
+and remember that not running it means queued mail is never sent, silently.
+
+Before the first deploy of a release:
+
+| | |
+|---|---|
+| `AUTO_MIGRATE` | leave unset — it defaults off when `APP_ENV=production`, and the app checks the applied migration version instead |
+| migrations | `migrate -path migrations -database "$DB_DSN" up` as its own step, before the new binaries roll |
+| `TRUSTED_PROXIES` | the CIDRs of your ingress, or the auth rate limiter keys on a header anyone can send |
+| `COOKIE_SECURE` | `true` · `COOKIE_SAMESITE=none` as well if your frontend is on a different site |
+| `/metrics` | reachable in-cluster for Prometheus, blocked at the ingress |
+| `JWT_SECRET`, `SMTP_HOST` | the app refuses to start in production without real values |
+
+The migration check is what makes the rollout order safe: a binary whose
+embedded migrations are ahead of the database refuses to start, while one
+that's behind logs a warning and serves — so migrating first, then rolling, is
+the order that never leaves a pod serving against a schema it doesn't know.

package/templates/create/base/cmd/api/main.go.hbs

@@ -1,141 +1,28 @@
 package main
 
 import (
-	"context"
-	"errors"
 	"log/slog"
-	"net/http"
 	"os"
-	"os/signal"
-	"syscall"
-	"time"
-
-	"{{goModule}}/internal/platform/database"
-{{#if observability}}
-	"{{goModule}}/internal/platform/telemetry"
-{{/if}}
-	"{{goModule}}/internal/shared/config"
-	"{{goModule}}/internal/shared/middleware"
-	// go-scaffold:imports
-
-	"github.com/gin-gonic/gin"
-{{#if observability}}
-	"github.com/prometheus/client_golang/prometheus/promhttp"
-{{/if}}
 )
 
+// main decides the exit code and nothing else. Everything it used to do lives
+// in run() — see wiring.go, which is this binary's composition root: the one
+// place that sees every module and hands them what they need.
+//
+// Two things that split buys. Deferred cleanup actually runs, because os.Exit
+// skips defers and this doesn't call it until run has returned — telemetry
+// shutdown and the signal handler used to be silently abandoned on a startup
+// error. And run() is an ordinary function returning an ordinary error, so a
+// test can call it.
+//
+// wiring.go is also the file `go-scaffold` patches. Keeping it out of main.go
+// means the first file you open to understand this binary is not the one that
+// grows a line every time a module is added.
 func main() {
-	cfg := config.Load()
-
-	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: parseLevel(cfg.LogLevel)}))
-	slog.SetDefault(logger)
-	// go-scaffold:config-checks
-
-{{#if observability}}
-	shutdownTelemetry, err := telemetry.Init(context.Background(), "{{projectName}}", cfg.OTELExporterEndpoint)
-	if err != nil {
-		logger.Error("init telemetry", "error", err)
-		os.Exit(1)
-	}
-	defer func() { _ = shutdownTelemetry(context.Background()) }()
-
-{{/if}}
-	db, err := database.Open(cfg)
-	if err != nil {
-		logger.Error("open db", "error", err)
-		os.Exit(1)
-	}
-
-	sqlDB, err := db.DB()
-	if err != nil {
-		logger.Error("db handle", "error", err)
-		os.Exit(1)
-	}
-	// go-scaffold:platform-init
-
-	if cfg.AutoMigrate {
-		// ponytail: AutoMigrate is for dev only (add-only, locks the table once data grows)
-		// prod: set AUTO_MIGRATE=false and run golang-migrate as versioned SQL instead
-		if err := db.AutoMigrate(
-			// go-scaffold:models
-		); err != nil {
-			logger.Error("migrate", "error", err)
-			os.Exit(1)
-		}
-	} else if err := database.CheckMigrationVersion(db); err != nil {
-		logger.Error("migration version check", "error", err)
+	if err := run(); err != nil {
+		// Correct before and after run() sets the JSON handler: slog's default
+		// writes to stderr, so a failure this early is still reported.
+		slog.Error("startup failed", "error", err)
 		os.Exit(1)
 	}
-
-	r := gin.New()
-	r.Use(gin.Recovery(), middleware.CORS(cfg.CORSAllowedOrigins), middleware.RequestID(), middleware.Logger(logger), middleware.Error(!cfg.IsProd()){{#if observability}}, middleware.Metrics(), middleware.Tracing("{{projectName}}"){{/if}})
-
-	// liveness = is the process up / readiness = ready for traffic (can it reach the DB)
-	r.GET("/livez", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"status": "ok"}) })
-	r.GET("/readyz", func(c *gin.Context) {
-		if err := sqlDB.PingContext(c.Request.Context()); err != nil {
-			c.JSON(http.StatusServiceUnavailable, gin.H{"status": "unavailable"})
-			return
-		}
-		// go-scaffold:readyz-checks
-		c.JSON(http.StatusOK, gin.H{"status": "ok"})
-	})
-{{#if observability}}
-	r.GET("/metrics", gin.WrapH(promhttp.Handler()))
-{{/if}}
-{{#if openapiDocs}}
-	// hand-written spec at docs/openapi.yaml, split across sibling files (common/, health/,
-	// <domain>/) via relative $ref — serve the whole tree under one prefix so a client that
-	// resolves $ref over HTTP (Scalar, Swagger UI, Redoc, Hey API pointed at a URL) can reach
-	// them too; StaticFile on just the index file would 404 on every $ref it follows.
-	r.Static("/docs", "./docs")
-{{/if}}
-
-	api := r.Group("/{{apiPrefix}}")
-	// go-scaffold:routes
-	_ = api // dropped once `generate module` registers the first route
-
-	srv := &http.Server{
-		Addr:         ":" + cfg.Port,
-		Handler:      r,
-		ReadTimeout:  10 * time.Second,
-		WriteTimeout: 10 * time.Second,
-		IdleTimeout:  60 * time.Second,
-	}
-
-	// graceful shutdown: catch SIGINT/SIGTERM, let in-flight requests finish before closing
-	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
-	defer stop()
-
-	go func() {
-		logger.Info("listening", "addr", srv.Addr)
-		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
-			logger.Error("server", "error", err)
-			os.Exit(1)
-		}
-	}()
-
-	<-ctx.Done()
-	logger.Info("shutting down")
-
-	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-	if err := srv.Shutdown(shutdownCtx); err != nil {
-		logger.Error("shutdown", "error", err)
-	}
-	// go-scaffold:shutdown
-	logger.Info("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/create/base/cmd/api/wiring.go.hbs

@@ -0,0 +1,161 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"{{goModule}}/internal/platform/database"
+	"{{goModule}}/internal/shared/config"
+	"{{goModule}}/internal/shared/middleware"
+	// go-scaffold:imports
+
+	"github.com/gin-gonic/gin"
+)
+
+// run is this binary's composition root — the only function that sees every
+// module and wires them to each other. Modules never import one another; a
+// domain that needs another's behaviour declares a narrow interface and gets
+// the concrete service from here (see docs/architect/patterns.md).
+//
+// It returns an error rather than calling os.Exit, so every defer below runs
+// on the way out and main() holds the only exit in the binary.
+//
+// This is the file `go-scaffold generate module` and `go-scaffold add *` patch,
+// at the // go-scaffold: markers. It grows with the system, which is what a
+// composition root is for.
+func run() error {
+	cfg := config.Load()
+
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: parseLevel(cfg.LogLevel)}))
+	slog.SetDefault(logger)
+	// go-scaffold:config-checks
+
+	db, err := database.Open(cfg)
+	if err != nil {
+		return fmt.Errorf("open db: %w", err)
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return fmt.Errorf("db handle: %w", err)
+	}
+	// go-scaffold:platform-init
+
+	// AutoMigrate creates tables but never the schema they live in — each
+	// domain gets its own (see model.go's TableName), so it has to exist
+	// before AutoMigrate runs. The versioned SQL migrations create the same
+	// schemas with CREATE SCHEMA IF NOT EXISTS, so this only matters for dev.
+	// go-scaffold:schemas
+
+	if cfg.AutoMigrate {
+		// ponytail: AutoMigrate is for dev only (add-only, locks the table once data grows)
+		// prod: set AUTO_MIGRATE=false and run golang-migrate as versioned SQL instead
+		if err := db.AutoMigrate(
+			// go-scaffold:models
+		); err != nil {
+			return fmt.Errorf("migrate: %w", err)
+		}
+	} else if err := database.CheckMigrationVersion(db); err != nil {
+		return fmt.Errorf("migration version check: %w", err)
+	}
+
+	r := gin.New()
+	// gin trusts every proxy by default, which makes c.ClientIP() — and so
+	// anything keyed on it, like the auth rate limiter — whatever
+	// X-Forwarded-For the caller felt like sending. Empty TRUSTED_PROXIES
+	// means trust nobody and use the peer address; set it to your load
+	// balancer's CIDRs when you actually run behind one.
+	if err := r.SetTrustedProxies(cfg.TrustedProxies); err != nil {
+		return fmt.Errorf("trusted proxies: %w", err)
+	}
+	r.Use(gin.Recovery(), middleware.CORS(cfg.CORSAllowedOrigins), middleware.RequestID(), middleware.Logger(logger), middleware.Error(!cfg.IsProd()))
+
+	// liveness = is the process up / readiness = ready for traffic (can it reach the DB)
+	r.GET("/livez", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"status": "ok"}) })
+	r.GET("/readyz", func(c *gin.Context) {
+		if err := sqlDB.PingContext(c.Request.Context()); err != nil {
+			c.JSON(http.StatusServiceUnavailable, gin.H{"status": "unavailable"})
+			return
+		}
+		// go-scaffold:readyz-checks
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+	// go-scaffold:extra-routes
+{{#if openapiDocs}}
+	// hand-written spec at docs/openapi.yaml, split across sibling files (common/, health/,
+	// <domain>/) via relative $ref — serve the whole tree under one prefix so a client that
+	// resolves $ref over HTTP (Scalar, Swagger UI, Redoc, Hey API pointed at a URL) can reach
+	// them too; StaticFile on just the index file would 404 on every $ref it follows.
+	//
+	// Not in production: this serves your whole API surface — every path,
+	// parameter and schema — to anyone who asks. Publish the spec deliberately
+	// (`make openapi-bundle`) rather than by leaving this on.
+	if !cfg.IsProd() {
+		r.Static("/docs", "./docs")
+	}
+{{/if}}
+
+	api := r.Group("/{{apiPrefix}}")
+	// go-scaffold:routes
+	_ = api // dropped once `generate module` registers the first route
+
+	srv := &http.Server{
+		Addr:         ":" + cfg.Port,
+		Handler:      r,
+		ReadTimeout:  10 * time.Second,
+		WriteTimeout: 10 * time.Second,
+		IdleTimeout:  60 * time.Second,
+	}
+
+	// graceful shutdown: catch SIGINT/SIGTERM, let in-flight requests finish before closing
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	// Buffered: if ListenAndServe fails before anything reads this, the
+	// goroutine still exits instead of blocking forever on an unread channel.
+	serverErr := make(chan error, 1)
+	go func() {
+		logger.Info("listening", "addr", srv.Addr)
+		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			serverErr <- err
+		}
+	}()
+
+	// A port already in use used to kill the process from inside that
+	// goroutine, skipping every defer on the way out. Now it comes back here.
+	select {
+	case err := <-serverErr:
+		return fmt.Errorf("server: %w", err)
+	case <-ctx.Done():
+	}
+	logger.Info("shutting down")
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if err := srv.Shutdown(shutdownCtx); err != nil {
+		logger.Error("shutdown", "error", err)
+	}
+	// go-scaffold:shutdown
+	logger.Info("stopped")
+	return nil
+}
+
+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/create/base/go.mod.hbs

@@ -3,9 +3,9 @@ module {{goModule}}
 go 1.25
 
 require (
-	github.com/gin-gonic/gin v1.10.0
-	github.com/go-playground/validator/v10 v10.20.0
+	github.com/gin-gonic/gin v1.10.1
+	github.com/go-playground/validator/v10 v10.30.3
 	github.com/google/uuid v1.6.0
-	gorm.io/driver/postgres v1.5.9
-	gorm.io/gorm v1.25.12
+	gorm.io/driver/postgres v1.6.2
+	gorm.io/gorm v1.31.2
 )