@nakedev/go-scaffold 0.1.2 → 0.1.3

package/dist/utils/rbac-patcher.js

@@ -0,0 +1,277 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchAuthDocsForRbac = patchAuthDocsForRbac;
+exports.patchConfigForRbac = patchConfigForRbac;
+exports.patchUserModelForRbac = patchUserModelForRbac;
+exports.patchMiddlewareAuthForRbac = patchMiddlewareAuthForRbac;
+exports.patchUserJWTForRbac = patchUserJWTForRbac;
+exports.patchUserServiceForRbac = patchUserServiceForRbac;
+exports.patchUserServiceTestForRbac = patchUserServiceTestForRbac;
+exports.patchUserDTOForRbac = patchUserDTOForRbac;
+exports.patchUserHandlerForRbac = patchUserHandlerForRbac;
+exports.patchUserErrorsForRbac = patchUserErrorsForRbac;
+exports.patchMainGoForRbac = patchMainGoForRbac;
+exports.patchCmdSeedForRbac = patchCmdSeedForRbac;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const marker_patch_1 = require("./marker-patch");
+const IMPORT_MARKER = "// go-scaffold:imports";
+const MODEL_MARKER = "// go-scaffold:models";
+const CONFIG_FIELDS_MARKER = "// go-scaffold:config-fields";
+const CONFIG_LOAD_MARKER = "// go-scaffold:config-load";
+// patchAuthDocsForRbac adds `role` to the hand-written MeResponse schema in
+// docs/auth/schemas.yaml — same marker convention as the Go dto.go patch
+// (patchUserDTOForRbac), since GET/PATCH /users(/me) all serialize the same
+// model.User whether or not RBAC is installed.
+function patchAuthDocsForRbac(authSchemasYamlPath) {
+    if (!fs_extra_1.default.existsSync(authSchemasYamlPath))
+        return; // openapi docs feature disabled
+    let content = fs_extra_1.default.readFileSync(authSchemasYamlPath, "utf8");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "# go-scaffold:me-response-fields", "role: { type: string }", "role: { type: string }");
+    fs_extra_1.default.writeFileSync(authSchemasYamlPath, content);
+}
+// patchConfigForRbac adds the Authz permission-cache TTL — configurable
+// instead of the hardcoded 1 minute it started as, same marker-based
+// insertion patchConfigForAuth uses.
+function patchConfigForRbac(configGoPath) {
+    let content = fs_extra_1.default.readFileSync(configGoPath, "utf8");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_FIELDS_MARKER, "AuthzCacheTTL time.Duration", "AuthzCacheTTL time.Duration");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_LOAD_MARKER, 'AuthzCacheTTL: time.Duration(envInt("AUTHZ_CACHE_TTL_MIN", 1)) * time.Minute,', "AuthzCacheTTL: time.Duration");
+    fs_extra_1.default.writeFileSync(configGoPath, content);
+}
+// patchUserModelForRbac adds the Role column to model.User — default 'staff'
+// at the DB level (via the gorm tag), so every existing user-creation path
+// (Register, Google, cmd/seed) gets a sane role without each one needing to
+// set it explicitly.
+function patchUserModelForRbac(userModelPath) {
+    let content = fs_extra_1.default.readFileSync(userModelPath, "utf8");
+    const field = `Role string \`json:"role" gorm:"type:varchar(20);not null;default:'staff'"\``;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-fields", field, "Role string");
+    fs_extra_1.default.writeFileSync(userModelPath, content);
+}
+// patchMiddlewareAuthForRbac adds RoleKey + the Role claim to the shared
+// middleware's own accessClaims copy (see auth.go's own comment on why it's
+// duplicated, not imported, from the user package's claims type).
+function patchMiddlewareAuthForRbac(middlewareAuthPath) {
+    let content = fs_extra_1.default.readFileSync(middlewareAuthPath, "utf8");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:middleware-auth-keys", 'const RoleKey = "role"', 'RoleKey = "role"');
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:middleware-auth-claims", 'Role string `json:"role,omitempty"`', "Role string");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:middleware-auth-context", "c.Set(RoleKey, claims.Role)", "c.Set(RoleKey");
+    fs_extra_1.default.writeFileSync(middlewareAuthPath, content);
+}
+// patchUserJWTForRbac adds the Role claim to the access token: the claim
+// itself (accessClaims.Role), an extra issueAccessToken param, and the value
+// wired into the claims literal — three separate marker points because the
+// param list and the struct literal are formatted one-arg-per-line
+// specifically so a marker patch can extend either without reformatting.
+function patchUserJWTForRbac(jwtGoPath) {
+    let content = fs_extra_1.default.readFileSync(jwtGoPath, "utf8");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:jwt-claims", 'Role string `json:"role,omitempty"`', "Role string");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:issue-access-token-params", "role string,", "role string,");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:jwt-claims-values", "Role: role,", "Role: role,");
+    fs_extra_1.default.writeFileSync(jwtGoPath, content);
+}
+// patchUserServiceForRbac wires a role.Service dependency into user.Service
+// (via a consumer-side roleChecker interface, same convention as
+// repository/mailer/tokenStore) and adds SetRole, the one place a user's
+// role actually changes after creation.
+function patchUserServiceForRbac(serviceGoPath) {
+    let content = fs_extra_1.default.readFileSync(serviceGoPath, "utf8");
+    const roleCheckerInterface = [
+        "// roleChecker = what the service needs from the role domain to validate a",
+        "// role assignment — declared consumer-side, same convention as repository/mailer.",
+        "type roleChecker interface {",
+        "\tCodeExists(ctx context.Context, code string) (bool, error)",
+        "}",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-interfaces", roleCheckerInterface, "type roleChecker interface");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-fields", "roles roleChecker", "roles roleChecker");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-params", "roles roleChecker,", "roles roleChecker,");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-init", "roles: roles,", "roles: roles,");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:issue-access-token-args", "u.Role,", "u.Role,");
+    const setRoleMethod = [
+        "// SetRole assigns userID a new role — validated against the role catalog",
+        "// (not just the DB's FK) so a typo'd code fails with a clear 422 here",
+        "// instead of surfacing as an opaque FK-violation, and so AutoMigrate-only",
+        "// test schemas (which never create the FK) still reject it correctly.",
+        "func (s *Service) SetRole(ctx context.Context, userID uuid.UUID, roleCode string) (*model.User, error) {",
+        "\tu, err := s.repo.FindByID(ctx, userID)",
+        "\tif err != nil {",
+        "\t\tif errors.Is(err, gorm.ErrRecordNotFound) {",
+        "\t\t\treturn nil, errNotFound()",
+        "\t\t}",
+        "\t\treturn nil, apperror.NewInternal()",
+        "\t}",
+        "\texists, err := s.roles.CodeExists(ctx, roleCode)",
+        "\tif err != nil {",
+        "\t\treturn nil, apperror.NewInternal()",
+        "\t}",
+        "\tif !exists {",
+        "\t\treturn nil, errUnknownRole()",
+        "\t}",
+        "\tu.Role = roleCode",
+        "\tif err := s.repo.UpdateUser(ctx, u); err != nil {",
+        "\t\treturn nil, apperror.NewInternal()",
+        "\t}",
+        "\treturn u, nil",
+        "}",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-methods", setRoleMethod, "func (s *Service) SetRole(");
+    fs_extra_1.default.writeFileSync(serviceGoPath, content);
+}
+// patchUserServiceTestForRbac keeps service_test.go's single NewService call
+// site (newTestService) compiling once patchUserServiceForRbac adds the
+// roleChecker param above — same drift risk the handoff notes called out for
+// middleware.NewAuthz's call sites, just for this signature instead. The fake
+// itself is added here too, not pre-declared unconditionally in the
+// template: golangci-lint's unused check flags an unreferenced type+method
+// pair in the auth-only (pre-rbac) state, since nothing there yet implements
+// or needs a roleChecker.
+function patchUserServiceTestForRbac(serviceTestGoPath) {
+    let content = fs_extra_1.default.readFileSync(serviceTestGoPath, "utf8");
+    const fakeRoles = [
+        "// fakeRoles satisfies role's roleChecker interface structurally.",
+        "type fakeRoles struct{}",
+        "",
+        "func (fakeRoles) CodeExists(context.Context, string) (bool, error) { return true, nil }",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-test-types", fakeRoles, "type fakeRoles struct{}");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-test-args", "fakeRoles{},", "fakeRoles{},");
+    fs_extra_1.default.writeFileSync(serviceTestGoPath, content);
+}
+// patchUserDTOForRbac adds the request DTO for PATCH /users/:id/set-role and
+// surfaces Role on the /me response — both gated behind RBAC since
+// model.User has no Role field at all without it.
+function patchUserDTOForRbac(dtoGoPath) {
+    let content = fs_extra_1.default.readFileSync(dtoGoPath, "utf8");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-me-fields", 'Role string `json:"role"`', "Role string");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-me-values", "Role: u.Role,", "Role: u.Role,");
+    const setRoleInput = ["type setRoleInput struct {", '\tRole string `json:"role" binding:"required"`', "}"].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-dto", setRoleInput, "type setRoleInput struct");
+    fs_extra_1.default.writeFileSync(dtoGoPath, content);
+}
+// patchUserHandlerForRbac wires an *middleware.Authz into Handler and adds
+// the admin routes this PR ships: listing/viewing other users (PermUserRead)
+// and changing a user's role (PermUserManageRole). Suspending a user is a
+// separate concern, not RBAC's — see the role domain's own /roles,
+// /permissions for the actual role/permission management API.
+function patchUserHandlerForRbac(handlerGoPath, goModule) {
+    let content = fs_extra_1.default.readFileSync(handlerGoPath, "utf8");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-consts", 'const PermUserManageRole = "user:manage-role"', "PermUserManageRole");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-consts", 'const PermUserRead = "user:read"', "PermUserRead");
+    const paginationImport = `"${goModule}/internal/shared/pagination"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-imports", paginationImport, "internal/shared/pagination");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-fields", "authz *middleware.Authz", "authz *middleware.Authz");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-params", "authz *middleware.Authz,", "authz *middleware.Authz,");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-init", "authz: authz,", "authz: authz,");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-routes", 'usersGroup.GET("", h.authz.Require(PermUserRead), h.adminListUsers)', 'usersGroup.GET("", h.authz.Require(PermUserRead)');
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-routes", 'usersGroup.GET("/:id", h.authz.Require(PermUserRead), h.adminGetUser)', 'usersGroup.GET("/:id", h.authz.Require(PermUserRead)');
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-routes", 'usersGroup.PATCH("/:id/set-role", h.authz.Require(PermUserManageRole), h.setRole)', 'usersGroup.PATCH("/:id/set-role"');
+    const adminListHandler = [
+        "func (h *Handler) adminListUsers(c *gin.Context) {",
+        "\tp := pagination.Parse(c)",
+        "\titems, err := h.svc.List(c.Request.Context(), p.Limit, p.Offset)",
+        "\tif err != nil {",
+        "\t\tc.Error(err)",
+        "\t\treturn",
+        "\t}",
+        "\tout := make([]meResponse, len(items))",
+        "\tfor i := range items {",
+        "\t\tout[i] = toMeResponse(&items[i])",
+        "\t}",
+        "\tc.JSON(http.StatusOK, p.Response(out))",
+        "}",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-funcs", adminListHandler, "func (h *Handler) adminListUsers(");
+    const adminGetHandler = [
+        "func (h *Handler) adminGetUser(c *gin.Context) {",
+        "\tid, ok := httpx.ParseID(c)",
+        "\tif !ok {",
+        "\t\treturn",
+        "\t}",
+        "\tu, err := h.svc.Get(c.Request.Context(), id)",
+        "\tif err != nil {",
+        "\t\tc.Error(err)",
+        "\t\treturn",
+        "\t}",
+        "\tc.JSON(http.StatusOK, toMeResponse(u))",
+        "}",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-funcs", adminGetHandler, "func (h *Handler) adminGetUser(");
+    const setRoleHandler = [
+        "func (h *Handler) setRole(c *gin.Context) {",
+        "\tid, ok := httpx.ParseID(c)",
+        "\tif !ok {",
+        "\t\treturn",
+        "\t}",
+        "\tvar in setRoleInput",
+        "\tif err := c.ShouldBindJSON(&in); err != nil {",
+        "\t\tc.Error(httpx.BindErr(err))",
+        "\t\treturn",
+        "\t}",
+        "\tu, err := h.svc.SetRole(c.Request.Context(), id, in.Role)",
+        "\tif err != nil {",
+        "\t\tc.Error(err)",
+        "\t\treturn",
+        "\t}",
+        "\tc.JSON(http.StatusOK, toMeResponse(u))",
+        "}",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-funcs", setRoleHandler, "func (h *Handler) setRole(");
+    fs_extra_1.default.writeFileSync(handlerGoPath, content);
+}
+function patchUserErrorsForRbac(errorsGoPath) {
+    let content = fs_extra_1.default.readFileSync(errorsGoPath, "utf8");
+    const errFn = ["func errUnknownRole() *apperror.AppError {", '\treturn apperror.New(http.StatusUnprocessableEntity, "USER_UNKNOWN_ROLE", "unknown role code")', "}"].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-errors", errFn, "func errUnknownRole(");
+    fs_extra_1.default.writeFileSync(errorsGoPath, content);
+}
+// patchMainGoForRbac wires the role domain into cmd/api: its import, its
+// three models in the AutoMigrate call, and — the one place a plain insert
+// isn't enough — REPLACES the `add auth` PR's user.NewHandler(...) call with
+// a version that also builds roleSvc/authz and passes them through, plus
+// registers role's own routes right after it.
+function patchMainGoForRbac(mainGoPath, goModule) {
+    let content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
+    const importLine = `"${goModule}/internal/app/role"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
+    const modelImportLine = `rolemodel "${goModule}/internal/app/role/model"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    const migrateLines = ["&rolemodel.Role{},", "&rolemodel.Permission{},", "&rolemodel.RolePermission{},"];
+    for (const line of migrateLines) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
+    }
+    const oldRouteLine = "user.NewHandler(user.NewService(user.NewRepository(db), user.NewRedisTokenStore(rdb), mail.NewAsyncClient(q), cfg), cfg.JWTSecret, cfg.JWTRefreshTTL, cfg.CookieSecure, rdb).Register(api)";
+    if (content.includes(oldRouteLine)) {
+        const newRouteBlock = [
+            "roleSvc := role.NewService(role.NewRepository(db))",
+            "authz := middleware.NewAuthz(roleSvc.PermissionsOf, cfg.AuthzCacheTTL)",
+            "user.NewHandler(user.NewService(user.NewRepository(db), user.NewRedisTokenStore(rdb), mail.NewAsyncClient(q), cfg, roleSvc), cfg.JWTSecret, cfg.JWTRefreshTTL, cfg.CookieSecure, rdb, authz).Register(api)",
+            "role.NewHandler(roleSvc, cfg.JWTSecret, authz).Register(api)",
+        ].join("\n");
+        content = content.replace(oldRouteLine, newRouteBlock);
+    }
+    fs_extra_1.default.writeFileSync(mainGoPath, content);
+}
+// patchCmdSeedForRbac makes the seeded admin actually an admin: wires a
+// role.Service into cmd/seed's own user.Service, then calls SetRole right
+// after EnsureUser creates/finds the SEED_ADMIN_EMAIL user (fixtures stay on
+// the 'staff' DB default — only the operator-specified admin gets promoted).
+function patchCmdSeedForRbac(seedMainGoPath, goModule) {
+    let content = fs_extra_1.default.readFileSync(seedMainGoPath, "utf8");
+    const importLine = `"${goModule}/internal/app/role"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:seed-imports", importLine, importLine);
+    const roleSvcLine = "roleSvc := role.NewService(role.NewRepository(db))";
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:seed-services", roleSvcLine, roleSvcLine);
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:seed-user-service-args", "roleSvc,", "roleSvc,");
+    const setRoleCall = [
+        'if _, err := svc.SetRole(ctx, u.ID, "admin"); err != nil {',
+        '\tlogger.Error("promote seed admin to admin role", "error", err)',
+        "\tos.Exit(1)",
+        "}",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:seed-admin-role", setRoleCall, "promote seed admin to admin role");
+    fs_extra_1.default.writeFileSync(seedMainGoPath, content);
+}

