zyket 1.2.20 → 1.2.22

package/AGENTS.md

@@ -20,7 +20,7 @@ npx zyket init api-rest        # default | api-rest | saas-multitenant | realtim
 `init` scaffolds the chosen template's files, generates a `.env` (defaults merged with the template's `.env.example`), writes a `package.json` with the right dependencies, and runs `npm install`. Templates that ship auth need their tables created once:
 
 ```bash
-npx @better-auth/cli migrate
+npx @better-auth/cli migrate --config src/services/auth/auth.js
 node index.js
 ```
 
@@ -49,10 +49,10 @@ kernel.boot(clearConsole = true, secretsPath = "<cwd>/.env")
 ```
 
 Boot order:
-1. Load `.env` (creates one with defaults if missing).
-2. Start the HTTP server on `PORT` (default 3000).
+1. Load `.env` (creates one with defaults if missing, including a random `AUTH_SECRET`).
+2. Start the HTTP server on `PORT` (default 3000). Until the Express service attaches, requests are answered `503 {"success":false,"message":"Server is starting"}` with `Retry-After: 1` — so a health check during boot gets an answer instead of hanging. With `DISABLE_EXPRESS=true` every HTTP request keeps getting that 503.
 3. Register **core services** (auto-selected from env, see §4) then your `services`.
-4. Call `boot({ httpServer })` on every service in order.
+4. Call `boot({ httpServer })` on every service in order. `express` boots before `socketio` on purpose: engine.io wraps the existing request listener, so reversing them breaks the socket.io polling transport.
 5. Load each `extensions` instance via `extension.load(container)` (after services).
 
 `kernel.container` exposes the DI container (`container.get('name')`, `container.has('name')`).
@@ -291,7 +291,29 @@ module.exports = class CustomAuthService extends AuthService {
 };
 ```
 
-Requirements: `DATABASE_DIALECT` must be `sqlite` or `postgresql`. Run `npx @better-auth/cli migrate` to create auth tables (it reads `src/services/auth/auth.js`).
+Requirements: `DATABASE_DIALECT` must be `sqlite` or `postgresql`.
+
+### Creating / updating the auth tables
+
+`AuthService.migrate()` runs whatever better-auth migrations are still pending — creating missing tables and adding missing columns — using the **installed** better-auth, so it always matches the schema your app expects:
+
+```js
+kernel.boot().then(async () => {
+  const { pending, tablesCreated, fieldsAdded } = await kernel.container.get('auth').migrate();
+  // { pending: 5, tablesCreated: ['user','account','organization',…], fieldsAdded: [] }
+});
+```
+
+| Call | Effect |
+|------|--------|
+| `await auth.migrate()` | applies pending migrations; returns `{ pending, tablesCreated, fieldsAdded }` |
+| `await auth.migrate({ dryRun: true })` | applies nothing; adds `sql` (the compiled statements) to the return value |
+
+Run it after adding a plugin, an `additionalFields` entry, or on a fresh database. It is idempotent — `pending: 0` when there is nothing to do — but it is **not** automatic: nothing migrates on boot unless you call it. `sqlite`/`postgresql` only (it throws otherwise).
+
+The external CLI still works — `npx @better-auth/cli migrate --config src/services/auth/auth.js` — and `--config` is required, because the CLI only auto-discovers `auth.js` under `src/{auth,lib,server,utils}/`, never under `src/services/`. Prefer `migrate()`: the CLI bundles its own better-auth copy, so it can disagree with your installed version about the schema (it currently creates a `verification` table that better-auth 1.6 no longer uses).
+
+**No `session` / `verification` tables?** That's expected. The `auth` service always wires better-auth's `secondaryStorage` to the `cache` service, and better-auth then keeps sessions and verification tokens there instead of in SQL. With the default in-memory cache that means **sessions do not survive a restart and are not shared between instances** — set `CACHE_URL=redis://…` for durable, shared sessions, or opt back into SQL with `session: { storeSessionInDatabase: true }` / `verification: { storeInDatabase: true }` in a subclass.
 
 ### Protecting routes & sockets
 
@@ -402,6 +424,6 @@ See `SECURITY.md` for the full audit. Essentials before production:
 3. **Access data** — `const { Thing } = container.get('database').models;`.
 4. **Realtime (optional)** — `src/handlers/<event>.js` with `guards = ["auth"]`; broadcast with `io`.
 5. **Background (optional)** — add the queue to `QUEUES`, `DISABLE_BULLMQ=false`, add `src/workers/<name>.js`, enqueue with `container.get('bullmq').addJob(...)`.
