@nakedev/go-scaffold 0.4.0 → 0.5.0

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

@@ -0,0 +1,83 @@
+// 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"
+{{#if auth}}
+	"{{goModule}}/internal/shared/middleware"
+{{/if}}
+
+	"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}}
+
+// Register wires the module's route group. Add endpoints with
+// `go-scaffold generate method {{pkg}} <name> --type ...`.
+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
+	_ = appError
+	// go-scaffold:handler-routes
+}
+
+func appError(err error) error {
+	switch {
+	case errors.Is(err, domain.ErrNotFound):
+		return apperror.New(http.StatusNotFound, "{{errorPrefix}}_NOT_FOUND", "{{pkg}} not found")
+	case errors.Is(err, domain.ErrConflict):
+		return apperror.New(http.StatusConflict, "{{errorPrefix}}_CONFLICT", "{{pkg}} already exists")
+	case errors.Is(err, domain.ErrStaleVersion):
+		return apperror.New(http.StatusConflict, "{{errorPrefix}}_STALE", "{{pkg}} was modified by someone else — reload and try again")
+	case errors.Is(err, domain.ErrHasReferences):
+		return apperror.New(http.StatusConflict, "{{errorPrefix}}_HAS_REFERENCES", "{{pkg}} still has related records")
+	case errors.Is(err, domain.ErrNotImplemented):
+		return apperror.New(http.StatusNotImplemented, "NOT_IMPLEMENTED", "not implemented")
+	default:
+		return apperror.NewInternal(err)
+	}
+}
+
+// go-scaffold:handler-funcs

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

@@ -0,0 +1,18 @@
+package httpadapter
+
+import (
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestHandler_RegisterCRUD(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+{{#if cqrs}}
+	h := NewHandler(nil, nil{{#if auth}}, "test-secret"{{/if}}{{#if permission}}, nil{{/if}})
+{{else}}
+	h := NewHandler(nil{{#if auth}}, "test-secret"{{/if}}{{#if permission}}, nil{{/if}})
+{{/if}}
+	h.Register(r)
+}

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

@@ -0,0 +1,30 @@
+package httpadapter
+
+import (
+	{{#if permission}}
+	"context"
+	"time"
+	{{/if}}
+	"testing"
+
+	{{#if permission}}
+	"{{goModule}}/internal/shared/middleware"
+	{{/if}}
+	"github.com/gin-gonic/gin"
+)
+
+func TestHandler_Register(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	{{#if permission}}
+	authz := middleware.NewAuthz(func(context.Context, string) (map[string]struct{}, error) {
+		return map[string]struct{}{"{{permission}}": {}}, nil
+	}, time.Minute)
+	{{/if}}
+{{#if cqrs}}
+	h := NewHandler(nil, nil{{#if auth}}, "test-secret"{{/if}}{{#if permission}}, authz{{/if}})
+{{else}}
+	h := NewHandler(nil{{#if auth}}, "test-secret"{{/if}}{{#if permission}}, authz{{/if}})
+{{/if}}
+	h.Register(r)
+}

package/templates/generate/module/hexagonal/adapters/outbound/postgres/model.go.hbs

@@ -0,0 +1,37 @@
+// Package postgres is the {{pkg}} outbound adapter. Its GORM model is not
+// exported as a domain type; conversion happens at this boundary.
+package postgres
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+
+	"github.com/google/uuid"
+)
+
+type {{pascalName}}Model struct {
+	ID        uuid.UUID `gorm:"type:uuid;primaryKey"`
+	CreatedAt time.Time
+	UpdatedAt time.Time
+	Version   int `gorm:"not null;default:1"`
+	// TODO: keep persistence-only fields here and map them explicitly.
+}
+
+func ({{pascalName}}Model) TableName() string {
+	return "{{schemaName}}.{{tableName}}"
+}
+
+func toDomain(m *{{pascalName}}Model) *domain.{{pascalName}} {
+	if m == nil {
+		return nil
+	}
+	return &domain.{{pascalName}}{ID: m.ID, CreatedAt: m.CreatedAt, UpdatedAt: m.UpdatedAt, Version: m.Version}
+}
+
+func fromDomain(m *domain.{{pascalName}}) *{{pascalName}}Model {
+	if m == nil {
+		return nil
+	}
+	return &{{pascalName}}Model{ID: m.ID, CreatedAt: m.CreatedAt, UpdatedAt: m.UpdatedAt, Version: m.Version}
+}

package/templates/generate/module/hexagonal/adapters/outbound/postgres/repository.go.hbs

@@ -0,0 +1,95 @@
+package postgres
+
+import (
+	"context"
+	"errors"
+
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/app/{{modulePath}}/ports"
+	"{{goModule}}/internal/shared/dberr"
+	"{{goModule}}/internal/shared/tx"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+var _ ports.Repository = (*Repository)(nil)
+
+type Repository struct {
+	db *gorm.DB
+}
+
+func NewRepository(db *gorm.DB) *Repository {
+	return &Repository{db: db}
+}
+
+func (r *Repository) Create(ctx context.Context, m *domain.{{pascalName}}) error {
+	if err := tx.From(ctx, r.db).WithContext(ctx).Create(fromDomain(m)).Error; err != nil {
+		return mapDatabaseError(err)
+	}
+	return nil
+}
+
+func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]domain.{{pascalName}}, error) {
+	var rows []{{pascalName}}Model
+	if err := tx.From(ctx, r.db).WithContext(ctx).Order("id desc").Limit(limit).Offset(offset).Find(&rows).Error; err != nil {
+		return nil, mapDatabaseError(err)
+	}
+	items := make([]domain.{{pascalName}}, len(rows))
+	for i := range rows {
+		items[i] = *toDomain(&rows[i])
+	}
+	return items, nil
+}
+
+func (r *Repository) FindByID(ctx context.Context, id uuid.UUID) (*domain.{{pascalName}}, error) {
+	var row {{pascalName}}Model
+	if err := tx.From(ctx, r.db).WithContext(ctx).First(&row, "id = ?", id).Error; err != nil {
+		return nil, mapDatabaseError(err)
+	}
+	return toDomain(&row), nil
+}
+
+func (r *Repository) Update(ctx context.Context, m *domain.{{pascalName}}) error {
+	expected := m.Version
+	row := fromDomain(m)
+	row.Version = expected + 1
+	result := tx.From(ctx, r.db).WithContext(ctx).
+		Model(&{{pascalName}}Model{}).
+		Where("id = ? AND version = ?", m.ID, expected).
+		Select("*").Omit("id", "created_at").Updates(row)
+	if result.Error != nil {
+		return mapDatabaseError(result.Error)
+	}
+	if result.RowsAffected == 0 {
+		return domain.ErrStaleVersion
+	}
+	m.Version = row.Version
+	return nil
+}
+
+func (r *Repository) Delete(ctx context.Context, id uuid.UUID) error {
+	result := tx.From(ctx, r.db).WithContext(ctx).Delete(&{{pascalName}}Model{}, "id = ?", id)
+	if result.Error != nil {
+		return mapDatabaseError(result.Error)
+	}
+	if result.RowsAffected == 0 {
+		return domain.ErrNotFound
+	}
+	return nil
+}
+
+func mapDatabaseError(err error) error {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return domain.ErrNotFound
+	}
+	if dberr.IsDuplicate(err) {
+		return domain.ErrConflict
+	}
+	if dberr.IsForeignKey(err) {
+		return domain.ErrHasReferences
+	}
+	return err
+}
+
+// go-scaffold:repository-methods

package/templates/generate/module/{repository_test.go.hbs → hexagonal/adapters/outbound/postgres/repository_test.go.hbs}

@@ -1,4 +1,4 @@
-package {{pkg}}
+package postgres
 
 import (
 	"context"
@@ -6,7 +6,7 @@ import (
 	"os"
 	"testing"
 
-	"{{goModule}}/internal/app/{{modulePath}}/model"
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
 
 	"github.com/google/uuid"
 	"gorm.io/driver/postgres"
@@ -15,7 +15,7 @@ import (
 
 // repositoryDBForTest expects the test database schema to come from the same
 // versioned SQL migrations used in production. Unit tests stay database-free;
-// CI sets REQUIRE_TEST_DB=true so an unavailable/unmigrated database fails
+// CI sets REQUIRE_TEST_DB=true so an unavailable or unmigrated database fails
 // instead of becoming a false-green skip.
 func repositoryDBForTest(t *testing.T) *gorm.DB {
 	t.Helper()
@@ -62,7 +62,7 @@ func TestRepository_CreateFindDelete(t *testing.T) {
 	repo := NewRepository(repositoryDBForTest(t))
 	ctx := context.Background()
 	id := uuid.New()
-	item := &model.{{pascalName}}{ID: id}
+	item := &domain.{{pascalName}}{ID: id, Version: 1}
 
 	if err := repo.Create(ctx, item); err != nil {
 		t.Fatalf("create: %v", err)
@@ -85,13 +85,13 @@ func TestRepository_CreateFindDelete(t *testing.T) {
 func TestRepository_Update_RefusesStaleVersion(t *testing.T) {
 	repo := NewRepository(repositoryDBForTest(t))
 	ctx := context.Background()
-	item := &model.{{pascalName}}{ID: uuid.New()}
+	item := &domain.{{pascalName}}{ID: uuid.New(), Version: 1}
 
 	if err := repo.Create(ctx, item); err != nil {
 		t.Fatalf("create: %v", err)
 	}
 
-	first := &model.{{pascalName}}{ID: item.ID, Version: item.Version}
+	first := &domain.{{pascalName}}{ID: item.ID, Version: item.Version}
 	if err := repo.Update(ctx, first); err != nil {
 		t.Fatalf("first update: %v", err)
 	}
@@ -99,8 +99,8 @@ func TestRepository_Update_RefusesStaleVersion(t *testing.T) {
 		t.Fatalf("want version bumped to %d, got %d", item.Version+1, first.Version)
 	}
 
-	stale := &model.{{pascalName}}{ID: item.ID, Version: item.Version}
-	if err := repo.Update(ctx, stale); !errors.Is(err, ErrStaleVersion) {
+	stale := &domain.{{pascalName}}{ID: item.ID, Version: item.Version}
+	if err := repo.Update(ctx, stale); !errors.Is(err, domain.ErrStaleVersion) {
 		t.Fatalf("want ErrStaleVersion for the second writer, got %v", err)
 	}
 	if stale.Version != item.Version {

package/templates/generate/module/hexagonal/application/commands.crud.go.hbs

@@ -0,0 +1,54 @@
+package application
+
+import (
+	"context"
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/app/{{modulePath}}/ports"
+	"{{goModule}}/internal/shared/id"
+
+	"github.com/google/uuid"
+)
+
+type CommandPort interface {
+	Create(context.Context, CreateInput) (*domain.{{pascalName}}, error)
+	Update(context.Context, uuid.UUID, UpdateInput) (*domain.{{pascalName}}, error)
+	Delete(context.Context, uuid.UUID) error
+	// go-scaffold:command-interface
+}
+
+type CommandHandler struct {
+	repo ports.CommandRepository
+}
+
+func NewCommandHandler(repo ports.CommandRepository) *CommandHandler {
+	return &CommandHandler{repo: repo}
+}
+
+func (h *CommandHandler) Create(ctx context.Context, in CreateInput) (*domain.{{pascalName}}, error) {
+	// TODO: map in to real domain fields and enforce invariants.
+	_ = in
+	m := &domain.{{pascalName}}{ID: id.New(), Version: 1}
+	if err := h.repo.Create(ctx, m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+func (h *CommandHandler) Update(ctx context.Context, id uuid.UUID, in UpdateInput) (*domain.{{pascalName}}, error) {
+	m, err := h.repo.FindByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	// TODO: map in to real domain fields before saving.
+	m.Version = in.Version
+	if err := h.repo.Update(ctx, m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+func (h *CommandHandler) Delete(ctx context.Context, id uuid.UUID) error {
+	return h.repo.Delete(ctx, id)
+}
+
+// go-scaffold:command-methods

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

@@ -0,0 +1,25 @@
+package application
+
+import (
+	"context"
+
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/app/{{modulePath}}/ports"
+)
+
+type CommandPort interface {
+	// go-scaffold:command-interface
+}
+
+type CommandHandler struct {
+	repo ports.CommandRepository
+}
+
+func NewCommandHandler(repo ports.CommandRepository) *CommandHandler {
+	return &CommandHandler{repo: repo}
+}
+
+var _ context.Context
+var _ *domain.{{pascalName}}
+
+// go-scaffold:command-methods

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

@@ -0,0 +1,66 @@
+package application
+
+import (
+	"context"
+	"testing"
+
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/app/{{modulePath}}/ports"
+
+	"github.com/google/uuid"
+)
+
+// repositoryStub is shared by command and query tests. It intentionally
+// exposes one function per operation so a focused test can assert exactly
+// which side of the CQRS boundary was called.
+type repositoryStub struct {
+	createFn   func(context.Context, *domain.{{pascalName}}) error
+	findAllFn  func(context.Context, int, int) ([]domain.{{pascalName}}, error)
+	findByIDFn func(context.Context, uuid.UUID) (*domain.{{pascalName}}, error)
+	updateFn   func(context.Context, *domain.{{pascalName}}) error
+	deleteFn   func(context.Context, uuid.UUID) error
+	// go-scaffold:repository-stub-fields
+}
+
+func (s *repositoryStub) Create(ctx context.Context, m *domain.{{pascalName}}) error {
+	if s.createFn == nil {
+		panic("unexpected repository.Create call")
+	}
+	return s.createFn(ctx, m)
+}
+func (s *repositoryStub) FindAll(ctx context.Context, limit, offset int) ([]domain.{{pascalName}}, error) {
+	if s.findAllFn == nil {
+		panic("unexpected repository.FindAll call")
+	}
+	return s.findAllFn(ctx, limit, offset)
+}
+func (s *repositoryStub) FindByID(ctx context.Context, id uuid.UUID) (*domain.{{pascalName}}, error) {
+	if s.findByIDFn == nil {
+		panic("unexpected repository.FindByID call")
+	}
+	return s.findByIDFn(ctx, id)
+}
+func (s *repositoryStub) Update(ctx context.Context, m *domain.{{pascalName}}) error {
+	if s.updateFn == nil {
+		panic("unexpected repository.Update call")
+	}
+	return s.updateFn(ctx, m)
+}
+func (s *repositoryStub) Delete(ctx context.Context, id uuid.UUID) error {
+	if s.deleteFn == nil {
+		panic("unexpected repository.Delete call")
+	}
+	return s.deleteFn(ctx, id)
+}
+
+var _ ports.CommandRepository = (*repositoryStub)(nil)
+var _ ports.QueryRepository = (*repositoryStub)(nil)
+
+func TestCQRSHandlersCompose(t *testing.T) {
+	repo := &repositoryStub{}
+	if NewCommandHandler(repo) == nil || NewQueryHandler(repo) == nil {
+		t.Fatal("expected command and query handlers")
+	}
+}
+
+// go-scaffold:repository-stub-methods

package/templates/generate/module/hexagonal/application/dto.go.hbs

@@ -0,0 +1,35 @@
+package application
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+
+	"github.com/google/uuid"
+)
+
+// CreateInput and UpdateInput are transport-neutral application inputs. JSON
+// names and binding/validation tags stay in adapters/inbound/http/dto.go.
+type CreateInput struct {
+	// TODO: add command fields and validate them in the application/domain.
+}
+
+type UpdateInput struct {
+	// Version is the optimistic-concurrency version the client last observed.
+	Version int
+	// TODO: add update fields.
+}
+
+// Response is a transport-neutral application output. The inbound adapter
+// maps it to its protocol response before serialization.
+type Response struct {
+	ID        uuid.UUID
+	CreatedAt time.Time
+	Version   int
+}
+
+func ToResponse(m *domain.{{pascalName}}) Response {
+	return Response{ID: m.ID, CreatedAt: m.CreatedAt, Version: m.Version}
+}
+
+// go-scaffold:dto

package/templates/generate/module/hexagonal/application/dto.minimal.go.hbs

@@ -0,0 +1,25 @@
+package application
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+
+	"github.com/google/uuid"
+)
+
+// A lean module starts with no use-case input type. `generate method` adds
+// the exact input beside the endpoint that needs it.
+// Response is a transport-neutral application output. The inbound adapter
+// maps it to its protocol response before serialization.
+type Response struct {
+	ID        uuid.UUID
+	CreatedAt time.Time
+	Version   int
+}
+
+func ToResponse(m *domain.{{pascalName}}) Response {
+	return Response{ID: m.ID, CreatedAt: m.CreatedAt, Version: m.Version}
+}
+
+// go-scaffold:dto

package/templates/generate/module/hexagonal/application/queries.crud.go.hbs

@@ -0,0 +1,33 @@
+package application
+
+import (
+	"context"
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/app/{{modulePath}}/ports"
+
+	"github.com/google/uuid"
+)
+
+type QueryPort interface {
+	List(context.Context, int, int) ([]domain.{{pascalName}}, error)
+	Get(context.Context, uuid.UUID) (*domain.{{pascalName}}, error)
+	// go-scaffold:query-interface
+}
+
+type QueryHandler struct {
+	repo ports.QueryRepository
+}
+
+func NewQueryHandler(repo ports.QueryRepository) *QueryHandler {
+	return &QueryHandler{repo: repo}
+}
+
+func (h *QueryHandler) List(ctx context.Context, limit, offset int) ([]domain.{{pascalName}}, error) {
+	return h.repo.FindAll(ctx, limit, offset)
+}
+
+func (h *QueryHandler) Get(ctx context.Context, id uuid.UUID) (*domain.{{pascalName}}, error) {
+	return h.repo.FindByID(ctx, id)
+}
+
+// go-scaffold:query-methods

package/templates/generate/module/hexagonal/application/queries.go.hbs

@@ -0,0 +1,25 @@
+package application
+
+import (
+	"context"
+
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/app/{{modulePath}}/ports"
+)
+
+type QueryPort interface {
+	// go-scaffold:query-interface
+}
+
+type QueryHandler struct {
+	repo ports.QueryRepository
+}
+
+func NewQueryHandler(repo ports.QueryRepository) *QueryHandler {
+	return &QueryHandler{repo: repo}
+}
+
+var _ context.Context
+var _ *domain.{{pascalName}}
+
+// go-scaffold:query-methods

package/templates/generate/module/hexagonal/application/service.crud.go.hbs

@@ -0,0 +1,73 @@
+package application
+
+import (
+	"context"
+	"errors"
+
+	"{{goModule}}/internal/app/{{modulePath}}/domain"
+	"{{goModule}}/internal/app/{{modulePath}}/ports"
+	"{{goModule}}/internal/shared/id"
+
+	"github.com/google/uuid"
+)
+
+type ServicePort interface {
+	Create(context.Context, CreateInput) (*domain.{{pascalName}}, error)
+	List(context.Context, int, int) ([]domain.{{pascalName}}, error)
+	Get(context.Context, uuid.UUID) (*domain.{{pascalName}}, error)
+	Update(context.Context, uuid.UUID, UpdateInput) (*domain.{{pascalName}}, error)
+	Delete(context.Context, uuid.UUID) error
+	// go-scaffold:service-interface
+}
+
+type Service struct {
+	repo ports.Repository
+}
+
+func NewService(repo ports.Repository) *Service {
+	return &Service{repo: repo}
+}
+
+func (s *Service) Create(ctx context.Context, in CreateInput) (*domain.{{pascalName}}, error) {
+	// TODO: map in to real domain fields and enforce invariants.
+	_ = in
+	m := &domain.{{pascalName}}{ID: id.New(), Version: 1}
+	if err := s.repo.Create(ctx, m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+func (s *Service) List(ctx context.Context, limit, offset int) ([]domain.{{pascalName}}, error) {
+	return s.repo.FindAll(ctx, limit, offset)
+}
+
+func (s *Service) Get(ctx context.Context, id uuid.UUID) (*domain.{{pascalName}}, error) {
+	return s.repo.FindByID(ctx, id)
+}
+
+func (s *Service) Update(ctx context.Context, id uuid.UUID, in UpdateInput) (*domain.{{pascalName}}, error) {
+	m, err := s.repo.FindByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	// TODO: map in to real domain fields before saving.
+	m.Version = in.Version
+	if err := s.repo.Update(ctx, m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+func (s *Service) Delete(ctx context.Context, id uuid.UUID) error {
+	if err := s.repo.Delete(ctx, id); err != nil {
+		return err
+	}
+	return nil
+}
+
+// IsNotFound is useful to non-HTTP callers without exposing persistence
+// errors. The inbound HTTP adapter maps the same domain sentinel to 404.
+func IsNotFound(err error) bool { return errors.Is(err, domain.ErrNotFound) }
+
+// go-scaffold:service-methods