@nakedev/go-scaffold 0.3.3 → 0.4.3

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

@@ -14,7 +14,6 @@ type Config struct {
 	Port              string
 	DBDSN             string
 	LogLevel          string
-	AutoMigrate       bool
 	DBMaxOpenConns    int
 	DBMaxIdleConns    int
 	DBConnMaxLifetime time.Duration
@@ -56,13 +55,6 @@ func Load() Config {
 		panic(fmt.Sprintf("invalid APP_ENV %q — must be development or production", cfg.AppEnv))
 	}
 
-	// Defaults off in production, which is why it's set here rather than in
-	// the literal above — it needs a validated AppEnv first. AutoMigrate
-	// rewrites the schema at boot AND skips CheckMigrationVersion entirely
-	// (see main.go), so a deploy that merely forgets to set it used to get
-	// both. AUTO_MIGRATE=true still forces it on if you really mean it.
-	cfg.AutoMigrate = env("AUTO_MIGRATE", strconv.FormatBool(!cfg.IsProd())) == "true"
-
 	return cfg
 }
 

package/templates/create/base/internal/shared/middleware/cors_test.go.hbs

@@ -0,0 +1,40 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestCORS_AllowsOnlyConfiguredExactOrigins(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	tests := []struct {
+		name             string
+		origin           string
+		wantAllowOrigin  string
+		wantCredentials  bool
+	}{
+		{name: "allowed exact origin", origin: "http://localhost:3000", wantAllowOrigin: "http://localhost:3000", wantCredentials: true},
+		{name: "different origin denied", origin: "https://evil.example", wantAllowOrigin: "", wantCredentials: false},
+		{name: "wildcard is not a substitute", origin: "*", wantAllowOrigin: "", wantCredentials: false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			router := gin.New()
+			router.Use(CORS([]string{"http://localhost:3000"}))
+			router.GET("/refresh", func(c *gin.Context) { c.Status(http.StatusNoContent) })
+			request := httptest.NewRequest(http.MethodGet, "/refresh", nil)
+			request.Header.Set("Origin", tt.origin)
+			response := httptest.NewRecorder()
+			router.ServeHTTP(response, request)
+			if got := response.Header().Get("Access-Control-Allow-Origin"); got != tt.wantAllowOrigin {
+				t.Fatalf("Access-Control-Allow-Origin = %q, want %q", got, tt.wantAllowOrigin)
+			}
+			if got := response.Header().Get("Access-Control-Allow-Credentials") == "true"; got != tt.wantCredentials {
+				t.Fatalf("Allow-Credentials = %v, want %v", got, tt.wantCredentials)
+			}
+		})
+	}
+}

package/templates/create/base/internal/shared/middleware/error.go.hbs

