@nakedev/go-scaffold 0.4.0 → 0.5.0

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

@@ -1,7 +1,7 @@
 # Coding Patterns: {{projectName}}
 
-> Status: generated by `@nakedev/go-scaffold`
-> Last updated: scaffold creation time
+> Status: generated by `@nakedev/go-scaffold`; current generated-project conventions
+> Last reviewed: generated at project creation and refreshed with feature docs
 
 ## Domain Package Shape
 
@@ -10,56 +10,92 @@ like this — copy the shape by hand if you ever add one without the CLI:
 
 ```text
 internal/app/<domain>/
-├── model/             # domain model(s) + GORM table(s) — a folder, one file per table
-│   └── model.go
-├── dto.go             # request/response structs + mapping (never leak the model directly)
-├── errors.go          # domain error catalog (<DOMAIN>_NOT_FOUND, ...)
-├── repository.go       # the only place that touches the DB for this domain, every method takes ctx
-├── service.go          # business logic; declares the repository interface it needs (mockable in tests)
-├── handler.go          # HTTP: routing, bind, delegate, respond
-├── service_test.go     # unit test, function-backed repository stub, no DB
-├── handler_test.go     # HTTP unit test, service stub, no DB
-└── repository_test.go  # Postgres integration test against migrated schema
+├── domain/
+│   ├── entity.go       # business state and invariants; no Gin/GORM/HTTP
+│   └── errors.go       # domain error catalog (<DOMAIN>_NOT_FOUND, ...)
+├── ports/
+│   └── repository.go   # consumer-owned persistence/application interfaces
+├── application/
+│   ├── dto.go          # transport-neutral use-case input/output types
+│   ├── service.go      # service-style use-case orchestration
+│   ├── commands.go     # CQRS writes, when selected
+│   ├── queries.go      # CQRS reads, when selected
+│   └── *_test.go       # application unit tests, no DB
+├── adapters/
+│   ├── inbound/http/
+│   │   ├── dto.go           # JSON/binding DTOs and application/HTTP mapping
+│   │   ├── handler.go       # Gin routing, error/response mapping
+│   │   └── handler_test.go  # HTTP adapter tests, no DB
+│   └── outbound/postgres/
+│       ├── model.go         # persistence model + explicit domain mapping
+│       ├── repository.go    # GORM adapter; the only DB access in the module
+│       └── repository_test.go # Postgres integration tests
+└── composition.go       # feature-local adapter → application → handler wiring
 ```
 
-### Model
-
-- Lives in its own `model` subpackage (`internal/app/<domain>/model`), imported
-  by the rest of the domain as `model.<Type>`
-- A folder, not a single file, so a domain with more than one table (e.g.
-  `order` + `order_item`) adds one file per table instead of growing a single
-  file — `generate module` only ever creates the first one
-- Every consumer inside `cmd/api/wiring.go` imports each domain's `model`
-  package under an alias (`ordermodel`, `usermodel`, ...) since they all share
-  the package name `model`
+`service.go` and `commands.go`/`queries.go` are mutually exclusive inside a
+module. Service and CQRS can coexist across different modules in the same
+modular monolith. The root package contains only `composition.go`; other code
+must import the specific boundary package it belongs to.
+
+### Domain and persistence model
+
+- `domain/entity.go` owns business state and invariants. It must not import
+  Gin, GORM, SQL drivers, Redis, HTTP, or environment configuration.
+- `adapters/outbound/postgres/model.go` owns persistence-only fields and
+  explicit `toDomain`/`fromDomain` mapping. A database column or GORM tag must
+  not silently become part of the business API.
+- A domain with more than one table should add one persistence model per table
+  in the outbound adapter, with the corresponding domain type or value object
+  kept in `domain/`.
 - `TableName()` returns a schema-qualified name (`order_svc.orders`, not
   `orders`) — every domain gets its own Postgres schema, created by its own
   migration (`CREATE SCHEMA IF NOT EXISTS`) and by `cmd/api/wiring.go` before
