@nakedev/go-scaffold 0.1.2 → 0.1.3

package/dist/index.js

@@ -10,12 +10,17 @@ const picocolors_1 = __importDefault(require("picocolors"));
 const create_1 = require("./commands/create");
 const generate_1 = require("./commands/generate");
 const method_1 = require("./commands/method");
+const migration_1 = require("./commands/migration");
 const remove_1 = require("./commands/remove");
+const version_1 = require("./utils/version");
+const worker_1 = require("./commands/worker");
+const auth_1 = require("./commands/auth");
+const rbac_1 = require("./commands/rbac");
 const program = new commander_1.Command();
 program
     .name("go-scaffold")
     .description("Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard")
-    .version("0.1.0");
+    .version((0, version_1.cliVersion)());
 program
     .command("create [name]")
     .alias("c")
@@ -23,6 +28,7 @@ program
     .option("--defaults", "skip the wizard, use defaults (for CI/scripting)")
     .option("--no-docker", "skip docker-compose.yml (only applies with --defaults)")
     .option("--no-openapi-docs", "skip docs/openapi.yaml (only applies with --defaults)")
+    .option("--observability", "add Prometheus /metrics + OpenTelemetry tracing (only applies with --defaults; off by default)")
     .option("--api-prefix <prefix>", 'URL prefix every route is grouped under (default "v1"; pass "" for none)')
     .action(async (name, opts) => {
     try {
@@ -30,6 +36,7 @@ program
             defaults: opts.defaults,
             docker: opts.docker,
             openapiDocs: opts.openapiDocs,
+            observability: opts.observability,
             apiPrefix: opts.apiPrefix,
         });
     }
@@ -51,14 +58,18 @@ const generate = program
             choices: [
                 { name: "Module (full CRUD domain)", value: "module" },
                 { name: "Method (add one endpoint to an existing module)", value: "method" },
+                { name: "Migration (reserve a timestamped up/down SQL file pair)", value: "migration" },
             ],
         });
         if (target === "module") {
             await (0, generate_1.generateModule)(undefined, { full: true });
         }
