@nakedev/go-scaffold 0.5.4 → 0.8.0

package/README.md

@@ -482,11 +482,24 @@ Auth adds:
   `password_credentials`, and `external_identities`; a Google-only user can
   add a password through `POST /users/me/identities/local` without creating a
   second account
-- failed-login lockout and user-session management
+- failed-login lockout in either of two shapes (`--lockout`), both ignoring a
+  repeated wrong password so a stale saved credential cannot lock the owner
+  out — and user-session management
 - MFA endpoints and configuration hooks
 - internal/app/user, auth middleware, cmd/seed, migrations, and OpenAPI
   documents when OpenAPI is enabled
 
+The --lockout choice controls what repeated failed logins cost:
+
+| --lockout | Policy | A patient attacker gets |
+|---|---|---|
+| progressive (default) | 3 free attempts, then the wait doubles from 2s to a 15 minute ceiling | ~4 guesses/hour |
+| fixed | 10 attempts, then a 5 minute lock; the count clears after 15 quiet minutes | ~12 guesses/hour |
+
+Both are per-account, temporary, and need no admin to unlock. `fixed` is the
+shape AD/Entra administrators expect and is kinder to someone who simply
+forgot their password; `progressive` starts costing time sooner.
+
 The --store choice controls refresh-token storage and rate-limit counters:
 
 | --store | Refresh/recovery token storage | Extra service |
@@ -584,10 +597,11 @@ my-api/
 │   │   ├── config/                 # environment configuration
 │   │   ├── apperror/               # consistent application errors
 │   │   ├── dberr/                  # database error classification
+│   │   ├── dbq/                    # escaped contains-search for list filters
 │   │   ├── httpx/                  # HTTP parsing and binding helpers
 │   │   ├── id/                     # UUID generation
 │   │   ├── middleware/             # request ID, logging, errors, CORS
-│   │   ├── pagination/             # pagination parsing and responses
+│   │   ├── pagination/             # pagination and ?q= parsing, responses
 │   │   └── tx/                     # transaction context helpers
 │   └── app/                        # empty until generate module is used
 ├── migrations/                     # embedded, versioned SQL migrations

package/dist/commands/auth.js