-6. **Run** — `npx @better-auth/cli migrate` (first time) then `node index.js`.
+6. **Run** — `npx @better-auth/cli migrate --config src/services/auth/auth.js` (first time) then `node index.js`.
 
 To scaffold any component quickly, use the `generate` skill (`/zyket:generate route things/[id]`).

package/README.md

@@ -19,7 +19,7 @@ npx zyket init api-rest      # default | api-rest | saas-multitenant | realtime-
 `init` scaffolds the template, generates a `.env`, writes `package.json` with the right dependencies, and installs them. Templates that ship authentication need their tables created once:
 
 ```bash
-npx @better-auth/cli migrate
+npx @better-auth/cli migrate --config src/services/auth/auth.js
 node index.js
 ```
 

package/bin/cli.js

@@ -285,7 +285,10 @@ function npmInstall() {
 			// Templates that ship auth need their tables created first.
 			const usesAuth = fs.existsSync(path.join(process.cwd(), 'src', 'services', 'auth'));
 			console.log('\nNext steps:');
-			if (usesAuth) console.log('  npx @better-auth/cli migrate   # create the auth tables');
+			if (usesAuth) {
+				console.log('  npx @better-auth/cli migrate --config src/services/auth/auth.js   # create the auth tables');
+				console.log("  # or, from inside the app: await container.get('auth').migrate()");
+			}
 			console.log('  node index.js\n');
 			if (fs.existsSync(path.join(process.cwd(), 'README.md'))) {
 				console.log('See README.md for template-specific details.\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zyket",
-  "version": "1.2.20",
+  "version": "1.2.22",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -13,45 +13,45 @@
   "license": "ISC",
   "description": "",
   "dependencies": {
-    "@bull-board/express": "^6.20.6",
-    "@tailwindcss/vite": "^4.2.2",
-    "@vitejs/plugin-react": "^6.0.1",
-    "better-auth": "^1.5.6",
+    "@bull-board/express": "^8.3.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@vitejs/plugin-react": "^6.0.4",
+    "better-auth": "^1.6.25",
     "better-sqlite3": "^12.8.0",
-    "bullmq": "^5.71.0",
+    "bullmq": "^5.81.2",
     "colors": "^1.4.0",
     "cors": "^2.8.6",
-    "dotenv": "^17.3.1",
+    "dotenv": "^17.4.2",
     "express": "^5.2.1",
     "express-basic-auth": "^1.2.1",
     "fast-glob": "^3.3.3",
-    "mariadb": "^3.5.2",
+    "mariadb": "^3.5.3",
     "minio": "^8.0.7",
-    "multer": "^2.1.1",
-    "node-cron": "^4.2.1",
-    "node-dependency-injection": "^3.2.6",
-    "pg": "^8.20.0",
+    "multer": "^2.2.0",
+    "node-cron": "^4.6.0",
+    "node-dependency-injection": "^4.2.2",
+    "pg": "^8.22.0",
     "prompts": "^2.4.2",
     "prop-types": "^15.8.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "react-router-dom": "^7.14.0",
-    "redis": "^5.11.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-router-dom": "^7.18.1",
+    "redis": "^6.1.0",
     "sequelize": "^6.37.8",
     "socket.io": "^4.8.3",
     "socket.io-client": "^4.8.3",
     "sqlite3": "^6.0.1",
-    "swagger-jsdoc": "^6.2.8",
+    "swagger-jsdoc": "^6.3.0",
     "swagger-ui-express": "^5.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.3.3",
     "typescript": "^5.9.3",
-    "umzug": "^3.8.2",
-    "vite": "^8.0.2",
-    "zustand": "^5.0.12"
+    "umzug": "^3.8.3",
+    "vite": "^8.1.5",
+    "zustand": "^5.0.14"
   },
   "optionalDependencies": {
     "@socket.io/redis-adapter": "^8.3.0",
-    "ioredis": "^5.6.1"
+    "ioredis": "^5.11.1"
   },
   "overrides": {
     "ajv": "^8.17.1",

package/plugin/skills/build/SKILL.md

@@ -35,9 +35,13 @@ Use this skill to take a user from zero to a running Zyket application, or to ex
    ```
    This copies the template, merges its `.env.example` onto sensible defaults, writes `package.json` with the right dependencies, and installs them.
 
-3. **If the template uses auth** (`src/services/auth` exists), create the tables once:
+3. **If the template uses auth** (`src/services/auth` exists), create the tables. From inside the app (preferred — uses the installed better-auth):
+   ```js
+   kernel.boot().then(() => kernel.container.get('auth').migrate());
+   ```
+   Or with the CLI, which needs `--config` because it never scans `src/services/`:
    ```bash
-   npx @better-auth/cli migrate
+   npx @better-auth/cli migrate --config src/services/auth/auth.js
    ```
 
 4. **Run:** `node index.js`. The API is on `PORT` (3000); a frontend, if any, on `VITE_PORT` (5173).
@@ -61,7 +65,7 @@ Flip the env flag, then add the component. Confirm details in `AGENTS.md §3–4
 
 1. Register the auth service in `index.js`: `["auth", require("./src/services/auth"), ["@service_container"]]`.
 2. Subclass `AuthService` (see `AGENTS.md §6`) to set `organizationEnabled`, `requireEmailVerification`, email senders, etc.
-3. Require `DATABASE_DIALECT` = `sqlite` or `postgresql`; run `npx @better-auth/cli migrate`.
+3. Require `DATABASE_DIALECT` = `sqlite` or `postgresql`; create/update the tables with `await container.get('auth').migrate()` (see `AGENTS.md §6`) or the CLI with `--config src/services/auth/auth.js`. Re-run it after adding a plugin or an additional field.
 4. Protect routes with `new RequireAuthMiddleware()` (or `['admin']` / `RequireAdminMiddleware`) and sockets with the `AuthGuard` (`module.exports = require('zyket').AuthGuard` in `src/guards/auth.js`; enforce connect-time auth inside `src/handlers/connection.js` via `container.get('auth').getSession(socket.handshake.headers)`).
 
 ### D. Building a feature (recipe)
@@ -79,7 +83,9 @@ Delegate individual component scaffolding to the **`generate`** skill (e.g. `/zy
 - **PATCH routes don't dispatch** — only `get/post/put/delete` methods are wired.
 - **Connection guards don't block** — do connect-time auth inside `connection.js` (throw to disconnect).
 - **`bullmq`/`scheduler`/`events` default ON when the `DISABLE_*` var is absent**, but the generated `.env` ships them as `true`. Set them to `false` explicitly to enable.
-- **Auth fails to boot** if `AUTH_SECRET` is missing or a known placeholder — let the framework generate it.
+- **Auth fails to boot** if `AUTH_SECRET` is missing or a known placeholder — let the framework generate it (it lands in `.env` when the file is created).
+- **`better-auth migrate` says "No configuration file found"** — the CLI only auto-discovers `auth.js` under `src/{auth,lib,server,utils}/`, never under `src/services/`. Always pass `--config src/services/auth/auth.js`, or call `container.get('auth').migrate()` instead.
+- **No `session`/`verification` table after migrating** — expected: `secondaryStorage` is wired to the `cache`, so better-auth keeps them there. With the default in-memory cache, sessions die on restart; set `CACHE_URL=redis://…` in production.
 - **Frontend can't resolve `vite`/`react`/`better-auth`** — the project (not just zyket) must declare those deps; `npx zyket init` does this automatically for templates with a frontend.
 - **Boot crashes with `Cannot read properties of undefined (reading 'BarBarToken')`** — a TypeScript 7 got hoisted into the tree, which `node-dependency-injection`'s bundled `typescript-estree@5` can't read. Zyket pins `typescript` to `^5` and `npx zyket init` writes a matching `overrides` block; on a project predating that, add `"overrides": { "typescript": "^5.9.3" }` to `package.json` and reinstall.
 

package/src/kernel/HTTPServer.js

@@ -19,6 +19,18 @@ module.exports = class HTTPServer {
     }
     console.log(`HTTP Server listening on port ${this.#port}`)
 
+    // The socket accepts connections from this point on, but Express only
+    // attaches its request listener once its service boots. Without a
+    // placeholder, anything arriving in between (health checks, an eager
+    // client) would be accepted and then never answered — the request hangs
+    // forever and the socket leaks. Answer 503 until Express takes over; it
+    // replaces this listener when it boots. With DISABLE_EXPRESS=true the
+    // placeholder stays, which is also the honest answer.
+    this.#server.on('request', (request, response) => {
+      response.writeHead(503, { 'Content-Type': 'application/json', 'Retry-After': '1' })
+      response.end(JSON.stringify({ success: false, message: 'Server is starting' }))
+    })
+
     this.#server.listen(this.#port, () => {})
   }
 

package/src/services/auth/index.js

@@ -8,6 +8,7 @@ const crypto = require("crypto");
 
 module.exports = class AuthService extends Service {
   #container;
+  #authOptions;
   client;
 
   constructor(container) {
@@ -131,7 +132,77 @@ module.exports = class AuthService extends Service {
     throw new Error("allowUserToCreateOrganization method not implemented");
   }
 
+  // Run the better-auth migrations that are still pending: create missing
+  // tables and add missing columns. Same work as
+  // `npx @better-auth/cli migrate --config src/services/auth/auth.js`, but from
+  // inside the app — so adding a plugin (two-factor, jwt, …) or a new
+  // additional field only needs `await container.get('auth').migrate()`.
+  //
+  // Pass `{ dryRun: true }` to get the SQL back without touching the database.
+  // Returns { pending, tablesCreated, fieldsAdded, sql } so callers can log,
+  // assert, or refuse to boot on a dirty schema.
+  async migrate({ dryRun = false } = {}) {
+    if (!['postgresql', 'sqlite'].includes(process.env.DATABASE_DIALECT)) {
+      throw new Error('AuthService.migrate() only supports PostgreSQL and SQLite as database dialects');
+    }
+
+    const logger = this.#logger();
+    // ESM-only subpath; import() keeps this working regardless of Node's
+    // require(esm) support.
+    const { getMigrations } = await import('better-auth/db/migration');
+    const { toBeCreated, toBeAdded, runMigrations, compileMigrations } = await getMigrations(this.authOptions);
+
+    const tablesCreated = toBeCreated.map((table) => table.table);
+    const fieldsAdded = toBeAdded.flatMap(
+      (table) => Object.keys(table.fields).map((field) => `${table.table}.${field}`)
+    );
+    const pending = tablesCreated.length + fieldsAdded.length;
+
+    if (pending === 0) {
+      logger.info('Auth schema is up to date, nothing to migrate');
+      return { pending: 0, tablesCreated: [], fieldsAdded: [], sql: dryRun ? '' : undefined };
+    }
+
+    const summary = [
+      tablesCreated.length ? `tables: ${tablesCreated.join(', ')}` : null,
+      fieldsAdded.length ? `fields: ${fieldsAdded.join(', ')}` : null,
+    ].filter(Boolean).join(' | ');
+
+    if (dryRun) {
+      const sql = await compileMigrations();
+      logger.info(`Auth migrations pending (dry run, nothing applied) — ${summary}`);
+      return { pending, tablesCreated, fieldsAdded, sql };
+    }
+
+    await runMigrations();
+    logger.info(`Auth migrations applied — ${summary}`);
+    return { pending, tablesCreated, fieldsAdded };
+  }
+
+  // The logger is unavailable when the service is built outside a booted
+  // kernel (e.g. the better-auth CLI loading src/services/auth/auth.js), and
+  // the DI container throws on unknown services rather than returning null.
+  #logger() {
+    try {
+      return this.#container?.get('logger') || console;
+    } catch {
+      return console;
+    }
+  }
+
+  // Built once and reused: every access to `auth` would otherwise open another
+  // SQLite handle / pg Pool. `migrate()` needs the very same options object,
+  // since that is what defines the expected schema.
+  get authOptions() {
+    if (!this.#authOptions) this.#authOptions = this.#buildAuthOptions();
+    return this.#authOptions;
+  }
+
   get auth() {
+    return betterAuth(this.authOptions);
+  }
+
+  #buildAuthOptions() {
     const cache = this.#container.get('cache');
 
     // Environment-aware cookie security:
@@ -144,7 +215,7 @@ module.exports = class AuthService extends Service {
     const cookieSameSite = crossDomain ? 'none' : 'lax';
     const cookieSecure = crossDomain || isProduction;
 
-    return betterAuth({
+    return {
       hooks: this.hooks,
       plugins: [
         admin(),
@@ -215,10 +286,6 @@ module.exports = class AuthService extends Service {
       baseURL: process.env.BETTER_AUTH_URL || 'http://localhost:3000',
       secret: this.#requireAuthSecret(),
       trustedOrigins: process.env.TRUSTED_ORIGINS?.split(',') || ['http://localhost:5173', 'http://localhost:6632']
-    })
-  }
-
-  get client() {
-    return this.client;
+    };
   }
 }

package/src/services/express/Express.js

@@ -111,7 +111,9 @@ module.exports = class Express extends Service {
         }
     });
 
-    // Attach Express to HTTP server - this allows dynamic route registration
+    // Attach Express to the HTTP server, replacing the kernel's "still
+    // booting" placeholder. This happens exactly once: the Express router is
+    // mutable, so routes registered later need no re-attachment.
     this.#httpServer.removeAllListeners("request");
     this.#httpServer.on("request", this.#app);
 
@@ -166,16 +168,13 @@ module.exports = class Express extends Service {
           });
       }
     }
