@nakedev/go-scaffold 0.1.3 → 0.3.0

package/templates/generate/module/handler_test.go.hbs

@@ -2,14 +2,9 @@ package {{pkg}}
 
 import (
 	"bytes"
-{{#if permission}}
 	"context"
-{{/if}}
-	"encoding/json"
 	"net/http"
 	"net/http/httptest"
-	"os"
-	"sync"
 	"testing"
 {{#if auth}}
 	"time"
@@ -23,67 +18,77 @@ import (
 	"github.com/golang-jwt/jwt/v5"
 {{/if}}
 	"github.com/google/uuid"
-	"gorm.io/driver/postgres"
-	"gorm.io/gorm"
 )
 
-// integration test backed by real Postgres (same engine as prod, no sqlite) — skips if the DB isn't reachable.
-// Runs against its own {{dbName}}_test database, never the one DB_DSN points at: the
-// harness does DropTable+AutoMigrate on every run, which would otherwise wipe the
-// schema `make migrate-up` built in your dev DB (FK constraints, seed data and all).
-// Create it once with `make db-create DB_NAME={{dbName}}_test`, or point TEST_DB_DSN
-// somewhere else.
-var (
-	testDBOnce sync.Once
-	testDB     *gorm.DB
-	testDBErr  error
-)
+// serviceStub keeps handler tests at the HTTP boundary. It exercises binding,
+// routing, middleware, status codes, and serialization without a database.
+type serviceStub struct {
+	// Embedding keeps this stub source-compatible when `generate method` adds a
+	// new operation to the handler's service interface. Base CRUD methods below
+	// still override the promoted concrete methods for focused unit tests.
+	*Service
+	createFn func(context.Context, createInput) (*model.{{pascalName}}, error)
+	listFn   func(context.Context, int, int) ([]model.{{pascalName}}, error)
+	getFn    func(context.Context, uuid.UUID) (*model.{{pascalName}}, error)
+	updateFn func(context.Context, uuid.UUID, updateInput) (*model.{{pascalName}}, error)
+	deleteFn func(context.Context, uuid.UUID) error
+}
 
-func dbForTest(t *testing.T) *gorm.DB {
-	t.Helper()
-	testDBOnce.Do(func() {
-		dsn := os.Getenv("TEST_DB_DSN")
-		if dsn == "" {
-			dsn = "postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable"
-		}
-		if testDB, testDBErr = gorm.Open(postgres.Open(dsn), &gorm.Config{TranslateError: true}); testDBErr == nil {
-			// drop first — AutoMigrate can't change an existing column's type, always start from a fresh schema
-			_ = testDB.Migrator().DropTable(&model.{{pascalName}}{})
-			testDBErr = testDB.AutoMigrate(&model.{{pascalName}}{})
-		}
-	})
-	if testDBErr != nil {
-		t.Skipf("postgres not ready (make db-create DB_NAME={{dbName}}_test, or set TEST_DB_DSN): %v", testDBErr)
+func (s *serviceStub) Create(ctx context.Context, in createInput) (*model.{{pascalName}}, error) {
+	if s.createFn == nil {
+		panic("unexpected service.Create call")
+	}
+	return s.createFn(ctx, in)
+}
+
+func (s *serviceStub) List(ctx context.Context, limit, offset int) ([]model.{{pascalName}}, error) {
+	if s.listFn == nil {
+		panic("unexpected service.List call")
+	}
+	return s.listFn(ctx, limit, offset)
+}
+
+func (s *serviceStub) Get(ctx context.Context, id uuid.UUID) (*model.{{pascalName}}, error) {
+	if s.getFn == nil {
+		panic("unexpected service.Get call")
+	}
+	return s.getFn(ctx, id)
+}
+
+func (s *serviceStub) Update(ctx context.Context, id uuid.UUID, in updateInput) (*model.{{pascalName}}, error) {
+	if s.updateFn == nil {
+		panic("unexpected service.Update call")
+	}
+	return s.updateFn(ctx, id, in)
+}
+
+func (s *serviceStub) Delete(ctx context.Context, id uuid.UUID) error {
+	if s.deleteFn == nil {
+		panic("unexpected service.Delete call")
 	}
-	return testDB
+	return s.deleteFn(ctx, id)
 }
 
-// setup builds the full stack on a transaction that's rolled back at the end → each test is isolated, no leftover rows
-func setup(t *testing.T) *gin.Engine {
+// go-scaffold:service-stub-methods
+
+func setupHandlerTest(t *testing.T, svc service) *gin.Engine {
 	t.Helper()
 	gin.SetMode(gin.TestMode)
-	tx := dbForTest(t).Begin()
-	t.Cleanup(func() { tx.Rollback() })
 	r := gin.New()
 	r.Use(middleware.RequestID(), middleware.Error(true))
 {{#if permission}}
-	// stub authz: always grants "{{permission}}" — this test is about the
-	// CRUD handler, not re-proving RBAC (that's covered by the role
-	// package's own tests), so the resolver doesn't need a real DB lookup.
+	// The handler unit test verifies route composition, not the role repository.
 	authz := middleware.NewAuthz(func(_ context.Context, _ string) (map[string]struct{}, error) {
 		return map[string]struct{}{"{{permission}}": {}}, nil
 	}, time.Minute)
 {{/if}}
-	NewHandler(NewService(NewRepository(tx)){{#if auth}}, testJWTSecret{{/if}}{{#if permission}}, authz{{/if}}).Register(r)
+	NewHandler(svc{{#if auth}}, testJWTSecret{{/if}}{{#if permission}}, authz{{/if}}).Register(r)
 	return r
 }
 
 {{#if auth}}
 const testJWTSecret = "test-secret"
 
-// authHeader mints a valid access token signed with testJWTSecret — the
-// route's own RequireAuth(testJWTSecret) (wired in via NewHandler above)
-// verifies against the same secret, so this round-trips for real.
 func authHeader() string {
 	claims := jwt.MapClaims{
 		"typ":  "access",
@@ -97,8 +102,8 @@ func authHeader() string {
 }
 
 {{/if}}
-func do(r *gin.Engine, method, path, body string) *httptest.ResponseRecorder {
-	req := httptest.NewRequest(method, path, bytes.NewBufferString(body))
+func doHandlerRequest(r *gin.Engine, method, requestPath, body string) *httptest.ResponseRecorder {
+	req := httptest.NewRequest(method, requestPath, bytes.NewBufferString(body))
 	req.Header.Set("Content-Type", "application/json")
 {{#if auth}}
 	req.Header.Set("Authorization", authHeader())
@@ -108,40 +113,61 @@ func do(r *gin.Engine, method, path, body string) *httptest.ResponseRecorder {
 	return w
 }
 
+// createBody is the JSON these tests POST. It starts empty because createInput
+// starts empty — add a value here for every field you add to createInput in
+// dto.go. Miss that and this test fails with a 400 the moment one of those
+// fields is `binding:"required"`: the handler is fine, the fixture just no
+// longer satisfies it.
+const createBody = `{}`
+
 func TestHandler_Create_OK(t *testing.T) {
-	r := setup(t)
-	w := do(r, http.MethodPost, "/{{plural}}", `{}`)
+	svc := &serviceStub{
+		createFn: func(context.Context, createInput) (*model.{{pascalName}}, error) {
+			return &model.{{pascalName}}{ID: uuid.New()}, nil
+		},
+	}
+	r := setupHandlerTest(t, svc)
+
+	w := doHandlerRequest(r, http.MethodPost, "/{{plural}}", createBody)
+
 	if w.Code != http.StatusCreated {
 		t.Fatalf("want 201, got %d body=%s", w.Code, w.Body)
 	}
 }
 
 func TestHandler_Get_NotFound(t *testing.T) {
-	r := setup(t)
-	w := do(r, http.MethodGet, "/{{plural}}/"+uuid.NewString(), "")
+	svc := &serviceStub{
+		getFn: func(context.Context, uuid.UUID) (*model.{{pascalName}}, error) {
+			return nil, errNotFound()
+		},
+	}
+	r := setupHandlerTest(t, svc)
+
+	w := doHandlerRequest(r, http.MethodGet, "/{{plural}}/"+uuid.NewString(), "")
+
 	if w.Code != http.StatusNotFound {
 		t.Fatalf("want 404, got %d body=%s", w.Code, w.Body)
 	}
 }
 
-func TestHandler_Get_InvalidID(t *testing.T) {
-	r := setup(t)
-	w := do(r, http.MethodGet, "/{{plural}}/not-a-uuid", "")
+func TestHandler_Get_InvalidID_DoesNotCallService(t *testing.T) {
+	r := setupHandlerTest(t, &serviceStub{})
+
+	w := doHandlerRequest(r, http.MethodGet, "/{{plural}}/not-a-uuid", "")
+
 	if w.Code != http.StatusBadRequest {
 		t.Fatalf("want 400, got %d body=%s", w.Code, w.Body)
 	}
 }
 
 func TestHandler_Delete_OK(t *testing.T) {
-	r := setup(t)
-	created := do(r, http.MethodPost, "/{{plural}}", `{}`)
-	var body struct {
-		ID string `json:"id"`
+	svc := &serviceStub{
+		deleteFn: func(context.Context, uuid.UUID) error { return nil },
 	}
-	if err := json.Unmarshal(created.Body.Bytes(), &body); err != nil {
-		t.Fatalf("decode create response: %v", err)
-	}
-	w := do(r, http.MethodDelete, "/{{plural}}/"+body.ID, "")
+	r := setupHandlerTest(t, svc)
+
+	w := doHandlerRequest(r, http.MethodDelete, "/{{plural}}/"+uuid.NewString(), "")
+
 	if w.Code != http.StatusNoContent {
 		t.Fatalf("want 204, got %d body=%s", w.Code, w.Body)
 	}

package/templates/generate/module/migration.down.sql.hbs

@@ -1 +1,3 @@
-DROP TABLE IF EXISTS {{plural}};
+DROP TABLE IF EXISTS {{schemaName}}.{{tableName}};
+-- the schema itself is left in place: cheap to keep, and dropping it here
+-- would be wrong the moment a second table (added later, by hand) shares it

package/templates/generate/module/migration.up.sql.hbs

@@ -1,5 +1,10 @@
-CREATE TABLE {{plural}} (
+-- one schema per domain — see model.go's TableName for why
+CREATE SCHEMA IF NOT EXISTS {{schemaName}};
+
+CREATE TABLE {{schemaName}}.{{tableName}} (
     id         UUID PRIMARY KEY,
     created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    -- bumped on every update; an update that carries an older value is refused
+    version    INTEGER NOT NULL DEFAULT 1
 );

package/templates/generate/module/minimal/dto.go.hbs

@@ -16,11 +16,13 @@ import (
 type response struct {
 	ID        uuid.UUID `json:"id"`
 	CreatedAt time.Time `json:"created_at"`
+	// clients send this back on an update so a concurrent save can be detected
+	Version int `json:"version"`
 }
 
 //nolint:unused
 func toResponse(m *model.{{pascalName}}) response {
-	return response{ID: m.ID, CreatedAt: m.CreatedAt}
+	return response{ID: m.ID, CreatedAt: m.CreatedAt, Version: m.Version}
 }
 
 // go-scaffold:dto

package/templates/generate/module/minimal/handler.go.hbs

@@ -8,9 +8,15 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// service is intentionally empty until `generate method` adds the exact
+// application operations required by this HTTP adapter.
+type service interface {
+	// go-scaffold:service-interface
+}
+
 // Handler = delivery for {{pkg}} (parses HTTP, calls the service, attaches errors for the middleware to render)
 type Handler struct {
-	svc *Service
+	svc service
 {{#if auth}}
 	jwtSecret string
 {{/if}}
@@ -19,7 +25,7 @@ type Handler struct {
 {{/if}}
 }
 
-func NewHandler(svc *Service{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
+func NewHandler(svc service{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
 	return &Handler{
 		svc: svc,
 {{#if auth}}

package/templates/generate/module/minimal/handler_test.go.hbs

@@ -1,117 +1,10 @@
 package {{pkg}}
 
-import (
-	"bytes"
-{{#if permission}}
-	"context"
-{{/if}}
-	"net/http/httptest"
-	"os"
-	"sync"
-	"testing"
-{{#if auth}}
-	"time"
-{{/if}}
-
-	"{{goModule}}/internal/app/{{modulePath}}/model"
-	"{{goModule}}/internal/shared/middleware"
-
-	"gorm.io/gorm"
-
-	"github.com/gin-gonic/gin"
-{{#if auth}}
-	"github.com/golang-jwt/jwt/v5"
-	"github.com/google/uuid"
-{{/if}}
-	"gorm.io/driver/postgres"
-)
-
-// integration test harness, backed by real Postgres (same engine as prod, no sqlite) — skips if
-// the DB isn't reachable. minimal module: no routes yet, so no tests reference this yet — kept
-// ready for once `generate method` adds endpoints.
-// Runs against its own {{dbName}}_test database, never the one DB_DSN points at: the
-// harness does DropTable+AutoMigrate on every run, which would otherwise wipe the
-// schema `make migrate-up` built in your dev DB (FK constraints, seed data and all).
-// Create it once with `make db-create DB_NAME={{dbName}}_test`, or point TEST_DB_DSN
-// somewhere else.
-//nolint:unused
-var (
-	testDBOnce sync.Once
-	testDB     *gorm.DB
-	testDBErr  error
-)
-
-//nolint:unused
-func dbForTest(t *testing.T) *gorm.DB {
-	t.Helper()
-	testDBOnce.Do(func() {
-		dsn := os.Getenv("TEST_DB_DSN")
-		if dsn == "" {
-			dsn = "postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable"
-		}
-		if testDB, testDBErr = gorm.Open(postgres.Open(dsn), &gorm.Config{TranslateError: true}); testDBErr == nil {
-			_ = testDB.Migrator().DropTable(&model.{{pascalName}}{})
-			testDBErr = testDB.AutoMigrate(&model.{{pascalName}}{})
-		}
-	})
-	if testDBErr != nil {
-		t.Skipf("postgres not ready (make db-create DB_NAME={{dbName}}_test, or set TEST_DB_DSN): %v", testDBErr)
-	}
-	return testDB
-}
-
-// setup builds the full stack on a transaction that's rolled back at the end → each test is isolated, no leftover rows
+// serviceStub embeds the concrete service so a generated method automatically
+// satisfies the handler's narrow service interface. Add explicit function-backed
+// overrides here when writing focused handler tests for that method.
 //
 //nolint:unused
-func setup(t *testing.T) *gin.Engine {
-	t.Helper()
-	gin.SetMode(gin.TestMode)
-	tx := dbForTest(t).Begin()
-	t.Cleanup(func() { tx.Rollback() })
-	r := gin.New()
-	r.Use(middleware.RequestID(), middleware.Error(true))
-{{#if permission}}
-	// stub authz: always grants "{{permission}}" — this test is about the
-	// CRUD handler, not re-proving RBAC (that's covered by the role
-	// package's own tests), so the resolver doesn't need a real DB lookup.
-	authz := middleware.NewAuthz(func(_ context.Context, _ string) (map[string]struct{}, error) {
-		return map[string]struct{}{"{{permission}}": {}}, nil
-	}, time.Minute)
-{{/if}}
-	NewHandler(NewService(NewRepository(tx)){{#if auth}}, testJWTSecret{{/if}}{{#if permission}}, authz{{/if}}).Register(r)
-	return r
-}
-
-{{#if auth}}
-//nolint:unused
-const testJWTSecret = "test-secret"
-
-// authHeader mints a valid access token signed with testJWTSecret — the
-// route's own RequireAuth(testJWTSecret) (wired in via NewHandler above)
-// verifies against the same secret, so this round-trips for real.
-//
-//nolint:unused
-func authHeader() string {
-	claims := jwt.MapClaims{
-		"typ":  "access",
-		"sub":  uuid.NewString(),
-		"role": "staff",
-		"exp":  time.Now().Add(time.Hour).Unix(),
-		"iat":  time.Now().Unix(),
-	}
-	tok, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(testJWTSecret))
-	return "Bearer " + tok
-}
-
-{{/if}}
-//nolint:unused
-func do(r *gin.Engine, method, path, body string) *httptest.ResponseRecorder {
-	req := httptest.NewRequest(method, path, bytes.NewBufferString(body))
-	req.Header.Set("Content-Type", "application/json")
-{{#if auth}}
-	req.Header.Set("Authorization", authHeader())
-{{/if}}
-	w := httptest.NewRecorder()
-	r.ServeHTTP(w, req)
-	return w
+type serviceStub struct {
+	*Service
 }

package/templates/generate/module/minimal/service_test.go.hbs

@@ -11,37 +11,60 @@ import (
 	"github.com/google/uuid"
 )
 
-// fakeRepo = mock of the repository interface, so the service can be tested without a DB
-// minimal module: no service methods yet, so no tests reference this — kept ready for
-// when `generate method` adds one (its patches append matching stubs here automatically
-// for a `get --get-mode one --field` lookup)
+// repositoryStub is ready for focused use-case tests added alongside generated
+// methods. Every unset dependency panics so unexpected orchestration is visible.
+//
 //nolint:unused
-type fakeRepo struct {
-	err error
-	m   *model.{{pascalName}}
+type repositoryStub struct {
+	createFn   func(context.Context, *model.{{pascalName}}) error
+	findAllFn  func(context.Context, int, int) ([]model.{{pascalName}}, error)
+	findByIDFn func(context.Context, uuid.UUID) (*model.{{pascalName}}, error)
+	updateFn   func(context.Context, *model.{{pascalName}}) error
+	deleteFn   func(context.Context, uuid.UUID) error
+	// go-scaffold:repository-stub-fields
 }
 
 //nolint:unused
-func (f *fakeRepo) Create(context.Context, *model.{{pascalName}}) error                    { return f.err }
+func (s *repositoryStub) Create(ctx context.Context, m *model.{{pascalName}}) error {
+	if s.createFn == nil {
+		panic("unexpected repository.Create call")
+	}
+	return s.createFn(ctx, m)
+}
 
 //nolint:unused
-func (f *fakeRepo) FindAll(context.Context, int, int) ([]model.{{pascalName}}, error) { return nil, f.err }
+func (s *repositoryStub) FindAll(ctx context.Context, limit, offset int) ([]model.{{pascalName}}, error) {
+	if s.findAllFn == nil {
+		panic("unexpected repository.FindAll call")
+	}
+	return s.findAllFn(ctx, limit, offset)
+}
 
 //nolint:unused
-func (f *fakeRepo) FindByID(context.Context, uuid.UUID) (*model.{{pascalName}}, error) {
-	if f.err != nil {
-		return nil, f.err
+func (s *repositoryStub) FindByID(ctx context.Context, id uuid.UUID) (*model.{{pascalName}}, error) {
+	if s.findByIDFn == nil {
+		panic("unexpected repository.FindByID call")
 	}
-	return f.m, nil
+	return s.findByIDFn(ctx, id)
 }
 
 //nolint:unused
-func (f *fakeRepo) Update(context.Context, *model.{{pascalName}}) error { return f.err }
+func (s *repositoryStub) Update(ctx context.Context, m *model.{{pascalName}}) error {
+	if s.updateFn == nil {
+		panic("unexpected repository.Update call")
+	}
+	return s.updateFn(ctx, m)
+}
 
 //nolint:unused
-func (f *fakeRepo) Delete(context.Context, uuid.UUID) error { return f.err }
+func (s *repositoryStub) Delete(ctx context.Context, id uuid.UUID) error {
+	if s.deleteFn == nil {
+		panic("unexpected repository.Delete call")
+	}
+	return s.deleteFn(ctx, id)
+}
 
-// go-scaffold:fake-repo-methods
+// go-scaffold:repository-stub-methods
 
 //nolint:unused
 func status(t *testing.T, err error) int {

package/templates/generate/module/model/model.go.hbs

@@ -17,4 +17,20 @@ type {{pascalName}} struct {
 	ID        uuid.UUID `json:"id" gorm:"type:uuid;primaryKey"`
 	CreatedAt time.Time `json:"created_at"`
 	UpdatedAt time.Time `json:"updated_at"`
+	// Version guards against two clients that both loaded this row overwriting
+	// each other: an update only applies if the version it carries still
+	// matches the stored one. Bumped by Repository.Update, never by hand.
+	Version int `json:"version" gorm:"not null;default:1"`
+}
+
+// TableName pins the persistence contract to the versioned SQL migrations.
+// Do not rely on GORM's English inflector: irregular/plural module names must
+// resolve to exactly the same table in development and production.
+//
+// Schema-qualified ("{{schemaName}}", not just "{{tableName}}") so this
+// domain's table can never collide with another domain's, and a raw SQL JOIN
+// reaching into it from outside this package fails loudly instead of quietly
+// coupling two domains together.
+func ({{pascalName}}) TableName() string {
+	return "{{schemaName}}.{{tableName}}"
 }

package/templates/generate/module/permission.up.sql.hbs

@@ -1,4 +1,6 @@
 -- ON CONFLICT DO NOTHING: safe to re-generate a module reusing a permission
 -- code another module already inserted (e.g. a shared "orders:manage").
-INSERT INTO permissions (code, description) VALUES ('{{permission}}', 'Manage {{plural}}')
+-- role_svc, not this module's own schema: `add rbac` owns the permissions
+-- table, wherever it ends up living — see `add rbac`'s migration.
+INSERT INTO role_svc.permissions (code, description) VALUES ('{{permission}}', 'Manage {{plural}}')
 ON CONFLICT (code) DO NOTHING;

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

@@ -2,15 +2,23 @@ package {{pkg}}
 
 import (
 	"context"
+	"errors"
 
 	"{{goModule}}/internal/app/{{modulePath}}/model"
+	"{{goModule}}/internal/shared/tx"
 
 	"github.com/google/uuid"
 	"gorm.io/gorm"
 )
 
+// ErrStaleVersion means the row moved on since the caller read it — someone
+// else saved first. Returned instead of overwriting their work.
+var ErrStaleVersion = errors.New("stale version")
+
 // Repository = data access for {{pkg}} (the only place that touches the DB for this domain)
-// every method takes ctx, so a cancelled request cancels the query too
+// every method takes ctx, so a cancelled request cancels the query too — and
+// so tx.From can pick up a transaction opened by the caller, letting two
+// repositories commit together without changing any signature here.
 type Repository struct {
 	db *gorm.DB
 }
@@ -20,30 +28,76 @@ func NewRepository(db *gorm.DB) *Repository {
 }
 
 func (r *Repository) Create(ctx context.Context, m *model.{{pascalName}}) error {
-	return r.db.WithContext(ctx).Create(m).Error
+	return tx.From(ctx, r.db).WithContext(ctx).Create(m).Error
 }
 
 func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]model.{{pascalName}}, error) {
 	var items []model.{{pascalName}}
-	err := r.db.WithContext(ctx).Order("id desc").Limit(limit).Offset(offset).Find(&items).Error
+	err := tx.From(ctx, r.db).WithContext(ctx).Order("id desc").Limit(limit).Offset(offset).Find(&items).Error
 	return items, err
 }
 
 func (r *Repository) FindByID(ctx context.Context, id uuid.UUID) (*model.{{pascalName}}, error) {
 	var m model.{{pascalName}}
 	// "id = ?" explicit — PK is a UUID, not an int, this avoids GORM misinterpreting the arg
-	if err := r.db.WithContext(ctx).First(&m, "id = ?", id).Error; err != nil {
+	if err := tx.From(ctx, r.db).WithContext(ctx).First(&m, "id = ?", id).Error; err != nil {
 		return nil, err
 	}
 	return &m, nil
 }
 
+// Update applies m only if the version it carries still matches the stored
+// row, then bumps it. Two clients that both loaded version 3 can't silently
+// overwrite each other: the second one gets ErrStaleVersion instead of the
+// first one's changes disappearing with no error anywhere.
 func (r *Repository) Update(ctx context.Context, m *model.{{pascalName}}) error {
-	return r.db.WithContext(ctx).Save(m).Error
+	expected := m.Version
+	m.Version = expected + 1
+
+	res := tx.From(ctx, r.db).WithContext(ctx).
+		Model(&model.{{pascalName}}{}).
+		Where("id = ? AND version = ?", m.ID, expected).
+		// Select("*") because Updates on a struct skips zero values, which
+		// would quietly ignore a field the caller meant to clear.
+		Select("*").Omit("id", "created_at").
+		Updates(m)
+	if res.Error != nil {
+		m.Version = expected
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		m.Version = expected
+		return ErrStaleVersion
+	}
+	return nil
 }
 
+// Delete reports gorm.ErrRecordNotFound when the row wasn't there, so a
+// DELETE on an id that never existed answers 404 like GET does — a plain
+// GORM delete affects zero rows and returns no error, which had the same
+// request answer 204 as a real deletion.
 func (r *Repository) Delete(ctx context.Context, id uuid.UUID) error {
-	return r.db.WithContext(ctx).Delete(&model.{{pascalName}}{}, "id = ?", id).Error
+	res := tx.From(ctx, r.db).WithContext(ctx).Delete(&model.{{pascalName}}{}, "id = ?", id)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+// Count is the total the list endpoint needs to say "page 3 of 12" — see
+// pagination.ResponseWithTotal. Separate from FindAll because it costs a second
+// query: an endpoint that only ever scrolls shouldn't pay for a count nobody
+// reads.
+//
+// Apply the same WHERE clause here that FindAll uses once you add filtering,
+// or the total will describe a different set than the rows.
+func (r *Repository) Count(ctx context.Context) (int64, error) {
+	var total int64
+	err := tx.From(ctx, r.db).WithContext(ctx).Model(&model.{{pascalName}}{}).Count(&total).Error
+	return total, err
 }
 
 // go-scaffold:repository-methods