@nakedev/go-scaffold 0.1.0

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

@@ -0,0 +1,38 @@
+# Tech Stack: {{projectName}}
+
+> Status: generated by `@nakedev/go-scaffold`
+
+## Stack Overview
+
+| Layer | Technology |
+|-------|-----------|
+| Language | Go 1.25 |
+| HTTP framework | Gin (`github.com/gin-gonic/gin` v1.10.0) |
+| Database | PostgreSQL |
+| ORM | GORM (`gorm.io/gorm` v1.25.12 + `gorm.io/driver/postgres` v1.5.9) |
+| Validation | `go-playground/validator/v10` v10.20.0 |
+| IDs | UUID v7 (`google/uuid` v1.6.0) |
+| Logging | `log/slog`, JSON handler |
+| Migrations | [golang-migrate](https://github.com/golang-migrate/migrate) |
+| Testing | stdlib `testing`, real Postgres for integration tests |
+
+## Scaffolded Capabilities
+
+- Response envelope (`apperror`) and pagination helpers: always enabled
+- 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}}`
+- 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
+
+## Operational Notes
+
+{{#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 openapiDocs}}- `docs/openapi.yaml` is hand-written, not generated — update it whenever an
+  endpoint or DTO changes
+{{/if}}- Versions above are what `go-scaffold create` pinned in `go.mod` — bump them
+  by hand (`go get -u` + `go mod tidy`) as the stack evolves

package/templates/generate/module/docs/collection.yaml.hbs

@@ -0,0 +1,36 @@
+post:
+  summary: Create {{pkg}}
+  operationId: create{{pascalName}}
+  tags: [{{plural}}]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/{{pascalName}}CreateInput' }
+  responses:
+    "201":
+      description: created
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/{{pascalName}}Response' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+get:
+  summary: List {{plural}}
+  operationId: list{{pascalName}}
+  tags: [{{plural}}]
+  parameters:
+    - $ref: '../common/parameters.yaml#/Limit'
+    - $ref: '../common/parameters.yaml#/Offset'
+  responses:
+    "200":
+      description: paginated list
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: '../common/schemas.yaml#/PageEnvelope'
+              - type: object
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: './schemas.yaml#/{{pascalName}}Response' }

package/templates/generate/module/docs/item.yaml.hbs

@@ -0,0 +1,37 @@
+parameters:
+  - $ref: '../common/parameters.yaml#/IdParam'
+get:
+  summary: Get {{pkg}}
+  operationId: get{{pascalName}}
+  tags: [{{plural}}]
+  responses:
+    "200":
+      description: ok
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/{{pascalName}}Response' }
+    "404": { $ref: '../common/responses.yaml#/NotFoundError' }
+put:
+  summary: Update {{pkg}}
+  operationId: update{{pascalName}}
+  tags: [{{plural}}]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/{{pascalName}}UpdateInput' }
+  responses:
+    "200":
+      description: updated
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/{{pascalName}}Response' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "404": { $ref: '../common/responses.yaml#/NotFoundError' }
+delete:
+  summary: Delete {{pkg}}
+  operationId: delete{{pascalName}}
+  tags: [{{plural}}]
+  responses:
+    "204": { description: deleted }
+    "404": { $ref: '../common/responses.yaml#/NotFoundError' }

package/templates/generate/module/docs/schemas.yaml.hbs

@@ -0,0 +1,13 @@
+{{pascalName}}CreateInput:
+  type: object
+  description: "TODO: add real request fields — matches the generated createInput stub, currently empty"
+  properties: {}
+{{pascalName}}UpdateInput:
+  type: object
+  description: "TODO: add real request fields — matches the generated updateInput stub, currently empty"
+  properties: {}
+{{pascalName}}Response:
+  type: object
+  properties:
+    id: { type: string, format: uuid }
+    created_at: { type: string, format: date-time }

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

@@ -0,0 +1,29 @@
+package {{pkg}}
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/{{modulePath}}/model"
+
+	"github.com/google/uuid"
+)
+
+// TODO: add request fields, e.g. Name string `json:"name" binding:"required"`
+type createInput struct {
+}
+
+// TODO: add request fields, e.g. Name string `json:"name" binding:"omitempty"`
+type updateInput struct {
+}
+
+// response = the DTO sent out (kept separate from the model so a later DB column doesn't leak automatically)
+type response struct {
+	ID        uuid.UUID `json:"id"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+func toResponse(m *model.{{pascalName}}) response {
+	return response{ID: m.ID, CreatedAt: m.CreatedAt}
+}
+
+// go-scaffold:dto

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