-    
-    this.#httpServer.removeAllListeners("request");
-    this.#httpServer.on("request", this.#app);
+    // No re-attachment: the app is already the server's request listener and
+    // its router picks up these routes immediately. Re-attaching would wipe
+    // engine.io's wrapper and kill the socket.io polling transport.
   }
 
   async regiterRawAllRoutes(path, handler) {
     this.#app.all(path, handler);
-
-    this.#httpServer.removeAllListeners("request");
-    this.#httpServer.on("request", this.#app);
   }
 
   async #loadCorsOrCreateDefault() {

package/src/services/index.js

@@ -25,7 +25,12 @@ module.exports = [
   s3Activated ? ["s3", S3, ["@service_container", process.env.S3_ENDPOINT, process.env.S3_PORT, process.env.S3_USE_SSL === "true", process.env.S3_ACCESS_KEY, process.env.S3_SECRET_KEY, process.env.S3_PUBLIC_BUCKETS, process.env.S3_PRIVATE_BUCKETS]] : null,
   schedulerActivated ? ["scheduler", Scheduler, ["@service_container"]] : null,
   bullmqActivated ? ["bullmq", require("./bullmq"), ["@service_container"]] : null,
+  // Express must boot BEFORE socketio: engine.io's attach() wraps whatever
+  // "request" listener is already on the HTTP server and delegates non-socket
+  // requests to it. Booting it the other way round means Express replaces
+  // engine.io's listener and the polling transport (the default first hop for
+  // every socket.io client) breaks with "xhr poll error".
+  expressActivated ? ["express", Express, ["@service_container"]] : null,
   socketActivated ? ["socketio", SocketIO, ["@service_container"]] : null,
   viteActivated ? ["vite", require("./vite"), ["@service_container", process.env.VITE_ROOT, Number(process.env.VITE_PORT) || 5173]] : null,
-  expressActivated ? ["express", Express, ["@service_container"]] : null,
 ].filter(Boolean);