-  `AutoMigrate` runs in dev (AutoMigrate creates tables, never the schema they
-  live in). A cross-domain FK is still fine — see the FK rules below — this
-  only stops one domain's table from silently colliding with another's, or a
-  raw SQL `JOIN` from reaching into a domain it doesn't own without at least
-  naming the schema it's crossing into.
+  the development table bootstrap runs. A cross-domain FK is still fine — see
+  the FK rules below — this only stops one domain's table from silently
+  colliding with another's.
 
 ## Layer Conventions
 
 ### Handler
-- Owns routing, request binding, and calling the service
+- Owns routing, request binding, and calling the application service or
+  command/query port
 - No business logic — `c.Error(err); return` on failure, nothing more
 - Reads pagination via `pagination.Parse(c)`, wraps list responses with
   `p.Response(out)`
 - Reads the `:id` param via `httpx.ParseID(c)`
 
+### Commands and queries (opt-in CQRS)
+
+Use the project default recorded in `go-scaffold.config.json`, or override it
+per module with `--cqrs`, when the feature has distinct write invariants, read
+projections, consistency requirements, or scaling needs. `commands.go` owns
+state-changing application ports and handlers; `queries.go` owns read-only
+ports and handlers. `composition.go` constructs both, and the HTTP adapter
+selects the matching port for each route. They may share the same
+repository/database in this modular monolith — separate storage or event
+sourcing is not implied.
+
+The generated CQRS application has separate `CommandPort` and `QueryPort`
+interfaces and separate handlers. Its HTTP adapter receives both through
+`NewHandler`; there is no generated `application/service.go` facade to hide the
+split. New feature code should depend on the narrower port it actually needs.
+`generate module --defaults` uses the project default; choose the single service
+path for simple CRUD and CQRS only when the feature earns the extra boundary.
+
 ### Service
 - Contains the business logic, knows nothing about HTTP
-- Declares a `repository` interface for what it needs from the data layer —
-  this is what makes it mockable in `service_test.go` without a DB
+- Depends on consumer-owned interfaces from `ports/` for what it needs from
+  the data layer — this is what makes it mockable in `application/*_test.go`
+  without a DB
 - Generates the ID itself via `id.New()` before calling `repository.Create`
-- Maps DB errors to domain errors with `dberr.IsDuplicate` /
-  `dberr.IsForeignKey`, never lets a raw DB error escape
+- Returns domain errors and never constructs an HTTP response. The outbound
+  adapter maps driver errors with `dberr.IsDuplicate` /
+  `dberr.IsForeignKey` before they reach the application boundary.
 
-### Repository
-- The only file per domain that talks to GORM
+### Repository adapter
+- `adapters/outbound/postgres/repository.go` is the only module code that talks
+  to GORM
 - Every method takes `ctx context.Context` first, so a cancelled request
   cancels the query
 - Every query starts from `tx.From(ctx, r.db).WithContext(ctx)`, never from
@@ -75,16 +111,18 @@ internal/app/<domain>/
   and GORM can misinterpret a bare struct arg
 
 ### DTOs
