@nakedev/go-scaffold 0.1.3 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pranob Onphaeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,9 +2,9 @@
 
 A CLI that scaffolds a Gin + GORM + PostgreSQL Go backend, then keeps
 generating consistent domain modules into that project as it grows — the Go
-counterpart to [nest-scaffold](../nest-scaffold).
+counterpart to nest-scaffold.
 
-You don't hand-wire a new domain into `cmd/api/main.go`, write the
+You don't hand-wire a new domain into `cmd/api/wiring.go`, write the
 handler/service/repository boilerplate, or decide error-handling conventions
 each time — the CLI does that, and every module it generates follows the
 same shape as the last one.
@@ -52,6 +52,11 @@ go-scaffold generate method orders approve --type patch
 
 ## Commands
 
+Every `add` command shows what it's about to do and asks before writing;
+`-y/--yes` skips that (and `--defaults` implies it) for CI and scripts.
+Running `go-scaffold` with no arguments picks the command from a menu.
+
+
 ### `create <name>` — scaffold a new project
 
 ```bash
@@ -61,19 +66,20 @@ go-scaffold create my-api --defaults --no-docker --api-prefix beta
 ```
 
 Produces a **bare skeleton only** — `cmd/api`, the shared platform packages
-(config/apperror/dberr/httpx/id/middleware/pagination), Docker+Postgres,
+(config/apperror/dberr/httpx/id/middleware/pagination/tx), Docker+Postgres,
 migrations folder, and the standards docs (`docs/architect/`, `AGENTS.md`,
 `CLAUDE.md`, `.claude/skills/go-scaffold/`). No domain modules — add those
 with `generate module`.
 
 | Option | Effect |
 |---|---|
-| `--defaults` | Skip the wizard, use defaults (Docker on, OpenAPI docs on, prefix `v1`) |
+| `--defaults` | Skip the wizard, use defaults (Docker on, OpenAPI docs on, no route prefix) |
 | `--no-docker` | Skip `docker-compose.yml` (with `--defaults`) |
 | `--no-openapi-docs` | Skip `docs/openapi.yaml` (with `--defaults`) |
-| `--api-prefix <prefix>` | URL prefix every route is grouped under (with `--defaults`; default `v1`, `""` for none, `/`-separated segments like `api/v1` are fine) |
+| `--observability` | Prometheus `/metrics` + OpenTelemetry tracing (with `--defaults`; off by default — `add observability` does the same later) |
+| `--api-prefix <prefix>` | URL prefix every route is grouped under — opt in with e.g. `v1` or `api/v1`; omit it for none |
 
-Without `--defaults`, an interactive wizard asks the same three questions.
+Without `--defaults`, an interactive wizard asks the same four questions.
 The prefix is a single project-wide choice made once at `create` time —
 there's no per-domain versioning (a domain that needs a real breaking change
 gets a new domain package or a new DTO field, not a duplicated model pointed
@@ -87,25 +93,30 @@ directory layout if missing).
 ### `generate module <name>` (alias `m`) — add a domain module
 
 ```bash
-go-scaffold generate module orders                  # full CRUD (default)
-go-scaffold generate module orders --no-full         # minimal skeleton — add endpoints with `generate method`
+go-scaffold generate module orders                  # asks for the shape (and auth, if installed)
+go-scaffold generate module orders --full           # opt-in CRUD skeleton, no prompt
+go-scaffold generate module orders --defaults       # safe minimal module, no prompt (CI/scripting)
 ```
 