package/src/templates/api-rest/README.md

@@ -23,12 +23,25 @@ Auth endpoints are mounted by better-auth under `/api/auth/*`.
 ## Setup
 ```bash
 npm install
-# 1) Create the better-auth tables (uses src/services/auth/auth.js)
-npx @better-auth/cli migrate
+# 1) Create the better-auth tables
+npx @better-auth/cli migrate --config src/services/auth/auth.js
 # 2) Run
 node index.js
 ```
 
+Instead of the CLI you can migrate from inside the app — it uses the
+better-auth version this project actually installs:
+
+```js
+kernel.boot().then(() => kernel.container.get('auth').migrate());
+```
+
+Re-run it after adding a better-auth plugin or an `additionalFields` entry.
+There is no `session`/`verification` table: `secondaryStorage` is wired to the
+cache service, so better-auth keeps those there (set `CACHE_URL=redis://…` if
+sessions must survive a restart).
+
+
 The `Task` table is created automatically via `sequelize.sync()` on boot.
 
 ## Auth quick test

package/src/templates/api-rest/index.js

@@ -9,8 +9,8 @@ const kernel = new Kernel({
 });
 
 kernel.boot().then(async () => {
-  // Create the example tables (Task). better-auth tables are created via the
-  // better-auth CLI migrate step (see README).
+  // Create the example tables (Task). The better-auth tables come from
+  // `container.get('auth').migrate()` or the better-auth CLI (see README).
   await kernel.container.get('database').sync();
   kernel.container.get('logger').info('api-rest template ready — try GET /tasks');
 }).catch((error) => {

package/src/templates/api-rest/src/services/auth/auth.js

@@ -1,5 +1,6 @@
-// Used by the better-auth CLI (`npx @better-auth/cli generate|migrate`) to
-// discover your auth configuration.
+// Your auth configuration for the better-auth CLI. The CLI does not scan
+// src/services/, so point it here explicitly:
+//   npx @better-auth/cli generate|migrate --config src/services/auth/auth.js
 const AuthService = require('./index.js');
 
 const auth = new AuthService({

package/src/templates/realtime-chat/README.md

@@ -14,9 +14,22 @@ connect or send messages.
 ## Setup
 ```bash
 npm install
-npx @better-auth/cli migrate
+npx @better-auth/cli migrate --config src/services/auth/auth.js
 node index.js
 ```
+
+Instead of the CLI you can migrate from inside the app — it uses the
+better-auth version this project actually installs:
+
+```js
+kernel.boot().then(() => kernel.container.get('auth').migrate());
+```
+
+Re-run it after adding a better-auth plugin or an `additionalFields` entry.
+There is no `session`/`verification` table: `secondaryStorage` is wired to the
+cache service, so better-auth keeps those there (set `CACHE_URL=redis://…` if
+sessions must survive a restart).
+
 This starts the API + websocket server on `:3000` and the Vite frontend on `:5173`.
 Open http://localhost:5173, register a user, and start chatting (open two
 browsers/users to see real-time delivery).

package/src/templates/realtime-chat/src/services/auth/auth.js

@@ -1,4 +1,6 @@
-// Used by the better-auth CLI (`npx @better-auth/cli generate|migrate`).
+// Your auth configuration for the better-auth CLI. The CLI does not scan
+// src/services/, so point it here explicitly:
+//   npx @better-auth/cli generate|migrate --config src/services/auth/auth.js
 const AuthService = require('./index.js');
 
 const auth = new AuthService({

package/src/templates/saas-multitenant/README.md

@@ -26,9 +26,22 @@ routes, not on re-implementing what better-auth already exposes.
 ## Setup
 ```bash
 npm install
-npx @better-auth/cli migrate   # creates user/session/organization/member tables
+npx @better-auth/cli migrate --config src/services/auth/auth.js   # creates the user/account/organization/member tables
 node index.js
 ```
+
+Instead of the CLI you can migrate from inside the app — it uses the
+better-auth version this project actually installs:
+
+```js
+kernel.boot().then(() => kernel.container.get('auth').migrate());
+```
+
+Re-run it after adding a better-auth plugin or an `additionalFields` entry.
+There is no `session`/`verification` table: `secondaryStorage` is wired to the
+cache service, so better-auth keeps those there (set `CACHE_URL=redis://…` if
+sessions must survive a restart).
+
 This starts the API on `:3000` and the Vite dashboard on `:5173`. Open
 http://localhost:5173, sign up, create an organization, set it active, and add
 projects (scoped to that organization).

package/src/templates/saas-multitenant/src/services/auth/auth.js

@@ -1,4 +1,6 @@
-// Used by the better-auth CLI (`npx @better-auth/cli generate|migrate`).
+// Your auth configuration for the better-auth CLI. The CLI does not scan
+// src/services/, so point it here explicitly:
+//   npx @better-auth/cli generate|migrate --config src/services/auth/auth.js
 const AuthService = require('./index.js');
 
 const auth = new AuthService({

package/src/utils/EnvManager.js

@@ -1,4 +1,5 @@
 const fs = require('fs');
+const crypto = require('crypto');
 
 module.exports = class EnvManager {
   static load(secretsPath) {
@@ -43,6 +44,10 @@ module.exports = class EnvManager {
       VITE_ROOT: './frontend',
       VITE_PORT: 5173,
       DISABLE_VITE: true,
+      // Generated here, not on first boot: the better-auth CLI reads .env when
+      // it loads your auth config, so `migrate` has to work before the app has
+      // ever run. A per-project random value, never a shared placeholder.
+      AUTH_SECRET: crypto.randomBytes(32).toString('hex'),
     }
 
     return header + Object.entries(envsToCreate).reduce((acc, [key, value]) => {