-- `createInput`/`updateInput` (request, `binding:` tags) and `response`
-  (what's actually sent back) are separate types from the model — adding a
-  DB column later doesn't leak it to clients until you decide to
+- `application/dto.go` owns transport-neutral use-case inputs and output read
+  models. `adapters/inbound/http/dto.go` owns JSON names, binding/validation
+  tags, and explicit request/response mapping at the HTTP boundary.
+- When `generate method` adds a POST input, it adds both the application input
+  and an inbound HTTP DTO/mapping seam. Fill both deliberately; do not bind
+  Gin JSON directly into an application type.
 
 ### Error Catalog
-- One function per error, not a shared `var` — the error middleware writes
-  the request ID onto the returned pointer, so a shared instance would race
-  across concurrent requests
-- Codes are domain-specific (`ORDER_NOT_FOUND`), never the generic
-  `apperror.NewNotFound()` directly from a handler
+- Domain sentinels live in `domain/errors.go`; they are values used with
+  `errors.Is`, not HTTP errors or mutable request state.
+- The inbound adapter maps those sentinels to domain-specific HTTP codes
+  (`ORDER_NOT_FOUND`); domain/application code never constructs an HTTP error.
 
 ## Optimistic Locking
 
@@ -103,13 +141,13 @@ and `response` echoes it back: the client round-trips the value, and an
 update that arrives without one is rejected rather than treated as a blind
 overwrite.
 
-In a CRUD skeleton the service translates `ErrStaleVersion` into `errStale()`
-from the domain's error catalog (`<DOMAIN>_STALE`, HTTP 409) — a lost update
-is a client problem to retry, not a 500. A minimal module has the same
-`Repository.Update` and the same `errStale()` waiting for it, just no update
-path yet. Keep the chain intact when you add one by hand:
-`errors.Is(err, ErrStaleVersion)` → `errStale()`, and never set `Version` on
-the model yourself — `Repository.Update` owns the bump.
+The inbound adapter maps `ErrStaleVersion` to the domain's `<DOMAIN>_STALE`
+HTTP 409 response — a lost update is a client problem to retry, not a 500. A
+minimal module has the same `Repository.Update` guard waiting for its first
+update use case. Keep the chain intact when you add one by hand:
+`errors.Is(err, domain.ErrStaleVersion)` → adapter HTTP mapping, and never set
+`Version` on the persistence model yourself — `Repository.Update` owns the
+bump.
 
 ## Domains With a Foreign Key (Relations) — 3 Rules
 
@@ -121,20 +159,21 @@ if this project has one):
    associations / belongs-to — that's what keeps one domain package from
    importing another.
 2. **Declare the FK constraint in migration SQL**
-   (`REFERENCES ... ON DELETE ...`), not a GORM tag — AutoMigrate doesn't
-   create the constraint, which would make dev and prod schemas diverge.
-3. **Map the FK error to the right status** via `dberr.IsForeignKey` —
-   inserting a reference to a missing parent, or deleting a parent that
-   still has children, is a client error (409/422), not a 500. Don't
-   pre-check existence before insert; let the DB enforce it atomically and
-   catch the error — a pre-check has a TOCTOU race.
+   (`REFERENCES ... ON DELETE ...`), not a GORM tag — the development bootstrap
+   doesn't create the constraint, which would make dev and prod schemas diverge.
+3. **Map the FK error to the right status** in the outbound adapter with
+   `dberr.IsForeignKey`, then let the inbound adapter render it — inserting a
+   reference to a missing parent, or deleting a parent that still has children,
+   is a client error (409/422), not a 500. Don't pre-check existence before
+   insert; let the DB enforce it atomically and catch the error — a pre-check
+   has a TOCTOU race.
 
 ## Calling Another Domain's Logic
 
 For behavior, not just a data reference (e.g. `order` needs `user`'s email
-to put on a receipt) — the caller's `service.go` declares its own narrow
-interface for exactly what it needs, the same way it already declares a
-`repository` interface.
+to put on a receipt) — the caller's application boundary (`application/service.go`,
+`application/commands.go`, or `application/queries.go`) declares its own narrow interface for exactly
+what it needs, the same way it already declares a `repository` interface.
 
 **The interface speaks in the caller's own terms.** No domain package ever
 imports another domain package — `golangci-lint`'s `depguard` rules enforce
@@ -142,33 +181,33 @@ this, and it is the same rule that makes rule 1 above work. So the interface
 names primitives, or types the caller owns, never `user.Response`:
 
 ```go
-// order/service.go
+// order/application/service.go
 type userLookup interface {
     EmailOf(ctx context.Context, id uuid.UUID) (string, error)
 }
 ```
 
