@nakedev/go-scaffold 0.1.0

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

@@ -0,0 +1,36 @@
+package apperror
+
+import "net/http"
+
+// AppError is an error that knows both its HTTP status and its payload.
+// Lower layers (service/repo) can return one without importing net/http themselves.
+type AppError struct {
+	HTTPStatus int    `json:"-"`
+	Code       string `json:"code"`
+	Message    string `json:"message"`
+	Details    any    `json:"details,omitempty"`
+	RequestID  string `json:"request_id,omitempty"` // filled in by the error middleware
+}
+
+func (e *AppError) Error() string { return e.Message }
+
+func New(status int, code, msg string) *AppError {
+	return &AppError{HTTPStatus: status, Code: code, Message: msg}
+}
+
+func NewValidation(msg string, details any) *AppError {
+	return &AppError{HTTPStatus: http.StatusBadRequest, Code: "VALIDATION_ERROR", Message: msg, Details: details}
+}
+
+func NewNotFound(msg string) *AppError {
+	return &AppError{HTTPStatus: http.StatusNotFound, Code: "NOT_FOUND", Message: msg}
+}
+
+func NewConflict(msg string) *AppError {
+	return &AppError{HTTPStatus: http.StatusConflict, Code: "CONFLICT", Message: msg}
+}
+
+func NewInternal() *AppError {
+	// ponytail: never leak internal details to the client, log separately in middleware
+	return &AppError{HTTPStatus: http.StatusInternalServerError, Code: "INTERNAL", Message: "internal server error"}
+}

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

@@ -0,0 +1,46 @@
+package config
+
+import (
+	"os"
+	"strconv"
+	"time"
+)
+
+// Config loads from env (with dev-friendly defaults).
+type Config struct {
+	Port              string
+	DBDSN             string
+	LogLevel          string
+	AutoMigrate       bool
+	DBMaxOpenConns    int
+	DBMaxIdleConns    int
+	DBConnMaxLifetime time.Duration
+}
+
+func Load() Config {
+	return Config{
+		Port:              env("PORT", "8080"),
+		DBDSN:             env("DB_DSN", "postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable"),
+		LogLevel:          env("LOG_LEVEL", "info"),
+		AutoMigrate:       env("AUTO_MIGRATE", "true") == "true",
+		DBMaxOpenConns:    envInt("DB_MAX_OPEN_CONNS", 10),
+		DBMaxIdleConns:    envInt("DB_MAX_IDLE_CONNS", 10),
+		DBConnMaxLifetime: time.Duration(envInt("DB_CONN_MAX_LIFETIME_MIN", 5)) * time.Minute,
+	}
+}
+
+func env(k, def string) string {
+	if v := os.Getenv(k); v != "" {
+		return v
+	}
+	return def
+}
+
+func envInt(k string, def int) int {
+	if v := os.Getenv(k); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			return n
+		}
+	}
+	return def
+}

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

@@ -0,0 +1,28 @@
+// Package dberr translates driver/GORM errors into "which constraint kind
+// broke" — glue with no I/O, so it lives in shared/, not platform/.
+// Centralized so every domain maps DB errors to HTTP status the same way,
+// instead of copy-pasting the logic per module.
+package dberr
+
+import (
+	"errors"
+	"strings"
+
+	"gorm.io/gorm"
+)
+
+// IsDuplicate reports a unique constraint violation — gorm.ErrDuplicatedKey
+// (requires TranslateError:true), with a string fallback in case the driver
+// doesn't translate: postgres "duplicate key value violates unique constraint".
+func IsDuplicate(err error) bool {
+	return errors.Is(err, gorm.ErrDuplicatedKey) ||
+		strings.Contains(strings.ToLower(err.Error()), "unique constraint")
+}
+
+// IsForeignKey reports a foreign key violation (referencing a missing parent,
+// or deleting a parent that's still referenced).
+// gorm.ErrForeignKeyViolated + string fallback: postgres "...foreign key constraint...".
+func IsForeignKey(err error) bool {
+	return errors.Is(err, gorm.ErrForeignKeyViolated) ||
+		strings.Contains(strings.ToLower(err.Error()), "foreign key")
+}

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

