@nakedev/go-scaffold 0.1.3 → 0.3.0

package/dist/commands/undo.js

@@ -0,0 +1,331 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.undoModule = undoModule;
+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 config_1 = require("../utils/config");
+const naming_1 = require("../utils/naming");
+const module_location_1 = require("../utils/module-location");
+const main_patcher_1 = require("../utils/main-patcher");
+const openapi_patcher_1 = require("../utils/openapi-patcher");
+const golangci_patcher_1 = require("../utils/golangci-patcher");
+const template_renderer_1 = require("../utils/template-renderer");
+const gocheck_1 = require("../utils/gocheck");
+const generate_wizard_1 = require("../prompts/generate-wizard");
+// undoModule reverses a `generate module` that shouldn't have happened —
+// a typo'd name, a domain you decided against — by deleting everything it
+// created, migration files included.
+//
+// It deliberately does NOT try to retire a domain that is live somewhere.
+// The command this replaced claimed to ("a migration may already be recorded
+// in schema_migrations on production"), and that framing was wrong twice
+// over. Nobody decommissions a shipped domain by running a scaffolding CLI:
+// that needs a deprecation window, a data migration, and a drop migration
+// written by hand. Meanwhile the case people actually hit — undoing a module
+// generated thirty seconds ago — got the production treatment, so the typo's
+// migration survived forever. `migrations/embed.go` is a `//go:embed *`, so
+// that leftover then ran on every database anyone created from then on,
+// building a `oder_svc.oders` table nobody asked for.
+//
+// So: work out whether the migration could possibly have escaped this
+// machine. If it can't have, delete it. If it might have, refuse and say why.
+async function undoModule(rawName, opts, projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    const naming = (0, module_location_1.resolveProjectModuleNaming)(projectDir, rawName ?? (await (0, generate_wizard_1.promptExistingModule)((0, module_location_1.existingModulePackages)(projectDir), "undo")));
+    const modulePath = naming.pkg;
+    const moduleDir = path_1.default.join(projectDir, "internal", "app", modulePath);
+    if (!fs_extra_1.default.existsSync(moduleDir)) {
+        throw new Error(`module "${naming.pkg}" not found at internal/app/${modulePath} — nothing to undo`);
+    }
+    // `user` and `role` live under internal/app/ like any generated module, but
+    // they were wired by add auth / add rbac using entirely different line
+    // shapes — this command would delete the package and then silently fail to
+    // un-wire most of it, leaving main.go and cmd/seed referencing a package
+    // that no longer exists. findDependents can't catch it either: the
+    // consumer-side-interface convention means `user` never imports `role`.
+    const featureOwner = { user: "auth", role: "rbac" };
+    const owner = featureOwner[modulePath];
+    if (owner && config.features[owner]) {
+        throw new Error(`"${modulePath}" belongs to \`go-scaffold add ${owner}\`, not to \`generate module\` — refusing to undo it.\n` +
+            `Its wiring in cmd/api/wiring.go (and cmd/seed, docs/openapi.yaml) doesn't match what this command knows how to reverse,\n` +
+            `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 { checkedDatabase } = assertMigrationsNeverEscaped(projectDir, migrations, naming.pkg);
+    if (!opts.yes) {
+        const ok = await (0, prompts_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.`,
+            default: false,
+        });
+        if (!ok)
+            throw new Error("undo 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];
+    }
+    // Refuse if another domain still imports this one. Deleting it anyway
+    // leaves the project un-compilable, and the error Go reports then points at
+    // the surviving module rather than at the removal that caused it.
+    const dependents = findDependents(projectDir, config.goModule, modulePath);
+    if (dependents.length > 0) {
+        throw new Error(`module "${naming.pkg}" is still used by: ${dependents.join(", ")}\n` +
+            `remove those references (or the modules themselves) first — deleting internal/app/${modulePath} now would break the build`);
+    }
+    const before = (0, gocheck_1.typeChecks)(projectDir);
+    // Un-wire before deleting, not after. Every step below can throw — a
+    // hand-edited wiring.go with the routes marker gone is enough — and if the
+    // package is already gone by then, the user's own code inside it is
+    // unrecoverable outside of git. This order fails the other way round: a
+    // still-present package with its wiring removed, which `generate module`
+    // re-wires idempotently.
+    // 1. wiring.go
+    (0, main_patcher_1.unpatchMainGo)(path_1.default.join(projectDir, "cmd", "api", "wiring.go"), {
+        goModule: config.goModule,
+        modulePath,
+        pkg: naming.pkg,
+        pascalName: naming.pascalName,
+        schemaName: naming.schemaName,
+        auth,
+        permission,
+    });
+    (0, golangci_patcher_1.unpatchGolangciForModule)(path_1.default.join(projectDir, ".golangci.yml"), modulePath);
+    // 2. openapi index + per-module docs
+    const openapiPath = path_1.default.join(projectDir, "docs", "openapi.yaml");
+    if (fs_extra_1.default.existsSync(openapiPath)) {
+        (0, openapi_patcher_1.unpatchOpenapiIndex)(openapiPath, naming, config.apiPrefix);
+        fs_extra_1.default.removeSync(path_1.default.join(projectDir, "docs", naming.plural));
+    }
+    // 3. the migrations — safe to delete, assertMigrationsNeverEscaped proved
+    // above that they exist nowhere but this working tree
+    for (const file of migrations)
+        fs_extra_1.default.removeSync(path_1.default.join(migrationsDir, file));
+    // 4. the domain package — last, once nothing left can fail
+    fs_extra_1.default.removeSync(moduleDir);
+    (0, template_renderer_1.gofmtTree)(projectDir);
+    (0, gocheck_1.assertNoDrift)(projectDir, before, config, {
+        didWhat: `undid module "${naming.pkg}"`,
+        recover: `internal/app/${modulePath}/ is gone; re-run \`go-scaffold generate module ${naming.pkg}\` to put it\nback, then reconcile cmd/api/wiring.go by hand.`,
+    });
+    console.log(picocolors_1.default.green(`\nundid module "${naming.pkg}"`));
+    console.log(`  deleted internal/app/${modulePath}/`);
+    console.log(`  un-wired cmd/api/wiring.go`);
+    if (fs_extra_1.default.existsSync(openapiPath))
+        console.log(`  un-wired docs/openapi.yaml + deleted docs/${naming.plural}/`);
+    if (migrations.length)
+        console.log(`  deleted migrations/${migrations.join(", migrations/")}`);
+    if (migrations.length && !checkedDatabase) {
+        console.log(picocolors_1.default.yellow(`\ncouldn't check whether those migrations had already been applied — no reachable DB_DSN,\n` +
+            `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.`));
+    }
+    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) {
+    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();
+}
+// assertMigrationsNeverEscaped is what lets undo delete migration files at
+// all. A migration that has only ever existed in this working tree cannot be
+// recorded in any other environment's schema_migrations, so removing it can't
+// make two databases disagree. Two ways it could have escaped:
+//
+//   1. it's committed — then it's in whatever anyone pulled or deployed
+//   2. it's applied to the database this project is pointed at
+//
+// A project with no git repository at all has never been pushed anywhere, so
+// "git doesn't know this file" covers it.
+//
+// The git half is the one that has to be right: it's what decides whether a
+// migration could be in someone else's database. The database half only ever
+// protects the developer's own dev database, and that damage is recoverable
+// (`migrate force`), so an unreachable database doesn't block the command —
+// it reports back that it couldn't check, and the caller says so.
+function assertMigrationsNeverEscaped(projectDir, migrations, pkg) {
+    if (migrations.length === 0)
+        return { checkedDatabase: true };
+    const known = migrations.filter((f) => gitKnowsAbout(projectDir, path_1.default.join("migrations", f)));
+    if (known.length) {
+        throw new Error(`git knows about these migrations, so they may already have been applied somewhere:\n` +
+            known.map((f) => `  migrations/${f}`).join("\n") +
+            `\n\n\`undo\` is for a module you generated and immediately regretted — it deletes migration\n` +
+            `files, which is only safe while they exist nowhere but this working tree. To retire a domain\n` +
+            `that has shipped, leave its history alone and write the reversal explicitly:\n` +
+            `  go-scaffold generate migration drop_${pkg}`);
+    }
+    // Check every database this project could mean, not just the first one
+    // found: an exported DB_DSN left over in the shell would otherwise shadow
+    // the project's own .env and answer for the wrong database entirely.
+    let checkedDatabase = true;
+    for (const dsn of candidateDsns(projectDir)) {
+        const applied = appliedVersion(projectDir, dsn);
+        if (applied === null) {
+            checkedDatabase = false;
+            continue;
+        }
+        const escaped = migrations.filter((f) => Number(f.split("_")[0]) <= applied);
+        if (escaped.length) {
+            throw new Error(`these migrations have already been applied to your database (schema_migrations is at ${applied}):\n` +
+                escaped.map((f) => `  migrations/${f}`).join("\n") +
+                `\n\nDeleting the files now would leave the database recorded at a version with no migration\n` +
+                `behind it, and golang-migrate would refuse to move from there. Roll them back first:\n` +
+                `  migrate -path migrations -database "$DB_DSN" down ${escaped.length / 2 || 1}\n` +
+                `then run this again.`);
+        }
+    }
+    return { checkedDatabase };
+}
+// gitKnowsAbout asks both questions, because either one means the file has
+// left this working tree. The index alone isn't enough: a file that was
+// committed and later `git rm --cached`'d is untracked now but is still in
+// history, and in anything anyone has pulled.
+function gitKnowsAbout(projectDir, relativePath) {
+    if (runsClean(projectDir, ["ls-files", "--error-unmatch", relativePath]))
+        return true;
+    const inHistory = (0, child_process_1.spawnSync)("git", ["log", "--all", "--max-count=1", "--format=%H", "--", relativePath], {
+        cwd: projectDir,
+        encoding: "utf8",
+    });
+    return !inHistory.error && inHistory.status === 0 && inHistory.stdout.trim() !== "";
+}
+function runsClean(projectDir, args) {
+    try {
+        (0, child_process_1.execFileSync)("git", args, { cwd: projectDir, stdio: "ignore" });
+        return true;
+    }
+    catch {
+        // not tracked, or not a git repository at all
+        return false;
+    }
+}
+// appliedVersion reads schema_migrations through the migrate CLI the project
+// already documents. Returns null when it can't tell — no migrate on PATH, no
+// DB_DSN, database unreachable, or nothing applied yet.
+function appliedVersion(projectDir, dsn) {
+    // spawnSync, not execFileSync: `migrate version` prints the version on
+    // stderr and still exits 0, and execFileSync only hands back stdout. That
+    // read as "" -> Number("") -> 0 -> "nothing applied yet", which waved every
+    // migration straight through the check this function exists to perform.
+    //
+    // The timeout matters as much: a DSN pointing at an unroutable host makes
+    // migrate sit on the OS TCP timeout, and the CLI froze for 77 seconds with
+    // no output before carrying on anyway.
+    const res = (0, child_process_1.spawnSync)("migrate", ["-path", "migrations", "-database", dsn, "version"], {
+        cwd: projectDir,
+        encoding: "utf8",
+        timeout: 5000,
+    });
+    if (res.error)
+        return null; // no migrate on PATH, or it timed out
+    const output = `${res.stderr ?? ""}\n${res.stdout ?? ""}`;
+    // a database that has never been migrated is a definitive "nothing
+    // applied", not an inconclusive answer
+    if (/no migration/i.test(output))
+        return 0;
+    return parseVersion(output);
+}
+// parseVersion pulls the bare version number out of migrate's output, and
+// insists on actually finding one: anything else (a connection error, a
+// "dirty" marker, an empty string) has to read as "can't tell", never as 0.
+function parseVersion(output) {
+    const match = output.trim().match(/^(\d+)/m);
+    return match ? Number(match[1]) : null;
+}
+// dsnFromEnvFile reads DB_DSN out of .env the same way the generated Makefile
+// does, and tolerates the two spellings people actually write: a quoted value,
+// and a leading `export`. Getting either wrong doesn't fail loudly — it hands
+// `migrate` a DSN it can't parse, appliedVersion then reports "can't tell",
+// and the applied-migrations guard is skipped entirely. Both forms silently
+// defeated it.
+// candidateDsns returns every database this project might mean, deduped. Both
+// are checked rather than just the first: an exported DB_DSN pointing at some
+// other environment would otherwise shadow the project's own .env and answer
+// the applied-migrations question about the wrong database.
+function candidateDsns(projectDir) {
+    const found = [process.env.DB_DSN, dsnFromEnvFile(projectDir)].filter((d) => Boolean(d));
+    return [...new Set(found)];
+}
+function dsnFromEnvFile(projectDir) {
+    const envPath = path_1.default.join(projectDir, ".env");
+    if (!fs_extra_1.default.existsSync(envPath))
+        return undefined;
+    const match = fs_extra_1.default.readFileSync(envPath, "utf8").match(/^[ \t]*(?:export[ \t]+)?DB_DSN[ \t]*=[ \t]*(.*)$/m);
+    if (!match)
+        return undefined;
+    let value = match[1].trim();
+    const quote = value[0];
+    if (quote === '"' || quote === "'") {
+        // a quoted value ends at its closing quote; anything after it is a comment
+        const end = value.indexOf(quote, 1);
+        value = end === -1 ? value.slice(1) : value.slice(1, end);
+    }
+    else {
+        // unquoted: strip a trailing ` # comment`, matching the Makefile's
+        // sed -E 's/[[:space:]]+#.*$//'. Not a bare `#` — that's legal in a URL.
+        value = value.replace(/[ \t]+#.*$/, "").trim();
+    }
+    return value || undefined;
+}
+// findDependents lists the .go files in *other* domains that import this one.
+// Import path match, not a bare package-name match: `orders` appears in plenty
+// of strings and comments, but only an import of
+// "<goModule>/internal/app/orders" is a real compile-time dependency.
+function findDependents(projectDir, goModule, modulePath) {
+    // The package itself, or one of its subpackages — and nothing else. Dropping
+    // the closing quote to catch `/model` was matching on a bare prefix too, so
+    // `undo module order` was refused by every module whose name merely starts
+    // with it: internal/app/orderitem imports nothing from internal/app/order,
+    // but the second path contains the first.
+    const base = `"${goModule}/internal/app/${modulePath}`;
+    const importsIt = (src) => src.includes(`${base}"`) || src.includes(`${base}/`);
+    const appDir = path_1.default.join(projectDir, "internal", "app");
+    const hits = [];
+    for (const pkg of (0, module_location_1.existingModulePackages)(projectDir)) {
+        if (pkg === modulePath)
+            continue;
+        for (const file of goFilesIn(path_1.default.join(appDir, pkg))) {
+            if (importsIt(fs_extra_1.default.readFileSync(file, "utf8"))) {
+                hits.push(path_1.default.relative(projectDir, file));
+            }
+        }
+    }
+    return hits;
+}
+function goFilesIn(dir) {
+    if (!fs_extra_1.default.existsSync(dir))
+        return [];
+    return fs_extra_1.default.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const full = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory())
+            return goFilesIn(full);
+        return entry.name.endsWith(".go") ? [full] : [];
+    });
+}

