@nakedev/go-scaffold 0.4.0 → 0.5.0

package/templates/create/base/cmd/api/wiring.go.hbs

@@ -22,7 +22,8 @@ import (
 // run is this binary's composition root — the only function that sees every
 // module and wires them to each other. Modules never import one another; a
 // domain that needs another's behaviour declares a narrow interface and gets
-// the concrete service from here (see docs/architect/patterns.md).
+// its concrete implementation from the process composition package (see
+// docs/architect/patterns.md).
 //
 // It returns an error rather than calling os.Exit, so every defer below runs
 // on the way out and main() holds the only exit in the binary.
@@ -46,17 +47,20 @@ func run() error {
 	if err != nil {
 		return fmt.Errorf("db handle: %w", err)
 	}
+	defer func() {
+		if err := sqlDB.Close(); err != nil {
+			logger.Error("close db", "error", err)
+		}
+	}()
 	// go-scaffold:platform-init
 
-	// AutoMigrate creates tables but never the schema they live in — each
-	// domain gets its own (see model.go's TableName), so it has to exist
-	// before AutoMigrate runs. The versioned SQL migrations create the same
-	// schemas with CREATE SCHEMA IF NOT EXISTS, so this only matters for dev.
-	// go-scaffold:schemas
+	if !cfg.IsProd() {
+		// Development boot creates tables but never the schema they live in — each
+		// domain gets its own (see the outbound postgres model's TableName), so it has to exist
+		// before the bootstrap runs. Production runs the versioned SQL migrations
+		// instead, so this entire branch is skipped there.
+		// go-scaffold:schemas
 
-	if cfg.AutoMigrate {
-		// ponytail: AutoMigrate is for dev only (add-only, locks the table once data grows)
-		// prod: set AUTO_MIGRATE=false and run golang-migrate as versioned SQL instead
 		if err := db.AutoMigrate(
 			// go-scaffold:models
 		); err != nil {

package/templates/create/base/internal/composition/doc.go.hbs

@@ -0,0 +1,7 @@
+// Package composition contains process-level wiring and cross-feature adapters.
+//
+// Feature-local construction belongs in internal/app/<feature>/composition.go.
+// Keep this package focused on translating caller-owned ports to another
+// feature's public application capabilities. Do not put business rules,
+// persistence adapters, or HTTP handlers here.
+package composition

package/templates/create/base/internal/platform/database/database.go.hbs

@@ -20,7 +20,8 @@ import (
 
 // Open connects to Postgres and sets the connection pool — it talks to a
 // real external system, so it lives in platform/, not shared/.
-// Schema is managed via golang-migrate (migrations/) in prod, not AutoMigrate — see README.
+// Production schema is managed via golang-migrate (migrations/); development
+// may use the convenience path selected by APP_ENV in the composition root.
 func Open(cfg config.Config) (*gorm.DB, error) {
 	// GORM's default logger reports ErrRecordNotFound at ERROR level, so an
 	// ordinary miss — every FindByID behind a 404, cmd/seed's "does this admin
@@ -58,8 +59,7 @@ var migrationVersionRe = regexp.MustCompile(`^(\d+)_.*\.up\.sql$`)
 // golang-migrate CLI's own schema_migrations table) doesn't match the newest
 // migration file baked into this binary — instead of booting against a stale
 // or half-applied schema and failing later on whatever query hits the
-// missing column first. Only meaningful when AutoMigrate is off (prod); call
-// this from that branch only.
+// missing column first. Call this from the production branch only.
 func CheckMigrationVersion(db *gorm.DB) error {
 	entries, err := migrations.FS.ReadDir(".")
 	if err != nil {

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

@@ -10,10 +10,15 @@ type AppError struct {
 	Message    string `json:"message"`
 	Details    any    `json:"details,omitempty"`
 	RequestID  string `json:"request_id,omitempty"` // filled in by the error middleware
+	cause      error
 }
 
 func (e *AppError) Error() string { return e.Message }
 
+// Unwrap keeps the technical cause available to structured logging and
+// errors.Is/As without putting it in the JSON response.
+func (e *AppError) Unwrap() error { return e.cause }
+
 func New(status int, code, msg string) *AppError {
 	return &AppError{HTTPStatus: status, Code: code, Message: msg}
 }
@@ -30,7 +35,15 @@ func NewConflict(msg string) *AppError {
 	return &AppError{HTTPStatus: http.StatusConflict, Code: "CONFLICT", Message: msg}
 }
 
-func NewInternal() *AppError {
+func NewInternal(cause ...error) *AppError {
 	// ponytail: never leak internal details to the client, log separately in middleware
-	return &AppError{HTTPStatus: http.StatusInternalServerError, Code: "INTERNAL", Message: "internal server error"}
+	err := &AppError{HTTPStatus: http.StatusInternalServerError, Code: "INTERNAL", Message: "internal server error"}
+	if len(cause) > 0 {
+		err.cause = cause[0]
+	}
+	return err
+}
+
+func NewNotImplemented() *AppError {
+	return &AppError{HTTPStatus: http.StatusNotImplemented, Code: "NOT_IMPLEMENTED", Message: "not implemented"}
 }

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

@@ -2,14 +2,18 @@
 
 ## Composition root
 
-`cmd/api/main.go` decides the exit code and nothing else. Everything it used to
-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.
+`cmd/api/main.go` decides the exit code and nothing else. `cmd/api/wiring.go`
+owns process bootstrap and route registration; `internal/composition/` owns
+reusable process-level adapters that connect feature ports.
+
+Modules never import one another. Each generated domain owns its local
+outbound adapter → service or command/query application handlers → inbound
+adapter composition in `composition.go`; `internal/composition/` owns
+cross-feature adapters and `wiring.go` supplies infrastructure, invokes those
+adapters, and registers routes. A domain that needs another's behaviour
+declares a narrow interface for exactly what it needs and receives its
+concrete implementation from the process composition; `.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
@@ -19,32 +23,49 @@ you open to understand the binary: `wiring.go` grows with the system, which is
 what a composition root is for, while `main.go` stays put.
 
 
-> Status: generated by `@nakedev/go-scaffold`
-> Scope: initial scaffold
+> Status: generated by `@nakedev/go-scaffold`; refreshes as optional features are added
+> Scope: current generated project configuration
 
 ## 1. Topology
 
-**Decision:** Single Go binary (`cmd/api`), REST over Gin.
-**Rationale:** One process serves all domains; a second entry point
-(`cmd/worker`, `cmd/migrate`) gets its own `main.go` only once there's a real
-second process — `main.go` has no importers, so adding one later touches no
-other file.
+**Decision:** `cmd/api` serves REST over Gin. Optional operational binaries
+are separate entry points: `cmd/worker` for queued jobs and `cmd/seed` for
+one-shot bootstrap tasks when those features are installed.
+**Rationale:** The HTTP process stays independently deployable while worker and
+seed lifecycles remain explicit. Adding either binary does not turn an API
+handler or feature composition root into a process-wide god object.
 
 ## 2. Package Layout
 
 ```text
 cmd/
-└── api/main.go             # config, slog, graceful shutdown, wires domains
+└── api/
+    ├── main.go             # process entrypoint and exit code
+    └── wiring.go           # config, infrastructure, graceful shutdown, routes
 internal/
-├── platform/                # talks to real external systems (DB, later: cache, queue, mail, ...)
-│   └── database/
+├── composition/             # process-level cross-feature adapters
+├── platform/                # talks to real external systems
+│   └── database/             # PostgreSQL connection and pool
 ├── shared/                  # pure logic/framework glue, no I/O
 │   ├── config/  apperror/  dberr/  httpx/  id/
 │   └── middleware/  pagination/  tx/
 └── app/                     # domain packages (one per feature)
     └── <domain>/
+        ├── domain/          # business entities and errors
+        ├── ports/           # consumer-owned application dependencies
+        ├── application/     # service OR commands + queries
+        ├── adapters/inbound/http/ # request/response DTOs + HTTP adapter
+        ├── adapters/outbound/postgres/
+        └── composition.go   # feature-local object graph
 ```
 
+Installed process and platform additions:
+{{#if auth}}- `cmd/seed` and `platform/authprovider/google/` for user bootstrap and Google OAuth/OIDC
+{{/if}}{{#if worker}}- `cmd/worker` and `platform/{mail,queue}/` for queue/SMTP jobs{{#if (eq queue "asynq")}}, plus `platform/cache/` for Redis{{/if}}
+{{/if}}{{#if observability}}- `platform/telemetry/` for the OTLP exporter
+{{/if}}{{#if rbac}}- `shared/middleware/authz.go` and `app/role/` for RBAC policy
+{{/if}}
+
 **Decision:** `platform/` vs `shared/` is split by whether the code talks to
 a real external system.
 **Rationale:** Code that does I/O against Postgres/cache/queue/SMTP/S3 →
@@ -52,47 +73,80 @@ a real external system.
 add a `shared/utils` or similarly generic package — name it after what it
 actually does.
 
+Optional feature boundaries are explicit: auth owns user authentication and
+provider ports; RBAC owns role policy and authorization; worker owns queue and
+mail adapters; observability owns metrics/tracing setup. They do not create a
+second domain architecture.
+
 ## 3. API Style
 
 **Decision:** REST over Gin, one handler package per domain, every route
 grouped under{{#if apiPrefix}} `/{{apiPrefix}}`{{else}} no prefix{{/if}}.
-**Rationale:** `handler → service → repository`, one direction, all three
-layers in the same package — no cross-domain imports. The prefix is a
+**Rationale:** `inbound HTTP adapter → application boundary → domain + ports →
+outbound adapter`, one direction,
+with delivery, application, and persistence concerns kept inside the feature
+boundary — no cross-domain imports. The prefix is a
 single project-wide choice made at `create` time (`--api-prefix`) — there is
 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, `application/commands.go` owns state-changing application use
+cases, `application/queries.go` owns read use cases, and `composition.go`
+constructs both. The HTTP adapter is still an inbound adapter and
+`cmd/api/wiring.go` still selects infrastructure, invokes process-level
+adapters from `internal/composition/`, and registers the feature. A service
+module instead has one `application/service.go`; these
+styles are exclusive inside a module but can coexist across the monolith.
+
+The CQRS inbound adapter is wired through `NewHandler` with separate command
+and query ports. It does not generate an `application/service.go` facade.
+
+## 5. Response and Error Model
 
 **Decision:** Central `apperror.AppError` (HTTP status + machine-readable
 `code` + message), rendered once by `middleware.Error()`.
 **Rationale:** Handlers only ever do `c.Error(err); return` — no `c.JSON` per
 call site, no error-shape drift between domains.
 
-- Domain-specific errors live in each package's `errors.go` (e.g.
+- Domain-specific errors live in each module's `domain/errors.go` (e.g.
   `USER_NOT_FOUND`, not a bare `NOT_FOUND`)
 - 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,7 +155,7 @@ 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, read from the working copy only — the server serves no `/docs`
@@ -112,7 +166,7 @@ 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
@@ -147,5 +201,11 @@ skipped by the `os.Exit` calls already in there.
 
 - `go-scaffold generate module <name>` adds a new domain package and
   wires it into `cmd/api/wiring.go`
-- This document only reflects the initial scaffold — update it as the real
-  architecture evolves
+- `go-scaffold check` validates the physical split, process-composition
+  boundary, layer dependencies, and exclusive service/CQRS choice for every
+  discovered module
+- `go-scaffold add auth`, `add worker`, `add rbac`, and `add observability`
+  refresh this document while it still matches the generated version. A
+  hand-edited document is preserved and must be updated by its owner.
+- This document describes package boundaries, not completed business behavior;
+  generated methods remain explicit TODO/501 stubs until implemented.