package/dist/utils/version.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cliVersion = cliVersion;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+// cliVersion reads this CLI's own version out of its package.json — one source
+// of truth for `--version`, for the stamp written into a new project's
+// go-scaffold.config.json, and for the drift diagnostic that compares the two.
+// Same two-candidate lookup as getTemplatesRoot (dist/ when installed, src/
+// when running from a checkout).
+function cliVersion() {
+    const candidates = [
+        path_1.default.join(__dirname, "..", "..", "package.json"),
+        path_1.default.join(__dirname, "..", "..", "..", "package.json"),
+    ];
+    const resolved = candidates.find((candidate) => fs_1.default.existsSync(candidate));
+    if (!resolved)
+        throw new Error("unable to locate package.json");
+    return fs_extra_1.default.readJsonSync(resolved).version;
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/NakePranob/go-scaffold.git"
   },
   "bin": {
-    "go-scaffold": "./bin/go-scaffold.js"
+    "go-scaffold": "bin/go-scaffold.js"
   },
   "files": [
     "dist",

package/templates/add/auth/cmd/seed/main.go.hbs

@@ -0,0 +1,76 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"log/slog"
+	"os"
+
+	"{{goModule}}/internal/app/user"
+	"{{goModule}}/internal/platform/database"
+	"{{goModule}}/internal/shared/config"
+	// go-scaffold:seed-imports
+)
+
+// cmd/seed is a one-off operational task, like `migrate` — not part of the
+// API server's runtime, so it's a separate binary rather than a flag on
+// cmd/api. tokens/mailer are nil: EnsureUser never touches them (no login
+// or email flow runs during seeding).
+func main() {
+	withFixtures := flag.Bool("fixtures", false, "also seed sample dev users — do not use against a real environment")
+	flag.Parse()
+
+	cfg := config.Load()
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+
+	db, err := database.Open(cfg)
+	if err != nil {
+		logger.Error("open db", "error", err)
+		os.Exit(1)
+	}
+
+	// go-scaffold:seed-services
+	svc := user.NewService(
+		user.NewRepository(db), nil, nil, cfg,
+		// go-scaffold:seed-user-service-args
+	)
+	ctx := context.Background()
+
+	if email := os.Getenv("SEED_ADMIN_EMAIL"); email != "" {
+		password := os.Getenv("SEED_ADMIN_PASSWORD")
+		if password == "" {
+			logger.Error("SEED_ADMIN_PASSWORD is required when SEED_ADMIN_EMAIL is set")
+			os.Exit(1)
+		}
+		name := os.Getenv("SEED_ADMIN_NAME")
+		if name == "" {
+			name = "Admin"
+		}
+		u, err := svc.EnsureUser(ctx, email, password, name)
+		if err != nil {
+			logger.Error("seed admin user", "error", err)
+			os.Exit(1)
+		}
+		logger.Info("admin user ready", "email", u.Email, "id", u.ID)
+		// go-scaffold:seed-admin-role
+	}
+
+	if *withFixtures {
+		seedFixtures(ctx, svc, logger)
+	}
+}
+
+func seedFixtures(ctx context.Context, svc *user.Service, logger *slog.Logger) {
+	fixtures := []struct{ email, name string }{
+		{email: "dev.one@example.com", name: "Dev One"},
+		{email: "dev.two@example.com", name: "Dev Two"},
+	}
+	for _, f := range fixtures {
+		u, err := svc.EnsureUser(ctx, f.email, "password123", f.name)
+		if err != nil {
+			logger.Error("seed fixture user", "email", f.email, "error", err)
+			continue
+		}
+		logger.Info("fixture user ready", "email", u.Email, "id", u.ID)
+	}
+}

