zyket 1.2.19 → 1.2.21

package/.claude-plugin/marketplace.json

@@ -10,8 +10,8 @@
     {
       "name": "zyket",
       "source": "./plugin",
-      "description": "Generate Zyket framework components — handlers, guards, routes, middlewares, services, events, schedulers, workers, and extensions.",
-      "version": "1.0.0"
+      "description": "Build and scaffold Zyket apps — initialize from templates, wire services/auth/security (build), and generate components like routes, handlers, guards, services, and workers (generate).",
+      "version": "1.1.0"
     }
   ]
 }

package/AGENTS.md

@@ -0,0 +1,407 @@
+# AGENTS.md — Zyket Framework Reference
+
+> A complete, accurate reference for AI agents building applications with **Zyket**.
+> Zyket is a service-oriented Node.js framework (Express 5 + Socket.IO + better-auth + Sequelize/BullMQ/MinIO) inspired by Symfony's architecture. Components are auto-discovered from the filesystem; services are wired through a dependency-injection container.
+
+This document is the source of truth. When an installed copy exists, read `node_modules/zyket/AGENTS.md`. Always confirm a base class API against the installed source before relying on it.
+
+---
+
+## 1. Quick start
+
+```bash
+mkdir my-app && cd my-app
+npm install zyket
+npx zyket init                 # interactive: pick a template
+# or non-interactive:
+npx zyket init api-rest        # default | api-rest | saas-multitenant | realtime-chat
+```
+
+`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 --config src/services/auth/auth.js
+node index.js
+```
+
+Minimal manual boot:
+
+```js
+// index.js
+const { Kernel } = require("zyket");
+
+const kernel = new Kernel({
+  services: [
+    ["auth", require("./src/services/auth"), ["@service_container"]],
+  ],
+});
+
+kernel.boot().then(() => console.log("Booted")).catch(console.error);
+```
+
+---
+
+## 2. The Kernel
+
+```js
+new Kernel({ services: [], extensions: [] })
+kernel.boot(clearConsole = true, secretsPath = "<cwd>/.env")
+```
+
+Boot order:
+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. `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')`).
+
+**Service registration tuple:** `[name, ClassOrFactory, args]`. Special arg placeholders:
+
+| Placeholder | Injected value |
+|-------------|----------------|
+| `"@service_container"` | the DI container |
+| `"@onConnection"` | the kernel's socket-connection callback |
+
+Auth is **not** a core service — register it yourself (templates do).
+
+---
+
+## 3. Environment variables
+
+The generated `.env` (`src/utils/EnvManager.js`) plus auth/vite variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `DEBUG` | `true` | Enable debug-level logs |
+| `PORT` | `3000` | HTTP/WS port |
+| `NODE_ENV` | — | `production` enables secure cookies, Vite preview build |
+| `HTTP_JSON_LIMIT` | `10mb` | Express JSON body limit |
+| `SOCKET_MAX_HTTP_BUFFER_SIZE` | `10485760` | Socket.IO max payload bytes |
+| `DISABLE_EXPRESS` | `false` | Turn off the HTTP/REST service |
+| `DISABLE_SOCKET` | `true` | Turn off Socket.IO |
+| `DISABLE_VITE` | `true` | Turn off the Vite frontend |
+| `DISABLE_EVENTS` | `true` | Turn off the events service |
+| `DISABLE_BULLMQ` | `true` | Turn off BullMQ queues/workers |
+| `DISABLE_SCHEDULER` | `true` | Turn off the cron scheduler |
+| `DISABLE_LOGGER` | `false` | Silence the logger |
+| `DISABLE_SWAGGER` | — | `true` removes the `/docs` UI |
+| `SWAGGER_PASSWORD` / `SWAGGER_USER` | — / `admin` | HTTP Basic auth for `/docs` |
+| `SWAGGER_PATH` | `/docs` | Swagger UI mount path |
+| `DATABASE_URL` | `./database.sqlite` | DB connection / sqlite path. Activates the `database` service when set |
+| `DATABASE_DIALECT` | `sqlite` | `sqlite`, `postgresql`, `mariadb`… (auth supports only `sqlite`/`postgresql`) |
+| `CACHE_URL` | `` | `redis://…` for Redis, empty/`memory` for in-memory |
+| `REDIS_URL` | — | Enables the Socket.IO Redis adapter (multi-instance) |
+| `S3_ENDPOINT` `S3_PORT` `S3_USE_SSL` `S3_ACCESS_KEY` `S3_SECRET_KEY` | — | MinIO/S3. The `s3` service activates when endpoint+keys are set |
+| `S3_PUBLIC_BUCKETS` / `S3_PRIVATE_BUCKETS` | — | Comma lists; public buckets get a read-all policy |
+| `LOG_DIRECTORY` | `./logs` | Log file directory |
+| `QUEUES` | `` | Comma list of BullMQ queue names to create |
+| `VITE_ROOT` | `./frontend` | Frontend project root |
+| `VITE_PORT` | `5173` | Vite dev/preview port |
+| `VITE_API_BASE` | `http://localhost:3000` | Frontend → backend base URL |
+| **Auth** (added by the auth service) | | |
+| `AUTH_SECRET` | random 32-byte hex | Session signing secret. **Boot fails if missing/insecure** |
+| `BETTER_AUTH_URL` | `http://localhost:3000` | Public base URL of the auth server |
+| `TRUSTED_ORIGINS` | `http://localhost:5173,http://localhost:3000` | Comma list of allowed origins (CORS + CSRF) |
+| `AUTH_CROSS_DOMAIN` | `false` | `true` → cross-site cookies (`sameSite=none; secure`, needs HTTPS) |
+| `BULLBOARD_ADMIN_PASSWORD` | — | Required to expose the BullBoard dashboard extension |
+
+---
+
+## 4. Services
+
+Core services are auto-registered based on env (`src/services/index.js`). Access any with `container.get('<name>')`.
+
+| Name | Activated when | Key API |
+|------|----------------|---------|
+| `logger` | always (silent if `DISABLE_LOGGER=true`) | `info/warn/error/debug(msg)` |
+| `template-manager` | always | internal (templates) |
+| `events` | `DISABLE_EVENTS !== 'true'` | `emit(name, payload)`, `emitAsync(name, payload, timeout)` |
+| `database` | `DATABASE_URL` set | `models`, `sequelize`, `Op`, `Sequelize`, `sync()`, `runMigrations(path)`, `loadModel(fn)` |
+| `cache` | always | `get/set/del/keys/expire`, `client` (redis or null) |
+| `s3` | `S3_ENDPOINT` + access + secret | `saveFile/getFile/removeFile/ensureBucket/listBuckets`, `client` (MinIO) |
+| `scheduler` | `DISABLE_SCHEDULER !== 'true'` | discovers `src/schedulers/*` |
+| `bullmq` | `DISABLE_BULLMQ !== 'true'` | `queues`, `addJob(queue, name, data, opts, waitForCompletion)` |
+| `socketio` | `DISABLE_SOCKET !== 'true'` | `io`, `sockets` |
+| `vite` | `VITE_ROOT` set + `DISABLE_VITE !== 'true'` | serves `frontend/` |
+| `express` | `DISABLE_EXPRESS !== 'true'` | `app()`, `registerRoutes(routes)`, `regiterRawAllRoutes(path, handler)` |
+| `auth` | **manual registration** | `client` (better-auth), `getSession(headers)` |
+
+> Note: `bullmq`, `scheduler`, `events` default to ON when their `DISABLE_*` var is absent, but the generated `.env` ships them as `true` (off). Set the relevant `DISABLE_*=false` to enable.
+
+### Custom service
+
+```js
+const { Service } = require("zyket");
+
+module.exports = class MyService extends Service {
+  #container;
+  constructor(container) { super("my-service"); this.#container = container; }
+  async boot({ httpServer } = {}) { /* init */ }
+  doThing() { /* ... */ }
+};
+```
+
+Register: `services: [["my-service", MyService, ["@service_container"]]]`.
+
+---
+
+## 5. Auto-discovered components
+
+These are discovered from folders under `src/` — the **filename is the identity**. Use kebab-case, `module.exports = class extends Base`, and do not add constructor params (the loader passes only the derived name).
+
+| Component | Folder | Base | Identity from filename |
+|-----------|--------|------|------------------------|
+| Route | `src/routes/` | `Route` | URL path |
+| Middleware | `src/middlewares/` | `Middleware` | referenced manually |
+| Handler | `src/handlers/` | `Handler` | socket event name |
+| Guard | `src/guards/` | `Guard` | guard name |
+| Event | `src/events/` | `Event` | event name |
+| Scheduler | `src/schedulers/` | `Schedule` | label |
+| Worker | `src/workers/` | `Worker` | label |
+| Model | `src/models/` | factory fn | model name |
+
+### Routes (`src/routes/**.js`)
+
+File path → URL: `index.js`→`/`, `users.js`→`/users`, `users/[id].js`→`/users/:id`. Methods: **`get`, `post`, `put`, `delete`** (PATCH is not dispatched).
+
+```js
+const { Route, RequireAuthMiddleware } = require("zyket");
+
+module.exports = class extends Route {
+  middlewares = { post: [new RequireAuthMiddleware()] }; // per-method
+
+  async get({ container, request, response }) {
+    return { items: [] };                 // → { success: true, items: [] }
+  }
+  async post({ container, request }) {
+    if (!request.body.name) return { success: false, message: "name required", status: 400 };
+    return { created: true, status: 201 };
+  }
+};
+```
+
+Return conventions: object → `{ success: true, ...obj }` JSON; `status` key sets HTTP code; `Buffer` → file download; `new RedirectResponse(url)` → redirect. Thrown errors → `500 { success:false, message:"Internal Server Error" }` (details only in logs).
+
+### Middlewares (`src/middlewares/*.js`)
+
+```js
+const { Middleware } = require("zyket");
+module.exports = class extends Middleware {
+  async handle({ container, request, response, next }) {
+    // respond to block, or call next() to continue
+    next();
+  }
+};
+```
+
+### Socket.IO handlers (`src/handlers/*.js`) & guards (`src/guards/*.js`)
+
+```js
+// src/handlers/message.js  → listens to the "message" event
+const { Handler } = require("zyket");
+module.exports = class extends Handler {
+  guards = ["auth"];                       // run before handle; throw to block
+  async handle({ container, socket, data, io }) {
+    io.to("room").emit("message", data);
+    return { ok: true };                   // returned to the client ack callback
+  }
+};
+```
+
+```js
+// src/guards/auth.js
+const { Guard } = require("zyket");
+module.exports = class extends Guard {
+  async handle({ container, socket, io }) {
+    if (!ok) throw new Error("Unauthorized"); // blocks the event
+  }
+};
+```
+
+> `connection.js` is special (runs on connect). **Connection-level guards are not awaited and do not reliably block** — enforce connect-time auth inside `connection.js` itself (throwing there disconnects the socket).
+
+### Events (`src/events/*.js`)
+
+```js
+const { Event } = require("zyket");
+module.exports = class extends Event {
+  async handle({ container, payload }) { /* ... */ }
+};
+// elsewhere: container.get('events').emit('user-registered', { id })
+```
+
+### Scheduler (`src/schedulers/*.js`)
+
+```js
+const { Schedule } = require("zyket");
+module.exports = class extends Schedule {
+  time = "*/5 * * * *";                    // node-cron expression
+  async handle({ container }) { /* ... */ }
+};
+```
+
+### Worker (`src/workers/*.js`) — BullMQ
+
+```js
+const { Worker } = require("zyket");
+module.exports = class extends Worker {
+  queueName = "emails";                    // must match a name in QUEUES
+  instances = 1;                           // number | array | async fn
+  options = { concurrency: 5 };            // BullMQ worker options | fn
+  async handle({ container, job, instance, index }) { /* process job.data */ }
+};
+// enqueue: container.get('bullmq').addJob('emails', 'welcome', { to })
+```
+
+### Model (`src/models/*.js`) — Sequelize factory
+
+```js
+module.exports = ({ sequelize, Sequelize, container }) => {
+  const User = sequelize.define("User", {
+    email: { type: Sequelize.STRING, allowNull: false },
+  });
+  User.associate = (models) => { /* User.hasMany(models.Post) */ };
+  return User;
+};
+// access: container.get('database').models.User ; create tables: .sync()
+```
+
+---
+
+## 6. Authentication (better-auth)
+
+The `auth` service mounts better-auth at `/api/auth/*` and provides sessions, the **admin** plugin, the **bearer** plugin, and (optionally) the **organization** plugin. Customize by subclassing `AuthService`:
+
+```js
+const { AuthService } = require("zyket");
+
+module.exports = class CustomAuthService extends AuthService {
+  get organizationEnabled() { return true; }        // multi-tenant
+  get requireEmailVerification() { return false; }
+  get plugins() { return []; }                       // extra better-auth plugins
+  get socialProviders() { return {}; }
+  get userAdditionalFields() { return {}; }
+  get organizationAdditionalFields() { return {}; }
+  async allowUserToCreateOrganization(user) { return true; }
+  async sendVerificationEmail({ user, url, token }) { /* email */ }
+  async sendResetPasswordEmail({ user, url, token }) { /* email */ }
+  async sendInvitationEmail(data) { /* org invite */ }
+};
+```
+
+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
+
+| Helper | Use |
+|--------|-----|
+| `RequireAuthMiddleware` | route middleware; requires a session. `new RequireAuthMiddleware(['admin'])` to gate by role. Sets `request.user` / `request.session` |
+| `RequireAdminMiddleware` | route middleware; requires `role === 'admin'` |
+| `AuthGuard` | socket guard; rejects events without a session. Use `module.exports = require('zyket').AuthGuard` in `src/guards/auth.js` |
+| `container.get('auth').getSession(headers)` | resolve a session from raw headers (e.g. `socket.handshake.headers`) without importing better-auth |
+
+### Cookies (environment-aware)
+
+Default: `sameSite=lax`, `secure` only in production → works over `http://localhost` when frontend (`:5173`) and API (`:3000`) are same-site. For front/back on **different domains**, set `AUTH_CROSS_DOMAIN=true` (HTTPS required) → `sameSite=none; secure` + cross-subdomain cookies.
+
+### Frontend auth client
+
+```js
+import { createAuthClient } from "better-auth/react";
+import { organizationClient, adminClient } from "better-auth/client/plugins";
+
+export const client = createAuthClient({
+  baseURL: `${import.meta.env.VITE_API_BASE || "http://localhost:3000"}/api/auth/`,
+  plugins: [organizationClient(), adminClient()],
+});
+```
+
+---
+
+## 7. Extensions
+
+Post-boot plugins with full container access. Register instances in the Kernel.
+
+```js
+const { Kernel, BullBoardExtension, InteractiveStorageExtension } = require("zyket");
+
+new Kernel({
+  extensions: [
+    new BullBoardExtension({ path: "/bullboard", middlewares: [] }),        // needs BULLBOARD_ADMIN_PASSWORD or middlewares, else it won't mount
+    new InteractiveStorageExtension({ path: "/storage", bucketName: "dropbox", middlewares: [/* auth */], maxDeleteBatch: 100 }),
+  ],
+});
+```
+
+Custom extension:
+
+```js
+const { Extension } = require("zyket");
+module.exports = class extends Extension {
+  constructor(options = {}) { super("MyExtension"); this.options = options; }
+  async load(container) {
+    if (!container.get("express")) return container.get("logger").warn("no express");
+    container.get("express").registerRoutes([/* Route instances */]);
+  }
+};
+```
+
+---
+
+## 8. Frontend (Vite + React)
+
+When `VITE_ROOT` is set and `DISABLE_VITE=false`, Zyket runs Vite (dev server, or a built preview server in production) for the `frontend/` app. Stack: React 19 + react-router-dom + zustand + Tailwind v4 + better-auth client. The frontend talks to the backend at `VITE_API_BASE`. A project with a frontend must declare its own frontend dependencies (the CLI does this automatically per template).
+
+---
+
+## 9. Templates
+
+| Template | Stack | Use for |
+|----------|-------|---------|
+| `default` | backend + (optional) React frontend | general starter |
+| `api-rest` | backend only, auth + CRUD (`Task`) | clean REST APIs |
+| `saas-multitenant` | orgs/roles + React dashboard, tenant-scoped `Project` | multi-tenant SaaS |
+| `realtime-chat` | Socket.IO + React chat UI, session auth | real-time apps |
+
+Each template is self-contained (`index.js`, `.env.example`, `README.md`, and frontend where relevant). `npx zyket init <template>` scaffolds it.
+
+---
+
+## 10. CLI
+
+```bash
+npx zyket                       # interactive menu
+npx zyket init                  # choose a template, scaffold + install + (default) run
+npx zyket init <template>       # scaffold a specific template
+```
+
+`init` keeps existing files (non-destructive). For non-default templates it prints next steps (auth migrate + run) instead of auto-starting.
+
+---
+
+## 11. Security checklist
+
+See `SECURITY.md` for the full audit. Essentials before production:
+
+- Keep `.env` out of git; never reuse `AUTH_SECRET` (it's generated per project; boot fails on a known/empty value).
+- Protect every non-public route/socket with `RequireAuthMiddleware` / `AuthGuard`.
+- Set `BULLBOARD_ADMIN_PASSWORD` (or pass `middlewares`) — the dashboard won't mount without auth.
+- Set `SWAGGER_PASSWORD` (or `DISABLE_SWAGGER=true`) in production.
+- Lock `TRUSTED_ORIGINS`; set `AUTH_CROSS_DOMAIN=true` only for real cross-domain HTTPS deployments.
+- Add rate limiting and `helmet` (not bundled).
+- For the storage extension, always pass auth `middlewares`; tune `maxFileSize` / `maxDeleteBatch`.
+
+---
+
+## 12. Build-a-feature recipe
+
+1. **Model** — `src/models/Thing.js` (Sequelize factory). Create tables with `container.get('database').sync()` in `index.js` after boot, or migrations.
+2. **Routes** — `src/routes/things/index.js` (GET list, POST create) and `src/routes/things/[id].js` (GET/PUT/DELETE). Gate with `new RequireAuthMiddleware()`.
+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 --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

@@ -1,279 +1,175 @@
-# Zyket
-
-Zyket is a Node.js framework designed to simplify the development of real-time applications with Socket.IO and Express. Inspired by the structured approach of frameworks like Symfony, Zyket provides a robust, service-oriented architecture for building scalable and maintainable server-side applications.
-
-Upon initial boot, Zyket automatically scaffolds a default project structure, including handlers, routes, and configuration files, allowing you to get started immediately.
-
-## Getting Started
-
-### Quick Start (Recommended)
-
-The easiest way to get started with Zyket is to use the CLI initialization command:
-
-```bash
-# Create a new directory for your project
-mkdir my-zyket-app
-cd my-zyket-app
-
-# Install zyket
-npm install zyket
-
-# Initialize the project (one command!)
-npx zyket init
-
-# Start your application
-npm run dev
-```
-
-The `init` command will:
-- Create an `index.js` file with the kernel boilerplate
-- Generate a `.env` file with sensible defaults
-- Create a `package.json` if one doesn't exist
-- Set up your project ready to run
-
-You can also run `npx zyket` without arguments for an interactive menu with more options.
-
-### Manual Setup (Alternative)
-
-If you prefer to set up manually, install Zyket in your project:
-
-```bash
-npm i zyket
-```
-
-Then, create an `index.js` file and boot the Zyket Kernel:
-
-```javascript
-// index.js
-const { Kernel } = require("zyket");
-
-// Instantiate the kernel
-const kernel = new Kernel();
-
-// Boot the kernel to start all services
-kernel.boot().then(() => {
-    console.log("Kernel booted successfully!");
-});
-```
-
-When you run this for the first time, Zyket will create a default `.env` file and a `src` directory containing boilerplate for routes, handlers, guards, and middlewares.
-
-## Core Concepts
-
-Zyket is built around a few key architectural concepts:
-
-*   **Socket.IO Handlers & Guards**: For managing real-time WebSocket events and their authorization.
-*   **Express Routes & Middlewares**: For handling traditional RESTful API endpoints.
-*   **Services**: Reusable components that are managed by a dependency injection container.
-*   **CLI**: A command-line tool to scaffold features from templates.
-
-### Socket.IO Development
-
-#### Handlers
-
-Handlers are classes that process incoming Socket.IO events. The name of the handler file (e.g., `message.js`) determines the event it listens to (`message`).
-
-```javascript
-// src/handlers/message.js
-const { Handler } = require("zyket");
-
-module.exports = class MessageHandler extends Handler {
-  // Array of guard names to execute before the handler
-  guards = ["default"];
-
-  async handle({ container, socket, data, io }) {
-    const logger = container.get("logger");
-    logger.info(`Received message: ${JSON.stringify(data)}`);
-    socket.emit("response", { received: data });
-  }
-};
-```
-
-#### Guards
-
-Guards are used to protect Socket.IO handlers or the initial connection. They run before the handler's `handle` method and are ideal for authorization logic.
-
-```javascript
-// src/guards/default.js
-const { Guard } = require("zyket");
-
-module.exports = class DefaultGuard extends Guard {
-  async handle({ container, socket, io }) {
-    container.get("logger").info(`Executing default guard for socket ${socket.id}`);
-    
-    // Example: Check for an auth token. If invalid, disconnect the user.
-    // if (!socket.token) {
-    //   socket.disconnect();
-    // }
-  }
-};
-```
-
-### Express API Development
-
-#### Routes
-
-Routes handle HTTP requests. The file path maps directly to the URL endpoint. For example, `src/routes/index.js` handles requests to `/`, and `src/routes/[test]/message.js` handles requests to `/:test/message`.
-
-```javascript
-// src/routes/index.js
-const { Route } = require("zyket");
-const DefaultMiddleware = require("../middlewares/default");
-
-module.exports = class DefaultRoute extends Route {
-  // Apply middlewares to specific HTTP methods
-  middlewares = {
-    get: [ new DefaultMiddleware() ],
-    post: [ new DefaultMiddleware() ]
-  }
-
-  async get({ container, request }) {
-    container.get("logger").info("Default route GET");
-    return { test: "Hello World GET!" };
-  }
-
-  async post({ container, request }) {
-    container.get("logger").info("Default route POST");
-    return { test: "Hello World POST!" };
-  }
-};
-```
-
-#### Middlewares
-
-Middlewares process the request before it reaches the route handler. They follow the standard Express middleware pattern.
-
-```javascript
-// src/middlewares/default.js
-const { Middleware } = require("zyket");
-
-module.exports = class DefaultMiddleware extends Middleware {
-  async handle({ container, request, response, next }) {
-    container.get("logger").info("Default Express middleware executing");
-    next(); // Pass control to the next middleware or route handler
-  }
-};
-```
-
-## Services
-
-Services are the cornerstone of Zyket's architecture, providing reusable functionality across your application. Zyket includes several default services and allows you to register your own.
-
-### Custom Services
-
-You can create your own services by extending the `Service` class and registering it with the Kernel.
-
-```javascript
-// src/services/MyCustomService.js
-const { Service } = require("zyket");
-
-module.exports = class MyCustomService extends Service {
-    constructor() {
-        super("my-custom-service");
-    }
-
-    async boot() {
-        console.log("MyCustomService has been booted!");
-    }
-
-    doSomething() {
-        return "Something was done.";
-    }
-}
-```
-
-Register the service in your main `index.js` file:
-
-```javascript
-// index.js
-const { Kernel } = require("zyket");
-const MyCustomService = require("./src/services/MyCustomService");
-
-const kernel = new Kernel({
-    services: [
-        // [name, class, [constructor_args]]
-        ["my-service", MyCustomService, []]
-    ]
-});
-
-kernel.boot();
-```
-Services are reusable components specified in the kernel configuration. Each service must include a boot() function that is executed when the kernel starts.
-
-```javascript
-module.exports = class LoggerService {
-    this.#container;
-    
-    boot(container, enableLogging = true) {
-        this.#container = container;
-        console.log("LoggerService Booted");
-    }
-
-    info(message) {
-        if(!enableLogging) return;
-        console.log(`[INFO]: ${message}`);
-    }
-};
-```
-
-Then, when booting the kernel, specify the service:
-
-```javascript
-const { Kernel } = require("zyket");
-const LoggerService = require("./LoggerService");
-
-const kernel = new Kernel({
-    services: [["logger", LoggerService, ['@service_container', true]],
-});
-
-kernel.boot().then(() => console.log(`Kernel Booted`));
-```
-
-## Default Services
-Zyket includes some default services that provide essential functionality. These services can be overridden or extended if needed.
-
-#### Cache Services
-- **Name** `cache`
-- **Description** Provides caching functionality using a Redis adapter.
-- **Configuration** Add `CACHE_URL` in your `.env` file to activate caching.
-
-#### Database Service
-- **Name** `database`
-- **Description** Manages database connections using a MariaDB/Sequelize adapter.
-- **Configuration** Add `DATABASE_URL` in your `.env` file to enable the database connection.
-
-#### S3 Service
-- **Name** `s3`
-- **Description** Provides S3-compatible object storage using MinIO.
-- **Configuration** Add the following variables in your `.env` file to enable the service
-    - `S3_ENDPOINT`
-    - `S3_PORT`
-    - `S3_USE_SSL`
-    - `S3_ACCESS_KEY`
-    - `S3_SECRET_KEY`
-
-#### Logger Service
-- **Name** `logger`
-- **Description** Handles logging for the application.
-- **Configuration**
-    - Change `LOG_DIRECTORY` in `.env` file to set a custom log directory.
-    - Set `DEBUG` in `.env` file to enable or disable debug logging.
-
-#### Socket.io Service
-- **Name** `socketio`
-- **Description** Manages the WebSocket server.
-- **Configuration** Add `PORT` in your `.env` file to define the listening port for Socket.io.
-
-
-## Contributing
-
-We welcome contributions from the community! If you'd like to improve Zyket, feel free to:
-
-- Report issues and suggest features on GitHub Issues
-
-- Submit pull requests with bug fixes or enhancements
-
-- Improve the documentation
-
-Let's build a better framework together! 🚀
-
+# Zyket
+
+Zyket is a service-oriented Node.js framework for building real-time and REST applications with **Express 5**, **Socket.IO**, **better-auth**, and **Sequelize/BullMQ/MinIO**. Inspired by Symfony, it pairs a dependency-injection container with filesystem-based auto-discovery: drop a file in the right folder and the framework wires it up.
+
+> **Building with an AI agent?** See **[AGENTS.md](AGENTS.md)** for a complete, machine-readable reference, and **[SECURITY.md](SECURITY.md)** for hardening guidance.
+
+## Getting started
+
+```bash
+mkdir my-app && cd my-app
+npm install zyket
+
+# Initialize from a template (interactive picker)
+npx zyket init
+# …or pick one directly:
+npx zyket init api-rest      # default | api-rest | saas-multitenant | realtime-chat
+```
+
+`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 --config src/services/auth/auth.js
+node index.js
+```
+
+### Templates
+
+| Template | What you get |
+|----------|--------------|
+| `default` | General starter (backend + optional React frontend) |
+| `api-rest` | Backend-only REST API with auth and a protected CRUD resource |
+| `saas-multitenant` | Multi-tenant SaaS (organizations, roles) + React dashboard |
+| `realtime-chat` | Authenticated real-time chat (Socket.IO) + React UI |
+
+### Manual boot
+
+```js
+// index.js
+const { Kernel } = require("zyket");
+
+const kernel = new Kernel({
+  services: [
+    ["auth", require("./src/services/auth"), ["@service_container"]],
+  ],
+});
+
+kernel.boot().then(() => console.log("Kernel booted!"));
+```
+
+On first run Zyket creates a `.env` and a `src/` directory with boilerplate.
+
+## Core concepts
+
+- **Routes & Middlewares** — REST endpoints via Express, auto-discovered from `src/routes`.
+- **Handlers & Guards** — Socket.IO events and their authorization, from `src/handlers` / `src/guards`.
+- **Services** — reusable units managed by a DI container (`logger`, `database`, `cache`, `s3`, `events`, `scheduler`, `bullmq`, `socketio`, `express`, `auth`).
+- **Extensions** — post-boot plugins (e.g. BullBoard, interactive storage).
+- **Templates & CLI** — scaffold whole projects or individual components.
+
+### Routes
+
+File path maps to the URL: `src/routes/index.js` → `/`, `src/routes/users/[id].js` → `/users/:id`. Methods: `get`, `post`, `put`, `delete`.
+
+```js
+const { Route, RequireAuthMiddleware } = require("zyket");
+
+module.exports = class extends Route {
+  middlewares = { post: [new RequireAuthMiddleware()] };
+
+  async get({ container, request }) {
+    return { items: [] };                       // → { success: true, items: [] }
+  }
+  async post({ container, request }) {
+    if (!request.body.name) return { success: false, message: "name required", status: 400 };
+    return { created: true, status: 201 };
+  }
+};
+```
+
+Return an object (wrapped as `{ success: true, ... }`), set `status` to change the HTTP code, return a `Buffer` for a download, or `new RedirectResponse(url)` to redirect.
+
+### Middlewares
+
+```js
+const { Middleware } = require("zyket");
+
+module.exports = class extends Middleware {
+  async handle({ container, request, response, next }) {
+    next(); // respond to block, or next() to continue
+  }
+};
+```
+
+### Socket.IO handlers & guards
+
+```js
+// src/handlers/message.js  → "message" event
+const { Handler } = require("zyket");
+
+module.exports = class extends Handler {
+  guards = ["auth"];
+  async handle({ container, socket, data, io }) {
+    io.emit("message", data);
+    return { ok: true };
+  }
+};
+```
+
+```js
+// src/guards/auth.js — reuse the built-in session guard
+module.exports = require("zyket").AuthGuard;
+```
+
+## Authentication
+
+Zyket ships first-class auth via [better-auth](https://better-auth.com) mounted at `/api/auth/*`, with the admin, bearer, and (optional) organization plugins. Customize by subclassing `AuthService`; protect routes/sockets with `RequireAuthMiddleware`, `RequireAdminMiddleware`, and `AuthGuard`.
+
+```js
+const { Route, RequireAdminMiddleware } = require("zyket");
+
+module.exports = class extends Route {
+  middlewares = { get: [new RequireAdminMiddleware()] };
+  async get() { return { secret: "admins only" }; }
+};
+```
+
+Cookies are environment-aware: `sameSite=lax` in local dev (works over `http://localhost`), and `sameSite=none; secure` when `AUTH_CROSS_DOMAIN=true` for cross-domain HTTPS deployments. See [AGENTS.md §6](AGENTS.md#6-authentication-better-auth).
+
+## Services
+
+Default services activate from environment variables (see [AGENTS.md §3–4](AGENTS.md#3-environment-variables)). Register your own in the Kernel:
+
+```js
+const { Service } = require("zyket");
+
+module.exports = class MyService extends Service {
+  #container;
+  constructor(container) { super("my-service"); this.#container = container; }
+  async boot() { /* init */ }
+  doThing() { return "done"; }
+};
+```
+
+```js
+const kernel = new Kernel({
+  services: [["my-service", MyService, ["@service_container"]]],
+});
+```
+
+Default services and their activation:
+
+| Service | Env to enable |
+|---------|---------------|
+| `database` | `DATABASE_URL` (+ `DATABASE_DIALECT`, default `sqlite`) |
+| `cache` | always (`CACHE_URL=redis://…` for Redis, else in-memory) |
+| `s3` | `S3_ENDPOINT` + `S3_ACCESS_KEY` + `S3_SECRET_KEY` (MinIO) |
+| `socketio` | `DISABLE_SOCKET=false` |
+| `bullmq` | `DISABLE_BULLMQ=false` + `QUEUES=...` |
+| `scheduler` | `DISABLE_SCHEDULER=false` |
+| `events` | `DISABLE_EVENTS=false` |
+| `vite` | `VITE_ROOT` + `DISABLE_VITE=false` |
+| `auth` | manual registration (requires `sqlite`/`postgresql`) |
+
+## Security
+
+Zyket bakes in several defaults (random per-project `AUTH_SECRET`, fail-closed BullBoard, configurable payload limits, path-traversal guards on storage). Review **[SECURITY.md](SECURITY.md)** before going to production — notably rate limiting and `helmet` are not bundled.
+
+## Tooling for AI agents
+
+- **[AGENTS.md](AGENTS.md)** — full framework reference.
+- **Claude Code plugin** (`plugin/`) — skills to scaffold and use Zyket (`generate`, `build`).
+
+## Contributing
+
+Issues and pull requests are welcome — bug fixes, features, and documentation improvements. Let's build a better framework together. 🚀

package/bin/cli.js

@@ -118,21 +118,49 @@ function depsForTemplate(template) {
 	return deps;
 }
 
+// `node-dependency-injection` loads @typescript-eslint/typescript-estree@5 at
+// require time, which reads `ts.SyntaxKind` off whatever `typescript` npm
+// hoisted. TypeScript 7 dropped that CJS shape, so an unpinned tree dies on
+// boot with "Cannot read properties of undefined (reading 'BarBarToken')".
+// zyket depends on typescript ^5 for this reason; the override is what keeps an
+// already-resolved lockfile from pulling 7.x back in.
+const TYPESCRIPT_PIN = ZYKET_PKG.dependencies?.typescript || '^5.9.3';
+
+function projectName() {
+	const raw = path.basename(process.cwd()).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+/, '');
+	return raw || 'zyket-app';
+}
+
+// `npm install zyket` already leaves a package.json behind, so merging into an
+// existing file is the normal path, not the exception. Only fill in what's
+// missing — never clobber versions or scripts the user already chose.
 function ensurePackageJson(template) {
 	const packageJsonPath = path.join(process.cwd(), 'package.json');
-	if (fs.existsSync(packageJsonPath)) return;
-	const packageJson = {
-		name: path.basename(process.cwd()),
+	let packageJson = {};
+	if (fs.existsSync(packageJsonPath)) {
+		try {
+			packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) || {};
+		} catch {
+			console.log('[ZYKET] package.json is not valid JSON — leaving it untouched.');
+			return;
+		}
+	}
+	const defaults = {
+		name: projectName(),
 		version: '1.0.0',
 		description: 'Zyket application',
 		main: 'index.js',
-		scripts: { dev: 'node index.js' },
 		keywords: [],
 		author: '',
 		license: 'ISC',
-		dependencies: depsForTemplate(template),
 	};
-	fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+	for (const [key, value] of Object.entries(defaults)) {
+		if (packageJson[key] === undefined) packageJson[key] = value;
+	}
+	packageJson.scripts = { dev: 'node index.js', ...packageJson.scripts };
+	packageJson.dependencies = { ...depsForTemplate(template), ...packageJson.dependencies };
+	packageJson.overrides = { typescript: TYPESCRIPT_PIN, ...packageJson.overrides };
+	fs.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
 }
 
 function npmInstall() {
@@ -257,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.19",
+  "version": "1.2.21",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -13,46 +13,48 @@
   "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",
-    "umzug": "^3.8.2",
-    "vite": "^8.0.2",
-    "zustand": "^5.0.12"
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3",
+    "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"
+    "ajv": "^8.17.1",
+    "typescript": "^5.9.3"
   }
 }

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "zyket",
-  "description": "Claude Code plugin for the Zyket framework — scaffold handlers, guards, routes, middlewares, services, events, schedulers, workers, and extensions.",
-  "version": "1.0.0",
+  "description": "Claude Code plugin for the Zyket framework. `build`: start, configure, and run a Zyket app (templates, services, auth, security). `generate`: scaffold handlers, guards, routes, middlewares, services, events, schedulers, workers, and extensions.",
+  "version": "1.1.0",
   "author": {
     "name": "OnchainTech"
   }

package/plugin/skills/build/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: build
+description: Build, configure, and run applications with the Zyket framework — start a project from a template, enable services, wire authentication, secure the app, and add features. Use whenever the user wants to use Zyket, create or set up a Zyket project/app, or understand how Zyket works. For scaffolding a single component, use the `generate` skill instead.
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+# Build with Zyket
+
+Use this skill to take a user from zero to a running Zyket application, or to extend an existing one. Zyket is a service-oriented Node.js framework (Express 5 + Socket.IO + better-auth + Sequelize/BullMQ/MinIO) with filesystem auto-discovery and a DI container.
+
+## Golden rules
+
+1. **Read the reference.** After install, the full, authoritative API lives in `node_modules/zyket/AGENTS.md`. Read it before relying on any API; confirm base classes against `node_modules/zyket/` source. Do not invent APIs.
+2. **Filename = identity.** Routes, handlers, guards, events, schedulers, workers, and models are auto-discovered from `src/<folder>/`; the filename determines the URL/event/name. Use kebab-case and `module.exports = class extends Base`. Never add constructor params to these.
+3. **Services activate from `.env`.** A feature that needs sockets/queues/db must have the matching `DISABLE_*=false` / `DATABASE_URL` set.
+4. **Secure by default.** Protect non-public routes/sockets with `RequireAuthMiddleware` / `AuthGuard`. Never weaken cookie/auth settings to "make it work" — use `AUTH_CROSS_DOMAIN` instead.
+
+## Workflow
+
+### A. Starting a new project
+
+1. **Pick a template** by intent:
+
+   | User wants… | Template |
+   |-------------|----------|
+   | A clean REST API | `api-rest` |
+   | Multi-tenant SaaS (orgs, roles, dashboard) | `saas-multitenant` |
+   | Real-time / chat / live updates | `realtime-chat` |
+   | A general starter / unsure | `default` |
+
+2. **Scaffold:**
+   ```bash
+   npm install zyket
+   npx zyket init <template>
+   ```
+   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:
+   ```bash
+   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).
+
+### B. Enabling a capability in an existing project
+
+Flip the env flag, then add the component. Confirm details in `AGENTS.md §3–4`.
+
+| Capability | `.env` | Then add |
+|-----------|--------|----------|
+| HTTP routes | `DISABLE_EXPRESS=false` | `src/routes/**.js` |
+| Real-time | `DISABLE_SOCKET=false` | `src/handlers/*.js`, `src/guards/*.js` |
+| Database | `DATABASE_URL=...`, `DATABASE_DIALECT=...` | `src/models/*.js` |
+| Background jobs | `DISABLE_BULLMQ=false`, `QUEUES=emails` | `src/workers/*.js` |
+| Cron | `DISABLE_SCHEDULER=false` | `src/schedulers/*.js` |
+| Cache | `CACHE_URL=redis://…` (or in-memory) | use `container.get('cache')` |
+| Object storage | `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY` | use `container.get('s3')` |
+| Frontend | `DISABLE_VITE=false`, `VITE_ROOT=./frontend` | `frontend/` React app |
+
+### C. Adding authentication
+
+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`.
+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)
+
+1. Model → `src/models/Thing.js` (Sequelize factory). Create tables with `container.get('database').sync()` after boot, or migrations.
+2. Routes → `src/routes/things/index.js` (GET/POST) and `src/routes/things/[id].js` (GET/PUT/DELETE), gated by `RequireAuthMiddleware`.
+3. Read data via `container.get('database').models.Thing`.
+4. Optional realtime/jobs per the table in B.
+5. Run and verify.
+
+Delegate individual component scaffolding to the **`generate`** skill (e.g. `/zyket:generate route things/[id]`).
+
+## Common pitfalls
+
+- **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 (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.
+
+## Security pass before shipping
+
+Run through `SECURITY.md`. Minimum: every private route/socket guarded; `BULLBOARD_ADMIN_PASSWORD` set (or the dashboard won't mount); `SWAGGER_PASSWORD` or `DISABLE_SWAGGER=true`; `TRUSTED_ORIGINS` locked; add rate limiting + `helmet` (not bundled).

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