@@ -0,0 +1,28 @@
+package {{pkg}}
+
+import (
+	"net/http"
+
+	"{{goModule}}/internal/shared/apperror"
+)
+
+// error catalog specific to {{pkg}} — codes carry more meaning than the generic apperror ones
+// functions, not vars: the error middleware writes RequestID onto the returned pointer directly
+// (a shared instance would race across concurrent requests). Not every entry is called by every
+// module (a minimal module calls none of these until `generate method` wires one in), hence nolint.
+//
+//nolint:unused
+func errNotFound() *apperror.AppError {
+	return apperror.New(http.StatusNotFound, "{{errorPrefix}}_NOT_FOUND", "{{pkg}} not found")
+}
+
+//nolint:unused
+func errConflict() *apperror.AppError {
+	// TODO: rename/reword once a real unique field exists (e.g. email already exists)
+	return apperror.New(http.StatusConflict, "{{errorPrefix}}_CONFLICT", "{{pkg}} already exists")
+}
+
+//nolint:unused
+func errHasReferences() *apperror.AppError {
+	return apperror.New(http.StatusConflict, "{{errorPrefix}}_HAS_REFERENCES", "{{pkg}} still has related records")
+}

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

@@ -0,0 +1,103 @@
+package {{pkg}}
+
+import (
+	"net/http"
+
+	"{{goModule}}/internal/shared/httpx"
+	"{{goModule}}/internal/shared/pagination"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Handler = delivery for {{pkg}} (parses HTTP, calls the service, attaches errors for the middleware to render)
+type Handler struct {
+	svc *Service
+}
+
+func NewHandler(svc *Service) *Handler {
+	return &Handler{svc: svc}
+}
+
+// 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) {
+	g := rg.Group("/{{plural}}")
+	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 (h *Handler) create(c *gin.Context) {
+	var in createInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	m, err := h.svc.Create(c.Request.Context())
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	c.JSON(http.StatusCreated, toResponse(m))
+}
+
+func (h *Handler) list(c *gin.Context) {
+	p := pagination.Parse(c)
+	items, err := h.svc.List(c.Request.Context(), p.Limit, p.Offset)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	out := make([]response, len(items))
+	for i := range items {
+		out[i] = 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
+	}
+	m, err := h.svc.Get(c.Request.Context(), id)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	c.JSON(http.StatusOK, 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
+	}
+	m, err := h.svc.Update(c.Request.Context(), id)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	c.JSON(http.StatusOK, toResponse(m))
+}
+
+func (h *Handler) delete(c *gin.Context) {
+	id, ok := httpx.ParseID(c)
+	if !ok {
+		return
+	}
+	if err := h.svc.Delete(c.Request.Context(), id); err != nil {
+		c.Error(err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// go-scaffold:handler-funcs

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

@@ -0,0 +1,105 @@
+package {{pkg}}
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"sync"
+	"testing"
+
+	"{{goModule}}/internal/app/{{modulePath}}/model"
+	"{{goModule}}/internal/shared/middleware"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+// integration test backed by real Postgres (same engine as prod, no sqlite) — skips if the DB isn't reachable
+// start the DB: docker compose up -d  (override with TEST_DB_DSN)
+var (
+	testDBOnce sync.Once
+	testDB     *gorm.DB
+	testDBErr  error
+)
+
+func dbForTest(t *testing.T) *gorm.DB {
+	t.Helper()
+	testDBOnce.Do(func() {
+		dsn := os.Getenv("TEST_DB_DSN")
+		if dsn == "" {
+			dsn = "postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable"
+		}
+		if testDB, testDBErr = gorm.Open(postgres.Open(dsn), &gorm.Config{TranslateError: true}); testDBErr == nil {
+			// drop first — AutoMigrate can't change an existing column's type, always start from a fresh schema
+			_ = testDB.Migrator().DropTable(&model.{{pascalName}}{})
+			testDBErr = testDB.AutoMigrate(&model.{{pascalName}}{})
+		}
+	})
+	if testDBErr != nil {
+		t.Skipf("postgres not ready (docker compose up -d, or set TEST_DB_DSN): %v", testDBErr)
+	}
+	return testDB
+}
+
+// setup builds the full stack on a transaction that's rolled back at the end → each test is isolated, no leftover rows
+func setup(t *testing.T) *gin.Engine {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	tx := dbForTest(t).Begin()
+	t.Cleanup(func() { tx.Rollback() })
+	r := gin.New()
+	r.Use(middleware.RequestID(), middleware.Error())
+	NewHandler(NewService(NewRepository(tx))).Register(r)
+	return r
+}
+
+func do(r *gin.Engine, method, path, body string) *httptest.ResponseRecorder {
+	req := httptest.NewRequest(method, path, bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+	return w
+}
+
+func TestHandler_Create_OK(t *testing.T) {
+	r := setup(t)
+	w := do(r, http.MethodPost, "/{{plural}}", `{}`)
+	if w.Code != http.StatusCreated {
+		t.Fatalf("want 201, got %d body=%s", w.Code, w.Body)
+	}
+}
+
+func TestHandler_Get_NotFound(t *testing.T) {
+	r := setup(t)
+	w := do(r, http.MethodGet, "/{{plural}}/"+uuid.NewString(), "")
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("want 404, got %d body=%s", w.Code, w.Body)
+	}
+}
+
+func TestHandler_Get_InvalidID(t *testing.T) {
+	r := setup(t)
+	w := do(r, http.MethodGet, "/{{plural}}/not-a-uuid", "")
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("want 400, got %d body=%s", w.Code, w.Body)
+	}
+}
+
+func TestHandler_Delete_OK(t *testing.T) {
+	r := setup(t)
+	created := do(r, http.MethodPost, "/{{plural}}", `{}`)
+	var body struct {
+		ID string `json:"id"`
+	}
+	if err := json.Unmarshal(created.Body.Bytes(), &body); err != nil {
+		t.Fatalf("decode create response: %v", err)
+	}
+	w := do(r, http.MethodDelete, "/{{plural}}/"+body.ID, "")
+	if w.Code != http.StatusNoContent {
+		t.Fatalf("want 204, got %d body=%s", w.Code, w.Body)
+	}
+}

package/templates/generate/module/migration.down.sql.hbs

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS {{plural}};

package/templates/generate/module/migration.up.sql.hbs

@@ -0,0 +1,5 @@
+CREATE TABLE {{plural}} (
+    id         UUID PRIMARY KEY,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);

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

@@ -0,0 +1,26 @@
+package {{pkg}}
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/{{modulePath}}/model"
+
+	"github.com/google/uuid"
+)
+
+// response = the DTO sent out (kept separate from the model so a later DB column doesn't leak automatically)
+// TODO: add fields as you generate methods that return more than id/created_at
+// unused until `generate method` adds a method that returns one
+//
+//nolint:unused
+type response struct {
+	ID        uuid.UUID `json:"id"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+//nolint:unused
+func toResponse(m *model.{{pascalName}}) response {
+	return response{ID: m.ID, CreatedAt: m.CreatedAt}
+}
+
+// go-scaffold:dto

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

@@ -0,0 +1,24 @@
+package {{pkg}}
+
+import (
+	"github.com/gin-gonic/gin"
+)
+
+// Handler = delivery for {{pkg}} (parses HTTP, calls the service, attaches errors for the middleware to render)
+type Handler struct {
+	svc *Service
+}
+
+func NewHandler(svc *Service) *Handler {
+	return &Handler{svc: svc}
+}
+
+// Register wires {{pkg}}'s routes onto the router group (takes an IRouter so it can be nested under /v1)
+// minimal module: no routes yet — add them with `go-scaffold generate method {{pkg}} <name> --type ...`
+func (h *Handler) Register(rg gin.IRouter) {
+	g := rg.Group("/{{plural}}")
+	_ = g
+	// go-scaffold:handler-routes
+}
+
+// go-scaffold:handler-funcs

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

@@ -0,0 +1,70 @@
+package {{pkg}}
+
+import (
+	"bytes"
+	"net/http/httptest"
+	"os"
+	"sync"
+	"testing"
+
+	"{{goModule}}/internal/app/{{modulePath}}/model"
+	"{{goModule}}/internal/shared/middleware"
+
+	"gorm.io/gorm"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/driver/postgres"
+)
+
+// integration test harness, backed by real Postgres (same engine as prod, no sqlite) — skips if
+// the DB isn't reachable. minimal module: no routes yet, so no tests reference this yet — kept
+// ready for once `generate method` adds endpoints (start the DB: docker compose up -d, override
+// with TEST_DB_DSN)
+//nolint:unused
+var (
+	testDBOnce sync.Once
+	testDB     *gorm.DB
+	testDBErr  error
+)
+
+//nolint:unused
+func dbForTest(t *testing.T) *gorm.DB {
+	t.Helper()
+	testDBOnce.Do(func() {
+		dsn := os.Getenv("TEST_DB_DSN")
+		if dsn == "" {
+			dsn = "postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable"
+		}
+		if testDB, testDBErr = gorm.Open(postgres.Open(dsn), &gorm.Config{TranslateError: true}); testDBErr == nil {
+			_ = testDB.Migrator().DropTable(&model.{{pascalName}}{})
+			testDBErr = testDB.AutoMigrate(&model.{{pascalName}}{})
+		}
+	})
+	if testDBErr != nil {
+		t.Skipf("postgres not ready (docker compose up -d, or set TEST_DB_DSN): %v", testDBErr)
+	}
+	return testDB
+}
+
+// setup builds the full stack on a transaction that's rolled back at the end → each test is isolated, no leftover rows
+//
+//nolint:unused
+func setup(t *testing.T) *gin.Engine {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	tx := dbForTest(t).Begin()
+	t.Cleanup(func() { tx.Rollback() })
+	r := gin.New()
+	r.Use(middleware.RequestID(), middleware.Error())
+	NewHandler(NewService(NewRepository(tx))).Register(r)
+	return r
+}
+
+//nolint:unused
+func do(r *gin.Engine, method, path, body string) *httptest.ResponseRecorder {
+	req := httptest.NewRequest(method, path, bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+	return w
+}

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

@@ -0,0 +1,45 @@
+package {{pkg}}
+
+import (
+	"context"
+	"errors"
+
+	"{{goModule}}/internal/app/{{modulePath}}/model"
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+// repository = what the service needs from the data layer (declared on the consumer side, so it can be mocked in tests)
+// minimal module: no CRUD wired yet, but the full data-access surface is here so `generate method` has something to call
+type repository interface {
+	Create(ctx context.Context, m *model.{{pascalName}}) error
+	FindAll(ctx context.Context, limit, offset int) ([]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:repository-interface
+}
+
+// Service = business logic for {{pkg}} (rules live here, it knows nothing about HTTP)
+// minimal module: add methods with `go-scaffold generate method {{pkg}} <name> --type ...`
+type Service struct {
+	repo repository
+}
+
+func NewService(repo repository) *Service {
+	return &Service{repo: repo}
+}
+
+// unused until `generate method` adds a get-one/patch/put/delete method that calls it
+//
+//nolint:unused
+func wrapFindErr(err error) error {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return errNotFound()
+	}
+	return apperror.NewInternal()
+}
+
+// go-scaffold:service-methods

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

@@ -0,0 +1,54 @@
+package {{pkg}}
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"{{goModule}}/internal/app/{{modulePath}}/model"
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/google/uuid"
+)
+
+// fakeRepo = mock of the repository interface, so the service can be tested without a DB
+// minimal module: no service methods yet, so no tests reference this — kept ready for
+// when `generate method` adds one (its patches append matching stubs here automatically
+// for a `get --get-mode one --field` lookup)
+//nolint:unused
+type fakeRepo struct {
+	err error
+	m   *model.{{pascalName}}
+}
+
+//nolint:unused
+func (f *fakeRepo) Create(context.Context, *model.{{pascalName}}) error                    { return f.err }
+
+//nolint:unused
+func (f *fakeRepo) FindAll(context.Context, int, int) ([]model.{{pascalName}}, error) { return nil, f.err }
+
+//nolint:unused
+func (f *fakeRepo) FindByID(context.Context, uuid.UUID) (*model.{{pascalName}}, error) {
+	if f.err != nil {
+		return nil, f.err
+	}
+	return f.m, nil
+}
+
+//nolint:unused
+func (f *fakeRepo) Update(context.Context, *model.{{pascalName}}) error { return f.err }
+
+//nolint:unused
+func (f *fakeRepo) Delete(context.Context, uuid.UUID) error { return f.err }
+
+// go-scaffold:fake-repo-methods
+
+//nolint:unused
+func status(t *testing.T, err error) int {
+	t.Helper()
+	var appErr *apperror.AppError
+	if !errors.As(err, &appErr) {
+		t.Fatalf("expected *apperror.AppError, got %T: %v", err, err)
+	}
+	return appErr.HTTPStatus
+}

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

@@ -0,0 +1,20 @@
+// Package model holds this domain's GORM tables — a folder (not a single
+// file) so a domain with more than one table can add a file per table
+// without cluttering the domain package's top level.
+package model
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// {{pascalName}} = domain model + GORM table
+// TODO: add your real fields here.
+// ID = UUID v7 generated app-side (service.Create via id.New) instead of a DB
+// default, so the app has the id before insert without needing gen_random_uuid.
+type {{pascalName}} struct {
+	ID        uuid.UUID `json:"id" gorm:"type:uuid;primaryKey"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}