@nakedev/go-scaffold 0.3.1 → 0.4.0

package/README.md

@@ -39,6 +39,7 @@ depending on your machine's npm/pnpm global-bin config — running
 go-scaffold create my-api
 cd my-api
 make docker-up   # if you kept Docker + PostgreSQL
+make db-create   # create the database itself (safe to re-run)
 go mod tidy
 make run
 ```
@@ -74,12 +75,14 @@ with `generate module`.
 | Option | Effect |
 |---|---|
 | `--defaults` | Skip the wizard, use defaults (Docker on, OpenAPI docs on, no route prefix) |
-| `--no-docker` | Skip `docker-compose.yml` (with `--defaults`) |
-| `--no-openapi-docs` | Skip `docs/openapi.yaml` (with `--defaults`) |
-| `--observability` | Prometheus `/metrics` + OpenTelemetry tracing (with `--defaults`; off by default — `add observability` does the same later) |
+| `--no-docker` | Skip `docker-compose.yml` |
+| `--no-openapi-docs` | Skip `docs/openapi.yaml` |
+| `--observability` | Prometheus `/metrics` + OpenTelemetry tracing (off by default — `add observability` does the same later) |
 | `--api-prefix <prefix>` | URL prefix every route is grouped under — opt in with e.g. `v1` or `api/v1`; omit it for none |
 
-Without `--defaults`, an interactive wizard asks the same four questions.
+Without `--defaults`, an interactive wizard asks the same four questions —
+skipping any a flag already answered, so `create my-api --no-docker` never asks
+about Docker and never scaffolds it.
 The prefix is a single project-wide choice made once at `create` time —
 there's no per-domain versioning (a domain that needs a real breaking change
 gets a new domain package or a new DTO field, not a duplicated model pointed

package/dist/commands/auth.js

@@ -94,11 +94,22 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
             { template: "add/auth/migrations/create_auth_tokens.down.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.down.sql`) },
         ], {});
     }
+    // Only meaningful when there is a worker; readConfig fills this from the
+    // adapter file on disk, so the only way it is still unknown is a project
+    // that has internal/platform/queue with neither adapter in it. Guessing
+    // here used to emit `queue.NewAsynqEnqueuer` into River-only projects —
+    // an undefined symbol that the parse-only gate below cannot see, so the
+    // command reported success over a project that no longer compiled.
+    const queueBackend = config.features.queue;
+    if (worker && !queueBackend) {
+        throw new Error("this project has internal/platform/queue but no river.go or asynq.go — can't tell which queue backend to wire auth's mailer onto.\n" +
+            "Restore the adapter file, or remove internal/platform/queue and re-run `go-scaffold add worker`.");
+    }
     (0, golangci_patcher_1.patchGolangciForModule)(path_1.default.join(projectDir, ".golangci.yml"), config.goModule, "user");
     (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", "wiring.go"), {
         goModule: config.goModule,
-        queueBackend: config.features.queue ?? "asynq",
+        queueBackend: queueBackend ?? "river",
         store,
         worker,
     });
