@nakedev/go-scaffold 0.5.5 → 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/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,7 +41,10 @@ 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
@@ -49,7 +53,7 @@ func (h *Handler) list(c *gin.Context) {
 	for i := range items {
 		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) {

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

@@ -36,9 +36,17 @@ type PermissionResponse struct {
 }
 
 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
 }
 

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

@@ -47,7 +47,7 @@ internal/
 ├── platform/                # talks to real external systems
 │   └── database/             # PostgreSQL connection and pool
 ├── shared/                  # pure logic/framework glue, no I/O
-│   ├── config/  apperror/  dberr/  httpx/  id/
+│   ├── config/  apperror/  dberr/  dbq/  httpx/  id/
 │   └── middleware/  pagination/  tx/
 └── app/                     # domain packages (one per feature)
     └── <domain>/
@@ -129,12 +129,15 @@ call site, no error-shape drift between domains.
 - DB errors are classified once in `shared/dberr` (`IsDuplicate`,
   `IsForeignKey`) and mapped to the right HTTP status per domain
 
-## 6. Pagination
+## 6. Pagination and Filtering
 
-**Decision:** Shared `limit`/`offset` parsing and response envelope
-(`shared/pagination`), used by every list endpoint.
-**Rationale:** One implementation, one response shape (`{data, limit,
-offset}`) — no per-domain reinvention.
+**Decision:** Shared `limit`/`offset`/`q` parsing and response envelope
+(`shared/pagination`), used by every list endpoint, with the SQL a filter
+repeats in `shared/dbq`. A list takes one filter struct from `ports/` and
+answers a page plus its total.
+**Rationale:** One implementation, one response shape (`{data, limit, offset,
+total}`) — no per-domain reinvention, and no per-domain LIKE escaping to get
+wrong. See `patterns.md`, "Filtered Lists".
 
 ## 7. Persistence
 

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

@@ -11,3 +11,8 @@ Offset:
   name: offset
   in: query
   schema: { type: integer, default: 0, minimum: 0 }
+Search:
+  name: q
+  in: query
+  description: "free-text search; which columns it matches is documented per endpoint"
+  schema: { type: string, maxLength: 100 }

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

@@ -4,6 +4,7 @@ PageEnvelope:
   properties:
     limit: { type: integer }
     offset: { type: integer }
+    total: { type: integer, description: "rows the filter matched; present on endpoints that count them" }
 
 Error:
   type: object

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

@@ -250,6 +250,66 @@ those markers** — they're where the next `generate method` call inserts. The
 method body is always left as a compiling `TODO` rather than guessing at
 business logic — same spirit as `generate module`'s placeholder fields.
 
+## Filtered Lists — one filter struct, a page and its total
+
+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
+*no* filter, not `400` — a list narrows on a best effort.
+
+**2. One filter struct, in `ports/`.** `ports.ListFilter` travels whole through
+handler → application → repository, so adding a filter later is one field and
+not a fourth positional argument on three signatures. It lives in `ports/`
+because that is the only package all three may import — `ports` importing
+`application` would be a cycle. Its zero value means "the first page of
+everything".
+
+```go
+type ListFilter struct {
+    Search string
+    Limit  int
+    Offset int
+    // Status, OwnerID, DateFrom … whatever this module actually filters by.
+}
+```
+
+**3. The repository returns the page *and* the total**, because a client that
+pages needs both and only SQL can answer either:
+
+```go
+FindAll(context.Context, ListFilter) ([]domain.Thing, int64, error)
+```
+
+Build the conditions in a closure and call it once per query — conditions
+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.
+
+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.
+
+**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.
+
+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
+envelope, not in it, and are computed from the filter minus the field the tabs
+switch. A tab that recounted itself when clicked would always read the same
+number.
+
 ## Testing Conventions
 
 - Unit and integration tests live in the same directory as the code under

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

@@ -21,9 +21,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; narrow it with ?q= and whatever filters this module adds"
       content:
         application/json:
           schema: