@nakedev/go-scaffold 0.5.4 → 0.8.0

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

@@ -10,11 +10,28 @@ import (
 	"github.com/google/uuid"
 )
 
+// ListFilter is the whole question the admin user list asks. The zero value is
+// "the first page of everything", so a caller only sets what it narrows by.
+//
+// Put new filters here as fields rather than as arguments: one struct travels
+// handler -> application -> repository, so adding a filter later is a field
+// and not a fourth parameter on three signatures. See
+// docs/architect/patterns.md.
+type ListFilter struct {
+	// Search is ?q= as shared/pagination parsed it, matched against the name
+	// and the primary email address.
+	Search string
+	Limit  int
+	Offset int
+}
+
 type UserRepository interface {
 	FindByEmail(context.Context, string) (*domain.User, error)
 	FindByID(context.Context, uuid.UUID) (*domain.User, error)
 	UpdateUser(context.Context, *domain.User) error
-	FindAll(context.Context, int, int) ([]domain.User, error)
+	// FindAll answers one page and the total the filter matched, which is what
+	// a client needs to draw "page 3 of 12".
+	FindAll(context.Context, ListFilter) ([]domain.User, int64, error)
 	FindIdentity(context.Context, uuid.UUID, domain.Provider) (*domain.Identity, error)
 	ListIdentities(context.Context, uuid.UUID) ([]domain.Identity, error)
 	FindIdentityByProviderUID(context.Context, string, string) (*domain.Identity, error)
@@ -23,8 +40,9 @@ type UserRepository interface {
 	UpdateIdentity(context.Context, *domain.Identity) error
 	DeleteIdentity(context.Context, uuid.UUID, domain.Provider) error
 	LoginLockedUntil(context.Context, string) (time.Time, error)
-	RecordLoginFailure(context.Context, string, int, time.Duration) error
-	ClearLoginFailures(context.Context, string) error
+{{#if fixedLockout}}	RecordLoginFailure(context.Context, string, string, int, time.Duration, time.Duration) error
+{{else}}	RecordLoginFailure(context.Context, string, string, int, time.Duration) error
+{{/if}}	ClearLoginFailures(context.Context, string) error
 	// go-scaffold:repository-interface
 }
 

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

@@ -2,9 +2,19 @@
 -- so it works for addresses that have no account (otherwise throttling itself
 -- leaks which addresses are registered) and so this table is not a user list.
 -- See adapters/outbound/postgres/model.go for why this exists separately from the rate limiter.
+-- last_attempt fingerprints the most recent wrong password so replaying the
+-- same one does not count again (see RecordLoginFailure). It is an HMAC, not a
+-- plain hash: a leaked table must not become a dictionary of near-miss
+-- passwords for known accounts.
 CREATE TABLE user_svc.login_throttle (
     email_hash   TEXT PRIMARY KEY,
     failures     INTEGER NOT NULL DEFAULT 0,
+    last_attempt TEXT,
     locked_until TIMESTAMPTZ,
     updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
 );
+
+-- The table sweeps itself: every failed login deletes the rows nothing has
+-- touched for a day (see RecordLoginFailure). This index is what keeps that
+-- delete from scanning the table each time.
+CREATE INDEX login_throttle_updated_at_idx ON user_svc.login_throttle (updated_at);

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

@@ -6,9 +6,10 @@ get:
   parameters:
     - $ref: '../common/parameters.yaml#/Limit'
     - $ref: '../common/parameters.yaml#/Offset'
+    - $ref: '../common/parameters.yaml#/Search'
   responses:
     "200":
-      description: paginated list
+      description: "paginated list; `q` matches code and display name"
       content:
         application/json:
           schema:

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

@@ -6,9 +6,10 @@ get:
   parameters:
     - $ref: '../common/parameters.yaml#/Limit'
     - $ref: '../common/parameters.yaml#/Offset'
+    - $ref: '../common/parameters.yaml#/Search'
   responses:
     "200":
-      description: paginated list
+      description: "paginated list; `q` matches name and primary email"
       content:
         application/json:
           schema:

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

@@ -0,0 +1,52 @@
+package httpadapter
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/role/application"
+)
+
+// Request DTOs belong to the inbound adapter. Keep JSON names and binding
+// tags out of application inputs so role use cases remain transport-neutral.
+type createInput struct {
+	Code string `json:"code"`
+	Name string `json:"name"`
+}
+
+func toCreateInput(in createInput) application.CreateInput {
+	return application.CreateInput{Code: in.Code, Name: in.Name}
+}
+
+type setPermissionsInput struct {
+	PermissionCodes *[]string `json:"permission_codes"`
+}
+
+func toSetPermissionsInput(in setPermissionsInput) application.SetPermissionsInput {
+	return application.SetPermissionsInput{PermissionCodes: in.PermissionCodes}
+}
+
+// Response DTOs belong to the inbound adapter too. Application responses are
+// deliberately free of JSON tags and are mapped explicitly before encoding.
+type roleResponse struct {
+	Code        string    `json:"code"`
+	Name        string    `json:"name"`
+	IsSystem    bool      `json:"is_system"`
+	Permissions []string  `json:"permissions"`
+	CreatedAt   time.Time `json:"created_at"`
+}
+
+func toRoleResponse(out application.RoleResponse) roleResponse {
+	return roleResponse{
+		Code: out.Code, Name: out.Name, IsSystem: out.IsSystem,
+		Permissions: out.Permissions, CreatedAt: out.CreatedAt,
+	}
+}
+
+type permissionResponse struct {
+	Code        string `json:"code"`
+	Description string `json:"description"`
+}
+
+func toPermissionResponse(out application.PermissionResponse) permissionResponse {
+	return permissionResponse{Code: out.Code, Description: out.Description}
+}

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

@@ -9,6 +9,7 @@ import (
 
 	"{{goModule}}/internal/app/role/application"
 	"{{goModule}}/internal/app/role/domain"
+	"{{goModule}}/internal/app/role/ports"
 	"{{goModule}}/internal/shared/apperror"
 	"{{goModule}}/internal/shared/httpx"
 	"{{goModule}}/internal/shared/middleware"
@@ -40,49 +41,53 @@ func (h *Handler) Register(rg gin.IRouter) {
 
 func (h *Handler) list(c *gin.Context) {
 	p := pagination.Parse(c)
-	items, err := h.svc.List(c.Request.Context(), p.Limit, p.Offset)
+	// 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}
+	items, total, err := h.svc.List(c.Request.Context(), filter)
 	if err != nil {
 		c.Error(toHTTPError(err))
 		return
 	}
-	out := make([]application.RoleResponse, len(items))
+	out := make([]roleResponse, len(items))
 	for i := range items {
-		out[i] = application.ToRoleResponse(items[i])
+		out[i] = toRoleResponse(application.ToRoleResponse(items[i]))
 	}
-	c.JSON(http.StatusOK, p.Response(out))
+	c.JSON(http.StatusOK, p.ResponseWithTotal(out, total))
 }
 
 func (h *Handler) create(c *gin.Context) {
-	var in application.CreateInput
+	var in createInput
 	if err := c.ShouldBindJSON(&in); err != nil {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	item, err := h.svc.Create(c.Request.Context(), in)
+	item, err := h.svc.Create(c.Request.Context(), toCreateInput(in))
 	if err != nil {
 		c.Error(toHTTPError(err))
 		return
 	}
-	c.JSON(http.StatusCreated, application.ToRoleResponse(*item))
+	c.JSON(http.StatusCreated, toRoleResponse(application.ToRoleResponse(*item)))
 }
 
 func (h *Handler) setPermissions(c *gin.Context) {
-	var in application.SetPermissionsInput
+	var in setPermissionsInput
 	if err := c.ShouldBindJSON(&in); err != nil {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	if in.PermissionCodes == nil {
+	appInput := toSetPermissionsInput(in)
+	if appInput.PermissionCodes == nil {
 		c.Error(apperror.NewValidation("invalid role input", map[string]string{"permission_codes": "is required"}))
 		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"), *appInput.PermissionCodes)
 	if err != nil {
 		c.Error(toHTTPError(err))
 		return
 	}
 	h.authz.Invalidate(item.Role.Code)
-	c.JSON(http.StatusOK, application.ToRoleResponse(*item))
+	c.JSON(http.StatusOK, toRoleResponse(application.ToRoleResponse(*item)))
 }
 
 func (h *Handler) delete(c *gin.Context) {
@@ -101,9 +106,9 @@ func (h *Handler) listPermissions(c *gin.Context) {
 		c.Error(toHTTPError(err))
 		return
 	}
-	out := make([]application.PermissionResponse, len(items))
+	out := make([]permissionResponse, len(items))
 	for i := range items {
-		out[i] = application.ToPermissionResponse(items[i])
+		out[i] = toPermissionResponse(application.ToPermissionResponse(items[i]))
 	}
 	c.JSON(http.StatusOK, p.Response(out))
 }

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

@@ -6,6 +6,7 @@ import (
 
 	"{{goModule}}/internal/app/role/domain"
 	"{{goModule}}/internal/app/role/ports"
+	"{{goModule}}/internal/shared/dbq"
 	"{{goModule}}/internal/shared/dberr"
 	"{{goModule}}/internal/shared/tx"
 
@@ -27,17 +28,33 @@ func (r *Repository) PermissionCodes(ctx context.Context, roleCode string) ([]st
 	return codes, mapDatabaseError(err)
 }
 
-func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]domain.Role, error) {
+// FindAll answers one page of the filter and how many roles it matched
+// altogether. Two queries, because a count over a LIMITed query would only
+// ever count the page.
+func (r *Repository) FindAll(ctx context.Context, filter ports.ListFilter) ([]domain.Role, int64, error) {
+	// A closure rather than one *gorm.DB reused twice: conditions accumulate
+	// on the value, so the count would silently inherit the page's LIMIT.
+	matching := func() *gorm.DB {
+		q := tx.From(ctx, r.db).WithContext(ctx).Model(&Role{})
+		return dbq.Search(q, filter.Search, "code", "name")
+	}
+
+	var total int64
+	if err := matching().Count(&total).Error; err != nil {
+		return nil, 0, mapDatabaseError(err)
+	}
+
 	var rows []Role
-	err := tx.From(ctx, r.db).WithContext(ctx).Order("code").Limit(limit).Offset(offset).Find(&rows).Error
+	// code is unique, so it needs no tiebreaker to page stably.
+	err := matching().Order("code").Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error
 	if err != nil {
-		return nil, mapDatabaseError(err)
+		return nil, 0, mapDatabaseError(err)
 	}
 	items := make([]domain.Role, len(rows))
 	for i := range rows {
 		items[i] = toDomainRole(&rows[i])
 	}
-	return items, nil
+	return items, total, nil
 }
 
 func (r *Repository) FindByCode(ctx context.Context, code string) (*domain.Role, error) {

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

@@ -9,12 +9,12 @@ import (
 const PermRoleManage = "role:manage"
 
 type CreateInput struct {
-	Code string `json:"code"`
-	Name string `json:"name"`
+	Code string
+	Name string
 }
 
 type SetPermissionsInput struct {
-	PermissionCodes *[]string `json:"permission_codes"`
+	PermissionCodes *[]string
 }
 
 type RoleListItem struct {
@@ -23,22 +23,30 @@ type RoleListItem struct {
 }
 
 type RoleResponse struct {
-	Code        string    `json:"code"`
-	Name        string    `json:"name"`
-	IsSystem    bool      `json:"is_system"`
-	Permissions []string  `json:"permissions"`
-	CreatedAt   time.Time `json:"created_at"`
+	Code        string
+	Name        string
+	IsSystem    bool
+	Permissions []string
+	CreatedAt   time.Time
 }
 
 type PermissionResponse struct {
-	Code        string `json:"code"`
-	Description string `json:"description"`
+	Code        string
+	Description string
 }
 
 func ToRoleResponse(item RoleListItem) RoleResponse {
+	// A role holding nothing must still answer `[]`, never `null`: Pluck
+	// leaves the slice nil, and the seeded `staff` role starts with no grants
+	// at all — so this is the common case, not an edge one. Every HTTP path
+	// (list, create, set-permissions) maps through here.
+	permissions := item.Permissions
+	if permissions == nil {
+		permissions = []string{}
+	}
 	return RoleResponse{
 		Code: item.Role.Code, Name: item.Role.Name, IsSystem: item.Role.IsSystem,
-		Permissions: item.Permissions, CreatedAt: item.Role.CreatedAt,
+		Permissions: permissions, CreatedAt: item.Role.CreatedAt,
 	}
 }
 

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

@@ -15,7 +15,7 @@ import (
 type ServicePort interface {
 	PermissionsOf(context.Context, string) (map[string]struct{}, error)
 	CodeExists(context.Context, string) (bool, error)
-	List(context.Context, int, int) ([]RoleListItem, error)
+	List(context.Context, ports.ListFilter) ([]RoleListItem, int64, error)
 	Create(context.Context, CreateInput) (*RoleListItem, error)
 	SetPermissions(context.Context, string, []string) (*RoleListItem, error)
 	Delete(context.Context, string) error
@@ -50,20 +50,20 @@ func (s *Service) CodeExists(ctx context.Context, code string) (bool, error) {
 	return true, nil
 }
 
-func (s *Service) List(ctx context.Context, limit, offset int) ([]RoleListItem, error) {
-	roles, err := s.repo.FindAll(ctx, limit, offset)
+func (s *Service) List(ctx context.Context, filter ports.ListFilter) ([]RoleListItem, int64, error) {
+	roles, total, err := s.repo.FindAll(ctx, filter)
 	if err != nil {
-		return nil, err
+		return nil, 0, err
 	}
 	out := make([]RoleListItem, len(roles))
 	for i, role := range roles {
 		perms, err := s.repo.PermissionCodes(ctx, role.Code)
 		if err != nil {
-			return nil, err
+			return nil, 0, err
 		}
 		out[i] = RoleListItem{Role: role, Permissions: perms}
 	}
-	return out, nil
+	return out, total, nil
 }
 
 var roleCodePattern = regexp.MustCompile(`^[a-z][a-z0-9_]*$`)

package/templates/add/rbac/internal/app/role/application/service_test.go.hbs

@@ -2,11 +2,14 @@ package application
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"net/http"
+	"strings"
 	"testing"
 
 	"{{goModule}}/internal/app/role/domain"
+	"{{goModule}}/internal/app/role/ports"
 )
 
 // fakeRepo = mock of the repository interface, so the service can be tested
@@ -23,7 +26,9 @@ type fakeRepo struct {
 }
 
 func (f *fakeRepo) PermissionCodes(context.Context, string) ([]string, error) { return nil, nil }
-func (f *fakeRepo) FindAll(context.Context, int, int) ([]domain.Role, error)  { return nil, nil }
+func (f *fakeRepo) FindAll(context.Context, ports.ListFilter) ([]domain.Role, int64, error) {
+	return nil, 0, nil
+}
 func (f *fakeRepo) FindByCode(context.Context, string) (*domain.Role, error) {
 	if f.findErr != nil {
 		return nil, f.findErr
@@ -124,3 +129,16 @@ func TestService_Delete_SystemRoleRejected(t *testing.T) {
 		t.Fatalf("want 409 for a system role, got %d", got)
 	}
 }
+
+func TestToRoleResponse_EmptyPermissionsMarshalAsArray(t *testing.T) {
+	// The repository's Pluck leaves the slice nil for a role with no grants,
+	// and `null` breaks any client that treats permissions as a list — which
+	// is every one of them, since the seeded `staff` role starts empty.
+	body, err := json.Marshal(ToRoleResponse(RoleListItem{Role: domain.Role{Code: "staff"}}))
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if !strings.Contains(string(body), `"Permissions":[]`) {
+		t.Fatalf("want an empty array for a role with no permissions, got %s", body)
+	}
+}

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

@@ -7,9 +7,21 @@ import (
 	"{{goModule}}/internal/app/role/domain"
 )
 
+// ListFilter is the whole question the role list asks. The zero value is "the
+// first page of everything", so a caller only sets what it narrows by. Put new
+// filters here as fields rather than as arguments — see
+// docs/architect/patterns.md.
+type ListFilter struct {
+	// Search is ?q= as shared/pagination parsed it, matched against the code
+	// and the display name.
+	Search string
+	Limit  int
+	Offset int
+}
+
 type Repository interface {
 	PermissionCodes(context.Context, string) ([]string, error)
-	FindAll(context.Context, int, int) ([]domain.Role, error)
+	FindAll(context.Context, ListFilter) ([]domain.Role, int64, error)
 	FindByCode(context.Context, string) (*domain.Role, error)
 	Create(context.Context, *domain.Role) error
 	SetPermissions(context.Context, string, []string) error

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

@@ -172,7 +172,7 @@ method:
 
 | Type | Shape | Generated behavior |
 |---|---|---|
-| get --get-mode all | GET /<plural>/<name> | Reuses FindAll; add real filtering |
+| get --get-mode all | GET /<plural>/<name> | Reuses FindAll (page + total, `?q=` parsed); add fields to ports.ListFilter |
 | get --get-mode one --field <f> | GET /<plural>/<f>/:<f> | Adds a repository lookup and test seam |
 | post | POST /<plural>/<name> | Body DTO plus internal-error TODO |
 | put / patch | <VERB> /<plural>/:id/<name> | Safe 501 Not Implemented; no repository read/write |

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

@@ -102,6 +102,13 @@ go-scaffold generate module <name> --defaults
 go-scaffold generate method <module> <name> --type <get|post|put|patch|delete>
 ```
 
+`generate method` extends the modules `generate module` created, and the one
+`add auth` owns. It refuses `add rbac`'s: that module builds its response from
+a role *together with its permissions* rather than from the entity, and the
+generator has no shape to write against there. Add an endpoint to it by hand —
+a route in `internal/app/role/adapters/inbound/http/handler.go`, a method on
+the application service, and its entry in `docs/`.
+
 Pass every value as a flag in CI. In an interactive shell, omitted values use
 the project defaults as the initial wizard choices. In a non-interactive
 shell, omitted values prompt and the command exits without writing.
@@ -142,7 +149,8 @@ These remain deliberate engineering work:
 - any work in a repository that lacks `go-scaffold.config.json`.
 
 Generated methods are explicit stubs. `generate method` GET-all reuses
-`FindAll` until real filtering is added; POST and DELETE return an internal
+`FindAll`, so it answers the same rows as the module's own list until
+`ports.ListFilter` grows the fields that endpoint narrows by; POST and DELETE return an internal
 error until implemented; PUT/PATCH intentionally return `501 Not Implemented`
 and must not read or write a record before their behavior is designed. Treat
 the generated OpenAPI TODO contract as incomplete, not as a promise that the

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

@@ -50,10 +50,11 @@ internal/
 │   ├── config/                # loads config from env
 │   ├── apperror/              # central error type (status + payload)
 │   ├── dberr/                 # maps DB errors to constraint kind — shared by every domain
+│   ├── dbq/                   # the SQL every list repeats: escaped contains-search
 │   ├── httpx/                 # HTTP helpers shared by every domain
 │   ├── id/                    # UUID v7 generation (id.New)
 │   ├── middleware/            # RequestID, Logger, Error, CORS{{#if auth}}, auth{{/if}}{{#if rbac}}, RBAC{{/if}}{{#if observability}}, metrics, tracing{{/if}}
-│   ├── pagination/            # parses ?limit=&offset=, response envelope
+│   ├── pagination/            # parses ?limit=&offset=&q=, response envelope
 │   └── tx/                    # carries a transaction on the context
 └── app/                       # one package per domain, added with `generate module`
 ```

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

@@ -0,0 +1,47 @@
+// Package dbq holds the SQL every list endpoint repeats, so a filter is not
+// re-derived — and re-broken — once per module.
+package dbq
+
+import (
+	"strings"
+
+	"gorm.io/gorm"
+)
+
+// likeEscaper protects the pattern's own metacharacters. Backslash first, or
+// it would escape the backslashes the other two just added.
+var likeEscaper = strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`)
+
+// LikePattern turns a search term into a `contains` pattern with the wildcards
+// escaped, so searching for "50%" looks for the three characters "50%" rather
+// than for anything starting with 50.
+//
+// Postgres already treats backslash as LIKE's escape character, so the pattern
+// needs no trailing ESCAPE clause.
+func LikePattern(term string) string {
+	return "%" + likeEscaper.Replace(term) + "%"
+}
+
+// Search narrows db to rows where any of cols contains term, ignoring case.
+// An empty term returns db untouched, so a caller applies it unconditionally:
+//
+//	q = dbq.Search(q, filter.Search, "name", "code")
+//
+// cols are SQL identifiers written by the caller. Never pass one that came off
+// the request — they are interpolated; only the term is a bound parameter.
+func Search(db *gorm.DB, term string, cols ...string) *gorm.DB {
+	if term == "" || len(cols) == 0 {
+		return db
+	}
+	pattern := LikePattern(term)
+	conds := make([]string, len(cols))
+	args := make([]any, len(cols))
+	for i, col := range cols {
+		conds[i] = col + " ILIKE ?"
+		args[i] = pattern
+	}
+	// Parenthesised here rather than trusting the driver to group it: ANDed
+	// with a second filter, an unwrapped OR would widen the result instead of
+	// narrowing it.
+	return db.Where("("+strings.Join(conds, " OR ")+")", args...)
+}

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

@@ -0,0 +1,66 @@
+package dbq
+
+import (
+	"strings"
+	"testing"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+func TestLikePatternEscapesWildcards(t *testing.T) {
+	// A term the user typed is data, not pattern: each of these three would
+	// otherwise silently widen the search.
+	for term, want := range map[string]string{
+		"nake":   "%nake%",
+		"50%":    `%50\%%`,
+		"a_b":    `%a\_b%`,
+		`c:\tmp`: `%c:\\tmp%`,
+	} {
+		if got := LikePattern(term); got != want {
+			t.Errorf("LikePattern(%q) = %q, want %q", term, got, want)
+		}
+	}
+}
+
+// dryRunDB builds SQL without a server, so this stays a unit test.
+func dryRunDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	db, err := gorm.Open(postgres.New(postgres.Config{DSN: "postgres://x/y"}), &gorm.Config{
+		DryRun:               true,
+		DisableAutomaticPing: true,
+	})
+	if err != nil {
+		t.Fatalf("open dry-run database: %v", err)
+	}
+	return db
+}
+
+type row struct {
+	ID   int
+	Name string
+	Code string
+}
+
+func TestSearchGroupsItsOrAndKeepsTheTermBound(t *testing.T) {
+	db := dryRunDB(t)
+	stmt := Search(db.Model(&row{}).Where("id = ?", 1), "ab", "name", "code").Find(&[]row{}).Statement
+	sql := stmt.SQL.String()
+
+	// Unparenthesised, `id = 1 AND name ILIKE ... OR code ILIKE ...` matches
+	// every row whose code hits — the filter beside it stops applying.
+	if !strings.Contains(sql, "(name ILIKE $2 OR code ILIKE $3)") {
+		t.Errorf("OR is not grouped: %s", sql)
+	}
+	if strings.Contains(sql, "ab") {
+		t.Errorf("search term was interpolated, not bound: %s", sql)
+	}
+}
+
+func TestSearchWithoutATermIsANoOp(t *testing.T) {
+	db := dryRunDB(t)
+	stmt := Search(db.Model(&row{}), "", "name").Find(&[]row{}).Statement
+	if strings.Contains(stmt.SQL.String(), "ILIKE") {
+		t.Errorf("empty term still filtered: %s", stmt.SQL.String())
+	}
+}

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

@@ -2,6 +2,7 @@ package pagination
 
 import (
 	"strconv"
+	"strings"
 
 	"github.com/gin-gonic/gin"
 )
@@ -9,15 +10,23 @@ import (
 const (
 	defaultLimit = 20
 	maxLimit     = 100
+	// Long enough for any name or address anyone types into a search box, and
+	// short enough that the LIKE it becomes cannot be used to make the
+	// database do real work.
+	maxSearchRunes = 100
 )
 
-// Params is a validated limit/offset pair (default 20, capped at 100).
+// Params is a validated limit/offset pair (default 20, capped at 100) plus the
+// free-text search the list was asked for.
 type Params struct {
 	Limit  int
 	Offset int
+	// 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
 }
 
-// Parse reads ?limit=&offset= off the request so every feature parses the
+// Parse reads ?limit=&offset=&q= off the request so every feature parses the
 // same way.
 func Parse(c *gin.Context) Params {
 	p := Params{Limit: defaultLimit}
@@ -30,6 +39,14 @@ func Parse(c *gin.Context) Params {
 	if v, err := strconv.Atoi(c.Query("offset")); err == nil && v >= 0 {
 		p.Offset = v
 	}
+	// Runes, not bytes: one non-Latin character is often three bytes, and
+	// cutting one in half would send invalid UTF-8 into the query.
+	if q := strings.TrimSpace(c.Query("q")); q != "" {
+		if r := []rune(q); len(r) > maxSearchRunes {
+			q = string(r[:maxSearchRunes])
+		}
+		p.Search = q
+	}
 	return p
 }