-        else {
+        else if (target === "method") {
             await (0, method_1.generateMethod)(undefined, undefined, {});
         }
+        else {
+            await (0, migration_1.generateMigration)(undefined);
+        }
     }
     catch (err) {
         console.error(picocolors_1.default.red(err.message));
@@ -70,9 +81,11 @@ generate
     .alias("m")
     .description("scaffold a domain module — full CRUD by default, or a bare skeleton with --no-full")
     .option("--no-full", "minimal skeleton (model/errors/repository, no default CRUD) — add endpoints one at a time with `generate method`")
+    .option("--auth", "require a valid access token for this module's routes (needs `add auth`)")
+    .option("--permission <code>", "also require this permission via authz.Require (needs `add rbac`; implies --auth)")
     .action(async (name, opts) => {
     try {
-        await (0, generate_1.generateModule)(name, { full: opts.full });
+        await (0, generate_1.generateModule)(name, { full: opts.full, auth: opts.auth, permission: opts.permission });
     }
     catch (err) {
         console.error(picocolors_1.default.red(err.message));
@@ -107,6 +120,56 @@ generate
         process.exitCode = 1;
     }
 });
+generate
+    .command("migration [name]")
+    .alias("mig")
+    .description("reserve a timestamped migrations/<version>_<name>.{up,down}.sql pair (stubs only — you write the SQL)")
+    .action(async (name) => {
+    try {
+        await (0, migration_1.generateMigration)(name);
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
+const add = program.command("add").description("add opt-in infrastructure to an existing go-scaffold project");
+add
+    .command("worker")
+    .description("add Redis, an Asynq task queue, SMTP mail, and cmd/worker (opt-in — most projects don't need this on day one)")
+    .action(async () => {
+    try {
+        await (0, worker_1.addWorker)();
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
+add
+    .command("auth")
+    .description("add email/password auth: JWT access tokens, Redis-backed refresh token rotation, register/login/refresh/logout/me (requires `add worker` first)")
+    .action(async () => {
+    try {
+        await (0, auth_1.addAuth)();
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
+add
+    .command("rbac")
+    .description("add role-based access control: roles/permissions admin API, cached Authz middleware, PATCH /users/:id/set-role (requires `add auth` first)")
+    .action(async () => {
+    try {
+        await (0, rbac_1.addRbac)();
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
 const remove = program
     .command("remove")
     .alias("rm")

package/dist/prompts/create-wizard.js

@@ -25,6 +25,10 @@ async function runCreateWizard() {
         message: "Include hand-written OpenAPI docs (docs/openapi.yaml, whole docs/ tree served at /docs)?",
         default: true,
     });
+    const observability = await (0, prompts_1.confirm)({
+        message: "Add metrics + tracing (Prometheus /metrics, OpenTelemetry over OTLP/HTTP for Gin + GORM)?",
+        default: false,
+    });
     const apiPrefixRaw = await (0, prompts_1.input)({
         message: "API route prefix (e.g. v1, api/v1; leave blank for none):",
         default: "v1",
@@ -34,10 +38,11 @@ async function runCreateWizard() {
     console.log("\nSummary:");
     console.log(`  Docker + PostgreSQL: ${docker ? "yes" : "no"}`);
     console.log(`  OpenAPI docs: ${openapiDocs ? "yes" : "no"}`);
+    console.log(`  Metrics + tracing: ${observability ? "yes" : "no"}`);
     console.log(`  Route prefix: ${apiPrefix ? `/${apiPrefix}` : "(none)"}`);
     const proceed = await (0, prompts_1.confirm)({ message: "\nCreate project with these settings?", default: true });
     if (!proceed) {
         throw new Error("project creation cancelled");
     }
-    return { features: { docker, openapiDocs }, apiPrefix };
+    return { features: { docker, openapiDocs, observability }, apiPrefix };
 }

package/dist/prompts/generate-wizard.js

@@ -4,6 +4,7 @@ exports.promptModuleName = promptModuleName;
 exports.promptMethodName = promptMethodName;
 exports.promptMethodType = promptMethodType;
 exports.promptGetMode = promptGetMode;
+exports.promptMigrationName = promptMigrationName;
 exports.promptLookupField = promptLookupField;
 const prompts_1 = require("@inquirer/prompts");
 const naming_1 = require("../utils/naming");
@@ -53,6 +54,13 @@ async function promptGetMode() {
         ],
     });
 }
+async function promptMigrationName() {
+    const name = await (0, prompts_1.input)({
+        message: "Migration name (e.g. add_status_to_orders):",
+        validate: (value) => (value.trim() ? true : "migration name is required"),
+    });
+    return name.trim();
+}
 async function promptLookupField() {
     const field = await (0, prompts_1.input)({
         message: "Lookup field (e.g. email, status, slug):",

package/dist/templates/auth-manifest.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_FILES = void 0;
+// output paths are relative to the project root
+exports.AUTH_FILES = [
+    { template: "add/auth/internal/shared/middleware/auth.go.hbs", output: "internal/shared/middleware/auth.go" },
+    { template: "add/auth/internal/shared/middleware/ratelimit.go.hbs", output: "internal/shared/middleware/ratelimit.go" },
+    { template: "add/auth/internal/app/user/model/user.go.hbs", output: "internal/app/user/model/user.go" },
+    { template: "add/auth/internal/app/user/model/identity.go.hbs", output: "internal/app/user/model/identity.go" },
+    { template: "add/auth/internal/app/user/dto.go.hbs", output: "internal/app/user/dto.go" },
+    { template: "add/auth/internal/app/user/errors.go.hbs", output: "internal/app/user/errors.go" },
+    { template: "add/auth/internal/app/user/jwt.go.hbs", output: "internal/app/user/jwt.go" },
+    { template: "add/auth/internal/app/user/tokenstore.go.hbs", output: "internal/app/user/tokenstore.go" },
+    { template: "add/auth/internal/app/user/repository.go.hbs", output: "internal/app/user/repository.go" },
+    { template: "add/auth/internal/app/user/service.go.hbs", output: "internal/app/user/service.go" },
+    { template: "add/auth/internal/app/user/service_test.go.hbs", output: "internal/app/user/service_test.go" },
+    { template: "add/auth/internal/app/user/handler.go.hbs", output: "internal/app/user/handler.go" },
+    { template: "add/auth/cmd/seed/main.go.hbs", output: "cmd/seed/main.go" },
+];

package/dist/templates/create-manifest.js

@@ -45,6 +45,10 @@ exports.CREATE_MANIFEST = [
         template: "create/base/internal/shared/pagination/pagination.go.hbs",
         output: "internal/shared/pagination/pagination.go",
     },
+    {
+        template: "create/base/internal/shared/middleware/cors.go.hbs",
+        output: "internal/shared/middleware/cors.go",
+    },
     {
         template: "create/base/internal/shared/middleware/error.go.hbs",
         output: "internal/shared/middleware/error.go",
@@ -58,6 +62,7 @@ exports.CREATE_MANIFEST = [
         output: "internal/shared/middleware/requestid.go",
     },
     { template: "create/base/migrations/.gitkeep.hbs", output: "migrations/.gitkeep" },
+    { template: "create/base/migrations/embed.go.hbs", output: "migrations/embed.go" },
     // architecture standards docs — always included, this is the point of the CLI
     {
         template: "create/features/docs/architecture.md.hbs",
@@ -107,4 +112,24 @@ exports.CREATE_MANIFEST = [
         output: "docs/health/health-readyz.yaml",
         when: (ctx) => ctx.openapiDocs,
     },
+    {
+        template: "create/features/docs/observability/metrics.yaml.hbs",
+        output: "docs/observability/metrics.yaml",
+        when: (ctx) => ctx.openapiDocs && ctx.observability,
+    },
+    {
+        template: "create/features/observability/middleware/metrics.go.hbs",
+        output: "internal/shared/middleware/metrics.go",
+        when: (ctx) => ctx.observability,
+    },
+    {
+        template: "create/features/observability/middleware/tracing.go.hbs",
+        output: "internal/shared/middleware/tracing.go",
+        when: (ctx) => ctx.observability,
+    },
+    {
+        template: "create/features/observability/platform/telemetry/tracing.go.hbs",
+        output: "internal/platform/telemetry/tracing.go",
+        when: (ctx) => ctx.observability,
+    },
 ];

package/dist/templates/rbac-manifest.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RBAC_FILES = void 0;
+// output paths are relative to the project root
+exports.RBAC_FILES = [
+    { template: "add/rbac/internal/shared/middleware/authz.go.hbs", output: "internal/shared/middleware/authz.go" },
+    { template: "add/rbac/internal/shared/middleware/authz_test.go.hbs", output: "internal/shared/middleware/authz_test.go" },
+    { template: "add/rbac/internal/app/role/model/role.go.hbs", output: "internal/app/role/model/role.go" },
+    { template: "add/rbac/internal/app/role/model/permission.go.hbs", output: "internal/app/role/model/permission.go" },
+    { template: "add/rbac/internal/app/role/model/role_permission.go.hbs", output: "internal/app/role/model/role_permission.go" },
+    { template: "add/rbac/internal/app/role/repository.go.hbs", output: "internal/app/role/repository.go" },
+    { template: "add/rbac/internal/app/role/service.go.hbs", output: "internal/app/role/service.go" },
+    { template: "add/rbac/internal/app/role/service_test.go.hbs", output: "internal/app/role/service_test.go" },
+    { template: "add/rbac/internal/app/role/handler.go.hbs", output: "internal/app/role/handler.go" },
+    { template: "add/rbac/internal/app/role/dto.go.hbs", output: "internal/app/role/dto.go" },
+    { template: "add/rbac/internal/app/role/errors.go.hbs", output: "internal/app/role/errors.go" },
+];

package/dist/templates/worker-manifest.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKER_FILES = void 0;
+// output paths are relative to the project root
+exports.WORKER_FILES = [
+    { template: "add/worker/internal/platform/cache/redis.go.hbs", output: "internal/platform/cache/redis.go" },
+    { template: "add/worker/internal/platform/queue/client.go.hbs", output: "internal/platform/queue/client.go" },
+    { template: "add/worker/internal/platform/queue/server.go.hbs", output: "internal/platform/queue/server.go" },
+    { template: "add/worker/internal/platform/mail/mail.go.hbs", output: "internal/platform/mail/mail.go" },
+    { template: "add/worker/internal/platform/mail/task.go.hbs", output: "internal/platform/mail/task.go" },
+    { template: "add/worker/cmd/worker/main.go.hbs", output: "cmd/worker/main.go" },
+];

package/dist/utils/auth-patcher.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchConfigForAuth = patchConfigForAuth;
+exports.patchMainGoForAuth = patchMainGoForAuth;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const marker_patch_1 = require("./marker-patch");
+const IMPORT_MARKER = "// go-scaffold:imports";
+const CONFIG_FIELDS_MARKER = "// go-scaffold:config-fields";
+const CONFIG_LOAD_MARKER = "// go-scaffold:config-load";
+const CONFIG_CHECKS_MARKER = "// go-scaffold:config-checks";
+const PLATFORM_INIT_MARKER = "// go-scaffold:platform-init";
+const MODEL_MARKER = "// go-scaffold:models";
+const ROUTE_MARKER = "// go-scaffold:routes";
+const SHUTDOWN_MARKER = "// go-scaffold:shutdown";
+// patchConfigForAuth adds JWT/cookie/password-reset/Google OAuth fields to
+// Config, the same marker-based text insertion patchConfigForWorker uses
+// (config.go.hbs is only rendered once, at `create` — everything after that
+// is a real file a human may have already edited).
+function patchConfigForAuth(configGoPath) {
+    let content = fs_extra_1.default.readFileSync(configGoPath, "utf8");
+    const fieldsBlock = [
+        "JWTSecret string",
+        "JWTAccessTTL time.Duration",
+        "JWTRefreshTTL time.Duration",
+        "CookieSecure bool",
+        "",
+        "PasswordResetTTL time.Duration",
+        "PasswordResetURL string",
+        "",
+        "EmailVerifyTTL time.Duration",
+        "EmailVerifyURL string",
+        "",
+        "GoogleClientID string",
+        "GoogleClientSecret string",
+        "GoogleRedirectURL string",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_FIELDS_MARKER, fieldsBlock, "JWTSecret string");
+    const loadBlock = [
+        'JWTSecret:     env("JWT_SECRET", "dev-secret-change-me"),',
+        'JWTAccessTTL:  time.Duration(envInt("JWT_ACCESS_TTL_MIN", 15)) * time.Minute,',
+        'JWTRefreshTTL: time.Duration(envInt("JWT_REFRESH_TTL_MIN", 43200)) * time.Minute,',
+        'CookieSecure:  env("COOKIE_SECURE", "false") == "true",',
+        "",
+        'PasswordResetTTL: time.Duration(envInt("PASSWORD_RESET_TTL_MIN", 30)) * time.Minute,',
+        'PasswordResetURL: env("PASSWORD_RESET_URL", "http://localhost:3000/reset-password"),',
+        "",
+        'EmailVerifyTTL: time.Duration(envInt("EMAIL_VERIFY_TTL_MIN", 1440)) * time.Minute,',
+        'EmailVerifyURL: env("EMAIL_VERIFY_URL", "http://localhost:3000/verify-email"),',
+        "",
+        'GoogleClientID:     env("GOOGLE_CLIENT_ID", ""),',
+        'GoogleClientSecret: env("GOOGLE_CLIENT_SECRET", ""),',
+        'GoogleRedirectURL:  env("GOOGLE_REDIRECT_URL", ""),',
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_LOAD_MARKER, loadBlock, 'JWTSecret:     env("JWT_SECRET"');
+    fs_extra_1.default.writeFileSync(configGoPath, content);
+}
+// patchMainGoForAuth wires the user domain into cmd/api: its import, a
+// queue.Client (needed for the forgot-password email — cmd/api itself never
+// enqueued anything before this), its two models in the AutoMigrate call, a
+// prod guard against the still-default JWT secret, and its route
+// registration (the domain's own Handler.Register splits /auth public vs
+// /users protected — main.go doesn't need to know that split, same
+// convention as every other module).
+function patchMainGoForAuth(mainGoPath, goModule) {
+    let content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
+    const importLine = `"${goModule}/internal/app/user"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
+    const modelImportLine = `usermodel "${goModule}/internal/app/user/model"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    const queueImportLine = `"${goModule}/internal/platform/queue"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, queueImportLine, queueImportLine);
+    const mailImportLine = `"${goModule}/internal/platform/mail"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, mailImportLine, mailImportLine);
+    const checkBlock = [
+        'if cfg.IsProd() && cfg.JWTSecret == "dev-secret-change-me" {',
+        '\tlogger.Error("JWT_SECRET is still the dev default — set a real secret before deploying with APP_ENV=production")',
+        "\tos.Exit(1)",
+        "}",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_CHECKS_MARKER, checkBlock, "JWT_SECRET is still the dev default");
+    const queueInitBlock = ["q, err := queue.NewClient(cfg.RedisURL)", "if err != nil {", '\tlogger.Error("open queue", "error", err)', "\tos.Exit(1)", "}"].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PLATFORM_INIT_MARKER, queueInitBlock, "q, err := queue.NewClient(cfg.RedisURL)");
+    const migrateLine1 = "&usermodel.User{},";
+    const migrateLine2 = "&usermodel.Identity{},";
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, migrateLine1, migrateLine1);
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, migrateLine2, migrateLine2);
+    const routeLine = "user.NewHandler(user.NewService(user.NewRepository(db), user.NewRedisTokenStore(rdb), mail.NewAsyncClient(q), cfg), cfg.JWTSecret, cfg.JWTRefreshTTL, cfg.CookieSecure, rdb).Register(api)";
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, ROUTE_MARKER, routeLine, routeLine);
+    content = content.replace(/\n\t_ = api \/\/ dropped once `generate module` registers the first route\n/, "\n");
+    const shutdownBlock = ["if err := q.Close(); err != nil {", '\tlogger.Error("close queue", "error", err)', "}"].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SHUTDOWN_MARKER, shutdownBlock, "if err := q.Close()");
+    fs_extra_1.default.writeFileSync(mainGoPath, content);
+}

package/dist/utils/gocheck.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typeChecks = typeChecks;
+exports.assertNoDrift = assertNoDrift;
+const child_process_1 = require("child_process");
+const picocolors_1 = __importDefault(require("picocolors"));
+const version_1 = require("./version");
+// typeChecks runs `go vet ./...` in projectRoot. Returns null when there's no
+// Go toolchain on PATH — the caller can't conclude anything either way then,
+// the same graceful skip as gofmtTree.
+//
+// `go vet` rather than `go build`: build skips _test.go files entirely, and the
+// generated handler_test.go is exactly where a shared/ signature change lands
+// first (it constructs the middleware chain by hand). vet type-checks tests
+// too, so it sees what build would miss.
+function typeChecks(projectRoot) {
+    try {
+        (0, child_process_1.execFileSync)("go", ["version"], { stdio: "ignore" });
+    }
+    catch {
+        return null;
+    }
+    try {
+        (0, child_process_1.execFileSync)("go", ["vet", "./..."], { cwd: projectRoot, stdio: ["ignore", "pipe", "pipe"] });
+        return { ok: true, output: "" };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, output: `${e.stderr?.toString() ?? ""}${e.stdout?.toString() ?? ""}`.trim() };
+    }
+}
+// assertNoDrift is the second half of a before/after pair: given what
+// typeChecks said *before* the files were written, it re-checks and fails
+// loudly if generating is what broke the project.
+//
+// Why compare instead of just checking afterwards: a project can be mid-refactor
+// (or simply not have run `go mod tidy` yet), and blaming the generator for a
+// break it didn't cause is worse than staying quiet. Only the
+// passed-before → broken-after transition is unambiguously ours.
+//
+// The failure this exists for: `generate` renders templates pinned to the
+// shared/ layer that `create` emits, so once a project edits that layer — which
+// is normal, expected work — the generated code stops compiling against it.
+// Without this check that lands as a mystery build error some time later, in
+// files the user never wrote.
+function assertNoDrift(projectRoot, before, config) {
+    if (before === null || !before.ok)
+        return; // no Go here, or already broken — not ours to judge
+    const after = typeChecks(projectRoot);
+    if (after === null || after.ok)
+        return;
+    const scaffoldedWith = config.scaffoldVersion ?? "unknown (predates version stamping)";
+    throw new Error(`${picocolors_1.default.red("the generated code doesn't compile, but this project was fine a moment ago.")}\n\n` +
+        `The most likely cause is drift: this project's internal/shared layer has been edited\n` +
+        `since it was scaffolded, so the templates this CLI emits no longer match it.\n\n` +
+        `  scaffolded with: go-scaffold ${scaffoldedWith}\n` +
+        `  this CLI:        go-scaffold ${(0, version_1.cliVersion)()}\n\n` +
+        `${picocolors_1.default.dim("go vet ./... says:")}\n${after.output}\n\n` +
+        `The generated files were left in place — reconcile them with your shared/ layer by\n` +
+        `hand, or undo (\`go-scaffold remove module <name>\` for a module) and generate again\n` +
+        `with a CLI version that matches this project.`);
+}

package/dist/utils/main-patcher.js

@@ -17,6 +17,11 @@ const UNUSED_API_LINE = "_ = api // dropped once `generate module` registers the
 // unpatchMainGo removes precisely what patch added.
 function mainGoLines(patch) {
     const modelAlias = `${patch.pkg}model`; // every domain's model subpackage is named "model"
+    const handlerArgs = [`${patch.pkg}.NewService(${patch.pkg}.NewRepository(db))`];
+    if (patch.auth)
+        handlerArgs.push("cfg.JWTSecret");
+    if (patch.permission)
+        handlerArgs.push("authz");
     return {
         importLine: `"${patch.goModule}/internal/app/${patch.modulePath}"`,
         modelImportLine: `${modelAlias} "${patch.goModule}/internal/app/${patch.modulePath}/model"`,
@@ -24,7 +29,9 @@ function mainGoLines(patch) {
         // `api` is the one route group declared by main.go.hbs, prefixed with
         // whatever apiPrefix the project chose at create time (e.g. /v1, /api,
         // or none) — every module registers on it, there is no per-module choice.
-        routeLine: `${patch.pkg}.NewHandler(${patch.pkg}.NewService(${patch.pkg}.NewRepository(db))).Register(api)`,
+        // `authz` only exists in main.go once `add rbac` has run — patch.permission
+        // is only ever set once that's already been verified by the caller.
+        routeLine: `${patch.pkg}.NewHandler(${handlerArgs.join(", ")}).Register(api)`,
     };
 }
 // patchMainGo wires a newly generated module into cmd/api/main.go: its

package/dist/utils/migrations.js

@@ -3,15 +3,37 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.nextMigrationSeq = nextMigrationSeq;
+exports.newMigrationVersion = newMigrationVersion;
 const fs_extra_1 = __importDefault(require("fs-extra"));
-// golang-migrate sequential numbering: 000001, 000002, ...
-function nextMigrationSeq(migrationsDir) {
-    const files = fs_extra_1.default.existsSync(migrationsDir) ? fs_extra_1.default.readdirSync(migrationsDir) : [];
-    const nums = files
+// golang-migrate timestamp numbering — the same convention as the CLI's own
+// `migrate create -ext sql -dir migrations -seq=false <name>`: a 14-digit
+// UTC timestamp (YYYYMMDDHHMMSS). Two people branching from the same base and
+// each adding a migration get different filenames instead of both claiming
+// the next sequential number and colliding on merge. golang-migrate orders
+// by the numeric prefix either way, and a 14-digit timestamp always sorts
+// after any existing 6-digit sequential number, so a project with old-style
+// numbers already in migrations/ is safe to keep generating into.
+function newMigrationVersion(migrationsDir) {
+    const existing = new Set((fs_extra_1.default.existsSync(migrationsDir) ? fs_extra_1.default.readdirSync(migrationsDir) : [])
         .map((f) => f.match(/^(\d+)_/))
         .filter((m) => m !== null)
-        .map((m) => parseInt(m[1], 10));
-    const next = (nums.length ? Math.max(...nums) : 0) + 1;
-    return String(next).padStart(6, "0");
+        .map((m) => m[1]));
+    let d = new Date();
+    let version = formatVersion(d);
+    // Vanishingly unlikely in normal (human-driven) use, but guard the
+    // same-second edge case rather than silently overwrite a sibling file.
+    while (existing.has(version)) {
+        d = new Date(d.getTime() + 1000);
+        version = formatVersion(d);
+    }
+    return version;
+}
+function formatVersion(d) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return (String(d.getUTCFullYear()) +
+        pad(d.getUTCMonth() + 1) +
+        pad(d.getUTCDate()) +
+        pad(d.getUTCHours()) +
+        pad(d.getUTCMinutes()) +
+        pad(d.getUTCSeconds()));
 }

package/dist/utils/openapi-patcher.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.patchOpenapiIndex = patchOpenapiIndex;
 exports.unpatchOpenapiIndex = unpatchOpenapiIndex;
+exports.patchOpenapiIndexRaw = patchOpenapiIndexRaw;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const marker_patch_1 = require("./marker-patch");
 const PATHS_MARKER = "# go-scaffold:paths";
@@ -45,3 +46,18 @@ function unpatchOpenapiIndex(openapiPath, naming, apiPrefix) {
     const { paths, schemas } = openapiLines(naming, apiPrefix);
     fs_extra_1.default.writeFileSync(openapiPath, (0, marker_patch_1.removeLines)(content, [...paths, ...schemas]));
 }
+// patchOpenapiIndexRaw wires hand-written path docs into the index — used by
+// `add auth`/`add rbac`, whose endpoints aren't a single CRUD resource so
+// there's no ModuleNaming to derive lines from. Each entry is patched with
+// its own sentinel (the path key) rather than one block for all of them, so
+// re-running `add rbac` after a partial failure doesn't skip entries that
+// never made it in.
+function patchOpenapiIndexRaw(openapiPath, apiPrefix, entries) {
+    let content = fs_extra_1.default.readFileSync(openapiPath, "utf8");
+    for (const { urlPath, file } of entries) {
+        const key = `${apiPrefix ? `/${apiPrefix}` : ""}${urlPath}:`;
+        const block = `${key}\n  $ref: '${file}'`;
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PATHS_MARKER, block, key);
+    }
+    fs_extra_1.default.writeFileSync(openapiPath, content);
+}

package/dist/utils/platform-patcher.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchConfigForWorker = patchConfigForWorker;
+exports.patchMainGoForWorker = patchMainGoForWorker;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const marker_patch_1 = require("./marker-patch");
+const IMPORT_MARKER = "// go-scaffold:imports";
+const CONFIG_FIELDS_MARKER = "// go-scaffold:config-fields";
+const CONFIG_LOAD_MARKER = "// go-scaffold:config-load";
+const PLATFORM_INIT_MARKER = "// go-scaffold:platform-init";
+const READYZ_MARKER = "// go-scaffold:readyz-checks";
+const SHUTDOWN_MARKER = "// go-scaffold:shutdown";
+// patchConfigForWorker adds RedisURL + SMTP_* fields to Config and their
+// env() loads to Load() — via marker comments, the same text-insertion
+// approach as patchMainGo, since config.go.hbs is only rendered once (at
+// `create`) and everything after that is a real file a human may have
+// already edited.
+function patchConfigForWorker(configGoPath) {
+    let content = fs_extra_1.default.readFileSync(configGoPath, "utf8");
+    const fieldsBlock = ["RedisURL string", "", "SMTPHost string", "SMTPPort string", "SMTPUsername string", "SMTPPassword string", "SMTPFrom string"].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_FIELDS_MARKER, fieldsBlock, "RedisURL string");
+    const loadBlock = [
+        'RedisURL: env("REDIS_URL", "redis://localhost:6379/0"),',
+        "",
+        'SMTPHost:     env("SMTP_HOST", ""),',
+        'SMTPPort:     env("SMTP_PORT", "587"),',
+        'SMTPUsername: env("SMTP_USERNAME", ""),',
+        'SMTPPassword: env("SMTP_PASSWORD", ""),',
+        'SMTPFrom:     env("SMTP_FROM", "no-reply@example.local"),',
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_LOAD_MARKER, loadBlock, 'RedisURL: env("REDIS_URL"');
+    fs_extra_1.default.writeFileSync(configGoPath, content);
+}
+// patchMainGoForWorker wires Redis into cmd/api: opened alongside the DB, and
+// pinged as part of /readyz (so a Redis outage is caught the same way a DB
+// outage already is). It does not create a queue.Client — nothing in cmd/api
+// enqueues a task until some domain actually needs to (e.g. a future `add
+// auth`'s forgot-password flow); an unused *queue.Client sitting in main()
+// would just be dead weight until then.
+function patchMainGoForWorker(mainGoPath, goModule) {
+    let content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
+    const cacheImport = `"${goModule}/internal/platform/cache"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, cacheImport, cacheImport);
+    const initBlock = ["rdb, err := cache.Open(cfg)", "if err != nil {", '\tlogger.Error("open redis", "error", err)', "\tos.Exit(1)", "}"].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PLATFORM_INIT_MARKER, initBlock, "rdb, err := cache.Open(cfg)");
+    const readyzBlock = [
+        "if err := rdb.Ping(c.Request.Context()).Err(); err != nil {",
+        '\tc.JSON(http.StatusServiceUnavailable, gin.H{"status": "unavailable"})',
+        "\treturn",
+        "}",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, READYZ_MARKER, readyzBlock, "if err := rdb.Ping(");
+    const shutdownBlock = ["if err := rdb.Close(); err != nil {", '\tlogger.Error("close redis", "error", err)', "}"].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SHUTDOWN_MARKER, shutdownBlock, "if err := rdb.Close()");
+    fs_extra_1.default.writeFileSync(mainGoPath, content);
+}