@nakedev/go-scaffold 0.4.0 → 0.5.0

package/dist/utils/auth-patcher.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.patchConfigForAuth = patchConfigForAuth;
 exports.authWiringLines = authWiringLines;
+exports.authHandlerLineFor = authHandlerLineFor;
 exports.patchMainGoForAuth = patchMainGoForAuth;
 exports.upgradeMailerToQueue = upgradeMailerToQueue;
 const fs_extra_1 = __importDefault(require("fs-extra"));
@@ -17,8 +18,7 @@ const PLATFORM_INIT_MARKER = "// go-scaffold:platform-init";
 const SCHEMA_MARKER = "// go-scaffold:schemas";
 const MODEL_MARKER = "// go-scaffold:models";
 const ROUTE_MARKER = "// go-scaffold:routes";
-const SHUTDOWN_MARKER = "// go-scaffold:shutdown";
-// patchConfigForAuth adds JWT/cookie/password-reset/Google OAuth fields to
+// patchConfigForAuth adds JWT/cookie/password-reset/browser OAuth fields to
 // Config, the same marker-based text insertion patchConfigForWorker uses
 // (config.go.hbs is only rendered once, at `create` — everything after that
 // is a real file a human may have already edited).
@@ -28,8 +28,11 @@ function patchConfigForAuth(configGoPath) {
         "JWTSecret string",
         "JWTAccessTTL time.Duration",
         "JWTRefreshTTL time.Duration",
+        "JWTRefreshMaxTTL time.Duration",
+        "OAuthStateTTL time.Duration",
         "CookieSecure bool",
         "CookieSameSite string",
+        "AuthBrowserTopology string",
         "",
         "PasswordResetTTL time.Duration",
         "PasswordResetURL string",
@@ -39,15 +42,25 @@ function patchConfigForAuth(configGoPath) {
         "",
         "GoogleClientID string",
         "GoogleClientSecret string",
-        "GoogleRedirectURL string",
+        "GoogleOAuthRedirectURI string",
+        "",
+        "AuthMFAEnabled bool",
+        "MFAIssuer string",
+        "MFAEncryptionKey string",
+        "MFAChallengeTTL time.Duration",
+        "MFATOTPWindow int",
+        "MFARecoveryCodeCount int",
     ].join("\n");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_FIELDS_MARKER, fieldsBlock, "JWTSecret");
     const loadBlock = [
         'JWTSecret:     env("JWT_SECRET", "dev-secret-change-me"),',
         'JWTAccessTTL:  time.Duration(envInt("JWT_ACCESS_TTL_MIN", 15)) * time.Minute,',
         'JWTRefreshTTL: time.Duration(envInt("JWT_REFRESH_TTL_MIN", 43200)) * time.Minute,',
+        'JWTRefreshMaxTTL: time.Duration(envInt("JWT_REFRESH_MAX_TTL_MIN", 43200)) * time.Minute,',
+        'OAuthStateTTL: time.Duration(envInt("OAUTH_STATE_TTL_MIN", 10)) * time.Minute,',
         'CookieSecure:  env("COOKIE_SECURE", "false") == "true",',
         'CookieSameSite: env("COOKIE_SAMESITE", "strict"),',
+        'AuthBrowserTopology:    env("AUTH_BROWSER_TOPOLOGY", "same-site"),',
         "",
         'PasswordResetTTL: time.Duration(envInt("PASSWORD_RESET_TTL_MIN", 30)) * time.Minute,',
         'PasswordResetURL: env("PASSWORD_RESET_URL", "http://localhost:3000/reset-password"),',
@@ -57,7 +70,14 @@ function patchConfigForAuth(configGoPath) {
         "",
         'GoogleClientID:     env("GOOGLE_CLIENT_ID", ""),',
         'GoogleClientSecret: env("GOOGLE_CLIENT_SECRET", ""),',
-        'GoogleRedirectURL:  env("GOOGLE_REDIRECT_URL", ""),',
+        'GoogleOAuthRedirectURI: env("GOOGLE_OAUTH_REDIRECT_URI", ""),',
+        "",
+        'AuthMFAEnabled: env("AUTH_MFA_ENABLED", "false") == "true",',
+        'MFAIssuer: env("MFA_ISSUER", "go-scaffold"),',
+        'MFAEncryptionKey: env("MFA_ENCRYPTION_KEY", ""),',
+        'MFAChallengeTTL: time.Duration(envInt("MFA_CHALLENGE_TTL_MIN", 5)) * time.Minute,',
+        'MFATOTPWindow: envInt("MFA_TOTP_WINDOW", 1),',
+        'MFARecoveryCodeCount: envInt("MFA_RECOVERY_CODE_COUNT", 10),',
     ].join("\n");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_LOAD_MARKER, loadBlock, 'env("JWT_SECRET"');
     fs_extra_1.default.writeFileSync(configGoPath, content);