@@ -0,0 +1,37 @@
+package httpx
+
+import (
+	"errors"
+	"strings"
+
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/gin-gonic/gin"
+	"github.com/go-playground/validator/v10"
+	"github.com/google/uuid"
+)
+
+// ParseID reads the ":id" route param as a UUID — shared by every domain
+// whose resource is identified by id.
+func ParseID(c *gin.Context) (uuid.UUID, bool) {
+	id, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		c.Error(apperror.NewValidation("invalid id", nil))
+		return uuid.Nil, false
+	}
+	return id, true
+}
+
+// BindErr converts a validator error into a validation payload with a field
+// map (shared by every domain).
+func BindErr(err error) *apperror.AppError {
+	var ve validator.ValidationErrors
+	if errors.As(err, &ve) {
+		details := make(map[string]string, len(ve))
+		for _, fe := range ve {
+			details[strings.ToLower(fe.Field())] = fe.Tag()
+		}
+		return apperror.NewValidation("invalid input", details)
+	}
+	return apperror.NewValidation("invalid json body", nil)
+}

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

@@ -0,0 +1,16 @@
+// Package id creates entity identifiers — "the whole system uses UUID v7" is
+// decided in one place, so changing the scheme is a one-file change.
+package id
+
+import "github.com/google/uuid"
+
+// New returns a UUID v7 (time-ordered, so rows sort by creation time and the
+// B-tree takes fewer page splits than v4 random IDs under heavy writes).
+// Falls back to v4 if entropy fails (practically impossible — reads
+// crypto/rand), so the entity-creation path never has to handle the error.
+func New() uuid.UUID {
+	if v7, err := uuid.NewV7(); err == nil {
+		return v7
+	}
+	return uuid.New()
+}

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

@@ -0,0 +1,33 @@
+package middleware
+
+import (
+	"errors"
+	"log/slog"
+
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Error reads the last error attached via c.Error() and renders it once, so
+// handlers only ever do c.Error(err); return — no c.JSON per call site.
+func Error() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Next()
+
+		err := c.Errors.Last()
+		if err == nil {
+			return
+		}
+
+		var appErr *apperror.AppError
+		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.RequestID = c.GetString(RequestIDKey)
+		c.JSON(appErr.HTTPStatus, gin.H{"error": appErr})
+	}
+}

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

@@ -0,0 +1,23 @@
+package middleware
+
+import (
+	"log/slog"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Logger logs each request as structured JSON instead of gin's default text logger.
+func Logger(log *slog.Logger) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		start := time.Now()
+		c.Next()
+		log.Info("request",
+			"method", c.Request.Method,
+			"path", c.Request.URL.Path,
+			"status", c.Writer.Status(),
+			"duration_ms", time.Since(start).Milliseconds(),
+			"request_id", c.GetString(RequestIDKey),
+		)
+	}
+}

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

@@ -0,0 +1,36 @@
+package middleware
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+
+	"github.com/gin-gonic/gin"
+)
+
+const (
+	RequestIDKey    = "request_id"
+	requestIDHeader = "X-Request-ID"
+)
+
+// RequestID reads X-Request-ID from the client, generating one if absent,
+// stores it in context, and echoes it back in the response header — used to
+// correlate logs/errors across services.
+func RequestID() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		id := c.GetHeader(requestIDHeader)
+		if id == "" {
+			id = newID()
+		}
+		c.Set(RequestIDKey, id)
+		c.Header(requestIDHeader, id)
+		c.Next()
+	}
+}
+
+func newID() string {
+	b := make([]byte, 8)
+	if _, err := rand.Read(b); err != nil {
+		return "unknown"
+	}
+	return hex.EncodeToString(b)
+}

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

