@nakedev/go-scaffold 0.1.4 → 0.3.0

package/templates/add/worker/internal/platform/mail/task.go.hbs

@@ -4,49 +4,46 @@ import (
 	"context"
 	"encoding/json"
 
-	"github.com/hibiken/asynq"
+	"{{goModule}}/internal/platform/queue"
 )
 
-const TypeSendEmail = "email:send"
-
-type sendEmailPayload struct {
-	To      string
-	Subject string
-	Body    string
+// SendEmail is the job cmd/api enqueues and cmd/worker runs. It is a plain
+// JSON struct on purpose — no queue backend's types appear here, so moving
+// between backends never touches this file.
+type SendEmail struct {
+	To      string `json:"to"`
+	Subject string `json:"subject"`
+	Body    string `json:"body"`
 }
 
-func NewSendEmailTask(p sendEmailPayload) *asynq.Task {
-	payload, _ := json.Marshal(p)
-	return asynq.NewTask(TypeSendEmail, payload)
-}
+// KindSendEmail is registered by cmd/worker and used when enqueueing.
+const KindSendEmail = "email:send"
 
-func HandleSendEmail(client *Client) asynq.Handler {
-	return asynq.HandlerFunc(func(ctx context.Context, task *asynq.Task) error {
-		var p sendEmailPayload
-		if err := json.Unmarshal(task.Payload(), &p); err != nil {
+func (SendEmail) Kind() string { return KindSendEmail }
+
+// Handle returns the worker-side handler for SendEmail.
+func Handle(c *Client) queue.Handler {
+	return func(ctx context.Context, raw []byte) error {
+		var p SendEmail
+		if err := json.Unmarshal(raw, &p); err != nil {
+			// Malformed payload will never parse — returning it lets the
+			// backend park the job for inspection instead of retrying it
+			// into a wall.
 			return err
 		}
-		return client.Send(p.To, p.Subject, p.Body)
-	})
-}
-
-type AsyncClient struct {
-	q interface {
-		Enqueue(task *asynq.Task, opts ...asynq.Option) (string, error)
+		return c.Send(p.To, p.Subject, p.Body)
 	}
 }
 
-func NewAsyncClient(q interface {
-	Enqueue(task *asynq.Task, opts ...asynq.Option) (string, error)
-}) *AsyncClient {
-	return &AsyncClient{q: q}
-}
+// AsyncClient enqueues mail instead of sending it inline, so an HTTP handler
+// returns in microseconds rather than blocking on SMTP.
+type AsyncClient struct{ q queue.Enqueuer }
+
+func NewAsyncClient(q queue.Enqueuer) *AsyncClient { return &AsyncClient{q: q} }
 
-// Send enqueues the email instead of sending it inline, so the caller (an
-// HTTP handler) returns in ~µs instead of blocking on SMTP. cmd/worker picks
-// it up and calls Client.Send.
-func (c *AsyncClient) Send(to, subject, body string) error {
-	task := NewSendEmailTask(sendEmailPayload{To: to, Subject: subject, Body: body})
-	_, err := c.q.Enqueue(task, asynq.MaxRetry(5))
-	return err
+// Send takes a ctx so the enqueue can join the caller's transaction: with a
+// Postgres-backed queue the mail is only ever sent if the write that asked
+// for it committed.
+func (c *AsyncClient) Send(ctx context.Context, to, subject, body string) error {
+	return c.q.Enqueue(ctx, SendEmail{To: to, Subject: subject, Body: body}, &queue.Options{MaxRetry: 5})
 }

package/templates/add/worker/internal/platform/queue/asynq.go.hbs

@@ -0,0 +1,140 @@
+package queue
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+
+	"github.com/hibiken/asynq"
+)
+
+// Asynq keeps jobs in Redis.
+//
+// ⚠️ It cannot honour the Enqueue contract in queue.go. Redis knows nothing
+// about your Postgres transaction, so a job enqueued inside tx.Do is still
+// delivered when that transaction rolls back — the classic "welcome email
+// sent to a user whose signup failed". The standard fix is an outbox: write
+// the job as a row in the same transaction, then relay those rows to Redis
+// from a separate loop. Add that before using this adapter for work that
+// must not fire against data that never existed.
+//
+// Pick this backend when throughput genuinely needs Redis (tens of thousands
+// of jobs per second), when several languages share one queue, or when the
+// primary database is already near capacity.
+type Asynq struct {
+	client *asynq.Client
+	server *asynq.Server
+	mux    *asynq.ServeMux
+	m      *mux
+}
+
+// NewAsynqEnqueuer builds an insert-only client, for cmd/api.
+func NewAsynqEnqueuer(redisURL string) (*Asynq, error) {
+	opt, err := asynq.ParseRedisURI(redisURL)
+	if err != nil {
+		return nil, err
+	}
+	return &Asynq{client: asynq.NewClient(opt), m: newMux()}, nil
+}
+
+// NewAsynqWorker builds a client that also works jobs, for cmd/worker.
+// Register every handler with Handle before calling Start.
+func NewAsynqWorker(redisURL string, concurrency int) (*Asynq, error) {
+	opt, err := asynq.ParseRedisURI(redisURL)
+	if err != nil {
+		return nil, err
+	}
+	srv := asynq.NewServer(opt, asynq.Config{
+		Concurrency: concurrency,
+		Logger:      &slogAdapter{inner: slog.Default()},
+	})
+	m := asynq.NewServeMux()
+	// One place to log every failed job, whatever it was.
+	m.Use(func(next asynq.Handler) asynq.Handler {
+		return asynq.HandlerFunc(func(ctx context.Context, task *asynq.Task) error {
+			err := next.ProcessTask(ctx, task)
+			if err != nil {
+				slog.Error("job failed", "kind", task.Type(), "error", err)
+			}
+			return err
+		})
+	})
+	return &Asynq{server: srv, mux: m, m: newMux()}, nil
+}
+
+// Handle registers a handler. Asynq dispatches on its own task type string,
+// which maps one-to-one onto our kind — no envelope needed on this backend.
+func (a *Asynq) Handle(kind string, h Handler) {
+	a.m.Handle(kind, h)
+	// Dispatch through our own table rather than closing over h, so both
+	// backends resolve a kind the same way — including what happens when a
+	// job arrives for a kind this binary doesn't know.
+	a.mux.Handle(kind, asynq.HandlerFunc(func(ctx context.Context, task *asynq.Task) error {
+		return a.m.dispatch(ctx, task.Type(), task.Payload())
+	}))
+}
+
+func (a *Asynq) Enqueue(ctx context.Context, j Job, opts *Options) error {
+	raw, err := encode(j)
+	if err != nil {
+		return err
+	}
+	var asynqOpts []asynq.Option
+	if opts != nil {
+		if opts.MaxRetry > 0 {
+			asynqOpts = append(asynqOpts, asynq.MaxRetry(opts.MaxRetry))
+		}
+		if !opts.RunAt.IsZero() {
+			asynqOpts = append(asynqOpts, asynq.ProcessAt(opts.RunAt))
+		}
+	}
+	_, err = a.client.EnqueueContext(ctx, asynq.NewTask(j.Kind(), raw), asynqOpts...)
+	return err
+}
+
+func (a *Asynq) Start(ctx context.Context) error {
+	if a.server == nil {
+		return fmt.Errorf("queue: this Asynq client was built for enqueueing only")
+	}
+	return a.server.Start(a.mux)
+}
+
+// Stop drains in-flight jobs. Asynq's Shutdown blocks with no timeout of its
+// own, so race it against ctx rather than letting a stuck job hang the
+// process forever.
+func (a *Asynq) Stop(ctx context.Context) error {
+	if a.server == nil {
+		return nil
+	}
+	done := make(chan struct{})
+	go func() {
+		a.server.Shutdown()
+		close(done)
+	}()
+	select {
+	case <-done:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+func (a *Asynq) Close() error {
+	if a.client == nil {
+		return nil
+	}
+	return a.client.Close()
+}
+
+// slogAdapter lets asynq log through slog. Asynq calls these like the stdlib
+// `log` package (a plain message, sometimes several args meant to be
+// concatenated), so fmt.Sprint joins them into one message rather than
+// passing them as slog key-value pairs, which would read a lone message
+// argument as a key with no value.
+type slogAdapter struct{ inner *slog.Logger }
+
+func (a *slogAdapter) Debug(args ...interface{}) { a.inner.Debug(fmt.Sprint(args...)) }
+func (a *slogAdapter) Info(args ...interface{})  { a.inner.Info(fmt.Sprint(args...)) }
+func (a *slogAdapter) Warn(args ...interface{})  { a.inner.Warn(fmt.Sprint(args...)) }
+func (a *slogAdapter) Error(args ...interface{}) { a.inner.Error(fmt.Sprint(args...)) }
+func (a *slogAdapter) Fatal(args ...interface{}) { a.inner.Error(fmt.Sprint(args...)) }

package/templates/add/worker/internal/platform/queue/queue.go.hbs

@@ -0,0 +1,87 @@
+// Package queue is this project's own vocabulary for background work.
+//
+// No backend package (River, Asynq, ...) may appear in this file or in any
+// caller — swapping backends has to mean rewriting one adapter file next to
+// this one, not every module that enqueues something.
+package queue
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sync"
+	"time"
+)
+
+// Job is one unit of background work. Each module defines its own job types;
+// the value is carried as JSON, so keep the fields plain and tagged.
+type Job interface {
+	// Kind is the stable identifier a handler registers against. Changing it
+	// orphans jobs already sitting in the queue.
+	Kind() string
+}
+
+// Options tunes a single enqueue. Each adapter translates these into its own
+// backend's equivalent — never rely on one for correctness, only for tuning.
+type Options struct {
+	// MaxRetry is how many times a failed job is retried before it is parked
+	// for inspection. Zero means "use the backend default".
+	MaxRetry int
+	// RunAt delays the job until this time. Zero means "as soon as possible".
+	RunAt time.Time
+}
+
+// Handler processes one job. raw is the JSON-encoded Job.
+type Handler func(ctx context.Context, raw []byte) error
+
+// Enqueuer is what application code depends on — nothing else.
+//
+// Contract: a job is delivered if, and only if, the database transaction
+// running on ctx commits. The Postgres-backed adapter gets this for free
+// (the job row joins that same transaction); a Redis-backed adapter cannot
+// provide it without an outbox, and says so in its own doc comment.
+type Enqueuer interface {
+	Enqueue(ctx context.Context, j Job, opts *Options) error
+}
+
+// Registry is what cmd/worker registers handlers on.
+type Registry interface {
+	Handle(kind string, h Handler)
+}
+
+// mux is the kind -> handler table every adapter dispatches through, so a
+// handler written against queue.Handler runs unchanged on any backend.
+type mux struct {
+	mu       sync.RWMutex
+	handlers map[string]Handler
+}
+
+func newMux() *mux { return &mux{handlers: make(map[string]Handler)} }
+
+// Handle panics on a duplicate kind: two handlers for one kind means one of
+// them silently never runs, which is far worse to debug than a boot failure.
+func (m *mux) Handle(kind string, h Handler) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if _, dup := m.handlers[kind]; dup {
+		panic("queue: duplicate handler registered for kind " + kind)
+	}
+	m.handlers[kind] = h
+}
+
+func (m *mux) dispatch(ctx context.Context, kind string, raw []byte) error {
+	m.mu.RLock()
+	h, ok := m.handlers[kind]
+	m.mu.RUnlock()
+	if !ok {
+		// Retrying cannot help until a binary that knows this kind is
+		// deployed — the error is returned so the job is retried/parked
+		// rather than dropped, which keeps the payload recoverable.
+		return fmt.Errorf("queue: no handler registered for kind %q", kind)
+	}
+	return h(ctx, raw)
+}
+
+// encode is shared by every adapter so a payload written by one backend is
+// readable by another during a switch-over, when both run side by side.
+func encode(j Job) ([]byte, error) { return json.Marshal(j) }

package/templates/add/worker/internal/platform/queue/river.go.hbs

@@ -0,0 +1,148 @@
+package queue
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"log/slog"
+	"regexp"
+
+	"{{goModule}}/internal/shared/tx"
+
+	"github.com/riverqueue/river"
+	"github.com/riverqueue/river/riverdriver/riverdatabasesql"
+	"gorm.io/gorm"
+)
+
+// envelope carries any queue.Job through River as a single River job kind.
+// River binds a worker to one concrete args type, so one envelope plus our
+// own kind dispatch keeps handlers byte-identical across backends.
+//
+// ponytail: the real kind travels as a River tag rather than a River kind —
+// enough to filter on in River's UI. Promote a job to its own River type the
+// day it needs per-kind queue or retry configuration.
+type envelope struct {
+	K   string          `json:"kind"`
+	Raw json.RawMessage `json:"payload"`
+}
+
+func (envelope) Kind() string { return "queue.envelope" }
+
+type envelopeWorker struct {
+	river.WorkerDefaults[envelope]
+	m *mux
+}
+
+func (w *envelopeWorker) Work(ctx context.Context, job *river.Job[envelope]) error {
+	return w.m.dispatch(ctx, job.Args.K, job.Args.Raw)
+}
+
+// River keeps jobs as rows in the same Postgres database as your data. That
+// is the entire point: Enqueue joins the caller's transaction, so a job is
+// delivered if and only if the write that scheduled it commits.
+//
+// It runs on River's database/sql driver so it can share GORM's existing
+// connection pool. ponytail: that driver cannot use Postgres LISTEN/NOTIFY,
+// so cmd/worker polls (sub-second pickup instead of instant). If a job ever
+// needs instant pickup, give cmd/worker its own pgxpool + riverpgxv5 client
+// and keep this one for inserting.
+type River struct {
+	client *river.Client[*sql.Tx]
+	db     *gorm.DB
+	m      *mux
+}
+
+// NewRiverEnqueuer builds an insert-only client, for cmd/api.
+func NewRiverEnqueuer(db *gorm.DB) (*River, error) {
+	sqlDB, err := db.DB()
+	if err != nil {
+		return nil, err
+	}
+	client, err := river.NewClient(riverdatabasesql.New(sqlDB), &river.Config{
+		Logger: slog.Default(),
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &River{client: client, db: db, m: newMux()}, nil
+}
+
+// NewRiverWorker builds a client that also works jobs, for cmd/worker.
+// Register every handler with Handle before calling Start.
+func NewRiverWorker(db *gorm.DB, concurrency int) (*River, error) {
+	m := newMux()
+	workers := river.NewWorkers()
+	river.AddWorker(workers, &envelopeWorker{m: m})
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return nil, err
+	}
+	client, err := river.NewClient(riverdatabasesql.New(sqlDB), &river.Config{
+		Logger:  slog.Default(),
+		Queues:  map[string]river.QueueConfig{river.QueueDefault: {MaxWorkers: concurrency}},
+		Workers: workers,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &River{client: client, db: db, m: m}, nil
+}
+
+func (r *River) Handle(kind string, h Handler) { r.m.Handle(kind, h) }
+
+// River validates a tag as \A[\w][\w\-]+[\w]\z and rejects the whole insert
+// if one doesn't match. Kinds like "email:send" don't, so map them to the
+// nearest legal form and drop the tag entirely if even that fails — a job
+// must never be lost over the spelling of a label in the admin UI.
+var (
+	tagUnsafe = regexp.MustCompile(`[^\w-]`)
+	tagLegal  = regexp.MustCompile(`\A[\w][\w\-]+[\w]\z`)
+)
+
+func kindTag(kind string) []string {
+	tag := tagUnsafe.ReplaceAllString(kind, "-")
+	if !tagLegal.MatchString(tag) {
+		return nil
+	}
+	return []string{tag}
+}
+
+func (r *River) Enqueue(ctx context.Context, j Job, opts *Options) error {
+	raw, err := encode(j)
+	if err != nil {
+		return err
+	}
+	env := envelope{K: j.Kind(), Raw: raw}
+
+	insertOpts := &river.InsertOpts{Tags: kindTag(j.Kind())}
+	if opts != nil {
+		if opts.MaxRetry > 0 {
+			insertOpts.MaxAttempts = opts.MaxRetry + 1 // River counts the first run as an attempt
+		}
+		if !opts.RunAt.IsZero() {
+			insertOpts.ScheduledAt = opts.RunAt
+		}
+	}
+
+	// Join the caller's transaction when there is one. This is the contract
+	// in queue.go, and the only reason the queue lives in Postgres at all.
+	if gdb := tx.From(ctx, r.db); gdb.Statement != nil {
+		if sqlTx, ok := gdb.Statement.ConnPool.(*sql.Tx); ok {
+			_, err = r.client.InsertTx(ctx, sqlTx, env, insertOpts)
+			return err
+		}
+	}
+	_, err = r.client.Insert(ctx, env, insertOpts)
+	return err
+}
+
+// Start begins working jobs. Only meaningful on a client from NewRiverWorker.
+func (r *River) Start(ctx context.Context) error { return r.client.Start(ctx) }
+
+// Stop drains in-flight jobs, giving up when ctx expires.
+func (r *River) Stop(ctx context.Context) error { return r.client.Stop(ctx) }
+
+// Close exists so cmd/api can shut the enqueuer down the same way whatever
+// backend it uses — River holds nothing of its own beyond GORM's pool.
+func (r *River) Close() error { return nil }

package/templates/create/base/.claude/skills/go-scaffold/SKILL.md.hbs

@@ -22,7 +22,7 @@ not hand-write a new one. Hand-writing a new `internal/app/<name>/` package,
 or adding a method by editing the handler/service directly, produces a shape
 that doesn't match the rest of the codebase (missing route registration,
 missing AutoMigrate wiring, a `repository` interface out of sync with its
-`fakeRepo` test mock, inconsistent error-catalog naming, etc.).
+`repositoryStub` test mock, inconsistent error-catalog naming, etc.).
 
 ## When to use this skill
 
@@ -46,22 +46,45 @@ missing AutoMigrate wiring, a `repository` interface out of sync with its
 Run from the project root:
 
 ```bash
-go-scaffold generate module <name>
+go-scaffold generate module <name> [--full] [--auth] [--permission <code>]
 go-scaffold generate method <module> <name> --type <get|post|put|patch|delete> [--get-mode all|one] [--field <name>]
+go-scaffold generate migration <name>
+go-scaffold undo module <name> [-y]
 ```
 
-`<name>` for a module should be a singular, lowercase, one-word domain noun
-(e.g. `order`, not `Orders` or `order-item`) — the CLI derives the Go
-package name, the pluralized REST route (`/orders`), and the table name
-from it.
+`<name>` for a module is a domain noun in whatever form reads naturally —
+singular or plural, any case, hyphens or underscores are all accepted and
+normalized (`products` → `product`, `Orders` → `order`, `order-item` →
+`orderitem`). From it the CLI derives the Go package name, the pluralized
+REST route (`/orders`, `/order-items`), the table, and the error-code prefix
+(`ORDER_ITEM_NOT_FOUND`). The only names it refuses are the ones that
+wouldn't compile: starting with a digit, or a Go keyword / predeclared type
+(`type`, `string`, `error`, ...).
 
 ### `generate module <name>`
 
-What you get: `internal/app/<name>/{model/,dto,errors,repository,service,handler,service_test,handler_test}.go`,
-a route registered under{{#if apiPrefix}} `/{{apiPrefix}}`{{else}} no prefix{{/if}}
-in `cmd/api/main.go`, the model added to the `AutoMigrate` call, and a new
-file in `migrations/`. There's no per-domain versioning — the route prefix
-is a single project-wide choice made at `create` time.
+**Minimal is the default** — the module is created with no endpoints, and
+what lands in `cmd/api/wiring.go` is an *empty route group* under{{#if apiPrefix}} `/{{apiPrefix}}`{{else}} no prefix{{/if}}
+waiting for `generate method`. You still get every file:
+`internal/app/<pkg>/{model/,dto,errors,repository,service,handler,service_test,handler_test,repository_test}.go`
+— the full data-access surface exists (the repository and its interface are
+complete) so `generate method` has something to call. Plus the model added
+to the `AutoMigrate` call and a new `migrations/<version>_create_<plural>.{up,down}.sql`.
+
+`--full` swaps in a CRUD skeleton instead: list/get/create/update/delete
+already routed and wired, with DTO fields and business rules left as TODOs.
+With OpenAPI enabled it also writes `docs/<plural>/{collection,item,schemas}.yaml`
+and wires them into `docs/openapi.yaml`. Use it only when a full CRUD surface
+is actually intended — otherwise prefer minimal plus explicit `generate method`
+calls.
+
+`--auth` puts the module's routes behind a valid access token (requires
+`go-scaffold add auth` in this project first). `--permission <code>` also
+requires that permission via `authz.Require` and seeds it in its own
+migration — it needs `add rbac`, and `--auth` must be passed alongside it.
+
+There's no per-domain versioning — the route prefix is a single
+project-wide choice made at `create` time.
 
 ### `generate method <module> <name>`
 
@@ -72,11 +95,35 @@ and shape depend on `--type`:
 | `--type` | Route | Notes |
 |---|---|---|
 | `get --get-mode all` | `GET /<plural>/<kebab-name>` | list-style, reuses `FindAll` — TODO to add real filtering |
-| `get --get-mode one --field <f>` | `GET /<plural>/<f>/:<f>` | adds a real `FindBy<F>` query to the repository (and its `repository` interface + `fakeRepo` test stub); `--field` can't be `id` |
+| `get --get-mode one --field <f>` | `GET /<plural>/<f>/:<f>` | adds a real `FindBy<F>` query to the repository (and its `repository` interface + `repositoryStub` test stub); `--field` can't be `id` |
 | `post` | `POST /<plural>/<kebab-name>` | adds a body DTO; service body is a TODO stub (`apperror.NewInternal()` until implemented) |
 | `put` / `patch` | `<VERB> /<plural>/:id/<kebab-name>` | finds the record by id, TODO before saving (safe no-op until implemented) |
 | `delete` | `DELETE /<plural>/:id/<kebab-name>` | TODO stub (`apperror.NewInternal()` until implemented) |
 
+### `generate migration <name>`
+
+Reserves a timestamped `migrations/<version>_<name>.{up,down}.sql` pair,
+both TODO stubs — the CLI doesn't guess at columns, you write the SQL. This
+is the way to make any schema change that isn't a new module: adding a
+column, an index, a foreign key, a backfill, a drop.
+
+### `undo module <name>`
+
+For a `generate module` that shouldn't have happened — a typo'd name, a
+domain decided against. Deletes `internal/app/<pkg>/`, the module's
+`migrations/<version>_create_<plural>.{up,down}.sql` pair, and reverses
+everything `generate module` wired up in `cmd/api/wiring.go` (and in
+`docs/openapi.yaml` + `docs/<plural>/` when OpenAPI is enabled). `-y` skips
+the confirmation prompt.
+
+The migration files go because `migrations/embed.go` is a `//go:embed *`: a
+typo's migration left behind runs on every database created from then on.
+That's only safe while those files exist nowhere else, so `undo` refuses —
+deleting nothing — when they're committed to git, or when the database is
+already at or past that version. Neither is a bug to work around: a domain
+that has shipped is retired with `generate migration drop_<table>` and a
+reviewed data removal, not with this command. The table is never dropped.
+
 What you still do by hand: real field names on the model/DTOs (the generated
 ones are placeholders), any foreign key to another domain (see
 `docs/architect/patterns.md` for the 3 rules), and the actual business logic

package/templates/create/base/.dockerignore.hbs

@@ -0,0 +1,13 @@
+# Everything the build stage doesn't need. Keeping the context small is most of
+# what makes `docker build` fast on a repeat run.
+.git
+.github
+bin
+docs
+*.md
+.env
+.env.*
+!.env.example
+docker-compose.yml
+Dockerfile
+.dockerignore

package/templates/create/base/.env.example.hbs

@@ -11,17 +11,26 @@ DB_MAX_OPEN_CONNS=10
 DB_MAX_IDLE_CONNS=10
 DB_CONN_MAX_LIFETIME_MIN=5
 
-# read only by `go test`, never by cmd/api — a separate database on purpose: the
-# integration-test harness does DropTable+AutoMigrate on every run, which would
-# otherwise wipe the schema `make migrate-up` built in DB_DSN above.
-# Create it once: make db-create DB_NAME={{dbName}}_test
+# read only by `go test`, never by cmd/api — a separate database on purpose:
+# repository tests run inside a transaction that's always rolled back (see
+# repositoryDBForTest in any repository_test.go), so nothing here ever
+# persists — but keeping it separate from DB_DSN above is cheap insurance
+# against a migration state mismatch or a future test that forgets to roll
+# back. Create it once: make db-create DB_NAME={{dbName}}_test
+# then apply the same migrations DB_DSN above got: make migrate-up-test
 TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable
 
+# with TEST_DB_DSN unset, repository tests skip themselves — convenient locally,
+# a false green in CI. REQUIRE_TEST_DB=true turns that skip into a failure, so a
+# missing or unmigrated test database is reported instead of quietly halving the
+# suite. CI sets it; leave it off locally unless you want the same strictness.
+# REQUIRE_TEST_DB=true
+
 # comma-separated frontend origins allowed to call this API with credentials (cookies)
 CORS_ALLOWED_ORIGINS=http://localhost:3000
-{{#if observability}}
 
-# OTLP/HTTP endpoint for trace export (e.g. localhost:4318) — empty disables
-# tracing entirely: no exporter is created, no network calls are made
-OTEL_EXPORTER_OTLP_ENDPOINT=
-{{/if}}
+# comma-separated CIDRs of the proxies in front of this app (load balancer,
+# ingress, CDN). Empty = trust nobody, so c.ClientIP() is the peer address.
+# Leave it empty unless you actually run behind a proxy: anything listed here
+# is allowed to set X-Forwarded-For, and the auth rate limiter keys on that.
+TRUSTED_PROXIES=

package/templates/create/base/.github/dependabot.yml.hbs

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  # Go dependencies drift quietly: nothing fails, the project just ages until
+  # an upgrade becomes a project of its own. Weekly PRs keep each bump small
+  # enough to read, and CI already builds, vets, lints and tests every one.
+  - package-ecosystem: gomod
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      # one PR for the routine patch/minor churn; majors stay separate so
+      # they get read properly
+      go-minor-and-patch:
+        update-types: [minor, patch]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

package/templates/create/base/.github/workflows/ci.yml.hbs

@@ -41,10 +41,20 @@ jobs:
 
       - uses: golangci/golangci-lint-action@v6
         with:
-          version: latest
+          # keep in step with GOLANGCI_LINT_VERSION in the Makefile, so a rule
+          # that passes locally passes here too
+          version: v2.12.2
 
+{{#if openapiDocs}}
+      # catches a broken $ref or malformed spec before it reaches anyone
+      # pointing a client generator or Scalar/Swagger UI at this file — those
+      # tools often fail with a much less specific error than this gives.
+      - name: Lint OpenAPI spec
+        run: npx --yes @redocly/cli lint docs/openapi.yaml
+
+{{/if}}
       - name: Install migration runner
-        run: go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.3
+        run: go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.19.1
 
       - name: Apply production migrations to the test database
         env: