@nakedev/go-scaffold 0.4.3 → 0.5.1

package/dist/utils/config.js

@@ -15,7 +15,7 @@ const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const types_1 = require("../types");
 const CONFIG_FILE = "go-scaffold.config.json";
-exports.CONFIG_SCHEMA_VERSION = 1;
+exports.CONFIG_SCHEMA_VERSION = 2;
 function configPath(projectDir) {
     return path_1.default.join(projectDir, CONFIG_FILE);
 }
@@ -74,9 +74,10 @@ function readConfig(projectDir) {
     return normalizeProjectConfig({ ...config, features: features }, projectDir);
 }
 /**
- * Validate and fill defaults for the project manifest. Older projects have
- * no architecture/modules keys yet; normalising them here lets every command
- * consume one stable shape while keeping the old config file compatible.
+ * Validate and fill defaults for the project manifest. Projects that omit the
+ * architecture/modules keys can still be resolved safely; an explicit schema
+ * from before the split-layout contract is rejected so commands never write a
+ * mixed old/new tree.
  */
 function normalizeProjectConfig(raw, projectDir) {
     const projectName = requiredString(raw.projectName, "projectName");
@@ -86,6 +87,10 @@ function normalizeProjectConfig(raw, projectDir) {
     if (!Number.isInteger(schemaVersion) || schemaVersion < 1) {
         throw new Error(`${CONFIG_FILE} has invalid schemaVersion "${String(schemaVersion)}" — expected a positive integer`);
     }
+    if (schemaVersion < exports.CONFIG_SCHEMA_VERSION) {
+        throw new Error(`${CONFIG_FILE} uses legacy schemaVersion ${schemaVersion}; go-scaffold ${exports.CONFIG_SCHEMA_VERSION} requires the hexagonal split layout. ` +
+            `Keep using go-scaffold 0.4.x for that project, or migrate its modules to internal/app/<module>/{domain,application,ports,adapters} before upgrading.`);
+    }
     if (schemaVersion > exports.CONFIG_SCHEMA_VERSION) {
         throw new Error(`${CONFIG_FILE} uses schemaVersion ${schemaVersion}, but this CLI supports up to ${exports.CONFIG_SCHEMA_VERSION} — upgrade go-scaffold first`);
     }
@@ -119,10 +124,14 @@ function normalizeArchitecture(raw) {
         ...value,
     };
     assertOneOf(architecture.style, "architecture.style", ["modular-monolith"]);
+    assertOneOf(architecture.boundary, "architecture.boundary", ["hexagonal"]);
+    assertOneOf(architecture.packageLayout, "architecture.packageLayout", ["split"]);
     assertOneOf(architecture.defaultModuleSurface, "architecture.defaultModuleSurface", ["minimal", "crud"]);
     assertOneOf(architecture.defaultApplicationStyle, "architecture.defaultApplicationStyle", ["service", "cqrs"]);
     return {
         style: architecture.style,
+        boundary: architecture.boundary,
+        packageLayout: architecture.packageLayout,
         defaultModuleSurface: architecture.defaultModuleSurface,
         defaultApplicationStyle: architecture.defaultApplicationStyle,
     };
@@ -139,11 +148,17 @@ function normalizeModules(raw) {
         }
         if (!isRecord(entry))
             throw new Error(`${CONFIG_FILE}.modules.${name} must be a JSON object`);
+        const boundary = entry.boundary ?? types_1.DEFAULT_ARCHITECTURE_CONFIG.boundary;
+        const packageLayout = entry.packageLayout ?? types_1.DEFAULT_ARCHITECTURE_CONFIG.packageLayout;
         assertOneOf(entry.surface, `modules.${name}.surface`, ["minimal", "crud"]);
         assertOneOf(entry.applicationStyle, `modules.${name}.applicationStyle`, ["service", "cqrs"]);
+        assertOneOf(boundary, `modules.${name}.boundary`, ["hexagonal"]);
+        assertOneOf(packageLayout, `modules.${name}.packageLayout`, ["split"]);
         modules[name] = {
             surface: entry.surface,
             applicationStyle: entry.applicationStyle,
+            boundary: boundary,
+            packageLayout: packageLayout,
         };
     }
     return modules;
@@ -207,7 +222,11 @@ function detectFeatures(projectDir) {
         // 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",
+        authStore: !auth
+            ? undefined
+            : has("internal", "app", "user", "adapters", "outbound", "postgres", "tokenstore_pg.go")
+                ? "postgres"
+                : "redis",
         rbac: has("internal", "app", "role") && has("internal", "shared", "middleware", "authz.go"),
         observability: has("internal", "platform", "telemetry"),
     };

package/dist/utils/docs-patcher.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshProjectDocs = refreshProjectDocs;
+exports.docsRefreshWarning = docsRefreshWarning;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const naming_1 = require("./naming");
+const template_renderer_1 = require("./template-renderer");
+const PROJECT_DOCS = [
+    { template: "create/base/README.md.hbs", output: "README.md" },
+    { 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") },
+];
+/**
+ * Refresh generated project docs after an incremental feature is installed.
+ *
+ * A generated doc is only safe to rewrite when its bytes still match the
+ * version rendered from the project's current config. This keeps feature
+ * commands from destroying a maintainer's edits while still preventing the
+ * common stale-doc state where config says a feature is enabled but README or
+ * architect docs still describe the base skeleton.
+ */
+function refreshProjectDocs(projectDir, config, featureOverrides) {
+    const beforeFeatures = { ...config.features };
+    const afterFeatures = { ...beforeFeatures, ...featureOverrides };
+    const beforeContext = {
+        projectName: config.projectName,
+        dbName: (0, naming_1.toDbName)(config.projectName),
+        apiPrefix: config.apiPrefix,
+        ...config.architecture,
+        ...beforeFeatures,
+    };
+    const afterContext = {
+        projectName: config.projectName,
+        dbName: (0, naming_1.toDbName)(config.projectName),
+        apiPrefix: config.apiPrefix,
+        ...config.architecture,
+        ...afterFeatures,
+    };
+    const root = (0, template_renderer_1.getTemplatesRoot)();
+    const skipped = [];
+    for (const doc of PROJECT_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");
+        const onDisk = normalizeLineEndings(fs_extra_1.default.readFileSync(outputPath, "utf8"));
+        const expectedBefore = normalizeLineEndings((0, template_renderer_1.renderString)(source, beforeContext));
+        if (onDisk !== expectedBefore) {
+            skipped.push(doc.output);
+            continue;
+        }
+        fs_extra_1.default.writeFileSync(outputPath, (0, template_renderer_1.renderString)(source, afterContext));
+    }
+    return skipped;
+}
+function docsRefreshWarning(skipped, feature) {
+    if (skipped.length === 0)
+        return "";
+    const files = skipped.join(", ");
+    return `\nwarning: ${files} did not match the generated version, so ${feature} left them untouched — update them by hand`;
+}
+function normalizeLineEndings(text) {
+    return text.replace(/\r\n/g, "\n");
+}

package/dist/utils/hexagonal-method-patcher.js

@@ -0,0 +1,334 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hexagonalMarkersPresent = hexagonalMarkersPresent;
+exports.assertHexagonalMethodAbsent = assertHexagonalMethodAbsent;
+exports.patchHexagonalMethod = patchHexagonalMethod;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const marker_patch_1 = require("./marker-patch");
+const naming_1 = require("./naming");
+const DTO_MARKER = "// go-scaffold:dto";
+const REPOSITORY_INTERFACE_MARKER = "// go-scaffold:repository-interface";
+const QUERY_REPOSITORY_INTERFACE_MARKER = "// go-scaffold:query-repository-interface";
+const REPOSITORY_METHODS_MARKER = "// go-scaffold:repository-methods";
+const SERVICE_MARKER = "// go-scaffold:service-methods";
+const SERVICE_INTERFACE_MARKER = "// go-scaffold:service-interface";
+const COMMAND_MARKER = "// go-scaffold:command-methods";
+const COMMAND_INTERFACE_MARKER = "// go-scaffold:command-interface";
+const QUERY_MARKER = "// go-scaffold:query-methods";
+const QUERY_INTERFACE_MARKER = "// go-scaffold:query-interface";
+const HANDLER_ROUTES_MARKER = "// go-scaffold:handler-routes";
+const HANDLER_FUNCS_MARKER = "// go-scaffold:handler-funcs";
+const REPOSITORY_STUB_FIELDS_MARKER = "// go-scaffold:repository-stub-fields";
+const REPOSITORY_STUB_METHODS_MARKER = "// go-scaffold:repository-stub-methods";
+function isCqrs(paths) {
+    return Boolean(paths.commandPath && paths.queryPath);
+}
+function read(files, file) {
+    const value = files.get(file);
+    if (value !== undefined)
+        return value;
+    const content = fs_extra_1.default.readFileSync(file, "utf8");
+    files.set(file, content);
+    return content;
+}
+function write(files, file, content) {
+    files.set(file, content);
+}
+function addImport(content, importPath) {
+    return (0, marker_patch_1.ensureImport)(content, importPath);
+}
+function requestDTOMarker(content) {
+    if ((0, marker_patch_1.hasMarker)(content, DTO_MARKER))
+        return DTO_MARKER;
+    if ((0, marker_patch_1.hasMarker)(content, "// go-scaffold:user-dto"))
+        return "// go-scaffold:user-dto";
+    throw new Error("inbound HTTP DTO file is missing a go-scaffold DTO marker");
+}
+function insert(content, marker, block) {
+    return (0, marker_patch_1.insertBeforeMarker)(content, marker, block);
+}
+function serviceApplicationTarget(paths, type) {
+    if (isCqrs(paths)) {
+        if (type === "get")
+            return { path: paths.queryPath, marker: QUERY_MARKER, receiver: "h *QueryHandler" };
+        return { path: paths.commandPath, marker: COMMAND_MARKER, receiver: "h *CommandHandler" };
+    }
+    if (!paths.servicePath)
+        throw new Error("service module is missing application/service.go");
+    return { path: paths.servicePath, marker: SERVICE_MARKER, receiver: "s *Service" };
+}
+function applicationInterfaceMarker(paths, type) {
+    if (isCqrs(paths)) {
+        return type === "get"
+            ? { path: paths.queryPath, marker: QUERY_INTERFACE_MARKER }
+            : { path: paths.commandPath, marker: COMMAND_INTERFACE_MARKER };
+    }
+    return { path: paths.servicePath, marker: SERVICE_INTERFACE_MARKER };
+}
+function methodSignature(naming, method, opts) {
+    if (opts.type === "get" && opts.getMode === "all") {
+        return `${method.pascalName}(context.Context, int, int) ([]domain.${naming.pascalName}, error)`;
+    }
+    if (opts.type === "get") {
+        return `${method.pascalName}(context.Context, string) (*domain.${naming.pascalName}, error)`;
+    }
+    if (opts.type === "post") {
+        return `${method.pascalName}(context.Context, ${method.pascalName}Input) (*domain.${naming.pascalName}, error)`;
+    }
+    return `${method.pascalName}(context.Context, uuid.UUID) error`;
+}
+function applicationMethod(naming, method, opts, receiver) {
+    const target = receiver.startsWith("s ") ? "s" : "h";
+    if (opts.type === "get" && opts.getMode === "all") {
+        return [
+            `func (${receiver}) ${method.pascalName}(ctx context.Context, limit, offset int) ([]domain.${naming.pascalName}, error) {`,
+            `\treturn ${target}.repo.FindAll(ctx, limit, offset)`,
+            `}`,
+            "",
+        ].join("\n");
+    }
+    if (opts.type === "get") {
+        const field = (0, naming_1.toCamelCase)(opts.field ?? "field");
+        const fieldPascal = (0, naming_1.toPascalCase)(opts.field ?? "field");
+        return [
+            `func (${receiver}) ${method.pascalName}(ctx context.Context, ${field} string) (*domain.${naming.pascalName}, error) {`,
+            `\treturn ${target}.repo.FindBy${fieldPascal}(ctx, ${field})`,
+            `}`,
+            "",
+        ].join("\n");
+    }
+    if (opts.type === "post") {
+        return [
+            `func (${receiver}) ${method.pascalName}(ctx context.Context, in ${method.pascalName}Input) (*domain.${naming.pascalName}, error) {`,
+            `\t_ = ctx`,
+            `\t_ = in`,
+            `\treturn nil, domain.ErrNotImplemented`,
+            `}`,
+            "",
+        ].join("\n");
+    }
+    return [
+        `func (${receiver}) ${method.pascalName}(ctx context.Context, id uuid.UUID) error {`,
+        `\t_ = ctx`,
+        `\t_ = id`,
+        `\treturn domain.ErrNotImplemented`,
+        `}`,
+        "",
+    ].join("\n");
+}
+function handlerMethod(naming, method, opts, cqrs, routeReceiver, errorMapper) {
+    const receiver = cqrs ? (opts.type === "get" ? "h.queries" : "h.commands") : "h.svc";
+    if (opts.type === "get" && opts.getMode === "all") {
+        return {
+            route: `${routeReceiver}.GET("/${method.pathSegment}", h.${method.handlerName})`,
+            imports: ["net/http", "pagination"],
+            body: [
+                `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
+                `\tp := pagination.Parse(c)`,
+                `\titems, err := ${receiver}.${method.pascalName}(c.Request.Context(), p.Limit, p.Offset)`,
+                `\tif err != nil {`,
+                `\t\tc.Error(${errorMapper}(err))`,
+                `\t\treturn`,
+                `\t}`,
+                `\tout := make([]response, len(items))`,
+                `\tfor i := range items {`,
+                `\t\tout[i] = toResponse(application.ToResponse(&items[i]))`,
+                `\t}`,
+                `\tc.JSON(http.StatusOK, p.Response(out))`,
+                `}`,
+                "",
+            ].join("\n"),
+        };
+    }
+    if (opts.type === "get") {
+        const field = (0, naming_1.toCamelCase)(opts.field ?? "field");
+        const column = (0, naming_1.toDbName)(opts.field ?? "field");
+        return {
+            route: `${routeReceiver}.GET("/${column}/:${field}", h.${method.handlerName})`,
+            imports: ["net/http"],
+            body: [
+                `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
+                `\t${field} := c.Param("${field}")`,
+                `\tm, err := ${receiver}.${method.pascalName}(c.Request.Context(), ${field})`,
+                `\tif err != nil {`,
+                `\t\tc.Error(${errorMapper}(err))`,
+                `\t\treturn`,
+                `\t}`,
+                `\tc.JSON(http.StatusOK, toResponse(application.ToResponse(m)))`,
+                `}`,
+                "",
+            ].join("\n"),
+        };
+    }
+    if (opts.type === "post") {
+        return {
+            route: `${routeReceiver}.POST("/${method.pathSegment}", h.${method.handlerName})`,
+            imports: ["net/http", "httpx"],
+            body: [
+                `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
+                `\tvar in ${method.pascalName}Input`,
+                `\tif err := c.ShouldBindJSON(&in); err != nil {`,
+                `\t\tc.Error(httpx.BindErr(err))`,
+                `\t\treturn`,
+                `\t}`,
+                `\tm, err := ${receiver}.${method.pascalName}(c.Request.Context(), to${method.pascalName}Input(in))`,
+                `\tif err != nil {`,
+                `\t\tc.Error(${errorMapper}(err))`,
+                `\t\treturn`,
+                `\t}`,
+                `\tc.JSON(http.StatusCreated, toResponse(application.ToResponse(m)))`,
+                `}`,
+                "",
+            ].join("\n"),
+        };
+    }
+    return {
+        route: `${routeReceiver}.${opts.type.toUpperCase()}("/:id/${method.pathSegment}", h.${method.handlerName})`,
+        imports: ["net/http", "httpx"],
+        body: [
+            `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
+            `\tid, ok := httpx.ParseID(c)`,
+            `\tif !ok {`,
+            `\t\treturn`,
+            `\t}`,
+            `\tif err := ${receiver}.${method.pascalName}(c.Request.Context(), id); err != nil {`,
+            `\t\tc.Error(${errorMapper}(err))`,
+            `\t\treturn`,
+            `\t}`,
+            `\tc.Status(http.StatusNoContent)`,
+            `}`,
+            "",
+        ].join("\n"),
+    };
+}
+function assertNotDuplicate(content, needle, what) {
+    if (content.includes(needle))
+        throw new Error(`${what} already exists — pick a different method name`);
+}
+function handlerRouteReceiver(content) {
+    // Auth's protected routes use usersGroup; generated CRUD modules use the
+    // local g group. Both remain the module's inbound adapter boundary.
+    return (0, marker_patch_1.hasMarker)(content, "// go-scaffold:user-routes") ? "usersGroup" : "g";
+}
+function hexagonalMarkersPresent(paths) {
+    if (!fs_extra_1.default.existsSync(paths.dtoPath) || !fs_extra_1.default.existsSync(paths.requestDTOPath) || !fs_extra_1.default.existsSync(paths.portsPath) || !fs_extra_1.default.existsSync(paths.repositoryAdapterPath) || !fs_extra_1.default.existsSync(paths.handlerPath) || !fs_extra_1.default.existsSync(paths.serviceTestPath))
+        return false;
+    const handler = fs_extra_1.default.readFileSync(paths.handlerPath, "utf8");
+    if (!(0, marker_patch_1.hasMarker)(handler, HANDLER_ROUTES_MARKER) || !(0, marker_patch_1.hasMarker)(handler, HANDLER_FUNCS_MARKER))
+        return false;
+    const dto = fs_extra_1.default.readFileSync(paths.dtoPath, "utf8");
+    const requestDTO = fs_extra_1.default.readFileSync(paths.requestDTOPath, "utf8");
+    const ports = fs_extra_1.default.readFileSync(paths.portsPath, "utf8");
+    const adapter = fs_extra_1.default.readFileSync(paths.repositoryAdapterPath, "utf8");
+    if (!(0, marker_patch_1.hasMarker)(dto, DTO_MARKER) ||
+        (!(0, marker_patch_1.hasMarker)(requestDTO, DTO_MARKER) && !(0, marker_patch_1.hasMarker)(requestDTO, "// go-scaffold:user-dto")) ||
+        !(0, marker_patch_1.hasMarker)(adapter, REPOSITORY_METHODS_MARKER))
+        return false;
+    if (isCqrs(paths)) {
+        return Boolean(paths.commandPath && paths.queryPath && (0, marker_patch_1.hasMarker)(fs_extra_1.default.readFileSync(paths.commandPath, "utf8"), COMMAND_MARKER) && (0, marker_patch_1.hasMarker)(fs_extra_1.default.readFileSync(paths.commandPath, "utf8"), COMMAND_INTERFACE_MARKER) && (0, marker_patch_1.hasMarker)(fs_extra_1.default.readFileSync(paths.queryPath, "utf8"), QUERY_MARKER) && (0, marker_patch_1.hasMarker)(fs_extra_1.default.readFileSync(paths.queryPath, "utf8"), QUERY_INTERFACE_MARKER) && (0, marker_patch_1.hasMarker)(ports, COMMAND_REPOSITORY_INTERFACE_MARKER) && (0, marker_patch_1.hasMarker)(ports, QUERY_REPOSITORY_INTERFACE_MARKER));
+    }
+    return Boolean(paths.servicePath && (0, marker_patch_1.hasMarker)(fs_extra_1.default.readFileSync(paths.servicePath, "utf8"), SERVICE_MARKER) && (0, marker_patch_1.hasMarker)(fs_extra_1.default.readFileSync(paths.servicePath, "utf8"), SERVICE_INTERFACE_MARKER) && (0, marker_patch_1.hasMarker)(ports, REPOSITORY_INTERFACE_MARKER));
+}
+const COMMAND_REPOSITORY_INTERFACE_MARKER = "// go-scaffold:command-repository-interface";
+function assertHexagonalMethodAbsent(paths, method) {
+    assertNotDuplicate(fs_extra_1.default.readFileSync(paths.handlerPath, "utf8"), `func (h *Handler) ${method.handlerName}(`, `handler method "${method.handlerName}"`);
+    const appFiles = [paths.servicePath, paths.commandPath, paths.queryPath].filter((file) => Boolean(file));
+    for (const file of appFiles)
+        assertNotDuplicate(fs_extra_1.default.readFileSync(file, "utf8"), `) ${method.pascalName}(`, `application method "${method.pascalName}"`);
+}
+function patchHexagonalMethod(paths, naming, method, opts, goModule) {
+    assertHexagonalMethodAbsent(paths, method);
+    if (opts.type === "get" && opts.getMode !== "all" && !opts.field)
+        throw new Error("--field is required for --type get --get-mode one");
+    if (opts.type === "get" && opts.field?.toLowerCase() === "id")
+        throw new Error('--field cannot be "id" — GET /:id already exists as the default lookup');
+    const files = new Map();
+    const cqrs = isCqrs(paths);
+    const interfaceTarget = applicationInterfaceMarker(paths, opts.type);
+    let interfaceFile = read(files, interfaceTarget.path);
+    interfaceFile = insert(interfaceFile, interfaceTarget.marker, methodSignature(naming, method, opts));
+    write(files, interfaceTarget.path, interfaceFile);
+    const target = serviceApplicationTarget(paths, opts.type);
+    let applicationFile = read(files, target.path);
+    applicationFile = addImport(applicationFile, "context");
+    if (opts.type !== "get" && opts.type !== "post")
+        applicationFile = addImport(applicationFile, "github.com/google/uuid");
+    applicationFile = insert(applicationFile, target.marker, applicationMethod(naming, method, opts, target.receiver));
+    write(files, target.path, applicationFile);
+    let handler = read(files, paths.handlerPath);
+    const handlerResult = handlerMethod(naming, method, opts, cqrs, handlerRouteReceiver(handler), paths.handlerErrorMapper ?? "appError");
+    handler = insert(handler, HANDLER_ROUTES_MARKER, handlerResult.route);
+    handler = insert(handler, HANDLER_FUNCS_MARKER, handlerResult.body);
+    for (const need of handlerResult.imports)
+        handler = addImport(handler, need.startsWith("net/") ? need : `${goModule}/internal/shared/${need}`);
+    write(files, paths.handlerPath, handler);
+    if (opts.type === "post") {
+        let dto = read(files, paths.dtoPath);
+        const inputName = `${method.pascalName}Input`;
+        assertNotDuplicate(dto, `type ${inputName} struct`, `DTO "${inputName}"`);
+        dto = insert(dto, DTO_MARKER, [`type ${inputName} struct {`, `\t// TODO: add request fields`, `}`, ""].join("\n"));
+        write(files, paths.dtoPath, dto);
+        let requestDTO = read(files, paths.requestDTOPath);
+        assertNotDuplicate(requestDTO, `type ${inputName} struct`, `HTTP DTO "${inputName}"`);
+        requestDTO = addImport(requestDTO, `${goModule}/internal/app/${naming.pkg}/application`);
+        requestDTO = insert(requestDTO, requestDTOMarker(requestDTO), [
+            `type ${inputName} struct {`,
+            `\t// TODO: mirror request fields from application.${inputName} and add JSON/binding tags`,
+            `}`,
+            "",
+            `func to${inputName}(in ${inputName}) application.${inputName} {`,
+            `\t// TODO: map request fields explicitly into the application input.`,
+            `\t_ = in`,
+            `\treturn application.${inputName}{}`,
+            `}`,
+            "",
+        ].join("\n"));
+        write(files, paths.requestDTOPath, requestDTO);
+    }
+    if (opts.type === "get" && opts.getMode !== "all") {
+        const fieldPascal = (0, naming_1.toPascalCase)(opts.field);
+        const fieldParam = (0, naming_1.toCamelCase)(opts.field);
+        const repoInterfaceMarker = cqrs ? QUERY_REPOSITORY_INTERFACE_MARKER : REPOSITORY_INTERFACE_MARKER;
+        let ports = read(files, paths.portsPath);
+        ports = insert(ports, repoInterfaceMarker, `FindBy${fieldPascal}(context.Context, string) (*domain.${naming.pascalName}, error)`);
+        write(files, paths.portsPath, ports);
+        let adapter = read(files, paths.repositoryAdapterPath);
+        const column = (0, naming_1.toDbName)(opts.field);
+        const modelType = paths.repositoryModelType ?? `${naming.pascalName}Model`;
+        const toDomain = paths.repositoryToDomain ?? "toDomain";
+        const errorMapper = paths.repositoryErrorMapper ?? "mapDatabaseError";
+        adapter = insert(adapter, REPOSITORY_METHODS_MARKER, [
+            `func (r *Repository) FindBy${fieldPascal}(ctx context.Context, ${fieldParam} string) (*domain.${naming.pascalName}, error) {`,
+            `\tvar row ${modelType}`,
+            `\tif err := tx.From(ctx, r.db).WithContext(ctx).First(&row, "${column} = ?", ${fieldParam}).Error; err != nil {`,
+            `\t\treturn nil, ${errorMapper}(err)`,
+            `\t}`,
+            `\treturn ${toDomain}(&row), nil`,
+            `}`,
+            "",
+        ].join("\n"));
+        write(files, paths.repositoryAdapterPath, adapter);
+        let test = read(files, paths.serviceTestPath);
+        const stubField = `findBy${fieldPascal}Fn`;
+        assertNotDuplicate(test, `${stubField} func(`, `repository stub field "${stubField}"`);
+        test = insert(test, REPOSITORY_STUB_FIELDS_MARKER, `\t${stubField} func(context.Context, string) (*domain.${naming.pascalName}, error)`);
+        const stubReceiver = paths.repositoryStubReceiver ?? "s *repositoryStub";
+        const stubVariable = stubReceiver.split(" ")[0];
+        assertNotDuplicate(test, `func (${stubReceiver}) FindBy${fieldPascal}(`, `repository stub method "FindBy${fieldPascal}"`);
+        test = insert(test, REPOSITORY_STUB_METHODS_MARKER, [
+            `func (${stubReceiver}) FindBy${fieldPascal}(ctx context.Context, value string) (*domain.${naming.pascalName}, error) {`,
+            `\tif ${stubVariable}.${stubField} == nil {`,
+            `\t\tpanic("unexpected repository.FindBy${fieldPascal} call")`,
+            `\t}`,
+            `\treturn ${stubVariable}.${stubField}(ctx, value)`,
+            `}`,
+            "",
+        ].join("\n"));
+        write(files, paths.serviceTestPath, test);
+    }
+    for (const [file, content] of files)
+        fs_extra_1.default.writeFileSync(file, content);
+}

package/dist/utils/main-patcher.js

@@ -22,7 +22,7 @@ const UNUSED_API_LINE = "_ = api // dropped once `generate module` registers the
 // API binary supplies infrastructure and security dependencies, then only
 // registers the feature's handler.
 function mainGoLines(patch) {
-    const modelAlias = `${patch.pkg}model`; // every domain's model subpackage is named "model"
+    const modelAlias = `${patch.pkg}postgres`; // every domain's persistence adapter is named "postgres"
     const handlerArgs = ["db"];
     const legacyHandlerArgs = [`${patch.pkg}Svc`];
     if (patch.auth)
@@ -38,7 +38,7 @@ function mainGoLines(patch) {
         legacyHandlerArgs.push("roleComposition.Authz");
     return {
         importLine: `"${patch.goModule}/internal/app/${patch.modulePath}"`,
-        modelImportLine: `${modelAlias} "${patch.goModule}/internal/app/${patch.modulePath}/model"`,
+        modelImportLine: `${modelAlias} "${patch.goModule}/internal/app/${patch.modulePath}/adapters/outbound/postgres"`,
         // Development schema bootstrap creates tables but not the schema they live in — see
         // the comment on go-scaffold:schemas in main.go.hbs. One Exec per schema,
         // guarded by its own sentinel so two modules sharing a schema name only
@@ -49,7 +49,7 @@ function mainGoLines(patch) {
             `}`,
         ].join("\n"),
         schemaSentinel: `CREATE SCHEMA IF NOT EXISTS ${patch.schemaName}`,
-        migrateLine: `&${modelAlias}.${patch.pascalName}{},`,
+        migrateLine: `&${modelAlias}.${patch.pascalName}Model{},`,
         // kept only so undo can clean projects generated before feature-local
         // composition was introduced.
         legacyServicePrefix: `${patch.pkg}Svc :=`,

package/dist/utils/module-location.js

@@ -18,7 +18,7 @@ function existingModulePackages(projectDir) {
         .map((entry) => entry.name);
 }
 // A Go package name has no word boundaries: "orderitem" cannot tell you it
-// came from "order-items". Everything else a command derives — the model type
+// came from "order-items". Everything else a command derives — the entity type
 // (OrderItem), the route (/order-items), the table (order_items), the
 // migration filename — does depend on those boundaries, so re-deriving them
 // from the package name yields Orderitem/orderitems and code that doesn't
@@ -29,15 +29,21 @@ function existingModulePackages(projectDir) {
 // prints as the next command to run. Following that instruction produced
 // `undefined: model.Orderitem (but have OrderItem)`.
 //
-// model/model.go is where the boundaries survive — the struct name is
-// PascalCase, so kebab-casing it recovers the exact string `generate module`
-// was originally given.
+// The outbound persistence model is where the generated PascalCase type
+// survives, so kebab-casing it recovers the exact string `generate module` was
+// originally given.
 function pascalNameOnDisk(projectDir, pkg) {
-    const modelPath = path_1.default.join(projectDir, "internal", "app", pkg, "model", "model.go");
-    if (!fs_extra_1.default.existsSync(modelPath))
-        return null;
-    const match = fs_extra_1.default.readFileSync(modelPath, "utf8").match(/^type\s+([A-Z]\w*)\s+struct\b/m);
-    return match ? match[1] : null;
+    // Split hexagonal modules keep persistence models in the outbound adapter.
+    // The package name still loses word boundaries (`orderitem`), so recover
+    // the original PascalCase entity from the generated `OrderItemModel` type
+    // before commands such as `undo module orderitem` rebuild their wiring.
+    const adapterModelPath = path_1.default.join(projectDir, "internal", "app", pkg, "adapters", "outbound", "postgres", "model.go");
+    if (fs_extra_1.default.existsSync(adapterModelPath)) {
+        const match = fs_extra_1.default.readFileSync(adapterModelPath, "utf8").match(/^type\s+([A-Z]\w*)Model\s+struct\b/m);
+        if (match)
+            return match[1];
+    }
+    return null;
 }
 function resolveProjectModuleNaming(projectDir, rawName) {
     const located = (0, naming_1.resolveExistingModuleNaming)(rawName, existingModulePackages(projectDir));
@@ -52,7 +58,7 @@ function resolveProjectModuleNaming(projectDir, rawName) {
         return located; // model.go holds something we can't derive a module name from
     }
     // Only trust the correction when it still points at the same package.
-    // A hand-renamed struct, or a legacy module whose type never matched its
-    // folder, would otherwise silently retarget the command at another module.
+    // A hand-renamed struct whose type no longer matches its folder would
+    // otherwise silently retarget the command at another module.
     return fromDisk.pkg === located.pkg ? fromDisk : located;
 }

package/dist/utils/platform-patcher.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.patchComposeForRedis = patchComposeForRedis;
 exports.patchCiForRedis = patchCiForRedis;
+exports.patchCiForRiver = patchCiForRiver;
 exports.patchConfigForRedis = patchConfigForRedis;
 exports.patchConfigForWorker = patchConfigForWorker;
 exports.patchConfigForSMTP = patchConfigForSMTP;
@@ -100,6 +101,32 @@ function patchCiForRedis(ciPath) {
     }
     fs_extra_1.default.writeFileSync(ciPath, patched);
 }
+// patchCiForRiver makes the generated worker round-trip test runnable in CI.
+// River's schema is versioned by River itself, separately from this project's
+// migrations/, so applying only the application migrations leaves the test
+// unable to exercise the worker.
+function patchCiForRiver(ciPath) {
+    if (!fs_extra_1.default.existsSync(ciPath))
+        return;
+    const content = fs_extra_1.default.readFileSync(ciPath, "utf8");
+    if (content.includes("river-migrate-test") || content.includes("Apply River migrations"))
+        return;
+    const testStep = content.split("\n").find((line) => line.trimStart().startsWith("- name: Test (required PostgreSQL integration tests cannot skip)"));
+    const dsn = content.match(/^\s+DB_DSN:\s+(.+)$/m)?.[1]?.trim();
+    if (!testStep || !dsn) {
+        console.error(picocolors_1.default.yellow(`skipped adding River migrations to ${ciPath} — the generated migration DSN or PostgreSQL test step is missing.\n` +
+            `Add a River migration step before the required PostgreSQL test step by hand.`));
+        return;
+    }
+    const step = [
+        "      - name: Apply River migrations to the test database",
+        "        env:",
+        `          TEST_DB_DSN: ${dsn}`,
+        '        run: go run github.com/riverqueue/river/cmd/river@v0.43.0 migrate-up --line main --database-url "$TEST_DB_DSN"',
+        "",
+    ].join("\n");
+    fs_extra_1.default.writeFileSync(ciPath, content.replace(testStep, `${step}${testStep}`));
+}
 // patchConfigForRedis adds RedisURL to Config and its env() load to Load().
 // Split out from the worker patch because Redis is no longer the worker's
 // concern by default — `add auth` needs it for the refresh-token store even