-Full CRUD (default) scaffolds:
+Anything you don't pass as a flag is asked for; `--defaults` takes the
+documented defaults (minimal, no auth) and asks nothing.
+
+`--full` scaffolds:
 
 ```text
-internal/app/orders/
+internal/app/order/
 ├── model/model.go      # domain model + GORM table (id/created_at/updated_at — add real fields yourself; a folder so multi-table domains can add more files)
 ├── dto.go               # request/response structs (empty stubs — add real fields yourself)
-├── errors.go             # ORDERS_NOT_FOUND / ORDERS_CONFLICT / ORDERS_HAS_REFERENCES
+├── errors.go             # ORDER_NOT_FOUND / ORDER_CONFLICT / ORDER_HAS_REFERENCES / ORDER_STALE
 ├── repository.go         # GORM data access
 ├── service.go            # business logic + repository interface (mockable)
 ├── handler.go            # Gin routes, registered under the project's API prefix
-├── service_test.go       # unit test, fake repo
-└── handler_test.go       # integration test, real Postgres, tx rollback
+├── service_test.go       # unit test, function-backed repository stub
+├── handler_test.go       # HTTP unit test, service stub, no DB
+└── repository_test.go    # Postgres integration test against migrated schema
 ```
 
-`--no-full` scaffolds the same `model`/`errors`/`repository` (so `generate
+The default minimal mode scaffolds the same `model`/`errors`/`repository` (so `generate
 method` always has a full data-access surface to call), but `dto`/`service`/
 `handler` start empty — no default CRUD, no routes, just the plumbing
 (`Register()`, the `repository` interface, `wrapFindErr`) that `generate
@@ -114,11 +125,13 @@ surface, or you'd rather add endpoints one at a time.
 
 Both modes also:
 
-- Register the module in `cmd/api/main.go` (via marker comments — see
+- Register the module in `cmd/api/wiring.go` (via marker comments — see
   `// go-scaffold:*` in that file) — full wires an actual route, minimal
   wires an empty route group
-- Add the model to the `AutoMigrate(...)` call
-- Append `migrations/<seq>_create_<plural>.{up,down}.sql`
+- Create the module's own Postgres schema (`<module>_svc`, e.g. `order_svc`)
+  and add the model to the `AutoMigrate(...)` call
+- Append `migrations/<timestamp>_create_<plural>.{up,down}.sql`, which creates that
+  same schema for `AUTO_MIGRATE=false`/production
 
 What it does **not** do: invent your fields or wire foreign keys between
 domains — see `docs/architect/patterns.md` in the generated project for the
@@ -145,7 +158,7 @@ overwrites a method with the same name; picks a different one or errors.
 | `--type` | Route | What's generated |
 |---|---|---|
 | `get --get-mode all` | `GET /<plural>/<kebab-name>` | reuses `FindAll` — TODO to add real filtering |
-| `get --get-mode one --field <f>` | `GET /<plural>/<f>/:<f>` | a real `FindBy<F>` query added to the repository (+ its interface + `fakeRepo` test stub) |
+| `get --get-mode one --field <f>` | `GET /<plural>/<f>/:<f>` | a real `FindBy<F>` query added to the repository (+ its interface + function-backed repository test stub) |
 | `post` | `POST /<plural>/<kebab-name>` | adds a body DTO; service is a TODO stub |
 | `put` / `patch` | `<VERB> /<plural>/:id/<kebab-name>` | finds by id, TODO before saving (safe no-op until implemented) |
 | `delete` | `DELETE /<plural>/:id/<kebab-name>` | TODO stub |
@@ -154,8 +167,9 @@ Business logic is always left as a `TODO`-marked stub that compiles and
 returns a clean `500` rather than inventing behavior — see
 `docs/architect/patterns.md` in the generated project.
 
-`generate method` prints the route it added but does **not** touch
-`docs/openapi.yaml` — endpoint-specific spec entries stay hand-written.
+When OpenAPI docs are enabled, `generate method` also creates a valid TODO stub
+under `docs/<plural>/methods/` and wires the route into `docs/openapi.yaml`.
+Replace its placeholder request/response schemas while implementing the TODO.
 
 **Drift check** — `generate` type-checks the project (`go vet ./...`) before and
 after it writes. If the project was fine beforehand and the generated code
@@ -190,26 +204,75 @@ Creates timestamped `migrations/<version>_<name>.up.sql` and `.down.sql` TODO
 stubs. The CLI reserves the names; you own the SQL and should apply it with
 `make migrate-up` (or `migrate -path migrations -database "$DB_DSN" up`).
 
-### `add worker` — add Redis-backed background work
+### `add worker` — add background job processing
 
 ```bash
-go-scaffold add worker
+go-scaffold add worker                      # asks where jobs should live
+go-scaffold add worker --queue postgres     # River (default)
+go-scaffold add worker --queue redis        # Asynq
+go-scaffold add worker --defaults           # no prompt, Postgres
 ```
 
-Adds Redis cache/queue support, async email delivery, and `cmd/worker`. It also
-makes `/readyz` report unavailable when Redis is down. Run `go mod tidy` and
-provide `REDIS_URL` before starting the API or worker.
+Adds `internal/platform/queue` (a backend-neutral contract plus one adapter),
+async email delivery, and `cmd/worker`.
+
+| | `--queue postgres` (River) | `--queue redis` (Asynq) |
+|---|---|---|
+| Extra service to run | none | Redis |
+| Needed by `add auth` | no | no — `add auth --store` decides that separately |
+| Enqueue joins your DB transaction | yes | **no** — needs an outbox |
+| Throughput | thousands/sec | tens of thousands/sec |
+| Inspect pending jobs | plain SQL | asynqmon |
+
+The default is Postgres because a job enqueued inside `tx.Do` is then only
+delivered if that transaction commits — no more welcome emails for signups
+that rolled back. Run `make river-migrate` once per database to create
+River's tables, then `make worker`.
+
+Application code only ever sees `queue.Job`, `queue.Enqueuer` and
+`queue.Handler` — no backend package appears outside its own adapter file, so
+switching later means writing one adapter, not touching every module that
+enqueues something.
+
+```go
+type WelcomeEmail struct{ To string `json:"to"` }
+func (WelcomeEmail) Kind() string { return "email:welcome" }
+
+// cmd/api — the job is discarded with the transaction if this fails
+tx.Do(ctx, db, func(ctx context.Context) error {
+    if err := repo.Create(ctx, u); err != nil { return err }
+    return jobs.Enqueue(ctx, WelcomeEmail{To: u.Email}, nil)
+})
+```
 
 ### `add auth` — add email/password authentication
 
 ```bash
-go-scaffold add auth
+go-scaffold add auth                    # asks where tokens should live, then confirms
+go-scaffold add auth --store postgres   # tokens in Postgres, no extra service
+go-scaffold add auth --store redis      # tokens in Redis, exact across replicas
+go-scaffold add auth --defaults         # Postgres, no prompt at all (CI/scripting)
 ```
 
-Requires `add worker`. Adds JWT access tokens, Redis-backed refresh-token
-rotation, registration/login/logout, password reset, email verification, and
-Google OAuth routes. Apply the generated migrations; `AUTO_MIGRATE=true` is
-convenient in development, while production should use `migrate up`.
+Adds JWT access tokens, refresh-token rotation with reuse detection,
+registration/login/logout, password reset, email verification, failed-login
+lockout, and Google OAuth routes. Apply the generated migrations;
+`AUTO_MIGRATE=true` is convenient in development, while production should use
+`migrate up`.
+
+No prerequisites. On a project with no worker the verification and reset mail
+is sent inline, and `add worker` later moves it onto the queue for you — the
+two endpoints that send mail block on SMTP until you do.
+
+| `--store` | Tokens and rate-limit counters | Extra service |
+|---|---|---|
+| `postgres` (default) | `user_svc.auth_tokens`, counters in-process | none |
+| `redis` | Redis | Redis |
+
+The rate limiter follows the store rather than being chosen separately, because
+"I want this exact across replicas" is one decision. With `postgres` the per-IP
+budget is per-replica; the failed-login lockout is in Postgres either way, since
+that one can't be approximate.
 
 ### `add rbac` — add roles and permissions
 
@@ -223,29 +286,51 @@ middleware, and role assignment. Its migration seeds the default roles and
 permissions, so apply it with `migrate up`: AutoMigrate creates tables but does
 not run SQL seed statements.
 
-### Observability at project creation
+### `add observability` — add metrics + tracing
 
 ```bash
-go-scaffold create my-api --defaults --observability
+go-scaffold add observability                          # on an existing project
+go-scaffold create my-api --defaults --observability    # or at creation time
 ```
 
-Opt-in observability adds Prometheus metrics at `/metrics` and OpenTelemetry
-tracing. Tracing is disabled until `OTEL_EXPORTER_OTLP_ENDPOINT` is configured.
+Adds Prometheus metrics at `/metrics` and OpenTelemetry tracing for Gin +
+GORM, patched into `cmd/api/wiring.go` and `internal/platform/database` the same
+way `add worker`/`add auth`/`add rbac` patch an existing project. Tracing is
+disabled until `OTEL_EXPORTER_OTLP_ENDPOINT` is configured; `/metrics` works
+either way. `create --observability` is exactly this command run right after
+scaffolding — the two produce the same project.
 
-### `remove module <name>` (alias `rm m`) — drop a domain
+### `undo module <name>` (alias `undo m`) — take back a `generate module`
 
 ```bash
-go-scaffold remove module orders          # confirms first
-go-scaffold rm m orders --yes             # skip the confirm
+go-scaffold undo module orders          # confirms first
+go-scaffold undo m orders --yes         # skip the confirm
 ```
 
-The inverse of `generate module`: deletes `internal/app/<name>/` and reverses
-everything that was wired up — the import/AutoMigrate/route in `main.go`, the
-paths/schemas in `docs/openapi.yaml`, the per-module docs folder, and the
-`create_<plural>` migration. Restores the `_ = api` placeholder if it was the
-last module, so the project still builds. Use this instead of hand-deleting
-the folder — a partial hand-delete leaves stale wiring that duplicates on the
-next `generate module` (which would panic gin at startup).
+The inverse of `generate module`, for the case it's actually the inverse of:
+a module you didn't mean to generate — a typo'd name, a domain you decided
+against. It deletes `internal/app/<name>/`, the per-module docs folder, **and
+the module's migration files**, and reverses the import/AutoMigrate/route in
+`main.go` plus the paths/schemas in `docs/openapi.yaml`. Restores the
+`_ = api` placeholder if it was the last module, so the project still builds.
+
+Deleting the migrations is the point. `migrations/embed.go` is a `//go:embed
+*`, so a typo'd `create_oders` left behind once ran on every database created
+from then on. That's only safe while those files exist nowhere but your
+working tree, so `undo` proves it first and refuses loudly otherwise:
+
+- **any of them is tracked by git** — it may already have been pulled or
+  deployed somewhere, so nothing is deleted. Retire that domain the explicit
+  way instead: `go-scaffold generate migration drop_<name>`.
+- **your database is already at or past that version** (read via the `migrate`
+  CLI when it's on `PATH` and a DSN is configured) — deleting the files would
+  strand `schema_migrations` at a version with no migration behind it. Run
+  `migrate ... down` first, then try again.
+
+The table itself is never dropped either way — `undo` only reverses what the
+CLI wrote. Prefer it to hand-deleting the folder: it also un-wires `main.go`,
+`.golangci.yml` and the OpenAPI index, and it refuses when another domain
+still imports this one rather than leaving you an un-compilable project.
 
 ## Why no per-domain versioning
 
@@ -261,7 +346,7 @@ and `float64` in the other for the *same* column, converging it to
 data with different, silently incompatible interpretations.
 
 Instead, every route in a project is grouped under a single project-wide
-`--api-prefix` (default `v1`) chosen once at `create` time. A domain that
+`--api-prefix` chosen once at `create` time — opt-in, no prefix unless you ask. 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 a table it can drift
 out of sync with.
@@ -269,10 +354,10 @@ out of sync with.
 ## Project structure produced by `create`
 
 ```text
-cmd/api/main.go
+cmd/api/wiring.go
 internal/
 ├── platform/database/
-├── shared/{config,apperror,dberr,httpx,id,middleware,pagination}/
+├── shared/{config,apperror,dberr,httpx,id,middleware,pagination,tx}/
 └── app/                      # empty until you `generate module`
 docs/
 ├── architect/{architecture,patterns,techstack}.md
@@ -280,8 +365,13 @@ docs/
 migrations/
 .github/workflows/ci.yml    # build, vet, gofmt check, golangci-lint, go test (with a Postgres service)
 Makefile
+.env.example
+.gitignore
 .golangci.yml
+redocly.yaml                # if openapi docs enabled
+docker-compose.yml          # if Docker enabled
 .vscode/settings.json
+README.md
 AGENTS.md
 CLAUDE.md
 .claude/skills/go-scaffold/SKILL.md
@@ -290,11 +380,14 @@ go-scaffold.config.json
 
 ## Supported stack
 
+Pinned in the generated `go.mod` — this table mirrors
+`templates/create/base/go.mod.hbs`, which is the source of truth.
+
 | Package | Version |
 |---|---|
-| Gin | v1.10.0 |
-| GORM + postgres driver | v1.25.12 / v1.5.9 |
-| validator/v10 | v10.20.0 |
+| Gin | v1.10.1 |
+| GORM + postgres driver | v1.31.2 / v1.6.2 |
+| validator/v10 | v10.30.3 |
 | google/uuid | v1.6.0 |
 
 ## License

package/dist/commands/auth.js

@@ -11,8 +11,13 @@ const config_1 = require("../utils/config");
 const template_renderer_1 = require("../utils/template-renderer");
 const auth_manifest_1 = require("../templates/auth-manifest");
 const auth_patcher_1 = require("../utils/auth-patcher");
+const platform_patcher_1 = require("../utils/platform-patcher");
+const worker_manifest_1 = require("../templates/worker-manifest");
+const golangci_patcher_1 = require("../utils/golangci-patcher");
 const migrations_1 = require("../utils/migrations");
 const openapi_patcher_1 = require("../utils/openapi-patcher");
+const gocheck_1 = require("../utils/gocheck");
+const gomod_patcher_1 = require("../utils/gomod-patcher");
 // URL (relative to the api prefix) -> docs file (relative to docs/) for every
 // route `add auth` registers — kept next to AUTH_FILES's route list so the
 // two are easy to eyeball together when a route changes.
@@ -36,16 +41,29 @@ const AUTH_OPENAPI_PATHS = [
 // (no roles/permissions) — that's a separate opt-in on top of this, since
 // most projects need "is this caller logged in" long before they need "can
 // this caller do X".
-async function addAuth(projectDir = process.cwd()) {
+async function addAuth(store = "postgres", projectDir = process.cwd()) {
     const config = (0, config_1.readConfig)(projectDir);
-    if (!config.features.worker) {
-        throw new Error("`go-scaffold add auth` requires `go-scaffold add worker` first — the refresh token store needs Redis");
-    }
+    // No longer a prerequisite. Without a worker the verification and reset mail
+    // goes out inline instead of through a queue — a real trade (those two
+    // endpoints then block on SMTP), but not one worth forcing a second binary
+    // and a queue-backend decision on someone who only wanted login.
+    const worker = config.features.worker ?? false;
     const userDir = path_1.default.join(projectDir, "internal", "app", "user");
     if (fs_extra_1.default.existsSync(userDir)) {
         throw new Error(`${userDir} already exists — auth looks like it's already been added`);
     }
-    await (0, template_renderer_1.applyTemplateEntries)(projectDir, auth_manifest_1.AUTH_FILES, { goModule: config.goModule });
+    const parsedBefore = (0, gocheck_1.parseChecks)(projectDir);
+    // Only `--store redis` needs Redis. With `--store postgres` (the default)
+    // auth adds no service at all — which is the whole point of the option.
+    if (store === "redis")
+        await ensureRedis(projectDir, config.goModule);
+    // the SMTP client, and the config it reads, normally arrive with `add worker`
+    if (!worker) {
+        await (0, template_renderer_1.applyTemplateEntries)(projectDir, worker_manifest_1.MAIL_CLIENT_ONLY, { goModule: config.goModule });
+        (0, platform_patcher_1.patchConfigForSMTP)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"));
+        patchEnvExampleForSMTP(path_1.default.join(projectDir, ".env.example"));
+    }
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, (0, auth_manifest_1.authFiles)(store), { goModule: config.goModule });
     const migrationsDir = path_1.default.join(projectDir, "migrations");
     fs_extra_1.default.ensureDirSync(migrationsDir);
     const usersVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
@@ -62,8 +80,35 @@ async function addAuth(projectDir = process.cwd()) {
         { template: "add/auth/migrations/create_identities.up.sql.hbs", output: path_1.default.join("migrations", `${identitiesVersion}_create_identities.up.sql`) },
         { template: "add/auth/migrations/create_identities.down.sql.hbs", output: path_1.default.join("migrations", `${identitiesVersion}_create_identities.down.sql`) },
     ], {});