-`cmd/api/wiring.go` is the one place that knows both domains, so the adapter
-lives there — a func literal, not a type:
+The feature keeps its own repository/application/handler composition in
+`composition.go`; `cmd/api/wiring.go` supplies the DB and registers routes.
+Process-level adapters for cross-feature capabilities live in
+`internal/composition/`. For example, auth and RBAC are composed locally and
+the root passes only the role feature's public capabilities:
 
 ```go
-userSvc := user.NewService(userRepo, ...)
-orderSvc := order.NewService(orderRepo, order.UserLookupFunc(
-    func(ctx context.Context, id uuid.UUID) (string, error) {
-        u, err := userSvc.Get(ctx, id)
-        if err != nil {
-            return "", err
-        }
-        return u.Email, nil
-    },
-))
+roleComposition := role.NewCompositionFromDB(db, cfg.JWTSecret, cfg.AuthzCacheTTL)
+user.NewHandlerFromDB(
+    db, cfg, roleComposition.Service, roleComposition.Authz,
+).Register(api)
 ```
 
-where `order` provides the usual func-to-interface shim next to its
-interface:
+For ordinary cross-domain behaviour, the caller still declares a narrow
+interface next to its application boundary. Its local composition accepts that
+port, while `internal/composition/` supplies an adapter; the process root never
+reaches into the callee's repository or handler. A func-to-interface shim is
+one small option:
 
 ```go
-// order/service.go
+// order/application/service.go
 type UserLookupFunc func(ctx context.Context, id uuid.UUID) (string, error)
 
 func (f UserLookupFunc) EmailOf(ctx context.Context, id uuid.UUID) (string, error) {
@@ -183,6 +222,10 @@ can never silently ripple into `order`. The adapter is also the honest place
 to notice you are reaching for something that should have been the caller's
 own data.
 
+Cross-feature integration tests belong under `internal/integration`, where
+they may compose real feature services and adapters. A feature's own unit and
+repository tests stay inside its package and must not import another feature.
+
 - **One direction only.** If `user` would need to call back into `order`,
   don't wire it both ways — either the two belong in one domain, or the
   callback needs an event/queue, not a direct call.
@@ -198,30 +241,33 @@ own data.
 go-scaffold generate method <domain> <name> --type <get|post|put|patch|delete> [--get-mode all|one] [--field <name>]
 ```
 
-Patches `handler.go`/`service.go` (and `repository.go` + the `repository`
-interface + its `repositoryStub` test stub, for a `get --get-mode one --field`
-lookup) in place, at the `// go-scaffold:*` marker comments near the end of
-each file. **Don't delete those markers** — they're where the next
-`generate method` call inserts. The method body is always left as a `TODO`
-that compiles and returns a clean `500` (`apperror.NewInternal()`) rather
-than guessing at business logic — same spirit as `generate module`'s
-placeholder fields.
+Patches `adapters/inbound/http/handler.go`, its request DTO seam, and the application boundary (or
+`application/commands.go`/`application/queries.go` for a CQRS module; plus
+`ports/repository.go` and the outbound repository adapter/test seam for a
+`get --get-mode one --field` lookup) in place, at the
+`// go-scaffold:*` marker comments near the end of each file. **Don't delete
+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.
 
 ## Testing Conventions
 
 - Unit and integration tests live in the same directory as the code under
   test (Go convention) — never a separate `test/` folder. `test/` is only
   for e2e black-box suites or fixtures.
-- `service_test.go` uses a function-backed repository stub so each dependency
-  method has independent behavior and argument assertions.
-- `handler_test.go` uses a service stub — HTTP tests never need Postgres.
-- `repository_test.go` runs against a migrated Postgres database inside a
+- `application/service_test.go` uses a function-backed repository stub so each
+  dependency method has independent behavior and argument assertions.
+- `adapters/inbound/http/handler_test.go` checks route composition; focused
+  HTTP tests can inject an application port and never need Postgres.
+- `adapters/outbound/postgres/repository_test.go` runs against a migrated
+  Postgres database inside a
   transaction that's rolled back after each test. Local runs may skip when
   `TEST_DB_DSN` is unset; CI sets `REQUIRE_TEST_DB=true` so it must run.
 
 ## Docs Maintenance
 
-- This document describes the output produced by `go-scaffold create` for
-  the current configuration
-- If new domains are generated or the architecture changes, update this doc
-  to match the real project
+- This document describes the conventions used by generated domains and the
+  canonical split emitted by `go-scaffold`.
+- When a shared generator contract changes, update the templates and add a
+  regression test. Generated projects with hand-edited docs are left alone by
+  incremental feature refreshes and must be updated by their owners.

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