@@ -56,9 +56,10 @@ 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(store = "postgres", projectDir = process.cwd(), browserTopology = auth_wizard_1.DEFAULT_BROWSER_TOPOLOGY) {
+async function addAuth(store = "postgres", projectDir = process.cwd(), browserTopology = auth_wizard_1.DEFAULT_BROWSER_TOPOLOGY, lockout = auth_wizard_1.DEFAULT_LOCKOUT_POLICY) {
     const config = (0, config_1.readConfig)(projectDir);
     const browser = (0, auth_wizard_1.validateBrowserTopology)(browserTopology);
+    const lockoutPolicy = (0, auth_wizard_1.validateLockoutPolicy)(lockout);
     // 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
@@ -83,6 +84,10 @@ async function addAuth(store = "postgres", projectDir = process.cwd(), browserTo
         goModule: config.goModule,
         redis: store === "redis",
         worker,
+        // one flag rather than the policy name: the templates only ever ask
+        // "which shape", and a second policy name in Handlebars would need an
+        // equality helper the renderer does not have
+        fixedLockout: lockoutPolicy === "fixed",
     });
     const migrationsDir = path_1.default.join(projectDir, "migrations");
     fs_extra_1.default.ensureDirSync(migrationsDir);

package/dist/commands/check.js

@@ -218,7 +218,11 @@ function checkModule(projectDir, config, name, module) {
     const rootGoFiles = fs_extra_1.default.existsSync(moduleDir)
         ? fs_extra_1.default
             .readdirSync(moduleDir, { withFileTypes: true })
-            .filter((entry) => entry.isFile() && entry.name.endsWith(".go"))
+            // `_test.go` excluded: the rule is about where implementation lives,
+            // and `package <mod>_test` beside composition.go is the only place Go
+            // lets you test the composition root end to end. It is imported by
+            // nothing and adds no dependency edge, so it is not a layout breach.
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".go") && !entry.name.endsWith("_test.go"))
             .map((entry) => path_1.default.join(moduleDir, entry.name))
         : [];
     for (const file of rootGoFiles) {

package/dist/commands/method.js

@@ -70,6 +70,15 @@ async function generateHexagonalMethod(config, naming, methodNameArg, opts, proj
     }
     const cqrs = moduleConfig.applicationStyle === "cqrs";
     const authModule = naming.pkg === "user" && fs_extra_1.default.existsSync(path_1.default.join(moduleDir, "application", "contracts.go"));
+    // `add rbac`'s role module, not a module someone generated and named "role":
+    // the generated one has no application/errors.go, so it stays extendable.
+    const rbacModule = naming.pkg === "role" && fs_extra_1.default.existsSync(path_1.default.join(moduleDir, "application", "errors.go"));
+    if (rbacModule) {
+        throw new Error("internal/app/role comes from `add rbac`, which builds its HTTP response from a role *and its permissions* " +
+            "rather than from the entity alone — `generate method` has no shape to write against there. Add the endpoint " +
+            "by hand: a route in internal/app/role/adapters/inbound/http/handler.go, a method on the application service, " +
+            "and its OpenAPI entry.");
+    }
     const paths = {
         dtoPath: path_1.default.join(moduleDir, "application", "dto.go"),
         requestDTOPath: path_1.default.join(moduleDir, "adapters", "inbound", "http", "dto.go"),
@@ -80,6 +89,17 @@ async function generateHexagonalMethod(config, naming, methodNameArg, opts, proj
         queryPath: cqrs ? path_1.default.join(moduleDir, "application", "queries.go") : undefined,
         handlerPath: path_1.default.join(moduleDir, "adapters", "inbound", "http", "handler.go"),
         serviceTestPath: path_1.default.join(moduleDir, "application", moduleConfig.applicationStyle === "cqrs" ? "cqrs_test.go" : "service_test.go"),
+        // What `add auth` and `add rbac` call the things the patcher writes
+        // against. They are finished features rather than starting points, so
+        // they name their persistence model, their mappers and their response
+        // type after themselves, not after the vocabulary `generate module`
+        // emits. Anything left out here is emitted with the generated module's
+        // name and compiles to `undefined: <that name>`.
+        //
+        // The route group, the HTTP error mapper and the application package
+        // alias are *not* here: those are read out of the handler being patched
+        // (hexagonal-method-patcher.ts), which is why this table is three
+        // entries shorter than the number of names that differ.
         ...(authModule
             ? {
                 repositoryModelType: "User",
@@ -88,9 +108,15 @@ async function generateHexagonalMethod(config, naming, methodNameArg, opts, proj
                 repositoryToDomainCallReturnsError: true,
                 repositoryErrorMapper: "persistenceError",
                 repositoryStubReceiver: "f *fakeRepo",
-                handlerErrorMapper: "toHTTPError",
             }
             : {}),
+        // rbac is deliberately absent. Renaming was never enough for it: its
+        // `toDomainRole` returns a value where every other module returns a
+        // pointer, and `ToRoleResponse` takes a RoleListItem — a role together
+        // with its permission codes — where the others take the entity. No name
+        // substitution reconciles a different shape, so `generate method` refuses
+        // the module instead of writing code that resolves and then will not
+        // type-check.
     };
     const required = [
         paths.dtoPath,

package/dist/index.js

@@ -382,7 +382,7 @@ async function runAddWizard() {
         // all), so the menu has to ask it the same way the worker menu asks for
         // its queue backend — a choice only reachable by knowing the flag name
         // isn't a choice for anyone driving this from the menu.
-        await runAddAuth(await (0, auth_wizard_1.promptAuthStore)(), await (0, auth_wizard_1.promptBrowserTopology)(), {});
+        await runAddAuth(await (0, auth_wizard_1.promptAuthStore)(), await (0, auth_wizard_1.promptBrowserTopology)(), await (0, auth_wizard_1.promptLockoutPolicy)(), {});
     }
     else if (target === "rbac") {
         await runAddRbac({});
@@ -400,7 +400,7 @@ async function runAddWorker(backend, opts) {
     ], opts);
     await (0, worker_1.addWorker)(backend);
 }
-async function runAddAuth(store, browserTopology, opts) {
+async function runAddAuth(store, browserTopology, lockout, opts) {
     const config = (0, config_2.readConfig)(process.cwd());
     await confirmAdd([
         "add internal/app/user/, internal/shared/middleware/auth.go, and cmd/seed",
@@ -408,11 +408,14 @@ async function runAddAuth(store, browserTopology, opts) {
         store === "postgres"
             ? "refresh + recovery tokens: Postgres (user_svc.auth_tokens), rate-limit counters in-process — no extra service"
             : picocolors_1.default.yellow("refresh tokens + rate-limit counters: Redis; recovery tokens: Postgres — requires Redis"),
+        lockout === "progressive"
+            ? "failed logins: 3 free attempts, then a doubling wait up to 15 minutes"
+            : "failed logins: locked for 5 minutes after 10 attempts, count cleared by 15 quiet minutes",
         config.features.worker
             ? "verification/reset mail: queued through the worker already installed"
             : picocolors_1.default.yellow("verification/reset mail: sent inline over SMTP (no worker yet) — /auth/register and /auth/forgot-password block until it's sent"),
     ], opts);
-    await (0, auth_1.addAuth)(store, process.cwd(), browserTopology);
+    await (0, auth_1.addAuth)(store, process.cwd(), browserTopology, lockout);
 }
 // Explicit browser flags are intentionally resolved before the confirmation
 // summary. `--defaults` is the stable non-TTY escape hatch; `--yes` with no
@@ -425,6 +428,15 @@ async function resolveBrowserTopology(opts) {
         return auth_wizard_1.DEFAULT_BROWSER_TOPOLOGY;
     return (0, auth_wizard_1.promptBrowserTopology)();
 }
+// Same shape again: the lockout shape is a real fork in the generated code, so
+// it is worth asking about, but never worth blocking a scripted run over.
+async function resolveLockoutPolicy(opts) {
+    if (opts.lockout !== undefined)
+        return (0, auth_wizard_1.validateLockoutPolicy)(opts.lockout);
+    if (opts.defaults || opts.yes)
+        return auth_wizard_1.DEFAULT_LOCKOUT_POLICY;
+    return (0, auth_wizard_1.promptLockoutPolicy)();
+}
 async function runAddRbac(opts) {
     const config = (0, config_2.readConfig)(process.cwd());
     if (!config.features.auth) {
@@ -497,8 +509,9 @@ add
     .description("add email/password auth: JWT access tokens, refresh rotation, device-session listing/revocation, register/login/refresh/logout/me (no prerequisites — without `add worker` the verification/reset mail is sent inline)")
     .option("--store <store>", 'where tokens and rate-limit counters live: "postgres" (default, no extra service) or "redis" (exact across replicas)')
     .option("--browser-topology <topology>", "browser deployment topology for cookie/CORS policy: same-origin, same-site (different origin), or cross-site (requires HTTPS deployment)")
-    .option("--defaults", "skip store, browser-topology, and confirmation prompts; use Postgres plus local same-site defaults")
-    .option("-y, --yes", "skip confirmation; omitted store/topology use local Postgres and same-site defaults")
+    .option("--lockout <policy>", 'how repeated failed logins are refused: "progressive" (default, 3 free then a doubling wait to 15 minutes) or "fixed" (10 attempts, 5 minute lock, count cleared after 15 quiet minutes)')
+    .option("--defaults", "skip store, browser-topology, lockout, and confirmation prompts; use Postgres plus local same-site defaults")
+    .option("-y, --yes", "skip confirmation; omitted store/topology/lockout use local Postgres, same-site, and progressive defaults")
     .action(async (opts) => {
     try {
         // Same shape as `add worker`: an explicit flag wins, --defaults takes
@@ -519,7 +532,8 @@ add
             store = await (0, auth_wizard_1.promptAuthStore)();
         }
         const browserTopology = await resolveBrowserTopology(opts);
-        await runAddAuth(store, browserTopology, { yes: opts.yes || opts.defaults });
+        const lockout = await resolveLockoutPolicy(opts);
+        await runAddAuth(store, browserTopology, lockout, { yes: opts.yes || opts.defaults });
     }
     catch (err) {
         fail(err);

package/dist/prompts/auth-wizard.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_BROWSER_TOPOLOGY = void 0;
+exports.DEFAULT_LOCKOUT_POLICY = exports.DEFAULT_BROWSER_TOPOLOGY = void 0;
 exports.promptAuthStore = promptAuthStore;
 exports.validateBrowserTopology = validateBrowserTopology;
 exports.promptBrowserTopology = promptBrowserTopology;
+exports.validateLockoutPolicy = validateLockoutPolicy;
+exports.promptLockoutPolicy = promptLockoutPolicy;
 const interactive_1 = require("./interactive");
 // The one decision `add auth` cannot make for you: where refresh tokens and
 // rate-limit counters live. Recovery tokens always use the durable Postgres
@@ -61,3 +63,33 @@ async function promptBrowserTopology() {
         choices: TOPOLOGIES,
     });
 }
+exports.DEFAULT_LOCKOUT_POLICY = "progressive";
+// The numbers in these descriptions are what the generated policy allows a
+// patient attacker per account, once the free attempts are gone. Both refuse
+// on their own and heal on their own; neither needs an admin to unlock.
+const LOCKOUT_POLICIES = [
+    {
+        name: "Progressive delay",
+        value: "progressive",
+        description: "3 free attempts, then the wait doubles from 2s to a 15 minute ceiling — about 4 guesses an hour, but someone who forgot their password starts waiting early",
+    },
+    {
+        name: "Fixed lockout with a memory window",
+        value: "fixed",
+        description: "10 attempts, then locked for 5 minutes; the count clears after 15 quiet minutes — about 12 guesses an hour, and the shape AD/Entra admins already expect",
+    },
+];
+function validateLockoutPolicy(raw) {
+    const value = raw.trim().toLowerCase();
+    if (!LOCKOUT_POLICIES.some((policy) => policy.value === value)) {
+        throw new Error(`Lockout policy must be one of: ${LOCKOUT_POLICIES.map((policy) => policy.value).join(", ")} (got "${raw}")`);
+    }
+    return value;
+}
+async function promptLockoutPolicy() {
+    return (0, interactive_1.select)({
+        message: "How should repeated failed logins be refused?",
+        default: exports.DEFAULT_LOCKOUT_POLICY,
+        choices: LOCKOUT_POLICIES,
+    });
+}

package/dist/templates/create-manifest.js

@@ -53,6 +53,14 @@ exports.CREATE_MANIFEST = [
         template: "create/base/internal/shared/pagination/pagination.go.hbs",
         output: "internal/shared/pagination/pagination.go",
     },
+    {
+        template: "create/base/internal/shared/dbq/dbq.go.hbs",
+        output: "internal/shared/dbq/dbq.go",
+    },
+    {
+        template: "create/base/internal/shared/dbq/dbq_test.go.hbs",
+        output: "internal/shared/dbq/dbq_test.go",
+    },
     {
         template: "create/base/internal/shared/tx/tx.go.hbs",
         output: "internal/shared/tx/tx.go",

package/dist/templates/rbac-manifest.js

@@ -14,6 +14,7 @@ exports.RBAC_FILES = [
     { template: "add/rbac/internal/app/role/application/errors.go.hbs", output: "internal/app/role/application/errors.go" },
     { template: "add/rbac/internal/app/role/application/service.go.hbs", output: "internal/app/role/application/service.go" },
     { template: "add/rbac/internal/app/role/application/service_test.go.hbs", output: "internal/app/role/application/service_test.go" },
+    { template: "add/rbac/internal/app/role/adapters/inbound/http/dto.go.hbs", output: "internal/app/role/adapters/inbound/http/dto.go" },
     { template: "add/rbac/internal/app/role/adapters/inbound/http/handler.go.hbs", output: "internal/app/role/adapters/inbound/http/handler.go" },
     { template: "add/rbac/internal/app/role/adapters/inbound/http/handler_test.go.hbs", output: "internal/app/role/adapters/inbound/http/handler_test.go" },
     { template: "add/rbac/internal/app/role/adapters/outbound/postgres/model.go.hbs", output: "internal/app/role/adapters/outbound/postgres/model.go" },

package/dist/utils/hexagonal-method-patcher.js

@@ -70,7 +70,7 @@ function applicationInterfaceMarker(paths, type) {
 }
 function methodSignature(naming, method, opts) {
     if (opts.type === "get" && opts.getMode === "all") {
-        return `${method.pascalName}(context.Context, int, int) ([]domain.${naming.pascalName}, error)`;
+        return `${method.pascalName}(context.Context, ports.ListFilter) ([]domain.${naming.pascalName}, int64, error)`;
     }
     if (opts.type === "get") {
         return `${method.pascalName}(context.Context, string) (*domain.${naming.pascalName}, error)`;
@@ -84,8 +84,11 @@ function applicationMethod(naming, method, opts, receiver) {
     const target = receiver.startsWith("s ") ? "s" : "h";
     if (opts.type === "get" && opts.getMode === "all") {
         return [
-            `func (${receiver}) ${method.pascalName}(ctx context.Context, limit, offset int) ([]domain.${naming.pascalName}, error) {`,
-            `\treturn ${target}.repo.FindAll(ctx, limit, offset)`,
+            `// TODO: narrow this list. It reuses FindAll, so today it answers the`,
+            `// same rows as the module's own list — give ports.ListFilter the fields`,
+            `// this endpoint filters by and read them in the repository.`,
+            `func (${receiver}) ${method.pascalName}(ctx context.Context, filter ports.ListFilter) ([]domain.${naming.pascalName}, int64, error) {`,
+            `\treturn ${target}.repo.FindAll(ctx, filter)`,
             `}`,
             "",
         ].join("\n");
@@ -119,25 +122,35 @@ function applicationMethod(naming, method, opts, receiver) {
         "",
     ].join("\n");
 }
-function handlerMethod(naming, method, opts, cqrs, routeReceiver, errorMapper) {
+// "ports" is the module's own package, not a shared one — every other token
+// in an imports list resolves under internal/shared.
+function handlerImportPath(need, goModule, naming) {
+    if (need.startsWith("net/"))
+        return need;
+    if (need === "ports")
+        return `${goModule}/internal/app/${naming.pkg}/ports`;
+    return `${goModule}/internal/shared/${need}`;
+}
+function handlerMethod(naming, method, opts, cqrs, routeReceiver, errorMapper, appPkg, names) {
     const receiver = cqrs ? (opts.type === "get" ? "h.queries" : "h.commands") : "h.svc";
     if (opts.type === "get" && opts.getMode === "all") {
         return {
             route: `${routeReceiver}.GET("/${method.pathSegment}", h.${method.handlerName})`,
-            imports: ["net/http", "pagination"],
+            imports: ["net/http", "pagination", "ports"],
             body: [
                 `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
                 `\tp := pagination.Parse(c)`,
-                `\titems, err := ${receiver}.${method.pascalName}(c.Request.Context(), p.Limit, p.Offset)`,
+                `\tfilter := ports.ListFilter{Search: p.Search, Limit: p.Limit, Offset: p.Offset}`,
+                `\titems, total, err := ${receiver}.${method.pascalName}(c.Request.Context(), filter)`,
                 `\tif err != nil {`,
                 `\t\tc.Error(${errorMapper}(err))`,
                 `\t\treturn`,
                 `\t}`,
-                `\tout := make([]response, len(items))`,
+                `\tout := make([]${names.responseType}, len(items))`,
                 `\tfor i := range items {`,
-                `\t\tout[i] = toResponse(application.ToResponse(&items[i]))`,
+                `\t\tout[i] = ${names.responseMapper}(${appPkg}.${names.applicationResponseMapper}(&items[i]))`,
                 `\t}`,
-                `\tc.JSON(http.StatusOK, p.Response(out))`,
+                `\tc.JSON(http.StatusOK, p.ResponseWithTotal(out, total))`,
                 `}`,
                 "",
             ].join("\n"),
@@ -157,7 +170,7 @@ function handlerMethod(naming, method, opts, cqrs, routeReceiver, errorMapper) {
                 `\t\tc.Error(${errorMapper}(err))`,
                 `\t\treturn`,
                 `\t}`,
-                `\tc.JSON(http.StatusOK, toResponse(application.ToResponse(m)))`,
+                `\tc.JSON(http.StatusOK, ${names.responseMapper}(${appPkg}.${names.applicationResponseMapper}(m)))`,
                 `}`,
                 "",
             ].join("\n"),
@@ -179,7 +192,7 @@ function handlerMethod(naming, method, opts, cqrs, routeReceiver, errorMapper) {
                 `\t\tc.Error(${errorMapper}(err))`,
                 `\t\treturn`,
                 `\t}`,
-                `\tc.JSON(http.StatusCreated, toResponse(application.ToResponse(m)))`,
+                `\tc.JSON(http.StatusCreated, ${names.responseMapper}(${appPkg}.${names.applicationResponseMapper}(m)))`,
                 `}`,
                 "",
             ].join("\n"),
@@ -208,10 +221,49 @@ function assertNotDuplicate(content, needle, what) {
     if (content.includes(needle))
         throw new Error(`${what} already exists — pick a different method name`);
 }
-function handlerRouteReceiver(content) {
-    // Auth's protected routes use usersGroup; generated CRUD modules use the
-    // local g group. Both remain the module's inbound adapter boundary.
-    return (0, marker_patch_1.hasMarker)(content, "// go-scaffold:user-routes") ? "usersGroup" : "g";
+/**
+ * The variable a new route hangs off, read out of the handler rather than
+ * guessed from it.
+ *
+ * Every module declares its own group — `g` in a generated CRUD module,
+ * `usersGroup` in auth, `roles` in rbac — and a hard-coded pair of names
+ * silently emitted `g.PATCH(...)` into modules that never declared a `g`. The
+ * project then failed to compile with `undefined: g`, after the CLI had
+ * already reported success.
+ *
+ * Matched on the mounted path, not on declaration order: a module may open
+ * several groups (rbac has one for roles and one for permissions), and the
+ * one that owns the module's own collection is the one a new endpoint belongs
+ * to.
+ */
+function handlerRouteReceiver(content, naming) {
+    const owning = new RegExp(`(\\w+)\\s*:=\\s*\\w+\\.Group\\(\\s*"/${naming.plural}"`).exec(content);
+    if (owning)
+        return owning[1];
+    const anyGroup = /(\w+)\s*:=\s*\w+\.Group\(/.exec(content);
+    if (anyGroup)
+        return anyGroup[1];
+    throw new Error("no route group found in the handler — `generate method` adds a route to an existing group and this module declares none");
+}
+/**
+ * The function that turns an application error into an HTTP one, by its
+ * signature rather than by a name the caller passes in. Modules disagree:
+ * generated ones use `appError`/`applicationError`, auth and rbac both use
+ * `toHTTPError`.
+ */
+function handlerErrorMapperName(content, fallback) {
+    const found = /func\s+(\w+)\(err error\) error \{/.exec(content);
+    return found ? found[1] : fallback;
+}
+/**
+ * How the file being patched refers to the module's application package.
+ * `add auth` imports it aliased as `userapp`; everything else imports it
+ * plainly. Emitting the wrong one compiles to `undefined: application`.
+ */
+function applicationAlias(content, goModule, naming) {
+    const importPath = `${goModule}/internal/app/${naming.pkg}/application`;
+    const aliased = new RegExp(`(\\w+)\\s+"${importPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"`).exec(content);
+    return aliased ? aliased[1] : "application";
 }
 function hexagonalMarkersPresent(paths) {
     if (!fs_extra_1.default.existsSync(paths.dtoPath) || !fs_extra_1.default.existsSync(paths.requestDTOPath) || !fs_extra_1.default.existsSync(paths.portsPath) || !fs_extra_1.default.existsSync(paths.repositoryAdapterPath) || !fs_extra_1.default.existsSync(paths.handlerPath) || !fs_extra_1.default.existsSync(paths.serviceTestPath))
@@ -259,11 +311,15 @@ function patchHexagonalMethod(paths, naming, method, opts, goModule) {
     applicationFile = insert(applicationFile, target.marker, applicationMethod(naming, method, opts, target.receiver));
     write(files, target.path, applicationFile);
     let handler = read(files, paths.handlerPath);
-    const handlerResult = handlerMethod(naming, method, opts, cqrs, handlerRouteReceiver(handler), paths.handlerErrorMapper ?? "appError");
+    const handlerResult = handlerMethod(naming, method, opts, cqrs, handlerRouteReceiver(handler, naming), handlerErrorMapperName(handler, paths.handlerErrorMapper ?? "appError"), applicationAlias(handler, goModule, naming), {
+        responseType: paths.handlerResponseType ?? "response",
+        responseMapper: paths.handlerResponseMapper ?? "toResponse",
+        applicationResponseMapper: paths.applicationResponseMapper ?? "ToResponse",
+    });
     handler = insert(handler, HANDLER_ROUTES_MARKER, handlerResult.route);
     handler = insert(handler, HANDLER_FUNCS_MARKER, handlerResult.body);
     for (const need of handlerResult.imports)
-        handler = addImport(handler, need.startsWith("net/") ? need : `${goModule}/internal/shared/${need}`);
+        handler = addImport(handler, handlerImportPath(need, goModule, naming));
     write(files, paths.handlerPath, handler);
     if (opts.type === "post") {
         let dto = read(files, paths.dtoPath);
@@ -273,16 +329,19 @@ function patchHexagonalMethod(paths, naming, method, opts, goModule) {
         write(files, paths.dtoPath, dto);
         let requestDTO = read(files, paths.requestDTOPath);
         assertNotDuplicate(requestDTO, `type ${inputName} struct`, `HTTP DTO "${inputName}"`);
+        // Read before the import is added, so an alias the file already carries
+        // wins over the plain name this would otherwise introduce.
+        const requestAppPkg = applicationAlias(requestDTO, goModule, naming);
         requestDTO = addImport(requestDTO, `${goModule}/internal/app/${naming.pkg}/application`);
         requestDTO = insert(requestDTO, requestDTOMarker(requestDTO), [
             `type ${inputName} struct {`,
-            `\t// TODO: mirror request fields from application.${inputName} and add JSON/binding tags`,
+            `\t// TODO: mirror request fields from ${requestAppPkg}.${inputName} and add JSON/binding tags`,
             `}`,
             "",
-            `func to${inputName}(in ${inputName}) application.${inputName} {`,
+            `func to${inputName}(in ${inputName}) ${requestAppPkg}.${inputName} {`,
             `\t// TODO: map request fields explicitly into the application input.`,
             `\t_ = in`,
-            `\treturn application.${inputName}{}`,
+            `\treturn ${requestAppPkg}.${inputName}{}`,
             `}`,
             "",
         ].join("\n"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.5.4",
+  "version": "0.8.0",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",

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

@@ -26,4 +26,12 @@ post:
               - { $ref: './schemas.yaml#/MFAChallengeResponse' }
     "400": { $ref: '../common/responses.yaml#/ValidationError' }
     "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
-    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }
+    "429":
+      description: |
+        Two different limiters answer with this status, and the body's `code`
+        says which: `RATE_LIMITED` is the per-IP request rate on this route,
+        while `AUTH_TOO_MANY_ATTEMPTS` means this account is locked out after
+        repeated failures and no password will be checked until it expires.
+      content:
+        application/json:
+          schema: { $ref: '../common/schemas.yaml#/Error' }

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler.go.hbs

@@ -7,6 +7,7 @@ import (
 
 	"{{goModule}}/internal/app/user/application"
 	"{{goModule}}/internal/app/user/domain"
+	"{{goModule}}/internal/app/user/ports"
 	"{{goModule}}/internal/shared/apperror"
 	"{{goModule}}/internal/shared/httpx"
 	"{{goModule}}/internal/shared/middleware"
@@ -154,7 +155,10 @@ func (h *Handler) Register(rg gin.IRouter) {
 
 func (h *Handler) adminListUsers(c *gin.Context) {
 	p := pagination.Parse(c)
-	items, err := h.svc.List(c.Request.Context(), p.Limit, p.Offset)
+	// One struct all the way down, so a filter added later is a field on
+	// ports.ListFilter and not a new argument on the three signatures below.
+	filter := ports.ListFilter{Search: p.Search, Limit: p.Limit, Offset: p.Offset}
+	items, total, err := h.svc.List(c.Request.Context(), filter)
 	if err != nil {
 		c.Error(toHTTPError(err))
 		return
@@ -163,7 +167,7 @@ func (h *Handler) adminListUsers(c *gin.Context) {
 	for i := range items {
 		out[i] = toMeResponse(&items[i])
 	}
-	c.JSON(http.StatusOK, p.Response(out))
+	c.JSON(http.StatusOK, p.ResponseWithTotal(out, total))
 }
 func (h *Handler) adminGetUser(c *gin.Context) {
 	id, ok := httpx.ParseID(c)
@@ -226,6 +230,12 @@ func toHTTPError(err error) error {
 		}
 		return apperror.New(status, ruleErr.Code, ruleErr.Message)
 	}
+	// Before the catch-all: a stub `generate method` wrote has no body yet and
+	// 501 says so, where NewInternal would report a server fault for a route
+	// nobody has written.
+	if errors.Is(err, domain.ErrNotImplemented) {
+		return apperror.New(http.StatusNotImplemented, "NOT_IMPLEMENTED", "not implemented")
+	}
 	if errors.Is(err, domain.ErrNotFound) {
 		return apperror.NewNotFound("user not found")
 	}

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/model.go.hbs

@@ -76,6 +76,7 @@ func (AuthToken) TableName() string { return "user_svc.auth_tokens" }
 type LoginThrottle struct {
 	EmailHash   string `gorm:"primaryKey;type:text"`
 	Failures    int    `gorm:"not null;default:0"`
+	LastAttempt *string `gorm:"type:text"`
 	LockedUntil *time.Time
 	UpdatedAt   time.Time
 }