+    // the failed-attempt counter is not a store choice — lockout has to survive a
+    // deploy and mean the same thing on every replica whichever store holds tokens
+    const throttleVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_login_throttle.up.sql.hbs", output: path_1.default.join("migrations", `${throttleVersion}_create_login_throttle.up.sql`) },
+        { template: "add/auth/migrations/create_login_throttle.down.sql.hbs", output: path_1.default.join("migrations", `${throttleVersion}_create_login_throttle.down.sql`) },
+    ], {});
+    if (store === "postgres") {
+        const authTokensVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+        await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+            { template: "add/auth/migrations/create_auth_tokens.up.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.up.sql`) },
+            { template: "add/auth/migrations/create_auth_tokens.down.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.down.sql`) },
+        ], {});
+    }
+    (0, golangci_patcher_1.patchGolangciForModule)(path_1.default.join(projectDir, ".golangci.yml"), config.goModule, "user");
     (0, auth_patcher_1.patchConfigForAuth)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"));
-    (0, auth_patcher_1.patchMainGoForAuth)(path_1.default.join(projectDir, "cmd", "api", "main.go"), config.goModule);
+    (0, auth_patcher_1.patchMainGoForAuth)(path_1.default.join(projectDir, "cmd", "api", "wiring.go"), {
+        goModule: config.goModule,
+        queueBackend: config.features.queue ?? "asynq",
+        store,
+        worker,
+    });
+    (0, gomod_patcher_1.patchGoModRequires)(path_1.default.join(projectDir, "go.mod"), [
+        "github.com/golang-jwt/jwt/v5 v5.3.1",
+        "golang.org/x/crypto v0.52.0",
+        "golang.org/x/oauth2 v0.36.0",
+        // go-redis only when something in this project actually constructs a client
+        ...(store === "redis" ? ["github.com/redis/go-redis/v9 v9.22.0"] : []),
+    ]);
     patchEnvExample(path_1.default.join(projectDir, ".env.example"));
     patchMakefile(path_1.default.join(projectDir, "Makefile"));
     let docsMessage = "";
