@nakedev/go-scaffold 0.4.0 → 0.5.0

package/dist/commands/auth.js

@@ -18,6 +18,8 @@ const migrations_1 = require("../utils/migrations");
 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.
@@ -29,20 +31,26 @@ const AUTH_OPENAPI_PATHS = [
     { urlPath: "/auth/forgot-password", file: "./auth/forgot-password.yaml" },
     { urlPath: "/auth/reset-password", file: "./auth/reset-password.yaml" },
     { urlPath: "/auth/verify-email", file: "./auth/verify-email.yaml" },
-    { urlPath: "/auth/google/login", file: "./auth/google-login.yaml" },
-    { urlPath: "/auth/google/callback", file: "./auth/google-callback.yaml" },
+    { urlPath: "/auth/{provider}/login", file: "./auth/provider-login.yaml" },
+    { urlPath: "/auth/{provider}/exchange", file: "./auth/provider-exchange.yaml" },
     { urlPath: "/users/me", file: "./auth/users-me.yaml" },
     { urlPath: "/users/me/resend-verification", file: "./auth/users-me-resend-verification.yaml" },
     { urlPath: "/users/me/logout-all", file: "./auth/users-me-logout-all.yaml" },
+    { urlPath: "/users/me/mfa", file: "./auth/users-me-mfa.yaml" },
+    { urlPath: "/users/me/mfa/setup", file: "./auth/users-me-mfa-setup.yaml" },
+    { urlPath: "/users/me/mfa/confirm", file: "./auth/users-me-mfa-confirm.yaml" },
+    { urlPath: "/users/me/mfa/disable", file: "./auth/users-me-mfa-disable.yaml" },
+    { urlPath: "/auth/mfa/verify", file: "./auth/mfa-verify.yaml" },
 ];
 // addAuth scaffolds email/password authentication: a users+identities model
-// pair, JWT access tokens, a Redis-backed refresh token store with
+// pair, JWT access tokens, a selectable refresh token store with
 // rotation + reuse detection, and register/login/refresh/logout/me. No RBAC
 // (no roles/permissions) — that's a separate opt-in on top of this, since
 // most projects need "is this caller logged in" long before they need "can
 // this caller do X".
-async function addAuth(store = "postgres", projectDir = process.cwd()) {
+async function addAuth(store = "postgres", projectDir = process.cwd(), browserTopology = auth_wizard_1.DEFAULT_BROWSER_TOPOLOGY) {
     const config = (0, config_1.readConfig)(projectDir);
+    const browser = (0, auth_wizard_1.validateBrowserTopology)(browserTopology);
     // No longer a prerequisite. Without a worker the verification and reset mail
     // goes out inline instead of through a queue — a real trade (those two
     // endpoints then block on SMTP), but not one worth forcing a second binary
@@ -63,7 +71,11 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
         (0, platform_patcher_1.patchConfigForSMTP)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"));
         patchEnvExampleForSMTP(path_1.default.join(projectDir, ".env.example"));
     }
-    await (0, template_renderer_1.applyTemplateEntries)(projectDir, (0, auth_manifest_1.authFiles)(store), { goModule: config.goModule });
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, (0, auth_manifest_1.authFiles)(store), {
+        goModule: config.goModule,
+        redis: store === "redis",
+        worker,
+    });
     const migrationsDir = path_1.default.join(projectDir, "migrations");
     fs_extra_1.default.ensureDirSync(migrationsDir);
     const usersVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
@@ -71,6 +83,11 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
         { template: "add/auth/migrations/create_users.up.sql.hbs", output: path_1.default.join("migrations", `${usersVersion}_create_users.up.sql`) },
         { template: "add/auth/migrations/create_users.down.sql.hbs", output: path_1.default.join("migrations", `${usersVersion}_create_users.down.sql`) },
     ], {});
+    const mfaVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_mfa.up.sql.hbs", output: path_1.default.join("migrations", `${mfaVersion}_create_mfa.up.sql`) },
+        { template: "add/auth/migrations/create_mfa.down.sql.hbs", output: path_1.default.join("migrations", `${mfaVersion}_create_mfa.down.sql`) },
+    ], {});
     // identities references users(id) — must apply strictly after it. A
     // second newMigrationVersion() call, scanning the dir again now that the
     // users pair is already written, guarantees a later (or same-second,
@@ -87,13 +104,13 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
         { template: "add/auth/migrations/create_login_throttle.up.sql.hbs", output: path_1.default.join("migrations", `${throttleVersion}_create_login_throttle.up.sql`) },
         { template: "add/auth/migrations/create_login_throttle.down.sql.hbs", output: path_1.default.join("migrations", `${throttleVersion}_create_login_throttle.down.sql`) },
     ], {});
