zyket 1.2.21 → 1.2.22

package/AGENTS.md

@@ -291,7 +291,29 @@ module.exports = class CustomAuthService extends AuthService {
 };
 ```
 
-Requirements: `DATABASE_DIALECT` must be `sqlite` or `postgresql`. Run `npx @better-auth/cli migrate --config src/services/auth/auth.js` to create the auth tables. The `--config` flag is required: the CLI only auto-discovers `auth.js` under `src/{auth,lib,server,utils}/`, never under `src/services/`.
+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
 

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 --config src/services/auth/auth.js   # 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.21",
+  "version": "1.2.22",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

package/plugin/skills/build/SKILL.md

@@ -35,7 +35,11 @@ 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 --config src/services/auth/auth.js
    ```
@@ -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 --config src/services/auth/auth.js`.
+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)
@@ -80,7 +84,8 @@ Delegate individual component scaffolding to the **`generate`** skill (e.g. `/zy
 - **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 (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`.
+- **`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/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/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)
+# 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/realtime-chat/README.md

@@ -17,6 +17,19 @@ npm install
 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/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 --config src/services/auth/auth.js   # 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).