@@ -81,10 +126,20 @@ async function addAuth(projectDir = process.cwd()) {
         docsMessage = "\ndocs: docs/auth/*.yaml, wired into docs/openapi.yaml";
     }
     (0, template_renderer_1.gofmtTree)(projectDir);
-    (0, config_1.writeConfig)(projectDir, { ...config, features: { ...config.features, auth: true } });
+    // parse-only: jwt/oauth2/bcrypt aren't in go.mod until the `go mod tidy`
+    // printed below, so `go vet` can't be the gate here.
+    (0, gocheck_1.assertStillParses)(projectDir, parsedBefore, "added auth");
+    (0, config_1.writeConfig)(projectDir, { ...config, features: { ...config.features, auth: true, authStore: store } });
     console.log(picocolors_1.default.green("\nadded internal/app/user/, internal/shared/middleware/auth.go, and cmd/seed"));
-    console.log("registered POST /auth/{register,login,refresh,logout,forgot-password,reset-password}, " +
-        "GET /auth/google/{login,callback}, and GET /users/me in cmd/api/main.go" +
+    console.log(worker
+        ? "verification + password-reset mail goes through the queue"
+        : "verification + password-reset mail is sent inline (no worker) — run `add worker` later to move it onto the queue");
+    console.log(store === "postgres"
+        ? "tokens + rate-limit counters: Postgres (user_svc.auth_tokens) and in-process — no Redis"
+        : "tokens + rate-limit counters: Redis");
+    console.log("registered POST /auth/{register,login,refresh,logout,forgot-password,reset-password,verify-email}, " +
+        "GET /auth/google/{login,callback}, GET /users/me, and " +
+        "POST /users/me/{resend-verification,logout-all} in cmd/api/wiring.go" +
         docsMessage);
     console.log(picocolors_1.default.dim("\nnext: go mod tidy, then apply the new migrations (AUTO_MIGRATE=true picks them up automatically in dev)\n" +
         "seed an admin: SEED_ADMIN_EMAIL=... SEED_ADMIN_PASSWORD=... make seed"));
@@ -100,8 +155,14 @@ function patchMakefile(makefilePath) {
         "# environment, not .env, so a real secret never sits in a checked-in file.\n" +
         "# --fixtures adds throwaway dev sample users, never use it outside dev.\n" +
         "seed:\n" +
-        "\t@[ -f .env ] && export $$(grep -v '^#' .env | sed -E 's/[[:space:]]+#.*$//' | xargs); go run ./cmd/seed $(ARGS)\n";
-    content = content.replace(/\nbuild:/, `${target}\nbuild:`);
+        // `$$` throughout: make expands a single `$` as a variable reference, so
+        // `$//` became `//` and left sed an unterminated s/// expression — the
+        // recipe then failed, `.env` never loaded, and a bare `export` dumped the
+        // whole environment. Matches every target in Makefile.hbs verbatim.
+        "\t@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; go run ./cmd/seed $(ARGS)\n";
+    // Function replacer — target contains a literal "$$", see worker.ts's
+    // patchMakefile for why a string replacement would silently mangle it.
+    content = content.replace(/\nbuild:/, () => `${target}\nbuild:`);
     fs_extra_1.default.writeFileSync(makefilePath, content);
 }
 function patchEnvExample(envExamplePath) {
@@ -117,6 +178,12 @@ function patchEnvExample(envExamplePath) {
             "JWT_ACCESS_TTL_MIN=15\n" +
             "JWT_REFRESH_TTL_MIN=43200\n" +
             "COOKIE_SECURE=false\n" +
+            "# strict | lax | none — the refresh cookie's SameSite. Keep strict while the\n" +
+            "# frontend is the same site as this API (localhost:3000 -> localhost:8080 is,\n" +
+            "# and so is app.example.com -> api.example.com). A frontend on a different\n" +
+            "# site entirely needs none, together with COOKIE_SECURE=true, or the browser\n" +
+            "# never sends the cookie to /auth/refresh and sessions die at every expiry.\n" +
+            "COOKIE_SAMESITE=strict\n" +
             "\nPASSWORD_RESET_TTL_MIN=30\n" +
             "PASSWORD_RESET_URL=http://localhost:3000/reset-password\n" +
             "\nEMAIL_VERIFY_TTL_MIN=1440\n" +
@@ -127,3 +194,41 @@ function patchEnvExample(envExamplePath) {
             "GOOGLE_REDIRECT_URL=\n";
     fs_extra_1.default.writeFileSync(envExamplePath, content);
 }
+// ensureRedis adds internal/platform/cache + its config/env/main.go wiring
+// when the project doesn't have Redis yet — which is the normal case once
+// the queue lives in Postgres. Idempotent: a project whose queue is Redis
+// already has all of this and nothing happens.
+async function ensureRedis(projectDir, goModule) {
+    const cacheGo = path_1.default.join(projectDir, "internal", "platform", "cache", "redis.go");
+    if (fs_extra_1.default.existsSync(cacheGo))
+        return;
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [{ template: "add/worker/internal/platform/cache/redis.go.hbs", output: "internal/platform/cache/redis.go" }], { goModule });
+    (0, platform_patcher_1.patchConfigForRedis)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"));
+    (0, platform_patcher_1.patchMainGoForWorker)(path_1.default.join(projectDir, "cmd", "api", "wiring.go"), goModule);
+    (0, platform_patcher_1.patchComposeForRedis)(path_1.default.join(projectDir, "docker-compose.yml"));
+    (0, platform_patcher_1.patchCiForRedis)(path_1.default.join(projectDir, ".github", "workflows", "ci.yml"));
+    const envExamplePath = path_1.default.join(projectDir, ".env.example");
+    if (fs_extra_1.default.existsSync(envExamplePath)) {
+        const content = fs_extra_1.default.readFileSync(envExamplePath, "utf8");
+        if (!content.includes("REDIS_URL")) {
+            fs_extra_1.default.writeFileSync(envExamplePath, content.replace(/\n?$/, "\n") + "\n# refresh-token store\nREDIS_URL=redis://localhost:6379/0\n");
+        }
+    }
+}
+// patchEnvExampleForSMTP mirrors `add worker`'s own SMTP block, for the case
+// where auth installed the mail client without a worker. Same append-once
+// shape as every other env patcher.
+function patchEnvExampleForSMTP(envExamplePath) {
+    if (!fs_extra_1.default.existsSync(envExamplePath))
+        return;
+    const content = fs_extra_1.default.readFileSync(envExamplePath, "utf8");
+    if (content.includes("SMTP_HOST"))
+        return;
+    fs_extra_1.default.writeFileSync(envExamplePath, content.replace(/\n?$/, "\n") +
+        "\n# leave SMTP_HOST unset to log emails instead of sending them (dev default)\n" +
+        "SMTP_HOST=\n" +
+        "SMTP_PORT=587\n" +
+        "SMTP_USERNAME=\n" +
+        "SMTP_PASSWORD=\n" +
+        "SMTP_FROM=no-reply@example.local\n");
+}

package/dist/commands/create.js

@@ -13,6 +13,7 @@ const config_1 = require("../utils/config");
 const naming_1 = require("../utils/naming");
 const create_wizard_1 = require("../prompts/create-wizard");
 const version_1 = require("../utils/version");
+const observability_1 = require("./observability");
 async function createProject(rawName, opts) {
     const trimmed = (rawName ?? (await (0, create_wizard_1.promptProjectName)())).trim();
     if (!trimmed)
@@ -28,7 +29,11 @@ async function createProject(rawName, opts) {
     let apiPrefix;
     if (opts.defaults) {
         features = { docker: opts.docker ?? true, openapiDocs: opts.openapiDocs ?? true, observability: opts.observability ?? false };
-        apiPrefix = (0, naming_1.normalizeApiPrefix)(opts.apiPrefix ?? "v1");
+        // "" to match what the wizard's Enter now gives. --defaults means "don't
+        // ask me", not "give me something I didn't ask for", and a prefix is a
+        // project-wide decision you cannot change later without rewriting routes
+        // and every OpenAPI path.
+        apiPrefix = (0, naming_1.normalizeApiPrefix)(opts.apiPrefix ?? "");
         const check = (0, naming_1.validateApiPrefix)(apiPrefix);
         if (check !== true)
             throw new Error(check);
@@ -47,6 +52,13 @@ async function createProject(rawName, opts) {
     await (0, template_renderer_1.applyTemplateEntries)(projectDir, create_manifest_1.CREATE_MANIFEST, context);
     (0, template_renderer_1.gofmtTree)(projectDir);
     (0, config_1.writeConfig)(projectDir, { projectName, goModule, apiPrefix, features, scaffoldVersion: (0, version_1.cliVersion)() });
+    // Composed the same way a user would do it by hand — `create` always
+    // renders the plain base, then this layers the same patches `add
+    // observability` would apply on an existing project, so the two paths
+    // produce identical output.
+    if (features.observability) {
+        await (0, observability_1.addObservability)(projectDir, { silent: true });
+    }
     console.log(picocolors_1.default.green(`\ncreated ${projectName}/`));
     console.log(`\ncd ${projectName}`);
     if (features.docker)