-    if (store === "postgres") {
-        const authTokensVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
-        await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
-            { template: "add/auth/migrations/create_auth_tokens.up.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.up.sql`) },
-            { template: "add/auth/migrations/create_auth_tokens.down.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.down.sql`) },
-        ], {});
-    }
+    // Recovery tokens are always stored in Postgres so consumption and the user
+    // update can share one transaction, even when refresh rotation uses Redis.
+    const authTokensVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_auth_tokens.up.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.up.sql`) },
+        { template: "add/auth/migrations/create_auth_tokens.down.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.down.sql`) },
+    ], {});
     // Only meaningful when there is a worker; readConfig fills this from the
     // adapter file on disk, so the only way it is still unknown is a project
     // that has internal/platform/queue with neither adapter in it. Guessing
@@ -120,7 +137,7 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
         // go-redis only when something in this project actually constructs a client
         ...(store === "redis" ? ["github.com/redis/go-redis/v9 v9.22.0"] : []),
     ]);
-    patchEnvExample(path_1.default.join(projectDir, ".env.example"));
+    patchEnvExample(path_1.default.join(projectDir, ".env.example"), browser);
     patchMakefile(path_1.default.join(projectDir, "Makefile"));
     let docsMessage = "";
     const openapiPath = path_1.default.join(projectDir, "docs", "openapi.yaml");
@@ -140,19 +157,30 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
     // 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"
         : "verification + password-reset mail is sent inline (no worker) — run `add worker` later to move it onto the queue");
     console.log(store === "postgres"
-        ? "tokens + rate-limit counters: Postgres (user_svc.auth_tokens) and in-process — no Redis"
-        : "tokens + rate-limit counters: Redis");
+        ? "refresh + recovery tokens: Postgres (user_svc.auth_tokens), rate-limit counters in-process — no Redis"
+        : "refresh tokens + rate-limit counters: Redis; recovery tokens: Postgres (user_svc.auth_tokens)");
     console.log("registered POST /auth/{register,login,refresh,logout,forgot-password,reset-password,verify-email}, " +
-        "GET /auth/google/{login,callback}, GET /users/me, and " +
-        "POST /users/me/{resend-verification,logout-all} in cmd/api/wiring.go" +
+        "GET /auth/{provider}/login, POST /auth/{provider}/exchange, GET /users/me, and " +
+        "POST /users/me/{resend-verification,logout-all,mfa/setup,mfa/confirm,mfa/disable}, " +
+        "GET /users/me/mfa, and POST /auth/mfa/verify in cmd/api/wiring.go" +
         docsMessage);
