@nakedev/go-scaffold 0.1.3 → 0.3.0

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

@@ -45,21 +45,23 @@ hand-rolling anything that looks like scaffolding.
 
 ## Command quick reference
 
-- `go-scaffold generate module <name>` — model + dto + errors + repository +
-  service + handler + tests, wired into `cmd/api/main.go` (AutoMigrate +
-  route registration) and appended to `migrations/`. Use `--no-full` for a
-  bare skeleton (no default CRUD/routes) when you'd rather add endpoints one
-  at a time with `generate method`
+- `go-scaffold generate module <name>` — safe minimal model + errors +
+  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>]` —
   patches an *existing* module's handler + service (and repository, for a
   `get --get-mode one --field` lookup) in place; never overwrites a method
-  with the same name — pick a different one if it collides. Endpoint docs in
-  `docs/openapi.yaml` are **not** auto-updated for methods — the command
-  prints the route so you can add the spec entry by hand
-- `go-scaffold remove module <name>` — the inverse of `generate module`:
-  deletes the package and un-wires main.go / openapi.yaml / migrations. Use
-  this to drop a domain instead of hand-deleting the folder (a partial
-  hand-delete leaves duplicate wiring behind)
+  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 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,26 +1,46 @@
+# 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
 DB_NAME ?= {{dbName}}
 PGPASSWORD ?= postgres
+POSTGRES_CONTAINER ?=
 
 # 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.)
+# 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
@@ -29,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 .
@@ -40,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
 
@@ -47,14 +72,17 @@ tidy:
 # connects to the always-present "postgres" maintenance DB to run CREATE DATABASE,
 # since the target DB may not exist yet. Safe to re-run — skips if it already exists.
 # \gexec only works read from stdin, not through -c, hence the pipe.
-# no local psql? falls back to `docker exec` into whatever container is publishing
-# DB_PORT — the project's own `docker compose up`'d postgres, or an unrelated
-# shared Postgres container you already have running, either works the same way.
+# `POSTGRES_CONTAINER` selects an exact Docker container when no host psql is
+# installed; otherwise the fallback discovers a container publishing DB_PORT.
 # override DB_HOST/DB_PORT/DB_USER/DB_NAME/PGPASSWORD to point at a different server.
 db-create:
 	@if command -v psql >/dev/null 2>&1; then \
 		echo "SELECT 'CREATE DATABASE $(DB_NAME)' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '$(DB_NAME)')\gexec" | \
 			PGPASSWORD=$(PGPASSWORD) psql -h $(DB_HOST) -p $(DB_PORT) -U $(DB_USER) -d postgres && echo "SUCCESS! database $(DB_NAME) is ready"; \
+	elif [ -n "$(POSTGRES_CONTAINER)" ]; then \
+		echo "no local psql — using docker exec into $(POSTGRES_CONTAINER)"; \
+		echo "SELECT 'CREATE DATABASE $(DB_NAME)' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '$(DB_NAME)')\gexec" | \
+			docker exec -i -e PGPASSWORD=$(PGPASSWORD) $(POSTGRES_CONTAINER) psql -U $(DB_USER) -d postgres && echo "SUCCESS! database $(DB_NAME) is ready"; \
 	elif [ "$(DB_HOST)" = "localhost" ] || [ "$(DB_HOST)" = "127.0.0.1" ]; then \
 		container=$$(docker ps -q --filter "publish=$(DB_PORT)" | head -1); \
 		if [ -z "$$container" ]; then \
@@ -72,6 +100,8 @@ db-create:
 db-drop:
 	@if command -v psql >/dev/null 2>&1; then \
 		PGPASSWORD=$(PGPASSWORD) psql -h $(DB_HOST) -p $(DB_PORT) -U $(DB_USER) -d postgres -c "DROP DATABASE IF EXISTS $(DB_NAME);" && echo "SUCCESS! database $(DB_NAME) dropped"; \
+	elif [ -n "$(POSTGRES_CONTAINER)" ]; then \
+		docker exec -i -e PGPASSWORD=$(PGPASSWORD) $(POSTGRES_CONTAINER) psql -U $(DB_USER) -d postgres -c "DROP DATABASE IF EXISTS $(DB_NAME);" && echo "SUCCESS! database $(DB_NAME) dropped"; \
 	elif [ "$(DB_HOST)" = "localhost" ] || [ "$(DB_HOST)" = "127.0.0.1" ]; then \
 		container=$$(docker ps -q --filter "publish=$(DB_PORT)" | head -1); \
 		if [ -z "$$container" ]; then \
@@ -85,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

@@ -2,12 +2,15 @@
 
 Gin + GORM backend, scaffolded by [go-scaffold](https://github.com/nakedev/go-scaffold). Organized by feature (domain), Postgres-backed, schema managed with [golang-migrate](https://github.com/golang-migrate/migrate).
 
-This is a bare skeleton — no domain modules yet. Add one with:
+This project starts as a bare skeleton. Add a safe minimal domain with:
 
 ```bash
 go-scaffold generate module orders
 ```
 
+Add endpoints one at a time with `generate method`, or pass `--full` to opt
+into a CRUD skeleton whose DTO fields and business rules remain explicit TODOs.
+
 See `docs/architect/` for the conventions every generated module follows, and `AGENTS.md`/`CLAUDE.md` if you're working with an AI coding agent in this repo.
 
 ## Layout
@@ -24,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`
 ```
 
@@ -50,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.
 
@@ -73,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
@@ -129,17 +136,23 @@ make migrate-verify   # up -> down-to-zero -> up, catches a broken down.sql befo
 
 ## 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).
+Handler and service tests are fast unit tests: handlers depend on a narrow
+service interface, and services use function-backed repository stubs. Neither
+suite requires a database.
 
-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:
+Repository integration tests run against a **real Postgres** instance using
+the same versioned SQL migrations as production, each test in a transaction
+that's rolled back. Locally they skip when `TEST_DB_DSN` is unset; CI sets
+`REQUIRE_TEST_DB=true`, so a missing or unmigrated database fails instead of
+becoming a false-green skip. Use a separate `{{dbName}}_test` database:
 
 ```bash
 {{#if docker}}
 make docker-up      # local postgres first
 {{/if}}
 make db-create DB_NAME={{dbName}}_test
-make test
-# point somewhere else entirely: TEST_DB_DSN=postgres://... go test ./...
+make migrate-up-test
+TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable REQUIRE_TEST_DB=true go test ./...
 ```
 
 ## Error payload
@@ -170,4 +183,40 @@ Import `docs/openapi.bundled.yaml` instead. Tools that resolve `$ref` over HTTP
 go-scaffold generate module orders
 ```
 
-Scaffolds `internal/app/orders/` (model/dto/errors/repository/service/handler + tests), wires it into `cmd/api/main.go` (AutoMigrate, route registration), and appends a migration file. See `docs/architect/patterns.md` for the module shape and the rules for domains with foreign keys.
+Scaffolds the safe minimal `internal/app/order/` module, wires its empty route
+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
+	}
+}