@@ -68,26 +88,36 @@ function patchConfigForAuth(configGoPath) {
 function authWiringLines(w) {
     const postgres = w.store === "postgres";
     return {
-        tokenStore: postgres ? "user.NewPgTokenStore(db)" : "user.NewRedisTokenStore(rdb)",
+        tokenStore: postgres ? "user.NewPgTokenStore(db)" : "user.NewRedisTokenStore(rdb, db)",
         limiter: postgres ? "middleware.NewMemoryLimiter()" : "middleware.NewRedisLimiter(rdb)",
         // with a queue the mail is enqueued and the request returns immediately;
         // without one it goes out inline, which is the cost of not running a worker
         mailer: w.worker ? "mail.NewAsyncClient(q)" : "mail.NewSyncClient(mail.Open(cfg))",
     };
 }
+// authHandlerLineFor is the one root-level auth route shape. The feature owns
+// construction; wiring.go only hands it shared infrastructure and, when RBAC
+// is present, the role feature's public capabilities.
+function authHandlerLineFor(w, roleDependencies = ["nil", "nil"]) {
+    const args = ["db", "cfg"];
+    if (w.store === "redis")
+        args.push("rdb");
+    if (w.worker)
+        args.push("q");
+    args.push(...roleDependencies);
+    return `user.NewHandlerFromDB(${args.join(", ")}).Register(api)`;
+}
 function patchMainGoForAuth(mainGoPath, w) {
     const { goModule, queueBackend, store } = w;
     let content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
     const importLine = `"${goModule}/internal/app/user"`;
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
-    const modelImportLine = `usermodel "${goModule}/internal/app/user/model"`;
+    const modelImportLine = `usermodel "${goModule}/internal/app/user/adapters/outbound/postgres"`;
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
     if (w.worker) {
         const queueImportLine = `"${goModule}/internal/platform/queue"`;
         content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, queueImportLine, queueImportLine);
     }
-    const mailImportLine = `"${goModule}/internal/platform/mail"`;
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, mailImportLine, mailImportLine);
     const checkBlock = [
         'if cfg.IsProd() && cfg.JWTSecret == "dev-secret-change-me" {',
         '\treturn errors.New("JWT_SECRET is still the dev default — set a real secret before deploying with APP_ENV=production")',
@@ -105,6 +135,21 @@ function patchMainGoForAuth(mainGoPath, w) {
         "}",
     ].join("\n");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_CHECKS_MARKER, smtpCheckBlock, "SMTP_HOST is unset");
+    const mfaCheckBlock = [
+        "if cfg.AuthMFAEnabled {",
+        "\tif err := user.ValidateMFASettings(user.MFASettings{",
+        "\t\tEnabled: cfg.AuthMFAEnabled,",
+        "\t\tIssuer: cfg.MFAIssuer,",
+        "\t\tEncryptionKey: cfg.MFAEncryptionKey,",
+        "\t\tChallengeTTL: cfg.MFAChallengeTTL,",
+        "\t\tTOTPWindow: cfg.MFATOTPWindow,",
+        "\t\tRecoveryCodeCount: cfg.MFARecoveryCodeCount,",
+        "\t}); err != nil {",
+        "\t\treturn fmt.Errorf(\"invalid MFA configuration: %w\", err)",
+        "\t}",
+        "}",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_CHECKS_MARKER, mfaCheckBlock, "invalid MFA configuration");
     // The enqueuer is built from whatever backend `add worker` chose — the
     // constructor differs, everything downstream of it (mail.NewAsyncClient)
     // only sees the queue.Enqueuer interface and doesn't change.
@@ -120,24 +165,27 @@ function patchMainGoForAuth(mainGoPath, w) {
     ].join("\n");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS user_svc");
     const migrateLines = ["&usermodel.User{},", "&usermodel.Identity{},", "&usermodel.LoginThrottle{},"];
