@nakedev/go-scaffold 0.8.1 → 0.10.0

package/README.md

@@ -325,14 +325,20 @@ CRUD modules contain the starter list/get/create/update/delete methods. Lean
 modules keep the endpoint surface small so it can be extended with
 generate method.
 
-Every generated list endpoint reads `?limit=&offset=&q=`, passes one
-`ports.ListFilter` from handler to application to repository, and answers the
-page beside the total the filter matched. The lists `add auth` and `add rbac`
-own use the same contract. `FindAll` calls `dbq.Search` with no columns, so
-`?q=` is accepted and ignored until you name the columns to search in
+Every generated list endpoint reads `?limit=&offset=&q=&sort=&order=`, passes
+one `ports.ListFilter` from handler to application to repository, and answers
+the page beside the total the filter matched. The lists `add auth` and
+`add rbac` own use the same contract. `FindAll` calls `dbq.Search` with no
+columns and carries a `dbq.Sort` with no columns either, so `?q=` and `?sort=`
+are accepted and ignored until you name them in
 `adapters/outbound/postgres/repository.go`; add further filters as fields on
 `ListFilter` rather than as parameters.
 
+`dbq.Sort` is why a sort name off the request never reaches the SQL — `ORDER
+BY` takes no bound parameter, so only a key of its `Columns` map is ever
+interpolated — and it adds the tiebreaker and `NULLS LAST` that every stable
+paged list needs.
+
 CQRS modules additionally contain:
 
 ~~~text
@@ -612,11 +618,11 @@ my-api/
 │   │   ├── config/                 # environment configuration
 │   │   ├── apperror/               # consistent application errors
 │   │   ├── dberr/                  # database error classification
-│   │   ├── dbq/                    # escaped contains-search for list filters
+│   │   ├── dbq/                    # escaped contains-search and whitelisted sort
 │   │   ├── httpx/                  # HTTP parsing and binding helpers
 │   │   ├── id/                     # UUID generation
 │   │   ├── middleware/             # request ID, logging, errors, CORS
-│   │   ├── pagination/             # pagination and ?q= parsing, responses
+│   │   ├── pagination/             # ?limit/offset/q/sort/order parsing, responses
 │   │   └── tx/                     # transaction context helpers
 │   └── app/                        # empty until generate module is used
 ├── migrations/                     # embedded, versioned SQL migrations

package/dist/commands/worker.js