package/templates/add/auth/docs/forgot-password.yaml.hbs

@@ -0,0 +1,19 @@
+post:
+  summary: Request a password reset link
+  description: Always returns the same message whether or not the email exists, to avoid leaking which emails are registered.
+  operationId: forgotPassword
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/ForgotPasswordInput' }
+  responses:
+    "200":
+      description: ok
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MessageResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/google-callback.yaml.hbs

@@ -0,0 +1,22 @@
+get:
+  summary: Google OAuth callback
+  description: Redirect target Google sends the browser back to after consent — not called directly by API clients.
+  operationId: googleCallback
+  tags: [auth]
+  security: []
+  parameters:
+    - name: code
+      in: query
+      required: true
+      schema: { type: string }
+    - name: state
+      in: query
+      required: true
+      schema: { type: string }
+  responses:
+    "200":
+      description: ok, refresh_token set as an httpOnly cookie
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/AuthResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/google-login.yaml.hbs

@@ -0,0 +1,7 @@
+get:
+  summary: Start the Google OAuth login flow
+  operationId: googleLogin
+  tags: [auth]
+  security: []
+  responses:
+    "302": { description: redirect to Google's consent screen }

package/templates/add/auth/docs/login.yaml.hbs

@@ -0,0 +1,19 @@
+post:
+  summary: Log in with email and password
+  operationId: loginUser
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/LoginInput' }
+  responses:
+    "200":
+      description: ok, refresh_token set as an httpOnly cookie
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/AuthResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/logout.yaml.hbs

@@ -0,0 +1,8 @@
+post:
+  summary: Log out the current session
+  description: Revokes the refresh_token cookie's session and clears the cookie. Always succeeds, even with no cookie.
+  operationId: logoutUser
+  tags: [auth]
+  security: []
+  responses:
+    "204": { description: logged out }

package/templates/add/auth/docs/refresh.yaml.hbs

@@ -0,0 +1,15 @@
+post:
+  summary: Rotate the refresh token cookie for a new access token
+  description: >-
+    Reads refresh_token from the httpOnly cookie (no request body). Reusing an
+    already-rotated-out token revokes the whole session family.
+  operationId: refreshToken
+  tags: [auth]
+  security: []
+  responses:
+    "200":
+      description: ok, a new refresh_token cookie is set
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/AuthResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/register.yaml.hbs

@@ -0,0 +1,19 @@
+post:
+  summary: Register a new account
+  operationId: registerUser
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/RegisterInput' }
+  responses:
+    "201":
+      description: created, refresh_token set as an httpOnly cookie
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/AuthResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/reset-password.yaml.hbs

@@ -0,0 +1,16 @@
+post:
+  summary: Reset a password using a reset token
+  description: The token is one-time use (consumed on success) and also revokes every existing refresh token for the account.
+  operationId: resetPassword
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/ResetPasswordInput' }
+  responses:
+    "204": { description: password reset }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/schemas.yaml.hbs

@@ -0,0 +1,58 @@
+RegisterInput:
+  type: object
+  required: [email, password, name]
+  properties:
+    email: { type: string, format: email }
+    password: { type: string, format: password, minLength: 8 }
+    name: { type: string }
+
+LoginInput:
+  type: object
+  required: [email, password]
+  properties:
+    email: { type: string, format: email }
+    password: { type: string, format: password }
+
+ForgotPasswordInput:
+  type: object
+  required: [email]
+  properties:
+    email: { type: string, format: email }
+
+ResetPasswordInput:
+  type: object
+  required: [token, new_password]
+  properties:
+    token: { type: string }
+    new_password: { type: string, format: password, minLength: 8 }
+
+VerifyEmailInput:
+  type: object
+  required: [token]
+  properties:
+    token: { type: string }
+
+# access_token in the body; refresh_token is set as an httpOnly cookie, never
+# echoed back — see toCookieResponse in internal/app/user/dto.go.
+AuthResponse:
+  type: object
+  properties:
+    access_token: { type: string }
+    token_type: { type: string, example: Bearer }
+    expires_in: { type: integer, description: seconds until access_token expires }
+
+MessageResponse:
+  type: object
+  properties:
+    message: { type: string }
+
+MeResponse:
+  type: object
+  properties:
+    id: { type: string, format: uuid }
+    email: { type: string, format: email }
+    name: { type: string }
+    avatar_url: { type: string }
+    email_verified: { type: boolean }
+    # go-scaffold:me-response-fields
+    created_at: { type: string, format: date-time }

package/templates/add/auth/docs/users-me-logout-all.yaml.hbs

@@ -0,0 +1,9 @@
+post:
+  summary: Log out every session for the current user
+  description: Revokes every refresh token for the caller, not just the current one, and clears this request's cookie too.
+  operationId: logoutAllSessions
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "204": { description: all sessions logged out }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/users-me-resend-verification.yaml.hbs

@@ -0,0 +1,10 @@
+post:
+  summary: Resend the email verification link
+  operationId: resendVerification
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "204": { description: verification email sent }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/users-me.yaml.hbs

@@ -0,0 +1,12 @@
+get:
+  summary: Get the current user
+  operationId: getMe
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "200":
+      description: ok
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MeResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/verify-email.yaml.hbs

@@ -0,0 +1,16 @@
+post:
+  summary: Verify an email address using a verification token
+  description: The token is one-time use (GETDEL), reusing an already-consumed token fails.
+  operationId: verifyEmail
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/VerifyEmailInput' }
+  responses:
+    "204": { description: email verified }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }