@nakedev/go-scaffold 0.1.2 → 0.1.4

package/README.md

@@ -87,25 +87,26 @@ directory layout if missing).
 ### `generate module <name>` (alias `m`) — add a domain module
 
 ```bash
-go-scaffold generate module orders                  # full CRUD (default)
-go-scaffold generate module orders --no-full         # minimal skeleton — add endpoints with `generate method`
+go-scaffold generate module orders                  # safe minimal module (default)
+go-scaffold generate module orders --full           # opt-in CRUD skeleton
 ```
 
-Full CRUD (default) scaffolds:
+`--full` scaffolds:
 
 ```text
-internal/app/orders/
+internal/app/order/
 ├── model/model.go      # domain model + GORM table (id/created_at/updated_at — add real fields yourself; a folder so multi-table domains can add more files)
 ├── dto.go               # request/response structs (empty stubs — add real fields yourself)
-├── errors.go             # ORDERS_NOT_FOUND / ORDERS_CONFLICT / ORDERS_HAS_REFERENCES
+├── errors.go             # ORDER_NOT_FOUND / ORDER_CONFLICT / ORDER_HAS_REFERENCES
 ├── repository.go         # GORM data access
 ├── service.go            # business logic + repository interface (mockable)
 ├── handler.go            # Gin routes, registered under the project's API prefix
-├── service_test.go       # unit test, fake repo
-└── handler_test.go       # integration test, real Postgres, tx rollback
+├── service_test.go       # unit test, function-backed repository stub
+├── handler_test.go       # HTTP unit test, service stub, no DB
+└── repository_test.go    # Postgres integration test against migrated schema
 ```
 