@@ -130,8 +130,11 @@ function patchMakefile(makefilePath, opts) {
     // Without it, .env.example's own `APP_ENV=development  # prod: production`
     // reaches `export` as a bare `#` and prints an error on every run.
     const loadEnv = "@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a;";
-    const targets = "\n# run both API + worker in one terminal — Ctrl+C kills both\n" +
-        "dev:\n" +
+    const targets = "\n# run both API + worker in one terminal — Ctrl+C kills both.\n" +
+        "#\n" +
+        "# migrate-up first, for the same reason `run` does it: cmd/api refuses to\n" +
+        "# boot against a database behind the migrations it embeds.\n" +
+        "dev: migrate-up\n" +
         `\t${loadEnv} \\\n` +
         "\t(trap 'kill 0' SIGINT SIGTERM; \\\n" +
         "\t go run ./cmd/api & \\\n" +

package/dist/utils/auth-patcher.js

@@ -113,7 +113,11 @@ function patchMainGoForAuth(mainGoPath, w) {
     const importLine = `"${goModule}/internal/app/user"`;
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
     const modelImportLine = `usermodel "${goModule}/internal/app/user/adapters/outbound/postgres"`;
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    // Only the development AutoMigrate list ever used this alias, so it is only
+    // an import where that list still exists — see the guard further down.
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    }
     if (w.worker) {
         const queueImportLine = `"${goModule}/internal/platform/queue"`;
         content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, queueImportLine, queueImportLine);
@@ -166,7 +170,13 @@ function patchMainGoForAuth(mainGoPath, w) {
         '\treturn fmt.Errorf("create schema user_svc: %w", err)',
         "}",
     ].join("\n");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS user_svc");
+    // The development AutoMigrate bootstrap is gone from the template, and with
+    // it the schema/model markers. A project scaffolded before that still has
+    // them, and still wants its tables registered there — so these stay, guarded
+    // by the marker's presence rather than deleted. New projects skip them.
+    if ((0, marker_patch_1.hasMarker)(content, SCHEMA_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS user_svc");
+    }
     const migrateLines = [
         "&usermodel.User{},",
         "&usermodel.UserEmail{},",
@@ -178,8 +188,10 @@ function patchMainGoForAuth(mainGoPath, w) {
     // live in Redis, so reset/verification can share the user transaction.
     migrateLines.push("&usermodel.AuthToken{},");
     migrateLines.push("&usermodel.MFAEnrollment{},", "&usermodel.MFAChallenge{},", "&usermodel.MFARecoveryCode{},");
-    for (const line of migrateLines) {
-        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        for (const line of migrateLines) {
+            content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
+        }
     }
     // Keep auth construction inside the feature package. The root only chooses
     // shared infrastructure and registers the resulting handler.

package/dist/utils/hexagonal-method-patcher.js

@@ -140,7 +140,13 @@ function handlerMethod(naming, method, opts, cqrs, routeReceiver, errorMapper, a
             body: [
                 `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
                 `\tp := pagination.Parse(c)`,
-                `\tfilter := ports.ListFilter{Search: p.Search, Limit: p.Limit, Offset: p.Offset}`,
+                `\tfilter := ports.ListFilter{`,
+                `\t\tSearch: p.Search,`,
+                `\t\tSort:   p.Sort,`,
+                `\t\tDesc:   p.Desc,`,
+                `\t\tLimit:  p.Limit,`,
+                `\t\tOffset: p.Offset,`,
+                `\t}`,
                 `\titems, total, err := ${receiver}.${method.pascalName}(c.Request.Context(), filter)`,
                 `\tif err != nil {`,
                 `\t\tc.Error(${errorMapper}(err))`,

package/dist/utils/main-patcher.js

@@ -39,10 +39,11 @@ function mainGoLines(patch) {
     return {
         importLine: `"${patch.goModule}/internal/app/${patch.modulePath}"`,
         modelImportLine: `${modelAlias} "${patch.goModule}/internal/app/${patch.modulePath}/adapters/outbound/postgres"`,
-        // Development schema bootstrap creates tables but not the schema they live in — see
-        // the comment on go-scaffold:schemas in main.go.hbs. One Exec per schema,
+        // Legacy only: projects generated before the development AutoMigrate
+        // bootstrap was removed still have the schema marker, and their tables are
+        // created by GORM rather than by the migration. One Exec per schema,
         // guarded by its own sentinel so two modules sharing a schema name only
-        // ever produce one line (not expected today, but cheap to keep safe).
+        // ever produce one line.
         schemaLines: [
             `if err := db.Exec("CREATE SCHEMA IF NOT EXISTS ${patch.schemaName}").Error; err != nil {`,
             `\treturn fmt.Errorf("create schema ${patch.schemaName}: %w", err)`,
@@ -73,7 +74,9 @@ function assertMainGoPatchable(mainGoPath) {
         throw new Error(`${mainGoPath} not found — this doesn't look like a go-scaffold project`);
     }
     const content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
-    const missing = [IMPORT_MARKER, SCHEMA_MARKER, MODEL_MARKER, ROUTE_MARKER].filter((m) => !(0, marker_patch_1.hasMarker)(content, m));
+    // Not SCHEMA_MARKER/MODEL_MARKER: those belong to the development
+    // AutoMigrate bootstrap, which newer projects do not have.
+    const missing = [IMPORT_MARKER, ROUTE_MARKER].filter((m) => !(0, marker_patch_1.hasMarker)(content, m));
     if (missing.length) {
         throw new Error(`cmd/api/wiring.go is missing the marker comment${missing.length > 1 ? "s" : ""} this command patches at:\n` +
             missing.map((m) => `  ${m}`).join("\n") +
@@ -94,9 +97,17 @@ function patchMainGo(mainGoPath, patch) {
     // folder was deleted (main.go still wired) is a no-op, not a dup that
     // panics gin at startup.
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaLines, schemaSentinel);
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, migrateLine, migrateLine);
+    // The development AutoMigrate bootstrap is gone from the template, and with
+    // it the schema/model markers. A project scaffolded before that still has
+    // them, and still wants its tables registered there — so these stay, guarded
+    // by the marker's presence rather than deleted. New projects skip them.
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, migrateLine, migrateLine);
+    }
+    if ((0, marker_patch_1.hasMarker)(content, SCHEMA_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaLines, schemaSentinel);
+    }
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, ROUTE_MARKER, routeLine, routeLine);
     content = (0, marker_patch_1.removeLines)(content, [UNUSED_API_LINE]);
     fs_extra_1.default.writeFileSync(mainGoPath, content);

package/dist/utils/rbac-patcher.js

@@ -167,16 +167,27 @@ function patchMainGoForRbac(mainGoPath, goModule, store, worker) {
     const importLine = `"${goModule}/internal/app/role"`;
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
     const modelImportLine = `rolepostgres "${goModule}/internal/app/role/adapters/outbound/postgres"`;
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    // Only the development AutoMigrate list ever used this alias.
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    }
     const schemaBlock = [
         'if err := db.Exec("CREATE SCHEMA IF NOT EXISTS role_svc").Error; err != nil {',
         '\treturn fmt.Errorf("create schema role_svc: %w", err)',
         "}",
     ].join("\n");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS role_svc");
+    // The development AutoMigrate bootstrap is gone from the template, and with
+    // it the schema/model markers. A project scaffolded before that still has
+    // them, and still wants its tables registered there — so these stay, guarded
+    // by the marker's presence rather than deleted. New projects skip them.
+    if ((0, marker_patch_1.hasMarker)(content, SCHEMA_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS role_svc");
+    }
     const migrateLines = ["&rolepostgres.Role{},", "&rolepostgres.Permission{},", "&rolepostgres.RolePermission{},"];
-    for (const line of migrateLines) {
-        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        for (const line of migrateLines) {
+            content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
+        }
     }
     const wiring = { goModule, queueBackend: "river", store, worker };
     const authRouteLine = (0, auth_patcher_1.authHandlerLineFor)(wiring);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler.go.hbs

@@ -157,7 +157,13 @@ func (h *Handler) adminListUsers(c *gin.Context) {
 	p := pagination.Parse(c)
 	// One struct all the way down, so a filter added later is a field on
 	// ports.ListFilter and not a new argument on the three signatures below.
-	filter := ports.ListFilter{Search: p.Search, Limit: p.Limit, Offset: p.Offset}
+	filter := ports.ListFilter{
+		Search: p.Search,
+		Sort:   p.Sort,
+		Desc:   p.Desc,
+		Limit:  p.Limit,
+		Offset: p.Offset,
+	}
 	items, total, err := h.svc.List(c.Request.Context(), filter)
 	if err != nil {
 		c.Error(toHTTPError(err))

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/repository.go.hbs

@@ -77,6 +77,25 @@ func (r *Repository) UpdateUser(ctx context.Context, user *domain.User) error {
 	}))
 }
 
+// sortable is the whole of what ?sort= may say on the admin user list: dbq.Sort
+// resolves the requested name against Columns, so nothing off the request is
+// ever interpolated into the ORDER BY.
+var sortable = dbq.Sort{
+	Columns: map[string]string{
+		"name":       "name",
+		"role":       "role",
+		"created_at": "created_at",
+		// The address lives one table over, and only one row per user is
+		// primary (idx_user_emails_primary), so the subquery answers exactly
+		// one value. Correlated, so it runs per matching row — fine for a
+		// staff table; make it a LEFT JOIN on that index if this ever pages
+		// thousands, and give the query its own SELECT list when you do.
+		"email": "(SELECT e.email FROM user_svc.user_emails e WHERE e.user_id = user_svc.users.id AND e.is_primary)",
+	},
+	Default:  "created_at desc",
+	Tiebreak: "id",
+}
+
 // FindAll answers one page of the filter and how many accounts it matched
 // altogether. Two queries for that, because a count over a LIMITed query would
 // only ever count the page.
@@ -104,10 +123,12 @@ func (r *Repository) FindAll(ctx context.Context, filter ports.ListFilter) ([]do
 	}
 
 	var rows []User
-	// id breaks ties in created_at: without it two accounts created in the
-	// same instant can swap between page 1 and page 2, showing one twice and
-	// hiding the other.
-	err := matching().Order("created_at desc, id").Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error
+	// Newest account first until a client asks for something else, and always
+	// with the tiebreaker sortable carries: without it two accounts created in
+	// the same instant can swap between page 1 and page 2, showing one twice
+	// and hiding the other.
+	order := sortable.OrderBy(filter.Sort, filter.Desc)
+	err := matching().Order(order).Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error
 	if err != nil {
 		return nil, 0, persistenceError(err)
 	}

package/templates/add/auth/internal/app/user/ports/repository.go.hbs

@@ -21,6 +21,11 @@ type ListFilter struct {
 	// Search is ?q= as shared/pagination parsed it, matched against the name
 	// and the primary email address.
 	Search string
+	// Sort is ?sort= and Desc is ?order=desc, both as shared/pagination parsed
+	// them. Which column names are accepted is the repository's to say — see
+	// the dbq.Sort beside its FindAll.
+	Sort   string
+	Desc   bool
 	Limit  int
 	Offset int
 }

package/templates/add/auth/migrations/create_auth_tokens.up.sql.hbs

@@ -17,8 +17,8 @@ CREATE TABLE user_svc.auth_tokens (
     last_used_at TIMESTAMPTZ NOT NULL DEFAULT now()
 );
 
--- Named to match model.AuthToken's own `index:` tags exactly, so the
--- development bootstrap and production migration describe the same indexes.
+-- Named to match model.AuthToken's own `index:` tags exactly, so the Go model
+-- and the schema that actually exists describe the same indexes.
 CREATE INDEX idx_auth_tokens_user_kind ON user_svc.auth_tokens (user_id, kind);
 CREATE INDEX idx_auth_tokens_expires_at ON user_svc.auth_tokens (expires_at);
 CREATE INDEX idx_auth_tokens_absolute_expires_at ON user_svc.auth_tokens (absolute_expires_at);

package/templates/add/rbac/docs/users.yaml.hbs

@@ -7,9 +7,14 @@ get:
     - $ref: '../common/parameters.yaml#/Limit'
     - $ref: '../common/parameters.yaml#/Offset'
     - $ref: '../common/parameters.yaml#/Search'
+    - $ref: '../common/parameters.yaml#/Sort'
+    - $ref: '../common/parameters.yaml#/Order'
   responses:
     "200":
-      description: "paginated list; `q` matches name and primary email"
+      description: >-
+        paginated list; `q` matches name and primary email, and `sort` takes
+        name, email, role or created_at — anything else is the default order,
+        newest account first
       content:
         application/json:
           schema:

package/templates/create/base/.claude/skills/go-scaffold/SKILL.md.hbs

@@ -329,10 +329,13 @@ go-scaffold add auth --store postgres --browser-topology same-site --defaults --
 
 - APP_ENV is the only environment gate and accepts development or production.
   Do not reintroduce an AUTO_MIGRATE setting.
-- Development may use the convenience db.AutoMigrate(...) bootstrap.
-  Production must never bootstrap or mutate schema at API startup. Apply
-  versioned SQL with make migrate-up; the startup version check must fail
-  fast for a behind or dirty database.
+- The schema comes from migrations/ in every environment, development
+  included. Apply it with make migrate-up; the startup version check fails
+  fast for a behind or dirty database. Never bootstrap or mutate schema at API
+  startup, and do not add a db.AutoMigrate(...) convenience for development:
+  GORM builds tables from the Go structs, so it produces none of the CHECK
+  constraints, foreign keys or seeded rows the SQL carries, and it silently
+  adds columns to an already-migrated database.
 - Use generate migration for schema changes outside a new module, write and
   review both migration directions, and test them against a disposable DB.
 - Keep SQL, Redis, queue, mail, and other external resources under the

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

@@ -64,6 +64,15 @@ jobs:
             migrate -path migrations -database "$DB_DSN" up
           fi
 
+      # up -> down -all -> up. The only check that catches a down.sql that has
+      # stopped reversing its up.sql, which is otherwise discovered during a
+      # rollback — the worst moment to find out. Runs against the test database
+      # and leaves it migrated up for the steps below.
+      - name: Verify migrations reverse cleanly
+        env:
+          TEST_DB_DSN: postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable
+        run: make migrate-verify
+
       - name: Test (required PostgreSQL integration tests cannot skip)
         env:
           TEST_DB_DSN: postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable

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

@@ -160,14 +160,46 @@ endpoint is production-ready.
 
 - `APP_ENV` is the single environment gate and accepts only `development` or
   `production`. Do not add a parallel flag such as `AUTO_MIGRATE`.
-- Development may use the convenience `db.AutoMigrate(...)` path for the
-  models registered by the generator. Production must never bootstrap or
-  mutate schema at API startup: apply versioned SQL with
-  `make migrate-up`, then let the startup migration-version check fail fast if
-  the database is behind or dirty.
+- **The schema comes from `migrations/` in every environment, development
+  included.** `cmd/api/wiring.go` runs the migration-version check and nothing
+  else: apply versioned SQL with `make migrate-up`, and let the check fail
+  fast when the database is behind or dirty. Never bootstrap or mutate schema
+  at API startup, and do not reintroduce a `db.AutoMigrate(...)` convenience
+  for development — GORM builds tables from the Go structs, so it writes none
+  of the CHECK constraints, none of the foreign keys and none of the seeded
+  rows a migration carries, and it is additive over an already-migrated
+  database, so a column a model has and a migration does not shows up on one
+  developer's machine and nowhere else.
 - Any schema change is a reviewed pair of versioned files in `migrations/`.
   Use `go-scaffold generate migration <name>` for changes outside a new
   module, write both directions, and test them against a disposable database.
+  Write the SQL first and the Go struct second: the SQL is what exists, the
+  struct is Go's view of it, and doing it the other way round feels finished
+  while the database still has nothing.
+- **A destructive change takes two deploys, never one.** During a rolling
+  deploy the old binary and the new one serve traffic at the same time, so a
+  migration has to be readable by the version of the code still running.
+  `CheckMigrationVersion` is built for that order — a database ahead of the
+  binary is a warning, behind it is fatal — which only works if migrations go
+  out first and stay backward compatible.
+
+  | change | deploys |
+  |---|---|
+  | add a nullable column, add a table, add an index | 1 |
+  | add `NOT NULL` with a `DEFAULT` | 1 — but it rewrites the table, so check its size first |
+  | rename a column | **2** |
+  | drop a column or a table | **2** |
+  | change a column's type | **2** |
+
+  The two are *expand* then *contract*: add the new shape and have the code
+  write both and prefer the new one; deploy that everywhere; only then drop the
+  old shape. `DROP COLUMN` in one round pulls the floor out from under the pods
+  still serving requests.
+- `make migrate-verify` (up → down -all → up) runs in CI and is the only thing
+  that catches a `down.sql` which has quietly stopped reversing its `up.sql`.
+  Without it that is found during a rollback, which is the worst moment to find
+  out. Never run it against a database whose data matters — `down -all` means
+  it.
 - Keep `*sql.DB`, Redis, queue, mail, and other external resources owned by
   their composition root. Close them on every exit path and preserve the
   signal-driven graceful shutdown; do not call `os.Exit` from a goroutine or

package/templates/create/base/Makefile.hbs

@@ -39,7 +39,12 @@ ENV_FILE ?= .env
 
 .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:
+# migrate-up first, because cmd/api refuses to boot against a database that is
+# behind the migrations it embeds. The schema is the migrations' in every
+# environment — this is the step that would otherwise be a db.AutoMigrate
+# bootstrap, except it applies the same SQL production gets, constraints and
+# seeded rows and all.
+run: migrate-up
 	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; go run ./cmd/api
 
 build:
@@ -115,26 +120,41 @@ db-drop:
 		exit 1; \
 	fi
 
+# A project has no migrations until its first `generate module` or `add auth`,
+# and `migrate up` treats an empty directory as an error rather than as nothing
+# to do. `run` depends on this target, so without the guard the very first
+# `make run` of a fresh scaffold fails on a database that is already correct.
 migrate-up:
-	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; migrate -path migrations -database "$$DB_DSN" up
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; \
+	if ! ls migrations/*.up.sql >/dev/null 2>&1; then echo "no migrations yet — nothing to apply"; exit 0; fi; \
+	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
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; \
+	if ! ls migrations/*.up.sql >/dev/null 2>&1; then echo "no migrations yet — nothing to apply"; exit 0; fi; \
+	migrate -path migrations -database "$$TEST_DB_DSN" up
 
 migrate-down:
 	@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.
+# runs up -> down-to-zero -> up to catch a bit-rotted down.sql (one that no
+# longer reverses cleanly) before you actually need a rollback.
+#
+# TEST_DB_DSN, not DB_DSN: this drops every table, and it used to say "point
+# DB_DSN at a throwaway database first" — advice its own recipe made impossible
+# to follow, because the .env sourced on the line below overwrites whatever
+# DB_DSN the caller set on the way in. The test database is the one that is
+# meant to be destroyed, so it is the one named here.
 migrate-verify:
 	@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
+	if ! ls migrations/*.up.sql >/dev/null 2>&1; then echo "no migrations yet — nothing to apply"; exit 0; fi; \
+	: "$${TEST_DB_DSN:?TEST_DB_DSN is required — migrate-verify drops every table and will not guess a database}"; \
+	migrate -path migrations -database "$$TEST_DB_DSN" up && \
+	migrate -path migrations -database "$$TEST_DB_DSN" down -all && \
+	migrate -path migrations -database "$$TEST_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

@@ -83,7 +83,7 @@ go mod tidy
 {{#if worker}}{{#if (eq queue "river")}}make river-migrate                 # create River's job tables before queued mail
 {{else}}# start Redis and set REDIS_URL before running the worker
 {{/if}}{{/if}}
-make run                           # APP_ENV=development enables the convenience schema bootstrap
+make run                           # needs `make migrate-up` first — the schema is the migrations'
 ```
 
 `make run`/`make test`/`make migrate-up`/`make migrate-down` load `.env` if
@@ -154,9 +154,9 @@ migrate -path migrations -database "$DB_DSN" down 1
 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:** `APP_ENV=development` enables the convenience table bootstrap.
-**prod:** `APP_ENV=production` never bootstraps or mutates the schema; run
-`migrate up` as a separate deploy step — versioned and rollback-capable.
+**Every environment:** the schema comes from `migrations/`. Nothing
+bootstraps or mutates it at startup; run `migrate up` as its own step —
+versioned and rollback-capable — and the app refuses to boot until you have.
 
 In production, the app checks the DB's applied migration version
 against the migration files baked into the binary (embedded at build time)
@@ -306,7 +306,7 @@ Before the first deploy of a release:
 
 | | |
 |---|---|
-| `APP_ENV` | `production` | production disables schema bootstrap and requires the applied migration version |
+| `APP_ENV` | `production` | production hides internal error details; the applied migration version is required in every environment |
 | 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 |

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

@@ -54,19 +54,21 @@ func run() error {
 	}()
 	// go-scaffold:platform-init
 
-	if !cfg.IsProd() {
-		// Development boot creates tables but never the schema they live in — each
-		// domain gets its own (see the outbound postgres model's TableName), so it has to exist
-		// before the bootstrap runs. Production runs the versioned SQL migrations
-		// instead, so this entire branch is skipped there.
-		// go-scaffold:schemas
-
-		if err := db.AutoMigrate(
-			// go-scaffold:models
-		); err != nil {
-			return fmt.Errorf("migrate: %w", err)
-		}
-	} else if err := database.CheckMigrationVersion(db); err != nil {
+	// The schema comes from migrations/ in every environment, development
+	// included: `make migrate-up` applies it, and this refuses to boot when the
+	// database is behind or dirty.
+	//
+	// There is deliberately no db.AutoMigrate bootstrap for development. GORM
+	// builds tables from the Go structs, so it writes none of the CHECK
+	// constraints, none of the foreign keys and none of the seeded rows a
+	// migration carries — a schema that only looks like production's, on which
+	// a seeded catalogue is simply empty. It is also additive over an
+	// already-migrated database, so a column a model has and a migration does
+	// not appears on the developer's machine and nowhere else.
+	//
+	// Every migration creates the schema its tables live in, so nothing here
+	// needs to.
+	if err := database.CheckMigrationVersion(db); err != nil {
 		return fmt.Errorf("migration version check: %w", err)
 	}
 

package/templates/create/base/internal/platform/database/database.go.hbs

@@ -76,6 +76,14 @@ func CheckMigrationVersion(db *gorm.DB) error {
 		}
 	}
 
+	// A scaffold that has not generated a module or added auth yet embeds no
+	// migrations, so there is no schema_migrations table to read and nothing
+	// to compare against. That is a project with no schema, not a project
+	// whose schema is behind.
+	if latest == 0 {
+		return nil
+	}
+
 	var version int
 	var dirty bool
 	row := db.Raw("SELECT version, dirty FROM schema_migrations").Row()

package/templates/create/base/internal/shared/dbq/dbq.go.hbs

@@ -45,3 +45,51 @@ func Search(db *gorm.DB, term string, cols ...string) *gorm.DB {
 	// narrowing it.
 	return db.Where("("+strings.Join(conds, " OR ")+")", args...)
 }
+
+// Sort is a list endpoint's ordering contract: the columns it accepts, the
+// order it has before anyone asks for one, and the column that breaks ties.
+// Declare it once per repository, beside the FindAll that uses it.
+type Sort struct {
+	// Columns maps the names the API accepts to the SQL each one means, and is
+	// the whole of what can reach the clause: ORDER BY takes no bound
+	// parameter, so a ?sort= that is not a key here is never interpolated. A
+	// value the table does not hold — an address one table over — is a
+	// subquery rather than a join, which would need its own SELECT list to
+	// keep Find scanning the right row.
+	Columns map[string]string
+	// Default is the order for a request that asked for nothing Columns knows,
+	// written without the tiebreaker: OrderBy adds it.
+	Default string
+	// Tiebreak is a column unique enough to page by, usually the primary key.
+	// Without it two rows equal on the sorted column can swap places between
+	// page 1 and page 2, showing one twice and hiding the other. Leave it empty
+	// only when Columns and Default are unique on their own.
+	Tiebreak string
+}
+
+// OrderBy resolves what the request asked for into an ORDER BY clause:
+//
+//	q = q.Order(thingSort.OrderBy(filter.Sort, filter.Desc))
+//
+// Sorted columns get NULLS LAST in both directions, because a row with no
+// value is missing an answer rather than holding the largest one — the account
+// that has never signed in belongs at the bottom whichever way the column is
+// pointed. It is a no-op on a column that cannot be null.
+func (s Sort) OrderBy(sort string, desc bool) string {
+	clause := s.Default
+	if col, ok := s.Columns[sort]; ok {
+		dir := "asc"
+		if desc {
+			dir = "desc"
+		}
+		clause = col + " " + dir + " NULLS LAST"
+	}
+	switch {
+	case s.Tiebreak == "":
+		return clause
+	case clause == "":
+		return s.Tiebreak
+	default:
+		return clause + ", " + s.Tiebreak
+	}
+}

package/templates/create/base/internal/shared/dbq/dbq_test.go.hbs

@@ -64,3 +64,37 @@ func TestSearchWithoutATermIsANoOp(t *testing.T) {
 		t.Errorf("empty term still filtered: %s", stmt.SQL.String())
 	}
 }
+
+// The whitelist is the security boundary: ?sort= comes off the request, and
+// ORDER BY takes no bound parameter. The rest is the two rules every list gets
+// for free — a tiebreaker, and empty values last.
+func TestSortOrderBy(t *testing.T) {
+	sorter := Sort{
+		Columns:  map[string]string{"name": "name", "seen_at": "seen_at"},
+		Default:  "created_at desc",
+		Tiebreak: "id",
+	}
+	for _, tc := range []struct {
+		sort string
+		desc bool
+		want string
+	}{
+		{"name", false, "name asc NULLS LAST, id"},
+		{"seen_at", true, "seen_at desc NULLS LAST, id"},
+		// Nobody asked for an order.
+		{"", false, "created_at desc, id"},
+		// A name that is not on the list is the default order, not SQL.
+		{"name; DROP TABLE things --", true, "created_at desc, id"},
+	} {
+		if got := sorter.OrderBy(tc.sort, tc.desc); got != tc.want {
+			t.Errorf("OrderBy(%q, %v) = %q, want %q", tc.sort, tc.desc, got, tc.want)
+		}
+	}
+
+	// A table keyed by something unique on its own needs no tiebreaker, and
+	// must not be given one it has no column for.
+	byCode := Sort{Columns: map[string]string{"name": "name"}, Tiebreak: "code"}
+	if got := byCode.OrderBy("", false); got != "code" {
+		t.Errorf("no default and no sort should be the tiebreaker alone, got %q", got)
+	}
+}

package/templates/create/base/internal/shared/pagination/pagination.go.hbs

@@ -24,10 +24,17 @@ type Params struct {
 	// Search is ?q= trimmed, empty when the caller sent none — so a repository
 	// can pass it straight to dbq.Search, which no-ops on an empty term.
 	Search string
+	// Sort is ?sort=, the column the client asked to be ordered by, and Desc
+	// is ?order=desc. Nothing is validated here on purpose: which names an
+	// endpoint accepts is its repository's to say, and dbq.Sort is where that
+	// whitelist is applied — a name it does not know falls back to the list's
+	// own order rather than failing the request.
+	Sort string
+	Desc bool
 }
 
-// Parse reads ?limit=&offset=&q= off the request so every feature parses the
-// same way.
+// Parse reads ?limit=&offset=&q=&sort=&order= off the request so every feature
+// parses the same way.
 func Parse(c *gin.Context) Params {
 	p := Params{Limit: defaultLimit}
 	if v, err := strconv.Atoi(c.Query("limit")); err == nil && v > 0 {
@@ -47,6 +54,10 @@ func Parse(c *gin.Context) Params {
 		}
 		p.Search = q
 	}
+	p.Sort = strings.TrimSpace(c.Query("sort"))
+	// Ascending unless asked otherwise: one spelling of "the other way", and
+	// anything else read as the default rather than refused.
+	p.Desc = c.Query("order") == "desc"
 	return p
 }
 

package/templates/create/features/docs/architecture.md.hbs

@@ -143,9 +143,12 @@ wrong. See `patterns.md`, "Filtered Lists".
 
 **Decision:** PostgreSQL + GORM, schema managed by
 [golang-migrate](https://github.com/golang-migrate/migrate).
-**Rationale:** `APP_ENV=development` allows a convenience table bootstrap;
-`APP_ENV=production` runs only after `migrate up` has applied the separate,
-versioned, rollback-capable SQL migrations.
+**Rationale:** one source of schema in every environment — the separate,
+versioned, rollback-capable SQL migrations, applied by `migrate up` before the
+binary starts. A development-only `db.AutoMigrate` convenience would build
+tables from the Go structs instead, dropping the CHECK constraints, foreign
+keys and seeded rows the SQL carries, and adding columns to an
+already-migrated database where no test would see the difference.
 
 {{#if docker}}- `docker-compose.yml` provides the local Postgres instance
 {{/if}}

package/templates/create/features/docs/common/parameters.yaml.hbs

@@ -16,3 +16,13 @@ Search:
   in: query
   description: "free-text search; which columns it matches is documented per endpoint"
   schema: { type: string, maxLength: 100 }
+Sort:
+  name: sort
+  in: query
+  description: "column to order by; which columns are accepted is documented per endpoint, and anything else is read as that list's own default order"
+  schema: { type: string }
+Order:
+  name: order
+  in: query
+  description: "direction for `sort`; ascending unless this is `desc`. Rows with no value sort last either way"
+  schema: { type: string, enum: [asc, desc], default: asc }

package/templates/create/features/docs/patterns.md.hbs

@@ -50,8 +50,8 @@ must import the specific boundary package it belongs to.
   kept in `domain/`.
 - `TableName()` returns a schema-qualified name (`order_svc.orders`, not
   `orders`) — every domain gets its own Postgres schema, created by its own
-  migration (`CREATE SCHEMA IF NOT EXISTS`) and by `cmd/api/wiring.go` before
-  the development table bootstrap runs. A cross-domain FK is still fine — see
+  migration (`CREATE SCHEMA IF NOT EXISTS`), which is the only thing that
+  creates it. A cross-domain FK is still fine — see
   the FK rules below — this only stops one domain's table from silently
   colliding with another's.
 
@@ -159,8 +159,8 @@ if this project has one):
    associations / belongs-to — that's what keeps one domain package from
    importing another.
 2. **Declare the FK constraint in migration SQL**
-   (`REFERENCES ... ON DELETE ...`), not a GORM tag — the development bootstrap
-   doesn't create the constraint, which would make dev and prod schemas diverge.
+   (`REFERENCES ... ON DELETE ...`), not a GORM tag — a GORM tag describes the
+   constraint to Go and to nothing that runs, so the database would not have it.
 3. **Map the FK error to the right status** in the outbound adapter with
    `dberr.IsForeignKey`, then let the inbound adapter render it — inserting a
    reference to a missing parent, or deleting a parent that still has children,
@@ -255,9 +255,10 @@ business logic — same spirit as `generate module`'s placeholder fields.
 A `crud`-surface module is generated with this already wired; a module that
 grows a list later copies the same four steps. Nothing about it is magic.
 
-**1. Parse at the boundary.** `pagination.Parse(c)` returns `Limit`, `Offset`
-and `Search` (`?q=`, trimmed and capped at 100 runes). Read the filters this
-endpoint owns off the query string beside it. An unreadable filter value means
+**1. Parse at the boundary.** `pagination.Parse(c)` returns `Limit`, `Offset`,
+`Search` (`?q=`, trimmed and capped at 100 runes) and the requested order —
+`Sort` (`?sort=`) and `Desc` (`?order=desc`). Read the filters this endpoint
+owns off the query string beside them. An unreadable filter value means
 *no* filter, not `400` — a list narrows on a best effort.
 
 **2. One filter struct, in `ports/`.** `ports.ListFilter` travels whole through
@@ -270,6 +271,8 @@ everything".
 ```go
 type ListFilter struct {
     Search string
+    Sort   string
+    Desc   bool
     Limit  int
     Offset int
     // Status, OwnerID, DateFrom … whatever this module actually filters by.
@@ -288,21 +291,47 @@ accumulate on a `*gorm.DB` value, so a count reusing the page's query object
 silently inherits its `LIMIT`. Use `dbq.Search(q, term, cols...)` for a
 contains-search over columns on the same table, and `dbq.LikePattern(term)`
 when the search spans a subquery or a join. Both escape `%` and `_`, so
-someone typing `50%` searches for `50%` instead of matching every row. Always
-keep a tiebreaker in the sort (`ORDER BY created_at DESC, id`) or two rows
-written in the same instant can swap between page 1 and page 2 — showing one
-twice and hiding the other.
+someone typing `50%` searches for `50%` instead of matching every row.
 
-The generated `FindAll` calls `dbq.Search` with no columns, which is a no-op:
-`?q=` is accepted and ignored until you name the columns this list is searched
-by. That TODO is the one line standing between the scaffold and a working
-search.
+The order is a `dbq.Sort` declared beside `FindAll`, not an `Order` string
+written per query:
+
+```go
+var sortable = dbq.Sort{
+    Columns:  map[string]string{"name": "name", "created_at": "created_at"},
+    Default:  "created_at desc",
+    Tiebreak: "id",
+}
+...
+q = q.Order(sortable.OrderBy(filter.Sort, filter.Desc))
+```
+
+`Columns` maps the names the API accepts to the SQL each one means and is the
+whole of what can reach the clause — `ORDER BY` takes no bound parameter, so a
+`?sort=` that is not one of its keys falls back to `Default` rather than being
+interpolated. `OrderBy` adds what every list needs and nobody should have to
+remember: `Tiebreak` on the end (without it two rows equal on the sorted column
+swap between page 1 and page 2, showing one twice and hiding the other) and
+`NULLS LAST` in both directions (a row with no value is missing an answer, not
+holding the largest one). A table already unique on its order — roles, keyed by
+`code` — sets `Tiebreak` to that column and leaves `Default` empty.
+
+A column the client sees but this table does not hold, such as a primary email
+one table over, belongs in `Columns` as a subquery rather than a join: a join
+would need its own `SELECT` list to keep `Find` scanning the right row.
+
+The generated `FindAll` calls `dbq.Search` with no columns and carries an empty
+`Columns` map, both no-ops: `?q=` and `?sort=` are accepted and ignored until
+you name the columns this list is searched and ordered by. Those two TODOs are
+the lines standing between the scaffold and a working list.
 
 **4. Respond with the shared envelope.** `p.ResponseWithTotal(out, total)` —
 `{ data, limit, offset, total }`, the same shape for every resource. Anything
 extra is a named key added to that map and documented in the endpoint's
-OpenAPI file. Reuse `common/parameters.yaml#/Search`, `#/Limit` and `#/Offset`
-for the query parameters.
+OpenAPI file. Reuse `common/parameters.yaml#/Search`, `#/Limit`, `#/Offset`,
+`#/Sort` and `#/Order` for the query parameters. `#/Sort` carries no enum —
+which columns an endpoint accepts is a sentence in its own response
+description, the same way `q` says what it matches.
 
 Counts that answer a *different* question from the page — "how many are open
 and how many are closed, whichever tab is showing" — belong beside the

package/templates/create/features/docs/techstack.md.hbs

@@ -40,8 +40,9 @@
 {{/if}}{{#if worker}}{{#if (eq queue "river")}}- Run `make river-migrate` before relying on queued jobs in a fresh database;
   run `make river-migrate-test` as well when `REQUIRE_TEST_DB=true` runs the
   River worker round-trip test.{{/if}}{{/if}}
-- `APP_ENV=development` enables the convenience table bootstrap;
-  `APP_ENV=production` requires `migrate up` as a deploy step instead
+- The schema is the migrations', in every environment: `migrate up` applies
+  it and the startup version check refuses to boot without it. There is no
+  development table bootstrap
 {{#if worker}}{{#if (eq queue "river")}}- River uses the database/sql driver and polls for jobs instead of receiving
   PostgreSQL LISTEN/NOTIFY wakeups; this is deliberate for a shared GORM pool.
 {{/if}}{{/if}}

package/templates/generate/module/docs/collection.yaml.hbs

@@ -22,9 +22,11 @@ get:
     - $ref: '../common/parameters.yaml#/Limit'
     - $ref: '../common/parameters.yaml#/Offset'
     - $ref: '../common/parameters.yaml#/Search'
+    - $ref: '../common/parameters.yaml#/Sort'
+    - $ref: '../common/parameters.yaml#/Order'
   responses:
     "200":
-      description: "paginated list; narrow it with ?q= and whatever filters this module adds"
+      description: "paginated list; narrow it with ?q= and whatever filters this module adds, and order it with ?sort= once the repository's dbq.Sort names a column"
       content:
         application/json:
           schema:

package/templates/generate/module/hexagonal/adapters/inbound/http/handler.go.hbs

@@ -111,7 +111,13 @@ func (h *Handler) list(c *gin.Context) {
 	// One struct all the way down, so this module's own filters are read off
 	// the query string here and added as fields on ports.ListFilter — never as
 	// extra arguments on the three signatures below.
-	filter := ports.ListFilter{Search: p.Search, Limit: p.Limit, Offset: p.Offset}
+	filter := ports.ListFilter{
+		Search: p.Search,
+		Sort:   p.Sort,
+		Desc:   p.Desc,
+		Limit:  p.Limit,
+		Offset: p.Offset,
+	}
 {{#if cqrs}}
 	items, total, err := h.queries.List(c.Request.Context(), filter)
 {{else}}

package/templates/generate/module/hexagonal/adapters/outbound/postgres/repository.go.hbs

@@ -31,6 +31,20 @@ func (r *Repository) Create(ctx context.Context, m *domain.{{pascalName}}) error
 	return nil
 }
 
+// sortable is the whole of what ?sort= may say for this list: dbq.Sort
+// resolves the requested name against Columns, so nothing off the request is
+// ever interpolated into the ORDER BY.
+//
+// TODO: name the columns this list may be ordered by, mapping the name the API
+// accepts to the SQL it means — {"name": "name", "created_at": "created_at"}.
+// Until then ?sort= is accepted and ignored, the same way dbq.Search is until
+// it has columns.
+var sortable = dbq.Sort{
+	Columns:  map[string]string{},
+	Default:  "created_at desc",
+	Tiebreak: "id",
+}
+
 // FindAll answers one page of the filter and how many rows it matched
 // altogether. Two queries, because a count over a LIMITed query would only
 // ever count the page.
@@ -52,10 +66,12 @@ func (r *Repository) FindAll(ctx context.Context, filter ports.ListFilter) ([]do
 	}
 
 	var rows []{{pascalName}}Model
-	// created_at orders it, id breaks the ties: without the tiebreaker two
-	// rows written in the same instant can swap between page 1 and page 2,
-	// showing one twice and hiding the other.
-	if err := matching().Order("created_at desc, id").Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error; err != nil {
+	// Newest first until a client asks for something else, and always with the
+	// tiebreaker sortable carries: without it two rows written in the same
+	// instant can swap between page 1 and page 2, showing one twice and hiding
+	// the other.
+	order := sortable.OrderBy(filter.Sort, filter.Desc)
+	if err := matching().Order(order).Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error; err != nil {
 		return nil, 0, mapDatabaseError(err)
 	}
 	items := make([]domain.{{pascalName}}, len(rows))

package/templates/generate/module/hexagonal/ports/repository.go.hbs

@@ -21,6 +21,11 @@ type ListFilter struct {
 	// Search is ?q= as shared/pagination parsed it, empty when the caller
 	// sent none.
 	Search string
+	// Sort is ?sort= and Desc is ?order=desc, both as shared/pagination parsed
+	// them. Which column names are accepted is the repository's to say — see
+	// the dbq.Sort beside its FindAll.
+	Sort   string
+	Desc   bool
 	Limit  int
 	Offset int
 }