-    // only the Postgres store has a table for AutoMigrate to create
-    if (store === "postgres")
-        migrateLines.push("&usermodel.AuthToken{},");
+    // Recovery tokens are always durable in Postgres, even when refresh tokens
+    // live in Redis, so reset/verification can share the user transaction.
+    migrateLines.push("&usermodel.AuthToken{},");
+    migrateLines.push("&usermodel.MFAEnrollment{},", "&usermodel.MFAChallenge{},", "&usermodel.MFARecoveryCode{},");
     for (const line of migrateLines) {
         content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
     }
-    // same two-line shape every generated module uses: a named service, then
-    // the handler that registers it. `add rbac` extends both lines later, and a
-    // human wiring another domain into user's service edits line one in place.
-    const { tokenStore, limiter, mailer } = authWiringLines(w);
-    const svcLine = `userSvc := user.NewService(user.NewRepository(db), ${tokenStore}, ${mailer}, cfg)`;
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, ROUTE_MARKER, svcLine, "userSvc :=");
-    const routeLine = `user.NewHandler(userSvc, cfg.JWTSecret, cfg.JWTRefreshTTL, cfg.CookieSecure, cfg.CookieSameSite, ${limiter}).Register(api)`;
+    // Keep auth construction inside the feature package. The root only chooses
+    // shared infrastructure and registers the resulting handler.
+    const routeLine = authHandlerLineFor(w);
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, ROUTE_MARKER, routeLine, routeLine);
     content = content.replace(/\n\t_ = api \/\/ dropped once `generate module` registers the first route\n/, "\n");
     if (w.worker) {
-        const shutdownBlock = ["if err := q.Close(); err != nil {", '\tlogger.Error("close queue", "error", err)', "}"].join("\n");
-        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SHUTDOWN_MARKER, shutdownBlock, "if err := q.Close()");
+        const cleanupBlock = [
+            "defer func() {",
+            '\tif err := q.Close(); err != nil {',
+            '\t\tlogger.Error("close queue", "error", err)',
+            "\t}",
+            "}()",
+        ].join("\n");
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PLATFORM_INIT_MARKER, cleanupBlock, "defer func() {\n\tif err := q.Close()");
     }
     fs_extra_1.default.writeFileSync(mainGoPath, content);
 }
