@nakedev/go-scaffold 0.1.2 → 0.1.3

package/README.md

@@ -157,6 +157,81 @@ returns a clean `500` rather than inventing behavior — see
 `generate method` prints the route it added but does **not** touch
 `docs/openapi.yaml` — endpoint-specific spec entries stay hand-written.
 
+**Drift check** — `generate` type-checks the project (`go vet ./...`) before and
+after it writes. If the project was fine beforehand and the generated code
+doesn't compile, it stops with the compiler output instead of leaving you to
+find it later:
+
+```text
+the generated code doesn't compile, but this project was fine a moment ago.
+
+The most likely cause is drift: this project's internal/shared layer has been edited
+since it was scaffolded, so the templates this CLI emits no longer match it.
+
+  scaffolded with: go-scaffold 0.1.2
+  this CLI:        go-scaffold 0.3.0
+```
+
+That happens because `generate`'s templates are written against the `shared/`
+layer `create` emits — editing that layer is normal work, but it moves the
+project away from what this CLI's templates expect. `create` records its own
+version in `go-scaffold.config.json` so the message can name both sides. A
+project that was *already* broken (mid-refactor, or `go mod tidy` not run yet)
+is left alone — only a passed-before/broken-after transition is reported. No Go
+on `PATH` means the check is skipped.
+
+### `generate migration <name>` (alias `mig`) — reserve a SQL migration pair
+
+```bash
+go-scaffold generate migration add_status_to_orders
+```
+
+Creates timestamped `migrations/<version>_<name>.up.sql` and `.down.sql` TODO
+stubs. The CLI reserves the names; you own the SQL and should apply it with
+`make migrate-up` (or `migrate -path migrations -database "$DB_DSN" up`).
+
+### `add worker` — add Redis-backed background work
+
+```bash
+go-scaffold add worker
+```
+
+Adds Redis cache/queue support, async email delivery, and `cmd/worker`. It also
+makes `/readyz` report unavailable when Redis is down. Run `go mod tidy` and
+provide `REDIS_URL` before starting the API or worker.
+
+### `add auth` — add email/password authentication
+
+```bash
+go-scaffold add auth
+```
+
+Requires `add worker`. Adds JWT access tokens, Redis-backed refresh-token
+rotation, registration/login/logout, password reset, email verification, and
+Google OAuth routes. Apply the generated migrations; `AUTO_MIGRATE=true` is
+convenient in development, while production should use `migrate up`.
+
+### `add rbac` — add roles and permissions
+
+```bash
+go-scaffold add rbac
+go-scaffold generate module secrets --auth --permission secret:manage
+```
+
+Requires `add auth`. Adds role/permission administration, cached authorization
+middleware, and role assignment. Its migration seeds the default roles and
+permissions, so apply it with `migrate up`: AutoMigrate creates tables but does
+not run SQL seed statements.
+
+### Observability at project creation
+
+```bash
+go-scaffold create my-api --defaults --observability
+```
+
+Opt-in observability adds Prometheus metrics at `/metrics` and OpenTelemetry
+tracing. Tracing is disabled until `OTEL_EXPORTER_OTLP_ENDPOINT` is configured.
+
 ### `remove module <name>` (alias `rm m`) — drop a domain
 
 ```bash

package/dist/commands/auth.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addAuth = addAuth;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const config_1 = require("../utils/config");
+const template_renderer_1 = require("../utils/template-renderer");
+const auth_manifest_1 = require("../templates/auth-manifest");
+const auth_patcher_1 = require("../utils/auth-patcher");
+const migrations_1 = require("../utils/migrations");
+const openapi_patcher_1 = require("../utils/openapi-patcher");
+// URL (relative to the api prefix) -> docs file (relative to docs/) for every
+// route `add auth` registers — kept next to AUTH_FILES's route list so the
+// two are easy to eyeball together when a route changes.
+const AUTH_OPENAPI_PATHS = [
+    { urlPath: "/auth/register", file: "./auth/register.yaml" },
+    { urlPath: "/auth/login", file: "./auth/login.yaml" },
+    { urlPath: "/auth/refresh", file: "./auth/refresh.yaml" },
+    { urlPath: "/auth/logout", file: "./auth/logout.yaml" },
+    { urlPath: "/auth/forgot-password", file: "./auth/forgot-password.yaml" },
+    { urlPath: "/auth/reset-password", file: "./auth/reset-password.yaml" },
+    { urlPath: "/auth/verify-email", file: "./auth/verify-email.yaml" },
+    { urlPath: "/auth/google/login", file: "./auth/google-login.yaml" },
+    { urlPath: "/auth/google/callback", file: "./auth/google-callback.yaml" },
+    { urlPath: "/users/me", file: "./auth/users-me.yaml" },
+    { urlPath: "/users/me/resend-verification", file: "./auth/users-me-resend-verification.yaml" },
+    { urlPath: "/users/me/logout-all", file: "./auth/users-me-logout-all.yaml" },
+];
+// addAuth scaffolds email/password authentication: a users+identities model
+// pair, JWT access tokens, a Redis-backed refresh token store with
+// rotation + reuse detection, and register/login/refresh/logout/me. No RBAC
+// (no roles/permissions) — that's a separate opt-in on top of this, since
+// most projects need "is this caller logged in" long before they need "can
+// this caller do X".
+async function addAuth(projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    if (!config.features.worker) {
+        throw new Error("`go-scaffold add auth` requires `go-scaffold add worker` first — the refresh token store needs Redis");
+    }
+    const userDir = path_1.default.join(projectDir, "internal", "app", "user");
+    if (fs_extra_1.default.existsSync(userDir)) {
+        throw new Error(`${userDir} already exists — auth looks like it's already been added`);
+    }
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, auth_manifest_1.AUTH_FILES, { goModule: config.goModule });
+    const migrationsDir = path_1.default.join(projectDir, "migrations");
+    fs_extra_1.default.ensureDirSync(migrationsDir);
+    const usersVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_users.up.sql.hbs", output: path_1.default.join("migrations", `${usersVersion}_create_users.up.sql`) },
+        { template: "add/auth/migrations/create_users.down.sql.hbs", output: path_1.default.join("migrations", `${usersVersion}_create_users.down.sql`) },
+    ], {});
+    // identities references users(id) — must apply strictly after it. A
+    // second newMigrationVersion() call, scanning the dir again now that the
+    // users pair is already written, guarantees a later (or same-second,
+    // bumped) timestamp rather than assuming +1 by hand.
+    const identitiesVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_identities.up.sql.hbs", output: path_1.default.join("migrations", `${identitiesVersion}_create_identities.up.sql`) },
+        { template: "add/auth/migrations/create_identities.down.sql.hbs", output: path_1.default.join("migrations", `${identitiesVersion}_create_identities.down.sql`) },
+    ], {});
+    (0, auth_patcher_1.patchConfigForAuth)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"));
+    (0, auth_patcher_1.patchMainGoForAuth)(path_1.default.join(projectDir, "cmd", "api", "main.go"), config.goModule);
+    patchEnvExample(path_1.default.join(projectDir, ".env.example"));
+    patchMakefile(path_1.default.join(projectDir, "Makefile"));
+    let docsMessage = "";
+    const openapiPath = path_1.default.join(projectDir, "docs", "openapi.yaml");
+    if (config.features.openapiDocs && fs_extra_1.default.existsSync(openapiPath)) {
+        const docsEntries = [
+            { template: "add/auth/docs/schemas.yaml.hbs", output: path_1.default.join("docs", "auth", "schemas.yaml") },
+            ...AUTH_OPENAPI_PATHS.map(({ file }) => ({
+                template: `add/auth/docs/${path_1.default.basename(file)}.hbs`,
+                output: path_1.default.join("docs", "auth", path_1.default.basename(file)),
+            })),
+        ];
+        await (0, template_renderer_1.applyTemplateEntries)(projectDir, docsEntries, {});
+        (0, openapi_patcher_1.patchOpenapiIndexRaw)(openapiPath, config.apiPrefix, AUTH_OPENAPI_PATHS);
+        docsMessage = "\ndocs: docs/auth/*.yaml, wired into docs/openapi.yaml";
+    }
+    (0, template_renderer_1.gofmtTree)(projectDir);
+    (0, config_1.writeConfig)(projectDir, { ...config, features: { ...config.features, auth: true } });
+    console.log(picocolors_1.default.green("\nadded internal/app/user/, internal/shared/middleware/auth.go, and cmd/seed"));
+    console.log("registered POST /auth/{register,login,refresh,logout,forgot-password,reset-password}, " +
+        "GET /auth/google/{login,callback}, and GET /users/me in cmd/api/main.go" +
+        docsMessage);
+    console.log(picocolors_1.default.dim("\nnext: go mod tidy, then apply the new migrations (AUTO_MIGRATE=true picks them up automatically in dev)\n" +
+        "seed an admin: SEED_ADMIN_EMAIL=... SEED_ADMIN_PASSWORD=... make seed"));
+}
+function patchMakefile(makefilePath) {
+    if (!fs_extra_1.default.existsSync(makefilePath))
+        return;
+    let content = fs_extra_1.default.readFileSync(makefilePath, "utf8");
+    if (content.includes("\nseed:\n"))
+        return; // already added
+    content = content.replace(/^\.PHONY: /m, ".PHONY: seed ");
+    const target = "\n# bootstrap an admin user (idempotent) — SEED_ADMIN_EMAIL/PASSWORD from the\n" +
+        "# environment, not .env, so a real secret never sits in a checked-in file.\n" +
+        "# --fixtures adds throwaway dev sample users, never use it outside dev.\n" +
+        "seed:\n" +
+        "\t@[ -f .env ] && export $$(grep -v '^#' .env | sed -E 's/[[:space:]]+#.*$//' | xargs); go run ./cmd/seed $(ARGS)\n";
+    content = content.replace(/\nbuild:/, `${target}\nbuild:`);
+    fs_extra_1.default.writeFileSync(makefilePath, content);
+}
+function patchEnvExample(envExamplePath) {
+    if (!fs_extra_1.default.existsSync(envExamplePath))
+        return;
+    let content = fs_extra_1.default.readFileSync(envExamplePath, "utf8");
+    if (content.includes("JWT_SECRET"))
+        return; // already added
+    content =
+        content.replace(/\n?$/, "\n") +
+            "\n# HS256 signing secret for access tokens — change this before deploying with APP_ENV=production\n" +
+            "JWT_SECRET=dev-secret-change-me\n" +
+            "JWT_ACCESS_TTL_MIN=15\n" +
+            "JWT_REFRESH_TTL_MIN=43200\n" +
+            "COOKIE_SECURE=false\n" +
+            "\nPASSWORD_RESET_TTL_MIN=30\n" +
+            "PASSWORD_RESET_URL=http://localhost:3000/reset-password\n" +
+            "\nEMAIL_VERIFY_TTL_MIN=1440\n" +
+            "EMAIL_VERIFY_URL=http://localhost:3000/verify-email\n" +
+            "\n# leave the Google vars unset to disable Google login (register/login/refresh still work)\n" +
+            "GOOGLE_CLIENT_ID=\n" +
+            "GOOGLE_CLIENT_SECRET=\n" +
+            "GOOGLE_REDIRECT_URL=\n";
+    fs_extra_1.default.writeFileSync(envExamplePath, content);
+}

