@nakedev/go-scaffold 0.4.0 → 0.5.0

package/dist/commands/method.js

@@ -10,13 +10,13 @@ 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 migrations_1 = require("../utils/migrations");
 const openapi_patcher_1 = require("../utils/openapi-patcher");
 const generate_wizard_1 = require("../prompts/generate-wizard");
-// URL path registered in method-patcher.ts, excluding the project-wide API
+const hexagonal_method_patcher_1 = require("../utils/hexagonal-method-patcher");
+// URL path registered in the inbound adapter, 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}`;
@@ -51,105 +51,116 @@ function methodOpenapiDocument(naming, method, type, getMode, field) {
     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") {
+    const status = type === "delete" ? "204" : type === "post" ? "201" : type === "put" || type === "patch" ? "501" : "200";
+    operation.push("  responses:", `    \"${status}\":`, `      description: ${type === "delete" ? "completed or already absent" : type === "put" || type === "patch" ? "not implemented" : "TODO define response"}`);
+    if (type !== "delete" && type !== "put" && type !== "patch") {
         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") {
+    if (type === "get") {
         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, module_location_1.resolveProjectModuleNaming)(projectDir, moduleNameArg ?? (await (0, generate_wizard_1.promptExistingModule)((0, module_location_1.existingModulePackages)(projectDir), "add a method to")));
-    const modulePath = naming.pkg;
-    const moduleDir = path_1.default.join(projectDir, "internal", "app", modulePath);
+async function generateHexagonalMethod(config, naming, methodNameArg, opts, projectDir) {
+    const moduleDir = path_1.default.join(projectDir, "internal", "app", naming.pkg);
+    const moduleConfig = config.modules[naming.pkg];
+    if (!moduleConfig) {
+        throw new Error("module " + naming.pkg + " has no split-layout metadata in go-scaffold.config.json; run go-scaffold check first");
+    }
+    const cqrs = moduleConfig.applicationStyle === "cqrs";
+    const authModule = naming.pkg === "user" && fs_extra_1.default.existsSync(path_1.default.join(moduleDir, "application", "contracts.go"));
     const paths = {
-        dtoPath: path_1.default.join(moduleDir, "dto.go"),
-        repositoryPath: path_1.default.join(moduleDir, "repository.go"),
-        servicePath: path_1.default.join(moduleDir, "service.go"),
-        handlerPath: path_1.default.join(moduleDir, "handler.go"),
-        serviceTestPath: path_1.default.join(moduleDir, "service_test.go"),
+        dtoPath: path_1.default.join(moduleDir, "application", "dto.go"),
+        requestDTOPath: path_1.default.join(moduleDir, "adapters", "inbound", "http", "dto.go"),
+        portsPath: path_1.default.join(moduleDir, "ports", "repository.go"),
+        repositoryAdapterPath: path_1.default.join(moduleDir, "adapters", "outbound", "postgres", "repository.go"),
+        servicePath: cqrs ? undefined : path_1.default.join(moduleDir, "application", "service.go"),
+        commandPath: cqrs ? path_1.default.join(moduleDir, "application", "commands.go") : undefined,
+        queryPath: cqrs ? path_1.default.join(moduleDir, "application", "queries.go") : undefined,
+        handlerPath: path_1.default.join(moduleDir, "adapters", "inbound", "http", "handler.go"),
+        serviceTestPath: path_1.default.join(moduleDir, "application", moduleConfig.applicationStyle === "cqrs" ? "cqrs_test.go" : "service_test.go"),
+        ...(authModule
+            ? {
+                repositoryModelType: "User",
+                repositoryToDomain: "toDomainUser",
+                repositoryErrorMapper: "persistenceError",
+                repositoryStubReceiver: "f *fakeRepo",
+                handlerErrorMapper: "toHTTPError",
+            }
+            : {}),
     };
-    for (const p of Object.values(paths)) {
-        if (!fs_extra_1.default.existsSync(p)) {
-            throw new Error(`module "${naming.pkg}" not found at ${moduleDir} (missing ${path_1.default.basename(p)}) — ` +
-                `run \`go-scaffold generate module ${naming.pkg}\` first`);
-        }
+    const required = [
+        paths.dtoPath,
+        paths.requestDTOPath,
+        paths.portsPath,
+        paths.repositoryAdapterPath,
+        paths.handlerPath,
+        paths.serviceTestPath,
+        ...(cqrs ? [paths.commandPath, paths.queryPath] : [paths.servicePath]),
+    ];
+    const missing = required.filter((file) => !fs_extra_1.default.existsSync(file));
+    if (missing.length) {
+        throw new Error("module " +
+            naming.pkg +
+            " is not a complete hexagonal split module (missing " +
+            missing.map((file) => path_1.default.relative(projectDir, file)).join(", ") +
+            "); run go-scaffold check");
     }
     const type = opts.type ?? (await (0, generate_wizard_1.promptMethodType)());
-    if (opts.getMode && type !== "get") {
+    if (opts.getMode && type !== "get")
         throw new Error("--get-mode can only be used with --type get");
-    }
-    if (opts.field && !(type === "get" && opts.getMode === "one")) {
+    if (opts.field && !(type === "get" && opts.getMode === "one"))
         throw new Error("--field can only be used with --type get --get-mode one");
-    }
     const getMode = type === "get" ? opts.getMode ?? (await (0, generate_wizard_1.promptGetMode)()) : undefined;
     const field = type === "get" && getMode === "one" ? opts.field ?? (await (0, generate_wizard_1.promptLookupField)()) : undefined;
-    // field becomes a Go param name (`func (...)(ctx, <field> string)`) and a
-    // column name in the generated `WHERE <field> = ?`
     if (field)
         (0, naming_1.assertGoIdentifier)((0, naming_1.toCamelCase)(field), "lookup field");
     const method = (0, naming_1.resolveMethodNaming)(methodNameArg ?? (await (0, generate_wizard_1.promptMethodName)()));
-    // Every marker this command patches has to exist before the first write:
-    // patchMethod writes dto.go, then handler.go, then reads service.go, so a
-    // missing service marker used to leave two files patched and the method
-    // permanently un-retryable (assertNotDuplicate then sees it as existing).
-    if (!(0, method_patcher_1.markersPresent)(paths.handlerPath, paths.servicePath)) {
-        throw new Error(`internal/app/${naming.pkg} is missing the marker comments \`generate method\` patches at.\n` +
-            `handler.go and service.go must both still carry their \`// go-scaffold:*\` markers —\n` +
-            `restore them, or add this method by hand.`);
+    if (!(0, hexagonal_method_patcher_1.hexagonalMarkersPresent)(paths)) {
+        throw new Error("internal/app/" + naming.pkg + " is missing a split-layout generate-method marker; restore the go-scaffold markers or edit this endpoint 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;
+    (0, hexagonal_method_patcher_1.assertHexagonalMethodAbsent)(paths, method);
+    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}`);
+        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, hexagonal_method_patcher_1.patchHexagonalMethod)(paths, naming, method, { type, getMode, field }, config.goModule);
     (0, template_renderer_1.gofmtTree)(projectDir);
     (0, gocheck_1.assertNoDrift)(projectDir, checkBefore, config);
-    // A --field lookup queries a column the table doesn't have yet. GORM builds
-    // that SQL at runtime, so nothing before the first real request notices:
-    // the build passes, vet passes, the generated tests pass. Ship the column
-    // and its index with the code that needs them.
     let fieldMigration = "";
     if (field) {
         const migrationsDir = path_1.default.join(projectDir, "migrations");
         fieldMigration = (0, migrations_1.newMigrationVersion)(migrationsDir);
         const fieldColumn = (0, naming_1.toDbName)(field);
         await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
-            { template: "generate/module/field-column.up.sql.hbs", output: path_1.default.join("migrations", `${fieldMigration}_add_${naming.tableName}_${fieldColumn}.up.sql`) },
-            { template: "generate/module/field-column.down.sql.hbs", output: path_1.default.join("migrations", `${fieldMigration}_add_${naming.tableName}_${fieldColumn}.down.sql`) },
-        ], { ...naming, pkg: naming.pkg, methodName: method.name, fieldColumn });
+            { template: "generate/module/field-column.up.sql.hbs", output: path_1.default.join("migrations", fieldMigration + "_add_" + naming.tableName + "_" + fieldColumn + ".up.sql") },
+            { template: "generate/module/field-column.down.sql.hbs", output: path_1.default.join("migrations", fieldMigration + "_add_" + naming.tableName + "_" + fieldColumn + ".down.sql") },
+        ], { ...naming, methodName: method.name, fieldColumn });
     }
     if (fieldMigration) {
-        console.log(`migration: migrations/${fieldMigration}_add_${naming.tableName}_${(0, naming_1.toDbName)(field)}.{up,down}.sql ` +
-            `(adds the column the lookup queries, plus an index on it — check the type before applying)`);
+        console.log("migration: migrations/" + fieldMigration + "_add_" + naming.tableName + "_" + (0, naming_1.toDbName)(field) + ".{up,down}.sql (adds the column the lookup queries, plus an index on it; check the type before applying)");
     }
     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}`,
-            },
+            { 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 (docsRelativePath) {
-        console.log(picocolors_1.default.green(`docs: docs/${docsRelativePath} (wired into docs/openapi.yaml)`));
+    console.log(picocolors_1.default.green("\nadded \"" + method.name + "\" to internal/app/" + naming.pkg + "/"));
+    console.log("route: " + routeHint(naming, method, type, config.apiPrefix, getMode, field));
+    if (docsRelativePath)
+        console.log(picocolors_1.default.green("docs: docs/" + docsRelativePath + " (wired into docs/openapi.yaml)"));
+    const implementationFile = cqrs ? "application/" + (type === "get" ? "queries.go" : "commands.go") : "application/service.go";
+    console.log(picocolors_1.default.dim("\nnext: fill in the TODO in " + implementationFile + ", then go build ./... / go test ./..."));
+}
+async function generateMethod(moduleNameArg, methodNameArg, opts, projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    const naming = (0, module_location_1.resolveProjectModuleNaming)(projectDir, moduleNameArg ?? (await (0, generate_wizard_1.promptExistingModule)((0, module_location_1.existingModulePackages)(projectDir), "add a method to")));
+    if (config.architecture.packageLayout !== "split") {
+        throw new Error("this scaffold only supports the canonical hexagonal split layout");
     }
-    console.log(picocolors_1.default.dim(`\nnext: fill in the TODO in service.go, then \`go build ./...\` / \`go test ./...\``));
+    await generateHexagonalMethod(config, naming, methodNameArg, opts, projectDir);
 }

package/dist/commands/migration.js

@@ -29,6 +29,6 @@ async function generateMigration(rawName, projectDir = process.cwd()) {
     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)`));
+    console.log(picocolors_1.default.dim(`\nnext: write the SQL, then apply it with \`make migrate-up\` before production ` +
+        `(APP_ENV=development only enables the convenience bootstrap)`));
 }

package/dist/commands/observability.js

@@ -13,6 +13,7 @@ const observability_manifest_1 = require("../templates/observability-manifest");
 const observability_patcher_1 = require("../utils/observability-patcher");
 const gocheck_1 = require("../utils/gocheck");
 const gomod_patcher_1 = require("../utils/gomod-patcher");
+const docs_patcher_1 = require("../utils/docs-patcher");
 // addObservability scaffolds Prometheus metrics (GET /metrics) and
 // OpenTelemetry tracing for Gin + GORM, wiring both into the files `create`
 // already wrote. Opt-in and separate from `create`: most projects don't want
@@ -52,7 +53,7 @@ async function addObservability(projectDir = process.cwd(), opts = {}) {
     // docs saying `enabled` while the config it never reached still said false —
     // a disagreement no later command could converge, since the "already added"
     // guard then blocks a re-run.
-    const staleDocs = refreshArchitectDocs(projectDir, config);
+    const staleDocs = (0, docs_patcher_1.refreshProjectDocs)(projectDir, config, { observability: true });
     (0, config_1.writeConfig)(projectDir, { ...config, features: { ...config.features, observability: true } });
     if (opts.silent)
         return;
@@ -66,57 +67,7 @@ async function addObservability(projectDir = process.cwd(), opts = {}) {
     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
-        // dependency versions — so every release that bumps one makes every
-        // project scaffolded before it look edited. Which is exactly the
-        // population this function exists for.
-        console.log(picocolors_1.default.yellow(`\nnote: couldn't safely rewrite ${staleDocs.join(" and ")} — ` +
-            `${staleDocs.length > 1 ? "they don't" : "it doesn't"} match what this go-scaffold\n` +
-            `  would have generated, so ${staleDocs.length > 1 ? "they were" : "it was"} left alone rather than overwriting your edits.\n` +
-            `  ${staleDocs.length > 1 ? "They still describe" : "It still describes"} this project as having no metrics or tracing; update by hand.`));
-    }
+    if (staleDocs.length)
+        console.log(picocolors_1.default.yellow((0, docs_patcher_1.docsRefreshWarning)(staleDocs, "add observability")));
     console.log(picocolors_1.default.dim("\nnext: go mod tidy, then set OTEL_EXPORTER_OTLP_ENDPOINT to export traces (empty = tracing no-ops, /metrics works either way)"));
 }
-// The architecture docs gate their observability sections on a `create`-time
-// flag, so adding the feature afterwards used to leave techstack.md saying
-// `disabled` and architecture.md missing the section entirely — while the
-// README promises `create --observability` and this command produce the same
-// project.
-//
-// Re-rendering from the templates rather than string-patching keeps the prose
-// in one place (the .hbs), but would also silently discard a user's edits. So
-// it first renders what the file *should* look like today, with observability
-// still off: only a byte-for-byte match proves nobody has touched it. Returns
-// the docs it declined to overwrite, for the caller to warn about.
-function refreshArchitectDocs(projectDir, config) {
-    const docs = [
-        { template: "create/features/docs/architecture.md.hbs", output: path_1.default.join("docs", "architect", "architecture.md") },
-        { template: "create/features/docs/techstack.md.hbs", output: path_1.default.join("docs", "architect", "techstack.md") },
-    ];
-    // only what the two templates actually reference — projectName, apiPrefix
-    // and the feature flags
-    const base = { projectName: config.projectName, apiPrefix: config.apiPrefix, ...config.features };
-    const root = (0, template_renderer_1.getTemplatesRoot)();
-    const skipped = [];
-    for (const doc of docs) {
-        const outputPath = path_1.default.join(projectDir, doc.output);
-        if (!fs_extra_1.default.existsSync(outputPath))
-            continue;
-        const source = fs_extra_1.default.readFileSync(path_1.default.join(root, doc.template), "utf8");
-        // compare with line endings normalised — a Windows checkout with
-        // core.autocrlf=true would otherwise never match, and the feature would
-        // silently never fire there
-        const onDisk = lf(fs_extra_1.default.readFileSync(outputPath, "utf8"));
-        if (onDisk !== lf((0, template_renderer_1.renderString)(source, { ...base, observability: false }))) {
-            skipped.push(doc.output);
-            continue;
-        }
-        fs_extra_1.default.writeFileSync(outputPath, (0, template_renderer_1.renderString)(source, { ...base, observability: true }));
-    }
-    return skipped;
-}
-function lf(text) {
-    return text.replace(/\r\n/g, "\n");
-}

package/dist/commands/rbac.js

@@ -15,6 +15,7 @@ const rbac_patcher_1 = require("../utils/rbac-patcher");
 const openapi_patcher_1 = require("../utils/openapi-patcher");
 const golangci_patcher_1 = require("../utils/golangci-patcher");
 const gocheck_1 = require("../utils/gocheck");
+const docs_patcher_1 = require("../utils/docs-patcher");
 // URL (relative to the api prefix) -> docs file (relative to docs/) for every
 // route `add rbac` registers or adds onto the user handler.
 const RBAC_OPENAPI_PATHS = [
@@ -58,14 +59,14 @@ async function addRbac(projectDir = process.cwd()) {
         { template: "add/rbac/migrations/add_roles.down.sql.hbs", output: path_1.default.join("migrations", `${version}_add_roles.down.sql`) },
     ], {});
     (0, rbac_patcher_1.patchConfigForRbac)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"));
-    (0, rbac_patcher_1.patchUserModelForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "model", "user.go"));
+    (0, rbac_patcher_1.patchUserModelForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "adapters", "outbound", "postgres", "model.go"));
     (0, rbac_patcher_1.patchMiddlewareAuthForRbac)(path_1.default.join(projectDir, "internal", "shared", "middleware", "auth.go"));
-    (0, rbac_patcher_1.patchUserJWTForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "jwt.go"));
-    (0, rbac_patcher_1.patchUserServiceForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "service.go"));
-    (0, rbac_patcher_1.patchUserServiceTestForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "service_test.go"));
-    (0, rbac_patcher_1.patchUserDTOForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "dto.go"));
-    (0, rbac_patcher_1.patchUserHandlerForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "handler.go"), config.goModule);
-    (0, rbac_patcher_1.patchUserErrorsForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "errors.go"));
+    (0, rbac_patcher_1.patchUserJWTForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "application", "jwt.go"));
+    (0, rbac_patcher_1.patchUserServiceForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "application", "service.go"), path_1.default.join(projectDir, "internal", "app", "user", "application", "sessions.go"));
+    (0, rbac_patcher_1.patchUserServiceTestForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "application", "service_test.go"));
+    (0, rbac_patcher_1.patchUserDTOForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "adapters", "inbound", "http", "dto.go"));
+    (0, rbac_patcher_1.patchUserHandlerForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "adapters", "inbound", "http", "handler.go"));
+    (0, rbac_patcher_1.patchUserErrorsForRbac)(path_1.default.join(projectDir, "internal", "app", "user", "application", "errors.go"));
     (0, golangci_patcher_1.patchGolangciForModule)(path_1.default.join(projectDir, ".golangci.yml"), config.goModule, "role");
     // projects scaffolded before --store existed are all Redis-backed
     (0, rbac_patcher_1.patchMainGoForRbac)(path_1.default.join(projectDir, "cmd", "api", "wiring.go"), config.goModule, config.features.authStore ?? "redis", config.features.worker ?? false);