@@ -0,0 +1,39 @@
+package pagination
+
+import (
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+)
+
+const (
+	defaultLimit = 20
+	maxLimit     = 100
+)
+
+// Params is a validated limit/offset pair (default 20, capped at 100).
+type Params struct {
+	Limit  int
+	Offset int
+}
+
+// Parse reads ?limit=&offset= off the request so every feature parses the
+// same way.
+func Parse(c *gin.Context) Params {
+	p := Params{Limit: defaultLimit}
+	if v, err := strconv.Atoi(c.Query("limit")); err == nil && v > 0 {
+		p.Limit = v
+	}
+	if p.Limit > maxLimit {
+		p.Limit = maxLimit
+	}
+	if v, err := strconv.Atoi(c.Query("offset")); err == nil && v >= 0 {
+		p.Offset = v
+	}
+	return p
+}
+
+// Response wraps a list so every feature responds with the same shape.
+func (p Params) Response(data any) gin.H {
+	return gin.H{"data": data, "limit": p.Limit, "offset": p.Offset}
+}

package/templates/create/features/docker-compose.yml.hbs

@@ -0,0 +1,14 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: {{dbName}}
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+volumes:
+  pgdata:

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

@@ -0,0 +1,99 @@
+# Architecture Decision Record: {{projectName}}
+
+> Status: generated by `@nakedev/go-scaffold`
+> Scope: initial scaffold
+
+## 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.
+
+## 2. Package Layout
+
+```text
+cmd/
+└── api/main.go             # config, slog, graceful shutdown, wires domains
+internal/
+├── platform/                # talks to real external systems (DB, later: cache, queue, mail, ...)
+│   └── database/
+├── shared/                  # pure logic/framework glue, no I/O
+│   ├── config/  apperror/  dberr/  httpx/  middleware/  pagination/
+└── app/                     # domain packages (one per feature)
+    └── <domain>/
+```
+
+**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 →
+`platform/`. Pure logic or HTTP-framework glue with no I/O → `shared/`. Never
+add a `shared/utils` or similarly generic package — name it after what it
+actually does.
+
+## 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
+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
+
+**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.
+  `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
+
+**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
+
+**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.
+
+{{#if docker}}- `docker-compose.yml` provides the local Postgres instance
+{{/if}}
+## 7. IDs
+
+**Decision:** UUID v7 for every entity, generated app-side
+(`shared/id.New()`), not by a DB default.
+**Rationale:** Time-ordered IDs sort by creation time, reducing B-tree page
+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
+
+**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).
+**Rationale:** Cheap while the endpoint count is low; switch to
+comment-generated (swaggo) if hand-updates start drifting.
+{{/if}}
+
+## Evolution Notes
+
+- `go-scaffold generate module <name>` adds a new domain package and
+  wires it into `cmd/api/main.go`
+- This document only reflects the initial scaffold — update it as the real
+  architecture evolves

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

@@ -0,0 +1,13 @@
+IdParam:
+  name: id
+  in: path
+  required: true
+  schema: { type: string, format: uuid }
+Limit:
+  name: limit
+  in: query
+  schema: { type: integer, default: 20, maximum: 100 }
+Offset:
+  name: offset
+  in: query
+  schema: { type: integer, default: 0, minimum: 0 }

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

@@ -0,0 +1,20 @@
+ValidationError:
+  description: invalid input
+  content:
+    application/json:
+      schema: { $ref: './schemas.yaml#/Error' }
+NotFoundError:
+  description: not found
+  content:
+    application/json:
+      schema: { $ref: './schemas.yaml#/Error' }
+ConflictError:
+  description: conflict (duplicate, or resource still referenced)
+  content:
+    application/json:
+      schema: { $ref: './schemas.yaml#/Error' }
+UnprocessableEntityError:
+  description: input well-formed but references a resource that doesn't exist
+  content:
+    application/json:
+      schema: { $ref: './schemas.yaml#/Error' }

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

@@ -0,0 +1,23 @@
+PageEnvelope:
+  type: object
+  description: "envelope shared by every list endpoint — data is an array of that resource"
+  properties:
+    limit: { type: integer }
+    offset: { type: integer }
+
+Error:
+  type: object
+  properties:
+    error:
+      type: object
+      properties:
+        code: { type: string, description: "machine-readable, e.g. USER_NOT_FOUND, VALIDATION_ERROR" }
+        message: { type: string }
+        details: { type: object, additionalProperties: true, nullable: true, description: "only present for VALIDATION_ERROR, field->tag that failed" }
+        request_id: { type: string, description: "correlates with server logs (header X-Request-ID)" }
+  example:
+    error:
+      code: "VALIDATION_ERROR"
+      message: "invalid input"
+      details: { email: "email" }
+      request_id: "a1b2c3d4e5f6a7b8"

package/templates/create/features/docs/health/health-livez.yaml.hbs

@@ -0,0 +1,13 @@
+get:
+  summary: Liveness probe
+  operationId: getLivez
+  tags: [health]
+  responses:
+    "200":
+      description: process is running
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status: { type: string, example: ok }

package/templates/create/features/docs/health/health-readyz.yaml.hbs

@@ -0,0 +1,21 @@
+get:
+  summary: Readiness probe (ping DB)
+  operationId: getReadyz
+  tags: [health]
+  responses:
+    "200":
+      description: ready
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status: { type: string, example: ok }
+    "503":
+      description: DB unreachable
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status: { type: string, example: unavailable }

package/templates/create/features/docs/openapi.yaml.hbs

@@ -0,0 +1,33 @@
+# ponytail: hand-written, not generated from annotations — cheap while the
+# endpoint count is low. Ceiling: must be updated by hand whenever an
+# endpoint/DTO changes beyond what `generate module` scaffolds.
+# Switch to swaggo (comment-generated) if drift becomes a recurring problem.
+# multi-file: split by domain module (health/<domain>) + common/ for shared
+# pieces — this file is just the index. `generate module <name>`
+# adds its paths/schemas here automatically; `generate method` does not
+# (endpoint-specific docs stay hand-written).
+openapi: 3.0.3
+info:
+  title: {{projectName}} API
+  version: "1.0.0"
+  description: Every resource uses UUID v7 as its id; list endpoints return the {data, limit, offset} envelope.
+servers:
+  - url: http://localhost:8080
+
+paths:
+  /livez:
+    $ref: './health/health-livez.yaml'
+  /readyz:
+    $ref: './health/health-readyz.yaml'
+  # go-scaffold:paths
+
+components:
+  schemas:
+    PageEnvelope: { $ref: './common/schemas.yaml#/PageEnvelope' }
+    Error: { $ref: './common/schemas.yaml#/Error' }
+    # go-scaffold:schemas
+  responses:
+    ValidationError: { $ref: './common/responses.yaml#/ValidationError' }
+    NotFoundError: { $ref: './common/responses.yaml#/NotFoundError' }
+    ConflictError: { $ref: './common/responses.yaml#/ConflictError' }
+    UnprocessableEntityError: { $ref: './common/responses.yaml#/UnprocessableEntityError' }

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

@@ -0,0 +1,119 @@
+# Coding Patterns: {{projectName}}
+
+> Status: generated by `@nakedev/go-scaffold`
+> Last updated: scaffold creation time
+
+## Domain Package Shape
+
+Every domain generated by `go-scaffold generate module <name>` looks
+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, fake repo, no DB
+└── handler_test.go     # integration test, real Postgres, transaction rolled back per test
+```
+
+### 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/main.go` imports each domain's `model`
+  package under an alias (`ordermodel`, `usermodel`, ...) since they all share
+  the package name `model`
+
+## Layer Conventions
+
+### Handler
+- Owns routing, request binding, and calling the service
+- 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)`
+
+### 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
+- 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
+
+### Repository
+- The only file per domain that talks to GORM
+- Every method takes `ctx context.Context` first, so a cancelled request
+  cancels the query
+- Look up by ID with an explicit `"id = ?"` — the PK is a UUID, not an int,
+  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
+
+### 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
+
+## Domains With a Foreign Key (Relations) — 3 Rules
+
+The CLI does not scaffold relations between domains; when you add one by
+hand, follow these three rules (see `internal/app/order` for a worked example
+if this project has one):
+
+1. **Reference by ID column only** (`UserID uuid.UUID`). No GORM
+   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.
+
+## Adding One Endpoint — `generate method`
+
+```bash
+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 `fakeRepo` 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.
+
+## 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 fake repository — no DB required, always runs.
+- `handler_test.go` runs against a real Postgres instance inside a
+  transaction that's rolled back after each test — skips automatically if
+  the DB isn't reachable.
+
+## 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