zyket 1.2.20 → 1.2.21

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,7 @@ 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`. 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/`.
 
 ### Protecting routes & sockets
 
@@ -402,6 +402,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,7 @@ 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('  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.21",
   "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

@@ -37,7 +37,7 @@ Use this skill to take a user from zero to a running Zyket application, or to ex
 
 3. **If the template uses auth** (`src/services/auth` exists), create the tables once:
    ```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 +61,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`; run `npx @better-auth/cli migrate --config src/services/auth/auth.js`.
 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 +79,8 @@ 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`.
 - **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/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

@@ -24,7 +24,7 @@ Auth endpoints are mounted by better-auth under `/api/auth/*`.
 ```bash
 npm install
 # 1) Create the better-auth tables (uses src/services/auth/auth.js)
-npx @better-auth/cli migrate
+npx @better-auth/cli migrate --config src/services/auth/auth.js
 # 2) Run
 node index.js
 ```

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,7 +14,7 @@ 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
 ```
 This starts the API + websocket server on `:3000` and the Vite frontend on `:5173`.

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,7 +26,7 @@ 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 user/session/organization/member tables
 node index.js
 ```
 This starts the API on `:3000` and the Vite dashboard on `:5173`. Open

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]) => {