@@ -1,6 +1,6 @@
 # Tech Stack: {{projectName}}
 
-> Status: generated by `@nakedev/go-scaffold`
+> Status: generated by `@nakedev/go-scaffold`; refreshes as optional features are added
 
 ## Stack Overview
 
@@ -15,6 +15,9 @@
 | Logging | `log/slog`, JSON handler |
 | Migrations | [golang-migrate](https://github.com/golang-migrate/migrate) |
 | Testing | stdlib `testing`, real Postgres for integration tests |
+| Authentication | {{#if auth}}JWT access/refresh sessions, password recovery, email verification, provider login, and MFA{{else}}optional via `go-scaffold add auth`{{/if}} |
+| Authorization | {{#if rbac}}RBAC role/permission middleware{{else}}optional RBAC via `go-scaffold add rbac`{{/if}} |
+| Background jobs | {{#if worker}}{{queue}} queue backend with SMTP mail and `cmd/worker`{{else}}optional via `go-scaffold add worker`{{/if}} |
 
 ## Scaffolded Capabilities
 
@@ -24,6 +27,9 @@
 - Docker Compose (local Postgres): `{{#if docker}}enabled{{else}}disabled{{/if}}`
 - OpenAPI docs (`docs/openapi.yaml`, working-copy only — never served over HTTP): `{{#if openapiDocs}}enabled{{else}}disabled{{/if}}`
 - Metrics + tracing (Prometheus `/metrics`, OpenTelemetry for Gin + GORM, `cmd/api` only): `{{#if observability}}enabled{{else}}disabled{{/if}}`
+- Authentication and browser OAuth: `{{#if auth}}enabled{{else}}disabled{{/if}}`
+- Background worker and mail: `{{#if worker}}enabled{{else}}disabled{{/if}}`
+- RBAC roles, permissions, and authorization: `{{#if rbac}}enabled{{else}}disabled{{/if}}`
 - API route prefix: `{{#if apiPrefix}}/{{apiPrefix}}{{else}}(none){{/if}}`
 - CI (`.github/workflows/ci.yml` — build, vet, gofmt check, golangci-lint, `go test` with a real Postgres service): always enabled
 
@@ -31,8 +37,14 @@
 
 {{#if docker}}- Local Postgres comes from `docker-compose.yml`
 {{else}}- No Docker scaffolding included — bring your own Postgres and point `DB_DSN` at it
-{{/if}}- `AUTO_MIGRATE=true` (dev default) runs GORM AutoMigrate on boot; set it to
-  `false` in prod and run `migrate up` as a deploy step instead
+{{/if}}{{#if worker}}{{#if (eq queue "river")}}- Run `make river-migrate` before relying on queued jobs in a fresh database;
+  run `make river-migrate-test` as well when `REQUIRE_TEST_DB=true` runs the
+  River worker round-trip test.{{/if}}{{/if}}
+- `APP_ENV=development` enables the convenience table bootstrap;
+  `APP_ENV=production` requires `migrate up` as a deploy step instead
+{{#if worker}}{{#if (eq queue "river")}}- River uses the database/sql driver and polls for jobs instead of receiving
+  PostgreSQL LISTEN/NOTIFY wakeups; this is deliberate for a shared GORM pool.
+{{/if}}{{/if}}
 {{#if openapiDocs}}- `docs/openapi.yaml` is hand-written, not generated — update it whenever an
   endpoint or DTO changes
 {{/if}}{{#if observability}}- `OTEL_EXPORTER_OTLP_ENDPOINT` unset (dev default) means tracing exports
@@ -44,3 +56,6 @@
   resolves them to the versions that feature was built against instead of
   whatever happened to be newest that day. The full list is `go.mod`; this
   table only covers what `create` itself brings in
+- Auth, worker, and RBAC are opt-in. Their `add` commands update this snapshot
+  when the generated file is untouched; hand-edited docs are left alone and
+  require a manual update.

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

@@ -0,0 +1,45 @@
+package httpadapter
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/{{modulePath}}/application"
+
+	"github.com/google/uuid"
+)
+
+// response is the HTTP representation of the application output. Keep JSON
+// names and protocol-only fields at this inbound boundary.
+type response struct {
+	ID        uuid.UUID `json:"id"`
+	CreatedAt time.Time `json:"created_at"`
+	Version   int       `json:"version"`
+}
+
+func toResponse(out application.Response) response {
+	return response{ID: out.ID, CreatedAt: out.CreatedAt, Version: out.Version}
+}
+
+// Request DTOs belong to the inbound adapter. Keep JSON names, validation
+// tags, and request-to-command mapping here; application inputs stay usable
+// from jobs, tests, and other non-HTTP callers.
+type createInput struct {
+	// TODO: mirror the request fields added to application.CreateInput.
+}
+
+type updateInput struct {
+	Version int `json:"version" binding:"required,min=1"`
+	// TODO: mirror the update fields added to application.UpdateInput.
+}
+
+func toCreateInput(in createInput) application.CreateInput {
+	// TODO: map request fields explicitly as the application contract evolves.
+	_ = in
+	return application.CreateInput{}
+}
+
+func toUpdateInput(in updateInput) application.UpdateInput {
+	return application.UpdateInput{Version: in.Version}
+}
+
+// go-scaffold:dto

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

@@ -0,0 +1,28 @@
+package httpadapter
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/{{modulePath}}/application"
+
+	"github.com/google/uuid"
+)
+
+// response is the HTTP representation of the application output. Keep JSON
+// names and protocol-only fields at this inbound boundary.
+//nolint:unused // generate method uses this seam when the first endpoint is added.
+type response struct {
+	ID        uuid.UUID `json:"id"`
+	CreatedAt time.Time `json:"created_at"`
+	Version   int       `json:"version"`
+}
+
+//nolint:unused // generate method uses this seam when the first endpoint is added.
+func toResponse(out application.Response) response {
+	return response{ID: out.ID, CreatedAt: out.CreatedAt, Version: out.Version}
+}
+
+// A lean module has no HTTP body endpoints yet. The marker gives
+// `generate method` a stable place to add request DTOs when a POST is earned.
+
+// go-scaffold:dto

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

@@ -0,0 +1,182 @@
+// Package httpadapter is the Gin inbound adapter for {{pkg}}.
+package httpadapter
+
+import (
+	"errors"
+	"net/http"
+
+	"{{goModule}}/internal/app/{{modulePath}}/application"
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/shared/apperror"
+	"{{goModule}}/internal/shared/httpx"
+{{#if auth}}	"{{goModule}}/internal/shared/middleware"
+{{/if}}
+	"{{goModule}}/internal/shared/pagination"
+
+	"github.com/gin-gonic/gin"
+)
+
+type Handler struct {
+{{#if cqrs}}
+	commands application.CommandPort
+	queries  application.QueryPort
+{{else}}
+	svc application.ServicePort
+{{/if}}
+{{#if auth}}
+	jwtSecret string
+{{/if}}
+{{#if permission}}
+	authz *middleware.Authz
+{{/if}}
+}
+
+{{#if cqrs}}
+func NewHandler(commands application.CommandPort, queries application.QueryPort{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
+	h := &Handler{commands: commands, queries: queries}
+{{#if auth}}
+	h.jwtSecret = jwtSecret
+{{/if}}
+{{#if permission}}
+	h.authz = authz
+{{/if}}
+	return h
+}
+{{else}}
+func NewHandler(svc application.ServicePort{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
+	h := &Handler{svc: svc}
+{{#if auth}}
+	h.jwtSecret = jwtSecret
+{{/if}}
+{{#if permission}}
+	h.authz = authz
+{{/if}}
+	return h
+}
+{{/if}}
+
+func (h *Handler) Register(rg gin.IRouter) {
+	g := rg.Group("/{{plural}}"{{#if auth}}, middleware.RequireAuth(h.jwtSecret){{/if}}{{#if permission}}, h.authz.Require("{{permission}}"){{/if}})
+	g.POST("", h.create)
+	g.GET("", h.list)
+	g.GET("/:id", h.get)
+	g.PUT("/:id", h.update)
+	g.DELETE("/:id", h.delete)
+	// go-scaffold:handler-routes
+}
+
+func appError(err error) error {
+	switch {
+	case errors.Is(err, domain.ErrNotFound):
+		return applicationError(http.StatusNotFound, "{{errorPrefix}}_NOT_FOUND", "{{pkg}} not found")
+	case errors.Is(err, domain.ErrConflict):
+		return applicationError(http.StatusConflict, "{{errorPrefix}}_CONFLICT", "{{pkg}} already exists")
+	case errors.Is(err, domain.ErrStaleVersion):
+		return applicationError(http.StatusConflict, "{{errorPrefix}}_STALE", "{{pkg}} was modified by someone else — reload and try again")
+	case errors.Is(err, domain.ErrHasReferences):
+		return applicationError(http.StatusConflict, "{{errorPrefix}}_HAS_REFERENCES", "{{pkg}} still has related records")
+	case errors.Is(err, domain.ErrNotImplemented):
+		return applicationError(http.StatusNotImplemented, "NOT_IMPLEMENTED", "not implemented")
+	default:
+		return apperror.NewInternal(err)
+	}
+}
+
+func applicationError(status int, code, message string) *apperror.AppError {
+	// The HTTP adapter is the only layer allowed to create an HTTP error.
+	return apperror.New(status, code, message)
+}
+
+func (h *Handler) create(c *gin.Context) {
+	var in createInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+{{#if cqrs}}
+	m, err := h.commands.Create(c.Request.Context(), toCreateInput(in))
+{{else}}
+	m, err := h.svc.Create(c.Request.Context(), toCreateInput(in))
+{{/if}}
+	if err != nil {
+		c.Error(appError(err))
+		return
+	}
+	c.JSON(http.StatusCreated, toResponse(application.ToResponse(m)))
+}
+
+func (h *Handler) list(c *gin.Context) {
+	p := pagination.Parse(c)
+{{#if cqrs}}
+	items, err := h.queries.List(c.Request.Context(), p.Limit, p.Offset)
+{{else}}
+	items, err := h.svc.List(c.Request.Context(), p.Limit, p.Offset)
+{{/if}}
+	if err != nil {
+		c.Error(appError(err))
+		return
+	}
+	out := make([]response, len(items))
+	for i := range items {
+		out[i] = toResponse(application.ToResponse(&items[i]))
+	}
+	c.JSON(http.StatusOK, p.Response(out))
+}
+
+func (h *Handler) get(c *gin.Context) {
+	id, ok := httpx.ParseID(c)
+	if !ok {
+		return
+	}
+{{#if cqrs}}
+	m, err := h.queries.Get(c.Request.Context(), id)
+{{else}}
+	m, err := h.svc.Get(c.Request.Context(), id)
+{{/if}}
+	if err != nil {
+		c.Error(appError(err))
+		return
+	}
+	c.JSON(http.StatusOK, toResponse(application.ToResponse(m)))
+}
+
+func (h *Handler) update(c *gin.Context) {
+	id, ok := httpx.ParseID(c)
+	if !ok {
+		return
+	}
+	var in updateInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+{{#if cqrs}}
+	m, err := h.commands.Update(c.Request.Context(), id, toUpdateInput(in))
+{{else}}
+	m, err := h.svc.Update(c.Request.Context(), id, toUpdateInput(in))
+{{/if}}
+	if err != nil {
+		c.Error(appError(err))
+		return
+	}
+	c.JSON(http.StatusOK, toResponse(application.ToResponse(m)))
+}
+
+func (h *Handler) delete(c *gin.Context) {
+	id, ok := httpx.ParseID(c)
+	if !ok {
+		return
+	}
+{{#if cqrs}}
+	err := h.commands.Delete(c.Request.Context(), id)
+{{else}}
+	err := h.svc.Delete(c.Request.Context(), id)
+{{/if}}
+	if err != nil {
+		c.Error(appError(err))
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// go-scaffold:handler-funcs