package/dist/commands/worker.js

@@ -11,65 +11,125 @@ 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
+const gocheck_1 = require("../utils/gocheck");
+const gomod_patcher_1 = require("../utils/gomod-patcher");
+const auth_patcher_1 = require("../utils/auth-patcher");
+// addWorker scaffolds async job processing: the backend-neutral queue
+// contract (platform/queue), one adapter for the chosen backing store, SMTP
+// mail (platform/mail, with an email:send job as the one thing a 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()) {
+// don't need a queue on day one, and an empty worker with no job kinds
+// registered is a stranger scaffold than not having one.
+async function addWorker(backend, 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"));
+    const parsedBefore = (0, gocheck_1.parseChecks)(projectDir);
+    const riverQueue = backend === "river";
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, (0, worker_manifest_1.workerFiles)(backend), { goModule: config.goModule, riverQueue });
+    (0, platform_patcher_1.patchConfigForWorker)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"), { redis: !riverQueue });
+    if (!riverQueue) {
+        (0, platform_patcher_1.patchMainGoForWorker)(path_1.default.join(projectDir, "cmd", "api", "wiring.go"), config.goModule);
+        (0, platform_patcher_1.patchComposeForRedis)(path_1.default.join(projectDir, "docker-compose.yml"));
+        (0, platform_patcher_1.patchCiForRedis)(path_1.default.join(projectDir, ".github", "workflows", "ci.yml"));
+    }
+    // pinned to what this scaffold was written against — see gomod-patcher
+    (0, gomod_patcher_1.patchGoModRequires)(path_1.default.join(projectDir, "go.mod"), riverQueue
+        ? ["github.com/riverqueue/river v0.43.0", "github.com/riverqueue/river/riverdriver/riverdatabasesql v0.43.0"]
+        : ["github.com/hibiken/asynq v0.26.0", "github.com/redis/go-redis/v9 v9.22.0"]);
+    // auth added before the worker wired a synchronous mailer — now that there
+    // is a queue, move it onto it
+    const mailerUpgraded = (0, auth_patcher_1.upgradeMailerToQueue)(path_1.default.join(projectDir, "cmd", "api", "wiring.go"), config.goModule, backend);
+    patchEnvExample(path_1.default.join(projectDir, ".env.example"), { redis: !riverQueue });
+    patchMakefile(path_1.default.join(projectDir, "Makefile"), { river: riverQueue });
     (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"));
+    // parse-only: river/asynq aren't in go.mod until the user runs `go mod
+    // tidy`, so `go vet` can't be the gate here.
+    (0, gocheck_1.assertStillParses)(projectDir, parsedBefore, `added worker (${backend})`);
+    (0, config_1.writeConfig)(projectDir, { ...config, features: { ...config.features, worker: true, queue: backend } });
+    console.log(picocolors_1.default.green(`\nadded internal/platform/{queue,mail}/ and cmd/worker/ (queue backend: ${backend})`));
+    if (riverQueue) {
+        console.log("jobs are rows in your Postgres — no extra service, and an enqueue inside tx.Do commits with it");
+        console.log(picocolors_1.default.dim("\nnext: make river-migrate (creates River's tables), then make worker"));
+    }
+    else {
+        console.log(mailerUpgraded
+            ? "wired Redis into cmd/api (readyz check) — auth's mailer now enqueues onto it instead of blocking on SMTP"
+            : "wired Redis into cmd/api (readyz check) — cmd/api does not enqueue anything yet");
+        console.log(picocolors_1.default.yellow("note: a Redis enqueue cannot join a database transaction — see the warning on queue.Asynq"));
+        console.log(picocolors_1.default.dim("\nnext: make worker (separate terminal, or `make dev` runs both), then go build ./... to confirm"));
+    }
 }
