@nakedev/go-scaffold 0.4.3 → 0.5.1

package/dist/commands/auth.js

@@ -19,6 +19,7 @@ const openapi_patcher_1 = require("../utils/openapi-patcher");
 const gocheck_1 = require("../utils/gocheck");
 const gomod_patcher_1 = require("../utils/gomod-patcher");
 const auth_wizard_1 = require("../prompts/auth-wizard");
+const docs_patcher_1 = require("../utils/docs-patcher");
 // URL (relative to the api prefix) -> docs file (relative to docs/) for every
 // route `add auth` registers — kept next to AUTH_FILES's route list so the
 // two are easy to eyeball together when a route changes.
@@ -156,7 +157,17 @@ async function addAuth(store = "postgres", projectDir = process.cwd(), browserTo
     // parse-only: jwt/oauth2/bcrypt aren't in go.mod until the `go mod tidy`
     // printed below, so `go vet` can't be the gate here.
     (0, gocheck_1.assertStillParses)(projectDir, parsedBefore, "added auth");
-    (0, config_1.writeConfig)(projectDir, { ...config, features: { ...config.features, auth: true, authStore: store } });
+    const staleDocs = (0, docs_patcher_1.refreshProjectDocs)(projectDir, config, { auth: true, authStore: store });
+    if (staleDocs.length)
+        docsMessage += (0, docs_patcher_1.docsRefreshWarning)(staleDocs, "add auth");
+    (0, config_1.writeConfig)(projectDir, {
+        ...config,
+        features: { ...config.features, auth: true, authStore: store },
+        modules: {
+            ...config.modules,
+            user: { surface: "minimal", applicationStyle: "service", boundary: "hexagonal", packageLayout: "split" },
+        },
+    });
     console.log(picocolors_1.default.green("\nadded internal/app/user/, internal/shared/middleware/auth.go, and cmd/seed"));
     console.log(worker
         ? "verification + password-reset mail goes through the queue"

package/dist/commands/check.js

@@ -0,0 +1,281 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkProject = checkProject;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const config_1 = require("../utils/config");
+const forbiddenByLayer = {
+    domain: [
+        /github\.com\/gin-gonic\/gin/,
+        /gorm\.io\//,
+        /net\/http/,
+        /internal\/(shared|platform)\//,
+        /redis/,
+    ],
+    application: [
+        /github\.com\/gin-gonic\/gin/,
+        /gorm\.io\//,
+        /database\/sql/,
+        /internal\/platform\//,
+        /internal\/shared\/(apperror|httpx|middleware|tx|dberr)\//,
+        /redis/,
+    ],
+    ports: [
+        /github\.com\/gin-gonic\/gin/,
+        /gorm\.io\//,
+        /database\/sql/,
+        /internal\/platform\//,
+        /internal\/shared\/(apperror|httpx|middleware|tx|dberr)\//,
+        /redis/,
+    ],
+    inbound: [/gorm\.io\//, /internal\/platform\//],
+    outbound: [/github\.com\/gin-gonic\/gin/, /internal\/shared\/httpx\//, /internal\/shared\/middleware\//],
+};
+// A split module is not hexagonal merely because its folders have the right
+// names. Keep dependencies flowing toward the application core. Composition
+// is the only module-local exception because it is the explicit wiring edge.
+const forbiddenInternalLayers = {
+    domain: ["application", "ports", "inbound", "outbound", "composition"],
+    ports: ["application", "inbound", "outbound", "composition"],
+    application: ["inbound", "outbound", "composition"],
+    inbound: ["outbound", "composition"],
+    outbound: ["application", "inbound", "composition"],
+};
+function goFiles(dir) {
+    if (!fs_extra_1.default.existsSync(dir))
+        return [];
+    const files = [];
+    for (const entry of fs_extra_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const entryPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory())
+            files.push(...goFiles(entryPath));
+        else if (entry.isFile() && entry.name.endsWith(".go"))
+            files.push(entryPath);
+    }
+    return files;
+}
+function directoriesNamed(dir, names) {
+    if (!fs_extra_1.default.existsSync(dir))
+        return [];
+    const found = [];
+    for (const entry of fs_extra_1.default.readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const entryPath = path_1.default.join(dir, entry.name);
+        if (names.has(entry.name))
+            found.push(entryPath);
+        found.push(...directoriesNamed(entryPath, names));
+    }
+    return found;
+}
+function imports(content) {
+    const found = [];
+    for (const match of content.matchAll(/^\s*(?:import\s+)?(?:[._\w]+\s+)?"([^"]+)"\s*$/gm))
+        found.push(match[1]);
+    return found;
+}
+function internalLayer(imported, moduleName) {
+    const match = imported.match(/(?:^|\/)internal\/app\/([^/]+)\/(.+)$/);
+    if (!match || match[1] !== moduleName)
+        return undefined;
+    const relative = match[2];
+    if (relative === "domain" || relative.startsWith("domain/"))
+        return "domain";
+    if (relative === "application" || relative.startsWith("application/"))
+        return "application";
+    if (relative === "ports" || relative.startsWith("ports/"))
+        return "ports";
+    if (relative === "adapters/inbound" || relative.startsWith("adapters/inbound/"))
+        return "inbound";
+    if (relative === "adapters/outbound" || relative.startsWith("adapters/outbound/"))
+        return "outbound";
+    if (relative === "composition.go" || relative === "composition")
+        return "composition";
+    return undefined;
+}
+function siblingModule(imported, current) {
+    const match = imported.match(/(?:^|\/)internal\/app\/([^/]+)(?:\/|$)/);
+    if (!match || match[1] === current)
+        return undefined;
+    return match[1];
+}
+function appImport(imported) {
+    const match = imported.match(/(?:^|\/)internal\/app\/([^/]+)(?:\/(.*))?$/);
+    if (!match)
+        return undefined;
+    return { module: match[1], privatePath: match[2] ?? "" };
+}
+function filesForLayer(moduleDir, layer) {
+    if (layer === "composition")
+        return goFiles(moduleDir).filter((file) => path_1.default.basename(file) === "composition.go");
+    const relative = layer === "inbound"
+        ? path_1.default.join("adapters", "inbound", "http")
+        : layer === "outbound"
+            ? path_1.default.join("adapters", "outbound")
+            : layer;
+    return goFiles(path_1.default.join(moduleDir, relative));
+}
+function moduleNames(projectDir, config) {
+    const appDir = path_1.default.join(projectDir, "internal", "app");
+    const discovered = fs_extra_1.default.existsSync(appDir)
+        ? fs_extra_1.default.readdirSync(appDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name)
+        : [];
+    return [...new Set([...Object.keys(config.modules), ...discovered])].sort();
+}
+function expectedFiles(moduleDir, module) {
+    const required = [
+        "composition.go",
+        "domain/entity.go",
+        "domain/errors.go",
+        "ports/repository.go",
+        "application/dto.go",
+        "adapters/inbound/http/dto.go",
+        "adapters/inbound/http/handler.go",
+        "adapters/outbound/postgres/model.go",
+        "adapters/outbound/postgres/repository.go",
+    ];
+    if (module.applicationStyle === "service")
+        required.push("application/service.go");
+    else
+        required.push("application/commands.go", "application/queries.go");
+    return required.map((file) => path_1.default.join(moduleDir, file));
+}
+function checkModule(projectDir, config, name, module) {
+    const errors = [];
+    const moduleDir = path_1.default.join(projectDir, "internal", "app", name);
+    if (!module) {
+        errors.push(`internal/app/${name}: missing module metadata in go-scaffold.config.json`);
+        return errors;
+    }
+    if (module.boundary !== "hexagonal" || module.packageLayout !== "split") {
+        errors.push(`internal/app/${name}: module must declare boundary=hexagonal and packageLayout=split`);
+    }
+    for (const forbidden of directoriesNamed(moduleDir, new Set(["model"]))) {
+        errors.push(`${path_1.default.relative(projectDir, forbidden)}: feature-level model package is forbidden; keep persistence models in the outbound adapter`);
+    }
+    for (const forbidden of directoriesNamed(moduleDir, new Set(["compat"]))) {
+        errors.push(`${path_1.default.relative(projectDir, forbidden)}: feature-level compat directory is forbidden; keep legacy compatibility out of the canonical split architecture`);
+    }
+    for (const file of expectedFiles(moduleDir, module)) {
+        if (!fs_extra_1.default.existsSync(file))
+            errors.push(`${path_1.default.relative(projectDir, file)}: required by the split module contract`);
+    }
+    const applicationDir = path_1.default.join(moduleDir, "application");
+    if (module.applicationStyle === "cqrs" && fs_extra_1.default.existsSync(path_1.default.join(applicationDir, "service.go"))) {
+        errors.push(`internal/app/${name}: CQRS module must not contain application/service.go; use commands.go and queries.go`);
+    }
+    if (module.applicationStyle === "cqrs" && fs_extra_1.default.existsSync(path_1.default.join(applicationDir, "service_test.go"))) {
+        errors.push(`internal/app/${name}: CQRS module must not contain application/service_test.go; use cqrs_test.go`);
+    }
+    if (module.applicationStyle === "service" && (fs_extra_1.default.existsSync(path_1.default.join(applicationDir, "commands.go")) || fs_extra_1.default.existsSync(path_1.default.join(applicationDir, "queries.go")))) {
+        errors.push(`internal/app/${name}: service module must not contain application/commands.go or queries.go`);
+    }
+    if (module.applicationStyle === "service" && fs_extra_1.default.existsSync(path_1.default.join(applicationDir, "cqrs_test.go"))) {
+        errors.push(`internal/app/${name}: service module must not contain application/cqrs_test.go; use service_test.go`);
+    }
+    for (const [layer, patterns] of Object.entries(forbiddenByLayer)) {
+        for (const file of filesForLayer(moduleDir, layer)) {
+            const content = fs_extra_1.default.readFileSync(file, "utf8");
+            for (const imported of imports(content)) {
+                const rule = patterns.find((pattern) => pattern.test(imported));
+                if (rule)
+                    errors.push(`${path_1.default.relative(projectDir, file)}: ${layer} layer imports forbidden dependency ${imported}`);
+                const importedLayer = internalLayer(imported, name);
+                if (importedLayer && forbiddenInternalLayers[layer].includes(importedLayer)) {
+                    errors.push(`${path_1.default.relative(projectDir, file)}: ${layer} layer imports forbidden internal layer ${imported}`);
+                }
+                const other = siblingModule(imported, name);
+                if (other) {
+                    errors.push(`${path_1.default.relative(projectDir, file)}: imports sibling module ${other}; use a port and process composition`);
+                }
+            }
+            if (layer === "application" && path_1.default.basename(file) === "dto.go" && content.includes("json:")) {
+                errors.push(`${path_1.default.relative(projectDir, file)}: application DTOs must be transport-neutral; keep JSON tags in adapters/inbound/http/dto.go`);
+            }
+        }
+    }
+    for (const file of filesForLayer(moduleDir, "composition")) {
+        const content = fs_extra_1.default.readFileSync(file, "utf8");
+        for (const imported of imports(content)) {
+            const other = siblingModule(imported, name);
+            if (other) {
+                errors.push(`${path_1.default.relative(projectDir, file)}: imports sibling module ${other}; use a port and process composition`);
+            }
+        }
+    }
+    for (const file of goFiles(moduleDir)) {
+        const content = fs_extra_1.default.readFileSync(file, "utf8");
+        for (const imported of imports(content)) {
+            if (/\/internal\/app\/[^/]+\/model(?:\/|$)/.test(imported)) {
+                errors.push(`${path_1.default.relative(projectDir, file)}: imports a forbidden feature-level model package ${imported}`);
+            }
+        }
+    }
+    const rootGoFiles = fs_extra_1.default.existsSync(moduleDir)
+        ? fs_extra_1.default
+            .readdirSync(moduleDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".go"))
+            .map((entry) => path_1.default.join(moduleDir, entry.name))
+        : [];
+    for (const file of rootGoFiles) {
+        if (path_1.default.basename(file) !== "composition.go") {
+            errors.push(`${path_1.default.relative(projectDir, file)}: root module package may only contain composition.go`);
+        }
+    }
+    return errors;
+}
+function checkProcessComposition(projectDir) {
+    const errors = [];
+    const compositionDir = path_1.default.join(projectDir, "internal", "composition");
+    const docPath = path_1.default.join(compositionDir, "doc.go");
+    if (!fs_extra_1.default.existsSync(docPath)) {
+        errors.push("internal/composition/doc.go: required process-level composition package");
+    }
+    for (const file of goFiles(compositionDir)) {
+        const content = fs_extra_1.default.readFileSync(file, "utf8");
+        for (const imported of imports(content)) {
+            const feature = appImport(imported);
+            if (feature?.privatePath) {
+                errors.push(`${path_1.default.relative(projectDir, file)}: process composition must import the public internal/app/${feature.module} package, not private path ${imported}`);
+            }
+        }
+    }
+    // wiring.go is allowed to see every feature package because it is the
+    // executable's root. Other cmd/api files must not become hidden
+    // cross-feature adapters; those belong here so integration tests can reuse
+    // the same mapping without importing package main.
+    const apiDir = path_1.default.join(projectDir, "cmd", "api");
+    for (const file of goFiles(apiDir)) {
+        const base = path_1.default.basename(file);
+        if (base === "main.go" || base === "wiring.go")
+            continue;
+        for (const imported of imports(fs_extra_1.default.readFileSync(file, "utf8"))) {
+            if (appImport(imported)) {
+                errors.push(`${path_1.default.relative(projectDir, file)}: process-level feature adapters belong in internal/composition; keep cmd/api for entrypoint and wiring`);
+                break;
+            }
+        }
+    }
+    return errors;
+}
+function checkProject(projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    const errors = [];
+    if (config.architecture.style !== "modular-monolith")
+        errors.push("architecture.style must be modular-monolith");
+    if (config.architecture.boundary !== "hexagonal")
+        errors.push("architecture.boundary must be hexagonal");
+    if (config.architecture.packageLayout !== "split")
+        errors.push("architecture.packageLayout must be split");
+    errors.push(...checkProcessComposition(projectDir));
+    for (const name of moduleNames(projectDir, config))
+        errors.push(...checkModule(projectDir, config, name, config.modules[name]));
+    if (errors.length) {
+        throw new Error(`${picocolors_1.default.red("architecture check failed")}:\n${errors.map((error) => `  - ${error}`).join("\n")}`);
+    }
+    console.log(picocolors_1.default.green(`architecture check passed: ${moduleNames(projectDir, config).length} split module(s), hexagonal boundary`));
+}

package/dist/commands/create.js

@@ -14,6 +14,7 @@ const naming_1 = require("../utils/naming");
 const create_wizard_1 = require("../prompts/create-wizard");
 const version_1 = require("../utils/version");
 const types_1 = require("../types");
+const config_2 = require("../utils/config");
 const observability_1 = require("./observability");
 const module_profile_1 = require("../utils/module-profile");
 async function createProject(rawName, opts) {
@@ -81,7 +82,7 @@ async function createProject(rawName, opts) {
     await (0, template_renderer_1.applyTemplateEntries)(projectDir, create_manifest_1.CREATE_MANIFEST, context);
     (0, template_renderer_1.gofmtTree)(projectDir);
     (0, config_1.writeConfig)(projectDir, {
-        schemaVersion: 1,
+        schemaVersion: config_2.CONFIG_SCHEMA_VERSION,
         projectName,
         goModule,
         apiPrefix,

package/dist/commands/generate.js

@@ -59,6 +59,7 @@ async function generateModule(rawName, opts, projectDir = process.cwd()) {
         modulePath,
         auth: opts.auth,
         permission: opts.permission,
+        full: opts.full,
         cqrs: opts.cqrs,
         moduleSurface: opts.full ? "crud" : "minimal",
         applicationStyle: opts.cqrs ? "cqrs" : "service",
@@ -148,13 +149,15 @@ async function generateModule(rawName, opts, projectDir = process.cwd()) {
             [modulePath]: {
                 surface: opts.full ? "crud" : "minimal",
                 applicationStyle: opts.cqrs ? "cqrs" : "service",
+                boundary: "hexagonal",
+                packageLayout: "split",
             },
         },
     });
     const routePath = config.apiPrefix ? `/${config.apiPrefix}/${naming.plural}` : `/${naming.plural}`;
     console.log(picocolors_1.default.green(`\ngenerated internal/app/${modulePath}/`));
     if (opts.cqrs) {
-        console.log("application boundary: CQRS command/query handlers in commands.go and queries.go");
+        console.log("application boundary: CQRS command/query handlers in application/commands.go and application/queries.go");
     }
     console.log(`recorded module defaults: ${opts.full ? "crud" : "minimal"} + ${opts.cqrs ? "cqrs" : "service"}`);
     if (opts.full) {
@@ -184,6 +187,6 @@ async function generateModule(rawName, opts, projectDir = process.cwd()) {
     }
     if (docsMessage)
         console.log(docsMessage);
-    console.log(picocolors_1.default.dim(`\nnext: add real fields to model.go/dto.go, run \`go build ./...\`, then apply the migration ` +
+    console.log(picocolors_1.default.dim(`\nnext: add real fields to domain/entity.go, application/dto.go, adapters/inbound/http/dto.go, and the outbound persistence model, then run \`go build ./...\` and apply the migration ` +
         `(use the development bootstrap locally, or \`migrate -path migrations -database "$DB_DSN" up\` before production)`));
 }

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}`;
@@ -62,109 +62,105 @@ function methodOpenapiDocument(naming, method, type, getMode, field) {
     }
     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"),
-        commandPath: path_1.default.join(moduleDir, "commands.go"),
-        queryPath: path_1.default.join(moduleDir, "queries.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",
+            }
+            : {}),
     };
-    const requiredPaths = [
+    const required = [
         paths.dtoPath,
-        paths.repositoryPath,
-        paths.servicePath,
+        paths.requestDTOPath,
+        paths.portsPath,
+        paths.repositoryAdapterPath,
         paths.handlerPath,
         paths.serviceTestPath,
+        ...(cqrs ? [paths.commandPath, paths.queryPath] : [paths.servicePath]),
     ];
-    for (const p of requiredPaths) {
-        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 cqrsPaths = [paths.commandPath, paths.queryPath].filter((candidate) => candidate !== undefined && fs_extra_1.default.existsSync(candidate));
-    if (cqrsPaths.length === 1) {
-        throw new Error(`module "${naming.pkg}" has an incomplete CQRS boundary at ${moduleDir} — ` +
-            `commands.go and queries.go must be present together`);
+    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.markersPresentForPaths)(paths)) {
-        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");
     }
-    const implementationFile = cqrsPaths.length === 2 ? (type === "get" ? "queries.go" : "commands.go") : "service.go";
-    console.log(picocolors_1.default.dim(`\nnext: fill in the TODO in ${implementationFile}, then \`go build ./...\` / \`go test ./...\``));
+    await generateHexagonalMethod(config, naming, methodNameArg, opts, projectDir);
 }

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,
-    // architecture defaults and the feature flags
-    const base = { projectName: config.projectName, apiPrefix: config.apiPrefix, ...config.architecture, ...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");
-}