@@ -29,14 +29,24 @@ func Error(exposeDetail bool) gin.HandlerFunc {
 		if !errors.As(err.Err, &appErr) {
 			// Unexpected error: log the real thing, answer the client generically.
 			slog.Error("unhandled error", "error", err.Err, "request_id", c.GetString(RequestIDKey))
-			appErr = apperror.NewInternal()
+			appErr = apperror.NewInternal(err.Err)
 			if exposeDetail {
 				appErr.Details = err.Err.Error()
 			}
-		} else if !exposeDetail {
-			// Known AppError (e.g. VALIDATION_ERROR): still strip Details in
-			// prod, so a direct API call doesn't get field-level hints.
-			appErr.Details = nil
+		} else {
+			// Internal AppErrors carry a technical cause for one structured log;
+			// known domain errors (validation, not-found, etc.) stay quiet.
+			if cause := appErr.Unwrap(); cause != nil {
+				slog.Error("request failed", "error", cause, "request_id", c.GetString(RequestIDKey))
+				if exposeDetail {
+					appErr.Details = cause.Error()
+				}
+			}
+			if !exposeDetail {
+				// Known AppError (e.g. VALIDATION_ERROR): still strip Details in
+				// prod, so a direct API call doesn't get field-level hints.
+				appErr.Details = nil
+			}
 		}
 
 		appErr.RequestID = c.GetString(RequestIDKey)

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

@@ -6,10 +6,12 @@
 do lives in `cmd/api/wiring.go`, in a `run() error` — the one function that sees
 every module and hands them what they need.
 
-Modules never import one another. A domain that needs another's behaviour
-declares a narrow interface for exactly what it needs and receives the concrete
-service from `run()`; `.golangci.yml` has a depguard rule per domain that fails
-the build if anyone shortcuts that.
+Modules never import one another. Each generated domain owns its local
+repository → service → handler composition in `composition.go`; `wiring.go`
+supplies the DB and any cross-feature security dependencies. A domain that
+needs another's behaviour declares a narrow interface for exactly what it
+needs and receives the concrete service from `run()`; `.golangci.yml` has a
+depguard rule per domain that fails the build if anyone shortcuts that.
 
 Two things the split buys. `run()` returns an error instead of calling
 `os.Exit`, so the deferred cleanup below it actually runs — `os.Exit` skips
@@ -63,7 +65,27 @@ no per-domain versioning; a domain that needs a real breaking change gets a
 new domain package (or a new field on the existing DTO), not a duplicated
 model pointed at the same table under a different URL.
 
-## 4. Response and Error Model
+## 4. Application boundaries
+
+**Decision:** New modules use the project defaults recorded in
+`go-scaffold.config.json`: surface `{{defaultModuleSurface}}` and application
+style `{{defaultApplicationStyle}}`. The `generate module` wizard presents
+those values through Lean/CRUD/CQRS profiles, with Advanced for an explicit
+custom combination. `--profile` or the supported axis flags can override the
+defaults for one module.
+**Rationale:** A feature with meaningful write invariants or a different read
+shape benefits from separate `CommandHandler` and `QueryHandler` ports while
+remaining inside this modular monolith. A small CRUD feature does not benefit
+from empty command/query wrappers, so it keeps one service until its business
+needs justify the split. CQRS here does not require a second database, broker,
+or event-sourcing runtime.
+
+When enabled, `commands.go` owns state-changing application use cases,
+`queries.go` owns read use cases, and `composition.go` constructs both. The
+HTTP handler is still an inbound adapter and `cmd/api/wiring.go` still only
+selects infrastructure and registers the feature.
+
+## 5. Response and Error Model
 
 **Decision:** Central `apperror.AppError` (HTTP status + machine-readable
 `code` + message), rendered once by `middleware.Error()`.
@@ -75,24 +97,24 @@ 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
 
-## 5. Pagination
+## 6. Pagination
 
 **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.
 
-## 6. Persistence
+## 7. Persistence
 
 **Decision:** PostgreSQL + GORM, schema managed by
 [golang-migrate](https://github.com/golang-migrate/migrate).
-**Rationale:** `AUTO_MIGRATE=true` runs GORM's AutoMigrate in dev for speed;
-prod runs `migrate up` as a separate, versioned, rollback-capable step —
-AutoMigrate is add-only and locks tables once there's real data.
+**Rationale:** `APP_ENV=development` allows a convenience table bootstrap;
+`APP_ENV=production` runs only after `migrate up` has applied the separate,
+versioned, rollback-capable SQL migrations.
 
 {{#if docker}}- `docker-compose.yml` provides the local Postgres instance
 {{/if}}
-## 7. IDs
+## 8. IDs
 
 **Decision:** UUID v7 for every entity, generated app-side
 (`shared/id.New()`), not by a DB default.
@@ -101,18 +123,18 @@ splits versus random v4 under heavy writes — and the app has the ID before
 insert, so it doesn't need `gen_random_uuid()`.
 
 {{#if openapiDocs}}
-## 8. API Documentation
+## 9. API Documentation
 
 **Decision:** Hand-written OpenAPI spec (`docs/openapi.yaml`), split by
-domain module, served under `/docs` (so relative `$ref`s to sibling files
-resolve over HTTP too — the index alone isn't enough for a renderer like
-Scalar/Swagger UI/Redoc to follow them).
+domain module, read from the working copy only — the server serves no `/docs`
+route in any environment. Renderers that follow relative `$ref`s get a
+fully-resolved single file from `make openapi-bundle`.
 **Rationale:** Cheap while the endpoint count is low; switch to
 comment-generated (swaggo) if hand-updates start drifting.
 {{/if}}
 
 {{#if observability}}
-## 9. Observability
+## 10. Observability
 
 **Decision:** Prometheus metrics (`GET /metrics`, request count + latency
 per route) always-on when this feature is enabled; OpenTelemetry tracing

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

@@ -16,6 +16,9 @@ internal/app/<domain>/
 ├── 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)
+├── commands.go         # optional: command port + state-changing application handlers (`--cqrs`)
+├── queries.go          # optional: query port + read-only application handlers (`--cqrs`)
+├── composition.go      # feature-local repository → service → handler wiring
 ├── 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
@@ -35,8 +38,8 @@ internal/app/<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
+  the development table bootstrap runs (the bootstrap 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.
@@ -50,6 +53,23 @@ internal/app/<domain>/
   `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 `Service` remains a compatibility facade for tests and existing
+callers. New feature code should depend on the narrower command/query 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 —
@@ -121,8 +141,8 @@ 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.
+   (`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** 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
@@ -148,24 +168,22 @@ type userLookup interface {
 }
 ```
 
-`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/service/handler composition in
+`composition.go`; `cmd/api/wiring.go` supplies the DB and any cross-feature
+security dependencies. 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 service. Its local composition accepts that
+port, while the root supplies an adapter; the root never reaches into the
+callee's repository or handler. A func-to-interface shim is one small option:
 
 ```go
 // order/service.go
@@ -198,12 +216,13 @@ 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`
+Patches `handler.go`/`service.go` (and `commands.go` or `queries.go` for a
+module generated with `--cqrs`; plus `repository.go` + the relevant repository
+port + 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
+that compiles and returns a clean `500` (`apperror.NewInternal(cause)`) rather
 than guessing at business logic — same spirit as `generate module`'s
 placeholder fields.
 

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

@@ -22,7 +22,7 @@
 - PostgreSQL + GORM baseline: always enabled
 - Graceful shutdown, structured logging, `/livez` + `/readyz`: always enabled
 - Docker Compose (local Postgres): `{{#if docker}}enabled{{else}}disabled{{/if}}`
-- OpenAPI docs (`docs/openapi.yaml`, whole `docs/` tree served at `/docs`): `{{#if openapiDocs}}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}}`
 - 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 +31,8 @@
 
 {{#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}}- `APP_ENV=development` enables the convenience table bootstrap;
+  `APP_ENV=production` requires `migrate up` as a deploy step instead
 {{#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

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

@@ -0,0 +1,95 @@
+package {{pkg}}
+
+import (
+	"context"
+	"errors"
+
+	"{{goModule}}/internal/app/{{modulePath}}/model"
+	"{{goModule}}/internal/shared/apperror"
+	"{{goModule}}/internal/shared/dberr"
+	"{{goModule}}/internal/shared/id"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+// commandRepository is the outbound port for state-changing use cases. It is
+// intentionally smaller than queryRepository so command handlers do not grow
+// a dependency on read-only operations by accident.
+type commandRepository interface {
+	Create(ctx context.Context, m *model.{{pascalName}}) error
+	FindByID(ctx context.Context, id uuid.UUID) (*model.{{pascalName}}, error)
+	Update(ctx context.Context, m *model.{{pascalName}}) error
+	Delete(ctx context.Context, id uuid.UUID) error
+	// go-scaffold:command-repository-interface
+}
+
+// commandService is the inbound application port consumed by the HTTP
+// adapter. Its implementation is free of Gin and is independently testable.
+type commandService interface {
+	Create(context.Context, createInput) (*model.{{pascalName}}, error)
+	Update(context.Context, uuid.UUID, updateInput) (*model.{{pascalName}}, error)
+	Delete(context.Context, uuid.UUID) error
+	// go-scaffold:command-interface
+}
+
+// CommandHandler owns state-changing use cases for {{pkg}}. It is deliberately
+// separate from QueryHandler even though both adapters may share one database.
+type CommandHandler struct {
+	repo commandRepository
+}
+
+func NewCommandHandler(repo commandRepository) *CommandHandler {
+	return &CommandHandler{repo: repo}
+}
+
+func (h *CommandHandler) Create(ctx context.Context, in createInput) (*model.{{pascalName}}, error) {
+	// TODO: set real fields from in
+	_ = in
+	m := &model.{{pascalName}}{ID: id.New()}
+	if err := h.repo.Create(ctx, m); err != nil {
+		if dberr.IsDuplicate(err) {
+			return nil, errConflict()
+		}
+		return nil, apperror.NewInternal(err)
+	}
+	return m, nil
+}
+
+func (h *CommandHandler) Update(ctx context.Context, id uuid.UUID, in updateInput) (*model.{{pascalName}}, error) {
+	m, err := h.repo.FindByID(ctx, id)
+	if err != nil {
+		return nil, wrapFindErr(err)
+	}
+	// TODO: apply real fields from in before saving
+	// The version the client read comes from the request, not from the row we
+	// just loaded — comparing the row against itself would always succeed and
+	// defeat the check.
+	m.Version = in.Version
+	if err := h.repo.Update(ctx, m); err != nil {
+		if errors.Is(err, ErrStaleVersion) {
+			return nil, errStale()
+		}
+		if dberr.IsDuplicate(err) {
+			return nil, errConflict()
+		}
+		return nil, apperror.NewInternal(err)
+	}
+	return m, nil
+}
+
+func (h *CommandHandler) Delete(ctx context.Context, id uuid.UUID) error {
+	if err := h.repo.Delete(ctx, id); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return errNotFound()
+		}
+		// deleting a {{pkg}} that's still referenced elsewhere → FK RESTRICT trips = 409, not 500
+		if dberr.IsForeignKey(err) {
+			return errHasReferences()
+		}
+		return apperror.NewInternal(err)
+	}
+	return nil
+}
+
+// go-scaffold:command-methods

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

@@ -0,0 +1,23 @@
+package {{pkg}}
+
+import "gorm.io/gorm"
+{{#if permission}}
+import "{{goModule}}/internal/shared/middleware"
+{{/if}}
+
+// NewHandlerFromDB is this feature's local composition root. The API binary
+// only chooses infrastructure and registers the route; repository, application
+// handlers, and delivery construction stay next to the feature.
+func NewHandlerFromDB(db *gorm.DB{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
+	{{#if cqrs}}
+	repo := NewRepository(db)
+	return NewHandlerFromCQRS(
+		NewCommandHandler(repo),
+		NewQueryHandler(repo){{#if auth}}, jwtSecret{{/if}}{{#if permission}}, authz{{/if}},
+	)
+	{{else}}
+	return NewHandler(
+		NewService(NewRepository(db)){{#if auth}}, jwtSecret{{/if}}{{#if permission}}, authz{{/if}},
+	)
+	{{/if}}
+}

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

@@ -0,0 +1,7 @@
+package {{pkg}}
+
+// These compile-time assertions make the generated boundary visible to both
+// users and tooling: commands and queries are separate application ports even
+// when they share one Postgres adapter in this modular monolith.
+var _ commandService = (*CommandHandler)(nil)
+var _ queryService = (*QueryHandler)(nil)

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

@@ -15,6 +15,21 @@ import (
 	"github.com/google/uuid"
 )
 
+{{#if cqrs}}
+// service is retained as a compatibility seam for handler tests and callers
+// that still want one feature facade. Production wiring uses the narrower
+// commandService/queryService ports through NewHandlerFromCQRS.
+type service interface {
+	commandService
+	queryService
+	Create(context.Context, createInput) (*model.{{pascalName}}, error)
+	List(context.Context, int, int) ([]model.{{pascalName}}, error)
+	Get(context.Context, uuid.UUID) (*model.{{pascalName}}, error)
+	Update(context.Context, uuid.UUID, updateInput) (*model.{{pascalName}}, error)
+	Delete(context.Context, uuid.UUID) error
+	// go-scaffold:service-interface
+}
+{{else}}
 // service is the narrow application API required by this HTTP adapter. Keeping
 // the dependency as an interface makes handler tests fast and database-free.
 type service interface {
@@ -25,10 +40,16 @@ type service interface {
 	Delete(context.Context, uuid.UUID) error
 	// go-scaffold:service-interface
 }
+{{/if}}
 
 // Handler = delivery for {{pkg}} (parses HTTP, calls the service, attaches errors for the middleware to render)
 type Handler struct {
+	{{#if cqrs}}
+	commands commandService
+	queries  queryService
+	{{else}}
 	svc service
+	{{/if}}
 {{#if auth}}
 	jwtSecret string
 {{/if}}
@@ -37,6 +58,27 @@ type Handler struct {
 {{/if}}
 }
 
+{{#if cqrs}}
+// NewHandler keeps the pre-CQRS constructor usable for focused handler tests
+// and hand-written callers. New production composition should use the explicit
+// command/query constructor below.
+func NewHandler(svc service{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
+	return NewHandlerFromCQRS(svc, svc{{#if auth}}, jwtSecret{{/if}}{{#if permission}}, authz{{/if}})
+}
+
+func NewHandlerFromCQRS(commands commandService, queries queryService{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
+	return &Handler{
+		commands: commands,
+		queries: queries,
+{{#if auth}}
+		jwtSecret: jwtSecret,
+{{/if}}
+{{#if permission}}
+		 authz: authz,
+{{/if}}
+	}
+}
+{{else}}
 func NewHandler(svc service{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
 	return &Handler{
 		svc: svc,
@@ -48,6 +90,7 @@ func NewHandler(svc service{{#if auth}}, jwtSecret string{{/if}}{{#if permission
 {{/if}}
 	}
 }
+{{/if}}
 
 // Register wires {{pkg}}'s routes onto the router group (takes an IRouter so it can be nested under /v1)
 func (h *Handler) Register(rg gin.IRouter) {
@@ -66,7 +109,7 @@ func (h *Handler) create(c *gin.Context) {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	m, err := h.svc.Create(c.Request.Context(), in)
+	{{#if cqrs}}m, err := h.commands.Create(c.Request.Context(), in){{else}}m, err := h.svc.Create(c.Request.Context(), in){{/if}}
 	if err != nil {
 		c.Error(err)
 		return
@@ -76,7 +119,7 @@ func (h *Handler) create(c *gin.Context) {
 
 func (h *Handler) list(c *gin.Context) {
 	p := pagination.Parse(c)
-	items, err := h.svc.List(c.Request.Context(), p.Limit, p.Offset)
+	{{#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(err)
 		return
@@ -93,7 +136,7 @@ func (h *Handler) get(c *gin.Context) {
 	if !ok {
 		return
 	}
-	m, err := h.svc.Get(c.Request.Context(), id)
+	{{#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(err)
 		return
@@ -111,7 +154,7 @@ func (h *Handler) update(c *gin.Context) {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	m, err := h.svc.Update(c.Request.Context(), id, in)
+	{{#if cqrs}}m, err := h.commands.Update(c.Request.Context(), id, in){{else}}m, err := h.svc.Update(c.Request.Context(), id, in){{/if}}
 	if err != nil {
 		c.Error(err)
 		return
@@ -124,7 +167,9 @@ func (h *Handler) delete(c *gin.Context) {
 	if !ok {
 		return
 	}
-	if err := h.svc.Delete(c.Request.Context(), id); err != nil {
+{{#if cqrs}}	if err := h.commands.Delete(c.Request.Context(), id); err != nil {
+{{else}}	if err := h.svc.Delete(c.Request.Context(), id); err != nil {
+{{/if}}
 		c.Error(err)
 		return
 	}

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

@@ -0,0 +1,34 @@
+package {{pkg}}
+
+import (
+	"context"
+
+	"{{goModule}}/internal/app/{{modulePath}}/model"
+
+	"github.com/google/uuid"
+)
+
+// commandRepository is the outbound port for state-changing use cases.
+type commandRepository interface {
+	Create(ctx context.Context, m *model.{{pascalName}}) error
+	FindByID(ctx context.Context, id uuid.UUID) (*model.{{pascalName}}, error)
+	Update(ctx context.Context, m *model.{{pascalName}}) error
+	Delete(ctx context.Context, id uuid.UUID) error
+	// go-scaffold:command-repository-interface
+}
+
+// commandService is the inbound application port consumed by command routes.
+type commandService interface {
+	// go-scaffold:command-interface
+}
+
+// CommandHandler owns state-changing use cases for {{pkg}}.
+type CommandHandler struct {
+	repo commandRepository
+}
+
+func NewCommandHandler(repo commandRepository) *CommandHandler {
+	return &CommandHandler{repo: repo}
+}
+
+// go-scaffold:command-methods