-function patchEnvExample(envExamplePath) {
+// needsSmtp and needsRedis are checked independently: `add auth` run without
+// a worker already writes SMTP_HOST on its own (auth stands alone — see
+// addAuth), so by the time a Redis-backed worker arrives after it, the old
+// single `if (content.includes("SMTP_HOST")) return` guard fired on the SMTP
+// block alone and quietly skipped the Redis block right along with it —
+// REDIS_URL never made it into .env.example even though config.go now reads
+// it. Each block gets its own guard so one being done doesn't hide the other.
+function patchEnvExample(envExamplePath, opts) {
     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" +
+    const needsRedis = opts.redis && !content.includes("REDIS_URL");
+    const needsSmtp = !content.includes("SMTP_HOST");
+    if (!needsRedis && !needsSmtp)
+        return; // both already added
+    content = content.replace(/\n?$/, "\n");
+    if (needsRedis) {
+        content += "\nREDIS_URL=redis://localhost:6379/0\n";
+    }
+    if (needsSmtp) {
+        content +=
             "\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";
+                "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) {
+function patchMakefile(makefilePath, opts) {
     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 ");
+    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
+    // by nothing on purpose: it is a one-shot setup command, not a build input.
+    const riverTarget = opts.river
+        ? "\n# create River's job tables (run once per database, and after upgrading River)\n" +
+            "river-migrate:\n" +
+            "\t@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; \\\n" +
+            '\tgo run github.com/riverqueue/river/cmd/river@latest migrate-up --line main --database-url "$$DB_DSN"\n'
+        : "";
+    // Both load config exactly the way Makefile.hbs says every target does:
+    // via $(ENV_FILE), and through the same sed that strips trailing comments.
+    // Without it, .env.example's own `APP_ENV=development  # prod: production`
+    // reaches `export` as a bare `#` and prints an error on every run.
+    const loadEnv = "@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a;";
     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${loadEnv} \\\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" +
+        `# background worker for async job processing (email, ...) — requires ${opts.river ? "Postgres (make river-migrate first)" : "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:`);
+        `\t${loadEnv} go run ./cmd/worker\n` +
+        riverTarget;
+    // Function replacer: targets contains literal "$$" (Make's escape for a
+    // shell "$") which String.replace would otherwise collapse to a single "$"
+    // when the replacement is a plain string — turning "$$DB_DSN" into
+    // "$DB_DSN" and silently handing the wrong value to every command below.
+    content = content.replace(/\nbuild:/, () => `${targets}\nbuild:`);
     fs_extra_1.default.writeFileSync(makefilePath, content);
 }