@@ -153,19 +201,62 @@ function patchMainGoForAuth(mainGoPath, w) {
 // at all — both simply don't contain the line it looks for. Returns whether
 // it actually upgraded something, so the caller's printed summary can say
 // which happened instead of always assuming "no auth yet".
-function upgradeMailerToQueue(mainGoPath, goModule, queueBackend) {
+function upgradeMailerToQueue(mainGoPath, goModule, queueBackend, compositionGoPath) {
     let content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
     const syncMailer = "mail.NewSyncClient(mail.Open(cfg))";
-    if (!content.includes(syncMailer))
-        return false;
-    const queueImportLine = `"${goModule}/internal/platform/queue"`;
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, queueImportLine, queueImportLine);
-    const queueCtor = queueBackend === "river" ? "queue.NewRiverEnqueuer(db)" : "queue.NewAsynqEnqueuer(cfg.RedisURL)";
-    const queueInitBlock = [`q, err := ${queueCtor}`, "if err != nil {", '\treturn fmt.Errorf("open queue: %w", err)', "}"].join("\n");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PLATFORM_INIT_MARKER, queueInitBlock, "q, err := queue.New");
-    const shutdownBlock = ["if err := q.Close(); err != nil {", '\tlogger.Error("close queue", "error", err)', "}"].join("\n");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SHUTDOWN_MARKER, shutdownBlock, "if err := q.Close()");
-    content = content.replace(syncMailer, () => "mail.NewAsyncClient(q)");
-    fs_extra_1.default.writeFileSync(mainGoPath, content);
-    return true;
+    let upgradedComposition = false;
+    // Auth now keeps mailer construction in internal/app/user. A worker added
+    // later must upgrade that feature-local composition and thread q into the
+    // existing root registration, rather than moving construction back to the
+    // composition root.
+    if (compositionGoPath && fs_extra_1.default.existsSync(compositionGoPath)) {
+        let composition = fs_extra_1.default.readFileSync(compositionGoPath, "utf8");
+        if (composition.includes(syncMailer)) {
+            composition = (0, marker_patch_1.ensureImport)(composition, `${goModule}/internal/platform/queue`);
+            if (!composition.includes("q queue.Enqueuer")) {
+                const configParam = "\tcfg config.Config,\n";
+                const redisParam = "\trdb *redis.Client,\n";
+                const queueAnchor = composition.includes(redisParam) ? redisParam : configParam;
+                if (!composition.includes(queueAnchor)) {
+                    throw new Error(`${compositionGoPath} is missing the cfg parameter needed to upgrade auth mail to a queue`);
+                }
+                composition = composition.replace(queueAnchor, `${queueAnchor}\tq queue.Enqueuer,\n`);
+            }
+            composition = composition.replace(syncMailer, "mail.NewAsyncClient(q)");
+            fs_extra_1.default.writeFileSync(compositionGoPath, composition);
+            upgradedComposition = true;
+            const routeMatch = content.match(/user\.NewHandlerFromDB\(db, cfg, ([^)]*)\)\.Register\(api\)/);
+            if (!routeMatch) {
+                throw new Error("cmd/api/wiring.go is missing auth's feature-local NewHandlerFromDB route while adding the worker");
+            }
+            const args = routeMatch[1].split(",").map((arg) => arg.trim());
+            if (!args.includes("q")) {
+                if (args.length < 2)
+                    throw new Error("auth's NewHandlerFromDB route has no role/authz dependency slots");
+                args.splice(args.length - 2, 0, "q");
+                content = content.replace(routeMatch[0], `user.NewHandlerFromDB(db, cfg, ${args.join(", ")}).Register(api)`);
+            }
+        }
+    }
+    if (upgradedComposition) {
+        const queueImportLine = `"${goModule}/internal/platform/queue"`;
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, queueImportLine, queueImportLine);
+        const queueCtor = queueBackend === "river" ? "queue.NewRiverEnqueuer(db)" : "queue.NewAsynqEnqueuer(cfg.RedisURL)";
+        const queueInitBlock = [`q, err := ${queueCtor}`, "if err != nil {", '\treturn fmt.Errorf("open queue: %w", err)', "}"].join("\n");
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PLATFORM_INIT_MARKER, queueInitBlock, "q, err := queue.New");
+        const cleanupBlock = [
+            "defer func() {",
+            '\tif err := q.Close(); err != nil {',
+            '\t\tlogger.Error("close queue", "error", err)',
+            "\t}",
+            "}()",
+        ].join("\n");
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PLATFORM_INIT_MARKER, cleanupBlock, "defer func() {\n\tif err := q.Close()");
+        fs_extra_1.default.writeFileSync(mainGoPath, content);
+        return true;
+    }
+    if (content.includes(syncMailer)) {
+        throw new Error("auth mailer is not owned by internal/app/user/composition.go; regenerate auth with the canonical split layout before adding a worker");
+    }
+    return false;
 }

package/dist/utils/config.js

@@ -3,18 +3,45 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_SCHEMA_VERSION = void 0;
 exports.configPath = configPath;
+exports.parseModuleSurface = parseModuleSurface;
+exports.parseApplicationStyle = parseApplicationStyle;
+exports.parseModuleProfile = parseModuleProfile;
 exports.writeConfig = writeConfig;
 exports.readConfig = readConfig;
 exports.isProjectDir = isProjectDir;
 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 = 2;
 function configPath(projectDir) {
     return path_1.default.join(projectDir, CONFIG_FILE);
 }
+function parseModuleSurface(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    assertOneOf(normalized, "--module-surface", ["minimal", "crud"]);
+    return normalized;
+}
+function parseApplicationStyle(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    assertOneOf(normalized, "--application-style", ["service", "cqrs"]);
+    return normalized;
+}
+function parseModuleProfile(value, flag = "--profile") {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    assertOneOf(normalized, flag, ["lean", "crud", "cqrs"]);
+    return normalized;
+}
 function writeConfig(projectDir, config) {
-    fs_extra_1.default.writeJsonSync(configPath(projectDir), config, { spaces: 2 });
+    fs_extra_1.default.writeJsonSync(configPath(projectDir), normalizeProjectConfig(config, projectDir), { spaces: 2 });
 }
 // readConfig falls back to detecting from go.mod when the config file is
 // missing (e.g. a project scaffolded before this file existed).