@@ -94,12 +95,22 @@ async function addRbac(projectDir = process.cwd()) {
         didWhat: "added RBAC",
         recover: "internal/app/role/ and the rbac patches were left in place — reconcile cmd/api/wiring.go by hand.",
     });
-    (0, config_1.writeConfig)(projectDir, { ...config, features: { ...config.features, rbac: true } });
+    const staleDocs = (0, docs_patcher_1.refreshProjectDocs)(projectDir, config, { rbac: true });
+    (0, config_1.writeConfig)(projectDir, {
+        ...config,
+        features: { ...config.features, rbac: true },
+        modules: {
+            ...config.modules,
+            role: { surface: "crud", applicationStyle: "service", boundary: "hexagonal", packageLayout: "split" },
+        },
+    });
     console.log(picocolors_1.default.green("\nadded internal/app/role/ and internal/shared/middleware/authz.go"));
     console.log("registered GET /users, GET /users/:id, PATCH /users/:id/set-role, /roles, and /permissions in cmd/api/wiring.go" + docsMessage);
-    console.log(picocolors_1.default.yellow("\n⚠ AUTO_MIGRATE=true does NOT seed the role/permission data — it only creates the\n" +
+    if (staleDocs.length)
+        console.log(picocolors_1.default.yellow((0, docs_patcher_1.docsRefreshWarning)(staleDocs, "add rbac")));
+    console.log(picocolors_1.default.yellow("\n⚠ The development table bootstrap does NOT seed role/permission data — it only creates the\n" +
         "  tables from the Go structs. The \"staff\"/\"admin\" roles and their permissions live\n" +
-        "  in the migration's SQL (INSERT statements), which AutoMigrate never runs. Without\n" +
+        "  in the migration's SQL (INSERT statements), which table creation never runs. Without\n" +
         "  applying it for real, `make seed` fails with \"unknown role code\" and nobody can be\n" +
         "  granted anything. Apply it before relying on RBAC, even in dev:\n" +
         "    migrate -path migrations -database \"$DB_DSN\" up   (or: make migrate-up)"));

package/dist/commands/undo.js

@@ -69,13 +69,16 @@ async function undoModule(rawName, opts, projectDir = process.cwd()) {
         if (!ok)
             throw new Error("undo cancelled");
     }
-    // detect --auth/--permission from the generated handler.go itself (not
+    // detect --auth/--permission from the generated handler 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");
+    const handlerCandidates = [
+        path_1.default.join(moduleDir, "adapters", "inbound", "http", "handler.go"),
+    ];
+    const handlerGoPath = handlerCandidates.find((candidate) => fs_extra_1.default.existsSync(candidate));
     let auth;
     let permission;
-    if (fs_extra_1.default.existsSync(handlerGoPath)) {
+    if (handlerGoPath) {
         const handlerContent = fs_extra_1.default.readFileSync(handlerGoPath, "utf8");
         auth = /jwtSecret\s+string/.test(handlerContent);
         permission = handlerContent.match(/h\.authz\.Require\("([^"]+)"\)/)?.[1];
@@ -123,6 +126,11 @@ async function undoModule(rawName, opts, projectDir = process.cwd()) {
         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.`,
     });
+    if (config.modules[modulePath]) {
+        const modules = { ...config.modules };
+        delete modules[modulePath];
+        (0, config_1.writeConfig)(projectDir, { ...config, modules });
+    }
     console.log(picocolors_1.default.green(`\nundid module "${naming.pkg}"`));
     console.log(`  deleted internal/app/${modulePath}/`);
     console.log(`  un-wired cmd/api/wiring.go`);

package/dist/commands/worker.js

@@ -14,6 +14,7 @@ const platform_patcher_1 = require("../utils/platform-patcher");
 const gocheck_1 = require("../utils/gocheck");
 const gomod_patcher_1 = require("../utils/gomod-patcher");
 const auth_patcher_1 = require("../utils/auth-patcher");
+const docs_patcher_1 = require("../utils/docs-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
@@ -35,19 +36,23 @@ async function addWorker(backend, projectDir = process.cwd()) {
         (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"));
     }
+    else {
+        (0, platform_patcher_1.patchCiForRiver)(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);
+    const mailerUpgraded = (0, auth_patcher_1.upgradeMailerToQueue)(path_1.default.join(projectDir, "cmd", "api", "wiring.go"), config.goModule, backend, path_1.default.join(projectDir, "internal", "app", "user", "composition.go"));
     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);
     // 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})`);
+    const staleDocs = (0, docs_patcher_1.refreshProjectDocs)(projectDir, config, { worker: true, queue: 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) {
@@ -61,6 +66,8 @@ async function addWorker(backend, projectDir = process.cwd()) {
         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"));
     }
+    if (staleDocs.length)
+        console.log(picocolors_1.default.yellow((0, docs_patcher_1.docsRefreshWarning)(staleDocs, "add worker")));
 }
 // needsSmtp and needsRedis are checked independently: `add auth` run without
 // a worker already writes SMTP_HOST on its own (auth stands alone — see
@@ -105,15 +112,18 @@ function patchMakefile(makefilePath, opts) {
         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" : ""} `);
+    content = content.replace(/^\.PHONY: /m, `.PHONY: dev worker${opts.river ? " river-migrate river-migrate-test" : ""} `);
     // 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.
+    // project's migrations/ directory — run its pinned CLI once per database.
     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'
+            '\tgo run github.com/riverqueue/river/cmd/river@v0.43.0 migrate-up --line main --database-url "$$DB_DSN"\n' +
+            "\n# apply River's own schema to TEST_DB_DSN for the real worker test\n" +
+            "river-migrate-test:\n" +
+            "\t@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; \\\n" +
+            '\tgo run github.com/riverqueue/river/cmd/river@v0.43.0 migrate-up --line main --database-url "$$TEST_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.