-`--no-full` scaffolds the same `model`/`errors`/`repository` (so `generate
+The default minimal mode scaffolds the same `model`/`errors`/`repository` (so `generate
 method` always has a full data-access surface to call), but `dto`/`service`/
 `handler` start empty — no default CRUD, no routes, just the plumbing
 (`Register()`, the `repository` interface, `wrapFindErr`) that `generate
@@ -145,7 +146,7 @@ overwrites a method with the same name; picks a different one or errors.
 | `--type` | Route | What's generated |
 |---|---|---|
 | `get --get-mode all` | `GET /<plural>/<kebab-name>` | reuses `FindAll` — TODO to add real filtering |
-| `get --get-mode one --field <f>` | `GET /<plural>/<f>/:<f>` | a real `FindBy<F>` query added to the repository (+ its interface + `fakeRepo` test stub) |
+| `get --get-mode one --field <f>` | `GET /<plural>/<f>/:<f>` | a real `FindBy<F>` query added to the repository (+ its interface + function-backed repository test stub) |
 | `post` | `POST /<plural>/<kebab-name>` | adds a body DTO; service is a TODO stub |
 | `put` / `patch` | `<VERB> /<plural>/:id/<kebab-name>` | finds by id, TODO before saving (safe no-op until implemented) |
 | `delete` | `DELETE /<plural>/:id/<kebab-name>` | TODO stub |
@@ -154,8 +155,84 @@ Business logic is always left as a `TODO`-marked stub that compiles and
 returns a clean `500` rather than inventing behavior — see
 `docs/architect/patterns.md` in the generated project.
 
-`generate method` prints the route it added but does **not** touch
-`docs/openapi.yaml` — endpoint-specific spec entries stay hand-written.
+When OpenAPI docs are enabled, `generate method` also creates a valid TODO stub
+under `docs/<plural>/methods/` and wires the route into `docs/openapi.yaml`.
+Replace its placeholder request/response schemas while implementing the TODO.
+
+**Drift check** — `generate` type-checks the project (`go vet ./...`) before and
+after it writes. If the project was fine beforehand and the generated code
+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
 
@@ -165,9 +242,11 @@ go-scaffold rm m orders --yes             # skip the confirm
 ```
 
 The inverse of `generate module`: deletes `internal/app/<name>/` and reverses
-everything that was wired up — the import/AutoMigrate/route in `main.go`, the
-paths/schemas in `docs/openapi.yaml`, the per-module docs folder, and the
-`create_<plural>` migration. Restores the `_ = api` placeholder if it was the
+the import/AutoMigrate/route in `main.go`, paths/schemas in `docs/openapi.yaml`,
+and the per-module docs folder. **Existing migrations are preserved** because
+production may already have recorded those immutable versions. The table/data
+are also untouched; create a new `generate migration drop_<table>` migration
+when removal is intentional. Restores the `_ = api` placeholder if it was the
 last module, so the project still builds. Use this instead of hand-deleting
 the folder — a partial hand-delete leaves stale wiring that duplicates on the
 next `generate module` (which would panic gin at startup).

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

@@ -9,25 +9,50 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const picocolors_1 = __importDefault(require("picocolors"));
 const config_1 = require("../utils/config");
 const naming_1 = require("../utils/naming");
+const module_location_1 = require("../utils/module-location");
 const template_renderer_1 = require("../utils/template-renderer");
 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);
-    const naming = (0, naming_1.resolveModuleNaming)(rawName ?? (await (0, generate_wizard_1.promptModuleName)()));
+    // --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, module_location_1.resolveProjectModuleNaming)(projectDir, 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 +67,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 +80,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 +121,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 +131,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

@@ -9,28 +9,61 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const picocolors_1 = __importDefault(require("picocolors"));
 const config_1 = require("../utils/config");
 const naming_1 = require("../utils/naming");
+const module_location_1 = require("../utils/module-location");
 const method_patcher_1 = require("../utils/method-patcher");
+const gocheck_1 = require("../utils/gocheck");
 const template_renderer_1 = require("../utils/template-renderer");
+const openapi_patcher_1 = require("../utils/openapi-patcher");
 const generate_wizard_1 = require("../prompts/generate-wizard");
-// the actual URL the new route answers on — printed so the user can add the
-// matching openapi.yaml entry by hand (methods are deliberately not wired into
-// the spec; see the note in docs/openapi.yaml). Mirrors the paths registered
-// in method-patcher.ts.
-function routeHint(naming, method, type, apiPrefix, getMode, field) {
-    const base = apiPrefix ? `/${apiPrefix}/${naming.plural}` : `/${naming.plural}`;
+// URL path registered in method-patcher.ts, excluding the project-wide API
+// prefix so it can be passed directly to patchOpenapiIndexRaw.
+function methodRoutePath(naming, method, type, getMode, field) {
+    const base = `/${naming.plural}`;
     if (type === "get" && getMode === "all")
-        return `GET ${base}/${method.pathSegment}`;
+        return `${base}/${method.pathSegment}`;
     if (type === "get")
-        return `GET ${base}/${(0, naming_1.toDbName)(field ?? "")}/{${(0, naming_1.toCamelCase)(field ?? "")}}`;
+        return `${base}/${(0, naming_1.toDbName)(field ?? "")}/{${(0, naming_1.toCamelCase)(field ?? "")}}`;
     if (type === "post")
-        return `POST ${base}/${method.pathSegment}`;
-    if (type === "delete")
-        return `DELETE ${base}/{id}/${method.pathSegment}`;
-    return `${type.toUpperCase()} ${base}/{id}/${method.pathSegment}`;
+        return `${base}/${method.pathSegment}`;
+    return `${base}/{id}/${method.pathSegment}`;
+}
+function routeHint(naming, method, type, apiPrefix, getMode, field) {
+    const path = methodRoutePath(naming, method, type, getMode, field);
+    const prefixed = apiPrefix ? `/${apiPrefix}${path}` : path;
+    return `${type.toUpperCase()} ${prefixed}`;
+}
+function methodOpenapiDocument(naming, method, type, getMode, field) {
+    const pathParameters = [];
+    if (type === "get" && getMode === "one") {
+        const parameter = (0, naming_1.toCamelCase)(field ?? "");
+        pathParameters.push("parameters:", `  - name: ${parameter}`, "    in: path", "    required: true", "    schema:", "      type: string");
+    }
+    else if (type === "put" || type === "patch" || type === "delete") {
+        pathParameters.push("parameters:", "  - name: id", "    in: path", "    required: true", "    schema:", "      type: string", "      format: uuid");
+    }
+    const operation = [
+        `${type}:`,
+        `  summary: TODO document ${method.name}`,
+        `  operationId: ${method.handlerName}${naming.pascalName}`,
+        `  tags: [${naming.plural}]`,
+    ];
+    if (type === "post") {
+        operation.push("  requestBody:", "    required: true", "    content:", "      application/json:", "        schema:", "          type: object", "          description: TODO define request fields");
+    }
+    const status = type === "delete" ? "204" : type === "post" ? "201" : "200";
+    operation.push("  responses:", `    \"${status}\":`, `      description: ${type === "delete" ? "completed or already absent" : "TODO define response"}`);
+    if (type !== "delete") {
+        operation.push("      content:", "        application/json:", "          schema:", "            type: object", "            description: TODO replace with the method response schema");
+    }
+    operation.push("    \"400\": { $ref: '../../common/responses.yaml#/ValidationError' }");
+    if (type === "get" || type === "put" || type === "patch") {
+        operation.push("    \"404\": { $ref: '../../common/responses.yaml#/NotFoundError' }");
+    }
+    return [...pathParameters, ...operation, ""].join("\n");
 }
 async function generateMethod(moduleNameArg, methodNameArg, opts, projectDir = process.cwd()) {
     const config = (0, config_1.readConfig)(projectDir);
-    const naming = (0, naming_1.resolveModuleNaming)(moduleNameArg ?? (await (0, generate_wizard_1.promptModuleName)()));
+    const naming = (0, module_location_1.resolveProjectModuleNaming)(projectDir, moduleNameArg ?? (await (0, generate_wizard_1.promptModuleName)()));
     const modulePath = naming.pkg;
     const moduleDir = path_1.default.join(projectDir, "internal", "app", modulePath);
     const paths = {
@@ -59,12 +92,30 @@ 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 docsRelativePath = config.features.openapiDocs
+        ? `${naming.plural}/methods/${method.pathSegment}.yaml`
+        : undefined;
+    if (docsRelativePath && fs_extra_1.default.existsSync(path_1.default.join(projectDir, "docs", docsRelativePath))) {
+        throw new Error(`OpenAPI method document already exists: docs/${docsRelativePath}`);
+    }
+    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);
+    if (docsRelativePath) {
+        const docsPath = path_1.default.join(projectDir, "docs", docsRelativePath);
+        fs_extra_1.default.outputFileSync(docsPath, methodOpenapiDocument(naming, method, type, getMode, field));
+        (0, openapi_patcher_1.patchOpenapiIndexRaw)(path_1.default.join(projectDir, "docs", "openapi.yaml"), config.apiPrefix, [
+            {
+                urlPath: methodRoutePath(naming, method, type, getMode, field),
+                file: `./${docsRelativePath}`,
+            },
+        ]);
+    }
     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) {
-        console.log(picocolors_1.default.yellow(`docs: add this route to docs/openapi.yaml by hand — \`generate method\` doesn't touch the spec`));
+    if (docsRelativePath) {
+        console.log(picocolors_1.default.green(`docs: docs/${docsRelativePath} (wired into docs/openapi.yaml)`));
     }
     console.log(picocolors_1.default.dim(`\nnext: fill in the TODO in service.go, then \`go build ./...\` / \`go test ./...\``));
 }

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)`));
+}