-    console.log(picocolors_1.default.dim("\nnext: go mod tidy, then apply the new migrations (AUTO_MIGRATE=true picks them up automatically in dev)\n" +
+    console.log(picocolors_1.default.dim("\nnext: go mod tidy, then apply the new migrations with `make migrate-up` before production\n" +
         "seed an admin: SEED_ADMIN_EMAIL=... SEED_ADMIN_PASSWORD=... make seed"));
 }
 function patchMakefile(makefilePath) {
@@ -183,7 +211,7 @@ function patchMakefile(makefilePath) {
     content = content.replace(/\nbuild:/, () => `${target}\nbuild:`);
     fs_extra_1.default.writeFileSync(makefilePath, content);
 }
-function patchEnvExample(envExamplePath) {
+function patchEnvExample(envExamplePath, browserTopology) {
     if (!fs_extra_1.default.existsSync(envExamplePath))
         return;
     let content = fs_extra_1.default.readFileSync(envExamplePath, "utf8");
@@ -195,13 +223,15 @@ function patchEnvExample(envExamplePath) {
             "JWT_SECRET=dev-secret-change-me\n" +
             "JWT_ACCESS_TTL_MIN=15\n" +
             "JWT_REFRESH_TTL_MIN=43200\n" +
-            "COOKIE_SECURE=false\n" +
+            "JWT_REFRESH_MAX_TTL_MIN=43200\n" +
+            "OAUTH_STATE_TTL_MIN=10\n" +
+            `COOKIE_SECURE=${browserTopology === "cross-site" ? "true" : "false"}\n` +
             "# strict | lax | none — the refresh cookie's SameSite. Keep strict while the\n" +
             "# frontend is the same site as this API (localhost:3000 -> localhost:8080 is,\n" +
             "# and so is app.example.com -> api.example.com). A frontend on a different\n" +
             "# site entirely needs none, together with COOKIE_SECURE=true, or the browser\n" +
             "# never sends the cookie to /auth/refresh and sessions die at every expiry.\n" +
-            "COOKIE_SAMESITE=strict\n" +
+            `COOKIE_SAMESITE=${browserTopology === "cross-site" ? "none" : "strict"}\n` +
             "\nPASSWORD_RESET_TTL_MIN=30\n" +
             "PASSWORD_RESET_URL=http://localhost:3000/reset-password\n" +
             "\nEMAIL_VERIFY_TTL_MIN=1440\n" +
@@ -209,7 +239,19 @@ function patchEnvExample(envExamplePath) {
             "\n# leave the Google vars unset to disable Google login (register/login/refresh still work)\n" +
             "GOOGLE_CLIENT_ID=\n" +
             "GOOGLE_CLIENT_SECRET=\n" +
-            "GOOGLE_REDIRECT_URL=\n";
+            "# exact browser callback URI registered with the provider (frontend-owned route)\n" +
+            "GOOGLE_OAUTH_REDIRECT_URI=\n" +
+            "\n# cookie/CORS deployment topology; the frontend owns its provider callback route\n" +
+            `AUTH_BROWSER_TOPOLOGY=${browserTopology}\n` +
+            "\n# MFA is globally off by default. When enabled, set a base64-encoded 32-byte\n" +
+            "# AES-256 key (for example: openssl rand -base64 32). Users still opt in\n" +
+            "# individually through /users/me/mfa/setup and /users/me/mfa/confirm.\n" +
+            "AUTH_MFA_ENABLED=false\n" +
+            "MFA_ISSUER=go-scaffold\n" +
+            "MFA_ENCRYPTION_KEY=\n" +
+            "MFA_CHALLENGE_TTL_MIN=5\n" +
+            "MFA_TOTP_WINDOW=1\n" +
+            "MFA_RECOVERY_CODE_COUNT=10\n";
     fs_extra_1.default.writeFileSync(envExamplePath, content);
 }
 // ensureRedis adds internal/platform/cache + its config/env/main.go wiring

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/config.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureProject = configureProject;
+exports.showProjectConfig = showProjectConfig;
+exports.validateProjectConfig = validateProjectConfig;
+const picocolors_1 = __importDefault(require("picocolors"));
+const generate_wizard_1 = require("../prompts/generate-wizard");
+const interactive_1 = require("../prompts/interactive");
+const config_1 = require("../utils/config");
+const module_profile_1 = require("../utils/module-profile");
+/**
+ * Interactive project-level defaults. Existing modules are not rewritten: the
+ * wizard only controls what a future `generate module` receives when the user
+ * chooses `--defaults` or accepts the generated-module prompt defaults.
+ */
+async function configureProject(projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    console.log("\nConfigure future generated modules:\n");
+    const profile = await (0, generate_wizard_1.promptModuleProfile)((0, module_profile_1.moduleProfileFor)(config.architecture.defaultModuleSurface, config.architecture.defaultApplicationStyle));
+    const { moduleSurface: defaultModuleSurface, applicationStyle: defaultApplicationStyle } = profile === "advanced"
+        ? await (0, generate_wizard_1.promptAdvancedModuleArchitecture)(config.architecture.defaultModuleSurface, config.architecture.defaultApplicationStyle)
+        : (0, generate_wizard_1.moduleArchitectureForProfile)(profile);
+    console.log("\nSummary:");
+    console.log(`  Default module profile: ${(0, generate_wizard_1.moduleProfileDescription)(defaultModuleSurface, defaultApplicationStyle)}`);
+    console.log(`  Default module surface: ${defaultModuleSurface}`);
+    console.log(`  Default application style: ${defaultApplicationStyle}`);
+    console.log("  Existing modules: unchanged");
+    const proceed = await (0, interactive_1.confirm)({ message: "Save these project defaults?", default: true });
+    if (!proceed)
+        throw new Error("configuration cancelled");
+    (0, config_1.writeConfig)(projectDir, {
+        ...config,
+        architecture: {
+            ...config.architecture,
+            defaultModuleSurface,
+            defaultApplicationStyle,
+        },
+    });
+    console.log(picocolors_1.default.green("\nupdated go-scaffold.config.json"));
+}
+function showProjectConfig(projectDir = process.cwd()) {
+    console.log(JSON.stringify((0, config_1.readConfig)(projectDir), null, 2));
+}
+function validateProjectConfig(projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    console.log(picocolors_1.default.green(`valid go-scaffold.config.json (schema ${config.schemaVersion})`));
+}

package/dist/commands/create.js

@@ -13,7 +13,10 @@ const config_1 = require("../utils/config");
 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) {
     const trimmed = (rawName ?? (await (0, create_wizard_1.promptProjectName)())).trim();
     if (!trimmed)
@@ -27,6 +30,13 @@ async function createProject(rawName, opts) {
     }
     let features;
     let apiPrefix;
+    let architecture;
+    const moduleProfile = (0, config_1.parseModuleProfile)(opts.moduleProfile, "--module-profile");
+    const moduleSurface = (0, config_1.parseModuleSurface)(opts.moduleSurface);
+    const applicationStyle = (0, config_1.parseApplicationStyle)(opts.applicationStyle);
+    if (moduleProfile && (moduleSurface || applicationStyle)) {
+        throw new Error("--module-profile cannot be combined with --module-surface or --application-style — choose one configuration style");
+    }
     if (opts.defaults) {
         features = { docker: opts.docker ?? true, openapiDocs: opts.openapiDocs ?? true, observability: opts.observability ?? false };
         // "" to match what the wizard's Enter now gives. --defaults means "don't
@@ -37,16 +47,27 @@ async function createProject(rawName, opts) {
         const check = (0, naming_1.validateApiPrefix)(apiPrefix);
         if (check !== true)
             throw new Error(check);
+        const profileArchitecture = moduleProfile ? (0, module_profile_1.architectureForModuleProfile)(moduleProfile) : undefined;
+        architecture = {
+            ...types_1.DEFAULT_ARCHITECTURE_CONFIG,
+            ...(profileArchitecture ? { defaultModuleSurface: profileArchitecture.moduleSurface } : {}),
+            ...(profileArchitecture ? { defaultApplicationStyle: profileArchitecture.applicationStyle } : {}),
+            ...(!profileArchitecture && moduleSurface ? { defaultModuleSurface: moduleSurface } : {}),
+            ...(!profileArchitecture && applicationStyle ? { defaultApplicationStyle: applicationStyle } : {}),
+        };
     }
     else {
         // commander gives `--no-x` options a default of true, and there is no
         // `--docker`/`--openapi-docs` to pass, so false here can only mean the
         // caller opted out explicitly. undefined leaves the question to the wizard.
-        ({ features, apiPrefix } = await (0, create_wizard_1.runCreateWizard)({
+        ({ features, apiPrefix, architecture } = await (0, create_wizard_1.runCreateWizard)({
             docker: opts.docker === false ? false : undefined,
             openapiDocs: opts.openapiDocs === false ? false : undefined,
             observability: opts.observability === true ? true : undefined,
             apiPrefix: opts.apiPrefix,
+            moduleProfile,
+            moduleSurface,
+            applicationStyle,
         }));
     }
     const context = {
@@ -54,12 +75,22 @@ async function createProject(rawName, opts) {
         goModule,
         dbName: (0, naming_1.toDbName)(projectName),
         apiPrefix,
+        ...architecture,
         ...features,
     };
     await fs_extra_1.default.ensureDir(projectDir);
     await (0, template_renderer_1.applyTemplateEntries)(projectDir, create_manifest_1.CREATE_MANIFEST, context);
     (0, template_renderer_1.gofmtTree)(projectDir);
-    (0, config_1.writeConfig)(projectDir, { projectName, goModule, apiPrefix, features, scaffoldVersion: (0, version_1.cliVersion)() });
+    (0, config_1.writeConfig)(projectDir, {
+        schemaVersion: config_2.CONFIG_SCHEMA_VERSION,
+        projectName,
+        goModule,
+        apiPrefix,
+        features,
+        architecture,
+        modules: {},
+        scaffoldVersion: (0, version_1.cliVersion)(),
+    });
     // Composed the same way a user would do it by hand — `create` always
     // renders the plain base, then this layers the same patches `add
     // observability` would apply on an existing project, so the two paths

package/dist/commands/generate.js

@@ -59,8 +59,18 @@ 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",
     };
-    const moduleFiles = opts.full ? module_manifest_1.MODULE_FILES : module_manifest_1.MODULE_FILES_MINIMAL;
+    const moduleFiles = opts.cqrs
+        ? opts.full
+            ? module_manifest_1.MODULE_FILES_CQRS
+            : module_manifest_1.MODULE_FILES_MINIMAL_CQRS
+        : opts.full
+            ? module_manifest_1.MODULE_FILES
+            : module_manifest_1.MODULE_FILES_MINIMAL;
     const moduleEntries = moduleFiles.map((f) => ({
         template: f.template,
         output: path_1.default.join("internal", "app", modulePath, f.output),
@@ -132,8 +142,24 @@ async function generateModule(rawName, opts, projectDir = process.cwd()) {
     }
     (0, template_renderer_1.gofmtTree)(projectDir);
     (0, gocheck_1.assertNoDrift)(projectDir, checkBefore, config);
+    (0, config_1.writeConfig)(projectDir, {
+        ...config,
+        modules: {
+            ...config.modules,
+            [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 application/commands.go and application/queries.go");
+    }
+    console.log(`recorded module defaults: ${opts.full ? "crud" : "minimal"} + ${opts.cqrs ? "cqrs" : "service"}`);
     if (opts.full) {
         console.log(`registered route ${routePath} in cmd/api/wiring.go`);
     }
@@ -161,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 ` +
-        `(AUTO_MIGRATE=true handles it in dev, or \`migrate -path migrations -database "$DB_DSN" up\`)`));
+    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)`));
 }