@@ -150,6 +161,13 @@ function patchMakefile(makefilePath) {
     let content = fs_extra_1.default.readFileSync(makefilePath, "utf8");
     if (content.includes("\nseed:\n"))
         return; // already added
+    // Both halves below have to land or neither should: .PHONY naming a target
+    // that was never inserted is a Makefile that lies about itself. `build:` is
+    // the anchor the target is inserted above, so check it first and bail whole.
+    if (!/\nbuild:/.test(content)) {
+        console.error(picocolors_1.default.yellow(`skipped the Makefile \`seed\` target — no \`build:\` target to anchor it to in ${makefilePath}.\nAdd it by hand: \`seed:\` running \`go run ./cmd/seed\`.`));
+        return;
+    }
     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" +

package/dist/commands/create.js

@@ -39,7 +39,15 @@ async function createProject(rawName, opts) {
             throw new Error(check);
     }
     else {
-        ({ features, apiPrefix } = await (0, create_wizard_1.runCreateWizard)());
+        // commander gives `--no-x` options a default of true, and there is no
+        // `--docker`/`--openapi-docs` to pass, so false here can only mean the
+        // caller opted out explicitly. undefined leaves the question to the wizard.
+        ({ features, apiPrefix } = await (0, create_wizard_1.runCreateWizard)({
+            docker: opts.docker === false ? false : undefined,
+            openapiDocs: opts.openapiDocs === false ? false : undefined,
+            observability: opts.observability === true ? true : undefined,
+            apiPrefix: opts.apiPrefix,
+        }));
     }
     const context = {
         projectName,

package/dist/commands/method.js

@@ -103,6 +103,11 @@ async function generateMethod(moduleNameArg, methodNameArg, opts, projectDir = p
             `handler.go and service.go must both still carry their \`// go-scaffold:*\` markers —\n` +
             `restore them, or add this method by hand.`);
     }
+    // Before the docs check below, so a name that's already taken is reported as
+    // exactly that on every project — otherwise the leftover OpenAPI document
+    // gets the blame on a docs-enabled project and the real cause (pick another
+    // method name) is the one thing the message doesn't say.
+    (0, method_patcher_1.assertMethodAbsent)(paths, method);
     const docsRelativePath = config.features.openapiDocs
         ? `${naming.plural}/methods/${method.pathSegment}.yaml`
         : undefined;

package/dist/commands/observability.js

@@ -57,7 +57,15 @@ async function addObservability(projectDir = process.cwd(), opts = {}) {
     if (opts.silent)
         return;
     console.log(picocolors_1.default.green("\nadded internal/platform/telemetry/, internal/shared/middleware/{metrics,tracing}.go, and GET /metrics"));
-    console.log("wired into cmd/api/wiring.go and internal/platform/database — every request and GORM query now gets a trace span");
+    console.log("wired into cmd/api/wiring.go and internal/platform/database — every request and GORM query cmd/api makes now gets a trace span");
+    // database.Open is shared, so a River-backed cmd/worker does raise GORM
+    // spans — but telemetry.Init, the only caller of otel.SetTracerProvider,
+    // runs in cmd/api alone. Those spans reach a no-op provider and vanish, and
+    // the worker serves no /metrics. Say so rather than leave someone hunting
+    // for background jobs that were never going to appear.
+    if (config.features.worker) {
+        console.log(picocolors_1.default.yellow("cmd/worker is not instrumented — it initialises no tracer provider, so its spans are dropped and it exposes no /metrics"));
+    }
     if (staleDocs.length) {
         // Deliberately not "you edited these". The comparison is a whole-file
         // match against today's template, and techstack.md embeds pinned

package/dist/commands/undo.js

@@ -8,7 +8,7 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const picocolors_1 = __importDefault(require("picocolors"));
-const prompts_1 = require("@inquirer/prompts");
+const interactive_1 = require("../prompts/interactive");
 const config_1 = require("../utils/config");
 const naming_1 = require("../utils/naming");
 const module_location_1 = require("../utils/module-location");
@@ -57,10 +57,10 @@ async function undoModule(rawName, opts, projectDir = process.cwd()) {
             `so removing it would leave the project un-compilable. Undo \`add ${owner}\` by hand, or start from a fresh scaffold.`);
     }
     const migrationsDir = path_1.default.join(projectDir, "migrations");
-    const migrations = moduleMigrations(migrationsDir, (0, naming_1.migrationSlugAliases)(naming));
+    const { owned: migrations, unclaimed } = moduleMigrations(migrationsDir, naming);
     const { checkedDatabase } = assertMigrationsNeverEscaped(projectDir, migrations, naming.pkg);
     if (!opts.yes) {
-        const ok = await (0, prompts_1.confirm)({
+        const ok = await (0, interactive_1.confirm)({
             message: `Undo module "${naming.pkg}"? Deletes internal/app/${modulePath}/, its docs, ` +
                 `${migrations.length ? `${migrations.length} migration file(s), ` : ""}` +
                 `and un-wires wiring.go/openapi.yaml. The ${naming.tableName} table itself is not dropped.`,
@@ -135,23 +135,58 @@ async function undoModule(rawName, opts, projectDir = process.cwd()) {
             `or no migrate CLI. They weren't committed, so no other environment can have them, but if\n` +
             `you had run them against a local database it now records a version with no file behind it.`));
     }
+    if (unclaimed.length) {
+        console.log(picocolors_1.default.yellow(`\nleft in place: ${unclaimed.join(", ")}\n` +
+            `  named like this module's column migrations but not referencing ${naming.schemaName}.${naming.tableName},\n` +
+            `  so they look like they belong to another table. Delete them by hand if they don't.`));
+    }
     console.log(picocolors_1.default.dim(`\nnothing was dropped from any database — if you had already run these migrations locally,\n` +
         `the ${naming.tableName} table is still there. \`make db-drop && make db-create && make migrate-up\` is the\n` +
         `quickest way back to a clean dev database.`));
 }
-// moduleMigrations lists the migration files `generate module` created for
-// this module: the create pair, plus the permission pair when it was
-// generated with --permission.
-function moduleMigrations(migrationsDir, slugs) {
+// moduleMigrations lists every migration file this module caused: the create
+// pair, the permission pair from --permission, and the column pair that
+// `generate method --get-mode one --field <f>` writes (method.ts names it
+// `<version>_add_<tableName>_<column>`).
+//
+// That last one used to be left behind. The module and its create migration
+// went, the ALTER TABLE against the now-uncreated table stayed, and because
+// migrations/embed.go is a `//go:embed *` it then ran on every database made
+// from that project — "schema <x>_svc does not exist" — which is the exact
+// failure this command exists to prevent.
+//
+// The column pair cannot be claimed on filename alone: a module whose table is
+// `orders` would otherwise also claim `_add_orders_logs_email.up.sql`, which
+// belongs to a table named `orders_logs`. So a filename match is confirmed
+// against the file's own `<schema>.<table>` reference, which is unique to this
+// module. Anything that matches the shape but not the schema is reported
+// rather than silently deleted or silently kept.
+function moduleMigrations(migrationsDir, naming) {
     if (!fs_extra_1.default.existsSync(migrationsDir))
-        return [];
-    return fs_extra_1.default
-        .readdirSync(migrationsDir)
-        .filter((f) => slugs.some((slug) => f.endsWith(`_create_${slug}.up.sql`) ||
-        f.endsWith(`_create_${slug}.down.sql`) ||
-        f.endsWith(`_add_${slug}_permission.up.sql`) ||
-        f.endsWith(`_add_${slug}_permission.down.sql`)))
-        .sort();
+        return { owned: [], unclaimed: [] };
+    const slugs = (0, naming_1.migrationSlugAliases)(naming);
+    const owned = [];
+    const unclaimed = [];
+    for (const f of fs_extra_1.default.readdirSync(migrationsDir).sort()) {
+        const suffix = [".up.sql", ".down.sql"].find((e) => f.endsWith(e));
+        if (!suffix)
+            continue;
+        const stem = f.slice(0, -suffix.length);
+        if (slugs.some((slug) => stem.endsWith(`_create_${slug}`) || stem.endsWith(`_add_${slug}_permission`))) {
+            owned.push(f);
+            continue;
+        }
+        // `<version>_add_<slug>_<column>` — the --field column migration
+        if (!slugs.some((slug) => new RegExp(`^\\d+_add_${slug}_.+$`).test(stem)))
+            continue;
+        if (fs_extra_1.default.readFileSync(path_1.default.join(migrationsDir, f), "utf8").includes(`${naming.schemaName}.${naming.tableName}`)) {
+            owned.push(f);
+        }
+        else {
+            unclaimed.push(f);
+        }
+    }
+    return { owned, unclaimed };
 }
 // assertMigrationsNeverEscaped is what lets undo delete migration files at
 // all. A migration that has only ever existed in this working tree cannot be

package/dist/commands/worker.js

@@ -98,6 +98,13 @@ function patchMakefile(makefilePath, opts) {
     let content = fs_extra_1.default.readFileSync(makefilePath, "utf8");
     if (content.includes("\nworker:\n"))
         return; // already added
+    // Same all-or-nothing rule as `add auth`'s Makefile patch: without the
+    // `build:` anchor the targets never get inserted, and a .PHONY line naming
+    // them would be a Makefile that lies about what it can run.
+    if (!/\nbuild:/.test(content)) {
+        console.error(picocolors_1.default.yellow(`skipped the Makefile \`dev\`/\`worker\` targets — no \`build:\` target to anchor them to in ${makefilePath}.\nAdd them by hand: \`worker:\` running \`go run ./cmd/worker\`.`));
+        return;
+    }
     content = content.replace(/^\.PHONY: /m, `.PHONY: dev worker${opts.river ? " river-migrate" : ""} `);
     // River keeps its own tables, versioned by River itself rather than by this
     // project's migrations/ directory — run its CLI once per database. Pinned

package/dist/index.js

@@ -5,7 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const prompts_1 = require("@inquirer/prompts");
+const interactive_1 = require("./prompts/interactive");
 const picocolors_1 = __importDefault(require("picocolors"));
 const create_1 = require("./commands/create");
 const generate_1 = require("./commands/generate");
@@ -22,16 +22,15 @@ const auth_wizard_1 = require("./prompts/auth-wizard");
 const generate_wizard_1 = require("./prompts/generate-wizard");
 const config_1 = require("./utils/config");
 // fail is every command's catch: one place so the two non-obvious cases stay
-// consistent. @inquirer/prompts throws ExitPromptError both on Ctrl-C and when
-// stdin isn't a TTY, and its raw message ("User force closed the prompt with 0
-// null") tells a user nothing — the CI case especially, where the real problem
-// is a missing argument, not the prompt.
+// consistent. @inquirer/prompts throws ExitPromptError on Ctrl-C, and its raw
+// message ("User force closed the prompt with 0 null") tells a user nothing.
+// The no-TTY case normally never reaches here — prompts/interactive.ts rejects
+// before a prompt starts — but stdin can also close mid-prompt, which arrives
+// as the same error and deserves the same advice rather than "aborted".
 function fail(err) {
     const message = err.message ?? String(err);
     if (err.name === "ExitPromptError") {
-        console.error(picocolors_1.default.red(process.stdin.isTTY
-            ? "aborted"
-            : "no interactive terminal to prompt on — pass every value as an argument/flag (see --help), or add --defaults"));
+        console.error(picocolors_1.default.red(process.stdin.isTTY ? "aborted" : interactive_1.NO_TTY_MESSAGE));
     }
     else {
         console.error(picocolors_1.default.red(message));
@@ -49,9 +48,9 @@ program
     .alias("c")
     .description("scaffold a new project (bare skeleton — add domains with `generate module`)")
     .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("--no-docker", "skip docker-compose.yml")
+    .option("--no-openapi-docs", "skip docs/openapi.yaml")
+    .option("--observability", "add Prometheus /metrics + OpenTelemetry tracing (off by default)")
     .option("--api-prefix <prefix>", 'URL prefix every route is grouped under, e.g. v1 or api/v1 (default: none)')
     .action(async (name, opts) => {
     try {
@@ -99,7 +98,7 @@ async function runModuleWizard(name, opts) {
 // so the top-level bare `go-scaffold` invocation can offer the exact same
 // choice without duplicating it.
 async function runGenerateWizard() {
-    const target = await (0, prompts_1.select)({
+    const target = await (0, interactive_1.select)({
         message: "What do you want to generate?",
         choices: [
             { name: "Module (safe minimal domain; add methods explicitly)", value: "module" },
@@ -213,7 +212,7 @@ async function confirmAdd(summaryLines, opts = {}) {
     for (const line of summaryLines)
         console.log(`  ${picocolors_1.default.dim("•")} ${line}`);
     console.log();
-    const proceed = await (0, prompts_1.confirm)({ message: "Proceed?", default: false });
+    const proceed = await (0, interactive_1.confirm)({ message: "Proceed?", default: false });
     if (!proceed) {
         throw new Error("cancelled — nothing was written");
     }
@@ -229,7 +228,7 @@ async function runAddWizard() {
     // Each add is once-only, and rbac needs auth first. Both facts are already
     // known here, so say them in the menu rather than letting someone walk three
     // steps and a confirmation to reach "already been added".
-    const target = await (0, prompts_1.select)({
+    const target = await (0, interactive_1.select)({
         message: "What do you want to add?",
         choices: [
             {
@@ -306,7 +305,14 @@ async function runAddRbac(opts) {
     await (0, rbac_1.addRbac)();
 }
 async function runAddObservability(opts) {
-    await confirmAdd(["add Prometheus /metrics + OpenTelemetry tracing", "patch cmd/api/wiring.go and internal/platform/database to wire it in"], opts);
+    const config = (0, config_1.readConfig)(process.cwd());
+    await confirmAdd([
+        "add Prometheus /metrics + OpenTelemetry tracing",
+        "patch cmd/api/wiring.go and internal/platform/database to wire it in — cmd/api only",
+        ...(config.features.worker
+            ? [picocolors_1.default.yellow("cmd/worker is not instrumented: no tracer provider there, so its spans are dropped and it serves no /metrics")]
+            : []),
+    ], opts);
     await (0, observability_1.addObservability)();
 }
 const add = program
@@ -359,7 +365,7 @@ async function resolveQueueBackend(opts) {
 }
 add
     .command("auth")
-    .description("add email/password auth: JWT access tokens, refresh token rotation, register/login/refresh/logout/me (requires `add worker` first)")
+    .description("add email/password auth: JWT access tokens, refresh token rotation, register/login/refresh/logout/me (no prerequisites — without `add worker` the verification/reset mail is sent inline)")
     .option("--store <store>", 'where tokens and rate-limit counters live: "postgres" (default, no extra service) or "redis" (exact across replicas)')
     .option("--defaults", "skip the prompt, use the Postgres-backed store (for CI/scripting)")
     .option("-y, --yes", "skip the confirmation summary")
@@ -474,7 +480,7 @@ async function runTopMenu() {
     // offer what can actually run here.
     const inProject = (0, config_1.isProjectDir)(process.cwd());
     const target = inProject
-        ? await (0, prompts_1.select)({
+        ? await (0, interactive_1.select)({
             message: "What do you want to do?",
             choices: [
                 { name: "Create a new project", value: "create" },

package/dist/prompts/auth-wizard.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.promptAuthStore = promptAuthStore;
-const prompts_1 = require("@inquirer/prompts");
+const interactive_1 = require("./interactive");
 // The one decision `add auth` cannot make for you: where refresh tokens,
 // one-time tokens and rate-limit counters live. It drives which tokenStore
 // implementation is written, whether Redis is added to the project at all,
@@ -10,7 +10,7 @@ const prompts_1 = require("@inquirer/prompts");
 // Mirrors promptQueueBackend: the choice exists as `--store` for scripting,
 // but nobody should have to know the flag name to discover the option.
 async function promptAuthStore() {
-    return (0, prompts_1.select)({
+    return (0, interactive_1.select)({
         message: "Where should refresh tokens and rate-limit counters be stored?",
         default: "postgres",
         choices: [

package/dist/prompts/create-wizard.js

@@ -2,10 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.promptProjectName = promptProjectName;
 exports.runCreateWizard = runCreateWizard;
-const prompts_1 = require("@inquirer/prompts");
+const interactive_1 = require("./interactive");
 const naming_1 = require("../utils/naming");
 async function promptProjectName() {
-    const name = await (0, prompts_1.input)({
+    const name = await (0, interactive_1.input)({
         message: "Project name:",
         validate: (value) => {
             if (!value.trim())
@@ -15,35 +15,49 @@ async function promptProjectName() {
     });
     return name.trim();
 }
-async function runCreateWizard() {
+async function runCreateWizard(preset = {}) {
+    // The closing "create with these settings?" is asked however many answers
+    // arrived as flags, so this wizard always needs a terminal — say so before
+    // printing a header for questions that are never going to appear.
+    (0, interactive_1.assertInteractive)();
     console.log("\nConfigure your project:\n");
-    const docker = await (0, prompts_1.confirm)({
-        message: "Include Docker Compose (local Postgres)?",
-        default: true,
-    });
-    const openapiDocs = await (0, prompts_1.confirm)({
-        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 docker = preset.docker ??
+        (await (0, interactive_1.confirm)({
+            message: "Include Docker Compose (local Postgres)?",
+            default: true,
+        }));
+    const openapiDocs = preset.openapiDocs ??
+        (await (0, interactive_1.confirm)({
+            message: "Include hand-written OpenAPI docs (docs/openapi.yaml — files only, never served over HTTP)?",
+            default: true,
+        }));
+    const observability = preset.observability ??
+        (await (0, interactive_1.confirm)({
+            message: "Add metrics + tracing (Prometheus /metrics, OpenTelemetry over OTLP/HTTP for Gin + GORM)?",
+            default: false,
+        }));
     // No default, so Enter means what an empty answer looks like it means. A
     // prefix is opt-in: it puts every route in the project behind a path segment
     // that is then fixed for the life of the project, which is not something to
     // acquire by not answering a question.
-    const apiPrefixRaw = await (0, prompts_1.input)({
-        message: "API route prefix — leave blank for none, or e.g. v1, api/v1:",
-        validate: naming_1.validateApiPrefix,
-    });
+    const apiPrefixRaw = preset.apiPrefix ??
+        (await (0, interactive_1.input)({
+            message: "API route prefix — leave blank for none, or e.g. v1, api/v1:",
+            validate: naming_1.validateApiPrefix,
+        }));
+    const prefixCheck = (0, naming_1.validateApiPrefix)(apiPrefixRaw);
+    if (prefixCheck !== true)
+        throw new Error(prefixCheck);
     const apiPrefix = (0, naming_1.normalizeApiPrefix)(apiPrefixRaw);
+    // Everything is listed whether it was asked or passed, so a flag never
+    // reaches the project without the caller seeing the value it produced.
+    const fromFlag = (passed) => (passed !== undefined ? " (from flag)" : "");
     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 });
+    console.log(`  Docker + PostgreSQL: ${docker ? "yes" : "no"}${fromFlag(preset.docker)}`);
+    console.log(`  OpenAPI docs: ${openapiDocs ? "yes" : "no"}${fromFlag(preset.openapiDocs)}`);
+    console.log(`  Metrics + tracing: ${observability ? "yes" : "no"}${fromFlag(preset.observability)}`);
+    console.log(`  Route prefix: ${apiPrefix ? `/${apiPrefix}` : "(none)"}${fromFlag(preset.apiPrefix)}`);
+    const proceed = await (0, interactive_1.confirm)({ message: "\nCreate project with these settings?", default: true });
     if (!proceed) {
         throw new Error("project creation cancelled");
     }

package/dist/prompts/generate-wizard.js

@@ -10,7 +10,7 @@ exports.promptModuleShape = promptModuleShape;
 exports.promptModuleAuth = promptModuleAuth;
 exports.promptModulePermission = promptModulePermission;
 exports.promptExistingModule = promptExistingModule;
-const prompts_1 = require("@inquirer/prompts");
+const interactive_1 = require("./interactive");
 const naming_1 = require("../utils/naming");
 // wraps an assert-style validator into inquirer's true|string contract so a
 // reserved word re-prompts inline instead of aborting the whole command.
@@ -24,21 +24,21 @@ function notKeyword(value, role) {
     }
 }
 async function promptModuleName() {
-    const name = await (0, prompts_1.input)({
+    const name = await (0, interactive_1.input)({
         message: "Module name (singular, e.g. order, product):",
         validate: (value) => (value.trim() ? (0, naming_1.validateModuleName)(value) : "module name is required"),
     });
     return name.trim();
 }
 async function promptMethodName() {
-    const name = await (0, prompts_1.input)({
+    const name = await (0, interactive_1.input)({
         message: "Method name (e.g. approve, findByStatus, resetPassword):",
         validate: (value) => (value.trim() ? notKeyword(value, "method") : "method name is required"),
     });
     return name.trim();
 }
 async function promptMethodType() {
-    return (0, prompts_1.select)({
+    return (0, interactive_1.select)({
         message: "Method type:",
         choices: [
             { name: "GET", value: "get" },
@@ -50,7 +50,7 @@ async function promptMethodType() {
     });
 }
 async function promptGetMode() {
-    return (0, prompts_1.select)({
+    return (0, interactive_1.select)({
         message: "GET mode:",
         choices: [
             { name: "List (all) — a new list endpoint with its own filter", value: "all" },
@@ -59,14 +59,14 @@ async function promptGetMode() {
     });
 }
 async function promptMigrationName() {
-    const name = await (0, prompts_1.input)({
+    const name = await (0, interactive_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)({
+    const field = await (0, interactive_1.input)({
         message: "Lookup field (e.g. email, status, slug):",
         validate: (value) => {
             if (!value.trim())
@@ -84,7 +84,7 @@ async function promptLookupField() {
 // reachable by knowing the flag name isn't a choice for anyone driving this
 // from the menu.
 async function promptModuleShape() {
-    return (0, prompts_1.select)({
+    return (0, interactive_1.select)({
         message: "What should the module contain?",
         default: false,
         choices: [
@@ -102,7 +102,7 @@ async function promptModuleShape() {
     });
 }
 async function promptModuleAuth() {
-    return (0, prompts_1.confirm)({
+    return (0, interactive_1.confirm)({
         message: "Require a valid access token for this module's routes?",
         default: false,
     });
@@ -111,7 +111,7 @@ async function promptModuleAuth() {
 // takes no validate — an unusable code is caught by generateModule, which
 // owns the pattern and the "needs add rbac" rule.
 async function promptModulePermission() {
-    const code = await (0, prompts_1.input)({
+    const code = await (0, interactive_1.input)({
         message: "Also require a permission code — leave blank for none, or e.g. products:manage:",
     });
     return code.trim() || undefined;
@@ -126,7 +126,7 @@ async function promptExistingModule(packages, action) {
     if (packages.length === 0) {
         throw new Error(`no modules in internal/app yet — run \`go-scaffold generate module <name>\` before trying to ${action} one`);
     }
-    return (0, prompts_1.select)({
+    return (0, interactive_1.select)({
         message: "Which module?",
         choices: packages.map((pkg) => ({ name: pkg, value: pkg })),
     });

package/dist/prompts/interactive.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.select = exports.input = exports.confirm = exports.NO_TTY_MESSAGE = void 0;
+exports.assertInteractive = assertInteractive;
+const prompts_1 = require("@inquirer/prompts");
+exports.NO_TTY_MESSAGE = "no interactive terminal to prompt on — pass every value as an argument/flag (see --help), or add --defaults";
+// @inquirer/prompts does reject on a non-TTY stdin, but only after it has
+// written the question and its cursor escapes: a CI log then ends with a
+// question nobody can answer, followed by raw ANSI, followed by the real
+// error. Answering the no-TTY case before the prompt starts leaves only the
+// line that says what to do instead.
+//
+// Every prompt in this CLI is imported from here rather than from
+// @inquirer/prompts directly, so a prompt added later gets this for free.
+// Exported for a caller that prints something before its first prompt: the
+// header belongs to a wizard that cannot run at all here, so it should not be
+// printed either.
+function assertInteractive() {
+    if (!process.stdin.isTTY)
+        throw new Error(exports.NO_TTY_MESSAGE);
+}
+const confirm = (...args) => {
+    assertInteractive();
+    return (0, prompts_1.confirm)(...args);
+};
+exports.confirm = confirm;
+const input = (...args) => {
+    assertInteractive();
+    return (0, prompts_1.input)(...args);
+};
+exports.input = input;
+const select = (...args) => {
+    assertInteractive();
+    return (0, prompts_1.select)(...args);
+};
+exports.select = select;

package/dist/prompts/worker-wizard.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.promptQueueBackend = promptQueueBackend;
-const prompts_1 = require("@inquirer/prompts");
+const interactive_1 = require("./interactive");
 // The one decision `add worker` cannot make for you: where jobs live. It
 // drives which adapter is written, whether Redis is added to the project at
 // all, and whether an enqueue can join a database transaction.
 async function promptQueueBackend() {
-    return (0, prompts_1.select)({
+    return (0, interactive_1.select)({
         message: "Where should background jobs be stored?",
         default: "river",
         choices: [

package/dist/utils/config.js

@@ -18,12 +18,58 @@ function writeConfig(projectDir, config) {
 }
 // readConfig falls back to detecting from go.mod when the config file is
 // missing (e.g. a project scaffolded before this file existed).
+//
+// When the file IS present, any feature key it does not define is filled in
+// from the tree. A file that exists but is missing a key used to mean "false"
+// to every caller, and callers then guessed: `add auth` guessed the queue
+// backend and wrote `queue.NewAsynqEnqueuer` into a River-only project (a
+// symbol that does not exist — and the post-patch gate is parse-only, so the
+// CLI reported success over a project that no longer builds), while
+// `undo module user` read a missing `auth` key as "not auth's" and deleted the
+// whole auth domain. The tree always knew the answer; this stops the guessing.
+//
+// The file still wins wherever it has a value — an explicit `false` is an
+// answer, not a hole.
 function readConfig(projectDir) {
     const file = configPath(projectDir);
-    if (fs_extra_1.default.existsSync(file)) {
-        return fs_extra_1.default.readJsonSync(file);
+    if (!fs_extra_1.default.existsSync(file))
+        return detectConfig(projectDir);
+    const config = fs_extra_1.default.readJsonSync(file);
+    const detected = detectFeatures(projectDir);
+    const features = { ...config.features };
+    for (const key of Object.keys(detected)) {
+        if (features[key] === undefined)
+            features[key] = detected[key];
     }
-    return detectConfig(projectDir);
+    return { ...config, features };
+}
+// detectFeatures answers "what is actually installed here" from the tree
+// alone. Every `add` command leaves a directory or a file behind that nothing
+// else writes, which is what makes this reliable.
+//
+// auth and rbac are keyed on their middleware, not on internal/app/{user,role}:
+// those directories are also what `generate module user` / `generate module
+// role` produce, and mistaking one for the other would make `undo module`
+// refuse to remove a module it generated itself.
+function detectFeatures(projectDir) {
+    const has = (...segments) => fs_extra_1.default.existsSync(path_1.default.join(projectDir, ...segments));
+    const worker = has("internal", "platform", "queue");
+    const auth = has("internal", "app", "user") && has("internal", "shared", "middleware", "auth.go");
+    return {
+        docker: has("docker-compose.yml"),
+        openapiDocs: has("docs", "openapi.yaml"),
+        worker,
+        // which adapter file is present is what `add worker --queue` decided
+        queue: !worker ? undefined : has("internal", "platform", "queue", "asynq.go") ? "asynq" : "river",
+        auth,
+        // which store `add auth` chose is readable from which implementation
+        // file it wrote — same trick as the queue adapter above. Projects from
+        // before the option existed have neither name and read as "redis",
+        // which is what they in fact are.
+        authStore: !auth ? undefined : has("internal", "app", "user", "tokenstore_pg.go") ? "postgres" : "redis",
+        rbac: has("internal", "app", "role") && has("internal", "shared", "middleware", "authz.go"),
+        observability: has("internal", "platform", "telemetry"),
+    };
 }
 function detectConfig(projectDir) {
     const goModPath = path_1.default.join(projectDir, "go.mod");
@@ -60,31 +106,11 @@ function detectConfig(projectDir) {
     // ("needs add worker first") while `add worker` also refused ("queue
     // already exists"), with no way out. Worse, the first `add` to succeed then
     // wrote a config that recorded the undetected features as absent.
-    const has = (...segments) => fs_extra_1.default.existsSync(path_1.default.join(projectDir, ...segments));
-    const worker = has("internal", "platform", "queue");
     return {
         projectName: path_1.default.basename(projectDir),
         goModule,
         apiPrefix,
-        features: {
-            docker: has("docker-compose.yml"),
-            openapiDocs: has("docs", "openapi.yaml"),
-            worker,
-            // which adapter file is present is what `add worker --queue` decided
-            queue: !worker ? undefined : has("internal", "platform", "queue", "asynq.go") ? "asynq" : "river",
-            auth: has("internal", "app", "user"),
-            // which store `add auth` chose is readable from which implementation
-            // file it wrote — same trick as the queue adapter above. Projects from
-            // before the option existed have neither name and read as "redis",
-            // which is what they in fact are.
-            authStore: !has("internal", "app", "user")
-                ? undefined
-                : has("internal", "app", "user", "tokenstore_pg.go")
-                    ? "postgres"
-                    : "redis",
-            rbac: has("internal", "app", "role"),
-            observability: has("internal", "platform", "telemetry"),
-        },
+        features: detectFeatures(projectDir),
     };
 }
 // isProjectDir answers "would readConfig succeed here?" without throwing, so

package/dist/utils/method-patcher.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertMethodAbsent = assertMethodAbsent;
 exports.patchMethod = patchMethod;
 exports.markersPresent = markersPresent;
 const fs_extra_1 = __importDefault(require("fs-extra"));
@@ -38,13 +39,19 @@ function assertNotDuplicate(content, needle, what) {
 function routeCall(type) {
     return { get: "GET", post: "POST", put: "PUT", patch: "PATCH", delete: "DELETE" }[type];
 }
-function patchMethod(paths, naming, method, opts, goModule) {
+// assertMethodAbsent is the same check patchMethod runs, exported so callers
+// can reach it before their own pre-flight checks. A name that already exists
+// is the cause the caller needs to hear about, so it has to be reported ahead
+// of anything downstream of it (the OpenAPI document that name would collide
+// with, for one) rather than after.
+function assertMethodAbsent(paths, method) {
     const handlerSig = `func (h *Handler) ${method.handlerName}(`;
     const serviceSig = `func (s *Service) ${method.pascalName}(`;
-    const handlerContent = fs_extra_1.default.readFileSync(paths.handlerPath, "utf8");
-    const serviceContent = fs_extra_1.default.readFileSync(paths.servicePath, "utf8");
-    assertNotDuplicate(handlerContent, handlerSig, `handler method "${method.handlerName}"`);
-    assertNotDuplicate(serviceContent, serviceSig, `service method "${method.pascalName}"`);
+    assertNotDuplicate(fs_extra_1.default.readFileSync(paths.handlerPath, "utf8"), handlerSig, `handler method "${method.handlerName}"`);
+    assertNotDuplicate(fs_extra_1.default.readFileSync(paths.servicePath, "utf8"), serviceSig, `service method "${method.pascalName}"`);
+}
+function patchMethod(paths, naming, method, opts, goModule) {
+    assertMethodAbsent(paths, method);
     if (opts.type === "get" && opts.getMode === "all") {
         patchGetAll(paths, naming, method, goModule);
     }

package/dist/utils/observability-patcher.js

@@ -49,8 +49,8 @@ function patchMainGoForObservability(mainGoPath, goModule, projectName) {
     }
     const newUseLine = `${USE_LINE.slice(0, -1)}, middleware.Metrics(), middleware.Tracing("${projectName}"))`;
     content = content.replace(USE_LINE, () => newUseLine);
-    // Not gated on APP_ENV the way /docs is: production is exactly where you
-    // want a scrape target, and Prometheus reaches it in-cluster. It is still
+    // Unlike docs/, which is never served at all: production is exactly where
+    // you want a scrape target, and Prometheus reaches it in-cluster. It is still
     // unauthenticated and does disclose your route list and traffic shape, so
     // block /metrics at the ingress rather than publishing it to the internet.
     const metricsRoute = 'r.GET("/metrics", gin.WrapH(promhttp.Handler()))';

package/dist/utils/platform-patcher.js

@@ -10,6 +10,7 @@ exports.patchConfigForWorker = patchConfigForWorker;
 exports.patchConfigForSMTP = patchConfigForSMTP;
 exports.patchMainGoForWorker = patchMainGoForWorker;
 const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
 const marker_patch_1 = require("./marker-patch");
 const IMPORT_MARKER = "// go-scaffold:imports";
 const CONFIG_FIELDS_MARKER = "// go-scaffold:config-fields";
@@ -58,9 +59,17 @@ function patchCiForRedis(ciPath) {
         return;
     // `steps:` sits one level under the job, so it's the first line that ends
     // the `services:` block — insert the service just above it.
+    //
+    // Anchored on the exact indentation the template emits. A hand-reformatted
+    // workflow is the realistic way to miss it, and returning silently there
+    // means CI runs without Redis and fails on a connection error that says
+    // nothing about this — so say it here instead.
     const stepsLine = content.split("\n").find((l) => l.trimEnd() === "    steps:");
-    if (!stepsLine)
+    if (!stepsLine) {
+        console.error(picocolors_1.default.yellow(`skipped adding the Redis service to ${ciPath} — no \`steps:\` line at the expected indentation to anchor it to.\n` +
+            `Add a redis service to the workflow's \`services:\` block by hand, or CI will run without one.`));
         return;
+    }
     const service = [
         "      redis:",
         "        image: redis:7-alpine",

package/package.json

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

package/templates/create/base/Dockerfile.hbs

@@ -4,8 +4,10 @@
 #   docker build --target api    -t {{projectName}}-api .
 #   docker build --target worker -t {{projectName}}-worker .
 #
-# The worker target only builds once `go-scaffold add worker` has created
-# cmd/worker; until then `--target api` is the only one that resolves.
+# api is the last stage on purpose: a plain `docker build .` builds whatever
+# comes last, and that has to be the binary every project has. The worker
+# stage only resolves once `go-scaffold add worker` has created cmd/worker —
+# ask for it by name, and only then.
 FROM golang:1.25-alpine AS build
 WORKDIR /src
 
@@ -23,6 +25,12 @@ ENV CGO_ENABLED=0
 RUN go build -trimpath -ldflags="-s -w" -o /out/api ./cmd/api
 RUN if [ -d ./cmd/worker ]; then go build -trimpath -ldflags="-s -w" -o /out/worker ./cmd/worker; fi
 
+FROM gcr.io/distroless/static-debian12:nonroot AS worker
+WORKDIR /app
+COPY --from=build /out/worker /app/worker
+USER nonroot:nonroot
+ENTRYPOINT ["/app/worker"]
+
 # nonroot, and no shell: there is nothing in this image to exec into if
 # something gets in. Debug with `docker run --entrypoint` against the build
 # stage instead.
@@ -34,9 +42,3 @@ COPY --from=build /out/api /app/api
 USER nonroot:nonroot
 EXPOSE 8080
 ENTRYPOINT ["/app/api"]
-
-FROM gcr.io/distroless/static-debian12:nonroot AS worker
-WORKDIR /app
-COPY --from=build /out/worker /app/worker
-USER nonroot:nonroot
-ENTRYPOINT ["/app/worker"]

package/templates/create/base/README.md.hbs

@@ -166,15 +166,15 @@ TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=
 
 ## API spec
 
-`docs/openapi.yaml` is hand-written and served, along with every file it `$ref`s (`common/`, `health/`, per-domain folders), under `/docs` while the server runs — point a renderer (Scalar, Swagger UI, Redoc) or a client generator (Hey API) at `http://localhost:8080/docs/openapi.yaml`. Update the spec by hand whenever an endpoint/DTO changes.
+`docs/openapi.yaml` is hand-written and split across sibling files (`common/`, `health/`, per-domain folders) via relative `$ref`. **The server never serves it** — there is no `/docs` route, in any environment, so the API surface and `docs/architect/`'s internal notes stay off the wire. Update the spec by hand whenever an endpoint/DTO changes.
 
-Some tools don't resolve external `$ref`s when importing a local file — they read it as-is and see zero routes (Bruno's "Import Collection" does this; some Postman flows too). For those, bundle the spec into one fully-resolved file first:
+To open it in a renderer (Scalar, Swagger UI, Redoc) or a client generator (Hey API), bundle it into one fully-resolved file and point the tool at that file. Bundling is also what importers that don't resolve external `$ref`s need — they read the index as-is and see zero routes (Bruno's "Import Collection" does this; some Postman flows too):
 
 ```bash
 make openapi-bundle          # writes docs/openapi.bundled.yaml (gitignored — regenerate anytime)
 ```
 
-Import `docs/openapi.bundled.yaml` instead. Tools that resolve `$ref` over HTTP or when reading a URL (Scalar, Swagger UI, Redoc) don't need this — point them at the live `/docs/openapi.yaml` URL above.
+Then open `docs/openapi.bundled.yaml` — it needs no network and no running server.
 {{/if}}
 
 ## Adding a domain
@@ -197,6 +197,10 @@ docker build --target api    -t {{projectName}}-api .
 docker build --target worker -t {{projectName}}-worker .    # once `add worker` exists
 ```
 
+`api` is the last stage, so a plain `docker build .` builds it — the worker
+stage has to be asked for by name, and only resolves once `add worker` has
+created `cmd/worker`.
+
 Both stages are distroless and run as `nonroot`, so there is no shell in either
 image. Debug against the `build` stage instead:
 `docker run --rm -it --entrypoint sh $(docker build -q --target build .)`.

package/templates/create/base/cmd/api/wiring.go.hbs

@@ -89,17 +89,13 @@ func run() error {
 	})
 	// go-scaffold:extra-routes
 {{#if openapiDocs}}
-	// hand-written spec at docs/openapi.yaml, split across sibling files (common/, health/,
-	// <domain>/) via relative $ref — serve the whole tree under one prefix so a client that
-	// resolves $ref over HTTP (Scalar, Swagger UI, Redoc, Hey API pointed at a URL) can reach
-	// them too; StaticFile on just the index file would 404 on every $ref it follows.
-	//
-	// Not in production: this serves your whole API surface — every path,
-	// parameter and schema — to anyone who asks. Publish the spec deliberately
-	// (`make openapi-bundle`) rather than by leaving this on.
-	if !cfg.IsProd() {
-		r.Static("/docs", "./docs")
-	}
+	// ponytail: docs/ is deliberately NOT served over HTTP, in any environment.
+	// The whole tree — every path, parameter and schema, plus docs/architect/'s
+	// internal design notes — used to be reachable at /docs outside production.
+	// Read the spec from the working copy instead: `make openapi-bundle` writes
+	// one fully-resolved docs/openapi.bundled.yaml for a renderer or client
+	// generator to open as a local file. Publish it deliberately if you want
+	// it public.
 {{/if}}
 
 	api := r.Group("/{{apiPrefix}}")

package/templates/create/features/docs/architecture.md.hbs

@@ -104,9 +104,9 @@ insert, so it doesn't need `gen_random_uuid()`.
 ## 8. API Documentation
 
 **Decision:** Hand-written OpenAPI spec (`docs/openapi.yaml`), split by
-domain module, served under `/docs` (so relative `$ref`s to sibling files
-resolve over HTTP too — the index alone isn't enough for a renderer like
-Scalar/Swagger UI/Redoc to follow them).
+domain module, read from the working copy only — the server serves no `/docs`
+route in any environment. Renderers that follow relative `$ref`s get a
+fully-resolved single file from `make openapi-bundle`.
 **Rationale:** Cheap while the endpoint count is low; switch to
 comment-generated (swaggo) if hand-updates start drifting.
 {{/if}}
@@ -133,6 +133,15 @@ newer Gin (→ HTTP/3/quic-go) and every DB driver they support tracing for
 (MySQL, ClickHouse, MongoDB), respectively, for a Postgres-only project that
 only wants request/query spans.
 
+**Scope: `cmd/api` only.** `cmd/worker` is not instrumented. The GORM plugin
+lives in `database.Open`, which the worker also calls, so it does raise spans —
+but `telemetry.Init` is the only thing that calls `otel.SetTracerProvider` and
+it runs in `cmd/api` alone, so those spans reach a no-op provider and are
+discarded. The worker serves no `/metrics` either. To change that, call
+`telemetry.Init` from `cmd/worker/main.go` — split it into `main`/`run` first,
+the way `cmd/api` is, or the `defer` that flushes the exporter on shutdown is
+skipped by the `os.Exit` calls already in there.
+
 {{/if}}
 ## Evolution Notes
 

package/templates/create/features/docs/techstack.md.hbs

@@ -22,8 +22,8 @@
 - PostgreSQL + GORM baseline: always enabled
 - Graceful shutdown, structured logging, `/livez` + `/readyz`: always enabled
 - Docker Compose (local Postgres): `{{#if docker}}enabled{{else}}disabled{{/if}}`
-- OpenAPI docs (`docs/openapi.yaml`, whole `docs/` tree served at `/docs`): `{{#if openapiDocs}}enabled{{else}}disabled{{/if}}`
-- Metrics + tracing (Prometheus `/metrics`, OpenTelemetry for Gin + GORM): `{{#if observability}}enabled{{else}}disabled{{/if}}`
+- OpenAPI docs (`docs/openapi.yaml`, working-copy only — never served over HTTP): `{{#if openapiDocs}}enabled{{else}}disabled{{/if}}`
+- Metrics + tracing (Prometheus `/metrics`, OpenTelemetry for Gin + GORM, `cmd/api` only): `{{#if observability}}enabled{{else}}disabled{{/if}}`
 - API route prefix: `{{#if apiPrefix}}/{{apiPrefix}}{{else}}(none){{/if}}`
 - CI (`.github/workflows/ci.yml` — build, vet, gofmt check, golangci-lint, `go test` with a real Postgres service): always enabled