@nakedev/go-scaffold 0.1.4 → 0.3.0

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

@@ -1,9 +1,20 @@
-CREATE TABLE users (
+CREATE SCHEMA IF NOT EXISTS user_svc;
+
+CREATE TABLE user_svc.users (
     id             UUID PRIMARY KEY,
-    email          VARCHAR(255) NOT NULL UNIQUE,
+    email          VARCHAR(255) NOT NULL,
     name           VARCHAR(255) NOT NULL DEFAULT '',
     avatar_url     TEXT NOT NULL DEFAULT '',
     email_verified BOOLEAN NOT NULL DEFAULT false,
     created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
     updated_at     TIMESTAMPTZ NOT NULL DEFAULT now()
 );
+
+-- A unique INDEX, not an inline UNIQUE constraint, and named to match the
+-- `uniqueIndex:idx_users_email` tag on model.User exactly. Postgres names an
+-- inline UNIQUE "users_email_key"; GORM's AutoMigrate (dev, AUTO_MIGRATE=true)
+-- then sees uniqueness it didn't create and tries to drop it under its own
+-- name, which fails the boot with
+--   constraint "uni_users_email" of relation "users" does not exist
+-- for anyone who ran `make migrate-up` first — which `add rbac` tells you to.
+CREATE UNIQUE INDEX idx_users_email ON user_svc.users (email);

package/templates/add/rbac/internal/app/role/dto.go.hbs

@@ -24,10 +24,15 @@ type CreateInput struct {
 	Name string `json:"name" binding:"required"`
 }
 
-// SetPermissionsInput.PermissionCodes is deliberately not `binding:"required"`
-// — an empty list is valid (it revokes every permission the role had).
+// SetPermissionsInput.PermissionCodes is a *pointer* so that "field absent"
+// and "field present but empty" stay different things. An empty list is a
+// valid request — it revokes every permission the role had — but with a plain
+// []string a body that simply misspells the key (say `{"permissions": [...]}`)
+// binds to nil, reads as that same "revoke everything", and answers 200 having
+// silently stripped the role. `required` on the pointer rejects the absent
+// case with a 400 while still allowing an explicit [].
 type SetPermissionsInput struct {
-	PermissionCodes []string `json:"permission_codes"`
+	PermissionCodes *[]string `json:"permission_codes" binding:"required"`
 }
 
 type permissionResponse struct {

package/templates/add/rbac/internal/app/role/handler.go.hbs

@@ -70,11 +70,13 @@ func (h *Handler) setPermissions(c *gin.Context) {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	item, err := h.svc.SetPermissions(c.Request.Context(), c.Param("code"), in.PermissionCodes)
+	item, err := h.svc.SetPermissions(c.Request.Context(), c.Param("code"), *in.PermissionCodes)
 	if err != nil {
 		c.Error(err)
 		return
 	}
+	// the grant is useless until the cache that answers Require() knows about it
+	h.authz.Invalidate(item.Code)
 	c.JSON(http.StatusOK, toResponse(&item.Role, item.Permissions))
 }
 
@@ -83,6 +85,7 @@ func (h *Handler) delete(c *gin.Context) {
 		c.Error(err)
 		return
 	}
+	h.authz.Invalidate(c.Param("code"))
 	c.Status(http.StatusNoContent)
 }
 

package/templates/add/rbac/internal/app/role/model/permission.go.hbs

@@ -7,3 +7,6 @@ type Permission struct {
 	Code        string `json:"code" gorm:"type:varchar(50);primaryKey"`
 	Description string `json:"description" gorm:"not null"`
 }
+
+// TableName — see Role.TableName; same schema, same reasoning.
+func (Permission) TableName() string { return "role_svc.permissions" }

package/templates/add/rbac/internal/app/role/model/role.go.hbs

@@ -16,3 +16,7 @@ type Role struct {
 	CreatedAt time.Time `json:"created_at"`
 	UpdatedAt time.Time `json:"updated_at"`
 }
+
+// TableName pins this to role_svc rather than GORM's default inflection —
+// every domain gets its own schema, see docs/architect/patterns.md.
+func (Role) TableName() string { return "role_svc.roles" }

package/templates/add/rbac/internal/app/role/model/role_permission.go.hbs

@@ -6,3 +6,6 @@ type RolePermission struct {
 	RoleCode       string `json:"role_code" gorm:"primaryKey;type:varchar(20)"`
 	PermissionCode string `json:"permission_code" gorm:"primaryKey;type:varchar(50)"`
 }
+
+// TableName — see Role.TableName; same schema, same reasoning.
+func (RolePermission) TableName() string { return "role_svc.role_permissions" }

package/templates/add/rbac/internal/app/role/repository.go.hbs

@@ -4,6 +4,7 @@ import (
 	"context"
 
 	"{{goModule}}/internal/app/role/model"
+	"{{goModule}}/internal/shared/tx"
 
 	"gorm.io/gorm"
 )
@@ -21,7 +22,7 @@ func NewRepository(db *gorm.DB) *Repository {
 // PermissionCodes returns the permission codes granted to roleCode.
 func (r *Repository) PermissionCodes(ctx context.Context, roleCode string) ([]string, error) {
 	var codes []string
-	err := r.db.WithContext(ctx).
+	err := tx.From(ctx, r.db).WithContext(ctx).
 		Model(&model.RolePermission{}).
 		Where("role_code = ?", roleCode).
 		Pluck("permission_code", &codes).Error
@@ -30,28 +31,28 @@ func (r *Repository) PermissionCodes(ctx context.Context, roleCode string) ([]st
 
 func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]model.Role, error) {
 	var items []model.Role
-	err := r.db.WithContext(ctx).Order("code").Limit(limit).Offset(offset).Find(&items).Error
+	err := tx.From(ctx, r.db).WithContext(ctx).Order("code").Limit(limit).Offset(offset).Find(&items).Error
 	return items, err
 }
 
 func (r *Repository) FindByCode(ctx context.Context, code string) (*model.Role, error) {
 	var m model.Role
-	if err := r.db.WithContext(ctx).First(&m, "code = ?", code).Error; err != nil {
+	if err := tx.From(ctx, r.db).WithContext(ctx).First(&m, "code = ?", code).Error; err != nil {
 		return nil, err
 	}
 	return &m, nil
 }
 
 func (r *Repository) Create(ctx context.Context, m *model.Role) error {
-	return r.db.WithContext(ctx).Create(m).Error
+	return tx.From(ctx, r.db).WithContext(ctx).Create(m).Error
 }
 
 // SetPermissions replaces roleCode's entire permission grant set in one
 // transaction — simpler for a checkbox-style admin UI than diffing
 // add/remove, and cheap at this scale (a handful of rows per role).
 func (r *Repository) SetPermissions(ctx context.Context, roleCode string, permissionCodes []string) error {
-	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		if err := tx.Where("role_code = ?", roleCode).Delete(&model.RolePermission{}).Error; err != nil {
+	return tx.From(ctx, r.db).WithContext(ctx).Transaction(func(t *gorm.DB) error {
+		if err := t.Where("role_code = ?", roleCode).Delete(&model.RolePermission{}).Error; err != nil {
 			return err
 		}
 		if len(permissionCodes) == 0 {
@@ -61,17 +62,17 @@ func (r *Repository) SetPermissions(ctx context.Context, roleCode string, permis
 		for i, code := range permissionCodes {
 			grants[i] = model.RolePermission{RoleCode: roleCode, PermissionCode: code}
 		}
-		return tx.Create(&grants).Error
+		return t.Create(&grants).Error
 	})
 }
 
 func (r *Repository) Delete(ctx context.Context, code string) error {
-	return r.db.WithContext(ctx).Delete(&model.Role{}, "code = ?", code).Error
+	return tx.From(ctx, r.db).WithContext(ctx).Delete(&model.Role{}, "code = ?", code).Error
 }
 
 func (r *Repository) FindAllPermissions(ctx context.Context, limit, offset int) ([]model.Permission, error) {
 	var items []model.Permission
-	err := r.db.WithContext(ctx).Order("code").Limit(limit).Offset(offset).Find(&items).Error
+	err := tx.From(ctx, r.db).WithContext(ctx).Order("code").Limit(limit).Offset(offset).Find(&items).Error
 	return items, err
 }
 
@@ -80,7 +81,7 @@ func (r *Repository) FindAllPermissions(ctx context.Context, limit, offset int)
 // SetPermissions request.
 func (r *Repository) AllPermissionCodes(ctx context.Context) ([]string, error) {
 	var codes []string
-	err := r.db.WithContext(ctx).Model(&model.Permission{}).Pluck("code", &codes).Error
+	err := tx.From(ctx, r.db).WithContext(ctx).Model(&model.Permission{}).Pluck("code", &codes).Error
 	return codes, err
 }
 
@@ -89,7 +90,7 @@ func (r *Repository) AllPermissionCodes(ctx context.Context) ([]string, error) {
 // would leave no role holding permissionCode at all.
 func (r *Repository) CountRolesWithPermission(ctx context.Context, permissionCode, excludeCode string) (int64, error) {
 	var count int64
-	err := r.db.WithContext(ctx).Model(&model.RolePermission{}).
+	err := tx.From(ctx, r.db).WithContext(ctx).Model(&model.RolePermission{}).
 		Where("permission_code = ? AND role_code <> ?", permissionCode, excludeCode).
 		Count(&count).Error
 	return count, err

package/templates/add/rbac/internal/app/role/repository_test.go.hbs

@@ -0,0 +1,176 @@
+package role
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"{{goModule}}/internal/app/role/model"
+
+	"github.com/google/uuid"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+// repositoryDBForTest expects the test database schema to come from the same
+// versioned SQL migrations used in production. Unit tests stay database-free;
+// CI sets REQUIRE_TEST_DB=true so an unavailable/unmigrated database fails
+// instead of becoming a false-green skip. Same pattern as every generated
+// module's repository_test.go.
+func repositoryDBForTest(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := os.Getenv("TEST_DB_DSN")
+	if dsn == "" {
+		if os.Getenv("REQUIRE_TEST_DB") == "true" {
+			t.Fatal("TEST_DB_DSN is required when REQUIRE_TEST_DB=true")
+		}
+		t.Skip("repository integration test skipped: set TEST_DB_DSN to a migrated PostgreSQL database")
+	}
+
+	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{TranslateError: true})
+	if err != nil {
+		if os.Getenv("REQUIRE_TEST_DB") == "true" {
+			t.Fatalf("open required test database: %v", err)
+		}
+		t.Skipf("repository integration test skipped: %v", err)
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("get SQL database handle: %v", err)
+	}
+	if err := sqlDB.Ping(); err != nil {
+		if os.Getenv("REQUIRE_TEST_DB") == "true" {
+			t.Fatalf("ping required test database: %v", err)
+		}
+		t.Skipf("repository integration test skipped: %v", err)
+	}
+
+	tx := db.Begin()
+	if tx.Error != nil {
+		t.Fatalf("begin test transaction: %v", tx.Error)
+	}
+	t.Cleanup(func() {
+		if err := tx.Rollback().Error; err != nil {
+			t.Errorf("rollback test transaction: %v", err)
+		}
+	})
+	return tx
+}
+
+// testCode returns a role/permission code that fits both varchar(20) and
+// varchar(50) columns and won't collide with the seeded 'staff'/'admin'
+// roles or 'role:manage'/'user:manage-role'/'user:read' permissions.
+func testCode(t *testing.T) string {
+	t.Helper()
+	return "t" + uuid.New().String()[:7]
+}
+
+// seedPermission inserts directly rather than through Repository, which has
+// no create method for Permission on purpose (see model/permission.go.hbs:
+// "seeded by migration, not admin-created"). Tests still need rows to grant.
+func seedPermission(t *testing.T, tx *gorm.DB, code string) {
+	t.Helper()
+	if err := tx.WithContext(context.Background()).Create(&model.Permission{Code: code, Description: code}).Error; err != nil {
+		t.Fatalf("seed permission %s: %v", code, err)
+	}
+}
+
+// SetPermissions deletes-then-recreates the grant set inside one transaction
+// (see repository.go.hbs). A stub can assert it was called with the right
+// arguments, but not that the *table* ends up holding exactly the new set —
+// that's a property of the real delete+insert, not of the call.
+func TestRepository_SetPermissions_ReplacesEntireSet(t *testing.T) {
+	tx := repositoryDBForTest(t)
+	repo := NewRepository(tx)
+	ctx := context.Background()
+
+	roleCode := testCode(t)
+	permA, permB, permC := testCode(t), testCode(t), testCode(t)
+	if err := repo.Create(ctx, &model.Role{Code: roleCode, Name: roleCode}); err != nil {
+		t.Fatalf("seed role: %v", err)
+	}
+	seedPermission(t, tx, permA)
+	seedPermission(t, tx, permB)
+	seedPermission(t, tx, permC)
+
+	if err := repo.SetPermissions(ctx, roleCode, []string{permA, permB}); err != nil {
+		t.Fatalf("grant a,b: %v", err)
+	}
+	if err := repo.SetPermissions(ctx, roleCode, []string{permC}); err != nil {
+		t.Fatalf("replace with c: %v", err)
+	}
+
+	got, err := repo.PermissionCodes(ctx, roleCode)
+	if err != nil {
+		t.Fatalf("permission codes: %v", err)
+	}
+	if len(got) != 1 || got[0] != permC {
+		t.Fatalf("want only [%s] after replacing the grant set, got %v", permC, got)
+	}
+}
+
+// role_permissions references both roles and permissions with
+// ON DELETE CASCADE (add_roles.up.sql) — deleting a role should never leave
+// an orphaned grant row behind, and should never surface as an FK error the
+// caller has to handle.
+func TestRepository_Delete_CascadesRolePermissions(t *testing.T) {
+	tx := repositoryDBForTest(t)
+	repo := NewRepository(tx)
+	ctx := context.Background()
+
+	roleCode := testCode(t)
+	permCode := testCode(t)
+	if err := repo.Create(ctx, &model.Role{Code: roleCode, Name: roleCode}); err != nil {
+		t.Fatalf("seed role: %v", err)
+	}
+	seedPermission(t, tx, permCode)
+	if err := repo.SetPermissions(ctx, roleCode, []string{permCode}); err != nil {
+		t.Fatalf("grant: %v", err)
+	}
+
+	if err := repo.Delete(ctx, roleCode); err != nil {
+		t.Fatalf("delete role: %v", err)
+	}
+
+	got, err := repo.PermissionCodes(ctx, roleCode)
+	if err != nil {
+		t.Fatalf("permission codes after delete: %v", err)
+	}
+	if len(got) != 0 {
+		t.Fatalf("want role_permissions cascade-deleted along with the role, still have %v", got)
+	}
+}
+
+// CountRolesWithPermission backs the "would this leave no role holding the
+// permission" guard in service.go — the exclusion in its WHERE clause is
+// exactly the kind of off-by-one a stub returning a canned int can't catch.
+func TestRepository_CountRolesWithPermission_ExcludesGivenRole(t *testing.T) {
+	tx := repositoryDBForTest(t)
+	repo := NewRepository(tx)
+	ctx := context.Background()
+
+	roleA, roleB := testCode(t), testCode(t)
+	permCode := testCode(t)
+	if err := repo.Create(ctx, &model.Role{Code: roleA, Name: roleA}); err != nil {
+		t.Fatalf("seed role a: %v", err)
+	}
+	if err := repo.Create(ctx, &model.Role{Code: roleB, Name: roleB}); err != nil {
+		t.Fatalf("seed role b: %v", err)
+	}
+	seedPermission(t, tx, permCode)
+	if err := repo.SetPermissions(ctx, roleA, []string{permCode}); err != nil {
+		t.Fatalf("grant to a: %v", err)
+	}
+	if err := repo.SetPermissions(ctx, roleB, []string{permCode}); err != nil {
+		t.Fatalf("grant to b: %v", err)
+	}
+
+	count, err := repo.CountRolesWithPermission(ctx, permCode, roleA)
+	if err != nil {
+		t.Fatalf("count: %v", err)
+	}
+	if count != 1 {
+		t.Fatalf("want 1 (roleB only, roleA excluded), got %d", count)
+	}
+}

package/templates/add/rbac/internal/app/role/service.go.hbs

@@ -77,6 +77,13 @@ func (s *Service) List(ctx context.Context, limit, offset int) ([]roleListItem,
 	if err != nil {
 		return nil, apperror.NewInternal()
 	}
+	// ponytail: one query per role, not a join. A system has a handful of
+	// roles, so this is a handful of round trips on an admin screen nobody
+	// loads in a loop — the join costs more to read than it saves.
+	//
+	// Do not copy this shape into a domain whose list is user-sized. There the
+	// upgrade is one query with a join (or an IN over the page's ids) and a
+	// group-by in Go; here it would be ceremony.
 	out := make([]roleListItem, len(roles))
 	for i, r := range roles {
 		perms, err := s.repo.PermissionCodes(ctx, r.Code)

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

@@ -54,6 +54,25 @@ func (a *Authz) Require(perm string) gin.HandlerFunc {
 	}
 }
 
+// Invalidate drops a role's cached permissions so the next request re-reads
+// them. The write path (PATCH /roles/:code/permissions) runs in this same
+// process, so letting the grant sit behind the TTL was a pure own-goal:
+// granting a permission appeared to succeed and then did nothing for up to
+// AUTHZ_CACHE_TTL_MIN, and logging in again didn't help either — the cache is
+// keyed on the role, not the token — so the only way out was restarting the
+// app.
+//
+// ponytail: same-process only. Other pods keep their copy until the TTL
+// expires; that's the documented ceiling, and Redis pub/sub is the upgrade if
+// instant cluster-wide invalidation ever matters.
+func (a *Authz) Invalidate(roleCodes ...string) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	for _, code := range roleCodes {
+		delete(a.cache, code)
+	}
+}
+
 // ponytail: process-local cache, a handful of roles x AUTHZ_CACHE_TTL_MIN —
 // a role's permission grants take effect within the TTL, no pub/sub needed.
 // Move to Redis only if instant cross-pod invalidation turns out to matter.

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

@@ -57,7 +57,7 @@ func TestAuthz_Require_ForbidsMissingPermission(t *testing.T) {
 	r := gin.New()
 	// Require only records a *apperror.AppError via c.Error — Error(true) is
 	// what actually translates that into the response status code, same as
-	// the real router (see cmd/api/main.go).
+	// the real router (see cmd/api/wiring.go).
 	r.Use(Error(true))
 	r.GET("/x", func(c *gin.Context) { c.Set(RoleKey, "staff") }, a.Require("role:manage"), func(c *gin.Context) {
 		c.Status(http.StatusOK)

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

@@ -3,13 +3,13 @@
 -- raise a clear, actionable error instead of a raw FK-violation.
 DO $$
 BEGIN
-    IF EXISTS (SELECT 1 FROM users WHERE role NOT IN ('staff', 'admin')) THEN
+    IF EXISTS (SELECT 1 FROM user_svc.users WHERE role NOT IN ('staff', 'admin')) THEN
         RAISE EXCEPTION 'cannot roll back add_roles: users still have a role other than staff/admin — reassign them to staff/admin first';
     END IF;
 END $$;
 
-ALTER TABLE users DROP COLUMN role;
+ALTER TABLE user_svc.users DROP COLUMN role;
 
-DROP TABLE role_permissions;
-DROP TABLE permissions;
-DROP TABLE roles;
+DROP TABLE role_svc.role_permissions;
+DROP TABLE role_svc.permissions;
+DROP TABLE role_svc.roles;

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

@@ -1,4 +1,6 @@
-CREATE TABLE roles (
+CREATE SCHEMA IF NOT EXISTS role_svc;
+
+CREATE TABLE role_svc.roles (
     code       VARCHAR(20) PRIMARY KEY,
     name       TEXT NOT NULL,
     is_system  BOOLEAN NOT NULL DEFAULT FALSE,
@@ -6,30 +8,34 @@ CREATE TABLE roles (
     updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
 );
 
-CREATE TABLE permissions (
+CREATE TABLE role_svc.permissions (
     code        VARCHAR(50) PRIMARY KEY,
     description TEXT NOT NULL
 );
 
-CREATE TABLE role_permissions (
-    role_code       VARCHAR(20) NOT NULL REFERENCES roles(code) ON DELETE CASCADE,
-    permission_code VARCHAR(50) NOT NULL REFERENCES permissions(code) ON DELETE CASCADE,
+CREATE TABLE role_svc.role_permissions (
+    role_code       VARCHAR(20) NOT NULL REFERENCES role_svc.roles(code) ON DELETE CASCADE,
+    permission_code VARCHAR(50) NOT NULL REFERENCES role_svc.permissions(code) ON DELETE CASCADE,
     PRIMARY KEY (role_code, permission_code)
 );
 
-INSERT INTO roles (code, name, is_system) VALUES
+INSERT INTO role_svc.roles (code, name, is_system) VALUES
     ('staff', 'Staff', TRUE),
     ('admin', 'Admin', TRUE);
 
-INSERT INTO permissions (code, description) VALUES
+INSERT INTO role_svc.permissions (code, description) VALUES
     ('role:manage',       'Create roles and change their permissions'),
     ('user:manage-role',  'Change a user''s assigned role'),
     ('user:read',         'List and view other users');
 
 -- admin gets every permission that exists, staff gets none — no behavior
 -- change for existing users until an admin explicitly grants something.
-INSERT INTO role_permissions (role_code, permission_code)
-SELECT 'admin', code FROM permissions;
+INSERT INTO role_svc.role_permissions (role_code, permission_code)
+SELECT 'admin', code FROM role_svc.permissions;
 
-ALTER TABLE users
-    ADD COLUMN role VARCHAR(20) NOT NULL DEFAULT 'staff' REFERENCES roles(code);
+-- cross-schema FK: role_svc's migration is the one place allowed to alter
+-- user_svc's table, because this feature's whole point is "give users a
+-- role" — see docs/architect/patterns.md's FK rules for why a plain FK, not
+-- an app-level existence check, is the right way to enforce this.
+ALTER TABLE user_svc.users
+    ADD COLUMN role VARCHAR(20) NOT NULL DEFAULT 'staff' REFERENCES role_svc.roles(code);

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

@@ -2,63 +2,69 @@ package main
 
 import (
 	"context"
-	"errors"
 	"log/slog"
 	"os"
 	"os/signal"
 	"syscall"
 	"time"
 
+{{#if riverQueue}}
+	"{{goModule}}/internal/platform/database"
+{{/if}}
 	"{{goModule}}/internal/platform/mail"
 	"{{goModule}}/internal/platform/queue"
 	"{{goModule}}/internal/shared/config"
 	// go-scaffold:imports
 )
 
+// workerConcurrency is how many jobs run at once in this process. Scale out
+// by running more worker processes before raising this.
+const workerConcurrency = 10
+
 func main() {
 	cfg := config.Load()
 
 	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: parseLevel(cfg.LogLevel)}))
 	slog.SetDefault(logger)
 
-	srv, err := queue.NewServer(cfg.RedisURL)
+{{#if riverQueue}}
+	// The queue lives in the same database as your data — the worker needs a
+	// connection to it, not to a separate broker.
+	db, err := database.Open(cfg)
 	if err != nil {
-		logger.Error("new queue server", "error", err)
+		logger.Error("open db", "error", err)
 		os.Exit(1)
 	}
 
-	srv.Handle(mail.TypeSendEmail, mail.HandleSendEmail(mail.Open(cfg)))
+	q, err := queue.NewRiverWorker(db, workerConcurrency)
+{{else}}
+	q, err := queue.NewAsynqWorker(cfg.RedisURL, workerConcurrency)
+{{/if}}
+	if err != nil {
+		logger.Error("start queue", "error", err)
+		os.Exit(1)
+	}
+
+	q.Handle(mail.KindSendEmail, mail.Handle(mail.Open(cfg)))
 	// go-scaffold:queue-handlers
 
 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
 	defer stop()
 
-	go func() {
-		logger.Info("worker started")
-		if err := srv.Start(); err != nil && !errors.Is(err, context.Canceled) {
-			logger.Error("worker server", "error", err)
-			os.Exit(1)
-		}
-	}()
+	if err := q.Start(ctx); err != nil {
+		logger.Error("worker start", "error", err)
+		os.Exit(1)
+	}
+	logger.Info("worker started", "concurrency", workerConcurrency)
 
 	<-ctx.Done()
 	logger.Info("shutting down worker")
 
+	// Give in-flight jobs a bounded window to finish before exiting.
 	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer cancel()
-	// asynq's Shutdown() blocks until in-flight tasks finish (or the process
-	// is killed) with no context/timeout parameter of its own — run it in a
-	// goroutine and race it against shutdownCtx so a stuck task can't hang
-	// the process forever.
-	done := make(chan struct{}, 1)
-	go func() {
-		srv.Shutdown()
-		close(done)
-	}()
-	select {
-	case <-done:
-	case <-shutdownCtx.Done():
-		logger.Warn("worker shutdown timed out")
+	if err := q.Stop(shutdownCtx); err != nil {
+		logger.Warn("worker shutdown timed out", "error", err)
 	}
 	logger.Info("worker stopped")
 }

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

@@ -1,6 +1,7 @@
 package mail
 
 import (
+	"context"
 	"fmt"
 	"log/slog"
 	"net/smtp"
@@ -46,3 +47,23 @@ func (c *Client) Send(to, subject, body string) error {
 	}
 	return smtp.SendMail(c.host+":"+c.port, auth, c.from, []string{to}, []byte(msg))
 }
+
+// SyncClient sends in the caller's goroutine, satisfying the same mailer
+// interface AsyncClient does. It exists so `add auth` can stand on its own:
+// a project that hasn't asked for a queue shouldn't be made to run a second
+// binary just to send a verification email.
+//
+// The trade is real — /auth/register and /auth/forgot-password block until
+// SMTP answers, where the async client returns as soon as the job is written.
+// Add a worker later and the wiring in cmd/api/wiring.go switches to
+// AsyncClient; nothing in the user service changes.
+type SyncClient struct{ c *Client }
+
+func NewSyncClient(c *Client) *SyncClient { return &SyncClient{c: c} }
+
+// Send ignores ctx: there is no queue here to join a transaction, so the mail
+// goes out whether or not the caller's transaction ends up committing. That is
+// the guarantee the Postgres-backed queue exists to give you.
+func (c *SyncClient) Send(_ context.Context, to, subject, body string) error {
+	return c.c.Send(to, subject, body)
+}