package/dist/commands/create.js

@@ -12,6 +12,7 @@ const create_manifest_1 = require("../templates/create-manifest");
 const config_1 = require("../utils/config");
 const naming_1 = require("../utils/naming");
 const create_wizard_1 = require("../prompts/create-wizard");
+const version_1 = require("../utils/version");
 async function createProject(rawName, opts) {
     const trimmed = (rawName ?? (await (0, create_wizard_1.promptProjectName)())).trim();
     if (!trimmed)
@@ -26,7 +27,7 @@ async function createProject(rawName, opts) {
     let features;
     let apiPrefix;
     if (opts.defaults) {
-        features = { docker: opts.docker ?? true, openapiDocs: opts.openapiDocs ?? true };
+        features = { docker: opts.docker ?? true, openapiDocs: opts.openapiDocs ?? true, observability: opts.observability ?? false };
         apiPrefix = (0, naming_1.normalizeApiPrefix)(opts.apiPrefix ?? "v1");
         const check = (0, naming_1.validateApiPrefix)(apiPrefix);
         if (check !== true)
@@ -45,7 +46,7 @@ async function createProject(rawName, opts) {
     await fs_extra_1.default.ensureDir(projectDir);
     await (0, template_renderer_1.applyTemplateEntries)(projectDir, create_manifest_1.CREATE_MANIFEST, context);
     (0, template_renderer_1.gofmtTree)(projectDir);
-    (0, config_1.writeConfig)(projectDir, { projectName, goModule, apiPrefix, features });
+    (0, config_1.writeConfig)(projectDir, { projectName, goModule, apiPrefix, features, scaffoldVersion: (0, version_1.cliVersion)() });
     console.log(picocolors_1.default.green(`\ncreated ${projectName}/`));
     console.log(`\ncd ${projectName}`);
     if (features.docker)

package/dist/commands/generate.js

@@ -14,20 +14,44 @@ const module_manifest_1 = require("../templates/module-manifest");
 const main_patcher_1 = require("../utils/main-patcher");
 const openapi_patcher_1 = require("../utils/openapi-patcher");
 const migrations_1 = require("../utils/migrations");
+const gocheck_1 = require("../utils/gocheck");
 const generate_wizard_1 = require("../prompts/generate-wizard");
+const PERMISSION_CODE_PATTERN = /^[a-z][a-z0-9:_-]*$/;
 async function generateModule(rawName, opts, projectDir = process.cwd()) {
     const config = (0, config_1.readConfig)(projectDir);
+    // --permission implies --auth (authz.Require must run after RequireAuth) —
+    // require both explicitly rather than silently turning one on, so the
+    // generated route's protection matches what the command line actually said.
+    if (opts.permission && !opts.auth) {
+        throw new Error("--permission requires --auth (permission checks run after auth) — pass both, e.g. --auth --permission products:manage");
+    }
+    if (opts.auth && !config.features.auth) {
+        throw new Error("--auth requires `go-scaffold add auth` first — there's no RequireAuth middleware yet");
+    }
+    if (opts.permission) {
+        if (!config.features.rbac) {
+            throw new Error("--permission requires `go-scaffold add rbac` first — there's no permissions table or authz middleware yet");
+        }
+        if (!PERMISSION_CODE_PATTERN.test(opts.permission)) {
+            throw new Error(`invalid permission code "${opts.permission}" — must start with a lowercase letter and contain only lowercase letters, digits, ':', '_', or '-'`);
+        }
+    }
     const naming = (0, naming_1.resolveModuleNaming)(rawName ?? (await (0, generate_wizard_1.promptModuleName)()));
     const modulePath = naming.pkg;
     const moduleDir = path_1.default.join(projectDir, "internal", "app", modulePath);
     if (fs_extra_1.default.existsSync(moduleDir) && fs_extra_1.default.readdirSync(moduleDir).length > 0) {
         throw new Error(`${moduleDir} already exists — pick a different name or delete it first`);
     }
+    // snapshot before writing anything, so assertNoDrift below can tell "we broke
+    // it" from "it was already broken"
+    const checkBefore = (0, gocheck_1.typeChecks)(projectDir);
     const context = {
         ...naming,
         goModule: config.goModule,
         dbName: (0, naming_1.toDbName)(config.projectName),
         modulePath,
+        auth: opts.auth,
+        permission: opts.permission,
     };
     const moduleFiles = opts.full ? module_manifest_1.MODULE_FILES : module_manifest_1.MODULE_FILES_MINIMAL;
     const moduleEntries = moduleFiles.map((f) => ({
@@ -42,7 +66,7 @@ async function generateModule(rawName, opts, projectDir = process.cwd()) {
         fs_extra_1.default.readdirSync(migrationsDir).some((f) => f.endsWith(`_create_${naming.plural}.up.sql`));
     let seq = "";
     if (!migrationExists) {
-        seq = (0, migrations_1.nextMigrationSeq)(migrationsDir);
+        seq = (0, migrations_1.newMigrationVersion)(migrationsDir);
         const migrationEntries = [
             {
                 template: "generate/module/migration.up.sql.hbs",
@@ -55,12 +79,33 @@ async function generateModule(rawName, opts, projectDir = process.cwd()) {
         ];
         await (0, template_renderer_1.applyTemplateEntries)(projectDir, migrationEntries, context);
     }
+    // --permission needs the code to actually exist before any role can be
+    // granted it — SetPermissions validates against the real catalog and
+    // rejects unknown codes, so an ungenerated permission would leave the
+    // route permanently unreachable by anyone, admin included.
+    let permissionSeq = "";
+    if (opts.permission) {
+        permissionSeq = (0, migrations_1.newMigrationVersion)(migrationsDir);
+        const permissionEntries = [
+            {
+                template: "generate/module/permission.up.sql.hbs",
+                output: path_1.default.join("migrations", `${permissionSeq}_add_${naming.plural}_permission.up.sql`),
+            },
+            {
+                template: "generate/module/permission.down.sql.hbs",
+                output: path_1.default.join("migrations", `${permissionSeq}_add_${naming.plural}_permission.down.sql`),
+            },
+        ];
+        await (0, template_renderer_1.applyTemplateEntries)(projectDir, permissionEntries, context);
+    }
     const mainGoPath = path_1.default.join(projectDir, "cmd", "api", "main.go");
     (0, main_patcher_1.patchMainGo)(mainGoPath, {
         goModule: config.goModule,
         modulePath,
         pkg: naming.pkg,
         pascalName: naming.pascalName,
+        auth: opts.auth,
+        permission: opts.permission,
     });
     let docsMessage = "";
     const openapiPath = path_1.default.join(projectDir, "docs", "openapi.yaml");
@@ -75,6 +120,7 @@ async function generateModule(rawName, opts, projectDir = process.cwd()) {
         docsMessage = `\ndocs: docs/${naming.plural}/{collection,item,schemas}.yaml, wired into docs/openapi.yaml`;
     }
     (0, template_renderer_1.gofmtTree)(projectDir);
+    (0, gocheck_1.assertNoDrift)(projectDir, checkBefore, config);
     const routePath = config.apiPrefix ? `/${config.apiPrefix}/${naming.plural}` : `/${naming.plural}`;
     console.log(picocolors_1.default.green(`\ngenerated internal/app/${modulePath}/`));
     if (opts.full) {
@@ -84,12 +130,24 @@ async function generateModule(rawName, opts, projectDir = process.cwd()) {
         console.log(`registered empty route group ${routePath} in cmd/api/main.go — ` +
             `add endpoints with \`go-scaffold generate method ${naming.pkg} <name> --type ...\``);
     }
+    if (opts.permission) {
+        console.log(`protected: requires a valid access token AND the "${opts.permission}" permission`);
+    }
+    else if (opts.auth) {
+        console.log("protected: requires a valid access token (no specific permission)");
+    }
+    else if (config.features.auth) {
+        console.log(picocolors_1.default.yellow(`note: this project has auth installed, but ${routePath} is PUBLIC — re-run with --auth (and --permission <code> if you also have rbac) to require login`));
+    }
     if (seq) {
         console.log(`migration: migrations/${seq}_create_${naming.plural}.{up,down}.sql`);
     }
     else {
         console.log(`migration: reused existing migrations/*_create_${naming.plural}.{up,down}.sql`);
     }
+    if (permissionSeq) {
+        console.log(`migration: migrations/${permissionSeq}_add_${naming.plural}_permission.{up,down}.sql (seeds the "${opts.permission}" permission — grant it to a role via PATCH /roles/:code/permissions)`);
+    }
     if (docsMessage)
         console.log(docsMessage);
     console.log(picocolors_1.default.dim(`\nnext: add real fields to model.go/dto.go, run \`go build ./...\`, then apply the migration ` +

package/dist/commands/method.js

@@ -10,6 +10,7 @@ const picocolors_1 = __importDefault(require("picocolors"));
 const config_1 = require("../utils/config");
 const naming_1 = require("../utils/naming");
 const method_patcher_1 = require("../utils/method-patcher");
+const gocheck_1 = require("../utils/gocheck");
 const template_renderer_1 = require("../utils/template-renderer");
 const generate_wizard_1 = require("../prompts/generate-wizard");
 // the actual URL the new route answers on — printed so the user can add the
@@ -59,8 +60,10 @@ async function generateMethod(moduleNameArg, methodNameArg, opts, projectDir = p
     if (field)
         (0, naming_1.assertNotGoKeyword)((0, naming_1.toCamelCase)(field), "lookup field");
     const method = (0, naming_1.resolveMethodNaming)(methodNameArg ?? (await (0, generate_wizard_1.promptMethodName)()));
+    const checkBefore = (0, gocheck_1.typeChecks)(projectDir);
     (0, method_patcher_1.patchMethod)(paths, naming, method, { type, getMode, field }, config.goModule);
     (0, template_renderer_1.gofmtTree)(projectDir);
+    (0, gocheck_1.assertNoDrift)(projectDir, checkBefore, config);
     console.log(picocolors_1.default.green(`\nadded "${method.name}" to internal/app/${modulePath}/`));
     console.log(`route: ${routeHint(naming, method, type, config.apiPrefix, getMode, field)}`);
     if (config.features.openapiDocs) {

package/dist/commands/migration.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMigration = generateMigration;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const config_1 = require("../utils/config");
+const migrations_1 = require("../utils/migrations");
+const naming_1 = require("../utils/naming");
+const generate_wizard_1 = require("../prompts/generate-wizard");
+// generate migration doesn't know your schema, so unlike `generate module`
+// it can't render real SQL — it only reserves the timestamped filename pair
+// so two people adding a migration on the same day never collide, and stubs
+// each with a TODO instead of leaving the CLI to guess at columns.
+async function generateMigration(rawName, projectDir = process.cwd()) {
+    (0, config_1.readConfig)(projectDir); // throws with a clear message if this isn't a go-scaffold project
+    const name = (0, naming_1.toDbName)(rawName ?? (await (0, generate_wizard_1.promptMigrationName)()));
+    if (!name) {
+        throw new Error(`invalid migration name: "${rawName}" (must contain letters/numbers)`);
+    }
+    const migrationsDir = path_1.default.join(projectDir, "migrations");
+    fs_extra_1.default.ensureDirSync(migrationsDir);
+    const version = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    const upPath = path_1.default.join(migrationsDir, `${version}_${name}.up.sql`);
+    const downPath = path_1.default.join(migrationsDir, `${version}_${name}.down.sql`);
+    fs_extra_1.default.writeFileSync(upPath, `-- TODO: write the up migration for ${name}\n`);
+    fs_extra_1.default.writeFileSync(downPath, `-- TODO: write the down migration for ${name} (reverses the up migration)\n`);
+    console.log(picocolors_1.default.green(`\ngenerated migrations/${version}_${name}.{up,down}.sql`));
+    console.log(picocolors_1.default.dim(`\nnext: write the SQL, then \`make migrate-up\` (dev) or apply it as a deploy step ` +
+        `(AUTO_MIGRATE=true also picks up model changes automatically in dev — this file matters most for prod)`));
+}

package/dist/commands/rbac.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addRbac = addRbac;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const config_1 = require("../utils/config");
+const template_renderer_1 = require("../utils/template-renderer");
+const rbac_manifest_1 = require("../templates/rbac-manifest");
+const migrations_1 = require("../utils/migrations");
+const rbac_patcher_1 = require("../utils/rbac-patcher");
+const openapi_patcher_1 = require("../utils/openapi-patcher");
+// URL (relative to the api prefix) -> docs file (relative to docs/) for every
+// route `add rbac` registers or adds onto the user handler.
+const RBAC_OPENAPI_PATHS = [
+    { urlPath: "/roles", file: "./rbac/roles.yaml" },
+    { urlPath: "/roles/{code}/permissions", file: "./rbac/role-permissions.yaml" },
+    { urlPath: "/roles/{code}", file: "./rbac/role.yaml" },
+    { urlPath: "/permissions", file: "./rbac/permissions.yaml" },
+    { urlPath: "/users", file: "./rbac/users.yaml" },
+    { urlPath: "/users/{id}", file: "./rbac/user.yaml" },
+    { urlPath: "/users/{id}/set-role", file: "./rbac/user-set-role.yaml" },
+];
+// addRbac layers role-based access control on top of `add auth`: a role
+// domain (roles/permissions/role_permissions, admin-manageable), an Authz
+// middleware with a cached role->permission lookup, a Role claim threaded
+// through the JWT, and the admin endpoints that actually need it: listing/
+// viewing other users (GET /users, GET /users/:id) and changing a user's
+// role (PATCH /users/:id/set-role). Opt-in on top of an opt-in — most
+// projects need "is this caller logged in" long before they need "can this
+// caller do X".
+async function addRbac(projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    if (!config.features.auth) {
+        throw new Error("`go-scaffold add rbac` requires `go-scaffold add auth` first — there's no Role claim to check permissions against otherwise");
+    }
+    const roleDir = path_1.default.join(projectDir, "internal", "app", "role");
+    if (fs_extra_1.default.existsSync(roleDir)) {
+        throw new Error(`${roleDir} already exists — RBAC looks like it's already been added`);
+    }
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, rbac_manifest_1.RBAC_FILES, { goModule: config.goModule });
+    const migrationsDir = path_1.default.join(projectDir, "migrations");
+    fs_extra_1.default.ensureDirSync(migrationsDir);
+    const version = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/rbac/migrations/add_roles.up.sql.hbs", output: path_1.default.join("migrations", `${version}_add_roles.up.sql`) },
+        { template: "add/rbac/migrations/add_roles.down.sql.hbs", output: path_1.default.join("migrations", `${version}_add_roles.down.sql`) },
+    ], {});
+    (0, rbac_patcher_1.patchConfigForRbac)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"));
+    (0, rbac_patcher_1.patchUserModelForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "model", "user.go"));
+    (0, rbac_patcher_1.patchMiddlewareAuthForRbac)(path_1.default.join(projectDir, "internal", "shared", "middleware", "auth.go"));
+    (0, rbac_patcher_1.patchUserJWTForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "jwt.go"));
+    (0, rbac_patcher_1.patchUserServiceForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "service.go"));
+    (0, rbac_patcher_1.patchUserServiceTestForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "service_test.go"));
+    (0, rbac_patcher_1.patchUserDTOForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "dto.go"));
+    (0, rbac_patcher_1.patchUserHandlerForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "handler.go"), config.goModule);
+    (0, rbac_patcher_1.patchUserErrorsForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "errors.go"));
+    (0, rbac_patcher_1.patchMainGoForRbac)(path_1.default.join(projectDir, "cmd", "api", "main.go"), config.goModule);
+    (0, rbac_patcher_1.patchCmdSeedForRbac)(path_1.default.join(projectDir, "cmd", "seed", "main.go"), config.goModule);
+    patchEnvExample(path_1.default.join(projectDir, ".env.example"));
+    let docsMessage = "";
+    const openapiPath = path_1.default.join(projectDir, "docs", "openapi.yaml");
+    if (config.features.openapiDocs && fs_extra_1.default.existsSync(openapiPath)) {
+        const docsEntries = [
+            { template: "add/rbac/docs/schemas.yaml.hbs", output: path_1.default.join("docs", "rbac", "schemas.yaml") },
+            ...RBAC_OPENAPI_PATHS.map(({ file }) => ({
+                template: `add/rbac/docs/${path_1.default.basename(file)}.hbs`,
+                output: path_1.default.join("docs", "rbac", path_1.default.basename(file)),
+            })),
+        ];
+        await (0, template_renderer_1.applyTemplateEntries)(projectDir, docsEntries, {});
+        (0, openapi_patcher_1.patchOpenapiIndexRaw)(openapiPath, config.apiPrefix, RBAC_OPENAPI_PATHS);
+        (0, rbac_patcher_1.patchAuthDocsForRbac)(path_1.default.join(projectDir, "docs", "auth", "schemas.yaml"));
+        docsMessage = "\ndocs: docs/rbac/*.yaml, wired into docs/openapi.yaml";
+    }
+    (0, template_renderer_1.gofmtTree)(projectDir);
+    (0, config_1.writeConfig)(projectDir, { ...config, features: { ...config.features, rbac: true } });
+    console.log(picocolors_1.default.green("\nadded internal/app/role/ and internal/shared/middleware/authz.go"));
+    console.log("registered GET /users, GET /users/:id, PATCH /users/:id/set-role, /roles, and /permissions in cmd/api/main.go" + docsMessage);
+    console.log(picocolors_1.default.yellow("\n⚠ AUTO_MIGRATE=true does NOT seed the role/permission data — it only creates the\n" +
+        "  tables from the Go structs. The \"staff\"/\"admin\" roles and their permissions live\n" +
+        "  in the migration's SQL (INSERT statements), which AutoMigrate never runs. Without\n" +
+        "  applying it for real, `make seed` fails with \"unknown role code\" and nobody can be\n" +
+        "  granted anything. Apply it before relying on RBAC, even in dev:\n" +
+        "    migrate -path migrations -database \"$DB_DSN\" up   (or: make migrate-up)"));
+    console.log(picocolors_1.default.dim("\nnext: go mod tidy, then SEED_ADMIN_EMAIL=... SEED_ADMIN_PASSWORD=... make seed to get an admin"));
+}
+function patchEnvExample(envExamplePath) {
+    if (!fs_extra_1.default.existsSync(envExamplePath))
+        return;
+    let content = fs_extra_1.default.readFileSync(envExamplePath, "utf8");
+    if (content.includes("AUTHZ_CACHE_TTL_MIN"))
+        return; // already added
+    content =
+        content.replace(/\n?$/, "\n") +
+            "\n# how long a role's permission set is cached before Authz.Require re-checks the DB —\n" +
+            "# a permission change takes effect for already-issued tokens within this window\n" +
+            "AUTHZ_CACHE_TTL_MIN=1\n";
+    fs_extra_1.default.writeFileSync(envExamplePath, content);
+}

package/dist/commands/remove.js

@@ -34,6 +34,17 @@ async function removeModule(rawName, opts, projectDir = process.cwd()) {
         if (!ok)
             throw new Error("removal cancelled");
     }
+    // detect --auth/--permission from the generated handler.go itself (not
+    // stored anywhere else) — unpatchMainGo needs the exact same flags used at
+    // generate-time to reconstruct the identical line it's removing.
+    const handlerGoPath = path_1.default.join(moduleDir, "handler.go");
+    let auth;
+    let permission;
+    if (fs_extra_1.default.existsSync(handlerGoPath)) {
+        const handlerContent = fs_extra_1.default.readFileSync(handlerGoPath, "utf8");
+        auth = /jwtSecret\s+string/.test(handlerContent);
+        permission = handlerContent.match(/h\.authz\.Require\("([^"]+)"\)/)?.[1];
+    }
     // 1. the domain package
     fs_extra_1.default.removeSync(moduleDir);
     // 2. main.go wiring
@@ -42,6 +53,8 @@ async function removeModule(rawName, opts, projectDir = process.cwd()) {
         modulePath,
         pkg: naming.pkg,
         pascalName: naming.pascalName,
+        auth,
+        permission,
     });
     // 3. openapi index + per-module docs
     const openapiPath = path_1.default.join(projectDir, "docs", "openapi.yaml");
@@ -49,12 +62,16 @@ async function removeModule(rawName, opts, projectDir = process.cwd()) {
         (0, openapi_patcher_1.unpatchOpenapiIndex)(openapiPath, naming, config.apiPrefix);
         fs_extra_1.default.removeSync(path_1.default.join(projectDir, "docs", naming.plural));
     }
-    // 4. migration files (up + down)
+    // 4. migration files (up + down) — including the --permission seed
+    // migration, if this module was generated with one.
     const migrationsDir = path_1.default.join(projectDir, "migrations");
     const removedMigrations = [];
     if (fs_extra_1.default.existsSync(migrationsDir)) {
         for (const f of fs_extra_1.default.readdirSync(migrationsDir)) {
-            if (f.endsWith(`_create_${naming.plural}.up.sql`) || f.endsWith(`_create_${naming.plural}.down.sql`)) {
+            if (f.endsWith(`_create_${naming.plural}.up.sql`) ||
+                f.endsWith(`_create_${naming.plural}.down.sql`) ||
+                f.endsWith(`_add_${naming.plural}_permission.up.sql`) ||
+                f.endsWith(`_add_${naming.plural}_permission.down.sql`)) {
                 fs_extra_1.default.removeSync(path_1.default.join(migrationsDir, f));
                 removedMigrations.push(f);
             }

package/dist/commands/worker.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addWorker = addWorker;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const config_1 = require("../utils/config");
+const template_renderer_1 = require("../utils/template-renderer");
+const worker_manifest_1 = require("../templates/worker-manifest");
+const platform_patcher_1 = require("../utils/platform-patcher");
+// addWorker scaffolds the async task processing subsystem: Redis
+// (platform/cache), Asynq client/server (platform/queue), SMTP mail
+// (platform/mail, with an email:send task type as the one thing the fresh
+// worker actually handles), and cmd/worker itself. Opt-in — most projects
+// don't need a queue on day one, and an empty worker with no task types
+// registered is a stranger scaffold than just not having one.
+async function addWorker(projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    const queueDir = path_1.default.join(projectDir, "internal", "platform", "queue");
+    if (fs_extra_1.default.existsSync(queueDir)) {
+        throw new Error(`${queueDir} already exists — worker infrastructure looks like it's already been added`);
+    }
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, worker_manifest_1.WORKER_FILES, { goModule: config.goModule });
+    (0, platform_patcher_1.patchConfigForWorker)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"));
+    (0, platform_patcher_1.patchMainGoForWorker)(path_1.default.join(projectDir, "cmd", "api", "main.go"), config.goModule);
+    patchEnvExample(path_1.default.join(projectDir, ".env.example"));
+    patchMakefile(path_1.default.join(projectDir, "Makefile"));
+    (0, template_renderer_1.gofmtTree)(projectDir);
+    (0, config_1.writeConfig)(projectDir, { ...config, features: { ...config.features, worker: true } });
+    console.log(picocolors_1.default.green("\nadded internal/platform/{cache,queue,mail}/ and cmd/worker/"));
+    console.log("wired Redis into cmd/api (readyz check) — cmd/api does not enqueue anything yet");
+    console.log(picocolors_1.default.dim("\nnext: make worker (separate terminal, or `make dev` runs both), then go build ./... to confirm"));
+}
+function patchEnvExample(envExamplePath) {
+    if (!fs_extra_1.default.existsSync(envExamplePath))
+        return;
+    let content = fs_extra_1.default.readFileSync(envExamplePath, "utf8");
+    if (content.includes("REDIS_URL"))
+        return; // already added
+    content =
+        content.replace(/\n?$/, "\n") +
+            "\nREDIS_URL=redis://localhost:6379/0\n" +
+            "\n# leave SMTP_HOST unset to log emails instead of sending them (dev default)\n" +
+            "SMTP_HOST=\n" +
+            "SMTP_PORT=587\n" +
+            "SMTP_USERNAME=\n" +
+            "SMTP_PASSWORD=\n" +
+            "SMTP_FROM=no-reply@example.local\n";
+    fs_extra_1.default.writeFileSync(envExamplePath, content);
+}
+function patchMakefile(makefilePath) {
+    if (!fs_extra_1.default.existsSync(makefilePath))
+        return;
+    let content = fs_extra_1.default.readFileSync(makefilePath, "utf8");
+    if (content.includes("\nworker:\n"))
+        return; // already added
+    content = content.replace(/^\.PHONY: /m, ".PHONY: dev worker ");
+    const targets = "\n# run both API + worker in one terminal — Ctrl+C kills both\n" +
+        "dev:\n" +
+        "\t@[ -f .env ] && export $$(grep -v '^#' .env | xargs); \\\n" +
+        "\t(trap 'kill 0' SIGINT SIGTERM; \\\n" +
+        "\t go run ./cmd/api & \\\n" +
+        "\t go run ./cmd/worker & \\\n" +
+        "\t wait)\n" +
+        "\n" +
+        "# background worker for async task processing (email, ...) — requires Redis.\n" +
+        "# Use `make dev` to run both in one terminal, or run this in a separate one.\n" +
+        "worker:\n" +
+        "\t@[ -f .env ] && export $$(grep -v '^#' .env | xargs); go run ./cmd/worker\n";
+    content = content.replace(/\nbuild:/, `${targets}\nbuild:`);
+    fs_extra_1.default.writeFileSync(makefilePath, content);
+}