@@ -35,13 +62,142 @@ function readConfig(projectDir) {
     if (!fs_extra_1.default.existsSync(file))
         return detectConfig(projectDir);
     const config = fs_extra_1.default.readJsonSync(file);
+    if (!isRecord(config)) {
+        throw new Error(`${CONFIG_FILE} must contain a JSON object`);
+    }
     const detected = detectFeatures(projectDir);
-    const features = { ...config.features };
+    const features = { ...(isRecord(config.features) ? config.features : {}) };
     for (const key of Object.keys(detected)) {
         if (features[key] === undefined)
             features[key] = detected[key];
     }
-    return { ...config, features };
+    return normalizeProjectConfig({ ...config, features: features }, projectDir);
+}
+/**
+ * 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");
+    const goModule = requiredString(raw.goModule, "goModule");
+    const apiPrefix = requiredString(raw.apiPrefix ?? "", "apiPrefix");
+    const schemaVersion = raw.schemaVersion ?? exports.CONFIG_SCHEMA_VERSION;
+    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`);
+    }
+    const detected = detectFeatures(projectDir);
+    const features = { ...(isRecord(raw.features) ? raw.features : {}) };
+    for (const key of Object.keys(detected)) {
+        if (features[key] === undefined)
+            features[key] = detected[key];
+    }
+    validateFeatures(features);
+    const architecture = normalizeArchitecture(raw.architecture);
+    const modules = normalizeModules(raw.modules);
+    return {
+        schemaVersion,
+        projectName,
+        goModule,
+        apiPrefix,
+        features: features,
+        architecture,
+        modules,
+        ...(raw.scaffoldVersion ? { scaffoldVersion: raw.scaffoldVersion } : {}),
+    };
+}
+function normalizeArchitecture(raw) {
+    const value = raw === undefined ? {} : raw;
+    if (!isRecord(value)) {
+        throw new Error(`${CONFIG_FILE}.architecture must be a JSON object`);
+    }
+    const architecture = {
+        ...types_1.DEFAULT_ARCHITECTURE_CONFIG,
+        ...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,
+    };
+}
+function normalizeModules(raw) {
+    if (raw === undefined)
+        return {};
+    if (!isRecord(raw))
+        throw new Error(`${CONFIG_FILE}.modules must be a JSON object`);
+    const modules = {};
+    for (const [name, entry] of Object.entries(raw)) {
+        if (!name || name.includes("/") || name.includes("\\")) {
+            throw new Error(`${CONFIG_FILE}.modules has invalid module key "${name}" — use the module's Go package name`);
+        }
+        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;
+}
+function validateFeatures(features) {
+    if (typeof features.docker !== "boolean")
+        throw new Error(`${CONFIG_FILE}.features.docker must be true or false`);
+    if (typeof features.openapiDocs !== "boolean")
+        throw new Error(`${CONFIG_FILE}.features.openapiDocs must be true or false`);
+    if (features.worker !== undefined && typeof features.worker !== "boolean") {
+        throw new Error(`${CONFIG_FILE}.features.worker must be true or false`);
+    }
+    if (features.queue !== undefined)
+        assertOneOf(features.queue, "features.queue", ["river", "asynq"]);
+    if (features.auth !== undefined && typeof features.auth !== "boolean") {
+        throw new Error(`${CONFIG_FILE}.features.auth must be true or false`);
+    }
+    if (features.authStore !== undefined)
+        assertOneOf(features.authStore, "features.authStore", ["postgres", "redis"]);
+    if (features.rbac !== undefined && typeof features.rbac !== "boolean") {
+        throw new Error(`${CONFIG_FILE}.features.rbac must be true or false`);
+    }
+    if (features.observability !== undefined && typeof features.observability !== "boolean") {
+        throw new Error(`${CONFIG_FILE}.features.observability must be true or false`);
+    }
+}
+function requiredString(value, field) {
+    if (typeof value !== "string")
+        throw new Error(`${CONFIG_FILE}.${field} must be a string`);
+    return value;
+}
+function assertOneOf(value, field, allowed) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        const label = field.startsWith("--") ? field : `${CONFIG_FILE}.${field}`;
+        throw new Error(`${label} must be one of: ${allowed.join(", ")} (got "${String(value)}")`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 // detectFeatures answers "what is actually installed here" from the tree
 // alone. Every `add` command leaves a directory or a file behind that nothing
@@ -66,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"),
     };
@@ -107,10 +267,13 @@ function detectConfig(projectDir) {
     // already exists"), with no way out. Worse, the first `add` to succeed then
     // wrote a config that recorded the undetected features as absent.
     return {
+        schemaVersion: exports.CONFIG_SCHEMA_VERSION,
         projectName: path_1.default.basename(projectDir),
         goModule,
         apiPrefix,
         features: detectFeatures(projectDir),
+        architecture: { ...types_1.DEFAULT_ARCHITECTURE_CONFIG },
+        modules: {},
     };
 }
 // isProjectDir answers "would readConfig succeed here?" without throwing, so

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");
+}